@roarpeng/graphflow 1.9.12 → 1.9.14

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,41 @@ 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
+# 或已有 ~/.dsh 时：
+npx @roarpeng/graphflow install
+```
+
+| 路径 | 作用 |
+|------|------|
+| 包内 `cordis.patch.yml` | `dsh plugin add` 插入的 bundle 层 |
+| `$DSH_HOME/cordis.patch.yml`（默认 `~/.dsh`） | `graphflow install` 写的 home overlay |
+| `$DSH_HOME/skills/graphflow/SKILL.md` | 本 Skill |
+
+**用法：** 每次 `graphflow_context` / `graphflow_plan` 传仓库绝对路径 `rootDir`。不要在 patch 里写死 `GRAPHFLOW_WORKSPACE_ROOT`。走了 `graphflow_run` 后必须 `graphflow_report_outcome`。
+
 ---
 
 ## Tool Inventory (10 MCP Tools)
@@ -138,13 +173,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 +253,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:**