20 KiB
开放平台 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 硬编码进接入方:先查
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」两步—— 和面板把图片拖进描述框是同一条链路,卫星侧不需要为开放平台单开一条路。
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": "" }
然后建单时把 markdown 放进 description:
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", "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) 不是图片语法,不会被下载;形式的外部链接只在工单没有任何 Meego 原生图片 / 附件时才走上面那条 老兜底。要保证 Agent 看到截图:粘成 Meego 原生图片,或先经/uploads/image上传再以写进描述。 链接到云文档 / 外部报告里的内容,无人值守的评估读不到。 - 复现步骤写在描述正文里即可,评估器会读;不要求回填 Meego 的独立「复现步骤」字段(填了也会读)。
- 上传本身没有任务归属,只能在鉴权后调用。
一句话需求(/features):评估完再确认执行
POST /api/openapi/v1/features 用一句 description 建一条需求(feature)任务,走和面板
「新建需求」同一条管线:评估器先起草实现方案(executionPlan)→ 状态 pending_confirmation(待确认)
→ 确认执行后进实现队列。它和 /tasks(bug)是两张表、两套状态机,taskId 与 featureId 别混用。
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: [视图] }。limit1–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(已取消)。
确认执行:
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