Knowledge-Base 知识库协议#

结构化 Markdown 知识库的最小公共管理协议，通过 references/ 适配具体知识库。

本文档分为两层：

• 核心协议：所有知识库都应遵守的最小公共约定
• 推荐实践：默认最佳实现，可由 references 覆盖或替换

知识库根路径#

由 references/ 配置文件定义。默认参考： references/hansphere.md

目录约定#

默认推荐结构#

默认推荐采用以下分层结构，具体路径和目录命名以 references 配置为准：

text

知识库根目录/
├── README.md              # 仓库总览
└── Notes/
    ├── 00-Inbox/          # 临时收集箱
    ├── 01-Daily/          # 日报/工作日志
    ├── 02-Sources/        # 外部来源
    │   └── Fulltext/      # 全文存档
    ├── 03-Concepts/       # 通用概念
    ├── 04-Issues/         # 问题模型
    ├── 05-Projects/       # 项目资料
    ├── 06-Architecture/   # 架构设计
    ├── 07-Patterns/       # 工作方法
    ├── 08-Reviews/        # 复盘总结
    ├── 09-Indexes/        # 索引导航
    ├── 10-Operations/     # 操作日志+体检
    ├── 98-Templates/      # 模板库
    └── 99-Archive/        # 归档区

各目录职责：

• Inbox → 临时收集，定期清理
• Daily → 当天事实记录
• Sources → 外部文章/资料（摘要+全文）
• Concepts → 可复用知识点
• Issues → 故障排查记录
• Projects → 项目资料（个人+公司统一管理）
• Architecture → 架构决策/ADR
• Patterns → 工作方法/SOP
• Reviews → 周报/月报/阶段复盘
• Indexes → 索引导航
• Operations → 操作日志+体检报告
• Templates → 笔记模板
• Archive → 长期归档

上述目录结构与职责为默认推荐映射，实际目录和职责边界以 references 配置为准。

执行流#

轻量流#

适用：Daily / Inbox / 已知文件更新 / 小修订

text

1. 判断目标文件
2. 套用已有模板/结构
3. 写入或更新
4. 回写 updated
5. 核心必检 6 项
6. 必要时补 ops

标准流#

适用：新建 Issue/Concept/Pattern/Project / 归档/迁移 / 批量整理 / 建索引

text

1. 搜索防重复
2. 判断类型
3. 读取规则（首次进入该类型时读目录 README + 模板；同会话内沿用上下文）
4. 创建/更新
5. 补关联字段
6. 回写 updated
7. 追加 ops（按工作批次收口）
8. 判断索引更新（延迟触发）
9. 完整质量清单

规则上下文缓存#

• 首次处理某类型笔记时，读取目录 README 和模板
• 同会话内同类型连续处理，沿用上下文，不重复读取

核心协议#

以下规则适用于所有知识库：

1. 语义类型判定#

新输入按以下语义角色判断类型（语义类型到实际目录的映射由 references 定义）：

语义角色含义默认目录时序记录当天/当期事实记录Daily临时收集尚未分类的新输入Inbox来源资料外部文章、书籍、课程Sources概念知识可复用的原理/机制Concepts问题排查具体故障的排查结论Issues项目资料项目需求、设计、变更记录Projects决策设计架构决策、技术选型Architecture方法流程可复用的工作方法/SOPPatterns复盘总结周期性归纳和回顾Reviews导航索引专题汇总、快速跳转Indexes

边界裁决：

• 问题排查 围绕"具体故障/排查结论"；概念知识 围绕"原理/机制"
• 外部文章即使和项目强相关，仍先进 Sources，再在 related 关联项目
• 临时收集 内容 7 天内必须归档或删除
• 时序记录 中出现可复用结论/排障闭环/架构决策/流程优化时，必须升格为长期笔记

2. 防重复搜索#

新建 长期知识类 笔记前必须搜索同主题已有内容：

风险级别语义类型要求**长期知识类（必须搜索）问题排查 / 概念知识 / 方法流程 / 项目正式文档文件名 + 正文中期资料类（推荐搜索）来源资料 / 决策设计 / 复盘总结文件名临时记录类（可跳过）**时序记录 / 临时收集 / 已知更新不强制

已有内容高度重合 → 更新旧文档，不新建。

3. 相对链接#

• 知识库内部使用可点击的 Markdown 相对链接： [简短说明](相对路径)
• 禁止使用绝对本地路径

4. 更新回写#

• 每次修改笔记必须回写 updated 字段为当天日期
• created 仅在首次创建时设置，后续不修改

5. 不写敏感信息#

• 不写入密码、Token、API Key、基础设施私钥、客户隐私或商业机密

6. 核心必检 6 项#

每次写入后检查：

• 路径符合类型判定规则
• 文件名符合命名约定（见 references）
• Front Matter 完整（id/title/type 必填）
• updated 已回写
• 不出现敏感信息
• 无明显重复（按搜索规则执行；可跳过类型无需强制搜索）

推荐实践#

以下实践为默认最佳方案，可由 references 覆盖。

以下类型名（Source/Issue/Concept 等）采用默认实现命名，仅作为推荐实践示例。

命名约定#

文件名应体现 类型前缀 + 主题/描述 + 日期，确保可读且可排序。

具体命名格式见 references 配置。参考实现：

类型HanSphere 格式DailyDAILY-YYYY-MM-DD.mdSourceSRC-Topic-YYYY-MM-DD.mdConceptCONCEPT-Domain-Topic.mdIssueISSUE-System-Problem.mdProjectPRJ-Project-Name/PatternPATTERN-Scenario.mdReviewYYYY-Www-WeeklyReview-MMDD-MMDD.md

Front Matter 标准字段#

字段说明id唯一标识，与文件名主干关联title与正文 H1 一致type笔记类型status当前状态domain领域project所属项目tags标签，推荐 3~7 个related关联笔记，数组格式source资料来源，数组格式created首次写入时间updated最后更新时间（每次修改必更新）review_cycle回顾周期（Source/Concept/Issue/Pattern 推荐）

原则：没有事实依据的字段宁可留空，不要猜。

related / source 默认规则：

• 默认实践中，来源资料 应提供 source 字段
• 默认实践中，问题排查 应尽量关联相关笔记；首次记录无关联对象可暂空，验证闭环前补齐
• 时序记录 / 孤立输入 允许都没有

生命周期#

使用 status 字段管理笔记状态：

类型状态流Sourcecaptured → processed → distilled → archivedProjectactive → paused → archivedIssueopen → diagnosed → fixed → verified → archivedConceptdraft → stable

最小正文骨架#

必须章节可简写，但不得省略核心信息。

类型必须章节Issue现象、排查过程、根因、解决方案Concept定义、核心机制、相关链接Source来源信息、核心观点、关键事实、相关链接Pattern适用场景、执行步骤、参考资料Architecture背景、问题、方案、决策、相关链接Review本期目标、实际进展、关键问题、相关链接

建议章节（可选）见完整模板。

归档规则#

archived 状态与物理移动到 Archive 目录是两个独立动作：

• 仅改状态：短期不再活跃
• 移动到 Archive：长期不再维护，须同时更新关联链接和索引

禁止只移动文件而不修复相关链接。归档后原路径保留简短说明 或 更新索引标注（二选一）。

索引生成#

触发条件：某主题 ≥ 5 篇 / 项目跨多模块 / 问题链路涉及多类型文档。

延迟触发：仅明确新建索引/用户要求/批量操作时立即更新，其他场景延后统一处理。

操作日志#

按 工作批次 收口，30 分钟内同主题多次修改合并为一条。仅记录有意义的知识动作（新建/结构调整/归档/体检等），不记录格式清理。

项目目录#

项目目录应包含稳定入口文件（如 00-Index/INDEX.md），可按需要包含以下分层：Overview / Requirements / Architecture / Modules / Interfaces / Data / Environments / Issues / Change-Logs / Todos / Decisions / Reviews。

实际目录结构由 references 定义。

知识库体检#

定期体检应覆盖：结构完整性、链接健康、命名规范、孤立页面、终端页面、报告输出。

具体评分权重和体检工具由 references 配置。

安全边界#

不写入认证信息（密码、Token、API Key）、基础设施私钥、客户隐私或商业机密。敏感值使用占位符。

配置扩展机制#

通过 references/<kb-name>.md 定义具体知识库的实现配置。reference 文件可定义以下维度：

维度说明根目录路径知识库在文件系统中的位置正文语言笔记正文使用的自然语言目录结构实际目录路径、层级和职责映射命名规范各类型的具体文件名格式字段默认值各类型默认 status、 review_cycle 等操作日志路径和模板ops 日志和体检日志的存储位置与格式体检脚本路径链接扫描等体检工具的执行命令Git/版本控制约定提交信息规范、同步流程项目目录结构项目内部的子目录层级和入口约定

当前配置： references/hansphere.md