# 角色代码说明

固定入口：**角色中心 → 上传角色代码**。可以点上传文件，也可以使用模板后直接编写，最后点生成角色。电脑支持Ctrl/Cmd+Enter。整个过程无需修改网页或聊天程序。

修改已有自定义角色：在代码窗口的“操作角色”中选中角色，编辑或上传新配置后点“保存修改”。角色沿用原id，聊天和记忆保留。只更新姓名与性格时，未填写的头像等字段也会保留。新增模式不覆盖已有id；批量配置中有重复id或无效配置时整批不添加。

手机代码框自动换行；“清空代码”可直接清掉模板，方便粘贴自己的配置。上传文件会先载入代码框，检查后再生成或保存。也可以在“我的角色”点“编辑”，用表单更换角色头像、姓名和人设。

## 最小配置

```json
{
  "id": "my_xiaoyu",
  "name": "小雨",
  "age": 26,
  "gender": "female",
  "personality": "安静、温柔，喜欢读书和雨天。先听对方说完，熟悉后更愿意主动关心。"
}
```

name和personality必填。未写id会自动生成，未写标签、开场和年龄会使用默认值。推荐保存独立id，方便避免重复添加。

也可写中文字段，例如`{姓名:'小雨',性格:'成熟坦率',年龄:'26岁',性别:'女'}`。支持头像、标签、开场白、说话风格、兴趣、相处方式和背景等中文键。常见角色卡的data包装、description人设和first_mes开场白可识别；批量也可使用characters数组。

完整模板：[new-role.role.json](new-role.role.json)。预设配置参考：[preset-roles.json](preset-roles.json)。网页“使用模板”每次生成不同id。

## 字段与容量

| 字段 | 内容 | 限制或默认行为 |
| --- | --- | --- |
| id | 独立标识，如my_xiaoyu | 字母、数字、下划线或连字符，1到70字符。保存时补custom_前缀。非法或缺失时自动生成 |
| name | 姓名，必填 | 保存最多12字符 |
| personality | 性格和详细人设，必填 | 最多12000字符，超限拒绝生成 |
| gender | female、male、unspecified | 其他值使用unspecified |
| age | 成年年龄 | 18到100，缺省24 |
| tag | 列表中显示的标签 | 最多20字符，缺省“新朋友” |
| greeting | 初次开场 | 最多300字符，缺省自然问候 |
| avatar | 预设路径、图片数据或HTTPS图片地址 | 推荐assets/avatars/内路径，照片也可在表单从相册选择 |
| voice | 说话习惯 | 最多240字符 |
| interests | 兴趣 | 最多240字符 |
| background | 虚构背景 | 最多600字符 |
| relationship | 相处方式 | 最多300字符 |
| conversation | 不同情境的接话原则对象 | 最多8项，键小于20字符，值最多300字符 |
| quickReplies | 快捷话题字符串数组 | 最多12项，每项最多100字符 |

除personality超限会明确拒绝外，其他文字字段超限时保留表中长度。重要人设尽量写在personality。头像字段不接受任意文件路径或执行脚本，非法地址会回到预设头像。头像数据上限180000字符。

## 写出有区别的人设

人设可以按“日常生活、表达方式、情绪反应、相处变化”组织。具体行为比一串形容词更容易形成稳定风格。

```json
{
  "id": "my_zhouyu",
  "name": "周予",
  "gender": "male",
  "age": 28,
  "tag": "安静坦诚",
  "avatar": "assets/avatars/shenyan-portrait.jpg",
  "greeting": "你来了。今天想说的，我慢慢听。",
  "personality": "28岁成年男性，安静但并不冷漠。周末喜欢骑车和找小书店。有自己的生活与兴趣，不把每句话都变成建议。对方累了先顺着情绪聊，开心时愿意一起分享。慢热，熟悉之后会主动关心，愿意根据明确反馈调整表达。",
  "voice": "自然口语，不反复追问，不用客服式套话。",
  "interests": "骑车、读书、街边小店",
  "background": "在城市工作，喜欢用周末慢慢认识附近街区。",
  "relationship": "熟悉以后更愿意表达惦念，也尊重对方的节奏。",
  "conversation": {
    "难过": "先承接具体感受，不急着讲道理。",
    "开心": "分享对方正在开心的事情，给出贴切反应。",
    "久别": "结合已知记忆自然接续，不编造离线经历。"
  },
  "quickReplies": ["今天有点累", "给我讲个小故事", "我有件开心的事"]
}
```

conversation是帮助模型理解性格的原则，不是固定答案库。角色仍根据当次话题生成真实回复。

## 批量添加

可用数组，也可用包含roles数组的对象，一次1到24个角色。

```json
{
  "roles": [
    {"id": "friend_a", "name": "阿夏", "age": 25, "gender": "female", "personality": "热情开朗，喜欢音乐。"},
    {"id": "friend_b", "name": "知远", "age": 29, "gender": "male", "personality": "沉稳细腻，喜欢读书。"}
  ]
}
```

新增模式遇到已有id或批量内部重复id，会提示选择角色后保存修改，整批不添加。任何一项缺少姓名、性格或年龄不合法时，整批不添加。保存空间不足会撤回本次新角色，并保留编辑框内容。

## 支持的JS包装

```javascript
export default {
  id: 'my_friend',
  name: '小满',
  age: 24,
  // 人设可以直接写多行
  personality: `成熟开朗，愿意认真听朋友说话。
说话直接自然，喜欢读书和散步。`,
};
```

可直接写对象，也支持`export default {...}`、`module.exports = {...}`、`const role = {...}; export default role;`或`const role = {...}; module.exports = role;`。字段名可以不加引号；字符串可用单引号、双引号或反引号；支持注释、末尾逗号和多行人设。粘贴时带着Markdown代码框标记也可识别。手机中文引号、冒号和逗号仅在结构位置兼容，文字内容保持原文。

只读取角色数据，不执行函数、计算表达式或字符串插值。不完整的字符串、缺少逗号或括号会提示具体行列，光标会定位到出错处；草稿不会清空。姓名和性格缺失时会直接说明缺哪个字段，年龄仍为18到100岁。

## 草稿和文件

代码框最多524288字符，上传文件最多5MiB。成功生成后草稿清空，未提交的草稿保存在同一标签页的sessionStorage中。关闭标签页后请以另存的文件为准。批量导入很大的内嵌头像可能占用较多浏览器空间，建议先保存记忆备份。

维护预设角色请改仓库根目录roles.js。这里的单独导入文件用于玩家自建角色，preset-roles.json作为参考，不自动覆盖线上预设。