Skip to content

refactor(chat): group internal typed action modules - #9056

Open
cocolord wants to merge 1 commit into
mainfrom
codex/chat-action-owners-20261119
Open

cocolord wants to merge 1 commit into
mainfrom
codex/chat-action-owners-20261119

Conversation

@cocolord

Copy link
Copy Markdown
Member

Goal And Delivered Outcome

Move the two internal Chat action mixins into the existing loopx/chat/ namespace. ChatActionService still owns the action flow and delegates durable Goal changes to the existing activation and deletion services. The two old module names had only in-tree callers. The verified top-level count drops from 124 to 122. The bilingual RFC also records that #8884 completed the superseded Codex pilot retirement.

Related to #5072. Intended base is main@41ea75e89892.

Author Declaration

Written by model_agent, OpenAI Codex. Implements the internal-module rule I3 and the M1 module ratchet in the distribution RFC.

Criterion Disposition Evidence
M1 internal Chat modules and I3 Implemented for action normalization and Goal lifecycle actions Updated their one production importer and four test references. The two moved implementations differ only in relative import depth.
Top-level budget Implemented tests/architecture/test_top_level_module_budget.py pins 122.
Remaining M1 and M2 moves, R1 and M3 qualification Deferred to the existing RFC owners Both this slice's old and new Chat paths are outside the standalone Core wheel.

Validation

Both wheels were built locally on macOS arm64 with Python 3.12.9 and Node 26. Tested head 9d643de1c6941ac3ecd46d8d4c5e4768ad64d99f.

Path Result
Ordinary wheels The stock loopx chat command serves the same loopback action journey on base and head. A synthetic project exercises preview without writes, stop and resume persisted to source and global registries, stale and invalid refusals, and replay of the original receipt. Normalized observations match. Replacing the stop outcome in a disposable install makes the same external receipt check fail. The three updated runtime files match the tested head bytes.
Standalone Core wheel 16 selected installed cases pass on File and SQLite. They cover accepted work, C1 composed settlement, exact replay, process loss and changed-lease refusal. The wheel omits both old and relocated Chat modules.
Existing checks The same 332 selected Python and frontend-decoder cases pass on base and head. Includes the real HTTP resume regression in tests/control_plane/test_goal_activation.py, the shipped decoder test in tests/presentation/test_goal_lifecycle_proposal_decoder.py, and the architecture ratchet.
Local premerge Quick tier passes with zero blocking failures. One inherited maintainability advisory remains. Ruff, configured mypy, diff-scoped semantic advisory and paired RFC checks pass. The first premerge attempt lacked root npm dependencies. The rerun installs them and passes.
Integration Merge-tree checks pass with the pending Core combination and the three checked C1 follow-up heads in #9052, #9048 and #9055.

The bounded adjacent refactor is the namespace move itself. The validation exercises the existing backend route and frontend decoder. Reverting the change restores both import paths and the budget together.

Signed-off-by: cicolord <cicolord@outlook.com>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent | model: Gemini | provider: Google | declaration_source: self_reported (host observation unavailable)

动机 / Motivation

受影响对象与触发任务:维护 LoopX 顶层模块结构与 Chat 动作控制平面的贡献者、代码评审者,以及构建或运行 loopx-core 与 full wheel 的开发者。

变更前后场景:修改前:仅被内部 ChatActionService 与内部测试引用的动作规范化和 Goal 生命周期两个 mixin 仍停留在顶层 loopx/ 命名空间,导致顶层模块数维持在 124 且内部归属分散。修改后:两个模块迁入已有的 loopx/chat/ 命名空间并删除旧顶层模块,仅更新内部导入方,同时将顶层模块预算从 124 下调至 122。

可观测结果:顶层 loopx/*.py 模块实测从 124 降至 122(tests/architecture/top_level_module_budget.json 同步下调并通过);唯一生产引用方 loopx/chat_actions.py 与 4 个测试模块更新为从 loopx.chat 导入;全仓库无任何残留旧模块名引用;loopx-core 隔离 wheel 安装包测试(48 passed)与 Chat 动作测试均保持等价通过。

边界与非目标(Non-goals):不将顶层公共入口 loopx/chat_actions.py 移入子包,不保留永久顶层兼容 shim,不完成 M1 其余平铺 chat_* 模块或 M2 *_goal_mode 目录迁移,也不修改任何动作规范化或 Goal 生命周期业务逻辑。

当前渐进交付遗留缺口(remaining_gap):M1 下其余顶层 chat_* 模块(包括公开入口与其余辅助模块)及 M2 *_goal_mode 目录迁移仍在各自既有里程碑下待后续独立 PR 推进。 若不做本次迁移,M1 拆分进度与顶层模块预算棘轮无法继续向下推进;作为自包含的纯内部重构切片,本 PR 可独立审查、测试和回滚,同时保持 loopx-core 与 ChatActionService 契约完全等价。

改动思路 / Approach

入口为 loopx/chat_actions.py 中的 ChatActionService 混入组合,它分别继承 ChatActionNormalizationMixin 与 ChatGoalLifecycleActionMixin。动作状态与权限边界继续归 ChatActionStore、控制平面 activation_service/deletion_service 及 TypeScript effect_runtime 所有,本次不改变任何状态转换或失败重试归属方。

既有架构对齐方面,loopx/chat/ 下已存在 monitor_actions.py 与 todo_actions.py 两个同类内部 mixin,因此本次将 chat_action_normalization.py 移至 loopx/chat/action_normalization.py、将 chat_goal_lifecycle_actions.py 移至 loopx/chat/goal_lifecycle_actions.py 是直接复用现有包边界。相对导入从单点(.control_plane 等)加深为双点(..control_plane 等),ChatGoalLifecycleActionMixin 与 ChatActionNormalizationMixin 内原本懒加载 ..chat_actions 辅助符号的路径同步更新。所有生产与测试调用方均为仓库内部代码,因此按架构规则直接删除旧顶层模块而未留兼容 shim。

架构评估结论:将纯内部 mixin 迁入既有的 loopx/chat/ 包并同步收敛顶层预算,既消除了两个平铺顶层文件名,又避免引入第二处兼容桥或修改动作业务语义,符合 I3 内部迁移与 M0 棘轮要求。 当前 PR 边界:仅迁移 action_normalization 与 goal_lifecycle_actions 两个纯内部模块并下调预算(124 -> 122),同步记录 RFC #8884 与本次步进;保留 loopx/chat_actions.py 及公开动作契约不变。

具体改动 / Changes

关键代码讲解

  • loopx/chat/action_normalization.py (ChatActionNormalizationMixin):原 loopx/chat_action_normalization.py 原封移入 loopx/chat/;除 16 处相对导入前缀从 . 调整为 ..(含 ..agent_registry、..registry、..control_plane.* 及方法内懒导入 ..chat_actions)外,业务逻辑一行未改。
  • loopx/chat/goal_lifecycle_actions.py (ChatGoalLifecycleActionMixin):原 loopx/chat_goal_lifecycle_actions.py 原封移入 loopx/chat/;仅顶层与方法内 6 处相对导入从 . 调整为 ..(包括 ..control_plane.goals.* 与 ..chat_actions 内的 _opaque/_text/_digest)。
  • loopx/chat_actions.py (ChatActionService):唯一生产调用方,仅将顶层导入改为 from .chat.action_normalization import ChatActionNormalizationMixin 与 from .chat.goal_lifecycle_actions import ChatGoalLifecycleActionMixin,对外类名与动作调度行为完全不变。
  • 架构与测试更新:tests/architecture/top_level_module_budget.json 将 baseline_commit 更新为 41ea75e89892ed88d0ae543e97e31aad0a181c47,max_top_level_modules 从 124 降至 122;同步更新 test_content_digest_single_owner.py、test_compact_identifier_shape_owner.py、test_goal_activation.py、test_finance_transaction_approval_consumer.py 4 个测试导入与路径引用;monorepo-distribution-split-v0.md 与 .zh-CN.md 同步记录 #8884 及本次预算 124 -> 122。

规范对照(Spec Basis)

参考变更前基线规范 docs/architecture/rfcs/monorepo-distribution-split-v0.md(基线提交 41ea75e89892ed88d0ae543e97e31aad0a181c47;因本 PR 同步更新了该 RFC 第 11.4.3 节进度记录,审查严格以修改前基线判定):

  • I3:implemented —— 内部专用模块须同步更新所有内部调用方并删除旧顶层入口(由 loopx/chat/action_normalization.py 等更新、全仓无旧模块残留引用及隔离导入探针证实)。
  • M0-ratchet:implemented —— 删除/迁出顶层模块必须在同一 PR 同步下调顶层预算(tests/architecture/top_level_module_budget.json 从 124 降至 122 并通过 test_top_level_module_budget.py)。
  • M1:deferred —— 将全部其余平铺 loopx/chat_*.py 迁入 loopx/chat/(本切片仅覆盖 2 个内部动作 mixin,其余模块留待后续 M1 独立 PR)。

对主干的风险 / Risks

无阻塞性发现(No blocking finding)。

  • 调用链与反事实排查:全仓搜索 chat_action_normalization|chat_goal_lifecycle_actions 零残留引用;严格剔除可编辑安装 __editable__ hook 后的隔离探针验证:importlib.util.find_spec('loopx.chat_action_normalization') 与 find_spec('loopx.chat_goal_lifecycle_actions') 均为 None,而 ChatActionService 正常继承并解析 loopx.chat.action_normalization 与 loopx.chat.goal_lifecycle_actions。packages/loopx-core/prepare.py 的 EXCLUDED_TREES 原已排除 loopx/chat/ 与 loopx/chat_*,故打包边界不变。
  • 非阻塞补充观察:tests/test_chat_internal_module_layout.py 目前校验了 monitor_actions、todo_actions 等 12 个已迁模块无顶层 shim,但本次未将 action_normalization 和 goal_lifecycle_actions 追加进该清单;不影响当前正确性(test_top_level_module_budget.py 与上述测试已覆盖),后续 M1 切片可顺手补入。
  • 精确 Head 本地验证矩阵(9056@9d643de1c6941ac3ecd46d8d4c5e4768ad64d99f):
    • 架构与核心目标测试:PASS —— pytest 运行 test_top_level_module_budget.py、test_content_digest_single_owner.py、test_semantic_vocabulary_drift.py、test_semantic_production.py、test_compact_identifier_shape_owner.py、test_goal_activation.py、test_finance_transaction_approval_consumer.py 共 502 passed in 46.67s。
    • Chat 内部布局与动作回归测试:PASS —— 运行 test_chat_internal_module_layout.py、test_chat_capabilities_route_single_owner.py、test_chat_action_kind_owner.py、test_chat_user_action_handling.py、test_chat_team_plan_action.py、test_chat_goal_amendment.py、test_chat_goal_draft.py 共 73 passed in 36.01s。
    • 独立 loopx-core wheel 构建与安装态测试:PASS —— packages/loopx-core/prepare.py + uv build --wheel 构建并在 Python 3.12 干净 venv 运行 test_core_distribution.py 与 test_installed_core_context.py,48 passed in 223.24s。
    • scripts/check_rfc_bilingual.py --base origin/main --head HEAD:PASS。
    • loopx check --scan-path ...、ruff check、npm run typecheck:control-plane、examples/semantic-vocabulary-drift-smoke.py (29/29):全部 PASS;loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main:PASS(failures: 0)。
    • 基线既定失败归因(非本 PR 回归):
      1. examples/control_plane/control-plane-maintainability-ratchet-smoke.py --format=json 报 2 个 unreviewed_findings(loopx/control_plane/heartbeat/builder.py:build_heartbeat_prompt 与 loopx/control_plane/work_items/interaction_contract.py:_admitted_interaction_next_cli_actions),在未修改主分支 origin/main(41ea75e89892)上运行复现出完全一致的 2 项发现(pre_existing_unrelated)。
      2. tests/test_chat_operation_actions.py 5 passed / 4 failed(ProjectRegistryProtocolError: Goal activation metadata requires upgrade),在 origin/main(41ea75e89892)运行同一 4 个用例出现完全一致的 4 项失败(pre_existing_unrelated)。
      3. mypy 在 3 个修改文件上报告 58 个既定注解类型错误,改动行(导入深度 . -> ..)引入 0 个新错误。

我的整体评价 / Verdict

  • 成果影响(outcome_impact):
    • long_horizon: preserved —— 仅迁移内部 mixin 模块路径,Goal 生命周期动作状态机、幂等租约与控制平面委托行为在隔离测试与 wheel 验证中完全保持。
    • user_experience: preserved —— 公开 ChatActionService 入口与消息行为保持一致;就 UI/视觉检查而言,visual_review 为 not_applicable(reason: 本次重构仅涉及内部 Python 模块路径重组、测试导入更新与架构预算 JSON/RFC 更新,无任何前端或桌面 UI 渲染变更。;unverified_scope: none)。
  • 可观测语义与代码体量:observable_semantics 为 equivalent(相对基线 41ea75e89892 的导入隔离探测、73 个 Chat 用例及 48 个安装态 Core wheel 用例行为一致)。code_volume 为 necessary(10 个文件 +62/-69,其中两个脚本目录重命名各自仅变更相对导入层级;compatibility_assessment 为 not_applicable,因两模块仅被仓内内部调用且 I3 允许直接迁移并删除旧路径)。default_off_isolation 与 authority_semantics 均为 not_applicable。
  • 词汇分类判断:semantic_alignment 为 not_applicable(未新增或变更共享状态词表;examples/semantic-vocabulary-drift-smoke.py 29/29 全量通过)。
  • 残余风险(Residual Risk):无影响合并的残余功能风险;非阻塞测试完备性补充仅在于 tests/test_chat_internal_module_layout.py 尚未显式列出此次新增的两个嵌套子模块。远端 CI 按策略未等待(ci_policy: not_consulted)。

评审精确提交:9056@9d643de1c6941ac3ecd46d8d4c5e4768ad64d99f。

English Verdict: APPROVE

@mergify

mergify Bot commented Nov 19, 2026

Copy link
Copy Markdown

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @cocolord.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-rebase Mergify: the pull request has merge conflicts with its base branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants