sillyspec 3.26.11 → 3.26.13

package/src/dispatch/probe.js

@@ -22,6 +22,13 @@ import { setPathAProbeResult } from './backends/sillyhub-mcp.js';
 /** 默认负面缓存 TTL（毫秒）。可被 local.yaml dispatch.probe_ttl_ms 或 ttlMs 参数覆盖。 */
 export const DEFAULT_PROBE_TTL_MS = 60_000;
 
+/**
+ * HUB-12a：probe 总超时。链路最坏 initialize(10s) + tools/call(10s) + tools/list(10s) 串行，
+ * 慢/挂 daemon 下此前要 ~30-50s 才降级，阻塞 execute。默认 25s 截断（可达 daemon 毫秒级
+ * 响应，不受影响）；opts.totalTimeoutMs 可覆盖。超时按 daemon-unreachable 语义进负面缓存。
+ */
+const DEFAULT_PROBE_TOTAL_TIMEOUT_MS = 25_000;
+
 // 负面缓存：configFingerprint → { result: {available,reason}, expiresAt }
 // 仅缓存网络派生的 unavailable 结果（daemon-unreachable），避免 daemon 抖动期反复探测（R-06）。
 // no-config 由 env 同步派生（不入缓存）；worktree-outside-root 依赖路径入参（每次重算，不入缓存）。
@@ -99,27 +106,6 @@ export function detectPathAFromTools(tools) {
   return Boolean(props.worktree_path) && Boolean(props.worker_prompt);
 }
 
-/**
- * 预热路径A 探测缓存（task-11）：probe.js daemon 可达后 best-effort 调 client.listTools，
- * 把 detectPathAFromTools 结果写回 sillyhub-mcp.js 缓存供 isPathASupported 同步读。
- *
- * best-effort：client 无 listTools 方法（旧 mock）/ listTools 异常 / 返回非数组 → 保守写 false
- * （R-04，绝不硬试路径A），**不抛穿 probe**（探测失败不影响 availability 判定）。
- * @param {object} cli - SillyHubMcpClient 实例（或含 listTools 的 mock）
- */
-async function preheatPathAProbe(cli) {
-  try {
-    if (!cli || typeof cli.listTools !== 'function') return; // 旧 mock 无 listTools → 不预热（留默认 false）
-    const tools = await cli.listTools();
-    setPathAProbeResult(detectPathAFromTools(tools));
-  } catch (err) {
-    // 探测异常 → 保守 false（R-04）；best-effort 不阻断 probe 主流程
-    const msg = err && err.message ? err.message : String(err);
-    console.warn(`[dispatch/probe] 路径A schema 探测异常（保守判 false）: ${msg}`);
-    setPathAProbeResult(false);
-  }
-}
-
 /**
  * 能力探测：决定 dispatch 是否可用 SillyHub 后端。
  *
@@ -127,21 +113,24 @@ async function preheatPathAProbe(cli) {
  *   1. env 快速路径（无网络）：缺 URL/TOKEN → no-config
  *   2. 负面缓存命中且未过 TTL → 直接返回缓存（无网络，R-06）
  *   3. 连通性探测 client.probeDaemon()：false → 缓存 daemon-unreachable 并返回
- *   3.5 路径A schema 预热（task-11）：daemon 可达 → best-effort client.listTools() 写
- *       isPathASupported 缓存（dispatch_worker schema 含 worktree_path + worker_prompt）
- *   4. root_path 校验（R-08 best-effort）：rootPath 显式传则用；未传则 best-effort 从 daemon
- *       拿（client.getRootPath，复用 tools/list）；worktreePath 同传且越界 → worktree-outside-root
+ *   3.5 路径A schema 预热 + root_path 获取（HUB-12a 合并）：daemon 可达后**一次**
+ *       tools/list 同时喂 detectPathAFromTools 预热与 root_path 越界校验（此前
+ *       listTools + getRootPath 各发一次同 method 请求）
+ *   4. worktreePath 越界校验（R-08 best-effort）
  *   5. 全通过 → available=true（不缓存正面结果）
  *
+ * 整链路受 totalTimeoutMs 总超时保护（HUB-12a）：超时按 daemon-unreachable 进负面缓存。
+ *
  * @param {object} [opts]
  * @param {object} [opts.client]       - SillyHubMcpClient 实例；缺省 new SillyHubMcpClient()（经 readMcpConfig 读 local.yaml mcp 段 + env）
  * @param {string} [opts.worktreePath] - SillySpec worktree 绝对路径（root_path 校验用）
  * @param {string} [opts.rootPath]     - daemon ws.root_path；未传（undefined）时 best-effort 从 daemon
  *                                       拿（task-12 #5），拿不到则跳过越界校验（不判 unavailable）
  * @param {number} [opts.ttlMs]        - 负面缓存 TTL 覆盖（优先于 local.yaml）
+ * @param {number} [opts.totalTimeoutMs] - 总超时覆盖（默认 25s，HUB-12a）
  * @returns {Promise<{ available: boolean, reason?: string }>}
  */
-export async function probeSillyHub({ client, worktreePath, rootPath, ttlMs } = {}) {
+export async function probeSillyHub({ client, worktreePath, rootPath, ttlMs, totalTimeoutMs } = {}) {
   // 1. 同步快速路径：无 local.yaml mcp 段且 env 缺凭据即 unavailable（不发网络，零回归关键）。
   //    readMcpConfig 纯 fs + env 读（best-effort 不抛不发网络），返回 null = 两源都缺 → no-config。
   if (!readMcpConfig(process.cwd())) {
@@ -155,51 +144,98 @@ export async function probeSillyHub({ client, worktreePath, rootPath, ttlMs } =
     return cached.result;
   }
 
-  // 3. 连通性探测：client.probeDaemon 自身 best-effort 不抛；再兜一层 try/catch，
-  //    即便 client 契约异常抛出也保守判 unavailable（铁律：绝不抛穿 execute）
   const cli = client || new SillyHubMcpClient({ cwd: process.cwd() });
-  let reachable;
-  try {
-    reachable = await cli.probeDaemon();
-  } catch (err) {
-    const msg = err && err.message ? err.message : String(err);
-    console.warn(`[dispatch/probe] probeDaemon 抛异常（保守判 unavailable）: ${msg}`);
-    reachable = false;
-  }
-  if (!reachable) {
-    const result = { available: false, reason: 'daemon-unreachable' };
+  const cacheNegative = (reason) => {
+    const result = { available: false, reason };
     const ttl = resolveTtl(ttlMs, process.cwd());
     negativeCache.set(fp, { result, expiresAt: Date.now() + ttl });
     return result;
-  }
-
-  // 3.5 路径A schema 探测预热（task-11，D-005）：daemon 可达后 best-effort 调 client.listTools，
-  //     把 dispatch_worker schema 含 worktree_path + worker_prompt 的结果写缓存供
-  //     isPathASupported 同步读。best-effort：失败保守 false（R-04），不影响 availability。
-  await preheatPathAProbe(cli);
-
-  // 4. root_path 校验（R-08，best-effort）：rootPath 显式传入则直接用；未传入时 best-effort 从
-  //    daemon 拿（task-12 #5，复用 listTools RPC：daemon 若在 tools/list 顶层暴露 root_path 则
-  //    自动适配；当前 gateway 不暴露 → null → 跳过越界校验，不判 unavailable）。
-  //    仅 worktreePath 也传时才校验（无 worktree 无谓越界判定）；任一缺失则跳过。
-  if (worktreePath) {
-    let effectiveRoot = rootPath;
-    if (effectiveRoot === undefined && cli && typeof cli.getRootPath === 'function') {
-      try {
-        effectiveRoot = await cli.getRootPath();
-      } catch (err) {
-        const msg = err && err.message ? err.message : String(err);
-        console.warn(`[dispatch/probe] rootPath best-effort 拿取异常（跳过越界校验）: ${msg}`);
-        effectiveRoot = null;
+  };
+
+  // HUB-12a：总超时兜底——慢/挂 daemon 不拖 execute。超时后后台请求由 client 自身
+  // 10s 请求超时自然终结（有界），probe 侧按不可达降级
+  const budgetMs = typeof totalTimeoutMs === 'number' && totalTimeoutMs > 0
+    ? totalTimeoutMs
+    : DEFAULT_PROBE_TOTAL_TIMEOUT_MS;
+
+  const probeBody = (async () => {
+    // 3. 连通性探测：client.probeDaemon 自身 best-effort 不抛；再兜一层 try/catch，
+    //    即便 client 契约异常抛出也保守判 unavailable（铁律：绝不抛穿 execute）
+    let reachable;
+    try {
+      reachable = await cli.probeDaemon();
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      console.warn(`[dispatch/probe] probeDaemon 抛异常（保守判 unavailable）: ${msg}`);
+      reachable = false;
+    }
+    if (!reachable) return cacheNegative('daemon-unreachable');
+
+    // 3.5+4 合并（HUB-12a）：一次 tools/list 同时拿 tools 数组（路径A schema 预热）与
+    //     root_path（越界校验）。旧 client 无 listToolsWithMeta 时回退 listTools +
+    //     getRootPath 各一次（兼容旧 mock）
+    let tools = null;
+    let toolsListRoot = undefined;
+    try {
+      if (typeof cli.listToolsWithMeta === 'function') {
+        const raw = await cli.listToolsWithMeta();
+        if (raw) {
+          if (Array.isArray(raw)) tools = raw;
+          else if (Array.isArray(raw.tools)) tools = raw.tools;
+          if (raw && typeof raw === 'object' && typeof raw.root_path === 'string' && raw.root_path) {
+            toolsListRoot = raw.root_path;
+          }
+        }
+      } else if (typeof cli.listTools === 'function') {
+        tools = await cli.listTools();
       }
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      console.warn(`[dispatch/probe] tools/list 异常（路径A 保守判 false）: ${msg}`);
+      tools = null;
     }
-    if (effectiveRoot && !isWithinRoot(effectiveRoot, worktreePath)) {
-      return { available: false, reason: 'worktree-outside-root' };
+    try {
+      setPathAProbeResult(detectPathAFromTools(tools));
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err);
+      console.warn(`[dispatch/probe] 路径A schema 探测异常（保守判 false）: ${msg}`);
+      setPathAProbeResult(false);
+    }
+
+    if (worktreePath) {
+      let effectiveRoot = rootPath;
+      if (effectiveRoot === undefined) {
+        effectiveRoot = toolsListRoot !== undefined ? toolsListRoot : null;
+        if (effectiveRoot === null && typeof cli.getRootPath === 'function') {
+          try {
+            effectiveRoot = await cli.getRootPath();
+          } catch (err) {
+            const msg = err && err.message ? err.message : String(err);
+            console.warn(`[dispatch/probe] rootPath best-effort 拿取异常（跳过越界校验）: ${msg}`);
+            effectiveRoot = null;
+          }
+        }
+      }
+      if (effectiveRoot && !isWithinRoot(effectiveRoot, worktreePath)) {
+        return { available: false, reason: 'worktree-outside-root' };
+      }
     }
-  }
 
-  // 5. 全通过：不缓存正面结果，下次重新探测（让 daemon 恢复/退化及时反映）
-  return { available: true };
+    // 5. 全通过：不缓存正面结果，下次重新探测（让 daemon 恢复/退化及时反映）
+    return { available: true };
+  })();
+
+  let timeoutId = null;
+  let raced;
+  try {
+    raced = await Promise.race([
+      probeBody,
+      new Promise((resolve) => { timeoutId = setTimeout(() => resolve(null), budgetMs) }),
+    ]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+  return raced || cacheNegative('probe-timeout');
 }
 
 /**

package/src/docs-check.js

@@ -17,8 +17,13 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from '
 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']
@@ -26,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
@@ -37,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
@@ -63,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,
     })
   }
@@ -268,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, suggest?: number[], fix: {fixable: boolean, newLine?: number, reason: string}}>, 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），仅做存在性校验')
@@ -288,6 +305,8 @@ 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)
@@ -303,8 +322,32 @@ 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,
@@ -338,9 +381,11 @@ 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 保守默认）
@@ -350,7 +395,7 @@ export function runDocsCheck(opts) {
     }
   }
 
-  return { ok: invalid.length === 0, total, invalid, warnings, kwChecked }
+  return { ok: invalid.length === 0, total, invalid, warnings, kwChecked, crossRepoSkipped }
 }
 
 /**

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) {