c0de-agent 1.2.0 → 1.3.0

package/dist/core/index.d.ts

@@ -11,4 +11,6 @@ export { clearSteering, drainSteering, injectSteering } from './steering.js';
 export type { CollectedToolCall, ToolCallResult } from './tool-exec.js';
 export { executeToolCall, executeToolCalls, partitionByConflict } from './tool-exec.js';
 export type { AgentConfig, AgentDependencies, AgentError, AgentEvent, AgentState, AgentStatus, CommandContext, CommandResult, LLMSegment, PendingToolCall, ProjectInfo, PromptContext, SlashCommand, TokenBudget, } from './types.js';
-export { containsWorkflow, WORKFLOW_NOTICE } from './workflow.js';
+export { buildWorkflowNotice, containsWorkflow, WORKFLOW_NOTICE } from './workflow.js';
+export type { WorkflowAgentResult, WorkflowContext, WorkflowEntry, WorkflowMeta, WorkflowRegistry, WorkflowResult, WorkflowUtils, } from './workflows/index.js';
+export { BUILTIN_WORKFLOWS, buildWorkflowContext, createAndPopulateRegistry, createBuiltinWorkflows, createWorkflowRegistry, discoverWorkflows, executeWorkflow, } from './workflows/index.js';

package/dist/core/index.js

@@ -9,4 +9,5 @@ export { buildSystemPrompt } from './prompt.js';
 export { builtinCommands, createSlashRegistry, parseSlashInput } from './slash.js';
 export { clearSteering, drainSteering, injectSteering } from './steering.js';
 export { executeToolCall, executeToolCalls, partitionByConflict } from './tool-exec.js';
-export { containsWorkflow, WORKFLOW_NOTICE } from './workflow.js';
+export { buildWorkflowNotice, containsWorkflow, WORKFLOW_NOTICE } from './workflow.js';
+export { BUILTIN_WORKFLOWS, buildWorkflowContext, createAndPopulateRegistry, createBuiltinWorkflows, createWorkflowRegistry, discoverWorkflows, executeWorkflow, } from './workflows/index.js';

package/dist/core/loop.js

@@ -712,8 +712,23 @@ export async function* agentLoop(state, deps) {
         const steering = drainSteering(state);
         const { entries, snapshots } = await getSessionContext(deps.db, state.session.id);
         let chatMessages = entriesToChatMessages(entries, snapshots);
+        // steering 消息必须插入到最后一条 user 消息之前（而非末尾 push），
+        // 使 notice 在相关 user 消息的同一 turn 生效。
+        // 参考 oh-my-pi magic-keyword fix：末尾 system 消息会被模型忽略。
         for (const s of steering) {
-            chatMessages.push({ role: 'system', content: s });
+            let lastUserIdx = -1;
+            for (let i = chatMessages.length - 1; i >= 0; i--) {
+                if (chatMessages[i]?.role === 'user') {
+                    lastUserIdx = i;
+                    break;
+                }
+            }
+            if (lastUserIdx >= 0) {
+                chatMessages.splice(lastUserIdx, 0, { role: 'system', content: s });
+            }
+            else {
+                chatMessages.push({ role: 'system', content: s });
+            }
         }
         if (deps.hookRunner) {
             const hookResult = await deps.hookRunner.runHooks('message:before', {

package/dist/core/slash.js

@@ -1,3 +1,6 @@
+import { createSession } from '../session/session.js';
+import { createAgent } from './agent.js';
+import { BUILTIN_WORKFLOWS, createWorkflowRegistry, executeWorkflow } from './workflows/index.js';
 function parseSlashInput(input) {
     const trimmed = input.trim();
     if (!trimmed.startsWith('/'))
@@ -32,6 +35,7 @@ const helpCommand = {
             '  /help           Show this help',
             '  /fork [index]   Fork session from a message',
             '  /config [k][v]  View or set configuration',
+            '  /workflow       Manage and run workflows',
         ];
         return { _tag: 'text', text: lines.join('\n') };
     },
@@ -102,6 +106,74 @@ const configCommand = {
         return { _tag: 'success', message: 'Config updates are handled via the config API' };
     },
 };
+const workflowCommand = {
+    name: 'workflow',
+    description: 'Manage and run workflows',
+    argsHint: '[run|show|list] [name] [args]',
+    execute: async (args, ctx) => {
+        const parts = args.split(/\s+/).filter(Boolean);
+        const subcommand = parts[0] ?? 'list';
+        let registry = ctx.workflowRegistry;
+        if (!registry) {
+            // 回退：创建仅含内置的注册表
+            registry = createWorkflowRegistry();
+            for (const wf of BUILTIN_WORKFLOWS) {
+                registry.register(wf);
+            }
+        }
+        if (subcommand === 'list') {
+            const workflows = registry.list();
+            const lines = ['Available workflows:'];
+            for (const wf of workflows) {
+                const phases = wf.meta.phases ? ` [${wf.meta.phases.join('→')}]` : '';
+                lines.push(`  /${wf.meta.name}${phases}  — ${wf.meta.description} (${wf.source})`);
+            }
+            lines.push('');
+            lines.push('Usage: /workflow run <name> [args]');
+            return { _tag: 'text', text: lines.join('\n') };
+        }
+        if (subcommand === 'show') {
+            const name = parts[1];
+            if (!name)
+                return { _tag: 'error', message: 'Usage: /workflow show <name>' };
+            const wf = registry.get(name);
+            if (!wf) {
+                return { _tag: 'error', message: `Unknown workflow: ${name}` };
+            }
+            const code = wf.sourceCode ?? '// source not available';
+            return {
+                _tag: 'text',
+                text: `// ${wf.meta.name}: ${wf.meta.description}\n\n${code}`,
+            };
+        }
+        if (subcommand === 'run') {
+            const name = parts[1];
+            if (!name)
+                return { _tag: 'error', message: 'Usage: /workflow run <name> [args]' };
+            const wfArgs = parts.slice(2).join(' ');
+            const agentConfig = {
+                provider: ctx.config.defaultProvider,
+                model: ctx.config.defaultModel,
+                tools: [],
+                plugins: ctx.config.plugins.enabled,
+                agentName: 'default',
+            };
+            const session = await createSession(ctx.deps.db, `workflow:${name}`, undefined, 'workflow');
+            const parent = await createAgent(session, agentConfig, ctx.deps);
+            return executeWorkflow({
+                registry,
+                name,
+                args: wfArgs,
+                deps: ctx.deps,
+                parent,
+            });
+        }
+        return {
+            _tag: 'error',
+            message: `Unknown subcommand: ${subcommand}. Use: list, run, show`,
+        };
+    },
+};
 const builtinCommands = [
     helpCommand,
     compactCommand,
@@ -109,5 +181,6 @@ const builtinCommands = [
     clearCommand,
     forkCommand,
     configCommand,
+    workflowCommand,
 ];
 export { builtinCommands, createSlashRegistry, parseSlashInput };

package/dist/core/types.d.ts

@@ -87,6 +87,7 @@ type CommandContext = {
     cwd: string;
     config: Config;
     deps: AgentDependencies;
+    workflowRegistry?: import('./workflows/registry.js').WorkflowRegistry;
 };
 type SlashCommand = {
     name: string;

package/dist/core/workflow.d.ts

@@ -11,8 +11,11 @@
  *  - 单任务模式：`{ subagent_type?, prompt, description? }`
  */
 /**
- * 判断 `text` 是否在 prose 中包含独立关键词 "workflowz"
- * （小写、空白分隔）——不在代码块、行内代码或路径中。
+ * 判断 `text` 是否在 prose 中包含独立关键词 "workflowz"。
+ *
+ * 边界为「非 ASCII 词/路径字符」，因此 CJK 字符和中文标点也算合法边界
+ * （中文无词间空格）；但仍拒绝 workflowzed / reworkflowz / workflowz.test.ts
+ * 等拉丁词续或路径内嵌形式。
  *
  * 简化版 prose 检测：移除 ``` 代码块和 `行内代码` 后再匹配。
  */
@@ -22,4 +25,12 @@ export declare function containsWorkflow(text: string): boolean;
  *
  * 适配 c0de-agent 的 task 工具 schema（subagent_type + context + tasks[]）。
  */
-export declare const WORKFLOW_NOTICE = "<workflow-notice>\nThe user's message contains the **workflowz** keyword: drive this task as a deterministic multi-subagent workflow. Use the `task` tool for batched fan-out \u2014 to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.\n\n<when>\nWorth it when the task benefits from decomposition + parallel coverage, or from independent/adversarial cross-checking. For a quick lookup or single edit, just do it directly \u2014 don't spin up agents. Scout inline first (list the files, scope the diff, find the call sites) to discover the work list, then fan out over it. Common shapes:\n- **Understand** \u2014 parallel readers over subsystems \u2192 structured map.\n- **Design** \u2014 independent approaches \u2192 scored synthesis.\n- **Review** \u2014 split dimensions \u2192 find per dimension \u2192 adversarially verify each finding.\n- **Research** \u2014 multi-modal sweep \u2192 deep-read the hits \u2192 synthesize.\n- **Migrate** \u2014 discover sites \u2192 transform each \u2192 verify.\n</when>\n\n<task-contract>\nCall `task` once per independent fan-out batch using the batch form:\n\n    task({\n      subagent_type: \"coder\",\n      context: \"shared background all subagents need\",\n      tasks: [\n        { prompt: \"specific assignment for agent 1\", description: \"short label\" },\n        { prompt: \"specific assignment for agent 2\", description: \"short label\" },\n      ]\n    })\n\nAvailable subagent types: `general` (full tools, recursive), `coder` (implementation), `researcher` (read-only scout), `reviewer` (code review). Pick the type that matches each task's intent.\n\n`context` carries shared background prepended to every subagent's prompt \u2014 put the shared contract, conventions, and coordination rules here.\n\nEach task in `tasks[]` must be self-contained:\n- `prompt`: exact target (files, symbols, subsystem) + what to do + acceptance criteria\n- `description`: short label for the UI\n\nEach subagent runs in an isolated session and returns its result via the `yield` tool. Subagents skip formatters, linters, and project-wide tests \u2014 the parent runs shared proof once after all results return.\n</task-contract>\n\n<structure>\nDecompose first, then batch the independent leaves:\n\n    task({\n      subagent_type: \"coder\",\n      context: \"# Goal\\nImplement feature X across the codebase\\n# Constraints\\nFollow existing patterns...\\n# Contract\\nReturn findings as structured data...\",\n      tasks: [\n        { prompt: \"# Target\\nsrc/auth/login.ts\\n# Change\\nAdd rate limiting to login endpoint\\n# Acceptance\\nRate limiter works, tests pass\", description: \"Login rate limiting\" },\n        { prompt: \"# Target\\nsrc/auth/signup.ts\\n# Change\\nAdd input validation\\n# Acceptance\\nValidation blocks invalid emails\", description: \"Signup validation\" },\n      ]\n    })\n\nPrefer one wide batch over serial calls when work items do not share files. If tasks overlap, have agents coordinate before editing.\n</structure>\n\n<patterns>\n- **Adversarial verify** \u2014 dispatch skeptical reviewers with distinct targets, then keep only findings you can verify against source.\n- **Perspective-diverse review** \u2014 use separate correctness, security, performance roles instead of identical reviewers.\n- **Completeness critic** \u2014 after the first batch, dispatch one read-only critic that asks what was missed.\n- **No silent caps** \u2014 if you bound coverage (top-N, sampling), state what was dropped and why.\n- **Parent owns closure** \u2014 subagents return evidence; the parent reads it, resolves contradictions, runs proof, and makes the final decision.\n</patterns>\n\n<execution>\n- Capture multi-phase workflow state in the visible todo system when available.\n- Batch independent subagents in one `task` call.\n- Give every subagent a narrow target, explicit non-goals, and a concrete return packet.\n- After fan-out returns, read the results, patch or decide, and run the shared gate.\n- Keep going until the task is closed \u2014 returned fan-out is a step, not a stopping point.\n</execution>\n</workflow-notice>";
+export declare const WORKFLOW_NOTICE = "<workflow-notice>\nThe user's message contains the **workflowz** keyword: you MUST drive this task as a deterministic multi-subagent workflow using the `task` tool for batched fan-out. This is not optional \u2014 the keyword signals the user explicitly wants parallel sub-agent decomposition, not inline work. This overrides any default tendency to do the whole task inline.\n\n<when>\nThe user typed workflowz intentionally \u2014 they want fan-out. You may do a brief inline scout (1-2 tool calls to list files/scope the work), but your NEXT action after scouting MUST be a `task` tool call to fan out. Do NOT spend the entire turn reading files inline \u2014 that defeats the purpose. Common shapes:\n- **Understand** \u2014 parallel readers over subsystems \u2192 structured map.\n- **Design** \u2014 independent approaches \u2192 scored synthesis.\n- **Review** \u2014 split dimensions \u2192 find per dimension \u2192 adversarially verify each finding.\n- **Research** \u2014 multi-modal sweep \u2192 deep-read the hits \u2192 synthesize.\n- **Migrate** \u2014 discover sites \u2192 transform each \u2192 verify.\n</when>\n\n<task-contract>\nCall `task` once per independent fan-out batch using the batch form:\n\n    task({\n      subagent_type: \"coder\",\n      context: \"shared background all subagents need\",\n      tasks: [\n        { role: \"coder\", assignment: \"specific assignment for agent 1\", description: \"short label\" },\n        { role: \"reviewer\", assignment: \"specific assignment for agent 2\", description: \"short label\" },\n      ]\n    })\n\nAvailable subagent types: `general` (full tools, recursive), `coder` (implementation), `researcher` (read-only scout), `reviewer` (code review). Pick the type that matches each task's intent.\n\n`context` carries shared background prepended to every subagent's prompt \u2014 put the shared contract, conventions, and coordination rules here.\n\nEach task in `tasks[]` must be self-contained:\n- `role`: specialist type for this sub-task (e.g. coder, reviewer, researcher)\n- `assignment`: exact target (files, symbols, subsystem) + what to do + acceptance criteria\n- `description`: short label for the UI\n\nEach subagent runs in an isolated session and returns its result via the `yield` tool. Subagents skip formatters, linters, and project-wide tests \u2014 the parent runs shared proof once after all results return.\n</task-contract>\n\n<structure>\nDecompose first, then batch the independent leaves:\n\n    task({\n      subagent_type: \"coder\",\n      context: \"# Goal\nImplement feature X across the codebase\n# Constraints\nFollow existing patterns...\n# Contract\nReturn findings as structured data...\",\n      tasks: [\n        { role: \"coder\", assignment: \"# Target\nsrc/auth/login.ts\n# Change\nAdd rate limiting to login endpoint\n# Acceptance\nRate limiter works, tests pass\", description: \"Login rate limiting\" },\n        { role: \"coder\", assignment: \"# Target\nsrc/auth/signup.ts\n# Change\nAdd input validation\n# Acceptance\nValidation blocks invalid emails\", description: \"Signup validation\" },\n      ]\n    })\n\nPrefer one wide batch over serial calls when work items do not share files. If tasks overlap, have agents coordinate before editing.\n</structure>\n\n<patterns>\n- **Adversarial verify** \u2014 dispatch skeptical reviewers with distinct targets, then keep only findings you can verify against source.\n- **Perspective-diverse review** \u2014 use separate correctness, security, performance roles instead of identical reviewers.\n- **Completeness critic** \u2014 after the first batch, dispatch one read-only critic that asks what was missed.\n- **No silent caps** \u2014 if you bound coverage (top-N, sampling), state what was dropped and why.\n- **Parent owns closure** \u2014 subagents return evidence; the parent reads it, resolves contradictions, runs proof, and makes the final decision.\n</patterns>\n\n<execution>\n- **You MUST call the `task` tool** \u2014 this is the defining action of a workflowz request. A response that only does inline read/glob/edit without dispatching sub-agents is a failure.\n- Capture multi-phase workflow state in the visible todo system when available.\n- Batch independent subagents in one `task` call.\n- Give every subagent a narrow target, explicit non-goals, and a concrete return packet.\n- After fan-out returns, read the results, patch or decide, and run the shared gate.\n- Keep going until the task is closed \u2014 returned fan-out is a step, not a stopping point.\n</execution>\n</workflow-notice>";
+/**
+ * 构建工作流 steering 通知：基础通知 + 可选的已注册工作流列表。
+ * 无工作流时退化为纯基础通知（向后兼容）。
+ */
+export declare function buildWorkflowNotice(workflows?: Array<{
+    name: string;
+    description: string;
+}>): string;

package/dist/core/workflow.js

@@ -10,11 +10,17 @@
  *  - 批量模式：`{ subagent_type, context, tasks: [{ prompt, description? }] }`
  *  - 单任务模式：`{ subagent_type?, prompt, description? }`
  */
-// 检测：小写关键词，两侧为空白或字符串边界。非全局，`.test` 无状态。
-const WORKFLOW_WORD = /(?<!\S)workflowz(?!\S)/;
+// 检测：小写关键词，两侧不得是 ASCII 词/路径字符（字母、数字、_、.、/、-）。
+// 用 [\w./-] 而非 \S 做边界，使 CJK 字符和中文标点也能当边界——
+// 中文无词间空格，用 \S 会拒绝「请workflowz」「workflowz。」等合法写法。
+// 仍拒绝 reworkflowz / workflowzed / workflowz.test.ts 等。
+const WORKFLOW_WORD = /(?<![\w./-])workflowz(?![\w./-])/;
 /**
- * 判断 `text` 是否在 prose 中包含独立关键词 "workflowz"
- * （小写、空白分隔）——不在代码块、行内代码或路径中。
+ * 判断 `text` 是否在 prose 中包含独立关键词 "workflowz"。
+ *
+ * 边界为「非 ASCII 词/路径字符」，因此 CJK 字符和中文标点也算合法边界
+ * （中文无词间空格）；但仍拒绝 workflowzed / reworkflowz / workflowz.test.ts
+ * 等拉丁词续或路径内嵌形式。
  *
  * 简化版 prose 检测：移除 ``` 代码块和 `行内代码` 后再匹配。
  */
@@ -31,10 +37,10 @@ export function containsWorkflow(text) {
  * 适配 c0de-agent 的 task 工具 schema（subagent_type + context + tasks[]）。
  */
 export const WORKFLOW_NOTICE = `<workflow-notice>
-The user's message contains the **workflowz** keyword: drive this task as a deterministic multi-subagent workflow. Use the \`task\` tool for batched fan-out — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.
+The user's message contains the **workflowz** keyword: you MUST drive this task as a deterministic multi-subagent workflow using the \`task\` tool for batched fan-out. This is not optional — the keyword signals the user explicitly wants parallel sub-agent decomposition, not inline work. This overrides any default tendency to do the whole task inline.
 
 <when>
-Worth it when the task benefits from decomposition + parallel coverage, or from independent/adversarial cross-checking. For a quick lookup or single edit, just do it directly — don't spin up agents. Scout inline first (list the files, scope the diff, find the call sites) to discover the work list, then fan out over it. Common shapes:
+The user typed workflowz intentionally — they want fan-out. You may do a brief inline scout (1-2 tool calls to list files/scope the work), but your NEXT action after scouting MUST be a \`task\` tool call to fan out. Do NOT spend the entire turn reading files inline — that defeats the purpose. Common shapes:
 - **Understand** — parallel readers over subsystems → structured map.
 - **Design** — independent approaches → scored synthesis.
 - **Review** — split dimensions → find per dimension → adversarially verify each finding.
@@ -49,8 +55,8 @@ Call \`task\` once per independent fan-out batch using the batch form:
       subagent_type: "coder",
       context: "shared background all subagents need",
       tasks: [
-        { prompt: "specific assignment for agent 1", description: "short label" },
-        { prompt: "specific assignment for agent 2", description: "short label" },
+        { role: "coder", assignment: "specific assignment for agent 1", description: "short label" },
+        { role: "reviewer", assignment: "specific assignment for agent 2", description: "short label" },
       ]
     })
 
@@ -59,7 +65,8 @@ Available subagent types: \`general\` (full tools, recursive), \`coder\` (implem
 \`context\` carries shared background prepended to every subagent's prompt — put the shared contract, conventions, and coordination rules here.
 
 Each task in \`tasks[]\` must be self-contained:
-- \`prompt\`: exact target (files, symbols, subsystem) + what to do + acceptance criteria
+- \`role\`: specialist type for this sub-task (e.g. coder, reviewer, researcher)
+- \`assignment\`: exact target (files, symbols, subsystem) + what to do + acceptance criteria
 - \`description\`: short label for the UI
 
 Each subagent runs in an isolated session and returns its result via the \`yield\` tool. Subagents skip formatters, linters, and project-wide tests — the parent runs shared proof once after all results return.
@@ -70,10 +77,10 @@ Decompose first, then batch the independent leaves:
 
     task({
       subagent_type: "coder",
-      context: "# Goal\\nImplement feature X across the codebase\\n# Constraints\\nFollow existing patterns...\\n# Contract\\nReturn findings as structured data...",
+      context: "# Goal\nImplement feature X across the codebase\n# Constraints\nFollow existing patterns...\n# Contract\nReturn findings as structured data...",
       tasks: [
-        { prompt: "# Target\\nsrc/auth/login.ts\\n# Change\\nAdd rate limiting to login endpoint\\n# Acceptance\\nRate limiter works, tests pass", description: "Login rate limiting" },
-        { prompt: "# Target\\nsrc/auth/signup.ts\\n# Change\\nAdd input validation\\n# Acceptance\\nValidation blocks invalid emails", description: "Signup validation" },
+        { role: "coder", assignment: "# Target\nsrc/auth/login.ts\n# Change\nAdd rate limiting to login endpoint\n# Acceptance\nRate limiter works, tests pass", description: "Login rate limiting" },
+        { role: "coder", assignment: "# Target\nsrc/auth/signup.ts\n# Change\nAdd input validation\n# Acceptance\nValidation blocks invalid emails", description: "Signup validation" },
       ]
     })
 
@@ -89,6 +96,7 @@ Prefer one wide batch over serial calls when work items do not share files. If t
 </patterns>
 
 <execution>
+- **You MUST call the \`task\` tool** — this is the defining action of a workflowz request. A response that only does inline read/glob/edit without dispatching sub-agents is a failure.
 - Capture multi-phase workflow state in the visible todo system when available.
 - Batch independent subagents in one \`task\` call.
 - Give every subagent a narrow target, explicit non-goals, and a concrete return packet.
@@ -96,3 +104,17 @@ Prefer one wide batch over serial calls when work items do not share files. If t
 - Keep going until the task is closed — returned fan-out is a step, not a stopping point.
 </execution>
 </workflow-notice>`;
+/**
+ * 构建工作流 steering 通知：基础通知 + 可选的已注册工作流列表。
+ * 无工作流时退化为纯基础通知（向后兼容）。
+ */
+export function buildWorkflowNotice(workflows) {
+    const registeredSection = workflows && workflows.length > 0
+        ? `\n<registered-workflows>
+Available workflow templates you can invoke with the task tool's workflow parameter:
+${workflows.map((w) => `- ${w.name}: ${w.description}`).join('\n')}
+If none fit, orchestrate inline using runSubagent fan-out as described below.
+</registered-workflows>`
+        : '';
+    return WORKFLOW_NOTICE + registeredSection;
+}

package/dist/core/workflows/builtins.d.ts

@@ -0,0 +1,7 @@
+import type { WorkflowEntry } from './types.js';
+/**
+ * 构建全部内置工作流条目（动态导入源码字符串）。幂等、内部缓存。
+ */
+declare function createBuiltinWorkflows(): Promise<WorkflowEntry[]>;
+declare const BUILTIN_WORKFLOWS: WorkflowEntry[];
+export { BUILTIN_WORKFLOWS, createBuiltinWorkflows };

package/dist/core/workflows/builtins.js

@@ -0,0 +1,192 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+// ── security-audit ──
+const SECURITY_AUDIT_SOURCE = `export const meta = {
+  name: 'security-audit',
+  description: '并行安全审计：按目录拆分扫描 → 独立审查员交叉验证 → 汇总报告',
+  argsHint: '[扫描目标描述]',
+  phases: ['scan', 'verify', 'report'],
+}
+
+export default async function workflow(ctx) {
+  const { runSubagents, utils, progress, project } = ctx
+
+  progress('拆分代码库为模块...')
+  const modules = await utils.splitByDirectory(project.rootDir, { depth: 2 })
+
+  progress(\`并行扫描 \${modules.length} 个模块...\`, { phase: 'scan' })
+  const scans = await runSubagents('researcher', modules.map((m) => ({
+    assignment: \`你是安全扫描专家。扫描目录 \${m.path} 下的代码，检查以下安全风险：
+- SQL 注入风险
+- 硬编码密钥 / 密码 / Token
+- 权限绕过模式
+- XSS / CSRF 风险
+- 不安全的依赖使用
+
+文件列表：\${m.files.slice(0, 50).join(', ')}
+
+返回 JSON：{ findings: [{ severity: 'critical|warning|info', file, line, issue, evidence }] }\`,
+    description: \`扫描 \${m.name}\`,
+  })))
+
+  const allFindings = scans
+    .filter((r) => r.ok)
+    .flatMap((r) => { try { return JSON.parse(r.output).findings ?? [] } catch { return [] } })
+
+  progress(\`交叉验证 \${allFindings.length} 个发现...\`, { phase: 'verify' })
+  const verified = await runSubagents('reviewer', allFindings.map((f) => ({
+    assignment: \`对抗审查以下安全发现，判断是否为真实问题还是误报：
+\${JSON.stringify(f, null, 2)}
+
+返回 JSON：{ confirmed: boolean, reason: string, adjustedSeverity?: 'critical|warning|info' }\`,
+    description: '验证发现',
+  })))
+
+  const confirmed = verified
+    .filter((r) => r.ok)
+    .map((r) => { try { return JSON.parse(r.output) } catch { return null } })
+    .filter((v) => v?.confirmed)
+
+  progress('生成报告...', { phase: 'report' })
+  const summary = \`扫描 \${modules.length} 个模块，发现 \${allFindings.length} 个候选问题，\${confirmed.length} 个经交叉验证确认。\`
+
+  return { output: summary, data: { confirmed, totalCandidates: allFindings.length } }
+}`;
+// ── code-review ──
+const CODE_REVIEW_SOURCE = `export const meta = {
+  name: 'code-review',
+  description: '多维度代码审查：correctness/security/performance/maintainability 各派独立 reviewer',
+  argsHint: '[审查目标路径]',
+  phases: ['review', 'merge'],
+}
+
+export default async function workflow(ctx) {
+  const { runSubagents, progress, project, args } = ctx
+  const target = args || project.rootDir
+
+  const dimensions = ['correctness', 'security', 'performance', 'maintainability']
+
+  progress(\`并行 \${dimensions.length} 个维度审查...\`, { phase: 'review' })
+  const reviews = await runSubagents('reviewer', dimensions.map((dim) => ({
+    assignment: \`你是 \${dim} 维度的代码审查专家。审查 \${target} 下的代码。
+
+关注点：
+\${dim === 'correctness' ? '- 逻辑正确性、边界条件、错误处理' : ''}
+\${dim === 'security' ? '- 安全漏洞、输入验证、权限控制' : ''}
+\${dim === 'performance' ? '- 性能瓶颈、不必要计算、内存泄漏' : ''}
+\${dim === 'maintainability' ? '- 代码可读性、重复代码、命名规范' : ''}
+
+返回 JSON：{ findings: [{ severity: 'critical|warning|info', file, line, issue, suggestion }] }\`,
+    description: \`\${dim} 审查\`,
+    role: dim,
+  })))
+
+  const allFindings = reviews
+    .filter((r) => r.ok)
+    .flatMap((r) => { try { return JSON.parse(r.output).findings ?? [] } catch { return [] } })
+
+  progress('合并去重并生成报告...', { phase: 'merge' })
+  const seen = new Set()
+  const deduped = allFindings.filter((f) => {
+    const key = \`\${f.file}:\${f.line}:\${f.issue}\`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+
+  const critical = deduped.filter((f) => f.severity === 'critical').length
+  const warning = deduped.filter((f) => f.severity === 'warning').length
+  const info = deduped.filter((f) => f.severity === 'info').length
+
+  return {
+    output: \`审查完成：\${critical} critical, \${warning} warning, \${info} info（共 \${deduped.length} 条）\`,
+    data: { findings: deduped, summary: { critical, warning, info, total: deduped.length } },
+  }
+}`;
+// ── migration-check ──
+const MIGRATION_CHECK_SOURCE = `export const meta = {
+  name: 'migration-check',
+  description: '迁移影响检查：分析变更的 breaking changes / deprecated / new features',
+  argsHint: '[base-branch或commit]',
+  phases: ['diff', 'analyze', 'report'],
+}
+
+export default async function workflow(ctx) {
+  const { runSubagents, progress, project, args } = ctx
+  const baseRef = args || 'HEAD~1'
+
+  progress(\`分析 \${baseRef} 到当前版本的变更...\`, { phase: 'diff' })
+
+  const categories = ['breaking-changes', 'deprecated', 'new-features']
+
+  progress(\`并行分析 \${categories.length} 个类别...\`, { phase: 'analyze' })
+  const analyses = await runSubagents('researcher', categories.map((cat) => ({
+    assignment: \`你是代码迁移分析专家。分析项目 \${project.rootDir} 从 \${baseRef} 到当前的变更，
+聚焦 \${cat === 'breaking-changes' ? '破坏性变更（API 签名变更、删除、行为变更）' : cat === 'deprecated' ? '已废弃的功能和 API' : '新增功能和特性'}。
+
+返回 JSON：{ items: [{ category: '\${cat}', description, files, impact: 'high|medium|low' }] }\`,
+    description: \`\${cat} 分析\`,
+    role: cat,
+  })))
+
+  const allItems = analyses
+    .filter((r) => r.ok)
+    .flatMap((r) => { try { return JSON.parse(r.output).items ?? [] } catch { return [] } })
+
+  progress('生成迁移报告...', { phase: 'report' })
+  const high = allItems.filter((i) => i.impact === 'high').length
+  const medium = allItems.filter((i) => i.impact === 'medium').length
+  const low = allItems.filter((i) => i.impact === 'low').length
+
+  return {
+    output: \`迁移检查完成：\${allItems.length} 个变更项（\${high} high, \${medium} medium, \${low} low）\`,
+    data: { items: allItems, summary: { high, medium, low, total: allItems.length } },
+  }
+}`;
+// ── factory：源码字符串 → WorkflowEntry（保证 show === run）──
+/**
+ * 把内置工作流的源码字符串编译为 WorkflowEntry：写入临时 .js → dynamic import →
+ * 取出 meta 与 default。这样 /workflow show 展示的源码就是实际执行的代码，
+ * 杜绝「源码字符串」与「TS 函数」两份副本各自漂移的维护陷阱。
+ */
+async function sourceToEntry(source) {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'wf-builtin-'));
+    const tmpFile = join(tmpDir, 'builtin.js');
+    writeFileSync(tmpFile, source, 'utf-8');
+    try {
+        const mod = (await import(pathToFileURL(tmpFile).href));
+        if (!mod.meta || typeof mod.default !== 'function') {
+            throw new Error('builtin workflow source missing `export const meta` or default export');
+        }
+        return {
+            meta: mod.meta,
+            source: 'builtin',
+            execute: mod.default,
+            sourceCode: source,
+        };
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/** 缓存：内置工作流只动态导入一次。 */
+let _builtinWorkflowsCache;
+/**
+ * 构建全部内置工作流条目（动态导入源码字符串）。幂等、内部缓存。
+ */
+async function createBuiltinWorkflows() {
+    if (_builtinWorkflowsCache)
+        return _builtinWorkflowsCache;
+    _builtinWorkflowsCache = await Promise.all([
+        sourceToEntry(SECURITY_AUDIT_SOURCE),
+        sourceToEntry(CODE_REVIEW_SOURCE),
+        sourceToEntry(MIGRATION_CHECK_SOURCE),
+    ]);
+    return _builtinWorkflowsCache;
+}
+// 顶层 await：模块加载时一次性解析，使同步消费方（注册表惰性 getter、slash 回退、
+// 单元测试）无需改造即可拿到已解析的内置条目；解析失败则 fail-fast。
+const BUILTIN_WORKFLOWS = await createBuiltinWorkflows();
+export { BUILTIN_WORKFLOWS, createBuiltinWorkflows };

package/dist/core/workflows/context.d.ts

@@ -0,0 +1,17 @@
+import type { SubAgentRequest, SubAgentResult } from '../../shared/types/tool.js';
+import type { AgentDependencies, AgentState } from '../types.js';
+import type { WorkflowContext } from './types.js';
+/** buildWorkflowContext 的参数。 */
+type BuildContextOpts = {
+    deps: AgentDependencies;
+    parent: AgentState;
+    args: string;
+    onProgress: (message: string, detail?: unknown) => void;
+    /** 项目名（从 ProjectInfo 传入）。 */
+    projectName?: string;
+    /** 测试注入：覆盖内部 runSubAgent 调用。生产环境省略，走 deps 关联的 loop.runSubAgent。 */
+    runSubAgentFn?: (request: SubAgentRequest) => Promise<SubAgentResult>;
+};
+/** 构建 WorkflowContext，注入 runSubagent/utils/progress。 */
+declare function buildWorkflowContext(opts: BuildContextOpts): WorkflowContext;
+export { buildWorkflowContext };