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、删除、付费）即使已在信封里提过，执行前仍各自再确认一次。
• 无人值守 / 长时间运行不扩大信封；信封只覆盖用户当次明确勾选的动作。

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

自然执行循环

循环不是阶段图：

读取目标、现场和证据
→ 选当前价值最高的一项行动
→ 按需发现并加载最小能力集合（核心能力地图 + 宿主 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 阶段就直接对产出（代码 + 真实渲染截图）评一次，不能因为"只是改个视图"就跳过。

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

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

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

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

做一项工作 → 至少 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；“每次判断”不等于“每次写文件”，保存也不等于可信。

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

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

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