@aipper/aiws-spec 0.0.17 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

package/templates/workspace/.agents/skills/ws-bugfix/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: ws-bugfix
+description: 缺陷修复（通过禅道 MCP 拉取 bug 与附件，下载图片证据，汇总到 issues/fix_bus_issues.csv，并绑定到 changes/<change-id>/）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 用禅道 MCP 拉取 bug 详情与附件（尤其图片）
+- 把证据落盘到 `changes/<change-id>/bug/`（避免只停留在对话）
+- 把修复任务汇总/更新到 `issues/fix_bus_issues.csv`
+- 与 `ws-dev` / `aiws change` 流程绑定，确保可追溯、可验证
+
+非目标（强制）：
+- 不自动 commit / push
+- 不写入任何 secrets（token、cookie、内网地址）
+- 不在无法复现时直接改代码（先产出阻塞信息）
+
+前置：
+1) 先运行 `$ws-preflight`。
+2) 准备 `change-id`（建议：`bug-<bug-id>` 或 `bugfix-<bug-id>-<slug>`）。
+3) 建立变更工件（推荐）：
+```bash
+aiws change start <change-id> --hooks
+# superproject + submodule 推荐：
+aiws change start <change-id> --hooks --worktree --submodules
+```
+
+建议流程（按顺序）：
+
+## 1) 通过禅道 MCP 拉取 bug
+- 使用当前会话中已启用的 zentao MCP 工具获取：
+  - `bug_id`、标题、优先级/严重级、模块、状态、指派人
+  - 重现步骤、期望结果、实际结果
+  - 附件列表（含图片 URL/文件名）
+- 若当前环境没有 zentao MCP 工具：立即停止并提示用户先配置，不要猜数据。
+
+## 2) 证据落盘（强制）
+在 `changes/<change-id>/bug/` 下落盘：
+- `zentao-bug-<bug-id>.json`：原始字段快照（避免信息丢失）
+- `zentao-bug-<bug-id>.md`：人类可读摘要（复现步骤/期望/实际/风险）
+- `images/<bug-id>/...`：下载的图片附件（保留原扩展名）
+
+建议目录：
+```text
+changes/<change-id>/bug/
+  zentao-bug-<bug-id>.json
+  zentao-bug-<bug-id>.md
+  images/<bug-id>/
+```
+
+## 3) 汇总到 issues/fix_bus_issues.csv（upsert）
+- 目标文件：`issues/fix_bus_issues.csv`
+- 若文件不存在，先创建表头：
+```csv
+Bug_ID,Title,Severity,Module,Status,Assigned_To,Change_ID,Image_Count,Image_Paths,Evidence_Path,Verify_Command,Fix_Status,Updated_At,Notes
+```
+- 以 `Bug_ID` 为主键 upsert：
+  - 已存在：更新状态/证据/图片路径
+  - 不存在：新增一行
+
+字段约束：
+- `Change_ID`：必须等于当前 `change-id`
+- `Evidence_Path`：指向 `changes/<change-id>/bug/zentao-bug-<bug-id>.md`
+- `Image_Paths`：多个路径用 `;` 分隔
+- `Fix_Status`：`TODO|DOING|DONE|BLOCKED`
+
+## 4) 修复执行与回填
+- 进入 `$ws-dev` 做最小改动修复。
+- 完成后回填 `issues/fix_bus_issues.csv`：
+  - `Fix_Status`
+  - `Verify_Command`
+  - `Updated_At`
+  - `Notes`（必要时写阻塞原因）
+
+## 5) 验证与交付
+```bash
+aiws change validate <change-id> --strict
+aiws validate . --stamp
+```
+- 需要提交时走 `$ws-commit`。
+- 需要收尾合并时走 `$ws-finish`（或在 superproject + submodule 场景走 `$ws-deliver`）。
+
+输出要求：
+- `Change_ID:` `<change-id>`
+- `CSV:` `issues/fix_bus_issues.csv` 中对应 `Bug_ID` 行的关键字段
+- `Evidence:` `changes/<change-id>/bug/zentao-bug-<bug-id>.md` + 图片目录
+- `Verify:` 实际运行命令与结果（未运行不声称已运行）

package/templates/workspace/.claude/commands/aiws-change-archive.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-archive -->
+# aiws change archive
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 归档已完成 change 工件
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change archive "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change archive "${change_id}"
+else
+  npx @aipper/aiws change archive "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-archive -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-finish.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-finish -->
+# aiws change finish
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 将 change/<change-id> 安全 fast-forward 合并回目标分支
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"  # 可留空（若当前分支可推断）
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change finish "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change finish "${change_id}"
+else
+  npx @aipper/aiws change finish "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-finish -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-list.md

@@ -0,0 +1,21 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-list -->
+# aiws change list
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 列出当前仓库 change 工件
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change list
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change list
+else
+  npx @aipper/aiws change list
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-list -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-new.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-new -->
+# aiws change new
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 创建 changes/<change-id> 工件目录与基础文件
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change new "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change new "${change_id}"
+else
+  npx @aipper/aiws change new "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-new -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-next.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-next -->
+# aiws change next
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 输出 change 下一步建议动作
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"  # 可留空（若当前分支可推断）
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change next "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change next "${change_id}"
+else
+  npx @aipper/aiws change next "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-next -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-start.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-start -->
+# aiws change start
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 切到 change/<change-id> 并初始化变更工件
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change start "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change start "${change_id}"
+else
+  npx @aipper/aiws change start "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-start -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-status.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-status -->
+# aiws change status
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 查看 change 当前状态与阻断项
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"  # 可留空（若当前分支可推断）
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change status "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change status "${change_id}"
+else
+  npx @aipper/aiws change status "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-status -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-sync.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-sync -->
+# aiws change sync
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 同步当前 change 与真值文件基线
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change sync "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change sync "${change_id}"
+else
+  npx @aipper/aiws change sync "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-sync -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-templates-init.md

@@ -0,0 +1,21 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-templates-init -->
+# aiws change templates init
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 初始化 changes/templates 覆盖模板
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates init
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates init
+else
+  npx @aipper/aiws change templates init
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-templates-init -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-templates-which.md

@@ -0,0 +1,21 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-templates-which -->
+# aiws change templates which
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 查看 change 模板来源
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates which
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates which
+else
+  npx @aipper/aiws change templates which
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-templates-which -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-change-validate.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-change-validate -->
+# aiws change validate
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 按严格模式校验变更工件与绑定关系
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change validate "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change validate "${change_id}"
+else
+  npx @aipper/aiws change validate "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-change-validate -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-hooks-install.md

@@ -0,0 +1,21 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-hooks-install -->
+# aiws hooks install
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 启用 git hooks 门禁（core.hooksPath=.githooks）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks install .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks install .
+else
+  npx @aipper/aiws hooks install .
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-hooks-install -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/aiws-hooks-status.md

@@ -0,0 +1,21 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-hooks-status -->
+# aiws hooks status
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 查看当前仓库 hooks 门禁状态（只读）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```
+<!-- AIWS_MANAGED_END:claude:aiws-hooks-status -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-bugfix.md

@@ -0,0 +1,27 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-bugfix -->
+# ws bugfix
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 通过禅道 MCP 拉单、图片证据落盘并汇总 `issues/fix_bus_issues.csv`。
+
+建议流程：
+1) 先运行 `/ws-preflight`。
+2) 建立变更工件（推荐）：`aiws change start <change-id> --hooks`（superproject+submodule 可用 `--worktree --submodules`）。
+3) 通过已配置 zentao MCP 拉取 bug 字段与附件列表。
+4) 落盘证据到 `changes/<change-id>/bug/`：
+   - `zentao-bug-<bug-id>.json`
+   - `zentao-bug-<bug-id>.md`
+   - `images/<bug-id>/...`
+5) upsert `issues/fix_bus_issues.csv`（主键 `Bug_ID`）。
+6) 进入 `/ws-dev` 修复并回填 `Fix_Status/Verify_Command/Updated_At`。
+7) 质量门：`aiws change validate <change-id> --strict` + `aiws validate . --stamp`。
+
+强制约束：
+- 不自动 commit / push。
+- 不写入 secrets（token、cookie、内网地址）。
+- 无法复现时先输出阻塞信息并落盘，不直接改代码。
+<!-- AIWS_MANAGED_END:claude:ws-bugfix -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-plan-verify.md

@@ -0,0 +1,25 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-plan-verify -->
+# ws plan verify
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 执行前检查计划是否跑偏，并给出最小修正项。
+
+执行建议：
+1) 先运行 `/ws-preflight`。
+2) 运行严格门禁：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change validate <change-id> --strict
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change validate <change-id> --strict
+else
+  npx @aipper/aiws change validate <change-id> --strict
+fi
+```
+3) 若失败：先修 `proposal.md` / `plan` 的绑定字段与验证命令，再复跑。
+4) 通过后再进入 `/ws-dev`。
+<!-- AIWS_MANAGED_END:claude:ws-plan-verify -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-plan.md

@@ -0,0 +1,17 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-plan -->
+# ws plan
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 生成可落盘执行计划（供 /ws-dev 执行）。
+
+执行建议：
+1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
+2) 生成或更新计划文件：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`。
+3) 计划至少包含：`Bindings`、`Goal`、`Non-goals`、`Scope`、`Plan`、`Verify`、`Risks & Rollback`、`Evidence`。
+4) 若已有 `changes/<change-id>/proposal.md`，对齐 `Plan_File` / `Contract_Row` / `Evidence_Path`。
+5) 完成后先运行 `/ws-plan-verify`，通过再进入 `/ws-dev`。
+<!-- AIWS_MANAGED_END:claude:ws-plan -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-change-archive.md

@@ -0,0 +1,25 @@
+---
+description: 变更归档：归档已完成的 change 工件
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-archive -->
+# aiws change archive
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 归档已完成 change 工件
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change archive "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change archive "${change_id}"
+else
+  npx @aipper/aiws change archive "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-archive -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-change-finish.md

@@ -0,0 +1,25 @@
+---
+description: 变更收尾：安全合并 change 分支回目标分支
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-finish -->
+# aiws change finish
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 将 change/<change-id> 安全 fast-forward 合并回目标分支
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"  # 可留空（若当前分支可推断）
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change finish "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change finish "${change_id}"
+else
+  npx @aipper/aiws change finish "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-finish -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-change-list.md

@@ -0,0 +1,24 @@
+---
+description: 变更列表：列出当前仓库 change 工件
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-list -->
+# aiws change list
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 列出当前仓库 change 工件
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change list
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change list
+else
+  npx @aipper/aiws change list
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-list -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-change-new.md

@@ -0,0 +1,25 @@
+---
+description: 变更新建：创建 changes/<change-id> 工件
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-new -->
+# aiws change new
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 创建 changes/<change-id> 工件目录与基础文件
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change new "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change new "${change_id}"
+else
+  npx @aipper/aiws change new "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-new -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-change-next.md

@@ -0,0 +1,25 @@
+---
+description: 变更下一步：输出当前 change 的建议动作
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-next -->
+# aiws change next
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 输出 change 下一步建议动作
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"  # 可留空（若当前分支可推断）
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change next "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change next "${change_id}"
+else
+  npx @aipper/aiws change next "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-next -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-change-start.md

@@ -0,0 +1,25 @@
+---
+description: 变更开始：切到 change/<change-id> 并初始化工件
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-start -->
+# aiws change start
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 切到 change/<change-id> 并初始化变更工件
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change start "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change start "${change_id}"
+else
+  npx @aipper/aiws change start "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-start -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/aiws-change-status.md

@@ -0,0 +1,25 @@
+---
+description: 变更状态：查看 change 状态与阻断项
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-status -->
+# aiws change status
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 查看 change 当前状态与阻断项
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"  # 可留空（若当前分支可推断）
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change status "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change status "${change_id}"
+else
+  npx @aipper/aiws change status "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-status -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。