admin/aiagent
1
0
Fork 0
Code Issues 23 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add 10 new tools + agent self-evolution system (31 tools total)

Browse Source 
New tools (10):
- code_execute: Python/JS sandbox execution
- git_operation: Git read-only operations (log/diff/blame/status)
- web_search: DuckDuckGo web search
- pdf_generate: Markdown to PDF/HTML report generation
- project_scaffold: Project template generator (fastapi/vue/react)
- task_plan: Task decomposition and progress tracking
- excel_process: Excel read/write with chart support
- browser_use: Headless browser control (playwright)
- docker_manage: Docker container management (read-only)
- deploy_push: File deployment (copy/rsync)

Self-evolution tools:
- agent_create: Dynamically create specialized sub-agents at runtime
- tool_register: Dynamically register HTTP tools at runtime

Documentation:
- Add 使用文档.md with full tool reference and project examples
- Update 创建agent.md (19→31 tools, add self-evolution chapter)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
renjianbo
2026-05-03 22:29:28 +08:00
parent de415ca310
commit 244ed31274
5 changed files with 1912 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
backend/app/core/tools_bootstrap.py
View File

@@ -8,11 +8,11 @@ logger = logging.getLogger(__name__)
_registered = False
_EXPECTED_BUILTIN = 19
_EXPECTED_BUILTIN = 31
def ensure_builtin_tools_registered() -> None:
"""幂等：注册 file_write / system_info 等内置工具，供工作流 LLM 节点使用。"""
"""幂等：注册所有内置工具，供工作流 LLM 节点使用。"""
global _registered
if _registered:
return
@@ -37,6 +37,18 @@ def ensure_builtin_tools_registered() -> None:
url_parse_tool,
regex_test_tool,
agent_call_tool,
code_execute_tool,
git_operation_tool,
web_search_tool,
pdf_generate_tool,
project_scaffold_tool,
task_plan_tool,
excel_process_tool,
browser_use_tool,
docker_manage_tool,
deploy_push_tool,
agent_create_tool,
tool_register_tool,
HTTP_REQUEST_SCHEMA,
FILE_READ_SCHEMA,
FILE_WRITE_SCHEMA,
@@ -56,6 +68,18 @@ def ensure_builtin_tools_registered() -> None:
URL_PARSE_SCHEMA,
REGEX_TEST_SCHEMA,
AGENT_CALL_SCHEMA,
CODE_EXECUTE_SCHEMA,
GIT_OPERATION_SCHEMA,
WEB_SEARCH_SCHEMA,
PDF_GENERATE_SCHEMA,
PROJECT_SCAFFOLD_SCHEMA,
TASK_PLAN_SCHEMA,
EXCEL_PROCESS_SCHEMA,
BROWSER_USE_SCHEMA,
DOCKER_MANAGE_SCHEMA,
DEPLOY_PUSH_SCHEMA,
AGENT_CREATE_SCHEMA,
TOOL_REGISTER_SCHEMA,
)
tool_registry.register_builtin_tool("http_request", http_request_tool, HTTP_REQUEST_SCHEMA)
@@ -77,6 +101,18 @@ def ensure_builtin_tools_registered() -> None:
tool_registry.register_builtin_tool("url_parse", url_parse_tool, URL_PARSE_SCHEMA)
tool_registry.register_builtin_tool("regex_test", regex_test_tool, REGEX_TEST_SCHEMA)
tool_registry.register_builtin_tool("agent_call", agent_call_tool, AGENT_CALL_SCHEMA)
tool_registry.register_builtin_tool("code_execute", code_execute_tool, CODE_EXECUTE_SCHEMA)
tool_registry.register_builtin_tool("git_operation", git_operation_tool, GIT_OPERATION_SCHEMA)
tool_registry.register_builtin_tool("web_search", web_search_tool, WEB_SEARCH_SCHEMA)
tool_registry.register_builtin_tool("pdf_generate", pdf_generate_tool, PDF_GENERATE_SCHEMA)
tool_registry.register_builtin_tool("project_scaffold", project_scaffold_tool, PROJECT_SCAFFOLD_SCHEMA)
tool_registry.register_builtin_tool("task_plan", task_plan_tool, TASK_PLAN_SCHEMA)
tool_registry.register_builtin_tool("excel_process", excel_process_tool, EXCEL_PROCESS_SCHEMA)
tool_registry.register_builtin_tool("browser_use", browser_use_tool, BROWSER_USE_SCHEMA)
tool_registry.register_builtin_tool("docker_manage", docker_manage_tool, DOCKER_MANAGE_SCHEMA)
tool_registry.register_builtin_tool("deploy_push", deploy_push_tool, DEPLOY_PUSH_SCHEMA)
tool_registry.register_builtin_tool("agent_create", agent_create_tool, AGENT_CREATE_SCHEMA)
tool_registry.register_builtin_tool("tool_register", tool_register_tool, TOOL_REGISTER_SCHEMA)
_registered = True
n = tool_registry.builtin_tool_count()

1324
backend/app/services/builtin_tools.py
View File

File diff suppressed because it is too large Load Diff

12
frontend/src/utils/agentSkills.ts
View File

@@ -16,6 +16,18 @@ export const BUILTIN_SKILL_OPTIONS: { name: string; label: string }[] = [
{ name: 'database_query', label: '数据库查询' },
{ name: 'adb_log', label: 'ADB 日志' },
{ name: 'agent_call', label: '调用 Agent' },
{ name: 'code_execute', label: '代码执行' },
{ name: 'git_operation', label: 'Git 操作' },
{ name: 'web_search', label: '网页搜索' },
{ name: 'pdf_generate', label: 'PDF 生成' },
{ name: 'project_scaffold', label: '项目脚手架' },
{ name: 'task_plan', label: '任务规划' },
{ name: 'excel_process', label: 'Excel 处理' },
{ name: 'browser_use', label: '浏览器操控' },
{ name: 'docker_manage', label: 'Docker 管理' },
{ name: 'deploy_push', label: '部署推送' },
{ name: 'agent_create', label: '创建 Agent' },
{ name: 'tool_register', label: '注册工具' },
]
export const BUILTIN_SKILL_LABELS: Record<string, string> = Object.fromEntries(

484
使用文档.md Normal file
View File

@@ -0,0 +1,484 @@
# Agent 工具使用文档
## 概述
所有 Agent 默认拥有 **31 个内置工具**（`tools: []` = 全部可用）。工具涵盖文件操作、网络访问、代码执行、项目管理、部署等能力，Agent 可在 ReAct 循环中自主选择和调用。
---
## 工具清单（31个）
### 文件与数据
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 1 | `file_read` | `file_path` | 读取文本/PDF/docx/xlsx/图片OCR |
| 2 | `file_write` | `file_path`, `content`, `mode` | 写入文本文件（覆盖/追加） |
| 3 | `json_process` | `json_data`, `operation`, `key` | JSON 结构化数据处理 |
| 4 | `excel_process` | `file_path`, `action`, `sheet_name`, `data_json`, `chart_config_json` | Excel 读写 + 图表生成 |
### 网络
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 5 | `http_request` | `url`, `method`, `headers`, `body` | HTTP 请求（GET/POST/PUT/DELETE） |
| 6 | `url_parse` | `url` | URL 解析 |
| 7 | `web_search` | `query`, `max_results` | DuckDuckGo 网页搜索 |
### 代码与文本
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 8 | `code_execute` | `code`, `language`, `timeout` | Python/JS 沙箱执行 |
| 9 | `text_analyze` | `text`, `operation` | 文本分析 |
| 10 | `regex_test` | `pattern`, `text` | 正则表达式测试 |
### 项目管理
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 11 | `git_operation` | `operation`, `file_path`, `revision` | Git 只读操作（log/diff/blame/status） |
| 12 | `project_scaffold` | `template`, `project_name`, `target_dir` | 项目模板生成（fastapi/vue/react等） |
| 13 | `task_plan` | `action`, `plan_id`, `title`, `steps_json`, `step_index`, `status` | 任务分解与进度跟踪 |
| 14 | `deploy_push` | `source_path`, `target`, `method`, `exclude` | 文件部署（本地复制/rsync） |
### 文档与报告
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 15 | `pdf_generate` | `markdown`, `output_path`, `title` | Markdown→PDF/HTML 报告生成 |
### 计算与系统
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 16 | `math_calculate` | `expression` | 数学计算 |
| 17 | `system_info` | | 系统环境信息 |
| 18 | `datetime` | `operation`, `datetime_str`, `timezone` | 日期时间计算 |
| 19 | `crypto_util` | `operation`, `text`, `key` | 加密/解密/哈希 |
| 20 | `random_generate` | `type`, `count`, `min`, `max` | 随机数据生成 |
### 自动化
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 21 | `schedule_create` | `agent_id`, `name`, `cron_expression`, `input_message` | 创建定时任务 |
| 22 | `schedule_list` | `agent_id` | 查看定时任务 |
| 23 | `schedule_delete` | `schedule_id` | 删除定时任务 |
### 通信与协作
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 24 | `send_email` | `to`, `subject`, `body` | 发送邮件 |
| 25 | `agent_call` | `agent_name`, `query`, `max_iterations` | 调用其他 Agent 委派任务 |
| 26 | `agent_create` | `name`, `system_prompt`, `description` | 动态创建专业子 Agent |
| 27 | `tool_register` | `name`, `description`, `method`, `url` | 动态注册 HTTP 工具 |
### DevOps
| # | 工具 | 参数 | 说明 |
|---|------|------|------|
| 26 | `database_query` | `query`, `params` | 数据库查询 |
| 27 | `docker_manage` | `operation`, `resource`, `options` | Docker 容器管理（只读） |
| 28 | `browser_use` | `url`, `action`, `selector`, `script` | 无头浏览器操控（截图/提取/填表） |
| 31 | `adb_log` | `device`, `lines`, `tag` | Android ADB 日志 |
---
## 核心工具详解
### 1. code_execute — 代码执行
```
code_execute(code="print(sum(range(1,101)))", language="python")
→ {"stdout": "5050\n", "stderr": "", "returncode": 0}
```
**场景：**
- 写脚本验证逻辑 → 看输出 → 修正 → 完成闭环
- 数据处理：pandas 读取 → 清洗 → 统计
- 批量文件重命名、格式转换
**安全限制：** 超时 30s，Python/JS 沙箱，任意代码可执行
---
### 2. git_operation — Git 操作
```
git_operation(operation="log", file_path="src/main.py")
→ 最近 50 条该文件的提交历史
git_operation(operation="diff", file_path="src/utils.py")
→ 当前未暂存的差异
git_operation(operation="blame", file_path="src/app.py")
→ 每行代码的作者和提交时间
```
**支持的 operation：** `log`, `diff`, `diff_staged`, `status`, `branch`, `blame`, `show`, `tag`, `remote`, `rev_parse`
**场景：**
- 理解项目演进历史
- 定位 bug 引入的提交
- 审查代码变更范围
---
### 3. web_search — 网页搜索
```
web_search(query="FastAPI middleware CORS setup 2025", max_results=5)
→ {"results": [
{"index": 1, "title": "...", "url": "https://...", "snippet": "..."},
...
], "count": 5}
```
**场景：**
- 查最新技术文档、API 用法
- 搜索错误信息找到解决方案
- 了解行业最佳实践
---
### 4. task_plan — 任务规划
```
# 创建计划
task_plan(
action="create",
title="开发用户认证系统",
steps_json='["设计数据库模型","实现注册API","实现登录API","添加JWT中间件","编写测试","部署配置"]'
)
→ {"plan": {"id": "plan_20260503_120000", "steps": [...], ...}}
# 标记步骤完成
task_plan(
action="update_step",
plan_id="plan_20260503_120000",
step_index=0,
status="done"
)
# 查看进度
task_plan(action="view", plan_id="plan_20260503_120000")
→ 完整计划及每个步骤的状态
# 列出所有计划
task_plan(action="list")
→ 所有活跃计划的摘要
```
**步骤状态：** `pending` → `in_progress` → `done` / `blocked`
**场景：**
- 复杂多步骤任务："帮我搭建一个完整的博客系统"
- Agent 自主拆解 → 逐步执行 → 汇报每步结果
- 长期项目跟踪
---
### 5. project_scaffold — 项目脚手架
```
project_scaffold(template="fastapi", project_name="my-api")
→ 在工作区创建标准 FastAPI 项目目录结构
project_scaffold(template="vue", project_name="my-dashboard")
→ Vue 3 + Vite 前端项目
```
**支持的模板：**
| 模板 | 说明 |
|------|------|
| `fastapi` | FastAPI 后端 + Dockerfile |
| `vue` | Vue 3 + Vite 前端 |
| `react` | React 18 + Vite |
| `python_cli` | Python CLI 工具 |
| `shell` | Shell 脚本项目 |
---
### 6. pdf_generate — 报告生成
```
pdf_generate(
markdown="# 项目周报\n\n## 进展\n- 完成用户模块\n- 修复3个bug\n\n## 下周计划\n- 集成支付",
title="项目周报 2026-05-03"
)
→ {"file": "/path/to/report_20260503_120000.pdf", "format": "pdf"}
```
**依赖：** `pip install weasyprint` 生成 PDF；否则降级为 HTML
---
### 7. excel_process — 高级 Excel
```
# 读取
excel_process(file_path="data.xlsx", action="read")
→ 返回所有工作表的数据
# 写入
excel_process(
file_path="output.xlsx",
action="write",
data_json='{"Sheet1": [["姓名","分数"],["张三",95],["李四",87]]}'
)
# 添加图表
excel_process(
file_path="output.xlsx",
action="chart",
chart_config_json='{"type":"bar","title":"成绩分布","data_min_col":2,"data_min_row":1,"data_max_col":2,"data_max_row":3}'
)
```
**支持的图表：** `bar`（柱状图）、`line`（折线图）、`pie`（饼图）
---
### 8. browser_use — 浏览器操控
```
# 截图
browser_use(url="https://example.com", action="screenshot")
→ {"screenshot": "/tmp/screenshot_20260503_120000.png"}
# 提取文本
browser_use(url="https://docs.example.com", action="content")
→ {"text": "...页面全部可读文本...", "text_length": 5432}
# 执行 JS
browser_use(url="https://example.com", action="evaluate", script="document.title")
→ {"evaluate_result": "Example Domain"}
```
**依赖：** `pip install playwright && playwright install chromium`
---
### 9. docker_manage — Docker 管理
```
docker_manage(operation="ps")
→ 正在运行的容器列表
docker_manage(operation="logs", resource="my-container")
→ 容器日志
docker_manage(operation="compose", resource="ps")
→ docker compose 服务状态
```
**只读操作：** `ps`, `images`, `logs`, `stats`, `inspect`, `version`, `info`, `compose ps/logs/config/top`
---
### 10. deploy_push — 部署推送
```
# 本地复制（自动排除 .git/node_modules 等）
deploy_push(source_path="/app/dist", target="/var/www/html", method="copy")
# rsync 到远程服务器
deploy_push(
source_path="/app/dist",
target="user@server.com:/var/www/html",
method="rsync",
exclude=".git,node_modules,.venv"
)
```
---
### 11. agent_call — Agent 间协作
```
agent_call(agent_name="家庭医生助手", query="用户头痛3天，伴随失眠，该注意什么？")
→ {
"agent": "家庭医生助手",
"status": "success",
"iterations": 3,
"tool_calls": 1,
"reply": "根据您描述的症状..."
}
```
详见下一节。
---
### 12. agent_create — 动态创建子 Agent
```
agent_create(
name="SQL优化专家",
system_prompt="你是MySQL性能优化专家，擅长分析慢查询日志...",
description="专门分析MySQL慢查询并提供优化方案"
)
→ {"status": "created", "agent": {"id": "uuid", "name": "SQL优化专家", ...}}
```
**场景：**
- Agent 发现任务需要专业知识但当前没有对应子 Agent → 创建一个 → 委派
- 新 Agent 写入 DB，拥有全部 31 工具 + RAG 记忆，持久化复用
- 创建后立即通过 `agent_call` 调用来完成任务
---
### 13. tool_register — 动态注册工具
```
tool_register(
name="currency_exchange",
description="查询实时汇率",
method="GET",
url="https://api.exchangerate-api.com/v4/latest/{base_currency}"
)
→ {"status": "registered", "tool": {"id": "uuid", "name": "currency_exchange", ...}}
```
**场景：**
- Agent 发现某个外部 API 很实用 → 注册为工具 → 立即调用
- URL 中用 `{param}` 占位 → 自动解析为工具参数
- 工具写入 DB → 加载到 tool_registry → 后续所有 Agent 均可复用
---
## Agent 自主能力扩展流程
```
全能助手收到: "监控线上MySQL慢查询并优化"
│
├─ 检查自身 → 缺少SQL专业深度
├─ web_search("MySQL慢查询分析方案")
│
├─ agent_create(name="SQL优化专家", system_prompt="你是MySQL性能优化专家...")
│ └─ 新 Agent 写入 DB，拥有全部 31 工具
│
├─ agent_call("SQL优化专家", "分析这份慢查询日志并给出优化建议")
│ └─ 子 Agent 独立 ReAct 循环执行
│
├─ 发现 percona-toolkit 有 REST API
├─ tool_register(name="pt_query_digest", url="http://internal-api/analyze?log={path}")
│ └─ 工具立即可用
│
└─ 整合结果: "慢查询优化方案如下..."
```
---
## Agent 间协作模式
### 路由模式（全能助手）
```
用户 → 全能助手 → 分析意图
├─ 健康问题 → agent_call("家庭医生助手")
├─ 代码问题 → agent_call("代码助手")
└─ 学习问题 → agent_call("学习助手")
```
### 串行协作
```
全能助手收到"分析服务器日志并给出健康建议"
→ agent_call("日志分析师", "分析这段错误日志")
→ agent_call("家庭医生助手", "这个错误模式是不是意味着系统压力太大，对运维人员的健康有什么建议")
→ 整合两个结果回复用户
```
### 并行协作
```
全能助手收到"对比 React 和 Vue 的优缺点"
→ 并行调用多个搜索/代码分析
→ 综合汇总
```
---
## 复杂项目示例
### 示例 1：从零搭建 Web 应用
```
用户: "帮我搭一个用户管理后台"
Agent 自主规划:
1. task_plan(action="create", title="用户管理后台", steps_json=[...])
2. project_scaffold(template="fastapi", project_name="user-admin")
3. code_execute 写模型代码 → 验证 → 修正
4. project_scaffold(template="vue", project_name="user-admin-ui")
5. web_search("Vue 3 Element Plus table CRUD example")
6. code_execute 写前端组件 → 验证
7. docker_manage(operation="compose") 检查环境
8. deploy_push(source_path="user-admin", target="/opt/app", method="copy")
9. pdf_generate(markdown="# 部署文档...") 生成交付文档
```
### 示例 2：数据分析报告
```
用户: "分析 sales.xlsx 的销售趋势并生成报告"
Agent 自主规划:
1. excel_process(action="read", file_path="sales.xlsx")
2. code_execute("用 Python 计算月度增长率/同比/环比")
3. excel_process(action="chart", chart_config_json='{"type":"line",...}')
4. web_search("2025 电商行业销售趋势对比") 补充行业背景
5. pdf_generate(markdown="# 销售分析报告\n...")
```
### 示例 3：Bug 排查
```
用户: "线上 /api/orders 接口报 500，帮我排查"
Agent 自主规划:
1. docker_manage(operation="logs", resource="api-container")
2. git_operation(operation="log", file_path="src/api/orders.py")
3. git_operation(operation="diff") 查看最近改动
4. database_query("SELECT * FROM orders WHERE created_at > '...'")
5. web_search("FastAPI order API 500 error common causes")
6. code_execute 复现 bug → 定位根因 → 输出修复方案
```
---
## 依赖安装（可选工具）
部分工具需要额外依赖才能使用。Agent 首次调用时会返回明确的安装指引。
| 工具 | 依赖 | 安装命令 |
|------|------|----------|
| `pdf_generate`（PDF模式） | weasyprint | `pip install weasyprint` |
| `browser_use` | playwright | `pip install playwright && playwright install chromium` |
| `excel_process` | openpyxl | `pip install openpyxl` |
| `docker_manage` | docker CLI | 安装 Docker Desktop |
| `deploy_push`（rsync模式） | rsync | `apt install rsync` / `brew install rsync` |
| `git_operation` | git CLI | 安装 Git |
| `code_execute`（JS模式） | node | 安装 Node.js |
---
## 扩展工具
如需添加新工具：
1. 在 `backend/app/services/builtin_tools.py` 添加工具函数 + Schema
2. 在 `backend/app/core/tools_bootstrap.py` 注册
3. 在 `frontend/src/utils/agentSkills.ts` 添加条目
4. 重启后端
工具函数签名为：
```python
async def my_tool(param1: str, param2: int = 0) -> str:
# ... 实现 ...
return json.dumps({"result": "..."}, ensure_ascii=False)
```

56
创建agent.md
View File

@@ -2,9 +2,9 @@
## 概述
本系统支持多种方式创建 Agent。**所有创建方式均默认赋予 Agent 全部 19 个内置工具能力**，除非明确限制。
本系统支持多种方式创建 Agent。**所有创建方式均默认赋予 Agent 全部 31 个内置工具能力**，除非明确限制。
## 内置工具清单（19个）
## 内置工具清单（31个）
| 类别 | 工具 | 用途 |
|------|------|------|
@@ -27,6 +27,58 @@
| 工具 | `random_generate` | 随机数据生成 |
| 调试 | `adb_log` | Android 设备日志（ADB） |
| 协作 | `agent_call` | 调用其他 Agent 委派任务（Agent 间协作） |
| 协作 | `agent_create` | 动态创建专业子 Agent（自我扩展能力） |
| 协作 | `tool_register` | 动态注册新 HTTP 工具（自我扩展工具） |
---
## Agent 自主能力扩展
Agent 可以通过 `agent_create` + `tool_register` 在运行时自我扩展能力和工具。
### 能力不足时的自主决策流程
```
Agent 收到复杂任务
│
├─ 评估自身能力是否足够
├─ 能力足够 → 直接处理
│
├─ 领域知识不足 → agent_create 创建专业子 Agent → agent_call 委派
│
├─ 缺少实用工具 → web_search 找到外部 API → tool_register 注册工具 → 直接调用
│
└─ 整合所有结果返回用户
```
### agent_create — 动态创建子 Agent
```
agent_create(
name="SQL优化专家",
system_prompt="你是MySQL性能优化专家，擅长分析慢查询日志并给出优化建议...",
description="专门优化MySQL慢查询"
)
→ {"status": "created", "agent": {"id": "uuid", ...}}
# 创建后立即委派
agent_call(agent_name="SQL优化专家", query="分析这份慢查询日志")
```
### tool_register — 动态注册工具
```
tool_register(
name="currency_exchange",
description="查询实时汇率",
method="GET",
url="https://api.exchangerate-api.com/v4/latest/{base_currency}"
)
→ {"status": "registered", "tool": {"id": "uuid", ...}}
# 注册后立即可用
currency_exchange(base_currency="USD")
```
---