# 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 自动跑。