@roarpeng/graphflow 1.9.14 → 1.9.16

package/dsh/plugin.mjs

@@ -0,0 +1,454 @@
+/**
+ * GraphFlow DeepSeek Harness (dsh) glue plugin.
+ *
+ * DSH plugins are ESM (`type: module`); GraphFlow's package root is CJS.
+ * This file is the `exports["./dsh"]` entry. Cordis loads it via
+ * `name: '@roarpeng/graphflow/dsh'` in cordis.patch.yml.
+ *
+ * Duck-types `ctx` — no hard dependency on `@deepseek-ai/cordis`.
+ * Missing `ctx.skills` / events → no-op. Never throw into the harness loop.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const name = "graphflow-dsh";
+
+const PLUGIN_ID = "graphflow-dsh";
+const AUTO_CAPTURE_ENV = "GRAPHFLOW_AUTO_CAPTURE";
+const JOURNAL_RELATIVE = join(".graphflow", "session-journal.jsonl");
+const DEFAULT_SKILL_DESCRIPTION =
+  "图谱上下文压缩、任务规划与知识图谱编排（10 个 MCP 工具）。任何读代码、改代码、排错、中文问题之前必须先调 graphflow_context。DeepSeek Harness 下工具名为 mcp__graphflow__graphflow_*。";
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** @typedef {{ spawn?: typeof spawn, env?: NodeJS.ProcessEnv, cwd?: string, readSkill?: () => { name: string, description: string, content: string, source: string, path?: string } }} GraphFlowDshPluginConfig */
+
+function envOf(config) {
+  return config?.env ?? process.env;
+}
+
+export function isAutoCaptureEnabled(env = process.env) {
+  const raw = env[AUTO_CAPTURE_ENV]?.trim().toLowerCase();
+  return !(raw === "0" || raw === "false" || raw === "off" || raw === "no" || raw === "disabled");
+}
+
+/**
+ * Explicit success only — same contract as Claude Code SessionEnd `$2`.
+ * Missing GRAPHFLOW_HOOK_SUCCESS leaves the episode pending.
+ * @returns {boolean|undefined}
+ */
+export function resolveExplicitSuccess(env = process.env) {
+  const raw = env.GRAPHFLOW_HOOK_SUCCESS?.trim().toLowerCase();
+  if (raw === "true" || raw === "1" || raw === "yes") return true;
+  if (raw === "false" || raw === "0" || raw === "no") return false;
+  return undefined;
+}
+
+export function resolveSessionJournalPath(workspaceRoot) {
+  const override = process.env.GRAPHFLOW_HOOK_JOURNAL?.trim();
+  if (override) return override;
+  return join(workspaceRoot ?? process.cwd(), JOURNAL_RELATIVE);
+}
+
+export function latestPendingEpisodeId(journalPath) {
+  if (!journalPath || !existsSync(journalPath)) return undefined;
+  let text;
+  try {
+    text = readFileSync(journalPath, "utf8");
+  } catch {
+    return undefined;
+  }
+  const lines = text.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const trimmed = lines[i]?.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed?.episodeId === "string" && parsed.episodeId) {
+        return parsed.episodeId;
+      }
+    } catch {
+      // skip damaged lines
+    }
+  }
+  return undefined;
+}
+
+export function buildContextHint(cwd = process.cwd()) {
+  return `GraphFlow: before large code reads, call mcp__graphflow__graphflow_context with rootDir=${cwd}. Do not dump SKILL.md.`;
+}
+
+/**
+ * Extract the plain text of a user message (its text ContentBlocks joined).
+ * Returns "" when the message carries no text. Never throws.
+ * @param {object|undefined} message - a UserMessage (agent/inbox/inserted payload).
+ * @returns {string}
+ */
+export function extractMessageText(message) {
+  if (!message || typeof message !== "object") return "";
+  const content = message.content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const block of content) {
+    if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+      parts.push(block.text);
+    }
+  }
+  return parts.join("\n").trim();
+}
+
+/**
+ * The local GraphFlow CLI entry (this package's own dist build). Falls back to
+ * `graphflow` from PATH when dist is absent (source checkout without build).
+ * @returns {string}
+ */
+export function resolveCliCommand(packageRoot = PACKAGE_ROOT) {
+  const distCli = join(packageRoot, "dist", "surfaces", "cli", "index.js");
+  return existsSync(distCli) ? distCli : "graphflow";
+}
+
+/**
+ * Whether a message originates from the human user rather than the harness.
+ * Only `source.kind === "user"` qualifies; harness/system injections
+ * (`plugin`/`tool`/`model`) must not become dialogue turns (job finished
+ * notices, subagent reports, tool results, …). Unknown/missing source falls
+ * back to the role check so nothing legitimate is dropped.
+ * @param {object|undefined} message
+ * @returns {boolean}
+ */
+export function isUserOriginatedMessage(message) {
+  if (!message || typeof message !== "object") return false;
+  const kind =
+    message.source && typeof message.source === "object" ? message.source.kind : undefined;
+  if (kind === "user") return true;
+  if (kind === "plugin" || kind === "tool" || kind === "model") return false;
+  return message.role !== "system";
+}
+
+/**
+ * Best-effort auto-record of one user turn as a dialogue node.
+ * Spawns `graphflow dialogue record --query "<text>" [--session <sessionId>]`
+ * in the agent's workspace (cwd = session header cwd) so every web/agent
+ * question becomes a dialogue-turn graph node without relying on the agent
+ * calling graphflow_context itself. Only human-originated messages are
+ * recorded (see isUserOriginatedMessage) — harness/system injections must not
+ * pollute the dialogue graph. `sessionId` scopes the turn to one dsh session
+ * (omitted → default "main" dialogue session) so question recording and reply
+ * filling land in the same dialogue session. Never throws; the spawned child
+ * is detached.
+ * @param {object|undefined} message - a UserMessage (agent/inbox/inserted payload).
+ * @param {string} [cwd]
+ * @param {GraphFlowDshPluginConfig} [config]
+ * @param {string} [sessionId] - dialogue session name/id; omitted → "main".
+ * @returns {{attempted: boolean, reason?: string, workspace?: string}}
+ */
+export function recordDialogueFromInbox(message, cwd, config = {}, sessionId) {
+  try {
+    if (!isUserOriginatedMessage(message)) {
+      return { attempted: false, reason: "not-user-message" };
+    }
+    const env = envOf(config);
+    if (!isAutoCaptureEnabled(env)) {
+      return { attempted: false, reason: "auto-capture-off" };
+    }
+    const text = extractMessageText(message);
+    if (text.length < 4) {
+      return { attempted: false, reason: "query-too-short" };
+    }
+    const workspace = typeof cwd === "string" && cwd.trim() ? cwd : process.cwd();
+    const spawnFn = typeof config.spawn === "function" ? config.spawn : spawn;
+    const cli = resolveCliCommand(config.packageRoot);
+    const args = [cli, "dialogue", "record", "--query", text];
+    if (typeof sessionId === "string" && sessionId.trim()) {
+      args.push("--session", sessionId);
+    }
+    const bin = cli === "graphflow" ? (env.GRAPHFLOW_HOOK_BIN?.trim() || "npx") : process.execPath;
+    const fullArgs = cli === "graphflow" ? ["-y", "--package=@roarpeng/graphflow", ...args] : args;
+    spawnFn(bin, fullArgs, {
+      cwd: workspace,
+      env,
+      stdio: "ignore",
+      detached: true,
+      windowsHide: true,
+    })?.unref?.();
+    return { attempted: true, workspace };
+  } catch {
+    return { attempted: false, reason: "error" };
+  }
+}
+
+/**
+ * Best-effort fill of one assistant reply into the latest pending dialogue
+ * turn for `sessionId`. Spawns `graphflow dialogue record --reply "<text>"
+ * [--session <sessionId>]` (reply-only mode) in the workspace; the runtime
+ * fills the latest pending turn's assistantReply and safely skips when none is
+ * pending. Half-written (interrupted) replies are not filled. Never throws.
+ * @param {object|undefined} event - an `assistant/message` session event.
+ * @param {string} [sessionId] - dialogue session name/id.
+ * @param {string} [cwd]
+ * @param {GraphFlowDshPluginConfig} [config]
+ * @returns {{attempted: boolean, reason?: string, workspace?: string}}
+ */
+export function recordReplyFromTurn(event, sessionId, cwd, config = {}) {
+  try {
+    const text = extractMessageText(event?.message);
+    if (!text) {
+      return { attempted: false, reason: "no-text" };
+    }
+    if (event?.interrupted) {
+      return { attempted: false, reason: "interrupted" };
+    }
+    const env = envOf(config);
+    if (!isAutoCaptureEnabled(env)) {
+      return { attempted: false, reason: "auto-capture-off" };
+    }
+    const workspace = typeof cwd === "string" && cwd.trim() ? cwd : process.cwd();
+    const spawnFn = typeof config.spawn === "function" ? config.spawn : spawn;
+    const cli = resolveCliCommand(config.packageRoot);
+    const args = [cli, "dialogue", "record", "--reply", text];
+    if (typeof sessionId === "string" && sessionId.trim()) {
+      args.push("--session", sessionId);
+    }
+    const bin = cli === "graphflow" ? (env.GRAPHFLOW_HOOK_BIN?.trim() || "npx") : process.execPath;
+    const fullArgs = cli === "graphflow" ? ["-y", "--package=@roarpeng/graphflow", ...args] : args;
+    spawnFn(bin, fullArgs, {
+      cwd: workspace,
+      env,
+      stdio: "ignore",
+      detached: true,
+      windowsHide: true,
+    })?.unref?.();
+    return { attempted: true, workspace };
+  } catch {
+    return { attempted: false, reason: "error" };
+  }
+}
+
+export function loadGraphFlowSkillRegistration(packageRoot = PACKAGE_ROOT) {
+  const skillPath = join(packageRoot, "skills", "graphflow", "SKILL.md");
+  let content = "";
+  let description = DEFAULT_SKILL_DESCRIPTION;
+  if (existsSync(skillPath)) {
+    try {
+      content = readFileSync(skillPath, "utf8");
+      const fm = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
+      const descLine = fm?.[1]?.match(/^description:\s*["']?(.+?)["']?\s*$/m);
+      if (descLine?.[1]) {
+        description = descLine[1].replace(/\\"/g, '"').trim();
+      }
+    } catch {
+      content = "";
+    }
+  }
+  return {
+    name: "graphflow",
+    description,
+    content,
+    source: "runtime",
+    path: skillPath,
+  };
+}
+
+function payloadAgent(payload) {
+  if (!payload || typeof payload !== "object") return undefined;
+  if (payload.agent && typeof payload.agent === "object") return payload.agent;
+  return payload;
+}
+
+export function resolveWorkspaceCwd(payload, fallbackCwd = process.cwd()) {
+  const agent = payloadAgent(payload);
+  const session = payload?.session ?? agent?.session;
+  const candidates = [
+    payload?.cwd,
+    agent?.cwd,
+    session?.cwd,
+    typeof fallbackCwd === "string" ? fallbackCwd : undefined,
+  ];
+  for (const value of candidates) {
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return process.cwd();
+}
+
+function buildOutcomeArgs(episodeId, success) {
+  return ["-y", "--package=@roarpeng/graphflow", "graphflow", "outcome", "report", episodeId, success ? "true" : "false"];
+}
+
+/**
+ * Best-effort close of the latest pending episode for `cwd`.
+ * Reuses `graphflow outcome report` (same flywheel as Claude Code SessionEnd).
+ * Does not default pending episodes to success: GRAPHFLOW_HOOK_SUCCESS must be
+ * an explicit true/false. Never throws.
+ */
+export function closePendingEpisodeForCwd(cwd, config = {}) {
+  try {
+    const env = envOf(config);
+    if (!isAutoCaptureEnabled(env)) {
+      return { attempted: false, reason: "auto-capture-off" };
+    }
+    const workspace = typeof cwd === "string" && cwd.trim() ? cwd : process.cwd();
+    const journalPath = resolveSessionJournalPath(workspace);
+    const episodeId = latestPendingEpisodeId(journalPath);
+    if (!episodeId) {
+      return { attempted: false, reason: "no-pending-episode" };
+    }
+    const success = resolveExplicitSuccess(env);
+    if (success === undefined) {
+      return { attempted: false, reason: "no-explicit-success", episodeId };
+    }
+    const spawnFn = typeof config.spawn === "function" ? config.spawn : spawn;
+    const bin = env.GRAPHFLOW_HOOK_BIN?.trim() || "npx";
+    spawnFn(bin, buildOutcomeArgs(episodeId, success), {
+      cwd: workspace,
+      env,
+      stdio: "ignore",
+      detached: true,
+      windowsHide: true,
+    })?.unref?.();
+    return { attempted: true, episodeId };
+  } catch {
+    return { attempted: false, reason: "error" };
+  }
+}
+
+function safeInjectHint(agent, cwd) {
+  if (!agent || typeof agent.inject !== "function") return;
+  const text = buildContextHint(cwd);
+  agent.inject({
+    id: crypto.randomUUID(),
+    role: "user",
+    content: [{ type: "text", text }],
+    source: { kind: "plugin", plugin: PLUGIN_ID, form: "instructions" },
+  });
+}
+
+function registerSkill(ctx, config) {
+  const skills = ctx?.skills;
+  if (!skills || typeof skills.register !== "function") return;
+  const skill =
+    typeof config.readSkill === "function" ? config.readSkill() : loadGraphFlowSkillRegistration();
+  skills.register(skill);
+}
+
+function listen(ctx, event, handler) {
+  if (!ctx || typeof ctx.on !== "function") return;
+  ctx.on(event, handler);
+}
+
+/**
+ * Cordis plugin entry. DSH mounts this row as `id: graphflow-dsh`.
+ * @param {object} ctx duck-typed Cordis context
+ * @param {GraphFlowDshPluginConfig} [config]
+ */
+export function apply(ctx, config = {}) {
+  try {
+    registerSkill(ctx, config);
+  } catch {
+    // missing or duplicate skill registry — ignore
+  }
+
+  const hinted = new WeakSet();
+  const closed = new Set();
+
+  const closeFromPayload = (payload) => {
+    try {
+      const cwd = resolveWorkspaceCwd(payload, config.cwd);
+      const journalPath = resolveSessionJournalPath(cwd);
+      const episodeId = latestPendingEpisodeId(journalPath);
+      if (episodeId && closed.has(episodeId)) {
+        return { attempted: false, reason: "already-closed" };
+      }
+      const result = closePendingEpisodeForCwd(cwd, config);
+      if (result.episodeId) closed.add(result.episodeId);
+      return result;
+    } catch {
+      return { attempted: false, reason: "error" };
+    }
+  };
+
+  try {
+    // Claude Code SessionEnd analog. Do not close on session/flush — that is a
+    // live durability checkpoint, not session end; reporting true there would
+    // mark the flywheel successful while the agent is still working.
+    listen(ctx, "agent/disposed", (payload) => {
+      closeFromPayload(payload);
+    });
+  } catch {
+    // event bus missing
+  }
+
+  const recordedInboxMessages = new WeakSet();
+
+  try {
+    // Auto record every user question as a dialogue-turn node (the dsh analog
+    // of Claude Code's PostToolUse capture): each web/agent question becomes a
+    // graph node with session/workspace lineage, without relying on the agent
+    // calling graphflow_context itself. Turns are scoped to the dsh session id
+    // so question recording and reply filling stay in the same dialogue
+    // session (never crossing same-workspace sessions).
+    listen(ctx, "agent/inbox/inserted", (payload) => {
+      try {
+        const message = payload?.message;
+        if (!message || typeof message !== "object") return;
+        if (recordedInboxMessages.has(message)) return;
+        recordedInboxMessages.add(message);
+        const agent = payloadAgent(payload);
+        const cwd =
+          agent?.session?.header?.cwd ??
+          resolveWorkspaceCwd(payload, config.cwd);
+        recordDialogueFromInbox(message, cwd, config, agent?.session?.id);
+      } catch {
+        // recording is optional
+      }
+    });
+  } catch {
+    // event bus missing
+  }
+
+  const recordedReplies = new WeakSet();
+
+  try {
+    // Auto fill every assistant reply into the latest pending dialogue turn of
+    // the same dsh session: closes the question→answer loop so dialogue-turn
+    // nodes record a complete exchange without the agent calling
+    // graphflow_context({ assistantReply }) itself. Deduped per message object;
+    // interrupted (half-written) replies are skipped.
+    listen(ctx, "session/event", (session, event) => {
+      try {
+        if (event?.type !== "assistant/message") return;
+        if (event.interrupted) return;
+        const message = event.message;
+        if (!message || typeof message !== "object") return;
+        if (recordedReplies.has(message)) return;
+        recordedReplies.add(message);
+        recordReplyFromTurn(event, session?.id, session?.header?.cwd, config);
+      } catch {
+        // reply fill is optional
+      }
+    });
+  } catch {
+    // event bus missing
+  }
+
+  try {
+    listen(ctx, "agent/pre-step", (payload, next) => {
+      try {
+        const agent = payloadAgent(payload);
+        if (agent && !hinted.has(agent)) {
+          hinted.add(agent);
+          safeInjectHint(agent, resolveWorkspaceCwd(payload, config.cwd));
+        }
+      } catch {
+        // hint is optional
+      }
+      if (typeof next === "function") {
+        return next();
+      }
+      return undefined;
+    });
+  } catch {
+    // event bus missing
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roarpeng/graphflow",
-  "version": "1.9.14",
+  "version": "1.9.16",
   "publishConfig": {
     "access": "public"
   },
@@ -11,6 +11,8 @@
     "plugin.json",
     "mcp.json",
     "cordis.patch.yml",
+    "dsh",
+    "web",
     "skills",
     "src/surfaces/trae-skill",
     "src/surfaces/trae-rules",
@@ -32,6 +34,15 @@
   "description": "A Context-Aware Multi-Agent Orchestration Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dsh": "./dsh/plugin.mjs",
+    "./web": "./web/plugin.mjs",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "graphflow": "dist/surfaces/cli/index.js",
     "graphflow-mcp": "dist/surfaces/mcp/server.js"

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "graphflow",
-  "version": "1.9.14",
+  "version": "1.9.16",
   "description": "图谱上下文压缩与任务规划插件（10 个 MCP 工具）。能力：压缩上下文、DAG 规划、增量建图、技能飞轮、诊断与产物导入导出。DeepSeek Harness：dsh plugin --profile web add @roarpeng/graphflow；工具名为 mcp__graphflow__graphflow_*。先调 graphflow_context（传 rootDir），复杂任务再 plan，改完代码后 index。",
   "author": {
     "name": "Roarpeng",
@@ -26,7 +26,7 @@
       "install": "dsh plugin --profile web add @roarpeng/graphflow",
       "installHome": "npx @roarpeng/graphflow install",
       "toolsPrefix": "mcp__graphflow__",
-      "usage": "先 mcp__graphflow__graphflow_context（rootDir=仓库绝对路径），复杂任务 graphflow_plan，改完 graphflow_index；graphflow_run 之后必须 graphflow_report_outcome。",
+      "usage": "先 mcp__graphflow__graphflow_context（rootDir=仓库绝对路径），复杂任务 graphflow_plan，改完 graphflow_index；graphflow_run 之后必须 graphflow_report_outcome。启动：npx @deepseek-ai/dsh web。",
       "capabilities": [
         "graphflow_context",
         "graphflow_plan",

package/skills/graphflow/SKILL.md

@@ -114,17 +114,18 @@ GraphFlow 是 DeepSeek Harness 的 `dsh-plugin`。装入后模型看到的工具
 
 ```sh
 dsh plugin --profile web add @roarpeng/graphflow
-# 或已有 ~/.dsh 时：
+npx @deepseek-ai/dsh web
+# 或已有 ~/.dsh 时写 home overlay + skill 文件：
 npx @roarpeng/graphflow install
 ```
 
 | 路径 | 作用 |
 |------|------|
-| 包内 `cordis.patch.yml` | `dsh plugin add` 插入的 bundle 层 |
+| 包内 `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 |
+| `$DSH_HOME/skills/graphflow/SKILL.md` | 本 Skill（install 复制）；glue 也会在运行时 `ctx.skills.register` |
 
-**用法：** 每次 `graphflow_context` / `graphflow_plan` 传仓库绝对路径 `rootDir`。不要在 patch 里写死 `GRAPHFLOW_WORKSPACE_ROOT`。走了 `graphflow_run` 后必须 `graphflow_report_outcome`。
+**用法：** 第一轮先 `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 上。
 
 ---
 

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

@@ -114,17 +114,18 @@ GraphFlow 是 DeepSeek Harness 的 `dsh-plugin`。装入后模型看到的工具
 
 ```sh
 dsh plugin --profile web add @roarpeng/graphflow
-# 或已有 ~/.dsh 时：
+npx @deepseek-ai/dsh web
+# 或已有 ~/.dsh 时写 home overlay + skill 文件：
 npx @roarpeng/graphflow install
 ```
 
 | 路径 | 作用 |
 |------|------|
-| 包内 `cordis.patch.yml` | `dsh plugin add` 插入的 bundle 层 |
+| 包内 `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 |
+| `$DSH_HOME/skills/graphflow/SKILL.md` | 本 Skill（install 复制）；glue 也会在运行时 `ctx.skills.register` |
 
-**用法：** 每次 `graphflow_context` / `graphflow_plan` 传仓库绝对路径 `rootDir`。不要在 patch 里写死 `GRAPHFLOW_WORKSPACE_ROOT`。走了 `graphflow_run` 后必须 `graphflow_report_outcome`。
+**用法：** 第一轮先 `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 上。
 
 ---
 

package/web/README.md

@@ -0,0 +1,36 @@
+# GraphFlow Web 知识节点栏
+
+DeepSeek Harness web 右侧"知识节点"面板的源码种子。
+
+## 现状
+
+- **自动按轮记录**（持久、随包生效）：`dsh/plugin.mjs`（glue）监听 `agent/inbox/inserted`，
+  自动把每一轮用户提问写成 `dialogue-turn` 图节点（写入 agent 会话工作区的 `.graphflow/`）。
+  回复补全沿用既有机制：agent 调用 `graphflow_context({ assistantReply })` 时填充（与
+  Claude Code SessionEnd 同一契约）。可用 `GRAPHFLOW_AUTO_CAPTURE=0` 关闭。
+- **右侧知识节点栏**（本会话生效）：以动态 Cordis 插件（Host + Client 双半部）挂载：
+  - `conversation.session.header.utilities`：会话头部"知识节点"开关按钮
+  - `shell.overlay`：右缘浮动面板（additive，不替换任何出厂 UI），展示
+    Workbench 主题（主线/旁支、活跃、待回复、消息数）+ 对话轮次（Q/A、跳转标记）
+  - 点击节点：通过会话 binding 的 `prompt('queue')` 通道提交续聊指令，agent 自动调用
+    `graphflow_context({ topicId | resumeFromTurnId })` 恢复上下文继续
+
+## 数据来源
+
+面板数据由动态插件的 host 半部经 `harness.handle("gf.nodes.list")` 提供，
+内部调用（当前工作区下）：
+- `graphflow workbench tree --json`
+- `graphflow dialogue list --json --limit 50`
+
+## 打包为静态客户端插件（未来）
+
+dsh web 的静态客户端包必须预编译为 `window.__ModuleLoader__.load({id, factory})`
+工厂格式并经 `/plugins/<id>/client.js` 提供；纯 ESM 文件无法直接加载。
+`plugin.mjs` 中的 `hostHalf()` / `clientHalf()` 即未来 `code.host` / `code.client`
+的源码。届时需：
+1. 在 `package.json` 增加 `dsh.client` 声明（`platform: "web"` + `inject` 列表）
+2. 用 dsh monorepo 的 rolldown 管线把 `./web` 编译为客户端 bundle
+3. 在 `cordis.patch.yml` 增加第三行（客户端插件行）
+
+在完成上述打包前，**不要**在 `cordis.patch.yml` 添加该行（client-modules 扫描到
+缺失 bundle 会使 profile 组合失败）。