chatccc 0.2.6 → 0.2.7

package/README.md

@@ -63,24 +63,44 @@ npm run dev
 
 #### Cursor Agent CLI（使用 Cursor 会话时需要）
 
-ChatCCC **不捆绑** Cursor Agent CLI，需要用户自行安装。Cursor Agent CLI 目前主要有两种来源：
+ChatCCC **不捆绑** Cursor Agent CLI，需要用户自行安装。
+
+**推荐安装方式（Windows）：**
+
+在 PowerShell 中执行：
+
+```powershell
+irm 'https://cursor.com/install?win32=true' | iex
+```
+
+安装完成后 `agent` 命令会出现在系统 PATH 中。
+
+**其他安装方式：**
 
 1. **Cursor IDE 自带**：安装 [Cursor IDE](https://cursor.com) 后，部分版本会自带 `agent` 或 `cursor-agent` 命令
-2. **独立安装**：Cursor 正在逐步提供独立的 CLI 安装方式，安装后 `agent` 命令会出现在系统 PATH 中
+2. **独立安装**：Cursor 正在逐步提供独立的 CLI 安装方式
 
-验证是否已安装：
+验证是否已安装（任一可用即可）：
 
 ```bash
 agent --version
+cursor-agent --version
 ```
 
-若 `agent` 不在 PATH 中，可通过环境变量指定自定义命令：
+ChatCCC 启动时会按以下顺序探测 Cursor Agent CLI：
+
+1. 环境变量 `CHATCCC_CURSOR_COMMAND` 指定的路径（若已设置）
+2. Windows 上 Cursor IDE 默认安装位置 `%LOCALAPPDATA%\cursor-agent\agent.cmd`（自动识别）
+3. PATH 中的 `agent` 命令
+
+若以上都找不到，或你想用一个非默认的可执行文件（例如 `cursor-agent`），在 `.env` 中显式指定：
 
 ```env
 CHATCCC_CURSOR_COMMAND=/path/to/agent
-CHATCCC_CURSOR_ARGS=-p --output-format stream-json --stream-partial-output
 ```
 
+> 高级用户如需覆盖默认 CLI 参数，可设置 `CHATCCC_CURSOR_ARGS`，一般无需修改。
+
 > **说明**：只使用 Claude Code（`/new claude` 或 `/new`）的用户无需安装 Cursor CLI。
 
 ### 2. 创建飞书应用
@@ -132,14 +152,25 @@ CHATCCC_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxx
 
 若你曾使用旧版变量名 `FEISHU_CLAUDER_APP_ID` / `FEISHU_CLAUDER_APP_SECRET`，请改为上表中的 `CHATCCC_APP_ID` / `CHATCCC_APP_SECRET`。
 
-可选：Claude 模型与思考深度（**默认均为 `default`**）：
+可选：Claude 模型与思考深度：
 
 ```env
-# 网关或服务商文档中的 model；设为 default（任意大小写）或不写则交给 SDK/CLI 默认，且 /status 中显示为 default
+# 网关或服务商文档中的 model；设为 default（任意大小写）或不写则交给 SDK/CLI 默认
 CHATCCC_ANTHROPIC_MODEL=default
 
-# 如 low / medium / high / max；设为 default（任意大小写）或不写则不向 SDK 传入 effort，/status 显示 default
-CHATCCC_ANTHROPIC_EFFORT=default
+# 如 low / medium / high / max；设为 default（任意大小写）或不写则不向 SDK 传入 effort
+CHATCCC_ANTHROPIC_EFFORT=max
+```
+
+Cursor Agent CLI 模型（仅 Cursor 会话相关，省略或 `default` 时不传 `--model`）：
+
+```env
+# Cursor 会话实际使用的模型 ID（如 claude-opus-4-7-max / claude-opus-4-7-thinking-max 等）
+# 可用 `agent --list-models` 查看所有支持的模型 ID
+CHATCCC_CURSOR_MODEL=claude-opus-4-7-max
+
+# 高级用户可覆盖默认 CLI 参数（一般无需修改）
+# CHATCCC_CURSOR_ARGS=-p --force --output-format stream-json --stream-partial-output
 ```
 
 #### 注意！第三方 API（如 DeepSeek）与鉴权 403
@@ -172,7 +203,7 @@ CHATCCC_ANTHROPIC_EFFORT=default
 
 > **说明**：项目根目录的 `.env` 若通过 `tsx --env-file=.env` 加载，其中的变量会进入 Node 进程环境，**多数情况下**会随进程继承给 SDK 子进程；但各家网关与 Claude Code 版本组合较多，**仍推荐**将 **`ANTHROPIC_API_KEY`** 与 **`ANTHROPIC_BASE_URL`** 放在系统/用户环境变量中，与 `settings.json` 形成双保险，避免仅依赖 `.claude/settings.json` 时在 SDK 场景下踩坑。
 
-`**CHATCCC_PORT`（可选）**：默认端口为 `18080`。若在一台机器上同时运行多个 ChatCCC 实例，可在各自的 `.env` 中设置不同端口：
+**`CHATCCC_PORT`（可选）**：默认端口为 `18080`。若在一台机器上同时运行多个 ChatCCC 实例，可在各自的 `.env` 中设置不同端口：
 
 ```env
 # 实例 A（项目1）的 .env
@@ -184,6 +215,13 @@ CHATCCC_PORT=18081
 
 不同端口的实例互不冲突，启动时会自动清理各自端口上的旧进程。
 
+**`CHATCCC_GIT_TIMEOUT_SECONDS`（可选）**：`/git <子命令>` 在会话工作目录执行 git 命令时的单次超时秒数，默认 `180`，允许范围 `1–3600`。配置非法（非整数、越界等）时启动日志会标红提示并回退为默认值；命令超时则会被 `SIGKILL` 强制终止，并把已收集到的输出（带「⏱️ 命令超时被强制终止」标记）回发到群里。
+
+```env
+# 调高到 600 秒，适合 git fsck、git gc 等耗时操作
+CHATCCC_GIT_TIMEOUT_SECONDS=600
+```
+
 > **权限说明**：目前 ChatCCC 以 `bypassPermissions` 模式运行，即跳过所有权限确认、允许所有操作。后续会考虑引入细粒度权限控制，让你可以按需放行特定操作。
 
 > **Linux 用户注意**：不能将项目装在 `/root` 目录下运行。
@@ -204,6 +242,7 @@ CHATCCC_PORT=18081
 | `/status`       | 查看当前会话的状态（轮数、模型、上下文 token 等） |
 | `/cd`           | 查看/切换工作目录                    |
 | `/sessions`     | 查看所有会话状态                    |
+| `/git <子命令>` | 在**当前会话工作目录**执行 `git ...` 并把 stdout/stderr 回发到群里（仅会话群内可用，超时见 `CHATCCC_GIT_TIMEOUT_SECONDS`） |
 | `/restart`      | 重启机器人进程                      |
 
 
@@ -211,4 +250,4 @@ CHATCCC_PORT=18081
 
 ## 技术栈
 
-TypeScript / Node.js >= 20 / tsx / Anthropic Claude Agent SDK / 飞书 WebSocket API / CardKit
+TypeScript / Node.js >= 20 / tsx / Anthropic Claude Agent SDK / Cursor Agent CLI / 飞书 WebSocket API / CardKit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",

package/src/__tests__/adapter-interface.test.ts

@@ -1,152 +1,152 @@
-import { describe, it, expect } from "vitest";
-import type {
-  UnifiedBlock,
-  UnifiedStreamMessage,
-  UnifiedThinkingBlock,
-  UnifiedTextBlock,
-  UnifiedToolUseBlock,
-  UnifiedToolResultBlock,
-  UnifiedRedactedThinkingBlock,
-  UnifiedSearchResultBlock,
-  UnifiedCompactBoundaryBlock,
-  CreateSessionResult,
-  SessionInfo,
-  ToolAdapter,
-} from "../adapters/adapter-interface.ts";
-
-// ---------------------------------------------------------------------------
-// 编译期类型验证：确保 UnifiedBlock 联合类型覆盖了所有预期的 block 形状
-// ---------------------------------------------------------------------------
-
-describe("UnifiedBlock union type coverage", () => {
-  it("accepts thinking block", () => {
-    const b: UnifiedBlock = { type: "thinking", thinking: "Let me think..." };
-    expect(b.type).toBe("thinking");
-  });
-
-  it("accepts text block", () => {
-    const b: UnifiedBlock = { type: "text", text: "Hello" };
-    expect(b.type).toBe("text");
-  });
-
-  it("accepts tool_use block", () => {
-    const b: UnifiedBlock = { type: "tool_use", name: "Read", input: { file_path: "/tmp" } };
-    expect(b.type).toBe("tool_use");
-  });
-
-  it("accepts tool_result block with string content", () => {
-    const b: UnifiedBlock = { type: "tool_result", tool_use_id: "abc123", content: "result" };
-    expect(b.type).toBe("tool_result");
-  });
-
-  it("accepts tool_result block with error flag", () => {
-    const b: UnifiedBlock = { type: "tool_result", tool_use_id: "abc123", content: "error", is_error: true };
-    expect(b.is_error).toBe(true);
-  });
-
-  it("accepts redacted_thinking block", () => {
-    const b: UnifiedBlock = { type: "redacted_thinking" };
-    expect(b.type).toBe("redacted_thinking");
-  });
-
-  it("accepts search_result block", () => {
-    const b: UnifiedBlock = { type: "search_result", query: "what is TypeScript" };
-    expect(b.type).toBe("search_result");
-  });
-
-  it("accepts compact_boundary block", () => {
-    const b: UnifiedBlock = { type: "compact_boundary", trigger: "auto", pre_tokens: 10000, post_tokens: 5000 };
-    expect(b.type).toBe("compact_boundary");
-  });
-
-  it("accepts compact_boundary block without post_tokens", () => {
-    const b: UnifiedBlock = { type: "compact_boundary", trigger: "manual", pre_tokens: 20000 };
-    expect(b.type).toBe("compact_boundary");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// UnifiedStreamMessage
-// ---------------------------------------------------------------------------
-
-describe("UnifiedStreamMessage", () => {
-  it("accepts assistant message with blocks", () => {
-    const m: UnifiedStreamMessage = {
-      type: "assistant",
-      blocks: [
-        { type: "thinking", thinking: "..." },
-        { type: "text", text: "answer" },
-      ],
-    };
-    expect(m.type).toBe("assistant");
-    expect(m.blocks).toHaveLength(2);
-  });
-
-  it("accepts user message with tool_result blocks", () => {
-    const m: UnifiedStreamMessage = {
-      type: "user",
-      blocks: [{ type: "tool_result", tool_use_id: "abc", content: "ok" }],
-    };
-    expect(m.type).toBe("user");
-  });
-
-  it("accepts system message", () => {
-    const m: UnifiedStreamMessage = {
-      type: "system",
-      blocks: [{ type: "compact_boundary", trigger: "auto", pre_tokens: 100 }],
-    };
-    expect(m.type).toBe("system");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// CreateSessionResult
-// ---------------------------------------------------------------------------
-
-describe("CreateSessionResult", () => {
-  it("accepts valid result", () => {
-    const r: CreateSessionResult = { sessionId: "uuid-12345" };
-    expect(r.sessionId).toBe("uuid-12345");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// SessionInfo
-// ---------------------------------------------------------------------------
-
-describe("SessionInfo", () => {
-  it("accepts full info", () => {
-    const info: SessionInfo = {
-      sessionId: "abc",
-      cwd: "/home/user",
-      summary: "A session",
-      lastModified: 1234567890,
-    };
-    expect(info.sessionId).toBe("abc");
-  });
-
-  it("accepts minimal info (only sessionId)", () => {
-    const info: SessionInfo = { sessionId: "minimal" };
-    expect(info.cwd).toBeUndefined();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// ToolAdapter interface 结构断言
-// ---------------------------------------------------------------------------
-
-describe("ToolAdapter interface structure", () => {
-  it("has correct property names via mock object", () => {
-    // 如果 ToolAdapter 接口的字段名或函数签名变更，该对象字面量将无法编译
-    const mock: ToolAdapter = {
-      displayName: "Test",
-      sessionDescPrefix: "Test Session:",
-      createSession: async () => ({ sessionId: "s" }),
-      prompt: async function* () {},
-      getSessionInfo: async () => undefined,
-      closeSession: async () => {},
-    };
-    expect(mock.displayName).toBe("Test");
-    expect(mock.sessionDescPrefix).toBe("Test Session:");
-  });
+import { describe, it, expect } from "vitest";
+import type {
+  UnifiedBlock,
+  UnifiedStreamMessage,
+  UnifiedThinkingBlock,
+  UnifiedTextBlock,
+  UnifiedToolUseBlock,
+  UnifiedToolResultBlock,
+  UnifiedRedactedThinkingBlock,
+  UnifiedSearchResultBlock,
+  UnifiedCompactBoundaryBlock,
+  CreateSessionResult,
+  SessionInfo,
+  ToolAdapter,
+} from "../adapters/adapter-interface.ts";
+
+// ---------------------------------------------------------------------------
+// 编译期类型验证：确保 UnifiedBlock 联合类型覆盖了所有预期的 block 形状
+// ---------------------------------------------------------------------------
+
+describe("UnifiedBlock union type coverage", () => {
+  it("accepts thinking block", () => {
+    const b: UnifiedBlock = { type: "thinking", thinking: "Let me think..." };
+    expect(b.type).toBe("thinking");
+  });
+
+  it("accepts text block", () => {
+    const b: UnifiedBlock = { type: "text", text: "Hello" };
+    expect(b.type).toBe("text");
+  });
+
+  it("accepts tool_use block", () => {
+    const b: UnifiedBlock = { type: "tool_use", name: "Read", input: { file_path: "/tmp" } };
+    expect(b.type).toBe("tool_use");
+  });
+
+  it("accepts tool_result block with string content", () => {
+    const b: UnifiedBlock = { type: "tool_result", tool_use_id: "abc123", content: "result" };
+    expect(b.type).toBe("tool_result");
+  });
+
+  it("accepts tool_result block with error flag", () => {
+    const b: UnifiedBlock = { type: "tool_result", tool_use_id: "abc123", content: "error", is_error: true };
+    expect(b.is_error).toBe(true);
+  });
+
+  it("accepts redacted_thinking block", () => {
+    const b: UnifiedBlock = { type: "redacted_thinking" };
+    expect(b.type).toBe("redacted_thinking");
+  });
+
+  it("accepts search_result block", () => {
+    const b: UnifiedBlock = { type: "search_result", query: "what is TypeScript" };
+    expect(b.type).toBe("search_result");
+  });
+
+  it("accepts compact_boundary block", () => {
+    const b: UnifiedBlock = { type: "compact_boundary", trigger: "auto", pre_tokens: 10000, post_tokens: 5000 };
+    expect(b.type).toBe("compact_boundary");
+  });
+
+  it("accepts compact_boundary block without post_tokens", () => {
+    const b: UnifiedBlock = { type: "compact_boundary", trigger: "manual", pre_tokens: 20000 };
+    expect(b.type).toBe("compact_boundary");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// UnifiedStreamMessage
+// ---------------------------------------------------------------------------
+
+describe("UnifiedStreamMessage", () => {
+  it("accepts assistant message with blocks", () => {
+    const m: UnifiedStreamMessage = {
+      type: "assistant",
+      blocks: [
+        { type: "thinking", thinking: "..." },
+        { type: "text", text: "answer" },
+      ],
+    };
+    expect(m.type).toBe("assistant");
+    expect(m.blocks).toHaveLength(2);
+  });
+
+  it("accepts user message with tool_result blocks", () => {
+    const m: UnifiedStreamMessage = {
+      type: "user",
+      blocks: [{ type: "tool_result", tool_use_id: "abc", content: "ok" }],
+    };
+    expect(m.type).toBe("user");
+  });
+
+  it("accepts system message", () => {
+    const m: UnifiedStreamMessage = {
+      type: "system",
+      blocks: [{ type: "compact_boundary", trigger: "auto", pre_tokens: 100 }],
+    };
+    expect(m.type).toBe("system");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CreateSessionResult
+// ---------------------------------------------------------------------------
+
+describe("CreateSessionResult", () => {
+  it("accepts valid result", () => {
+    const r: CreateSessionResult = { sessionId: "uuid-12345" };
+    expect(r.sessionId).toBe("uuid-12345");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// SessionInfo
+// ---------------------------------------------------------------------------
+
+describe("SessionInfo", () => {
+  it("accepts full info", () => {
+    const info: SessionInfo = {
+      sessionId: "abc",
+      cwd: "/home/user",
+      summary: "A session",
+      lastModified: 1234567890,
+    };
+    expect(info.sessionId).toBe("abc");
+  });
+
+  it("accepts minimal info (only sessionId)", () => {
+    const info: SessionInfo = { sessionId: "minimal" };
+    expect(info.cwd).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ToolAdapter interface 结构断言
+// ---------------------------------------------------------------------------
+
+describe("ToolAdapter interface structure", () => {
+  it("has correct property names via mock object", () => {
+    // 如果 ToolAdapter 接口的字段名或函数签名变更，该对象字面量将无法编译
+    const mock: ToolAdapter = {
+      displayName: "Test",
+      sessionDescPrefix: "Test Session:",
+      createSession: async () => ({ sessionId: "s" }),
+      prompt: async function* () {},
+      getSessionInfo: async () => undefined,
+      closeSession: async () => {},
+    };
+    expect(mock.displayName).toBe("Test");
+    expect(mock.sessionDescPrefix).toBe("Test Session:");
+  });
 });