Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)
This commit is contained in:
octopus
@@ -0,0 +1,215 @@
|
||||
# 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 落点）：
|
||||
|
||||
```bash
|
||||
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`） |
|
||||
Reference in New Issue
Block a user