commit b31c801f120ecd3c04bbcf1b4f400318c874f1c5 Author: fourbroad Date: Wed Jun 24 09:25:14 2026 +0800 docs(wiki): add Octopus↔Gitea 工作流状态映射说明 diff --git a/Octopus-%E5%B7%A5%E4%BD%9C%E6%B5%81%E7%8A%B6%E6%80%81%E6%98%A0%E5%B0%84%E8%87%B3-Gitea.md b/Octopus-%E5%B7%A5%E4%BD%9C%E6%B5%81%E7%8A%B6%E6%80%81%E6%98%A0%E5%B0%84%E8%87%B3-Gitea.md new file mode 100644 index 0000000..24bfda3 --- /dev/null +++ b/Octopus-%E5%B7%A5%E4%BD%9C%E6%B5%81%E7%8A%B6%E6%80%81%E6%98%A0%E5%B0%84%E8%87%B3-Gitea.md @@ -0,0 +1,254 @@ +# Octopus 工作流状态映射至 Gitea + +本文档详细说明 Octopus SDLC（软件开发生命周期）工作流的各个状态、阶段与产物，是如何精确映射到 Gitea 仓库的各个实体（项目看板、里程碑、Issue、Wiki、标签、PR、Release）上的。该映射由 Octopus 的 `gitea-sync` 能力驱动，支持两种触发模式。 + +--- + +## 1. 核心映射原则 + +Octopus 将"软件开发流程"抽象为一组**概念实体**：Roadmap（路线图）、Chunk（分块）、Work Item（工作项）、Phase/Stage（阶段）、Iteration（迭代）、Document（文档）、Review（评审）、Release（发布）。这些概念并不直接存储在 Gitea 中，而是通过一套**确定性映射规则**投影到 Gitea 原生能力上： + +- **Gitea 是投影面，不是真相源**：Octopus 的 `.artifacts/{slug}/` 目录才是产物的唯一真相源；Gitea 上的内容是同步过来的可读副本，供人在 Web UI 中审阅。 +- **同步时机**：同步始终发生在**评审收敛之后**、**征求用户批准之前**。用户在 TUI 与 Gitea 两侧都能看到同一份产物。 +- **幂等性**：每次同步前先检查目标实体是否已存在，已存在则用 `update` 覆盖，避免产生重复。 + +--- + +## 2. 实体映射总表 + +| Octopus 概念 | Gitea 实体 | 使用的 MCP 工具 | 同步触发时机 | +|---|---|---|---| +| Roadmap（路线图） | 项目看板 + Wiki 页面 | `project__create`、`wiki__create_page` | roadmap 阶段之后 | +| Chunk（分块） | 里程碑（Milestone） | `milestone__create` | roadmap 中定义分块时 | +| Chunk 依赖关系 | 里程碑描述（自由文本） | `milestone__update` | 定义依赖时 | +| Work Item（工作项） | Issue（正文中含验收标准清单） | `issue__create` | 创建工作项时 | +| 工作项依赖 | Issue 的 blocked-by（Gitea 原生） | `issue__create` + 依赖 API | 设置依赖时 | +| Phase / 阶段 | 看板列的位置 | `column__move_issue` | 阶段流转时 | +| 状态（blocked 等） | 标签 | `issue_label__add` | 状态变更时 | +| 类型（feature/bugfix/refactor） | 标签 | `issue_label__add` | 创建 Issue 时 | +| 优先级 | 标签 | `issue_label__add` | 创建 Issue 时 | +| 迭代 | 标签 | `issue_label__add` | 分配迭代时 | +| 需求文档 | Wiki 页面 | `wiki__create_page` / `wiki__update_page` | requirements 阶段之后 | +| 设计文档 | Wiki 页面 | `wiki__create_page` / `wiki__update_page` | design 阶段之后 | +| 迭代计划 | Wiki 页面 | `wiki__create_page` / `wiki__update_page` | plan 阶段之后 | +| 评审结论 | Issue 评论 | `issue_comment__create` | 各评审阶段之后 | +| 代码分支与合并 | Pull Request | `pull__create`、`pull__merge` | 代码合并时 | +| Release（发布） | Gitea Release + Tag | `release__create` | 切版发布时 | + +--- + +## 3. 一次性前置设置（Prerequisites） + +首次同步前，目标 Gitea 仓库需要预先创建**标签体系、项目看板、看板列**。这是一次性的、每仓库仅需执行一次的初始化。 + +### 3.1 标签体系（Label Taxonomy） + +| 标签名 | 颜色 | 说明 | +|---|---|---| +| `type/feature` | `#84b6eb` | 新功能开发 | +| `type/bugfix` | `#e11d48` | 缺陷修复 | +| `type/refactor` | `#5cb85c` | 代码重构 | +| `status/blocked` | `#e11d48` | 被依赖阻塞 | +| `status/needs-attention` | `#fbca04` | 需要人工决策 | +| `priority/high` | `#e11d48` | 高优先级 | +| `priority/medium` | `#fbca04` | 中优先级 | +| `priority/low` | `#cccccc` | 低优先级 | + +> 迭代标签（`iteration/iter-1`、`iteration/iter-2`……）随迭代定义**动态创建**，颜色统一用 `#fbca04`。技术标识符（`chunk/`、`iteration/`、`type/` 前缀）保持英文，其余内容可中文化。 + +### 3.2 项目看板 + +创建一个名为 `{项目名} SDLC Board` 的项目看板，作为整个工作流的视觉总览。 + +### 3.3 看板列（对应 SDLC 阶段） + +Gitea 默认会创建若干列，需重命名或重建为以下布局。创建后须**记录每列的 column_id**，后续 `column__move_issue` 全程依赖它们。 + +| 顺序 | 列标题 | 对应的 Octopus 阶段 | +|---|---|---| +| 1 | Backlog | 未启动 | +| 2 | Requirements | requirements-elicitation（需求收集） | +| 3 | Design | design（架构设计） | +| 4 | Plan | plan-iterations（迭代规划） | +| 5 | Implement | implement（代码实现） | +| 6 | Review | review-code（代码评审） | +| 7 | Verify | verify（验证） | +| 8 | Done | 已完成 | + +--- + +## 4. 文档 → Wiki 页面映射 + +Wiki 页面采用扁平命名空间，以 `/` 作为分隔符。Wiki 内容是产物文件的**完整 Markdown 源码**（MCP 工具透明处理 base64 编解码，直接传入原始 Markdown 即可）。 + +| 文档 | Wiki 页面标题 | 来源文件 | +|---|---|---| +| 路线图 | `Roadmap` | `.artifacts/{slug}/roadmap/roadmap.md` | +| 需求（按分块） | `Requirements/{chunk-id}` | `.artifacts/{slug}/index.md` | +| 设计（按分块） | `Design/{chunk-id}` | `.artifacts/{slug}/design/design.md` | +| 迭代计划 | `Plan/{chunk-id}` | `.artifacts/{slug}/plan/plan.md` | +| 可行性报告 | `Feasibility-Report` | `docs/.../*.md` | + +> **page_name 注意事项**：Gitea 会把 Wiki 标题转换成 URL 安全的 `sub_url`（例如 `Plan/chunk-foo` → `Plan/chunk-foo.-`）。在调用 `wiki__get_page` / `wiki__update_page` 前，应先 `wiki__list_pages` 并使用返回的 `sub_url` 作为 `page_name`。 + +--- + +## 5. 两种触发模式 + +### 模式一：流水线集成（推荐） + +当用户说 **"启用 Gitea 同步"** 后，流水线中每个评审门在收敛后会自动把评审通过的产物同步到 Gitea，**再**提交给用户批准。用户可在 Gitea 的 Web UI（Wiki 页面、Issue、项目看板）中直接审阅产物，而非只能在 TUI 里看。会话内记住该同步状态直至用户说 **"停止 Gitea 同步"**。 + +#### 流水线同步点 + +| 评审门完成 | 同步到 Gitea | 用户在何处审阅 | +|---|---|---| +| `review-roadmap` | Wiki 页面"Roadmap" + 里程碑（分块）+ 项目看板 | Gitea wiki + 项目看板 | +| `review-design-space` | Wiki 页面"Requirements/{chunk}" + "Design/{chunk}" + Issue（工作项）+ 看板列 | Gitea wiki + Issue + 看板 | +| `review-iteration-plan` | Wiki 页面"Plan/{chunk}" + 给 Issue 打迭代标签 + 把 Issue 移到"Plan"列 | Gitea wiki + Issue 标签 | +| `review-code` | PR（若有代码）+ 评审结论作为 Issue 评论 + Issue 移到"Review"列 | Gitea PR + Issue 评论 | +| `verify` | 验证结果作为 Issue 评论 + 关闭 Issue + 移到"Done"列 | Gitea Issue（已关闭） | + +> **关键原则**：同步发生在评审收敛*之后*、`question` 工具征求批准*之前*。 + +#### 编排器在每个同步点执行的动作 + +1. 检查 Gitea 同步是否已启用（由"启用"命令记住）。 +2. 查上表确定要同步的内容。 +3. 调用对应的 Gitea MCP 工具推送产物。 +4. 报告一行摘要："✓ Synced to Gitea: {创建了/更新了什么}"。 +5. 继续进入 `question` 征求用户批准。 + +### 模式二：手动触发（始终可用） + +用户随时可显式请求同步： + +| 用户指令 | 同步内容 | +|---|---| +| "同步到 Gitea" | 当前流水线迄今产生的全部产物 | +| "同步 roadmap 到 Gitea" | 仅路线图（看板 + 里程碑） | +| "同步这个 chunk 到 Gitea" | 单个分块的工作项 + 文档 | +| "同步 PR 到 Gitea" | 创建镜像代码分支的 Gitea PR | +| "同步 release 到 Gitea" | 创建 Gitea Release + Tag | + +--- + +## 6. 生命周期操作详解（分阶段） + +以下过程在两种模式下通用。在**流水线模式**中，由编排器在每个同步点调用对应小节；在**手动模式**中，由用户指令决定执行哪些小节。所有操作均遵循幂等规则，可安全在每个评审门迭代时反复调用。 + +### A. 同步 Roadmap（roadmap 阶段后） + +1. 确保看板 + 列已存在（见第 3 节）。 +2. 为路线图中每个 chunk 创建里程碑： + - 标题 `chunk-{chunk-id}`，描述包含"分块说明 + 依赖列表"。 +3. 把路线图文档同步到 Wiki 页面 `Roadmap`。 + +### B. 同步 Requirements（review-design-space 收敛后 · 需求部分） + +1. 把需求文档同步到 Wiki 页面 `Requirements/{chunk-id}`。 +2. 为每个工作项创建 Issue： + - 标题 `[{chunk-id}] {工作项标题}`；正文含"## 验收标准"清单 + 描述；关联里程碑；打上类型与优先级标签。 +3. 设置工作项依赖：在 Issue 正文记录"Blocked by #N"，或通过依赖 API（`POST /repos/{owner}/{repo}/issues/{blocker}/blocks`）设置。 + +### C. 同步 Design（review-design-space 收敛后 · 设计部分） + +1. 把设计文档同步到 Wiki 页面 `Design/{chunk-id}`。 +2. 把该 chunk 的所有 Issue 移到"Design"列（`column__move_issue` 的参数是 `issue_index`，即 Issue 编号）。 +3. 给被依赖阻塞的 Issue 打上 `status/blocked` 标签。 + +### D. 同步迭代计划（review-iteration-plan 收敛后） + +1. 把计划文档同步到 Wiki 页面 `Plan/{chunk-id}`。 +2. 若迭代标签不存在则创建 `iteration/iter-{N}`。 +3. 给 Issue 打上对应迭代标签。 +4. 把 Issue 移到"Plan"列。 + +### E. 同步实现（review-code 门 · 代码就绪时） + +1. 把 Issue 移到"Implement"列。 +2. 创建分支、代码就绪后创建 PR：标题 `[{chunk-id}][{iteration}] {描述}`，body 含"Closes #{issue_index}"。 +3. 按需添加评审人。 + +### F. 同步代码评审（review-code 收敛后） + +1. 把评审摘要作为 Issue 评论发出（含 PASS / NEEDS-FIX 状态）。 +2. 把已评审的 Issue 移到"Review"列。 + +### G. 同步验证（verify 收敛后） + +1. 把验证结果（DoD 矩阵摘要）作为 Issue 评论发出（含 PASS / FAIL 状态）。 +2. 把已验证的 Issue 移到"Done"列。 +3. 关闭 Issue（`issue__update` 设 state="closed"）。 +4. 若该迭代所有工作项均通过验证，则合并 PR（`pull__merge`）。 + +### H. 同步发布 + +1. 收集上次发布以来所有已关闭的 Issue。 +2. 收集上次发布以来所有已合并的 PR。 +3. 创建 Release：tag `v{version}`，target `main`，note 含"## What's New"与"## Changelog"。 + +--- + +## 7. 幂等规则（避免重复同步） + +每次创建前先检查： + +1. **里程碑**：`milestone__list` → 标题已存在则跳过。 +2. **Issue**：带标签过滤的 `issue__list` → 标题已匹配则跳过。 +3. **标签**：`label__list` → 名称已存在则跳过。 +4. **Wiki 页面**：`wiki__list_pages` → 页面已存在则改用 `wiki__update_page`。 +5. **Release**：`release__list` → tag 已存在则跳过。 +6. **项目看板**：`project__list` → 同名看板已存在则跳过。 + +重新同步（产物变更后）使用更新工具：`issue__update`、`milestone__update`、`wiki__update_page`、`issue_label__replace`。 + +--- + +## 8. 阶段流转一图速览 + +``` +roadmap ──┐ + ▼ +[里程碑创建 · 看板创建 · Wiki "Roadmap"] + │ +requirements-elicitation ──▶ review-design-space ──▶ design + ▼ ▼ +[Wiki "Requirements/{chunk}" · Issue 创建] [Wiki "Design/{chunk}" · Issue→Design 列] + │ + ▼ +plan-iterations ──▶ review-iteration-plan + ▼ +[Wiki "Plan/{chunk}" · 迭代标签 · Issue→Plan 列] + │ + ▼ +implement ──▶ review-code + ▼ ▼ +[Issue→Implement 列 · PR 创建] [Issue 评论评审结论 · Issue→Review 列] + │ + ▼ +verify + ▼ +[Issue 评论验证结论 · Issue→Done 列 · Issue 关闭 · PR 合并] + │ + ▼ +release + ▼ +[Gitea Release + Tag] +``` + +--- + +## 9. 语言约定 + +所有生成内容（Issue 标题/正文、Wiki 页面、标签描述、PR 描述、发布说明）采用用户指定的语言： + +- 用户说"用中文同步" → 全部中文。 +- 用户说"sync in English" → 全部英文。 +- 用户未指定 → 沿用源产物的语言。 + +技术标识符（`chunk/`、`iteration/`、`type/` 前缀等）除非另有说明，保持英文。 + +--- + +*本页面由 Octopus `gitea-sync` 能力生成并维护。真相源始终是 `.artifacts/{slug}/` 目录下的原始产物文件。* \ No newline at end of file