镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/service-roles.md ↗

服务角色

Bot 里的角色分两个维度:

全局的服务角色(内置角色和全局模板)在「全局设置 → 服务角色」(#/settings/service-roles)维护,只有超级管理员可以查看和修改。项目管理员还可以为自己管理的项目建项目群助手角色(#849),在「个人设置 → 飞书绑定」的「项目群助手角色」中新建、修改和删除,不需要超级管理员;它属于一个项目(project_id,建好后不能改),只能绑定到范围只有这个项目的群。

定义

每个服务角色有名称、职责说明、提示词、模型和配置版本(revision)。群聊助手角色只是提示词和模型的模板:一个群能做什么由它的群绑定的权限档位决定(#849),见 消息渠道。

内置角色可以修改,但不能停用或删除;自定义角色可以停用和删除,但仍有启用中的群聊绑定时不能删除(409 service_role_in_use),需要维护人先为这些群更换角色或停用绑定。每次保存都要带上读取时的 expected_revision,版本已变时返回 409 service_role_revision_conflict,不会覆盖别人的修改。新建、修改、删除和模型的自动采用/清除都写入审计记录(service_role.*)。重启不会覆盖管理员对内置角色的修改。

允许使用虚拟电脑的管理助手和群(群绑定的档位打开「使用虚拟电脑」时)使用自己对话归属的助手电脑(见下文「助手电脑」),不再借用项目电脑,也不需要先选仓库;使用前提是群的授权者或私信本人至少在一个范围内仓库有 tasks.write。私有记忆按角色、会话、用户或群绑定和授权围栏密封保存;复用同一角色模板不会共享不同群或用户的历史、任务或记忆。管理助手和群聊助手均可使用已接入的仓库读取、管理查询/命令、私有记忆和电脑工具,在各自的权限(管理助手是当前用户的权限,群是绑定的档位)之内,仍受各入口支持范围约束。

助手电脑

群聊助手和管理助手的 read_file、write_file、delete_file、run_command(以及附件的 import_message_resource、attach_workspace_file)使用按对话归属分配的助手电脑(#457):群按群(飞书连接 + 群),私信按人(会话所属组织 + 本人),同一个人的飞书私信和控制台管理助手对话(同一范围)共用一台电脑和一个 HOME。归属、授权围栏和 HOME 代次都由控制面根据已认证的会话决定,模型只给路径,不能指定电脑、卷或宿主路径。部署没有挂载 HOME 卷(assistant-homes,控制面的 BOT_ASSISTANT_HOMES)或没有 manager 时,不提供这些工具。

阶段消息与一轮回答的结束

服务角色的每轮回答(管理助手的一条消息、群聊助手的一次回答,以及会话定时任务的一次运行)默认带有 send_message 工具(#435),用来在工作期间向当前会话发送阶段消息。它不是权限项,也没有审批。系统提示词和工具说明告诉模型何时发送(#453):预计要较长时间的工作(多步工具调用、跨仓库或多文件检索、日志排查、在电脑上执行命令)开始前,先发一条说明接下来要做什么;之后只在有关键发现、新证据或阶段结论时再发;不发「仍在执行」「请稍候」这类没有内容的消息,也不在最终回答里重复已发过的进展;可能安静结束的回合(群里没有 @ 助手的消息、没有可汇报内容的定时任务)在确定要回答之前不发。

一轮回答没有步数上限,只在以下情况结束:模型回复时不再调用工具;可以安静的回合里模型调用 stay_silent(见下文);回答被停止(管理助手由用户停止;群聊助手在当前轮源消息撤回或修改、绑定或授权围栏变化时停止,也可以在控制台停止)。其他历史消息编辑或撤回后,会话与电脑保留,助手收到当前正文和变更通知,下一步从当前来源重建派生上下文。成员进出与历史补读不改变授权围栏,旧自有任务和私有记忆继续可用;真实解绑、角色能力收回、授权丢失或机器人被移出群仍作废会话。上下文大小由工具结果的折叠控制,见 Agent 运行时。模型请求暂时失败(90 秒没有输出、连接断开、429、5xx 等)不会结束这一轮:按 Agent 运行时 的规则在同一步重试,最多 5 次;群聊回合每次重试记一个 model_retry 步骤,管理助手发出 model_retry 事件,控制台丢掉失败那次已流出的文字并显示正在重试。重试用完仍失败时,群聊回合把原因写进回合记录(error_detail),飞书会话页显示“原因:…”;管理助手的 error 事件带 detail,控制台显示原因和错误码。独立任务、群定时任务和私聊定时任务使用同一套重试。

保持安静

可以安静结束的回合会多一个 stay_silent 工具(#489):群聊助手回答没有 @ 它的群消息(问题或全部参与模式),群定时任务,以及私聊管理助手执行定时任务。被 @ 的群消息、私聊里本人发来的消息和独立任务不提供这个工具。

独立任务

管理助手和群聊助手都可以创建和继续自己的独立任务:为了保持当前对话整洁,把一件事放到单独的上下文里想清楚,只把结论带回当前回答。独立任务不受权限项控制,也没有配置项;它使用与当前对话相同的服务角色、模型和工具,权限也相同(管理助手是固定全权限与当前用户有效授权的交集,群聊助手是群绑定的档位(权限项)、绑定范围和授权者当前权限的交集),不能扩大权限,也不能再开新的独立任务。

用量与计费

服务角色的模型请求记在 model_requests.service_role_id 上,repository_id 为空,不计入任何项目。两处例外同时记在一个仓库上(repository_id),计入它的项目用量:范围只有一个仓库的群(见下文),以及管理助手为一个仓库运行的接入向导。项目的统计、成本和管理查询 get_usage 仍只按项目汇总;服务角色页按角色显示累计请求数、token、费用和未计价请求数。删除自定义角色后,已有记录仍保留原角色 id。

model_requests.repository_id 原来是 NOT NULL。升级时控制面重建一次这张表:沿用表原有的建表语句(含之后新增的全部列),只去掉这一处 NOT NULL,复制全部数据,并按原 SQL 重建全部索引和触发器;完成后在设置项 model_requests_nullable_repository 记录时间,之后启动不再重建。

管理助手

控制台管理助手和飞书个人私聊都使用 management-assistant:模型和用量都属于这个服务角色,不再取账户可读的第一个项目。账户第一个项目没有配置模型时,问候仍然正常。权限仍是当前用户自己的有效权限,项目范围和工具与 统一管理服务与管理助手 一致。

群聊助手

一个飞书群绑定一个服务角色、一份项目范围(整个组织或多选仓库)和本群的权限档位(只读问答/可评论和打标签/可派活,或高级逐项设置),由对所选仓库有配置权限、已绑定飞书且在群中的维护人在「个人设置 → 飞书绑定」点击「创建群绑定」或对应群条目的「配置仓库与权限」设置。同一个服务角色可以绑定到多个群,每个群的项目范围和档位各自独立。群内有效权限是绑定的档位、授权者当前权限和 GitHub App 安装权限三者的交集,不校验发言人。群聊助手使用服务角色自己的模型,用量记在服务角色上;范围只有一个仓库的群,用量同时计入这个项目的费用(model_requests.repository_id),跨多个项目或整个组织的群不拆到各项目,只记在角色和这个群的会话上;点击群绑定条目或「查看聊天记录」进入「飞书会话」查看本群的消息、执行过程、回答和用量。具体规则、工具和旧群员工迁移见 消息渠道。

群助手的模型

项目的模型保存即被信任、只收到这个项目的上下文(见 架构)。群助手一轮回答可能读范围内任何项目的代码,所以群只能用对范围内每个项目都可用的模型(#849):

保存群绑定、改范围或换角色时检查,不满足返回 409 channel_service_model_unavailable,detail.projects 列出缺少授权的项目;项目角色用到别的项目时返回 400 service_role_project_scope。修改角色的模型时,如果用这个角色的启用中的群里有项目不能用新模型,同样返回 409 channel_service_model_unavailable 并列出这些项目,不保存。每轮回答开始时、以及每次模型请求前再检查一次:模型被删除、撤销授权或某个项目不再授权时,本轮不发出任何模型请求,群里回复模型不可用并点名缺授权的项目,绑定在控制台显示暂停(model_gaps),不会悄悄改用其他模型。群里派出的任务不受影响,仍在目标项目里用项目自己的模型执行。

升级时(#849)每条启用中的绑定所用的共享模型,一次性授权给它当时范围内的全部项目(审计 model.sharing_migrated),这些项目原本就由这个模型读取,所以已有的群不会因新规则停下。

接口

见 管理 API 的 /api/service-roles。

金额用量只统计,不作为调用条件。已知费用按币种汇总,未计价请求与已知 token 分开显示;历史金额配置读取时忽略,重新保存后清除。