Repository navigation
Conversation
Signed-off-by: cicolord <cicolord@outlook.com>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent | Gemini | Google | self_reported
动机 / Motivation
适用对象与触发条件: 使用独立 loopx-core 安装包或 CLI 运行 generic-cli Turn 的调用方与运维方,在原 Turn 宿主进程已产出并持久化结果(待完成独立校验、待结算,或已结算需回读)但原外部宿主适配器脚本已移除或不再携带时,执行 --resume-turn-key(或解析后的 --resume-turn-instance-id)恢复回合。
修改前后场景对比: 修改前(基线 41ea75e):prepare_turn_host_arguments 与 _prepare_host_invocation 在 host == 'generic-cli' 时无条件强制要求 --host-adapter-command-json,导致即使原 Turn 已把宿主结果写入 journal 或已完成结算,只要调用方省去原适配器命令就会在参数解析/预备阶段直接失败退出,无法完成待校验结果的核验结算或已结算结果的只读回读;修改后(48d7951859):仅当恢复既有 Turn(--resume-turn-key 存在且未显式传入空 --host-command-json)时允许省略 --host-adapter-command-json 与 schema,并在读入并锁定原始 journal、由既有 assess_existing_turn_recovery 给出决策之后通过 _turn_transport_refusal 分流:已结算直接无副作用回读;待独立校验缺少 --validation-command-json 时拒止且保留原始 journal 字节;需要新一次宿主执行(reinvoke_host/needs_host)却缺少适配器时同样在任何日志修改或额度预约前拒止。
可观测收益: 在 SQLite 与 File 双后端的已构建安装版 loopx_core-2.4.0 wheel 实测中,删除原宿主适配器脚本后,--resume-turn-key 无适配器可继续完成 POSIX SIGKILL 后的独立校验与一次性提交结算、无适配器且无校验器可幂等回读已结算 Turn(all effects False);而对需要新 Host 尝试的失败回合或待校验缺少 --validation-command-json 的恢复请求,CLI 明确返回 unavailable 与所需参数提示,零副作用且 journal 字节与额度计数保持原样。
明确非目标与边界: 不放宽新建 generic-cli 回合(无 --resume-turn-key)或显式传入空字符串 --host-command-json 时的适配器要求,不绕过已有恢复状态机(assess_existing_turn_recovery / STOP_RESULT_KINDS),也不修改 codex-cli、dsh 或前端展示面。
改动思路 / Approach
如果不做这次改动,只要自主宿主脚本是临时生成或升级后路径变化,已经耗时完成外部模型产出的 generic-cli 回合在进程意外中断后就既无法继续跑独立校验、也无法仅凭 --resume-turn-key 安全回读已结算结果。与之相比,本 PR 并没有在 CLI 另造“只读回读/仅校验恢复”新命令,而是把原先过于靠前(尚未知晓 journal 处于什么恢复阶段就强制要求宿主命令)的传输检查拆分为两步:
turn run-once --host generic-cli [--resume-turn-key K]
|-- 无 --resume-turn-key,或显式传了空 --host-command-json ""
| --> prepare_turn_host_arguments() 立即报错 ValueError(守住新建回合门槛)
'-- 有 --resume-turn-key 且省略 --host-command-json
--> prepare_turn_host_arguments() 返回 raw_argv=None
--> _prepare_host_invocation(resume_existing_turn=True) 返回 (None, {})
--> run_loopx_turn_once() 加文件锁读 journal,跑 assess_existing_turn_recovery()
|-- action == "return_existing"(已结算)--> 无宿主/无校验器直接幂等回读
'-- action == "continue" --> _turn_transport_refusal()(位于 journal 写与 cadence 预约之前):
|-- needs_host 或 reinvoke_host --> 返回 unavailable,提示补传 --host-adapter-command-json
|-- resume_from == "validation" 且非 STOP 终态且缺校验器 --> 返回 unavailable,提示补传 --validation-command-json
'-- 其余合法恢复(待校验且有校验器 / 待结算)--> 原 Turn 身份继续完成校验或结算
(Illustrative source-derived control-flow diagram against 48d7951859f95469178b46cfd421b2eff192ca67; tested behaviors verified via wheel & pytest below.)
架构分工与当前边界(architecture_assessment): 复用既有 Turn 恢复决策拥有者(assess_existing_turn_recovery、STOP_RESULT_KINDS 与单通道执行门控)而非新增旁路子命令或二次恢复状态机;参数传输层仅在 --resume-turn-key 下延后‘必须提供宿主 argv’的检查,由 run_loopx_turn_once 在加锁读取既有 journal 并得出恢复决策后经 _turn_transport_refusal 做精确拒止。 职责划分清楚:prepare_turn_host_arguments 与 _prepare_host_invocation 保持纯参数标准化,assess_existing_turn_recovery 保留唯一恢复决策权,_turn_transport_refusal 仅做动作前的传输充分性检查。本 PR 严格收窄在 CLI 参数传输放行与 run_loopx_turn_once 恢复前传输校验两层:仅覆盖 generic-cli 带 --resume-turn-key(含由 --resume-turn-instance-id 在 turn.py 解析赋值的路径)的恢复/只读回读入口,同步补充 README、CLI 帮助文案、双语 RFC 段落与安装版 Core wheel 回归测试。
具体改动 / Changes
本次精确提交 48d7951859f95469178b46cfd421b2eff192ca67(base 41ea75e89892ed88d0ae543e97e31aad0a181c47)共修改 8 个文件(+121 / -20):运行时源码 4 个文件(+53 / -14)、安装指南 1 个文件(+8 / -0)、双语 RFC 2 个文件(+11 / -0)与安装版 wheel 验收测试 1 个文件(+49 / -6)。
对照规范 docs/architecture/rfcs/monorepo-distribution-split-v0.md 在改动前基线修订 41ea75e89892ed88d0ae543e97e31aad0a181c47 的逐条核对如下(PR #9051 自身亦在 Governed lifecycle and external effects 节双语补充 1 段关于已持久化 generic-cli 结果无需原适配器即可恢复校验/结算与回读的说明,属于对既有恢复规则的精确补充而非放宽既有契约):
I2(implemented):唯一内核真值与单一恢复裁决者。run_loopx_turn_once仍完全由assess_existing_turn_recovery决定当前 Turn 是否已结算、继续校验或需重跑宿主,_turn_transport_refusal不引入第二套恢复状态机;由tests/test_core_distribution.py安装版 50 项测试验证。I4(implemented):缺失必要执行依赖时显式报告不可用而非静默替代或篡改原记录。缺少必需适配器或校验器时返回status == "unavailable"及清晰参数提示;由test_installed_core_resume_without_adapter_refuses_new_host_attempt与test_installed_core_recovers_confirmed_result_after_process_loss验证。I7(implemented):缺失执行前提必须在派发或副作用前失败。_turn_transport_refusal在stage_turn_decision_capture、complete_turn_host_source与admit_start之前执行;新开回合省略--host-adapter-command-json仍在prepare_turn_host_arguments报错拒止。I8(implemented):重放与恢复严格使用原持久化身份、已批准工作区与租约代次,并由独立校验器完成门禁后一次性结算。已在 SQLite 与 File 双后端的已安装 wheel 进程中断恢复及--resume-turn-key重放全量实测通过。
关键代码讲解
prepare_turn_host_arguments(turn_host_request.py):将generic-cli的入口检查改为仅当提供了非空host_command_json时解析为raw_argv;若省略(None)则只有在“未携带--resume-turn-key”或“用户显式传了空字符串""”时才抛出ValueError("generic-cli requires --host-adapter-command-json (alias --host-command-json)")。注意turn.py#L152-L163会先将--resume-turn-instance-id解析回填至args.resume_turn_key,从而两条恢复标志自然共享此放行。_prepare_host_invocation与_turn_transport_refusal(executor.py):前者允许resume_existing_turn=True且host_argv is None返回(None, {})以便读入 journal;后者在锁内评估恢复决策后、任何写盘或额度预约之前拦截三类非法输入:需要新一次宿主调用却缺适配器;待校验非STOP_RESULT_KINDS结果却缺--validation-command-json;或携带适配器但schema不匹配。execute_turn_run_once(turn_run_once.py):向下游传入resume_existing_turn=args.host == "generic-cli" and bool(getattr(args, "resume_turn_key", None)),严格把省略宿主命令的资格绑定到显式的generic-cli回合恢复路径。
对主干的风险 / Risks
- 阻断级缺陷: 无(No blocking finding)。
- 最坏回归场景与边界约束验证: 最大潜在风险在于“新建
generic-cli回合被误放行导致运行时缺可执行命令”或“恢复一个需要重试宿主(host_result_contract失败)的 Turn 时污染原 journal/额度预约”。针对上述两类反例已直接核验:prepare_turn_host_arguments对无--resume-turn-key以及带--resume-turn-key但传--host-command-json ""均直接抛出ValueError;test_installed_core_resume_without_adapter_refuses_new_host_attempt实测证明失败宿主在无适配器下以--retry-failed-turn恢复会返回status == "unavailable",所有effects均为False,且磁盘journal字节指纹与_spends(runtime) == 0毫厘未改。 - 范围适配、兼容与隔离评估: 所有新增参数与辅助函数均有现役生产调用方(
turn_run_once.py与executor.py),无冗余分支或新增共享状态字段;未携带--resume-turn-key路径与非generic-cli主机行为保持严格基线等价;双语 RFC、包说明文档与 CLI 帮助文本同步一致。 - 本地验证与残余风险: 本地实测已完整构建隔离
loopx_core-2.4.0wheel 并跑通tests/test_core_distribution.py+tests/control_plane/test_installed_core_context.py(50 passed in 131.45s),以及 5 套 turn/CLI 源码测试(507 passed in 312.89s),加上ruff、mypy(17 文件)、check_rfc_bilingual.py、typecheck:control-plane、loopx check与canary premerge --tier quick(merge_gate_passed: true,0告警)。残余说明:_prepare_host_invocation对host_argv=None细粒度分支除了轮子端到端用例外亦经单元探针直接验证;按仓库策略未咨询远端 CI(wait_for_ci=false)。
我的整体评价 / Verdict
交付与影响判定(outcome_impact): long_horizon 与 user_experience 均判定为 improved —— 已完成外部宿主产出的中断/待校验/已结算 generic-cli Turn 在原宿主适配器已移除或路径迁移后仍可无阻塞完成校验、一次结算与幂等回读,减少长程流水线因适配器生命周期解耦造成的卡死。关于可视化界面评审(visual_review):inspected paths: loopx/cli_commands/turn_host_request.py, loopx/cli_commands/turn_registration.py, loopx/cli_commands/turn_run_once.py, loopx/control_plane/turn_driver/executor.py, packages/loopx-core/README.md — CLI/runtime 与文档变更,未涉及渲染界面。;unverified_scope: none。
语义、兼容性与代码体量结论: observable_semantics 判定为 intentional_change_validated(严格将“可省略适配器”限定于已存在 journal 恢复/回读的 generic-cli 路径并守住新回合与需重启宿主门槛);repository_reuse 为 reused;code_volume 为 necessary(兼容性保留全部现有命令行签名与恢复语义);change_proportionality 为 proportionate;default_off_isolation 为 isolated;authority_semantics 为 aligned;semantic_alignment 为 aligned(未引入新词表,沿用 STOP_RESULT_KINDS 与现有 Turn 恢复决策,双语 RFC Diff 检查与语义漂移门禁均通过)。
综上,在精确提交 48d7951859f95469178b46cfd421b2eff192ca67 上全部本地安装版与源码验证均全绿通过且无阻断问题,建议批准合入。
English Verdict: APPROVE
User outcome
A generic CLI Turn can finish from its saved result after the original adapter is removed. Recovery uses the original Turn key and approved workspace. A pending independent check still needs its validator. A settled Turn returns its recorded result. If the typed recovery decision requires a new Host attempt, the CLI asks for the adapter before changing the original journal or acquiring a new start.
This uses the existing Turn command, typed recovery decision, lease proof and settlement owners. The paired small-kernel RFCs, standalone guide and command help describe the smaller recovery input.
Local validation
48d7951859f95469178b46cfd421b2eff192ca67againstmain@41ea75e89892. A fresh Core wheel passed four focused recovery and refusal cases on File and SQLite. The same runtime previously passed 17 installed cases including terminal replay, independent validation, process loss, renewed/released leases and invalid artifacts. The baseline wheel refuses both the saved-result and terminal readback paths when the adapter is absent.Tests used real CLI processes and isolated File/SQLite state with scripted local hosts. The scope is recovery of an existing task in the selected Core host path.