claude-coder 1.0.1 → 1.0.3

package/bin/cli.js

@@ -46,6 +46,9 @@ function parseArgs(argv) {
       case '--dry-run':
         opts.dryRun = true;
         break;
+      case '--view':
+        opts.viewMode = true;
+        break;
       case '--help':
       case '-h':
         showHelp();
@@ -78,7 +81,11 @@ async function main() {
   switch (command) {
     case 'run': {
       const runner = require('../src/runner');
-      await runner.run(positional[0] || null, opts);
+      if (opts.viewMode) {
+        await runner.view(positional[0] || null, opts);
+      } else {
+        await runner.run(positional[0] || null, opts);
+      }
       break;
     }
     case 'setup': {

package/docs/ARCHITECTURE.md

@@ -278,7 +278,65 @@ sequenceDiagram
 
 ---
 
-## 9. 后续优化方向
+## 9. Claude Agent SDK V1/V2 对比与迁移计划
+
+当前使用 **V1 稳定 API**（`query()`），V2 为 preview 状态（`unstable_` 前缀）。
+
+### V1 vs V2 API 对比
+
+| 维度 | V1 `query()` | V2 `send()/stream()` |
+|------|-------------|---------------------|
+| **状态** | 稳定，生产可用 | `unstable_` 前缀，preview |
+| **入口函数** | `query({ prompt, options })` | `unstable_v2_createSession(opts)` / `unstable_v2_prompt()` |
+| **多轮会话** | 需手动管理 AsyncGenerator | `session.send()` + `session.stream()`，更简洁 |
+| **会话恢复** | `options.resume: sessionId` | `unstable_v2_resumeSession(id)` |
+| **Hooks** | `options.hooks: { PreToolUse, PostToolUse, ... }` | 未支持 |
+| **Subagents** | `options.agents: { name: AgentDefinition }` | 未支持 |
+| **Session Fork** | `options.forkSession: true` | 未支持 |
+| **Plugins** | `options.plugins: [{ type, path }]` | 未支持 |
+| **结构化输出** | `options.outputFormat: { type: 'json_schema', schema }` | 支持 |
+| **文件检查点** | `options.enableFileCheckpointing + rewindFiles()` | 未明确 |
+| **Cost Tracking** | `SDKResultMessage.total_cost_usd` | `SDKResultMessage.total_cost_usd` |
+| **权限控制** | `canUseTool`, `permissionMode`, `allowedTools`, `disallowedTools` | 继承 |
+
+### 当前实现使用的 V1 特性
+
+```javascript
+query({
+  prompt,
+  options: {
+    systemPrompt,                      // 注入 CLAUDE.md
+    allowedTools,                      // 工具白名单
+    permissionMode: 'bypassPermissions',
+    allowDangerouslySkipPermissions: true,
+    model,                             // 从 .env 传入
+    env,                               // 环境变量透传
+    settingSources: ['project'],       // 加载项目 CLAUDE.md
+    hooks: { PreToolUse: [...] },      // 实时 spinner 监控
+  }
+})
+```
+
+### V2 迁移条件（等待稳定后）
+
+1. V2 去掉 `unstable_` 前缀，正式发布
+2. V2 支持 Hooks（当前项目依赖 PreToolUse 做 spinner 和 activity log）
+3. V2 支持 Subagents（未来可能用于扫描 Agent / 编码 Agent 分离）
+
+### 可利用但尚未使用的 V1 特性
+
+| 特性 | 说明 | 优先级 |
+|------|------|--------|
+| `maxBudgetUsd` | SDK 内置成本上限，替代自研追踪 | P0 |
+| `effort` | 控制思考深度（`low`/`medium`/`high`/`max`） | P1 |
+| `enableFileCheckpointing` | 文件操作检查点，比 git reset 更精细 | P1 |
+| `outputFormat` | 结构化输出，让 Agent 直接输出 JSON 格式 | P1 |
+| `agents` | 定义子 Agent，不同模型/工具集 | P2 |
+| `betas` | 扩展上下文窗口 | P2 |
+
+---
+
+## 10. 后续优化方向
 
 ### P0 — 近期
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Claude Coder — Autonomous coding agent harness powered by Claude Code SDK. Scan, plan, code, validate, git-commit in a loop.",
   "bin": {
     "claude-coder": "bin/cli.js"

package/src/runner.js

@@ -12,14 +12,28 @@ const { runCodingSession, runViewSession, runAddSession } = require('./session')
 
 const MAX_RETRY = 3;
 
-function requireSdk() {
-  try {
-    require.resolve('@anthropic-ai/claude-agent-sdk');
-  } catch {
-    console.error('错误：未找到 @anthropic-ai/claude-agent-sdk');
-    console.error('请先安装：npm install -g @anthropic-ai/claude-agent-sdk');
-    process.exit(1);
+async function requireSdk() {
+  const pkgName = '@anthropic-ai/claude-agent-sdk';
+  const attempts = [
+    () => { require.resolve(pkgName); return true; },
+    () => {
+      const { createRequire } = require('module');
+      createRequire(__filename).resolve(pkgName);
+      return true;
+    },
+    () => {
+      const prefix = execSync('npm prefix -g', { encoding: 'utf8' }).trim();
+      const sdkPath = path.join(prefix, 'lib', 'node_modules', pkgName);
+      if (fs.existsSync(sdkPath)) return true;
+      throw new Error('not found');
+    },
+  ];
+  for (const attempt of attempts) {
+    try { if (attempt()) return; } catch { /* try next */ }
   }
+  console.error(`错误：未找到 ${pkgName}`);
+  console.error(`请先安装：npm install -g ${pkgName}`);
+  process.exit(1);
 }
 
 function getHead() {
@@ -86,7 +100,7 @@ function appendProgress(entry) {
   const p = paths();
   let progress = { sessions: [] };
   if (fs.existsSync(p.progressFile)) {
-    try { progress = JSON.parse(fs.readFileSync(p.progressFile, 'utf8')); } catch { /* reset */ }
+    try { progress = JSON.parse(fs.readFileSync(p.progressFile, 'utf8').replace(/[\u201c\u201d]/g, '"')); } catch { /* reset */ }
   }
   if (!Array.isArray(progress.sessions)) progress.sessions = [];
   progress.sessions.push(entry);
@@ -97,7 +111,7 @@ function updateSessionHistory(sessionData, sessionNum) {
   const p = paths();
   let sr = { current: null, history: [] };
   if (fs.existsSync(p.sessionResult)) {
-    try { sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8')); } catch { /* reset */ }
+    try { sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8').replace(/[\u201c\u201d]/g, '"')); } catch { /* reset */ }
     if (!sr.history && sr.session_result) {
       sr = { current: sr, history: [] };
     }
@@ -199,7 +213,7 @@ async function run(requirement, opts = {}) {
       return;
     }
 
-    requireSdk();
+    await requireSdk();
     const scanResult = await scan(requirement, { projectRoot });
     if (!scanResult.success) {
       console.log('');
@@ -215,7 +229,7 @@ async function run(requirement, opts = {}) {
   }
 
   // Coding loop
-  if (!dryRun) requireSdk();
+  if (!dryRun) await requireSdk();
   log('info', `开始编码循环 (最多 ${maxSessions} 个会话) ...`);
   console.log('');
 
@@ -319,7 +333,7 @@ async function run(requirement, opts = {}) {
 }
 
 async function view(requirement, opts = {}) {
-  requireSdk();
+  await requireSdk();
   const projectRoot = getProjectRoot();
   ensureLoopDir();
 
@@ -331,7 +345,7 @@ async function view(requirement, opts = {}) {
 }
 
 async function add(instruction, opts = {}) {
-  requireSdk();
+  await requireSdk();
   const p = paths();
   const projectRoot = getProjectRoot();
   ensureLoopDir();

package/src/session.js

@@ -6,12 +6,76 @@ const { paths, loadConfig, buildEnvVars, getAllowedTools, log } = require('./con
 const { Indicator, inferPhaseStep } = require('./indicator');
 const { buildSystemPrompt, buildCodingPrompt, buildScanPrompt, buildViewPrompt, buildAddPrompt } = require('./prompts');
 
+let _sdkModule = null;
+async function loadSDK() {
+  if (_sdkModule) return _sdkModule;
+
+  const pkgName = '@anthropic-ai/claude-agent-sdk';
+  const attempts = [
+    () => import(pkgName),
+    () => {
+      const { createRequire } = require('module');
+      const resolved = createRequire(__filename).resolve(pkgName);
+      return import(resolved);
+    },
+    () => {
+      const { execSync } = require('child_process');
+      const prefix = execSync('npm prefix -g', { encoding: 'utf8' }).trim();
+      const sdkPath = path.join(prefix, 'lib', 'node_modules', pkgName, 'sdk.mjs');
+      return import(sdkPath);
+    },
+  ];
+
+  for (const attempt of attempts) {
+    try {
+      _sdkModule = await attempt();
+      return _sdkModule;
+    } catch { /* try next */ }
+  }
+
+  log('error', `未找到 ${pkgName}`);
+  log('error', `请先安装：npm install -g ${pkgName}`);
+  process.exit(1);
+}
+
 function applyEnvConfig(config) {
   Object.assign(process.env, buildEnvVars(config));
 }
 
+function buildQueryOptions(config, opts = {}) {
+  const base = {
+    allowedTools: getAllowedTools(config),
+    permissionMode: 'bypassPermissions',
+    allowDangerouslySkipPermissions: true,
+    cwd: opts.projectRoot || process.cwd(),
+    env: buildEnvVars(config),
+    settingSources: ['project'],
+  };
+  if (config.model) base.model = config.model;
+  return base;
+}
+
+function extractResult(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].type === 'result') return messages[i];
+  }
+  return null;
+}
+
+function logMessage(message, logStream, indicator) {
+  if (message.type === 'assistant' && message.message?.content) {
+    for (const block of message.message.content) {
+      if (block.type === 'text' && block.text) {
+        if (indicator) process.stderr.write('\r\x1b[K');
+        process.stdout.write(block.text);
+        if (logStream) logStream.write(block.text);
+      }
+    }
+  }
+}
+
 async function runCodingSession(sessionNum, opts = {}) {
-  const { query } = require('@anthropic-ai/claude-agent-sdk');
+  const sdk = await loadSDK();
   const config = loadConfig();
   applyEnvConfig(config);
   const indicator = new Indicator();
@@ -26,46 +90,34 @@ async function runCodingSession(sessionNum, opts = {}) {
   indicator.start(sessionNum);
 
   try {
-    const session = query({
-      prompt,
-      options: {
-        systemPrompt,
-        allowedTools: getAllowedTools(config),
-        permissionMode: 'bypassPermissions',
-        verbose: true,
-        cwd: opts.projectRoot || process.cwd(),
-        timeout_ms: config.timeoutMs,
-        hooks: {
-          PreToolUse: [{
-            matcher: '*',
-            callback: (event) => {
-              inferPhaseStep(indicator, event.tool_name, event.tool_input);
-              return { decision: 'allow' };
-            }
-          }]
-        }
-      }
-    });
+    const queryOpts = buildQueryOptions(config, opts);
+    queryOpts.systemPrompt = systemPrompt;
+    queryOpts.hooks = {
+      PreToolUse: [{
+        matcher: '*',
+        hooks: [async (input) => {
+          inferPhaseStep(indicator, input.tool_name, input.tool_input);
+          return {};
+        }]
+      }]
+    };
+
+    const session = sdk.query({ prompt, options: queryOpts });
 
-    let result;
+    const collected = [];
     for await (const message of session) {
-      if (message.content) {
-        const text = typeof message.content === 'string'
-          ? message.content
-          : JSON.stringify(message.content);
-        process.stdout.write(text);
-        logStream.write(text);
-      }
-      result = message;
+      collected.push(message);
+      logMessage(message, logStream, indicator);
     }
 
     logStream.end();
     indicator.stop();
 
+    const result = extractResult(collected);
     return {
       exitCode: 0,
-      cost: result?.total_cost_usd || null,
-      tokenUsage: result?.message?.usage || null,
+      cost: result?.total_cost_usd ?? null,
+      tokenUsage: result?.usage ?? null,
       logFile,
     };
   } catch (err) {
@@ -83,7 +135,7 @@ async function runCodingSession(sessionNum, opts = {}) {
 }
 
 async function runScanSession(requirement, opts = {}) {
-  const { query } = require('@anthropic-ai/claude-agent-sdk');
+  const sdk = await loadSDK();
   const config = loadConfig();
   applyEnvConfig(config);
   const indicator = new Indicator();
@@ -100,45 +152,33 @@ async function runScanSession(requirement, opts = {}) {
   log('info', `正在调用 Claude Code 执行项目扫描（${projectType}项目）...`);
 
   try {
-    const session = query({
-      prompt,
-      options: {
-        systemPrompt,
-        allowedTools: getAllowedTools(config),
-        permissionMode: 'bypassPermissions',
-        verbose: true,
-        cwd: opts.projectRoot || process.cwd(),
-        timeout_ms: config.timeoutMs,
-        hooks: {
-          PreToolUse: [{
-            matcher: '*',
-            callback: (event) => {
-              inferPhaseStep(indicator, event.tool_name, event.tool_input);
-              return { decision: 'allow' };
-            }
-          }]
-        }
-      }
-    });
+    const queryOpts = buildQueryOptions(config, opts);
+    queryOpts.systemPrompt = systemPrompt;
+    queryOpts.hooks = {
+      PreToolUse: [{
+        matcher: '*',
+        hooks: [async (input) => {
+          inferPhaseStep(indicator, input.tool_name, input.tool_input);
+          return {};
+        }]
+      }]
+    };
+
+    const session = sdk.query({ prompt, options: queryOpts });
 
-    let result;
+    const collected = [];
     for await (const message of session) {
-      if (message.content) {
-        const text = typeof message.content === 'string'
-          ? message.content
-          : JSON.stringify(message.content);
-        process.stdout.write(text);
-        logStream.write(text);
-      }
-      result = message;
+      collected.push(message);
+      logMessage(message, logStream, indicator);
     }
 
     logStream.end();
     indicator.stop();
 
+    const result = extractResult(collected);
     return {
       exitCode: 0,
-      cost: result?.total_cost_usd || null,
+      cost: result?.total_cost_usd ?? null,
       logFile,
     };
   } catch (err) {
@@ -150,7 +190,7 @@ async function runScanSession(requirement, opts = {}) {
 }
 
 async function runViewSession(requirement, opts = {}) {
-  const { query } = require('@anthropic-ai/claude-agent-sdk');
+  const sdk = await loadSDK();
   const p = paths();
   const config = loadConfig();
   applyEnvConfig(config);
@@ -172,25 +212,13 @@ async function runViewSession(requirement, opts = {}) {
   }
 
   try {
-    const session = query({
-      prompt,
-      options: {
-        systemPrompt,
-        allowedTools: getAllowedTools(config),
-        permissionMode: 'bypassPermissions',
-        verbose: true,
-        cwd: opts.projectRoot || process.cwd(),
-        timeout_ms: config.timeoutMs,
-      }
-    });
+    const queryOpts = buildQueryOptions(config, opts);
+    queryOpts.systemPrompt = systemPrompt;
+
+    const session = sdk.query({ prompt, options: queryOpts });
 
     for await (const message of session) {
-      if (message.content) {
-        const text = typeof message.content === 'string'
-          ? message.content
-          : JSON.stringify(message.content);
-        process.stdout.write(text);
-      }
+      logMessage(message, null);
     }
   } catch (err) {
     log('error', `观测模式错误: ${err.message}`);
@@ -198,7 +226,7 @@ async function runViewSession(requirement, opts = {}) {
 }
 
 async function runAddSession(instruction, opts = {}) {
-  const { query } = require('@anthropic-ai/claude-agent-sdk');
+  const sdk = await loadSDK();
   const config = loadConfig();
   applyEnvConfig(config);
 
@@ -210,26 +238,13 @@ async function runAddSession(instruction, opts = {}) {
   const logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
   try {
-    const session = query({
-      prompt,
-      options: {
-        systemPrompt,
-        allowedTools: getAllowedTools(config),
-        permissionMode: 'bypassPermissions',
-        verbose: true,
-        cwd: opts.projectRoot || process.cwd(),
-        timeout_ms: config.timeoutMs,
-      }
-    });
+    const queryOpts = buildQueryOptions(config, opts);
+    queryOpts.systemPrompt = systemPrompt;
+
+    const session = sdk.query({ prompt, options: queryOpts });
 
     for await (const message of session) {
-      if (message.content) {
-        const text = typeof message.content === 'string'
-          ? message.content
-          : JSON.stringify(message.content);
-        process.stdout.write(text);
-        logStream.write(text);
-      }
+      logMessage(message, logStream);
     }
 
     logStream.end();

package/src/tasks.js

@@ -13,10 +13,16 @@ const TRANSITIONS = {
   done:        [],
 };
 
+function normalizeJson(text) {
+  return text
+    .replace(/[\u201c\u201d]/g, '"')
+    .replace(/[\u2018\u2019]/g, "'");
+}
+
 function loadTasks() {
   const p = paths();
   if (!fs.existsSync(p.tasksFile)) return null;
-  return JSON.parse(fs.readFileSync(p.tasksFile, 'utf8'));
+  return JSON.parse(normalizeJson(fs.readFileSync(p.tasksFile, 'utf8')));
 }
 
 function saveTasks(data) {

package/src/validator.js

@@ -4,6 +4,10 @@ const fs = require('fs');
 const { execSync } = require('child_process');
 const { paths, log, getProjectRoot } = require('./config');
 
+function normalizeJson(text) {
+  return text.replace(/[\u201c\u201d]/g, '"').replace(/[\u2018\u2019]/g, "'");
+}
+
 function validateSessionResult() {
   const p = paths();
 
@@ -14,7 +18,7 @@ function validateSessionResult() {
 
   let data;
   try {
-    data = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
+    data = JSON.parse(normalizeJson(fs.readFileSync(p.sessionResult, 'utf8')));
   } catch {
     log('error', 'session_result.json JSON 格式错误');
     return { valid: false, fatal: true, reason: 'JSON 格式错误' };
@@ -86,9 +90,9 @@ function checkTestCoverage() {
   if (!fs.existsSync(p.testsFile) || !fs.existsSync(p.sessionResult)) return;
 
   try {
-    const sr = JSON.parse(fs.readFileSync(p.sessionResult, 'utf8'));
+    const sr = JSON.parse(normalizeJson(fs.readFileSync(p.sessionResult, 'utf8')));
     const current = sr.current || sr;
-    const tests = JSON.parse(fs.readFileSync(p.testsFile, 'utf8'));
+    const tests = JSON.parse(normalizeJson(fs.readFileSync(p.testsFile, 'utf8')));
 
     const taskId = current.task_id || '';
     const testCases = tests.test_cases || [];