189 lines
5.1 KiB
Markdown
189 lines
5.1 KiB
Markdown
# 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 |