sillyspec 3.26.10 → 3.26.13

package/src/dispatch/strategy.js

@@ -1,121 +1,121 @@
-/**
- * 派发策略生成器（task-dispatcher 抽象层）— task-02
- *
- * 定位（D-007 + UB-2）：dispatcher **不是 JS 执行体**。本文件 = **派发策略生成器**：
- * 依据 probe 结果选择后端（sillyhub / local），并把对应后端的派发指令模板组合成可注入
- * execute prompt 的「派发指令文本」，告诉 agent 用哪个后端、调什么 tool、传什么参数、
- * 怎么轮询与回收。**实际 tool 调用（本机 Agent tool / SillyHub MCP tool）由 agent 执行，
- * 本模块不 import client、不调任何 tool。**
- *
- * backend 选择（acceptance #1/#2，**由 probe.available 驱动，不由 isPathASupported 驱动**）：
- * - `probe.available === true` → backend = `'sillyhub'`（指令走 SillyHub MCP 模板）
- * - 否则（false / undefined / probe 为 null）→ backend = `'local'`（与现状行为一致，零回归）
- *
- * 路径 A 降级（D-003@v2）：`isPathASupported()` **不改 backend 标签**（仍由 probe 驱动），
- * 而是影响 SillyHub 指令的**文本内容**：path A 未支持时（当前 stub 恒 false），在 SillyHub
- * 主指令后附加降级提示段（PATH_A_DOWNGRADE_REASON + per-worker 回退 Local 说明），并始终追加
- * Local 兜底指令全文，让 agent 据此 per-worker 回退本机 Agent tool，不硬试 MCP 路径。
- *
- * 铁律（R-09 / UB-7 / D-004）：
- * - 纯函数：除 import 的模板生成器外无副作用，易测（task-08 mock probe 验两分支）。
- * - 指令必须明确**单后端**（backend 字段 + 文本只描述选定后端 + 兜底），避免 agent 误执行。
- * - allowedPaths 不物化到 SillyHub（仅写入指令供 SillySpec 侧 assess/apply 校验）——
- *   allowedPaths 由各后端模板在指令文本里声明，本策略不额外处理。
- * - 兼容 Win/Linux/macOS：无路径拼接 / 无平台分支，纯模板组合。
- */
-
-import { renderLocalInstruction } from './backends/local-agent.js';
-import {
-  isPathASupported,
-  renderSillyHubInstruction,
-  PATH_A_DOWNGRADE_REASON,
-} from './backends/sillyhub-mcp.js';
-
-/**
- * @typedef {import('./backends/local-agent.js').DispatchContract} DispatchContract
- * @see design.md「接口定义」DispatchContract：brief / worktreePath / branch / allowedPaths /
- *      readOnly / modelHint / agentProfileHint / runId / missionId
- */
-
-/**
- * @typedef {object} DispatchInstruction
- * @property {string} instruction - 注入 execute prompt 的派发指令文本（含选定后端 + 兜底）
- * @property {'sillyhub' | 'local'} backend - 选定后端标签（由 probe.available 驱动）
- */
-
-/**
- * 生成派发指令（注入 execute prompt，agent 据此执行派发）。
- *
- * 决策（D-007 + task-02 acceptance）：
- * 1. 解析 probe：`available = !!(probe && probe.available)`；probe 为 null/undefined/缺
- *    available 均视为 unavailable → local（零回归）。
- * 2. **backend = available ? 'sillyhub' : 'local'**（acceptance #1/#2，由 probe 驱动）。
- * 3. contract 兜底为 `{}`（renderLocalInstruction / renderSillyHubInstruction 内部已对
- *    缺字段回退醒目占位符，不会崩）。
- * 4. backend==='sillyhub'：
- *    - 主指令 = renderSillyHubInstruction(contract)（含轮询间隔 / kill lease 防双写 / 回收约定）
- *    - 若 !isPathASupported()：追加降级提示段（PATH_A_DOWNGRADE_REASON + per-worker 回退 Local）
- *    - **始终追加 Local 兜底指令全文**（implementation #4，保证可回退）
- * 5. backend==='local'：主指令 = renderLocalInstruction(contract)（与现状行为一致）
- *
- * 注：renderLocalInstruction / renderSillyHubInstruction 内部已自行替换
- * LOCAL_RECYCLE_RULE / SILLYHUB_RECYCLE_RULE 的 `<runId>` 占位符，本策略不重复替换；
- * 仅当额外引用含占位符的常量时才需替换，当前实现未额外引用，故无需处理。
- *
- * @param {DispatchContract} [contract] - 派发契约（缺省视为空对象，模板内部回退占位符）
- * @param {{ available?: boolean, reason?: string } | null} [probe] - probeSillyHub() 的结果
- * @returns {DispatchInstruction} `{ instruction, backend }`
- */
-export function renderDispatchInstruction(contract, probe) {
-  // 1. 解析 probe：null/undefined/缺 available 均视为 unavailable → local（零回归）
-  const available = !!(probe && probe.available);
-
-  // 2. backend 由 probe.available 驱动（acceptance #1/#2，不由 isPathASupported 驱动）
-  const backend = available ? 'sillyhub' : 'local';
-
-  // 3. contract 兜底（模板内部对缺字段已有醒目占位符处理，不会崩）
-  const c = contract || {};
-
-  if (backend === 'sillyhub') {
-    // SillyHub 主指令：含一 Wave 一 mission / dispatch_worker 参数 / 终态轮询间隔 / kill lease
-    // 防双写 / 回收约定（acceptance #3 轮询间隔与 kill lease 来自此模板）
-    const sillyHubInstruction = renderSillyHubInstruction(c);
-
-    // path A 未支持时的降级提示段（不改 backend 标签，仅追加文本，引导 agent per-worker 回退 Local）
-    const pathADowngrade = isPathASupported()
-      ? ''
-      : [
-          '',
-          '---',
-          '',
-          '### 路径 A 降级提示（per-worker 回退 Local）',
-          '',
-          `${PATH_A_DOWNGRADE_REASON}`,
-          '',
-          '本次派发 backend 标记仍为 `sillyhub`（由 probe 可达驱动，acceptance 要求不改标签），',
-          '但实际执行将回退 Local：agent 调 dispatch_worker 传 worktree_path 会被拒/忽略，',
-          '请 per-worker 回退本机 Agent tool（见下方 Local 兜底），不要硬试 MCP 路径。',
-          '',
-        ].join('\n');
-
-    // 始终追加 Local 兜底指令全文（implementation #4「始终附加 Local 兜底」）：
-    // 保证 SillyHub 路径任一步异常（dispatch 被拒 / 轮询超时 kill 后 fallback / path A 未落地）
-    // 时 agent 可立即改用本机 Agent tool 重派，零回归。
-    const localFallback = [
-      '',
-      '---',
-      '',
-      '### 兜底：Local（本机 Agent tool）— SillyHub 路径异常时回退',
-      '',
-      '当上方 SillyHub MCP 路径任一步失败，立即改用本机 Agent tool 重派该 task。',
-      'Local 后端派发指令全文如下（workdir 强制 = contract.worktreePath）：',
-      '',
-      renderLocalInstruction(c),
-    ].join('\n');
-
-    return { instruction: sillyHubInstruction + pathADowngrade + localFallback, backend };
-  }
-
-  // backend === 'local'：与现状行为一致（acceptance #2），probe 本就 unavailable，无需额外降级提示
-  return { instruction: renderLocalInstruction(c), backend };
-}
+/**
+ * 派发策略生成器（task-dispatcher 抽象层）— task-02
+ *
+ * 定位（D-007 + UB-2）：dispatcher **不是 JS 执行体**。本文件 = **派发策略生成器**：
+ * 依据 probe 结果选择后端（sillyhub / local），并把对应后端的派发指令模板组合成可注入
+ * execute prompt 的「派发指令文本」，告诉 agent 用哪个后端、调什么 tool、传什么参数、
+ * 怎么轮询与回收。**实际 tool 调用（本机 Agent tool / SillyHub MCP tool）由 agent 执行，
+ * 本模块不 import client、不调任何 tool。**
+ *
+ * backend 选择（acceptance #1/#2，**由 probe.available 驱动，不由 isPathASupported 驱动**）：
+ * - `probe.available === true` → backend = `'sillyhub'`（指令走 SillyHub MCP 模板）
+ * - 否则（false / undefined / probe 为 null）→ backend = `'local'`（与现状行为一致，零回归）
+ *
+ * 路径 A 降级（D-003@v2）：`isPathASupported()` **不改 backend 标签**（仍由 probe 驱动），
+ * 而是影响 SillyHub 指令的**文本内容**：path A 未支持时（当前 stub 恒 false），在 SillyHub
+ * 主指令后附加降级提示段（PATH_A_DOWNGRADE_REASON + per-worker 回退 Local 说明），并始终追加
+ * Local 兜底指令全文，让 agent 据此 per-worker 回退本机 Agent tool，不硬试 MCP 路径。
+ *
+ * 铁律（R-09 / UB-7 / D-004）：
+ * - 纯函数：除 import 的模板生成器外无副作用，易测（task-08 mock probe 验两分支）。
+ * - 指令必须明确**单后端**（backend 字段 + 文本只描述选定后端 + 兜底），避免 agent 误执行。
+ * - allowedPaths 不物化到 SillyHub（仅写入指令供 SillySpec 侧 assess/apply 校验）——
+ *   allowedPaths 由各后端模板在指令文本里声明，本策略不额外处理。
+ * - 兼容 Win/Linux/macOS：无路径拼接 / 无平台分支，纯模板组合。
+ */
+
+import { renderLocalInstruction } from './backends/local-agent.js';
+import {
+  isPathASupported,
+  renderSillyHubInstruction,
+  PATH_A_DOWNGRADE_REASON,
+} from './backends/sillyhub-mcp.js';
+
+/**
+ * @typedef {import('./backends/local-agent.js').DispatchContract} DispatchContract
+ * @see design.md「接口定义」DispatchContract：brief / worktreePath / branch / allowedPaths /
+ *      readOnly / modelHint / agentProfileHint / runId / missionId
+ */
+
+/**
+ * @typedef {object} DispatchInstruction
+ * @property {string} instruction - 注入 execute prompt 的派发指令文本（含选定后端 + 兜底）
+ * @property {'sillyhub' | 'local'} backend - 选定后端标签（由 probe.available 驱动）
+ */
+
+/**
+ * 生成派发指令（注入 execute prompt，agent 据此执行派发）。
+ *
+ * 决策（D-007 + task-02 acceptance）：
+ * 1. 解析 probe：`available = !!(probe && probe.available)`；probe 为 null/undefined/缺
+ *    available 均视为 unavailable → local（零回归）。
+ * 2. **backend = available ? 'sillyhub' : 'local'**（acceptance #1/#2，由 probe 驱动）。
+ * 3. contract 兜底为 `{}`（renderLocalInstruction / renderSillyHubInstruction 内部已对
+ *    缺字段回退醒目占位符，不会崩）。
+ * 4. backend==='sillyhub'：
+ *    - 主指令 = renderSillyHubInstruction(contract)（含轮询间隔 / kill lease 防双写 / 回收约定）
+ *    - 若 !isPathASupported()：追加降级提示段（PATH_A_DOWNGRADE_REASON + per-worker 回退 Local）
+ *    - **始终追加 Local 兜底指令全文**（implementation #4，保证可回退）
+ * 5. backend==='local'：主指令 = renderLocalInstruction(contract)（与现状行为一致）
+ *
+ * 注：renderLocalInstruction / renderSillyHubInstruction 内部已自行替换
+ * LOCAL_RECYCLE_RULE / SILLYHUB_RECYCLE_RULE 的 `<runId>` 占位符，本策略不重复替换；
+ * 仅当额外引用含占位符的常量时才需替换，当前实现未额外引用，故无需处理。
+ *
+ * @param {DispatchContract} [contract] - 派发契约（缺省视为空对象，模板内部回退占位符）
+ * @param {{ available?: boolean, reason?: string } | null} [probe] - probeSillyHub() 的结果
+ * @returns {DispatchInstruction} `{ instruction, backend }`
+ */
+export function renderDispatchInstruction(contract, probe) {
+  // 1. 解析 probe：null/undefined/缺 available 均视为 unavailable → local（零回归）
+  const available = !!(probe && probe.available);
+
+  // 2. backend 由 probe.available 驱动（acceptance #1/#2，不由 isPathASupported 驱动）
+  const backend = available ? 'sillyhub' : 'local';
+
+  // 3. contract 兜底（模板内部对缺字段已有醒目占位符处理，不会崩）
+  const c = contract || {};
+
+  if (backend === 'sillyhub') {
+    // SillyHub 主指令：含一 Wave 一 mission / dispatch_worker 参数 / 终态轮询间隔 / kill lease
+    // 防双写 / 回收约定（acceptance #3 轮询间隔与 kill lease 来自此模板）
+    const sillyHubInstruction = renderSillyHubInstruction(c);
+
+    // path A 未支持时的降级提示段（不改 backend 标签，仅追加文本，引导 agent per-worker 回退 Local）
+    const pathADowngrade = isPathASupported()
+      ? ''
+      : [
+          '',
+          '---',
+          '',
+          '### 路径 A 降级提示（per-worker 回退 Local）',
+          '',
+          `${PATH_A_DOWNGRADE_REASON}`,
+          '',
+          '本次派发 backend 标记仍为 `sillyhub`（由 probe 可达驱动，acceptance 要求不改标签），',
+          '但实际执行将回退 Local：agent 调 dispatch_worker 传 worktree_path 会被拒/忽略，',
+          '请 per-worker 回退本机 Agent tool（见下方 Local 兜底），不要硬试 MCP 路径。',
+          '',
+        ].join('\n');
+
+    // 始终追加 Local 兜底指令全文（implementation #4「始终附加 Local 兜底」）：
+    // 保证 SillyHub 路径任一步异常（dispatch 被拒 / 轮询超时 kill 后 fallback / path A 未落地）
+    // 时 agent 可立即改用本机 Agent tool 重派，零回归。
+    const localFallback = [
+      '',
+      '---',
+      '',
+      '### 兜底：Local（本机 Agent tool）— SillyHub 路径异常时回退',
+      '',
+      '当上方 SillyHub MCP 路径任一步失败，立即改用本机 Agent tool 重派该 task。',
+      'Local 后端派发指令全文如下（workdir 强制 = contract.worktreePath）：',
+      '',
+      renderLocalInstruction(c),
+    ].join('\n');
+
+    return { instruction: sillyHubInstruction + pathADowngrade + localFallback, backend };
+  }
+
+  // backend === 'local'：与现状行为一致（acceptance #2），probe 本就 unavailable，无需额外降级提示
+  return { instruction: renderLocalInstruction(c), backend };
+}

package/src/docs-check.js

@@ -9,15 +9,21 @@
  *
  * 纯函数（collectDocRefs/looksLikeCodeSymbol/validateRefLines/extractExpectedTokensFromLine）
  * 无 fs 依赖可单测；resolveCandidates/walkGlob/runDocsCheck 是 IO 面。
- * 只读校验（不修改任何被校验文件）；纯 Node 内置模块零依赖（D-008：glob 手写 walker，
+ * 校验链路只读（不修改任何被校验文件）；applyFixes 是唯一写回面（--fix 显式触发，design §9：
+ * 文档非多进程竞争的运行时文件，普通 writeFileSync）；纯 Node 内置模块零依赖（D-008：glob 手写 walker，
  * 仅「目录递归」「目录单层」「字面路径」三形态）；Windows 路径归一化；兼容 CRLF/LF。
  */
-import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import jsYaml from 'js-yaml'
 
-/** 提取 file.js:line / file.js:start-end 引用（.js/.mjs，反引号包裹与裸文本均命中，全文扫描 D-006） */
-const REF_RE = /([A-Za-z0-9_.\-\/]+\.(?:js|mjs)):(\d+)(?:-(\d+))?/g
+/** 提取 file.js:line / file.js:start-end 引用（.js/.mjs，反引号包裹与裸文本均命中，全文扫描 D-006）。
+ * repo:// 前缀（2026-08-20）：跨仓引用显式标记——`repo://<仓库名>/<路径>.js:行`。
+ * 不同设备兄弟仓库位置不同，未配映射时默认跳过本地校验（防跨设备误报）；
+ * 在本机 .sillyspec/local.yaml 的 docs-check.cross_repo_roots 配
+ * `<仓库名>: <本机绝对路径>` 后，走与本地引用完全相同的层1（行号边界）+ 层2（关键词窗口）校验。
+ * 正则组：1=仓库名（可选），2=文件，3=start，4=end。 */
+const REF_RE = /(?:repo:\/\/([A-Za-z0-9_.\-]+)\/)?([A-Za-z0-9_.\-\/]+\.(?:js|mjs)):(\d+)(?:-(\d+))?/g
 
 /** 缺省扫描范围：docs/ + .sillyspec/docs/（scan/modules 产物同是文档，失效即该暴露；2026-08-16 用户裁决改缺省，见 doc-consistency-debt.md §八） */
 const DEFAULT_DOC_PATHS = ['docs/**/*.md', '.sillyspec/docs/**/*.md']
@@ -25,10 +31,10 @@ const DEFAULT_DOC_PATHS = ['docs/**/*.md', '.sillyspec/docs/**/*.md']
 /**
  * 读 local.yaml 的 docs-check 段（best-effort，绝不抛；缺文件/无段 → 全缺省）。
  * @param {string} projectRoot 源码仓根（local.yaml 在 <root>/.sillyspec/local.yaml）
- * @returns {{ paths?: string[], skip: string[], keywordAssert: boolean }}
+ * @returns {{ paths?: string[], skip: string[], keywordAssert: boolean, crossRepoRoots: Record<string, string> }}
  */
 export function readDocsCheckConfig(projectRoot) {
-  const fallback = { paths: null, skip: [], keywordAssert: true }
+  const fallback = { paths: null, skip: [], keywordAssert: true, crossRepoRoots: {} }
   try {
     const p = join(projectRoot, '.sillyspec', 'local.yaml')
     if (!existsSync(p)) return fallback
@@ -36,10 +42,17 @@ export function readDocsCheckConfig(projectRoot) {
     if (!doc || typeof doc !== 'object') return fallback
     const dc = doc['docs-check']
     if (!dc || typeof dc !== 'object') return fallback
+    const crr = dc['cross_repo_roots']
     return {
       paths: Array.isArray(dc.paths) ? dc.paths.filter(s => typeof s === 'string') : null,
       skip: Array.isArray(dc.skip) ? dc.skip.filter(s => typeof s === 'string') : [],
       keywordAssert: typeof dc.keywordAssert === 'boolean' ? dc.keywordAssert : true,
+      // repo://<name> → 本机仓库根（每台设备各自配；local.yaml 是 gitignored，绝对路径不入库）
+      crossRepoRoots: crr && typeof crr === 'object' && !Array.isArray(crr)
+        ? Object.fromEntries(
+            Object.entries(crr).filter(([, v]) => typeof v === 'string' && v.trim() !== ''),
+          )
+        : {},
     }
   } catch {
     return fallback
@@ -62,9 +75,10 @@ export function collectDocRefs(md) {
   while ((m = re.exec(md)) !== null) {
     refs.push({
       ref: m[0],
-      file: m[1],
-      start: parseInt(m[2], 10),
-      end: m[3] !== undefined ? parseInt(m[3], 10) : parseInt(m[2], 10),
+      repo: m[1] !== undefined ? m[1] : null,
+      file: m[2],
+      start: parseInt(m[3], 10),
+      end: m[4] !== undefined ? parseInt(m[4], 10) : parseInt(m[3], 10),
       docLine: md.slice(0, m.index).split(/\r?\n/).length,
     })
   }
@@ -267,16 +281,20 @@ function relDisplay(absPath, projectRoot) {
 
 /**
  * IO 入口：跑一次完整校验。
- * @param {{ projectRoot: string, docs?: string[], paths?: string[], skip?: string[], keywordAssert?: boolean }} opts
+ * @param {{ projectRoot: string, docs?: string[], paths?: string[], skip?: string[], keywordAssert?: boolean, crossRepoRoots?: Record<string, string> }} opts
  *   projectRoot 源码仓根（候选解析与 glob 的锚点，平台模式也传源码仓根）
  *   docs 显式文档相对路径列表（优先于 paths glob 展开结果）
- * @returns {{ ok: boolean, total: number, invalid: Array<{doc, docLine, ref, reason}>, warnings: string[], kwChecked: number }}
+ *   crossRepoRoots repo://<仓库名> → 本机仓库根映射（未映射的跨仓引用跳过不计失效）
+ * @returns {{ ok: boolean, total: number, invalid: Array<{doc, docLine, ref, reason, suggest?: number[], fix: {fixable: boolean, newLine?: number, reason: string}}>, warnings: string[], kwChecked: number, crossRepoSkipped: number }}
  * @throws {DocsCheckConfigError} glob 形态不支持
  */
 export function runDocsCheck(opts) {
   // paths/docs 显式传 null（readDocsCheckConfig 无 local.yaml 段时的回退值）须落回缺省 glob，
   // 解构默认值只挡 undefined 不挡 null——docs-check 无配置裸跑曾因此 null.flatMap 崩溃。
-  const { projectRoot, docs = null, paths: rawPaths = DEFAULT_DOC_PATHS, skip = [], keywordAssert = true } = opts || {}
+  const {
+    projectRoot, docs = null, paths: rawPaths = DEFAULT_DOC_PATHS, skip = [],
+    keywordAssert = true, crossRepoRoots = {},
+  } = opts || {}
   const paths = Array.isArray(rawPaths) && rawPaths.length > 0 ? rawPaths : DEFAULT_DOC_PATHS
   const warnings = []
   if (keywordAssert === false) warnings.push('关键词断言已关闭（keywordAssert=false），仅做存在性校验')
@@ -287,11 +305,16 @@ export function runDocsCheck(opts) {
   const invalid = []
   let total = 0
   let kwChecked = 0
+  // repo:// 跨仓引用：未配映射被跳过的数量（不计入 total/invalid，跨设备零误报）
+  let crossRepoSkipped = 0
 
   for (const docRel of docFiles) {
     const docAbs = join(projectRoot, docRel)
     if (!existsSync(docAbs)) {
-      invalid.push({ doc: docRel, docLine: 0, ref: '', reason: '文档不存在' })
+      invalid.push({
+        doc: docRel, docLine: 0, ref: '', reason: '文档不存在',
+        fix: { fixable: false, reason: '文档不存在，无法自动定位' },
+      })
       continue
     }
     const md = readFileSync(docAbs, 'utf8')
@@ -299,12 +322,37 @@ export function runDocsCheck(opts) {
     const mdLines = md.split(/\r?\n/)
 
     for (const r of refs) {
+      // repo:// 跨仓引用：未配映射 → 跳过（不同设备仓库位置不同，不按本仓解析误报）；
+      // 配了映射 → 以映射根为唯一候选，走与本地引用相同的层1+层2 校验。
+      let candidates
+      if (r.repo) {
+        const repoRoot = crossRepoRoots && typeof crossRepoRoots[r.repo] === 'string'
+          ? crossRepoRoots[r.repo]
+          : null
+        if (!repoRoot) {
+          crossRepoSkipped++
+          continue
+        }
+        const abs = join(repoRoot, r.file)
+        if (!existsSync(abs)) {
+          total++
+          invalid.push({
+            doc: docRel, docLine: r.docLine, ref: r.ref,
+            reason: `跨仓 repo://${r.repo} → 文件不存在（cross_repo_roots 映射根：${repoRoot}）`,
+            fix: { fixable: false, reason: '跨仓引用无法自动定位' },
+          })
+          continue
+        }
+        candidates = [abs]
+      } else {
+        candidates = resolveCandidates(projectRoot, r.file)
+      }
       total++
-      const candidates = resolveCandidates(projectRoot, r.file)
       if (candidates.length === 0) {
         invalid.push({
           doc: docRel, docLine: r.docLine, ref: r.ref,
           reason: '文件不存在（含 / 按仓库根解析；裸文件名在 src/ 递归）',
+          fix: { fixable: false, reason: '文件不存在，无法自动定位' },
         })
         continue
       }
@@ -333,17 +381,21 @@ export function runDocsCheck(opts) {
       }
       if (tokens.length > 0) kwChecked++
       if (!passedAny) {
+        // 跨仓校验失败的 reason 加 repo:// 前缀，用户一眼区分「改外部仓引用」还是「改本仓引用」
+        const repoPrefix = r.repo ? `跨仓 repo://${r.repo} → ` : ''
         invalid.push({
           doc: docRel, docLine: r.docLine, ref: r.ref,
-          reason: candidateFails.length > 1 ? `多候选全失败 → ${candidateFails.join(' | ')}` : candidateFails[0],
+          reason: repoPrefix + (candidateFails.length > 1 ? `多候选全失败 → ${candidateFails.join(' | ')}` : candidateFails[0]),
           // 建议行号（--suggest）：token 在首个候选文件的全量命中行，供人工确认改锚——不自动改文件
           suggest: suggestLines(candidates, tokens),
+          // 修复分类（--fix 判定依据）：全量候选 token 命中统计，唯一命中才 fixable（D-006 保守默认）
+          fix: classifyFix(candidates, tokens),
         })
       }
     }
   }
 
-  return { ok: invalid.length === 0, total, invalid, warnings, kwChecked }
+  return { ok: invalid.length === 0, total, invalid, warnings, kwChecked, crossRepoSkipped }
 }
 
 /**
@@ -360,3 +412,123 @@ function suggestLines(candidates, tokens) {
     return out.slice(0, 8)
   } catch { return [] }
 }
+
+/**
+ * 修复分类（--fix 判定依据）：对 resolveCandidates 全量候选跑 token 命中统计，跨候选合并行号后——
+ *   唯一命中 → fixable=true + newLine（自动重锚唯一解）；无 token / 零命中 / 多命中 → needs-manual。
+ * 与 suggestLines 的差异：suggest 只查首个候选（candidates[0]），本函数查全量候选（design §12 自审存疑 +
+ * R-01——多候选同名文件场景下防止定位到另一文件的同名符号）。合并口径按「去重后的行号集合」：
+ * 重锚写回的目标是行号，多个候选命中同一行号仍是唯一改写目标。
+ * 纯增量分类，不参与层1/层2 判定（D-004 兼容红线）。
+ * @param {string[]} candidates resolveCandidates 返回的全量候选绝对路径
+ * @param {string[]} tokens 层2 提取的期望 token（keywordAssert=false 时为空数组）
+ * @returns {{ fixable: boolean, newLine?: number, reason: string }}
+ */
+function classifyFix(candidates, tokens) {
+  if (tokens.length === 0) {
+    return { fixable: false, reason: '无 token 符号线索（纯位置引用或关键词断言关闭），无法自动定位' }
+  }
+  const hitLines = new Set()
+  for (const candAbs of candidates) {
+    const lines = readLines(candAbs)
+    if (lines === null) continue
+    lines.forEach((l, i) => { if (tokens.some((t) => l.includes(t))) hitLines.add(i + 1) })
+  }
+  if (hitLines.size === 0) {
+    return { fixable: false, reason: 'token 在全量候选文件零命中，无法自动定位' }
+  }
+  if (hitLines.size === 1) {
+    return { fixable: true, newLine: [...hitLines][0], reason: 'token 在全量候选唯一命中，可自动重锚' }
+  }
+  const sorted = [...hitLines].sort((a, b) => a - b)
+  const shown = sorted.slice(0, 8).join('、') + (sorted.length > 8 ? '…' : '')
+  return { fixable: false, reason: `token 多处命中（候选行号：${shown}），歧义需人工确认（D-006 保守默认）` }
+}
+
+/**
+ * 将可确定性修复的失效引用写回文档（--fix 消费面，design §7 接口逐字）。
+ * 纯机械定点替换：按 docLine + ref 串在该行内的字符偏移替换为 newRef，不解析行号语义、
+ * 不改引用文件名与 token（D-003：ref/newRef 一致性由调用方保证）；候选定位全部依赖调用方
+ * 传入（不读 local.yaml 不解析配置）。范围引用（src/a.js:3-8）newRef 同样由调用方给全串。
+ * 同一行多个 fix 按行内偏移从后往前（降序）替换，防前序替换挤偏后序偏移（R-04）；
+ * 其余字节不动：行内容只动命中片段，行结束符按原文（\r\n / \n 整文件统一口径）原样 join（R-05）。
+ * @param {string} projectRoot 源码仓根（doc 相对路径的锚点）
+ * @param {Array<{doc: string, docLine: number, ref: string, newRef: string}>} fixes
+ *   doc 为相对 projectRoot 的文档路径；ref 旧引用串（如 src/a.js:6），newRef 新引用串（如 src/a.js:1）
+ * @param {{dryRun?: boolean}} opts dryRun 为真时不写盘仅返回将应用列表
+ * @returns {{applied: number, skipped: Array<{ref: string, reason: string}>}}
+ *   dryRun 时 applied 为「将应用」计数；skipped 条目含 ref 与可读 reason（文档不存在/docLine 越界/
+ *   行内找不到 ref 串），跳过不中断批量
+ */
+export function applyFixes(projectRoot, fixes, opts = {}) {
+  const dryRun = opts.dryRun === true
+  let applied = 0
+  const skipped = []
+  if (!Array.isArray(fixes) || fixes.length === 0) return { applied, skipped }
+
+  // 按 doc 分组，每文档一次读改写（design §9：普通 writeFileSync，文档非运行时竞争文件）
+  const byDoc = new Map()
+  for (const f of fixes) {
+    if (!f || typeof f !== 'object' || typeof f.doc !== 'string' || typeof f.docLine !== 'number' ||
+      typeof f.ref !== 'string' || typeof f.newRef !== 'string') {
+      skipped.push({ ref: f && typeof f.ref === 'string' ? f.ref : '(条目缺失)', reason: 'fix 条目字段不完整（doc/docLine/ref/newRef）' })
+      continue
+    }
+    if (!byDoc.has(f.doc)) byDoc.set(f.doc, [])
+    byDoc.get(f.doc).push(f)
+  }
+
+  for (const [docRel, docFixes] of byDoc) {
+    const docAbs = join(projectRoot, docRel)
+    if (!existsSync(docAbs)) {
+      for (const f of docFixes) skipped.push({ ref: f.ref, reason: `文档不存在：${docRel}` })
+      continue
+    }
+    const raw = readFileSync(docAbs, 'utf8')
+    // 行结束符检测整文件统一口径（R-05）：原文含 \r\n 则 CRLF join，否则 LF——与 readLines 归一逻辑一致
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n'
+    const lines = raw.split(/\r?\n/)
+    let dirty = false
+
+    // 同一 docLine 的多 fix 按行内偏移从后往前替换（R-04）：先按 docLine 分组，
+    // 组内按 ref 在该行内的命中偏移降序逐个定点替换
+    const byLine = new Map()
+    for (const f of docFixes) {
+      if (!byLine.has(f.docLine)) byLine.set(f.docLine, [])
+      byLine.get(f.docLine).push(f)
+    }
+    for (const [docLine, lineFixes] of byLine) {
+      if (!Number.isInteger(docLine) || docLine < 1 || docLine > lines.length) {
+        for (const f of lineFixes) skipped.push({ ref: f.ref, reason: `docLine=${docLine} 越界（文档共 ${lines.length} 行）` })
+        continue
+      }
+      const li = docLine - 1
+      const located = []
+      let cursor = 0
+      for (const f of lineFixes) {
+        // 找不到 ref 串、或两次命中同一偏移（重复 fix），该条目跳过不中断批量
+        const at = lines[li].indexOf(f.ref, cursor)
+        if (at === -1) {
+          skipped.push({ ref: f.ref, reason: `docLine=${docLine} 行内未找到引用串` })
+        } else {
+          located.push({ at, f })
+          cursor = at + f.ref.length
+        }
+      }
+      located.sort((a, b) => b.at - a.at) // 降序：后位先替换，前序替换不挤偏后序偏移
+      let line = lines[li]
+      for (const { at, f } of located) {
+        line = line.slice(0, at) + f.newRef + line.slice(at + f.ref.length)
+        applied++
+      }
+      if (located.length > 0) {
+        lines[li] = line
+        dirty = true
+      }
+    }
+
+    if (dirty && !dryRun) writeFileSync(docAbs, lines.join(eol))
+  }
+
+  return { applied, skipped }
+}

package/src/docs-debt.js

@@ -14,7 +14,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { safeGit } from './git-helper.js'
 import { parseModuleMapSimple } from './modules.js'
-import { runDocsCheck } from './docs-check.js'
+import { runDocsCheck, readDocsCheckConfig } from './docs-check.js'
 
 /** safeGit 超时（大仓 git log 慢时降级该模块，不挂起 Wave 渲染） */
 const GIT_TIMEOUT_MS = 5000
@@ -212,7 +212,11 @@ function inlineCardInvalidRefs(entry, docGitRoot, docPathPrefix) {
   if (!docGitRoot || !docPathPrefix || !entry.doc) return null
   try {
     const docGitPath = `${docPathPrefix}/${entry.doc.replace(/^modules\//, '')}`
-    const check = runDocsCheck({ projectRoot: docGitRoot, docs: [docGitPath] })
+    // HUB-06：补传 crossRepoRoots（与 docs gate 同口径），repo:// 跨仓引用不再恒跳过；
+    // 配置读取失败（无 local.yaml 段等）→ 不启用跨仓，与原行为一致
+    let crossRepoRoots
+    try { crossRepoRoots = readDocsCheckConfig(docGitRoot)?.crossRepoRoots } catch { crossRepoRoots = undefined }
+    const check = runDocsCheck({ projectRoot: docGitRoot, docs: [docGitPath], crossRepoRoots })
     if (check.ok || !Array.isArray(check.invalid) || check.invalid.length === 0) return null
     const parts = check.invalid.slice(0, 3).map((inv) => {
       const sug = Array.isArray(inv.suggest) && inv.suggest.length > 0 ? `→建议 L${inv.suggest.join('/L')}` : ''

package/src/docs-gate.js

@@ -76,6 +76,7 @@ export async function runDocsGate(opts = {}, checkOpts = {}) {
       paths: checkOpts.paths || cfg.paths,
       skip: checkOpts.skip || cfg.skip,
       keywordAssert: checkOpts.keywordAssert ?? cfg.keywordAssert,
+      crossRepoRoots: checkOpts.crossRepoRoots || cfg.crossRepoRoots,
     });
   } catch (e) {
     if (e instanceof DocsCheckConfigError) {