# Arkweb Spec Review

> ArkWeb Spec 文档评审。可作为独立 subagent 运行。检查文档完整性、一致性、可行性。触发词：评审设计文档、Spec review、检查设计文档、需求评审。

- Skill: `openharmonyinsight/arkweb-spec-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openharmonyinsight/arkweb-spec-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openharmonyinsight/arkweb-spec-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: openharmonyinsight (https://skillmd.com/u/openharmonyinsight)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openharmonyinsight/arkweb-spec-review

---


# ArkWeb Spec 文档评审

**Announce at start:** "我正在使用 arkweb-spec-review skill 评审设计文档。"

## 运行模式

### 模式 A：Subagent 模式（推荐）

作为独立 subagent 被 `arkweb-architect` 调用时，设计文档和代码分析结果路径已在 task 描述中提供，直接执行评审。

**输入格式（从 task 描述中解析）：**
```
## 待评审文档
{DOCS_REPO}/docs/{date}-{feature}-requirement.md

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

## 参考资料（按需读取）
- ACE Engine 索引：{DOCS_REPO}/analysis/arkweb-ace-engine-analysis.md
- WebWebView 分析：{DOCS_REPO}/analysis/web-webview-analysis.md
```

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

### 模式 B：交互模式

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

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

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

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

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

```
Step 1: 读取设计文档 + Checklist 模版
Step 2: 执行 Checklist 33 项检视（输出结果表）
Step 3: 有阻塞项？
  ├─ 否 → 输出"通过"，流程结束
  └─ 是 → 逐组修改设计文档
         ├─ 每组修改提交一个 PR
         ├─ 老板审批合并
         ├─ 合并后重新检视该组修改项
         └─ 全部通过 → 流程结束
```

**与模式 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 项必选阻塞）
```

**判定规则：**
- 必选无"不满足"项 → ✅ 通过，进入 Step 3
- 必选有"不满足"项 → ❌ 不通过，输出评审报告后打回 design-doc 修改

### Step 3: 输出评审报告

```markdown
# {文档名} 评审报告

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

## 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: 闭环处理

#### Checklist 不通过时（必选有阻塞项）
- 输出评审报告，明确列出 Checklist 不满足项
- 打回 `arkweb-design-doc` 修改
- 修改后重新走 spec-review 流程

#### Checklist 通过但评审维度有问题时
- 🔴 必须修改项：打回 design-doc 修改
- 🟡 建议修改项：不阻塞，记录在评审报告中

#### 全部通过时
- 进入下一阶段（create-sr）

### Step 5: 输出

#### Subagent 模式
保存评审报告并回复结果摘要。不执行修改（由主 session 的决策 3 处理）。

#### 交互模式
呈现评审结果，用户决定是否修改。修改后可重新评审。

## 产出物

- **路径**：`{DOCS_REPO}/docs/YYYY-MM-DD-{feature-name}-review.md`

## Subagent 回复格式

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