Octopus/octopus-release
3
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 14 Wiki Activity

fix(wiki): 替换全角（）：为半角以消除 Gitea 模棱两可 Unicode 字符警告

fourbroad
2026-06-24 09:50:13 +08:00
parent b31c801f12
commit 83ebe90cc2
1 changed files with 69 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
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
+69 -69
@@ -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/` 前缀等)除非另有说明，保持英文。
---