跳到主要内容

角色

角色是 Anyy 的 profile 本地身份。一个角色包含显示名、状态、onboarding 状态和 SOUL.md persona 文件。角色让同一个 profile 能在不同助理声音或用途之间切换，而不需要创建另一个 profile。

角色不是用户、权限组或 provider 账号。它们共享该 profile 的记忆、技能、渠道、providers 和 gateway 状态。

什么是角色​

默认角色永远是 default，映射到：

<home>/SOUL.md

命名角色映射到：

<home>/roles/<role_id>/SOUL.md

SOUL.md 可以定义角色人格、语气、边界、不确定性风格，以及 Anyy 应该如何与你协作。它不能覆盖 provider identity、工具策略、审批、ChangePlan、审计或显式用户指令。

角色范围​

角色身份是会话范围的一部分：

Scope item行为
已有会话保留创建时的角色。
新本地会话使用 profile 的 default_role 指针；未设置时使用 default。
默认角色使用 <home>/SOUL.md；不会 materialize roles/default/SOUL.md。
命名角色使用 roles/<role_id>/SOUL.md。
命名 SOUL.md 缺失Prompt assembly 时回退到默认角色身份。

记忆是 profile-level 的。USER.md 和 MEMORY.md 在角色之间共享。

创建角色​

anyy role create research --display-name "Research"

Role ID 必须是路径安全的小写 identifier。ID 会用于角色目录路径，因此应视为长期不变。

列出角色：

anyy role list
anyy role list --include-archived
anyy role list --json

更新角色​

更新显示名：

anyy role update research --display-name "Research"

从 markdown 文件更新角色 persona：

anyy role update research --soul-file ./research.SOUL.md

默认角色可以更新 <home>/SOUL.md，但它的显示名和基础角色 metadata 受保护。需要独立身份时请使用命名角色。

使用角色​

为新会话设置 profile default role：

anyy role use research

这会写入 profile default_role 指针。它不会重写已有会话角色。

查看单个角色：

anyy role get research
anyy role get research --json

不再需要时删除一个角色：

anyy role delete research

Delete 会软删除角色，并从 Dashboard roles 列表移除。当角色被选为默认，或仍有 channel bindings、cron jobs、background jobs、session queue items、tasks、subagent runs 等 active references 时，Anyy 会阻止删除。

Role Onboarding​

命名角色可以从 pending 或 active onboarding state 开始。Onboarding 期间，Anyy 会讨论角色名称、用途、语气、边界、歧义处理、分歧方式和用户期望。

role_onboarding_complete 工具可以提出最终 SOUL.md 内容，但写入长期角色身份前需要用户审批。审批摘要包含 SOUL.md preview。

完成的角色会记录 onboarding completion time，并在未来 prompt assembly 中使用写入的 SOUL.md。

Dashboard 中的角色​

Dashboard 的 Roles 页面可以：

动作行为
List roles显示所选角色、active roles，以及 setup state。
Create role创建角色身份并打开 SOUL.md editor。
Use role为新会话选择 profile default role。
Edit SOUL.md通过 role RPC 保存角色 persona。
Rename更新命名角色 display name。
Delete软删除没有 active references 的角色。

Dashboard role writes 使用已认证 dashboard sessions 和 same-origin POST checks。角色文件写入保留在 active profile home 下。