ab1589921a
## 安全修复 (12项) - Webhook接口添加全局Token认证，过滤敏感请求头 - 修复JWT Base64 padding公式，防止签名验证绕过 - 数据库密码/飞书Token从源码移除，改为环境变量 - 工作流引擎添加路径遍历防护 (_resolve_safe_path) - eval()添加模板长度上限检查 - 审批API添加认证依赖 - 前端v-html增强XSS转义，console.log仅开发模式输出 - 500错误不再暴露内部异常详情 ## Agent运行时修复 (7项) - 删除_inject_knowledge_context中未定义db变量的finally块 - 工具执行添加try/except保护，异常不崩溃Agent - LLM重试计入budget计数器 - self_review异常时passed=False - max_iterations截断标记success=False - 工具参数JSON解析失败时记录警告日志 - run()开始时重置_llm_invocations计数器 ## 配置与基础设施 - DEBUG默认False，SQL_ECHO独立配置项 - init_db()补全13个缺失模型导入 - 新增WEBHOOK_AUTH_TOKEN/SQL_ECHO配置项 - 新增.env.example模板文件 ## 前端修复 (12项) - 登录改用URLSearchParams替代FormData - 401拦截器通过Pinia store统一清理状态 - SSE流超时从60s延长至300s - final/error事件时清除streamTimeout - localStorage聊天记录添加24h TTL - safeParseArgCount替代模板中裸JSON.parse - fetchUser 401时同时清除user对象 ## 新增模块 - 知识进化: knowledge_extractor/retriever/tasks - 数字孪生: shadow_executor/comparison模型 - 行为采集: behavior_middleware/collector/fingerprint_engine - 代码审查: code_review_agent/document_review_agent - 反馈学习: feedback_learner - 瓶颈检测/优化引擎/成本估算/需求估算 - 速率限制器 (rate_limiter) - Alembic迁移 015-020 ## 文档 - 商业化落地计划 - 8篇docs文档 (架构/API/部署/开发/贡献等) - Docker Compose生产配置 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
242 lines
4.8 KiB
Markdown
242 lines
4.8 KiB
Markdown
# 🛠️ 开发指南
|
||
|
||
> **Development Guide**
|
||
|
||
本文档面向加入天工智能体平台开发的工程师，涵盖开发环境搭建、编码规范、测试与调试等内容。
|
||
|
||
---
|
||
|
||
## 一、开发环境搭建
|
||
|
||
### 前置要求
|
||
|
||
| 工具 | 版本 | 下载 |
|
||
|:----|:-----|:-----|
|
||
| Node.js | 18+ | [nodejs.org](https://nodejs.org/) |
|
||
| pnpm | 8+ | `npm install -g pnpm` |
|
||
| Python | 3.11+ | [python.org](https://python.org/) |
|
||
| Docker Desktop | 最新 | [docker.com](https://www.docker.com/products/docker-desktop/) |
|
||
| Git | 2.30+ | [git-scm.com](https://git-scm.com/) |
|
||
| IDE | VSCode / PyCharm | 推荐 VSCode + 对应插件 |
|
||
|
||
### 推荐 VSCode 插件
|
||
|
||
- **Vue 开发**：Vue Language Features (Volar)、TypeScript Vue Plugin
|
||
- **Python 开发**：Python、Pylance
|
||
- **数据库**：MySQL (weijan-chen)
|
||
- **Redis**：Redis
|
||
- **Docker**：Docker
|
||
- **格式化**：Prettier、ESLint
|
||
- **Git**：GitLens、Git History
|
||
|
||
---
|
||
|
||
## 二、代码规范
|
||
|
||
### 前端规范
|
||
|
||
#### 命名规范
|
||
|
||
| 类型 | 规范 | 示例 |
|
||
|:----|:-----|:-----|
|
||
| 组件名 | PascalCase | `UserProfile.vue` |
|
||
| 文件名 | kebab-case | `user-profile.vue` |
|
||
| 变量/函数 | camelCase | `getUserList()` |
|
||
| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
|
||
| Pinia Store | useXxxStore | `useUserStore` |
|
||
| CSS 类名 | kebab-case | `.user-avatar` |
|
||
|
||
#### 组件结构
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
// 1. 导入
|
||
import { ref, computed } from 'vue'
|
||
import { useUserStore } from '@/stores/user'
|
||
|
||
// 2. Props 定义
|
||
const props = defineProps<{
|
||
userId: string
|
||
}>()
|
||
|
||
// 3. Emits 定义
|
||
const emit = defineEmits<{
|
||
'update': [data: any]
|
||
}>()
|
||
|
||
// 4. 响应式状态
|
||
const loading = ref(false)
|
||
|
||
// 5. 计算属性
|
||
const isAdmin = computed(() => userStore.role === 'admin')
|
||
|
||
// 6. 方法
|
||
async function fetchUser() {
|
||
loading.value = true
|
||
try {
|
||
// ...
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
// 7. 生命周期
|
||
onMounted(() => {
|
||
fetchUser()
|
||
})
|
||
</script>
|
||
|
||
<template>
|
||
<div class="user-profile">
|
||
<!-- 模板内容 -->
|
||
</div>
|
||
</template>
|
||
|
||
<style scoped lang="scss">
|
||
.user-profile {
|
||
// 样式
|
||
}
|
||
</style>
|
||
```
|
||
|
||
#### Git Commit 规范
|
||
|
||
遵循 Conventional Commits 规范：
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
```
|
||
|
||
| Type | 含义 |
|
||
|:-----|:------|
|
||
| `feat` | 新功能 |
|
||
| `fix` | 修复 Bug |
|
||
| `docs` | 文档变更 |
|
||
| `style` | 代码格式调整（不影响功能） |
|
||
| `refactor` | 重构代码 |
|
||
| `perf` | 性能优化 |
|
||
| `test` | 添加/修改测试 |
|
||
| `chore` | 构建/工具链变更 |
|
||
|
||
```bash
|
||
# 示例
|
||
feat(agent): 新增智能体知识库关联功能
|
||
fix(user): 修复 Token 刷新失败问题
|
||
docs(readme): 更新快速开始指南
|
||
```
|
||
|
||
---
|
||
|
||
### 后端规范
|
||
|
||
#### 项目约定
|
||
|
||
| 项目 | 约定 |
|
||
|:-----|:------|
|
||
| 代码风格 | 遵循 PEP 8 |
|
||
| 类型注解 | 所有函数必须包含类型注解 |
|
||
| 注释 | 关键逻辑需写中文注释 |
|
||
| 路由命名 | `/{module}/{action}`，如 `/agents/{id}/start` |
|
||
| 响应格式 | 统一使用 `{ code, message, data }` 格式 |
|
||
|
||
#### 响应格式
|
||
|
||
```python
|
||
# 成功响应
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": { ... }
|
||
}
|
||
|
||
# 错误响应
|
||
{
|
||
"code": 40001,
|
||
"message": "用户不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、测试指南
|
||
|
||
### 前端测试
|
||
|
||
```bash
|
||
cd frontend
|
||
|
||
# 运行单元测试
|
||
pnpm test
|
||
|
||
# 运行测试并生成覆盖率报告
|
||
pnpm test:coverage
|
||
```
|
||
|
||
### 后端测试
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 运行所有测试
|
||
pytest
|
||
|
||
# 运行特定模块测试
|
||
pytest tests/test_agent.py -v
|
||
|
||
# 运行测试并生成覆盖率
|
||
pytest --cov=app tests/
|
||
```
|
||
|
||
---
|
||
|
||
## 四、调试技巧
|
||
|
||
### 前端
|
||
|
||
- **Vue Devtools**：浏览器安装 Vue Devtools 插件，可查看组件树、状态、事件
|
||
- **Axios 拦截器**：在 `utils/request.ts` 中可打印请求/响应的完整信息
|
||
|
||
### 后端
|
||
|
||
- **FastAPI 自动文档**：访问 `http://localhost:8037/docs` 交互式调试 API
|
||
- **Pdb 调试**：在代码中插入 `import pdb; pdb.set_trace()` 启动断点调试
|
||
- **日志查看**：后端日志输出到控制台，关键位置使用 `logger.info()` 打点
|
||
|
||
---
|
||
|
||
## 五、数据库变更流程
|
||
|
||
```bash
|
||
# 1. 修改 model 文件（如 app/models/user.py）
|
||
|
||
# 2. 生成迁移脚本
|
||
cd backend
|
||
alembic revision --autogenerate -m "add_user_avatar_field"
|
||
|
||
# 3. 审查并执行迁移
|
||
alembic upgrade head
|
||
|
||
# 4. （如需回滚）
|
||
alembic downgrade -1
|
||
```
|
||
|
||
> ⚠️ **注意**：生产环境的数据库迁移需先在预发布环境验证。
|
||
|
||
---
|
||
|
||
## 六、常见开发问题
|
||
|
||
| 问题 | 解决方案 |
|
||
|:-----|:---------|
|
||
| `pnpm install` 报错 | 检查 Node.js 版本，删除 `node_modules` 重新安装 |
|
||
| 后端热重载不生效 | 检查 `uvicorn` 是否带 `--reload` 参数 |
|
||
| Alembic 检测不到模型变更 | 确认模型已导入 `app/models/__init__.py` |
|
||
| CORS 错误 | 检查后端 CORS 配置中 `origins` 是否包含前端地址 |
|
||
|
||
---
|
||
|
||
> 📎 **相关文档**：[快速开始指南](./quickstart.md) | [项目结构概览](./project-structure.md)
|