Knowledge-Base

结构化 Markdown 知识库管理协议。在知识库中新增、整理、搜索笔记和项目。匹配：在知识库中记笔记/归档/整理/搜索/创建项目/写日报/写周报/记录外部来源/沉淀概念或问题模型/知识库体检。当用户提到知识库操作、笔记管理、知识库健康检查时触发。默认推荐结构见正文，实际目录/命名/脚本等由 references/ 配置文件定义。

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
方法流程	可复用的工作方法/SOP	Patterns
复盘总结	周期性归纳和回顾	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 格式
Daily	DAILY-YYYY-MM-DD.md
Source	SRC-Topic-YYYY-MM-DD.md
Concept	CONCEPT-Domain-Topic.md
Issue	ISSUE-System-Problem.md
Project	PRJ-Project-Name/
Pattern	PATTERN-Scenario.md
Review	YYYY-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 字段管理笔记状态：

类型	状态流
Source	captured → processed → distilled → archived
Project	active → paused → archived
Issue	open → diagnosed → fixed → verified → archived
Concept	draft → 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