dx-devops-project-manage

DevOps Center 项目管理

管理 DevOps Center 项目的完整生命周期——从列出现有项目，到创建项目，再到更新项目设置。提供由无头 CLI 驱动的操作，支持自主发布工作流。

范围

• 范围内：列出 DevOps Center 项目、创建新项目、更新项目字段（名称、说明）、将项目名称解析为 ID，供下游技能使用
• 范围外：工作项生命周期、管道创建/配置、推广/部署、冲突检测（由单独的技能负责）

---

必需输入

继续操作前，请收集或推断以下信息：

• 操作类型：列出、创建或更新
• 目标组织：除非已设置 target-org 配置变量（sf config get target-org），否则每条命令都必须指定 --target-org <alias>
• 列出时：不需要其他必需输入（列出组织中的所有项目）；可选名称筛选条件
• 创建时：项目名称（必需）、说明（可选）
• 更新时：项目 ID（必需）、要更新的字段——名称、说明或活动状态至少指定一项

除非另有指定，否则使用以下默认值：

• 输出格式：使用 --json 以便无头方式读取
• 项目标识符：用户提供项目名称以进行更新时，先通过 sf devops project list --target-org <alias> --json 将其解析为项目 ID

如果用户提出明确请求（“列出所有项目”“创建名为 Release Alpha 的项目”“将项目 X 重命名为 Y”），请立即继续操作，无需提出不必要的问题。

---

工作流

所有操作均使用 sf devops project CLI 命令，并通过 --json 输出结构化内容。

阶段 1 — 确定操作

1. 根据用户意图确定操作类型：
   • 关键词如“列出”“显示”“查找”“有哪些项目”“获取项目 ID” → 列出操作
   • 关键词如“创建”“新建”“设置”“初始化” → 创建操作
   • 关键词如“更新”“更改”“重命名”“修改”“编辑” → 更新操作

阶段 2 — 执行操作

2. 在执行任何操作之前验证组织身份验证，并检查操作将针对的同一组织：

   # 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
   

   • 如果请求的组织尚未通过身份验证或身份验证已过期，请指示用户运行：

     sf org login web --alias <alias>
     

   • 尝试列出项目，以验证已通过身份验证的组织是否启用了 DevOps Center
   • 除非已设置 target-org 配置变量（使用 sf config get target-org 检查），否则每个 sf devops project 命令都必须指定 --target-org <alias>。针对特定组织时，所有命令都要添加 --target-org <alias> — 针对特定组织的操作绝不能要求更改或重置默认组织

   确定性的项目列表解析、空列表处理、名称→ID 解析、幂等创建和更新均由 scripts/ 中的脚本处理 — 每个脚本在失败时都会以非零状态码退出，并提供可执行的错误消息。如果未设置 target-org 配置变量，请将组织别名作为末尾参数或 --target-org 参数传入；省略该参数则使用默认组织。脚本会读取权威的 .result.projects[] 列表封装。

3. 列出项目 — 用户想查看现有项目或将项目名称解析为 ID 时：

   • 使用 sf devops project list CLI（通过 scripts/list-projects.sh）— 不要替换为 MCP/元数据工具（例如 list_devops_center_projects 工具）。sf devops project CLI 是唯一受支持且可验证的途径；其他工具会绕过此技能，无法满足操作要求。
   • 列出所有项目：运行 scripts/list-projects.sh [target-org]，并报告返回的任何错误。输出以制表符分隔，列为 Id Name Description，每行一个项目；如果输出只有一行 NO_PROJECTS，则表示没有项目。
   • 将单个项目名称解析为其 ID：运行 scripts/list-projects.sh --resolve "<project-name>" [target-org]，并报告返回的任何错误（退出码 3 = 无此项目）。

4. 创建项目 — 用户想创建新项目时：

   • 运行 scripts/create-project.sh "<name>" "<description>" [target-org]，并报告返回的任何错误。描述参数可选。
   • 此脚本具有幂等性：如果已存在同名项目，则输出 EXISTING <id>；如果创建并验证了新项目，则输出 CREATED <id>。请记录返回的 ID，供后续操作（工作项、管道）使用。

5. 更新项目 — 用户想更改名称、描述或活动状态时：

   • 运行 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>。

阶段 3 — 报告

6. 报告结果（脚本已确定性地验证成功；请将输出报告给用户）：
   • 列出：以易读的格式展示项目，并显示项目 ID、名称和描述。如果返回 NO_PROJECTS，请说明未找到 DevOps Center 项目。如果是将名称解析为 ID，则返回该 ID。
   • 创建：返回项目 ID 并确认 — “项目已成功创建。请将此项目 ID 用于工作项和管道：。”如果脚本返回 EXISTING <id>，请告知用户该项目已存在并返回该 ID。
   • 更新：确认已更改的字段（例如，“项目名称已更新为 ‘Platform Core’。”或“项目已停用。”）。

---

规则 / 约束

约束	原因
始终使用 sf devops project CLI	列出／创建／更新必须通过 sf devops project（借助 scripts/）完成，绝不能使用 salesforce_dx MCP 工具或元数据查询——它们会绕过此技能，导致操作失败
所有 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 解析
创建时必须指定 --name	创建项目时必须提供名称
更新时至少需要一个字段	如果未提供 --name、--description 或 --is-active 中的任何一个，更新命令就会失败
使用 --is-active / --no-is-active 激活或停用	使用 --is-active 激活，使用 --no-is-active 停用；不要传入值
创建操作必须保持幂等	创建前检查是否已存在同名项目
绝不使用交互式提示	技能运行于无头环境；所有输入都必须通过 CLI 标志提供
项目是工作项和流水线的前提条件	下游技能（work-item-manage、pipeline-manage）需要此技能返回的项目 ID

---

注意事项

问题	解决方案
未设置默认组织	首先运行 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），但使用它会绕过此技能和 sf devops project list CLI——始终通过 scripts/list-projects.sh 列表
未启用 DevOps Center	如果 sf devops project list 报错，说明该组织缺少 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 中的任何一个，更新就会失败；请确保至少传入一个字段
未设置默认组织，也未指定 --target-org	命令会因 NoOrgFound／缺少 target-org 而失败；请设置 --target-org <alias> 或运行 sf config set target-org <alias>
激活／停用时传入了值	--is-active 是布尔标志——使用 --is-active 或 --no-is-active，绝不要使用 --is-active true

---

输出预期

不同操作的交付内容有所不同：

• 列表：由 scripts/list-projects.sh 输出制表符分隔的 Id Name Description 行（或 NO_PROJECTS）
• 创建：由 scripts/create-project.sh 输出 EXISTING <id> 或 CREATED <id>
• 更新：由 scripts/update-project.sh 输出 UPDATED <id>

输出取自 scripts/ 辅助脚本调用的 sf devops project CLI；这些脚本会读取权威的 .result.projects[] 列表响应封装。

---

验证清单

向用户报告结果前：

通用检查

• 是否已使用 sf org display --json 验证组织身份验证？
• 是否已向脚本传入 --target-org <alias>（或确认已设置 target-org 配置变量）？
• 调用的脚本是否以 0 退出？（非零退出表示操作失败——请报告脚本的错误消息。）

列表操作检查

• 显示的项目是否包含项目 ID、名称和描述？
• 如果脚本返回 NO_PROJECTS，是否已将此情况告知用户？
• 如果将名称解析为 ID，是否已返回该 ID（或在退出码为 3 时显示“未找到”）？

创建操作检查

• 脚本是否返回 CREATED <id> 或 EXISTING <id>，并且是否已报告该 ID？

更新操作检查

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

---

跨技能集成

何时	委派给
用户想要在项目中创建、列出或更新工作项	dx-devops-work-item-manage（传入此技能提供的项目 ID）
用户想要为项目创建或配置管道	dx-devops-pipeline-manage
用户想要推广或部署更改	dx-devops-promote

此技能通常会在 DevOps Center 工作流中首先运行——它返回的项目 ID 是工作项和管道技能的入口。

---

参考文件索引

文件	何时读取 / 运行
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	用户的请求符合常见模式（名称解析、幂等创建、将项目设置为工作流入口点）时