# Gitea Adapter — 写模式（Write Patterns） > Gitea adapter 参考实现（Increment 3，自 dogfood 源 > `_shared/gitea-write-patterns.md` 拆分上提）。本目录承载后端绑定的 > API 形态（MCP 工具名、REST 端点、curl 形态）；页名规范与寻址语义 > 是后端中立契约，见 `core/rules/artifact-addressing.md`（本文不重复）。 > 实例基址由实例配置提供（下文 ``），见 > `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 响应可用时（静态源串）用 ``，且仅此一处来源。 ## 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 引用 `#`；子工单正文 带 `## 父级 / Parent` 节引用父 `#`。 ### 衍生工单创建 - 技术债（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 落点）： ```bash curl -X POST "/api/v1/repos/Octopus/octopus/statuses/{sha}" \ -H "Authorization: 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 从实例配置读取（此处 `` 占位）。 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`） |