硅基的你 · 记忆与传承
> 为什么叫「硅基的你」
>
> 人类区别于其他动物的地方，是会使用工具、并懂得用文字、语言、影音保存知识、
> 反思教训、总结经验 —— 靠这一条，文明得以跨代传承、持续累积。
>
> 但个体不是这样。人的记忆随肉体老化而衰减：能长期记住的越来越少，遗忘的越来越多。
> 一个人一生的经验，绝大部分随他一起消失。
>
> 这个 skill 做的事，就是把这份经验搬进硅基载体 —— 你已有的资料、你随手记下的判断、
> 你改过几稿的结论、你为什么改、事后怎么看 —— 全部记住、随取随用、不会随时间褪色。
>
> 所以它不是"工具"，是你的一副外置记忆：一个记忆力更强、时间更长的你。
> 它照的是你的镜子 —— 镜面里的那个你，更全、更久。
但有一条必须说清楚（边界声明）
| 它是什么 | 它不是什么 |
|---|---|
| 你的记忆载体：保管、检索、串联、复盘你写下来的东西 | 你的人格替身：它不替你判断、不替你决定、不代言 |
| 记忆力更强、时间更长的那部分你 | "另一个你"：它只知道你写下来过的东西，读不到你没记的 |
| 帮你看见自己怎么想过来的（版本演进、决策留痕） | 帮你美化过去：复盘素材原样呈现，包括那些改错的地方 |
> 一句话：它记性比你好，但判断权始终在你手里。 这是它能被称为"你"，而不被称为"神明"的原因。
能力与操作边界
> - 既有原始资料只读。 未经你明确说明「某处资料需要更正」，不改动、不移动、不重命名任何已有资料。
> - 授权不等于写权限。 目录授权只授予「可扫描 / 可索引 / 可检索」。
> - 本工具不提供删除能力。 没有删除命令，任何情况下都不删文件。
> - 不外发。 索引、感知与检索全部离线完成，资料内容不上传。
> - 敏感目录永久排除（密钥 / 密码 / 证件 / 财务 / AppData），不可通过配置绕过。
一、七类能力
| 能力 | 做什么 | 写权限 |
|---|---|---|
找 find |
检索定位已有资料（关键词/类型/时间/目录） | 只读 |
读 read |
抽取并读取已授权资料的正文 | 只读 |
察 survey |
全盘只读感知：系统/磁盘/桌面/目录结构（需 L0） | 只读，不读文件内容 |
记 note distill archive |
记录新信息 → 归纳 → 沉淀为正式资料 | 只写自己产出的资料库 |
悟 review |
复盘萃取：时间线 + 版本演进 + 决策留痕，供提炼经验 | 只读 |
守 audit |
巡检报告（重复/大文件/陈旧/分布） | 只读，只报告不清理 |
理 move rename undo |
更正迁移 | 需逐次授权令牌 |
记与悟的分工：distill 向前 —— 把散落记录归纳成一份资料；review 向后 —— 回答
「这件事是怎么一步步走到今天的」。前者是积累，后者是传承。缺了后者，这个 skill 只是个仓库。
三级授权（核心概念）
| 级别 | 名称 | 授予什么 | 生效方式 |
|---|---|---|---|
| L0 | 全景授权 | 全盘只读感知（元数据，不含正文） | 一次性，须 grant-survey --yes 显式确认，可撤销 |
| L1 | 目录纳入授权 | 可扫描 / 可索引 / 可检索 | 一次性，持久 |
| L2 | 操作授权 | 执行某一次具体变更 | 逐次，用完即失效 |
L0 与 L1 互不包含；L1 目录授权 ≠ 写权限。
任何写操作都必须先出预览、拿到 TOKEN、由用户确认后带 --confirm 执行。 这是机制强制，不是流程建议。
二、快速入门
# 0. 首次使用：初始化 + 授权目录 + 建索引
python <skill>/scripts/butler.py init
python <skill>/scripts/butler.py grant "D:/资料"
python <skill>/scripts/butler.py index
# 1. 找
python <skill>/scripts/butler.py find "报价单"
python <skill>/scripts/butler.py find "阀门" --kind doc --since 90
# 2. 读
python <skill>/scripts/butler.py read "D:/资料/项目/线缆报价联动说明.md"
# 3. 记 → 归纳 → 入库
python <skill>/scripts/butler.py note "新金普基准 72000 元每公里" --tags 线缆,报价
python <skill>/scripts/butler.py distill "线缆报价"
python <skill>/scripts/butler.py archive --title "线缆报价联动要点" --topic "线缆报价" --from-file 草稿.md
# 4. 悟 → 复盘萃取 → 经验卡片
python <skill>/scripts/butler.py review "线缆报价"
python <skill>/scripts/butler.py archive --title "报价联动的三条教训" --topic "线缆报价" \
--from-file 经验卡片.md --links "线缆报价联动要点"
# 5. 守
python <skill>/scripts/butler.py audit
# 6. 察（全盘只读感知，需 L0）
python <skill>/scripts/butler.py grant-survey --yes
python <skill>/scripts/butler.py survey --scope all
python <skill>/scripts/butler.py survey --scope tree --dir "D:/资料"
# 7. 理（两段式）
python <skill>/scripts/butler.py move "D:/下载/报价.xlsx" "D:/资料/线缆"
python <skill>/scripts/butler.py move "D:/下载/报价.xlsx" "D:/资料/线缆" --confirm 3f9a1c07
运行要求：Python 3.8+，仅标准库，无需 pip 安装任何依赖。
三、命令速查
初始化与授权
| 命令 | 说明 |
|---|---|
init |
初始化数据目录并写默认配置 |
status [--json] |
数据目录 / 授权目录 / 索引概况 |
grant <目录> [--json] |
L1 授权一个目录（不授予写权限） |
revoke <目录> |
撤销 L1 授权（不动任何文件） |
grants [--json] |
列出已授权目录 |
grant-survey --yes |
授予 L0 全盘只读感知（须显式 --yes，缺省只出说明） |
revoke-survey |
撤销 L0 |
察（全盘只读感知，需 L0）
| 命令 | 说明 |
|---|---|
survey --scope all |
系统信息 + 磁盘容量与顶层布局 + 桌面项目 |
survey --scope system |
操作系统 / CPU / 内存 / Python |
survey --scope disks |
各磁盘总量 / 剩余 / 使用率 + 顶层目录 |
survey --scope desktop |
桌面项目清单（文件夹 / 快捷方式 / 文件，只列名称） |
survey --scope tree --dir <目录> [--depth 2] [--max-entries 100000] [--budget 20] |
指定目录的资料类型分布与结构（带硬上限） |
察的边界：只采集元数据（名称/大小/类型/结构），不读取任何文件正文；敏感排除规则在 L0 之下依然生效。
找 / 读
| 命令 | 说明 |
|---|---|
find <关键词> [--ext docx,xlsx] [--kind doc] [--since 30] [--in-dir <目录>] [--root <目录>] [--limit 20] [--sort relevance\|time] [--json] |
检索；多关键词空格分隔，取交集 |
read <路径> [--chars 3000] [--full] [--json] |
读取正文；--json 中的 excerpt_state 可用于诊断 |
kind 取值：doc sheet slide pdf image audio video archive code ebook other
记
| 命令 | 说明 |
|---|---|
note "<内容>" [--tags a,b] [--source 对话] [--from-file <文件>] [--stdin] |
记入收件箱 |
inbox [--days 7] [--limit 50] [--json] |
查看收件箱 |
distill "<主题>" [--days 90] [--limit 30] [--write] [--json] |
聚合素材包，交 AI 归纳 |
archive --title "<标题>" --topic "<主题>" (--from-file <草稿> \| --content "<正文>") [--tags a,b] [--derived-from id1,id2] [--links 标题1,标题2] |
资料化入库；同名自动升版；--links 建双向链接 |
library [--json] |
列出资料库 |
悟
| 命令 | 说明 |
|---|---|
review "<主题>" [--days 365] [--limit 50] [--write] [--json] |
复盘素材包：时间线 + 版本演进 + 决策留痕（只读，不改动任何资料） |
守 / 理
| 命令 | 说明 |
|---|---|
audit [--top 10] [--stale-days 180] [--no-hash] [--report] [--json] |
巡检报告 |
move <源> <目标目录> [--confirm <TOKEN>] |
移动；不带 --confirm 只出预览 |
rename <源> <新名> [--confirm <TOKEN>] |
改名；不带 --confirm 只出预览 |
undo [<操作号>] [--confirm <TOKEN>] |
回滚最近一次（或指定）移动/改名 |
log [--limit 20] [--json] |
查看操作日志 |
四、七个典型工作流
工作流 1：找回一份资料（找）
1. find "<能想起来的词>" # 想不起全名就拆词：find "报价 铜价"
2. 按需要补过滤：--kind sheet --since 365
3. 确认后 read <路径> 看内容
> 检索不到不要急着重来：先 status 看索引条数，为 0 就先 index。
工作流 2：梳理某主题的现有材料（读）
1. find "<主题>" --limit 50 --json # 拿到清单
2. 逐份 read 抽取正文要点
3. 输出对照分析 / 汇总视图（不移动任何文件）
工作流 3：沉淀新信息（记）★ 日常主循环
① note 随手记 → 收件箱（不做分类判断，零摩擦）
② distill <主题>
→ 拿到「素材包」：命中的收件箱记录 + 相关在库资料
→ 我据此归纳成文（这一步由 AI 完成，脚本只负责聚合）
③ archive → 命名、落盘、登记元数据、入索引，立刻可被 find 检索到
> 闭环价值：记录的产出反哺检索，记忆越用越厚。
> 归纳产物带 version / derived_from，可追溯「当初是怎么归纳的」；
> 同名不覆盖，自动升版。
工作流 4：复盘萃取（悟）★ 传承主循环
1. review "<主题>"
→ 素材一：认识的时间线（什么时候记住的什么）
→ 素材二：认知的版本演进（v1 → vN，哪些改过）
→ 素材三：决策与操作留痕（改过什么、为什么改、回滚过什么）
2. 我基于素材起草「经验卡片」：结论 / 依据 / 适用边界 / 下次怎么做
3. 你订正后 archive 入库，并用 --links 挂到相关主题上
4. 卡片入库 → 立刻可被 find 检索到，成为下一次决策的输入
> 复盘不落纸，就等于没复盘。 素材包只是原料，卡片才是产品。
> 写卡片时保留「当时的判断」与「后来为什么改」——这两者的差，就是经验本身。
工作流 5：本地资料体检（守）
1. audit --json # 拿到结构化结果
2. audit --report # 需要留档时写出 Markdown 报告
3. 把发现的问题转成「建议清单」交用户逐条决定
> audit 永远只报告，不清理。 发现重复也不要自作主张移动或删除。
工作流 6：用户明确要求更正某处资料（理）
1. 确认用户**明确说明了**要更正哪个文件的什么
2. 执行不带 --confirm 的命令 → 拿到预览与 TOKEN
3. 把预览念给用户（含源、目标、大小），请其确认
4. 用户确认后带 --confirm <TOKEN> 执行
5. 告知操作号，说明可用 undo 回滚
工作流 7：全盘摸底（察）★ 需 L0
1. 用户首次要求「看看整台电脑」时：
grant-survey # 不带 --yes 只出授权说明，念给用户确认
grant-survey --yes # 用户同意后正式授予
2. survey --scope all # 全景：系统 + 磁盘 + 桌面
3. survey --scope tree --dir "D:/" # 想深入某个盘/目录时按需补
4. 把结果组织成人话汇报，并标注「全程只读」
> 察只采元数据，不读正文。 用户问「某盘里资料怎么分布的」用 tree；
> 用户问「某份资料在哪」用 find（需要先 grant + index 建正文索引）。
> 两条线互不替代：察不需要索引、即时可用；找需要建索引、可搜正文。
五、操作纪律（AI 必读）
- 绝不主动写。 用户没说「要更正某处资料」时，只用
find/read/audit/review/survey。 - 整理 = 出视图。 用户说「整理/归类」时，默认生成视图清单，不移动文件。
只有在用户明确指定「把 X 移到 Y」时，才走move两段式流程。 - 先预览后执行。 任何写命令都必须先跑一遍不带
--confirm的，把预览给用户看。 - 不提删除。 不要建议用户用其它工具删除；重复文件的处置建议一律是「指定保留哪份、其余移到归档目录」。
- 中文参数走文件。 内容含中文时优先用
--from-file或--stdin，避免命令行引号与编码问题。 - 需要解析结果时加
--json。 人读文本与 JSON 是两种模式，不要混读。 - 失败要报出来。 命令返回
{"ok": false}时原文告知用户原因，不要静默略过。 - 记录要主动，复盘要落纸。 用户随口说出的事实、判断、教训，主动问一句「要我记下来吗」；
复盘素材包生成后，必须推动提炼成经验卡片并入库，不要停在"素材已生成"。 - 不替用户下结论。 复盘只呈现原料（时间线/版本差异/操作留痕），
哪里是教训、哪里是运气，由用户拍板；我给草稿，不给判决。
六、常见问题
| 现象 | 原因 | 处置 |
|---|---|---|
| 检索不到任何东西 | 未建索引 / 未授权 | status → grant → index |
| 某文件搜不到但它确实存在 | 该目录未授权，或命中敏感排除 | grants 核对；敏感目录按设计不可索引 |
| 搜中文双字词没结果 | 极少见；主路走 LIKE，正常应命中 | find <词> --json 看 search_paths.fts_used |
| PDF 读不到内容 | 扫描件无文本层 | 看 excerpt_state=pdf_scanned，需走 OCR |
| doc/xls/ppt 读不到内容 | 旧二进制格式 | need_tool:legacy_office，建议另存为新格式 |
| 授权被拒绝 | 命中敏感排除规则 | 按设计如此；把资料移到普通目录后再授权 |
| 索引与实际不符 | 外部增删了文件 | verify 查看偏差，再 index |
review 说没有演进链 |
该主题还没产出过资料，或标题里不含主题词 | 先用 note → distill → archive 积累 |
survey 被拒绝 |
未授予 L0 | 先 grant-survey --yes |
诊断命令
python butler.py status --json # 数据目录 / 授权 / 索引概况
python butler.py verify --json # 索引 vs 磁盘 三类偏差
python butler.py log --limit 20 # 操作日志
七、自测与维护
python <skill>/scripts/selftest.py
自测套件会在临时目录造一套中文资料样本，跑完整链路（86 项断言）并校验铁律，
默认自动清理现场；设 BUTLER_SELFTEST_KEEP=1 可保留现场排查。
修改脚本后务必重跑自测。
八、文件结构
silicon-you/
├── SKILL.md 本文件：定位、能力、命令、纪律
├── scripts/
│ ├── butler.py 统一 CLI 入口
│ ├── butler_core.py 底座：配置 / 权限闸门 / 操作日志（铁律在此硬编码）
│ ├── butler_scan.py 扫描（只读）/ 建索引 / 对账
│ ├── butler_search.py 找 / 读
│ ├── butler_notes.py 记 + 悟：收件箱 / 归纳素材 / 资料化入库 / 复盘萃取
│ ├── butler_survey.py 察：L0 全盘只读感知（系统/磁盘/桌面/目录结构）
│ ├── butler_audit.py 守：巡检（只报告）
│ ├── butler_amend.py 理：L2 授权 + 可回滚（无删除）
│ └── selftest.py 自测套件（86 项断言）
├── references/
│ ├── safety.md 权限模型与铁律
│ ├── index-design.md 检索架构与实测依据
│ └── taxonomy.md 组织方式与命名规范
└── assets/
└── config.example.json 配置示例
参考文件（按需读取，路径相对于本 skill 根目录）
| 文件 | 内容 | 何时读 |
|---|---|---|
references/safety.md |
权限模型、三级授权（L0/L1/L2）、铁律 | 涉及写操作、目录授权、全盘感知、敏感目录被拒时 |
references/index-design.md |
检索架构、实测依据、规模基线、排查顺序 | 检索异常、需要调整检索策略时 |
references/taxonomy.md |
组织方式、分类维度、命名规范、主题词表 | 涉及归类、归纳、命名、资料库结构时 |
assets/config.example.json |
配置示例（授权目录 / 排除规则 / 命名模板） | 用户要调整配置时 |
数据存放位置
| 内容 | 路径 |
|---|---|
| 配置 | ~/.workbuddy/silicon-you/config.json |
| 索引库 | ~/.workbuddy/silicon-you/index.db |
| 收件箱 | ~/.workbuddy/silicon-you/inbox/YYYY-MM-DD.md |
| 资料库 | ~/.workbuddy/silicon-you/library/<主题>/ |
| 操作日志 | ~/.workbuddy/silicon-you/logs/operations.jsonl |
| 巡检报告 | ~/.workbuddy/silicon-you/reports/ |
| 复盘/素材包缓存 | ~/.workbuddy/silicon-you/cache/ |
可用环境变量 BUTLER_HOME 改变根目录。索引与日志放在数据目录，不放在 skill 目录，
以免打包分享时带上私人数据。若新数据目录尚未建立、而本机检测到历史数据目录，
脚本会自动沿用，不会造成记忆断档。
九、Changelog
- v1.0.0 首版
- 定位：个人记忆载体 —— 把已有的资料、随手记下的判断、改过几稿的结论、以及"为什么改"
一并收进硅基载体，可检索、可串联、可复盘。明确边界：它是记忆的载体，不是人格替身，
判断权始终归用户。 - 七类能力：找（检索定位）/ 读（抽取正文）/ 察（全盘只读感知）/ 记（记录·归纳·沉淀入库）/
悟（复盘萃取：时间线 + 版本演进 + 决策留痕）/ 守（巡检只报告）/ 理（指令驱动的受限更正）。 - 三级授权：L0 全景授权（只读感知，须
grant-survey --yes显式确认，可撤销）/
L1 目录纳入授权（可扫描、可索引、可检索）/ L2 操作授权（逐次签发令牌，用完即失效）。
L0 与 L1 互不包含；目录授权不等于写权限。 - 安全底座：工具本体不提供删除能力；敏感目录（密钥/密码/证件/财务/AppData）永久硬排除，
在 L0 之下依然生效且含文件级过滤；所有感知、索引与检索全程离线，不外发任何资料内容。 - 可追溯：资料入库同名自动升版不覆盖，带
version/derived_from；--links建双向链接
把资料聚成网络；写操作先出预览、签发 TOKEN、确认后执行，全程留痕并可整批回滚。 - 感知有界：
survey只采元数据、不读任何文件正文；目录遍历带深度 / 条目数 / 时间预算三重硬上限。 - 零依赖：仅用 Python 标准库，无需 pip 安装；docx / xlsx / pptx 通过 zip + XML 自解析，
PDF 文本层用内置解析、扫描件提示转 OCR。 - 双路检索：
LIKE子串匹配为主路（对中文 1~4 字查询友好），FTS5trigram为正文辅路。 - 自测：86 项断言覆盖完整链路与上述安全铁律。
