pi-fpa

Business history reset (2.4.1)

The server-only operating service can inspect and clear an explicit allowlist of derived business history, including all operating/backtest snapshots, proposals, budgets, checks, plans, execution records, dashboard publications, artifacts and Graph run history. Source CSVs, import versions, source declarations, company profiles and Graph definitions survive. The host owns confirmation, authentication, session deletion and tenant request exclusion. Reset is not an Agent tool.

The dashboard worker and reset share withHistoryResetLock; a durable pending receipt pauses publication and ordinary host requests until cleanup succeeds or is explicitly resumed. Restart both host and worker after upgrading. Actual deletion must be validated in an isolated workspace; publishing this capability does not authorize clearing a user's workspace automatically.

Operating workspace service (2.4.0)

extensions/fpa-operating/service.ts exports immutable operating snapshots, App-scoped analysis contexts, paginated evidence, deterministic budget scenarios and standalone proposals. The host provides tenant APIs and rendering; financial calculations stay in this plugin.

• Default scope: the previous complete calendar month, iOS, all markets. Aggregate the full observed scope before pagination, retain registered Apps without observations, and distinguish real financial revenue from event proceeds. Missing costs never become zero profit.
• app_direct_costs_monthly uses existing CSV preview, monthly replacement and checks; the independent app_direct_costs task does not expand monthly-plan prerequisites.
• Scenarios preserve existing revenue and use explicit marginal gain/loss and cost assumptions. Current-month adjustments require matching actual spend through the current source business day and cannot transfer incurred spend.
• Confirmation checks exact proposal and budget revisions, snapshot freshness and overlapping uncompleted proposals. An atomic ledger publishes proposal versions, budget changes and idempotency receipts together. Adoption and execution require user actions; backtests cannot adopt operating budgets.
• .fpa-data/operating/<runKey> is separate from monthly plans and Dashboard. Generic file tools cannot directly alter these records. This tool ownership guard is not an OS sandbox for arbitrary code.
• fpa_operating_context and fpa_preview_scenario let the Agent inspect evidence and prepare scenarios, without adopting budgets or reporting execution.

npm run test:operating covers 131 Apps, missing/zero/synthetic values, evidence scope, incremental calculations, incurred spend, concurrent and duplicate confirmation, overlapping budgets, tenant/path/run isolation, and prompt idempotency. Automated fixtures do not certify real financial data.

面向 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、租户工作区隔离和回测截止约束。