Knowledge Packages

A knowledge package is the Agent-facing output of a Context knowledge workspace: a folder under dist/ that turns approved knowledge into something another Agent can install and query. It carries the approved articles in reader-facing form, a query Skill that knows how to search them, and an inventory that maps every file back to its approved source. The same build can also produce a documentation website and LLM text; this page covers the package itself.

mermaid

flowchart LR
  approved["Approved, closed knowledge<br/>knowledge/"] --> build["context build"]
  tpl["Package template<br/>src/package-templates/kb"] --> build
  build --> kb["dist/name/<br/>knowledge package"]
  build --> site["dist/base-site/<br/>website (optional)"]
  kb --> agent["Agents query it with<br/>knowledge-query"]

What is inside

text

dist/<package-name>/
├── AGENTS.md
├── skills/
│   └── knowledge-query/
│       ├── SKILL.md
│       └── scripts/search.mjs
├── wikis/
│   ├── index.md          # package entry page
│   ├── codeindex/ ...
│   ├── business/ ...
│   └── product/ ...
├── guides/ ...           # architecture, sop, faq, decision, incident
├── rules/ ...            # standards, test
├── feats/ ...
├── others/assets/ ...    # bundled images and resources
└── context-build-inventory.json

The package name already names the folder, so roots inside are flat: wikis/, guides/, rules/, feats/. Each article lands under the root for its collection — sop pages under guides/sop/, codeindex pages under wikis/codeindex/ — as listed in Knowledge Collections. wikis/ is the structured entity-and-relationship layer; guides/ and rules/ explain, operationalize or constrain it.

Pages in the package are written for consumers: they keep their reader-facing frontmatter, drop lifecycle comments, section markers and fingerprints, and end with a readable Sources section generated from the article's references — repository links with file and line ranges, document links with their captured attribution. Exact section evidence stays in the mapped page of the knowledge workspace.

How Agents read it

The default knowledge-query Skill is a complete, generic query entry. It works structure first:

Start from the generated directory indexes in each root.
Use relationship records in context-build-inventory.json for package-visible connections.
Read the candidate pages and cite their visible headings and passages.
Report a gap when the package does not cover the fact asked for.

When the indexes do not narrow the scope, or a page is too large to read directly, its bundled scripts/search.mjs ranks bounded Markdown chunks with BM25. Search results are leads; page bodies and typed relationship records establish what the package says. A package-only reader must not claim to have read the original sources. See Using Packages in Agents for installing a package into an Agent.

Declaring a package

Packages are declared in the knowledge workspace's src/index.ts. The Agent edits this for you when you choose outputs in the work-start report; you never need to write it by hand.

kbPackage({
  name: "project-kb",
  template: "src/package-templates/kb",
  select: { exclude: ["**/internal/**"] },
  site: { title: "Project knowledge", lang: "en-US", base: "/" },
});

Field	Meaning
`name`	Lowercase, path-safe package name; output goes to `dist/<name>/`
`template`	Template directory, or `{ path, vars }`
`select`	Optional selection by `collections`, OKF `okfRoots`, or `include` / `exclude` paths under `knowledge/`; omitted means all approved knowledge
`navigation`	Directory-index policy; defaults to folding indexes with up to 50 inline entries
`assets`	Resource delivery: bundled by default, Git raw links or omission when explicitly configured
`site`	Also build a documentation website

Full details are in Package Templates.

Choosing outputs

Outputs can be combined. The work-start report shows them as one multi-select list and later steps reuse your choice:

[x] Agent knowledge package — the default for a new knowledge workspace.
[x] Documentation website — the default together with the package, for local preview or later hosting.
[ ] LLM text — optional input for model context or RAG; see LLM Docs.

You can also stop at approved Markdown: keep packages: [] and no build runs. There is no separate website Skill and no second permission per selected output.

Building and assets

context build consumes only approved and closed knowledge; if close is pending, the workflow runs it first. A newly initialized generic template must be edited or explicitly accepted before the first build — context status shows this as a package template review step.

Images and resources referenced by approved pages are bundled into others/assets/ by default. Each packaged image is kept at or below 1 MiB and all images together at or below 40 MiB; oversized images are compressed into new WebP files inside dist/ only, never touching sources/ or knowledge/assets/. Source audit files and capture reports are never shipped as reader assets.

What the build checks

Template boundary. Template prose that describes coverage, scope or known gaps must cite approved knowledge, the inventory or rendered structure data; otherwise the build reports a diagnostic.
Index links. Every generated directory index is checked so relative links resolve inside the package.
Path collisions. A rendered template path may not collide with a selected knowledge path; rename the template file or exclude the knowledge path with select.exclude.
Relationship coverage. The inventory's structure.relationship_coverage records whether code index pages carry current relationship data, so an empty edge list is evidence of coverage, not permission to invent a dependency.

Fix problems in the template, the approved knowledge or the package declaration and rebuild. Never patch dist/ as the durable fix. To change the template itself, see Custom Output Templates.

知识包

知识包是 Context 知识工作区面向 Agent 的产出：dist/ 下的一个文件夹，把已批准的知识变成其他 Agent 可以安装和查询的内容。它包含面向读者的已批准文章、一个懂得如何搜索这些文章的查询 Skill，以及一份把每个文件映射回其已批准来源的清单。同一次构建还可以生成文档网站和 LLM 文本；本页只介绍知识包本身。

mermaid

flowchart LR
  approved["已批准且已 close 的知识<br/>knowledge/"] --> build["context build"]
  tpl["知识包模板<br/>src/package-templates/kb"] --> build
  build --> kb["dist/name/<br/>知识包"]
  build --> site["dist/base-site/<br/>网站（可选）"]
  kb --> agent["Agent 通过<br/>knowledge-query 查询"]

包里有什么

text

dist/<package-name>/
├── AGENTS.md
├── skills/
│   └── knowledge-query/
│       ├── SKILL.md
│       └── scripts/search.mjs
├── wikis/
│   ├── index.md          # package entry page
│   ├── codeindex/ ...
│   ├── business/ ...
│   └── product/ ...
├── guides/ ...           # architecture, sop, faq, decision, incident
├── rules/ ...            # standards, test
├── feats/ ...
├── others/assets/ ...    # bundled images and resources
└── context-build-inventory.json

知识包名称已经是文件夹名，所以内部的根目录是扁平的：wikis/、guides/、rules/、feats/。每篇文章都放在其所属集合对应的根目录下——sop 页面放在 guides/sop/，codeindex 页面放在 wikis/codeindex/——具体对应关系见知识分类。wikis/ 是结构化的实体与关系层；guides/ 和 rules/ 则对其进行解释、落地为操作或加以约束。

知识包中的页面是写给使用者的：它们保留面向读者的 frontmatter，去掉生命周期注释、章节标记和指纹，并在末尾附上一个根据文章引用生成的可读来源章节——仓库链接带有文件和行范围，文档链接带有采集时记录的来源归属。精确的章节证据仍保留在知识工作区中对应的页面里。

Agent 如何读取知识包

默认的 knowledge-query Skill 是一个完整、通用的查询入口。它以结构优先的方式工作：

从每个根目录中生成的目录索引开始。
借助 context-build-inventory.json 中的关系记录了解知识包中可见的关联。
阅读候选页面，并引用其中可见的标题和段落。
当知识包没有覆盖所问的事实时，报告这一缺口。

当索引无法缩小范围，或某个页面太大而无法直接阅读时，它会用内置的 scripts/search.mjs 以 BM25 对有限大小的 Markdown 片段排序。搜索结果只是线索；知识包说了什么，要以页面正文和带类型的关系记录为准。只读取知识包的 Agent 不得声称自己读过原始来源。关于如何把知识包安装到 Agent 中，请参阅在 Agent 中使用知识包。

声明知识包

知识包在知识工作区的 src/index.ts 中声明。当你在开工报告中选择产出时，Agent 会替你修改这个文件；你无需手写。

kbPackage({
  name: "project-kb",
  template: "src/package-templates/kb",
  select: { exclude: ["**/internal/**"] },
  site: { title: "Project knowledge", lang: "en-US", base: "/" },
});

字段	含义
`name`	小写且可安全用于路径的知识包名称；产出写入 `dist/<name>/`
`template`	模板目录，或 `{ path, vars }`
`select`	可选，按 `collections`、OKF `okfRoots`，或 `knowledge/` 下的 `include` / `exclude` 路径进行选择；省略表示选择全部已批准的知识
`navigation`	目录索引策略；默认折叠索引，每个索引最多内联 50 个条目
`assets`	资源交付方式：默认打包；显式配置时可改为 Git raw 链接或不交付
`site`	同时构建文档网站

完整说明见包模板。

选择产出

多种产出可以组合。开工报告会把它们显示为一个多选列表，后续步骤沿用你的选择：

[x] Agent 知识包——新知识工作区的默认选项。
[x] 文档网站——默认与知识包一起生成，用于本地预览或之后托管。
[ ] LLM 文本——可选，作为模型上下文或 RAG 的输入；参见 LLM Docs。

你也可以只停留在已批准的 Markdown：保持 packages: []，就不会运行任何构建。没有单独的网站 Skill，每个选中的产出也不需要再单独授权。

构建与资源

context build 只使用已批准且已 close 的知识；如果 close 尚未完成，工作流会先执行它。新初始化的通用模板必须先修改或明确接受，才能进行首次构建——context status 会把它显示为知识包模板审核步骤。

已批准页面引用的图片和资源默认打包到 others/assets/。每张打包的图片不超过 1 MiB，所有图片合计不超过 40 MiB；过大的图片只会在 dist/ 中被压缩为新的 WebP 文件，绝不会改动 sources/ 或 knowledge/assets/。来源审计文件和采集报告永远不会作为读者资源交付。

构建会检查什么

模板边界。 描述覆盖范围、范围边界或已知缺口的模板文字，必须引用已批准的知识、清单或渲染后的结构数据；否则构建会报告诊断。
索引链接。 每个生成的目录索引都会被检查，确保相对链接能在知识包内解析。
路径冲突。 渲染后的模板路径不能与选中的知识路径冲突；请重命名模板文件，或用 select.exclude 排除该知识路径。
关系覆盖。 清单中的 structure.relationship_coverage 记录代码索引页面是否带有当前的关系数据，因此空的边列表是覆盖情况的证据，而不是可以凭空捏造依赖的许可。

请在模板、已批准的知识或知识包声明中修复问题，然后重新构建。永远不要把修补 dist/ 当作长期修复。如需修改模板本身，请参阅定制输出模板。

Knowledge Packages ​

What is inside ​

How Agents read it ​

Declaring a package ​

Choosing outputs ​

Building and assets ​

What the build checks ​

知识包 ​

包里有什么 ​

Agent 如何读取知识包 ​

声明知识包 ​

选择产出 ​

构建与资源 ​

构建会检查什么 ​