@andyqiu/codeforge 0.5.0 → 0.5.1

package/agents/codeforge.md

@@ -66,12 +66,13 @@ fallback_models:
 | 场景 | 该做什么 | MUST NOT |
 |---|---|---|
 | 用户问简单问题 / 寻求解释 / 对比方案讨论（≤ 800 字能答完） | **自己直接答**，不派任何 agent | ❌ 派 planner 或 coder |
-| **小改动 short-circuit**：用户指明确切文件位置 + 改动 ≤ 1 文件 + 估算 < 5 行 + 用户已给出修改思路 | 跳过 planner，**直接派 coder**，prompt 自包含改动需求（无 plan_id 路径） | ❌ 派 planner 再让它派 coder |
+| **小改动 short-circuit**：用户指明确切文件位置 + 改动 ≤ 1 文件 + 估算 < 5 行 + 用户已给出修改思路 | 跳过 planner，**直接派 coder**，prompt 自包含改动需求（无 plan_id 路径）；coder 完成后同样走「coder 回报正常完成」行的自动 reviewer 流程 | ❌ 派 planner 再让它派 coder |
 | 复杂多步任务（含设计 / 涉及多文件 / 不确定改哪 / 需要查历史经验） | **派 planner 出方案** → 等 planner 回 boomerang（含 `plan_id: plan-xxx`）→ **自动派 reviewer 审方案**（`review_target=plan_only` + plan_id）：APPROVE → 派 coder 执行（带 plan_id + sessionId）；REQUEST_CHANGES (`plan_review_loop_count` < 3) → 自动派 planner 改方案，loop +1；REQUEST_CHANGES (loop = 3) → 转告用户三选一；BLOCK → 转告用户 + 建议派 planner 重设计 | ❌ 派完 planner 直接派 coder；❌ 绕过方案 BLOCK |
 | **决策 review（Q3-a 范围）** | 先派 reviewer 审决策合理性（`review_target=decision_only`）：APPROVE → 按决策派；REQUEST_CHANGES → reviewer 给替代方案，loop 1 次后转告用户；BLOCK → 转告用户 | ❌ 审用户业务选择本身；❌ 把所有 question 都套 review |
 | 用户要"独立交付物" | 派 coder 子 session 写并直接落到 session worktree；prompt 明示"final response 不要粘回长内容" | ❌ 自己在父对话吐长文档 |
 | 用户要查项目结构 / 历史经验 | 自己调 `smart_search` / `repo_map` / `read` / `plan_read` | ❌ 为此派 subagent |
-| **subagent 回报正常完成** | 拿到 boomerang 摘要后决定下一棒：**询问用户是否 `/merge`** / 派 reviewer / 派下个 phase / 收尾 | ❌ 重新审查 subagent 的代码；❌ 默认 subagent 会自派下一棒 |
+| **coder 回报正常完成** | 自动派 reviewer 审代码改动（`review_target` 按文件类型自动检测）；后续按下方「reviewer 报三档」独立行处理 | ❌ 跳过 reviewer 直接问用户是否 merge；❌ 重新审查代码 |
+| **其他 subagent 回报正常完成**（planner / reviewer 等） | 按上下文决定下一棒：派 reviewer / 派下个 phase / 收尾 | ❌ 默认 subagent 会自派下一棒 |
 | **subagent 报错 / 中断 / 摘要为空** | **立刻停下**，把错误首行原文 + 子 session id 转告用户，问「重试 / 改方案 / 跳过」三选一 | ❌ 盲目"再派一次试试" |
 | **subagent 长时间无回报** | 提醒用户「子 session 仍在跑，按 `Ctrl+→` 可切过去看进度」 | ❌ 主动 Esc 取消；❌ 重派 |
 | **reviewer 报 REQUEST_CHANGES（代码 review，`code_review_loop_count` < 3）** | **自动派 coder 修**（带具体到行的 reviewer 意见 + 原 plan_id + sessionId），loop +1 | ❌ 同时派多个 coder；❌ 不带 reviewer 意见 |

package/commands/diff.md

@@ -0,0 +1,62 @@
+---
+description: 查看当前 session worktree 的改动（文件列表+统计，或完整 diff）
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: diff
+  version: 1.0.0
+  requires_human_approval: false
+  说明：底层调用 session_merge 工具的 action=diff
+        默认显示改动文件列表 + 统计（stat=true）
+        --full 显示完整 diff 内容（stat=false）
+        没有 worktree 时友好提示
+-->
+
+
+# /diff — 查看当前 session worktree 改动
+
+**ADR: worktree-session-isolation Phase 3**
+
+快速查看当前 session worktree 中的代码改动，无需触发 merge 或 review 流程。
+
+## 输入
+
+用户参数：$ARGUMENTS
+
+## 用法
+
+```
+/diff                     # 显示改动文件列表 + 统计（git diff --stat 风格）
+/diff --full              # 显示完整 diff 内容
+```
+
+## 行为说明
+
+| 模式 | 触发条件 | 输出内容 |
+|------|----------|----------|
+| **stat 模式**（默认） | `/diff` | 改动文件列表 + 增删行数统计 |
+| **full 模式** | `/diff --full` | 完整 diff 内容（含每行改动） |
+| **无 worktree** | session 无写操作 | 友好提示：当前 session 没有写操作，无 worktree 改动 |
+
+## 底层调用
+
+```
+/diff         → session_merge(action="diff", stat=true)
+/diff --full  → session_merge(action="diff", stat=false)
+```
+
+## 何时使用
+
+- 在 `/merge` 之前确认改动范围
+- 向用户或 reviewer 展示本次 session 做了什么
+- 调试时快速确认某文件是否已被修改
+
+## 与其他命令的关系
+
+| 命令 | 用途 |
+|------|------|
+| `/diff` | 本命令：只读查看 worktree 改动，不触发任何合并 |
+| `/merge` | 触发 review-fix-review 审批闭环后 squash merge 入主仓 |
+| `/discard-session` | 放弃当前 session 所有改动（不可恢复） |
+| `session_merge action=status` | 查看 worktree 绑定状态（非 diff 内容） |

package/dist/index.js

@@ -13763,6 +13763,7 @@ var description26 = [
   "- action=status：查询当前 session worktree 状态（任意 agent 可调）",
   "- action=merge：codeforge orchestrator 在用户触发 /merge 后调（**subagent 禁止**）",
   "- action=discard：用户决定放弃当前 session 改动时调",
+  "- action=diff：查看当前 session worktree 相对主仓（baseSha）的改动；stat=true 只看文件列表",
   "**注意**：",
   "- merge 走 review-fix-review 闭环（默认 3 轮）；force=true 跳过 review 直接 squash",
   "- subagent (coder/reviewer/planner) 调 action=merge 会被 Phase 2 guard plugin 拒绝",
@@ -13784,6 +13785,11 @@ var ArgsSchema26 = z27.discriminatedUnion("action", [
   z27.object({
     action: z27.literal("discard"),
     session_id: z27.string().optional().describe("默认当前 session")
+  }),
+  z27.object({
+    action: z27.literal("diff"),
+    session_id: z27.string().optional().describe("默认当前 session"),
+    stat: z27.boolean().optional().describe("true=只显示文件列表+统计，false=完整 diff（默认 false）")
   })
 ]);
 var _ctx = {};
@@ -13833,6 +13839,63 @@ async function execute26(input) {
         data: { discarded: true, sessionId }
       };
     }
+    if (args.action === "diff") {
+      const entry = await getSessionWorktree(sessionId, mainRoot);
+      if (!entry) {
+        return { ok: false, action: "diff", error: `session ${sessionId} 没有绑定 worktree` };
+      }
+      const { execFile: execFile4 } = await import("node:child_process");
+      const { promisify: promisify2 } = await import("node:util");
+      const execFileAsync = promisify2(execFile4);
+      const diffArgs = args.stat ? ["diff", "--stat", entry.baseSha] : ["diff", entry.baseSha];
+      let diffOutput = "";
+      let changedFiles = [];
+      try {
+        const { stdout } = await execFileAsync("git", diffArgs, {
+          cwd: entry.worktreePath,
+          maxBuffer: 5242880
+        });
+        diffOutput = stdout;
+        const { stdout: nameOnly } = await execFileAsync("git", ["diff", "--name-only", entry.baseSha], { cwd: entry.worktreePath, maxBuffer: 1048576 });
+        changedFiles = nameOnly.trim().split(`
+`).filter(Boolean);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (!msg.includes("unknown revision") && !msg.includes("bad object")) {
+          return { ok: false, action: "diff", error: `git diff 失败: ${msg}` };
+        }
+        try {
+          const fallbackArgs = args.stat ? ["diff", "--stat", "HEAD"] : ["diff", "HEAD"];
+          const { stdout } = await execFileAsync("git", fallbackArgs, {
+            cwd: entry.worktreePath,
+            maxBuffer: 5242880
+          });
+          diffOutput = stdout;
+          const { stdout: nameOnly } = await execFileAsync("git", ["diff", "--name-only", "HEAD"], { cwd: entry.worktreePath, maxBuffer: 1048576 });
+          changedFiles = nameOnly.trim().split(`
+`).filter(Boolean);
+        } catch (e2) {
+          return {
+            ok: false,
+            action: "diff",
+            error: `git diff 失败: ${e2 instanceof Error ? e2.message : String(e2)}`
+          };
+        }
+      }
+      return {
+        ok: true,
+        action: "diff",
+        data: {
+          sessionId,
+          worktreePath: entry.worktreePath,
+          branch: entry.branch,
+          baseSha: entry.baseSha,
+          changedFiles,
+          fileCount: changedFiles.length,
+          diff: diffOutput
+        }
+      };
+    }
     if (!_ctx.spawner) {
       return {
         ok: false,
@@ -13840,11 +13903,12 @@ async function execute26(input) {
         error: "session_merge: SubagentSpawner 未注入（Phase 1 runtime 暂未接 wire-up；" + "Phase 3 commands/merge.md 落地后会通过 __setContext 注入）"
       };
     }
+    const mergeArgs = args;
     const result = await runMergeLoop({
       sessionId,
       mainRoot,
-      ...args.plan_id ? { planId: args.plan_id } : {},
-      ...args.force ? { force: true } : {},
+      ...mergeArgs.plan_id ? { planId: mergeArgs.plan_id } : {},
+      ...mergeArgs.force ? { force: true } : {},
       spawner: _ctx.spawner
     });
     return { ok: true, action: "merge", data: result };
@@ -20596,7 +20660,7 @@ import * as zlib from "node:zlib";
 // lib/version-injected.ts
 function getInjectedVersion() {
   try {
-    const v = "0.5.0";
+    const v = "0.5.1";
     if (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v)) {
       return v;
     }

package/install.ps1

@@ -1,556 +1,556 @@
-<#
-.SYNOPSIS
-  CodeForge installer (PowerShell) — 零侵入安装到 opencode（v2 单 bundle 架构）
-
-.DESCRIPTION
-  CodeForge v0.1+ 改为 OMO 风格的单 plugin bundle 架构：
-    1. 17 个能力被 bun build 编译成 dist/index.js 一个 ESM bundle
-    2. 在 opencode.json 里只占 1 行 plugin entry
-    3. 永久避免 opencode 1.14+ 早期版本的 zod 跨实例 bug（issue #12336/#21155）
-
-  本脚本职责：
-    1. 检测 opencode CLI 与 KH MCP
-    2. 把 dist/index.js 复制到 ~/.config/opencode/codeforge/index.js
-    3. 在 ~/.config/opencode/opencode.json 的 "plugin" 数组追加 file:// URL
-    4. 把 agents/commands 用 file-by-file copy 注入（带白名单）
-    5. 把 workflows/context-templates/review-profiles 拷贝过去
-    5b. 把 skills/ 目录拷贝到 $TargetRoot/skills/（与 install.sh 对称）
-    6. 智能合并 AGENTS.md：
-       - 项目模式 + 已有 AGENTS.md → 替换 <!-- knowledge-hub:start -->...<!-- knowledge-hub:end --> 块（带 .bak 备份）
-       - 项目模式 + 无 AGENTS.md  → 生成含 marker 块的短版骨架
-       - 全局模式               → 跳过（context-templates 已经放进 ~/.config/opencode/context-templates/ 给所有项目复用）
-    7. -Global 时生成 ~/.config/codeforge/kh.json 模板（不含 token，硬约束 #2）
-    8. 输出验证清单
-
-.PARAMETER Global
-  装到全局 (~/.config/opencode/)，默认装到当前项目 (.opencode/)
-
-.PARAMETER Uninstall
-  卸载 CodeForge 注入物（不动 opencode 自身和 AGENTS.md，会清掉 opencode.json 里的 plugin entry）
-
-.PARAMETER DryRun
-  仅打印将要执行的操作，不真正执行
-
-.PARAMETER SkipBuild
-  跳过 npm run build。默认每次安装前会先 build 确保 dist 是最新的，加 -SkipBuild 跳过
-
-.EXAMPLE
-  .\install.ps1
-  .\install.ps1 -Global
-  .\install.ps1 -Uninstall
-  .\install.ps1 -DryRun
-  .\install.ps1 -SkipBuild
-#>
-[CmdletBinding()]
-param(
-  [switch]$Global,
-  [switch]$Uninstall,
-  [switch]$DryRun,
-  [switch]$SkipBuild
-)
-
-$ErrorActionPreference = 'Stop'
-
-# ────────────── 工具函数 ──────────────
-function Write-Section([string]$Text) {
-  Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
-  Write-Host "[codeforge] $Text" -ForegroundColor Cyan
-}
-function Write-Ok([string]$Text)   { Write-Host "$([char]0x2713) $Text" -ForegroundColor Green }
-function Write-Warn2([string]$Text) { Write-Host "$([char]0x26A0)  $Text" -ForegroundColor Yellow }
-function Write-Err2([string]$Text) { Write-Host "$([char]0x2717) $Text" -ForegroundColor Red }
-
-function Invoke-Step([string]$Description, [scriptblock]$Action) {
-  if ($DryRun) {
-    Write-Host "  [dry-run] $Description" -ForegroundColor Blue
-  } else {
-    & $Action
-  }
-}
-
-# ────────────── 路径解析 ──────────────
-$ScriptDir  = Split-Path -Parent $MyInvocation.MyCommand.Path
-$SourceRoot = $ScriptDir
-
-if ($Global) {
-  $XdgConfig = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { Join-Path $HOME '.config' }
-  $TargetRoot = Join-Path $XdgConfig 'opencode'
-  $Mode = 'global'
-} else {
-  $TargetRoot = Join-Path (Get-Location).Path '.opencode'
-  $Mode = 'project'
-}
-
-# CodeForge 自身的全局配置目录（与 opencode 配置目录同级）
-$XdgConfigBase = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { Join-Path $HOME '.config' }
-$CodeforgeCfgDir = Join-Path $XdgConfigBase 'codeforge'
-
-# v0.1 之前 install.ps1 装的目录（卸载时一并清掉）
-$LegacyDirs    = @('agent', 'command', 'tool', 'tools', 'plugin', 'plugins', 'lib')
-# v0.1+ 才有的目录（review-profiles 由 ADR:reviewer-multi-profile 引入）
-$ManagedDirs   = @('codeforge', 'agents', 'commands', 'workflows', 'context-templates', 'review-profiles')
-
-# v0.1+ 文件分发计划
-$BundleSrcRel  = 'dist/index.js'
-$BundleDstRel  = 'codeforge/index.js'   # 相对 $TargetRoot
-
-# B3 KH 行为规范模板（智能合并的输入）
-$KhTemplateRel = 'context-templates/kh-instructions.md'
-
-# .md file-by-file copy（白名单 *.md，排除 README/_*/.bak）
-$MdCopyMap = @(
-  @{ Src='agents';   Dst='agents'   },
-  @{ Src='commands'; Dst='commands' }
-)
-# 普通整目录 copy（review-profiles 由 ADR:reviewer-multi-profile 引入）
-$CopyMap = @(
-  @{ Src='workflows';         Dst='workflows'         },
-  @{ Src='context-templates'; Dst='context-templates' },
-  @{ Src='review-profiles';   Dst='review-profiles'   }
-)
-
-# ────────────── opencode.json 管理 ──────────────
-function Get-OpencodeConfigPath {
-  Join-Path $TargetRoot 'opencode.json'
-}
-
-function Get-PluginUri {
-  # opencode 接受 file:// URL 也接受裸绝对路径，统一用 file:// 更明确
-  $abs = Join-Path $TargetRoot $BundleDstRel
-  $abs = $abs -replace '\\', '/'
-  if ($abs -notmatch '^[A-Za-z]:/') {
-    return "file://$abs"
-  }
-  return "file:///$abs"
-}
-
-function Add-PluginEntry {
-  $cfgPath = Get-OpencodeConfigPath
-  $uri = Get-PluginUri
-
-  if (-not (Test-Path -LiteralPath $TargetRoot)) {
-    Invoke-Step "mkdir $TargetRoot" {
-      New-Item -ItemType Directory -Path $TargetRoot -Force | Out-Null
-    }
-  }
-
-  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
-    Write-Err2 "需要 node 才能改写 opencode.json，请安装 Node.js >= 20"
-    exit 1
-  }
-
-  Invoke-Step "write $cfgPath plugin entry: $uri" {
-    $env:CODEFORGE_CFG = $cfgPath
-    $env:CODEFORGE_URI = $uri
-    $nodeScript = @'
-const fs = require("node:fs");
-const path = process.env.CODEFORGE_CFG;
-const uri = process.env.CODEFORGE_URI;
-let cfg = {};
-if (fs.existsSync(path)) {
-  try { cfg = JSON.parse(fs.readFileSync(path, "utf8")); }
-  catch { fs.copyFileSync(path, path + ".bak." + Date.now()); cfg = {}; }
-}
-if (!cfg.$schema) cfg.$schema = "https://opencode.ai/config.json";
-if (!Array.isArray(cfg.plugin)) cfg.plugin = [];
-const cleaned = [];
-for (const e of cfg.plugin) {
-  const s = String(e);
-  if (/\/codeforge\/index\.js$/.test(s)) continue;
-  if (/\/plugins\/[^/]+\.ts$/.test(s) && /opencode/.test(s)) continue;
-  if (/\/\.opencode\/plugins\//.test(s)) continue;
-  cleaned.push(e);
-}
-cleaned.push(uri);
-cfg.plugin = cleaned;
-fs.writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", "utf8");
-'@
-    & node -e $nodeScript
-    Remove-Item Env:\CODEFORGE_CFG -ErrorAction SilentlyContinue
-    Remove-Item Env:\CODEFORGE_URI -ErrorAction SilentlyContinue
-  }
-  Write-Ok "opencode.json 已写入 plugin entry: $uri"
-}
-
-function Remove-PluginEntry {
-  $cfgPath = Get-OpencodeConfigPath
-  if (-not (Test-Path -LiteralPath $cfgPath)) { return }
-  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
-    Write-Warn2 "未找到 node，跳过 opencode.json plugin entry 清理"
-    return
-  }
-
-  Invoke-Step "rewrite $cfgPath without codeforge plugin entry" {
-    $env:CODEFORGE_CFG = $cfgPath
-    $nodeScript = @'
-const fs = require("node:fs");
-const path = process.env.CODEFORGE_CFG;
-let cfg;
-try { cfg = JSON.parse(fs.readFileSync(path, "utf8")); }
-catch { return; }
-if (!Array.isArray(cfg.plugin)) return;
-cfg.plugin = cfg.plugin.filter(e => {
-  const s = String(e);
-  if (/\/codeforge\/index\.js$/.test(s)) return false;
-  if (/\/plugins\/[^/]+\.ts$/.test(s)) return false;
-  if (/\/\.opencode\/plugins\//.test(s)) return false;
-  return true;
-});
-fs.writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", "utf8");
-'@
-    & node -e $nodeScript
-    Remove-Item Env:\CODEFORGE_CFG -ErrorAction SilentlyContinue
-  }
-  Write-Ok "opencode.json 已移除 codeforge plugin entry"
-}
-
-# ────────────── KH 全局模板（仅 -Global） ──────────────
-#
-# 硬约束 #2：API key 绝不能落盘，模板里**不写** token / apiKey 字段。
-# 用户必须通过环境变量 KNOWLEDGE_API_KEY 提供。
-# 已存在则跳过，避免覆盖用户自定义。
-function Write-KhTemplate {
-  $khFile = Join-Path $CodeforgeCfgDir 'kh.json'
-  if (-not (Test-Path -LiteralPath $CodeforgeCfgDir)) {
-    Invoke-Step "mkdir $CodeforgeCfgDir" {
-      New-Item -ItemType Directory -Path $CodeforgeCfgDir -Force | Out-Null
-    }
-  }
-  if (Test-Path -LiteralPath $khFile) {
-    Write-Ok "已存在 $khFile，跳过覆盖"
-    return
-  }
-  Invoke-Step "write $khFile (no token)" {
-    $body = @"
-{
-  "url": "http://10.5.60.26:8900/mcp",
-  "timeoutMs": 5000,
-  "maxRetries": 1
-}
-"@
-    # 用 .NET WriteAllText 强制无 BOM 的 UTF8（PowerShell 5.1 默认 BOM 会被 KhConfig 容错，但保持干净）
-    [System.IO.File]::WriteAllText($khFile, $body, (New-Object System.Text.UTF8Encoding $false))
-  }
-  Write-Ok "已生成 $khFile（API key 请通过环境变量 KNOWLEDGE_API_KEY 提供，禁止写入文件）"
-}
-
-# ────────────── AGENTS.md 智能合并（B3 新增） ──────────────
-#
-# 实现委托给 scripts/merge-agents-md.mjs CLI（C.4 单一入口），
-# 算法源自 lib/agents-merge.ts，sh/ps1 共用同一份 Node 实现，
-# 避免 install 脚本各自维护算法副本造成漂移。
-function Merge-ProjectAgentsMd {
-  param(
-    [Parameter(Mandatory=$true)] [string] $AgentsTarget,
-    [Parameter(Mandatory=$true)] [string] $TemplatePath
-  )
-  $cliPath = Join-Path $SourceRoot 'scripts/merge-agents-md.mjs'
-  if (-not (Test-Path -LiteralPath $TemplatePath)) {
-    Write-Warn2 "模板不存在，跳过 AGENTS.md 合并: $TemplatePath"
-    return
-  }
-  if (-not (Test-Path -LiteralPath $cliPath)) {
-    Write-Warn2 "merge CLI 不存在，跳过 AGENTS.md 智能合并: $cliPath"
-    return
-  }
-  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
-    Write-Warn2 "未找到 node，跳过 AGENTS.md 智能合并（请安装 Node.js >= 20）"
-    return
-  }
-  $cliArgs = @('--target', $AgentsTarget, '--template', $TemplatePath)
-  if ($DryRun) { $cliArgs += '--dry-run' }
-  try {
-    & node $cliPath @cliArgs
-  } catch {
-    Write-Warn2 "AGENTS.md 合并失败（不阻塞 install 主流程）: $_"
-  }
-}
-
-# ────────────── 卸载 ──────────────
-function Invoke-Uninstall {
-  Write-Section "卸载 CodeForge from: $TargetRoot"
-  Remove-PluginEntry
-  $candidates = $LegacyDirs + $ManagedDirs | Select-Object -Unique
-  foreach ($name in $candidates) {
-    $path = Join-Path $TargetRoot $name
-    if (Test-Path -LiteralPath $path) {
-      Invoke-Step "remove $path" {
-        # Junction 不能用 Remove-Item 直接删（会删源），需要先 rmdir
-        $item = Get-Item -LiteralPath $path -Force
-        if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
-          [IO.Directory]::Delete($path, $false)
-        } else {
-          Remove-Item -LiteralPath $path -Recurse -Force
-        }
-      }
-      Write-Ok "已删除 $path"
-    }
-  }
-  # 细粒度删除 skills：只删 CodeForge 自己的 skill，不删用户自装的
-  $ownedSkills = @('ambiguity-gate', 'devils-advocate', 'ears-zh', 'example-mapping', 'success-criteria', 'weighted-dimensions')
-  foreach ($skillName in $ownedSkills) {
-    $skillPath = Join-Path $TargetRoot "skills\$skillName"
-    if (Test-Path -LiteralPath $skillPath) {
-      Invoke-Step "remove skill $skillName" {
-        Remove-Item -LiteralPath $skillPath -Recurse -Force
-      }
-      Write-Ok "已删除 skill: $skillPath"
-    }
-  }
-  Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
-  Write-Ok "卸载完成（opencode 自身、AGENTS.md、~/.config/codeforge/kh.json 不会被动）"
-}
-
-# ────────────── 环境检测 ──────────────
-function Test-Opencode {
-  $cmd = Get-Command opencode -ErrorAction SilentlyContinue
-  if ($cmd) {
-    try {
-      $v = & opencode --version 2>$null
-      Write-Ok "检测到 opencode: $v"
-    } catch {
-      Write-Ok "检测到 opencode (版本未知)"
-    }
-  } else {
-    Write-Warn2 "未检测到 opencode CLI"
-    Write-Warn2 "  安装方式：https://github.com/sst/opencode#installation"
-  }
-}
-
-function Test-KhMcp {
-  $xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { Join-Path $HOME '.config' }
-  $cfg = Join-Path (Join-Path $xdg 'opencode') 'opencode.json'
-  if ((Test-Path -LiteralPath $cfg) -and ((Get-Content -LiteralPath $cfg -Raw -Encoding UTF8) -match 'knowledge-hub|code-forge-knowledge-hub')) {
-    Write-Ok "检测到 Knowledge Hub MCP 已注册"
-  } else {
-    Write-Warn2 "未在 $cfg 中找到 Knowledge Hub MCP"
-    Write-Warn2 "  配置示例见 docs/PRD.md §6.2"
-  }
-}
-
-# ────────────── 主流程 ──────────────
-Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
-Write-Host "[codeforge] CodeForge installer  (mode=$Mode, uninstall=$Uninstall, dry-run=$DryRun)" -ForegroundColor Cyan
-Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
-Write-Host "Source : $SourceRoot"
-Write-Host "Target : $TargetRoot"
-Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
-
-if ($Uninstall) {
-  Invoke-Uninstall
-  exit 0
-}
-
-# Step 1/7: 环境检测
-Write-Section 'Step 1/7: 环境检测'
-Test-Opencode
-Test-KhMcp
-
-# Step 2/7: build dist bundle
-Write-Section 'Step 2/7: 构建 dist/index.js 单 bundle'
-$bundleSrc = Join-Path $SourceRoot $BundleSrcRel
-if ($SkipBuild) {
-  Write-Warn2 '已跳过 build（-SkipBuild），使用现有 dist/index.js'
-} else {
-  Invoke-Step "npm run build" {
-    Push-Location $SourceRoot
-    try {
-      $out = npm run build 2>&1 | Out-String
-      if ($LASTEXITCODE -ne 0) {
-        Write-Err2 'npm run build 失败'
-        Write-Host $out
-        exit 1
-      }
-    } finally {
-      Pop-Location
-    }
-  }
-}
-if (-not (Test-Path -LiteralPath $bundleSrc)) {
-  if ($SkipBuild) {
-    Write-Err2 "找不到 $bundleSrc（npm 包可能损坏）"
-    Write-Err2 "  请尝试重装：npx @andyqiu/codeforge install [--global]"
-  } else {
-    Write-Err2 "找不到 $bundleSrc，请先成功执行 npm run build"
-  }
-  exit 1
-}
-$bundleSize = (Get-Item -LiteralPath $bundleSrc).Length
-Write-Ok "bundle 已就绪: $bundleSrc ($([math]::Round($bundleSize/1024,1)) KB)"
-
-# Step 3/7: 准备目标目录
-Write-Section 'Step 3/7: 准备目标目录'
-if (-not (Test-Path -LiteralPath $TargetRoot)) {
-  Invoke-Step "mkdir $TargetRoot" {
-    New-Item -ItemType Directory -Path $TargetRoot -Force | Out-Null
-  }
-}
-# 清理 legacy 单数目录 + 老的 17 个 plugin / lib / tools junction
-foreach ($legacy in $LegacyDirs) {
-  $dst = Join-Path $TargetRoot $legacy
-  if (Test-Path -LiteralPath $dst) {
-    Invoke-Step "cleanup legacy $dst" {
-      $item = Get-Item -LiteralPath $dst -Force
-      if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
-        [IO.Directory]::Delete($dst, $false)
-      } else {
-        Remove-Item -LiteralPath $dst -Recurse -Force
-      }
-    }
-    Write-Warn2 "已清理 legacy 目录: $dst"
-  }
-}
-
-# Step 4/7: 装 bundle 到 codeforge/index.js
-Write-Section 'Step 4/7: 装入 dist/index.js bundle'
-$bundleDst = Join-Path $TargetRoot $BundleDstRel
-$bundleDstDir = Split-Path -Parent $bundleDst
-if (-not (Test-Path -LiteralPath $bundleDstDir)) {
-  Invoke-Step "mkdir $bundleDstDir" {
-    New-Item -ItemType Directory -Path $bundleDstDir -Force | Out-Null
-  }
-}
-Invoke-Step "copy $BundleSrcRel -> $BundleDstRel" {
-  Copy-Item -LiteralPath $bundleSrc -Destination $bundleDst -Force
-}
-Write-Ok "bundle -> $bundleDst"
-Add-PluginEntry
-
-# 写 VERSION marker 文件（用户 cat 一行查版本，不依赖 grep bundle）
-$cfVersion = "unknown"
-try {
-  $pkgPath = Join-Path $SourceRoot "package.json"
-  if (Test-Path -LiteralPath $pkgPath) {
-    $pkg = Get-Content -LiteralPath $pkgPath -Raw | ConvertFrom-Json
-    if ($pkg.version) { $cfVersion = $pkg.version }
-  }
-} catch { $cfVersion = "unknown" }
-$versionFile = Join-Path $TargetRoot "codeforge/VERSION"
-if (-not $DryRun) {
-  Set-Content -LiteralPath $versionFile -Value $cfVersion -NoNewline:$false -Encoding utf8
-}
-Write-Ok "VERSION -> $versionFile ($cfVersion)"
-
-# Step 5/7: 装 agents / commands / workflows / context-templates / review-profiles
-Write-Section 'Step 5/7: 装 agents / commands / workflows / context-templates / review-profiles'
-foreach ($entry in $MdCopyMap) {
-  $src = Join-Path $SourceRoot $entry.Src
-  $dst = Join-Path $TargetRoot $entry.Dst
-  if (-not (Test-Path -LiteralPath $src)) {
-    Write-Warn2 "源目录不存在，跳过: $src"
-    continue
-  }
-  if (Test-Path -LiteralPath $dst) {
-    Invoke-Step "cleanup old $dst" {
-      $item = Get-Item -LiteralPath $dst -Force
-      if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
-        [IO.Directory]::Delete($dst, $false)
-      } else {
-        Remove-Item -LiteralPath $dst -Recurse -Force
-      }
-    }
-  }
-  Invoke-Step "mkdir $dst" {
-    New-Item -ItemType Directory -Path $dst -Force | Out-Null
-  }
-  $files = Get-ChildItem -LiteralPath $src -Filter '*.md' -File | Where-Object {
-    $_.Name -ne 'README.md' -and
-    $_.Name -notmatch '^_' -and
-    $_.Name -notmatch '\.bak$' -and
-    $_.Name -notmatch '^\.'
-  }
-  foreach ($f in $files) {
-    Invoke-Step "copy $($entry.Src)/$($f.Name)" {
-      Copy-Item -LiteralPath $f.FullName -Destination (Join-Path $dst $f.Name) -Force
-    }
-  }
-  Write-Ok "$($entry.Src)/ -> $dst  ($($files.Count) 个 .md)"
-}
-foreach ($entry in $CopyMap) {
-  $src = Join-Path $SourceRoot $entry.Src
-  $dst = Join-Path $TargetRoot $entry.Dst
-  if (-not (Test-Path -LiteralPath $src)) {
-    Write-Warn2 "源目录不存在，跳过: $src"
-    continue
-  }
-  Invoke-Step "copy $($entry.Src)/ -> $dst" {
-    if (-not (Test-Path -LiteralPath $dst)) {
-      New-Item -ItemType Directory -Path $dst -Force | Out-Null
-    }
-    Copy-Item -Path (Join-Path $src '*') -Destination $dst -Recurse -Force
-  }
-  Write-Ok "$($entry.Src)/ -> $dst (整目录拷贝)"
-}
-
-# Step 5b/7: 装 skills/（opencode skill 目录）
-Write-Section 'Step 5b/7: 装 skills/'
-$skillsSrc = Join-Path $SourceRoot 'skills'
-$skillsDst = Join-Path $TargetRoot 'skills'
-if (Test-Path -LiteralPath $skillsSrc) {
-  if (-not (Test-Path -LiteralPath $skillsDst)) {
-    New-Item -ItemType Directory -Path $skillsDst -Force | Out-Null
-  }
-  $skillDirs = Get-ChildItem -LiteralPath $skillsSrc -Directory
-  $skillCount = 0
-  foreach ($skillDir in $skillDirs) {
-    $dstSkill = Join-Path $skillsDst $skillDir.Name
-    if (Test-Path -LiteralPath $dstSkill) {
-      Invoke-Step "remove old skill $($skillDir.Name)" {
-        Remove-Item -LiteralPath $dstSkill -Recurse -Force
-      }
-    }
-    Invoke-Step "copy skill $($skillDir.Name)" {
-      Copy-Item -LiteralPath $skillDir.FullName -Destination $dstSkill -Recurse -Force
-    }
-    $skillCount++
-  }
-  Write-Ok "skills/ -> $skillsDst  ($skillCount 个 skill)"
-} else {
-  Write-Warn2 "skills/ 目录不存在，跳过（发布包未含 skills）"
-}
-
-# Step 6/7: AGENTS.md 智能合并（仅项目模式）
-Write-Section 'Step 6/7: AGENTS.md 智能合并'
-if ($Mode -eq 'project') {
-  $agentsTarget = Join-Path (Get-Location).Path 'AGENTS.md'
-  $templatePath = Join-Path $SourceRoot $KhTemplateRel
-  Merge-ProjectAgentsMd -AgentsTarget $agentsTarget -TemplatePath $templatePath
-} else {
-  Write-Ok "全局模式：跳过项目 AGENTS.md 合并（context-templates 已装到 $TargetRoot\context-templates）"
-}
-
-# Step 7/7: KH 全局配置模板（仅 -Global）
-Write-Section 'Step 7/7: KH 全局配置模板'
-if ($Global) {
-  Write-KhTemplate
-} else {
-  Write-Ok "项目级安装，跳过 KH 全局模板（要装请加 -Global）"
-}
-
-# 验证清单
-Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
-Write-Ok "CodeForge v$cfVersion 安装完成"
-Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
-Write-Host @"
-验证清单：
-  1. 列出注入的扩展点：
-     PS> Get-ChildItem '$TargetRoot' -Force
-  2. 看 opencode.json 里 plugin entry：
-     PS> Get-Content '$TargetRoot\opencode.json'
-  3. 让 opencode 校验配置：
-     PS> opencode debug config
-     -> 期望看到 1 个 codeforge plugin entry（不是 17 个）
-  4. 跑一次最小 dogfood，看 plugin import + activation 日志：
-     PS> opencode run "hello"
-     PS> Get-Content `$HOME\.cache\codeforge\plugins.log -Tail 50
-  5. KH 配置（仅 -Global 安装时生成）：
-     PS> Get-Content '$CodeforgeCfgDir\kh.json'
-     PS> `$env:KNOWLEDGE_API_KEY = '<your-token>'   # ← API key 必须走环境变量
-  6. AGENTS.md 智能合并（仅项目级）：
-     - 已有 AGENTS.md → KH 块被替换成模板内容，原文件备份成 *.bak.<timestamp>
-     - 模板源：$SourceRoot\$KhTemplateRel（修改后请重新 install）
-
-卸载：
-  PS> .\install.ps1 -Uninstall$(if ($Global) { ' -Global' })
-"@
-Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
+<#
+.SYNOPSIS
+  CodeForge installer (PowerShell) — 零侵入安装到 opencode（v2 单 bundle 架构）
+
+.DESCRIPTION
+  CodeForge v0.1+ 改为 OMO 风格的单 plugin bundle 架构：
+    1. 17 个能力被 bun build 编译成 dist/index.js 一个 ESM bundle
+    2. 在 opencode.json 里只占 1 行 plugin entry
+    3. 永久避免 opencode 1.14+ 早期版本的 zod 跨实例 bug（issue #12336/#21155）
+
+  本脚本职责：
+    1. 检测 opencode CLI 与 KH MCP
+    2. 把 dist/index.js 复制到 ~/.config/opencode/codeforge/index.js
+    3. 在 ~/.config/opencode/opencode.json 的 "plugin" 数组追加 file:// URL
+    4. 把 agents/commands 用 file-by-file copy 注入（带白名单）
+    5. 把 workflows/context-templates/review-profiles 拷贝过去
+    5b. 把 skills/ 目录拷贝到 $TargetRoot/skills/（与 install.sh 对称）
+    6. 智能合并 AGENTS.md：
+       - 项目模式 + 已有 AGENTS.md → 替换 <!-- knowledge-hub:start -->...<!-- knowledge-hub:end --> 块（带 .bak 备份）
+       - 项目模式 + 无 AGENTS.md  → 生成含 marker 块的短版骨架
+       - 全局模式               → 跳过（context-templates 已经放进 ~/.config/opencode/context-templates/ 给所有项目复用）
+    7. -Global 时生成 ~/.config/codeforge/kh.json 模板（不含 token，硬约束 #2）
+    8. 输出验证清单
+
+.PARAMETER Global
+  装到全局 (~/.config/opencode/)，默认装到当前项目 (.opencode/)
+
+.PARAMETER Uninstall
+  卸载 CodeForge 注入物（不动 opencode 自身和 AGENTS.md，会清掉 opencode.json 里的 plugin entry）
+
+.PARAMETER DryRun
+  仅打印将要执行的操作，不真正执行
+
+.PARAMETER SkipBuild
+  跳过 npm run build。默认每次安装前会先 build 确保 dist 是最新的，加 -SkipBuild 跳过
+
+.EXAMPLE
+  .\install.ps1
+  .\install.ps1 -Global
+  .\install.ps1 -Uninstall
+  .\install.ps1 -DryRun
+  .\install.ps1 -SkipBuild
+#>
+[CmdletBinding()]
+param(
+  [switch]$Global,
+  [switch]$Uninstall,
+  [switch]$DryRun,
+  [switch]$SkipBuild
+)
+
+$ErrorActionPreference = 'Stop'
+
+# ────────────── 工具函数 ──────────────
+function Write-Section([string]$Text) {
+  Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
+  Write-Host "[codeforge] $Text" -ForegroundColor Cyan
+}
+function Write-Ok([string]$Text)   { Write-Host "$([char]0x2713) $Text" -ForegroundColor Green }
+function Write-Warn2([string]$Text) { Write-Host "$([char]0x26A0)  $Text" -ForegroundColor Yellow }
+function Write-Err2([string]$Text) { Write-Host "$([char]0x2717) $Text" -ForegroundColor Red }
+
+function Invoke-Step([string]$Description, [scriptblock]$Action) {
+  if ($DryRun) {
+    Write-Host "  [dry-run] $Description" -ForegroundColor Blue
+  } else {
+    & $Action
+  }
+}
+
+# ────────────── 路径解析 ──────────────
+$ScriptDir  = Split-Path -Parent $MyInvocation.MyCommand.Path
+$SourceRoot = $ScriptDir
+
+if ($Global) {
+  $XdgConfig = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { Join-Path $HOME '.config' }
+  $TargetRoot = Join-Path $XdgConfig 'opencode'
+  $Mode = 'global'
+} else {
+  $TargetRoot = Join-Path (Get-Location).Path '.opencode'
+  $Mode = 'project'
+}
+
+# CodeForge 自身的全局配置目录（与 opencode 配置目录同级）
+$XdgConfigBase = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { Join-Path $HOME '.config' }
+$CodeforgeCfgDir = Join-Path $XdgConfigBase 'codeforge'
+
+# v0.1 之前 install.ps1 装的目录（卸载时一并清掉）
+$LegacyDirs    = @('agent', 'command', 'tool', 'tools', 'plugin', 'plugins', 'lib')
+# v0.1+ 才有的目录（review-profiles 由 ADR:reviewer-multi-profile 引入）
+$ManagedDirs   = @('codeforge', 'agents', 'commands', 'workflows', 'context-templates', 'review-profiles')
+
+# v0.1+ 文件分发计划
+$BundleSrcRel  = 'dist/index.js'
+$BundleDstRel  = 'codeforge/index.js'   # 相对 $TargetRoot
+
+# B3 KH 行为规范模板（智能合并的输入）
+$KhTemplateRel = 'context-templates/kh-instructions.md'
+
+# .md file-by-file copy（白名单 *.md，排除 README/_*/.bak）
+$MdCopyMap = @(
+  @{ Src='agents';   Dst='agents'   },
+  @{ Src='commands'; Dst='commands' }
+)
+# 普通整目录 copy（review-profiles 由 ADR:reviewer-multi-profile 引入）
+$CopyMap = @(
+  @{ Src='workflows';         Dst='workflows'         },
+  @{ Src='context-templates'; Dst='context-templates' },
+  @{ Src='review-profiles';   Dst='review-profiles'   }
+)
+
+# ────────────── opencode.json 管理 ──────────────
+function Get-OpencodeConfigPath {
+  Join-Path $TargetRoot 'opencode.json'
+}
+
+function Get-PluginUri {
+  # opencode 接受 file:// URL 也接受裸绝对路径，统一用 file:// 更明确
+  $abs = Join-Path $TargetRoot $BundleDstRel
+  $abs = $abs -replace '\\', '/'
+  if ($abs -notmatch '^[A-Za-z]:/') {
+    return "file://$abs"
+  }
+  return "file:///$abs"
+}
+
+function Add-PluginEntry {
+  $cfgPath = Get-OpencodeConfigPath
+  $uri = Get-PluginUri
+
+  if (-not (Test-Path -LiteralPath $TargetRoot)) {
+    Invoke-Step "mkdir $TargetRoot" {
+      New-Item -ItemType Directory -Path $TargetRoot -Force | Out-Null
+    }
+  }
+
+  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    Write-Err2 "需要 node 才能改写 opencode.json，请安装 Node.js >= 20"
+    exit 1
+  }
+
+  Invoke-Step "write $cfgPath plugin entry: $uri" {
+    $env:CODEFORGE_CFG = $cfgPath
+    $env:CODEFORGE_URI = $uri
+    $nodeScript = @'
+const fs = require("node:fs");
+const path = process.env.CODEFORGE_CFG;
+const uri = process.env.CODEFORGE_URI;
+let cfg = {};
+if (fs.existsSync(path)) {
+  try { cfg = JSON.parse(fs.readFileSync(path, "utf8")); }
+  catch { fs.copyFileSync(path, path + ".bak." + Date.now()); cfg = {}; }
+}
+if (!cfg.$schema) cfg.$schema = "https://opencode.ai/config.json";
+if (!Array.isArray(cfg.plugin)) cfg.plugin = [];
+const cleaned = [];
+for (const e of cfg.plugin) {
+  const s = String(e);
+  if (/\/codeforge\/index\.js$/.test(s)) continue;
+  if (/\/plugins\/[^/]+\.ts$/.test(s) && /opencode/.test(s)) continue;
+  if (/\/\.opencode\/plugins\//.test(s)) continue;
+  cleaned.push(e);
+}
+cleaned.push(uri);
+cfg.plugin = cleaned;
+fs.writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+'@
+    & node -e $nodeScript
+    Remove-Item Env:\CODEFORGE_CFG -ErrorAction SilentlyContinue
+    Remove-Item Env:\CODEFORGE_URI -ErrorAction SilentlyContinue
+  }
+  Write-Ok "opencode.json 已写入 plugin entry: $uri"
+}
+
+function Remove-PluginEntry {
+  $cfgPath = Get-OpencodeConfigPath
+  if (-not (Test-Path -LiteralPath $cfgPath)) { return }
+  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    Write-Warn2 "未找到 node，跳过 opencode.json plugin entry 清理"
+    return
+  }
+
+  Invoke-Step "rewrite $cfgPath without codeforge plugin entry" {
+    $env:CODEFORGE_CFG = $cfgPath
+    $nodeScript = @'
+const fs = require("node:fs");
+const path = process.env.CODEFORGE_CFG;
+let cfg;
+try { cfg = JSON.parse(fs.readFileSync(path, "utf8")); }
+catch { return; }
+if (!Array.isArray(cfg.plugin)) return;
+cfg.plugin = cfg.plugin.filter(e => {
+  const s = String(e);
+  if (/\/codeforge\/index\.js$/.test(s)) return false;
+  if (/\/plugins\/[^/]+\.ts$/.test(s)) return false;
+  if (/\/\.opencode\/plugins\//.test(s)) return false;
+  return true;
+});
+fs.writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+'@
+    & node -e $nodeScript
+    Remove-Item Env:\CODEFORGE_CFG -ErrorAction SilentlyContinue
+  }
+  Write-Ok "opencode.json 已移除 codeforge plugin entry"
+}
+
+# ────────────── KH 全局模板（仅 -Global） ──────────────
+#
+# 硬约束 #2：API key 绝不能落盘，模板里**不写** token / apiKey 字段。
+# 用户必须通过环境变量 KNOWLEDGE_API_KEY 提供。
+# 已存在则跳过，避免覆盖用户自定义。
+function Write-KhTemplate {
+  $khFile = Join-Path $CodeforgeCfgDir 'kh.json'
+  if (-not (Test-Path -LiteralPath $CodeforgeCfgDir)) {
+    Invoke-Step "mkdir $CodeforgeCfgDir" {
+      New-Item -ItemType Directory -Path $CodeforgeCfgDir -Force | Out-Null
+    }
+  }
+  if (Test-Path -LiteralPath $khFile) {
+    Write-Ok "已存在 $khFile，跳过覆盖"
+    return
+  }
+  Invoke-Step "write $khFile (no token)" {
+    $body = @"
+{
+  "url": "http://10.5.60.26:8900/mcp",
+  "timeoutMs": 5000,
+  "maxRetries": 1
+}
+"@
+    # 用 .NET WriteAllText 强制无 BOM 的 UTF8（PowerShell 5.1 默认 BOM 会被 KhConfig 容错，但保持干净）
+    [System.IO.File]::WriteAllText($khFile, $body, (New-Object System.Text.UTF8Encoding $false))
+  }
+  Write-Ok "已生成 $khFile（API key 请通过环境变量 KNOWLEDGE_API_KEY 提供，禁止写入文件）"
+}
+
+# ────────────── AGENTS.md 智能合并（B3 新增） ──────────────
+#
+# 实现委托给 scripts/merge-agents-md.mjs CLI（C.4 单一入口），
+# 算法源自 lib/agents-merge.ts，sh/ps1 共用同一份 Node 实现，
+# 避免 install 脚本各自维护算法副本造成漂移。
+function Merge-ProjectAgentsMd {
+  param(
+    [Parameter(Mandatory=$true)] [string] $AgentsTarget,
+    [Parameter(Mandatory=$true)] [string] $TemplatePath
+  )
+  $cliPath = Join-Path $SourceRoot 'scripts/merge-agents-md.mjs'
+  if (-not (Test-Path -LiteralPath $TemplatePath)) {
+    Write-Warn2 "模板不存在，跳过 AGENTS.md 合并: $TemplatePath"
+    return
+  }
+  if (-not (Test-Path -LiteralPath $cliPath)) {
+    Write-Warn2 "merge CLI 不存在，跳过 AGENTS.md 智能合并: $cliPath"
+    return
+  }
+  if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    Write-Warn2 "未找到 node，跳过 AGENTS.md 智能合并（请安装 Node.js >= 20）"
+    return
+  }
+  $cliArgs = @('--target', $AgentsTarget, '--template', $TemplatePath)
+  if ($DryRun) { $cliArgs += '--dry-run' }
+  try {
+    & node $cliPath @cliArgs
+  } catch {
+    Write-Warn2 "AGENTS.md 合并失败（不阻塞 install 主流程）: $_"
+  }
+}
+
+# ────────────── 卸载 ──────────────
+function Invoke-Uninstall {
+  Write-Section "卸载 CodeForge from: $TargetRoot"
+  Remove-PluginEntry
+  $candidates = $LegacyDirs + $ManagedDirs | Select-Object -Unique
+  foreach ($name in $candidates) {
+    $path = Join-Path $TargetRoot $name
+    if (Test-Path -LiteralPath $path) {
+      Invoke-Step "remove $path" {
+        # Junction 不能用 Remove-Item 直接删（会删源），需要先 rmdir
+        $item = Get-Item -LiteralPath $path -Force
+        if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
+          [IO.Directory]::Delete($path, $false)
+        } else {
+          Remove-Item -LiteralPath $path -Recurse -Force
+        }
+      }
+      Write-Ok "已删除 $path"
+    }
+  }
+  # 细粒度删除 skills：只删 CodeForge 自己的 skill，不删用户自装的
+  $ownedSkills = @('ambiguity-gate', 'devils-advocate', 'ears-zh', 'example-mapping', 'success-criteria', 'weighted-dimensions')
+  foreach ($skillName in $ownedSkills) {
+    $skillPath = Join-Path $TargetRoot "skills\$skillName"
+    if (Test-Path -LiteralPath $skillPath) {
+      Invoke-Step "remove skill $skillName" {
+        Remove-Item -LiteralPath $skillPath -Recurse -Force
+      }
+      Write-Ok "已删除 skill: $skillPath"
+    }
+  }
+  Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
+  Write-Ok "卸载完成（opencode 自身、AGENTS.md、~/.config/codeforge/kh.json 不会被动）"
+}
+
+# ────────────── 环境检测 ──────────────
+function Test-Opencode {
+  $cmd = Get-Command opencode -ErrorAction SilentlyContinue
+  if ($cmd) {
+    try {
+      $v = & opencode --version 2>$null
+      Write-Ok "检测到 opencode: $v"
+    } catch {
+      Write-Ok "检测到 opencode (版本未知)"
+    }
+  } else {
+    Write-Warn2 "未检测到 opencode CLI"
+    Write-Warn2 "  安装方式：https://github.com/sst/opencode#installation"
+  }
+}
+
+function Test-KhMcp {
+  $xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { Join-Path $HOME '.config' }
+  $cfg = Join-Path (Join-Path $xdg 'opencode') 'opencode.json'
+  if ((Test-Path -LiteralPath $cfg) -and ((Get-Content -LiteralPath $cfg -Raw -Encoding UTF8) -match 'knowledge-hub|code-forge-knowledge-hub')) {
+    Write-Ok "检测到 Knowledge Hub MCP 已注册"
+  } else {
+    Write-Warn2 "未在 $cfg 中找到 Knowledge Hub MCP"
+    Write-Warn2 "  配置示例见 docs/PRD.md §6.2"
+  }
+}
+
+# ────────────── 主流程 ──────────────
+Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
+Write-Host "[codeforge] CodeForge installer  (mode=$Mode, uninstall=$Uninstall, dry-run=$DryRun)" -ForegroundColor Cyan
+Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
+Write-Host "Source : $SourceRoot"
+Write-Host "Target : $TargetRoot"
+Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
+
+if ($Uninstall) {
+  Invoke-Uninstall
+  exit 0
+}
+
+# Step 1/7: 环境检测
+Write-Section 'Step 1/7: 环境检测'
+Test-Opencode
+Test-KhMcp
+
+# Step 2/7: build dist bundle
+Write-Section 'Step 2/7: 构建 dist/index.js 单 bundle'
+$bundleSrc = Join-Path $SourceRoot $BundleSrcRel
+if ($SkipBuild) {
+  Write-Warn2 '已跳过 build（-SkipBuild），使用现有 dist/index.js'
+} else {
+  Invoke-Step "npm run build" {
+    Push-Location $SourceRoot
+    try {
+      $out = npm run build 2>&1 | Out-String
+      if ($LASTEXITCODE -ne 0) {
+        Write-Err2 'npm run build 失败'
+        Write-Host $out
+        exit 1
+      }
+    } finally {
+      Pop-Location
+    }
+  }
+}
+if (-not (Test-Path -LiteralPath $bundleSrc)) {
+  if ($SkipBuild) {
+    Write-Err2 "找不到 $bundleSrc（npm 包可能损坏）"
+    Write-Err2 "  请尝试重装：npx @andyqiu/codeforge install [--global]"
+  } else {
+    Write-Err2 "找不到 $bundleSrc，请先成功执行 npm run build"
+  }
+  exit 1
+}
+$bundleSize = (Get-Item -LiteralPath $bundleSrc).Length
+Write-Ok "bundle 已就绪: $bundleSrc ($([math]::Round($bundleSize/1024,1)) KB)"
+
+# Step 3/7: 准备目标目录
+Write-Section 'Step 3/7: 准备目标目录'
+if (-not (Test-Path -LiteralPath $TargetRoot)) {
+  Invoke-Step "mkdir $TargetRoot" {
+    New-Item -ItemType Directory -Path $TargetRoot -Force | Out-Null
+  }
+}
+# 清理 legacy 单数目录 + 老的 17 个 plugin / lib / tools junction
+foreach ($legacy in $LegacyDirs) {
+  $dst = Join-Path $TargetRoot $legacy
+  if (Test-Path -LiteralPath $dst) {
+    Invoke-Step "cleanup legacy $dst" {
+      $item = Get-Item -LiteralPath $dst -Force
+      if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
+        [IO.Directory]::Delete($dst, $false)
+      } else {
+        Remove-Item -LiteralPath $dst -Recurse -Force
+      }
+    }
+    Write-Warn2 "已清理 legacy 目录: $dst"
+  }
+}
+
+# Step 4/7: 装 bundle 到 codeforge/index.js
+Write-Section 'Step 4/7: 装入 dist/index.js bundle'
+$bundleDst = Join-Path $TargetRoot $BundleDstRel
+$bundleDstDir = Split-Path -Parent $bundleDst
+if (-not (Test-Path -LiteralPath $bundleDstDir)) {
+  Invoke-Step "mkdir $bundleDstDir" {
+    New-Item -ItemType Directory -Path $bundleDstDir -Force | Out-Null
+  }
+}
+Invoke-Step "copy $BundleSrcRel -> $BundleDstRel" {
+  Copy-Item -LiteralPath $bundleSrc -Destination $bundleDst -Force
+}
+Write-Ok "bundle -> $bundleDst"
+Add-PluginEntry
+
+# 写 VERSION marker 文件（用户 cat 一行查版本，不依赖 grep bundle）
+$cfVersion = "unknown"
+try {
+  $pkgPath = Join-Path $SourceRoot "package.json"
+  if (Test-Path -LiteralPath $pkgPath) {
+    $pkg = Get-Content -LiteralPath $pkgPath -Raw | ConvertFrom-Json
+    if ($pkg.version) { $cfVersion = $pkg.version }
+  }
+} catch { $cfVersion = "unknown" }
+$versionFile = Join-Path $TargetRoot "codeforge/VERSION"
+if (-not $DryRun) {
+  Set-Content -LiteralPath $versionFile -Value $cfVersion -NoNewline:$false -Encoding utf8
+}
+Write-Ok "VERSION -> $versionFile ($cfVersion)"
+
+# Step 5/7: 装 agents / commands / workflows / context-templates / review-profiles
+Write-Section 'Step 5/7: 装 agents / commands / workflows / context-templates / review-profiles'
+foreach ($entry in $MdCopyMap) {
+  $src = Join-Path $SourceRoot $entry.Src
+  $dst = Join-Path $TargetRoot $entry.Dst
+  if (-not (Test-Path -LiteralPath $src)) {
+    Write-Warn2 "源目录不存在，跳过: $src"
+    continue
+  }
+  if (Test-Path -LiteralPath $dst) {
+    Invoke-Step "cleanup old $dst" {
+      $item = Get-Item -LiteralPath $dst -Force
+      if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
+        [IO.Directory]::Delete($dst, $false)
+      } else {
+        Remove-Item -LiteralPath $dst -Recurse -Force
+      }
+    }
+  }
+  Invoke-Step "mkdir $dst" {
+    New-Item -ItemType Directory -Path $dst -Force | Out-Null
+  }
+  $files = Get-ChildItem -LiteralPath $src -Filter '*.md' -File | Where-Object {
+    $_.Name -ne 'README.md' -and
+    $_.Name -notmatch '^_' -and
+    $_.Name -notmatch '\.bak$' -and
+    $_.Name -notmatch '^\.'
+  }
+  foreach ($f in $files) {
+    Invoke-Step "copy $($entry.Src)/$($f.Name)" {
+      Copy-Item -LiteralPath $f.FullName -Destination (Join-Path $dst $f.Name) -Force
+    }
+  }
+  Write-Ok "$($entry.Src)/ -> $dst  ($($files.Count) 个 .md)"
+}
+foreach ($entry in $CopyMap) {
+  $src = Join-Path $SourceRoot $entry.Src
+  $dst = Join-Path $TargetRoot $entry.Dst
+  if (-not (Test-Path -LiteralPath $src)) {
+    Write-Warn2 "源目录不存在，跳过: $src"
+    continue
+  }
+  Invoke-Step "copy $($entry.Src)/ -> $dst" {
+    if (-not (Test-Path -LiteralPath $dst)) {
+      New-Item -ItemType Directory -Path $dst -Force | Out-Null
+    }
+    Copy-Item -Path (Join-Path $src '*') -Destination $dst -Recurse -Force
+  }
+  Write-Ok "$($entry.Src)/ -> $dst (整目录拷贝)"
+}
+
+# Step 5b/7: 装 skills/（opencode skill 目录）
+Write-Section 'Step 5b/7: 装 skills/'
+$skillsSrc = Join-Path $SourceRoot 'skills'
+$skillsDst = Join-Path $TargetRoot 'skills'
+if (Test-Path -LiteralPath $skillsSrc) {
+  if (-not (Test-Path -LiteralPath $skillsDst)) {
+    New-Item -ItemType Directory -Path $skillsDst -Force | Out-Null
+  }
+  $skillDirs = Get-ChildItem -LiteralPath $skillsSrc -Directory
+  $skillCount = 0
+  foreach ($skillDir in $skillDirs) {
+    $dstSkill = Join-Path $skillsDst $skillDir.Name
+    if (Test-Path -LiteralPath $dstSkill) {
+      Invoke-Step "remove old skill $($skillDir.Name)" {
+        Remove-Item -LiteralPath $dstSkill -Recurse -Force
+      }
+    }
+    Invoke-Step "copy skill $($skillDir.Name)" {
+      Copy-Item -LiteralPath $skillDir.FullName -Destination $dstSkill -Recurse -Force
+    }
+    $skillCount++
+  }
+  Write-Ok "skills/ -> $skillsDst  ($skillCount 个 skill)"
+} else {
+  Write-Warn2 "skills/ 目录不存在，跳过（发布包未含 skills）"
+}
+
+# Step 6/7: AGENTS.md 智能合并（仅项目模式）
+Write-Section 'Step 6/7: AGENTS.md 智能合并'
+if ($Mode -eq 'project') {
+  $agentsTarget = Join-Path (Get-Location).Path 'AGENTS.md'
+  $templatePath = Join-Path $SourceRoot $KhTemplateRel
+  Merge-ProjectAgentsMd -AgentsTarget $agentsTarget -TemplatePath $templatePath
+} else {
+  Write-Ok "全局模式：跳过项目 AGENTS.md 合并（context-templates 已装到 $TargetRoot\context-templates）"
+}
+
+# Step 7/7: KH 全局配置模板（仅 -Global）
+Write-Section 'Step 7/7: KH 全局配置模板'
+if ($Global) {
+  Write-KhTemplate
+} else {
+  Write-Ok "项目级安装，跳过 KH 全局模板（要装请加 -Global）"
+}
+
+# 验证清单
+Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
+Write-Ok "CodeForge v$cfVersion 安装完成"
+Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray
+Write-Host @"
+验证清单：
+  1. 列出注入的扩展点：
+     PS> Get-ChildItem '$TargetRoot' -Force
+  2. 看 opencode.json 里 plugin entry：
+     PS> Get-Content '$TargetRoot\opencode.json'
+  3. 让 opencode 校验配置：
+     PS> opencode debug config
+     -> 期望看到 1 个 codeforge plugin entry（不是 17 个）
+  4. 跑一次最小 dogfood，看 plugin import + activation 日志：
+     PS> opencode run "hello"
+     PS> Get-Content `$HOME\.cache\codeforge\plugins.log -Tail 50
+  5. KH 配置（仅 -Global 安装时生成）：
+     PS> Get-Content '$CodeforgeCfgDir\kh.json'
+     PS> `$env:KNOWLEDGE_API_KEY = '<your-token>'   # ← API key 必须走环境变量
+  6. AGENTS.md 智能合并（仅项目级）：
+     - 已有 AGENTS.md → KH 块被替换成模板内容，原文件备份成 *.bak.<timestamp>
+     - 模板源：$SourceRoot\$KhTemplateRel（修改后请重新 install）
+
+卸载：
+  PS> .\install.ps1 -Uninstall$(if ($Global) { ' -Global' })
+"@
+Write-Host '────────────────────────────────────────────────' -ForegroundColor DarkGray

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andyqiu/codeforge",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "CodeForge — opencode 的零侵入扩展包",
   "type": "module",
   "private": false,