# ClaudePotter

**Repository Path**: timwenx/claude-potter

## Basic Information

- **Project Name**: ClaudePotter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ClaudePotter

> 基于 Rust 构建的 Claude Code CLI 工作流编排引擎，提供计划生成、逐步执行和自动审查的完整闭环。

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

[English](README.md) | **中文**

---

## 项目简介

ClaudePotter 解决的核心问题是：**将大模型从「单次对话工具」升级为「可编排、可追踪、可恢复」的工程化执行系统。**

在日常开发中，直接用 Claude Code CLI 处理复杂任务时，常常遇到：
- 任务拆解不稳定，一次性生成容易跑偏
- 执行过程不可追踪，无法知道当前进展
- 多轮修改丢失上下文，反复沟通成本高
- 远程协作不方便，非技术人员无法参与

ClaudePotter 通过 **Plan → Exec → Review** 的多阶段工作流，配合飞书集成和知识库系统，让 AI 驱动的开发变得可控、可观测、可持续。

---

## 核心特性

### 🔄 四种工作流模式

| 模式 | 说明 |
|------|------|
| `plan` | 根据自然语言描述生成结构化实施计划 |
| `exec` | 按轮次逐步执行已有计划，每轮记录进度 |
| `full` | 完整流程：计划 → 执行 → 审查，一键到底 |
| `resume` | 恢复中断的项目，基于已有上下文继续执行 |

### 🤖 多 Agent 协作

系统内置三类角色，职责边界清晰：

| 角色 | 职责 |
|------|------|
| **Planner** | 分析需求，生成分轮次的实施计划 |
| **Executor** | 逐轮执行计划，调用 Claude CLI 修改代码 |
| **Reviewer** | 审查执行结果，检查代码质量和一致性 |

### 📱 飞书集成

三种远程接入模式，让团队协作突破终端限制：

| 模式 | 特点 | 要求 |
|------|------|------|
| Webhook | 单向通知，最简配置 | 仅需 Webhook URL |
| App (HTTP) | 双向交互，支持卡片操作 | 需要公网 IP/域名 |
| WebSocket | 双向交互，无需公网 | 仅需 App ID/Secret |

飞书中可直接发送 `/plan`、`/exec`、`/full` 等命令，通过交互式卡片审批、反馈、查看进度。

### 🧠 知识库系统

项目级 Knowledge Base（`.claudepotter/kb/`）自动注入上下文，帮助 Claude 理解项目全局：

```
.claudepotter/kb/
├── README.md        # 知识库索引
├── architecture.md  # 项目架构概述
├── modules.md       # 模块职责说明
├── conventions.md   # 编码规范和约定
└── workflow.md      # 工作流执行模式
```

### 📋 其他能力

- **MAIN.md 追踪**：自动维护任务状态（待办 / 进行中 / 已完成）
- **自动提交**：每轮执行成功后自动 Git commit
- **失败重试**：执行失败时自动换策略重试
- **国际化**：中英文双语界面支持
- **守护进程**：后台运行 + IPC 控制
- **模型调度**：支持为不同阶段配置不同模型（如计划用 Opus，执行用 Sonnet）

---

## 安装

### 前置条件

- Rust 1.70+（edition 2021）
- Claude Code CLI 已安装并配置
- Git（用于自动提交功能）

### 从源码构建

```bash
# 克隆仓库
git clone https://gitee.com/timwenx/claude-potter.git
cd claudepotter-source

# 构建
cargo build --release

# 二进制文件位于 target/release/claude-p
```

---

## 快速开始

### 基本用法

```bash
# 生成计划
claude-p plan "为用户模块添加 JWT 认证"

# 执行计划
claude-p exec plan.md

# 完整流程（计划 + 执行 + 审查）
claude-p full "实现用户管理的 REST API"

# 恢复中断的项目
claude-p resume /path/to/project
```

### 飞书集成模式

```bash
# 启动 WebSocket 模式（推荐，无需公网 IP）
claude-p serve --mode ws

# HTTP 回调模式（需要公网 IP）
claude-p serve --mode app --port 3100

# 连接到运行中的守护进程
claude-p attach
```

### 守护进程模式

```bash
# 启动守护进程
claude-p daemon

# 查看状态
claude-p status

# 停止守护进程
claude-p stop
```

---

## 配置

ClaudePotter 的配置文件存放在 `~/.claudepotter/` 目录：

```
~/.claudepotter/
├── config.toml      # 用户偏好（语言、模型、轮次等）
└── settings.json    # 飞书集成凭证
```

### config.toml

```toml
language = "zh"                     # 界面语言："zh" 或 "en"
default_model = "claude-sonnet-4"   # 默认模型
default_rounds = 6                  # 默认执行轮次
streaming = true                    # 流式输出
retries = 3                         # 失败重试次数

[tui]
theme = "dark"                      # TUI 主题
verbosity = "minimal"               # 输出详细程度

[plan]
auto_generate = true                # 自动生成计划

[features]
auto_review = true                  # 执行后自动审查
auto_commit = true                  # 每轮成功后自动提交
kb_sync = true                      # 启用知识库同步
```

### settings.json（飞书配置）

```json
{
  "feishu": {
    "enabled": true,
    "mode": "ws",
    "app_id": "cli_xxxxxxxx",
    "app_secret": "xxxxxxxx",
    "default_chat_id": "oc_xxxxxxxx",
    "notify_on": ["project_start", "project_complete", "project_failed"]
  }
}
```

---

## 飞书集成快速配置

### WebSocket 模式（推荐）

1. 在[飞书开放平台](https://open.feishu.cn/)创建自建应用
2. 开启事件订阅，选择「使用 WebSocket 接收事件」
3. 订阅事件：`im.message.receive_v1`、`card.action.trigger`
4. 添加权限：`im:message`、`im:message:send_as_bot`
5. 在 `settings.json` 中填入 App ID 和 App Secret
6. 运行 `claude-p serve --mode ws`

### 飞书命令

| 命令 | 说明 |
|------|------|
| `/plan <描述>` | 生成实施计划 |
| `/exec <文件>` | 执行计划文件 |
| `/full <描述>` | 完整工作流 |
| `/approve [轮次]` | 审批计划 |
| `/reject` | 驳回计划 |
| `/feedback <消息>` | 发送反馈 |
| `/cancel` | 取消任务 |
| `/status` | 查看状态 |
| `/list` | 查看活跃任务 |

详细飞书集成文档请参考 [docs/feishu-integration.md](docs/feishu-integration.md)。

---

## 项目结构

```
claudepotter-source/
├── cli/                 # 主 CLI 应用
│   ├── src/
│   │   ├── main.rs      # 入口
│   │   ├── cli_driver.rs # CLI 参数定义
│   │   ├── config.rs    # 用户配置
│   │   ├── settings.rs  # 集成配置
│   │   ├── workflow/    # 执行工作流（Planner、Executor、Reviewer）
│   │   ├── feishu/      # 飞书集成（WebSocket、HTTP、Webhook）
│   │   ├── serve/       # 服务模式
│   │   ├── claude/      # Claude CLI 驱动层
│   │   ├── common/      # 公共工具（无外部依赖）
│   │   └── i18n/        # 国际化
│   └── prompts/         # 系统提示词
├── protocol/            # 数据结构（Plan、Progress、Task）
├── tui/                 # 终端 UI 组件
├── hooks/               # 生命周期钩子系统
├── docs/                # 文档
└── .claudepotter/       # 项目知识库
```

---

## 架构设计

项目采用模块化架构，层次清晰：

- **CLI 层**：参数解析和命令路由
- **工作流层**：Plan / Exec / Review 编排，包含长链路推理和多阶段协作
- **集成层**：飞书 WebSocket / HTTP / Webhook 三种接入模式
- **公共层**：共享工具（不依赖外部 crate）

### 关键设计决策

1. **配置分离**：TOML 存用户偏好，JSON 存凭证密钥
2. **WebSocket 优先**：飞书集成无需公网 IP，降低部署门槛
3. **知识库半自动**：提供模板和初始化机制，用户可自定义维护

---

## 许可证

Apache License 2.0

## 贡献

欢迎贡献！请在修改前阅读 `.claudepotter/kb/architecture.md` 中的架构文档。

## 参考资源

- [飞书开放平台文档](https://open.feishu.cn/document/)
- [Claude Code CLI 文档](https://docs.anthropic.com/claude-code)
- [Rust Edition 指南](https://doc.rust-lang.org/edition-guide/)