From 5ff05c1af4ef97840dd342095cfbe755eb7a607d Mon Sep 17 00:00:00 2001 From: huangrt01 Date: Sun, 9 Aug 2026 06:13:06 +0800 Subject: [PATCH] docs(rfc): mark q3 complete and update quota course reading paths --- .../rfcs/agent-loop-effect-interpreter-v0.md | 11 +++++++---- .../control-plane-course/03-first-real-loop.md | 13 +++++++++---- .../06-quota-decision-kernel.md | 16 ++++++++++------ .../07-host-scheduler-and-heartbeat.md | 2 +- .../10-autonomous-agent-quality-gates.md | 3 ++- .../topic-long-horizon-convergence.md | 2 +- 6 files changed, 30 insertions(+), 17 deletions(-) diff --git a/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md b/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md index ad578d221..91add1e6e 100644 --- a/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md +++ b/docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md @@ -48,7 +48,7 @@ that model over time. | M3 Focused test families | Mostly complete (#2916-#2918, #2925, #2929) | | M4 Architecture documentation | Mostly complete (#2921, #2923, #2924) | | M5 Steady-state review | Mostly complete (#2922, #2931) | -| M6 General effect-program abstraction | In progress; quality gate pending (#2938-#2959) | +| M6 General effect-program abstraction | In progress; Q3 complete (#2963-#2965), Q4 in progress; quality gate pending (#2938-#2959) | ## Why This Matters @@ -314,7 +314,7 @@ replacements. It is not yet a qualitative change. M6 must not be called mostly complete until all of the following are true: 1. Hot modules shrink to bounded sizes: - - `loopx/quota.py` below 2000 lines; + - `loopx/quota.py` below 2000 lines (currently 1043); - `loopx/status.py` below 2000 lines; - `loopx/heartbeat_prompt.py` below 1200 lines. 2. `loopx quota should-run` builds through a bounded `should_run` decision @@ -334,9 +334,12 @@ Phases: - Q2: Characterize hot modules and capture parity fixtures for `quota.py`, `status.py`, and `heartbeat_prompt.py`. - Q3: Extract the quota `should-run` decision and packet builder into - `loopx/control_plane/quota/should_run.py`. + bounded modules. Done: `should_run.py` entry decision (#2963), + `should_run_prepare.py` preparation chain (#2964), and + `should_run_packet.py` route/packet assembly (#2965). - Q4: Extract status read models, collection, and presentation into bounded - modules. + modules. In progress; course/RFC reading paths updated to the new quota + bounded modules. - Q5: Extract heartbeat prompt builders into bounded modules. - Q6: Make CLI quota, turn driver, and bootstrap construction consume `EffectTurn` / `EffectProgram`. diff --git a/docs/development/control-plane-course/03-first-real-loop.md b/docs/development/control-plane-course/03-first-real-loop.md index 4aea4c9d2..67bfdc627 100644 --- a/docs/development/control-plane-course/03-first-real-loop.md +++ b/docs/development/control-plane-course/03-first-real-loop.md @@ -401,9 +401,12 @@ loopx --format json quota should-run \ 2. `loopx/cli_commands/starter_bootstrap.py` 3. `loopx/bootstrap_command_pack.py` 4. `loopx/heartbeat_prompt.py` -5. `loopx/quota.py::build_quota_should_run` +5. `loopx/control_plane/quota/should_run.py::build_quota_should_run` -不要从头通读 `quota.py`。先搜索 `build_quota_should_run`，再沿它调用的 bounded-context helper 向下读。 +不要从头通读旧的 `loopx.quota` facade。真实决策在 +`loopx/control_plane/quota/should_run.py`、`should_run_prepare.py` 与 +`should_run_packet.py`。先搜索 `build_quota_should_run`，再沿 bounded-context +helper 向下读。 ### 步骤 D：带着调用链读核心代码 @@ -563,7 +566,9 @@ effective_action = _effective_action(...) 按这个顺序领读：先确定 goal boundary，再选 work lane，再检查能力与 workspace，最后让 projection repair 覆盖普通 delivery。`should_run=True` 只说明“本轮有必须尝试的合法动作”，动作可能是 repair，并不总是产品交付。 -建议断点：`quota.py:1300`、`:1351`、`:1404`、`:1442`、`:1461`。每次只记录 `effective_action`、四个 `*_allowed` 与 guard 的 `reason`。 +建议断点：`should_run_prepare.py` 的 preparation 阶段，以及 +`should_run_packet.py` 的 route/build 阶段。每次只记录 `effective_action`、 +四个 `*_allowed` 与 guard 的 `reason`。 #### 读完这一段应能回答 @@ -601,7 +606,7 @@ effective_action = _effective_action(...) | 新人命令路径 | `docs/guides/newcomer-command-path.md` | | guided start | `loopx/cli_commands/starter_bootstrap.py`、`loopx/bootstrap_command_pack.py` | | heartbeat body | `loopx/heartbeat_prompt.py` | -| quota 入口 | `loopx/quota.py::build_quota_should_run` | +| quota 入口 | `loopx/control_plane/quota/should_run.py::build_quota_should_run` | | Showcase 真相 | `docs/showcases/showcase-catalog.json` | | guided start 回归 | `examples/bootstrap-command-pack-smoke.py` | | quota/heartbeat 回归 | `examples/control_plane/heartbeat-quota-flow-smoke.py` | diff --git a/docs/development/control-plane-course/06-quota-decision-kernel.md b/docs/development/control-plane-course/06-quota-decision-kernel.md index 9317623f9..639b136cc 100644 --- a/docs/development/control-plane-course/06-quota-decision-kernel.md +++ b/docs/development/control-plane-course/06-quota-decision-kernel.md @@ -55,7 +55,7 @@ interaction contract。后面的字段、mode 和 scheduler hint 都应能回到 - 这一轮可以 spend 吗？ - host 下一次多久后再唤醒？ -所以现在的核心函数 `loopx/quota.py::build_quota_should_run` 更像一个 decision compiler： +所以现在的核心函数 `loopx/control_plane/quota/should_run.py::build_quota_should_run` 更像一个 decision compiler： ```text registered state + projections + runtime declarations @@ -210,7 +210,8 @@ selected Todo 显式声明 `task_repository` 且当前 mode 允许验证后记 ## Decision Pipeline -`build_quota_should_run` 的代码很长，但阅读时可以按决策阶段理解，而不是按行号通读。 +`quota should-run` 的决策链分布在 `should_run.py`、`should_run_prepare.py` 与 +`should_run_packet.py` 三个 bounded 模块中，阅读时按决策阶段理解，而不是按行号通读。 ### 1. Resolve goal 与 agent identity @@ -508,7 +509,8 @@ jq '{ ### 1. 先建立 decision inputs，再谈优先级 -`loopx/quota.py::build_quota_should_run` 开始时解析 registry goal、quota plan、user/agent todo projection 与 peer identity。中段才进入核心 pipeline： +`loopx/control_plane/quota/should_run_prepare.py` 负责解析 registry goal、quota plan、 +user/agent todo projection 与 peer identity。`should_run_packet.py` 才进入核心 pipeline： ```python goal_boundary = _goal_boundary(registry_goal or item, item=item, ...) @@ -675,7 +677,7 @@ cli_channel -> 下一条 CLI 写回、何时允许 spend ### 断点与 decision table -建议在 `quota.py:1404`、`:1434`、`:1442`、`:1461`、`:1489` 打断点，记录下面的最小表： +建议在 `should_run_prepare.py` 与 `should_run_packet.py` 的关键阶段打断点，记录下面的最小表： | 场景 | normal | self repair | workspace repair | terminal | 预期 action | | --- | ---: | ---: | ---: | ---: | --- | @@ -699,14 +701,16 @@ cli_channel -> 下一条 CLI 写回、何时允许 spend ```text loopx/cli.py -> quota command handler - -> loopx/quota.py::build_quota_should_run + -> loopx/control_plane/quota/should_run.py::build_quota_should_run -> loopx/control_plane/quota/ -> loopx/control_plane/runtime/ -> loopx/control_plane/scheduler/ -> loopx/control_plane/todos/ ``` -不要把 `quota.py` 的文件长度当成设计边界。仓库正在把已证明的规则迁入 bounded context，`docs/product/core-control-plane/bounded-context-layout.md` 和 `rule-seam-map.md` 才是导航图。 +不要把 `loopx.quota` facade 的剩余文件长度当成设计边界。已证明的规则已经迁入 +bounded context；`docs/product/core-control-plane/bounded-context-layout.md` 和 +`rule-seam-map.md` 才是导航图。 ### Characterize before move diff --git a/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md b/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md index 90aa27742..a2b10fc91 100644 --- a/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md +++ b/docs/development/control-plane-course/07-host-scheduler-and-heartbeat.md @@ -632,7 +632,7 @@ App tick 2. `docs/operations/long-task-cadence-policy.md` 3. `loopx/heartbeat_prompt.py` 4. `loopx/control_plane/scheduler/` -5. `loopx/quota.py` 的 final composition：interaction contract、scheduler hint、protocol action packet +5. `loopx/control_plane/quota/should_run_packet.py` 的 final composition：interaction contract、scheduler hint、protocol action packet 6. `docs/product/core-control-plane/state-machine.md` 的 Scheduler/Heartbeat 状态机 ## 代表性 Smoke diff --git a/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md b/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md index ee0cd1189..00bf8d291 100644 --- a/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md +++ b/docs/development/control-plane-course/10-autonomous-agent-quality-gates.md @@ -296,7 +296,8 @@ replan interval reached ### 核心代码领读：Replan 如何覆盖 Monitor Quiet -入口是 `loopx/quota.py::build_quota_should_run`。先找到 monitor quiet 的候选决策， +入口是 `loopx/control_plane/quota/should_run.py::build_quota_should_run`；prepare 与 packet +阶段分别位于 `should_run_prepare.py` 和 `should_run_packet.py`。先找到 monitor quiet 的候选决策， 再继续向下看 replan 分支： ```python diff --git a/docs/development/control-plane-course/topic-long-horizon-convergence.md b/docs/development/control-plane-course/topic-long-horizon-convergence.md index 1a8eb6840..75fb7fbf7 100644 --- a/docs/development/control-plane-course/topic-long-horizon-convergence.md +++ b/docs/development/control-plane-course/topic-long-horizon-convergence.md @@ -1614,7 +1614,7 @@ LoopX 已经提供的通用机制包括： | 机制 | 入口 | 读代码时要确认 | | --- | --- | --- | -| 本轮决策 | `loopx/quota.py::build_quota_should_run` | 多种 source facts 怎样收敛成一个 interaction decision | +| 本轮决策 | `loopx/control_plane/quota/should_run.py::build_quota_should_run`（prepare/packet 在 `should_run_prepare.py`、`should_run_packet.py`） | 多种 source facts 怎样收敛成一个 interaction decision | | Agent-facing packet | `loopx/control_plane/work_items/interaction_contract.py::build_interaction_contract` | selected work、gate、replan、terminal 是否完整投影 | | Goal frontier replan | `loopx/control_plane/goals/goal_frontier/replan_rules.py::select_goal_frontier_replan_rule` | runnable、gate、succession gap、monitor exhaustion 的优先级 | | Vision checkpoint | `loopx/state_refresh.py::build_vision_checkpoint` | material closeout 后如何防止局部目标替代长期方向 |