toolflow 3.1.4

package/src/json_extractor.ts

@@ -0,0 +1,57 @@
+import fs from "fs";
+
+/**
+ * 健壮提取大模型输出中的 JSON 对象：
+ * 1. 优先提取 Markdown 代码块 (```json ... ```)；
+ * 2. 次选基于平衡大括号算法 (Balanced Brace Counting) 提取首个最完整外层对象，
+ *    精准避开贪婪匹配跨多代码块导致的 SyntaxError 崩溃。
+ */
+export function extractValidJsonObject(raw: string): any {
+  if (!raw || typeof raw !== "string") {
+    throw new Error("Invalid raw text for JSON extraction");
+  }
+
+  // 1. 尝试匹配首个围栏 Markdown json 代码块
+  const codeBlockMatch = raw.match(/```(?:json)?\s*(\{[\s\S]*?\})\s*```/i);
+  if (codeBlockMatch) {
+    try {
+      return JSON.parse(codeBlockMatch[1].trim());
+    } catch (_) {}
+  }
+
+  // 2. 基于平衡括号扫描首个外层完整 JSON 对象
+  const firstBrace = raw.indexOf("{");
+  if (firstBrace === -1) throw new Error("No JSON object found in response");
+
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+
+  for (let i = firstBrace; i < raw.length; i++) {
+    const char = raw[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (char === "\\") {
+      escape = true;
+      continue;
+    }
+    if (char === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (!inString) {
+      if (char === "{") depth++;
+      else if (char === "}") {
+        depth--;
+        if (depth === 0) {
+          const candidate = raw.slice(firstBrace, i + 1);
+          return JSON.parse(candidate);
+        }
+      }
+    }
+  }
+
+  throw new Error("Unbalanced braces in LLM response");
+}

package/src/memory.ts

@@ -0,0 +1,151 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface ArchitecturalLesson {
+  id: string;
+  topic: string;
+  rule: string;
+  rationale: string;
+  tags: string[];
+  timestamp: number;
+}
+
+export interface CodebaseMemoryStore {
+  version: "1.0.0";
+  codebaseId: string;
+  updatedAt: number;
+  conventions: string[];
+  lessons: ArchitecturalLesson[];
+}
+
+const MAX_LESSONS = 15;
+
+export class CodebaseMemoryManager {
+  private memoryFilePath: string;
+  private workspaceRoot: string;
+
+  constructor(workspaceRoot: string = process.cwd()) {
+    this.workspaceRoot = workspaceRoot;
+    const memoryDir = path.join(workspaceRoot, ".pi", "toolflow", "memory");
+    try {
+      fs.mkdirSync(memoryDir, { recursive: true });
+    } catch (_) {}
+    this.memoryFilePath = path.join(memoryDir, "architecture_memory.json");
+  }
+
+  public loadMemory(): CodebaseMemoryStore {
+    if (fs.existsSync(this.memoryFilePath)) {
+      try {
+        const raw = fs.readFileSync(this.memoryFilePath, "utf-8");
+        const parsed = JSON.parse(raw) as CodebaseMemoryStore;
+        if (parsed && Array.isArray(parsed.lessons)) {
+          return parsed;
+        }
+      } catch (_) {}
+    }
+    return {
+      version: "1.0.0",
+      codebaseId: path.basename(this.workspaceRoot),
+      updatedAt: Date.now(),
+      conventions: [],
+      lessons: []
+    };
+  }
+
+  private safeWriteStore(store: CodebaseMemoryStore): void {
+    const tempPath = `${this.memoryFilePath}.tmp.${process.pid}.${Date.now()}`;
+    try {
+      const parentDir = path.dirname(this.memoryFilePath);
+      if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+      }
+      fs.writeFileSync(tempPath, JSON.stringify(store, null, 2), "utf-8");
+
+      let renamed = false;
+      for (let attempt = 0; attempt < 5; attempt++) {
+        try {
+          fs.renameSync(tempPath, this.memoryFilePath);
+          renamed = true;
+          break;
+        } catch (_) {
+          const start = Date.now();
+          while (Date.now() - start < 10) {}
+        }
+      }
+
+      if (!renamed) {
+        try {
+          fs.copyFileSync(tempPath, this.memoryFilePath);
+          renamed = true;
+        } catch (_) {}
+      }
+    } catch (_) {
+      try {
+        fs.writeFileSync(this.memoryFilePath, JSON.stringify(store, null, 2), "utf-8");
+      } catch (_) {}
+    } finally {
+      try {
+        if (fs.existsSync(tempPath)) {
+          fs.unlinkSync(tempPath);
+        }
+      } catch (_) {}
+    }
+  }
+
+  public recordLesson(topic: string, rule: string, rationale: string, tags: string[] = []): void {
+    const store = this.loadMemory();
+    const existingIndex = store.lessons.findIndex(l => l.topic === topic || l.rule === rule);
+    const newLesson: ArchitecturalLesson = {
+      id: "lesson_" + Date.now().toString(36),
+      topic,
+      rule,
+      rationale,
+      tags,
+      timestamp: Date.now()
+    };
+
+    if (existingIndex >= 0) {
+      store.lessons[existingIndex] = newLesson;
+    } else {
+      store.lessons.push(newLesson);
+    }
+
+    // 滑动窗口控制：严控在最新 MAX_LESSONS (15) 条以内，杜绝 Token 爆炸
+    if (store.lessons.length > MAX_LESSONS) {
+      store.lessons = store.lessons.slice(-MAX_LESSONS);
+    }
+
+    store.updatedAt = Date.now();
+    this.safeWriteStore(store);
+  }
+
+  public recordConvention(convention: string): void {
+    const store = this.loadMemory();
+    if (!store.conventions.includes(convention)) {
+      store.conventions.push(convention);
+      if (store.conventions.length > 10) {
+        store.conventions = store.conventions.slice(-10);
+      }
+      store.updatedAt = Date.now();
+      this.safeWriteStore(store);
+    }
+  }
+
+  public getPromptContextInjection(): string {
+    const store = this.loadMemory();
+    if (store.lessons.length === 0 && store.conventions.length === 0) {
+      return "";
+    }
+    const lines = ["\n[Codebase 历史架构与避坑记忆 (Memory Directives)]:"];
+    store.conventions.forEach(c => lines.push("- 仓库规范: " + c));
+    store.lessons.slice(-MAX_LESSONS).forEach(l => {
+      const truncatedRationale = l.rationale && l.rationale.length > 100 ? `${l.rationale.slice(0, 97)}...` : l.rationale;
+      lines.push("- " + l.topic + ": " + l.rule + " (" + truncatedRationale + ")");
+    });
+    let result = lines.join("\n");
+    if (result.length > 1500) {
+      result = result.slice(0, 1490) + "\n...";
+    }
+    return result;
+  }
+}

package/src/prompts_manager.ts

@@ -0,0 +1,262 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { extractValidJsonObject } from "./json_extractor.js";
+
+export interface PromptItemInfo {
+  command: string;
+  name: string;
+  description: string;
+  scope: "global" | "project" | "package";
+  category: "user" | "system"; // 分组：用户自定义（global/project） vs 系统内置（package）
+  filePath: string;
+  updatedAt: number; // 文件修改时间戳，用于将最新添加/修改的排在顶端
+  lastUsedAt?: number; // 最近使用时间戳（MRU）
+}
+
+export class PromptsManager {
+  public static scanAllPrompts(cwd: string = process.cwd()): PromptItemInfo[] {
+    const results: PromptItemInfo[] = [];
+    const seen = new Set<string>();
+
+    const checkDir = (dir: string, scope: "global" | "project" | "package") => {
+      if (!fs.existsSync(dir)) return;
+      try {
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+          if (file.endsWith(".md")) {
+            const name = file.replace(/.md$/, "");
+            const command = "/" + name;
+            if (seen.has(command)) continue;
+            seen.add(command);
+
+            const filePath = path.join(dir, file);
+            let description = "";
+            try {
+              const content = fs.readFileSync(filePath, "utf8");
+              const parts = content.split("description:");
+              if (parts.length > 1) {
+                description = parts[1].split("\n")[0].trim();
+              }
+            } catch (_) {}
+
+            let updatedAt = 0;
+            try {
+              updatedAt = fs.statSync(filePath).mtimeMs;
+            } catch (_) {}
+
+            const category: "user" | "system" = scope === "package" ? "system" : "user";
+
+            results.push({
+              command,
+              name,
+              description: description || "自定义提示词模板 [" + command + "]",
+              scope,
+              category,
+              filePath,
+              updatedAt
+            });
+          }
+        }
+      } catch (_) {}
+    };
+
+    const projectDir = path.join(cwd, ".pi", "prompts");
+    checkDir(projectDir, "project");
+
+    const piAgentBase = process.env.PI_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+    const globalDir = path.join(piAgentBase, "prompts");
+    checkDir(globalDir, "global");
+
+    const pkgDir = path.join(piAgentBase, "npm", "node_modules");
+    if (fs.existsSync(pkgDir)) {
+      try {
+        const scanPkgs = (base: string, depth = 0) => {
+          if (depth > 2) return;
+          const items = fs.readdirSync(base);
+          for (const item of items) {
+            const full = path.join(base, item);
+            if (item === "prompts") {
+              checkDir(full, "package");
+            } else if (fs.statSync(full).isDirectory() && !item.startsWith(".")) {
+              scanPkgs(full, depth + 1);
+            }
+          }
+        };
+        scanPkgs(pkgDir);
+      } catch (_) {}
+    }
+
+    // 读取最近使用时间戳（MRU）
+    const mruMap = this.loadMruMap();
+    for (const item of results) {
+      if (mruMap[item.command]) {
+        item.lastUsedAt = mruMap[item.command];
+      }
+    }
+
+    // 默认按照最后修改时间排序
+    results.sort((a, b) => b.updatedAt - a.updatedAt);
+    return results;
+  }
+
+  private static getMruFilePath(): string {
+    const piAgentBase = process.env.PI_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+    return path.join(piAgentBase, "toolflow_prompts_mru.json");
+  }
+
+  private static loadMruMap(): Record<string, number> {
+    const file = this.getMruFilePath();
+    if (!fs.existsSync(file)) return {};
+    try {
+      return JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch (_) {
+      return {};
+    }
+  }
+
+  /**
+   * 记录提示词被调用/选中，更新 MRU 时间戳
+   */
+  public static recordPromptUsage(command: string): void {
+    const mruMap = this.loadMruMap();
+    mruMap[command] = Date.now();
+    try {
+      const file = this.getMruFilePath();
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(mruMap, null, 2), "utf8");
+    } catch (_) {}
+  }
+
+  /**
+   * 获取最近使用的提示词列表（Top N），若无使用记录则回退为按最新添加时间排序
+   */
+  public static getRecentPrompts(prompts: PromptItemInfo[], limit: number = 5): PromptItemInfo[] {
+    const mruMap = this.loadMruMap();
+    const withUsage = prompts.filter(p => mruMap[p.command] !== undefined);
+    if (withUsage.length > 0) {
+      withUsage.sort((a, b) => (mruMap[b.command] || 0) - (mruMap[a.command] || 0));
+      return withUsage.slice(0, limit);
+    }
+    // 回退展示按更新时间排序的前 N 个
+    return [...prompts].sort((a, b) => b.updatedAt - a.updatedAt).slice(0, limit);
+  }
+
+  /**
+   * 提取指定提示词文件的正文前 N 行用于即时预览（自动剥离 frontmatter 头部）
+   */
+  public static getPromptPreviewLines(item: PromptItemInfo, maxLines: number = 3): string[] {
+    const body = this.getPromptContent(item);
+    if (!body) return [];
+    return body
+      .split(/\r?\n/)
+      .map(l => l.trim())
+      .filter(l => l.length > 0)
+      .slice(0, maxLines);
+  }
+
+  public static createPrompt(name: string, description: string, content: string, scope: "global" | "project" = "global", cwd: string = process.cwd()): PromptItemInfo {
+    const cleanName = name.replace(/^\/+/, "").trim();
+    const piAgentBase = process.env.PI_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+    const targetDir = scope === "project"
+      ? path.join(cwd, ".pi", "prompts")
+      : path.join(piAgentBase, "prompts");
+
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+
+    const filePath = path.join(targetDir, cleanName + ".md");
+    const fileBody = [
+      "---",
+      "description: " + description.trim(),
+      "---",
+      "",
+      content.trim(),
+      ""
+    ].join("\n");
+
+    fs.writeFileSync(filePath, fileBody, "utf8");
+
+    return {
+      command: "/" + cleanName,
+      name: cleanName,
+      description: description.trim(),
+      scope,
+      category: "user",
+      filePath,
+      updatedAt: Date.now()
+    };
+  }
+
+  public static getPromptContent(item: PromptItemInfo): string {
+    if (!item.filePath || !fs.existsSync(item.filePath)) {
+      return "";
+    }
+    try {
+      const raw = fs.readFileSync(item.filePath, "utf8");
+      if (raw.startsWith("---")) {
+        const parts = raw.split("---");
+        if (parts.length >= 3) {
+          return parts.slice(2).join("---").trim();
+        }
+      }
+      return raw.trim();
+    } catch (_) {
+      return "";
+    }
+  }
+
+  public static deletePrompt(item: PromptItemInfo): boolean {
+    if (!item.filePath || !fs.existsSync(item.filePath)) {
+      return false;
+    }
+    try {
+      fs.unlinkSync(item.filePath);
+      return true;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  public static async autoSummarizeTagWithLLM(content: string, ctx?: any): Promise<{ name: string; description: string }> {
+    const fallbackName = "my-prompt";
+    const fallbackDesc = content.slice(0, 30).replace(/\r?\n/g, " ");
+
+    if (!ctx || !(ctx as any).modelRegistry || !(ctx as any).model) {
+      return { name: fallbackName, description: fallbackDesc };
+    }
+
+    try {
+      const mr = (ctx as any).modelRegistry;
+      const model = (ctx as any).model;
+      const prompt = `请为以下这段用于 AI 编程的 Prompt 模版生成一个极简短的命令名称和一个精练的中文说明。
+
+[PROMPT 内容]:
+${content.slice(0, 1500)}
+
+严格按 JSON 输出:
+{
+  "name": "极简英文命令名（如 wechat-test, code-review, rust-api 等，纯小写字母与连字符）",
+  "description": "一句话大白话精炼说明（20字以内，讲清楚它的作用）"
+}`;
+
+      const resp = await mr.complete(model, {
+        messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
+        options: { temperature: 0.2 }
+      });
+
+      const raw = resp.content?.[0]?.type === "text" ? resp.content[0].text : "";
+      // 稳健提取 JSON 块，剥离 Markdown 围栏并支持平衡括号防崩溃
+      const parsed = extractValidJsonObject(raw);
+
+      return {
+        name: (parsed.name || fallbackName).replace(/[^a-zA-Z0-9_-]/g, "").toLowerCase(),
+        description: parsed.description || fallbackDesc
+      };
+    } catch (_) {
+      return { name: fallbackName, description: fallbackDesc };
+    }
+  }
+
+}

package/src/review_isolation.ts

@@ -0,0 +1,188 @@
+import { execSync } from "child_process";
+import * as path from "path";
+import { BlueprintStage } from "./types.js";
+
+export interface ReviewSnapshot {
+  baseSha?: string;
+  headSha?: string;
+  diffSummary: string;
+  detailedDiff: string;
+  changedFiles: string[];
+  hasChanges?: boolean;
+}
+
+export interface ReviewIsolationResult {
+  isIsolated: boolean;
+  isolationMode: "fresh_subagent" | "context_stripped_turn";
+  snapshot: ReviewSnapshot;
+  isolatedSystemPrompt: string;
+  isolatedUserPrompt: string;
+}
+
+/**
+ * 捕获当前 Git 仓库的物理变更 Diff 快照
+ */
+export function captureReviewDiffSnapshot(cwd: string = process.cwd()): ReviewSnapshot {
+  try {
+    // 检查是否在 git 仓库中
+    const isGit = execSync("git rev-parse --is-inside-work-tree", {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "ignore"],
+      timeout: 2000
+    }).trim() === "true";
+
+    if (!isGit) {
+      return {
+        diffSummary: "Non-git directory: unable to extract git diff.",
+        detailedDiff: "",
+        changedFiles: []
+      };
+    }
+
+    let headSha = "";
+    try {
+      headSha = execSync("git rev-parse HEAD", {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "ignore"],
+        timeout: 2000
+      }).trim();
+    } catch {
+      // 新仓库可能尚无 HEAD
+      headSha = "INITIAL_UNCOMMITTED";
+    }
+
+    // 获取变更文件清单 (staged + unstaged + untracked)
+    const statusOut = execSync("git status --porcelain", {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "ignore"],
+      timeout: 3000
+    }).trim();
+
+    const changedFiles: string[] = [];
+    if (statusOut) {
+      const lines = statusOut.split("\n");
+      for (const line of lines) {
+        const filePart = line.substring(3).trim();
+        if (filePart) changedFiles.push(filePart);
+      }
+    }
+
+    // 获取详细 diff
+    let detailedDiff = "";
+    try {
+      detailedDiff = execSync("git diff HEAD", {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "ignore"],
+        timeout: 5000
+      });
+      if (!detailedDiff.trim()) {
+        // 如果没有与 HEAD 的 diff，尝试抓取未暂存 diff
+        detailedDiff = execSync("git diff", {
+          cwd,
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "ignore"],
+          timeout: 5000
+        });
+      }
+    } catch {
+      detailedDiff = statusOut;
+    }
+
+    // 限制 diff 尺寸以防膨胀
+    if (detailedDiff.length > 8000) {
+      detailedDiff = detailedDiff.substring(0, 8000) + "\n... [Diff truncated to 8000 chars for context hygiene]";
+    }
+
+    const summary = `${changedFiles.length} file(s) changed: ${changedFiles.slice(0, 5).join(", ")}${changedFiles.length > 5 ? "..." : ""}`;
+
+    return {
+      headSha,
+      diffSummary: summary,
+      detailedDiff,
+      changedFiles,
+      hasChanges: changedFiles.length > 0
+    };
+  } catch (err: any) {
+    return {
+      diffSummary: `Failed to inspect git diff: ${err?.message || String(err)}`,
+      detailedDiff: "",
+      changedFiles: [],
+      hasChanges: false
+    };
+  }
+}
+
+/**
+ * 构建针对 Reviewer 智能体的冷启动隔离上下文与脱水提示词契约。
+ * 杜绝承袭 Implementer 的历史推理心智，以客观物理视角审视 Diff 与验收标准。
+ */
+export function buildColdStartReviewContract(
+  stage: BlueprintStage,
+  stageIndex: number,
+  totalStages: number,
+  snapshot: ReviewSnapshot
+): ReviewIsolationResult {
+  const isolatedSystemPrompt = [
+    "=== ZERO-MEMORY INDEPENDENT CODE AUDITOR ===",
+    "ROLE: You are an independent, objective software auditor and QA reviewer.",
+    "ISOLATION STATUS: Cold start enabled. You have NO prior implementation context or bias.",
+    "OBJECTIVE: Objectively verify the git changes against the expected artifacts and quality gates.",
+    "GUIDELINES:",
+    "1. Base your verdict strictly on actual physical file diffs and command verifications, NOT developer promises.",
+    "2. Check for syntax correctness, edge case security, blast radius violations, and test assertions.",
+    "3. Be adversarial yet fair. Report concrete bugs or approve if all quality gates pass.",
+    "ALLOWED OPERATIONS: Read, inspect files, execute verification commands (bash/powershell)."
+  ].join("\n");
+
+  const gateCommands = stage.verificationCommands && stage.verificationCommands.length > 0
+    ? `\nVerification Gate: ${stage.verificationCommands.join(" && ")}`
+    : "";
+
+  const isolatedUserPrompt = [
+    `[Stage ${stageIndex + 1}/${totalStages}: ${stage.title} (Independent Review)]`,
+    `Review Target: ${stage.expectedArtifact}`,
+    `Core Objective: ${stage.coreObjective}${gateCommands}`,
+    `Changes Under Review:\n${snapshot.diffSummary}`,
+    snapshot.detailedDiff ? `\n--- DIFF AUDIT PAYLOAD ---\n${snapshot.detailedDiff}\n--- END DIFF ---` : "",
+    `\nInstruction: Perform cold-start audit on these changes. Validate correctness and artifact integrity.`
+  ].join("\n");
+
+  return {
+    isIsolated: true,
+    isolationMode: "fresh_subagent",
+    snapshot,
+    isolatedSystemPrompt,
+    isolatedUserPrompt
+  };
+}
+
+/**
+ * 审查阶段运行时工具防线 (Review Isolation Guard)
+ * 物理阻断任何修改代码的动作 (write, edit 等)，强制要求审核员保持“只读/只验证”客观状态。
+ */
+export class ReviewIsolationGuard {
+  private active: boolean = false;
+  private allowedAuditTools = new Set(["read", "bash", "powershell", "grep", "find", "goal_complete", "goal_blocked", "goal_wait", "mcp"]);
+
+  public activate(): void {
+    this.active = true;
+  }
+
+  public deactivate(): void {
+    this.active = false;
+  }
+
+  public isActive(): boolean {
+    return this.active;
+  }
+
+  public isToolAllowedInReview(toolName: string): boolean {
+    if (!this.active) return true;
+    return this.allowedAuditTools.has(toolName);
+  }
+}
+