Files

T

octopus bb35e661b2 Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)

2026-09-15 08:41:51 +08:00

9.0 KiB

Raw Blame History

Gitea Adapter — 写模式（Write Patterns）

Gitea adapter 参考实现（Increment 3，自 dogfood 源 _shared/gitea-write-patterns.md 拆分上提）。本目录承载后端绑定的 API 形态（MCP 工具名、REST 端点、curl 形态）；页名规范与寻址语义是后端中立契约，见 core/rules/artifact-addressing.md（本文不重复）。实例基址由实例配置提供（下文 <gitea-base-url>），见 core/adapters/TERMINOLOGY.md。

Owner/repo 固定为 Octopus/octopus。所有 wiki 页名遵循 Core 契约 {slug}/{type}-{seq:02d}-{title}（例外页全枚举见 artifact-addressing.md）。

Wiki URL 构造 — html_url 规则

黄金规则：绝不手工拼接 wiki URL。 gitea_wiki__create_page / gitea_wiki__get_page / gitea_wiki__list_pages 响应中的 html_url 字段是唯一权威链接，发布时捕获并原样复用。page_name → html_url 的变换不可推导（/→%2F、含斜杠页名带 .- 尾缀、CJK 百分号编码），必须读 API。

两种标识符勿混淆：

标识符	是什么	用途
`page_name`	原始页标识；字面 `/`、无主机、无编码	wiki MCP 工具的 `page_name`/`title` 参数
`html_url`	后端生成的完整可点击 URL	markdown 链接、`target_url`、PR 正文

去向：

工件索引位置列 — 一个单元格同时存两者： [`{page_name}`]({html_url})。链接文本供读侧调 gitea_wiki__get_page，href 供人点击（见 Pattern 10）。
commit-status target_url — 终报页的 html_url（见 Pattern 8）。
页内交叉链接 — 用 html_url。

无 API 响应可用时（静态源串）用 <gitea-base-url>，且仅此一处来源。

Pattern 1: create-wiki-page

gitea_wiki__create_page(owner="Octopus", repo="octopus",
  title="{slug}/{type}-{seq:02d}-{title}",
  content="{内容}",
  message="{可选 commit message}")

发布→验证（强制）：发布后立刻回读确认存在且内容一致：

gitea_wiki__get_page(owner="Octopus", repo="octopus", page_name="{同 title}")

404 / 内容不一致 → 修复后重发。页名冲突（409）→ 该页已存在，改用 Pattern 2 update，绝不另发新页。响应的 html_url 立即捕获复用。

Pattern 2: update-wiki-page

gitea_wiki__update_page(owner="Octopus", repo="octopus",
  page_name="{页名}",
  content="{新内容}",
  message="{commit message}")

更新后再回读验证；409 冲突 → 拉最新内容手工合并后重试。

Pattern 3: create-issue

gitea_issue__create(owner="Octopus", repo="octopus",
  title="{标题}", body="{正文}", labels=["{label}"])

工单交叉链接（强制）

父子工单组必须双向链接：父工单 task list 引用 #<number>；子工单正文带 ## 父级 / Parent 节引用父 #<number>。

衍生工单创建

技术债（verify Phase 5.5）：TD-NNN 经分配台账取号后升票，## Parent 指回登记册源工单。
基线失败（Phase 5.55）：label baseline-failure + BF-NNN（族伞签，按失败签名去重）。
不稳定测试（Phase 5.56）：label flaky-test + FT-NNN（同上）。

Pattern 4: update-issue

gitea_issue__update(owner="Octopus", repo="octopus",
  index={issue_number}, body="{正文}", state="{open|closed}", ...)

原位更新正文（checklist 勾选、live 状态表维护）；关闭工单即触发归档动作（见 artifact-addressing.md §4.3 + Pattern 10）。

Pattern 5: add-issue-comment

gitea_issue_comment__create(owner="Octopus", repo="octopus",
  index={issue_number}, body="{评论正文}")

首次评论后捕获返回的 comment_id——后续对同一逻辑评论的更新必须走 Pattern 6 原位 edit，绝不再 create。用于：评审综合（Synthesis）、状态备注、TD 登记、claim 认领。

Pattern 6: edit-issue-comment

gitea_issue_comment__edit(owner="Octopus", repo="octopus",
  comment_id={comment_id}, body="{新正文}")

单评论聚合不变量（工件索引、当前状态表等）的执行手段。

Pattern 7: move-issue-to-column

gitea_column__move_issue(owner="Octopus", repo="octopus",
  project_id={project_id}, column_id={column_id}, index={issue_number})

看板列迁移（Todo → In Progress → Review → Done）。

Pattern 7.5: move-issue-to-pipeline-stage

管线阶段板列（Pipeline Stages board column）承载阶段迁移——阶段转移落到板列，不落 ## 当前状态 行（该表只承载 PR / 评审 / CI 行与非阶段阻塞项）。列序列按管线阶段定义；移动用 Pattern 7 同款 gitea_column__move_issue，column 由 gitea_project__list / gitea_column__list 发现。

Pattern 8: post-commit-status（REST 回退）

MCP 工具缺席时用 REST 直发 commit status（评审综合的 Tier-2 落点）：

curl -X POST "<gitea-base-url>/api/v1/repos/Octopus/octopus/statuses/{sha}" \
  -H "Authorization: token <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "pipeline/review-{stage}",
    "state": "{success|failure|pending|error}",
    "target_url": "{html_url}",
    "description": "{≤140 chars 摘要}"
  }'

context 公式：pipeline/review-{stage}（code / review-dag / audit-process）。token 从实例配置读取（此处 <token> 占位）。 merge 前读回验证：GET /commits/{PR_SHA}/status。

Pattern 9: create-iteration-board

gitea_project__create(owner="Octopus", repo="octopus",
  title="{slug} — Iteration {N}", description="…")
gitea_column__create(owner="Octopus", repo="octopus",
  project_id={project_id}, title="Todo")
# … In Progress / Review / Done 同款

DAG 聚合 agent 在单门 PASS 后建板；工单正文模板带 ## Node Reference （指向 {epic-slug}/dag）、## Acceptance Criteria、## Parent。

Pattern 10: artifact-index（工单 ↔ 工件索引）

技能发布工件后，在源工单维护 ## 工件索引 评论——单一原位编辑的索引（反向链接 + compaction 恢复主路径；语义不变量见 core/rules/artifact-addressing.md §4）：

# 1. 找源工单（PR body / commit 的 Closes #N，或 DAG 父映射）；无则跳过
# 2. 评论已存在？
gitea_issue_comment__list(owner="Octopus", repo="octopus", index={issue_number})
#    → 扫 body 以 "## 工件索引" 开头的评论（遗留前缀 "## Pipeline 工件追踪表"
#      原位升级，不重复发）
# 3a. 不存在 → gitea_issue_comment__create 初始化
# 3b. 存在   → gitea_issue_comment__edit 原位编辑（复用 comment_id）

索引表模板（每工件一行；技能只增改自己的行，绝不删他技的行）：

## 工件索引

slug: `{slug}` — source issue #{N}

| 工件 | 类型 | 版本 | 位置 | 重读 |
|------|------|------|------|------|
| DAG | 任务图 | v1 (frozen) | [`{epic-slug}/dag`]({html_url}) | CORE |

位置列填充规则：单元格 = markdown 链接 [`{page_name}`]({html_url})；链接文本（page_name，字面 /）供读侧 gitea_wiki__get_page；href （html_url）供人点击，必须取自 API 响应，严禁拼接。

重读优先级：CORE = compaction 后必读（重读集 = 全部 CORE 行）； ON-Demand → ON-DEMAND = 按需；ARCHIVE = 已归档不读。

归档动作（archive-at-close）：工单关闭时由关闭方 agent 原位 edit 本评论——表格上方加归档横幅（> **状态**: ✅ 已归档 — issue #{N} 关闭于 {date}）+ 全部行重读置 ARCHIVE；不删行、不改位置列、不发第二条评论。主路径 verify Phase 5.6；跳过 verify 的路由由关闭 agent 补执行。

各技能行映射：

技能	工件 ID	位置
`analyze-dag`	`DAG`	`{epic-slug}/dag`
`review-artifact`	`REVIEW-{stage}`	`{slug}/reviews/{stage}/final/report`
`review-code`	`REVIEW-code`	`{slug}/reviews/code/final/report`
`review-code`（DAG task）	`REVIEW-code-task-{node-id}`	`{epic-slug}/reviews/code/final/report-task-{node-id}`
`verify`	`VERIFY-{N}`	`{slug}/05-verify-iteration-{N}`
`verify`（milestone）	`VERIFY-M-{M-id}`	`{epic-slug}/05-verify-milestone-{M-id}`（重读 `ON-DEMAND`）
`verify`（DAG task）	`VERIFY-TASK-{node-id}`	`{epic-slug}/05-verify-task-{node-id}`（重读 `ON-DEMAND`）

9.0 KiB Raw Blame History Unescape Escape