sillyspec 3.34.1 → 3.34.2

package/src/spec-sync.js

@@ -17,7 +17,7 @@
 
 import { createHash } from 'crypto';
 import { timedAsync } from './timing.js';
-import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, unlinkSync, rmSync } from 'fs';
 import { join, relative, sep } from 'path';
 import { bindSyncNoiseRoot, syncConnectionWarn, isConnectionClassStatus, noteSyncSuccess } from './sync-noise.js';
 import { runtimeStatePath } from './runtime-paths.js';
@@ -52,6 +52,60 @@ function toPosix(p) {
 // 小响应维持 10s 噪音闸门不变。
 const MANIFEST_FULL_TIMEOUT_MS = 120_000;
 
+// 推送分批（2026-11-04-sync-push-chunking）：大积压单批 POST 在单请求预算内必死——
+// 生产实证 multi-agent-platform 工作区 15 天积压 2436 ops/45.7MB（base64 后 ~60MB），
+// 上传+服务端 apply 双超（客户端 30s 掐线、服务器 16-34s 处理后 400/中断），37 连败
+// 零落地。切块顺序推送：每块独立提交，已落地块推进服务器清单，失败即停由下轮 diff
+// 断点续传（锚点刷新后已落地路径自动出 diff）。env 仅调优，缺省零回归（小批量一块直发）。
+const PUSH_TIMEOUT_DEFAULT_MS = 30_000;
+const CHUNK_OPS_DEFAULT = 128;
+const CHUNK_BYTES_DEFAULT = 2 * 1024 * 1024;
+
+function resolvePushTimeoutMs() {
+  const raw = Number(process.env.SILLYSPEC_SPEC_SYNC_PUSH_TIMEOUT_MS);
+  if (Number.isFinite(raw) && raw >= 1000) return Math.floor(raw);
+  return PUSH_TIMEOUT_DEFAULT_MS;
+}
+
+function resolveChunkOps() {
+  const raw = Number(process.env.SILLYSPEC_SPEC_SYNC_CHUNK_OPS);
+  if (Number.isInteger(raw) && raw >= 1) return raw;
+  return CHUNK_OPS_DEFAULT;
+}
+
+function resolveChunkBytes() {
+  const raw = Number(process.env.SILLYSPEC_SPEC_SYNC_CHUNK_BYTES);
+  if (Number.isFinite(raw) && raw >= 1024) return Math.floor(raw);
+  return CHUNK_BYTES_DEFAULT;
+}
+
+/**
+ * 按 op 数与 base64 字节数双约束切块（顺序保序；单 op 超任一上限独占一块——
+ * 4.7MB 级 change.patch 单文件不切不丢弃）。行宽为粗估（content + path×2 + 包裹），
+ * 只为分块比例，无需精确。
+ */
+export function chunkOpsForPush(ops, opts = {}) {
+  const maxOps = opts.maxOps ?? resolveChunkOps();
+  const maxBytes = opts.maxBytes ?? resolveChunkBytes();
+  if (!Array.isArray(ops) || ops.length === 0) return [];
+  if (maxOps < 1 || maxBytes < 1) return [ops.slice()];
+  const chunks = [];
+  let cur = [];
+  let curBytes = 0;
+  for (const op of ops) {
+    const size = (op.content ? op.content.length : 0) + op.path.length * 2 + 96;
+    if (cur.length > 0 && (cur.length >= maxOps || curBytes + size > maxBytes)) {
+      chunks.push(cur);
+      cur = [];
+      curBytes = 0;
+    }
+    cur.push(op);
+    curBytes += size;
+  }
+  if (cur.length > 0) chunks.push(cur);
+  return chunks;
+}
+
 function debugLog(msg) {
   if (process.env.SILLYSPEC_DEBUG_SYNC) console.warn(msg);
 }
@@ -68,7 +122,7 @@ export function describeSyncError(err) {
     return '平台响应慢，本轮同步被总预算熔断让路（best-effort，下一条命令自动重试）';
   }
   if (err && err.name === 'TimeoutError') {
-    return '单请求超时（清单 10s / 推送 30s 口径，best-effort，下次自动重试）';
+    return '单请求超时（清单增量 10s/全量 120s；推送默认 30s，SILLYSPEC_SPEC_SYNC_PUSH_TIMEOUT_MS 可调；分批尺寸 SILLYSPEC_SPEC_SYNC_CHUNK_*；best-effort，下次自动重试）';
   }
   return err && err.message ? err.message : String(err);
 }
@@ -310,6 +364,12 @@ export function computeSpecOps(serverManifest, localFiles) {
   for (const p of localMap.keys()) {
     if (renamedNew.has(p)) continue;
     if (!serverSet.has(p)) {
+      // 平台已审候选不复活（2026-11-07-sync-proposed-no-revive）：平台知识页 merge/reject
+      // 待审候选后服务器软删（manifest 行 exists=false，不置墓碑）——此处若照常 add 会走
+      // 平台复活分支把已审条目推回待审区（2026-11-07 平台侧核查实证）。窄化判定：仅
+      // knowledge/proposed/ 前缀 + 软删行在场（平台处置的唯一可信证据；manifest 无行 =
+      // 从未同步的新提议，照常 add）。本地残留清理由 cleanupPlatformDisposedProposed 负责。
+      if (p.startsWith('knowledge/proposed/') && server[p]?.exists === false) continue;
       const localEntry = localMap.get(p);
       const content = (localEntry.buf ?? readFileSync(localEntry.absPath ?? join('.', p))).toString('base64');
       ops.push({
@@ -326,6 +386,39 @@ export function computeSpecOps(serverManifest, localFiles) {
   return ops;
 }
 
+/**
+ * 平台已审候选的本地残留清理（2026-11-07-sync-proposed-no-revive FR-02）：
+ * 「本地 knowledge/proposed/ 文件 ∩ 服务器 manifest exists=false 行」= 平台侧已
+ * merge/reject 处置过的候选在本地留下的残件（computeSpecOps 已拦其 add 复活）——
+ * 此处删除本地文件并提示，防止残留永久滞留（每次 sync 重算，幂等；无残留零输出）。
+ * 删除安全性：服务器侧该路径已无活文件（软删行），删本地不产生两端不一致；误删窗口
+ * 仅「同 slug 复写新内容 + 平台恰已处置同路径」（发生率极低，见变更 design R-02）。
+ * @returns {string[]} 已清理的 spec 相对路径列表
+ */
+export function cleanupPlatformDisposedProposed(specRoot, serverManifest) {
+  const server = serverManifest || {};
+  const disposed = Object.keys(server).filter(
+    (p) => p.startsWith('knowledge/proposed/') && server[p]?.exists === false
+  );
+  if (disposed.length === 0) return [];
+  const removed = [];
+  for (const p of disposed) {
+    // spec 相对路径 → 本地绝对路径（walkSpecTree 同源根；路径来自服务器清单为 POSIX 形态）
+    const abs = join(specRoot, ...p.split('/'));
+    if (!existsSync(abs)) continue; // 本地不在场的处置行零动作零上报（只清真残件）
+    try {
+      rmSync(abs, { force: true });
+      removed.push(p);
+    } catch { /* 删除失败不阻断同步——下轮重算重试（幂等） */ }
+  }
+  if (removed.length > 0) {
+    console.log(
+      `[spec-sync] 已清理 ${removed.length} 个平台已审核（合并/拒绝）的本地待审候选残留（不再回推复活）: ${removed.slice(0, 5).join(', ')}${removed.length > 5 ? ' 等' : ''}`
+    );
+  }
+  return removed;
+}
+
 /**
  * 从 ops 提取本次涉及的变更目录名集合（change_dirs 标注，D-005@v1）。
  *
@@ -838,6 +931,11 @@ async function syncSpecTreeImpl(specRoot, platform, changeName, opts = {}) {
   // 2. walk/hash/diff
   const entries = walkSpecTree(specRoot);
   const localFiles = hashFiles(entries);
+  // 平台已审候选残留清理（2026-11-07-sync-proposed-no-revive FR-02）：computeSpecOps 已拦
+  // 其 add 复活，此处删本地残件+提示（幂等；walk 已完成，删除不影响本轮 diff 结果）。
+  try {
+    cleanupPlatformDisposedProposed(specRoot, serverManifest);
+  } catch { /* 清理 fail-soft——不阻断文件树同步 */ }
   let ops = computeSpecOps(serverManifest, localFiles);
 
   // 旧副本回推防护（并行会话一致性）：上次同步后本地从未改动的文件不回推覆盖服务器新内容。
@@ -877,30 +975,47 @@ async function syncSpecTreeImpl(specRoot, platform, changeName, opts = {}) {
     return { synced: 0, ok: true };
   }
 
-  // 3. POST ops
+  // 3. POST ops（2026-11-04-sync-push-chunking：分批顺序推送——单批大积压在单请求
+  //    预算内上传+服务端 apply 双超零落地；切块后每块独立提交，失败即停下轮续传）
   try {
-    const res = await fetch(syncUrl, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${platform.token}`,
-      },
-      body: JSON.stringify({ ops }),
-      signal: withSignal(30000),
-    });
-    if (!res.ok) {
-      const raw = await res.text().catch(() => '');
-      const detail = describeErrorBody(res.status, raw);
-      const failCount = bumpFailStreak(specRoot, logLabel, detail);
-      const line = `[spec-sync] 同步请求失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）: ${logLabel}${detail ? ` —— ${detail}` : ''}`;
-      if (isConnectionClassStatus(res.status)) syncConnectionWarn(line);
-      else console.warn(line);
-      if (failCount >= FAIL_STREAK_ESCALATE_AT) {
-        console.warn(`🚨 [spec-sync] 已连续 ${failCount} 次同步失败——平台文件树可能持续落后（变更中心或仍显示「进行中」/旧内容）: ${logLabel}`);
+    const chunks = chunkOpsForPush(ops);
+    if (chunks.length > 1) {
+      console.log(`[spec-sync] 推送分批：${ops.length} ops 切 ${chunks.length} 块顺序提交（块上限 ${resolveChunkOps()} ops / ${Math.round(resolveChunkBytes() / 1024)}KB 估算）: ${logLabel}`);
+    }
+    let landedChunks = 0;
+    const body = { conflict: false, server_versions: {}, platform_deleted: [] };
+    for (let ci = 0; ci < chunks.length; ci++) {
+      const res = await fetch(syncUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${platform.token}`,
+        },
+        body: JSON.stringify({ ops: chunks[ci] }),
+        signal: withSignal(resolvePushTimeoutMs()),
+      });
+      if (!res.ok) {
+        const raw = await res.text().catch(() => '');
+        const detail = describeErrorBody(res.status, raw);
+        const failCount = bumpFailStreak(specRoot, logLabel, detail);
+        const landedNote = landedChunks > 0 ? `（前 ${landedChunks}/${chunks.length} 块已落地，下轮自动续传未落地部分）` : '';
+        const line = `[spec-sync] 同步请求失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）${landedNote}: ${logLabel}${detail ? ` —— ${detail}` : ''}`;
+        if (isConnectionClassStatus(res.status)) syncConnectionWarn(line);
+        else console.warn(line);
+        if (failCount >= FAIL_STREAK_ESCALATE_AT) {
+          console.warn(`🚨 [spec-sync] 已连续 ${failCount} 次同步失败——平台文件树可能持续落后（变更中心或仍显示「进行中」/旧内容）: ${logLabel}`);
+        }
+        return { synced: 0, ok: false };
       }
-      return { synced: 0, ok: false };
+      const chunkBody = await res.json().catch(() => ({}));
+      landedChunks += 1;
+      // 块响应合并成单批等价形状：conflict 任一块命中即真；server_versions /
+      // platform_deleted 逐块累积（块间路径互斥——computeSpecOps 每 path 至多一 op）。
+      if (chunkBody.conflict) body.conflict = true;
+      Object.assign(body.server_versions, chunkBody.server_versions || {});
+      if (Array.isArray(chunkBody.platform_deleted)) body.platform_deleted.push(...chunkBody.platform_deleted);
+      if (chunks.length > 1) debugLog(`[spec-sync] 分批 ${ci + 1}/${chunks.length} 落地（${chunks[ci].length} ops）`);
     }
-    const body = await res.json().catch(() => ({}));
     if (body.conflict) {
       // HUB-08 冲突闭环：落 spec-sync-conflict-<change>.json（与进度 sync-conflict-* 同目录），
       // 供 platform status 列出 + platform resolve 三态处置。此前只 warn 返回，下次 sync 用
@@ -1037,5 +1152,6 @@ export default {
   filterStaleUpdates,
   dropFollowServerUpdates,
   partitionConflictPaths,
+  chunkOpsForPush,
   syncSpecTree,
 };

package/src/stages/execute.js

@@ -21,7 +21,7 @@ import { collectExecuteChangedFiles, computeDecisionTouches, renderDecisionTouch
 // （test 直 import 本文件皆此形态）触发 stages/index.js 顶层 stageRegistry 对本文件 definition
 // const 的 TDZ 求值（ESM 环实证 2026-09-14）。此处为同格式本地孪生，漂移由
 // test/knowledge-inject.test.mjs 格式等价断言锁定——改 prompt.js 版必同步改此处。
-import { matchKnowledge } from '../knowledge-match.js'
+import { matchKnowledge, resultChannel } from '../knowledge-match.js'
 import { matchKnowledgeWithScope, graphPathCandidates, scopeTelemetryRefs } from '../knowledge-graph.js'
 import { appendKnowledgeHit } from '../knowledge-hits.js'
 
@@ -136,10 +136,12 @@ function buildWaveKnowledgeSection(changeDir, wave) {
     }
     }
     try {
+      // channel 单源记录（FR-04，2026-11-05-knowledge-search-observability）——画像/调优数据地基
       appendKnowledgeHit(path.join(specBase, '.runtime'), {
         type: 'inject',
         change: path.basename(changeDir),
         query,
+        channel: resultChannel(result),
         matchedFiles: result.matched ? [...humanEntries, ...routeHits].map(e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)) : [],
         ...(result.matched ? (() => {
           const scopeMatchedFiles = scopeTelemetryRefs(result, { includeRejected: false })

package/src/stages/explore.js

@@ -22,11 +22,13 @@ export const definition = {
    - 在途面（出方向建议前）→ \`sillyspec status\` 活跃变更一览——结论别跟在途工作撞车
 4. 输出 2-3 个有价值方向、关键风险和下一步建议
 5. 如果用户要求保存结论，先明确保存位置，再写入对应文档
-6. 讨论 UI/交互方案且用户明确要求原型时，按下方「HTML 原型生成」执行
+6. 讨论 UI/交互方案或状态机/流程/时序类歧义且用户明确要求原型时，按下方「HTML 原型生成」执行
 
 ### HTML 原型生成（仅用户明确要求时）
-探索保持只读姿态：不主动写原型文件；UI 讨论成形时可以提议（"要不要出个原型看效果"），用户同意后再生成。探索期原型是**粗选对比件**（求快不求真，手绘单文件含内联 CSS+JS 在探索期合法，浏览器直接打开）：
+探索保持只读姿态：不主动写原型文件；UI/交互讨论成形、或状态机/流程/时序类歧义文字多轮问答装不下时，可以提议（"要不要出个原型看效果"），用户同意后再生成。探索期原型是**粗选对比件**（求快不求真，手绘单文件含内联 CSS+JS 在探索期合法，浏览器直接打开）：
 - 呈现讨论中的布局/组件/交互流程——用户看到的是"这个方案做出来长什么样"，不是示意图；能用项目真实组件库/设计 token 观感的尽量用（先读 scan 文档与现有前端代码），降低与真实效果的偏差
+- 逻辑形（状态机/流转/时序类歧义用）：把流转规则写成内联纯逻辑模块，配状态面板（每步操作后重渲染全量状态）+ 领域语言标注，让用户亲手把玩边界场景代替文字推演；非 JS 项目即「JS 复刻的模拟器」——验证的是复刻件非真码，提议时声明可能的翻译失真；逻辑形不进变更目录（prototype-*.html 命名是 UI 契约件专属），结论以 design/decisions 文字落盘
+- 多方案对比时：各方案须在布局/信息层级（UI 形）或流转结构（逻辑形）上实质性分歧，颜色文案级差异不构成对比方案；mock 数据取真实形状与密度，不在空态页面上做判断
 - 保存到 \`{SPEC_ROOT}/explore/prototype-<名称>.html\`（目录不存在则先创建；用户指定了其他位置则从其指定）
 - 原型是探索讨论工具、不是交付物，也不是实现代码——不要顺手把原型接进项目源码或构建；话题后续进入 brainstorm 时分两路：已是可复跑真码的原型复制到 \`{SPEC_ROOT}/changes/<变更名>/\`（**保留 \`prototype-<名称>.html\` 命名**——execute 按此命名注入，改名＝不注入）走登记复用；手绘粗选件只是方向输入，brainstorm 定稿须按其「生成要求」升级为真码（同方言/可复跑），不得把手绘件直接当定稿登记
 

package/src/stages/knowledge.js

@@ -17,10 +17,10 @@
  */
 
 import { existsSync, readFileSync, readdirSync, mkdirSync, statSync } from 'fs'
-import { join, basename } from 'path'
+import { join, basename, dirname } from 'path'
 import { writeAtomicSync } from '../fs-atomic.js'
 import { parseKnowledgeIndex, keywordMatchesContext, normalizeAnchorForCompare } from '../knowledge-match.js'
-import { matchKnowledgeHybrid } from '../knowledge-vector.js'
+import { matchKnowledgeHybrid, resultChannel } from '../knowledge-vector.js'
 
 // ── 工具函数 ──
 
@@ -132,6 +132,21 @@ export async function cmdSearch(dir, args, opts = {}) {
     ? result.json.parkingFiltered : []
   const payload = buildSearchPayload(result, knowledgeDir, limit, query)
 
+  // search 面遥测（FR-05，2026-11-05-knowledge-search-observability）：显式检索此前零落盘
+  // ——查询形态/命中率/通道分布是向量层调优（地板值/词表收录）的唯一数据源。fail-soft：
+  // 落盘失败不影响检索输出（R-04 纪律）；stats 按 type 严格过滤，type=search 不进既有视图。
+  try {
+    const { appendKnowledgeHit } = await import('../knowledge-hits.js')
+    appendKnowledgeHit(join(dirname(knowledgeDir), '.runtime'), {
+      type: 'search',
+      query,
+      matched: Boolean(result && result.matched),
+      channel: resultChannel(result),
+      entry_count: (payload.matches || []).length,
+      matchedFiles: (payload.matches || []).map((m) => m.id).slice(0, 12),
+    })
+  } catch { /* 遥测 fail-soft（R-04） */ }
+
   output(true, {
     query,
     ...payload,
@@ -176,11 +191,8 @@ export function buildSearchPayload(result, knowledgeDir, limit, query) {
  */
 export function buildSearchMatches(result, knowledgeDir, limit, query) {
   const ctx = String(query || '').toLowerCase()
-  const channel = result && result.json && result.json.fallback ? 'fallback'
-    : result && result.json && result.json.vector ? 'vector'
-      : result && result.json && result.json.scope ? 'scope'
-        : 'routing'
-  return result.entries.slice(0, limit).map(entry => {
+  const channel = resultChannel(result)
+  return result.entries.slice(0, limit).map((entry) => {
     const filePath = join(knowledgeDir, entry.file)
     let title = entry.display
     let summary = ''
@@ -192,12 +204,16 @@ export function buildSearchMatches(result, knowledgeDir, limit, query) {
     }
 
     const tags = entry.keywords
+    // 向量通道透出真实余弦分（FR-03，2026-11-05-knowledge-search-observability）：
+    // keywords∩query 对 vector 通道恒 0（keywords=['vector'] 非查询词）——错值不只是缺值；
+    // vectorScore 由 buildResultFromPlatform 挂文件级最高分。其余通道 score 口径不变。
+    const vectorScore = channel === 'vector' && typeof entry.vectorScore === 'number' ? entry.vectorScore : null
     return {
       id: pathToId(entry.file, knowledgeDir),
       path: join('knowledge', entry.file),
       title,
       summary,
-      score: tags.filter(k => keywordMatchesContext(k, ctx)).length,
+      score: vectorScore !== null ? Math.round(vectorScore * 1000) / 1000 : tags.filter((k) => keywordMatchesContext(k, ctx)).length,
       tags,
       channel,
       category: entry.category,
@@ -399,120 +415,17 @@ export async function cmdValidate(dir, args, opts = {}) {
 // ── refresh ──
 
 export async function cmdRefresh(dir, args, opts = {}) {
+  // generated 切块退役（2026-11-07-knowledge-generated-retire）：双仓审计实证切块镜像为
+  // 零消费死区（INDEX 零引用、检索四层零进语料、自带 INDEX 零读取方）且是双源漂移源
+  // （平台仓同事实矛盾实证）——scan 文档本体在 docs 下项目 scan 目录，保留为唯一真相源，
+  // 切块产物退出知识库。子命令入口保留防脚本断链，行为=废弃提示零写盘。
   const knowledgeDir = resolveKnowledgeDir(dir, opts.specDir)
-  const generatedDir = join(knowledgeDir, 'generated')
-
-  if (!existsSync(knowledgeDir)) {
-    output(false, {}, { code: 'knowledge_dir_missing', path: knowledgeDir })
-    return
-  }
-
-  // refresh 只写 generated/ 区
-  mkdirSync(generatedDir, { recursive: true })
-
-  // 扫描 scan 文档。项目名用 DB 注册名优先（坑 knowledge-basename-project-mismatch）：
-  // scan 写侧 docs/<project> 的 project 来自 dbProjectName || basename(cwd)，注册名 ≠ 目录名
-  // （projects yaml name/path 分离、平台模式 specRoot≠sourceRoot）时，用 basename(dir) 拼
-  // scanDir 永远找不到 → refresh 恒报 scan_docs_missing。DB 读失败回退 basename（与写侧
-  // default 同口径）。查不到注册名对应目录时再回退 basename 试一次（双形态兼容）。
-  const base = opts.specDir || join(dir, '.sillyspec')
-  let projectName = null
-  try {
-    const { DatabaseSync } = await import('node:sqlite')
-    const db = new DatabaseSync(join(base, '.runtime', 'sillyspec.db'), { readOnly: true })
-    const row = db.prepare('SELECT name FROM project LIMIT 1').get()
-    db.close()
-    if (row && row.name) projectName = row.name
-  } catch { /* db 不可读 → 走 basename 兜底 */ }
-  if (!projectName) projectName = basename(dir)
-  let scanDir = join(base, 'docs', projectName, 'scan')
-  if (!existsSync(scanDir) && projectName !== basename(dir)) {
-    scanDir = join(base, 'docs', basename(dir), 'scan')
-  }
-
-  if (!existsSync(scanDir)) {
-    output(false, {}, { code: 'scan_docs_missing', path: scanDir })
-    return
-  }
-
-  const scanFiles = readdirSync(scanDir).filter(f => f.endsWith('.md'))
-  const generated = []
-  const overwritten = []
-  // 同 run 文件名去重（坑 knowledge-slug-collision）：slug 只由章节标题生成，不同 scan 文件
-  // 的同名章节（如各自都有「## 概述」）后者 writeFileSync 静默覆盖前者，INDEX 却登记两条
-  // 指向同一路径的条目——知识条目无声丢失。碰撞时追加 -2/-3 后缀保双份（唯一命名零扰动，
-  // 每次 refresh 按相同文件顺序重跑，后缀分配稳定）
-  const usedNames = new Set()
-
-  for (const scanFile of scanFiles) {
-    const scanPath = join(scanDir, scanFile)
-    const content = readFileSync(scanPath, 'utf8')
-    const title = extractTitle(content) || scanFile.replace('.md', '')
-
-    // 简单提取：取每个 ## 章节作为一个知识条目候选
-    const sections = extractSections(content)
-    for (const section of sections) {
-      if (section.lines < 3) continue // 太短的章节跳过
-
-      const slug = section.heading.toLowerCase()
-        .replace(/[^\w\u4e00-\u9fff]+/g, '-')
-        .replace(/^-|-$/g, '')
-        .slice(0, 60)
-
-      let fileName = `${slug}.md`
-      if (usedNames.has(fileName)) {
-        let n = 2
-        while (usedNames.has(`${slug}-${n}.md`)) n++
-        fileName = `${slug}-${n}.md`
-      }
-      usedNames.add(fileName)
-      const genPath = join(generatedDir, fileName)
-      const isNew = !existsSync(genPath)
-
-      const entryContent = [
-        `---`,
-        `source: scan/${scanFile}`,
-        `section: ${section.heading}`,
-        `generated_at: ${new Date().toISOString()}`,
-        `---`,
-        ``,
-        `# ${title} — ${section.heading}`,
-        ``,
-        section.body,
-      ].join('\n')
-
-      // INDEX/generated 是 search/validate 的解析源（跨进程读），走原子写防半截
-      writeAtomicSync(genPath, entryContent)
-      generated.push({ file: `generated/${fileName}`, title: `${title} — ${section.heading}`, new: isNew })
-      if (!isNew) overwritten.push(`generated/${fileName}`)
-    }
-  }
-
-  // 更新 generated/INDEX.md
-  const genIndexPath = join(generatedDir, 'INDEX.md')
-  const indexLines = [
-    '---',
-    `generated_at: ${new Date().toISOString()}`,
-    '---',
-    '',
-    '# Generated Knowledge Index',
-    '',
-    '> Auto-generated from scan documents. Do not edit manually.',
-    '',
-  ]
-  for (const g of generated) {
-    indexLines.push(`- ${g.title} → [${g.file}](${g.file})`)
-  }
-  writeAtomicSync(genIndexPath, indexLines.join('\n'))
-
   output(true, {
-    generated_count: generated.length,
-    new_count: generated.filter(g => g.new).length,
-    overwritten_count: overwritten.length,
-    files: generated,
+    deprecated: true,
+    message: 'knowledge refresh 已退役（2026-11-07-knowledge-generated-retire）：generated 切块为死区已退库。scan 文档本体在 docs 下的项目 scan 目录，由 scan 流程维护；知识沉淀走 propose → 用户确认后 accept 合并。',
+    knowledge_dir: knowledgeDir,
   })
 }
-
 // ── propose ──
 
 export async function cmdPropose(dir, args, opts = {}) {
@@ -525,6 +438,13 @@ export async function cmdPropose(dir, args, opts = {}) {
   const category = categoryIdx >= 0 && args[categoryIdx + 1] ? args[categoryIdx + 1] : 'uncategorized'
   const bodyIdx = args.indexOf('--body')
   const body = bodyIdx >= 0 && args[bodyIdx + 1] ? args[bodyIdx + 1] : ''
+  // --body-file 文件正文通道（2026-11-06-knowledge-propose-body-file）：中文长正文
+  // 经命令行 argv 传递会被策略层分词误杀（「斜杠+中文标点」序列误判路径，2026-11-06
+  // 平台会话双 shell 实证），文件通道彻底绕开 argv。相对路径按进程 cwd 解析
+  // （readFileSync 直读，不做 specDir 拼接）。
+  const bodyFileIdx = args.indexOf('--body-file')
+  const bodyFile = bodyFileIdx >= 0 && args[bodyFileIdx + 1] ? args[bodyFileIdx + 1] : ''
+  let bodyFromFile = ''
   const fromIdx = args.indexOf('--from')
   const from = fromIdx >= 0 && args[fromIdx + 1] ? args[fromIdx + 1] : ''
 
@@ -533,6 +453,40 @@ export async function cmdPropose(dir, args, opts = {}) {
     return
   }
 
+  // 三类参数错误先于 mkdirSync/writeAtomicSync——错误路径零目录创建零落盘。
+  // 互斥按 flag 在场判定（值缺省同算同给，报冲突优于静默择一）。
+  if (bodyFileIdx >= 0 && bodyIdx >= 0) {
+    output(false, {}, {
+      code: 'body_source_conflict',
+      message: '--body 与 --body-file 互斥，只能提供一个正文来源',
+    })
+    return
+  }
+  if (bodyFileIdx >= 0) {
+    if (!bodyFile || bodyFile.startsWith('--')) {
+      output(false, {}, '--body-file requires a path')
+      return
+    }
+    if (!existsSync(bodyFile)) {
+      output(false, {}, { code: 'body_file_missing', path: bodyFile })
+      return
+    }
+    try {
+      // 文件通道逐字快照读：空文件落空正文（不走 argv 通道的 '(no body provided)'
+      // 兜底——FR-01 落盘与源文件一致）
+      bodyFromFile = readFileSync(bodyFile, 'utf8')
+    } catch (err) {
+      output(false, {}, {
+        code: 'body_file_read_failed',
+        path: bodyFile,
+        reason: String((err && err.message) || err),
+      })
+      return
+    }
+  }
+  const hasBodyFile = bodyFileIdx >= 0
+  const bodyText = hasBodyFile ? bodyFromFile : body
+
   mkdirSync(proposedDir, { recursive: true })
 
   // 生成 slug
@@ -555,7 +509,8 @@ export async function cmdPropose(dir, args, opts = {}) {
     '',
     `# ${title}`,
     '',
-    body || '(no body provided)',
+    // argv 通道保持既有空兜底；文件通道逐字（空即空，见上方读取处注释）
+    hasBodyFile ? bodyText : (bodyText || '(no body provided)'),
     '',
     '---',
     '> This is a proposed knowledge entry. Review and merge into manual/ or generated/.',
@@ -673,15 +628,16 @@ export async function cmdKnowledge(args, dir, opts = {}) {
       '  digest                治理信号卡（rot/伪域/坏绑定——纯读）',
       '  scope                 知识注入作用域现状与标记语法（always/repo/module/关键词；纯读）',
       '  stats                 覆盖率/死条目统计（纯读）',
-      '  refresh               重扫 scan 文档重写 generated/ 区（**写盘**——先 validate 再用）',
-      '  propose / classify / inbox / graph / stats / renumber',
+      '  refresh               （已退役 2026-11-07）generated 切块死区退库——零写盘废弃提示；scan 本体由 scan 流程维护',
+      '  propose --title "..." [--body "<文本>" | --body-file <路径>] [--category <名>] [--from <来源>]   提议新知识（长中文正文用 --body-file 从文件读正文，绕开命令行传参）',
+      '  accept --id proposed/<slug> [--file <目标>] [--dry-run]   合并待审提议为正式知识（用户确认后执行；category 有效时可省 --file 自动路由）',
       '  renumber [--dry-run|--apply]  存量决策号迁移为全局号（dry-run 先行；apply 写盘幂等）',
       '  redomain-unmapped [--face decisions|fr] [--apply]  unmapped 停车场存量批量清偿（文件锚/覆盖面投票目标域；dry-run 先行）',
       '',
       '写盘面子命令（refresh/propose/classify）先跑同名只读命令确认现状；探索用法先看本帮助。',
     ]
     for (const l of lines) console.log(l)
-    output(true, { help: true, subcommands: ['search', 'inspect', 'validate', 'digest', 'refresh', 'propose', 'classify', 'inbox', 'graph', 'stats', 'scope', 'redomain-unmapped'] })
+    output(true, { help: true, subcommands: ['search', 'inspect', 'validate', 'digest', 'refresh', 'propose', 'accept', 'classify', 'inbox', 'graph', 'stats', 'scope', 'redomain-unmapped'] })
     return
   }
   const subCommand = args[0] || ''
@@ -697,6 +653,20 @@ export async function cmdKnowledge(args, dir, opts = {}) {
       return cmdRefresh(dir, args.slice(1), opts)
     case 'propose':
       return cmdPropose(dir, args.slice(1), opts)
+    case 'accept': {
+      // 待审知识收口（2026-11-07-knowledge-accept-channel）：合并 proposed 条目到正式知识
+      // 文件——动态 import 同 classify 先例（实现缺席返回友好错误）。
+      const mod = await tryImportSubcommandImpl('../knowledge-classify.js', 'knowledge-classify.js')
+      if (!mod || typeof mod.cmdKnowledgeAccept !== 'function') {
+        output(false, {}, {
+          code: 'not_implemented',
+          subcommand: 'accept',
+          message: '实现未落地（src/knowledge-classify.js cmdKnowledgeAccept）',
+        })
+        return
+      }
+      return mod.cmdKnowledgeAccept(dir, args.slice(1), opts)
+    }
     case 'redomain-unmapped': {
       // unmapped 停车场存量批量清偿（FR-04，2026-10-21-knowledge-tier-denoise）：decisions 按文件锚
       // / fr 按来源变更覆盖面投票目标域；缺省 dry-run 报告先行，--apply 幂等迁移（不裸删、冲突跳过）。
@@ -857,7 +827,7 @@ export async function cmdKnowledge(args, dir, opts = {}) {
       output(false, {}, {
         code: 'unknown_subcommand',
         subCommand: subCommand,
-        available: ['search', 'inspect', 'validate', 'refresh', 'propose', 'classify', 'inbox', 'stats', 'digest', 'graph', 'renumber', 'redomain-unmapped'],  // dump 随 graph 路由面（2026-10-09-graph-dump-layout）
+        available: ['search', 'inspect', 'validate', 'refresh', 'propose', 'accept', 'classify', 'inbox', 'stats', 'digest', 'graph', 'renumber', 'redomain-unmapped'],  // dump 随 graph 路由面（2026-10-09-graph-dump-layout）
       })
   }
 }