# Python 编程助手 CLI

`CLI工具` `编程助手` `AI代理` `MCP服务器` `Python`

# 编程助手

编程助手是一个基于 Python 的命令行工具，专为编程工作流设计。它集成了基于边界的智能代理循环、内置本地工具，以及可选的外部 MCP 服务器支持。

## 核心特性

- 内置本地工具：Shell 命令、Python 执行、文件系统操作、TODO 管理和后台任务工具。
- 支持通过 stdio 或 SSE 连接外部 MCP 服务器。
- 基于 Prompt-toolkit 的交互式命令行界面。
- 内置默认指令和技能包，支持配置额外的技能目录。
- 无内置沙箱隔离；如需隔离，请在外部沙箱中运行。

## 环境要求

- Python 3.12+。
- 推荐使用 `uv` 进行安装和运行。
- 所选 OpenAI 兼容服务商的 API 密钥，例如 `OPENAI_API_KEY` 或 `OPENROUTER_API_KEY`。
- 外部 MCP 服务器的可选依赖，例如基于 NPM 的服务器需要 Node.js/npm。

## 安装

使用 `uv` 安装：

```bash
uv tool install coding-assistant-cli
```

本地开发：

```bash
uv sync
```

## 快速开始

启动交互式会话：

```bash
coding-assistant --model "openai/gpt-5-mini"
```

查看可用选项：

```bash
coding-assistant --help
```

公开支持的接口为 CLI 命令行界面。内部 Python 模块可能在不通知的情况下发生变更。

## CLI 参数说明

- `--model`：选择使用的模型（必填）。
- `--instructions`：追加自定义指令。
- `--mcp-servers`：以 JSON 字符串形式配置外部 MCP 服务器。
- `--trace`：记录模型请求和响应的追踪日志。
- `--wait-for-debugger`：在 `1234` 端口等待调试器连接。
- `--skills-directories`：加载额外的技能目录。

CLI 为交互式模式。启动时会打印一个本地 WebSocket 端点；当会话空闲时，远程客户端可通过该端点向同一会话发送提示、接收流式更新并取消当前运行。

交互式 CLI 还支持以下命令：

- `/exit`
- `/help`
- `/compact`
- `/image <路径或URL>`

## MCP 服务器

通过重复使用 `--mcp-servers` 参数并传入 JSON 字符串来配置 MCP 服务器。同时支持基于 stdio 的服务器和远程 SSE 服务器。

stdio 服务器示例：

```json
{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "{home_directory}"]
}
```

SSE 服务器示例：

```json
{
  "name": "remote-mcp",
  "url": "http://localhost:8000/sse"
}
```

参数支持变量替换，可用变量包括 `{home_directory}` 和 `{working_directory}`。

示例：

```bash
coding-assistant \
  --model "openrouter/openai/gpt-4o-mini" \
  --mcp-servers \
    '{"name": "filesystem", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "{home_directory}"]}' \
    '{"name": "fetch", "command": "uvx", "args": ["mcp-server-fetch"]}'
```

## 内置本地工具

默认 CLI 包含以下本地工具：

- `shell_execute`：执行 Shell 命令。
- `python_execute`：运行 Python 代码片段。
- `filesystem_write_file` 和 `filesystem_edit_file`：针对性的文件修改操作。
- `todo_add`、`todo_list_todos` 和 `todo_complete`：TODO 任务跟踪。
- `tasks_list_tasks`、`tasks_get_status`、`tasks_get_output`、`tasks_kill_task` 和 `tasks_remove_task`：后台任务管理。

核心运行时还内置了辅助工具，例如 `compact_conversation` 和 `redirect_tool_call`。

## 技能（Skills）

编程助手目前内置了一个示例技能：

- `example`

该示例用于演示技能打包机制和 `SKILL.md` 的预期布局。项目有实际内置技能后，可以替换或删除此示例。

通过 `--skills-directories` 可添加更多技能。每个额外的技能目录下应包含含有 `SKILL.md` 文件的子目录：

```text
skills-root/
├── my-skill/
│   ├── SKILL.md
│   ├── references/
│   └── scripts/
└── another-skill/
    └── SKILL.md
```

默认 CLI 提供以下技能工具：

- `skills_list_resources`
- `skills_read`

这些工具仅暴露内置及已配置技能目录中的文件。

技能名称在内置技能和用户自定义技能中必须唯一。如发生冲突，CLI 会立即报错并提示冲突目录。

## 外部沙箱隔离

本项目已移除内置沙箱功能。如需文件系统隔离，请在外部沙箱（如 `bubblewrap`）中运行助手。

参见 [docs/sandboxing.md](docs/sandboxing.md) 获取最简 `bubblewrap` 使用示例。

## Shell 与 Python 工具行为说明

内置的 `shell_execute` 和 `python_execute` 工具：

- 支持多行脚本；
- 将 stderr 合并到 stdout 输出；
- 仅在非零退出码时在输出前加上退出码头部信息；
- 支持 `truncate_at` 参数以限制输出大小；
- 支持 `timeout` 参数，默认超时为 30 秒；
- 可将长时间运行的任务交给后台任务管理器处理。

不支持交互式终端程序，例如 `git rebase -i`。

## 开发

运行测试：

```bash
just test
```

运行代码检查、格式化和类型检查：

```bash
just lint
```

还提供集成测试目标：

```bash
just test-integration
```

## 许可证

MIT