角色扮演与设定配置
Kesoku 拥有灵活且动态的角色扮演 (Role-Playing) 系统，允许用户或 Agent 自身在会话中即时切换不同的人物设定（Persona）。
🎭 运行机制
每个角色设定均由存放于 roles/ 目录下对应文件夹中的 intro.md 描述文件定义：
kesoku/
└── roles/
├── default/
│ └── intro.md # 默认的智能体系统提示词
├── coder/
│ └── intro.md # Coder 人设提示词
└── helper/
└── intro.md # Helper 人设提示词
当某个会话绑定了特定角色时：
- Kesoku 读取对应
roles/<角色名>/intro.md文件的内容。 - 将其注入到系统提示词编译链的 Active Persona 部分。
- 模型在当前通道的后续对话中将立即采用此人设。
🛠️ 配置自定义角色人设
步骤 1：创建角色目录
在已配置的 roles_dir（默认为工作目录下的 roles/）中，创建一个以角色名字命名的新文件夹（例如 helper）：
mkdir -p roles/helper
步骤 2：写入人设提示词 (intro.md)
在此文件夹中创建 intro.md 文件：
touch roles/helper/intro.md
写入人设规则，例如：
你是一个得力的编程助手。你说话简明扼要，且总是编写整洁、注释详尽的 Python 代码。
步骤 3：初始化与覆盖角色
如果您是第一次初始化工作区，请确保角色目录已生成：
kesoku init -c config.toml
kesoku init -c config.toml --overwrite-roles
🔄 动态角色切换
在 Kesoku 中，角色人设的切换是完全动态的，由聊天指令进行管理。
使用聊天指令
在支持的应用平台（如 Discord 或微信）上，您可以通过以下指令即时管理角色：
* /role：查看当前活跃的角色名称，并列出当前工作区中所有可用的角色列表。
* /role {名称}：为当前频道或线程绑定并切换到指定的角色（例如 /role coder）。
[!TIP] Discord 线程继承：在 Discord 中，新建的子线程默认会自动继承父级文本频道的角色绑定关系。当然，您随时可以在子线程中运行
/role {名称}来为其单独绑定其他不同的人物设定。[!NOTE] 系统目前不支持直接通过日常对话文本（如“扮演 helper”）来请求智能体自动切换角色。请始终使用
/role指令来干净地切换人设。
🎨 教程：如何创建生动的角色人设（集成声音克隆与图像生成）
在 Kesoku 中，您不需要手动去创建复杂的角色文件夹、编写底层的语音/图像生成脚本。Kesoku 已经内置了 role-creator 技能，您可以直接让智能体为您交互式地设计、创建并自动初始化一个全新的角色人设！
🚀 使用技能交互式创建角色
您只需在聊天中直接对智能体说：
“帮我设计一个名为 Alice 的新角色” 或 “启动角色创建工具”
智能体便会启用 role-creator 技能，化身为您的角色设定顾问，交互式地引导您一步步完成创建：
1. 核心人设设计：收集角色名称、性格特征、语言口吻及口头禅。
2. 头像样本（可选）：引导您提供或上传一张参考头像，用于保持图像生成的一致性。
3. 声音样本（可选）：引导您提供一段 5-15 秒的 WAV 语音音频作为基准，并录入转录文本，以便克隆出极其相似的专属 TTS 声音输出。
收集完毕后，智能体将自动在工作区下生成专属的角色文件夹、配置文件以及底层克隆脚本。
📂 生成的角色文件夹结构
当 role-creator 执行完毕后，它会自动在 roles/ 目录下生成如下结构（以 roles/alice/ 为例）：
roles/alice/
├── intro.md # 角色生平设定、性格规则与生成调用指南（自动生成）
├── images/
│ └── character.jpg # Alice 的头像（若提供，用于图像一致性参考）
├── audio/
│ └── character.wav # Alice 的参考声音频片段（若提供，用于声音克隆基准）
└── scripts/
├── alice-tts.sh # 自动生成的文本转语音声音克隆执行脚本
└── alice-image.sh # 自动生成的 Alice 图像一致性渲染脚本
🔄 专属的备忘记忆隔离
当新角色 Alice 创建成功并处于活跃状态后，智能体通过 update_memory 写入类别为 "memo"（自定义备忘）的记忆时，会自动打上 role='alice' 的专属标签，从而与其它角色的记忆完全隔离，防止不同人设之间的互动记忆发生混乱。