CharityDoing · Agent Workbench (CLI & UI)

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

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

✨ 特性总览

• 双形态体验
  • 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 模式

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

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

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

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

? 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 模式（实验性）

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

# 安装依赖（需要 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 内命令）：

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

⏮ 回滚、上下文 & Prompt 缓存

Shadow Git 智能快照系统

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

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

灵活的回滚策略

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

UI 可视化操作

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

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

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

上下文管理 & Prompt 缓存

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

⌨️ CLI 使用速览

基础对话

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

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

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

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

典型命令

# 会话管理
/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：

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 开发模式

常用环境变量：

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

📄 许可协议

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

或者修改 npm 全局目录：

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

📝 许可证

MIT License - 详见 LICENSE

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📧 联系方式

• NPM: @mk-co/charitydoing-cli
• Issues: GitHub Issues

Built with ❤️ by MK-CO