Repository navigation
refactor(control-plane): slim management_projection and eliminate Any - #8971
Conversation
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
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 #8971 exact head 3de32c50d165d58224ba776bc42bab48160ae9cc 完成完整审查与本地验证(审查结论:APPROVE,无 P0/P1/P2 问题)。
动机 / Motivation
受影响调用方与运维者:所有消费 loopx/control_plane/agents/management_projection.py 的控制面目录、执行事实、督导、配额与看板状态投影模块(包括 loopx/control_plane/status/collection.py、loopx/control_plane/status/agent_lane_projection.py、loopx/control_plane/agents/directory.py、loopx/control_plane/agents/execution_facts.py、loopx/control_plane/agents/supervisor.py、loopx/control_plane/quota/should_run_prepare.py、loopx/control_plane/quota/task_orchestration.py、loopx/status.py、loopx/dash_server.py 与 loopx/cli_commands/dash.py),以及 loopx/canary/ 可维护性棘轮维护者。
修改前(origin/main 68440058):loopx/control_plane/agents/management_projection.py 共 937 行、存在 67 处 Any(含 dict[str, Any] 与宽松集合推导)及重复的去重列表、非空字典过滤与单 Agent 行构造样板,且未写入 loopx/canary/module_metric_baseline.json 零 Any 基线棘轮。修改后(3de32c50d1):该文件净减 126 行降至 811 行(diff 为 +238/-364),any_count 与 dict_any_count 均降至 0,并以 any_count: 0, dict_any_count: 0, lines: 826 写入基线文件锁死上限。
可观测结果:module_metrics 返回 {'lines': 811, 'any_count': 0, 'dict_any_count': 0};mypy --strict --follow-imports=silent loopx/control_plane/agents/management_projection.py 与全仓 mypy(17 个源码文件)均报 0 错误;ruff 全过;9 组棘轮/控制面/词表单测套件共 287 passed in 22.14s(0 skipped),5 个控制面 smoke 脚本与 loopx canary premerge --tier quick(selected_checks: 3, failures: 0, ok: true)全部通过,loopx check --scan-path ... errors=0, warnings=0。
非目标边界:本 PR 不更改 agent_management_projection_v0、todo_row_v0 或 agent_material_frontier_v1 对外 JSON 结构与空值裁剪语义,不引入任务写操作或自动抢占逻辑,亦不授予作者自有运行时的合入权限。
改动思路 / Approach
全部强类型收口与重复样板合并均保留在 loopx/control_plane/agents/management_projection.py 单一边界内,不新增并行适配层,不修改下游调用方文件。
当前 PR 边界:只触及 loopx/control_plane/agents/management_projection.py 的类型收口/去重瘦身,以及 loopx/canary/module_metric_baseline.json 中对应的棘轮条目注册。
- 零
Any与窄化边界(loopx/control_plane/agents/management_projection.py:23-78,593-618):定义内部别名Payload = dict[str, object]与PayloadView = Mapping[str, object],统一抽取_as_dict、_as_list、_append_unique、_nonempty_dict与_string_list,取代散落在各解析辅助函数与_collect_session_binding_candidates中的Any与隐式可变映射假设。 - 单 Agent 投影构造收敛(
loopx/control_plane/agents/management_projection.py:620-682,684-811):将原build_agent_management_projection循环体内联的 Todo 排序筛选、证据/交接引用收集、material_frontier/handoff_note/workspace_ref/blocked_on/stale_claim_hint组装下沉至_build_agent_row,并通过_nonempty_dict精确复用(None, "", [], {})的原有非空裁剪契约。 - 可维护性棘轮注册(
loopx/canary/module_metric_baseline.json:56-60):按字母序在agent_scope.py与goal_frontier/__init__.py之间插入"loopx/control_plane/agents/management_projection.py": {"any_count": 0, "dict_any_count": 0, "lines": 826}。
具体改动 / Changes
本次 diff 仅触及 2 个文件(243 insertions(+), 364 deletions(-),整体净减 121 行):
loopx/control_plane/agents/management_projection.py(+238 / -364,净减126行,937 -> 811行,67 Any -> 0):清除全部Any,增加Payload、PayloadView、_as_dict、_as_list、_append_unique、_nonempty_dict与_build_agent_row,保留全部既有文档字符串与解释性注释。loopx/canary/module_metric_baseline.json(+5 / -0,L56-60):登记any_count=0、dict_any_count=0、lines=826棘轮基线。
对主干的风险 / Risks
- 调用方兼容与空值/游标语义等价:经
origin/main对照核实,build_agent_management_projection末段_nonempty_dict精确保留了原有的{k: v ... if value not in (None, "", [], {})}语义,after_agent_id分页计数、registered_agent_count与diagnostic_agent_count分离统计均保持原样;全仓 17 个mypy目标(0 错误)与 287 个控制面/棘轮/词表单测全部通过。 - 公共与私密边界:
loopx check --scan-path ...与canary premerge --tier quick均报 0 错误,零新增持久化字段或 CLI 开关。 - 本地完整验证结果(exact head
3de32c50d165d58224ba776bc42bab48160ae9cc):module_metrics:{'lines': 811, 'any_count': 0, 'dict_any_count': 0}uv run --extra test mypy --strict --follow-imports=silent loopx/control_plane/agents/management_projection.py: Success: no issues found in 1 source fileuv run --extra test mypy: Success: no issues found in 17 source filesuv run --extra test ruff check loopx/control_plane/agents/management_projection.py tests/canary/test_maintainability_ratchet.py: All checks passed!uv run --extra test pytest -q -n 4(9 个棘轮/控制面/词表漂移测试文件): 287 passed in 22.14s(0 skipped)- 5 个控制面 smoke(
agent-management-live-status-smoke.py,agent-material-handoff-projection-smoke.py,peer-supervisor-smoke.py,task-orchestration-smoke.py,status-collection-readmodel-smoke.py): 全部通过 uv run --extra test loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main: passed (ok=true,selected=3,failures=0)loopx check --scan-path loopx/control_plane/agents/management_projection.py --scan-path loopx/canary/module_metric_baseline.json: ok=True (errors=0, warnings=0)
我的整体评价 / Verdict
- Long-horizon 影响:
improved— 清除共享 Agent 管理投影模块的 67 处Any并净减 126 行冗余样板、叠加 826 行棘轮门禁,避免后续状态投影演进重新引入宽松类型与结构复制。 - User-experience 影响:
not_applicable— 纯内部控制面强类型重构、去重瘦身与静态棘轮基线注册,visual_review为not_applicable。 - 可观测语义 / 复用 / 词表:
observable_semantics为equivalent,repository_reuse为reused,authority_semantics与semantic_alignment均为aligned(candidate_decision="reuse_existing")。
改动收敛在 2 个文件、强类型与单测/smoke/premerge 验证充分且无 P0/P1/P2 发现项;因属于作者自有控制面运行代码,合入仍需维护者授权及远端 CI 全绿通过。
English verdict: APPROVE exact head 3de32c5 (author-owned COMMENTED approval review); eliminates all 67 Any usages and 126 net lines in loopx/control_plane/agents/management_projection.py via Payload/PayloadView narrowing, _append_unique, _nonempty_dict, and _build_agent_row with a zero-Any baseline ratchet, verified by strict/repo mypy (17 files), ruff, 287 passing pytest tests, 5 control-plane smokes, and quick premerge canary.
Summary
67Anyannotations (any_count: 67 -> 0,dict_any_count: 0 -> 0) inloopx/control_plane/agents/management_projection.pyusingPayload = dict[str, object],PayloadView = Mapping[str, object],objectinputs, and explicit narrowing in_as_dict/_as_list, achieving zeromypy --strict --follow-imports=silentissues and17/17repo-widemypypass.loopx/control_plane/agents/management_projection.pyfrom937to811lines (-126net lines;243 insertions(+), 364 deletions(-)across the patch) without behavior or schema changes by consolidating repeated deduplication, compact optional-dict construction, and per-agent projection assembly into_append_unique,_nonempty_dict, and_build_agent_row.loopx/control_plane/agents/management_projection.py(any_count: 0,dict_any_count: 0,lines: 826) inloopx/canary/module_metric_baseline.json.Verification
From a clean worktree on
origin/main(68440058):uv run --extra test python -c 'from pathlib import Path; from loopx.canary.maintainability_ratchet import module_metrics; print(module_metrics(Path("loopx/control_plane/agents/management_projection.py")))'->{'lines': 811, 'any_count': 0, 'dict_any_count': 0}uv run --extra test mypy --strict --follow-imports=silent loopx/control_plane/agents/management_projection.py->Success: no issues found in 1 source fileuv run --extra test mypy->Success: no issues found in 17 source filesuv run --extra test ruff check loopx/control_plane/agents/management_projection.py tests/canary/test_maintainability_ratchet.py->All checks passed!uv run --extra test pytest -q -n 4 tests/canary/test_maintainability_ratchet.py tests/control_plane/test_status_agent_lane_projection.py tests/control_plane/test_agent_management_material_capability_gate.py tests/control_plane/test_peer_agent_directory.py tests/control_plane/test_agent_lifecycle_state.py tests/control_plane/test_status_collection_material_capability_wiring.py tests/control_plane/test_agent_session_binding_candidates.py tests/control_plane/test_task_orchestration_admission.py tests/architecture/test_semantic_vocabulary_drift.py->287 passed in 22.14s(0 skipped)examples/control_plane/agent-management-live-status-smoke.py,examples/control_plane/agent-material-handoff-projection-smoke.py,examples/control_plane/peer-supervisor-smoke.py,examples/control_plane/task-orchestration-smoke.py,examples/control_plane/status-collection-readmodel-smoke.pyuv run --extra test loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main->ok: true,selected_checks: 3,failures: 0errors=0, warnings=0on both changed paths)