claude-coder 1.0.2 → 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.2",
+  "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

@@ -100,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);
@@ -111,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: [] };
     }

package/src/session.js

@@ -62,10 +62,11 @@ function extractResult(messages) {
   return null;
 }
 
-function logMessage(message, logStream) {
+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);
       }
@@ -106,7 +107,7 @@ async function runCodingSession(sessionNum, opts = {}) {
     const collected = [];
     for await (const message of session) {
       collected.push(message);
-      logMessage(message, logStream);
+      logMessage(message, logStream, indicator);
     }
 
     logStream.end();
@@ -168,7 +169,7 @@ async function runScanSession(requirement, opts = {}) {
     const collected = [];
     for await (const message of session) {
       collected.push(message);
-      logMessage(message, logStream);
+      logMessage(message, logStream, indicator);
     }
 
     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 || [];