Skip to content

feat(personas): 新增角色(含知识库)包导出与导入 / add persona bundle export and import (with knowledge base) - #71

Closed
aloasut wants to merge 9 commits into
sqfcyily:mainfrom
aloasut:pr/persona-export-import
Closed

aloasut wants to merge 9 commits into
sqfcyily:mainfrom
aloasut:pr/persona-export-import

Conversation

@aloasut

@aloasut aloasut commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

动机

角色目前锁在单机:换机、备份、分享都没有路径。而且一个「角色」往往不只是 <id>.md 一段提示词——它常带从属内容:专属技能(整目录含参考文档/脚本)、专属 MCP 服务(配置 + 加密存储的密钥)、知识库目录(personas/knowledge/<id>/,#65 的档 0 约定)、自定义头像。只导出 md 正文,另一半资产就断在现场。

功能

  • 导出:Rail 角色右键「导出角色包」→ zip(persona.md 磁盘原文 + 头像 + 专属技能整目录 + 专属 MCP 配置与密钥 + 知识库整目录 + manifest.json)。内置角色(Deva / 小码酱)不可导出。
  • 导入:花名册「+」菜单「导入角色包」→ zip-slip 守卫 + 三重限额解包 → 按 id 判定序落位:
    • 原 id 空闲 → 沿用(两台机器导入后 id 一致,任务/IM 绑定语义在消费侧可控)
    • 已被占且 personas.imports 簿记在案(同源包再导入)→ 就地更新,不产生重复角色
    • 撞了别的角色 / 外来 id / 内置 → makeId 铸新 id,绝不覆盖(主进程本无防覆盖闸,此闸由本功能显式实现)
  • 随包技能 / MCP 落地后可用角色收窄为仅该角色;随包 MCP 导入即启用(导入动作即显式意图),连接由既有 reconcile 驱动。
  • 手机端经既有 WebPersona 推送自动看到导入的角色,无新增远端面。

设计依据

完整决策与证据在 docs/plantree/plans/001-persona-export-import/(随本 PR 提交):六项决策(id 策略 / 内置不导出 / 再导入=更新 / 打包范围 / UI 入口 / 来源只进 manifest)、全角落清单、v2 设计、验证记录。

安全考虑

验证

  • pnpm typecheck 双侧 + pnpm build 通过。
  • 进程内桩冒烟 6 案全绿:导出(含内置拒绝)/ 回环+同包更新 / 冲突铸新 id 不动外来者 / originalId=general 硬闸 + 坏 manifest 拒绝 / 删除级联(簿记+头像+知识库随删)/ 缺秘密导出警告。
  • 真实数据 dry-run(~/.deva 纯读,zip 落 /tmp):两个真实角色回环与更新均字节级一致;带知识库角色(6 md / 83KB)导入后 sha256 逐一匹配。
  • 审核修正一轮:常量归位、部分带入 toast 语义、知识库缺件警告。

已知边界

兼容性

纯新增功能,无迁移。config.json 新增 personas.imports[id] 簿记键(删除角色时级联清理);其余键不动。

- 角色可打包为 zip(persona.md + 头像 + 专属技能 + 专属 MCP 含解密秘密 + 知识库目录),在另一台机器 / 另一 DEVA_HOME 导入 / bundle a persona with its avatar, exclusive skills and MCP servers (secrets decrypted), and knowledge directory for import on another machine or DEVA_HOME
- 导入按来源簿记判定:同包再导入就地更新;原 id 空闲则沿用,冲突铸新 id,内置角色永不落位 / import decides by provenance: same bundle re-import updates in place, free ids are kept, conflicts mint new ids, builtin ids are never targeted
- 侧入口:Rail 角色右键导出(内置灰显)、花名册 + 菜单导入;成功后 toast 并刷新扩展清单 / Rail context menu exports (builtins disabled), roster add-menu imports, with toast feedback and extension refresh
- personas.ts 导出目录助手(路径唯一出口)、atomic-write 支持二进制原子写 / personas.ts now exports its directory helpers as the single path source; writeFileAtomic gains a binary overload
…y in the delete cascade

- 知识库目录(档 0 约定、角色包导入会创建)此前删除角色时不清理,会留孤儿目录;与头像同等待遇一并删 / the knowledge directory (doc-0 convention, created by bundle imports) survived persona deletion as an orphan; it is now removed alongside the avatar
…fully and skip symlinks

- 导入不再经 frontmatter 重组写盘:包内 persona.md 原样落盘,手改键与未来字段(knowledge/workspace)不在往返中丢失;启用态语义不变(新建默认关、更新不动)/ imports now write the bundled persona.md bytes verbatim instead of recomposing frontmatter, so hand-edited keys and future fields (knowledge/workspace) survive round-trips; enable semantics unchanged
- 目录收集改用 lstat 并跳过符号链接:防链接环无限递归与越界拉取(对齐检查点模块的同类取法)/ directory collection uses lstat and skips symlinks, preventing loop recursion and out-of-tree pulls (same approach as checkpoints)
- 真实数据 dry-run(办公室运维助手 persona-3585c7d1)验证:回环与更新路径字节级一致,额外键保留 / verified against the real 办公室运维助手 persona: round-trip and update are byte-identical, extra keys preserved
…rt and import

- 引导 docs/plantree(README、baseline 模块键、ideas);P001 记录全角落清单、六项决策、v2 设计与验证证据 / bootstrap docs/plantree (README, baseline module keys, ideas); P001 records the persona-surface inventory, six decisions, v2 design and verification evidence
…acement, partial-import toast semantics, missing-knowledge warning

- Rail 的 BUILTIN_PERSONA_IDS 从 import 块中间移到 import 之后 / move the BUILTIN_PERSONA_IDS const out of the import block in Rail
- 导入 toast:随包技能/MCP 改名(良性 →)不再误报「部分带入」,仅真失败(write-failed/secret-unavailable 等)才提示 / import toast no longer reports benign id renames as partial installs; only real failures do
- manifest 声称带知识库但包内无对应文件时记 knowledge:missing 警告,不再静默跳过 / warn knowledge:missing when the manifest claims a knowledge base the bundle does not contain
@aloasut

aloasut commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

撤回重做:不应包含方案树文档,且需合并为单个提交。稍后以干净的单提交分支重新提交。

@aloasut aloasut closed this Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant