docs/backend-migration/plans/2026-05-08-cleanup-teammate-cheatsheet.md
2026-05-08-cleanup-team-playbook.md
为准,查细节去那里2026-05-08-cleanup-and-test-rewrite-design.mdM 系列(2026-05-07)整条链最后在 feat/ci-web-cli-release-integration 留下了
10+ 个修复 commit,根因几乎都是"teammate 偷懒"—— 改完代码不等 CI,验证用
经验判断,删代码不 grep 证据,测试被 .skip 绕过。这次本需求的业务逻辑极少、
几乎每一步都能用 tsc / vitest / grep 机械判定,如果还出现同类问题,是
组织纪律问题不是技术问题。
UC-F 5 条是本 cheatsheet 最关键的增量,必须比 UC-A..E 更熟。
每条 requirements 里的"自动化门禁"命令,handoff 对应位置必须附:
$ <command>)$ echo $?)禁止:"tsc 通过" / "vitest 绿" / "按经验无影响" 这类转述。任何非 0 退出
必须在 handoff 的"诊断"节说明根因 + 修复,不得 || true 吞错。
本仓库 CI 触发实测:
pr-checks.yml → PR 到 main/dev 或 workflow_dispatchbuild-and-release.yml → push: branches: [dev] + tags(push 到 dev
触发完整 CI)_build-reusable.yml / pack-web-cli.yml → workflow_call 被动调用本链策略:N1-N5 在 feature 分支链上完成后,由 team-lead 把整链一次性
合入 dev 触发一次完整 CI。不是每个里程碑跑一次(避免扰动 dev +
保持粒度清晰)。
lint + tsc + vitest + prek +
基线同步后复跑(UC-F-5)是你本里程碑的主门禁dev 或 feat/backend-migrationgh workflow run 等方式主动触发 CI(由 team-lead 统一)build-and-release.ymlgh run watch、必须 conclusion: success;失败不得 hot-fix dev,
必须 revert + 回链尾某里程碑补 commit你不负责合 dev,但:
gh run rerun 一次,
说明原因;≥ 2 次 flaky 必须 escalate 调查根因删除任何源文件前,必须跑并在 handoff 贴输出:
grep -rn "<basename>" \
packages/ scripts/ tests/ \
--include='*.ts' --include='*.tsx' --include='*.js' \
--include='*.json' --include='*.yml' --include='*.yaml'
每行必须标注("self-reference" / "consumer 也在删除集合中");发现外部引用
不得自行判断"可以忽略",必须 escalate。删后再跑 bunx tsc --noEmit,
错误数必须保持为 0。
bunx vitest run --reporter=verbose,handoff 贴每个新增测试的 ✓ 行 +
总 N passed.skip / .todo / xit / xtest;清单里每个测试必须真正能跑的断言mockHttpBridge 或 vi.mock# Step 1 初次本地门禁
bun run lint
bunx tsc --noEmit
bunx vitest run
prek run --from-ref origin/feat/backend-migration --to-ref HEAD
# Step 2 里程碑专属业务回归(见各 requirements)
# Step 3 同步基线(merge 不是 rebase)
git fetch origin feat/backend-migration
git merge origin/feat/backend-migration --no-ff \
-m "chore(nx): sync with feat/backend-migration"
# Step 4 合并后完整复跑 Step 1 四条,不得跳过
bun run lint && bunx tsc --noEmit && bunx vitest run && \
prek run --from-ref origin/feat/backend-migration --to-ref HEAD
# Step 5 push(改 workflow 的按 UC-F-2 等 CI)
git push -u origin <branch>
Step 4 新失败:基线引入的破坏 → escalate;本里程碑隐性冲突 → 修 + handoff Deviations。
| 角色 | 产出 | 读什么 |
|---|---|---|
| executor-N{x} | 代码 + 测试 + handoff | 本 cheatsheet + 总设计对应节 + 自己 requirements + (N3/N4 还要读 detailed plan) + 上游 handoff |
| plan-writer-N{3 或 4} | 2026-05-08-n{x}-{name}.md detailed plan 文件 | 本 cheatsheet + 总设计 + 自己 requirements + M1 plan(格式参考 2026-05-07-m1-monorepo-skeleton.md) + 已完成的 handoff |
N1 / N2 / N5 不派 plan-writer(纯机械清理/配置,requirements 已经够 executor 执行)。
origin/feat/n{x-1}-xxx(上游里程碑分支)创建自己的 feature 分支feat/cleanup-and-test-rewrite(等于整条链的起点分支)feat/n2-legacy-test-cleanupfeat/n3-test-rewrite-adapter-commonfeat/n4-test-rewrite-domainsfeat/n5-restore-cifeat/backend-migrationN4 是本链唯一允许内部并行的里程碑。team-lead 可以在同一个分支
feat/n4-test-rewrite-domains 上派 3 个 teammate:
tests/unit/assistants/ + skills/ + extension/(19 文件)tests/unit/providers/ + system/ + cron/(18 文件)tests/unit/previews/ + assets/ + bootstrap/(17 文件)严格约束:
feat/n4-test-rewrite-domains 分支,不开子分支git pull --rebase 再写,避免冲突tests/unit/_helpers/mockHttpBridge.ts 任何 N4 teammate 都不得改;
需要扩展必须 escalateN4-outcome.md(A 部分 / B 部分 / C 部分三节)涉及 UC-G 跨仓 backend 改动时(三路并行下的协同):
feat/n4-test-rewrite-domains,协同规则与前端一致:先到先 push、后到
git pull --rebasemockHttpBridge 签名(N4 依赖锚点)发现上层与下层冲突 → 以上层为准,escalate 给 team-lead,不自主折中。
bunx tsc --noEmit # 类型检查
bun run lint # oxlint
bunx vitest run # 单元测试
prek run --from-ref origin/feat/backend-migration --to-ref HEAD
git fetch origin feat/backend-migration
git merge origin/feat/backend-migration --no-ff \
-m "chore(n{x}): sync with feat/backend-migration"
# 冲突:简单自己解,复杂 escalate
# 合入后重跑上面的质量门禁
git push -u origin feat/n{x}-{name}
docs/backend-migration/handoffs/N{x}-outcome.md,≤ 700 字)N 系列由于 UC-F-1 要贴原始命令输出,比 M 系列的 500 字稍放宽到 700 字。 命令输出按头 10 + 尾 10 + 总行数截断,不要贴全。
# N{x} <名称> - 交付摘要
## 已交付
- 新建 / 删除 / 修改文件清单
- 新增的对外 API / 配置项
## 与计划的偏离
- <改动点> —— 原因 —— 对后续影响
## 给下一个里程碑的提醒
- <警示>
## 验证证据(UC-F-1,贴原始输出)
- 分支名 + 最新 SHA
- 基线同步状态(基线 SHA + merge commit SHA)
- tsc / lint / vitest / prek 的头 10 尾 10 + 总行数 + 退出码
- 本里程碑对应的 checkpoint 命令输出
## Backend 修改(UC-G,必填,没改写"无")
- 仓库 / 分支 / 最新 SHA
- 修改文件(file + 变更行数)
- 一句话理由
- 验证(`cargo test -p <crate>` 输出)
- 待办(人类 PR+merge)
## Backend 问题发现(UC-G 必 escalate 的情况,无则不写)
- 问题描述 + 位置 + 为什么本里程碑不能自行改
- 建议的后续 issue / 修复方向
## 遗留问题 / 跟进项
N{x} 完成。
- 分支:feat/n{x}-{name}
- SHA:<sha>
- 基线同步:origin/feat/backend-migration @ <基线 sha> 已合入
- Handoff:docs/backend-migration/handoffs/N{x}-outcome.md
- UC-F 证据:贴命令输出 ✓ / grep 证据 ✓ / CI 真跑 ✓(N5) / 无 skip ✓ / 基线后复跑 ✓
- 偏离计划:<无 / 列出>
请启动 N{x+1}。
2026-05-08-n{3|4}-{name}.md 文件,不写代码test(nx): ... 或 refactor(nx): ...)bunx vitest / prek / gh 等可用性)"看起来差不多对了"不是 PASS 理由。本需求每一步都能用 tsc / vitest / grep
判定,理论上不应该出现"无法机械化"。
migrateAssistants.ts / runBackendMigrations.ts /
systemSettingsBridge.ts / previewUtils.ts(被 AcpAgentManager 用) /
ccSwitchModelSource.ts(被 acp/agent 用);见总设计附录 A 的 grep 证据tests/unit/<module>/ 镜像 tests/e2e/features/;保留
tests/e2e/** / tests/fixtures/** / vitest.setup.ts /
vitest.dom.setup.ts / packages/web-host/**/*.unit.test.ts;不改
vitest.config.tsbunx vitest run 注释;不保留
"temporarily disabled" 注释块本机必须按 ~/Documents/github/aionui-backend/docs/development-workflow.md
"一次性环境准备"节配好双仓联调环境。少一步后面 UC-G 走不通:
# 1. 安装 cargo-watch(推荐)
cargo install cargo-watch
# 2. 先编译一次 backend,确认 target/debug/aionui-backend 产物存在
cd ~/Documents/github/aionui-backend
cargo build
# 3. 建 symlink 到 PATH 首位(关键!前端 binaryResolver.ts 靠这个找到 backend)
ln -sf ~/Documents/github/aionui-backend/target/debug/aionui-backend \
~/.cargo/bin/aionui-backend
# 4. 验证 symlink 正确(输出开头应是 'l' 表示 symlink,不是真实二进制)
ls -la ~/.cargo/bin/aionui-backend
which aionui-backend # 应输出 /Users/<user>/.cargo/bin/aionui-backend
aionui-backend --help # 应能跑
# 5. 前端仓依赖
cd ~/Documents/github/AionUi
bun install
避坑:若 ~/.cargo/bin/aionui-backend 开头不是 l(说明之前 cargo install --path . 装成了真二进制),必须删掉重建 symlink,否则后续改 backend
源码不会被前端看到。
teammate 首次执行里程碑时在 handoff 的"环境预检"节贴 ls -la ~/.cargo/bin/aionui-backend 和 which aionui-backend 输出各一行证明。
改 backend 源码 → cargo watch 自动编译 → 重启 AionUi(关闭 bun start 再
重启)即可吃到新行为。前端 renderer HMR 不受影响;backend 是启动时 spawn
的子进程,不会热重载,所以每次改 backend 都要重启前端。
前端测试 / 清理工作发现后端行为问题,允许 teammate 在本地 aionui-backend 改代码:
# 1. 在 backend 仓拉同名分支
cd ~/Documents/github/aionui-backend
git fetch origin
git checkout -b feat/n{x}-{name} origin/main
# 分支名和前端本里程碑分支尾段完全一致
# 2. 改代码,cargo watch 自动编译
# 3. 本地验证
cargo check --workspace
cargo clippy --workspace -- -D warnings
cargo test -p <受影响 crate> # 别跑全仓
cargo fmt --all -- --check
# 4. 重启 AionUi 端到端验证(关掉 bun start 再重启)
# 5. commit + push backend 分支(不开 PR!)
git add <files>
git commit -m "<type>(<crate>): <subject>"
git push -u origin feat/n{x}-{name}
aionui-team,N4 不得改 aionui-mcp 等)rebase / force-pushaionui-backend/main 或任何 backend 共享分支release-please / rust-toolchain.toml / Cargo
workspace 配置 / DB migration / API 破坏性改动(这些必须 escalate)→ teammate 把发现写进 handoff "Backend 问题发现(需 escalate)"节, 不自己改,SendMessage 给 team-lead
不论有没有改,都要写(没改就填"无"):
## Backend 修改
- 仓库:iOfficeAI/aionui-backend
- 分支:feat/n{x}-{name}
- 最新 SHA:<push 后的 SHA>
- 修改文件:
- `crates/aionui-system/src/bedrock_probe.rs`(+12 / -3)
- 一句话理由:backend 返回 provider.id 为 Option<String>,adapter 期望
非空 String;修 backend 为必填(符合 api-types 约定)
- 验证:`cargo test -p aionui-system` N passed;前端重启后对应测试变绿
- **待办**(人类):backend 分支未开 PR,链合入 dev 前须先 PR+merge 到
aionui-backend/main
整链合入 dev 前,team-lead 必须先完成 backend 侧的合入:
aionui-backend/main整链合入 dev 后 build-and-release.yml fail,诊断指向 backend:
| 状况 | 做法 |
|---|---|
| checkpoint 失败 | 不 push,escalate,handoff 里列诊断 + 尝试过的修复 |
| 基线合并冲突复杂 | 不硬改,escalate |
| requirements 的决策和 UC 冲突 | 以 UC 为准,escalate 让人类改 requirements |
| plan 里某条验证需要人眼判断 | 改进验证命令,不能打"manual verify" |
| 发现上游里程碑遗留 bug | 不自主修,escalate;该补丁应在新的 commit 而非 amend 里解决 |
| 写测试发现 backend 行为有 bug | UC-G:判断 scope,在 scope 内就在本地 backend 仓同名分支改、cargo test 验证、handoff 记录;scope 外 escalate |
| 发现 backend 缺 route / 数据库 schema 不对 | 按 UC-G 必 escalate 的 5 种情况判定,DB / 破坏性变更一律 escalate |
| 发现 UC-B 保留文件实际可删 / 或"可删"文件实际不能删 | 立即 escalate,不得自主扩大或缩小删除清单 |
需要的工具没装(prek / bunx @electron/asar / gh) | 装上;若不能装 escalate |
| CI flaky(网络 / registry / 偶发) | 允许 gh run rerun <id> 一次并在 handoff 说明;≥ 2 次 escalate 调查根因 |
| N4 三个并行 teammate 撞了同一文件 | 不能撞(目录零重叠);如发生一定是有人越界,escalate |
N3 的 mockHttpBridge.ts 不够用 | escalate,由 team-lead 决定是否扩展 helper 签名 + 更新 N3 handoff |
| 主题 | 去 playbook 的哪节 |
|---|---|
| 完整角色模型、派发流程 | "用户操作" / "Team-lead 调度规则" |
| 完整 executor / plan-writer prompt 模板 | "Executor Prompt 模板" / "Plan-Writer Prompt 模板" |
| 简单 vs 复杂里程碑判定 | "里程碑复杂度与派发策略" |
| Checkpoint 清单(每个里程碑) | "Checkpoint 规范" |
| N4 内部并行的 team-lead 视角 | "N4 并行派发" |
| 分支协作模型全貌 | "分支协作模型" |
| 基线同步的冲突处理 | "基线同步规范" |
| UC-F 违反了怎么办 | "UC-F 违反的处理" |
手头事有明确做法就直接做;规则不清才去查 playbook。