@sanqianx/project-knowledge 5.0.16-rc.1 → 5.0.16-rc.3

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "project-knowledge",
-      "version": "5.0.16-rc.1",
+      "version": "5.0.16-rc.3",
       "source": "./plugins/project-knowledge",
       "description": "Search durable project decisions and implementation history through MCP."
     }

package/README.md

@@ -339,6 +339,11 @@ and real-index smoke tests are reported separately. No mobile matrix or new
 Windows installer is claimed. Full crash-stage combinations and the final
 switch of a user's existing data require separate acceptance.
 
+See the [Leader / GLM Workbench playbook](docs/leader-glm-workbench-playbook.md)
+for task dispatch and independent review, and the
+[5.0.16 acceptance record](docs/release-5.0.16-acceptance.md) for this round's
+actual results and remaining gates. These documents are not a release approval.
+
 ## License
 
 [Apache-2.0](LICENSE). See [NOTICE](NOTICE).

package/_modules/knowledge-engine/README.md

@@ -76,7 +76,7 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 
 开发前 `/api/context` 复用正式检索与记忆适用范围校验，不运行分析模型、不写知识树。默认本项目优先、相关时补充所属领域；适用记忆独立准备，即使需求没有偏好关键词也保留。完整注入最多 8,000 字符，记忆最多 3,000 字符；剩余事实预算本项目保留 70%，领域参考最多 30%，不凑满低质量结果。候选、忽略、失效及未同步投影不进入上下文，向量故障明确标为 `file-fallback`。输入的凭据样式在向量查询前脱敏，不记录原需求或知识正文。读取日志的 `knowledge.context.prepared` 只证明准备完成，不能冒充模型送达证据。
 
-检索排序 `project-knowledge/ranking-v2` 在当前文件片段上使用中文分词 BM25 与向量片段 RRF 融合，不直接叠加原始分数。vector-hub 的可选 `resultLevel=chunk` 返回 LF 规范化正文哈希及半开字符范围；匹配只影响相应片段，不扩散至整篇。原文变化、删除、项目归属变化及记忆失效都会重新验证；未知或未标定模型不能只凭高向量分返回知识。`retrieval-policy.json` 的 embo-01 / 1536 维门槛来自固定语料的训练问题族，测试问题族不参与选择；不是对任意语料准确率的保证。
+检索排序 `project-knowledge/ranking-v2` 在当前文件片段上使用中文分词 BM25 与向量片段 RRF 融合，不直接叠加原始分数。vector-hub 的可选 `resultLevel=chunk` 返回 LF 规范化正文哈希及半开字符范围；匹配只影响相应片段，不扩散至整篇。已校验范围不足半个词法分块时，引擎从当前规范正文按同一半开坐标系截取独立片段候选，进入同一 RRF 融合，纯语义命中不因分块尺寸不一致而丢失；重复段落按文档顺序定位，周期性重复文本不得把后续分块拉回更早的重复位置伪造向量证据。词法分块器为版本 2：标题边界围栏感知，代码围栏内的 `#` 注释不再切成伪小节，分块几何随版本号封入 documentHash。既有 v5 数据的 version-1 词法缓存因此哈希失配，经当前文件、版本与哈希校验走安全 delta overlay 按需重建派生索引；知识正文与来源不改写，不做全量分析，也不强制全量 embedding 索引重建，向量行按正文哈希独立校验不受影响。健康信息只记录召回、合并、截取与各类拒绝计数，不回显知识正文。原文变化、删除、项目归属变化及记忆失效都会重新验证；未知或未标定模型不能只凭高向量分返回知识。`retrieval-policy.json` 的 embo-01 / 1536 维门槛来自固定语料的训练问题族，测试问题族不参与选择；不是对任意语料准确率的保证。
 
 普通搜索每篇最多两个互补片段，精确提交与源文件仍优先。`search` 增加 `intent`、`rankingVersion`、`matchStatus`、`currentProjectStatus` 和 `matchReason` 等兼容字段；最近进度优先当前项目维护历史，时间来源区分提交依据、晋升和 mtime 回退。问候不进行主题召回，短追问仅复用同项目同会话五分钟内仍有效的引用，引用缓存只在内存中且有界，不保存原对话。索引故障与“本次无可靠匹配”不等于知识为空。
 
@@ -90,7 +90,7 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 - 无头分析在隔离进程中运行，只读冻结证据，只写本次 staging。产物必须通过路径、内容 hash 和依据校验，只有晋升路径写最终项目知识。
 - 归档对话和检索内容只作证据，不能覆盖后台维护指令。SDK 返回成功文字但未生成 manifest 时，记录 `ANALYSIS_OUTPUT_MISSING` 并保留证据供重试，不误报晋升完成。
 - 空知识库是正常首用状态。输出合同明确 UTF-8、一级标题和非空正文；仅缺标题的非空文档在 staging 中确定性补齐并重新封印哈希，空正文、非法路径、占位内容或不匹配哈希仍拒绝晋升。
-- 占位检测区分未完成正文与源码示例：HTML 的 `placeholder=` 属性、行内代码和有正文解释的围栏代码不被误判为未完成知识；只有标题或仅用代码包裹未完成标记的文档仍拒绝。校验不改写有效原文。
+- 占位检测区分未完成正文与源码示例：HTML 的 `placeholder=` 属性、行内代码和有正文解释的围栏代码不被误判为未完成知识；只有标题或仅用代码包裹未完成标记的文档仍拒绝。裸 `placeholder` 术语只在 UI 语境加完整事实谓语时放行——中文事实动词（属性、校验、描述等）或英文完整说明谓语（describes、specifies 等），且句内不得出现待补、后续补齐等待填措辞；空引号或仅省略号的样例只在紧邻该术语或其限定词（属性说明、值为、value is 等）之后才拒绝，同句其它字段的空值不计入。`TBD` 仅在讨论标记机制本身的完整规则清单事实中放行（如"均未改动""之外不再有其它"且其后有实际文本），正则、围栏等技术名词本身不构成豁免，计划谓语（实现 TBD、方案待定）仍拒绝。校验不改写有效原文。
 - 具体失败原因、失败步骤和提交依据进入运行详情及 `log/v2` 诊断。受外壳守护时通过 IPC 交给外壳现有日志系统；独立运行保存在 `<data>/logs/`，不写模型凭据和原始证据。升级不会重新运行已失败提交，用户可显式重试失败阶段。
 - 数据目录有单实例租约，目标知识目录有写入锁。关闭或超时等待子进程实际退出，再释放写入锁。
 - 晋升与索引分别记录。索引失败保留已晋升知识并显示待修复，不重新调用模型。

package/_modules/knowledge-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/ai-coding-knowledge-engine",
-  "version": "0.2.7-rc.5",
+  "version": "0.2.7-rc.6",
   "description": "Knowledge engine module for project-knowledge: commit-boundary triggered knowledge analysis/generation (trigger plane) and retrieval for development assistants (retrieval plane).",
   "license": "Apache-2.0",
   "main": "src/server.js",

package/_modules/knowledge-engine/src/retrieval.js

@@ -3,12 +3,30 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { KnowledgeRetrievalService } = require('./runtime/knowledge-retrieval-service');
-const { listMarkdownFiles, isExcludedKnowledgePath, CHUNKER_VERSION } = require('./runtime/markdown-knowledge-indexer');
+const { listMarkdownFiles, isExcludedKnowledgePath, CHUNKER_VERSION, lineFenceState, headingOf } = require('./runtime/markdown-knowledge-indexer');
 const { DomainError } = require('./runtime/contracts');
+const { sha256 } = require('./runtime/content-hash');
 const ranking = require('./retrieval-ranking');
 const fileNames = query => [...new Set((String(query).match(/[\p{L}\p{N}_./\\-]+\.(?:cjs|mjs|js|jsx|ts|tsx|py|cs|cpp|c|h|hpp|rs|go|html|css|scss|json|ya?ml|toml|md|txt|sh|ps1)\b/giu) || []).map(value => path.posix.basename(value.replace(/\\/g, '/')).toLowerCase()))].slice(0, 20);
 const mentionsFile = (candidate, name) => new RegExp(`(?<![\\p{L}\\p{N}_-])${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\p{L}\\p{N}_.-])`, 'iu').test([candidate.entryId, candidate.title, candidate.chunkText, ...(candidate.metadata?.sourcePaths || [])].join('\n'));
 
+const headingPathAt = (body, pos) => {
+  const headings = [];
+  let fence = null;
+  let offset = 0;
+  for (const line of String(body).split('\n')) {
+    const lineStart = offset;
+    offset += line.length + 1;
+    if (lineStart > pos) break;
+    fence = lineFenceState(line, fence);
+    if (fence) continue;
+    const heading = headingOf(line);
+    if (heading) { headings.length = heading.level - 1; headings[heading.level - 1] = heading.text; }
+  }
+  return headings.filter(Boolean);
+};
+const overlapOf = (aStart, aEnd, bStart, bEnd) => Math.max(0, Math.min(aEnd, bEnd) - Math.max(aStart, bStart));
+
 class EngineRetrieval extends KnowledgeRetrievalService {
   constructor(options) { super(options); this.store = options.store; this.memories = options.memories; this.vectorUrl = options.vectorUrl || 'http://127.0.0.1:8787'; this.retrievalPolicy = options.retrievalPolicy || require('./retrieval-policy.json'); }
   async retrieve(input = {}) {
@@ -23,11 +41,23 @@ class EngineRetrieval extends KnowledgeRetrievalService {
       const key = `${c.spaceId}:${c.entryId}`;
       try {
         if (!bodies.has(key)) bodies.set(key, ranking.bodyText(fs.readFileSync(path.join(c.knowledgePath, c.entryId), 'utf8')));
-        const body = bodies.get(key), start = body.indexOf(c.chunkText);
-        c.bodyHash = ranking.bodyHash(body); c.bodyLength = body.length; c.startPos = start; c.endPos = start < 0 ? -1 : start + c.chunkText.length;
       } catch { scanned.candidates.delete(id); }
     }
-    if (!['greeting', 'followup'].includes(ranking.intent(signals.indexQuery))) await this.recallIndex(scopes, signals.indexQuery, scanned.candidates, health);
+    // The canonical chunker emits authoritative half-open offsets into the same
+    // body coordinate system. A position is accepted only when the current
+    // body still slices to the exact chunk text; anything else degrades to
+    // unpositioned instead of guessing by search.
+    for (const c of scanned.candidates.values()) {
+      const body = bodies.get(`${c.spaceId}:${c.entryId}`);
+      const positioned = Boolean(body) && Number.isInteger(c.chunkStart) && Number.isInteger(c.chunkEnd)
+        && c.chunkStart >= 0 && c.chunkEnd > c.chunkStart && c.chunkEnd <= body.length && body.slice(c.chunkStart, c.chunkEnd) === c.chunkText;
+      c.bodyHash = body ? ranking.bodyHash(body) : null;
+      c.bodyLength = body ? body.length : 0;
+      c.startPos = positioned ? c.chunkStart : -1;
+      c.endPos = positioned ? c.chunkEnd : -1;
+    }
+    const lexicalChunkCount = scanned.candidates.size;
+    if (!['greeting', 'followup'].includes(ranking.intent(signals.indexQuery))) await this.recallIndex(scopes, signals.indexQuery, scanned.candidates, health, bodies);
     else health.index = 'not-requested';
     if (stamp !== scopeStamp(this.store.getProject(project.projectId))) throw new DomainError('PROJECT_SCOPE_CHANGED', '项目归属或绑定已变化，请重新检索。', { status: 409 });
     for (const [id, c] of scanned.candidates) {
@@ -58,7 +88,7 @@ class EngineRetrieval extends KnowledgeRetrievalService {
       if (checked.get(key)) candidates.push(c);
       if (candidates.length >= this.candidateLimit) break;
     }
-    return { project, scopes, signals, health, candidates, totalCurrentChunks: scanned.candidates.size, intent: ranking.intent(signals.indexQuery) };
+    return { project, scopes, signals, health, candidates, totalCurrentChunks: lexicalChunkCount, intent: ranking.intent(signals.indexQuery) };
   }
   signalSet(input = {}) {
     const signals = super.signalSet(input);
@@ -122,13 +152,21 @@ class EngineRetrieval extends KnowledgeRetrievalService {
     result.scopeHealth.push(...extra.scopeHealth);
     return result;
   }
-  async recallIndex(scopes, query, current, health) {
+  async recallIndex(scopes, query, current, health, bodies) {
     if (!query) { health.index = 'unavailable'; return; }
     // File identifiers, like commit IDs, select current facts before semantic
     // ranking. A not-yet-known filename still permits analogous background.
     const named = fileNames(query), known = named.filter(name => [...current.values()].some(candidate => mentionsFile(candidate, name)));
     for (const candidate of current.values()) { candidate.knownFileQuery = known.length > 0; candidate.fileReferences = known.filter(name => mentionsFile(candidate, name)); }
     const mappings = scopes.map(s => ({ scope: s, registration: this.store.getProject(s.projectId) || (() => { const shared = this.store.state.sharedScopes.find(p => p.id === s.projectId); return shared ? { vectorProjectId: `scope-${shared.kind}-${shared.id}` } : null; })() })).filter(m => m.registration);
+    const recall = { rows: 0, merges: 0, slices: 0, rejected: {} };
+    const reject = reason => { recall.rejected[reason] = (recall.rejected[reason] || 0) + 1; };
+    const anchors = new Map();
+    for (const candidate of current.values()) {
+      const key = `${candidate.spaceId}:${candidate.entryId}`;
+      if (!anchors.has(key)) anchors.set(key, candidate);
+    }
+    const pending = [];
     try {
       const url = new URL('/api/search', this.vectorUrl);
       url.searchParams.set('q', query);
@@ -145,33 +183,90 @@ class EngineRetrieval extends KnowledgeRetrievalService {
       // Vectors only contribute a rank. Displayed text/hash always comes from
       // current canonical files, so deleted or stale index bodies cannot leak.
       for (const row of payload.results || []) {
+        recall.rows += 1;
         const mapping = mappings.find(m => (m.registration.vectorProjectId || m.scope.projectId) === row.project);
-        if (!mapping) continue;
+        if (!mapping) { reject('unknown-project'); continue; }
         const uri = row.uri || row.documentUri || '';
         const entry = path.isAbsolute(uri) ? path.relative(mapping.scope.knowledgePath, uri).replace(/\\/g, '/') : String(uri).replace(/\\/g, '/');
+        const key = `${mapping.scope.spaceId}:${entry}`;
+        const anchor = anchors.get(key);
+        if (!anchor || !bodies || !bodies.has(key)) { reject('no-current-document'); continue; }
+        const valid = row.scoreType === 'cosine' && row.bodyHash === anchor.bodyHash && Number.isInteger(row.startPos) && Number.isInteger(row.endPos)
+          && row.startPos >= 0 && row.endPos > row.startPos && row.endPos <= anchor.bodyLength;
+        if (!valid) { reject(row.bodyHash === anchor.bodyHash ? 'invalid-range' : 'body-hash-mismatch'); continue; }
+        const value = Number(row.score);
+        if (!Number.isFinite(value) || value < -1 || value > 1) { reject('invalid-score'); continue; }
         for (const candidate of current.values()) {
-          if (candidate.spaceId === mapping.scope.spaceId && candidate.entryId === entry) {
-            const valid = row.scoreType === 'cosine' && row.bodyHash === candidate.bodyHash && Number.isInteger(row.startPos) && Number.isInteger(row.endPos)
-              && row.startPos >= 0 && row.endPos > row.startPos && row.endPos <= candidate.bodyLength && candidate.startPos >= 0;
-            const overlap = valid ? Math.max(0, Math.min(candidate.endPos, row.endPos) - Math.max(candidate.startPos, row.startPos)) : 0;
-            if (!overlap) continue;
-            const value = Number(row.score);
-            if (!Number.isFinite(value) || value < -1 || value > 1) continue;
-            candidate.indexScore = Math.max(candidate.indexScore || 0, Math.max(0, value));
-            candidate.vectorRanges ||= [];
-            candidate.vectorRanges.push([Math.max(candidate.startPos, row.startPos), Math.min(candidate.endPos, row.endPos)]);
-            const ranges = [...candidate.vectorRanges].sort((a, b) => a[0] - b[0]);
-            let covered = 0, end = -1;
-            for (const range of ranges) { covered += Math.max(0, range[1] - Math.max(end, range[0])); end = Math.max(end, range[1]); }
-            if (covered >= candidate.chunkText.length * 0.5) { candidate.indexChannels = ['vector-hub']; candidate.vectorVerified = true; }
-            if (calibrated) { candidate.vectorCalibrated = true; candidate.vectorMinScore = calibrated.minScore; }
-          }
+          if (candidate.fromVectorRange || candidate.spaceId !== mapping.scope.spaceId || candidate.entryId !== entry || candidate.startPos < 0) continue;
+          const overlap = Math.max(0, Math.min(candidate.endPos, row.endPos) - Math.max(candidate.startPos, row.startPos));
+          if (!overlap) continue;
+          recall.merges += 1;
+          candidate.indexScore = Math.max(candidate.indexScore || 0, Math.max(0, value));
+          candidate.vectorRanges ||= [];
+          candidate.vectorRanges.push([Math.max(candidate.startPos, row.startPos), Math.min(candidate.endPos, row.endPos)]);
+          const ranges = [...candidate.vectorRanges].sort((a, b) => a[0] - b[0]);
+          let covered = 0, end = -1;
+          for (const range of ranges) { covered += Math.max(0, range[1] - Math.max(end, range[0])); end = Math.max(end, range[1]); }
+          if (covered >= candidate.chunkText.length * 0.5) { candidate.indexChannels = ['vector-hub']; candidate.vectorVerified = true; }
+          if (calibrated) { candidate.vectorCalibrated = true; candidate.vectorMinScore = calibrated.minScore; }
         }
+        const sliceText = bodies.get(key).slice(row.startPos, row.endPos);
+        if (!sliceText.trim()) { reject('empty-slice'); continue; }
+        let duplicate = false;
+        for (const candidate of current.values()) {
+          if (!candidate.fromVectorRange || candidate.spaceId !== mapping.scope.spaceId || candidate.entryId !== entry) continue;
+          if (overlapOf(candidate.startPos, candidate.endPos, row.startPos, row.endPos) * 2 >= Math.min(candidate.endPos - candidate.startPos, row.endPos - row.startPos)) { duplicate = true; break; }
+        }
+        for (const prior of pending) {
+          if (prior.scope.spaceId !== mapping.scope.spaceId || prior.entry !== entry) continue;
+          if (overlapOf(prior.row.startPos, prior.row.endPos, row.startPos, row.endPos) * 2 >= Math.min(prior.row.endPos - prior.row.startPos, row.endPos - row.startPos)) { duplicate = true; break; }
+        }
+        if (duplicate) continue;
+        pending.push({ scope: mapping.scope, key, entry, anchor, row, sliceText, value, calibrated });
+      }
+      for (const p of pending) {
+        recall.slices += 1;
+        const recordId = `${p.scope.spaceId}:${p.entry}:vector:${p.row.startPos}-${p.row.endPos}`;
+        current.set(recordId, {
+          recordId,
+          spaceId: p.scope.spaceId,
+          projectId: p.scope.projectId,
+          scopeReason: p.scope.reason,
+          // A slice inherits the anchor candidate's own scope weight: a project
+          // memory keeps project weight even inside a lower-weight shared scope.
+          scopeWeight: p.anchor.scopeWeight,
+          fromVectorRange: true,
+          knowledgePath: p.scope.knowledgePath,
+          entryId: p.entry,
+          entryType: p.anchor.entryType,
+          chunkId: `${p.entry}:vector:${p.row.startPos}-${p.row.endPos}`,
+          chunkOrder: null,
+          title: p.anchor.title,
+          headingPath: headingPathAt(bodies.get(p.key), p.row.startPos),
+          chunkText: p.sliceText,
+          documentHash: p.anchor.documentHash,
+          contentHash: sha256(p.sliceText),
+          metadata: p.anchor.metadata,
+          fromOverlay: p.anchor.fromOverlay,
+          bodyHash: p.anchor.bodyHash,
+          bodyLength: p.anchor.bodyLength,
+          startPos: p.row.startPos,
+          endPos: p.row.endPos,
+          indexScore: Math.min(1, Math.max(0, p.value)),
+          indexChannels: ['vector-hub'],
+          vectorRanges: [[p.row.startPos, p.row.endPos]],
+          vectorVerified: true,
+          knownFileQuery: known.length > 0,
+          fileReferences: known.filter(name => mentionsFile({ entryId: p.entry, title: p.anchor.title, chunkText: p.sliceText, metadata: p.anchor.metadata }, name)),
+          ...(p.calibrated ? { vectorCalibrated: true, vectorMinScore: p.calibrated.minScore } : {}),
+        });
       }
       health.index = payload.projectsSkipped?.length ? 'partial' : 'ok';
-      health.verifiedVectorChunks = [...current.values()].filter(c => c.vectorVerified).length;
+      health.verifiedVectorChunks = [...current.values()].filter(c => c.vectorVerified && !c.fromVectorRange).length;
       health.vectorMode = payload.resultLevel === 'chunk' ? 'verified-chunks' : 'legacy-document-results';
     } catch { health.index = 'degraded'; health.reason = 'vector-hub-unavailable'; }
+    health.vectorRecall = recall;
+    health.verifiedVectorSlices = recall.slices;
   }
   async search(input = {}) {
     const registration = this.resolve(input);

package/_modules/knowledge-engine/src/runtime/knowledge-promotion.js

@@ -48,7 +48,26 @@ function decodeUtf8(buffer) {
 // A quoted sample is exempt only when the same sentence of the original
 // document names a concrete UI field or attribute context; a quoted marker
 // without that context is still unfinished prose, whatever it quotes.
-const UI_CONTEXT = /(?:<(?:input|textarea|select)\b|#[a-zA-Z][\w-]*|\b(?:input|textarea|select|field|form|dialog|ui|html|attribute)\b|属性|字段|输入|表单|对话框|界面|控件|提示|文案)/i;
+const UI_CONTEXT = /(?:<(?:input|textarea|select)\b|#[a-zA-Z][\w-]*|\b(?:input|textarea|select|field|form|dialog|ui|html|attribute)\b|属性|字段|输入|表单|对话框|界面|控件|提示|文案)/i;
+const FACTUAL_TERM = /(?:事实|属性|校验|验证|描述|说明|区分|识别|判定|误判|放行|拒绝|豁免|术语|样例|示例|规则|正则|边界)/;
+// Full predicate inflections only (noun forms like "description" do not
+// vouch for an attribute by themselves).
+const FACTUAL_TERM_EN = /\b(?:describ(?:es?|ed|ing)|specif(?:ies|ied|ying)|defin(?:es?|ed|ing)|indicat(?:es?|ed|ing)|displa(?:ys?|yed|ying)|provid(?:es?|ed|ing)|show(?:s?|n|ing)|control(?:s?|led|ling)|explain(?:s?|ed|ing)|document(?:s?|ed|ing))\b/i;
+const INCOMPLETE_LATER = /(?:待补|待填|待定|待完成|待完善|后续补充|后续补齐|后续再说|尚未|还没|暂未|fill this in|later|\bpending\b|\bunfinished\b|\bnot\s+yet\b)/i;
+const EMPTY_SAMPLE = /[「"'“][ \t]*[.．…]*[ \t]*[」"'”]/;
+// An empty sample counts only inside this placeholder's own noun phrase:
+// right beside the term or behind a short qualifier such as 属性说明 or
+// "value is"; once a real predicate starts, later empty values belong to
+// other fields and must not veto this mention.
+const OWN_EMPTY_SAMPLE = new RegExp(
+  '^[ \\t]*(?:的[ \\t]*)?(?:默认值|属性|字段|输入|提示|文案|样例|样本|示例|说明|描述|值|attribute|value|sample|text|label)?'
+    + '[ \\t]*(?:说明|描述|样例|样本|示例|文案|值)?[ \\t]*(?:是|为|is|=|:|：)?[ \\t]*' + EMPTY_SAMPLE.source,
+  'i'
+);
+// A TBD mention passes only inside a complete factual predicate about the
+// marker machinery itself: an unchanged or nothing-beyond claim with real
+// text after the mention. Technical nouns alone never vouch for TBD.
+const TBD_COMPLETE_FACT = /(?:未改动|未调整|未变化|未修改|保持不变|保持原样|之外不再|不再有其它|没有其它)/;
 
 function sentenceAround(text, index) {
   const delimiters = /[。！？；\n.!?;]/g;
@@ -72,25 +91,60 @@ function maskCoded(content) {
     .replace(/(`+)[^\n]*?\1/g, span => span.replace(/[^\n]/g, ' '));
 }
 
-function unfinishedPlaceholder(prose, source) {
-  const re = /\bplaceholder\b[ \t]*(=|[「"'“][^」"'”]*[」"'”])?/gi;
-  let match;
-  while ((match = re.exec(prose))) {
-    if (match[1] === '=') continue;
-    if (match[1]) {
-      const sample = match[1].slice(1, -1).trim();
-      if (!sample || /^[.．…]+$/.test(sample)) return match[0];
-      // Context must come from this very sentence, outside the quoted value,
-      // so neither an earlier twin hit nor the sample itself can vouch for it.
-      const sentence = sentenceAround(source, match.index);
-      const quoteOffset = match.index + match[0].length - match[1].length - sentence.start;
-      const context = sentence.text.slice(0, quoteOffset) + ' '.repeat(match[1].length) + sentence.text.slice(quoteOffset + match[1].length);
-      if (UI_CONTEXT.test(context)) continue;
-    }
-    return match[0];
-  }
-  return null;
-}
+function unfinishedPlaceholder(prose, source) {
+  const re = /\bplaceholder\b[ \t]*(=|[「"'“][^」"'”]*[」"'”]|[「"'“])?/gi;
+  let match;
+  while ((match = re.exec(prose))) {
+    if (match[1] === '=') continue;
+    // The same sentence governs the decision; inline code stays masked so it
+    // can lend neither context nor samples.
+    const sentence = sentenceAround(source, match.index);
+    const masked = maskCoded(sentence.text);
+    // An empty or ellipsis-only quoted sample is an unfinished hole only in
+    // this placeholder's own noun phrase: directly after the term or after
+    // a qualifier such as 属性说明 or "value is". Empty values owned by
+    // another field later in the sentence never veto the mention.
+    const rest = masked.slice(match.index - sentence.start + match[0].length).split(/[，,]/)[0];
+    if (OWN_EMPTY_SAMPLE.test(rest)) return match[0];
+    // A quote that opens right beside the placeholder yet never closes is an
+    // unfinished sample, not an attribute mention.
+    if (match[1] && match[1].length === 1) return match[0];
+    if (match[1]) {
+      const sample = match[1].slice(1, -1).trim();
+      if (!sample || /^[.．…]+$/.test(sample)) return match[0];
+      // Context must come from this very sentence, outside the quoted value,
+      // so neither an earlier twin hit nor the sample itself can vouch for it.
+      const quoteOffset = match.index + match[0].length - match[1].length - sentence.start;
+      const context = sentence.text.slice(0, quoteOffset) + ' '.repeat(match[1].length) + sentence.text.slice(quoteOffset + match[1].length);
+      if (UI_CONTEXT.test(context)) continue;
+    } else {
+      // A bare term passes only as a factual description of the UI attribute:
+      // UI context in the raw sentence plus a factual predicate in the prose
+      // (Chinese verb or complete English description verb) with no
+      // to-be-filled wording.
+      if (UI_CONTEXT.test(sentence.text) && (FACTUAL_TERM.test(masked) || FACTUAL_TERM_EN.test(masked)) && !INCOMPLETE_LATER.test(masked)) continue;
+    }
+    return match[0];
+  }
+  return null;
+}
+
+// TBD may be named only as the topic of a complete rule-list fact, never as
+// the predicate of a planning sentence. The completion predicate must sit in
+// the same comma clause after the mention: 、 enumerations stay inside the
+// clause, and a fact from a neighbouring clause never vouches for this TBD.
+function unfinishedTbd(prose, source) {
+  const re = /\bTBD\b/gi;
+  let match;
+  while ((match = re.exec(prose))) {
+    const sentence = sentenceAround(source, match.index);
+    const masked = maskCoded(sentence.text);
+    const clause = masked.slice(match.index - sentence.start + match[0].length).split(/[，,]/)[0];
+    if (TBD_COMPLETE_FACT.test(clause) && !INCOMPLETE_LATER.test(masked)) continue;
+    return match[0];
+  }
+  return null;
+}
 
 function validateMarkdown(content, relativePath) {
   if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(content)) {
@@ -100,10 +154,12 @@ function validateMarkdown(content, relativePath) {
   // UI attributes and quoted source samples describe real changes; they are
   // not unfinished prose. Quoted samples still need a UI context in the same
   // sentence, so fencing a placeholder cannot make it valid knowledge.
-  const marker = /(?:\[TODO:|\bTODO:\s|\bTBD\b)/i;
-  const prose = maskCoded(content);
-  const bare = !prose.replace(/^#{1,6}[ \t]+.*$/gm, '').trim();
-  if (marker.test(prose) || unfinishedPlaceholder(prose, content) || bare && (marker.test(content) || unfinishedPlaceholder(content, content))) {
+  const hardMarker = /(?:\[TODO:|\bTODO:\s)/i;
+  const tbd = /\bTBD\b/i;
+  const prose = maskCoded(content);
+  const bare = !prose.replace(/^#{1,6}[ \t]+.*$/gm, '').trim();
+  if (hardMarker.test(prose) || unfinishedTbd(prose, content) || unfinishedPlaceholder(prose, content)
+    || bare && (hardMarker.test(content) || tbd.test(content) || unfinishedPlaceholder(content, content))) {
     throw new DomainError('INVALID_ARGUMENT', `Placeholder knowledge is not allowed: ${relativePath}.`);
   }
   const fences = content.match(/^```/gm) || [];

package/_modules/knowledge-engine/src/runtime/knowledge-retrieval-service.js

@@ -140,12 +140,14 @@ class KnowledgeRetrievalService {
             knowledgePath: scope.knowledgePath,
             entryId,
             entryType: inferEntryType(entryId),
-            chunkId,
-            chunkOrder: chunk.chunkOrder,
-            title,
-            headingPath: chunk.headingPath,
-            chunkText: chunk.chunkText,
-            documentHash,
+            chunkId,
+            chunkOrder: chunk.chunkOrder,
+            title,
+            headingPath: chunk.headingPath,
+            chunkText: chunk.chunkText,
+            chunkStart: Number.isInteger(chunk.startPos) ? chunk.startPos : null,
+            chunkEnd: Number.isInteger(chunk.endPos) ? chunk.endPos : null,
+            documentHash,
             contentHash: documentSha256(chunk.chunkText),
             metadata,
             fromOverlay,

package/_modules/knowledge-engine/src/runtime/markdown-knowledge-indexer.js

@@ -1,8 +1,12 @@
-const fs = require('fs');
-const path = require('path');
-const { sha256 } = require('./content-hash');
+const fs = require('fs');
+const path = require('path');
+const { sha256 } = require('./content-hash');
+const { bodyText } = require('../retrieval-ranking');
 
-const CHUNKER_VERSION = 1;
+// Version 2: fence-aware heading boundaries changed real chunk geometry (a
+// fenced '#' comment no longer splits a section), so version-1 lexical caches
+// must miss their sealed document hash and rebuild through the delta overlay.
+const CHUNKER_VERSION = 2;
 const DEFAULT_MAX_CHARS = 1200;
 const DEFAULT_OVERLAP_CHARS = 120;
 const EXCLUDED_DIRS = new Set(['.git', '_ai', '_backup', 'node_modules', 'dev-conversations']);
@@ -43,67 +47,102 @@ function parseKnowledgeMetadata(markdown) {
   };
 }
 
-function splitLongText(text, maxChars, overlapChars) {
-  const clean = String(text || '').trim();
-  if (!clean) return [];
-  if (clean.length <= maxChars) return [clean];
-  const parts = [];
-  let start = 0;
-  while (start < clean.length) {
+function splitLongText(text, maxChars, overlapChars, base = 0) {
+  const raw = String(text || '');
+  const clean = raw.trim();
+  if (!clean) return [];
+  const origin = base + (raw.length - raw.trimStart().length);
+  if (clean.length <= maxChars) return [{ text: clean, start: origin, end: origin + clean.length }];
+  const parts = [];
+  let start = 0;
+  while (start < clean.length) {
     let end = Math.min(start + maxChars, clean.length);
     if (end < clean.length) {
       const floor = start + Math.floor(maxChars * 0.6);
       const boundary = Math.max(clean.lastIndexOf('\n\n', end), clean.lastIndexOf('。', end), clean.lastIndexOf('. ', end));
       if (boundary >= floor) end = boundary + 1;
     }
-    parts.push(clean.slice(start, end).trim());
-    if (end >= clean.length) break;
-    start = Math.max(start + 1, end - overlapChars);
-  }
-  return parts.filter(Boolean);
-}
-
-function chunkMarkdown(markdown, options = {}) {
-  const maxChars = Number(options.maxChars || DEFAULT_MAX_CHARS);
-  const overlapChars = Math.min(Number(options.overlapChars || DEFAULT_OVERLAP_CHARS), Math.floor(maxChars / 3));
-  const body = stripFrontmatter(markdown).replace(/\r\n/g, '\n');
-  const lines = body.split('\n');
-  const headings = [];
-  const sections = [];
-  let buffer = [];
-  let sectionHeadings = [];
-
-  const flush = () => {
-    const text = buffer.join('\n').trim();
-    if (text) sections.push({ headingPath: [...sectionHeadings], text });
-    buffer = [];
-  };
-
-  for (const line of lines) {
-    const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
-    if (match) {
-      flush();
-      const level = match[1].length;
-      headings.length = level - 1;
-      headings[level - 1] = match[2].trim();
-      sectionHeadings = headings.filter(Boolean);
-      buffer.push(line);
-    } else {
-      buffer.push(line);
-    }
-  }
-  flush();
-
-  const chunks = [];
-  for (const section of sections) {
-    for (const text of splitLongText(section.text, maxChars, overlapChars)) {
-      chunks.push({
-        chunkOrder: chunks.length,
-        headingPath: section.headingPath,
-        chunkText: text,
-      });
-    }
-  }
+    const piece = clean.slice(start, end);
+    const trimmed = piece.trim();
+    if (trimmed) {
+      const lead = piece.length - piece.trimStart().length;
+      parts.push({ text: trimmed, start: origin + start + lead, end: origin + start + lead + trimmed.length });
+    }
+    if (end >= clean.length) break;
+    start = Math.max(start + 1, end - overlapChars);
+  }
+  return parts;
+}
+
+// Heading and fence parsing must stay identical to the slice heading scan in
+// retrieval.js so vector slices report the same heading paths as chunks.
+function lineFenceState(line, fence) {
+  const marker = /^([ \t]*)(`{3,}|~{3,})(.*)$/.exec(line);
+  if (!marker) return fence;
+  if (!fence) return marker[2];
+  if (fence[0] === marker[2][0] && marker[2].length >= fence.length && !marker[3].trim()) return null;
+  return fence;
+}
+
+function headingOf(line) {
+  const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+  return match ? { level: match[1].length, text: match[2].trim() } : null;
+}
+
+function chunkMarkdown(markdown, options = {}) {
+  const maxChars = Number(options.maxChars || DEFAULT_MAX_CHARS);
+  const overlapChars = Math.min(Number(options.overlapChars || DEFAULT_OVERLAP_CHARS), Math.floor(maxChars / 3));
+  const body = bodyText(markdown);
+  const lines = body.split('\n');
+  const headings = [];
+  const sections = [];
+  let buffer = [];
+  let bufferStart = 0;
+  let sectionHeadings = [];
+  let fence = null;
+
+  const flush = () => {
+    const text = buffer.join('\n');
+    const trimmed = text.trim();
+    if (trimmed) {
+      const lead = text.length - text.trimStart().length;
+      const trail = text.length - text.trimEnd().length;
+      sections.push({ headingPath: [...sectionHeadings], text: trimmed, start: bufferStart + lead, end: bufferStart + text.length - trail });
+    }
+    buffer = [];
+  };
+
+  let offset = 0;
+  for (const line of lines) {
+    const lineStart = offset;
+    offset += line.length + 1;
+    fence = lineFenceState(line, fence);
+    // Only real headings outside code fences split sections; a fenced '#'
+    // comment is plain content.
+    const heading = fence ? null : headingOf(line);
+    if (heading) {
+      flush();
+      headings.length = heading.level - 1;
+      headings[heading.level - 1] = heading.text;
+      sectionHeadings = headings.filter(Boolean);
+    }
+    if (!buffer.length) bufferStart = lineStart;
+    buffer.push(line);
+  }
+  flush();
+
+  const chunks = [];
+  for (const section of sections) {
+    for (const part of splitLongText(section.text, maxChars, overlapChars, section.start)) {
+      chunks.push({
+        chunkOrder: chunks.length,
+        headingPath: section.headingPath,
+        chunkText: part.text,
+        startPos: part.start,
+        endPos: part.end,
+      });
+    }
+  }
   return chunks;
 }
 
@@ -223,11 +262,13 @@ class MarkdownKnowledgeIndexer {
   }
 }
 
-module.exports = {
-  MarkdownKnowledgeIndexer,
-  CHUNKER_VERSION,
-  chunkMarkdown,
-  listMarkdownFiles,
+module.exports = {
+  MarkdownKnowledgeIndexer,
+  CHUNKER_VERSION,
+  chunkMarkdown,
+  lineFenceState,
+  headingOf,
+  listMarkdownFiles,
   isExcludedKnowledgePath,
   isDerivedIndex,
   inferEntryType,