@roarpeng/graphflow 1.0.9 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roarpeng/graphflow",
-  "version": "1.0.9",
+  "version": "1.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -9,6 +9,7 @@
     "wasm",
     "scripts/safe-postinstall.cjs",
     "src/surfaces/trae-skill",
+    "src/surfaces/cursor-rules",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
@@ -71,7 +72,7 @@
     "@types/node": "^25.9.1",
     "@typescript-eslint/eslint-plugin": "^8.60.0",
     "@typescript-eslint/parser": "^8.60.0",
-    "@vitest/coverage-v8": "^4.1.8",
+    "@vitest/coverage-v8": "^3.2.6",
     "eslint": "^10.4.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
@@ -79,7 +80,7 @@
     "tree-sitter-wasms": "0.1.11",
     "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^3.2.6"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/scripts/safe-postinstall.cjs

@@ -1,11 +1,56 @@
 #!/usr/bin/env node
-const { existsSync, mkdirSync, copyFileSync, readFileSync } = require("node:fs");
+const { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, unlinkSync } = require("node:fs");
 const { join } = require("node:path");
 const { homedir } = require("node:os");
 const { spawnSync } = require("node:child_process");
 
 const isWindows = process.platform === "win32";
 
+// ─── 版本比较与自动更新 ───
+
+/** 版本标记文件路径：记录上次安装的 GraphFlow 版本号 */
+const VERSION_FILE = join(homedir(), ".graphflow-install-version");
+
+/**
+ * 读取上次安装时记录的版本号
+ * @returns {string | null} 上次版本号，不存在则返回 null
+ */
+function readPreviousVersion() {
+  try {
+    if (existsSync(VERSION_FILE)) {
+      return readFileSync(VERSION_FILE, "utf8").trim();
+    }
+  } catch {
+    // 忽略读取失败
+  }
+  return null;
+}
+
+/**
+ * 将当前版本号写入标记文件
+ * @param {string} version 当前版本号
+ */
+function writeCurrentVersion(version) {
+  try {
+    writeFileSync(VERSION_FILE, version, "utf8");
+  } catch {
+    // 忽略写入失败
+  }
+}
+
+/**
+ * 比较版本号，判断是否需要强制更新 Skill/Rules/MCP 文件
+ * @param {string} currentVersion 当前安装的版本号
+ * @returns {boolean} 是否需要强制更新
+ */
+function needsForceUpdate(currentVersion) {
+  const previousVersion = readPreviousVersion();
+  if (!previousVersion) {
+    return true; // 首次安装或无版本记录，强制更新
+  }
+  return previousVersion !== currentVersion;
+}
+
 function resolveHomePaths() {
   const home = homedir();
   const appData = process.env.APPDATA || (isWindows ? join(home, "AppData", "Roaming") : "");
@@ -147,6 +192,231 @@ function isGlobalInstall() {
   return false;
 }
 
+/**
+ * 获取 Cursor Rules 源文件路径（graphflow.mdc）
+ * 优先从 dist 目录查找，回退到 src 目录。
+ * @returns {string | null} 源文件路径，不存在则返回 null
+ */
+function getCursorRulesSourceFile() {
+  const candidates = [
+    join(__dirname, "..", "dist", "surfaces", "cursor-rules", "graphflow.mdc"),
+    join(__dirname, "..", "src", "surfaces", "cursor-rules", "graphflow.mdc"),
+  ];
+  for (const filePath of candidates) {
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+
+/**
+ * 获取 CLAUDE.md 源文件路径
+ * 优先从包根目录查找。
+ * @returns {string | null} 源文件路径，不存在则返回 null
+ */
+function getClaudeMdSourceFile() {
+  const candidates = [
+    join(__dirname, "..", "CLAUDE.md"),
+  ];
+  for (const filePath of candidates) {
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+
+/**
+ * 获取 Cursor rules 目录列表。
+ * Cursor 的 rules 目录为 ~/.cursor/rules/（跨平台一致），
+ * 也有用户使用 %APPDATA%/Cursor/User/rules/。
+ * @returns {Array<{name: string, rulesDir: string}>} Cursor rules 目录列表
+ */
+function getCursorRulesDirs() {
+  const { home, appData } = resolveHomePaths();
+  const dirs = [];
+
+  // ~/.cursor/rules — Cursor 的标准 rules 目录
+  if (existsSync(join(home, ".cursor"))) {
+    dirs.push({
+      name: "Cursor (~/.cursor)",
+      rulesDir: join(home, ".cursor", "rules"),
+    });
+  }
+
+  // %APPDATA%/Cursor/User/rules — Windows 上的备选目录
+  if (isWindows && existsSync(join(appData, "Cursor", "User"))) {
+    dirs.push({
+      name: "Cursor (AppData)",
+      rulesDir: join(appData, "Cursor", "User", "rules"),
+    });
+  }
+
+  return dirs;
+}
+
+/**
+ * 通用文件安装逻辑：检测 marker → 创建目标目录 → 复制文件 → 已存在且内容相同则跳过
+ * @param {string} sourceFile 源文件路径
+ * @param {string} destDir 目标目录
+ * @param {string} destFileName 目标文件名
+ * @returns {{status: string, reason?: string}} 安装结果
+ */
+function installFileToDir(sourceFile, destDir, destFileName) {
+  if (!existsSync(sourceFile)) {
+    return { status: "skipped", reason: "源文件不存在" };
+  }
+
+  const destFile = join(destDir, destFileName);
+  const existed = existsSync(destFile);
+
+  if (existed) {
+    const existingContent = readFileSync(destFile, "utf8");
+    const newContent = readFileSync(sourceFile, "utf8");
+    if (existingContent === newContent) {
+      return { status: "skipped", reason: "已是最新" };
+    }
+  }
+
+  mkdirSync(destDir, { recursive: true });
+  copyFileSync(sourceFile, destFile);
+
+  return { status: existed ? "updated" : "created" };
+}
+
+/**
+ * 检测并安装 Cursor Rules（graphflow.mdc）到 Cursor rules 目录
+ * @returns {{status: string, reason?: string} | null} 安装结果，无需安装则返回 null
+ */
+function installCursorRules() {
+  const sourceFile = getCursorRulesSourceFile();
+  if (!sourceFile) {
+    return { status: "skipped", reason: "Cursor Rules 源文件不存在" };
+  }
+
+  const dirs = getCursorRulesDirs();
+  if (dirs.length === 0) {
+    return null; // 未检测到 Cursor，跳过
+  }
+
+  // 只需要安装到第一个有效目录
+  const target = dirs[0];
+  return installFileToDir(sourceFile, target.rulesDir, "graphflow.mdc");
+}
+
+/**
+ * 检测并安装 CLAUDE.md 到 ~/.claude/CLAUDE.md（Claude Code 约定）
+ * @returns {{status: string, reason?: string} | null} 安装结果，无需安装则返回 null
+ */
+function installClaudeMd() {
+  const sourceFile = getClaudeMdSourceFile();
+  if (!sourceFile) {
+    return { status: "skipped", reason: "CLAUDE.md 源文件不存在" };
+  }
+
+  const { home } = resolveHomePaths();
+  const claudeDir = join(home, ".claude");
+
+  // 检测 ~/.claude 是否存在（Claude Code 的 marker 目录）
+  if (!existsSync(claudeDir)) {
+    return null; // 未检测到 Claude Code，跳过
+  }
+
+  return installFileToDir(sourceFile, claudeDir, "CLAUDE.md");
+}
+
+/**
+ * 注入 workspace 级 MCP 配置到已存在的 workspace MCP 文件。
+ * 仅在检测到 .cursor/mcp.json 或 .vscode/mcp.json 时生效（更安全，只在当前项目内）。
+ * @param {string} workspaceRoot 当前项目根目录
+ * @returns {Array<{configPath: string, status: string}>} 注入结果列表
+ */
+function installWorkspaceLevelMcp(workspaceRoot) {
+  const results = [];
+  const configFiles = [
+    { path: join(workspaceRoot, ".cursor", "mcp.json"), name: "Cursor", key: "mcpServers" },
+    { path: join(workspaceRoot, ".vscode", "mcp.json"), name: "VS Code", key: "servers" },
+  ];
+
+  const mcpEntry = {
+    command: "npx",
+    args: ["-y", "--package=@roarpeng/graphflow", "graphflow-mcp"],
+    env: { GRAPHFLOW_MCP_STDIO: "1", GRAPHFLOW_LOG_JSON: "1" },
+  };
+
+  for (const config of configFiles) {
+    if (!existsSync(config.path)) {
+      continue; // 该 workspace 级配置不存在，跳过
+    }
+
+    try {
+      let json = {};
+      try {
+        json = JSON.parse(readFileSync(config.path, "utf8"));
+      } catch {
+        // 配置文件为空或损坏，初始化为空对象
+      }
+
+      const servers = json[config.key] || {};
+      if (servers.graphflow) {
+        results.push({ configPath: config.path, status: "skipped", name: config.name, reason: "already configured" });
+        continue;
+      }
+
+      servers.graphflow = mcpEntry;
+      json[config.key] = servers;
+      writeFileSync(config.path, JSON.stringify(json, null, 2) + "\n", "utf8");
+      results.push({ configPath: config.path, status: "created", name: config.name });
+      console.log(`[GraphFlow] Workspace 级 MCP 已注入到 ${config.path} (${config.name})`);
+    } catch (err) {
+      results.push({ configPath: config.path, status: "error", name: config.name, reason: err.message });
+      console.log(`[GraphFlow] Workspace 级 MCP 注入失败 ${config.path}: ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * 在 workspace 级创建 .graphflow/skills/ 目录并复制 Skill 文件。
+ * 仅在检测到 .cursor/mcp.json 或 .vscode/mcp.json 时生效。
+ * @param {string} workspaceRoot 当前项目根目录
+ */
+function installWorkspaceLevelSkills(workspaceRoot) {
+  const configFiles = [
+    join(workspaceRoot, ".cursor", "mcp.json"),
+    join(workspaceRoot, ".vscode", "mcp.json"),
+  ];
+  const hasWorkspaceConfig = configFiles.some((p) => existsSync(p));
+
+  if (!hasWorkspaceConfig) {
+    return; // 无 workspace 级 MCP 配置，跳过 Skill 安装
+  }
+
+  const skillSourceDir = getSkillSourceDir();
+  if (!skillSourceDir) {
+    return;
+  }
+
+  // 在 .graphflow/skills/graphflow/ 下创建 workspace 级 Skill
+  const skillDestDir = join(workspaceRoot, ".graphflow", "skills", "graphflow");
+  const result = installSkill(skillDestDir, skillSourceDir);
+  if (result.status !== "skipped") {
+    console.log(`[GraphFlow] Workspace 级 Skill: ${result.status}${result.reason ? ` (${result.reason})` : ""} -> ${skillDestDir}`);
+  }
+
+  // 同时安装 Cursor Rules 到 workspace 级 .cursor/rules/
+  const cursorRulesSource = getCursorRulesSourceFile();
+  if (cursorRulesSource && existsSync(join(workspaceRoot, ".cursor"))) {
+    const cursorRulesDir = join(workspaceRoot, ".cursor", "rules");
+    const rulesResult = installFileToDir(cursorRulesSource, cursorRulesDir, "graphflow.mdc");
+    if (rulesResult.status !== "skipped") {
+      console.log(`[GraphFlow] Workspace 级 Cursor Rules: ${rulesResult.status}${rulesResult.reason ? ` (${rulesResult.reason})` : ""}`);
+    }
+  }
+}
+
 function main() {
   if (process.env.GRAPHFLOW_SKIP_POSTINSTALL === "1" || process.env.CI === "true") {
     process.exit(0);
@@ -156,13 +426,44 @@ function main() {
   const explicitlyEnabled = process.env.GRAPHFLOW_ENABLE_POSTINSTALL === "1";
 
   if (!globalInstall && !explicitlyEnabled) {
-    console.log("[GraphFlow] Local install detected. Auto-setup skipped to avoid modifying your global config.");
-    console.log("[GraphFlow] To install GraphFlow MCP + Skill, run:");
-    console.log("[GraphFlow]   npx @roarpeng/graphflow install");
+    // 本地安装：检测 workspace 级 MCP 配置，若有则自动注入 workspace 级 MCP + Skill
+    const workspaceRoot = process.cwd();
+    const workspaceMcpResults = installWorkspaceLevelMcp(workspaceRoot);
+    const hasWorkspaceConfig = workspaceMcpResults.some((r) => r.status === "created" || r.status === "skipped");
+
+    if (hasWorkspaceConfig) {
+      console.log("[GraphFlow] 检测到 workspace 级 MCP 配置，已自动注入 workspace 级 GraphFlow MCP。");
+      installWorkspaceLevelSkills(workspaceRoot);
+      console.log("[GraphFlow] 如需完整安装（用户级 MCP + Trae Skill），运行:");
+      console.log("[GraphFlow]   npx @roarpeng/graphflow install");
+    } else {
+      console.log("[GraphFlow] Local install detected. Auto-setup skipped to avoid modifying your global config.");
+      console.log("[GraphFlow] To install GraphFlow MCP + Skill, run:");
+      console.log("[GraphFlow]   npx @roarpeng/graphflow install");
+    }
     process.exit(0);
   }
 
+  // 读取当前版本号，用于版本比较和强制更新
+  let currentVersion = "unknown";
+  try {
+    const pkg = require("../package.json");
+    currentVersion = pkg.version || "unknown";
+  } catch {
+    // npm 包中 package.json 在上层目录；如果读取失败则跳过版本比较
+  }
+
+  const forceUpdate = needsForceUpdate(currentVersion);
+  const previousVersion = readPreviousVersion();
+
   console.log(`[GraphFlow] Running post-install setup (${globalInstall ? "global install" : "explicitly enabled"})...`);
+  console.log(`[GraphFlow] 版本: ${currentVersion}`);
+
+  if (forceUpdate && previousVersion) {
+    console.log(`[GraphFlow] 检测到版本变化 (${previousVersion} → ${currentVersion})，将强制更新所有 Skill/Rules/MCP 文件`);
+  } else if (forceUpdate && !previousVersion) {
+    console.log("[GraphFlow] 首次安装，将安装所有 Skill/Rules/MCP 文件");
+  }
 
   const skillSourceDir = getSkillSourceDir();
   const traeDirs = getTraeUserDirs();
@@ -185,6 +486,23 @@ function main() {
     console.log(`[GraphFlow] MCP install skipped: ${mcpResult.reason}`);
   }
 
+  // ─── Cursor Rules 安装 ───
+  const cursorRulesResult = installCursorRules();
+  if (cursorRulesResult) {
+    console.log(`[GraphFlow] Cursor Rules: ${cursorRulesResult.status}${cursorRulesResult.reason ? ` (${cursorRulesResult.reason})` : ""}`);
+  }
+
+  // ─── Claude Code 约定安装 ───
+  const claudeMdResult = installClaudeMd();
+  if (claudeMdResult) {
+    console.log(`[GraphFlow] Claude Code 约定: ${claudeMdResult.status}${claudeMdResult.reason ? ` (${claudeMdResult.reason})` : ""}`);
+  }
+
+  // 写入当前版本号标记文件
+  if (currentVersion !== "unknown") {
+    writeCurrentVersion(currentVersion);
+  }
+
   console.log("[GraphFlow] Post-install complete.");
 }
 
@@ -192,4 +510,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { installSkill, detectTrae, getTraeUserDirs, getSkillSourceDir };
+module.exports = { installSkill, detectTrae, getTraeUserDirs, getSkillSourceDir, readPreviousVersion, writeCurrentVersion, needsForceUpdate, VERSION_FILE };

package/src/surfaces/cursor-rules/graphflow.mdc

@@ -0,0 +1,131 @@
+---
+description: Use GraphFlow first for token-efficient repo context, planning, and orchestration.
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+# GraphFlow Token-First Rule
+
+GraphFlow is a graph-based context and planning service backed by a persistent MCP server. It turns codebases into queryable knowledge graphs, delivering token-efficient compressed context, task planning, and orchestration.
+
+Before broad code exploration, implementation, debugging, review, planning, or architecture questions:
+
+1. Call `graphflow_preview_context` with the user's task/query.
+2. Use the returned `summary`, `anchors`, `refillPreview`, and `tokenBudget` as the first context source.
+3. Read full files only when:
+   - GraphFlow anchors point to that file/symbol,
+   - the compressed context is insufficient,
+   - or exact edits require the file body.
+4. For multi-step or ambiguous work, call `graphflow_plan` before implementation.
+5. For graph freshness after project changes, call `graphflow_index`.
+6. Report token budget when available:
+   - estimated raw tokens,
+   - compressed tokens,
+   - estimated savings percent,
+   - max context token budget.
+
+Do not scan the whole repository, recursively inspect many files, or read large files before trying GraphFlow context.
+
+## Tool Inventory (18 MCP Tools)
+
+### Core Context Tools (Highest Frequency)
+
+| Tool | Purpose | Call Frequency |
+|------|---------|---------------|
+| `graphflow_preview_context` | Compress task context with token budget | **Highest** - default first step |
+| `graphflow_expand_anchor` | Expand a single anchor to full content | **High** - dive deeper into specific items |
+
+### Planning Tools (High Frequency)
+
+| Tool | Purpose | Call Frequency |
+|------|---------|---------------|
+| `graphflow_plan` | Multi-step task decomposition & DAG | High - before complex work |
+| `graphflow_plan_insight` | Six Thinking Hats + 5-Why deep analysis | Medium - ambiguous/high-stakes tasks |
+| `graphflow_run` | Plan + context package (bridge mode) | Medium - full task packaging |
+| `graphflow_report_outcome` | Report bridge-mode execution outcome back | Medium - close the learning loop |
+
+### Graph Management Tools (Medium Frequency)
+
+| Tool | Purpose | Call Frequency |
+|------|---------|---------------|
+| `graphflow_index` | Incremental workspace re-index | Medium - after file changes |
+| `graphflow_index_file` | Single file incremental index | Medium-High - after saving a file |
+| `graphflow_rebuild` | Clear cache + full re-index | Low - when graph is stale/corrupted |
+| `graphflow_inspect_graph` | Graph stats & sample nodes/edges | Low - check graph health |
+| `graphflow_enrich_graph` | Semantic enrichment of symbols | Rare - LLM-powered enrichment |
+| `graphflow_model_download` | Download local compression model | Rare - offline setup |
+
+### Collaboration & Insights Tools (Low Frequency)
+
+| Tool | Purpose | Call Frequency |
+|------|---------|---------------|
+| `graphflow_export_artifact` | Export graph to portable artifact | Low - team sharing |
+| `graphflow_import_artifact` | Import graph artifact | Low - skip full index on new machine |
+| `graphflow_skill_insights` | Learned skill patterns | Low - leverage prior learning |
+| `graphflow_stats` | Cumulative token savings stats | Low - ROI tracking |
+| `graphflow_metrics` | Prometheus-compatible metrics | Low - observability |
+| `graphflow_diagnose` | Provider health & model routing | Rare - config issues |
+
+## Standard Workflows
+
+### Workflow 1: Context First (90% of tasks)
+
+**Use when:** Answering code questions, exploring codebase, understanding modules
+
+```
+Step 1: graphflow_preview_context(query: "<your question>")
+Step 2: Read summary + anchors as primary context
+Step 3: Expand specific anchors with graphflow_expand_anchor when needed
+Step 4: Read full files only when exact edits required
+```
+
+### Workflow 2: Plan Before Coding (complex tasks)
+
+**Use when:** Multi-step changes, refactors, features with unclear scope
+
+```
+Step 1: graphflow_preview_context(query: "<task>")
+Step 2: graphflow_plan(task: "<task description>")
+Step 3: Review plan steps and dependencies
+Step 4: Execute step by step, using GraphFlow context for each step
+Step 5: graphflow_index() after major changes
+```
+
+### Workflow 3: Deep Analysis (complex/ambiguous tasks)
+
+**Use when:** High-stakes changes, root-cause analysis, ambiguous requirements
+
+```
+Step 1: graphflow_preview_context(query: "<task>")
+Step 2: graphflow_plan_insight(task: "<task>")
+Step 3: Review analysis and apply findings
+```
+
+## Bridge-mode outcome reporting
+
+After `graphflow_run`, the external agent **must** call `graphflow_report_outcome` to close the skill flywheel loop:
+
+- Pass `episodeId` from the run result, a `success` boolean, and optional `lessons`.
+- Do this after executing the work described in the returned `executionDescriptor`, whether the task succeeded or failed.
+- When the run returns `agentWorkItems`, answer each prompt with your model and call `graphflow_submit_insight` once per item (before or with `graphflow_report_outcome`).
+
+CLI fallback:
+
+```bash
+graphflow --json outcome report <episodeId> <success>
+```
+
+If MCP is unavailable, use the CLI fallback and always request JSON output:
+
+```bash
+graphflow --json context preview "<query>"
+graphflow --json plan "<task>"
+graphflow --json graph inspect
+graphflow --json skill insights
+graphflow --json route diagnose
+```
+
+Treat GraphFlow outputs as structured machine-readable data, not prose.
+
+When the user asks about saving token usage, optimizing context, repo understanding, or learning from Graphify, prioritize GraphFlow context compression over ordinary file search.