Initial commit: company-kb framework

- 完整的知识库框架（P0-P5 路线图） - 12篇治理文档 - 工具脚本（kb-init.sh, kb-lint-fm.py, feishu-sync.py, kb-bot） - 7个 Claude 命令 - 示例项目和测试项目（wanniu-l1） - 契约文件（meta/kb-contract.yaml） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-16 18:24:39 +08:00
commit 84f7950589
60 changed files with 4410 additions and 0 deletions
--- a/CONVENTIONS.md
+++ b/CONVENTIONS.md
@@ -0,0 +1,136 @@
+# CONVENTIONS · 录入宪法
+
+> 本文是知识库的录入规范。**type 集、字段必填矩阵、enum 取值的唯一机器可读真相源是 `meta/kb-contract.yaml`**——本文只做人读镜像与规约说明，不复述契约细节。任何冲突以契约文件为准。
+> 铁律：能让 AI 自动做的绝不让人做（丢资料是唯一强人工入口）；AI 永不擅自有损操作；AI 永不编造，无据即报 Gap。
+> **规则归属与修改**（谁能改本规范/契约/命令、怎么改）见 `docs/12-治理与规则维护.md`：物料全员录入，规则改动全员可提 PR、合入需 review。
+
+---
+
+## 1. Frontmatter Schema（人读镜像）
+
+每个知识页顶部是一段 YAML frontmatter。字段的必填性由 `meta/kb-contract.yaml` 的必填矩阵判定，`kb-lint-fm.py` 运行时读契约校验。下表为人读镜像：
+
+| 字段 | 必填 | 类型 | 说明 / AI 自动化 |
+|---|---|---|---|
+| `type` | ✅ **唯一硬必填** | string | 取值见 `kb-contract.yaml` 已激活 type；缺失只报不猜 |
+| `status` | ✅（默认 `seed`） | enum | `seed`/`developing`/`mature`；新建即 `seed`，AI 可自动填默认 |
+| `created` | ✅ | date | 内容产生时间；AI 从源推导或填今天 |
+| `ingested` | ✅ | date | 汇入时间；**AI 自动 = 今天** |
+| `source` | 外部摄入页 ✅ | enum | `飞书文档`/`飞书群`/`微信群`/`本地`/`NAS`/`会议`/`人工沉淀`/`AI编译`；采集器自动填 |
+| `source_link` | 外部摄入页 ✅ | string | 原始链接/绝对路径；采集器自动填 |
+| `title` | 建议 | string | **AI 自动 = H1 或文件名回填**（实际免手写） |
+| `description` | 可选 | string | ≤120 字摘要，供导航 |
+| `tags` | 可选 | list | kebab-case |
+| `timestamp` | 可选 | date | 信息最后有效期（判断过时） |
+| `author` | 可选 | string | 内容产生人 |
+| `related` | 可选 | list | `[[slug]]` wikilink 强边 |
+| `resource` | `metric` 型 ✅ | string | 底层资源稳定链接 |
+
+**派生必填规则**（写进契约，lint 据此判定）：
+- `type ∈ {doc, decision, conversation}` 且 `source` 为外部渠道 → `source` + `source_link` 升为必填。
+- `projects/*/_index.md`（`type: project`）豁免溯源字段。
+- 顶层 `README.md`/`CONVENTIONS.md`/`docs/*`/`assets/*` 免 frontmatter（仓库脚手架，非知识页）。
+- **人工必填压到最少**：绝大多数场景人只需拍板 `type`（采集器常可推断），其余由 CC 自动补齐。
+
+**注意**：不设 `updated` 字段——最后修改时间查 `git log`。
+
+**完整示例**（`projects/_example/decisions/` 下一页）：
+
+```markdown
+---
+type: decision
+title: "客户 A 报价采用阶梯定价而非一口价"
+description: 因客户预算分期到位，改用阶梯定价锁定长期合作，牺牲首单毛利。
+tags: [报价, 客户-A, 定价策略]
+timestamp: 2026-06-20
+source: 飞书群
+source_link: https://company.feishu.cn/im/xxxx?msg=99231
+author: 张三
+created: 2026-06-20
+ingested: 2026-06-24
+status: mature
+related:
+  - "[[project-clientA]]"
+---
+
+# 客户 A 报价采用阶梯定价而非一口价
+
+## 背景 / 决策 / 参与人·时间 / 溯源
+原始讨论见 source_link。
+```
+
+---
+
+## 2. Type 体系（引用契约）
+
+**唯一真相源 = `meta/kb-contract.yaml`**。核心集封闭；扩展 = 改契约 + 一次 PR（轻量登记）。
+
+核心 4 type（Day-1 激活，首个闭环即用）：`project` / `decision` / `conversation` / `doc`。
+预留 type（登记后按需激活）：`entity` / `concept` / `question` / `runbook` / `metric`。
+
+> lint 白名单 = 契约中「已激活 type」的并集，激活即放行。定义与目录归属见 `docs/04-架构.md` 与契约文件本身，此处不复述。
+
+**扩展流程**：新增 type = 在 `kb-contract.yaml` 的 `types` 数组登记（含 active/reserved 标记 + 必填规则）→ 建对应目录 → 一次 PR。禁止在脚本里硬编码 type。
+
+---
+
+## 3. 命名与路径规约
+
+- **项目代号**：英文或拼音，kebab-case，禁纯中文目录名（CC 会把中文编码为 `-` 导致 ID 碰撞）。例：`projects/clientA/`、`projects/power-bid/`。
+- **文件名**：kebab-case，语义化，无空格。例：`stepped-pricing-decision.md`。
+- **项目门户**：每个项目目录必有 `_index.md`（`type: project`）作为导航锚点。
+- **附件**：原始二进制/图片放各项目 `assets/`，免 frontmatter。
+- **目录布局**必须与 `docs/04-架构.md` 一致，`kb-init.sh` 据此建骨架。
+
+---
+
+## 4. Wikilink 规约
+
+- 用 `[[slug]]` 建立页间强边，写入 frontmatter 的 `related` 字段或正文。
+- slug 用目标文件名（不含 `.md`）或项目代号，例 `[[project-clientA]]`。
+- **强边（related）**：语义强关联（同一决策链、同一客户、上下游依赖）。
+- 正文内引用其他页用行内 `[[slug]]`，Obsidian 图谱据此渲染。
+- AI 录入时**自动建 wikilink**：识别页面提及的已有实体/项目/决策并挂链。
+
+---
+
+## 5. 摄入规则
+
+1. **Delta Check 去重**：录入前对内容算 hash，比对 `meta/ingest-manifest.json` 台账，已存在则跳过或提示合并，不重复落盘。
+2. **落原文**：外部文档原文进 `projects/*/docs/`（或 `assets/`），frontmatter 记 `source` + `source_link`。
+3. **抽关键发现**：AI 从原文抽要点，写成合规知识页（`decision`/`conversation` 等）。
+4. **frontmatter 自动补齐**：AI 自动填 `title`（H1/文件名回填）、`ingested`（今天）、`status`（`seed`）、可推导的 `created`/`source`。
+5. **矛盾不静默覆盖**：新内容与已有页冲突时，**MVP 用简单标注挂起**（正文加矛盾标记），交人拍板；**不做自动 status 降级状态机**。
+6. **凭据不入库**：`feishu-pull.py` 等采集器的凭据走环境变量。
+7. **MVP 一次录入产出结构化 markdown**，不做 8-15 页 wiki 编译（P4 才编译）。
+
+---
+
+## 6. Lint 规则
+
+`tools/kb-lint-fm.py` 用 **PyYAML 解析** frontmatter，**读 `meta/kb-contract.yaml`** 判定，退出码非 0 供 CC 判定。检查项：
+
+| 检查项 | 级别 | AI 处置 |
+|---|---|---|
+| `type` 缺失或不在已激活白名单 | 阻断 | 报错，不猜 |
+| 派生必填字段缺失（如外部页缺 `source_link`） | 阻断 | 报错；可推导则自动补 |
+| `status` 不在 enum | 阻断 | 报错；缺失自动填 `seed` |
+| `source` 不在 enum | 阻断 | 报错 |
+| `title` 缺失 | 提示 | 自动 = H1/文件名回填 |
+| 死链（`related` 指向不存在页） | 提示 | 建 stub 或标注 |
+| 孤立页（无任何入链/出链） | 提示 | 提议加 wikilink |
+| 过时（`timestamp` 超期） | 提示 | 交人/AI 判断 |
+
+**安全项 AI 自动修**：补可推导字段、建 stub、加 wikilink。
+**有损项挂起交人**：删页、解决矛盾、合并、改 type。
+
+> 维护保持轻量提示，**不做周度 cron 强制门禁**；靠 Git PR review + CC 提示 + `/kb-check` 按需运行。
+
+---
+
+## 附：写页 checklist（人只需第 1 条）
+
+1. **丢资料 + 一句说明 + 对 AI 抽的要点点头**（唯一强人工动作）。
+2. ~~填 frontmatter~~ → AI 自动补齐。
+3. ~~建 wikilink~~ → AI 自动挂链。
+4. ~~跑 lint~~ → `/kb-check` 或提交前 CC 自动跑。