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时的启动崩溃。
cd /Users/myAgent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env编辑 .env，填入你的 DeepSeek key：
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 找不到源码，执行：
scripts/fix_pth.sh这个脚本会 patch venv 入口，并在 site-packages/my_agent 里生成指向 src/my_agent 的 shim package。
进入交互模式：
.venv/bin/my-agent或者：
.venv/bin/python -m my_agent单次提问：
.venv/bin/my-agent "用一句话介绍你自己"管道输入：
echo "列出当前目录文件" | .venv/bin/my-agent显式进入 REPL：
.venv/bin/my-agent --repl恢复最近会话：
.venv/bin/my-agent --resume latest恢复指定会话：
.venv/bin/my-agent --resume <session-id>启动后会看到类似：
╭─ ✻ ─────────────────────────────────────────╮
│ 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表示当前权限模式，不是唯一模式。
支持反斜杠续行：
╰─> 请分析这个问题，并分步骤处理 \
... 先读 README，再检查测试
REPL 中输入 /help 可以查看命令列表。
| 命令 | 说明 |
|---|---|
/help |
查看 Slash 命令 |
/clear |
清空当前对话历史 |
/compact |
手动压缩上下文 |
/permission |
查看或切换权限模式 |
/history |
查看消息数和估算 token |
/status |
查看当前模型、工具、会话、权限等状态 |
/doctor |
查看运行时健康摘要 |
/session |
查看当前会话信息 |
/save |
保存当前会话 |
/exit / /quit |
退出 REPL |
切换权限模式示例：
/permission read_only
/permission ask
/permission allow_all
/permission danger
| 模式 | 行为 |
|---|---|
read_only |
只允许读文件、搜索等低风险操作 |
ask |
默认模式；写文件、执行命令等操作会询问确认 |
allow_all |
大多数工具调用直接允许 |
danger |
跳过权限检查，接近 Claude Code 的 dangerously-skip-permissions |
启动时指定：
.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也可以用环境变量：
MY_AGENT_PERMISSION_MODE=allow_all .venv/bin/my-agent查看帮助：
.venv/bin/my-agent --help查看健康状态：
.venv/bin/my-agent doctor列出会话：
.venv/bin/my-agent sessions list删除会话：
.venv/bin/my-agent sessions delete <session-id>指定模型：
.venv/bin/my-agent --model "deepseek-v4-pro[1m]"指定推理强度：
.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 兼容接口：
.venv/bin/my-agent \
--provider openai \
--base-url https://api.deepseek.com/v1 \
--model deepseek-chat配置优先级从低到高：
- 默认值
~/.my-agent/settings.json- 当前项目
.my-agent/settings.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 |
在 .my-agent/settings.json 或 ~/.my-agent/settings.json 中配置 MCP server：
{
"mcpServers": {
"filesystem": {
"command": "node",
"args": ["path/to/server.js"]
}
}
}启动时，myAgent 会通过 stdio 初始化 MCP server，读取 tools/list，并把远端工具注册为：
mcp__<server_name>__<tool_name>
MCP 参数 schema 会转换成 Pydantic 输入模型，当前已覆盖 required、enum、数值边界、字符串长度、pattern、数组 item、nullable、anyOf / oneOf、const、单层嵌套对象等常见结构。
可以在 settings 中配置工具调用前后钩子：
{
"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_EVENTMY_AGENT_TOOL_NAMEMY_AGENT_TOOL_INPUT
插件目录：
~/.my-agent/plugins/
在该目录放置 Python 文件，并导出符合 Tool 接口的类，启动时会自动发现并注册。插件注册失败会被跳过，不影响主程序启动。
全量测试不需要真实 API key，使用 mock client 和本地 stub：
.venv/bin/pytest -q当前基线：
156 passed
代码检查：
.venv/bin/ruff check .入口检查：
.venv/bin/my-agent --help
.venv/bin/python -m my_agent --helpsrc/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 入口和源码加载
已在代码中做运行时防护：当检测到 SOCKS proxy 但缺少 socksio 时，会自动绕过环境代理，避免启动崩溃。
同时 pyproject.toml 已包含 socksio>=1.0，重新安装依赖后可原生支持 SOCKS：
pip install -e ".[dev]"执行：
scripts/fix_pth.sh然后再验证：
.venv/bin/my-agent --help
.venv/bin/python -m my_agent --help会话默认保存到：
~/.my-agent/sessions/
如果当前运行环境没有权限写入该目录，myAgent 会打印 warning，但不会让 REPL 退出时报 traceback。
- Plan.md：阶段计划和路线图
- taskFinished.md：已完成任务记录
- ToDo.md：复测发现、技术债和后续事项