Imported from IsKenKenYa/skills (skills/harmonyos/tools/deveco-studio/deveco-native-flow/references/native-plan/SKILL.md). Install upstream with npx skills add IsKenKenYa/skills --skill native-plan. Copyright stays with the author.

Native Plan - 原生开发实施规划专家

基于跨端技术方案（tech-spec.md），生成端级细化实施计划。如果没有 tech-spec，则独立完成完整规划（向后兼容）。只做分析和规划，不写代码，等待用户确认后再开始编码。

核心职责

规划能力

• 需求重述：引用 tech-spec 背景或独立重述需求
• 影响分析：聚焦当前端特有细节（有 tech-spec 时精简跨端分析）
• 架构设计：细化端内实现架构和流程图
• 变更流程：从 tech-spec 子任务出发，细化为端内文件级变更清单（保留端内流程/交互图）
• 分阶段拆解：按依赖关系拆分为可独立交付的阶段
• 风险评估：聚焦当前端特有风险（有 tech-spec 时精简跨端风险）

计划持久化

存储位置

计划文件保存在需求产出物目录下：

.bundle-flow/
├── state.json                          # 全局状态（active + 所有需求）
├── {requirement_id}/                   # 需求产出物目录
│   ├── tech-spec.md                    # 跨端技术方案（native-analyse 产出，如有）
│   ├── plan-{platform}.md              # 端级实施计划（按平台分文件，如 plan-ios.md）
│   └── metadata.json                   # 计划元数据

requirement_id 获取：从 .bundle-flow/state.json 的 active 字段读取当前活跃需求 ID。

文件说明

metadata.json - 计划元数据

{
  "plan_id": "<kebab-case-功能名>",
  "title": "功能名称",
  "status": "draft | confirmed | in_progress | completed",
  "tech_spec_status": "draft | confirmed | null",
  "created_at": "2026-03-24T10:00:00Z",
  "tech_spec_confirmed_at": null,
  "confirmed_at": null,
  "complexity": "high | medium | low",
  "modules": ["module-name-1", "module-name-2"],
  "platforms": ["KMP", "Android", "iOS", "HarmonyOS"],
  "current_phase": 0,
  "total_phases": 4
}

计划生命周期

上下文恢复

执行 /native-plan 时，首先检查是否存在未完成的计划：

1. 读取 .bundle-flow/state.json 获取当前活跃的 requirement_id，扫描 .bundle-flow/{requirement_id}/ 目录，查找 metadata.json 中 status 不为 completed 的计划
2. 如果存在未完成计划：
   • 读取 plan-{platform}.md 恢复完整计划内容（platform 由 --platform 参数指定）
   • 读取 metadata.json 恢复当前进度
   • 向用户展示摘要：计划名称、当前阶段、已完成步骤数
   • 询问用户：继续当前计划 / 废弃并创建新计划 / 修改当前计划
3. 如果不存在未完成计划，正常执行规划流程

执行流程

阶段 0: 上下文恢复 & 平台检测 & tech-spec 检测

目标：检测项目结构、已有计划和 tech-spec.md，确定执行模式

输入来源

native-plan 通过以下来源获取上下文：

项目结构检测：从项目目录自动推断平台和模块信息：

1. 平台检测：扫描项目根目录下的特征文件判断平台
   • build-profile.json5 / oh-package.json5 / hvigorfile.ts → HarmonyOS
   • Podfile / *.xcodeproj / *.xcworkspace → iOS
   • build.gradle.kts / build.gradle / settings.gradle.kts → Android
   • src/commonMain/ / src/nativeMain/ → KMP
2. 模块检测：根据平台特征识别模块目录
   • HarmonyOS：扫描 entry/、features/、commons/ 等目录
   • iOS：扫描 *.xcodeproj、Podfile 中定义的模块
   • Android：扫描 settings.gradle.kts 中 include 的模块
   • KMP：扫描 gradle.properties 和 settings.gradle.kts

必需上下文缺失处理：

1. 尝试恢复：通过项目目录结构推断缺失信息
2. 恢复成功 → 记录恢复来源，继续执行
3. 无法恢复 → 提示用户提供项目路径或指定平台，然后停止执行

参数定义

--platform 解析规则：

if 启动参数包含 --platform:
    → 使用指定的 platform 值
elif 项目中只检测到一个平台:
    → 自动推断为该平台
else:
    → 提示用户必须指定 --platform（使用 AskUserQuestion 让用户选择）

platform 值决定：

• 读取/写入文件名：plan-{platform}.md、delta-plan-{platform}.md
• 从项目结构中筛选该平台的模块列表

操作清单

• 解析 --platform 参数

  按上述规则确定目标平台。

• 读取上下文

  1. 读取 .bundle-flow/state.json 获取当前活跃的 requirement_id
  2. 通过项目目录结构检测平台和模块列表
  3. 读取 .bundle-flow/{requirement_id}/tech-spec.md（如有）

• 加载 HarmonyOS 知识（当平台为 HarmonyOS 时）

  当检测到目标平台为 HarmonyOS 时，加载以下内部知识文件以确保架构设计和变更清单符合 ArkTS 规范和 Kit API 约束：

  1. 读取 references/lang-syntax/SKILL.md — ArkTS 语法规范和核心约束（必须加载）
  2. 根据需求涉及的功能领域，按需读取 references/kits_*/SKILL.md：
     • UI 场景：references/kits_ui/SKILL.md
     • 网络请求：references/kits_network/SKILL.md
     • 数据存储：references/kits_data/SKILL.md
     • 媒体相关：references/kits_media/SKILL.md
     • 其他 Kit 根据需求关键词匹配加载
  3. 根据需求涉及的基础 UI 组件，按需读取：
     • 基础组件：references/component_basic_ui/SKILL.md
     • 容器组件：references/component_container/SKILL.md

  时机要求：必须在阶段 3 架构设计之前完成，确保 ArkTS 语法规范和 Kit API 可用于设计决策和变更清单编写。

• 扫描已有计划

  读取 .bundle-flow/state.json 获取当前活跃的 requirement_id，扫描 .bundle-flow/{requirement_id}/ 目录，查找 metadata.json 中 status 不为 completed 的计划，然后检查 .bundle-flow/{requirement_id}/metadata.json 是否存在。

• 检查未完成计划

  如果存在 metadata.json，读取并检查 status 字段：

  • draft：计划已生成但未确认，提示用户确认或重新规划
  • confirmed：计划已确认但未开始，提示用户开始实施
  • in_progress：计划正在实施中，读取 metadata.json 展示当前进度

• 检测 tech-spec.md

  在同一 requirement_id 目录下检查 tech-spec.md 是否存在：

  • 存在且已确认（tech_spec_status: confirmed）→ 进入精简模式：阶段 1/2/3 引用 tech-spec，阶段 4 从 tech-spec 子任务出发细化
  • 存在但未确认 → 提示用户先确认 tech-spec（参考 references/native-analyse/SKILL.md）
  • 不存在 → 进入完整模式：按原有流程独立完成全部阶段（向后兼容）

  检测到跨端技术方案: [功能名称]
  - tech-spec 状态: confirmed
  - 涉及平台: [平台列表]
  
  将基于技术方案进行端级细化（精简模式）。

• 展示恢复摘要（如有未完成计划）

  发现未完成的计划: [功能名称]
  - 状态: [当前状态]
  - 当前阶段: 阶段 X / 共 Y 阶段
  - 已完成: M / N 步骤
  
  选择操作:
  1. 继续当前计划 (continue)
  2. 废弃并创建新计划 (discard)
  3. 修改当前计划 (modify)

• 根据用户选择执行

  • continue：跳转到当前进行中的阶段，继续实施
  • discard：将当前计划 status 设为 completed（标注废弃），开始新的规划
  • modify：加载当前计划，进入修改模式

• 检测变更模式

  检查是否由 /flow change 触发（通过启动参数或上下文判断）：

  模式	触发条件	行为
  正常模式	直接调用 /native-plan	产出 plan-{platform}.md，原地写入
  增量模式	--delta round-{N} 参数（场景 A）	读取原 plan-{platform}.md 作为基线 + delta-spec.md，只列增量子任务，产出 changes/round-{N}/delta-plan-{platform}.md
  修改模式	--change "变更描述" 参数（场景 B）	读取现有 plan-{platform}.md + 变更描述，原地覆盖 plan-{platform}.md

  增量模式：

  1. 读取原 plan-{platform}.md 作为基线
  2. 读取 changes/round-{N}/delta-spec.md（增量技术方案）作为输入
  3. 只列增量子任务：新增的 + 需要修改的，标注与原 plan 子任务的关系
  4. 阶段 1-3 精简执行（引用原 plan 的需求重述/影响分析/架构，只展示 diff）
  5. 阶段 4 变更流程只生成增量子任务的变更清单
  6. 产出写入 changes/round-{N}/delta-plan-{platform}.md（格式见 flow/SKILL.md 场景 A）
  7. 不修改原 plan-{platform}.md

  修改模式：

  1. 读取现有 plan-{platform}.md 作为起点（不从零开始）
  2. 将变更描述作为额外上下文注入阶段 1 需求重述
  3. 阶段 2-5 中逐段评估是否需要修改，未受影响的部分保持不变
  4. brain-storm 式确认每个修改点
  5. 修改完成后原地覆盖 plan-{platform}.md（flow change 已在修改前做了快照备份）

• 检测失效状态

  读取 state.json，检查 plan 是否在 invalidated_phases 中：

  • 是：提示"实施计划已被标记失效（上游技术方案已变更），需要重新生成计划"
  • 读取已更新的 tech-spec.md，进入正常 plan 流程
  • 完成后从 invalidated_phases 移除 plan，加回 completed_phases

阶段 1: 需求重述

目标：明确需求内容，消除歧义，建立共识

精简模式（有 tech-spec）

直接引用 tech-spec 的"一.背景"章节，补充当前端的特定上下文：

• 引用 tech-spec 背景

  • 引用 tech-spec 中的需求概要、成功标准、范围边界
  • 标注当前 native-plan 针对的平台：[iOS / Android / HarmonyOS]

• 补充端级上下文

  • 当前端有无特殊的需求差异或约束
  • 如无差异，直接进入下一阶段

完整模式（无 tech-spec）

• 读取需求输入

  • 如果是文件路径：使用 Read 工具读取文档内容
  • 如果是描述文本：直接进行分析

• 重述需求

  • 用 2-3 句话清晰描述要做什么
  • 列出成功标准（可量化、可验证的结果）
  • 列出假设和约束（平台限制、技术限制、时间限制等）

• 明确范围边界

  • 明确包含哪些功能
  • 明确不包含哪些功能（避免范围蔓延）
  • 标注需要用户进一步确认的歧义点

阶段 2: 影响范围分析

目标：分析当前端的影响范围和特有细节

精简模式（有 tech-spec）

跨端通用的影响分析已在 tech-spec 中完成，此处聚焦当前端特有的细节：

• 引用 tech-spec 影响分析

  • 引用 tech-spec "二.现有流程" 中与当前端相关的部分
  • 引用 tech-spec "2.2 各端实现现状" 中当前端的行

• 补充端级特有分析

  • 当前端的模块内部依赖关系
  • 当前端特有的技术约束（如 iOS 审核限制、Android 碎片化、HarmonyOS ArkTS 限制等）
  • 当前端特有的代码结构或设计模式

• 列出当前端涉及的模块

  模块 ID	修改内容	备注
  module-name	[修改说明]	[端特有说明]

完整模式（无 tech-spec）

• 检查模块定位结果

  如果当前会话中已有模块定位结果（通过项目目录检测或上游产出），引用其定位结果：

  • 涉及的模块列表
  • 平台分布
  • 依赖层次

  如果尚未确定，根据需求关键词和项目结构进行初步分析。

• 现有流程分析

  针对涉及的模块，梳理现有的技术架构和业务流程：

  • 现有架构图：绘制当前相关模块的架构关系图
  • 现有流程图/交互图：梳理当前业务流程的调用链路和交互时序
  • 核心代码逻辑：结合项目知识库和源码，说明关键代码路径
  • 请求/接口清单：列出现有相关的请求和接口（如有）

  | 模块 | 现有流程 | 核心代码路径 | 说明 |
  |------|---------|-------------|------|
  | `module-name` | [流程描述] | `path/to/core/Class.kt` | [说明] |

  来源：结合项目知识库（.knowledge/）和源码分析。 知识库不足时，直接读取相关源码补充。

• 分析平台影响

  确定涉及的平台及修改范围：

  平台	是否涉及	修改范围
  KMP（跨平台共享层）	是/否	[具体说明]
  Android	是/否	[具体说明]
  iOS	是/否	[具体说明]
  HarmonyOS	是/否	[具体说明]

• 分析模块依赖层次

  根据项目结构分析修改顺序：

  层次	类型	涉及模块	修改原则
  底层核心层	被广泛依赖	[模块列表]	优先修改，保持向后兼容
  中间业务层	依赖底层，被顶层依赖	[模块列表]	等底层发布后再修改
  顶层应用层	依赖中间层和底层	[模块列表]	最后修改

• 查阅项目知识库

  使用 Glob/Grep 查询相关项目知识文档：

  • <project>/.knowledge/ - 项目知识库（架构、规范、业务逻辑等）
  • 项目根目录的 CLAUDE.md、README.md 等文档

阶段 3: 架构设计

目标：设计当前端的实现架构

交互规则（强制）

架构设计分为两轮交互，禁止一次性输出全部内容：

第一轮：端内架构设计

• 展示端内架构图、流程图、模块关系（精简模式引用 tech-spec 后补充端特有部分）
• 展示后停下来等用户确认
• 用户可能提出修改意见 → 调整后重新展示

第二轮：技术选型（如有端特有决策点）

• 每个决策点给出 2-3 个可选方案 + 推荐
• 每个决策点单独等用户选择，选完再进入下一个

脑暴原则贯穿：端内架构设计中遇到不确定的实现方式（如 MVVM vs MVC、Compose vs XML、ArkUI vs 声明式等），停下来给选项让用户决定。

精简模式（有 tech-spec）

跨端通用的架构设计已在 tech-spec 中完成，此处聚焦当前端的实现架构：

• 第一轮：端内架构（展示后等确认）

  引用 tech-spec "三.整体设计" 中的目标架构和技术选型作为基础，在此之上细化：

  • 端内架构图：当前端内部模块的实现架构（如 iOS 的 MVVM/MVC 结构、HarmonyOS 的 ArkUI 组件结构）
  • 端内流程图：当前端的具体调用链路和页面导航
  • 框架/组件选型：当前端使用的具体 UI 框架、状态管理方式等

  展示后停下来，询问用户：端内架构设计是否 OK？

• 第二轮：端特有技术决策（逐个等确认）

  如有端特有的决策点，逐个展示并等待用户选择：

  决策点	选择	理由
  [端特有决策]	[选择]	[理由]

  无端特有决策时跳过此轮，直接进入阶段 4。

完整模式（无 tech-spec）

• 第一轮：架构全景（展示后等确认）

  基于阶段 2 的现有流程分析，设计目标状态的整体架构：

  • 目标架构图：绘制优化后的模块架构关系图，与现有架构形成对比
  • 目标流程图/交互图：绘制优化后的业务流程和交互时序
  • 模块间关系：说明模块间的依赖方向和数据流向
  • 与前后台交互：说明前端与后端服务的交互方式（如涉及）

  此阶段关注宏观全貌，具体的数据模型和接口契约在阶段 4 的子任务中按需定义。

  展示后停下来，询问用户：架构设计是否 OK？

• 第二轮：技术选型（逐个决策点等确认）

  针对需求中的每个关键决策点，逐个展示可选方案并等待用户选择：

  决策点: [例：状态管理]
  
  方案 A: [描述]（推荐）
  - 优点: ...
  - 缺点: ...
  
  方案 B: [描述]
  - 优点: ...
  - 缺点: ...
  
  推荐: 方案 A — [理由]
  → 等待用户选择后，再展示下一个决策点

阶段 4: 变更流程

目标：按模块维度细化子任务的端内实现方案和文件变更清单

交互规则（强制）

按模块逐个展示，每个模块的变更方案展示后必须等用户确认再继续下一个。 禁止一次性输出所有模块的变更。

展示模块 A 的全部子任务 → 等用户确认（OK / 调整）
展示模块 B 的全部子任务 → 等用户确认
...
全部模块确认后 → 展示配置变更 + 验证点汇总 → 等最终确认

脑暴原则贯穿：

• 子任务的实现方案如有多种可行路径，给出选项让用户选择
• 变更清单中涉及的架构决策（新建文件 vs 扩展现有文件、继承 vs 组合），遇到不确定时停下来问用户
• 用户确认某个模块后，如果后续模块发现需要回调之前的设计，主动提出

精简模式（有 tech-spec）

从 tech-spec 的子任务出发，细化为当前端的具体实现。保留端内流程/交互图，确保看 native-plan 时不需要回翻 tech-spec。

每次只展示一个模块的全部子任务：

#### 模块: `module-name` (平台: [当前端])

##### 子任务 1: [引用 tech-spec 四.4.N 的任务名称]

**来源**: tech-spec → 四.子任务拆分 → 4.N

**跨端契约**（引用 tech-spec）：
- 数据模型：[引用 tech-spec 中的通用模型]
- 接口契约：[引用 tech-spec 中的通用接口]
- 事件/回调：[引用 tech-spec 中的通用事件]

**端内流程/交互图**：
[当前端的具体流程和交互时序，非跨端通用视角]

**端内实现方案**：
- 实现逻辑：[当前端具体怎么实现，如 SwiftUI/Compose/ArkUI]
- 数据层：[端内数据类/结构体定义]
- UI 层：[端内视图组件实现]
- 错误处理：[端内异常处理方式]

**端特有处理**：
- [tech-spec "各端差异提示" 中标注的该端差异的具体落地方案]

**变更清单**：
| 操作 | 文件路径 | 修改内容 | 依赖 |
|-----|---------|---------|------|
| 新增 | `path/to/NewFile.swift` | 新增 XxxViewController | 无 |
| 修改 | `path/to/ExistingFile.swift` | 在 viewDidLoad() 中增加 xxx | 步骤 1 |

**产出**：
- [该子任务在当前端的产出]

##### 子任务 2: [引用 tech-spec 四.4.M 的任务名称]
...（重复上述结构）

→ 这个模块的变更方案 OK 吗？需要调整吗？

完整模式（无 tech-spec）

每次只展示一个模块的全部子任务：

以模块为单位，将每个模块的改动拆分为若干子任务。 子任务粒度原则：每个子任务完成一个完整且单一的事情，不过度拆分。

#### 模块: `module-name` (平台: KMP/Android/iOS/HarmonyOS)

##### 子任务 1: [任务名称，如：新增确认弹窗 UI]

**流程/交互图**（如有）：
[描述该子任务涉及的流程或交互]

**前置依赖**：
- [依赖的 API、数据模型、其他模块产出等]

**核心实现方案**：
- 数据模型：[按需定义该子任务涉及的模型]
- 接口契约：[按需定义该子任务涉及的接口]
- 实现逻辑：[核心代码逻辑概要，伪代码或自然语言描述]
- 错误处理：[异常场景的处理方式]

**变更清单**：
| 操作 | 文件路径 | 修改内容 | 依赖 |
|-----|---------|---------|------|
| 新增 | `path/to/NewFile.ets` | 新增 XxxService 实现类 | 无 |
| 修改 | `path/to/ExistingFile.ets` | 在 doSomething() 中增加 xxx 逻辑 | 步骤 1 |

**产出**：
- [该子任务完成后输出什么：数据/API/组件等，供后续子任务使用]

##### 子任务 2: [任务名称]
...（重复上述结构）

→ 这个模块的变更方案 OK 吗？需要调整吗？

通用操作（两种模式共用，全部模块确认后执行）

操作类型：

• 新增：创建新文件（类、接口、资源等）

• 修改：变更已有文件的特定方法或配置

• 删除：移除废弃的文件或代码（需说明原因）

• 梳理配置和资源变更

  除代码文件外，检查是否需要变更：

  • 构建配置（build.gradle.kts、Podfile、build-profile.json5、oh-package.json5 等）
  • 资源文件（布局 XML、strings、图片资源等）
  • 依赖声明（新增或升级第三方库）
  • 混淆规则（ProGuard/R8 keep rules）

• 确定变更验证点

  每个模块变更完成后的验证方式：

  模块	验证方式	验证标准
  module-name	编译通过 + 单元测试	[具体标准]
  module-name	集成测试 + UI 验证	[具体标准]

  展示配置变更 + 验证点后，等用户最终确认，进入阶段 5。

阶段 5: 分阶段实施计划

目标：基于阶段 2-4 的分析结果，按依赖顺序组织为可独立交付的阶段

原生开发阶段模板

根据跨平台依赖关系，按以下模板组织阶段：

Phase 1: 底层核心层（KMP/Rust）

• 适用于有跨平台共享逻辑的需求
• 按阶段 4 中底层模块的子任务顺序执行
• 底层修改需保持向后兼容

Phase 2: 平台适配层

• 按阶段 4 中各平台模块的子任务顺序执行
• 各平台可并行开发

Phase 3: UI 层实现

• 按阶段 4 中各平台 UI 相关子任务执行
• Android: Compose/XML 布局
• iOS: SwiftUI/UIKit 视图
• HarmonyOS: ArkUI 组件

Phase 4: 测试验证

• 按阶段 4 中各模块的验证点执行
• 单元测试（各平台）
• 集成测试（跨平台交互）
• 多端一致性验证

每步的信息结构

每个具体步骤直接引用阶段 4 的子任务：

1. **[子任务名]** (模块: xxx, Phase: N)
   - 来源: 阶段 4 → 模块 `xxx` → 子任务 M
   - 前置依赖: 无 / 依赖步骤 X
   - 风险: 低/中/高
   - 验证: [引用阶段 4 的验证标准]

阶段拆分原则

• 每阶段可独立交付和验证
• 按依赖顺序排列（底层 → 中间 → 顶层）
• 同层级的平台适配可并行
• 步骤直接对应阶段 4 的子任务，不重复描述实现细节

阶段 6: 风险评估

目标：识别潜在风险并提供应对方案

精简模式（有 tech-spec）

跨端通用风险已在 tech-spec "五.三板斧" 中覆盖，此处聚焦当前端特有风险：

• 端特有兼容性风险

  • 当前端最低支持版本是否支持所需 API
  • 当前端特有的 API 差异或废弃接口
  • 当前端的设备碎片化问题（如 Android 多厂商适配、HarmonyOS API 版本差异）

• 端特有性能风险

  • 当前端的 UI 渲染性能（如 iOS 的主线程阻塞、Android 的过度绘制、HarmonyOS 的 ArkUI 渲染）
  • 当前端的内存/启动时间影响

• 端特有构建/发版风险

  • 模块依赖版本冲突
  • 基线版本锁定
  • 审核风险（如 iOS App Store 审核、HarmonyOS 应用市场审核）

完整模式（无 tech-spec）

• 跨平台兼容性风险

  • KMP 模块修改是否影响所有平台
  • 各平台 API 差异是否需要特殊处理
  • 版本兼容性（最低支持版本）

• 模块依赖冲突风险

  • 修改底层模块是否影响其他依赖方
  • API 接口变更是否需要联动修改
  • 发版顺序是否有约束

• 性能风险

  • HarmonyOS 特殊流程（先拉 Portal 再 sync）
  • 大数据量场景下的性能表现
  • UI 渲染性能（列表、图表等）

• 基线版本兼容性

  • 当前基线版本是否支持所需 API
  • 是否需要等待依赖方发版
  • 是否存在基线锁定问题

风险等级标准

阶段 7: 输出计划、持久化并等待确认

目标：输出结构化的实施计划，持久化到本地文件，等待用户确认

操作清单

• 生成计划 ID

  使用功能名称的 kebab-case 形式，例如 trade-confirm-dialog。

• 输出计划到会话

  按下方输出格式，将完整计划内容输出到会话中，供用户即时查看和确认。 此时不写入本地文件，仅在会话中展示。

• 等待用户确认

  必须使用 AskUserQuestion 工具向用户展示以下四个选项，禁止直接在文本中输出选项后自行继续：

  请确认此实施计划：

  1. yes — 计划无误，持久化到本地文件，可以开始编码
  2. modify — 计划整体方向正确，但部分内容需要调整（请说明哪里需要改）
  3. supplement — 计划缺少某些需求场景或约束，需要增量补充
  4. no — 计划方向有问题，废弃当前计划

  各选项处理：

  • yes：进入"确认后持久化"步骤
  • modify：根据用户反馈调整计划中已有内容，重新输出完整计划，再次展示选项等待确认
  • supplement：执行增量补充流程（见下方）
  • no：废弃当前计划，流程结束

• supplement 增量补充流程

  当用户选择 supplement 时，按以下步骤执行：

  1. 接收补充内容：让用户描述遗漏的需求点、场景或约束

  2. 交互式澄清：复用核心原则第6条的交互式决策确认（每次只问一个问题、优先选择题、智能跳过），确保补充内容清晰无歧义

  3. 评估影响范围：分析补充内容对已有计划各章节的影响，向用户展示：

     补充内容: [摘要]
     
     影响评估:
     - [ ] 一.需求重述 — [需要/不需要] 更新
     - [ ] 二.影响范围分析 — [需要/不需要] 更新，原因: [xxx]
     - [ ] 三.架构设计 — [需要/不需要] 更新，原因: [xxx]
     - [ ] 四.变更流程 — [需要/不需要] 更新，原因: [新增子任务/修改现有变更清单]
     - [ ] 五.实施阶段 — [需要/不需要] 更新，原因: [新增步骤/调整依赖顺序]
     - [ ] 六.测试策略 — [需要/不需要] 更新
     - [ ] 七.风险与应对 — [需要/不需要] 更新

  4. 增量更新：按影响范围逐章节更新，每个受影响的章节标注 [补充] 标记，方便用户识别变更点

  5. 重新输出完整计划：输出更新后的完整实施计划，再次使用 AskUserQuestion 展示四个选项等待确认

• 确认后持久化

  用户确认（yes）后，根据执行模式写入不同位置：

  正常模式 / 修改模式：

  1. .bundle-flow/{requirement_id}/plan-{platform}.md — 完整实施计划（platform 由 --platform 参数指定）
  2. .bundle-flow/{requirement_id}/metadata.json — 读取-合并-写入：先 Read 现有 metadata.json（不存在则初始化 {}），只更新 native-plan 负责的字段（plan_id、title、status 设为 confirmed、confirmed_at 设为当前时间、complexity、modules、platforms、current_phase、total_phases），保留其他字段（如 tech_spec_status、tech_spec_confirmed_at）不变，再 Write 回
  3. 更新 state.json — current_phase: "plan"，completed_phases 追加 "plan"
  4. 修改模式下若 plan 在 invalidated_phases 中，移回 completed_phases

  增量模式：

  1. .bundle-flow/{requirement_id}/changes/round-{N}/delta-plan-{platform}.md — 增量实施计划
  2. 不修改原 plan-{platform}.md 和 metadata.json
  3. 不更新 state.json 的 completed_phases（增量模式不改变原有阶段状态）

  持久化完成后，提示开始实施计划（增量模式提示执行增量编码）。

输出格式

# 实施计划: [功能名称]

> Plan ID: `<plan-id>`
> 状态: draft
> 创建时间: YYYY-MM-DDTHH:mm:ssZ
> 预估复杂度: 高/中/低

## 一. 需求重述

### 1.1 需求概要
[2-3 句总结需求要点]

### 1.2 成功标准
- [可量化、可验证的结果]

### 1.3 范围边界
- 包含：[明确包含的功能]
- 不包含：[明确不包含的功能]

## 二. 影响范围分析

### 2.1 涉及模块

| 模块 ID | 平台 | 修改内容 |
|---------|------|---------|
| `module-name` | KMP/Android/iOS/HarmonyOS | [修改说明] |

### 2.2 现有流程分析

#### 2.2.1 [模块名]

**现有架构图**：
[架构关系图]

**现有流程图/交互图**：
[业务流程和调用链路]

**核心代码逻辑**：
[关键代码路径说明]

**请求/接口清单**（如有）：

| 请求/接口 | 描述 | 说明 |
|----------|------|------|
| [接口名] | [描述] | [说明] |

#### 2.2.2 [模块名]
...

### 2.3 平台影响

| 平台 | 是否涉及 | 修改范围 |
|-----|---------|---------|
| KMP（跨平台共享层） | 是/否 | [具体说明] |
| Android | 是/否 | [具体说明] |
| iOS | 是/否 | [具体说明] |
| HarmonyOS | 是/否 | [具体说明] |

### 2.4 模块依赖层次

| 层次 | 类型 | 涉及模块 | 修改原则 |
|-----|------|---------|---------|
| **底层核心层** | 被广泛依赖 | [模块列表] | 优先修改，保持向后兼容 |
| **中间业务层** | 依赖底层，被顶层依赖 | [模块列表] | 等底层发布后再修改 |
| **顶层应用层** | 依赖中间层和底层 | [模块列表] | 最后修改 |

## 三. 架构设计

### 3.1 目标架构图
[优化后的模块架构关系图，与现有架构对比]

### 3.2 目标流程图/交互图
[优化后的业务流程和交互时序]

### 3.3 模块间关系与数据流向
[模块间依赖方向和数据流向说明]

### 3.4 与前后台交互
[前端与后端服务的交互方式说明（如涉及）]

### 3.5 技术选型

| 决策点 | 可选方案 | 推荐方案 | 理由 |
|-------|---------|---------|------|
| [决策点] | [方案 A / 方案 B] | [推荐] | [理由] |

## 四. 变更流程

### 4.1 模块: `module-name` (平台: xxx)

#### 4.1.1 子任务 1: [任务名称]

**流程/交互图**（如有）：
[描述该子任务涉及的流程或交互]

**前置依赖**：
- [依赖的 API、数据模型、其他模块产出等]

**核心实现方案**：
- 数据模型：[按需定义该子任务涉及的模型]
- 接口契约：[按需定义该子任务涉及的接口]
- 实现逻辑：[核心代码逻辑概要，伪代码或自然语言描述]
- 错误处理：[异常场景的处理方式]

**变更清单**：

| 操作 | 文件路径 | 修改内容 | 依赖 |
|-----|---------|---------|------|
| 新增/修改 | `path/to/file` | [具体修改] | 无/步骤 X |

**产出**：
- [该子任务完成后输出什么：数据/API/组件等，供后续子任务使用]

#### 4.1.2 子任务 2: [任务名称]
...

### 4.2 模块: `module-name-2` (平台: xxx)
...

### 4.N 配置和资源变更

| 类型 | 文件路径 | 变更内容 |
|-----|---------|---------|
| 构建配置 | `build-profile.json5` / `build.gradle.kts` / `Podfile` | [变更说明] |
| 资源文件 | [路径] | [变更说明] |
| 依赖声明 | [路径] | [新增或升级的第三方库] |
| 混淆规则 | [路径] | [keep rules 说明] |

### 4.N+1 变更验证点

| 模块 | 验证方式 | 验证标准 |
|------|---------|---------|
| `module-name` | 编译通过 + 单元测试 | [具体标准] |
| `module-name` | 集成测试 + UI 验证 | [具体标准] |

## 五. 实施阶段

### 5.1 阶段 1: [阶段名]
1. **[子任务名]** (模块: xxx, Phase: 1)
   - 来源: 四.变更流程 → 4.X 模块 `xxx` → 子任务 M
   - 前置依赖: 无 / 依赖步骤 X
   - 风险: 低/中/高
   - 验证: [引用 4.N+1 变更验证点中的验证标准]

### 5.2 阶段 2: [阶段名]
...

## 六. 测试策略

### 6.1 单元测试
[各平台单元测试内容]

### 6.2 集成测试

以 UserStory 为粒度编写集成测试用例，每个 UserStory 对应一个可被 verifier 自动执行的验证场景。

#### 测试用例格式

```markdown
#### US-{N}: {UserStory 标题}

**前置条件**：
- 应用包名: `{packageName}`
- 入口页面: {页面名称/路径}
- 前置数据: {需要预置的账号、数据状态等，无则填"无"}

**操作步骤**：
1. {具体操作，如：点击"xxx"按钮}
2. {下一步操作}
3. ...

**预期结果**：
- [ ] {可观测的 UI 断言，如：页面显示"xxx"文本}
- [ ] {元素状态断言，如：按钮变为不可点击状态}
- [ ] {页面跳转断言，如：跳转到 xxx 页面}

**日志验证**：
- 关键日志 TAG: [`{TAG1}`, `{TAG2}`, ...]
- [ ] {日志断言，如：操作后出现 TAG=OrderSubmit 且包含 "submit success" 的日志}
- [ ] {异常日志断言，如：不应出现 ERROR 级别的 "NullPointer" 日志}
- [ ] {时序断言，如：`initStart` 日志应在 `renderComplete` 日志之前出现}
- 无需日志验证时填 "无"

**截图留痕点**：
- 步骤 {M} 后截图: {截图说明，如"弹窗出现时"}
- 步骤 {N} 后截图: {截图说明，如"操作完成后的结果页"}

编写原则

• 每个 UserStory 覆盖一个完整的用户操作路径（从入口到结果），不拆分为多个碎片化用例
• 操作步骤使用用户视角的自然语言（点击/输入/滑动），不涉及代码实现细节
• UI 预期结果必须是 UI 层可观测的（元素存在/文本内容/页面跳转）
• 日志验证用于确保关键业务路径有足够的日志可追踪，验证内容包括：
  • 关键路径覆盖：核心业务操作（如提交、支付、登录）必须有对应日志输出，确保出问题时能定位
  • 错误可追踪：异常场景应输出包含上下文信息的错误日志（如请求参数、错误码），而非静默失败
  • 无脏日志：正常操作路径不应出现 ERROR/FATAL 级别日志
• 截图留痕点至少包含：操作前初始状态、关键操作后状态、最终结果状态
• 异常场景（如网络错误、输入校验失败）也需要对应的 UserStory

6.3 多端一致性验证

[多端验证计划]

6.4 日志验证策略

定义本需求中需要验证日志输出的关键场景，确保发生问题时能够根据日志查出根因。

日志验证范围

各平台日志收集方式

七. 风险与应对

7.1 跨平台兼容性风险

7.2 模块依赖冲突风险

7.3 性能风险

7.4 基线版本兼容性

等待确认（使用 AskUserQuestion 工具展示选项）:

1. yes — 计划无误，持久化并开始编码
2. modify — 部分内容需要调整
3. supplement — 缺少某些场景或约束
4. no — 计划方向有问题

---

## 决策规则

### 阶段拆分规则

| 场景 | 阶段策略 |
|-----|---------|
| 纯 KMP 修改 | 架构图 → 子任务拆分 → Phase 1: KMP 修改 → Phase 2: 各平台验证 |
| 单平台需求 | 架构图 → 子任务拆分 → Phase 1: 目标平台实现 → Phase 2: 测试验证 |
| 跨平台需求 | 架构图 → 子任务拆分 → Phase 1: 底层 → Phase 2: 各平台适配 → Phase 3: UI → Phase 4: 测试 |
| 单平台需求（HarmonyOS） | 架构图 → 子任务拆分 → Phase 1: 核心逻辑 → Phase 2: UI 实现 → Phase 3: 测试验证 |

### 复杂度评估标准

| 等级 | 标准 |
|-----|------|
| **低** | 单模块、单平台、无依赖变更 |
| **中** | 2-3 个模块、2 个平台、有限的依赖变更 |
| **高** | 4+ 个模块、3+ 个平台、底层接口变更 |

---

## 核心原则

### 1. 只分析不编码
- 此技能仅做需求分析和计划输出
- 不修改应用源代码文件，不编写业务代码
- 只写入工作流产物文件（`.bundle-flow/` 目录下的计划、状态文件）
- 必须获得用户明确确认后才能开始编码

### 2. 以模块为单位组织
- 实施步骤按模块组织，而非按文件
- 明确每个模块的修改内容和修改顺序
- 考虑模块间的依赖关系

### 3. 关注跨平台依赖
- 遵循依赖层次
- 底层修改优先，顶层最后
- 同层级平台可并行开发

### 4. 可落地可验证
- 每步有具体的操作描述
- 每阶段有明确的验证标准
- 风险有对应的应对方案

### 5. 持久化可恢复
- 计划输出同时持久化到 `.bundle-flow/{requirement_id}/` 目录
- 通过 state.json 的 active 字段定位当前需求目录
- 上下文切换后可通过 `/native-plan` 自动恢复未完成计划
- `.bundle-flow/` 应加入 `.gitignore`，不随代码提交

### 6. brain-storm 式交互（贯穿全流程）

**核心规则：禁止一股脑输出，必须分段交互。** 每个阶段都有明确的停止点，展示后等用户确认再继续。

- **需求重述**：对歧义点逐个交互确认
- **影响分析**：逐端/逐模块分析，展示后等确认
- **架构设计**：先展示架构全景等确认，再逐个决策点等选择（详见阶段 3 交互规则）
- **变更流程**：按模块逐个展示，每个确认后再展示下一个（详见阶段 4 交互规则）
- **任何阶段遇到不确定的设计决策**：停下来给 2-3 个选项，让用户选择，不自行假设
- **交互原则**：每次只问一个问题，优先选择题，遵循 YAGNI 原则
- **智能跳过**：如果项目知识库或用户有明确的规范/习惯，直接按此执行，无需确认

### 7. 遵守项目知识库规范
- 生成计划前，加载项目知识库（`.knowledge/`）和全局知识文档
- 计划内容必须符合项目的技术规范、编码约定和架构约束
- 知识库不足时，直接读取源码补充
- 当平台为 HarmonyOS 时，额外加载 `references/lang-syntax/SKILL.md` 和相关 `references/kits_*/SKILL.md`

---

## 与其他命令的联动

### 上游
- **项目检测**：通过项目目录结构自动检测平台和模块信息（替代 bundle-locator/bundle-setup）
- **native-analyse**（`references/native-analyse/SKILL.md`）：产出跨端技术方案（tech-spec.md），native-plan 读取并基于其细化

### 下游
- **native-coding**（`references/native-coding/SKILL.md`）：native-plan 确认后，按计划开始编码

### 推荐工作流（有 tech-spec）

检测项目结构和平台 → 确定涉及的模块和平台 native-analyse "需求描述" → 产出跨端技术方案，等待确认 native-plan "需求描述" → 基于技术方案，各端细化计划，等待确认 开始编码 → 按计划逐步实施，进度自动更新

### 推荐工作流（无 tech-spec，向后兼容）

> 注意：此模式下 native-plan 在项目检测后直接执行，计划质量取决于对项目结构的分析深度。如需更精确的计划，建议先执行 native-analyse 再执行 native-plan。

检测项目结构和平台 → 确定涉及的模块和平台 native-plan "需求描述" → 独立完成完整规划，等待确认 开始编码 → 按计划逐步实施，进度自动更新

### 上下文切换恢复

新会话中直接执行 /native-plan，自动检测未完成计划和 tech-spec

/native-plan → 发现未完成计划，提示继续/废弃/修改 → 检测到 tech-spec，自动进入精简模式

---

## 参考文档

### 项目知识库

**项目知识库**（`<project>/.knowledge/`）：
- `<project>/.knowledge/architecture/` - 项目架构映射
- `<project>/.knowledge/standards/` - 项目技术规范
- `<project>/.knowledge/domain/` - 项目业务逻辑

### 内部参考文档

**HarmonyOS 平台知识**（按需加载）：
- `references/lang-syntax/SKILL.md` - ArkTS 语法规范和核心约束
- `references/kits_ui/SKILL.md` - UI 开发 Kit API
- `references/kits_network/SKILL.md` - 网络开发 Kit API
- `references/kits_data/SKILL.md` - 数据管理 Kit API
- `references/kits_media/SKILL.md` - 媒体开发 Kit API
- `references/component_basic_ui/SKILL.md` - 基础 UI 组件规范
- `references/component_container/SKILL.md` - 容器组件规范

**其他内部参考**：
- `references/native-analyse/SKILL.md` - 跨端技术方案分析流程
- `references/native-coding/SKILL.md` - 原生编码实施流程
- `references/native-build-fix/SKILL.md` - 构建修复流程
- `references/harmony-verify/SKILL.md` - HarmonyOS 验证流程
- `references/harmony-build-fix/SKILL.md` - HarmonyOS 构建修复

---

## 成功标准

- [ ] 完成需求重述，消除歧义
- [ ] 完成影响范围分析，梳理现有流程，列出涉及的模块、平台和依赖层次
- [ ] 完成架构设计，定义目标交互/架构图和技术选型
- [ ] 完成变更流程，按模块拆分子任务，每个子任务含实现方案和变更清单
- [ ] 生成分阶段实施计划，步骤引用阶段 4 子任务，有验证标准
- [ ] 完成风险评估，提供应对方案
- [ ] 计划持久化到正确路径（正常模式 → plan-{platform}.md，增量模式 → changes/round-N/delta-plan-{platform}.md）
- [ ] 输出结构化计划到会话，等待用户确认
- [ ] 用户确认后更新 metadata.json 状态，指引执行编码
- [ ] 增量模式下只列增量子任务，不修改原 plan-{platform}.md
- [ ] 修改模式下正确注入变更描述，原地覆盖 plan-{platform}.md
- [ ] 失效状态下完成后正确更新 invalidated_phases → completed_phases
- [ ] 当平台为 HarmonyOS 时，已加载 ArkTS 语法规范和相关 Kit API 知识