Criss404 Save to KB(知识库记录)
Overview
把对话中的知识沉淀为正式知识库笔记(curation(策展),不是转录)。所有输出遵循 references/standards.md 中的规范,按笔记类型选用 assets/ 下对应模板(知识笔记 template.md、操作手册 ops-template.md)。深度研究/教材级深化不在本 skill,见 expand-note。
知识库定位与路由(通用协议,不写死结构)
- 定位知识库根目录,按顺序取第一个可用值:环境变量
KB_ROOT→ 当前 harness 加载的指令文件(如 Qoder/OpenCode 的 AGENTS.md、Claude Code 的 CLAUDE.md;不是 agent 自动记忆)中声明的知识库路径 → 都没有就向用户询问,禁止猜测 - 读根目录的
知识库结构.md(或STRUCTURE.md):目录路由表、编号前缀、各域 MOC、非策展区、写作偏好全部以它为准(与本 skillreferences/standards.md冲突时,以结构文件为准);禁止凭记忆猜结构。该文件不存在时(冷启动):向用户报告,询问是否按assets/structure-template.md创建——同意后:① 问用户先建哪 1~2 个知识域(名称 + 一句话定位 + 前缀);② 按模板生成结构文件(填入用户的域与 curated-dirs);③ 创建域目录 + 00 MOC;④ 继续正常记录流程。拒绝创建则中止记录并说明原因。幂等:文件已存在则本条后半全部跳过,不重复询问、不覆盖 - 归属拿不准或沾边不足时向用户提问并等待选择,候选清单按结构文件路由规则列出(现有目录 + "新建目录/子目录"方案并列,禁止因新建有流程就默认塞现有目录);出现新领域时按结构文件的演化规则,征得用户同意后新建"域文件夹 + 前缀 + XX-00 MOC"并回写结构文件
模式
模式 A:记录会话
用户说"记录本次会话/把刚才的内容记到知识库"时执行:
- 分阶段保存(先于一切):大块知识产出后(一次调研/排障/决策定案)随即保存入库,不要攒到会话结尾一次性处理——结尾时上下文最满、记忆最差,长会话极易漏掉中早期主题。用户说"交接/换 session"时若还没保存,先把当前已完成的知识块入库再交接。
- 时间线扫查提取候选:按会话时间线逐段回顾(按事件顺序:每完成一件事扫一遍它产出了什么知识),不是按主题回忆——长会话里早期主题会沉底;对每个候选做 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 候选清单过目(防遗漏):候选提取完成后,把候选清单(含"跳过内容及依据")列给用户过目,用户确认或补充后再写——人工兜底是最后的防漏网,禁止跳过此步
- 决定拆分:一个独立概念/结论 = 一篇笔记;少量相关内容可合并;禁止把整场对话塞进一篇
- 写前查重:对每个知识点运行
KB_ROOT=<知识库根目录> python3 <本skill目录>/scripts/find_related.py <关键词...>获取候选清单(脚本只扫结构文件声明的策展区),只对候选做判断——已覆盖 → 更新该笔记;部分覆盖 → 合并进去;NO_MATCH→ 新建。禁止为查重通读全库(token 成本必须保持 O(候选)) - 读取目标子文件夹现有文件,确定下一个可用编号,禁止覆盖已有文件
- 每篇按
assets/template.md模板写作,遵循references/standards.md全部规范 - 更新 MOC:把新笔记加入
00索引的目录,必要时在 TL;DR 补一行结论,并更新"更新日期" - 输出清单:列出新建/更新的文件路径及查重决策(几新几改几跳过),并报告操作手册候选评估结果(写了哪本 / 评估后不写的依据),报告给用户
- 维护人类导航层(条件条款):仅当结构文件声明了「人类导航层/人读索引」时执行——新笔记/新手册写入后,按结构文件该节维护对应索引条目(纯指针、不写正文;如 Obsidian 用路径式
[[目录/文件|显示名]]链接);顺带校验既有条目链接未失效,笔记改名/移动则同步。结构文件未声明此层的知识库跳过本条,不创建 - 版本提交:在知识库根目录运行
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 候选评估成册)——两条入口同走本模式流程:
- 目标系列按
知识库结构.md路由表的操作手册域(前缀与 MOC 以它为准);系列 MOC 不存在时先创建(参照其他域 MOC 结构) - 从会话中提取该操作的骨架(跨工具不变的步骤序列 + 每步完成标准)与配方(当前 harness 的具体路径/命令),按
assets/ops-template.md模板写作——骨架配方必须分离 - 白话原则(白话在句式,不在术语):手册面向"照着做"——祈使句、一步一个动作、命令可直接复制粘贴、每步给"做对的标志";术语遵循全库约定(英文原词(中文),skill/memory/hook 照常使用,禁止译成中文别名),但数量最小化:只出现操作必需的术语,不引入理论侧术语;知识只链接不展开:步骤需要背景时最多一两句话说明动机,深入原理一律用 wikilink 指向知识域笔记,禁止在手册内展开知识内容
- 只记本环境特有的参数与约定(仓库地址、路径、规范、特殊 flag);agent 张口就会的通用命令(如 git 基本用法)不抄教程
- 配方必须标注 harness 名与验证日期;回写约定:在新 harness 上按骨架走通后,必须把新配方补回手册(手册随实践更新,不是一次写死);过期配方标"待复验",不删除
- 其余流程同模式 A 的步骤 1.5、3、4、6、7、8、9(压缩防护、查重、编号、MOC、报告、维护人类导航层(条件条款)、版本提交)
分支防重与防遗漏(fork 场景)
当本会话是从历史会话分叉出来的(context 中出现过会话分叉命令的痕迹,如 Qoder 的 /branch;或本会话与历史会话大量重叠)时,启用以下规则:
- 只信磁盘记录,不信对话记忆:"某知识点是否已记录过"一律以写前查重结果和 MOC 为准——分支之间互相看不见对方的对话,只有磁盘上的文件反映真实状态
- 查重升级:命中的候选笔记必须打开正文快速比对确认覆盖情况(平时只看候选清单即可);宁可更新既有笔记,不新建
- 共享部分的处理:优先策展分叉点之后的新内容;分叉前的共享内容先查重验证是否已入库——已入库才可跳过,未入库照常策展(不得假设另一个分支会处理)。验证顺序先廉后贵:① 先在知识库根目录跑
git log --oneline -20,分叉之后有 commit(不限前缀,save-to-kb:/expand-note:等均可)且文件名与知识点主题明确对应的,视为已入库的磁盘证据,跳过并在报告中引用 commit 号;② 对应不明确、查不到 commit、或仓库不存在的,回退到逐点查重 + 打开候选正文比对(原流程)。git 证据是单向阀:只能用于确认跳过,不能用于确认"未记录"——查不到不等于没记,必须回退验证 - 跳过必须说明(防遗漏):凡决定不记录的内容,必须在执行报告中列明"跳过了什么 + 依据"(已入库 / 判定无价值);禁止不说明就跳过——遗漏靠报告透明来发现,靠备份档案随时补录来挽救
- 并发写入提醒:多个分支同时工作时,记录操作应一个接一个执行(写入前重新确认编号可用),避免编号与 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 只判断候选;库上千篇且近义漏判多时,再升级为向量相似度查重