vague-code

面向真实编码场景的轻量级本地 Coding Agent CLI。自研 Agent Runtime、可控工具系统、四层上下文压缩、冲突可串行化并发调度、权限安全体系与跨会话记忆，以及配套的自动化评测工具链。

Powered by DeepSeek V4 Flash (or any OpenAI/Anthropic compatible backend).

架构

┌─────────────────────────────────────────────────────────────────────┐
│  CLI (Rich Renderer) + TUI (Textual) ──── thin shell              │
├─────────────────────────────────────────────────────────────────────┤
│  Agent Runtime (ReAct Loop + Retry + Checkpoint/Resume)             │
│  ┌─────────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────────┐  │
│  │ Tool System │ │ Context  │ │Security  │ │ Memory System      │  │
│  │ 7 核心工具  │ │五层压缩  │ │4 种模式  │ │SQLite 统一记忆库   │  │
│  │ 并发调度    │ │KV Cache  │ │审计日志  │ │episodic 按需检索   │  │
│  │ 冲突可串行化│ │分层注入  │ │纯函数决策│ │增量蒸馏            │  │
│  └─────────────┘ └──────────┘ └──────────┘ └────────────────────┘  │
│                          │                                          │
│  Model Abstraction ──────┴─── Codecs (DeepSeek / Anthropic) ────→  │
│  Custom IR (text/thinking/tool_use/tool_result) + Unified Stream    │
├─────────────────────────────────────────────────────────────────────┤
│  Trajectory (Event-Sourced JSONL → SQLite)                          │
├─────────────────────────────────────────────────────────────────────┤
│  Repo Map (tree-sitter 符号索引) ── code_search 工具 + 地图注入     │
├─────────────────────────────────────────────────────────────────────┤
│  Eval Harness ── 31 tasks (官方保留) ── 真验收/pass^k ── Report     │
└─────────────────────────────────────────────────────────────────────┘

安装

pip install vague-code

要求 Python ≥ 3.12（支持 Windows / Linux）。安装后提供 vague-code 命令，也可用 python -m vague_code.cli。

配置 API Key

vague-code 依次从 .env 文件（当前工作目录）与环境变量读取密钥，二者任一即可：

方式 1：.env 文件（推荐，跨平台一致）

在你要运行 Agent 的目录下创建 .env 文件：

DEEPSEEK_API_KEY=sk-xxxxxx
# ANTHROPIC_API_KEY=sk-ant-xxxxxx   # 使用 --provider anthropic 时

方式 2：环境变量

# Linux / macOS
export DEEPSEEK_API_KEY=sk-xxxxxx
# Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-xxxxxx"
# Windows cmd
set DEEPSEEK_API_KEY=sk-xxxxxx

API Key 获取：DeepSeek 开放平台（https://platform.deepseek.com）创建；`--provider anthropic` 使用 Anthropic 风格配置（默认指向 DeepSeek 的 Anthropic 兼容端点，密钥同样在 DeepSeek 平台获取）。

使用 GPT 系列模型（OpenAI 官方）

export OPENAI_API_KEY=sk-proj-xxxxxx
vague-code --provider openai --model gpt-4o "Fix the bug in stats.py"
vague-code tui --provider openai --model gpt-4o

任何 OpenAI 兼容端点均可通过 --base-url / --api-key-env 接入（OpenRouter、Moonshot 等）：

vague-code tui --base-url https://openrouter.ai/api/v1 --api-key-env OPENROUTER_API_KEY --model openai/gpt-4o

备注：--provider 三选一（deepseek/openai/anthropic），未指定 --base-url/--api-key-env 时按 provider 取默认端点与密钥环境变量；token 预算按模型自动匹配（GPT 系列用 OpenAI 词表，窗口含 gpt-4o 128K / gpt-4.1 1M / o3-mini 200K）。

快速开始

# 运行 Agent（CLI 模式）
vague-code "Fix the bug in stats.py"
vague-code --provider anthropic "Refactor auth module"

# 运行 Agent（TUI 模式 — 全屏交互界面）
vague-code tui "Fix the bug in stats.py"
vague-code tui --model deepseek-v4-pro "Analyze the project structure"

# 运行评测（现行体系：真验收 + sanity gate + pass^k，详见 eval/README.md）
python -m eval.cli --tasks eval/tasks.json --fake          # 验证框架
python -m eval.cli --tasks eval/tasks.json --model deepseek-v4-flash --max-turns 25  # 真实 API（20 题本机可跑）
python -m eval.cli --tasks eval/tasks.json --repeat 3 --out report.md  # 消融实验

从源码运行（开发者）：uv sync 安装依赖后，把上述命令中的 vague-code 换成 python -m vague_code.cli 即可。

TUI 模式

vague-code tui [task] 启动全屏交互式终端界面（基于 Textual 框架，v2 分层架构见 docs/adr/0019-tui-v2-architecture.md）。

布局

• Topbar — brand · 运行状态 · provider/model · 权限模式 · 工作目录（窄屏自动截断）
• Conversation View — 流式 Markdown 渲染；消息类型左边线分色（用户=青 / 助手=绿 / 工具=灰 / 权限=琥珀 / 错误=红）；thinking 超长自动折叠（T 展开）
• Activity Line — 状态动画（thinking [..] / running [= ] / streaming [> ]）+ 回合指标（12.3s · 2 tools）
• Composer — 多行输入（Shift+Enter 换行），运行中发送进入 guidance 队列，下一轮生效

键绑定

斜杠命令

权限

交互式确认对话框：Y 允许一次，Ctrl+Y 始终允许并持久化规则至 .agent/permission-rules.json，N 拒绝。 对 write_file/patch 会先展示写入前 diff 预览（红删绿增）；拒绝时可填理由，理由会回传给模型（反馈闭环）。

选项

vague-code tui [task] [--model] [--max-turns] [--db-path] [--provider] [--timeout-s]

提示：vague-code 命令需要激活虚拟环境（uv run vague-code tui ... 或先 .venv\Scripts\Activate.ps1）。

核心模块

评测结果

⚠️ 早期 v0.1 的 83%/93% 等数字基于假 pass/fail（验收测试未实跑），已废弃且不得引用。 2026-08 起评测体系按 docs/plans/0016-eval-methods.md 全面升级：真验收（sanity gate 双检 + F2P/P2P 实跑）、pass^k 可靠性、任务集按 OpenAI SWE-bench Verified 官方标注重建。

现状（详见 docs/handoff/2026-08-03-vague-code-eval-system.md 与 docs/handoff/2026-08-05-vague-code-concurrency-and-ablation.md）：

• 任务集 31 题（全部官方保留，17 道脏题已剔除），本机可跑 20 题（sympy 17 + sphinx 2 + pytest 1）

• 环境策展 5 仓实证验证（sanity gate 全过）；sklearn/astropy 10 题需 MSVC/Linux CI

• 8 题小消融（2026-08-05，max_turns 25，k=1，$3.05）：

  cell	pass	输入 token	缓存命中率	成本
  基线全开	5/8	5.65M	27%	$1.35
  关压缩	4/8	7.92M	93%	$0.78
  关 RepoMap	4/8	7.01M	80%	$0.91

  要点：① 压缩减少 29% 输入 token（stale_snip 单层回收 14.1 万 token），pass rate 方向性支持（基线 5/8 最高）；② 压缩改写历史导致 KV Cache 命中率从 93% 降至 27%，单 token 成本升 4 倍，净成本反升——压缩与 Cache 的张力待长任务验证；③ 8 题均短，microcompact/auto_compact/truncate 未触发，五层流水线收益需长任务实验。

• 20 题基线消融待跑（P1）：python -m eval.cli --tasks eval/tasks.json --max-turns 25 --repeat 3

项目结构

vague-code/
├── vague_code/agent/                 # Agent 核心包
│   ├── loop.py                # ReAct 主循环
│   ├── tools.py               # 6 个基础工具 + code_search spec
│   ├── concurrency.py         # 冲突可串行化并发
│   ├── context_compress.py    # 五层压缩流水线
│   ├── context.py             # 系统提示构建
│   ├── context_tokens.py      # Token 计数 + 预算
│   ├── context_rules.py       # 规则文件层级加载
│   ├── permission.py          # 权限系统
│   ├── memory.py              # 记忆系统
│   ├── memory_tool.py         # memory_search 工具
│   ├── repomap.py             # tree-sitter 符号索引（code_search + 地图注入）
│   ├── config.py              # AgentConfig 配置
│   ├── ir.py                  # 自定义 IR dataclass
│   ├── backend.py             # LLM 后端适配层
│   └── codecs/                # 厂商 codec
│       ├── deepseek.py        # DeepSeek codec
│       └── anthropic.py       # Anthropic codec
├── eval/                      # 评测框架
│   ├── cli.py                 # 评测 CLI 入口
│   ├── harness.py             # Agent 驱动 + 真验收（verify/metrics 接入）
│   ├── env.py                 # 每 repo venv 策展（REPO_SETUP）
│   ├── verify.py              # 验收执行器（sanity gate 双检 + F2P/P2P）
│   ├── matrix.py              # 实验矩阵展开
│   ├── reporter.py            # Markdown 报告（pass^k + 失败分布）
│   ├── metrics.py             # 确定性轨迹指标
│   ├── judge.py / rubric.py   # LLM-as-Judge（离线）
│   ├── classify.py            # 八类失败分类
│   ├── audit_tasks.py / audit_ui.py  # 任务质量筛查（HTML 打分页）
│   ├── select_verified_tasks.py      # 官方保留题选择器
│   └── tasks.json             # 31 题任务集（20 题本机可跑）
├── cli/                       # CLI 薄壳
│   ├── __init__.py            # Args + backend 创建
│   └── renderer.py            # Rich 流式渲染
├── docs/                      # 文档
│   ├── adr/                   # 18 份架构决策记录
│   ├── plans/                 # 16 份实现计划
│   ├── articles/              # 24 篇成品文章（含 README 索引）
│   ├── handoff/               # 会话交接记录
│   └── known-issues.md        # 已知问题跟踪
└── tests/                     # 586 条自动化测试

技术栈

相关知识

• Agent 架构决策目录 — 14 份 ADR，覆盖所有模块设计决策
• 完整实现计划 — 12 份，逐步骤实现
• 已知问题 — 未修复的低优问题跟踪