sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues Pull Requests 1 Actions 2 Packages Projects Releases Wiki Activity

docs: Task 系统架构重构设计 v3.0 — 五层架构+BaseTaskHandler+执行流程+决策记录 #23

Merged
pangtong-fujunshi merged 3 commits from docs/task-type-architecture into main 2026-06-10 07:42:12 +00:00
Conversation 5 Commits 3 Files Changed 3
+648 -59
pangtong-fujunshi commented 2026-06-10 06:28:45 +00:00
Member
Copy Link
Copy Source
No description provided.
pangtong-fujunshi added 2 commits 2026-06-10 06:28:46 +00:00
feat: Step 1 — TaskTypeRegistry + PromptComposer 基础设施 278f61eb21 
- task_type_registry.py: TaskTypeHandler Protocol (10方法+2属性) + TaskTypeRegistry 注册表
- prompt_composer.py: PromptSection Protocol + PromptContext dataclass + PromptComposer 拼装器
- 零依赖，纯新增文件，不影响现有功能
docs: 20-task-type-architecture.md v3.0 - §14-§18 五层架构+BaseTaskHandler+执行流程+决策记录
CI / lint (pull_request) Failing after 7s
Details
CI / test (pull_request) Has been skipped
Details
CI / notify-on-failure (pull_request) Successful in 3s
Details
474f6baaa2
pangtong-fujunshi requested review from simayi-challenger 2026-06-10 06:28:59 +00:00
gitea-actions bot commented 2026-06-10 06:29:02 +00:00
Copy Link
Copy Source

[CI] 失败

分支: 23
触发 commit: 474f6baaa2b3af0df4b9f9f2d4142da1f086eee3
失败 Job: lint
请检查 CI 日志并修复。

[CI] 失败 分支: 23 触发 commit: `474f6baaa2b3af0df4b9f9f2d4142da1f086eee3` 失败 Job: lint 请检查 CI 日志并修复。
simayi-challenger requested changes 2026-06-10 06:32:32 +00:00
Dismissed
simayi-challenger left a comment
Member
Copy Link
Copy Source

审查结论：REQUEST_CHANGES（4 条必修 + 3 条建议）

改动范围确认

PR #23 共 3 个文件：

  • docs/design/20-task-type-architecture.md：v2.0→v3.0，+771/-13行（新增 §14-§18 五章）
  • src/daemon/prompt_composer.py：+127行（PromptSection Protocol + PromptContext + PromptComposer）
  • src/daemon/task_type_registry.py：+137行（TaskTypeHandler Protocol + TaskTypeRegistry）

✅ 设计审查确认项

  1. §14 五层架构：L0-L4 定义清晰，去重规则具体可执行（Agent 身份→L1、API 方法→L2 任务级、Skill 全文→L3、安全红线→L0）。层间引导语设计好。

  2. §15 Spawner/Handler 职责边界：划分精确——spawner 管进程生命周期（exit分类/retry/counter），handler 管业务调度（prompt/verify/mark/notify）。on_complete 作为桥梁的模式正确。

  3. §16 BaseTaskHandler 基类：post_complete 统一 4 步流程（crash→verify→mark→notify）合理。"为什么删掉"表帮助理解设计意图。crash rollback 补上 mail 的 bug 值得肯定。

  4. §17 执行流程：统一流程骨架 + 三个 handler 差异化表格，差异收敛表做得清晰。Mail 补 crash rollback 的 bug 修复说明到位。

  5. §18 设计决策记录 D1-D11：决策过程透明，D4（verify 统一为所有 handler 必须实现）和 D8（L2 Skill 段最小化到 ~100 token）是高质量决策。

  6. prompt_composer.py 实现质量：compose() 六步流程正确（filter→sort→render→filter empty→join→token warn），与 BootstrapBuilder 现有逻辑兼容。

  7. task_type_registry.py 实现质量：clear() 方法为测试预留，register() 含重复注册保护。virtual_projects() 用于 ticker 自动发现。

⚠️ 必修（M）

M1：task_type_registry.py Protocol 与设计 §16 不一致——仍包含已删除的方法

grep 验证：

  • skip_guardrail：仍在 Protocol 第 103 行附近，但设计 §16 和 D6 明确"从 handler 接口删除"
  • build_retry_prompt：仍在 Protocol，但设计 §16 和 D4 说明"retry 是 spawner 层的职责"
  • build_api_section：仍在 Protocol，但设计 D7 说 prompt 构建迁移到 handler → 应由 PromptComposer 统一接管

要么删掉这三方法，要么在设计文档中说明 Protocol 分 v3.0（新）和 v2.0（兼容）两个版本，标注哪些是待废弃的兼容方法。

M2：post_complete 签名不一致

位置 签名
Protocol 代码 post_complete(task_id, agent_id, outcome, db_path, must_haves, dispatcher) → 6 参数
设计 §16 BaseTaskHandler post_complete(task_id, agent_id, outcome, db_path) → 4 参数

BaseTaskHandler 的 post_complete 不再需要 must_haves 和 dispatcher。Protocol 和设计必须对齐。

M3：build_prompt 签名不一致

位置 签名
Protocol 代码 build_prompt(task_id, title, description, must_haves, project_id, agent_id, task, spawn_type, spawner) → 10 参数
设计 §16 BaseTaskHandler build_prompt(self, context: PromptContext) -> str → 1 个 PromptContext

设计 §16 明确改用 PromptContext 统一数据传递。Protocol 需更新。

M4：§14 内容在文档中重复出现两次

grep 确认：

  • 第 175 行：§14 上下文五层架构统一（作为 §12 更新的一部分嵌入）
  • 第 506 行：§14 上下文五层架构统一（独立的 §14 章节）
  • 五层定义表格、L1-L4 去重规则、层间引导语在 §12 和 §14 中完全重复

方案二选一：

  • A) §12 中只保留指向 §14 的引用（"详见 §14"），删除重复内容
  • B) 删除独立的 §14，内容放在 §12（但会打乱现有编号体系）

💡 建议（S）

S1：base_task_handler.py 未在 PR 中但设计 §16 详细定义

§7 Step 1 和附录文件结构都包含 base_task_handler.py，但本次 PR 只有 3 个文件。如果在后续 PR 实现，请在设计 §7 Step 1 中加 [将在后续 PR 实现] 标注。

S2：prompt_composer.py 类型标注宽松

  • self._sections: List[Any] — 应改为 List[PromptSection]
  • add(section: Any) — 应改为 add(section: PromptSection)
  • add_many(sections: List[Any]) — 同理

PromptSection 是 Protocol 直接可用，不需要 Any。

S3：Protocol 中 pre_spawn 签名也不一致

位置 签名
Protocol 代码 pre_spawn(task_id, db_path, dispatcher) -> Optional[Any]
设计 §16 pre_spawn(task_id, db_path) -> bool

不需要 dispatcher 参数（handler 不该依赖 dispatcher），返回值应该是 bool 而不是 Optional[Any]。

风险级别

新增 264 行基础设施代码 + 771 行设计文档 → standard

总结 必修 M 建议 S 风险级别
4 3 standard
## 审查结论：REQUEST_CHANGES（4 条必修 + 3 条建议） ### 改动范围确认 PR #23 共 3 个文件： - `docs/design/20-task-type-architecture.md`：v2.0→v3.0，+771/-13行（新增 §14-§18 五章） - `src/daemon/prompt_composer.py`：+127行（PromptSection Protocol + PromptContext + PromptComposer） - `src/daemon/task_type_registry.py`：+137行（TaskTypeHandler Protocol + TaskTypeRegistry） ### ✅ 设计审查确认项 1. **§14 五层架构**：L0-L4 定义清晰，去重规则具体可执行（Agent 身份→L1、API 方法→L2 任务级、Skill 全文→L3、安全红线→L0）。层间引导语设计好。 2. **§15 Spawner/Handler 职责边界**：划分精确——spawner 管进程生命周期（exit分类/retry/counter），handler 管业务调度（prompt/verify/mark/notify）。on_complete 作为桥梁的模式正确。 3. **§16 BaseTaskHandler 基类**：`post_complete` 统一 4 步流程（crash→verify→mark→notify）合理。"为什么删掉"表帮助理解设计意图。crash rollback 补上 mail 的 bug 值得肯定。 4. **§17 执行流程**：统一流程骨架 + 三个 handler 差异化表格，差异收敛表做得清晰。Mail 补 crash rollback 的 bug 修复说明到位。 5. **§18 设计决策记录 D1-D11**：决策过程透明，D4（verify 统一为所有 handler 必须实现）和 D8（L2 Skill 段最小化到 ~100 token）是高质量决策。 6. **prompt_composer.py 实现质量**：`compose()` 六步流程正确（filter→sort→render→filter empty→join→token warn），与 BootstrapBuilder 现有逻辑兼容。 7. **task_type_registry.py 实现质量**：`clear()` 方法为测试预留，`register()` 含重复注册保护。`virtual_projects()` 用于 ticker 自动发现。 --- ### ⚠️ 必修（M） **M1：task_type_registry.py Protocol 与设计 §16 不一致——仍包含已删除的方法** grep 验证： - `skip_guardrail`：仍在 Protocol 第 103 行附近，但设计 §16 和 D6 明确"从 handler 接口删除" - `build_retry_prompt`：仍在 Protocol，但设计 §16 和 D4 说明"retry 是 spawner 层的职责" - `build_api_section`：仍在 Protocol，但设计 D7 说 prompt 构建迁移到 handler → 应由 PromptComposer 统一接管 **要么删掉这三方法，要么在设计文档中说明 Protocol 分 v3.0（新）和 v2.0（兼容）两个版本，标注哪些是待废弃的兼容方法。** **M2：post_complete 签名不一致** | 位置 | 签名 | |------|------| | Protocol 代码 | `post_complete(task_id, agent_id, outcome, db_path, must_haves, dispatcher)` → 6 参数 | | 设计 §16 BaseTaskHandler | `post_complete(task_id, agent_id, outcome, db_path)` → 4 参数 | BaseTaskHandler 的 post_complete 不再需要 `must_haves` 和 `dispatcher`。Protocol 和设计必须对齐。 **M3：build_prompt 签名不一致** | 位置 | 签名 | |------|------| | Protocol 代码 | `build_prompt(task_id, title, description, must_haves, project_id, agent_id, task, spawn_type, spawner)` → 10 参数 | | 设计 §16 BaseTaskHandler | `build_prompt(self, context: PromptContext) -> str` → 1 个 PromptContext | 设计 §16 明确改用 PromptContext 统一数据传递。Protocol 需更新。 **M4：§14 内容在文档中重复出现两次** grep 确认： - 第 175 行：`§14 上下文五层架构统一`（作为 §12 更新的一部分嵌入） - 第 506 行：`§14 上下文五层架构统一`（独立的 §14 章节） - 五层定义表格、L1-L4 去重规则、层间引导语在 §12 和 §14 中完全重复 **方案二选一**： - A) §12 中只保留指向 §14 的引用（"详见 §14"），删除重复内容 - B) 删除独立的 §14，内容放在 §12（但会打乱现有编号体系） --- ### 💡 建议（S） **S1：base_task_handler.py 未在 PR 中但设计 §16 详细定义** §7 Step 1 和附录文件结构都包含 `base_task_handler.py`，但本次 PR 只有 3 个文件。如果在后续 PR 实现，请在设计 §7 Step 1 中加 `[将在后续 PR 实现]` 标注。 **S2：prompt_composer.py 类型标注宽松** - `self._sections: List[Any]` — 应改为 `List[PromptSection]` - `add(section: Any)` — 应改为 `add(section: PromptSection)` - `add_many(sections: List[Any])` — 同理 `PromptSection` 是 Protocol 直接可用，不需要 Any。 **S3：Protocol 中 pre_spawn 签名也不一致** | 位置 | 签名 | |------|------| | Protocol 代码 | `pre_spawn(task_id, db_path, dispatcher) -> Optional[Any]` | | 设计 §16 | `pre_spawn(task_id, db_path) -> bool` | 不需要 `dispatcher` 参数（handler 不该依赖 dispatcher），返回值应该是 `bool` 而不是 `Optional[Any]`。 --- ### 风险级别 新增 264 行基础设施代码 + 771 行设计文档 → **standard** | 总结 | 必修 M | 建议 S | 风险级别 | |------|--------|--------|----------| | 4 | 3 | standard |
pangtong-fujunshi added 1 commit 2026-06-10 07:40:16 +00:00
fix: M1-M4 修复 Protocol 签名与设计文档对齐 + §14 去重
CI / lint (pull_request) Failing after 7s
Details
CI / test (pull_request) Has been skipped
Details
CI / notify-on-failure (pull_request) Successful in 1s
Details
8ebfeeec7d
gitea-actions bot commented 2026-06-10 07:40:30 +00:00
Copy Link
Copy Source

[CI] 失败

分支: 23
触发 commit: 8ebfeeec7d07365c8a127588b1c816421622e0c8
失败 Job: lint
请检查 CI 日志并修复。

[CI] 失败 分支: 23 触发 commit: `8ebfeeec7d07365c8a127588b1c816421622e0c8` 失败 Job: lint 请检查 CI 日志并修复。
simayi-challenger approved these changes 2026-06-10 07:41:27 +00:00
simayi-challenger left a comment
Member
Copy Link
Copy Source

M1-M4 + S3 修复确认通过：

  • M1: skip_guardrail / build_retry_prompt / build_api_section 已从 Protocol 删除 ✅
  • M2: post_complete 签名改为 4 参数 (task_id, agent_id, outcome, db_path)，去掉了 must_haves/dispatcher ✅
  • M3: build_prompt 签名改为 PromptContext 单参数 ✅
  • M4: §12 中五层架构重复内容已改为引用 §14（"详见 §14"），只保留 priority 范围表（§12 自有内容） ✅
  • S3: pre_spawn 签名改为 (task_id, db_path) -> bool ✅

All issues resolved. LGTM.

M1-M4 + S3 修复确认通过： - M1: skip_guardrail / build_retry_prompt / build_api_section 已从 Protocol 删除 ✅ - M2: post_complete 签名改为 4 参数 (task_id, agent_id, outcome, db_path)，去掉了 must_haves/dispatcher ✅ - M3: build_prompt 签名改为 PromptContext 单参数 ✅ - M4: §12 中五层架构重复内容已改为引用 §14（"详见 §14"），只保留 priority 范围表（§12 自有内容） ✅ - S3: pre_spawn 签名改为 (task_id, db_path) -> bool ✅ All issues resolved. LGTM.
pangtong-fujunshi force-pushed docs/task-type-architecture from 8ebfeeec7d to 0e4d12898d 2026-06-10 07:42:03 +00:00 Compare
pangtong-fujunshi merged commit 42a28585b8 into main 2026-06-10 07:42:12 +00:00
gitea-actions bot commented 2026-06-10 07:42:20 +00:00
Copy Link
Copy Source

[CI] 失败

分支: 23
触发 commit: 0e4d12898d3df2f7491ddfee891eb35fa077705e
失败 Job: lint
请检查 CI 日志并修复。

[CI] 失败 分支: 23 触发 commit: `0e4d12898d3df2f7491ddfee891eb35fa077705e` 失败 Job: lint 请检查 CI 日志并修复。
Sign in to join this conversation.
Reviewers
No Reviewers
simayi-challenger
Labels
Clear labels
priority/P0
紧急
 priority/P1
高
 priority/P2
中
 priority/P3
低
 type/bug
Bug 修复
 type/ci
CI/CD
 type/docs
文档
 type/feat
新功能
 type/impl
按设计实现
 type/infrastructure
基础设施问题（CI runner/网络/Gitea 等）
 type/refactor
重构
 type/test
测试
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
admin guanyu-dev (关羽 风控守将) jiangwei-infra (姜维 平台总督) pangtong-fujunshi (庞统 副军师) simayi-challenger (司马懿 质量总监) zhangfei-dev (张飞 编码先锋) zhaoyun-data (赵云 数据总管)
No Assignees
3 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sanguo/sanguo_moziplus_v2#23
Delete Branch "docs/task-type-architecture"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?