@zhushanwen/pi-subagent-workflow 0.1.0

package/src/interface/tool-render.ts

@@ -0,0 +1,333 @@
+// src/tui/tool-render.ts
+//
+// 对话流 tool block 渲染。renderCall（标题行）+ renderResult（背景色 block）。
+//
+// 关键设计（参照 nicobailon pi-subagents 渲染架构）：
+//   1. 不设 renderShell（默认 default）。背景色/padding 归 Pi 的 contentBox = Box(1,1,bgFn)，
+//      它按 isPartial/isError 自动切 toolPendingBg/toolSuccessBg/toolErrorBg 三态。
+//      组件 render 返回的 string[] **绝不调 theme.bg**——否则双重背景混色。
+//   2. 所有输出行经 truncLine（ANSI 安全，省略号前重应用 SGR，背景不断裂）。
+//   3. 上下留白（Spacer(1) + Box paddingY=1）由 ToolExecutionComponent 负责，
+//      组件不自己加 Spacer 做间隔。
+//   4. spinner 用 seed-based 选帧（progress 字段派生），不用 setInterval/invalidate。
+//      onUpdate 驱动重绘时 seed 变化 → 自动换帧。
+//   5. streaming delta（text/thinking）不触发 onUpdate，仅离散边界事件触发重绘。
+//   6. compact 分支返回单 Text（多行 join "\n"），expanded 返回 Container。
+//      单 Text 让整块作为单个渲染单元整体失效，绕开 pi 差分引擎对「多 Text 子组件
+//      + 内容平移」的 cell 残留 bug（ghosting 空行）。详见 renderSubagentResult 的
+//      [HISTORICAL] 注释。
+
+import type { Component } from "@earendil-works/pi-tui";
+import { Container, Text } from "@earendil-works/pi-tui";
+import type { AgentToolResult, Theme } from "@mariozechner/pi-coding-agent";
+
+import type {
+  ListResponse,
+  SubagentToolResult,
+} from "../execution/types.ts";
+import {
+  extractAgentName,
+  firstLine,
+  formatElapsedSeconds,
+  sanitizeLabel,
+  statusGlyph,
+  type ThemeLike,
+  truncLine,
+} from "./format.ts";
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** message stream 每行的缩进前缀（2 空格 + ⎿ + 空格），dim 色。 */
+const STREAM_PREFIX = "  ⎿ ";
+
+/** footer 用的纯空格缩进（与 STREAM_PREFIX 等宽 4 列，但不带 ⎿）。 */
+const FOOTER_PREFIX = "    ";
+
+/**
+ * 获取终端宽度（参照 nicobailon getTermWidth）。
+ * truncLine 需要在创建 Text 之前执行——此时 Pi 的 Box.render(contentWidth) 还未调用，
+ * 只能从 process.stdout 估算。-4 对应 Pi Box paddingX=1（左右各 1 列）+ 安全余量。
+ */
+function getTermWidth(): number {
+  return (process.stdout.columns || 120) - 4;
+}
+
+// ============================================================
+// 类型（已存在的契约）
+// ============================================================
+
+/**
+ * renderResult 的 context（SDK ToolRenderContext 的有意子集——只读 state/invalidate）。
+ * SDK 实际传入更完整的 { args, toolCallId, cwd, executionStarted, argsComplete, isPartial,
+ * expanded, showImages, isError, lastComponent, ... }，本组件结构兼容只取需要的字段。
+ *
+ * 注意：不使用 lastComponent。每次 renderResult 返回新 Container（参照 nicobailon）。
+ */
+export interface RenderContext {
+  state: Record<string, never>;
+  invalidate(): void;
+}
+
+// ============================================================
+// renderCall —— tool 标题行
+// ============================================================
+
+/**
+ * renderCall：tool 标题行（agent + model + thinking，不变信息）。
+ *
+ *   "subagent worker · glm-5.2 · thinking high"
+ *
+ * model/thinkingLevel 由调用方（subagent-tool.ts 的闭包）预解析后传入，
+ * 因为 renderCall 在 execute 前调用，但 model 解析是同步的（只读配置）。
+ * resolved 缺失时（hub 未就绪）降级为只显示 agent 名。
+ *
+ * 返回 `new Text(line, 0, 0)`——paddingX=0 paddingY=0，背景交给 contentBox。
+ */
+export function renderSubagentCall(
+  args: unknown,
+  theme: Theme,
+  _context: RenderContext,
+  resolved?: { model: string; thinkingLevel?: string },
+): Component {
+  const t = theme as ThemeLike;
+  // args 结构：{ action:"start", startParam:{ agent, task, ... } }（见 subagent-tool.ts schema）。
+  // 从 startParam 提取 agent + task，对齐 nicobailon 的 renderCall 多行布局。
+  const startParam = typeof args === "object" && args !== null && "startParam" in args
+    ? (args as { startParam?: unknown }).startParam
+    : undefined;
+  const agent = extractAgentName(startParam);
+  const parts = [`${t.fg("toolTitle", t.bold("subagent "))}${t.fg("accent", agent)}`];
+
+  // model + thinking——完整 provider/model（accent 色），thinking 保持 dim。
+  // 不去 provider 前缀——provider 是模型来源的关键信息，感知「用错模型」需要完整路径。
+  if (resolved) {
+    parts.push(t.fg("dim", " ("));
+    parts.push(t.fg("accent", resolved.model));
+    if (resolved.thinkingLevel) {
+      parts.push(t.fg("dim", ` · thinking ${resolved.thinkingLevel})`));
+    } else {
+      parts.push(t.fg("dim", ")"));
+    }
+  }
+
+  // task preview 行——对齐 nicobailon：renderCall 输出多行（标题 + \n + task 预览）。
+  // 实验假设：call 多行让首帧（无 result）与后续帧（有 result）的高度跳变模式
+  // 与 nicobailon 一致，可能影响 pi diff 引擎的行对齐路径。preview 截断到 60 字符。
+  const task = typeof startParam === "object" && startParam !== null && "task" in startParam
+    ? (startParam as { task?: unknown }).task
+    : undefined;
+  if (typeof task === "string" && task.length > 0) {
+    // task 取首行——prompt 常含换行（多行指令），直接 slice 会保留 \n，
+    // 渲染时意外换行破坏 tool block 行对齐。
+    const taskFirst = task.split("\n").find((l) => l.trim())?.trim() ?? "";
+    const preview = taskFirst.length > 60 ? `${taskFirst.slice(0, 60)}...` : taskFirst;
+    if (preview) parts.push(`\n  ${t.fg("dim", preview)}`);
+  }
+
+  return new Text(parts.join(""), 0, 0);
+}
+
+// ============================================================
+// renderResult —— 对话流背景色 block
+// ============================================================
+
+/**
+ * renderResult：对话流背景色 block。
+ *
+ * compact（默认）返回单个 Text（多行 join "\n"），expanded 返回 Container。
+ * 背景色由 Pi default shell 的 contentBox 按 isPartial/isError 自动施加，
+ * 组件本身不施加背景色。
+ *
+ *   1. details 缺失 → fallback new Text（防御性）
+ *   2. 按 action 路由到 compact / expanded / list / cancel 渲染
+ *   3. compact：lines.join("\n") → new Text（绕开 ghosting，见下方 HISTORICAL）
+ *   4. expanded：lines → Container { Text, Text, ... }
+ */
+export function renderSubagentResult(
+  result: AgentToolResult<SubagentToolResult>,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+  _context: RenderContext,
+): Component {
+  const themeLike = theme as ThemeLike;
+  const details = result.details;
+
+  // 防御性 fallback：按 action 判断 details 结构是否完整（G2-007）。
+  // list/cancel 无顶层 status/agent，旧 guard（typeof details.status）会误判「execution failed」。
+  // details 缺失通常是因为 execute 抛错（如 hub disposed）——此时 Pi 把 error.message 塞进
+  // result.content[0].text。旧实现只显示 "no details available"，吞掉真实原因，导致 AI 盲猜。
+  // 现在从 result.content 提取错误文本显示，拿不到才退回通用文案。
+  if (!details || typeof details.action !== "string" || !isDetailsStructurallyComplete(details)) {
+    const errorText = extractResultError(result.content);
+    const fallback = errorText ?? "(subagent execution failed — no details available)";
+    return new Text(themeLike.fg("warning", fallback), 0, 0);
+  }
+
+  const lines = options.expanded
+    ? buildExpandedLines(details, themeLike)
+    : buildCompactLines(details, themeLike);
+
+  // [HISTORICAL] compact 分支返回单个 Text（多行 join "\n"），而非 Container{Text...}。
+  // 对齐 nicobailon 的渲染结构（single Text 整块）。
+  // expanded 分支仍用 Container（未来可能含 Markdown 等富组件）。
+  if (!options.expanded) {
+    return new Text(lines.join("\n"), 0, 0);
+  }
+
+  const container = new Container();
+  for (const line of lines) {
+    container.addChild(new Text(line, 0, 0));
+  }
+  return container;
+}
+
+// ============================================================
+// 行内容生成（compact / expanded）
+// ============================================================
+
+/**
+ * 压缩视图行内容生成。返回裸内容行（不含背景色/padding）。
+ *
+ * 布局：statusLine + 滚动区(eventLog 最近 N 条) + 底部行。
+ * running 和 terminal 态行数可能不同（running 有 "Press Ctrl+O"，terminal 有 delivery），
+ * 不强制行数对齐（行数随 eventLog 增长自然变化）。
+ */
+function buildCompactLines(d: SubagentToolResult, theme: ThemeLike): string[] {
+  const width = getTermWidth();
+
+  // ── list 分支：表格（每行一个 item 摘要）──
+  if (d.action === "list" && d.listResponse) {
+    return renderListCompact(d.listResponse, theme, width);
+  }
+  // ── cancel 分支：确认行 ──
+  if (d.action === "cancel" && d.cancelResponse) {
+    return [truncLine(
+      `${theme.fg("muted", "■")} ${theme.fg("dim", "cancelled ")}${theme.fg("accent", d.subagentId ?? "?")}`,
+      width,
+    )];
+  }
+  // ── start 分支：background ──
+  if ("bgResponse" in d) {
+    return [truncLine(
+      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}`
+      + ` ${theme.fg("dim", "· running detached · will notify on completion")}`,
+      width,
+    )];
+  }
+  return [truncLine(theme.fg("warning", "(subagent: no response)"), width)];
+}
+
+/**
+ * 展开视图行内容生成。完整 eventLog + 交付物。
+ */
+function buildExpandedLines(d: SubagentToolResult, theme: ThemeLike): string[] {
+  const width = getTermWidth();
+
+  if (d.action === "list" && d.listResponse) {
+    return renderListExpanded(d.listResponse, theme, width);
+  }
+  if (d.action === "cancel" && d.cancelResponse) {
+    return [truncLine(
+      `${theme.fg("muted", "■")} ${theme.fg("dim", "cancelled ")}${theme.fg("accent", d.subagentId ?? "?")}`,
+      width,
+    )];
+  }
+
+  const lines: string[] = [];
+  // bg 占位 expanded 与 compact 同（一次性 block 无细节可展开）
+  if ("bgResponse" in d) {
+    lines.push(truncLine(
+      `${theme.fg("accent", "●")} ${theme.fg("dim", "background: ")}${theme.fg("accent", d.subagentId ?? "?")}`,
+      width,
+    ));
+    return lines;
+  }
+  return [truncLine(theme.fg("warning", "(subagent: no response)"), width)];
+}
+
+// ============================================================
+// 私有 helper（模块内）
+// ============================================================
+
+/** 按 action 检查 details 内层分组是否存在（G2-007 guard）。 */
+function isDetailsStructurallyComplete(d: SubagentToolResult): boolean {
+  switch (d.action) {
+    case "start":
+      return "bgResponse" in d;
+    case "list":
+      return "listResponse" in d;
+    case "cancel":
+      return "cancelResponse" in d;
+    default:
+      return false;
+  }
+}
+
+/**
+ * 从 tool result 的 content 里提取错误文本。
+ *
+ * execute 抛错（如 hub disposed / task 缺失）时，subagents handler 不 catch，
+ * Pi 框架会把 error.message 塞进 result.content[0].text。renderResult 的 fallback
+ * 分支用它把真实原因显示出来，避免只显「no details available」让 AI 盲猜。
+ * content 可能多行，只取首行（用共享 firstLine 裁断 + sanitize）。
+ */
+function extractResultError(content: AgentToolResult<SubagentToolResult>["content"]): string | undefined {
+  if (!Array.isArray(content)) return undefined;
+  for (const item of content) {
+    const text = getStringText(item);
+    if (text) return firstLineSanitized(text);
+  }
+  return undefined;
+}
+
+/** 若 item 是带非空 .text 的对象则返回 text，否则 undefined。 */
+function getStringText(item: unknown): string | undefined {
+  if (typeof item !== "object" || item === null) return undefined;
+  const val = (item as Record<string, unknown>).text;
+  return typeof val === "string" && val.trim().length > 0 ? val : undefined;
+}
+
+/**
+ * 取文本首个非空行（多行压成首行展示），并 sanitize。
+ * 用于 done/failed 的交付物预览。
+ * 共享 firstLine（./format.ts）取首行，本 wrapper 叠加 sanitizeLabel。
+ */
+function firstLineSanitized(text?: string): string {
+  return sanitizeLabel(firstLine(text));
+}
+
+// ============================================================
+// list 渲染 helper（action:"list" 分支）
+// ============================================================
+
+/** list compact：标题行 + 每行一个 item 摘要（glyph + agent + mode + status + duration）。 */
+function renderListCompact(resp: ListResponse, theme: ThemeLike, width: number): string[] {
+  if (resp.items.length === 0) {
+    return [truncLine(theme.fg("dim", `No subagents (running: ${resp.running})`), width)];
+  }
+  const lines: string[] = [
+    truncLine(theme.fg("dim", `Subagents (running: ${resp.running}/${resp.items.length})`), width),
+  ];
+  for (const it of resp.items) {
+    const glyph = statusGlyph(it.status);
+    const icon = glyph.icon ?? "●";
+    const mode = "bg";
+    const line = `${theme.fg(glyph.color, icon)} ${theme.fg("accent", it.agent)}`
+      + ` ${theme.fg("dim", `· ${mode} · ${it.status} · ${formatElapsedSeconds(it.duration)}`)}`;
+    lines.push(truncLine(`${STREAM_PREFIX}${line}`, width));
+  }
+  return lines;
+}
+
+/** list expanded：compact 基础上每 item 追加 sessionFile 路径行。 */
+function renderListExpanded(resp: ListResponse, theme: ThemeLike, width: number): string[] {
+  const lines = renderListCompact(resp, theme, width);
+  for (const it of resp.items) {
+    if (it.sessionFile) {
+      lines.push(truncLine(`${theme.fg("dim", `${FOOTER_PREFIX}session: `)}${it.sessionFile}`, width));
+    }
+  }
+  return lines;
+}

package/src/interface/tool-workflow-script.ts

@@ -0,0 +1,351 @@
+/**
+ * Workflow Extension — tool-workflow-script
+ *
+ * workflow-script tool，5 actions（FR-5：脚本领域收口为单 tool）。
+ *
+ * Actions:
+ * - generate: AI 生成临时脚本 → 写 .pi/workflows/.tmp/
+ * - lint: 静态检查脚本（调 engine/script-lint.ts lintScript）
+ * - save: 临时脚本转固定（.tmp → .pi/workflows/）
+ * - delete: 删除脚本（前查 isRunning 防删运行中脚本）
+ * - list: 列出可用脚本（调 registry.loadAll）
+ *
+ * 层归属：Interface。依赖 Pi SDK + engine script-lint + infra workflow-files。
+ *
+ * 参考：domain-models.md §FR-5（tool 收口 4→2）。
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve as pathResolve } from "node:path";
+
+import { StringEnum } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { type Static, Type } from "typebox";
+
+import type { WorkflowScriptRegistry } from "../orchestration/models/workflow-script-registry.ts";
+import { lintScript } from "../orchestration/script-lint.ts";
+import { deleteWorkflow, saveWorkflow } from "../orchestration/workflow-files.ts";
+import { renderTextFallback } from "./views/format.ts";
+
+// ── Parameter schema ─────────────────────────────────────────
+
+const WorkflowScriptParams = Type.Object({
+  action: StringEnum(["generate", "lint", "save", "delete", "list"] as const, {
+    description: "Script management action",
+  }),
+  name: Type.Optional(
+    Type.String({ description: "Workflow script name (generate/lint/save/delete)" }),
+  ),
+  script: Type.Optional(
+    Type.String({ description: "Complete JS workflow script content (generate only)" }),
+  ),
+  description: Type.Optional(
+    Type.String({ description: "Workflow purpose (generate only)" }),
+  ),
+  newName: Type.Optional(
+    Type.String({ description: "New name when saving a tmp script (save --as only)" }),
+  ),
+});
+
+type ScriptParams = Static<typeof WorkflowScriptParams>;
+
+// ── Tool result types (S3: typed details, replaces Record<string, unknown>) ──
+
+/**
+ * Discriminated union of `workflow-script` tool `details` payloads.
+ *
+ * Discriminant: `action`. `save`/`delete` may surface structured `ok:false`
+ * details on failure (instead of bare `undefined`) so programmatic consumers
+ * can distinguish error shape from success.
+ */
+export type WorkflowScriptToolDetails =
+  | { action: "generate"; path: string; name: string; status: "ready" }
+  | { action: "lint"; name: string; valid: boolean; findingCount: number }
+  | { action: "list"; count: number }
+  | { action: "save"; name: string; ok: boolean }
+  | { action: "delete"; name: string; ok: boolean };
+
+/** Result returned by the `workflow-script` tool's execute. */
+export interface TextContent {
+  content: Array<{ type: "text"; text: string }>;
+  details: WorkflowScriptToolDetails | undefined;
+  isError?: boolean;
+}
+
+// ── Tool registration ────────────────────────────────────────
+
+/**
+ * 注册 workflow-script tool（5 actions: generate/lint/save/delete/list）。
+ *
+ * @param pi ExtensionAPI
+ * @param registry WorkflowScriptRegistry
+ * @param isRunning 判断脚本是否正在运行（delete 前防删运行中脚本；factory 传入）
+ */
+export function registerWorkflowScriptTool(
+  pi: ExtensionAPI,
+  registry: WorkflowScriptRegistry,
+  isRunning: (name: string) => boolean,
+): void {
+  pi.registerTool({
+    name: "workflow-script",
+    label: "Workflow Script",
+    description:
+      "Manage workflow scripts: generate (AI creates tmp script), lint (static check), " +
+      "save (tmp→permanent), delete, list. Replaces workflow-generate + workflow-lint tools.",
+    promptSnippet: "Generate, lint, save, delete, or list workflow scripts",
+    promptGuidelines: [
+      "generate: AI writes a tmp workflow script to .pi/workflows/.tmp/. Script can be run immediately via the workflow tool.",
+      "lint: Statically check a script for common API misuse (outputSchema, result.output, file state).",
+      "save: Promote a tmp script to permanent (.pi/workflows/).",
+      "delete: Remove a script (blocked if a run is active).",
+      "list: Show all available workflow scripts with source tags.",
+    ],
+    parameters: WorkflowScriptParams,
+
+    async execute(
+      _toolCallId: string,
+      params: ScriptParams,
+      signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: ExtensionContext,
+    ): Promise<TextContent> {
+      switch (params.action) {
+        case "generate":
+          return actionGenerate(params, signal);
+        case "lint":
+          return actionLint(params, registry);
+        case "save":
+          return actionSave(params);
+        case "delete":
+          return actionDelete(params, registry, isRunning);
+        case "list":
+          return await actionList(registry);
+        default:
+          return textResult(`Unknown action: ${String(params.action)}`, true);
+      }
+    },
+
+    renderCall(args: ScriptParams, theme: Theme, _context?: unknown) {
+      const label = `workflow-script ${args.action}`;
+      const name = args.name ?? "";
+      const text =
+        theme.fg("toolTitle", theme.bold(`${label} `)) + theme.fg("accent", name);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(
+      result: { content?: Array<{ type: string; text?: string }> },
+      _options: unknown,
+      _theme: Theme,
+      _context?: unknown,
+    ) {
+      return new Text(renderTextFallback(result), 0, 0);
+    },
+  });
+}
+
+// ── generate action ──────────────────────────────────────────
+
+function actionGenerate(params: ScriptParams, signal: AbortSignal | undefined): TextContent {
+  if (signal?.aborted) {
+    return textResult("Operation aborted before start", true);
+  }
+  const name = params.name;
+  const script = params.script;
+  if (!name || !script) {
+    return textResult("generate requires 'name' and 'script' parameters", true);
+  }
+
+ // 1. Reject ESM syntax (Worker runs CJS); 'export const meta' 例外
+  const stripped = script.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+  if (/\bimport\s+(?:type\s+)?[\w{*]/.test(stripped)) {
+    return textResult(
+      "Script uses ESM 'import' syntax. Workflow scripts run in a CJS Worker — use require() instead.",
+      true,
+    );
+  }
+  const hasExportMeta = /\bexport\s+const\s+meta\s*=/.test(stripped);
+  const otherExports = stripped.match(/\bexport\s+(?:const|let|var|function|default|\{)/g);
+  if (otherExports && !hasExportMeta) {
+    return textResult(
+      "Script uses ESM 'export' (non-meta). Use 'const meta = {...}' at top level instead.",
+      true,
+    );
+  }
+
+ // 2. Validate meta declaration
+  if (!script.includes("const meta") && !script.includes("export const meta")) {
+    return textResult(
+      "Script must contain a meta declaration: const meta = { name, description, phases }",
+      true,
+    );
+  }
+
+ // 3. Check agent usage
+  if (!/\bagent\s*\(/.test(stripped)) {
+    return textResult(
+      "Script does not contain any agent() calls. A workflow must call agent() at least once.",
+      true,
+    );
+  }
+
+ // 4. Syntax check (wrap in async IIFE like runtime)
+  const cjsScript = script.replace(/\bexport\s+const\s+meta\b/, "const meta");
+  try {
+    new Function(`(async () => { ${cjsScript} })();`);
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return textResult(`Syntax error in script: ${msg}`, true);
+  }
+
+ // 5. Write to .tmp directory
+  const tmpDir = pathResolve(".pi/workflows/.tmp");
+  mkdirSync(tmpDir, { recursive: true });
+  const filePath = pathResolve(tmpDir, `${name}.js`);
+  writeFileSync(filePath, script, "utf-8");
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Generated workflow script: ${filePath}\nName: ${name}\nReady to run via the workflow tool.`,
+      },
+    ],
+    details: { action: "generate", path: filePath, name, status: "ready" },
+  };
+}
+
+// ── lint action ──────────────────────────────────────────────
+
+async function actionLint(
+  params: ScriptParams,
+  registry: WorkflowScriptRegistry,
+): Promise<TextContent> {
+  const name = params.name;
+  if (!name) {
+    return textResult("lint requires 'name' parameter", true);
+  }
+  const source = await loadScriptSource(name, registry);
+  if (!source) {
+    return textResult(`Workflow '${name}' not found or not available.`, true);
+  }
+
+  const result = lintScript(source);
+  if (result.findings.length === 0) {
+    return textResult(`✅ No issues found in '${name}'.`);
+  }
+
+  const lines = result.findings.map((f) => {
+    const icon = f.severity === "error" ? "❌" : "⚠️";
+    return `${icon} L${f.line}: ${f.message}\n   Suggestion: ${f.suggestion}`;
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: `${result.valid ? "Warnings" : "Errors"} found in '${name}':\n\n${lines.join("\n\n")}`,
+      },
+    ],
+    details: { action: "lint", name, valid: result.valid, findingCount: result.findings.length },
+    isError: !result.valid,
+  };
+}
+
+/**
+ * 加载脚本源码（lint 用）。通过 registry port 获取——registry 返回的
+ * WorkflowScript 自带 sourceCode（FR-2：registry 是唯一读文件处），
+ * 不再穿透到 config-loader 直接扫文件系统。
+ */
+async function loadScriptSource(
+  name: string,
+  registry: WorkflowScriptRegistry,
+): Promise<string | undefined> {
+  const script = await registry.get(name);
+  return script?.available ? script.sourceCode : undefined;
+}
+
+// ── save action ──────────────────────────────────────────────
+
+async function actionSave(params: ScriptParams): Promise<TextContent> {
+  const name = params.name;
+  if (!name) {
+    return textResult("save requires 'name' parameter (tmp script name)", true);
+  }
+  try {
+    const result = await saveWorkflow(name, params.newName);
+    return {
+      content: [{ type: "text", text: result }],
+      details: { action: "save", name, ok: true },
+    };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Save failed: ${msg}` }],
+      details: { action: "save", name, ok: false },
+      isError: true,
+    };
+  }
+}
+
+// ── delete action ────────────────────────────────────────────
+
+function actionDelete(
+  params: ScriptParams,
+  registry: WorkflowScriptRegistry,
+  isRunning: (name: string) => boolean,
+): TextContent {
+  const name = params.name;
+  if (!name) {
+    return textResult("delete requires 'name' parameter", true);
+  }
+ // deleteWorkflow 内部检查 isRunning（防止删运行中脚本）
+  try {
+    const result = deleteWorkflow(name, isRunning);
+ // 失效 registry 缓存（下次 list/get 重扫）
+    registry.invalidate();
+    return {
+      content: [{ type: "text", text: result }],
+      details: { action: "delete", name, ok: true },
+    };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Delete failed: ${msg}` }],
+      details: { action: "delete", name, ok: false },
+      isError: true,
+    };
+  }
+}
+
+// ── list action ──────────────────────────────────────────────
+
+async function actionList(registry: WorkflowScriptRegistry): Promise<TextContent> {
+  try {
+    const all = await registry.loadAll();
+    const available = all.filter((wf) => wf.available);
+    if (available.length === 0) {
+      return textResult("No workflow scripts available.");
+    }
+    const lines = available.map(
+      (wf) => `  [${wf.source}] ${wf.name} — ${wf.meta.description || "(no description)"}`,
+    );
+    return {
+      content: [{ type: "text", text: `Available workflows:\n${lines.join("\n")}` }],
+      details: { action: "list", count: available.length },
+    };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return textResult(`List failed: ${msg}`, true);
+  }
+}
+
+// ── helper ───────────────────────────────────────────────────
+
+function textResult(text: string, isError = false): TextContent {
+  return {
+    content: [{ type: "text", text }],
+    details: undefined,
+    isError: isError || undefined,
+  };
+}