# Arkweb Design Doc

> ArkWeb 设计文档生成。可作为独立 subagent 运行。Phase 4 产出两个文档：requirement.md（需求基线评审）和 design.md（架构设计）。触发词：写设计文档、生成需求评审、写功能设计、输出 Spec。

- Skill: `openharmonyinsight/arkweb-design-doc` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openharmonyinsight/arkweb-design-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openharmonyinsight/arkweb-design-doc/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-design-doc

---


# ArkWeb 设计文档生成

**Announce at start:** "我正在使用 arkweb-design-doc skill 生成设计文档。"

## 运行模式

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

作为独立 subagent 被 `arkweb-architect` 调用时，方案和代码分析结果已在 task 描述中提供，直接生成文档。

**输入格式（从 task 描述中解析）：**
```
## 确认的方案
{方案详情：方案类型、架构思路、关键修改点}

## 代码分析结果（读取此文件）
{DOCS_REPO}/analysis/{date}-{feature}-analysis.md

## 参考资料（按需读取）
- proposal 文档：{DOCS_REPO}/docs/features/{feature-name}/proposal.md
- brainstorm 文档：{DOCS_REPO}/docs/{date}-{feature}-brainstorm.md
- 架构参考：{DOCS_REPO}/references/arkweb-architecture.md
- 兼容性检查：{DOCS_REPO}/docs/api-compatibility-check-arkweb.md
```

**输出：** 两个文档 → 保存到指定路径 → 回复文档结构摘要
1. `requirement.md`：需求基线评审文档（模板：`assets/templates/requirement.md`）
2. `design.md`：架构设计文档（模板：`assets/templates/design.md`）

### 模式 B：交互模式

在主 session 中直接调用，用户确认方案后生成文档，生成后请用户审阅。

---

## 概述

基于 brainstorm 阶段确定的方案，按标准模板输出正式设计文档。

> **核心原则：单一方案文档。** 设计文档中只体现最终确认的一个方案，不呈现方案 A/B/C 对比或多方案选型过程。brainstorm 阶段的方案对比分析保留在 brainstorm 文档中，设计文档聚焦于选定方案的完整实现细节。如果某功能存在降级/回退路径（如 CDP 不可用时回退 JS 注入），应在实现方案中作为异常处理章节说明，而非独立方案。

## 知识库驱动规则

通用规则统一引用：`../_shared/KB_RULES.md`。本 skill 的增量要求：

- 设计文档必须在「需求功能设计」或附录提供「知识依据清单」。
- 章节中的关键结论（子系统归属、组件选型、接口建议）必须可追溯到证据包。

## 文档类型

| 阶段 | 模板 | 适用场景 |
|------|------|---------|
| 需求导入检查 | `requirement-import-checklist.md` | 需求刚进入时的 17 项检查 |
| 需求基线评审 | `requirement-baseline-review-template.md` | 正式评审（推荐） |
| 功能设计说明书 | `widget-ai-functional-design.md` | 复杂需求，含 DFX 分析 |
| API Spec | `template-openharmony-spec.md` | API 设计 Spec |

## 流程

### Step 1: 读取参考资料

根据 brainstorm 的方案类型，读取相关文档：
- 兼容性参考：`{DOCS_REPO}/docs/api-compatibility-check-arkweb.md`
- 架构参考：`{DOCS_REPO}/references/arkweb-architecture.md`
- 竞品参考：`{DOCS_REPO}/references/competitor-analysis.md`
- 设备矩阵：`{DOCS_REPO}/references/device-matrix.md`
- 代码索引：`{DOCS_REPO}/analysis/arkweb-ace-engine-analysis.md`
- 代码分析（来自 Sub-2）：`{DOCS_REPO}/analysis/{date}-{feature}-analysis.md`

Step 1 输出要求（强制）：
- 候选子系统（1~3）、候选部件（3~8）、关键 API（5~20），每项附证据来源与置信度
- **【强制持久化】** 证据包 Write 到 `{DOCS_REPO}/tmp/`，详见 `_shared/KB_RULES.md` 第 10 节

### Step 2: 分析项选择（交互模式）或直接填充（Subagent 模式）

#### 交互模式：先列出分析项清单

在生成文档前，先向用户展示模板分析项清单，让用户选择哪些章节需要分析，哪些不需要：

```
📋 模板分析项清单（回复序号，不需要分析的项我会标记"不涉及"）：

1. 诉求方
2. 需求背景（问题背景/现状/目标/技术说明）
3. 竞品分析（各竞品现状/竞品分析总结）
4. 需求描述（功能范围、典型场景、验收标准）
5. 功能点（AR）拆解
6. 功能概述
7. 0层架构设计（周边依赖、进程/线程模型、数据流）
8. 实现方案（架构图/类图/时序图）
9. 接口设计（参数表、类型定义、示例代码，标注内部/外部）
10. 芯片平台和产品约束（1+8 设备差异表，仅有效功能点）
11. 周边依赖关系
12. 安全隐私设计
12. 性能功耗设计（表格格式：性能/内存/功耗）
13. 本地数据库设计
14. DFX 分析（可靠性/基础安全保障/埋点规格/可服务性/可扩展性/可配置/兼容性/可测试性）
15. 其他非功能性分析（分档分级/边界场景矩阵/演进路线）

回复示例：`1-8, 10, 14-15`（跳过 9/11/12/13）
或：`全部分析`
```

用户选择后：
- **选中的项**：正常填充详细内容
- **未选中的项**：仅填写 `> 不涉及`，不展开

#### Subagent 模式：task 描述中指定

在 task 描述中通过 `## 分析项范围` 字段指定，格式同上。若未指定，默认全部分析。

#### 模板结构

Phase 4 产出两个文档，各自使用独立模板：

**【强制】生成文档前，必须先 Read 模板文件，严格按模板的章节结构、中文章节标题、表格格式填充内容。不得自行改为英文结构或英文标题。这是硬性要求，不是建议。**

**1. requirement.md（需求基线评审）**
- **模板：** `{DOCS_REPO}/assets/templates/requirement.md`
- 生成时读取该模板，按以下规则填充：
  - 用户选中的分析项：正常填充详细内容
  - 用户未选中的分析项：仅填写 `> 不涉及`，不展开
  - 模板中 `>` 引用块为格式规范说明，生成时删除

**2. design.md（架构设计）**
- **模板：** `{DOCS_REPO}/assets/templates/design.md`
- 生成时读取该模板，按以下规则填充：
  - 设计元数据：从 proposal.md 和 brainstorm.md 提取
  - 涉及仓和模块：从 code-analysis 结果提取
  - 关键设计决策：从 brainstorm 确认方案中提取
  - 骨架 Spec 拆分：从 requirement.md 接口设计中提取

#### 各章节内容规范

**【需求背景】**（四段式，必选 + 可选）
- **问题背景**（必选）：简要描述原始需求，不讲具体代码
- **现状**（必选）：当前系统/模块的现有能力与不足
- **目标**（必选）：本次需求要达成的目标
- **技术说明**（可选）：涉及的具体代码、API、类名等实现细节

**【竞品分析】**（表格化呈现）
- 必须使用表格列出各竞品，列包含：**竞品 | 功能范围 | 实现方式 | 限制**
- 给出**竞品分析总结**：当前方案对标哪个竞品，还是独立实现
- 竞品分析中**仅体现当前现状**，不体现未来设计实现
- 需求导入如有竞品对标，需设计人员在 AI 分析阶段进行导入

**【需求描述】**
- **功能范围**：只讲具体规格，不讲实现方式。实现仅在实现方案章节呈现
- **典型场景**：每个场景需标明 Web 在场景中的角色（如：被控方/主动方）
- 典型场景中**冗余/重复的场景应去除**
- **验收标准**：通过标准必须关联具体场景上下文，禁止写无场景的模糊描述

**【功能点（AR）拆解】**
- **替代原"工作量评估"**，设计文档中不出现工期/人天估算
- 按功能点列出，包含涉及领域、说明、优先级
- 可附 Phase 分期实施路线图

**【0层架构设计】**（作为 2.0 子章节，位于实现方案内）
- 位于架构上下文之前，展示各领域间的调用关系（明确有周边交互的）
- 必须体现**进程模型**和**线程模型**
- 如有数据传递，给出**数据约束信息**（数据大小、数据类型）及**数据流层图**

**【性能功耗设计】**（表格格式）
- 使用三列表格：维度（性能/内存/功耗）、结论（涉及/不涉及）、说明
- 不涉及就写"不涉及"加简短原因，涉及才展开专项指标

**【DFX 分析】**
- 9.1 可靠性分析：场景/处理方式/返回错误码表格
- 9.2 基础安全保障
- 9.3 DFX 埋点规格：埋点位置/内容/级别/关键词表格，明确标注日志(HiLog)或 trace
- 9.4 可服务性设计：错误码覆盖/DFX 日志/远程排查
- 9.5 可扩展性隔离设计
- 9.6 可配置设计
- 9.7 兼容性设计
- 9.8 可测试性设计：必须包含「不可测试点及解决方案」表格

**【其他非功能性分析】**
- 11.1 分档分级说明：不涉及就写一行说明
- 11.2 边界场景矩阵：表格格式（场景/预期行为/风险）
- 11.3 演进路线：表格格式（方向/说明/阶段）

### Step 3: 自检

- [ ] 用户选中的分析项有实质内容（无空章节）
- [ ] 用户未选中的分析项标记为"不涉及"
- [ ] 文档顶部无日期/版本/状态/变更说明等元数据块
- [ ] 已按离线知识库标准顺序完成检索，并输出候选子系统/部件/API
- [ ] 组件路由通过 `subsystems/*.json -> component_files`，未使用字符串拼路径
- [ ] DeepWiki 仅作为补充证据，未替代离线主证据
- [ ] 文档包含「知识依据清单」，每条证据含来源/对象/路径(或URL)/命中原因/置信度
- [ ] 若"需求背景"被选中：包含问题背景/现状/目标三段（技术说明可选），不含具体代码
- [ ] 若"竞品分析"被选中：使用表格（竞品/功能范围/实现方式/限制）呈现，含对标总结结论
- [ ] 若"需求描述"被选中：功能范围只讲规格不讲实现；典型场景标明 Web 角色；无冗余场景
- [ ] 若"验收标准"被选中：通过标准关联具体场景上下文，无模糊描述
- [ ] 功能点（AR）拆解替代工作量评估，文档中无工期/人天估算
- [ ] 0层架构设计作为 2.0 子章节位于实现方案内
- [ ] 若"0层架构设计"被选中：含进程模型、线程模型；有数据传递时含数据约束和数据流图
- [ ] 若"实现方案"被选中：包含 ASCII 架构图/类图/时序图
- [ ] 若"接口设计"被选中：每个接口标注内部/外部；有参数表和示例代码
- [ ] 若"接口设计"被选中：每个字段说明列包含描述/前置条件/规格/异常处理四段式
- [ ] 若"接口设计"被选中：字段关联关系已说明（互斥/依赖/联动）
- [ ] 若"接口设计"被选中：四段式内容过多时引用具体表格或章节
- [ ] 若"芯片平台和产品约束"被选中：按功能点×设备矩阵格式，仅保留有效功能点
- [ ] 若"性能功耗设计"被选中：使用表格格式（维度/结论/说明），性能/内存/功耗三列
- [ ] 若"DFX 分析"被选中：9.1~9.8 共 8 项全部覆盖
- [ ] 若"DFX 埋点规格"被选中：使用表格（埋点位置/内容/级别/关键词），明确标注日志(HiLog)或 trace
- [ ] 若"DFX 基础安全保障"被选中：包含安全检查项
- [ ] 若"DFX 可服务性设计"被选中：包含错误码覆盖/DFX 日志/远程排查
- [ ] 若"DFX 可测试性"被选中：含「不可测试点及解决方案」表格
- [ ] 若"其他非功能性分析"被选中：11.1 分档分级/11.2 边界场景矩阵/11.3 演进路线
- [ ] 文档中无"刷新到全量设计特性文档"章节
- [ ] 类名/接口名与代码分析结果一致（交叉验证）

## 📋 章节内容职责规则

设计文档只做三件事：**讲清楚为什么做、怎么做、验收标准是什么**。不堆砌实现细节。

### 各章节"该放什么 / 不该放什么"

| 章节 | ✅ 该放 | ❌ 不该放 |
|------|---------|-----------|
| 需求背景 | 问题背景、现状、目标（三段式） | 具体代码/API/类名 |
| 竞品分析 | 表格对比（竞品/场景/实现/限制） | 未来设计实现方案 |
| 需求描述 | 功能范围、典型场景、验收标准 | 实现方式、架构细节 |
| 功能概述 | 关键设计特点、设计约束 | 代码实现链路（5仓库表）、调用链路图、ASCII 详细伪代码 |
| 0层架构 | 进程划分、数据流、核心类关系 | 数据约束表、错误码枚举 |
| 接口设计 | 参数表、错误码、C++ 签名 | 架构图、实现伪代码细节 |
| DFX 埋点 | 埋点内容 + 触发示例 + 全局关键词 | 埋点位置（代码层面）、性能 trace 数据 |
| 可服务性设计 | 错误码覆盖、DFX 日志、远程排查 | |
| 测试方式 | 测试方式、边界场景 | 框架兼容性矩阵、不可测试点 |
| 其他非功能分析 | 分档分级、边界场景矩阵、兼容性说明 | 参考文档索引 |

### 🎯 "最小必要文档"原则

1. **不堆砌实现细节** — 功能概述只讲"设计约束和关键特点"，不放代码实现链路表、仓库级 PR 清单
2. **不重复已有内容** — 已在 brainstorm/analysis/pr 中详述的内容（方案对比、代码索引、竞品对标），设计文档用引用方式关联，不复制
3. **不放参考文档索引** — 附录、参考文档路径不在设计文档中列出
4. **不展示修改历史** — 历史版本的变更记录留在 PR commit message 中，不体现在文档正文

## 🔍 术语规范（强制）

| 场景 | ✅ 正确 | ❌ 错误 |
|------|--------|--------|
| 设计文档类型 | 需求基线评审文档 | 代码实现文档、PR 摘要 |

### 🤖 评审前置自动校验

在 `arkweb-spec-review` skill 的自检中新增**模板合规检查项**，评审前自动扫描以下问题：

```python
checklist = [
    ("章节职责", "0层架构.*数据约束|功能概述.*PR清单|接口设计.*架构图|DFX.*埋点位置"),
    ("最小必要", "附录|调用链路|参考文档|框架兼容性矩阵"),
    ("风险标注", "低|中|高.*无.*风险.*说明"),
]
```

### Step 4: 输出

#### Subagent 模式
保存两个文档并回复结构摘要。不等待用户审阅（由主 session 的决策 2 处理）。

#### 交互模式
输出文档后请用户审阅，修改后重新自检。

## 产出规范

- **目录**：`{DOCS_REPO}/docs/features/{feature-name}/`
- **文件**：
  - `{date}-{feature}-requirement.md`（需求基线评审）
  - `{date}-{feature}-design.md`（架构设计）
- **语言**：中文
- **图表**：ASCII 格式（不依赖外部工具）
- **注释**：关键决策点添加 `<!-- architect: ... -->`
- **元数据**：不要在文档顶部放日期/版本/状态/变更说明等元数据块

## Subagent 回复格式

```
✅ design-doc 完成
📄 requirement.md：{file_path}
📄 design.md：{file_path}
📋 requirement.md 结构：
- 需求描述：{N} 个典型场景，{N} 个验收标准
- 功能点（AR）：{N} 个（P0: {N}, P1: {N}）
- 0层架构：进程模型 ✅ 线程模型 ✅ 数据流 ✅
- 功能设计：架构图 ✅ 类图 ✅ 时序图 {N}个
- 接口设计：{N} 个外部接口，{N} 个内部接口
- 设备矩阵：{N} 个有效功能点 × 6 类设备
- DFX：8/8 维度覆盖，日志 {N} 处，trace {N} 处
📋 design.md 结构：
- 涉及仓：{N} 个
- ADR：{N} 项
- 骨架 Spec：{N} 个 Task
```