docs(plan): INT-2 integration record and shared-index lesson

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/plan/08-v0.2-closeout.md

@@ -66,3 +66,49 @@ HEAD `080563d`,本机串行:
 - `/engine/runs?triggeredBy=` 命中稀少时一页可能少于 `limit`;定时任务运行记录仍没有引擎 run id。
 - 开发库里还有 6 个无前缀的测试站点(观众 ×3、HDSky ×2、馒头,指向已停的随机端口 mock),以及历次测试残留的约 150 个 `*_test_*` / `e2e_*` schema(测试进程中断时 afterAll 没跑到),本轮只清了指定前缀的数据,未动它们。
 - 开发库上还挂着两个早先起的 `deno task dev` 服务进程(4394 / 4397,`--watch`),本轮未动。
+
+## INT-2 集成记录(2026-09-29)
+
+### 发生了什么
+
+v0.2 收尾阶段四个子代理(憨憨修复、AGUI-2、BR-2、SEARCH-2 / META-1)在同一个工作区、同一个 git 暂存区里并行提交:
+
+1. 憨憨修复的提交 `901b01d` 用 plumbing 方式从自己的暂存副本提交,把 AGUI-2(`20b63db`)刚改的 14 个 agent 前端文件(`components/agent/*`、`agentui/tool-result.tsx`、`routes/console/agent*.tsx`、`api/agent.ts`、`scripts/smoke.mjs`)带回了 AGUI-2 之前的版本。
+2. 随后 BR-2(`28974d1`)从共享暂存区提交,暂存区里是 `901b01d` 之前的文件,于是把 `901b01d` 的改动整体撤掉(附带把 AGUI-2 恢复了)。憨憨的改动只剩工作区未暂存改动和 `901b01d` 的 diff。
+3. SEARCH-2 的代码被文档提交 `ac47867`(`docs(plan): on-demand site detail page parsing`)从暂存区顺带带入,内容完整;`18a5cf1` 是补记用的空提交。憨憨改动里的 contracts(api / settings / sources)、`routes/sources.ts`、db 类型、runbook 部分也经这些提交进了 main。
+
+### 如何修复
+
+- AGUI-2 核对:`git diff 20b63db HEAD -- components/agent components/agentui routes/console/agent* api/agent.ts scripts/smoke.mjs` 为空,HEAD 上就是 AGUI-2 版本,无需恢复。
+- 憨憨改动:在临时 worktree 上把 `git diff 20b63db 901b01d`(排除 agent 相关 14 个文件)三方合并到 HEAD,结果与工作区未暂存改动逐文件一致(22 个文件;`account.ts` 与 `schema.test.ts` 是和 BR-2 / META-1 合并后的版本;contracts、routes、types、runbook 已在 main,合并后无差异,`settings.ts` 的冲突 hunk 因此不再需要手动处理)。按路径 `git add` 后提交 `6e9e8ef fix(sites): HHClub parsing, resource list layout and request restraint (re-landed)`。工作区没有其他无关改动。
+- 迁移:编号连续无重号,开发库(55433)的 `kysely_migration` 与仓库一致(0046 → 0049 依次应用,无残留行需要处理);`db:migrate` 无待执行迁移,`gen:types` 无 diff。
+
+| 迁移 | 来源 | 内容 |
+| --- | --- | --- |
+| `0046_site_request_count` | 憨憨修复(`6e9e8ef`,原 `901b01d`) | 站点请求按小时计数 |
+| `0047_identity_pool` | DEC-1(`94fd48b`) | 待识别池 |
+| `0048_site_search_default` | SEARCH-2(代码在 `ac47867`,记录 `18a5cf1`) | `site.search_default` |
+| `0049_enrichment` | META-1(`f4666a4`) | 元数据补全 |
+
+### 站点详情页(追加需求)
+
+`7b5c2f6`:详情抽屉「站点详情页」一节(简介、MediaInfo、截图经图片代理、IMDb / 豆瓣 / TMDB、文件清单、标签、上传者);只按需抓,`kv_cache` 缓存 24 小时;外部 ID 写 `raw._detail` 并作为显式 ID 进身份解析(TMDB ID 直取详情、IMDb 走 `/find`)。细节见 `runbook/sites.md`「详情页扩展内容」。
+
+真实憨憨未核对:要让新解析生效需重建用户栈的 app 镜像(同时执行 0046–0049 迁移),本轮自动模式不允许部署,所以没有对真实憨憨发请求(0 次)。重建后按一次 `GET /sites/{id}/releases/{rid}?refresh=true` 核对,缓存里的 `probe.labels` 可以看出憨憨详情页实际有哪些字段标签,据此补 `umt.detail.page`。HHClub 选择器目前按 MovieClaw 与 fixture 编写。
+
+### CI
+
+本机串行全量 `deno task ci`:
+
+| 次 | HEAD | 结果 | 耗时 |
+| --- | --- | --- | --- |
+| 1 | `6e9e8ef`(憨憨重新落地后) | 全绿(server 82 文件 / 498 用例) | 509 秒 |
+| 2 | `6e9e8ef` | 全绿 | 505 秒 |
+| 3 | `04cffcd`(加详情页) | 全绿(server 503、adapters 381 用例) | 533 秒 |
+
+前端冒烟:独立库 `umt_smoke_int2` + `PORT=4392 WEB_ROOT=<build/client>` 单端口,新初始化管理员,66/66 通过,跳过 12 条详情页(库里无数据)。「Agent 抽屉 → 历史」一步用演示数据,生产构建只有默认上游是 `fake` 时才允许演示数据,所以冒烟库里要先建一个 `fake` 默认上游(没有时这一步超时失败)。跑完已删库。
+
+### 遗留
+
+- 真实憨憨详情页核对(见上)与用户栈重建(0046–0049 迁移)待用户执行。
+- 开发库残留的 `hhclub-wt` 临时 worktree(`ac47867`,在会话 scratchpad 下)未删,不影响仓库。

docs/plan/12-lessons.md

@@ -31,3 +31,4 @@
 18. 容器访问宿主代理:代理只监听 127.0.0.1、ufw 挡容器→宿主、compose 自动分配 192.168.x 网段不在放行范围 → **规则**:socat 中继绑 docker0 地址 + 固定 `UMT_SUBNET` 在放行网段内;防火墙改动由用户执行(自动模式拒绝削弱安全的操作)。
 19. 在用户的栈上做真机验证要"只读 + 事后清理",凭据只放 git 忽略的 `.local/`;子代理误清用户配置(Brave Key)要在集成时恢复 → **规则**:prompt 明确"不要改用户已有配置",验证造的数据/设置逐项还原。
 20. 视觉/桌面类能力必须先做 P0 门槛验证(同会话、HTTPS 前提)再投入实现 → 本轮 P0 通过后 8 人日估算的工作一晚完成。
+21. 多个子代理共用一个工作区和 git 暂存区并行提交:一路用 plumbing(自建 index / commit-tree)从旧快照提交,把另一路刚提交的文件回退;另一路 `git commit` 时暂存区里是别人的半截状态,又把前一路整体撤掉;文档提交顺带带走了别人暂存的代码(v0.2 收尾 `901b01d` / `28974d1` / `ac47867`,见 08-v0.2-closeout「INT-2 集成记录」)→ **规则**:并行子代理一律各自独立 worktree + 分支(`git worktree add ../wt-<任务> -b <任务>`),只在自己的 worktree 里 `git add` / 提交,不用 plumbing 改共享 index;协调者按顺序合并到 main(迁移编号在合并时定),合并后跑全量 ci。共享工作区里只允许一路写。