chatccc 0.2.0 → 0.2.2

package/README.md

@@ -67,21 +67,29 @@ npm run dev
 
 **添加应用能力**：开启「机器人」功能。
 
-**权限配置**（在「权限管理」中搜索并开通以下权限）：
+**权限配置（重要）**（在「权限管理」中按前缀搜索，**将以下三类前缀开头的权限全部开通**）：
 
+| 前缀 | 用途（简要） |
+| ---- | ------------ |
+| `im:message` | 收发与读取消息、以机器人身份发言、与会话相关的消息能力等 |
+| `im:chat` | 创建与管理群聊、与会话绑定、群成员与聊天场景相关能力等 |
+| `cardkit:` | 群卡片展示、流式更新、卡片按钮与交互回调相关能力等 |
 
-| 权限                              | 用途        |
-| ------------------------------- | --------- |
-| `im:chat`                       | 创建和管理群聊   |
-| `im:message`                    | 收发消息      |
-| `im:message:send_as_bot`        | 以机器人身份发消息 |
-| `im:message.p2p_msg:readonly`   | 读取私聊消息    |
-| `im:message.group_msg:readonly` | 读取群聊消息    |
+控制台中同一前缀下往往有多条子权限，请逐项勾选开通，避免遗漏导致收不到消息或卡片异常。
 
+<p align="center">
+  <img src="images/img_readme_permission.png" alt="飞书应用权限配置" width="280" />
+</p>
+
+**事件订阅（重要）**（在「事件与回调」中）：订阅 `im.message.receive_v1` 和 `card.action.trigger` 事件。
 
-**事件订阅**（在「事件与回调」中）：订阅 `im.message.receive_v1` 和 `card.action.trigger` 事件。
+<p align="center">
+  <img src="images/img_readme_event.png" alt="飞书事件订阅" width="280" />
+  &emsp;
+  <img src="images/img_readme_callback.png" alt="飞书请求网址与回调" width="280" />
+</p>
 
-**发布版本**：配置完成后创建应用版本并发布（仅企业内部可用即可）。
+**发布版本（不要忘了）**：配置完成后创建应用版本并发布（仅企业内部可用即可）。
 
 ### 3. 获取凭证
 
@@ -112,6 +120,36 @@ CHATCCC_ANTHROPIC_MODEL=default
 CHATCCC_ANTHROPIC_EFFORT=default
 ```
 
+#### 注意！第三方 API（如 DeepSeek）与鉴权 403
+
+若你通过 **Anthropic 兼容网关**（例如 DeepSeek 的 `/anthropic` 端点）调用模型，除了官方 Claude 以外，需要配置 **`ANTHROPIC_API_KEY`**（API 密钥）与 **`ANTHROPIC_BASE_URL`**（写入系统环境变量，见下表）。
+
+不少用户会把这些写在 **`~/.claude/settings.json`**（Windows 一般为 `C:\Users\<用户名>\.claude\settings.json`）的 `env` 字段里，供本机 **交互式 Claude Code** 使用。但 **Claude Agent SDK 在启动时拉起的是子进程**，其行为与直接打开终端跑 Claude Code 并不完全一致，**子进程未必会按你预期读取 `.claude` 目录下 `settings.json` 里的 `ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL` 等**，从而出现类似：
+
+`Failed to authenticate. API Error: 403 Request not allowed`
+
+**建议（最稳妥）**：把 **`ANTHROPIC_BASE_URL`** 与 **`ANTHROPIC_API_KEY`**（API 密钥）写进 **操作系统环境变量**（当前用户的「用户变量」即可，一般无需管理员），例如：
+
+| 变量名 | 说明 |
+| ------ | ---- |
+| `ANTHROPIC_API_KEY` | 在服务商控制台获取的 **API 密钥**，填入本环境变量。Anthropic 兼容网关普遍使用该名称；若服务商文档要求使用其它环境变量名，以文档为准。 |
+| `ANTHROPIC_BASE_URL` | 兼容 Anthropic API 的 base URL，例如 DeepSeek：`https://api.deepseek.com/anthropic` |
+
+若你在 `settings.json` 里还为 Sonnet/Haiku/Opus 配置了默认模型名，可一并同步到用户环境变量（如 `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 等），与文档及网关要求保持一致。
+
+修改环境变量后，请 **完全退出并重新打开** 终端、IDE（如 Cursor）以及 ChatCCC 进程，再试飞书对话或本地 `npm run demo:claude-hi`，确保子进程继承到新变量。
+
+在 **Windows** 上可用 PowerShell 写入当前用户的持久变量（示例，请把第二行里的字符串换成你在服务商控制台复制的 **API 密钥**，即 **`ANTHROPIC_API_KEY`** 的值）：
+
+```powershell
+[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.deepseek.com/anthropic", "User")
+[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "你的_API_密钥", "User")
+```
+
+也可在 **系统属性 → 环境变量** 中手动添加。Linux / macOS 可将 `export` 写入 `~/.bashrc`、`~/.zshrc` 等，或使用 systemd、`launchctl` 等按你的部署方式注入。
+
+> **说明**：项目根目录的 `.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` 中设置不同端口：
 
 ```env

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",
@@ -22,10 +22,11 @@
     "demo:bot-test:local": "tsx --env-file=.env demo/bot_test.ts --local",
     "demo:create-group": "tsx --env-file=.env src/index.ts",
     "demo:create-group:local": "tsx --env-file=.env src/index.ts --local",
-    "demo:permission-check": "tsx --env-file=.env demo/permission_check.ts"
+    "demo:permission-check": "tsx --env-file=.env demo/permission_check.ts",
+    "demo:claude-hi": "tsx --env-file=.env demo/claude_say_hi.ts"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.133",
+    "@anthropic-ai/claude-agent-sdk": "0.2.133",
     "@larksuiteoapi/node-sdk": "^1.59.0",
     "tsx": "^4.0.0",
     "ws": "^8.18.0"

package/src/feishu-api.ts

@@ -32,6 +32,134 @@ export async function getTenantAccessToken(): Promise<string> {
   return data.tenant_access_token;
 }
 
+// ---------------------------------------------------------------------------
+// Permission verification (startup check)
+// ---------------------------------------------------------------------------
+
+interface PermissionDef {
+  scope: string;
+  description: string;
+  method: "GET" | "POST" | "PATCH" | "DELETE";
+  path: string;
+  body?: string; // JSON string, supports __TOKEN__ placeholder
+}
+
+/** 项目所需的所有飞书权限及对应的非破坏性测试请求 */
+const REQUIRED_PERMISSIONS: PermissionDef[] = [
+  {
+    scope: "im:chat",
+    description: "读取/创建/更新群聊（创建会话群、改名、读群信息）",
+    method: "GET",
+    path: "/im/v1/chats?page_size=1",
+  },
+  {
+    scope: "im:message:send_as_bot",
+    description: "以机器人身份发送消息（文本/卡片回复）",
+    method: "POST",
+    path: "/im/v1/messages?receive_id_type=chat_id",
+    body: JSON.stringify({
+      receive_id: "oc_000000000000000000000000",
+      msg_type: "text",
+      content: JSON.stringify({ text: "permcheck" }),
+    }),
+  },
+  {
+    scope: "im:message:reaction",
+    description: "添加消息表情回应（Give a like）",
+    method: "POST",
+    path: "/im/v1/messages/om_000000000000000000000000/reactions",
+    body: JSON.stringify({ reaction_type: { emoji_type: "Get" } }),
+  },
+  {
+    scope: "im:message",
+    description: "撤回/更新消息（关闭卡片、撤回卡片消息）",
+    method: "PATCH",
+    path: "/im/v1/messages/om_000000000000000000000000",
+    body: JSON.stringify({ content: JSON.stringify({ elements: [{ tag: "markdown", content: " " }] }) }),
+  },
+];
+
+interface PermissionResult {
+  scope: string;
+  description: string;
+  ok: boolean;
+  detail: string;
+}
+
+/** 对单个权限做非破坏性探针请求。返回 false 表示权限缺失。 */
+async function probePermission(token: string, def: PermissionDef): Promise<PermissionResult> {
+  const url = `${BASE_URL}${def.path}`;
+  try {
+    const resp = await fetch(url, {
+      method: def.method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: def.body ?? undefined,
+    });
+    const data = (await resp.json()) as { code: number; msg?: string };
+    if (data.code === 0) {
+      return { scope: def.scope, description: def.description, ok: true, detail: "通过" };
+    }
+    const msg = (data.msg ?? "").toLowerCase();
+    // 飞书权限缺失时 msg 通常含 "permission" / "scope" / "denied" / "unauthorized"
+    // 权限 OK 但资源不存在时 msg 含 "not found" / "chat" / "message" / "不存在"
+    const deniedKeywords = ["permission", "scope", "denied", "unauthorized", "无权限", "权限", "access denied"];
+    const isDenied = deniedKeywords.some((kw) => msg.includes(kw));
+    if (isDenied) {
+      return { scope: def.scope, description: def.description, ok: false, detail: `权限缺失 → code=${data.code} msg=${data.msg}` };
+    }
+    // 资源不存在 = 通过了权限检查，只是目标资源不存在（预期内）
+    return { scope: def.scope, description: def.description, ok: true, detail: `通过（资源不存在: code=${data.code} msg=${data.msg}）` };
+  } catch (err) {
+    return { scope: def.scope, description: def.description, ok: false, detail: `网络异常: ${(err as Error).message}` };
+  }
+}
+
+/**
+ * 验证所有必需权限。返回失败的权限列表。
+ * 若全部通过返回空数组。
+ */
+export async function verifyAllPermissions(token: string): Promise<PermissionResult[]> {
+  const results: PermissionResult[] = [];
+  for (const def of REQUIRED_PERMISSIONS) {
+    const r = await probePermission(token, def);
+    results.push(r);
+  }
+  return results;
+}
+
+/** 输出权限验证结果到控制台和文件日志，并返回是否有失败 */
+export function reportPermissionResults(
+  results: PermissionResult[],
+  log: (msg: string) => void
+): boolean {
+  const failed = results.filter((r) => !r.ok);
+  const passed = results.filter((r) => r.ok);
+
+  log(`\n${"-".repeat(60)}`);
+  log(`[权限验证] 飞书应用权限检查完成: ${passed.length}/${results.length} 通过`);
+  for (const r of passed) {
+    log(`  [通过] ${r.scope} — ${r.description}`);
+  }
+  for (const r of failed) {
+    log(`  [失败] ${r.scope} — ${r.description}`);
+    log(`         原因: ${r.detail}`);
+  }
+  if (failed.length > 0) {
+    log(`\n[权限验证] 以下权限未在飞书开放平台中配置:`);
+    for (const r of failed) {
+      log(`  - ${r.scope}: ${r.description}`);
+    }
+    log(`\n请到飞书开放平台 → 应用详情 → 权限管理 中开通上述权限后重试。`);
+    log(`${"-".repeat(60)}\n`);
+  } else {
+    log(`${"-".repeat(60)}\n`);
+  }
+  return failed.length > 0;
+}
+
 // ---------------------------------------------------------------------------
 // Group chat CRUD
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -63,6 +63,8 @@ import {
   updateCardMessage,
   updateChatInfo,
   sendRestartCard,
+  verifyAllPermissions,
+  reportPermissionResults,
 } from "./feishu-api.ts";
 import { buildHelpCard, buildStatusCard, buildThinkingCardV2, buildCdContent, buildSessionsCard } from "./cards.ts";
 import { updateCardKitCard } from "./cardkit.ts";
@@ -281,9 +283,10 @@ async function handleCommand(text: string, chatId: string, openId: string, msgTi
       return;
     }
 
+    const cwd = await getDefaultCwd();
     await sendCardReply(
       freshToken, newChatId, "Claude Session Ready",
-      `群聊已创建，这是你的 Claude 会话群。\n\n**Session ID:** ${sessionId}\n\n直接在这里发消息即可与 Claude 对话。`,
+      `群聊已创建，这是你的 Claude 会话群。\n\n**Session ID:** ${sessionId}\n**工作目录:** \`${cwd}\`\n\n直接在这里发消息即可与 Claude 对话。\n\n发送 **/sessions** 查看所有会话状态。`,
       "green"
     );
 
@@ -464,14 +467,14 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  console.log(`\n[启动 1/6] 单实例：按 PID 文件清理旧 ChatCCC 进程`);
+  console.log(`\n[启动 1/7] 单实例：按 PID 文件清理旧 ChatCCC 进程`);
   console.log(`  PID 文件: ${PID_FILE}`);
   appendStartupTrace("main: before ensureSingleInstance", { PID_FILE, CHATCCC_PORT });
   ensureSingleInstance(PID_FILE);
   appendStartupTrace("main: after ensureSingleInstance");
   console.log("  完成。\n");
 
-  console.log(`[启动 2/6] 环境与凭证检查`);
+  console.log(`[启动 2/7] 环境与凭证检查`);
   reportEnvironmentVariableReadout();
   console.log(`  工作目录: ${process.cwd()}`);
   console.log(`  包根目录: ${PROJECT_ROOT}`);
@@ -485,7 +488,7 @@ async function main(): Promise<void> {
   console.log(`  必填项校验通过（App ID 摘要: ${maskAppId(APP_ID)}）。\n`);
   appendStartupTrace("main: feishu credentials ok", { appIdMask: maskAppId(APP_ID) });
 
-  console.log(`[启动 3/6] 启动本地 WebSocket 中继（ws://127.0.0.1:${CHATCCC_PORT}）…`);
+  console.log(`[启动 3/7] 启动本地 WebSocket 中继（ws://127.0.0.1:${CHATCCC_PORT}）…`);
   appendStartupTrace("main: before freeRelayListenPort", { CHATCCC_PORT });
   freeRelayListenPort(CHATCCC_PORT);
   appendStartupTrace("main: after freeRelayListenPort", { CHATCCC_PORT });
@@ -501,7 +504,7 @@ async function main(): Promise<void> {
   console.log(`  In a Claude session group, send any message to resume & prompt.`);
   console.log(`${"=".repeat(60)}`);
 
-  console.log(`\n[启动 4/6] 向飞书开放平台申请 tenant_access_token …`);
+  console.log(`\n[启动 4/7] 向飞书开放平台申请 tenant_access_token …`);
   let token: string;
   try {
     token = await getTenantAccessToken();
@@ -510,15 +513,34 @@ async function main(): Promise<void> {
     console.error("  失败：无法获取 tenant_access_token。");
     console.error(`  接口: POST ${BASE_URL}/auth/v3/tenant_access_token/internal`);
     console.error("  常见原因:");
+    console.error(
+      "    - 本机网络无法访问 open.feishu.cn（可尝试：关闭系统/终端代理、检查防火墙；Windows 可管理员运行 netsh winsock reset 后重启）",
+    );
     console.error("    - App ID / App Secret 与开放平台「凭证与基础信息」不一致");
     console.error("    - 自建应用尚未创建/发布可用版本");
-    console.error("    - 本机网络无法访问 open.feishu.cn");
     console.error(`  详情: ${msg}`);
     printServiceDidNotStart("无法从飞书开放平台获取 tenant_access_token（凭证或网络问题）");
     process.exit(1);
   }
   console.log(`  完成。当前 App ID 摘要: ${maskAppId(APP_ID)}\n`);
 
+  console.log(`\n[启动 5/7] 验证飞书应用权限（非破坏性探针）…`);
+  const permResults = await verifyAllPermissions(token);
+  const hasFailed = reportPermissionResults(permResults, (msg) => {
+    console.log(msg);
+  });
+  if (hasFailed) {
+    appendStartupTrace("main: permissions check failed", {
+      failed: permResults.filter((r) => !r.ok).map((r) => r.scope).join(", "),
+    });
+    printServiceDidNotStart(
+      `飞书权限不足: ${permResults.filter((r) => !r.ok).map((r) => r.scope).join(", ")}`
+    );
+    process.exit(1);
+  }
+  appendStartupTrace("main: permissions check ok");
+  console.log(`  完成。所有必需权限已验证通过。\n`);
+
   console.log(`[${ts()}] [AUTH] Token obtained`);
 
   const eventDispatcher = new EventDispatcher({});
@@ -613,14 +635,14 @@ async function main(): Promise<void> {
   });
 
   if (USE_LOCAL) {
-    console.log(`\n[启动 5/6] 本地区 relay 模式：正在连接 ${LOCAL_RELAY_URL} …`);
+    console.log(`\n[启动 6/7] 本地区 relay 模式：正在连接 ${LOCAL_RELAY_URL} …`);
     console.log("  若失败：请先在 SDK 模式下启动主进程，或确认本机中继已在该地址监听。");
     let localRelayOpened = false;
     const ws = new WebSocket(LOCAL_RELAY_URL);
     ws.on("open", () => {
       localRelayOpened = true;
       console.log("[WS] Connected to local relay");
-      console.log("[启动 6/6] 已连接本地中继，可接收转发事件。\n");
+      console.log("[启动 7/7] 已连接本地中继，可接收转发事件。\n");
       printServiceRunningHint("local");
     });
     ws.on("message", (raw: Buffer) => {
@@ -648,7 +670,7 @@ async function main(): Promise<void> {
     ws.on("close", () => { console.log("[WS] Local relay disconnected"); process.exit(0); });
     ws.on("error", (err: Error) => {
       if (!localRelayOpened) {
-        console.error(`[启动 5/6] 失败：无法连接本地中继。`);
+        console.error(`[启动 6/7] 失败：无法连接本地中继。`);
         console.error(`  ${err.message}`);
         console.error(`  目标: ${LOCAL_RELAY_URL}`);
         printServiceDidNotStart(`无法连接本地中继 ${LOCAL_RELAY_URL}`);
@@ -666,7 +688,7 @@ async function main(): Promise<void> {
       onReconnected: () => resetState(),
     });
 
-    console.log(`\n[启动 5/6] 飞书长连接：正在通过 SDK 建立 WebSocket …`);
+    console.log(`\n[启动 6/7] 飞书长连接：正在通过 SDK 建立 WebSocket …`);
     try {
       await wsClient.start({ eventDispatcher });
     } catch (err) {
@@ -678,7 +700,7 @@ async function main(): Promise<void> {
       process.exit(1);
     }
     console.log("[WS] Feishu WebSocket connected (SDK)");
-    console.log("[启动 6/6] 服务已就绪，等待飞书消息（群聊 / 卡片回调）。\n");
+    console.log("[启动 7/7] 服务已就绪，等待飞书消息（群聊 / 卡片回调）。\n");
     printServiceRunningHint("sdk");
 
     sendRestartCard(token).catch((err) =>