@c4a/context 0.6.1 → 0.6.3

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

@@ -0,0 +1,99 @@
+---
+name: {{skillName}}
+description: 查询 {{displayName}} 中经过审核、可追溯来源的知识。用于查找包内实体、API、行为、流程、约束、决策、排障信息、关系和覆盖范围。
+---
+
+# 知识查询
+
+只根据本包包含的已批准知识回答。先通过索引缩小范围，再打开具体页面；正文是事实证据，frontmatter 摘要只用于导航。
+
+## 查询步骤
+
+1. 判断请求属于实体查找、解释、流程、规则、关系、细节还是覆盖检查。
+2. 从最相关的根索引开始，例如 `{{wikisRoot}}/index.md`，再沿链接进入具体页面。
+3. 只读取回答所需的章节；frontmatter 用来选择范围，不作为事实依据。
+4. 查询关系或影响范围时，先检查 `context-build-inventory.json` 中的 `structure.edge_records`，再读取两端页面。
+5. 结论只能来自可见章节正文和来源支持的边记录，并引用对应页面或章节。
+6. 如果包内没有证据，明确报告缺口和已经检查的范围，不要根据邻近内容推断。
+
+## 知识根目录
+
+| 根目录 | 用途 |
+|---|---|
+| `{{wikisRoot}}/` | 来自 codegraph、business、product 的结构化实体和关系。 |
+| `{{guidesRoot}}/` | 架构、流程、FAQ、决策、故障和排障说明。 |
+| `{{rulesRoot}}/` | 标准、约束、验收条件和测试场景。 |
+| `{{featsRoot}}/` | 被选择进入包内的功能知识。 |
+
+缺少某个根目录表示当前知识包没有选择该类别。
+
+## 按意图导航
+
+| 意图 | 第一步 |
+|---|---|
+| 模糊主题或未知名称 | 打开可能相关的根索引，从分组中选择候选页面。 |
+| 指定实体、API、领域或动作 | 打开匹配页面或最近的分组索引；有歧义时列出候选。 |
+| 架构、流程、FAQ、决策或故障 | 从 `{{guidesRoot}}/index.md` 开始。 |
+| 标准、约束、验收或测试 | 从 `{{rulesRoot}}/index.md` 开始。 |
+| 关系或影响范围 | 检查类型化边，再读取两端页面。 |
+| 已知页面中的细节 | 读取对应 `context:section`。 |
+| 覆盖范围或缺口 | 检查根索引和 `context-build-inventory.json`。 |
+
+## 证据契约
+
+| 证据 | 可支持的内容 |
+|---|---|
+| 页面路径 | 页面身份和引用位置。 |
+| frontmatter 的标题、描述、稳定节点标识和标签 | 导航和范围选择。 |
+| `context:section` 的 id、kind、`source_ref` | 章节身份、引用位置和来源边界。 |
+| 读者可见的章节正文 | 事实结论的主要依据。 |
+| `context-build-inventory.json` 的边记录 | 类型化关系证据。 |
+| 根索引和构建清单 | 包的范围和覆盖情况。 |
+
+不要根据页面同时出现来推断关系。如果 `source_ref` 指向未随包分发的来源，只能引用已经过审核的可见章节，不能扩展到正文没有表达的内容。
+
+## 搜索兜底
+
+只有索引和页面结构无法确定范围，或候选页面过大不适合整页读取时才搜索。精确名称、API、配置键、路径或错误字符串可先用 `rg`；包含多个关键词、中文短语或多个大型索引时，执行本 Skill 随附的 [`scripts/search.mjs`](scripts/search.mjs) 做 BM25 排序：
+
+```bash
+node <当前 knowledge-query Skill 目录>/scripts/search.mjs --query '<关键词>' --limit 8
+```
+
+脚本位于知识包目录内时会自动定位 `{{packageName}}`。如果包管理工具将本 Skill 复制到了其他位置，增加 `--root <包含 context-build-inventory.json 的包目录>`；也可以使用 `--base <多包集合根目录>`，按构建清单中的包名定位。它按 Markdown 标题和固定行块机械切分，返回路径、行号、标题和短预览，不判断内容语义。
+
+搜索命中只是线索。回答前必须打开命中的页面和章节；关系或影响范围仍以 `context-build-inventory.json` 的类型化边为准，不能用 BM25 分数或文本共现替代关系证据。
+
+## 引用与缺口
+
+引用应紧跟结论：
+
+```text
+页面：     <结论> [<root>/path/page.md]
+章节：     <结论> [<root>/path/page.md#section-id]
+来源绑定： <结论> [<root>/path/page.md#section-id, source_ref]
+关系：     <结论> [context-build-inventory.json#structure.edge_records edge:<type>]
+覆盖：     <结论> [context-build-inventory.json]
+```
+
+没有证据时返回：
+
+```text
+缺口：本知识包没有包含 <缺失点> 的证据。
+已检查：<索引、页面或构建产物>。
+下一步来源：<已知时填写来源、页面或 source_ref>。
+```
+
+“本包没有证据”不等于“事实不成立”。禁止使用模型记忆、旧对话或包外源码填补缺口。
+
+## 包边界
+
+- 包内兼容 OKF 的根目录是本 Skill 的事实来源。
+- 本包只包含 Context 工作区选择并批准的知识，不声明完整覆盖底层产品或代码库。
+- 已有更窄索引范围可以回答时，不要扫描所有页面或关系边。
+
+已批准知识文件：`{{knowledgeCount}}`
+
+## 模板作者建议
+
+这是可直接工作的通用查询 Skill。正式发布前，如果知识包存在专用术语、常见用户意图、推荐入口、已知边界或固定任务流程，作者应修改 description、路由表和包边界说明；如果通用行为已经足够，应在 Context 的包模板 Review 中明确接受未修改模板。

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

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_NAME = "{{packageName}}";
+const STANDARD_ROOTS = ["wikis", "guides", "rules", "feats"];
+const MAX_CHUNK_LINES = 80;
+const CHUNK_OVERLAP = 5;
+
+function usage() {
+  return [
+    "Search an approved knowledge package with deterministic BM25 ranking.",
+    "",
+    "Usage:",
+    "  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");
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  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 };
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    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;
+    }
+    positional.push(arg);
+  }
+  if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 50) {
+    throw new Error("--limit must be an integer between 1 and 50");
+  }
+  options.query ??= positional.join(" ");
+  if (options.query.trim().length === 0) throw new Error("query must not be empty");
+  return options;
+}
+
+function isPackageRoot(directory) {
+  return existsSync(join(directory, "context-build-inventory.json"));
+}
+
+function ancestorPackageRoot(start) {
+  let current = resolve(start);
+  while (true) {
+    if (isPackageRoot(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function findInventories(directory, depth = 0) {
+  if (!existsSync(directory) || depth > 5) return [];
+  const inventory = join(directory, "context-build-inventory.json");
+  if (existsSync(inventory)) return [inventory];
+  const matches = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    matches.push(...findInventories(join(directory, entry.name), depth + 1));
+  }
+  return matches;
+}
+
+function inventoryPackageName(inventoryPath) {
+  try {
+    return JSON.parse(readFileSync(inventoryPath, "utf8"))?.package?.name;
+  } catch {
+    return undefined;
+  }
+}
+
+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}`);
+    return root;
+  }
+  const scriptRoot = ancestorPackageRoot(dirname(fileURLToPath(import.meta.url)));
+  if (scriptRoot !== undefined) return scriptRoot;
+  const cwdRoot = ancestorPackageRoot(process.cwd());
+  if (cwdRoot !== undefined) return cwdRoot;
+  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) {
+    throw new Error(`multiple installed packages named ${PACKAGE_NAME}; pass --root explicitly`);
+  }
+  throw new Error("cannot locate the knowledge package; pass --root <package-root>");
+}
+
+function knowledgeRoots(packageRoot) {
+  const inventoryPath = join(packageRoot, "context-build-inventory.json");
+  let declared = [];
+  try {
+    const inventory = JSON.parse(readFileSync(inventoryPath, "utf8"));
+    declared = Object.values(inventory?.package?.distribution?.roots ?? {})
+      .filter((value) => typeof value === "string");
+  } catch {
+    declared = [];
+  }
+  return [...new Set([...declared, ...STANDARD_ROOTS])]
+    .map((root) => join(packageRoot, root))
+    .filter((root) => existsSync(root) && statSync(root).isDirectory());
+}
+
+function markdownFiles(directory) {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...markdownFiles(path));
+    else if (entry.isFile() && entry.name.endsWith(".md")) files.push(path);
+  }
+  return files;
+}
+
+function headingChunks(content) {
+  const lines = content.split(/\r?\n/u);
+  const starts = [];
+  for (let index = 0; index < lines.length; index++) {
+    if (/^#{1,6}\s+\S/u.test(lines[index] ?? "")) starts.push(index);
+  }
+  if (starts.length === 0) starts.push(0);
+  const chunks = [];
+  for (let headingIndex = 0; headingIndex < starts.length; headingIndex++) {
+    const start = starts[headingIndex] ?? 0;
+    const end = starts[headingIndex + 1] ?? lines.length;
+    const heading = (lines[start] ?? "").replace(/^#{1,6}\s+/u, "").trim() || "Document";
+    for (let offset = start; offset < end; offset += MAX_CHUNK_LINES - CHUNK_OVERLAP) {
+      const chunkEnd = Math.min(end, offset + MAX_CHUNK_LINES);
+      chunks.push({
+        heading,
+        startLine: offset + 1,
+        endLine: chunkEnd,
+        text: lines.slice(offset, chunkEnd).join("\n"),
+      });
+      if (chunkEnd === end) break;
+    }
+  }
+  return chunks;
+}
+
+function tokens(text) {
+  const normalized = text.toLocaleLowerCase();
+  const result = normalized.match(/[a-z0-9@._:/-]+|\p{Script=Han}+/gu) ?? [];
+  const expanded = [];
+  for (const token of result) {
+    expanded.push(token);
+    if (/^\p{Script=Han}+$/u.test(token)) {
+      for (let index = 0; index < token.length - 1; index++) expanded.push(token.slice(index, index + 2));
+    } else {
+      expanded.push(...token.split(/[^a-z0-9]+/u).filter((part) => part.length > 1));
+    }
+  }
+  return expanded.filter((token) => token.length > 0);
+}
+
+function termFrequency(items) {
+  const counts = new Map();
+  for (const item of items) counts.set(item, (counts.get(item) ?? 0) + 1);
+  return counts;
+}
+
+function preview(text, queryTerms, query) {
+  const lines = text.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean);
+  const loweredQuery = query.toLocaleLowerCase().trim();
+  const matching = [...lines].sort((left, right) => {
+    const leftText = left.toLocaleLowerCase();
+    const rightText = right.toLocaleLowerCase();
+    const lineScore = (value) =>
+      (value.includes(loweredQuery) ? queryTerms.length + 2 : 0)
+      + queryTerms.filter((term) => value.includes(term)).length;
+    return lineScore(rightText) - lineScore(leftText);
+  })[0];
+  return (matching ?? lines[0] ?? "").replace(/\s+/gu, " ").slice(0, 240);
+}
+
+function search(packageRoot, query, limit) {
+  const documents = [];
+  for (const root of knowledgeRoots(packageRoot)) {
+    for (const file of markdownFiles(root)) {
+      const path = relative(packageRoot, file).split("\\").join("/");
+      const content = readFileSync(file, "utf8");
+      for (const chunk of headingChunks(content)) {
+        const weightedText = `${path} ${chunk.heading} ${chunk.heading} ${chunk.text}`;
+        const chunkTokens = tokens(weightedText);
+        documents.push({ ...chunk, path, tokens: chunkTokens, tf: termFrequency(chunkTokens) });
+      }
+    }
+  }
+  const queryTerms = [...new Set(tokens(query))];
+  const documentFrequency = new Map();
+  for (const term of queryTerms) {
+    documentFrequency.set(term, documents.filter((document) => document.tf.has(term)).length);
+  }
+  const averageLength = documents.reduce((sum, document) => sum + document.tokens.length, 0)
+    / Math.max(documents.length, 1);
+  const loweredQuery = query.toLocaleLowerCase().trim();
+  const scored = documents.map((document) => {
+    let score = 0;
+    for (const term of queryTerms) {
+      const frequency = document.tf.get(term) ?? 0;
+      if (frequency === 0) continue;
+      const matches = documentFrequency.get(term) ?? 0;
+      const idf = Math.log(1 + (documents.length - matches + 0.5) / (matches + 0.5));
+      const denominator = frequency + 1.2 * (0.25 + 0.75 * document.tokens.length / Math.max(averageLength, 1));
+      score += idf * frequency * 2.2 / denominator;
+    }
+    const searchable = `${document.path}\n${document.heading}\n${document.text}`.toLocaleLowerCase();
+    if (searchable.includes(loweredQuery)) score += 4;
+    if (`${document.path} ${document.heading}`.toLocaleLowerCase().includes(loweredQuery)) score += 2;
+    return { ...document, score };
+  }).filter((document) => document.score > 0);
+  scored.sort((left, right) =>
+    right.score - left.score
+    || left.path.localeCompare(right.path)
+    || left.startLine - right.startLine
+  );
+  return scored.slice(0, limit).map((document) => ({
+    score: Number(document.score.toFixed(4)),
+    path: document.path,
+    heading: document.heading,
+    start_line: document.startLine,
+    end_line: document.endLine,
+    preview: preview(document.text, queryTerms, query),
+  }));
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    process.stdout.write(`${usage()}\n`);
+    process.exit(0);
+  }
+  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`);
+  } else if (results.length === 0) {
+    process.stdout.write(`No matching knowledge found for: ${options.query}\n`);
+  } else {
+    for (const [index, result] of results.entries()) {
+      process.stdout.write(`${index + 1}. ${result.path}:${result.start_line}-${result.end_line} [${result.score}] ${result.heading}\n`);
+      process.stdout.write(`   ${result.preview}\n`);
+    }
+  }
+} catch (error) {
+  process.stderr.write(`knowledge-search: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.stderr.write(`${usage()}\n`);
+  process.exit(2);
+}

package/templates/package-templates.zh-CN/kb/wikis/index.md

@@ -0,0 +1,39 @@
+---
+type: Knowledge Bundle
+title: "{{displayName}}"
+description: "由 Context 工作区生成的已批准知识包。"
+tags:
+  - context
+  - knowledge-base
+timestamp: "{{knowledgeTimestamp}}"
+resource: "context://package/{{packageName}}/{{wikisRoot}}"
+package: "{{packageName}}"
+package_kind: "{{packageKind}}"
+knowledge_count: {{knowledgeCount}}
+---
+
+<!-- context:template
+这是一个起始模板。`context build` 渲染后会将其复制到
+`dist/<package-name>/{{wikisRoot}}/index.md`。
+
+以 context:template 开头的模板注释不会进入构建产物。
+修改前请阅读模板变量手册：
+node_modules/@c4a/context/docs/reference/template-variables.md
+
+正式发布前，应补充知识包范围、目标读者、推荐阅读顺序、已知缺口、使用场景或任务入口。
+小目录会直接列出内容，超过导航阈值时会链接到子目录 index.md。
+-->
+
+# {{displayName}}
+
+本知识包包含 `{{knowledgeCount}}` 个已批准知识页面。请先使用本索引定位范围，再打开具体知识页获取可追溯来源的细节。
+
+## 内容
+
+{{knowledgeGroupsMarkdown}}
+
+## 使用方式
+
+- 从上方导航开始，再进入知识页或子目录索引。
+- 安装为 Agent 知识包后，可以使用随包提供的 knowledge-query Skill。
+- 如果包需要专用范围、已知缺口、阅读路径或任务入口，作者应替换或编辑本通用索引；否则应在 Context 包模板 Review 中明确接受未修改模板。

package/templates/package-templates.zh-CN/llms/llms.txt

@@ -0,0 +1,8 @@
+# {{packageName}}
+
+由 Context 生成。
+
+包类型：{{packageKind}}
+已批准知识文件：{{knowledgeCount}}
+
+{{knowledge}}

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 和构建回执报告完成情况，说明检查范围、知识新增/更新/
+无变化、尚未解决的权限或保真问题，以及知识包是仅完成构建还是已经另行发布。