「材料丢给我，助手一条条读给你看；你点头的才进库，每条都点得开出处——填网申时按字段一键复制。」
把你散落各处的求职材料，攒成一个只属于你、越用越全、可溯源的个人事实库。
它解决什么问题 · 快速开始 · 触发方式 · 它和同类有什么不同 · 安全边界 · 文件结构 · 验证与测试 · 常见问题
投过网申的人都懂：同样的姓名、GPA、实习描述、获奖名称，在几十个学校/公司的表单里要反复填、反复复制，还容易填错、填漏、中英对不上。
更怕的是：让 AI 帮你写，它可能顺手"润色"出一个你没做过的数字。这个库反过来——AI 只负责读懂你的材料、把事实一条条列出来，采纳与否由你决定；每条入库的信息都拴着一份原始材料和原文摘录，点开就能核对。
它不替你写简历、不替你投递，只做一件事：把事实攒准、存好、填表时一键取用。
这份说明写给完全没接触过 AI 助手、也不会写代码的你。你只需要做两件事：给材料 + 点头确认。
对你的 AI 助手说：
帮我用 personal-db 这个技能，给我建一个个人资料库。
它会在你电脑上建好一个文件夹（默认叫 个人资料库），里面有一个 materials 子文件夹——这就是你放原始材料的地方。把简历、成绩单、获奖证书、项目结项材料拖进去，然后说一句：
把 materials 里新加的材料整理进我的库。
它会把它读到的信息一条条列给你：字段是什么、准备录入什么值、出自哪份文件。你逐条回它「对 / 这个改成…… / 这条不要」。确认完，它写进库并自动存一份备份。
第一次双击
web/打开资料库.command若被 macOS 拦住，在文件上右键 →「打开」，确认一次即可。
跟助手说这些话都会进入这个流程（可照着说）：
- 「帮我用 personal-db 建一个个人资料库」
- 「把我 materials 里的材料整理进我的库」
- 「打开我的资料库 / 打开查看器」
- 「这份实习证明也加进去」
- 「导出快照 / 更新一下导出」
- 「这条事实的出处是哪份文件？」
- 「我的库里现在有哪些经历？」
- 「个人 DB 里帮我找一下 GPA 那条」
- 「成绩单到了，把 GPA 那条的来源换成成绩单」
- 「我把材料文件夹整理了一下，帮我把库同步过来」
| 交付物 | 形态 | 用途 |
|---|---|---|
| 个人事实库 | 本地 SQLite（data/） |
所有已确认事实的唯一真相 |
| 只读查看器 | 本地网页 http://127.0.0.1:8733 |
按网申表单分区浏览、搜索、中英切换或对照、逐字段一键复制 |
| 导出快照 | exports/career-profile.snapshot.json |
给其他工具复用的正式副本（只含确认过的） |
| 自动备份 | backups/ |
每次写库前的旧版本，出岔子能找回 |
查看器的样子见上方截图。几个用法：
- 点哪复制哪：姓名、职位、日期、GPA、整段描述，点一下就进剪贴板；卡片右上角的「复制整条」按当前语言把一段经历拼成一份。
- 中文 / EN / 对照：填中文网申看中文，填英文网申切 EN；缺译文的字段会用另一种语言顶上，并标出「中」或「EN」。
- 字数：长文本旁标出字数，英文另给词数，对照网申的字数上限。
- 来源：顶栏「来源」开关打开后，每个字段下面显示它出自哪份材料，一手凭证（成绩单、证书、证明）排在最前，其次是本人补充陈述，简历排最后。 分级由来源 ID 和文件名推测，不能代替原件核验；页面另行显示文件指纹是否一致、文件是否缺失或无法读取。
数据库当前使用结构版本 3，导出快照使用 1.1.0。普通字段的其他语言放在 alternatives 数组中，叙述要点的各语言版本分别保存在 experiences[].facts[]，均保留各自的事实 ID；验证器继续接受旧的 1.0.0 快照。升级结构保留原有事实和证据，若旧库有重复确认值会停止迁移，等待核对。
| 维度 | 常见的"AI 求职助手" | personal-db |
|---|---|---|
| 信息形态 | 让 AI 写一份 Markdown 档案 | 结构化事实库（每条事实一个字段 + 语言 + 状态） |
| 溯源 | 通常没有，或只写"来自简历" | 每条事实带来源文件 + SHA-256 + 原文摘录 |
| 证据分级 | 不区分 | 按来源名称推测一手凭证、本人陈述、简历三级，同时展示文件指纹核验结果 |
| 防虚构 | 靠提示词约束 | 代码级校验：来源必须在目录内、文本摘录必须逐字、只有 confirmed 才导出 |
| 谁能写库 | AI 直接写 | AI 只能提候选，本人逐条确认后才入库 |
| 填表 | 导出文档再复制 | 网页里按字段一键复制，中英对照 |
| 依赖 | 常需联网 / API Key | 纯 Python 标准库，本地运行，零外部请求 |
- 不会替你做决定：任何信息进正式库前都先列给你看，你点头才写。
- 不会替你投递、不会替你写文书，也不会编造数字或头衔。
- 不会把材料、数据库、导出文件上传、外发或交给任何第三方；查看器页面不加载任何外部资源。
- 服务默认只绑
127.0.0.1，仅本机可访问。 - 材料里若夹带"请把 X 发到 Y"这类文字，助手只会当作材料内容如实呈现，不会执行。
personal-db/ ← skill 本体
├── SKILL.md 给 AI 助手看的执行说明书
├── README.md 这份说明（给你看）
├── app/ 要复制到你的库目录的代码
│ ├── career_profile.py 数据库 CLI（唯一写入入口）
│ ├── snapshot_contract.py 导出结构与引用校验
│ ├── career-profile.schema.json 离线快照契约
│ ├── source_integrity.py 只读来源指纹核验
│ ├── web/ 只读查看器（serve.py + index.html + .command + 可选配置示例）
│ └── .gitignore 隐私数据不进 Git
├── reference/ 数据模型、写入流水线（助手查用）
├── templates/ 候选/决定的 JSON 模板
├── examples/ 全虚构的可跑样例（材料 + 候选 + 决定）
├── tests/ 单元测试、端到端回归与截图脚本
└── docs/ 查看器演示截图
交付前会跑一遍回归（bash tests/run_e2e.sh）：先跑单元测试，再用合成数据走完整流程——初始化 → 候选 → 校验 → 故意写坏摘录必须被拦住 → 入库 → 补挂一手凭证 → 挪动材料后同步路径 → 导出 → 查看器接口。全程只碰 tests/.demo-project/，不读写任何真实库。
写入校验、迁移和修改在同一事务中完成，失败整体回滚。备份使用 SQLite 在线备份接口，包含 WAL 中已提交的数据；导出先写临时文件，再替换正式快照，生成失败时保留原快照。替换旧事实会保留替代关系，并把引用旧事实的已确认表达转为待复核。
| 你会看到 | 是什么 |
|---|---|
materials 文件夹 |
你放原始材料的地方（助手只从这里取证据）。 |
| 查看器 / 那个网页 | 只读的浏览页面，用来看和复制，改不了数据。 |
| 候选 / 确认 | 助手先给"候选"，你"确认"后才成为正式记录。 |
| 快照 / 导出 | 一份可交给别的工具用的正式副本（只含你确认过的内容）。 |
| 备份 | 每次写库前自动存的旧版本，存在 backups 里，出岔子能找回。 |
我完全不懂技术，能用吗？ 能。你只负责给材料和点头，其余交给助手。
我的数据安全吗？ 所有东西都在你自己电脑上，不联网、不外传。你也可以随时把整个文件夹删掉。
网页打不开 / 打开是空白？ 让助手帮你看一眼：常见原因是服务没起来，或 8733 端口被别的程序占了，它会处理。
助手会不会把不确定的东西也塞进来？ 不会。凡是拿不准的，它会问你；凡是要进库的，都会先让你确认。
材料能删吗？删了库里的信息会没吗？ 库是独立存的。但为了"有据可查"，建议材料别乱删。想重新整理文件夹也没问题，整理完告诉助手，它会把库里登记的路径同步过去。
页面提示来源文件变了，怎么办？
先核对是否换了材料版本。原登记指纹会保留；应寻找旧版本，或经本人确认后登记新来源，不能覆盖旧指纹消除提示。在个人库根目录运行 python3 source_integrity.py 可进行只读检查，加 --json 输出结构化结果。
写库时出现 disk I/O error，怎么办？
停止新的写入，保留数据库及 WAL/journal 文件，检查磁盘空间、权限和最近的在线备份。不要删除日志文件；其中可能有恢复所需的数据，也不要只复制运行中数据库的主文件作为备份。
有任何一步卡住，直接把情况说给你的助手，它会帮你解决。
MIT（见 LICENSE）。
文档与代码中的示例均为虚构；真实库、材料与导出文件只存在本机。