cc-ding 0.1.0 → 0.3.0-beta

package/README.md

@@ -4,29 +4,37 @@
 [![npm downloads](https://img.shields.io/npm/dm/cc-ding.svg?style=flat-square)](https://www.npmjs.com/package/cc-ding)
 [![License](https://img.shields.io/npm/l/cc-ding.svg?style=flat-square)](LICENSE)
 [![Node.js](https://img.shields.io/node/v/cc-ding.svg?style=flat-square)](https://nodejs.org)
+[![GitHub stars](https://img.shields.io/github/stars/yihuineng/cc-ding.svg?style=flat-square)](https://github.com/yihuineng/cc-ding/stargazers)
 
-将钉钉机器人接入本地 [Claude Code](https://claude.ai/code)，实现群聊多轮对话、任务队列、定时任务等能力。
+> 将 Claude Code 接入钉钉，构建企业级 AI 协作工作流。
+>
+> Connect Claude Code to DingTalk for enterprise-grade AI collaboration.
 
-## 功能特性
+**[中文](#中文--简体中文)** | **[English](#english)**
 
-- **多轮对话** — 支持私聊 / 群聊多轮会话，`/new` `/end` `/resume` 灵活切换
-- **群内多用户** — 白名单内所有成员均可参与同一会话
-- **任务队列** — `/task` 提交任务，按队列顺序执行，完成后自动回复
-- **定时任务** — 自然语言创建 cron，支持暂停 / 恢复 / 删除
-- **图片消息** — 自动接收钉钉图片 / 富文本内嵌图片，可选本地 OCR 识别
-- **API Key 池化** — 429 自动切换、跨天重置，提升服务稳定性
-- **关联群** — 多个群共享同一个 Claude 会话上下文
+---
 
-## 快速开始
+## 中文 | 简体中文
 
-### 安装
+将 Claude Code 接入钉钉，实现双向通信。支持多轮对话、任务队列、定时任务、图片识别，帮助团队以最低成本构建可私有化部署的 AI 助手。
+
+### 目录
+
+- [快速开始](#快速开始)
+- [命令参考](#命令参考)
+- [配置说明](#配置说明)
+- [数据存储](#数据存储)
+- [开发](#开发)
+
+### 快速开始
+
+#### 安装
 
 ```bash
 pnpm i cc-ding -g
-cc-ding --help
 ```
 
-### 1. 初始化配置
+#### 初始化
 
 ```bash
 cc-ding init -ci {clientId} -cs {clientSecret} -m {手机号}
@@ -34,107 +42,78 @@ cc-ding init -ci {clientId} -cs {clientSecret} -m {手机号}
 
 | 参数 | 说明 |
 |------|------|
-| `-ci, --clientId` | 钉钉应用的 ClientId |
+| `-ci, --clientId` | 钉钉应用 ClientId |
 | `-cs, --clientSecret` | 钉钉 Stream 连接密钥 |
 | `-m, --mobile` | 管理员手机号（自动加入白名单） |
 | `-cn, --clientName` | 机器人名称（可选，默认 "cc助手"） |
 
-### 2. 编辑配置
+#### 编辑配置
 
-配置文件位于 `~/.cc-ding/{clientId}/config.json`，按 [配置文件示例](#配置文件示例) 补充 `conversations` 等字段。
+配置文件位于 `~/.cc-ding/{clientId}/config.json`，参考下方 [配置文件示例](#配置文件示例)。
 
-### 3. 启动
+#### 启动
 
 ```bash
 # 直接启动
 cc-ding run -ci {clientId}
 
-# 推荐：PM2 守护进程方式
+# 推荐：PM2 守护进程
 pm2 start --name "cc-ding-{clientId}" npx -- -p cc-ding cc-ding run -ci {clientId}
 ```
 
-## 使用指南
+### 命令参考
 
-### 会话模式
+#### 会话
 
 | 命令 | 说明 |
 |------|------|
-| `/help` | 查看所有可用命令 |
-| `/log [行数]` | 查看最近会话日志 |
-| `/new [初始消息]` | 开始新的对话 |
-| `/resume [会话ID]` | 继续历史会话（不指定则恢复最近一个） |
+| `/help` | 查看所有命令 |
+| `/log [行数]` | 查看会话日志 |
+| `/new [消息]` | 开始新对话 |
+| `/resume [ID]` | 恢复历史会话（不指定则恢复最近一个） |
 | `/end` | 结束当前会话 |
 
-- 会话自动持久化到 `active.json`，服务重启后自动恢复
-- 群内所有白名单用户均可参与对话
+> 会话自动持久化到 `active.json`，重启后无缝恢复。群内所有白名单用户均可参与。
 
-### 任务模式
+#### 任务
 
 ```
-/task <任务描述>      # 提交任务到队列
-/task cancel          # 取消任务
+/task <描述>       # 提交任务（自动排队顺序执行）
+/task cancel       # 取消任务
 ```
 
-### 定时任务
+#### 定时任务
 
 ```
-/cron <自然语言描述>              # Claude 自动生成 cron 表达式
-/cron 0 9 * * * <任务描述>        # 直接指定 cron 表达式
-/cron list                        # 查看列表
-/cron pause <id> / resume <id>    # 暂停 / 恢复
-/cron delete <id>                 # 删除
+/cron <自然语言>             # Claude 自动生成 cron 表达式
+/cron 0 9 * * * <描述>       # 直接指定 cron
+/cron list                   # 查看列表
+/cron pause <id> | resume <id>   # 暂停 / 恢复
+/cron delete <id>            # 删除
 ```
 
-### 文件操作
+#### 文件操作
 
 | 命令 | 说明 |
 |------|------|
-| `/pwd` | 显示工作目录绝对路径 |
 | `/ls [目录] [层数]` | 查看目录结构 |
-| `/mkdir <路径>` | 创建文件夹 |
-| `/touch <路径>` | 创建空文件 |
-| `/rm <路径>` | 删除文件或目录 |
+| `/bash <命令>` | 执行任意命令（覆盖 pwd/mkdir/touch/rm 等） |
 
-### 管理命令（仅 owner）
+#### 管理命令（仅 owner）
 
 | 命令 | 说明 |
 |------|------|
-| `/info [robot\|session\|task]` | 查看群配置、会话和任务信息 |
-| `/version` | 查看版本信息 |
-| `/open [shell]` | 在文件管理器或终端中打开工作目录 |
-| `/clean [all]` | 清除历史会话和缓存 |
+| `/info [robot\|session\|task]` | 查看配置/会话/任务信息 |
+| `/version` | 版本信息 |
+| `/open [shell]` | 打开工作目录 |
+| `/clean [all]` | 清除历史和缓存 |
 | `/reset-apikeycfg` | 重置 API Key 配置 |
-| `/cfg` | 注册当前群到配置 |
+| `/cfg` | 注册当前群到配置（支持 `--permissionMode` 设置权限模式） |
 | `/auth [add\|del <用户>]` | 管理群级白名单 |
 
-## 配置说明
-
-### 白名单
-
-- **全局白名单**：`config.json` 中的 `whiteUserList`
-- **群级白名单**：`conversations[].whiteUserList`（优先级高于全局）
-- 支持手机号和 userId 两种格式，手机号自动解析为 userId
-
-### API Key 池化
-
-配置 `apiKeyCfg` 后启用：
-
-- 429 错误自动切换到可用 Key
-- 连续 TPM 不稳定时自动换 Key
-- 每日 0 点自动重置 API Key 状态
-
-### 图片消息
-
-- 支持 `picture` 和 `richText`（含内嵌图片）消息类型
-- 图片自动下载到 `.images/` 目录
-- `useLocalOcr: true`（默认）使用本地 OCR 识别，同时传入原图路径供 Claude 自主查看
-- 设置 `useLocalOcr: false` 关闭 OCR（适用于支持图片识别的模型）
-
-### 关联群
+### 配置说明
 
-通过 `linkConversationId` 实现多个群共享同一个 Claude 会话上下文，消息自动路由到同一活跃会话。
-
-## 配置文件示例
+#### 配置文件示例
 
 ```json
 {
@@ -151,9 +130,8 @@ pm2 start --name "cc-ding-{clientId}" npx -- -p cc-ding cc-ding run -ci {clientI
       "whiteUserList": ["工号1", "工号2"],
       "agent": "指定agent（可选）",
       "useLocalOcr": true,
-      "taskCfg": {
-        "skill": "指定技能（可选）"
-      }
+      "permissionMode": "bypassPermissions",
+      "taskCfg": { "skill": "指定技能（可选）" }
     }
   ],
   "taskQueueSize": 50,
@@ -165,30 +143,216 @@ pm2 start --name "cc-ding-{clientId}" npx -- -p cc-ding cc-ding run -ci {clientI
 }
 ```
 
-## 数据存储
+#### 配置项速查
+
+| 配置 | 说明 |
+|------|------|
+| `whiteUserList` | 全局白名单（手机号或 userId） |
+| `conversations[].whiteUserList` | 群级白名单，优先级高于全局 |
+| `apiKeyCfg` | API Key 池化：429 自动切换、每日 0 点重置 |
+| `useLocalOcr` | 图片本地 OCR（默认 `true`），模型支持图片时可设 `false` |
+| `linkConversationId` | 关联群 ID，多群共享同一 Claude 会话上下文 |
+| `permissionMode` | Claude 进程权限模式（默认 `bypassPermissions`），可选: `default`、`acceptEdits`、`plan`、`auto`、`bypassPermissions`、`dontAsk` |
+| `preBash` | 全局 `/bash` 前置命令 |
+
+### 数据存储
 
 所有数据存储在 `~/.cc-ding/{clientId}/` 目录下：
 
 | 类型 | 路径 |
 |------|------|
-| 会话数据 | `{MD5}/.sessions/{claudeSessionId}/session.{json,log}` |
-| 任务数据 | `{MD5}/.tasks/{时间戳}/task.{json,log}` |
+| 会话 | `{MD5}/.sessions/{claudeSessionId}/session.{json,log}` |
+| 任务 | `{MD5}/.tasks/{时间戳}/task.{json,log}` |
 | 定时任务 | `cron.json` |
 | 图片缓存 | `{MD5}/.images/` |
 | 手机号映射 | `phone-map.json` |
 
-## 开发
+### 开发
+
+```bash
+pnpm install
+pnpm run lint
+pnpm run test
+pnpm run build
+```
+
+**系统要求：** Node.js >= 24
+
+---
+
+## English
+
+Connect Claude Code to DingTalk for bidirectional communication. Supports multi-turn conversations, task queues, scheduled jobs, and image recognition — helping teams build privately deployable AI assistants at minimal cost.
+
+### Table of Contents
+
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+- [Configuration](#configuration)
+- [Data Storage](#data-storage)
+- [Development](#development)
+
+### Quick Start
+
+#### Install
+
+```bash
+pnpm i cc-ding -g
+```
+
+#### Initialize
+
+```bash
+cc-ding init -ci {clientId} -cs {clientSecret} -m {phone_number}
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `-ci, --clientId` | DingTalk app ClientId |
+| `-cs, --clientSecret` | DingTalk Stream connection secret |
+| `-m, --mobile` | Admin phone number (auto-added to whitelist) |
+| `-cn, --clientName` | Bot name (optional, default "cc助手") |
+
+#### Edit Config
+
+Config file is at `~/.cc-ding/{clientId}/config.json`. See [config example](#configuration-example) below.
+
+#### Start
+
+```bash
+# Direct start
+cc-ding run -ci {clientId}
+
+# Recommended: PM2 daemon
+pm2 start --name "cc-ding-{clientId}" npx -- -p cc-ding cc-ding run -ci {clientId}
+```
+
+### Commands
+
+#### Session
+
+| Command | Description |
+|---------|-------------|
+| `/help` | View all commands |
+| `/log [lines]` | View session logs |
+| `/new [msg]` | Start a new conversation |
+| `/resume [ID]` | Resume a previous session (latest if omitted) |
+| `/end` | End the current session |
+
+> Sessions are auto-persisted to `active.json` and restored on restart. All whitelisted users in the group can participate.
+
+#### Task
+
+```
+/task <description>     # Submit task (auto-queued, sequential execution)
+/task cancel            # Cancel a task
+```
+
+#### Scheduled
+
+```
+/cron <natural language>        # Claude auto-generates cron expression
+/cron 0 9 * * * <description>   # Specify cron directly
+/cron list                      # View all
+/cron pause <id> | resume <id>  # Pause / resume
+/cron delete <id>               # Delete
+```
+
+#### File Operations
+
+| Command | Description |
+|---------|-------------|
+| `/ls [dir] [depth]` | View directory structure |
+| `/bash <cmd>` | Execute arbitrary commands (covers pwd/mkdir/touch/rm etc.) |
+
+#### Admin (owner only)
+
+| Command | Description |
+|---------|-------------|
+| `/info [robot\|session\|task]` | View config/session/task info |
+| `/version` | Version info |
+| `/open [shell]` | Open working directory |
+| `/clean [all]` | Clear history and cache |
+| `/reset-apikeycfg` | Reset API Key configuration |
+| `/cfg` | Register current group to config (supports `--permissionMode` to set permission mode) |
+| `/auth [add\|del <user>]` | Manage group whitelist |
+
+### Configuration
+
+#### Configuration Example
+
+```json
+{
+  "clientName": "cc助手",
+  "owner": "your_phone_number",
+  "whiteUserList": ["your_phone_number"],
+  "clientSecret": "dingtalk_stream_secret",
+  "defaultDingToken": "fallback_dingtalk_bot_token",
+  "conversations": [
+    {
+      "conversationId": "group_id",
+      "conversationTitle": "group_name",
+      "dingToken": "group_bot_token",
+      "whiteUserList": ["emp_id_1", "emp_id_2"],
+      "agent": "specified_agent (optional)",
+      "useLocalOcr": true,
+      "permissionMode": "bypassPermissions",
+      "taskCfg": { "skill": "specified_skill (optional)" }
+    }
+  ],
+  "taskQueueSize": 50,
+  "taskHandlerCount": 1,
+  "sessionMaxConcurrency": 20,
+  "includeThinking": false,
+  "resultOnly": true,
+  "debug": false
+}
+```
+
+#### Config Quick Reference
+
+| Config | Description |
+|--------|-------------|
+| `whiteUserList` | Global whitelist (phone or userId) |
+| `conversations[].whiteUserList` | Group-level whitelist, higher priority than global |
+| `apiKeyCfg` | API Key pooling: auto-switch on 429, daily reset at midnight |
+| `useLocalOcr` | Local image OCR (default `true`); set `false` if model supports images natively |
+| `linkConversationId` | Link groups to share one Claude session context |
+| `permissionMode` | Claude process permission mode (default `bypassPermissions`), options: `default`, `acceptEdits`, `plan`, `auto`, `bypassPermissions`, `dontAsk` |
+| `preBash` | Global pre-bash command for `/bash` |
+
+### Data Storage
+
+All data is stored under `~/.cc-ding/{clientId}/`:
+
+| Type | Path |
+|------|------|
+| Sessions | `{MD5}/.sessions/{claudeSessionId}/session.{json,log}` |
+| Tasks | `{MD5}/.tasks/{timestamp}/task.{json,log}` |
+| Cron jobs | `cron.json` |
+| Image cache | `{MD5}/.images/` |
+| Phone mapping | `phone-map.json` |
+
+### Development
 
 ```bash
 pnpm install
-pnpm run lint       # 代码检查
-pnpm run test       # 运行测试
-pnpm run build      # 构建
+pnpm run lint
+pnpm run test
+pnpm run build
 ```
 
-## 系统要求
+**Requirements:** Node.js >= 24
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=yihuineng/cc-ding&type=Date)](https://github.com/yihuineng/cc-ding/stargazers)
+
+## Contributors
 
-- Node.js >= 24
+[![Contributors](https://contrib.rocks/image?repo=yihuineng/cc-ding)](https://github.com/yihuineng/cc-ding/graphs/contributors)
 
 ## License