OneOS1.2/rules/prototype-annotation-layout-guide.md

原型标注布局规范

适用于 src/prototypes/ 下所有接入 @axhub/annotation 的原型页面。

核心原则

1. 禁止在右侧「原型目录」中展示跨原型导航

   • 不得在 annotation-source.json 的 directory.nodes 中维护 id: oneos-project-nav 的「ONE-OS 原型导航」文件夹
   • 跨原型跳转统一由 /prototypes/oneos-prototype-nav（原型导航页） 承担

2. PRD 说明展示在右侧「原型标注」目录面板

   • 产品需求、模块说明、分章节 PRD 等内容，通过 directory 的 markdown 节点写入
   • 用户在右侧工具栏打开「原型标注 / 原型目录」，按章节阅读 Markdown 正文
   • 不在页面正文下方内联展示 PRD 大段内容

3. 去除目录内页面跳转

   • type: link 跨原型/跨模块链接不在目录树中展示
   • type: route 页面内跳转节点不在目录树中展示（route 仅用于声明 pageId 绑定，供按当前页过滤章节）
   • 页面切换由原型自身导航（按钮、Tab、Hash 等）完成

4. 标注工具栏保留

   • 页面元素批注、主题切换、颜色筛选等 @axhub/annotation 能力继续可用

标准接入方式

所有新原型与存量改造，必须使用公共壳组件：

import {
  type AnnotationSourceDocument,
  type AnnotationViewerOptions,
} from '@axhub/annotation';
import { PrototypeAnnotationHost } from '../../common/prototype-annotation-host';
import annotationSourceDocument from './annotation-source.json';

export default function MyPrototypePage() {
  const annotationOptions = useMemo<AnnotationViewerOptions>(() => ({
    showToolbar: true,
    showThemeToggle: true,
    showColorFilter: true,
    emptyWhenNoData: false,
    toolbarEdge: 'right',
    currentPageId: 'list', // 多页面原型按当前页传入
  }), []);

  return (
    <>
      <MyApp />
      <PrototypeAnnotationHost
        source={annotationSourceDocument as AnnotationSourceDocument}
        options={annotationOptions}
      />
    </>
  );
}

多页面原型

• options.currentPageId 与页面路由保持一致
• annotation-source.json 中带 route 子节点的文件夹，仅在其 payload.pageId 匹配当前页时，才在右侧目录中展示对应 PRD 章节
• 无 route 绑定的 PRD 文件夹（如「PRD 全文」「模块总览」）在所有子页面均展示
• 一般不需要再实现 onDirectoryRoute（目录内已无 route 可点击节点）

annotation-source.json 目录约定

directory.nodes 中只允许保留 本产品说明，结构建议：

directory.nodes
├── folder · 模块说明 / PRD 全文 / 列表页模块 / 新增页模块 …
│   ├── markdown · 章节正文（内联 markdown 或 markdownMap）
│   └── route · 仅用于声明 pageId 绑定（不在 UI 展示）

禁止写入：

• id: oneos-project-nav 导航文件夹
• 依赖 type: link 的跨原型跳转（改放原型导航页）

不在目录 UI 展示（但可保留在 JSON 中供过滤）：

• type: link 节点
• type: route 节点（仅作 pageId 绑定元数据）

脚本与同步

命令	作用
npm run project-nav:sync	更新原型导航页 nav-menu.json，并清理各原型目录中的导航节点
node scripts/strip-prototype-nav-from-directory.mjs	批量移除 oneos-project-nav
node scripts/migrate-prototype-annotation-host.mjs	将 AnnotationViewer 迁移为 PrototypeAnnotationHost

修改 sidebar 菜单或批量整理标注目录后，执行 npm run project-nav:sync。

Agent 开发检查清单

新建或改造带标注的原型时：

• index.tsx 使用 PrototypeAnnotationHost，不直接挂载裸 AnnotationViewer
• annotation-source.json 无 oneos-project-nav 节点
• PRD / 模块说明以 markdown 节点写入 directory，能在右侧「原型目录」分章节阅读
• 页面正文下方无大块 PRD 内联区域
• 右侧目录无跨原型 link、无可点击的 route 页面跳转
• 跨原型入口统一引导用户打开「原型导航」页
• 多页面原型正确传入 currentPageId，右侧 PRD 章节与当前页匹配

相关文件

文件	说明
src/common/prototype-annotation-host.tsx	标注壳：过滤目录 + 批注工具栏
src/common/prototype-annotation-utils.ts	PRD 目录过滤与导航节点清理
src/prototypes/oneos-prototype-nav/	全局原型导航页
scripts/sync-project-prototype-directory.mjs	导航菜单同步（不再注入侧边导航树）