Skip to content

README.md

Latest commit

 

History

History
412 lines (300 loc) · 9.58 KB

README.md

File metadata and controls

412 lines (300 loc) · 9.58 KB
Raw

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 时的启动崩溃。

安装

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，再检查测试

Slash 命令

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

配置

配置优先级从低到高：

  1. 默认值
  2. ~/.my-agent/settings.json
  3. 当前项目 .my-agent/settings.json
  4. 环境变量

项目配置示例：

{
  "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：

{
  "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、单层嵌套对象等常见结构。

Hooks

可以在 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_EVENT
  • MY_AGENT_TOOL_NAME
  • MY_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 --help

目录结构

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：

pip install -e ".[dev]"

.venv/bin/my-agent 启动失败或加载旧源码

执行：

scripts/fix_pth.sh

然后再验证：

.venv/bin/my-agent --help
.venv/bin/python -m my_agent --help

退出时无法保存 session

会话默认保存到：

~/.my-agent/sessions/

如果当前运行环境没有权限写入该目录，myAgent 会打印 warning，但不会让 REPL 退出时报 traceback。

相关文档