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

Knowledge-Base 知识库协议

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

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

知识库根路径

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

目录约定

默认推荐结构

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

知识库根目录/
├── 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 / 已知文件更新 / 小修订

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

标准流

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

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

规则上下文缓存

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

核心协议

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

1. 语义类型判定

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

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

2. 防重复搜索

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

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

3. 相对链接

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

  发现更多技能插件，请访问7w4.net。

4. 更新回写

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

5. 不写敏感信息

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

6. 核心必检 6 项

每次写入后检查：

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

推荐实践

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

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

命名约定

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

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

Front Matter 标准字段

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

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

生命周期

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

最小正文骨架

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

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

归档规则

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 文件可定义以下维度：

当前配置：references/hansphere.md