@aipper/aiws-spec 0.0.16 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "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/AGENTS.md

@@ -10,7 +10,21 @@
 - 启用本机门禁（推荐）：`aiws hooks install .`（或手工：`git config core.hooksPath .githooks`；`git commit`/`git push` 会自动跑 `aiws validate .`）
 - 提交前校验（强制门禁）：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
 - Codex（推荐）：本仓库内置 repo skills：`.agents/skills/`（可显式 `$ws-dev`，也可隐式套用工作流）
-- Codex skills（常用）：`$ws-preflight` / `$ws-submodule-setup` / `$ws-plan` / `$ws-plan-verify` / `$ws-dev` / `$ws-pull` / `$ws-push` / `$ws-review` / `$ws-commit` / `$aiws-init` / `$aiws-validate` / `$aiws-hooks-install` / `$aiws-change-new`
+- Codex skills（常用，一句话说明）：
+  - `$ws-preflight`：预检（读取真值文件并输出约束摘要）
+  - `$ws-submodule-setup`：子模块分支对齐（写入 `.gitmodules` 的 `submodule.<name>.branch`）
+  - `$ws-plan`：规划（生成可落盘 `plan/` 工件；供 `$ws-dev` 执行）
+  - `$ws-plan-verify`：计划质检（执行前检查计划是否过长/跑偏）
+  - `$ws-dev`：开发（按需求实现并验证；适用于任何需要修改代码/配置的任务）
+  - `$ws-bugfix`：缺陷修复（禅道 MCP 拉单 + 图片证据落盘 + `issues/fix_bus_issues.csv` 汇总）
+  - `$ws-pull`：拉取并对齐 submodules（尽量避免 detached；减少人为差异）
+  - `$ws-push`：推送（submodule 感知：先 submodules 后 superproject；fast-forward 安全）
+  - `$ws-review`：评审（提交前审计与证据落盘）
+  - `$ws-commit`：提交（先审计/门禁再 commit；submodule 感知）
+  - `$aiws-init`：初始化工作区（生成真值文件与门禁）
+  - `$aiws-validate`：校验工作区（漂移检测 + 门禁）
+  - `$aiws-hooks-install`：启用 git hooks 门禁（`core.hooksPath=.githooks`）
+  - `$aiws-change-new`：创建 `changes/<change-id>` 工件
 - Codex CLI（推荐，可选）：安装全局 skills：`npx @aipper/aiws codex install-skills`（写入 `~/.codex/skills/` 或 `$CODEX_HOME/skills`）
 - Codex CLI（遗留，可选）：安装全局 prompts：`npx @aipper/aiws codex install-prompts`（写入 `~/.codex/prompts/` 或 `$CODEX_HOME/prompts`；prompts 已 deprecated）
 - 不要把敏感信息写入 git：`secrets/test-accounts.json`、`.env*`、token、内网地址等

package/templates/workspace/manifest.json

@@ -139,6 +139,7 @@
       ".agents/skills/aiws-change-templates-which/SKILL.md",
       ".agents/skills/aiws-change-templates-init/SKILL.md",
       ".agents/skills/ws-analyze/SKILL.md",
+      ".agents/skills/ws-bugfix/SKILL.md",
       ".agents/skills/ws-commit/SKILL.md",
       ".agents/skills/ws-dev/SKILL.md",
       ".agents/skills/ws-deliver/SKILL.md",