Skip to content

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

Open
aloasut wants to merge 1 commit into
sqfcyily:mainfrom
aloasut:pr/persona-export-import
Open

aloasut wants to merge 1 commit 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 推送自动看到导入的角色,无新增远端面。

设计决策摘要

  • id 策略:原 id 安全且空闲则沿用(两机导入 id 一致);同源包再导入就地更新(personas.imports 簿记判定);冲突/外来 id 铸新 id,绝不覆盖既有角色。
  • 内置硬闸:general / xiaomajiang 拒绝导出、导入永不落位——覆盖会毁掉种子文件。
  • 打包范围:角色本体 + 头像 + 专属技能(整目录)+ 专属 MCP(含密钥)+ 知识库目录;不打包定时任务/对话/IM 绑定(机器本地引用)。
  • 入口:导出 = Rail 角色右键菜单;导入 = 花名册「+」菜单;来源信息(originalId 等)只进包内 manifest,不污染 persona.md。

安全考虑

验证

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

已知边界

兼容性

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

…rt (with knowledge base)

- 角色可打包为 zip:persona.md 磁盘原文 + 自定义头像 + 专属技能整目录 + 专属 MCP 配置(含解密密钥)+ 知识库目录(personas/knowledge/<id>/)+ manifest;Rail 角色右键导出(内置角色灰显拒绝)、花名册 + 菜单导入 / bundle a persona into a zip (raw persona.md, avatar, exclusive skill folders, exclusive MCP servers with decrypted secrets, knowledge directory) with export from the Rail context menu (builtins rejected) and import from the roster add-menu
- 导入 id 判定序:原 id 安全且空闲则沿用;已被占且 personas.imports 簿记在案(同源包)→ 就地更新;冲突/外来 id → makeId 铸新 id 绝不覆盖;内置 general/xiaomajiang 永不落位 / import keeps a safe free id, updates same-provenance bundles in place via the provenance ledger, mints fresh ids on conflicts, and never lands on builtin ids
- persona.md 经 writePersonaMdRaw 原样字节落盘,不做 frontmatter 重组——手改键与未来字段(sqfcyily#65 knowledge、sqfcyily#49 workspace)往返不丢失;删除角色级联清理头像、知识库目录与导入簿记 / persona.md is written verbatim via writePersonaMdRaw (no frontmatter recomposition, so hand-edited and future keys survive); persona deletion cascades avatar, knowledge dir and import bookkeeping
- 安全:zip-slip 逐段守卫 + 30MB/500 文件/10MB 单文件限额;目录收集 lstat 跳过符号链接(防环递归与越界拉取);MCP 密钥导出解密进包(开箱即用的明示取舍)、导入重加密回 secrets.json,加密不可用字段跳过并警告 / security: per-segment zip-slip guards with 30MB/500-file/10MB limits, lstat-based symlink skipping against loop recursion and out-of-tree pulls, MCP secrets decrypted into the bundle (explicit trade-off) and re-encrypted into secrets.json on import with warnings for undecryptable fields
- atomic-write 支持 Uint8Array 二进制原子写;preload personas 桥新增 exportBundle/importBundle;i18n 中英文案;随包 MCP 导入即启用并收窄为仅该角色,手机端经既有 WebPersona 推送自动可见 / binary-safe writeFileAtomic, exportBundle/importBundle on the preload personas bridge, bilingual i18n; bundled MCP servers import enabled and scoped to the persona, visible on phones via existing WebPersona pushes
@sqfcyily

Copy link
Copy Markdown
Owner

感谢这个 PR,实现很完整。

不过角色的导入导出目前不在近期规划内,说明一下原因:

  • 方向还没定。未来可能会做特色角色开源分享,那时的信任模型和现在这套“本机备份 / 迁移”不一样:分享包不应携带密钥,随包的 MCP 也不能导入即启用(stdio 类型等同于执行包里指定的命令)。现在把包格式和 personas.imports 簿记定下来,之后大概率要推翻重做。
  • 现阶段有更轻的办法。需要分享时,把角色提示词、技能等打包成一个文件,由对方的 AI 读取后自行添加即可,添加过程对方可见、可控。

如果之后启动这个方向,会参考这里的实现。届时有几处需要调整,先记在这里:

  • 同源更新目前只按 originalId 判断,会直接整删并覆盖本地的知识库和技能目录,需要确认步骤和更可靠的来源判定(bundleHash 已记录但未使用)。
  • unzipSync 是先完整解压再检查限额,防不住 zip 炸弹,需要在解压过程中限制。
  • 壳层逻辑请放进 renderer/src/redesign/ 的独立文件,ChatFirstShell.tsx 只做组合。

另外说明下,我们添加了角色默认工作区,并重构了记忆,增加了角色记忆,会在下个版本发布。

再次感谢。

@DounalDash

Copy link
Copy Markdown

未来规划的角色分享的畅想:

不但是skill,还包括mcp/知识库/可以用到工具
用户下载到的角色卡,就像一个卡带,插入以后就全能继承这个技能
以前有个大佬写到一半就不写了:
https://github.com/TokenRollAI/tool-bridge

This branch has not been deployed

No deployments
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.

3 participants