From 3f07c528b616f13b602695716392d13ff8547c4b Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sun, 14 Jun 2026 12:07:47 +0800 Subject: [PATCH] =?UTF-8?q?[moz]=20docs:=20=E9=87=8D=E5=86=99=20=C2=A726?= =?UTF-8?q?=20Gitea=20=E5=8D=8F=E4=BD=9C=E8=A7=84=E8=8C=83=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=EF=BC=88=E6=B5=81=E6=B0=B4=E8=B4=A6=E2=86=92=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E6=96=87=E6=A1=A3=E9=A3=8E=E6=A0=BC=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - §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 混淆） --- docs/design/13-toolchain-and-dev-workflow.md | 118 +++++++++++++++---- 1 file changed, 95 insertions(+), 23 deletions(-) diff --git a/docs/design/13-toolchain-and-dev-workflow.md b/docs/design/13-toolchain-and-dev-workflow.md index 269550e..ad60930 100644 --- a/docs/design/13-toolchain-and-dev-workflow.md +++ b/docs/design/13-toolchain-and-dev-workflow.md @@ -324,7 +324,7 @@ Open → In Progress → Review → Closed - `[quant] feat: 趋势跟踪策略骨架` 此规范通过 L2 引擎层 `GiteaConventionSection`（priority=55）自动注入所有 Agent prompt。 -完整规范文档：L3 Skill `gitea-conventions`。 +完整规范文档：L3 Skill `gitea-conventions`。规范设计原理详见 [§26](#26-gitea-协作规范设计)。 --- @@ -3329,40 +3329,107 @@ async def _handle_issue_comment(payload): --- -## §26. Gitea 协作规范落地 +## §26. Gitea 协作规范设计 -> **状态**: ✅ 已完成 +> **状态**: ✅ 已实现（PR #69） > **日期**: 2026-06-14 -> **PR**: 本次改动随 PR 提交 -### 26.1 动机 +### 26.1 设计目标 -团队三个仓库（moziplus_v2 / quant_live / vnpy）缺少统一的 Issue/PR 模板、Label 体系和标题规范。人类从标题无法一眼分辨是哪个项目什么类型的问题。 +团队三个仓库（moziplus_v2 / quant_live / vnpy）在 Gitea 上独立存在，协作时存在三个问题： -### 26.2 落地内容 +1. **标题不可辨识**：`Fix mail API` 看不出是哪个项目、什么类型的改动 +2. **Label 缺失**：无统一标签体系，无法按类型/优先级筛选 +3. **填写无约束**：Issue/PR 内容格式随意，审查时缺少关键信息 -| 层级 | 内容 | 说明 | +本规范的目标：让人类一眼识别项目+类型，让 Agent 可程序化遵循，让模板降低填写门槛。 + +### 26.2 规范设计 + +#### 26.2.1 标题规范 + +**规则**：所有 Issue/PR 标题必须包含项目代号前缀。 + +| 类型 | 格式 | 示例 | |------|------|------| -| L3 | `gitea-conventions` Skill | 完整规范文档（标题/分支/commit/label） | -| L2 | `GiteaConventionSection`（priority=55） | 注入所有 handler（task/toolchain/mail），自动提醒 Agent 遵循标题格式 | -| L1 | TOOLS.md 追加代号表 | Agent 静态可见的速查 | -| Gitea 模板 | 3 仓库 × 4 文件 | bug.yml / feature.yml / test.yml / PULL_REQUEST_TEMPLATE.md | -| Gitea Labels | 3 仓库 × 11 个 | type × 7 + priority × 4 | +| Issue | `[代号] type: 简述` | `[moz] bug: Mail API 500 when comment_type invalid` | +| PR | `[代号] type(scope): 简述` | `[moz] impl(daemon): WikiGuideSection 注入` | -### 26.3 四层注入路径 +**项目代号**：moz=moziplus_v2, quant=quant_live, vnpy=vnpy -``` -L1 TOOLS.md（静态，Agent workspace） - → 代号表 + 格式速查 +**type 清单**：bug / feat / impl / fix / docs / test / ci / refactor / chore -L2 GiteaConventionSection（动态，每次 spawn 注入） - → "创建 Issue/PR 时标题必须带 [代号] 前缀" +**设计决策**： +- 为什么用代号前缀而不是靠仓库隔离？— 团队成员同时在多仓库协作，通知列表（Mail、Gitea dashboard）混合展示时代号前缀提供即时辨识。仓库隔离解决不了跨仓库视图的辨识问题 +- PR 加 `scope` 是因为 PR 通常涉及具体模块（daemon / api / frontend），Issue 不需要 -L3 gitea-conventions Skill（被动，extraDirs 自动发现） - → 完整规范：标题/分支/commit/label/模板 -``` +#### 26.2.2 Label 体系 -### 26.4 代码改动 +采用 `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 实现记录 | 文件 | 改动 | |------|------| @@ -3371,4 +3438,9 @@ L3 gitea-conventions Skill（被动，extraDirs 自动发现） | `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 合并。 -- 2.45.4