Files
2026-11-16 17:26:44 -08:00

20 KiB
Raw Permalink Blame History

开放平台 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": "![screenshot.png](https://…)" }

然后建单时把 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![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 别混用。

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(已取消)。

确认执行:

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