零样本 CLI

🎉 v5.4 新特性： 现已支持 OpenCode CLI！您可以选择 Claude、Codex、Gemini 或 OpenCode 作为 AI 提供商。同时支持 GitHub、GitLab、Jira 和 Azure DevOps 作为问题后端。详情请参阅 提供商 和 多平台问题支持。

npm install -g @covibes/zeroshot

演示（100倍速，90分钟运行，5轮迭代直至批准）

Zeroshot 是一个开源的 AI 编码代理编排 CLI，它运行多代理工作流，以自主方式实现、审查、测试和验证代码变更。

它在隔离环境中运行一个 规划器、一个 实施者 和独立的 验证者，循环执行直到变更被 验证 或因可操作且可复现的失败而被 拒绝。

专为那些正确性比速度更重要的任务而设计。

工作原理

• 规划：将任务转化为具体的验收标准
• 实施：在隔离的工作区（本地、工作树或 Docker）中进行更改
• 验证：由独立的验证者运行自动化检查
• 迭代：重复执行，直到验证通过，或返回可操作的失败信息
• 恢复：崩溃安全的状态会被持久化以便恢复

快速开始

zeroshot run 123                    # GitHub 问题编号
zeroshot run feature.md             # Markdown 文件
zeroshot run "添加暗模式"        # 内联文本

或者直接描述一个复杂任务：

zeroshot run "添加带有自动重试的乐观锁：更新用户时，使用指数退避策略最多重试 3 次，合并不冲突的字段更改，并详细提示冲突。处理版本从 A 变为 B 再变回 A 的 ABA 问题。"

为什么不能只用一个 AI 代理？

使用场景

• 自主 AI 代码重构
• AI 驱动的拉取请求自动化
• 带有验证的自动化 bug 修复
• 软件工程中的多代理代码生成
• 带有盲验证的代理式编码工作流

适合人群

• 关注正确性和可重复性的高级工程师
• 自动化 PR 流程和代码审查关卡的团队
• 标准化代理式工作流的基础架构/平台团队
• 处理问题积压的开源维护者
• 希望获得验证而非“感觉”的 AI 高级用户

安装与要求

平台：Linux、macOS。Windows（原生/WSL）暂未支持，因为我们正在强化可靠性和多提供商的正确性。

npm install -g @covibes/zeroshot

要求：Node 18+，至少一个提供商 CLI（Claude Code、Codex、Gemini、Opencode）。

# 安装一个或多个提供商
npm i -g @anthropic-ai/claude-code
npm i -g @openai/codex
npm i -g @google/gemini-cli
# Opencode：详见 https://opencode.ai

# 使用提供商 CLI 进行认证
claude login        # Claude
codex login         # Codex
gemini auth login   # Gemini
opencode auth login # Opencode

# GitHub 认证（用于问题编号）
gh auth login

提供商

Zeroshot 会调用各个提供商的 CLI。您可以选择默认提供商，也可以在每次运行时覆盖：

zeroshot providers
zeroshot providers set-default codex
zeroshot run 123 --provider gemini

有关设置、模型级别和 Docker 挂载，请参阅 docs/providers.md。

为什么需要多个代理？

单代理会话容易失效。上下文会在数千个 token 中被淹没。模型更倾向于“完成”而不是“正确”。

Zeroshot 通过隔离的代理来解决这个问题，这些代理会相互检查彼此的工作。验证者无法对未编写的代码撒谎。如果检查失败？就修复并重试，直到真正有效为止。

区别于其他工具之处

• 盲验证：验证者永远不会看到工作者的上下文或代码历史
• 可重复的工作流：任务复杂度决定了代理数量和模型选择
• 接受/拒绝循环：拒绝结果包含可操作的发现，而非含糊的抱怨
• 崩溃恢复：所有状态都会持久化到 SQLite 数据库中；随时可以恢复
• 隔离模式：无隔离、git 工作树或 Docker 容器
• 成本控制：模型上限可防止 API 费用失控

何时使用 Zeroshot

Zeroshot 在任务具有明确的验收标准时表现最佳。

经验法则：如果您无法描述“完成”意味着什么，那么验证者就无法对其进行验证。

命令概览

# 运行
zeroshot run 123                      # GitHub 问题
zeroshot run feature.md               # Markdown 文件
zeroshot run "添加暗模式"          # 内联文本

# 隔离
zeroshot run 123 --worktree       # git 工作树
zeroshot run 123 --docker         # 容器

# 自动化（--ship 表示 --pr 表示 --worktree）
zeroshot run 123 --pr             # 工作树 + 创建 PR
zeroshot run 123 --ship           # PR + 批准时自动合并

# 后台模式
zeroshot run 123 -d
zeroshot run 123 --ship -d

# 控制
zeroshot list
zeroshot status <id>
zeroshot logs <id> -f
zeroshot resume <id>
zeroshot stop <id>
zeroshot kill <id>
zeroshot watch

# 提供商
zeroshot 提供商
zeroshot 提供商 设置默认 codex

# 代理库
zeroshot 代理 列表
zeroshot 代理 显示 <名称>

# 维护
zeroshot 清理
zeroshot 清除

多平台问题支持

Zeroshot 支持 GitHub、GitLab、Jira 和 Azure DevOps。只需粘贴问题的 URL 或编号即可。 在 Git 仓库中工作时，zeroshot 会自动从你的 Git 远程 URL 中检测问题提供商，无需任何配置！

# GitHub
zeroshot 运行 123
zeroshot 运行 https://github.com/org/repo/issues/123

# GitLab（云和自托管）
zeroshot 运行 https://gitlab.com/org/repo/-/issues/456
zeroshot 运行 https://gitlab.mycompany.com/org/repo/-/issues/789

# Jira
zeroshot 运行 PROJ-789
zeroshot 运行 https://company.atlassian.net/browse/PROJ-789

# Azure DevOps
zeroshot 运行 https://dev.azure.com/org/project/_workitems/edit/999

要求：根据你使用的平台，需要相应的 CLI 工具（gh、glab、jira 或 az)。有关设置及自托管实例，请参阅 issue-providers README。

--pr 模式注意事项：请从目标仓库目录运行 zeroshot。拉取请求将在你当前目录的 Git 远程仓库上创建。如果你从其他仓库运行，zeroshot 会发出警告并跳过“Closes #X”引用（拉取请求仍会被创建，但不会自动关闭问题）。

架构

Zeroshot 是一个基于消息驱动的协调层，具有智能默认配置。

• 调度器会根据任务的复杂性和类型对任务进行分类。
• 工作流模板会选择代理和验证者。
• 代理会将结果发布到 SQLite 账本中。
• 验证者会根据具体发现批准或拒绝。
• 被拒绝的任务会返回给执行者进行修复。

                                ┌─────────────────┐
                                │      任务       │
                                └────────┬────────┘
                                         │
                                         ▼
                ┌────────────────────────────────────────────┐
                │                 调度器                  │
                │     复杂度 × 任务类型 → 工作流       │
                └────────────────────────┬───────────────────┘
                                         │
           ┌─────────────────────────────┼─────────────────────────────┐
           │                             │                             │
           ▼                             ▼                             ▼
     ┌───────────┐                ┌───────────┐                ┌───────────┐
     │  简单任务  │                │  简单任务   │                │ 标准及以上任务 │
     │  1 个代理  │──────────▶     │  执行者    │                │ 计划者    │
     │ (初级)     │  完成        │ + 1 个验证者│                │ + 执行者  │
     │ 无验证者  │                └─────┬─────┘                │ + 3-5 个验证者│
     └───────────┘                      │                      └─────┬─────┘
                                        ▼                            │
                                 ┌─────────────┐                     ▼
                             ┌──▶│   执行者    │             ┌─────────────┐
                             │   └──────┬──────┘             │   计划者   │
                             │          │                    └──────┬──────┘
                             │          ▼                           │
                             │   ┌─────────────────────┐            ▼
                             │   │ ✓ 验证者         │     ┌─────────────┐
                             │   │   （通用检查）   │ ┌──▶│   执行者    │
                             │   └──────────┬──────────┘ │   └──────┬──────┘
                             │       拒绝   │ 全部通过     │          │
                             └──────────────┘     │      │          ▼
                                                  │      │   ┌──────────────────────┐
                                                  │      │   │ ✓ 要求               │
                                                  │      │   │ ✓ 代码（标准及以上）   │
                                                  │      │   │ ✓ 安全性（关键）      │
                                                  │      │   │ ✓ 测试员（关键）      │
                                                  │      │   │ ✓ 对抗测试           │
                                                  │      │   │   （实际执行）       │
                                                  │      │   │   （实际执行）       │
                                                  │      │   └──────────┬───────────┘
                                                  │      │       拒绝   │ 全部通过
                                                  │      └──────────────┘     │
                                                  ▼                           ▼
     ┌─────────────────────────────────────────────────────────────────────────────┐
     │                                完成                                     │
     └─────────────────────────────────────────────────────────────────────────────┘

复杂度模型

按复杂度选择模型

等级对应于特定提供商的模型。可通过 zeroshot providers setup <provider> 或 settings.providerSettings 进行配置。（旧版 maxModel 仅适用于 Claude。）

为安全关键功能创建一个 zeroshot 集群配置：

1. 实现代理（level2）负责实现该功能
2. 四个并行验证者：
   - 安全验证者：OWASP 检查、SQL 注入、XSS、CSRF
   - 性能验证者：避免 N+1 查询、正确索引
   - 隐私验证者：GDPR 合规、数据最小化
   - 代码审查员：整体代码质量
3. 所有验证者必须批准后才能合并
4. 如果任何验证者拒绝，实现代理需修复并重新提交
5. 安全验证者使用 level3（风险最高）

请参考 cluster-templates/base-templates/full-workflow.json，并创建类似的集群，保存为 cluster-templates/security-review.json

崩溃恢复

所有状态都持久化在 SQLite 账本中。您可以在任何时候恢复：

zeroshot resume cluster-bold-panther

隔离模式

Git 工作树（默认用于 --pr/--ship）

zeroshot run 123 --worktree

使用 git 工作树进行轻量级隔离。它会创建一个独立的工作目录和分支。当使用 --pr 和 --ship 时会自动启用。

Docker 容器

zeroshot run 123 --docker

在一个全新的容器中实现完全隔离。您的工作区将保持不变。适合进行高风险实验或并行运行。

何时使用哪种模式

默认行为： 代理仅修改文件，不会提交或推送，除非使用明确允许此操作的隔离模式。

# 通过设置配置（持久化）
zeroshot settings set dockerMounts '["gh", "git", "ssh", "aws", "azure"]'

# 查看当前配置
zeroshot settings get dockerMounts

# 每次运行覆盖
zeroshot run 123 --docker --mount ~/.aws:/root/.aws:ro

# 提供商凭证
zeroshot run 123 --docker --mount ~/.config/codex:/home/node/.config/codex:ro
zeroshot run 123 --docker --mount ~/.config/gemini:/home/node/.config/gemini:ro

# 禁用所有挂载
zeroshot run 123 --docker --no-mounts

# CI：环境变量覆盖
ZEROSHOT_DOCKER_MOUNTS='["aws","azure"]' zeroshot run 123 --docker

zeroshot settings set dockerMounts '[
  "gh",
  "git",
  {"host": "~/.myconfig", "container": "$HOME/.myconfig", "readonly": true}
]'

zeroshot settings set dockerContainerHome '/home/node'
# 或每次运行：
zeroshot run 123 --docker --container-home /home/node

zeroshot settings set dockerEnvPassthrough '["MY_API_KEY", "TF_VAR_*"]'

资源

• CLAUDE.md - 架构、集群配置模式、代理原语
• docs/providers.md - 提供商设置、模型等级和 Docker 挂载
• docs/context-management.md - 上下文选择、上下文包和状态快照
• Discord - 支持与社区
• zeroshot export <id> - 将对话导出为 Markdown
• sqlite3 ~/.zeroshot/*.db - 直接访问账本以进行调试

贡献

请参阅 CONTRIBUTING.md，了解开发环境搭建及贡献指南。

请在参与之前阅读 CODE_OF_CONDUCT.md。

如遇安全相关问题，请参阅 SECURITY.md。

TUI

Ratatui（Rust 实现）是目前唯一支持的 TUI。入口点如下：

• zeroshot（TTY 环境，无需参数）
• zeroshot tui
• zeroshot watch

TUI 开发

Rust 版本的 TUI 会通过标准输入输出启动一个 Node 后端。迭代时请同时运行这两部分。

单命令开发循环（自动构建并重启）：

cargo install cargo-watch
npm run dev:tui

1. 安装依赖

   npm ci
   

2. 以监听模式构建 TUI 后端

   npm run build:tui-backend -- --watch
   # 或者
   npx tsc -p tsconfig.tui-backend.json -w
   

3. 运行 Rust 版本的 TUI（在另一个终端中）

   cd tui-rs
   cargo run -p zeroshot-tui -- --ui disruptive
   

从本仓库本地运行 CLI

若希望全局使用开发分支中的 zeroshot 命令：

npm run dev:link

一条命令即可完成链接并启动 TUI 开发循环：

npm run dev:bootstrap

CLI 集成流程

使用 Node CLI 启动本地的 Rust 二进制文件：

cd tui-rs
cargo build -p zeroshot-tui
cd ..
ZEROSHOT_TUI_BINARY_PATH="$PWD/tui-rs/target/debug/zeroshot-tui" node cli/index.js tui

TUI 自定义配置

• ZEROSHOT_TUI_BACKEND_PATH 可指向特定的 lib/tui-backend/server.js
• ZEROSHOT_TUI_BINARY_PATH 可指向本地的 Rust 二进制文件
• ZEROSHOT_TUI_UI=classic|disruptive 可强制指定 UI 风格

MIT 许可证 - Covibes

基于 Anthropic 的 Claude Code 构建。

Zeroshot 快速上手指南

Zeroshot 是一个开源的 AI 编码代理编排 CLI 工具。它通过运行多智能体工作流（规划者、实现者、独立验证者），在隔离环境中自动执行代码的编写、审查、测试和验证，直到变更被确认或通过可复现的错误报告被拒绝。适用于对代码正确性要求高于速度的场景。

环境准备

系统要求

• 操作系统：Linux 或 macOS。（Windows 用户建议使用 WSL）
• Node.js：版本 18 或更高。

前置依赖 在使用 Zeroshot 之前，你需要安装并登录至少一个 AI 提供商的 CLI 工具，以及对应平台的 Issue 管理工具（如使用 GitHub Issues）。

1. 安装 AI 提供商 CLI（任选其一或多个）：

   npm i -g @anthropic-ai/claude-code
   npm i -g @openai/codex
   npm i -g @google/gemini-cli
   # Opencode 请参考其官方文档
   

2. 认证 AI 提供商：

   claude login        # Claude
   codex login         # Codex
   gemini auth login   # Gemini
   opencode auth login # Opencode
   

3. 安装平台 CLI（用于读取 Issue，以 GitHub 为例）：

   # 安装 GitHub CLI
   gh auth login
   

   注：若使用 GitLab、Jira 或 Azure DevOps，请分别安装 glab、jira 或 az 并完成认证。

安装步骤

使用 npm 全局安装 Zeroshot：

npm install -g @covibes/zeroshot

提示：如果下载速度较慢，可配置 npm 国内镜像源（如淘宝源）后再执行安装：

npm config set registry https://registry.npmmirror.com
npm install -g @covibes/zeroshot

安装完成后，可通过以下命令查看可用提供商或设置默认提供商：

zeroshot providers
zeroshot providers set-default codex

基本使用

Zeroshot 支持直接通过 Issue 编号、Markdown 文件或自然语言描述来启动任务。

1. 处理 GitHub/GitLab/Jira Issue 直接输入 Issue 编号（需在对应仓库目录下）或完整 URL：

zeroshot run 123
zeroshot run https://github.com/org/repo/issues/123
zeroshot run PROJ-789

2. 基于本地文件运行 将任务描述写在 Markdown 文件中运行：

zeroshot run feature.md

3. 直接输入自然语言指令 适合简单任务或快速原型：

zeroshot run "Add dark mode"

4. 复杂任务示例 可以直接描述复杂的逻辑需求，Zeroshot 会自动规划并验证：

zeroshot run "Add optimistic locking with automatic retry: when updating a user,
retry with exponential backoff up to 3 times, merge non-conflicting field changes,
and surface conflicts with details. Handle the ABA problem where version goes A->B->A."

常用参数

• --worktree：在 git worktree 隔离环境中运行。
• --docker：在 Docker 容器中运行（最高隔离级别）。
• --pr：完成任务后自动创建 Pull Request。
• --ship：创建 PR 并在批准后自动合并。

# 示例：在 Docker 中运行并自动创建 PR
zeroshot run 123 --docker --pr