Octopus/octopus-release

Fork 0

Table of Contents

Octopus 工作流状态映射至 Gitea

1. 核心映射原则
2. 实体映射总表
3. 一次性前置设置(Prerequisites)

3.1 标签体系(Label Taxonomy)
3.2 项目看板
3.3 看板列(对应 SDLC 阶段)

4. 文档 → Wiki 页面映射
5. 两种触发模式

模式一:流水线集成(推荐)

流水线同步点
编排器在每个同步点执行的动作

模式二:手动触发(始终可用)

6. 生命周期操作详解(分阶段)

A. 同步 Roadmap(roadmap 阶段后)
B. 同步 Requirements(review-design-space 收敛后 · 需求部分)
C. 同步 Design(review-design-space 收敛后 · 设计部分)
D. 同步迭代计划(review-iteration-plan 收敛后)
E. 同步实现(review-code 门 · 代码就绪时)
F. 同步代码评审(review-code 收敛后)
G. 同步验证(verify 收敛后)
H. 同步发布

7. 幂等规则(避免重复同步)
8. 阶段流转一图速览
9. 语言约定

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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 工具征求批准之前。

编排器在每个同步点执行的动作

检查 Gitea 同步是否已启用(由"启用"命令记住)。
查上表确定要同步的内容。
调用对应的 Gitea MCP 工具推送产物。
报告一行摘要:"✓ Synced to Gitea: {创建了/更新了什么}"。
继续进入 question 征求用户批准。

模式二:手动触发(始终可用)

用户随时可显式请求同步:

用户指令	同步内容
"同步到 Gitea"	当前流水线迄今产生的全部产物
"同步 roadmap 到 Gitea"	仅路线图(看板 + 里程碑)
"同步这个 chunk 到 Gitea"	单个分块的工作项 + 文档
"同步 PR 到 Gitea"	创建镜像代码分支的 Gitea PR
"同步 release 到 Gitea"	创建 Gitea Release + Tag

6. 生命周期操作详解(分阶段)

以下过程在两种模式下通用。在流水线模式中，由编排器在每个同步点调用对应小节；在手动模式中，由用户指令决定执行哪些小节。所有操作均遵循幂等规则，可安全在每个评审门迭代时反复调用。

A. 同步 Roadmap(roadmap 阶段后)

确保看板 + 列已存在(见第 3 节)。
为路线图中每个 chunk 创建里程碑:
- 标题 chunk-{chunk-id}，描述包含"分块说明 + 依赖列表"。
把路线图文档同步到 Wiki 页面 Roadmap。

B. 同步 Requirements(review-design-space 收敛后 · 需求部分)

把需求文档同步到 Wiki 页面 Requirements/{chunk-id}。
为每个工作项创建 Issue:
- 标题 [{chunk-id}] {工作项标题}；正文含"## 验收标准"清单 + 描述；关联里程碑；打上类型与优先级标签。
设置工作项依赖:在 Issue 正文记录"Blocked by #N"，或通过依赖 API(POST /repos/{owner}/{repo}/issues/{blocker}/blocks)设置。

C. 同步 Design(review-design-space 收敛后 · 设计部分)

把设计文档同步到 Wiki 页面 Design/{chunk-id}。
把该 chunk 的所有 Issue 移到"Design"列(column__move_issue 的参数是 issue_index，即 Issue 编号)。
给被依赖阻塞的 Issue 打上 status/blocked 标签。

D. 同步迭代计划(review-iteration-plan 收敛后)

把计划文档同步到 Wiki 页面 Plan/{chunk-id}。
若迭代标签不存在则创建 iteration/iter-{N}。
给 Issue 打上对应迭代标签。
把 Issue 移到"Plan"列。

E. 同步实现(review-code 门 · 代码就绪时)

把 Issue 移到"Implement"列。
创建分支、代码就绪后创建 PR:标题 [{chunk-id}][{iteration}] {描述}，body 含"Closes #{issue_index}"。
按需添加评审人。

F. 同步代码评审(review-code 收敛后)

把评审摘要作为 Issue 评论发出(含 PASS / NEEDS-FIX 状态)。
把已评审的 Issue 移到"Review"列。

G. 同步验证(verify 收敛后)

把验证结果(DoD 矩阵摘要)作为 Issue 评论发出(含 PASS / FAIL 状态)。
把已验证的 Issue 移到"Done"列。
关闭 Issue(issue__update 设 state="closed")。
若该迭代所有工作项均通过验证，则合并 PR(pull__merge)。

H. 同步发布

收集上次发布以来所有已关闭的 Issue。
收集上次发布以来所有已合并的 PR。
创建 Release:tag v{version}，target main，note 含"## What's New"与"## Changelog"。

7. 幂等规则(避免重复同步)

每次创建前先检查:

里程碑:milestone__list → 标题已存在则跳过。
Issue:带标签过滤的 issue__list → 标题已匹配则跳过。
标签:label__list → 名称已存在则跳过。
Wiki 页面:wiki__list_pages → 页面已存在则改用 wiki__update_page。
Release:release__list → tag 已存在则跳过。
项目看板: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}/ 目录下的原始产物文件。