---
name: tool-schema-validation
description: 阶段产物 Schema 参考资料。介绍各阶段 JSON 结构、PostWrite Hook 自动校验机制和跨阶段一致性规则；具体校验/报告渲染均由 hmos-library-adapter-flutter CLI 内置完成，无需 Agent 主动调用。
---

# 阶段产物 Schema 参考

> **说明**：本 Skill 仅作为字段语义与机制描述的参考资料。实际的 schema 校验、报告生成、
> 跨阶段一致性检查 全部由 `hmos-library-adapter-flutter` CLI 内部实现（已 bundle 进 npm 包），
> 不再依赖 skill 内的 .cjs 脚本与 node_modules。

| 目录 | 内容 |
|------|------|
| `docs/01-analysis-prd.md` | analysis 阶段 PRD 模板（Agent 在写入 `.ohos-adaptation/01-analysis-prd.md` 时参照） |

---

## 各阶段 Schema 文件

Schema 在 `hmos-library-adapter-flutter install` 时由 CLI 释放到本地数据目录：

```
~/.local/share/hmos-library-adapter-flutter/schemas/
├── 01-analysis.schema.json
├── 02-planning.schema.json
├── 03-coding-library.schema.json
├── 04-testing.schema.json
├── 04-test-cases.schema.json
└── 05-summary.schema.json
```

| 阶段 | JSON Schema 文件名 |
|------|-------------------|
| analysis | `01-analysis.schema.json` |
| planning | `02-planning.schema.json` |
| coding-library | `03-coding-library.schema.json` |
| testing | `04-testing.schema.json` |
| summary | `05-summary.schema.json` |

Schema 中 `description` 字段包含每个属性的语义说明。Agent 写入产物前可 Read 对应文件以确认 `required` 字段和 `enum` 取值。

> **附加文档**（特定阶段）：
> - analysis 阶段：PRD 模板 → `{{SKILLS_DIR}}/tool-schema-validation/docs/01-analysis-prd.md`

---

## JSON 产物标准生成流程

每个阶段写入 JSON 产物时，按以下流程执行：

**第一步：读取 Schema**

通过 `~/.local/share/hmos-library-adapter-flutter/schemas/<stage>.schema.json` Read 本阶段 Schema，确认 `required` 字段和 `enum` 取值。

> 本阶段的 JSON 产物是 **输出** 文件，不要在流程一开始就尝试读取（文件可能不存在）。

**第二步：写入 JSON 产物**

使用 `write` 工具一次性写入完整 JSON 文件到 `.ohos-adaptation/` 目录，字段定义严格遵循 JSON Schema。

> **必须** 通过 `write`/`edit` 工具写入，不要用 `bash` + heredoc，否则自动校验不会触发。

**第三步：自动校验、报告生成与修复**

写入后由宿主自动触发 **校验 → 报告生成 → 跨阶段一致性检查**：

- **Claude Code**：`~/.claude/settings.json` 中由 install 自动注入的 PostToolUse hook 会调用 `hmos-library-adapter-flutter validate-on-write`
- **OpenCode**：plugin 内置 `tool.execute.after` 钩子直接同进程调用相同的逻辑

具体动作：
1. **JSON Schema 校验**：用内嵌的 AJV 检查产物是否符合对应 Schema
2. **自动生成 Markdown 报告**：校验通过后从 JSON 数据渲染对应的 `-report.md` 文件（**无需 Agent 手动写入报告**）
3. **跨阶段一致性校验**（仅 `05-summary.json` 时触发）：见下文

校验结果直接显示在工具输出中。若 ❌ 未通过，根据字段路径和错误描述 **立即修改并重新写入**（会再次触发校验和报告生成），循环直到 ✅ 通过。

> **注意**：`-report.md` 文件由 hook 自动生成，Agent **不需要** 手动写入。仅 `01-analysis-prd.md` 和 `INTEGRATION_GUIDE.md`（仅 summary 阶段，hook 也会自动写）保留 Agent 可手动编辑的入口。

**第四步：确认产物完整**

确认本阶段所有产物文件（JSON + 自动生成的 Markdown 报告 + Agent 手动编写的附加文件）均已写入磁盘，缺失则补写。

---

## PostWrite Hook 行为说明

- **触发条件**：通过 `write`/`edit` 工具写入 `.ohos-adaptation/` 下阶段产物 JSON（文件名匹配 `01-analysis.json` … `05-summary.json`）
- **入口实现**：
  - Claude Code：`hmos-library-adapter-flutter validate-on-write` CLI 子命令（由 install 时注入到 `~/.claude/settings.json` 的 PostToolUse hook 触发）
  - OpenCode：plugin 内 `tool.execute.after` 钩子（同进程函数调用，无 bash 开销）
- **JSON Schema 校验**：内嵌的 AJV 2020 校验器（src/cli/lib/schema-validator.ts）
- **自动报告生成**：内嵌的 Handlebars 模板引擎（src/cli/lib/report-renderer.ts），从 src/templates/zh-CN 加载模板
- **跨阶段一致性**：写入 `05-summary.json` 时额外运行 8 项跨阶段检查（src/cli/lib/pipeline-validator.ts）
- **阻塞行为**：始终不阻塞写入操作；Agent 根据输出自行修复

---

## 跨阶段一致性校验规则（仅 `05-summary.json`，8 项）

与 `01`～`04` 产物对照：

| 检查名 | 含义 |
|--------|------|
| `channel_name_consistency` | `03` 中实现的 channel 须在 `01` 的 `channels` 中定义 |
| `plugin_type_skill_consistency` | `02` 与 `03` 的 `plugin_type_skill` 一致 |
| `build_status_propagation` | `05` 的 `build_status` 与 `03` 一致 |
| `example_status_propagation` | `05` 的 `example_status` 与 `04` 的 `example_build_status` 等规则一致 |
| `coverage_math_consistency` | `05` 的 `coverage` 与 `03` 的方法数量一致 |
| `runtime_check_summary_consistency` | `05` 的运行态统计与 `04` 的 `runtime_checks` 一致 |
| `device_test_summary_consistency` | `05` 的设备验证摘要与 `04` 的 `device_test_*` 一致 |
| `quality_score_consistency` | `05` 的 `quality_score` 与编译状态、覆盖率等数据不自相矛盾 |

---

## 工具使用约束（产物写入）

- 产物（JSON / Markdown / 代码）**必须** 通过 `write` 或 `edit` 写入磁盘，**绝不** 将内容输出到对话中代替写入
- 大型 JSON 直接用 `write` 一次性写入，不要用 `bash` + heredoc 拼接

---

## 报告模板体系

报告由 **Handlebars 模板引擎** 渲染。模板源代码（不暴露给 Agent）位于 npm 包内 `src/templates/zh-CN/`，bundle 时内嵌进 CLI。模板按阶段一对一：

| 阶段 | 生成的报告文件 |
|------|---------------|
| analysis | `01-analysis-report.md` |
| planning | `02-planning-report.md` |
| coding-library | `03-coding-library-report.md` |
| testing | `04-testing-report.md` |
| summary | `05-summary-report.md` + `INTEGRATION_GUIDE.md` |

---

## JSON 中的叙事字段

各阶段 Schema 包含若干 **可选叙事字段**（非 `required`）。Agent 应尽量填写以提高报告质量：

| 阶段 | 可选叙事字段 | 说明 |
|------|------------|------|
| analysis | `conclusion` | 分析结论（Markdown），总结适配建议和关键发现 |
| analysis | `example_path` / `example_notes` | Example 路径和功能覆盖说明 |
| analysis | `ohos_readiness.display_status` | 面向报告的状态短标签 |
| analysis | `monorepo_packages[].description` | 子包功能说明 |
| analysis | `core_features[].implementation` | 实现方式（如「纯 Dart」「Platform Channel」） |
| planning | `implementation_strategy.approach_detail` | 详细方案（Markdown，比 `approach` 更详尽） |
| planning | `implementation_strategy.supplemental_sections[]` | 补充段落 |
| coding-library | `overview` | 编码阶段概述 |
| coding-library | `engineering_setup.directory_tree` | ohos 工程目录树文本 |
| coding-library | `architecture_decisions[]` | 关键架构决策记录 |
| testing | `example_build_command` | Example 编译命令 |
| testing | `example_build_artifacts[]` | 构建产物（路径、大小） |
| summary | `summary.plugin_version` | 插件版本 |
| summary | `compilation_fixes[]` | 编译修复记录（合并 03+04） |

---

## 数据架构简述

每个 Flutter 插件的适配信息都集中存放在其仓库根下的 `.ohos-adaptation/` 目录，由 5 个阶段的 JSON 产物 + 自动生成的 Markdown 报告组成。JSON Schema 为结构化产物的 **唯一事实来源**（字段语义、类型约束、枚举值均在 Schema 内 `description` 中定义）。
