Skip to content

feat(steward): add scoped PR signal monitors and chat_root report delivery - #9182

Merged
loopx-agent merged 1 commit into
mainfrom
codex/steward-scoped-monitors-report-20261121
Nov 21, 2026
Merged

loopx-agent merged 1 commit into
mainfrom
codex/steward-scoped-monitors-report-20261121

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

交付摘要 / Summary

重构 Steward Signal Monitor 的作用域门控与直接汇报投递链路,支持多个独立配置的 GitHub PR Monitor 各自内部聚合、互不串扰唤醒,并在触发后直接向绑定的 Steward 会话(App 与 Feishu chat_root)投递单篇可读汇报,替代逐 PR 创建散装 user_action 待办的轰炸模式。

关键改动 / Key Changes

  1. Control-Plane Scope Normalization & Isolated Signal Gate (loopx/control_plane/collaboration/steward_managed_mode.ts, effect_runtime_handlers.ts):
    • 新增 normalizeStewardSignalMonitorScope(steward_signal_monitor_scope_v0)与 collaboration.steward.monitor.signal_scope.normalize,支持配置 include_portfolio、include_inbox 及领域中立的 pr_filter(exclude_drafts、exclude_conflicting、effective_verdicts、required_approver_declarations、author_mode/authors、min_stalled_hours)。
    • hasMatchingApprovedReviewerDeclaration 按序重放 exact_head_reviews 并正确处理 DISMISSED 状态与多 reviewer 声明匹配。
    • observeStewardSignalMonitor 在未传入 signal_scope 时保持 100% legacy 行为与哈希不变;启用 signal_scope 时仅对作用域内信号计算 result_hash,并在 PR 跨过 min_stalled_hours 阈值时仅于达标跃迁时翻转哈希(附带 stalled_threshold_met: true 而不随采集时钟抖动)。
  2. Monitor Scope Configuration & Scoped Collection (loopx/capabilities/native_chat/steward_monitor.py, loopx/chat_action_normalization.py, loopx/chat_actions.py, loopx/chat/monitor_actions.py):
    • 支持通过 monitor.create 与 monitor.update 校验并持久化 steward-monitors/<goal_id>/scopes/<target_key>.json。
    • StewardMonitor._collect_signal_monitor 按需读取 signal_scope,在关闭 portfolio/inbox 时跳过无关本地收集,并将过滤后的 scoped_repository_items 写入轻量快照供后续跟进消费。
  3. Aggregated Owner Report Queuing & Feishu chat_root Reconciliation (loopx/capabilities/native_chat/steward_turn.py, loopx/extensions/lark/steward_reports.py, loopx/extensions/lark/private_conversations.py):
    • StewardTurnHost 新增可选 steward_owner_report(<= 24000 字符 Markdown 或 {markdown},支持静默省略/null),在 committed 后原子落盘 steward_monitor_report_delivery_v0 回执队列并直接作为 App 端 Turn 回复,同时提示聚合汇报场景不再逐 PR 产出 steward_user_actions。
    • LarkStewardReports.pending() 与 _reconcile_monitor_reports() 独立于每日周期汇报开关,校验原 Turn committed 状态与当前 binding/actor 授权,沿原始 P2P 受众以 reply_placement="chat_root"、finalize_source=False 发送一次并验证回执幂等去重。

验证范围 / Verification

  • node --experimental-strip-types --test tests/control_plane_ts/steward_managed_mode.test.ts (16/16 passed)
  • .venv/bin/python -m pytest -n 4 -q tests/test_steward_generic_monitor_todo.py tests/test_lark_steward_reports.py tests/test_native_steward_turn_host.py tests/test_chat_operation_actions.py (173 passed)
  • .venv/bin/ruff check on all changed Python files and tests
  • .venv/bin/python examples/semantic-vocabulary-drift-smoke.py --git-diff origin/main
  • .venv/bin/python -m loopx.entrypoint canary premerge --tier quick --from-git-diff --git-diff-base origin/main (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.

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

Reviewer: model_agent · Gemini · Google DeepMind · self_reported

动机 / Motivation

当受托 Steward 需要并行运行多个 PR 信号监控任务时,既有共享信号指纹门控会导致跨监控串扰与散装待办轰炸。

  • 受影响调用方:受托 Steward 运维调用方与多 Monitor 管理路径(monitor.create/monitor.update、StewardTurnHost 及 LarkStewardReports)。
  • 改进前后对比:修改前:所有 PR Monitor 共享同一包含全量 PR 与 portfolio/inbox 的结果哈希,无法按关注范围独立唤醒,PR 跨越 24 小时停滞阈值不会触发哈希变化,且异常逐条写入散装 user_action 待办或污染每日总报;修改后:每个 Monitor 按独立的 steward_signal_monitor_scope_v0 过滤仓库列表与信号源、于达标跃迁 >=24h 时单次翻转哈希,并在提交后将单篇聚合 Markdown 汇报原子入队并直达 App 与飞书私聊根会话(chat_root)。
  • 可观测交付结果:启用 signal_scope 的 Monitor 各自产出隔离的 result_hash 与 scoped_repository_items,支持领域中立的 required_approver_declarations 与 DISMISSED 重放;输出 steward_owner_report 时创建 0 条 user 待办并在飞书 chat_root 完成幂等投递。
  • 非目标边界:本 PR 不修改每日 09:00 全局 periodic_report 的既有调度/预设生成权限,也不赋予 Steward 自动合并 PR 或免评审旁路权限。

改动思路 / Approach

整体严格沿 TypeScript 控制面唯一策略所有权演进并保持默认关闭向后兼容:

  1. 在 steward_managed_mode.ts 定义 steward_signal_monitor_scope_v0 与 normalizeStewardSignalMonitorScope,支持领域中立的 required_approver_declarations(重放 exact_head_reviews 并正确剥离 DISMISSED 状态)、author_mode/authors 与 min_stalled_hours 阈值跃迁,未配置 signal_scope 时与基线逐字段同构。
  2. 在 steward_monitor.py 与 monitor.create/monitor.update(chat_action_normalization.py、chat_actions.py、chat/monitor_actions.py)持久化 scopes/<target_key>.json 并仅拉取所需维度、写入 scoped_repository_items。
  3. 在 steward_turn.py 新增可选 steward_owner_report 验证与 steward_monitor_report_delivery_v0 队列落盘;在 LarkStewardReports._reconcile_monitor_reports 独立于每日周期日报订阅开关,复用原受众 _deliver(..., reply_placement="chat_root", finalize_source=False) 实现单次幂等直达。

架构评估与边界:复用既有 monitor_todo 调度、TS 控制面信号归属权与 Lark _deliver/_original_route,不引入并行守护进程或第二套决策状态,未开启新字段时与主干基线完全一致。 当前边界:当前 PR 边界覆盖 TS 控制面作用域过滤、monitor 动作持久化、Turn 聚合汇报入队与飞书 chat_root 幂等送达;线上 4-Monitor 配置切换与历史待办清理由发布后的运维切换步骤执行。

具体改动 / Changes

  • 规格依据(spec_basis):对照仓库 TypeScript 控制面演进契约与既有 Lark 私聊出站投递边界(无单独书面 RFC 规格文件,spec_source=none),本次改动 5464acfc24e15eea3da7dc103f00b7c125c4512a 已完整落地作用域隔离哈希、min_stalled_hours 跃迁与单篇聚合直达投递。

关键代码讲解

  • normalizeStewardSignalMonitorScope(loopx/control_plane/collaboration/steward_managed_mode.ts:860):严格校验 schema_version、布尔开关与 pr_filter 字段白名单,去重小写排序规范化 required_approver_declarations 与 authors,拒绝未知字段与非正 min_stalled_hours。
  • observeStewardSignalMonitor(loopx/control_plane/collaboration/steward_managed_mode.ts:1027):signal_scope == null 时执行完全相同的旧哈希逻辑并省略 scoped_repository_items;启用作用域时仅纳入启用维度与过滤后 PR,重放 exact_head_reviews 过滤已撤销结论,并在跨过 min_stalled_hours 时仅随 stalled_threshold_met: true 跃迁翻转一次而不受采集时钟影响。
  • StewardTurnHost._normalize_steward_actions(loopx/capabilities/native_chat/steward_turn.py:1131)与落盘分支(steward_turn.py:1605):校验可选 steward_owner_report(1..24000 字符或 {markdown}),提交后原子写入 deliveries/<turn_id>.json 并直接返回聚合 Markdown。
  • LarkStewardReports._reconcile_monitor_reports(loopx/extensions/lark/steward_reports.py:105):在 reconcile() 中先于周期报告订阅判断运行,锁定单个投递文件并验证 native_loopx 提交事件、self.reports.selected(binding_id) 实时授权与不可变 original_route 后,以 chat_root 与 finalize_source=False 发送一次并凭回执去重。

对主干的风险 / Risks

  • 默认关闭隔离与兼容(default_off_isolation / observable_semantics):未配置 signal_scope 时 observeStewardSignalMonitor 输出完全不变;未返回 steward_owner_report 时现有 Monitor 照常生成 steward_user_actions 或 context_handoff。已由 observeStewardSignalMonitor null/undefined 对照测试与既有 TS/Python 套件验证通过。
  • 并发、越权与伪阳性风险(authority_semantics / failure_analysis):_reconcile_monitor_reports 强制核对 Turn 身份、实时 binding 启用状态及原 P2P 受众;finalize_reactions Skip Set 纳入 steward_monitor_report 避免错误终结原消息表情;required_approver_declarations 使用结构化 reviewer_declaration + DISMISSED 状态重放,消除硬编码厂商正则与已撤销审批误判。
  • 本地验证实况:node --experimental-strip-types --test tests/control_plane_ts/steward_managed_mode.test.ts PASS(16/16)、pytest -n 4 PASS(173/173,注:55 并发 -n auto 曾因 CPU 争抢触发 15s TS IPC 超时,降为 -n 4 后稳定全过)、架构/创建回归测试 PASS(112/112 [100%])、ruff check PASS、examples/semantic-vocabulary-drift-smoke.py --git-diff origin/main PASS、loopx check 12 文件 PASS、canary premerge --tier quick PASS(3/3,0 阻塞)。

我的整体评价 / Verdict

  • 长程与体验结论(outcome_impact):long_horizon 与 user_experience 均判定为 improved。前端未修改(visual_review 结论为 not_applicable:本 PR 仅涉 TS 控制面与后端/飞书出站投递逻辑,未改动任何渲染界面,且未遗漏范围 unverified_scope: none)。
  • 体量、兼容与语义结论:code_volume 为 necessary,change_proportionality 为 proportionate;两个新增本地 JSON 结构为局部作用域配置与投递回执(semantic_alignment: not_applicable)。exact head 5464acfc24e15eea3da7dc103f00b7c125c4512a 满足本地准入要求,未依赖远程 CI。

英文简短结论

English verdict: APPROVE at head 5464acf. Scoped signal isolation, domain-neutral exact-head declaration filtering, steward_owner_report queuing, and idempotent chat_root delivery verified locally (16 TS, 173+112 Python, ruff, loopx check, canary premerge quick PASS) with default-off parity preserved.

@loopx-agent
loopx-agent merged commit 00ef1c7 into main Nov 21, 2026
16 of 21 checks passed
@loopx-agent
loopx-agent deleted the codex/steward-scoped-monitors-report-20261121 branch November 21, 2026 08:27
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