MINARA新增工具
如何向註冊表添加新工具
工具是帶 JSON-Schema 參數的 TypeScript 函數。它們位於 apps/agent/src/tools/<name>.ts，並導出返回 ToolEntry[] 的工廠函數。
最小示例
創建 apps/agent/src/tools/my-provider.ts：
import { PermissionTier, type ToolEntry } from "../core/tool-registry.js";
import { ok, err, errFromThrow } from "./_shared/result.js";
export function createMyProviderTools(): ToolEntry[] {
const apiKey = process.env.MY_PROVIDER_API_KEY;
if (!apiKey) return []; // feature-gate: registry hides missing tools
return [
{
name: "my_provider_search",
toolSet: "research",
permissionTier: PermissionTier.READ_ONLY,
isAsync: true,
description: "Search My Provider for a query",
schema: {
name: "my_provider_search",
description: "Search My Provider for a query",
parameters: {
type: "object",
properties: {
query: { type: "string", description: "The search query" },
limit: { type: "number", description: "Max results", default: 10 },
},
required: ["query"],
},
},
handler: async ({ query, limit }) => {
try {
const res = await fetch(
`https://api.myprovider.com/search?q=${encodeURIComponent(query)}&limit=${limit ?? 10}`,
{ headers: { Authorization: `Bearer ${apiKey}` } },
);
if (!res.ok) return err(`HTTP ${res.status}`);
return ok(await res.json());
} catch (e) {
return errFromThrow(e);
}
},
},
];
}在最接近的能力旁註冊工廠。屬於某個裝配領域的工具應放入 apps/agent/src/app/ 下的對應 Builder，例如 messaging.ts、institution.ts 或 artifacts.ts。沒有對應 Builder 的能力留在 apps/agent/src/app.ts，並放在相關注冊附近。
import { createMyProviderTools } from "./tools/my-provider.js";
// ...
for (const tool of createMyProviderTools()) toolRegistry.register(tool);在 apps/agent/src/core/tool-registry.ts 的 BUILTIN_TOOL_SETS 中添加工具集條目：
research: {
description: "Market and social research tools",
tools: [
// ... existing
"my_provider_search",
],
},如果 Agent 應通過某項技能發現該工具，請將準確的工具名加入該技能的 metadata.minara.tool_names。延遲加載工具通過 tool_search 被發現，因此描述必須具體且不與其他工具衝突。
權限等級
權限等級在 apps/agent/src/core/tool-registry.ts 中定義：
| 等級 | 名稱 | 使用場景 |
|---|---|---|
| 1 | READ_ONLY | 價格 / 餘額 / 搜索 / read_file |
| 2 | CONFIRM_ONCE | 分析、研究、小額兌換 |
| 3 | ALWAYS_CONFIRM | write_file、patch、涉及資金的操作、文檔生成 |
| 4 | MANUAL_ONLY | 提現、外部地址轉賬、緊急停止開關 |
如有疑問，參考最接近的現有工具。資金操作工具還要聲明 isFundMoving: true 和 controlPolicy.confirm。統一權限門會展示預覽，並在處理器運行前確認準確請求。
結果包裹
每個處理器都通過 apps/agent/src/tools/_shared/result.ts 中的 ok({...}) / err("...") 返回字符串。永遠不要從處理器拋出異常。使用 errFromThrow(e) 轉換捕獲的錯誤。Agent 循環解析包裹並向 LLM 呈現結構化錯誤。
沙盒根目錄文件工具
如果工具涉及文件系統，使用 apps/agent/src/tools/_security/sandbox.ts 中的 resolveInSandbox() 解析所有路徑。這是強制要求。參見沙盒與權限。
驗證並更新文檔
在 apps/agent/tests/unit/tools/ 下添加聚焦測試，覆蓋成功結果、提供商錯誤、憑據缺失和聲明的安全策略。
pnpm --filter @minara/agent exec vitest run tests/unit/tools/my-provider.test.ts
pnpm --filter @minara/agent typecheck
pnpm --filter @minara/docs generate工具改變公共流程時，需要同步更新四種語言的手寫文檔。生成的工具參考來自 BUILTIN_TOOL_SETS，不要直接編輯。