原生开发实施规划专家 - 基于跨端技术方案（tech-spec），生成端级细化实施计划，持久化到本地支持上下文恢复。 工作流程： 1. 上下文恢复：检测项目结构、已有计划和 tech-spec.md 2. 需求重述：引用 tech-spec 或独立分析（向后兼容） 3. 影响分析：有 tech-spec 时精简，聚焦当前端特有细节 4. 架构设计：有 tech-spec 时精简，聚焦端内实现架构 5. 变更流程：从 tech-spec 子任务出发，细化为端内文件级变更（保留端内流程图） 6. 分阶段拆解：按依赖关系拆分为可独立交付的阶段 7. 风险评估：有 tech-spec 时聚焦当前端特有风险 8. 等待确认：必须获得用户明确确认后才能开始编码 使用场景： - 有 tech-spec 时：基于跨端技术方案，细化单端实施计划 - 无 tech-spec 时：独立分析需求，生成完整实施计划（向后兼容） <example> user: "/native-plan 新增交易确认弹窗，iOS 端" assistant: "读取 tech-spec.md，基于跨端技术方案细化 iO...
Scanned 9/22/2026
Install to Claude Code
Skills Directorynpx -y skills add IsKenKenYa/skills --skill native-plan --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Native Plan?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/iskenkenya-native-plan)More formats (shields.io, HTML) on the badges page.
---
name: native-plan
description: |
原生开发实施规划专家 - 基于跨端技术方案（tech-spec），生成端级细化实施计划，持久化到本地支持上下文恢复。
工作流程：
1. 上下文恢复：检测项目结构、已有计划和 tech-spec.md
2. 需求重述：引用 tech-spec 或独立分析（向后兼容）
3. 影响分析：有 tech-spec 时精简，聚焦当前端特有细节
4. 架构设计：有 tech-spec 时精简，聚焦端内实现架构
5. 变更流程：从 tech-spec 子任务出发，细化为端内文件级变更（保留端内流程图）
6. 分阶段拆解：按依赖关系拆分为可独立交付的阶段
7. 风险评估：有 tech-spec 时聚焦当前端特有风险
8. 等待确认：必须获得用户明确确认后才能开始编码
使用场景：
- 有 tech-spec 时：基于跨端技术方案，细化单端实施计划
- 无 tech-spec 时：独立分析需求，生成完整实施计划（向后兼容）
<example>
user: "/native-plan 新增交易确认弹窗，iOS 端"
assistant: "读取 tech-spec.md，基于跨端技术方案细化 iOS 端实施计划..."
</example>
skills: []
enabled: true
user-invocable: true
metadata:
internal: true
---
# 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` - 计划元数据
```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
}
```
### 计划生命周期
| 状态 | 触发条件 | 说明 |
|-----|---------|------|
| `draft` | `/native-plan` 执行完成 | 计划已生成，等待用户确认 |
| `confirmed` | 用户回复 yes | 用户已确认，可以开始编码 |
| `in_progress` | 开始编码实施 | 正在按计划执行 |
| `completed` | 所有阶段完成 | 计划已全部实施完毕 |
### 上下文恢复
执行 `/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 通过以下来源获取上下文：
| 来源 | 用途 | 必需 |
|------|------|------|
| `.bundle-flow/state.json` | 获取当前活跃的 `requirement_id` | 是 |
| 项目目录结构 | 自动检测平台和模块 | 是 |
| `.bundle-flow/{requirement_id}/tech-spec.md` | 跨端技术方案（有则精简模式，无则完整模式） | 否 |
**项目结构检测**：从项目目录自动推断平台和模块信息：
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` | `--platform ios` | 条件必需 | 目标平台，决定读写哪个 `plan-{platform}.md` |
| `--delta` | `--delta round-{N}` | 否 | 进入增量模式（场景 A） |
| `--change` | `--change "变更描述"` | 否 | 进入修改模式（场景 B） |
**`--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`）
- **不存在** → 进入**完整模式**：按原有流程独立完成全部阶段（向后兼容）
```markdown
检测到跨端技术方案: [功能名称]
- tech-spec 状态: confirmed
- 涉及平台: [平台列表]
将基于技术方案进行端级细化（精简模式）。
```
- [ ] **展示恢复摘要**（如有未完成计划）
```markdown
发现未完成的计划: [功能名称]
- 状态: [当前状态]
- 当前阶段: 阶段 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）
- [ ] **检查模块定位结果**
如果当前会话中已有模块定位结果（通过项目目录检测或上游产出），引用其定位结果：
- 涉及的模块列表
- 平台分布
- 依赖层次
如果尚未确定，根据需求关键词和项目结构进行初步分析。
- [ ] **现有流程分析**
针对涉及的模块，梳理现有的技术架构和业务流程：
- **现有架构图**：绘制当前相关模块的架构关系图
- **现有流程图/交互图**：梳理当前业务流程的调用链路和交互时序
- **核心代码逻辑**：结合项目知识库和源码，说明关键代码路径
- **请求/接口清单**：列出现有相关的请求和接口（如有）
```markdown
| 模块 | 现有流程 | 核心代码路径 | 说明 |
|------|---------|-------------|------|
| `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？
- [ ] **第二轮：技术选型（逐个决策点等确认）**
针对需求中的每个关键决策点，**逐个**展示可选方案并等待用户选择：
```markdown
决策点: [例：状态管理]
方案 A: [描述]（推荐）
- 优点: ...
- 缺点: ...
方案 B: [描述]
- 优点: ...
- 缺点: ...
推荐: 方案 A — [理由]
→ 等待用户选择后，再展示下一个决策点
```
---
### 阶段 4: 变更流程
**目标**：按模块维度细化子任务的端内实现方案和文件变更清单
#### 交互规则（强制）
**按模块逐个展示，每个模块的变更方案展示后必须等用户确认再继续下一个。** 禁止一次性输出所有模块的变更。
```
展示模块 A 的全部子任务 → 等用户确认（OK / 调整）
展示模块 B 的全部子任务 → 等用户确认
...
全部模块确认后 → 展示配置变更 + 验证点汇总 → 等最终确认
```
**脑暴原则贯穿**：
- 子任务的实现方案如有多种可行路径，给出选项让用户选择
- 变更清单中涉及的架构决策（新建文件 vs 扩展现有文件、继承 vs 组合），遇到不确定时停下来问用户
- 用户确认某个模块后，如果后续模块发现需要回调之前的设计，主动提出
#### 精简模式（有 tech-spec）
从 tech-spec 的子任务出发，细化为当前端的具体实现。**保留端内流程/交互图**，确保看 native-plan 时不需要回翻 tech-spec。
**每次只展示一个模块的全部子任务**：
```markdown
#### 模块: `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）
**每次只展示一个模块的全部子任务**：
以模块为单位，将每个模块的改动拆分为若干子任务。
子任务粒度原则：每个子任务完成一个完整且单一的事情，不过度拆分。
```markdown
#### 模块: `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 的子任务：
```markdown
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. **评估影响范围**：分析补充内容对已有计划各章节的影响，向用户展示：
```markdown
补充内容: [摘要]
影响评估:
- [ ] 一.需求重述 — [需要/不需要] 更新
- [ ] 二.影响范围分析 — [需要/不需要] 更新，原因: [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`（增量模式不改变原有阶段状态）
持久化完成后，提示开始实施计划（增量模式提示执行增量编码）。
#### 输出格式
```markdown
# 实施计划: [功能名称]
> 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 日志验证策略
定义本需求中需要验证日志输出的关键场景，确保发生问题时能够根据日志查出根因。
#### 日志验证范围
| 场景类型 | 验证目标 | 示例 |
|---------|---------|------|
| 核心业务路径 | 关键操作有日志记录，可追踪完整链路 | 提交流程每步有对应 TAG 日志 |
| 错误与异常 | 异常场景输出含上下文的错误日志，非静默失败 | 网络超时日志包含 URL、超时时长、重试次数 |
| 生命周期事件 | 页面/组件生命周期有日志，可排查时序问题 | 页面 onCreate/onDestroy 有日志 |
#### 各平台日志收集方式
| 平台 | 命令 | 过滤方式 |
|------|------|---------|
| Android | `adb logcat` | TAG 过滤: `adb logcat -s TAG1,TAG2`；级别过滤: `adb logcat *:E` |
| iOS | `xcrun simctl spawn booted log stream` | `--predicate 'subsystem == "com.example.app"'` |
| HarmonyOS | `hdc shell hilog` | TAG 过滤: `hilog -T TAG1`；级别过滤: `hilog -L ERROR` |
## 七. 风险与应对
### 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 知识Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
