角色与提示词资产库

角色库保存“画谁”，提示词资产库保存“怎么画”。例如，先保存原创角色「小葵」的外观，再保存「柔和水彩」画风，后续就可以请求 Bot 用这套设定画不同场景，无需每次重写。

从哪里进入

在管理面板选择目标 Bot，打开「生成素材库」。页面上方是「素材库设置」，下方分为「角色」和「提示词资产」两个标签页。角色与资产按 Bot 隔离，切换 Bot 不会自动共享记录。

教程适用于已包含该功能的 v0.3.0 或更新版本。如果看不到入口，先确认实例已经升级和部署；GitHub 发布版本不会自动更新正在运行的面板。

生图前还需配置图片 Provider、路由和聊天权限，见图片、贴纸与媒体。只保存和整理资料不要求先发起图片任务。

先确认权限和开关

后台 owner/admin 可以管理素材库；editor 可查看，但不能修改共享配置或资产。Telegram 中，普通用户可在权限和隐私设置允许时保存自己的原创角色、维护自己的角色绑定；Bot 管理员可维护共享提示词资产。

修改开关后，点击「素材库设置」中的「保存」。第一次使用建议保留默认设置，先手动选择一个角色和一项 Safe 资产验证，再开启自动注入。

关闭自动注入只停止自动加入置顶资产。 启用角色或提示词资产时，本次明确选择的素材仍可使用。要完全不使用素材库，需要明确要求本次跳过素材库。

第一步：保存一个角色

保存原创角色

1. 在「角色」标签页点击「添加原创角色」。
2. 填写「名称」和「外观」，这两项必填；按需填写别名、默认服装、所属作品和备注。多个别名用英文逗号分隔。
3. 如需把角色归属于某位群友，在「绑定群友档案」选择已有档案；留空表示管理员维护的角色。这是在指定角色归属，不会自动将它设为该群友的默认代表形象。
4. 点击「保存」，返回列表搜索名称，确认记录存在。

可用以下内容练习：

也可以在 Telegram 中明确要求保存：

请记住我的原创角色“小葵”：黑色短发、绿色眼睛，左侧有向日葵发夹。
默认穿白色衬衫和深蓝色背带裙。请保存到角色库。

这些是自然语言请求示例，不是固定命令；Bot 需要启用 AI 和对应工具。普通聊天中提到角色不会自动创建原创角色。同名角色不会自动合并，更新时请先让 Bot 查找并确认要修改的记录。

当前角色库保存文字设定，不保存参考图。外观尽量写稳定特征；临时动作、背景和本次服装放在生图请求中。

从缓存头像整理外貌

启用人物档案记忆并使用支持视觉输入的回复模型后，可以明确请求 AI 分析当前 Bot 已缓存的头像：

反推一下柠柠的头像，整理成纯英文自然语言外貌提示词。

AI 先确认对应人物及 Telegram ID，再用 get_profile_avatar 读取缓存图片。同名人物需要先确认；这个工具不会仅凭 hasAvatar 猜测外貌，也不会临时向 Telegram 下载头像。一次请求最多读取三个头像。

档案与缓存按 Bot 隔离，范围是当前 Bot 已认识的人物，不限于当前聊天；不会读取另一个 Bot 的档案。请求者关闭个人化时不可使用。目标用户为 normal 时可读取，目标为 isolated 时仅本人可读取，目标为 off 时拒绝读取。详见隐私、历史与记忆。

图片只用于本次模型请求，工具日志和持久历史保存读取状态，不保存图片二进制或下载地址。模型收到的是缓存版本，可能不是用户刚换的新头像；未缓存或缓存不可用时，可以让用户发送图片，或等 Bot 正常观察与刷新头像后再试。

正常观察到用户时，头像默认每 24 小时检查一次；当前刷新失败后，5 分钟后的下一次观察可重试。档案重建后可立即刷新，旧请求迟到失败不会缩短新档案的刷新间隔。

后台刷新头像时，下载正文上限为 5 MB；即使响应未声明大小，超过上限也会停止读取并保留已有头像。

分析头像与保存角色是两步。 如需保存，另行明确要求；读取他人的头像不授予其角色或绑定的修改权。普通用户仍只能按既有规则维护自己的角色，别人的角色应由本人或有维护权限的人操作。

沉淀 Danbooru 角色

在 Telegram 请求 Bot 查询角色标签，例如：

帮我查找初音未来的 Danbooru 角色标签，并列出候选供我确认。

启用角色功能时，角色查询工具返回的结果会按规范 tag 保存。之后打开「角色」，将来源筛选为「Danbooru」，搜索名称或 tag 查看结果。仅在普通消息里输入角色名，不代表已经调用查询或完成入库。

来源 tag、别名和上游元数据只读；管理者可补充本地外观、默认服装、所属作品或备注。上游摘要可能不完整，不要把它当成人工确认的设定。

来源缓存有效期为 12 小时，过期回退会标明。列表的查询次数统计工具返回该角色的次数，缓存命中也计入；它不是画图次数。

第二步：设置自己的代表形象

如果希望以后说“画一下我”时使用小葵，需要额外建立人物与角色的绑定。

在 Telegram 中可以请求：

请查找刚保存的“小葵”，将她绑定为我的代表形象，并设为默认。

管理员也可以在面板操作：

1. 打开当前 Bot 的「人物档案」，找到目标群友。
2. 点击「管理角色绑定」，搜索已保存的角色。
3. 将「绑定关系」选为「代表形象」，勾选「设为默认代表形象」，点击该角色旁的「添加」。
4. 确认已绑定列表出现「默认」标记。

一个人可以绑定多个角色，但最多有一个默认代表形象。「喜爱角色」只表示喜欢，不会自动拿来代表本人。没有默认代表形象时，请先指定角色或建立默认绑定，Bot 不会随意挑选。

普通用户只能维护自己的绑定。角色归属、人物绑定和角色编辑权限是三件事：绑定别人维护的角色不会让你获得其编辑权。个人隐私设置也会影响资料的保存和读取，见隐私、历史与记忆。

第三步：保存一项画风资产

1. 切到「提示词资产」，点击「添加提示词资产」。
2. 输入名称，例如「柔和水彩」，类型选择「画风」。其他类型包括画师串、服装、特征和构图。
3. 在「提示词内容」填写 soft watercolor, delicate brush strokes, warm daylight，按需补充备注。
4. 「安全分类」选择 Safe，先不勾选「置顶」，点击「保存」。

名称方便检索，真正用于生成的是「提示词内容」。备注用于说明用途，不要把希望出现在图中的要求只写进备注。

Bot 管理员也可以通过 Telegram 明确要求保存：

请保存提示词资产“柔和水彩”，类型为画风，分类为 safe，
内容是 soft watercolor, delicate brush strokes, warm daylight。暂时不要置顶。

普通群友不能修改共享提示词资产或全 Bot 的默认画风。保存前必须明确选择 Safe 或 NSFW，不能留空。

第四步：在生图中使用

先明确指定素材，确认效果后再设置默认项：

用角色库中的“小葵”和提示词资产“柔和水彩”，画她坐在窗边读书。

已经绑定默认代表形象时：

用我的默认代表形象画一下我，使用“柔和水彩”，背景是清晨的花园。

本次想换衣服时：

画角色库里的“小葵”，这次穿黄色雨衣，不使用角色保存的默认服装。
保留原本的发夹和外貌，背景是雨后的街道。

本次衣服或场景不会改写角色档案。需要永久更新时另行明确要求保存。明确选择的角色优先于人物默认代表形象；检索到某项资产不代表本次已经采用。

图片任务仍受原有 Provider、preset、配额和权限约束。“已接受”不代表生成或 Telegram 投递成功；到生成记录中确认任务状态，再回聊天查看图片。查找任务、读取失败和删除核对见生成记录与问题恢复。

让置顶资产自动使用

1. 编辑已验证的资产，勾选「置顶」并保存。
2. 在「素材库设置」开启「自动注入」，同时保持「启用提示词资产」开启，点击「保存」。
3. 在一个测试聊天中发起生成，确认默认风格符合预期后再继续使用。

置顶是共享默认项，会影响当前 Bot 中符合条件的生成请求，不只影响设置它的管理员。系统按分类和本次选择筛选，显式选择与置顶命中同一资产时只加入一次。

按需使用以下请求：

• 本次不用默认画风：“这次不要使用任何置顶资产，只用我明确指定的素材。”
• 排除某个默认项：“这次不要自动加入置顶的‘柔和水彩’。”避免同时又明确选择该资产。
• 完全跳过素材库：“这次跳过整个素材库，只按我这段提示词生成。”这也会跳过库中的角色与显式资产。
• 停止后续自动加入：关闭「自动注入」并保存。已有角色、资产和历史任务仍保留。

NSFW 资产需要管理员开启「允许 NSFW 资产」，并且本次请求明确使用 NSFW 模式；仅置顶不会绕过这一条件。Safe 请求不会自动加入 NSFW 资产，显式选择不符合条件的资产会被拒绝。分类不替代图片供应商的内容策略。

查看次数、编辑与删除

角色查询次数用于观察常查的角色。资产的成功使用次数则按任务计算：产物成功保存后，每任务每资产加一；一个任务多张图仍只加一。检索、提交、失败和取消不计入，Telegram 投递重试不会重复计数。

生成任务保存当时使用的素材内容快照，后来编辑或删除资产不会改写旧任务的提示词。删除角色会解除所有相关人物绑定；只移除绑定不会删除角色。删除确认中可查看受影响的绑定数量。

导出角色绑定时，需同时包含对应的人物档案和角色。导入时 ID 会重新分配，关联随之转换；缺少依赖会报错并回滚。同实例中已有的生成任务标识仍可能导致重复导入失败，素材引用转换不等于完整备份恢复验收。

Telegram 保存资产失败时

管理员明确要求新建资产时，save_prompt_asset 的 id 可以省略或传 null；更新必须先检索并确认已有 id。省略备注和置顶参数时，分别使用空备注和不置顶。成功结果会区分新建、更新，并返回资产 id。

参数不合法时，写入前会拒绝并指出校验原因；资产不存在或没有权限时会返回明确错误。若提示存储异常、写入结果未知，先检索名称并核对内容与 id，再决定是否重试，以免重复创建。管理员可在运行日志中查看脱敏的存储原因；工具显示失败并不总能证明数据库没有完成写入。

常见问题

管理员升级前还应阅读备份与升级及 v0.3.0 升级说明。真实图片效果需要在自己的模型和 Provider 上验证。