Initial import of streamline
This commit is contained in:
@@ -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。
|
||||
@@ -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.
|
||||
@@ -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`;没有该变量时跳过。该测试明确不提供安全扫描节点,验证无模型依赖的自动分发、管理员分类/确认、只读旧载体、幂等、停止保护和客户端协议兼容。
|
||||
@@ -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).
|
||||
@@ -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`(上传、上报人更新、他人重发忽略、分类随报告更新但不覆盖管理员分类、管理员读取)。
|
||||
@@ -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 上传/回读和客户端下载安装。
|
||||
@@ -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;
|
||||
```
|
||||
|
||||
恢复后才启动旧二进制,暂不删新表/索引;旧版本没有预算保护,保持客户端上传关闭。再次升级需要重新核算预算,不直接复用回滚期间的账本。
|
||||
@@ -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).
|
||||
@@ -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}`。
|
||||
@@ -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.
|
||||
@@ -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 时标记为不可靠
|
||||
- 判据类策略额外有回放对照,那个是即时且无风险的
|
||||
|
||||
---
|
||||
|
||||
## 边界
|
||||
|
||||
- 分析任务**不批准任何东西**。它只提出。
|
||||
- 分析任务**不改代码**。策略里写清楚改什么,由人执行。
|
||||
- 判据是唯一可以「批准即生效」的抓手,因为它可版本化、可回放、可一键回滚。
|
||||
其他抓手都要走正常的发版流程。
|
||||
@@ -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,不经过这条路径。
|
||||
@@ -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 凭据(和证据镜像同一套)。
|
||||
@@ -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
@@ -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": "" }
|
||||
```
|
||||
|
||||
然后建单时把 `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", "platform": "android"}'
|
||||
```
|
||||
|
||||
契约与边界:
|
||||
|
||||
- **只有 `description` 会被物化**:工作区只把 description 写进 `OriginalIntro.md` 并下载其中的图片;
|
||||
放进 `reproSteps` 的 markdown 不会被下载(它只进评估 prompt),Agent 只会看到一个打不开的链接。
|
||||
- 只接受图片:`png / jpeg / gif / webp / bmp / svg / heic / avif`,≤ 12MB;空文件 400、非图片 415、
|
||||
超过 12MB 413;TOS 未配置 503、写入失败 502。执行侧只会把工作区 `images/` 下的图片交给 Agent,
|
||||
日志 / 文本 / 视频请直接写进 description 或 reproSteps 正文。
|
||||
- 上传结果是**公开、永久的 voffline URL**:拿到链接任何人都能读,敏感截图不要传;对象名里不带 Key
|
||||
归属,也还没有 per-key 配额(与证据上传共享 TOS 的 QPS / 并发闸)。
|
||||
- 卫星 bootstrap 工作区时,`satellite/src/workspace.ts::materializeDescriptionImages` 只认
|
||||
`shared/src/protocol.ts` 里的 `TOS_IMAGE_BASE` 前缀:把它下载到 `<workspace>/images/<file>`,并把
|
||||
description 里的绝对 URL 改写成相对 `images/<file>`。评估器的 prompt 随后给出这些文件的本机绝对路径
|
||||
(`shared/src/workspace_images.ts`),执行期 prompt 则指向 `{{workspaceDir}}/images/`(`shared/src/run_prompt.ts`)。
|
||||
**会被保证物化的只有通过这个接口上传的 URL**:手写任意外部图片 URL 不被保证——bug 工作区还留着一条
|
||||
老的「抓正文里 http(s) 图片」兜底(`satellite/src/workspace.ts::extractImageUrls`),feature 工作区没有,别依赖。
|
||||
- 上传发生在建单之前(那时还没有任务可以挂附件),两步顺序不能反;同一个 URL 可以重复用在多条任务里。
|
||||
- **meego-import** 的附件来自工单本身:描述富文本里**直接粘贴的图片**和「多个附件」字段经控制面代理下载进
|
||||
`images/`(`satellite/src/attachments.ts`),这条是保证的。描述正文里的**裸链接**(`参考截图: https://…png`)
|
||||
不是图片语法,不会被下载;`` 形式的外部链接只在工单没有任何 Meego 原生图片 / 附件时才走上面那条
|
||||
老兜底。要保证 Agent 看到截图:粘成 Meego 原生图片,或先经 `/uploads/image` 上传再以 `` 写进描述。
|
||||
链接到云文档 / 外部报告里的内容,无人值守的评估读不到。
|
||||
- 复现步骤写在描述正文里即可,评估器会读;不要求回填 Meego 的独立「复现步骤」字段(填了也会读)。
|
||||
- 上传本身没有任务归属,只能在鉴权后调用。
|
||||
|
||||
## 一句话需求(`/features`):评估完再确认执行
|
||||
|
||||
`POST /api/openapi/v1/features` 用一句 `description` 建一条**需求**(feature)任务,走和面板
|
||||
「新建需求」同一条管线:评估器先起草实现方案(`executionPlan`)→ 状态 `pending_confirmation`(待确认)
|
||||
→ 确认执行后进实现队列。它和 `/tasks`(bug)是两张表、两套状态机,`taskId` 与 `featureId` 别混用。
|
||||
|
||||
```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`
|
||||
@@ -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.
|
||||
@@ -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 注入静默失效。
|
||||
@@ -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
@@ -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 |
@@ -0,0 +1,36 @@
|
||||
# TTKB 集成评审截图
|
||||
|
||||
采集于 2026-09-03。实际界面组件来自本 MR 分支;没有执行新的业务任务或部署生产。
|
||||
静态截图用于核对状态和信息层级,不冒充录屏或真机端到端验收。
|
||||
|
||||
## 真实本地页面 / 已安装包目录
|
||||
|
||||
`default/android` 的本地卫星实际上报 6 个包,全部 ready;仅在草稿里勾选,没有提交建单。背景为本地测试数据库,不是生产看板。
|
||||
|
||||

|
||||
|
||||
切换到没有在线候选节点的 `pns` 集群后,选项清空并显示不可用。
|
||||
|
||||

|
||||
|
||||
## 实际组件 / 合成 fixture
|
||||
|
||||
以下页面直接复用 `KbHitsPanel` / `TtkbUsagePanel`,只替换输入数据和本页 API 返回值;不读写任务数据库、不代表任何真实任务采纳。页面顶部保留 FIXTURE 标记,示例包为 `example/business` / `example/testing`。
|
||||
此前真实任务的日志与临时截图已不在当前环境,不能将这些组件截图当作其重放证据。
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
交互检查还验证了“展开其余 1 篇”能显示第四篇导航文档。TTKB 显示的是成功读取,不等于采纳;Streamline 显示的是注入及模型报告的采纳。
|
||||
|
||||
## 其他验证
|
||||
|
||||
- 全量单元测试:765 pass / 0 fail,77 files,2,825 assertions。
|
||||
- 全仓类型检查、web 生产构建、satellite bundle 构建均通过。
|
||||
- 多节点版本不一致、缺包、旧节点未上报由确定性单元测试覆盖;没有模拟这些情况为真实机器截图。
|
||||
- 安装、权限边界、发布顺序及回退见 [集成说明](../ttkb-integration.md)。
|
||||
@@ -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
@@ -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 视频成为核心证据)。
|
||||
Reference in New Issue
Block a user