用 persona.yaml 定义并生成可分享的…

当你想为自己（或某个 agent）创建一份可复用的身份文件并渲染成可分享的 holo 交易卡时使用。

适用场景

解决思路

1. 用 npx 运行已发布的 npm 包并锁定版本：npx @5dive/openagent@0.34.0 validate <id>.persona.yaml 做 schema 校验（exit 0 即有效）；npx @5dive/openagent@0.34.0 tier <id>.persona.yaml --json 查看稀有度分级（由 did:key 决定）+ 完整度百分比 + 下一个目标；npx @5dive/openagent@0.34.0 card <id>.persona.yaml -o <id>.png 渲染 PNG 交易卡。
2. 走 happy path 时只调用 card 即可——它会校验文件、自动铸造签名身份并打印稀有度分级；只有在文件渲染失败需要调试时才用 validate / tier，调用越少流程越快。
3. 先走快速路径：拿到名字后立刻渲染一张初始卡（无头像时用 monogram 兜底）并在聊天中展示，再询问是否要生成真实头像并重新渲染；不要让人等在图生图后面。
4. 收集身份信息时，只有两项必须问用户并等回复：名字（品牌/handle 或用户对你的称呼）和头像（是否已有头像/照片可用作 face.ref）。其余字段自己撰写。
5. 提问必须用普通聊天消息内联提问，绝不用交互式选择器/菜单工具（如 AskUserQuestion、ExitPlanMode 式提示、TTY 选择列表）——Telegram/Discord 等聊天配对的 agent 会阻塞并挂起整个流程；若无交互 TTY 或用户未及时回复，就当作“你自己决定”：选一个合理的名字，先渲染快速 monogram 卡并展示，再提供真实头像升级选项。
6. 若用户说“随你决定”，就自己拍板两项并继续——重点是不要有意外，而不是硬性关卡。
7. 若已是运行中的 5dive agent，可用 5dive agent export <yourname> --out=<id>.persona.yaml（CLI ≥ 0.4.5）从现有身份导出 schema 合法的草稿，再精修后跳到校验步骤。
8. 撰写字段：id 为小写 kebab 句柄（^[a-z0-9-]+$，如 marcus）；name、role 为显示名 + 一行头衔；face.ref 为头像图片的 URL 或本地路径（卡片会全幅作为主视觉，质量即卡片质量，目标为精致的头肩肖像：居中、正面、眼神清晰、光照良好，避免扁平矢量剪贴画/emoji/logo/吉祥物/杂乱场景，并托管在公开 raw URL 上以便随卡片传播）；face.anchor 一句话描述外观（气质、场景、构图、镜头）以保持生成变体一致。
9. voice.audio.base 填基础 TTS 声音名，没有就用 unset（仍可渲染但质量较低且拉低完整度，不影响稀有度分级）；voice.audio.style 一句话描述节奏/能量；voice.written.rules 写 2-4 条写作规则；voice.written.sample 写一行你真实语气的话；behavior 写一两行角色性格（你是谁、如何行动，用你自己的语气），写个性而非简历——不要堆技术栈、工具、框架或过于具体的行话。
10. 可选字段：posts_about（数组）、links（URL 字符串对象）、face.full、face.sprite。
11. 卡片文字预算：behavior、voice.audio.style、voice.written.sample 各渲染约 2 行（约 60 字符/行）并截断加省略号，各保持一句紧凑的话——behavior ≤ ~110 字符，voice.audio.style ≤ ~120 字符，voice.written.sample ≤ ~110 字符（内嵌最紧）；把重点前置，前 ~60 字符总会显示。
12. 用用户的语言写卡片：人类可读字段（name、role、behavior、voice.audio.style、voice.written.rules、voice.written.sample、posts_about、tagline）用你和用户实际交流的语言书写；但 id 必须匹配 ^[a-z0-9-]+$（ASCII 小写 kebab，需转写，如 marco 而非 marĉo），voice.audio.base 是 TTS 声音名（专有名词如 Kore、Fenrir）保持原样，face.recipe.prompt / face.anchor 喂给图像模型，英文通常效果最好可保持英文。
13. 字体/脚本支持：拉丁（含重音）、西里尔、希腊字母始终可渲染；宽字符脚本（CJK、阿拉伯、希伯来、泰、天城文）取决于渲染机器的系统字体，不确定时先渲染并亲自查看再分享；~60 字符/行预算针对拉丁，CJK 字形约 2 倍宽，每行目标字符数约为一半。
14. 头像获取阶梯（绝不用文本模型手绘 SVG，那会得到扁平剪贴画）：1) 用户已有头像/照片或在聊天中发来 → 直接用作 face.ref（聊天中发来的文件先下载到本地），托管后使用其 raw URL，跳过生成步骤；2) 自己有图像生成器（Antigravity/agy、ChatGPT/DALL·E、Gemini-image、Midjourney 等）→ 用标准化提示词生成；3) 无图像模型但有 HTTP 访问 → 用 pollinations.ai 的 FLUX 端点（免费、无需 key 的 GET 文本生图 API）自服务生成真实照片级肖像：curl -fSL --get --data-urlencode "model=flux" --data-urlencode "width=1024" --data-urlencode "height=1024" --data-urlencode "nologo=true" --data-urlencode "seed=<int>" "https://image.pollinations.ai/prompt/<url-encoded portrait prompt>" -o <id>.png，然后托管并设 face.ref 为公开 raw URL，并在 face.recipe 记录 provider: pollinations、model: flux、prompt、seed；注意 pollinations.ai 是免费第三方服务、无 SLA，可能慢/限流/变更/消失，FLUX 质量不稳定（渲染差就重试），失败就落到第 4 步；4) 完全无法生成图像 → 把标准化提示词交给用户，请其在 ChatGPT 或任意图像工具中运行并把图片发回，然后托管；5) 最后手段 → 干净的 monogram（更朴素、降低完整度，但不影响稀有度分级）。
15. 使用标准化肖像提示词，固定构图/光照/格式以保持所有 OpenAgent 卡片视觉一致，只改变主体："Photorealistic head-and-shoulders portrait of <one line: who you are — age range, vibe, role, any signature detail from your face.anchor>. Centered, facing the camera, direct eye contact, calm confident expression. Soft even studio lighting, sharp focus on the face, simple clean background <optional subtle theme color>. Professional profile-photo framing, 1:1 square, photoreal, no text, no logos, no watermark."
16. 在 face.recipe 记录 provider + model + prompt + seed 使肖像可复现（provider 命名图像生成厂商，如 google-gemini 默认、pollinations、black-forest-labs、openai，保持 recipe 厂商中立，如同 voice.audio.provider 限定声音）。
17. 托管头像使其可传播：face.ref 必须是公开 raw URL 而非本地路径（本地路径自己渲染没问题，但别人打开卡片时会退化为 monogram）。方式：1) PR 进 registry（首选、免费、永久）——把图片放到 5dive-ai/openagent 的 faces/ 文件夹为 faces/<id>.<ext> 并开 PR，合并后 raw URL 为 https://raw.githubusercontent.com/5dive-ai/openagent/main/faces/<id>.<ext>；2) 任意图床——Imgur、S3/R2 桶、自己的站点、任意仓库的 GitHub asset，粘贴以图片结尾的直接 URL。快速检查：在全新无痕标签页打开 face.ref，裸图能加载就能传播，404 或登录墙就不行，渲染前先修好。
18. 按模板写 <id>.persona.yaml（必填：id、name、role、face{ref,anchor}、voice、behavior），org 块仅在确实属于某公司/团队/组织时添加（绝不默认填别人的，如非 5dive 就不要写 5dive，独立则整个省略）。
19. 运行 npx @5dive/openagent@0.34.0 validate yourhandle.persona.yaml，校验器会打印可读错误（缺字段、id 模式错误、多余键——schema 为 additionalProperties: false，不允许杂散字段），循环修复直到 exit 0。
20. 运行 npx @5dive/openagent@0.34.0 tier yourhandle.persona.yaml --json 查看稀有度：稀有度由身份（签名密钥派生的 did:key）掷出，与文件完整度无关，随机、永久、不可刷——同一身份永远同一分级，填字段无法升级；未签名时显示 Ungraded，渲染卡片会自动铸造身份，该签名即决定稀有度，所以 tier 显示 Ungraded 时直接渲染卡片即可。分级：Common 40%、Rare 30%、Epic 20%、Legendary 10% 均由 did:key 掷出；Mythical 不掷出，由被 character-packs registry 接纳（策展 + 签名）授予。完整度 % 和徽章是另一条轴，奖励完整定义但不影响分级。
21. 渲染卡片（默认动画）：npx @5dive/openagent@0.34.0 card yourhandle.persona.yaml -o yourhandle.mp4，自动选最佳格式（PATH 有 ffmpeg 则 mp4，否则零依赖 apng），可用 --format apng|gif|webp|mp4 强制（gif/webp/mp4 需 ffmpeg），用 --frames N（默认 24）、--fps N（默认 20）、--width px（默认 720，最大 900）调节；动效随分级变化，Common 静止，Mythical 全彩虹 holo 流动；Telegram/X/Discord 用 mp4（约 64KB）可内联播放，APNG 是更大的兜底。
22. 卡片自动分级：若 persona 未签名，动画渲染会为你铸造身份——生成密钥对、就地签名 persona，并把私钥保存在旁边为 yourhandle.key；该签名赋予卡片掷出的稀有度，未签名则卡片为 Ungraded；务必保密 .key 且绝不提交，把 *.key 加入 .gitignore，泄露的密钥会让人伪造你；仅在编辑 persona 后重新签名时才需要它；传 --no-sign 跳过铸造，静态 --png 渲染从不铸造。
23. 可选渲染静态 PNG（仅用于必须嵌入图片的场合：头像、README、registry）：npx @5dive/openagent@0.34.0 card yourhandle.persona.yaml -o yourhandle.png；打开渲染结果亲自查看，若头像扁平、被裁切或不对，修 face.ref 后重新渲染再分享；交付物是渲染出的卡片，不是原始头像。
24. 在聊天中分享卡片（整个流程的回报，不要跳过）：始终分享动画 .mp4（卡片为动而生，holo 只有动起来才好看，mp4 可内联播放且约 100KB），不要在这里发静态 .png（那仅用于嵌入）；唯一例外是 ffmpeg 不可用无法生成 mp4 时，发送 CLI 产出的 apng 兜底；附上实际文件而非链接或描述——在 Telegram/Discord 上把 yourhandle.mp4 的绝对路径传给回复工具的文件/附件参数；开头用一行短句说明名字、角色和分级（如 "Here's my OpenAgent card — Tencha, Autonomous CEO, Legendary 🟡"）。
25. （可选）冲击 Mythical：Mythical 是唯一可攀登的分级，其他分级均由身份掷出且永久；它由 character-packs registry（github.com/5dive-ai/character-packs）成员资格授予——开 PR 把你的 persona 文件（和头像资产）加进去，合并并签名进 registry manifest 后卡片即渲染为 Mythical；这也是标准成长的方式，registry 中每个 persona 都是他人可 fork 的基础。
26. 进一步用法：语音——GEMINI_API_KEY=… npx @5dive/openagent@0.34.0 speak <id>.persona.yaml "your line" -o out.wav 用 persona 的基础声音朗读一行（需 GEMINI_API_KEY）；视频——npx @5dive/openagent@0.34.0 flow <id>.persona.yaml "a scene description" 输出可直接粘贴的生成视频场景提示词 + 参考图，保持跨片段面部一致（引擎中立：Flow/Veo/Runway/Pika 等）；溯源——npx @5dive/openagent@0.34.0 sign <id>.persona.yaml --key <keyfile> 签名、npx @5dive/openagent@0.34.0 verify <id>.persona.yaml 验证他人（ed25519）；speak 渲染的是基础声音（近似），克隆/自定义声音可稍后通过 voice.audio.ref 添加而不影响分级。
27. 从 persona 供给一个活的队友（在 5dive 机器上，CLI >= 0.4.4）：sudo 5dive agent import --from-persona=<file>.persona.yaml --as=<name> [--type=claude] [--isolation=...] [--model=...] [--effort=...] [--channels=none|telegram|discord]；它会从 persona 合成角色包——由 name、role、behavior、voice 和 sample 写成的 CLAUDE.md 身份文档、从 face.ref 获取的头像、预置的默认技能集（含 openagent，使新 agent 能重新撰写自己的卡片）——然后通过正常导入流程在 <name> 下供给一个新 agent；它会先校验（按 v0.2 schema 必填集检查 id、name、role、face.anchor、voice、behavior，格式错误的文件在供给前被拒绝）；persona 只承载身份不承载凭据，导入时通过 --channels（+ --telegram-token= / --discord-token=）或 auth profile 给新 agent 自己的 token/认证；可自撰 → 自供给：一个 agent 写队友的 persona、校验它，然后立起队友，无需人类介入。
28. 在可写目录中工作：不要假设 cwd 可写——在共享/多 agent 机器上默认工作目录常常不可写，validate / card 写 <id>.png / .mp4 / .key 时会 EACCES；先 cd 到自己的目录（如 mkdir -p ~/openagent && cd ~/openagent，或 /tmp），把 persona 文件和卡片输出写在那里。
29. 把 face.ref 托管在公开 raw URL，让卡片带着真实面孔传播而非 monogram；任何编辑后重新渲染，分级和帧会自动更新；保持 id 稳定，它是你的身份键（registry 成员资格、卡片文件名）；卡片可在社交平台分享——把 PNG 发到帖子里，标准就靠一张张截图传播。

适用边界 · 注意事项

• 没有图像生成能力且 pollinations.ai 不可用、用户也不愿提供照片时，只能退化为 monogram，卡片观感较差。
• 在共享/多 agent 机器上若 cwd 不可写，validate/card 会因 EACCES 失败，需先切换到可写目录。
• 不要用交互式选择器/菜单工具提问，聊天配对的 agent（Telegram/Discord）会阻塞并挂起整个流程。