npm package: @mk-co/charitydoing-cli
Description: Professional AI code assistant CLI powered by Node.js
Author: Your Name
Latest version: 2.0.6

# CharityDoing · Agent Workbench (CLI & UI)

<div align="center">

**专业 AI 代理工作台 · 双形态：CLI + 桌面 UI**

[![npm version](https://img.shields.io/npm/v/@mk-co/charitydoing-cli.svg)](https://www.npmjs.com/package/@mk-co/charitydoing-cli)
[![Node.js](https://img.shields.io/badge/Node.js-20.0+-green.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)

支持多模型（Claude / GPT / 兼容 API）、多中转站、自动快照回滚、上下文与 Prompt 缓存，面向「长时任务」与「多 Agent 协作」的下一代 AI 工具链。

</div>

---

## ✨ 特性总览

- **双形态体验**
  - `CLI 模式`：在终端内完成代码编写、文件操作、脚本执行等复杂任务
  - `桌面 UI 模式`：Electron + React，可视化管理会话、任务和多模型
- **多模型 / 多中转站**
  - 支持 OpenAI / GPT 系列
  - 支持 Anthropic Claude 系列
  - 支持任意 OpenAI 兼容中转站（如自建 One-API、New-API 等）
  - 一次配置，多模型随时切换
- **Shadow Git 智能回滚**
  - 消息级自动快照，精确追踪每轮对话的文件变更
  - 支持整体回滚、单文件回滚、单次编辑行级回滚
  - 已回滚的变更可随时重新应用
  - 文件系统和会话状态完全同步，避免状态不一致
- **上下文与 Prompt 缓存**
  - 会话级上下文记忆，支持长对话协作
  - Prompt 模板与缓存机制，减少重复抄写和上下文丢失
  - 针对常用工作流（重构、Review、生成单测等）可固化为「工作流 Prompt」
- **丰富内置 Tools**
  - 文件系统操作（读/写/搜索/结构分析）
  - 代码执行（Python / JS / TS / Bash）
  - Git 集成、依赖分析、数据处理等
  - **Java Debug Tools** (可选)：让 AI 自动调试 Java 应用（基于 DAP 协议）
- **长任务 & 计划模式（规划中）**
  - 支持定义多步骤 Plan
  - 任务状态跟踪（进行中 / 已完成 / 待办）
  - 目标：支持跨小时甚至跨天的「持续任务」

---

## 🚀 快速开始

### 1. CLI 模式

适合高频开发、自动化脚本、在终端中深度协作。

```bash
# 全局安装
npm install -g @mk-co/charitydoing-cli

# 启动
charitydoing
# 或使用短命令
mkcd
```

首次启动会有交互式向导，帮助你配置模型与中转站：

```text
? How would you like to configure?
❯ ⚡ Interactive setup (recommended)
  📝 Edit config file manually
```

**支持的模型 / 提供商示例：**
- OpenAI：`gpt-4.1` / `gpt-4o` / `o3-mini` 等
- Anthropic：`claude-3.5-sonnet` / `claude-3-opus` 等
- 自建或第三方中转：One-API、New-API，以及任何 OpenAI 兼容网关

**配置文件默认位置：**
- macOS: `~/Library/Application Support/CharityDoing/config.json`
- Linux: `~/.config/charitydoing/config.json`
- Windows: `%APPDATA%\CharityDoing\config.json`

### 2. 桌面 UI 模式（实验性）

适合更复杂的「任务看板」和多会话并行工作。

```bash
# 安装依赖（需要 Node.js 20+）
npm install

# 启动 UI 开发模式（Vite + Electron）
npm run ui:dev

# 构建 UI
npm run ui:build

# 仅做 UI 类型检查
npm run ui:type-check
```

UI 已与 CLI 核心 Runner 完全打通，实现真正的统一工作台体验。

---

## 🧠 多模型 & 多中转站

- 可以在配置中添加多个 Provider：
  - 不同云厂商（OpenAI / Anthropic / 其他）
  - 不同中转站（例如多个 One-API 节点分流）
- 在会话内快速切换模型：
  - 针对「代码生成」用一个模型
  - 针对「长文分析」用另一个模型
- 未来计划支持：
  - 不同模型绑定不同「角色」或「领域」
  - 自动将子任务分配给最合适的模型

示例（CLI 内命令）：

```bash
/provider list      # 查看已配置的模型提供商
/provider add       # 添加新的中转站 / Provider
/model              # 在当前会话切换模型
```

---

## ⏮ 回滚、上下文 & Prompt 缓存

### Shadow Git 智能快照系统

CharityDoing 采用创新的 **Shadow Git** 快照机制，在工作区外创建隐藏的 Git 仓库来追踪文件变更，实现精细化的版本控制：

- **消息级快照**：每次 AI 回复前后自动创建检查点，精确追踪每轮对话的文件变更
- **行级 Diff 回滚**：支持单个编辑的精确回退，只撤销特定修改而不影响其他变更
- **智能状态同步**：文件系统变更与会话状态完全同步，避免「对话回滚了但代码乱了」的问题

### 灵活的回滚策略

| 回滚方式 | 说明 | 适用场景 |
|---------|------|---------|
| **整体回滚** | 回滚整个消息的所有文件变更 | AI 生成的代码整体不满意 |
| **单文件回滚** | 只回滚某个文件的变更 | 部分文件修改正确，部分需要撤销 |
| **单次编辑回滚** | 精确回滚某一次 edit 操作 | 某个具体修改有问题，其他保留 |
| **重新应用** | 将已回滚的变更重新应用 | 回滚后发现原来是对的 |

### UI 可视化操作

在桌面 UI 模式下，每个编辑卡片都提供直观的操作按钮：

- 📝 **Diff 视图**：左右对照显示修改前后的代码，支持同步滚动
- ↩️ **回退按钮**：一键回退单次编辑或整个消息
- ↪️ **重新应用**：将已回退的修改重新应用到文件
- 📊 **状态指示**：清晰显示每个编辑的当前状态（已应用/已回退）

```bash
# CLI 命令
/checkpoint [name]  # 创建手动检查点
/rollback           # 选择一个快照回滚
/rollback <id>      # 回滚到指定快照
/undo               # 快速撤销上一步（整体回滚最后一条消息）
```

### 上下文管理 & Prompt 缓存

- 长对话中自动维护上下文，按需裁剪，避免超 Token
- 支持把常用指令存成「模板 Prompt」
- 后续计划引入：
  - Prompt 片段复用库
  - 自动拼装多段 Prompt 的「工作流」

---

## ⌨️ CLI 使用速览

### 基础对话

```text
You: 帮我创建一个 React 登录页面，包含表单验证

AI: 我来帮你创建一个带验证的 React 登录页面...
[自动创建 LoginPage.tsx]

You: 再加上密码强度检查和错误提示

AI: 已添加密码强度检查和错误提示...
[更新文件并显示变更 diff]
```

### 典型命令

```bash
# 会话管理
/sessions           # 列出所有会话
/session new        # 创建新会话
/session resume     # 恢复会话
/clear              # 清空当前会话

# 快照 / 回滚
/checkpoint [name]  # 创建检查点
/rollback           # 打开快照选择器
/rollback <id>      # 回滚到指定快照
/undo               # 撤销一步

# 模型与追踪
/provider list      # 查看模型提供商
/model              # 切换当前模型
/tracing on|off     # 开关执行追踪
/stats              # 查看使用统计
```

---

## 🧰 内置 Tools 一览（节选）

- 文件 / 项目
  - 读取 / 写入 / 搜索文件
  - 扫描项目结构、统计文件类型
  - 生成/更新文档和说明
- 代码执行
  - Python / Node.js / TypeScript / Bash 沙箱执行
  - 超时保护、日志捕获
- Git / 协作
  - 查看 Git 状态 / 提交历史
  - 辅助生成 Commit Message、变更说明
- 数据 / 分析
  - CSV / JSON 等数据格式处理
  - 统计分析、图表辅助生成

---

## 🧭 未来规划 · Roadmap

- **多模型协同工作**
  - 不同模型负责不同领域（如代码、写作、数据分析）
  - 同一任务下的分工与结果合并
- **更强大的内置 Tools**
  - 深度项目重构工具链
  - 性能分析 / 安全扫描辅助工具
  - 针对特定栈（前端 / 后端 / 数据）的专用工具集
- **长时间任务 & Plan 模式**
  - 支持设置「多小时 / 多天」级别的任务
  - Plan 模式下由 Agent 自动按步骤推进
  - 任务状态可视化（待办 / 进行中 / 已完成）
- **更完善的桌面工作台**
  - 多会话看板
  - 长任务时间线视图
  - 多 Agent / 多模型协作的拓扑视图

---

## 🛠️ 开发者指南

从源码运行 CLI / UI：

```bash
git clone https://github.com/your-org/CharityDoing.git
cd CharityDoing

npm install
npm run build        # 构建 CLI
npm link             # 本地全局链接 CLI

npm run ui:dev       # 启动桌面 UI 开发模式
```

常用环境变量：

```bash
export CLI_DEBUG=1       # 打印调试日志
export MARKOR_TRACING=1  # 开启执行追踪
```

---

## 📄 许可协议

本项目采用 **GNU Affero General Public License v3.0 (AGPL-3.0)** 许可协议，详情见 `LICENSE`。  
在基于本项目进行二次开发、提供在线服务或分发时，请务必阅读并遵守 AGPL-3.0 的条款。

或者修改 npm 全局目录：

```bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

---

## 📝 许可证

MIT License - 详见 [LICENSE](LICENSE)

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

## 📧 联系方式

- NPM: [@mk-co/charitydoing-cli](https://www.npmjs.com/package/@mk-co/charitydoing-cli)
- Issues: [GitHub Issues](https://github.com/your-org/CharityDoing/issues)

---

<div align="center">

**Built with ❤️ by MK-CO**

</div>