catalog/repos/0xmsc--coding-assistant.md

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 安装：

uv tool install coding-assistant-cli

本地开发：

uv sync

快速开始

启动交互式会话：

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

查看可用选项：

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 服务器示例：

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

SSE 服务器示例：

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

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

示例：

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 文件的子目录：

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

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

• skills_list_resources
• skills_read

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

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

外部沙箱隔离

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

参见 docs/sandboxing.md 获取最简 bubblewrap 使用示例。

Shell 与 Python 工具行为说明

内置的 shell_execute 和 python_execute 工具：

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

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

开发

运行测试：

just test

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

just lint

还提供集成测试目标：

just test-integration

许可证

MIT