fix: M1-M4 修复 Protocol 签名与设计文档对齐 + §14 去重
CI / lint (pull_request) Failing after 7s
CI / test (pull_request) Has been skipped
CI / notify-on-failure (pull_request) Successful in 1s

This commit is contained in:
cfdaily
2026-06-10 15:40:12 +08:00
parent 474f6baaa2
commit 8ebfeeec7d
2 changed files with 21 additions and 454 deletions
+11 -409
View File
@@ -53,10 +53,11 @@ moziplus v2 的任务调度系统当前通过 `if/else` 硬编码区分两种 ta
定义 Python Protocol,所有 task type handler 必须满足此接口:
```python
from typing import Protocol, Optional, Dict, Any
from typing import Protocol, Optional, Dict, Any, runtime_checkable
from pathlib import Path
@runtime_checkable
class TaskTypeHandler(Protocol):
"""所有 task type handler 的统一接口。"""
@@ -64,35 +65,12 @@ class TaskTypeHandler(Protocol):
task_type: str # 类型标识:'task' | 'mail' | 'toolchain'
virtual_project: Optional[str] # 虚拟项目 ID,如 '_mail'、'_toolchain'。普通任务为 None
def build_prompt(
self,
task_id: str,
title: str,
description: str,
must_haves: str,
project_id: str,
agent_id: str,
task: Optional[Dict] = None,
spawn_type: str = "executor",
spawner: Any = None,
) -> str:
"""构建 Agent prompt。"""
def build_prompt(self, context: "PromptContext") -> str:
"""构建 Agent prompt(通过 PromptComposer 拼 section)。"""
...
def build_api_section(
self, project_id: str, task_id: str, agent_id: str
) -> str:
"""构建 API 操作指令(success_status 等)。"""
...
def skip_guardrail(self, project_id: str) -> bool:
"""是否跳过 guardrail 检查。"""
...
def pre_spawn(
self, task_id: str, db_path: Path, dispatcher: Any
) -> Optional[callable]:
"""spawn 前回调,返回 on_checks_passed 回调或 None。"""
def pre_spawn(self, task_id: str, db_path: Path) -> bool:
"""spawn 前业务准备。默认 Truemail/toolchain override 为 auto_working。"""
...
def post_complete(
@@ -101,30 +79,15 @@ class TaskTypeHandler(Protocol):
agent_id: str,
outcome: str,
db_path: Path,
must_haves: str,
dispatcher: Any,
) -> None:
"""spawn 完成后回调"""
...
def build_retry_prompt(
self,
task_id: str,
agent_id: str,
retry_count: int,
max_retries: int,
retry_field: str,
task_info: Dict,
spawner: Any,
) -> str:
"""构建重试 prompt。"""
"""spawn 完成后的业务处理。统一流程:crash→verify→mark→notify"""
...
def check_completion(self, task_id: str, db_path: Path) -> bool:
"""检查任务是否已完成(如 mail 的回复检查"""
"""ticker 级别的完成检查。"""
...
def get_sections(self) -> list['PromptSection']:
def get_sections(self) -> list:
"""返回此 handler 的 prompt section 列表。
返回有序的 PromptSection 列表,由 PromptComposer 统一拼装。
@@ -503,19 +466,9 @@ for vp in TaskTypeRegistry.virtual_projects():
# §12 PromptSection 模式
基于知识库优秀实践(Hermes 10层有序注入、Microsoft 三层中间件、我们的上下文五层架构),引入 PromptSection 模式。
基于知识库优秀实践(Hermes 10层有序注入、Microsoft 三层中间件),引入 PromptSection 模式。
### 统一的上下文五层架构
PromptComposer 是 **L2 引擎注入层**的拼装机制。五层定义(统一设计语言):
| 层 | 名称 | 机制 | 内容示例 | token |
|---|------|------|---------|-------|
| L0 | 铁律层 | Hook 每轮强制注入 | GATE 铁律、Delegation 铁律 | ~500 |
| L1 | 角色层 | Workspace 自动注入 | SOUL.md、AGENTS.md、TOOLS.md、MEMORY.md | ~2000 |
| **L2** | **引擎注入层** | **PromptComposer 按 handler 拼装** | **任务上下文、前序产出、角色规范、API 指令、约束** | **~1500** |
| L3 | 被动参考层 | Skills 索引注入,Agent 按需 read 全文 | OpenClaw 42 Skills + moziplus SkillRegistry | 按需 |
| L4 | 检索层 | Agent 运行时主动检索 | wiki 知识库、NAS 文档、Web 搜索 | 按需 |
> 五层架构定义、L1-L4 去重规则、层间引导详见 **§14**。
priority 范围与 L2 注入组件的对应关系:
@@ -1054,354 +1007,3 @@ handler.post_complete(task_id, agent_id, outcome, db_path)
**结论**L2 的 RoleSkillSection 改为注入索引+引导语(~100 token),引导 Agent 用 `read` 去读 Skill 全文(L3 层)。遵循 Hermes 的渐进式 Skill 加载模式。
---
# §14 上下文五层架构统一
## 五层定义(统一设计语言)
PromptComposer 是 **L2 引擎注入层**的拼装机制。五层定义如下:
| 层 | 名称 | 机制 | 内容示例 | token |
|---|------|------|---------|-------|
| L0 | 铁律层 | Hook 每轮强制注入 | GATE 铁律、Delegation 铁律 | ~500 |
| L1 | 角色层 | Workspace 自动注入 | SOUL.md、AGENTS.md、TOOLS.md、MEMORY.md | ~2000 |
| **L2** | **引擎注入层** | **PromptComposer 按 handler 拼装** | **任务上下文、前序产出、角色规范、API 指令、约束** | **~1500** |
| L3 | 被动参考层 | Skills 索引注入,Agent 按需 read 全文 | OpenClaw 42 Skills + moziplus SkillRegistry | 按需 |
| L4 | 检索层 | Agent 运行时主动检索 | wiki 知识库、NAS 文档、Web 搜索 | 按需 |
## L1-L4 去重规则
当前 L1 和 L2 存在重叠(Agent 身份两处注入、API 操作指令两处注入、状态流转规则两处注入)。重构后:
| 信息 | 唯一归属 | 其他层怎么处理 |
|------|---------|--------------|
| Agent 身份 | L1 | L2 删除 `_inject_agent_identity` |
| 团队协作规则 | L1 | L2 不重复 |
| API 操作方法 | L2(任务级精简版) | L1 保留黑板概述,L2 只给本次任务的 curl |
| Skill 全文 | L3Agent 按需 read) | L2 只给索引+引导语,不注入全文 |
| 状态流转规则 | L1(完整版) | L2 只给 success_statusdone/review |
| 安全红线 | L0 | L2 不重复 |
| 任务上下文 | L2 | L1 不涉及 |
## 层间引导
每层只做自己的事,通过层间引导语串联:
- L2 prompt 末尾追加引导语:
- "需要详细操作规范?用 `read` 读取对应 Skill 文件"(引导到 L3
- "需要更多知识?查看 wiki 知识库或 Web 搜索"(引导到 L4
---
# §15 Spawner/Handler 职责边界
## Spawner 职责(进程管理层)
| 职责 | 说明 |
|------|------|
| 进程启动/监控 | spawn subprocess、monitor stdout/stderr |
| 进程退出分类 | `_classify_outcome`A0-A17 全在 spawner |
| 重试决策 | `should_retry` + `_do_retry` + cooldown |
| counter 管理 | acquire/release/cooldown |
| attempt 记录 | `_record_attempt` |
## Handler 职责(业务调度层)
| 职责 | 说明 |
|------|------|
| prompt 构建 | 通过 PromptComposer 拼 section |
| pre_spawn 业务准备 | auto_working 等 |
| crash 回退 | rollback current_agent |
| 完成验证 | verify_completion |
| 状态标记 | mark success/failed |
| 失败通知 | notify_failure |
## 关键边界
1. **Spawner 不做业务逻辑**`_build_mail_prompt` 和 `_build_api_section` 迁移到 handler 后,spawner 不再构建 prompt
2. **Handler 不碰进程管理**handler 不做 exit 分类、不做 retry 决策、不管 counter
3. **状态标记不冲突**spawner 的 `_mark_task` 处理进程级异常(crash/auth_failed/api_error → failed),handler 的 `mark_task_status` 处理业务级完成(done/review/failed)。两者操作不同 outcome 场景,互斥不重复
4. **on_complete 是桥梁**spawner 完成进程级处理后调 `on_complete(outcome)`handler 收到 outcome 做业务级处理
---
# §16 BaseTaskHandler 基类设计
## 设计原则
基类收敛**合理的共性能力**,不是现有代码的归类总结。参考优秀实践:
- Hermes: "Keep calling tools until complete AND verified"
- Quality Gate: 三阶段门控(机械→语义→共识)
- Edict: stalled→retry→escalate 升级策略
- OpenAI Agents SDK: Input/Output Guardrail
## VerifyResult 结构
```python
@dataclass
class VerifyResult:
"""验证结果"""
passed: bool
reason: str # "has_output" / "no_reply" / "no_signal" / ...
evidence: str # "output_count=1, comment_count=0"
can_retry: bool = True
retry_count: int = 0
```
## 基类定义
```python
class BaseTaskHandler:
"""所有 task type handler 的基类。
职责:L2 引擎注入层的业务逻辑——prompt 构建、完成验证、状态标记。
不管:进程生命周期、exit 分类、重试决策(这些归 spawner)。
"""
# crash 类 outcome(进程级异常,需要 rollback
CRASH_OUTCOMES = frozenset({
"crashed", "compact_failed", "process_crash",
"session_stuck", "compact_hanging",
})
# === 子类必须实现 ===
task_type: str
virtual_project: Optional[str]
def build_prompt(self, context: PromptContext) -> str:
"""构建 L2 prompt(通过 PromptComposer 拼 section"""
...
def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult:
"""验证任务完成质量。每个 handler 自己的验证逻辑。"""
...
def target_success_status(self) -> str:
"""验证通过后的目标状态。task='review', mail/toolchain='done'"""
return "review"
# === 基类提供统一流程 ===
def pre_spawn(self, task_id: str, db_path: Path) -> bool:
"""spawn 前业务准备。默认:True。
mail/toolchain override 为 auto_working。"""
return True
def post_complete(self, task_id: str, agent_id: str,
outcome: str, db_path: Path) -> None:
"""spawn 完成后的业务处理。统一 4 步流程:
1. crash 处理 → rollback current_agent
2. verify → 验证产出
3. mark → 标目标状态
4. notify → 失败时通知
spawner 已完成进程级处理(exit 分类、重试、counter release)。
这里只做业务级处理。
"""
# 1. crash 处理(基类提供,所有 handler 继承)
if outcome in self.CRASH_OUTCOMES:
self._rollback_current_agent(db_path, task_id, agent_id)
return # crash 不进 verify,不标状态
# 2. verify
result = self.verify_completion(task_id, db_path)
# 3. mark
if result.passed:
mark_task_status(db_path, task_id, self.target_success_status())
else:
# 4. notifyon_failure 内部处理)
self.on_failure(task_id, agent_id, db_path, result)
def _rollback_current_agent(self, db_path: Path, task_id: str, agent_id: str) -> None:
"""crash 后回退 current_agent → assignee,避免 exclude_current 卡死。
从 dispatcher._rollback_current_agent 迁移。"""
...
def on_failure(self, task_id: str, agent_id: str,
db_path: Path, verify: VerifyResult) -> None:
"""验证失败处理。默认:标 failed。
子类可 override 加通知等。"""
mark_task_status(db_path, task_id, "failed")
def check_completion(self, task_id: str, db_path: Path) -> bool:
"""ticker 级别的完成检查。默认:False。"""
return False
```
## 为什么删掉了这些方法
| 删除的方法 | 原因 |
|-----------|------|
| `skip_guardrail` | guardrail 是系统级安全层,不该由 handler 开关。guardrail 规则自己判断 project_id 是否跳过 |
| `build_retry_prompt` | retry 是 spawner 层的职责,handler 不管重试 |
## 为什么 verify_completion 是每个 handler 必须实现的
参考 Hermes 的 "Keep calling tools until complete AND verified"——验证不是可选的,是完成流程的核心环节。每个 handler 的验证逻辑不同(task 看三信号、mail 看回复、toolchain 看行动输出),但**必须验证**这个要求是共性的。
---
# §17 三个 Handler 的完整执行流程
## 统一流程骨架
```
ticker 扫描 → dispatcher.decide → 路由到 agent
handler.pre_spawn(task_id, db_path)
│ task: return True(无准备)
│ mail/toolchain: auto_workingpending → working
spawner.spawn_full_agent()
├── counter acquire
├── handler.build_prompt(context) ← L2 prompt 拼装
├── subprocess 启动 Agent 进程
├── monitor
Agent 进程退出)
spawner._handle_exit()
├── _classify_outcome → outcome
├── should_retry=True → _do_retryspawner 自己处理,不调 handler
└── should_retry=False → on_complete(outcome)
handler.post_complete(task_id, agent_id, outcome, db_path)
├── 1. crash? → rollback current_agent → return
├── 2. verify_completion → VerifyResult
├── 3. passed? → mark target_success_status()
└── 4. failed? → on_failure()
```
## TaskHandler 执行流程
| 阶段 | 动作 | 代码来源 |
|------|------|----------|
| pre_spawn | return True | — |
| build_prompt | PromptComposer 拼 5 个 section | BootstrapBuilder |
| post_complete → crash | rollback current_agent | dispatcher._rollback_current_agent |
| post_complete → verify | 三信号检查(output_count>0 OR comment_count>0 OR status已终态) | dispatcher._task_verify_completion |
| passed → mark | "review" | dispatcher._task_auto_complete |
| failed → on_failure | 留 working(等 ticker 重投) | 当前行为保持 |
**Task 特殊逻辑**review 阶段的 on_complete 需要读 verdict → approved 标 done / 非 approved @mention assignee。这是 TaskHandler 的 review 分支,不走 verify 流程。
## MailHandler 执行流程
| 阶段 | 动作 | 代码来源 |
|------|------|----------|
| pre_spawn | auto_workingpending → working | dispatcher._mail_auto_working |
| build_prompt | PromptComposer 拼 3 个 section | spawner._build_mail_prompt |
| post_complete → crash | rollback current_agent**补上** | 新增 |
| post_complete → verify | 区分 inform/requestrequest 检查是否回复,inform 检查 outcome | dispatcher._mail_auto_complete |
| passed → mark | "done" | dispatcher._mail_auto_complete |
| failed → on_failure | mark "failed" + Mail 通知发件人 | dispatcher._mail_auto_complete |
**Mail 修复项**:当前 mail crash 时不做 rollback current_agent,可能导致 exclude_current 卡死。重构后补上。
## ToolchainHandler 执行流程
| 阶段 | 动作 | 代码来源 |
|------|------|----------|
| pre_spawn | auto_workingpending → working | 新增 |
| build_prompt | PromptComposer 拼 3 个 section | toolchain_templates.py |
| post_complete → crash | rollback current_agent | 新增 |
| post_complete → verify | 检查行动输出(output 或 comment 有实质内容) | 新增 |
| passed → mark | "done" | 新增 |
| failed → on_failure | mark "failed" + Mail 通知主公 | 新增 |
## 三个 handler 差异收敛表
| 差异点 | TaskHandler | MailHandler | ToolchainHandler |
|--------|------------|-------------|-----------------|
| pre_spawn | 无 | auto_working | auto_working |
| sections 数量 | 5 | 3 | 3 |
| verify 逻辑 | 三信号检查 | 回复检查 + inform/request 区分 | 行动输出检查 |
| target_success_status | review | done | done |
| on_failure | 留 working | 标 failed + 通知发件人 | 标 failed + 通知主公 |
| review 分支 | 有(读 verdict | 无 | 无 |
---
# §18 设计决策记录
本节记录设计过程中的关键讨论和决策,便于未来回顾。
## D1: 方案A(独立 task typevs 方案Bmail 内子分支)
**决策**:方案A,独立 task type。
**讨论**:方案B 改动量小但数据混合、mail handler 重构时会波及。方案A 数据隔离、生命周期独立、未来演进互不影响。主公明确表示"不想修修补补"。
## D2: 设计一步到位,实现分步
**决策**PromptSection 模式 + BaseTaskHandler 基类 + 五层架构统一都在设计文档中完整定义,但实施按 5 步渐进。
**讨论**:避免设计时偷懒、实现时痛苦。设计完整后实施每步有清晰目标。
## D3: 三种 handler 不是简单的"子集"关系
**讨论**:最初认为 MailHandler/ToolchainHandler 是 TaskHandler 的子集(流程是 TaskHandler 最全,其他是简化版)。
**结论**:三种 handler 走相同的流程骨架(Protocol 定义),但每一步的实现各自不同。MailHandler 有独特的幻觉门控和回复检查,TaskHandler 有独特的 review verdict 分支。差异是真实的,不是简单的"全"和"子集"。但从共性角度看,TaskHandler 的 section 数量最多(5个),MailHandler 和 ToolchainHandler 更简单(3个),这个认知是正确的。
## D4: 幻觉门控和 verify 应该所有 handler 都有
**发现**:当前只有 mail 有幻觉门控(`_mail_auto_complete` 中检查是否回复)、只有 task 有三信号验证(`_task_verify_completion`)。很多"差异"是历史遗漏而非设计差异。
**决策**verify_completion 成为 BaseTaskHandler 的抽象方法,所有 handler 必须实现。验证不是可选的,是完成流程的核心环节。
## D5: crash_rollback 放在 handler 基类
**讨论**crash 处理分散在两层——spawner 做进程级处理(cooldown、counter release),dispatcher 做业务级 rollback current_agent。只有 task 路径有 rollbackmail 路径没有。
**结论**
- spawner 管进程级:cooldown、counter release(不动)
- handler 管业务级:rollback current_agent(从 dispatcher 迁移到 BaseTaskHandler
- 放在 post_complete 第一步,所有 handler 都继承,不遗漏
- 当前 mail 缺少 crash rollback 是 bug,重构后补上
## D6: skip_guardrail 从 handler 接口删除
**讨论**handler 接口中 `skip_guardrail` 暗示 handler 可以开关安全层。
**结论**guardrail 是系统级安全层,不该由 handler 开关。guardrail 规则自己判断 project_id 是否跳过(如 `_mail` / `_toolchain` 不做检查)。handler 不需要知道 guardrail 的存在。从 handler 接口中删除。
## D7: spawner 的 prompt 构建迁移到 handler
**讨论**:当前 `_build_mail_prompt` 和 `_build_api_section` 在 spawner 中,按职责应该归 handler。
**结论**handler 的 build_prompt 通过 PromptComposer 拼 sectionspawner 只负责传递 prompt 给 subprocess。spawner 不再做任何 prompt 构建逻辑。这是 L2 职责回归 L2 层。
## D8: L2 Skill 段最小化
**讨论**:当前 BootstrapBuilder 段3 注入 Skill 全文(~800 token),重复了 L3 层的职责。主公提出"最小化 L2 这一层"。
**结论**L2 的 RoleSkillSection 改为注入索引+引导语(~100 token),引导 Agent 用 `read` 去读 Skill 全文(L3 层)。遵循 Hermes 的渐进式 Skill 加载模式:Tier 1 只返回索引,Tier 2 按需加载全文。
## D9: priority 范围划分的设计依据
**讨论**priority 范围(10-19/20-29/30-39/40-49/50-59/60-69)的划分不是凭空定义的,是基于 L2 的 7 个注入组件按认知顺序排列,并参考了 Hermes 的 10 层有序注入实践。
**结论**:LLM 处理信息的认知顺序 = 从目标到背景到方法到行动到约束。Hermes 在生产环境验证过这个顺序的合理性。
## D10: ApiSection 和 ConstraintsSection 统一为参数化类
**讨论**:三个 handler 的 ApiSection 唯一差异是 `success_status`task="review"mail/toolchain="done"),ConstraintsSection 唯一差异是约束内容。
**结论**:统一为参数化类,handler 只需传不同参数:
```python
api_section = ApiSection(success_status="review") # TaskHandler
api_section = ApiSection(success_status="done") # MailHandler / ToolchainHandler
constraints = ConstraintsSection(rules=["禁止状态转换命令", "完成后自动标记 done"])
```
## D11: Gitea 流程临时简化
**背景**:Gitea CI 错误大爆炸,和工具链 webhook 联动形成循环。
**决策**:临时简化 Gitea 流程——PR 合并只需 review 通过,webhook 联动暂停(姜维已执行 active=false)。等 task 架构重构完成后再恢复完整 Gitea 流程。
+10 -45
View File
@@ -9,7 +9,10 @@ from __future__ import annotations
import logging
from pathlib import Path
from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Protocol, runtime_checkable
if TYPE_CHECKING:
from src.daemon.prompt_composer import PromptContext
logger = logging.getLogger("moziplus-v2.registry")
@@ -26,35 +29,12 @@ class TaskTypeHandler(Protocol):
task_type: str # 类型标识:'task' | 'mail' | 'toolchain'
virtual_project: Optional[str] # 虚拟项目 ID,如 '_mail'、'_toolchain'。普通任务为 None
def build_prompt(
self,
task_id: str,
title: str,
description: str,
must_haves: str,
project_id: str,
agent_id: str,
task: Optional[Dict] = None,
spawn_type: str = "executor",
spawner: Any = None,
) -> str:
"""构建 Agent prompt。"""
def build_prompt(self, context: "PromptContext") -> str:
"""构建 Agent prompt(通过 PromptComposer 拼 section)。"""
...
def build_api_section(
self, project_id: str, task_id: str, agent_id: str
) -> str:
"""构建 API 操作指令(success_status 等)。"""
...
def skip_guardrail(self, project_id: str) -> bool:
"""是否跳过 guardrail 检查。"""
...
def pre_spawn(
self, task_id: str, db_path: Path, dispatcher: Any
) -> Optional[Any]:
"""spawn 前回调,返回 on_checks_passed 回调或 None。"""
def pre_spawn(self, task_id: str, db_path: Path) -> bool:
"""spawn 前业务准备。默认 Truemail/toolchain override 为 auto_working。"""
...
def post_complete(
@@ -63,27 +43,12 @@ class TaskTypeHandler(Protocol):
agent_id: str,
outcome: str,
db_path: Path,
must_haves: str,
dispatcher: Any,
) -> None:
"""spawn 完成后回调"""
...
def build_retry_prompt(
self,
task_id: str,
agent_id: str,
retry_count: int,
max_retries: int,
retry_field: str,
task_info: Dict,
spawner: Any,
) -> str:
"""构建重试 prompt。"""
"""spawn 完成后的业务处理。统一流程:crash→verify→mark→notify"""
...
def check_completion(self, task_id: str, db_path: Path) -> bool:
"""检查任务是否已完成(如 mail 的回复检查"""
"""ticker 级别的完成检查。"""
...
def get_sections(self) -> list: