@roarpeng/graphflow 1.9.13 → 1.9.15

package/skills/graphflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "graphflow"
-description: "Graph-based code context compression, task planning, and knowledge graph orchestration (10 MCP tools). Invoke before ANY code question, bug fix, debugging, file reading, Chinese/CJK query, refactor, or multi-step edit — ALWAYS call graphflow_context MCP first when GraphFlow is connected."
+description: "图谱上下文压缩、任务规划与知识图谱编排（10 个 MCP 工具）。任何读代码、改代码、排错、中文问题之前必须先调 graphflow_context。DeepSeek Harness 下工具名为 mcp__graphflow__graphflow_*。"
 ---
 
 # GraphFlow Skill
@@ -91,6 +91,42 @@ Run `npx @roarpeng/graphflow install` from the project root. Do **not** hardcode
 | `.vscode/mcp.json` | Project MCP (optional, team-shared) |
 | `.github/copilot-instructions.md` | Repo-level Copilot instructions |
 
+### 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` |
+
+**安装**
+
+```sh
+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)
@@ -138,13 +174,21 @@ 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):**
 ```typescript
 {
-  query: string;           // Required for preview - user question (Chinese OK)
+  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;
 }
@@ -210,9 +254,11 @@ Step 2: graphflow_plan(task: "<task description>")
     (simple-plan-intent, simple-plan-decomposition) and optional suggestedNodes.
     MUST submit/merge via graphflow_insight before treating the DAG as final.
   - Local suggestedNodes are heuristic hints only.
-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
+  - Result includes workbench.topics and workbench.outline (mainline DAG + side branches).
+Step 3: Review workbench.outline (function nodes), not chat turns. Wake later with graphflow workbench tree or graphflow_diagnose (graph.workbenchOutline).
+Step 4: Refine a node: graphflow_context({ query, topicId: "<topic:...>" })
+Step 5: If the conversation drifted, click a 主线 node (same topicId) to restore trunk context
+Step 6: graphflow_index() after major changes
 ```
 
 **Input:**

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

@@ -87,8 +87,11 @@ 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, graphflow_context({ assistantReply: "<original answer>" }) to fill the pending turn
 ```
 
+Each `graphflow_context` preview records the user question into the graph (workbench topic if a plan DAG exists, otherwise a dialogue-turn). After answering, call again with `assistantReply` (query optional) so the original answer is stored. Workbench titles are display labels only — do not replace stored messages with an extracted abstract.
+
 ### Workflow 2: Plan Before Coding (complex tasks)
 
 **Use when:** Multi-step changes, refactors, features with unclear scope
@@ -96,11 +99,14 @@ Step 4: Read full files only when exact edits required
 ```
 Step 1: graphflow_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
+Step 3: Review workbench.topics (function nodes on the canvas). Wake the outline later with graphflow workbench tree / graphflow_diagnose.graph.workbenchOutline.
+Step 4: Refine a node with graphflow_context({ query, topicId })
+Step 5: If the chat drifted, click a 主线 node (same topicId) to return
+Step 6: graphflow_index() after major changes
 ```
 
+Each `graphflow_plan` seeds a **workbench** of topic containers (function nodes). Click a node and pass `topicId` to `graphflow_context` to refine that function. Drift auto-forks an isolated side node; click a 主线 node to return. Messages stay inside the topic — the canvas is not one-turn-one-node. Wake the outline with `graphflow workbench tree`, VS Code **GraphFlow: Workbench Tree**, or chat `/tree`. The tree stays collapsed until you open it.
+
 ### Workflow 3: Deep Analysis (complex/ambiguous tasks)
 
 **Use when:** High-stakes changes, root-cause analysis, ambiguous requirements
@@ -131,6 +137,7 @@ If MCP is unavailable, use the CLI fallback and always request JSON output:
 graphflow --json context preview "<query>"
 graphflow --json plan "<task>"
 graphflow --json graph inspect
+graphflow --json workbench tree
 graphflow --json skill insights
 graphflow --json route diagnose
 ```

package/src/surfaces/trae-skill/graphflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "graphflow"
-description: "Graph-based code context compression, task planning, and knowledge graph orchestration (10 MCP tools). Invoke before ANY code question, bug fix, debugging, file reading, Chinese/CJK query, refactor, or multi-step edit — ALWAYS call graphflow_context MCP first when GraphFlow is connected."
+description: "图谱上下文压缩、任务规划与知识图谱编排（10 个 MCP 工具）。任何读代码、改代码、排错、中文问题之前必须先调 graphflow_context。DeepSeek Harness 下工具名为 mcp__graphflow__graphflow_*。"
 ---
 
 # GraphFlow Skill
@@ -91,6 +91,42 @@ Run `npx @roarpeng/graphflow install` from the project root. Do **not** hardcode
 | `.vscode/mcp.json` | Project MCP (optional, team-shared) |
 | `.github/copilot-instructions.md` | Repo-level Copilot instructions |
 
+### 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` |
+
+**安装**
+
+```sh
+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)
@@ -138,13 +174,21 @@ 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):**
 ```typescript
 {
-  query: string;           // Required for preview - user question (Chinese OK)
+  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;
 }
@@ -210,9 +254,11 @@ Step 2: graphflow_plan(task: "<task description>")
     (simple-plan-intent, simple-plan-decomposition) and optional suggestedNodes.
     MUST submit/merge via graphflow_insight before treating the DAG as final.
   - Local suggestedNodes are heuristic hints only.
-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
+  - Result includes workbench.topics and workbench.outline (mainline DAG + side branches).
+Step 3: Review workbench.outline (function nodes), not chat turns. Wake later with graphflow workbench tree or graphflow_diagnose (graph.workbenchOutline).
+Step 4: Refine a node: graphflow_context({ query, topicId: "<topic:...>" })
+Step 5: If the conversation drifted, click a 主线 node (same topicId) to restore trunk context
+Step 6: graphflow_index() after major changes
 ```
 
 **Input:**