扩展氢能站点、加氢记录与台账原型链路，新增工作台、车辆资产 H5、自营物流等原型，并同步导航注册、PRD 资源与交付技能。
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
王冕
98
.cursor/skills/oneos-autoprd/references/annotation-sync.md
Normal file
98
.cursor/skills/oneos-autoprd/references/annotation-sync.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# 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 分章」：各章可单独打开
|
||||
- [ ] 用户故事仍为业务条线说明口径（起点 / 怎么运作 / 闭环）
|
||||
@@ -0,0 +1,58 @@
|
||||
# 颗粒度标杆与用户故事口径
|
||||
|
||||
## 用户故事：对齐「业务条线说明」页面
|
||||
|
||||
页面：`/prototypes/lease-business-line-overview`
|
||||
数据：`src/prototypes/lease-business-line-overview/lines.ts`
|
||||
|
||||
每个能力卡片的产品叙述结构：
|
||||
|
||||
```text
|
||||
责任部门（roles）
|
||||
→ 起点（start）
|
||||
→ 怎么运作（process[]，有序）
|
||||
→ 关键结果（outcomes，可选）
|
||||
→ 闭环（closure）
|
||||
```
|
||||
|
||||
AutoPRD 第 4 章必须用同一套结构写用户故事，而不是「作为…我希望…」宽表。
|
||||
|
||||
### 示例（保险采购 · 交车合规，示意）
|
||||
|
||||
#### US · 保险有效才允许交车
|
||||
- **角色**：采购部、运维部
|
||||
- **起点**：采购或运营维护车辆交强险与商业险台账，作为交车前置合规数据。
|
||||
- **怎么运作**：
|
||||
1. 在保险采购维护一车一档险种台账（录入 / 识别 / 导入）。
|
||||
2. 交车时系统校验交强 + 商业是否均为正常或临期。
|
||||
3. 不合规则拦截交车并给出可理解原因。
|
||||
- **关键结果**：`允许交车` / `禁止交车 · 保险异常`
|
||||
- **闭环**：交车合规与台账一致、可追溯；异常车辆不能进入履约运营。
|
||||
- **排期（可选）**：US-17 · 规模 M · 作为采购/运维，我想维护交强+商业险并在交车时校验，以便不合规车辆无法交车。
|
||||
|
||||
### 反例（不要作为主叙述）
|
||||
|
||||
| 编号 | 用户故事 | SP |
|
||||
|------|----------|----|
|
||||
| B1 | 作为运营，我能看到失败原因 | 2 |
|
||||
|
||||
↑ 信息太扁，缺少起点、协作步骤与闭环结果。
|
||||
|
||||
---
|
||||
|
||||
## AutoPRD 其余层次（仍要对齐）
|
||||
|
||||
1. 一句话 + 目标/非目标
|
||||
2. 模块边界（独立业务线写清「不自动同步」）
|
||||
3. 角色表（命名对齐业务条线）
|
||||
4. **用户故事：起点 / 怎么运作 / 闭环** + SP/规模
|
||||
5. 分模块正逆向
|
||||
6. 关键业务逻辑
|
||||
7. mermaid 流程图
|
||||
8. 验收清单
|
||||
9. 交付口径
|
||||
|
||||
## 刻意不写
|
||||
|
||||
- 表结构、接口、代码路径
|
||||
- 用实现指令代替业务闭环描述
|
||||
78
.cursor/skills/oneos-autoprd/references/release-changelog.md
Normal file
78
.cursor/skills/oneos-autoprd/references/release-changelog.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# 功能变更记录（定稿触发）
|
||||
|
||||
用户回复**需求定稿关键字**后，必须生成「自上次定稿以来」的功能变更日志，追加到 PRD **最下方**，并更新定稿基线。
|
||||
|
||||
## 触发关键字（命中任一）
|
||||
|
||||
`需求定稿` · `定稿` · `确认定稿` · `本次定稿`
|
||||
|
||||
（可带模块名，如「保险采购需求定稿」。）
|
||||
|
||||
## 写什么 / 不写什么
|
||||
|
||||
| 要写（产品发版视角） | 不写 |
|
||||
|----------------------|------|
|
||||
| 哪个功能做了什么修改 | 布局、页面样式、UI 设计优化 |
|
||||
| 变更了什么业务逻辑 / 流程 / 验收口径 | 「优化了哪些表」「改了哪些字段/接口」 |
|
||||
| 用户可感知的交互结果变化 | 纯样式、动效、无语义文案微调 |
|
||||
|
||||
条目口吻示例：
|
||||
|
||||
- 「识别失败」：失败数可点击查看失败文件与原因；仅失败时也可打开明细
|
||||
- 「比价单」：审批通过后仍须在保单管理另行录入正式保单（强调不自动同步）
|
||||
|
||||
## 落点
|
||||
|
||||
1. **PRD 文末章节**（强制）
|
||||
`src/prototypes/<id>/.spec/requirements-prd.md` → `## 10. 功能变更记录`
|
||||
新定稿块插在该章**最上方**（倒序：最新在上）；历史块保留。
|
||||
|
||||
2. **定稿基线**（强制）
|
||||
`src/prototypes/<id>/.spec/autoprd-baseline.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"prototypeId": "insurance-procurement",
|
||||
"lastConfirmedAt": "2026-07-21T12:00:00+08:00",
|
||||
"lastConfirmedLabel": "定稿 · 2026-07-21",
|
||||
"summaryBullets": ["…", "…"]
|
||||
}
|
||||
```
|
||||
|
||||
3. **标注目录**：同步更新「产品需求说明（PRD）」全文节点；若有「PRD 分章」，增加或更新「功能变更记录」分章。
|
||||
|
||||
4. **云效交接**（若本轮同时走云效）：把**本次定稿块**正文作为需求描述「更新内容」；旧「更新内容」挪到「更新内容·历史」。
|
||||
|
||||
## 定稿工作流
|
||||
|
||||
1. 确认 `<prototype-id>`（从对话 / 打开文件 / 用户指名推断）。
|
||||
2. 读现有 PRD 与 `autoprd-baseline.json`（无基线则本轮视为**首版定稿**）。
|
||||
3. 收集自 `lastConfirmedAt` 以来的产品语义变更：
|
||||
对话确认口径 → 批注/操作说明 → PRD 新旧差异 →（可选）相关提交说明。
|
||||
过滤掉样式/表结构类改动。
|
||||
4. 若无功能增量：仍写定稿块，正文为「本轮无功能/逻辑增量（仅样式或未达产品语义变更）」或「首版定稿」。
|
||||
5. 追加 `### 定稿 · YYYY-MM-DD` + 条目列表到第 10 章顶部。
|
||||
6. 更新 `autoprd-baseline.json`；执行 annotation-sync。
|
||||
7. 向用户回报：基线时间、条目数、PRD 路径；若需发云效，提示可用口令。
|
||||
|
||||
## PRD 章节格式
|
||||
|
||||
```markdown
|
||||
## 10. 功能变更记录
|
||||
|
||||
> 产品经理原型发版记录。仅记功能与业务逻辑变更；不含样式/UI/表结构。
|
||||
|
||||
### 定稿 · 2026-07-21
|
||||
|
||||
- 「能力名」：做了什么 / 逻辑如何变
|
||||
- …
|
||||
|
||||
### 定稿 · 2026-07-10
|
||||
|
||||
- …
|
||||
```
|
||||
|
||||
## 与日常改原型的关系
|
||||
|
||||
- **改原型过程中**：按 AutoPRD 主流程增量更新第 1–9 章；**不必**每改一次就写第 10 章。
|
||||
- **用户说定稿时**：才汇总写入第 10 章并刷新基线。
|
||||
163
.cursor/skills/oneos-autoprd/references/template.md
Normal file
163
.cursor/skills/oneos-autoprd/references/template.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# OneOS AutoPRD 输出模板
|
||||
|
||||
复制下列结构填写。方括号为占位。**第 4 章用户故事必须用业务条线说明口径。**
|
||||
|
||||
```markdown
|
||||
# <模块名> · 产品需求说明（全模块）
|
||||
|
||||
## 1. 一句话与目标
|
||||
|
||||
**一句话**
|
||||
<用一句话说明模块解决什么>
|
||||
|
||||
**要解决的问题**
|
||||
- …
|
||||
|
||||
**本期目标**
|
||||
1. …
|
||||
2. …
|
||||
|
||||
**非目标（本期不做）**
|
||||
- …
|
||||
|
||||
## 2. 模块边界（最重要）
|
||||
|
||||
（可选 mermaid：模块与外部系统关系）
|
||||
|
||||
| 业务线 / 子域 | 做什么 | 不做什么 |
|
||||
|---------------|--------|----------|
|
||||
| … | … | … |
|
||||
|
||||
**外部依赖（产品口径）**
|
||||
| 依赖方 | 交互方式 | 产品要求 |
|
||||
|--------|----------|----------|
|
||||
| … | … | … |
|
||||
|
||||
**关键约束**
|
||||
- …
|
||||
|
||||
## 3. 用户与角色
|
||||
|
||||
| 角色 | 主要目标 |
|
||||
|------|----------|
|
||||
| … | … |
|
||||
|
||||
> 角色名优先与「业务条线说明」一致（如业务管理组、采购部、运维部）。
|
||||
|
||||
## 4. 用户故事与故事点（业务条线说明口径）
|
||||
|
||||
> 故事点 / 规模供排期参考，可按团队基准调整。合计约 **N SP**（或 S/M/L 汇总说明）。
|
||||
|
||||
按 Epic 或能力单元分组。**每一条**按下面四块写（对齐业务条线说明页：责任部门 → 起点 → 怎么运作 → 闭环）：
|
||||
|
||||
### Epic A · <名称>（约 N SP）
|
||||
|
||||
#### A1 · <能力标题>
|
||||
- **角色**：…
|
||||
- **起点**：…
|
||||
- **怎么运作**：
|
||||
1. …
|
||||
2. …
|
||||
3. …
|
||||
- **关键结果**（可选）：`可…` / `禁止…`
|
||||
- **闭环**：…
|
||||
- **排期（可选）**：US-xx · 规模 S/M/L · 「作为…，我想…，以便…」
|
||||
|
||||
#### A2 · <能力标题>
|
||||
…
|
||||
|
||||
### Epic B · …
|
||||
|
||||
## 5. 功能模块说明（正向 / 逆向）
|
||||
|
||||
### 5.x <功能名>
|
||||
|
||||
**正向**
|
||||
1. …
|
||||
2. …
|
||||
|
||||
**逆向 / 边界**
|
||||
|
||||
| 情况 | 系统表现 |
|
||||
|------|----------|
|
||||
| … | … |
|
||||
|
||||
## 6. 关键业务逻辑（必须对齐）
|
||||
|
||||
### 6.x <规则名>
|
||||
|
||||
用编号优先级、表格或短列表写清业务规则。
|
||||
|
||||
## 7. 总览流程图
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
home[入口] --> a[能力A]
|
||||
home --> b[能力B]
|
||||
```
|
||||
|
||||
## 8. 验收清单（产品 / 测试）
|
||||
|
||||
**子域 A**
|
||||
- [ ] …
|
||||
|
||||
## 9. 交付口径
|
||||
|
||||
> <一段可贴需求单开头的浓缩描述>
|
||||
|
||||
## 10. 功能变更记录
|
||||
|
||||
> 产品经理原型发版记录。仅记功能与业务逻辑变更；不含样式/UI/表结构。
|
||||
> 由「需求定稿」关键字触发追加；日常改原型不强制每改必写。详见 [release-changelog.md](release-changelog.md)。
|
||||
|
||||
### 定稿 · YYYY-MM-DD
|
||||
|
||||
- 「<能力名>」：<做了什么 / 逻辑如何变>
|
||||
- …
|
||||
```
|
||||
|
||||
成文后**必须**同步 Axhub 标注目录（见 [annotation-sync.md](annotation-sync.md)）：
|
||||
|
||||
1. `src/prototypes/<id>/.spec/requirements-prd.md`
|
||||
2. `annotation-source.json` → 目录节点「产品需求说明（PRD）」（`markdownPath` + `markdown`）
|
||||
3. `src/resources/prd/<id>-autoprd.md`
|
||||
4. 定稿时另写：`src/prototypes/<id>/.spec/autoprd-baseline.json`
|
||||
|
||||
## 用户故事写法（对照业务条线说明）
|
||||
|
||||
业务条线说明页字段 → AutoPRD 字段：
|
||||
|
||||
| 页面 | AutoPRD |
|
||||
|------|---------|
|
||||
| 责任部门标签 | **角色** |
|
||||
| 起点 | **起点** |
|
||||
| 怎么运作（有序列表） | **怎么运作** |
|
||||
| 结果色签 | **关键结果**（可选） |
|
||||
| 闭环 | **闭环** |
|
||||
|
||||
示例口吻（摘自业务条线风格，非照抄某模块）：
|
||||
|
||||
- **起点**：采购部维护交强与商业险台账，作为交车合规的前置数据。
|
||||
- **怎么运作**：1. 运营录入或识别保单… 2. 运维交车时校验…
|
||||
- **闭环**：核心险种有效则允许交车；异常则拦截并提示原因，过程可追溯。
|
||||
|
||||
**不要**用下面这种宽表作为第 4 章唯一形态：
|
||||
|
||||
| 编号 | 作为…我希望… | SP |
|
||||
|------|--------------|----|
|
||||
|
||||
「作为…我想…以便…」只允许作为**排期可选一行**，主叙述必须是起点/怎么运作/闭环。
|
||||
|
||||
## 正逆向写法约定
|
||||
|
||||
- **正向**：用户成功完成任务的最短路径
|
||||
- **逆向**：取消、关闭、禁用、冲突状态、不可操作项
|
||||
- 审批类：写清「本页只读 / 在外部系统办理」
|
||||
|
||||
## 规模与故事点
|
||||
|
||||
| 规模 | 建议含义 | 约 SP |
|
||||
|------|----------|-------|
|
||||
| S | 轻交互 / 列表展示 | 1～2 |
|
||||
| M | 标准流程 + 筛选详情 | 3～5 |
|
||||
| L | 状态机 / 跨模块 / 批量识别 | 6+ |
|
||||
@@ -0,0 +1,44 @@
|
||||
# 云效阶段任务自动创建（AutoPRD 负责）
|
||||
|
||||
本规则写在 **oneos-autoprd**，不依赖改写 `yunxiao-requirement-lifecycle`。
|
||||
凡本 Skill 参与的云效操作中，需求推进到下列状态时，**同一轮必须**建同名任务并正式关联需求。
|
||||
|
||||
## 触发状态
|
||||
|
||||
| 需求推进至 | 任务标签（右侧基础字段） | 负责人 | 任务标题 |
|
||||
|------------|--------------------------|--------|----------|
|
||||
| **分析中** | `分析` | **需求创建人**姓名 | 与需求标题**完全同名** |
|
||||
| **设计中** | `设计` | **需求创建人**姓名 | 与需求标题**完全同名** |
|
||||
| **待开发** | `交付`（若项目无「交付」标签则用 `开发`） | **何斐** | 与需求标题**完全同名** |
|
||||
|
||||
## 强制字段与关系
|
||||
|
||||
1. **正式关联需求**：父子或关联项；只挂标题不算关联。创建后必须在界面上能看到需求 ↔ 任务关系。
|
||||
2. **标签**：写入任务「标签」基础字段（见上表）；标题前缀不能代替标签。
|
||||
3. **创建时间沿用需求**：任务的创建时间（及标签侧可见的创建时间口径）尽量与**需求创建时间**一致。
|
||||
- 平台允许改创建时间 / 用 API 指定时：写成需求的创建时间。
|
||||
- 平台不允许：在任务描述首行注明 `创建时间口径=需求创建时间（YYYY-MM-DD HH:mm）`，并在回报里说明「平台限制未改系统创建时间」。
|
||||
4. **幂等**：同一需求、同一阶段标签下，已存在**未取消**且已正式关联的同名任务 → **不新建**，只校验负责人/标签/关联是否正确，缺则补齐。
|
||||
5. **顺序**：先确认需求已进入目标状态（或本轮动作将写入该状态），再创建/补齐任务；回报时给出任务编号与链接。
|
||||
|
||||
## 执行步骤（apply 时）
|
||||
|
||||
```text
|
||||
1. 读取需求：标题、创建人、创建时间、当前/目标状态、已关联任务列表
|
||||
2. 按上表确定本轮阶段标签与负责人
|
||||
3. 查重（需求ID + 阶段标签 + 未取消）
|
||||
4. 无则创建：标题=需求标题；标签=阶段标签；负责人=上表；创建时间口径=需求创建时间；正式关联需求
|
||||
5. 有则校验并修补标签/负责人/关联
|
||||
6. 回报：需求状态、任务编号、负责人、是否新建/复用
|
||||
```
|
||||
|
||||
## 不在本规则内
|
||||
|
||||
- 不自动建「测试 / 发版」任务（除非用户另行要求）。
|
||||
- 不因样式类 PRD 变更触发建任务；仅**需求状态**进入分析中/设计中/待开发时触发。
|
||||
- 云效生命周期细则、流水线、缺陷闭环仍可由 `$yunxiao-requirement-lifecycle` 配合执行；**本建任务逻辑以 AutoPRD 本文为准**。
|
||||
|
||||
## 与定稿 / 需求说明的关系
|
||||
|
||||
- 写「需求说明 / 更新内容」仍按 AutoPRD 主流程与定稿流程。
|
||||
- 推进到待开发且需要描述时：先 AutoPRD 文档，再改状态，再按本文件建任务（负责人何斐）。
|
||||
Reference in New Issue
Block a user