场景	前置 skill	本 skill 时机
新增命令	`create-cli-command` Phase 1-4 完成后	替代其 Phase 5
修改命令	直接修改代码后	代码修改完成即可
发版前	`feature-development-workflow` Phase 4 完成后	在 Phase 5 推送之前
仅补翻译	无前置	任意时间

🚀 执行步骤

Phase 0: 变更分析

目的：识别本次变更影响了哪些命令组、哪些文档需要更新，避免遗漏或无谓修改。

检查当前变更范围

# 最近一次提交的变更文件
git diff --name-only HEAD~1
# 工作区未提交的变更
git diff --name-only

识别受影响的命令组

根据变更的代码文件映射到命令组：

代码文件	命令组	docs 文件
`cmd/apikey*.go`, `cmd/concurrency.go`	apikey	`docs/en/apikey.md` / `docs/zh/apikey.md`
`cmd/image*.go`	image	`docs/en/image.md` / `docs/zh/image.md`
`cmd/network.go`	network	`docs/en/network.md` / `docs/zh/network.md`
`cmd/skills*.go`	skills	`docs/en/skills.md` / `docs/zh/skills.md`
`cmd/docker.go`	docker	`docs/en/docker.md` / `docs/zh/docker.md`
`cmd/login.go`, `cmd/logout.go`, `cmd/constants.go`	core	`docs/en/core.md` / `docs/zh/core.md`

判定文档更新类型

变更类型	docs 更新	README 更新	CHANGELOG 更新
新增命令	✅ 添加完整命令文档节	✅ 在表格中添加子命令	✅
新增参数	✅ 更新参数表格	✅ 如影响简述则更新	✅
修改参数默认值	✅ 更新默认值和说明	✅ 如影响简述则更新	✅
修改输出格式	✅ 更新输出示例	❌ 通常不需要	✅
修改命令行为	✅ 更新说明和注意事项	✅ 更新简述	✅
仅内部重构	❌ 通常不需要	❌	视情况
仅补充翻译	❌	❌	✅ 仅 Phase 3

向用户确认更新范围

展示分析结果，例如：
检测到以下变更需要文档同步：
- 新增命令: apikey status → 需更新 docs/en/apikey.md、docs/zh/apikey.md、README 表格、CHANGELOG
- 修改参数: image create --os-type 默认值变更 → 需更新 docs/en/image.md、docs/zh/image.md
是否按此范围执行文档更新？

Phase 1: 更新 docs/ 命令文档

原则：中英文文档结构必须完全一致，内容互为翻译。先更新英文版，再同步中文版。

1.1 读取现有文档结构

读取目标命令组的现有文档，理解当前格式和风格。

1.2 新增命令 — 添加命令文档节

在对应命令组文档的 ## Commands / ## 命令 部分末尾追加新节。

英文版模板：

---

### `<group> <subcommand>`

<一句话描述>

```bash
agentbay <group> <subcommand> [flags]

Flags:

Flag	Short	Type	Required	Description
`--param`	`-p`	string	Yes	说明

Notes:

注意事项


**中文版模板**：

```markdown
---

### `<group> <subcommand>`

<一句话中文描述>

```bash
agentbay <group> <subcommand> [flags]

参数：

参数	短参数	类型	必填	说明
`--param`	`-p`	string	是	中文说明

注意事项：

注意事项


**关键约束**：

- 命令示例保留英文（`agentbay apikey create` 不翻译为 `agentbay apikey 创建`）
- 表头英文版用 `Flag` / `Short` / `Type` / `Required` / `Description`，中文版用 `参数` / `短参数` / `类型` / `必填` / `说明`
- `Required` 列英文版用 `Yes`/`No`，中文版用 `是`/`否`
- 如果命令有破坏性操作，必须包含 `--yes` / `-y` 参数说明和注意事项
- 如果没有短参数（Short），中文版可省略"短参数"列（参考同文件已有命令的格式）
- 新增节前用 `---` 分隔线

#### 1.3 修改命令 — 更新已有命令文档节

定位到对应子命令的文档节，更新受影响的部分：

- **新增参数**：在参数表格中追加行
- **修改参数默认值**：更新 Type 列中的默认值标注和 Description/说明列
- **修改输出格式**：更新输出示例代码块
- **修改命令行为**：更新描述段落和注意事项

**必须注意**：修改时不要破坏同一节中未变更的内容。

#### 1.4 双语同步验证

更新完成后，逐项对比中英文文档：

- [ ] 英文版和中文版的命令数量一致
- [ ] 每个命令的参数数量和名称一致
- [ ] Required/必填 列的值一致
- [ ] 注意事项的条目数一致
- [ ] 双语切换链接（文件第一行）正确

---

### Phase 1.5: 更新 RAM 接口权限说明

**目的**：当新增或删除 OpenAPI 调用时，同步维护各命令文档中的「涉及接口」章节，以及 README 中的 RAM 权限汇总表，并向用户输出权限变更摘要供人工核查。

#### 1.5.1 识别接口变更

基于 Phase 0 的变更分析，确认哪些命令新增/删除/修改了 OpenAPI 调用：

- 读取相关 `cmd/*.go` 文件，统计调用的接口名（函数名即 Action）
- 每个 Action 对应的权限字符串：`agentbay:<ActionName>`
- 不统计本地 docker CLI 封装命令（`docker tag`、`docker push`）

#### 1.5.2 在 docs/ 中维护「涉及接口」章节

**位置**：每个子命令的参数表格之后（或注意事项之后）、`---` 分隔线之前。

**英文版模板**：

```markdown
**Involved APIs:**

| Action | Required Permission |
|---|---|
| `XxxAction` | `agentbay:XxxAction` |

```json
{
  "Action": [
    "agentbay:XxxAction"
  ]
}


**中文版模板**：

```markdown
**涉及接口：**

| Action | 所需权限 |
|---|---|
| `XxxAction` | `agentbay:XxxAction` |

```json
{
  "Action": [
    "agentbay:XxxAction"
  ]
}


**规则**：

- 一个命令涉及多个接口时，表格按调用顺序列出所有 Action，JSON 数组同样全部列出
- 无需区分分支条件，只要命令可能调用的接口均需列出
- 本地 CLI 封装命令（无 AgentBay API 调用）不加「涉及接口」表格，改用提示：
  - 英文：`> **Note**: This is a native docker CLI wrapper — no AgentBay API calls are made. No additional RAM permissions required.`
  - 中文：`> **注意**：此命令是本地 docker CLI 的封装命令，不调用任何 AgentBay OpenAPI 接口，无需配置额外的 RAM 权限。`
- `skills list`（占位命令）等尚无 API 调用的命令不加「涉及接口」章节

#### 1.5.3 更新 README RAM 权限汇总表

`README.md` 和 `README.zh-CN.md` 中的 `## RAM Permissions` / `## RAM 账号接口权限` 章节包含各命令组的权限汇总表和 Policy JSON 示例。

**更新规则**：

- 新增接口：在对应命令组的汇总表中追加行，并在 Policy JSON 的 `Action` 数组中追加权限字符串
- 删除接口：从表格和 Policy JSON 中移除对应行/条目（需先确认该接口在该命令组的其他命令中已无引用）
- 接口名变更：同步修改表格和 Policy JSON

**Policy JSON 格式参考**（`README.md`）：

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "agentbay:XxxAction"
      ],
      "Resource": "*"
    }
  ]
}

1.5.4 终端输出接口变更摘要

⚠️ 执行本 skill 时，必须在终端输出以下格式的权限变更摘要，供用户核查是否有接口遗漏或误加：

========================================
  RAM 接口权限变更摘要
========================================

受影响命令组：<group>
受影响命令：<group> <subcommand>

新增接口权限：
  + agentbay:XxxAction     （<group> <subcommand>）

删除接口权限：
  - agentbay:YyyAction     （<group> <subcommand>）

无变更：（如无新增/删除则显示此行）

已同步位置：
  - docs/en/<group>.md — <subcommand> 涉及接口章节
  - docs/zh/<group>.md — <subcommand> 涉及接口章节
  - README.md — RAM Permissions > <group> 命令组
  - README.zh-CN.md — RAM 账号接口权限 > <group> 命令组

请核查上述权限变更是否正确，如有遗漏请告知。
========================================

输出时机：在完成所有文档更新后，统一输出一次摘要。如果本次变更无 OpenAPI 调用变化（纯参数修改、文档格式调整等），则输出「无接口权限变更」。

Phase 2: 更新 README Command Overview 表格

原则：README 表格只做概要展示，不展示详细参数。更新时保持表格格式不变。

2.1 定位 Command Overview 表格

README.md 中搜索 ## Command Overview。 README.zh-CN.md 中搜索 ## 命令概览。

2.2 更新表格

新增子命令：在对应命令组的 Commands 列中，按逻辑序追加子命令名（用反引号包裹，逗号分隔）。

例如新增 apikey status 命令后：

英文：`create`, `enable`, `disable`, `delete`, `list`, `status`, `concurrency set`
中文：`create`, `enable`, `disable`, `delete`, `list`, `status`, `concurrency set`

修改子命令：如果命令重命名，替换旧名为新名。

关键约束：

README 表格中的命令名一律使用英文（中文版也不例外）
保持 Details 列的链接不变
两组 README 的表格内容必须完全一致（仅表头和列名不同）
不要改变表格列的顺序和宽度

Phase 3: 更新 CHANGELOG.md

原则：CHANGELOG 由 git-cliff 自动生成英文部分，中文翻译由 AI 生成后经用户确认写入。

3.1 获取最新远程信息

git fetch aliyun

3.2 比对当前分支与 aliyun/master 的差异

git log aliyun/master..HEAD --oneline

此步骤确认有哪些新 commit 将被纳入 CHANGELOG，验证 git-cliff 的输出是否完整。

3.3 生成/更新 CHANGELOG

# 优先使用 Makefile target
make changelog

# 或直接使用 git-cliff
git-cliff -o CHANGELOG.md

如果 git-cliff 未安装，提示用户安装：

make changelog-install
# 或
brew install git-cliff

3.4 检查生成的 CHANGELOG

读取更新后的 CHANGELOG.md，检查：

[Unreleased] 部分是否包含本次变更
分类是否正确（Features / Bug Fixes / Documentation / Other Changes）
scope 标注是否正确（**apikey**:、**image**: 等）

3.5 补充中文翻译

查找待翻译占位符：

在 CHANGELOG.md 中搜索 。

翻译规则：

英文分类	中文分类	条目动词示例
Features	新功能	新增、支持
Bug Fixes	问题修复	修正、修复、兼容
Documentation	文档	补充、更新、新增
Refactoring	重构	重构、简化
Performance	性能	优化、提升
Other Changes	其他变更	更新、移除、新增

翻译格式：

在 * * * 分隔线下方，镜像英文结构的中文版本：

* * *

### 新功能

- **apikey**: 新增 `apikey delete` 命令，支持多步骤确认
- **image**: 新增 `image warmup-status` 命令

### 问题修复

- **client**: 兼容响应中 `HttpStatusCode` 字段为字符串类型的情况

翻译要点：

scope 保留英文（**apikey**:、**image**:、**client**:）
命令名保留英文（`apikey delete` 不翻译）
遵循已有版本的翻译风格（参考 CHANGELOG.md 中 v0.2.7、v0.2.9 等已有翻译）
合并同类条目时保持语义不丢失

3.6 向用户确认翻译

将生成的中文翻译完整展示给用户：

已生成以下 CHANGELOG 中文翻译，请确认：
### 新功能
- **apikey**: 新增 `apikey status` 命令，用于查询 API Key 状态
是否需要修改？确认后将写入 CHANGELOG.md。

⚠️ 铁律：翻译必须经用户确认后才可写入，不得自动替换占位符。

3.7 写入并验证

将翻译替换占位符，写入 CHANGELOG.md。验证：

 占位符已被替换
* * * 分隔线在英文和中文之间
没有残留的占位符

📤 输出标准

docs/ 命令文档

docs/en/<group>.md 已更新（新增节或修改已有节）
docs/zh/<group>.md 已更新（与英文版结构一致）
双语切换链接正确
参数表格完整且类型/必填标注准确
涉及接口章节已更新（新增/删除/修改 OpenAPI 调用时）

README RAM 权限汇总

README.md RAM Permissions 表格已更新（新增/删除接口时）
README.zh-CN.md RAM 账号接口权限表格已更新
Policy JSON 中的 Action 数组已同步

README Command Overview

README.md Command Overview 表格已更新
README.zh-CN.md 命令概览表格已更新
两个表格的命令列表一致

CHANGELOG

git fetch aliyun 已执行
git-cliff -o CHANGELOG.md 已执行（或 make changelog）
中文翻译已补充（占位符已替换）
翻译已经用户确认
无残留  占位符

📚 参考

development.md — 文档同步规则
create-cli-command — CLI 命令封装流程（Phase 5 委托本 skill）
feature-development-workflow — 开发流程规范

⚠️ 注意事项

先代码后文档：文档更新必须在代码变更完成后执行，避免文档与代码不一致
双语必须同步：docs/en/ 和 docs/zh/ 的结构必须完全一致，不得只更新一方
CHANGELOG 翻译需确认：AI 生成的中文翻译必须经用户确认后才写入，不得自动替换
不要修改已有版本的翻译：CHANGELOG 中已发布版本的翻译不得修改，只更新 [Unreleased] 或最新版本
README 表格格式：不得改变表格列的顺序、宽度或格式风格
命令名一律英文：文档中所有命令名、参数名均使用英文，不翻译
参考已有风格：更新 docs/ 时参考同文件中已有命令的文档风格，保持一致
接口变更必须同步权限文档：只要新增或删除了 OpenAPI 调用，涉及接口章节和 README RAM 权限汇总表必须同步更新，不得遗漏
必须输出权限变更摘要：无论有无接口变更，都必须在终端输出 Phase 1.5.4 要求的摘要，方便用户人工核查

update-cli-command-docs

More from this repository

More from this repository