claude-coder 1.8.3 → 1.9.0

package/src/index.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadConfig, log } = require('./common/config');
+const { assets } = require('./common/assets');
+const { Session } = require('./core/session');
+
+/** @typedef {{ max?: number, pause?: number, dryRun?: boolean, readFile?: string, model?: string, n?: number, planOnly?: boolean, interactive?: boolean, reset?: boolean, deployTemplates?: boolean, projectRoot?: string, reqFile?: string }} MainOpts */
+
+function checkReady(command) {
+  if (['init', 'scan'].includes(command)) return;
+
+  if (!assets.exists('profile')) {
+    throw new Error('文件缺失: project_profile.json，请运行 claude-coder init 初始化项目');
+  }
+}
+
+/**
+ * 应用入口：初始化资产、加载配置、分发命令
+ * @param {string} command - 命令名称（init | scan | plan | run | go | simplify）
+ * @param {string} input - 位置参数（需求文本等）
+ * @param {MainOpts} [opts={}] - CLI 选项
+ * @returns {Promise<Object|void>}
+ */
+async function main(command, input, opts = {}) {
+  assets.init(opts.projectRoot || process.cwd());
+  assets.ensureDirs();
+  const config = loadConfig();
+
+  if (!opts.model) opts.model = config.defaultOpus || config.model;
+
+  if (opts.readFile) {
+    const reqPath = path.resolve(assets.projectRoot, opts.readFile);
+    if (!fs.existsSync(reqPath)) {
+      throw new Error(`文件不存在: ${reqPath}`);
+    }
+    opts.reqFile = reqPath;
+  }
+
+  checkReady(command);
+
+  const displayModel = opts.model || '(default)';
+  log('ok', `模型: ${config.provider || 'claude'} (${displayModel}), 命令: ${command}`);
+
+  switch (command) {
+    case 'init': {
+      const { executeInit } = require('./core/init');
+      return executeInit(config, opts);
+    }
+    case 'scan': {
+      const { executeScan } = require('./core/scan');
+      return executeScan(config, opts);
+    }
+    case 'simplify': {
+      const { executeSimplify } = require('./core/simplify');
+      return executeSimplify(config, input, opts);
+    }
+    case 'plan': {
+      const { executePlan } = require('./core/plan');
+      return executePlan(config, input, opts);
+    }
+    case 'run': {
+      const { executeRun } = require('./core/runner');
+      return executeRun(config, opts);
+    }
+    case 'go': {
+      const { executeGo } = require('./core/go');
+      return executeGo(config, input, opts);
+    }
+    default:
+      throw new Error(`未知命令: ${command}`);
+  }
+}
+
+module.exports = { main, Session };

package/templates/codingSystem.md

@@ -45,8 +45,8 @@
 
 **Step 3 — 收尾（必须执行）**
 1. 根据 prompt 提示管理后台服务
-2. `git add -A && git commit -m "feat(task-id): 描述"`
-3. 写 session_result.json：notes 只写未解决问题
+2. 写 session_result.json：notes 只写未解决问题
+3. `git add -A && git commit -m "feat(task-id): 描述"`
 
 ## 工具规范
 

package/templates/codingUser.md

@@ -9,7 +9,7 @@ Session {{sessionNum}}。任务已分配，按 3 步流程执行。
 {{docsHint}}
 {{testEnvHint}}
 {{mcpHint}}
-{{playwrightAuthHint}}
+{{webTestHint}}
 {{retryContext}}
 
 ## 收尾

package/templates/guidance.json

@@ -4,14 +4,14 @@
       "name": "playwright",
       "matcher": "^mcp__playwright__",
       "file": {
-        "path": "assets/playwright.md",
+        "path": "assets/web-testing.md",
         "injectOnce": true
       },
       "toolTips": {
         "injectOnce": false,
         "extractor": "browser_(\\w+)",
         "items": {
-          "snapshot": "snapshot 消耗 3-8K tokens，仅在必要时使用。",
+          "snapshot": "snapshot 频率注意控制。",
           "wait_for": "设置合理 timeout，AI 生成任务建议 60-180s。",
           "click": "点击前确认元素已通过 snapshot 获取 ref。",
           "type": "大量文本输入可使用 fill_form 批量操作。",
@@ -19,6 +19,25 @@
         }
       }
     },
+    {
+      "name": "chrome-devtools",
+      "matcher": "^mcp__chrome.devtools__",
+      "file": {
+        "path": "assets/web-testing.md",
+        "injectOnce": true
+      },
+      "toolTips": {
+        "injectOnce": false,
+        "extractor": "^(\\w+)$",
+        "items": {
+          "take_snapshot": "snapshot 频率注意控制。",
+          "wait_for": "设置合理 timeout，AI 生成任务建议 60-180s。",
+          "click": "点击前确认元素已通过 take_snapshot 获取定位。",
+          "type_text": "大量文本输入可使用 fill_form 批量操作。",
+          "navigate_page": "导航后必须 take_snapshot 确认页面加载成功。"
+        }
+      }
+    },
     {
       "name": "frontend-component",
       "matcher": "^(Edit|MultiEdit|Write)$",
@@ -50,4 +69,4 @@
       }
     }
   ]
-}
+}

package/templates/planSystem.md

@@ -69,8 +69,8 @@ test 类任务 steps 用标签标记优先级：`【P0】` 必测 | `【P1】`
 2. 读取 `.claude-coder/tasks.json` + `project_profile.json`，了解现状
 3. 识别功能点，判断单任务还是需拆分；对比已有任务避免重叠
 4. 确定 `depends_on`，按规范追加任务到 tasks.json
-5. `git add -A && git commit -m "chore: add new tasks"`
-6. 写入 session_result.json：`{ "session_result": "success", "status_before": "N/A", "status_after": "N/A", "notes": "追加了 N 个任务：简述" }`
+5. 写入 session_result.json：`{ "session_result": "success", "status_before": "N/A", "status_after": "N/A", "notes": "追加了 N 个任务：简述" }`
+6. `git add -A && git commit -m "chore: add new tasks"`
 
 ## 反面案例
 

package/templates/scanSystem.md

@@ -108,13 +108,13 @@
   "existing_docs": ["README.md", ".claude/CLAUDE.md"],
   "has_tests": false,
   "has_docker": false,
-  "mcp_tools": { "playwright": false },
+  "mcp_tools": { "web_test_tool": "playwright | chrome-devtools | none" },
   "custom_init": [],
   "scan_files_checked": []
 }
 ```
 
 **注意**：
-- `existing_docs`：列出项目中所有可读文档路径
+- `existing_docs`：列出项目中重要的可读文档路径，比如 README.md、API 文档、架构文档等。
 - `services` 的 `command` 必须来自实际配置文件或标准命令
-- `mcp_tools`：检查 `.claude-coder/.env` 中的变量，不存在则全部设为 `false`
+- `mcp_tools`：检查 `.claude-coder/.env` 中 `WEB_TEST_TOOL` 变量的值（playwright / chrome-devtools / 空）

package/templates/scanUser.md

@@ -5,6 +5,6 @@
 profile 质量要求（harness 会校验）：
 - services 数组必须包含所有可启动服务（command、port、health_check），不得为空
 - existing_docs 必须列出所有实际存在的文档路径
-- 检查 .claude/CLAUDE.md 是否存在，若无则生成（WHAT/WHY/HOW 格式），并加入 existing_docs
+- 检查 .claude/CLAUDE.md 是否存在，若无则生成，并加入 existing_docs
 
 注意：本次只扫描项目，不分解任务。

package/templates/web-testing.md

@@ -0,0 +1,17 @@
+【浏览器测试规则提醒】
+
+## Smart Snapshot 策略（节省 40-60% Token）
+- 必须：首次加载页面、关键断言点、操作失败时
+- 跳过：连续同类操作间、等待循环中（改用 wait_for 类工具）
+- 高效模式：导航 → 快照 → 填写 → 选择 → 点击 → 等待 → 快照（仅 2 次）
+
+## 等待策略
+- 瞬时操作（导航、点击）：直接操作，不等待
+- 短等（表单提交）：wait_for 类工具，text="成功" timeout=10000
+- 长等（AI 生成、SSE 流式、文件处理）：wait_for + 合理 timeout（60-180s）
+- 禁止轮询快照等待，Token 消耗从 ~60K+ 降至 ~5K
+
+## 失败处理
+- 阻断性（服务未启动、500 错误、凭证缺失）：立即停止
+- 非阻断性（样式异常、console warning）：记录后继续
+- 失败流程：快照（记录状态）→ 控制台消息（错误日志）→ 停止该场景

package/types/index.d.ts

@@ -0,0 +1,217 @@
+import { WriteStream } from 'fs';
+
+// ─── Config ───────────────────────────────────────────────
+
+export interface Config {
+  provider?: string;
+  model?: string;
+  defaultOpus?: string;
+  maxTurns?: number;
+  stallTimeout: number;
+  editThreshold?: number;
+  webTestTool?: 'playwright' | 'chrome-devtools' | '';
+  webTestMode?: 'persistent' | 'isolated' | 'extension' | '';
+  simplifyInterval: number;
+  simplifyCommits: number;
+  [key: string]: unknown;
+}
+
+// ─── Main Options ─────────────────────────────────────────
+
+export interface MainOpts {
+  max?: number;
+  pause?: number;
+  dryRun?: boolean;
+  readFile?: string;
+  model?: string;
+  n?: number;
+  planOnly?: boolean;
+  interactive?: boolean;
+  reset?: boolean;
+  deployTemplates?: boolean;
+  projectRoot?: string;
+  reqFile?: string;
+}
+
+// ─── Session ──────────────────────────────────────────────
+
+export interface SessionRunOptions {
+  logFileName: string;
+  logStream?: WriteStream;
+  sessionNum?: number;
+  label?: string;
+  execute: (session: Session) => Promise<Record<string, unknown>>;
+}
+
+export interface QueryResult {
+  messages: SDKMessage[];
+  success: boolean;
+  subtype: string | null;
+  cost: number | null;
+  usage: { input_tokens: number; output_tokens: number } | null;
+  turns: number | null;
+}
+
+export interface RunQueryOpts {
+  onMessage?: (message: SDKMessage, messages: SDKMessage[]) => void | 'break';
+}
+
+export interface SDKMessage {
+  type: 'assistant' | 'tool_result' | 'result' | string;
+  message?: {
+    content?: Array<{
+      type: 'text' | 'tool_use' | string;
+      text?: string;
+      name?: string;
+      input?: Record<string, unknown>;
+    }>;
+  };
+  result?: string;
+  subtype?: string;
+  total_cost_usd?: number;
+  usage?: { input_tokens: number; output_tokens: number };
+  num_turns?: number;
+  is_error?: boolean;
+  content?: string;
+  [key: string]: unknown;
+}
+
+export interface SessionRunResult {
+  exitCode: number;
+  logFile: string | null;
+  stalled: boolean;
+  [key: string]: unknown;
+}
+
+export declare class Session {
+  static _sdk: unknown;
+
+  /** 确保 SDK 已加载（懒加载单例） */
+  static ensureSDK(config: Config): Promise<unknown>;
+
+  /** 创建 Session 实例并执行回调，自动管理生命周期 */
+  static run(type: string, config: Config, options: SessionRunOptions): Promise<SessionRunResult>;
+
+  readonly config: Config;
+  readonly type: string;
+  readonly indicator: Indicator;
+  logStream: WriteStream | null;
+  logFile: string | null;
+  hooks: unknown;
+  abortController: AbortController;
+
+  constructor(
+    type: string,
+    config: Config,
+    options: { logFileName: string; logStream?: WriteStream; sessionNum?: number; label?: string },
+  );
+
+  /** 构建 SDK query 选项，自动附加 hooks、abortController、权限模式 */
+  buildQueryOptions(overrides?: Record<string, unknown>): Record<string, unknown>;
+
+  /** 执行一次 SDK 查询，遍历消息流并收集结果 */
+  runQuery(prompt: string, queryOpts: Record<string, unknown>, opts?: RunQueryOpts): Promise<QueryResult>;
+
+  /** 检查会话是否因停顿超时 */
+  isStalled(): boolean;
+
+  /** 结束会话：清理 hooks、关闭日志流、停止 indicator */
+  finish(): void;
+}
+
+// ─── Indicator ────────────────────────────────────────────
+
+export declare class Indicator {
+  phase: 'thinking' | 'coding';
+  step: string;
+  toolTarget: string;
+  sessionNum: number;
+  startTime: number;
+  stallTimeoutMin: number;
+  toolRunning: boolean;
+  currentToolName: string;
+  projectRoot: string;
+
+  /** 启动 indicator 渲染循环 */
+  start(sessionNum: number, stallTimeoutMin: number, projectRoot: string): void;
+
+  /** 停止渲染循环并清除终端行 */
+  stop(): void;
+
+  updatePhase(phase: 'thinking' | 'coding'): void;
+  updateStep(step: string): void;
+  appendActivity(toolName: string, summary: string): void;
+  updateActivity(): void;
+
+  /** 标记工具开始执行 */
+  startTool(name: string): void;
+
+  /** 标记工具执行结束 */
+  endTool(): void;
+
+  pauseRendering(): void;
+  resumeRendering(): void;
+
+  /** 生成当前状态行文本 */
+  getStatusLine(): string;
+}
+
+/** 根据工具名称和输入推断当前阶段和步骤，更新 indicator 状态 */
+export declare function inferPhaseStep(
+  indicator: Indicator,
+  toolName: string,
+  toolInput: Record<string, unknown> | string,
+): void;
+
+// ─── Main ─────────────────────────────────────────────────
+
+/** 应用入口：初始化资产、加载配置、分发命令 */
+export declare function main(
+  command: string,
+  input: string,
+  opts?: MainOpts,
+): Promise<unknown>;
+
+// ─── Logging ──────────────────────────────────────────────
+
+/** 处理 SDK 消息并写入日志流 */
+export declare function logMessage(
+  message: SDKMessage,
+  logStream: WriteStream,
+  indicator?: Indicator,
+): void;
+
+/** 从消息列表中提取 type='result' 的消息 */
+export declare function extractResult(messages: SDKMessage[]): SDKMessage | null;
+
+/** 从消息列表中提取结果文本 */
+export declare function extractResultText(messages: SDKMessage[]): string;
+
+// ─── AssetManager ─────────────────────────────────────────
+
+export declare class AssetManager {
+  projectRoot: string | null;
+  loopDir: string | null;
+  assetsDir: string | null;
+  bundledDir: string;
+
+  init(projectRoot?: string): void;
+  path(name: string): string | null;
+  dir(name: string): string | null;
+  exists(name: string): boolean;
+  read(name: string): string | null;
+  readJson(name: string, fallback?: unknown): unknown;
+  write(name: string, content: string): void;
+  writeJson(name: string, data: unknown): void;
+  render(name: string, vars?: Record<string, string>): string;
+  ensureDirs(): void;
+  deployAll(): string[];
+  deployRecipes(): string[];
+
+  /** 解析 recipes 目录：先查项目 .claude-coder/recipes/，再 fallback 到 bundled */
+  recipesDir(): string;
+
+  clearCache(): void;
+}
+
+export declare const assets: AssetManager;

package/src/core/context.js

@@ -1,117 +0,0 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { loadConfig, buildEnvVars, log } = require('../common/config');
-const { Indicator } = require('../common/indicator');
-const { logMessage: baseLogMessage } = require('../common/logging');
-const { createHooks } = require('./hooks');
-const { assets } = require('../common/assets');
-
-class SessionContext {
-  constructor(type, opts = {}) {
-    this.type = type;
-    this.opts = opts;
-    assets.init(opts.projectRoot || process.cwd());
-    this.config = loadConfig();
-    this._applyEnvConfig();
-    this.indicator = new Indicator();
-    this.logStream = null;
-    this.logFile = null;
-    this.hooks = null;
-    this.cleanup = null;
-    this._isStalled = () => false;
-    this.abortController = new AbortController();
-    this._lastStatusKey = '';
-  }
-
-  _applyEnvConfig() {
-    Object.assign(process.env, buildEnvVars(this.config));
-  }
-
-  initLogging(logFileName, externalLogStream) {
-    if (externalLogStream) {
-      this.logStream = externalLogStream;
-      this._externalLogStream = true;
-    } else {
-      const logsDir = assets.dir('logs');
-      this.logFile = path.join(logsDir, logFileName);
-      this.logStream = fs.createWriteStream(this.logFile, { flags: 'a' });
-      this._externalLogStream = false;
-    }
-  }
-
-  initHooks(hookType) {
-    const stallTimeoutMs = this.config.stallTimeout * 1000;
-    const completionTimeoutMs = this.config.completionTimeout * 1000;
-    const result = createHooks(hookType, this.indicator, this.logStream, {
-      stallTimeoutMs,
-      abortController: this.abortController,
-      editThreshold: this.config.editThreshold,
-      completionTimeoutMs,
-    });
-    this.hooks = result.hooks;
-    this.cleanup = result.cleanup;
-    this._isStalled = result.isStalled;
-    return Math.floor(stallTimeoutMs / 60000);
-  }
-
-  startIndicator(sessionNum, stallTimeoutMin) {
-    this.indicator.start(sessionNum, stallTimeoutMin);
-  }
-
-  isStalled() {
-    return this._isStalled();
-  }
-
-  async runQuery(sdk, prompt, queryOpts) {
-    const collected = [];
-    const session = sdk.query({ prompt, options: queryOpts });
-
-    for await (const message of session) {
-      if (this._isStalled()) {
-        log('warn', '停顿超时，中断消息循环');
-        break;
-      }
-      collected.push(message);
-      this._logMessage(message);
-    }
-
-    return collected;
-  }
-
-  _logMessage(message) {
-    const hasText = message.type === 'assistant'
-      && message.message?.content?.some(b => b.type === 'text' && b.text);
-
-    if (hasText && this.indicator) {
-      this.indicator.pauseRendering();
-      process.stderr.write('\r\x1b[K');
-    }
-
-    baseLogMessage(message, this.logStream, this.indicator);
-
-    if (hasText && this.indicator) {
-      const contentKey = `${this.indicator.phase}|${this.indicator.step}|${this.indicator.toolTarget}`;
-      if (contentKey !== this._lastStatusKey) {
-        this._lastStatusKey = contentKey;
-        const statusLine = this.indicator.getStatusLine();
-        if (statusLine) process.stderr.write(statusLine + '\n');
-      }
-      this.indicator.resumeRendering();
-    }
-  }
-
-  finish() {
-    if (this.cleanup) this.cleanup();
-    if (this.logStream && !this._externalLogStream) this.logStream.end();
-    this.indicator.stop();
-  }
-
-  errorFinish(err) {
-    this.finish();
-    log('error', err.message);
-  }
-}
-
-module.exports = { SessionContext };