内容
# PyClaudeCode
PyClaudeCode 是一个用 Python 实现的类 Claude Code 编程 Agent，支持多轮对话、工具调用、文件读写、命令执行、权限控制、会话恢复、上下文压缩、MCP 接入与 Claude Code 风格终端交互界面。
当前包名和 CLI 仍为 `my_agent` / `my-agent`。默认走 DeepSeek 的 Anthropic 兼容接口，也可以切换到 OpenAI 兼容接口。
## 功能概览
- Claude Code 风格 REPL：欢迎面板、上下文提示符、流式输出、工具调用状态、Slash 命令。
- 多轮工具循环：模型可以连续调用工具，直到得到最终回答。
- 内置工具：`read`、`write`、`edit`、`bash`、`glob`、`grep`、`task`。
- 权限模式：`read_only`、`ask`、`allow_all`、`danger`。
- 会话管理：自动保存、列出、删除、按 ID 或 `latest` 恢复。
- 配置系统：支持项目级 `.my-agent/settings.json`、用户级 `~/.my-agent/settings.json` 和环境变量覆盖。
- MCP 客户端：通过 stdio 接入外部 MCP server，并把 MCP tool 暴露给模型。
- Hooks 和插件：支持工具前后钩子，以及从 `~/.my-agent/plugins/` 自动发现自定义工具。
- 兼容性修复：处理 Python 3.14 venv `.pth` 问题，以及 SOCKS proxy 缺少 `socksio` 时的启动崩溃。
## 安装
```bash
cd /Users/myAgent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
```
编辑 `.env`，填入你的 DeepSeek key：
```bash
ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
ANTHROPIC_MODEL=deepseek-v4-pro[1m]
ANTHROPIC_EFFORT=off
```
如果在 Python 3.14 的 macOS venv 里遇到 `my-agent` 入口或 `python -m my_agent` 找不到源码，执行：
```bash
scripts/fix_pth.sh
```
这个脚本会 patch venv 入口，并在 `site-packages/my_agent` 里生成指向 `src/my_agent` 的 shim package。
## 启动
进入交互模式：
```bash
.venv/bin/my-agent
```
或者：
```bash
.venv/bin/python -m my_agent
```
单次提问：
```bash
.venv/bin/my-agent "用一句话介绍你自己"
```
管道输入：
```bash
echo "列出当前目录文件" | .venv/bin/my-agent
```
显式进入 REPL：
```bash
.venv/bin/my-agent --repl
```
恢复最近会话：
```bash
.venv/bin/my-agent --resume latest
```
恢复指定会话：
```bash
.venv/bin/my-agent --resume <session-id>
```
## 交互界面
启动后会看到类似：
```text
╭─ ✻ ─────────────────────────────────────────╮
│ Welcome to myAgent Code │
│ cwd: ~/Documents/BuildAgent/myAgent │
│ model: deepseek-v4-pro[1m] │
│ permission: ask session: def37a2a tools: 7│
│ /help for commands Ctrl+D to exit │
╰─────────────────────────────────────────────╯
╭─ ~/Documents/BuildAgent/myAgent (ask)
╰─>
```
提示符含义：
- 第一行显示当前目录和权限模式。
- 第二行 `╰─>` 是实际输入位置。
- 括号里的 `ask` 表示当前权限模式，不是唯一模式。
支持反斜杠续行：
```text
╰─> 请分析这个问题，并分步骤处理 \
... 先读 README，再检查测试
```
## Slash 命令
REPL 中输入 `/help` 可以查看命令列表。
| 命令 | 说明 |
|---|---|
| `/help` | 查看 Slash 命令 |
| `/clear` | 清空当前对话历史 |
| `/compact` | 手动压缩上下文 |
| `/permission` | 查看或切换权限模式 |
| `/history` | 查看消息数和估算 token |
| `/status` | 查看当前模型、工具、会话、权限等状态 |
| `/doctor` | 查看运行时健康摘要 |
| `/session` | 查看当前会话信息 |
| `/save` | 保存当前会话 |
| `/exit` / `/quit` | 退出 REPL |
切换权限模式示例：
```text
/permission read_only
/permission ask
/permission allow_all
/permission danger
```
## 权限模式
| 模式 | 行为 |
|---|---|
| `read_only` | 只允许读文件、搜索等低风险操作 |
| `ask` | 默认模式；写文件、执行命令等操作会询问确认 |
| `allow_all` | 大多数工具调用直接允许 |
| `danger` | 跳过权限检查，接近 Claude Code 的 dangerously-skip-permissions |
启动时指定：
```bash
.venv/bin/my-agent --permission-mode read_only
.venv/bin/my-agent --permission-mode ask
.venv/bin/my-agent --permission-mode allow_all
.venv/bin/my-agent --permission-mode danger
```
也可以用环境变量：
```bash
MY_AGENT_PERMISSION_MODE=allow_all .venv/bin/my-agent
```
## 常用命令
查看帮助：
```bash
.venv/bin/my-agent --help
```
查看健康状态：
```bash
.venv/bin/my-agent doctor
```
列出会话：
```bash
.venv/bin/my-agent sessions list
```
删除会话：
```bash
.venv/bin/my-agent sessions delete <session-id>
```
指定模型：
```bash
.venv/bin/my-agent --model "deepseek-v4-pro[1m]"
```
指定推理强度：
```bash
.venv/bin/my-agent --effort low
.venv/bin/my-agent --effort medium
.venv/bin/my-agent --effort high
.venv/bin/my-agent --effort max
.venv/bin/my-agent --effort off
```
切换到 OpenAI 兼容接口：
```bash
.venv/bin/my-agent \
--provider openai \
--base-url https://api.deepseek.com/v1 \
--model deepseek-chat
```
## 配置
配置优先级从低到高：
1. 默认值
2. `~/.my-agent/settings.json`
3. 当前项目 `.my-agent/settings.json`
4. 环境变量
项目配置示例：
```json
{
"permissionMode": "ask",
"model": "deepseek-v4-pro[1m]",
"baseUrl": "https://api.deepseek.com/anthropic",
"effort": "off",
"maxIterations": 20
}
```
支持的环境变量：
| 环境变量 | 对应配置 |
|---|---|
| `ANTHROPIC_AUTH_TOKEN` | API key |
| `ANTHROPIC_MODEL` | `model` |
| `ANTHROPIC_BASE_URL` | `baseUrl` |
| `ANTHROPIC_EFFORT` | `effort` |
| `MY_AGENT_PERMISSION_MODE` | `permissionMode` |
## MCP 配置
在 `.my-agent/settings.json` 或 `~/.my-agent/settings.json` 中配置 MCP server：
```json
{
"mcpServers": {
"filesystem": {
"command": "node",
"args": ["path/to/server.js"]
}
}
}
```
启动时，myAgent 会通过 stdio 初始化 MCP server，读取 `tools/list`，并把远端工具注册为：
```text
mcp__<server_name>__<tool_name>
```
MCP 参数 schema 会转换成 Pydantic 输入模型，当前已覆盖 required、enum、数值边界、字符串长度、pattern、数组 item、nullable、`anyOf` / `oneOf`、`const`、单层嵌套对象等常见结构。
## Hooks
可以在 settings 中配置工具调用前后钩子：
```json
{
"hooks": {
"pre_tool_use": ["echo about to run $MY_AGENT_TOOL_NAME"],
"post_tool_use": ["echo completed $MY_AGENT_TOOL_NAME"],
"stop": ["echo done"]
}
}
```
钩子执行时会注入：
- `MY_AGENT_EVENT`
- `MY_AGENT_TOOL_NAME`
- `MY_AGENT_TOOL_INPUT`
## 插件
插件目录：
```text
~/.my-agent/plugins/
```
在该目录放置 Python 文件，并导出符合 `Tool` 接口的类，启动时会自动发现并注册。插件注册失败会被跳过，不影响主程序启动。
## 测试
全量测试不需要真实 API key，使用 mock client 和本地 stub：
```bash
.venv/bin/pytest -q
```
当前基线：
```text
156 passed
```
代码检查：
```bash
.venv/bin/ruff check .
```
入口检查：
```bash
.venv/bin/my-agent --help
.venv/bin/python -m my_agent --help
```
## 目录结构
```text
src/my_agent/
cli.py Typer CLI 入口、REPL、Slash 命令
agent.py 多轮 Agent tool loop
prompt.py system prompt 组装
config.py settings.json / env 配置加载
permission.py 权限策略与 bash 风险检测
session.py 会话保存、恢复、列表、删除
compact.py 上下文压缩
hooks.py pre/post/stop hooks
mcp.py MCP stdio client 与 MCP tool wrapper
plugins.py 用户插件发现
types.py Anthropic-style 内部消息协议
ui/
claude.py Claude Code 风格终端 UI
render.py 流式输出和工具状态渲染
llm/
anthropic_style.py Anthropic Messages API 兼容客户端
openai_style.py OpenAI-compatible 客户端
proxy.py SOCKS proxy / httpx client 防护
tools/
read.py 读取文件
write.py 写文件
edit.py 替换编辑
bash.py 执行 shell 命令
glob.py 文件匹配
grep.py 文本搜索
task.py 子 Agent 工具
tests/
test_*.py 单元测试和回归测试
scripts/
fix_pth.sh 修复 Python 3.14 venv 入口和源码加载
```
## 常见问题
### `Using SOCKS proxy, but the 'socksio' package is not installed`
已在代码中做运行时防护：当检测到 SOCKS proxy 但缺少 `socksio` 时，会自动绕过环境代理，避免启动崩溃。
同时 `pyproject.toml` 已包含 `socksio>=1.0`，重新安装依赖后可原生支持 SOCKS：
```bash
pip install -e ".[dev]"
```
### `.venv/bin/my-agent` 启动失败或加载旧源码
执行：
```bash
scripts/fix_pth.sh
```
然后再验证：
```bash
.venv/bin/my-agent --help
.venv/bin/python -m my_agent --help
```
### 退出时无法保存 session
会话默认保存到：
```text
~/.my-agent/sessions/
```
如果当前运行环境没有权限写入该目录，myAgent 会打印 warning，但不会让 REPL 退出时报 traceback。
## 相关文档
- [Plan.md](Plan.md)：阶段计划和路线图
- [taskFinished.md](taskFinished.md)：已完成任务记录
- [ToDo.md](ToDo.md)：复测发现、技术债和后续事项
连接信息
猜你喜欢
暂无推荐服务器