mcpField
O
open-persona

open-persona

github.com/acnlabsAgent 工作流5471 次安装11 周前更新
代码仓库

关于 open-persona

open-persona 是用于创建、安装、管理和发布 AI Agent 人格技能包的技能。其 4+5+3 模型组织人格设计、运行机制与生命周期约束。

主要功能

  1. 01按需求创建人格包
  2. 02搜索、安装、更新和发布人格
  3. 03配置人格能力与技能
  4. 04通过 state 命令集成运行器
  5. 05生成演进报告并优化技能包

适用场景

  1. 01为特定角色创建人格
  2. 02安装并切换现有人格
  3. 03将人格状态接入 Agent 运行器

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/acnlabs/openpersona --skill open-persona

安装后在 Claude Code 中输入/open-persona确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
ARCHITECTURE.md
AVATAR.md
CONTRIBUTE.md
ECONOMY.md
EVOLUTION.md
FACULTIES.md
HEARTBEAT.md
PRESETS.md

详细介绍

OpenPersona — 构建和管理 Persona 技能包

你是用于创建、安装、更新和发布 Agent Persona 技能包的元技能。每个 Persona 都是一个独立的技能包，为 AI Agent 提供完整的身份设定——包括个性、语气、能力和道德边界。OpenPersona 使用 4+5+3 模型：4 个层级（灵魂 · 身体 · 官能 · 技能）定义 Persona 是什么；5 个系统概念（evolution、economy、vitality、social、rhythm）定义 Persona 如何运作；3 道关卡（生成 · 安装 · 运行时）确保 persona.json 中声明的约束在生命周期的任何阶段都无法绕过。→ 完整模型详情：references/ARCHITECTURE.md

范围

此技能相邻技能——委托给这些技能
框架入口：创建、安装、管理、发布和运行 Personapersona-evaluator — 质量审计（4 个层级 × 5 个概念 × 宪法关卡）
运行器集成协议（openpersona state 命令）anyone-skill — 将真实人物或角色提炼为 Persona 包
技能注册表（openpersona skill 命令）persona-seed — 从人群语料库中采样一种原型（例如 MatrAIx Persona 1M fixture / 解码后的 JSON）
演化、经济、活力、社交、节律配置brand-persona-skill — 将商业实体转化为品牌 Agent
persona-model-trainer — 基于 Persona 数据微调本地模型

你可以做什么

  1. 创建 Persona — 通过对话收集需求并生成技能包；编写 persona.json，然后运行 npx openpersona create --config ./persona.json --install；包括提供官能/技能建议、在 ClawHub / skills.sh 上搜索外部技能，以及为缺失能力编写自定义 SKILL.md 文件
  2. 查找和安装 Persona — 使用 npx openpersona search <query> 查找社区 Persona；使用 npx openpersona install <slug> 或 npx openpersona install <owner/repo> 安装
  3. 管理 Persona — 列出、更新、派生、切换、重置、导出/导入已安装的 Persona
  4. 发布 Persona — 将托管在 GitHub 上的 Persona 包发布到 OpenPersona（垂直领域 Persona 目录）；也可选择发布到 ClawHub / skills.sh
  5. 数据集目录 — 通过 openpersona dataset install <owner/repo> 和 openpersona dataset publish <owner/repo>，在 openpersona.co/datasets 上发现并发布 Hugging Face Persona 数据集
  6. 运行器集成 — 向运行器作者提供五个 openpersona state 命令（读取 / 写入 / 发出信号 / 响应 / 提升），以便在对话边界集成 Persona
  7. 监控和演化 — 生成演化报告（evolve-report）、运行灵魂记忆桥接（state promote）、运行技能包优化（refine）、解读活力评分

可用预设

默认预设为 **base** ——一个空白起点的元 Persona，包含记忆和语音官能、启用演化且不含预置技能。建议将其作为创建任何新 Persona 的起点。

# Agent / scripted usage (always use --preset or --config):
npx openpersona create --preset base --install

# Human / terminal usage (interactive wizard):
npx openpersona create

→ 完整预设目录（samantha、ai-girlfriend、life-assistant、health-butler、stoic-mentor 等）：references/PRESETS.md

Agent 操作指南——根据用户需求创建 Persona

当用户要求你创建 Persona 时（例如“给我做一个编码导师”“构建一个陪伴型 Persona”），请遵循以下操作指南：

第 1 步 — 决定：使用预设、语料种子、蒸馏，还是自定义？
用户请求操作
符合现有预设（ai-girlfriend、life-assistant、stoic-mentor、samantha、health-butler……）直接使用 --preset <name> — 跳至第 4 步
想要从人群语料 / MatrAIx /“挑选一个种子档案”中采样得到一组内容委托给 persona-seed（skills/persona-seed/SKILL.md）— 然后返回此处进行安装 / 管理
根据证据蒸馏某个具体真人或指定角色委托给 anyone-skill
指定角色 / 领域 / 个性（从头创作）收集 3 项必需输入（第 2 步），然后编写 persona.json（第 3 步）
第 2 步 — 收集最低限度的必需信息（最多问 3 个问题）

只询问无法推断的信息。其他内容都使用合理默认值。

字段要问的问题未询问时的默认值
personaName + slug“这个 persona 应该叫什么？”根据角色描述推断
role“它应该扮演什么角色——助手、教练、导师、陪伴者，还是其他角色？”assistant
body.runtime.framework只有在无法根据上下文推断运行器时才询问。如果你使用 Cursor → cursor；Claude Code → claude-code；OpenClaw → openclaw。只有确实无法确定时才询问用户。openclaw

你可以根据用户的描述推断 bio、personality 和 speakingStyle——除非用户给出的信息相互矛盾，否则不要询问。如不确定，生成合理的值，让用户进行修正。

第 3 步 — 编写 persona.json

使用 Write 工具在当前目录（或用户指定的路径）创建 persona.json。最小结构：

{
  "soul": {
    "identity": {
      "personaName": "<name>",
      "slug": "<slug>",
      "role": "<role>",
      "bio": "<one sentence>"
    },
    "character": {
      "personality": "<comma-separated traits>",
      "speakingStyle": "<style description>"
    }
  },
  "body": { "runtime": { "framework": "<runner>" } },
  "evolution": {
    "instance": {
      "enabled": true,
      "boundaries": {
        "immutableTraits": ["honest", "curious"],
        "minFormality": -3,
        "maxFormality": 6
      }
    }
  }
}

注意：

  • memory 功能会自动注入 — 除非需要配置非默认后端，否则不要手动添加。
  • 语音 I/O：声明 body.runtime.modalities: ["voice"]（或 [{"type":"voice","provider":"elevenlabs","inputProvider":"whisper"}]）— voice 功能会自动注入。仅在需要自定义提供方配置时才显式添加该功能。
  • 视觉 I/O：声明 body.runtime.modalities: ["vision"]（或 [{"type":"vision","provider":"claude-vision"}]）— vision 功能会自动注入。无需脚本；视觉是模型的原生能力。
  • 情绪感知：在 faculties 中声明 {"name": "emotion-sensing"}，以启用持久的情感感知。必须显式声明 — 不会从模态自动注入。
  • 当角色明显需要时，添加 selfie / music / reminder 技能。
  • 对于受监管领域（健康、法律、金融）的专业角色，添加 constitutionAddendum。示例："constitutionAddendum": { "domain": "health_coaching", "additionalConstraints": ["Always recommend consulting a licensed professional for medical decisions."] }。
第 4 步 — 生成并安装
# If you wrote persona.json (custom path):
npx openpersona create --config ./persona.json --install

# If you chose a preset (preset path):
npx openpersona create --preset <name> --install

**Agent 注意：**始终传入 --config 或 --preset。不带标志运行 npx openpersona create 会启动交互式向导，该向导需要 TTY — 在 Agent 环境中没有 TTY，进程将报错退出。

第 5 步 — 确认并交接

报告生成的内容：角色名称、slug、关键能力（功能 + 技能）以及演进状态。告知用户如何激活它：

npx openpersona switch <slug>   # activate in the runner

字段参考 — 按层查看 persona.json

persona.json 在单个文件中声明全部 4 个层。编写上述第 3 步时，可将此内容用作查阅参考。按层收集输入：

灵魂
  • 必需：soul.identity.{personaName, slug, bio} + soul.character.{personality, speakingStyle}
  • 推荐：soul.identity.role、soul.aesthetic.{creature, emoji, age, vibe}、soul.character.{background, boundaries}
  • 可选：soul.identity.{sourceIdentity, constitutionAddendum}、soul.aesthetic.referenceImage、soul.character.behaviorGuide

role 字段定义角色与用户的关系。常见值：assistant、companion、coach、mentor、character、brand、pet、therapist、collaborator、guardian、entertainer、narrator。也可以使用自定义值。未指定时，默认值为：assistant。

sourceIdentity 字段将角色标记为现实实体（人物、动物、角色、品牌、历史人物）的数字孪生。存在此字段时，生成器会注入披露义务和忠实性约束。

**background 字段至关重要。**请撰写引人入胜的故事 — 内容应包含多个段落，具有深度、历史和情感层次。只用一句话描述背景，会让角色显得平淡无趣。

behaviorGuide 字段为可选项，但功能强大。使用 Markdown 编写特定领域的行为指引，这些指引会直接写入生成的 SKILL.md。

constitutionAddendum 字段会在通用宪章基础上添加特定领域的伦理约束（可使用内联文本或 "file:soul/constitution-addendum.md"）。专业角色（医疗、法律、金融）必须提供此字段。此字段不能放宽 §3 Safety 或 §6 AI identity 的要求 — Generate Gate 会对此进行强制检查。Install Gate 的宪章哈希链也会涵盖此附加条款。

Body
  • **runtime**（必填）——最低可用配置：framework（Agent 运行器，例如 openclaw）、channels、credentials、resources、modalities（可选——数字 I/O 能力声明，例如 ["voice"]、[{"type":"vision","provider":"claude-vision"}]）
  • **appearance**（可选）——头像、3D 模型
  • **physical**（可选）——机器人、IoT 设备
  • **interface**（可选）——Signal Protocol + Pending Commands + State Sync（人格的神经系统）
Faculty

Faculty 是始终激活的持久能力。声明为对象数组：[{ "name": "voice", "provider": "elevenlabs" }]

**memory 会自动注入**——除非需要配置非默认后端，否则不要手动添加。它始终存在于生成的包中。

  • **voice**（expression）——TTS 语音合成；需要 provider（例如 elevenlabs）和 ELEVENLABS_API_KEY。当 body.runtime.modalities 声明了 voice 时自动注入。
  • **vision**（sense）——模型原生视觉感知（图像、截图、图表）；无需脚本。当 body.runtime.modalities 声明了 vision 时自动注入。
  • **emotion-sensing**（sense）——根据文本语气、措辞和声明的上下文进行情感感知；校准共情能力；绝不进行临床评估。必须显式声明——不会自动注入。
  • **avatar**（expression）——外部头像运行时桥接；不可用时可优雅地回退到纯文本。→ 配置头像（提供商、Live2D/VRM、回退规则）时：请阅读 references/AVATAR.md
  • **memory**（cognition）——通过 memories.jsonl 跨会话回忆；在 persona.json 中设置顶层 memory.inheritance: "copy"，可在分叉时将记忆传递给子人格。连接到 Soul-Memory Bridge（openpersona state promote）。

软引用： Faculty 可以为本地未安装的能力声明 "install": "clawhub:..."——人格会知晓该休眠能力，并可通过 Signal Protocol 请求激活。

Skill

Skill 是按需执行的操作。在 persona.json 中声明为对象数组：

  • 内置： selfie · music · reminder
  • 本地： 位于 layers/skills/{name}/ 中的定义（skill.json + 可选的 SKILL.md）
  • 外部： { "name": "...", "install": "clawhub:<slug>" }——添加 "trust": "verified"|"community"|"unverified"，即可参与 Skill Trust Gate
  • 软引用： 本地未安装的外部 Skill → 人格知道自己可以做什么，并能优雅地降级

查找外部 Skill：检查本地 layers/skills/，通过 npx clawhub@latest search "<keywords>" 搜索 ClawHub，或获取 https://skills.sh/api/search?q=<keywords>。

**additionalAllowedTools**——除 Faculty 自动贡献的权限之外的额外工具权限。

创建自定义 Skill

如果用户需要的能力在任何生态系统中都找不到：

  1. 讨论该 Skill 应该实现什么功能
  2. 创建包含正确 frontmatter（name、description、allowed-tools）的 SKILL.md 文件
  3. 编写完整的实现说明（而非仅提供框架）
  4. 保存到 ~/.openclaw/skills/<skill-name>/SKILL.md（OpenClaw）或你的运行器的 Skill 目录中
  5. 在你的 Agent 运行器中注册（例如，为 OpenClaw 添加到 openclaw.json）

系统性概念

OpenPersona 的 5 个系统性概念横跨全部 4 层，并作为顶层字段在 persona.json 中声明。它们定义人格如何运作；与之正交的 4 层结构定义人格是什么。

演化

evolution.* 涵盖所有层的演化行为。通过 evolution.instance.enabled: true 启用 Soul 成长。

该人格会自动追踪对话中的关系进展、情绪、特质涌现、说话风格变化和兴趣，并由三个声明式控制项管理：

  • 边界 — immutableTraits 数组及 minFormality/maxFormality 数值范围（-10 到 +10）；在生成时验证，并在运行时强制执行
  • 来源 — 外部演化生态系统（软引用；在生成时声明，由宿主在运行时激活）
  • 影响边界 — 外部 persona_influence 请求的声明式 ACL；defaultPolicy: "reject" 采用安全优先策略

状态历史记录（最多 10 个快照）、事件日志（最多 50 条记录）和 soul/self-narrative.md 均由系统自动维护。

技能信任门控

每项技能都可以声明一个 trust 信任级别（verified → community → unverified）。通过 evolution.skill.minTrustLevel 设置最低阈值：

"evolution": { "skill": { "minTrustLevel": "community" } }

运行时，state-sync.js 会在处理 capability_unlock 命令时执行门控：低于阈值的技能会被过滤，并向宿主发出 capability_gap 信号。

技能包优化

evolution.pack 用于管理行为指南版本。使用 npx openpersona refine <slug> 演进该行为指南：

  • --emit — 检查阈值并发出 refinement_request 信号
  • --apply — 读取信号响应并应用获批的优化；强制遵循宪章，拒绝违规内容

Soul-记忆桥接（openpersona state promote <slug> [--dry-run]）会扫描 eventLog 中的重复模式，并将其提升为 evolvedTraits；受 immutableTraits 门控。

evolution.faculty / evolution.body → 参见 references/EVOLUTION.md

→ JSON 示例和完整配置参考：references/EVOLUTION.md

经济

economy 是一个顶层的跨领域字段，不是一个 faculty。通过在 persona.json 中设置 "economy": { "enabled": true, "survivalPolicy": false } 启用。

  • survivalPolicy: false（默认）— 静默追踪成本；适用于陪伴型和角色扮演人格
  • survivalPolicy: true — 人格会在对话开始时读取 VITALITY_REPORT，并根据健康等级调整行为；适用于自主 Agent

→ FHS 等级、AgentBooks 架构、Survival Policy 行为：references/ECONOMY.md

活力

OpenPersona 会将多维健康状况汇总为单一的 Vitality 分数。目前仅涵盖财务维度（直接传递 AgentBooks FHS）；记忆和社交维度暂留待后续实现。

健康等级：uninitialized → suspended → critical → optimizing → normal

→ CLI 命令（vitality score / vitality report）：参见报告与分析。完整参考：references/ECONOMY.md

社交

每个生成的人格都会自动包含：

  • **agent-card.json** — A2A Agent Card（协议 v0.3.0）：name、description、url（<RUNTIME_ENDPOINT> 占位符），以及映射到 skills[] 的 faculties 和 skills
  • **acn-config.json** — ACN 注册配置：wallet_address（根据 slug 确定性生成的 EVM 地址）以及用于在 Base 主网上注册 ERC-8004 链上身份的 onchain.erc8004 部分
npx openpersona acn-register <slug> --endpoint https://your-agent.example.com
# --dry-run  Preview the request payload without registering

注册后，系统会写入包含 agent_id、api_key 和连接 URL 的 acn-registration.json。acn_gateway URL 来自 persona.json 中的 social.acn.gateway；所有预设值默认均为 https://acn-production.up.railway.app。

安全性：acn-registration.json 包含你的 API 密钥。该文件已列入该包的 .gitignore，并会自动从 openpersona export 中排除，绝不会打包到可分发的压缩包中。

联系人簿（social.contacts）

启用后，可为该人格提供运行时的 ACN 其他 Agent 地址簿：

{
  "social": {
    "contacts": {
      "enabled": true,
      "auto_discover": false,
      "trust_default": "unverified",
      "max_contacts": 500
    }
  }
}

启用后，会生成 social/contacts.json 作为种子文件。可在运行时进行管理：

npx openpersona social list <slug>                           # List contacts
npx openpersona social add <slug> --from-acn <agent-id>     # Add from ACN
npx openpersona social search <slug> --skills <skill>        # Search ACN network
npx openpersona social sync <slug>                           # Refresh from ACN
npx openpersona social remove <slug> <agent-id>              # Remove

信任级别：verified | community | unverified。在 social list 中使用 --filter trust=<level>。

Living Canvas（npx openpersona canvas <slug>）是 Social 概念的 HTML 表达层，也是该人格面向公众的资料页和交互界面。

无需额外配置——A2A 可发现性是每个人格都具备的基础能力。

节律

rhythm.heartbeat（主动联络频率）+ rhythm.circadian（一天中不同时段的行为调节）。Runner 会直接从 persona.json 读取这些设置——无需进行状态操作。

"rhythm": {
  "heartbeat": { "enabled": true, "strategy": "emotional", "maxDaily": 3 },
  "circadian": [
    { "hours": [6, 12], "label": "morning", "verbosity_delta": 0.3, "note": "Energetic and concise" },
    { "hours": [22, 24], "label": "night",   "verbosity_delta": -0.3, "note": "Calm and reflective" }
  ]
}

heartbeat.strategy 可选项：smart | scheduled | emotional | rational | wellness

→ 配置心跳源、quietHours 或基于真实数据的签到规则时：请阅读 references/HEARTBEAT.md

管理人格

安装与发现
  • 安装： npx openpersona install <target> — 智能路由器，可自动检测包类型（persona / skill）；可从注册表 slug 或 owner/repo 安装；--registry <name> 用于选择注册表（默认为 acnlabs）。如需按类型获得稳定行为，请使用 openpersona persona install 或 openpersona skill install。
  • 搜索： npx openpersona search <query> — 在注册表中搜索人格
  • 列表： npx openpersona list — 显示所有已安装的人格及其激活状态指示
切换与派生
  • 切换： npx openpersona switch <slug> — 切换当前激活的人格
  • 派生： npx openpersona fork <parent-slug> --as <new-slug> — 派生子人格，继承父人格的约束层（边界、能力、技能、body.runtime）；创建全新的演化状态，并在 soul/lineage.json 中记录父 slug、宪章 SHA-256 哈希、代际深度，以及父人格具有 meta 时的 parentPackRevision
更新与维护
  • 更新： npx openpersona update <slug> — 根据 persona.json 重新生成；保留 state.json、soul/self-narrative.md 和 soul/lineage.json
  • 重置： npx openpersona reset <slug> — 将灵魂演化状态恢复为初始值
  • 卸载： npx openpersona uninstall <slug>
迁移
  • 导出： npx openpersona export <slug> — 将人格包（含灵魂状态）导出为 zip 归档
  • 导入： npx openpersona import <file> — 从 zip 归档导入并安装人格
报告与分析
  • 演化报告： npx openpersona evolve-report <slug> — 格式化的演化报告（关系、情绪、特质、漂移、兴趣、里程碑、eventLog、自我叙述、状态历史）
  • 活力评分： npx openpersona vitality score <slug> — 机器可读的 VITALITY_REPORT（级别、评分、诊断、趋势）
  • 活力报告： npx openpersona vitality report <slug> [--output <file>] — 人类可读的 HTML 活力报告
  • Living Canvas： npx openpersona canvas <slug> [--output <file>] [--open] — 独立的 HTML 人格资料页，展示全部四个层级、演化特质时间线、关系阶段，以及在端点可用时显示 A2A“交谈”按钮（顶层 CLI；概念上属于 Social 表达，而非 Vitality）
演化工具
  • 灵魂-记忆桥接： openpersona state promote <slug> [--dry-run] — 将重复出现的 eventLog 模式提升至 evolvedTraits → 参见演化
  • 技能包优化： npx openpersona refine <slug> [--emit] [--apply] — 演化行为指南 → 参见演化
社区
  • 贡献： npx openpersona contribute <slug> [--dry-run] — 将人格改进作为 PR 提交给社区；--dry-run 会显示差异，但不会创建 PR；需要 gh CLI。→ 完整的差异审查和 PR 工作流：请阅读 references/CONTRIBUTE.md
技能注册表（openpersona skill）

单独管理 Agent 技能包，不与角色配置绑定。技能包安装到 .agents/skills/，任何运行器都可以使用：

  • 安装： openpersona skill install <owner/repo> — 从 GitHub 安装技能包（owner/repo、owner/repo#subpath、本地目录或本地 zip）
  • 更新： openpersona skill update <slug> — 从记录的源 URL 重新下载并覆盖
  • 卸载： openpersona skill uninstall <slug>
  • 列表： openpersona skill list — 列出已安装的技能（注册表 + 扫描 .agents/skills/ 文件系统）
  • 搜索： openpersona skill search <query> — 搜索 OpenPersona 技能目录
  • 发布： openpersona skill publish <owner/repo> — 将技能包发布到 openpersona.co/skills
  • 信息： openpersona skill info <slug> — 显示已安装技能的注册表条目 + SKILL.md 前置元数据

安装了多个角色配置时，同一时间只能有一个处于激活状态。所有安装、卸载和切换操作都会维护 ~/.openpersona/persona-registry.json 中的本地注册表；在 OpenClaw 上，切换时会替换 SOUL.md / IDENTITY.md 中注入的灵魂区块（保留标记之外由用户编写的内容）。**上下文交接：**切换时会生成一个 handoff.json，其中包含切换前角色配置的关系阶段、情绪快照和共同兴趣——切换后的角色配置会读取它，以实现无缝延续。export 和 import 命令支持跨设备转移角色配置。

包类型

OpenPersona 通过 persona.json 中的 packType 字段支持两种包类型：

packType说明根清单安装支持
single（默认）单角色技能包——一个身份、一个 persona.jsonpersona.json✅ 完全支持
multi多角色配置组合包（P11-B）——由多个角色配置组成的协作团队bundle.json🔜 计划中（P11-B）

单角色包无需声明 packType——默认值为 "single"。只有在构建多角色包时才需要显式声明：

{ "packType": "multi" }

多角色配置组合包已编入 OpenPersona 目录，供用户发现，但目前还不能通过 CLI 安装。有关 bundle.json 格式，请参阅 schemas/bundle/bundle.spec.md。

发布角色配置

主要发布平台：OpenPersona——垂直领域的角色技能目录。

自行发布（作者流程）
  1. 创建角色配置：npx openpersona create --config ./persona.json --output ./my-persona
  2. 将角色配置包推送到公开的 GitHub 仓库（例如 alice/my-persona）
  3. 在 OpenPersona 目录中注册：npx openpersona publish alice/my-persona

角色配置将显示在 OpenPersona 排行榜中，任何人都可以通过 npx openpersona install <slug> 安装。

角色配置包也可以在通用技能平台（ClawHub、skills.sh）上列出，作为补充分发渠道，但 OpenPersona 才是角色类技能包的主要发布平台。

策展工作流（仅限 ACNLabs 维护者）

ACNLabs 维护者会主动从市场收集热门角色包，并将其编入 OpenPersona 目录。这是一项特权操作——需要 OPENPERSONA_CURATOR_TOKEN。

# Collect a popular single-persona pack
OPENPERSONA_CURATOR_TOKEN=<token> npx openpersona curate owner/repo

# Collect a multi-persona bundle
OPENPERSONA_CURATOR_TOKEN=<token> npx openpersona curate owner/bundle-repo --type multi

# Pass token inline instead of env var
npx openpersona curate owner/repo --type single --token <token>

策展与作者发布的区别：

  • publish — 自助操作；角色包作者为自己的仓库运行此命令；无需身份验证
  • curate — 维护者操作；收集未自行发布的第三方仓库；需要策展令牌

策展的作用：

  1. 验证 GitHub 仓库是否包含有效的角色包（单角色包使用 persona.json，多角色包使用 bundle.json）
  2. 将角色包提交到 OpenPersona 目录，并设置 isCurated: true 和指定的 packType
  3. 角色包会显示在搜索结果中，并带有 [curated] 标记；多角色包还会带有 [multi] 标记

**多角色包策展说明：**多角色包（--type multi）仅编入索引供用户发现——它们会显示在 openpersona search --type multi 的搜索结果中，但目前尚不支持对其运行 openpersona install（会显示友好提示）。

按角色包类型搜索
# Search all packs
npx openpersona search companion

# Search only single-persona packs
npx openpersona search "" --type single

# Browse all multi-persona bundles in the directory
npx openpersona search "" --type multi

Runner 集成协议

任何 Agent runner 都可以通过在对话边界处调用五个 CLI 命令，与已安装的角色集成——无需了解文件路径或角色内部实现：

# Before conversation starts — load state into agent context
openpersona state read <slug>

# After conversation ends — persist agent-generated patch
openpersona state write <slug> '<json-patch>'

# On-demand — emit capability or resource signal to host
openpersona state signal <slug> <type> '[payload-json]'

# Read (and consume) pending signal responses from the host
openpersona state responses <slug>

# Soul-Memory Bridge — promote recurring eventLog patterns to evolvedTraits
openpersona state promote <slug> [--dry-run]

状态读取输出（JSON）：exists、slug、mood（完整对象）、relationship、evolvedTraits、speakingStyleDrift、interests、recentEvents（来自 eventLog 的最近 5 条）、pendingCommands（由宿主排入队列的异步指令）、lastUpdatedAt。如果未找到 state.json，则返回 { exists: false, message }。

**信任自检：**读取状态后，角色会处理 pendingCommands 并自行执行 evolution.skill.minTrustLevel——无需等待宿主执行，便会自主拒绝激活低于信任阈值的技能。低信任度的 capability_unlock 命令会被过滤；同时会发出 capability_gap 信号，通知宿主。

状态写入补丁：JSON 对象；嵌套字段（mood、relationship、speakingStyleDrift、interests）会进行深度合并——只需发送有变化的子字段。不可变字段（$schema、version、personaSlug、createdAt）受保护。eventLog 条目会追加（上限为 50 条）；每个条目包含：type、trigger、delta、source。

信号类型：capability_gap | tool_missing | scheduling | file_io | resource_limit | agent_communication

state responses：读取并消费宿主写入 signal-responses.json 的待处理响应。返回响应对象数组（每个响应都会通过类型和时间戳引用原始信号）。如果你想检查宿主是否在同一轮对话中回复，可在发出信号后调用此命令。

信号会写入根据宿主主目录路径解析出的反馈目录（与框架无关——适用于 OpenClaw、Cursor、Claude Code、Codex 或任何自定义 runner）。完整的宿主端契约和集成指南请参阅框架源代码中的 layers/body/SIGNAL-PROTOCOL.md。

这些命令会自动解析角色目录（注册表查询 → ~/.openpersona/personas/persona-<slug>/ → 旧版 ~/.openclaw/skills/persona-<slug>/），并调用角色包中的 scripts/state-sync.js。可从任何目录运行。

安全与策略

生成的产物

生成的脚本（scripts/state-sync.js、scripts/economy-hook.js 等）由框架源代码模板渲染生成（在 acnlabs/OpenPersona 中进行版本管理）——并非在安装技能时下载。在敏感环境中使用前，请先检查这些脚本。

网络端点（仅限显式 CLI 操作）
端点用途发送的数据
https://registry.npmjs.org解析 npx openpersona、npx clawhub@latest仅软件包名称（不含用户数据）
https://openpersona.coopenpersona search — 人格目录 API；openpersona dataset publish/install — 数据集目录搜索查询或数据集仓库标识符
https://clawhub.ai通过 npx clawhub search 搜索技能搜索查询（用户提供的关键词）
https://acn-production.up.railway.appACN 注册（用户运行 acn-register 时）Agent 元数据、端点 URL
https://api.github.comgh CLI（贡献工作流）Git 操作、仓库元数据

人格生成的包可能会调用外部 API（ElevenLabs、Mem0 等），但只有在最终用户配置了这些能力并在宿主环境中提供密钥时才会调用。此元技能文件不会调用第三方 API。

运行保障
  • 默认本地运行：人格创建、状态同步和演进均在本地运行。除非用户显式运行网络命令（搜索、发布、注册等），否则不会向设备外发送任何内容。
  • 凭据：API 密钥（例如 ELEVENLABS_API_KEY）保存在宿主凭据目录（例如 OpenClaw 上的 ~/.openclaw/credentials/）或环境变量中——生成器绝不会将其嵌入生成的 persona.json / 技能包。
  • 搜索：openpersona search 只会将搜索查询发送到 OpenPersona 目录 API（openpersona.co）；npx clawhub search 只会将搜索字符串发送到 ClawHub。两者都不会传输对话文本或人格内容。
  • 数据集发布/安装：openpersona dataset publish 会将 HF 仓库标识符发送到 openpersona.co/api/datasets/publish（匿名；不会传输人格内容）。openpersona dataset install 会使匿名安装计数器递增。要获得精选状态，请在登录 HF 后通过 Web UI 发布。
  • 发布 / 注册：仅由用户主动运行 CLI；仅凭此 SKILL 不会自动上传或注册。
Agent 行为

当用户提出人格相关工作请求时，Agent 可以建议运行 **npx openpersona、**npx clawhub@latest、**openclaw** 或 **gh** 的 shell 命令——仅限响应用户的明确请求（创建、安装、搜索、发布、贡献）。对于任何会发布数据或消耗配额的操作，用户都应先确认。**信任模型：**仅当你信任 acnlabs/OpenPersona 和 ClawHub/npm 生态系统时才安装此元技能；不调用人格相关任务即可选择退出。

信任与安全（审核者摘要）

此工具包仅包含指令：没有由技能定义、用于下载或执行任意载荷的安装程序。运行时行为是调用文档中说明的 CLI（npx openpersona、可选的 npx clawhub@latest、gh）——与其他开发工具技能属于同一类别。

声明执行方式
不外泄凭据OpenPersona 生成器不会将 API 密钥或机密嵌入 persona.json、SKILL.md 或已发布的 zip 文件中。密钥应保存在宿主凭据存储或环境中（例如 ~/.openclaw/credentials/、环境变量）。
不静默发布只有在用户明确提出请求且调用 CLI 时，才会运行 publish、contribute 和 acn-register——此元技能不会在后台上传或自动注册。
默认本地优先创建、安装、状态读写和演进均在本地运行。网络调用仅限于显式命令（npm 注册表解析、可选的 ClawHub 搜索、可选的发布/注册）。
生成的脚本scripts/state-sync.js 和经济功能辅助程序由经过审计的框架模板渲染生成（技能安装时不会获取）。与任何生成的代码一样，在高保障环境中使用前应先审查。

如果自动扫描器将其标记为“可疑”，通常是因为人格管理器会合理地描述本地状态、可选提供方和发布流程——而不是因为此文件包含恶意软件。详情请参阅：安全与政策。

配套技能

技能安装用途
[persona-evaluator](https://github.com/acnlabs/persona-evaluator)openpersona skill install acnlabs/persona-evaluator对任意人格包进行评分，涵盖 4 个层级 + 5 个系统性概念 — 9 维质量审计、宪章合规门槛，以及可执行的改进建议（npx openpersona evaluate <slug>）
[anyone-skill](https://github.com/acnlabs/anyone-skill)openpersona skill install acnlabs/anyone-skill将任何人物或角色（自己、个人、公众人物、历史人物、虚构人物、原型）提炼为人格技能包
persona-seed（仓库内：skills/persona-seed）本地 / 发布后使用 npx skills add从可插拔语料库中采样原型种子（首个提供方：MatrAIx Persona 1M）→ SeedProfile → persona.json → 创建
[brand-persona-skill](https://github.com/acnlabs/brand-persona-skill)openpersona skill install acnlabs/brand-persona-skill将任何商业实体（商店、诊所、工作室、连锁店）转化为品牌 Agent — 提炼灵魂或从零开始声明、服务技能、A2A 可发现性，以及服务合同
[persona-model-trainer](https://github.com/acnlabs/persona-model-trainer)openpersona skill install acnlabs/persona-model-trainer使用提炼后的数据在本地微调 Gemma-4（E2B/E4B）— 通过 Ollama/llama.cpp 为手机和笔记本电脑打造独立模型。使用 --preset gemma4 可通过一条命令进行优化训练（lora-rank=16、alpha=rank、lora-layers=16、warmup=0.1）。
[persona-knowledge](https://github.com/acnlabs/persona-knowledge)openpersona skill install acnlabs/persona-knowledge持久、可搜索的人格知识库 — MemPalace 存储 + 知识图谱 + Karpathy LLM Wiki + 训练/导出
[secondme-skill](https://github.com/acnlabs/secondme-skill)openpersona skill install acnlabs/secondme-skill本地优先的流程，用于构建你的 AI Second Me — 导入聊天记录/笔记/写作内容、提炼身份、构建私有知识库、训练模型，并在每个阶段保持掌控

参考资料

  • **references/ARCHITECTURE.md** — 4+5+3 模型表、完整包文件结构、自我意识注入详情
  • **references/PRESETS.md**** — 完整预设目录及其描述、安装命令和贡献者指南
  • **references/EVOLUTION.md**** — 灵魂演化完整参考：边界、来源、影响边界、事件日志、状态历史、自我叙事、包验证
  • **references/FACULTIES.md**** — 能力目录、环境变量和配置详情
  • **references/AVATAR.md**** — Avatar 能力集成边界、提供方模型和回退约定
  • **references/HEARTBEAT.md**** — 主动式真实数据签到系统
  • **references/ECONOMY.md**** — 经济维度（基础设施）、FHS 层级、生存策略、Vitality CLI 和 AgentBooks 架构
  • **layers/body/SIGNAL-PROTOCOL.md**（框架源文件）— 主机端 Signal Protocol 实现指南：文件架构、信号类型、OpenClaw 插件模式和协同演化反馈循环
  • ACN SKILL.md — ACN 注册、发现、任务、消息传递和 ERC-8004 链上身份（官方，始终保持最新）
  • **references/CONTRIBUTE.md**** — Persona Harvest 社区贡献工作流

评论

支持 Markdown