@viccydev/pi-fpa 0.9.1 → 0.9.2

package/README.md

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

package/extensions/fpa-dashboard/stage-projector.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 
 import { stableJson } from "../fpa-artifacts/store.ts";
 import type { DashboardModuleBuild } from "./module-publisher.ts";
-import type { TableCell } from "./projector.ts";
+import type { TableCell, TableDataset } from "./projector.ts";
 import type { ApprovedCycleForecast } from "../fpa-artifacts/contracts.ts";
 import type { ArtifactRefV2 } from "../fpa-artifacts/store.ts";
 
@@ -56,10 +56,80 @@ function strategyAction(value: unknown, label: string): StrategyAction {
 	throw new Error(`${label} must be one of grow, hold, cut, stop.`);
 }
 
+function signedPercent(value: unknown): TableCell {
+	if (typeof value !== "number" || !Number.isFinite(value)) return cell(value);
+	return `${value > 0 ? "+" : ""}${(value * 100).toFixed(1)}%`;
+}
+
+/** `metric` repeats across scopes, so the scope is what makes a headline row identifiable. */
+function headlineLabel(entry: Record<string, unknown>, index: number): string {
+	const metric = requiredString(entry.metric ?? `Metric ${index + 1}`, `driver_analysis.headline_results[${index}].metric`);
+	return typeof entry.scope === "string" && entry.scope.trim() !== "" ? `${metric} · ${entry.scope}` : metric;
+}
+
+/**
+ * The `driver_analysis` contract publishes `headline_results` as a list of metric rows
+ * carrying actual/baseline/variance. Earlier artifacts used a flat `{ metric: value }`
+ * map, so both shapes are projected here rather than rejecting the contract shape.
+ */
+function headlineTable(value: unknown): TableDataset {
+	if (Array.isArray(value)) {
+		return {
+			label: "核心结果",
+			columns: [
+				{ key: "metric", label: "指标" },
+				{ key: "actual", label: "实际", align: "right" },
+				{ key: "baseline", label: "基准", align: "right" },
+				{ key: "variance", label: "变化", align: "right" },
+				{ key: "variance_pct", label: "变化率", align: "right" },
+			],
+			rows: value.map((item, index) => {
+				const entry = record(item, `driver_analysis.headline_results[${index}]`);
+				return {
+					metric: headlineLabel(entry, index),
+					actual: cell(entry.actual),
+					baseline: cell(entry.baseline),
+					variance: cell(entry.variance),
+					variance_pct: signedPercent(entry.variance_pct),
+				};
+			}),
+		};
+	}
+	const headline = record(value ?? {}, "driver_analysis.headline_results");
+	return {
+		label: "核心结果",
+		columns: [{ key: "metric", label: "指标" }, { key: "value", label: "结果", align: "right" }],
+		rows: Object.entries(headline).map(([metric, entry]) => ({ metric, value: cell(entry) })),
+	};
+}
+
+/** Evidence is a list in the contract; a bare JSON dump of it is unreadable in a table cell. */
+function listCell(value: unknown): TableCell {
+	return Array.isArray(value) ? lines(value) : cell(value);
+}
+
+/**
+ * `data_limits` is the contract field and `limitations` is what older artifacts wrote.
+ * They are merged instead of ranked so a published module never silently drops one set.
+ */
+function limitationRows(analysis: Record<string, unknown>): Array<Record<string, TableCell>> {
+	const seen = new Set<string>();
+	const rows: Array<Record<string, TableCell>> = [];
+	for (const key of ["data_limits", "limitations", "risks"] as const) {
+		if (analysis[key] === undefined) continue;
+		for (const item of array(analysis[key], `driver_analysis.${key}`)) {
+			const dedupe = stableJson(item);
+			if (seen.has(dedupe)) continue;
+			seen.add(dedupe);
+			rows.push({ item: cell(item) });
+		}
+	}
+	return rows;
+}
+
 export function projectReviewModule(input: unknown): DashboardModuleBuild {
 	const analysis = record(input, "driver_analysis");
 	if (analysis.artifact_type !== "driver_analysis") throw new Error("Review publication requires artifact_type=driver_analysis.");
-	const headline = record(analysis.headline_results ?? {}, "driver_analysis.headline_results");
 	const drivers = array(analysis.drivers ?? [], "driver_analysis.drivers");
 	return {
 		id: "period-review",
@@ -75,25 +145,25 @@ export function projectReviewModule(input: unknown): DashboardModuleBuild {
 			{
 				id: "review-headline",
 				type: "table",
-				span: "half",
+				span: "full",
 				dataset: "review-headline.json",
-				data: {
-					label: "核心结果",
-					columns: [{ key: "metric", label: "指标" }, { key: "value", label: "结果", align: "right" }],
-					rows: Object.entries(headline).map(([metric, value]) => ({ metric, value: cell(value) })),
-				},
+				data: headlineTable(analysis.headline_results),
 			},
 			{
 				id: "review-drivers",
 				type: "table",
-				span: "half",
+				span: "full",
 				dataset: "review-drivers.json",
 				data: {
 					label: "关键驱动",
-					columns: [{ key: "driver", label: "驱动" }, { key: "impact", label: "影响" }, { key: "evidence", label: "证据" }],
+					columns: [{ key: "driver", label: "驱动" }, { key: "impact", label: "影响", align: "right" }, { key: "evidence", label: "证据" }],
 					rows: drivers.map((item, index) => {
 						const driver = record(item, `driver_analysis.drivers[${index}]`);
-						return { driver: cell(driver.driver ?? driver.name ?? `Driver ${index + 1}`), impact: cell(driver.impact ?? driver.effect), evidence: cell(driver.evidence ?? driver.evidence_ids) };
+						return {
+							driver: cell(driver.driver ?? driver.name ?? `Driver ${index + 1}`),
+							impact: cell(driver.impact ?? driver.effect ?? driver.quantified_contribution),
+							evidence: listCell(driver.evidence ?? driver.evidence_ids),
+						};
 					}),
 				},
 			},
@@ -105,7 +175,7 @@ export function projectReviewModule(input: unknown): DashboardModuleBuild {
 				data: {
 					label: "限制与风险",
 					columns: [{ key: "item", label: "说明" }],
-					rows: array(analysis.limitations ?? analysis.risks ?? [], "driver_analysis.limitations").map((item) => ({ item: cell(item) })),
+					rows: limitationRows(analysis),
 				},
 			},
 		],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",

package/skills/fpa-analyze-drivers/references/artifact-contract.md

@@ -8,6 +8,7 @@ actuals_snapshot_id: string
 comparison_basis: string
 headline_results:
   - metric: string
+    scope: string | absent   # required when the same metric is reported for more than one scope
     actual: number | null
     baseline: number | null
     variance: number | null