From 83ebe90cc2540a67188bed65b53b2e20c3f70723 Mon Sep 17 00:00:00 2001 From: fourbroad Date: Wed, 24 Jun 2026 09:50:13 +0800 Subject: [PATCH] =?UTF-8?q?fix(wiki):=20=E6=9B=BF=E6=8D=A2=E5=85=A8?= =?UTF-8?q?=E8=A7=92=EF=BC=88=EF=BC=89=EF=BC=9A=E4=B8=BA=E5=8D=8A=E8=A7=92?= =?UTF-8?q?=E4=BB=A5=E6=B6=88=E9=99=A4=20Gitea=20=E6=A8=A1=E6=A3=B1?= =?UTF-8?q?=E4=B8=A4=E5=8F=AF=20Unicode=20=E5=AD=97=E7=AC=A6=E8=AD=A6?= =?UTF-8?q?=E5=91=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...%80%81%E6%98%A0%E5%B0%84%E8%87%B3-Gitea.md | 138 +++++++++--------- 1 file changed, 69 insertions(+), 69 deletions(-) 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 index 24bfda3..cddc074 100644 --- 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 @@ -1,16 +1,16 @@ # Octopus 工作流状态映射至 Gitea -本文档详细说明 Octopus SDLC（软件开发生命周期）工作流的各个状态、阶段与产物，是如何精确映射到 Gitea 仓库的各个实体（项目看板、里程碑、Issue、Wiki、标签、PR、Release）上的。该映射由 Octopus 的 `gitea-sync` 能力驱动，支持两种触发模式。 +本文档详细说明 Octopus SDLC(软件开发生命周期)工作流的各个状态、阶段与产物，是如何精确映射到 Gitea 仓库的各个实体(项目看板、里程碑、Issue、Wiki、标签、PR、Release)上的。该映射由 Octopus 的 `gitea-sync` 能力驱动，支持两种触发模式。 --- ## 1. 核心映射原则 -Octopus 将"软件开发流程"抽象为一组**概念实体**：Roadmap（路线图）、Chunk（分块）、Work Item（工作项）、Phase/Stage（阶段）、Iteration（迭代）、Document（文档）、Review（评审）、Release（发布）。这些概念并不直接存储在 Gitea 中，而是通过一套**确定性映射规则**投影到 Gitea 原生能力上： +Octopus 将"软件开发流程"抽象为一组**概念实体**:Roadmap(路线图)、Chunk(分块)、Work Item(工作项)、Phase/Stage(阶段)、Iteration(迭代)、Document(文档)、Review(评审)、Release(发布)。这些概念并不直接存储在 Gitea 中，而是通过一套**确定性映射规则**投影到 Gitea 原生能力上: -- **Gitea 是投影面，不是真相源**：Octopus 的 `.artifacts/{slug}/` 目录才是产物的唯一真相源；Gitea 上的内容是同步过来的可读副本，供人在 Web UI 中审阅。 -- **同步时机**：同步始终发生在**评审收敛之后**、**征求用户批准之前**。用户在 TUI 与 Gitea 两侧都能看到同一份产物。 -- **幂等性**：每次同步前先检查目标实体是否已存在，已存在则用 `update` 覆盖，避免产生重复。 +- **Gitea 是投影面，不是真相源**:Octopus 的 `.artifacts/{slug}/` 目录才是产物的唯一真相源；Gitea 上的内容是同步过来的可读副本，供人在 Web UI 中审阅。 +- **同步时机**:同步始终发生在**评审收敛之后**、**征求用户批准之前**。用户在 TUI 与 Gitea 两侧都能看到同一份产物。 +- **幂等性**:每次同步前先检查目标实体是否已存在，已存在则用 `update` 覆盖，避免产生重复。 --- @@ -18,14 +18,14 @@ Octopus 将"软件开发流程"抽象为一组**概念实体**：Roadmap（路 | 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 | 设置依赖时 | +| 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 时 | +| 状态(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 阶段之后 | @@ -33,15 +33,15 @@ Octopus 将"软件开发流程"抽象为一组**概念实体**：Roadmap（路 | 迭代计划 | Wiki 页面 | `wiki__create_page` / `wiki__update_page` | plan 阶段之后 | | 评审结论 | Issue 评论 | `issue_comment__create` | 各评审阶段之后 | | 代码分支与合并 | Pull Request | `pull__create`、`pull__merge` | 代码合并时 | -| Release（发布） | Gitea Release + Tag | `release__create` | 切版发布时 | +| Release(发布) | Gitea Release + Tag | `release__create` | 切版发布时 | --- -## 3. 一次性前置设置（Prerequisites） +## 3. 一次性前置设置(Prerequisites) 首次同步前，目标 Gitea 仓库需要预先创建**标签体系、项目看板、看板列**。这是一次性的、每仓库仅需执行一次的初始化。 -### 3.1 标签体系（Label Taxonomy） +### 3.1 标签体系(Label Taxonomy) | 标签名 | 颜色 | 说明 | |---|---|---| @@ -54,154 +54,154 @@ Octopus 将"软件开发流程"抽象为一组**概念实体**：Roadmap（路 | `priority/medium` | `#fbca04` | 中优先级 | | `priority/low` | `#cccccc` | 低优先级 | -> 迭代标签（`iteration/iter-1`、`iteration/iter-2`……）随迭代定义**动态创建**，颜色统一用 `#fbca04`。技术标识符（`chunk/`、`iteration/`、`type/` 前缀）保持英文，其余内容可中文化。 +> 迭代标签(`iteration/iter-1`、`iteration/iter-2`……)随迭代定义**动态创建**，颜色统一用 `#fbca04`。技术标识符(`chunk/`、`iteration/`、`type/` 前缀)保持英文，其余内容可中文化。 ### 3.2 项目看板 创建一个名为 `{项目名} SDLC Board` 的项目看板，作为整个工作流的视觉总览。 -### 3.3 看板列（对应 SDLC 阶段） +### 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（验证） | +| 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 页面采用扁平命名空间，以 `/` 作为分隔符。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` | +| 需求(按分块) | `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`。 +> **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 同步"** 后，流水线中每个评审门在收敛后会自动把评审通过的产物同步到 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-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（已关闭） | +| `review-code` | PR(若有代码)+ 评审结论作为 Issue 评论 + Issue 移到"Review"列 | Gitea PR + Issue 评论 | +| `verify` | 验证结果作为 Issue 评论 + 关闭 Issue + 移到"Done"列 | Gitea Issue(已关闭) | -> **关键原则**：同步发生在评审收敛*之后*、`question` 工具征求批准*之前*。 +> **关键原则**:同步发生在评审收敛*之后*、`question` 工具征求批准*之前*。 #### 编排器在每个同步点执行的动作 -1. 检查 Gitea 同步是否已启用（由"启用"命令记住）。 +1. 检查 Gitea 同步是否已启用(由"启用"命令记住)。 2. 查上表确定要同步的内容。 3. 调用对应的 Gitea MCP 工具推送产物。 -4. 报告一行摘要："✓ Synced to Gitea: {创建了/更新了什么}"。 +4. 报告一行摘要:"✓ Synced to Gitea: {创建了/更新了什么}"。 5. 继续进入 `question` 征求用户批准。 -### 模式二：手动触发（始终可用） +### 模式二:手动触发(始终可用) -用户随时可显式请求同步： +用户随时可显式请求同步: | 用户指令 | 同步内容 | |---|---| | "同步到 Gitea" | 当前流水线迄今产生的全部产物 | -| "同步 roadmap 到 Gitea" | 仅路线图（看板 + 里程碑） | +| "同步 roadmap 到 Gitea" | 仅路线图(看板 + 里程碑) | | "同步这个 chunk 到 Gitea" | 单个分块的工作项 + 文档 | | "同步 PR 到 Gitea" | 创建镜像代码分支的 Gitea PR | | "同步 release 到 Gitea" | 创建 Gitea Release + Tag | --- -## 6. 生命周期操作详解（分阶段） +## 6. 生命周期操作详解(分阶段) 以下过程在两种模式下通用。在**流水线模式**中，由编排器在每个同步点调用对应小节；在**手动模式**中，由用户指令决定执行哪些小节。所有操作均遵循幂等规则，可安全在每个评审门迭代时反复调用。 -### A. 同步 Roadmap（roadmap 阶段后） +### A. 同步 Roadmap(roadmap 阶段后) -1. 确保看板 + 列已存在（见第 3 节）。 -2. 为路线图中每个 chunk 创建里程碑： +1. 确保看板 + 列已存在(见第 3 节)。 +2. 为路线图中每个 chunk 创建里程碑: - 标题 `chunk-{chunk-id}`，描述包含"分块说明 + 依赖列表"。 3. 把路线图文档同步到 Wiki 页面 `Roadmap`。 -### B. 同步 Requirements（review-design-space 收敛后 · 需求部分） +### B. 同步 Requirements(review-design-space 收敛后 · 需求部分) 1. 把需求文档同步到 Wiki 页面 `Requirements/{chunk-id}`。 -2. 为每个工作项创建 Issue： +2. 为每个工作项创建 Issue: - 标题 `[{chunk-id}] {工作项标题}`；正文含"## 验收标准"清单 + 描述；关联里程碑；打上类型与优先级标签。 -3. 设置工作项依赖：在 Issue 正文记录"Blocked by #N"，或通过依赖 API（`POST /repos/{owner}/{repo}/issues/{blocker}/blocks`）设置。 +3. 设置工作项依赖:在 Issue 正文记录"Blocked by #N"，或通过依赖 API(`POST /repos/{owner}/{repo}/issues/{blocker}/blocks`)设置。 -### C. 同步 Design（review-design-space 收敛后 · 设计部分） +### C. 同步 Design(review-design-space 收敛后 · 设计部分) 1. 把设计文档同步到 Wiki 页面 `Design/{chunk-id}`。 -2. 把该 chunk 的所有 Issue 移到"Design"列（`column__move_issue` 的参数是 `issue_index`，即 Issue 编号）。 +2. 把该 chunk 的所有 Issue 移到"Design"列(`column__move_issue` 的参数是 `issue_index`，即 Issue 编号)。 3. 给被依赖阻塞的 Issue 打上 `status/blocked` 标签。 -### D. 同步迭代计划（review-iteration-plan 收敛后） +### D. 同步迭代计划(review-iteration-plan 收敛后) 1. 把计划文档同步到 Wiki 页面 `Plan/{chunk-id}`。 2. 若迭代标签不存在则创建 `iteration/iter-{N}`。 3. 给 Issue 打上对应迭代标签。 4. 把 Issue 移到"Plan"列。 -### E. 同步实现（review-code 门 · 代码就绪时） +### E. 同步实现(review-code 门 · 代码就绪时) 1. 把 Issue 移到"Implement"列。 -2. 创建分支、代码就绪后创建 PR：标题 `[{chunk-id}][{iteration}] {描述}`，body 含"Closes #{issue_index}"。 +2. 创建分支、代码就绪后创建 PR:标题 `[{chunk-id}][{iteration}] {描述}`，body 含"Closes #{issue_index}"。 3. 按需添加评审人。 -### F. 同步代码评审（review-code 收敛后） +### F. 同步代码评审(review-code 收敛后) -1. 把评审摘要作为 Issue 评论发出（含 PASS / NEEDS-FIX 状态）。 +1. 把评审摘要作为 Issue 评论发出(含 PASS / NEEDS-FIX 状态)。 2. 把已评审的 Issue 移到"Review"列。 -### G. 同步验证（verify 收敛后） +### G. 同步验证(verify 收敛后) -1. 把验证结果（DoD 矩阵摘要）作为 Issue 评论发出（含 PASS / FAIL 状态）。 +1. 把验证结果(DoD 矩阵摘要)作为 Issue 评论发出(含 PASS / FAIL 状态)。 2. 把已验证的 Issue 移到"Done"列。 -3. 关闭 Issue（`issue__update` 设 state="closed"）。 -4. 若该迭代所有工作项均通过验证，则合并 PR（`pull__merge`）。 +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"。 +3. 创建 Release:tag `v{version}`，target `main`，note 含"## What's New"与"## Changelog"。 --- -## 7. 幂等规则（避免重复同步） +## 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` → 同名看板已存在则跳过。 +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`。 +重新同步(产物变更后)使用更新工具:`issue__update`、`milestone__update`、`wiki__update_page`、`issue_label__replace`。 --- @@ -241,13 +241,13 @@ release ## 9. 语言约定 -所有生成内容（Issue 标题/正文、Wiki 页面、标签描述、PR 描述、发布说明）采用用户指定的语言： +所有生成内容(Issue 标题/正文、Wiki 页面、标签描述、PR 描述、发布说明)采用用户指定的语言: - 用户说"用中文同步" → 全部中文。 - 用户说"sync in English" → 全部英文。 - 用户未指定 → 沿用源产物的语言。 -技术标识符（`chunk/`、`iteration/`、`type/` 前缀等）除非另有说明，保持英文。 +技术标识符(`chunk/`、`iteration/`、`type/` 前缀等)除非另有说明，保持英文。 ---