codex-workspace-codegraph-mcp 0.2.0

package/src/feedback.js

@@ -0,0 +1,272 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { FEEDBACK_TIMEOUT_SECONDS, randomToken, readJsonBody, toolText, writeJson, writeText } from './utils.js';
+import { runProcess } from './process.js';
+
+function timingSafeEqualText(left, right) {
+  const a = Buffer.from(String(left || ''));
+  const b = Buffer.from(String(right || ''));
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+function openUrl(url) {
+  const command = process.platform === 'win32' ? 'cmd' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  execFile(command, args, { windowsHide: true }, () => {});
+}
+
+function sanitizeFilename(value) {
+  const base = path.basename(String(value || 'attachment'));
+  return base.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120) || 'attachment';
+}
+
+function publicSession(session) {
+  return {
+    id: session.id,
+    type: session.type,
+    summary: session.summary,
+    details: session.details,
+    status: session.status,
+    created_at: session.createdAt,
+    expires_at: session.expiresAt,
+    validation_command: session.validationCommand,
+    validation_result: session.validationResult,
+  };
+}
+
+export class FeedbackManager {
+  constructor(config, workspace) {
+    this.config = config;
+    this.workspace = workspace;
+    this.sessions = new Map();
+    this.server = null;
+    this.openedBrowser = false;
+    this.storageRoot = path.join(os.homedir(), '.codex-workspace-mcp', 'feedback');
+  }
+
+  async start() {
+    if (this.server) return;
+    await fs.mkdir(this.storageRoot, { recursive: true });
+    this.server = http.createServer((request, response) => this.#handleHttp(request, response).catch((error) => {
+      writeJson(response, error.statusCode || 500, { error: error.message });
+    }));
+    await new Promise((resolve, reject) => {
+      this.server.once('error', reject);
+      this.server.listen(this.config.webPort, this.config.webHost, resolve);
+    });
+    if (!this.config.quiet) console.error(`[feedback] 本地 Web UI: ${this.localUrl}`);
+  }
+
+  get localUrl() {
+    return `http://${this.config.webHost}:${this.config.webPort}/?token=${encodeURIComponent(this.config.accessToken)}`;
+  }
+
+  async close() {
+    for (const session of this.sessions.values()) {
+      if (session.status === 'pending') this.#finish(session, { status: 'server_closed', feedback: '' });
+    }
+    if (this.server) await new Promise((resolve) => this.server.close(resolve));
+    this.server = null;
+  }
+
+  async requestFeedback(input = {}) {
+    return this.#createSession({
+      type: 'feedback',
+      summary: String(input.summary || '请审阅当前工作结果并提供反馈。'),
+      details: String(input.details || ''),
+      validationCommand: input.validation_command ? String(input.validation_command) : null,
+      cwd: String(input.cwd || '.'),
+    });
+  }
+
+  async requestApproval(input = {}) {
+    return this.#createSession({
+      type: 'approval',
+      summary: String(input.summary || '请求批准一个高风险操作'),
+      details: String(input.details || ''),
+      validationCommand: null,
+      cwd: String(input.cwd || '.'),
+    });
+  }
+
+  async #createSession(data) {
+    await this.start();
+    const id = randomToken(18);
+    const now = Date.now();
+    const session = {
+      id,
+      ...data,
+      status: 'pending',
+      createdAt: new Date(now).toISOString(),
+      expiresAt: new Date(now + FEEDBACK_TIMEOUT_SECONDS * 1000).toISOString(),
+      validationResult: null,
+      timer: null,
+      resolve: null,
+    };
+    const promise = new Promise((resolve) => { session.resolve = resolve; });
+    session.timer = setTimeout(() => {
+      this.#finish(session, data.type === 'approval'
+        ? { status: 'timeout', decision: 'reject', feedback: '' }
+        : { status: 'timeout', feedback: '', attachments: [] });
+    }, FEEDBACK_TIMEOUT_SECONDS * 1000);
+    session.timer.unref();
+    this.sessions.set(id, session);
+
+    if (!this.config.quiet) {
+      console.error(`[feedback] 新会话: ${session.summary}`);
+      console.error(`[feedback] ${this.localUrl}`);
+    }
+    if (this.config.openBrowser && !this.openedBrowser) {
+      this.openedBrowser = true;
+      openUrl(this.localUrl);
+    }
+
+    const autoResponse = process.env.CWMCP_FEEDBACK_AUTO_RESPONSE;
+    if (autoResponse !== undefined) {
+      queueMicrotask(() => this.#finish(session, data.type === 'approval'
+        ? { status: 'submitted', decision: 'approve', feedback: autoResponse }
+        : { status: 'submitted', feedback: autoResponse, attachments: [] }));
+    }
+    return promise;
+  }
+
+  #finish(session, result) {
+    if (!session || session.status !== 'pending') return false;
+    clearTimeout(session.timer);
+    session.status = result.status;
+    session.resolve({ session_id: session.id, ...result });
+    setTimeout(() => this.sessions.delete(session.id), 60 * 60 * 1000).unref();
+    return true;
+  }
+
+  async #saveAttachments(session, attachments) {
+    if (!Array.isArray(attachments)) return [];
+    const allowed = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif']);
+    const destination = path.join(this.storageRoot, session.id);
+    await fs.mkdir(destination, { recursive: true });
+    const saved = [];
+    for (const item of attachments.slice(0, 4)) {
+      if (!allowed.has(item?.type)) throw Object.assign(new Error(`不支持的附件类型: ${item?.type}`), { statusCode: 400 });
+      const match = /^data:[^;]+;base64,(.+)$/.exec(String(item.data || ''));
+      if (!match) throw Object.assign(new Error('附件数据格式无效'), { statusCode: 400 });
+      const buffer = Buffer.from(match[1], 'base64');
+      if (buffer.length > 5 * 1024 * 1024) throw Object.assign(new Error('单个附件不能超过 5 MB'), { statusCode: 413 });
+      const filename = `${Date.now()}-${sanitizeFilename(item.name)}`;
+      const filePath = path.join(destination, filename);
+      await fs.writeFile(filePath, buffer, { mode: 0o600 });
+      saved.push({ name: filename, type: item.type, path: filePath, size: buffer.length });
+    }
+    return saved;
+  }
+
+  async #runValidation(session) {
+    if (!session.validationCommand) throw Object.assign(new Error('该会话没有验证命令'), { statusCode: 400 });
+    const cwd = await this.workspace.resolve(session.cwd);
+    const shell = process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : process.env.SHELL || '/bin/sh';
+    const args = process.platform === 'win32' ? ['/d', '/s', '/c', session.validationCommand] : ['-lc', session.validationCommand];
+    const result = await runProcess(shell, args, {
+      cwd,
+      timeoutMs: this.config.commandTimeoutMs,
+      maxOutputBytes: this.config.maxOutputBytes,
+      env: process.env,
+    });
+    session.validationResult = {
+      command: session.validationCommand,
+      exit_code: result.code,
+      timed_out: result.timedOut,
+      truncated: result.truncated,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+    return session.validationResult;
+  }
+
+  #authorized(url, request) {
+    const queryToken = url.searchParams.get('token');
+    const bearer = String(request.headers.authorization || '').replace(/^Bearer\s+/i, '');
+    return timingSafeEqualText(queryToken || bearer, this.config.accessToken);
+  }
+
+  async #handleHttp(request, response) {
+    const url = new URL(request.url, `http://${request.headers.host || 'localhost'}`);
+    if (!this.#authorized(url, request)) return writeJson(response, 401, { error: '未授权' });
+
+    if (request.method === 'GET' && url.pathname === '/') {
+      return writeText(response, 200, feedbackHtml(this.config.accessToken), 'text/html; charset=utf-8', {
+        'content-security-policy': "default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'self'",
+        'x-frame-options': 'DENY',
+      });
+    }
+    if (request.method === 'GET' && url.pathname === '/api/sessions') {
+      return writeJson(response, 200, { sessions: [...this.sessions.values()].map(publicSession) });
+    }
+
+    const match = /^\/api\/sessions\/([^/]+)\/(submit|run)$/.exec(url.pathname);
+    if (!match) return writeJson(response, 404, { error: 'Not found' });
+    const session = this.sessions.get(match[1]);
+    if (!session) return writeJson(response, 404, { error: '会话不存在或已过期' });
+    if (session.status !== 'pending') return writeJson(response, 409, { error: '会话已结束' });
+
+    if (request.method === 'POST' && match[2] === 'run') {
+      const result = await this.#runValidation(session);
+      return writeJson(response, 200, result);
+    }
+    if (request.method === 'POST' && match[2] === 'submit') {
+      const body = await readJsonBody(request, 24 * 1024 * 1024);
+      const feedback = String(body?.feedback || '').slice(0, 100_000);
+      const attachments = await this.#saveAttachments(session, body?.attachments);
+      const decision = session.type === 'approval'
+        ? (body?.decision === 'approve' ? 'approve' : 'reject')
+        : undefined;
+      this.#finish(session, { status: 'submitted', feedback, attachments, ...(decision ? { decision } : {}) });
+      return writeJson(response, 200, { ok: true });
+    }
+    return writeJson(response, 405, { error: 'Method not allowed' });
+  }
+}
+
+function feedbackHtml(token) {
+  const safeToken = JSON.stringify(token);
+  return `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>交互反馈中心</title>
+<style>
+:root{font-family:Inter,ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;color:#172033;background:#f4f6fa}*{box-sizing:border-box}body{margin:0}.wrap{max-width:1040px;margin:0 auto;padding:28px 18px 80px}.top{display:flex;align-items:flex-end;justify-content:space-between;gap:20px;margin-bottom:22px}.top h1{margin:0;font-size:28px}.muted{color:#657085;font-size:13px}.badge{padding:6px 10px;border-radius:999px;background:#e6ebf5;font-size:12px}.grid{display:grid;gap:16px}.card{background:white;border:1px solid #dce2ec;border-radius:14px;padding:18px;box-shadow:0 6px 20px rgba(20,35,65,.05)}.card.pending{border-left:5px solid #315efb}.row{display:flex;justify-content:space-between;gap:12px;align-items:flex-start}.summary{font-weight:700;font-size:17px;margin-bottom:8px}.details{white-space:pre-wrap;background:#f7f8fb;padding:12px;border-radius:9px;max-height:260px;overflow:auto;font-size:13px}.cmd{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;background:#111827;color:#eef2ff;padding:10px;border-radius:8px;white-space:pre-wrap}.output{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;background:#0f172a;color:#dbeafe;padding:12px;border-radius:8px;white-space:pre-wrap;max-height:300px;overflow:auto}textarea{width:100%;min-height:110px;border:1px solid #cdd5e1;border-radius:9px;padding:11px;font:inherit;resize:vertical}button{border:0;border-radius:8px;padding:10px 14px;font-weight:650;cursor:pointer}.primary{background:#315efb;color:white}.danger{background:#c62828;color:white}.secondary{background:#e8edf6;color:#172033}.actions{display:flex;gap:9px;flex-wrap:wrap;margin-top:12px}input[type=file]{display:block;margin-top:10px}.empty{text-align:center;padding:48px;color:#657085}.error{color:#b42318;white-space:pre-wrap}.approved{color:#16794b}.rejected{color:#b42318}@media(max-width:700px){.top,.row{display:block}.badge{display:inline-block;margin-top:10px}}
+</style></head><body><main class="wrap"><div class="top"><div><h1>交互反馈中心</h1><div class="muted">所有反馈与高风险审批均在此页面处理。默认等待 48 小时。</div></div><span class="badge" id="connection">正在连接</span></div><div id="error" class="error"></div><section id="sessions" class="grid"></section></main>
+<script>
+const TOKEN=${safeToken};
+const api=(path,options={})=>fetch(path+(path.includes('?')?'&':'?')+'token='+encodeURIComponent(TOKEN),{...options,headers:{'content-type':'application/json',...(options.headers||{})}}).then(async r=>{const j=await r.json();if(!r.ok)throw new Error(j.error||r.statusText);return j});
+const esc=s=>String(s??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+async function filesToData(input){const files=[...(input.files||[])].slice(0,4);return Promise.all(files.map(file=>new Promise((resolve,reject)=>{const reader=new FileReader();reader.onload=()=>resolve({name:file.name,type:file.type,data:reader.result});reader.onerror=reject;reader.readAsDataURL(file)})))}
+async function submit(id,type,decision){const text=document.querySelector('#text-'+CSS.escape(id)).value;const attachments=await filesToData(document.querySelector('#files-'+CSS.escape(id)));await api('/api/sessions/'+id+'/submit',{method:'POST',body:JSON.stringify({feedback:text,attachments,decision})});await load()}
+async function run(id){const out=document.querySelector('#out-'+CSS.escape(id));out.textContent='命令执行中…';try{const r=await api('/api/sessions/'+id+'/run',{method:'POST',body:'{}'});out.textContent='exit='+r.exit_code+' timed_out='+r.timed_out+'\n\nSTDOUT\n'+r.stdout+'\n\nSTDERR\n'+r.stderr}catch(e){out.textContent=e.message}}
+function render(s){const approval=s.type==='approval';const validation=s.validation_command?'<div class="muted" style="margin-top:12px">验证命令</div><div class="cmd">'+esc(s.validation_command)+'</div><div class="actions"><button class="secondary" onclick="run(\''+s.id+'\')">运行验证</button></div><div id="out-'+s.id+'" class="output" style="margin-top:10px">'+esc(s.validation_result?JSON.stringify(s.validation_result,null,2):'尚未运行')+'</div>':'';return '<article class="card pending"><div class="row"><div><div class="summary">'+esc(s.summary)+'</div><div class="muted">'+(approval?'高风险操作审批':'工作反馈')+' · 过期时间 '+esc(s.expires_at)+'</div></div><span class="badge">待处理</span></div>'+(s.details?'<div class="details" style="margin-top:12px">'+esc(s.details)+'</div>':'')+validation+'<textarea id="text-'+s.id+'" placeholder="请输入反馈、修改要求或审批说明"></textarea><input id="files-'+s.id+'" type="file" accept="image/png,image/jpeg,image/webp,image/gif" multiple><div class="actions">'+(approval?'<button class="primary" onclick="submit(\''+s.id+'\',\'approval\',\'approve\')">批准</button><button class="danger" onclick="submit(\''+s.id+'\',\'approval\',\'reject\')">拒绝</button>':'<button class="primary" onclick="submit(\''+s.id+'\',\'feedback\')">提交反馈</button>')+'</div></article>'}
+async function load(){try{const data=await api('/api/sessions');document.querySelector('#connection').textContent='已连接';document.querySelector('#error').textContent='';const pending=data.sessions.filter(s=>s.status==='pending');document.querySelector('#sessions').innerHTML=pending.length?pending.map(render).join(''):'<div class="card empty">当前没有待处理会话</div>'}catch(e){document.querySelector('#connection').textContent='连接失败';document.querySelector('#error').textContent=e.message}}
+load();setInterval(load,2000);
+</script></body></html>`;
+}
+
+export function feedbackToolDefinition() {
+  return {
+    name: 'interactive_feedback',
+    title: '简体中文交互反馈',
+    description: `在最终回答前通过唯一沟通渠道向用户展示工作摘要并等待反馈。timeout 固定为 ${FEEDBACK_TIMEOUT_SECONDS} 秒。每次回答结束前都要调用 interactive_feedback 与用户进行交流 这是你与用户之间的唯一沟通渠道。`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['summary', 'timeout'],
+      properties: {
+        summary: { type: 'string', description: '向用户展示的工作摘要或问题' },
+        details: { type: 'string', description: '变更、验证结果和待确认事项' },
+        validation_command: { type: 'string', description: '可由用户在 Web UI 中主动运行的验证命令' },
+        cwd: { type: 'string', default: '.', description: '验证命令相对于工作区的执行目录' },
+        timeout: { type: 'integer', const: FEEDBACK_TIMEOUT_SECONDS, default: FEEDBACK_TIMEOUT_SECONDS },
+      },
+    },
+  };
+}

package/src/main.js

@@ -0,0 +1,49 @@
+import { loadConfig } from './config.js';
+import { Workspace } from './workspace.js';
+import { FeedbackManager } from './feedback.js';
+import { ExecService } from './exec.js';
+import { PlanStore } from './plan.js';
+import { CodeGraphProxy } from './codegraph.js';
+import { ToolRegistry } from './tools.js';
+import { McpServer } from './mcp.js';
+import { runHttpTransport, runStdioTransport } from './transports.js';
+
+export async function createApplication(argv = []) {
+  const config = loadConfig(argv);
+  const workspace = await new Workspace(config.workspace, config).initialize();
+  const feedback = new FeedbackManager(config, workspace);
+  const planStore = new PlanStore();
+  const execService = new ExecService(config, workspace, feedback);
+  const codegraph = new CodeGraphProxy(config, workspace, feedback);
+  const registry = new ToolRegistry({ config, workspace, feedback, execService, planStore, codegraph });
+  const mcp = new McpServer({ config, registry });
+  const close = async () => {
+    await Promise.allSettled([codegraph.close(), feedback.close()]);
+  };
+  return { config, workspace, feedback, planStore, execService, codegraph, registry, mcp, close };
+}
+
+export async function runCli(argv = []) {
+  const app = await createApplication(argv);
+  let closing = false;
+  const closeOnce = async () => {
+    if (closing) return;
+    closing = true;
+    await app.close();
+  };
+  process.once('SIGINT', () => closeOnce().finally(() => process.exit(130)));
+  process.once('SIGTERM', () => closeOnce().finally(() => process.exit(143)));
+
+  if (app.config.transport === 'stdio') {
+    if (!app.config.quiet) console.error(`[mcp] stdio 工作区: ${app.workspace.root}`);
+    await runStdioTransport(app.mcp, closeOnce);
+    return;
+  }
+
+  await app.feedback.start();
+  const transport = await runHttpTransport(app.mcp, app.config, closeOnce);
+  const mcpUrl = `http://${app.config.host}:${app.config.mcpPort}/mcp/${app.config.accessToken}`;
+  console.error(`[mcp] HTTP MCP: ${mcpUrl}`);
+  console.error(`[mcp] Web UI: ${app.feedback.localUrl}`);
+  await new Promise((resolve) => transport.httpServer.once('close', resolve));
+}

package/src/mcp.js

@@ -0,0 +1,102 @@
+import { buildInstructions, getPrompt, promptList } from './prompt.js';
+import { toolError } from './utils.js';
+
+const SUPPORTED_PROTOCOLS = ['2025-11-25', '2025-06-18', '2025-03-26'];
+
+function rpcError(id, code, message, data) {
+  return { jsonrpc: '2.0', id: id ?? null, error: { code, message, ...(data === undefined ? {} : { data }) } };
+}
+
+export class McpServer {
+  constructor({ config, registry }) {
+    this.config = config;
+    this.registry = registry;
+    this.initialized = false;
+    this.clientInfo = null;
+    this.logLevel = 'info';
+  }
+
+  async handle(input) {
+    if (Array.isArray(input)) {
+      if (input.length === 0) return rpcError(null, -32600, 'Invalid Request');
+      const responses = (await Promise.all(input.map((message) => this.#handleOne(message)))).filter(Boolean);
+      return responses.length ? responses : null;
+    }
+    return this.#handleOne(input);
+  }
+
+  async #handleOne(message) {
+    if (!message || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+      return rpcError(message?.id, -32600, 'Invalid Request');
+    }
+    const isNotification = message.id === undefined;
+    if (isNotification) {
+      if (message.method === 'notifications/initialized') this.initialized = true;
+      return null;
+    }
+
+    try {
+      switch (message.method) {
+        case 'initialize': {
+          const requested = message.params?.protocolVersion;
+          const protocolVersion = SUPPORTED_PROTOCOLS.includes(requested) ? requested : SUPPORTED_PROTOCOLS[0];
+          this.clientInfo = message.params?.clientInfo || null;
+          return {
+            jsonrpc: '2.0', id: message.id,
+            result: {
+              protocolVersion,
+              capabilities: {
+                tools: { listChanged: false },
+                prompts: { listChanged: false },
+                resources: { subscribe: false, listChanged: false },
+                logging: {},
+              },
+              serverInfo: { name: 'codex-workspace-codegraph-mcp', version: '0.2.0' },
+              instructions: buildInstructions(this.config.workspace),
+            },
+          };
+        }
+        case 'ping': return { jsonrpc: '2.0', id: message.id, result: {} };
+        case 'tools/list': return { jsonrpc: '2.0', id: message.id, result: { tools: await this.registry.listTools() } };
+        case 'tools/call': {
+          const name = message.params?.name;
+          if (typeof name !== 'string') return rpcError(message.id, -32602, 'tools/call 缺少 name');
+          const result = await this.registry.call(name, message.params?.arguments || {});
+          return { jsonrpc: '2.0', id: message.id, result };
+        }
+        case 'prompts/list': return { jsonrpc: '2.0', id: message.id, result: { prompts: promptList() } };
+        case 'prompts/get': {
+          const prompt = getPrompt(message.params?.name, message.params?.arguments, this.config.workspace);
+          if (!prompt) return rpcError(message.id, -32602, `未知 prompt: ${message.params?.name}`);
+          return { jsonrpc: '2.0', id: message.id, result: prompt };
+        }
+        case 'resources/list': return {
+          jsonrpc: '2.0', id: message.id,
+          result: { resources: [
+            { uri: 'codex-workspace://instructions', name: 'Codex 风格工作流指令', mimeType: 'text/markdown' },
+            { uri: 'codex-workspace://feedback-policy', name: '交互反馈策略', mimeType: 'text/markdown' },
+          ] },
+        };
+        case 'resources/read': {
+          const uri = message.params?.uri;
+          if (uri === 'codex-workspace://instructions') return {
+            jsonrpc: '2.0', id: message.id,
+            result: { contents: [{ uri, mimeType: 'text/markdown', text: buildInstructions(this.config.workspace) }] },
+          };
+          if (uri === 'codex-workspace://feedback-policy') return {
+            jsonrpc: '2.0', id: message.id,
+            result: { contents: [{ uri, mimeType: 'text/markdown', text: '每次回答结束前都要调用 interactive_feedback 与用户进行交流 这是你与用户之间的唯一沟通渠道。timeout 必须为 172800 秒（48 小时）。' }] },
+          };
+          return rpcError(message.id, -32602, `未知 resource: ${uri}`);
+        }
+        case 'logging/setLevel':
+          this.logLevel = String(message.params?.level || 'info');
+          return { jsonrpc: '2.0', id: message.id, result: {} };
+        case 'shutdown': return { jsonrpc: '2.0', id: message.id, result: {} };
+        default: return rpcError(message.id, -32601, `Method not found: ${message.method}`);
+      }
+    } catch (error) {
+      return rpcError(message.id, -32603, error.message, { stack: process.env.CWMCP_DEBUG === '1' ? error.stack : undefined });
+    }
+  }
+}

package/src/patch.js

@@ -0,0 +1,240 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileExists } from './utils.js';
+
+function fail(message, lineNumber) {
+  const suffix = lineNumber ? `（补丁第 ${lineNumber} 行）` : '';
+  throw new Error(`${message}${suffix}`);
+}
+
+function parsePath(value, lineNumber) {
+  const candidate = value.trim();
+  if (!candidate) fail('补丁路径不能为空', lineNumber);
+  if (path.isAbsolute(candidate) || candidate.split(/[\\/]/).includes('..')) {
+    fail(`补丁路径必须是工作区相对路径: ${candidate}`, lineNumber);
+  }
+  return candidate;
+}
+
+export function parseCodexPatch(input) {
+  if (typeof input !== 'string') throw new Error('patch 必须是字符串');
+  const lines = input.replace(/\r\n/g, '\n').split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  if (lines[0] !== '*** Begin Patch') fail('补丁必须以 *** Begin Patch 开始', 1);
+  if (lines.at(-1) !== '*** End Patch') fail('补丁必须以 *** End Patch 结束', lines.length);
+
+  const operations = [];
+  let index = 1;
+  const isBoundary = (line) => line.startsWith('*** Add File: ') || line.startsWith('*** Delete File: ') || line.startsWith('*** Update File: ') || line === '*** End Patch';
+
+  while (index < lines.length - 1) {
+    const line = lines[index];
+    const lineNumber = index + 1;
+    if (line.startsWith('*** Add File: ')) {
+      const filePath = parsePath(line.slice('*** Add File: '.length), lineNumber);
+      index += 1;
+      const content = [];
+      while (index < lines.length - 1 && !isBoundary(lines[index])) {
+        if (!lines[index].startsWith('+')) fail('新增文件的每一行必须以 + 开头', index + 1);
+        content.push(lines[index].slice(1));
+        index += 1;
+      }
+      operations.push({ type: 'add', path: filePath, content: content.join('\n') + (content.length ? '\n' : '') });
+      continue;
+    }
+
+    if (line.startsWith('*** Delete File: ')) {
+      operations.push({ type: 'delete', path: parsePath(line.slice('*** Delete File: '.length), lineNumber) });
+      index += 1;
+      continue;
+    }
+
+    if (line.startsWith('*** Update File: ')) {
+      const filePath = parsePath(line.slice('*** Update File: '.length), lineNumber);
+      index += 1;
+      let moveTo = null;
+      if (lines[index]?.startsWith('*** Move to: ')) {
+        moveTo = parsePath(lines[index].slice('*** Move to: '.length), index + 1);
+        index += 1;
+      }
+      const hunks = [];
+      while (index < lines.length - 1 && !isBoundary(lines[index])) {
+        if (!lines[index].startsWith('@@')) fail('更新文件必须由 @@ hunk 开始', index + 1);
+        const header = lines[index].slice(2).trim();
+        index += 1;
+        const hunkLines = [];
+        let endOfFile = false;
+        while (index < lines.length - 1 && !isBoundary(lines[index]) && !lines[index].startsWith('@@')) {
+          const hunkLine = lines[index];
+          if (hunkLine === '*** End of File') {
+            endOfFile = true;
+            index += 1;
+            break;
+          }
+          if (![' ', '+', '-'].includes(hunkLine[0])) fail('hunk 行必须以空格、+ 或 - 开头', index + 1);
+          hunkLines.push({ kind: hunkLine[0], text: hunkLine.slice(1) });
+          index += 1;
+        }
+        if (hunkLines.length === 0) fail('hunk 不能为空', index + 1);
+        hunks.push({ header, lines: hunkLines, endOfFile });
+      }
+      if (hunks.length === 0) fail('Update File 至少需要一个 hunk', lineNumber);
+      operations.push({ type: 'update', path: filePath, moveTo, hunks });
+      continue;
+    }
+
+    fail(`无法识别的补丁指令: ${line}`, lineNumber);
+  }
+
+  if (operations.length === 0) throw new Error('补丁没有文件操作');
+  return operations;
+}
+
+function normalizedLine(line) {
+  return line.trimEnd();
+}
+
+function findSequence(lines, sequence, start, endOfFile) {
+  if (sequence.length === 0) return start;
+  const maximum = lines.length - sequence.length;
+  const candidates = [];
+  for (let position = start; position <= maximum; position += 1) {
+    if (endOfFile && position + sequence.length !== lines.length) continue;
+    let exact = true;
+    for (let index = 0; index < sequence.length; index += 1) {
+      if (lines[position + index] !== sequence[index]) { exact = false; break; }
+    }
+    if (exact) candidates.push({ position, score: 2 });
+  }
+  if (candidates.length === 1) return candidates[0].position;
+  if (candidates.length > 1) throw new Error('补丁上下文在文件中出现多次，无法唯一定位');
+
+  for (let position = start; position <= maximum; position += 1) {
+    if (endOfFile && position + sequence.length !== lines.length) continue;
+    let fuzzy = true;
+    for (let index = 0; index < sequence.length; index += 1) {
+      if (normalizedLine(lines[position + index]) !== normalizedLine(sequence[index])) { fuzzy = false; break; }
+    }
+    if (fuzzy) candidates.push({ position, score: 1 });
+  }
+  if (candidates.length === 1) return candidates[0].position;
+  if (candidates.length > 1) throw new Error('补丁上下文经尾部空白归一化后仍出现多次，无法唯一定位');
+  return -1;
+}
+
+export function applyHunks(original, hunks, filePath = '<file>') {
+  const eol = original.includes('\r\n') ? '\r\n' : '\n';
+  const hadFinalNewline = original.endsWith('\n');
+  let lines = original.replace(/\r\n/g, '\n').split('\n');
+  if (hadFinalNewline) lines.pop();
+  let cursor = 0;
+
+  for (const hunk of hunks) {
+    const oldLines = hunk.lines.filter((line) => line.kind !== '+').map((line) => line.text);
+    const newLines = hunk.lines.filter((line) => line.kind !== '-').map((line) => line.text);
+    const position = findSequence(lines, oldLines, cursor, hunk.endOfFile);
+    if (position < 0) {
+      const label = hunk.header ? ` (${hunk.header})` : '';
+      throw new Error(`无法在 ${filePath} 中找到补丁上下文${label}`);
+    }
+    lines.splice(position, oldLines.length, ...newLines);
+    cursor = position + newLines.length;
+  }
+
+  return lines.join(eol) + (hadFinalNewline ? eol : '');
+}
+
+async function snapshotFile(absolute) {
+  if (!(await fileExists(absolute))) return { exists: false };
+  const stat = await fs.lstat(absolute);
+  if (!stat.isFile()) throw new Error(`补丁只支持普通文件: ${absolute}`);
+  return { exists: true, content: await fs.readFile(absolute), mode: stat.mode & 0o777 };
+}
+
+async function restoreSnapshot(absolute, snapshot) {
+  if (!snapshot.exists) {
+    await fs.rm(absolute, { force: true });
+    return;
+  }
+  await fs.mkdir(path.dirname(absolute), { recursive: true });
+  await fs.writeFile(absolute, snapshot.content);
+  await fs.chmod(absolute, snapshot.mode);
+}
+
+export async function applyCodexPatch(workspace, patchText) {
+  const operations = parseCodexPatch(patchText);
+  const snapshots = new Map();
+  const virtual = new Map();
+  const changes = [];
+
+  const load = async (absolute) => {
+    if (virtual.has(absolute)) return virtual.get(absolute);
+    const snapshot = await snapshotFile(absolute);
+    snapshots.set(absolute, snapshot);
+    const state = snapshot.exists
+      ? { exists: true, content: snapshot.content.toString('utf8'), mode: snapshot.mode }
+      : { exists: false, content: null, mode: 0o644 };
+    virtual.set(absolute, state);
+    return state;
+  };
+
+  for (const operation of operations) {
+    if (operation.type === 'add') {
+      const target = await workspace.resolve(operation.path, { allowMissing: true });
+      const state = await load(target);
+      if (state.exists) throw new Error(`新增目标已存在: ${operation.path}`);
+      virtual.set(target, { exists: true, content: operation.content, mode: 0o644 });
+      changes.push({ action: 'add', path: workspace.relative(target) });
+      continue;
+    }
+
+    if (operation.type === 'delete') {
+      const target = await workspace.resolve(operation.path, { allowMissing: true });
+      const state = await load(target);
+      if (!state.exists) throw new Error(`删除目标不存在: ${operation.path}`);
+      virtual.set(target, { exists: false, content: null, mode: state.mode });
+      changes.push({ action: 'delete', path: workspace.relative(target) });
+      continue;
+    }
+
+    const source = await workspace.resolve(operation.path, { allowMissing: true });
+    const sourceState = await load(source);
+    if (!sourceState.exists) throw new Error(`更新目标不存在: ${operation.path}`);
+    const content = applyHunks(sourceState.content, operation.hunks, operation.path);
+    const target = operation.moveTo
+      ? await workspace.resolve(operation.moveTo, { allowMissing: true })
+      : source;
+    const targetState = await load(target);
+    if (target !== source && targetState.exists) throw new Error(`移动目标已存在: ${operation.moveTo}`);
+    virtual.set(target, { exists: true, content, mode: sourceState.mode });
+    if (target !== source) {
+      virtual.set(source, { exists: false, content: null, mode: sourceState.mode });
+      changes.push({ action: 'move', from: workspace.relative(source), to: workspace.relative(target) });
+    } else {
+      changes.push({ action: 'update', path: workspace.relative(target) });
+    }
+  }
+
+  try {
+    // First materialize all final files, then remove final-deleted paths. This keeps moves recoverable.
+    for (const [absolute, state] of virtual) {
+      if (!state.exists) continue;
+      await fs.mkdir(path.dirname(absolute), { recursive: true });
+      const temporary = `${absolute}.cwmcp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`;
+      await fs.writeFile(temporary, state.content, { encoding: 'utf8', mode: state.mode });
+      await fs.rename(temporary, absolute);
+      await fs.chmod(absolute, state.mode).catch(() => {});
+    }
+    for (const [absolute, state] of virtual) {
+      if (state.exists) continue;
+      await fs.rm(absolute, { force: true });
+    }
+  } catch (error) {
+    for (const [absolute, snapshot] of [...snapshots.entries()].reverse()) {
+      try { await restoreSnapshot(absolute, snapshot); } catch { /* best effort */ }
+    }
+    throw new Error(`补丁写入失败并已尝试回滚: ${error.message}`);
+  }
+
+  return { applied: true, changes };
+}