Knowledge-Base

SKILL.md

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

# Knowledge-Base 知识库协议

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

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

## 知识库根路径

由 references/ 配置文件定义。默认参考：[references/hansphere.md](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 定义）：

| 语义角色 | 含义 | 默认目录 |
| --- | --- | --- |
| **时序记录** | 当天/当期事实记录 | 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](references/hansphere.md)