TBC/docs/CONFIG.md
D-Robotics 637b1026df release: v1.2.0 - 安全加固与性能优化
Security:
- 添加 API 认证中间件 (PLATFORM_API_TOKEN Bearer Token)
- SSRF 防护: 校验 git URL scheme + 过滤内网 IP
- 路径遍历修复: module 参数添加 is_relative_to 校验
- 异常信息泄露修复: 统一错误处理不返回内部信息
- API Key 不持久化到数据库
- 硬编码 SSH Key 移至环境变量
- CORS 生产环境校验

Rate Limiting:
- 新增内存滑动窗口速率限制 (6个POST端点)

Performance:
- ThreadPoolExecutor(max_workers=4) 限制并发
- 任务超时 _enforce_proc_timeout (默认3600s)
- JSON 原子写入 tempfile+os.replace
- 日志轮转 RotatingFileHandler
- httpx 连接池配置
- 随机名改用 uuid4
- 前端 Error Boundary
- 前端统一 EventSource 使用

Docs:
- 更新 .env.example, CHANGELOG, API.md, CONFIG.md, AGENTS.md
- .gitignore 添加 .venv/ 和 backend/db.json
2026-07-16 15:00:05 +08:00

247 lines
6.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# TestAgent 配置文档
## 一、config.yaml
```yaml
agent:
name: "TestAgent"
model: "glm-5.2" # LLM 模型名称
provider: "openai" # OpenAI 兼容
base_url: "https://ai-api.d-robotics.cc/v1"
temperature: 0.3
max_tokens: 16384
git:
default_branch: "main"
clone_depth: 50 # git clone 深度
max_file_size_kb: 500
analysis:
supported_languages: # 支持的语言
- python
- typescript
- javascript
- go
- java
ignore_patterns: # 忽略的文件/目录
- "**/node_modules/**"
- "**/__pycache__/**"
- "**/.git/**"
- "**/dist/**"
- "**/build/**"
- "**/vendor/**"
- "**/*.min.js"
- "**/*.bundle.js"
test_generation:
output_dir: "tests" # 测试输出目录
domain_layer_dir: "tests/domain"
infrastructure_layer_dir: "tests/infrastructure"
session_domain_dir: "tests/session"
smoke_marker: "smoke"
integration_marker: "integration"
regression_marker: "regression"
e2e_marker: "e2e"
metrics_gate: # 指标门禁
min_coverage: 60 # 覆盖率 ≥ 60%
min_pass_rate: 95 # 通过率 ≥ 95%
backend:
host: "0.0.0.0"
port: 5002
existing_tests_root: "./tests"
plugins:
enabled:
- pylint_analyzer # 代码静态分析
- test_runner # 测试运行 + 门禁
logging:
level: "info"
format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
```
---
## 二、.env 环境变量
```bash
# LLM API 配置(固定,页面无需输入)
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://ai-api.d-robotics.cc/v1
# 测试平台登录凭证
TEST_USERNAME=admin&tsting # 地瓜机器人平台账号
TEST_PASSWORD=12345678 # 对应密码
```
**可选环境变量:**
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DEEPSEEK_API_KEY` | DeepSeek API Key(兼容模式) | - |
| `ANTHROPIC_API_KEY` | Anthropic API Key | - |
| `HEADLESS` | 浏览器无头模式 | `false` |
| `PLATFORM_API_TOKEN` | API 认证 Token(留空则关闭认证) | - |
| `FLASK_ENV` | Flask 运行环境(development/production) | `development` |
| `CORS_ORIGINS` | CORS 允许来源(逗号分隔) | `http://localhost:5174,...` |
| `TASK_TIMEOUT_SECONDS` | 单任务最大运行时间(秒) | `3600` |
| `SSH_PUBLIC_KEY` | SSH 公钥(原硬编码迁移) | - |
| `DM_SSH_KEY` | 开发机 SSH Key(原硬编码迁移) | - |
---
## 三、Skills 知识库配置
知识库位于 `skills/` 目录,每个 Skill 是一个子目录,包含 `SKILL.md` 文件。
### 3.1 TDD 方法论 (`skills/tdd-methodology/SKILL.md`)
- 红-绿-重构循环
- FIRST 原则(Fast/Independent/Repeatable/Self-Validating/Timely)
- AAA 模式(Arrange-Act-Assert)
- 测试命名规范
- 测试替身(Stub/Mock/Fake/Spy/Dummy)
### 3.2 DDD 模式 (`skills/ddd-patterns/SKILL.md`)
- 限界上下文划分
- 聚合根/实体/值对象/领域服务/仓储
- 测试目录结构规范
- 领域层 vs 基础设施层隔离
- Session 领域测试
### 3.3 测试框架规范 (`skills/test-framework/SKILL.md`)
- 测试分层(冒烟/集成/系统/回归/指标)
- 测试标记规范
- 指标门禁断言
- CI/CD 流水线链
- 敏捷迭代规范
### 3.4 多语言模式 (`skills/language-patterns/SKILL.md`)
- Python (pytest + Mock)
- TypeScript (Jest)
- Go (testing)
- 测试数据管理
---
## 四、插件配置
### 4.1 pylint_analyzer
- 触发时机:`pre_analysis`
- 功能:行长度检测、TODO/FIXME 标记、print 语句检测、复杂度评估
### 4.2 test_runner
- 触发时机:`post_generation`
- 功能:运行生成的测试、解析结果、指标门禁检查
---
## 五、前端配置
### 5.1 vite.config.ts
```typescript
export default defineConfig({
plugins: [react(), tailwindcss()],
server: {
host: '0.0.0.0',
port: 5174,
proxy: {
'/api': 'http://127.0.0.1:5002',
'/artifacts': 'http://127.0.0.1:5002',
},
},
})
```
### 5.2 主题配置
- 暗色/亮色模式切换
- CSS 自定义属性 14 个主题变量
- 存储在 `localStorage`,默认跟随系统偏好
---
## 六、数据清理策略
- 任务超过 100 个时自动清除最旧 50 个
- 清理时同步删除关联的截图和报告文件
- `platform_db.json` 每次写入时自动清理
---
## 七、安全加固配置(已实施)
### 7.1 API 认证
设置 `PLATFORM_API_TOKEN` 环境变量后,所有 API 请求(`/api/health` 豁免)需携带 `Authorization: Bearer <token>` 请求头:
```bash
export PLATFORM_API_TOKEN="your-secret-token"
```
前端请求示例:
```javascript
fetch('/api/repos', {
headers: { 'Authorization': 'Bearer your-secret-token' }
})
```
未设置时认证关闭(仅开发模式推荐)。
### 7.2 CORS 配置
通过 `CORS_ORIGINS` 环境变量配置允许的来源(逗号分隔)。生产环境(`FLASK_ENV=production`)启动时若未设置则输出警告:
```bash
export CORS_ORIGINS="https://your-domain.com"
export FLASK_ENV=production
```
### 7.3 SSRF 防护
所有接受 Git URL 的端点执行 URL 校验:
- 仅允许 HTTPS 协议(拒绝 `git://`、`ssh://`、`git@`)
- 拒绝内网 IP(10.x / 172.16-31.x / 192.168.x / 169.254.x / 127.x / ::1 / fc00:: / fe80::)
### 7.4 路径安全
所有文件路径参数(`test_file`、`module`)通过 `Path.resolve()` + `is_relative_to()` 校验,防止目录穿越攻击。
### 7.5 速率限制
关键 POST 端点按客户端 IP 实施滑动窗口速率限制(5-10 次/60 秒),超过返回 `429`。
### 7.6 API Key 保护
API Key 仅在内存中传递,不持久化到 `platform_db.json`。任务创建后 API Key 字段从数据库记录中移除。
### 7.7 异常信息保护
`@errorhandler(500)` 返回通用错误消息,内部异常详情仅写入日志,不返回客户端。
### 7.8 数据库原子写入
`platform_db.json` 使用 `tempfile.mkstemp` + `os.replace` 原子写入,防止进程崩溃时数据库损坏。
---
## 八、性能优化(已实施)
### 8.1 线程池
- `ThreadPoolExecutor(max_workers=4)` 限制并发任务执行,防止无限创建线程
### 8.2 任务超时
- `_enforce_proc_timeout()` 后台 Timer,超时自动 kill 进程组(默认 3600 秒)
### 8.3 日志轮转
- `RotatingFileHandler(maxBytes=10MB, backupCount=5)` 防止日志文件无限增长
### 8.4 httpx 连接池
- `LLMClient` 配置 `Limits(max_connections=10, max_keepalive_connections=5)`
### 8.5 随机名生成
- 资源名使用 `uuid.uuid4().hex[:8]` 替代 `random.randint()`,消除碰撞风险
### 8.6 前端优化
- SSE 日志限制保留 200 条
- `useTaskLogs` hook 统一管理 EventSource 生命周期,组件卸载自动清理
- 全局 `ErrorBoundary` 捕获渲染异常,防止白屏