Skip to content

refactor(lark): slim explore_results below 1,350 lines and extract explore_visual_sink - #8925

Merged
loopx-agent merged 2 commits into
mainfrom
codex/explore-results-slim-20261117
Nov 18, 2026
Merged

loopx-agent merged 2 commits into
mainfrom
codex/explore-results-slim-20261117

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Slim loopx/extensions/lark/presentation/explore_results.py from 2,391 to 1,313 lines (any_count: 78 -> 45, dict_any_count: 0) with a net -188 LOC reduction (+1,092 / -1,280 across 3 files), and retire the lines: 2458 baseline ceiling in loopx/canary/module_metric_baseline.json.

Key Changes & Deduplications

  1. Cohesive Visual-Sink Separation (loopx/extensions/lark/presentation/explore_visual_sink.py, 891 lines, any_count: 41, dict_any_count: 0)

    • Moved whiteboard sink configuration, display-value / rendered-span redaction, and single/dual-view whiteboard sync (configure_lark_explore_visual_sink, sync_explore_visual_to_lark, sync_explore_visuals_to_lark, explore_visual_semantic_digest, _visual_delivery_digests, and redaction helpers) into explore_visual_sink.py.
    • Retained explicit as re-exports in explore_results.py plus _explore_results.run_command / config lookup indirection so callers and existing test monkeypatches (explore_results.run_command) remain 100% compatible without circular imports.
    • Kept sink_visibility single-owner discipline (from .sink_visibility import ..., zero inline pair literals).
    • Deduplicated:
      • Derived AUTO_DOC_CREATE_XML from AUTO_DOC_TITLE + AUTO_DOC_APPEND_XML.
      • Shared editable_local_explore_config across explore_visual_sink.py and explore_results.py instead of 4 inline key-stripping comprehensions.
      • Extracted _build_visual_sink_entry to replace duplicate 16-key visual-sink dict construction in configure_lark_explore_visual_sink.
      • Unified docs +create / docs +update command dispatch and overview extraction in configure_lark_explore_visual_sink.
      • Extracted _visual_result for early/status returns in sync_explore_visual_to_lark and _publish_target in sync_explore_visuals_to_lark to share stage/overview publish + host-timeout deferral + in-place readback target registration.
  2. Bitable Row-Sync & Material-Sync Deduplication (loopx/extensions/lark/presentation/explore_results.py)

    • Extracted _row_result_key and _scan_explore_goal_records to eliminate the duplicated ~50-line paginated base +record-list loop shared by the initial pre-upsert scan and post-write readback scan inside sync_explore_results_to_lark (preserving exact per-scan failure handling and warnings).
    • Extracted _sync_packet inside sync_issue_fix_explore_on_material_change to share baseline response fields across all 7 status outcomes (not_applicable, not_configured/invalid_config, source_projection_regression_blocked, unchanged, would_sync, external_sink_suppressed, synced/sync_failed).
  3. Ratchet Baseline Retirement (loopx/canary/module_metric_baseline.json)

    • Removed "lines": 2458 from loopx/extensions/lark/presentation/explore_results.py and tightened "any_count" from 78 to 45 ("dict_any_count": 0).

Verification

All checks run on commit be3849e298 (clean worktree over origin/main 68fe178851):

  • uv run --extra test ruff check loopx/extensions/lark/presentation/explore_results.py loopx/extensions/lark/presentation/explore_visual_sink.py: passed
  • uv run --extra test mypy: Success: no issues found in 17 source files
  • uv run --extra test python -m pytest tests/test_explore_presentation_views.py tests/extensions/test_lark_shared_sink_redaction.py tests/extensions/test_lark_private_state_writes.py tests/capabilities/test_explore_machine_defaults.py tests/capabilities/test_explore_research_evidence.py tests/capabilities/test_research_composition_gate.py tests/cli_commands/test_project_lifecycle_explore_graph.py tests/control_plane/test_refresh_checkpoint_isolation.py tests/architecture/test_lark_sink_visibility_owner.py tests/architecture/test_control_plane_import_boundaries.py -q: 229 passed
  • uv run --extra test python -m pytest tests/canary/test_maintainability_ratchet.py -q: 14 passed
  • uv run --extra test python examples/control_plane/control-plane-maintainability-ratchet-smoke.py: passed
  • uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD: passed

@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, max)

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

[P2] 更换白板目标后,Kanban 把待同步的可视化标为未变。 基线 needs_visual_sync=true,当前提交 false,而两者均为 would_sync。Kanban 当前提交显示 visual_status=unchanged。授权抑制分支也返回 false。 构造回执时读取预览后的 needs_visual_sync。持平、受限未写入和正常发布各沿用自己的标志值。添加源摘要相同、目标不同的回归,核对回执和 Kanban 的投影。 当前实现

动机 / Motivation

更换 Explore 白板目标后,操作者通过 Kanban 同步预览确认要更新哪些结果。
同一份探索结果换到新白板时,旧提交会明确报告还需要同步可视化。当前提交仍计划同步,却把可视化标为已是最新。
提取白板发布逻辑应缩小 Explore 同步模块的维护范围,并保留读回结果和实际交付计划的一致性。
本次交付覆盖现有表格和白板同步路径,新增可视化视图和改变 LoopX 的授权流程各有独立边界。

改动思路 / Approach

Issue-fix 账本先生成 Explore 投影,Lark 配置决定目标白板。表格写入依据行读回摘要,白板依据渲染和目标的投递摘要。explore_visual_sink.py 集中处理配置、脱敏、绘图以及远端标记的读回,explore_results.py 仍负责原材料变化的同步判断。复用两个摘要的做法合理,回执字段需要从最终决定生成。

具体改动 / Changes

关键代码讲解

  • sync_issue_fix_explore_on_material_change 沿真实 issue-fix 投影运行,预览后决定要同步哪些界面并把结果传给 CLI。当前 _sync_packet 的参数默认值保留了较早的状态。 源码
  • sync_explore_visuals_to_lark 提取后的角色视图发布按 canonical/executive 分发,继续依据远端读回标记确认送达,并在耗尽宿主等待预算后停止后续写入。 源码
  • _scan_explore_goal_records 合并写前和写后记录扫描。以 Goal、数据表、记录结果 ID 匹配远端行,重复行保留第一条,空页与读取失败交由各阶段生成对应诊断。 源码

三个文件净减 188 行,主文件降至 1,313 行。模块预算移除原行数例外,Any 上限从 78 降至 45。

验收依据为基线 68fe1788518e7edbf912638dcc421e17b0c9bc31 的 docs/development/testing-and-quality.md。“真实路径等价”在上面的 P2 场景未满足。“回归敏感性”已有同输入对照,基线符合预期,当前提交失败。 真实路径要求

对主干的风险 / Risks

语义与 CI 对齐

不可变输入在两个源码提交中通过实际 issue-fix 账本、Lark Explore 本地配置和真正的白板预览生成。仅换目标 token,源摘要相同,投递摘要改变。would_sync 和 external_sink_suppressed 均在本地验证,实际 CLI 读回使用同一配置。

重跑方法。先用已稳定的 Explore 图保存源、行读回和白板投递摘要,然后只改 canonical overview token,再跑预览、无外部发布授权及 lark-kanban sync-loopx-todos 路径。旧目标作为对照。 缺省未启用扩展时两版拒绝入口且零连接器调用。受限发布路径同样零连接器调用。本轮覆盖的是持久化配置与状态读回。

120 项定向用例在基线和当前提交均通过,原 issue-fix Explore smoke 两边通过。该 smoke 已覆盖渲染投递变化后的发布,却没有断言此回执字段。Ruff、mypy、模块预算与 git diff --check 已通过。完整 premerge、实际 Lark 服务端和远端画板渲染未验证。

两版对照以 68fe1788518e7edbf912638dcc421e17b0c9bc31 与 be3849e29852846c76e459a638d54117532cf527 为输入。本轮对已读回主干 e235cde9c8d1c4e673af4aefd6f304b7397bba07 的本地合并模拟通过。

我的整体评价 / Verdict

白板与行同步可以继续沿用现有模块职责。错误标志会让有待重投的画板在自动和人工读回中显示已是最新,导致操作者跳过必要的同步。修复可留在回执构造边界,用相同源摘要和更换目标的对照复审。

本轮使用实际 CLI 与白板预览生成器核对状态,实际远端文档和整屏画板仍待核验。 真实远端文档、画板的页面渲染和读回。

English verdict: REQUEST_CHANGES at be3849e. After an overview target changes with the same source digest, the returned visual-sync flag is stale. Build the receipt from the final preview decision and test the Kanban readback.

…plore_visual_sink

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
@loopx-agent
loopx-agent force-pushed the codex/explore-results-slim-20261117 branch from be3849e to c8d97ea Compare November 18, 2026 17:41

@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 | Gemini | Google | self_reported
Reviewed Exact Head: 8925@c8d97eafe2b68b92489c1f43892373b2a579ab4c

动机 / Motivation

受影响的是调用自动同步与看板 CLI 的维护者及运行时同步流程(通过 sync_issue_fix_explore_on_material_change 与 loopx lark-kanban sync-loopx-todos 管理飞书结果板与白板视图)。此前在 LoopX 的飞书探索结果板呈现层中,Bitable 行同步、单飞并发控制、自动投影判定与白板可视化汇配置、脱敏和发布全部耦合在同一个大文件内,导致模块超出 2,000 行可维护性预算并增加增量修改风险。

重构前 explore_results.py 膨胀至 2,458 行且含 78 处 Any 注解;拆出可视化汇后,此前提交因 _sync_packet 在定义阶段提前冻结默认值 needs_visual_sync=False,导致仅更换白板目标而 Bitable 行摘要不变时,preview 阶段与受限未写入分支误报 needs_visual_sync=False、看板状态误显示 unchanged。修复后,无论干跑预览、未授权抑制还是正式发布,回执与看板均如实透传 needs_visual_sync=True。该故障会让操作者误以为白板交付已是最新状态,从而漏掉已经变更的目标白板推送,影响视觉看板对最新探索结论的呈现。

explore_results.py 精简至 1,313 行并保持已有重导出兼容,explore_visual_sink.py 独立承担 891 行白板配置与发布逻辑,且白板目标变更在直接调用和 Kanban CLI 下均稳定触发增量可视化同步而不误写表格行。 本 PR 不修改飞书 Bitable 字段 schema、Mermaid/SVG 渲染协议或扩展权限模型,也不处理与本次拆分无关的主干 control_plane 可维护性基线存量告警。

改动思路 / Approach

将飞书白板配置、脱敏与阶段画板发布抽离至 explore_visual_sink.py,同时由 explore_results.py 保留 Bitable 行/摘要持久化单点所有权及兼容重导出,并在视觉预览后通过 None 默认参数动态读取 needs_visual_sync。 本次边界严格限定于 Lark Explore 呈现扩展模块化拆分、_sync_packet 动态状态修复、对应回归测试及 module_metric_baseline.json 指标收敛,不引入新持久化字段或新权限范围。

具体机制分工如下:

  1. 可视化汇提供方 IO 边界(loopx/extensions/lark/presentation/explore_visual_sink.py):集中封装 configure_lark_explore_visual_sink、展示文本与坐标脱敏 helper、单画板及双视角阶段白板协调发布函数 sync_explore_visuals_to_lark,以及交付摘要提取函数 _visual_delivery_digests;内部通过延迟导入 .explore_results 读写配置,避免模块导入期循环依赖。
  2. 核心策略与状态回执边界(loopx/extensions/lark/presentation/explore_results.py):负责计算探索结果源语义摘要 semantic_digest 并比对历史行数摘要(needs_row_sync),再通过 sync_explore_visuals_to_lark(..., execute=False) 预览对比 prior_visual_delivery_digests 与 expected_visual_delivery_digests,将 needs_visual_sync 更新为真实需求。此前内嵌辅助函数 _sync_packet 使用闭包默认参数 vis_sync: bool = needs_visual_sync,导致 Python 在函数定义瞬间将默认值固定为预览前的 False。现改为 vis_sync: bool | None = None,在返回字典时按 needs_visual_sync if vis_sync is None else vis_sync 动态读取闭包当前状态(对显式传入的布尔值如 unchanged 路径的 vis_sync=False 仍按显式值返回)。
sync_issue_fix_explore_on_material_change (HEAD: 8925@c8d97eafe2b68b92489c1f43892373b2a579ab4c)
  ├─ 步骤 1: 计算行摘要 -> needs_row_sync = False, 初始 needs_visual_sync = False
  ├─ 步骤 2: 预览 visual_sinks -> 目标变更,重算 needs_visual_sync = True
  ├─ 旧实现: _sync_packet(vis_sync=needs_visual_sync [def 冻结 False]) -> 错报 False / unchanged
  └─ 新实现: _sync_packet(vis_sync=None) -> 返回期动态求值 needs_visual_sync -> 正确透传 True

(上述流程图基于当前精确提交源码逻辑整理,作为机制说明,不替代下方实测执行证据。)

具体改动 / Changes

  • 生产代码与兼容导出:
    • loopx/extensions/lark/presentation/explore_visual_sink.py(+891 行):承接白板配置、双视角 Mermaid/SVG 阶段发布及安全脱敏逻辑。
    • loopx/extensions/lark/presentation/explore_results.py(净缩减至 1,313 行):第 66–84 行保留全量兼容重导出别名,第 1032–1059 行修复 _sync_packet 默认值捕获问题。
  • 回归测试与基线指标:
    • tests/test_explore_presentation_views.py(第 2039–2309 行,+273 行):新增 test_sync_issue_fix_explore_reports_visual_sync_when_whiteboard_target_changes_and_rows_unchanged,完整验证行不变而更换 overview_whiteboard_token 时的 unchanged、would_sync、external_sink_suppressed、synced 及真实 loopx lark-kanban sync-loopx-todos CLI 输出(并确认行同步计数不重复递增)。
    • loopx/canary/module_metric_baseline.json(第 142–145 行):将 explore_results.py 的 any_count 上限从 78 下调至 45,并移除已低于 2,000 行阈值(实测 1,313 行)的 lines: 2458 豁免。

关键代码讲解

  1. loopx/extensions/lark/presentation/explore_results.py#L1032-L1059 (_sync_packet):将 needs、row_sync、vis_sync 默认值统一设为 None,组装返回字典时仅当形参为 None 才读取当前 needs_sync / needs_row_sync / needs_visual_sync,消除 Python 默认参数定义期早绑定问题。
  2. loopx/extensions/lark/presentation/explore_results.py#L1090-L1136 (sync_issue_fix_explore_on_material_change):先通过 sync_explore_visuals_to_lark(..., execute=False) 获取预期交付摘要并更新 needs_visual_sync = True,随后 would_sync 与 external_sink_suppressed 分支可直接透传准确的视觉待同步标记。
  3. loopx/extensions/lark/presentation/explore_visual_sink.py#L634-L860 (sync_explore_visuals_to_lark) 与 #L864-L891 (_visual_delivery_digests):聚合角色视角交付摘要供上层增量化比对使用,隔离飞书渲染与阶段文档协调细节。

本变更属于无独立前置书面 RFC 的模块瘦身重构与行内缺陷修复(no_spec);对基线行为等价性与行内 [P2] 修复诉求已在精确头提交 8925@c8d97eafe2b68b92489c1f43892373b2a579ab4c 上全部落实并经本地测试与 Canary 门禁验证。

对主干的风险 / Risks

  • 验证矩阵与实测结论(exact head 8925@c8d97eafe2b68b92489c1f43892373b2a579ab4c):
    • pytest 相关 6 个测试集(含新回归测试):PASS(375 passed, 2 skipped in 18.62s;2 项跳过为既有环境共享脱敏条件用例,新增回归测试 1 passed in 1.11s)。
    • 冒烟脚本:examples/issue-fix-explore-projection-smoke.py PASS(ok);examples/lark-explore-source-runtime-route-smoke.py PASS(ok)。
    • 静态检查与边界:ruff check 3 变更文件 PASS;npm run typecheck:control-plane(临时只读挂载 node_modules 并在退出清理)PASS;严格配置 mypy PASS(17 source files clean);隔离 HOME 下 loopx check --scan-path ... PASS(errors: 0, public_boundary_scan.ok: true)。
    • Premerge Canary:loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick PASS(ok: true, merge_gate_passed: true, failure_count: 0;另有 1 项与本 PR 无关的 control_plane 既有函数复杂度 advisory 提示,已归因至主干基线)。
  • 负向路径与未覆盖范围:未配置 explore_graph 或摘要未变路径保持默认关闭与无副作用(not_applicable / unchanged);测试替身仅隔离飞书远端 Bitable/白板 HTTP 子进程及扩展激活查询,真实线上租户 API 端到端未在单元测试内实网调用,回滚可通过标准 git revert 原子完成。

我的整体评价 / Verdict

将飞书白板配置、脱敏与阶段画板发布抽离至 explore_visual_sink.py,同时由 explore_results.py 保留 Bitable 行/摘要持久化单点所有权及兼容重导出,并在视觉预览后通过 None 默认参数动态读取 needs_visual_sync。 本次边界严格限定于 Lark Explore 呈现扩展模块化拆分、_sync_packet 动态状态修复、对应回归测试及 module_metric_baseline.json 指标收敛,不引入新持久化字段或新权限范围。本 PR 不仅高标准完成了 explore_results.py 降至 1,313 行与 33 处 Any 清理的目标,还捕捉并彻底修复了 _sync_packet 早绑定造成的视觉同步状态丢失缺陷,并以端到端 CLI 与直调双覆盖测试固证回归边界。远端 CI 在当前配置下不作为准入条件(ci_policy: not_consulted),当前精确头本地实测全部通过,对主干长程可维护性与用户体验均属正向改进,结论为批准合入。

English Verdict: APPROVE

@loopx-agent
loopx-agent merged commit 4ac1fc1 into main Nov 18, 2026
7 of 11 checks passed
@loopx-agent
loopx-agent deleted the codex/explore-results-slim-20261117 branch November 18, 2026 17:49
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