@c4a/context 0.6.1 → 0.6.2

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
+```
+
+脚本会从原始包或 TTKB 安装目录定位 `{{packageName}}`；无法唯一定位时，增加 `--root <包含 context-build-inventory.json 的包目录>`。它按 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,264 @@
+#!/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>] [--limit <n>] [--json]",
+    "  node search.mjs <text> [--root <package-root>] [--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, 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 === "--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 === "--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) {
+  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;
+  const inventories = findInventories(join(process.cwd(), ".ttkb", "packages"));
+  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);
+  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}}