dx-devops-project-manage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DevOps Center Project Management

DevOps Center项目管理

Manages the complete DevOps Center project lifecycle — from listing existing projects through creation to updating project settings. Provides headless CLI-driven operations for autonomous release workflows.
管理DevOps Center项目的完整生命周期——从列出现有项目到创建项目,再到更新项目设置。为自动化发布工作流提供无界面CLI驱动的操作。

Scope

适用范围

  • In scope: List DevOps Center projects, create a new project, update project fields (name, description), resolve a project name to its ID for downstream skills
  • Out of scope: Work item lifecycle, pipeline creation/configuration, promotion/deployment, conflict detection (separate skills)

  • 包含范围:列出DevOps Center项目、创建新项目、更新项目字段(名称、描述)、将项目名称解析为ID以供下游Skill使用
  • 排除范围:工作项生命周期、管道创建/配置、晋升/部署、冲突检测(对应单独的Skill)

Required Inputs

必填输入

Gather or infer before proceeding:
  • Operation type: list, create, or update
  • Target org:
    --target-org <alias>
    is required on every command unless the
    target-org
    config var is already set (
    sf config get target-org
    )
  • For list: no other required input (lists all projects in the org); optional name filter
  • For create: project name (required), description (optional)
  • For update: project ID (required), fields to update — at least one of name, description, or active status
Defaults unless specified:
  • Output format:
    --json
    for headless consumption
  • Project identifier: when the user gives a project name for update, resolve it to a project ID first via
    sf devops project list --target-org <alias> --json
If the user provides a clear request ("list all projects", "create a project called Release Alpha", "rename project X to Y"), proceed immediately without unnecessary questions.

执行前需收集或推断以下信息:
  • 操作类型:list(列出)、create(创建)或update(更新)
  • 目标org:除非已设置
    target-org
    配置变量(可通过
    sf config get target-org
    查看),否则每个命令都必须指定
    --target-org <alias>
  • 针对list操作:无需其他必填输入(列出org中的所有项目);可选名称筛选条件
  • 针对create操作:项目名称(必填)、描述(可选)
  • 针对update操作:项目ID(必填)、需更新的字段——至少包含名称、描述或激活状态中的一项
默认设置(除非另行指定):
  • 输出格式:
    --json
    (用于无界面场景)
  • 项目标识符:当用户提供项目名称进行更新时,先通过
    sf devops project list --target-org <alias> --json
    将其解析为项目ID
如果用户提供明确请求(如“列出所有项目”、“创建名为Release Alpha的项目”、“将项目X重命名为Y”),请直接执行,无需额外询问。

Workflow

工作流

All operations use
sf devops project
CLI commands with
--json
output for structured consumption.
所有操作均使用
sf devops project
CLI命令,并以
--json
格式输出以支持结构化处理。

Phase 1 — Identify Operation

阶段1 — 确定操作类型

  1. Determine the operation type from user intent:
    • Keywords like "list", "show", "find", "what projects", "get project ID" → list operation
    • Keywords like "create", "new", "set up", "initialize" → create operation
    • Keywords like "update", "change", "rename", "modify", "edit" → update operation
  1. 根据用户意图确定操作类型:
    • 关键词如“list”、“show”、“find”、“有哪些项目”、“获取项目ID” → list操作
    • 关键词如“create”、“new”、“set up”、“initialize” → create操作
    • 关键词如“update”、“change”、“rename”、“modify”、“edit” → update操作

Phase 2 — Execute Operation

阶段2 — 执行操作

  1. Verify org authentication before any operation, checking the same org the operation will target:
    bash
    # When a specific org is requested, check that alias (do NOT rely on the default org):
    sf org display --target-org <alias> --json
    # Only when no alias is supplied and a default org is expected:
    sf org display --json
    • If the requested org is not authenticated or authentication has expired, instruct the user to run:
      bash
      sf org login web --alias <alias>
    • Verify the authenticated org has DevOps Center enabled by attempting to list projects
    • --target-org <alias>
      is required on every
      sf devops project
      command unless the
      target-org
      config var is set (check with
      sf config get target-org
      ). Add
      --target-org <alias>
      to all commands when targeting a specific org — a targeted operation must never require or reset the default org
    Deterministic project-list parsing, empty-list handling, name→ID resolution, idempotent create, and update are handled by the scripts in
    scripts/
    — each script exits non-zero with an actionable message on failure. Pass the org alias as the trailing/
    --target-org
    argument when the
    target-org
    config var is not set; omit it to use the default org. The scripts read the authoritative
    .result.projects[]
    list envelope.
  2. List projects — when the user wants to see existing projects or resolve a project name to an ID:
    • Use the
      sf devops project list
      CLI (via
      scripts/list-projects.sh
      ) — do NOT substitute an MCP/metadata tool
      (e.g. a
      list_devops_center_projects
      tool). The
      sf devops project
      CLI is the only supported, verifiable path; other tools bypass this skill and will not satisfy the operation.
    • To list all projects: run
      scripts/list-projects.sh [target-org]
      and report any errors it returns. Output is tab-separated
      Id  Name  Description
      , one project per line; a single line
      NO_PROJECTS
      means none exist.
    • To resolve a single project name to its ID: run
      scripts/list-projects.sh --resolve "<project-name>" [target-org]
      and report any errors it returns (exit 3 = no such project).
  3. Create a project — when the user wants to create a new project:
    • Run
      scripts/create-project.sh "<name>" "<description>" [target-org]
      and report any errors it returns. The description argument is optional.
    • The script is idempotent: it prints
      EXISTING <id>
      if a project with that name already exists, or
      CREATED <id>
      after creating and verifying a new one. Capture the returned ID for downstream operations (work items, pipelines).
  4. Update a project — when the user wants to change name, description, or active status:
    • Run
      scripts/update-project.sh --project (<id>|name:<name>) [--name "<new-name>"] [--description "<new-desc>"] [--is-active|--no-is-active] [--target-org <alias>]
      and report any errors it returns.
    • Pass
      --project name:<name>
      to update by name (the script resolves it to an ID) or
      --project <id>
      for a known ID.
    • At least one of
      --name
      ,
      --description
      , or
      --is-active
      /
      --no-is-active
      must be provided (the script enforces this). Use
      --is-active
      to activate or
      --no-is-active
      to deactivate.
    • The script prints
      UPDATED <id>
      on success.
  1. 在执行任何操作前验证org身份验证,检查操作目标的org:
    bash
    # 当指定特定org时,检查该别名(请勿依赖默认org):
    sf org display --target-org <alias> --json
    # 仅当未提供别名且预期使用默认org时:
    sf org display --json
    • 如果请求的org未通过身份验证或身份验证已过期,指导用户运行:
      bash
      sf org login web --alias <alias>
    • 通过尝试列出项目,验证已通过身份验证的org是否启用了DevOps Center
    • 除非已设置
      target-org
      配置变量(通过
      sf config get target-org
      检查),否则每个
      sf devops project
      命令都必须添加
      --target-org <alias>
      。针对特定org的操作必须始终添加
      --target-org <alias>
      ——定向操作绝不能依赖或重置默认org
    确定性项目列表解析、空列表处理、名称→ID解析、幂等创建和更新均由
    scripts/
    目录下的脚本处理——每个脚本执行失败时会返回非零退出码及可执行的提示信息。当未设置
    target-org
    配置变量时,将org别名作为尾部参数或
    --target-org
    参数传入;省略该参数则使用默认org。脚本会读取权威的
    .result.projects[]
    列表包。
  2. 列出项目 — 当用户想要查看现有项目或将项目名称解析为ID时:
    • 使用
      sf devops project list
      CLI(通过
      scripts/list-projects.sh
      )——请勿替代为MCP/元数据工具
      (如
      list_devops_center_projects
      工具)。
      sf devops project
      CLI是唯一受支持、可验证的路径;使用其他工具会绕过该Skill,无法完成操作。
    • 列出所有项目:运行
      scripts/list-projects.sh [target-org]
      并报告返回的任何错误。输出为制表符分隔的
      Id  Name  Description
      ,每行一个项目;若返回单行
      NO_PROJECTS
      则表示无项目存在。
    • 将单个项目名称解析为ID:运行
      scripts/list-projects.sh --resolve "<project-name>" [target-org]
      并报告返回的任何错误(退出码3表示无匹配项目)。
  3. 创建项目 — 当用户想要创建新项目时:
    • 运行
      scripts/create-project.sh "<name>" "<description>" [target-org]
      并报告返回的任何错误。描述参数为可选。
    • 脚本具备幂等性:若已存在同名项目,则输出
      EXISTING <id>
      ;若创建并验证新项目成功,则输出
      CREATED <id>
      。捕获返回的ID以供下游操作(工作项、管道)使用。
  4. 更新项目 — 当用户想要修改名称、描述或激活状态时:
    • 运行
      scripts/update-project.sh --project (<id>|name:<name>) [--name "<new-name>"] [--description "<new-desc>"] [--is-active|--no-is-active] [--target-org <alias>]
      并报告返回的任何错误。
    • 若按名称更新,传入
      --project name:<name>
      (脚本会将其解析为ID);若已知ID,传入
      --project <id>
      。
    • 必须至少提供
      --name
      、
      --description
      或
      --is-active
      /
      --no-is-active
      中的一项(脚本会强制执行此要求)。使用
      --is-active
      激活项目,
      --no-is-active
      停用项目。
    • 脚本成功执行时会输出
      UPDATED <id>
      。

Phase 3 — Report

阶段3 — 报告结果

  1. Report results (the scripts already verified success deterministically; report their output to the user):
    • List: present projects in a readable format showing project ID, name, and description. If
      NO_PROJECTS
      was returned, state that no DevOps Center projects were found. If resolving a name to an ID, return the ID.
    • Create: return the project ID and confirm — "Project created successfully. Use this project ID for work items and pipelines: <id>." If the script returned
      EXISTING <id>
      , tell the user the project already existed and return that ID.
    • Update: confirm which fields were changed (e.g., "Project name updated to 'Platform Core'", or "Project deactivated").

  1. 报告结果(脚本已确定性验证操作成功;将脚本输出告知用户):
    • List操作:以易读格式展示项目ID、名称和描述。若返回
      NO_PROJECTS
      ,告知用户未找到DevOps Center项目。若为名称解析为ID的请求,返回对应的ID。
    • Create操作:返回项目ID并确认——“项目创建成功。请使用该项目ID进行工作项和管道操作:<id>。”若脚本返回
      EXISTING <id>
      ,告知用户该项目已存在并返回对应的ID。
    • Update操作:确认修改的字段(如“项目名称已更新为'Platform Core'”或“项目已停用”)。

Rules / Constraints

规则/约束

ConstraintRationale
Always use the
sf devops project
CLI
List/create/update MUST go through
sf devops project
(via the
scripts/
), never a
salesforce_dx
MCP tool or metadata query — those bypass this skill and fail the operation
All sf devops commands must use
--json
flag
Structured output is required for headless consumption; human-readable output is unreliable for parsing
--target-org
required unless config var set
Every
sf devops project
command requires
--target-org <alias>
unless the
target-org
config var is already set
Project ID required for updateUse
--project-id
(
-i
); resolve from a name via
sf devops project list --target-org <alias> --json
when the user gives a name
--name
required for create
A project cannot be created without a name
At least one update field requiredUpdate command fails if none of
--name
,
--description
, or
--is-active
is provided
Use
--is-active
/
--no-is-active
for activation
Activate with
--is-active
, deactivate with
--no-is-active
; do not pass a value
Idempotent create operationsCheck for an existing project with the same name before creating a duplicate
Never use interactive promptsSkills run in headless environments; all inputs must be via CLI flags
A project is a prerequisite for work items and pipelinesDownstream skills (work-item-manage, pipeline-manage) need the project ID this skill returns

约束条件理由
始终使用
sf devops project
CLI
列出/创建/更新操作必须通过
sf devops project
(通过
scripts/
脚本)完成,绝不能使用
salesforce_dx
MCP工具或元数据查询——这些方式会绕过该Skill,导致操作失败
所有sf devops命令必须使用
--json
标志
结构化输出是无界面场景的必需条件;人类可读的输出解析不可靠
除非已设置配置变量,否则必须指定
--target-org
每个
sf devops project
命令都需要
--target-org <alias>
,除非已设置
target-org
配置变量
更新操作必须提供项目ID使用
--project-id
(
-i
);当用户提供名称时,通过
sf devops project list --target-org <alias> --json
将其解析为ID
创建操作必须提供
--name
无名称无法创建项目
必须至少提供一个更新字段若未提供
--name
、
--description
或
--is-active
中的任何一项,更新命令会执行失败
使用
--is-active
/
--no-is-active
控制激活状态
使用
--is-active
激活,
--no-is-active
停用;请勿传入值
创建操作具备幂等性创建重复项目前,检查是否已存在同名项目
绝不使用交互式提示Skill运行在无界面环境中;所有输入必须通过CLI标志传入
项目是工作项和管道的前提条件下游Skill(work-item-manage、pipeline-manage)需要该Skill返回的项目ID

Gotchas

注意事项

IssueResolution
No default org setRun
sf org display --json
first; if it fails, instruct the user to run
sf org login web --set-default
User provides project by name, not ID (update)Resolve via
scripts/list-projects.sh --resolve "<name>" [target-org]
, or pass
--project name:<name>
to
scripts/update-project.sh
(it resolves internally)
Tempted to use an MCP listing toolA
salesforce_dx
MCP tool (e.g.
list_devops_center_projects
) may be available, but using it bypasses this skill and the
sf devops project list
CLI — always list via
scripts/list-projects.sh
DevOps Center not enabledIf
sf devops project list
errors, the org lacks DevOps Center; instruct the user to provision it in Setup → DevOps Center
Project not found (update)User provided an invalid project ID; run
scripts/list-projects.sh [target-org]
to show available projects
Wrong list envelope
project list
returns records under
.result.projects[]
(capitalized
Id
/
Name
/
Description
), NOT
.result[]
; the scripts already use the correct path
Duplicate project nameIdempotent create check should catch this; return the existing project ID instead of creating a duplicate
Empty project listNo projects exist yet; guide the user to create one before setting up work items or pipelines
Missing update fieldUpdate fails if none of
--name
,
--description
, or
--is-active
is provided; ensure at least one is passed
No default org and no
--target-org
Commands fail with a NoOrgFound / missing target-org error; set
--target-org <alias>
or
sf config set target-org <alias>
Activate/deactivate passes a value
--is-active
is a boolean flag — use
--is-active
or
--no-is-active
, never
--is-active true

问题解决方案
未设置默认org先运行
sf org display --json
;若执行失败,指导用户运行
sf org login web --set-default
用户提供项目名称而非ID(更新操作)通过
scripts/list-projects.sh --resolve "<name>" [target-org]
解析,或向
scripts/update-project.sh
传入
--project name:<name>
(脚本会内部解析)
想要使用MCP列表工具可能存在
salesforce_dx
MCP工具(如
list_devops_center_projects
),但使用它会绕过该Skill和
sf devops project list
CLI——始终通过
scripts/list-projects.sh
列出项目
未启用DevOps Center若
sf devops project list
执行出错,说明该org未启用DevOps Center;指导用户在Setup → DevOps Center中启用
项目未找到(更新操作)用户提供了无效的项目ID;运行
scripts/list-projects.sh [target-org]
显示可用项目
错误的列表包
project list
返回的记录位于
.result.projects[]
(
Id
/
Name
/
Description
首字母大写),而非
.result[]
;脚本已使用正确路径
项目名称重复幂等性创建检查应捕获此问题;返回现有项目ID而非创建重复项目
项目列表为空当前无项目存在;指导用户先创建项目,再设置工作项或管道
缺少更新字段若未提供
--name
、
--description
或
--is-active
中的任何一项,更新操作会失败;确保至少传入一项
未设置默认org且未指定
--target-org
命令会因NoOrgFound/缺少target-org错误而失败;设置
--target-org <alias>
或
sf config set target-org <alias>
激活/停用操作传入了值
--is-active
是布尔标志——使用
--is-active
或
--no-is-active
,绝不要使用
--is-active true

Output Expectations

输出预期

Deliverables vary by operation:
  • List: tab-separated
    Id  Name  Description
    lines (or
    NO_PROJECTS
    ) from
    scripts/list-projects.sh
  • Create:
    EXISTING <id>
    or
    CREATED <id>
    from
    scripts/create-project.sh
  • Update:
    UPDATED <id>
    from
    scripts/update-project.sh
Outputs are derived from the
sf devops project
CLI via the
scripts/
helpers, which read the authoritative
.result.projects[]
list envelope.

不同操作的交付成果如下:
  • List操作:来自
    scripts/list-projects.sh
    的制表符分隔
    Id  Name  Description
    行(或
    NO_PROJECTS
    )
  • Create操作:来自
    scripts/create-project.sh
    的
    EXISTING <id>
    或
    CREATED <id>
  • Update操作:来自
    scripts/update-project.sh
    的
    UPDATED <id>
输出通过
scripts/
辅助脚本从
sf devops project
CLI获取,脚本会读取权威的
.result.projects[]
列表包。

Verification Checklist

验证清单

Before reporting results to the user:
向用户报告结果前,请完成以下检查:

Universal Checks

通用检查

  • Was org authentication verified with
    sf org display --json
    ?
  • Was
    --target-org <alias>
    supplied to the script (or the
    target-org
    config var confirmed set)?
  • Did the invoked script exit 0? (Non-zero exit means the operation failed — report the script's error message.)
  • 是否已通过
    sf org display --json
    验证org身份验证?
  • 是否已向脚本传入
    --target-org <alias>
    (或确认已设置
    target-org
    配置变量)?
  • 调用的脚本是否返回退出码0?(非零退出码表示操作失败——报告脚本的错误信息。)

List Operation Checks

List操作检查

  • Are projects displayed with project ID, name, and description?
  • If the script returned
    NO_PROJECTS
    , was this communicated to the user?
  • If resolving a name to an ID, was the ID returned (or "not found" surfaced on exit 3)?
  • 是否已展示包含项目ID、名称和描述的项目信息?
  • 若脚本返回
    NO_PROJECTS
    ,是否已告知用户?
  • 若为名称解析为ID的请求,是否已返回ID(或在退出码3时提示“未找到”)?

Create Operation Checks

Create操作检查

  • Did the script return
    CREATED <id>
    or
    EXISTING <id>
    , and was the ID reported?
  • 脚本是否返回
    CREATED <id>
    或
    EXISTING <id>
    ,且是否已报告该ID?

Update Operation Checks

Update操作检查

  • Was the project identified by
    --project <id>
    or
    --project name:<name>
    ?
  • Was at least one update field provided (name, description, or
    --is-active
    /
    --no-is-active
    )?
  • Did the script return
    UPDATED <id>
    ?

  • 是否已通过
    --project <id>
    或
    --project name:<name>
    指定项目?
  • 是否已至少提供一个更新字段(名称、描述或
    --is-active
    /
    --no-is-active
    )?
  • 脚本是否返回
    UPDATED <id>
    ?

Cross-Skill Integration

跨Skill集成

WhenDelegate to
User wants to create, list, or update work items in a project
dx-devops-work-item-manage
(pass the project ID from this skill)
User wants to create or configure a pipeline for a project
dx-devops-pipeline-manage
User wants to promote or deploy changes
dx-devops-promote
This skill typically runs first in a DevOps Center workflow — the project ID it returns is the entry point for work item and pipeline skills.

场景委托至
用户想要在项目中创建、列出或更新工作项
dx-devops-work-item-manage
(传入该Skill返回的项目ID)
用户想要为项目创建或配置管道
dx-devops-pipeline-manage
用户想要晋升或部署变更
dx-devops-promote
该Skill通常是DevOps Center工作流中的首个执行Skill——它返回的项目ID是工作项和管道Skill的入口点。

Reference File Index

参考文件索引

FileWhen to read / run
scripts/list-projects.sh
Workflow step 3 — list all projects or resolve a project name to an ID (
--resolve
); handles the empty-list case
scripts/create-project.sh
Workflow step 4 — idempotently create a project and verify it via re-read
scripts/update-project.sh
Workflow step 5 — update name/description/active status by ID or name
references/cli-commands.md
When you need detailed CLI flag documentation, JSON output schemas, or error handling patterns
examples/common-workflows.md
When the user's request matches a common pattern (name resolution, idempotent creation, project setup as a workflow entry point)
文件读取/运行场景
scripts/list-projects.sh
工作流步骤3——列出所有项目或将项目名称解析为ID(使用
--resolve
参数);处理空列表场景
scripts/create-project.sh
工作流步骤4——幂等性创建项目并通过重新读取验证
scripts/update-project.sh
工作流步骤5——通过ID或名称更新名称/描述/激活状态
references/cli-commands.md
需要详细CLI标志文档、JSON输出模式或错误处理模式时
examples/common-workflows.md
用户请求匹配常见模式(名称解析、幂等性创建、项目设置作为工作流入口点)时