@aipper/aiws-spec 0.0.1

package/templates/workspace/.opencode/command/ws-dev.md

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-dev -->
+# ws dev
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 约束下完成一个可回放、可验证的小步交付。
+
+建议流程：
+1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+2) 建立变更归因（推荐）：
+   - 切分支：`git switch -c change/<change-id>`
+   - 初始化变更工件：创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）
+3) 如涉及需求调整：先 `/ws-req-review` → 用户确认后再 `/ws-req-change`（避免需求漂移）。
+4) 实施最小改动：任何改动都要能归因到 `REQUIREMENTS.md`（验收）或 `issues/problem-issues.csv`（问题）。
+5) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。
+6) 提交前强制：`aiws validate .`（commit/push hooks 也会阻断）。
+
+输出要求：
+- `Changed:` 文件清单
+- `Verify:` 实际运行的命令 + 期望结果
+- `Evidence:` 证据路径（例如 `.agentdocs/tmp/...` 或 `changes/<change-id>/...`）
+<!-- AIWS_MANAGED_END:opencode:ws-dev -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-migrate.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-migrate -->
+# ws migrate
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
+
+执行（在项目根目录）：
+1) 若已存在 `.aiws/manifest.json`：`npx @aipper/aiws update .`
+2) 否则：`npx @aipper/aiws init .`
+3) 门禁校验：`npx @aipper/aiws validate .`
+4) 启用本机 git hooks（推荐，本地生效）：`git config core.hooksPath .githooks`
+
+回滚：
+- 恢复最近一次快照：`npx @aipper/aiws rollback . latest`
+
+约束：
+- 不写入任何 secrets。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-migrate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-preflight.md

@@ -0,0 +1,27 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-preflight -->
+# ws preflight
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：
+   - 优先：`git rev-parse --show-toplevel`
+   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+3) 输出：
+   - `Root:` <项目根路径>
+   - `Found:` <实际读取到的文件列表>
+   - `Missing:` <缺失文件列表>
+   - `Key rules:` 3–8 条 bullet（范围/禁止项/必须产物/必须验证命令）
+
+安全：
+- 不打印 secrets；遇到疑似敏感值只提示“存在风险”但不要复述原文。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-preflight -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-req-change.md

@@ -0,0 +1,34 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-change -->
+# ws req change
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：记录需求变更（更新 `REQUIREMENTS.md` + 追加 `requirements/CHANGELOG.md`），并同步/校验执行合同 `requirements/requirements-issues.csv`。
+
+步骤（必须按顺序）：
+1) 读取：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`、`requirements/CHANGELOG.md`（缺失则创建目录与文件）。
+2) 先产出“拟变更方案”（不要立刻写文件）：
+   - 变更摘要（1–5 条）
+   - 影响范围（API/鉴权/字段/状态码/测试边界）
+   - 回滚思路（1–2 条）
+3) 强制停下来让用户确认：是否继续落盘？(Y/N)
+4) 用户确认 Y 后再写入：
+   - 更新 `REQUIREMENTS.md`（只保留当前有效版本，不在此堆历史）
+   - 追加 `requirements/CHANGELOG.md`
+5) 同步/补齐执行合同（至少做其中之一，按仓库现状选择最安全路径）：
+   - 若你维护了 FlowSpec：`python3 tools/requirements_contract_sync.py --workspace .`
+   - 否则：`python3 tools/requirements_contract.py init` 后手工补齐/新增对应 Req 行
+6) 校验（强制）：`python3 tools/requirements_contract.py validate`
+7) 建议（如维护 FlowSpec）：运行 `/ws-req-flow-sync`
+
+输出必须包含：
+- 本次更新的文件清单（路径）
+- 回滚方案（如何撤销本次需求变更）
+- 下一步建议命令
+
+安全：
+- 不打印 `secrets/test-accounts.json`
+- 不引入任何 token/密钥到仓库
+<!-- AIWS_MANAGED_END:opencode:ws-req-change -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-req-contract-sync.md

@@ -0,0 +1,18 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-sync -->
+# ws req contract sync
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+用途：从 `REQUIREMENTS.md` 的 FlowSpec 补齐 `requirements/requirements-issues.csv`（只生成骨架，不猜测完成状态）。
+
+执行（在 workspace 根目录）：
+- `python3 tools/requirements_contract_sync.py --workspace .`
+
+输出要求：
+- 说明新增/更新了多少条
+- 明确下一步：手工补齐 CRUD/Inputs/Outputs/Business_Logic/Tests，并将可开工条目标为 `Spec_Status=READY`
+
+下一步建议：`/ws-req-contract-validate`
+<!-- AIWS_MANAGED_END:opencode:ws-req-contract-sync -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-req-contract-validate.md

@@ -0,0 +1,13 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-validate -->
+# ws req contract validate
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+执行（失败则修正 CSV 后重试）：
+- `python3 tools/requirements_contract.py validate`
+
+输出要求：
+- 若失败：列出前 20 条缺失字段（Req_ID + field），并给出最小补齐建议
+<!-- AIWS_MANAGED_END:opencode:ws-req-contract-validate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-req-flow-sync.md

@@ -0,0 +1,20 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-flow-sync -->
+# ws req flow sync
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：基于 `REQUIREMENTS.md` 的 FlowSpec 生成：
+- `docs/api-flow.mmd`（简短逻辑图，Mermaid）
+- `issues/server-scenario-issues.csv`（场景执行合同：TODO/DONE/BLOCKED）
+
+执行（在 workspace 根目录）：
+`python3 tools/requirements_flow_gen.py --workspace .`
+
+若缺少工具 `tools/requirements_flow_gen.py`：提示用户先运行 `npx @aipper/aiws init .`（默认会安装 optional tools）。
+
+输出要求：只打印生成的文件路径与下一步命令：
+- 查看逻辑图：`cat docs/api-flow.mmd`
+- 查看场景合同：`cat issues/server-scenario-issues.csv`
+<!-- AIWS_MANAGED_END:opencode:ws-req-flow-sync -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-req-review.md

@@ -0,0 +1,33 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-review -->
+# ws req review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不修改任何文件的前提下，对 `REQUIREMENTS.md` 做一次整体 QA，输出缺口/冲突/风险，减少实现漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：`git rev-parse --show-toplevel`（失败则停止并让用户确认根目录）。
+2) 读取（存在则必须读取；缺失则明确列出，不要臆测）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+   - `requirements/CHANGELOG.md`（若存在）
+   - `requirements/requirements-issues.csv`（若存在）
+3) 输出固定结构的报告：
+
+## Requirements QA
+- 结论：是否可进入实现（是/否/有条件）
+- 漂移风险：最容易导致不一致的点
+- 可验收性缺口：缺少输入/输出/错误码/边界/示例的条目
+- 完整性：Non-goals/兼容性/鉴权/重试/并发/观测性/性能
+- 一致性：与 `AI_PROJECT.md` 约束冲突点
+- 可测试性与证据：最小验证命令 + 期望结果 + 证据路径
+- 风险清单：3–8 条
+- 需要澄清的问题：5–12 个（按优先级）
+
+4) 最后询问用户：是否进入需求落盘流程 `/ws-req-change`？(Y/N)
+
+安全：不打印 `secrets/test-accounts.json`。
+<!-- AIWS_MANAGED_END:opencode:ws-req-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-review.md

@@ -0,0 +1,25 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-review -->
+# ws review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据落盘到 `.agentdocs/tmp/review/`。
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
+   - 是否存在越界目录改动/危险操作
+   - 是否有可复现验证命令与证据
+   - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
+3) 将审计落盘到：`.agentdocs/tmp/review/opencode-review.md`（目录不存在则创建）。
+4) 回复中输出：
+   - `Evidence:` 证据文件路径
+   - `Top risks:` 3–8 条（高→低）
+   - `Next:` 最小修复清单 + 最小验证命令
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-rule.md

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-rule -->
+# ws rule
+
+     用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+     目标：把用户口述的“项目特有规则”整理成可执行条款，并写入 `AI_PROJECT.md` 的 `AI_PROJECT_RULES_BEGIN/END` 段（托管块外内容会被保留）。
+
+     安全规则（强制）：
+     - 不打印/不写入 secrets（token、密钥、内网地址、账号密码）。
+     - 不执行破坏性命令。
+
+     工作流：
+     1) 先运行 `/ws-preflight`；若缺失 `AI_PROJECT.md`：提示用户先 `/ws-migrate` 或运行 `npx @aipper/aiws init .`。
+     2) 写入前创建备份（必须）：
+`ts="$(date +%Y%m%d-%H%M%S)"; mkdir -p .aiws/backups/manual; cp -a AI_PROJECT.md .aiws/backups/manual/AI_PROJECT.md.bak.${ts}`
+     3) 先输出“将写入的规则清单”（3–12 条），并要求用户回复 `CONFIRM` 后再落盘。
+     4) 用户确认后，**仅更新** BEGIN/END 段内内容（合并去重；写成可检查条款：目录白名单/必须验证命令/禁止项/产物要求）。
+     5) 输出必须包含：
+        - 更新了哪些文件（路径）
+        - 回滚方式（恢复备份文件）
+        - 下一步建议：`aiws validate .`
+<!-- AIWS_MANAGED_END:opencode:ws-rule -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/AGENTS.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:agents -->
+本仓库启用 AIWS（AI Workspace）约定，请先读取并遵守（按优先级）：
+1) `AI_PROJECT.md`（规则/边界）
+2) `REQUIREMENTS.md`（需求与验收真值）
+3) `AI_WORKSPACE.md`（运行/测试入口真值）
+4) `changes/README.md`（变更工件流程与归档）
+
+协作约束（建议最小集）：
+- 每次变更使用分支 `change/<change-id>`，并维护 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
+- 启用本机门禁（推荐）：`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-plan` / `$ws-dev` / `$ws-review` / `$ws-commit` / `$aiws-init` / `$aiws-validate` / `$aiws-hooks-install` / `$aiws-change-new`
+- 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、内网地址等
+
+如果缺文件：运行 `npx @aipper/aiws init`（或 `aiws init`）。
+（如你仍在使用 dotfiles 的 `ws` wrappers，也可用 `ws init/ws migrate`；但本模板默认不依赖 dotfiles。）
+<!-- AIWS_MANAGED_END:agents -->
+
+你可以在本段下方追加项目自定义说明；`aiws update` 不会改动托管块以外内容。

package/templates/workspace/AI_PROJECT.md

@@ -0,0 +1,86 @@
+# AI_PROJECT.md（项目规则 / 约束真值）
+
+<!-- AIWS_MANAGED_BEGIN:ai-project:core -->
+<!-- AI_PROJECT_VERSION: 2 -->
+
+本文件用于在**具体项目/工作区**内统一 Codex / Claude / OpenCode / iFlow 的执行约束与协作方式，避免多套规则各写一份导致漂移。
+
+定位：
+- `REQUIREMENTS.md`：定义“要做什么/验收是什么”（需求真值）
+- `AI_WORKSPACE.md`：定义“怎么跑/怎么测/目录如何发现”（运行与测试真值）
+- `AI_PROJECT.md`：定义“允许怎么做/边界是什么/产物如何沉淀”（项目约束真值）
+
+## 1) 优先级（强制）
+
+当三者内容冲突时，按以下优先级执行：
+1. `AI_PROJECT.md`
+2. `REQUIREMENTS.md`
+3. `AI_WORKSPACE.md`
+4. `requirements/CHANGELOG.md`（仅记录历史，不覆盖当前需求）
+5. `requirements/requirements-issues.csv`（需求拆解执行合同：Spec/Impl 状态机）
+6. `issues/*.csv`（执行合同；必须与上面真值一致）
+
+## 2) 安全与边界（强制）
+
+- 不写入/不打印 secrets：`secrets/`、`.env*`、token/apiKey/oauth/private_key 等不得进入 git。
+- 不做破坏性操作：除非在本文件明确允许（例如 `rm -rf`、`git reset --hard`、`git clean -fdx`）。
+- 仅在 `environment: test` 场景允许自动化修复闭环/无人值守（否则必须人工确认每一步）。
+
+## 3) 产物与证据（强制）
+
+每轮迭代必须落盘至少一个“可追溯产物”（三选一即可）：
+- 证据：`.agentdocs/tmp/...`（report/log/resp）
+- 合同：`issues/*.csv`（状态变化：TODO/DOING/DONE/BLOCKED/SKIP）
+- 变更工件：`changes/<change-id>/`（proposal/tasks/design；详见 `changes/README.md`）
+
+不得只在对话里口头描述“已验证/已修复”。
+
+推荐（防规则/范围漂移）：
+- 创建工件：补齐 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
+- 声明 active change（团队共享）：切到分支 `change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
+- 严格校验：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
+- 启用 hooks（本地生效）：`git config core.hooksPath .githooks`（提交/推送时自动跑 `aiws validate .`）
+- CI 建议追加：`aiws validate .`
+
+可选（完全脱离 dotfiles 的默认路径）：
+- `aiws change new|validate|sync|archive ...`（创建工件/运行校验/归档的快捷命令）
+
+### 3.1) 变更归因（强制）
+
+任何“写代码/改配置/改测试”的改动必须能归因到以下二选一：
+- **需求交付**：关联 `requirements/requirements-issues.csv` 的 `Req_ID`（并能映射到 `REQUIREMENTS.md` 的验收条款）
+- **问题修复**：关联 `issues/problem-issues.csv` 的 `Problem_ID`（BUG/TECHDEBT/OPS/TOOLING 等）
+
+若一个问题阻塞某个需求交付：两边都要互相引用（在 `Notes` 字段里写对方的 ID），避免“修了但没人验收/验收了但遗留问题丢失”。
+
+## 4) 提交流程（默认推荐）
+
+- 先对齐 `REQUIREMENTS.md`（必要时用 `/ws-req-change` 记录变更并写入 `requirements/CHANGELOG.md`）
+- 再执行最小验证（以 `AI_WORKSPACE.md` 的测试入口为准）
+- 最后才允许提交（若项目采用 submodule，按 `AI_WORKSPACE.md` 的 `server_dirs` 执行）
+
+## 5) 可配置开关（可选）
+
+如需要在本项目强制更严格的行为，可在此追加明确条款（示例）：
+- 只允许改动的目录白名单
+- 必须执行的测试命令列表
+- 必须携带/回传 `X-Request-Id` 的接口范围
+
+## 6) 服务端/自动化测试约束（工作区模式，强制）
+
+当本目录按 AI Workspace 运行（存在 `AI_WORKSPACE.md` / `REQUIREMENTS.md` / `tools/server_test_runner.py`）时，约束如下：
+
+- `X-Request-Id`：自动化测试请求必须携带；服务端必须回传同名响应头；日志应包含 `request_id=<id>` 以便按单次请求定位问题。
+- 接口清单真值：优先使用 `docs/openapi.json`。若缺失，先补齐导出方式并生成到该路径，再做全量覆盖测试（避免“覆盖范围不可复现”）。
+- 证据落盘：每轮至少更新一次 `.agentdocs/tmp/...` 或 `issues/*.csv`（禁止只在对话里口头宣称“已验证/已修复”）。
+
+<!-- AIWS_MANAGED_END:ai-project:core -->
+
+## 7) 项目特有规则（ws-rule 管理）
+
+<!-- AI_PROJECT_RULES_BEGIN -->
+- 使用 `/ws-rule` 维护本段内容；请勿手工修改 BEGIN/END 标记。
+- 建议写成“可执行/可检查”的条款（能落到目录/文件/命令/产物），避免只写口号。
+<!-- AI_PROJECT_RULES_END -->
+
+你可以在本段下方追加项目自定义说明；`aiws update` 不会改动托管块以外内容。

package/templates/workspace/AI_WORKSPACE.md

@@ -0,0 +1,167 @@
+# AI_WORKSPACE.md（工作区说明）
+
+## 0) 项目配置（用户维护）
+
+本段由用户维护；`aiws update` 不会改动本段（建议把“可变参数”都放在这里）。
+
+- server_dirs:
+  - ./backend
+- web_dirs:
+  - ./web
+- app_dirs:
+  - ./app
+
+- openapi_path: "docs/openapi.json"
+- openapi_url: "/openapi.json"
+
+- base_url: "http://127.0.0.1:8080"
+- health_path: "/health"
+- log_path: ".agentdocs/tmp/server-test/app.log"
+
+- environment: "test"
+- base_url_allowlist:
+  - "http://127.0.0.1"
+  - "http://localhost"
+  - "https://127.0.0.1"
+  - "https://localhost"
+- dangerous_disabled: true
+- max_requests_per_minute: 60
+
+- node_version: "20"
+- node_use_cmd: "command -v mise >/dev/null && mise use -g node@20 || (command -v nvm >/dev/null && nvm use 20) || true"
+
+<!-- AIWS_MANAGED_BEGIN:ai-workspace:core -->
+
+本文件描述“AI Workspace（多子项目工作区）”的结构与运行方式，供 Codex / Claude / OpenCode / iFlow 共同读取。
+
+## 1) 目录发现规则
+
+目录名不固定时，按以下优先级寻找 server（后端服务）目录：
+1. 明确配置（推荐）：在上方 `0) 项目配置` 写出 `server_dirs` 列表（相对路径）
+2. 自动发现：扫描子目录，匹配以下标记文件
+   - Rust：`Cargo.toml`
+   - Go：`go.mod`
+   - Java：`pom.xml` 或 `build.gradle` / `build.gradle.kts`
+
+可选：前端目录同理（`package.json` + 常见前端脚手架特征），请在上方 `web_dirs/app_dirs` 写死路径。
+
+## 1.1) 接口清单来源（强烈建议）
+
+为保证自动化测试覆盖“全部已实现接口”且可复现，优先使用 OpenAPI 作为接口清单真值来源。
+
+请在上方 `0) 项目配置` 填写：
+- `openapi_path`：固定路径（推荐 `docs/openapi.json`）
+- `openapi_url`：服务运行时导出 OpenAPI 的 URL（缺省时 runner 会按常见路径尝试 `/openapi.json`、`/v3/api-docs`、`/swagger.json` 等）
+
+如 OpenAPI/Knife4j 受 basic/bearer 保护，可在 `secrets/test-accounts.json` 配置 `openapi_auth`（支持 headers/basic/bearer；未填则沿用 API 鉴权）。
+
+规则：
+1) 若 `docs/openapi.json` 存在，则以其生成接口清单（优先级最高）
+2) 否则尝试通过 `openapi_url` 从运行中的服务导出并写入 `docs/openapi.json`
+3) 若仍不可用，才降级到路由导出/代码扫描（兜底）
+
+## 2) 服务启动与构建（可覆盖）
+
+默认策略：
+- Rust：`cargo build`，启动 `cargo run` 或 `./target/<bin>`
+- Go：`go test ./...`，启动 `go run ./cmd/<app>`（按项目调整）
+- Java：`./mvnw -q -DskipTests package`，启动 `java -jar target/*.jar`
+
+如果你的项目不是上述结构，请在上方 `0) 项目配置` 写死命令（推荐）：
+- `build_cmd` / `start_cmd` / `stop_cmd`（用于 runner 的 `--manage-service`）
+
+占位符：
+- `{service_dir}`：服务目录的绝对路径
+- `{service}`：服务目录名（Path.name）
+
+## 2.1) Git / Submodule 提交（可选）
+
+如果你的工作区使用 git submodule 管控后端/前端目录，建议把 server 目录固定写入 `server_dirs`，并把“提交动作”独立出来：
+- 先 `/server-test-plan` → `/server-test` 跑到验收通过
+- 再 `/server-commit` 对 `server_dirs` 指定的 submodule 做 commit，并在工作区根仓库提交 submodule 指针更新
+
+建议 commit message 保持通用简洁（Conventional Commits 风格），例如：
+- `fix(api): ...`
+- `chore(server): api test fixes`
+- `chore(workspace): bump server submodules`
+
+## 3) 测试入口
+
+默认：
+- BASE_URL: `http://127.0.0.1:8080`
+- HEALTH_PATH: `/health`（或 Spring Boot `/actuator/health`）
+
+请在上方 `0) 项目配置` 覆盖：
+- `base_url` / `health_path` / `log_path`
+
+## 3.2) web/app 的测试命令（可选但推荐）
+
+为了让“需求→实现→测试→提交”闭环在多子项目工作区中可自动执行，建议在上方 `0) 项目配置` 写死：
+- `web_test_cmd` / `web_build_cmd`
+- `app_test_cmd` / `app_build_cmd`
+
+占位符：
+- `{web_dir}`：web 目录的绝对路径
+- `{app_dir}`：app 目录的绝对路径
+
+## 3.3) 工具链与版本（强烈建议）
+
+为减少“在新机器上验证半天”的情况，建议在上方 `0) 项目配置` 显式声明语言工具链版本与切换方式：
+- `node_version` / `node_use_cmd`
+- `java_version` / `java_use_cmd`
+- `python_version` / `python_use_cmd`
+
+## 3.0) Policy（默认安全边界）
+
+为让自动化测试“开箱即用且不越界”，建议统一用 policy 字段作为硬边界（runner 与 hooks 会读取）。推荐默认值：
+- `environment: "test"`
+- `base_url_allowlist`：默认仅允许 localhost（防止误打到生产）
+- `dangerous_disabled: true`：默认禁用危险接口（除非 REQUIREMENTS 明确允许）
+- `max_requests_per_minute: 60`：默认节流，避免压垮测试环境
+
+## 3.1) 环境声明（强烈建议）
+
+建议在上方 `0) 项目配置` 明确声明当前是测试环境，并写清允许的测试边界：
+- `environment: "test"`
+- `allow_mutations: true`
+- `auto_commit: true`（可选：仅在 test 环境允许自动提交）
+
+## 4) 鉴权与测试账号
+
+测试账号与鉴权信息放在（固定位置）：
+- `secrets/test-accounts.json`
+
+规则：
+- 该文件不应提交到 git
+- AI 不应在输出中打印其中的敏感字段
+
+推荐格式（节选）：
+- 若已有 token：在 `auth.headers` 填入固定 header（例如 `Authorization: Bearer ...`）
+- 若只有账号密码：填写 `accounts[0].username/password`，并在 `auth` 中指定登录方式（例如 `auth.type=login` + `login_path/token_json_path`）；runner 会先登录再带 token 跑接口
+
+## 5) Request-ID / Trace-ID 约定（强烈建议）
+
+为便于自动化测试将“单次请求”与“服务端日志”稳定关联，建议统一以下约定：
+
+- 请求 Header：`X-Request-Id`
+  - 测试端每次请求都生成一个新的 `X-Request-Id`（例如时间戳/uuid）
+  - 服务端若收到该 header，必须原样透传到响应 header（同名）
+  - 服务端若未收到该 header，必须生成一个，并写入响应 header
+- 日志字段：服务端日志必须包含 `request_id=<id>`（或等价字段，但需在此文件中固定）
+
+说明：
+- 自动化测试默认会在请求中携带 `X-Request-Id`，并以该值作为日志 grep 的主键（比时间窗更可靠）。
+- 如果你的服务使用 `traceparent`（W3C Trace Context）也可以，但仍建议保留 `X-Request-Id` 作为最低公约数。
+
+## 6) Runner 约定（推荐）
+
+如果测试机安装了 `uv`，推荐在工作区根目录放置 `tools/server_test_runner.py`（来自本仓库模板），用于：
+- 从 OpenAPI 生成/更新 `issues/server-api-issues.csv`
+- 执行请求并按 `X-Request-Id` 关联日志
+
+如希望 runner 自动执行 build/start/stop，请使用：
+```bash
+uv run tools/server_test_runner.py --workspace . --manage-service
+```
+
+<!-- AIWS_MANAGED_END:ai-workspace:core -->

package/templates/workspace/REQUIREMENTS.md

@@ -0,0 +1,94 @@
+# REQUIREMENTS.md（需求与验收标准）
+
+<!-- AIWS_MANAGED_BEGIN:requirements:contract -->
+本文件是工作区需求的唯一真值来源。AI 在制定计划与执行测试时必须以此为准。
+
+约束：
+- 不写入任何 secrets（token、账号、内网端点等）
+- `aiws update` 只维护本托管块；其余内容由项目自由编辑
+
+相关合同：
+- `requirements/requirements-issues.csv`：需求拆解执行合同（校验：`python3 tools/requirements_contract.py validate`）
+<!-- AIWS_MANAGED_END:requirements:contract -->
+
+## 需求概述
+
+- 背景：
+- 目标：
+- 非目标：
+
+## 业务链路（简短逻辑图输入，建议填写）
+
+为降低“每次让 AI 重新理解系统”的 token 消耗，并让自动化测试能按业务链路组合执行，建议维护一份**机器可读**的 FlowSpec。
+
+说明：
+- 该 FlowSpec 用于自动生成 `docs/api-flow.mmd`（简短逻辑图）与 `issues/server-scenario-issues.csv`（场景执行合同）。
+- 每次需求变更（例如运行 `/ws-req-change`）后，都应重新生成一次（不会修改 secrets）。
+
+<!-- FLOW_SPEC_BEGIN -->
+```json
+{
+  "flows": [
+    {
+      "id": "auth_login",
+      "title": "登录并获取身份",
+      "steps": [
+        { "name": "login", "method": "POST", "path": "/api/login" },
+        { "name": "me", "method": "GET", "path": "/api/me" }
+      ],
+      "notes": "尽量使用无副作用接口；需要资源 id 的步骤请配合 secrets/test-accounts.json:test_resource_ids"
+    }
+  ]
+}
+```
+<!-- FLOW_SPEC_END -->
+
+## 变更记录
+
+进行中的需求变更请使用独立变更日志（避免在本文件里堆历史）：
+- `requirements/CHANGELOG.md`
+
+## 接口需求（按需填写）
+
+建议按接口列出：
+- 名称：
+- Method + Path：
+- 鉴权要求（header/cookie/none）：
+- 请求示例：
+- 响应示例：
+- 错误码/边界条件：
+
+## 验收标准（必须可验证）
+
+- 代码：编译/构建无报错
+- 功能：需求覆盖完整（按接口清单逐项通过）
+- 日志：关键请求路径无异常（ERROR/Exception/Stacktrace）或已确认可接受
+
+## 自动化测试闭环（建议）
+
+为减少“下一步操作”式的人工介入，建议把自动化测试的产物与边界固化为执行合同：
+- `docs/openapi.json`：接口清单真值来源（优先）
+- `issues/server-api-issues.csv`：每个 endpoint 的验收字段与状态机（TODO/DOING/DONE/BLOCKED/SKIP）
+- `issues/server-fix-issues.csv`：当出现 BLOCKED 时自动生成的“下一步修复清单”（用于持续闭环；包含 Failure_Category/Failure_Analysis/Suggestion）
+- `issues/server-triage-issues.csv`：当 runner 无法稳定归因/需要人工判断时生成的“人工介入清单”（避免把噪声混进 fix issues）
+- `.agentdocs/tmp/server-test/`：响应与日志片段（不入库）
+
+当出现 BLOCKED：
+- 若属于业务/需求不清：先补齐本文件对应接口的期望，再改代码
+- 若属于代码/配置错误：修复后只重测失败项（runner 会跳过 DONE/SKIP）
+
+## 接口清单真值（推荐）
+
+- OpenAPI：以 `docs/openapi.json` 为接口清单真值来源
+- 若 OpenAPI 缺失：在本次任务中补齐导出方式（生成到 `docs/openapi.json`），否则自动化测试只能做“尽力覆盖”
+
+## 测试环境与副作用边界（强烈建议填写）
+
+- 环境：test / staging / prod（推荐写 `test`）
+- 是否允许测试有副作用接口（POST/PUT/DELETE）：是/否
+- 如允许：是否要求测试数据隔离/幂等（例如使用测试账号、固定测试数据、或每次清理）
+
+## Request-ID / Trace-ID 验收（推荐）
+
+- 服务端支持并回传 `X-Request-Id` 响应头（与请求一致或自动生成）
+- 服务端日志包含 `request_id=<id>`，便于按请求定位错误