Repository navigation
refactor(agents): slim agent_scope and purge _ACTION_SCOPE_STOPWORDS for typed scope matching - #8936
loopx-agent wants to merge 1 commit into
Conversation
32ecdce to
7e12a36
Compare
…for typed scope matching Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
7e12a36 to
4add4de
Compare
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent | self_reported | Gemini | Google DeepMind
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机 / Motivation
使用 scoped gate 兜底选择、奖惩经验匹配与 Agent 范围收敛的控制面开发者及自动巡检任务。
此前 agent_scope.py 中存在 _ACTION_SCOPE_STOPWORDS 与 _action_scope_tokens_from_text 文本正则停用词黑箱切词启发式(外加大量 dict[str, Any]),维护脆弱且易受多语言或无意义词汇误匹配影响(agent_scope.py 原达 1,453 行、any_count=107);本次彻底清除正则停用词黑箱与 import re,改为基于结构化作用域字段(HUMAN_REWARD_LESSON_STRUCTURED_SCOPE_FIELDS + work_lane)匹配,并同步净化 agent_scope.py 净减 298 行且把 any_count 上限由 107 压低至 13。
删除 _ACTION_SCOPE_STOPWORDS 与 _action_scope_tokens_from_text 及 import re,将反馈经验作用域收口到结构化字段(含 CJK 覆盖测试),同步下调 module_metric_baseline 中 agent_scope.py any_count 至 13。
非目标边界:本 PR 不修改其他文件中的非 scope 停用词残留(由独立 PR 跟进),也不改变无关配额调度策略。
清掉正则停用词启发式不仅消除英文词袋对中文或跨域名场景的盲区,还借助统一辅助提取让 agent_scope.py 实现净减法重构并大幅收敛类型不确定性。
改动思路 / Approach
以显式结构化作用域字段契约(HUMAN_REWARD_LESSON_STRUCTURED_SCOPE_FIELDS 与 work_lane)取代 agent_scope.py 内脆弱的停用词词袋与正则切词,在保持既有公开投影消费契约的同时消减 298 行冗余与 94 个 Any 注解。
当前 PR 边界:仅覆盖 agent_scope.py 停用词退役与结构化投影重构、feedback.py 结构化 lesson 作用域压缩、quota/_supporting_projections.py 与 should_run_packet work_lane 透传及对应 baseline/测试(8 文件)。
- 结构化匹配不变量:
feedback.py中的compact_reward_lesson显式保留与校验结构化 scope 字段(todo_id,agent_id,capability_id,work_lane等),_supporting_projections.py优先依据结构化字段交集做经验匹配,消除对自由文本停用词词包的依赖。 - 类型与体积棘轮:在
agent_scope.py用Mapping[str, object]与共享辅助替代泛滥dict[str, Any](1,453 -> 1,155行,import re彻底删除),同步把module_metric_baseline.json中该模块any_count上限由107锁定下调至13。
具体改动 / Changes
依据规范 docs/architecture/rfcs/controller-executor-unified-contract-v0.md(修订 ef099ae3ac3c08054b9d928fff48aefe2615b950)核对两项要求:
TYPED-SCOPE-MATCH:移除_ACTION_SCOPE_STOPWORDS正则停用词启发式,改用结构化作用域与显式分词比较并覆盖 CJK 用例(由tests/control_plane/test_quota_supporting_projections.py与test_scoped_gate_fallback_selection.py31 passed 验证)。RATCHET-ANY-DOWN:agent_scope.py净减 298 行并将module_metric_baseline.jsonany_count下调至13(由canary premerge中control-plane-maintainability-ratchet-smoke.py验证 PASS)。
关键代码讲解
loopx/control_plane/agents/agent_scope.py:1:彻底移除import re、_ACTION_SCOPE_STOPWORDS词袋及_action_scope_tokens_from_text,整理_as_dict/_dict_items/_select_and_compact_candidates与_AgentScopeNoCandidateContext结构,单文件净减 298 行、移除 94 个Any。loopx/feedback.py:205(HUMAN_REWARD_LESSON_STRUCTURED_SCOPE_FIELDS/compact_reward_lesson):新增结构化 scope 白名单与公开安全校验,确保结构化字段写入即可安全投影消费。loopx/control_plane/quota/_supporting_projections.py:1(_match_lesson_structured_scope)&should_run_packet.py:1653:把work_lane透传至投影并优先匹配结构化域键值,非结构化文本回退收窄为纯显式对比。
对主干的风险 / Risks
历史持久化中若存在完全缺少结构化字段的旧 lesson,_match_unstructured_avoid 仍留有最小只读规范化兜底且有 CJK/ASCII 回归单测保护;另注意后续合并需留意本 PR 与独立 feedback.py 惰性加载改进 PR 分别修改不同行区段(feedback.py:205+ 与顶部 import 区),彼此无语义冲突。远端 GitHub Actions kernel-static-checks 目前报错为 origin/main 既有的 tests/control_plane/test_contract_health.py:10 F401(本 PR 未改该文件)。
| 验证项 | 级别 | 结果 | 实跑输出(exact head 4add4dec055f0d1adea211ef724c4bfe02706927) |
|---|---|---|---|
pytest -q tests/control_plane/test_quota_supporting_projections.py tests/control_plane/test_scoped_gate_fallback_selection.py |
required | PASS | 31 passed in 7.35s |
ruff check loopx/control_plane/agents/agent_scope.py loopx/control_plane/quota/_supporting_projections.py loopx/feedback.py loopx/control_plane/quota/should_run_packet.py |
required | PASS | All checks passed! |
loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick |
required | PASS | selected_checks: 3, failures: 0, ok: true (maintainability-ratchet + semantic-vocabulary-drift + configure-goal) |
远端 GitHub Checks(kernel-static-checks 等) |
diagnostic (required=false) |
FAIL (unrelated) | 基线 tests/control_plane/test_contract_health.py:10 F401 预存故障 |
我的整体评价 / Verdict
对精确 head 4add4dec055f0d1adea211ef724c4bfe02706927 的评价:用户体验维度影响为 not_applicable(仅调整控制面内部 scope/projection 结构化匹配逻辑与注解类型,不涉及 UI 界面、样式或渲染视图(inspected: loopx/control_plane/agents/agent_scope.py, loopx/feedback.py)。,unverified_scope: none),长程稳定性 improved。本 PR 在语义对齐侧于 feedback.py 内定义本地结构化 scope 字段元组 HUMAN_REWARD_LESSON_STRUCTURED_SCOPE_FIELDS(semantic_alignment=new_semantics_justified / local_only,未扩充全局 status enum;无兼容旧停用词分支 compatibility_assessment=not_applicable)。经精确 head 本地 Pytest 31 项、ruff 与 maintainability-ratchet/semantic-vocabulary canary 实测全绿,同意合入。
English verdict: APPROVE
Summary
Rebases onto
origin/main(0514512ee7), slimsloopx/control_plane/agents/agent_scope.py(1,453 -> 1,155lines,-298net LOC;any_count: 13,dict_any_count: 0), completely deletes_ACTION_SCOPE_STOPWORDSand_action_scope_tokens_from_text, and replaces prose stopword token-bag matching inloopx/control_plane/quota/_supporting_projections.pywith typed structured scope matching (with CJK-safe exact phrase matching only when a lesson carries no structured target fields).Key Changes
loopx/control_plane/agents/agent_scope.py(1,453 -> 1,155lines,573+/871-vsorigin/main,-298net LOC;any_count:107 -> 13;dict_any_count: 0):_ACTION_SCOPE_STOPWORDS,_action_scope_tokens_from_text, and unusedimport re(zero prose stopword tokenizers remain inagent_scope.py)._TodoPatch,_as_dict,_int_value,_dict_items,_first_dict,_todo_label,_todo_identity,_sorted_claimants,_collect_lane_or_fallback,_select_and_compact_candidates,_blocking_handoff_copy).vocabulary_v0.jsonfrontier producer names intact and removed 5 single-line/unused internal wrappers.loopx/canary/module_metric_baseline.json:"loopx/control_plane/agents/agent_scope.py""any_count"from107to13(keeping"dict_any_count": 0).loopx/control_plane/quota/_supporting_projections.py,should_run_packet.py,loopx/feedback.py,loopx/control_plane/runtime/run_compaction.py:_action_scope_tokens_from_textstopword bag overlap in_reward_lesson_projection_warningwith_SelectionScopeContext,_extract_selection_scope_context,_match_lesson_structured_scope, and_match_unstructured_avoid.todo_id,todo_ids,claimed_by,agent_id,task_class,capability_id,capability_ids,required_capabilities,work_lane,action_kind,target_key,scope_key,scope_keys,target_scopes,decision_scope) throughcompact_reward_lessonandcompact_human_reward._reward_lesson_projection_warningnow matches strictly on declared structured scope fields (match_kind: "structured_scope") and never falls back to English stopword-bag overlap; unstructured lessons require exact key match or CJK/English normalized phrase containment (rejecting bare[P0..P4]tags).tests/control_plane/test_quota_supporting_projections.py,tests/control_plane/test_scoped_gate_fallback_selection.py):claimed_by,todo_id,task_class), end-to-endbuild_quota_should_runCJK projection test, andbuild_agent_scope_frontier_payloadCJK fallback test without prose stopwords.Verification
rg -n "_ACTION_SCOPE_STOPWORDS|_action_scope_tokens_from_text" loopx/ tests/ examples/—0hitsuv run --extra test ruff check loopx/control_plane/agents/ loopx/control_plane/quota/_supporting_projections.py loopx/control_plane/quota/should_run_packet.py loopx/feedback.py loopx/control_plane/runtime/run_compaction.py tests/control_plane/test_quota_supporting_projections.py tests/control_plane/test_scoped_gate_fallback_selection.py—All checks passed!uv run --extra test mypy—Success: no issues found in 17 source filesuv run --extra test mypy --no-incremental --follow-imports=silent loopx/control_plane/agents/agent_scope.py loopx/control_plane/quota/_supporting_projections.py loopx/control_plane/runtime/run_compaction.py—Success: no issues found in 3 source filesuv run --extra test python -m pytest tests/architecture/test_semantic_bindings.py tests/architecture/test_semantic_production.py tests/architecture/test_semantic_vocabulary_drift.py tests/control_plane/test_frontier_envelope_compatibility.py tests/control_plane/test_scheduler_backoff_convergence.py tests/control_plane/test_scoped_gate_fallback_selection.py tests/control_plane/test_agent_scope_frontier_contract.py tests/control_plane/test_resume_planning_projection.py tests/control_plane/test_complete_turn_decision.py tests/control_plane/test_quota_supporting_projections.py tests/control_plane/test_work_lane_contract_core.py tests/canary/test_maintainability_ratchet.py -q—408 passed in 153.07sHOMEuv run --extra test loopx check --scan-path ...—errors=0,public boundary scan clean: 8 filesHOMEuv run --extra test loopx canary premerge --from-git-diff --git-diff-base origin/main --tier quick --no-progress—status: passed,merge_gate_passed: true(6/6 direct checks, 3/3 catalog canaries)uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD—RFC bilingual diff check passed.