Repository navigation
refactor(presentation): slim status_markdown and eliminate Any - #8957
loopx-agent wants to merge 1 commit into
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 #8957 的精确提交 1e11fe506db30d80235fee63061c17076fe4006d 完成全部取证与校验。该 PR 为作者本人提交,受 GitHub 自审规则限制无法使用正式 Approve 动作,因此以 COMMENTED 形式发布等价批准结论。
动机 / Motivation
需要维护或静态检查状态 Markdown 渲染器的开发者,以及消费 status 命令和各类观测测试的调用方,都会受状态渲染模块的静态类型债与重复代码膨胀影响。改动前,status_markdown 模块包含 1597 行代码、47 处 Any 注解、75 个 mypy 静态错误,以及大量重复的字典判空和待办渲染模板,导致静态检查失真且每次调整字段都要在多处同步修改;改动后,该模块收缩至 1102 行、Any 清零且 mypy 达到零错误,对外输出保持完全一致。status_markdown 模块的源码行数从 1597 行降至 1102 行,Any 计数从 47 降至 0,mypy 与 ruff 检查全部零报错,且模块指标基线文件已同步收紧对应的上限。本次改动不改变状态 Markdown 的任何可见输出格式、不修改调用方接口契约,也不改动正由并行 PR 8945 修改中的 PR 评审模块。
从工程维护成本看,旧实现中大量内联的 isinstance(..., dict) 五行判空块与对称重复的待办分组渲染逻辑,不仅掩盖了字段空值处理边界,也使基线中的 any_count: 47 长期阻断严格类型检查。若放任不管,后续每次新增状态摘要段落都会继续复制这些样板并在调用方边界隐藏类型回归;将其收口为一个只改渲染实现与基线棘轮的独立增量切片,既能立刻消除债务,又不会波及并行 PR。
改动思路 / Approach
状态展示渲染器只承担只读投影职责,所有类型收束与重复列表渲染辅助函数均内聚在本地模块中,不引入新的跨模块状态所有者或运行期副作用。当前 PR 仅覆盖状态 Markdown 渲染模块与可维护性基线棘轮文件的收紧,不扩展到控制面状态写入或外部调用方改造。
整体重构遵循只读投影与严格静态边界分离的原则:
- 统一类型入口与只读收束:对外公开函数签名统一接受
Mapping[str, object]与object(如goal_id),内部通过只读视图_map、列表收束_seq、回退查找_pick_map及标量读取_scalar消除Any传播;仅在调用仍要求dict[str, Any]的外部兄弟渲染器或政策摘要函数(如append_goal_acceptance_observation_markdown、append_agent_reward_memory_markdown、execution_profile_summary)时,显式使用_as_dict构造dict[str, object]边界。 - 消除真正重复的渲染分支:抽取
_headline_parts与_append_scalar_fields统一人类奖励与操作门恢复契约两处相同格式的标题和附注行;抽取_append_asset_todo_group合并asset_user_todo与asset_agent_todo两段高度对称的渲染逻辑;抽取_append_operational_todos合并运营视图下的user_todos与agent_todos分支,同时通过include_materials参数精确保留仅用户待办渲染review_material的既有语义。 - 空值与原值语义保真:保留原始渲染器对原始标量(如
None、False、0)与markdown_scalar(...)(将假值归一化为空串)的严格区分,不把未包markdown_scalar的键误包进字符串清洗,确保对空字典、缺省字段、[{}]列表首项等边界输入实现逐字节输出等价。
具体改动 / Changes
本次 PR 共修改 2 个文件(+660 / -1154,净减少 494 行),无单独新增设计规格或 RFC 文档(遵循仓库既有的维护性基线棘轮与 AGENTS.md 工程 hygiene 要求):
loopx/presentation/renderers/status_markdown.py:1597 -> 1102行(-495行),any_count: 47 -> 0,dict_any_count: 0 -> 0。loopx/canary/module_metric_baseline.json:将该模块基线从{"any_count": 47, "dict_any_count": 0}向下棘轮收紧为{"any_count": 0, "dict_any_count": 0, "lines": 1102}。
关键代码讲解
_pick_map(loopx/presentation/renderers/status_markdown.py:29):替代原本分散在 6 处的多层嵌套isinstance(..., dict)三元表达式,按project_asset优先、其次item的顺序检查isinstance(value, Mapping)并直接返回首个命中的映射,同时忠实保留主数据源显式给出空映射{}时不回退到item的原有判定语义。goals_by_id(loopx/presentation/renderers/status_markdown.py:79):从payload.get("run_history")提取goals列表后,筛选具备非空id的映射条目并通过_as_dict返回dict[str, dict[str, object]],保持返回值对既有dict[str, dict[str, Any]]调用方的类型兼容,同时彻底移除Any标注。append_run_history_markdown(loopx/presentation/renderers/status_markdown.py:261):继续作为Run History段落的唯一起点,通过_as_dict桥接调用append_goal_acceptance_observation_markdown与append_goal_artifact_lifecycle_markdown;在读取latest_runs[0]时保留isinstance(latest_runs[0], Mapping)的严格判定,保证当latest_runs为[{}]时仍与基线一致渲染latest:行。append_project_asset_todo_quota_markdown(loopx/presentation/renderers/status_markdown.py:668):利用循环汇总user与agent待办计数生成asset_todos汇总行,再交由_append_asset_todo_group依次输出asset_user_todo(无作用域后缀)与asset_agent_todo(携带goal_todo_scope_suffix),在消除重复切片[1:3]代码的同时保持逐行输出顺序不变。render_status_markdown与_append_operational_todos(loopx/presentation/renderers/status_markdown.py:725, 1027):顶层入口将输入放宽为只读Mapping[str, object](兼容所有dict与只读映射调用方);底部_append_operational_todos统一渲染user_todos与agent_todos,并通过include_materials=True仅在用户待办首个未完成项后输出review_material明细。
对主干的风险 / Risks
本次改动对主干的回归风险低且可控,所有变化均局限于只读 Markdown 文本拼装层,不涉及磁盘状态写入、配额准入、调度锁或数据库权限:
- 潜在回归点与负向边界核查:最容易引入隐性差异的风险点有三处:其一是
_int对bool、str与None的转换边界;其二是空映射{}在_pick_map或latest_runs=[{}]中的真值判定;其三是误将原本直接格式化输出None/False的字段套上markdown_scalar导致变成空串。逐行核对以及基于全部 7 组黄金用例(覆盖空载荷、全量概览、截断告警、候选组、latest_runs=[{}]、多维project_asset回退与空human_reward)和examples/control_plane/status-markdown-smoke.py的前后对照验证均显示输出逐字节一致。 - 调用方与静态兼容性:外部调用点集中在
loopx/cli_commands/status.py、tests/及examples/control_plane/的端到端渲染入口。本地校验已证明改动后status_markdown.py在mypy --follow-imports=silent与--strict下均达到 0 错误,且在共同检查loopx/cli_commands/status.py时未引入任何新增类型报错。 - 语义与词表边界:本次未新增任何状态枚举、闭合字面量集合或约束语义,既有字符集
{"coordinator_reported", "host_observed", "mixed"}为原文件已有分支常量原样保留,未扩展控制面词表,也无待补的 RFC 或注册表对齐项。 - 远端 CI 观察说明:当前 PR 的
inspect-pr-diff、Sign-off、dependency-review、loopx-codex-provider-routing、loopx-repo-health、loopx-obelisk与Summary均已SUCCESS,loopx-core、prepare与kernel-static-checks仍在运行中,本地全量测试与快速预检门已先于精确提交1e11fe506db30d80235fee63061c17076fe4006d完整验证全部改动不变量。
我的整体评价 / Verdict
从长程任务效果看,状态渲染器本身不干预 Goal 推进、预算或续跑决策,因此长期可验证产出与调度公平性均保持不变(preserved),而模块体积收缩 31% 且消除全部 47 处 Any 显著提升了后续长期维护的安全性;从用户体验与视觉界面看,本次改动属于只读文本渲染层内部类型收紧与去重重构,不改变任何前端视图、交互流程或终端呈现文案,已验证全量输出与既有渲染完全一致,视觉检查不适用且无未验证的界面范围(unverified_scope: none)。代码规模和兼容性处理均合理且收束克制,module_metric_baseline.json 同步将基线棘轮下调至 1102 行和 0 个 Any,未新增任何控制面词表(沿用既有结构)。
本地关键验证结果汇总(均在精确提交 1e11fe506db30d80235fee63061c17076fe4006d 上执行通过):
ruff check loopx/presentation/renderers/status_markdown.py tests/canary/test_maintainability_ratchet.py:PASSmypy --follow-imports=silent loopx/presentation/renderers/status_markdown.py(含--strict):PASS(0 errors)pytest -q(覆盖 ratchet、top_level_module_budget、contract_health、presentation 与 control_plane 状态测试共 13 个测试文件):PASS(325 passed)python examples/control_plane/status-markdown-smoke.py:PASS(status-markdown-smoke ok)loopx --format json canary premerge --tier quick --from-git-diff --git-diff-base origin/main:PASS(ok: true,6 项直接检查 + 3 项目录金丝雀均通过,0 失败)loopx --format json check --scan-path loopx/presentation/renderers/status_markdown.py --scan-path loopx/canary/module_metric_baseline.json:PASS(errors: 0)
残余风险极低,合并阶段仍需等待 GitHub 远端运行中的 CI 检查收敛并遵循维护者合入权限门。
English verdict: APPROVE at exact head 1e11fe5: status_markdown.py shrinks from 1597 to 1102 lines with Any reduced from 47 to 0, zero mypy/ruff issues, 325 pytest tests and quick premerge canary passing with byte-for-byte output parity.
Summary
loopx/presentation/renderers/status_markdown.py, eliminate 100% ofAnyannotations, and ratchetloopx/canary/module_metric_baseline.jsondownward.loopx/pr_review.pyafter the open-PR overlap check showed open PR feat(control-plane): assess scope budget proportionality without blocking large features #8945 (codex/pr-anti-bloat-mechanism-20261118) actively modifies it againstmain.Changes
loopx/presentation/renderers/status_markdown.py:Anyannotations withMapping[str, object],dict[str, object],list[object], andobject._map,_as_dict,_seq,_pick_map,_int,_scalar,_csv,_claim_suffix,_headline_parts,_append_scalar_fields) to replace repeated inlineisinstance(..., dict/list)andmarkdown_scalar(... or "")boilerplate.asset_user_todo/asset_agent_todorendering (_append_asset_todo_group), operationaluser_todos/agent_todosrendering (_append_operational_todos),contract_errors/contract_warningsblocks, andhuman_reward/operator_gate_resume_contractsections while keeping all public signatures and Markdown output identical.loopx/canary/module_metric_baseline.json:loopx/presentation/renderers/status_markdown.pyfrom{"any_count": 47, "dict_any_count": 0}to{"any_count": 0, "dict_any_count": 0, "lines": 1102}.Module Metrics
lines(status_markdown.py)any_count(status_markdown.py)dict_any_count(status_markdown.py)2 files)Verification
Tested on pushed commit
1e11fe506d:ruff check loopx/presentation/renderers/status_markdown.py tests/canary/test_maintainability_ratchet.py: passedmypy --follow-imports=silent loopx/presentation/renderers/status_markdown.py(and--strict):0errors (down from 75)pytest -qacross ratchet, top-level module budget, contract health, presentation, and control-plane status tests (13test files):325 passedpython examples/control_plane/status-markdown-smoke.py: passed (status-markdown-smoke ok)loopx --format json canary premerge --tier quick --from-git-diff --git-diff-base origin/main:ok: true(6direct checks +3catalog canaries passed,0failures)loopx --format json check --scan-path loopx/presentation/renderers/status_markdown.py --scan-path loopx/canary/module_metric_baseline.json:ok: true,errors: 0