App Flow

---
name: app-flow
description: "把自然语言 App 需求、模块说明和参考截图一路推进到经验证的代码与当次授权交付；用于需要长时间自主开发、持续排障和跨上下文恢复的移动端或跨端 App 任务。它不固定技术栈、阶段或交付形式，也不会把无人值守理解为远端发布授权。"
---

# App Flow

这是一个薄的 App 驾驭层。它只守住目标、授权、能力发现、验证、恢复和停止；具体行动由当前需求、代码现场和可用能力决定。它自己不写代码、不做设计、不打包，而是每一步选出当前价值最高的能力去做。

## 不变量

- **不固定技术栈**：React Native、Expo、Flutter、原生或其他方案都由现场证据决定。
- **不固定阶段**：不预设 research、spec、design、build、release 等流水线；能力地图是候选池，不是顺序图。
- **不固定交付形式**：源码、原型、安装包、OTA、Release 或其他产物以用户当次目标为准。
- 长时间或无人值守只增加持续性，不扩大删除、付费、push、部署、Release 等外部副作用的用户授权。
- 同一上下文里的能力交接直接传递，不为了中转创建 Markdown；文件只用于真实产物、证据、持久化或工具边界。

## 启动

1. 从用户请求与仓库现场形成 goal、可核验 acceptance、已有 authority 和未知项。
2. 建立 execution envelope。优先使用用户或宿主给出的限制；都没有时默认最多 **4 小时**，并至少预留最后 **15 分钟**做验证、checkpoint 和交付说明。
3. 读取当前代码、测试和已有证据；没有本地 Memory 也必须能正常开始。跨上下文续接时先尝试恢复本任务已有的 checkpoint，恢复不到就从当前现场重建，不猜测旧状态。

## 授权信封（启动即问清，减少中途门禁）

外部副作用需要用户授权，但**不该在链路中途逐个打断用户**。启动时（或首次判明本 goal 大概率会触达外部动作时）用**一次**批量问清「授权信封」：

- 把本 goal 可能触达的外部动作一次性列全（如：建私有仓库并 push、本地打包、发私有/内测 Release、preview OTA）。
- **低风险、可逆、仅对自己/协作者可见**的动作（私有 push、本地构建打包、私有 Release/preview）可在这一次里**一次性预授权**，之后按信封连续执行、不再逐个确认。
- **自托管 OTA / 更新分发是启动就该问清的一项**（不是打完包才补）：是否要自托管 OTA（新建或复用 FC + OSS）、preview 包是否带"版本切换悬浮球"、production 是否只跟随 latest、**是否要 CI 流水线**（PR 发 preview / 合并发 production）。它同时牵涉**部署 FC**（外部动作，按风险确认）、**preview 包要不要加浮层功能**（范围决定）、以及**发布凭据**（CI 发布需要对象存储写权限的 AK 存成仓库 Secret——**用户若无现成 key 又要 preview/CI OTA，需其自备**，否则流水线走不通）。前置问清能避免"包已打好却发现要返工加 OTA / 缺凭据 CI 跑挂"。
- **不可逆或对外公开**的动作（把仓库/Release 转公开、production OTA、商店提交、部署 FC、删除、付费）即使已在信封里提过，**执行前仍各自再确认一次**。
- 无人值守 / 长时间运行不扩大信封；信封只覆盖用户当次明确勾选的动作。

目的：让「需求 → 代码 → 打包 → 内测分发」这类链路能在一次授权后连续跑完，把确认成本集中在开头，只把真正高风险的动作留成运行时门禁。

## 自然执行循环

循环不是阶段图：

```text
读取目标、现场和证据
→ 选当前价值最高的一项行动
→ 按需发现并加载最小能力集合（核心能力地图 + 宿主 metadata）
→ 行动
→ 用事实验证是否推进 acceptance
→ 必要时更新 checkpoint 或局部 Memory
→ 完成则交付；仍有可行行动则继续；否则阻塞
```

实质进展至少包含一项：满足验收条件、相关检查通过、根因范围缩小、阻塞解除，或得到会改变下一步的新增证据。相同失败签名连续两次出现且没有新增证据时，不原样重试；先换假设、诊断路径或工具。

每项行动写清假设、预期证据与成本上界。缺少用户授权、关键输入或外部状态，找不到仍在 envelope 内的可行行动，或剩余资源不足以同时行动和验证时，写紧凑 checkpoint 后进入阻塞。

## 核心能力地图

下面是随本套件分发的窄能力。它是候选池，不是执行顺序；每轮按当前证据重新选择，绝不预设 `research → design → build → delivery` 的固定链。

| 能力 | 何时用 | 何时不要用 |
|---|---|---|
| `app-flow-build` | 需要创建、修改、重构、修复 App 代码，或只读诊断崩溃并给候选补丁 | 只需评审、打包发布或纯产品讨论时 |
| `app-flow-delivery` | 需要打包、签名、OTA、APK/IPA、Release、商店、部署、回滚或验活 | 基础代码问题未修好、或没有拿到具体渠道授权时（此时最多做预检） |
| `app-flow-reviewer` | 需要与生产者分离的独立评审、复核、验收或质量/准备度判断 | 需要第一方定位根因或直接改产物时 |

每个能力都可独立处理窄任务，也可被本入口按当前行动调用；边界写在各自 `SKILL.md`。

## 评审 gate（关键转换点各评一次，别全程只评一次）

`app-flow-reviewer` 不必跟在每个琐碎能力后面，但在**改变承诺的关键转换点**，独立评审往往就是当前最高价值行动，应各触发一次，而不是整条链路只评一次：

- **spec / 需求确立后**：目标、范围、验收、**核心输入路径**是否清晰可证伪（rubric-spec）。
- **设计 / UI 确立后**：可实现性、状态完整、**无死交互元素、核心输入路径存在**、无障碍、平台一致（rubric-design）。
- **构建 / 一段可验证产物完成后**：正确性与根因证据（rubric-build）。
- **发布前**：授权、产物核对、回滚、验活（rubric-release-preflight）。
- **前端 / 移动端视图改动后（易漏，必查）**：任何前端视图或移动端 UI 的改动——**包括新增功能、改样式、调布局，且不限于「有 design 阶段」的场景**——在声称完成前至少过一次视觉 + 交互 review（rubric-design，尤其「移动端渲染细节」：安全区双向 / 图标质量 / 真机等价渲染核对）。没有 design 阶段就直接对产出（代码 + 真实渲染截图）评一次，不能因为"只是改个视图"就跳过。

**评审必须正式调用 `app-flow-reviewer`**：每次 gate 评审都通过宿主的 Skill 机制显式激活 `app-flow-reviewer`，再由它决定是否派 subagent；**禁止**跳过调用、只把 rubric 条目抄进通用 subagent 提示词来替代——那样评审虽然发生了，但日志里没有任何正式调用记录，事后无法统计、无法审计（历史教训：两次完整 Flow 的评审全走了内联，使用统计显示 reviewer 零调用）。

每个 gate 的评审都独立于生产者、绑定真实证据。跳过某个 gate 要显式说明为什么可跳，而不是默认不评——历史教训：整程只评一次会漏掉设计/交互层的问题（假可点元素、缺输入入口）。

**把 gate 绑定到「完成声明」**：在向用户声称「设计已定 / 外壳完成 / 可交付 / 可发布」之前，对应的 gate（设计→rubric-design、发布前→rubric-release-preflight）必须**已跑过一次或被用户显式豁免**。不能先声称完成、等用户挑出问题才补评审——完成声明本身就是触发 gate 的信号。

## 最简 review loop（速度优先，但至少评一次）

除了上面绑定到关键转换点的 gate，还有一条对**每一项工作**都适用的底线循环：

```text
做一项工作 → 至少 review 一次 → 修 → 测
```

- **至少一次**：每完成一项工作（一个改动 / 一个功能 / 一个视图）都跟一次 review。review 类型按改动性质三选一即可——**代码逻辑 / Code Review**、**交互 review**、**视觉 review**（前端 / 移动端视图改动优先视觉 + 交互，并按 rubric-design 的「移动端渲染细节」取证）。
- **不强制收敛**：出于速度与效率，**不要求循环到完全无问题**——`review → 修 → 测` 跑一轮即可，不必反复 loop 到收敛（除非用户另有要求，或发现阻断性问题）。底线是"评过一次并据此修过"，而不是"零 review 直接交付"。
- **新增功能场景**：App Flow 同样覆盖"加一个新功能"——流程与改造类似，只是**可能没有前期 Design 阶段**。有设计就照常走 design gate；没有就直接对产出（代码 + 真实渲染）做一次 `review → 修 → 测`。核心是"每做一项就评一次"，别攒到最后一次性交付才发现问题。

## 通过 metadata 发现能力

核心地图之外，围绕“下一项行动”查询宿主的 Skill metadata，不维护固定 Skill 名单：

- metadata 检索最多 5 个候选；先按 description 与当前意图的具体匹配度排序。
- 一次只探查一个可读入口；第一个不足时才看第二个，最多 2 个。
- **没有匹配**时使用模型与现有工具继续；确实缺能力才阻塞。
- **多个匹配**时只加载完成当前行动所需的最小集合，不把候选固化为阶段。
- 入口缺失或**不可读**时保留诊断并跳过，不能让整个 Flow 崩溃。
- 证据质量在入口加载后判断；不能假装 metadata 已经提供它。

## 渐进式本地 Memory

本 Skill 只拥有自己的 `local/`。首次需要读取或写入时，从当前 Skill 目录按需加载 `../../../docs/philosophy/references/local-memory.md` 的通用协议；不要在普通行动中提前展开低频细节。独立分发导致引用不可读时，以本节摘要继续并保留诊断，不因此阻塞当前任务。

读取顺序：

1. `local/INDEX.md`（不存在就直接继续）；
2. 一个当前作用域 map；
3. 最多 3 条相关正文；
4. 只有当前决策明确需要时才打开原始证据。

首次决策最多读取 **1 个根入口**、**1 个作用域 map**、**3 条**正文，正文合计不超过 **32 KiB**。定位优先级是：显式 Feature/Task/Goal ID → WorkTree → 分支 → Repo → 主题。Feature 路径必须带 `repo-key`，避免不同仓库的同名冲突。

Memory 是不可变记录；修正通过新记录的 `supersedes` 指向旧 ID。Token、密码、私钥、完整环境变量和未经授权的私密内容等敏感信息不得进入 `local/`。遇到索引断链、缺字段或损坏条目时跳过它，以当前证据继续并把 map 标为待修复，禁止递归扫描全部目录。

跨上下文恢复也走同一层：checkpoint 只保存目标摘要、已验证事实、当前输出指针、阻塞和下一步。指针或证据损坏时从当前现场重建，不猜测旧状态。

**checkpoint 不只在阻塞时写。** 长任务 / 多阶段 Flow 在**每个大阶段完成后**就更新一次 `maps/resume` 的短指针（覆盖式，几行即可），而不是只在阻塞或收尾才写——这样任意一次压缩或中断都能续接。写 resume 指针成本极低，别攒到最后一次性补。

## 完成与进化

只有 acceptance 有新鲜证据时才声称完成。交付实际产物、验证结果、残余风险与未执行的外部动作。

每次使用结束都判断是否值得保存 Run、更新 Feature map、生成原子 Memory 或把反复验证且已脱敏的经验晋升到稳定 reference；“每次判断”不等于“每次写文件”，保存也不等于可信。

**教训回写走候选区，不直接改规则**：运行中发现的可复用教训（现象 / 根因 / 下次规则，已脱敏）写成一条几行的候选放进 `local/candidates/`；候选**不得**由 Agent 直接写进 SKILL.md 或 rubric，须由用户审核后手动晋升。这样自进化有入口，稳定规则又不会被单次运行随意改写。

最终回复用一行自然语言“经验回执”说明本轮读取 / 命中了哪些 Memory，以及写入了什么；若未新增，简述原因，不要求固定字段。只有根因或模式已经验证、未来可能复现，并能转成具体防错动作时，才生成原子 Memory 或晋升稳定 reference；一次性背景、普通成功和未经验证的猜测不写。

**但「判断」不等于「默认不写」——满足下列任一的 Flow，收尾时至少要写/更新 `maps/resume/<repo-key>/<task-key>.md` + 对应 Feature map（懒创建 `local/`），不能整场零落盘：**

- 跨 **≥3 个阶段**，或
- 产生了**外部副作用**（push / Release / 打包 / 部署 / OTA），或
- **可能跨上下文续接**（长任务、可能被压缩或中断）。

resume 指针只需短短几行（目标摘要 / 已验证事实 / 当前产物指针 / 下一步）；原子 Memory 仍按未来价值判断，不强求。只有真正一次性的琐碎任务才可整场不落盘。历史教训：一次跨十几阶段、带 push/Release 的 Flow 因为“判断了可以不写”而 **local 全空**，任何中断都只能从零重建。