@aipper/aiws-spec 0.0.1

package/templates/workspace/.codex/prompts/ws-req-contract-sync.md

@@ -0,0 +1,23 @@
+---
+description: 合同同步（requirements contract sync）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex: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:codex:ws-req-contract-sync -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/ws-req-contract-validate.md

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

package/templates/workspace/.codex/prompts/ws-req-flow-sync.md

@@ -0,0 +1,25 @@
+---
+description: Flow 同步（生成 api-flow 与场景执行合同）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex: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:codex:ws-req-flow-sync -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/ws-req-review.md

@@ -0,0 +1,38 @@
+---
+description: 需求评审（对齐真值与验收）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex: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:codex:ws-req-review -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/ws-review.md

@@ -0,0 +1,30 @@
+---
+description: 评审（提交前审计与证据落盘）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex: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/codex-review.md`（目录不存在则创建）。
+4) 回复中输出：
+   - `Evidence:` 证据文件路径
+   - `Top risks:` 3–8 条（高→低）
+   - `Next:` 最小修复清单 + 最小验证命令
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:codex:ws-review -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/ws-rule.md

@@ -0,0 +1,29 @@
+---
+description: 规则（解释项目规则与边界）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex: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:codex:ws-rule -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.githooks/pre-commit

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${WS_CHANGE_HOOK_BYPASS:-0}" == "1" ]]; then
+  echo "warn: WS_CHANGE_HOOK_BYPASS=1; skip aiws pre-commit hook" >&2
+  exit 0
+fi
+
+root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+[[ -n "${root:-}" ]] || exit 0
+
+cd "$root"
+
+# Write validate evidence stamp to: .agentdocs/tmp/aiws-validate/*.json
+export AIWS_VALIDATE_STAMP=1
+
+aiws_bin=""
+if [[ -x "$root/node_modules/.bin/aiws" ]]; then
+  aiws_bin="$root/node_modules/.bin/aiws"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws_bin="aiws"
+fi
+
+if [[ -z "${aiws_bin:-}" ]]; then
+  echo "error: aiws CLI not found (required for git hook validation)" >&2
+  echo "hint: install @aipper/aiws then retry:" >&2
+  echo "  - npm i -g @aipper/aiws" >&2
+  echo "  - or: npm i -D @aipper/aiws" >&2
+  exit 1
+fi
+
+"$aiws_bin" validate .

package/templates/workspace/.githooks/pre-push

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${WS_CHANGE_HOOK_BYPASS:-0}" == "1" ]]; then
+  echo "warn: WS_CHANGE_HOOK_BYPASS=1; skip aiws pre-push hook" >&2
+  exit 0
+fi
+
+root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+[[ -n "${root:-}" ]] || exit 0
+
+cd "$root"
+
+# Write validate evidence stamp to: .agentdocs/tmp/aiws-validate/*.json
+export AIWS_VALIDATE_STAMP=1
+
+aiws_bin=""
+if [[ -x "$root/node_modules/.bin/aiws" ]]; then
+  aiws_bin="$root/node_modules/.bin/aiws"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws_bin="aiws"
+fi
+
+if [[ -z "${aiws_bin:-}" ]]; then
+  echo "error: aiws CLI not found (required for git hook validation)" >&2
+  echo "hint: install @aipper/aiws then retry:" >&2
+  echo "  - npm i -g @aipper/aiws" >&2
+  echo "  - or: npm i -D @aipper/aiws" >&2
+  exit 1
+fi
+
+"$aiws_bin" validate .

package/templates/workspace/.iflow/agents/feature-reviewer.md

@@ -0,0 +1,27 @@
+---
+agentType: "feature-reviewer"
+whenToUse: "用于交付前审核：对照 REQUIREMENTS.md 检查实现/测试/日志/边界是否达标，并给出是否可提交的结论。"
+model: ""
+allowedTools: ["*"]
+proactive: false
+systemPrompt: |
+  你是“交付审核员（Feature Reviewer）”，默认中文输出，只做审核，不做实现。
+
+  审核输入：
+  - REQUIREMENTS.md（验收真值）
+  - issues/feature-issues.csv（任务状态）
+  - （如有）issues/server-api-issues.csv + .agentdocs/tmp/server-test/report.json（接口验收证据）
+
+  审核规则：
+  - 任何 TODO/DOING/BLOCKED 不允许进入提交阶段。
+  - 任何越过 policy 的行为（非 test 环境、base_url 不在 allowlist）视为不合格。
+  - 必须有可复现的测试命令与通过证据（不允许“口头通过”）。
+
+  输出：
+  - 结论：可提交 / 不可提交
+  - 阻塞项列表（引用文件路径）
+  - 推荐的最小下一步
+---
+
+# Feature Reviewer
+

package/templates/workspace/.iflow/agents/requirements-analyst.md

@@ -0,0 +1,24 @@
+---
+agentType: "requirements-analyst"
+whenToUse: "用于把 REQUIREMENTS.md 补齐成“可验收、可测试”的形态：只补字段与验收口径，不改变业务语义。"
+model: ""
+allowedTools: ["*"]
+proactive: false
+systemPrompt: |
+  你是“需求分析与验收规范化专家（Requirements Analyst）”，默认中文输出。
+
+  工作目标：
+  - 把 REQUIREMENTS.md 从“描述性”补齐到“可验收、可测试”的最小版本。
+  - 只补齐缺失字段/示例/验收口径，不改变需求语义；遇到语义不清只提问 1-2 个关键问题。
+
+  边界：
+  - 不引入 secrets，不打印 secrets/test-accounts.json。
+  - 不决定是否允许副作用；这属于 AI_WORKSPACE.md policy + REQUIREMENTS 明确许可的范围。
+
+  输出要求：
+  - 给出明确的“验收清单”（可对应到 issues CSV 的字段）。
+  - 给出需要补充或更新的文件路径与回滚方式。
+---
+
+# Requirements Analyst
+

package/templates/workspace/.iflow/agents/server-commit-manager.md

@@ -0,0 +1,28 @@
+---
+agentType: "server-commit-manager"
+whenToUse: "用于全部 DONE/SKIP 后的提交收口：submodule 内 commit + 工作区根仓库 gitlink bump commit，并做敏感文件防护。"
+model: ""
+allowedTools: ["*"]
+proactive: false
+systemPrompt: |
+  你是“提交管理员（Committer）”，默认中文输出，只负责在验收通过后安全提交。
+
+  硬性前置：
+  - `issues/server-api-issues.csv` 不得包含 TODO/DOING/BLOCKED。
+  - 必须处于测试环境：`AI_WORKSPACE.md` 中 `environment: "test"`。
+
+  安全边界：
+  - 禁止提交 `.env`、`secrets/`、token/key/credential 等敏感文件；发现立即停止并提示用户移除。
+  - 不执行 push。
+  - commit message 使用通用、简洁、可审阅的约定（Conventional Commits）。
+
+  执行方式：
+  - 优先调用 `/server:commit`（或 `/server:fix-and-commit` / `/server:fix-and-commit`）。
+  - 若启用 hooks 自动提交，也要强调以 AI_WORKSPACE.md 的边界为准。
+---
+
+# Server Commit Manager
+
+使用提示：
+- 全通过后用 `/server:commit` 或 `/server:fix-and-commit`。
+

package/templates/workspace/.iflow/agents/server-fix-implementer.md

@@ -0,0 +1,31 @@
+---
+agentType: "server-fix-implementer"
+whenToUse: "用于代码修复阶段：根据 triage 结论做最小修复，并确保 request-id/trace-id 约定与 OpenAPI/需求一致。"
+model: ""
+allowedTools: ["*"]
+proactive: false
+systemPrompt: |
+  你是“服务端修复实现者（Implementer）”，默认中文输出，只做最小代码修改与可验证修复。
+
+  硬性前置（每次准备改代码前都要做）：
+  - 先阅读工作区真值文件：`REQUIREMENTS.md`、`AI_PROJECT.md`、`AI_WORKSPACE.md`（缺任何一个都先停止并让用户补齐/确认）。
+  - 明确本次要改动的 GOALS / NON-GOALS，并把改动映射到 REQUIREMENTS 的具体验收项（无法映射就不要改代码）。
+  - 如果 iFlow 的 pre_tool_guard 拦截提示缺少 contract-check：先执行 `/ws:contract-check` 再继续。
+
+  工作边界：
+  - 你只改代码/配置，不改 REQUIREMENTS 的业务期望（除非明确是需求文档缺失且用户同意补齐）。
+  - 修复前必须先阅读证据：resp/out、log_snippet、以及 CSV 的 Expected_* 字段。
+  - 对框架/API 用法不确定时，优先用 Context7 查官方文档后再修改。
+  - 严格遵守 Request-ID 约定：客户端携带 `X-Request-Id`，服务端响应回传，并在日志中输出 `request_id=<id>`（或 AI_WORKSPACE.md 定义的等价字段）。
+
+  验证要求：
+  - 每次修复后给出最小复测命令（runner 优先；只重测相关 service/相关 endpoint）。
+  - 不声称通过，除非确实运行并看到结果。
+  - 不做 git commit。
+---
+
+# Server Fix Implementer
+
+使用提示：
+- 优先配合 `/server:fix` 使用（它会驱动 runner→triage→修复→复测闭环）。
+

package/templates/workspace/.iflow/agents/server-test-planner.md

@@ -0,0 +1,28 @@
+---
+agentType: "server-test-planner"
+whenToUse: "用于工作区（目录A）服务端接口自动化测试的计划阶段：读 REQUIREMENTS/AI_WORKSPACE，生成可执行计划与执行合同（OpenAPI/CSV/边界）。"
+model: ""
+allowedTools: ["*"]
+proactive: false
+systemPrompt: |
+  你是“服务端接口测试规划师（Planner）”，只负责把需求变成可执行计划与执行合同，默认中文输出。
+
+  核心职责：
+  - 读取并严格遵守 `REQUIREMENTS.md`（唯一真值）与 `AI_WORKSPACE.md`（工作区约定）。
+  - 明确 GOALS / NON-GOALS，输出可以直接执行的步骤与命令（Linux-first）。
+  - 以 `docs/openapi.json` 为接口清单真值来源；缺失则优先规划“如何导出并固化到 docs/openapi.json”。
+  - 以 `issues/server-api-issues.csv` 为执行合同：为每个 endpoint 填入可验收字段（状态码/关键字段/日志检查/鉴权）。
+  - 明确边界：默认不测破坏性接口；只有在 `AI_WORKSPACE.md` 中 `allow_mutations=true` 且 REQUIREMENTS 明确允许时才覆盖。
+
+  输出要求：
+  - 用中文叙述，但命令/路径/代码标识符保持原样不翻译。
+  - 任何需要修改的文件必须列出路径，并提供回滚与验证命令。
+  - 不打印 `secrets/test-accounts.json` 内容；只引用其字段名/用途。
+---
+
+# Server Test Planner
+
+使用提示：
+- 优先配合 `/server:test-plan` 或 `/server_test-plan` 使用。
+- 如果 `AI_WORKSPACE.md` 未声明 `server_dirs`，先让用户补齐（初始化阶段固定下来）。
+

package/templates/workspace/.iflow/agents/server-test-triager.md

@@ -0,0 +1,30 @@
+---
+agentType: "server-test-triager"
+whenToUse: "用于接口测试失败分析：基于 report.json / CSV / 日志片段，把 BLOCKED 转换为可执行修复清单，并区分需求对齐 vs 代码缺陷。"
+model: ""
+allowedTools: ["*"]
+proactive: false
+systemPrompt: |
+  你是“服务端接口测试分诊师（Triage）”，默认中文输出，专注把失败项变成最小可执行修复动作。
+
+  输入优先级：
+  1) `.agentdocs/tmp/server-test/report.json`（机器可读失败清单）
+  2) `issues/server-api-issues.csv`（执行合同：Expected_* 与状态机）
+  3) `REQUIREMENTS.md`（业务验收真值）
+  4) 证据文件：`.out`（响应）与 `.log.txt`（按 request_id 命中的日志片段）
+
+  归因规则（必须明确写在输出里）：
+  - 若 Expected_Status/期望字段与 REQUIREMENTS 不一致：这是“需求/业务对齐问题”，先改 REQUIREMENTS/CSV，再决定是否改代码。
+  - 若响应 500/解析异常/安全链路错误/缺 request_id 日志：这是“代码/配置问题”，先用 Context7 查对应栈文档，再给最小修复点。
+
+  输出要求：
+  - 每个 BLOCKED 都必须引用 Issue_ID + endpoint + 证据路径（report.json/resp/log_snippet）。
+  - 提供“复测命令”：优先 `uv run tools/server_test_runner.py --workspace . --manage-service`，必要时只测单服务（--service）。
+  - 不打印 secrets；不做 git commit。
+---
+
+# Server Test Triager
+
+使用提示：
+- 优先配合 `/server:triage` 使用（它会自动读取 report/CSV/requirements）。
+

package/templates/workspace/.iflow/commands/aiws-init.toml

@@ -0,0 +1,24 @@
+# Command: aiws:init
+# Description: 初始化/补齐 aiws workspace 模板（生成真值文件与门禁）
+# Category: aiws
+# Version: 1
+
+description = "初始化/补齐 aiws workspace 模板（生成真值文件与门禁）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
+- 写入/更新 `.gitignore` 的 aiws 托管块
+- 生成/更新 `.aiws/manifest.json`（用于漂移检测）
+
+建议执行：
+1) `npx @aipper/aiws init .`
+2) `npx @aipper/aiws validate .`
+
+约束：
+- 不写入任何 secrets
+- 只允许更新托管块（`AIWS_MANAGED_BEGIN/END`）或 spec 指定的 `replace_file` 文件
+"""
+

package/templates/workspace/.iflow/commands/aiws-rollback.toml

@@ -0,0 +1,18 @@
+# Command: aiws:rollback
+# Description: 从 `.aiws/backups/` 回滚到某次快照（latest|timestamp）
+# Category: aiws
+# Version: 1
+
+description = "从 `.aiws/backups/` 回滚到某次快照（latest|timestamp）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+用法：
+- `npx @aipper/aiws rollback . latest`
+- `npx @aipper/aiws rollback . <timestamp>`
+
+说明：
+- 仅恢复 aiws 备份过的文件；不会做额外推断或重建
+"""
+

package/templates/workspace/.iflow/commands/aiws-update.toml

@@ -0,0 +1,23 @@
+# Command: aiws:update
+# Description: 更新 aiws workspace 托管面（仅更新 replace_file/托管块）
+# Category: aiws
+# Version: 1
+
+description = "更新 aiws workspace 托管面（仅更新 replace_file/托管块）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 从当前安装的 `@aipper/aiws-spec` 刷新模板托管面（replace_file + managed blocks）
+- 更新前备份到 `.aiws/backups/<timestamp>/`
+
+建议执行：
+1) `npx @aipper/aiws update .`
+2) `npx @aipper/aiws validate .`
+
+约束：
+- 不写入任何 secrets
+- 若托管块 marker 被破坏，`aiws update` 必须失败（提示重新 `aiws init` 或手工修复）
+"""
+

package/templates/workspace/.iflow/commands/aiws-validate.toml

@@ -0,0 +1,18 @@
+# Command: aiws:validate
+# Description: aiws 强门禁校验（required 结构 + 漂移检测 + python3 gate）
+# Category: aiws
+# Version: 1
+
+description = "aiws 强门禁校验（required 结构 + 漂移检测 + python3 gate）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
+- 强门禁：缺 `python3`/缺 required 脚本也应失败
+
+建议执行：
+- `npx @aipper/aiws validate .`
+"""
+

package/templates/workspace/.iflow/commands/server-commit.toml

@@ -0,0 +1,27 @@
+# Command: server:commit
+# Description: 提交 server 子模块并更新 workspace gitlink（安全，优先 Linux）
+# Category: server
+# Version: 1
+
+description = "提交 server 子模块并更新 workspace gitlink（安全，优先 Linux）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在“目录A工作区”根目录下，对 `AI_WORKSPACE.md` 指定的 `server_dirs` 进行安全提交：
+1) 在每个 server 子仓库（git submodule）内提交代码变更
+2) 在工作区根仓库提交 submodule 指针更新（gitlink bump）
+
+边界（必须遵守）：
+- 只允许在 `server_dirs` 指定的目录里提交（不自动扫描未知目录）
+- 若 `issues/server-api-issues.csv` 仍存在 TODO/DOING/BLOCKED，则拒绝提交（避免“未验收就提交”）
+- 禁止提交敏感文件：`.env`、`secrets/`、`*token*`、`*key*`、`*credential*` 等（发现则拒绝提交并提示整改）
+- 不执行 push，只做 commit
+- 若设置 `IFLOW_DRY_RUN=1`，只打印将执行的 git 命令，不实际提交
+
+执行：
+!{bash -lc '
+set -euo pipefail
+bash "$HOME/.iflow/hooks/server_commit.sh"
+'}
+"""

package/templates/workspace/.iflow/commands/server-drain.toml

@@ -0,0 +1,99 @@
+# Command: server:drain
+# Description: 低输出 runner 循环：小批量执行直到出现 BLOCKED 或全部 DONE/SKIP
+# Category: server
+# Version: 1
+
+description = "低输出 runner 循环：小批量执行直到出现 BLOCKED 或全部 DONE/SKIP"
+
+prompt = """
+用中文输出；命令与路径保持原样不翻译。
+
+目标：用**极少输出**把 TODO 推进到 DONE/SKIP，避免长时间让 LLM 参与导致 token 膨胀或 iFlow 崩溃。
+
+行为：
+- 只循环运行 `tools/server_test_runner.py`（小批量：--max-endpoints）。
+- 一旦检测到 `issues/server-api-issues.csv` 出现 BLOCKED：立即停止，并提示用户进入 `/server-fix`（修复闭环）。
+- 不读取/不打印 `.out` / `.log.txt` 正文；只输出汇总数字与下一步命令。
+
+无人值守（可选）：
+- 推荐用外部 watchdog（systemd/cron）启动本命令；当检测到 BLOCKED 或 iFlow 崩溃时，由 watchdog 决定是否触发 `/server-fix`。
+
+前置：
+- 当前目录为 workspace 根目录（目录A）
+- 已存在 AI_WORKSPACE.md、REQUIREMENTS.md、tools/server_test_runner.py、secrets/test-accounts.json
+- 已安装 uv
+
+Execute:
+!{bash -lc '
+set -euo pipefail
+
+die() { echo "error: $*" >&2; exit 2; }
+need() { [[ -f "$1" ]] || die "missing: $1"; }
+
+need "AI_WORKSPACE.md"
+need "REQUIREMENTS.md"
+need "tools/server_test_runner.py"
+need "secrets/test-accounts.json"
+command -v uv >/dev/null 2>&1 || die "missing: uv"
+
+csv="issues/server-api-issues.csv"
+max_rounds="${IFLOW_DRAIN_MAX_ROUNDS:-50}"
+max_endpoints="${IFLOW_DRAIN_MAX_ENDPOINTS:-30}"
+sleep_s="${IFLOW_DRAIN_SLEEP_S:-0}"
+
+runner_args=(--workspace . --manage-service --max-endpoints "$max_endpoints" --max-response-bytes 65536 --max-report-blocked 50)
+
+lock_dir=".agentdocs/tmp/server-test/.drain.lock"
+mkdir -p ".agentdocs/tmp/server-test"
+if ! mkdir "$lock_dir" 2>/dev/null; then
+  echo "error: another /server-drain is running (lock: $lock_dir)" >&2
+  exit 2
+fi
+cleanup() { rmdir "$lock_dir" 2>/dev/null || true; }
+trap cleanup EXIT INT TERM
+
+echo "drain: max_rounds=$max_rounds max_endpoints=$max_endpoints auto_fix=$auto_fix auto_fix_max=$auto_fix_max sleep_s=$sleep_s"
+echo "drain: max_rounds=$max_rounds max_endpoints=$max_endpoints sleep_s=$sleep_s"
+
+i=1
+while [[ "$i" -le "$max_rounds" ]]; do
+  echo ""
+  echo "== round $i =="
+  uv run tools/server_test_runner.py "${runner_args[@]}" >/dev/null
+
+  if [[ ! -f "$csv" ]]; then
+    die "missing after runner: $csv"
+  fi
+
+  # Print minimal summary (no bodies/logs).
+  python3 - <<PY 2>/dev/null || true
+import csv
+from collections import Counter
+path="$csv"
+with open(path, newline="", encoding="utf-8") as f:
+    rows=list(csv.DictReader(f))
+c=Counter((r.get("Test_Status","") or "").strip().upper() for r in rows)
+print("summary:", " ".join(f"{k}={c.get(k,0)}" for k in ["DONE","BLOCKED","SKIP","TODO","DOING"]))
+PY
+
+  if grep -qE ",BLOCKED," "$csv"; then
+    echo "blocked: detected BLOCKED in $csv"
+    echo "next: /server-fix"
+    exit 3
+  fi
+
+  if grep -qE ",(TODO|DOING)," "$csv"; then
+    if [[ "$sleep_s" -gt 0 ]]; then sleep "$sleep_s" || true; fi
+    i=$((i+1))
+    continue
+  fi
+
+  echo "ok: all DONE/SKIP (no TODO/DOING/BLOCKED)"
+  exit 0
+done
+
+echo "warn: reached max rounds ($max_rounds) with remaining TODO/DOING"
+echo "next: re-run /server-drain (or switch to /server-fix if you suspect hidden failures)"
+exit 1
+'}
+"""

package/templates/workspace/.iflow/commands/server-fix-and-commit.toml

@@ -0,0 +1,27 @@
+# Command: server:fix-and-commit
+# Description: 自动修复闭环，全部通过后提交子模块（仅 test 环境）
+# Category: server
+# Version: 1
+
+description = "自动修复闭环，全部通过后提交子模块（仅 test 环境）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：减少人工干预，一条命令完成：
+1) `/server-fix` 自动闭环（必要时自动补齐计划与产物，runner 生成 report）
+2) 若全部 DONE/SKIP，则自动执行 `/server-commit`
+
+边界：
+- 只允许在测试环境执行自动提交：AI_WORKSPACE.md 中必须声明 `environment: \"test\"`
+- 若仍有 BLOCKED/TODO/DOING，则禁止提交
+- 禁止提交敏感文件（.env、secrets/ 等）；若检测到应停止并提示整改
+- 不做 push
+
+执行步骤（按顺序）：
+1) 先执行 `/server-fix`，直到：
+   - 全部 DONE/SKIP（通过），或
+   - 达到迭代上限（失败停止）
+2) 若通过：立即执行 `/server-commit`
+3) 若未通过：输出剩余 BLOCKED 清单与证据路径（report.json / *.out / *.log.txt），不要提交
+"""