Repository navigation
refactor(collaboration): slim conversation_binding.ts from 2,000 to 1,769 LOC - #9266
loopx-agent wants to merge 1 commit into
Conversation
Consolidate repeated recovery turn admission, cooldown backoff, failed-turn preflight, retained-work review, native anchor/segment validation, and request-error assertion patterns into local helpers while preserving all exported signatures, payload shapes, reason codes, state transitions, and verbatim prose. Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
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)
动机 / Motivation
维护控制面外部会话绑定、恢复调度与 Steward 授权逻辑的开发者,以及通过 effect_runtime_handlers.ts 和 Python conversation_bindings.py 调用这 7 个导出决策入口的上游控制面与端到端链路。
修改前:conversation_binding.ts 为 2,000 行(距离 2,000 行上限仅余 0 行),恢复计划和前置检查分支散布重复的字段存在性判断与回复封装。修改后:通过在同一文件内提炼闭集常量表和单职责局部辅助函数,文件降至 1,769 行(净减 231 行),为后续演进留出 231 行安全余量且不改变任何公开 API 或运行时行为。
wc -l loopx/control_plane/collaboration/conversation_binding.ts 降至 1,769 行(-231 LOC),control-plane-maintainability-ratchet-smoke.py、npm run typecheck:control-plane、conversation_binding.test.ts(70/70)及全套 Python 绑定测试全部通过,基线对比探测在 7 个导出函数上输出与报错完全一致。
明确非目标(Non-goals):不修改任何公开函数签名或返回值字段、不修改 loopx/canary/module_metric_baseline.json、不抽取新同级文件、也不顺带修复基线仓中无关模块(如 execution_loss_closeout_record.ts)的固定清单漂移。
改动思路 / Approach
整体重构策略聚焦于单文件内部高内聚去重与可逆性,先将散落各处的只读错误码表、回复元数据键集、命令合法集与基础空恢复对象收拢为顶层只读常量表,再为高频重复的字段合法性断言、回合窗口判定、原生分段锚点核验及恢复准入包装抽取短小单职责私有辅助函数。这样在不拆分新模块、不新增公开接口且不触碰基线例外表的前提下,显著消除了样板冗余,同时令每条分支的前置拒绝与恢复边界更加集中可读。
保留在单一控制面所有权文件 conversation_binding.ts 内,新增的局部辅助函数与闭集表格属于纯 local_helper 职责,内聚且无新边界。 当前 PR 边界:仅重构 loopx/control_plane/collaboration/conversation_binding.ts(2,000 -> 1,769 行),不新增同级文件且不改动 baseline 配置。
| 对比维度 | 基线状态 (c563a473d845) |
当前 HEAD (f905fefbe0ee) |
|---|---|---|
| 文件行数与净变化 | 2,000 行(处于基线阈值边缘) |
1,769 行(-231 净行数;+767 / -998) |
| 校验与封闭集合 | 多处散落的字面量数组和重复 if (!...) throw new EffectRuntimeRequestError(...) |
提炼 NO_RECOVERY、RESPONSE_METADATA_KEYS、RECOVERY_FAMILY_KEYS、VALID_REQUEST_COMMANDS、PENDING_ERROR_CODES 与 ensure / matchId / isNonEmptyStr / isBareSha256 等辅助函数 |
| 恢复准入与回合匹配 | planNativeQuotaRecovery、planUnfinishedWork 等各自内联失败回合、冷却窗口与只读复审判定 |
集中由 admittedRecoveryResult、cooldownNotBefore、matchesFailedTurnBase、matchesRetainedWorkReview 与 stewardAnswerWithCapacity 统一表达 |
| 外部导出与测试覆盖 | 7 个导出接口 | 7 个导出接口签名、返回结构与异常文本 100% 保持,新增文件内局部复用无额外依赖 |
说明:上方采用紧凑对比表替代额外渲染图(未执行浏览器渲染,仅基于精确 HEAD Diff 与类型/单测核对)。
具体改动 / Changes
本次仅修改生产控制面单文件 loopx/control_plane/collaboration/conversation_binding.ts(+767 / -998,净减 231 行)。规范依据说明(no_spec / 无新增或变更的功能规范):本次是对既有控制面模块做的等价去重重构以遵守仓库 2,000 行可维护性守门,不涉及新功能 RFC 或接口协议更改,所有既有契约约束均沿用原有定义。
关键代码讲解
planConversationBinding与入口绑定规划:继续承担外部对话绑定配置、授权智能体目标、撤销与断开的全部核心状态规划,并继续由loopx/control_plane/effect_runtime_handlers.ts:657唯一注册调用。重构中将重复的参数类型校验和正则模式断言收口为ensure、matchId、isNonEmptyStr与isSafeInt,保持错误消息和状态版本校验顺序完全不变。planBoundConversationRequest:作为绑定对话命令与恢复规划总入口(被effect_runtime_handlers.ts:660消费),利用封闭常量表RECIPIENT_COMMANDS、STEWARD_COMMANDS与VALID_REQUEST_COMMANDS替代重复字面量集合,命令校验失败仍精确抛出unsupported external conversation command,并在携带context_recovery时交由planContextRecovery分派。admittedRecoveryResult:新提炼的文件私有构造辅助函数,为planNativeQuotaRecovery、planWorkAfterResultReview、planRelatedResultReview与planCompletedResultReview等恢复规划分支统一构造{operation: "admit_turn", recovery_candidate: true, ...}响应载荷,消除了大量样板对象拼接,同时严格保留原有键集合与附加字段透传。matchesFailedTurnBase与matchesRetainedWorkReview:分别统一收口配额/路由/准备恢复中对失败回合基准、预留号、时间窗与错误码集合的多项校验,以及已完成结果只读复审中对未提交元数据、纯文本回答、原生分段闭合性与所有者来源的联合守门条件,在降低重复度的同时原封不动保留所有拒止条件。
对主干的风险 / Risks
无阻塞性问题(No blocking findings)。
- 生产调用与范围合理性(Scope fit & Proportionality):通过全仓检索已确认
loopx/control_plane/effect_runtime_handlers.ts:643-661与loopx/control_plane/collaboration/project_conversation.ts:5,42为全部 7 个导出符号的活跃生产调用路径,且loopx/capabilities/native_chat/conversation_bindings.py通过 Python 桥接持续调用。所有提取的常量表与函数均属于local_helper职责,未引入任何新机制、新接口、功能开关(default_off_isolation不适用)或权限模型拓展(authority_semantics不适用),相比修改 baseline 或拆文件方案风险与维护成本最低。 - 负向路径与变异敏感度:基线
c563a473d845与精确HEAD(f905fefbe0ee)运行同套 70 条原生 TS 单元测试均 70/70 全过;15 组覆盖 7 个导出接口的配对反事实对比(含 9 组正常返回及 6 组非法操作、越权发送者、不匹配智能体、异常命令、失效指令与过期 Steward 授权拒绝)返回与抛错信息逐字节一致(指纹493858c068c6feb2)。故意将VALID_REQUEST_COMMANDS中的"status"移除做变异验证时,探针立即因消息漂移(unsupported external conversation commandvsinvalid project conversation context)报错捕获,验证检验灵敏有效。 - 本地验证矩阵与无关基线归因:
npm run typecheck:control-plane(PASS,0 errors);8 文件关联 TS 控制面测试集(PASS,162 passed,0 failed);Python 必跑 4 套(PASS,215 passed)及 3 套绑定/Peer 扩展集(PASS,229 passed);scripts/check_rfc_bilingual.py、loopx check(0 errors/warnings)、CQR 验证(PASS,cqr_38e4773444484f2a0586)与loopx canary premerge(PASS,14/14 checks)均通过。44 文件 TS 匹配集(517 passed,0 failed,10 条依赖实时 PostgreSQL 服务按环境跳过)中,无关基线文件tests/control_plane_ts/content_digest_single_owner.test.ts在基线c563a473d845与精确HEAD上出现完全相同的 1 条基线失败(control_plane/quota/execution_loss_closeout_record.ts固定消费者列表缺失),而conversation_binding.ts在该测试内的自身断言通过且本 PR 未更改消费者清单,属pre_existing_unrelated,不阻断本次评审结论。远程 CI 按 Goal 配置未作等待(wait_for_ci: false)。 - 残留风险与最强待补验证(Residual risk & Strongest missing validation):残余风险为本地跳过了依赖实时 PostgreSQL 服务的 10 条通用控制面 TS 测试(虽然
conversation_binding.ts本身无直连数据库逻辑),以及上述主干无关测试content_digest_single_owner.test.ts的既有失败;最强的补充验证是在配备可用 PostgreSQL 测试实例的环境中运行完整test:postgresql-authority-store全套以补齐那 10 条环境跳过项。
我的整体评价 / Verdict
- 长程与用户体验影响:
long_horizon与user_experience均判定为preserved(保留原行为等价,所有状态机转移、恢复预算、冷却边界与错误输出未出现任何退化或额外用户交互);视觉评审visual_review因纯后端控制面模块不涉及界面展示而为not_applicable:本次修改仅涉及后台 TypeScript 控制面模块loopx/control_plane/collaboration/conversation_binding.ts的内部重构,不涉及任何前端渲染视图、页面布局或可见文案变动。(unverified_scope: none)。 - 可观测语义与代码体量:基于基线
c563a473d845与精确审查提交f905fefbe0ee的成对执行与变异验证,确认observable_semantics保持equivalent且未改动任何 Agent/用户引导文本。code_volume净减 231 行(2,000 -> 1,769),在零兼容负担下实现了实质性的结构简化,架构边界收敛(change_proportionality:proportionate),且未引入新公开语义词汇(semantic_alignment:not_applicable,仅在单文件内复用已有常量字面量)。 - 精确头部与结论:已在精确头
9266@f905fefbe0eea8e73a9279a22d8875b1bdf186e1核对全部本地实测与 CQR 回执cqr_38e4773444484f2a0586,无任何待修复阻塞项。
English verdict: APPROVE
Summary
Pure behavior-preserving net-negative-LOC refactoring of
loopx/control_plane/collaboration/conversation_binding.tsto bring it cleanly under the 2,000-line maintainability ceiling (and target<= 1,785LOC) without modifyingloopx/canary/module_metric_baseline.jsonor extracting any new sibling module.2,000LOC →1,769LOC (-231net LOC;1 file changed, 767 insertions(+), 998 deletions(-)).resolveConversationAgentTarget,planConversationBinding,resolveBoundConversation,listLocalBoundSessions,planBoundConversationRequest,stewardCommand,authorizeStewardCreation), signatures/types, return payload shapes/keys/values, reason codes, state transitions, or verbatim agent/user guidance prose.What Changed
Consolidated repeated validation guards, closed command/key sets, endpoint/turn/proof predicates, response envelope builders, and quota/cooldown helpers inside
loopx/control_plane/collaboration/conversation_binding.ts:NO_RECOVERY,RESPONSE_METADATA_KEYS,RECOVERY_FAMILY_KEYS,RECIPIENT_COMMANDS,STEWARD_COMMANDS,VALID_REQUEST_COMMANDS,PENDING_ERROR_CODES.ensure,matchId,isNonEmptyStr,isNonBlankStr,isBareSha256,isSafeInt,allUnique,hasNoFields,hasAnyField,hasConflictingRecoveryKey,fieldsMatch,isStewardEndpoint,boundChannelId.recoveryClientBase,reviewClientId,matchesReservation,matchesOriginalTurn,isFreshEpochSeconds,withinTurnWindow,validNativeAnchor,isClosedNativeSegment,matchesAttachedSession,matchesPrivateOwnerSource,matchesNativeProofBase,codexErrorDetail,provenanceThreads,admittedRecoveryResult,parseCorePreparationEvents,cooldownNotBefore,matchesFailedTurnBase,stewardAnswerWithCapacity,reviewCandidate,matchesRetainedWorkReview,isEligibleEndpointPair,isValidQuotaRecord.Verification
All checks ran locally on final commit
f905fefbe0eea8e73a9279a22d8875b1bdf186e1(or identical final file contents immediately prior to commit):npm run typecheck:control-plane: passed (0errors)8files:conversation_binding.test.ts,steward_managed_mode.test.ts,steward_pr_merge_auth.test.ts,project_conversation.test.ts,action_review_plan.test.ts,action_review_plan_session.test.ts,effect_runtime_handlers.test.ts,effect_runtime_handler_loading.test.ts):162passed,0failed,0skipped44files coveringconversation_binding,steward,collaboration,action_review_plan, excluding pre-existing unrelatedcontent_digest_single_owner.test.tsorigin/mainfailure oncontrol_plane/quota/execution_loss_closeout_record.tswhereconversation_binding.tspasses inCANONICAL_CONSUMERS):517passed,0failed,10skipped (postgresql)tests/canary/test_maintainability_ratchet.py,tests/test_chat_project_coordination.py,tests/test_chat_manager_context.py,tests/test_manager_context_roundtrip.py):215passedtests/test_chat_conversation_bindings.py,tests/control_plane/test_bound_owner_web_input.py,tests/control_plane/test_original_conversation_peer.py):229passedscripts/check_rfc_bilingual.py --base origin/main --head HEAD: passedloopx check --scan-path loopx/control_plane/collaboration/conversation_binding.ts):0errors,0warnings (5checks passed)change-quality verify):status: "valid",decision: "pass",receipt_id: "cqr_38e4773444484f2a0586"loopx canary premerge --from-git-diff --git-diff-base origin/main):ok: true(4direct checks +2catalog canaries +8risk-profile smokes =14passed,0failed)