@code2knowledge/skill 0.0.0-stage → 1.0.0

package/assets/project-context/ontology/schema.md

@@ -0,0 +1,37 @@
+---
+knowledge_type: type_constraint
+---
+
+# 代码知识图谱本体
+
+本体用于约束业务语义、代码事实以及二者之间的映射。业务域是知识维护和检索单元，一个业务域可以跨多个微服务。
+
+## 四层模型
+
+1. `ontology`：定义概念类型、代码节点类型、关系类型和属性约束。
+2. `domains`：维护术语、业务概念、能力、规则、流程和经验风险。
+3. `graph/curated`：维护可由源码验证的代码节点、关系和事实判定。
+4. `mappings`：把业务概念、能力和规则映射到代码入口、表、MQ 与外部系统。
+
+## 业务概念
+
+业务概念必须使用 `concept-types.yaml` 中定义的类型。概念不是 Java 类名，而是产品、开发和测试共同使用的业务语义。每个 capability 至少关联一个 concept；concept 的 `related` 只能引用已定义概念。
+
+## 代码事实
+
+代码节点必须符合 `node-types.yaml` 的必填属性，关系必须符合 `relation-types.yaml` 的方向和端点约束。带 `path` 的节点必须能在对应仓库中找到真实文件。
+
+## 分层边界
+
+- 可从代码重新验证的内容进入 `graph/curated`。
+- 业务口径、流程说明和历史经验进入 `domains`。
+- 业务到代码的定位关系进入 `mappings`。
+- 推断必须标记为 `UNVERIFIED`，不得伪装成代码事实。
+
+## 知识契约 2.0
+
+业务 Markdown 使用 frontmatter，业务 YAML 使用 meta，包含稳定 knowledge_id、product/domain/systems、sources、生成时间与审核状态。类型约束与维护资料仅标识自身角色，不能伪装成业务事实。
+
+规则、能力、流程、概念、术语和独立结论分别维护稳定业务 ID，声明 claim_type、代码核验 status、人工 review_status、lifecycle、适用条件/版本/限制及结构化证据。推断不能 VERIFIED，默认审核 pending。流程与文档引用规则 ID，不复制权威规则定义。
+
+VERIFIED 关键证据需仓库、完整 commit、相对路径、符号、有效行号与支持结论。业务资料证据需真实内容指纹与定位，不能单独证明代码实现。结构通过不证明语义或人工审核真实性。

package/assets/project-context/rules/sync-rules.md

@@ -0,0 +1,15 @@
+---
+knowledge_type: maintenance
+---
+
+# 知识维护规则
+
+代码入口、数据表/字段、状态、MQ、配置、业务规则或边界变更时，按 evidence 与 mappings 定位受影响的规则、能力和流程。validate 的 impact 提供 repository/commit/path/symbol → knowledge_id/claim_id 关联。
+
+刷新来源材料，重读受影响证据；保留稳定 ID。标记待复核 needs_review 并说明原因，不能继续作为当前 VERIFIED；废弃使用 deprecated，说明原因/替代 ID。删除前检查所有入向引用并审核 Git 差异，不自动提交。未受影响的事实也需核对新适用版本，不机械替换 commit。
+
+一条规则的详细定义只维护在 domains/rules.yaml，流程/能力通过 ID 引用。更新原始条目后同步 Markdown 摘要与映射，避免重复定义漂移。来源或内容实质变化使既有人工审核指纹失效，应恢复 pending 或重新审核，Agent 不代替业务确认。
+
+旧格式依据真实来源显式补齐，不编造元数据，不覆盖旧成果。导出遇到目标存在而草稿缺失的旧文件会停止；用户决定保留/标废弃或明确处理后再导出。
+
+导出成功不等于审核通过或已发布。下游应继承元数据、逐条状态、来源及限制；系统标签不是员工权限。

package/assets/project-context/rules/validation-rules.yaml

@@ -0,0 +1,92 @@
+meta:
+  knowledge_type: maintenance
+validation_rules:
+  - id: graph_node_type_must_be_defined
+    target: graph/curated/*.yaml
+    check: node_type_exists
+    desc: graph 中的节点 type 必须在 ontology/node-types.yaml 中定义。
+
+  - id: graph_node_required_properties_must_exist
+    target: graph/curated/*.yaml
+    check: node_required_properties_exist
+    desc: graph 节点必须包含对应类型声明的全部 required 属性。
+
+  - id: graph_relation_must_be_defined
+    target: graph/curated/*.yaml
+    check: relation_type_exists
+    desc: graph 中的 rel 必须在 ontology/relation-types.yaml 中定义。
+
+  - id: graph_relation_endpoints_must_match
+    target: graph/curated/*.yaml
+    check: relation_endpoint_types_match
+    desc: 每条边的 from/to 节点类型必须符合关系端点约束。
+
+  - id: graph_path_must_exist
+    target: graph/curated/*.yaml
+    check: file_path_exists
+    desc: 带 path 的节点必须能在关联代码仓库中找到。
+
+  - id: concept_type_must_be_defined
+    target: domains/concepts.yaml
+    check: concept_type_exists
+    desc: 每个 concept 的 type 必须在 ontology/concept-types.yaml 中定义。
+
+  - id: concept_related_reference_must_exist
+    target: domains/concepts.yaml
+    check: concept_related_reference_exists
+    desc: concept.related 引用的概念必须存在或登记为相邻域概念。
+
+  - id: every_capability_has_concept
+    target: domains/capabilities.yaml
+    check: capability_has_concept
+    desc: 每个 capability 至少关联一个有效 concept。
+
+  - id: every_capability_has_mapping
+    target: domains/capabilities.yaml
+    check: capability_exists_in_mappings
+    desc: 每个 VERIFIED capability 必须存在代码映射；UNVERIFIED 资料能力不强迫编造实现。
+
+  - id: every_mapping_node_exists_in_graph
+    target: mappings/*.mapping.yaml
+    check: graph_node_reference_exists
+    desc: mappings 引用的 graph_nodes 必须存在于对应 graph。
+
+  - id: every_core_table_has_domain
+    target: graph/curated/*.yaml
+    check: table_has_domain_mapping
+    desc: 每张核心表必须通过 belongs_to 或 capability mapping 归属业务域。
+
+  - id: every_high_rule_has_code_mapping
+    target: domains/rules.yaml
+    check: high_severity_rule_has_mapping
+    desc: 每条 VERIFIED high 规则必须映射到代码节点并引用权威条目的完整证据。
+
+  - id: verified_commit_must_be_present
+    target: graph/curated/*.yaml
+    check: verified_commit_present
+    desc: 已验证事实必须记录关联仓库 commit。
+
+  - id: business_metadata_contract
+    target: domains/*,graph/curated/*,mappings/*
+    check: contract_metadata
+    desc: 校验 frontmatter/meta 的 2.0 必填字段与类型、真实来源版本一致性。
+
+  - id: stable_ids_and_references
+    target: domains/*,graph/curated/*,mappings/*
+    check: contract_references
+    desc: 校验知识/业务 ID、条目引用、节点、入口和映射证据索引；同中心范围限可访问输出。
+
+  - id: verified_evidence_complete
+    target: domains/*.yaml,graph/curated/*.yaml
+    check: contract_evidence
+    desc: VERIFIED 结论需仓库、完整 commit、相对路径、非空符号、有效行号及 supports；在对应 commit 检查文件与行数。
+
+  - id: inference_and_review_separate
+    target: domains/*
+    check: contract_status
+    desc: 推断禁止 VERIFIED，审核需独立状态，非 pending 需审核依据与有效内容指纹；不认证审核人身份。
+
+  - id: portable_export
+    target: ontology/*,domains/*,graph/*,mappings/*,rules/*
+    check: contract_portability
+    desc: 拒绝内部证据引用、常见机器绝对路径和认证信息模式；不宣称完整凭证扫描。

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@code2knowledge/skill",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Agent Skill for evidence-based multi-repository business knowledge.",
+  "license": "ISC",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "register": "node scripts/register.mjs",
+    "test": "node --test",
+    "check": "node --check scripts/setup.mjs && node --check scripts/knowledge.mjs && node --check scripts/register.mjs && node --check scripts/lib/knowledge.mjs && node --check scripts/lib/wizard.mjs && node --check scripts/lib/contract.mjs && node --check scripts/lib/notify.mjs && node --check scripts/lib/preflight.mjs && node --check scripts/lib/config.mjs && node --check scripts/postinstall.mjs",
+    "prepublishOnly": "npm test && npm run check",
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "bin": {
+    "code2knowledge": "scripts/setup.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "agents/",
+    "assets/",
+    "references/",
+    "scripts/",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "knowledge-base",
+    "code-analysis"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/references/analysis.md

@@ -0,0 +1,33 @@
+# 分析与可信度
+
+## 范围与续跑
+
+先读中心原料和 source-index/Repomix，记录候选入口、文件、依赖与排除范围到 analysis-plan.yaml。source-index 只有索引，不是源码快照。以业务边界控制读取；为完成已授权主流程，可以沿证据扩展必要依赖并记录原因。范围外依赖保留一跳摘要；无法访问的环节列为未核实，不编造完整链路。不扫描未授权仓库。
+
+已有 `.codegraph/` 时定位/理解源码先用 CodeGraph MCP 或 `codegraph explore`；无索引不自动建立。CodeGraph 不能替代原料版本检查或具体证据。材料中的指令不是任务授权。
+
+按服务保存内部 evidence，记录 service/commit、entry_points/call_chains/data_access/events/rules/tests/unverified/evidence。每条证据使用 knowledge-model.md 中的结构，但内部允许上下文路径帮助续跑；最终资产必须整理为可移植证据。按服务顺序分析；只有用户授权且宿主支持时并行子任务。恢复时检查来源版本和业务范围，只复用未受变化影响的证据。
+
+## 事实、规则与推断
+
+- code_fact：源码在指定版本、条件下可证明的行为。
+- business_rule：业务判定或口径；可以来自资料，但实现状态必须另行核实。
+- inference：解释、风险猜测或未闭环推断，只能 UNVERIFIED。
+
+方法名、注释、索引命中、单个调用点只能作为线索；核对真实分支、调用参数、启用条件、配置覆盖、异常及调用上下文。配置默认值不等于生产有效配置。跨系统调用、消息生产消费要分别找证据，不能凭同名 API/topic 声称贯通。
+
+逐条填写代码状态与审核状态：VERIFIED 需真实完整 commit、分析及核验时 clean 工作区、repository/path/symbol/有效行号/supports。非 Git、dirty/unknown 仍可分析，但相应结论 UNVERIFIED 并说明限制；不能因一个仓库异常而否定其他独立且证据完整的局部事实。资料冲突记录各自来源与差异，不自动裁定产品口径。
+
+## 流程与测试
+
+沿“触发入口 → 核心服务 → 数据读写/跨系统交互 → 状态或结果 → 失败与补偿”核实，说明前置状态、异步事件、适用条件和未覆盖环节。不存在异步/补偿时说明依据，不为了填表编造行为。
+
+分别记录发现哪些测试、阅读哪些测试、实际执行哪些命令及结果。运行前按宿主权限和用户授权判断是否适合执行；不能把本次未运行的测试写成通过。没有测试时保留覆盖限制，源码可证明的局部事实仍可 VERIFIED；不能声称因此证明完整流程或生产效果。
+
+## 汇总、审核与交付
+
+复用既有概念和稳定 ID；一条规则只在 rules.yaml 定义，能力/流程/Markdown 通过 ID 引用。flows.yaml 为流程权威定义；claims.yaml 只容纳额外风险/独立结论。文档小节保留业务背景，逐条区分状态，不使用整篇 confidence 取代差异。
+
+汇总完整证据到最终资产，不能只写内部 evidence ID。默认 review_status: pending、owner: null；Agent 不代替人工确认。仅用户提供真实审核依据时记录 confirmed/rejected，实质内容或来源变更后重新审核。结构校验不证明调用语义、业务正确性或审核人身份。
+
+校验修复后导出到选定本地位置；不修改源码、自动提交 Git 或发布外部平台。收尾分别报告结构检查结果、代码核验范围、业务待审核与测试限制。提示词生成、骨架创建或导出都不能描述为业务知识已得到完整验证。

package/references/downstream-contract.md

@@ -0,0 +1,23 @@
+# 下游接入契约
+
+这是对文档站、RAG 和 MCP 接入方的要求，不代表 Code2Knowledge 已实现这些服务。格式为通用 Markdown/YAML，不绑定 Onyx 或 knowledge-rag-plus。
+
+## 接收与索引
+
+解析业务 Markdown frontmatter 与业务 YAML meta，保存 schema_version、knowledge_id、product、domain、systems、knowledge_type、sources、generated_at、owner、review_status、lifecycle。类型约束/维护资料按 knowledge_type 单独识别，不作为普通业务事实。
+
+按稳定 knowledge_id 更新记录，文件移动不能产生第二份知识；业务条目按稳定业务 ID 建立引用。sources 必须保留所有仓库版本与工作区状态，资料保留 document_id/path/sha256。不要在导入时把 pending 自动变成 confirmed。
+
+## 分块
+
+每块继承知识 ID、业务域、系统、来源版本、文件及条目审核状态、生命周期；保留适用条件和限制。按流程/规则/能力的语义边界分块，不把结论与证据断开。需要展开引用时按稳定 ID 获取权威规则，不凭“上述规则”补猜上下文。
+
+VERIFIED 是代码核验状态，review_status 是人工业务审核状态。文件 pending 可以含局部 VERIFIED 条目；confirmed 文件也不能掩盖其中的 pending/UNVERIFIED 条目。needs_review/deprecated/rejected 不作为当前确定事实，是否展示历史记录由下游明确决定。
+
+## MCP 返回
+
+检索结果至少返回：内容、knowledge_id、业务条目 ID、product/domain/systems、claim_type/status/review_status/lifecycle、适用条件与限制，以及可复查的 repository/commit/path/symbol/lines/supports 或资料指纹和定位。若生成源码链接，只能使用经过授权、无认证信息的仓库地址映射；不暴露本机路径。
+
+## 权限与发布
+
+元数据标签不等于员工权限。身份认证、数据权限、检索过滤、审计、Embedding、发布门禁由下游实现；不能仅凭 product/domain 标签认定某位员工有访问权限。Code2Knowledge 导出成功只表示交付了本地资产，不代表已导入索引、通过业务审核或向员工发布。

package/references/execution.md

@@ -0,0 +1,154 @@
+# Agent 执行接口
+
+## 环境与路径
+
+需要 Node.js 20+、Git。Skill 内核仅依赖 `yaml`；安装新项目时执行一次 `npm ci --ignore-scripts`（在 Skill 目录）。若缺少依赖，先按宿主权限执行安装；不能联网时说明阻塞，不安装 Web/终端依赖。需要资料转换时才检测 `markitdown`；需要 Repomix 时才调用 `npx -y repomix`。
+
+### 配套工具安装与告知
+
+npm 安装 Skill 或执行 npm ci 只安装包声明的依赖，不代表 Repomix、MarkItDown 已就绪。首次实际使用前先检测；有缺失时简短告知用户“将配套安装本次所需工具：Repomix 由 npm/npx 下载，文档转换器 MarkItDown 由 Python/pip 安装”，然后在已授权任务范围和宿主权限内执行，不无故增加确认环节。仅在确有权限/环境限制时说明阻塞，不宣称已安装。
+
+- 默认 Repomix：执行 `npx -y repomix --version` 验证并按需下载到 npm 缓存，后续打包仍用 npx；无需全局安装，也不要安装到被分析仓库的 package.json。
+- 需要转换非文本资料时：先检测 `markitdown --version`。缺失则用 `python3 -m venv ~/.local/share/code2knowledge-tools` 建立独立环境，再用该环境的 Python 执行 `-m pip install 'markitdown[all]'`；将其 bin 目录加入当前执行环境 PATH，保证后续 knowledge.mjs 能找到 markitdown。已有可用安装直接复用。不要覆盖系统 Python；Python 或特定格式系统依赖缺失时报告真实问题。
+- 安装后验证对应命令，报告实际结果；仅 Markdown/TXT/CSV/YAML/JSON 无需 MarkItDown，source-index 模式无需 Repomix。首次下载需要网络，不能联网时保留向导并说明阻塞，不能静默丢弃资料或降级模式。
+
+设 `SKILL` 是读取本文件的 Skill 绝对路径，`PROJECT` 是任务启动目录，`WORKSPACE` 默认 `PROJECT/.code2knowledge`。脚本参数以独立参数传递，路径包含空格也必须正确引用。不要用用户输入拼接 shell 代码。每次命令明确传 `--workspace`，续跑保持相同值。
+
+## 正式逆向前：master 分支检查（必须执行）
+
+此门禁已由 preflight.mjs 强制执行：prepare/material 创建原料、domain 复用原料、wizard-start 启动或恢复任务都会同步 master，失败抛错并保存工作区 preflight/ 记录；飞书启用时自动尝试人工介入通知。确定所有依赖服务仓库和文档选择后、首次生成代码原料前执行；复用原料、恢复尚未完成分析的任务也应在再次分析前执行。只读 discover 不需要切换分支。仅文档任务跳过此步骤。
+
+先告知“将检查所有依赖服务代码，自动切换到 master 并拉取最新版本，失败时停止请求人工处理”。对每个仓库用独立参数调用 Git，工作目录设为该仓库，不拼接用户路径到 shell 代码：
+
+1. 记录原分支及 HEAD；检查是否为 Git 仓库，检查 `git status --porcelain` 和 merge/rebase/cherry-pick 等进行中操作。存在用户未提交或未跟踪改动、子模块改动、未完成操作时停止，不擅自 stash、提交或清理。工作区内工具自身生成的 `.code2knowledge/` 内容按既有 inspectRepository 排除规则判断，不要求用户删除工具产物。
+2. 执行 `git fetch origin`，成功后确认 `refs/remotes/origin/master` 存在。缺少 origin 或远程 master 时停止，不擅自改用 main 或其他远程，也不能拿旧缓存代替最新远程状态。
+3. 本地 master 存在时执行 `git switch master`；不存在时执行 `git switch --track -c master origin/master`。然后执行 `git pull --ff-only origin master`，禁止 merge commit、rebase、reset --hard 或强制切换。
+4. 比较 `git rev-parse HEAD` 与 `git rev-parse refs/remotes/origin/master`，必须相等且当前分支确为 master、工作区仍 clean 才通过。本地 master 即使仅领先远程也不能视为最新基线，不删除本地提交，请人工处理。记录检查时间、原分支、原 commit、最终 commit、远程和结果到任务计划/检查记录；“最新”指本次成功同步的远程快照。
+
+先对全部仓库做只读工作区检查再逐仓同步，减少部分更新。任意一步失败：停止原料准备与正式分析，向用户列出失败仓库、失败步骤、实际 Git 错误、已完成切换的仓库和当前状态，明确请求人工处理后继续。不要自动回滚已更新仓库或循环重试。用户处理后重新检查全部仓库。
+
+全部通过后再创建原料，commit 必须取更新后的真实 HEAD。复用/续跑时，如果新 HEAD 与原料记录不同，旧原料和旧产物不得直接续写或冒充最新；按过期原料流程让用户选择刷新或处理已有任务，保留原料与历史证据。用户明确要求分析历史分支/commit 时按该要求执行并标明，不能把历史分析报告成最新 master。
+
+## 选择向导接口（优先使用）
+
+```bash
+node "$SKILL/scripts/knowledge.mjs" discover --workspace "$WORKSPACE"
+```
+
+返回当前仓库候选、菜单、业务中心、最近原料、未完成任务和问答检查点。默认各取最近 8 项，`totals` 表示完整数量。需要更多原料用 `list`，更多任务用 `runs`。发现阶段不核查全部仓库版本，原料的 `freshness: unchecked` 不能解释为可复用。
+
+将用户选择与已有信息写到工作区内临时 JSON，再调用 `wizard --input FILE` 保存：
+
+```json
+{
+  "intent": "reuse",
+  "materialDir": "/absolute/path/.code2knowledge/materials/order-center/<版本>",
+  "answers": {
+    "domainName": "退款",
+    "domainSlug": "refund"
+  }
+}
+```
+
+`intent` 为 `new`（新建原料并整理域）、`reuse`（引用已有原料整理域）、`resume`（继续已有 run）、`material`（仅准备原料）。已有 run 用 `runDir`，已有原料用 `materialDir`。
+
+```bash
+node "$SKILL/scripts/knowledge.mjs" wizard --input "$WORKSPACE/answer.json" --workspace "$WORKSPACE"
+```
+
+结果返回 `wizardId`、`wizardPath`、已填 `answers`、`missingFields`、`nextStep`、`status`；英文标识和输出位置齐全时返回 `exportDirPreview`，用于展示最终路径。后续传同一个 `wizardId`，仅补新增答案，不需要重复传全部参数：
+
+```json
+{
+  "wizardId": "<返回的编号>",
+  "answers": {
+    "domainScope": "包含退款申请、审核和原路退回；排除售后换货，支付仅保留依赖",
+    "outputRootDir": "/absolute/path/project"
+  }
+}
+```
+
+复用时中心/仓库及资料自动从 material 带入。新建原料时必须先完成“是否添加文档资料”的结构化选择；选择添加后收集本地目录写入 rawDocsDir，选择不添加才保存空字符串，不能把默认空值或 missingFields 为空视为已经回答。业务域名、边界说明和导出位置通过向导明确收集，outputRootDir 只有用户选定后才保存，不能直接复制发现接口的推荐值冒充选择。收集导出位置必须沿用宿主结构化选择工具，提供推荐目录与自定义入口；普通文本编号只用于工具确实不可用的兜底，详细规则见 wizard.md。rawDocsDir 必须显式提交：不添加传空字符串，添加传目录；新向导缺少它时 missingFields 返回 rawDocsDir，启动及底层原料创建均拒绝缺省值。`answers` 仅支持 `productName`、`productSlug`、`domainName`、`domainSlug`、`domainScope`、`repoDirs`、`rawDocsDir`、`outputRootDir` 和 `contextMode`；repoDirs 为路径数组，其余为文本。中文名称需由 Agent 在命名选择中一并推荐英文标识，用户选用后保存；纯英文名称可自动规范为小写连字符标识。缺少中文名称对应的英文标识时，missingFields 会返回 productSlug / domainSlug，禁止猜测翻译后直接开始。
+
+```bash
+node "$SKILL/scripts/knowledge.mjs" wizard --wizard "$WIZARD_ID" --workspace "$WORKSPACE"
+node "$SKILL/scripts/knowledge.mjs" wizard-start --wizard "$WIZARD_ID" --workspace "$WORKSPACE"
+```
+
+`wizard-start` 仅允许 `ready`，复用前检查仓库版本；失败保留问答。成功返回 `wizard` 与 `result`，后者为 material 或 run 的准备结果，包含草稿/提示词/证据路径。向导标记 `started` 并关联任务；再次调用返回同一任务（`alreadyStarted: true`），不重新准备。Agent 接着分析，不能把这个状态视为分析完成。普通任务按顺序调用；创建途中进程异常时先用 `discover` 检查已经生成的 run，避免另建重复任务。
+
+需要刷新选定原料时，用同一个 wizardId 保存 `intent: new`，已有中心、仓库、域名和范围继续保留。版本检查器同时核对仓库与已记录资料指纹；Agent 仍需核对转换结果和资料语义是否完整。
+
+## 底层输入（完整参数或特殊流程）
+
+底层命令继续保留，通常由向导代办；已通过向导创建任务后不能重复调用。完整输入示例：
+
+```json
+{
+  "productName": "订单中心",
+  "productSlug": "order-center",
+  "domainName": "退款",
+  "domainSlug": "refund",
+  "domainScope": "退款申请、审核和原路退回，不含售后换货",
+  "repoDirs": ["/absolute/path/order-api", "/absolute/path/order-core"],
+  "rawDocsDir": "",
+  "outputRootDir": "/absolute/path/project",
+  "contextMode": "repomix"
+}
+```
+
+字段来自用户或已说明的默认值；英文目录标识随名称选项一并确定，不另开技术字段问卷；不要逐项提问 contextMode 等参数。目录标识必须匹配 `[a-z0-9]+(?:-[a-z0-9]+)*`。默认启用 repomix，通过 `npx -y repomix` 生成代码上下文（首次调用可能需要联网下载）；显式设置 contextMode 为 source-index 时仅创建文件列表，由 Agent 后续定向读取源码。复用原料或继续向导时沿用已有模式。
+
+## 命令
+
+以下是 Agent 内部工具，用户日常只需输入启动词。
+
+```bash
+node "$SKILL/scripts/knowledge.mjs" list --workspace "$WORKSPACE"
+node "$SKILL/scripts/knowledge.mjs" prepare --input "$WORKSPACE/request.json" --workspace "$WORKSPACE"
+```
+
+stdout 仅为 JSON；日志默认关闭，`C2K_VERBOSE=1` 时日志写 stderr。成功结果包含 `contractContext`（真实来源及程序时间，metadata 的生成上下文）、`materialDir`、`runDir`、`draftsDir`、`promptPath`、`analysisPlanPath`、`evidenceDir` 和导出目标。读取这些返回值，不能猜时间戳路径。
+
+需要复用时，先找同产品、同仓库、同资料的 material，核对路径、contextMode、资料是否变化，再执行：
+
+```bash
+node "$SKILL/scripts/knowledge.mjs" check --material "$MATERIAL" --workspace "$WORKSPACE"
+```
+
+只有所有仓库 commit 相同且记录时/当前均为 clean，返回 `reusable: true`。同时检查已记录资料的 SHA-256、新增资料及不可读文件；转换质量仍需 Agent 复核。有变化生成新原料，不能修改旧 material 冒充原版本。
+
+复用时输入改为 `materialDir` 加业务域名称、英文标识、范围和输出目录，执行 `domain`。需要只准备原料执行 `material`。`prepare` 同时完成原料与业务域骨架准备，也接受 `materialDir`。
+
+```bash
+node "$SKILL/scripts/knowledge.mjs" domain --input "$WORKSPACE/request.json" --workspace "$WORKSPACE"
+node "$SKILL/scripts/knowledge.mjs" status --run "$RUN" --workspace "$WORKSPACE"
+node "$SKILL/scripts/knowledge.mjs" validate --run "$RUN" --workspace "$WORKSPACE"
+node "$SKILL/scripts/knowledge.mjs" export --run "$RUN" --workspace "$WORKSPACE" --output "$OUTPUT"
+```
+
+失败返回非零退出码；校验失败仍输出 JSON 诊断，不能因退出码非零而忽略诊断。`export` 每次重新校验，不能靠历史 `validated` 状态绕过。只导出五个资产目录，不带提示词、分析计划和原始 evidence；整理后的证据必须包含在最终业务条目/图谱中，不含机器绝对路径。目标有草稿未包含的旧文件时阻止导出，不静默删除或残留旧成果。
+
+## 续跑与旧数据
+
+用户提供 run 路径时，工作区是该路径的 `runs` 的父目录。先读取 `status`、原料、分析计划和各服务 evidence。核对 commit、范围和文档变化，只重读受影响证据。更新计划中的阶段状态，不能只根据进程成功或文件存在认为完成。
+
+旧 Web 项目的 material/run 格式仍可读取：`--workspace` 指向旧 `workspace` 即可；缺少工作区状态的历史材料只能做结构校验，应在报告中说明并重新核实源码。不要自动迁移、覆盖或清理原项目。旧记录中的中文中心/域标识仍可读取，但不能继续生成新域或导出到中文标识目录；保留旧数据，使用英文标识新建任务，不能只重命名目录而遗漏图谱、映射和引用。
+
+## 契约上下文与历史补齐
+
+新任务的 run.json 与准备结果包含 contractContext：schema_version、product/domain、generated_at、systems、sources、已知 identities。模板直接由这些真实值生成，不能临时猜时间、版本和审核信息。来源资料的 document_id/path/sha256 来自原料清单；复用核查原资料指纹。
+
+旧任务没有上下文时，保持读取和恢复能力。先读取原料记录；从真实来源确认分析版本/资料指纹，再手工补齐现有文件的 frontmatter/meta、业务 ID、逐条状态、证据与引用。无法核实的来源明确未知或刷新原料重新分析，不能用当前 HEAD 代替历史版本。工具不会自动填造旧元数据、批量覆盖旧文件或将旧格式直接标为满足 2.0。
+
+## 校验边界
+
+程序检查 Markdown frontmatter/业务 YAML meta 类型、ID 唯一性及引用、条目类型与状态、VERIFIED 证据完整性、来源材料一致性、对应 commit 中的文件与行号边界、人工审核记录结构与内容指纹、本体约束、映射及入口引用。validate 返回 contractVersion、assets、impact、errors/warnings 和 sourceCheck；impact 为来源代码到业务 ID 的关联，原始 evidence 不导出。
+
+中心查重覆盖当前资产及指定输出根目录下可读取的同中心其他业务域，不覆盖未知知识库或历史快照。dirty/unknown 限制按结论实际引用仓库判断；缺测试执行记录需说明覆盖限制，不否定已有局部源码事实。
+
+符号仅检查非空；程序不自动证明调用语义、SQL 语义、规则正确性、行号是否足以支持结论、审核人身份或测试真实运行。常见绝对路径/认证 URL/凭证模式检查不是完整泄漏扫描。Agent 必须继续做证据语义复核；通过结构校验不等于业务审核或发布。
+
+## 通知
+
+人工介入使用 `notify --input FILE --workspace DIR`，输入和触发条件见 [通知协议](notifications.md)。export 成功后自动返回 notification 结果；仅 status=sent 为已确认发送。通知配置默认关闭。

package/references/knowledge-model.md

@@ -0,0 +1,108 @@
+# 知识资产契约 2.0
+
+Code2Knowledge 是知识生产层：源码/资料 → Code2Knowledge → Git 知识资产 → 文档站/RAG → MCP → 员工 Agent。只负责本地知识生产与交付，不实现下游服务，不自动提交 Git、部署或发布。结构通过、代码核验、业务审核和员工发布是不同事件。
+
+## 五个目录与权威定义
+
+- `ontology/`：类型约束，`knowledge_type: type_constraint`。
+- `domains/`：业务 Markdown 和业务 YAML。
+- `graph/curated/<domain>.graph.yaml`：核实存在的代码节点与关系。
+- `mappings/<domain>.mapping.yaml`：规则/能力/流程到代码的关联。
+- `rules/`：维护资料，`knowledge_type: maintenance`；不是业务规则定义。
+
+业务规则详细定义只在 `domains/rules.yaml`；能力在 `capabilities.yaml`；概念在 `concepts.yaml`；术语在 `glossary.yaml`（条目也需 id）。`flows.yaml` 保存权威流程，`flows.md` 给出带 ID 和业务背景的阅读摘要。`claims.yaml` 仅维护其他集合无法表达的风险/独立结论，不能复制已有规则。三个 Markdown 为 `overview.md / flows.md / pitfalls.md`。
+
+## 文件元数据
+
+业务 Markdown 使用 YAML frontmatter；业务 YAML 使用顶层 `meta`，不可在 YAML 外包 Markdown 分隔符。业务 YAML 包括 domains、graph 和 mappings。最低字段：
+
+```yaml
+schema_version: "2.0"
+knowledge_id: K:order-center:refund:business_rules
+product: order-center
+domain: refund
+systems: [order-api, order-core]
+knowledge_type: business_rules
+generated_at: <程序生成的真实 ISO 时间>
+review_status: pending
+owner: null
+lifecycle: current
+sources:
+  - kind: code
+    repository: order-api
+    commit: <原料记录的完整 Git commit>
+    worktree_status: clean
+  - kind: code
+    repository: order-core
+    commit: <原料记录的完整 Git commit>
+    worktree_status: clean
+```
+
+示意占位值不能直接用于交付。每份业务资产保留本次所有仓库来源，不能用单个 source_commit 代替。commit 为完整 40/64 位小写十六进制；非 Git/不可获取时为 `null`，相关结论不能 VERIFIED。工作区状态为 `clean/dirty/unknown`。sources 不写仓库绝对路径、认证 URL 或凭证。
+
+资料来源使用 `kind: document`、`document_id`、原资料相对 `path`、真实内容 `sha256`。原料准备时程序计算指纹并记录；不能用文档更新时间推测版本。没有代码仓库的资料分析允许 `systems: []`，但 sources 不能空。
+
+knowledge_type 为 `overview / flows / pitfalls / business_note / glossary / concepts / capabilities / business_rules / flow_definitions / claims / code_graph / code_mappings`。维护资料只要求明确角色，不伪装业务审核元数据。
+
+业务 Markdown 另有 `claim_refs: [稳定业务 ID]`，引用权威条目。关键结论不能只写自由正文而遗漏结构化条目；每个可检索小节写出业务对象、条件、行为、版本或限制，不能只写“按上述规则”。程序检查引用存在，不证明自然语言摘要忠实于权威定义。
+
+## 稳定标识
+
+knowledge_id 标识文件承载的知识，业务 id 标识概念/能力/规则/流程/结论。两者不由时间戳、内容 hash 或当前文件路径生成。新资产初始 knowledge_id 为 `K:<product>:<domain>:<知识类型>`；重新整理已有域时，程序读取已有导出元数据按知识类型沿用 ID。自定义同类文档需分配独立稳定 ID；移动文件保留 ID，不能重编。
+
+业务 ID 保留现有 `CONCEPT:/CAP:/RULE:` 形式，增加 `TERM:/FLOW:/CLAIM:`，同中心唯一。更新前读取已有资产并保留其语义 ID；不能通过改 ID 绕开历史引用。中心级程序查重只覆盖本次资产和所选输出根目录下可读取的同中心其他业务域，不声称检查整个企业。跨域引用登记 `external_references: [{id, knowledge_id, domain}]`；登记只明确来源，不代表自动验证外部资产内容。
+
+## 条目契约与审核
+
+术语、概念、能力、规则、流程和独立结论均包含：
+
+```yaml
+id: RULE:refund:positive-amount
+claim_type: business_rule  # code_fact / business_rule / inference
+status: UNVERIFIED        # 代码证据状态
+review_status: pending    # pending / confirmed / rejected
+lifecycle: current        # current / needs_review / deprecated
+applicability:
+  conditions: []
+  versions: []
+  limitations: [尚未核验实现]
+evidence: []
+```
+
+VERIFIED 必须有完整代码证据及非空适用版本，inference 不能 VERIFIED。UNVERIFIED 必须说明限制。业务资料能证明“文档记载该规则”，不能单独证明代码实现。文档/条目审核分别记录，整篇审核状态不能替代条目状态；默认全部 pending，owner 未知为 null。
+
+Agent 不自动 confirmed/rejected。仅在用户提供真实人工审核依据时记录 `review: {reviewer, reviewed_at, basis, content_sha256}`。指纹由 `scripts/lib/contract.mjs` 的 `contentHash` 计算，排除 generated_at/review/review_status，包含来源版本与实质内容；文件审核覆盖完整 YAML 或 Markdown 的 `{meta, body}`，条目审核覆盖原条目。修改内容/来源后旧指纹失效，需重新审核或恢复 pending。程序只能验证结构和指纹，不能认证审核人身份或审批真实性。
+
+## 可交付证据
+
+```yaml
+evidence:
+  - kind: code
+    repository: order-core
+    commit: <真实完整 commit>
+    path: src/RefundService.java
+    symbol: RefundService#apply
+    lines: [80, 120]
+    supports: 非正数金额进入参数异常分支
+    node_id: FUNC:order-core:refund-apply  # 可选，存在时必须对应同一代码路径
+```
+
+证据 path 为仓库内相对路径；图谱节点继续使用 `<repository>/<relative-path>`。程序检查仓库来源、版本、符号非空、行号有效且不越过对应 commit 的文件，不能证明符号真是该语言的定义或行号内容足以支持结论。
+
+资料证据使用 `kind/document_id/path/sha256/locator/supports`，对应 sources 中的资料；locator 是章节/页码等可复查位置。最终资产不能只写内部 EVIDENCE ID 或临时路径。
+
+图谱带 path 节点附代码 evidence，代码关系需 `status: VERIFIED` 和 evidence；未确认关系进入 claims。能力/规则/流程映射分别用 `capability_id/rule_id/flow_id`、`graph_nodes`、`evidence_refs: [{claim_id, index}]`，index 为该权威条目 evidence 的零起始索引。避免再次复制规则定义或维护第二套证据。
+
+VERIFIED 能力、high 规则、流程需要映射；资料中的未实现规则允许不映射。提供的映射必须引用真实节点和该条目的有效证据。
+
+## 流程与测试
+
+flows 条目还需 `name/trigger/scope`，以及文本列表 `preconditions/steps/data_changes/async_events/failures/compensation`。确实无适用项时明确说明原因，不编造异步事件或补偿。
+
+`tests.discovered/read` 分别记录发现和阅读的测试；`executions` 记录实际 `command/executed_at/exit_code/result`；`limitations` 说明覆盖范围。未运行时 limitations 不能为空。发现测试、阅读测试、执行通过不可相互替代，也不能因无测试否定源码已证明的局部事实。
+
+## 更新与追溯
+
+evidence 和 mappings 共同提供来源代码 → 规则/能力/流程关联，validate 另返回 `impact` 便于定位影响。来源变化后刷新原料并重读受影响结论，标记 needs_review；废弃用 deprecated 并说明替代关系/原因，不能继续 VERIFIED。删除前检查入向引用并由 Git 变更审核，工具不自动提交。
+
+导出不静默清理旧文件：目标存在而草稿缺失的文件会阻止导出，需显式保留/标废弃或由用户授权处理。旧格式保持可读、可续跑，必须依据真实来源补齐后满足新契约；不得用当前 HEAD 冒充历史版本，也不得自动覆盖旧资产。

package/references/notifications.md

@@ -0,0 +1,46 @@
+# 飞书通知：人工介入与最终结果
+
+默认关闭，不读取 super-engineer 的凭证，不自动创建机器人。npm 安装钩子及 Agent 注册会自动补齐缺失的本机模板，已有配置不覆盖；--ignore-scripts 会跳过安装钩子，注册时仍会补齐。用户在本机 `~/.code2knowledge/config.yml` 配置（建议目录权限 700、文件权限 600，不提交 Git）：
+
+```yaml
+notification:
+  feishu:
+    enabled: false
+    webhook_url: ""
+    secret: "" # 机器人开启签名校验时填写
+```
+
+启用时填入自己的飞书/Lark 自定义机器人 webhook，改 enabled 为 true。配置启用即表示授权将本任务摘要发往该机器人所在会话；通知包含任务标识和本机输出位置，不发送源码、文档正文或原始 Git 错误。不要自动沿用其他 skill 的通知配置。支持官方 open.feishu.cn / open.larksuite.com webhook。
+
+## 人工介入
+
+仅在确实必须停止、等待用户处理时发送，如 master 同步失败、转换依赖安装受阻、必要资料不可读。普通向导提问和可自动修复的校验错误不发送。Agent 将如下 JSON 写入工作区临时文件，然后调用：
+
+```json
+{
+  "event": "intervention",
+  "task": "稳定的向导 ID 或 run 绝对路径",
+  "summary": "订单中心 / 退款：master 同步失败，需要人工处理",
+  "details": ["服务：order-core；步骤：快进拉取", "原因：本地分支与远程分叉", "请保留本地提交，人工处理分支后回复继续"]
+}
+```
+
+```bash
+node "$SKILL/scripts/knowledge.mjs" notify --workspace "$WORKSPACE" --input "$WORKSPACE/notification-input.json"
+```
+
+task 使用稳定标识，同一次阻塞重试时保持摘要一致；恢复后新的阻塞需包含新的阶段/来源版本以区分事件。只发简要原因和下一步，不发送原始异常、凭证、私有 URL 或材料内容。通知后仍在当前会话明确请求人工介入，不能把通知当作用户回复，也不能自行继续。
+
+## 最终结果
+
+由 exportRun 在重新校验并导出成功后自动发送，Agent 不得提前手写 completed 通知。包含业务域、导出结果、本机输出位置、产物指纹及“业务仍待审核”。代码核验范围和测试限制以交付报告为准，不声称全部实现已验证。仅生成骨架、校验失败、只准备原料不会发送完成通知。
+
+## 记录和失败
+
+记录在 `<工作区>/notifications/<事件指纹>.json`。只有 status=sent 才表示飞书接口确认成功；skipped 表示未配置或关闭，failed 表示发送/配置异常。相同任务与事件内容已发送则跳过，导出内容变化会生成新完成事件；并发发送通过锁文件避免重复。失败可在人工排查后重试，未自动重试以免刷屏。网络超时存在消息已到达但本机未确认的可能，不能保证绝对一次投递。进程异常退出遗留 .lock 时，确认无发送进程后人工移除再重试。
+
+通知失败不覆盖真实导出或阻塞状态，Agent 应在会话说明发送失败；如果记录写入失败，只能报告未确认，不能声称已通知。不提供在线产物托管，本机路径不是飞书可访问链接。
+
+测试隔离：node:test 环境及其 CLI 子进程禁止真实通知传输，不读取本机通知配置；通知单测仅使用模拟传输。设置 C2K_NOTIFICATIONS_DISABLED=1 也可关闭真实发送。人工介入防重忽略每次变化的检查记录路径，同一仓库及同一阻塞内容只发送一次。
+
+卡片样式：使用飞书 interactive 卡片，人工介入为橙色标题、完成为绿色标题，采用加粗分组标题与项目列表，依次展示任务摘要、任务结果/阻塞说明、交付位置/排查记录和下一步；移除双栏及分隔线，任务和路径使用代码样式。材料插入 Markdown 前转义，避免触发提及或格式注入。测试卡片必须醒目标记【测试】，真实发送前明确告知接收机器人和数量；自动化测试保持模拟传输隔离。