# Axhub 标注目录同步（强制）

使用 OneOS AutoPRD 时，除资源库归档外，**必须**把 PRD 挂到 Axhub Make 标注工具的「原型目录」里，用户才能在右侧面板直接打开。

## 落点（三份必须一致）

| # | 路径 | 作用 |
|---|------|------|
| 1 | `src/prototypes/<prototype-id>/.spec/requirements-prd.md` | **主真相**：产品可读 PRD 全文 |
| 2 | `src/prototypes/<prototype-id>/annotation-source.json` → **顶层** `directory.nodes` | **标注目录入口**：面板里可见的 Markdown/PRD |
| 3 | `src/resources/prd/<prototype-id>-autoprd.md` | 资源库归档（可选但默认写） |

可选：复杂判定另写 `.spec/<topic>.md`，目录里再挂一条，并在 PRD 里链过去（与 `business-logic-documentation` 一致）。

## ⚠️ 目录必须写在文档顶层（常见踩坑）

Wire format（与 `prototype-annotation` 一致）：

```json
{
  "documentVersion": 1,
  "format": "axhub-annotation-source",
  "data": { "version": 2, "prototypeName": "...", "nodes": [] },
  "markdownMap": {},
  "assetMap": {},
  "directory": { "nodes": [] }
}
```

| 正确 | 错误 |
|------|------|
| 顶层 `directory.nodes` | 只写在 `data.directory` |
| `PrototypeAnnotationHost` / Make 读的是 `source.directory` | 写在 `data` 下时右侧「原型目录」为空 |

若误写在 `data.directory`：迁移到顶层 `directory`，并删除 `data.directory`，避免双源。

## 目录节点写法（推荐）

在说明根 `folder` 的 `children` **靠前**插入或更新：

```json
{
  "type": "markdown",
  "id": "<prefix>-doc-prd",
  "title": "产品需求说明（PRD）",
  "markdownPath": ".spec/requirements-prd.md",
  "markdown": "<与 .spec/requirements-prd.md 相同的全文>"
}
```

### 分章节 PRD（推荐，便于右侧目录浏览）

在「产品需求说明（PRD）」旁增加文件夹 **「PRD 分章」**，按 PRD 的 `##` 一级标题拆成多个 `markdown` 子节点（标题用章节名，正文为该章全文）。专题规格（`.spec/<topic>.md`）放在 **「专题规格」** 文件夹。

参考结构：

```text
folder  <模块>说明
  markdown  产品需求说明（PRD）     ← 全文
  folder    PRD 分章
    markdown  1. 一句话与目标
    markdown  2. 模块边界
    …
  folder    专题规格
    markdown  <topic 标题>
```

有 `scripts/sync-annotation-directory.mjs` 的原型：改 PRD / `.spec` 后**必须执行**该脚本再生目录。

定稿后第 10 章「功能变更记录」必须进入 PRD 全文节点；若有「PRD 分章」，同步该章节点。详见 [release-changelog.md](release-changelog.md)。

约定：

- `id`：`<短前缀>-doc-prd`（如 `ipc-doc-prd`、`wb-doc-prd`、`h5-va-doc-prd`）
- `title`：优先「产品需求说明（PRD）」；已有「PRD」可保留不改名
- **同时写** `markdownPath` + `markdown`：构建可内联路径，运行时目录也能直接读到正文
- 若已有同 id / 同标题节点：只更新正文与 path，不新建重复入口
- 遵守 `prototype-annotation-layout`：目录以 `markdown` 为主，不要用 `link`/`route` 顶替 PRD

## 增量改原型时怎么更新

1. 根据改动的文件路径确定 `<prototype-id>`。
2. 读现有 `.spec/requirements-prd.md`（没有则按 AutoPRD 模板新建）。
3. 只改受影响章节（故事、正逆向、关键逻辑、验收）；其余保留。
4. 回写 `.spec` + `resources/prd` + **顶层** `annotation-source.json` → `directory`（正文与文件一致；含分章节点）。
5. 若原型有 `scripts/sync-annotation-directory.mjs`，改完后执行它。

## 可跳过全量重写的情况

纯样式、无文案/无流程/无判定变化的微调：不必重写整份 PRD，但若改了用户可见文案或交互结果，仍须同步对应段落与目录节点。

## 验收

- [ ] `.spec/requirements-prd.md` 存在且为最新
- [ ] `annotation-source.json` **顶层**有 `directory.nodes`（不是只在 `data` 下）
- [ ] 标注目录能打开「产品需求说明（PRD）」且内容与文件一致
- [ ] 若有「PRD 分章」：各章可单独打开
- [ ] 用户故事仍为业务条线说明口径（起点 / 怎么运作 / 闭环）