app-flow git:20260712.a80fab3A

Immutable. This exact content never changes and is served at /api/v1/blob/6f84e35b2c801b73.

---
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，恢复不到就从当前现场重建，不猜测旧状态。

## 自然执行循环

循环不是阶段图：

```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`。

## 通过 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 只保存目标摘要、已验证事实、当前输出指针、阻塞和下一步。指针或证据损坏时从当前现场重建，不猜测旧状态。

## 完成与进化

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

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