Repository navigation
refactor(control-plane): slim Todo summaries and eliminate remaining Any - #8987
Conversation
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Gemini · Google (self_reported)
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
已针对 PR #8987 exact head 0b403cdf1509048f96c8889efeb503213694569c 完成完整审查与本地验证(审查结论:APPROVE,无 P0/P1/P2 问题)。
动机 / Motivation
受影响调用方与运维者:所有消费 loopx/control_plane/todos/quota_summary.py 与 loopx/control_plane/todos/todo_summary.py 的控制面、CLI 与状态投影模块(包括 loopx/status.py、loopx/cli_commands/status.py、loopx/cli_commands/quota_cache_freshness.py、loopx/control_plane/quota/should_run_packet.py、loopx/control_plane/quota/should_run_prepare.py、loopx/control_plane/quota/unsettled_host_turn.py、loopx/control_plane/work_items/semantic_replan_writeback.py、loopx/control_plane/work_items/repair_delta.py、loopx/control_plane/todos/goal_todo_projection.py、loopx/control_plane/todos/todo_index.py、loopx/control_plane/todos/user_gate.py、loopx/control_plane/todos/addition.py、loopx/control_plane/todos/machine_section_projection.py、loopx/control_plane/status/attention_projection.py、loopx/control_plane/status/monitor_display_projection.py、loopx/control_plane/status/active_state_projection.py、loopx/control_plane/coordination/authority_source_capture.py 与 loopx/control_plane/testing/quota_fixtures.py),以及 loopx/canary/ 可维护性棘轮维护者。
修改前(origin/main 3c03e91e67):quota_summary.py 共 703 行含 88 处 Any、todo_summary.py 共 895 行含 79 处 Any(合计 167 处 Any),两文件内部分别存在重复的配额请求构造与 wire 解包、嵌套列表/条目压缩样板、structured_todo_item 重复字段归一化分支及 compact_todo_group / compact_evaluated_todo_group 尾段逻辑,且两文件均未录入 loopx/canary/module_metric_baseline.json 零 Any 棘轮。修改后(0b403cdf1509048f96c8889efeb503213694569c):quota_summary.py 精简至 700 行、todo_summary.py 精简至 702 行(净减少 196 行源码,全 PR 4 个文件 +642/-826 净减 184 行),两文件 any_count 与 dict_any_count 均降至 0,semantic_replan_writeback.py 仅补充 1 处经全仓 mypy 暴露的 goal_acceptance_contract 运行时 Mapping 窄化,并在 module_metric_baseline.json 登记 quota_summary.py(lines: 715)与 todo_summary.py(lines: 717)的零 Any 基线棘轮。
可观测结果:module_metrics 返回 quota_summary.py: {'lines': 700, 'any_count': 0, 'dict_any_count': 0} 与 todo_summary.py: {'lines': 702, 'any_count': 0, 'dict_any_count': 0};mypy --strict --follow-imports=silent 两文件 0 错误,全仓 mypy(17 个源码目标)0 错误,ruff 全过;44 组针对性 Todo/配额/状态/棘轮/词表单测 1369 passed in 65.11s(0 failed, 0 skipped)及 19 项控制面 smoke 全过;canary premerge --tier quick 6 项直接检查与 3 项目录金丝雀均通过(ok: true, failures: 0, manual_hold_count: 0);loopx check --scan-path ... errors=0, warnings=0。
非目标边界:本 PR 不修改 Todo 记录、配额规划 wire、状态注意力投影或回执上下文的运行时 JSON schema、返回字典键集、校验语义或错误字符串,完整保留既有 docstring、行内注释及下游导入的私有兼容符号(_compact_agent_lane_status_todo_summary、_compact_todo_item_record、_structured_todo_group_items、_structured_resume_source_items、_task_orchestration_authority、_select_todo_source 等),亦不修改与静态类型收口无关的下游行为或授予合入权限。
改动思路 / Approach
全部零 Any 类型收敛与重复样板合并均收敛在 loopx/control_plane/todos/quota_summary.py 与 loopx/control_plane/todos/todo_summary.py 原生边界内,未新增并行决策层或额外模块;唯一跨文件改动为 loopx/control_plane/work_items/semantic_replan_writeback.py:399-401 处由全仓 mypy 显式暴露的 1 处 goal_acceptance_contract Mapping 运行时窄化。
当前 PR 边界:仅触及 quota_summary.py 与 todo_summary.py 的 Payload / PayloadView 强类型收口与内部重复助函数/归一化表合并、semantic_replan_writeback.py 的最小调用方 Mapping 窄化,以及 loopx/canary/module_metric_baseline.json 中对应的 2 条零 Any 棘轮基线。
- 统一窄化契约(
quota_summary.py:13-14,154-167、todo_summary.py:67-68,149-156):以Payload = dict[str, object]与PayloadView = Mapping[str, object]替代两文件全部167处Any/dict[str, Any],抽出_as_dict、_to_dict_or_none、_require_dict_list、_as_dict_list;对于只读字典入参(如agent_identity、todos、item)采用协变的PayloadView,使下游dict[str, Sequence[str]]等收窄调用无需额外修改。 - 消除模块内重复样板并保兼容:在
quota_summary.py中合并_summarize_todos_for_quota、_compact_payload_item_fields、_compact_nested_item_lists、_compact_lane_items、_compact_role_todos、_quota_projection_request与_project_quota_wires,保持全部错误文案与返回字典结构原样;在todo_summary.py中用顺序表_STRUCTURED_PRE_ACTOR_FIELDS与_STRUCTURED_POST_ACTOR_FIELDS折叠structured_todo_item的 22 组重复字段归一化分支,抽出_finalize_projected_todo_group合并compact_todo_group与compact_evaluated_todo_group的共享收尾逻辑,并用局部emit助函数收拢active_state_todo_attention_item。 - 调用方窄化与棘轮锁定:
semantic_replan_writeback.py:399-401对agent_todos.get("goal_acceptance_contract")补充isinstance(..., Mapping)窄化;loopx/canary/module_metric_baseline.json:64-73按字母序登记两条any_count=0, dict_any_count=0基线。
具体改动 / Changes
本次 diff 仅触及 4 个文件(642 insertions(+), 826 deletions(-),净减 184 行);无书面 RFC/契约规范(spec_basis: no_spec,以既有模块运行时契约与可维护性棘轮基线为准)。
loopx/control_plane/todos/quota_summary.py(+327 / -330,703 -> 700行,88 Any -> 0):清除全部Any,引入Payload/PayloadView与共享助函数,保留全部既有 docstring、行内注释、错误文案与now_utc等测试 monkeypatch 接口。loopx/control_plane/todos/todo_summary.py(+302 / -495,895 -> 702行,79 Any -> 0):清除全部Any,以表驱动替代structured_todo_item重复归一化块,抽离_finalize_projected_todo_group与active_state_todo_attention_item内嵌emit,完整保留被goal_todo_projection.py和todo_index.py导入的私有兼容符号。loopx/control_plane/work_items/semantic_replan_writeback.py(+3 / -1,L399-401):在调用attach_receipt_replan_context时对goal_acceptance_contract做isinstance(..., Mapping)窄化。loopx/canary/module_metric_baseline.json(+10 / -0,L64-73):注册quota_summary.py(lines: 715)与todo_summary.py(lines: 717)的零Any棘轮基线。
关键代码讲解
quota_summary._summarize_todos_for_quota/_quota_projection_request/_project_quota_wires(quota_summary.py:170-184,451-474):统一收敛 user 与 project-asset 配额摘要入口以及三处单事务配额投影请求构建与quota_wires长度校验,同时保留各分支原错误字符串(invalid complete quota summary response、invalid complete quota projection response、invalid consumed Agent terminal view、invalid Agent terminal source rows、invalid User quota source display、invalid explicit Agent quota display views、invalid prepared quota vision wait basis)。quota_summary._compact_payload_item_fields/_compact_nested_item_lists/_compact_lane_items/_compact_role_todos(quota_summary.py:208-267,359-368):消除配额条目压缩、嵌套列表压缩、长度截断计数记录及attention_queue/project_asset双角色遍历中的重复样板,返回值与原实现逐键一致。todo_summary.structured_todo_item(todo_summary.py:116-143,292-338):保持原有字段求值顺序及 truthy 与is not None区分语义(_STRUCTURED_PRE_ACTOR_FIELDS、created_by/claimed_by/bound_agent、_STRUCTURED_POST_ACTOR_FIELDS、material_change_scope*、no_followup),使函数长度与复杂度大幅降低。todo_summary._finalize_projected_todo_group(todo_summary.py:624-639):提取compact_todo_group与compact_evaluated_todo_group完全一致的选中计数判断、attach_active_vision_waits与_task_orchestration_authority挂载路径。
对主干的风险 / Risks
- 兼容性与类型窄化:
_as_dict/_as_dict_list/_to_dict_or_none/_require_dict_list在运行时保持字典引用身份(例如_CanonicalTodoSummary、_QuotaProjectedSummary与_EvaluatedTodo实例)不变,异常输入沿用原有回退或RuntimeError。全仓mypy(17 目标)0 错误、mypy --strict(2 目标)0 错误、AST 符号/docstring/行内注释对比无任何缺失。 - 单测基线与远端 CI 状态:44 组针对性单测全部通过(
1369 passed in 65.11s,0 failed, 0 skipped)且 19 项控制面 smoke 全过;另外 6 个依赖主机环境/本地 CLI 状态的测试文件(test_quota_selection.py中test_public_quota_keeps_gate_from_real_canonical_provider6 例、test_effective_turn_replan.py2 例、test_replan_semantic_action_behavior.py3 例、test_frontier_deadline.py2 例、test_resume_planning_projection.py4 例、test_selected_work_requirements.py6 例)已在未修改的origin/main(3c03e91e67) 复现完全一致的失败结果,非本 PR 引入。远端 GitHub Checks(inspect-pr-diff、Sign-off、dependency-review、loopx-core、postgresql-authority (real server)、changes、prepare、loopx-codex-provider-routing、loopx-repo-health、loopx-obelisk、Summary)尚在排队/运行中,需待 CI 全绿与维护者授权后方可合并。 - 本地完整验证结果(exact head
0b403cdf1509048f96c8889efeb503213694569c):module_metrics:quota_summary.py: {'lines': 700, 'any_count': 0, 'dict_any_count': 0},todo_summary.py: {'lines': 702, 'any_count': 0, 'dict_any_count': 0}— PASSuv run --extra test mypy --strict --follow-imports=silent loopx/control_plane/todos/quota_summary.py loopx/control_plane/todos/todo_summary.py: Success: no issues found in 2 source files — PASSuv run --extra test mypy: Success: no issues found in 17 source files — PASSuv run --extra test ruff check ...: All checks passed! — PASSuv run --extra test pytest -q -n 8(44 个 Todo/配额/状态/棘轮/词表/边界测试文件): 1369 passed in 65.11s — PASSuv run --extra test loopx --format json canary premerge --tier quick --from-git-diff --git-diff-base origin/main: ok=true, gate.status=passed, 6 direct + 3 catalog canaries, failures=0, manual_hold_count=0 — PASSloopx check --scan-path ...: ok=True (errors=0, warnings=0, checks=5) — PASS
我的整体评价 / Verdict
- Long-horizon 影响:
improved— 彻底清零quota_summary.py(88 处)与todo_summary.py(79 处)共 167 处Any、净减 196 行源码并锁定棘轮基线,使后续 Todo/配额演进与跨会话状态恢复受静态类型和棘轮门禁保护,降低隐式字段漂移风险。 - User-experience 影响:
not_applicable— 内部 Python 静态类型收口、重复助函数合并、1 处调用方窄化与 JSON 基线登记,不改变 CLI 参数、输出字段或任何前端界面;visual_review为not_applicable(已检查quota_summary.py、todo_summary.py、semantic_replan_writeback.py、module_metric_baseline.json,unverified_scope:none,远端 GitHub Actions 检查尚在运行中另行跟踪)。 - 可观测语义 / 复用 / 词表:
observable_semantics为equivalent,repository_reuse为reused,authority_semantics与semantic_alignment均为aligned(candidate_decision="reuse_existing",未新增任何协议状态词表或并行拥有者)。
改动聚焦、净减代码规模显著、严格类型检查与本地 1369 条单测及 premerge 金丝雀均验证通过且无 P0/P1/P2 发现项;因触及 loopx/control_plane/ 且为作者自有 PR,合并需等待远端 CI 全绿并获得维护者明确授权。
English verdict: APPROVE exact head 0b403cd (author-owned COMMENTED approval review); eliminates all 167 Any usages across loopx/control_plane/todos/quota_summary.py (88 -> 0, 703 -> 700 lines) and loopx/control_plane/todos/todo_summary.py (79 -> 0, 895 -> 702 lines), consolidates duplicated normalization/compaction/projection helpers with zero behavior drift, adds minimal Mapping narrowing in semantic_replan_writeback.py, and locks zero-Any ratchet baselines in module_metric_baseline.json, verified by strict/repo mypy (17 files), ruff, 1369 passed targeted pytest cases, 19 control-plane smokes, and quick premerge canaries (0 failures).
|
This pull request has merge conflicts with Choose the remote for the base repository, not an out-of-date fork. git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEADFor a same-repository clone whose Keep the DCO |
…inate all 167 Any Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
0b403cd to
b5a9e9b
Compare
huangruiteng
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · GPT-5 · OpenAI (self_reported)
APPROVE。 精确 head b5a9e9b6382db145d9c6cbbd56e884dcd9094510 未发现阻断项;当前 rebase 基线上这两份 Todo 摘要的 161 处 Any 已全部清零,行为路径由直接消费者测试和 premerge 覆盖。
动机 / Motivation
受影响的是维护 Todo、quota、status 与 replan 投影的控制面开发者和所有依赖这些摘要 JSON 的调用方。旧实现把 quota_summary.py 与 todo_summary.py 的输入、嵌套列表和投影结果声明为 Any;当 Todo 字段新增、遗漏或类型漂移时,静态检查无法指出受影响的读取、归一化或压缩路径,维护者只能靠运行时测试和人工搜索确认。一个具体的 before/after 场景是:带 actor 字段、决策作用域、resume 条件和可选 generation 的 Todo 经过 structured_todo_item 与 compact_todo_group;修改前字段访问被 Any 遮蔽,修改后统一由 Payload、PayloadView 和显式 narrow helper 表达,错误输入仍走原有保护分支,合法路径仍返回原来的字典结构。
这个增量把当前 main 上的 quota_summary.py(85 个 Any)与 todo_summary.py(76 个)收敛到 0,并通过零 Any 的 module metric ratchet 锁定。非目标是改变 Todo/quota schema、CLI、排序或 eligibility 语义,也不改变 File/SQLite/PostgreSQL provider、权限或持久化协议;由于这是控制面内部类型和重复样板整理,不包含新的产品能力。
改动思路 / Approach
入口仍是 summarize_user_todos_for_quota、summarize_project_asset_todos_for_quota、structured_todo_item、compact_todo_group 和 compact_evaluated_todo_group。权威输入仍来自既有 canonical Todo/project-asset payload,决策仍由 project_quota_planning 与 project_todo_read_group 持有,本 PR 只在这些本地 projection/local-helper 边界做类型收口和重复逻辑合并。正路径是:调用方传入合法 mapping,local helper 只负责 narrow/compaction,既有 decision owner 计算摘要,最终返回给 status、quota、CLI 和 replan 消费者;失败路径仍是原有 RuntimeError、空结果或 fallback,错误文案未改。现有 owner 足以承担这些规则,因此没有新增并行状态机或抽象层。
flowchart LR
A[Canonical Todo / project-asset payload] --> B[untyped Any branches on base]
A --> C[PayloadView + explicit narrowing on head]
B --> D[Existing quota or Todo projection]
C --> D
D --> E[Unchanged summary JSON and callers]
C -. malformed input .-> F[Existing fallback or RuntimeError]
上图是 source-derived illustrative flow,不是执行证据。当前 PR 边界是保留现有 owner:retain,因为把类型修复或压缩 helper 抽到新模块会增加调用层和维护面,而这里的变化可以被局部行为等价验证覆盖。目标输出和回退语义都不变,验证见下方测试矩阵。
具体改动 / Changes
相对 origin/main 37d795806d2b1ac1e92e19cda2fec46b75ddc65f,精确 head 共 4 个文件、+631/-808。quota_summary.py 为 691 -> 686 行、85 -> 0 个 Any;todo_summary.py 为 875 -> 691 行、76 -> 0 个 Any;semantic_replan_writeback.py 只增加一处 Mapping narrow;module_metric_baseline.json 登记两条零 Any 基线。rebase 冲突按主干事实处理:主干已删除的三个旧 helper 没有被恢复,PR 的 typed 改动被保留。
没有可引用的书面 RFC;此 PR 属于 no_spec 的局部重构,验收依据是既有运行时字典契约、module metric ratchet 和调用方测试,而不是新增协议标准。
关键代码讲解
_summarize_todos_for_quota(quota_summary.py:170)统一 user 与 project-asset 的 summary 入口,先 narrow 为Payload,再调用既有project_quota_planning;它仍保留source_open_count、agent identity、capability resolution 和 failure 语义。_project_quota_wires(quota_summary.py:467)集中处理三处单事务 quota projection 的 wire 数量校验;不完整响应继续抛出原来的错误字符串。structured_todo_item(todo_summary.py:292)以固定字段序表替代重复的 assignment 分支;truthy 与is not None的差异、source section、archive state 和内容 revision 仍由原逻辑决定。_finalize_projected_todo_group(todo_summary.py:613)合并两个 compact group 的共享收尾:empty-selection 判断、vision wait 挂载与 task-orchestration authority 投影都在既有project_todo_read_group结果上完成。semantic_replan_writeback.py:399把可选goal_acceptance_contract明确 narrow 为Mapping;这不是新的 acceptance owner,只让下游 typed receipt 接收合法运行时对象。
对主干的风险 / Risks
最强的回归场景是合法 Todo 含多组可选字段,或 malformed payload 同时触发多个拒绝条件;若字段归一化顺序、truthy 判断或错误优先级变化,status/quota 可能显示不同 lane 或 replan receipt 可能丢失上下文。当前路径把 narrow helper 限制在既有函数边界,并保留原错误串与 owner;直接消费者批量用例 1239 passed 覆盖了合法、空、resume、replan、projection 和 CLI readback。
另有 12 条涉及真实 canonical provider/CLI 状态构造的用例失败;同一三文件在未修改的 origin/main 上得到完全相同的 12 failed, 66 passed,因此归属为 base-equivalent 问题,而不是本 PR 回归。严格 mypy、全仓 mypy、ruff、62 条 maintainability/quality 测试和 quick premerge 均通过;远端 CI 在审查时仍排队,因此只作为 diagnostic,不冒充本地证据。最坏情况可通过 squash commit 整体回滚,不涉及迁移或持久状态。
我的整体评价 / Verdict
Long-horizon 影响为 improved:两份高频摘要模块从 161 个 Any 降到 0,重复归一化和收尾逻辑被合并,并以 ratchet 防止回退;这降低后续字段演进和恢复路径出现隐性漂移的概率。User-experience 影响为 not_applicable:没有渲染或 CLI contract 变更,visual_review 不适用。可观测语义为 equivalent,repository reuse 为 reused,authority/domain-neutrality/guidance 均保持既有边界;本 head 没有 blocking finding。
English verdict: APPROVE exact head b5a9e9b6382db145d9c6cbbd56e884dcd9094510; the rebased change removes all remaining 161 Any usages from the two Todo summary modules, preserves the existing projection owners and observable payload shapes, and passes strict/repo mypy, ruff, 1239 direct-consumer tests, 62 quality-gate tests, and quick premerge; 12 further tests fail identically on unmodified main.
Summary
Anyusages inloopx/control_plane/todos/quota_summary.py(85 -> 0) andloopx/control_plane/todos/todo_summary.py(76 -> 0) on the current PR base. The earlier PR revision started from a base with167; concurrent main changes had already removed six before this rebase.Payload = dict[str, object],PayloadView = Mapping[str, object],Sequence[PayloadView], and explicit runtime narrowing helpers (_as_dict,_as_dict_list,_to_dict_or_none,_require_dict_list).goal_acceptance_contractinloopx/control_plane/work_items/semantic_replan_writeback.py, then lock both Todo summary modules at zeroAnyinloopx/canary/module_metric_baseline.json.Verification
Rebased onto
origin/mainat37d795806d2b1ac1e92e19cda2fec46b75ddc65f; reviewed headb5a9e9b6382db145d9c6cbbd56e884dcd9094510.module_metrics:quota_summary.pyis now691 -> 686lines andtodo_summary.pyis875 -> 691; both reportany_count: 0anddict_any_count: 0.uv run --extra test mypy --strict --follow-imports=silent ...: no issues in the two changed Todo summary modules.uv run --extra test mypy: no issues in all configured targets.uv run --extra test ruff check ...: passed.1239 passed; 12 tests intest_quota_selection.py,test_resume_planning_projection.py, andtest_replan_history_provider.pyfail identically on unmodifiedorigin/main(12 failed, 66 passed), so they are recorded as base-equivalent rather than attributed to this PR.62 passed.loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main: passed with 6 direct checks and 3 catalog canaries,failures: 0,manual_hold_count: 0.Boundary & Rollback
The PR keeps the existing control-plane owners and observable runtime contract. It does not add a provider, protocol field, persisted state, CLI option, or scheduling decision. It is fully reversible by reverting the squash commit.