feat(package): context-knowledge-query 按证据链查询

packages/context-cli/src/__tests__/pluginWorkspaceGuard.test.ts

@@ -166,9 +166,10 @@ describe("plugin and workflow workspace guard", () => {
       join(CONTEXT_PACKAGE_ROOT, "templates", "package-templates", "kb", "skills", "context-knowledge-query", "SKILL.md"),
       "utf8",
     );
-    expect(template).toContain("Query Procedure");
     expect(template).toContain("Find The Packages");
-    expect(template).toContain("Going Back To The Sources");
+    expect(template).toContain("Follow The Evidence Chain");
+    expect(template).toContain("Read The Sources");
+    expect(template).toContain("Code at a recorded commit");
     expect(template).toContain("`{{guidesRoot}}/`");
     expect(template).toContain("`{{rulesRoot}}/`");
     expect(template).toContain("context-build-inventory.json");
@@ -189,6 +190,8 @@ describe("plugin and workflow workspace guard", () => {
       "utf8",
     );
     expect(localizedTemplate).toContain("## 找到知识包");
+    expect(localizedTemplate).toContain("## 沿证据链查询");
+    expect(localizedTemplate).toContain("### 记录提交上的代码");
     expect(localizedTemplate).toContain("{{!-- 模板作者说明");
     expect(localizedTemplate).toContain("others/context/search-guide.md");
     expect(localizedTemplate).not.toContain("C4A");

packages/context-cli/src/__tests__/projectV060.test.ts

@@ -84,11 +84,11 @@ describe("0.6.0 project init and source ensure", () => {
         join(project, "src", "package-templates", "kb", "skills", "context-knowledge-query", "SKILL.md"),
         "utf8",
       );
-      expect(knowledgeQueryTemplate).toContain("Answer from approved knowledge packages");
-      expect(knowledgeQueryTemplate).toContain("Query Procedure");
+      expect(knowledgeQueryTemplate).toContain("follow their\nevidence chain");
+      expect(knowledgeQueryTemplate).toContain("Follow The Evidence Chain");
       expect(knowledgeQueryTemplate).toContain("Find The Packages");
-      expect(knowledgeQueryTemplate).toContain("Evidence Contract");
-      expect(knowledgeQueryTemplate).toContain("Going Back To The Sources");
+      expect(knowledgeQueryTemplate).toContain("Read The Sources");
+      expect(knowledgeQueryTemplate).toContain("Investigating code");
       expect(knowledgeQueryTemplate).toContain("## Search");
       expect(knowledgeQueryTemplate).toContain("heading");
       expect(knowledgeQueryTemplate).toContain("Treat every hit as a lead");

packages/context/templates/package-templates.zh-CN/kb/skills/context-knowledge-query/SKILL.md

@@ -1,16 +1,26 @@
 ---
 name: {{skillName}}
-description: 查询本项目可用的 Context 知识包中经过审核、可追溯来源的知识。用于跨一个或多个已安装知识包查找实体、API、行为、流程、约束、决策、排障信息、关系和覆盖范围。
+description: 根据本项目可用的 Context 知识包回答问题，并沿证据链回到记录版本的原始文档和代码。用于跨一个或多个已安装知识包查找实体、API、行为、流程、约束、决策、排障信息、关系、影响范围和覆盖范围。
 metadata:
   shared: "true"
   version: "{{contextVersion}}"
 ---
 
 # Context 知识查询
 
-只根据 Context 构建的已批准知识包回答。每个 Context 知识包都带同一份本 Skill，
-所以一份就能服务项目里安装的全部知识包：先确定相关的包，再沿索引缩小范围；正文是
-事实证据，记忆和 frontmatter 摘要不是。
+根据 Context 构建的已批准知识包回答，并按问题需要沿证据链深入：知识包页面、页面链接的
+其他页面、每页记录的出处，以及这些出处在记录版本上的代码或文档。每个 Context 知识包都带
+同一份本 Skill，所以一份就能服务项目里安装的全部知识包。
+
+## 边界
+
+- 只做查询。不要修改知识包文件、项目文件、Skills、Rules、包锁文件或用户级配置；不要因为
+  知识包列出了某个 Skill 或插件就安装或启用它。
+- 临时材料放在当前项目的 `.tmp/context-knowledge-query/` 下，与用户自己的检出分开，
+  不再需要时删除。
+- 知识包页面是已批准知识。页面标题、检索片段或记录的出处只用于定位证据，不代表原文已经读过。
+- 用户或宿主明确要求只用本地、离线或只用远程读取原文时照做；这改变的是读取原文的方式，
+  不改变什么算证据。
 
 ## 找到知识包
 
@@ -28,20 +38,31 @@ node <本 Skill 目录>/scripts/search.mjs --list
 4. 环境变量 `CONTEXT_KNOWLEDGE_PACKAGES` 列出的目录（用平台路径分隔符分隔）。
 5. 当前发行版支持的宿主包管理器所记录的知识包。
 
-每一项显示包名、版本、目录以及是否有检索说明。用户点名了某个包或团队时只查它；
-否则先读各包的 `index.md` 和检索说明，选出范围与问题相符的包，其余不打开。
+每一项显示包名、版本、目录以及是否有检索说明。用户点名了某个包或团队时只查它；否则先读
+各包的 `index.md` 和 `others/context/search-guide.md`，选出范围与问题相符的包，其余不打开。
+本次任务中复用这份列表，不要反复列出。
+
+## 沿证据链查询
 
-## 查询步骤
+按顺序走以下环节。每走完一环，判断剩下的未知是否可能改变结论、结论的条件或适用范围：
+不会就直接回答，会就进入下一环。
 
-1. 判断请求属于实体查找、解释、流程、规则、关系、细节还是覆盖检查。
-2. 选中的包有 `others/context/search-guide.md` 时先读它：其中列出该包的术语、
-   同义词、常见问题和首选入口页。
-3. 从最相关的根索引开始，例如 `{{wikisRoot}}/index.md`，再沿链接进入具体页面。
-4. 只读取回答所需的章节；frontmatter 用来选择范围，不作为事实依据。
-5. 查询关系或影响范围时，读取明确说明；同名、目录位置或链接本身不能证明关系。
-6. 结论来自可见章节正文，引用对应的包、页面和章节。多个包都有贡献时分别引用，
-   不要合成任何一页都没有写明的结论。
-7. 如果知识包里没有证据，明确报告缺口和已经检查的范围，不要根据邻近内容推断。
+1. **确定范围。** 判断请求属于实体查找、解释、流程、规则、关系、影响范围、细节还是覆盖检查，
+   记下答案依赖的术语、符号和条件。
+2. **导航。** 从对应的根索引开始（`{{wikisRoot}}/`、`{{guidesRoot}}/`、`{{rulesRoot}}/`、
+   `{{featsRoot}}/`），结合分组和检索说明里的首选入口选页面，在上下文中读取相关章节。
+   frontmatter 只用于选择范围。
+3. **在知识包内扩展。** 章节把机制、条件或例外交给另一页说明时，沿链接过去；还有可能相关的
+   候选页面时，先把它们的相关章节一起读完，再决定是否继续深入。导航找不到时再检索（见下文）。
+4. **追溯出处。** 对仍不确定的结论，读取支撑它的页面 `Sources` 条目并直接打开原文；
+   不要先问用户是否继续深入。某个出处读不到，只影响依赖它的结论。
+5. **调查代码。** 答案取决于代码行为时，从记录提交上的被引用文件和行开始，只按问题需要
+   沿 import、调用和服务路由扩展。
+6. **停止。** 剩下的缺口不会改变答案，或现有权限无法补上时就回答；关键缺口无法补上时给出
+   有条件的结论。
+
+不要穷举所有候选，也不要固定检索或阅读次数。知识包正文已经回答了问题时，不要再拉代码或核对
+每个相关出处。没有核实的补充说法宁可不写，也不要为了支撑它扩大调查。
 
 | 根目录 | 用途 |
 |---|---|
@@ -50,19 +71,18 @@ node <本 Skill 目录>/scripts/search.mjs --list
 | `{{rulesRoot}}/` | 标准、约束、验收条件和测试场景。 |
 | `{{featsRoot}}/` | 被选择进入包内的功能知识。 |
 
-缺少某个根目录表示该知识包没有选择这一类别。
-
-若存在 `{{wikisRoot}}/imports.md`，它只列出外部入口，不代表内容已随包分发或已安装；
-`{{wikisRoot}}/repo-content.md` 是生成的仓库入口页，不是批准知识文章。仅在相关且
-有权访问时沿链接读取；不能因列出了 Skill 或插件就安装或执行。
+缺少某个根目录表示该知识包没有选择这一类别。`{{wikisRoot}}/imports.md` 只列出外部入口，
+不是随包证据；`{{wikisRoot}}/repo-content.md` 是生成的仓库入口页，不是批准知识文章；
+二者都只在相关时才沿链接读取。
 
 ## 检索
 
 索引和页面结构无法确定范围，或候选页面太大时才检索。
 
-- 使用检索说明里的业务词、代码符号和同义词；多跑几条互补的查询，而不是一条很长的。
-- 没有结果时换成等价词或上位词；结果太多时按包、根目录或更具体的符号收窄。
-  一次没搜到不能证明不存在。
+- 使用检索说明和已读页面中的业务词、代码符号和同义词；多跑几条互补的查询，而不是一条很长的。
+- 依据命中的有限片段选页面，不要只看文件名。
+- 没有结果时先检查查询本身的含义，放宽组合条件，或换等价词、上位词；结果太嘈杂时按包、
+  根目录、路径或更有区分度的词收窄后再读。一次没搜到不能证明不存在。
 - 精确名称、API、配置键、路径或错误信息用 `rg`。
 - 多个词、中文短语或跨多个包时运行随附的 BM25 排序脚本：
 
@@ -71,40 +91,79 @@ node <本 Skill 目录>/scripts/search.mjs --query '<检索词>' --limit 8
 node <本 Skill 目录>/scripts/search.mjs --query '<检索词>' --package <包名>
 ```
 
-不带 `--package` 时在所有找到的包中统一排序。脚本按标题和有限行区间机械切块，返回
-包、路径、行区间、标题和预览，不理解语义。每个命中都只是线索，回答前要打开对应页面和章节。
+不带 `--package` 时在所有找到的包中统一排序，返回包、路径、行区间、标题和预览。每个命中
+都只是线索，使用前要打开对应页面和章节。
 
-## 回到原始来源
+## 读取出处
 
-每篇发布的页面末尾都有从工作区出处导出的 `Sources` 一节。只有包内正文不足以回答，
-或答案依赖代码当前行为时，才去读原文：
+每篇发布的页面末尾都有从工作区出处导出的 `Sources` 一节，其中条目就是对应结论的出处基线。
 
 | 出处 | 怎么读 |
 |---|---|
-| 带提交和行区间的代码仓库链接 | 用宿主已授权的方式在该提交读取：已配置的只读代码检索服务，或稀疏浅克隆到 `.tmp/context-knowledge-query/<host>/<repository>/<commit>/`。不要把更新后的分支头当作被引用的版本。 |
+| 带提交和行区间的代码仓库链接 | 在该提交读取该文件，见下文“记录提交上的代码”。 |
 | 文档链接 | 打开的是当前文档；行区间对应写作时采集的副本。现文不同时如实说明。 |
 | 没有链接的条目 | 原文无法从包里访问，只依据包内正文并说明这一点。 |
 
-原文与包内正文分开引用。原文读不到时保留包内结论，说明哪些没能核对，然后继续。
-不要修改项目文件；用完删除临时克隆。
+无法确定出处的身份或版本时，保留基于知识包的结论并说明出处受限；不要猜测仓库，也不要把
+当前内容当成记录的基线。本次任务已读过的原文直接复用，不要重复读取。
+
+### 记录提交上的代码
+
+- 有已配置且已授权的只读代码检索或阅读服务时优先使用：在记录的提交上读取记录的文件和行，
+  再在该提交内检索需要的符号。
+- 否则在本地取回该提交，放在
+  `.tmp/context-knowledge-query/<host>/<仓库路径>/<commit>/`，路径各段安全、不含凭据，
+  并使用完整提交号：
+  - 支持时使用浅历史（`--depth=1`）和延迟内容（`--filter=blob:none`），在检出前配置
+    稀疏检出，检出后核对实际提交；
+  - 稀疏范围从被引用路径开始；不确定模块位置时，用 `git ls-tree -r --name-only <commit>`
+    列出候选，再读代码确认；import 指向别处时再追加路径；
+  - 复用目录前先核对身份，不覆盖不匹配的目录，同一检出同一时间只由一个进程写入；
+  - 不要重置或改动用户自己的检出；记录的提交拿不到时，不要用默认分支代替。
+- 给取回留足时间，已就绪的模块先读；无法克隆时退回到按提交读取单个文件。
+
+### 调查代码
+
+- 从记录的位置开始，先复用那里出现的路径、符号、import 和调用，再考虑猜测名称或扩大检索。
+- 遇到同名定义时，沿被检提交上实际的 import 或解析路径确认；名字相似的文件或测试 mock
+  不能互相替代。
+- 位置明确后把相关读取合并进行，并带上足以支撑结论的上下文；未解决的依赖只追到问题需要的
+  程度，不必遍历整张调用图。
+- 区分实现、声明的契约、测试断言、运行时观察和推断。符号常量的具体值，要读它在该提交上
+  导入的定义后才能确定。
+
+### 版本
 
-## 证据约定
+记录的提交是知识的出处基线，不是当前分支头，也不能证明线上部署的状态。基线已经能回答问题时，
+不做版本比较。只有问题涉及当前行为、证据冲突或怀疑有变化时，才用实际 diff 做有限的比较；
+缺少比较只有在影响答案时才需要提到。
+
+### 文档与笔记
+
+读取保存的正文和结论依赖的附件。摘要不是完整记录，没读过的链接不是证据，当前的远端内容也
+不能证明历史快照。
+
+## 回答
+
+- 直接回答问题，把会改变结论的条件放在结论旁边。复杂问题要讲清产生结果的机制，而不只是结论。
+- 关键证据紧挨它支撑的结论；补充事实与证明分开。说明局部规则的适用范围，不要推广到整个系统。
+- 篇幅与问题相称：简单问题简短回答，长回答用简短小标题。证据齐备后不要重复结论，也不要再
+  额外做一轮规划或总结。
+- 多个包都有贡献时分别引用，不要合成任何一页都没有写明的结论。关系和影响范围要引用确立它的
+  说明；同名、目录位置或链接本身不能证明关系。
+- 知识包之间说法不一致，或知识包与其出处冲突时，说明各自怎么说、各自对应哪个版本。
+
+证据与引用：
 
 | 证据 | 用途 |
 |---|---|
 | 包与页面路径 | 身份与引用句柄。 |
 | frontmatter 标题、描述和标签 | 仅用于导航和选择范围。 |
 | Markdown 标题 | 定位并引用页面内的章节。 |
 | 可见章节正文 | 事实结论的主要依据。 |
-| `Sources` 条目及据此读到的原文 | 包外的补充依据，单独引用。 |
+| 通过 `Sources` 读到的原文 | 包外的补充依据，单独引用。 |
 | 根索引与 `context-build-inventory.json` | 包的范围与覆盖情况。 |
 
-不要根据页面共现推断关系。发布页面不需要生产标识或出处记账即可使用；引用可读路径和
-标题即可。只有覆盖问题或维护者需要 `dist_path` → `approved_path` 时才打开
-`context-build-inventory.json`。
-
-## 引用与缺口
-
 ```text
 页面：  <结论> [<包>: <root>/path/page.md]
 章节：  <结论> [<包>: <root>/path/page.md, 标题: <可见标题>]
@@ -113,25 +172,33 @@ node <本 Skill 目录>/scripts/search.mjs --query '<检索词>' --package <包
 覆盖：  <结论> [<包>: context-build-inventory.json]
 ```
 
+链接实际读过的材料：被检提交上的源码文件、知识网站页面和原始文档。没有可靠链接时，给出本地
+路径、符号和简短摘录，并说明限制。不要根据页面共现推断关系，也不要用记忆、以往对话或未读过的
+文件填补缺口。
+
 缺少证据时返回：
 
 ```text
 缺口：可用知识包中没有 <缺失点> 的证据。
-已检查：<包、索引、页面或原文>。
+已检查：<读过的包、页面、出处或代码>。
 下一步可查：<已知的来源文档或页面>。
 ```
 
-区分“这些知识包没有证据”和“这件事不成立”。不要用记忆、以往对话或未读过的文件填补缺口。
+区分“这些知识包没有证据”和“这件事不成立”，缺口只针对已检查的范围。
+
+## 网站链接
 
-## 最终总结中的网站链接
+回答后可以附上相关的知识网站链接。从包目录读取 `context-site-map.json`，或读取
+`others/context/context-site-map.json`。把读过的页面与 `pages[].package_path` 或
+`approved_path` 匹配，使用其 `title`，并把 `site_path` 相对于 `site_url` 解析；`site_url`
+已包含部署基础路径。只引用匹配的页面，去重，不要编造锚点。这是本地格式化，不是检索：不要
+探测 URL 或检查远端版本；映射缺失或格式错误时保留本地引用。
 
-根据实际读过的页面回答后，可以附上相关文档链接。从包目录读取 `context-site-map.json`，
-或读取 `others/context/context-site-map.json`。把读过的页面与 `pages[].package_path` 或
-`approved_path` 匹配，使用其 `title`，并把 `site_path` 相对于 `site_url` 解析；
-`site_url` 已包含部署基础路径。只引用匹配的文章，去重，不要编造章节锚点。
+## 知识更新
 
-这是本地格式化步骤，不是检索或验证。不要为了加链接去探测 URL、打开浏览器或检查远端
-版本。映射、URL 或匹配页面缺失或格式错误时，保留本地引用并继续。
+回答过程中发现页面过期、有误或缺少内容时，告诉用户是哪一页、证据显示了什么、由哪些出处支撑，
+以便知识包维护者更新对应的知识工作区。不要修改已安装的知识包。维护者需要页面的
+`dist_path` → `approved_path` 对应关系时，再打开 `context-build-inventory.json`。
 
 {{!-- 模板作者说明（不属于发布的 Skill）：