Initial import of streamline

This commit is contained in:
2026-11-16 17:26:44 -08:00
commit 8e4aec1855
1221 changed files with 274256 additions and 0 deletions
+46
View File
@@ -0,0 +1,46 @@
# Eddy 兼容知识 API(/api/eddy)
Eddy 是本地 Catalyst 原型运行时(源码仓 `tiktok/streamline_playground`)。它把"同一基线 App 上用户撞过的坑与修法"
共享给所有同基线用户,Streamline 是这条链的**审核、复验、发布与生产化**所在地,不是 Eddy 的控制面。
契约与 JSON 形状以 `streamline_playground/API.md` 为准;`streamline_playground/stub/control_plane.py` 是 CLI 端到端测试用的
参考实现(sqlite),改路由时两边同步。
## 组成
| 位置 | 内容 |
|---|---|
| `drizzle/0026_eddy_compat.sql` + `0027_eddy_releases.sql` / `control-server/src/schema.ts` | `eddy_baselines`(身份,客户端层 first-seen 登记,不可变)`eddy_releases`(官方发布:下载地址,只有管理员 / 发布流水线能写,可更新可下架;0028 加 `source` 列 = 可选的源码快照包 `{url,sha256,bytes,commit,repo}`,产品仓在 App 构建 commit 的文本文件,Eddy 侧 `baseline add` 一起下载、Agent 据此把交接里的源码位置标 verified-symbol)`eddy_problems` `eddy_observations` `eddy_installs` `eddy_fixes` `eddy_advisories` `eddy_handoffs`(只用字符串键关联,不加外键:观察可能先于基线登记到达,发布可能早于任何 seen) |
| `control-server/src/eddy_rules.ts` | 纯规则:signature 校验/别名匹配、候选 → verifying → verified → published → disabled/retired 状态机、自动停用(≥2 台机器回归,或 ≥5 样本中过半仍复现)、候选校验。`bun test control-server/test/eddy_rules.test.ts` |
| `control-server/src/eddy_db.ts` | 数据访问;`compatIndex()` 装配客户端读的索引;`ingestTelemetry()` 顺带跑自动停用;`searchKb()` 多源检索(advisory / semantic 层 kb_claims / handoffs / features) |
| `control-server/src/routes_eddy.ts` | 三个信任层:客户端层(内网任意 Mac;`X-Eddy-User` 只做归因,有 SSO cookie 时以 SSO 为准;`baselines/seen` 只收身份,请求里的 `artifact` 一律丢弃)、管理员层(SSO + admin,发布/停用/合并/派发复验;`/admin/releases/*` 和 `/admin/locks/*` 另外接受 `Authorization: Bearer $EDDY_RELEASE_TOKEN`,给发布流水线用)、卫星回调(cluster secret) |
| `satellite/src/eddy_verify.ts` + `/sat/eddy/verify` | 复验 runner:用节点自己的 Eddy CLI `compat try` 装候选 → 观察事件流 → `EDDY_DISABLE_COMPAT=1` 对照 → 回执 POST 回控制面。节点通过 `EDDY_HOME` 上报 `eddy-runtime` 能力 |
| `control-web` Management › Eddy 兼容知识 | 审核台:基线(官方发布 / 仅观测到;填下载地址发布、更新、下架)、待审候选(卫星复验 / 发布 / 拒绝)、已发布(停用 / 重新发布)、问题(状态、合并 alias)、最近观察 |
| `control-server/src/eddy_crashes.ts` | Eddy 崩溃报告(`POST /crashes`,devicesim / eddy / app 三类):存进 `eddy_observations` + `eddy_knowledge_assets`,按问题归并;管理员 `/admin/crashes*` 读取。见 [eddy/crash-reports.md](eddy/crash-reports.md) |
## 状态与规则
- 候选提交后 `candidate`;`POST /compat/candidates/:id/verify` 派发到在线且有 `eddy-runtime` 的 iOS 卫星 → `verifying`;回执 `passed=true` 时 launch-config 直接 `published`,frida-guard / native-dylib 变 `verified` 等维护者发布;`passed=false` → `rejected`。
- 遥测里每条 `install/try` 记录回流 `confirmations`;`published` 修法满足自动停用规则时变 `disabled`,下一次 `compat sync` 即从用户端 active 集合消失。
- 问题按 `(signature, baseline)` 存;维护者可把一个 signature 合并进另一个(`aliases`),客户端 lookup 同时匹配别名。
- 基线分「仅观测到」(有人 `./eddy up` 过,身份行由客户端登记)和「官方发布」(`eddy_releases` 有 published 记录)。`frida-guard` / `native-dylib` 候选只能提交 / 复验 / 发布到官方基线——卫星要装同一份 App 才能复验,而且发布会把代码放进别人的进程;仅观测到的基线(本地 import-app 的构建)只能挂 advisory / launch-config。
## 部署
1. 应用 `drizzle/0026_eddy_compat.sql`、`0027_eddy_releases.sql`、`0028_eddy_release_source.sql`(走评审过的迁移流程,不用 `drizzle-kit push` 碰生产库)。
1. 可选环境变量 `EDDY_RELEASE_TOKEN`:发布流水线(`eddy baseline publish`)用它调 `/api/eddy/admin/releases/*`,不设则只有 SSO 管理员能在审核台发布基线;Eddy 的定时自动发布还用它登记全局租约 `/api/eddy/admin/locks/*`(见 [eddy/locks.md](eddy/locks.md))。
2. 控制面可选环境变量 `CONTROL_PLANE_PUBLIC_URL`:卫星回调地址的 origin;未设时取请求的 origin。
3. 要启用卫星复验:在一台 iOS 卫星上安装 Eddy 便携包并设置 `EDDY_HOME=<包目录>`(或放在 `~/Documents/Eddy/current`),
重启卫星后 Health 面板会显示「Eddy 复验」能力。复验时该卫星会启动/停止基线 App,与正在跑的 feature/bug 任务共享
同一台机器,建议用专门的复验节点。
4. `POST /api/eddy/handoffs`(Eddy `task ship`)会调用 `createFeature` 建一个 iOS feature task,描述里带交接包下载链接
`/api/eddy/handoffs/:id/zip`;zip 以 base64 存在 `eddy_handoffs.zip`(≤ 20 MB),迁到 TOS 是后续优化,不改契约。
描述同时附人用面板链接和执行节点用的只读内网 API 链接(默认 `https://streamline-internal-api.bytedance.net`,本地部署可用 `EDDY_HANDOFF_AGENT_BASE_URL` 覆盖),以及实际 ZIP 的 SHA256。卫星先下载/解压读全套材料,不能用浏览器 SSO 面板 URL 抓到的 HTML 代替附件。
建任务要有人认领:只认浏览器 SSO 或 `./eddy auth login` 得到的 Eddy 会话(创建人 = 会话邮箱),API key 与
`X-Eddy-User` 一律 401。产品配置按基线 id 前缀反查 `EDDY_EXPORT_PRODUCTS`(`tiktokm`→tiktok、`notes`、`whee`),
查不到或该产品未启用时 400、不落库——不再静默落到 TikTok/develop。
## 未做 / 后续
- 语义检索目前是词法打分(与 KB 主库同一状态:embedding 列保留给 Phase C)。
- 跨版本 carry-forward(新基线发布时在卫星上重放上一版 open problems):发布入口已经有了(`/admin/releases/:baseline`),复验作业本身未做。
- 客户端只在 `origin=central` 的基线上共享;用户 `import-app` 的基线只用本地 advisory。
+55
View File
@@ -0,0 +1,55 @@
# Eddy client SSO
Ordinary employees can connect Eddy from `/eddy/connect` after signing in to Streamline.
The browser forwards its existing InspireCloud session to `/api/eddy/auth/authorize`.
The server verifies `getUserInfo`; neither the client email header nor admin membership is used to authorize knowledge contribution.
The CLI owns a temporary IPv4 loopback callback, random state, and PKCE S256 verifier.
The server returns a 2-minute, one-use authorization code bound to the callback URI and challenge.
`POST /auth/token` atomically consumes the matching grant and issues a random, revocable 30-day session.
Only hashes of grants and sessions are stored. Expired entries are pruned during authorization.
`GET /auth/session` checks the session; `POST /auth/logout` revokes it.
The historical session scope is `eddy:knowledge:write` (kept for existing clients).
It also identifies the person for private conversation reads/writes under `/api/eddy/conversations`,
using the full SSO email with no admin/API-key bypass; see [conversation sync](conversations.md).
For existing contributions it is accepted by `POST /api/eddy/knowledge`
and session status/logout. Product usage submission `POST /api/eddy/usage` also uses this session;
aggregated monitoring is browser-admin-only. Even a session issued to an administrator does not carry admin rights.
Direct browser SSO and legacy API keys retain their existing behavior. Release tokens and TOS publishing are unchanged.
Knowledge author attribution matches direct browser SSO (normalized email prefix), so either path can revise the same record.
Historical records attributed to `api-key:opk_…` retain that owner; an SSO login does not silently claim them.
The client stores sessions per API base URL in a 0700 directory with 0600 files and atomic, locked writes.
Only status/email/expiry reach Portal and CLI output. Browser cookies and SSO session tokens never pass to the CLI.
The browser callback carries only the code and state, suppresses logging/referrers and removes the query from browser history.
The client does not follow API redirects while exchanging a code or using its contributor session.
## Deployment
1. Apply `drizzle/0032_eddy_sso.sql` through the normal approved migration flow before deploying the server.
It only adds two tables and their expiry indexes; there is no migration of existing knowledge or permissions.
2. Deploy both control-server and control-web from this change. `/eddy/connect` is available to every SSO user, outside admin UI.
No new environment secret or SSO provider callback registration is needed: the existing Streamline web login handles SSO.
3. Publish an Eddy release containing the CLI, network client, Portal source and rebuilt Portal assets from the matching change.
4. On the corporate network, test `eddy auth login`, ordinary-user contribution, logout and subsequent rejection.
Local fixture tests verify the entire callback/HTTP/database flow but do not certify the live SSO provider or gateways.
For a custom deployment, configure Eddy's `streamline.web_url` alongside `streamline.base_url` so the browser and CLI use the same database-backed control plane.
The official mapping is `https://streamline-internal-api.bytedance.net` → `https://streamline.bytedance.net`.
Rollback: keep the additive tables and restore the previous server/client releases; legacy API key contribution remains available.
Existing SSO-only clients need the new control plane; rolling the server back makes their sessions unusable until it is restored.
## Validation
Use only an isolated local database through `TEST_DATABASE_URL`. Run each integration file separately because they close the pool and mock modules:
```sh
bun test control-server/test/eddy_sso.integration.test.ts
bun test control-server/test/eddy_catalog.integration.test.ts
bun test control-server/test/eddy_handoff.integration.test.ts
```
Tests cover employee identity, wrong verifier/callback, one-use concurrent exchange, expiry, revocation,
knowledge revisions, absence of admin/release/telemetry privileges, and hash-only persistence.
+47
View File
@@ -0,0 +1,47 @@
# 兼容知识流程:分发与客户端应用
问题归属与症状分开记录:`source-bug`(源码,只记录)、`devicesim`(通用运行层,可启动独立源码修复任务)、`app-compat`(特定 App 构建的兼容知识)。`unknown` 保留待分类材料,`confidence=suspected` 明确假设,不能用 Catalyst 单端结果证明真机无问题。
Agent 蒸馏读取本任务明确关联的聊天、观察、真实脚本与回执。`eddy task chat <id> --agent codex --session-id <id>` 或 `--file <JSONL>` 建立关联;不搜集其他聊天。提交 JSON `knowledge` 包含 category/confidence/summary/cause/solution/validation/rollback;可附 `advisory` 文字和 Frida JS / launch-config。源码和 DeviceSim 类型只提交文字。
```sh
./eddy compat propose 'hang:layout' --category app-compat \
--knowledge-file knowledge.json --tier frida-guard --payload guard.js --title '修复限定场景的布局递归'
```
基线下载发布与知识提交解耦,不要求 App 在官方目录上架。补丁目标包含 baseline、bundle/version/build、arm64、Catalyst platform=6、完整主程序 UUID、主程序 SHA-256,以及所 hook 的嵌入库 hash(自动收集 Core.framework,其他库缺少身份时先提交文字)。不能仅按市场版本号匹配。版本记录不可变,相同内容重交幂等,修改产生新修订。
## 认证和检查
提交共享知识与反馈需要 SSO 或已有 Streamline Open Platform API key。客户端配置 `EDDY_STREAMLINE_TOKEN` 或 installation.json 的 streamline.token;用户名 header 仅署名,不能认证。失败时本地候选保留,401 不冒充提交成功。不要把 token 写进聊天、报告或仓库。
Streamline 接收经过认证的上报,验证基础格式、载体文件名与声明 hash。新提交的 `app-compat` 文字建议、Frida JS 和 launch-config 保存后即分发,不等待服务端 Agent/模型检查或卫星复验。源码、DeviceSim 和待分类材料仅记录。基线下载是否上架不影响知识分发。native-dylib 暂不进入此自动应用协议,保留为待处理材料。
管理员可在问题行修改分类,并对旧记录点击「确认分发」,或对已分发的材料停用/恢复;操作记录 actor、时间、auto/admin 来源以及原 manifest/payload hash。修改分类不改动不可变的载体和清单;旧记录不会因升级或补分类而自动发布。改为非基线兼容分类会停用关联的已分发材料,后续上报不能覆盖管理员分类。重复提交同一载体不会重新启用已停用修订,迟到复验也不能复活它;确认分发不伪造或覆盖安全检查结果。
`distribution` 是目录分发决定,独立于历史 `safety`。新客户端声明 `X-Eddy-Compat-Protocol: 3`,收到绑定当前 manifest/payload 的 `eddy-distribution-v1` 回执。旧客户端收到新分发记录的 candidate 状态,避免把分发误作执行许可。较旧可用修订不会因新修订停用而回退启用。
客户端核对精确二进制身份、manifest 和 payload;有本机 Agent CLI 时使用用户选择的 CLI 快速安全检查(60 秒上限,按 server/manifest/payload/CLI/policy 缓存)。Codex 在临时目录只读运行,关闭 shell/apps/plugins/多 Agent/浏览器和搜索,忽略用户配置;Claude 使用空工具集与严格空 MCP。检查阻止、未知或不可用时保留为未应用并提示。未安装 CLI 时不做模型检查,仍执行身份、完整性和运行合约校验,不声称服务端已审核。知识文本不是执行工具调用的授权。
分发不要求旧记录已经补全可执行身份:它可以先被同步、阅读,但缺少主程序 SHA-256 等字段的旧补丁不能自动应用。控制面显示这一边界。历史模型检查仅供参考,不再阻止管理员分发;真正的客户端应用状态由安装回执反馈。
## 应用时机与恢复
安装基线后和启动前召回;Portal/启动器运行时每 5 分钟同步已安装基线。同步只准备下次启动的 active.json,不重启、重新附加或改写当前 demo。必须在窗口前安装的 guard 使用第一行 `// eddy-compat-install: bootstrap`。
guard 安装异常先调用 dispose 尝试清理,隔离失败的 fix@rev 并回传结果;后续启动跳过失败修订,不循环拉起 App。当前任务、产品 registry 和容器数据保留。无法可靠判定哪个补丁导致进程崩溃时不随意归因;通用物理内存上限仍独立生效。服务端停用会在下次同步影响后续启动,已经装入的补丁不会在演示中途被强制重启卸载。
## 本地验证
Python 回归使用 `PYTHONPATH=vendor/site-packages ./vendor/python/bin/python3 -m unittest discover -s tests`;JS 合约使用 `node --test tests/test_engine_compat.mjs`。`stub/control_plane.py` 保留旧协议回归用途,不代表正式服务的安全检查;完整 v2 流程在 Streamline 的隔离 PostgreSQL 集成测试验证。
## Streamline 运维接入
部署按正常迁移流程应用 `drizzle/0029_eddy_knowledge.sql` 和 `drizzle/0030_eddy_distribution.sql`(开发空库可使用 drizzle-kit push)。需要更新 control-server、control-web 和 Eddy 客户端。分发不要求在线 satellite;DeviceSim 源码修复仍需支持的节点。
- 服务端不再启动安全审核队列,保留 satellite 安全检查能力供独立诊断使用;它不修改目录分发状态。
- DeviceSim 修复节点:设置 `EDDY_DEVICESIM_REPO` 为 `ugc-android/DeviceSim` 本地 Git 仓库,必须由维护者同步到要修的源码;用 `EDDY_DEVICESIM_AGENT=codex|claude` 选择 CLI,可配置 `EDDY_DEVICESIM_AGENT_BIN` 和 `EDDY_DEVICESIM_JOBS`。节点报告 `eddy-devicesim-v1`。管理台点击后,从该 checkout 的 HEAD 创建独立 worktree/branch;Codex 使用 workspace-write 沙盒,Claude 使用限定工具,保存日志、报告和 git diff。不自动注入 App、提交代码、推 MR 或部署;维护者可审查差异后按正常 DeviceSim 流程提交。节点重启显示 interrupted,保留工作区。
- 管理台分别显示可编辑分类、真实分发状态、具体建议与载体、验证/撤销说明。历史服务端检查折叠显示,避免将模型判断混为分发状态。
- 写 API 复用 Open Platform key;并非发布流水线的 `EDDY_RELEASE_TOKEN`,也不信任 X-Eddy-User。管理员继续用原 SSO 管理。
集成测试必须显式设置 `TEST_DATABASE_URL` 为隔离本地 PostgreSQL,运行 `bun test control-server/test/eddy_flow.integration.test.ts`;没有该变量时跳过。该测试明确不提供安全扫描节点,验证无模型依赖的自动分发、管理员分类/确认、只读旧载体、幂等、停止保护和客户端协议兼容。
+110
View File
@@ -0,0 +1,110 @@
# Eddy main-Agent conversation sync
The Eddy setting is opt-out, enabled by default; there is no separate sync confirmation.
The client first requires the person's Streamline SSO session and a task-bound source.
It uploads that entire source session's available visible history and new records,
including user/assistant messages and tool calls/results, without the summary reader's text budget.
Hidden reasoning, system/developer instructions, Claude sidechain records and binary attachments
are excluded. Recognizable credentials are masked on the client on a best-effort basis.
This is not a complete multimedia replay or a guarantee of arbitrary-secret detection.
`POST /api/eddy/conversations`: schema 1, batchId (sha256), taskId, taskTitle, sourceId (sha256),
provider (codex/claude/file), machine (16 hex), events (1–64). Body is limited to 512 KiB.
Each event contains id, streamId (optional hash of the log basename), position (byte offset), block,
part (zero-based), parts, kind (message/tool_call/tool_result/attachment), role, text, redacted,
and optional timestamp/toolName/callId. Unknown properties are discarded.
Long text parts are reconstructed in streamId/position/block/part order; identical repeated messages
retain different event ids. The server acknowledges `{batchId, accepted}` after its atomic insert.
Duplicate event delivery is accepted without another row. Ownership is part of the deduplication key.
`GET /api/eddy/conversations?task=<taskId>&machine=<machine>&source=<sourceId>&cursor=<sequence>&limit=100`:
returns `{events, nextCursor}`, 1–500 records per page in insertion-sequence order.
Each envelope carries taskId/taskTitle, sourceId/provider, machine, receivedAt, sequence and event.
Use nextCursor until null. Same main session bound to several Eddy tasks is intentionally associated
with all those tasks; these records are not a claim of per-message task attribution.
## Viewing history
The SSO-only `/eddy/tasks` page is linked from the account menu (“我的 Eddy 任务”) and
Management → Eddy (“我的任务与会话”). It is available to ordinary signed-in users,
independent of the administrator-only usage/knowledge panels. Each user sees their own
records there. Browser-SSO Streamline administrators can also read every account's history
(internal employee data): `/eddy/tasks?scope=all` (linked from Management → Eddy as
「全部用户任务与会话」) adds a per-account summary (tasks, sessions, devices, records, first/last
sync), an account filter and the owner on each task; an Eddy session never grants this.
The standalone page does not boot the task board or its background fetches.
- Search tasks by latest reported title or task id; same task id on two installations
is displayed separately. Task titles reflect the latest received event, not a live
task metadata mirror. Tasks with no uploaded conversation do not appear.
- Select a Codex/Claude/imported source; the task, machine and source ride in the URL
for refresh/back/forward. Opening the link still requires the same SSO owner.
- Read available visible messages in source-file position order. Text split over upload
or read pages is reconstructed; incomplete parts are labelled until loaded. Repeated
messages are preserved. Tool calls/results are collapsed and all content renders as
inert text. No remote images, HTML or attachment binaries are loaded by the viewer.
- “任务信息与产物” shows task identifiers and the first available user message as a
requirement reference, clearly labelled. It is not an independently maintained task
description. Screenshots, patches and snapshots are not uploaded by conversation sync;
handoff bundles remain accessible through the corresponding Streamline feature.
- Read more via bounded pages or refresh explicitly. Empty data, old server (404), expired
login (401) and retryable failures have distinct states. Private reads are `no-store`
and are not shared by the Web API's cross-component in-flight GET cache.
Metadata list APIs (same SSO/owner checks and no-store):
`GET /api/eddy/conversations/tasks?q=<title-or-id>&before=<sequence>&limit=30`
returns `{items, nextCursor}`. Each item contains `machine, taskId, taskTitle,
lastReceivedAt, lastSequence, recordCount, sourceCount`; there are no transcript bodies.
Search is literal/case-insensitive (including `%`, `_` and backslashes), at most 200 characters.
`GET /api/eddy/conversations/sources?task=<taskId>&machine=<machine>&before=<sequence>&limit=30`
requires both selectors and returns `{items, nextCursor}` with `sourceId, provider,
firstReceivedAt, lastReceivedAt, lastSequence, recordCount`. A missing or non-owned task
returns an empty list. Both lists allow 1–100 rows per page, newest received sequence first;
pass `nextCursor` as `before`. New uploads can move an item to the front during browsing;
refresh the list to see these updates. Counts are stored fragments, not message counts.
Both methods require verified browser SSO or an active Eddy SSO session, scoped by the **full email**.
No API-key, release-token, X-Eddy-User or administrator bypass. Responses are `Cache-Control: no-store`.
The historical scope string stays `eddy:knowledge:write` for existing client compatibility, as for handoffs;
these routes use the SSO identity, and do not grant admin/release rights. Nothing enters the public knowledge feed.
Switching off stops subsequent client reads and uploads after an in-flight short request finishes;
it does not delete already stored data. Switching on catches up. Logged-out clients never read transcripts.
Only acknowledged offsets/parts are stored locally. 401/404/503/offline preserve progress for retry.
An old control plane returns 404; this does not block local Eddy use.
## Rollout and validation
Apply additive `drizzle/0065_eddy_conversations.sql` using the normal deployment flow **before** the server release,
then release the client. There is no production schema/data mutation in local development.
Rolling back the client stops the worker; the additive table can remain. Stop the route to stop receiving.
```sh
# TEST_DATABASE_URL must be an explicitly isolated database.
bun test control-server/test/eddy_conversations.test.ts
TEST_DATABASE_URL=postgres://user@127.0.0.1:55483/test bun test control-server/test/eddy_conversations.integration.test.ts
# Optional actual Eddy Python → HTTP → Postgres probe, using synthetic temporary sessions only:
EDDY_TEST_SOURCE=/path/to/eddy-source TEST_DATABASE_URL=postgres://user@127.0.0.1:55483/test bun test control-server/test/eddy_conversations.integration.test.ts
```
The integration database needs `0032_eddy_sso.sql` and `0065_eddy_conversations.sql`.
Tests cover authentication, expiry, owner isolation, no admin bypass, retries, pagination, limits,
Unicode/long messages, tools, reasoning exclusion, masking and default-on/off/on catch-up.
The optional browser integration test `control-server/test/eddy_history.browser.test.ts` seeds only
synthetic records, starts a loopback HTTP fixture and cleans them up. Build the real page fixture with
`bun build control-web/test/fixtures/eddy-history.tsx --target browser --outdir /tmp/eddy-history-bundle
--define 'import.meta.env={"VITE_DEBUG":"1","DEV":true}'`, then set `TEST_DATABASE_URL` (isolated PG),
`EDDY_HISTORY_BUNDLE=/tmp/eddy-history-bundle` and run the test. The committed driver is
`control-web/test/eddyHistory.browser.mjs`; it requires Playwright/Chrome in the test environment.
`EDDY_HISTORY_BROWSER_NODE` selects Node, `EDDY_HISTORY_PLAYWRIGHT_PACKAGE` can point at a dependency
package.json from which Playwright resolves, and `EDDY_HISTORY_OUTPUT_DIR` selects the screenshots/report
directory. The driver rejects a non-loopback fixture URL; it never needs production SSO or data.
Administrator APIs (browser SSO administrator only, no-store; same pagination and validation):
`GET /api/eddy/admin/conversations/users` → `{items:[{owner, taskCount, sourceCount, machineCount,
recordCount, firstReceivedAt, lastReceivedAt}]}`; `GET /api/eddy/admin/conversations/tasks?owner=&q=&before=&limit=`
(owner optional; items carry `owner`); `GET /api/eddy/admin/conversations/sources?owner=&task=&machine=…` and
`GET /api/eddy/admin/conversations?owner=&task=&machine=&source=&cursor=&limit=` (owner required).
+72
View File
@@ -0,0 +1,72 @@
# Eddy 崩溃报告(POST /api/eddy/crashes)
Eddy 用户的 App 在任务里崩溃时,Eddy 本机 supervisor 保存这次启动的完整现场并自动重启(重启后没有任何用户动作、任务也没变又崩,才视为循环,停下),
按崩溃栈规则判断归属,四类里三类上报到这里,供维护者复现和接力修。**报告里是事实和规则判断,不是结论**:读的时候以证据文件为准。
**什么时候到达**:Eddy 当前版本(`2026.10.23-eddy-home.19` 起)在崩溃当场按规则上报,不论任务有没有改动(看 `task.edits`),
报告固定 `classSource: "rule"`、`confidence: "suspected"`,不带用户本机 Agent 的判断(它只留在用户本机,避免较弱的本地模型推测成为修复的起点)。
更早的 Eddy:任务没有改动时当场按初判上报(`suspected`),用户的 Agent 确认后再发同一份报告(`confirmed`、带 `note`),按 id 更新;
这类 `note` 是用户本机 Agent 写的,只当线索。
| class | 含义 | Streamline 侧问题分类 |
|---|---|---|
| `devicesim` | DeviceSim 的问题(栈落在 `devicesim.dylib`,或与它模拟的摄像头/运动/窗口等能力有关) | `devicesim`(可直接派 DeviceSim 修复 Agent) |
| `eddy` | Eddy 自己的问题(`runtime/app_compat`、adhoc 补丁、补丁引擎、启动配置) | `eddy`(记录,交 Eddy 维护者) |
| `app` | App 源码问题(例如 unrecognized selector);用户 Agent 另行找绕过办法,经用户同意后用在任务里 | `source-bug` |
第四类 `task-edit`(用户在任务里要求的改动没改好)由 Agent 在本机继续修,不上报;服务端也拒收。
客户端契约与 `crash.json` 字段见 `streamline_playground/API.md`「崩溃报告」,Agent 规则见该仓 `skills/eddy-frida/SKILL.md`「App 崩溃时」。
## 存储(不加表、无迁移)
- `eddy_observations`:一份报告一行,`id` = 客户端崩溃 id(`crash-YYYYmmddTHHMMSS-<8hex>`),
`payload` = `{kind:"crash-report", report}`;`user` 为会话/SSO 身份,`machine` 为客户端硬件 UUID 的 sha256 前 16 位。
同一 id 再次上报:同一上报人(且 baseline、signature 不变)更新 `payload`,返回 `{duplicate: true, updated: true}`;别人的重发忽略。
- `eddy_problems`:和其他观察一样按 `(signature, baseline)` 归并(含 alias)。问题**未分类**或分类**来自崩溃报告**
(`knowledge.source = "crash-report"`)时,写入报告的分类与可信度;suspected 不会覆盖 confirmed;
管理员分类或修法提交带来的分类(没有这个 source)不会被覆盖。
- `eddy_knowledge_assets`:证据文件按 sha256 存(base64)。只经下面的管理员路由下载,且必须是该报告列出的文件。
- DeviceSim 修复(`POST /admin/problems/devicesim`)派发时,问题数据里附上该问题最近 3 份报告(文本,无附件)。
## 上传内容与隐私
报告本身:规则判断的 class 与依据(`reasons`)、signature、异常名与原因、崩溃栈前 12 帧、App bundle/版本/build/UUID、Eddy/DeviceSim/macOS 版本、
启动环境**变量名**(只有 `DEVICESIM_*` 带值)、启动参数**个数**、任务改动数与 key 列表(不含脚本内容)、重启决定;
`localEvidence` 列出留在用户本机、没有上传的文件(名字、大小、sha256),需要时找上报人要。
证据文件(单文件 ≤ 4 MB、合计 ≤ 8 MB):
| 文件 | 内容 |
|---|---|
| `report.ips` | macOS 崩溃报告(Apple 已把用户目录写成 `/Users/USER`) |
| `exception.txt` | 统一日志里该 PID 的 uncaught exception 行(.ips 常常只有 abort()) |
| `devicesim.log` | 这次启动期间 `/tmp/devicesim.log` 写入的全部内容;本机所有 DeviceSim App 共用,可能混有其他实例的行(按 `identity: registered as` 区分)。更早的 Eddy 是尾部 200 行 |
| `events.jsonl` | 崩溃那次启动的 supervisor 事件 |
| `unified.log.gz` | 这次启动 App 的统一日志(`log show --info`,最多回溯 1 小时),gzip |
| `app.log.gz` | App 自己这次启动的输出(stdout/stderr),gzip |
| `supervisor.log.gz` | Eddy supervisor 这次启动的日志,gzip |
`.gz` 文件项带 `of`(原文件名);单个日志压缩后仍超过 4 MB 时只保留结尾,带 `omittedBytes`,解压后第一行也注明。
三份日志按上表顺序放进 8 MB 总量,放不下的进 `localEvidence`。文本中的 home 路径已替换为 `~`。
App 日志可能含账号等信息,用户可在 Eddy 里关闭自动上报。任务脚本(`registry.json`)、启动参数值和其他环境变量值(`launch.json`)、截图、聊天不上传。
## 鉴权
`POST /crashes` 与知识贡献相同:Eddy 会话(`./eddy auth login`)、浏览器 SSO 或 Open Platform API key;只有 `X-Eddy-User` 时 401,
客户端保留 pending,登录后 `./eddy crash submit <id>` 重试。读取全部走管理员(SSO + admin):
- `GET /api/eddy/admin/crashes?class=&baseline=&signature=&limit=` — 列表(最新在前)
- `GET /api/eddy/admin/crashes/:id` — 完整报告 + 每个文件的下载地址
- `GET /api/eddy/admin/crashes/:id/files/:sha256` — 证据文件
## 维护者复现
1. 按 class 拉列表,打开报告,看 `exception`、`stack`、`reasons`(规则依据),再读证据文件;旧报告的 `note` 是用户本机 Agent 写的,只当线索。
2. 基线:`report.baseline` 对应 `eddy_releases` 的官方包(`./eddy baseline add <id>`);`app.executableUUID` 核对是同一份构建。
3. DeviceSim:`versions.deviceSim`(mode/version/sha256)选同一版本;用 `launch.devicesim` 里的 `DEVICESIM_*` 启动。
4. Eddy:`versions.eddy` 是 runtime 版本(`dev` = 源码检出);`task.appCompatibility` / `task.adhocPatches` / `task.engine` 说明当时注入了什么。
5. 下载 `report.ips` 用 Console 或 `atos` 看完整栈;`unified.log.gz` 里常有 .ips 没有的原因(异常、断言、系统框架报错);
`events.jsonl` 是那次启动的时间线(attach、重放、compat、hang);`devicesim.log` 可能混有同机其他实例的行。
## 测试
`bun test control-server/test/eddy_crashes.test.ts`(校验);`eddy_crashes.integration.test.ts` 需要 `TEST_DATABASE_URL`(上传、上报人更新、他人重发忽略、分类随报告更新但不覆盖管理员分类、管理员读取)。
+99
View File
@@ -0,0 +1,99 @@
# Feature 导出到 Eddy
在任务详情的「接力到本地」中选择 Claude Code / Cursor 的 Markdown 文档,或 iOS feature 专属的「准备 Eddy 接力包」。Eddy 由任务卫星机(离线时由同集群的其他 iOS 卫星机)生成临时 App 基线,列表和详情展示进度,成功后飞书通知。用户将 App ZIP 和源码 ZIP 放到同一目录,在 Eddy「基线」安装 App ZIP,再把 RELAY.md 交给本地 Agent。Android 保留普通 Markdown 接力,不显示 Eddy 选项;接口和卫星机解析同样拒绝 Android。
这是 feature 的独立导出作业,不改变 feature 状态、不合并 MR、不发布到 Eddy 官方基线目录。首版支持 `manual_review`、`completed` 且有已推送 MR 分支、已知 `repoKey` 的 iOS feature。
## 执行和交付约定
1. 控制面认证点击者,选定执行导出的卫星机(见下文「哪台卫星机导出」),复用普通接力的报告、反馈历史和执行摘要。共用起点规则:人工复核用任务分支,确认已合入用配置的基线,合入记录未知时先任务分支、明确不存在才退回基线;网络失败不触发回退。Feature 的合入状态通过匹配仓库/源分支的 Bits 只读查询补充。卫星机把所选远端起点解析为完整 SHA,文档记录实际分支和提交。
2. 服务端持久化提交、构建说明 hash、任务/MR 和完整接力文档快照。相同 feature、提交、分支、构建说明及上下文的有效作业复用;每个请求者各有通知记录。反馈/报告变化时新建快照,不把旧上下文当作刚生成的接力文档。
3. 卫星机在串行 implementation scheduler 内领取作业,先获取与 Asking 共用的 checkout 锁。导出占用节点,不与下一次实现、Asking 代码修改或 Eddy compat 验证并行;控制面热部署等待该作业结束。控制面把构建到上传这几个阶段的导出计入该节点的执行槽(`countSlotsPerNode`),所以节点卡片显示「执行 1/1」和「Eddy 导出 · <任务标题>」(`GET /api/eddy-exports/running`,点开进入该 feature),调度台和导出改派也不会把它当成空闲节点。
4. 在独立目录 clone 产品仓,在分支名上检出固定 SHA(`git checkout -B <分支> <提交>`,源码包和接力文档从这里出),再把节点的共享检出(`$AI_WORKSPACE/TikTok`)固定到同一提交(先用验证任务同一个 `checkoutChangeCommit` fetch 分支、`checkout -f --detach`、`clean -fd`,再 `checkout -B <分支> <提交>` 放到分支名上——`airb sync` 按分支名取提交,detached 的需求分支提交远端取不到(`Commit not exist in codebase`);本地分支若有会被丢掉的提交,先存到 `refs/eddy-export/backup/`),并从官方 `eddy/LATEST` 获取 runtime(验证发布 ZIP hash 和分发 MANIFEST;只复制分发清单文件,不复制卫星机 Eddy 的账号、任务、已安装 App)。
5. **构建由智能体按 DeviceSim 的 `Skill(airbuild)` 完成**——和该节点修复/验证任务出包是同一套做法,构建细节只维护在 skill 里(「工程专用」的 TikTok 与 TikTokNotes / Whee 两节)。智能体在共享检出上用它已绑定的 airspace 构建(和修复/验证任务一样;**不 `airb init`、不 `airb release`**——每人只有 2 个空间,原先每次导出新开一个、失败的还保留,配额满后导出全部在 init 失败),把产物 `airb pull` 到作业的 `build/`,并写回执 `airbuild-receipt.json`。随后 worker 只认:独立 clone 与共享检出的 HEAD 都不变且无改动/新文件、`build/` 里恰好是声明的那个 `.app`、回执的产品与提交与作业一致。回执是构建声明,作为 `BUILD.json` 进包;源码包始终按固定提交切。
6. 打包直接调用 Eddy 的 `portable/build_app_baseline.build`(runtime `2026.10.15-eddy-home.12` 起支持 `extend`):先在作业目录的 `DEVICESIM_ROOT` 里装好 DeviceSim(runtime `2026.10.23-eddy-home.18` 及以前用包里随附的;之后的 runtime 不带 DeviceSim,由 Eddy 从 DeviceSim 官方渠道下载最新 stable,所以卫星机要能访问办公网下载入口),用它经 cat-supervisor 完成转换、注入和签名,切源码包、写基线;导出只通过 `extend` 加入任务来源、`BUILD.json`、`RELAY.md`、`INSTALL.md`,产物在作业目录的 `package/artifacts/`。冒烟后由 Eddy 的 `devicesim_install.stop_capture_daemon()` 停掉从作业 DeviceSim 拉起的截图 daemon。`DEVICESIM_ROOT`、`EDDY_STATE_DIR` 和 cat-supervisor 的实例目录都落在作业目录里,不切换、不触碰节点自己的 `/Users/Shared/DeviceSim` 与 `~/iosapp`。
7. 在作业自己的 runtime / state 下安装 ZIP、DeviceSim 选 `installed`(即上一步在作业目录里启用的那份),启动 App 并运行 Eddy smoke。要求原生连接 active、无产品编辑、无 Frida engine attach、产出有效 PNG。此检查证明基线可启动、可截图,不等于 feature 的业务验收。
8. 两份 ZIP 经 SHA-256 和长度检查后,由卫星机直传 TOS。服务端仅签发该作业对象的 PUT 请求,不给卫星机 AK/SK:签的是 **TOS 临时签名**,地址是桶的**内网子域名** `https://<bucket>.tos-cn-north.byted.org/<key>`,2 小时内有效,每次重试重新签发。不能用图片上传那套 S3 签名:卫星机在办公网,办公网 DNS 只解析内网子域名,`tos-s3-cn-north.byted.org`(任何形式)和裸 `tos-cn-north.byted.org` 都解析不了。临时签名是 TOS 文档(「TOS 临时签名」「不同环境如何访问 TOS」)给无 Consul 环境的上传方式,HMAC 的 key 是桶的 access key,签的是方法、路径、签名名称和过期时间,不含内容摘要,所以字节的正确性由卫星机上传前的预检和控制面随后的回读保证。控制面从用户下载地址流式回读两份文件并校验;完成请求立即返回 202,校验在后台运行,卫星机继续心跳及查询。
9. 只有回读成功才标记 ready、开始 7 天有效期并发送飞书卡片。卡片链接回任务详情,避免保存一个即将过期的直接下载地址。
产物:
- `baseline-<baselineId>.zip`:App、DeviceSim、baseline.json、MANIFEST.json、安装说明及 feature 上下文。
- `baseline-<baselineId>-source.zip`:Eddy 标准源码快照,严格对应同一提交。包含受支持的 tracked 文本文件,不是完整 Git 仓或可直接重编译的全量依赖副本。
- 卫星机保留 `build.log`、`result.json`、`verification.json`、`smoke.png` 等诊断材料。作业结束清理源码检出、runtime 副本及大型中间产物;若原生停止失败则保留 runtime/state 供排查。
## 配置与部署
默认 `EDDY_EXPORT_ENABLED=0`。开启前须部署控制面、shared 和卫星机代码,按仓库正常发布流程应用 `drizzle/0033_eddy_feature_exports.sql`。该迁移仅新增两张表和索引,可重复执行;回滚代码时关闭开关即可保留历史记录。
控制面配置:
| 配置 | 用途 |
| --- | --- |
| `EDDY_EXPORT_ENABLED=1` | 启用创建、下载、节点执行及维护 |
| `CLUSTER_SECRET` | 可选,与集群其余接口一致:配置了就校验,控制面和卫星机须相同;留空则不校验 |
| `TOS_ACCESS_KEY`、`TOS_SECRET_KEY`、`TOS_REGION`、`TOS_S3_ENDPOINT`、`TOS_BUCKET` | 导出与图片上传共用同一套配置和 bucket;导出上传用 `TOS_ACCESS_KEY` 签临时签名 |
| `EDDY_EXPORT_TOS_DOMAIN` | 可选,导出上传用的内网子域名根,默认 `tos-cn-north.byted.org`(桶在其他区域时改成对应的内网子域名) |
| `APP_BASE_URL` | 飞书卡片返回任务详情的地址 |
| 现有 Lark 机器人凭据 | 就绪通知;未配置时产物仍可下载,通知保持待发 |
对象固定落在 `eddy/task-exports/<exportId>/<sha256>/<filename>`,下载地址由 `shared/src/protocol.ts` 的 `TOS_DOWNLOAD_BASE` 拼出,与图片上传同源。在 TOS 为该前缀配置 **8 天生命周期**,覆盖上传至校验完成的时间和随后的 7 天下载窗口。API 的过期检查不等于物理删除,已经拿到的直接 URL 在对象删除前仍可能有效。失败产生的对象也由同一生命周期清理。首版单文件上限 4 GiB,使用单次 PUT,不做分片上传。
卫星机需要已解锁的 Apple Silicon macOS 15+ 会话、Xcode 工具、产品仓读取权限、到控制面的网络、能解析并访问 TOS 内网子域名 `<bucket>.tos-cn-north.byted.org`(办公网默认可以),并有足够容纳源码和数份 App 副本的磁盘空间。
**卫星机不需要任何导出专用配置。** 只要具备修复/验证任务出包本来就用的两样——PATH 上的 `airb`(且已登录 Airbuild)和 DeviceSim 的 airbuild skill(`<AI_WORKSPACE>/.claude/skills/airbuild` 或 `~/.claude/skills/airbuild`)——就会领取导出。缺任意一样时,「准备 Eddy 接力包」会直接报出缺的是什么。
接力对话框的导出记录会写明由哪台卫星机执行;排队时说明在等什么(卫星机正忙、已离线、刚等待领取),改派过的会注明接力文档里没有修复报告。
**哪台卫星机导出。** 任务卫星机在线就由它导出,它报的错(缺 airb、查不到远端分支等)原样返回。离线时改派:导出只用远端已推送的提交、独立 clone、Airbuild 远端构建和官方 runtime,不读执行节点磁盘上的任何东西,唯一拿不到的是修复报告(接力文档里会标注未能获取)。候选是在线、iOS、集群标签与该 feature 相交、不是实验机(`manual-only`)的节点,空闲的排前面;控制面同时请它们解析起点,选排名最靠前且解析成功的那台,作业从此只派给它。都不行时报错里列出各节点的原因。改派占用的是那台卫星机的时间和它共享检出已绑定的 Airbuild 空间。
**构建什么由任务决定。** `product` 取自 feature 的 product profile id(无 profile 时回落成 `tiktok`),在 `shared/src/eddy_export.ts` 的 `EDDY_EXPORT_PRODUCTS` 里查到 Eddy 目标名、产物名和启动参数;**怎么构建**只写在 DeviceSim airbuild skill 的「工程专用」里,Streamline 不再维护任何构建脚本或节点配方。目前支持:
| product | skill 一节 | 产物 | Eddy key | 启动参数 |
| --- | --- | --- | --- | --- |
| `tiktok` | TikTok | `TikTokM.app` | `tiktokm` | `-skipForceLogin` |
| `notes` | TikTokNotes | `TikTokNotes.app` | `notes` | 无 |
| `whee` | Whee | `Whee.app` | `whee` | `-skipForceLogin` |
`lemon8` 等表里没有的 product 会干净报错「该产品还不支持导出到 Eddy」,不会误编成别的 App。新增产品 = 先在 skill 里写清它的构建,再在表里加一行。
- `EDDY_EXPORT_ROOT` 默认 `~/.streamline/eddy-exports`;`EDDY_EXPORT_PYTHON` 默认系统 Python。官方 runtime 包缓存固定在 `~/.cache/streamline/eddy`。
- Eddy 更新不会覆盖节点的现有安装。每次作业从最新官方分发生成隔离 runtime,并将实际版本留在回执中。
## 重试与排查
状态为 `queued → building → packaging → verifying → uploading → ready`,中途可失败。执行租约为 120 秒,卫星机每 20 秒续租;失联或进程重启后作业失败,旧 lease 的回报不能覆盖新状态。排队中的作业只派给选定的那台卫星机:它超过 10 分钟没有心跳,作业标为失败,「导出当前提交」会重新选卫星机(短暂离线如部署重启不受影响);排队超过 24 小时同样失败。失败或过期时点「导出当前提交」,会重新解析当时的分支 SHA 并新建作业。
断线后的完成确认可以重复请求;已经 ready 的作业直接返回既有结果。上传清单固定后不能换文件内容。飞书通知单独重试,常规重复点击不重复通知;极端情况下发出成功、落库前进程崩溃,通知可能重发一次。
日志在 `<EDDY_EXPORT_ROOT>/<exportId>/`:`build.log`(worker 各阶段)、`build-agent.log`(构建智能体的会话流)、`airbuild-receipt.json`(构建回执,失败时带 `error`)。UI 错误包含 exportId,构建失败时带回执里的原因。构建、签名、原生 smoke 或校验失败时不发布下载入口,原 feature 的实现结果保持原样。
导出不开也不释放 Airspace:构建用共享检出已绑定的那个,失败后它照常留给下一个修复/验证任务;共享检出停在导出的提交上(分离 HEAD),下一个任务会检出自己的分支。
## 验证
```bash
bun run typecheck
bun run build
bun run build:satellite
bun test control-server/test/eddy_export.test.ts
python3 -m unittest discover -s satellite/eddy-export -v
```
数据库集成测试只接受显式提供的本机 `*_test` 数据库;先在可丢弃数据库加载 schema,再运行:
```bash
TEST_DATABASE_URL=postgres://test@127.0.0.1:5432/streamline_test \
bun test control-server/test/eddy_export.integration.test.ts
```
集成测试使用真实 PostgreSQL,拦截全部 SSO、卫星机和对象下载网络请求,覆盖鉴权、并发幂等、任务变化、固定提交、阶段顺序、过期租约、错误产物、异步完成确认、通知预约、过期重建;不发真实飞书消息。
可选真实工具链测试:编译一个最小扁平 Catalyst App 代替构建智能体,经该 runtime 自带的 cat-supervisor 打包,并从本地 ZIP 安装 App 与源码;不启动原生 App。`EDDY_EXPORT_TEST_RUNTIME` 指向解压后的官方 runtime(含 `MANIFEST.json` 的目录):
```bash
EDDY_EXPORT_TEST_RUNTIME=/path/to/official/eddy-runtime \
python3 -m unittest discover -s satellite/eddy-export -v
```
UI 的本地示例在 `/test/fixtures/eddy-export.html`,可检查初始、构建中、可下载、失败、过期和未启用状态。上线前还需在配置好的卫星机上对真实 feature 跑一次完整构建、原生启动、TOS 上传/回读和客户端下载安装。
+55
View File
@@ -0,0 +1,55 @@
# Eddy 摄取容量、限速和正文去重
## 范围与默认值
单次请求的512 KiB/64事件(对话)、128 KiB/100事件(使用行为)限制继续保留。
新增服务端配额,不接受客户端传入配额或身份。SSO完整邮箱派生SHA256预算标识,同一用户所有设备共用额度;该标识只用于预算,不进入产品指标响应。
使用行为 schema 2 允许不带凭据上传(只收正式环境、一批只能来自一台设备)。**所有未登录上传共用一份额度**(预算标识固定为 `anonymous` 的 SHA256),不按客户端声明的设备标识分:设备标识可以随便填,按它分额度会让每个请求都换一份新额度、新增一行预算记录,进而把全局额度耗尽。这份共用额度单独可配(`EDDY_USAGE_ANONYMOUS_BYTES/_ROWS/_DAILY_BYTES/_DAILY_ROWS/_RPM/_BURST`,默认 1 GiB / 400 万行 / 每天 64 MiB、40 万行 / 每分钟 300 批、突发 16 批),累计和速率都不超过全局的一半,登录用户的上传始终有余量。设备标识只用于统计;未登录的数据是客户端自报的,看板把它单独标为「未登录」。
| 项目 | 对话默认 | 使用行为默认 |
| --- | --- | --- |
| 账号每日新增逻辑字节 | 256 MiB | 16 MiB |
| 账号每日新增行数 | 250,000 | 100,000 |
| 账号累计逻辑字节 | 2 GiB | 256 MiB |
| 账号累计行数 | 2,000,000 | 1,000,000 |
| 全局累计行数 | 10,000,000 | 10,000,000 |
| 账号速率 / 突发 | 60批/分钟 / 8批 | 同左 |
| 全局速率 / 突发 | 600批/分钟 / 32批 | 同左 |
| 原始记录保留 | 接收后90天 | 接收后90天 |
`EDDY_CONVERSATION_GLOBAL_BYTES` 和 `EDDY_USAGE_GLOBAL_BYTES` **必须显式配置正整数**。未配置、为0或非法时,摄取503拒绝,绝不默认为无限。`.env.example` 中的全局数字只是语法示例,须先由部署人员核对DB可用容量、索引/WAL/副本余量并填写预算。代码未查询生产磁盘余量,未实现物理磁盘水位自动熔断,不能把逻辑字节预算当数据库物理磁盘上限。
配置前缀为 `EDDY_CONVERSATION_` / `EDDY_USAGE_`;其余后缀见 `.env.example`。额度按UTC天计算。修改配置、重启生效,不需改schema;降低至已有用量之下只会暂停新增,不删除旧数据。保留期可由 `EDDY_CONVERSATION_RETENTION_DAYS` 调整。
## 去重和兼容
`eddy_conversation_records` 只保存一次正文,键为SHA256(完整SSO用户、设备、来源、事件id)。不跨用户合并,不按文本值去重;同样文字出现在两个不同事件里仍完整保留。
原 `eddy_conversation_events` 保留每个任务的轻量索引、sequence、标题和来源,正文改为record_id引用。维持现有逐任务分页、不同设备隔离及任务/来源列表;**任务索引仍按事件存在,去重降低正文空间,不承诺降低总行数**。配额同时计入规范化UTF-8正文和任务元数据、两张表的新增行数。PG行头、索引、WAL、副本、物理膨胀不计入逻辑字节。
新客户端可在schema1请求里附带至多32个`tasks`,只发一份事件。服务端事务生成所有任务索引,返回`taskIds`;客户端核对全部关联后才推进游标。旧客户端单任务请求仍可用并在服务端去重;旧服务器无多任务回执时,新客户端回退逐任务请求,不推进未确认的任务游标;每小时重新探测能力。来源/文件/游标不同的任务保持分别上传。
## 并发、拒绝和清理
PG共享令牌桶在独立短事务中扣请求额度,失败的写请求也消耗请求次数。每个通道使用跨进程try advisory lock,最多一个写事务,繁忙返回429;有500ms锁等待和SQL超时,避免大量摄取请求长时间占满连接池。
存储事务先查询已有事件/任务索引,在同一事务中检查并占用全局/账号累计与每日额度,再批量写入正文及索引。拒绝在大正文写入前发生,整批无部分成功;重试仅确认已有记录,不重复扣存储额度。成功响应的`accepted`包含幂等重复记录。
拒绝提供安全错误码和`Retry-After`:`eddy_rate_limited`、`eddy_daily_quota`、`eddy_storage_quota`、`eddy_ingestion_unconfigured`。客户端不推进游标,遵循提示并指数退避/随机延迟;设置显示额度暂停,原始日志不删除。产品使用本地队列仍最多7天/1000条,长时间暂停后超期数据可能被淘汰。
每小时按最多5000条清理过期任务索引/无引用的旧正文,使用同一通道锁,删除与累计额度回收同事务;不退还每日新增额度。清理繁忙或失败延后,不阻塞正常本地使用。计时按接收时间,客户端从头重传的旧日志可能重新进入保留窗口,仍受所有配额约束。预算账本每个用户仅一行,没有无限增长的每日明细表。
## 部署、观察和回滚
本改动包含`0067_eddy_ingestion_budgets.sql`,**迁移、服务更新必须安排一次摄取维护窗口**:停止旧控制面写入,使用正常部署迁移流程原子执行迁移,再启动新控制面。不要让旧版写入器跨迁移继续写,以免旧写入不计预算。迁移将既有正文去重、保留原任务索引和分页sequence,并初始化累计用量;每日用量从新版本接收时开始累计。既有使用事件没有SSO预算归属,迁移只计入全局预算,不猜用户归属。
全局字节预算未配置时,新版仍能读历史,所有摄取等待配置;建议先配置小范围灰度预算核对监控,再恢复客户端开关。只通过迁移和部署流程发布,开发机不得执行生产DDL。
管理员可用`GET /api/eddy/admin/ingestion`查看两个通道的全局用量、行数、配置和是否就绪;普通用户/API key/客户端会话不授予管理员访问权。接口不返回账号标识或聊天正文。
回滚:先停止摄取和新服务,通过部署迁移工具恢复旧列正文:
```sql
UPDATE eddy_conversation_events e SET event = r.event
FROM eddy_conversation_records r WHERE r.id = e.record_id AND e.event IS NULL;
```
恢复后才启动旧二进制,暂不删新表/索引;旧版本没有预算保护,保持客户端上传关闭。再次升级需要重新核算预算,不直接复用回滚期间的账本。
+47
View File
@@ -0,0 +1,47 @@
# Eddy knowledge catalog v1
Reference materials, not executable distribution. All complete categories (source-bug,
devicesim, app-compat, unknown) are accepted and initially Enabled. Classification is
diagnostic metadata. It does not select replay behavior or require administrator/model approval.
The old compat API remains unchanged for old clients; new clients do not execute that feed.
Authenticated POST /api/eddy/knowledge accepts {document, files}, where files maps SHA-256
to base64. Document schema is eddy-knowledge-v1: id, title, category, confidence,
problem {description, steps, expected, actual, cause, signature?},
solution {description, kind, validation, rollback, contract?}, observedEnvironment,
origin {task?, derivedFrom?, legacy?}, attachments [{name, role, mediaType, sha256, bytes}].
Kinds: frida-js, devicesim-diff, launch-config, advice. JS needs a code attachment;
DeviceSim diff needs a diff attachment. Screenshots are optional and should contain only relevant evidence.
24 attachments maximum, 8 MiB each, 32 MiB total; text fields bounded and assets hash-checked.
An author can revise their record; an SSO administrator can also revise.
Eddy clients sign in through browser SSO (`eddy auth login`); ordinary employees receive a knowledge-only session without requesting an API key.
See [client SSO](client-sso.md) for the grant flow, session lifetime and deployment order.
Repeated content returns its immutable revision receipt; a new revision never undoes Disable.
GET /api/eddy/knowledge/feed?cursor=...&limit=50 delivers all enabled materials, independent
of installed baseline. Stable watermark pagination and serialized change sequence allocation
prevent skipped concurrent writes. A subsequent incremental pass catches writes after the
watermark. Disable is a tombstone; clients remove it from default retrieval without deleting
task edits already created from it. A concurrent disable can make an attachment unavailable;
clients keep the prior cursor and restart a full visibility scan on 404.
GET /knowledge/:id/:revision and /knowledge/assets/:hash read content; disabled content
is restricted to administrators. Baseline identity remains metadata for relevance and
local execution checks.
Administrator APIs under /api/eddy/admin:
- GET /knowledge: paged full catalog including Disabled, with latest action actor/time.
- POST /knowledge/:id/state with {enabled: boolean}: audited Enable / Disable.
- GET /knowledge/:id/export: ZIP containing knowledge.json, receipt.json, problem.md,
solution.md and every attachment. The extracted package is compatible with Eddy knowledge save.
Deployment: apply drizzle/0031_eddy_knowledge_catalog.sql before serving these routes.
Then explicitly run scripts/migrate-eddy-knowledge.ts against the intended database.
It preserves old material, author/ID/revision provenance and stopped states, never modifies
old-client compat states and skips imported revisions on repeat. Invalid/missing payloads
are reported for follow-up rather than silently discarded or fabricated.
Unsolved observations remain in the historical audit store; they are not invented solutions.
Review migration output before switching users to the new knowledge view.
Local validation: TEST_DATABASE_URL must point to a dedicated local PostgreSQL database.
Run bun test control-server/test/eddy_catalog.integration.test.ts and the existing
eddy_flow.integration.test.ts separately (both close their connection pool).
+20
View File
@@ -0,0 +1,20 @@
# Eddy 维护任务的全局租约(locks)
有些维护任务全世界只能同时跑一个,比如 Eddy 的定时自动发布(Eddy 仓 `maintainer/autorelease`,每天两次检查 DeviceSim main、TikTok M / Notes / Whee 的 alpha 版本,比线上新就打包发布)。它们在开始前向控制面登记一个具名租约,运行中心跳,结束时注销。代码 `control-server/src/eddy_locks.ts`,表 `eddy_locks`(迁移 `drizzle/0074_eddy_locks.sql`)。
## 接口
都在 `/api/eddy/admin/locks`,权限和 `/admin/releases/*` 相同:SSO 管理员,或 `Authorization: Bearer $EDDY_RELEASE_TOKEN`(`X-Eddy-User` 只做归因,记为 `actor`)。名字是 1–64 位小写字母、数字、`.`、`_`、`-`。
| 请求 | 体 | 成功 | 失败 |
|---|---|---|---|
| `POST /:name/register` | `{holder, ttlSeconds?, info?}` | `{token, lock}` | 409 `eddy_lock_held`,`lock` 里是当前持有者 |
| `POST /:name/heartbeat` | `{token, ttlSeconds?, status?}` | `{lock}`,过期时间顺延 | 409 `eddy_lock_lost`:已被别人接管或已注销 |
| `POST /:name/unregister` | `{token, result?}` | `{lock}`,`lock.last` 记下这次运行 | 409 `eddy_lock_lost` |
| `GET /:name`、`GET /` | — | 当前状态(不含 token) | — |
- `holder` 1–128 个可打印 ASCII 字符(如 `mac-a pid 123`);`ttlSeconds` 30–3600,默认 600;`info` / `status` 不超过 4 KB,`result` 不超过 8 KB,都必须是 JSON 对象。
- token 只在 register 的响应里出现一次,表里只存它的 SHA-256。
- 空闲或已过期的租约才能 register,同一条 SQL 完成判断和写入,并发登记只有一个成功。
- 过期但还没人接管时,原持有者的心跳仍然有效(token 没变)。被接管后原 token 失效,`last` 记录被接管的那次运行(`end: expired`、它最后的 `status`)。持有者应在每个不可逆步骤前确认自己还持有租约。
- 正常注销后 `last` 是 `{holder, info, actor, acquiredAt, endedAt, end: "released", status, result}`。
+88
View File
@@ -0,0 +1,88 @@
# Eddy product usage monitor
Client default-on **产品使用数据** switch is independent of conversation sync and compatibility telemetry.
Off stops collection/uploads and clears pending events; it does not retroactively collect the disabled interval.
Only fixed enums and small numeric fields are accepted: random installation/session/operation/event ids,
time, event/action/source/outcome, duration/queue time, Eddy release and macOS major.
No message, user input, task title/id, filesystem path, screenshot, URL, raw exception, script or App content.
`POST /api/eddy/usage`: schema 1 needs browser/Eddy SSO; schema 2 (Eddy runtime level 6 / Mac app 0.9.13) may also come
without any credential. batchId (64 hex), events (1–100).
Body max 128 KiB. Events older than 8 days or more than 5 minutes in the future are rejected.
Each event: id/installation (32 hex), at (ms), name/action/source (closed enums), release, macosMajor;
optional session/operation (32 hex), outcome, durationMs/queueMs (0–7 days).
Portal views/sessions/engagement require a portal source and session; engagement max 60 seconds.
Runtime events require runtime source; jobs require job source. Unknown event fields are rejected.
PK = SHA256(installation + ':' + id). Atomic insert ignores duplicates and returns `{batchId, accepted}`.
Each new event records the uploading account (`owner`, lower-case SSO email) for the administrator per-user view.
Schema 2 (`drizzle/0073_eddy_usage_devices.sql`) adds per event: `device` (16 hex: sha256(IOPlatformUUID)[:16], the value
every Eddy request already sends as `X-Eddy-Machine`; the same Mac keeps it across reinstalls and folders), `deviceSource`
(hardware | hostname), `env` (clients upload only `production`; anything else is rejected as a client bug), optional
`appVersion` (`0.9.13+15`) and `props` — a closed set per name/action of enums, flags, bounded integers and version strings
(`eddy_usage_rules.ts` PROPS, mirrored by `eddyctl/usage.py`). The Mac app's own events use source `shell`: sessions,
engagement (≤5 min per event), `view.opened` of its screens, `runtime.prepare`, `home.shown`, `permission.flow`,
`update.flow`, `device.profile`. A schema 2 batch without a credential must come from one device; it is stored with
`owner` NULL and `anonymous` true and charged to one shared `anonymous` ingestion budget (its own limits, at most half the global ones — see ingestion-limits.md;
the device id is reporting data, never the quota key, so changing it buys nothing). A credential that does not verify
is still 401, so a lapsed sign-in is noticed.
The client deletes only acknowledged files, caps the queue at 1,000/7 days, uploads every 30 seconds,
and binds a queue entry to its original API endpoint. Collection does not wait on upload requests.
Names: session.started, view.opened, engagement, operation.started, operation.completed,
app.launch, app.session, agent_job.completed; schema 2 adds runtime.prepare, home.shown, permission.flow, update.flow,
device.profile, and (P1) desk.action, preview.change, dock.attach, agent.entry, notice.shown, notice.action, app.crash
(runtime) and the operations storage.clean (props what / freedMB) and storage.tidy. Actions, views (Portal and Mac app)
and props are in `eddy_usage_rules.ts`. The metrics add `details` — those P1 events by action and their one closed
detail (kind / what / class / agent / value) with counts, devices, success rate, median duration and MB freed — crashes
per App hour (summary.appCrashes over appRuntimeMs) and more adoption (desk captures, previews, docking, Agent entry).
Portal workers emit operation starts/ends; their nested CLI skips counting. Manual/Agent CLI uses
exit status plus top-level ok:false/isError. Actual launches measure spawn→ready including failed spawn;
jobs use their actual exit and artifact validation. App runtime is ready→supervisor-exit duration,
not user-interaction time. Session ids restart per Portal document load.
`GET /api/eddy/admin/usage?days=28&release=...&user=<email>`: browser SSO administrator only, no Eddy-session admin bypass.
Returns summary (installations, devices, accounts, devices with anonymous uploads, Portal and Mac app sessions and
time), daily UTC buckets, per-name/action/source counts and percentiles, release breakdown,
`users` (per account, `anonymous` for uploads without a sign-in: devices, installations, sessions, actions, launch/operation
outcomes, Portal/Mac app/App time, last event), `devices` (per Mac: first 8 hex digits only, installations, number of
accounts but never which, sessions, time, launches, App time, Mac app builds, latest hardware profile; up to 500),
`funnel` (devices whose first launch is in the range — a Mac app start on a fresh eddy folder or its first runtime
preparation — and how many then had the runtime ready, reached home, installed an App, opened a task, had an Agent edit,
shared; median time to each), `retention` (those devices by UTC week of first launch: any event on day 1, days 7–13,
days 28–34; a window counts only once it has fully passed), `adoption` (of the active devices, how many opened a task,
used the design desk, cold-restarted an App, had an Agent edit, shared, imported, relayed), `appVersions`, and `flows`
(update and permission steps);
`user` filters every section to one account. No raw rows or installation ids. Activity counts use distinct random
installations, **not deduplicated people**; the per-user rows group by uploading account. Events from before
`owner` was recorded are matched by `budget_owner` (sha256 of the email) against known Eddy accounts
(sign-ins, synced-history owners); unmatched ones appear as `sha256:<prefix>`, events older than that as null.
Success denominator includes success/failure/timeout/interrupted, excludes cancellation and missing outcomes.
Latency P50/P95 uses successful completed events; queue P95 includes all completions.
Portal active time requires visible/focused/recent-input, excludes long sleep gaps. Ongoing App sessions
are absent from completed runtime sums. Days are rolling 24-hour periods; edge daily bins can be partial.
Abandoned pre-SSO sign-in, offline/opted-out clients, dropped queue entries and missing completions
are not a complete product funnel. No native FPS/CPU claim or automatic alerting.
Management → Eddy → **使用与表现** exposes 7/28/90-day, release and user filters, device/account/install and Mac app
KPIs, the activation funnel, weekly retention, feature use, per-user and per-device tables, per-action reliability/latency
tables, update and permission steps, Mac app builds, daily trends and page counts. Auto refresh every visible minute.
`eddy_usage_events` retains received events for 90 days, pruned at boot, hourly and during ingestion.
Data collection is additional to legacy compatibility observations, not an extension of their raw payloads.
Rollout: apply additive `drizzle/0066_eddy_usage.sql` through deployment, then server, then client. Schema 2 the same
way: `drizzle/0073_eddy_usage_devices.sql`, then this server (it keeps accepting schema 1), then the Eddy runtime, then
the Mac app.
This follows the separate conversation migration 0065 when both features ship together.
Client rollback stops new collection; server rollback can leave the additive table in place.
Development tests use only explicitly isolated `TEST_DATABASE_URL`, never the production database.
```sh
bun test control-server/test/eddy_usage.test.ts
TEST_DATABASE_URL=postgres://user@127.0.0.1:55483/test bun test control-server/test/eddy_usage.integration.test.ts
EDDY_TEST_SOURCE=/path/to/eddy-source TEST_DATABASE_URL=postgres://user@127.0.0.1:55483/test bun test control-server/test/eddy_usage.integration.test.ts
```
Integration database needs migrations 0032 (SSO) and 0066. Synthetic cross-repository probe verifies
actual Python→HTTP→Hono→Postgres, authentication, no admin bypass, fixed-field rejection, idempotency,
exact success/percentile denominators, range/version filters, retention and opt-out.
+156
View File
@@ -0,0 +1,156 @@
# 证据采集监控 · 每日分析任务
这是每日分析跑批的作业书。控制面的定时任务(`scripts/evidmon-daily.sh`)负责把
指标算出来;这份文档负责把「指标变了 → 为什么 → 该做什么」这一步写清楚,产出一篇
研究日志条目和若干条待批准策略。
面板位置:证据采集监控 Portal → **研究日志** tab。
---
## 分工
| 环节 | 由谁做 | 何时 |
|---|---|---|
| 拉取节点 manifest、算指标快照、刷新已生效策略的前后对比 | `scripts/evidmon-daily.sh`(系统 cron) | 每日 09:00 北京时间 |
| 读快照 → 写发现 → 提策略 | 每日分析任务(本文档) | 每日 09:30 北京时间 |
| 批准 / 驳回策略 | owner,在面板上 | 人工 |
| 判据类策略生效 | 批准即时生效(无需发版) | 自动 |
| 其余策略执行 | 转为待办,人工推进后在面板标记「已上线」 | 人工 |
指标快照必须由机器定时写,不能依赖分析任务是否跑成功——否则前后对比的基线会因为
某天没做分析而出现空洞。
---
## 每日流程
### 1. 取数
```bash
# 若快照当天还没生成(cron 未跑或失败),先补一次
bun run control-server/src/evidmon_daily.ts
```
然后读取:
- `GET /api/evidmon/metrics?days=30` — 指标树当前值 + 历史快照
- `GET /api/evidmon/findings` — 既有研究日志、全部策略、已生效策略的实测效果
- `GET /api/evidmon/events?sinceDays=2` — 近两日原始事件(用于定位具体样本)
分析任务用 `x-cluster-secret` 头认证。**它能写发现、不能批准策略**——批准路由要求
SSO 登录身份,这是刻意的:提出和批准必须分开。
### 2. 看什么
按这个顺序过,先看尺子准不准,再看量出来的数:
1. **L1-E 判定精度** — 它低,上面所有指标都是用弯尺量的。先修它。
2. **指标树里发生了变化的项** — 对照上一篇的 deltas,只关注变化 ≥1% 且样本足够的。
3. **昨日新增的 fail / warn 样本** — 逐个看 probe:是真坏,还是判据误伤?
4. **skip 理由** — 这是最富信息的字段。新出现的阻塞类型往往指向一条能力型策略。
5. **已生效策略的实测效果** — 有没有出现"批准了但指标没动",或者更糟,"动反了"。
### 3. 写发现的标准
一条发现必须包含:
- **evidence** — 引用真实数字和具体产物名。写「12 条 static 打在了 25–108fps 的真实
录制上」,不要写「静态检测不太准」。
- **rootCause** — 定位到代码或机制。写不出根因说明还没查透,那就先标记为待查,不要
用形容词补位。
- **metricKey** — 这条发现对应指标树里的哪一项。对不上任何指标,通常意味着指标树缺了
一维,这本身就是一条发现。
**样本量纪律**:每天只有约 20–40 次采集,视频只有 ~5 次。所以:
- 视频类指标用 14 天窗口,不看单日
- 分母 <8 的比率不下结论,面板会自动标「样本不足」
- 宁可写「样本尚不足以判断,继续观察」,也不要把噪声讲成趋势
### 4. 提策略的标准
每条策略必须能回答四个问题:
| 问题 | 落在哪个字段 |
|---|---|
| 改什么 | `title` + `payload` |
| 为什么(证据是什么) | `rationale` |
| 用哪个指标验收 | `metricKey` + `baselineValue` + `targetValue` |
| 怎么生效、怎么回滚 | `knob` |
四类 knob:
- **criteria** — 阈值与规则。批准即生效,可一键回滚到任一历史版本。
**必须附回放结果**(见下)。
- **collector** — record-evidence 的行为。需发版到节点。
- **prompt** — 采集引导话术。
- **capability** — 能力/环境工程项(采集后端、账号池、构建健康)。
### 5. 判据类策略必须先回放
判据变更不需要等新数据来验证——历史采集的完整 ffprobe 结果都在库里,而
`evaluateCapture` 是纯函数,所以新判据可以对全部历史样本重跑:
```
POST /api/evidmon/criteria/replay
{ "criteria": { ...CaptureCriteria 的差异字段... }, "days": 30 }
```
返回收紧/放松了多少条、每个 issue code 的增减、以及每一条判定翻转的样本(带时长、
有效帧率、码率,便于人工抽查)。把整个 `ReplayResult` 放进策略的 `replay` 字段,面板
会渲染成生效前后对照。
**这意味着判据类策略的效果在批准前就是已知的,不是预期。** 提这类策略时不要写
"预计能降低误报",直接写回放跑出来的确定结果。
回放时要留意的陷阱:
- 拼接产物(`compose`)是重编码的,码率天然低一个数量级,不能套原生录屏的码率下限
- `r_frame_rate` 不可用(大量样本返回 90000 时基),活性要用 `nb_frames / duration`
- 一个判据同时收紧和放松是正常的;要分别检查两侧的样本是否都合理
### 6. 写入
```
POST /api/evidmon/findings
{
"id": "YYYY-MM-DD", "day": "YYYY-MM-DD",
"title": "...", "summary": "...",
"highlights": ["..."],
"findings": [{ "code": "P1", "title": "...", "severity": "critical",
"evidence": "...", "rootCause": "...", "metricKey": "..." }],
"strategies": [{ "id": "YYYY-MM-DD-S1", "code": "S1", "title": "...",
"rationale": "...", "knob": "criteria", "metricKey": "...",
"baselineValue": 0.538, "targetValue": 0.9,
"payload": { "criteria": {...}, "label": "v3-..." },
"replay": { ...ReplayResult... } }]
}
```
同 id 重复写入是覆盖(便于当天修订),但**已决策的策略不会被重新提案覆盖**——
批准/驳回是终态。
### 7. 没有新发现的日子
不要为了填日志而写。指标平稳、无新样本时,写一条短条目说明「本日无显著变化,
样本量 N」即可,不提策略。虚构的发现会污染日志作为决策依据的价值。
---
## 前后对比是怎么算的
- `effectiveAt` 在**批准的那一刻**盖章,不能事后挑窗口
- 对比取生效前 7 个快照 vs 生效后 7 个快照的**均值**,不是单日读数——避免一个安静的
日子主导结论
- 样本量随结论一起显示;任一侧天数 <2 或样本 <20 时标记为不可靠
- 判据类策略额外有回放对照,那个是即时且无风险的
---
## 边界
- 分析任务**不批准任何东西**。它只提出。
- 分析任务**不改代码**。策略里写清楚改什么,由人执行。
- 判据是唯一可以「批准即生效」的抓手,因为它可版本化、可回放、可一键回滚。
其他抓手都要走正常的发版流程。
+48
View File
@@ -0,0 +1,48 @@
# 外部链接(飞书文档 / Figma)
任务描述里的飞书文档、Figma 链接由 `shared/src/external_links.ts` 识别,执行时 agent 通过节点上配置的 MCP 读取。
节点能读什么由卫星从自己的 MCP 配置推出来、随心跳上报(`satellite/src/capabilities.ts`,面板健康页可见)。
## Figma:按提交人的 Token 读设计稿
每个节点在 MCP 配置里有一把自己的 Figma Token,过去所有 agent 都用它,节点账号打不开的稿子就读不到。
现在提交人可以在面板头像菜单 →「Figma Token」绑定自己的 Personal access token(服务端先用 `GET /v1/me` 验过才存)。
卫星起 agent 时向控制面要**任务创建人**的 Token(`/api/internal/figma/user-token`),放进该子进程的 `FIGMA_API_KEY`;
创建人没绑、或 Token 已被 Figma 拒绝,就什么都不注入,用节点 Token,和以前一样。不会退到别人的 Token。
开放平台建的单,「创建人」是建单那把 Key 的申请人(接口不收提交人,见 `docs/openapi.md`「归属与安全」)。
### 节点需要的一次性改动
Claude Code 会把父进程的环境变量传给 stdio MCP server,但 MCP 配置里**写死的值优先于父进程**。
所以节点要把 Figma MCP 改成「父进程有值就用父进程的,没有才用节点 Token」。2026-10-16 实测(Claude Code 2.1.301):
| `env` 块里的 `FIGMA_API_KEY` | 父进程有值时 server 拿到 |
|---|---|
| 不写 | 父进程的值 |
| 字面量 `"figd_…"` | 字面量(用户 Token 失效) |
| `"${FIGMA_API_KEY:-figd_…}"` | 父进程的值;父进程没有时取默认值 |
按节点的配置方式二选一:
- **包装脚本**(例如脚本从 Keychain 取 Token 再 `exec` Framelink):脚本里不要无条件赋值,改成
```bash
FIGMA_API_KEY="${FIGMA_API_KEY:-$(security find-generic-password -a "$USER" -s figma-api-key -w 2>/dev/null)}"
export FIGMA_API_KEY
```
- **`.mcp.json` / `~/.claude.json` 里写死了值**:
```json
"env": { "FIGMA_API_KEY": "${FIGMA_API_KEY:-figd_<节点 Token>}" }
```
args 里用了 `--figma-api-key=<值>` 的同理,改成 `--figma-api-key=${FIGMA_API_KEY:-<节点 Token>}` 或去掉该参数改走 env。
卫星不改这些文件(同 DeviceSim skill 的规矩:节点自己维护配置)。不改的节点行为不变,继续用节点 Token。
改完后自己确认一次:用一份只有你能打开的稿子建单,绑定前 agent 拿到 403,绑定后能读。
### 风险
Token 放在 agent 的环境里,agent 运行期间可以用 shell 读到它。绑定时请只给 `file_content:read` 和 `current_user:read`(后者只用来验证 Token 并显示是谁的)、有效期选短,过期后重新绑定。
目前只覆盖 `AGENT_MODE=claude`;codex / cursor 模式从各自的配置加载 MCP,不经过这条路径。
+79
View File
@@ -0,0 +1,79 @@
# Ideas 墙
大家愿意公开的「想法 demo」:Pinterest / Mobbin 式多列卡片,直接看 demo 效果,点开可以点赞、分享、接力。
类型和校验规则在 `shared/src/ideas.ts`,存储在 `ideas` / `idea_likes` / `feature_relays`(`drizzle/0071_ideas.sql`)和 `idea_comments` / `idea_stamps`(`drizzle/0072_idea_comments_stamps.sql`)。
## 来源与发布
| 来源 | 谁能发布 | 怎么发布 |
|---|---|---|
| Feature / Bug | 任何登录的人(包括别人的单) | 详情页右下「新增修改」左边的「发布到 Ideas」,证据里的截图 / 录屏默认全选(录屏在前,≤ 9 个) |
| Eddy | 任何登录的人(上传人即作者) | Ideas 页右上「上传 Eddy 想法」:先拖入 Eddy 导出的分享包(必传;Mac 版 Eddy「分享」导出的 `.eddy`,或命令行导出的 `.eddy.zip`),浏览器读出标题 / 说明 / 平台 / 包内截图,确认后上传 |
- **入口只在 Feature 上出现**:Bug / Security / 原型 / 验证的抽屉右下角没有「发布到 Ideas」,判定集中在
`control-web/src/lib/ideas.ts::canPublishToIdeas`(`control-web/test/ideasPublishGate.test.ts` 锁住)。
Bug 是缺陷单,不是「想法」;历史已经发布过的 Bug 想法仍留在墙上,能看能移除。
`POST /api/ideas` 仍接受 `source: "bug"`(兼容存量数据 / 脚本),但 UI 不再产出新的。
- **作者**:原单主人(第一个邮箱关注人;存量 Bug 没有时取 QA),**不是**发布人;同一张单再发布 = 更新,作者不变。
- **移除**:作者、发布人或管理员可以从 Ideas 移除(只删这一条,原单 / Eddy 任务不受影响)。
- Eddy 包的解析在 `shared/src/eddy_share.ts`(浏览器和控制面共用,无 zip 依赖)。
- **文件名**:`.eddy`、`.eddy.zip`、`.zip` 都收,内容是同一种 zip(`eddy-task-share`)。Mac 版 Eddy 导出 `.eddy` 是为了双击能直接用 Eddy 打开。
判断文件名统一用 `eddyShareExt` / `isEddyShareName` / `eddyShareBaseName`,不要在组件里另写正则。
- **说明**依次取:`share.json` 的 `description` / `summary` → `changes.text`(Eddy 导出时写的改动说明)里「改了什么」一节,去掉 Markdown 记号
→ `instructions`(发送者填的体验说明)→ 补丁脚本首行注释。最长 2000 字,确认页可以再改。
- **截图 / 录屏**:新版 Eddy 导出时可以带上做原型时截的图和录的屏(发送者在分享卡上逐个勾选),放在包里 `assets/media/<sha>/<名字>`,
`share.json` 的 `media`(`[{path, kind: screenshot|recording, name, bytes}]`)列着它们:有这个清单就只按它取,截图在前,
第一张截图当封面,录屏排后面,最多 9 个;清单为空就是发送者一个都没勾。没有 `media` 的旧包照旧扫 `assets/` 以外的图片视频
(Eddy 旧包里一般没有,确认页要手动加)。包里其余 `assets/` 下的图片是任务替换进 App 的资源,不当演示截图。
## 接力
| | Feature 想法 | Bug 想法(仅存量) | Eddy 想法 |
|---|---|---|---|
| **Streamline 接力**(主) | 复制一张到接力人名下:baseRef = 源单已推送的分支,remark 带源单需求 / 方案 / 实现报告 / 复核反馈 + 接力人这次想改的 | 打开原单 | 新建一张 Feature,按原型效果在代码仓正式实现,remark 带 Eddy 包里的补丁脚本当挂点参考 |
| **Eddy 接力**(次) | iOS Feature:准备 Eddy 接力包 | — | 下载作者上传的 Eddy 包(文件名是想法标题,扩展名和上传时一样) |
Streamline 接力出来的新单走正常流程:评估 → **待确认计划**(不自动执行)→ 确认后执行出新 MR。
Feature 接力的新 MR 默认合进源单分支(叠在对方结果上)。逻辑在 `control-server/src/feature_relay.ts`。
**来源链路**:每次接力在 `feature_relays` 记一跳(新单 ← 谁的第几版 / 哪个 Eddy 原型)。新单详情的关注人处显示完整链路,
源头在前,例如「Eddy 原型 · A → B 第 2 版 → 你接力(当前)」,节点可点回对应的单 / 想法;多人多次接力一节一节串下去(最多追 20 跳)。
## 评论与审阅章
- **评论**:卡片和详情里点赞左边的评论按钮;详情里有评论区,最新的在最上面,回车发送,评论人自己或管理员可删。
- **审阅章**(`control-web/src/components/IdeaStamps.tsx`):详情弹窗右侧一列 PASS / CONDITIONAL PASS / NO PASS。点章拿起(跟随鼠标、带投影),
在弹窗上左键按下 → 压下、抖动、印上,章飞回章架;右键 / Esc 松手放回。每人每条只留一个章,再盖替换旧的;
所有人可见,平时 40% 不透明度,悬停 100% 并显示谁、什么时候盖的。**NO PASS / CONDITIONAL PASS 必须写原因**:
按下时先弹原因框,原因以「【NO PASS】…」发成评论后才盖下去,服务端也校验盖章人在这条下留过评论。
## 接口
浏览器(SSO):
- `GET /api/ideas` → `{ ideas: Idea[] }`,新的在前;每条带 `likes` / `liked` / `likedBy`(最近 8 个点赞人)。
- `POST /api/ideas` `{ source: "feature"|"bug", sourceId, title, summary?, media: [{type, url}], platform? }` → `{ idea }`。
面板只会发 `feature`;`bug` 保留给存量数据 / 脚本,新 UI 不再产生。
`media.url` 只收站内 `/api/...` 地址或 TOS 下载地址。
- `DELETE /api/ideas/:id` —— 从 Ideas 移除。
- `PUT` / `DELETE /api/ideas/:id/like` —— 点赞 / 取消 → `{ likes, liked, likedBy }`。
- `GET /api/ideas/:id/likes` → `{ likes: [{ email, at }] }`,全部点赞人和时间。
- `GET` / `POST /api/ideas/:id/comments` `{ text }`、`DELETE /api/ideas/:id/comments/:cid` —— 评论。列表里每条想法带 `comments`(条数)。
- `GET /api/ideas/:id/stamps`、`PUT /api/ideas/:id/stamps` `{ kind: "pass"|"cond"|"nopass", x, y, rot }`、`DELETE /api/ideas/:id/stamps` —— 审阅章。
- `POST /api/ideas/:id/relay` `{ note? }` → `{ feature }` —— Streamline 接力。
- `GET /api/ideas/relay-of/:featureId` → `{ chain }` —— 这张单的接力链路(源头在前,不是接力来的为空)。
- `POST /api/ideas/upload`(multipart):字段 `title`(必填)、`summary`、`platform`;文件 `media`(≥ 1,单个 ≤ 60 MB)、
`bundle`(Eddy 分享包,`.eddy` / `.eddy.zip`,**必传**,≤ 300 MB)。服务端转存 TOS 的 `ideas/<ideaId>/`,不看扩展名。
- `GET /api/ideas/:id/bundle` —— 下载这条 Eddy 想法的包(「Eddy 接力」用)。从 TOS 转一手,文件名给成「想法标题 + 上传时的扩展名」
(TOS 上的对象名只留 ASCII,中文标题直链下载会变成 `eddy-_.eddy`);取不到时 302 回 TOS 直链。
分享链接:`/ideas?id=<ideaId>` 落到 Ideas 页并展开那条详情。
## 本地体验
`?mock=1` 下 Ideas 墙用线上真实已完成单的证据(只读 TOS 镜像)+ 几条 Eddy 演示;发布 / 移除 / 点赞 / 接力只改浏览器本地,不碰线上写接口。
上传弹窗在 mock 下有「用示例包直接看确认页」。
## 部署
新表:**先跑 `0071_ideas.sql`(已上线)和 `0072_idea_comments_stamps.sql` 再上代码**(只建表、不动已有表;反过来只有 Ideas 页报错,不影响看板)。上传依赖 TOS 凭据(和证据镜像同一套)。
+201
View File
@@ -0,0 +1,201 @@
# 复现知识库 · Phase C:检索与注入
> 状态:**已上线;2026-08-21 重做过一版检索策略,2026-09-02 又补了「拉」和「归因」两条腿**。
> 下面按时间倒序:先是 2026-09-02 这次的依据与改动,再是 08-21 那次,最后是最初的设计,
> 都保留原样 —— 它们哪里判断错了,对下一次改动比它们哪里对了更有用。
## 2026-09-02:上线 12 天的实测,以及照着它改的四件事
08-21 那版的效果是真的(条目级引用率 3.6% → 40.9%),但同一批数据也把三个新问题
摆了出来。三条都不是调参能解决的,所以这次改的是结构。
### 实测(strategyAt = 2026-08-21 17:14,至今 12 天;分母是「回报过 KB_USED 的注入」)
| | 注入次数 | 每次条数 | 条目级引用率 |
|---|---|---|---|
| eval · 改版前 | 646 | 9.7 | **5.0%**(97 / 1958) |
| eval · 改版后 | 321 | 6.6 | **47.7%**(751 / 1575) |
| fix · 改版后(新开的) | 614 | 6.0 | **37.5%**(1263 / 3366) |
按 kind(改版后):env **43.2%**(1947/4508)· account 31.3% · pitfall 22.3% ·
entry_path **8.9%**(7/79)· experiment **0/89** · tricky 0/6。
fix 阶段 614 次注入里 561 次回报了 `KB_USED`,338 次(60%)至少用上一条。
### 三个问题,以及它们各自的证据
**① 归因回环仍然是开的。** 全部 1634 次注入:inconclusive 731 · contradicted 5 ·
confirmed 3 · 待判 895。改版后已评分的 350 次里只有 8 次不是 inconclusive。
不是缺证据 —— fix 注入覆盖 265 个 target,其中 **248 个有 verified 的 `run_conditions`**,
这些 target 上光 `env` 类就有 520 条真机确证条件,而 fix 注入的又几乎全是 env。
卡在 `matchStrength` 的主题相似度门槛上:把精确 key 相等换成分级匹配只把命中率从
0/381 抬到 8/350。**跨月、跨节点、各自随手写的 subject 和 statement,事后是配不回去的。**
**② 待判队列在结构上排不空。** 404 个待判 target 里 **214 个永远不可能被评分**
(一条 verified 条件都没有,`attributeTarget` 返回空、`outcome` 留 NULL),
而 sweep 每天只扫 100 个、**无排序无水位** —— 于是每天的预算被这批不可评分的吃掉,
真的能判的排在后面永远轮不到。
**③ 产品面知识在「推」这条路上不可能命中。** entry_path 展示 79 次引用 7 次、
experiment 展示 89 次引用 0 次。工单标题是在**任何人看到那个页面之前**写下的,
拿它去匹配入口路径,匹配到的是对的**模块**、错的**事实**。
### 改了什么
| # | 改动 | 落点 |
|---|---|---|
| ① | **让 agent 直接写下配对**:`conditions record --kb K1`,归因优先用显式关联,模糊匹配退为兜底 | `bin/conditions.ts`、`run_conditions.kb_labels`、`kb_outcome.ts::explicitLinks` |
| ② | **待判队列加水位和退出**:超过 7 天仍无任何真机确证条件的注入判为 `unscoreable`;sweep 按最早注入时间排序 | `kb_outcome.ts::sweepPendingAttribution` |
| ③ | **执行期可以反过来拉**:`kb recall --target bug:<id> "<问题>"`,命中项接着现有 K 编号往下排、并入同一份注入清单 | `bin/kb.ts`、`kb_retrieval.ts::recallClaims`、`POST /api/internal/kb/recall` |
| ④ | **产品面知识不再硬推**(`KB_INJECT_SPECIFIC_K` 默认 0),改由 recall 按真实问题检索 | `kb_retrieval.ts::SPECIFIC_K` |
四条是一件事的两半:**派发时推「不管什么单子都成立」的常驻知识,执行期拉「只有当下才知道要什么」的产品面知识**;
而两边用的是同一套 K 编号、同一行 `KB_USED:`、同一条归因路径,所以效果仍然是一个数能说清的。
### 三条必须守住的边界
1. **`--kb` 记录的是关联,不是判定。** agent 说「这条条件讲的是 K1」,
对不对由控制面拿 `--statement` 去比 —— 否则就是让模型给模型的知识投票,
`docs/rsi.md` 那条底线(真值只认执行结果)当场破掉。
2. **编号只在执行阶段解析。** eval 的 K1 和 agent 看到的 K1 不是同一条知识,
越界编号一律丢弃、同编号先写者胜(否则 ingest 顺序能翻转判定)。
3. **`unscoreable` 不是判定,是退出。** 它跟 `inconclusive` 分开计:
「看过了没配上」和「压根没东西可看」要修的是完全不同的两处
(前者是匹配规则,后者是记录纪律)。
---
## 2026-08-21 那次:上线后的实测
三周生产数据(688 次注入、200 次带引用回报):
| 观察 | 数值 |
|---|---|
| 条目级引用率 | **3.6%**(106 / 2973) |
| 撞满 K=10 上限的注入 | **649 / 688** |
| 按 kind 的引用率 | env 11.6% · account 6.0% · pitfall 4.4% · experiment 1.1% · tricky 0.9% · **entry_path 0.5%** |
| 跨任务复用过的 claim | **7 / 3748** |
| 已核实条件里 subject 在第二个任务再出现过的 | **9 / 3595** |
| 归因回环闭合过几次 | **0**(49,483 对比对,精确配对命中 0) |
两个结论,都跟原设计的假设相反:
1. **这个库当时几乎是一次性的。** 每条知识只在它诞生的那个任务里成立过一次。
对这样的语料做检索不是检索,是抽样 —— 起草者用 3.6% 的引用率把这件事说清楚了。
2. **文本相关性预测不了采纳。** 被引用与被忽略的知识,相关性均值 0.149 / 0.147,
每一类都如此。照相关性排反而比原来的按置信度排更差(MRR 0.275 vs 0.410)。
原因在读一眼被引用的内容就清楚了:"airb 远端是共享池"、"这个 inhouse 包首启会卡在
Feishu 验证" —— 它们跟工单写了什么无关,是关于**这台机器**的常驻知识,
而这正是唯一会复用的那部分。
## 重做后的四条策略
| # | 策略 | 落点 |
|---|---|---|
| ① | **分层**:episodic(只当证据)/ semantic(可检索)。凭出身(env/account、人工录入)或凭本事(被第二个任务见证、被起草者引用)晋升 | `kb_claims.tier`、`kb_db.ts::earnsSemanticTier` |
| ② | **两个检索池**:常驻知识按平台 + 历史表现选,不要求命中工单词;产品面知识(entry_path/experiment)才做文本匹配并设相关性下限,允许一条都不注 | `kb_retrieval.ts::STANDING_KINDS / retrieveClaims` |
| ③ | **有用度回流**:`injected_count` / `cited_count` 直接进排序权重 | `kb_retrieval.ts::usefulnessFactor` |
| ④ | **执行阶段也注入**(只 env/tricky/pitfall)+ 归因配对规则重写 | `routes.ts::FIX_STAGE_KINDS`、`kb_outcome.ts::matchStrength` |
## 效果(同一批历史注入回放,`bun scripts/kb_rank_replay.ts`)
- 每次注入 **9.9 → 3.3 条**(−67%),而被起草者引用过的知识 **99% 仍在注入里**;
- 排序 MRR **0.410 → 0.548**,被引用知识平均名次 3.41 → 3.24,前 3 条命中 57% → 59%;
- 可检索知识 3748 → 约三分之一,其余留库作证据。
回放是**前序式**的:给第 N 次注入打分时,有用度先验只看第 1..N-1 次的引用 ——
否则就是拿正在被预测的那次引用去预测它自己。面板「知识库蒸馏 › 效果」用的是同一段代码
(`kb_effectiveness.ts::replayRanking`),命令行和面板算出两套数字是这类度量最常见的烂尾方式。
---
## 1. 检索
### 第一版:不上向量库
`kb_claims` 已有 `embedding` 列但**先别用**。第一版走关键词 + 结构化字段的混合检索:
- Postgres `pg_trgm` 扩展,对 `statement` / `scope_label` / `subject_key` 建 GIN 索引
- 查询词从 task 的 `title` + `description` + `reproSteps` 抽取
- 硬过滤:`platform` 匹配(或 NULL)、`status = 'active'`
- 排序:`confidence × trgm 相似度`,取 Top-K
```sql
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX kb_claims_statement_trgm ON kb_claims USING gin (statement gin_trgm_ops);
CREATE INDEX kb_claims_scope_trgm ON kb_claims USING gin (scope_label gin_trgm_ops);
```
**K ≈ 8-12,渲染后正文 ≤ 2000 字。** 注入长度必须有硬上限:prompt 里每多一段"参考资料",模型对「铁律」和 NEEDS_INPUT 哨兵纪律的遵守度就掉一点,这个 tradeoff 是真实的。
### 第二版:语义检索
trgm 对「Story 相机」vs「故事拍摄页」这类同义表述无能为力(`normalizeKey` 也不行,见 `kb_arbitration.ts` 的注释)。届时:写入时算 embedding 存进 `kb_claims.embedding`,检索改成 `向量相似度 × confidence`,trgm 保留为召回补充。
---
## 2. 注入点(三处)
| 位置 | 文件 | 注入什么 |
|---|---|---|
| 评估器首轮 | `satellite/src/evaluator.ts` · `buildEvalPrompt` | 全部 kind —— 这是核心诉求,让首版 TestSpec 就带上正确的复现条件 |
| 评估器重生成 | `satellite/src/evaluator.ts` · `buildRegenPrompt` | 同上 |
| 修复执行器 | `satellite/src/runner.ts` · `buildSinglePrompt` | 只注 `tricky` / `env` / `pitfall` —— 构建命令、mock、必须冷启动之类,减少执行期踩坑 |
知识由**控制面**在派发时查好并随 Task 下发(控制面拥有 DB;卫星不该反向查库)。渲染格式:
```
## 已验证的历史复现知识(参考,非权威)
- [置信 0.87 · 最近验证 2026-07-10 · 源自 meego 7328764565] Story 相机:进入特效面板的路径是 我的 → 右上角三点 → 设置 → 隐私 → 故事
- [置信 0.62 · 最近验证 2026-05-02 · 源自 meego 7301120088] Story 相机:需开启 abid 7712334 才能看到特效入口
```
### 注入即 hint,不是 fact
prompt 里必须写死两条,否则这套东西会从"提高准确率"变成"系统化地传播错误":
1. **与代码调研冲突时以代码为准。** 知识库记录的是过去某次执行时的事实,代码是现在的事实。
2. **引用了哪条就在该位置标注来源。** 这不是为了好看 —— 它是下面命中率统计的唯一数据来源。
现有的「铁律」和 NEEDS_INPUT 哨兵机制**完全不变**:知识库里有,不等于可以不验证。评估器仍然必须对拿不准的内容打哨兵。
---
## 3. 注入 → 验证回环(`kb_injections`)
这是让知识库自我纠错的第二条腿(第一条是蒸馏时的仲裁,见 `kb_db.ts` 的 `arbitrate`)。
1. 评估/派发时,把注入的 `claimIds` 写一行 `kb_injections`(`stage` = eval / regen / fix);
2. 该 task 执行结束后回看:
- 产生了**针对某条注入 claim 的 SpecDelta** → 说明注进去的知识是错的 → 给该 claim 记一条 `refute` 证据;
- 没有相关 delta 且执行成功 → 记一条 `support` 证据;
3. 回填 `kb_injections.outcome` / `evaluated_at`。
匹配「SpecDelta 是否针对某条 claim」用与仲裁同一套 `(scopeKey, subjectKey, kind)` 对齐 + `claimsEquivalent`,不要另造一套 —— 两套判等规则一旦不一致,回环就会开始随机地奖惩知识。
**效果**:知识不只在蒸馏时更新,**每次被用到都在被执行器重新验证一遍**。这正是"执行器是验证器"这条原则的完整形态。
---
## 4. 效果度量
上线注入的同时必须能回答"它到底有没有用"。按**有无注入**分组对比(同期任务随机分流,或先按 scope 灰度):
| 指标 | 取数位置 | 预期方向 |
|---|---|---|
| 首版 TestSpec 的 NEEDS_INPUT 哨兵数 | 解析 `tasks.executionPlan` | ↓ |
| `pending_confirmation` 人工批注轮次 | `tasks.regenContext` 的重生成次数 | ↓ |
| 首轮复现成功率 | `unreproducible` 占比 | ↑ |
| 每任务 SpecDelta 条数 | `spec_delta_events` | ↓(spec 一开始就更准) |
| 注入命中率 | 生成文本里的来源标注 ÷ 注入条数 | 观测项,判断 K 值和检索质量 |
**注入条数 ↓ 而 SpecDelta 条数不降**,说明检索召回不行;**SpecDelta 降但 unreproducible 不降**,说明知识被采纳了但采纳的是错的 —— 这两种情况都要回到仲裁规则去查。
---
## 5. 上线前的前置条件
- [ ] `spec_delta_events` 里累计 ≥ 数十个任务的真实数据
- [ ] 「未声明率」(见看板 `undeclaredRate`)稳定在低位 —— 高说明采集在漏,注入会把漏掉的错误固化下来
- [ ] 人工抽查过一批 `kb_claims`,确认 scope / subject 的归一化没有把不同的事混成一桶(或把同一件事拆成多桶)
- [ ] 至少出现过一次**真实的自动 supersede**,并人工确认它覆盖对了 —— 这是整个自我纠错机制唯一的实战证据
+235
View File
@@ -0,0 +1,235 @@
# 开放平台 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`
+124
View File
@@ -0,0 +1,124 @@
# Product profiles
Management → **Products & branches** configures product profiles for Bug and Feature tasks. Only admins may save settings.
**TikTok** is the built-in default (branch `develop` on both platforms). Creating a task selects TikTok unless the user picks another enabled product. Lemon8 and Notes start as disabled drafts; verify the remote branches and Bits configuration before enabling them.
The create dialog’s More options lists **Product profile** above **Custom branch**. Picking a non-default product fills Custom branch once with that product’s base branch; the user can still edit it afterwards. Each profile option is `id (repo path)`. A snapshot of the selected product is stored on the task for display; execution follows Custom branch (the same `baseRef` path Bug already used).
| Draft | Platform | Repository | Base / requested target |
| --- | --- | --- | --- |
| TikTok (default, enabled) | iOS | ugc/TikTok | develop |
| TikTok (default, enabled) | Android | ugc-android/TikTok | develop |
| Lemon8 | iOS | ugc/TikTok | lemon8/develop |
| Lemon8 | Android | ugc-android/TikTok | develop |
| Notes | iOS | ugc/TikTok | notes/develop |
| Notes | Android | ugc-android/TikTok | notes/develop |
These targets are proposed request values, not verified Bits final-target mappings. Bits can rewrite the target through its own workflow.
## Compatibility and scope
- TikTok (or an omitted `productProfileId`) retains legacy behavior, including independent node/control-plane `BASE_BRANCH` defaults. Old satellites can still claim TikTok tasks. No profile is inferred from task text or KB context.
- Selection resolves after platform classification. Meego platform metadata still wins over the creation dialog's platform button. A bulk import uses one settings revision; unsupported-platform tickets are returned in `skipped`.
- Tasks store a server-authored `productProfile` snapshot in `tasks.product_profile` / `features.product_profile`. Later management edits, disabling the product and satellite updates cannot rewrite it. A newly created cross-platform port resolves the same product ID for its destination platform from current enabled settings; it fails explicitly if unavailable.
- Custom branch is `baseRef` on both Bug and Feature. An explicit value always wins. A non-default product fills it at create time when the caller left it empty. Empty still means trunk `develop`. `baseRef` only decides where the fix branch is cut from and where the MR points — merges always go through Bits; the executor merge-back that used to run on approval (2026-10-26) is gone.
- Sidecar repositories retain their registry-owned defaults, including `tt_im_monorepo` → `master`. They do not inherit the client product's branches.
- Only the already registered iOS/Android delivery repositories are selectable. Adding arbitrary repositories, changing GitLab/Bits identities, credentials, checkout paths or deployment pools is not part of this form.
- Non-default (Lemon8 / Notes) tasks still require satellites that advertise `productProfilesVersion: 1`. Those nodes verify the exact repository origin and fetch the configured remote branches before a profiled run. Failure does not fall back to another product's checkout.
## Product prompt
Each product × platform has an optional **Product prompt** textarea (≤ 8000 characters) in Management → Products & branches. Use it for facts the default prompts and the node workspace get wrong for this product: the app under test and its package name, the build command, usable accounts, known pitfalls.
- **Where it lands.** At dispatch the control plane appends it, under a `## 产品定制说明(<product> · <platform>)` heading that states it overrides conflicting defaults, to the end of the Bug / Feature main prompts: `eval` / `regen`, `feature.eval` / `feature.regen`, `bug.run`, `feature.run.first` / `feature.run.second`. Not `bug.critic`, and not security / prototype / verification yet. RSI lab reruns keep their own wording.
- **Which text.** Looked up from the *current* settings by the task's snapshot `profileId` and platform, so an edit applies to everything not yet claimed — it is deliberately not part of the write-once snapshot. A task without a snapshot (no product chosen at create) uses the default product, TikTok. A disabled product still supplies its text to tasks already created under it.
- **No satellite upgrade.** Prompt bodies already ride down with the work item, so the control plane edits the text it sends; older satellite bundles pick it up as is. `{{` / `}}` in the text are split so node-side variable substitution cannot touch it.
- **Visibility.** Only the admin endpoints return it; `GET /api/product-profiles` and the open-platform view strip it.
- **This is the one prompt that does not live in code** (see `CLAUDE.md` → 改 prompt). It has no git history: the settings row keeps only the latest revision. Keep stage wording in `shared/src/*_prompt.ts`; put only product facts here.
## API
`GET /api/product-profiles` exposes enabled profiles (TikTok is present by default). `GET /api/admin/product-profiles` includes drafts; `PUT /api/admin/product-profiles` accepts `{ revision, profiles }`. Saves validate repository/platform compatibility and branch syntax; optimistic revision conflicts return 409. Storage is one versioned settings row (`product_profiles_v1`), with no boot-time seed writes.
Creation endpoints accept optional `productProfileId` (default TikTok in the UI) and optional `baseRef` (Custom branch), e.g. `"notes"`: `/api/import`, `/api/features`, `/api/openapi/tasks`, and the open-platform v1 creation endpoints (`/meego-import`, `/tasks`, `/features`; on v1 an invalid branch name is a 400, see `docs/openapi.md`). Callers send an ID, not their own snapshot. Existing deduplication still returns the existing task without changing its configuration.
`GET /api/product-profiles` is the console's own shape: it is unauthenticated on the panel host but it is not a versioned contract for external integrators. Those callers get a purpose-built, API-key-authenticated view of the same selectable set, from the same source and with the same enabled-only filter, at `GET /api/openapi/v1/product-profiles`. That response adds `defaultProfileId` and renders each platform's registered `repoPath` (the console shows `id (repo path)`) instead of `repoKey`, and omits `enabled` because only enabled profiles are returned. The task view (`GET /api/openapi/v1/tasks[/:id]`) and the feature view (`GET /api/openapi/v1/features[/:id]`) echo `productProfileId` / `productProfileName` from the stored snapshot, so a caller can confirm the selection took effect (`null` = omitted at create, i.e. no snapshot and the trunk default applies).
Omitting `productProfileId` is not byte-for-byte the same as sending `tiktok`: an omitted value stores no snapshot and follows the node/control-plane trunk default (`BASE_BRANCH`), while an explicit profile follows the profile's configured `baseBranch`. They agree only while the default product still points at `develop`. See `docs/openapi.md` for the open-platform surface.
## Rollout (not performed by this change)
1. Apply `drizzle/0023_product_profiles.sql` before deploying the new control plane (nullable columns, no backfill). The migration also adds `features.base_ref`.
2. Deploy control plane and web. Keep Lemon8 / Notes drafts disabled while verifying configuration. TikTok is already enabled.
3. Upgrade the intended iOS/Android satellites before enabling Lemon8 / Notes. Their claim requests advertise `productProfilesVersion: 1`; older nodes are SQL-filtered out of **non-TikTok** profiled tasks only. TikTok / unprofiled work still runs on older nodes.
4. Verify repository access, base and requested target branches, the product build environment and actual Bits target mapping. Enable a profile and try one task in the intended pool before broader use.
### Operator checklist
The deployment script **checks** migrations but does not apply them. After the
merged code is available in the deployment checkout, and before restarting the
control plane, the authorized operator runs the existing migration workflow:
```sh
bun scripts/apply-migration.ts drizzle/0023_product_profiles.sql
# Only after reviewing the dry run and approving the production schema change:
bun scripts/apply-migration.ts drizzle/0023_product_profiles.sql --commit
bun scripts/check-migrations.ts
```
Run these in the configured deployment environment as its repository owner;
do not copy production credentials into a local development shell. The migration
adds nullable text columns only, is idempotent, and needs no historical backfill.
Allow for PostgreSQL's brief ALTER TABLE lock when scheduling it.
Then use `.claude/skills/streamline-deploy/deploy.sh` for the normal control-plane,
web and satellite deployment. `bun run build` alone does not rebuild satellites.
The deployment script's default satellite scope is the `default` pool: separately
coordinate upgrades for any other pool that will run Lemon8 / Notes. Do not
force-restart busy nodes; queued or offline nodes have not adopted the new
capability until they actually restart and claim with `productProfilesVersion: 1`.
Before enabling a non-default profile, confirm the node's `TikTok` checkout origin matches
the configured registered repository, both remote branches exist and are
fetchable, and isolated evaluation worktrees are enabled (`EVAL_WORKTREE` must
not be `0`). Verify the product-specific build/device setup and Bits' final
target mapping with an authorized canary. No new secret or global `BASE_BRANCH`
change is required by this MR; repository registration, credentials and Bits
integration remain outside the management form. No active prompt version needs
to be edited: Custom branch uses the same first-run note Bug already injects.
Rollback: disable non-default profiles to stop new opt-ins. Existing snapshots remain intact. Do not roll the control plane back to a version without claim gating while non-TikTok profiled tasks are queued.
## Verification
Run `bun run typecheck`, `bun run build`, and `bun run test`. The ordinary suite never requires a database. For DB integration, create an isolated local database **named `streamline_profiles_test`**, apply the schema, then point both `TEST_DATABASE_URL` and `PRODUCT_PROFILES_TEST_DATABASE_URL` at it and run `bun test control-server/test/product_profiles_pg.test.ts`. The test rejects non-local or differently named databases and stubs all external HTTP requests.
For manual UI verification, start Vite with `API_TARGET=http://127.0.0.1:1` and open `/test/fixtures/product-profiles.html`. This renders the real Management/ImportDialog components with an in-memory API; saves and creates cannot reach production. It is not included in the production entry point.
### Real local service
For persistent manual testing, create a dedicated PostgreSQL database named
`streamline_profiles_dev` on `127.0.0.1`, then run from the repository root:
```sh
DATABASE_URL=postgres://streamline_test@127.0.0.1:55438/streamline_profiles_dev bun --no-env-file x drizzle-kit push --force
DATABASE_URL=postgres://streamline_test@127.0.0.1:55438/streamline_profiles_dev bun --no-env-file scripts/local-dev.ts
```
The example assumes PostgreSQL is already running on port 55438 and the local
role `streamline_test` exists. Schema initialization is **only** for this new,
disposable database, never a shared or production database.
Open `http://127.0.0.1:63868/manage` → **Products & branches**. The real API runs
on port 63869 and settings/tasks persist in PostgreSQL. The frontend signs in as
a local test admin through a serve-only SSO adapter; the normal backend identity
resolver and admin checks still run. This is not production SSO. Enable a draft
locally, then create a plain-text Bug or Feature to test its saved snapshot.
The launcher refuses other database hosts/names, does not inherit production
credentials or load env files, blocks outbound HTTP integrations and execution
routes, and does not start schedulers or satellites. Tasks remain queued for
evaluation; no code repair, MR submission or notification runs. The normal Vite
and server entrypoints are unchanged. `Ctrl-C` stops both local application
processes; PostgreSQL data remains available for the next run.
+88
View File
@@ -0,0 +1,88 @@
# Prototype(原型需求)—— 第四种任务类型
> 目标:纯 UI / 交互类需求,从「提交」到「看到效果截图」压到几十分钟以内,
> 绕开 2 小时以上的编译 + 云端回拉;用户多轮加意见到满意后,再把
> 「UI 产物 + Frida 脚本 + 源码定位」作为 Context 交给现有 Feature 链路做原生实现。
## 一句话流程
```
提交原型需求 ──▶ awaiting_prototype ──▶ prototyping ──▶ prototype_ready ──▶ (加意见) ──▶ awaiting_prototype …
│
└──▶ 「转正式实现」 ──▶ promoted + 新建一个普通 Feature(附接手包)
```
- **不评估、不确认**:没有 eval 阶段,创建即入队。原型本身就是"评估"——效果对不对,人看截图说了算。
- **不编译、不装包**:卫星直接拿设备上**已经装着的基线 App**(Android:设备里的 TikTok-M;iOS:`~/iosapp/TikTokM.app` 的 macCatalyst 进程),用 Frida 脚本做运行时热改造。
- **不改代码仓**:代码仓只允许只读查询(`git grep` / `git show origin/<base>:<path>`),用来把 hook 点映射回源码符号。没有分支、没有 MR。
- **原生实现不另起炉灶**:「转正式实现」= 用 `createFeature()` 建一个普通 Feature,`remark` 里塞接手包;后续 eval → 人工确认 → 实现 → MR 全走既有链路。原型行上记 `promotedFeatureId`,Feature 描述里注明来源。
## 为什么「UI 产物 + Frida 脚本」是有意义的 Context
调研结论(2026-09-09,见飞书《TikTok 私信单条消息自由编辑|Frida 原型与 iOS 源码接手包》):
1. **Frida hook 点天然就是源码符号。** iOS 的 `-[AWEIMUserMessageCellView layoutSubviews]`、Android 的 `com.ss.android.ugc.aweme.xxx.Foo.bar` 直接能 `git grep` 到文件;仓库里 `shared/src/method_coverage.ts` 已经在做同一件事的反方向(diff → Frida selector)。那份文档 10 个 hook 点映射到了 14 个源码文件 + 行号,是接手包的骨架。
2. **脚本本身是"运行时 diff"。** 它记录了:在哪个类的哪个时机、改了什么状态、参数是多少(尺寸/颜色/阈值集中在 `CONFIG`)。这比一段自然语言需求精确得多,且已被真机验证过。
3. **截图是验收基线。** 原生实现的验收标准从"实现方案里推断的"变成"和原型截图逐项对齐",评估器少猜很多。
4. **但脚本不是实现方案。** Frida 直接改 view、绕过 ViewModel / 组件系统、用全局单例存状态——这些原生实现都不能照搬。所以接手包强制带一节「原型不可照搬之处」,Feature 的 remark 里也明写"脚本用于定位触点和行为契约,不是移植对象"。
## 状态机(`shared/src/types.ts::PrototypeStatus`)
| 状态 | 含义 | 出边 |
|---|---|---|
| `awaiting_prototype` | 排队等卫星(创建即此态) | 卫星 claim → `prototyping` |
| `prototyping` | 卫星上 Agent 在跑 | `STATUS: PROTOTYPE_READY` → `prototype_ready`;否则 → `prototype_failed`;基础设施/鉴权错误 → 回 `awaiting_prototype`;用户 abort → `prototype_failed`(failureReason=用户中止) |
| `prototype_ready` | 有截图 + 脚本 + 报告,等人看 | 加意见(`/feedback`)→ `awaiting_prototype`(同工作区、同脚本继续迭代,`attempts+1`,`reviewHistory` 追加 human 注记);「转正式实现」→ `promoted`;归档 → `archived` |
| `prototype_failed` | Agent 做不出来 / 中止 | 重开 → `awaiting_prototype` |
| `promoted` | 已建出 Feature(终态) | — |
| `archived` | 搁置(终态,统计记失败) | 重开 → `prototype_ready` |
| `cancelled` | 用户取消 | — |
## 数据
- 表 `prototypes`(`drizzle/0026_prototypes.sql`),与 features 结构平行但**不共用**:没有 branch/MR/plan/regen/readable 列;多了 `baseline`(JSON:包名/bundle、版本、build、探测时间)、`script`(最新 `hooks/prototype.js` 全文)、`report_markdown`(最新 `ProtoReport.md` 全文)、`promoted_feature_id`。
- 表 `prototype_rounds`(prototype_id, round, script, markdown, created_at):每轮归档,晋升时能回看演进。
- 脚本与报告在卫星每轮结束时随 `/api/internal/prototypes/:id/update` 的 patch 上送,控制面落库并归档到 rounds。文件本体仍在卫星 `~/taskLog/prototype-<id>/`。
## 卫星(`satellite/src/prototype_runner.ts`)
- 工作区:`~/taskLog/prototype-<id>/{OriginalIntro.md, hooks/prototype.js, ProtoReport.md, evidence/, logs/}`。
- 跑之前**机械探测基线**:Android `adb shell dumpsys package <pkg>` 取 versionName/versionCode;iOS 读 `~/iosapp/TikTokM.app/Contents/Info.plist`(macCatalyst 布局)或 `Info.plist` 的 `CFBundleShortVersionString/CFBundleVersion`。探测结果写进 prompt 的「基线 App」块和行的 `baseline` 字段。探测失败不阻塞,写 `note`。
- Prompt:`shared/src/prototype_prompt.ts` 的 `DEFAULT_PROTOTYPE_RUN_FIRST_TEMPLATE` / `SECOND`(阶段 key `prototype.run.first` / `prototype.run.second`,控制面派发时随任务下发代码里的正文,与其他 track 一致)。
- 与 fix 循环同一个 claim 通道(同一台设备不能同时被两个 Agent 驱动),但控制面 `claimAnyFixForNode` **先看 prototypes 再看其它三张表**:原型几分钟就完,插队的代价远小于让它排在 2 小时构建后面。要彻底不排队,用 `clusters` 标签给原型单独划节点。
- 不需要代码 checkout 锁(不 checkout);不跑 tracking / method-coverage 扫描;不做 KB / TTKB / conditions;不生成可读性报告(面板直接渲染 `ProtoReport.md`,与 security 一样)。
- 结束时杀掉本工作区拉起的 frida 进程(App 回到基线,是预期行为)。
## 控制面
- `/api/prototypes`:list / get / create / feedback / promote / archive / reopen / abort / pin / unpin / delete / watchers / description / report / script / rounds / rounds/:round / log-file / logs / evidence* / handover。
- `/api/internal/prototypes/:id/{update,notify}` + `attachment/:uuid`。
- 通知卡:`dispatched` / `prototype_ready` / `prototype_failed` / `promoted`,深链 `?prototype_id=`。
- 接手包 `control-server/src/prototype_promote.ts::buildPrototypeBrief()`:原始需求 + 反馈脉络 + 最终 ProtoReport 全文 + 脚本全文(fenced js)+ 截图 URL 列表 + 「如何使用这份材料」规则。
## 前端
- kind `prototype`,路由 `/prototype?id=`,legacy `?prototype_id=`。
- 卡片 chip「原型」;抽屉:ProtoReport 渲染、脚本查看/复制、证据、「添加修改意见」、「转正式实现」(成功后显示到 Feature 的跳转)。
- 分桶:`awaiting_prototype→queued`、`prototyping→running`、`prototype_ready→review`、`prototype_failed/cancelled→failed`、`promoted→merged`、`archived→archived`。
## 明确不做(v1)
- Asking(与 Agent 聊)、可读性报告、跨端移植、Meego 写回、TTKB、KB 回灌。
- 让原型脚本"常驻"设备:Frida 退出即恢复,多任务共用设备只能这样。
## 生产前提
- Android 节点:`frida` 16.7.19 + 设备上 root 的 `frida-server`(fei-android-01 已验证)。
- **iOS 节点:frida attach 必须以 root 跑。** 实测(2026-09-10, fei-ios-01 / temp-ios-01):
普通用户 `frida -p <pid>` 必定 `Failed to attach: timeout was reached`,同一条加 `sudo` 秒回。
与 `DevToolsSecurity` 无关——两台都已 `-enable`、用户也在 `_developer` 组,普通用户照样不行。
根因是被测 App 是 adhoc 签名、**没有 `get-task-allow`**,非 root 拿不到 task port。
所以节点需要一条 NOPASSWD sudoers 规则(见下),否则无人值守的任务用不了 frida:
```
# /etc/sudoers.d/streamline-frida (chmod 440)
<节点用户> ALL=(root) NOPASSWD: /opt/homebrew/bin/frida, /Users/<用户>/Library/Python/3.9/bin/frida
```
frida 在 iOS 节点装在 pip 目录(`~/Library/Python/3.9/bin`),不在 homebrew——两处都写进规则。
`frida-ps`(只枚举进程)不需要 root。
备选通道 **不可用**:macCatalyst(platform 6)走 iOS 式 AMFI,`DYLD_*` 会被剥离,frida-gadget 注入静默失效。
+61
View File
@@ -0,0 +1,61 @@
# 复核群:在 Meego 缺陷群里推进一张 bug
机器人私信是单点提醒,催不动人。Meego 缺陷群里本来就有报告人(QA)、经办人(RD)和工单创建人;
把 Streamline 机器人也拉进去,每个流转节点都发生在一个有别人看着的地方,催办才有推动力。
代码:`shared/src/review_group.ts`(纯逻辑)、`control-server/src/review_group.ts`(IO)。
## 分两步上线(2026-11-09 定)
| | 第一步:只读(已上线) | 第二步:前台助理(待做) |
|---|---|---|
| 群里看得到 | 状态卡、「轮到谁」播报、超时催办 | 同左 |
| @机器人 | 「状态」:现在在哪、轮到谁、最近 5 次流转、面板 / MR / Meego 链接;其它话 → 说明去面板和 Meego 操作 | 任意自然语言:答疑、收意见、推断要不要打回 |
| 写操作 | 无 | 推断出的动作回确认卡,报告人 / 经办人 / 管理员确认后执行 |
| 模型 | 不用 | 执行节点上的 Asking 会话(控制面不需要模型 token) |
### 第一步怎么工作
1. **开群**:项目在批次设置里打开「复核群」(默认关,只有管理员能改)后,单子第一次要发通知时:
- 读单上的「拉群方式选择」(`group_type`:`auto` / `bind` / `disabled`);
- 不拉群的写成 `"auto"`(必须是字符串),Meego 随即建群,拉进**创建人 + 报告人 + 经办人**;
- `POST /open_api/:project/work_item/:id/bot_join_chat` 把 Streamline 机器人拉进群;
- 群号加进任务的 watchers:之后状态卡、复核卡补全、漏发补发都自动发进群。
托管中(还没移交经办人)和评估集的单不开群。三个 Meego 接口 2026-11-09 在生产插件上实测过,
插件 token 就够。管理员可用 `POST /api/tasks/:id/review-group` 给单张单开群(试点用,不看项目开关)。
2. **播报**:状态卡发完,@ 当前该动手的人,说清楚在面板 / Meego 上要做什么
(待复核 → RD;待 QA 验收 → QA;QA 关单但 MR 未合 → RD;复现不了 → RD,QA 先验收的项目里是 QA)。
3. **催办**:同一段等待满 24 小时再 @ 一次,之后每天一次,最多 3 次;只在北京时间工作日 10–19 点。
开关:`REVIEW_GROUP_DISABLED=1` 整块停用;`REVIEW_GROUP_ACTIONS=1` 打开群里的写操作(第二步用)。
### 第二步:类比 Asking Mode
面板的「质询」(Asking)已经解决了「控制面没有模型 token 也能用模型」:会话跑在**执行过这张单的卫星**上
(那台节点有工作区、执行日志、FixReport、代码 checkout),控制面只转发
(`/api/tasks/:id/asking/send|stream|history` → `satPath.asking.*`)。复核群的前台照搬这条路:
1. 群里 @机器人 的话(含截图、被引用的消息)→ 控制面 → 这张单执行节点上的 Asking 会话 `send`,
`from` 带发言人(名字、邮箱、在这张单上的角色)。截图先走 `asking/upload`。
**和面板「质询」是同一个会话**:群里问过的,面板上点开就能接着问,上下文不分叉。
2. 群来源的轮次在 preamble 里约定输出:先给群里看的回答(短,长了截断并附面板链接),末尾附一段
结构化决策,例如 `{"decision":"answer" | "propose_rework" | "propose_note", "reworkText": "..."}`。
3. 控制面读 `history` 等这一轮结束,把回答回复进群;决策是 `propose_*` 时回确认卡(第一步里已写好的
`confirmCard` / `rejectBugReview` / 写 Meego 评论,就是这一层的执行器)。**模型只提议,人点了才执行**;
流转账本记点确认的人。
4. 约束:
- 群来源永远不进 code-mode(不碰 checkout 锁、不改代码);
- 状态门和面板质询一致:`manual_review` / `fix_succeeded` / `unreproducible`;其它状态退回第一步的只读回复;
- 执行节点离线 / 会话报错 → 退回只读回复,不让群里干等;
- 打回原因的真值仍在 Meego 单上:确认打回时原样写成单上评论(2026-11-05 定的规矩);
- 真值只认执行结果(`docs/rsi.md` 的底线):前台推断「该打回」不算质量信号,人确认的打回才算。
5. 用量:这些轮次计入卫星的 Asking 用量(`claude_usage_source` 按首条 prompt 归类),
上线前要给群来源单独一个来源标签,方便看成本。
### 已知限制
- Streamline 应用没有 `im:chat` / `im:chat.members` 权限:机器人不能拉人进群,也读不到成员列表。
拉人只能靠 Meego(自动拉群、`join-chat`)或群里的真人。想把 TL / 治理负责人拉进群增加围观压力,要先申请权限。
- 卡片按钮要在飞书开发者后台把「回调」配成长连接、订阅 `card.action.trigger`;没配时群里回「确认 / 取消」兜底。
- 自动拉群会拉工单创建人,不只是角色成员——批量对存量单开群前要知道会把这些人都拉进来。
+669
View File
@@ -0,0 +1,669 @@
# Streamline 的递归式自我改进(RSI)
> 一份关于「一个 coding agent 平台如何用自己产出的数据改进自己的做事方法」的工程报告。
> 素材全部来自本仓库的真实实现:`control-server/src/{rsi_*,kb_*,evidmon_*}.ts`、
> `satellite/src/{runner,evaluator,tool_gap}.ts`、`shared/src/{eval_prompt,conditions}.ts`。
> 每个例子都给出**方法论 / 数据 / 指标**三段,指标全部可从生产库直接算出。
---
## 0. 一句话结论
Streamline 不只是「让 agent 干活」,它已经在**用干活产生的数据,改自己干活的方法**:
```
┌──────────────────── 人改代码、人决定上线(唯一的写权限)─────────┐
│ │
任务 ──► 评估器 ──► 执行器 ──► Fix-Critic ──► 人工复核 ──► 真机条件 / 驳回理由 / 会话日志
▲ │
│ ▼
prompt(代码常量)◄── 实验机复跑 ◄── 离线重放 ◄── 自动实验回路审计会话 ◄──┘
知识库注入 ◄── 归因 ◄── 真机条件与注入知识的一致性
工具库 ◄── 提案 ◄── 会话日志里的重复命令签名
```
关键不是「有没有自动改」,而是**改动是否可证伪**:这条回路上的每一次修改,
都必须先拿出一份用**执行结果**(而非另一个模型的意见)算出来的证据。
---
## 1. RSI 是什么
**Recursive Self-Improvement**:agent 不只完成任务,而是利用完成任务产生的经验、
代码与评测结果,改进自己的**做事方法**,再用改进后的自己去做下一轮任务。
```
任务 → Agent → 结果 → Evaluator → 改进算法 → 更强的 Agent → 任务 …
```
三个常见误解,先澄清:
**① RSI ≠ 自己训练自己。** 可被改的对象远不止权重:system prompt、workflow、
工具与技能、记忆/知识库、上下文管理、子 agent 分解、评测器本身。分级:
| Level | 改什么 | Streamline 现状 |
|---|---|---|
| L0 | 不改自己 | — |
| L1 | 改 Prompt / 记忆 | ✅ 复现知识库注入、evaluator prompt 版本库 + 热更 |
| L2 | 改 Workflow / 判据 | ✅ 证据判据版本化(evidmon)、失败模式 → 提案三段式 |
| L3 | 改 Skills / Tools | ✅ `record-evidence`;🆕 工具缺口自动挖掘 |
| L4 | 改 Agent Code / 架构 | ⚠️ 人在环,提案可提、代码需人写 |
| L5 | 改模型权重 | ❌ 不做(也不该在业务平台里做) |
| L6 | 改「改进自己的能力」 | ⚠️ 分类器准确率、判据精度、风险分校准已被度量,但优化仍靠人 |
**② 真正难的是 Evaluation,不是 Improvement。** 没有可靠的 evaluator,RSI 会退化成
**recursive self-delusion**:模型把评分标准也一起改松了,指标一路上涨,实际能力不变。
所以**评估器必须尽可能独立于被优化对象**。
**③ 为什么 coding agent 是 RSI 最早落地的领域**:代码天然有 evaluator——编译、测试、
真机验证、MR 是否被合入。Streamline 更进一步:它的执行器**在真机上确立事实**
(`run_conditions`),这是一份既不属于评估器、也不属于修复器的独立证词。
---
## 2. 已有实践(改造前就在跑的)
### 例子 1 · 复现知识库:把一次执行的经验变成下一次的先验
**方法论。** 传统做法是让一个模型读日志、事后"总结知识"。本仓库反过来:**执行器自己
写下它确立了什么**(`scope / subject / statement` 三元组),因为它刚做完那件事,比下游
读日志的模型更知道该怎么命名。于是"蒸馏"退化成一次**纯代码的归一化**——没有模型、
没有节点依赖、毫秒级(`kb_promote.ts` 顶部注释记录了模型版失败的三条代价)。
冲突仲裁独立成 DB-free 的四个函数(`kb_arbitration.ts`):key 归一化、命题等价、
证据加权、置信衰减。注入侧(`kb_retrieval.ts`)有五道闸:只取 `active`、置信下限、
Top-K、渲染长度硬上限、`KB_INJECT=0` 急停开关。
**数据。**
- `run_conditions`:每轮执行结束镜像回控制面(工作区会被清,DB 不会)
- `kb_claims` / `kb_evidence` / `kb_proposals` / `kb_injections`
- 只有 `verdict='verified'`(真机上真的做过)才能升格为 claim
**指标。**
- `kbAdoptionRate` 知识采纳率 = 评估器 `KB_USED` 引用过的注入 / 上报过引用的注入
- `kbHitRate` 知识命中率 = 真机证实 / (证实 + 推翻)← 本次新增,见例子 8
- claim 置信度 = Laplace 平滑的支持率 × 90 天半衰期衰减
**局限。** 检索是关键词 + 结构化过滤,同义表述("Story 相机" vs "故事拍摄页")召不回;
向量列 `kb_claims.embedding` 留着但故意没用——一次错误注入的代价是一次真机构建,
比一次漏召回贵得多。
---
### 例子 2 · Fix-Critic:把提出者和评分者拆开
**方法论。** 修复 agent 自称 `STATUS: FIXED` 后,**另一个只读的 claude pass** 独立复判,
四选一:`ROOT_CAUSE / SCENARIO_BANDAID / INTENT_MISMATCH / UNCERTAIN`,外加一个
0–100 的风险分。严格只读——不许改代码、不许构建、不许碰设备。判为旁路时**自动打回重修**
(有次数上限),把评审意见塞进下一批的 prompt。
这就是 RSI 架构里最关键的那条:**evaluator 必须独立于被优化对象**。它拦的是最典型的
自我认证——`if (场景) return;` 让坏现象消失,负向验证通过,但根因机制没动。
**数据。** `tasks.fixed_risk`(风险分)、`tasks.critic_verdict`(判定类别,本次新增列)、
`reviewHistory` 里 `source='critic'` 的反馈条目、`logs/critic-<round>.log` 全文。
**指标。**
- `rootCauseRate` 根因修复率、`bandaidRate` 场景旁路率(分母 = 有判定的批次)
- `riskCalibration` **风险分校准**:判"可信"(risk<40)的任务里,真的一次通过的比例
- `riskDiscrimination` 区分度 = 低风险组通过率 − 高风险组通过率
> 后两个是**给尺子量尺子**。区分度塌到 0 时,"可信度"标签就没有信息量了,
> 此时所有其它质量指标都是用弯尺量出来的——这是策略队列应当最优先修的东西。
---
### 例子 3 · EffectiveSpec:规格的自我修正,且保住基线
**方法论。** 执行期在真机上发现 TestSpec 写错了(`spec='contradicted'`),修正不是
就地改原文,而是折进一份**派生**文件 `EffectiveSpec.md`(引用块标出,优先于原文)。
`TestSpec.md` 永远只读。
为什么重要:`TestSpec.md` 同时是 Fix-Critic 的判据、和**评估器首轮质量的基线**。
如果允许执行期改它,被优化对象就把尺子一起改了——这是 RSI 里最隐蔽的自欺路径。
**数据。** `run_conditions.spec ∈ {predicted, contradicted, absent}` + `spec_said`
(当时 spec 是怎么说的)。这是评估器质量的**逐条判决书**。
**指标。**
- `specPredictionRate` 规格预测命中率 = predicted /(predicted+contradicted+absent)
- `specContradictionRate` 规格反证率
- 明细 `topSpecMisses`:按 subject 排的"最常猜错的条件"
---
### 例子 4 · 证据判据闭环(evidmon):agent 改的是"尺子"本身
**方法论。** 一条完整的 L2 回路,且是本仓库里最早跑通的:
机器定时写指标快照 → 每日分析任务读快照写「发现」→ 提「策略」→ **人工批准** →
判据新版本生效(无需发版,节点每次采集时拉取)→ 用批准时刻打戳的窗口做前后对比。
杀手锏是 `evidmon_replay.ts`:判据是纯函数、每次采集的 ffprobe 结果都存着,
所以候选判据能在**毫秒内在全量历史上重放**,批准前就知道哪些样本会翻盘。
不用等一个季度的 A/B。
**数据。** `evidence_capture_events`(含 probe 原始结果)、`evidmon_metrics_daily`、
`evidmon_findings` / `evidmon_strategies` / `evidmon_criteria`(判据版本表)。
**指标(L0 证据可采信率往下拆)。**
| key | 含义 |
|---|---|
| `evidenceAcceptanceRate` | 复核态任务里带着可采信证据的比例(北极星) |
| `coverage` / `keyEvidenceRate` | 有采集 / 有通过的演示视频 |
| `validity` / `videoValidity` | 采集通过率 |
| `durability` | 已镜像 TOS(明天还在) |
| **`verdictPrecision`** | **判坏的确实坏——同样是"给尺子量尺子"** |
| `retryRoi` / `retryRegression` | 重拍后判定改善 / 反而变差 |
---
### 例子 5 · 可读性报告 Prompt Lab:prompt 变成有版本的数据
**方法论。** 报告生成 prompt 的正文是代码常量(`shared/src/readable_prompt.ts`),
生产永远用它;实验室里可以存草稿版本(`readable_prompts`)、在任意历史目标上试跑、
存量批量重跑、并排对比。这是**"prompt 可被实验"的基础设施**。
(它曾有一个 active 指针决定生产用库里哪一行,新基线「插入但不自动激活」——代码基线
因此两次在库里躺了数周没人切,2026-10-12 拆掉,生产改为只认代码。)
配套的第一性原理写在 `docs/逼近AI实现报告可读性的极限.md` 里,其中最锋利的一条是
**pixel-blind 定律**:格式化者看不见像素,所以 **ImplReport 的质量就是可读性的天花板**——
要提升第 N 阶段,先去优化第 N−1 阶段。
**数据。** `readable_prompts` / `readable_report_runs` / `readable_sources`。
**指标。** 目前只有人眼评审 + 生成成功率。**这是已知缺口**:没有客观 scorer,
所以这条回路停在 L1 的"可实验",没进到"可自动择优"。
---
### 例子 6 · record-evidence:把 prompt 纪律变成工具约束(L3)
**方法论。** agent 反复手敲 `adb` / `xcrun` / `ffmpeg` 录屏,错法千奇百怪,
产出还只能靠文字描述取信。做法不是把 prompt 写得更长,而是**做一个工具**:
统一命令、自动 ffprobe 校验时长/画面/完整性、把每一次尝试(含失败)结构化写进
`evidence/manifest.jsonl`。
> **工程 know-how:工具化把「要求模型做对」变成「模型只能做对」。**
> prompt 微调的收益会迅速见顶,能力边界由工具决定。
**数据。** `evidence_capture_events`(就是 manifest 的入库形态)。
**指标。** 见例子 4 整棵树——这棵树本身就是工具化之后才有的东西。
---
### 例子 7 · 无法复现的产出化:连分类器都要被打分
**方法论。** `unreproducible` 不再是"平台耸肩",而是产出一份给报告人的结构化说明。
其中只有一个判断题——六种失败形状选一——用**规则分类器**做,**人工确认后**才发出。
`env_blocked`(我们自己的构建/设备/CLI 出问题)永远不可发送。
**数据。** `unrepro_digests`:`category`(人工确认的)与 `suggested_category`
(分类器猜的)**同时保留**。
**指标。** `unreproClassifierAgreement` = 分类器建议被人工采纳的比例。
这是一条 **L6 味道**的指标:它度量的不是产出质量,而是"我们做判断的能力"有多准。
---
## 3. 本次新建的四条回路
### 例子 8 · 修复质量指标树(`rsi_metrics.ts`)——先把尺子架起来
**方法论。** 改造前 `weekly_report.ts` 只统计**吞吐**(新增 / 派发 / 合入),
一个质量指标都没有。没有质量时间序列,任何 prompt 改动都是盲改:无法回答
"这次改动到底让它变强了没有"。于是照抄 evidmon 的形状,把北极星定为
**L0 一次交付通过率**,往下拆成九组解释性指标。
三个刻意的定义选择:
1. **交付 ≠ 裁决。** 停在 `manual_review` 的任务算"已交付"、不算"已裁决"——
否则只要不复核,通过率就会上涨。
2. **只有 `verified` 条件进规格分母。** `assumed` 是评估器自己的推断被回声,
拿它给规格打分等于自己批改自己的卷子。
3. **没上报引用的注入是缺数据,不是零采纳。** 否则某个节点部署落后,
知识采纳率就会莫名其妙下跌。
**数据。** `tasks`(status/attempts/fixed_risk/critic_verdict/reviewHistory/mr*) +
`task_transitions`(只取 `source='forward'`) + `run_conditions` + `kb_injections` +
`unrepro_digests`;快照落 `rsi_metrics_daily`(每日一行,机器定时写)。
**指标。**
| key | 定义 | 为什么要它 |
|---|---|---|
| `firstPassYield` | 无驳回即批准 / 已裁决 | 北极星 |
| `rootCauseRate` / `bandaidRate` | Critic 判定分布 | 修得对不对,而不只是修没修好 |
| `humanRejectRate` | 驳回次数 / 交付次数 | 人的返工负担 |
| **`riskCalibration` / `riskDiscrimination`** | 判"可信"的确实一次通过 / 低-高风险组差值 | **给尺子量尺子** |
| `specPredictionRate` / `specContradictionRate` | 真机对 TestSpec 的判决 | 评估器首轮质量 |
| `reworkRounds` / `multiRunRate` | 平均执行批次 / 多批次率 | 成本 |
| `mrMergeRate` | 已批准且有 MR 的合入率 | 终局验收 |
| `unreproRate` / `infoRequiredRate` | 无法复现 / 信息不足 | 把球踢回去的比例 |
| `kbAdoptionRate` / `kbHitRate` | 采纳率 / 命中率 | 知识回路健康度 |
样本量下限取 5(证据回路是 8):修复任务比证据采集稀疏得多,
低于门槛的比率照常显示,但**标记为"样本不足"**,前端置灰。
---
### 例子 9 · evaluator prompt 模板化 + 随任务下发
**方法论。**
1. **模板化**:`buildEvalPrompt` / `buildRegenPrompt` 的正文搬进
`shared/src/eval_prompt.ts`,变成 `{{占位符}}` 模板(之后执行期的 bug / feature /
security / prototype / 验证模板也照此搬进 `shared/src/run_prompt.ts` 等,全平台的
派发 stage 见 `control-server/src/agent_prompt_db.ts::PROMPT_STAGES`)。
迁移时用 24 组组合(语言 × remark × 知识注入 × regen)逐字节比对了新旧渲染结果,
**完全一致**——"只动管道、不动行为"是可核对的断言,不是口号。
(之后英文语言指令被**有意**加强了一版:中文模板 + 一句"请用英文"常导致中英混写,
新指令显式声明"不要跟随下方指令的语言"并保护下游按中文标题定位的结构标签。
这是这次改造里唯一一处刻意的行为变更。)
2. **随任务下发**:控制面在 claim 时把**自己编译进去的那份代码正文**随任务下发
(`protocol.ts::WithEvalPrompt` / `WithRunPrompt`,与 `kbContext` 同一条路),
卫星收到就用、收不到就用自己包里的。于是改 prompt = 改常量 + 部署,卫星包落后的
节点也跑新措辞。RSI 实验机复跑时,同一条路换成候选正文——这是"prompt 可实验"的基础。
**曾经的第 3 步:版本库 + 离线重放打分(已删除)。** 08-12 建过一套 `agent_prompts`
版本库 + 每个 stage 一个 active 指针(`settings.rsiActivePrompt:<stage>`)+ 只读的离线重放
(候选 eval prompt 在历史工单上重跑,按真机核实的条件召回 / 终态判定 / 结构纪律 / 不重犯
已知错误打分),批准一条 prompt 提案就移动指针。2026-10-12 核对生产:指针从未设过、提案
0 条、重放 0 次——生产一直跑的就是内置默认;它留下的唯一长期效果,是让每个读代码的人
以为"改默认不生效、要走提案"。于是整套拆掉:生产只认代码,版本历史就是 git。
打分思路里**不用 LLM 当裁判**那条原则由自动实验回路继承(例子 13):与被评对象同源的
裁判会让回路学会"讨好裁判"而不是"变强"。
---
### 例子 10 · 知识注入的效果归因(`kb_outcome.ts`)——把 L1 推向 L2
**方法论。** 改造前这条回路是**开口**的:`kb_injections` 记了注入什么、
评估器上报了采纳什么,然后就没了——`outcome` 与 `evaluated_at` 是两列**从没被写过**的
预留列。后果是:一条知识可以被注入五十次、每次都是错的,置信度**一分不掉**,
检索还在把它排在前面推给下一个人。
现在每轮执行结束(跟条件镜像同一个时机)做归因:把注入过的 claim 与该次执行
**真机核实**的条件配对,用与仲裁同一套等价判定比对命题:
一致 → 支持证据,不一致 → 反驳证据,
然后走 `recordExecutionVerdict` 重算置信度、必要时自动降级。
> **配对规则于 2026-08-21 改写,原因是它一次都没配上过。**
> 原规则是 `(scopeKey, subjectKey)` 严格相等——与仲裁同一套。那对仲裁是对的
> (比的是同一次运行里的行),对归因是错的:归因比的是几个月前另一台节点写的
> 自由文本。生产数据没有含糊之处——**457 次「运行期确实核实过东西」的注入、
> 49,483 对 claim × 条件,subject 精确命中 0 次**,历史上每一次归因都滚成
> `inconclusive`,执行期证据一条没写过。
>
> 新规则见 `kb_outcome.ts::matchStrength`:kind 必须相同、平台必须相容,
> 然后 subject 相似度与 **statement 相似度**两条锚各自都能成立配对——
> subject 是两次运行各自起的名字(3,595 个已核实条件的 subject 里,只有 9 个
> 在第二个任务里再出现过),statement 才是命题本身。
> 确认与推翻的门槛**不对称**(`MATCH_THRESHOLD` / `REFUTE_THRESHOLD`):
> 错误的推翻会废掉一条本来正确的知识,代价远高于漏掉一次。
>
> **但这不足以让回路活过来。** 把新规则回放到全部历史数据上,49,483 对里只配上
> 1 对。真正的约束不在匹配器,而在检索:注入进去的 10 条知识,跟这次执行真正
> 会碰到的东西基本无关。更根本的是,这个库今天几乎不复用——3,748 条 claim 里
> 只有 **7 条**拿到过一个以上任务的证据。匹配器是必要条件,不是充分条件。
三条纪律:
- **采纳 ≠ 正确**:所有被注入的 claim 都参与打分,不只被引用的那些。
否则一条被忽略的错误知识永远无法被推翻。
- **沉默 ≠ 同意**:本轮没触及的 claim **不给任何证据**(不是弱支持)。
否则置信度会变成"被检索过多少次"的度量。
- **只认 `verified`**:`assumed` 条件是评估器读了注入以后的推断,
拿它确认注入,等于让回路自造证据。
**数据。** `kb_injections.outcome ∈ {confirmed, contradicted, mixed, inconclusive}`
+ `evaluated_at`;`kb_evidence` 追加执行期证据(权重走既有 `evidenceWeight` 表)。
**指标。** `kbHitRate`(命中率)、注入归因分布(证实/推翻/混合/未触及/待判),
以及它对 claim `confidence` 的实际影响。
---
### 例子 11 · 失败模式聚类 → 提案三段式(`rsi_analyst.ts` + `rsi_strategy_db.ts`)
**方法论。** 显而易见的做法是"把一个月的驳回理由丢给 LLM,问它前三类失败是什么"。
读起来很漂亮,且**不可证伪**。两个具体问题让它不适合做这里的原语:
同样输入两次跑出不同分桶,于是"这类失败有没有变少"根本问不出来;而且是
**同一个模型家族在给自己的弱点命名**。
所以分类用**关键词规则表**:笨、稳定、可审计——每个桶里的任务都能列出来被人反驳,
准确率本身可度量(对照 `unreproClassifierAgreement` 的做法),改规则本身也是一条可提的策略。
LLM 仍然有活干,只是往后挪了一步:读**已经数好的**聚类和指标变化,写发现与提案。
三个信号源,全部已结构化、无需重新叙述:人工驳回理由(驳回必须写理由,所以文本一定存在)、
Fix-Critic 打回(自动拦下的失败,基于复核的统计永远看不到它们)、
真机推翻 TestSpec 的条件(评估器的锅,记在事实里)。
提案的生命周期沿用 evidmon 已经验证过的三段式,并保留它证明有效的两条铁律:
1. 没有人就出不了 `proposed`——分析任务用 cluster secret 认证,批准路由要 SSO 身份;
2. `effectiveAt` 在**批准那一刻**打戳,事后不能把前后窗口画得对自己有利。
所有旋钮(prompt / tool / workflow / capability)的提案都是**待办**:批准后由人写代码,
上线后标记生效、开始计前后对比。`prompt` 旋钮曾经**批准即执行**(写版本库 + 移动
active 指针),配过一道离线重放证据闸(08-21 因拦错了人关闭);2026-10-12 随提示词库
一起拆掉(见例子 9)——这期间生产上一条提案都没有过。
**数据。** `rsi_findings`(研究日志,附 `clusters` 快照)、`rsi_strategies`
(提案 + 决策 + 前后值)、`rsi_metrics_daily`。
**指标。** 每个聚类的 `count / tasks / share`(份额之和恒为 1,一条信号只进一个桶);
每条已生效策略的 before/after(按日快照取均值,两侧样本量随答案一起显示,
样本不足时**只给数字、不给结论**)。
---
### 例子 12 · 工具缺口挖掘(`tool_gap.ts` × 2)——L3 的需求发现
**方法论。** `record-evidence` 证明了工具化的收益,但**难的从来不是造工具,
而是发现哪一段咒语值得造工具**。现在让机器发现:各卫星扫自己最近的 session 日志,
提取所有 Bash 工具调用,把每条命令**归一化成签名**(去掉路径、id、hash、长数字、
引号串;短 flag 排序去重;取管道头部作为意图),控制面聚合全集群。
排名 `runs × (1 + failRate) × log(1 + tasks)`——三个信号缺一不可:
只跑过两次不值得造工具;每次都成功的命令当命令用挺好;
同一个任务里跑二十次是一个 agent 在重试循环里,不是模式(所以取 log 阻尼)。
**日志不出节点**:会话日志按 MB 计,只有聚合结果(签名、计数、一条样本)过网。
**数据。** `rsi_tool_gaps`(签名主键,`first_seen_at` 永不更新——
"这个缺口已经开了两个月"通常是最有说服力的数字)。
**指标。** 签名的 `runs / targets / failRate / score`,以及三态流转
`open → proposed → toolized`(或 `ignored`)。
---
### 例子 13 · 自动实验回路——把「发现 → 提案 → 验证」也接起来
**方法论。** 前十二个例子解决了指标、版本和判定,但仍要人读日志、想改法。
`scripts/rsi_loop/` 是每天跑在 temp-ios-01 上的独立回路进程,把缺的这一半补齐:
```
近 14 天原生会话
→ 同一堵墙 / 同族命令重复失败切片(读取类输出不算失败)
→ dead_end / decision_error / context_missing / not_failure 审计
→ 按失败调用浪费聚类,只选一个问题、只往现行 prompt 插入一段
→ 目标点 + 其它模式保留集配对重放
→ /api/rsi-loop/experiments(离线没过也记录)
```
审计模型只负责提出**可证伪的假设**。离线闸不问另一个模型「写得好不好」,只看第一步
动作形态:开始等 App 时有没有继续手写长 sleep / 轮询;撞过同一堵墙后有没有原样重试;
Frida 首次失败后有没有不诊断就再次注入。目标组最多 36 点、保留集 15 点,每个点的现行 / 候选
各跑三遍,以 `baseBad − candBad` 做 paired bootstrap,目标组至少 15 点(2026-10-03 用 24 点 × 2 遍
时区间半宽约 ±0.11,一个与现行打平的候选以下界 −0.104 被拦,故加到 36 点 × 3 遍,半宽约 ±0.08)。
离线的下一步是真机复跑,所以离线只拦**明显变差**的(目标组与保留集的 95% 区间下界都不低于
−0.10)——2026-10-02 完整试运行里现行版在「等 App 就绪」点上坏选择率只有 18.8%,要求离线显著
变好会让每个实验都停在这里。规则在 `shared/src/rsi_loop.ts`,回路进程改不了,控制面收到提交后
会重新验模板和离线结果。
**边界。** 原生会话含工单正文和测试账号,只落 temp-ios-01 的 `~/rsi_loop/data`,
默认 14 天删除;控制面只收到聚合模式、四段实验记录和数字。重放在第一次失败结果后截断,
有后台任务未结束、缺环境附件或上下文过大的点不用;所有工具调用由 hook 拒绝。候选新增行
按锚点插进历史会话第一条用户 prompt 的同一位置、不加标题(离线比生产更醒目会高估候选),
锚点定位不到的点两组都不跑;base / candidate 共用同一历史前缀。这仍是「续跑一步」的近似,
不能把它说成真机重演。重放报错率超过 20% 或目标点不足 15 个时不提交,避免把基础设施故障
记成「候选无效」。
**真机复跑(离线之后的第二道闸,也是实验的终点)。** 离线重放只看模型想做的第一步,判的是
**机制**;真机复跑判的是提案登记的**业务指标**。它从评估集挑 5 个同平台、跑完过的历史 bug,在
专用实验机上用现行 / 候选 prompt 各完整跑一遍(Android 在 `evaluator-android-01`,iOS 在
`temp-ios-01`,`RSI_LAB_NODES` 可改),同一来源两版交替先后以抵消设备上残留的上一次构建。
以「走不通时耗掉的时长」立项的实验,5 个来源里 3 个换成近 60 天生产上走不通(unreproducible /
fix_failed)的单——评估集里这种单每平台只有 2 个,只喂能修好的单测不出「早认死路」。判定是
**安全闸**而不是显著性检验(`judgeLab`):目标指标方向改善、agent 自报修好的个数不比现行少
(自报不是真值,只作底线)、到达复现现场的任务数不比现行少(防「跳过复现换提速」)、单次用时
不长于现行 20%,四条都满足才算通过;3 天到期不足 3 对跑完判不通过。每次复跑是一条
从评估集复制出来的 bug 任务,id 前缀 `rsi-lab-`,控制面与卫星据此关掉所有生产副作用:不推分支
不提 MR、不碰 Meego(不带单号,附件按来源任务只读代理)、不发卡片 / webhook、
不记状态流转、不注入 / 不升格知识、不出可读报告、不上传证据,并从看板、统计、周报、RSI 指标与
基线里排除;只保留会话摘要和节点本地的证据清单,指标从它们来。只有 `bug.run` 能复跑(评估集只有 bug)。
**运行时实验(执行配置包)。** 拆 160 批生产执行的时间:模型思考占 31–34%,是最大的一块;
每批写明的 sleep 合计 Android 7.6 分、iOS 4.0 分;构建只在 iOS 上是大头(约 25%,`airb` 拉产物)。
这些都不是「prompt 少一句话」能改的,所以回路还能提交 `kind=runtime` 的实验:两组同一版 prompt,
候选组多带一个**执行配置包**(`shared/src/executor_profile.ts`),派单时随任务下发,卫星按它改
CLI 参数或在 prompt 末尾追加一节。配置包是**封闭目录里的旋钮**,目前两个:`effort`(claude 的
`--effort`,对着模型思考那三分之一)和 `ui_settle`(`wait-for --settle`:画面指纹连续 1.2 秒不变
就返回。iOS 用 `catuse ui` 的界面大纲,约 0.24 秒、视频播放不影响;Android 在设备上给截屏中段算
md5,约 0.65 秒,视频流页面永远等不到稳定——把 10MB 原始截屏拉回来取样要 1.6 秒,比要替代的
`sleep 3` 还慢,已弃用。所以这个旋钮先在 iOS 上试)。不让配置包携带任意代码是有意的:量指标的尺子(证据清单、逐步计时、conditions)
和执行器在同一个卫星包里,能换代码就能改尺子。新旋钮由人写代码、正常部署,回路只决定开不开。
运行时实验不走离线重放(重放比不了换参数之后整批怎么跑),直接复跑;一个实验只能改 prompt
或拧旋钮之一,否则归不了因。复跑认领时记下节点的卫星包版本,同一来源两组版本不一致(中途
部署过)的配对不可比、不进判定。实验机上的复跑另开完整计时(命令 4000 字、绝对时刻、结果
末尾 300 字),两组都开,不影响比较。
**为什么没有线上灰度。** 最早的设计在离线之后还有一段线上灰度(同平台派单按任务哈希分一半
走候选、过程指标单侧显著就自动上线、上线后留旧版对照观察 14 天、变差自动 revert),
2026-10-05 整套下线,代码与页面一并删除。原因是对照不成立:新进来的生产任务之间差别太大
(平台、模块、难度、复现路径),两组新任务的差异主要是任务本身的,不是改动的;按平台划分后
Android 每天只有约 6 批,凑够能判的样本要几周。跑过的历史任务有现成的基线——同一个任务、
同一台实验机、新旧两版各跑一遍——差异才归得到改动上。所以生产派单永远走现行版本,
`rsi_experiment_assignments` 表保留但不再写入。
**自动执行权限。** 这条新回路和旧的 `/api/rsi` 人工提案系统不是同一条权限链:
它用独立 `RSI_LOOP_TOKEN` 只能读状态 / prompt / 会话、提交实验、写时间线,不能改生产 prompt。
真机复跑的判定由控制面的 `rsi_loop_judge.ts` 按纯函数规则完成;同一 stage 在 Android / iOS 上
各允许一个进行中的实验(实验机一台只跑一个实验的复跑)。复跑结论就是实验的终点,**不会自动改
生产 prompt**,上线由人决定。人在页面能暂停回路、停止复跑。
**批准上线:哪端复跑通过就只上哪端。** bug.run 一份模板两端共用,而实验只在实验机那一端复跑过。
所以模板支持平台段(`{{#ios}}…{{/ios}}`,`shared/src/prompt_platform.ts`),控制面派单时按任务
平台展开,卫星拿到的是普通正文。回路提交时声明策略范围:单端只在那一端复跑;双端两端各建一条
实验(同一 `group_id`,另一端实验机忙就排队),两端都跑完才决定——都通过两端一起上,只有一端
通过就只上那一端;另一端「判不了」(可比的对数不够)可以重跑那一端。单端通过后管理员也可以
「补另一端复跑」。只上一端时新增行包进该端的平台段,另一端展开后的正文必须逐字节不变,这由
`shared/src/rsi_ship.ts::planPromptShip` 每次校验;运行时旋钮上线改的是按端分开的
`PRODUCTION_PROFILE`,天然互不影响。批准 / 驳回只有管理员能做,**批准不改任何指针**:
它定下上线范围、校验补丁可用,改动由人用 `bun scripts/rsi-ship.ts <实验 id>` 在本地代码上
重算并写进常量,提交后照常部署;判定任务每轮按运行中的代码核对,带上了记「已上线」,之后
又没了记「已撤回」。实验的基线在提交时存成快照(按端展开),复跑的现行组跑快照而不是派单时
的代码,中途有改动上线也不会让配对失真;批准时代码改过就按锚点变基,找不到位置就是冲突,交给人。
规则在 `control-server/src/rsi_ship_service.ts`。
**数据与指标。** `rsi_experiments` / `rsi_experiment_events` 记录问题总结、猜想、方式、
离线结果、复跑判定和结论;`rsi_round_metrics` 每批存两类指标,定义在
`shared/src/rsi_loop.ts::LOOP_METRICS`。提案优先登记业务指标,过程指标只在找不到可信因果链时用:
| 业务指标 | 口径(真值来源) | 2026-10 生产基线(160 批) |
|---|---|---|
| `reach_s` 到达复现现场用时 | 这批开始到第一张校验通过的 `before-*` 证据(证据清单 `manifest.jsonl`,ffprobe 判 pass/warn);没到达按整批截尾;之前批次已到达的不计 | 中位 Android 30 分、iOS 44 分,约占整批一半 |
| `reach_miss` 未到达复现现场 | 一批结束仍无合格 `before-*`;任务级任一批到达即算到达 | 修好的批次 Android 17%、iOS 14% 未到达;复现不了的 12 批里 10 批未到达 |
| `evidence_fail` 证据校验失败 | 证据清单里判 fail 的截图 / 录屏次数(要重拍) | 每批 Android 0.6、iOS 1.0 次 |
| `dead_end_s` 走不通时耗掉的时长 | 没以 FIXED 收尾的批次的整批时长,修好记 0(早期失败识别) | — |
过程指标是 `ui_wait_s`、`blind_sleep_s`、`failed_calls`、`repeat_fail_calls`、`frida_fail_calls`、
`tool_calls`,加两条底线 `round_wall_s`、`round_failed`。
业务指标的真值不从计时文件取:计时文件里命令只留前 200 字,`record-evidence` 的 `--out`
有六成被截掉。证据按时间窗归批,不信条目里的 `round` 字段(那是 agent 填的尝试序号,36% 对不上
批次号)。成功率没有单列成目标:唯一现成的信号是 agent 自报 FIXED,按纪律它只当底线。到达类
目标有一条防刷分的确定性规则(`lintMetricGaming`,回路进程和控制面各验一遍):候选新增内容不许
涉及截图 / 录屏 / 证据命名——到达是按第一张合格证据量的,改快门时机会让指标变好而现场没变快。
页面同时画全舰队每日基线和单实验对照,避免「每个实验都显著、整体却没进步」。
### 例子 14 · 复核意见挖掘——把人工打回变成下一单的规范
**问题**:人工复核的打回意见(`review_history` 里 `source=human` 的那些)是平台最直接的质量信号,
但它只被下一轮返工用一次。同一句「改动要用 AB 包裹」「别新建组件,用 TUX 的」在不同单上被不同的人
反复写,agent 每一单都从头犯一遍。
**调研(2026-11-03)**:6–11 月 1306 条人工意见 + 56 条 MR 摘录(517 单),模型逐条分类、人工抽查约
85% 准。只有约 22% 讲「代码该怎么写」,其余是操作指令、没修好、视觉数值、背景信息、要证据、需求变更。
在这 22% 里,按跨单 × 跨人排前五:AB 开关 87 条 / 69 单 / 29 人、最小改动 55 / 49 / 29、先复用
47 / 37 / 23、不硬编码 26 / 19 / 10、注释整洁 18 / 15 / 9。个人口味的信号很稀:真正集中在一个人
身上的只有两三类;能认出复核人的意见只有 23%(`ReviewNote.reviewer` 11-02 才有,流转 `actor`
09-30 才有),认得出的里 72% 是建单人自己打回。
**两个反直觉的结论**写进了设计:
- **AB 默认开还是关,不是个人口味。** 同一个人在不同单上两种都要求过。读原话能分开:要「止损 /
防止上线撤不回」的,合码后改动必须生效 → 默认开;要「做实验 / 和线上隔离」的 → 默认关。所以规范
按用途定默认值,归纳提示词要求同一人前后相反时不出个人候选、把反例列进 conflicts。
- **建单人不等于复核人。** 批量导入的单,建单人是导入的人。个人口味只认 `reviewer` 和打回那一刻的
流转 `actor`,认不出就不算进人数。
**怎么做**:
| 环节 | 谁 | 做什么 |
|---|---|---|
| 规范块 | 代码 | 前五条写进 `shared/src/code_conventions.ts`,原文由 `scripts/sync-code-conventions.ts` 抄进 bug.run / feature.run.first / feature.run.second(rsi-ship 只认纯字面量,不能插值);仓库约定用平台段 |
| 每晚打标签 | 回路进程 | `/api/rsi-loop/review-mining/pending` 拿拼好的提示词(`REVIEW_LABEL_PROMPT_TEMPLATE`),交回原始回答;控制面按 key 回表校验、现算归属,写 `review_note_labels` |
| 每周一归纳 | 回路进程 | 拿近 90 天的编码习惯标签和归纳提示词(`CONVENTION_CLUSTER_PROMPT_TEMPLATE`),候选交回;控制面**按证据 key 重算**单数 / 人数过门槛(全局 / 仓库级 ≥3 单 ≥2 人,个人本人 ≥3 条 ≥2 单),写 `convention_candidates` |
| 决定 | 管理员 | RSI 页「复核意见挖掘」逐条批准 / 驳回(驳回要写理由,下周模型会看到)。全局 / 仓库级批准后改 `code_conventions.ts` 落代码,再标「已上线」填提交号 |
| 个人口味 | 本人 | 个人候选批准后进「我的代码口味」(用户菜单),**本人确认**才生效;派单时插在规范块末尾,给这单的复核人、Meego 经办人和建单人(最多 3 人),和 spec 冲突时以 spec 为准 |
| 写法偏好 | 本人 | 同在「我的代码口味」,本人事先写的一段额外提示词:常用写法可叠加勾选(勾选 = 往文本框插一段原文,如「所有改动加 AB 开关」),也可自由改写,下发的就是原文(`shared/src/code_taste.ts`,存 `settings` 的 `codeTaste:<前缀>`)。和个人口味注入同一块、同一批人。为批量导入加:导入即派单,经办人还没复核过就按平台默认写完了,挖掘链赶不上 |
**真值**:只认人写下的意见。页面顶上的月度读数是「某一类习惯被打回的次数 / 当月人工意见总数」,
规则上线后对应 topic 应该降下来;不降,说明规则没起作用或措辞不对。按现在的量(每月约 300 条),
只有 AB / 最小改动 / 先复用这三个大簇每月够 10 条以上,小簇的变化分辨不出来——这是已知局限,
不是可以用更多模型判断补上的。规范块上线时没有留对照组:模板常量对所有单生效,月度读数是前后对比。
---
## 4. 代码与数据地图
| 层 | 文件 |
|---|---|
| 指标树 | `control-server/src/rsi_metrics.ts` |
| 快照 / 研究日志 / 策略 | `control-server/src/rsi_strategy_db.ts` |
| 失败模式规则引擎 | `control-server/src/rsi_analyst.ts` |
| prompt 正文 | `shared/src/{eval_prompt,run_prompt,verify_prompt,readable_prompt,…}.ts`(结构见 `shared/src/prompt_registry.ts`) |
| prompt 派发 / 实验候选 | `control-server/src/agent_prompt_db.ts`(`currentPrompt` = 代码正文;`agent_prompts` 只存回路候选) |
| 知识注入归因 | `control-server/src/kb_outcome.ts`(+ `kb_db.recordExecutionVerdict`) |
| 工具缺口 | `control-server/src/tool_gap.ts` × `satellite/src/tool_gap.ts` |
| 自动回路进程 | `scripts/rsi_loop/` |
| 自动实验契约 / 分组 / 离线与线上闸 | `shared/src/rsi_loop.ts` |
| 自动实验 API / 采集判定 / 页面 | `control-server/src/{routes_rsi_loop,rsi_loop_*}.ts` + `control-web/src/components/RsiLoop.tsx` |
| 原生执行会话接口 | `satellite/src/transcripts.ts` |
| API | `control-server/src/routes_rsi.ts`(`/api/rsi/*`) |
| 复核意见挖掘 | `shared/src/{review_mining,review_mining_prompt,code_conventions}.ts` + `control-server/src/review_mining.ts` + `scripts/rsi_loop/rsi_loop/review_mining.py` + `scripts/sync-code-conventions.ts` |
| 面板 | `control-web/src/components/{RsiPanel,RsiLoop,ReviewMining,CodeStyleModal}.tsx` |
| 定时任务 | `control-server/src/rsi_daily.ts` + `scripts/rsi-daily.sh`(北京时间每日 09:10) |
| 迁移 | `drizzle/0008_rsi.sql`;复核意见挖掘 `drizzle/0064_review_mining.sql` |
新增表:`rsi_metrics_daily` / `rsi_findings` / `rsi_strategies` / `agent_prompts` /
`agent_prompt_runs`(离线重放删除后不再写入,待迁移删表)/ `rsi_tool_gaps`;
新增列:`tasks.critic_verdict`。
`kb_injections.outcome` / `evaluated_at` 早在 `0002_flaky_sprite.sql` 就已建好、
一直没有任何代码写过,这次才真正被填上——**预留一个当时用不上的列,
比事后再加一次迁移便宜**。
每日任务只做确定性的五件事(归因扫尾 → 写快照 → 挖工具缺口 → 写规则引擎日志 →
刷新已生效策略的前后对比),**不写带判断的发现、不提提案**。
理由与 evidmon 相同:指标必须由机器定时写,否则"没人分析的那天"就会在时间序列上留洞。
---
## 5. 七条反自欺纪律(这套系统真正稀缺的部分)
下面第 1 条描述的是旧的 `/api/rsi` 人工策略链。自动实验回路另走
`/api/rsi-loop`:不等人工批准,但回路令牌改不了生产 prompt;候选只在实验机上复跑历史任务,
通过与否由控制面的固定离线闸和复跑判定决定,上不上线由人决定(见例子 13)。
1. **提出与批准分离**:分析任务持 cluster secret 可写发现与提案,**不能批准**;
批准要 SSO 身份。这不是防攻击,是**回路结构上无法自我批准**。
2. **评分者只读**:Fix-Critic 不许改代码、不许构建、不许碰设备。
3. **基线不可动**:`TestSpec.md` 只读,修正走派生的 `EffectiveSpec.md`。
4. **真值只认执行**:升格进知识库、给规格打分、给重放打分,
一律只用 `verdict='verified'` 的真机条件与工单终态,不用模型意见。
5. **决策时刻打戳**:`effectiveAt` 在批准瞬间写死,前后窗口不能事后重画。
6. **有偏数据不进 headline**:`task_transitions` 只取 `source='forward'`;
未上报的注入算缺数据不算零采纳;样本不足只给数字不给结论。
7. **生产 prompt 只经代码改**:回路令牌、提案、批准都碰不到生产 prompt,生产只跑
部署的那份代码;候选只在实验机上跑。(原第 7 条"自动执行必须带证据"守的是
批准即生效的 prompt 旋钮:08-21 关掉了证据闸,10-12 连同这个旋钮一起拆掉——
没有自动执行,也就不再需要那道闸。)
配套的两个急停:`KB_INJECT=0` 关知识注入;prompt 回滚 = revert 那次提交 + 部署。
---
## 6. 我们在哪,和明确的局限
**在哪。** L1 闭环(知识);prompt 由自动实验回路提出、实验机验证、人改代码上线;
L2 有提案面与判据版本化;
L3 有需求发现;L4 及以上是人在环。**L6 的雏形**是那几个"给尺子量尺子"的指标:
`riskCalibration`、`verdictPrecision`、`unreproClassifierAgreement`。
**局限,逐条摆明。**
- **没有衡量"spec 写得好不好"的打分。** 想覆盖它,需要一个与生成器**不同源**的
独立裁判 + 一份人工标注的 held-out 校准集。**这是下一步,不是现在的能力**。
- **失败分类是关键词规则**,会漏、会误判。它的准确率应当像 unrepro 分类器那样
被人工确认率度量——目前还没接。
- **`criticVerdict` 历史行靠解析我们自己的措辞回填**,且对"打回后又修好"的任务
偏向记成旁路(旧代码只在非 ROOT_CAUSE 时写 failureReason)。偏差方向是安全的
(高估旁路率),且随卫星发版自然消失。
- **样本稀疏**。修复任务一天几个,日粒度比率天天不可靠;
真正能读的是 7 天均值和月级趋势。
- **可读性报告 prompt 仍无客观 scorer**(例子 5 的缺口),
所以那条回路还停在"可实验"而非"可择优"。
- **feature / security 两条链路尚未接入**指标树。三套表是平行的,
接入需要各自定义真值——不是把 bug 的定义套过去就行。
---
## 7. GUI:只放正在进行的两条回路
入口在**看板 → 自我改进**(也可直接访问 `/rsi`;顶栏菜单里有快捷入口)。谁能看:实验室成员
_或_ 管理员;暂停回路、停止复跑要可解析的登录身份,回路令牌做不了这些。
页面有两个子页:「自动实验」(`RsiLoop.tsx`)和「复核意见挖掘」(`ReviewMining.tsx`,见例子 14:月度读数、候选规范逐条批准 / 驳回 / 标为已上线,每条可展开看支持和相反的原话)。自动实验按回路真实运转的顺序回答三个问题:
| 区块 | 回答什么 |
|---|---|
| 回路状态 | 回路开没开、暂停没有、各状态的实验数、实验机是哪两台、复跑判定规则 |
| 基线走势 | 系统整体有没有在变好:生产执行批次的业务指标(到达复现现场、证据校验、走不通时长)与过程指标每日均值,图上标出每次复跑的开始与结论(复跑任务不进基线) |
| 实验 | 每一次改动怎么想的、结果如何:问题总结 / 猜想 / 优化方式 / 结论,离线重放结果,真机复跑判定与配对表,候选改动或执行配置包,动作时间线 |
| 回路日志 | 回路进程每天跑了什么、发现了哪些问题模式 |
**2026-10 删掉了 8 月那版的七个子页**(概览 / 质量指标 / 失败模式 / 研究日志·策略 / Prompt
实验室 / 工具缺口 / 方法论)。删之前核对过生产数据:策略提案、Prompt 实验室的版本与离线重放
**一条都没有**;质量指标快照、规则引擎日志、工具缺口每天机械地写,但一半指标已知失真(Critic
自 08-19 关闭、知识归因七成是错链),没有人据此行动过;失败模式的关键词聚类已被回路里的审计
聚类取代。提示词库、离线重放与 prompt 旋钮的执行路径已于 10-12 连后端一起删除(例子 9);
每日快照(`rsi_daily.ts`)与其余 `/api/rsi/*` 接口**暂未下线**,例子 1–12 的设计记录仍留在
本文前几节供查。
## 8. 顺手修掉的两处生产安全隐患
建设过程中被测试暴露出来的,与 RSI 无关但值得记一笔:
1. **单测在连生产库。** `control-server/test/setup_env.ts` 用 `||=` 设 `DATABASE_URL`,
但 Bun 会自动加载仓库根的 `.env`——变量早就被设成生产了,`||=` 什么也没做。
注释里写的"结构上无法碰到生产"在它最该生效的那台机器上完全失效。
现在改成无条件赋值,想连真库必须显式设 `TEST_DATABASE_URL`。
2. **`db.ts` 一被 import 就写库。** 该文件模块顶层有 `await` 的 boot seeds,
其中包含一条 `UPDATE tasks SET watchers = …`。于是"导入 DAL 去测一个纯函数"
会连库并**写**它。现已改成显式的 `runBootSeeds()`,由服务入口调用。
副作用:整个测试套件从 33 秒(连生产超时)降到 3 秒。
---
## 9. 上线步骤(都是生产写操作,需人工执行)
```bash
# 1) 迁移预演(只读),确认无误后再 --commit
bun scripts/apply-migration.ts drizzle/0008_rsi.sql
bun scripts/apply-migration.ts drizzle/0008_rsi.sql --commit
# 2) 部署控制面 + 卫星(卫星必须发:critic_verdict 写入与 /sat/toolgap 端点都在卫星侧)
.claude/skills/streamline-deploy/deploy.sh
# 3) 补一次当日快照 + 首次工具缺口扫描
bun run control-server/src/rsi_daily.ts
# 4) 挂 cron(与 evidmon 同机制,自身按北京时间自锁)
# 0 * * * * /path/to/streamline/scripts/rsi-daily.sh
```
面板入口:**看板 → 自我改进**(实验室成员或管理员均可见),或直接访问 `/rsi`。
第一周该看什么:先看 `riskCalibration` 与 `specPredictionRate` 的分母够不够;
够了再看比率。指标树自己就是被度量对象——**尺子不准的时候,先修尺子**。
Binary file not shown.

After

Width:  |  Height:  |  Size: 59 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 53 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

+36
View File
@@ -0,0 +1,36 @@
# TTKB 集成评审截图
采集于 2026-09-03。实际界面组件来自本 MR 分支;没有执行新的业务任务或部署生产。
静态截图用于核对状态和信息层级,不冒充录屏或真机端到端验收。
## 真实本地页面 / 已安装包目录
`default/android` 的本地卫星实际上报 6 个包,全部 ready;仅在草稿里勾选,没有提交建单。背景为本地测试数据库,不是生产看板。
![Feature 创建:Android、default、可选 TTKB 包](07-feature-android-live.jpg)
切换到没有在线候选节点的 `pns` 集群后,选项清空并显示不可用。
![无候选节点时不可选包](08-no-pool-live.jpg)
## 实际组件 / 合成 fixture
以下页面直接复用 `KbHitsPanel` / `TtkbUsagePanel`,只替换输入数据和本页 API 返回值;不读写任务数据库、不代表任何真实任务采纳。页面顶部保留 FIXTURE 标记,示例包为 `example/business` / `example/testing`。
此前真实任务的日志与临时截图已不在当前环境,不能将这些组件截图当作其重放证据。
![两个来源并存;TTKB 文档、包内路径、阶段、读取次数与导航索引](02-knowledge-panels-fixture.jpg)
![选择包但没有读取文档](04-no-documents-fixture.jpg)
![节点不能提供文档记录](05-offline-fixture.jpg)
![未选择 TTKB,仍保留 Streamline 历史知识](06-unselected-fixture.jpg)
交互检查还验证了“展开其余 1 篇”能显示第四篇导航文档。TTKB 显示的是成功读取,不等于采纳;Streamline 显示的是注入及模型报告的采纳。
## 其他验证
- 全量单元测试:765 pass / 0 fail,77 files,2,825 assertions。
- 全仓类型检查、web 生产构建、satellite bundle 构建均通过。
- 多节点版本不一致、缺包、旧节点未上报由确定性单元测试覆盖;没有模拟这些情况为真实机器截图。
- 安装、权限边界、发布顺序及回退见 [集成说明](../ttkb-integration.md)。
+115
View File
@@ -0,0 +1,115 @@
# TTKB:按任务选择的辅助知识
TTKB 是可选的外部知识源,不替代 Streamline 自有 PG 知识库及 `kbContext`。
任务不选择知识包时,TTKB prompt wrapper 原样返回原提示词;不会扫描包正文或自动安装。
本功能覆盖 Bugfix、Feature、Security 的创建、评估和执行,包括 Security 的重试路径。
## 用户看到什么
- 新建任务:在集群和平台对应的目录中勾选 `space/package`;默认不选。
- 任务卡片和详情:`TTKB × N` 表示选择了 N 个包,不表示整个包被采用。
- **复用的历史知识 / Streamline**:原有 PG 注入条目、K 标签、模型报告的采纳情况及人工反馈。
- **本次使用的外部知识 / TTKB**:成功直接读取的 Markdown/MDX 文档,包含包名、包内路径、标题、评估/执行阶段及重复读取次数;索引/README 单独标记为导航。
TTKB 面板的“使用”证据实际上是**成功读取**,不是模型确认采纳,更不是执行验证正确。
失败 Read、目录探测、Glob、仅出现在 prompt 中的包不计入。API 保留轮次,UI 聚合各轮,正文优先,默认显示 3 篇并可展开。
两块面板数据来源独立,TTKB 不写入 `kb_claims` / `kb_injections`,没有自动蒸馏或多语言改写知识正文。
## 管理员安装
使用卫星进程所属的 OS 用户安装;另一个用户的 HOME 不会被发现。先确保该用户已经安装可用的 TTKB CLI,并完成企业认证。以下参数以 `ttkb install --help` / `ttkb update --help` 为准;Streamline 不捆绑 CLI,也不负责其 npm 发布问题。
例如同一 Android 池的每台卫星都安装相同已审核版本:
```bash
ttkb install lemon8/lemon8-knowledge --global --version 0.0.45 --ai-tool cursor --no-package-paths --yes
```
Claude/Codex 节点将 `--ai-tool` 改为实际工具。版本号是示例,不是“当前最新”的承诺。优先固定版本或 commit,在池内统一更新。
若采用项目级安装,显式指定卫星的 `AI_WORKSPACE`,避免 CLI 自动选择 Git 根目录导致装到别处:
```bash
ttkb install lemon8/lemon8-knowledge --scope-root "$AI_WORKSPACE" --version 0.0.45 --ai-tool cursor --no-package-paths --yes
```
发现规则:
| 安装范围 | lock 文件 | 必须存在的原件目录 |
| --- | --- | --- |
| 卫星用户全局 | `$HOME/.ttkb/lock.json` | `$HOME/.ttkb/packages/<space>/<package>/` |
| 卫星工作区 | `$AI_WORKSPACE/.ttkb/lock.json` | `$AI_WORKSPACE/.ttkb/packages/<space>/<package>/` |
同名包项目级覆盖全局。只扫描这两个 lock 及默认原件目录;不支持任意 `--package-root` / `--package-base` 的自定义布局。`ttkb/cli` 不作为业务包展示。原生 skill 投影目录不是包发现依据。
本地扫描缓存 60 秒,节点注册和心跳上报包 ID、version、commitId、description、skills,不上传本机绝对路径或知识正文。等待扫描缓存刷新和下一次心跳后,重新打开创建弹窗。
```bash
# 只读:核对目标控制面;示例为本地开发服务
curl 'http://127.0.0.1:5173/api/ttkb/packages?cluster=default&platform=android'
```
包需要 `ready: true` 才能选择:**当前路由池中所有在线候选节点**都有它,且 version/commitId 元组完全一致,每份至少有一个版本标识。不是全公司的所有机器,也不按包名中的 android/ios 推断平台。
不完整、版本不一致、尚未上报的新旧节点混合池会禁用选项;没有在线候选节点时也不可选。多集群建单要求在每个可能落点的池都可用。
Meego 导入或未明确平台的 Bugfix 在获知真实平台之前按全部候选平台保守校验,可能比纯文本指定平台更严格。
更新先预演,确认后在维护窗口统一执行:
```bash
ttkb update lemon8/lemon8-knowledge --global --dry-run
# 若确实要解除 pin 升到 HEAD 并纳入新增知识,管理员明确决定后执行:
ttkb update lemon8/lemon8-knowledge --global --to-latest --include-new --yes
```
生产池更推荐每台机器统一 `install --version` / `--commit`,而非各自在不同时间追 HEAD。不要在运行中的任务读取包文件时更新。
## 对原有系统的影响
1. **数据库**:`tasks`、`features`、`security` 各增加一个 nullable TEXT `ttkb_packages`,保存 JSON ID 数组。旧行/未提供字段按空选择读取;不迁移或复制知识正文。
2. **API**:创建接口新增可选 `ttkbPackages: string[]`,去重、校验 ID(最多 20 项)及路由池可用性;非法或不可用的显式选择返回 400。新增目录及各任务类型的 `ttkb-usage` GET 接口。
3. **执行**:原有 `kbContext` 下发、K 标签和反馈链路保留;TTKB 只在选中后叠加辅助导航。当前代码、任务 spec 和 Streamline 已确认知识优先于 TTKB。没有额外在线翻译、embedding 或知识服务查询。
4. **跨语言**:复用独立多语言 MR !36 的 shared 词表,生成最多 24 个导航搜索词,不是事实或通用翻译,不修改知识包/PG 数据。
5. **路径与子 agent**:使用经本机验证的绝对原件路径及浅层入口。要求主会话直接 Read TTKB,不将 TTKB 查阅委托给子 agent;其他代码探索仍可委托。这是 prompt 约束,不是工具层隔离。
6. **节点稳定性**:被清理的未知节点发心跳得到 404,触发现有卫星重新注册完整地址/平台信息;正常心跳仍返回 200。此修复影响所有节点,不仅 TTKB,防止目录因幽灵心跳长期消失。
## 限制与风险
- **选择不是安全隔离**:`--global` 还可能向 Agent 原生全局目录投影 Skills/Rules,Agent 可自行发现;不选择只保证 Streamline 不额外注入 TTKB 指引,不能阻止原生自动加载。不要把这当成权限边界,包内容需管理员审核。
- **不自动安装**:没有自由输入未知包/下载/更新/单任务 worktree 安装。选中包在执行时缺失会告警并继续,不中断任务。
- **创建时校验不是执行时版本锁**:任务只存包 ID,未固定版本/快照;创建后节点加入、掉线、目录更新可使可用性或内容漂移,调度器本身不新增包约束。
- **审计依赖格式和文件**:只识别当前 stream-json 的直接 Read/read_file/readfile 及工具结果;Shell/cat、Grep 片段、子 agent 独立日志及其他未适配格式可能漏计。依赖卫星在线、日志保留和原文件存在,标题从当前文件读取,并非运行时内容快照。
- **审计不是无损历史库**:每个日志默认最多扫描 100,000 行(`TTKB_USAGE_MAX_LINES`);按日志尺寸/mtime 缓存,包文件单独更新不使缓存失效;每个进程的工作区缓存当前无 LRU。首次大日志扫描有 I/O 成本。运行中 UI 每 3 秒请求,后端缓存避免重复扫描相同日志。
- **无自动纠正历史记录**:旧节点、遗失日志、漏执行 schema 迁移不能凭 UI 恢复。原有 kbContext 记录失败仍可能静默:提示词成功注入但 `kb_injections` 为空,历史面板就不显示。TTKB 不修复该问题,也不能把读取等同采纳。
- **混合版本**:旧卫星不会提供新目录/审计或执行新指引。若旧控制面先于新卫星接收带 `ttkbPackages` 的请求,可能忽略该字段;发布完成前不要开放选择。自有 KB 的错误隐藏/刷新行为未在本 MR 改动。
## 发布与验收
本功能不是部署授权。生产操作按 `CLAUDE.md` 和部署 skill,由管理员在维护窗口执行。
1. 独立多语言 MR !36 先合入;若为 squash 合并,TTKB 分支 rebase 到 main 时跳过已包含的多语言提交,再将 MR target 改为 main。不要把 TTKB 合进仍待审核的多语言源分支。
2. 核对目标数据库及基线迁移齐全,再执行本 MR 的 `drizzle/0024_ttkb_task_packages.sql`(合入 main 时从 0021 改号,避免与已有 `0021_code_sidecars.sql` 前缀重复;当前仓库工具按文件执行,不按编号自动去重)。
```bash
# 预演默认只读;不会自动执行 DDL
bun scripts/apply-migration.ts drizzle/0024_ttkb_task_packages.sql
# 管理员核准正确目标库后才执行
bun scripts/apply-migration.ts drizzle/0024_ttkb_task_packages.sql --commit
```
3. 核对新代码所需的**全部**基线 schema,尤其 `0021_code_sidecars.sql` / `0022_kb_recall_links.sql` / `0023_product_profiles.sql`,不能只看 TTKB 三列。迁移包含 `ADD COLUMN IF NOT EXISTS`,但缺列依然会让新代码查询失败。
4. 发布 control-server + web,并升级目标池 shared/satellite bundle;只重启 server 不会更新卫星 prompt。管理员预装相同版本包,等心跳目录 ready 后开放使用。
5. 验收未选择任务行为不变、两类知识独立展示、成功读文档与导航区分、缺包/混合版本不可选、节点重新注册,以及 Bugfix/Feature/Security 对应接口。
6. 观察派发/读取失败日志、400、心跳 404 后的注册恢复、目录 ready 比例、卫星 I/O。新增心跳 404 应随后转为成功注册,持续 404 需要排查。
## 回退
- **立即停止新任务使用**:新建任务不选择包;这不改变已有任务的选择,没有专用全局 TTKB kill switch。已经启动的 Agent prompt 不会被撤回。
- **代码回退**:安排已运行任务自然收尾或由管理员确认暂停,按正常发布流程回退 web/server/satellite 到已知版本;必须覆盖卫星 bundle。若仅撤销 TTKB,保留已审核的 !36 多语言基线;节点心跳修复可按独立提交保留。
- **保留 schema**:不删除新增 nullable 列、任务选择、包文件或日志;旧版本忽略新增列,保留数据便于重新上线。不要执行破坏性 down migration。
- **包版本回退**:管理员恢复原先记录的版本/commit,统一到整个池,再检查 ready;代码回退不会卸载全局技能投影,必要时由管理员单独处理。任何在途任务的包变更都需协调。
## 验证范围
`bun run test`、`bun run typecheck`、`bun run build`;TTKB 相关测试覆盖发现/覆盖关系/非法 ID、路由池一致性、空选择 prompt 不变、绝对路径与双语导航、直接成功文档读取/跨轮聚合、未知节点 404 后重新注册。
页面截图区分真实本地目录和显式标记的组件 fixture。fixture 用于验证布局、折叠、导航/正文、来源区分及空/不可用状态,不证明某个任务实际采纳,也不替代真机端到端验收。
已采集的页面状态和来源说明见 [评审截图](ttkb-evidence/README.md)。
+359
View File
@@ -0,0 +1,359 @@
# 「验证」线
跑真机、收证据、出报告。**只测试,不产生代码改动** —— 没有分支,没有 MR,终态产物是一份可交互的报告加一个证据包。
报告有四种格式:
- **用例验证**(`case-run`,基础格式,新建单的默认值):拿一份测试用例,在真机上逐条执行,每个检查点给一个结论,附截图和录像。用例从 Bits 测试计划拉取。
- **UI 走查**(`ui-audit`,定制格式):同一批页面在多种语言下各截一遍,逐条记 UI 问题,并把问题标回截图上。建单时在「更多选项」里选,默认不选。
- **CI 包覆盖率验证**(`ci-coverage`,定制格式,**实验,仅管理员**):从一张已经跑完的 bug / feature 单一键建。平台把它 MR 流水线打出的覆盖率插桩包装上,按这张单第一次执行验证过的路径重走,把改动代码尽量都执行到,让覆盖率记到 MR 上;报告把截图、录像和「执行到的改动代码」按时间轴对在一起。见下文「CI 包覆盖率验证」。
- **改动验证**(`change-run`,定制格式,**2026-10-26 起暂停新建**:Skill 不再引导,命令行建单 / 复验由 `routes_cli.ts` 的 `CHANGE_RUN_OPEN` 挡住,已建的照常执行。等机器数量、按需独占实例、热编译唤起就绪再打开):提交人在本地分支改完、推送后,用命令行 `streamline verify`(Skill)建。节点在 agent 起来之前把代码仓检出到被测提交(`satellite/src/change_run.ts`,提交不在远端就直接 `verify_failed`,提示先推送),agent 从这个提交**编译出包**、装上,按提交人用自己的 coding agent 写、本人确认过的用例逐条执行。报告是用例验证的骨架,报告头多「被测提交」、末尾多第 3 节「建议」。它是验证线里**唯一会编译**的格式,但同样不改代码、不提交 —— 想法只能写进「建议」。报告就绪后 `streamline verify get` 把逐条结论和建议带回提交人的会话。
后面还想放回归核验(改动前后同路径对拍)、埋点核对(操作序列 ↔ 上报事件)、竞品对照 —— 它们和 UI 走查一样,是建在「用例验证」这个基础之上的定制格式。
## 为什么要单独一条线
这件事在有这条线之前就已经在跑了,只是被塞进 Feature 里。`e5e4c65c-23a8-4f8d-a63d-637086a22cf3`(TikTok iOS 社交场景走查,61 页面 × 11 语言 / 657 张截图 / 106 条问题)跑完之后:
- 分支 `feature/social-ui-audit-report` **0 commit**,ImplReport 的「Remote delivery」写着 *Skipped — 规约排除 MR,且没有代码改动*。Feature 那一整套分支 / MR / 代码覆盖检查全是空转。
- 真正的交付物(报告、对照图、657 张截图)只能藏在 `evidence/` 里,最后靠一个手工建的飞书文档送出去。面板上看到的可读性报告,是模型把一篇 ImplReport 转述成的图文 —— 106 条问题里它只提了几条。
所以分歧不在「要不要多一个入口」,而在**字段和终态语义对不上**。
## 它是第五条 track,不是 Feature 的变体
库里是自己的一张表 `verifications`(见 `drizzle/0036_verifications.sql`),有自己的 id、状态机、执行模板、runner、接口和统计口径。和另外四条一样,**字段是平行定义,不是共享的**。
最早它是 `features.deliverable = 'report'` 的 feature,理由是「派发、认领、路由、复核都能复用,差别只在交付物和报告格式两处」。跑了一段之后发现,共用一张表的代价不在这两处分叉,而在**它把 Feature 的一切口径都污染了**:
- 服务端的每日创建 / 完成数、周报、KB 效果、证据指标全都按 `features` 表算,走查被计成 Feature 交付,前端再靠 `displayKindOf()` 事后剔一遍 —— 只剔得掉看板,剔不掉服务端统计。
- 执行 prompt 是 Feature 的 `feature.run.*` 模板,再在末尾追加一段「前面那套交付代码的规矩这一轮不适用」。TestSpec、EffectiveSpec、TTKB、拉产品代码仓全照跑,Feature 模板每次改版都顺带改了验证线的行为,而验证线的 prompt 没法独立做版本实验。
- 收尾时 feature runner 仍会走推分支那段逻辑,`e5e4c65c` 因此挂着一个 0 commit 的 `feature/social-ui-audit-report`。
所以拆开。它和 prototype 一样**不改代码仓**(没有 eval、没有确认闸、没有分支 / MR),认领时排在 prototype 之后、其它三类之前。面板上它本来就独立成一档,现在后端也是。改动验证要检出、编译,却仍然插队:提交人正等着结果接着改,不该排在修复单两小时的构建后面。老卫星会把不认识的格式当 UI 走查跑,所以卫星认领时声明自己能跑的格式(`verifyFormats`),没声明 `change-run` 的拿不到改动验证。
同样的道理也用在格式上:两种格式的执行模板、报告契约、面板视图**各是一套**,不是一份模板里的两个开关。出现下一种交付物时,先加一种格式,别往现有模板里塞「只有某种验证才用」的段落。
## 一条任务的全生命周期
| 阶段 | status | 面板读法 | 这一步产出什么 |
|---|---|---|---|
| 建单 | `awaiting_verify` | 待采集 | `verifications.verify_spec`(规约 JSON;用例验证连同用例清单一起落库) |
| 执行 | `verifying` | 采集中 | `evidence/`:截图、录像、`manifest.jsonl`;报告 `evidence/Case-Run-Report.md` 或 `evidence/UI-Audit-Report.md`(UI 走查另有同名 `.ui.txt` / `.navfail.png`;CI 包覆盖率验证另有 `ci-*.json(l)` 四个平台文件) |
| 收尾 | `report_ready` | 报告就绪 | `verifications.audit_report`(面板渲染用的结构化数据)+ `readable_report_html`(几 KB 降级摘要) |
| 复核期 | `report_ready` | — | `verification_notes`:复核人写的期望、以及问题转成了哪张单 |
| 补采 | `report_ready` → `awaiting_verify` | 待采集 | 复核意见追加进 `review_history`,下一轮用第二轮模板在原工作区上补 |
| 终态 | `accepted` / `verify_failed` / `archived` | 已验收 / 采集失败 / 已归档 | 无分支、无 MR、代码零改动 |
UI 走查的「执行」可以是**多段会话**:一段结束后,报告第 3 节还有「待走」场景、预算没用完、这一段确实有进展,节点就起下一段从报告接着走(见下文「长时间走查:预算与接力」)。下面说的终态判定发生在最后一段之后。
执行结束的判据是 Agent 自己打的哨兵:`STATUS: VERIFY_DONE` 且本格式的报告已落盘 → `report_ready`,`STATUS: VERIFY_FAILED` / 没有哨兵 → `verify_failed`。**超时但报告已落盘也判 `report_ready`**:报告是边走边写的,已落盘的部分照样能复核 —— 用例验证里没写到的检查点显示「未报告」,UI 走查里没走到的页面在覆盖矩阵里是「—」,都不会被当成通过;超时且没有报告才是 `verify_failed`;claude CLI 鉴权失败或 API 基础设施错误退回 `awaiting_verify` 自动重排,和 prototype 同一套处理。`report_ready` 时控制面自动触发一次报告生成。
**每一步都落库**:规约(`verify_spec`)→ 过程(`round_digests`,kind `verify`)→ 产物(`audit_report`)→ 人的判断(`verification_notes`)。唯一还在盘上的是证据文件本身,它有自己的 TOS 镜像(owner kind `verify`)。
## 规约与执行模板
`e5e4c65c` 那次能跑成,靠的是有人把整份走查规约手写进了任务描述、agent 恰好读懂 —— 那是运气不是机制。要测什么、语言矩阵、用户形态、报告格式都是**创建时就已知的事实**,应该由控制面下发。
所以建单时收的是结构化规约(`shared/src/verify_prompt.ts::VerifySpec`):
```jsonc
// 用例验证
{ "format": "case-run", "scope": "<补充说明,可空>", "cases": { "source": {…}, "title": "…", "cases": [ … ] } }
// UI 走查
{ "format": "ui-audit", "scope": "社交场景全链路 …", "langs": ["en","de",…], "personas": ["新用户",…],
"scopeTemplate": "tiktok-social-main", "checks": ["【热区】…", …], "budgetHours": 8 }
```
没写 `format` 的是用例验证出现之前的老规约,按 UI 走查处理。
执行模板各自是 `shared/src/verify_prompt.ts` 里的一个常量、各有自己的派发 stage(控制面随任务下发正文),改它不影响 Feature:
| 格式 | 首轮 | 补采轮 | 报告文件 |
|---|---|---|---|
| 用例验证 | `verify.case.first` | `verify.case.second` | `Case-Run-Report.md` |
| UI 走查 | `verify.run.first` | `verify.run.second` | `UI-Audit-Report.md` |
| CI 包覆盖率验证 | `verify.cicov.first` | `verify.cicov.second` | `Case-Run-Report.md`(多一节「覆盖补测」) |
| 改动验证 | `verify.change.first` | `verify.change.second` | `Case-Run-Report.md`(报告头多「被测提交」,多一节「建议」) |
控制面派发时六份一起下发,节点按规约的 `format` 和「本格式的报告在不在」挑一份(`verify_runner.ts::verificationPromptStage`)—— 不让控制面去猜格式和轮次。规约由 runner 渲染成 `{{verifySpecBlock}}`;规约缺失时退回用标题 + 描述当 UI 走查的 `scope`。
**分支。** 建单「更多选项」里和 Feature / Bugfix 一样有产品和自定义分支(`verifications.base_ref`),两种格式里含义不同:UI 走查里它是查「代码位置」的只读基线;用例验证里它是**测试分支** —— 平台不替它出包,执行前让 agent 核对设备上装的包是不是这个分支出的,写进报告头「被测包」,对不上照常执行并标明。
## 用例从哪来:Bits 测试计划与按人授权
建单时贴 Bits 测试计划的执行页链接(`…/quality/plan/scenarios/planDetail/<plan>/manualTask/<id>`),表单当场拉出用例、按模块勾选。
**用例树怎么拆**(`shared/src/test_cases.ts`)。数据来自 `bytedcli -j test-plan mind get`,它自带的 Markdown 导出只列叶子(预期结果),前置条件、步骤、模块层级全丢,不能用。脑图 JSON 里结构是完整的,每个节点带 `nodeType`:`0` 模块 / 标题,`3` 前置条件,`6` 操作步骤,`13` 预期结果。要拆对的一点:**Bits 的叶子不是用例,是检查点** —— 多个预期常挂在同一步骤下。所以一条用例 = 前置条件 + 操作步骤,下面挂若干检查点(Share to story 那份计划:18 条用例、31 个检查点)。编号 `C01…` / `#1…` 在解析时按先序遍历定死,取消勾选不重排,这样编号能对回 Bits 那一行,补采轮也和上一轮对得上。用例清单在建单那一刻随规约落库,派发时不再回 Bits 拉。
**授权。** 读计划用的是**建单人自己**的 Bits 权限:
1. 表单调 `POST /api/bits-cases/fetch`。控制面只认 SSO 解析出的邮箱 —— 前端传的一概不收,否则谁都能借别人的授权读计划。
2. **控制面在本机**执行 `bytedcli --profile sl-<邮箱>`(`control-server/src/bits_cli.ts`),每人一个 profile,凭据互不相干,都存在控制面这台机器上。
3. 没授权 → 表单直接给一个授权链接(ByteCloud 设备码流程,`auth login --begin`),人点开批准,表单每 3 秒轮询 `--complete`,批准后接着拉。refresh token 约 30 天有效,过期了表单会再给链接。
4. 批准的人不一定是建单的人(授权页上登着的可能是另一个账号)。`--complete` 成功后核对 bytedcli 报出的身份,和建单人不一致就清掉这份凭据、报 `mismatch`,让他用自己的账号重来。
为什么放控制面、不放卫星:凭据要固定存在一台机器上,控制面本来就只有一台;而且这样卫星根本不碰 Bits —— 读到的用例随规约(`verify_spec`,一段 JSON 字符串)落库,认领时整行下发给卫星,runner 从里面渲染 prompt,报告组装也从它还原用例清单。卫星上没有任何能以别人身份读 Bits 的接口,也就不依赖集群密钥。
## 报告文件是一份双向契约
prompt 里写死报告的章节骨架,而解析它的是平台的解析器。**两者是同一份契约的两端**,改一边必须改另一边。漂了不会有人报错 —— 解析不出来时面板静默退回普通报告,证据还在但交互式视图消失。
| 格式 | 骨架 | 解析器 | 盯着它的测试 |
|---|---|---|---|
| 用例验证 | `case_run_report.ts::CASE_RUN_REPORT_SKELETON` | `parseCaseRunReport` | `satellite/test/case_run.test.ts` |
| CI 包覆盖率验证 | `ci_coverage.ts::CI_COVERAGE_REPORT_SKELETON`(用例验证骨架 + 第 3 节) | `parseCaseRunReport`(第 3 节当附加章节) | `satellite/test/ci_coverage.test.ts` |
| UI 走查 | `verify_prompt.ts::UI_AUDIT_REPORT_SKELETON` | `audit_report.ts::parseAuditReport` | `satellite/test/verify_prompt.test.ts` |
证据文件名也是契约的一部分:平台靠文件名把截图 / 录像对到检查点或页面上,名字错一个字就「没有证据」。用例验证的示例名由 `caseShotName` / `caseVideoName` 生成,测试断言 prompt 里写的就是这两个函数的输出。
## 报告是一份数据,不是一段 HTML
另外几条线在可读性报告那个位置放的是模型写好的一段 HTML,读完就完了。这条线不行 —— 报告的价值在**看得准、选得动、回得去**,静态 HTML 做不到(`dangerouslySetInnerHTML` 注进面板的 `<script>` 根本不会执行,第一版就是这么丢掉交互的)。
所以节点交付的是结构化数据,存在 `verifications.audit_report`,各格式存同一列、靠 `format` 字段区分:用例验证和改动验证都是 `CaseRunData`(`format: "case-run"`),CI 包覆盖率验证是 `CiCoverageData`(`format: "ci-coverage"`,用例验证的数据 + 覆盖块),UI 走查是 `AuditData`。面板入口 `AuditReportView.tsx` 按它选 `CiCoverageReportPanel`、`CaseRunReportPanel` 或 `AuditReportPanel`。`readable_report_html` 仍然写,里面是几 KB 的**降级摘要**(结论 + 要看的条目 + 体检),给飞书卡片、导出这类不吃 JSON 的消费者用 —— 它是附属品,不是主视图。
数据 100+ KB,所以不跟着条目下发:列表和详情都把它剥掉、只留一个 `hasAuditReport` 布尔,面板真要渲染时走 `GET /api/verifications/:id/audit-report` 取一次。
**报告本身不是模型写的。** 源文件已经是结构化的,再让模型转述一遍只会丢精度,而且**每漏一行都是静默的**。用例验证完全不调模型;UI 走查只问模型一件事(见下文「标注框」)。
**人写的东西单独落一张表**(`verification_notes`):复核人填的「期望怎么改」、以及这条问题最后转成了哪张单。不能塞进 `audit_report` —— 那一列是机器产出,每次重新生成整体覆盖,人边看边写的判断会在下一次 regen 时静默消失。
> **踩过的坑:生成结果是从异步回调回来的。** 节点对报告生成返回 202,真正的结果随后 POST 回 `/api/internal/readable-result`。第一版只在**同步分支**里落 audit 数据,于是线上生成完一切正常、`readableReportGeneratedAt` 也更新了,**但 `audit_report` 始终是空的**,面板静默退回普通报告。加字段时记得两条路径都要过。
### 生成链路
节点上 `readable_report.ts` 收到 kind `audit` 的生成请求后:`Case-Run-Report.md` 在就走用例验证,否则走 UI 走查,两者都认不出才退回模型生成。一个工作区只跑一种格式,两份报告不会同时出现。这段跑在节点而不是控制面,因为要的东西只在节点盘上:证据目录的完整文件清单、`manifest.jsonl`、UI 走查的 `.ui.txt` 结构树和截图像素(证据代理只透出扁平文件,带 `/` 的路径直接 400)。
## 用例验证的报告
按用例组织,检查点是最小单位。每个检查点四种结论之一,外加平台补的一种:
- **通过**:走到了,实际与预期一致,有证据。
- **不通过**:走到了,实际与预期不符。prompt 要求先复现一次、复现那一遍录像。
- **阻塞**:前置条件造不出来 / 进不去 / 设备或账号不够,没走到。不怪被测功能,**不计入通过率分母**,但要写进报告第 2 节:卡在哪、试了什么、还差什么。
- **需人工**:走到了、证据齐,但预期本身没法客观判定(「符合设计稿」却没给设计稿)。
- **未报告**:用例清单里有、报告里没写 —— 平台补的,**不计为通过**。分母只认建单时定下的那份清单,agent 自己加的行丢掉。
汇总数字(通过率、各结论条数)不让 agent 写,平台从逐条结论算;agent 写的数字和它自己的表对不上是常态,两份并存只会让读者不知道信哪个。
面板自上而下:汇总 → **需要你看的**(不通过 → 未报告 → 需人工 → 阻塞,每条带预期 / 实际 / 细节,录像停在出问题的那一刻)→ 全部用例(按模块折叠,有问题的模块默认展开)→ 复核处理记录 → 证据体检。
**证据体检**(全部只看文件,不问模型;判的是「结论有没有东西撑着」,不判结论对错):每个检查点有结论、走到了的检查点有截图、不通过的用例有复现录像、截图落在录制区间内能打点、录像本身过了 `record-evidence` 的校验。
## 录像与打点
一条用例录一段:从执行「操作步骤」开始,到最后一个检查点截完图结束;前置条件的搭建不录。检查点预期是动态的(出现 / 消失 / 跳转 / 动画 / 键盘 / toast)必须录,判了不通过的必须录,静态画面只截图,阻塞的不录。单段目标 60 秒以内,检查点太多就拆段(`case-C05-r1-p2.mp4`)。
**打点不要 agent 多做任何事。** 录制期间 agent 照常在检查点那一刻截图(`case-C05-r1-cp27.png`),平台从 `manifest.jsonl` 里读:截图的拍摄时刻落在某段录像的 start / stop 之间,就换算成录像里的秒数(`case_run_report.ts::caseVideosFromManifest`)。两处校准:
- 截图时刻用 `record-evidence shot` 在按快门前记的 `takenAt`。`ts` 是截完、探测完、跑完校验才写的,会晚好几秒。老 manifest 没有 `takenAt` 时退回 `ts`。
- 录制器起来要时间:挂钟时长比文件真实时长(ffprobe)多出来的那一截,基本花在开头,从偏移里扣掉。
面板上每段录像下面一条时间轴,打点按结论着色;点检查点从打点前 1.5 秒开始播,播到哪、对应的检查点就高亮;链接带 `?case=C05&t=18.2` 打开时滚到那条用例、从那一秒播。**模型不看视频判结论** —— 真值只认执行,录像是给人复核用的。
## CI 包覆盖率验证(实验)
### 为什么有这种格式
Streamline 的 bug / feature 交付物是 Bits 上的一条 MR,MR 的卡点之一是**代码覆盖率**。覆盖率只认流水线打出的**插桩包**在真机上跑出的数据:包里的 SDK 每 60s 把执行过的代码报给 `coverage-data-center`,按 commit 记到 MR 上。平台第一次执行时测的是节点本地构建的包,覆盖率同步不过去,人还得拿 CI 包再手测一遍。这种格式把「第二遍」交给平台,而且**接力**第一遍:第一次执行时验证过的路径(TestSpec 的条件 / 步骤、报告里的验证小节)原样带过来,不用重新摸索。
2026-09-24 用 MR 8439663 在 fei-android-01 上手工走过一遍全链路,结论全部成立:CI 包与节点本地包**签名相同**,`adb install -r -d` 覆盖装、登录态保留;channel `local_test` ⇒ 离线包,TTMock 生效;R8 混淆后 Frida 按 mapping 翻译的名字能 hook;打开任意草稿后等 180s,Bits 行覆盖率 0% → 66.67%。
### 建单:只能从单子上一键建,事实在建单时查定
入口在 bug / feature 抽屉头部的烧瓶按钮,**只对管理员显示**(Android、已有 MR、复核中 / 已完成才出现);建出来的验证任务和报告对所有人照常可见。表单 `POST /api/verifications` 不接受 `ci-coverage` 规约 —— 手写的包信息平台核实不了,装错包白跑一轮还污染 MR 的覆盖率。
`POST /api/verifications/from-source`(`control-server/src/ci_verify.ts`)以**建单人自己**的 Bits 授权(和读测试计划同一份 bytedcli profile,没授权时抽屉走同一套设备码流程)查定:
1. `bits mr status` → project / iid / **最新 commit** / merge base / 流水线 job 与产物;
2. `bits mr packages` → **最新 commit** 那一组里的 `*-local_test-release.apk`(`ci_package.ts::pickCiPackage`)。只有旧 commit 的包 = 流水线还没出新包,返回 409 让人稍后再点 —— 拿旧包等于验证一份已经改掉的代码;
3. 打包 job 的 `jenkins_build_result.json`(公开地址)→ md5、大小、**mapping 地址**;
4. 来源单 TestSpec → 用例(`ci_coverage.ts::casesFromSourceSpec`):C01 的检查点是 bug「修复后验证」/ feature「验收标准」的每一条,前置 / 步骤原文带上;C02 是「改动代码覆盖补测」。
同一张单同一个 commit 已有未归档的,直接打开那一个。
**用哪条 MR,建单时可以改。** 单子上记的 MR 不一定是修复最终落地的那条:`0ed54d79` 记着的 8188853 已关闭,真正在用的 8439663 是后来在另一条分支上手工开的,平台不知道。所以抽屉的确认框里 MR 链接默认填单子上那条、可以改;**已关闭的 MR 直接拒绝**(409 `mr-closed`)—— 它最新 commit 的包往往还在,不拦就会成功建单、认真跑完一整轮,测的却是被放弃的代码。入口除了头部的烧瓶图标,复核清单 / 「修复完成」清单里也有一行「用 CI 包验证 · 跑覆盖率」:执行成功不等于不需要这一步,覆盖率卡点只认 CI 包的数据。
**只有 release 变体插桩**:`gradle/global/buildcontext.gradle` 里 `isOpenJacoco = (jacoco || precise_test) && !isDebug`。CI-Check 那个 `*-local_test-debug.apk` 虽然也带 `jacoco=true`,dex 里没有 `$jacocoInit`,不能用。
### 节点:agent 起来之前装包、之后恢复
`satellite/src/ci_coverage_run.ts`,不交给 agent —— 一半是真值来源(装的到底是不是 CI 包、改了哪些方法、执行到没有),一半是会弄坏节点的操作。
- **准备**:备份设备上的包 → 下载 CI 包(md5 校验,按 URL 缓存在 `~/.streamline/ci-cache`,留最近 2 个)→ `adb install -r -d` → 从 `merge base..commit` 的 diff 算改动方法(`git show <commit>:<path>` 只读,不碰工作区)→ 流式扫 mapping(400+ MB 不进内存)把类名、方法名、参数类型翻译成混淆名 → 生成 Frida 脚本 → 起采集守护。这一段十几分钟(下载 ~1 GB 是大头),期间状态已是 `verifying`,进度在运行日志 `[ci]` 行。装包失败直接 `verify_failed` 并恢复原包,不让 agent 在错的包上跑。
- **采集守护**:每 2s 看一次 App 的 pid,换了就重新 attach(agent 冷启动 App 是常事);attach 连续很快失败时指数退避。事件写进 `evidence/ci-events.jsonl`,已执行 / 未执行的清单实时刷新到 `evidence/ci-coverage-status.md` —— agent 靠它知道 C02 还要去触发哪些方法。
- **收尾**(写终态之前):App 必须活着再等 190s,让 SDK 报完最后一个周期(被 agent 杀了就拉起来,落盘没报的会在启动后补报)→ 停采集 → 装回原包。顺序不能反:终态一落,控制面就让本节点组装报告,报告要读到这一步的记录(`evidence/ci-run.json`)。
### 时间轴:谁的时钟、怎么对齐
Frida 脚本(`ci_coverage.ts::buildCiFridaScript`)只观察、不改行为,挂三类 hook:
- **改动方法**:按翻译后的名字**和参数类型**选重载(R8 会让不同签名的方法共用一个混淆名);mapping 里找不到的方法 = 被内联或裁掉,标「包里没有」、不计入分母,**绝不猜**(带行号的 mapping 里,同区间同混淆名一串中前面的是内联帧,也不 hook)。
- **点击**:`View.performClick` —— 控件在屏幕上的矩形、文案、resource id。agent 用 `adb input tap` 注入的点击不经过 `/dev/input`,`getevent` 看不到,但一定走到 App 里的 performClick。报告里的「UI 区域高亮」就是这个矩形。
- **触摸**:`Activity.dispatchTouchEvent` 的按下 / 抬起(滑动这类没有 click 的操作)。
事件带**设备时间**;frida CLI 走管道有缓冲,到达宿主的时间不可信。所以每 5s 发一次心跳,报告组装时按 `offset = min(recv - dt)` 把设备时间换到宿主时钟上,再和 manifest(录像起止、截图 `takenAt`,宿主时间)对齐。残余误差 = 最快那条事件的传输延迟,USB 上是几十毫秒。
### 报告
`CiCoverageReportPanel`:头部三个数 —— 检查点结论、**改动方法执行到几个**(平台记录)、行覆盖率(链到 Bits,**只有 Bits 能解析插桩数据**,报告不自己估);然后是**回放**:录像上叠被点控件的高亮框和触摸涟漪,改动方法一执行,右侧卡片浮现那个方法的 diff、几秒后淡出,旁白(开始录制 / 点击「…」/ 执行到改动代码 … / 检查点 #n → 结论)随播放滚动、点击跳转,下面三条轨道(检查点 / 改动代码 / 操作)可点;再往下是改动方法清单(点开看 diff、跳到第一次执行)和逐条检查点(每条挂着「拍这张截图之前执行到的改动代码」)。旁白、打点、对应关系全是平台从文件算的,**不调模型**。
体检比用例验证多六项:装的是 CI 插桩包(不可调试、md5 对)、改动方法能在包里定位、代码执行记录、改动方法执行到、覆盖率上报等待、恢复原包。
### 这一版的边界
- **只支持 Android。** iOS 的 CI 包是 iphoneos 的 InhouseRelease IPA(带 `BDTestCoverage`),`deploy.sh` 理论上能转成 macCatalyst,但没验证过;而且 iOS MR 面板上「总插桩行」是 0,流水线是否接了覆盖率要先问覆盖率平台。
- **行覆盖率不自动取。** Bits 的覆盖率接口(`ospApi/codeCoverage/...`)走浏览器会话,控制面能不能以 bytedcli 的授权调用没验证;bytedcli 也没有客户端覆盖率命令。
- **节点要有 frida CLI**:fei-android-01 有;evaluator-android-01 只有 frida-server 没有 CLI,在那里跑时代码执行记录为空(体检 FAIL,用例照常)。
- **补采轮的状态清单是本轮重新记的**:上一轮执行到的方法这一轮没再跑到会显示「未执行」;Bits 上的覆盖率按 commit 累计,不受影响。
- **上线要控制面 + 卫星一起发,卫星先到。** 老卫星的 `parseVerifySpec` 不认识 `ci-coverage`,会把它当 UI 走查跑(不装包、不采集)。入口只对管理员开放,在卫星全部更新之前不要建单。
- **本地插桩构建**(不下载 CI 包,节点自己 `-Pjacoco=true -PpredefinedChannel=local_test` 打 release)在调研中:插件对 `TASK_ID` 为空的本地构建有专门分支(uuid `-1`、TOS 前缀 `local_android`),但这样上报的数据会不会计入 MR 报告还没验证。
## UI 走查的报告
### 生成链路
```
evidence/UI-Audit-Report.md ──parseAuditReport──> AuditReport(覆盖矩阵/逐页问题/BLOCKED)
evidence/screens/<lang>/<page>.ui.txt ──parseUiTree──> UiElement[](含 frame)
│
├── 模型:这条问题指的是哪个控件?只能回 @序号
│
└── boxOf() ──> 百分比框 ──> buildAuditData() ──> verifications.audit_report
```
- `shared/src/audit_report.ts` —— 解析、坐标换算、数据组装、降级摘要。零运行时依赖(要打进卫星 bundle)。
- `satellite/src/audit_report.ts` —— 扫证据目录、收结构树、跑定位、做证据体检。
模型只被问一件事,而且是**封闭选择题**:候选控件连同 `@序号` 一起给出,它只能回序号。最坏情况是选错控件(框画在邻居身上,人一眼看得出),而不是编一个看起来合理、实际不存在的坐标。任何一批定位失败就丢掉那一批,报告照出 —— **没有框比框错好**,面板上那条问题会标「未标框」。
### 坐标换算有一个坑
截图是 macCatalyst 的**窗口**截图,比 App 窗口本身高出一条标题栏。先用宽度定缩放(窗口宽 = 图宽),再用高度差反推标题栏占了多少像素:
```
scale = imgW / winW // 606 / 394 = 1.538
chrome = imgH - winH * scale // 1418 - 854*1.538 = 104px
```
不扣这 104px,所有框整体偏上约 7 个百分点 —— 在 chip 这种 16pt 高的目标上就是完全错位。
### 面板
**默认按问题读**(`AuditIssueReport.tsx`,对照用户期望的交付报告样子做的):批量走查是后续修复计划的入口,所以顶上是「后续执行」—— 已处置进度(转修复 / 无需修复 / 未处置)、修复单各档(待确认执行 → 修复中 → 待复核 → 修复完成 → MR 合入 → 未修好)、按规则挑的「下一步」(最多三条,不调模型)、按严重度 / 按面 / 报告完整度的入口,每个数点了就是把下面的列表筛到那一撮。类别页签(功能 / 热区 / 文案与多语言 / 颜色 / 布局 / 组件规范,老报告的自由类别按关键词归进来)+ 优先级筛选;问题卡里看截图上的标注框、现象、**复现条件与原因**(直接展示不折叠:读者靠它判断是不是真 bug,修的人靠它复现;报告第 4 节问题表的两列,人可以在卡上补充 / 修正,落在 `verification_notes.repro` / `cause`(`drizzle/0056`),人写的优先,转单时原样写进修复单)、证据与检查说明、修复期望,上一个 / 下一个(按列表的显示顺序);「分享」复制 `/verify?id=…&issue=<页面 id>:<序号>`,对方打开直接全屏定位到那一条(多语言这类转不成修复单、要交给别的团队的问题用它)。下面是按「类别 → 功能区(报告里的面)」分组的问题列表,每行「开始修复」或「无需修复」,处置后留在原地显示新状态;勾选后底部结算条「修复所选问题」(同一个面上的合并成一张,见下文「建单」)或「重新检查」(带上所选问题和补充要求,走补采意见那条路,回到采集中)。一条问题在多语言里出现算一条。「无需修复」落在 `verification_notes.dismissed_at`(`drizzle/0055`),可撤销。可全屏(和修复报告同一个外壳):详情在左吸顶、列表在右,选中行高亮。演示页 `control-web/demo-audit-fix.html`。
原来的**按页面看**仍在,外层切换:三栏:页面列表(按面分组,带该语言下的采集状态与问题数)· 截图与标注框 · 检查项与问题。顶上是语言条 —— 切的是截图和命中的问题,不是界面翻译。
**勾选是跨页跨语言累积的**,所以结算条一直吸在底部。每条勾中的问题下面会长出一个选填的「期望怎么改」输入框 —— 捕获点必须在看着那张截图的时候,隔两屏再回忆就变成空话了。
**建单:同一个面合并,复现已确认,直接修**(`POST /api/verifications/:id/fix-batch`,逻辑在 `control-server/src/audit_fix.ts`,分组和正文在 `shared/src/audit_fix_plan.ts`,面板拿同一份代码预览)。原来一条一单:2026-10 的六份走查转出 161 张,每张各自 clean 构建、装包、走到那一页、复现、拍修复前证据 —— 修复一轮中位 59 分钟、构建加设备操作占一半,建单到开跑中位 53 小时,还有 50 张停在「待确认执行」等人点。现在:
- **分组**:同一份走查、同一个面(`### 面 N · …`)的问题合成一张,一张最多 6 条,同一页面的问题不拆开(某一页本身超过 6 条才切开)。161 条 → 39 张。**P0 / P1 和「功能」类单独成单、照常评估** —— 它们是行为缺陷,要真复现。勾了多条时先弹预览,说清会建几张、每张挂哪几条;只勾一条直接建。
- **不复现**:走查截图是真机上的执行结果,按 `docs/rsi.md` 的底线可以当真值。合并单不过评估器:控制面直接写好 TestSpec,以「待确认执行」带方案落库后立刻走 `startTaskExecution` 进修复队列(勾选、写期望的那一下就是确认)。TestSpec 第一段是「复现已确认」声明,`bug.run` 步骤 3 认这几个字(`TRUSTED_REPRO_MARK`,测试钉住两端):不单独复现、不判 UNREPRODUCIBLE,走查截图复制进 `evidence/` 当 `before-*`,修复后逐条回到现场拍 `after-*`,FixReport 加一节「逐条结论」(已修复 / 未修复 / 不成立 / 不在本仓)。**修好几条就交几条**:至少一条已修复就推送、以 FIXED 收尾,其余各条的结论留给复核人;一条都没修好才 FIX_FAILED。原来要求「全部已修复或不在本仓」才算成功,2026-10 的 5 张 FIX_FAILED 合并单里 4 张其实已修好 1–5 条,commit 卡在节点本地;被判「未修复」的多半是走查量错(所以加了「不成立」)或改了没环境验证。走查写的「原因」「代码位置」是走查 agent 的推断,在 TestSpec 里标成线索 —— 线上有走查判成 Lynx 页面、其实是原生 Fragment 的单。建单时勾的检查项里和本单问题同类的那几条,原文写进 TestSpec「走查用的判定规则」:修复侧动手前按同一条规则、同一个参照系复算,不命中的不改代码、记「不成立」,规则套不上的写「规则不适用」,不另定标准;记「不成立」时并排写出双方量的控件、参照和数值。以前修复侧只拿到「按 TUX 规范 / 同类页面的做法改」,各自定标准 —— 2026-10 的合并单里被修复侧推翻的 F-62 / F-18 / F-98 复算下来都是走查量错(参照系取了屏幕边、取了含 padding 的 cell 边界、量了被盖住收不到点击的控件),而 F-39 / F-60 按走查规则修复前并不命中,修复侧却改了代码。间距和热区两条检查项的原文同时改了(到所在容器左边缘、只认可见内容、热区写出来源并对叠放控件做 hitTest);已建的走查规约是快照,不追溯。
- **现场随单走**:每条问题的走查截图、同名 `.ui.txt` 结构树和 `.controls.txt` 控件清单,建单时转存成 plan 图(`img_upload/plan-<uuid>.<ext>`),卫星认领时 `materializePlanImages` 拉进修复单的 `images/`,走查节点的工作区被清掉也不丢;标注框坐标、人补的复现条件 / 原因 / 期望、第 5 节的构造方式、第 6 节的路由一并写进正文。以前只写证据文件名,修复 agent 拿不到图;正文里「进入方式见第 5 节」也是一句悬空的引用。
- **母单与并发**:一份走查转出的单都挂在批次 `audit-<验证 id 前 8 位>` 下(批次中心里就是那张母单,建单人是负责人);同一批同时最多 2 张在修(`AUDIT_BATCH_MAX_RUNNING`,`claimAnyFixForNode` 认领时检查,软上限),免得一份走查占满整个舰队。
- **停泊合并**:合并单建好后先停 15 分钟才让节点领(`AUDIT_PARK_MS`,记在控制面内存里 `audit_park.ts`,重启丢了只是提前开跑);停泊期内、以及之后在队列里还没开跑的时候,同一个面上再转的问题先并进这张单(并满 6 条为止,同页面的优先去已有这一页的单;`planAuditFixMerge`),整张单的描述和 TestSpec 按全部问题重写,用条件更新防和认领撞车(撞了就新建)。只对走查转出的合并单,普通 Bug 单没有停泊。
- **面板引导一起修**:建单前先以 `dryRun` 问服务端会并进哪张、会新建几张,预览里写「并入现有单 +N 条,共 M 条」;单条点「修复」时,同一个面上还有能合并的问题就提示「再加 N 条能凑满这一张、共用一次编译」(只建议凑满一张的那几条,同页面优先);列表每个面的标题上有「选中这一面」。
- **修复单抽屉**:「原始问题与截图」按合并单正文(`auditFiledIssues` 认新旧两种格式)一条一行 —— 缩略图、等级、一句现象、编号 · 页面 · 语言,和走查报告的列表一个样子;点开看带标注框的截图和期望、复现条件、原因(线索)。正文里的 `images/plan-…` 换成 TOS 地址显示。
- **回写**:每条问题的 `verification_notes.filed_task_id` 指向它所在的那张单,几条问题指向同一张;已经转过单、标了无需修复的跳过;某一组建失败不影响别的组。同一份走查同一时刻只跑一个建单请求。
**修复进度。** 走查报告是总表,修复单各自一张。总表不另记进度,只读每张单自己的状态(`verification_notes.filed_task_id` → `GET /api/tasks/:id`,开着报告时每分钟刷新):问题卡上的「已转」变成带状态的链接(修复中 / 待复核 / 修复完成 / MR 已合入 / 未修好 / 已关闭),报告顶部多一节「修复进度」,一单一行、链到单子和 MR、列出它挂着的问题编号。合并单修好几条就交几条,单子状态说明不了每一条,所以单子跑完后(待复核 / 修复完成 / 未修好)再按它最近一批 FixReport 的「逐条结论」逐条显示(`GET /api/verifications/:id/audit-verdicts`,解析器 `parseAuditVerdicts` 和 TestSpec 里规定的结论词是同一份契约,测试钉住两端):「已修复」照旧跟单子状态走;「未修复」显示「这条没修好」、「不成立」显示「复查未见」(和走查结论对不上,附修复 agent 的实测依据),这两种重新算待处置,可以「再转一张」(新单 TestSpec 带上上一张的结论当线索,`不成立` 的先核对两边量的是不是同一个东西)或确认无需修复;「不在本仓」提示用「分享」交给对应团队。编号按问题当前挂着的那张单对,报告重新生成、问题挪了位时会对错,目前不校验。本地演示 `control-web/demo-audit-fix.html`(报告数据读线上只读接口,单子状态是假的)。
**构造态。** 报告第 5 节「状态构造记录」里登记过的页面,在页面列表和截图头上标「构造态」,截图上方写怎么造的 —— 看图的人得知道这一帧不是自然走到的。
**场景可达性。** 覆盖率只统计进得去的页面,进不去的场景根本不在分母里。`e5e4c65c` 的「单元可达率 97.9%」看着很好,但 Story 创作、新用户弹窗顺序、Streak 主页这些整类场景从未进入那 61 个页面。所以 BLOCKED 清单是结构化字段(场景 / 原因分类 / 已做到哪一步 / 解封需要什么),不是正文里的一段话。可达性判断本身会出错:那次复核推翻了首轮的一条 —— 首轮判「Creator 消息套件缺账号做不了」,复核发现设置里换个套件就能进,多覆盖了 6 个页面。做成字段才追得着改。
**证据完备性。** 截图与结构树是否配套、**字节重复检测**、导航失败是否留痕(`*.navfail.png`)、未采集单元、问题是否落到代码行、有没有端到端录像。字节重复那一项是有来历的:那次走查有 10 张截图内容完全相同(隐私弹窗压根没拍到,却按「已采集」计入 279 张),另有 3 起误拍(阿语好友列表拍成粉丝列表、贴纸面板和表情面板同一帧、Streak Pet 拍成贺卡面板)。**全是人工复核才发现的,而它们在落盘那一刻就能机械查出来。**
### 范围模板与关注问题
建单表单(UI 走查)有三样起草辅助,都在 `shared/src/verify_scope_templates.ts`:
- **范围模板**:选了就把一段起草好的范围正文填进输入框,人照样能改、能追加「这次重点看空态」。落库的仍是文字,模板 id 只记来源;模板改版不追溯已建的单。第一份是「TikTok 社交主场景」(Story 创作 / Story 消费 / DM / Profile / Friends tab)。
- **关注问题**:勾几条注入几条(`spec.checks`),**不勾 = 只按范围正文查**,系统 prompt 里没有缺省检查项(以前不勾会补一份写死的六类,含热区 <44pt,范围只写了多语言的 e1e28a58 因此报出 23 条热区);原来的六类是表单上的「常规走查」一组。热区的规范只有 `hit-area-spec` 一份。表单上「添加更多」可以加共享的自定义专项(名称 + 六类之一 + 检查内容),存在 `settings` 表 `verify_check_presets_v1` 一行 JSON,目前所有人都能读写删(`/api/verify-check-presets`);建单时和内置专项一样把全文快照进 `spec.checks`,改了删了不影响已建的单。范围正文的快捷填充叫「常用场景」,仍存在各人浏览器本地。每条带类别(热区 / 布局 / 组件规范 / 文案与多语言),prompt 要求报告「类别」列照填,面板按类别筛得动。**量法写在条目里**:热区、间距从结构树的 frame 算(安卓像素要按 density 换成 dp),字重、组件类名从运行时读(Frida),截图目测判不准这几类。
- **时间预算**:2–12 小时,缺省 6(= 引入预算前的单会话上限)。
- **测试账号**(`spec.accounts`,可选):按用户形态给号(空账号 / 新用户 …)。给了就取真实空态 —— 比 Frida 造的可信,也省掉 agent 自己去账号池里试号(`e3c30b3d` 试了两个号,都有大量数据,还在设备上留下了账号)。prompt 同时禁止登录规约之外的账号。
### 状态构造:进不去的状态可以造出来
走查不是修 bug,目标只是让页面以某种状态(空态、加载失败、断网、无好友…)出现在屏幕上好检查 UI,不需要「真实复现」。所以 prompt 给了一个从低到高的阶梯,三档都试过才允许写「BLOCKED(缺数据)」:真实操作 → 环境手段(断网、TTMock)→ **Frida 改数据**(把列表数据源 / ViewModel / 解析后的回包改成空或失败,再刷新)。规矩:脚本存 `evidence/hooks/`、报告第 5 节登记;hook 不许跨页泄漏,但脚本自带 `dispose()`、复原能确认的就不冷启(`e3c30b3d` 一轮冷启了 29 次,每次连带重新导航),只有动过缓存 / 单例 / 全局开关才冷启;只因构造本身才出现的异常不记成问题。平台相关的 attach 方式由 runner 按探测到的基线渲染进 `{{fridaBlock}}`。
**Frida 报错不等于阻塞。** 2026-10-14 扫了 6 个用过 Frida 的会话(5 个原型 + `4c3b7d32`):10 次 Frida 报错里 8 次 agent 在后续序列里自己恢复了(重启设备上的 frida-server、清残留 helper、修脚本、补 PATH、冷启 App),剩下 2 次都有已知解法、只是放弃得太早 —— `4c3b7d32` 遇到 `unable to intercept function` 重试一次就转去抓包、把 Frida 记成「环境」;`766f1074` 第 1 轮 iOS attach 一直超时判了失败,第 2 轮先清 helper,**普通用户**就挂上了(所以「iOS 必须 root、`sudo -n true` 要密码就不可用」这条是错的)。prompt 因此带一张「现象 → 解法」自救表,表里的解法没试完不许写 BLOCKED,并要求在「已做到哪一步」逐条写试过什么。复核可达性时同样按这个口径:**看后续序列有没有自己恢复,恢复过的或有已知解法的都不是 hard block。**节点兜底:每段会话结束都清掉命令行带工作区路径的 frida 进程、安卓 `svc wifi enable`。
### 长时间走查:预算与接力
一段 `claude -p` 会话越拉越长,上下文就越来越糊;`4c3b7d32` 那种一小时就自认「走完了」收工的情形也常见。所以长走查交给**多段会话**:
- prompt 要求开工先把规约范围拆成场景清单,**全部写进报告第 3 节、状态「待走」**,走完一个移走一个。「待走」行是段与段之间唯一的交接物 —— 它在报告里,不在模型上下文里。
- 一段结束后(`verify_runner.ts` 的循环),满足全部条件就起下一段:报告里还有「待走」、剩余预算 ≥ 15 分钟、段数 < 8、这一段证据目录或报告有变化(防空转)、这一段没打 `VERIFY_FAILED`、不是鉴权 / API 错误。接力段的 prompt = 一段开场白(第几段、已用 / 剩余、还剩几个待走)+ 本轮完整 prompt。
- 日志追加到同一个 `session-r<n>.log`(面板只认一个 logPath);哨兵和卡死看门狗只看本段新增的部分,否则上一段的 `VERIFY_DONE` 会让下一段一起来就被掐掉。
- 预算用完时仍是「待走」的场景,在可达性表里显示「未走到」,不计为通过。
- **按上下文体量交棒。** `e3c30b3d` 两段会话的上下文都从 68k 线性涨到 550k+、一次没压缩(模型有 1M 窗口),每一步都把整段重读一遍 —— 那一单约 $78 里八成是读缓存。而接力段开场只要几分钟、68k 起步,所以更早交棒更划算:节点每次轮询从日志尾部读主会话最近一次调用的上下文大小(子 Agent 的不算),超过 200k(`VERIFY_HANDOFF_CTX`)建 `logs/HANDOFF`,prompt 要求 agent 每走完一个面检查它、存在就落盘交棒;超过 360k(`VERIFY_HANDOFF_HARD_CTX`)直接截断本段照常接力(报告边走边写,最多丢正在做的那一页)。
- **看图节制。** 同一单读了 143 张全分辨率截图,占工具输出的 48%。热区、间距、字重、类名、文案是否带「…」从结构树 / Frida 控件清单读数判断;要用眼睛看的先 `sips -Z 480` 缩略,成批核对交给子 Agent、只回文字。
- **改报告走 `audit-report` 命令,一次改一处。** `00889383` 写了 122 次报告、其前的思考共 34 分钟 —— 每次把整份 Markdown 读出来拼字符串整段写回,越往后越贵,还把表格改坏过。`bin/audit-report.ts`(打进卫星 bundle 的子命令,核心在 `shared/src/audit_report_edit.ts`)提供 `init / page / issue / cov / scene / done / construct / route / recipe / summary`,格式由它保证、和解析器同一份契约,写入先落临时文件再改名(会话被截断也不会留下半份报告)。命令全名由节点渲染进 `{{auditReportCmd}}`。
- **等界面用 `wait-for --ui-text`,不写死 sleep。** 两张走查单每轮 16–21 分钟耗在 `sleep` 上。`--ui-text '<正则>'` 每秒读一次结构树,出现即返回;`--ui-gone` 等加载提示消失;默认 30 秒、上限 3 分钟,等不到时打印当前屏幕上的文案(这正是早先禁止拿 `--until` 等 UI 的理由 —— 只知道没等到、不知道在哪一页)。这一条写在所有任务共用的等待块里,修 bug / Feature 同样受益。
- **Android 别拿 `actl_screenshot` 看屏幕**:它把整张图返回进上下文,`00889383` 调了 168 次、占工具输出 39%。
- **长语言对照放最后。** 主语言把所有场景走完后一次切换、逐页补拍、一次复原,在第 3 节是最后一行「待走:长语言对照」。`e3c30b3d` 切了 4 次德语,每次都要冷启并复原切语言带出的两项翻译设置。
- 代价:验证插队在修复单前面,12 小时的走查就是占住一台节点半天。
### 已知路由与做法:跨任务积累
每次走查都在重新摸同样的入口(Story 归档要从精选进、Followers 要从 Following 里切 tab)和同样的坑(Story 创作入口卡在相册授权框、切德语带出翻译设置副作用),而这些只写进了那台节点本机的记忆。所以:
- 报告新增**第 6 节「路由与经验」**:两张表,`页面 | 中文名 | 怎么进` 和 `场景 | 管用的做法`,写给下一个 agent 看。解析进 `AuditData.report.routes / recipes`,随报告数据落库。
- 派单时控制面取同平台最近 6 份 UI 走查报告的第 6 节,按「新的覆盖旧的」合并(`mergeAuditKnowledge`,上限 150 条路由 / 40 条做法),作为 `runPromptTemplates["verify.knowledge"]` 随模板一起下发;节点渲染进 `{{knowledgeBlock}}`,前面再拼上写在代码里的**平台配方**(`verify_prompt.ts` 的 `IOS_RECIPES` / `ANDROID_RECIPES`,从 `e3c30b3d` / `4c3b7d32` / `a614077e` 的日志里沉淀:MTLJSONAdapter 清空列表、Reachability + TTNet 改写断网、相册授权打通 Story 创作、各类权限被拒的真正读取点、App 内切语言及复原、SCK 截图守护重启、DeviceSim 假相机等)。prompt 要求先照着走、走不通再探索,并把新路由写回第 6 节。
- **只给 UI 走查。** 用例验证 / 改动验证 / CI 包覆盖率验证不经过页面,修 bug / Feature 要的是真实复现 —— 它们的 prompt 都不带这一块(测试里断言了)。其中的环境坑(截图守护、假相机)对所有 iOS 任务都有用,但那属于节点自己维护的 DeviceSim skill,应该写在那里,不往别的线的 prompt 里塞。
### 解析器对契约漂移的兜底
agent 写报告不会百分之百照骨架来,每处漂移在面板上都是静默的失真,所以解析器对见过的几种都兜住了(`00889383` 一次撞上四种):
- `.ui.txt` 前面拼了说明 / Frida 视图树、uiautomator 的 XML 在文件中段 → 从 `<hierarchy` 截起解析(那一单原先 122 张里只有 8 张画得出框)。prompt 同时要求 `.ui.txt` 只放原始结构树,Frida 的另存 `.controls.txt`。
- 走完的场景写成「已覆盖」留在第 3 节 → 不算阻塞(原先在可达性表里显示成 13 行「未覆盖」)。
- 第 5 节多加了别的说明表 → 只认表头第一格是「页面」的那张。
- 覆盖矩阵补进来的全绿页只能按 id 猜出「面 3」→ 并到同序号的全名面上,按功能区分组不再裂成两组。
### 取证与基线的两处修补
- `record-evidence` 不许同名覆盖已通过的证据,而文件名是平台契约(页面 id / 检查点编号)—— 拍错一帧就只能空着(`e3c30b3d` 丢了 2 张德语帧)。现在可以显式 `--replace "<作废原因>"`:旧文件(连同 `.ui.txt` / `.controls.txt`)改名为 `<名>.replaced-<n>.<ext>` 保留,manifest 记一条 `void`(原因、去向),之后同名可重拍。不带这个参数时行为不变 —— 所有任务类型共用这个工具,只多了一个显式开关。
- iOS 基线探测只认 `~/iosapp/TikTokM.app`,而 DeviceSim 节点上 App 跑在 cat-supervisor 实例里,报告头的「被测包」一直是空的。现在找不到时退到 `cat-supervisor list`(正在跑的实例优先)读实例包的 Info.plist,bundle id 去掉 `.dsim.<实例>` 后缀。包里没有源码 commit(`AWEBuildInfo.json` 为空),代码位置仍按 develop 查,prompt 要求在「代码索引基线」写明;大仓 `git grep` 先缩目录、攒一批后台查(那一单撞过两次 120 秒超时)。
## 迁移
`drizzle/0036_verifications.sql` 建表并把存量搬过去:`features.deliverable = 'report'` 的行连同 `audit_report` / `verify_spec` / `audit_notes` 一起进 `verifications` / `verification_notes`,**id 不变**(节点工作区 `~/taskLog/<id>/` 和证据路径都按 id 找),辅表(`readable_report_runs`、`readable_sources`、`task_transitions`、`round_digests`、`evidence_capture_events`、`evidence_media`)里挂在这些 id 上的 kind 一并改挂,然后从 `features` 删掉这些行。它只建表、搬行、删行,不删列,所以在旧进程还跑着时执行是无害的。
`drizzle/0037_drop_feature_verify_columns.sql` 删掉 `features` 上的三列和 `audit_notes` 表,**只能在 0036 执行且新代码已上线之后跑**。
上线顺序(每一步迁移都是生产写操作,由人执行):
1. `bun scripts/apply-migration.ts drizzle/0036_verifications.sql`(预演)→ `--commit`。
2. 部署新代码(控制面 + 卫星)。
3. **再跑一次 0036**。它是幂等的;第 1 步到控制面重启之间,旧进程仍接受 `POST /features {deliverable:'report'}`,这段窗口里新建的验证会留在 `features` 里,不搬就会被新代码当普通 Feature 派发、跑出代码。
4. `SELECT count(*) FROM features WHERE deliverable = 'report'` 为 0 后,跑 0037。
卫星热部署在等空档、或有推不上去的节点时,旧卫星还在认领。控制面按认领请求里有没有 `excludeVerificationIds` 字段判断卫星是否认识验证线,老卫星不会被派到验证任务 —— 否则它会把验证当 feature 处理、崩在认领里,任务卡死在 `verifying`。
老的 feature 深链(`?feature=<id>`)指向已迁走的 id 时,面板回退去查 `/api/verifications/:id`。
用例验证不需要迁移:规约和报告数据都复用原来的列,只多了 `format` 字段。
## 上线用例验证要做的
- **在控制面那台机器上、以运行服务的账号装 bytedcli**(`NPM_CONFIG_REGISTRY=http://bnpm.byted.org npm install -g @bytedance-dev/bytedcli`)。服务的 PATH 里找不到时,在控制面的环境里设 `BYTEDCLI_BIN` 指向它;bytedcli 是 node 脚本,它所在目录会被放到 PATH 最前,同目录的 node 才找得到。没装时表单会显示「控制面这台机器没有安装 bytedcli」(503)。
- **控制面 + 卫星一起发。** 用例验证的模板、`record-evidence` 的 `takenAt`、报告组装都在卫星上;老卫星会把 `case-run` 规约当 UI 走查跑。
## 还没做的
- **执行结果回写 Bits**(第二期):把每个检查点的结论和证据链接填回测试计划,QA 在 Bits 里直接看进度。bytedcli 没有封装(`bits autocase run report` 只写本地 `report.json`);后端有 `ExecuteTestPlan`,要直接调,而且是写 QA 的计划,需要单独确认。叶子节点 id 已经随用例存下(`TestCheckpoint.leafId`)。
- **UI 走查还不能叠加在用例验证上**。现在两种格式二选一;「按用例走、顺带在经过的每一屏上做 UI 检查」要等 UI 走查改造成附加检查。
- **打点帧与截图的一致性校验**:在打点时刻从录像抽一帧和同名截图比对,对不上说明打点或截图有问题。现在只校验打点落在录像时长内。
- **只认测试计划执行页**(manualTask),单条用例链接(caseDetail)和 scenario plan 本身还不认。
- **不碰代码仓只靠 prompt 约束**,代码层没有硬闸门(和 prototype 一样)。
- **合并单的「逐条结论」还没解析回来**:FixReport 里已经按声明写了每条问题的结论,但报告页上一条问题的状态仍然读整张单的状态。要加 `verification_notes.fix_outcome` 和解析器(prompt 骨架和解析器是同一份契约)。
- **第 5 节的构造脚本没有随单下发**:脚本在走查工作区的 `hooks/` 子目录里,证据代理不透出子目录;现在只带「怎么造的」那段说明,修复 agent 照说明重写。
- **UI 走查建单去重口径**:同一条问题在不同语言下算不同的单。要改成一单多语言,把 key 从 `page#n@lang` 改成 `page#n` 即可 —— 但 `verification_notes` 的主键也要跟着改。
- **UI 走查的定位占着节点的可读性报告信号量**:12 批跑完之前,这台机器上别的报告排队。要么把批次上限压到 4–6,要么给定位单开一个并发档。
- **`.ui.txt` 取不回控制面**(证据代理不透出子目录),所以只有节点能算框;控制面没法复算,人也没法手工校正一个画歪的框。
- **历史任务不会被追溯重写**,要回填(且回填是生产写操作)。
- **没有跨任务聚合**:单个任务内能看可达性、覆盖和通过率,但看不到「这几轮验证在变好还是变差」。
@@ -0,0 +1,214 @@
# 逼近 AI 代码实现报告可读性的极限
一份关于「如何科学地把 AI 生成的代码实现/修复报告,逼近可读性的极致边界」的工程方法论。
> 素材来源:本仓库中 readable-report 管线的完整演进史(`shared/src/readable_prompt.ts`、`control-server/src/lab_db.ts`、`satellite/src/{runner,feature_runner}.ts`),以及 jingyuan.yi 名下从 `0584742`(管线雏形)到 `5ce7596`(demo 视频成为核心证据)的一连串提交。本文把这些提交里的「为什么」抽象成可迁移的原则。
---
## 0. 先把问题的形状看清楚
我们要优化的不是「一段 prompt」,而是**一条两段式管线**:
```
[Runner Agent] [Readable Generator] [Host 渲染]
干活的 agent ──写──► FixReport.md ──喂──► 第二个 LLM ──产出──► llm-report HTML ──► reviewer 眼睛
ImplReport.md (verbose 工程原文) (pixel-blind) (封闭 class 词表)
▲ ▲
生产者:证据、根因、验证都在这里产生 格式化者:只做「压缩 + 结构化」,看不见像素
```
目标函数(写死在 prompt 里,`shared/src/readable_prompt.ts:54`):
> reviewer 在 **60 秒内**理解:用户/评审关心什么 · 根因 · 改了什么 · 怎么证明的 · 验证的局限与回归风险。
注意读者是 **reviewer 而不是终端用户**。这决定了「可读性」在这里的定义不是「好看」,而是 **信息密度 × 可信度 / 阅读时间**。后面所有 know-how 都是这个分式的因式分解。
---
## 1. 第一性原理:可读性 = 信息密度 × 可信度,不是排版
把目标函数拆成三个可优化的乘子,逐个击破:
**① 提升信息密度 —— skip-don't-pad。**
prompt 里反复强调的一句话是「**ONLY when the source actually has that data — skip a block entirely rather than padding it with an empty card**」(`readable_prompt.ts:82`)。空卡片、凑数的段落是负信息:它稀释密度、还骗过读者以为「覆盖全了」。
→ 宁可少一个 block,不要一个注水的 block。
**② 保护可信度 —— 反过度声称。**
「never overclaim validation; when live/E2E proof is missing, say so via the note block」。系统专门给「验证被阻塞/缺失」造了一个视觉出口:琥珀色 `llm-report__note` + `⚠ 阻塞` 的 metric。**给诚实一个专门的位置**,模型才不会用乐观的措辞去填补空白。对 reviewer 而言,一份敢说「活体复现环境离线、我没能证明」的报告,比一份滴水不漏的漂亮报告更可信。
**③ 压缩阅读时间 —— 分层 + 渐进式披露。**(见 §5)
这三条是纲。剩下的章节都是在讲「怎么在工程上真的做到」。
---
## 2. 决定性洞察:下游的天花板在上游(pixel-blind 定律)
这是整条管线里**最重要、也最反直觉**的一条,值得单独成章。
格式化者是 **pixel-blind** 的——它拿到的是一堆截图**文件名**和报告里对每张图的**文字描述**,它从来没有、也不可能「看见」像素。提交 `d2934ed` / `520412d` 的 message 把这句话钉死了:
> The readable-report generator is pixel-blind … so **ImplReport quality is the ceiling**.
推论极其锋利:**你无法把第 N 段打磨到超过第 N-1 段给它的信息量。** 当读者觉得报告「说不清这张图证明了什么」,99% 的情况不是格式化 prompt 不行,而是**上游的 runner 根本没在原文里讲清楚这张图证明了什么**。
所以这两个提交做的事,不是改 readable prompt,而是**回头去改「干活的 agent」的 prompt**(`buildSinglePrompt` / `buildFeatureFirstPrompt`):
- 要求 runner 用**语义化证据命名**;
- 要求 runner 产出一份**测试图清单**;
- 把 FixReport 的章节结构**重排成与下游 block 一一对应**。
> **工程 know-how #1:要提升第 N 阶段的产出,先去优化第 N-1 阶段。** 在 prompt 上反复微调下游,收益会迅速见顶;真正的边界由上游的信息供给决定。定位问题时永远先问一句:「下游想渲染的这个东西,上游到底喂给它了没有?」
---
## 3. 把每一次跨阶段交接,变成一份被校验的契约
既然两个阶段之间是「盲」的,那它们之间传递的每一个 bit 都必须是**显式契约**,而不是靠模型「悟」。
### 3.1 语义化证据命名 = 盲阶段之间的唯一带宽
命名约定:`<phase>-<round>[-NN]-<slug>.<ext>`,phase ∈ `before / after / flow / mech / edge / demo`。
对一个看不见像素的格式化者,**文件名本身就是它能读到的最结构化的信息**。`before-1-xxx.png` 和 `after-1-xxx.png` 同名同场景配对,格式化者才能把它们拼成决定性的「修复前/修复后」对比(`readable_prompt.ts` 的 `测试图对比` block)。
### 3.2 测试图清单(shot index)= 把「文字描述」也变成契约
`520412d` 要求 runner 额外产出一份清单:**每张截图 + 一句「它证明了什么」+ 角色**。commit message 里那句话是点睛:
> the **only thing** the generator can read to pick and caption images.
这就是在承认「你看不见图,所以我把图的语义先替你写成结构化文本」。
### 3.3 URL-free 证据契约:不让模型 mint 自己无法核实的标识符
格式化者**绝不允许**输出 `<img>` / `src` / `href` / 任何 URL——因为它一定会幻觉出不存在的路径。取而代之:模型只在 `<figure>` 上写 `data-evidence="<精确文件名>"`,host 拿这个文件名去解析成真实 URL,**幻觉出的名字直接被丢弃**(`16feaaa`:hydrateShots/injectShots)。
> **工程 know-how #2:凡是模型无法自行核实的标识符(URL、ID、路径),都给它一个封闭清单 + 占位符间接层,最终在宿主侧做校验丢弃。** 幻觉不是靠「叮嘱模型别幻觉」消除的,是靠「让幻觉在架构上无处可去」消除的。
这条同样体现在 runner 侧:run 的成败靠**终止哨兵**(`STATUS` / `ASSESSMENT`)判定,而不是退出码——`9776cd1` 揭示,pty wrapper 会给 API Error 合成一个假的 `success` 帧,只有显式哨兵才能区分「agent 真的下了结论」和「基础设施把它打断了」。**契约要显式,不要从副信号里猜。**
---
## 4. 约束输出空间:封闭词表 > 开放建议
这是把「格式化者耦合到渲染器」这件事做到底的一步,也是可读性从「像 AI 随手写的」跃迁到「像人精心排的」的关键。
对比 v0(`0584742`)和 v1(`9dc9abb`)的措辞:
| | v0(雏形) | v1(现行 SSOT) |
|---|---|---|
| class 约束 | 「class names **must be prefixed** with llm-report」 | 「**Use ONLY these classes. NEVER invent** — an unknown class has zero styling and renders bare」 |
| 结构 | 「**Suggested** class structure」 | 「MUST use the structural markup … Do NOT collapse into plain `<p>`」 |
为什么这个改动是决定性的?因为 host 页面的 CSS 只给**一组固定的 class** 上了样式。模型一旦发挥创意造一个新 class,那段内容就以**零样式的裸文本**渲染出来——排版当场崩掉。开放式的「建议」必然导致漂移;**封闭词表把输出空间收缩到「渲染器真的能渲染」的那个子集**。
同理,「结构化标记 vs 裸 prose」也是一条硬规则:模型的默认倾向是写段落,而段落在这个 host 上「completely unstyled」。所以 prompt 用大量篇幅给出 timeline / cards / steps / metrics 的**逐字模板**,堵死「塌回 prose」这个失败模式。
> **工程 know-how #3:生成结构化 UI 时,prompt 必须精确暴露「渲染器能渲染的那张表面」,并显式禁止一切表面之外的发挥。** 生成器与渲染器是一对必须同步演进的耦合体——每加一个 CSS class,就得同步进封闭词表;每进一个词表项,host 就得有对应样式。二者漂移,报告立刻裸奔。
---
## 5. 分层与渐进式披露:为「60 秒」做减法
阅读时间这个分母,靠两件事压下来。
**① 双语域分层——同一份报告服务两类读者。**
- `大白话总结`:写给零 Android/Compose 背景的 PM/设计,**禁止**出现任何方法/变量/框架/OS 名,允许一个类比,把**唯一**的关键修复思路包进一个 `<em>`。
- 其余 block:给工程师看,标识符一律 `<code>` 保留原文。
一个 artifact,两个寄存器,读者各取所需,谁都不用读对自己是噪声的那半。
**② 渐进式披露——把「crux」浮上来,把「全量」折下去。**
- `关键代码变更` 只放 **单个最决定性的 hunk,≤25 行**,其余用一行 `…` 省略,且强制装进**默认折叠**的 `<details>`(`4436c40`)。全量 diff 是噪声,crux 才是信号;默认收起,让报告的「阅读海拔」始终保持在高处。
**③ 证据分级——最有力的证据顶到最前。**
证据形态经历了三次进化,每次都把「更决定性的证据」往前提:
```
截图 (16feaaa) ──► before/after 英雄对比 + 验证画廊 (16feaaa/7ff55d4) ──► 端到端 demo MP4 置顶 (5ce7596)
```
`5ce7596` 让 demo 录屏成为「核心证据」,排在前后对比截图**之前**。值得学的实现细节:media-hero 模板是用**字符串手术**从 baseline 派生的(`readable_prompt.ts:315`),共享 block 一个字节都不会漂移,只有媒体那一段不同——**变体不靠复制粘贴,靠从 SSOT 派生**。
---
## 6. 决定论与鲁棒性:容易被忽视的底座
可读性的边界,一半输在这些「不性感」的底层细节上。
**① 语言必须是无条件显式指令。**
`527a2db` 的教训:prompt 里没写死输出语言时,只要上下文是英文,模型就**漂移到英文**。修复是加一条无条件指令 + 列清例外(`<code>` 里的标识符、固定中文标签保持原文)。凡是「希望模型总是 X」的属性,都不能靠上下文暗示,必须显式写死并枚举例外。
**② 替换层要抗污染。**
`renderReadablePrompt`(`readable_prompt.ts:363`)有三个刻意设计:源 markdown **最后**才替换(防止其中的 `{{...}}` 或 `$` 破坏后续替换);用**函数式** replace(绕开 `$&`/`$1` 的特殊模式解释);超长**显式截断**并留 `[TRUNCATED]` 标记。不可信内容永远最后注入,是模板拼装的基本卫生。
**③ 警惕「数据缺失」伪装成「prompt 不行」。**
`1b1db98` 是最好的反面教材:多轮修复的 `修复历程` timeline 一直渲染不出来,看起来像 prompt 问题。真相是——**磁盘上每轮只保留一个 FixReport.md,agent 每轮覆盖它**,所以下游根本没收到多轮数据。commit message 一针见血:
> The prod prompt template is **already multi-round-aware** … so **no prompt change was needed — it just never received the data**.
修复在数据管线(按轮归档进 `fix_report_versions`),不在 prompt。
> **工程 know-how #4:调 prompt 之前,先确认 prompt 真的收到了它索要的数据。** 「prompt 已经会渲染 X,只是从没拿到 X」是这类系统里最高频、最费解的一类 bug。
**④ 生产者的鲁棒性 = 报告的保真度。**
`9776cd1`:API Error 打断的 run 会缺终止哨兵,旧逻辑把「没有哨兵」误读成真实结论(假的 `fix_failed`),污染源报告。让生产者能从基础设施抖动里恢复(in-session 续跑 + 有界重试),下游报告才有干净的原料。
---
## 7. 让「逼近极限」变成可操作的闭环,而不是玄学调参
前面都是「怎么写得更好」,这一章是**「怎么科学地知道自己写得更好」**——没有这个闭环,所谓「逼近极限」只是碰运气。
### 7.1 把 prompt 当成版本化的生产制品
`77ca594` 之后,prompt 不再是散落在代码里的字符串,而是一套完整的制品体系(`lab_db.ts`):
- **SSOT**:模板只有一份权威源(`shared/src/readable_prompt.ts`),control plane 和 satellite 都 import 同一段文本,**两个构建之间零漂移**。
- **生产只跑代码**:新任务永远用 `DEFAULT_READABLE_PROMPT_TEMPLATE` 渲染,改它 + 部署即生效,回滚就是 revert。`readable_prompts` 表只存实验室里的草稿版本(试跑、批量重刷、对比用),每次生成的 run 都快照了当时的正文。曾经有一个 `readableActivePromptId` 指针决定生产用哪一行、新基线「插入但不自动激活」——结果代码基线两次在库里躺了数周没人切(2026-07-31、2026-09-11),2026-10-12 拆掉。
### 7.2 一个便宜、可逆的实验台
Lab(owner-only)提供真正的实验能力:
- **test / compare / save**:拿候选 prompt 在真实 target 上跑,readable-over-raw 并排对比。
- **adhoc 无 workspace**:候选 prompt 能在**任意在线节点**上跑,不需要 checkout 工作区——实验成本被压到最低。
- **批量存量更新(`4436c40`)**:选一批历史报告,用新版本一次性异步重刷,有界并发 `min(liveNodes,3)`、单活跃任务锁、重启后 orphan 回收。让「换一版 prompt」能立刻在整个存量上看到效果。
- **每版本归档 + 决定论排序(`6fa1af0`)**:生产生成会按 prompt 版本归档每次 run,按 `finishedAt` 排序取「该版本最新代表」,**即使两次 run 同一毫秒也能确定性地选出代表**——版本之间才能公平 diff。
> **工程 know-how #5:要逼近一个没有解析解的边界,你需要的不是更聪明的一次尝试,而是一个「改一版 → 在真实存量上立刻可见 → 可确定性对比 → 可一键回滚」的短反馈环。** 方法论的重心从「设计完美 prompt」转移到「让糟糕 prompt 的代价趋近于零」。
---
## 8. Know-how 速查表
| # | 原则 | 一句话 |
|---|---|---|
| 1 | **上游即天花板** | 下游 pixel-blind,要提升第 N 段先改第 N-1 段 |
| 2 | **交接即契约** | 语义化命名 + shot index + `data-evidence`,盲阶段之间只走显式契约 |
| 3 | **幻觉无处可去** | 模型无法核实的标识符 → 封闭清单 + 占位符 + 宿主侧校验丢弃 |
| 4 | **封闭词表** | 只暴露渲染器能渲染的表面,禁止一切发挥;生成器与 CSS 同步演进 |
| 5 | **结构 > prose** | 逐字给结构模板,堵死「塌回段落」这个默认失败模式 |
| 6 | **skip-don't-pad** | 没数据就整块跳过,空卡片是负信息 |
| 7 | **给诚实留位置** | 造一个「验证阻塞」的专属视觉出口,模型才不用乐观措辞填空 |
| 8 | **分层双语域** | 大白话(零术语)+ 工程层(`<code>`)服务两类读者 |
| 9 | **渐进式披露** | crux ≤25 行浮上来,全量 diff 折叠下去,保持阅读海拔 |
| 10 | **证据分级** | 最决定性的证据顶到最前(demo MP4 > 前后对比 > 画廊) |
| 11 | **语言写死** | 无条件输出语言指令 + 枚举例外,别靠上下文暗示 |
| 12 | **替换抗污染** | 不可信内容最后注入、函数式替换、显式截断 |
| 13 | **先查数据再改 prompt** | 「模板已会渲染 X,只是从没收到 X」是最高频的伪 prompt bug |
| 14 | **SSOT** | 一份权威模板(代码常量)就是生产;实验版本只在实验室里跑;回滚 = git revert |
| 15 | **短反馈环** | 存量批量重刷 + 决定论归档,让换一版 prompt 的代价趋近于零 |
---
## 9. 边界在哪里,以及下一步往哪走
诚实地标出这套方法**还没触达**的边界:
1. **真正的 pixel-aware。** 当前整条链路的根本约束仍是「格式化者看不见图」。所有的语义化命名、shot index,本质都是在**绕过**这个约束而非**解除**它。下一个数量级的提升,来自让报告生成真的具备多模态读图能力——那时 §3 的一大半契约可以退化简化。
2. **目标函数仍靠人眼评测。** 「60 秒读懂」目前没有自动度量。真正把「逼近极限」做成科学,缺的最后一块是一个**自动可读性评分器**(哪怕是一个 LLM judge:给它报告,问它能否在约束内答出影响/根因/改动/验证/局限)——有了它,§7 的实验台就能从「人肉并排看」升级成「跑分驱动的搜索」。
3. **证据形态还会继续进化。** 从截图到 demo MP4 是一条清晰的上升曲线,下一站可能是可交互的复现步骤、或把 trace/日志作为一等证据。
---
### 结语
「逼近可读性的极致边界」听起来像一个措辞问题,做下来发现它**几乎全是工程问题**:把目标函数写清楚、认清下游的天花板在上游、把每次盲交接变成被校验的契约、把输出空间收缩到渲染器的真实表面、再用一个便宜可逆的实验闭环把每一次改动的代价压到趋近于零。prompt 措辞只是浮在最上面那一层——底下真正决定边界的,是**契约、数据完整性、和反馈环的工程**。
> 演进轨迹一览:`0584742`(管线雏形) → `9dc9abb`(封闭词表 + 结构模板) → `527a2db`(语言写死) → `77ca594`(版本化 lab) → `16feaaa`(测试图契约) → `d2934ed`/`520412d`(上游即天花板) → `1b1db98`(数据 > prompt) → `4436c40`(折叠 crux + 批量重刷) → `6fa1af0`(决定论归档) → `5ce7596`(demo 视频成为核心证据)。