@viccydev/pi-fpa 0.7.1 → 0.8.0

package/README.md

@@ -148,12 +148,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.7.1
+pi install git:github.com/linyqh/pi-fpa@v0.8.0
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.7.1` 对应 `v0.7.1`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.8.0` 对应 `v0.8.0`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 

package/extensions/fpa-dashboard/compat-publisher.ts

@@ -0,0 +1,45 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { DashboardBuild } from "./projector.ts";
+import type { DashboardProjectorProvenance, DashboardProjectorRuntime } from "./provenance.ts";
+import { publishDashboard, resolveDashboardDir } from "./publisher.ts";
+import { publishDashboardModule, readDashboardModuleManifest } from "./module-publisher.ts";
+import type { DashboardActualsSnapshot } from "./source.ts";
+
+interface Options {
+	cwd: string;
+	build: DashboardBuild;
+	projector: DashboardProjectorProvenance;
+	runtime: DashboardProjectorRuntime;
+	actualsSnapshot?: DashboardActualsSnapshot;
+	allowBacktestDisplay?: boolean;
+}
+
+export async function publishDashboardProjection(options: Options): Promise<{ dashboardDir: string; fingerprint: string; publishedDatasets: number }> {
+	const dashboardDir = await resolveDashboardDir(options.cwd);
+	let schemaVersion: number | undefined;
+	try {
+		schemaVersion = (JSON.parse(await readFile(join(dashboardDir, "manifest.json"), "utf8")) as { schemaVersion?: number }).schemaVersion;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	if (schemaVersion !== 2) return publishDashboard(options);
+	if (options.build.source.forecast_role === "backtest" && options.allowBacktestDisplay !== true) {
+		throw new Error("A backtest cannot replace dashboard execution evidence without explicit user authorization.");
+	}
+	const current = await readDashboardModuleManifest(options.cwd);
+	const published = await publishDashboardModule({
+		cwd: options.cwd,
+		dashboardTitle: options.build.title,
+		expectedDashboardRevision: current?.dashboardRevision ?? null,
+		module: {
+			id: "execution-evidence",
+			title: "经营执行与校准证据",
+			status: "published",
+			source: { ...options.build.source, warnings: options.build.warnings, projector: options.projector, runtime: options.runtime },
+			widgets: options.build.widgets,
+		},
+	});
+	return { dashboardDir: published.dashboardDir, fingerprint: published.moduleRevision, publishedDatasets: published.publishedDatasets };
+}

package/extensions/fpa-dashboard/coordinator.ts

@@ -9,7 +9,8 @@ import {
 	type ArtifactRefV2,
 	type ForecastRole,
 } from "../fpa-artifacts/store.ts";
-import { dashboardBuildFingerprint, publishDashboard, resolveDashboardDir } from "./publisher.ts";
+import { dashboardBuildFingerprint, resolveDashboardDir } from "./publisher.ts";
+import { publishDashboardProjection } from "./compat-publisher.ts";
 import { buildDashboardProjection } from "./service.ts";
 
 const EVENT_MAX_BYTES = 64 * 1024;
@@ -723,7 +724,7 @@ async function defaultWorker(event: DashboardRefreshEvent, projectRoot: string,
 	if (event.desired_generation_id && generationId !== event.desired_generation_id) {
 		throw new ObsoleteDashboardRefreshError("Dashboard inputs changed after polling; the stale desired generation must be replanned.");
 	}
-	await publishDashboard({ cwd: projectRoot, build: result.build, projector: result.projector, runtime: result.runtime, actualsSnapshot: result.actuals });
+	await publishDashboardProjection({ cwd: projectRoot, build: result.build, projector: result.projector, runtime: result.runtime, actualsSnapshot: result.actuals });
 	return {
 		generation_id: generationId,
 		data_as_of: result.build.source.data_as_of,

package/extensions/fpa-dashboard/index.ts

@@ -2,8 +2,19 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { readArtifactByRef, type ArtifactRefV2 } from "../fpa-artifacts/store.ts";
-import { dashboardBuildFingerprint, publishDashboard } from "./publisher.ts";
+import { readArtifactByRef, readProjectJsonFile, type ArtifactRefV2 } from "../fpa-artifacts/store.ts";
+import { dashboardBuildFingerprint } from "./publisher.ts";
+import { publishDashboardProjection } from "./compat-publisher.ts";
+import {
+	dashboardModuleBuildFingerprint,
+	publishDashboardModule,
+	readDashboardModuleManifest,
+	readDashboardModuleSource,
+	transitionStrategyModule,
+} from "./module-publisher.ts";
+import { projectForecastModule, projectReviewModule, projectStrategyModule } from "./stage-projector.ts";
+import type { ApprovedCycleForecast } from "../fpa-artifacts/contracts.ts";
+import { commitStrategyDecision, createStrategyDecisionRequest, readCommittedStrategyDecision } from "./strategy-decision.ts";
 import {
 	enqueueDashboardRefresh,
 	enqueueDashboardRefreshForArtifact,
@@ -28,6 +39,220 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		entry_id: Type.String({ pattern: "^[a-f0-9]{64}$" }),
 		body_fingerprint: Type.String({ pattern: "^[a-f0-9]{64}$" }),
 	}, { additionalProperties: false });
+	pi.registerTool({
+		name: "fpa_dashboard_module_status",
+		label: "FP&A Dashboard Module Status",
+		description: "Inspect independently published FP&A dashboard modules and their current dashboard revision without changing files.",
+		promptSnippet: "Inspect the independently published FP&A dashboard modules",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		executionMode: "parallel",
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			const manifest = await readDashboardModuleManifest(ctx.cwd);
+			return toolResult(manifest ? {
+				status: "available",
+				dashboard_revision: manifest.dashboardRevision,
+				module_order: manifest.moduleOrder,
+				modules: Object.fromEntries(Object.entries(manifest.modules).map(([id, module]) => [id, module ? {
+					status: module.status,
+					revision: module.revision,
+					updated_at: module.updatedAt,
+					interactive: module.interaction?.kind === "strategy-decision",
+				} : null])),
+			} : { status: "missing" });
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_dashboard_publish_review",
+		label: "Publish FP&A Period Review Module",
+		description: "Preview or publish only the period-review dashboard module from a project driver_analysis JSON artifact. Other dashboard modules are preserved.",
+		promptSnippet: "Publish the completed period analysis as its own dashboard module",
+		promptGuidelines: [
+			"This tool is called by the main Agent after the analysis Graph returns; never add it to a Graph tool allowlist.",
+			"Preview first, then publish with the exact preview fingerprint and dashboard revision.",
+		],
+		parameters: Type.Object({
+			mode: StringEnum(["preview", "publish"] as const),
+			analysis_path: Type.String({ minLength: 1 }),
+			expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+			expected_dashboard_revision: Type.Optional(Type.Union([Type.String({ pattern: "^[a-f0-9]{64}$" }), Type.Null()])),
+			dashboard_title: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const module = projectReviewModule(await readProjectJsonFile(ctx.cwd, params.analysis_path, "analysis_path"));
+			const previewFingerprint = dashboardModuleBuildFingerprint(module);
+			const current = await readDashboardModuleManifest(ctx.cwd);
+			if (params.mode === "preview") return toolResult({
+				status: "ready",
+				module_id: module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: current?.dashboardRevision ?? null,
+				widget_count: module.widgets.length,
+			});
+			if (params.expected_preview_fingerprint !== previewFingerprint) throw new Error("Review module inputs changed after preview; preview again before publishing.");
+			if (params.expected_dashboard_revision === undefined) throw new Error("Publish requires expected_dashboard_revision from preview, including null for a new dashboard.");
+			const published = await publishDashboardModule({
+				cwd: ctx.cwd,
+				module,
+				dashboardTitle: params.dashboard_title,
+				expectedDashboardRevision: params.expected_dashboard_revision,
+			});
+			return toolResult({ status: "published", module_id: module.id, preview_fingerprint: previewFingerprint, dashboard_revision: published.dashboardRevision, module_revision: published.moduleRevision });
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_dashboard_publish_strategy",
+		label: "Publish FP&A Strategy Module",
+		description: "Preview or publish only the reviewed next-strategy module and create a server-side decision action bound to the calling main session. Other modules are preserved.",
+		promptSnippet: "Publish the reviewed strategy for human confirmation in the dashboard",
+		promptGuidelines: [
+			"Call this from the main Agent after the strategy Graph returns; Graph nodes must never publish dashboard modules.",
+			"Preview first. Publishing binds the confirmation action to this exact main session and reviewed handoff fingerprint.",
+		],
+		parameters: Type.Object({
+			mode: StringEnum(["preview", "publish"] as const),
+			proposal_path: Type.String({ minLength: 1 }),
+			handoff_path: Type.String({ minLength: 1 }),
+			expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+			expected_dashboard_revision: Type.Optional(Type.Union([Type.String({ pattern: "^[a-f0-9]{64}$" }), Type.Null()])),
+			dashboard_title: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const proposal = await readProjectJsonFile(ctx.cwd, params.proposal_path, "proposal_path");
+			const handoff = await readProjectJsonFile(ctx.cwd, params.handoff_path, "handoff_path");
+			const module = projectStrategyModule(proposal, handoff);
+			const previewFingerprint = dashboardModuleBuildFingerprint(module);
+			const current = await readDashboardModuleManifest(ctx.cwd);
+			if (params.mode === "preview") return toolResult({
+				status: "ready",
+				module_id: module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: current?.dashboardRevision ?? null,
+				strategy_version: module.source.strategy_version,
+				widget_count: module.widgets.length,
+			});
+			if (params.expected_preview_fingerprint !== previewFingerprint) throw new Error("Strategy module inputs changed after preview; preview again before publishing.");
+			if (params.expected_dashboard_revision === undefined) throw new Error("Publish requires expected_dashboard_revision from preview, including null for a new dashboard.");
+			const handoffFingerprint = module.source.handoff_fingerprint as string;
+			const request = await createStrategyDecisionRequest(ctx.cwd, {
+				sessionId: ctx.sessionManager.getSessionId(),
+				strategyVersion: module.source.strategy_version as string,
+				handoffFingerprint,
+			});
+			module.interaction = { kind: "strategy-decision", action_id: request.actionId };
+			const published = await publishDashboardModule({
+				cwd: ctx.cwd,
+				module,
+				dashboardTitle: params.dashboard_title,
+				expectedDashboardRevision: params.expected_dashboard_revision,
+			});
+			return toolResult({
+				status: "awaiting_decision",
+				module_id: module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: published.dashboardRevision,
+				module_revision: published.moduleRevision,
+				action_id: request.actionId,
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_dashboard_publish_forecast",
+		label: "Publish FP&A Forecast Module",
+		description: "Preview or publish only the next-forecast dashboard module from an exact committed approved forecast. Other dashboard modules are preserved.",
+		promptSnippet: "Publish the confirmed strategy forecast as its own dashboard module",
+		promptGuidelines: [
+			"Call this from the main Agent only after fpa_strategy_decision_commit confirmed the exact strategy and the forecast Graph returned an immutable forecast ref.",
+			"Never add this tool to a Graph tool allowlist. Preview first and publish with the exact preview fingerprint and dashboard revision.",
+		],
+		parameters: Type.Object({
+			mode: StringEnum(["preview", "publish"] as const),
+			forecast_ref: artifactRefSchema,
+			strategy_decision: Type.Object({
+				action_id: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+				decision_fingerprint: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+			}, { additionalProperties: false }),
+			expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+			expected_dashboard_revision: Type.Optional(Type.Union([Type.String({ pattern: "^[a-f0-9]{64}$" }), Type.Null()])),
+			dashboard_title: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const decision = await readCommittedStrategyDecision(ctx.cwd, params.strategy_decision.action_id, params.strategy_decision.decision_fingerprint);
+			if (decision.decision !== "confirm") throw new Error("Forecast publication requires a confirmed strategy decision.");
+			const read = await readArtifactByRef(ctx.cwd, params.forecast_ref as ArtifactRefV2);
+			if (read.artifact.artifact_type !== "approved_cycle_forecast") throw new Error("Forecast module requires an approved_cycle_forecast artifact ref.");
+			const forecast = read.artifact as ApprovedCycleForecast;
+			if (forecast.status === "blocked" || !forecast.approval_conditions_satisfied) throw new Error("Forecast module requires a completed forecast whose approval conditions are satisfied.");
+			if (forecast.strategy_version !== decision.strategy_version) throw new Error("Forecast strategy_version does not match the confirmed strategy decision.");
+			const currentStrategy = (await readDashboardModuleManifest(ctx.cwd))?.modules["next-strategy"];
+			if (!currentStrategy || currentStrategy.status !== "approved") throw new Error("Forecast publication requires the current strategy dashboard module to be approved.");
+			const strategySource = await readDashboardModuleSource(ctx.cwd, "next-strategy");
+			if (strategySource?.strategy_version !== decision.strategy_version || strategySource?.handoff_fingerprint !== decision.handoff_fingerprint) {
+				throw new Error("Approved strategy module does not match the confirmed decision lineage.");
+			}
+			const module = projectForecastModule(forecast, params.forecast_ref as ArtifactRefV2);
+			const previewFingerprint = dashboardModuleBuildFingerprint(module);
+			const current = await readDashboardModuleManifest(ctx.cwd);
+			if (params.mode === "preview") return toolResult({
+				status: "ready",
+				module_id: module.id,
+				preview_fingerprint: previewFingerprint,
+				dashboard_revision: current?.dashboardRevision ?? null,
+				forecast_version: forecast.forecast_version,
+				widget_count: module.widgets.length,
+			});
+			if (params.expected_preview_fingerprint !== previewFingerprint) throw new Error("Forecast module inputs changed after preview; preview again before publishing.");
+			if (params.expected_dashboard_revision === undefined) throw new Error("Publish requires expected_dashboard_revision from preview, including null for a new dashboard.");
+			const published = await publishDashboardModule({
+				cwd: ctx.cwd,
+				module,
+				dashboardTitle: params.dashboard_title,
+				expectedDashboardRevision: params.expected_dashboard_revision,
+			});
+			return toolResult({ status: "published", module_id: module.id, preview_fingerprint: previewFingerprint, dashboard_revision: published.dashboardRevision, module_revision: published.moduleRevision });
+		},
+	});
+
+	pi.registerTool({
+		name: "fpa_strategy_decision_commit",
+		label: "Commit FP&A Strategy Decision",
+		description: "Commit an idempotent human strategy confirmation or change request from the original main session, then transition the strategy dashboard module.",
+		promptSnippet: "Commit the dashboard strategy decision in the original main session",
+		parameters: Type.Object({
+			action_id: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+			decision: StringEnum(["confirm", "request_changes"] as const),
+			feedback: Type.Optional(Type.String({ minLength: 1, maxLength: 8000 })),
+		}, { additionalProperties: false }),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const committed = await commitStrategyDecision(ctx.cwd, {
+				actionId: params.action_id,
+				sessionId: ctx.sessionManager.getSessionId(),
+				decision: params.decision,
+				feedback: params.feedback,
+			});
+			const transitioned = await transitionStrategyModule(ctx.cwd, {
+				actionId: params.action_id,
+				status: params.decision === "confirm" ? "approved" : "changes_requested",
+			});
+			return toolResult({
+				status: "committed",
+				decision: committed.decision,
+				decision_fingerprint: committed.decisionFingerprint,
+				decision_path: committed.path,
+				strategy_version: committed.strategyVersion,
+				handoff_fingerprint: committed.handoffFingerprint,
+				dashboard_revision: transitioned.dashboardRevision,
+				next_stage: params.decision === "confirm" ? "run fpa-forecast-freeze Graph, then publish next-forecast module" : "rerun strategy planning with the exact feedback, then republish next-strategy module",
+			});
+		},
+	});
+
 	pi.registerTool({
 		name: "fpa_dashboard_status",
 		label: "FP&A Dashboard Status",
@@ -58,11 +283,13 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 		label: "Refresh FP&A Dashboard",
 		description:
 			"Build the forecast closed-loop dashboard from a committed approved forecast, optional committed execution receipt, and current read-only FP&A Actuals. " +
-			"Preview computes and validates without publishing; publish requires the exact preview fingerprint and atomically promotes a content-addressed generation.",
+			"Preview computes and validates without publishing; publish requires the exact preview fingerprint and atomically promotes a content-addressed generation. " +
+			"A backtest can be displayed only from an exact committed artifact when the user explicitly requests it.",
 		promptSnippet: "Preview or atomically publish the forecast closed-loop FP&A dashboard",
 		promptGuidelines: [
 			"Always call fpa_dashboard_refresh with mode=preview before mode=publish and carry forward the exact preview_fingerprint.",
 			"Never write .fpa-dashboard files with generic file or shell tools; use fpa_dashboard_refresh so calculations, lineage, and atomic publication stay consistent.",
+			"Set allow_backtest_display=true only when the user explicitly asks to display or publish an exact committed backtest; never infer this authorization from Graph completion.",
 		],
 		parameters: Type.Object(
 			{
@@ -70,6 +297,7 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 				mode: StringEnum(["preview", "publish"] as const),
 				locale: Type.Optional(StringEnum(["zh-CN", "en-US"] as const)),
 				expected_preview_fingerprint: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$" })),
+				allow_backtest_display: Type.Optional(Type.Boolean()),
 				scope_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 				cycle_id: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
 				forecast_ref: Type.Optional(artifactRefSchema),
@@ -86,6 +314,9 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			if (hasAnyExactField && exactFields.some((value) => value === undefined)) {
 				throw new Error("scope_id, cycle_id, and forecast_ref must be supplied together; exact refresh never falls back to current artifacts.");
 			}
+			if (params.allow_backtest_display && !hasAnyExactField) {
+				throw new Error("allow_backtest_display requires an exact scope_id, cycle_id, and forecast_ref.");
+			}
 			const exact = hasAnyExactField ? {
 				scopeId: params.scope_id as string,
 				cycleId: params.cycle_id as string,
@@ -96,19 +327,24 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			} : undefined;
 			if (exact) {
 				const exactForecast = await readArtifactByRef(ctx.cwd, exact.forecastRef);
-				if (exactForecast.ledgerContext?.forecast_role === "backtest") {
-					throw new Error("A backtest forecast cannot be previewed or published as the operating dashboard.");
+				const exactRole = exactForecast.ledgerContext?.forecast_role;
+				if (exactRole === "backtest" && params.allow_backtest_display !== true) {
+					throw new Error("Displaying a backtest requires explicit user authorization through allow_backtest_display=true.");
+				}
+				if (params.allow_backtest_display === true && exactRole !== "backtest") {
+					throw new Error("allow_backtest_display is valid only for an exact committed backtest.");
 				}
 			}
 			const { build, forecast, actuals, sliceKeyMismatch, projector, runtime } = await buildDashboardProjection(ctx.cwd, params.preset, params.locale ?? "zh-CN", exact, signal);
-			if (build.source.forecast_role === "backtest") {
-				throw new Error("A backtest forecast cannot be previewed or published as the operating dashboard.");
+			if (build.source.forecast_role === "backtest" && params.allow_backtest_display !== true) {
+				throw new Error("Displaying a backtest requires explicit user authorization through allow_backtest_display=true.");
 			}
 			const previewFingerprint = dashboardBuildFingerprint(build, projector);
 			const summary = {
 				preset: params.preset,
 				preview_fingerprint: previewFingerprint,
 				forecast_version: forecast.forecast_version,
+				forecast_role: build.source.forecast_role,
 				forecast_fingerprint: build.source.forecast_fingerprint,
 				execution_fingerprint: build.source.execution_fingerprint,
 				data_as_of: build.source.data_as_of,
@@ -146,7 +382,14 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			if (params.expected_preview_fingerprint !== previewFingerprint) {
 				throw new Error("Dashboard inputs changed after preview; run preview again before publishing.");
 			}
-			const published = await publishDashboard({ cwd: ctx.cwd, build, projector, runtime, actualsSnapshot: actuals });
+			const published = await publishDashboardProjection({
+				cwd: ctx.cwd,
+				build,
+				projector,
+				runtime,
+				actualsSnapshot: actuals,
+				allowBacktestDisplay: params.allow_backtest_display === true,
+			});
 			return toolResult({ status: "published", ...summary, dashboard_dir: published.dashboardDir, published_datasets: published.publishedDatasets });
 		},
 	});