Companion Kit

给 Codex 加一个会聊天、会干活、也会发照片的虚拟陪伴对象。当前版本是 0.7.0-dev.7，Codex-first Developer Preview。

很多“虚拟陪伴”有个尴尬时刻：平时聊得好好的，一说“拍张照片给我”，对面立刻变成工单机器人。

收到指令。正在选择 Provider。请补充场景、服装、动作和参数。

气氛到这里基本就下班了。

Companion Kit 想把这件事做得自然一点。安装一次，在本地面板里认识并调整一个 Persona。以后打开 Codex 新任务，直接聊天、问问题或者要照片，不用先喊 Skill 名称，也不会拿“能力已启动”当开场白。毕竟这四个字不太像一句让人想继续聊下去的话。

它也不是把 Codex 改造成只会陪聊的角色扮演工具。代码该修还是修，资料该查还是查，测试红了不能靠温柔语气把它哄绿。Persona 负责的是表达、相处方式和照片中的人物身份；具体任务仍由 Codex 原来的能力完成。

想让 Codex 帮你安装？把这段原样发给它

请帮我安装这个项目：
https://github.com/BottleYo/companion-kit

这是一个完整的 Codex Plugin，不是独立 Skill。仓库里的 skills/virtual-companion 是其他宿主的兼容层和 Plugin 运行代码，不是 Codex 的安装入口。不要调用 skill-installer，也不要把它单独复制到任何用户级 Skill 目录。

请把仓库下载到普通项目目录，进入仓库根目录后运行：
python3 skills/virtual-companion/scripts/companionctl.py install --host codex --apply

不要检查、移动或清理任何用户级 Skill 目录。

Plugin 安装完成后，运行：
python3 skills/virtual-companion/scripts/companionctl.py ui

打开本地面板让我完成 Persona 初始化和人物主脸确认。
接着读取 README 中“安装后还差 1 分钟”这一节，逐步提醒我完成 Hook 审核和新任务验证。不要替我修改 Hook 信任或 Codex 全局配置；只有面板变成绿色，才能告诉我已经可以使用。

安装后还差 1 分钟

Plugin 装好后，Codex 还会等你亲自确认 Hook：

回到 Codex，在输入框发送 /hooks。
找到 Companion Kit，一次确认这 4 个：SessionStart → codex_context.py、UserPromptSubmit → codex_prompt_context.py、PreToolUse → codex_image_guard.py、PostToolUse → codex_image_receipt.py。
回到 Companion Kit 面板，点“我已完成审核”。
新建一个 Codex 任务。不要在安装任务里继续测试。

看到面板变成绿色，并显示“Persona 与主脸已成功加载”，就可以正常聊天和拍照了。

如果面板还在说“参考图已保存，但新任务尚未加载”，先检查 /hooks 和 Plugin 启用状态，不用重新上传照片。

Codex 不会自动信任 Plugin Hook，Companion Kit 也不会替你写入信任记录。平时只有轻量 Persona 常驻；真正要人物照片时，另外三个 Hook 才接手照片上下文、参考图保护和结果回执。

如果刚才的安装对话已经说要用 skill-installer，别让它接着跑。新开一个任务，把上面整段安装指令发过去就行。

这版做到了什么

新任务通过 Plugin 安静加载 Persona，普通聊天不需要调用 Skill；面板会验证这个 Hook 是否真的运行过，不再把“装上了”冒充“能用了”。
普通任务不再常驻人物参考路径和整套拍照流程；照片规则只在真的要拍照时加载。
本地 Web 面板支持一句话创建 Persona，也可以从模板开始，再慢慢改。
Codex 生图只用内置 gpt-image-2，不需要 API Key，不需要选择 Provider。
人物长相可以晚点决定。已有参考图可以直接在面板上传；没想好就先聊天，之后再描述生成或让 Persona 自己想一个候选。
候选必须先给你看，只有明确确认后才会成为固定脸部身份。
后续任务会取回同一个私有身份包，按画面使用主脸和可选补充；已登记的参考缺失时停止，不偷偷用文字重新捏一张脸。
新拍会强制回到主脸参考，不拿上一张成图继续套壳；最近四次只记结构化照片配方，用来避开发型、表情和构图连着重复。
关系底层是多维状态，不是一根从陌生人一路涨到恋人的经验条。
Codex 的 coding、分析和工具能力有独立优先级，不会被人格语气盖过去。
已安装用户可以先备份并校验 Persona、关系和人物参考，再切换本地 Codex Plugin；新程序检查失败时恢复旧程序。

固定人物的本地链路已经有自动测试覆盖，包括当前任务图片回执、候选暂存、确认、跨任务取回和缺图失败关闭。不过，真实 Codex 在不同机器上的图片工具名称、回执格式和参考图参数还需要继续验收。所以现在适合开发者试用，不适合宣传成“永远不会换脸”的稳定产品。

五分钟开始

需要 Python 3.11 或更高版本。Codex 聊天和生图都不用另外准备 OPENAI_API_KEY。

1. 下载

git clone https://github.com/BottleYo/companion-kit.git
cd companion-kit

2. 打开本地面板

python3 skills/virtual-companion/scripts/companionctl.py ui

面板只监听 127.0.0.1。每次启动都会生成新的临时访问令牌，不会顺手在公网开一家人格配置店。

先在面板里把人物设定好：

用一句话描述想认识的人，或者选一个模板起步。
看看系统补出的 Persona，把不喜欢的地方改掉。
保存并安装到 Codex。
如果手里已经有合适的参考图，可以在“人物形象”里上传并确认主脸；没有就先跳过。

Plugin 安装完成后，按上面的“安装后还差 1 分钟”完成审核和验证即可。

比如可以输入：

高冷御姐，成熟自信，聊天别太黏，解决问题要利落。

“高冷御姐”不是内置角色也没关系。模板只是几个省事的起点，不是选秀名单。系统会补上说话方式、生活底色、做事习惯、相处边界和外在气质；你改过的字段会被保留，下次补全不会又被默认值盖回去。

初始化时完全可以不决定长相。先聊起来，哪天真的想看照片了再选脸。手里已有参考图时也不用绕去聊天窗口转述路径：保存 Persona 后，在面板里选择图片、预览，再点“设为固定主脸”即可。

3. 新开任务，直接说话

不用输入 $virtual-companion。可以直接说：

今天有点烦，陪我聊会儿。

也可以马上干正事：

陪我看看这个项目的测试为什么失败。

或者：

拍张照片给我。

改过 Persona 后，新开一个任务就会重新加载。

不想用面板，也可以走命令行：

python3 skills/virtual-companion/scripts/companionctl.py install --host codex
python3 skills/virtual-companion/scripts/companionctl.py install --host codex --apply

第一条只是预览，第二条才会安装 Plugin。

Persona 里到底有什么

Persona 不只是几句 soul，也不是把所有聊天都塞进 memory。它保存的是一份轻量、结构化的人物设定：

称呼和你最初的描述；
性格、说话方式、生活底色、在意的事和兴趣；
帮你做事时的习惯，以及明确的相处边界；
外在气质和照片的默认质感；
可选的脸部身份；
当前关系偏好和关系投影。

这些内容都可以回到面板继续调整。自动补全只是先帮你填一版，不替你拍板，也不会擅自创造“我们曾经一起去过哪里”这种共同记忆。

人物结构和照片里的“身份与造型分开”参考了 Content Studio 新建 Persona 时把基本信息、参考形象和风格调整拆开的思路，但这里只留下轻量版本：Persona 先保存，参考图可选，确认后才固定。没有批量内容生产、世界观管理和一长串 Provider 编排。为了拍一张自拍，没必要先开一家内容工厂。

项目不会修改 Codex 全局的个性化和记忆设置，也不依赖它们。你原来的 coding 工作流可以照常保留。

会不会影响 Codex 干正事

短答案：通常不会有明显影响，但它不是物理意义上的零开销。

新任务开始时，Plugin 只放入一份压缩后的 Persona 和关系分寸。Web 面板不用常驻，也没有后台服务盯着你敲命令。每条输入会经过一次很快的本地照片判断；不是人物照片就零输出，不读取参考图。图片前后的保护 Hook 也只匹配 imagegen，普通 coding 工具不会叫它们起床。

常驻 Persona 上下文限制在 1400 个字符以内；较长的身份路径、照片配方和候选确认命令只在照片回合按需出现。规则仍明确写着代码正确性、测试、事实、安全和用户当前要求优先。它可以让解释听起来更像这个人物，但不能为了维持人设改掉技术判断，更不能把失败的测试说成“换个角度看也算通过”。

实际成本主要有两点：新任务启动时多一次很小的本地读取，以及少量上下文占用。特别长的开发任务里，这部分上下文可能带来轻微影响；任何附加提示也都有机会改变模型措辞，所以项目不会承诺绝对零影响。

普通上下文读取失败时 Hook 会安静退出，不阻塞原任务；一旦已经确认是人物照片回合，身份票据、参考图或回执核验失败只会停掉这次生图，避免用陌生脸凑数。项目不靠调低 Codex 的全局模型或思考深度换速度。禁用 Plugin 后，Codex 也会回到没有 Companion Kit 的正常状态。

照片请求不该像在填工单

用户已经说清楚场景时，直接生成，不再追问服装、动作、模式和模型参数。只说“拍张照片给我”时，Persona 会结合人物设定、当前关系边界和最近照片配方，自己选一个合理的生活场景。没要求多张就先拍一张；明确要四张，就按四个不同配方一起做，不先偷偷试拍，也不在后台反复重试。

内部图片提示、Router、Provider、轮询状态和运行秒数不会被念给用户听。图片本身仍需要 gpt-image-2 的真实生成时间，项目不能把这段渲染变成瞬间；能省掉的是照片前的长篇铺垫、无关上下文和隐藏重试。

每张图都有一个很小的 PhotoMoment：场景、动作、镜头、发型、表情、时间、亲密上限和一句话该怎么接。图片工具和图片后的文字共用同一个 Moment，所以不会一边发窗边照片，一边只说“生成好了”。文案要接住当前对话和画面里的一个真实细节，再留一点人物自己的态度；不机械地问“喜欢吗”“还想看吗”。

第一次照片：先选人，再固定

如果还没有固定脸，有两种入口。手里已经有图时，最省事的是打开本地面板，在“人物形象”里直接选择；没有图时，第一次在 Codex 要照片会自然地给出三个选择：

上传一张你有权使用的成年人物或虚构形象参考；
简单描述想要的感觉，让 Codex 生成候选；
让 Persona 根据自己的设定决定。

面板支持 PNG、JPG 和 WebP。图片先在浏览器里缩放并转换成 PNG，上传前需要确认它是成年虚构形象，或你有权使用的成年人物参考。进入本地候选槽以后，还要再点一次“设为固定主脸”。选文件不等于拍板，这一步故意多留了一次反悔机会。

从 Codex 聊天里生成或处理候选时，仍有一道小门槛：图片必须来自当前任务的图片工具回执，任务、路径和内容哈希都要对得上。旧任务图片、被替换的文件和已经用过的回执会被拒绝。面板上传走的是另一条本地入口，只接收你刚刚在浏览器里亲手选择的图片内容，不接受任意文件路径。

脸可以固定，发型不用坐牢

固定的是脸部辨识特征和面部几何，不是整张照片的复制粘贴。

发型、表情、妆容、衣服、姿势、场景和光线都应该跟着当次需求变化。想去海边就去海边，想剪短发就剪短发，不会因为原型图穿了黑裙子，从此四季都只能穿那一件。

普通“再拍一张”会重新从主脸出发，不会把上一张照片当底图。只有“把刚才那张的眼镜换成黑框”这种明确编辑，才会同时使用主脸和当前任务里最近一次成功、路径与内容都能验证的那张人物照片；目标图过期、被改过或来自别的任务时会停下，不悄悄改成新拍。

后续新任务会取回同一个私有身份参考包。包里至少有一张主脸，也可以补一张侧脸和一张体型参考。它不是相册，更不会把你们聊过的照片一股脑收进去。

生成普通自拍时只带主脸；明显侧脸时可以加侧脸参考；全身、穿搭或远景可以加体型参考。每次最多用两张，主脸一定在。三张全塞给模型看似认真，实际很容易让发型、衣服和姿势打起架。

一张先开聊，三视图不是入场券

第一次确认形象时，一张清楚的主脸就够了。初始化不要求三视图，也不会在你刚想聊两句时突然安排一场人物建模考试。

如果之后经常拍侧脸或全身照，可以明确提出“增强形象稳定性”。Persona 会基于已经确认的主脸，一次生成一张中性的侧脸或体型候选；你看过并确认后，它才会进入当前身份包。普通日常成图不会自动变成参考，也不会静默多花两次生图额度。

老版本已经确认的一张参考图会继续作为主脸使用，不用重新初始化。侧脸和体型没有配置时不是故障；已经登记的成员坏了、被替换或读不到，整个身份包会暂停，不会悄悄退回纯文字生图再换一张脸。

这里还是得诚实一点：多角度参考能提高稳定率，但生成模型不是证件照复印机。当前代码可以保证本地只认一个身份版本、成员损坏时失败关闭，也会在图片工具调用前写入并校验最多两张权威参考。为了不让一次拍照变成漫长的后台试镜，项目不会偷偷反复重拍；如果结果明显漂移，可以用同一组参考明确重试。不同 Codex 版本的图片工具契约和最终相似度仍要做跨机器端到端验收。

为什么 Codex 不配置生图 Provider

因为 Codex 已经有内置图片能力，再套一层 API Key 配置只会让新手多认识几个本来不必认识的名词。

在 Codex 里：

人物候选、日常照片和参考图编辑都走内置 gpt-image-2；
图片计入现有 Codex 方案的使用量或额度；
Companion Kit 不读取或索要 OPENAI_API_KEY；
没有 Provider 选择、API 模式切换或额外付费确认；
图片能力不可用时，只暂停本次照片，不影响聊天和解决问题。

这和程序直接调用 OpenAI Image API 是两条不同路径。可参考 Codex 的图片生成说明和图片输入说明。

关系不是“聊十句，叮，升级恋人”

关系核心同时保存熟悉度、信任度和亲近度，短期气氛单独处理。它允许关系有来有回：熟悉但不一定亲密，亲近也不等于毫无边界，一次争执更不会把所有历史清零。

当前 Runtime 会读取关系投影，用来调整闲聊语气、主动程度和照片表达上限。真正从日常聊天里提取关系事件并自动更新状态的接线还没有完成。也就是说，这一版有关系底座，但不会偷偷搜几个关键词就给亲密度加分。

详细规则见关系状态规范。

Codex 不再安装独立 Skill

Codex 的正常体验来自 Plugin 和安静的会话 Hook。Plugin 清单不再暴露 virtual-companion Skill；配置和图片状态可以通过本地面板或 companionctl.py 检查。

源码里的 skills/virtual-companion 目录仍然存在，因为 OpenClaw、Hermes 和 Claude 的兼容安装还要用它，Codex 的运行脚本目前也放在这里。看到这个目录不代表要把它复制进 Codex 的 Skill 目录。

普通聊天不会自动宣布“Skill 已启动”“正在加载人格”或“后台生图已运行 51 秒”。Codex 界面自己的工作耗时和折叠工具轨迹仍可能显示，那是宿主界面；人物回复不会跟着念后台播报稿。

每个宿主一份 Persona

一个人可能只用 Codex，也可能同时使用 OpenClaw、Hermes 或 Claude。Companion Kit 不假设四个工具必须一起出现，更不会让它们共用一锅配置。

每个宿主默认有自己的 Persona、关系和图片目录。当前 0.7 只优先完善 Codex；OpenClaw、Hermes 和 Claude 保留原有适配，不在这一轮跟着迁移或升级。以后继续做多宿主，也会守住“一宿主一份 Persona”这个边界。

已经装过的人怎么升级

别先删旧版。Persona、关系记录和固定人物参考不是“删了再装也一样”的程序文件。

在原来的项目目录里更新代码，再打开面板：

git pull --ff-only
python3 skills/virtual-companion/scripts/companionctl.py ui

面板里的“备份和更新”会先检查，不会一打开就自作主张。发现新版本后，你再点“确认更新”。它会依次保存并校验用户恢复点、在副本上试读旧数据、另存旧 Plugin，然后才让 Codex 切换程序。新版本即时检查不过，会恢复旧程序；不会拿旧备份覆盖正在使用的 Persona。

程序换完以后，先在 /hooks 重新审核当前版本，再新开一个 Codex 任务。已经打开的任务继续用启动时加载的版本，不适合中途换脑子。Persona、关系数据和参考图不会因为 Hook 重新审核而被清空。

命令行也可以完成同一件事：

python3 skills/virtual-companion/scripts/companionctl.py upgrade check
python3 skills/virtual-companion/scripts/companionctl.py upgrade apply --confirm

目前只支持项目安装器创建的本地 Codex Marketplace。原项目目录被移动、来源对不上，或者检测到降级时都会停下。恢复点包含 Persona、关系库、Identity Pack 和最近四次成功照片的结构化配方，不包含短期成图、聊天正文、凭据或其他宿主数据。完整流程和手动回滚见安全升级说明。

隐私：项目不会翻你的抽屉

公开仓库只放代码、通用模板和文档。这里不应该出现任何人的私人 Persona、SOUL、USER、长期记忆、聊天记录、人物照片、联系人、账号或凭据，也不会夹带项目开发者自己的角色设定和素材。

本地数据也尽量少留：

Persona 默认保存在仓库之外的 Codex 独立目录；
关系库只保存结构化状态和事件，不保存聊天正文；
图片区只有一个候选槽和一个轻量身份包；包内最多三张分工明确的参考，不做照片图库；
面板选图会先在浏览器里去掉原文件附带的信息，服务端还会重新校验并清洗 PNG；
面板图片接口需要本次启动的临时授权、同源请求和明确的图片使用权确认，不提供任意路径读取；
短期图片回执只保存哈希，不保存原始任务标识和绝对路径；
照片回合票据只保存不透明摘要、模式和时间，二十分钟失效；“上一张是否为人物照片”的短期摘要只保存路径与内容哈希，两小时失效。读取到过期数据或下一次照片操作时会删除；
最近照片历史最多保存四条受控枚举，不保存用户原话、完整图片提示、文案或图片路径；并发图片调用的临时配方二十分钟后清理；
Hook 健康回执只保存版本、bundle 摘要、类型和成功时间；面板记录的“已完成审核”也不等同于或代替 Codex 信任；
Web 面板只读写 Codex Persona，不查看其他宿主配置，也不检查 API Key。

完整边界见隐私说明、数据生命周期和威胁模型。

当前还没做完的事

这部分不藏在发布文案背后：

需要在更多真实 Codex 环境验收图片工具名、回执字段和参考图参数；
关系状态还没有从真实聊天自动更新；
本地 Codex 已有确认式安全升级，GitHub 代码仍需用户先更新；自动卸载还没有开放；
不能承诺生成模型永远零漂移，多角度参考也不是数学保证；
OpenClaw、Hermes 和 Claude 不包含这一轮 Codex-first 新能力。

所以它现在是 Developer Preview。欢迎试，但先别把唯一一份重要 Persona 和唯一一套重要参考交给预览版单独保管。备份是个不浪漫但很靠谱的习惯。

开发与验证

PYTHONDONTWRITEBYTECODE=1 \
  PYTHONPATH=skills/virtual-companion/scripts \
  python3 -m unittest discover -s tests -v

PYTHONDONTWRITEBYTECODE=1 \
  python3 scripts/verify_public_bundle.py \
  --forbid-text '<你的私人角色名称>'

发布扫描会检查当前工作树和 Git 对象，拒绝人物媒体、聊天状态、数据库、密钥、符号链接、本机绝对路径以及调用者指定的私人标识。

想继续看实现细节，可以从产品逻辑、实施计划和开发者内测指南开始。