From 711c0dbba8b0ae4fd2d006551c7928af739f725a Mon Sep 17 00:00:00 2001 From: qiansc Date: Sat, 24 Oct 2026 12:56:10 +0000 Subject: [PATCH] feat(package): give context-knowledge-query the evidence-chain query discipline Rewrite the shared package query Skill around an evidence chain: navigate package pages, widen to linked pages and candidates, trace each claim's recorded sources directly, investigate code at the recorded commit along imports and calls, and stop when remaining gaps cannot change the answer. Port the applicable inspect-search rules for package-only use: sparse commit-pinned retrieval, duplicate-definition and version handling, document evidence, conditional answers and knowledge-update reporting. Co-Authored-By: Claude Opus 5.5 --- .../__tests__/pluginWorkspaceGuard.test.ts | 7 +- .../src/__tests__/projectV060.test.ts | 8 +- .../skills/context-knowledge-query/SKILL.md | 165 ++++++++---- .../skills/context-knowledge-query/SKILL.md | 235 +++++++++++++----- 4 files changed, 291 insertions(+), 124 deletions(-) diff --git a/packages/context-cli/src/__tests__/pluginWorkspaceGuard.test.ts b/packages/context-cli/src/__tests__/pluginWorkspaceGuard.test.ts index ab457e34..9adcf52f 100644 --- a/packages/context-cli/src/__tests__/pluginWorkspaceGuard.test.ts +++ b/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"); diff --git a/packages/context-cli/src/__tests__/projectV060.test.ts b/packages/context-cli/src/__tests__/projectV060.test.ts index d9dd79ee..b0eb2a52 100644 --- a/packages/context-cli/src/__tests__/projectV060.test.ts +++ b/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"); diff --git a/packages/context/templates/package-templates.zh-CN/kb/skills/context-knowledge-query/SKILL.md b/packages/context/templates/package-templates.zh-CN/kb/skills/context-knowledge-query/SKILL.md index 1dd8495b..f9e175bc 100644 --- a/packages/context/templates/package-templates.zh-CN/kb/skills/context-knowledge-query/SKILL.md +++ b/packages/context/templates/package-templates.zh-CN/kb/skills/context-knowledge-query/SKILL.md @@ -1,6 +1,6 @@ --- name: {{skillName}} -description: 查询本项目可用的 Context 知识包中经过审核、可追溯来源的知识。用于跨一个或多个已安装知识包查找实体、API、行为、流程、约束、决策、排障信息、关系和覆盖范围。 +description: 根据本项目可用的 Context 知识包回答问题，并沿证据链回到记录版本的原始文档和代码。用于跨一个或多个已安装知识包查找实体、API、行为、流程、约束、决策、排障信息、关系、影响范围和覆盖范围。 metadata: shared: "true" version: "{{contextVersion}}" @@ -8,9 +8,19 @@ metadata: # 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,24 +91,69 @@ node <本 Skill 目录>/scripts/search.mjs --query '<检索词>' --limit 8 node <本 Skill 目录>/scripts/search.mjs --query '<检索词>' --package <包名> ``` -不带 `--package` 时在所有找到的包中统一排序。脚本按标题和有限行区间机械切块，返回 -包、路径、行区间、标题和预览，不理解语义。每个命中都只是线索，回答前要打开对应页面和章节。 +不带 `--package` 时在所有找到的包中统一排序，返回包、路径、行区间、标题和预览。每个命中 +都只是线索，使用前要打开对应页面和章节。 -## 回到原始来源 +## 读取出处 -每篇发布的页面末尾都有从工作区出处导出的 `Sources` 一节。只有包内正文不足以回答， -或答案依赖代码当前行为时，才去读原文： +每篇发布的页面末尾都有从工作区出处导出的 `Sources` 一节，其中条目就是对应结论的出处基线。 | 出处 | 怎么读 | |---|---| -| 带提交和行区间的代码仓库链接 | 用宿主已授权的方式在该提交读取：已配置的只读代码检索服务，或稀疏浅克隆到 `.tmp/context-knowledge-query////`。不要把更新后的分支头当作被引用的版本。 | +| 带提交和行区间的代码仓库链接 | 在该提交读取该文件，见下文“记录提交上的代码”。 | | 文档链接 | 打开的是当前文档；行区间对应写作时采集的副本。现文不同时如实说明。 | | 没有链接的条目 | 原文无法从包里访问，只依据包内正文并说明这一点。 | -原文与包内正文分开引用。原文读不到时保留包内结论，说明哪些没能核对，然后继续。 -不要修改项目文件；用完删除临时克隆。 +无法确定出处的身份或版本时，保留基于知识包的结论并说明出处受限；不要猜测仓库，也不要把 +当前内容当成记录的基线。本次任务已读过的原文直接复用，不要重复读取。 + +### 记录提交上的代码 + +- 有已配置且已授权的只读代码检索或阅读服务时优先使用：在记录的提交上读取记录的文件和行， + 再在该提交内检索需要的符号。 +- 否则在本地取回该提交，放在 + `.tmp/context-knowledge-query//<仓库路径>//`，路径各段安全、不含凭据， + 并使用完整提交号： + - 支持时使用浅历史（`--depth=1`）和延迟内容（`--filter=blob:none`），在检出前配置 + 稀疏检出，检出后核对实际提交； + - 稀疏范围从被引用路径开始；不确定模块位置时，用 `git ls-tree -r --name-only ` + 列出候选，再读代码确认；import 指向别处时再追加路径； + - 复用目录前先核对身份，不覆盖不匹配的目录，同一检出同一时间只由一个进程写入； + - 不要重置或改动用户自己的检出；记录的提交拿不到时，不要用默认分支代替。 +- 给取回留足时间，已就绪的模块先读；无法克隆时退回到按提交读取单个文件。 + +### 调查代码 + +- 从记录的位置开始，先复用那里出现的路径、符号、import 和调用，再考虑猜测名称或扩大检索。 +- 遇到同名定义时，沿被检提交上实际的 import 或解析路径确认；名字相似的文件或测试 mock + 不能互相替代。 +- 位置明确后把相关读取合并进行，并带上足以支撑结论的上下文；未解决的依赖只追到问题需要的 + 程度，不必遍历整张调用图。 +- 区分实现、声明的契约、测试断言、运行时观察和推断。符号常量的具体值，要读它在该提交上 + 导入的定义后才能确定。 + +### 版本 -## 证据约定 +记录的提交是知识的出处基线，不是当前分支头，也不能证明线上部署的状态。基线已经能回答问题时， +不做版本比较。只有问题涉及当前行为、证据冲突或怀疑有变化时，才用实际 diff 做有限的比较； +缺少比较只有在影响答案时才需要提到。 + +### 文档与笔记 + +读取保存的正文和结论依赖的附件。摘要不是完整记录，没读过的链接不是证据，当前的远端内容也 +不能证明历史快照。 + +## 回答 + +- 直接回答问题，把会改变结论的条件放在结论旁边。复杂问题要讲清产生结果的机制，而不只是结论。 +- 关键证据紧挨它支撑的结论；补充事实与证明分开。说明局部规则的适用范围，不要推广到整个系统。 +- 篇幅与问题相称：简单问题简短回答，长回答用简短小标题。证据齐备后不要重复结论，也不要再 + 额外做一轮规划或总结。 +- 多个包都有贡献时分别引用，不要合成任何一页都没有写明的结论。关系和影响范围要引用确立它的 + 说明；同名、目录位置或链接本身不能证明关系。 +- 知识包之间说法不一致，或知识包与其出处冲突时，说明各自怎么说、各自对应哪个版本。 + +证据与引用： | 证据 | 用途 | |---|---| @@ -96,15 +161,9 @@ node <本 Skill 目录>/scripts/search.mjs --query '<检索词>' --package <包 | frontmatter 标题、描述和标签 | 仅用于导航和选择范围。 | | Markdown 标题 | 定位并引用页面内的章节。 | | 可见章节正文 | 事实结论的主要依据。 | -| `Sources` 条目及据此读到的原文 | 包外的补充依据，单独引用。 | +| 通过 `Sources` 读到的原文 | 包外的补充依据，单独引用。 | | 根索引与 `context-build-inventory.json` | 包的范围与覆盖情况。 | -不要根据页面共现推断关系。发布页面不需要生产标识或出处记账即可使用；引用可读路径和 -标题即可。只有覆盖问题或维护者需要 `dist_path` → `approved_path` 时才打开 -`context-build-inventory.json`。 - -## 引用与缺口 - ```text 页面： <结论> [<包>: /path/page.md] 章节： <结论> [<包>: /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）： diff --git a/packages/context/templates/package-templates/kb/skills/context-knowledge-query/SKILL.md b/packages/context/templates/package-templates/kb/skills/context-knowledge-query/SKILL.md index 3afa541e..c5027997 100644 --- a/packages/context/templates/package-templates/kb/skills/context-knowledge-query/SKILL.md +++ b/packages/context/templates/package-templates/kb/skills/context-knowledge-query/SKILL.md @@ -1,6 +1,6 @@ --- name: {{skillName}} -description: Query approved, source-linked knowledge from the Context knowledge packages available to this project. Use for questions about entities, APIs, behavior, procedures, constraints, decisions, troubleshooting, relationships, and package coverage, across one or several installed packages. +description: Answer questions from the Context knowledge packages available to this project and follow their evidence chain to original documents and code at the recorded versions. Use for entities, APIs, behavior, procedures, constraints, decisions, troubleshooting, relationships, impact and package coverage, across one or several installed packages. metadata: shared: "true" version: "{{contextVersion}}" @@ -8,10 +8,24 @@ metadata: # Context Knowledge Query -Answer from approved knowledge packages built by Context. Every Context package -ships this same Skill, so one copy serves all packages installed in a project: -find the relevant packages first, navigate their indexes, and treat the visible -section body as evidence rather than memory or frontmatter summaries. +Answer from approved knowledge packages built by Context, and follow their +evidence chain as far as the question needs: package pages, the pages they link, +the sources each page records, and the code or documents behind those sources at +the recorded version. Every Context package ships this same Skill, so one copy +serves all packages installed in a project. + +## Boundaries + +- Query only. Do not edit package files, project files, Skills, Rules, package + locks or user-level configuration. Do not install or enable a Skill or plugin + because a package lists it. +- Keep temporary material under `.tmp/context-knowledge-query/` in the current + project, separate from user checkouts, and remove it when no longer needed. +- Package pages are approved knowledge. A page title, search snippet or + recorded source entry locates evidence; it does not prove the original was read. +- Follow an explicit local-only, offline or remote-only instruction from the + user or host for reading originals. It changes how originals are read, not + what counts as evidence. ## Find The Packages @@ -33,27 +47,42 @@ The script finds packages in this order and merges the results: Each entry shows the package name, version, directory and whether it has a search guide. If the user named a package or team, use only that package. -Otherwise read each package's `index.md` and search guide, choose the packages -whose scope matches the question, and leave the rest unopened. - -## Query Procedure - -1. Classify the request as entity lookup, explanation, procedure, rule, - relationship, detail, or coverage audit. -2. Read the chosen package's `others/context/search-guide.md` when present: it - lists the package's terms, synonyms, common questions and preferred entry - pages. -3. Open the most relevant root index, such as `{{wikisRoot}}/index.md`, then - follow its links to a likely page. -4. Read only the sections needed. Use frontmatter to select scope, not to - support factual claims. -5. For relationship or impact questions, read the explicit explanations. Shared - names, directory placement and links alone do not prove a relationship. -6. Answer from reader-visible section content and cite the supporting package, - page and section. When several packages contribute, cite each separately and - do not merge them into a claim neither page states. -7. If the packages lack evidence, report the gap and what was checked instead - of inferring from nearby content. +Otherwise read each package's `index.md` and `others/context/search-guide.md`, +choose the packages whose scope matches the question, and leave the rest +unopened. Reuse the list for the rest of the task instead of listing again. + +## Follow The Evidence Chain + +Work through these links in order. After each one, decide whether what remains +unknown could change the conclusion, its conditions or its scope. If not, +answer. If so, take the next link. + +1. **Scope.** Classify the request as entity lookup, explanation, procedure, + rule, relationship, impact, detail, or coverage audit. Note the terms, + symbols and conditions the answer depends on. +2. **Navigate.** Start from the matching root index (`{{wikisRoot}}/`, + `{{guidesRoot}}/`, `{{rulesRoot}}/`, `{{featsRoot}}/`), choose pages from + their grouping and the search guide's entry pages, and read the relevant + sections in context. Use frontmatter only to choose scope. +3. **Widen within the packages.** When a section defers to another page for a + mechanism, condition or exception, follow that link. When likely candidates + remain, read their relevant sections together before deciding to go further. + Search (below) when navigation does not find them. +4. **Trace the sources.** For the claims that remain uncertain, read the page's + `Sources` entries that support them and open those originals directly; do + not ask the user whether to go deeper. One unreadable source blocks only the + claims that depend on it. +5. **Investigate code.** When the answer depends on how code behaves, start + from the cited file and lines at the recorded commit and expand along + imports, calls and service routes only as far as the question requires. +6. **Stop.** When the remaining gaps cannot change the answer, or cannot be + closed with the available access, answer. State a conditional conclusion + when a decisive gap stays open. + +Do not exhaust every candidate or impose a fixed number of searches or reads. +If the package text already answers the question, do not fetch code or check +every related source. Omit supplementary claims that were not verified rather +than widening the investigation to support them. | Root | Use | |---|---| @@ -63,23 +92,22 @@ whose scope matches the question, and leave the rest unopened. | `{{featsRoot}}/` | Feature knowledge when selected into the package. | A missing root means that category was not selected into that package. - -If present, `{{wikisRoot}}/imports.md` lists declared external entrances, not -bundled evidence or installed capabilities, and `{{wikisRoot}}/repo-content.md` -is a generated repository entrance, not an approved article. Follow either only -when relevant and authorized; never install or execute a Skill or plugin merely -because it is listed. +`{{wikisRoot}}/imports.md` lists declared external entrances, not bundled +evidence, and `{{wikisRoot}}/repo-content.md` is a generated repository +entrance, not an approved article; follow either only when relevant. ## Search Search when indexes and page structure do not identify a useful scope, or when a candidate page is too large to read in full. -- Use business terms, code symbols and synonyms from the search guide. Run a few - complementary queries rather than one long one. -- With no results, broaden to equivalent or parent terms; with too many, narrow - by package, root or a more specific symbol. A miss alone does not prove that - something is absent. +- Use business terms, code symbols and synonyms from the search guide and from + pages already read. Run a few complementary queries rather than one long one. +- Read bounded match excerpts to choose pages, not file names alone. +- With no results, check the query's meaning, relax combined conditions or try + equivalent and parent terms. With noisy results, narrow by package, root, + path or a more distinctive term before reading more. A miss does not prove + that something is absent. - Use `rg` for an exact name, API, configuration key, path or error string. - For several terms, Chinese phrases or several packages, run the bundled BM25 ranker: @@ -89,28 +117,93 @@ node /scripts/search.mjs --query '' --limit 8 node /scripts/search.mjs --query '' --package ``` -Without `--package` it ranks across all found packages. It chunks Markdown by -headings and bounded line ranges and returns package, path, line range, heading -and preview; it does not interpret meaning. Treat every hit as a lead and open -its page and section before answering. +Without `--package` it ranks across all found packages and returns package, +path, line range, heading and preview. Treat every hit as a lead and open its +page and section before using it. -## Going Back To The Sources +## Read The Sources Each published page ends with a `Sources` section exported from the workspace's -references. Read originals only when the package text does not settle the -question, or when the answer depends on the current behavior of code: +references. Use its entries as the source baseline for the claims they support. | Source entry | How to read it | |---|---| -| Repository link with a commit and line range | Read that file at that commit with authorized host tools: a configured read-only code search service, or a sparse shallow clone under `.tmp/context-knowledge-query////`. Never read a newer branch head as if it were the cited version. | +| Repository link with a commit and line range | Read that file at that commit; see Code below. | | Document link | It opens the current document; the line range refers to the copy captured when the page was written. Say so when the current text differs. | | Entry without a link | The original is not reachable from the package. Stay within the package text and say so. | -Cite originals separately from package content. If an original cannot be read, -keep the package's conclusion, state what could not be checked, and continue. -Do not modify project files; remove temporary clones when done. - -## Evidence Contract +If a source's identity or version cannot be established, keep the +package-grounded finding and qualify its attribution; do not guess a repository +or treat current content as the recorded baseline. Reuse originals already read +in this task instead of reading them again. + +### Code at a recorded commit + +- Prefer a configured, authorized read-only code search or reading service when + one is available: read the recorded file and range at the recorded commit, + then search within that commit for the symbols you need. +- Otherwise retrieve the commit locally under + `.tmp/context-knowledge-query////`, using safe, + credential-free path components and the full commit: + - use shallow history (`--depth=1`) and deferred contents + (`--filter=blob:none`) where supported, with sparse checkout configured + before checkout, then verify the checked-out commit; + - start the sparse scope from the cited paths; when the module is unclear, + list candidates with `git ls-tree -r --name-only ` and confirm them + by reading code; add paths as imports lead elsewhere; + - verify identity before reusing a directory, never overwrite a mismatched + one, and let one process write to a checkout at a time; + - do not reset or reconfigure the user's own checkouts, and never substitute + the default branch for an unavailable recorded commit. +- Allow retrieval enough time, read modules that are ready while others load, + and fall back to commit-specific file reads when a clone is not possible. + +### Investigating code + +- Start from the recorded location and reuse the paths, symbols, imports and + calls found there before guessing names or broadening the search. +- For duplicate definitions, follow the actual import or resolution path at the + inspected commit; a similarly named file or a test mock is not the same thing. +- Batch related reads once locations are known, with enough surrounding context + to support the claim. Follow unresolved dependencies only as far as the + question needs, not the whole call graph. +- Distinguish implementation, declared contracts, test assertions, runtime + observations and inferences. Do not turn a symbolic constant into a value + without reading its imported definition at that commit. + +### Versions + +A recorded commit is the knowledge's source baseline, not the current branch +head and not proof of what is deployed. When the baseline settles the question, +answer without comparing versions. Compare narrowly, with actual diffs, only when +the question asks about current behavior, the evidence conflicts, or a change is +suspected; mention a missing comparison only when it limits the answer. + +### Documents and notes + +Read saved bodies and the attachments the claim depends on. A summary is not a +full transcript, an unread link is not evidence, and current remote content does +not prove a historical snapshot. + +## Answer + +- Answer the question directly and keep conditions that change the conclusion + beside it. For complex questions, explain the mechanism that produces the + result, not just the verdict. +- Keep decisive evidence next to the claim it supports; separate supplementary + facts from the proof. State where a local rule applies instead of + generalizing it to the whole system. +- Fit the depth to the question: short answers for simple questions, short + headings for longer ones. Do not repeat the conclusion or add a separate + planning or summary round once the evidence is in. +- When several packages contribute, cite each separately and do not merge them + into a claim neither page states. For relationships and impact, cite the + explanation that establishes them; shared names, directory placement and + links alone do not. +- When packages disagree, or a package conflicts with its source, say which + says what and which version each reflects. + +Evidence and citations: | Evidence | Valid use | |---|---| @@ -118,16 +211,9 @@ Do not modify project files; remove temporary clones when done. | Frontmatter title, description, and tags | Navigation and scope selection only. | | Markdown headings | Locate and cite a section within its page. | | Reader-visible section body | Primary support for factual claims. | -| `Sources` entries and originals read through them | Support beyond the package, cited separately. | +| Originals read through `Sources` | Support beyond the package, cited separately. | | Root indexes and `context-build-inventory.json` | Package scope and coverage evidence. | -Do not infer a relationship from page co-occurrence. Published pages do not need -production identifiers or source bookkeeping to be usable; cite their readable -paths and headings. Open `context-build-inventory.json` only for coverage -questions or when a maintainer needs `dist_path` → `approved_path`. - -## Citations And Gaps - ```text Page: [: /path/page.md] Section: [: /path/page.md, heading: ] @@ -136,30 +222,41 @@ Original: [@: L-L] Coverage: [: context-build-inventory.json] ``` +Link material actually read: source files at the inspected commit, knowledge +website pages and original documents. When no reliable link exists, give the +local path, symbol and a short excerpt with the limitation. +Do not infer a relationship from page co-occurrence, and do not fill gaps from +memory, previous conversations or unread files. + When evidence is missing, return: ```text Gap: the available packages do not contain evidence for . -Checked: . +Checked: . Next useful source: . ``` -Distinguish "not evidenced by these packages" from "not true." Do not fill gaps -from memory, previous conversations, or unread files. +Distinguish "not evidenced by these packages" from "not true", and scope a gap to +what was inspected. -## Website Links In The Final Summary +## Website Links -After answering from the pages actually read, optionally append related document -links. Read `context-site-map.json` from the package directory, or +After answering, optionally append related knowledge website links. Read +`context-site-map.json` from the package directory, or `others/context/context-site-map.json`. Match the read page to `pages[].package_path` or `approved_path`; use its `title` and resolve `site_path` relative to `site_url`, which already includes the deployment base -path. Only cite matched articles, deduplicate links, and do not invent section -anchors. +path. Cite only matched pages, deduplicate links, and do not invent anchors. +This is local formatting, not retrieval: do not probe URLs or check remote +versions, and keep local citations when the map is absent or malformed. + +## Knowledge Updates -This is a local formatting step, not retrieval or validation. Do not probe URLs, -open a browser, or check remote versions to add links. If the map, URL or -matching page is absent or malformed, keep the local citation and continue. +When an answer shows that a page is stale, wrong or missing something, tell the +user which page, what the evidence shows and which sources support it, so the +package's maintainers can update its knowledge workspace. Do not edit installed +packages. Open `context-build-inventory.json` when a maintainer needs the +page's `dist_path` → `approved_path` mapping. {{!-- Template author guidance (not part of the published Skill):