@andyqiu/codeforge 0.3.12 → 0.3.13

package/install.ps1

@@ -1,516 +1,555 @@
-<#
-.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 拷贝过去
-    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+ 才有的目录
-$ManagedDirs   = @('codeforge', 'agents', 'commands', 'workflows', 'context-templates')
-
-# 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
-$CopyMap = @(
-  @{ Src='workflows';         Dst='workflows'         },
-  @{ Src='context-templates'; Dst='context-templates' }
-)
-
-# ────────────── 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"
-    }
-  }
-  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
-Write-Section 'Step 5/7: 装 agents / commands / workflows / context-templates'
-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 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 拷贝过去
+    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+ 才有的目录
+$ManagedDirs   = @('codeforge', 'agents', 'commands', 'workflows', 'context-templates')
+
+# 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
+$CopyMap = @(
+  @{ Src='workflows';         Dst='workflows'         },
+  @{ Src='context-templates'; Dst='context-templates' }
+)
+
+# ────────────── 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
+Write-Section 'Step 5/7: 装 agents / commands / workflows / context-templates'
+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