@aipper/aiws 0.0.24 → 0.0.26

package/README.md

@@ -1,34 +1,68 @@
 # @aipper/aiws
 
-AI Workspace CLI：把 Claude Code / OpenCode / Codex / iFlow 对齐到同一套“真值文件 + 可审计工作流”，降低规则漂移。
+`@aipper/aiws` 是面向 AI coding workflow 的 CLI。
 
-核心能力：
-- 初始化/更新模板：`aiws init` / `aiws update`
-- 强门禁校验：`aiws validate`（可选证据落盘 `--stamp`）
-- 回滚：`aiws rollback`（从 `.aiws/backups/` 恢复）
-- 变更工件工作流（脱离 dotfiles）：`aiws change ...`
-- Git hooks：`aiws hooks install/status`
-- Codex：repo skills（推荐）+ 可选全局 skills 安装
+它负责把真值文件、变更工件、门禁和跨工具入口落到仓库里，让 Claude Code、OpenCode、Codex 可以共享同一套项目约束，而不是每个工具各写一份 prompt。
 
-真值来源（SSOT）：`@aipper/aiws-spec`（模板与契约）。
+## 当前能力
+
+- `aiws init` / `aiws update`：初始化或升级 workspace 模板
+- `aiws validate`：校验模板漂移与门禁，可选 `--stamp`
+- `aiws rollback`：从 `.aiws/backups/` 回滚
+- `aiws change ...`：变更工件工作流
+- `aiws dashboard serve`：本地 change/dashboard API
+- `aiws hooks install/status`
+- `aiws opencode status`
+- `aiws codex install-skills/status-skills/uninstall-skills`
+
+支持工具：
+- Claude Code
+- OpenCode
+- Codex
+
+说明：
+- `ws-dev-lite` 是当前推荐的小改动入口
 
 ## 安装
 
-二选一：
-- 全局安装（推荐，适合长期使用）：`npm i -g @aipper/aiws`
-- 临时运行（不污染全局版本）：`npx @aipper/aiws <command>`
+```bash
+npm i -g @aipper/aiws
+# 或
+npx @aipper/aiws --help
+```
 
 ## 快速开始
 
-在任意 git 仓库根目录：
 ```bash
 aiws init .
 aiws hooks install .
 
-# 建议：用 change 工作流生成可审计工件并切分支
 aiws change start demo-change --no-design --hooks
+aiws change validate demo-change --strict
+aiws validate . --stamp
+```
+
+初始化后会生成：
+- 真值文件：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`
+- 工件目录：`changes/`
+- AI 入口：`.agents/skills/`、`.claude/skills/`、`.claude/commands/`、`.opencode/skills/`、`.opencode/commands/`
+- hooks：`.githooks/`
 
-# 提交前门禁（并落盘证据）
+## 推荐用法
+
+AI 工具内：
+- 不确定该从哪里开始：`$using-aiws`
+- simple/local 单点修复：`$ws-dev-lite`
+- 常规实现：`$ws-dev`
+- 中大型任务：`$ws-plan` → `$ws-plan-verify` → `$ws-dev`
+- 提交前：`$ws-review` / `$ws-commit`
+- 交付前：`$ws-deliver` / `$ws-finish`
+
+shell 内：
+
+```bash
+aiws change start <change-id> --no-design
+aiws change validate <change-id> --strict
 aiws validate . --stamp
 ```
 
@@ -40,29 +74,51 @@ aiws update [path]
 aiws validate [path] [--stamp]
 aiws rollback [path] <timestamp|latest>
 
-aiws change <list|new|start|status|next|sync|validate|archive|templates>
-aiws hooks <install|status>
-aiws codex <install-skills|status-skills|uninstall-skills|install-prompts|status|uninstall-prompts>
+aiws change new <change-id> [--no-design]
+aiws change start <change-id> [--switch|--no-switch|--worktree]
+aiws change status [change-id]
+aiws change next [change-id]
+aiws change sync [change-id]
+aiws change validate [change-id] [--strict] [--check-evidence] [--check-scope]
+aiws change evidence [change-id]
+aiws change archive [change-id]
+
+aiws dashboard serve [--host 127.0.0.1] [--port 3456]
+aiws hooks install [path]
+aiws hooks status [path]
+aiws opencode status [path]
+aiws codex install-skills
+aiws codex status-skills
+aiws codex uninstall-skills
 ```
 
-## Codex（repo skills 优先）
+## Dashboard
 
-- `aiws init .` 会生成 `.agents/skills/`（随仓库共享），在 Codex 中可显式调用（示例）：`$ws-preflight` / `$ws-plan` / `$p-tasks-plan` / `$ws-handoff` / `$ws-dev` / `$ws-review` / `$ws-commit`
-- 交付收尾（submodules+superproject 分步提交 + 安全合并）：`$ws-deliver`
-- 收尾（安全合并回目标分支）：`$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward）
-- 可选：安装全局 skills 到 `~/.codex/skills/`（或 `$CODEX_HOME/skills`）：
-  - `aiws codex install-skills`
-  - `aiws codex status-skills`
-  - `aiws codex uninstall-skills`
-- legacy prompts（deprecated，仅兼容）：`aiws codex install-prompts`
+`aiws dashboard serve` 会显示：
+- change phase
+- strict blockers
+- review gates
+- scope gate
+- collaboration 统计
+- next advice
 
-## 证据落盘与协作
+本地 API：
+- `/api/changes`
+- `/api/workflow-stages`
+- `/api/change/<id>/validate?strict=1`
 
-- `aiws validate --stamp` 会写入：`.agentdocs/tmp/aiws-validate/*.json`（默认被 `.gitignore` 忽略）
-- `$ws-review` 会落盘：`.agentdocs/tmp/review/codex-review.md`（默认被 `.gitignore` 忽略）
-- 建议把“可协作/可审计”的内容放进 `changes/<change-id>/`（proposal/tasks/design）并提交；`.agentdocs/tmp/` 作为本地缓存更稳
+## 跨工具入口
+
+`aiws init .` 会把入口投影到：
+- Codex：`.agents/skills/*`
+- Claude：`.claude/skills/*` + `.claude/commands/*`
+- OpenCode：`.opencode/skills/*` + `.opencode/commands/*` + `.opencode/command/*`
+
+目标是统一 workflow 入口，不保证工具自动发现或自动加载。
 
 ## 运行要求
 
-- Node.js：>= 20
-- `aiws validate`：需要 `python3`（用于执行 `tools/ws_change_check.py` 与 `tools/requirements_contract.py`）
+- Node.js >= 20
+- `aiws validate` 需要 `python3`
+
+更多仓库级说明见根 README：[`../../README.md`](../../README.md)

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@aipper/aiws",
-  "version": "0.0.24",
-  "description": "AI Workspace CLI (init/update/validate) for Claude Code / OpenCode / Codex / iFlow.",
+  "version": "0.0.26",
+  "description": "AI Workspace CLI (init/update/validate) for Claude Code / OpenCode / Codex.",
   "type": "module",
   "bin": {
     "aiws": "./bin/aiws.js"
   },
   "dependencies": {
-    "@aipper/aiws-spec": "0.0.24"
+    "@aipper/aiws-spec": "0.0.26"
   },
   "files": [
     "bin",

package/src/cli.js

@@ -14,6 +14,7 @@ import { codexStatusSkillsCommand } from "./commands/codex-status-skills.js";
 import { codexUninstallSkillsCommand } from "./commands/codex-uninstall-skills.js";
 import { hooksInstallCommand } from "./commands/hooks-install.js";
 import { hooksStatusCommand } from "./commands/hooks-status.js";
+import { opencodeStatusCommand } from "./commands/opencode-status.js";
 import { dashboardServeCommand } from "./commands/dashboard.js";
 import {
   changeArchiveCommand,
@@ -46,6 +47,10 @@ export async function cliMain(argv) {
     printHooksHelp();
     return 0;
   }
+  if (args[0] === "opencode" && (args.includes("-h") || args.includes("--help"))) {
+    printOpenCodeHelp();
+    return 0;
+  }
   if (args[0] === "dashboard" && (args.includes("-h") || args.includes("--help"))) {
     printDashboardHelp();
     return 0;
@@ -242,6 +247,23 @@ export async function cliMain(argv) {
           throw new UserError(`Unknown dashboard subcommand: ${sub}`, { details: "Use `aiws dashboard --help` to see available subcommands." });
       }
     }
+    case "opencode": {
+      const sub = args.shift();
+      if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+        printOpenCodeHelp();
+        return 0;
+      }
+      switch (sub) {
+        case "status": {
+          const { positionals } = parseArgs(args, {});
+          const targetPath = positionals[0] ?? ".";
+          await opencodeStatusCommand({ targetPath });
+          return 0;
+        }
+        default:
+          throw new UserError(`Unknown opencode subcommand: ${sub}`, { details: "Use `aiws opencode --help` to see available subcommands." });
+      }
+    }
     case "change": {
       const sub = args.shift();
       if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
@@ -433,6 +455,7 @@ Usage:
   aiws change <subcommand>
   aiws metrics <subcommand>
   aiws dashboard <subcommand>
+  aiws opencode <subcommand>
   aiws codex <subcommand>
   aiws hooks <subcommand>
 
@@ -458,7 +481,8 @@ Usage:
 Notes:
   - Prefer repo skills: .agents/skills (no install needed)
   - Prefer global skills over legacy prompts
-  - Default skills dir: ~/.codex/skills (or $CODEX_HOME/skills)
+  - Default skills dir: ~/.agents/skills
+  - Compatibility/test override: $CODEX_HOME/.agents/skills or --dir <path>
   - install-prompts is legacy (prompts are deprecated)
   - Default target dir: ~/.codex/prompts
   - If CODEX_HOME is set: $CODEX_HOME/prompts
@@ -478,6 +502,18 @@ Notes:
 `);
 }
 
+function printOpenCodeHelp() {
+  console.log(`aiws opencode
+
+Usage:
+  aiws opencode status [path]
+
+Notes:
+  - Detects project-local .opencode/ and oh-my-opencode (oMo) config.
+  - Helps verify whether AIWS OpenCode skills should prefer oMo agents or fallback to standard-opencode.
+`);
+}
+
 function printDashboardHelp() {
   console.log(`aiws dashboard
 
@@ -486,6 +522,8 @@ Usage:
 
 Notes:
   - Local-only dashboard, no external dependencies.
+  - Dashboard also exposes workflow governance data sourced from @aipper/aiws-spec:
+    /api/changes, /api/workflow-stages, /api/change/<id>/validate?strict=1
   - Recommended: run change quality gate first (AI tools: $ws-plan-verify):
     aiws change validate <change-id> --strict
 `);
@@ -515,7 +553,7 @@ Notes:
     you can omit <change-id> for status/next/validate/sync/archive/finish.
   - Execution quality gate first: aiws change validate [change-id] --strict
     (equivalent to running $ws-plan-verify in AI tools).
-  - status/next now prioritize quality-gate guidance before coding ($ws-dev).
+  - status/next now prioritize quality-gate guidance before coding ($ws-dev-lite / $ws-dev).
   - start refuses to switch/create worktree with a dirty working tree (unless --allow-dirty).
   - finish --push is submodule-aware: when .gitmodules exists it pushes submodules first, then the target branch, then safely cleans the separate change worktree if possible.
   - If .gitmodules exists and you didn't specify --switch/--no-switch/--worktree,

package/src/codex-skills.js

@@ -7,16 +7,16 @@ import { UserError } from "./errors.js";
 /**
  * Resolve Codex global skills directory:
  * - If `--dir` provided, use it directly.
- * - Else if `CODEX_HOME` is set, use `$CODEX_HOME/skills`.
- * - Else use `~/.codex/skills`.
+ * - Else if `CODEX_HOME` is set, use `$CODEX_HOME/.agents/skills` as a compatibility/test override root.
+ * - Else use `~/.agents/skills`.
  *
  * @param {string | undefined} dirOption
  */
 export function resolveCodexSkillsDir(dirOption) {
   if (dirOption) return path.resolve(dirOption);
   const envHome = String(process.env.CODEX_HOME || "").trim();
-  if (envHome) return path.join(path.resolve(envHome), "skills");
-  return path.join(os.homedir(), ".codex", "skills");
+  if (envHome) return path.join(path.resolve(envHome), ".agents", "skills");
+  return path.join(os.homedir(), ".agents", "skills");
 }
 
 function timestamp() {

package/src/commands/change-advice.js

@@ -0,0 +1,191 @@
+import path from "node:path";
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{
+ *   listGitWorktrees: (gitRoot: string) => Promise<Array<{ worktree: string, branch: string }>>
+ * }} deps
+ */
+export async function resolveChangeWorktreeHint(gitRoot, changeId, deps) {
+  try {
+    const worktrees = await deps.listGitWorktrees(gitRoot);
+    const changeRef = `refs/heads/change/${changeId}`;
+    const changeWorktree = worktrees.find((worktree) => String(worktree.branch || "") === changeRef)?.worktree || "";
+    return changeWorktree && path.resolve(changeWorktree) !== path.resolve(gitRoot) ? changeWorktree : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{
+ *   computeChangeStatus: (gitRoot: string, changeId: string) => Promise<any>,
+ *   currentBranch: (gitRoot: string) => Promise<string>,
+ *   inferChangeIdFromBranch: (branch: string) => string,
+ *   listGitWorktrees: (gitRoot: string) => Promise<Array<{ worktree: string, branch: string }>>,
+ *   changeDirAbs: (gitRoot: string, changeId: string) => string,
+ *   governanceGuidanceLines: (status: any) => Promise<string[]>,
+ *   scopeGateFailureAction: (changeId: string) => string,
+ *   scopeGatePendingRecommendation: (changeId: string) => string,
+ *   scopeGatePassedRecommendation: () => string
+ * }} deps
+ */
+export async function computeChangeNextAdvice(gitRoot, changeId, deps) {
+  const status = await deps.computeChangeStatus(gitRoot, changeId);
+  const branch = await deps.currentBranch(gitRoot);
+  const inferred = deps.inferChangeIdFromBranch(branch);
+  const advice = {
+    changeId,
+    branch: branch || "",
+    inferredChangeId: inferred || "",
+    phase: status.phase,
+    governance: status.governance || null,
+    scopeGate: status.scopeGate || null,
+    blockersStrict: status.blockersStrict,
+    evidence: status.evidence?.counts || null,
+    collaboration: status.collaboration?.counts || null,
+    actions: [],
+    prohibitions: [],
+    recommended: [],
+  };
+
+  if (!branch) {
+    advice.actions.push("当前为 detached HEAD：建议切到 `change/<change-id>` 分支后再继续（或显式传入 `<change-id>`）");
+  } else if (inferred && inferred !== changeId) {
+    advice.actions.push(`当前分支为 \`${branch}\`（推断 change=${inferred}），但你在查看 change=${changeId}：建议先切换到 \`change/${changeId}\` 再执行开发/交付`);
+  } else if (!inferred) {
+    advice.actions.push(`当前分支为 \`${branch}\`（非 change 分支）：建议 \`aiws change start ${changeId} --hooks --switch\` 或 \`git switch change/${changeId}\``);
+  }
+
+  const changeWorktree = await resolveChangeWorktreeHint(gitRoot, changeId, deps);
+  if (changeWorktree) {
+    advice.actions.push(`change/${changeId} 分支在另一个 worktree：\`cd ${changeWorktree}\`（建议在该目录执行开发/交付相关命令）`);
+    advice.prohibitions.push("不要在当前 worktree 继续写代码（很可能不在 change 分支上）");
+  }
+
+  if (status.metaState !== "ok") advice.actions.push(`补齐元信息并建立真值基线：\`aiws change sync ${changeId}\``);
+  if (status.driftFiles.length > 0) {
+    advice.actions.push("真值/合同已变化：先对齐 `AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md` 与 proposal/tasks");
+    advice.actions.push(`确认后同步基线：\`aiws change sync ${changeId}\``);
+  }
+
+  const proposalPath = path.join(deps.changeDirAbs(gitRoot, changeId), "proposal.md");
+  const tasksPath = path.join(deps.changeDirAbs(gitRoot, changeId), "tasks.md");
+  if (status.blockersStrict.some((item) => item.includes("proposal.md") && item.includes("WS:TODO"))) {
+    advice.actions.push(`完善 proposal：\`$EDITOR ${proposalPath}\``);
+  }
+  if (status.blockersStrict.some((item) => item.includes("tasks.md") && item.includes("WS:TODO"))) {
+    advice.actions.push(`完善 tasks：\`$EDITOR ${tasksPath}\``);
+  }
+  if (status.blockersStrict.some((item) => item.includes("proposal.md missing attribution"))) {
+    advice.actions.push("补齐归因：在 proposal.md 填写非空 `Req_ID` 或 `Problem_ID`（严格校验需要）");
+  }
+  if (status.blockersStrict.some((item) => item.includes("missing Contract_Row"))) {
+    advice.actions.push("补齐绑定：在 proposal.md 填写非空 `Contract_Row`（严格校验需要）");
+  }
+  if (status.blockersStrict.some((item) => item.includes("Plan_File"))) {
+    advice.actions.push("补齐绑定：修正 proposal.md 的 `Plan_File`（严格校验需要；必须存在且仅 1 个）");
+  }
+  if (status.blockersStrict.some((item) => item.includes("missing Evidence_Path"))) {
+    advice.actions.push("补齐绑定：在 proposal.md 填写非空 `Evidence_Path`（严格校验需要；建议优先写 `changes/<id>/evidence/...`）");
+  }
+  if (status.scopeGate?.status === "failed") {
+    advice.actions.push(deps.scopeGateFailureAction(changeId));
+  }
+  if (status.tasks.unchecked > 0) advice.actions.push(`完成未勾选任务（${status.tasks.unchecked} 项）`);
+  if (status.blockersStrict.length === 0 && status.tasks.unchecked > 0) {
+    advice.actions.push("质量门通过后继续开发：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`");
+  }
+  if ((status.collaboration?.counts?.analysis || 0) > 0 && (status.collaboration?.counts?.review || 0) === 0) {
+    advice.actions.push("已有委托分析但还没有 review 汇总结论：建议在 `changes/<id>/review/` 落盘结论后再交付");
+  }
+  if ((status.collaboration?.counts?.patches || 0) > 0) {
+    advice.actions.push("存在委托 patch 草案：提交/交付前先人工审查 `changes/<id>/patches/`，不要直接无审查应用");
+  }
+
+  if (status.blockersStrict.length > 0 && advice.actions.length === 0) {
+    advice.actions.push("先修复 Blockers (strict) 后复跑质量门，再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`");
+  }
+
+  if (status.blockersStrict.length === 0 && status.tasks.unchecked === 0) {
+    for (const line of await deps.governanceGuidanceLines(status)) advice.recommended.push(line);
+    if (advice.evidence && advice.evidence.persistent === 0) {
+      advice.recommended.push("交付前建议生成持久证据并回填：`aiws change evidence <change-id>`");
+    }
+    if (status.scopeGate?.status === "not_run") {
+      advice.recommended.push(deps.scopeGatePendingRecommendation(changeId));
+    } else if (status.scopeGate?.status === "passed") {
+      advice.recommended.push(deps.scopeGatePassedRecommendation());
+    }
+    if ((status.governance?.recommendedStage || "") === "ws-finish" || (status.governance?.currentStage || "") === "ws-commit") {
+      advice.recommended.push("交付前门禁（推荐落盘）：`aiws validate . --stamp`");
+    }
+    if ((status.collaboration?.counts?.review || 0) > 1) advice.recommended.push("存在多份 review：交付前建议在 handoff 或 review 汇总里收敛最终结论");
+  } else if (advice.actions.length === 0) {
+    advice.recommended.push("继续开发：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`（小步实现 + 可复现验证）");
+    if ((status.collaboration?.counts?.analysis || 0) > 0) advice.recommended.push("已有委托分析：进入实现前先收敛 `changes/<id>/analysis/` 结论");
+    if ((status.collaboration?.counts?.patches || 0) > 0) advice.recommended.push("已有 patch 草案：应用前先人工审查 `changes/<id>/patches/`");
+  }
+
+  return advice;
+}
+
+/**
+ * @param {{
+ *   changeId: string,
+ *   gitRoot: string,
+ *   now: string,
+ *   status: any,
+ *   advice: any,
+ *   planVerifyLine: string
+ * }} input
+ */
+export function renderChangeStateMarkdown(input) {
+  /** @type {string[]} */
+  const lines = [];
+  lines.push(`# AIWS STATE: ${input.changeId}`);
+  lines.push("");
+  lines.push(`Generated: ${input.now}`);
+  lines.push("");
+  lines.push("## Context");
+  lines.push(`- Worktree: \`${input.gitRoot}\``);
+  lines.push(`- Branch: \`${input.advice.branch || "(detached)"}\``);
+  lines.push("");
+  lines.push("## Phase");
+  lines.push(`- Phase: \`${input.status.phase}\``);
+  lines.push(`- Tasks: ${input.status.tasks.done}/${input.status.tasks.total} (unchecked=${input.status.tasks.unchecked})`);
+  lines.push("");
+  lines.push("## Bindings");
+  if (input.status.reqId) lines.push(`- Req_ID: \`${input.status.reqId}\``);
+  if (input.status.probId) lines.push(`- Problem_ID: \`${input.status.probId}\``);
+  if (input.status.bindings?.contractRow) lines.push(`- Contract_Row: \`${input.status.bindings.contractRow}\``);
+  if (input.status.bindings?.planFile) lines.push(`- Plan_File: \`${input.status.bindings.planFile}\``);
+  lines.push("");
+  lines.push("## Evidence");
+  if (input.status.evidence?.counts) {
+    const counts = input.status.evidence.counts;
+    lines.push(
+      `- Declared: \`${counts.total}\` (exists=\`${counts.exists}\`, missing=\`${counts.missing}\`, persistent=\`${counts.persistent}\`, tmp=\`${counts.tmp}\`)`,
+    );
+  } else {
+    lines.push("- (unknown)");
+  }
+  lines.push("");
+  lines.push("## Blockers (strict)");
+  if (input.status.blockersStrict.length === 0) lines.push("- (none)");
+  else for (const blocker of input.status.blockersStrict) lines.push(`- ${blocker}`);
+  lines.push("");
+  lines.push("## Next");
+  lines.push(`- ${input.planVerifyLine}`);
+  for (const action of input.advice.actions) lines.push(`- ${action}`);
+  for (const recommendation of input.advice.recommended) lines.push(`- ${recommendation}`);
+  if (input.advice.prohibitions.length > 0) {
+    lines.push("");
+    lines.push("## Do Not");
+    for (const prohibition of input.advice.prohibitions) lines.push(`- ${prohibition}`);
+  }
+  return lines.join("\n") + "\n";
+}