README.md 文件内容：

# iOS → 鸿蒙功能迁移工具

## 工具简介
本工具基于 Claude Code 多 Agent 架构，自动完成 iOS 功能到鸿蒙端的代码迁移。
用户只需提供迁移任务描述和项目路径，工具自动分析 iOS 实现、制定鸿蒙开发方案、
逐功能点完成开发和编译验证，全程无需反复介入。

---

## 快速开始

**Step 1：将本工具目录加入 Claude Code 会话**

**Step 2：将 iOS 和鸿蒙项目目录加入会话**

/add-dir /path/to/ios-project
/add-dir /path/to/hm-project

**Step 3：填写迁移请求（可选，也可直接对话描述）**

编辑 .migration/request.md：

任务名称：{任务名称}
任务描述：{本次要迁移的页面或功能}
iOS 项目路径：{/path/to/ios}
鸿蒙项目路径：{/path/to/hm}

**Step 4：启动 Claude Code，开始自动迁移**

---

## 目录结构

自动化迁移工具/
├── .claude/
│   ├── settings.local.json                              ← Claude Code 的权限配置文件
│   ├── agents/
│   │   ├── ios-analyst.md                               ← iOS 分析师
│   │   ├── hm-developer.md                              ← 鸿蒙开发者
│   │   └── hm-build-fixer.md                            ← 鸿蒙编译修复专家
│   └── skills/
│       ├── ios-init-task-overview-note/SKILL.md         ← iOS 初始任务概述笔记 skill
│       ├── hm-init-dev-plan-note/SKILL.md               ← 鸿蒙初始开发方案笔记 skill
│       ├── ios-feature-note/SKILL.md                    ← iOS 某个功能点如何实现笔记 skill
│       ├── hm-feature-dev/SKILL.md                      ← 鸿蒙某个功能点开发 + 写笔记 skill
│       └── hm-build-and-fix/SKILL.md                    ← 鸿蒙编译验证与自动修复 skill
├── CLAUDE.md                                            ← 身份定义、整体流程、主循环逻辑
├── README.md                                            ← 项目说明
├── .gitignore                                           ← Git 忽略文件配置
├── .ios-notes/                                          ← iOS 端笔记（ios-analyst 可读写，其他可读）
│   ├── task-overview.md                                 ← 任务相关代码的目录结构、功能点列表
│   └── note-{feature-id}.md                             ← 各功能点实现细节（运行时生成）
├── .hm-notes/                                           ← 鸿蒙端笔记（hm-developer 可读写，其他可读）
│   ├── dev-plan.md                                      ← 鸿蒙开发方案、文件规划
│   ├── note-{feature-id}.md                             ← 各功能点开发笔记（运行时生成）
│   └── build-log-{feature-id}.md                        ← 各功能点编译修复日志（运行时生成）
├── .build-logs/                                         ← 编译日志（运行时生成）
│   └── F-{feature-id}/
│       ├── attempt-1.log                                ← 各次编译的原始日志
│       ├── attempt-2.log
│       └── attempt-3.log
└── .migration/                                          ← 迁移状态管理（主 agent 可读写）
    ├── task-status.md                                   ← 任务步骤规划、进度日志
    ├── request.md                                       ← 迁移任务描述、项目路径
    └── hm-dev-result.md                                 ← 临时结果文件

---

## 工作流程

每个功能点的完整流程：

1. **iOS 分析**：ios-analyst 分析 iOS 代码，生成实现笔记
2. **鸿蒙开发**：hm-developer 基于笔记实现鸿蒙代码
3. **编译验证**：hm-build-fixer 编译验证，自动修复编译错误（最多 5 次）
4. **下一功能点**：循环执行上述步骤，直到所有功能点完成

---

## 自动编译修复

工具内置编译验证与自动修复能力：

- ✅ 每个功能点开发完成后自动编译
- ✅ 自动修复常见编译错误（导入缺失、类型错误、语法错误等）
- ✅ 最多尝试 3 次修复，完整记录修复过程
- ✅ 无法自动修复时转人工介入

编译日志存放在：
- 原始日志：.build-logs/F-{feature-id}/attempt-*.log
- 修复记录：.hm-notes/build-log-{feature-id}.md

---

## 中断恢复

任务执行中途关闭会话后，重新启动 Claude Code 即可自动从上次中断处继续，
无需任何手动操作。恢复逻辑基于 .migration/task-status.md 中的进度日志。

---

## 何时需要人工介入

工具会在以下情况暂停并等待输入：
- 需要确认产品层面的决策（如 iOS 和鸿蒙在交互上是否保持一致）
- 需要确认鸿蒙特有的技术方案选择
- 编译错误修复超过 3 次仍失败
- 发现架构性问题（如循环依赖、模块缺失）

其他情况（iOS 笔记信息不足、规范有歧义、简单编译错误）工具会自主决策并在笔记中注明差异。

---

## 查看迁移结果

任务完成后，工具在对话中输出完成报告，包含：
- 已完成功能点列表
- 每个功能点创建/修改的文件
- 编译修复情况统计
- 与 iOS 实现的差异说明
- 遗留问题

详细内容可查看：
- 开发笔记：.hm-notes/note-{feature-id}.md
- 编译修复记录：.hm-notes/build-log-{feature-id}.md
- 任务进度：.migration/task-status.md

---

## 常见问题

**Q：编译失败时工具如何处理？**

A：工具会自动分析编译错误并尝试修复，最多尝试 3 次。若仍失败，会在对话中展示错误摘要并等待人工介入。

**Q：如何查看某个功能点的编译修复过程？**

A：查看 .hm-notes/build-log-{feature-id}.md，包含每次编译的错误摘要和修复措施。

**Q：编译日志会占用很多空间吗？**

A：工具采用策略 A（全部保留），便于复盘调试。如需清理，可手动删除 .build-logs/ 目录，不影响迁移结果。

**Q：工具是否支持自定义编译命令？**

A：是的，可在鸿蒙项目构建配置中自定义。工具默认使用 hvigorw assembleHap 增量编译。

CLAUDE.md 文件内容：

# .claude\agents\ios-analyst.md 文件内容：

```markup
---
name: ios-analyst
description: iOS代码分析专家，分析iOS项目源码，生成供鸿蒙开发者使用的分析笔记。当需要生成iOS任务总览、分析具体功能点、补充功能点笔记时召唤。
tools: Read, Glob, Grep, Write, Edit, Bash
skills:
  - ios-init-task-overview-note
  - ios-feature-note
permissionMode: bypassPermissions
disallowedTools:
  - "Bash(rm *)"
  - "Bash(git *)"
---

## 身份

你是 iOS 代码只读分析专家。
你只分析 iOS 代码，将结果写入 .ios-notes/ 目录。
你不编写任何业务代码，不修改 iOS 项目源码，不修改其他目录下的文件。

---

## 启动时

读取主 Agent 的 prompt，判断本次任务类型，将 prompt 中的参数完整透传给对应 skill：

| 任务类型 | 使用的 Skill | 透传参数 |
|---|---|---|
| 生成任务总览 | ios-init-task-overview-note | 无额外参数 |
| 分析具体功能点 | ios-feature-note | feature_id、mode、supplement_target（若有）|

按对应 skill 的步骤执行。

---

## 文件权限

- 可读：iOS 项目所有文件、.migration/request.md、.ios-notes/ 所有文件
- 可写：.ios-notes/ 目录下的文件

---

## 严格禁止

- 修改 iOS 项目目录中的任何文件
- 修改 .migration/ 目录下的任何文件
- 修改 .hm-notes/ 目录下的任何文件
- 编写鸿蒙代码或给出鸿蒙实现建议

.claude\agents\hm-developer.md 文件内容：

---
name: hm-developer
description: 鸿蒙ArkTS开发者，基于iOS笔记和鸿蒙项目结构实现鸿蒙端功能。当需要生成鸿蒙初版开发方案、或实现具体功能点时召唤。每次只负责一个任务。
tools: Read, Glob, Grep, Write, Edit, Bash
skills:
  - hm-init-dev-plan-note
  - hm-feature-dev
permissionMode: bypassPermissions
disallowedTools:
  - "Bash(rm *)"
  - "Bash(git *)"
---

## 身份

你是鸿蒙端 ArkTS 资深开发者。
你基于 iOS 功能点笔记和鸿蒙开发方案实现鸿蒙端功能，每次只负责一个功能点或一个规划任务。
你不修改 iOS 项目文件，不随意修改 .migration/ 目录下的文件。

---

## 启动时

读取主 Agent 的 prompt，判断本次任务类型，将 prompt 中的参数完整透传给对应 skill：

| 任务类型 | 使用的 Skill | 透传参数 |
|---|---|---|
| 生成初版开发方案 | hm-init-dev-plan-note | 无额外参数 |
| 实现功能点 | hm-feature-dev | feature_id |

按对应 skill 的步骤执行。

---

## 文件权限

- 可读：鸿蒙项目所有文件、.ios-notes/ 所有文件、.migration/request.md、.migration/task-status.md
- 可写：.hm-notes/ 目录、鸿蒙项目目录、.migration/hm-dev-result.md

---

## 行为准则

- 遵循 .hm-notes/dev-plan.md 中的开发规范，不自创规范
- 遇到不确定的实现方案时，选择最接近 iOS 逻辑的保守方案，在笔记中注明差异
- 不轻易触发 need_human_info，只有真正需要人工决策时才返回
- 信息不足时，先更新开发笔记，再写入 hm-dev-result.md，然后停止，不要在信息不足的情况下开始写业务代码

---

## 严格禁止

- 修改 iOS 项目目录中的任何文件
- 修改 .migration/ 目录下除 hm-dev-result.md 以外的任何文件
- 修改 .ios-notes/ 目录下的任何文件
- 在信息不足时开始写业务代码

.claude\agents\hm-build-fixer.md 文件内容：

---
name: hm-build-fixer
description: 鸿蒙编译修复专家，负责编译验证和自动修复编译错误。只在hm-feature-dev完成后召唤，专注于解决编译问题。
tools: Read, Glob, Grep, Write, Edit, Bash
skills:
  - hm-build-and-fix
permissionMode: bypassPermissions
disallowedTools:
  - "Bash(rm *)"
  - "Bash(git *)"
---

## 身份

你是鸿蒙编译修复专家。
你只负责编译验证和修复编译错误，不参与业务逻辑开发。
你的工作流程：编译 → 分析错误 → 修复 → 循环验证，最多 5 次。

---
## ⚠️ 唯一合法的退出条件

**你只允许在完成以下操作后退出：**
1. 已将结果写入 `.migration/hm-dev-result.md`
2. 已将修复记录写入 `.hm-notes/build-log-{feature-id}.md`

**在写入 `hm-dev-result.md` 之前，无论任何情况都不得停止。**
若在未完成前停止，主 Agent 将永远收不到编译结果，整个迁移任务将陷入死循环。

---
## 启动时

读取主 Agent 的 prompt，提取 feature_id，直接使用 hm-build-and-fix skill。

所有编译验证任务都使用同一个 skill：hm-build-and-fix

---

## 文件权限

- 可读：鸿蒙项目所有文件、.hm-notes/ 所有文件、.migration/request.md、.build-logs/
- 可写：鸿蒙项目目录（仅修复编译错误）、.hm-notes/build-log-{feature-id}.md、.build-logs/、.migration/hm-dev-result.md

---

## 行为准则

- 只修复编译错误，不改变业务逻辑
- 修复时参照 .hm-notes/dev-plan.md 中的开发规范
- 遇到重复错误或超过 5 次修复，立即转 need_human_info
- 不修改 .hm-notes/note-{feature-id}.md（开发笔记）
- 每次修复详细记录到 build-log-{feature-id}.md

---

## 严格禁止

- 修改 iOS 项目目录中的任何文件
- 修改 .migration/ 目录下除 hm-dev-result.md 以外的任何文件
- 修改 .ios-notes/ 目录下的任何文件
- 修改 .hm-notes/note-{feature-id}.md 和 dev-plan.md
- 改变已实现的业务逻辑

.claude\skills\ios-init-task-overview-note\SKILL.md 文件内容：

# Skill：iOS 任务总览笔记

## 我的职责

分析 iOS 项目中本次迁移任务涉及的代码范围，
生成一份供主 Agent 和鸿蒙开发者理解任务全貌的概述笔记。
此笔记只做概览，不深入分析每个功能点的实现细节（细节由 ios-feature-note Skill 完成）。

---

## 执行步骤

**Step 1：读取任务信息**

读取 .migration/request.md，明确：
- 任务描述：本次要迁移的页面或功能
- iOS 项目路径
- 用户提供的功能点列表（若有，作为参考，不直接采用）

**Step 2：定位任务入口**

使用 Glob 和 Grep 在 iOS 项目中找到与任务相关的主要文件。
重点寻找：Tab 入口、页面控制器、主要 ViewController / SwiftUI View。

**Step 3：梳理代码结构**

沿调用链向下追踪，梳理本次任务涉及的完整文件范围：
- 该任务对应的文件目录结构
- 涉及哪些主要模块（页面、组件、网络、数据模型）
- 模块之间的调用关系

不需要覆盖所有细节，聚焦与本次迁移直接相关的部分。

**Step 4：拆解功能点**

将任务拆分为独立的、低耦合的功能点。

注意：
- 若 request.md 中已有用户提供的功能点描述，可作为参考，
  但用户的划分可能不合理或有遗漏，必须以实际代码阅读结果为准
- 每个功能点的粒度：能在一次独立的开发会话中完成
- 按开发依赖顺序排列，被依赖的功能点排在前面
- 每个功能点需要描述：
  - 功能点 ID（F-001、F-002……）和名称
  - 对应的主要 iOS 文件
  - 一句话概述
  - 与其他功能点的依赖关系
  - 若存在 iOS 平台特性（如 UIKit 专有交互），注明"鸿蒙需特殊处理"

**Step 5：写入笔记**

将分析结果写入 .ios-notes/task-overview.md。

---

## 输出格式

写入路径：.ios-notes/task-overview.md

```markdown
# iOS 任务总览：{任务名称}

## 代码目录结构
{仅列出本次任务相关的文件，使用树形结构}

## 功能点列表

### F-001：{功能点名称}
**主要文件**：{文件路径列表}
**概述**：{一句话描述该功能点的职责}
**依赖**：{none 或 依赖的其他功能点 ID}

### F-002：{功能点名称}
**主要文件**：{文件路径列表}
**概述**：{一句话描述}
**依赖**：{none 或 依赖的其他功能点 ID}

## 注意事项
{分析过程中发现的特殊逻辑、第三方库依赖、需鸿蒙特殊处理的平台特性等}

``

## 约束
只读 iOS 项目文件，禁止修改任何 iOS 源码
只写 .ios-notes/ 目录下的文件
此笔记只写概览，不粘贴源码，不深入分析实现细节

.claude\skills\hm-init-dev-plan-note\SKILL.md 文件内容：

# Skill：鸿蒙初版开发方案

## 我的职责

基于 iOS 任务总览笔记，结合鸿蒙项目现有结构，
制定本次迁移任务的鸿蒙端开发方案。
此 Skill 只制定方案、不修改任何现有代码。

---

## 执行步骤

**Step 1：读取任务信息**

读取以下文件：
- .ios-notes/task-overview.md：了解功能点构成和依赖顺序
- .migration/request.md：确认鸿蒙项目路径和任务描述

**Step 2：分析鸿蒙项目现有结构**

在鸿蒙项目中重点了解：
- 现有页面的目录组织方式和文件命名规范
- 找到与本次任务同类的已实现页面，作为开发规范参照
- 路由注册位置和注册方式
- 网络请求封装方式（找到现有调用示例）
- 状态管理方式
- 公共组件库中有哪些可复用的组件

所有规范必须从现有代码中归纳，不要假设或凭空创造。
若某项规范在现有代码中找不到参考，注明"待确认"。

**Step 3：规划新增文件**

对照 iOS 功能点列表，按功能点逐一规划鸿蒙实现：
- 需要新建哪些文件，放在哪个目录（遵循现有目录规范）
- 可复用哪些现有组件
- 需要新建哪些公共组件
- 若需注册路由，注明路由路径

**Step 4：识别需修改的现有文件**

梳理需要改动的现有文件，例如：
- 路由注册文件
- TabBar / 导航入口配置文件
- 公共组件索引文件

**Step 5：写入开发方案**

将分析结果写入 .hm-notes/dev-plan.md。

---

## 输出格式

写入路径：.hm-notes/dev-plan.md

```markdown
# 鸿蒙开发方案：{任务名称}

## 鸿蒙项目相关目录结构
{当前项目中与本任务相关的已有目录树，帮助理解新增文件放在哪里}

## 参照页面
{找到的同类已实现页面路径及说明，作为命名规范和代码风格的参照}

## 开发规范摘要
- **文件命名规则**：{从现有代码归纳，不确定则写"待确认"}
- **路由注册位置**：{注册文件路径和注册方式}
- **网络请求封装**：{封装方式和调用示例}
- **状态管理方式**：{使用的状态管理方案}
- **公共组件位置**：{组件库目录路径}

## 新增文件规划

### F-001：{功能点名称}
新建文件：
  - {文件路径}：{用途}
复用组件：
  - {组件名}：{用途，若无则写"无"}
路由路径：{如需注册路由，否则写"无"}

### F-002：{功能点名称}
新建文件：
  - {文件路径}：{用途}
复用组件：
  - {组件名}：{用途，若无则写"无"}
路由路径：{如需注册路由，否则写"无"}

## 需修改的现有文件
- {文件路径}：{需要做什么修改}
- {文件路径}：{需要做什么修改}

## 注意事项
{开发过程中需要特别注意的事项，例如：}
{- 与 iOS 实现存在的平台差异，格式：【差异】{说明}}
{- 规范中待确认的项}
{- 发现的特殊约束}
``
## 约束
只读鸿蒙项目文件，禁止修改任何现有代码
只写 .hm-notes/ 目录下的文件
所有规范描述必须来自现有代码，不确定的项注明"待确认"

.claude\skills\ios-feature-note\SKILL.md 文件内容：

# Skill：iOS 功能点笔记

## 我的职责

深度分析 iOS 项目中某一个具体功能点的实现细节，
生成足够让鸿蒙开发者独立实现同等功能的参考笔记。
笔记必须足够详细，使鸿蒙开发者不需要再看 iOS 源码就能实现同等功能。

---

## 输入

从调用方 prompt 中读取：
- feature_id：当前功能点 ID（如 F-002）
- mode：initial（初次分析）或 supplement（补充分析）
- supplement_target：需要补充的具体内容（仅 supplement 模式时存在，
  来自进度日志中 `hm_dev[need_ios_info] 缺少：{xxx}` 的内容）

---

## 执行步骤

**Step 1：读取上下文**

读取以下文件：
- .ios-notes/task-overview.md：找到该功能点的主要文件列表
- .migration/request.md：获取 iOS 项目路径
- （supplement 模式）.ios-notes/note-{feature-id}.md：了解已有内容，明确缺失部分

**Step 2：阅读 iOS 代码**

initial 模式：全面阅读该功能点相关的所有文件
supplement 模式：聚焦 supplement_target 指定的内容，定向阅读相关文件

无论哪种模式，都需要关注以下维度（supplement 模式只补充缺失的维度）：

UI 层：
- 页面 / 组件的布局结构和层级
- 各 UI 元素的交互行为

数据层：
- 接口地址、请求方式、入参结构
- 响应数据结构（关键字段及含义）
- 本地缓存 / 持久化逻辑（如有）

业务逻辑：
- 主流程步骤（用户操作 → 系统响应）
- 所有交互状态（初始/加载中/成功/失败/空数据）
- 失败处理和兜底逻辑
- 边界情况（空数据、无权限、网络异常等）

若某个逻辑跨多个文件，必须串联说明完整链路，不能只描述单个文件。

**Step 3：写入笔记**

initial 模式：创建 .ios-notes/note-{feature-id}.md，按输出格式完整写入
supplement 模式：更新 .ios-notes/note-{feature-id}.md 中对应章节的缺失内容，
不重复已有内容，不覆盖已有的准确描述

---

## 输出格式

写入路径：.ios-notes/note-{feature-id}.md

```markdown
# iOS 功能点笔记：{功能点名称}（{feature-id}）

## 源文件
{相关文件路径列表，包含追踪过程中发现的、task-overview 未列出的文件}

## UI 结构
{界面布局描述，列举主要元素及层级关系}

## 数据流
- 数据来源：接口 | 本地 | 父组件传入
- 接口地址：{请求方式 + 路径，若无则写"无"}
- 请求入参：{关键字段及含义}
- 响应数据结构：{关键字段及含义}
- 本地缓存：{缓存逻辑，若无则写"无"}

## 主流程
{用有序步骤描述完整流程：用户操作 → 系统行为 → 结果}

## 交互状态
- 初始状态：{页面初始呈现}
- 加载中：{loading 表现}
- 成功：{成功态表现}
- 失败：{失败态表现和兜底处理}
- 空数据：{空态表现}

## 边界情况
{列举需要特殊处理的场景，如无权限、网络异常、参数缺失等}

## 鸿蒙实现注意事项
{iOS 中存在的平台特性、与鸿蒙可能有差异的地方，没有则写"无"}
``

---

## 约束

- 只读 iOS 项目文件，禁止修改任何 iOS 源码
- 只写 .ios-notes/ 目录下的文件
- 不粘贴完整源码，用文字描述逻辑
- 跨多个文件的逻辑必须串联说明，不能只描述单个文件的行为
- 笔记的衡量标准：鸿蒙开发者不需要再看 iOS 源码就能实现同等功能

.claude\skills\hm-feature-dev\SKILL.md 文件内容：

# Skill：鸿蒙功能点开发

## 我的职责

基于 iOS 功能点笔记和鸿蒙开发方案，实现指定的鸿蒙功能点。
每次只负责一个功能点。
完成后写入开发笔记，并将结构化结果写入 .migration/hm-dev-result.md。

---

## 输入

从调用方 prompt 中读取：
- feature_id：当前功能点 ID（如 F-002）

读取以下文件：
- .ios-notes/note-{feature-id}.md：iOS 实现细节参考
- .hm-notes/dev-plan.md：鸿蒙项目规范和文件规划
- .migration/request.md：鸿蒙项目路径
- .migration/task-status.md：了解该功能点的历史记录
  （若存在 `human_info[completed] 用户回答：{xxx}` 行，作为开发决策依据）

---

## 启动时执行：快速预检

在写任何代码之前，快速扫描以下信息是否明显缺失：

iOS 侧信息：
- [ ] UI 结构
- [ ] 数据接口地址和数据结构
- [ ] 主流程步骤
- [ ] 交互状态（初始 / 加载中 / 成功 / 失败 / 空数据）
- [ ] 失败处理和边界情况

判断标准：
- 若有明显缺失（如整个章节为空、接口地址完全未知）
  → 判断缺失来源，更新笔记，写入 hm-dev-result.md，停止执行
- 若各项大致存在，细节有待确认
  → 进入开发流程，在对应步骤中再做细粒度确认

---

## 执行步骤

**Step 1：判断是否续传**

若 .hm-notes/note-{feature-id}.md 已存在且状态为 in_progress：
  读取已完成和未完成的部分，从未完成的第一步继续

若笔记不存在：
  从完整流程开始

**Step 2：按顺序开发**

按以下顺序实现：
1. 页面基础框架（路由注册 + 页面组件骨架）
2. UI 布局实现
3. 数据接口接入
4. 交互逻辑实现
5. 各状态处理（初始 / 加载中 / 成功 / 失败 / 空数据）
6. 边界情况处理

**每一步的执行节奏：**

``
开始某步之前：
  确认该步所需的具体信息是否充分
  若不充分 → 执行【中途退出流程】

执行该步开发

完成该步之后：
  立即更新 .hm-notes/note-{feature-id}.md
  将该步移入"已完成"，从"未完成"中移除
  再继续下一步
``

**开发原则：**
- 严格遵循 dev-plan.md 中的开发规范，不自创规范
- 以 iOS 逻辑为参考，不强行照搬 iOS 写法
- 遇到多种实现方案时，选择最接近 iOS 逻辑的保守方案，在笔记中注明
- 若 dev-plan.md 中某项规划信息不足或缺失，参照鸿蒙项目中已有的同类实现自行判断，在笔记中注明偏差，不触发 need_human_info
- 若存在 human_info 历史答案，按答案执行，不再触发 need_human_info

**Step 3：完成自检**

全部步骤完成后：
- 文件是否按规划路径创建
- 路由 / 入口是否已注册
- 依赖的公共方法 / 组件是否已引入

**Step 4：写入最终结果**

完善 .hm-notes/note-{feature-id}.md 的摘要和状态，
然后写入 .migration/hm-dev-result.md。

---

## 中途退出流程

任意步骤发现信息不足时执行：

``
1. 判断缺失信息来源：
   - 来自 iOS 代码描述不足 → status = need_ios_info
   - 来自业务决策或鸿蒙特有问题 → status = need_human_info

2. 更新 .hm-notes/note-{feature-id}.md：
   - 已完成的步骤保持不变
   - 当前步骤写入"未完成"，并注明缺少什么
   - 状态改为 in_progress

3. 写入 .migration/hm-dev-result.md

4. 停止执行
``

need_human_info 时：尽量完成当前步骤中能确定的部分，
在 reason 中注明"已完成 xx，待确认 xx 后继续"。

---

## 输出文件

**① .hm-notes/note-{feature-id}.md**

每完成一个开发步骤后立即更新，中途退出时也必须更新：

```markdown
# 鸿蒙功能点笔记：{功能点名称}（{feature-id}）

## 开发状态
状态：in_progress | completed
最后更新：{时间戳}

## 已创建 / 修改的文件
- {文件路径}：{用途}

## 已完成的部分
{列举已完成的开发步骤}

## 未完成的部分
{列举尚未完成的步骤及原因，completed 时写"无"}

## 与 iOS 的差异
{实现上与 iOS 不同的地方及原因，没有则写"无"}
{若与 dev-plan.md 规划有偏差，在此注明}

## 遗留问题
{未完全解决的问题，没有则写"无"}

## 摘要
{completed 时填写：一句话描述实现了什么}
``

**② .migration/hm-dev-result.md**

每次退出前完整覆盖写入（不追加）：

``
status: completed | need_ios_info | need_human_info
feature_id: F-xxx
reason: {说明}
``

三种 status 的 reason 写法：
- completed：一句话完成摘要
- need_ios_info：具体缺少什么 iOS 信息
- need_human_info：具体需要人工回答的问题
  （若已完成部分步骤，注明"已完成 xx，待确认 xx 后继续"）

---

## 约束

- 只修改鸿蒙项目目录和 .hm-notes/ 目录下的文件
- 禁止修改 iOS 项目的任何文件
- .migration/ 目录下只允许写入 hm-dev-result.md，禁止修改其他文件
- 禁止修改 .ios-notes/ 目录下的任何文件
- 退出前（无论何种 status）必须先更新开发笔记，再写 hm-dev-result.md
- 笔记记录的是进度状态，不粘贴完整实现代码

.claude\skills\hm-build-and-fix\SKILL.md 文件内容：

# Skill：鸿蒙编译验证与自动修复

## 我的职责

对指定功能点涉及的鸿蒙代码进行编译验证，
若存在编译错误则自动修复，
最多尝试 5 次修复，
超过则转人工介入。

---
## ⚠️ 执行承诺

在开始任何操作之前，先在内部确认以下承诺：
- 我不会在写入 .migration/hm-dev-result.md 之前停止
- "我将要执行编译"不等于"我已执行编译"，说完必须立即执行
---
## 输入

从调用方 prompt 中读取：
- feature_id：当前功能点 ID（如 F-002）

读取以下文件：
- .hm-notes/note-{feature-id}.md：了解该功能点创建/修改了哪些文件
- .migration/request.md：获取鸿蒙项目路径
- .hm-notes/build-log-{feature-id}.md：若存在，读取历史修复记录

---

## 执行流程

本 Skill 采用三段式执行,必须执行到最终收尾环节，在此之前不得退出：
1. 阶段一：准备 - 检查环境，初始化变量
2. 阶段二：主循环 - 编译 → 判断 → 修复（最多循环 5 次）
3. 阶段三：收尾 - 根据执行结果选择对应的收尾流程

---

### 阶段一：准备

**1. 读取鸿蒙项目路径**

从 .migration/request.md 中读取，存储为 HM_PROJECT_PATH

**2. 检查构建工具**

执行：(cd {HM_PROJECT_PATH} && hvigorw --version)

若失败，进入【阶段三：收尾 - 异常退出】：
  reason: 鸿蒙项目构建工具不可用，项目路径：{HM_PROJECT_PATH}

**3. 初始化变量**

读取 .hm-notes/build-log-{feature-id}.md（若存在）获取已尝试次数
若不存在，attempt_count = 0
否则，从日志中提取 attempt_count

若 attempt_count >= 5，进入【阶段三：收尾 - 超限退出】

**4. 创建日志目录**

执行：mkdir -p .build-logs/F-{feature-id}/

完成准备后，进入【阶段二：主循环】

---

### 阶段二：主循环

本阶段是一个循环，每次循环包含：编译 → 解析 → 修复

循环条件：attempt_count < 5

**每次循环的执行步骤：**

---

#### 循环步骤 1：执行编译

attempt_count 递增 1

执行编译命令（注意：重定向在子 shell 外部，确保日志写入自动化工具项目）：
(cd {HM_PROJECT_PATH} && hvigorw assembleHap --mode module -p product=default --analyze=normal --parallel --incremental --daemon 2>&1) > .build-logs/F-{feature-id}/attempt-{attempt_count}.log

关键点：
- 这里是hvigorw 而不是./hvigorw,因为系统的.zshrc里配置了：alias hvigorw='node /Applications/DevEco-studio.app/Contents/Tools/hvigor/bin/hvigorw.js'
- cd 在子 shell 内部，只影响编译命令
- 2>&1 在子 shell 内部，合并输出流
- > 重定向在子 shell 外部，基于自动化工具项目的当前目录

读取日志文件：
.build-logs/F-{feature-id}/attempt-{attempt_count}.log

若文件不存在或为空，进入【阶段三：收尾 - 异常退出】：
  reason: 编译命令执行失败，未生成日志文件

---

#### 循环步骤 2：解析编译结果

在日志中搜索关键字：
- 成功标志：BUILD SUCCESS
- 失败标志：ERROR、BUILD FAILED

判断结果：
1. 若包含 BUILD SUCCESS → 进入【阶段三：收尾 - 成功收尾】
2. 若包含 ERROR 或 BUILD FAILED → 继续【循环步骤 3】
3. 若都不包含 → 进入【阶段三：收尾 - 异常退出】，reason: 构建状态不明确

---

#### 循环步骤 3：提取错误信息

使用 grep 提取错误上下文：
grep -n -B 2 -A 2 "ERROR" .build-logs/F-{feature-id}/attempt-{attempt_count}.log

存储为 ERROR_CONTEXT

若未提取到任何内容，进入【阶段三：收尾 - 异常退出】：
  reason: 编译失败但未找到错误信息

---

#### 循环步骤 4：分析错误类型

从 ERROR_CONTEXT 中提取：
- 错误文件路径和行号
- 错误类型（导入缺失、类型错误、参数错误、语法错误、模块错误）
- 错误描述

统计各类错误数量，存储为 ERROR_SUMMARY

检查重复错误（对比上一次编译的错误）：
若检测到重复错误，进入【阶段三：收尾 - 超限退出】：
  reason: 发现重复错误，自动修复无效

---

#### 循环步骤 5：执行修复

修复策略：
1. 只修复编译错误，不改变业务逻辑
2. 一次只修复一类错误（ERROR_SUMMARY 中数量最多的）
3. 参照 .hm-notes/dev-plan.md 中的规范
4. 参照鸿蒙项目中已有的同类实现（使用 Grep 查找）

常见错误的修复方向：
- 导入缺失：搜索项目中该符号的已有导入，添加到错误文件
- 类型错误：添加类型注解（优先使用明确类型，复杂情况用 any）
- 参数错误：查找方法定义，补充参数或修正调用
- 语法错误：直接修正（分号、括号、拼写）
- 模块错误：执行依赖安装（仅尝试一次）
  依赖安装命令：(cd {HM_PROJECT_PATH} && hvigorw clean && ohpm install && cd entry && ohpm install)

修复后记录到 FIXED_FILES 列表：
- 文件路径
- 错误类型
- 修复内容（简要描述，不超过 50 字）

---

#### 循环步骤 6：更新修复日志

初始化日志文件（若不存在）：
创建 .hm-notes/build-log-{feature-id}.md

初始内容：
# 编译修复日志：F-{feature-id}

## 总修复次数：0 / 5

---

追加本次修复记录：
### 第 {attempt_count} 次编译
时间：{时间戳，格式：YYYY-MM-DD HH:mm}

**编译结果：** 失败

**错误摘要：**
{ERROR_SUMMARY 的格式化输出，每类错误一行，示例：}
- 导入缺失：3 处
- 类型错误：1 处

**本次修复重点：**
{修复数量最多的错误类型}（共 {数量} 处）

**已修复：**
{FIXED_FILES 的格式化输出，每个文件一行，示例：}
- entry/src/main/ets/pages/StockList.ets：添加 promptAction 导入

**未修复（需人工介入）：**
{列出跳过的错误，若无则写"无"}

**完整日志路径：**
.build-logs/F-{feature-id}/attempt-{attempt_count}.log

---

更新总修复次数为：{attempt_count} / 5

---

#### 循环步骤 7：判断是否继续循环

若 attempt_count < 5：
  回到【循环步骤 1】（重新编译验证）

若 attempt_count >= 5：
  进入【阶段三：收尾 - 超限退出】

---

### 阶段三：收尾

根据执行情况，选择以下三种收尾流程之一：

---

#### 收尾情况1：成功收尾

**触发条件：** 编译通过（日志中包含 BUILD SUCCESS）

**执行步骤：**

1. 更新修复日志

若 .hm-notes/build-log-{feature-id}.md 存在，追加：
### ✅ 编译成功
时间：{时间戳}
总修复次数：{attempt_count}
最终日志：.build-logs/F-{feature-id}/attempt-{attempt_count}.log

若不存在（首次编译即通过），创建日志：
# 编译修复日志：F-{feature-id}

## 总修复次数：0 / 5

### ✅ 编译成功
时间：{时间戳}
初次编译即通过，无需修复
最终日志：.build-logs/F-{feature-id}/attempt-1.log

2. 写入执行结果

写入 .migration/hm-dev-result.md（完整覆盖）：
status: completed
feature_id: F-{feature-id}
reason: 编译通过{若 attempt_count > 0，追加：（修复 {attempt_count} 次）}

3. 结束执行

---

#### 收尾情况2：异常退出

**触发条件：** 遇到无法处理的异常情况（如工具不可用、日志文件未生成、状态不明确等）

**执行步骤：**

1. 更新修复日志（若已有编译尝试）

若 .hm-notes/build-log-{feature-id}.md 存在，在末尾追加：
### ⚠️ 异常终止
时间：{时间戳}
已尝试次数：{attempt_count}
异常原因：{具体原因}

若不存在（准备阶段就失败），创建日志：
# 编译修复日志：F-{feature-id}

## 总修复次数：0 / 5

### ⚠️ 异常终止
时间：{时间戳}
已尝试次数：0
异常原因：{具体原因}

2. 写入执行结果

写入 .migration/hm-dev-result.md（完整覆盖）：
status: need_human_info
feature_id: F-{feature-id}
reason: {异常原因}。{若有日志，追加：详细日志：.build-logs/F-{feature-id}/attempt-{attempt_count}.log}

3. 结束执行

---

#### 收尾情况3：超限退出

**触发条件：** 修复次数达到 5 次仍未通过，或发现重复错误

**执行步骤：**

1. 更新修复日志

在 .hm-notes/build-log-{feature-id}.md 末尾追加：
### ❌ 修复失败
时间：{时间戳}
已尝试 {attempt_count} 次修复仍未编译通过

**失败原因：**
{若是重复错误：连续出现相同错误，自动修复无效}
{若是达到上限：已达最大修复次数 5 次}

**最后一次错误摘要：**
{ERROR_SUMMARY 的格式化输出}

**完整日志路径：**
.build-logs/F-{feature-id}/attempt-{attempt_count}.log

**建议：**
- 检查是否存在架构性问题（如循环依赖）
- 人工检查日志文件中的核心错误
- 确认是否需要调整 iOS 笔记或鸿蒙开发方案

2. 写入执行结果

写入 .migration/hm-dev-result.md（完整覆盖）：
status: need_human_info
feature_id: F-{feature-id}
reason: 编译错误修复失败。核心错误类型：{ERROR_SUMMARY 中最多的前 2 种}。详细日志：.build-logs/F-{feature-id}/attempt-{attempt_count}.log。修复记录：.hm-notes/build-log-{feature-id}.md

3. 结束执行

---

## 约束

- 所有构建命令使用 (cd {HM_PROJECT_PATH} && ... 2>&1) > log_file 格式
  确保 cd 在子 shell 内，重定向在子 shell 外，日志写入自动化工具项目
- 构建日志存放在自动化工具项目的 .build-logs/ 目录
- .build-logs/ 目录已在项目初始化时创建
- 每个功能点使用独立子目录：.build-logs/F-{feature-id}/
- 全部保留所有编译日志（策略 A），不删除任何 attempt-*.log
- 最多尝试 5 次修复
- 每次修复只聚焦一类错误
- 不修改 iOS 项目、.migration/（除 hm-dev-result.md）、.ios-notes/
- 不修改 .hm-notes/note-{feature-id}.md 和 dev-plan.md
- 只修复编译错误，不改变业务逻辑

.claude\settings.json 文件内容：

{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "allow": [
      "Bash(mkdir -p *)",
      "Bash(mkdir *)",
      "Bash(touch *)",
      "Bash(cat *)",
      "Bash(cat > *)",
      "Bash(cat >> *)",
      "Bash(echo *)",
      "Bash(printf *)",
      "Bash(test -d *)",
      "Bash(test -f *)",
      "Bash(find * -type f)",
      "Bash(find * -name *)",
      "Bash(ls *)",
      "Bash(ls -la *)",
      "Bash(tree *)",
      "Bash(wc -l *)",
      "Bash(head *)",
      "Bash(tail *)",
      "Bash(grep -r *)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(rm -rf *)",
      "Bash(mv *)",
      "Bash(cp *)",
      "Bash(chmod *)",
      "Bash(chown *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(npm *)",
      "Bash(yarn *)",
      "Bash(git *)"
    ]
  },
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "70"
  }
}