# Save To Kb

> 把会话内容策展(curation)成正式笔记或操作手册,按固定规范快速写入用户的 Obsidian 知识库。触发场景:用户说"记录到知识库/保存会话/把这次内容记下来/把这个操作记下来/记操作手册/save to kb"等。涉及知识库路径、笔记格式、wikilink、索引更新的写入操作都用本 skill。教材级深化和新主题深度研究请用 expand-note skill。

- Skill: `criss404/save-to-kb` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add criss404/save-to-kb`
- Raw SKILL.md: https://api.skillmd.com/api/skills/criss404/save-to-kb/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Criss404 (https://skillmd.com/u/criss404)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/criss404/save-to-kb

---


# Save to KB(知识库记录)

## Overview

把对话中的知识沉淀为**正式知识库笔记**(curation(策展),不是转录)。所有输出遵循 `references/standards.md` 中的规范,按笔记类型选用 `assets/` 下对应模板(知识笔记 `template.md`、操作手册 `ops-template.md`)。深度研究/教材级深化不在本 skill,见 expand-note。

## 知识库定位与路由(通用协议,不写死结构)

1. **定位知识库根目录**,按顺序取第一个可用值:环境变量 `KB_ROOT` → 当前 harness 加载的指令文件(如 Qoder/OpenCode 的 AGENTS.md、Claude Code 的 CLAUDE.md;不是 agent 自动记忆)中声明的知识库路径 → 都没有就向用户询问,禁止猜测
2. **读根目录的 `知识库结构.md`(或 `STRUCTURE.md`)**:目录路由表、编号前缀、各域 MOC、非策展区、写作偏好全部以它为准(与本 skill `references/standards.md` 冲突时,以结构文件为准);禁止凭记忆猜结构。**该文件不存在时(冷启动)**:向用户报告,询问是否按 `assets/structure-template.md` 创建——同意后:① 问用户先建哪 1~2 个知识域(名称 + 一句话定位 + 前缀);② 按模板生成结构文件(填入用户的域与 curated-dirs);③ 创建域目录 + 00 MOC;④ 继续正常记录流程。拒绝创建则中止记录并说明原因。幂等:文件已存在则本条后半全部跳过,不重复询问、不覆盖
3. **归属拿不准或沾边不足时向用户提问并等待选择**,候选清单按结构文件路由规则列出(现有目录 + "新建目录/子目录"方案并列,禁止因新建有流程就默认塞现有目录);出现新领域时按结构文件的演化规则,征得用户同意后新建"域文件夹 + 前缀 + XX-00 MOC"并回写结构文件

## 模式

### 模式 A:记录会话

用户说"记录本次会话/把刚才的内容记到知识库"时执行:

0. **分阶段保存(先于一切)**:大块知识产出后(一次调研/排障/决策定案)随即保存入库,不要攒到会话结尾一次性处理——结尾时上下文最满、记忆最差,长会话极易漏掉中早期主题。用户说"交接/换 session"时若还没保存,先把当前已完成的知识块入库再交接。
1. **时间线扫查提取候选**:按**会话时间线逐段回顾**(按事件顺序:每完成一件事扫一遍它产出了什么知识),不是按主题回忆——长会话里早期主题会沉底;对每个候选做 **Diátaxis 四象限定性**:
   - **候选提取判据(防漏)**:凡出现"怎么做 X"的描述(命令、步骤、配置、安装流程、使用方式),**一律提取为 How-to/Tutorial 候选**;项目文档是否已有只影响配方要不要抄,**不影响是否成册**——禁止以"项目文档已有"为由把操作内容判出候选
   - **Explanation(解释,讲原理)/ Reference(参考,定义/参数/清单)** → 知识笔记候选,走步骤 2-9
   - **How-to(操作指南,教做具体事)/ Tutorial(教程,从零带一遍)** → 操作手册候选:按价值门槛(高频复用 / 跨机器换环境需要)判断是否成册;成册 → 走模式 C;不成册 → 记入报告"操作手册候选评估结果",**不静默丢弃**
   - **四象限外**(项目实现细节、闲聊、一次性消息)→ 不入库,报告说明
   判定例句:讲原理 → Explanation;列参数/定义 → Reference;教做具体事 → How-to;从零带一遍 → Tutorial。
   - **拿不准/争议处置**:候选象限不明、或内容疑似用户明确需求(用户说过"记这个操作/记使用文档"之类)时,**不得自行判出候选、不得自行判"不成册",必须先询问用户**(说明候选象限与依据,由用户拍板);仅当用户不可达且与用户明确需求无关时,才按最接近象限归类并写入报告
   - **1.5 压缩防护(对照原文协议)**:若会话很长、context 中出现压缩摘要痕迹、PreCompact 提醒,或用户主动说"上下文不够/先交接"时,不要凭记忆策展——先运行 archive-sessions 的备份脚本刷新备份(0 token;命令见其 SKILL.md,即 `python3 <本工具包安装目录>/archive-sessions/scripts/archive_sessions.py`),再按知识点关键词 grep 备份目录(`$AGENT_ARCHIVE_DIR` 或默认 `~/sessionbackup/<harness>/`)对应文件,核对细节数据与来源链接;**记忆与备份原文冲突时,以备份原文为准**;仍无法核实的内容标注"待核实"而不是硬写
   - **1.6 候选清单过目(防遗漏)**:候选提取完成后,把候选清单(含"跳过内容及依据")列给用户过目,用户确认或补充后再写——人工兜底是最后的防漏网,禁止跳过此步
2. 决定拆分:一个独立概念/结论 = 一篇笔记;少量相关内容可合并;禁止把整场对话塞进一篇
3. **写前查重**:对每个知识点运行 `KB_ROOT=<知识库根目录> python3 <本skill目录>/scripts/find_related.py <关键词...>` 获取候选清单(脚本只扫结构文件声明的策展区),只对候选做判断——已覆盖 → **更新该笔记**;部分覆盖 → 合并进去;`NO_MATCH` → 新建。**禁止为查重通读全库**(token 成本必须保持 O(候选))
4. 读取目标子文件夹现有文件,确定下一个可用编号,**禁止覆盖已有文件**
5. 每篇按 `assets/template.md` 模板写作,遵循 `references/standards.md` 全部规范
6. 更新 MOC:把新笔记加入 `00` 索引的目录,必要时在 TL;DR 补一行结论,并更新"更新日期"
7. 输出清单:列出新建/更新的文件路径及查重决策(几新几改几跳过),并报告**操作手册候选评估结果**(写了哪本 / 评估后不写的依据),报告给用户
8. **维护人类导航层(条件条款)**:仅当结构文件声明了「人类导航层/人读索引」时执行——新笔记/新手册写入后,按结构文件该节维护对应索引条目(纯指针、不写正文;如 Obsidian 用**路径式** `[[目录/文件|显示名]]` 链接);顺带校验既有条目链接未失效,笔记改名/移动则同步。结构文件未声明此层的知识库跳过本条,不创建
9. **版本提交**:在知识库根目录运行 `git add -A && git commit -m "save-to-kb: <本次新建/更新的文件名>"`(每次写入对应一个 commit,出错可用 `git diff`/`git checkout <commit> -- <文件>` 审计与回滚)。**仓库不存在时**:询问用户是否 `git init`(同意才执行,已是仓库则不重复初始化);拒绝则跳过提交步骤并在报告注明"未版本化",不中断记录流程。提交失败时向用户报告原因,同样不中断

### 模式 B:拓展主题(已迁出)

深度拓展与教材级深化已迁至 **expand-note skill**——用户要求"拓展主题/深化笔记/写教材级内容"时,改用该 skill,不要在本 skill 内执行联网研究。

### 模式 C:记录操作手册

本模式可由用户点名触发(说"把这个操作记下来/记操作手册/以后换工具还要用"),也可由模式 A 的四象限定性转来(How-to/Tutorial 候选评估成册)——两条入口同走本模式流程:

1. 目标系列按 `知识库结构.md` 路由表的操作手册域(前缀与 MOC 以它为准);系列 MOC 不存在时先创建(参照其他域 MOC 结构)
2. 从会话中提取该操作的**骨架**(跨工具不变的步骤序列 + 每步完成标准)与**配方**(当前 harness 的具体路径/命令),按 `assets/ops-template.md` 模板写作——骨架配方必须分离
3. **白话原则(白话在句式,不在术语)**:手册面向"照着做"——祈使句、一步一个动作、命令可直接复制粘贴、每步给"做对的标志";**术语遵循全库约定**(英文原词(中文),skill/memory/hook 照常使用,禁止译成中文别名),但**数量最小化**:只出现操作必需的术语,不引入理论侧术语;**知识只链接不展开**:步骤需要背景时最多一两句话说明动机,深入原理一律用 wikilink 指向知识域笔记,禁止在手册内展开知识内容
4. 只记**本环境特有**的参数与约定(仓库地址、路径、规范、特殊 flag);agent 张口就会的通用命令(如 git 基本用法)不抄教程
5. 配方必须标注 harness 名与验证日期;**回写约定**:在新 harness 上按骨架走通后,必须把新配方补回手册(手册随实践更新,不是一次写死);过期配方标"待复验",不删除
6. 其余流程同模式 A 的步骤 1.5、3、4、6、7、8、9(压缩防护、查重、编号、MOC、报告、维护人类导航层(条件条款)、版本提交)

## 分支防重与防遗漏(fork 场景)

当本会话是从历史会话分叉出来的(context 中出现过会话分叉命令的痕迹,如 Qoder 的 `/branch`;或本会话与历史会话大量重叠)时,启用以下规则:

1. **只信磁盘记录,不信对话记忆**:"某知识点是否已记录过"一律以写前查重结果和 MOC 为准——分支之间互相看不见对方的对话,只有磁盘上的文件反映真实状态
2. **查重升级**:命中的候选笔记必须**打开正文快速比对**确认覆盖情况(平时只看候选清单即可);宁可更新既有笔记,不新建
3. **共享部分的处理**:优先策展分叉点之后的新内容;分叉前的共享内容**先查重验证是否已入库**——已入库才可跳过,未入库照常策展(不得假设另一个分支会处理)。**验证顺序先廉后贵**:① 先在知识库根目录跑 `git log --oneline -20`,分叉之后有 commit(不限前缀,`save-to-kb:`/`expand-note:` 等均可)且文件名与知识点主题**明确对应**的,视为已入库的磁盘证据,跳过并在报告中引用 commit 号;② 对应不明确、查不到 commit、或仓库不存在的,回退到逐点查重 + 打开候选正文比对(原流程)。git 证据是单向阀:**只能用于确认跳过,不能用于确认"未记录"**——查不到不等于没记,必须回退验证
4. **跳过必须说明(防遗漏)**:凡决定不记录的内容,必须在执行报告中列明"跳过了什么 + 依据"(已入库 / 判定无价值);**禁止不说明就跳过**——遗漏靠报告透明来发现,靠备份档案随时补录来挽救
5. **并发写入提醒**:多个分支同时工作时,记录操作应一个接一个执行(写入前重新确认编号可用),避免编号与 MOC 互相覆盖

## 记什么 / 不记什么

**记**:结论与决策(含理由)、方案对比表、原理讲解、踩坑与修复、可迁移性强的知识(范式层优先)、重要来源链接。

**不记**:寒暄闲聊、中途被推翻的尝试(除非教训本身有价值)、API key 等敏感信息、纯时效性消息、与用户知识体系无关的旁枝。

**价值判断与路由判断解耦**:"没有合适目录"不是"不记"的理由——先按本节标准判价值,值得记但现有目录都不字面匹配的,按结构文件路由规则走"新建目录候选"流程向用户提问;禁止因路由无解而把知识点改判为"旁枝"静默丢弃。拿不准记不记的边缘知识点,列入执行报告的"跳过内容及依据"清单或直接问用户,禁止不留痕迹地丢弃。

## 执行检查清单(每次必须逐项过)

- [ ] 候选按**时间线扫查**提取(非主题回忆),候选清单已按 1.6 给用户过目
- [ ] 上下文紧张/用户喊交接时,已按 1.5 先刷新备份再核对,未凭记忆硬写
- [ ] 每篇笔记 frontmatter 声明了 Diátaxis 类型和知识层级
- [ ] 操作手册候选已评估(四象限定性结果:写了哪本/评估后不写的依据,已入报告)
- [ ] 拿不准/疑似用户明确需求的候选已询问用户,未自行判出
- [ ] 写前查重已执行,报告含查重决策(几新几改几跳过)与"跳过内容及依据"清单(含筛选阶段判"不记"的边缘知识点,不只是查重阶段的跳过)
- [ ] 更新类笔记:先列"本会话该主题的全部增量清单"(逐条),写完逐条勾销——防"补了主结论、漏了同批小坑" 
- [ ] 术语与排版遵循结构文件声明的写作偏好(本库默认:英文原词(中文)、中英文间空格),同一术语全库写法一致(用 grep 抽查既有笔记的写法)
- [ ] 关键事实标注来源:`[训练集]` / `[联网:链接]` / `[知识库:文件]`
- [ ] 入库前复核事实断言:凡来源仅为 `[训练集]` 的产品特性/版本/时效内容,当场联网复核,复核不了就在笔记中显式标"待验证";否定断言("没有/不支持某功能")必须有官方文档依据,否则不得写成结论(知识库写入是持久化边界,错误一旦入库会被后续会话当可信来源引用)
- [ ] 中英文之间有空格,标点符合中文排版规范
- [ ] 笔记间有 [[wikilink]] 互链,文末有"相关笔记"
- [ ] MOC(00 索引)已更新
- [ ] 若结构文件声明了人类导航层,对应索引条目已更新(死链已校验);未声明则跳过
- [ ] 未覆盖任何已有文件;编号无冲突
- [ ] 向用户报告了文件清单
- [ ] 出口检查:写完全部后,对着本次候选清单逐项勾销(每个候选落在某文件或跳过清单里)
- [ ] 已执行 git 提交,提交信息以 "save-to-kb: " 开头并含本次文件名

## Resources

- `references/standards.md`:完整记录规范(Diátaxis、写作规范、排版规范、知识分层、来源标注)——写作前先读
- `assets/template.md`:笔记模板——每篇笔记以此为骨架
- `assets/structure-template.md`:结构文件模板——冷启动(知识库无结构文件)时按它引导创建
- `scripts/find_related.py`:写前查重助手——机械检索候选交脚本,LLM 只判断候选;库上千篇且近义漏判多时,再升级为向量相似度查重