一个运行在本地终端中的 AI 编程 Agent，能够读取项目上下文、拆解开发任务、调用工具修改代码、执行命令验证结果，并在权限边界内完成可审计、可回滚的开发闭环。
- Node.js >= 20
- pnpm >= 9
cd ~/devagent
pnpm install
pnpm buildDevAgent 通过环境变量配置，支持任何 OpenAI 兼容的 API 端点。
# 必需
export DEVAGENT_API_KEY="your-api-key"
# 可选（有默认值）
export DEVAGENT_API_BASE="https://api.deepseek.com/v1" # API 地址
export DEVAGENT_MODEL="deepseek-chat" # 模型名称支持的模型服务：
| 服务 | API Base | 模型示例 |
|---|---|---|
| DeepSeek | https://api.deepseek.com/v1 |
deepseek-chat, deepseek-reasoner |
| OpenAI | https://api.openai.com/v1 |
gpt-4o, o3-mini |
| Claude (via OpenRouter) | https://openrouter.ai/api/v1 |
anthropic/claude-sonnet-4 |
| 本地 Ollama | http://localhost:11434/v1 |
llama3, qwen2.5 |
| 其他兼容端点 | 自定义 | 自定义 |
也可以创建 .env 文件（已在 .gitignore 中）：
# ~/devagent/.env
DEVAGENT_API_KEY=sk-xxxxx
DEVAGENT_API_BASE=https://api.deepseek.com/v1
DEVAGENT_MODEL=deepseek-chat# 开发模式（推荐，无需每次 build）
pnpm dev
# 或构建后运行
pnpm build
node packages/cli/dist/index.jspnpm dev进入交互界面后直接输入任务：
devagent> 解释这个项目的目录结构
devagent> 帮我修复 src/utils/parser.ts 中的 bug
devagent> 运行测试并修复失败的用例
devagent> 给 UserService 添加分页功能
# 指定模型
pnpm dev -- -m deepseek-reasoner
# 指定 API 地址
pnpm dev -- --api-base https://api.openai.com/v1
# 权限模式
pnpm dev -- --permission-mode auto_low
# 查看帮助
pnpm dev -- --help| 命令 | 说明 |
|---|---|
/exit 或 /quit |
退出 |
/state |
查看当前会话状态（轮次、消息数、上下文使用率） |
DevAgent 对所有副作用操作进行权限控制。
| 模式 | 说明 |
|---|---|
strict（默认） |
所有写操作都需要确认 |
auto_low |
低风险操作自动允许，高风险需确认 |
yolo |
全部自动允许（慎用） |
| 等级 | 工具 | 行为 |
|---|---|---|
| 无风险 | read_file, list_files, search_code, git_status |
始终允许 |
| 低风险 | run_command（只读命令如 ls, git log） |
auto_low 模式自动允许 |
| 高风险 | write_file, edit_file, run_command（一般命令） |
需要用户确认 |
| 极高风险 | run_command（rm -rf, sudo, git push --force） |
始终需要确认，建议拒绝 |
当 Agent 需要执行高风险操作时：
⚠ Permission required [high]
Modifying file: /path/to/file.ts
? Allow this action?
❯ Allow once
Always allow this session
Deny
DevAgent 内置 7 个核心工具：
| 工具 | 说明 |
|---|---|
read_file |
读取文件内容（带行号） |
write_file |
写入/创建文件 |
edit_file |
搜索替换编辑文件 |
list_files |
按 glob 模式列出文件 |
search_code |
用正则搜索代码（ripgrep） |
run_command |
执行 Shell 命令 |
git_status |
查看 Git 状态/diff/log |
在项目根目录创建 AGENTS.md，Agent 会自动加载其中的规则：
# AGENTS.md
## 项目规则
- 使用 pnpm，不使用 npm
- API 返回格式统一为 { code, message, data }
- 修改接口后必须补充测试
## 常用命令
- pnpm dev 启动开发服务器
- pnpm test 运行测试
- pnpm build 构建项目
## 架构说明
- src/api 后端接口
- src/lib 核心逻辑
- src/components UI 组件Agent 会将这些信息注入系统提示词，确保行为符合项目规范。
每次文件修改前，DevAgent 会自动将原文件备份到 .devagent/checkpoints/ 目录。
如果修改出错，可以手动恢复：
# 查看备份
ls .devagent/checkpoints/
# 恢复文件
cp .devagent/checkpoints/1715500000000-a1b2c3d4-parser.ts src/utils/parser.tsdevagent/
├── packages/
│ ├── shared/ # 核心类型定义与工具函数
│ ├── tool-system/ # 工具注册、执行、Schema 转换
│ ├── permission-engine/ # 风险评估、策略引擎、权限接口
│ ├── context-manager/ # Checkpoint、AGENTS.md、上下文压缩
│ ├── model-gateway/ # OpenAI 兼容 API 客户端（流式）
│ ├── agent-runtime/ # 核心 Agent 循环
│ └── cli/ # 终端入口、REPL、渲染器
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.base.json
# 安装依赖
pnpm install
# 构建所有包
pnpm build
# 清理构建产物
pnpm clean
# 开发模式运行 CLI
pnpm devpnpm --filter @devagent/tool-system build
pnpm --filter @devagent/agent-runtime builddevagent> 这个项目是做什么的？核心模块有哪些？
devagent> npm test 有失败的用例，帮我修复
devagent> 给用户列表加上按部门筛选的功能
devagent> 审查最近的 git diff，找出潜在问题
devagent> 为 src/services/auth.ts 生成单元测试
- API Key 安全 — 不要将 key 提交到代码仓库，使用环境变量或
.env文件 - 工作目录 — 在目标项目目录下启动 DevAgent，它会以当前目录为上下文
- 权限控制 — 生产环境建议使用
strict模式，避免误操作 - 上下文窗口 — 长对话会自动压缩，如果响应变慢可以重启会话
- Checkpoint — 文件修改前自动备份，但建议重要修改前先
git commit
MIT