轻量级 AI 编码助手 - 全 Python 实现，易于定制和扩展
致敬 Claude Code 的学习项目 - 全 Python 实现，帮助初学者理解 AI Agent 架构
English | 中文文档
jojo-Code 是一个致敬 Claude Code 的开源学习项目。它的设计灵感来源于 Claude Code 的终端交互体验，用纯 Python 实现了一个简化版的 AI 编码助手。
这个项目的目标不是替代或对标 Claude Code 等商业产品，而是提供一个清晰、可读的代码库，帮助初学者理解：
- AI Agent 是如何工作的（LangGraph 状态机）
- Tool Calling 是如何实现的（40+ 工具注册与执行）
- TUI 界面是如何构建的（Textual 框架）
- WebSocket 实时通信是如何设计的
如果你对 AI Agent 开发感兴趣，jojo-Code 是一个不错的起点。
这个项目涵盖了 AI Agent 开发的完整链路：
| 模块 | 说明 | 你能学到什么 |
|---|---|---|
agent/ |
LangGraph 状态机 | Agent 的 Thinking-Action-Loop 循环 |
tools/ |
40+ 工具实现 | Tool Calling 的注册、调用、结果处理 |
cli/widgets/ |
Textual TUI 组件 | 终端界面的消息渲染和交互 |
server/ |
WebSocket + SSE 服务 | 实时通信和流式输出 |
plugin/ |
插件系统 | 如何设计可扩展的插件架构 |
security/ |
权限与审计 | Agent 安全控制的设计模式 |
memory/ |
对话记忆管理 | 上下文压缩和记忆分层 |
# 从源码安装
git clone https://github.com/afine907/jojo-code.git
cd jojo-code
uv sync# 交互式配置向导
jojo-code setup
# 或手动设置环境变量
export OPENAI_API_KEY=your-api-key
# 可选：使用其他 API
export OPENAI_BASE_URL=https://api.longcat.chat/openai/v1# 启动 TUI（自动启动后台服务）
jojo-code
# 或分别启动
jojo-code server start -d # 后台启动服务
jojo-code # 连接服务# TUI
jojo-code # 启动终端界面
jojo-code --no-server # 启动 TUI 但不自动启动服务
jojo-code --server ws://host:8080 # 连接远程服务
# 服务管理
jojo-code server start # 前台启动服务
jojo-code server start -d # 后台守护模式
jojo-code server status # 查看服务状态
jojo-code server stop # 停止服务
# 配置
jojo-code config set <key> <value> # 设置配置
jojo-code config show # 查看所有配置
jojo-code config get <key> # 获取单个配置
# 插件
jojo-code plugin list # 列出所有插件
jojo-code plugin enable <name> # 启用插件
jojo-code plugin disable <name> # 禁用插件
jojo-code plugin info <name> # 查看插件详情CLI Layer (cli/) -> Server (server/) -> Agent Loop (agent/) -> Tool Layer (tools/)
WebSocket/SSE LangGraph StateGraph 40+ tools
src/jojo_code/
├── cli/ # Textual TUI
│ ├── app.py # 主应用
│ ├── main.py # CLI 入口（argparse）
│ ├── ws_client.py # WebSocket 客户端
│ └── widgets/ # UI 组件
│ ├── chat.py # 消息列表（User/Assistant/System）
│ ├── header.py # 顶部栏（品牌/模式/模型）
│ ├── input_area.py # 输入框
│ ├── footer.py # 底部提示栏
│ └── messages.py # 消息事件类型
│
├── server/ # WebSocket/SSE Server
│ ├── ws_server.py # FastAPI 主服务
│ ├── handlers.py # JSON-RPC 方法处理
│ ├── jsonrpc.py # JSON-RPC stdio 服务
│ └── main.py # stdio 服务入口
│
├── agent/ # LangGraph Agent
│ ├── graph.py # 状态图定义
│ ├── nodes.py # thinking/execute 节点
│ ├── state.py # 状态结构
│ ├── modes.py # Plan/Build 模式
│ ├── sub.py # 子代理系统
│ └── tool.py # Agent-as-Tool
│
├── tools/ # 40+ 工具
│ ├── file_tools.py # 文件读写
│ ├── shell_tools.py # Shell 执行
│ ├── git_tools.py # Git 操作
│ ├── search_tools.py # 代码搜索
│ ├── web_tools.py # Web 搜索
│ ├── web_fetch_tools.py # Web 抓取
│ ├── http_tools.py # HTTP 请求
│ ├── code_analysis_tools.py # 代码分析
│ ├── performance_tools.py # 性能分析
│ ├── data_tools.py # 数据转换
│ ├── doc_tools.py # 文档处理
│ └── system_tools.py # 系统监控
│
├── plugin/ # 插件系统
│ ├── base.py # 插件基类
│ ├── hooks.py # 生命周期钩子
│ ├── discovery.py # 插件发现
│ └── registry.py # 插件注册
│
├── security/ # 安全系统（权限/审计/SSRF防护）
├── memory/ # 对话记忆（短期/长期/检索）
├── ops/ # AgentOps（指标/评估/仪表盘）
├── models/ # 模型提供商抽象
├── session/ # 会话持久化
├── skills/ # 技能系统
├── task/ # 任务执行框架
├── context/ # 项目上下文管理
├── mcp/ # MCP 客户端
└── core/ # 核心基础设施（配置/缓存/重试/日志）
- AI Agent 初学者 - 想理解 Agent 是如何工作的，但被复杂的框架文档劝退
- Python 开发者 - 想从零构建自己的 AI 工具，需要一个可运行的参考实现
- 架构学习者 - 对 Tool Calling、状态机、插件系统等设计模式感兴趣
# 启动 TUI
jojo-code
# 试试这些命令
/help # 查看可用命令
/status # 查看连接状态
/mode plan # 切换到规划模式jojo-Code 的清晰架构适合学习 Agent 开发：
# src/jojo_code/agent/graph.py
from langgraph.graph import StateGraph
# 定义状态
class AgentState(TypedDict):
messages: list[BaseMessage]
tool_calls: list[ToolCall]
tool_results: list[ToolResult]
mode: str # "plan" or "build"
# 定义节点
def thinking(state: AgentState) -> AgentState:
"""LLM 思考，决定是否调用工具"""
...
def execute(state: AgentState) -> AgentState:
"""执行工具调用"""
...
# 构建图
graph = StateGraph(AgentState)
graph.add_node("thinking", thinking)
graph.add_node("execute", execute)
graph.add_edge("thinking", "execute")注意：Docker 部署功能尚在完善中，建议优先使用本地安装方式。
# 启动
docker compose up -d
# 验证
curl http://localhost:8080/health
# 远程连接
jojo-code --server ws://your-server:8080/ws| 类别 | 技术 |
|---|---|
| Agent 框架 | LangGraph |
| 工具定义 | LangChain Tools |
| LLM 客户端 | langchain-openai / langchain-anthropic |
| CLI 框架 | Textual |
| Server | FastAPI + WebSocket + SSE |
| 测试 | pytest + pytest-asyncio |
| 包管理 | uv |
# 安装依赖
uv sync
# 运行测试
uv run pytest tests/ -v
# 运行特定测试
uv run pytest tests/test_tui/ -v
uv run pytest tests/test_tools/ -v
# 代码检查
uv run ruff check src/ tests/
uv run ruff format src/ tests/
# 类型检查
uv run mypy src/欢迎贡献！这个项目还很年轻，有很多可以改进的地方。
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'feat: add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
- Claude Code - 设计灵感来源
- LangGraph - Agent 框架
- Textual - TUI 框架
Inspired by Claude Code. Built for learning.