# 开放平台 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/.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` 前缀:把它下载到 `/images/`,并把 description 里的绝对 URL 改写成相对 `images/`。评估器的 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://…///detail/`)会被平台 按面板新建需求的同一条逻辑展开成「实际内容」块(标题 / 描述 / 复现步骤 + 图片)。所以接入方也可以只贴 一句诉求 + 需求单链接,不必自己把工单正文抄一遍。 响应 `{ 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`