镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/api.md ↗
管理 API
管理页面的操作都经由下列接口。它们和管理页面、OAuth 与 App 回调、Webhook 在同一个业务端口(容器 8791,宿主默认 127.0.0.1:8791),对外经同一个 HTTPS 入口访问;Webhook 和外部执行端路径按自己的签名或令牌认证,不需要浏览器会话。部署见部署细节。
除初始化状态、初始化、登录和健康检查外,管理 API 都需要登录会话。登录/初始化响应设置 HttpOnly; SameSite=Strict Cookie,并返回 csrf_token;之后的写请求必须提供同值 X-CSRF-Token 和 Content-Type: application/json。登录后 GET /api/auth/me 可读取当前会话的 CSRF 值。接口不接受额外字段,不支持传入 role 将自己升级。HTTP 失败只返回稳定错误码,不回显输入或内部异常。经 Cloudflare 等入口访问时,502、504 响应的正文会被入口换成它自己的错误页,错误码随之丢失;控制台此时提示“入口网关返回了错误页面”,不显示 JSON 解析错误。需要用户据此处理的错误不用这两个状态码。
项目列表 GET /api/repositories、GET /api/installations 和 GET /api/installations/hidden 支持 repository_id,account_id,owner_id 筛选;先应用权限和筛选,再按原顺序分页。传入 limit 或 offset 时每页默认 50 条、上限 100 条,offset 默认 0;不传分页参数时保留完整列表响应,供其他页面使用。项目页和任务数刷新固定请求当前页的 50 条,再按 owner_id 分组展示;分组不改变权限或筛选。
管理查询 get_effective_config 的 task_creation:{allowed,reason} 是当前身份、项目、安装与凭据条件的只读预检。allowed:true 不授予代码或 PR 写入;提交 task.create 时仍执行原有版本、授权与软件交付检查。
| 路径 | 方法 | 功能和范围 |
|---|---|---|
/healthz |
GET | 业务端口的数据库健康检查 |
/api/setup |
GET / POST | 初始化状态/仅首次创建超级管理员,POST 字段 username,password |
/api/auth/login、/api/auth/logout、/api/auth/me |
POST / POST / GET | 登录、退出、会话与仓库权限 |
/api/users、/api/users/:id |
GET / POST、PATCH / DELETE | 超级管理员列出/创建用户、停用或启用;创建可带 role,repository_ids,organization_ids,含义同下行,超级管理员忽略这两项。DELETE 需 confirm:true,删除会话、仓库和组织授权、个人看板设置,审计保留;最后一名活跃超级管理员返回 409 last_super_admin,删除自己成功后会话失效 |
/api/assistant-computers |
GET | 仅超级管理员。每个群、每个人 HOME 的 {owner,kind,name,generation,bytes,files,measured_at,active_at,read_only,computer,sealed},以及 totals:{bytes,alert_bytes,alert}、数据盘 disk 和运行中的电脑数 |
/api/assistant-computers/:owner/clear |
POST | 仅超级管理员。删除这个归属的电脑和 HOME 的全部数据(含封存代次),记审计 assistant_computers.home_cleared |
/api/agent-tools、/api/agent-tools/install、/api/agent-tools/prune |
GET、POST、POST | 仅超级管理员(#705)。GET 返回 /opt/agent-tools 卷状态(arch、各 CLI 的兼容版本范围 compatible_range、已安装版本、选定版本及来源 manifest)、当前保留版本数 retain_count 与允许范围 retain_bounds:[1,10]。POST /api/agent-tools/install 字段 cli(claude_code/codex)、version(精确 semver)、可选 sha256、native_sha256(仅 claude_code,校验原生二进制包 SHA-256)与 retain_count(传入且安装成功后保存为默认保留数,响应 status.retain_count 即该次保存值),从固定官方源下载并校验 SHA-256/npm integrity 后原子安装到 /opt/agent-tools/<cli>/<version>/(Claude Code 附带受控 Node 运行时;Codex 在 GitHub API 触发匿名限流但请求显式携带 sha256 时可回退到固定发行版地址并严格校验该 sha256),记审计 agent_tools.installed;上游下载或校验失败返回 502。该版本正被运行中的 task_runs.cli_version 或 role_conversation_turns.cli_version 使用时返回 409 agent_tool_version_in_use(field 形如 codex@0.166.0),替换 Claude Code 依赖的 Node 运行时同理(field 形如 node@22.15.0);入口先拒绝一次,下载完成替换目录前再读一次活动版本,期间被领用的运行同样拒绝。POST /api/agent-tools/prune 字段可选 cli、retain_count(传入时在清理成功后保存为默认保留数,清理失败不改变设置),清理旧版本与无引用的 Node 运行时(无引用的 Node 运行时只在省略 cli 或 cli 为 claude_code 的那一趟回收:只有 Claude Code 的清单会指名它要哪个 Node 运行时,cli=codex 的清理不删 Node 运行时),正在运行的 task_runs.cli_version/role_conversation_turns.cli_version 与刚安装的版本始终保留;清单已不可读的版本目录(例如安装中断留下的残骸)平时照旧清理,但其中属于上述保留版本的目录保留下来、不改动其内容,并在响应中列出:POST /api/agent-tools/prune 返回 protected_invalid(按 CLI 分组的版本号数组 {claude_code,codex}),POST /api/agent-tools/install 返回扁平的版本号数组(恒在,未触发清理时为空数组);该目录执行的 Node 运行时(node/<ver>)同样不在这一次清理中被删,等那次运行结束后下一次清理才删除;记审计 agent_tools.pruned |
/api/settings |
GET / PATCH | 仅超级管理员,项目管理员得到 403。返回 settings:{task_concurrency,task_concurrency_bounds,computer_defaults,assistant_computers} 和 version;PATCH 字段 task_concurrency、computer_defaults、assistant_computers,至少一个。assistant_computers(#457)读取时为 {computers:{settings,defaults,bounds,host,usage},homes:{settings,defaults,bounds}}(host 同 computer_defaults),部署没有助手电脑时为 null;PATCH 时传 {idle_minutes?,max_containers?,max_lifetime_minutes?,cpus?,memory_mb?,pids?,tmp_mb?,workspace_mb?,home_limit_gb?,retention_days?,total_alert_gb?} 的部分值:资源是每台助手电脑的 CPU、内存、进程数、/tmp 和工作目录大小,范围同下方 configure(workspace_mb 同 tmp_mb),cpus 可到两位小数,其余都是整数;cpus 超过主机 CPU 数返回 400 cpus_exceed_host,任何一项不合法返回 400 且整次不保存,部署没有助手电脑时返回 503 assistant_computers_unavailable。新资源用于之后创建的电脑,空闲的电脑在归属的下一个回合开始时按新值重建。task_concurrency 是每台虚拟电脑默认同时运行的任务数,1–32 的整数,未设置时为 1,超出范围返回 400 invalid_task_concurrency。computer_defaults 由 manager 保存和执行,读取时为 {defaults,builtin,bounds,host,allocated}(host 是主机 CPU 数与内存 MiB,读不到时为 null;allocated 是运行中虚拟电脑的台数与分配总量),manager 不可用时整项为 null;PATCH 时传 {cpus?,memory_mb?,pids?,tmp_mb?} 的部分值,范围同下方 configure,cpus 超过主机 CPU 数返回 400 cpus_exceed_host,其他非法值返回 400 invalid_defaults。新建的虚拟电脑立即使用新默认值;已有电脑中跟随默认值的资源在没有任务运行时由控制面重建容器生效(工作卷和代次保留),重建期间这台电脑不领取新任务 |
/api/storage |
GET | 登录用户。存储页的数据(轨迹文件):projects 列出可见项目各自的轨迹文件 files、按类型的记录 records、blobs、写入中的文件 open 和 manager 侧的 manager(各为 {count,bytes},其中 manager.expired 是过期删除的文件);超级管理员看全部项目(含不属于项目的会话),并另有 totals(两个数据库的大小与空闲页(database.auto_vacuum,以及上次启动时的压缩 totals.*.compaction 和之后的增量回收 totals.*.vacuum)、所在磁盘剩余与保留空间、后台迁移进度、manager 过期删除 totals.manager.expiry、Docker 镜像、容器可写层与构建缓存 totals.manager.docker(每项 {count,bytes},镜像与构建缓存另带可回收字节;尚未读到、或其中一项 Docker 没有给出可用大小时该项 bytes 为 null,容器单独一次读取,读取失败只让容器一项为 null))、alerts(剩余低于保留空间的磁盘,where 为 control 或 manager,见剩余空间保护)、host(数据盘与已知占用 known、other_bytes)、reclaimable 和 freed;每个项目另有 computer(项目电脑工作卷最后一次后台扫描,任务工作区按保留规则分类,见存储页);项目管理员只看自己的项目,没有 totals。读写入时累加的计数和每 5 分钟的后台快照,不扫描文件或数据表;refreshed_at 是快照时间;manager_read_at 是 manager 与各项目 computer 数字的读取时间(从未成功读过时为 null),manager_error 是最近一次后台刷新读 manager 失败的错误码(成功时为 null),读取失败时这些数字与 alerts 里来自 manager 的那条(带 stale:true)都保留上次成功的结果 |
/api/storage/retention |
GET、PUT | 超级管理员。按天数清理的设置(settings,含 defaults、bounds)、可设置的项目、最近一次每日清理(last_cleanup)和群聊保留汇总(chats);PUT 只改给出的字段,越界或未知字段返回 400 storage_retention_invalid(field 指出字段),保存记入审计。见按天数清理 |
/api/version |
GET | 仅超级管理员;控制面进程环境 BOT_IMAGE_TAG 给出的镜像标签 {image_tag,source:"image"},源码直接运行、变量为空时为 {image_tag:null,source:"source"} |
/api/project-admin-assignments |
GET / PUT | 超级管理员查询/替换项目管理员的授权。GET 返回 assignments(单个仓库)、organization_assignments(整个组织,user_id,owner_id)和 organizations:当前已安装仓库按 owner_id 分组,每组带 owner_login 和仓库 id,full_name,registered。PUT 字段 user_id,repository_ids,organization_ids,给出的那份整份替换、省略的那份不变,空数组表示不授权。仓库 ID 须是已安装或已启用的仓库(已安装未启用的仓库启用后授权生效),否则 400 repository_not_found;组织 ID 须是某个已安装仓库的 owner_id,或是 PUT 所改用户已有的组织授权(其仓库都已移出安装时保留,名单里去掉才删除),否则 400 organization_not_found 且不改已有授权。项目管理员的仓库范围是单个仓库加上这些组织下的全部项目,每次请求重新计算 |
/api/accounts、/api/accounts/:id |
GET / POST、GET / PATCH / DELETE | 超级管理员管理 GitHub App/机器人账号;POST 字段 name,type,app_id,private_key,token,webhook_secret 按账号类型选用。DELETE 需 confirm:true,仍有项目使用该账号时返回 409 account_has_projects;只从本系统删除账号、Webhook 入口、安装同步记录和凭据,不调用 GitHub |
/api/accounts/:id/credentials/revoke |
POST | 超级管理员撤销账号认证材料 |
/api/accounts/:id/permissions |
GET | 超级管理员检查 GitHub App 权限和事件订阅:返回所需权限 required 与所需事件 required_events、App 缺少的权限 app.missing 与未订阅的事件 app.missing_events、App 权限设置页 app.settings_url,只检查 App 定义,齐全时 ok:true;安装缺口在项目列表显示;机器人账号返回 409 |
/api/onboarding/app/refresh |
POST | 仅超级管理员,需 CSRF 和合法 Origin;正文 {account_id} 必须是向导当前所选的 GitHub App。使用 App JWT 读取 GET /app,补全并返回 {app} 的 slug,owner,owner_type,settings_url,install_url,保留 Webhook、安装状态和凭据。不会回传密钥或切换登录配置。查询失败或 GitHub 返回不匹配的 App/缺少所有者时返回 502 github_app_metadata_unavailable;请求期间另一个页面更换了所选 App 时返回 409 github_app_changed,不覆盖新选择 |
/api/github/rate-limits |
GET | 超级管理员读取 GitHub 每小时请求窗口,按账号分组:accounts:[{account_id,name,type,buckets:[{key,kind,installation_id,owner,blocked_until,waiting_tasks,windows:[{resource,quota,used,remaining,reset_at,expired,observed_at}]}]}]。kind 是 app(App 自身的 JWT)、installation(App 在一个组织或用户上的安装,owner 为其登录名)或 user(Token 账号所属的 GitHub 用户,owner 为用户登录名,所有仓库和该用户的其他 Token 共用);resource 为 core(REST)、graphql 或 search;blocked_until 是 REST 窗口用完或被 GitHub 拒绝后可再发送的时间(毫秒),waiting_tasks 是等它的任务数;expired 表示窗口已重置、数字是上一窗口的 |
/api/accounts/:id/rate-limits/probe |
POST | 超级管理员立即读取账号的窗口:App 读自身窗口,并为每个未暂停的安装签发只读 metadata 令牌读取后吊销;Token 账号读取 Token 所属用户的窗口。窗口经 GET /rate_limit 读取,这个请求不计入额度;App 列出安装、签发令牌用的是 App 自身(JWT)的请求,Token 账号还没记下登录名时会多发一次 GET /user(计入该用户的额度)。正文 {},返回同上 |
/api/accounts/:id/endpoints、/api/accounts/:id/endpoints/:endpoint |
POST、PATCH | 创建签名入口/轮换签名材料;PATCH 带 webhook_secret 或 revoke:true |
/api/repositories、/api/repositories/:id |
GET | 范围内列表/详情;仓库由安装同步发现,经 POST /api/installations/:id/activate 启动后登记 |
/api/repositories/:id/policy |
GET / PATCH | 范围内策略,字段 model_id,capability_ceiling,review_enabled,development_enabled,enabled,test_command,base_branch,max_revisions,task_concurrency;capability_ceiling 是项目能力上限 read/comment/develop,review_enabled、development_enabled 是它的旧写法,读到的总与它一致,不能与它同时写(invalid_capability_ceiling),见项目能力上限;task_concurrency 是这台虚拟电脑同时运行的任务数,1–32 的整数,null 跟随全局默认,项目管理员可以改自己的项目,响应另带全局默认 task_concurrency_default;选择模型、设置能力上限、指定必需测试和跟进预算;基准分支留空时读取仓库默认分支;检视规则字段 review_issues、review_pull_requests、review_pr_updates、review_issue_updates、review_pr_discussion(布尔,分别控制 Issue 打开、PR 打开/转为可检视、PR 新提交、Issue 被修改或有新评论、PR 被修改或有新评论/检视/检视回复时是否触发检视)和 review_language(auto/zh/en);review_label(检视发布后加的标签,空字符串表示不加)和 development_label(人加上它表示要求开发,不能为空),最长 50 个字符、首尾不能有空白和控制字符,否则返回 invalid_label,默认 bot-reviewed/bot-develop。检视指引不是策略字段,写在 Manager 提示词的检视章节里 |
/api/repositories/:id/rules |
GET | 任务使用的规则:每个规则章节的内置文本和 Manager 提示词里的项目文本(files 仍以原 .bot/ 路径为键)、项目电脑规格及只读 computer_sources、检视和开发标签、默认分支上的仓库 skill,retired_files 列出默认分支上仍有、但已不再读取的 .bot/ 文件,imported 是升级时一次性导入的报告(导入的文件、写入的章节、标签、机器配置字段和警告;升级后新加的项目为 null)。needs_refresh: true 或 sha: null 表示还没读过默认分支。POST …/rules/refresh 用正文 {} 重新读取默认分支的 skill,成功返回 201 及更新后的 rules。原控制台覆盖的 PUT 和 POST …/rules/apply-computer 返回 410 rules_update_removed,说明改用 manager.update、roles.update 和项目设置,见在角色配置里调整行为 |
/api/repositories/:id/manager、/api/repositories/:id/dispatch、/api/repositories/:id/dispatch/:event、/api/repositories/:id/dispatch/:event/retry、/api/tasks/:id/dispatch |
GET / PUT、GET、GET、POST、GET | 项目配置与 Manager 的兼容接口:提示词、工作类型的开关和写入、项目级事件开关,分派记录、项目内详情与人工重试,任务的分派来源。原 /api/repositories/:id/workflows 返回 410 workflows_removed。字段和错误码见项目 Manager 与工作类型 |
/api/environments、/api/environments/:id |
GET | 按账号、组织 ID、仓库过滤环境;项目管理员无筛选也只见被分配仓库。列表和详情带这台电脑上正在运行的任务 running_tasks;详情另含按入队时间排序的完整排队任务 queued_tasks(不受最近任务条数限制)、生效并发度 task_concurrency、manager 给出的容器/卷/网络/镜像/资源限制、最近 20 个任务和最近 30 条命令 |
/api/environments/:id/start、/stop、/reset |
POST | 仓库管理员操作;字段 operation_id,generation,操作 ID 为 48 位随机十六进制;重试必须复用同一 ID |
/api/environments/:id/configure |
POST | 仅超级管理员;字段 operation_id,generation,spec,spec 可含 cpus(0.25–16)、memory_mb(256–65536)、pids(64–16384)、tmp_mb(16–16384),资源设为 null 时清除项目自己的值、改为跟随全局默认(内置默认依次为 2、4096、1024、1024,可在 /api/settings 修改),详情里 computer.inherited 列出跟随默认的资源,computer.resources_pending 表示新默认值尚未应用到容器;另可含 egress、egress、packages(最多 100 个 Debian 包名)、env(最多 64 个非机密变量,PATH、HOME、BOT_*、GIT_* 等保留名拒绝)、setup_script(≤16 KiB)和一次性的 rerun_setup。范围由 manager 校验;规格随项目保存、跨重启和重置保留,保存后在项目锁内重建容器,工作卷和代次不变;软件包镜像构建失败时不改动正在运行的电脑。资源设为 null 时跟随全局默认;仓库里的 .bot/computer.yaml 不再读取,规格只有这一处来源(#935) |
/api/environments/:id/stats |
GET | 范围内实时资源:CPU、内存、进程数、网络、磁盘读写和工作区占用(工作区每分钟最多统计一次),不占用项目锁 |
/api/repositories/:id/knowledge-files、…/:fileId、…/:fileId/versions、…/:fileId/restore |
GET / POST、GET / PUT / DELETE、GET、POST | 统一自由文件入口;创建只需 name,content,读旧版本用 revision,修改/删除带 expected_revision,恢复带 revision,expected_revision。保留原文、历史与角色可见范围;删除后可恢复,过期修改报 note_revision_changed。不启动项目电脑,旧笔记和知识原地兼容;列表另带 quarantined:[{id,path,reason}],列出旧规则留下、名称含控制字符而不再可寻址的文件(记录与磁盘文件原样保留,不影响同卷健康文件);详见 文件协议 |
/api/repositories/:id/notes、/api/repositories/:id/notes/:name |
GET、GET / PUT / DELETE | 超级管理员及本项目管理员列出、读取、保存(content)和删除笔记;manager 直接访问稳定笔记卷,不启动电脑。:name 是 URL 编码的单段文件名,支持 Unicode 和任意扩展名,但不含控制字符(NUL、其余 C0、DEL、C1、U+2028/U+2029),这类名称以 invalid_note_name 或 invalid_note_path 拒绝;仍拒绝路径逃逸、子目录及内部锁文件名。内容原样保存,不设文件数量和容量配额 |
/api/environments/:id/delete |
POST | 仅超级管理员,另需 confirm:true;删除容器/网络,保留卷 |
/api/models、/api/models/:id |
GET / POST、GET / PATCH / DELETE | 范围内模型,字段 repository_id,api_url,api_key,model_name;POST 也可以用 key_from(同一项目、或同为部署共享的已保存模型 ID)代替 api_url 和 api_key,新模型沿用该模型的 URL,并封存一份它的 Key,用于给同一供应商再添加模型;与 api_url/api_key 同时出现返回 400 invalid_model_source,来源不在同一范围返回 404 model_not_found,来源的 Key 已撤销返回 409 model_key_missing;PATCH 带 version;version 仅在该模型自己的 api_url 或 model_name 实际变化时递增,轮换/撤销 Key、价格更新及新增同供应商的兄弟模型不递增。在途任务固定地址和模型名,每次模型请求读取当前 Key;撤销后等待重新配置 Key,恢复后沿用原模型版本和任务快照,无需采用新配置。列表对每个模型返回 used_by:调用者可见范围内选用该模型的项目 [{repository_id,full_name}],没有可见项目选用时为空数组;详情中的 model.used_by 规则不同——只向超级管理员或该模型所属项目的管理员返回,其余调用者不带这个字段;相同详情权限还返回 role_used_by(当前已保存配置中的显式引用,含停用角色,不含历史版本和运行快照)及 onboarding_default 布尔值。角色项的 type 为 project_role 或 service_role,均带 role_id,name,enabled;项目项另带 repository_id,full_name,configuration_enabled,服务角色项的 repository_id 为 null;不返回提示词或密钥。列表的 used_by 仍仅表示项目默认/工作类型引用,不增加角色数据 |
/api/models/:id |
DELETE | 权限同 PATCH:项目管理员可删本项目专属模型,共享模型仅超级管理员可删;不可见或未知模型返回 404 model_not_found,可见共享模型被项目管理员删除返回 403。正文 {},无需 version;事务内清空选用策略、删除单价和共享关系及模型配置,销毁封存的 Key;它是接入向导的默认模型时一并清除该默认(/api/onboarding 的 model_id 变为 null),选用它的服务角色改为未配置模型(revision 加一,审计 service_role.model_cleared),审计 model.deleted。响应 {ok:true,cleared_repository_ids:[...]},不含 Key;保留历史模型请求和成本快照,不取消已运行任务,之后找不到模型沿用 model_not_configured/waiting_configuration |
/api/models/:id/projects、/api/models/:id/credentials/revoke |
PUT、POST | 共享模型默认对所有项目可用(读到 all_projects: true,#850);超级管理员用 PUT {repository_ids:[…]} 把它限定给这些项目(审计 model.sharing_updated),{repository_ids:null} 恢复为所有项目可用(审计 model.sharing_all_projects)。有权编辑者用 POST 撤销模型 Key |
/api/service-roles |
GET / POST | 见服务角色。超级管理员看到全部角色;项目管理员只看到自己有 config.write 的项目的项目群助手角色。GET 返回 service_roles(每项含 id,builtin,enabled,name,responsibility,prompt,project,model_id,model,permissions_fixed,revision,usage,project 是所属项目 {id,full_name} 或 null,model.project_id 标出项目专属模型,管理助手另有固定的 permissions;usage 是该角色累计的 requests,input_tokens,output_tokens,cached_input_tokens,usage_missing_requests,unpriced_requests,last_requested_at,costs)和统一权限目录 permission_items。POST 新建自定义角色,字段 name(必填),responsibility,prompt,model_id,enabled,project_id:不带 project_id 是全局模板,仅超级管理员;带 project_id 是该项目的群助手角色,要求对该项目有 config.write,model_id 可以是该项目的专属模型或已授权给它的共享模型(否则 400 project_model_required)。返回 201 {service_role}。群能做什么由群绑定的权限档位决定(#849),给群聊角色提交 permissions 返回 400 service_role_permissions_moved |
/api/service-roles/:id |
PATCH / DELETE | 全局角色仅超级管理员,项目群助手角色由对所属项目有 config.write 的人维护。都必须带 expected_revision,版本已变返回 409 service_role_revision_conflict。PATCH 字段同 POST,只改提交的字段:全局角色的 model_id 只能是共享模型(否则 400 shared_model_required),换模型时如果用这个角色的启用中的群有项目不能用新模型,返回 409 channel_service_model_unavailable,detail.projects 列出这些项目;管理助手使用统一目录的固定全权限(permissions_fixed:true),试图缩减返回 400 service_role_permissions_fixed,实际操作仍受当前用户授权约束,内置角色不能停用或删除(409 builtin_service_role_required)。DELETE 正文 {expected_revision},返回 {ok:true,id},已有用量记录保留 |
/api/models/endpoints?api_url= |
GET | 不需要 Key 的地址解析:返回 chat_url、models_url 和 has_v1(去掉末尾 / 和 /chat/completions 后,路径是否以 /v1 结尾);不会添加或删除 /v1。模型的读写响应也带同样内容的 endpoints |
/api/models/upstream、/api/models/test |
POST | 未保存的模型:用提交的 api_url,api_key 获取上游模型列表;测试另带 model_name,发一次最小的 Chat Completions 请求。带 repository_id 时要求该项目的管理权限,为 null 时只允许超级管理员;不写数据库 |
/api/models/:id/upstream、/api/models/:id/test |
POST | 已保存的模型用自己的 URL、Key 和模型名获取列表/测试,正文 {};权限与编辑该模型相同(共享模型只允许超级管理员),审计记为 model.upstream_listed/model.tested;Key 已撤销返回 409 model_key_missing |
/api/events、/api/events/:id |
GET | 范围内投递列表/正文和响应;读路径对 payload、response、request_headers 逐层(含嵌套对象与数组元素)按键名闭集 token,secret,password,authorization,cookie,private_key(大小写不敏感)把值换成 [redacted],闭集之外的键原样返回;解析成功但无法完成过滤的正文返回 {"redacted":true,"reason":"redaction_failed"} 而不是原文,只有不是 JSON 的正文按原字节返回。管理命令回执的 arguments、result 走同一个出口;列表可筛选 repository_id,account_id,owner_id,event,status,delivery_id,limit,offset。未限定范围的超级管理员另返回 rejected_archive(rows,bytes,pruned_total,max_rows,max_age_ms,summary_bytes,header_bytes,即被拒投递档案的当前占用与上限);只有非租户范围(无 context.tenant_id)的超级管理员能读到它,且带 repository_id/account_id 过滤时仍按全平台统计返回,租户范围内的会话一律不返回 |
/api/tasks、/api/tasks/:id、/api/tasks/:id/logs、/api/tasks/:id/checks |
GET | 范围内任务列表、结果、发布回执(详情状态只含候选及证据元数据,历史为最近 50 项并附 history_page,正文从来源入口读取)和带时间的公开过程日志;支持 `kind=review |
/api/tasks/:id/events |
GET | 事件索引,after 游标、limit 1–100(默认 50),支持 run_id/type/revision/candidate_id;默认只返回元数据,include_data=1 内联至多 8192 字符的数据,完整数据通过来源接口读取 |
/api/tasks/:id/runs |
GET | 运行索引,after、limit 1–100(默认 20);include_snapshots=1 返回输入/输出快照 |
/api/tasks/:id/source |
GET | ref 指向 task_history、task_runs、model_requests 等来源;校验任务及项目范围,保留完整性、缺失及脱敏标记 |
/api/tasks/:id/lineage |
GET | 父子任务、验收决定及关联来源;沿用项目读取授权 |
/api/tasks/:id/live |
GET | 运行中任务当前正在执行的命令及其已产生的输出,参数 offset 为已读字节数 |
/api/board |
GET | 当前用户的视图、自定义单选字段及选项、七个固定 bot 阶段;阶段带 hint 说明,PR 看板措辞不同时带 pr:{name,hint} |
/api/board/cards |
GET | Issue/PR 对象与 project_releases 发版本卡片,参数 view_id(默认 default)、group_by、filters(JSON 数组)、limit(1–100)、offset(0–100000);返回 cards,has_more,limit,offset,counts,release_count,work_count,column_counts,对象和发版本均始终限制在当前仓库授权范围。counts 为 {issue,pr} 总数,忽略 object_type 条件、保留其余条件,表示去重的对象数;work_count 为筛选后的工作卡片总数,column_counts 为当前分列各组的全量工作数;对象卡片带 card_category(review/development)、该类别最新的 task_id,task_status 及独立的阶段/执行状态;对象卡片的 development_pr_number 是最近开发任务结果里的 PR 编号,发版本卡片带 release_id,version,release_stage,execution_status,release_url,不返回原始 data |
/api/board/cards/:repository/:type/:number/tasks |
GET | 同一对象的关联任务摘要,type 为 issue 或 pr,支持同样的有界分页;filters 可带 category 和 execution_status;界面按卡片类别读取全部关联任务,避免执行状态筛选隐藏历史任务;任务详情沿用 /api/tasks/:id |
/api/board/cards/:repository/:type/:number |
PATCH | {field_id,option_id} 修改当前用户的自定义单选值,option_id:null 清空;禁止写执行阶段,不创建或修改任务 |
/api/board/fields、/api/board/fields/:id/options |
POST | {name} 新建个人单选字段/新增选项(即加列),每用户最多 30 个字段、每字段最多 50 个选项 |
/api/board/views、/api/board/views/:id |
POST、PATCH / DELETE | 个人视图,字段 name,group_by,filters,hidden_columns;最多 50 个自建视图。内置 default 可保存筛选、折叠列和标准查看维度,不能删除、改名或切换为自定义字段 |
/api/installations、/api/installations/sync |
GET、POST | 仅超级管理员;每个仓库一行,合并 GitHub 安装范围、登记、启用和环境状态(organization_trusted 说明仓库的 owner 是否受信任),以及各账号最近同步结果;POST 立即全量同步,results[] 带每个账号的 installations(未暂停安装的 id,account,missing,missing_events)及 app 定义检查结果(失败为 {error}),供控制台保留同步结论;账号同步失败时返回该项的 error。hidden=1 的行不出现在这里 |
/api/installations/hidden |
GET | 仅超级管理员;从列表隐藏的仓库,仍保留安装行;每行可调用恢复 |
/api/installations/:id/activate、/api/installations/:id/disable |
POST | 超级管理员启动(可带 model_id,capability_ceiling,account_id;capability_ceiling 是项目能力上限 read/comment/develop,不带时首次启动为 comment、再次启用保留原档位且至少 comment;旧写法 development_enabled 仍可用,true 为 develop、false 为 comment,不能与 capability_ceiling 同时出现;以及 trust_organization:true 同时按本次的共享模型和能力上限信任仓库的 owner)或再次启用/禁用一个仓库;受信任组织下尚未启动的仓库,其 GitHub 派生管理员也可用空请求体启动(用组织默认值;不受信任 403 organization_not_trusted,不是管理员 403 repository_admin_required,已登记 403 installation_forbidden) |
/api/trusted-organizations |
GET | 仅超级管理员;受信任的组织(owner_id,owner_login,trusted_by,trusted_at,updated_at,model,capability_ceiling,以及与之一致的旧字段 development_enabled)和可以信任的已安装 owner(candidates) |
/api/trusted-organizations/:owner_id |
PUT、DELETE | 仅超级管理员;PUT 信任或修改默认值(model_id 只接受部署共享模型或 null;capability_ceiling 是在这个组织下启动的项目的能力上限,不带时为 comment,旧写法 development_enabled 换算同启动接口),审计 organization.trusted/organization.trust_updated;DELETE 撤销信任,审计 organization.untrusted,已启动的项目不受影响 |
/api/installations/:id |
DELETE | 仅超级管理员;只把该仓库的安装行标记为隐藏(hidden=1),不访问 GitHub、不改项目策略或任何其他表,同步也不会让它重新出现;没有安装行返回 404 repository_not_installed,成功返回 {hidden:true} |
/api/installations/:id/restore |
POST | 仅超级管理员;取消隐藏(hidden=0),返回 {hidden:false};没有安装行返回 404 repository_not_installed |
/readyz |
GET | 部署就绪:数据库、manager 与笔记卷对账。notes_volumes 报告 orphans、threshold、oldest_seconds、max_age_seconds、warn_age_seconds、retrying、abandoned、trajectory_orphans、over_threshold、over_age;超过 BOT_NOTES_ORPHAN_THRESHOLD 或最老孤儿超过 BOT_NOTES_ORPHAN_MAX_AGE_MS 时返回 503 |
/api/maintenance/orphans |
GET | 仅超级管理员:列出仍未回收的笔记卷(repository_id、name、first_failed_at)与无主轨迹目录(repository_id、path),以及同一份 report;manager 读不到卷时退回审计意图、置 notes_volumes_unreadable:true 并保留 report 的计数;正常读取时该标志为 false |
/api/installations/:id/removal |
DELETE | 仅超级管理员,需 confirm:true;当场向 GitHub 核对后删除项目(未启动的仓库只删安装列表行)。仍能访问返回 409 repository_still_accessible,权限不足返回 409 repository_permissions_insufficient,GitHub 不可用、限流或答复不确定返回 502,凭据缺失返回 409 github_credentials_missing,以上都不删除;容器或网络删除失败、记录清理校验失败或任务未停下时项目保持禁用、记录保留;笔记卷在删除记录的事务提交之后才以 best-effort 删除,manager 删不掉时删除仍返回成功并记 repository.notes_removal_failed 审计,卷可能残留;重试删除不会清理它(此时项目行已不存在,请求不再到达 manager),删除是逻辑删除 + 异步回收,不是立即物理删除:残留卷由 #771 的对账任务回收,/readyz 报告孤儿卷数量与最老一份的年龄,并由 /api/maintenance/orphans 列出 |
/api/projects/:id/gate-onboarding、/api/gate-onboarding/… |
任意 | 「接入门禁」已删除(#931),一律返回 410 gate_onboarding_removed,detail 说明改用开发任务以 bot PR 改 CI(POST /api/tasks 的 workflow_changes) |
/api/installations/permissions/check |
POST | 仅超级管理员;App 通过带版本检查的完整安装同步重读权限及范围,机器人账号重读仓库权限;返回每行的 permission_missing,permissions_checked_at,permissions_stale 和各账号错误;失败保留最近成功快照 |
/api/installations/archive |
GET | 仅超级管理员;包括零仓库、暂停、卸载及历史证据缺失的安装档案,不含原始 payload 或凭据;契约与恢复说明 |
/api/installations/archive/:host/:appId/:installationId |
GET | 仅超级管理员;当前投影、版本与人员证据摘要;附加 /repositories 或 /events 读范围或事件索引,POST .../sync 持久化请求同步 |
/api/tasks/:id/retry |
POST | 有权项目管理员重试故障任务;发布未知时仍先对账,不直接重复 POST。waiting_publication 的重试即人工确认:结果未知的写入回到待发送,先查找,查不到才发送。needs_replan 在尚未写入 GitHub 时从准备阶段重新规划 |
/api/tasks/:id/writes |
POST | 设置普通任务(#814)被授予的写入:writes(完整列表,取值 pull_request、review、github)和必填的 reason。放宽要在项目能力上限与开关、任务来源的上限之内,角色只有项目主控(Manager)可以调用,并且不超出它自己的权限;有权管理项目任务的人也可以调用;收窄在下一次调用时生效。写审计 task.grant_writes。拒绝返回 403 capability_ceiling/task_software_disabled/task_external_write_forbidden/task_pull_request_forbidden(detail.write 为被拒的写入),已结束的任务 409 task_already_delivered,#814 之前建的任务 409 task_writes_not_grantable。POST /api/tasks 同样接受 writes,intent=development 或 PR 终点映射为 pull_request;任务详情的 writes 给出已授予、现在生效、可授予的写入、授予记录和每次运行的交付工具(旧任务为 null)。项目策略 PATCH /api/repositories/:id/policy 的 delivery_gates: {pull_request_qa: false} 关闭开 PR 前的独立 QA 门槛(默认开;没有配置测试命令的项目仍要独立 QA)。 |
/api/audit、/api/status |
GET | 范围内最近 100 条操作审计/当前能力状态 |
/api/costs |
GET | 授权范围内的统计。参数 timezone 为浏览器的 IANA 时区(省略时兼容 UTC,无效时返回 400 invalid_statistics_timezone),from,to 为该时区的 YYYY-MM-DD(含首尾,默认最近 30 天,最多 366 天),repository_id 可省略,currency 为 USD(默认)或 CNY。模型费用和 token 按 requested_at 的本地日、项目聚合;费用最多 5000 个日期/项目分组,超限要求缩小范围。返回 days,summary,prices,other_currencies,timezone,collection_started_at,tasks;summary 只合计所选币种及尚未定价的请求,other_currencies 按币种列出同一授权与日期范围内因币种过滤而未计入这些合计的请求数([{currency,requests}],不含未定价请求,不做换算也不相减);tasks 独立聚合,不占费用分组配额。不返回模型密钥或原始请求 |
/hooks/github/:account/:endpoint |
POST | 按已登记入口验签和归档,不需要登录会话 |
项目电脑详情另外返回 observation:{status,checked_at,state}:available 表示本次取得电脑状态,unavailable 表示连接/协议读取失败,absent 表示 manager 没有该电脑记录,recovering 表示 manager 明确返回恢复栅栏,error 表示 manager 回应了其他错误;没有取得电脑状态时 state 为 null,原始错误正文不返回。environment.state 继续是持久生命周期记录,读取失败不会将它改写成停止;checked_at 是核验完成时间,不是心跳。 |
GET /api/tasks/:id/logs 默认按时间顺序返回最近 100 条日志。limit 为 1–100,before 向前读取更早页,after 向后读取新增页,两种游标不能同时提供。游标取响应 log_page.first_sequence 或 last_sequence,以日志追加序号为准,不依赖可能相同的时间戳;has_older 和 has_newer 表示当前读取方向是否还有下一页。客户端加载历史页后保留最早游标,轮询新增页时继续使用已读取的最大序号。每个请求都重新核对任务所属项目的权限,历史模型日志的私有字段在读取投影中过滤,新的 Pi 日志在保存前统一移除私有字段。
Webhook 对原始字节计算 HMAC-SHA256 并以恒定时间比较,验签后才解析和关联仓库。签名错误返回 401,未知入口返回 404,非法 JSON 返回 400,超过 2 MiB 返回 413。被拒投递(未知入口、验签失败、正文超限、非法 JSON、缺事件或投递号)只归档摘要 {rejected,bytes,truncated,sha256}(最多 256 字节)和四个识别用请求头 x-github-event,x-github-delivery,content-type,user-agent(合计最多 1 KiB),不保存正文;拒绝行最多 500 条、只保留 7 天,超额或超龄的行在每次拒绝时裁剪,pruned_total 记录累计裁剪数。被拒投递不写入正文,未认证请求的存储不会随请求体大小增长;合法投递的正文、响应记录与去重语义不变。请求头中的认证、签名和 Cookie 等内容脱敏。请求正文、响应记录和 (account_id,endpoint_id,delivery_id) 去重键在同一个 SQLite BEGIN IMMEDIATE 事务提交后才返回成功;写库失败返回 503 且回滚去重。重复投递保存独立档案,响应标记 duplicate:true。失败投递不消费去重键,重试可成功。空仓库配置、未启动或已禁用的仓库只归档,不生成任务。
项目列表接口 GET /api/repositories 与超级管理员的 GET /api/installations 在每个仓库上返回 running_tasks 和 queued_tasks。GET /api/installations 另返回 permission_missing:仍在安装列表中的仓库所缺权限(permission,required,current;机器人账号为 repository_role),未读到授予权限或不在安装列表时为 null;events_missing 是安装未订阅的必选事件名,未知或已移出安装时为 null,机器人账号为 [];events 列损坏无法解析、或能解析但不是事件数组时同样按未知处理(null);events_unreadable 是每行都有的布尔值,只在该行事件列无法读取时为 true,列表其余行照常返回。access_gaps 对照全部功能(不论是否开启)列出缺口,每项为 kind,name,required,current,features:kind 是 permission、event、role(机器人账号的仓库角色)或 account(机器人账号不能用只走 GitHub App 的发版本、经确认的 CI 改动和 Actions 失败分析);features 是因此不能用的功能,空数组表示只低于接入基线;授予权限或 App 安装事件尚未读取、或不在安装列表时为 null。基线之外,控制台检查状态展示(ci_checks)还需要 check_run 与 status 事件,经确认的 CI 改动(ci_changes)还需要 workflows: write,Actions 失败分析还需要 workflow_run 事件;review_threads(再次检视时关闭作者已修复的行内意见)需要 contents: write,缺少时检视照常发布,只是不关闭讨论串。actions_failures_enabled 是该仓库的 Actions 失败分析开关。POST /api/installations/permissions/check 返回重新读取后的完整仓库行。GET /api/accounts/{id}/permissions 的 app.feature_gaps 列出 App 定义在基线之外还缺、只有部分功能需要的项,不影响 ok。permissions_stale 表示权限/事件尚未完整读取,或已超过 10 分钟未重读。前者仅统计实际执行阶段,后者统计 queued;配置等待、环境等待与已结束任务不计入执行中。返回范围沿用项目管理员的仓库权限。列表开关调用 PATCH /api/repositories/{id}/policy,仅提交本次切换的 review_enabled 或 development_enabled,不更改项目总启用状态。
看板筛选格式为 [{"field":"object_type","value":"pr"},{"field":"text","value":"research"}],最多 20 条,条件之间为“且”。支持 repository_id(仓库 ID)、object_type(all/issue/pr,默认全部;Issue/PR 限制结果为该对象类型,单独筛发版本时保留但忽略对象类型条件)、category(review/development/release)、execution_status(running,queued,failed,completed,waiting,other)、bot_stage(unreviewed,reviewing,reviewed,developing,developed,attention,stopped)、text(对象编号可带 #,否则按标题或发版本号匹配)、include_closed(布尔,默认 false,只影响对象卡片)。group_by 为 bot_stage,repository,execution_status,category 或当前用户的单选字段 ID;自定义字段空值列 ID 为 unassigned。筛选、标准维度和折叠列可在浏览器先预览,点击“保存视图”后持久保存。每页最多 100 张工作卡片;work_count、column_counts 为筛选范围内全量计数,counts 为去重对象数,release_count 为筛选后的发版记录数。
任务列表、任务详情、项目最近任务和看板关联任务现在带 metrics:runtime_ms(累计已观测执行时长,不含排队/等待)、running、complete(历史或进程中断时可能不完整)、input_tokens,output_tokens,cached_input_tokens,cache_hit_rate、requests,usage_missing_requests,cache_missing_requests,unpriced_requests 和按币种分开的 costs。缓存是输入的子集,命中率用累计缓存 token 除以累计输入 token;缺少必要统计时返回 null,不用 0 冒充。complete:false 时显示的是已经观测到的部分。
GET /api/costs 的 tasks.days 为按任务 created_at 的本地日、仓库与工作类型聚合的行,tasks.summary 为日期范围内按工作类型的汇总(按工作类型目录顺序),tasks.undated 单独列出授权仓库内无可靠创建日期的历史任务,不进入日期范围内总数或每日分桶。所有任务都统计:workflow(沿用旧字段名)是工作类型 id,通用回复任务(包括原自定义工作流的任务)为 reply,其他是任务种类(如 review.issue、actions.failures、release.observe);name 是工作类型名称。每行还含 kind,count,runtime_ms,incomplete_tasks,running_tasks;整段累计执行耗时计入创建日,不跨日拆分,运行中含当前已观测执行区间,不含排队与等待。缺失计时或未观测到时长的不完整历史计时返回 null,已有部分则仅累计已观测值并标记不完整。仅覆盖控制面账本与任务,不采集外部执行端自行调用或项目内其他服务。
模型创建和带 version 的 PATCH 可提交 pricing:{currency,input_per_million?,output_per_million?,cache_per_million?}。手填单价按字段覆盖目录,每百万 token 为 0–1000000 的有限数;currency 为 USD 或 CNY。未填写字段继承同币种目录值,不能把 USD 目录值与 CNY 手填值混算。pricing:null 清除手填并恢复目录;没有足够价格的请求保持未定价。每次请求使用开始时的价格快照,历史成本不重算。模型响应的 pricing 是有效价格,pricing_override 是手填值,pricing_source 为 manual、mixed、catalog 或 null。
获取模型列表和测试模型的上游结果都在成功响应里返回:ok 表示上游是否成功,status 是上游的 HTTP 状态码(没有收到响应时为 null)。列表成功时返回 models_url,total,truncated,models,按名称排序,最多 200 个 id;测试成功时返回 chat_url、model(上游答复中的模型名)、reply(回复摘录,最多 200 个字符)、finish_reason 和 elapsed_ms。失败时返回 error(upstream_http_error、upstream_timeout、upstream_unreachable、upstream_redirect、upstream_response_invalid、upstream_response_too_large)和简短的 message:它只取自上游 JSON 的错误字段(error.message,或字符串形式的 error、message、detail、msg),重定向时是 Location,连接失败时是错误码;其他响应正文一律不回显。两类请求都在 15 秒后超时、不跟随重定向,结果中出现的 Key 先整体替换为 [REDACTED],再截断。模型 URL 只接受 http(s),不能带用户名、密码、查询串(?)或片段(#),否则保存、解析、获取列表和测试都返回 400 invalid_api_url。明文 http: 只允许本机:按 new URL() 解析后的主机名,localhost、[::1]、[::ffff:7f00:1] 与 127.0.0.0/8(含 127.1、十进制 2130706433、十六进制 0x7f000001 等写法)放行,其他主机返回 400 insecure_api_url(field: api_url),因为随后会把 Key 明文发出。这条规则之前保存的这类 URL 也不能获取列表或测试;任务运行、容器中转和角色运行在使用前再检查一次,命中时以 model_url_insecure/waiting_configuration 停下(登记在「模型服务或模型配置」一类,等人改地址,不自动重试),不发请求。测试请求的内容是一句不含项目数据的探测,只带 max_completion_tokens: 32,不带 max_tokens;任务中的模型请求仍只带一个输出上限字段,优先用显式角色额度,否则使用所选模型的最大输出;未匹配时为 8192。
模型能力与目录:
GET /api/models/catalog?q=&offset=0&limit=100返回目录状态catalog、规范化条目entries、匹配总数与下一页偏移,limit 为 1–200。状态含来源、最近成功快照时间、最近尝试时间、刷新错误和丢弃/跳过计数。POST /api/models/catalog/refresh {}仅超级管理员可用。控制面启动时及每 6 小时刷新固定的 models.dev 地址;失败保留旧快照。目录校验只接受文本对话模型、合法能力/价格和有限范围数值,非法条目单独丢弃。- 模型 POST/PATCH 可带
catalog:{mode:'auto'|'manual'|'disabled',ref?:'provider/model'}、capabilities:{context_window?,max_output_tokens?,reasoning?}。手动模式必须指定当前目录中的 ref;空能力对象恢复目录/默认。手填能力按字段优先,不改变模型身份 version。上下文为 1–32000000,最大输出为 1–16000000,reasoning 为布尔值。 - 模型响应含
capabilities(有效能力、来源和目录匹配状态)与capabilities_override。自动匹配先按 provider API/官方域名,再按去前缀、忽略大小写、点与横线等价的官方模型名;不唯一时显示候选,等待手动指定。中转使用官方 USD 参考价格,不作 CNY 换算。 - 从未成功下载或没有匹配时,能力沿用 128000 上下文、8192 最大输出、非推理模型。Pi 使用这些有效能力构建模型配置和上下文预留;显式角色输出额度保持优先。价格统计仍要求实际 token 计数;缺失缓存计数且缓存价不同时保持未知,不按零计价。
供应商连接的批量管理沿用模型范围和规范化请求地址,不引入跨项目凭据共享:
POST /api/models/provider:{repository_id?, api_url, api_key, model_names:[...]},一次创建供应商下的多个模型,至少一个、最多 200 个。相同范围已有该请求地址返回409 provider_already_exists。PATCH /api/models/:id/provider:以模型 ID 定位所在供应商;必须提供组内全部模型的versions:[{id,version}],可提交api_url、非空api_key和待添加的model_names。Key 空白保持原值。组成员、版本发生变化返回409 version_conflict;事务内更新全部连接并添加新模型,返回不含 Key 的models。- 同一路径提交
{versions, revoke_key:true}统一撤销组内 Key;不能同时提交 URL、新 Key 或新增模型。项目选择和已有计费单价不变。 POST /api/models/:id/upstream可带version、草稿api_url/api_key,在编辑权限下使用草稿或已保存 Key 获取列表,不保存这些值;空 Key 使用该模型已保存的 Key。旧的单模型 API 保持兼容。
任务运行、来源保留上限及详情投影的完整说明见 Task trace。文本交付按原始 UTF-8 正文 2 MiB 限制,JSON 转义后的包裹体另有 16 MiB 上限;超限保留路径、版本、读取/脱敏状态及哈希,仅省略正文。
项目记忆(沿用项目权限):GET/POST /api/repositories/:repo/memories 查询/建立条目,GET 支持 query、module、source、kind、status、baseline、after、limit(1–50)、include_superseded=1;GET/PATCH .../memories/:id 读取指定 revision 或按 expected_revision 更新,支持 supersedes 同项目 ID 数组;GET .../:id/versions 查询修订与来源关系;POST .../:id/document 从真实 GitHub PR 和文件验证仓库文档关联。具体契约见 Project memory。
项目角色:GET /api/repositories/:repo/role-board 只读返回各角色配置元数据、并发限额、正在执行运行(含主控委派标记 delegated_active)、可唯一归属的排队任务与 role_capacity 等待队列及 can_write_tasks;GET/PUT /api/repositories/:repo/roles 查询/配置 RoleDefinitionV2(新任务默认使用 Manager;旧 enabled 和 controller.entries 布尔值仅兼容接收,不再关闭协调,当前配置返回 true;历史快照保留原值。PUT 必须带 expected_revision,冲突返回 409;校验错误的响应带 field,指出出错的配置字段),GET 还返回 Harness 能力矩阵、逐项权限定义 permission_items、共用系统提示词 system_prompt、可编辑角色模板 role_templates、必需角色列表 required_roles、环境/预算/输出 schema 目录、可引用模型、技能来源和按工作类型的解析预览;角色的 permissions 逐项配置资源的 write/read/none 或动作的 allow/deny,PUT 的 deleted_roles 显式删除角色,Manager、Coordinator 和 QA 不允许删除,?revision=N 返回历史配置;POST /api/repositories/:repo/roles/resolve 以 role, workflow, expected_revision 只读预览运行快照,不建任务也不落库;GET /api/tasks/:id/roles 查询实例、委派、各次角色运行及其快照;POST /api/tasks/:id/roles/apply 以 role, expected_revision 让运行中的角色在下一个安全检查点结束,再带新 revision 续接同一实例。沿用项目权限,正文会话不返回。POST /api/tasks/:id/merge 以 expected_sha、merge_method 显式授权合入已验收的 Bot PR,校验精确 head、策略与检查,不绕过 GitHub 分支规则。详见 Role-Pool。每次角色运行还带 RoleRun 事实:lease_scope、lease_epoch、resume_from_run_id、protocol_recovery、run_context(不含密钥)和 admission,见 RoleRun 协议。
并行集成与合入:POST /api/tasks/:id/merge 可返回 merged:false 和 integrating/queued 状态,显式授权由任务引擎持久化续接;只有 merged:true 和 repository_evolved 表示确认合入。GET 同路径查询请求状态,DELETE 撤回并移除待处理队列项(已合入不撤销)。新候选需要重新验证和独立 QA。详见 Parallel integration。
Task coordination: GET /api/tasks/:id/coordination reads explicit requests, notices and feedback in project scope. POST /api/tasks/:id/coordination/:request_id/retry retries a failed or human-wait request; task write authorization applies. See task coordination for role tools and version/QA boundaries.
本地聊天记录:GET /api/channels/chats?connector_id=... 列出管理员可见的本地群/私信及同步诊断;GET /api/channels/chats/:id/messages 仅查询本地密封账本,支持 message_id,sender_id,reply_to,thread_id,from,to,keyword,cursor,limit,时间为毫秒,limit 1–100,返回 messages,next_cursor,has_more,sync_state,coverage,gaps,retention。cursor 只可用于同一查询与授权范围;搜索或未命中均不调用飞书。GET .../:id/conversation?offset=0 按整个会话的当前读取权限分页返回历史回合、回答、阶段消息及同账本用量,不按回合来源或授权版本隐藏历史;不返回原始模型日志。群聊助手和私信的回合带 messages(本轮阶段消息,按顺序);群聊助手会话另有 can_manage,运行中的回合有 can_stop。POST .../:id/service-turns/:turn/stop(空请求体)停止一个运行中的群聊助手回答,只限能管理该群绑定的人,返回 {id,state},见消息渠道。私信拥有者可查询自己的当前授权记录,群记录仍要求群聊助手绑定的维护人(配置人、对全部范围有配置权限者)、旧群员工维护人或平台管理员,普通项目权限不会开放其他群或私信。POST .../:id/sync 的 {full?:boolean} 显式建立同步请求,未完成作业保留已有游标。GET/PUT/DELETE .../:id/retention 仍要求 platform.manage;PUT {days:null|1..3650,expected_revision},DELETE {before:<毫秒时间>,expected_revision},版本来自 chats 列表,清理删除原文及派生摘要并保留覆盖边界。限制和平台权限见消息渠道。
飞书控制台读取会话采用统一入口授权:超级管理员可查看所有群聊与私聊,普通用户仍需取得整个会话的读取资格。conversation、timeline、messages 和 turns/:turn 不再按单个回合的旧来源或授权版本隐藏内容;私聊的历史管理会话一并读取。响应中的 can_continue 仅在本人的私聊中为真,管理员查看他人私聊不产生该用户的操作身份;关联任务的项目详情权限保持独立。
会话定时任务(#330):GET /api/channels/chats/:id/schedules 返回 {can_manage,schedules};POST 同一路径创建,接受 {name,prompt,timezone,cron 或 interval_minutes,enabled}。PATCH /api/channels/schedules/:id 带 expected_revision 修改上述字段,或只传 enabled 暂停/恢复;DELETE 带 expected_revision 删除;POST /api/channels/schedules/:id/run 立即运行一次;POST /api/channels/schedules/preview 接受时区与 cron 或 interval_minutes,返回接下来的触发时间。私聊由绑定主人管理,群由能管理群聊助手绑定的人管理;平台管理员可以查看和停用。原 /api/channels/destinations 与 /api/channels/chats/:id/destinations 已移除:项目的 list_schedule_destinations 直接列出可选会话(chat:<会话 id>),保存计划或订阅时自动登记。旧的群范围接口 /api/channels/connectors/:id/groups 和 PUT /api/channels/chats/:id/personal-role 已移除。
群聊助手绑定(#312):GET /api/channels/service-bindings 返回本人可见的绑定(状态、暂停原因、可达与暂停的仓库、can_manage、can_view)、本人已绑定飞书且在本地有可信发言的候选群、可用于群聊的服务角色(recommended 标出仓库问答助手)、三个权限档位 levels(每项 id,permissions)、统一权限目录 permission_items、本人有配置权限的仓库和组织,以及本人维护的旧群员工(legacy_employees,含未结束任务数);每条绑定带 level(read|comment|dispatch|custom)和 permissions。PUT /api/channels/chats/:id/service-binding 接受 {service_role_id,scope,participation,level,permissions,enabled,expected_revision},level 为 read|comment|dispatch,permissions 是高级逐项设置(只接受 permission_items 中的项和模式,在当前绑定的设置上修改),两者只能给一个(channel_service_level_conflict),都不给时保持原档位、新绑定为 read;无效值返回 channel_service_level_invalid 或 channel_service_permission_invalid。项目群助手角色只能用于范围只有其所属项目的群(400 service_role_project_scope,detail 给出所属项目和范围外的项目);角色的模型必须对范围内每个项目都可用(409 channel_service_model_unavailable,detail.projects 列出缺少授权的项目)。列表里的 service_roles 包括全局模板和本人可配置项目的项目角色(带 project、model),每条绑定另有 model_gaps(模型没有授权的范围内项目)。scope 为 {kind:'repositories',repositories:[项目 id…]} 或 {kind:'organization',organization:<租户 id>},participation 为 mentions|questions|all;启用要求当前个人飞书绑定、在群中(在线核验成员)以及对每个仓库或整个组织的 config.write,管理助手不能绑定(service_role_not_bindable)。停用只需 {enabled:false,expected_revision},由配置人、超级管理员或对全部范围有配置权限者执行。版本冲突返回 channel_revision_conflict。不接受客户端给定 principal、配置人或成员证明。旧接口 GET /api/channels/employees 继续返回私信会话和旧群员工;PUT /api/channels/chats/:id/employee 只能停用旧群员工({project_id,enabled:false,expected_revision}),启用返回 410 channel_employee_retired。详见消息渠道。
任务浏览器证据
任务在声明了 input.browser.origins 后,可用独立的真实浏览器访问这些源,步骤与截图见 任务浏览器与执行证据。
GET /api/tasks/:id/browser-evidence:步骤列表(JSON,不含像素和口令)。GET /api/tasks/:id/browser-evidence/step-N.png:对应截图。仅能查看本人权限范围内的任务,且只提供步骤清单中出现过的 PNG。