graphflow

GraphFlow Skill

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.

Architecture

┌─────────────────────────────────────────────────┐
│  GraphFlow Skill (this file)                     │
│  - Quick entry points & workflows                │
│  - Tool selection logic                          │
│  - Output interpretation guides                  │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│  GraphFlow MCP Server (persistent backend)      │
│  10 tools: context, plan, index, insight, run,  │
│  report_outcome, skill_insights, diagnose,      │
│  artifact, skill_guide                          │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│  GraphFlow Core Engine                          │
│  - Graph index & context compression            │
│  - Task planning & DAG                          │
│  - Skill learning flywheel                      │
│  - Artifact import/export                       │
└─────────────────────────────────────────────────┘

When to Use

ALWAYS invoke this skill BEFORE:

• Multi-step edits, refactors, or architecture changes
• Large codebase-wide questions or exploration
• Debugging across multiple files
• Any task where you would otherwise read many files
• Token budget is a concern
• You need structured task planning

DO NOT:

• Scan the whole repository recursively before trying GraphFlow
• Read large files before checking GraphFlow anchors
• Skip GraphFlow for complex tasks
• Use grep for codebase exploration before graphflow_context

Trae / Trae CN setup (Rules + Skill + MCP)

Trae loads Rules every turn and Skills on demand. GraphFlow install writes:

Path	Role
.trae/rules/graphflow.md	alwaysApply: true — must call graphflow_context first
.trae/skills/graphflow/SKILL.md	Full workflows; trigger with #graphflow
User/mcp.json	GraphFlow MCP server

If Rules are missing, type #graphflow at the start of a chat. Pass rootDir = current project absolute path on every context call.

Antigravity IDE setup (Rules + Skill + MCP)

Path	Role
~/.gemini/antigravity/mcp_config.json	Global MCP (mcpServers.graphflow)
~/.gemini/antigravity/skills/graphflow/SKILL.md	Global Skill
.agent/rules/graphflow.md	Project rules (always loaded in workspace)
.agent/skills/graphflow/SKILL.md	Project Skill
GEMINI.md (project root)	Managed token-first block

Run npx @roarpeng/graphflow install from the project root. Do not hardcode GRAPHFLOW_WORKSPACE_ROOT in MCP env.

Gemini CLI setup

Path	Role
~/.gemini/settings.json	MCP (mcpServers.graphflow)
~/.gemini/GEMINI.md	Global managed instruction block
GEMINI.md (project root)	Project managed block (with install --scope all)

GitHub Copilot (VS Code) setup

Path	Role
~/.config/Code/User/mcp.json	User MCP (servers.graphflow)
.vscode/mcp.json	Project MCP (optional, team-shared)
.github/copilot-instructions.md	Repo-level Copilot instructions

Kimi Code CLI setup

Path	Role
~/.kimi-code/mcp.json (or $KIMI_CODE_HOME/mcp.json)	User MCP (mcpServers.graphflow)
~/.kimi-code/skills/graphflow/SKILL.md	User Skill (/skill:graphflow)
~/.kimi-code/AGENTS.md	Global token-first instruction block

Run npx @roarpeng/graphflow install. Kimi Code does not expand ${workspaceFolder}; GraphFlow omits that env placeholder. Tools appear as mcp__graphflow__graphflow_*. HostAdapter id: kimi-code.

DeepSeek Harness（dsh）插件：用法与能力

GraphFlow 是 DeepSeek Harness 的 dsh-plugin。装入后模型看到的工具名带前缀 mcp__graphflow__。

能力

能力	工具（dsh 名）
压缩上下文（先调用）	mcp__graphflow__graphflow_context
任务规划 DAG	mcp__graphflow__graphflow_plan
桥接执行包	mcp__graphflow__graphflow_run
回填飞轮	mcp__graphflow__graphflow_report_outcome
ATP insight	mcp__graphflow__graphflow_insight
增量/全量建图	mcp__graphflow__graphflow_index
技能洞察	mcp__graphflow__graphflow_skill_insights
诊断	mcp__graphflow__graphflow_diagnose
图谱产物	mcp__graphflow__graphflow_artifact
技能指南	mcp__graphflow__graphflow_skill_guide

安装

dsh plugin --profile web add @roarpeng/graphflow
npx @deepseek-ai/dsh web
# 或已有 ~/.dsh 时写 home overlay + skill 文件：
npx @roarpeng/graphflow install

路径	作用
包内 cordis.patch.yml	dsh plugin add 插入的 bundle 层：MCP（cwd: process.cwd()）+ @roarpeng/graphflow/dsh glue
$DSH_HOME/cordis.patch.yml（默认 ~/.dsh）	graphflow install 写的 home overlay
$DSH_HOME/skills/graphflow/SKILL.md	本 Skill（install 复制）；glue 也会在运行时 ctx.skills.register

用法： 第一轮先 mcp__graphflow__graphflow_context（rootDir = 仓库绝对路径）。不要在 patch 里写死 GRAPHFLOW_WORKSPACE_ROOT。走了 graphflow_run 后必须 graphflow_report_outcome。会话结束时 glue 会 best-effort 关闭 pending episode（GRAPHFLOW_AUTO_CAPTURE=0 可关）。VS Code 图谱面板 / Workbench Tree 不在 dsh 上。

---

Tool Inventory (10 MCP Tools)

Core Context Tools (Highest Frequency)

Tool	Purpose	Call Frequency
graphflow_context	Preview compressed context (query) or expand anchor (anchorId)	Highest - default first step

Planning Tools (High Frequency)

Tool	Purpose	Call Frequency
graphflow_plan	Multi-step task decomposition & DAG (mode='simple' or 'insight')	High - before complex work
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
graphflow_insight	Submit or merge agent insights	Medium - no external LLM API

Graph Management Tools (Medium Frequency)

Tool	Purpose	Call Frequency
graphflow_index	Incremental workspace re-index, single-file, or full rebuild	Medium - after file changes

Collaboration & Insights Tools (Low Frequency)

Tool	Purpose	Call Frequency
graphflow_artifact	Export or import graph artifact	Low - team sharing
graphflow_skill_insights	Learned skill patterns	Low - leverage prior learning
graphflow_skill_guide	Skill usage guide for connected agents	Low - onboarding
graphflow_diagnose	Provider health, graph stats, and token savings	Low - ROI tracking / config issues

---

Standard Workflows

Workflow 1: Context First (90% of tasks)

Use when: Answering code questions, exploring codebase, understanding modules

Step 1: graphflow_context(query: "<your question>")
Step 2: Read summary + anchors as primary context
Step 3: Expand specific anchors with graphflow_context(anchorId: "...") when needed
Step 4: Read full files only when exact edits required
Step 5: After answering the user, call graphflow_context({ assistantReply: "<original answer>" })
        (query optional). This fills the pending turn/topic. Store original text, not an extracted abstract.

Complex tasks: graphflow_plan seeds a workbench of topic containers (function nodes on the canvas). Pass topicId to refine a node or return to the mainline. Drift auto-forks an isolated side node; messages stay inside the topic — the canvas is not one-turn-one-node. Without a workbench, previews still record as dialogue-turn nodes (resumeFromTurnId). Workbench titles/Path labels are display only; next-turn context is Goal + path titles + local original Q/A.

Input - context (preview):

{
  query?: string;          // User question (Chinese OK). Omit when only filling assistantReply.
  englishQuery?: string;   // Agent-translated English code search terms (recommended for CJK)
  topicId?: string;        // Click a workbench function node to refine / return to mainline
  sessionId?: string;      // Dialogue session name (default "main")
  resumeFromTurnId?: string; // Continue from a clicked dialogue-turn node (legacy, no workbench)
  assistantReply?: string; // Original assistant answer to store on the pending turn/topic
  configPath?: string;
  rootDir?: string;
}

Input - context (expand):

{
  anchorId: string;        // Required for expand - anchor id from preview
  configPath?: string;
  rootDir?: string;
}

Output structure (preview):

{
  summary: string[];
  anchors: Array<{ id: string; type: string; layer: "L1" | "L2" | "L3" }>;
  tokenBudget: {
    maxContextTokens: number;
    estimatedRawTokens: number;
    compressedTokens: number;
    estimatedSavingsPercent: number;
    budgetUsedPercent: number;
  };
  agentWorkItems?: Array<{ id: string; kind: string; prompt: string }>; // CJK low-match delegation
  englishQuery?: string;
}

Always report to user: token savings %, anchor count, key summary findings

Workflow 1b: Chinese / CJK queries (agent translates → English search)

Use when: User asks in Chinese but the codebase uses English symbols

GraphFlow tokenizes CJK and expands workspace path hints. When that is not enough, YOU must translate to English code keywords.

Preferred (proactive):

Step 1: Translate user intent to English file/symbol terms with YOUR model
Step 2: graphflow_context({ query: "<Chinese>", englishQuery: "PoseDetectionPage avatarMode BattlePage shieldEffect", rootDir })
Step 3: Use summary + anchors

Use exact file/class/component names (PascalCase stems). Avoi

---

Content truncated.