Skip to content

refactor(lark,history): slim goal_topic_runtime and history and zero out Any - #8953

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/lark-history-any-slim-20261118
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/lark-history-any-slim-20261118

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Delivery Brief

  • Goal / Source: Slim large runtime modules (loopx/extensions/lark/goal_topic_runtime.py and loopx/history.py), eliminate all Any annotations, ratchet loopx/canary/module_metric_baseline.json strictly downward, and remove the unused F401 import in tests/control_plane/test_contract_health.py.
  • Gap: goal_topic_runtime.py sat directly at the 2,000-line ceiling (MODULE_LINE_LIMIT) with 56 Any annotations (10 dict[..., Any]), history.py had 1,152 lines and 42 Any annotations (41 dict[..., Any]), module_metric_baseline.json carried 56 / 51 Any without line-count pins on either module, and tests/control_plane/test_contract_health.py had an unused display_report_text import.
  • Observable Result:
    • loopx/extensions/lark/goal_topic_runtime.py: 2000 -> 1617 lines (-383), any_count: 56 -> 0, dict_any_count: 10 -> 0. Replaced Any with object, covariant Mapping/Sequence, dict[str, object], _StreamProcess Protocol, ProviderRunner, ChatRuntimeController, and small payload/error helpers (_as_mapping, _as_dict, _str_field, _int_field, _str_list, _dict_list, _iter_enabled_bindings, _event_consume_args, _empty_poll_result, _topic_error, _persist_delivery), while fixing MESSAGE_ID_PATTERN import from .identity_shapes and trimming duplicated dispatch/lock boilerplate.
    • loopx/history.py: 1152 -> 1035 lines (-117), any_count: 42 -> 0, dict_any_count: 41 -> 0. Replaced Any and cast with concrete Mapping/Sequence/dict[str, object]/object annotations (covariant Mapping on read-only parameters) and consolidated shared index/report helpers (_as_dict, _as_mapping, _mapping_list, _int_field, _normalized_activation, _goal_index_paths, _index_command_payload, _group_index_lines, _markdown_report_lines, reusing index_identity).
    • loopx/control_plane/runtime/runtime_projection_route.py: updated _route_projection_is_current to bind marker = row.get(marker_field) before isinstance(marker, dict) so mypy narrows cleanly with typed load_index returns.
    • loopx/canary/module_metric_baseline.json & tests/canary/test_maintainability_ratchet.py: pinned both modules strictly downward (any_count: 0, dict_any_count: 0, lines: 1617 and 1035); moved the unpinned-line assertion in test_maintainability_ratchet.py from goal_topic_runtime.py to loopx/canary/planner.py.
    • tests/control_plane/test_contract_health.py: removed unused from loopx.paths import display_report_text (F401).
    • Net diff in loopx/: 4 files changed, 894 insertions(+), 1390 deletions(-) (-496 net lines), 0 new top-level loopx/*.py modules (124 unchanged).

Verification

  • uv run --extra test ruff check loopx/extensions/lark/goal_topic_runtime.py loopx/history.py loopx/control_plane/runtime/runtime_projection_route.py tests/control_plane/test_contract_health.py tests/canary/test_maintainability_ratchet.py: passed (All checks passed!).
  • uv run --extra test mypy: passed (Success: no issues found in 17 source files).
  • uv run --extra test mypy --follow-imports=silent loopx/extensions/lark/goal_topic_runtime.py loopx/history.py: passed (Success: no issues found in 2 source files).
  • uv run --extra test loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick: passed (merge_gate_passed: true, 3/3 catalog canaries passed).
  • uv run --extra test pytest -n 4 -q --tb=short tests/extensions/test_lark_goal_topic_runtime.py: 101 passed in 12.70s.
  • uv run --extra test pytest -n 8 -q -rs tests/canary/: 114 passed, 6 skipped in 10.84s (all 6 skips are filesystem non-UTF-8 / root-name skips in tests/canary/test_git_path_display.py).
  • Targeted caller suites (tests/canary/, tests/architecture/test_top_level_module_budget.py, tests/architecture/test_lark_event_prefix_owner.py, tests/control_plane/test_contract_health.py, tests/control_plane/test_status_history_reuse.py, tests/test_history_*.py, tests/extensions/test_lark_topic_inbox_config.py, tests/extensions/test_lark_goal_topic_connections.py, tests/extensions/test_lark_manager_returns.py, tests/extensions/test_lark_private_manager_returns.py, tests/extensions/test_lark_private_steward_triage.py, tests/extensions/test_lark_reply_handoff.py, tests/extensions/test_lark_event_timing.py, tests/extensions/test_lark_direct_group_dispatch.py, tests/test_lark_private_compatibility.py, tests/test_lark_private_ingress.py, tests/test_lark_delivery_wakeup.py, tests/test_chat_lark_api_contract.py): 550 passed, 6 skipped.
  • tests/extensions/test_lark_topic_inbox_config.py + tests/test_lark_private_compatibility.py + tests/test_lark_private_ingress.py + tests/test_lark_delivery_wakeup.py: 94 passed.
  • Broader Lark / history / control-plane runs observed pre-existing origin/main-identical failures unrelated to this PR:
    • tests/extensions/test_lark_realtime_dispatch.py (test_profile_without_steerable_binding_keeps_four_ordinary_workers excluded because it loops while self._workers is unpopulated; test_idle_handler_failure_reconnects_through_the_existing_service_owner fails pre-existing).
    • tests/test_native_steward_turn_host.py::test_managed_work_never_commits_without_current_independent_postcondition[stopped_after_model], tests/presentation/test_background_services_api.py::test_http_recheck_starts_existing_owners_once_and_preserves_disabled_features, tests/control_plane/test_bound_owner_web_input.py::test_http_binding_discovery_preserves_duplicate_observations_for_the_typed_owner[file|sqlite], tests/test_lark_source_authority_reply.py::test_successful_preflight_cannot_authorize_a_send_after_authority_changes[app|revoke] (verified failing identically on origin/main), and 8 Goal activation metadata requires upgrade failures in tests/test_zcode_goal_bridge.py (runtime_projection_route + history run had 637 passed, 6 skipped).

…out Any

Eliminate all Any annotations and trim boilerplate in loopx/extensions/lark/goal_topic_runtime.py (2000 -> 1617 lines, 56 -> 0 Any) and loopx/history.py (1152 -> 1035 lines, 42 -> 0 Any), fix downstream dict narrowing in runtime_projection_route.py, ratchet module_metric_baseline.json strictly downward, and remove unused F401 import in tests/control_plane/test_contract_health.py.

Signed-off-by: LoopX Agent <[email protected]>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Reviewer: model_agent | model: Gemini | provider: Google | declaration_source: self_reported (reviewer_execution unavailable)

动机 / Motivation

此前受影响的对象与触发场景是:维护代码库静态健康与类型收敛的开发者、Lark 话题运行时及历史索引的调用方,以及 Ruff/Mypy/可维护性棘轮检查门禁。。之所以必须在当前推进,是因为改动前,loopx/extensions/lark/goal_topic_runtime.py 恰好停留在 2000 行的模块上限(MODULE_LINE_LIMIT)且包含 56 处 Any 注解,loopx/history.py 有 1152 行和 42 处 Any,每次修改都可能触及行数上限并缺乏严格静态约束,同时 tests/control_plane/test_contract_health.py 第 10 行残留了未使用的 display_report_text 导入触发 Ruff F401;改动后,goal_topic_runtime.py 缩减至 1617 行且 Any 清零,history.py 缩减至 1035 行且 Any 清零,基线严格向下锁定且 F401 消除。如果不加治理,后续围绕 Lark 话题实时分发或 JSONL 历史记录的任何小幅改动都会继续撞线或放大弱类型透传风险。本 PR 的实际可观测收益清晰可控:goal_topic_runtime.py(2000 -> 1617 行,Any 56 -> 0)与 history.py(1152 -> 1035 行,Any 42 -> 0)在 loopx/ 内合计净减少 496 行,module_metric_baseline.json 严格向下锁定两项指标,下游 runtime_projection_route.py 字典缩窄与 test_contract_health.py 未使用导入一并修复,且 ruff、mypy、canary premerge 与相关回归用例保持通过。。同时明确边界如下:本 PR 不更改对外 CLI/HTTP 协议字段与持久化格式,不新增顶层 loopx/*.py 模块,不重写 TypeScript 控制面,也不顺带修复 origin/main 上既有的无关测试失败。

改动思路 / Approach

整体思路是“先收敛外部边界与内部核心数据结构类型,再合并重复包装和分发样板,最后向下更新基线并修补暴露出的下游类型缩窄问题”。在设计权衡上,所有改动均严格收敛在既有运行时与历史索引所有者内部(local_helper 与 invariant),通过协变 Mapping/Sequence、本地强类型转换辅助与下游显式局部绑定完成零 Any 收敛和样板精简,未引入新顶层模块或跨层新策略。本 PR 边界限定为 goal_topic_runtime.py 与 history.py 的全量去 Any 精简、由此暴露的 runtime_projection_route.py 类型缩窄修复、module_metric_baseline.json 向下锁定(含匹配棘轮单测例示文件调整)以及 test_contract_health.py 的 F401 未使用导入清理。

从调用链路与数据分层来看,外部事件与 JSON 索引记录进入 stream_lark_goal_topic_profile、answer_lark_goal_topic、_process_lark_goal_topic_event 或 load_index 后,统一在模块内边界由 _as_mapping、_as_dict、_str_field、_int_field、_dict_list 与 index_identity 完成结构校验与类型窄化,不改动权限判定、消息确认(ACK)、持久化 JSONL 格式与失败重试契约;对于只读输入参数采用协变 Mapping[str, object] 与 Sequence[...],避免调用方传入 dict[str, str] 触发类型不变性冲突,对外或需就地修改的数据结构则保留明确的 dict[str, object]。当 load_index 返回值从隐式 Any 收敛为 tuple[list[dict[str, object]], int] 后,mypy 立即暴露出 loopx/control_plane/runtime/runtime_projection_route.py 中 _route_projection_is_current 对 row[marker_field] 的不安全嵌套读取,因此在原地改用局部绑定 marker = row.get(marker_field) 完成对齐。

具体改动 / Changes

本 PR 属于静态类型收敛、代码体积精简与棘轮基线清理,仓库中不存在针对此次重构的独立书面规格(spec_basis = no_spec),以现有可维护性棘轮、mypy 严格检查与运行期回归用例作为等价约束依据。

  • 运行期精简与去 Any:loopx/extensions/lark/goal_topic_runtime.py(2000 -> 1617 行,any_count: 56 -> 0,dict_any_count: 10 -> 0)、loopx/history.py(1152 -> 1035 行,any_count: 42 -> 0,dict_any_count: 41 -> 0),以及下游类型缩窄修复 loopx/control_plane/runtime/runtime_projection_route.py。
  • 基线锁定与静态检查修复:loopx/canary/module_metric_baseline.json(严格向下锁定上述两模块,并保留键值防止落入宽松默认上限)、tests/canary/test_maintainability_ratchet.py(将第 49 行仍无 lines 键的示例路径从 goal_topic_runtime.py 改为 loopx/canary/planner.py)与 tests/control_plane/test_contract_health.py(删除第 10 行未使用的 display_report_text 导入消除 F401)。

关键代码讲解

  1. loopx/extensions/lark/goal_topic_runtime.py#L154-L220 — _as_mapping / _as_dict / _str_field / _int_field / _str_list / _dict_list / _event_consume_args / _topic_error:把原先分散在流式消费、问答与事件处理里的重复 isinstance(..., dict) 转换、event consume 命令参数拼接与错误字典构造集中为小粒度纯类型适配辅助,消除了全部 56 处 Any 注解与冗余分支,同时改为复用 .identity_shapes 中的 MESSAGE_ID_PATTERN。
  2. loopx/extensions/lark/goal_topic_runtime.py#L1235-L1295 — _process_lark_goal_topic_event:规范化 Lark 话题事件并驱动 ingest_lark_event_inbox、manager_context_projection、回复发送与消息确认。签名替换为协变 Mapping[str, object] 与精确函数协议(CommandRunner / ProposalDeliverer)后,完整保留 direct_session 与 async_inbox 分支、无匹配路由忽略与管理员权限模式校验逻辑。
  3. loopx/history.py#L473-L525 — load_index / latest_status_run / collect_history:将原先基于 dict[str, Any] 与 cast(...) 的索引读写接口全部转为 tuple[list[dict[str, object]], int] 与只读 Mapping[str, object],并整合 _goal_index_paths、_index_command_payload、_group_index_lines、_markdown_report_lines 及现有 index_identity,清除 42 处 Any 并保持统计过滤与解码容错一致。
  4. loopx/control_plane/runtime/runtime_projection_route.py#L468-L492 — _route_projection_is_current:因 load_index 返回元素收敛为 dict[str, object],改用显式循环将 marker = row.get(marker_field) 绑定到局部变量后再执行 isinstance(marker, dict) 校验(同时规避了 mypy 1.20.2 在生成器表达式中使用海象运算符触发的内部错误),判定语义保持不变。

对主干的风险 / Risks

经完整核对当前提交 484c83552d83d7a175f28352d1a059430910968f 的修改边界与下游引用,本 PR 没有发现阻塞合并的缺陷(no blocking finding),风险主要集中在以下三方面且已有明确边界控制:

  • 静态签名与调用方兼容边界:将只读字典输入收紧为 Mapping[str, object]、将部分返回容器标注为 dict[str, object] 后,若未纳入仓库默认 17 个 mypy 文件的其他分支或外部脚本直接假设返回值字段为隐式 Any 子类型,可能在类型检查时报错;但在运行期所有对象仍为原生 dict/list,且全部 monkeypatch 扩展点(_inbox_config、_active_profile_configs、LarkGoalTopicRuntimeService、_indexed_artifact_exists、_chronology_key)与默认 17 文件 mypy 均保持完全兼容。
  • 验证覆盖与既有失败归因:在当前审查提交 484c83552d83d7a175f28352d1a059430910968f 上,ruff check 全通过,默认 17 文件 mypy 与两个目标模块 mypy --follow-imports=silent 零错误,loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick 通过(3/3 catalog canaries),tests/extensions/test_lark_goal_topic_runtime.py 101 项全过(12.70s),tests/canary/ 114 通过、6 项因 macOS 文件系统限制非 UTF-8/保留名跳过,核心历史/架构/Lark 用例集 550 通过(6 skipped)与 94 通过。扩大回归中遇到的若干失败(test_lark_realtime_dispatch.py、test_native_steward_turn_host.py、test_background_services_api.py、test_bound_owner_web_input.py、test_lark_source_authority_reply.py、test_zcode_goal_bridge.py)已在未修改的 origin/main(ef099ae3ac3c08054b9d928fff48aefe2615b950)上交叉验证或核对堆栈,确认均属主干既有失败或激活元数据升级校验,非本 PR 引入。
  • 剩余风险与最强未覆盖检查:提交审阅时远端 GitHub Actions(如完整 kernel-static-checks 与 postgresql-authority (real server))仍在队列/运行中;本地未连接真实远端 Feishu 通道或独立 PostgreSQL 实例,不过本次改动不涉及 PostgreSQL 存储层或线上网络协议。

我的整体评价 / Verdict

综合长程演进与用户体验影响(outcome_impact.long_horizon = improved、user_experience = preserved、visual_review = not_applicable,不涉及渲染界面),本 PR 以净删减 496 行 loopx/ 代码的方式清零了两个核心模块共计 98 处 Any 注解,使 goal_topic_runtime.py 从 2000 行安全回落至 1617 行、history.py 从 1152 行回落至 1035 行,并完成下游 mypy 窄化修复、基线棘轮向下锁定(未新增任何顶层模块,维持 124)及 test_contract_health.py F401 清理。各验证维度均在精确头 484c83552d83d7a175f28352d1a059430910968f 上实证通过,无阻塞发现(no blocking finding);远端 CI 仍需合并前例行放行。

English verdict: APPROVE — Cleanly eliminates all 98 Any annotations across goal_topic_runtime.py (2000 -> 1617 lines) and history.py (1152 -> 1035 lines) with a net 496-line reduction in loopx/, ratchets module_metric_baseline.json strictly downward, resolves downstream narrowing in runtime_projection_route.py and F401 in test_contract_health.py, and passes ruff, mypy, canary premerge, and targeted test suites without regressions.

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, xhigh)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

APPROVE。已核对正常入口、失败分支及持久化读回。 真实轮询入口加合成飞书适配器,同批外部会话拒绝、正确 Topic 写一次并读回一次、同消息重放已确认。三棵树的实际收发计数及顺序一致。

动机 / Motivation

经已绑定飞书 Topic 读取、回复并确认消息的用户,以及用 CLI 查看或修复本地历史索引的维护者。 Topic 路由及回复各自验证作用域和读回,历史诊断与修复对重复行和原反馈有明确处理。 候选抽出共享字段读取、事件命令和投递回执落盘逻辑,归并索引分组及渲染。Lark 和历史共减少 500 行,清除这两个模块的显式 Any。 真实本地历史索引和 Topic runtime,飞书身份、投递和读回由隔离适配器模拟。实际飞书连接、安装和托管 CI 未验证。 后续发布需用真实飞书渠道验收当前恢复行为。

改动思路 / Approach

Topic 继续使用已绑定的目标、原 reply transport 和 effect/ACK 权威。历史继续使用 run index 与已有锁,修复和重建保持现有审阅与写入边界。 将重复操作收敛到原 Topic 和索引 owner,保持发送前权限复核、确认前读取,以及锁内写入原边界。 主要决策路径为 loopx/extensions/lark/goal_topic_runtime.py。评审依据为 docs/development/testing-and-quality.md(ef099ae3ac3c08054b9d928fff48aefe2615b950)。固定依据

具体改动 / Changes

精确头 484c83552d83d7a175f28352d1a059430910968f,merge base ef099ae3ac3c08054b9d928fff48aefe2615b950,与主干 b97818e5149661f2feda934dc7bdb7a20ae60e07 干净整合。全量差异 6 个文件,新增 895 行、删除 1392 行。

  • Topic 投递兼容。真实轮询入口加合成飞书适配器,同批外部会话拒绝、正确 Topic 写一次并读回一次、同消息重放已确认。三棵树的实际收发计数及顺序一致。
  • 索引与反馈保留。同一真实 history CLI 与合成索引同时含坏行、完整重复和反馈覆盖。三棵树在诊断、只读预览、实际修复、第二次无改动、反馈和 Markdown 内容一致。JSON 键顺序变化。
  • 回归敏感性。实际历史修复只删除一个逐字重复记录,保留坏行、原反馈和两条历史运行。模拟遗漏反馈覆盖时,独立诊断由一组变成零组。畸形旧注册表在三个版本均返回同一明确失败。

关键代码讲解

  • poll_lark_goal_topic_profile_once。把实际收件流交给原有回复并读回确认。 源码
  • _process_lark_goal_topic_event。沿已有 receipt 顺序恢复和去重。 源码
  • _group_index_lines。保留原物理行号和索引 identity。 源码
  • repair_index_duplicates。同一索引锁内删除可安全删除的行,保留反馈。 源码
  • _route_projection_is_current。继续要求同一源时间和两种制品均可读回。 源码

对主干的风险 / Risks

状态与索引变更均先走原属主。修复操作在临时本地注册表和真实索引上演练。飞书路由、拒绝与重复回放使用合成 provider 响应。 定向 Topic 选测覆盖并发单次回答、回复补送、部分消息读回、非授权效果和重试。相同 7 项定向用例和 14 项运行时路由用例在基线、精确头和整合各通过。基线、精确头及与当时主干的整合树,较广测试集各 418 项通过。 精确头和所测主干整合均通过标准 premerge。各 6 项直接检查和 18 项选中检查无阻塞失败。Ruff 与声明范围的 mypy 通过。 实际历史修复只删除一个逐字重复记录,保留坏行、原反馈和两条历史运行。模拟遗漏反馈覆盖时,独立诊断由一组变成零组。畸形旧注册表在三个版本均返回同一明确失败。 本地故障注入使诊断从 1 个反馈覆盖组变成 0 组。

我的整体评价 / Verdict

APPROVE。 后续发布需用真实飞书渠道验收当前恢复行为。 真实本地历史索引和 Topic runtime,飞书身份、投递和读回由隔离适配器模拟。实际飞书连接、安装和托管 CI 未验证。

English verdict: APPROVE at 484c835. Local Topic routing, rejection and delivery replay match the base. The real history CLI preserves index diagnostics, reward overlays and repeat-safe repair. Live Feishu adoption remains unverified.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant