ahel
Start free

ArkWeb 设计文档生成

SkillDocs & knowledge

ArkWeb design document generation. Can run as a standalone subagent. Phase 4 produces two documents: requirement.md (requirements baseline review) and design.md (architecture design). Trigger words: write design document, generate requirements review, write feature design, output Spec.

Available today. Use it from your connected AI after setup.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the ArkWeb 设计文档生成 skill

What this skill tells your AI

The instructions your AI receives, as published by openharmonyinsight/openharmony-skills in workflows/arkweb/.aceharness/skills/arkweb-design-doc/SKILL.md and read by ahel’s review.

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 Spectemplate-openharmony-spec.mdAPI 设计 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 输出要求（强制）：

  • 候选子系统（13）、候选部件（38）、关键 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 的自检中新增模板合规检查项，评审前自动扫描以下问题：

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

Signals

GitHub stars
34
Forks
7
Last commit
Sep 2026
Advanced
Catalog kind
skill
Gateway key
arkweb-design-doc
Source
github.com/openharmonyinsight/openharmony-skills

github.com/openharmonyinsight/openharmony-skills

More in Docs & knowledge

canvas-design
Skill · anthropicsdoc-coauthoring
Skill · anthropicstheme-factory
Skill · anthropicsagent-architecture-audit
Skill · affaan-mbrand-voice
Skill · affaan-mck
Skill · affaan-m