Skip to content

refactor(lark): slim kanban presentation and extract board module - #8931

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

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

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Delivery Brief

  • Goal / Gap: loopx/extensions/lark/presentation/kanban.py was the last >2,000-line module under loopx/extensions/lark/ (2,760 lines, any_count=100, dict_any_count=0).
  • Observable Result:
    • Extracted cohesive board schema, provisioning, setup, doctor preflight, and Base payload ID helpers into loopx/extensions/lark/presentation/kanban_board.py (1,057 lines, any_count=35, dict_any_count=0), preserving compatibility re-exports (as X) and dynamic kanban lookups in kanban.py.
    • Deduplicated repeated field definitions, seed/feasibility task builders, recursive value sanitization (_transform_lark_value), sink_visibility validation (_validate_sink_visibility), base CLI argument builders (_base_cmd, _table_create_cmd, _permission_grant_cmd), payload ID traversal (_walk_first), and record upsert loops (_upsert_record_batch, _projection_upsert_items).
    • Slimmed loopx/extensions/lark/presentation/kanban.py to 1,392 lines (any_count=62, dict_any_count=0), achieving a net -312 LOC reduction across the diff (1,699 insertions, 2,011 deletions).
    • Updated only the loopx/extensions/lark/presentation/kanban.py entry in loopx/canary/module_metric_baseline.json, retiring the grandfathered "lines": 2760 exception and tightening "any_count" from 100 to 62 ("dict_any_count": 0).

Metrics & Diff Stat

  • loopx/extensions/lark/presentation/kanban.py: 1,392 lines (was 2,760), any_count=62 (was 100), dict_any_count=0
  • loopx/extensions/lark/presentation/kanban_board.py: 1,057 lines, any_count=35, dict_any_count=0
  • git diff --numstat origin/main..HEAD:
    • 2 3 loopx/canary/module_metric_baseline.json
    • 640 2008 loopx/extensions/lark/presentation/kanban.py
    • 1057 0 loopx/extensions/lark/presentation/kanban_board.py

Verification

  • uv run --extra test ruff check loopx/extensions/lark/presentation/: passed (All checks passed!)
  • uv run --extra test mypy & uv run --extra test mypy --follow-imports=silent loopx/extensions/lark/presentation/kanban.py loopx/extensions/lark/presentation/kanban_board.py: passed (Success: no issues found)
  • uv run --extra test python examples/control_plane/control-plane-maintainability-ratchet-smoke.py: passed (control-plane-maintainability-ratchet: ok, unreviewed: 0, stale_exceptions: 0, magnitude_regressions: 0)
  • uv run --extra test python -m pytest $(rg -l kanban tests/) tests/architecture/test_lark_identity_shape_owner.py tests/canary/test_maintainability_ratchet.py -q: 370 passed (after building the ignored chat bundle in the worktree via npm --prefix apps/presentation/dashboard run build:chat for cold-import retirement tests)
  • uv run --extra test python -m pytest tests/extensions/test_lark_cli_transport.py tests/extensions/test_lark_private_state_writes.py tests/extensions/test_extension_entrypoint_surface.py tests/extensions/test_extension_presentation.py tests/extensions/test_colocated_extension_layout.py tests/extensions/test_lark_goal_channel_lifecycle.py tests/extensions/test_lark_goal_channel_binding_isolation.py -q: 20 passed, 4 passed, 45 passed
  • uv run --extra test loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick --no-progress: status: passed (ok: true, merge_gate_passed: true)
  • uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD: passed
  • uv run --extra test python -m loopx.extensions.lark.provider --doctor: passed
  • Lark/Kanban smoke examples (lark-kanban-control-plane-smoke.py, lark-projection-source-reconcile-smoke.py, lark-capability-layout-smoke.py, issue-fix-outcome-projection-smoke.py, issue-fix-metrics-projection-smoke.py, lark-extension-activation-smoke.py): all passed (CLI-invoking smokes run with an isolated HOME where default and legacy host runtime roots coexist)

@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] 看板补全被拒时,部分成功会把工作视图写成字符串 None。 两版 setup 都以 ok=true, partial=true 返回。基线保存 view_id=Worker Queue,心跳返回 no_claimable_task。当前提交保存 view_id=None 字符串,心跳发出同一错误 ID 并得到 record_list_failed。 保存可用配置时仅使用有效的非空视图 ID,让缺值继续走 Worker Queue 回退。加上保留历史记录映射的部分成功和下游心跳回归。 当前实现

动机 / Motivation

重跑 Kanban setup 的看板操作者可能有一份工作视图 ID 尚未填齐的本地配置,之后继续由心跳读取看板。
已可定位 Base 和表格时,旧提交会在字段补全失败后保留 Worker Queue 回退路径。当前提交把未填的视图 ID 写成字符串 None,随后心跳读取错误视图。
提取看板 schema 和配置逻辑可以降低维护成本,同时应保证部分成功回执所承诺的看板可以继续使用。
本次交付范围是已有 Base 绑定、投影和心跳路径,新增远程授权与更改远程看板布局属于独立工作。

改动思路 / Approach

kanban_board.py 接管 Base 表单定义、预检、配置保存与补全步骤,kanban.py 保留投影、行脱敏和心跳。执行仍通过已有 CLI transport,应用配置读取只是投影目标的标识。原设计先保存可用 Base,在字段或视图补全权限不足时允许继续用现有看板。把未解析的本地值统一转换成字符串会破坏这个首次保存路径。

具体改动 / Changes

关键代码讲解

  • setup_lark_kanban_board 先探测身份和原 Base/表格,再保存一个能用的本地绑定,随后尽力补字段和视图。早期 str(value) 使已知空值成为真实视图 ID。 源码
  • _upsert_record_batch 集中调用记录 upsert,维护本地行映射,失败时按执行模式停止。已有类型与可见性继续由上游选定,写入回执仍携带行身份。 源码
  • lark_kanban_heartbeat 先用配置的工作视图读取记录,再根据现有筛选规则决定是否认领。错误的 ID 会在读取阶段阻断,未进入 worker 行为。 源码

三个文件净减 312 行,主文件降至 1,392 行。模块预算移除原行数例外,Any 上限从 100 降至 62。

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

对主干的风险 / Risks

语义与 CI 对齐

以相同可重放配置调用两版真实 CLI 的 setup、config 和 heartbeat。外部字段返回本地模拟权限拒绝,记录列表接受默认视图并返回空集。无视图映射项是健康对照,两版均回退为 Worker Queue。

重跑方法。用含 Worker Queue: null 的已有配置触发字段读回拒绝,运行 setup、回读配置并启动仅读取记录的心跳。验证回退视图和旧行映射都保留。对照没有该键的配置。 缺省未启用扩展时两版均拒绝入口且零连接器调用。权限拒绝由本地 transport 模拟,实际 CLI、配置落盘和心跳判断均执行。

155 项 schema、脱敏、私有配置和 Goal Channel 定向用例在两版均通过。Ruff、mypy、模块预算与 git diff --check 通过。原 Kanban smoke 在两版遇到相同的双 runtime root 路由错误。让合成 registry 声明其专用 runtime 后,两版 smoke 均通过。完整 premerge 与 Lark 远端访问未执行。

两版对照以 6d19ab66cf40b5483e458a20144f221a5f82cfa7 与 724de334084990e6f3092ccaca9182520dff3af0 为输入。本轮对已读回主干 e235cde9c8d1c4e673af4aefd6f304b7397bba07 的本地合并模拟通过。

我的整体评价 / Verdict

看板拆分的维护收益可以保留。缺失视图 ID 时持久化错误目标,会让已有同步任务在心跳阶段失去读取入口,且部分成功回执无法说明这个损坏。保留原视图回退即可限制修复范围,复审核对两次真实 CLI 操作和写入后的配置。

English verdict: REQUEST_CHANGES at 724de33. With a null cached worker view and failed field enrichment, setup persists a literal None view ID and the subsequent heartbeat cannot read the board. Preserve the fallback and test persisted recovery.

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/kanban-slim-20261117 branch from 724de33 to 13e16bd Compare November 18, 2026 17:54

@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: 8931@13e16bd8ad89b12907f0d9a926302014930a27f2

动机 / Motivation

受影响的是通过 setup_lark_kanban_board 初始化或迁移已有飞书看板配置、以及后续运行 lark_kanban_heartbeat 认领任务的维护者与自动化调度链路。此前在 LoopX 的飞书看板扩展中,Bitable schema 定义、新建/迁移看板流程、doctor 诊断与任务记录同步、心跳状态机全部集中于单一超大模块,超出 2,000 行可维护性阈值并使局部演进风险放大。

重构前 kanban.py 达到 2,760 行且含 100 处 Any 注解;此前 PR 提交在拆出 kanban_board.py 后因对 raw_view_ids 使用 str(v) 强转,导致已有本地配置中 view_ids["Worker Queue"] 为 null 且字段列表权限受阻发生部分成功保存时,board.view_id 被错写成字符串 "None",致使下游心跳列表请求报错 record_list_failed。修复后仅保留非空字符串视图 ID,缺失或 null 键值回退为默认 Worker Queue,心跳正常返回 no_claimable_task。这种隐式字符串化错误在部分成功路径下最容易被忽略,会直接中断后续无人值守看板心跳轮询。

kanban.py 精简至 1,392 行并通过 re-export 保持对外接口完全兼容,kanban_board.py 独立承担 1,063 行看板结构、建表配置与诊断逻辑,且部分成功路径准确保留 todo_records 映射并回退 DEFAULT_STATUS_QUEUE_VIEW。 本 PR 不修改飞书多维表格字段定义、记录同步过滤逻辑或心跳认领策略,也不处理与本次拆分无关的既有宿主双根目录环境变量或 control_plane 存量基线告警。

改动思路 / Approach

将看板字段 schema、建表 setup 与 doctor 诊断职责抽离至 kanban_board.py,由 kanban.py 保留配置读写、任务同步、心跳状态机及全部对外兼容 re-export,并在 setup_lark_kanban_board 读取 existing_board.view_ids 时严格过滤非空字符串。 本次边界严格限定于 Lark Kanban 模块瘦身拆分、setup_lark_kanban_board 空视图 ID 过滤修复、部分成功及心跳回归测试,以及 module_metric_baseline.json 指标收敛。

核心边界与控制流如下:

  1. 看板构建与诊断边界(loopx/extensions/lark/presentation/kanban_board.py):承担字段定义、视图预设、URL/Token 解析、新建与增量迁移 setup_lark_kanban_board 及 lark_kanban_doctor;在 setup_lark_kanban_board#L571-L579 对 existing_board.get("view_ids") 进行类型与非空校验(仅当键、值均为 str 且 .strip() 非空时纳入 view_ids),保证当远端 +field-list 等增强步骤被拒绝返回 partial=True 时,save_usable_config() 仍通过 view_ids.get(DEFAULT_STATUS_QUEUE_VIEW) or DEFAULT_STATUS_QUEUE_VIEW 回退为 "Worker Queue",而不产生字符串 "None" 污染本地配置。
  2. 运行时同步与单点持久化边界(loopx/extensions/lark/presentation/kanban.py):在 L37-L83 完整 re-export 所有看板符号,并在 save_lark_kanban_board_config#L534-L589 原子保存 "board" 与历史 "todo_records" 映射;下游 lark_kanban_heartbeat 通过 lark_kanban_config_from_payload 读取 board.view_id,从而发出正确的 --view "Worker Queue"。
setup_lark_kanban_board (HEAD: 8931@13e16bd8ad89b12907f0d9a926302014930a27f2)
  ├─ 已有配置: view_ids={"Worker Queue": None, "Kanban": "vew_kanban_fixture"} + todo_records
  ├─ 旧代码: {str(k): str(v)} -> view_id="None" -> heartbeat +record-list -> record_list_failed
  └─ 新代码: 过滤仅保留非空字符串 -> view_id="Worker Queue" -> heartbeat 正常返回 no_claimable_task

(上述流程示意基于当前精确提交源码控制流整理,真实执行证据见下方测试与 Canary 验证。)

具体改动 / Changes

  • 模块拆分与缺陷修复:
    • loopx/extensions/lark/presentation/kanban_board.py(1,063 行):独立承载看板 schema、创建/setup/doctor 等逻辑;第 571–579 行修复 raw_view_ids 对 None 等非字符串/空值的错误字符串强转。
    • loopx/extensions/lark/presentation/kanban.py(净缩减至 1,392 行):第 37–83 行保留全部已有对外/测试重导出签名,save_lark_kanban_board_config 与心跳、同步主链路保持单点行为等价。
  • 回归测试与基线指标:
    • tests/extensions/test_lark_kanban_schema_preflight.py(第 361–462 行,+104 行):新增 test_partial_setup_ignores_null_view_id_and_preserves_records_and_heartbeat_fallback,覆盖含 "Worker Queue": None 与历史 todo_records 在 +field-list 权限失败时的部分成功保存与下游 lark_kanban_heartbeat 联调行为。
    • loopx/canary/module_metric_baseline.json(第 146–149 行):将 kanban.py 的 any_count 上限从 100 下调至 62,并移除已低于 2,000 行上限(实测 1,392 行)的 lines: 2760 豁免。

关键代码讲解

  1. loopx/extensions/lark/presentation/kanban_board.py#L571-L579 (setup_lark_kanban_board):遍历 raw_view_ids 时强制校验 isinstance(k, str) and k.strip() and isinstance(v, str) and v.strip() 并执行 .strip(),直接剔除 None 及空白值,确保 "Worker Queue" 缺省时后续 view_ids.get(DEFAULT_STATUS_QUEUE_VIEW) or DEFAULT_STATUS_QUEUE_VIEW 稳定回退为 "Worker Queue"。
  2. loopx/extensions/lark/presentation/kanban.py#L534-L589 (save_lark_kanban_board_config):合并既有 board 配置与已过滤 view_ids,同时保留历史 todo_records 映射并以私有文件原子写入持久化。
  3. loopx/extensions/lark/presentation/kanban.py#L592-L606 (lark_kanban_config_from_payload) 与心跳消费端:从持久化 board.view_id 构造 LarkKanbanConfig,供 lark_kanban_heartbeat 发起 --view 列表查询;配合回归测试共同守住“部分成功写入不应破坏下游心跳读回”的端到端不变量。

本次拆分与 Bug 修复无独立前置书面 RFC(no_spec);行内评审 [P2] 所指出的空视图 ID 字符串化漏洞及历史记录保留验证已全部在当前提交 8931@13e16bd8ad89b12907f0d9a926302014930a27f2 落地并通过实测。

对主干的风险 / Risks

  • 验证矩阵与实测结果(exact head 8931@13e16bd8ad89b12907f0d9a926302014930a27f2):
    • pytest 5 个相关测试集:PASS(379 passed in 15.62s,涵盖 test_lark_kanban_schema_preflight.py 新增回归、共享脱敏、Goal Channel、内容摘要单点与顶层模块预算)。
    • 端到端冒烟:examples/lark-kanban-control-plane-smoke.py(在隔离 HOME 单运行根环境下执行,避免本机双默认运行根冲突)PASS(lark-kanban-control-plane-smoke: ok)。
    • 静态检查与边界:ruff check 3 个变更 Python 文件 PASS;npm run typecheck:control-plane 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(隔离 HOME 且挂载只读 node_modules 清理陷阱)PASS(ok: true, merge_gate_passed: true, failure_count: 0;1 项 control_plane 存量函数复杂度 advisory 属于主干已有问题,与本 PR 无关)。
  • 负向路径与限制:当本地已有 view_ids 全为空且 +field-list 失败触发 partial=True 时,系统依然可以保存可用最小配置并安全退出而不丢弃 todo_records,心跳未发现待办返回 decision="no_claimable_task" 而不产生写副作用;飞书 lark-cli 远端调用在回归测试中通过可注入 runner 校验精确命令行参数,真实线上租户未实网写入。改动全部隔离在 Lark Kanban 扩展目录,可单个 squash revert 安全回滚。

我的整体评价 / Verdict

将看板字段 schema、建表 setup 与 doctor 诊断职责抽离至 kanban_board.py,由 kanban.py 保留配置读写、任务同步、心跳状态机及全部对外兼容 re-export,并在 setup_lark_kanban_board 读取 existing_board.view_ids 时严格过滤非空字符串。 本次边界严格限定于 Lark Kanban 模块瘦身拆分、setup_lark_kanban_board 空视图 ID 过滤修复、部分成功及心跳回归测试,以及 module_metric_baseline.json 指标收敛。本 PR 成功将 kanban.py 降至 1,392 行并清理 38 处 Any 注解(100 -> 62),兼容重导出保持完整;同时精准根治了 raw_view_ids 把 null 强转为 "None" 字符串的隐蔽问题,并通过串联部分成功与心跳读回的回归测试闭环验证。远端 CI 在当前 Goal 策略下不咨询(ci_policy: not_consulted),精确头 commits 本地全量测试与 Canary 门禁均已通过,对主干维护性与运行期稳定性均为正向收益,建议合入。

English Verdict: APPROVE

@loopx-agent
loopx-agent merged commit 41ea75e into main Nov 18, 2026
7 of 11 checks passed
@loopx-agent
loopx-agent deleted the codex/kanban-slim-20261117 branch November 18, 2026 17:56
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