add-coder 0.3.39 → 0.3.40

package/templates/core/docs/ADD-governance-vscode-copilot.md

@@ -93,6 +93,94 @@ VS Code Copilot hooks 产物位于 **项目根目录** 的 `.vscode/hooks/`（14
 
 ---
 
+## 工具可见性：VirtualTools 折叠（VS Code 用户必配项）
+
+> **一句话**：Copilot Chat 会在**所有 MCP 服务器的工具总数**越过阈值时把部分工具"折叠"成代理，未激活就调用会稳定误报 `currently disabled by the user`。必配项一劳永逸关掉折叠；降级流程用于尚未改设置的存量会话。
+> **证据来源**：[GitHub Issue #21](https://github.com/xiaomingming92/add-coder/issues/21)（含源码级根因定位与请求级工具快照对比）。
+
+### VS Code 用户必配项：关闭虚拟工具折叠
+
+把下面这行加进 **用户级 `settings.json`** 或 **工作区级 `.vscode/settings.json`**（二选一即可）：
+
+```json
+"github.copilot.chat.virtualTools.threshold": 0
+```
+
+已有 `settings.json` 的话，直接粘这一行进大括号内即可；从零建文件的完整形态：
+
+```json
+{
+  "github.copilot.chat.virtualTools.threshold": 0
+}
+```
+
+**设置语义**：
+
+| 项 | 值 |
+|---|---|
+| 归属 | GitHub Copilot Chat 扩展注册的实验设置（不在 VS Code core 设置里） |
+| 类型 / 取值域 | `number`，`0`–`128` |
+| 默认值 | `128` |
+| 设为 `0` 的含义 | 阈值 = ∞ ⇒ **虚拟工具折叠整体禁用** ⇒ 全部工具始终直连 |
+
+**触发条件（务必看清口径）**：折叠的判定基准是 **所有 MCP 服务器的工具总数 ≥ `threshold/2`**，默认即 **≥ 64 个工具**——**不是**单个服务器的工具数。
+
+- add-coder 自身注册 **47** 个工具；
+- 叠加常见扩展（Pylance 19 个、Java Debug、Python 等）后**必然越线**；
+- 因此任何 VS Code + Copilot Chat 用户都会遇到，与是否只装了 add-coder 无关。
+
+**生效方式**：改完设置后 **需重载 VS Code 窗口**（`Ctrl/Cmd+Shift+P` → `Developer: Reload Window`，或关闭重开）。只重开会话、或 reload 扩展都不会生效。
+
+**自查**：在 VS Code 项目下执行
+
+```bash
+npx add-coder status
+```
+
+未配置时会输出缺键告警与修复指引（只报告，不写你的设置文件）。
+
+### 工具假禁用的降级流程
+
+**症状**（未配置必配项时）：
+
+```
+ERROR: Tool mcp_<server>_<name> is currently disabled by the user, and cannot be called.
+```
+
+> ⚠️ **这是误报**：你从未在 UI 里禁用任何工具。真实原因是该工具被折叠进虚拟工具代理，而代理尚未被激活。
+
+**处置三步**：
+
+1. 在**当前会话的工具列表**里找描述含 `Contains the tools:` 字样的 `activate_fallback_*` 代理（形如 `activate_fallback_mcp_add-dev-tools_get_memory_1`）；
+2. 调用该代理 —— 返回文本会以 `Tools activated: ...` 列出它携带的成员工具；
+3. 重试原先失败的目标工具（本会话内有效）。
+
+> ⚠️ **代理名会变，勿缓存**：代理名由「折叠段首个工具名 + 树编号」拼成，会随会话槽位重算而**重构**（实测同一环境从 `get_memory` 组变为 `get_hook_events` 组，旧名字随即失效）。**每次都以当前工具列表为准**，不要把代理名写进脚本、提示词或笔记里复用。
+
+**受影响的治理工具族**（折叠按字母序裁掉后 N-1 个，治理工具恰好集中在字母序后半段）：
+
+| 工具族 | 具体工具 | 断链后果 |
+|---|---|---|
+| Plan 追踪 | `plan_track` / `plan_status` / `plan_sync` | 进度不落库、`tasks.md` 勾选无法同步 |
+| Review 追踪 | `review_track` / `review_status` / `review_sync` | P0/P1 缺陷无法入库与回写 |
+| 状态与人机审核 | `status_hitl` / `update_hitl` / `render_hitl_approval` | **审批无法落库** → TONGYI 哨兵不生成 → Plan/Review 写入被 PreToolUse 阻断 |
+| 审计链 | `record_dev_operation` / `query_audit_logs` | **ADD-7 开发操作审计断链**、稀疏推理恢复失效 |
+| 上下文与记忆 | `get_project_context` / `get_memory` | 会话恢复与记忆召回不可用 |
+| 关键字面 | `plan_*` / `review_*` / `status_*` / `update_*` | 上述族名的共同前缀，可用于快速判断"是不是折叠误伤" |
+
+**降级流程与必配项的关系**：降级流程是**临时手段**（仅本会话有效，下次开窗又要重新激活）；必配项是**根治**（一次配置，全部工具始终直连）。生产/日常使用请配置必配项。
+
+### 附录：为什么这是宿主问题（可据此向上游反馈）
+
+本问题**不是 add-coder 的实现缺陷**：折叠由 Copilot Chat 扩展自身的虚拟工具分组机制（源码内 `VirtualToolGrouper`，可通过 bundle 中 `Contains the tools:` 字样定位）触发；同为受害者的还有 **Pylance**（19 个工具中 14 个被折叠）、**Java Debug**、**Python** 等官方或知名扩展 —— 属宿主通用行为。
+
+可向上游反馈两点：
+
+1. **错误文案具误导性**：`disabled by the user` 会让用户去 UI 里找一个根本不存在的"禁用开关"，而真实原因是虚拟工具折叠未激活；建议文案区分"用户禁用"与"折叠未激活"两种状态。
+2. **折叠机制会命中 MCP 服务器的治理关键工具**：折叠按字母序裁剪，审批 / 审计类工具（`update_hitl` / `record_dev_operation` / `query_audit_logs` 等）恰好落在被裁区间，对大工具集 MCP 服务器造成可用性影响；建议折叠策略至少保证关键工具直连，或提供显式开关。
+
+---
+
 ## 自定义 Hook 源切换
 
 VS Code Copilot 的 `.vscode/hooks/*.mjs` 为 VS Code 原生 node 产物（14 入口）。项目同时产出 `.claude/` 目录（含 Claude Code 完整 hook 体系 + settings.json），两套体系可切换。

package/templates/core/governance/rules.ts

@@ -529,7 +529,7 @@ export const context = {
     {
       "id": "has_add_dev_unclosed",
       "consumed": true,
-      "text": "[ADD Stop] ⚠️ 代码已完成但验收未闭环:\n{{info}}\n\n请依次执行（不要等下次会话）:\n  ① Write devlog → handoff 同目录 devlog-{plan}-v{n}.md\n     格式: # Devlog: {plan}\\n 日期 / Plan / 轮次 / 本轮改了什么 / 验收结果 / 遗留项 / 架构回看\n  ② Edit handoff → 更新 §验证标准 全部 [x] + 补充审计 ID\n     ★ 同步: checklist 有新 cuid → handoff ADD-7 表必须对应新增行\n     ★ Step 0 准入: handoff + add-route + Specs 三元组缺一不可，缺则回退 Step 0.5\n  ③ Read docs/ → 回看架构文档确认一致性\n  ④ Edit add-route → 勾选对应 Step [x]\n\n以上全部完成后 Agent 才能停止。\n\n下次恢复: 读 handoff → 查同目录 devlog-*.md → query_audit_logs\n"
+      "text": "[ADD Stop] ⚠️ 代码已完成但验收未闭环:\n{{info}}\n\n请依次执行（不要等下次会话）:\n  ① Write devlog → 调用 `record_dev_operation`（MCP）落库审计；并把本轮验收记录（日期 / Plan / 轮次 / 改了什么 / 验收结果 / 遗留项 / 架构回看）写进 handoff 的验收段落——**不新建 devlog 文件**\n  ② Edit handoff → 更新 §验证标准 全部 [x] + 补充审计 ID（真实 cuid）\n     ★ 同步: checklist 有新 cuid → handoff ADD-7 表必须对应新增行\n     ★ Step 0 准入: handoff + add-route + Specs 三元组缺一不可，缺则回退 Step 0.5\n  ③ Read docs/ → 回看架构文档确认一致性\n  ④ Edit add-route → 勾选对应 Step [x]\n\n以上全部完成后 Agent 才能停止。\n\n下次恢复: 读 handoff → query_audit_logs({ planKeyword })（devlog 即 DevOperation 记录，无独立文件）\n"
     },
     {
       "id": "has_add_dev_closed",
@@ -541,7 +541,7 @@ export const context = {
     {
       "adapter": "qoder",
       "id": "has_add_dev_unclosed",
-      "text": "[ADD Stop] ⚠️ 代码已完成但验收未闭环:\n{{info}}\n\n请依次执行（不要等下次会话）:\n  ① Write devlog → handoff 同目录 devlog-{plan}-v{n}.md\n     格式: # Devlog: {plan}\\n 日期 / Plan / 轮次 / 本轮改了什么 / 验收结果 / 遗留项 / 架构回看\n  ② Edit handoff → 更新 §验证标准 全部 [x] + 补充审计 ID\n     ★ 同步: checklist 有新 cuid → handoff ADD-7 表必须对应新增行\n     ★ Step 0 准入: handoff + add-route + Specs 三元组缺一不可，缺则回退 Step 0.5\n  ③ Read docs/ → 回看架构文档确认一致性\n  ④ Edit add-route → 勾选对应 Step [x]\n\n以上全部完成后 Agent 才能停止。\n\n下次恢复: 读 handoff → 查同目录 devlog-*.md → query_audit_logs\n"
+      "text": "[ADD Stop] ⚠️ 代码已完成但验收未闭环:\n{{info}}\n\n请依次执行（不要等下次会话）:\n  ① Write devlog → 调用 `record_dev_operation`（MCP）落库审计；并把本轮验收记录（日期 / Plan / 轮次 / 改了什么 / 验收结果 / 遗留项 / 架构回看）写进 handoff 的验收段落——**不新建 devlog 文件**\n  ② Edit handoff → 更新 §验证标准 全部 [x] + 补充审计 ID（真实 cuid）\n     ★ 同步: checklist 有新 cuid → handoff ADD-7 表必须对应新增行\n     ★ Step 0 准入: handoff + add-route + Specs 三元组缺一不可，缺则回退 Step 0.5\n  ③ Read docs/ → 回看架构文档确认一致性\n  ④ Edit add-route → 勾选对应 Step [x]\n\n以上全部完成后 Agent 才能停止。\n\n下次恢复: 读 handoff → query_audit_logs({ planKeyword })（devlog 即 DevOperation 记录，无独立文件）\n"
     }
   ],
   "templates": {

package/templates/core/governance/session-start-guard.ts

@@ -108,19 +108,43 @@ export class SessionStartGuard {
    *   shadow → 仅提示快照存在（召回可执行并落审计，但不注入上下文）
    *   inject → 读预计算快照注入（新鲜度 ≤7 天，token 预算截断，带来源边界标签）
    * 同步 Hook ≤200ms 约束：只读文件，任何异常 fail-open 静默跳过。
+   *
+   * [2026-09-21 接线修复] 三态必须**可区分**，且"未接线/已过期"不再静默：
+   * 原实现 `if (!existsSync(file)) return` 会让"没跑 job"与"没有已治理记忆"、
+   * 以及"档位没开"三种情况在会话里完全无痕，用户与模型都无从判断记忆是否接上。
    */
   protected emitMemoryL1(): void {
     try {
       const mode = recallMode()
       if (mode === "off" || !this.magicDir) return
       const file = join(this.projectDir, this.magicDir, MEMORY_DIR_NAME, L1_SNAPSHOT_FILE)
-      if (!existsSync(file)) return
+      // ① 未接线：文件不存在（缺 job 入口 / 首次安装 / 从未刷新）
+      if (!existsSync(file)) {
+        process.stdout.write(
+          `[Memory] ⚠️ L1 快照未接线（${file} 不存在）——当前档位 ${mode}。` +
+          `生成快照：执行 \`npx add-coder sync\`、调用 MCP 工具 refresh_memory_snapshots、或运行 ` +
+          `\`${this.magicDir}/scripts/memory/memory-jobs.ts refresh-l1\`；` +
+          `注入开关：ADD_MEMORY_RECALL_MODE=inject（默认）。详见 ${this.magicDir}/docs/ADD-governance-codex.md\n`,
+        )
+        return
+      }
       if (mode === "shadow") {
-        process.stdout.write(`[Memory] L1 快照已生成（shadow 模式未注入）。需要时调用 recall_memory 显式召回: ${file}\n`)
+        process.stdout.write(
+          `[Memory] 当前档位 shadow：召回可执行并落审计，但**不注入**上下文（快照已生成: ${file}）。` +
+          `需要注入时去掉 ADD_MEMORY_RECALL_MODE 或设为 inject（默认）；也可直接调用 recall_memory 显式召回。\n`,
+        )
+        return
+      }
+      // ② 已接线但过期：inject 下不注入，但必须说明原因与刷新入口
+      const ageMs = Date.now() - statSync(file).mtimeMs
+      if (ageMs > L1_SNAPSHOT_TTL_MS) {
+        const days = Math.floor(ageMs / 86400000)
+        process.stdout.write(
+          `[Memory] ⚠️ L1 快照已过期（${days} 天 > TTL 7 天，未注入）：${file}` +
+          `——刷新：调用 refresh_memory_snapshots 或运行 \`${this.magicDir}/scripts/memory/memory-jobs.ts refresh-l1\`\n`,
+        )
         return
       }
-      // inject：过期快照不注入
-      if (Date.now() - statSync(file).mtimeMs > L1_SNAPSHOT_TTL_MS) return
       const text = readFileSync(file, "utf-8")
       const budget = memoryMaxTokens()
       if (estimateTokens(text) <= budget) {

package/templates/core/prisma/add.prisma

@@ -78,6 +78,7 @@ enum PlanLifecycleStatus {
   BLOCKED
   REJECTED
   CLOSED
+  REOPENED
   ABANDONED
 }
 
@@ -295,6 +296,9 @@ model AddMemory {
   topic           String
   content         String
   summary         String?
+  /// 检索展开文本（写入期产出：CJK bigram / jieba 词级 token 串，两侧共用同一 tokenization 契约）
+  /// 主通道索引 AddMemory_searchText_tsv_idx 建立在该列的 tsvector 表达式上（Plan Task 2.3）
+  searchText      String          @default("")
 
   scopeType       MemoryScopeType
   scopeValue      String

package/templates/core/scripts/mcp-server/resources/hitl-approval-widget.ts

@@ -5,13 +5,15 @@ import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import {
   HITL_APPROVAL_WIDGET_FILE,
   HITL_APPROVAL_WIDGET_MIME,
-  HITL_APPROVAL_WIDGET_URI,
+  getHitlApprovalWidgetUri,
 } from "../shared/hitl-ui.js"
 
 export function registerHitlApprovalWidgetResource(server: McpServer) {
+  // [2026-09-21 修复] 与工具 `_meta.ui.resourceUri` 共用同一函数（基名 + 内容哈希），保证两处严格一致
+  const WIDGET_URI = getHitlApprovalWidgetUri()
   server.registerResource(
     "hitl-approval-widget",
-    HITL_APPROVAL_WIDGET_URI,
+    WIDGET_URI,
     {
       title: "ADD HITL Approval",
       description: "逐项审核 ADD HITL 提案的 core 标准 widget",

package/templates/core/scripts/mcp-server/resources/index.ts

@@ -4,6 +4,7 @@ import { registerRoundTaskResources } from "./round-task.js"
 import { registerVersionResource } from "./add-coder-version.js"
 import { registerHookEventResources } from "./hook-events-report.js"
 import { registerHitlApprovalWidgetResource } from "./hitl-approval-widget.js"
+import { registerWidgetProbeResource } from "./widget-probe.js"
 
 export function registerAllResources(server: McpServer) {
   registerAddStateResources(server)
@@ -11,4 +12,5 @@ export function registerAllResources(server: McpServer) {
   registerVersionResource(server)
   registerHookEventResources(server)  // 2 resources: hook-events/{daily,weekly}
   registerHitlApprovalWidgetResource(server)
+  registerWidgetProbeResource(server)  // 1 resource: 最小 MCP Apps 渲染探针（诊断用）
 }

package/templates/core/scripts/mcp-server/resources/widget-probe.ts

@@ -0,0 +1,53 @@
+import type { McpServer } from "@modelcontextprotocol/server"
+
+/**
+ * 最小 MCP Apps 渲染探针（诊断用，2026-09-21 引入）。
+ *
+ * 背景：Codex 桌面端对 HITL 审批 widget 报 "This app couldn't be loaded"，而按 MCP 协议直连 server 的探针
+ * 证明 `resources/read` 能取到 widget（15128 字符、`text/html;profile=mcp-app`）——失败在宿主渲染阶段。
+ * 为把「宿主加载不了任何 app」与「我们 widget 自身有问题」分开，注册本资源：
+ *   · 无任何外部资源引用（无 script src / link / @import）
+ *   · 内联脚本只有 10 行、全程 try/catch，**不查任何业务 DOM id**，不外抛异常
+ *   · 页面文案会随加载阶段变化，观察文案即可定位：HTML 已加载（脚本未执行）/ 内联脚本已执行 / 脚本异常
+ * 配套工具 `probe_widget_render` 携带 `_meta.ui.resourceUri` 指向本资源，调用即触发宿主渲染。
+ */
+export const WIDGET_PROBE_URI = "ui://add-coder/widget-probe-minimal"
+export const WIDGET_PROBE_MIME = "text/html;profile=mcp-app"
+
+export const WIDGET_PROBE_HTML = [
+  "<!DOCTYPE html>",
+  '<html lang="zh-CN">',
+  "<head>",
+  '<meta charset="utf-8">',
+  "<title>ADD widget probe</title>",
+  "<style>body{font:14px/1.6 system-ui,sans-serif;margin:0;padding:12px}</style>",
+  "</head>",
+  "<body>",
+  '<div id="probe-msg">ADD widget probe: HTML 已加载（内联脚本未执行 ⇒ 疑似 CSP 拦截）</div>',
+  "<script>",
+  "try {",
+  '  var m = document.getElementById("probe-msg");',
+  '  m.textContent = "ADD widget probe: 内联脚本已执行";',
+  '  window.parent.postMessage({ jsonrpc: "2.0", id: 1, method: "ui/initialize", params: { protocolVersion: "2026-07-28" } }, "*");',
+  "} catch (e) {",
+  '  document.getElementById("probe-msg").textContent = "ADD widget probe: 脚本异常 " + e;',
+  "}",
+  "</script>",
+  "</body>",
+  "</html>",
+].join("\n")
+
+export function registerWidgetProbeResource(server: McpServer) {
+  server.registerResource(
+    "widget-probe-minimal",
+    WIDGET_PROBE_URI,
+    {
+      title: "ADD Widget Render Probe",
+      description: "最小 MCP Apps 渲染探针：区分「宿主加载不了任何 app」与「业务 widget 自身有问题」",
+      mimeType: WIDGET_PROBE_MIME,
+    },
+    (uri) => ({
+      contents: [{ uri: uri.href, mimeType: WIDGET_PROBE_MIME, text: WIDGET_PROBE_HTML }],
+    }),
+  )
+}

package/templates/core/scripts/mcp-server/shared/db-types.ts

@@ -15,6 +15,8 @@
  * 契约：schema 须与 prisma/add.prisma 模型对齐（字段名/可空性）。
  */
 import * as z from "zod/v4"
+// lifecycle 值的**唯一真源**（zod）：本文件不再手写字面量列表（2026-09-21 决策）
+import { PlanLifecycleStatusSchema } from "./plan-lifecycle.js"
 
 // ===== 行 schema（对齐 prisma/add.prisma；looseObject 前瞻兼容） =====
 
@@ -23,7 +25,7 @@ export const PlanRowSchema = z.looseObject({
   projectKey: z.string(),
   adapterKey: z.string(),
   planName: z.string(),
-  lifecycle: z.enum(["DRAFT", "ACTIVE", "BLOCKED", "REJECTED", "CLOSED", "ABANDONED"]),
+  lifecycle: PlanLifecycleStatusSchema,
   revision: z.number(),
   planPath: z.string(),
   planKeyword: z.string().nullable(),
@@ -164,6 +166,8 @@ export const AddMemoryRowSchema = z.looseObject({
   status: MemoryStatusSchema,
   topic: z.string(),
   content: z.string(),
+  /** 检索展开文本（写入期产出：jieba 词级 / bigram token 串）；主通道索引建立在该列 tsvector 表达式上 */
+  searchText: z.string().default(""),
   summary: z.string().nullable(),
   scopeType: MemoryScopeTypeSchema,
   scopeValue: z.string(),

package/templates/core/scripts/mcp-server/shared/dev-operation.ts

@@ -0,0 +1,97 @@
+/*
+ * dev-operation.ts — DevOperation（ADD-7 开发操作审计）写入的**唯一实现**
+ *
+ * 背景（2026-09-21 决策）：审计写入此前散成两份——`tools/audit.ts::record_dev_operation` 一份、
+ * 临时脚本 `scripts/plan-close.ts` 又手写一份（自己解析 AddUser + 直写）⇒ 典型的"同一能力两处实现"漂移。
+ * 现抽为本文件：**record_dev_operation / plan_update / 脚本** 三方共用，形状与幂等键语义完全一致。
+ *
+ * 幂等：`operationKey` 未提供时按 `{projectKey, producerAdapterKey, action, targetType, targetId,
+ * planKeyword, beforeState, afterState, reason}` 的规范化 JSON 取 sha256（与既有行为逐字一致，
+ * 不把 toolName 纳入 hash —— 换调用方不该产生新审计行）。落库按唯一键
+ * `projectKey_producerAdapterKey_toolName_operationKey` upsert（重复调用吸收）。
+ */
+import { createHash } from "node:crypto"
+import type { RuntimeContextKey } from "./runtime-context.js"
+
+export interface DevOperationWriterDatabase {
+  devOperation: {
+    upsert(args: Record<string, unknown>): Promise<DevOperationWrittenRow>
+  }
+  addUser: {
+    findUnique(args: Record<string, unknown>): Promise<{ id: string } | null>
+    create(args: Record<string, unknown>): Promise<{ id: string }>
+  }
+}
+
+export interface DevOperationWrittenRow {
+  id: string
+  operationKey: string
+  createdAt: Date
+  beforeState: unknown
+  afterState: unknown
+}
+
+export interface WriteDevOperationInput {
+  context: RuntimeContextKey
+  action: string
+  targetType: string
+  targetId?: string
+  planKeyword?: string
+  beforeState: Record<string, unknown> | unknown[]
+  afterState: Record<string, unknown> | unknown[]
+  reason?: string | null
+  operationKey?: string
+  /** 审计来源工具/脚本名；默认 record_dev_operation */
+  toolName?: string
+}
+
+/** 审计用户解析：先 ai-assistant，缺失则建；再退回库内首个用户；都没有则显式报错（不静默） */
+async function resolveAuditUserId(database: DevOperationWriterDatabase): Promise<string> {
+  const existing = await database.addUser.findUnique({ where: { username: "ai-assistant" }, select: { id: true } })
+  if (existing) return existing.id
+  const created = await database.addUser.create({
+    data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" },
+  })
+  return created.id
+}
+
+export async function writeDevOperation(
+  database: DevOperationWriterDatabase,
+  input: WriteDevOperationInput,
+): Promise<DevOperationWrittenRow> {
+  const toolName = input.toolName ?? "record_dev_operation"
+  const userId = await resolveAuditUserId(database)
+  const operationPayload = {
+    projectKey: input.context.projectKey,
+    producerAdapterKey: input.context.adapterKey,
+    action: input.action,
+    targetType: input.targetType,
+    targetId: input.targetId || "unknown",
+    planKeyword: input.planKeyword || "unknown",
+    beforeState: input.beforeState,
+    afterState: input.afterState,
+    reason: input.reason ?? null,
+  }
+  const operationKey =
+    (input.operationKey ?? "").trim() ||
+    createHash("sha256").update(JSON.stringify(operationPayload)).digest("hex")
+
+  return database.devOperation.upsert({
+    where: {
+      projectKey_producerAdapterKey_toolName_operationKey: {
+        projectKey: input.context.projectKey,
+        producerAdapterKey: input.context.adapterKey,
+        toolName,
+        operationKey,
+      },
+    },
+    create: {
+      ...operationPayload,
+      userId,
+      contextId: input.context.contextId,
+      toolName,
+      operationKey,
+    },
+    update: {},
+  })
+}

package/templates/core/scripts/mcp-server/shared/hitl-ui.ts

@@ -1,3 +1,48 @@
-export const HITL_APPROVAL_WIDGET_URI = "ui://add-coder/hitl-approval"
+import { createHash } from "node:crypto"
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { PROJECT_ROOT, MAGIC_DIR } from "./env.js"
+
 export const HITL_APPROVAL_WIDGET_MIME = "text/html;profile=mcp-app"
 export const HITL_APPROVAL_WIDGET_FILE = "hitl-approval-widget.html"
+
+/**
+ * 资源 URI **基名**（不含内容哈希）。
+ *
+ * [2026-09-21 修复] 宿主把 resource URI 当**缓存键**（官方 MCP Apps 规范：
+ * "Treat the resource URI as a cache key. When you make a breaking change to the HTML,
+ * JavaScript, or CSS, publish a new URI and update every tool that references it."）。
+ * 2026-09-18 改过 widget HTML 但 URI 未变，宿主命中旧缓存 ⇒ 实测 "This app couldn't be loaded"。
+ * 现改为**机制化**：最终 URI = 基名 + widget 内容短哈希（`getHitlApprovalWidgetUri()`），
+ * 改 HTML/JS/CSS 即自动换 URI，不再依赖人记得手动 bump。
+ */
+export const HITL_APPROVAL_WIDGET_URI_BASE = "ui://add-coder/hitl-approval"
+
+let cachedUri: string | null = null
+
+/** widget 内容短哈希（sha256 前 8 位）；文件缺失/不可读返回 ""（调用方回退静态基名） */
+export function computeWidgetContentHash(): string {
+  try {
+    const p = join(PROJECT_ROOT, MAGIC_DIR, "templates", HITL_APPROVAL_WIDGET_FILE)
+    if (!existsSync(p)) return ""
+    return createHash("sha256").update(readFileSync(p)).digest("hex").slice(0, 8)
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * 资源注册与工具 `_meta.ui.resourceUri` **共用**的 URI（进程内 memoize，保证两处完全一致）。
+ * 同一进程内若替换了 widget 文件，需重启 MCP server 才会换 URI（宿主本就要求重启后重读元数据）。
+ */
+export function getHitlApprovalWidgetUri(): string {
+  if (cachedUri) return cachedUri
+  const hash = computeWidgetContentHash()
+  cachedUri = hash ? `${HITL_APPROVAL_WIDGET_URI_BASE}-${hash}` : HITL_APPROVAL_WIDGET_URI_BASE
+  return cachedUri
+}
+
+/** 测试专用：清空 memo，使同一进程内可重新计算（生产路径不需要） */
+export function resetHitlApprovalWidgetUriCache(): void {
+  cachedUri = null
+}

package/templates/core/scripts/mcp-server/shared/memory/jobs/snapshot.ts

@@ -36,6 +36,15 @@ export function renderSnapshotMarkdown(level: "L1" | "L2", items: RecalledMemory
     `[Memory ${level} · 来源: AddMemory 治理库 · 生成于 ${generatedAt.toISOString()}]`,
     `<agent-memory source="add-memory" trust="governed">`,
   ]
+  // 空态显式标记（2026-09-21 接线 Plan Task 1.1.4）：
+  // 零条快照也必须可区分于"未接线"——否则文件不存在既可能是没跑 job、也可能是没有已治理记忆，自检无法判定。
+  if (items.length === 0) {
+    lines.push(
+      level === "L1"
+        ? "- 本仓库暂无已治理记忆（ACTIVE=0）：快照已接线，但尚无通过治理的记忆可注入"
+        : "- 本次查询未命中已治理记忆（ACTIVE=0）",
+    )
+  }
   for (const it of items) {
     lines.push(
       `- [${it.kind}] ${it.topic}（置信 ${it.confidence.toFixed(2)}）`,

package/templates/core/scripts/mcp-server/shared/memory/retrieval/cjk-segmenter.ts

@@ -0,0 +1,140 @@
+/*
+ * CJK 分词器（主通道 + 兜底）— Plan add-coder-memory-cjk-bigram-baseline 轮 4（人类裁决：完整上 jieba）
+ *
+ * 路线（与 farm-agent `src/lib/memory/cjk-segmenter.ts` 的 2026-09-18 人类裁定对齐）：
+ *   ① **jieba 为主**：`@node-rs/jieba`（native，optionalDependency）+ 可选用户词典；
+ *   ② **bigram 兜底**：`cjk-tokenize.ts`（纯函数、零依赖）——jieba 不可用时自动降级，**不是错误**。
+ *
+ * 为什么"主 + 兜底"而不是二选一：
+ *   · jieba 给的是**词级 token**（IDF/BM25 才有判别力、索引不膨胀），但依赖原生二进制与词典版本；
+ *   · bigram 是**地板**（1-2 字查询可索引、OOV 不惧、天然读写同源），但 token 数≈字符数、判别力弱；
+ *   · add-coder 的 memory 代码**模板分发到六端用户项目**，native 依赖在 pnpm 严格布局 / 非主流平台可能根本装不上
+ *     ⇒ 必须有一条"装不上也能跑"的路径，且**必须显式告知当前用的是哪条**（降级明示原则）。
+ *
+ * 契约：**写入侧与查询侧必须调用同一函数**（读写同源）；返回 `method` 供召回结果透出，
+ * `method === "bigram"` 即视为降级，须能被 `get_memory_health` / recall 审计观察到。
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { join } from "node:path"
+import { MAGIC_DIR, PROJECT_ROOT } from "../../env.js"
+import { expandForQuery, tokenize } from "./cjk-tokenize.js"
+
+export type SegmentMethod = "jieba" | "bigram"
+
+export interface SegmentResult {
+  /** token 数组（与写入侧同一实现产出） */
+  terms: string[]
+  /** 实际使用的分词器：`jieba` = 主通道；`bigram` = 兜底（降级） */
+  method: SegmentMethod
+  /** 用户词典是否已加载（仅 jieba 路径有意义） */
+  userDict?: boolean
+}
+
+/** 用户词典（可选注入）：每行一条术语，或 `术语 词频`（jieba 用户词典格式） */
+export const USER_DICT_PATH = ["data", "jieba", "userdict.txt"] as const
+
+interface JiebaLike {
+  cut(text: string, hmm?: boolean): string[]
+  cutForSearch(text: string, hmm?: boolean): string[]
+}
+
+let jieba: JiebaLike | null | undefined
+let userDictLoaded = false
+let loadFailureReason: string | null = null
+
+/**
+ * 构建实例：`@node-rs/jieba` v2 是 **class 形式** —— `Jieba.withDict(dict)`，
+ * 内置词典在子路径 `@node-rs/jieba/dict`（`Uint8Array`）；v2 未暴露 `addWord`，
+ * 故用户词典走「内置词典文本 + 追加用户行 → 合并 bytes」再 `withDict`。
+ */
+function buildJieba(req: NodeRequire): JiebaLike {
+  const { Jieba } = req("@node-rs/jieba") as { Jieba: { withDict: (dict: Uint8Array) => JiebaLike } }
+  const { dict } = req("@node-rs/jieba/dict") as { dict: Uint8Array }
+
+  const userPath = join(PROJECT_ROOT, MAGIC_DIR, ...USER_DICT_PATH)
+  if (existsSync(userPath)) {
+    try {
+      const userLines = readFileSync(userPath, "utf-8")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith("#"))
+      if (userLines.length > 0) {
+        const baseDictPath = req.resolve("@node-rs/jieba/dict.txt") as string
+        const merged = Buffer.concat([
+          readFileSync(baseDictPath),
+          Buffer.from("\n" + userLines.join("\n"), "utf8"),
+        ])
+        userDictLoaded = true
+        return Jieba.withDict(new Uint8Array(merged))
+      }
+    } catch (error) {
+      // 用户词典损坏 → 退回内置词典，但留下原因（禁止静默）
+      loadFailureReason = `userdict 读取失败（已退回内置词典）: ${error instanceof Error ? error.message : String(error)}`
+    }
+  }
+  return Jieba.withDict(dict)
+}
+
+function loadJieba(): JiebaLike | null {
+  if (jieba !== undefined) return jieba
+  try {
+    // 同步加载语义：@node-rs/jieba 导出同步 `cut`；用 createRequire 避免顶层 await 影响调用方。
+    // 注意：本模块是 ESM，**不能**用裸 `require`（运行时 ReferenceError 会被下面的 catch 吞掉 →
+    //      即使 jieba 装好了也会永远走兜底），必须用 node:module 的 createRequire。
+    const req = createRequire(import.meta.url)
+    jieba = buildJieba(req)
+  } catch (error) {
+    // 装不上（未声明 / 平台不匹配 / pnpm 严格布局不可达）→ 兜底，不抛错
+    jieba = null
+    loadFailureReason = error instanceof Error ? error.message : String(error)
+  }
+  return jieba
+}
+
+/** jieba 不可用时的原因（诊断用；`get_memory_health` / 召回审计可透出） */
+export function jiebaUnavailableReason(): string | null {
+  return loadFailureReason
+}
+
+/**
+ * 统一分词入口（**写入侧与查询侧都必须调它**）。
+ * jieba 可用 → 词级 token；不可用或切分为空 → bigram 兜底。
+ */
+export function segmentForMatch(text: string): SegmentResult {
+  const instance = loadJieba()
+  if (instance) {
+    try {
+      const terms = instance
+        // 检索场景用 `cutForSearch`：除整词外还产出子词（召回优先）
+        .cutForSearch(text, true)
+        .map((t) => t.trim().toLowerCase())
+        // 噪声过滤（2026-09-21 实测修正）：
+        //  · 必须含**字母/数字/CJK**——jieba 的 cutForSearch 会把 "：" "（" 这类标点也切出来，
+        //    而 bigram 契约只匹配 CJK 连续段，两者若不一致就会让索引里塞满无意义 token；
+        //  · 单字符拉丁（如 "地块A" 切出的 "a"）噪声大，丢弃；CJK 单字保留（与 bigram 契约一致）。
+        .filter((t) => /[\p{L}\p{N}]/u.test(t) && !(t.length === 1 && /^[\x00-\x7f]$/.test(t)))
+      if (terms.length > 0) {
+        return { terms: [...new Set(terms)], method: "jieba", userDict: userDictLoaded }
+      }
+      loadFailureReason = "jieba 切分返回空结果，已走 bigram 兜底"
+    } catch (error) {
+      // 切分异常 → 落到兜底，但记录原因（禁止静默降级）
+      loadFailureReason = `jieba 切分异常（已走 bigram 兜底）: ${error instanceof Error ? error.message : String(error)}`
+    }
+  }
+  return { terms: tokenize(text), method: "bigram" }
+}
+
+/** 文档侧：展开为空格分隔 token 串（写入期落 `searchText`），并回报所用分词器 */
+export function expandForIndexWithMethod(text: string): { text: string; method: SegmentMethod } {
+  const { terms, method } = segmentForMatch(text)
+  return { text: terms.join(" "), method }
+}
+
+/** 查询侧：token 数组（与 `expandForIndexWithMethod` 同一实现） */
+export function expandForQueryWithMethod(query: string): SegmentResult {
+  return segmentForMatch(query)
+}
+
+export { expandForQuery, tokenize }