Files
streamline/docs/openapi.md
T
2026-11-16 17:26:44 -08:00

236 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 开放平台 v1(API Key 接入)
面向外部服务端程序(Meego、Jira、自有平台)的 HTTP API。一把 `sk-sl-…` Key 代表一个接入方:
它建出来的任务记归属(`createdViaKeyId`),查单 / 执行 / Webhook 都按这个归属设闸。
另外两条路不要混:浏览器面板走 SSO;命令行 / Skill(`openapi-skill/`)走 `/api/cli/v1/*` +
本人 SSO 会话,以「本人」身份操作,不算接入方。
- **Host**:内网直达 `https://streamline-internal-api.bytedance.net`。公网面板域名前面的网关
只放行 GET,外部 POST 会被拦(405)。
- **鉴权**:`Authorization: Bearer sk-sl-…`。Key 在面板头像菜单「开放平台 API」申请,明文只在
生成时返回一次;自助申请 → 管理员审批 → 申请人领取。
- **面向接入方的完整文档**是飞书《Streamline 开放平台接入》(URL 见
`control-web/src/components/OpenApiUsageDocs.tsx` 的 `OPENAPI_GUIDE_URL`),面板的「开放平台 API」
页也渲染同一份要点。本文只记实现边界和容易踩的契约。
## 端点
| 方法 / 路径 | 作用 |
| --- | --- |
| `POST /api/openapi/v1/meego-import` | 按 Meego 链接导入一条 bug(标题/描述/附件/经办人都来自工单) |
| `POST /api/openapi/v1/tasks` | 通用建任务(不挂 Meego),`externalId` 按 Key 作用域去重 |
| `POST /api/openapi/v1/features` | 用一句话建一条「需求」(feature),评估 → 待确认 → 确认执行,见「一句话需求」 |
| `GET /api/openapi/v1/features?externalId=…&limit=…` / `GET /api/openapi/v1/features/{featureId}` | 列 / 按自己的单号查 / 单条需求视图 |
| `POST /api/openapi/v1/features/{featureId}/execute` | 把已起草(`pending_confirmation`)的需求推入实现队列 |
| `POST /api/openapi/v1/tasks/{taskId}/execute` | 把已起草(`pending_confirmation`)的任务推入修复队列 |
| `GET /api/openapi/v1/tasks?externalId=…&limit=…` | 列 / 按自己的单号查这条 Key 建的任务 |
| `GET /api/openapi/v1/tasks/{taskId}` | 单条任务视图(含产品配置、`baseRef`、打回原因 `infoRequired`、待补项 `needsInput`) |
| `GET /api/openapi/v1/product-profiles` | 可用的产品(工程)配置选项 + 默认值 |
| `POST /api/openapi/v1/uploads/image` | 上传建单要用的一张图片,返回公开 URL |
| `POST /api/openapi/v1/webhooks` 等 | 状态推送订阅,见 `routes_openapi_webhooks.ts` / 面板文档 |
同一个前缀下还有接入方机器人(`/lark-bots`)与 Key 自助接口;使用情况在管理台「开放平台 → 使用情况」,
口径见 `openapi_usage_core.ts`。
## 产品(工程)配置:`productProfileId`
取值和面板新建对话框里「产品配置」下拉一致——线上目前是 `tiktok`(默认)、`whee`、`lemon8`、`notes`
(以接口返回为准)。由管理员在 Management → 产品与分支 维护,所以**不要把这些 id 硬编码进接入方**:先查
```sh
curl https://streamline-internal-api.bytedance.net/api/openapi/v1/product-profiles \
-H "Authorization: Bearer sk-sl-…"
# → { "defaultProfileId": "tiktok", "revision": 4,
# "profiles": [{ "id": "tiktok", "name": "TikTok",
# "platforms": {
# "ios": { "repoPath": "ugc/TikTok", "baseBranch": "develop", "targetBranch": "develop" },
# "android": { "repoPath": "ugc-android/TikTok", "baseBranch": "develop", "targetBranch": "develop" } } }, …] }
```
这个响应和面板的 `GET /api/product-profiles` 同源、同过滤(只含启用中的产品),差别只在形状:多了
`defaultProfileId`,`platforms` 用注册表里的 `repoPath`(面板显示成 `id (repo path)`)而不是 `repoKey`,
也没有 `enabled`(既然只返回启用中的)。
- `/meego-import`、`/tasks`、`/features` 三个建单接口都接受 `productProfileId`。传了就把该产品的
仓库/基线快照写进任务(`tasks.product_profile` / `features.product_profile`),非默认产品同时自动
填 `baseRef`(自定义分支),执行侧据此检出分支;显式传 `tiktok` 也会落快照,但 `baseRef` 仍是空
(走默认主干)。
- 不传 = 不落产品快照,执行走节点/控制面的主干默认。生产默认配置下(tiktok 的基线是 `develop`、
节点 `BASE_BRANCH` 也是 `develop`)这与显式选 tiktok 等价;管理员改过 tiktok 的基线之后两者不再等价。
- 只列 / 只接受启用中的产品。停用、未知、或该产品不支持任务的平台都回 400,**不会静默退回默认产品**。
- 去重命中(`externalId` / `meegoId`)时仍然返回已有任务,不改它已有的配置(`baseRef` 同理)。
## 检出分支:`baseRef`
两个建单接口都接受可选的 `baseRef`,即面板上的「自定义分支」:评估在这条远端分支上读代码,修复分支
从它切出,MR 也回到它。典型是特性分支上验收出来的问题(例:`"baseRef": "notes/feature/restaurant-radar"`)。
- 优先级:显式 `baseRef` > 产品配置的 `baseBranch` > 主干。
- 只认分支名(`shared/src/product_profiles.ts::validProductBranch`);`origin/` 前缀会被去掉;SHA、refspec、
含 `..` 的值回 400。分支名要和远端**逐字一致**,节点 fetch 不到时评估会失败,不会换别的分支。
- meego-import 不读 Meego 上的分支字段:各空间字段不统一,接入方手里本来就有分支名,传进来最可靠。
- 任务视图回显实际生效的 `baseRef`(`null` = 主干)。
## 任务视图:打回原因与待补项
`GET /tasks[/:id]` 除状态外还给两样东西,让接入方不用打开面板就知道该做什么
(实现与单测:`openapi_task_view.ts` / `control-server/test/openapi_task_view.test.ts`):
- `infoRequired`:只在 `status = info_required` 时非 null。
- `{ "kind": "platform_error", "message": … }`:评估环节平台侧出错(节点崩溃、超时、额度、鉴权,
识别规则见 `eval_failure.ts`)。与工单内容无关,补信息没用;**不回原始报错**(节点路径、git 输出)。
- `{ "kind": "needs_info", "reason": … }`:评估器对工单下的「信息不足」结论,`reason` 是它的原话。
- `needsInput`:TestSpec 里评估器确定不了的项(`NEEDS_INPUT` 哨兵,每条一句话,不含面板用的候选项)。
`pending_confirmation` 和 `needs_info` 时给出;`platform_error` 时为空,因为那时的 TestSpec 可能是上一轮留下的。
- `/execute` 对 `info_required` 回 409 时,文案同样区分这两种情况。
## 附件:只支持图片
非 Meego 的通用建单没有工单附件可读,所以走「先上传拿 URL,再把链接写进 description」两步——
和面板把图片拖进描述框是同一条链路,卫星侧不需要为开放平台单开一条路。
```sh
curl -X POST https://streamline-internal-api.bytedance.net/api/openapi/v1/uploads/image \
-H "Authorization: Bearer sk-sl-…" \
-F "file=@screenshot.png"
# → { "uuid": "…", "ext": "png", "url": "https://voffline.byted.org/download/tos/schedule/streamline/img_upload/<uuid>.png",
# "name": "screenshot.png", "markdown": "![screenshot.png](https://…)" }
```
然后建单时把 `markdown` 放进 **`description`**:
```sh
curl -X POST https://streamline-internal-api.bytedance.net/api/openapi/v1/tasks \
-H "Authorization: Bearer sk-sl-…" -H "Content-Type: application/json" \
-d '{"title": "…", "description": "现象如下:\n\n![screenshot.png](https://voffline.byted.org/…)", "platform": "android"}'
```
契约与边界:
- **只有 `description` 会被物化**:工作区只把 description 写进 `OriginalIntro.md` 并下载其中的图片;
放进 `reproSteps` 的 markdown 不会被下载(它只进评估 prompt),Agent 只会看到一个打不开的链接。
- 只接受图片:`png / jpeg / gif / webp / bmp / svg / heic / avif`,≤ 12MB;空文件 400、非图片 415、
超过 12MB 413;TOS 未配置 503、写入失败 502。执行侧只会把工作区 `images/` 下的图片交给 Agent,
日志 / 文本 / 视频请直接写进 description 或 reproSteps 正文。
- 上传结果是**公开、永久的 voffline URL**:拿到链接任何人都能读,敏感截图不要传;对象名里不带 Key
归属,也还没有 per-key 配额(与证据上传共享 TOS 的 QPS / 并发闸)。
- 卫星 bootstrap 工作区时,`satellite/src/workspace.ts::materializeDescriptionImages` 只认
`shared/src/protocol.ts` 里的 `TOS_IMAGE_BASE` 前缀:把它下载到 `<workspace>/images/<file>`,并把
description 里的绝对 URL 改写成相对 `images/<file>`。评估器的 prompt 随后给出这些文件的本机绝对路径
(`shared/src/workspace_images.ts`),执行期 prompt 则指向 `{{workspaceDir}}/images/`(`shared/src/run_prompt.ts`)。
**会被保证物化的只有通过这个接口上传的 URL**:手写任意外部图片 URL 不被保证——bug 工作区还留着一条
老的「抓正文里 http(s) 图片」兜底(`satellite/src/workspace.ts::extractImageUrls`),feature 工作区没有,别依赖。
- 上传发生在建单之前(那时还没有任务可以挂附件),两步顺序不能反;同一个 URL 可以重复用在多条任务里。
- **meego-import** 的附件来自工单本身:描述富文本里**直接粘贴的图片**和「多个附件」字段经控制面代理下载进
`images/`(`satellite/src/attachments.ts`),这条是保证的。描述正文里的**裸链接**(`参考截图: https://…png`)
不是图片语法,不会被下载;`![](url)` 形式的外部链接只在工单没有任何 Meego 原生图片 / 附件时才走上面那条
老兜底。要保证 Agent 看到截图:粘成 Meego 原生图片,或先经 `/uploads/image` 上传再以 `![](url)` 写进描述。
链接到云文档 / 外部报告里的内容,无人值守的评估读不到。
- 复现步骤写在描述正文里即可,评估器会读;不要求回填 Meego 的独立「复现步骤」字段(填了也会读)。
- 上传本身没有任务归属,只能在鉴权后调用。
## 一句话需求(`/features`):评估完再确认执行
`POST /api/openapi/v1/features` 用一句 `description` 建一条**需求**(feature)任务,走和面板
「新建需求」同一条管线:评估器先起草实现方案(`executionPlan`)→ 状态 `pending_confirmation`(待确认)
→ 确认执行后进实现队列。它和 `/tasks`(bug)是两张表、两套状态机,`taskId` 与 `featureId` 别混用。
```sh
curl -X POST https://streamline-internal-api.bytedance.net/api/openapi/v1/features \
-H "Authorization: Bearer sk-sl-…" -H "Content-Type: application/json" \
-d '{"description": "把收藏页的排序改成按最近收藏,空列表时给一句空态文案", "platform": "android", "externalId": "TICKET-123"}'
# → { "featureId": "…", "status": "created",
# "panelUrl": "https://streamline.bytedance.net/feature?id=…" }
```
入参(JSON,`description`、`platform` 必填):
| 字段 | 说明 |
| --- | --- |
| `description` | 必填,需求正文。一句话即可,支持 markdown 和图片链接:图片先走 `POST /api/openapi/v1/uploads/image` 拿公开 URL,再把 markdown 图片链接写进 description(见上一节)。`title` 不传时取 description 里**第一条非空行**作为标题(超过 80 字截断),不是报错。 |
| `title` | 选填,显式标题。 |
| `platform` | **必填**,`android` / `ios`。和 `/tasks` 不同:需求没有现象描述可供分类,不传只能落到 `FEATURE_DEFAULT_PLATFORM`,接入方事后才发现实现在错的端上,所以缺省直接 400。 |
| `productProfileId` | 选填,语义与 `POST /api/openapi/v1/tasks` 完全一致:取值先查 `GET /api/openapi/v1/product-profiles`;不传 = 不落快照、走主干默认;非默认产品会自动把该产品配置的基线填成 `baseRef`。 |
| `baseRef` | 选填,自定义 Git 基线分支(只认分支名,不认 SHA / refspec,非法回 400)。显式传了优先;不传时非默认产品会用该产品配置的基线自动填(和面板选产品后回填的行为一致)。 |
| `watchers` | 选填,额外通知人 / 群,形式同其它 v1 接口:邮箱前缀 / 完整邮箱 / `oc_` 群 / `ou_` 个人。**Key 的申请人自动加入**,不用传(和 bug 不同,见「归属与安全 · 建单人」)。 |
| `externalId` | 选填,调用方自己的需求 / 工单 ID,与这把 Key 组合去重。命中重复时返回已有任务(`status:"exists"`),不重开、不改已有配置。 |
| `larkReply` | 选填,`{ "botId": "lkb_…", "messageId": "om_…" }`,和 bug 的两个建单接口同一套校验与语义:状态卡片以接入方登记的机器人身份回复进话题(`openplatform_lark_bots.ts`)。 |
不收 `lang`:可读性报告默认双语(`readable_translate.ts`),生成语言用默认值,和 bug 的两个建单接口一致。
旧调用方传了也会被忽略。
`description` 里贴 Meego 工单链接(形如 `https://…/<project>/<work_item_type>/detail/<id>`)会被平台
按面板新建需求的同一条逻辑展开成「实际内容」块(标题 / 描述 / 复现步骤 + 图片)。所以接入方也可以只贴
一句诉求 + 需求单链接,不必自己把工单正文抄一遍。
响应 `{ featureId, status: "created" | "exists", panelUrl }`,带了 `larkReply` 时多一个 `larkReplyAttached`。
错误:401 未带有效 Key;400 `platform` 缺失或非法、产品不可用或该产品不支持这个平台(**不会**静默退回默认产品)、
`description` 为空、`watchers` 无法解析、`larkReply` 形状或归属不对(错误码同 bug)。
查单:
- `GET /api/openapi/v1/features?externalId=…&limit=…` → `{ features: [视图] }`。`limit` 1–100,默认 20;
`externalId` 命中时只回那一条。
- `GET /api/openapi/v1/features/{featureId}` → 单条视图;非本 Key 建的单 403,不存在 404。
- 视图字段:`featureId, externalId, title, platform, status, statusLabel, productProfileId,
productProfileName, baseRef, infoRequired, needsInput, createdAt, statusChangedAt, finishedAt, mrUrl, panelUrl`。
时间字段都是毫秒 epoch;`finishedAt` / `statusChangedAt` 在没有对应时刻时为 `null`。
`infoRequired` / `needsInput` 和任务视图同名同口径(同一个 `infoRequiredDetail` / `planNeedsInput`),见上文「任务视图」。
- `status` 是需求自己的状态机:`initializing`(评估中)、`info_required`(待补充)、
`pending_confirmation`(待确认)、`awaiting_implementation`(待实现)、`implementing`(实现中)、
`manual_review`(人工复核)、`completed`(已完成)、`implementation_failed`(实现失败)、
`archived`(已归档)/ `cancelled`(已取消)。
确认执行:
```sh
curl -X POST https://streamline-internal-api.bytedance.net/api/openapi/v1/features/{featureId}/execute \
-H "Authorization: Bearer sk-sl-…"
# → { "featureId": "…", "status": "queued", "featureStatus": "awaiting_implementation", "panelUrl": "…" }
```
- 和 bug 的 `/tasks/{taskId}/execute` 一样是**两段式**:建单后要等评估器起草完(通常数分钟),
期间调用返回 409;只有 `pending_confirmation` 能执行。先查 `GET …/{featureId}` 看 `status` 再决定:
`initializing` 稍后重试、`info_required` 按 `infoRequired.kind` 区分平台出错(等平台重评)和信息不足(补信息)、`awaiting_implementation` / `implementing`
不用再调、终态不可再入队(409 响应都带 `featureStatus`);计划为空 400。
- 归属闸和 bug 一致:只能执行本 Key 建的需求(否则 403,响应不带状态;不存在 404),查询别人的单也是 403。
- 状态推送:`larkReply` 和 bug 一样生效(`notify.ts::notifyFeatureStatusChange` 同一张卡片再回复进话题);
**按 Key 的 Webhook 订阅目前只覆盖 bug**,需求单要对账请轮询 `GET /api/openapi/v1/features/{featureId}`。
与 bug 建单的边界(不是同一套东西):
- 入参:`/tasks` 要求 `title` 与 `description` 必填、`platform` 可自动判断,可带 `reproSteps`;`/features`
要求 `description` 与 `platform`,`title` 可从首行推导,也只认上表字段(`reproSteps` 这类 bug 侧入参不要带)。
两者共用 `productProfileId` / `baseRef` / `watchers` / `externalId` / `larkReply` 的语义与校验。
- 状态机:bug 是 `initializing` → `pending_confirmation` → `awaiting_fix` → `fixing` → `manual_review`
→ `fix_succeeded` / `fix_failed`(另有 `unreproducible`、`archived`、`cancelled`);需求是
`initializing` → `pending_confirmation` → `awaiting_implementation` → `implementing` → `manual_review`
→ `completed` / `implementation_failed`(另有 `info_required`、`archived`、`cancelled`)。
`status` 的取值不要按 bug 的枚举猜。
- 执行与交付:各用各的 execute 接口;需求完成后产物是 MR(`mrUrl`),报告是 `ImplReport.md`(bug 是 `FixReport.md`)。
- 归属与去重:两者都按 Key 设闸,去重都按「Key + `externalId`」;跨接口不互相去重。
## 归属与安全
- Key 只能看到、执行自己建的任务:别人的任务 403,且响应里不带状态。校验顺序是「先归属再状态」,
避免用 409 的文案泄露别人任务的生命周期。
- `watchers` / `larkReply` 同样有归属闸:只在自有任务上补挂,绝不把通知面暴露给别人。
- 建单人:接口不收「提交人」,三个建单接口(`/meego-import`、`/tasks`、`/features`)把这把 Key 的**申请人**
记成任务的 `creatorEmail`。bug 的两个接口不把申请人加进 watchers(一把 Key 批量建单,不该每单都给申请人发卡);
`/features` 会加(需求要人看方案、确认执行、复核 MR,申请人就是负责人)。凡是按建单人取的
个人凭据都随之用申请人的:读 Figma 用申请人在面板绑的 Figma Token、读飞书文档用申请人的飞书授权
(见 `docs/external-links.md`);没有 Meego 经办人时 MR 也优先挂申请人名下。2026-11 之前建的单
`creatorEmail` 为空,不受影响。持有 Key 的服务因此能以申请人的身份让 agent 读设计稿 / 文档,申请 Key 时要知道这一点。
- 使用痕迹(路由、状态码、归属的 Key / 人、客户端标识)在管理台可查,不含对话内容。
注意「使用情况」的**建单数**目前只统计 bug:`/features` 建的需求只出现在调用记录里
(按路由/状态码可查),建单/推进率要按需求对账就轮询 `GET /api/openapi/v1/features`。
(顺带:按 Key 的 Webhook 订阅同样只覆盖 bug;`larkReply` 两条线都覆盖。)
## 测试
- 纯逻辑(图片校验 / TOS 上传 / markdown、产品选项视图、任务视图):`bun test control-server/test/image_uploads.test.ts control-server/test/product_profiles.test.ts control-server/test/openapi_task_view.test.ts`(后者 import 时需要一个 `DATABASE_URL`,给个连不上的假串即可,不会真连)
- 一句话需求的执行闸 / 视图 / 409 文案(纯逻辑,不要库):`bun test control-server/test/openapi_feature_gate.test.ts`
- 端到端(需要本地 PG,建议指向一次性库;测试结束会把产品配置恢复原样。外部 HTTP 全部打桩):
`TEST_DATABASE_URL=postgres://…@127.0.0.1:55438/… bun test control-server/test/openapi_product_attachments.integration.test.ts`