diff --git a/verification/resident-website-loop-summary.md b/verification/resident-website-loop-summary.md new file mode 100644 index 0000000..69a0665 --- /dev/null +++ b/verification/resident-website-loop-summary.md @@ -0,0 +1,125 @@ +# 常驻监听网站闭环验证摘要 + +## 起点与交付物(代码就绪,local only) + +- 工作区:`~/workspace/codex-app-server-resident-website-loop` +- 分支:`feat-resident-website-loop`,起点为上一轮网站版 + `feat-resident-task` 的 `0722ca3`(基底 `origin/main 622c51e`)。 +- 实现提交:`561b389`(仅新增端到端测试文件 + `cloud/tests/test_resident_website_loop.py`,364 行)。 + 本摘要为其后提交,工作区提交后干净。 +- 范围:只做网站用例。不做 server_status、agent_status、 + relay_cost 等其它探针;不把 resident-watches 改名/泛化成 + 通用任务;不改 API、表名与任何生产默认值。 +- 泛化 worktree(`~/workspace/codex-app-server-resident-generic`) + 本轮一律未碰;resident-task worktree、主 checkout + (`feat-repo-picker`)及其它 worktree 一律未动。 +- **未做**:未 push、未合并到 main、未跑 `deploy.py`、未部署、 + 未建生产任务、未动生产/主机 env/系统 key/sub2api/ + 生产网关/仓库可见性/GitHub App 权限、未杀生产容器、 + 未连真实外部网站。 + +## 闭环逐环证据(全部真实链路,不是注入假抓取) + +测试文件:`cloud/tests/test_resident_website_loop.py`,2 项。 +内容服务是线程内真实 `http.server`(可变内容、可停服重启); +控制面是真实 `ThreadingHTTPServer` + 真实 SQLite 临时库; +驱动走真实 `default_fetch`(urllib、超时、1MB 截断)。 +生产 URL 校验一字不改:测试主机名 `website-loop.test` 不是 +IP 字面、不是 localhost,所以校验通过;测试进程内只把该 +主机名的 DNS 指到本地服务(相当于 /etc/hosts 的一条测试 +条目),并给它加 `no_proxy`(见“测试中发现的两处假断点”)。 + +1. 创建(API):`POST /projects/{id}/resident-watches` + (name=site1、target_url=`http://website-loop.test:<本地端口>/data`、 + prompt=“变化时汇报”、interval_seconds=60)返回 201, + 状态 running、interval 60、fetch_timeout 10(生产默认)、 + last_content_hash 为空、next_poll_at 在位;审计含 + `resident_watch_created`。状态查询 `GET` 单条可看到 + running、游标、下次轮询。 +2. 基线轮询:worker 驱动 `process_due_resident_watches` + (fetcher=None,即真实 default_fetch)抓到 “version one”, + 记 `baseline` 轮询、游标为其 sha256,任务数为 0; + 状态查询的 polls 第 1 条就是 baseline。 +3. 变化建任务:内容改成 “version two”,到期轮询记 + `changed`、建出 1 个 queued 任务,任务 prompt 含用户提示 + “变化时汇报”与摘录 “version two”,任务行与审计行 + `resident_watch_change_task_created` 均可查;游标推进到 + version two,last_change_text 含 version two。 +4. 暂停:API pause 后状态 paused、next_poll_at 为空;暂停 + 期间内容再改成 “version three”,驱动返回空、轮询数仍为 + 2、游标仍为 version two——暂停期间的变化没有被轮询上报。 +5. 恢复:API resume 后状态 running;下一次驱动用旧游标比 + 对,记 `changed` 并建第 2 个任务(prompt 含 version three), + 不是从头建基线;游标推进到 version three。 +6. 失败环:停掉内容服务后驱动记 `failed` 轮询、 + consecutive_failures=1、next_poll_at 大于 now+60+30 + (间隔 + 首次退避 30 秒)、状态仍 running、游标仍为 + version three——驱动不崩、监听不擅自结束。恢复服务后 + (内容仍为 version three)驱动记 `unchanged`、失败清零、 + 任务数仍为 2。 +7. 结束:API end 后状态 ended、next_poll_at 为空、游标仍为 + version three;驱动返回空;pause / resume / end / PATCH + 更新一律 409;状态查询显示 ended 与最后游标/变化, + polls 总数为 5(baseline、changed、changed、failed、 + unchanged)。 +8. 驱动接线:单独一测试把 `run_all` 等无关边界打桩,只留 + resident 驱动走真实抓取,调真实 `Worker.run_loop` + (interval=0.05、max_seconds=0.4);记录到 run_loop 轮次 + 边界至少调了 1 次 `process_due_resident_watches`,且状态 + 查询里出现 1 条 baseline 轮询、游标为 version one。 + 这证明接线在 run_loop 里,不只是测试直接调驱动函数。 + +## 断点结论:生产代码无断点,无生产改动 + +本轮逐环均通,生产代码(`cloud/resident.py`、`cloud/server.py`、 +`cloud/worker.py`)一字未改,`git diff` 为空、新增文件只有 +端到端测试。第一次跑出的 2 个失败都是测试脚手架问题, +不是生产断点,修法与证据如下,不许读成“修了生产代码”: + +- 假断点 1——首次真实抓取 failed:测试环境自带 egress 代理, + urllib 默认把测试主机名也送代理并被代理断开。实测对照: + 不加 no_proxy 时 `default_fetch` 报 RemoteDisconnected, + 加 no_proxy 后返回 “version one”。修法只在测试 setUp 里 + 给 `website-loop.test` 加 no_proxy(测试进程内生效,撕掉 + 时还原),生产抓取与代理行为一字不改。 +- 假断点 2——run_loop 接线测试 TypeError:实例属性上的 + recording 函数不会自动绑定 self。修法改为闭包捕获 worker, + 不改 worker 代码。 + +## 真实测试数字 + +- 定向(全量后重跑,含本轮 2 项):`python3 -m unittest + cloud.tests.test_resident cloud.tests.test_resident_server + cloud.tests.test_resident_website_loop` —— 15 项全部通过。 + 其中上一轮 13 项在新 worktree 动工前已先复核全过。 +- 全量(CI 同款三条 discover,定向之后、全量之前无生产改动, + 全量后又重跑定向 15 项全过,时间关系如实写明): + - `discover -s tests`:105 项,0 失败,0 跳过。 + - `discover -s cloud/tests`:1546 项,0 失败,9 跳过 + (上一轮 1544 + 本轮新增 2,对账无差)。 + - `discover -s deploy/tests`:44 项,0 失败。 + - 合计 1695 项、0 失败、9 跳过。失败未靠删断言、加 skip、 + 改默认值蒙混;生产间隔下限 60 秒、抓取超时默认 10 秒、 + URL 校验口径一律未动,到期只用驱动 now 注入模拟时间流逝。 + +## 已知偏差与未做事项(未写成已完成) + +- 控制台 UI 不在本轮闭环内:只能走 API,无常驻面板。 +- 真实外网抓取未验:只验了本地 HTTP 服务 + 测试 DNS 映射, + 不要把本轮说成真实外网验证;生产环境下的代理/DNS/证书 + 行为仍属后续验证项。 +- 生产 PG 表迁移未验(只验 SQLite 临时库)、双进程抢单未验 + (只验条件 UPDATE 单胜者的上一轮单测与本轮单驱动链路)。 +- 其它探针本轮明确不做:server_status、agent_status、 + relay_cost、通用任务改名一律不在本轮范围内。 +- 变化判定仍是上一轮 v1 全文 hash,无选择器/区域提取; + SSRF 仍是 v1 只挡字面私有 IP,未做 DNS 解析后校验。 +- 未做:未 push、未合并、未部署;架构与代码质量的 10 分 + 审核是父级后续独立步骤,本轮不自评、不给自己打 10 分。 + +## Blocker + +- 本轮无 blocker(纯本地代码与本地测试,未触及只有用户能给 + 的账号/密钥/商户/商店账号/宿主/维护窗口,也未发生 + 花真钱、删生产数据、改生产可见性的动作)。