proma-ai Tool Builder
通过交互式对话帮助用户创建可在 Chat 模式中使用的自定义 HTTP API 工具。
工作流程
1. 需求收集
向用户了解：
- 工具用途（查天气、翻译、汇率等）
- API 端点 URL 和认证方式
- 需要哪些参数（名称、类型、是否必填）
- HTTP 方法（GET/POST）
- 响应中需要提取哪部分数据
如果用户不确定具体 API，帮助推荐合适的公开 API。
2. 构建配置
根据收集的信息构建工具配置 JSON。配置文件位于 ~/.proma/chat-tools.json。
配置文件结构
{
"toolStates": {
"memory": { "enabled": true },
"web-search": { "enabled": false },
"custom-weather": { "enabled": true }
},
"toolCredentials": {},
"customTools": [
{
"id": "custom-weather",
"name": "天气查询",
"description": "查询指定城市的当前天气信息",
"params": [
{ "name": "city", "type": "string", "description": "城市名称", "required": true }
],
"category": "custom",
"executorType": "http",
"httpConfig": {
"urlTemplate": "https://wttr.in/{{city}}?format=j1",
"method": "GET",
"resultPath": "current_condition"
}
}
]
}
ChatToolMeta 字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
id |
是 | 唯一标识，必须以 custom- 前缀 + slug 格式（如 custom-weather） |
name |
是 | 显示名称 |
description |
是 | 工具描述，AI 据此决定何时调用 |
params |
是 | 参数列表，每个含 name/type/description/required |
category |
是 | 固定为 "custom" |
executorType |
是 | 固定为 "http" |
httpConfig |
是 | HTTP 请求配置 |
icon |
否 | Lucide 图标名（如 "Cloud"、"Languages"） |
systemPromptAppend |
否 | 启用时注入的系统提示词 |
httpConfig 字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
urlTemplate |
是 | URL 模板，{{paramName}} 占位符会被参数值替换（自动 URL 编码） |
method |
是 | "GET" 或 "POST" |
headers |
否 | 请求头，常用于 API Key 认证：{ "Authorization": "Bearer xxx" } |
bodyTemplate |
否 | POST 请求体 JSON 模板，{{paramName}} 占位符会被替换（不编码） |
resultPath |
否 | 点号路径提取响应中的特定字段（如 "data.results"） |
参数类型
params[].type 支持："string" / "number" / "boolean"
可选添加 enum 字段限制可选值：
{ "name": "unit", "type": "string", "description": "温度单位", "enum": ["celsius", "fahrenheit"] }
3. 写入配置
操作步骤：
- 读取
~/.proma/chat-tools.json（如不存在则创建） - 将新工具追加到
customTools数组（按id去重） - 在
toolStates中添加{ "enabled": true }使其默认启用 - 写回文件（保持 JSON 格式化）
写入后应用会自动检测文件变化并刷新工具列表。
4. 测试引导
告知用户：
- "工具已创建并启用，请切换到 Chat 模式测试"
- "在 Chat 输入框左下角的工具选择器中应该能看到新工具"
- "试着问一个需要用到这个工具的问题"
- "如果有问题，回到 Agent 模式告诉我，我帮你调试"
5. 调试修复
用户反馈问题时，常见原因：
- URL 模板错误 → 修正
urlTemplate - 参数映射不对 → 调整
params定义 - 响应格式变化 → 修改
resultPath - 认证失败 → 检查
headers中的 API Key - 超时 → 检查 API 可达性
修复后重新写入 chat-tools.json，应用自动刷新。
6. 删除工具
从 customTools 数组中移除对应工具，同时删除 toolStates 中的条目。
完整示例：天气查询工具
{
"id": "custom-weather",
"name": "天气查询",
"description": "查询指定城市的当前天气和温度信息。当用户询问天气时调用。",
"params": [
{ "name": "city", "type": "string", "description": "城市名称（英文）", "required": true }
],
"category": "custom",
"executorType": "http",
"httpConfig": {
"urlTemplate": "https://wttr.in/{{city}}?format=j1",
"method": "GET",
"resultPath": "current_condition"
}
}
完整示例：翻译工具（POST + API Key）
{
"id": "custom-translate",
"name": "翻译",
"description": "将文本翻译为目标语言。当用户需要翻译时调用。",
"params": [
{ "name": "text", "type": "string", "description": "要翻译的文本", "required": true },
{ "name": "target_lang", "type": "string", "description": "目标语言代码", "required": true, "enum": ["EN", "ZH", "JA", "KO", "FR", "DE", "ES"] }
],
"category": "custom",
"executorType": "http",
"httpConfig": {
"urlTemplate": "https://api.example.com/translate",
"method": "POST",
"headers": { "Authorization": "Bearer YOUR_API_KEY" },
"bodyTemplate": "{\"text\": \"{{text}}\", \"target_lang\": \"{{target_lang}}\"}",
"resultPath": "translations.0.text"
}
}