镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/service-roles.md ↗
服务角色
Bot 里的角色分两个维度:
- 工作角色:每个项目各自的 Manager、Dev、QA、Reviewer 等,在项目的「角色」页配置,见 Role-Pool。
- 服务角色:平台级的助手,不属于某个项目。内置两个:
management-assistant(管理助手,用于控制台管理助手和飞书个人私聊)和repository-assistant(仓库问答助手,群聊的默认推荐角色)。超级管理员还可以新建自定义服务角色。
全局的服务角色(内置角色和全局模板)在「全局设置 → 服务角色」(#/settings/service-roles)维护,只有超级管理员可以查看和修改。项目管理员还可以为自己管理的项目建项目群助手角色(#849),在「个人设置 → 飞书绑定」的「项目群助手角色」中新建、修改和删除,不需要超级管理员;它属于一个项目(project_id,建好后不能改),只能绑定到范围只有这个项目的群。
定义
每个服务角色有名称、职责说明、提示词、模型和配置版本(revision)。群聊助手角色只是提示词和模型的模板:一个群能做什么由它的群绑定的权限档位决定(#849),见 消息渠道。
- 模型:全局角色只能从部署共享模型(不属于任何仓库的模型)中选择;项目群助手角色还可以选本项目的专属模型,或已授权给本项目的共享模型(否则 400
project_model_required)。没有配置模型时,这个角色的对话直接提示到控制台配置,不会改用某个项目的模型或其他模型。删除模型时,用到它的服务角色改为未配置模型;删除项目时,它的项目群助手角色一并删除;仍被群绑定引用的保留并停用,用的是这个项目的专属模型时模型一并清除(随项目删除)。群聊还要遵守下文的「群助手的模型」。接入向导设置默认共享模型时,还没有模型的内置角色同时采用它;已经选了模型的角色不受影响。 - 提示词附加在内置安全提示之后,只是行为说明,不能扩大工具或权限。
- 权限只有管理助手有:它固定允许统一目录(见 共用角色权限)的全部已接入能力(
permissions_fixed: true),仍与当前用户有效权限和项目范围取交集,提供的github_write只写当前用户能写任务(tasks.write)的仓库。群聊角色不再带权限:给它们提交permissions返回 400service_role_permissions_moved,页面也不再显示权限编辑。#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 时,不提供这些工具。
- 电脑:manager 在宿主 Docker 上创建的同级容器(
manager/assistant-computers.mjs),用批准的项目电脑基础镜像(不含任何项目的软件包、环境变量和初始化脚本,BOT_ASSISTANT_IMAGE可另指定),uid 10001、只读根文件系统、去掉全部 capabilities、no-new-privileges、init,每台默认 1 CPU、2048 MiB 内存(含 tmpfs)、512 个进程,没有网络,用 Docker 的默认运行时(runc)。CPU、内存、进程数、/tmp和工作目录大小在「全局设置 → 助手电脑」修改,范围与项目电脑相同;新值用于之后创建的电脑,空闲的电脑在归属的下一个回合开始时按新值重建(HOME 保留,/tmp和工作目录清空),进行中的回合不受影响。不在容器里嵌套其他沙箱,创建失败时工具明确返回assistant_computer_unavailable,不改在项目电脑或宿主上执行。 - 目录:
~(/home/assistant)是持久 HOME;工作目录/workspace和/tmp是 tmpfs(默认各 512 MiB,内容计入内存上限,写满时命令得到“磁盘已满”),可以运行放在里面的程序,随电脑删除。pip、uv、npm 的缓存指向/tmp,用户级安装(pip --user、uv tool)仍在 HOME。提示词要求临时文件写/tmp,只有值得以后复用的数据才写 HOME;群的 HOME 由本群现有和以后加入的成员共用。 - 生命周期:一个回合第一次运行命令或读写
/tmp、工作目录时创建(或复用)这台电脑;只读写 HOME 的回合和没有命令权限的回合不启动电脑,由控制面直接读写 HOME(打开文件后按/proc/self/fd核对真实路径在本归属的目录内,只接受普通文件,符号链接和..一律拒绝)。回合进行中(含模型思考和其他工具)控制面每 30 秒续期;最终回复交出、回合失败或被停止后,结束本回合启动的全部进程,开始空闲计时(默认 5 分钟),期间同一归属的新回合直接复用,/tmp仍在。空闲到期、最长存活(默认 4 小时,只在两个回合之间检查)、授权围栏变化(群的成员、绑定及其档位、角色或授权人权限变化;个人的授权版本变化)、绑定停用都会立即删除电脑;续期中断 2 分钟(控制面崩溃或卡住)也会删除。manager 启动时删除上次留下的全部助手电脑,控制面启动后第一次对账删除不属于正在运行回合的电脑;回合在电脑创建完成后才算持有它,所以正在创建的电脑被这次对账删掉时,回合重新核对权限后再取一次,不因此失败;权限或会话来源已经变化的回合在这次核对时结束,不会重取。同一归属同时只有一个回合使用电脑;同一个人在私信和控制台同时用电脑时,后来的回合等前一个结束。同时存活的电脑达到上限(默认 20 台)时,先删最久未用的空闲电脑,都在使用时按到达顺序排队,排队开始时向对话发一条进度消息。 - HOME 代次:HOME 存在 Compose 卷
assistant-homes的<归属>/home-<代次>,电脑只挂入当前代次(卷 subpath)。绑定换成另一个、服务角色更换、可访问的仓库范围缩小(群:仓库移出绑定或授权人失去权限;私信:本人失去某仓库权限)时开始新代次,旧代次封存、不再挂载,封存满保留期后删除;范围扩大、修改提示词或权限项、群成员变化都不换代。 - 容量与保留:每个回合结束后统计 HOME 的大小和文件数;超过上限(默认 5 GB)时下一回合以只读挂载,工具结果提示模型用
delete_file清理或请管理员在控制台清空,清理后下一回合恢复可写(软上限:单个回合内仍可能写超)。最后一个回合结束后超过保留期(默认 30 天)没有新回合,删除这个归属的全部数据。所有 HOME 合计没有硬上限,超过告警值(默认 50 GB)时在「全局设置 → 助手电脑」和日志中告警。这些值都在「全局设置 → 助手电脑」修改,那里也列出每个 HOME 的占用并可以清空。 - 已知限制:电脑没有网络,不能在线安装软件包;HOME 里的
.pth等配置会在本归属以后的命令中生效(git 不读~/.gitconfig),影响只限本归属,可以在控制台清空。
阶段消息与一轮回答的结束
服务角色的每轮回答(管理助手的一条消息、群聊助手的一次回答,以及会话定时任务的一次运行)默认带有 send_message 工具(#435),用来在工作期间向当前会话发送阶段消息。它不是权限项,也没有审批。系统提示词和工具说明告诉模型何时发送(#453):预计要较长时间的工作(多步工具调用、跨仓库或多文件检索、日志排查、在电脑上执行命令)开始前,先发一条说明接下来要做什么;之后只在有关键发现、新证据或阶段结论时再发;不发「仍在执行」「请稍候」这类没有内容的消息,也不在最终回答里重复已发过的进展;可能安静结束的回合(群里没有 @ 助手的消息、没有可汇报内容的定时任务)在确定要回答之前不发。
- 每轮最多 10 条,回合每并入一条新消息(见消息渠道)再多 1 条。超出后的调用不发送,返回
stage_message_limit(remaining: 0),本轮继续,由最终回答给出结论。系统提示词、工具说明和每次调用的返回值(sequence、remaining)都向模型说明这个上限。 - 只发文字(Markdown,最多 4000 字),发送前脱敏。附件只随最终回答发送。最终回答仍是模型不再调用工具时的那次回复,由系统在本轮结束时发送。独立任务不提供这个工具。
- 发送途径与最终回答相同:飞书私聊、群聊和定时任务在轮次运行期间立即写入发送队列,发送前复核源消息、绑定、授权和围栏;控制台管理助手写入事件流,按顺序显示在最终回答之前。细节见消息渠道和统一管理服务与管理助手。
一轮回答没有步数上限,只在以下情况结束:模型回复时不再调用工具;可以安静的回合里模型调用 stay_silent(见下文);回答被停止(管理助手由用户停止;群聊助手在当前轮源消息撤回或修改、绑定或授权围栏变化时停止,也可以在控制台停止)。其他历史消息编辑或撤回后,会话与电脑保留,助手收到当前正文和变更通知,下一步从当前来源重建派生上下文。成员进出与历史补读不改变授权围栏,旧自有任务和私有记忆继续可用;真实解绑、角色能力收回、授权丢失或机器人被移出群仍作废会话。上下文大小由工具结果的折叠控制,见 Agent 运行时。模型请求暂时失败(90 秒没有输出、连接断开、429、5xx 等)不会结束这一轮:按 Agent 运行时 的规则在同一步重试,最多 5 次;群聊回合每次重试记一个 model_retry 步骤,管理助手发出 model_retry 事件,控制台丢掉失败那次已流出的文字并显示正在重试。重试用完仍失败时,群聊回合把原因写进回合记录(error_detail),飞书会话页显示“原因:…”;管理助手的 error 事件带 detail,控制台显示原因和错误码。独立任务、群定时任务和私聊定时任务使用同一套重试。
保持安静
可以安静结束的回合会多一个 stay_silent 工具(#489):群聊助手回答没有 @ 它的群消息(问题或全部参与模式),群定时任务,以及私聊管理助手执行定时任务。被 @ 的群消息、私聊里本人发来的消息和独立任务不提供这个工具。
- 模型调用
stay_silent后,本批工具调用执行完就结束这一轮,平台不发送回答:同一条回复里写的文字和已选的附件都丢弃,回合照常记为完成。已经发出的阶段消息保留。 - 参数只有可选的
reason(最多 200 字),说明为什么不需要回答,只保存在控制台记录里,不会发到飞书。群聊回合(包括群定时任务)在飞书会话页的回合记录显示为“本轮保持安静,未发送回答:原因”。私聊定时任务在它专属的管理助手里运行,原因记在这次stay_silent调用的工具结果里;定时任务的运行记录显示“无需通知,未发送”。 - 群聊回合中并入了核验 @ 助手的消息后,这一轮就必须回答:此时调用返回
reply_required,回合继续,由模型给出回答。私聊定时任务的专属管理助手不接收并入消息:本人这时发来的私聊消息在私聊自己的会话里另开一轮,照常回答。 - 系统提示词和工具说明都告诉模型:不需要回答时调用
stay_silent,写出的任何文字都会作为回答发出,不要写“无需回复”之类的说明。回答为空仍按安静处理,但提示词不再这样要求模型,因为模型常把“空回答”理解成写一句占位文字。
独立任务
管理助手和群聊助手都可以创建和继续自己的独立任务:为了保持当前对话整洁,把一件事放到单独的上下文里想清楚,只把结论带回当前回答。独立任务不受权限项控制,也没有配置项;它使用与当前对话相同的服务角色、模型和工具,权限也相同(管理助手是固定全权限与当前用户有效授权的交集,群聊助手是群绑定的档位(权限项)、绑定范围和授权者当前权限的交集),不能扩大权限,也不能再开新的独立任务。
- 工具:
start_own_task(标题、要想清楚的问题)、continue_own_task(编号、补充说明)、list_own_tasks、read_own_task、manage_own_task(暂停或取消;暂停后可以继续,取消后不可继续)。 - 归属:管理助手的独立任务属于同一用户的同一个管理会话,群聊助手的属于同一条群绑定。授权修订(管理助手)或群围栏变化(绑定及其档位、角色、授权者权限)之后,旧的独立任务不再可见,也不能继续。
- 每次运行不限步数(每步的工具调用数量也不设上限,结果预算与所在对话相同),每个独立任务也不限轮数:一次运行在给出结论、被暂停或取消、所在对话被停止或授权被撤回时结束。每轮的说明和结论密封保存在
service_role_own_tasks,不进入tasks表,也不出现在项目看板;继续时较早的轮次合计超过 96 KiB 就从最早一轮开始略去并注明略去轮数,read_own_task仍能读到全部轮次。独立任务不向会话发阶段消息。服务重启时运行中的独立任务记为失败(own_task_interrupted),已有结论保留。 - 用量与所在对话一样记在服务角色上(
repository_id为空);已知费用按币种展示,未计价请求单独计数。控制台管理助手把独立任务和其中的查询、命令显示为执行步骤。
用量与计费
服务角色的模型请求记在 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):
- 范围只有一个项目的群,可以用这个项目的专属模型,或授权给它的共享模型;
- 跨多个项目(包括整个组织)的群,只能用对这些项目都授权了的共享模型。共享模型默认对所有项目可用(#850),超级管理员把它限定给部分项目后,才会因范围外的项目被拒绝。
保存群绑定、改范围或换角色时检查,不满足返回 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 分开显示;历史金额配置读取时忽略,重新保存后清除。