dev-agent

本地可部署的 AI Coding Agent（TypeScript / Node.js CLI）。

用一句话描述任务，Agent 在本机对目标 Git 仓库完成：理解结构 → 改代码；可选写测试 / 跑 pnpm test / 失败自动修复。另提供多轮只读 Chat 问答。代码与文件系统留在你的机器上，仅 LLM API 请求会出网。

功能概览

能力	命令	说明
编码任务	deva run	扫描（静默索引）→ 理解 → 生成；加 --test 才写测 / 跑测 / 修复
多轮问答	deva chat	REPL + 只读 tools（读文件 / 读 PDF / 列目录 / git）+ RAG 片段
代码索引	deva index	主动建索引 / --rebuild 强制重建（平时 run/chat 会静默 ensure）
多模型	环境变量	DeepSeek（默认）、Anthropic、OpenAI；embedding 走本地 Ollama
执行护栏	shell 工具	命令白名单；删除 / git rm / force-push 等高危操作需人工确认

规划中（未完成）： 任务/项目记忆（SQLite）等，见 docs/specs/local-coding-agent-mvp.md。

环境要求

• Node.js ≥ 20.6（使用 process.loadEnvFile）
• pnpm 9.x（本仓库以 pnpm 为准）
• 仅在使用 --test 时需要目标仓库能执行 pnpm test
• 代码 RAG（可选）：本机 Ollama + embedding 模型（默认 nomic-embed-text）。未启动时任务仍可跑，只是没有检索增强

安装（本机部署）

git clone https://github.com/yellowryan/dev-agent.git
cd dev-agent
pnpm install
pnpm build

可选：把 CLI 链到全局，之后任意目录可用 deva：

pnpm build
pnpm link --global
# 使用：deva run "..."   /   deva chat

开发态不必全局安装，直接用：

pnpm dev run "..."
pnpm dev chat

配置

复制环境变量模板并填入至少一个供应商的 API Key：

cp .env.example .env

.env 示例：

# 默认 deepseek
DEEPSEEK_API_KEY=sk-...

# 或切换供应商
# LLM_PROVIDER=anthropic | openai | deepseek
# ANTHROPIC_API_KEY=
# OPENAI_API_KEY=

# 可选
# LLM_MODEL=
# LLM_BASE_URL=

# RAG embedding（本地 Ollama，默认 nomic-embed-text）
# OLLAMA_BASE_URL=http://127.0.0.1:11434
# OLLAMA_EMBED_MODEL=nomic-embed-text

.env 已加入 .gitignore，不要提交密钥。

用法

未指定路径时，默认使用当前工作目录作为目标仓库。

一次性编码任务

# 开发态（默认只改代码，不跑测试）
pnpm dev run "给 UserService 加一个 deleteUser 方法"
pnpm dev run "给 UserService 加一个 deleteUser 方法" D:\path\to\other-repo

# 需要写测 + 跑 pnpm test + 失败修复时再加 --test
pnpm dev run "给 UserService 加一个 deleteUser 方法" --test

# 已 link / 已 build 后
deva run "修复登录页的空指针"
deva run "列出这个仓库的主要目录结构" .
deva run "加功能并自测" . --test

默认流程：理解仓库（只读）→ 生成/修改代码 → done。
加 --test 后才会：编写测试 → 执行 pnpm test → 失败则修复循环（默认最多 5 次；连续相同错误签名会 Escalate）。

多轮 Chat（只读）

pnpm dev chat
# 或
pnpm dev chat D:\path\to\repo
deva chat

进入后在提示符下输入问题；/exit 或 /quit 退出。

you> package.json 里项目名叫什么？
assistant> ...
you> /exit

Chat 不会改文件；需要改代码请用 deva run。详见 docs/specs/cli-chat-v1.md。

代码索引（RAG）

索引落在目标仓库的 .deva/rag/（已 gitignore）。deva run / deva chat 在 Scanning 阶段会静默 ensure：指纹未变则跳过，变了才重建。也可主动触发：

# 确保索引最新（与静默逻辑相同）
deva index
pnpm dev index

# 强制全量重建
deva index . --rebuild

需要本机 Ollama 可用，例如：

ollama pull nomic-embed-text

开发

pnpm install
pnpm test          # vitest
pnpm typecheck
pnpm build
pnpm dev run "..." # tsx 直接跑源码

相关文档

路径	说明
docs/specs/local-coding-agent-mvp.md	MVP 产品规格
docs/specs/cli-chat-v1.md	Chat REPL 规格
docs/adr/0001-chat-vs-task-runtime.md	Chat 与 Task Runtime 分入口决策
AGENTS.md	Agent / 票务约定
CONTEXT.md	领域上下文