84f7950589
- 完整的知识库框架（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>
137 lines
7.2 KiB
Markdown
Executable File
137 lines
7.2 KiB
Markdown
Executable File
# 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 自动跑。
|