SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsarkweb-spec-review

arkweb-spec-review

Design & creation

View repository

Updated 10-16 07:28

About this skill

ArkWeb Spec Document Review

Announce at start: "I am using the arkweb-spec-review skill to review the design document."

Run Modes

Mode A: Subagent Mode (Recommended)

When called as an independent subagent by arkweb-architect , the paths to the design document and code analysis results are already provided in the task description; execute the review directly.

Input format (parsed from the task description):

## 待评审文档
{DOCS_REPO}/docs/{date}-{feature}-requirement.md

## 代码分析结果（用于交叉验证）
{DOCS_REPO}/analysis/{date}-{feature}-analysis.md

Reference Materials (read as needed)

  • ACE Engine index: {DOCS_REPO}/analysis/arkweb-ace-engine-analysis.md
  • WebWebView analysis: {DOCS_REPO}/analysis/web-webview-analysis.md

**输出：** 评审报告 → 保存到指定路径 → 回复评审结果摘要

### 模式 B：交互模式

在主 session 中直接调用，评审完成后呈现给用户，用户决定是否修改。

### 模式 C：最小化检视流程（独立检视 + 修改闭环）

适用于**已有设计文档，只需检视和修改**的场景，跳过 brainstorm/code-analysis/design-doc 全链路。

**触发词：** 检视设计文档、review checklist、快速检视

**流程：检视 → 修改 → 复审 → 提 PR**

Step 1: Read the design document + Checklist template Step 2: Perform the 33-item Checklist review (output the results table) Step 3: Are there any blocking items? ├─ No → output "Pass", process ends └─ Yes → modify the design document group by group ├─ Submit one PR per group of modifications ├─ Boss approves and merges ├─ After merging, re-review that group's modifications └─ All pass → process ends


**与模式 A/B 的区别：**
- 不执行完整评审维度检查（5 维度 31 项），仅做 Checklist 33 项检视
- 不依赖代码分析结果交叉验证
- 检视不通过时直接修改文档（而非打回 design-doc skill）
- 每组修改独立提 PR，合并后复审该组，不重跑全量检视

---

## 概述

对已生成的 ArkWeb 设计文档进行系统评审，确保完整性、一致性和技术可行性。

## 评审维度

### 1. 完整性检查（10 项）

- [ ] 需求描述覆盖所有功能点（FR）
- [ ] 非功能需求覆盖（NFR）：性能/安全/兼容性/可测试性
- [ ] 每个章节有实质内容（无空章节/占位符）
- [ ] 包含架构图（ASCII）
- [ ] 包含类图（ASCII）
- [ ] 包含时序图（ASCII）
- [ ] 接口设计有参数表和返回值说明
- [ ] 接口设计有示例代码
- [ ] 测试用例矩阵完整
- [ ] 全量设计待办清单完整

### 2. 一致性检查（6 项）

- [ ] 术语统一（全文中同一概念使用相同术语）
- [ ] 架构描述与类图一致
- [ ] 时序图与接口设计一致
- [ ] 设备差异表与兼容性分析一致
- [ ] 工期估算与方案复杂度匹配
- [ ] 文件路径与实际代码索引一致（交叉验证）

### 3. 技术可行性检查（5 项）

- [ ] 方案涉及的 ArkWeb API 是否已存在（查 ace_engine 分析文档）
- [ ] 涉及的 Chromium 内核修改是否有上游支持
- [ ] OHOS 平台 API 依赖是否在目标版本可用
- [ ] 性能基线是否可达成
- [ ] 兼容性降级方案是否合理

### 4. DFX 完整性（6 项）

- [ ] 可靠性设计（异常处理、重试、降级）
- [ ] 安全设计（权限、沙箱、数据保护）
- [ ] 可扩展性设计（接口预留、插件机制）
- [ ] 可配置性设计（开关、参数）
- [ ] 兼容性设计（版本兼容、向前/向后兼容）
- [ ] 可测试性设计（测试点、自动化方案）

### 5. 文档规范（4 项）

- [ ] 文件命名符合 `{YYYY-MM-DD}-{feature-name}-requirement.md`
- [ ] 关键决策点有 `<!-- architect: ... -->` 注释
- [ ] 1+8 设备差异表完整
- [ ] 工期估算合理

### 6. 接口设计规范（7 项 — 历史纠正项固化）

> ⚠️ **以下为多轮评审反复出现的问题，已固化为强制检查项：**

- [ ] **说明列四段式结构：** 参数表中每个字段的「说明」列必须包含描述/前置条件/规格/异常处理四段，内容过多时引用具体表格或章节。**禁止在表格下方另起独立段落写四段式**（与说明列冗余）。若参数表后有"接口整体规格"段落，仅保留跨字段的全局性说明（如执行语义、公共异常处理），不重复字段级信息。
- [ ] **设备差异表必须用表格：** 即使所有设备均支持，也必须保留表格格式，每个格子填"支持"。**禁止删除表格改为纯文字描述**（如"不涉及。所有设备均支持"）。不支持的设备在对应格标注原因。
- [ ] **字段关联关系：** 参数表后的字段关联关系说明必须存在（互斥/依赖/联动），不得缺失。
- [ ] **接口入参全文档联动：** 当接口入参格式变更（如字段名、类型、结构变化），全文所有引用处必须同步更新，包括但不限于：功能范围表、典型场景示例、架构图 JSON 示例、类图成员变量、时序图、C++ 代码/伪代码、错误码触发场景、DFX 分析、设备矩阵功能点命名、全量特性表。不得残留旧字段名。
- [ ] **方案变更全文档联动：** 当实现方案发生重大变更（如 JS 注入 → C++ DOM API），以下章节必须全部重写/更新：功能概述（实现路径描述）、架构图（内核层描述）、类图（方法命名）、时序图（NWebImpl→Chromium 的调用方式）、C++ 代码（核心 API 调用）、JS 注入模板（删除或改为降级方案）、框架兼容性（新方案的兼容性分析）、伪代码、接口规格汇总（描述中的实现方式）、DFX（安全设计检查等）、演进路线/降级方案。
- [ ] **错误码完整性：** 错误码定义表的触发场景描述必须与实际实现方式匹配。方案变更后（如不再使用 JS 注入），需删除已不适用的错误码（如 ERROR_SETTER_NOT_AVAILABLE），新增方案特有的错误码（如 ERROR_CPP_API_NOT_AVAILABLE），并更新其他错误码的触发场景描述（如"document.evaluate()" → "Document::EvaluateXPath()"）。
- [ ] **术语一致性：** 全文同一概念必须使用相同术语。方案变更后，旧术语（如 setValue/selectOption/ExecuteJavaScript）不得残留，C++ 类成员变量名（如 eventType_）除外。

## 需求检视 Checklist

> 评审流程中嵌入结构化检视环节，使用通用 Checklist 模版（`assets/templates/requirement-design-review-checklist.md`）逐项检查设计文档质量。
> Checklist 为设计文档评审的质量门禁：检视不通过时，要求 design-doc 修改后重新评审。

### Checklist 分类

- **必选（27 项）：** 大部分设计文档需要满足，少量不涉及的可填写不涉及
- **可选（6 项）：** 设计文档中写明不涉及即通过，如涉及则需评审满足度

### 检视时机

在 Step 2 逐项检查完成后、Step 3 输出报告前执行。

### 检视不通过的处理

- 🔴 必选项不满足 → 打回 design-doc 修改，修改后重新走 spec-review
- ⚠️ 可选项涉及但不满足 → 建议修改，不阻塞
- ❌ 必选项不涉及 → 需在说明列给出不涉及理由

### Checklist 模版路径

assets/templates/requirement-design-review-checklist.md


8 大类 33 项：需求分析(5) / 需求规格(3) / KPI&KQI(4) / 模块(3) / 接口(2) / 设计(8) / 可测试性(3) / 安全(5)

---

## 流程

### Step 1: 读取文档

读取待评审文档 + 代码分析结果（用于交叉验证类名、接口签名、文件路径）。

### Step 2: 逐项检查

按上述 5 个维度逐项检查，记录问题。

**交叉验证要点：**
- 设计文档中的类名是否在 ace_engine 分析中存在
- 接口签名是否与 web_webview 分析中的定义一致
- 文件路径是否正确

### Step 2.5: Checklist 结构化检视

基于 `assets/templates/requirement-design-review-checklist.md` 逐项检查，输出 Checklist 结果表：

```markdown
## Checklist 检视结果

| # | 检查项 | 必/可选 | 状态 | 说明 |
|---|--------|---------|------|------|
| 1 | ... | 必选 | ✅/⚠️/❌ | ... |
| ... | ... | ... | ... | ... |

### 检视统计
- 必选满足：N / 27
- 必选不满足：N（阻塞项）
- 必选不涉及：N
- 可选涉及：N / 6
- 可选不涉及：N

### 检视结论
✅ 通过 / ❌ 不通过（N 项必选阻塞）

Decision rules:

  • Required items have no "Not Satisfied" entries → ✅ Pass, proceed to Step 3
  • Required items have "Not Satisfied" entries → ❌ Fail, output the review report and send back to design-doc for modification

Step 3: Output the review report

# {文档名} 评审报告

## 评审结果：{通过 / 需修改 / 不通过}

## Checklist 检视结果

| # | 检查项 | 必/可选 | 状态 | 说明 |
|---|--------|---------|------|------|
| 1 | ... | 必选 | ✅/⚠️/❌ | ... |

### 检视统计
- 必选满足：N / 27 | 必选不满足：N | 必选不涉及：N
- 可选涉及：N / 6 | 可选不涉及：N
- 检视结论：✅ 通过 / ❌ 不通过

## 问题清单
### 🔴 必须修改（含 Checklist 必选不满足项）
1. [描述] - 位置：{章节} - 来源：Checklist #N

### 🟡 建议修改
1. [描述] - 位置：{章节}

### 🟢 优秀实践
1. [描述]

## 统计
- Checklist 总检查项：33（必选 27 / 可选 6）
- Checklist 满足：N | 不满足：N | 不涉及：N
- 评审维度检查项：N
- 通过：N
- 🔴 必须修改：N 项
- 🟡 建议修改：N 项
- 🟢 优秀实践：N 项

Step 4: Closed-loop handling

When the Checklist does not pass (required items have blocking entries)

  • Output the review report, clearly listing the Checklist items that are not satisfied
  • Send back to arkweb-design-doc for modification
  • After modification, go through the spec-review process again

When the Checklist passes but there are issues in the review dimensions

  • 🔴 Must-fix items: send back to design-doc for modification
  • 🟡 Suggested modification items: not blocking, record in the review report

When everything passes

  • Proceed to the next stage (create-sr)

Step 5: Output

Subagent Mode

Save the review report and reply with a result summary. Do not perform modifications (handled by decision 3 of the main session).

Interactive Mode

Present the review results; the user decides whether to modify. After modification, the review can be performed again.

Deliverables

  • Path：{DOCS_REPO}/docs/YYYY-MM-DD-{feature-name}-review.md

Subagent reply format

✅ spec-review 完成
📄 报告：{file_path}
📊 评审结果：{通过 / 需修改 / 不通过}
📋 Checklist 检视：满足 N/33 | 不满足 N | 不涉及 N（必选阻塞 N）
- 总检查项：{N}，通过：{N}
- 🔴 必须修改：{N} 项
- 🟡 建议修改：{N} 项
- 🟢 优秀实践：{N} 项