Code Puppy
一只嘴炮满级、隐私至上的命令行 AI 编程代理，直接读写你的代码库、执行命令、多模型轮换，让昂贵的 IDE 变得多余。
自定义JSON代理支持按需选择工具并给出最小工具集示例（read-only agent），得2分；但默认code-puppy代理'Full access to all tools'包括shell执行与delete_file，扣分。用户确认机制在证据中完全缺失——shell命令、文件删除均未见确认/审批流程描述，得0分。数据流透明度仅见'100% privacy'徽章锚点而无实质内容，得1分。敏感数据处理方面：API密钥通过环境变量引用、依赖keyring、/meta-logout可清除凭据，得2分。依赖安全：依赖列表宽松且含可疑项（httpx2与httpx并存），无锁文件或审计证据，得1分。外部效应：shell执行、文件删除、浏览器工具均有，但缓解措施未记载，得1分。回滚：DBOS持久化执行支持崩溃恢复与/dbos开关，/truncate管理历史，得2分。MIT许可证与作者署名完整，得2分。
自相矛盾明显：README称durable'off by default in the dependency tree'，随后又说'/set enable_dbos false to disable (enabled by default)'；CI注明models.出厂为空而README暗示开箱即用模型——得1分。依赖可用性较好：models.dev离线回退、可配置超时、Android编译缓存说明，得2分。失败信息：不支持提供商/无工具调用模型的智能警告、测试中可见结构化错误消息，得2分。
受众与场景覆盖充分：多提供商、多代理类型、Android/Termux、自定义命令，得3分。能力边界：明确标注未充分测试的39+提供商、Android上Playwright不可用、Windows测试已知失败（CI注释），得2分。触发精度：斜杠命令与AGENTS.md加载顺序定义清晰，得2分。环境适配：macOS/Linux/Windows/Termux均有安装说明与平台注意事项，但Windows支持被CI注释承认不完整，得2分。
信息架构总体可用但README冗长且章节重复（DBOS两处描述、超时配置两处），得2分。安装说明详尽（uv/pipx/Termux分平台），得3分。命名稳定：kebab-case约定、工具与代理命名一致，得2分。示例丰富但无FAQ，得2分。已知局限有诚实标注（未测试提供商、平台差异），得2分。LICENSE文件、pyproject与徽章三处一致为MIT，得3分。版本号0.0.827存在但变更日志依赖外链Kittylog而非仓库内文件，得1分。维护责任：作者署名、CI、Discord存在，但无贡献/治理/安全策略文件证据，得1分。
输出可用性：CLI/TUI、rich输出、/truncate等上下文管理工具，得2分。边际价值：65+提供商聚合、JSON代理系统、DBOS持久化提供差异化价值，得2分。成本收益：需多提供商API密钥、计费信息仅在/add_model预览中出现，整体运行成本无量化说明，得1分。
声明可追溯性弱：170k下载、Build/Tests Passing徽章指向外部状态，仓库内无法核实；'1024 puppies'等营销表述与事实混杂，得1分。跨源印证：README、pyproject、CI大体一致但DBOS默认值与models.存在矛盾，得1分。事实与推断分离：部分做到（明确标注'not been tested thoroughly'），但隐私承诺等关键声明无支撑细节，得1分。
- 默认代理拥有shell执行、文件删除等全部工具权限，且文档中未见任何用户确认/审批机制——在生产环境使用前应自行加装确认层或使用受限工具集的自定义代理。
- 文档自相矛盾：DBOS持久化默认开还是关，README两处描述冲突，使用前请在当前版本中实际验证。
- 39+提供商的OpenAI兼容端点'未经充分测试'，密钥经这些端点发送前请自行评估。
- 隐私声明仅有徽章级别断言，未见具体数据流说明；Meta OAuth凭据复用~/.config/muse/auth.，请确认共享凭据的影响范围。
- 变更日志、贡献指南、安全策略均不在仓库内，维护可持续性无法从源码评估。
这个 Agent 能做什么，适合哪些场景？
Code Puppy 是一个基于 Pydantic AI 构建的终端 AI 编程代理，由 mpfaffenberger 以 MIT 许可开源发布在 GitHub（mpfaffenberger/code_puppy），并通过 PyPI 以 code-puppy 分发，下载量超过 17 万。它通过 uvx 在终端运行，可以列出和读取文件、用 grep 搜索、创建和编辑文件、应用多文件补丁、执行 shell 命令，并可解释其推理过程。它通过 models.dev 集成支持 65 个以上提供商和 1000 多个模型（包括 OpenAI、Anthropic、Google、Cerebras、Groq、xAI、Ollama 本地模型和 Meta Muse OAuth），并提供轮询分发以绕过速率限制。内置的代理系统支持 Python 代理（如默认的 code-puppy 和 agent-creator）以及用户用 JSON 定义的自定义代理，还支持 MCP 服务器、DBOS 持久化执行、AGENTS.md 规则和自定义斜杠命令。该项目承诺零遥测、零提示日志记录，可以选择完全本地运行。
在终端中，Code Puppy 通过 uvx code-puppy -i 启动，读取 ~/.code_puppy/extra_models. 中的模型配置，并连接到配置的 LLM 提供商。在交互式会话中，它使用文件系统工具（list_files、read_file、grep、create_file、edit、replace_in_file、apply_patch、delete_snippet、delete_file）、用于 shell 命令的 agent_run_shell_command，以及用于解释其推理过程的 agent_share_your_reasoning。用户使用 /model 切换模型，使用 /agent 在代理之间切换（包括内置的 code-puppy 和 agent-creator，或 ~/.code_puppy/agents/ 中的自定义 JSON 代理），使用 /add_model 从 models.dev 添加模型，使用 /mcp 管理 MCP 服务器，并使用 /dbos 切换 DBOS 持久化执行（将代理输入、LLM 响应、MCP 调用和工具调用进行检查点保存，以便在崩溃后恢复）。它按照搜索顺序加载 AGENTS.md 规则（~/.code_puppy/AGENTS.md、.code_puppy/AGENTS.md、./AGENTS.md），从 .claude/commands/ 或类似目录运行自定义斜杠命令，并可以在 extra_models. 中配置多个 API 密钥进行轮询模型轮换。
- 在 CLI 终端（而非 IDE）中完成日常工作流、希望 AI 代理直接编辑文件并运行命令的开发者。
- 因 Windsurf 或 Cursor 等订阅工具的价格上涨和模型访问受限而感到沮丧、想要一个开源替代方案的用户。
- 在多个提供商（如 Cerebras、Groq、xAI 等）之间拥有多个 API 密钥，并希望通过轮询分发以保持在速率限制内的团队。
- 需要持久化、可恢复的长时运行代理任务，并希望对每个检查点（LLM 响应、工具调用、MCP 调用）进行存档的工程师，可通过 DBOS 集成实现。
- 注重隐私的开发人员，通过将 Code Puppy 指向本地 VLLM/SGLang/Llama.cpp 端点来运行它，确保任何数据都不会离开其网络。
- 想要构建和共享带有自定义系统提示和受限工具访问权限的专用编码代理（代码审查员、Python 导师、DevOps 助手），而无需编写 Python 代码的用户，可通过 JSON 代理模式实现。
这个 Agent 有哪些优点和局限？
- 完全开源（MIT 许可），拥有结构上的隐私承诺：零遥测、零提示日志记录、零第三方共享，并带有完全本地选项。
- 通过 models.dev 集成提供广泛的多提供商支持：65 个以上提供商、1000 多个模型，外加内置提供商（Synthetic、Cerebras、OpenAI、Google、Anthropic）、Meta Muse OAuth 和用于本地模型的 Ollama。
- 使用轮询模型分发和自定义端点超时，以对抗速率限制和不可靠的端点。
- 通过 DBOS 检查点实现持久化执行，可以在崩溃后恢复长时运行的代理运行（代理输入、LLM 响应、MCP 和工具调用）。
- 可扩展的代理系统：无需 Python 即可创建架构验证的 JSON 代理，或继承 BaseAgent 的 Python 代理；支持 MCP 服务器和 AGENTS.md 规则。
- 跨平台：macOS、Linux、Windows 和 Android (Termux) 均有文档记录的支持。
- 需要 Python 3.11+ 和 uv/pipx 工具链；基于 uvx 的工作流对于不熟悉 Python 工具的开发者来说增加了设置成本。
- 文档记录的 39 个 OpenAI 兼容提供商已被“自动配置但未经彻底测试”，且不支持工具调用的模型会收到重大警告，因为它们无法使用文件/shell 工具。
- 完全功能需要提供商 API 密钥（OpenAI、Gemini、Cerebras、Anthropic、Ollama）——这是持续的成本和配置负担。
- Android/Termux 的首次运行可能需要 10-20 分钟来编译包（如 pydantic-core、cryptography），并且未安装 Playwright 浏览器工具。
- README 将其定义为对 Windsurf/Cursor 的反感式替代——没有记录企业级功能、保证的 SLA 或后端支持，因为它是一个没有企业或投资者支持的独立项目。
如何安装或部署这个 Agent？
先决条件：Python 3.11+，以及至少一个配置的提供商 API 密钥（如 OPENAI_API_KEY、GEMINI/Google、Cerebras、Anthropic 或本地 Ollama 端点）。
macOS / Linux（推荐使用 uv）：
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx code-puppyWindows（PowerShell 作为管理员）：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"uvx code-puppy （或作为全局工具安装，以获得更好的 Ctrl+C/Ctrl+X 快捷键支持）
Android（Termux）：
pkg update && pkg install python rust ripgrep libjpeg-turbo git
python -m pip install pipx && pipx ensurepath
pipx run code-puppy可选持久化执行插件：
pip install "code-puppy[durable]"首次调用：uvx code-puppy -i
如何使用这个 Agent？
- 使用
uvx code-puppy -i启动交互式会话。 - 设置提供商密钥环境变量（例如 OPENAI_API_KEY、GROQ_API_KEY、XAI_API_KEY），或在
~/.code_puppy/extra_models.中定义自定义/轮询模型。 - 使用
/model选择模型；使用/add_model浏览 models.dev 中的 65 个以上提供商。 - 使用纯语言描述你的编程任务；代理将使用其文件、grep、编辑、补丁和 shell 工具读取你的仓库、修改代码并运行命令。
- 使用
/agent <name>切换代理，或使用/agent agent-creator构建新的 JSON 代理。 - 使用
/mcp管理 MCP 服务器，使用/dbos on启用持久化执行，使用/truncate <N>削减消息历史记录。 - 在
~/.code_puppy/AGENTS.md或项目AGENTS.md中定义项目编码标准；将自定义斜杠命令放入.claude/commands/、.github/prompts/或.agents/commands/。
这个 Agent 与同类方案有什么区别？
README 明确将 Code Puppy 定位为 Windsurf 和 Cursor 的开源、注重隐私、基于终端的替代方案，并将该项目描述为为了应对这些工具移除模型访问权限和提高价格而愤怒编写的。与这些订阅式 IDE 不同，Code Puppy 在任何终端中运行，自带模型，可以指向本地服务器。
常见问题
Code Puppy 会收集我的代码或使用情况数据吗？
我可以使用哪些模型，需要什么 API 密钥？
长时运行的代理任务在运行中途崩溃了怎么办？
如何创建自己的专用代理？
/agent agent-creator 进行引导式 JSON 代理创建，或者手动将 *-agent. 文件放入 ~/.code_puppy/agents/，其中包含名称、描述、系统提示、工具和可选字段（如 model 和 model_settings）。Python 代理也可以通过在 code_puppy/agents/ 中继承 BaseAgent 来添加。