@aipper/aiws-spec 0.0.1

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

@@ -0,0 +1,65 @@
+# Command: server:fix
+# Description: 自动修复闭环：分诊 -> 最小修复 -> 复测直到 DONE/SKIP
+# Category: server
+# Version: 1
+
+description = "自动修复闭环：分诊 -> 最小修复 -> 复测直到 DONE/SKIP"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在测试环境（AI_WORKSPACE.md: environment=test）中，针对“单服务”为主的工作区，自动进入闭环：
+（计划）->（执行测试）->（更新 issues CSV + 证据）->（定位）->（修复）->（复测），直到验收通过或达到迭代上限。
+
+自动化（减少人工干预）：
+- 不要求先手动执行 `/server-test-plan`：如果检测到“计划/执行合同产物缺失”，本命令会先按 `/server-test-plan` 的规则自动补齐计划与产物，再进入闭环。
+
+前置（必须满足）：
+- 当前目录为工作区根目录（目录A）
+- 已存在 AI_WORKSPACE.md、REQUIREMENTS.md
+- 已存在 tools/server_test_runner.py（uv 可用）
+- 已存在 secrets/test-accounts.json（敏感，不展示内容）
+
+你日常只需要关注的产物（其余可忽略）：
+- `issues/server-fix-issues.csv`：修复清单（runner 自动生成/更新，包含证据与建议）
+- `issues/server-triage-issues.csv`：需要人工介入的条目（证据不足/需业务判断/日志缺 request_id 等）
+- `.agentdocs/tmp/server-test/report.{json,md}`：证据包与汇总
+
+说明（避免混乱）：
+- `issues/server-api-issues.csv` 是 runner 的“执行合同/端点账本”，用于记录每个 endpoint 的状态机与期望字段，便于跳过 DONE、聚焦 BLOCKED；你不需要手工维护它。
+- 如你希望尽量减少 LLM 参与、降低 token：可先运行 `/server-drain` 把 TODO 推进到 DONE/SKIP，遇到 BLOCKED 再进入本命令。
+
+闭环策略（必须按此执行）：
+0) 计划/执行合同预检（若缺失则先补齐）：
+   - 若 `issues/server-api-issues.csv` 不存在：先从 OpenAPI 生成（runner 会自动 upsert）
+   - 若 `.agentdocs/tmp/server-test/report.json` 不存在：先运行 runner 生成证据包
+   - 若 `docs/openapi.json` 不存在：优先通过 AI_WORKSPACE.md:openapi_url 从运行服务导出（runner 的 --refresh-openapi）
+   - 若 REQUIREMENTS.md 的接口需求未填：先把 REQUIREMENTS.md 补齐到“可验收”（否则修复会跑偏）
+1) 运行 runner（默认小批量，避免长时间运行导致上下文/输出膨胀；需要时重复运行多轮）：
+   - 单服务推荐默认：`uv run tools/server_test_runner.py --workspace . --manage-service --max-endpoints 30 --max-response-bytes 65536 --max-report-blocked 50`
+   - 若需要刷新 OpenAPI：在上述命令后追加 `--refresh-openapi`
+2) 只读取“摘要与清单”，不要读取大文件全文（防止 token 爆炸）：
+   - 先读 `.agentdocs/tmp/server-test/report.md`（摘要）
+   - 再读 `issues/server-fix-issues.csv` 与 `issues/server-triage-issues.csv`
+   - 只在需要时，按证据路径打开单个 `*.out` 或 `*.log.txt`（最多 1-2 个 BLOCKED）
+3) 若存在 BLOCKED：
+   a) 只处理 Top 3 BLOCKED：对每个 BLOCKED，按 Evidence 读取证据文件路径（resp=... / log_snippet=...），不要把文件内容整段贴回输出
+   b) 判断是“需求/业务对齐”还是“代码/配置问题”
+   c) 对代码/配置问题：先用 Context7 查对应栈（按 server_dir 检测：pom.xml/gradle/go.mod/Cargo.toml），再做最小修复
+   d) 单服务默认直接复测；多服务时只复测相关 service（设置 CSV 对应项为 TODO/BLOCKED 即可；runner 会跳过 DONE）
+4) 每轮最多修复 3 个 BLOCKED，最多迭代 5 轮；超出则停止并给出剩余问题清单与建议
+
+输出限制（防止 iFlow 崩溃）：
+- 每轮输出只包含：汇总数字 + Top 3 BLOCKED（Issue_ID/Method/Path/证据路径）+ 1-3 条下一步命令
+- 不要输出任何日志/响应正文；一律用文件路径引用
+
+边界：
+- 不做破坏性数据操作；除非 AI_WORKSPACE.md allow_mutations=true 且 REQUIREMENTS.md 明确允许
+- 不泄露 secrets
+- 不做 git commit（提交由 /server-commit 负责）
+- 反死循环：连续 2 轮 BLOCKED 数不下降时，必须缩小范围（只跑单 service/单 endpoint）或先修环境/先补齐 REQUIREMENTS，不能继续盲改
+
+当全部 DONE/SKIP：
+- 默认输出：可以执行 `/server-commit`
+- 若希望“一条命令自动提交”，使用 `/server-fix-and-commit`（仅限 environment=test）
+"""

package/templates/workspace/.iflow/commands/server-test-plan.toml

@@ -0,0 +1,62 @@
+# Command: server:test-plan
+# Description: 规划 workspace 级 server API 测试（发现服务目录、记录接口、生成 issues CSV）
+# Category: server
+# Version: 1
+
+description = "规划 workspace 级 server API 测试（发现服务目录、记录接口、生成 issues CSV）"
+
+prompt = """
+IMPORTANT:
+- Use Chinese for all narrative output (plans, explanations, headings).
+- Keep commands/paths/code identifiers in their original form.
+
+Create a concrete, executable plan to test server APIs in a workspace directory that may contain multiple projects (backend/frontend) with non-fixed names.
+
+First, read these workspace-standard files (if present in cwd):
+- AI_WORKSPACE.md (workspace discovery and run overrides)
+- REQUIREMENTS.md (single source of truth for requirements)
+If AI_WORKSPACE.md defines a Request-ID convention, follow it (default: X-Request-Id and log field request_id=<id>).
+If AI_WORKSPACE.md defines OpenAPI conventions, follow them (default: docs/openapi.json).
+
+Secrets:
+- If secrets/test-accounts.json exists, treat it as sensitive. Never print its contents.
+- Use it only to know headers/base_url/accounts for testing.
+
+Output format:
+1) GOALS / NON-GOALS (must match REQUIREMENTS.md)
+2) Discovery strategy:
+   - Identify server directories (non-fixed names) using AI_WORKSPACE.md server_dirs if provided,
+     else detect by markers: Cargo.toml (Rust), go.mod (Go), pom.xml/gradle (Java).
+   - For each server dir, detect build/test/start commands (prefer explicit overrides in AI_WORKSPACE.md).
+3) API inventory strategy (pick in order, per server):
+   - OpenAPI spec as source of truth:
+     - Prefer docs/openapi.json if present
+     - Else export from running server (AI_WORKSPACE.md openapi_url) into docs/openapi.json
+   - Runtime route dump endpoint if available (framework-specific)
+   - Code scan fallback (list routes from framework conventions)
+4) Artifacts (execution contract):
+   - docs/api.md: API document draft (method/path/auth/request/response/error)
+   - issues/server-api-issues.csv: rows for each endpoint with a state machine (no percentages)
+     Columns MUST include:
+       Issue_ID, Service, Title, Method, Path, Auth, Request_Example, Expected_Status,
+       Expected_Body_Checks, Log_Checks, Test_Status, Review_Status, Notes
+     Test_Status: TODO | DOING | DONE | BLOCKED | SKIP
+     Review_Status: PENDING | REVIEWING | APPROVED
+5) Execution loop:
+   - Build -> start (capture logs) -> wait health -> for each endpoint: request -> check response -> check logs -> update CSV
+   - If fail: smallest fix, implement, rerun only failing items
+   - Requests MUST include X-Request-Id; log checks should prefer grepping by that id (fallback to time-window grep)
+   - If tools/server_test_runner.py exists and uv is available, prefer using:
+     - uv run tools/server_test_runner.py --workspace .
+     - (optional) uv run tools/server_test_runner.py --workspace . --refresh-openapi
+     - (optional) uv run tools/server_test_runner.py --workspace . --manage-service
+6) Rollback plan (git restore / revert / stop processes)
+7) Verification commands + expected results
+
+Constraints:
+- Assume Linux. Avoid docker-compose (not used).
+- If AI_WORKSPACE.md declares environment=test and allow_mutations=true, you may include mutating endpoints in the plan,
+  but still require explicit coverage and expectations in REQUIREMENTS.md.
+- Otherwise, do not hit destructive endpoints unless explicitly allowed in REQUIREMENTS.md.
+- Ask 1-2 clarification questions only if required info is missing.
+"""

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

@@ -0,0 +1,58 @@
+# Command: server:test
+# Description: 执行 workspace 级 server API 测试循环（构建/运行/请求/日志/迭代）
+# Category: server
+# Version: 1
+
+description = "执行 workspace 级 server API 测试循环（构建/运行/请求/日志/迭代）"
+
+prompt = """
+IMPORTANT:
+- Use Chinese for all narrative output (status, summaries, next steps).
+- Keep commands/paths/code identifiers in their original form.
+
+Execute the workspace-level server API test loop in the current directory.
+
+Preflight (must do):
+- Read AI_WORKSPACE.md and REQUIREMENTS.md if present.
+- Ensure secrets/test-accounts.json exists; if missing, ask user to create it from ai-workspace/templates/secrets/test-accounts.example.json.
+- Never print secrets from secrets/test-accounts.json.
+ - Generate a per-request X-Request-Id and include it in every request; prefer correlating logs by request_id / X-Request-Id.
+
+Working dirs / artifacts:
+- Create .agentdocs/tmp/server-test/ for logs and outputs.
+- Maintain docs/api.md and issues/server-api-issues.csv as the execution contract.
+- Maintain issues/server-fix-issues.csv as the "next fix" list when any endpoint is BLOCKED.
+
+Steps:
+1) Discover server dirs (AI_WORKSPACE.md server_dirs or marker-based detection).
+   - If tools/server_test_runner.py exists, prefer using it (uv + python runner) to generate/update issues/server-api-issues.csv and execute requests.
+   - The runner will use docs/openapi.json as source of truth and enforce Expected_Status when present; keep Expected_Status aligned with OpenAPI/requirements.
+2) For each server:
+   a) Determine build/test/start commands (prefer explicit overrides).
+   b) Build and start in background, capturing stdout/stderr to .agentdocs/tmp/server-test/<service>.log
+   c) Wait for health endpoint (AI_WORKSPACE.md health_path + base_url; fallback /health).
+   d) Inventory endpoints (source of truth):
+      - Prefer docs/openapi.json if present
+      - Else export OpenAPI from running server (AI_WORKSPACE.md openapi_url) into docs/openapi.json
+      - Else fallback to route dump / code scan
+      Then ensure endpoints exist in issues/server-api-issues.csv (add missing rows).
+   e) For each endpoint row with Test_Status in TODO/BLOCKED:
+      - Set Test_Status=DOING
+      - Execute request (curl preferred; python3 httpx/requests acceptable if installed), always include X-Request-Id header
+      - Save response to .agentdocs/tmp/server-test/<service>__<endpoint-slug>.out
+      - Prefer grepping logs by request_id / X-Request-Id; fallback to ERROR|Exception|Stacktrace time-window grep; update Notes with evidence (no secrets)
+      - Mark DONE if passes, else BLOCKED
+   f) Stop the server cleanly (do not leave background processes).
+3) If anything is BLOCKED:
+   - Propose the smallest fix to satisfy REQUIREMENTS.md, implement it, and rerun ONLY blocked endpoints.
+   - Do not stop at "needs next step": keep the loop until all DONE/SKIP or you hit the iteration cap; keep issues/server-fix-issues.csv current.
+4) Finish when all endpoints are DONE/SKIP and build has no errors.
+
+Hard rules:
+- Linux-first commands.
+- If AI_WORKSPACE.md declares environment=test and allow_mutations=true, mutating endpoint tests are allowed,
+  but only for endpoints explicitly listed/required by REQUIREMENTS.md.
+- Otherwise, no destructive tests unless explicitly permitted.
+- No leaking of secrets or tokens.
+- Do not claim tests passed unless commands were executed and outputs observed.
+"""

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

@@ -0,0 +1,38 @@
+# Command: server:triage
+# Description: 基于 report.json + issues CSV 分诊失败项，给出与 REQUIREMENTS 对齐的修复建议
+# Category: server
+# Version: 1
+
+description = "基于 report.json + issues CSV 分诊失败项，给出与 REQUIREMENTS 对齐的修复建议"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：把“测试结果 → 可执行修复清单”自动化，减少人工判断。
+
+输入（在 cwd/workspace 根目录）：
+- AI_WORKSPACE.md（server_dirs、base_url、openapi 约定、Request-Id 约定）
+- REQUIREMENTS.md（唯一真值：业务边界/验收标准）
+- issues/server-api-issues.csv（执行合同）
+- issues/server-fix-issues.csv（runner 自动生成的“下一步修复清单”，用于聚焦 BLOCKED）
+- .agentdocs/tmp/server-test/report.json（runner 自动生成；若缺失，先运行 runner 生成）
+
+规则：
+- 不打印 secrets/test-accounts.json 内容
+- 若 report.json 不存在：直接运行
+  `uv run tools/server_test_runner.py --workspace . --manage-service`
+  再继续 triage
+- triage 结束时：必须确保 `issues/server-fix-issues.csv` 已更新（若缺失则重新运行 runner）
+- 将 BLOCKED 分成两类，并给出下一步：
+  A) 需求/业务对齐问题：Expected_Status/Expected_Body_Checks 与 REQUIREMENTS.md 不一致 → 先更新 REQUIREMENTS/CSV，再改代码
+  B) 代码/配置问题：500/解析异常/安全链路/日志缺 request_id 等 → 先用 Context7 查对应技术文档，再给最小修复点
+- 反死循环：若同一 BLOCKED 连续出现且证据不变，优先缩小范围（只跑单 service/单 endpoint）或先修环境/先补齐 REQUIREMENTS
+
+输出必须包含：
+1) 结论：当前是否可以进入提交阶段（是否全部 DONE/SKIP）
+2) BLOCKED Top 列表（按影响排序，引用 Issue_ID + endpoint + 证据文件路径，如 report.json / *.out / *.log.txt）
+3) 每个 BLOCKED 的“修复动作”：
+   - 需要改哪些文件（给相对路径）
+   - 建议如何验证（优先 rerun runner；必要时只跑对应 service）
+4) 若涉及请求日志关联：明确要求服务端输出 `request_id=<id>` 或按 AI_WORKSPACE.md 的约定
+"""

package/templates/workspace/.iflow/commands/server_test-plan.toml

@@ -0,0 +1,12 @@
+# Command: server_test-plan
+# Description: 与 /server-test-plan 等价的下划线别名
+# Category: server
+# Version: 1
+
+description = "与 /server-test-plan 等价的下划线别名"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+等价于 `/server-test-plan`：请按相同规则生成工作区后端接口测试计划（OpenAPI -> issues CSV -> 闭环执行）。
+"""

package/templates/workspace/.iflow/commands/server_test.toml

@@ -0,0 +1,12 @@
+# Command: server_test
+# Description: 与 /server-test 等价的下划线别名
+# Category: server
+# Version: 1
+
+description = "与 /server-test 等价的下划线别名"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+等价于 `/server-test`：请按相同规则在当前工作区执行接口测试闭环（runner 优先，BLOCKED 自动进入修复建议/闭环）。
+"""

package/templates/workspace/.iflow/commands/ws-analyze.toml

@@ -0,0 +1,33 @@
+# Command: ws:analyze
+# Description: AI Workspace 多模型技术分析（Claude + Codex + Gemini），证据落盘到 .agentdocs/tmp/analyze/
+# Category: workspace
+# Version: 1
+
+description = "AI Workspace 多模型技术分析（Claude + Codex + Gemini），证据落盘到 .agentdocs/tmp/analyze/"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在实现/修复前，对当前工作区做技术分析，形成可验证行动清单，并把结果落盘到 `.agentdocs/tmp/analyze/` 便于回放。
+
+输入：
+- 本命令参数（如有）视为分析主题（topic）。
+
+强制步骤：
+1) 预检：读取 `AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`。
+2) 若 iFlow 拦截写入：先执行 `/ws-contract-check`，再继续。
+3) 输出（必须）：
+   - GOALS / NON-GOALS（必须映射到 `REQUIREMENTS.md`）
+   - Top risks（3–8 条，按高→低）
+   - Next actions（最小可验证步骤清单；每步包含 Verify 命令与 Expected）
+4) 证据落盘（必须）：
+   - 在 `.agentdocs/tmp/analyze/` 写入一份 `analysis.<timestamp>.md`（或等价文件）
+   - 文件中必须包含：本次读取到的真值文件列表、以及上述输出
+5) 建议下一步（择一）：
+   - 进入交付闭环：`/ws-dev`
+   - 需求对齐：`/ws-req-review` 或 `/ws-req-change`
+
+边界：
+- 不打印任何 secrets（尤其是 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。
+"""

package/templates/workspace/.iflow/commands/ws-contract-check.toml

@@ -0,0 +1,69 @@
+# Command: ws:contract-check
+# Description: 在任何写入前确认已读取需求/规则（生成 stamp 供 pre_tool_guard 放行）
+# Category: workspace
+# Version: 1
+
+description = "在任何写入前确认已读取需求/规则（生成 stamp 供 pre_tool_guard 放行）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始任何代码/配置写入前，强制完成一次“工作区 contract 预检”，并写入 stamp 文件供 iFlow `pre_tool_guard.sh` 放行。
+
+执行（会检查/提示缺失项，并写入 `.agentdocs/tmp/.iflow-contract-checked`）：
+!{bash -lc '
+set -euo pipefail
+
+ws_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ws_root"
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "error: python3 not found (required for contract-check stamp)" >&2
+  exit 2
+fi
+
+mkdir -p .agentdocs/tmp
+
+python3 - <<'PY'
+import datetime
+import hashlib
+import json
+import os
+import pathlib
+
+ws_root = pathlib.Path(os.getcwd()).resolve()
+
+def sha256(p: pathlib.Path) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest()
+
+truth_files = {}
+missing = []
+for name in ("REQUIREMENTS.md", "AI_PROJECT.md", "AI_WORKSPACE.md"):
+    p = ws_root / name
+    key = f"{name}_sha256"
+    if p.exists():
+        truth_files[key] = sha256(p)
+    else:
+        truth_files[key] = ""
+        missing.append(name)
+
+data = {
+    "generated_at": datetime.datetime.utcnow().replace(microsecond=0).isoformat() + "Z",
+    "workspace_root": str(ws_root),
+    "truth_files": truth_files,
+}
+
+stamp = ws_root / ".agentdocs" / "tmp" / ".iflow-contract-checked"
+stamp.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+print(f"OK: wrote {stamp}")
+if missing:
+    print("WARN: missing truth files: " + ", ".join(missing))
+    print("HINT: run aiws init to bootstrap (e.g. `npx @aipper/aiws init .`)")
+PY
+'}
+
+边界：
+- 不打印任何 secrets（尤其是 `secrets/test-accounts.json`）。
+- 本命令只负责预检与写 stamp，不做实现、不跑测试、不提交。
+"""

package/templates/workspace/.iflow/commands/ws-dev.toml

@@ -0,0 +1,34 @@
+# Command: ws:dev
+# Description: AI Workspace Claude-first 开发闭环（分析→确认→实施→审计→证据落盘）
+# Category: workspace
+# Version: 1
+
+description = "AI Workspace Claude-first 开发闭环（分析→确认→实施→审计→证据落盘）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AI Workspace 约束下完成一个可回放、可验证的小步交付。
+
+输入：
+- 本命令参数（如有）视为本次交付主题（topic）。
+
+强制流程：
+1) 预检：读取 `AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`（缺失则先运行 `/aiws-init`，或在 shell 执行 `aiws init .`）。
+2) 若 iFlow 拦截写入（缺少 contract-check stamp）：先执行 `/ws-contract-check`，再继续。
+3) 明确 GOALS / NON-GOALS，并把改动归因到：
+   - `requirements/requirements-issues.csv` 的 `Req_ID`，或
+   - `issues/problem-issues.csv` 的 `Problem_ID`。
+4) 先输出“将改动的文件清单 + 回滚方案 + 验证命令”，并等待用户确认继续（Y/N）。
+5) 用户确认后再实施最小改动（遵守 `AI_PROJECT.md` 的安全边界；不要引入任何 secrets）。
+6) 运行门禁并给出结果：
+   - `aiws validate .`（若未安装全局 aiws，可用 `npx @aipper/aiws validate .`）
+7) 产出证据（至少一个）：
+   - 更新 `changes/<change-id>/...`，或
+   - 更新 `issues/*.csv` 的状态机，或
+   - 写入 `.agentdocs/tmp/...` 的 report/log/resp（不要包含 secrets）。
+
+边界：
+- 不打印任何 secrets（尤其是 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。
+"""

package/templates/workspace/.iflow/commands/ws-doctor.toml

@@ -0,0 +1,141 @@
+# Command: ws:doctor
+# Description: 检查 workspace-A 约定并给出可执行的下一步
+# Category: workspace
+# Version: 1
+
+description = "检查 workspace-A 约定并给出可执行的下一步"
+
+prompt = """
+用中文输出。检查当前目录是否符合 AIWS workspace 约定，并给出可执行的下一步建议。
+
+Rules:
+- Do not print secrets (especially secrets/test-accounts.json).
+- Only report presence/absence and safe guidance.
+- Prefer Linux-first commands.
+
+Execute:
+!{bash -lc '
+set -euo pipefail
+
+ok()   { printf "OK: %s\n" "$*"; }
+warn() { printf "警告: %s\n" "$*"; }
+miss() { printf "缺失: %s\n" "$*"; }
+note() { printf "说明: %s\n" "$*"; }
+
+project_root() {
+  local root
+  root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+  if [[ -n "${root:-}" ]]; then
+    echo "$root"
+  else
+    pwd
+  fi
+}
+
+workspace_root() {
+  local d="$PWD"
+  while true; do
+    if [[ -f "$d/AI_WORKSPACE.md" || -f "$d/REQUIREMENTS.md" || -f "$d/AI_PROJECT.md" ]]; then
+      echo "$d"
+      return 0
+    fi
+    [[ "$d" == "/" ]] && break
+    d="$(dirname "$d")"
+  done
+  project_root
+}
+
+workspace_env() {
+  [[ -f AI_WORKSPACE.md ]] || return 0
+  local line
+  line="$(grep -m1 -E "^[[:space:]]*- environment:[[:space:]]*" AI_WORKSPACE.md 2>/dev/null || true)"
+  [[ -n "${line:-}" ]] || return 0
+  printf "%s\n" "$line" | sed -E "s/.*environment:[[:space:]]*\\\"?([^\\\"#[:space:]]+).*/\\1/"
+}
+
+subdir="$(pwd)"
+root="$(workspace_root)"
+cd "$root"
+
+echo "工作目录: $root"
+if [[ "$subdir" != "$root" ]]; then
+  echo "当前子目录: $subdir"
+fi
+echo
+
+need_init=0
+
+if [[ -f AGENTS.md ]]; then ok "AGENTS.md"; else warn "AGENTS.md 未发现（建议运行 /aiws-init 补齐）"; fi
+if [[ -f AI_PROJECT.md ]]; then ok "AI_PROJECT.md"; else miss "AI_PROJECT.md"; need_init=1; fi
+if [[ -f AI_WORKSPACE.md ]]; then ok "AI_WORKSPACE.md"; else miss "AI_WORKSPACE.md"; need_init=1; fi
+if [[ -f REQUIREMENTS.md ]]; then ok "REQUIREMENTS.md"; else miss "REQUIREMENTS.md"; need_init=1; fi
+
+if [[ -f requirements/CHANGELOG.md ]]; then ok "requirements/CHANGELOG.md"; else warn "requirements/CHANGELOG.md 未发现"; fi
+if [[ -f requirements/requirements-issues.csv ]]; then ok "requirements/requirements-issues.csv"; else warn "requirements/requirements-issues.csv 未发现"; fi
+if [[ -f issues/problem-issues.csv ]]; then ok "issues/problem-issues.csv"; else warn "issues/problem-issues.csv 未发现"; fi
+
+if [[ -f .aiws/manifest.json ]]; then ok ".aiws/manifest.json"; else miss ".aiws/manifest.json"; need_init=1; fi
+if [[ -f .githooks/pre-commit ]]; then ok ".githooks/pre-commit"; else warn ".githooks/pre-commit 未发现"; fi
+if [[ -f .githooks/pre-push ]]; then ok ".githooks/pre-push"; else warn ".githooks/pre-push 未发现"; fi
+
+echo
+echo "工具链:"
+if command -v python3 >/dev/null 2>&1; then ok "python3"; else warn "python3 未发现（aiws validate 需要）"; fi
+if command -v uv >/dev/null 2>&1; then ok "uv"; else note "uv 未发现（可选；用于运行 tools/server_test_runner.py）"; fi
+if command -v aiws >/dev/null 2>&1; then ok "aiws"; else note "aiws 未发现（可用 npx @aipper/aiws ...）"; fi
+
+echo
+echo "git hooks:"
+git_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -n "${git_root:-}" ]]; then
+  hooks_path="$(git config --get core.hooksPath 2>/dev/null || true)"
+  if [[ "$hooks_path" == ".githooks" ]]; then
+    ok "core.hooksPath=.githooks（提交/推送将自动运行 aiws validate）"
+  else
+    warn "core.hooksPath 未设置为 .githooks（当前：${hooks_path:-<unset>}）"
+    note "可执行：git config core.hooksPath .githooks"
+  fi
+else
+  note "未检测到 git 仓库（跳过 hooks 检查）"
+fi
+
+echo
+echo ".gitignore:"
+if [[ -f .gitignore ]]; then
+  if grep -qF "# AIWS_MANAGED_BEGIN:gitignore" .gitignore; then
+    ok ".gitignore 已包含 AIWS managed block"
+  else
+    warn ".gitignore 缺少 AIWS managed block（建议运行 /aiws-init 或 /aiws-update 修复）"
+  fi
+else
+  warn "未找到 .gitignore"
+fi
+
+echo
+env="$(workspace_env || true)"
+if [[ -n "${env:-}" ]]; then
+  echo "environment: ${env}"
+fi
+
+echo
+echo "下一步建议:"
+if [[ "$need_init" -eq 1 ]]; then
+  echo "  - 执行: /aiws-init（或 `npx @aipper/aiws init .`）"
+else
+  echo "  - 运行门禁: aiws validate .（或 `npx @aipper/aiws validate .`）"
+fi
+echo "  - 如 iFlow 拦截写入：/ws-contract-check（写入 stamp）"
+if [[ ! -f secrets/test-accounts.json && -f secrets/test-accounts.example.json ]]; then
+  echo "  - 创建 secrets：cp -n secrets/test-accounts.example.json secrets/test-accounts.json"
+fi
+if [[ -f tools/server_test_runner.py ]]; then
+  echo "  - 接口闭环（自动修复）：/server-fix"
+  echo "  - 仅执行 runner：uv run tools/server_test_runner.py --workspace . --manage-service"
+fi
+if [[ -d memory-bank ]]; then
+  echo "  - 固定上下文：更新 memory-bank/progress.md"
+else
+  echo "  - 初始化 memory-bank：/ws-memory-bank-init"
+fi
+'}
+"""

package/templates/workspace/.iflow/commands/ws-env-doctor.toml

@@ -0,0 +1,74 @@
+# Command: ws:env-doctor
+# Description: 检查工具链并给出 node/java/python/uv 切换建议（workspace-A）
+# Category: workspace
+# Version: 1
+
+description = "检查工具链并给出 node/java/python/uv 切换建议（workspace-A）"
+
+prompt = """
+用中文输出。检查当前环境的工具链与版本，并根据 AI_WORKSPACE.md 给出可执行的切换建议。
+
+规则：
+- 只读检查，不修改系统状态
+- 优先 Linux-first
+
+Execute:
+!{bash -lc '
+set -euo pipefail
+
+say() { printf "%s\n" "$*"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+ws="$(pwd)"
+say "工作目录: $ws"
+
+if [[ -f AI_WORKSPACE.md ]]; then
+  say "OK: 发现 AI_WORKSPACE.md"
+else
+  say "警告: 未发现 AI_WORKSPACE.md（建议先 /aiws-init）"
+fi
+
+say ""
+say "== 工具可用性 =="
+for c in git uv node npm pnpm yarn java javac mvn gradle python3 mise asdf nvm sdk jenv; do
+  if have "$c"; then
+    say "OK: $c"
+  else
+    say "缺失: $c"
+  fi
+done
+
+say ""
+say "== 版本信息 =="
+have node && say "node: $(node -v 2>/dev/null || true)" || true
+have npm && say "npm: $(npm -v 2>/dev/null || true)" || true
+have pnpm && say "pnpm: $(pnpm -v 2>/dev/null || true)" || true
+have java && say "java: $(java -version 2>&1 | head -n 1)" || true
+have javac && say "javac: $(javac -version 2>&1 | head -n 1)" || true
+have python3 && say "python3: $(python3 -V 2>/dev/null || true)" || true
+have uv && say "uv: $(uv --version 2>/dev/null || true)" || true
+
+say ""
+say "== AI_WORKSPACE.md 建议执行的切换命令（如果已配置） =="
+extract_cmd() {
+  local key="$1"
+  rg -n \"^\\s*-\\s*${key}\\s*:\\s*\\\"(.*)\\\"\\s*$\" AI_WORKSPACE.md 2>/dev/null | sed -E \"s/.*\\\"(.*)\\\".*/\\1/\" | head -n 1
+}
+
+if [[ -f AI_WORKSPACE.md ]]; then
+  boot="$(extract_cmd toolchain_bootstrap_cmd || true)"
+  node_use="$(extract_cmd node_use_cmd || true)"
+  java_use="$(extract_cmd java_use_cmd || true)"
+
+  [[ -n \"$boot\" ]] && say \"toolchain_bootstrap_cmd: $boot\"
+  [[ -n \"$node_use\" ]] && say \"node_use_cmd: $node_use\"
+  [[ -n \"$java_use\" ]] && say \"java_use_cmd: $java_use\"
+fi
+
+say ""
+say "下一步建议："
+say "- 若版本不匹配：把 node/java 的版本与切换命令写进 AI_WORKSPACE.md 的 3.3 节"
+say "- 跑服务端接口测试：uv run tools/server_test_runner.py --workspace . --manage-service"
+say "- 跑需求交付闭环：/ws-feature-plan -> /ws-feature-deliver"
+'}
+"""

package/templates/workspace/.iflow/commands/ws-feature-deliver.toml

@@ -0,0 +1,44 @@
+# Command: ws:feature-deliver
+# Description: 执行跨子项目交付闭环（需求 -> 代码 -> 测试 -> Review -> 提交）
+# Category: workspace
+# Version: 1
+
+description = "执行跨子项目交付闭环（需求 -> 代码 -> 测试 -> Review -> 提交）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在工作区根目录执行“需求->实现->测试->审核->提交”的闭环，尽量减少人工干预，但严格遵守边界与可回滚。
+
+必须遵守：
+- REQUIREMENTS.md 为唯一真值；若发现需求缺口，先补齐“可验收字段”，不要擅自改语义
+- 需求变更必须通过 `/ws-req-change` 处理，并写入 `requirements/CHANGELOG.md`，再同步 issues 执行合同（避免需求漂移）
+- AI_WORKSPACE.md policy 为硬边界（默认 environment=test、base_url_allowlist=localhost）；不满足时不得执行自动化测试/自动提交
+- secrets/test-accounts.json 为敏感文件，禁止输出内容
+- 反死循环：连续 2 轮无法减少 BLOCKED 或无法推进 issues 状态，必须缩小范围或先修环境/补齐 REQUIREMENTS，不能继续盲改
+
+步骤（按顺序）：
+1) 预检（缺失则补齐）：
+   - 若不存在 `issues/feature-issues.csv`：先执行 `/ws-feature-plan` 生成计划与执行合同
+   - 检查 AI_WORKSPACE.md 是否有 environment/test 与 base_url_allowlist；缺失则用默认安全值并提示用户确认
+   - 若 AI_WORKSPACE.md 定义了 toolchain_bootstrap_cmd / node_use_cmd / java_use_cmd：在任何 build/test 前必须先执行（用 bash -lc 保证加载 shell 环境）
+2) 执行（每次只推进 1~3 个 TODO）：
+   - 从 issues/feature-issues.csv 选取 TODO，标为 DOING
+   - 先做“现状验证”：检查该 issue 对应能力是否已存在（避免重复实现/冲突）；若已满足则记录证据并直接标 DONE
+   - 否则实现最小代码修改（只改与该 issue 相关的文件）
+   - 运行对应 Tests（按 issue 的 Tests 字段或 AI_WORKSPACE.md 的 *_test_cmd）
+   - 通过则标 DONE；失败则标 BLOCKED 并写 Notes（含复现命令与证据路径）
+3) 如果涉及服务端 API 或你检测到存在 tools/server_test_runner.py：
+   - 运行 runner 生成证据包与接口合同：
+     `uv run tools/server_test_runner.py --workspace . --manage-service`
+   - 若存在 BLOCKED：执行 `/server-fix`（或 `/server-triage` 输出修复清单），直到接口验收通过或达到迭代上限
+4) 审核：
+   - 对照 REQUIREMENTS.md 验收标准逐项确认（不满足就回到步骤2/3）
+5) 提交：
+   - 若工作区使用 git submodule：优先 `/server-commit`（仅提交 server_dirs），或用 `/server-fix-and-commit`
+   - 其它 submodule（web/app）若需要提交：先给出“将提交哪些目录/文件”的清单，再执行对应子仓库 commit（不要 push）
+
+输出要求：
+- 每轮输出：本轮处理的 Issue_ID、改动文件、测试命令与结果摘要、下一步
+- 全部完成时输出：可以 merge/提 PR 的最小检查清单
+"""