[moz] docs: 重写 §26 Gitea 协作规范设计（流水账→设计文档风格）

- §26 从落地流水账重写为正式设计文档
- 新增 26.1 设计目标（三个问题 + 目标）
- 新增 26.2 规范设计（标题规范/Label 体系/模板，含设计决策）
- 新增 26.3 执行机制（四层注入 + L2 priority 设计理由）
- 新增 26.4 Label 迁移策略（旧标签保留，不做批量迁移）
- 新增 26.5 与其他章节的交叉引用关系
- 保留 26.6 实现记录（压缩为记录而非主体）
- §4.5 末尾加交叉引用指向 §26
- P3 色值从 #c5def5 改为 #cfd3d7（解决与 type/impl 混淆）

.gitea/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,34 @@
+name: Bug 报告
+about: 报告一个 Bug
+title: "[moz] bug: "
+labels:
+  - type/bug
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug 描述
+      description: 清晰描述什么行为是错误的
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: 复现步骤
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 预期行为
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: 优先级
+      options:
+        - P0 紧急
+        - P1 高
+        - P2 中
+        - P3 低

.gitea/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,27 @@
+name: 功能需求
+about: 提出一个新功能需求
+title: "[moz] feat: "
+labels:
+  - type/feat
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: 需求描述
+      description: 你希望实现什么功能？为什么需要？
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: 建议方案
+      description: 如果有初步想法可以写 here
+  - type: dropdown
+    id: priority
+    attributes:
+      label: 优先级
+      options:
+        - P0 紧急
+        - P1 高
+        - P2 中
+        - P3 低

.gitea/ISSUE_TEMPLATE/test.yml

@@ -0,0 +1,20 @@
+name: 测试任务
+about: 创建一个测试任务（E2E、集成测试等）
+title: "[moz] test: "
+labels:
+  - type/test
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: 测试目标
+      description: 要验证什么场景？
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: 测试步骤
+      description: 关键步骤或验收标准
+    validations:
+      required: true

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## 改动概述
+
+<!-- 一句话说明这个 PR 做了什么 -->
+
+## 关联 Issue
+
+<!-- #issue_number，如果没有关联可删掉 -->
+
+## 改动类型
+
+- [ ] feat: 新功能
+- [ ] impl: 实现
+- [ ] fix: 修复
+- [ ] docs: 文档
+- [ ] test: 测试
+- [ ] refactor: 重构
+- [ ] ci: CI/CD
+- [ ] chore: 杂项
+
+## 检查清单
+
+- [ ] 标题格式正确：`[代号] type(scope): 简述`
+- [ ] 改动在开发目录（`~/.openclaw/sanguo_projects/`）完成
+- [ ] 已同步到安装目录（`~/.sanguo_projects/`）
+- [ ] 已运行测试（如适用）
+- [ ] 已更新相关设计文档（如适用）

docs/design/13-toolchain-and-dev-workflow.md

@@ -245,11 +245,14 @@ pm2 show sanguo-act-runner      # 详情
 |------|------|
 | `feat` | 新功能 |
 | `fix` | Bug 修复 |
+| `impl` | 按设计文档实现 |
 | `refactor` | 重构（不改行为） |
 | `test` | 测试相关 |
 | `docs` | 文档 |
 | `chore` | 构建/工具/配置 |
 
+sanguo 组织所有仓库统一使用此 commit 规范。
+
 ---
 
 ## §4. 问题管理
@@ -266,15 +269,19 @@ pm2 show sanguo-act-runner      # 详情
 
 ### 4.2 Issue 标签体系
 
-| 标签 | 颜色 | 说明 |
-|------|------|------|
-| `bug` | 红 | 功能异常 |
-| `feature` | 蓝 | 新功能需求 |
-| `improvement` | 绿 | 改进优化 |
-| `security` | 橙 | 安全相关 |
-| `risk:high/standard/low` | 分级色 | 风险级别（见 §6.1 判定规则） |
-| `priority:high/medium/low` | 黄/灰 | 优先级 |
-| `blocked` | 紫 | 阻塞中 |
+| 标签 | 颜色 | 色值 | 说明 |
+|------|------|------|------|
+| `type/bug` | 红 | #ee0701 | Bug 修复 |
+| `type/feat` | 蓝 | #84b6eb | 新功能 |
+| `type/impl` | 浅蓝 | #c5def5 | 按设计实现 |
+| `type/docs` | 黄 | #fbca04 | 文档 |
+| `type/test` | 绿 | #0e8a16 | 测试 |
+| `type/ci` | 紫 | #d4c5f9 | CI/CD |
+| `type/refactor` | 橙 | #ff6f00 | 重构 |
+| `priority/P0` | 深红 | #b60205 | 紧急 |
+| `priority/P1` | 红 | #d93f0b | 高 |
+| `priority/P2` | 黄 | #fbca04 | 中 |
+| `priority/P3` | 浅蓝 | #c5def5 | 低 |
 
 ### 4.3 需求/问题 Review 前置
 
@@ -296,6 +303,29 @@ Open → In Progress → Review → Closed
   └──── Reopened ←───────────────────┘
 ```
 
+### 4.5 标题规范
+
+所有 Issue 和 PR 标题**必须**包含项目代号前缀，让人类一眼识别项目+类型：
+
+**Issue**: `[代号] type: 简述`
+**PR**: `[代号] type(scope): 简述`
+
+项目代号：
+
+| 仓库 | 代号 |
+|------|------|
+| sanguo_moziplus_v2 | moz |
+| sanguo_quant_live | quant |
+| sanguo_vnpy | vnpy |
+
+示例：
+- `[moz] bug: Mail API 500 when comment_type invalid`
+- `[moz] impl(daemon): 知识注入 L2 引擎层 — WikiGuideSection`
+- `[quant] feat: 趋势跟踪策略骨架`
+
+此规范通过 L2 引擎层 `GiteaConventionSection`（priority=55）自动注入所有 Agent prompt。
+完整规范文档：L3 Skill `gitea-conventions`。规范设计原理详见 [§26](#26-gitea-协作规范设计)。
+
 ---
 
 ## §5. CI/CD 管道设计
@@ -3297,3 +3327,120 @@ async def _handle_issue_comment(payload):
 |------|------|------|
 | 2026-06-09 | v1.0 | 初版：E2E 真实场景暴露问题 → 四层改造方案 + @mention 通知 + Mail type 改造 |
 
+---
+
+## §26. Gitea 协作规范设计
+
+> **状态**: ✅ 已实现（PR #69）
+> **日期**: 2026-06-14
+
+### 26.1 设计目标
+
+团队三个仓库（moziplus_v2 / quant_live / vnpy）在 Gitea 上独立存在，协作时存在三个问题：
+
+1. **标题不可辨识**：`Fix mail API` 看不出是哪个项目、什么类型的改动
+2. **Label 缺失**：无统一标签体系，无法按类型/优先级筛选
+3. **填写无约束**：Issue/PR 内容格式随意，审查时缺少关键信息
+
+本规范的目标：让人类一眼识别项目+类型，让 Agent 可程序化遵循，让模板降低填写门槛。
+
+### 26.2 规范设计
+
+#### 26.2.1 标题规范
+
+**规则**：所有 Issue/PR 标题必须包含项目代号前缀。
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| Issue | `[代号] type: 简述` | `[moz] bug: Mail API 500 when comment_type invalid` |
+| PR | `[代号] type(scope): 简述` | `[moz] impl(daemon): WikiGuideSection 注入` |
+
+**项目代号**：moz=moziplus_v2, quant=quant_live, vnpy=vnpy
+
+**type 清单**：bug / feat / impl / fix / docs / test / ci / refactor / chore
+
+**设计决策**：
+- 为什么用代号前缀而不是靠仓库隔离？— 团队成员同时在多仓库协作，通知列表（Mail、Gitea dashboard）混合展示时代号前缀提供即时辨识。仓库隔离解决不了跨仓库视图的辨识问题
+- PR 加 `scope` 是因为 PR 通常涉及具体模块（daemon / api / frontend），Issue 不需要
+
+#### 26.2.2 Label 体系
+
+采用 `type/*` + `priority/*` 双命名空间，替代旧标签（bug/feature/improvement/security）：
+
+| 标签 | 色值 | 说明 |
+|------|------|------|
+| `type/bug` | #ee0701 | Bug 修复 |
+| `type/feat` | #84b6eb | 新功能 |
+| `type/impl` | #c5def5 | 按设计实现 |
+| `type/docs` | #fbca04 | 文档 |
+| `type/test` | #0e8a16 | 测试 |
+| `type/ci` | #d4c5f9 | CI/CD |
+| `type/refactor` | #ff6f00 | 重构 |
+| `priority/P0` | #b60205 | 紧急 |
+| `priority/P1` | #d93f0b | 高 |
+| `priority/P2` | #fbca04 | 中 |
+| `priority/P3` | #cfd3d7 | 低 |
+
+**设计决策**：
+- 用 `type/` `priority/` 命名空间而非扁平命名，避免标签膨胀时冲突，且在 Gitea UI 中按前缀分组显示
+- type 用暖色系（红/橙/黄），priority 用冷→热渐变（灰→蓝→黄→红），视觉上两类标签不混淆
+- ⚠️ 已知问题：`type/impl`(#c5def5) 与 `priority/P3` 色值相近。P3 已调整为灰色 #cfd3d7 以区分
+
+#### 26.2.3 Issue/PR 模板
+
+**Issue 模板**（3 种）：bug.yml / feature.yml / test.yml
+
+覆盖决策：只做最高频的 3 种类型（bug 报告、功能需求、测试任务），其余类型（docs/ci/refactor）频率低，走自由创建。每种模板包含描述、复现/方案、优先级字段。
+
+**PR 模板**（1 种）：PULL_REQUEST_TEMPLATE.md
+
+改动类型 checklist + 检查清单（标题格式、开发→安装目录同步、测试、设计文档更新）。
+
+### 26.3 执行机制
+
+规范通过四层路径保证执行，每层职责不同：
+
+| 层 | 载体 | 职责 | Token 成本 |
+|----|------|------|-----------|
+| **L1** | TOOLS.md（Agent workspace） | 代号表 + 格式速查，Agent 静态可见 | ~100 |
+| **L2** | `GiteaConventionSection`（priority=55） | 每次 spawn 动态注入，提醒标题格式 | ~80 |
+| **L3** | `gitea-conventions` Skill（extraDirs） | 完整规范（标题/分支/commit/label），Agent 按需加载 | 按需 |
+| **Gitea** | Issue/PR Template + Label（仓库级） | 人类创建时表单引导，标签选择 | — |
+
+**L2 设计决策**：
+- `GiteaConventionSection` priority=55，排在 Constraints(50) 之后、Extension(60) 之前。标题规范属于约束类，但优先级低于安全/流程约束
+- 注入所有 handler（Task/Toolchain/Mail），因为任何 handler 都可能创建 Issue/PR
+- ⚠️ L1 文件在各 Agent workspace（`~/.openclaw/workspace-*/TOOLS.md`），不在仓库管理。Agent workspace 变更不通过 PR
+
+### 26.4 Label 迁移策略
+
+旧标签（bug/feature/improvement/security/risk:high/priority:high）已由新体系替代：
+
+- **旧标签保留不动**（不删除），避免历史 Issue 丢失标签信息
+- **新 Issue/PR 使用新标签**（type/* + priority/*）
+- 当前不做批量迁移。如有需要可后续通过 Gitea API 批量替换
+
+### 26.5 与其他章节的关系
+
+| 章节 | 关系 |
+|------|------|
+| §4.2 Issue 标签体系 | §26.2.2 Label 设计在问题管理场景的具体应用（已随 PR #69 更新） |
+| §4.5 标题规范 | §26.2.1 标题规范的执行层摘要（已随 PR #69 新增） |
+| §5 CI/CD 管道 | CI 事件通过标题前缀 `[CI]` 做事件路由（见 §16 事件中枢） |
+| §6 代码审查流程 | PR Template 检查清单约束审查前置条件 |
+
+### 26.6 实现记录
+
+| 文件 | 改动 |
+|------|------|
+| `prompt_composer.py` | 新增 `GiteaConventionSection`（priority=55） |
+| `task_handler.py` | `get_sections()` 注册 `GiteaConventionSection()` |
+| `toolchain_handler.py` | `get_sections()` 注册 `GiteaConventionSection()` |
+| `mail_handler.py` | `get_sections()` 注册 `GiteaConventionSection()` |
+| `db.py` | `COMMENT_TYPES` 补 `action_report`（修 API 500 bug） |
+| `.gitea/ISSUE_TEMPLATE/` | bug.yml / feature.yml / test.yml |
+| `.gitea/PULL_REQUEST_TEMPLATE.md` | PR 检查清单模板 |
+| Gitea Labels | 3 仓库各创建 11 个 Label（type × 7 + priority × 4） |
+
+PR #69，2026-06-14 合并。
+

docs/design/16-knowledge-injection.md

@@ -1,8 +1,8 @@
 # #16 知识注入设计
 
-> 状态：设计中
+> 状态：v2 设计中
 > 作者：庞统
-> 日期：2026-06-13
+> 日期：2026-06-13（v1），2026-06-14（v2 对齐 #11 四层架构）
 > 评审：待司马懿评审
 
 ## 一、问题
@@ -22,8 +22,6 @@ Agent（庞统、司马懿、张飞等）在执行任务时，不主动查询已
 
 **根因是注入时机**：Agent 不知道什么时候该查、没有强制机制让 Agent 在关键决策点查。
 
-现有设计（#11 四层架构）把知识注入放在 L3-4（被动参考层），但没有定义"什么时候触发被动参考"。
-
 ### 1.3 目标
 
 1. Agent 在关键决策点**主动查询** wiki-vault
@@ -64,31 +62,55 @@ Agent（庞统、司马懿、张飞等）在执行任务时，不主动查询已
 
 | 设计点 | 来源 | 我们的做法 |
 |--------|------|-----------|
-| 铁律级强制 | Superpowers | L0 Hook + SOUL.md 双重注入 |
-| Red Flags 反合理化 | Superpowers | 知识查询 Red Flags 表 |
+| 铁律级强制 | Superpowers | L0 Hook 注入 + L1 SOUL.md 行为引导 |
+| Red Flags 反合理化 | Superpowers | 知识查询 Red Flags 表（L1 SOUL.md） |
 | 经验内化 | Hermes | 经验→wiki-vault→下次查询 |
 | 渐进式披露 | Hermes | 先查 summary，按需读全文 |
 
-## 三、设计决策
+## 三、设计决策（对齐 #11 四层架构）
 
-### D16-1：三层触发机制（核心设计）
+> **层级体系严格对齐 [#11](./11-context-layers-redesign.md)**，不自创命名。
 
-不是在引擎层面自动注入知识全文（token 浪费），而是通过三层机制让 Agent **主动查询**：
+### 总览
 
-| 层级 | 机制 | 内容 | 覆盖范围 |
-|------|------|------|---------|
-| **L0 铁律** | SOUL.md 行为引导 | "做方案前先查 wiki-vault，有 1% 相关就要查" | 所有 Agent、所有场景 |
-| **L1 Skill 路由** | wiki-query Skill description | 触发词：调查、研究、分析、优秀实践、经验、怎么做X | Agent 匹配到触发词时 |
-| **L2 知识 gap 闭环** | 定时任务 | 查不到→记 gap→每天处理→写入 wiki-vault | 持续改进 |
+| #11 层级 | 知识注入角色 | 本设计覆盖 | 注入方式 |
+|----------|------------|-----------|---------|
+| **L0 铁律层** | "做方案前先查 wiki-vault" | ✅ D16-1 | Hook 每轮强制注入 |
+| **L1 角色层** | TOOLS.md 知识库速查表 + SOUL.md Red Flags | ✅ D16-2 | Workspace 文件自动注入 |
+| **L2 引擎注入层** | 三种 handler 各注入 WikiGuideSection | ✅ D16-3 | PromptComposer 拼装 |
+| **L3 被动参考层** | wiki-query Skill 按需触发 | ✅ D16-4 | extraDirs Description 匹配 |
+| 运维层 | gap 闭环 cron job | ✅ D16-5 | 不属于上下文分层 |
 
-**为什么不做 PromptComposer 自动注入**：
-1. 自动注入 token 浪费（每次任务都注入可能不相关的知识）
-2. 覆盖范围有限（只影响 moziplus 子任务 Agent）
-3. Agent 主动查询更精准（知道自己缺什么知识）
+### D16-1：L0 铁律层 — 新增一条 wiki 查询铁律
 
-### D16-2：知识查询 Red Flags（防止跳过）
+L0 只放跨系统通用的、不可绕过的行为底线。wiki 查询铁律和 GATE 门控同级。
 
-在 SOUL.md 中加入 Red Flags 表，和 Superpowers 一致：
+**新增铁律**：
+
+```
+<wiki-rule>
+做方案前先查 wiki-vault，有 1% 相关就要查。查不到记 knowledge-gaps.md。
+</wiki-rule>
+```
+
+**注入方式**：和 `<gate-rules>` / `<delegation-rule>` 并列，Hook 每轮强制注入。
+
+**覆盖范围**：所有 Agent、所有场景（不限于 moziplus spawn 的子任务）。
+
+### D16-2：L1 角色层 — TOOLS.md + SOUL.md
+
+#### TOOLS.md（✅ 已完成）
+
+各 Agent workspace 的 TOOLS.md 中已有「LLM Wiki 知识库」段，包含：
+
+- 速查表（场景 → 怎么做 → 什么时候用）
+- 检索原则（index.md → summary → grep → 整页读取，从便宜到昂贵）
+- 目录结构（wiki-vault / practices / concepts / skills / ...）
+- 铁律（做方案前先查、查不到记 gap）
+
+#### SOUL.md Red Flags
+
+在各 Agent 的 SOUL.md 中加入知识查询 Red Flags 表（和 Superpowers 一致）：
 
 | Agent 的想法 | 反驳 |
 |---|---|
@@ -97,22 +119,122 @@ Agent（庞统、司马懿、张飞等）在执行任务时，不主动查询已
 | "这个领域我熟悉" | 熟悉≠知道最新实践，wiki-vault 持续更新 |
 | "查知识库浪费时间" | 重复踩坑浪费的时间远大于查询时间 |
 
-### D16-3：知识 gap 记录机制
+### D16-3：L2 引擎注入层 — 三种 handler 各注入 WikiGuideSection
 
-**触发**：Agent 在 wiki-vault 中查不到相关知识时。
+L2 是 BootstrapBuilder/PromptComposer 动态拼装的 prompt 段。当前有三种 handler，各有自己的 PromptSection 实现：
 
-**记录位置**：`/Volumes/KnowledgeBase/wiki-vault/_meta/knowledge-gaps.md`
+#### 当前 handler 结构
 
-**格式**（已有）：
-```markdown
-- [日期] Agent名查"主题" → 待处理
+| Handler | Sections（priority） | 有 wiki 引导？ |
+|---------|---------------------|--------------|
+| **TaskHandler** | Context(10) → Prior(20) → RoleSkill(30) → API(40) → Constraints(50) | ❌ |
+| **MailHandler** | Context(10) → API(40) → Constraints(50) | ❌ |
+| **ToolchainHandler** | Context(10) → API(40) → Constraints(50) | ❌ |
+
+#### 新增 WikiGuideSection（priority=60，PRIORITY_EXTENSION）
+
+创建一个**通用 PromptSection**，三种 handler 的 `get_sections()` 都注入：
+
+```python
+# 可放在 prompt_composer.py 或独立文件，三种 handler 共用
+
+class WikiGuideSection:
+    """知识查询引导段 — 引导 Agent 在关键决策点查 wiki-vault。"""
+
+    name: str = "wiki_guide"
+    priority: int = 60  # PRIORITY_EXTENSION
+
+    WIKI_GUIDE = (
+        "## 知识查询引导\n"
+        "涉及方案设计、编码实现、故障排查时，先查 wiki-vault 相关实践：\n"
+        "- 路径：/Volumes/KnowledgeBase/wiki-vault/\n"
+        "- 速查：index.md → grep 关键词 → summary 字段 → 按需读全文\n"
+        "- 查不到：在 _meta/knowledge-gaps.md 记录"
+    )
+
+    def render(self, context: PromptContext) -> str:
+        return self.WIKI_GUIDE
+
+    def should_include(self, context: PromptContext) -> bool:
+        return True
 ```
 
-**已有基础设施**：
-- knowledge-gaps.md 已存在，有 20+ 条历史记录
-- 格式已定义，处理后会标注 `→ 已建立 ✅`
+#### 三种 handler 改动
 
-### D16-4：定时任务流程（已有 cron 基础）
+每种 handler 的 `get_sections()` 末尾加 `WikiGuideSection()`：
+
+```python
+# TaskHandler
+def get_sections(self) -> list:
+    return [
+        TaskContextSection(),
+        PriorOutputsSection(),
+        RoleSkillSection(),
+        TaskApiSection(),
+        TaskConstraintsSection(),
+        WikiGuideSection(),          # ← 新增
+    ]
+
+# MailHandler
+def get_sections(self) -> list:
+    return [
+        MailContextSection(),
+        MailApiSection(),
+        MailConstraintsSection(),
+        WikiGuideSection(),          # ← 新增
+    ]
+
+# ToolchainHandler
+def get_sections(self) -> list:
+    return [
+        ToolchainContextSection(),
+        ToolchainApiSection(),
+        ToolchainConstraintsSection(),
+        WikiGuideSection(),          # ← 新增
+    ]
+```
+
+#### 为什么三种 handler 都需要
+
+- **TaskHandler**：executor 做方案/编码，最需要查实践
+- **ToolchainHandler**：CI 失败排查、部署问题，有相关运维实践可参考
+- **MailHandler**：request 类型回复杂问题时也可能需要查已有经验
+
+#### token 开销
+
+WikiGuideSection 固定 ~60 字（~30 tokens），对 L2 预算影响可忽略。
+
+### D16-4：L3 被动参考层 — wiki-query Skill
+
+#### 现状
+
+`wiki-query` Skill 已部署在 `~/.sanguo_projects/sanguo_mozi/skills/wiki/wiki-query/SKILL.md`，description 包含中文触发词：
+
+> 调查、研究、分析、优秀实践、最佳实践、经验、怎么做X、有没有X的经验、以前怎么处理的
+
+#### 触发机制
+
+Agent 通过 extraDirs 加载 Skill header（name + description），按 Description 匹配自主 `read` 全文。这是标准 L3 行为，和 #11 设计一致。
+
+#### 待确认：extraDirs 子目录递归
+
+wiki-query 在 `skills/wiki/wiki-query/` 子目录下。需确认 moziplus spawn 子 agent 时 extraDirs 是否递归扫描子目录。如果不递归，需要：
+- 方案 A：把 wiki-query 移到 `skills/` 顶层
+- 方案 B：配置 extraDirs 包含 `skills/wiki/` 子目录
+
+### D16-5：知识 gap 记录 + 定时任务（运维层）
+
+> 不属于上下文分层体系，是独立的运维流程。
+
+#### gap 记录机制（已有基础设施）
+
+- **位置**：`/Volumes/KnowledgeBase/wiki-vault/_meta/knowledge-gaps.md`
+- **格式**：`- [日期] Agent名查"主题" → 待处理`
+- **已有 20+ 条历史记录**，处理后标注 `→ 已建立 ✅`
+
+wiki-query Skill 的 Step 5 已内置 gap 记录逻辑。
+
+#### 定时任务（已有 cron 基础）
 
 | 任务 | 时间 | 内容 | 状态 |
 |------|------|------|------|
@@ -126,56 +248,60 @@ Agent（庞统、司马懿、张飞等）在执行任务时，不主动查询已
 4. 新建或更新 wiki-vault 页面
 5. 更新 knowledge-gaps.md（标记为"已建立 ✅"或"无KB内容，跳过"）
 
-### D16-5：wiki-vault 作为索引层
+### D16-6：和 #11 各层关系总结
 
-**确认原则**：wiki-vault 是索引层，不是详细内容存储。
+| #11 层级 | #11 原始定义 | 知识注入贡献 | 本设计 |
+|---------|------------|------------|--------|
+| L0 铁律 | GATE 门控 + Delegation + 安全底线 | wiki 查询铁律 | ✅ D16-1 |
+| L1 角色 | SOUL.md + AGENTS.md + TOOLS.md + MEMORY.md | TOOLS.md 速查表 + SOUL.md Red Flags | ✅ D16-2 |
+| L2 引擎 | 任务上下文 + 角色操作规范 + 硬约束 | WikiGuideSection 通用段 | ✅ D16-3 |
+| L3 参考 | A/B/C/D 类 Skill，靠 Description 触发 | wiki-query Skill | ✅ D16-4 |
+| 运维 | — | gap 闭环 cron job | ✅ D16-5 |
 
-- 查询先走 wiki-vault（practices/concepts/skills）
-- 如果页面指向 knowledge_base 的详细内容，**必须 follow** 获取原文
-- knowledge_base 的路径：`/Volumes/KnowledgeBase/knowledge_base/`
+### D16-7：为什么不做 PromptComposer 自动注入知识全文
 
-### D16-6：和 #11 四层架构的关系
-
-| 层级 | 知识注入角色 | 本文档覆盖 |
-|------|------------|-----------|
-| L0 铁律层 | "做方案前先查 wiki-vault" | ✅ D16-1 L0 |
-| L1 身份层 | SOUL.md 中加入查询行为引导 | ✅ D16-1 L0 + D16-2 |
-| L2 引擎注入层 | 不做自动注入（Agent 主动查询更精准） | — |
-| L3 被动参考层 | wiki-query Skill 按需加载 | ✅ D16-1 L1 |
-| L4 检索层 | wiki-vault grep/read + knowledge_base follow | ✅ D16-5 |
-
-**和 #11 L3-4 的关系**：#11 把知识注入放在 L3 被动参考层，本文档是 L3-4 的具体实现方案。
-
-### D16-7：和 topic6 经验沉淀的关系
-
-| | topic6（moziplus 内部） | 本文档（知识注入） |
-|---|---|---|
-| **范围** | moziplus 引擎 spawn 的子任务 | 所有 Agent、所有场景 |
-| **经验来源** | 黑板 decisions/reviews/comments | jsonl 日志 + knowledge gaps |
-| **载体** | experiences 表（SQLite） | wiki-vault（Markdown） |
-| **关系** | topic6 的经验最终汇入 wiki-vault | wiki-vault 是知识的 single source of truth |
-
-**topic6 不急**：因为 jsonl 日志中的经验也是知识来源之一，定时总结时会覆盖。topic6 可以在后续作为 moziplus 内部的额外经验来源。
+1. **token 浪费**：每次任务都注入可能不相关的知识
+2. **覆盖范围有限**：只影响 moziplus 子任务 Agent
+3. **Agent 主动查询更精准**：知道自己缺什么知识，按需查询
 
 ## 四、改动清单
 
 ### 4.1 已完成 ✅
 
-| 改动 | 文件 | 说明 |
-|------|------|------|
-| TOOLS.md 更新 | workspace-pangtong/TOOLS.md | 新增「LLM Wiki 知识库」段：速查表、检索原则、铁律 |
+| 改动 | 文件 | 层级 | 说明 |
+|------|------|------|------|
+| TOOLS.md 知识库段 | 各 Agent workspace TOOLS.md | L1 | 速查表 + 检索原则 + 目录结构 + 铁律 |
+| wiki-query Skill 部署 | `skills/wiki/wiki-query/SKILL.md` | L3 | 中文触发词 + 渐进式检索协议 |
+| knowledge-gaps.md | `_meta/knowledge-gaps.md` | 运维 | 已有 20+ 条记录 |
+| wiki-daily-update cron | cron job | 运维 | 每天 04:00，需完善处理逻辑 |
+| pangtong-vault-sync cron | cron job | 运维 | 每天 05:00 |
 
 ### 4.2 待实现
 
-| 改动 | 文件 | 说明 |
-|------|------|------|
-| SOUL.md 行为引导 | workspace-pangtong/SOUL.md | 新增「知识查询」行为规则 + Red Flags |
-| wiki-daily-update 完善 | cron job | gap 处理 + 经验总结逻辑 |
+| 改动 | 文件 | 层级 | 说明 |
+|------|------|------|------|
+| L0 wiki 铁律 | Hook 注入配置（`prependContext`） | L0 | 新增 `<wiki-rule>` 段 |
+| SOUL.md Red Flags | 各 Agent workspace SOUL.md | L1 | 知识查询 Red Flags 表 |
+| WikiGuideSection | `prompt_composer.py` 或独立文件 | L2 | 通用 PromptSection，三种 handler 共用 |
+| TaskHandler 注入 | `task_handler.py` `get_sections()` | L2 | 末尾加 `WikiGuideSection()` |
+| MailHandler 注入 | `mail_handler.py` `get_sections()` | L2 | 末尾加 `WikiGuideSection()` |
+| ToolchainHandler 注入 | `toolchain_handler.py` `get_sections()` | L2 | 末尾加 `WikiGuideSection()` |
+| extraDirs 递归确认 | moziplus spawn 配置 | L3 | 确认 wiki-query 子目录可被发现 |
+| wiki-daily-update 完善 | cron job 脚本 | 运维 | gap 处理 + jsonl 经验提取 |
 
 ### 4.3 不做
 
 | 项目 | 原因 |
 |------|------|
-| PromptComposer 知识注入 | token 浪费，Agent 主动查询更精准 |
+| PromptComposer 知识全文注入 | token 浪费，Agent 主动查询更精准 |
 | experiences 表 | wiki-vault 已覆盖，不重复建设 |
-| 新 Skill | wiki-query 已有，不需要新的 |
+| 新 Skill（除 wiki-query 外） | wiki-query 已有，不需要新的 |
+
+## 五、风险
+
+| 风险 | 概率 | 缓解 |
+|------|------|------|
+| Agent 不主动查 wiki | 中 | L0 铁律强制 + L2 引导 + L3 Description 触发，三层保障 |
+| wiki-query 在子目录不被 extraDirs 发现 | 中 | 确认后决定移顶层或配置子目录 |
+| wiki-daily-update gap 处理质量不够 | 低 | 人工审核 + 逐步完善 |
+| WikiGuideSection 增加 token | 低 | 固定 ~30 tokens，影响可忽略 |

src/blackboard/db.py

@@ -209,6 +209,7 @@ VALID_TRANSITIONS = {
 COMMENT_TYPES = frozenset({
     "general", "handoff", "observation", "review", "rebuttal",
     "rebuttal_response", "debate_argument", "debate_rebuttal", "debate_judgment",
+    "action_report",
 })
 
 SEVERITY_LEVELS = frozenset({"blocking", "warning", "info", "audit"})

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
+from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection
 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()]
+        return [MailContextSection(), MailApiSection(), MailConstraintsSection(), GiteaConventionSection(), WikiGuideSection()]
 
     def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult:
         """Mail 完成验证：区分 inform/request。

src/daemon/prompt_composer.py

@@ -127,3 +127,50 @@ class PromptComposer:
             )
 
         return result
+
+
+# ---------------------------------------------------------------------------
+class GiteaConventionSection:
+    """Gitea 标题规范引导段 — 提醒 Agent 创建 Issue/PR 时遵循标题格式。"""
+
+    name: str = "gitea_convention"
+    priority: int = 55  # CONSTRAINTS(50) 和 EXTENSION(60) 之间
+
+    CONVENTION_TEXT = (
+        "## Gitea 标题规范\n"
+        "创建 Issue/PR 时，标题**必须**包含项目代号前缀：\n"
+        "- Issue: `[代号] type: 简述`，如 `[moz] bug: Mail API 500`\n"
+        "- PR: `[代号] type(scope): 简述`，如 `[moz] impl(daemon): WikiGuideSection 注入`\n"
+        "代号：moz=moziplus_v2, quant=quant_live, vnpy=vnpy\n"
+        "type: bug/feat/impl/fix/docs/test/ci/refactor/chore"
+    )
+
+    def render(self, context: "PromptContext") -> str:
+        return self.CONVENTION_TEXT
+
+    def should_include(self, context: "PromptContext") -> bool:
+        return True
+
+
+# ---------------------------------------------------------------------------
+# WikiGuideSection — 知识查询引导段
+# ---------------------------------------------------------------------------
+class WikiGuideSection:
+    """知识查询引导段 — 引导 Agent 在关键决策点查 wiki-vault。"""
+
+    name: str = "wiki_guide"
+    priority: int = 60  # PRIORITY_EXTENSION
+
+    WIKI_GUIDE = (
+        "## 知识查询引导\n"
+        "涉及方案设计、编码实现、故障排查时，先查 wiki-vault 相关实践：\n"
+        "- 路径：/Volumes/KnowledgeBase/wiki-vault/\n"
+        "- 速查：index.md → grep 关键词 → summary 字段 → 按需读全文\n"
+        "- 查不到：在 _meta/knowledge-gaps.md 记录"
+    )
+
+    def render(self, context: "PromptContext") -> str:
+        return self.WIKI_GUIDE
+
+    def should_include(self, context: "PromptContext") -> bool:
+        return True

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
+from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection
 from src.blackboard.db import get_connection
 
 logger = logging.getLogger("moziplus-v2.handler")
@@ -306,13 +306,15 @@ class TaskHandler(BaseTaskHandler):
         return True
 
     def get_sections(self) -> list:
-        """返回 5 个 PromptSection 实例。"""
+        """返回 PromptSection 实例。"""
         return [
             TaskContextSection(),
             PriorOutputsSection(),
             RoleSkillSection(),
             TaskApiSection(),
             TaskConstraintsSection(),
+            GiteaConventionSection(),
+            WikiGuideSection(),
         ]
 
     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
+from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection
 from src.daemon.toolchain_templates import render_template, _TEMPLATE_MAP
 from src.blackboard.db import get_connection
 
@@ -221,11 +221,13 @@ class ToolchainHandler(BaseTaskHandler):
         return self._auto_mark_working(task_id, db_path)
 
     def get_sections(self) -> list:
-        """返回 3 个 Toolchain PromptSection 实例"""
+        """返回 Toolchain PromptSection 实例"""
         return [
             ToolchainContextSection(),
             ToolchainApiSection(),
             ToolchainConstraintsSection(),
+            GiteaConventionSection(),
+            WikiGuideSection(),
         ]
 
     def build_prompt(self, context: PromptContext) -> str: