agentworkshop 0.7.27 → 0.7.34

package/server/services/workshop/agents/codex-agent.ts

@@ -20,35 +20,25 @@ import { randomUUID } from 'node:crypto'
 import { join } from 'node:path'
 import { mkdirSync, writeFileSync, existsSync, readFileSync, copyFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import type {
-  AgentEvent,
-  AgentInterface,
-  AgentInfo,
-  AgentRunContext,
-  AgentRunRequest,
-  SupervisionDecision,
-  SupervisionSnapshot,
-} from './agent-interface'
+import type { AgentEvent, AgentInterface, AgentInfo, AgentRunContext, AgentRunRequest } from './agent-interface'
 import type { AgentContextStats } from '../types/task'
 import { registerHarnessProcess, bindHarnessProcess, markHarnessProcessExit, killHarnessProcess } from './harness-process'
-import { createSessionState, dispatchHostTool } from './host-tool-bridge'
-import {
-  contextPrefix as buildContextPrefix,
-  createRosterCache,
-  extractJsonArray,
-  peerPrompt,
-  supervisePrompt,
-  systemManual,
-  toolArgsPreview,
-  workerPrompt,
-} from './prompt-builder'
+import { peerPrompt, systemManual, toolArgsPreview, workerPrompt } from './prompt-builder'
 import { getHitlRegistry } from './hitl-registry'
 import { harnessSettings } from '../settings'
 import { StdioJsonRpcClient } from './adapters/stdio-jsonrpc'
+import { BaseAgentImpl } from './base-agent'
 import { generateMcpBridgeEnv } from './harness-env'
 
 const log = createLogger('workshop.codex')
 
+/**
+ * 默认回合停滞上限:整轮无任何事件(含推理模型的静默思考期)达到该时长才中止。
+ * 600s 会误杀健康的沉默推理(实测推理档静默 >10 分钟后被打断,任务 FAILED→重试→CANCELED);
+ * 事件到达即刷新计时,真实卡死仍会在该窗口内被发现。
+ */
+const CODEX_TURN_STALL_MS = 1_800_000
+
 export interface CodexAgentConfig {
   /** codex 可执行文件(默认取 harness.codex_command 设置) */
   command?: string
@@ -69,6 +59,12 @@ export interface CodexAgentConfig {
   contextWindow?: number
   /** 压缩阈值(0-1,默认 0.7) */
   compactThreshold?: number
+  /**
+   * 回合停滞上限(ms):整轮无任何事件(推理模型静默思考也不产 delta)达到该时长才中止。
+   * 默认 1800000(30 分钟):codex 0.154 的推理档在负载下可静默思考 >10 分钟,
+   * 600s 会把健康的沉默推理误杀为 CODEX_TURN_STALLED(任务 FAILED→重试→CANCELED)。
+   * 有事件(delta/status/工具轨迹)即刷新计时,不放大真实卡死的发现延迟。
+   */
   promptTimeoutMs?: number
   superviseTimeoutMs?: number
   systemPromptPrefix?: string
@@ -82,23 +78,16 @@ export interface CodexAgentConfig {
   mcpBridgePath?: string
 }
 
-export class CodexAgentImpl implements AgentInterface {
+export class CodexAgentImpl extends BaseAgentImpl implements AgentInterface {
   private readonly config: CodexAgentConfig
-  private workspace: AgentRunContext['workspace'] | null = null
   private agentInfo: AgentInfo | null = null
-  private readonly toolState = createSessionState()
   private readonly bridgeCtx = {
     identity: { agentId: '', channelId: '', role: 'worker' as 'lead' | 'worker', name: 'agent' },
     state: this.toolState,
     getWorkspace: () => this.workspace,
   }
 
-  private roster = createRosterCache({ selfAgentId: '', listAgents: async () => [] })
-
-  private selfAgentId = ''
-  private agentName = 'agent'
   private agentRole: 'lead' | 'worker' = 'worker'
-  private channelId = ''
 
   private client: StdioJsonRpcClient | null = null
   private clientStarting: Promise<void> | null = null
@@ -116,29 +105,21 @@ export class CodexAgentImpl implements AgentInterface {
   private pendingApprovals = new Map<string, { rpcId: string | number, timer: ReturnType<typeof setTimeout> | null }>()
 
   constructor(config: Record<string, unknown> = {}) {
+    super({
+      agentId: typeof config.agentId === 'string' ? config.agentId : '',
+      name: typeof config.name === 'string' ? config.name : undefined,
+      role: config.role === 'lead' ? 'lead' : 'worker',
+      channelId: typeof config.channelId === 'string' ? config.channelId : '',
+    })
     this.config = config as CodexAgentConfig
-    this.selfAgentId = this.config.agentId ?? ''
-    this.agentName = this.config.name ?? 'agent'
-    this.agentRole = this.config.role ?? 'worker'
-    this.channelId = this.config.channelId ?? ''
-    this.refreshIdentity()
   }
 
-  private refreshIdentity(): void {
-    this.bridgeCtx.identity = { agentId: this.selfAgentId, channelId: this.channelId, role: this.agentRole, name: this.agentName }
-    this.roster = createRosterCache({
-      selfAgentId: this.selfAgentId,
-      listAgents: async () => this.workspace?.listAgents() ?? [],
-    })
+  protected get harnessId(): string {
+    return 'codex'
   }
 
-  async init(input: { agent: AgentInfo, channelId: string }): Promise<void> {
-    this.agentInfo = input.agent
-    this.channelId = input.channelId
-    this.agentName = input.agent.name
-    this.agentRole = input.agent.role
-    this.selfAgentId = input.agent.id
-    this.refreshIdentity()
+  protected configRecord(): Record<string, unknown> {
+    return this.config
   }
 
   async dispose(): Promise<void> {
@@ -173,10 +154,6 @@ export class CodexAgentImpl implements AgentInterface {
     this.client?.reconcile()
   }
 
-  dispatchHostTool(toolName: string, args: Record<string, unknown>): Promise<{ text: string, isError?: boolean }> {
-    return dispatchHostTool(this.bridgeCtx, { toolName, arguments: args })
-  }
-
   getContextStats(): AgentContextStats | null {
     if (!this.lastUsage) return null
     const window = this.config.contextWindow ?? null
@@ -249,55 +226,7 @@ export class CodexAgentImpl implements AgentInterface {
     }
   }
 
-  // ===== run / supervise =====
-
-  async* run(request: AgentRunRequest, ctx: AgentRunContext): AsyncIterable<AgentEvent> {
-    const kind = request.message.metadata?.['x-aw-task-kind']
-    if (kind === 'assign' && ctx.role === 'worker') {
-      yield* this.workerRun(request, ctx)
-      return
-    }
-    if (!kind && (request.fromAgentId || request.message.metadata?.['x-aw-from-label'])) {
-      yield* this.peerMessageRun(request, ctx)
-      return
-    }
-  }
-
-  private supervising = false
-
-  async supervise(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<SupervisionDecision[]> {
-    await this.ensureClient(ctx)
-    if (!this.client || !this.threadId) return []
-    if (this.supervising) return []
-    const prompt = supervisePrompt({
-      snapshot,
-      agentName: this.agentName,
-      channelId: this.channelId,
-      ctxPrefix: await this.contextPrefix(),
-      manual: systemManual(),
-      memory: ctx.memory,
-    })
-    this.supervising = true
-    try {
-      const events = await this.collectTurn(prompt, this.config.superviseTimeoutMs ?? 150_000, opts?.signal)
-      let text = ''
-      for (const e of events) {
-        if (e.kind === 'artifact') {
-          text += e.artifact.parts.map(p => 'text' in p ? p.text : '').join('')
-        }
-      }
-      const parsed = extractJsonArray(text)
-      return parsed && parsed.length > 0 ? parsed as SupervisionDecision[] : []
-    }
-    catch {
-      return []
-    }
-    finally {
-      this.supervising = false
-    }
-  }
-
-  private async* workerRun(request: AgentRunRequest, ctx: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown> {
+  protected async* workerTurn(request: AgentRunRequest, ctx: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown> {
     const taskId = request.taskId ?? (request.message.metadata?.['x-aw-task-id'] as string | undefined)
     if (!taskId) return
     this.toolState.currentTaskId = taskId
@@ -319,14 +248,14 @@ export class CodexAgentImpl implements AgentInterface {
         ctxPrefix: await this.contextPrefix(),
         manual: systemManual(),
       })
-      yield* this.streamTurn(prompt, taskId, this.config.promptTimeoutMs ?? 600_000, ctx.signal)
+      yield* this.streamTurn(prompt, taskId, this.config.promptTimeoutMs ?? CODEX_TURN_STALL_MS, ctx.signal)
     }
     finally {
       this.toolState.currentTaskId = null
     }
   }
 
-  private async* peerMessageRun(request: AgentRunRequest, ctx: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown> {
+  protected async* peerTurn(request: AgentRunRequest, ctx: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown> {
     await this.ensureClient(ctx)
     const msg = request.message
     const fromId = request.fromAgentId
@@ -359,16 +288,7 @@ export class CodexAgentImpl implements AgentInterface {
       fromChannel: typeof msg.metadata?.['x-aw-from-channel'] === 'string' ? String(msg.metadata['x-aw-from-channel']) : '',
       msgText,
     })
-    yield* this.streamTurn(prompt, undefined, this.config.promptTimeoutMs ?? 600_000, ctx.signal)
-  }
-
-  private async contextPrefix(): Promise<string> {
-    return buildContextPrefix({
-      scenarioPrompt: this.config.scenarioPrompt,
-      systemPromptPrefix: this.config.systemPromptPrefix,
-      agentId: this.selfAgentId,
-      roster: await this.roster.roster(),
-    })
+    yield* this.streamTurn(prompt, undefined, this.config.promptTimeoutMs ?? CODEX_TURN_STALL_MS, ctx.signal)
   }
 
   // ===== 回合执行 =====
@@ -584,7 +504,7 @@ export class CodexAgentImpl implements AgentInterface {
   }
 
   /** supervise 用:收齐整个回合的事件流(supervise 决策解析在调用方) */
-  private async collectTurn(prompt: string, timeoutMs: number, signal?: AbortSignal): Promise<AgentEvent[]> {
+  protected async collectTurnEvents(prompt: string, timeoutMs: number, signal?: AbortSignal): Promise<AgentEvent[]> {
     const events: AgentEvent[] = []
     for await (const e of this.streamTurn(prompt, undefined, timeoutMs, signal)) {
       events.push(e)
@@ -760,12 +680,17 @@ export class CodexAgentImpl implements AgentInterface {
    * per-agent CODEX_HOME config.toml:注册 MCP 桥(required=true,桥挂了宁可失败)。
    * 已有 config.toml(从全局目录种子化复制)→ 追加本段(保留用户的 provider/model
    * 配置,自定义网关/密钥不丢失);全新目录 → 独立写入。
+   *
+   * 无条件种子化(不再仅当 effort 配置时才挂桥):MCP 桥是 codex worker 的 host
+   * 工具面(complete_task/ops_log/…)唯一入口;不挂桥的实例模型只能拿自带 shell
+   * 乱翻工作区,永远调不到 complete_task → 任务停滞被看门狗回收
+   * (实测 codex 任务终态 CANCELED、交付物却只落在频道消息里的根因)。
    */
   private writeCodexHomeConfig(): void {
     let home = this.config.codexHome
-    if (!home && this.config.effort) {
-      // effort 需要配置文件面(model_reasoning_effort):自动种子化 per-agent CODEX_HOME
-      // (拷贝全局凭据/网关配置,保登录与自定义 provider;追加 MCP 段 + 顶部 effort)
+    if (!home) {
+      // 自动种子化 per-agent CODEX_HOME(拷贝全局凭据/网关配置,保登录与自定义
+      // provider;追加 MCP 段 + 顶部 effort)
       home = join(tmpdir(), `aw-codex-${this.selfAgentId.slice(0, 8)}`)
       this.config.codexHome = home
       for (const f of ['auth.json', 'config.toml', 'cc-switch-model-catalog.json']) {
@@ -776,7 +701,6 @@ export class CodexAgentImpl implements AgentInterface {
         catch { /* 单文件缺失忽略 */ }
       }
     }
-    if (!home) return
     try {
       mkdirSync(home, { recursive: true })
       const configFile = join(home, 'config.toml')

package/server/services/workshop/agents/copilot-agent.ts

@@ -0,0 +1,136 @@
+/**
+ * CopilotAgentImpl — GitHub Copilot CLI(`-p/--output-format json`)的 AgentInterface 实现。
+ *
+ * 进程模型:每回合一个 `copilot` 子进程(prompt 经 stdin 管道投递,--output-format json
+ * 输出 JSONL)。鉴权走 token 链(COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN,
+ * 服务端无需浏览器);配置经 COPILOT_HOME 按 agent 隔离(<root>/.AgentWorkShop/
+ * harness-config/copilot/<agentId>/,内种子 mcp-config.json 挂 aw 桥)。
+ *
+ *  - steer:一次性进程模型 → 恒 'deferred'
+ *  - HITL:无程序化审批面(--allow-tool 白名单制)。默认仅授权 aw 桥工具
+ *    (--allow-tool aw),native shell/write 保持未授权;config.copilotAllowTools 可扩
+ *  - 事件帧:JSONL 逐行(行级 schema 以探针为准;解析器对未知 type 忽略并计数)
+ */
+import { isAbsolute, join, resolve } from 'node:path'
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs'
+import { createLogger } from '../logger'
+import { harnessSettings } from '../settings'
+import {
+  OneShotCliAgentImpl,
+  type OneShotEngineSpec,
+} from './adapters/one-shot-cli-agent'
+import { resolveBridgePath } from './harness-env'
+import { toolArgsPreview } from './prompt-builder'
+
+const log = createLogger('workshop.copilot')
+
+/** agentId 白名单化(仅作为路径段使用;杜绝 ../ 与分隔符注入) */
+function safeId(agentId: unknown): string {
+  const id = String(agentId ?? 'default').replace(/[^A-Za-z0-9_-]/g, '')
+  return id !== '' ? id : 'default'
+}
+
+/** COPILOT_HOME 解析:显式 config 路径须为绝对路径且不含 .. 段;否则落配置根白名单目录 */
+function resolveCopilotHome(config: Record<string, unknown>): string {
+  const raw = typeof config.copilotHome === 'string' ? config.copilotHome.trim() : ''
+  if (raw !== '') {
+    if (raw.split(/[\\/]/).includes('..') || !isAbsolute(raw)) {
+      throw new Error(`copilotHome 必须是不含 .. 的绝对路径: ${JSON.stringify(raw.slice(0, 80))}`)
+    }
+    return resolve(raw)
+  }
+  const root = process.env.AW_PACKAGE_ROOT ?? process.cwd()
+  return join(root, '.AgentWorkShop', 'harness-config', 'copilot', safeId(config.agentId))
+}
+
+/** 确保 <copilotHome>/mcp-config.json 含 aw 桥(merge-only) */
+export function ensureCopilotMcpConfig(home: string, bridgePath: string): void {
+  mkdirSync(home, { recursive: true })
+  const file = join(home, 'mcp-config.json')
+  let doc: Record<string, unknown> = {}
+  try {
+    if (existsSync(file)) doc = JSON.parse(readFileSync(file, 'utf-8')) as Record<string, unknown>
+  }
+  catch (err) {
+    log.warn(`copilot mcp-config.json 解析失败,保留原文件: ${err instanceof Error ? err.message : String(err)}`)
+    return
+  }
+  const servers = (doc.mcpServers && typeof doc.mcpServers === 'object' ? doc.mcpServers : {}) as Record<string, unknown>
+  const existing = servers.aw as Record<string, unknown> | undefined
+  if (existing?.command && existing?.args) return
+  servers.aw = { type: 'stdio', command: process.execPath, args: [bridgePath] }
+  doc.mcpServers = servers
+  writeFileSync(file, JSON.stringify(doc, null, 2), 'utf-8')
+}
+
+/** 从行 JSON 中尽力抽取文本增量/工具名(官方行级 schema 未稳定,宽容解析) */
+function extractAssistantText(json: Record<string, unknown>): string {
+  const msg = (json.message ?? {}) as Record<string, unknown>
+  const content = (json.content ?? msg.content) as unknown
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content.map((p) => {
+      const part = p as Record<string, unknown>
+      if (typeof part?.text === 'string') return part.text
+      return ''
+    }).join('')
+  }
+  if (typeof json.text === 'string') return json.text
+  if (typeof msg.text === 'string') return msg.text
+  return ''
+}
+
+const spec: OneShotEngineSpec = {
+  harnessId: 'copilot',
+  resolveCommand: config => (typeof config.command === 'string' && config.command.trim() !== '' ? config.command.trim() : harnessSettings().copilot_command),
+  buildArgs: ({ config }) => {
+    const args = ['--output-format', 'json', '--no-ask-user', '--allow-tool', 'aw']
+    if (typeof config.model === 'string' && config.model.trim() !== '') args.push('--model', config.model.trim())
+    const extra = Array.isArray(config.copilotAllowTools) ? config.copilotAllowTools as unknown[] : []
+    for (const t of extra) {
+      if (typeof t === 'string' && t.trim() !== '') args.push('--allow-tool', t.trim())
+    }
+    return args
+  },
+  engineEnv: (config) => {
+    let home: string
+    try {
+      home = resolveCopilotHome(config)
+    }
+    catch (err) {
+      log.warn(`copilotHome 非法,回退默认目录: ${err instanceof Error ? err.message : String(err)}`)
+      home = join(process.env.AW_PACKAGE_ROOT ?? process.cwd(), '.AgentWorkShop', 'harness-config', 'copilot', safeId(config.agentId))
+    }
+    return {
+      COPILOT_HOME: home,
+      ...(typeof config.apiKey === 'string' && config.apiKey !== '' ? { COPILOT_GITHUB_TOKEN: config.apiKey } : {}),
+    }
+  },
+  prepare: (config) => {
+    ensureCopilotMcpConfig(resolveCopilotHome(config), resolveBridgePath(typeof config.mcpBridgePath === 'string' ? config.mcpBridgePath : undefined))
+  },
+  mapLine: (json, _raw, _state, sink) => {
+    const type = String(json.type ?? '')
+    if (type === 'assistant' || type === 'message' || (!type && (json.message || json.content))) {
+      const text = extractAssistantText(json)
+      if (text) sink.delta(text)
+      return
+    }
+    if (type === 'tool_call' || type === 'tool_use' || type === 'tool') {
+      const tool = (json.tool_call ?? json.tool ?? json) as Record<string, unknown>
+      sink.status(`🔧 ${String(tool.name ?? tool.tool_name ?? type)}${toolArgsPreview(tool.input ?? tool.arguments ?? tool.args)}`)
+      return
+    }
+    if (type === 'result' || type === 'done') {
+      const usage = (json.usage ?? json.token_usage ?? {}) as Record<string, unknown>
+      const input = Number(usage.input_tokens ?? usage.input ?? usage.total_tokens)
+      if (Number.isFinite(input) && input > 0) sink.usage({ inputTokens: input })
+    }
+  },
+}
+
+export class CopilotAgentImpl extends OneShotCliAgentImpl {
+  constructor(config: Record<string, unknown>) {
+    super(config, spec)
+  }
+}

package/server/services/workshop/agents/crush-agent.ts

@@ -0,0 +1,107 @@
+/**
+ * CrushAgentImpl — Charm Crush(`crush run --format json`)的 AgentInterface 实现。
+ *
+ * 进程模型:每回合一个 `crush run` 子进程(prompt 作为单参数投递,--format json 输出
+ * JSONL 事件,opencode 血统):step_start / text / step_finish(含 cost/tokens)。
+ *
+ *  - steer:一次性进程模型 → 恒 'deferred'
+ *  - HITL:run 模式无程序化审批面(如后续版本输出权限事件再升级)
+ *  - 工具/模型:crush 配置解析序 ./.crushrc → ./crushrc → ~/.config/crush/crushrc;
+ *    首次回合 merge-only 写 <workspace>/.crushrc(mcp add aw 桥 + zhipu openai-compat
+ *    provider,api_key 引用 AW_CRUSH_API_KEY 环境变量,不落明文进配置文件)
+ *  - 鉴权:config.apiKey → 进程 env AW_CRUSH_API_KEY(经 crushrc $() 引用) +
+ *    OPENAI_API_KEY 兜底
+ */
+import { existsSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createLogger } from '../logger'
+import { harnessSettings } from '../settings'
+import {
+  OneShotCliAgentImpl,
+  type OneShotEngineSpec,
+} from './adapters/one-shot-cli-agent'
+import { resolveBridgePath } from './harness-env'
+import { toolArgsPreview } from './prompt-builder'
+
+const log = createLogger('workshop.crush')
+
+/** crushrc 的 bash 方言内变量引用固定为 AW_CRUSH_API_KEY(凭据不落盘) */
+const CRUSH_KEY_ENV = 'AW_CRUSH_API_KEY'
+
+/**
+ * 确保 <cwd>/.crushrc 存在且含 aw 桥与 zhipu provider(仅当文件缺失时整份生成;
+ * 已有用户 crushrc 时不动 —— 用户自行按官方文档接入)。
+ */
+export function ensureCrushConfig(cwd: string, bridgePath: string, baseUrl: string): void {
+  const file = join(cwd, '.crushrc')
+  if (existsSync(file)) return
+  // crushrc 是 bash 方言:路径统一正斜杠,避免反斜杠被转义吞掉
+  const nodePath = process.execPath.replace(/\\/g, '/')
+  const bridgeForward = bridgePath.replace(/\\/g, '/')
+  const lines = [
+    `# AgentWorkShop 生成(幂等;删除后下次回合重建)。凭据经 ${CRUSH_KEY_ENV} 环境变量注入。`,
+    `mcp add aw --command "${nodePath}" --args "${bridgeForward}" --timeout 30`,
+    `provider add zhipu --type openai-compat --base-url ${baseUrl} --api-key "\${${CRUSH_KEY_ENV}}"`,
+    `model add zhipu/glm-5.3-flash`,
+    `model large zhipu/glm-5.3-flash`,
+    '',
+  ]
+  try {
+    writeFileSync(file, lines.join('\n'), 'utf-8')
+  }
+  catch (err) {
+    log.warn(`.crushrc 写入失败(引擎侧将以无桥模式运行): ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
+
+const spec: OneShotEngineSpec = {
+  harnessId: 'crush',
+  resolveCommand: config => (typeof config.command === 'string' && config.command.trim() !== '' ? config.command.trim() : harnessSettings().crush_command),
+  buildArgs: ({ config }) => {
+    // crush v0.92:run 无 --format 旗标(JSON 输出已移除);-q 静默 spinner,输出纯文本
+    const args = ['run', '-q']
+    if (typeof config.model === 'string' && config.model.trim() !== '') args.push('-m', config.model.trim())
+    return args
+  },
+  promptDelivery: 'arg',
+  plainTextStdout: true,
+  engineEnv: (config) => {
+    const key = typeof config.apiKey === 'string' ? config.apiKey : ''
+    return {
+      ...(key !== '' ? { [CRUSH_KEY_ENV]: key, OPENAI_API_KEY: key } : {}),
+    }
+  },
+  prepare: (config) => {
+    const cwd = (typeof config.cwd === 'string' && config.cwd !== '' ? config.cwd : process.cwd())
+    ensureCrushConfig(cwd, resolveBridgePath(typeof config.mcpBridgePath === 'string' ? config.mcpBridgePath : undefined), String(config.providerBaseUrl ?? 'https://open.bigmodel.cn/api/coding/paas/v4'))
+  },
+  mapLine: (json, _raw, _state, sink) => {
+    const type = String(json.type ?? '')
+    if (type === 'step_start' || type === 'step-start') {
+      sink.status('▶ crush step')
+      return
+    }
+    if (type === 'text') {
+      const part = (json.part ?? json) as Record<string, unknown>
+      if (typeof part.text === 'string') sink.delta(part.text)
+      return
+    }
+    if (type === 'tool_use' || type === 'tool_call' || type === 'tool') {
+      const part = (json.part ?? json.tool ?? json) as Record<string, unknown>
+      sink.status(`🔧 ${String(part.tool ?? part.name ?? part.type ?? 'tool')}${toolArgsPreview(part.input ?? part.arguments ?? part.args)}`)
+      return
+    }
+    if (type === 'step_finish' || type === 'step-finish') {
+      const part = (json.part ?? json) as Record<string, unknown>
+      const tokens = (part.tokens ?? {}) as Record<string, unknown>
+      const input = Number(tokens.input ?? tokens.inputTokens ?? tokens.total)
+      if (Number.isFinite(input) && input > 0) sink.usage({ inputTokens: input })
+    }
+  },
+}
+
+export class CrushAgentImpl extends OneShotCliAgentImpl {
+  constructor(config: Record<string, unknown>) {
+    super(config, spec)
+  }
+}

package/server/services/workshop/agents/cursor-agent.ts

@@ -0,0 +1,102 @@
+/**
+ * CursorAgentImpl — Cursor CLI(`cursor-agent -p --output-format stream-json`)的实现。
+ *
+ * 进程模型:每回合一个 `cursor-agent -p` 子进程(prompt 作为单参数投递,经消毒;
+ * --stream-partial-output 提供增量 delta)。帧形(官方 headless 文档,Claude Code 同构):
+ *   {"type":"system","subtype":"init","model":"..."}
+ *   {"type":"assistant","timestamp_ms":..,"message":{"content":[{"text":"..."}]}}
+ *   {"type":"tool_call","subtype":"started"|"completed","tool_call":{...}}
+ *   {"type":"result","duration_ms":..}
+ *
+ *  - steer:一次性进程模型 → 恒 'deferred'
+ *  - HITL:无程序化审批面(--force 二档制)。默认**不带** --force:文件变更只提案不落地
+ *    (与平台写控制哲学一致);config.force=true 显式放开
+ *  - 工具:--mcp-config 指向 .AgentWorkShop/harness-config/cursor/aw-mcp.json(aw 桥);
+ *    agent 身份经进程 env 继承到 MCP 子进程
+ *  - 已知边界:社区报告 print 模式下 MCP 工具偶发不触发(版本相关);鉴权仅
+ *    CURSOR_API_KEY(Cursor 账号侧),无 OpenAI 兼容 provider 面
+ */
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { harnessSettings } from '../settings'
+import {
+  OneShotCliAgentImpl,
+  type OneShotEngineSpec,
+} from './adapters/one-shot-cli-agent'
+import { resolveBridgePath } from './harness-env'
+import { toolArgsPreview } from './prompt-builder'
+
+/** aw 桥 mcp-config 固定路径(无 agent 段:身份走 env 继承,配置可共享) */
+function mcpConfigPath(): string {
+  return join(process.env.AW_PACKAGE_ROOT ?? process.cwd(), '.AgentWorkShop', 'harness-config', 'cursor', 'aw-mcp.json')
+}
+
+export function ensureCursorMcpConfig(bridgePath: string): void {
+  const file = mcpConfigPath()
+  let doc: Record<string, unknown> = {}
+  try {
+    if (existsSync(file)) doc = JSON.parse(readFileSync(file, 'utf-8')) as Record<string, unknown>
+  }
+  catch {
+    doc = {}
+  }
+  const servers = (doc.mcpServers && typeof doc.mcpServers === 'object' ? doc.mcpServers : {}) as Record<string, unknown>
+  const existing = servers.aw as Record<string, unknown> | undefined
+  if (existing?.command && existing?.args) return
+  servers.aw = { command: process.execPath, args: [bridgePath] }
+  doc.mcpServers = servers
+  mkdirSync(join(file, '..'), { recursive: true })
+  writeFileSync(file, JSON.stringify(doc, null, 2), 'utf-8')
+}
+
+const spec: OneShotEngineSpec = {
+  harnessId: 'cursor',
+  resolveCommand: config => (typeof config.command === 'string' && config.command.trim() !== '' ? config.command.trim() : harnessSettings().cursor_command),
+  buildArgs: ({ config }) => {
+    const args = ['-p', '--output-format', 'stream-json', '--stream-partial-output', '--mcp-config', mcpConfigPath()]
+    if (typeof config.model === 'string' && config.model.trim() !== '') args.push('--model', config.model.trim())
+    if (config.force === true) args.push('--force')
+    return args
+  },
+  promptDelivery: 'arg',
+  engineEnv: config => ({
+    ...(typeof config.apiKey === 'string' && config.apiKey !== '' ? { CURSOR_API_KEY: config.apiKey } : {}),
+  }),
+  prepare: () => {
+    ensureCursorMcpConfig(resolveBridgePath())
+  },
+  mapLine: (json, _raw, _state, sink) => {
+    const type = String(json.type ?? '')
+    if (type === 'system' && String(json.subtype ?? '') === 'init') {
+      sink.status(`▶ cursor(${String(json.model ?? 'default')})`)
+      return
+    }
+    if (type === 'assistant') {
+      const msg = (json.message ?? {}) as Record<string, unknown>
+      const content = msg.content ?? json.content
+      if (Array.isArray(content)) {
+        for (const p of content as Array<Record<string, unknown>>) {
+          if (typeof p?.text === 'string' && p.text) sink.delta(p.text)
+        }
+      }
+      else if (typeof content === 'string' && content) sink.delta(content)
+      return
+    }
+    if (type === 'tool_call') {
+      const tool = (json.tool_call ?? {}) as Record<string, unknown>
+      const name = String(tool.name ?? (tool as Record<string, unknown>).tool_name ?? json.tool_name ?? 'tool')
+      const status = String(json.subtype ?? '')
+      sink.status(`🔧 ${name}${status === 'completed' ? ' ✓' : ''}${status !== 'completed' ? toolArgsPreview(tool.input ?? tool.arguments) : ''}`)
+      return
+    }
+    if (type === 'result') {
+      sink.status(`✓ cursor 回合完成(${Number(json.duration_ms ?? 0)}ms)`)
+    }
+  },
+}
+
+export class CursorAgentImpl extends OneShotCliAgentImpl {
+  constructor(config: Record<string, unknown>) {
+    super(config, spec)
+  }
+}