# coding-agent

**Repository Path**: luo-junxue/coding-agent

## Basic Information

- **Project Name**: coding-agent
- **Description**: 基于 FastAPI + WebSocket 的自托管编程智能体。浏览器里对话，它在你指定的工作目录里读写文件、执行命令、跑子任务——所有敏感操作先过你的审批。

## 特性

- **多用户隔离**：config.json 配置令牌即启用鉴权，会话按用户隔离，工作目录可按用户区分
- **15 个内置工具**：文件读写/精确编辑、目录浏览、内容检索、命令执行（前台流式/后台托管）、联网搜索、网页
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-30
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 编程智能体（Coding Agent）

基于 FastAPI + WebSocket 的自托管编程智能体。浏览器里对话，它在你指定的工作目录里读写文件、执行命令、跑子任务——所有敏感操作先过你的审批。

## 特性

- **多用户隔离**：config.json 配置令牌即启用鉴权，会话按用户隔离，工作目录可按用户区分
- **15 个内置工具**：文件读写/精确编辑、目录浏览、内容检索、命令执行（前台流式/后台托管）、联网搜索、网页阅读、代码草稿执行、任务计划等
- **主从多智能体**：`task` 工具派生子智能体跑独立子任务，只把结论带回主对话；深度限 2 层，防止递归失控
- **审批闸门**：危险命令（格式化/递归删除/关机等）黑名单硬拒不弹窗；普通命令弹窗审批，可勾选「本会话免审」；文件写入以 diff 卡片确认
- **上下文自动压缩**：条数或估算 token 双阈值触发，旧对话增量摘要合并，攒批减少模型调用
- **流式输出**：正文/思考分离渲染，Markdown 实时排版，消息可复制，token 用量逐轮统计（含思考 token）
- **技能系统**：提示词文件化到 skills/*.md，对话中只注入索引，模型按需 load_skill 加载全文
- **MCP 扩展**：config.json 里配置外部 MCP Server（stdio），工具自动接入
- **断线恢复**：审批中的任务不随页面刷新丢失，重连后自动重放未决审批；服务重启后提示中断任务

## 快速开始

```bash
# 1. 安装依赖（Python 3.10+）
pip install -r requirements.txt

# 2. 创建本机配置
cp config.example.json config.json
# 编辑 config.json：填入模型 api_key（落盘时自动 DPAPI 加密）

# 3. 启动
python main.py

# 4. 浏览器打开
http://127.0.0.1:8765
```

默认仅本机可用。局域网访问：config.json 里把 `host` 改为 `0.0.0.0`，并配置 `users` 令牌：

```json
{
  "users": [
    {"name": "alice", "token": "自定义口令", "workspace": "D:/work/alice", "role": "admin"}
  ]
}
```

打开 `http://地址:8765/?token=口令` 或在登录框输入口令即可。

## 目录结构

```
main.py    启动入口（日志 / uvicorn）
server/    Web 层：路由 / WebSocket 连接管理 / 鉴权
agent/     智能体核心：编排循环 / 流式解析 / 上下文压缩 / 审批策略 / prompts
tools/     工具实现：文件 / 命令 / 搜索 / 后台任务 / MCP
infra/     基础设施：配置加载 / SQLite 存储 / DPAPI 加密
skills/    技能库（Markdown，按需加载）
web/       前端（原生 HTML/CSS/JS，无构建步骤）
```

## 配置说明

| 字段 | 说明 |
|---|---|
| `api_base_url` / `api_key` / `model` | OpenAI 兼容接口；本地 vLLM / 中转网关均可 |
| `models` | 多套模型方案，界面里一键切换（所有用户共用） |
| `auto_approve_prefixes` | 命令白名单前缀，匹配即跳过审批弹窗 |
| `mcp_servers` | 外部 MCP Server（stdio），`{name, command, args}` |
| `users` | 多用户令牌表；为空则单用户模式 |
| `host` | 监听地址，`0.0.0.0` 供局域网（必须配 users） |

## 安全设计

- API Key 用 Windows DPAPI 加密落盘，config.json 不存明文；WS 令牌走首帧消息，不进 URL 与访问日志
- 危险命令黑名单硬拒（不给批准机会），命令白名单仅对「无 shell 控制符的单一命令」生效
- 文件操作限制在工作目录内，越界路径直接拒绝
- 后台任务按连接分配随机作用域，跨连接无法查询或终止他人任务
- 工作目录之外：不读、不写、不执行

## 已适配模型

DeepSeek（含 R1 思考链）、Qwen（vLLM 部署，流式 usage 需 `stream_options`）、及任意 OpenAI 兼容接口。token 统计自动兼容多种 usage 字段格式。