sansan-knowledge：文件夹知识库

让用户现有的文件夹成为 Agent 可以稳定使用的知识库，并持续帮助用户收录资料、查找内容、判断版本、登记冲突和检查结构。

用户只需要理解「知识库」三个字。SOURCE_OF_TRUTH.md、AGENTS.md、CLAUDE.md、CODEBUDDY.md 和宿主兼容规则都在后台处理。需要解释技术文件时，把 SOURCE_OF_TRUTH.md 称为「知识库导航」。

一句话定义

提供一个入口，处理四类事情：

• 建：建立新的文件夹知识库，或让已有文件夹具备知识库导航。
• 存：把新资料放到合适位置，保留来源，处理重名、版本关系和来源冲突。
• 用：从知识库定位原始文件，综合回答并说明依据；高价值结论可经确认后回存。
• 查：检查失效路径、孤儿文件、陈旧权威、近似重复、版本冲突和维护缺口。

核心结果

一次成功的知识库建立至少形成这条调用链：

用户的问题或新资料
  ↓
Agent 入口规则：什么时候先查知识库
  ↓
SOURCE_OF_TRUTH.md：去哪里找、放在哪里、多个版本以哪个为准
  ↓
目录 README.md：复杂目录的局部说明（按需）
  ↓
原始文件：事实、材料和证据

知识库导航只负责指路与解决冲突。回答具体问题时，必须继续读取导航指向的原始文件，不能只根据导航摘要作答。

工作边界

默认会做

• 只读扫描用户指定的知识库目录。
• 识别目录职责、候选权威文件、原始资料、汇总文件和历史版本。
• 生成或更新知识库导航。
• 为当前 Agent 补充最小调用入口。
• 根据用户意图执行收录、查找、冲突登记或健康检查。

默认不会做

• 不要求安装数据库、向量库、Embedding 服务或 RAG 系统，不做本地语义检索引擎。
• 不上传用户文件到第三方平台。
• 不改写原始资料正文。
• 不根据文件标题臆测内容与权威性。
• 不在未确认时批量移动、重命名、覆盖或删除文件。
• 不按固定框架（如 PARA）强行重构用户已有目录结构。
• 不把每一个文件都登记进导航。
• 不读取密钥、密码、浏览器数据、聊天数据库等敏感内容。

写入规则

只读审计可自由执行。用户已明确说出修改对象和目标，且改动范围小、结果清楚时，这句话本身算确认，可直接执行（如修正一条错误路径、把刚用的文件加入导航、把已确认文件标为最新版）。

修改对象不明确，或涉及移动、复制、重命名、覆盖、删除、批量改动时，先给简短预览：①要改哪些路径；②会保留什么；③是否移动原文件；④是否影响现有 Agent 规则。用户确认后再写入。查询和只读健康检查不需要确认。

Obsidian 适配

进入目录先判断它是不是 Obsidian vault：根目录或上层含 .obsidian/ 配置目录即是。

确认是 vault 时：

1. 尊重用户已有的文件夹、标签、Dataview 查询和双链结构，不另建一套 wiki 目录、不重排笔记。
2. 导航和派生笔记中可以使用 [[双链]] 关联相关笔记；非 vault 库只用普通相对路径链接。
3. SOURCE_OF_TRUTH.md 放在 vault 根目录，可借助 Obsidian Properties（frontmatter）记录更新时间、状态等元信息。
4. 不破坏 Obsidian 的附件文件夹、模板文件夹和插件配置目录（.obsidian/、templates/、附件目录默认排除扫描）。
5. 不是 vault 时按普通 Markdown 文件夹处理，不强行引入双链。

第一步：确定知识库目录

按顺序确定根目录：

1. 用户明确给出目录：用该目录。
2. 用户说「这个文件夹」且当前工作目录边界清楚：用当前工作目录。
3. 当前目录是主目录、磁盘根、下载目录或范围明显过大：先请用户指定更具体目录。
4. 用户没有任何资料：询问知识库名称和保存位置，只问会改变实际路径的最小问题。

确认目录存在并使用规范化绝对路径，不把 skill 安装目录当成用户知识库。

第二步：只读审计

先看根级与 1～2 层目录，再按实际问题下钻。大型目录不一次读取全部正文。

优先查看：SOURCE_OF_TRUTH.md、AGENTS.md、CLAUDE.md、CODEBUDDY.md、根级和主要目录的 README.md、反映业务结构的顶层目录、文件名带日期/版本/最终版/原始/汇总/归档信号的文件。

默认排除：.git/、node_modules/、.obsidian/ 配置与插件目录、.trash/、缓存和构建产物、.env 与密钥凭证文件、大型二进制（只登记文件名/类型/大小/位置）、其他项目的演示和历史备份。

审计时判断：用户主要保存哪类资料？目录是否表达清业务边界？哪些可能是当前有效版本、依据是什么？哪些是原始记录、哪些是汇总或派生？是否已有导航、路径是否有效？当前宿主能否自动读取项目规则？是否为 Obsidian vault？

证据不足时标「待确认」，不自行指定权威版本。

第三步：识别状态与意图

状态 A：目录为空或几乎没资料 → 新建

默认最小结构：

{知识库根目录}/
├── 00-待整理/
├── SOURCE_OF_TRUTH.md
├── AGENTS.md
└── CLAUDE.md

• 00-待整理/ 是低门槛入口，暂时不知道放哪就先放这里。
• 按用户已说明的用途，可增加 2～5 个有明确职责的业务目录；没说明资料类型时不预建大量空目录。
• CLAUDE.md 只做 Claude Code 薄入口，跨宿主规则维护在 AGENTS.md。

状态 B：已有资料、缺导航 → 建立导航

先输出审计结果：①资料大致分哪些领域；②已清楚的目录职责；③候选当前版本与待确认冲突；④建议写入导航的条目；⑤明确排除的目录。用户确认后生成 SOURCE_OF_TRUTH.md，再补 Agent 入口。保留现有目录结构，只有明确归类收益且用户同意时才移动文件。

状态 C：已有导航 → 按意图路由

多个意图按依赖顺序处理（如先收录新文件，再回答依赖该文件的问题）。

轻量更新导航

用户说「更新知识库」「把刚才的文件加入」「这条路径写错了」「设为最新版」时走轻量更新：只读 SOT → 定位具体条目 → 只改对应小节 → 校验新路径存在。不扫全库、不重跑引导、不改 Agent 入口、不顺手整理无关文件、不重写整份导航。完成后只报本次实际变化：

知识库已更新：
- [修改] `{路径或条目}`：{改了什么}
- [新增] `{路径或条目}`：{加了什么}
- [删除] `{路径或条目}`：{删了什么}

导航瘦身与分层治理

当导航开始承担文件清单职责时进入治理（不按文件大小硬判断）：同项目逐文件登记可用一个主入口代替；同类条目大量重复；出现失效/重复路径或多个当前版本；Agent 要读大量无关条目才能定位；用户明确要求压缩。

• 只读审计：统计总行数、大小、表格条目数、精确路径数；按主题统计密度；查重复、失效、悬空引用、多个「最新版」、疑似敏感明细；列出可合并组与可承接明细的 README。
• 保留/合并/下沉/删除：
• 保留：目录职责、快速入口、当前权威、动态结论、版本冲突规则、跨目录关系、高频直达文件。
• 合并：同类资料只留一个主入口，写清范围、状态、更新时间、下钻位置。
• 下沉：原始表、附件、过程稿、历史版本、同类清单交给目录 README.md，导航只指向局部索引。
• 删除导航条目：重复、失效、已被主题入口覆盖的条目可从导航移除，原始业务文件保留。
• 敏感信息（账号、证件、密钥、财务明细）不写入导航。
• 证据不足的冲突保留「待确认」，不擅自指定当前版本。
• 写入前备份：整体瘦身属批量改动，先预览范围和备份位置，确认后把原导航复制到 .trash/YYYY-MM-DD_SOURCE_OF_TRUTH_优化前.md，再修改。
• 优化后验证：路径真实存在；每项权威事实能直达或经一层索引到达；职责/版本规则/高频入口没丢；没有新增重复或多个未解释当前版。记录优化前后行数、条目数、失效路径数、压缩比例。
• 防止再膨胀：新资料只有改变权威来源、目录职责、版本关系或高频入口时才更新顶层导航；一个项目默认一个顶层入口；过程文件不逐条登记。

模式一：建知识库

SOURCE_OF_TRUTH.md 最小结构

# 知识库导航

本文件告诉用户和 Agent：要找什么、去哪里找、多个版本以哪个为准。

## 快速查找
| 要找什么 | 去哪里 | 当前状态／备注 |
|---|---|---|

## 目录职责
| 目录 | 放什么 | 不放什么 |
|---|---|---|

## 版本与冲突规则
1. {明确的当前版本规则}
2. 无法确认时保留冲突，登记到「待确认冲突」并向用户询问。

## 待确认冲突
| 冲突点 | 来源 A（路径/日期） | 来源 B（路径/日期） | 状态 |
|---|---|---|---|

## 维护规则
- 新增关键权威文件、目录职责变化或发现版本冲突时更新本导航。
- 日常编辑普通文件无需逐条更新。

只登记对查找和判断有价值的信息类别，大量同类文件登记主目录、主索引或命名规则。

Agent 调用入口

AGENTS.md 存在则保留原文，在合适位置加入短小的「知识库调用」段：

## 知识库调用
- 查找本项目资料、判断动态事实、确认当前版本或创建新文件前，先读 `SOURCE_OF_TRUTH.md`。
- 根据导航定位并读取完成任务所需的原始文件。
- 多个来源冲突时遵循版本规则；规则不明确时登记「待确认冲突」并报告，不静默取舍。
- 回答时说明依据文件、资料时效和缺失信息。

已有等价规则不重复添加。CLAUDE.md 只做薄入口（@AGENTS.md），不把完整导航复制进去；WorkBuddy 缺 CODEBUDDY.md 时用 AGENTS.md 即可。其他宿主无法自动读取规则时，依靠已触发的本 skill 直接读导航。

模式二：存入知识库

收到新文件或新内容时：

1. 读导航和目标目录局部 README.md。
2. 判断资料类型、来源、日期、当前状态和候选归属。
3. 检查同名文件、相似版本和已有当前版本。
4. 来源冲突检查：若新资料与已有资料对同一事实给出不同说法，不静默覆盖、不擅自挑一个：
   - 在导航「待确认冲突」登记一行：冲突点、双方路径与日期、状态=待裁定；
   - 两份原始资料都保留，等用户裁定后再定权威，并移除该冲突行。
5. 给出建议目标路径及理由。知识库外文件默认复制并保留原件，用户明确要求移动才移动；重名不覆盖，用日期/版本/来源区分。
6. 只有新资料改变权威来源、目录职责或版本关系时才更新导航。

无法归类且不影响使用的先进 00-待整理/。待整理区持续增长时，健康检查要提醒。

模式三：从知识库调用

回答问题时：

1. 读 SOURCE_OF_TRUTH.md，定位 1 个或少量相关目录与文件。
2. 读原始文件中足以回答问题的部分；时间敏感信息核对更新时间。
3. 发现冲突时同时报告各来源及版本规则；规则不明确就登记「待确认冲突」，不凭常识补造本地事实。
4. 默认回答格式：

{直接回答用户的问题}

依据文件：
- `{路径}`：{支持了什么判断}

时效与缺口：{资料更新到什么时候；还缺什么；没有则省略}

用户只要求找文件时，直接给可点击路径和一句用途说明，不额外综合。

高价值结论回存（默认先问，不自动写）

当本次综合出的结论明显可复用（如跨多份资料提炼出的判断、一张对照表、一个定型结论），在交付后问一句：

> 这条结论以后可能还用得到，要不要我存成一篇派生笔记、挂到知识库导航？

用户同意后才写，并遵守：

• 存为派生结论文件（如 派生结论_YYYY-MM-DD_主题.md），正文写清它引用了哪些原始文件、生成日期；
• 与原始资料明确区分，不得改写或冒充原始文件；
• 在导航对应主题挂一个入口；用户没同意就不生成，避免堆积派生文件。

模式四：检查知识库（含三类深度 lint）

默认只读检查，分两层。

基础检查

• 导航路径是否存在；快速查找表是否覆盖主要领域；
• 是否出现多个「最终版/最新版」却没有冲突规则；
• 目录职责是否重叠；00-待整理/ 是否长期积压；根目录是否有大量无归属文件；
• Agent 入口能否指向导航；是否把历史版本/缓存/敏感目录误登记为当前来源；
• 是否有失效路径或悬空引用。

深度 lint（三类重点）

输出按优先级分级

• 立即处理：Agent 可能读错、路径失效、当前版本冲突、来源事实打架未裁定。
• 建议处理：出现孤儿/陈旧/近似重复，结构开始变乱但暂不影响主要使用。
• 保持现状：规则清楚，无需为整齐而移动。

修复前给修改清单，用户确认后再执行。检查结论不超过实际检查范围，没查到的部分明确说明。

首次使用引导

第一次建立、连接或检查知识库时，结果里必须含一段可直接照着说的引导：

1. 一句话确认状态，如「你的知识库已经可以使用」。
2. 告诉用户无需打开配置文件、不用记术语，用日常语言描述任务即可。
3. 根据实际扫描到的资料生成 3～4 条贴合当前目录的示例，至少覆盖「找/放/用/检查」中的三类，不用「某文件」这类空占位。
4. 告诉用户可直接复制一句或回复序号。
5. 导航和 Agent 入口路径放「技术详情」，用户没要求时保持简短。

完整小示例

> 用户：「帮我把这个内容资料文件夹变成知识库。」

• 审计发现：成稿/、素材/、选题.xlsx、3 个名字都带「最终版」的文档、根目录 2 个没人引用的零散 docx。
• 建导航：快速查找表 + 目录职责；3 个「最终版」无法判定先后 → 登记「待确认冲突」，不擅自指定。
• 深度 lint：2 个零散文件是孤儿文件 → 建议一个归入素材、一个归档；其中一个「最终版」半年没动但有更新稿 → 标为陈旧权威待复核。
• 检测到 .obsidian/ → 认定为 vault，导航放根目录，用 [[]] 关联，不重排现有文件夹。
• 首次引导给 3 句真实示例：「从知识库找一下上次那篇 AI 变现成稿」「把这份新素材放进知识库」「检查下有没有孤儿文件和版本冲突」。

完成标准

• 建立：根目录明确；导航路径经存在性检查；目录职责与版本规则有事实依据；当前 Agent 有可用调用路径；用户知道怎么放新资料、怎么提问。
• 收录：新资料位置明确；原件处理符合授权；没覆盖同名；来源冲突已登记不静默取舍；该更新的导航已更新。
• 查询：回答读了原始文件；关键判断可追溯到路径；时效、冲突、缺口已说明；派生结论经用户同意才回存。
• 检查：风险按三级列出并覆盖孤儿/陈旧/近似重复；建议具体到路径；未经确认没做移动覆盖删除。
• 轻量更新：只读改了直接相关内容；新路径经存在性检查；其他条目和入口保持原样；用简短变化清单交付。

质量自检

• 回答是否读了原始文件，而不是只凭导航摘要？
• 每处移动/覆盖/批量改动前是否给了预览并取得确认？
• 两个来源事实打架时，是否登记「待确认冲突」而不是静默挑一个？
• 健康检查是否覆盖孤儿文件、陈旧权威、近似重复三类深度 lint？
• 派生结论是否经用户同意才写、且与原始资料明确区分？
• 检测到 Obsidian vault 时是否尊重现有结构、用双链而不是另起目录？
• 是否没有引入向量库/数据库，没有按固定框架强行重构用户目录？
• 导航是否只指路、没有膨胀成文件清单，瘦身前是否备份？
• 是否排除了密钥、凭证、.obsidian/ 配置等不该读/不该登记的内容？
• 中文是否遵循《中文文案排版指北》？

与其他 Skill 的关系

用户请求越过边界时，先完成当前知识库任务，把越界需求写进结论，再引导到对应 skill，不硬塞进当前 skill。

语言

• 用户用中文就中文回，用英文就英文回。
• 中文遵循《中文文案排版指北》：中英文之间加空格、中文与数字之间加空格、中文标点用全角、数字用半角。

完成当前任务后直接结束。

作者与支持

• 作者：sansan（GitHub 主页）
• 如需加入付费答疑群，可扫码或打开答疑群说明