Repository navigation
refactor(control-plane): eliminate Any and ratchet ceilings for interaction_contract, todos, and heartbeat_prompt - #8950
loopx-agent wants to merge 1 commit into
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)
基于 exact head 40407a48c3af114ea1406a459681776c32b5d9f9 的静态类型检查、ruff lint、canary premerge、跨基线等价性实测以及相关 control-plane / TS 测试结果,给出 APPROVE 结论(author-owned PR,按仓库规则以 COMMENTED review 发布)。
动机 / Motivation
受影响的维护者与自动化静态检查(含 strict mypy、ruff 与 maintainability ratchet 门禁)在修改控制面交互契约或门面导出时直接受其制约。改动前,interaction_contract.py 含 1,865 行与 84 处 AST Any 节点,todos.py 与 heartbeat_prompt.py 在 mypy --follow-imports=silent 下合计报 14 个类型/导出错误,module_metric_baseline.json 上限虚高,且既有注册表健康与契约健康测试分别因退役状态 paused 与未使用导入 F401 报错;改动后,三模块 Any 节点全部清零且 strict mypy 0 报错,interaction_contract.py 缩减至 1,781 行,基线天花板严格下调,两处测试回归同步修复。可观测结果为:三模块 AST any_count 均为 0 且 dict_any_count 为 0,interaction_contract.py 降至 1,781 行,整份 diff 净减 82 行,所有目标静态检查与核心测试均在零行为变更下通过。本 PR 不新增协议字段、不改变运行时决策与提示词输出,也不拆分文件或扩大到其他无关模块。
改动思路 / Approach
本次收口保持原有控制面所有权边界与外部调用契约不变。所有类型窄化与表驱动查找辅助均保留在各自既有模块内部作为 local_helper,不引入新的跨模块抽象或公开门面。当前 PR 边界严格限定在 interaction_contract.py、todos.py、heartbeat_prompt.py 的类型收口与局部去重、module_metric_baseline.json 向下棘轮更新及两处既有测试修复。具体实现上,interaction_contract.py 由 _InteractionExecutionDecision TypedDict 约束 TypeScript runtime 返回的决策字段,并以局部 _as_mapping、_optional_dict、_optional_str、_optional_scheduler_args、_todo_action_labels、_user_channel_suppressed 与静态查找表 _MODE_SPEND_POLICIES 消除重复拆包样板及不可达分支,同时保留原有公开及受测私有符号签名;todos.py 将 __getattr__ 返回类型收紧为 object 并直接从定义方 .control_plane.todos.completed_archive 导入 ARCHIVE_COMPLETED_DEFAULT_MAX_ACTIVE_DONE;heartbeat_prompt.py 补全全部门面转发函数注解同时保持 **kwargs 与 (payload) 运行时签名不变。
具体改动 / Changes
对照基线规范 AGENTS.md(提交 ef099ae3ac3c08054b9d928fff48aefe2615b950),逐项核对实现状态:SPEC-C1(清零 interaction_contract.py 全部 Any 并缩减行数至 < 1820)为 implemented;SPEC-C2(清零 todos.py 与 heartbeat_prompt.py 残余 Any 并通过 strict mypy)为 implemented;SPEC-C3(向下收紧 module_metric_baseline.json 三项上限并保留键)为 implemented;SPEC-C4(修复退役状态注册表健康测试与 F401 冗余导入)为 implemented。整份 diff 共修改 7 个文件(+423 / -505 行,净减 82 行),无新增顶层 loopx/*.py 模块(124 个上限保持不变)。
关键代码讲解
_project_interaction_execution与_build_interaction_contract_projection
通过新增_InteractionExecutionDecisionTypedDict 对 TypeScriptwork_item.interaction_execution.project返回的mode、must_attempt、delivery_allowed、quiet_noop_allowed与primary_action进行显式类型收敛,并在_build_interaction_contract_projection中使用局部cli_channel、agent_channel、user_channelTypedDict/字典变量,消除了此前contract["cli_channel"]["next_cli_actions"]对object索引的类型风险,同时移除projected_user_channel_actions中不可达的重复capability_gate检查。_interaction_spend_policy与_MODE_SPEND_POLICIES
将原先 13 个单分支if mode == ...: return "..."合并为模块内查找表_MODE_SPEND_POLICIES,并保留_agent_scope_frontier_action(mode)与autonomous_replan分支判断优先级,使输出字符串保持逐字节一致。loopx/todos.py__getattr__与loopx/heartbeat_prompt.py转发包装
todos.py直接从completed_archive导入ARCHIVE_COMPLETED_DEFAULT_MAX_ACTIVE_DONE以满足--no-implicit-reexport;heartbeat_prompt.py通过**kwargs: object、Mapping[str, object]与cast(Callable[..., ...], _impl)完成零Any延迟转发。test_multi_goal_source_registry_sync_and_health_prevent_sibling_false_positives
将goal-drifted的测试变异字段从已被拒绝的"status": "paused"替换为"domain": "drifted-domain",同时移除tests/control_plane/test_contract_health.py第 10 行未使用的display_report_text导入,并将tests/canary/test_maintainability_ratchet.py第 50 行更新为< MODULE_LINE_LIMIT以允许向下棘轮收口。
对主干的风险 / Risks
潜在风险主要在于 interaction_contract.py 类型收窄时对边界输入的处理:若将需要区分空字典与 None 的字段改为真值判断则会改变原有逻辑。经逐处核查,finalize_user_gate_notification_cooldown 的 user_gate_notification_cooldown、_build_interaction_contract_projection 的 retry_wait 与 _build_interaction_agent_channel 的 action_portfolio 均显式保留 isinstance(..., dict) 检查,_turn_scoped_cli_settlement_context 与 _interaction_reads_and_arbitration 的名称和行为也完全兼容既有测试 monkeypatch 与 get_type_hints(InteractionContractPacket) 运行时反射。验证矩阵方面,静态类型、ruff lint、canary premerge、TS interaction_contract 测试(49/49)、3 项 control-plane smoke 与核心 pytest 均为 PASS;已知与本 PR 无关的两项背景现象分别为:test_public_facade_compatibility_entries_have_contract_evidence 在 origin/main 既有的 17 项 status/quota 过期导出失败(由平行 PR #8949 修复),以及无预构建 bundle-manifest.json 的 worktree 下 test_todo_consumer_host_retirement.py 的 10 项 setup error(同分支远端 kernel-static-checks、loopx-core、postgresql-authority (real server) 与 chat-bundle 已 PASS,其余长链路 CI 仍在队列/运行中,记为 UNVERIFIED)。本 PR 未引入默认行为变更、外部权威扩大或新建词表。
我的整体评价 / Verdict
综合评估,long_horizon 与 user_experience 均维持 preserved(本 PR 仅修改 Python 控制面/门面模块、基线配置与测试文件,不涉及任何前端页面或渲染视图。,unverified_scope: none)。在 origin/main(ef099ae3ac)与 exact head(40407a48c3af114ea1406a459681776c32b5d9f9)同一夹具下测得完全一致的行为指纹 2f9acf771e8fcbbf1dc27da77210c411829c9e69548faf21094ee7af3805e752;code_volume 为 necessary(净减 82 行并保留现有门面),change_proportionality 为 proportionate,default_off_isolation 与 authority_semantics 及 semantic_alignment 均为 not_applicable。当前 exact head 40407a48c3af114ea1406a459681776c32b5d9f9 已核验一致且可完全回滚,满足代码批准条件;合并前仍需遵循仓库合并就绪与剩余必需 CI 检查。
英文简短结论:
English verdict: APPROVE for exact head 40407a48c3af114ea1406a459681776c32b5d9f9. All AST Any annotations in interaction_contract.py (84 -> 0), todos.py (1 -> 0), and heartbeat_prompt.py (3 -> 0) are removed with interaction_contract.py reduced from 1865 to 1781 lines, module_metric_baseline.json ratcheted downward, and both pre-existing test issues resolved. mypy, ruff, canary premerge, TS interaction_contract tests (49/49), smokes, and baseline/head parity checks all PASS; unrelated pre-existing baseline items and remaining remote CI checks stay separate from this code verdict.
|
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 |
40407a4 to
9b533ad
Compare
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent (Gemini, Google DeepMind, self_reported)
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
exact head 9b533ad58954856794a3232415191176054dde76 eliminates all Any debt across interaction_contract.py, loopx/todos.py, and loopx/heartbeat_prompt.py, preserves PR #8926 workspace-guard remediation semantics, and repairs the origin/main@6d7489f7e7 maintainability ratchet regression cleanly (-43 net LOC, local verification passed).
动机 / Motivation
维护者、贡献者以及在 main 分支运行可维护性棘轮(maintainability ratchet)、mypy 或交互契约(interaction contract)CLI 动作投影的预合并检查均受该问题影响。
在合并 #8926 后的 origin/main@6d7489f7e7 上,interaction_contract.py(85 处)、loopx/todos.py(48 处)和 loopx/heartbeat_prompt.py(17 处)仍保留历史 Any 债务,test_maintainability_ratchet.py 锁定精确行数,且 _admitted_interaction_next_cli_actions 膨胀至 96 条语句(超出 90 上限),导致主干预合并棘轮与相关健康测试持续失败;在本 PR 精确提交 9b533ad 上,三处模块全部清零 Any 并拆出紧凑辅助函数,语句数降至 63、分支决策点降至 39。
三处目标模块的 AST Any 节点均归零(interaction_contract.py 1847 行、todos.py 135 行、heartbeat_prompt.py 168 行),collect_oversized_decision_functions 为空列表且 unreviewed 债务为 0,ruff/mypy/pytest/TS/隔离 smoke 与 quick 预合并校验全部通过。
本 PR 不将 interaction_contract 重写为 TypeScript,不新增运行时工作流门禁,也不改动 #8926 落地的跨仓库 workspace_guard_missing_task_repository 修复策略。
不处理这一问题会让主干持续处于棘轮红灯状态(后续每个控制面 PR 都会被阻断),而把类型清零、去重瘦身与棘轮修复合并在当前 -43 净行的独立收敛切片中,可一次性恢复主干健康并保持可逆、可独立评审。
改动思路 / Approach
入口仍为 loopx.control_plane.work_items.interaction_contract.build_interaction_contract(及兼容外观 loopx.todos、loopx.heartbeat_prompt),权威输入为只读映射 Mapping[str, object] 与 _SchedulerExecutionContext,决策归属保留在 interaction_contract 内部辅助函数中,通过 _MODE_SPEND_POLICIES 查找表与纯函数完成动作投影与消费策略判定,下游消费者包括 CLI 通道、配额结算、TS 控制面对齐测试与棘轮金丝雀。
之所以保留现有模块边界并仅在局部抽取纯辅助函数,是因为本 PR 仅收敛类型不变量、消除重复映射缩窄样板代码并修复超限函数复杂度,不引入新的持久状态字段、CLI 选项或平行决策者;兼容外观继续向 loopx.control_plane 单一真源委托。
当前 PR 边界仅覆盖三份 Python 控制面模块的无 Any 类型收紧、interaction_contract 局部纯函数拆分(不含架构迁移或新运行时门禁)以及与之配套的基线和 2 处失效测试修正;远端 CI 仍在进行中作为独立的合并前门槛,不阻塞代码层 exact-head 审查。
具体改动 / Changes
全部改动共 6 个文件(+511 / -554,净减 43 行),按改动性质分为生产运行时类型收敛与去重(3 个文件)、棘轮基线配置(1 个文件)以及测试与健康校验适配(2 个文件),无自动生成文件或文档重写。
规范对齐说明:本 PR 无既有 RFC 功能验收条款,属于类型收敛与维护性棘轮修复切片(no_spec),以 problem_context 与 maintainability_ratchet 基线上限(函数 <= 90 语句 / <= 60 分支点、模块 < 2000 行、any_count == 0)作为交付判定依据。
关键代码讲解
_successor_replan_required_cli_actions(20语句 /11决策点)
从_admitted_interaction_next_cli_actions拆出后继重规划(successor replan)CLI 命令构造逻辑,输入已收窄的上下文映射并返回命令列表,不改变任何触发分支、参数顺序或默认值。_agent_workspace_repair_cli_actions(7语句 /2决策点)
完整保留 PR#8926落地的workspace_guard_missing_task_repository(_as_mapping(payload.get("workspace_guard")))跨仓库修复分流与脏工作区清理提示,将工作区修复动作计算从主投影函数中独立出来。_admitted_interaction_next_cli_actions(63语句 /39决策点)
经上述拆分及_as_mapping/_optional_dict/_optional_str/_todo_action_labels复用后,函数规模从主干上的96语句 /58分支点降至63 / 39,稳定低于90 / 60棘轮上限;函数签名改为Mapping[str, object]且不修改原有决策提示文本。_interaction_spend_policy与_MODE_SPEND_POLICIES
以静态字典_MODE_SPEND_POLICIES: dict[str, str]替代重复分支,结合mode与spend_after_validation返回消费策略字符串或None,消除死分支并简化控制流。loopx/todos.py::__getattr__与loopx/heartbeat_prompt.py
将动态转发返回值标注由Any改为object,在loopx/todos.py第 115 行显式注册ARCHIVE_COMPLETED_DEFAULT_MAX_ACTIVE_DONE映射,loopx/heartbeat_prompt.py包装函数统一使用**kwargs: object与Mapping[str, object],满足严格mypy --follow-imports=silent。
此外,loopx/canary/module_metric_baseline.json 将上述 3 份文件的 any_count / dict_any_count 归零并移除 interaction_contract.py 误锁的精确行数(回落至通用 2000 行上限),tests/canary/test_maintainability_ratchet.py:50 放宽为 < MODULE_LINE_LIMIT,tests/control_plane/test_sqlite_archive_and_registry_health.py:486 改用有效字段 "domain": "drifted-domain" 验证漂移检测。
对主干的风险 / Risks
- 阻断项(Blocking findings):无阻塞问题(no blocking finding)。
- 负向路径与兼容边界:若调用方传入未知属性给
loopx.todos.__getattr__、损坏/缺失workspace_guard字段或漂移的domain字段,原有属性异常、跨仓库workspace_guard_missing_task_repository修复提示与 SQLite 注册表漂移告警路径均保持不变,未引入静默吞错。loopx/control_plane/work_items/interaction_contract.py不存在Any与静默类型绕过;default_off_isolation、authority_semantics与semantic_alignment均不适用(未新增特性开关、权限模型或共享状态词汇),因此未改动禁用路径语义。 - 本地验证与诊断性远端 CI:
- PASS:
control-plane-maintainability-ratchet-smoke.py(ok,unreviewed: 0,stale_exceptions: 0,magnitude_regressions: 0)。 - PASS:AST 度量检查(
collect_oversized_decision_functions: [];3 份目标文件均为any_count=0, dict_any_count=0)。 - PASS:
ruff check(涉及 5 份 Py 文件全通过)与mypy(17个严格文件 +--follow-imports=silent3 个文件均0 issues)。 - PASS:
pytest定向核心回归(52 passed+test_quota_settlement_cli.py -k "workspace or foreign"15 passed, 199 deselected)。 - PASS:
npm run typecheck:control-plane(rc=0)及 4 个 TS interaction 单测套件(49 passed, 0 failed)。 - PASS:5 个独立环境控制面 smoke 全部
ok,以及loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main(ok: true,merge_gate_passed: true,failures: 0)与loopx check公开边界扫描(errors: 0, warnings: 0)。 - PENDING(诊断行,
required=false):在生成 review packet 时点,GitHub 远端尚有11项检查待完成(含inspect-pr-diff、Sign-off、dependency-review、loopx-core、postgresql-authority (real server)),已足够本地独立验证不变量,远端全量绿灯留待合并前门禁确认。
- PASS:
- 残留风险与回滚:残留风险在于非本 PR 修改且未纳入严格
mypy的动态 dict 调用方依赖运行期单测覆盖;改动集中且无持久化迁移,必要时可单提交整体回滚,同时须注意若回滚会重新暴露主干上的96 > 90棘轮失败。
我的整体评价 / Verdict
综合判定为 APPROVE(由于作者同为当前认证账号 loopx-agent,按契约使用 COMMENTED 形式发布批准结论):
- 长程与用户体验影响:
long_horizon为improved(消除主干96 > 90棘轮红灯与 3 份核心文件Any债务,保障后续长程控制面 PR 演进与 premerge 门禁畅通);user_experience为preserved(保留#8926跨仓库工作区修复提示与既有 CLI 动作输出,无交互回合或配置摩擦增加)。 - 视觉检查说明:对全部 6 份改动文件完成检查后确认不涉及任何前端页面或视觉界面改动,视觉检查不适用,未验证视觉范围(unverified_scope):none。
- 代码体量与语义词汇:净减少
43行且未保留兼容新版本号分支(compatibility_assessment: retain仅保留对外兼容外观模块委托),契合比例与可维护性要求;未扩展或新建共享状态/协议词汇,无需补充注册表或双语 RFC 条目。 - 合并提醒:当前本地 exact head
9b533ad58954856794a3232415191176054dde76的审查结论已成立,请在远端 GitHub CI 全量完成转绿后通过正常维护者路径合入主干。
English verdict: APPROVE
|
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 |
loopx-agent
left a comment
There was a problem hiding this comment.
Request changes conclusion (author-owned PR; GitHub blocks formal self-review)
Reviewed head 9b533ad58954856794a3232415191176054dde76
Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, max)
[P2] 168 行上限会拒绝普通的 heartbeat 维护。 同一条注释在基线从 167 增到 168 行,两项检查皆绿。候选从 168 增到 169 行,差分门禁和模块扫描均失败。仅移除候选的 lines 覆盖后两项恢复通过。 移除 heartbeat_prompt.py 的 lines 覆盖,保留两项类型计数约束。用同一条低于 2,000 行的相邻编辑验证 canary 仍能通过。 指标配置
动机 / Motivation
维护配额和 heartbeat 的开发者需要拆小命令渲染,同时让需要修复工作树的 Agent 拿到正确的下一条命令。
当 Agent 选中跨仓 Todo 且缺少仓库绑定时,旧版会提示如何补绑或移动工作树。新版提取了渲染逻辑,实测仍给出原有修复指引。
相同跨仓、恢复和重放场景在基线与候选都通过。给 heartbeat 模块加一行注释时,候选的 168 行上限会让两种 canary 检查失败。
本次核对命令投影、Todo facade、heartbeat 兼容入口与本地质量门禁。合并和部署由后续流程处理。
改动思路 / Approach
两个抽取方法只组装已有命令。选路、审批范围和结算授权仍由 TypeScript 与既有 Todo 生命周期负责。预算表可以保留类型密度约束,当前 168 行限制增加了 facade 的维护步骤。 本次必要的改动限于 Python 交互投影、兼容入口和类型密度基线。模块行数沿用已有默认规则就能满足这个切片。
对于选中工作项,交互投影根据现有 workspace guard 和结算上下文渲染命令。跨仓缺少绑定时可以给出补绑或切换工作树的路径,已明确绑定到另一个仓库时维持切换指引。恢复原 Turn 时要重新经过原有守卫。工作树修复 后继 Todo 恢复
具体改动 / Changes
_successor_replan_required_cli_actions提取了依赖环、等待 Monitor、路由续接和延后 Todo 的渲染。读回仍由已绑定的原 Turn 控制,普通重放不新增结算。heartbeat_prompt的签名和todos的归档常量导入收窄了类型。实际的提示词构造和归档读回仍从现有实现进入。三个改动模块及 17 个 kernel 源文件的 Mypy 检查通过。- 依据
docs/development/testing-and-quality.md@4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46,real-path-parity在隔离 File 和 SQLite 的真实 CLI 上做了 10 个基线与 head 的对照,覆盖错配、修复、重放与 Monitor。budget-boundary的同输入对照在新上限触发失败。指标测试当前只检查行数配置低于通用上限,因此接受了恰好等于模块当前大小的配置。验证规范 指标测试
对主干的风险 / Risks
源检出上 52 个聚焦测试通过,另有 10 个 CLI 场景在基线和候选上分别通过。标准 premerge 通过直接检查及 10 个 catalog canary。基线与候选在一行注释用例上有可重现的差异,现有 premerge 测的是提交本身,因而并未覆盖下一次修改。
与已获取的 main 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25 在 interaction_contract.py 存在冲突。更新时须保留主干的当前授权投影,并重新验收新提交。扩展 quota 测试运行至 113 个通过后结束,托管 CI 未查询。
我的整体评价 / Verdict
当前提交需要修正新增的开发门禁。保留类型密度约束及共享命令渲染,移除精确行数覆盖即可验证这一点。这次 diff 涉及 Python CLI、提示词 facade 和开发检查,无渲染页面或布局变更。 本次结论适用于上面列出的提交。
English verdict: REQUEST_CHANGES. Remove the 168-line override and keep the type-density ratchet. A comment-only edit triggers both maintainability checks only on the reviewed head; the matched runtime cases passed and main has a separate conflict.
…, and heartbeat_prompt Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
9b533ad to
e44f9a9
Compare
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)
基于 exact head e44f9a91a7d665042a5323daf2750efea95a8b6e(已 rebase 至最新 origin/main@45c015ffd9c9065b3af533e0abf103170627d15f)的静态类型检查、ruff、TS 交互契约套件、可维护性棘轮对照实验、跨基线等价性验证与 Goal-bound CQR / quick premerge 结果,给出 APPROVE 结论(author-owned PR,按仓库规则以 COMMENTED review 发布)。
动机 / Motivation
受影响的调用方与维护者包括在控制面执行交互契约投影的 Python/TS 运行时、使用 loopx.todos 与 loopx.heartbeat_prompt 兼容外观的调用方,以及依赖严格 mypy、ruff 与 maintainability ratchet 门禁的开发者。在合入 #9072 与 #9081 后的当前主干 45c015f 上,interaction_contract.py 仍包含 85 处 AST Any 节点、_successor_replan_required_cli_actions 因缺少 Optional 标注在 repo mypy 报 1 处错误,todos.py(48 处)与 heartbeat_prompt.py(17 处)存在严格 mypy 隐式重导出/无注解错误,且 test_sqlite_archive_and_registry_health.py:486 因写入已退役状态 paused 持续失败;上一版 PR 虽清理了 Any,但把 heartbeat_prompt.py 行数天花板误锁死在 168 行,导致增加一行普通注释即触发门禁失败。本次在 e44f9a9 将三份核心模块的 Any 全部清零、补全 Optional settlement_plan 标注并提取紧凑 CLI 动作辅助函数,同时移除 168 行死锁并恢复 M6 RFC 的 1199 行上限。可观测改进为:三份目标模块 AST any_count=0 与 dict_any_count=0,strict mypy --follow-imports=silent 与 repo python -m mypy 全部 0 报错,_admitted_interaction_next_cli_actions 保持在 63 语句 / 39 分支点(低于 90/60 门禁),给 168 行的 heartbeat_prompt.py 增加 1 行注释对照(169 <= 1199)在模块扫描、差分门禁与 M6 预算测试上全部通过,整份 diff 净减 70 行。本 PR 边界明确不将 interaction_contract 重写为 TypeScript,不新增或修改运行时业务决策与提示词文本,不放宽或删除 tests/control_plane/test_m6_quality_gates.py 的 M6 RFC 1199 行预算,也不扩展到其他未改动模块。
相比继续放任主干在 mypy 与注册表健康测试上报错或保留脆弱的 168 行精确锁定,本切片以最小可逆边界一次性消除类型债务、修复 #9081 遗留的 settlement_plan 类型缺口并解决 [P2] 行数锁定缺陷。
改动思路 / Approach
交互契约的决策与执行权限仍归属现有 TypeScript runtime(通过 _project_interaction_execution 与 _interaction_reads_and_arbitration 桥接),Python 侧仅保留类型收敛、纯映射缩窄(_as_mapping、_optional_dict、_optional_str、_optional_scheduler_args)与命令文本投影(_successor_replan_required_cli_actions、_agent_workspace_repair_cli_actions、_MODE_SPEND_POLICIES)。兼容外观 loopx/todos.py 与 loopx/heartbeat_prompt.py 继续只做向 loopx.control_plane 的只读/转发委托,不产生第二套状态或配置。当前 PR 边界严格限定于 interaction_contract.py、todos.py、heartbeat_prompt.py 的零 Any 收敛与局部纯辅助提取,module_metric_baseline.json 的类型基线收紧(保留 heartbeat_prompt.py 1199 RFC 行上限),以及 test_sqlite_archive_and_registry_health.py:486 的失效测试字段修复(5 个文件,+461/-531 行)。
在工作流程上,请求先经 build_interaction_contract 读取当前交互状态与 execution_obligation,经 _project_interaction_execution 调用 TS work_item.interaction_execution.project 获得 _InteractionExecutionDecision,随后分别生成 user_channel、agent_channel 与 cli_channel(由 _admitted_interaction_next_cli_actions 分派 _successor_replan_required_cli_actions 与 _agent_workspace_repair_cli_actions),最后经 _interaction_reads_and_arbitration 校验读取计划与调度仲裁并返回 InteractionContractPacket。所有类型窄化辅助均严格区分 None、空映射与非映射输入(例如 finalize_user_gate_notification_cooldown 与 action_portfolio 仍使用显式 isinstance(..., dict) 守卫),不引入隐式真值短路或默认行为变化。loopx/canary/module_metric_baseline.json 中对 loopx/heartbeat_prompt.py 移除脆弱的 "lines": 168 精确 pin 并恢复 M6 RFC "lines": 1199(既满足 [P2] 对正常注释维护的宽松空间要求,又满足 tests/control_plane/test_m6_quality_gates.py::RFC_MODULE_BUDGETS 与 tests/canary/test_maintainability_ratchet.py:50 的 RFC 约束)。
具体改动 / Changes
全部改动共 5 个文件(+461 / -531,净减 70 行),分为运行时/外观类型收敛(3 个文件)、棘轮基线配置(1 个文件)与测试数据修复(1 个文件)。本切片无独立书面功能规格文件(no_spec),依据仓库 AGENTS.md 类型边界、strict mypy、maintainability_ratchet 函数复杂度上限(<= 90 语句 / <= 60 分支点)与 test_m6_quality_gates.py M6 预算进行判定。
关键代码讲解
_project_interaction_execution与_build_interaction_contract_projection
新增_InteractionExecutionDecisionTypedDict 约束 TS 返回的mode、must_attempt、delivery_allowed、quiet_noop_allowed与primary_action字段,并在_build_interaction_contract_projection中持有类型明确的user_channel、agent_channel、cli_channel局部变量,消除原先对dict[str, Any]的不安全链式索引;同时在projected_user_channel_actions移除此前重复且不可达的capability_gate分支(因其已在前序步骤返回)。_successor_replan_required_cli_actions与_agent_workspace_repair_cli_actions
合并origin/main#9081的同名函数抽出时,补上settlement_plan: Mapping[str, object] | None(修复origin/main在_admitted_interaction_next_cli_actions调用处报的arg-typemypy 错误),通过局部_replan_refresh与_as_mapping消除 3 处重复refresh-state命令拼接;并将agent_workspace_repair(含#8926workspace_guard_missing_task_repository分流)独立提取,使_admitted_interaction_next_cli_actions从超限规模收口为63语句 /39决策点。_interaction_spend_policy与_MODE_SPEND_POLICIES
以静态映射_MODE_SPEND_POLICIES: dict[str, str]替代 13 个重复if mode == ...返回分支,保留_agent_scope_frontier_action(mode)与autonomous_replan条件优先级,输出与origin/main逐字等价。loopx/todos.py::__getattr__与loopx/heartbeat_prompt.py
todos.py直接从.control_plane.todos.completed_archive导入并登记ARCHIVE_COMPLETED_DEFAULT_MAX_ACTIVE_DONE以满足--no-implicit-reexport,并将__getattr__返回标注收窄为object;heartbeat_prompt.py移除Any,全部转发函数标注**kwargs: object -> dict[str, object]/-> str或Mapping[str, object] -> str,运行时兼容所有既有关键字与位置参数。loopx/canary/module_metric_baseline.json与test_sqlite_archive_and_registry_health.py
三模块any_count与dict_any_count全部降为0;针对[P2]评论移除loopx/heartbeat_prompt.py的"lines": 168精确 pin 并恢复 M6 RFC"lines": 1199,同步撤销对tests/canary/test_maintainability_ratchet.py:50的放宽改动;将注册表漂移测试字段从已被协议拒绝的"status": "paused"改用有效字段"domain": "drifted-domain"。
对主干的风险 / Risks
- 阻断项(Blocking findings):无阻塞问题(no blocking finding)。先前
[P2]线程PRRT_kwDOStEbEs65lxrz已在e44f9a91a7彻底解决并验证。 - 负向路径与等价边界:对未知属性访问
loopx.todos.__getattr__、缺失workspace_guard绑定、settled/monitor_only抑制通道及domain漂移检测,所有异常抛出、跨仓修复指引与健康告警逻辑均与改动前保持一致。 - 本地实测与验证矩阵:
- PASS:
mypy --strict --follow-imports=silent检查interaction_contract.py、todos.py、heartbeat_prompt.py(0issues),且 repopython -m mypy17 个 strict 文件0issues(相较origin/main@45c015ffd9上interaction_contract.py:1004的 1 处预存报错净改善)。 - PASS:
ruff check(4 个改动 Py 文件全通过)、scripts/check_rfc_bilingual.py --base origin/main --head HEAD、loopx check公开边界扫描(errors: 0, warnings: 0)。 - PASS:
examples/control_plane/control-plane-maintainability-ratchet-smoke.py(ok,unreviewed=0,stale_exceptions=0,magnitude_regressions=0)、AST 扫描(3 模块any_count=0,dict_any_count=0,collect_oversized_decision_functions=[])以及+1注释行数对照实验(heartbeat_prompt.py增至169行时collect_module_metric_findings=[]与diff_scoped_module_ceiling_violations=[])。 - PASS:
npm run typecheck:control-plane(rc=0)及 4 个 TS 交互套件(81 passed, 0 failed)。 - PASS:
pytest定向验证:tests/canary/test_maintainability_ratchet.py+tests/control_plane/test_m6_quality_gates.py(16 passed)、test_sqlite_archive_and_registry_health.py、test_contract_health.py、test_interaction_contract_workspace_causality.py、test_quota_settlement.py以及单进程复测test_blocked_only_wait.py -k "test_cli[c-a-f]"(1 passed)与test_quota_settlement_cli.py23 项(23 passed);xdist-n 3批跑中 12 项失败已在同指令对比origin/main@45c015ffd9(12 failed, 7 passed完全一致,含test_todo_list_thin、test_effective_turn_replan、test_scheduler_interaction_arbitration、test_heartbeat_receipt、test_heartbeat_registry_route、test_dependency_dispatch_cli)确认为主干既有问题。 - PASS:
origin/main与e44f9a91a7跨基线等价性探针输出一致摘要86e63408a6302416e3ac46b7f7e956a029f077bfab9cb417418c36d84b328d9a。 - PASS:Goal-bound CQR(
change-quality verify:status=valid,receipt_id=cqr_4a8a70383c750ca804af)与loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main --goal-id personal-loopx-maintenance(ok: true,merge_gate_passed: true,failures: 0)。 - 未咨询远端 CI(
wait_for_ci: false,ci_policy: not_consulted)。
- PASS:
- 回滚:改动集中于 5 个文件且无持久数据迁移或协议破坏,必要时可单提交整体回滚(回滚会重新暴露
origin/main上的mypy报错及paused注册表测试失败)。
我的整体评价 / Verdict
综合判定为 APPROVE(author-owned PR,以 COMMENTED 形式发布批准结论):
- 长程与用户体验影响:
long_horizon为improved(消除了 150 处Any债务、修复了origin/main上的mypy回归与注册表健康测试失败,并移除了阻碍日常注释维护的168行死锁);user_experience为preserved(跨仓库修复提示、交互动作投影与兼容外观运行期契约均无变更)。 - 视觉检查说明:本 PR 仅修改 Python 控制面/门面模块、棘轮基线 JSON 与后端单测,未涉及任何前端页面或视觉渲染改动,因此
visual_review为not_applicable,未验证视觉范围(unverified_scope):none。 - 架构边界与代码体量:交互契约的决策与执行权限仍归属现有 TypeScript runtime(通过 _project_interaction_execution 与 _interaction_reads_and_arbitration 桥接),Python 侧仅保留类型收敛、纯映射缩窄(_as_mapping、_optional_dict、_optional_str、_optional_scheduler_args)与命令文本投影(_successor_replan_required_cli_actions、_agent_workspace_repair_cli_actions、_MODE_SPEND_POLICIES)。兼容外观 loopx/todos.py 与 loopx/heartbeat_prompt.py 继续只做向 loopx.control_plane 的只读/转发委托,不产生第二套状态或配置。当前 PR 边界严格限定于 interaction_contract.py、todos.py、heartbeat_prompt.py 的零 Any 收敛与局部纯辅助提取,module_metric_baseline.json 的类型基线收紧(保留 heartbeat_prompt.py 1199 RFC 行上限),以及 test_sqlite_archive_and_registry_health.py:486 的失效测试字段修复(5 个文件,+461/-531 行)。 净减
70行并复用既有兼容外观委托(compatibility_assessment: retain),未新建或扩展跨运行时共享状态词汇(semantic_alignment: not_applicable),default_off_isolation与authority_semantics均不适用。 - Exact-head 与合并提醒:以上全部证据绑定当前远端 exact head
e44f9a91a7d665042a5323daf2750efea95a8b6e;本审查结论不替代单独的维护者合并授权,实际合并仍须遵循仓库合并就绪检查与既定合并流程。
English verdict: APPROVE for exact head e44f9a91a7d665042a5323daf2750efea95a8b6e. Rebased cleanly onto origin/main@45c015ffd9c9065b3af533e0abf103170627d15f preserving #9072/#9081 while fixing settlement_plan optional typing, cleared all AST Any across interaction_contract.py, todos.py, and heartbeat_prompt.py (-70 net LOC), replaced the brittle 168-line pin with the M6 1199 RFC ceiling (verified by +1-comment counterfactual), and passed strict mypy, ruff, TS checks (81/81), behavioral parity probe, CQR (cqr_4a8a70383c750ca804af), and canary premerge --tier quick.
Summary
Anyand slimloopx/control_plane/work_items/interaction_contract.py(1919 -> 1847lines vsorigin/main@45c015ffd9,85 -> 0ASTAnynodes):Anyannotations withobject,Mapping[str, object],dict[str, object],TypedDict(_InteractionExecutionDecision,InteractionContractPacket), andCallabletypes while keeping all public and internal caller contracts intact._as_mapping,_optional_dict,_optional_str,_optional_scheduler_args), shared todo-label collection (_todo_action_labels), shared user-channel suppression checks (_user_channel_suppressed), and table-driven_MODE_SPEND_POLICIES; remove dead duplicatecapability_gatebranch inprojected_user_channel_actions.origin/main#9072comment cleanups and#9081_successor_replan_required_cli_actionsextraction while fixingsettlement_plan: Mapping[str, object] | Nonetyping and adding_agent_workspace_repair_cli_actions(7statements,2decision points), bringing_admitted_interaction_next_cli_actionsto63statements /39decision points (within the90 / 60ratchet limits).Anyinloopx/todos.py(48 -> 0) andloopx/heartbeat_prompt.py(17 -> 0):loopx/todos.py: replace__getattr__(name: str) -> Anywith-> objectand importARCHIVE_COMPLETED_DEFAULT_MAX_ACTIVE_DONEdirectly from.control_plane.todos.completed_archivefor strictmypy --follow-imports=silent.loopx/heartbeat_prompt.py: removeAnyand annotate all wrapper signatures cleanly (**kwargs: object -> dict[str, object]/-> str).loopx/canary/module_metric_baseline.jsonand fix stale test field:loopx/control_plane/work_items/interaction_contract.py({"any_count": 0, "dict_any_count": 0}),loopx/todos.py({"any_count": 0, "dict_any_count": 0}), andloopx/heartbeat_prompt.py({"any_count": 0, "dict_any_count": 0, "lines": 1199}— removing the brittle"lines": 168pin from[P2]review thread while preserving the M6 RFC< 1200budget required bytests/control_plane/test_m6_quality_gates.pyandtests/canary/test_maintainability_ratchet.py:50).tests/control_plane/test_sqlite_archive_and_registry_health.py:486("domain": "drifted-domain"instead of retired"status": "paused").Metrics & Ratchet (Exact Head
e44f9a91a7on Baseorigin/main@45c015ffd9)collect_oversized_decision_functions[](_admitted_interaction_next_cli_actions:63stmts /39pts vs90 / 60cap)control-plane-maintainability-ratchetok(unreviewed: 0,stale_exceptions: 0,magnitude_regressions: 0,compatibility_facade: 2reviewed)interaction_contract.py1,847lines (< 2,000),any_count: 0,dict_any_count: 0loopx/todos.py135lines,any_count: 0,dict_any_count: 0loopx/heartbeat_prompt.py168lines (<= 1,199),any_count: 0,dict_any_count: 05 files)461 insertions(+), 531 deletions(-)(-70 net lines)Verification (Exact Head
e44f9a91a7d665042a5323daf2750efea95a8b6e)examples/control_plane/control-plane-maintainability-ratchet-smoke.py:ok(unreviewed: 0,stale_exceptions: 0,magnitude_regressions: 0)+1comment counterfactual onloopx/heartbeat_prompt.py(168 -> 169lines):collect_module_metric_findings=[],diff_scoped_module_ceiling_violations=[]ruff checkon all 4 changed Python files:All checks passed!mypy --strict --follow-imports=silent loopx/control_plane/work_items/interaction_contract.py loopx/todos.py loopx/heartbeat_prompt.py(0 issues) and repopython -m mypy(0 issuesin 17 strict files vs 1 pre-existing error onorigin/main)pytestontest_maintainability_ratchet.py,test_m6_quality_gates.py,test_sqlite_archive_and_registry_health.py,test_contract_health.py,test_interaction_contract_workspace_causality.py,test_quota_settlement.py, and single-processtest_blocked_only_wait.py(1 passed) + 23 targetedtest_quota_settlement_cli.pycases (23 passed)npm run typecheck:control-plane(rc=0) and 4 Node TS interaction suites (81 passed, 0 failed)origin/mainvse44f9a91a7): identical digest86e63408a6302416e3ac46b7f7e956a029f077bfab9cb417418c36d84b328d9achange-quality verify):status=valid,receipt_id=cqr_4a8a70383c750ca804afloopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main --goal-id personal-loopx-maintenance:ok: true,merge_gate_passed: true,failures: 0loopx check --scan-path ...across all 5 changed files:errors: 0, warnings: 0