Persome模型构建与导出完全指南:从model build到可审计的模型快照
Persome模型构建与导出完全指南:从model build到可审计的模型快照
Persome(开源项目 personal-model)是一个运行在你 Mac 本地的个人模型构建工具:它从你授权的真实活动中学会"你是如何思考与工作的",把零散观察沉淀为一份带证据链的模型快照,并支持一键构建(persome model build)、状态检查与脱敏导出(persome model export)。本文带你完整走通模型构建、查看与导出的全流程,最终得到一份可审计、可复现的 HUMAN.md 个人模型。
Persome 个人模型是什么?🧠
Persome 的核心理念是"Build your HUMAN.md"——为每个人构建一个不断进化的个人模型。它把活动流逐层抽象成五种"几何结构":
| 层级 | 含义 | 通俗理解 |
|---|---|---|
| Point(点) | 带来源的观察或事件 | 一条带"收据"的事实 |
| Line(线) | 随时间变化的关系或演进 | 事实之间的连接 |
| Face(面) | 有相关证据支撑的稳定模式 | 你反复出现的行为模式 |
| Volume(体) | 跨项目/跨领域的高阶结构 | 贯穿多个主题的主题 |
| Root(根) | 当前整合后的"你"的模型 | 此刻最重要的目标与判断方式 |
新证据可以强化、修正甚至推翻早期推断——每一条重要结论都保留了证据"收据"(receipt),这是 Persome 模型可审计的关键。
先体验:五分钟合成模型演示
不想碰自己的数据?项目提供了完全合成的演示脚本 scripts/sample_demo.py,无需 API key、无需访问你的 ~/.persome 数据:
git clone https://gitcode.com/gh_mirrors/pe/personal-model
cd personal-model
uv run python scripts/sample_demo.py
脚本会打开本地模型查看器(http://127.0.0.1:8743/model),按 Ctrl-C 后自动删除临时合成数据。加 --showcase 参数可看到更稠密的合成图谱:
一键构建模型:persome model build 详解
构建命令与常用参数
模型构建的入口只有一条命令:
persome model build
它会按依赖顺序依次跑完共享的一次性构建流水线(完整阶段定义见 src/persome/model/build.py):
- state_formation:会话压缩与基础状态写入
- evomem_baseline:evomem 节点基线回填
- schema_miner:从重复出现的持久事实中挖掘 Face
- cross_domain_sweeper:跨领域结构比对,生成 Volume
- root_synthesis:在 token 预算内压缩出至多一个 Root
常用参数:
| 参数 | 作用 |
|---|---|
--wait-seconds N |
等待其他构建占用的锁最多 N 秒(默认 30 秒) |
--no-wait |
锁被占用时立即返回 busy |
构建命令的 CLI 实现位于 src/persome/cli.py。
构建为什么"只许一个"?🔒
model build 使用独占的 model-build.lock 文件锁(由内核在进程退出时自动释放),避免多个进程同时写模型。30 分钟定时刷新、每日 00:15 守护进程调度与手动构建共享同一把锁,详见 docs/model-contract.md。
构建输出怎么看?
构建结束后,终端会打印一行汇总与清单位置:
model build: complete points=142 lines=58 faces=6 volumes=2 roots=1
manifest: ~/.persome/model-build.json
HUMAN.md: ~/.persome/HUMAN.md
三个要点:
degraded(降级)不是失败:某个语义阶段报错时,构建会如实记录degraded_stages,而不是虚构几何结构。稀疏的模型在早期是完全正常的。build清单可复现:每次构建都记录core_commit、各阶段模型名、提示词哈希、配置哈希、输入窗口、耗时等;build_id是所有其他字段内容的稳定哈希(实现见 src/persome/model/manifest.py)。固定输入与时间戳会产生相同的build_id。HUMAN.md是确定性的阅读视图:构建完成后,Persome 把当前快照确定性投影到~/.persome/HUMAN.md(权限0600,仅属主可读写)。它方便人阅读,但对机器而言,版本化 JSON 快照与构建清单才是权威。
检查构建结果:persome model status
persome model status
该命令展示实时模型就绪度、各层级计数和最后一次构建的 build_id,实现见 src/persome/cli.py。输出示例:
model: ready points=142 lines=58 faces=6 volumes=2 roots=1
build status: complete
last build: 3f9a1c2b8d4e5f6a7b0c
如果没有任何已完成的构建记录,build status 会如实报告 not_built——Persome 绝不会从当前数据库"临时拼"出一个看似成功的构建结果。
在本地查看器中"看见"你的模型 👀
persome model open # 立即打开
persome model open --after 30 # 30 分钟后自动打开
查看器运行在本机回环地址上,以星座图形式渲染你的模型:Root 位于中心,Volumes 构成内圈,Faces 向外聚成语义簇,Points 在所属 Face 周围形成稳定的局部云团。布局是追加稳定的——新证据加入时,已有节点保持原位,模型像星系一样向外生长。完整布局契约见 docs/model-contract.md 的 Viewer layout 一节。
导出模型快照:persome model export
基本用法
persome model export # 默认输出到 ~/.persome/exports/
persome model export --out ./model-snapshot.json # 指定导出路径
persome model export --raw # 显式关闭脱敏(敏感数据风险自担)
CLI 导出、MCP 的 get_model_snapshot 与 /model/graph 接口暴露的是同一个版本化 JSON schema,消费方无需直接查询 SQLite(投影实现见 src/persome/model/snapshot.py)。
快照里有什么?
顶层固定包含 9 个键(schema_version 起始值为 1,消费方必须按该字段分支):
{
"schema_version": 1,
"generated_at": "2026-07-10T09:06:00+00:00",
"build": {},
"points": [],
"lines": [],
"faces": [],
"volumes": [],
"root": null,
"receipts": [],
"stats": {}
}
stats 报告点/线/面/体/根/收据的数量以及脱敏计数;完整几何要求至少有一点、一条线、一个 Face、一个 Volume 且恰好一个 Root(字段黄金标准见 tests/fixtures/runtime_model/model_snapshot_v1.golden.json)。
默认脱敏,分享更安心 🛡️
默认导出会经过运行时的确定性密钥/PII 清洗器(src/persome/privacy/scrub.py):移除可检测的密钥、绝对路径与敏感文本类别,原子写入并把文件权限设为 0600。
⚠️ 注意:脱敏是"分享辅助"而非"完全匿名保证"——仍可能出现人名或组织名。公开发布导出内容前,建议单独做匿名化审查。
可审计性:从 Root 一路回溯到原始事实
Persome 的快照不止"好看",还能审计:
- receipts(收据):每个 Point 都有稳定的证据句柄;Face、Volume、Root 通过成员链聚合
source_receipts,可以把一句话的 Root 结论逐层展开回原始事实证据。 - 证据接口:MCP 的
resolve_evidence工具与认证端点GET /model/evidence?ref=...可解析任意引用;显式来源在sources,时间相邻的线索单独放在context,不会被误报为直接证据。 - 时间旅行:Point 保留
supersedes/superseded_by历史链,is_latest标记当前链头,旧版本仍可审计。 - 构建清单:
model-build.json记录谁(哪个 commit)、用什么提示词、在什么输入窗口上、花了多久构建出这份模型;build_id哈希校验防止清单被篡改后仍以complete状态示人。
完整的模型快照契约请阅读 MODEL_FORMAT.md 与 docs/model-contract.md,各构建阶段的写入职责见 docs/writer.md。
常见问题 FAQ
Q1:model status 显示 not_built 怎么办?
说明还没有任何完成或降级的构建。运行 persome model build 即可;若之前配置过语义模型提供方,可先执行 persome llm status --check 确认就绪。
Q2:构建提示 busy 是卡死吗?
不是。说明另一个构建(如 30 分钟定时刷新)正持有 model-build.lock。默认最多等 30 秒,可用 --no-wait 立即返回,或稍后重试。
Q3:导出的 JSON 和 HUMAN.md 有什么区别?
HUMAN.md 是确定性的本地阅读视图(含原始文本,权限 0600);JSON 快照才是面向机器、分享与复现的权威格式,默认已脱敏。请勿把 HUMAN.md 当作可安全分享的文件。
Q4:模型可以手动修改吗?
直接编辑 HUMAN.md 不是修正接口,可能被下一次投影覆盖。要修改模型内容请使用 persome correct。
总结
用三条命令掌握 Persome 的模型生命周期:
persome model build # 一键构建 Point/Line/Face/Volume/Root
persome model status # 检查就绪度与最后一次 build_id
persome model export # 导出可审计的脱敏快照
从一次 model build 到一份可回溯、可复现、可分享的模型快照,Persome 让"你的个人模型"既有工程上的确定性,又始终掌握在你自己手中。🚀

