feat(package): 随包分发共享的 context-knowledge-query Skill（0.7.84）

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to Context are documented here.
 
+## 0.7.84 - 2026-10-24
+
+- The default package query Skill is now `context-knowledge-query`, replacing `knowledge-query`. It is identical in every Context package and declares `metadata.shared` and its Context version, so a package manager can install one copy that searches every Context package available to a project. Its search script lists the packages it found (`--list`), ranks across them or within one (`--package`), and also reads directories named in `CONTEXT_KNOWLEDGE_PACKAGES`. When a page's text does not settle a question, the Skill follows the page's repository sources at their recorded commit through authorized host tools.
+- Package-specific search hints move to a new `others/context/search-guide.md` template file, so tuning one package no longer changes the shared Skill.
+- `context build` replaces a workspace template's `knowledge-query` Skill with `context-knowledge-query`, adds the search guide when it is missing, and reports the replacement as an agent hint.
+
 ## 0.7.83 - 2026-10-23
 
 - Upgrading the CLI now re-renders an existing website on the next build, even when its knowledge and settings are unchanged. Page and navigation rendering live in the CLI, so the site renderer version now includes the CLI version; previously only theme changes invalidated a built site, and an upgrade such as 0.7.82's sidebar order did not appear until the site output was deleted. Fresh clones were not affected.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "context",
-  "version": "0.7.83",
+  "version": "0.7.84",
   "packageManager": "bun@1.3.9",
   "repository": {
     "type": "git",

packages/context-cli/CLAUDE.md

@@ -258,7 +258,7 @@ block 标题用 `**Label**:` 或 `**Label** (meta):`，统一英文（中文标
 - Prompt/cache-stable 输出：必要且不变的指令与 schema 放前段，当前任务的材料和问题放后段；不重复携带已退场的主体矩阵或事实账本。CLI JSON 字段顺序稳定，不为刷新输出制造时间戳或随机 ID；授权材料位置与命令所需路径按现有 Route 交付。
 - Knowledge 本身就是 lookup registry。不新增动态 registry 文件；Agent 通过
   当前 status、任务材料、approved `knowledge/structure.yaml`、OKF
-  indexes、build inventory 和生成包里的 `knowledge-query` skill 获取
+  indexes、build inventory 和生成包里的 `context-knowledge-query` skill 获取
   相关知识文章及其来源区域。lookup 输出可带知识分类和排序,
   不带存储路径或临时时间戳。
 

packages/context-cli/context-workflow/provider.yaml

@@ -1,6 +1,6 @@
 schema: agent-graph.provider.v1
 id: c4a/context
-version: 0.7.83
+version: 0.7.84
 name: Context workflow
 description: Internal work contract for Context knowledge workspaces.
 graphs:

packages/context-cli/context-workflow/resources/dialogue/package-output.md

@@ -8,7 +8,7 @@ mediaType: text/markdown
 
 Explain output shapes before SDK factory names. Offer:
 
-- an Agent knowledge-base package with `AGENTS.md`, a knowledge-query Skill,
+- an Agent knowledge-base package with `AGENTS.md`, the shared context-knowledge-query Skill,
   approved OKF roots, and adaptive indexes;
 - a searchable documentation website with the approved knowledge map, source cards and local-time update timestamps;
 - one LLM text bundle for model context or RAG import.

packages/context-cli/context-workflow/resources/manuals/guides/package-outputs.md

@@ -207,8 +207,9 @@ Typical output:
 dist/<package-name>/
 ├── AGENTS.md
 ├── skills/
-│   └── knowledge-query/
+│   └── context-knowledge-query/
 │       └── SKILL.md
+├── others/context/search-guide.md
 └── wikis/
     ├── index.md
     └── ...
@@ -238,7 +239,7 @@ The package name already identifies the surrounding build folder, so the
 output does not repeat it inside each root:
 
 ```text
-skills/knowledge-query/SKILL.md
+skills/context-knowledge-query/SKILL.md
 wikis/index.md
 guides/...
 rules/...
@@ -255,8 +256,14 @@ final template directory name directly—for
 example `skills/android-query/SKILL.md`. Package-root layout never renames a
 Skill.
 
-The default `knowledge-query` Skill is a complete generic query entry. It
-carries the structure-first query discipline: start from OKF directory indexes, use
+The default `context-knowledge-query` Skill is a complete generic query entry,
+identical in every Context package. It declares `metadata.shared: "true"` and
+its Context version, so a package manager that supports shared Skills can
+install one copy for all Context packages in a project, and that copy searches
+every package it can find: the surrounding package, `--root`, packages under
+`--base`, directories in `CONTEXT_KNOWLEDGE_PACKAGES`, and packages recorded by
+the host's package manager when the distribution supports one. It carries the
+structure-first query discipline: start from OKF directory indexes, use
 `context-build-inventory.json` edge records for package-visible relationships,
 read candidate pages, cite their visible headings and relevant passages, and
 report gaps when the package does not cover a requested fact. Consumer pages
@@ -269,10 +276,21 @@ scope, or a candidate page is too large to read directly, its bundled
 bounded Markdown chunks. Search results are leads; page bodies and typed edge
 records establish what the package actually says. Package authors edit the source
 template when project-specific terminology, entry points or task workflows are
-needed. Authoring instructions should be template comments or separate guidance,
-not a final section addressed to authors in the delivered query Skill. The
-current template-review Route can accept an intentionally sufficient generic
-default under its applicable authority.
+needed: put terms, synonyms, common questions and preferred entry pages in
+`others/context/search-guide.md`, which the Skill reads first, and keep the
+shared Skill unchanged. Editing the Skill makes it package-specific; rename its
+directory and `name` so it installs separately. When a page's text does not
+settle a question, the Skill follows the page's `Sources` entries: repository
+links are read at their recorded commit through authorized host tools, document
+links open the current document, and entries without links stay unreachable
+from the package. The current template-review Route can accept an intentionally
+sufficient generic default under its applicable authority.
+
+Workspaces created before the rename keep `skills/knowledge-query/` in their
+template. `context build` replaces it with `context-knowledge-query` in the old
+Skill's language, adds `others/context/search-guide.md` when it is missing, and
+reports the replacement as an agent hint. Move any package-specific wording the
+old Skill carried into the search guide.
 
 When approved pages reference materialized resources, Context keeps their
 production copies in content-addressed `knowledge/assets/` paths and bundles

packages/context-cli/context-workflow/resources/manuals/reference/package-templates.md

@@ -135,7 +135,7 @@ that name inside the package's knowledge roots.
 Templates keep a logical, consumer-neutral layout:
 
 ```text
-skills/knowledge-query/SKILL.md
+skills/context-knowledge-query/SKILL.md
 wikis/index.md
 guides/...
 rules/...
@@ -145,7 +145,7 @@ feats/...
 For `name: "component-lib-kb"`, `context build` writes:
 
 ```text
-skills/knowledge-query/SKILL.md
+skills/context-knowledge-query/SKILL.md
 wikis/index.md
 guides/...
 rules/...
@@ -219,8 +219,11 @@ src/package-templates/
 │   ├── AGENTS.md
 │   ├── wikis/
 │   │   └── index.md
+│   ├── others/
+│   │   └── context/
+│   │       └── search-guide.md
 │   └── skills/
-│       └── knowledge-query/
+│       └── context-knowledge-query/
 │           ├── SKILL.md
 │           └── scripts/
 │               └── search.mjs
@@ -237,16 +240,25 @@ rejects it.
 
 The default kb template includes:
 
-- `skills/knowledge-query/SKILL.md`, a reusable skill that teaches agents to
-  navigate copied knowledge pages, cite relevant text and its exported source
-  attribution, and report gaps instead of inventing unsupported answers. The
+- `skills/context-knowledge-query/SKILL.md`, a reusable skill shared by every
+  Context package (`metadata.shared: "true"`, `metadata.version` set to the
+  Context version). It finds the Context packages available to the project,
+  navigates copied knowledge pages, cites relevant text and its exported source
+  attribution, follows repository sources at their recorded commit when the page
+  text is not enough, and reports gaps instead of inventing unsupported answers.
+  It uses no package-specific template values, so every package renders the same
+  file. The
   default entry OKF root is `wikis/`; packages that select additional internal
   collections expose
   `guides/`, `rules/`, or `feats/` indexes when those roots are selected.
-- `skills/knowledge-query/scripts/search.mjs`, a dependency-free BM25 fallback
-  for exact terms, mixed keyword queries, and large Markdown indexes. It chunks
-  mechanically, returns inspectable paths and line ranges, and never replaces
-  reading the relevant source-backed explanation.
+- `skills/context-knowledge-query/scripts/search.mjs`, a dependency-free BM25
+  fallback for exact terms, mixed keyword queries, and large Markdown indexes.
+  `--list` shows the packages it found; without `--package` it ranks across all
+  of them. It chunks mechanically, returns package, path and line range, and
+  never replaces reading the relevant source-backed explanation.
+- `others/context/search-guide.md`, the package's own search hints: terms,
+  synonyms, common questions and preferred entry pages. Edit this file, not the
+  shared Skill, to tune search for one package.
 - `wikis/index.md`, the editable OKF bundle entry page for the generated
   `dist/<package-name>/wikis/` directory.
 

packages/context-cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@c4a/context-cli",
   "description": "Local runtime and Agent integration for traceable knowledge production",
-  "version": "0.7.83",
+  "version": "0.7.84",
   "type": "module",
   "license": "MIT",
   "engines": {

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

@@ -163,16 +163,17 @@ describe("plugin and workflow workspace guard", () => {
 
   test("SDK package templates preserve current OKF root mapping", async () => {
     const template = await readFile(
-      join(CONTEXT_PACKAGE_ROOT, "templates", "package-templates", "kb", "skills", "knowledge-query", "SKILL.md"),
+      join(CONTEXT_PACKAGE_ROOT, "templates", "package-templates", "kb", "skills", "context-knowledge-query", "SKILL.md"),
       "utf8",
     );
     expect(template).toContain("Query Procedure");
-    expect(template).toContain("Package Roots");
-    expect(template).toContain("Start from `{{guidesRoot}}/index.md`");
-    expect(template).toContain("Start from `{{rulesRoot}}/index.md`");
+    expect(template).toContain("Find The Packages");
+    expect(template).toContain("Going Back To The Sources");
+    expect(template).toContain("`{{guidesRoot}}/`");
+    expect(template).toContain("`{{rulesRoot}}/`");
     expect(template).toContain("context-build-inventory.json");
     expect(template).toContain("{{!-- Template author guidance");
-    expect(template).toContain("edit it before publishing");
+    expect(template).toContain("others/context/search-guide.md");
     expect(template).not.toContain("C4A");
 
     const agents = await readFile(
@@ -184,12 +185,12 @@ describe("plugin and workflow workspace guard", () => {
     expect(agents).toContain("`{{rulesRoot}}/` maps from `standards` and `test`");
 
     const localizedTemplate = await readFile(
-      join(CONTEXT_PACKAGE_ROOT, "templates", "package-templates.zh-CN", "kb", "skills", "knowledge-query", "SKILL.md"),
+      join(CONTEXT_PACKAGE_ROOT, "templates", "package-templates.zh-CN", "kb", "skills", "context-knowledge-query", "SKILL.md"),
       "utf8",
     );
-    expect(localizedTemplate).toContain("## 知识根目录");
-    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");
     for (const queryTemplate of [template, localizedTemplate]) {
       // Published pages intentionally omit production attribution. The default
@@ -199,11 +200,14 @@ describe("plugin and workflow workspace guard", () => {
       expect(queryTemplate).not.toContain("#section-id");
       expect(queryTemplate).toContain("dist_path");
       expect(queryTemplate).toContain("approved_path");
+      // The Skill is shared by every package, so it must render without package values.
+      expect(queryTemplate).not.toMatch(/\{\{\s*(?:displayName|packageName|knowledgeCount)\s*\}\}/u);
+      expect(queryTemplate).toContain('shared: "true"');
       const published = Handlebars.compile(queryTemplate)({
-        name: "sample-library", knowledgeCount: 2,
+        skillName: "context-knowledge-query", contextVersion: "1.0.0",
         wikisRoot: "wikis", guidesRoot: "guides", rulesRoot: "rules", featsRoot: "feats",
       });
-      expect(published).not.toMatch(/Template author guidance|模板作者建议|edit it before publishing|正式发布前/u);
+      expect(published).not.toMatch(/Template author guidance|模板作者说明/u);
       expect(published).toContain("context-build-inventory.json");
       expect(published).not.toContain("{{");
     }