company-kb/CONVENTIONS.md

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/ 下一页）：

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