chatccc 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,106 @@
+# ChatCCC
+
+**飞书聊天控制 Claude Code，未来支持 Cursor、Codex**
+
+---
+
+## 解决的核心痛点
+
+传统的 Claude Code（尤其是使用第三方 API 的，如 DeepSeek），需要坐在电脑桌前才能用。**离开电脑就没法用了。**
+
+ChatCCC 把 Claude Code 接入了飞书群聊：
+
+- **手机上也能用 Claude Code** —— 在飞书群里发消息就等于在终端输入指令，Claude 的思考和回复会流式展示在群卡片里
+- **多会话并行** —— 一个群就是一个 Claude 会话，完全隔离、互不干扰，并行工作效率更高
+- **流式打字机效果** —— 体验丝滑，流式输出响应迅速
+
+一句话：**在任何设备上打开飞书，就能让 Claude 帮你写代码、排查问题、分析项目。**
+
+---
+
+## 怎么部署
+
+### 1. 创建飞书应用
+
+打开 [飞书开放平台](https://open.feishu.cn)，创建一个**企业自建应用**。
+
+**添加应用能力**：开启「机器人」功能。
+
+**权限配置**（在「权限管理」中搜索并开通以下权限）：
+
+| 权限 | 用途 |
+|------|------|
+| `im:chat` | 创建和管理群聊 |
+| `im:message` | 收发消息 |
+| `im:message:send_as_bot` | 以机器人身份发消息 |
+| `im:message.p2p_msg:readonly` | 读取私聊消息 |
+| `im:message.group_msg:readonly` | 读取群聊消息 |
+
+**事件订阅**（在「事件与回调」中）：订阅 `im.message.receive_v1` 和 `card.action.trigger` 事件。
+
+**发布版本**：配置完成后创建应用版本并发布（仅企业内部可用即可）。
+
+### 2. 获取凭证
+
+在飞书应用详情页的「凭证与基础信息」中，复制 **App ID** 和 **App Secret**。
+
+### 3. 配置环境变量
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env`，填入上一步拿到的凭证：
+
+```env
+FEISHU_CLAUDER_APP_ID=cli_xxxxxxxxxxxx
+FEISHU_CLAUDER_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+可选的高级配置：
+
+```env
+# Claude 模型（见下方优先级说明）
+CHATCCC_ANTHROPIC_MODEL=dashscope/deepseek-v4-pro-anthropic
+
+# 思考深度，可选值: low | medium | high | max
+CHATCCC_ANTHROPIC_EFFORT=max
+```
+
+**`CHATCCC_ANTHROPIC_MODEL` 优先级**：环境变量设置的值 > 代码内默认值 `dashscope/deepseek-v4-pro-anthropic`。不设或设为空白时自动使用默认模型。
+
+**`CHATCCC_ANTHROPIC_EFFORT` 优先级**：环境变量设置的值 > 代码内默认值 `max`。
+
+> **权限说明**：目前 ChatCCC 以 `bypassPermissions` 模式运行，即跳过所有权限确认、允许所有操作。后续会考虑引入细粒度权限控制，让你可以按需放行特定操作。
+
+> **Linux 用户注意**：不能将项目装在 `/root` 目录下运行。
+
+### 4. 安装依赖并启动
+
+```bash
+# 要求 Node.js >= 20
+npm install
+npm run dev
+```
+
+启动后机器人通过 WebSocket 连接飞书服务器，日志会写入 `logs/` 目录。
+
+### 5. 开始使用
+
+在飞书中找到你的机器人，发送 `/new`，机器人会自动创建一个群聊并把你的 Claude 会话绑定到该群。之后直接在群里发消息就能和 Claude 对话。
+
+### 可用指令
+
+| 指令 | 作用 |
+|------|------|
+| `/new` | 创建新的 Claude 会话（绑定一个新群聊） |
+| `/stop` | 停止当前正在生成的回复 |
+| `/status` | 查看当前会话的状态（轮数、模型、上下文 token 等） |
+| `/cd` | 查看/切换工作目录 |
+| `/restart` | 重启机器人进程 |
+
+---
+
+## 技术栈
+
+TypeScript / Node.js >= 20 / tsx / Anthropic Claude Agent SDK / 飞书 WebSocket API / CardKit

package/bin/chatccc.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { register } from "node:module";
+import { pathToFileURL } from "node:url";
+
+register("tsx/esm", pathToFileURL("./"));
+
+await import("../src/index.js");

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "chatccc",
+  "version": "0.1.0",
+  "description": "Feishu bot bridge for Claude Code",
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "chatccc": "./bin/chatccc.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "tsx --env-file=.env src/index.ts",
+    "chatccc": "tsx --env-file=.env src/index.ts",
+    "start": "tsx --env-file=.env src/index.ts",
+    "demo:bot-test": "tsx --env-file=.env demo/bot_test.ts",
+    "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"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.133",
+    "@larksuiteoapi/node-sdk": "^1.59.0",
+    "tsx": "^4.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cardkit.ts

@@ -0,0 +1,158 @@
+import { BASE_URL, fileLog, ts } from "./config.ts";
+
+// CardKit 是飞书的卡片流式更新 API，通过 cardElement.content 端点
+// 对卡片上指定 element_id 的元素进行增量内容更新，实现打字机效果。
+// 与普通卡片 PATCH 的区别：PATCH 是全量替换卡片 JSON，CardKit 是
+// 由飞书客户端自行渲染增量文本，用户看到的是逐字出现的效果。
+// 参考: https://open.feishu.cn/document/uYjLw4iNukDO6YDN4ITM4MjM
+
+export async function createCardKitCard(token: string, cardJson: string): Promise<string> {
+  const body = JSON.stringify({ type: "card_json", data: cardJson });
+  const resp = await fetch(`${BASE_URL}/cardkit/v1/cards`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body,
+  });
+  const respText = await resp.text();
+  let data: { code: number; msg?: string; data?: { card_id?: string } };
+  try {
+    data = JSON.parse(respText);
+  } catch {
+    console.error(`[${ts()}] [CARDIKT] createCard: invalid JSON response (status=${resp.status}) body=${respText.slice(0, 500)}`);
+    fileLog.flush();
+    throw new Error(`CardKit create: invalid JSON response (status=${resp.status})`);
+  }
+  if (data.code !== 0) {
+    console.error(`[${ts()}] [CARDIKT] createCard FAIL: status=${resp.status} code=${data.code} msg="${data.msg}" body=${respText.slice(0, 500)}`);
+    fileLog.flush();
+    throw new Error(`CardKit create: [${data.code}] ${data.msg}`);
+  }
+  console.log(`[${ts()}] [CARDIKT] createCard OK cardId=${data.data?.card_id ?? "(none)"}`);
+  return data.data?.card_id ?? "";
+}
+
+export async function setCardKitSettings(
+  token: string,
+  cardId: string,
+  settings: Record<string, unknown>,
+  sequence: number
+): Promise<void> {
+  const resp = await fetch(`${BASE_URL}/cardkit/v1/cards/${cardId}/settings`, {
+    method: "PATCH",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ settings: JSON.stringify(settings), sequence }),
+  });
+  const respText = await resp.text();
+  let data: { code: number; msg?: string };
+  try { data = JSON.parse(respText); } catch {
+    console.error(`[${ts()}] [CARDIKT] settings FAIL: invalid JSON cardId=${cardId} seq=${sequence} status=${resp.status}`);
+    fileLog.flush();
+    throw new Error(`CardKit settings: invalid JSON (status=${resp.status})`);
+  }
+  if (data.code !== 0) {
+    console.error(`[${ts()}] [CARDIKT] settings FAIL: cardId=${cardId} seq=${sequence} status=${resp.status} code=${data.code} msg="${data.msg}"`);
+    fileLog.flush();
+    throw new Error(`CardKit settings: [${data.code}] ${data.msg}`);
+  }
+  console.log(`[${ts()}] [CARDIKT] settings OK cardId=${cardId} seq=${sequence}`);
+}
+
+export async function streamCardKitElement(
+  token: string,
+  cardId: string,
+  elementId: string,
+  content: string,
+  sequence: number
+): Promise<void> {
+  const resp = await fetch(
+    `${BASE_URL}/cardkit/v1/cards/${cardId}/elements/${elementId}/content`,
+    {
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ content, sequence }),
+    }
+  );
+  const respText = await resp.text();
+  let data: { code: number; msg?: string };
+  try { data = JSON.parse(respText); } catch {
+    console.error(`[${ts()}] [CARDIKT] streamElement FAIL: invalid JSON cardId=${cardId} element=${elementId} seq=${sequence} status=${resp.status}`);
+    fileLog.flush();
+    throw new Error(`CardKit stream: invalid JSON (status=${resp.status})`);
+  }
+  if (data.code !== 0) {
+    console.error(`[${ts()}] [CARDIKT] streamElement FAIL: cardId=${cardId} element=${elementId} seq=${sequence} status=${resp.status} code=${data.code} msg="${data.msg}"`);
+    fileLog.flush();
+    throw new Error(`CardKit stream: [${data.code}] ${data.msg}`);
+  }
+  // success log is intentionally sparse — uncomment to debug streaming throughput
+  // console.log(`[${ts()}] [CARDIKT] streamElement OK cardId=${cardId} seq=${sequence}`);
+}
+
+export async function updateCardKitCard(
+  token: string,
+  cardId: string,
+  cardJson: string,
+  sequence: number
+): Promise<void> {
+  const resp = await fetch(`${BASE_URL}/cardkit/v1/cards/${cardId}`, {
+    method: "PUT",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ card: { type: "card_json", data: cardJson }, sequence }),
+  });
+  const respText = await resp.text();
+  let data: { code: number; msg?: string };
+  try { data = JSON.parse(respText); } catch {
+    console.error(`[${ts()}] [CARDIKT] updateCard FAIL: invalid JSON cardId=${cardId} seq=${sequence} status=${resp.status}`);
+    fileLog.flush();
+    throw new Error(`CardKit update: invalid JSON (status=${resp.status})`);
+  }
+  if (data.code !== 0) {
+    console.error(`[${ts()}] [CARDIKT] updateCard FAIL: cardId=${cardId} seq=${sequence} status=${resp.status} code=${data.code} msg="${data.msg}"`);
+    fileLog.flush();
+    throw new Error(`CardKit update: [${data.code}] ${data.msg}`);
+  }
+  console.log(`[${ts()}] [CARDIKT] updateCard OK cardId=${cardId} seq=${sequence}`);
+}
+
+export async function sendCardKitMessage(
+  token: string,
+  chatId: string,
+  cardId: string
+): Promise<string> {
+  const payload = { receive_id: chatId, msg_type: "interactive", content: JSON.stringify({ type: "card", data: { card_id: cardId } }) };
+  const url = `${BASE_URL}/im/v1/messages?receive_id_type=chat_id`;
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(payload),
+  });
+  const respText = await resp.text();
+  let data: { code: number; msg?: string; data?: { message_id?: string } };
+  try { data = JSON.parse(respText); } catch {
+    console.error(`[${ts()}] [CARDIKT] sendMessage FAIL: invalid JSON cardId=${cardId} chatId=${chatId} status=${resp.status}`);
+    fileLog.flush();
+    throw new Error(`sendCardKitMessage: invalid JSON (status=${resp.status})`);
+  }
+  if (data.code !== 0) {
+    console.error(`[${ts()}] [CARDIKT] sendMessage FAIL: status=${resp.status} code=${data.code} msg="${data.msg}" cardId=${cardId} chatId=${chatId}`);
+    fileLog.flush();
+    throw new Error(`[${data.code}] ${data.msg}`);
+  }
+  console.log(`[${ts()}] [CARDIKT] sendMessage OK cardId=${cardId} chatId=${chatId} msgId=${data.data?.message_id ?? "(none)"}`);
+  return data.data?.message_id ?? "";
+}

package/src/cards.ts

@@ -0,0 +1,170 @@
+// ---------------------------------------------------------------------------
+// Button helpers
+// ---------------------------------------------------------------------------
+
+export interface ButtonDef {
+  text: string;
+  value: string;
+  type?: "primary" | "default" | "danger";
+}
+
+export function buildButtons(buttons: ButtonDef[]): object {
+  return {
+    tag: "action",
+    actions: buttons.map((b) => ({
+      tag: "button",
+      text: { tag: "plain_text", content: b.text },
+      type: b.type ?? "primary",
+      value: b.value,
+    })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Content helpers
+// ---------------------------------------------------------------------------
+
+export function truncateContent(text: string, maxLines = 20, maxChars = 8000): string {
+  const lines = text.split("\n");
+  let displayText: string;
+  if (lines.length > maxLines) {
+    const firstLine = lines[0];
+    const lastLines = lines.slice(-(maxLines - 1)).join("\n");
+    displayText = firstLine + "\n...\n" + lastLines;
+  } else {
+    displayText = text;
+  }
+
+  if (displayText.length > maxChars) {
+    displayText = "..." + displayText.slice(-maxChars);
+  }
+
+  return displayText;
+}
+
+export function getToolEmoji(name: string): string {
+  const n = name.toLowerCase();
+  if (n.includes("read") || n.includes("cat")) return "\u{1F4D6}";        // 📖
+  if (n.includes("write")) return "\u{270D}\u{FE0F}";                    // ✍️
+  if (n.includes("edit")) return "\u{270F}\u{FE0F}";                     // ✏️
+  if (n.includes("grep") || n.includes("search")) return "\u{1F50E}";    // 🔎
+  if (n.includes("glob") || n.includes("find") || n.includes("ls")) return "\u{1F4C2}"; // 📂
+  if (n.includes("bash") || n.includes("shell") || n.includes("exec")) return "\u{1F5A5}\u{FE0F}"; // 🖥️
+  if (n.includes("websearch") || n.includes("web_search")) return "\u{1F310}"; // 🌐
+  if (n.includes("webfetch") || n.includes("web_fetch") || n.includes("fetch")) return "\u{1F4E5}"; // 📥
+  if (n.includes("todo") || n.includes("task")) return "\u{2705}";       // ✅
+  if (n.includes("agent")) return "\u{1F916}";                           // 🤖
+  if (n.includes("notebook")) return "\u{1F4D3}";                        // 📓
+  if (n.includes("ask") || n.includes("question")) return "\u{2753}";    // ❓
+  return "\u{1F527}";                                                     // 🔧
+}
+
+// ---------------------------------------------------------------------------
+// Card builders
+// ---------------------------------------------------------------------------
+
+// CardKit schema 2.0 思考卡片（带停止按钮，支持打字机流式更新）
+export function buildThinkingCardV2(
+  thinkingText: string,
+  opts: { showStop?: boolean; headerTitle?: string; headerTemplate?: string } = {}
+): string {
+  const { showStop = true, headerTitle = "思考中...", headerTemplate = "blue" } = opts;
+  const elements: object[] = [
+    { tag: "markdown", content: truncateContent(thinkingText), element_id: "main_content" },
+  ];
+  if (showStop) {
+    elements.push({ tag: "hr" });
+    elements.push({
+      tag: "button",
+      text: { tag: "plain_text", content: "查看状态（/status）" },
+      type: "default",
+      value: { action: "status" },
+      element_id: "action_status",
+    });
+    elements.push({
+      tag: "button",
+      text: { tag: "plain_text", content: "停止生成（/stop）" },
+      type: "danger",
+      value: { action: "stop" },
+      element_id: "action_stop",
+    });
+  }
+  return JSON.stringify({
+    schema: "2.0",
+    config: {
+      update_multi: true,
+      streaming_mode: showStop,
+    },
+    header: {
+      template: headerTemplate,
+      title: { tag: "plain_text", content: headerTitle },
+    },
+    body: {
+      direction: "vertical",
+      elements,
+    },
+  });
+}
+
+export function buildHelpCard(userText: string): string {
+  return JSON.stringify({
+    config: { wide_screen_mode: true },
+    header: { template: "blue", title: { content: "ChatCCC", tag: "plain_text" } },
+    elements: [
+      { tag: "div", text: { tag: "lark_md", content: `你发送了: ${userText}` } },
+      buildButtons([
+        { text: "新建会话（/new）", value: JSON.stringify({ cmd: "new" }), type: "primary" },
+        { text: "重启Chat CCC（/restart）", value: JSON.stringify({ cmd: "restart" }), type: "danger" },
+        { text: "查看/切换工作路径（/cd）", value: JSON.stringify({ cmd: "cd" }), type: "default" },
+      ]),
+    ],
+  });
+}
+
+// 工作路径内容（/cd 命令统一使用，返回 markdown 内容字符串）
+export function buildCdContent(
+  dirPath: string,
+  entries: { name: string; isDir: boolean }[],
+  isUpdate: boolean,
+  maxFiles = 100
+): string {
+  const display = entries.slice(0, maxFiles);
+  const overflow = entries.length > maxFiles ? `\n...（共 ${entries.length} 个条目，仅显示前 ${maxFiles} 个）` : "";
+  const listing = display.map(e => e.isDir ? `📁 ${e.name}/` : `📄 ${e.name}`).join("\n");
+
+  const statusLine = isUpdate
+    ? `**工作路径已更新为:** \`${dirPath}\``
+    : `**当前工作路径:** \`${dirPath}\``;
+
+  return [
+    statusLine,
+    ``,
+    `此路径持久化在配置文件中，仅影响**新建会话**的工作路径。`,
+    ``,
+    `---`,
+    `**目录内容** (最多 ${maxFiles} 个):`,
+    listing,
+    overflow,
+  ].join("\n");
+}
+
+// 状态卡片（带关闭按钮）
+export function buildStatusCard(statusText: string, template = "blue"): string {
+  return JSON.stringify({
+    config: { wide_screen_mode: true },
+    header: { template, title: { content: "会话状态", tag: "plain_text" } },
+    elements: [
+      { tag: "div", text: { tag: "lark_md", content: statusText } },
+      { tag: "hr" },
+      {
+        tag: "action",
+        actions: [{
+          tag: "button",
+          text: { tag: "plain_text", content: "收起" },
+          type: "default",
+          value: { action: "close" },
+        }],
+      },
+    ],
+  });
+}