fix: mention 重复投递 + mail 失败通知竞态保护 + §14 设计文档同步

Bug 1: spawn_full_agent use_main_session 返回 None 导致 mention 重复投递
- 根因: use_main_session=True 时 session_id=None, return None 被 ticker
  _process_posts 误判为 spawn 失败, 每次 tick 都重试
- 修复: 引入 effective_sid = session_id or 'main', 统一用于
  _register_session / _monitor_process / return value

Bug 2: _mark_task failed 时未检查已完成状态导致误发投递失败通知
- 根因: spawner 标 failed 和 handler 标 done 竞态条件下, 已完成的
  mail task 被误发投递失败通知
- 修复: notify_mail_failed 调用前加防御性检查, 若 task 已 done 则跳过

设计文档: §13 三个 handler sections 列表同步 DeliveryChecklistSection
  及 GiteaConventionSection / WikiGuideSection, 更新 section 复用分析表
  及文件结构 section 计数

docs/design/14-task-type-architecture.md

@@ -585,6 +585,18 @@ class PromptComposer:
 | 50-59 | 硬约束 | 安全红线、禁止行为 |
 | 60-69 | 扩展段 | 保留给未来使用 |
 
+## 共性 Section（三 handler 共享）
+
+以下三个 Section 在 `prompt_composer.py` 中统一定义，被 Task/Mail/Toolchain 三个 handler 共同注入：
+
+| Section | priority | 用途 |
+|---------|----------|------|
+| `GiteaConventionSection` | 55 | Gitea Issue/PR 标题规范、分支命名、提交格式 |
+| `DeliveryChecklistSection` | 55 | 交付前检查清单（产出格式、验证项、必读文档） |
+| `WikiGuideSection` | 60 | Wiki 知识库检索指引（检索路径、优先级、知识缺口记录） |
+
+设计意图：将跨 handler 的共性约束从各 handler 的 ConstraintsSection 中抽离，避免重复维护。
+
 ---
 
 # §13 三个 Handler 的 Section 注册
@@ -601,6 +613,9 @@ def get_sections(self) -> list[PromptSection]:
         RoleSkillSection(priority=30),         # BootstrapBuilder 段 3（Skill 全文）
         TaskApiSection(priority=40),           # API 操作指令，success_status="review"
         TaskConstraintsSection(priority=50),   # 硬约束
+        GiteaConventionSection(priority=55),   # Gitea 协作规范（共性）
+        WikiGuideSection(priority=60),         # Wiki 知识库检索指引（共性）
+        DeliveryChecklistSection(priority=55), # 交付检查清单（共性）
     ]
 ```
 
@@ -611,6 +626,9 @@ def get_sections(self) -> list[PromptSection]:
 | RoleSkillSection | BootstrapBuilder 段 3 | 个性：只有 task 读 Skill 全文 |
 | TaskApiSection | spawner `_build_api_section` | **共性基础 + 个性参数**（success_status） |
 | TaskConstraintsSection | BootstrapBuilder 段 4 | 个性：每种 task 约束不同 |
+| GiteaConventionSection | prompt_composer.py | **共性**：Gitea Issue/PR 规范 |
+| WikiGuideSection | prompt_composer.py | **共性**：Wiki 检索指引 |
+| DeliveryChecklistSection | prompt_composer.py | **共性**：交付前检查清单 |
 
 ## MailHandler sections
 
@@ -620,6 +638,9 @@ def get_sections(self) -> list[PromptSection]:
         MailContextSection(priority=10),       # from/to/title/text，区分 inform/request
         MailApiSection(priority=40),           # API 操作指令，success_status="done"
         MailConstraintsSection(priority=50),   # 硬约束（禁止状态转换命令等）
+        GiteaConventionSection(priority=55),   # Gitea 协作规范（共性）
+        WikiGuideSection(priority=60),         # Wiki 知识库检索指引（共性）
+        DeliveryChecklistSection(priority=55), # 交付检查清单（共性）
     ]
 ```
 
@@ -628,6 +649,9 @@ def get_sections(self) -> list[PromptSection]:
 | MailContextSection | MAIL_INFORM_TEMPLATE / MAIL_REQUEST_TEMPLATE | 个性：邮件格式 |
 | MailApiSection | spawner `_build_api_section` 变体 | **共性基础 + 个性参数**（success_status="done"，含 Mail API 指令） |
 | MailConstraintsSection | 模板中的 ⚠️ 约束 | 个性 |
+| GiteaConventionSection | prompt_composer.py | **共性**：Gitea Issue/PR 规范 |
+| WikiGuideSection | prompt_composer.py | **共性**：Wiki 检索指引 |
+| DeliveryChecklistSection | prompt_composer.py | **共性**：交付前检查清单 |
 
 ## ToolchainHandler sections
 
@@ -637,6 +661,9 @@ def get_sections(self) -> list[PromptSection]:
         ToolchainContextSection(priority=10),  # 事件类型 + 事件详情
         ToolchainApiSection(priority=40),      # API 操作指令，success_status="done"
         ToolchainConstraintsSection(priority=50),  # 硬约束
+        GiteaConventionSection(priority=55),   # Gitea 协作规范（共性）
+        WikiGuideSection(priority=60),         # Wiki 知识库检索指引（共性）
+        DeliveryChecklistSection(priority=55), # 交付检查清单（共性）
     ]
 ```
 
@@ -645,6 +672,9 @@ def get_sections(self) -> list[PromptSection]:
 | ToolchainContextSection | toolchain_templates.py + md 文件 | 个性：事件格式 |
 | ToolchainApiSection | spawner `_build_api_section` 变体 | **共性基础 + 个性参数** |
 | ToolchainConstraintsSection | 新增 | 个性 |
+| GiteaConventionSection | prompt_composer.py | **共性**：Gitea Issue/PR 规范 |
+| WikiGuideSection | prompt_composer.py | **共性**：Wiki 检索指引 |
+| DeliveryChecklistSection | prompt_composer.py | **共性**：交付前检查清单 |
 
 ## Section 复用分析
 
@@ -655,6 +685,9 @@ def get_sections(self) -> list[PromptSection]:
 | *ConstraintsSection | ✅ | ✅ | ✅ | ❌ 约束内容不同，各自实现 |
 | PriorOutputsSection | ✅ | ❌ | ❌ | 仅 task |
 | RoleSkillSection | ✅ | ❌ | ❌ | 仅 task |
+| GiteaConventionSection | ✅ | ✅ | ✅ | **共性**：三 handler 共享，prompt_composer.py 定义 |
+| WikiGuideSection | ✅ | ✅ | ✅ | **共性**：三 handler 共享，prompt_composer.py 定义 |
+| DeliveryChecklistSection | ✅ | ✅ | ✅ | **共性**：三 handler 共享，prompt_composer.py 定义 |
 
 **结论**：ApiSection 可以抽一个 BaseApiSection（curl 模板 + success_status 参数），其余 section 各自实现。
 
@@ -667,9 +700,9 @@ src/daemon/
 ├── task_type_registry.py    # §3 + §4：Protocol + Registry
 ├── prompt_composer.py        # §12 PromptSection + PromptContext + PromptComposer
 ├── base_task_handler.py      # §16 BaseTaskHandler 基类
-├── task_handler.py           # §13 TaskHandler（继承 BaseTaskHandler）+ 5 sections
-├── mail_handler.py           # §13 MailHandler（继承 BaseTaskHandler）+ 3 sections
-├── toolchain_handler.py      # §13 ToolchainHandler（继承 BaseTaskHandler）+ 3 sections
+├── task_handler.py           # §13 TaskHandler（继承 BaseTaskHandler）+ 8 sections
+├── mail_handler.py           # §13 MailHandler（继承 BaseTaskHandler）+ 6 sections
+├── toolchain_handler.py      # §13 ToolchainHandler（继承 BaseTaskHandler）+ 6 sections
 ├── dispatcher.py             # §6 改动
 ├── spawner.py                # §6 改动
 ├── ticker.py                 # §6 改动

src/daemon/mail_handler.py

@@ -9,7 +9,7 @@ import logging
 from pathlib import Path
 
 from src.daemon.base_task_handler import BaseTaskHandler, VerifyResult
-from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection
+from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection, DeliveryChecklistSection
 from src.blackboard.db import get_connection
 
 logger = logging.getLogger("moziplus-v2.handler.mail")
@@ -36,7 +36,7 @@ class MailHandler(BaseTaskHandler):
         return composer.compose(context)
 
     def get_sections(self) -> list:
-        return [MailContextSection(), MailApiSection(), MailConstraintsSection(), GiteaConventionSection(), WikiGuideSection()]
+        return [MailContextSection(), MailApiSection(), MailConstraintsSection(), GiteaConventionSection(), WikiGuideSection(), DeliveryChecklistSection()]
 
     def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult:
         """Mail 完成验证：区分 inform/request。

src/daemon/prompt_composer.py

@@ -174,3 +174,27 @@ class WikiGuideSection:
 
     def should_include(self, context: "PromptContext") -> bool:
         return True
+
+
+# ---------------------------------------------------------------------------
+# DeliveryChecklistSection — 交付检查清单
+# ---------------------------------------------------------------------------
+class DeliveryChecklistSection:
+    """交付检查清单 — 提醒 Agent 完成前同步关联成果物。"""
+
+    name: str = "delivery_checklist"
+    priority: int = 55  # CONSTRAINTS(50) 和 EXTENSION(60) 之间
+
+    CHECKLIST_TEXT = (
+        "## 交付检查\n"
+        "完成代码改动前确认：\n"
+        "- 改了实现 → docs/design/ 对应设计文档是否需要更新\n"
+        "- 改了实现 → tests/ 是否有对应测试脚本需要更新\n"
+        "- 所有成果物变更通过 PR 流程：PR review 把关设计合理性，CI 把关代码质量，CD 把关部署正确性\n"
+    )
+
+    def render(self, context: "PromptContext") -> str:
+        return self.CHECKLIST_TEXT
+
+    def should_include(self, context: "PromptContext") -> bool:
+        return True

src/daemon/spawner.py

@@ -625,19 +625,24 @@ curl -X POST http://{self.api_host}:{self.api_port}/api/projects/{project_id}/ta
                 stdout=asyncio.subprocess.PIPE,
                 stderr=asyncio.subprocess.PIPE,
             )
-            self._register_session(session_id, agent_id, task_id, proc.pid,
+            # use_main_session=True 时 session_id 为 None,但 _register_session 和
+            # _monitor_process 需要一个非 None 的 key;同时 ticker 等调用方用
+            # `result is not None` 判断 spawn 是否成功,返回 None 会被误判为失败。
+            # 统一用 "main" 作为占位标识。
+            effective_sid = session_id or "main"
+            self._register_session(effective_sid, agent_id, task_id, proc.pid,
                                    broadcast_task_ids=broadcast_task_ids)
             logger.info("Spawned agent %s (session=%s, pid=%d)",
-                        agent_id, session_id, proc.pid)
+                        agent_id, effective_sid, proc.pid)
 
             # Schedule monitor(传 wrapped_on_complete)
             asyncio.create_task(
-                self._monitor_process(session_id, proc, agent_id, task_id,
+                self._monitor_process(effective_sid, proc, agent_id, task_id,
                                       on_complete=_wrapped_on_complete,
                                       db_path=task_db_path or self.db_path)
             )
 
-            return session_id
+            return effective_sid
 
         except Exception as e:
             # spawn 失败也要 release counter
@@ -1949,6 +1954,19 @@ curl -X POST http://{api_host}:{api_port}/api/projects/{project_id}/tasks/{task_
                 try:
                     from src.daemon.mail_notify import _is_mail_project, notify_mail_failed
                     if _is_mail_project(db_path):
+                        # 防御性检查：如果 task 已经 done，不触发失败通知（竞态保护）
+                        # 场景：spawner 标 failed 和 handler 标 done 同时发生
+                        try:
+                            conn2 = get_connection(db_path)
+                            current_status = conn2.execute(
+                                "SELECT status FROM tasks WHERE id=?", (task_id,)
+                            ).fetchone()
+                            conn2.close()
+                            if current_status and current_status["status"] == "done":
+                                logger.info("Task %s already done, skipping mail failure notification", task_id)
+                                return
+                        except Exception:
+                            pass
                         # Mail 失败：通知发件人，不 @pangtong
                         notify_mail_failed(db_path, task_id, reason, detail)
                     else:

src/daemon/task_handler.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from typing import Dict, Optional
 
 from src.daemon.base_task_handler import BaseTaskHandler, VerifyResult
-from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection
+from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection, DeliveryChecklistSection
 from src.blackboard.db import get_connection
 
 logger = logging.getLogger("moziplus-v2.handler")
@@ -315,6 +315,7 @@ class TaskHandler(BaseTaskHandler):
             TaskConstraintsSection(),
             GiteaConventionSection(),
             WikiGuideSection(),
+            DeliveryChecklistSection(),
         ]
 
     def build_prompt(self, context: PromptContext) -> str:

src/daemon/toolchain_handler.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from typing import Dict, List
 
 from src.daemon.base_task_handler import BaseTaskHandler, VerifyResult
-from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection
+from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection, DeliveryChecklistSection
 from src.daemon.toolchain_templates import render_template, _TEMPLATE_MAP
 from src.blackboard.db import get_connection
 
@@ -51,17 +51,41 @@ class ToolchainContextSection:
     name: str = "toolchain_context"
     priority: int = 10
 
+    EVENT_LABELS_ZH: Dict[str, str] = {
+        "review_request": "Review 请求",
+        "review_result": "Review 结果",
+        "review_merged": "PR 合并",
+        "review_comment": "Review 评论",
+        "review_updated": "Review 更新",
+        "ci_failure": "CI 失败",
+        "deploy_failure": "部署失败",
+        "issue_assigned": "Issue 指派",
+        "mention": "@提及",
+    }
+
     def render(self, context: PromptContext) -> str:
         event_type = context.event_type
         event_data: Dict = context.event_data or {}
 
+        # 事件类型中文标签
+        event_label = self.EVENT_LABELS_ZH.get(event_type, event_type or '未知')
+
+        # from / to 信息
+        to_agent = context.agent_id or ''
+        from_agent = 'system'
+
         # Part 1: 事件信息(现有模板引擎)
         if event_type in _TEMPLATE_MAP:
             variables = {k: str(v) for k, v in event_data.items()}
             event_text = render_template(event_type, variables)
+            # 补充事件类型中文标签 + from/to
+            header = f"- **事件类型**: {event_label}\n- **来源**: {from_agent}\n- **指派**: {to_agent}\n"
+            event_text = header + "\n" + event_text
         else:
             lines = ["## 工具链事件", ""]
-            lines.append(f"- **事件类型**: {event_type or '未知'}")
+            lines.append(f"- **事件类型**: {event_label}")
+            lines.append(f"- **来源**: {from_agent}")
+            lines.append(f"- **指派**: {to_agent}")
             if event_data:
                 lines.append("- **事件详情**:")
                 for key, value in event_data.items():
@@ -228,6 +252,7 @@ class ToolchainHandler(BaseTaskHandler):
             ToolchainConstraintsSection(),
             GiteaConventionSection(),
             WikiGuideSection(),
+            DeliveryChecklistSection(),
         ]
 
     def build_prompt(self, context: PromptContext) -> str:

src/frontend/src/components/ToolchainPanel.tsx

@@ -4,6 +4,28 @@
  */
 import { useEffect, useState } from 'react';
 
+const AGENT_NAMES: Record<string, string> = {
+  'pangtong-fujunshi': '庞统',
+  'simayi-challenger': '司马懿',
+  'zhangfei-dev': '张飞',
+  'guanyu-dev': '关羽',
+  'zhaoyun-data': '赵云',
+  'jiangwei-infra': '姜维',
+  'system': '系统',
+};
+
+const EVENT_LABELS: Record<string, string> = {
+  'review_request': 'Review 请求',
+  'review_result': 'Review 结果',
+  'review_merged': 'PR 合并',
+  'review_comment': 'Review 评论',
+  'review_updated': 'Review 更新',
+  'ci_failure': 'CI 失败',
+  'deploy_failure': '部署失败',
+  'issue_assigned': 'Issue 指派',
+  'mention': '@提及',
+};
+
 const STATUS_COLORS: Record<string, string> = {
   pending: '#f59e0b22', claimed: '#6a9eff22', working: '#6a9eff22',
   review: '#818cf822', done: '#2ecc8a22', failed: '#ef444422',
@@ -36,6 +58,7 @@ export default function ToolchainPanel() {
   const [detail, setDetail] = useState<any>(null);
   const [searchQuery, setSearchQuery] = useState('');
   const [loading, setLoading] = useState(false);
+  const [filterMode, setFilterMode] = useState<'all' | 'pending'>('all');
 
   const loadTasks = async (q?: string) => {
     setLoading(true);
@@ -52,6 +75,10 @@ export default function ToolchainPanel() {
     setLoading(false);
   };
 
+  const displayed = filterMode === 'pending'
+    ? tasks.filter(t => !['done', 'failed', 'cancelled'].includes(t.status))
+    : tasks;
+
   useEffect(() => { loadTasks(); }, []);
 
   // 搜索防抖 300ms
@@ -120,7 +147,19 @@ export default function ToolchainPanel() {
             padding: '3px 8px', borderRadius: 4, fontSize: 10,
             border: '1px solid #2a3550', background: '#161b2e', color: '#8899aa', cursor: 'pointer',
           }}>🔄</button>
-          <span style={{ fontSize: 10, color: 'var(--muted)' }}>{tasks.length} 条</span>
+          <button onClick={() => setFilterMode('all')} style={{
+            padding: '3px 8px', borderRadius: 4, fontSize: 10,
+            border: `1px solid ${filterMode === 'all' ? 'var(--acc)' : '#2a3550'}`,
+            background: filterMode === 'all' ? 'var(--acc)22' : '#161b2e',
+            color: filterMode === 'all' ? 'var(--acc)' : '#8899aa', cursor: 'pointer',
+          }}>全部</button>
+          <button onClick={() => setFilterMode('pending')} style={{
+            padding: '3px 8px', borderRadius: 4, fontSize: 10,
+            border: `1px solid ${filterMode === 'pending' ? 'var(--acc)' : '#2a3550'}`,
+            background: filterMode === 'pending' ? 'var(--acc)22' : '#161b2e',
+            color: filterMode === 'pending' ? 'var(--acc)' : '#8899aa', cursor: 'pointer',
+          }}>未处理</button>
+          <span style={{ fontSize: 10, color: 'var(--muted)' }}>{filterMode === 'pending' ? displayed.length : tasks.length} 条</span>
         </div>
 
         {/* 事件列表 */}
@@ -130,7 +169,7 @@ export default function ToolchainPanel() {
               {loading ? '加载中...' : '暂无工具链事件'}
             </div>
           )}
-          {tasks.map((t: any) => (
+          {displayed.map((t: any) => (
             <div key={t.id} onClick={() => setSelectedId(t.id)} style={{
               padding: '10px 14px', borderBottom: '1px solid var(--line)',
               cursor: 'pointer', transition: 'background .15s',
@@ -151,6 +190,9 @@ export default function ToolchainPanel() {
                 fontSize: 12, fontWeight: 500, color: '#dde4f8',
                 overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
               }}>{t.title}</div>
+              <div style={{ fontSize: 10, color: 'var(--muted)', marginTop: 2 }}>
+                {AGENT_NAMES['system'] || '系统'} → {AGENT_NAMES[t.assignee] || t.assignee || '?'}
+              </div>
             </div>
           ))}
         </div>
@@ -174,6 +216,9 @@ export default function ToolchainPanel() {
                 <span style={{ fontSize: 10, color: 'var(--muted)' }}>{detail.id}</span>
               </div>
               <div style={{ fontSize: 18, fontWeight: 700, lineHeight: 1.3 }}>{detail.title}</div>
+              <div style={{ fontSize: 11, color: 'var(--muted)', marginTop: 4 }}>
+                {AGENT_NAMES['system'] || '系统'} → {AGENT_NAMES[detail.assignee] || detail.assignee || '?'}
+              </div>
               <div style={{ fontSize: 12, color: 'var(--muted)', marginTop: 6 }}>
                 {fmtTime(detail.created_at)}
               </div>