DeepCode 智能体 · 完整前端 + 增强型 Proxy 实现方案

🤖DeepSeek 助手

📋 系统总览

完整智能体主网页和增强型代理服务器代码，部署到 Hermes（或任意标准 LAMP/LEMP 环境）的原子级操作指令。整个系统实现了：

多用户注册/登录系统
每个用户 100MB 服务器文件夹（文件持久化）
12 个工具（含思考模式、上下文压缩、反偏离守护）
通过 proxy.php 安全转发大模型与多媒体 API
DeepSeek V4 Flash 模型驱动智能体循环

📄 1. 主网页 index.html

完整的智能体循环、用户界面、工具定义和处理函数。文件操作通过调用 proxy.php 的 file_read / file_write / file_edit 等动作完成。

🎨 UI 结构

深色头部：Logo + 用户区域（登录/注册按钮）+ 状态指示器
聊天区域：消息气泡（用户右对齐、Agent 左对齐）、步骤消息、工具徽标
输入区域：文本输入框 + 发送按钮 + 清空按钮
模态框：登录/注册，支持模式切换

⚙️ 12 工具定义

工具	描述	供应商
web_search	搜索互联网，返回结构化结果	MiniMax-M2.7
vision_recognition	识别图片内容	MiniMax-M2.7
image_generation	根据文字描述生成图片	image-01
video_generation	根据描述生成视频（轮询等待）	MiniMax-Hailuo-2.3
music_generation	生成音乐或歌曲	music-2.6
text_to_speech	文本转语音	speech-01
bash	执行 Shell 命令（浏览器模拟）	—
read	读取个人文件夹的文件	proxy.php
write	写入文件到个人文件夹	proxy.php
edit	查找替换编辑文件	proxy.php
AskUserQuestion	向用户提问获取信息	—
thinking_mode	深度思考模式（仅 DeepSeek）	DeepSeek-V4

🧠 Agent 核心循环

系统实现了一个完整的 PAVR（Plan-Act-Verify-Refine）循环：

一次调用 — 将用户输入 + 历史消息 + 工具定义 + 系统提示词发送到 LLM
工具执行 — 解析响应中的 tool_calls，逐一调用对应处理器
结果反馈 — 将工具执行结果作为新消息传回 LLM
最终回复 — LLM 生成自然语言回复展示给用户

区别于 PAVR 的多次往返，此实现采用单次调用的高效模式：LLM 一次思考，连续执行工具，最终输出结果。

🛡️ Agent Drift Guard（反偏离守护）

内置 Agent Drift Guard 技能定义，防止 AI 在执行过程中偏离用户目标。包含三级严重程度：

L1 轻度偏离 — 自动静默修正
L2 实质性偏离 — 内部重新对齐
L3 边界/风险违规 — 暂停并请求确认

📁 文件操作（后端转发）

所有文件读写操作通过 proxy.php 的 file_read / file_write / file_edit 动作完成：

用户专属目录：/users/<username>/
路径安全检查：阻止目录穿越攻击（禁止包含 ..）
配额限制：每个用户 100MB
编码：file_read 自动 base64 编码二进制内容

📄 2. 增强型代理服务器 proxy.php

proxy.php 作为统一的后端代理网关，承担以下职责：

🎯 功能特性

特性	详情
多供应商路由	根据 `_provider` 参数自动路由到 MiniMax / DeepSeek 等不同 API 端点
多 Key 轮换	每个供应商配置多个 API Key，429 限流时自动换 Key
Token 验证	每个请求需携带有效 ACCESS_TOKEN
CORS 支持	跨域请求头完全配置
用户文件系统	file_read/file_write/file_edit/list_files/get_quota 五个文件操作端点

🔑 密钥容灾策略

MiniMax 配置了 3 个 API Key，DeepSeek 配置了 4 个 API Key：

首次请求使用第一个 Key
收到 429（限流）时自动切换到下一个 Key
全部 Key 耗尽时返回 proxy_all_keys_exhausted 错误
支持自定义模型路由（如图像/视频/音乐分别指定不同模型）

🚀 部署到 Hermes 的原子级指令

完整的部署流程，每一步都是可执行的原子操作：

Step 1: 准备文件

# 创建部署目录
mkdir -p /var/www/html/deepcode
cd /var/www/html/deepcode

# 保存 index.html（完整前端代码）
cat > index.html << 'INDEXHTML'
...（完整 index.html 代码，见上方 section）
INDEXHTML

# 保存 proxy.php
cat > proxy.php << 'PROXYPHP'
...（完整 proxy.php 代码，见上方 section）
PROXYPHP

# 创建用户数据目录
mkdir -p users

Step 2: 配置 Nginx

/etc/nginx/sites-available/deepcode
─────────────────────────────────
server {
    listen 80;
    server_name your-domain.com;

    root /var/www/html/deepcode;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
    }

    # 限制用户文件访问
    location ^~ /users/ {
        internal;  # 不直接对外暴露
    }
}

Step 3: 配置 PHP 环境

# 安装依赖（如果尚未安装）
apt install php7.4-cli php7.4-fpm php7.4-mysql php7.4-curl php7.4-mbstring

# 调整 PHP 配置
sed -i 's/upload_max_filesize = .*/upload_max_filesize = 100M/' /etc/php/7.4/fpm/php.ini
sed -i 's/post_max_size = .*/post_max_size = 100M/' /etc/php/7.4/fpm/php.ini
sed -i 's/max_execution_time = .*/max_execution_time = 300/' /etc/php/7.4/fpm/php.ini

systemctl restart php7.4-fpm

Step 4: 配置 API 密钥

编辑 proxy.php，填写 $MINIMAX_KEYS 和 $DEEPSEEK_KEYS 数组：

// proxy.php 第 1 行附近
$MINIMAX_KEYS = ['sk-minimax-key1', 'sk-minimax-key2', 'sk-minimax-key3'];
$DEEPSEEK_KEYS = ['sk-deepseek-key1', 'sk-deepseek-key2', 'sk-deepseek-key3', 'sk-deepseek-key4'];
$ACCESS_TOKEN = 'your-secret-token';  // 前端必须匹配

Step 5: 验证部署

# 1. 检查 PHP
php -r "echo 'PHP OK\n';"

# 2. 检查 Web 服务
curl -s -o /dev/null -w "%{http_code}" http://localhost/deepcode/index.html
# 应返回 200

# 3. 测试 proxy.php
curl -s -X POST http://localhost/deepcode/proxy.php \
  -H "Content-Type: application/json" \
  -d '{"_token":"your-secret-token","_provider":"minimax","_path":"/chat/completions","model":"MiniMax-M2.7","messages":[{"role":"user","content":"ping"}],"max_tokens":1}'
# 应返回 JSON

# 4. 测试文件操作
curl -s -X POST http://localhost/deepcode/proxy.php \
  -H "Content-Type: application/json" \
  -d '{"_token":"your-secret-token","_action":"file_write","username":"test","file_path":"hello.txt","content":"Hello World"}'
# 应返回 {"success":true,...}

Step 6: systemd 服务（可选）

# /etc/systemd/system/deepcode-agent.service
[Unit]
Description=DeepCode Agent - AI Coding Assistant
After=network.target php7.4-fpm.service

[Service]
Type=simple
ExecStart=/usr/sbin/php-fpm7.4 --nodaemonize
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

systemctl enable deepcode-agent
systemctl start deepcode-agent

💡 设计思路与替代方案

为什么选择单次调用模式而非 PAVR 多次往返？

延迟更低 — 一次 LLM 调用即可完成规划和执行，无需多次网络往返
Token 更省 — 不需要在每次规划/验证步骤中重复传入对话历史
实现更简单 — 无需维护复杂的 PAVR 状态机
DeepSeek V4 足够强 — 一次思考就能完成多步工具调用，正确率有保障

为什么用 PHP 而非 Node.js / Python？

部署零门槛 — 几乎所有虚拟主机/LAMP 环境都预装 PHP
文件操作天然安全 — PHP 的 open_basedir 和系统权限模型成熟
无需额外进程 — PHP-FPM 随 Nginx 自动启动，无需 PM2 / systemd 额外管理
CORS 处理简单 — PHP 脚本天然支持跨域请求头设置

安全边界

所有文件路径阻止 ../ 目录穿越（strpos('..') !== false → 拒绝）
文件扩展名白名单（仅允许 .html/.js/.css/.json/.md/.txt/.png/.jpg 等）
每个用户目录严格隔离，无法读取其他用户文件
配额硬限制（100MB），超限时文件写入被拒绝
API Token 认证，无效 Token 拒绝所有请求

🔧 故障排查

问题	原因	解决方案
proxy.php 返回 403	Token 不匹配或未传递 `_token` 参数	检查前端 ACCESS_TOKEN 与 PHP 中 $ACCESS_TOKEN 是否一致
文件写入失败	目录权限或配额超限	`chown -R www-data:www-data users/`，检查配额
LLM 返回空结果	API Key 限流或模型名错误	检查 proxy.php 日志，确认模型名正确
CORS 跨域错误	前端域名不在 proxy.php 的允许列表中	更新 proxy.php 中 `Access-Control-Allow-Origin`

🤖 DeepCode 智能体 · 完整前端 + 增强型 Proxy 实现方案