KV重置后身份还能找回吗capsule-identity的spark.toml自动探测与降级恢复设计【免费下载链接】capsule-identitySystem prompt builder. Assembles agent identity from workspace config and spark.toml. Part of Unicity AOS.项目地址: https://gitcode.com/gh_mirrors/ca/capsule-identitycapsule-identityastrid-capsule-identity是 Astrid OS 的系统提示词构建器负责为 AI 智能体管理 spark 身份配置并将其与工作环境组装成完整的 system prompt。它最巧妙的设计在于即使底层 KV 状态被重置身份也能通过spark.toml自动探测找回或在探测失败时优雅降级为新手引导全程不丢用户体验。一、先认识 capsule-identity智能体的身份档案室 ️把 Astrid OS 想象成一台操作系统capsule-identity 就相当于/etc/profile——系统启动时第一个加载用户身份的地方。它维护一份 spark 身份配置包含五个核心字段字段含义例子callsign智能体名字Lyraclass角色定位a precise concierge agentaura性格特质Calm, direct, and context awaresignal沟通风格Use short answers unless detail is neededcore核心指令与约束Preserve user boundaries数据结构定义见 SparkConfig默认身份名字 Astrid、角色安全编码助手见 Default 实现。当外部发出spark.v1.request.build构建请求时capsule 会从胶囊 KV 状态中加载已持久化的 spark 身份若 KV 状态为空自动探测home://.config/spark.toml附加环境上下文工作目录、平台信息将组装好的 system prompt 发布到spark.v1.response.ready。完整流程说明可参考 README.md 的 How it works 章节。二、KV 重置为什么会让身份失踪capsule 的身份状态spark 配置 onboarded标志默认持久化在 Astrid 的胶囊 KV 存储中按调用方主体隔离。这是第一层状态。问题是KV 一旦被重置升级、迁移、故障恢复智能体就失忆了——onboarded变回false用户又要重新走一遍漫长的身份引导对话之前精心调教的名字、性格、沟通风格全部归零。为此capsule-identity 采用双层持久化策略第一层KV 状态速度快用于日常会话见 IdentityBuilder 的#[capsule(state)]状态声明第二层spark.toml 文件作为恢复副本路径常量定义在 SPARK_CONFIG_PATH即home://.config/spark.toml。关键动作在save_identity工具中智能体完成身份设置后调用它身份同时写入 KV 状态和 spark.toml 文件代码注释明确写着 Persist to spark.toml so identity survives KV resets见 save_identity。三、spark.toml 自动探测机制三步判断静默复活 ️KV 重置后的第一次构建请求是恢复的黄金窗口。核心逻辑在 build_prompt_text_with_spark_loader 中当onboarded false时capsule 不会立刻弹引导而是先尝试读取 spark.toml并做三步判断KV 状态为空 │ ├─ 文件不存在 ────────────► 走新手引导Onboarding │ ├─ 解析失败 ──────────────► 记录警告日志走新手引导优雅降级 │ └─ 解析成功 ├─ callsign 为空 ────► 视为空壳文件不复活走新手引导 └─ callsign 非空 ────► 恢复身份onboarded 置 true静默复活 ✅具体实现见 自动探测分支。注意一个细节这里绕过了容错解析函数直接用toml::from_str严格解析。因为容错版本parse_spark_toml在解析失败时会回退到一个 callsign 非空的默认值若用它做探测判断会误判文件损坏为身份已恢复。这个细节体现了对降级边界的严格把控。单元测试 spark_file_loader_restores_identity_when_state_is_empty 专门验证了这条恢复路径状态为空、但提供 spark.toml 内容时prompt 直接以 You are Lyra… 开场且不出现引导文案。四、三条降级路径每种失败都有体面的出口 降级恢复设计的价值在于每一种异常状态都有确定性走向用户永远不会看到崩溃或空白场景行为用户体验✅ 探测成功身份静默恢复prompt 以身份前导语开头无感知像什么都没发生⚠️ 文件损坏/格式错误记录log::warn警告回退新手引导重新引导但不会卡死 文件是空壳callsign 为空视为未引导走新手引导重新起名避免无名智能体️ 文件不存在走新手引导首次上机的标准流程身份前导语的拼装逻辑见 build_preamble按 You are {callsign}, {class}. 性格 沟通风格 核心指令的层次组装任何一个字段为空都会优雅跳过对应段落。新手引导的文案设计也很有意思见 ONBOARDING_PROMPT它要求智能体先自我介绍、提一个开放问题、从自然对话中推导出名字和性格再让用户确认——引导本身也是产品体验的一部分而非冷冰冰的表单。五、手动恢复双通道identity-export 与 identity-import 除了全自动的静默探测capsule-identity 还暴露了一对显式 CLI 命令方便用户主动备份与迁移身份/identity-export把当前 KV 中的身份序列化为 TOML 写入home://.config/spark.toml返回导出字节数实现见 export 分支/identity-import反向读取 spark.toml 灌回 KV 状态并置onboarded true返回恢复出的 callsign实现见 import 分支。两个命令在 Capsule.toml 中注册。值得注意的能力声明 fs_read / fs_write 仅限 home://——capsule 被沙箱限制在用户主目录虚拟文件系统内读写无法越界访问这是身份数据安全的底座。典型使用姿势迁移设备前先执行identity-export备份身份新设备执行identity-import恢复若忘了导入也别慌——只要 spark.toml 在下次构建请求会自动探测复活。六、小结一份配置文件换来的失忆免疫 capsule-identity 的恢复设计可以浓缩为三个原则双写冗余身份同时落 KV快与 spark.toml稳KV 只是缓存文件才是真相探测优先状态丢失时不急着重新引导先用文件验明正身用户零感知严格降级文件损坏、空壳、缺失各有明确出口最坏情况也只是回到新手引导绝不产生错误身份。核心源码全部集中在 src/lib.rs 一个文件中含 3 组单元测试配合 Capsule.toml 的组件/订阅声明和 README.md 的 IPC 协议表是理解 AI 操作系统中智能体持久化设计的一个小而完整的范本。【免费下载链接】capsule-identitySystem prompt builder. Assembles agent identity from workspace config and spark.toml. Part of Unicity AOS.项目地址: https://gitcode.com/gh_mirrors/ca/capsule-identity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考