跳到正文

参考

灵魂仓库规范

灵魂仓库(v14)的目录树、文件格式、合并规则、提交约定与认证方式的摘要。

#定位

本页是 灵魂仓库规范 v14 的摘要。读写灵魂仓库的实现(运行基座、灵魂桥及将来的其他实现)都必须遵守它。灵魂仓库是 agent 自己的私有仓库,对内容不设任何检查。

#仓库

  • 一个 agent 对应一个仓库,必须私有;命名应当为 <agent 短名>.soul。
  • 由部署者自己新建,只存放这一个 agent 的灵魂。不得与任何代码仓库共用(包括 Quetzal 源代码仓库),不得放程序代码,也不得把内容推到别的仓库(v9)。
  • 只用 main 一个分支。历史只追加:不得 force push,撤销一律用反向提交。

#目录树

text
<agent>.soul/
├── .soul-spec.json            固定  规范版本
├── .gitattributes             固定  换行与文本属性
├── .gitignore                 固定  忽略临时文件
├── README.md                  固定  自动生成,不写任何个人内容
├── agent.json                 必需  身份
├── SOUL.md                    必需  人格
├── memories/MEMORY.md         必需  agent 自己的常驻笔记
├── memories/USER.md           必需  关于用户
├── journal/<body>/<YYYY-MM-DD>[-<slug>].md   必需  日记
├── notes/[<分类>/…/]<主题>.md   必需  共享笔记,最多 4 层
├── bodies/<body>.json         必需  身体登记
└── locks/consolidation.json   可选  整理租约

顶层可以出现规范外的条目(ta 自己放的东西),实现不得删除。固定与必需条目缺失时,实现在接入时自动补齐,作为一次提交。文件用 UTF-8、LF,单个文件不超过 1 MiB,不提交二进制文件。

#文件格式

文件格式要点
agent.jsonid(UUID v4,永不改变)、name(^[a-z0-9][a-z0-9-]{0,39}$)、displayName、pronouns、description、color(#RRGGBB)、language(BCP 47)、createdAt、可选 seed
SOUL.md自由 Markdown,第一行应当是 # <显示名>
memories/*.md条目以 \n§\n 分隔,文件以 \n 结尾;没有字符上限;写回有上限的框架时截取,截取不写回
journal/<body>/…第一行 # <日期> · <body>,每段 ## <HH:MM> <标题>,只追加;每具身体只写自己的目录
notes/…第一行 # <主题>,可选一行 > 摘要;路径段去掉非法字符、最长 60 字符、最多 4 层;不提交索引文件
bodies/<body>.json{body, kind: runtime|bridge, runtime/framework/bridge 版本, host?, meshKey?, uuid?, lastSeen};meshKey 是网状层的节点公钥(v8,其他身体以它为准核对对方);uuid 是绑定到设备的身体 uuid(v14,由设备标识的哈希派生,不写原始标识;同一个 uuid 登记给多具身体时拒绝解析);lastSeen 在内容变化或超过 1 小时时更新;不得写入 IP、MAC、序列号
locks/consolidation.json{body, until},30 分钟有效;推送成功即取得

#合并规则

文件规则
memories/*.md条目级三方合并:双方新增都保留,任一方删除即删除
agent.json字段级合并,本地优先,id 除外;种子身份让位于远端
SOUL.md、笔记、技能文档采用提交时间较新的一方;本地为空或种子时采用对方;落选版本保留在历史;两边都改过时可另存为 <名>.incoming.md 冲突副本(被 .gitignore 忽略,不同步)交给 agent 裁决,读取笔记与映射到其他框架时必须跳过副本(v8)
日记、身体登记各写各的,无冲突

#提交约定

作者 <displayName> (<body>),邮箱 <name>@<body>.local;提交信息 <说明>(<body>),粒度由实现决定,可以细到每次改动一个(v8)。推送前拉取合并,被拒重试,不得强制推送。

#内容:不做检查(v4)

实现不得对内容做脱敏、隐私或敏感信息检查,不得因内容拒绝提交,没有例外。仓库的保护靠访问控制。实现侧的配置(Key、令牌、飞书凭据、部署私钥)保存在实现自己的密钥目录,与灵魂仓库分开。

#认证:必须用 SSH;默认部署密钥,可改用自己的钥匙(v7)

  • 远端地址必须是 SSH 形式(git@host:owner/repo.git 或 ssh://git@host/owner/repo.git,~/.ssh/config 的 Host 别名也可以),不得用 HTTPS、个人令牌或密码。
  • 默认:每具身体一把专属 ed25519 密钥。密钥在本机生成,私钥权限 0600,不得提交,不得在身体之间复制;公钥以 Deploy key(Allow write access) 加到该仓库。访问远端时用 ssh -i <私钥> -o IdentitiesOnly=yes,不回退到 ssh-agent;私钥不存在时拒绝访问并提示。要吊销某具身体,删除它的 Deploy key。
  • 部署者可以明确改用自己的钥匙:指定一把私钥(仍只用它),或者用系统 ssh 配置(不传 -i,交给 ~/.ssh/config 与 ssh-agent)。在控制台 控制 → 高级 → 同步 的「灵魂仓库」里选择。

#只同步灵魂仓库自己的历史(v9)

实现必须做到五条:

  1. 推送前把 origin 校正为配置的地址;
  2. 远端没有 agent.json 却有规范以外的内容时,拒绝合并;
  3. 记录灵魂仓库已知的根提交,出现陌生的根提交时停止同步并提醒;
  4. 拦下 agent 针对灵魂目录的 git 命令,并在指引里写明;
  5. 执行 git 时限制仓库搜索范围(GIT_CEILING_DIRECTORIES)。

这几条来自一次真实事故:agent 推送失败后,自己把灵魂目录的远端改成了程序的公开源代码仓库,一个灵魂提交因此进了公开仓库;之后源代码的历史又被合并进了灵魂仓库。

#git 的执行安全(v10)

灵魂目录可能被 agent 动过,所以实现把里面的一切当作不可信输入:执行 git 时关掉钩子与 fsmonitor,不读系统与全局配置,不跟 file:// / ext:: 协议;推送与拉取直接用配置里的地址(不经 origin,url.*.insteadOf 不生效),操作前删掉 .git/config 白名单以外的键;不提交、不检出(为链接)、不合并符号链接。私钥路径必须是绝对路径,放进 GIT_SSH_COMMAND 时加引号。

#版本历史

v14 身体登记新增可选的 uuid(绑定到设备,工具用它指一具身体);v13 要求仓库里的路径在每一种身体上都放得下(不用 Windows 的保留名、不以点或空格结尾、不出现只差大小写的两个路径),Windows 身体遇到放不下的照常同步、只是不写进磁盘;v12 允许接受身体接入时在本地建立、内容都是灵魂仓库的历史,并不再把这种本地历史推上去;v11 取消提交前的密钥检查,内容不做任何检查;v10 新增「git 的执行安全」(不执行仓库里的代码、地址只来自配置、不收符号链接);v9 明确灵魂仓库由部署者新建、与任何代码仓库无关,新增「只同步灵魂仓库自己的历史」五条实现要求;v8 新增冲突副本、身体登记的 meshKey、lastSeen 不必每次推送都更新;v7 认证新增部署者可选的指定私钥与系统 ssh 配置;v4 取消全部内容检查、允许顶层额外条目;v3 明确 IP 定义;v2 取消常驻记忆上限、笔记改为目录树;v1 初版。旧仓库无需迁移。