From e1d2f0421516cecade81d16dbabbac03e3c587fc Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 28 Oct 2026 03:01:41 +0800 Subject: [PATCH] docs(controller): define intelligent mediation and full-cycle tradeoffs Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- docs/architecture/rfcs/STATUS.md | 2 +- docs/architecture/rfcs/STATUS.zh-CN.md | 2 +- ...controller-executor-unified-contract-v0.md | 65 ++++++++++++++++++- ...ller-executor-unified-contract-v0.zh-CN.md | 47 +++++++++++++- .../rfcs/loopx-overall-roadmap-v0.md | 6 ++ .../rfcs/loopx-overall-roadmap-v0.zh-CN.md | 5 ++ 6 files changed, 123 insertions(+), 4 deletions(-) diff --git a/docs/architecture/rfcs/STATUS.md b/docs/architecture/rfcs/STATUS.md index 76b8757020..67a340c3ce 100644 --- a/docs/architecture/rfcs/STATUS.md +++ b/docs/architecture/rfcs/STATUS.md @@ -68,7 +68,7 @@ appendix may keep dated history, but no dated log heading may precede it. | [RFC: Shared Goal Alignment and Governed Amendment Protocol (v0)](shared-goal-alignment-and-governed-amendment-v0.md) | Accepted | none | [2 entries](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC: LoopX Shared Control-Plane Authority and Pluggable State Providers (v0)](shared-goal-authority-state-provider-v0.md) | Accepted | none | [24 entries](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | Accepted | none | — | -| [RFC: TypeScript Control-Plane Migration Direction v0](typescript-control-plane-migration-v0.md) | Accepted | none | [16 entries](ledger/typescript-control-plane-migration-v0/) | +| [RFC: TypeScript Control-Plane Migration Direction v0](typescript-control-plane-migration-v0.md) | Accepted | none | [18 entries](ledger/typescript-control-plane-migration-v0/) | ## Superseded (1) diff --git a/docs/architecture/rfcs/STATUS.zh-CN.md b/docs/architecture/rfcs/STATUS.zh-CN.md index 5686b66d77..7059783a1e 100644 --- a/docs/architecture/rfcs/STATUS.zh-CN.md +++ b/docs/architecture/rfcs/STATUS.zh-CN.md @@ -65,7 +65,7 @@ | [RFC：共享 Goal 对齐与受治理 Amendment 协议（v0）](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md) | 已接受 | 无 | [2 条](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC：LoopX 共享控制面权威与可插拔状态 Provider（v0）](shared-goal-authority-state-provider-v0.zh-CN.md) | 已接受 | 无 | [24 条](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | 已接受 | none | — | -| [RFC：LoopX 控制面 TypeScript 渐进迁移方向 v0](typescript-control-plane-migration-v0.zh-CN.md) | 已接受 | 无 | [16 条](ledger/typescript-control-plane-migration-v0/) | +| [RFC：LoopX 控制面 TypeScript 渐进迁移方向 v0](typescript-control-plane-migration-v0.zh-CN.md) | 已接受 | 无 | [18 条](ledger/typescript-control-plane-migration-v0/) | ## 已被替代 (1) diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md index 871e2e7230..83e3dc2b11 100644 --- a/docs/architecture/rfcs/controller-executor-unified-contract-v0.md +++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0.md @@ -31,7 +31,8 @@ evidence belongs in a dated ledger when an implementation first produces it. against the original quota-packet path. Existing domain owners still decide their own facts. 2. In the optional two-session profile, the **controller model session is the - sole model-facing Core client**. It reads the contract, reasons about work, + sole model-facing Core client and an intelligent mediator of control work**. + It reads the contract, reasons about work, talks to the executor and submits explicit typed Core operations. Core owns legal transitions and receipts; the controller is not a second authority. 3. The executor receives a natural-language task conversation, original source @@ -204,6 +205,56 @@ and recovery derive from the saved instance without another guard. A legitimate new selection or authority check may produce a new capture; it must not rewrite an earlier observation or silently rebind an outstanding result. +### Controller intelligence and semantic compression + +The controller session itself supplies intelligence. Its architectural role is +to turn the control plane's complete facts and obligations into useful work for +the executor, and interpret the executor's findings back into justified Core +operations. “Intelligent compressor” describes this mediation of control work; +fewer queries or shorter text alone do not implement it. The existing summary +already assigns reading, reasoning and typed operations to the controller. The +additional design choice here is **where decisions and attention are spent**: + +| Decision | Controller responsibility | Retained boundary | +| --- | --- | --- | +| What to do next | Compare the current Goal gap, evidence, viable work and complete costs; continue a useful route or change it when warranted | Core still decides legal admission, claims, leases, budgets and transitions; controller judgment grants no authority | +| What to delegate together | Choose a coherent, verifiable task and decide which control concerns to absorb itself | The executor keeps local tool/step choice within scope; it does not request approval for each tool call or author Core bookkeeping | +| What the executor must know | Deliver the task's full constraints, relevant contrary evidence, original materials and unresolved reads; explain the decision in task language | A summary is not an alternate contract or proof of source reading. Unknown relevance requires more material before dependent work | +| What a result changes | Distinguish a finding, verified artifact, blocked attempt and accepted outcome; decide whether to continue, investigate or replan | Independent validation and current Core receipts, rather than either session's narrative, determine acceptance and settlement | + +Keep three operations separate. The deterministic composition owner combines +domain facts without inventing policy; the existing codec encodes an exactly +recoverable full/delta input; the controller performs task-dependent semantic +selection and reasoning. A natural-language task can omit irrelevant control +syntax and cannot promise bit-for-bit equivalence. Its adequacy is tested by +preserved constraints, actual executor decisions and accepted outcomes, with +the original authorized material reachable. Do not replace these operations +with a second schema, model-authored state store or keyword-based relevance +classifier. Controller notes are working context, not a new durable authority. + +For example, after an export repair produces a valid artifact but a packaging +check fails, the controller can keep the useful repair, delegate the evidenced +packaging correction and retain the original unsettled identity. It must not +reduce the result to “done”, discard the failed check or ask the executor to +learn writeback syntax. If the same evidence shows that the repair violates a +shared requirement, it must revise the task and deliver that requirement before +dependent work. This is a decision consequence, not a target compression ratio. + +Amortization is a hypothesis. A controller can absorb several control-heavy +interactions while an executor continues ordinary authorized work, but every +new selection, permission change, cancellation and closeout still follows its +existing owner and freshness rules. Do not add a Core round trip or a new Turn +for each local tool step; do not cache an old permission to avoid a required +check. Small tasks, rapidly changing shared constraints and frequent controller +recovery can make the extra session cost more than it saves. + +Controller failure must not make the executor a fallback Core client. Pause +dependent dispatch, recover the original capture and session/attempt records, +read current authority where required, and reconcile any already admitted +result through the original identity. An executor summary cannot reconstruct +missing control obligations. Conflicting or inaccessible required material +holds dependent work; independent authorized work keeps its existing route. + ### Review freshness and recovery A complete capture proves what was observed; it does not freeze write-time @@ -617,6 +668,7 @@ by this document alone. | Lossless context delivery | Full/delta/recovery equivalence, missing/late/truncated pages, role/session mismatch and real native compaction/resume | Include all read/recovery costs; no second admission or spend | | Role isolation and recovery | Controller/executor crash windows, duplicate dispatch, late result, revision change, lease expiry and stop under actual host tools | No executor Core access; no stale result adoption or hidden business executor | | Semantic adoption | Original requirements → controller decision → actual executor work → independent verification → accepted result and original-audience return | Read receipt, valid JSON or successful replan alone cannot pass | +| Intelligent mediation | Coherent delegation, changed/contrary evidence and result interpretation across ordinary continuation, shared-constraint change, controller loss and a small-task counterexample | Explain the actual decision consequence and retained obligations; fewer queries or a shorter handoff cannot pass | | Shared production paths | Real CLI and supported File/SQLite paths; real isolated PostgreSQL suite when authority persistence changes; packaged App heartbeat and benchmark worker reuse | No live Goal corruption; unsupported/unrun hosts stay unqualified | | Outcome and cost benefit | Matched current single-session, unified single-session and unified two-session arms with fixed task/model/policy/budget/evaluator | Report uncertainty, failures and counterexamples; no claim from prompt bytes alone | @@ -694,6 +746,17 @@ cost when an artifact is forwarded. Compare accepted outcomes under comparable budgets, not only replan counts or executor speed. Freeze criteria before any separately authorized experiment; this RFC specifies no automatic winner. +For the later two-session comparison, attribute controller reasoning and all +handoff/material, validation and recovery costs as well as executor work. The +break-even question is whether those **added complete costs** are outweighed by +avoided control/bookkeeping work, repeated execution or human intervention, +while preserving comparable accepted outcomes. Account for actual repeated +model consumption even when both sessions read the same artifact; forwarding +one usage receipt must not double-count that receipt. Report workload-specific +tradeoffs and unknown billing/cache coverage. No universal overhead threshold, +compression ratio or per-message token ceiling is proposed. This comparison +does not replace the prior original-quota versus unified single-session gate. + ## 10. Operational contract Existing Goal Chat, settings and work readback must expose the selected profile, diff --git a/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md b/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md index ab60844ec9..cdd29e96da 100644 --- a/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md +++ b/docs/architecture/rfcs/controller-executor-unified-contract-v0.zh-CN.md @@ -25,7 +25,8 @@ 长期保留 quota/Turn 兼容视图不是目标。吸收 quota packet 的必要信息量优势与 TurnEnvelope 的交付效率优势，一起替换二者，并相对原 quota packet 路径验收净变化。 各 domain owner 仍决定自己拥有的事实。 -2. 在可选的双会话 profile 中，**controller 模型会话是唯一面向 Core 的模型客户端**。 +2. 在可选的双会话 profile 中，**controller 模型会话是唯一面向 Core 的模型客户端， + 也是控制工作的智能中介**。 它读契约、判断工作、与 executor 沟通并提交显式 typed Core 操作。Core 拥有合法迁移与 回执；controller 不是第二个权威。 3. Executor 接收自然语言任务对话、原始材料和普通宿主工具，返回发现、产物、证据与问题。 @@ -168,6 +169,42 @@ digest 保护传输，canonical hash 保护语义内容，既有 effect 身份 不再执行 guard。合法的新选择或权限复核可以产生新 capture，但不能改写旧观察，或把 未结算结果悄悄绑定到新观察。 +### Controller 的智能与语义压缩 + +智能来自 controller 会话本身。它在架构上把控制面的完整事实与义务转化成 executor +可执行的有用工作，再把 executor 的发现解释为有依据的 Core 操作。“智能压缩器”描述 +的是对控制工作的这种中介作用；少查几次或缩短文本本身不能实现它。既有摘要已把阅读、 +推理与 typed 操作交给 controller，这里补充的设计决定是**把判断与注意力放在哪里**： + +| 判断 | Controller 的职责 | 保留的边界 | +| --- | --- | --- | +| 下一步做什么 | 比较当前 Goal 缺口、证据、可行工作与完整成本；有依据地继续或换路 | 合法准入、claim、lease、预算和迁移仍由 Core 决定；controller 的判断不授予权限 | +| 哪些工作一起交接 | 选择连贯、可验证的任务，决定自己吸收哪些控制事务 | Executor 在范围内自主选择局部工具与步骤，不逐次请示，也不编写 Core 记账 | +| Executor 必须知道什么 | 交付任务完整约束、相关反证、原始材料和未完成必读，用任务语言解释判断 | 摘要不是另一份契约，也不证明读过来源；相关性未知时，依赖工作前须补足材料 | +| 结果改变什么 | 区分发现、已验证产物、受阻尝试与已接受成果，判断继续、调查或 replan | 独立验证与当前 Core 回执决定验收和结算，不能由任一会话的叙述替代 | + +区分三种操作：确定性的 composition owner 组合 domain 事实，不另造 policy；既有 +codec 编码可精确恢复的 full/delta 输入；controller 按任务进行语义选择和推理。自然 +语言任务可以省去无关控制语法，不能承诺逐字节等价。其充分性要由约束保留、executor +实际决策与验收成果检验，同时原始获授权材料仍可到达。不能用第二套 schema、模型编写的 +状态库或按关键词判断相关性的分类器替代这些操作。Controller 笔记是工作上下文，不是 +新的持久权威。 + +例如导出修复已产出有效文件，但打包检查失败：controller 可以保留有用修复，交接有 +证据的打包纠正，并保留原未结算身份。它不能把结果缩成“完成”、丢掉失败检查，或要求 +executor 学习 writeback 格式。如果同一证据表明修复违反共同要求，则先修改任务并交付 +该要求，再继续依赖工作。这是实际判断后果，不是压缩比例目标。 + +成本摊薄仍是假设。Executor 继续普通获授权工作时，controller 可以吸收多次控制密集 +交互，但每次新选择、权限变化、取消与收尾仍遵循既有 owner 和新鲜度规则。不要为每个 +局部工具步骤增加一次 Core 往返或新 Turn，也不能缓存旧权限来跳过必需复核。小任务、 +快速变化的共同约束和频繁 controller 恢复，都可能让额外会话的成本超过节省。 + +Controller 失败不能让 executor 变成备用 Core 客户端。暂停依赖的 dispatch，恢复原 +capture 与 session/attempt 记录，在必要处读取当前权限，并按原身份对账已准入结果。 +Executor 摘要不能重建缺失的控制义务。必需材料矛盾或不可达时，依赖工作保持阻塞； +独立获授权工作继续沿原路径推进。 + ### 评审新鲜度与恢复 完整 capture 证明当时观察到了什么，不会冻结写回时的有效性。语义内容身份、评审 @@ -466,6 +503,7 @@ reader。本文不单独授权破坏性迁移。 | 无损上下文交付 | Full/delta/recovery 等价；缺页、迟到、截断、role/session 不符与真实原生压缩/续接 | 合计所有读取/恢复成本，不重新准入/扣额 | | 角色隔离与恢复 | 实际 host tools 下的 controller/executor 崩溃窗口、重复 dispatch、迟到结果、revision 变化、lease 到期、Stop | Executor 不能访问 Core，不能采用过时结果或隐藏第二个业务 executor | | 语义采用 | 原始要求 → controller 判断 → executor 实际工作 → 独立验证 → 接受结果并回原受众 | 读回执、合法 JSON 或 replan 成功不能单独通过 | +| 智能中介 | 普通继续、共同约束变化、controller 丢失和小任务反例中的连贯交接、变化／反向证据及结果解释 | 说明真实判断后果与保留义务；少查询或短交接均不足 | | 共享生产路径 | 真实 CLI 与受支持 File/SQLite；涉及 authority 持久化变更时跑真实隔离 PostgreSQL；打包 App heartbeat 与 benchmark worker 复用 | 不破坏 live Goal；未支持/未运行 host 仍未合格 | | 成果与成本收益 | 当前单会话、统一契约单会话、统一契约双会话三组，固定 task/model/policy/budget/evaluator | 报告不确定性、失败与反例，不从 prompt bytes 单独宣称收益 | @@ -525,6 +563,13 @@ serializer 或字节减少结清。 产物时不重复计算成本。比较可比预算下的已接受成果，不能只看 replan 次数或 executor 速度。另行授权实验前冻结标准，本文不预设胜出方案。 +在后续双会话对照中，除 executor 工作，还要归因 controller 推理及全部交接／材料、 +验证与恢复成本。收支平衡问题是：在保留可比验收成果时，这些**新增完整成本**能否被 +避免的控制／记账、重复执行或人工介入所抵消。即使两会话读同一产物，也按实际重复 +模型消费计量；转发同一用量回执不能把该回执重复计费。报告不同 workload 的取舍和 +账单／缓存覆盖未知。本文不规定通用开销阈值、压缩比例或每条消息 token 上限；此对照 +不替代前置的原 quota 与统一单会话验收。 + ## 10. 运行契约 既有 Goal Chat、settings 与工作 readback 应呈现选定 profile、controller/executor diff --git a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md index 585e9ce933..423fc6b6f3 100644 --- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md +++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md @@ -190,6 +190,12 @@ recovery and settlement. Session roles, execution modes, wake sources and benchmark arms remain separate axes. This is design direction, not shipped behavior or evidence of lower cost. +The controller session's [intelligent mediation](controller-executor-unified-contract-v0.md#controller-intelligence-and-semantic-compression) +concentrates task choice, necessary material and result interpretation in that +session. Deterministic composition and exact delta encoding retain their own +owners. Qualify retained obligations and subsequent accepted work against the +controller's added complete costs; query counts or text size cannot pass it. + C1's [caller cutover map](controller-executor-unified-contract-v0.md#c1-caller-replacement-and-cutover-unit) includes quota emission, the direct Turn producer and the final native/structured host prompts. A common capture does not unify those consumers. Qualification diff --git a/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md b/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md index d6660acb88..4c640f6009 100644 --- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md +++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md @@ -145,6 +145,11 @@ S2/S4/S6/S7/S11：用一份受治理工作 schema 替代 quota/Turn packet 格 和材料；身份、权限、恢复、结算仍归既有 host/Core owner。Session role、执行模式、 唤醒来源和 benchmark 评估组保持正交。这是设计方向，不是已交付行为或成本收益证据。 +Controller 会话的[智能中介作用](controller-executor-unified-contract-v0.zh-CN.md#controller-的智能与语义压缩) +把任务选择、必要材料和结果解释集中到该会话；确定性 composition 与精确 delta 编码 +仍归各自 owner。以保留义务及后续验收成果，对照 controller 新增完整成本验收，不能 +用查询次数或文本体积代替。 + C1 的[消费链切换表](controller-executor-unified-contract-v0.zh-CN.md#c1-消费链替换与切换单元) 覆盖 quota emission、直接生产契约的 Turn 入口和最终 native/structured host prompt。 共享 capture 不表示这些消费者已统一。资格检查须追踪来源义务经过组合、重建到实际