pi-fpa

面向 Pi 的完整 FP&A 周期资源包，目标运行时为 @earendil-works/pi-coding-agent 0.84.1。

本包分发 Prompt Template、Skill、参考合同，以及路由护栏、数据读取、企业上下文、经营计划、执行证据、规范化 Artifact 和看板投影七个 Extension。包内不含业务数据与模型凭证，也不实现工作流状态机。主 Agent 负责前置诊断与独立月度复盘，正式策略、预测冻结和执行阶段使用 Graph。Graph 的执行状态、多 Agent 隔离和审批交互由宿主运行时或独立工作流承担。

包含的资源

策略规划 Graph v5.0.0 消费主 Agent 已预检并封存的 Actuals 诊断与驱动分析，只负责并行场景、策略推荐和独立审核。业务阻塞立即报告，可修复审核问题最多自动修改两轮；同一问题与相同证据重复时提前停止。Graph 运行完成不等于业务就绪，主 Agent 仅在取得 ready handoff 后发布。目录工具默认去除重复 App 注册表，支持 dataset 筛选和 app_offset/app_limit 分页。

Prompt Template：

• /fpa-plan-cycle：主 Agent 整理输入、调用 fpa_plan_preflight、完成 Actuals 诊断和驱动分析并封存证据，再通过 fpa-strategy-planning Graph 完成策略模拟、推荐和独立复核，形成 reviewed_strategy_handoff 后停止；不跨越人工批准或冻结正式预测。
• /fpa-review-cycle：在精确 Forecast/Execution refs 和新周期 Actuals 到达后，通过 fpa-cycle-review Graph 形成周期复盘。

Skill：

• fpa-apply-core-rules
• fpa-plan-cycle
• fpa-diagnose-actuals
• fpa-analyze-drivers
• fpa-simulate-strategies
• fpa-recommend-strategy
• fpa-review-strategy
• fpa-forecast-approved-strategy
• fpa-review-cycle
• fpa-execute-approved-strategy
• fpa-refresh-dashboard

执行 Skill 设置了 disable-model-invocation: true，不会出现在模型可主动调用的 Skill 摘要中，也没有对应 Prompt。它只能由用户显式输入 /skill:fpa-execute-approved-strategy，或由 fpa-strategy-execution Graph 通过插件间注册按名称精确分配；Graph 分配不会把 Skill 暴露给主模型。P1 只解析精确、不可变的执行请求并展示人工执行状态，不调用真实 adapter；缺少 F1 lineage、目标账户、负责人或独立执行授权时必须保持 blocked。

Graph-first 路由

主 Agent 同时具备 graph_list 和 graph_run 时，正式多阶段流程先查询 Graph catalog。经营规划允许主 Agent 整理输入、检查数据、诊断与驱动分析， 完成 fpa_plan_preflight 检查和封存后再启动策略 Graph。独立数据检查与 已完成月份的经营复盘不要求创建计划或启动 Graph。主要工作流的边界为：

• fpa-strategy-planning：验证精确预检与前置工件，执行三类并行策略场景、 推荐与独立审核，形成 reviewed_strategy_handoff 后停止。
• fpa-forecast-freeze：只接受精确 handoff，经人工批准后冻结 Forecast。
• fpa-strategy-execution：只接受精确 execution request ID 与指纹，由确定性服务校验其 committed F1 lineage、预算、切片、账户、负责人和独立授权；当前模板只记录人工外部执行，不调用投放适配器。
• fpa-cycle-review：只接受精确 Forecast/Execution refs 与新 Actuals。

Graph 的业务阻塞不能触发父 Agent 降级执行。Graph 工具不可用、catalog 不存在 匹配 Graph 或匹配 Graph 无法加载时，多阶段入口保持 blocked；用户必须另行 显式请求一个隔离阶段，父 Agent 不能自动把完整工作流改成本地串行执行。Graph 节点只执行分配给自己的阶段，不得递归启动另一个 Graph。

fpa-routing-guard Extension 会在 Pi 的 tool_call 执行前落实这条边界： 它从展开后的请求识别多阶段 FP&A 意图，要求目标 Graph 与请求阶段一致， 允许主 Agent 执行规划前置准备，阻断提前模拟、推荐、冻结或执行。Graph worker 没有 graph_list/graph_run 时不会激活该护栏，因此节点仍可执行被分配的单一阶段。 首次在可信项目进入 FP&A 工作流时，护栏会把 package 自带的 Graph 模板安装到 .agent-graph/graphs；较旧的同名模板和已经退役的拆分 Graph 会先移入 .agent-graph/graphs_backup_v* 再更新，因此 graph_list 能直接发现当前组合 Graph，同时保留可恢复的旧定义。非可信项目、符号链接目录和更高版本的项目 Graph 均不会被覆盖。

数据 Extension（fpa-data）

extensions/fpa-data 注册八个面向分析的工具，只读外部数据，结果证据保存在当前工作区：

工具	作用
fpa_data_catalog	数据字典：数据集、维度、指标定义与聚合语义、各表实时日期覆盖、已知数据坑
fpa_check_data	按任务和月份检查数据，默认返回资格、限制与逐项状态摘要
fpa_data_evidence	按 result_id 和 JSON path 分页读取已保存的完整证据，不重新执行来源查询
fpa_query	结构化聚合查询：指标 + 维度 + 时间粒度 + 过滤；SQL 由代码生成，比率按“先聚合分子分母、再相除”计算
fpa_cohort	安装 cohort 的 LTV / ROAS / 留存曲线；分别核验日历成熟、收入/留存/花费覆盖与分母，不完整的指标返回 NULL 并给出原因
fpa_calc	确定性计算器：命名公式求值（四则、abs/min/max/round），NULL 与除零安全传播
fpa_revenue_bridge	同范围两期事件净收入桥：完整聚合所有事件，独立其他项、退款影响及汇总/明细勾稽一次返回
fpa_compare	双期间对比：差值、百分比变化、逐行贡献度全部由代码计算

fpa_data_catalog 默认只读取数据字典和各数据集日期覆盖，不执行随表规模增长的精确行数扫描。确实需要精确 row_count、App 数量和 cohort-size 覆盖时显式传入 include_stats: true；需要 App 列表时传入 include_apps: true。这些补充信息都有独立的 5 秒预算，单个数据集超时会返回对应的 *_unavailable 说明，不会丢失其它数据集的覆盖信息。认证、网络、服务端错误和调用方取消仍然抛出。

设计契约：模型不写 SQL、不做任何算术。模型只从注册表中选择数据集、指标和维度；SQL 生成、数据库聚合和全部派生计算（比率、差异、LTV/ROAS/留存、临时公式）都在 Extension 代码内完成，缺数据或除零返回 NULL，绝不编造数值。

Extension 内置的关键防护：

• appsflyer_ua_campaign_daily 的三种 breakdown_type 是同一份花费的重叠切分；每次查询自动锁定一种，避免花费被重复计算。
• 每个查询结果都带 date_min / date_max / source_rows 覆盖率元数据；各数据集日期覆盖不一致时以此为准。
• Apple 指标按来源语义聚合：COUNT 求和、AVERAGE 取日均、LATEST 取期末值。
• cohort 规模缺失（2026-08-01 之前）时 LTV/留存分母返回 NULL。

Artifact 与看板 Extension

fpa-artifacts 提供 fpa_forecast_finalize，把紧凑 Forecast plan 一次性合成、校验、按目标周期推导生命周期角色并冻结；模型无需在 Graph handoff 与 ledger 枚举之间转译 forecast_role。通用的 fpa_artifact_commit 仍负责 approved_cycle_forecast 和 execution_receipt 的严格字段校验、对账、稳定指纹和原子落盘。只有工具返回成功后的 JSON 才是冻结产物，Markdown 不是正式数据源。

fpa-execution 的确定性服务提供执行请求准备、独立授权和整体人工回执；Agent Extension 只暴露状态读取、精确请求解析和 execution-evidence 发布工具，不能伪造登录用户的写入身份。执行请求与回执 append-only；重复提交使用稳定提交 ID 幂等恢复。人工回执始终是 reported / complete_with_limits，实际支出、applied mutations、外部回执和核验证据保持空值。Backtest 模式禁止创建上述对象。

同一 Extension 还提供 fpa_evolution_evaluate：对已经关闭且可比较的 Forecast 方法确定性计算 WAPE、MAPE、Bias、区间覆盖率和相对 baseline 改善；对分析 Playbook 计算客观检查通过率与耗时改善。工具只输出 fpa-evolution-evidence/v1 证据及其生命周期策略，不直接改变 Agent，也不会凭一次结果宣布方法更优。调用方必须提供 kind:sha256:<64hex> 格式的精确 Forecast/Actuals 或分析/review 引用和 period_end；缺少完整预测区间、baseline、有效分母或历史时点证明时会返回不足证据。

fpa-dashboard 提供分模块发布工具和兼容的闭环刷新工具：

工具	作用
fpa_dashboard_module_status	只读检查各独立模块及当前 Dashboard revision
fpa_dashboard_publish_review	只发布 period-review，保留其他模块
fpa_dashboard_publish_strategy	只发布带确认/修改动作的 next-strategy，并绑定当前主会话
fpa_dashboard_publish_forecast	确认策略并冻结预测后，只发布 next-forecast
fpa_dashboard_status	只读检查当前 manifest、构建回执和各数据集是否可读
fpa_dashboard_refresh	从冻结预测、可选执行回执和实时 Actuals 生成固定的闭环看板；先 preview，再携带相同指纹原子 publish
fpa_dashboard_refresh_queue	检查或处理持久刷新队列；主 Agent 用 enqueue_artifact 显式交接 Forecast/Execution，Actuals watermark 按 SLA 轮询并幂等发布

持续刷新由 package 自带的独立 worker 驱动，Web 保持严格只读：

fpa-dashboard-worker --workspace /absolute/path/to/workspace

使用 --once 可接 cron/systemd timer；常驻运行时默认每 30 秒检查队列，并按内部 5 分钟 Actuals 水位 SLA 轮询。worker 只消费精确 immutable artifact refs，执行有界重试，并通过与交互工具相同的原子 publisher 发布。

周期关账不按“过了若干小时”推断。ETL 必须原子写入一份有界、非 group/world-writable 的 JSON 关账信号，并同时配置 FPA_ACTUALS_CLOSE_SIGNAL_PATH 与 FPA_ACTUALS_CLOSE_SIGNAL_ROOT。可信根必须位于 Agent workspace 之外，且文件及其目录链必须由 Agent 运行身份之外的控制面身份拥有；否则 worker 会拒绝把周期判为已关账：

{"kind":"fpa.actuals.source-close","schema_version":1,"dataset":"ua_spend","signal_id":"ua-close-2026-08-v1","closed_through":"2026-08-31","emitted_at":"2026-09-01T03:00:00Z"}

缺少该信号时，完整日期覆盖仍只算累计 Actual，不开放整周期 Forecast vs Actual 差异。

看板按 app_id + store + channel_group 精确限定同口径 Actuals，比率全部在聚合后重算，缺值保持 NULL；未获批的付费分片只形成告警，不混入预测对比。整周期 Forecast vs Actual 只在 Actuals 提供统一、完整、可勾稽的单快照，且比较基线是周期开始前冻结的 original Forecast 时开放；EAC、稀疏覆盖和多查询未核验快照都不会生成伪差异。发布器写内容寻址的数据集、不可变 generation catalog，并最后原子提升 manifest.json，不会让 Web 端读到半成品代际。

凭证配置

Extension 通过 Supabase Management API 只读查询，凭证仅从环境变量读取，绝不写入包内：

export SUPABASE_PROJECT_REF="<project ref>"
export SUPABASE_ACCESS_TOKEN="<personal access token, sbp_...>"

在启动 Pi 前设置。未配置时工具报错并说明缺哪个变量，不发出任何查询。

Backtest 启动模式

回测必须在启动 Pi 前显式配置，不能只在提示词或 Graph 中把 forecast_role 写成 backtest：

export FPA_RUN_MODE="backtest"
export FPA_EFFECTIVE_AT="2026-05-01T00:00:00Z"

默认回测直接复用现有 SUPABASE_PROJECT_REF 和 SUPABASE_ACCESS_TOKEN，但所有查询都会被截断到 FPA_EFFECTIVE_AT 对应的业务日期。启动后 RunProfile 不可热切换；推进模拟时间必须停止并 重启进程。例如先在 5 月 1 日冻结 Forecast，周期结束后改为 6 月 1 日， 再用原 Forecast 的精确 ref 运行 fpa-backtest-review。

如需严格无回刷证据，可额外启用高级快照模式：

export FPA_DATA_SNAPSHOT_REF="kind:sha256:<64 lowercase hex>"
export FPA_BACKTEST_SUPABASE_PROJECT_REF="<isolated snapshot project ref>"
# 默认复用 SUPABASE_ACCESS_TOKEN；快照项目使用单独凭证时设置：
export FPA_BACKTEST_SUPABASE_ACCESS_TOKEN="<snapshot access token>"
# 查询 CSV 数据集时还必须设置：
export FPA_BACKTEST_CSV_ROOT="/absolute/path/to/immutable/snapshot/csv"

启动配置会形成不可变 RunProfile。Backtest 模式下：

• effective_at 是模拟的历史决策时点；普通查询、Catalog 和 Cohort 都会被截断到该日期。
• 默认 live_cutoff 模式读取现有 Supabase；它适合流程调试和业务复盘，但可能看到后来补录或重算的历史数据，因此不是严格无泄漏证据。
• live_cutoff 模式允许为当前 effective_at 手动上传回测专用财务 CSV。上传人必须确认该版本在模拟时点已经存在；版本按模拟时点隔离，不读取或覆盖经营模式上传，且不能包含当时尚未完成的月份。
• 同时提供 snapshot ref 和独立项目时进入 immutable_snapshot 模式；该 project ref 不得与正式库相同。严格 CSV 快照使用 FPA_BACKTEST_CSV_ROOT。
• immutable_snapshot 模式保持只读，不接受页面上传。
• Forecast 的生命周期角色仍相对 effective_at 推导。例如在 5 月回测“6 月计划”时，run_mode=backtest、forecast_role=next_plan。
• Forecast 正文和 Ledger 同时记录 RunProfile、快照引用与生命周期角色；调用方提供的 frozen_at 仍会被忽略。
• 规划完成后与经营模式一致，由 fpa_dashboard_publish_review 和 fpa_dashboard_publish_strategy 发布复盘与策略模块；人工确认仍由 fpa_strategy_decision_commit 固化，随后发布只读 next-forecast。
• 回测允许继续生成执行计划、完成独立执行授权、提交人工回执，并发布 execution-evidence。这些记录使用 FPA_EFFECTIVE_AT 作为业务时间，修改模拟时间并重启后仍沿同一回测时间线继续；旧版按单一时点保存的计划会无损迁移。
• 回测执行仅用于完整流程调试：不会调用真实投放平台。完整闭环刷新、通知、真实投放及经营 current pointer 更新仍被阻断，人工回执继续明确标记为未经过外部核验。

FPA_DATA_SNAPSHOT_REF 是可选的内容寻址快照身份；一旦设置，必须同时设置独立 snapshot project。仅按日期读取持续回刷的正式 Mart 不构成严格无泄漏回测。正式模式下不要残留上述 Backtest 变量，否则启动配置会拒绝加载。

输入契约

两个 Prompt 的基本参数都是：

<project-root> <cycle-id> [instructions]

数据来源优先级：

1. fpa_data_catalog 等 fpa_* 工具（Supabase 集市，推荐）。
2. 运行时显式提供的字段目录与 Schema 路径。
3. <project-root>/LOCAL_FPA_MART_FIELD_CATALOG.md 与 <project-root>/LOCAL_FPA_MART_SCHEMA.sql（本地文件回退）。

资源不存在时必须报告缺口，不得回退到开发者机器路径或编造输入。

本地安装

从 npm 安装正式版本：

pi install npm:@viccydev/pi-fpa

从本地工作区安装开发版本：

pi install /absolute/path/to/pi-fpa
pi list

本地路径只写入 Pi settings，不复制源目录。修改包后使用 /reload 或重启 Pi。

团队分发建议使用固定 Git tag：

pi install git:github.com/linyqh/pi-fpa@v1.1.0

发布到 npm

发布动作由 GitHub Release 触发。Release 标签必须严格使用 v<package.json version>，例如版本 1.1.0 对应 v1.1.0。工作流会检出该标签，执行 npm ci、npm test 和包内容预检，全部通过后发布公开包 @viccydev/pi-fpa。普通 Release 发布到 latest，Prerelease 发布到 next。

发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：

1. Provider：GitHub Actions。
2. Organization or user：linyqh。
3. Repository：pi-fpa。
4. Workflow filename：publish.yml。
5. Allowed actions：npm publish。

工作流必须保留 permissions.id-token: write，并使用满足 npm Trusted Publishing 最低版本要求的 Node/npm；不要重新添加 NPM_TOKEN 或 NODE_AUTH_TOKEN。当前 GitHub 仓库为 private，OIDC 发布可用，但 npm 不会生成 provenance。当前许可证仍是 UNLICENSED；若准备让第三方使用或修改本包，应先明确许可证。

使用

/fpa-plan-cycle /path/to/project 2026-Q3 "按 App、Store、Channel Group 规划；预算上限见 planning input"
/fpa-review-cycle /path/to/project 2026-Q3 "使用精确 forecast/execution refs 和新到达的 Actuals snapshot"
/skill:fpa-refresh-dashboard "预览并发布当前项目的预测闭环看板"

规划入口停在 reviewed_strategy_handoff，不会等待人工批准、冻结 Forecast 或进入真实策略执行。后续分别由 fpa-forecast-freeze 和 fpa-strategy-execution Graph 承担。若宿主没有 Graph 能力、且用户只请求一个隔离执行阶段，才可在单独、已授权的运行中显式调用：

/skill:fpa-execute-approved-strategy <exact committed forecast ref and execution scope>

资源迁移注意

如果 ~/.pi/agent/skills/ 中仍有同名 fpa-* Skill，Pi 会报告命名冲突并采用先发现的资源。先在隔离配置中验证本包，确认来源路径后再通过 pi config 禁用旧副本或将旧目录移出发现路径。全局 ~/.pi/agent/extensions/ 下如有旧的数据 extension（如 ios-fpa），工具名不同不会冲突，但建议确认是否仍需保留。

验证

npm test          # 包结构 + extension 单元测试 + Pi loader 冒烟
npm run test:live # 可选：需要 SUPABASE_* 环境变量，对真实库做只读冒烟
npm run pack:check

数据口径自动发现（1.3.0）

data-rules-2 在原有数据服务内增加只读元数据发现，页面与 fpa_check_data 共用结果；fpa_data_catalog 也返回 source_discovery。兼容 v1 契约，新增 DataSourceInfo.discovery 和 CheckReport.discovery，没有新增工具参数或数据库迁移。

• 通过 pg_constraint 读取已验证的业务主键/唯一键。只接受真实存在、符合标识符规则、包含业务日期及 App 身份的字段组合，技术自增 ID 不会被当作业务粒度。服务端明确配置的业务键保留优先级。
• 读取 app_registry 的当前有效 App/平台清单及未映射数量。清单限 2,000 对并标注截断；只在一次请求内复用查询。当前注册清单不自动转为某历史月份、某数据源的 expectedApps，也不承诺逐日出数。
• 对所选记录单独检查 NULL、空字符串和非法 App 代码。这些记录不计入 App 数量。逐日覆盖按 App/平台分别统计，不允许两个平台的缺天相互抵消。与当前注册表的差异只报告待核对，避免把历史退役/改名误判为漏数。
• 投放花费的 USD 从 cost_usd 明确的 currency=USD 字段说明发现；事件/cohort 金额从四个注册金额字段的 USD 说明发现。AppsFlyer 业务时区从本次选中记录的 app_timezone 验证；Mixpanel UTC 从 business_date 的明确说明发现。数据库会话时区不会充当业务时区，不跨表猜测 Master API 或 Apple 报表时区。
• 同一范围出现混合时区或与人工声明冲突时不通过。产品行为来源时区不同会明确排除直接跨来源按日比较；各来源仍可独立检查。
• 使用实时数据加业务日期截止的回测，在投放就绪检查中还检查 source_data_as_of 和 exported_at。晚于有效时点的版本不可用，证据缺失返回未确认；不能把后来累计的 LTV 或修订值视为过去已知。配置的不可变快照保持原有独立来源路径。
• 查询失败、权限不足、证据缺失不被转换为零或通过。数据库约束发现失败时仍支持明确的服务端声明；登记表不可读不影响 CSV。所有发现包含查询时间、来源和证据，性质 nature 和出数承诺 recording 不会根据表名、行数或日期连续性自动填为真实/完整。

discovery 是本次检查的元数据证据，不是原始数据快照。字段说明和人工声明也不等于外部凭证审计。本轮加强的是数据就绪服务；现有 fpa_query 的业务日期截断不能单独证明当时可知，Agent 应先读 fpa_check_data 的限制，历史复盘需使用符合时点的源版本。

验证覆盖约束发现、空 App、跨平台缺天、时区冲突、登记表不可用/截断、无效证据、并发请求隔离和回测晚到版本。兼容目标为 Pi 0.84.1；包结构依据 Pi package 文档，保持现有 Extension 注册方式。

映射缺口容忍（data-rules-4）

局部 App 映射缺口不再一律阻断后续分析。若每项受检指标的缺失影响都有可靠证据且均不超过 5%，基础指标保留为 usable_with_limits，报告同时排除未映射记录的 App 级归因。影响未知、证据不可靠或任一指标超过阈值时仍保持 unusable；整表缺失、关键值异常、重复记录和回测时点穿越也不受此规则放宽。

Workspace-root layout

FPA-Agent layout v2 uses the tenant workspace itself as the project cwd. A regular .fpa-workspace.json containing {"layoutVersion":2,"projectName":"default"} explicitly selects this layout. Data, plans and dashboards are resolved inside that cwd, alongside artifacts/ and .agent-graph/. The logical project name remains default, preserving existing refresh event and subscription identities. The standalone worker accepts this root with --workspace and no child project. Unmarked CLI projects retain the previous layout with workspace data beside cwd. Do not infer the layout from a basename or a process-global tenant environment variable.

经营计划服务提供 deletePlan(ctx, cycleId, { expectedRevision })，按工作区、运行模式和回测时间线删除计划记录。删除以带版本的 tombstone 保留记录，列表、详情和后续写入忽略已删除记录；旧时间线迁移不会复活该周期。同周期重建归档旧记录并继续递增版本，旧会话与旧版本不能修改新计划。数据文件、不可变产物和会话不在删除范围内；Web 宿主负责拒绝运行中的删除请求和提供确认交互。

经营计划页确认输入

preparePlanInputs 返回数据源读取状态和口径建议；未知或冲突的时区、币种保持未确认。validatePlanInputs 校验精确目标周期、历史基线、时区和非空范围。Web 的明确确认与聊天工具 fpa_plan_confirm_inputs 共用 confirmPlanInputs，均绑定原会话和乐观 revision；确认后 buildPlanAnalysisPrompt 引导主 Agent 执行 fpa_plan_preflight、实际数据诊断与驱动分析，并封存前置工件。预检及封存通过后再启动策略 Graph；Graph 负责并行场景、推荐和独立审核，保留策略审批停点。

计划准备服务的 choices 提供下拉选项及读取状态。App、商店与产品分组分别来自当前注册表的 app_code、platform、studio_code；渠道使用投放数据的 media_source，保持原始值，不与广告版位 channel 混用。渠道发现按运行模式选择数据连接并限制业务日期，失败或截断会明确标记，不证明历史数据可得性。时区提供常用报表时区与来源声明值，报告币种提供当前指标使用的 USD，候选值本身不代替用户确认。

选择工作室后，confirmPlanInputs 以当前注册表解析工作室、App、商店的交集并保存明确 App 清单；不根据 App 代码前缀猜测工作室。无法完整读取、工作室消失或交集为空时拒绝确认。读取凭据仅来自宿主的服务端上下文，不进入 JSON 传输契约。当前注册表映射不证明历史归属和月份覆盖。

来源口径确认（data-rules-6）

Web 宿主可调用数据服务 readSourceSettings(ctx, sourceId) 和 saveSourceSettings(ctx, sourceId, { timezone, currency, expectedRevision })，让用户填写真实来源导出的业务日时区与金额币种。当前支持五类 Supabase 来源及 USD，选项由插件返回；未配置时区保持空值，不默认使用计划时区。

设置在当前数据工作区 .fpa-data/source-settings.json 持久化，记录操作者、时间和乐观版本；只覆盖对应来源的 timezone/currency，其他服务端信任与覆盖策略保持不变。宿主必须从认证上下文提供 workspaceRoot 和 actor，不能接受浏览器传入。通用 Agent write/edit 不能替用户写这份声明。

目录、检查与规划预检共用合并后的策略。口径变化使旧报告、预检和后续交接资格失效；保存不能直接标记检查通过，也不会重写源数据日期或换算金额。重新检查仍核验声明与数据库中的明确证据，不用人工声明覆盖已知冲突。该服务不注册模型可自行确认口径的 Pi 工具。

分析上下文与证据（2.3.7）

企业上下文默认返回 App 摘要，指定 fpa_company_context 的 mode=evidence 与 app_codes 才读取项目依据；省略代码只读完整企业背景。长证据可按版本续读，不重复注入全部 App 依据。

数据工具默认使用紧凑 JSON，单次正文限制 24,000 字符；完整结果保存在工作区 .fpa-data/tool-results/。通过 fpa_data_evidence 的 result_id、path 和分页读取保存的证据，超大单项支持 mode=fragment。SQL 默认不返回，可读取保存的 sql。快照绑定工作区、运行模式及回测时点，不是自动查询缓存，也不证明来源当前仍未改变。摘要保留资格和负面状态，未读完证据时不能声称检查完整。

Cohort 逐 App、平台和安装批次验证 D0–DN 收入、DN 活跃和同一安装范围的 UA 费用。日历成熟不代替完整性，缺行不填零；LTV/ROAS 使用扣退款后的净收益。缺口或计数异常仅限制相关指标，已观测部分单独保留。月度复盘复用同范围结果，并对齐跨来源 App/平台范围；倒算“其他项”的零残差不能作为独立勾稽证明。

注册契约参照 Pi Extension API，通过 Pi 0.84.1 实际加载验证；新增 cohort 测试使用仅开发依赖 PGlite 执行真实 PostgreSQL SQL。

金额检查与完整收入桥（2.3.8）

fpa_check_data 的 data-rules-7 按指标和粒度检查实际金额。product_behavior 覆盖事件每日汇总金额、事件 JSON 明细以及二者勾稽；revenue_store_checks 校验 Apple 实际 JSON 指标值。顶层 product_events.net_proceeds 的资格不代表 product_events.event_name.net_proceeds 已通过。局部金额问题只限制受影响的指标；必要来源、范围、重复记录等公共问题仍保留原有约束。旧规则检查需重新执行。

每个检查摘要保留 metrics、metricScope 和明细数量。完整缺失日期按 App/platform 保存在 details 数组，模型可用返回的 details_path 分页读取，不再在保存前裁成前 40 个 App/platform、前 10 个日期。

fpa_revenue_bridge 接受 baseline/current: {from,to} 与同范围 app_codes、platforms；可用 major_events 指定精确事件名，默认按规模选主要事件，不根据名称猜业务分类。同一次只读查询独立聚合两期汇总金额和全部事件明细，返回主要事件、独立其他项、退款影响及残差。明细中的原始空值不当零，缺失与无事件记录明确区分；残差不塞进其他项。完整事件依据保存在租户结果快照中，默认聚合结果无需模型读完所有事件分页后再抄入计算器。

该工具用于同来源事件净收入的变化解释，不认证会计收入、现金到账或因果关系，也不替代月度来源资格检查。新工具沿用 Pi 0.84.1、租户工作区隔离和回测截止约束。