项目唯一维护仓库是 dsSep/pico。原 pico-agent 仓库仅有重复的 README，现已统一到这里；包名、CLI 命令和模块入口均保持 pico。
pico 是一个面向代码仓库的轻量本地 coding agent。它直接跑在终端里，先看当前工作区，再用一组受约束的工具去读文件、改文件、跑命令，并把会话状态保存在本地 .pico/ 目录里。
它更像一个能在仓库里持续工作的命令行助手，不是纯聊天窗口。你可以拿它做代码排查、测试修复、仓库分析，或者让它在当前项目里执行一次性的工程任务。
无需安装 Python、配置环境或提供 API Key，在浏览器中选择任务，即可逐步查看 Pico 的工具调用、权限检查与完整执行记录。
| 演示场景 | 可以观察什么 |
|---|---|
| 仓库结构分析 | 列出文件、读取 README 与代码、形成分析结果 |
| 测试失败排查 | 查看失败夹具与相关源码，理解只读诊断与修复建议 |
| 权限与失败处理 | 观察只读写入拒绝、参数校验错误，以及模型如何继续返回说明 |
当前版本为 测试夹具 / 运行记录回放：使用真实 Pico 执行框架和工具生成记录，模型决策由脚本预设。它不会实时调用模型或执行访客命令，也不将回放结果作为模型能力基准。
- 在本地仓库里排查测试失败
- 读取当前代码结构并给出修改建议
- 基于现有文件做小步迭代，而不是脱离仓库空想
- 在会话中保留上下文，支持继续上一次工作
- 包名是
pico - CLI 命令是
pico - 模块入口是
python -m pico - 会话保存在
.pico/sessions/ - 每次运行的工件保存在
.pico/runs/<run_id>/ - 支持四类模型后端：
- Ollama
- OpenAI 兼容 Responses API
- Anthropic 兼容 Messages API
- DeepSeek Anthropic 兼容 API
以下为早期界面示例，provider 和默认值以当前 python -m pico --help 及本文配置说明为准。
CLI 帮助信息：
启动界面：
REPL 内置命令与会话路径：
需要 Python 3.10+。
如果你用 uv，直接安装依赖：
uv sync如果你已经在自己的 Python 环境里工作，也可以直接装成可编辑模式：
pip install -e .在当前仓库里启动交互模式。默认 provider 是 DeepSeek：
uv run pico指定另一个工作目录：
uv run pico --cwd /path/to/repo直接跑一次性任务：
uv run pico "inspect the test failures and propose a fix"如果当前环境已经安装过包，也可以直接这样启动：
python -m picoPico 启动时会读取项目根目录的 .env。本地真实 key 放在 .env，仓库只保留 .env.example。配置优先级是：
显式 CLI 参数 > .env 里的 PICO_* 变量 > 旧环境变量 > 代码默认值
Provider 选择的具体顺序是：
--provider > PICO_PROVIDER > 代码默认 deepseek
不传 --provider 且没有 PICO_PROVIDER 时默认使用 deepseek。这是推荐配置路径：DeepSeek 的 Anthropic-compatible endpoint 比本地 Ollama 更少依赖本机模型环境，也比 OpenAI-compatible/Anthropic-compatible 代理少一层默认 gateway 假设。其他 provider 仍然保留，可以在 .env 里写 PICO_PROVIDER=openai、PICO_PROVIDER=anthropic、PICO_PROVIDER=ollama，也可以显式传 --provider openai、--provider anthropic 或 --provider ollama。
.env 会在构建 provider client 前加载，并覆盖当前进程里的同名环境变量。模型名和 base URL 可以通过 --model、--base-url 临时覆盖；API key 只从环境变量读取。
本地第一次配置：
cp .env.example .env然后把要使用的 provider key 填进去。.env 已经被 .gitignore 忽略，不要提交真实 key。
最小配置只需要 key：
PICO_DEEPSEEK_API_KEY="your-api-key"默认模型和接口是：
PICO_DEEPSEEK_API_BASE="https://api.deepseek.com/anthropic"
PICO_DEEPSEEK_MODEL="deepseek-v4-pro"所以常规情况下 .env 里只填 PICO_DEEPSEEK_API_KEY 就能直接启动：
uv run pico如果你需要临时切模型或代理地址，不必改 .env，可以直接覆盖：
uv run pico --model deepseek-v4-pro --base-url https://api.deepseek.com/anthropicDeepSeek 当前走 Anthropic-compatible Messages API，所以 runtime 里复用的是 Anthropic-compatible client；这只影响 HTTP 协议，不影响 CLI 用法。
Pico 当前使用文本编码的工具协议，因此会在 DeepSeek 请求中显式关闭 provider-native thinking，避免思考内容耗尽单步输出预算或产生无法回放的 thinking block。后续如果接入原生工具协议，需要同时实现 thinking block 的完整回放，不能只删除这个开关。
right.codes 在 Pico 里有两条可选 provider 路径：
--provider openai：走 OpenAI-compatible/responses，默认 base URL 是https://www.right.codes/codex/v1，默认模型是gpt-5.4--provider anthropic：走 Anthropic-compatible/messages，默认 base URL 是https://www.right.codes/claude/v1，默认模型是claude-sonnet-4-6
如果 right.codes 给你的是一把共享 key，推荐只填这一项：
PICO_RIGHT_CODES_API_KEY="your-right-codes-key"然后按需要选择 provider：
uv run pico --provider openai
uv run pico --provider anthropic如果你想显式区分两条 provider 的 key，也可以分别配置：
PICO_OPENAI_API_KEY="your-right-codes-key-for-codex"
PICO_ANTHROPIC_API_KEY="your-right-codes-key-for-claude"不要在 .env 里写 PICO_OPENAI_API_KEY=$PICO_RIGHT_CODES_API_KEY 这种 shell 展开形式；Pico 的 .env 解析器只读取字面量，不展开变量引用。要么只写 PICO_RIGHT_CODES_API_KEY，要么把 key 字符串分别填到 provider-specific 变量里。
如果请求 right.codes 返回 API Key额度不足，说明协议和 endpoint 已经打通，但当前 key 没有可用额度；换一把有额度的 key，或到 right.codes 后台处理额度。
当前 provider 环境变量：
| provider | base URL | API key | model |
|---|---|---|---|
deepseek |
PICO_DEEPSEEK_API_BASE，回退 DEEPSEEK_API_BASE，默认 https://api.deepseek.com/anthropic |
PICO_DEEPSEEK_API_KEY，回退 DEEPSEEK_API_KEY |
PICO_DEEPSEEK_MODEL，回退 DEEPSEEK_MODEL，默认 deepseek-v4-pro |
openai |
PICO_OPENAI_API_BASE，回退 OPENAI_API_BASE，默认 https://www.right.codes/codex/v1 |
PICO_OPENAI_API_KEY，回退 OPENAI_API_KEY、PICO_RIGHT_CODES_API_KEY、RIGHT_CODES_API_KEY、PICO_ANTHROPIC_API_KEY、ANTHROPIC_API_KEY |
PICO_OPENAI_MODEL，回退 OPENAI_MODEL，默认 gpt-5.4 |
anthropic |
PICO_ANTHROPIC_API_BASE，回退 ANTHROPIC_API_BASE，默认 https://www.right.codes/claude/v1 |
PICO_ANTHROPIC_API_KEY，回退 ANTHROPIC_API_KEY、PICO_RIGHT_CODES_API_KEY、RIGHT_CODES_API_KEY、PICO_OPENAI_API_KEY、OPENAI_API_KEY |
PICO_ANTHROPIC_MODEL，回退 ANTHROPIC_MODEL，默认 claude-sonnet-4-6 |
ollama |
--host，默认 http://127.0.0.1:11434 |
不需要 | --model，默认 qwen3.5:4b |
如果有额外的敏感环境变量需要从 trace/report 里脱敏，可以用 PICO_SECRET_ENV_NAMES 配置逗号分隔的变量名，或启动时重复传 --secret-env-name NAME。
如果要改用 OpenAI-compatible /responses 服务，显式传 --provider openai：
uv run pico --provider openai默认 OpenAI 兼容接口使用 right.codes 的 Codex endpoint：
PICO_OPENAI_API_BASE="https://www.right.codes/codex/v1"
PICO_RIGHT_CODES_API_KEY="your-right-codes-key"
PICO_OPENAI_MODEL="gpt-5.4"也可以改成其他 OpenAI-compatible 服务：
PICO_OPENAI_API_BASE="https://your-api.example/v1"
PICO_OPENAI_API_KEY="your-api-key"
PICO_OPENAI_MODEL="gpt-5.4"如果要改用 Anthropic-compatible 服务，显式传 --provider anthropic：
uv run pico --provider anthropic默认 Anthropic 兼容接口使用 right.codes 的 Claude endpoint：
PICO_ANTHROPIC_API_BASE="https://www.right.codes/claude/v1"
PICO_RIGHT_CODES_API_KEY="your-right-codes-key"
PICO_ANTHROPIC_MODEL="claude-sonnet-4-6"如果你的服务端对多个兼容接口复用了同一套密钥，pico 也支持从 PICO_ANTHROPIC_API_KEY 回退到 ANTHROPIC_API_KEY、PICO_RIGHT_CODES_API_KEY、RIGHT_CODES_API_KEY、PICO_OPENAI_API_KEY 或 OPENAI_API_KEY。
如果要改用本地 Ollama，显式传 --provider ollama：
ollama serve
ollama pull qwen3.5:4b
uv run pico --provider ollama --model qwen3.5:4b/help：查看内置命令/memory：查看提炼后的工作记忆/session：查看当前会话文件路径/reset：清空当前会话状态/exit或/quit：退出 REPL
pico 不会默认把所有动作都放开。像 shell 执行、文件写入这类高风险操作，会受审批模式控制：
--approval ask--approval auto--approval never
每次运行结束后，都会在 .pico/runs/<run_id>/ 下写出这些文件：
task_state.jsontrace.jsonlreport.json
这些内容默认只保存在本地，不需要跟仓库一起提交。
常用本地检查：
uv run pytest tests -q
uv run ruff check pico tests scripts内部代码现在按较轻的边界拆分：pico/evaluation/ 放 benchmark 和 metrics，pico/providers/ 放模型 provider client，pico/features/ 放可选运行时能力。新代码应直接使用这些包路径；旧的 pico.evaluator、pico.metrics、pico.models 和 pico.memory import 不再作为公共入口保留。
贡献与验证步骤见 CONTRIBUTING.md，凭据与漏洞报告说明见 SECURITY.md。教学版位于 examples/mini-pico/，与完整版本一起维护。
仓库尚未指定开源许可证。代码公开可读，复制、修改和分发权限需要由后续许可证明确。