@c4a/context 0.6.2 → 0.6.3

package/README.md

@@ -131,6 +131,13 @@ For advanced routing and retrieval, a template may carry a local script such as
 Skill can also route the Agent to MCP servers, CLI commands, or other tools to
 form a package-specific Agentic Search workflow.
 
+Long-lived, multi-source production workspaces can copy
+`templates/project-skills/maintain-project-knowledge/SKILL.md` into their
+`.agents/skills/` directory and customize it with project ownership, source
+impact mappings, and readiness criteria. This project adapter is not included
+in knowledge packages; lifecycle authority remains with the installed Context
+Skill and current Route.
+
 ## State Boundary
 
 The SDK stays declarative. It may describe reads, writes, phases, review, and
@@ -147,5 +154,6 @@ state. The CLI owns that runtime state and removes it after a successful close.
 - [Agent Guide](./docs/guides/agent-guide.md)
 - [Project API](./docs/reference/project-api.md)
 - [Package Outputs](./docs/guides/package-outputs.md)
+- [Lark Resource Materialization](./docs/guides/lark-resources.md)
 - [Package Templates](./docs/reference/package-templates.md)
 - [Template Variables](./docs/reference/template-variables.md)

package/README.zh-CN.md

@@ -106,6 +106,12 @@ Skill 名称继续由作者独立维护。
 
 如果需要更强的路由和检索能力，模板可以携带 `query.ts` 一类本地脚本，再由 Skill 约定 Agent 何时、如何调用。Skill 也可以把 Agent 路由到 MCP、CLI 或其他工具，组成适合当前知识包的 Agentic Search 流程。
 
+长期维护、多来源的知识生产工作区可以从
+`templates/project-skills.zh-CN/maintain-project-knowledge/SKILL.md` 复制一份
+项目维护 Skill 到 `.agents/skills/`。它不进入知识包，而是补充项目专属的来源
+归属、仓库变化影响范围和准出标准；Context 生命周期仍由已安装的 Context Skill
+和当前 Route 负责。
+
 ## 状态边界
 
 SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识包选择，但来源物化、内容读取、代码提取、审核应用、正式知识写入、质量验证和构建都由 CLI 负责。不要通过直接编辑 `sources/`、`knowledge/`、`dist/` 或被忽略的 `.tmp/context-runtime/lifecycle/` 运行态来替代 CLI 生命周期操作；成功 close 后 CLI 会清理该运行态。
@@ -117,5 +123,6 @@ SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识
 - [Agent 指南](./docs/guides/agent-guide.md)
 - [项目 API](./docs/reference/project-api.md)
 - [知识包输出](./docs/guides/package-outputs.md)
+- [飞书资源物化](./docs/guides/lark-resources.md)
 - [知识包模板](./docs/reference/package-templates.md)
 - [模板变量](./docs/reference/template-variables.md)

package/docs/README.md

@@ -17,6 +17,7 @@ general reference; do not preload the whole manual set.
 - [Agent Guide](./guides/agent-guide.md) — what an agent should do, and what it should not inspect manually.
 - [Agent Dialogue](./guides/agent-dialogue.md) — stable dialogue principles and how route-selected gate resources are discovered.
 - [Package Outputs](./guides/package-outputs.md) — how to choose between an agent knowledge-base package, LLM text, or no package output.
+- [Lark Resource Materialization](./guides/lark-resources.md) — how embedded resources move from source evidence to approved knowledge and package assets.
 - [Project API](./reference/project-api.md) — `defineProject`, sources, phases, review, and packages.
 - [Package Templates](./reference/package-templates.md) — `kbPackage`, `llmsPackage`, template variables, and examples.
 - [Template Variables](./reference/template-variables.md) — Handlebars variables, loops, comments, and default knowledge inventories.
@@ -40,3 +41,15 @@ node_modules/@c4a/context/templates/package-templates/
 
 Copy or mirror these into a workspace under `src/package-templates/` when the
 project needs package outputs.
+
+Long-lived multi-source production workspaces may also start from the optional
+project-maintenance Skill template at:
+
+```text
+node_modules/@c4a/context/templates/project-skills/maintain-project-knowledge/SKILL.md
+```
+
+Copy it into the project's `.agents/skills/`, rename it for the project, and
+replace its project-fact and impact-map sections. It is a project adapter; it is
+not included in a built knowledge package and does not replace the installed
+Context Skill.

package/docs/getting-started.md

@@ -7,7 +7,7 @@ source boundary, then declare the matching phases in `src/index.ts`.
 ## 1. Initialize
 
 ```bash
-context init context --dev
+context init context
 cd context
 bun install
 context status --format json
@@ -18,10 +18,10 @@ generated README, AGENTS contract, and package starter templates should use a
 specific language. Context stores this choice in `package.json`; it does not
 guess from the shell locale or Agent conversation.
 
-Use `--dev` when testing a local link or prepared pack before the matching SDK
-version is published. It writes a `file:` dependency to the SDK resolved beside
-the active CLI. Published users can omit it and install the versioned SDK from
-the registry.
+Use `--dev` only when testing a locally linked CLI or a prepared package before
+the matching SDK version is published. It writes a `file:` dependency to the SDK
+resolved beside the active CLI. Registry installs should use the default command
+above so the workspace receives the matching versioned SDK dependency.
 
 Without `project-dir`, init uses the dedicated `context/` directory. Initializing
 inside a non-empty directory that is not already a Context workspace is blocked
@@ -187,8 +187,19 @@ and suggested `context source add` commands.
 
 Remote Git sources need the same boundary decision. Ask for the remote URL, the
 pinned commit/ref, and whether the user approves cloning. The CLI does not
-clone, checkout, reset, or fetch silently. If source material is missing or at
-the wrong ref, ask the user before running repo operations outside the CLI.
+clone, checkout, reset, or fetch silently. If registered source material is
+missing, the current Route exposes a repository recovery plan. The user chooses
+an existing checkout, a bounded local scan, or an explicit shallow/partial clone
+of the registered pinned commit. Context validates the remote, commit, and
+subpaths, restores local aliases, and materializes module links. Advancing to a
+new upstream commit remains a separate source-update decision.
+
+For a long-lived production workspace with project-specific source ownership or
+impact rules, copy the optional maintenance Skill template from
+`templates/project-skills/maintain-project-knowledge/SKILL.md` into the
+project's `.agents/skills/`, rename it for the project, and edit its project
+facts. Keep Context lifecycle commands in the installed Context Skill and
+current Route rather than duplicating them in the project Skill.
 
 ## 3. Declare The Flow
 

package/docs/guides/agent-guide.md

@@ -107,7 +107,7 @@ Present only the current workflow surface:
 | Task | Current route |
 |---|---|
 | Register a knowledge boundary | `context source add file/lark/repo ...`, followed by the matching project phase declaration. Source registration is a user-confirmed boundary decision. |
-| Capture document sources | Run the declared `capture:file:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory and updates that directory's single `manifest.json`. |
+| Capture document sources | Run the declared `capture:file:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory, updates that directory's single `manifest.json`, and mechanically materializes supported Lark resources. Do not download or rewrite embedded resources outside the CLI. |
 | Investigate captured material | Use `context status` and the returned `context run align:<type>:<source>:<collection> --view ...` commands. Evidence views drive reading; raw directory grep is not the workflow. |
 | Confirm prose structure | `alignProse` validates and stages CLI-managed lifecycle structure. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
 | Compile source-bound drafts | `compileProse` turns confirmed structure into source-bound draft pages. It does not approve knowledge. |

package/docs/guides/lark-resources.md

@@ -0,0 +1,115 @@
+# Lark Resource Materialization
+
+Lark documents can contain evidence that is not present in the readable text
+body. Context handles these resources mechanically during `captureLark`; the
+Agent does not download, summarize, or reconstruct them itself.
+
+## Resource policy
+
+| Resource | Default capture behavior |
+|---|---|
+| Image and attachment | Download the original file and link it from the Markdown projection. |
+| Sheet | Read the complete selected sheet, render a Markdown table, and retain a CSV snapshot. |
+| Base | Read the selected table/view with pagination, render a Markdown table, and retain a canonical JSON snapshot. |
+| Whiteboard and diagram | Retain a readable preview plus the raw structured export. |
+| Synced block | Resolve the exact source block, project its body, and retain a Markdown evidence snapshot. |
+| Poll | Preserve exported options and metadata as non-interactive Markdown; warn when the export omits them. |
+| Bookmark, citation, sub-document, chat, and generic embed | Preserve a stable navigation reference and provenance. |
+| Video | Preserve a stable reference by default; download only when `resources.videos` is `bundle`. |
+
+Required inline resources fail closed when their stable identity, bytes, or
+complete structured data cannot be obtained. When the remote API explicitly
+confirms that a referenced whiteboard or diagram no longer exists, Context
+preserves an unavailable-resource notice with the reason code
+`document.resource.source-missing`, reports a warning, and continues capture;
+it does not pretend that the deleted content was materialized. When the current
+identity can read the document body but the API explicitly returns
+`authorization/permission_denied` for an embedded resource, Context records
+`document.resource.permission-denied`, keeps the stable resource identity in
+the audit layer, renders the same unavailable-resource notice, and continues
+with a warning. Missing scopes, transient network errors, malformed payloads,
+and unclassified authorization failures still block capture. Reference-only
+resources remain explicit in the capture report. Unknown non-empty XML blocks
+stay auditable in the raw XML and receive a warning; the CLI does not infer
+their meaning.
+
+## Storage lifecycle
+
+Resources have three distinct locations:
+
+```text
+sources/lark/<date>/
+├── <module>.md
+├── manifest.json
+└── assets/<module>/
+    ├── source.xml
+    ├── capture-report.json
+    └── materialized/**
+knowledge/assets/<resource-kind>/<content-sha256>.<ext>
+dist/<package>/others/assets/<resource-kind>/<content-sha256>.<ext>
+```
+
+- `sources/` is the captured source and audit layer. `source.xml` preserves the
+  structured source, one `capture-report.json` closes fidelity and resource
+  handling for the document, and `materialized/` contains downloaded files and
+  structured exports. Resource descriptors are consolidated in the report;
+  capture does not create one metadata file per embedded resource.
+- The date-level `manifest.json` is a compact inventory. It records hashes,
+  asset roles, the report path, and status summaries without duplicating the
+  complete report.
+- `knowledge/assets/` contains only resources referenced by approved pages.
+  Paths are content-addressed, so identical bytes are reused and changed bytes
+  produce a new identity. Review apply rewrites page links mechanically;
+  verification compares the underlying content identity, so this deterministic
+  path projection does not count as a change to a verbatim section.
+  Markdown files below `knowledge/assets/` remain evidence resources and are
+  never interpreted as approved knowledge pages or structure views.
+- `others/assets/` is the portable package projection. Build copies only
+  resources referenced by selected package pages and rewrites their relative
+  links. Audit-only source files are not distributed.
+
+Deleting an approved page allows unreferenced `knowledge/assets` files to be
+cleaned. A missing approved or packaged resource is a verification error rather
+than a silent broken link.
+
+Source assets are part of the reproducible evidence snapshot and should not be
+ignored when the workspace is versioned. Repositories with many binary source
+assets can use Git LFS for `materialized/` while keeping Markdown, XML, JSON, and
+CSV directly reviewable in Git. The workspace must remain private when the
+captured source or screenshots are access-controlled.
+
+## SDK configuration
+
+Defaults are suitable for ordinary documents:
+
+```ts
+captureLark({ source: handbook });
+```
+
+Projects can opt into bundled video and adjust deterministic byte limits:
+
+```ts
+captureLark({
+  source: handbook,
+  resources: {
+    videos: "bundle",
+    maxBytesPerResource: 20 * 1024 * 1024,
+    maxTotalBytes: 200 * 1024 * 1024,
+  },
+});
+```
+
+The limits are capture constraints, not semantic filters. Context does not
+decide which resources are important from their business content.
+
+## Agent behavior
+
+Use the capture command returned by the current Route. Inspect the structured
+resource summary and fidelity diagnostics; do not manually edit `sources/`,
+`knowledge/assets/`, or package links. Required materialization failures other
+than a confirmed source-side deletion or an explicit resource-level permission
+denial must be resolved by recapturing after access or source problems are
+fixed. Accepted failures remain visible as warnings and unavailable-resource
+notices; they are never represented as downloaded evidence. Review shows
+available previews, references, and warnings so the human or managed policy can
+assess the page with its non-text evidence.

package/docs/guides/package-outputs.md

@@ -61,6 +61,7 @@ wikis/index.md
 guides/...
 rules/...
 feats/...
+others/assets/...
 ```
 
 Do not ask for another distribution namespace. Older workspaces may still
@@ -88,6 +89,13 @@ package needs project-specific terminology, entry points, known limits, or
 task workflows. Authors may explicitly accept the generic default when it is
 intentionally sufficient.
 
+When approved pages reference materialized document resources, Context keeps
+their production copies in content-addressed `knowledge/assets/` paths. Build
+copies only the resources selected by package pages to `others/assets/` and
+rewrites relative Markdown links. Source audit XML and capture reports stay in
+the production workspace; they are not distributed as reader assets. See
+[Lark Resource Materialization](./lark-resources.md).
+
 The same inventory exposes `structure.relationship_coverage`. It records
 whether selected codegraph pages have current source-backed AST relationship
 metadata, how many codegraph views were selected, and how many package-visible

package/docs/reference/project-api.md

@@ -209,6 +209,13 @@ extraction phases, review gates, close/build, and packages explicitly. The CLI
 then routes work through `context status`, `context run <phase-id>`, `context
 review html/apply`, `context close`, `context verify`, and `context build`.
 
+For Agent and automation output, use `context verify --format json --compact`.
+It returns deterministic groups, counts, affected-scope totals, and a few
+representative samples instead of repeating every issue. Read the complete,
+auditable issue set only when needed with `context verify --view diagnostics
+--page-size 25 --format json`; follow its executable pagination command without
+inventing overlapping file ranges.
+
 ### Status declaration coverage
 
 `context status --format json --view full` includes a `declarationGraph` and
@@ -321,6 +328,21 @@ Markdown snapshot:
 captureLark({ source: handbook });
 ```
 
+Embedded resources are materialized with deterministic defaults. Video remains
+reference-only unless a project opts into bundling, and byte limits prevent an
+unexpected document from expanding the workspace without bound:
+
+```ts
+captureLark({
+  source: handbook,
+  resources: {
+    videos: "bundle",
+    maxBytesPerResource: 20 * 1024 * 1024,
+    maxTotalBytes: 200 * 1024 * 1024,
+  },
+});
+```
+
 Phase id:
 
 ```text
@@ -334,19 +356,33 @@ one date batch; when `--module` is omitted, the CLI derives an opaque,
 credential-safe module id. Capture reads the
 remote document through the CLI runner as structured Docx XML. Context keeps a
 redacted XML audit asset, projects supported blocks deterministically into
-readable Markdown, and registers external resources such as document citations,
-images, video, whiteboards, and Base references in the snapshot manifest even
-when their binary content is not downloaded. The projection does not infer or
-summarize document meaning. Its fidelity report closes discovered blocks
+readable Markdown, and materializes required inline resources such as images,
+attachments, Sheets, Bases, whiteboards, diagrams, and synced blocks. Navigation
+resources and default video capture remain explicit references. The projection
+does not infer or summarize document meaning. Its fidelity and resource reports close discovered blocks
 against converted and intentionally skipped blocks and reports evidence
 completeness separately from Markdown projection quality. Unknown non-empty XML
 blocks receive a generic, auditable, non-interactive projection and do not block
-downstream work. Missing source content or unresolved external-resource identity
-remains an evidence error and prevents downstream Review.
+downstream work. A remote whiteboard or diagram explicitly confirmed as deleted
+is preserved as an unavailable-resource notice with
+`document.resource.source-missing` and a warning. An embedded resource whose
+export is explicitly rejected as `authorization/permission_denied` is retained
+the same way with `document.resource.permission-denied`. Missing scopes,
+unresolved external-resource identity, retryable failures, and unclassified
+authorization errors remain evidence errors and prevent downstream Review.
 Snapshot files live under `sources/lark/<date>/` as sibling document files
-tracked by one date-level `manifest.json`. Access credentials and transient
+tracked by one compact date-level `manifest.json`. Each module keeps one raw
+`source.xml`, one consolidated `capture-report.json`, and its actual downloaded
+or structured resources under `assets/<module>/materialized/`; it does not emit
+one descriptor file per embedded resource. Access credentials and transient
 signed media URLs are not written into the workspace.
 
+Approved resource bytes are projected to content-addressed
+`knowledge/assets/<kind>/` paths. KB build copies selected resources to
+`others/assets/<kind>/` inside the package and rewrites page links. See
+[Lark Resource Materialization](../guides/lark-resources.md) for the complete
+resource table and storage lifecycle.
+
 Use a typed document reference in project declarations:
 
 ```ts

package/index.js

@@ -7128,6 +7128,14 @@ var captureFile = (definition) => {
 var captureLark = (definition) => {
   const sourceDefinition = bindSourceType(definition.source, "lark", "captureLark source");
   const sourceId = getSourceName(sourceDefinition);
+  const maxBytesPerResource = definition.resources?.maxBytesPerResource ?? 20 * 1024 * 1024;
+  const maxTotalBytes = definition.resources?.maxTotalBytes ?? 200 * 1024 * 1024;
+  if (!Number.isSafeInteger(maxBytesPerResource) || maxBytesPerResource < 1) {
+    throw new TypeError("captureLark resources.maxBytesPerResource must be a positive safe integer");
+  }
+  if (!Number.isSafeInteger(maxTotalBytes) || maxTotalBytes < maxBytesPerResource) {
+    throw new TypeError("captureLark resources.maxTotalBytes must be a safe integer greater than or equal to maxBytesPerResource");
+  }
   return {
     kind: "phase.capture.lark",
     id: `capture:lark:${sourceId}`,
@@ -7136,7 +7144,12 @@ var captureLark = (definition) => {
       source: sourceDefinition
     }],
     writes: [sourceSnapshotResource(sourceDefinition, "lark")],
-    source: sourceDefinition
+    source: sourceDefinition,
+    resources: {
+      videos: definition.resources?.videos ?? "reference-only",
+      maxBytesPerResource,
+      maxTotalBytes
+    }
   };
 };
 var alignProse = (definition) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "type": "module",
   "description": "Context SDK — project-local configuration and workspace primitives",
   "license": "MIT",
@@ -15,6 +15,9 @@
     "knowledge",
     "workspace"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "yaml": "^2.5.1",
     "zod": "^3.23.8"

package/phases.d.ts

@@ -143,6 +143,11 @@ export type CaptureLarkPhaseDefinition = {
     reads: readonly PhaseResourceReference[];
     writes: readonly PhaseResourceReference[];
     source: LarkSourceDefinition | LarkSourceReference;
+    resources: {
+        videos: "reference-only" | "bundle";
+        maxBytesPerResource: number;
+        maxTotalBytes: number;
+    };
 };
 export type AlignProsePhaseDefinition = {
     kind: "phase.align.prose";
@@ -200,6 +205,11 @@ export declare const captureFile: (definition: {
 }) => CaptureFilePhaseDefinition;
 export declare const captureLark: (definition: {
     source: LarkSourceDefinition | LarkSourceReference;
+    resources?: {
+        videos?: "reference-only" | "bundle";
+        maxBytesPerResource?: number;
+        maxTotalBytes?: number;
+    };
 }) => CaptureLarkPhaseDefinition;
 export declare const alignProse: (definition: {
     source: DocumentSourceDefinition;

package/templates/package-templates/kb/skills/knowledge-query/SKILL.md

@@ -78,11 +78,12 @@ phrases, or several large indexes, run the bundled
 node <current knowledge-query Skill directory>/scripts/search.mjs --query '<terms>' --limit 8
 ```
 
-The script locates `{{packageName}}` from a raw package or TTKB installation.
-If discovery is ambiguous, add `--root <package directory containing
-context-build-inventory.json>`. It chunks Markdown mechanically by headings and
-bounded line ranges, then returns paths, line ranges, headings, and previews; it
-does not interpret meaning.
+The script locates `{{packageName}}` when it runs inside the package tree. If a
+package manager copied this Skill elsewhere, add `--root <package directory
+containing context-build-inventory.json>`, or use `--base <package collection>`
+to locate this package by its inventory name. It chunks Markdown mechanically
+by headings and bounded line ranges, then returns paths, line ranges, headings,
+and previews; it does not interpret meaning.
 
 Treat every hit as a lead and open its page and section before answering. For
 relationship or impact claims, use typed edges from

package/templates/package-templates/kb/skills/knowledge-query/scripts/search.mjs

@@ -14,8 +14,8 @@ function usage() {
     "Search an approved knowledge package with deterministic BM25 ranking.",
     "",
     "Usage:",
-    "  node search.mjs --query <text> [--root <package-root>] [--limit <n>] [--json]",
-    "  node search.mjs <text> [--root <package-root>] [--limit <n>] [--json]",
+    "  node search.mjs --query <text> [--root <package-root>] [--base <package-collection>] [--limit <n>] [--json]",
+    "  node search.mjs <text> [--root <package-root>] [--base <package-collection>] [--limit <n>] [--json]",
     "",
     "The package root is detected from context-build-inventory.json when possible.",
   ].join("\n");
@@ -23,7 +23,7 @@ function usage() {
 
 function parseArgs(argv) {
   const positional = [];
-  const options = { root: undefined, query: undefined, limit: 8, json: false };
+  const options = { root: undefined, base: undefined, query: undefined, limit: 8, json: false };
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
     if (arg === "--help" || arg === "-h") return { help: true };
@@ -31,10 +31,11 @@ function parseArgs(argv) {
       options.json = true;
       continue;
     }
-    if (arg === "--root" || arg === "--query" || arg === "--limit") {
+    if (arg === "--root" || arg === "--base" || arg === "--query" || arg === "--limit") {
       const value = argv[++index];
       if (value === undefined) throw new Error(`missing value for ${arg}`);
       if (arg === "--root") options.root = value;
+      else if (arg === "--base") options.base = value;
       else if (arg === "--query") options.query = value;
       else options.limit = Number(value);
       continue;
@@ -83,7 +84,7 @@ function inventoryPackageName(inventoryPath) {
   }
 }
 
-function resolvePackageRoot(explicitRoot) {
+function resolvePackageRoot(explicitRoot, packageCollection) {
   if (explicitRoot !== undefined) {
     const root = resolve(explicitRoot);
     if (!isPackageRoot(root)) throw new Error(`package root has no context-build-inventory.json: ${root}`);
@@ -93,7 +94,10 @@ function resolvePackageRoot(explicitRoot) {
   if (scriptRoot !== undefined) return scriptRoot;
   const cwdRoot = ancestorPackageRoot(process.cwd());
   if (cwdRoot !== undefined) return cwdRoot;
-  const inventories = findInventories(join(process.cwd(), ".ttkb", "packages"));
+  if (packageCollection === undefined) {
+    throw new Error("cannot locate the knowledge package; pass --root <package-root> or --base <package-collection>");
+  }
+  const inventories = findInventories(resolve(packageCollection));
   const matching = inventories.filter((path) => inventoryPackageName(path) === PACKAGE_NAME);
   if (matching.length === 1) return dirname(matching[0]);
   if (matching.length > 1) {
@@ -245,7 +249,7 @@ try {
     process.stdout.write(`${usage()}\n`);
     process.exit(0);
   }
-  const root = resolvePackageRoot(options.root);
+  const root = resolvePackageRoot(options.root, options.base);
   const results = search(root, options.query, options.limit);
   if (options.json) {
     process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, root, query: options.query, results }, null, 2)}\n`);

package/templates/package-templates/llms/llms.txt

@@ -6,4 +6,3 @@ Package kind: {{packageKind}}
 Approved knowledge files: {{knowledgeCount}}
 
 {{knowledge}}
-

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

@@ -60,7 +60,7 @@ description: 查询 {{displayName}} 中经过审核、可追溯来源的知识
 node <当前 knowledge-query Skill 目录>/scripts/search.mjs --query '<关键词>' --limit 8
 ```
 
-脚本会从原始包或 TTKB 安装目录定位 `{{packageName}}`；无法唯一定位时，增加 `--root <包含 context-build-inventory.json 的包目录>`。它按 Markdown 标题和固定行块机械切分，返回路径、行号、标题和短预览，不判断内容语义。
+脚本位于知识包目录内时会自动定位 `{{packageName}}`。如果包管理工具将本 Skill 复制到了其他位置，增加 `--root <包含 context-build-inventory.json 的包目录>`；也可以使用 `--base <多包集合根目录>`，按构建清单中的包名定位。它按 Markdown 标题和固定行块机械切分，返回路径、行号、标题和短预览，不判断内容语义。
 
 搜索命中只是线索。回答前必须打开命中的页面和章节；关系或影响范围仍以 `context-build-inventory.json` 的类型化边为准，不能用 BM25 分数或文本共现替代关系证据。
 

package/templates/package-templates.zh-CN/kb/skills/knowledge-query/scripts/search.mjs

@@ -14,8 +14,8 @@ function usage() {
     "Search an approved knowledge package with deterministic BM25 ranking.",
     "",
     "Usage:",
-    "  node search.mjs --query <text> [--root <package-root>] [--limit <n>] [--json]",
-    "  node search.mjs <text> [--root <package-root>] [--limit <n>] [--json]",
+    "  node search.mjs --query <text> [--root <package-root>] [--base <package-collection>] [--limit <n>] [--json]",
+    "  node search.mjs <text> [--root <package-root>] [--base <package-collection>] [--limit <n>] [--json]",
     "",
     "The package root is detected from context-build-inventory.json when possible.",
   ].join("\n");
@@ -23,7 +23,7 @@ function usage() {
 
 function parseArgs(argv) {
   const positional = [];
-  const options = { root: undefined, query: undefined, limit: 8, json: false };
+  const options = { root: undefined, base: undefined, query: undefined, limit: 8, json: false };
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
     if (arg === "--help" || arg === "-h") return { help: true };
@@ -31,10 +31,11 @@ function parseArgs(argv) {
       options.json = true;
       continue;
     }
-    if (arg === "--root" || arg === "--query" || arg === "--limit") {
+    if (arg === "--root" || arg === "--base" || arg === "--query" || arg === "--limit") {
       const value = argv[++index];
       if (value === undefined) throw new Error(`missing value for ${arg}`);
       if (arg === "--root") options.root = value;
+      else if (arg === "--base") options.base = value;
       else if (arg === "--query") options.query = value;
       else options.limit = Number(value);
       continue;
@@ -83,7 +84,7 @@ function inventoryPackageName(inventoryPath) {
   }
 }
 
-function resolvePackageRoot(explicitRoot) {
+function resolvePackageRoot(explicitRoot, packageCollection) {
   if (explicitRoot !== undefined) {
     const root = resolve(explicitRoot);
     if (!isPackageRoot(root)) throw new Error(`package root has no context-build-inventory.json: ${root}`);
@@ -93,7 +94,10 @@ function resolvePackageRoot(explicitRoot) {
   if (scriptRoot !== undefined) return scriptRoot;
   const cwdRoot = ancestorPackageRoot(process.cwd());
   if (cwdRoot !== undefined) return cwdRoot;
-  const inventories = findInventories(join(process.cwd(), ".ttkb", "packages"));
+  if (packageCollection === undefined) {
+    throw new Error("cannot locate the knowledge package; pass --root <package-root> or --base <package-collection>");
+  }
+  const inventories = findInventories(resolve(packageCollection));
   const matching = inventories.filter((path) => inventoryPackageName(path) === PACKAGE_NAME);
   if (matching.length === 1) return dirname(matching[0]);
   if (matching.length > 1) {
@@ -245,7 +249,7 @@ try {
     process.stdout.write(`${usage()}\n`);
     process.exit(0);
   }
-  const root = resolvePackageRoot(options.root);
+  const root = resolvePackageRoot(options.root, options.base);
   const results = search(root, options.query, options.limit);
   if (options.json) {
     process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, root, query: options.query, results }, null, 2)}\n`);

package/templates/project-skills/maintain-project-knowledge/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: maintain-project-knowledge
+description: Maintain a project-local Context knowledge workspace by checking registered repository and document sources, selecting the affected project scope, and handing lifecycle actions to the installed Context Skill. Customize the name, description, project facts, and impact map before using this template in a real project.
+---
+
+# Maintain project knowledge
+
+Use this file as a project adapter, not as a copy of the Context workflow. Read
+the installed Context Skill first and treat its current Route, resources, and
+commands as authoritative. Keep only stable project facts and source-impact
+mappings here.
+
+## Repository sources
+
+Start with the current Context Route. If registered repository modules are
+missing or their local links are broken, follow the route-selected repository
+recovery procedure. Let the user choose an existing checkout, authorize a scan
+inside one bounded directory, or explicitly clone the registered pinned commit.
+
+When a checkout already exists, inspect its origin, HEAD, dirty state, and
+registered subpaths before asking whether to keep the recorded commit or update
+to another explicit commit. Never pull, switch, clean, or reset an external
+checkout without separate authority.
+
+Repository sources are ready for knowledge work only when every selected module
+resolves to its registered remote and commit, all required subpaths exist,
+unknown local changes are preserved, Context has materialized its module links,
+and the current Route no longer reports a repository-readiness blocker.
+
+Add the project's stable mapping from repository changes to declared extraction
+scope here. Do not infer this mapping from filenames during a maintenance run.
+
+## Remote document sources
+
+Use the current Context Route and the installed document-provider Skills or CLI
+to read registered remote documents. Keep this section short: provider login,
+permissions, capture, sub-page traversal, and fidelity diagnostics belong to
+the provider and Context resources selected for the current step.
+
+A remote document is ready for knowledge work only when its registered identity
+is unchanged unless the user explicitly adds a new source, the current account
+can read the required body and assets, relevant child pages are represented as
+their own sources, capture fidelity has no blocking error, and the current Route
+allows structure or extraction work to begin.
+
+Add project-specific source ownership, expected document families, and update
+boundaries here. Do not copy credentials, source bodies, or volatile command
+lines into this Skill.
+
+## Project facts and completion
+
+Record only durable project paths, declared package outputs, physical-to-logical
+repository grouping, and evidence-backed impact rules. Do not duplicate Context
+phase commands or manually edit lifecycle-owned directories.
+
+Report completion using the current Context Route and build receipt, including
+the checked source range, changed and unchanged knowledge, unresolved permissions
+or fidelity blockers, and whether a package was built or separately published.

package/templates/project-skills.zh-CN/maintain-project-knowledge/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: maintain-project-knowledge
+description: 维护项目内的 Context 知识生产工作区；用于检查已登记仓库和文档来源、判断项目影响范围，并把生命周期动作交回已安装的 Context Skill。用于真实项目前，请修改名称、描述、项目事实和影响映射。
+---
+
+# 维护项目知识
+
+本 Skill 是项目适配层，不复制 Context 工作流。先读取已安装的 Context
+Skill，并以当前 Route、资源和命令为权威；这里只保留稳定的项目事实和来源
+影响映射。
+
+## 仓库来源的获取和更新
+
+先检查当前 Context Route。已登记仓库模块缺失或本地链接断开时，使用 Route
+选择的仓库恢复流程，让用户选择已有 checkout、授权在一个限定目录内扫描，
+或明确允许 clone 已登记的固定 commit。
+
+checkout 已存在时，先检查 origin、HEAD、dirty 状态和已登记 subpath，再询问
+用户保持当前登记版本，还是更新到另一个明确 commit。没有单独授权时，不得对
+外部 checkout 执行 pull、切换、清理或 reset。
+
+只有当每个目标模块都对应已登记 remote 和 commit、全部 subpath 存在、未知
+本地修改得到保护、Context 已物化模块链接，并且当前 Route 不再报告仓库未
+就绪时，仓库来源才可以进入知识更新。
+
+在这里补充本项目稳定的“仓库变化 → 提取范围”映射。维护过程中不得仅根据
+文件名临时猜测影响关系。
+
+## 远程文档来源的获取和更新
+
+通过当前 Context Route 以及宿主安装的文档提供方 Skill 或 CLI 读取已登记
+文档。本节保持简短：登录、权限、采集、子页遍历和保真诊断由当前步骤选择的
+提供方与 Context 资源负责。
+
+只有当来源身份保持稳定（除非用户明确新增来源）、当前账号能够读取所需正文
+和资源、需要正文的子页已作为独立来源处理、采集不存在阻塞性 fidelity error，
+并且当前 Route 允许开始结构或提取工作时，远程文档才可以进入知识更新。
+
+在这里补充本项目的来源归属、预期文档类型和更新边界。不要把凭据、来源正文
+或易漂移的完整命令写进 Skill。
+
+## 项目事实与完成标准
+
+只记录长期稳定的项目路径、包输出、物理仓库与逻辑来源分组，以及有证据的影响
+规则。不得复制 Context 阶段命令，也不得手工修改生命周期托管目录。
+
+以当前 Context Route 和构建回执报告完成情况，说明检查范围、知识新增/更新/
+无变化、尚未解决的权限或保真问题，以及知识包是仅完成构建还是已经另行发布。