117 lines
7.9 KiB
Markdown
117 lines
7.9 KiB
Markdown
# 工件寻址契约（Core，后端中立）
|
||
|
||
> Core 原生契约（Increment 3，无 dogfood 对应源文件）。术语对照见
|
||
> `core/adapters/TERMINOLOGY.md`；本文所有实例路径以占位符表述
|
||
> （`<runs-root>` = 实例运行目录根），落地实例时按术语表绑定。
|
||
|
||
## 1. ref 语法
|
||
|
||
所有 Tier-2 工件的规范引用格式：
|
||
|
||
```
|
||
{backend}:{kind}/{owner}/{repo}/{id}#{anchor}
|
||
```
|
||
|
||
- `{backend}` — 工单后端标识（如 `gitea`）；由 adapter 层注册。
|
||
- `{kind}` — 工件类别，枚举见下表；新类别扩展时须同步各 adapter 的
|
||
resolve 实现并在本表登记。
|
||
- `{owner}/{repo}` — 仓库坐标。
|
||
- `{id}` — 工件标识：issue/PR 用数字，wiki 页用页名（可含 `/`），
|
||
评论用 `{issue-number}c{comment-id}`，commit-status 用 `{sha}@{context}`。
|
||
- `#{anchor}` — 可选锚点（页内段落、行号等），解析时透传不解释。
|
||
|
||
| kind | 含义 | id 形态 |
|
||
| --------------- | --------------- | ---------------------- |
|
||
| `issue` | 工单 | 数字 |
|
||
| `issue-comment` | 工单评论 | `{issue}c{comment-id}` |
|
||
| `wiki-page` | Tier-2 工件库页 | 页名（含 `/`） |
|
||
| `commit-status` | 提交状态 | `{sha}@{context}` |
|
||
| `pr` | 合并请求 | 数字 |
|
||
|
||
## 2. 页名文法（Core 契约）
|
||
|
||
Tier-2 工件库的**常规页名**：
|
||
|
||
```
|
||
{slug}/{type}-{seq:02d}-{title}
|
||
```
|
||
|
||
- `{slug}` 限 `[a-z0-9-]`；`{seq}` 两位零填充；`{title}` 限
|
||
`[a-z0-9-]`（CJK 标题按 adapter 层编码规则处理）。
|
||
|
||
### 2.1 例外页（全枚举）
|
||
|
||
以下页名不受常规文法约束（勘自实例的全部真实约定）：
|
||
|
||
| 例外页 | 形态 | 说明 |
|
||
| -------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------- |
|
||
| 评审轮次页 | `{slug}/reviews/{stage}/round{N}/{page}` | `page` ∈ `task-{ROLE}`、`revision-summary` |
|
||
| 评审终报 | `{slug}/reviews/{stage}/final/report` | 含 DAG task 变体 `…/final/report-task-{node-id}` |
|
||
| 验证报告 | `{slug}/05-verify-iteration-{N}` | 常规前缀 + 无 title 段的变体 |
|
||
| 验证报告（里程碑） | `{epic-slug}/05-verify-milestone-{M-id}` | 同上 |
|
||
| 验证报告（任务节点） | `{epic-slug}/05-verify-task-{node-id}` | 同上 |
|
||
| DAG 工件 | `{epic-slug}/dag`、`{epic-slug}/dag-nodes/{node-id}`、`{epic-slug}/dag-coverage` | 单门 DAG 管线工件 |
|
||
| DAG 共享契约 | `{epic-slug}/shared/{file}` | 跨会话契约 |
|
||
| bugfix 附件 | `{slug}/repro-notes`、`{slug}/test-report`、`{slug}/bugfix-report`、`{slug}/ABORT` | 单段固定名 |
|
||
| 原型/笔记 | `{slug}/prototype-debt`、`{slug}/spike-report`、`{slug}/impl-notes` | 单段固定名 |
|
||
| 设计修订 | `{slug}/03-design-amendments` | 常规前缀 + 固定名 |
|
||
| 浏览器证据 | `{slug}/verify/evidence/{name}` | 验证证据页 |
|
||
| 审计轮次页 | `audit/{date}/round{N}/{page}` | 日期 slug 例外；`page` ∈ `synthesis`、`task-{ROLE}` |
|
||
| 审计终报 | `audit/{date}/final/report` | 日期 slug 例外 |
|
||
| 回顾报告 | `_retrospectives/{cycle-name}` | 跨 slug 命名空间例外 |
|
||
| 技能评估 | `_evals/{skill-name}/{page}` | 评估命名空间例外 |
|
||
| 移植工件 | `port-{name}/source-analysis/{file}`、`port-{name}/self-check` | 移植命名空间例外 |
|
||
| 回顾归档 | `_archive/{slug}/…` | 归档命名空间例外 |
|
||
|
||
> 历史只读页名（旧管线产物，仍可读取）：`{slug}/01-stakeholder-interview`、
|
||
> `{slug}/02-requirements-index`、`{slug}/02-req-{seq:02d}-{title}`、
|
||
> `{slug}/02-03-req-design`、`{slug}/03-design-{seq:02d}-{title}`、
|
||
> `{slug}/03-adr-{NNNN}-{title}`、`{slug}/04-plan-index`、
|
||
> `{slug}/04-plan-{seq:02d}-{title}`、`{slug}/roadmap/{page}`。
|
||
|
||
### 2.2 kind ↔ type 映射
|
||
|
||
| 工件类别（kind 语境） | 页名 `{type}` 段 |
|
||
| --------------------- | ---------------------------------------------------------------- |
|
||
| 验证报告 | `05-verify-iteration` / `05-verify-milestone` / `05-verify-task` |
|
||
| 设计文档 | `03-design` / `03-adr` / `03-design-amendments` |
|
||
| 计划文档 | `04-plan` |
|
||
| 需求文档 | `02-req` / `02-requirements-index` |
|
||
| 评审工件 | `reviews`（目录段，非前缀） |
|
||
| DAG 工件 | `dag` / `dag-nodes` / `dag-coverage` |
|
||
| 审计工件 | `audit`（日期前缀命名空间） |
|
||
|
||
## 3. Tier-1 ↔ Tier-2 映射
|
||
|
||
wiki 页 `{slug}/…` 与实例运行目录 `<runs-root>/{slug}/…`（Tier-1 本地
|
||
结构化工件，见 Two-Tier 规则）按 slug 一一对应：
|
||
|
||
- 页 `{slug}/reviews/{stage}/round{N}/findings-{DIM}.json` ↔ 本地
|
||
`<runs-root>/{slug}/reviews/{stage}/round{N}/findings-{DIM}.json`；
|
||
- 页面正文承载 Tier-2 决策记录；原始发现、工作草稿留在 Tier-1 本地。
|
||
|
||
**文件名 URL 编码规则**：页名映射为本地文件名时 `/` → `%2F`
|
||
（逆向解码同理）；`.-` 尾缀是实例后端生成的 slug 产物，解码时剥除。
|
||
|
||
## 4. 双向链接不变量
|
||
|
||
1. **工件 ↔ 工单引用成对**：工件发布到工件库后，源工单侧必须有反向
|
||
索引（工件索引评论）；工单侧索引的每一行必须指向真实存在的工件。
|
||
2. **单评论聚合**：一个源工单有且仅有一条工件索引评论，各技能只
|
||
原位增改自己的行，绝不发第二条。
|
||
3. **归档补全**：工单关闭时，关闭方 agent 原位编辑索引评论——加归档
|
||
横幅、全部行重读优先级置 `ARCHIVE`；不删行、不改位置列。
|
||
|
||
## 5. adapter 义务
|
||
|
||
每个工单后端 adapter 必须实现三个操作：
|
||
|
||
- **parse** — 解析 ref 字符串为 `{backend, kind, owner, repo, id, anchor}`；
|
||
- **resolve** — 把解析结果解析为该后端可调用的 API 形态（端点、工具名、
|
||
参数），API 调用形态归 adapter 层，Core 不约束；
|
||
- **validate** — 校验页名符合第 2 节文法（含例外枚举）。
|
||
|
||
页名规范是**后端中立契约**；仓里的共用解析器
|
||
`script/resolve-artifact-ref.ts` 提供 parse 与页名/文件名编解码、
|
||
Tier-1 路径预测的中立实现，adapter 可复用。
|