@guanlin4924/devflow-pi 0.1.4 → 0.1.6

package/README.md

@@ -34,8 +34,11 @@ devflow-pi
 /devflow checkpoint
 /devflow resume
 /devflow-usage
+/usage-stats
 ```
 
+用量统计默认只读取当前项目的隔离会话：`/usage-stats`。需要明确查看历史 OMP 会话时，使用 `/usage-stats omp`，或加筛选条件：`/usage-stats omp --from 2026-08-01 --to 2026-08-10`。历史统计保留真实会话路径，不再把不同项目的长会话文件合并成 `main`；统计只使用 assistant message 的原始 usage，不虚构工具调用成本分摊。
+
 会话继续使用 `devflow-pi --resume`；也可用 `devflow-pi --resume <session-id>` 打开当前项目的指定 Session。OMP 17.2.7 退出时仍会显示上游硬编码的 `omp --resume` 提示，在专项发行版中应替换为这里的 `devflow-pi --resume`，不会去读取官方 OMP 的 Session 目录。
 
 专项 Pi 的隔离边界：
@@ -47,7 +50,7 @@ devflow-pi
 - 只显式加载产品内六个插件根，不自动混入用户或项目的环境 Extension；
 - MCP 默认关闭，避免自动连接用户全局服务器；确需复用时显式加 `devflow-pi --mcp`；
 - `task` 只允许六个 Devflow 角色 Agent，且必须显式写明 agent；同名项目/用户 Agent 与产品定义不一致时拒绝执行；
-- `devflow-pi usage` 和 `devflow_usage_stats` 默认只能统计当前项目的隔离 Session。
+- `devflow-pi usage`、`devflow_usage_stats` 与 `usage_stats` 默认只统计当前项目的隔离 Session；`usage_stats` 显式传 `source=omp` 时才读取 `~/.omp` 历史会话。
 - 以 `devflow-pi` 启动时，确定性工作流和代码索引脚本只从产品包内六插件解析；项目遗留 `.skills` 不会覆盖专项版本。`install.sh --apply` 兼容模式仍可使用项目 `.skills`。
 
 `devflow-pi doctor` 是产品壳和资源检查；TUI 内的 `/devflow doctor` 还会验证活动 Extension、30 个必需 Skills、6 个 Agents，以及 `@smol/@task/@slow` 三个不同的已认证模型。专项 Pi 默认用 `@slow` 处理用户交互和规划，`@smol` 仅负责只读侦察，`@task` 仅负责受限执行与验证。完整产品设计见 [`features/20260805Devflow专项Pi发行版.md`](features/20260805Devflow专项Pi发行版.md)，双模型控制规范见 [`features/devflow-agent-orchestration/00-架构总览.md`](features/devflow-agent-orchestration/00-架构总览.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

package/plugins/devflow-core/extensions/devflow-core.ts

@@ -38,6 +38,7 @@ const READ_ONLY_TOOLS = new Set([
   "devflow_code_index",
   "devflow_context_cursor",
   "devflow_usage_stats",
+  "usage_stats",
 ]);
 
 const PLANNING_AGENTS = new Set(["project-scout", "requirements-auditor", "contract-auditor"]);
@@ -1432,7 +1433,16 @@ export default function devflowCore(pi: ExtensionAPI) {
         const plan = inspected.snapshot?.recovery_plan as Record<string, unknown> | undefined;
         const revision = plan?.expected_revision;
         if (!inspected.result.ok || !plan || plan.classification !== "safe_repairable" || typeof revision !== "number") {
-          ctx.ui.notify("当前状态没有可安全执行的恢复计划；请先运行 /devflow explain-state，并按其中的阻塞证据处理。", "error");
+          const status = typeof inspected.snapshot?.status === "string" ? inspected.snapshot.status : "unknown";
+          const step = compactStep(inspected.snapshot?.next_step) ?? compactStep(inspected.snapshot?.current_step);
+          const stepId = typeof step?.id === "string" ? step.id : "当前步骤";
+          if (inspected.result.ok && status === "in_progress") {
+            ctx.ui.notify(`控制面状态一致，无需恢复。当前步骤是 ${stepId}；请执行 /devflow continue。`, "info");
+          } else if (inspected.result.ok && status === "waiting_checkpoint") {
+            ctx.ui.notify(`控制面状态一致，无需恢复。当前正在等待 checkpoint；请审查产物后执行 /devflow checkpoint。`, "info");
+          } else {
+            ctx.ui.notify("当前状态没有可安全自动执行的恢复计划；请运行 /devflow explain-state，并按其中的阻塞证据处理。", "error");
+          }
           return;
         }
         const confirmed = await ctx.ui.confirm(

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import path from "node:path";
+import { readFileSync } from "node:fs";
 
 import { formatDoctor, runHostDoctor } from "./doctor.ts";
 import { initializeProject, loadProjectContext, resolveProjectRoot } from "./project-context.ts";
@@ -17,6 +18,11 @@ function usage(): string {
   ].join("\n");
 }
 
+function packageVersion(): string {
+  const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version?: unknown };
+  return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+}
+
 function option(args: string[], name: string): string | undefined {
   const index = args.indexOf(name);
   return index >= 0 ? args[index + 1] : undefined;
@@ -32,6 +38,10 @@ function optionalOption(args: string[], name: string): boolean | string | undefi
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
   const command = args[0];
+  if (command === "--version" || command === "-v" || command === "version") {
+    console.log(packageVersion());
+    return;
+  }
   if (command === "--help" || command === "-h" || command === "help") {
     console.log(usage());
     return;

package/src/platform-extension.ts

@@ -1,45 +1,90 @@
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 
-import { aggregateUsage, renderUsage } from "./usage-stats.ts";
+import { aggregateUsageReport, renderUsageReport, type UsageRange } from "./usage-stats.ts";
 
 export interface PlatformExtensionOptions {
   sessionRoot: string;
+  ompSessionRoot: string;
   projectId: string;
 }
 
+type UsageInput = UsageRange & { source?: "project" | "omp"; format?: "table" | "json" };
+
+function commandUsageInput(args: string): UsageInput {
+  const tokens = args.trim().split(/\s+/).filter(Boolean);
+  const read = (flag: string): string | undefined => {
+    const index = tokens.indexOf(flag);
+    return index >= 0 ? tokens[index + 1] : undefined;
+  };
+  const source = read("--source") ?? (tokens[0] === "omp" || tokens[0] === "project" ? tokens[0] : undefined);
+  return {
+    source: source === "omp" ? "omp" : "project",
+    session: read("--session"),
+    from: read("--from"),
+    to: read("--to"),
+  };
+}
+
 export function createPlatformExtension(options: PlatformExtensionOptions) {
   return function devflowPlatform(pi: ExtensionAPI) {
     const { z } = pi.zod;
     pi.setLabel("Devflow Platform Runtime");
-    pi.registerTool({
-      name: "devflow_usage_stats",
+    const usageParameters = z.object({
+      source: z.enum(["project", "omp"]).default("project"),
+      session: z.string().optional(),
+      from: z.string().optional(),
+      to: z.string().optional(),
+      format: z.enum(["table", "json"]).default("table"),
+    });
+    const usageTool = {
       label: "Devflow Usage Stats",
-      description: "Read token and cost totals from this Devflow project's isolated session store.",
-      parameters: z.object({
-        from: z.string().optional(),
-        to: z.string().optional(),
-        format: z.enum(["table", "json"]).default("table"),
-      }),
-      approval: "read",
-      async execute(_id, params) {
-        const input = params as { from?: string; to?: string; format: "table" | "json" };
-        const totals = await aggregateUsage(options.sessionRoot, { from: input.from, to: input.to });
+      description:
+        "Read token and cost totals. source=project (default) reads only the current Devflow project; source=omp explicitly reads ~/.omp history. Session buckets preserve their real relative paths and do not merge unrelated sessions into main.",
+      parameters: usageParameters,
+      approval: "read" as const,
+      async execute(_id: string, params: unknown) {
+        const input = params as UsageInput;
+        const source = input.source ?? "project";
+        const report = await aggregateUsageReport(
+          source === "omp" ? options.ompSessionRoot : options.sessionRoot,
+          source,
+          { session: input.session, from: input.from, to: input.to },
+        );
         return {
           content: [
             {
               type: "text" as const,
-              text: input.format === "json" ? JSON.stringify({ projectId: options.projectId, ...totals }) : renderUsage(totals),
+              text: input.format === "json" ? JSON.stringify({ projectId: options.projectId, ...report }, null, 2) : renderUsageReport(report),
             },
           ],
-          details: { projectId: options.projectId, totals },
+          details: { projectId: options.projectId, ...report },
         };
       },
+    };
+    for (const name of ["devflow_usage_stats", "usage_stats"]) {
+      pi.registerTool({
+        name,
+        ...usageTool,
+      });
+    }
+    pi.registerCommand("usage-stats", {
+      description: "Show token/cost usage. Default is this project; pass `omp` or --source omp for explicit OMP history.",
+      handler: async (args, ctx) => {
+        const input = commandUsageInput(args);
+        const source = input.source ?? "project";
+        const report = await aggregateUsageReport(
+          source === "omp" ? options.ompSessionRoot : options.sessionRoot,
+          source,
+          { session: input.session, from: input.from, to: input.to },
+        );
+        ctx.ui.notify(renderUsageReport(report).slice(0, 12000), "info");
+      },
     });
     pi.registerCommand("devflow-usage", {
-      description: "Show project-scoped Devflow token and cost totals",
+      description: "Alias for /usage-stats (project-scoped)",
       handler: async (_args, ctx) => {
-        const totals = await aggregateUsage(options.sessionRoot);
-        ctx.ui.notify(renderUsage(totals), "info");
+        const report = await aggregateUsageReport(options.sessionRoot, "project");
+        ctx.ui.notify(renderUsageReport(report), "info");
       },
     });
   };

package/src/runtime.ts

@@ -123,6 +123,7 @@ export async function createEmbeddedRuntime(project: ProjectContext, options: Ru
     extensions: [
       createPlatformExtension({
         sessionRoot: sessionDir,
+        ompSessionRoot: path.join(sharedAgentDir, "sessions"),
         projectId: project.manifest.projectId,
       }),
     ],

package/src/usage-stats.ts

@@ -12,6 +12,22 @@ export interface UsageTotals {
   sessionFiles: number;
 }
 
+export interface UsageReport {
+  source: "project" | "omp";
+  sessionRoot: string;
+  filter: { session: string; from?: string; to?: string; timezoneOffset: string };
+  totals: UsageTotals;
+  perModel: Record<string, UsageTotals>;
+  perSession: Record<string, UsageTotals>;
+}
+
+export interface UsageRange {
+  from?: string;
+  to?: string;
+  session?: string;
+  timezoneOffset?: string;
+}
+
 function emptyUsage(): UsageTotals {
   return {
     input: 0,
@@ -29,13 +45,37 @@ function finiteNumber(value: unknown): number {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
-function includeTimestamp(timestamp: unknown, from?: string, to?: string): boolean {
-  if (!from && !to) return true;
+function usageCost(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (value && typeof value === "object") return finiteNumber((value as Record<string, unknown>).total);
+  return 0;
+}
+
+function addUsage(target: UsageTotals, usage: Record<string, unknown>): void {
+  target.input += finiteNumber(usage.input);
+  target.output += finiteNumber(usage.output);
+  target.cacheRead += finiteNumber(usage.cacheRead);
+  target.cacheWrite += finiteNumber(usage.cacheWrite);
+  target.totalTokens += finiteNumber(usage.totalTokens);
+  target.cost += usageCost(usage.cost);
+  target.assistantMessages += 1;
+}
+
+function nextDate(value: string): string {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return value;
+  const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]) + 1));
+  return date.toISOString().slice(0, 10);
+}
+
+function includeTimestamp(timestamp: unknown, range: UsageRange): boolean {
+  if (!range.from && !range.to) return true;
   if (typeof timestamp !== "string") return false;
   const value = Date.parse(timestamp);
   if (!Number.isFinite(value)) return false;
-  if (from && value < Date.parse(`${from}T00:00:00.000Z`)) return false;
-  if (to && value > Date.parse(`${to}T23:59:59.999Z`)) return false;
+  const timezoneOffset = range.timezoneOffset ?? "+08:00";
+  if (range.from && value < Date.parse(`${range.from}T00:00:00${timezoneOffset}`)) return false;
+  if (range.to && value >= Date.parse(`${nextDate(range.to)}T00:00:00${timezoneOffset}`)) return false;
   return true;
 }
 
@@ -48,17 +88,42 @@ async function jsonlFiles(root: string): Promise<string[]> {
       return entry.isFile() && entry.name.endsWith(".jsonl") ? [target] : [];
     }),
   );
-  return nested.flat();
+  return nested.flat().sort();
+}
+
+function sessionLabel(sessionRoot: string, file: string): string {
+  // A relative path is stable and never collapses unrelated UUID-named main
+  // sessions into one misleading "main" bucket.
+  return path.relative(sessionRoot, file).replace(/\.jsonl$/, "").split(path.sep).join("/");
+}
+
+function modelName(entry: Record<string, unknown>, current: string): string {
+  const candidate = entry.model;
+  if (typeof candidate === "string" && candidate) return candidate;
+  if (candidate && typeof candidate === "object") {
+    const value = (candidate as Record<string, unknown>).id;
+    if (typeof value === "string" && value) return value;
+  }
+  return current;
 }
 
-export async function aggregateUsage(
+export async function aggregateUsageReport(
   sessionRoot: string,
-  range: { from?: string; to?: string } = {},
-): Promise<UsageTotals> {
+  source: "project" | "omp" = "project",
+  range: UsageRange = {},
+): Promise<UsageReport> {
   const totals = emptyUsage();
+  const perModel: Record<string, UsageTotals> = {};
+  const perSession: Record<string, UsageTotals> = {};
   const files = await jsonlFiles(sessionRoot);
   totals.sessionFiles = files.length;
+
   for (const file of files) {
+    const session = sessionLabel(sessionRoot, file);
+    if (range.session && range.session !== "all" && range.session !== session) continue;
+    const sessionTotals = (perSession[session] ??= emptyUsage());
+    sessionTotals.sessionFiles = 1;
+    let currentModel = "unknown";
     const content = await readFile(file, "utf8").catch(() => "");
     for (const line of content.split("\n")) {
       if (!line.trim()) continue;
@@ -68,22 +133,49 @@ export async function aggregateUsage(
       } catch {
         continue;
       }
-      if (entry.type !== "message" || !includeTimestamp(entry.timestamp, range.from, range.to)) continue;
+      if (entry.type === "model_change") {
+        currentModel = modelName(entry, currentModel);
+        continue;
+      }
+      if (entry.type !== "message" || !includeTimestamp(entry.timestamp, range)) continue;
       const message = entry.message as Record<string, unknown> | undefined;
       if (message?.role !== "assistant") continue;
       const usage = message.usage as Record<string, unknown> | undefined;
       if (!usage) continue;
-      const cost = usage.cost as Record<string, unknown> | undefined;
-      totals.input += finiteNumber(usage.input);
-      totals.output += finiteNumber(usage.output);
-      totals.cacheRead += finiteNumber(usage.cacheRead);
-      totals.cacheWrite += finiteNumber(usage.cacheWrite);
-      totals.totalTokens += finiteNumber(usage.totalTokens);
-      totals.cost += finiteNumber(cost?.total);
-      totals.assistantMessages += 1;
+      const model = currentModel;
+      const modelTotals = (perModel[model] ??= emptyUsage());
+      addUsage(totals, usage);
+      addUsage(sessionTotals, usage);
+      addUsage(modelTotals, usage);
     }
   }
-  return totals;
+
+  return {
+    source,
+    sessionRoot,
+    filter: {
+      session: range.session ?? "all",
+      from: range.from,
+      to: range.to,
+      timezoneOffset: range.timezoneOffset ?? "+08:00",
+    },
+    totals,
+    perModel,
+    perSession,
+  };
+}
+
+export async function aggregateUsage(sessionRoot: string, range: UsageRange = {}): Promise<UsageTotals> {
+  return (await aggregateUsageReport(sessionRoot, "project", range)).totals;
+}
+
+function renderRows(title: string, rows: Record<string, UsageTotals>): string[] {
+  const entries = Object.entries(rows).sort(([, left], [, right]) => right.totalTokens - left.totalTokens || right.cost - left.cost);
+  if (entries.length === 0) return [`${title}: none`];
+  return [
+    `${title}:`,
+    ...entries.map(([name, totals]) => `  ${name} | ${totals.assistantMessages} requests | ${totals.totalTokens.toLocaleString("en-US")} tokens | $${totals.cost.toFixed(6)}`),
+  ];
 }
 
 export function renderUsage(totals: UsageTotals): string {
@@ -99,3 +191,15 @@ export function renderUsage(totals: UsageTotals): string {
     `cost: $${totals.cost.toFixed(6)}`,
   ].join("\n");
 }
+
+export function renderUsageReport(report: UsageReport): string {
+  const { totals, filter } = report;
+  return [
+    "Devflow usage stats",
+    `source: ${report.source} | session: ${filter.session} | ${filter.from ?? "all time"} → ${filter.to ?? "all time"} (${filter.timezoneOffset})`,
+    `sessions: ${totals.sessionFiles} | assistant requests: ${totals.assistantMessages} | tokens: ${totals.totalTokens.toLocaleString("en-US")} | cost: $${totals.cost.toFixed(6)}`,
+    ...renderRows("By model", report.perModel),
+    ...renderRows("By session", report.perSession),
+    "Note: token/cost totals use assistant message usage directly. Tool-call cost allocation is intentionally not estimated.",
+  ].join("\n");
+}