dx-devops-project-manage
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDevOps 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: is required on every command unless the
--target-org <alias>config var is already set (target-org)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: for headless consumption
--json - 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 - 项目标识符:当用户提供项目名称进行更新时,先通过将其解析为项目ID
sf devops project list --target-org <alias> --json
如果用户提供明确请求(如“列出所有项目”、“创建名为Release Alpha的项目”、“将项目X重命名为Y”),请直接执行,无需额外询问。
Workflow
工作流
All operations use CLI commands with output for structured consumption.
sf devops project--json所有操作均使用 CLI命令,并以格式输出以支持结构化处理。
sf devops project--jsonPhase 1 — Identify Operation
阶段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
- 根据用户意图确定操作类型:
- 关键词如“list”、“show”、“find”、“有哪些项目”、“获取项目ID” → list操作
- 关键词如“create”、“new”、“set up”、“initialize” → create操作
- 关键词如“update”、“change”、“rename”、“modify”、“edit” → update操作
Phase 2 — Execute Operation
阶段2 — 执行操作
-
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
- is required on every
--target-org <alias>command unless thesf devops projectconfig var is set (check withtarget-org). Addsf config get target-orgto all commands when targeting a specific org — a targeted operation must never require or reset the default org--target-org <alias>
Deterministic project-list parsing, empty-list handling, name→ID resolution, idempotent create, and update are handled by the scripts in— each script exits non-zero with an actionable message on failure. Pass the org alias as the trailing/scripts/argument when the--target-orgconfig var is not set; omit it to use the default org. The scripts read the authoritativetarget-orglist envelope..result.projects[] - If the requested org is not authenticated or authentication has expired, instruct the user to run:
-
List projects — when the user wants to see existing projects or resolve a project name to an ID:
- Use the CLI (via
sf devops project list) — do NOT substitute an MCP/metadata tool (e.g. ascripts/list-projects.shtool). Thelist_devops_center_projectsCLI is the only supported, verifiable path; other tools bypass this skill and will not satisfy the operation.sf devops project - To list all projects: run and report any errors it returns. Output is tab-separated
scripts/list-projects.sh [target-org], one project per line; a single lineId Name Descriptionmeans none exist.NO_PROJECTS - To resolve a single project name to its ID: run and report any errors it returns (exit 3 = no such project).
scripts/list-projects.sh --resolve "<project-name>" [target-org]
- Use the
-
Create a project — when the user wants to create a new project:
- Run and report any errors it returns. The description argument is optional.
scripts/create-project.sh "<name>" "<description>" [target-org] - The script is idempotent: it prints if a project with that name already exists, or
EXISTING <id>after creating and verifying a new one. Capture the returned ID for downstream operations (work items, pipelines).CREATED <id>
- Run
-
Update a project — when the user wants to change name, description, or active status:
- Run and report any errors it returns.
scripts/update-project.sh --project (<id>|name:<name>) [--name "<new-name>"] [--description "<new-desc>"] [--is-active|--no-is-active] [--target-org <alias>] - Pass to update by name (the script resolves it to an ID) or
--project name:<name>for a known ID.--project <id> - At least one of ,
--name, or--description/--is-activemust be provided (the script enforces this). Use--no-is-activeto activate or--is-activeto deactivate.--no-is-active - The script prints on success.
UPDATED <id>
- Run
-
在执行任何操作前验证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。针对特定org的操作必须始终添加--target-org <alias>——定向操作绝不能依赖或重置默认org--target-org <alias>
确定性项目列表解析、空列表处理、名称→ID解析、幂等创建和更新均由目录下的脚本处理——每个脚本执行失败时会返回非零退出码及可执行的提示信息。当未设置scripts/配置变量时,将org别名作为尾部参数或target-org参数传入;省略该参数则使用默认org。脚本会读取权威的--target-org列表包。.result.projects[] - 如果请求的org未通过身份验证或身份验证已过期,指导用户运行:
-
列出项目 — 当用户想要查看现有项目或将项目名称解析为ID时:
- 使用CLI(通过
sf devops project list)——请勿替代为MCP/元数据工具(如scripts/list-projects.sh工具)。list_devops_center_projectsCLI是唯一受支持、可验证的路径;使用其他工具会绕过该Skill,无法完成操作。sf devops project - 列出所有项目:运行并报告返回的任何错误。输出为制表符分隔的
scripts/list-projects.sh [target-org],每行一个项目;若返回单行Id Name Description则表示无项目存在。NO_PROJECTS - 将单个项目名称解析为ID:运行并报告返回的任何错误(退出码3表示无匹配项目)。
scripts/list-projects.sh --resolve "<project-name>" [target-org]
- 使用
-
创建项目 — 当用户想要创建新项目时:
- 运行并报告返回的任何错误。描述参数为可选。
scripts/create-project.sh "<name>" "<description>" [target-org] - 脚本具备幂等性:若已存在同名项目,则输出;若创建并验证新项目成功,则输出
EXISTING <id>。捕获返回的ID以供下游操作(工作项、管道)使用。CREATED <id>
- 运行
-
更新项目 — 当用户想要修改名称、描述或激活状态时:
- 运行并报告返回的任何错误。
scripts/update-project.sh --project (<id>|name:<name>) [--name "<new-name>"] [--description "<new-desc>"] [--is-active|--no-is-active] [--target-org <alias>] - 若按名称更新,传入(脚本会将其解析为ID);若已知ID,传入
--project name:<name>。--project <id> - 必须至少提供、
--name或--description/--is-active中的一项(脚本会强制执行此要求)。使用--no-is-active激活项目,--is-active停用项目。--no-is-active - 脚本成功执行时会输出。
UPDATED <id>
- 运行
Phase 3 — Report
阶段3 — 报告结果
- 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 was returned, state that no DevOps Center projects were found. If resolving a name to an ID, return the ID.
NO_PROJECTS - Create: return the project ID and confirm — "Project created successfully. Use this project ID for work items and pipelines: <id>." If the script returned , tell the user the project already existed and return that ID.
EXISTING <id> - Update: confirm which fields were changed (e.g., "Project name updated to 'Platform Core'", or "Project deactivated").
- List: present projects in a readable format showing project ID, name, and description. If
- 报告结果(脚本已确定性验证操作成功;将脚本输出告知用户):
- List操作:以易读格式展示项目ID、名称和描述。若返回,告知用户未找到DevOps Center项目。若为名称解析为ID的请求,返回对应的ID。
NO_PROJECTS - Create操作:返回项目ID并确认——“项目创建成功。请使用该项目ID进行工作项和管道操作:<id>。”若脚本返回,告知用户该项目已存在并返回对应的ID。
EXISTING <id> - Update操作:确认修改的字段(如“项目名称已更新为'Platform Core'”或“项目已停用”)。
- List操作:以易读格式展示项目ID、名称和描述。若返回
Rules / Constraints
规则/约束
| Constraint | Rationale |
|---|---|
Always use the | List/create/update MUST go through |
All sf devops commands must use | Structured output is required for headless consumption; human-readable output is unreliable for parsing |
| Every |
| Project ID required for update | Use |
| A project cannot be created without a name |
| At least one update field required | Update command fails if none of |
Use | Activate with |
| Idempotent create operations | Check for an existing project with the same name before creating a duplicate |
| Never use interactive prompts | Skills run in headless environments; all inputs must be via CLI flags |
| A project is a prerequisite for work items and pipelines | Downstream skills (work-item-manage, pipeline-manage) need the project ID this skill returns |
| 约束条件 | 理由 |
|---|---|
始终使用 | 列出/创建/更新操作必须通过 |
所有sf devops命令必须使用 | 结构化输出是无界面场景的必需条件;人类可读的输出解析不可靠 |
除非已设置配置变量,否则必须指定 | 每个 |
| 更新操作必须提供项目ID | 使用 |
创建操作必须提供 | 无名称无法创建项目 |
| 必须至少提供一个更新字段 | 若未提供 |
使用 | 使用 |
| 创建操作具备幂等性 | 创建重复项目前,检查是否已存在同名项目 |
| 绝不使用交互式提示 | Skill运行在无界面环境中;所有输入必须通过CLI标志传入 |
| 项目是工作项和管道的前提条件 | 下游Skill(work-item-manage、pipeline-manage)需要该Skill返回的项目ID |
Gotchas
注意事项
| Issue | Resolution |
|---|---|
| No default org set | Run |
| User provides project by name, not ID (update) | Resolve via |
| Tempted to use an MCP listing tool | A |
| DevOps Center not enabled | If |
| Project not found (update) | User provided an invalid project ID; run |
| Wrong list envelope | |
| Duplicate project name | Idempotent create check should catch this; return the existing project ID instead of creating a duplicate |
| Empty project list | No projects exist yet; guide the user to create one before setting up work items or pipelines |
| Missing update field | Update fails if none of |
No default org and no | Commands fail with a NoOrgFound / missing target-org error; set |
| Activate/deactivate passes a value | |
| 问题 | 解决方案 |
|---|---|
| 未设置默认org | 先运行 |
| 用户提供项目名称而非ID(更新操作) | 通过 |
| 想要使用MCP列表工具 | 可能存在 |
| 未启用DevOps Center | 若 |
| 项目未找到(更新操作) | 用户提供了无效的项目ID;运行 |
| 错误的列表包 | |
| 项目名称重复 | 幂等性创建检查应捕获此问题;返回现有项目ID而非创建重复项目 |
| 项目列表为空 | 当前无项目存在;指导用户先创建项目,再设置工作项或管道 |
| 缺少更新字段 | 若未提供 |
未设置默认org且未指定 | 命令会因NoOrgFound/缺少target-org错误而失败;设置 |
| 激活/停用操作传入了值 | |
Output Expectations
输出预期
Deliverables vary by operation:
- List: tab-separated lines (or
Id Name Description) fromNO_PROJECTSscripts/list-projects.sh - Create: or
EXISTING <id>fromCREATED <id>scripts/create-project.sh - Update: from
UPDATED <id>scripts/update-project.sh
Outputs are derived from the CLI via the helpers, which read the authoritative list envelope.
sf devops projectscripts/.result.projects[]不同操作的交付成果如下:
- List操作:来自的制表符分隔
scripts/list-projects.sh行(或Id Name Description)NO_PROJECTS - Create操作:来自的
scripts/create-project.sh或EXISTING <id>CREATED <id> - Update操作:来自的
scripts/update-project.shUPDATED <id>
输出通过辅助脚本从 CLI获取,脚本会读取权威的列表包。
scripts/sf devops project.result.projects[]Verification Checklist
验证清单
Before reporting results to the user:
向用户报告结果前,请完成以下检查:
Universal Checks
通用检查
- Was org authentication verified with ?
sf org display --json - Was supplied to the script (or the
--target-org <alias>config var confirmed set)?target-org - Did the invoked script exit 0? (Non-zero exit means the operation failed — report the script's error message.)
- 是否已通过验证org身份验证?
sf org display --json - 是否已向脚本传入(或确认已设置
--target-org <alias>配置变量)?target-org - 调用的脚本是否返回退出码0?(非零退出码表示操作失败——报告脚本的错误信息。)
List Operation Checks
List操作检查
- Are projects displayed with project ID, name, and description?
- If the script returned , was this communicated to the user?
NO_PROJECTS - 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 or
CREATED <id>, and was the ID reported?EXISTING <id>
- 脚本是否返回或
CREATED <id>,且是否已报告该ID?EXISTING <id>
Update Operation Checks
Update操作检查
- Was the project identified by or
--project <id>?--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集成
| When | Delegate to |
|---|---|
| User wants to create, list, or update work items in a project | |
| User wants to create or configure a pipeline for a project | |
| User wants to promote or deploy changes | |
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.
| 场景 | 委托至 |
|---|---|
| 用户想要在项目中创建、列出或更新工作项 | |
| 用户想要为项目创建或配置管道 | |
| 用户想要晋升或部署变更 | |
该Skill通常是DevOps Center工作流中的首个执行Skill——它返回的项目ID是工作项和管道Skill的入口点。
Reference File Index
参考文件索引
| File | When to read / run |
|---|---|
| Workflow step 3 — list all projects or resolve a project name to an ID ( |
| Workflow step 4 — idempotently create a project and verify it via re-read |
| Workflow step 5 — update name/description/active status by ID or name |
| When you need detailed CLI flag documentation, JSON output schemas, or error handling patterns |
| When the user's request matches a common pattern (name resolution, idempotent creation, project setup as a workflow entry point) |
| 文件 | 读取/运行场景 |
|---|---|
| 工作流步骤3——列出所有项目或将项目名称解析为ID(使用 |
| 工作流步骤4——幂等性创建项目并通过重新读取验证 |
| 工作流步骤5——通过ID或名称更新名称/描述/激活状态 |
| 需要详细CLI标志文档、JSON输出模式或错误处理模式时 |
| 用户请求匹配常见模式(名称解析、幂等性创建、项目设置作为工作流入口点)时 |