@easynet/agent-tool 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# Agent Tool
+
+**自动把你任意的 function 和 SKILL，转换为 tool，链接到任何 LLM model 和 agent。**
+
+---
+
+## 支持什么
+
+| 来源 | 写法 |
+|------|------|
+| **任意函数** | 添加 `@tool` annotation 秒变 MCP tool |
+| **SKILL** | 全面支持 [SKILL](docs/AGENT_SKILLS_SPEC.md)，不再依赖 Claude，支持任意 LLM |
+| **mcp.json** | 桥接其他 MCP |
+
+---
+
+## 快速启动
+
+1. **安装**（Node 18+）
+
+   ```bash
+   npm install @easynet/agent-tool
+   ```
+
+2. **编译**：在项目目录执行，输出到 `dist/`
+
+   ```bash
+   agent-tool build
+   ```
+
+3. **发布**（可选）：进 `dist/` 发布为自己的 npm 包
+
+   ```bash
+   cd dist && npm publish
+   ```
+
+4. **运行**：进 `dist/` 后按正常 `npm start` 启动 MCP
+
+   ```bash
+   cd dist && npm install && npm start
+   ```
+
+5. **安装自己的包**：发布后可在任意项目 `npm install <你的包名>` 安装使用。
+
+用 Cursor / Claude 等 MCP 客户端连 `mcp.json` 即可。
+
+---
+
+## 代码示例
+
+**@tool（TypeScript）**
+
+```ts
+/**
+ * 两数相加。
+ * @tool
+ */
+export async function add(a: number, b: number): Promise<number> {
+  return a + b;
+}
+```
+
+→ 生成的 MCP 工具：  
+- 名：`example.add`（文件 `src/tools/example.ts` 时为 `src.tools.example.add`）  
+- 描述：两数相加  
+- 入参：`a` (number)、`b` (number)
+
+工具名由路径+函数名决定，如 `src/tools/math.ts` 的 `add` → `src.tools.math.add`。
+
+**SKILL**
+
+目录内放 `SKILL.md`（YAML 头：name、description）和可选的 `handler.js`。详见 [AGENT_SKILLS_SPEC](docs/AGENT_SKILLS_SPEC.md)。
+
+**示例与扩展**
+
+- 示例脚本与参考内容：`extensions/examples/`（ReAct 股票报告脚本、instruction-only skill、MCP 配置）。
+- 示例工具扩展（core 风格）：`extensions/example-tools/`（Yahoo Finance quote + chart；FS/HTTP 用 builtin-tools）。
+
+**运行 Agent（CLI 一条命令）**
+
+```bash
+# 需配置 OPENAI_API_KEY；MCP 模式需项目根或 MCP_CONFIG_PATH 下有 mcp.json
+agent-tool run "你的任务"                  # 默认 local（builtin + example 工具）
+agent-tool run "你的任务" --mode mcp       # MCP 模式（mcp.json 里的工具）
+agent-tool run "任务" -c agent.yaml        # 用 YAML 指定要加载的 tool 名字
+agent-tool run "任务" --mode mcp --report out.html
+```
+
+- `run`：执行 ReAct agent，第一个参数为任务，`--mode local|mcp` 选工具来源，`--config` / `-c` 指定 agent YAML，`--report` 指定报告路径。
+- **Agent YAML**：在 `agent.yaml` 里写 `mode` 和要加载的 **tool 名字**，framework 自动按名加载。示例见 `agent.yaml.example`：
+  - `tools: [core/fs.readText, core/fs.listDir, example/finance.yahoo.quote]` 只加载列出的工具；
+  - 支持 npm 描述符：`npm:@scope/package#toolPath`，如 `npm:@easynet/agent-tool-builtin-tools#fs.readText` → `core/fs.readText`；
+  - 或 `tools: { builtin: [fs, http], example: true }` 按组加载。
+- `serve`：启动生成的 MCP 服务（stdio，用于测试）：`agent-tool serve` 或 `agent-tool serve -p ./dist`。
+- 股票示例：`npm run agent:stock AAPL`（需先 `npm run build`）。
+
+**MCP 模式**：`agent-tool run "任务" --mode mcp`。Framework 读取当前目录或 `MCP_CONFIG_PATH` 下的 `mcp.json`，按配置用 stdio 启动 MCP server 并连接，将 MCP 工具转为 LangChain 工具供 agent 使用。
+
+- **用法**：`npm run agent -- --mode mcp "任务" [report.html]`。mcp.json 由用户配置（command、args、cwd），指向你要用的 MCP server。
+- **mcp.json**：`scripts/mcp.json` 为 Cursor 格式示例；裸配置见 `scripts/mcp-agent-tool.json`。将 `command`/`args` 改为你的 MCP 启动命令即可。
+- 环境变量：`AGENT_MODE`、`MCP_CONFIG_PATH`、`AGENT_TASK`、`AGENT_SYSTEM`、`OPENAI_API_KEY` 等。
+
+**Release (npmjs.org)**：Publish runs when you **push to branch `master`**, or manually: open **Actions** → select **Release** → **Run workflow**. Add **NPM_TOKEN** (npm Automation or Publish token for @easynet) in repo **Settings → Secrets and variables → Actions**.

package/dist/chunk-3YLVPZRJ.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+// src/types/ToolSpec.ts
+var DEFAULT_INPUT_SCHEMA = {
+  type: "object",
+  additionalProperties: true
+};
+var DEFAULT_OUTPUT_SCHEMA = {
+  type: "object",
+  additionalProperties: true
+};
+function createToolSpec(opts) {
+  const sideEffect = opts.sideEffect ?? "none";
+  return {
+    name: opts.name,
+    version: opts.version ?? "1.0.0",
+    kind: opts.kind,
+    description: opts.description,
+    tags: opts.tags,
+    inputSchema: opts.inputSchema ?? DEFAULT_INPUT_SCHEMA,
+    outputSchema: opts.outputSchema ?? DEFAULT_OUTPUT_SCHEMA,
+    capabilities: opts.capabilities,
+    costHints: opts.costHints,
+    _meta: { hitl: { sideEffect } }
+  };
+}
+
+exports.DEFAULT_INPUT_SCHEMA = DEFAULT_INPUT_SCHEMA;
+exports.DEFAULT_OUTPUT_SCHEMA = DEFAULT_OUTPUT_SCHEMA;
+exports.createToolSpec = createToolSpec;
+//# sourceMappingURL=chunk-3YLVPZRJ.cjs.map
+//# sourceMappingURL=chunk-3YLVPZRJ.cjs.map

package/dist/chunk-3YLVPZRJ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types/ToolSpec.ts"],"names":[],"mappings":";;;AAwEO,IAAM,oBAAA,GAA+B;AAAA,EAC1C,IAAA,EAAM,QAAA;AAAA,EACN,oBAAA,EAAsB;AACxB;AAGO,IAAM,qBAAA,GAAgC;AAAA,EAC3C,IAAA,EAAM,QAAA;AAAA,EACN,oBAAA,EAAsB;AACxB;AA2BO,SAAS,eAAe,IAAA,EAAuC;AACpE,EAAA,MAAM,UAAA,GAAa,KAAK,UAAA,IAAc,MAAA;AACtC,EAAA,OAAO;AAAA,IACL,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,OAAA,EAAS,KAAK,OAAA,IAAW,OAAA;AAAA,IACzB,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,aAAa,IAAA,CAAK,WAAA;AAAA,IAClB,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,WAAA,EAAa,KAAK,WAAA,IAAe,oBAAA;AAAA,IACjC,YAAA,EAAc,KAAK,YAAA,IAAgB,qBAAA;AAAA,IACnC,cAAc,IAAA,CAAK,YAAA;AAAA,IACnB,WAAW,IAAA,CAAK,SAAA;AAAA,IAChB,KAAA,EAAO,EAAE,IAAA,EAAM,EAAE,YAAW;AAAE,GAChC;AACF","file":"chunk-3YLVPZRJ.cjs","sourcesContent":["/**\n * Unified tool kinds supported by the tools package.\n */\nexport type ToolKind = \"mcp\" | \"langchain\" | \"n8n\" | \"comfyui\" | \"skill\" | \"core\" | \"example\";\n\n/**\n * Capability declarations for tools.\n * Used by PolicyEngine for permission gating.\n */\nexport type Capability =\n  | \"read:web\"\n  | \"read:fs\"\n  | \"write:fs\"\n  | \"read:db\"\n  | \"write:db\"\n  | \"network\"\n  | \"gpu\"\n  | \"workflow\"\n  | \"danger:destructive\"\n  | \"exec\";\n\n/**\n * HITL (Human-in-the-Loop) side-effect classification.\n * Used to gate execution: external_write / destructive require human approval when onApprovalRequired is set.\n */\nexport type HitlSideEffect = \"none\" | \"local_write\" | \"external_write\" | \"destructive\";\n\n/**\n * Cost hints for tools, used by Budget and routing.\n */\nexport interface CostHints {\n  latencyMsP50?: number;\n  latencyMsP95?: number;\n  isAsync?: boolean;\n}\n\n/**\n * Unified tool specification.\n * All tool types (MCP, LangChain, n8n, SKILL) are described by this interface.\n */\nexport interface ToolSpec {\n  /** Globally unique name, recommended format: namespace/name */\n  name: string;\n  /** Semver version */\n  version: string;\n  /** Tool kind determines which adapter handles execution */\n  kind: ToolKind;\n\n  description?: string;\n  tags?: string[];\n\n  /** JSON Schema for input validation */\n  inputSchema: object;\n  /** JSON Schema for output validation */\n  outputSchema: object;\n\n  /** Required capabilities for this tool */\n  capabilities: Capability[];\n  costHints?: CostHints;\n\n  /** HITL: side-effect level; when external_write/destructive, runtime may require human approval before execute */\n  _meta?: { hitl?: { sideEffect?: HitlSideEffect } };\n\n  /** Adapter-specific: endpoint URL (MCP/n8n) */\n  endpoint?: string;\n  /** Adapter-specific: resource identifier (workflowId, promptId, etc.) */\n  resourceId?: string;\n  /** Adapter-specific: implementation reference (LangChain Tool instance, skill handler) */\n  impl?: unknown;\n}\n\n/** Default permissive input schema when not provided (framework supports auto-derived schema). */\nexport const DEFAULT_INPUT_SCHEMA: object = {\n  type: \"object\",\n  additionalProperties: true,\n};\n\n/** Default permissive output schema when not provided (framework supports auto-derived schema). */\nexport const DEFAULT_OUTPUT_SCHEMA: object = {\n  type: \"object\",\n  additionalProperties: true,\n};\n\n/**\n * Minimal options to build a ToolSpec. Use with @effect in JSDoc for HITL sideEffect.\n * Framework fills _meta.hitl.sideEffect from the sideEffect parameter (matches @effect annotation).\n * inputSchema/outputSchema are optional: when omitted, permissive defaults are used (framework supports auto-derived schema at build time in codegen).\n */\nexport interface CreateToolSpecOptions {\n  name: string;\n  version?: string;\n  kind: ToolKind;\n  description?: string;\n  tags?: string[];\n  /** Optional: when omitted, DEFAULT_INPUT_SCHEMA is used. Codegen can derive from handler params. */\n  inputSchema?: object;\n  /** Optional: when omitted, DEFAULT_OUTPUT_SCHEMA is used. Codegen can derive from handler return type. */\n  outputSchema?: object;\n  capabilities: Capability[];\n  costHints?: CostHints;\n  /** HITL: from @effect annotation (none | local_write | external_write | destructive). Default \"none\". */\n  sideEffect?: HitlSideEffect;\n}\n\n/**\n * Build a ToolSpec from minimal options. Use @effect in handler JSDoc as annotation; pass same value as sideEffect.\n * When inputSchema/outputSchema are omitted, permissive defaults are used (schema can be auto-derived at build time).\n */\nexport function createToolSpec(opts: CreateToolSpecOptions): ToolSpec {\n  const sideEffect = opts.sideEffect ?? \"none\";\n  return {\n    name: opts.name,\n    version: opts.version ?? \"1.0.0\",\n    kind: opts.kind,\n    description: opts.description,\n    tags: opts.tags,\n    inputSchema: opts.inputSchema ?? DEFAULT_INPUT_SCHEMA,\n    outputSchema: opts.outputSchema ?? DEFAULT_OUTPUT_SCHEMA,\n    capabilities: opts.capabilities,\n    costHints: opts.costHints,\n    _meta: { hitl: { sideEffect } },\n  };\n}\n\n/**\n * Unified adapter interface.\n * Each protocol adapter (MCP, LangChain, n8n, SKILL) implements this.\n */\nexport interface ToolAdapter {\n  kind: ToolKind;\n  /** Optional: supports dynamic tool discovery */\n  listTools?(): Promise<ToolSpec[]>;\n  /** Execute the tool with validated args */\n  invoke(\n    spec: ToolSpec,\n    args: unknown,\n    ctx: import(\"./ToolIntent.js\").ExecContext,\n  ): Promise<{ result: unknown; raw?: unknown }>;\n}\n"]}

package/dist/chunk-AXUNV4MK.js

@@ -0,0 +1,28 @@
+// src/types/ToolSpec.ts
+var DEFAULT_INPUT_SCHEMA = {
+  type: "object",
+  additionalProperties: true
+};
+var DEFAULT_OUTPUT_SCHEMA = {
+  type: "object",
+  additionalProperties: true
+};
+function createToolSpec(opts) {
+  const sideEffect = opts.sideEffect ?? "none";
+  return {
+    name: opts.name,
+    version: opts.version ?? "1.0.0",
+    kind: opts.kind,
+    description: opts.description,
+    tags: opts.tags,
+    inputSchema: opts.inputSchema ?? DEFAULT_INPUT_SCHEMA,
+    outputSchema: opts.outputSchema ?? DEFAULT_OUTPUT_SCHEMA,
+    capabilities: opts.capabilities,
+    costHints: opts.costHints,
+    _meta: { hitl: { sideEffect } }
+  };
+}
+
+export { DEFAULT_INPUT_SCHEMA, DEFAULT_OUTPUT_SCHEMA, createToolSpec };
+//# sourceMappingURL=chunk-AXUNV4MK.js.map
+//# sourceMappingURL=chunk-AXUNV4MK.js.map

package/dist/chunk-AXUNV4MK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types/ToolSpec.ts"],"names":[],"mappings":";AAwEO,IAAM,oBAAA,GAA+B;AAAA,EAC1C,IAAA,EAAM,QAAA;AAAA,EACN,oBAAA,EAAsB;AACxB;AAGO,IAAM,qBAAA,GAAgC;AAAA,EAC3C,IAAA,EAAM,QAAA;AAAA,EACN,oBAAA,EAAsB;AACxB;AA2BO,SAAS,eAAe,IAAA,EAAuC;AACpE,EAAA,MAAM,UAAA,GAAa,KAAK,UAAA,IAAc,MAAA;AACtC,EAAA,OAAO;AAAA,IACL,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,OAAA,EAAS,KAAK,OAAA,IAAW,OAAA;AAAA,IACzB,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,aAAa,IAAA,CAAK,WAAA;AAAA,IAClB,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,WAAA,EAAa,KAAK,WAAA,IAAe,oBAAA;AAAA,IACjC,YAAA,EAAc,KAAK,YAAA,IAAgB,qBAAA;AAAA,IACnC,cAAc,IAAA,CAAK,YAAA;AAAA,IACnB,WAAW,IAAA,CAAK,SAAA;AAAA,IAChB,KAAA,EAAO,EAAE,IAAA,EAAM,EAAE,YAAW;AAAE,GAChC;AACF","file":"chunk-AXUNV4MK.js","sourcesContent":["/**\n * Unified tool kinds supported by the tools package.\n */\nexport type ToolKind = \"mcp\" | \"langchain\" | \"n8n\" | \"comfyui\" | \"skill\" | \"core\" | \"example\";\n\n/**\n * Capability declarations for tools.\n * Used by PolicyEngine for permission gating.\n */\nexport type Capability =\n  | \"read:web\"\n  | \"read:fs\"\n  | \"write:fs\"\n  | \"read:db\"\n  | \"write:db\"\n  | \"network\"\n  | \"gpu\"\n  | \"workflow\"\n  | \"danger:destructive\"\n  | \"exec\";\n\n/**\n * HITL (Human-in-the-Loop) side-effect classification.\n * Used to gate execution: external_write / destructive require human approval when onApprovalRequired is set.\n */\nexport type HitlSideEffect = \"none\" | \"local_write\" | \"external_write\" | \"destructive\";\n\n/**\n * Cost hints for tools, used by Budget and routing.\n */\nexport interface CostHints {\n  latencyMsP50?: number;\n  latencyMsP95?: number;\n  isAsync?: boolean;\n}\n\n/**\n * Unified tool specification.\n * All tool types (MCP, LangChain, n8n, SKILL) are described by this interface.\n */\nexport interface ToolSpec {\n  /** Globally unique name, recommended format: namespace/name */\n  name: string;\n  /** Semver version */\n  version: string;\n  /** Tool kind determines which adapter handles execution */\n  kind: ToolKind;\n\n  description?: string;\n  tags?: string[];\n\n  /** JSON Schema for input validation */\n  inputSchema: object;\n  /** JSON Schema for output validation */\n  outputSchema: object;\n\n  /** Required capabilities for this tool */\n  capabilities: Capability[];\n  costHints?: CostHints;\n\n  /** HITL: side-effect level; when external_write/destructive, runtime may require human approval before execute */\n  _meta?: { hitl?: { sideEffect?: HitlSideEffect } };\n\n  /** Adapter-specific: endpoint URL (MCP/n8n) */\n  endpoint?: string;\n  /** Adapter-specific: resource identifier (workflowId, promptId, etc.) */\n  resourceId?: string;\n  /** Adapter-specific: implementation reference (LangChain Tool instance, skill handler) */\n  impl?: unknown;\n}\n\n/** Default permissive input schema when not provided (framework supports auto-derived schema). */\nexport const DEFAULT_INPUT_SCHEMA: object = {\n  type: \"object\",\n  additionalProperties: true,\n};\n\n/** Default permissive output schema when not provided (framework supports auto-derived schema). */\nexport const DEFAULT_OUTPUT_SCHEMA: object = {\n  type: \"object\",\n  additionalProperties: true,\n};\n\n/**\n * Minimal options to build a ToolSpec. Use with @effect in JSDoc for HITL sideEffect.\n * Framework fills _meta.hitl.sideEffect from the sideEffect parameter (matches @effect annotation).\n * inputSchema/outputSchema are optional: when omitted, permissive defaults are used (framework supports auto-derived schema at build time in codegen).\n */\nexport interface CreateToolSpecOptions {\n  name: string;\n  version?: string;\n  kind: ToolKind;\n  description?: string;\n  tags?: string[];\n  /** Optional: when omitted, DEFAULT_INPUT_SCHEMA is used. Codegen can derive from handler params. */\n  inputSchema?: object;\n  /** Optional: when omitted, DEFAULT_OUTPUT_SCHEMA is used. Codegen can derive from handler return type. */\n  outputSchema?: object;\n  capabilities: Capability[];\n  costHints?: CostHints;\n  /** HITL: from @effect annotation (none | local_write | external_write | destructive). Default \"none\". */\n  sideEffect?: HitlSideEffect;\n}\n\n/**\n * Build a ToolSpec from minimal options. Use @effect in handler JSDoc as annotation; pass same value as sideEffect.\n * When inputSchema/outputSchema are omitted, permissive defaults are used (schema can be auto-derived at build time).\n */\nexport function createToolSpec(opts: CreateToolSpecOptions): ToolSpec {\n  const sideEffect = opts.sideEffect ?? \"none\";\n  return {\n    name: opts.name,\n    version: opts.version ?? \"1.0.0\",\n    kind: opts.kind,\n    description: opts.description,\n    tags: opts.tags,\n    inputSchema: opts.inputSchema ?? DEFAULT_INPUT_SCHEMA,\n    outputSchema: opts.outputSchema ?? DEFAULT_OUTPUT_SCHEMA,\n    capabilities: opts.capabilities,\n    costHints: opts.costHints,\n    _meta: { hitl: { sideEffect } },\n  };\n}\n\n/**\n * Unified adapter interface.\n * Each protocol adapter (MCP, LangChain, n8n, SKILL) implements this.\n */\nexport interface ToolAdapter {\n  kind: ToolKind;\n  /** Optional: supports dynamic tool discovery */\n  listTools?(): Promise<ToolSpec[]>;\n  /** Execute the tool with validated args */\n  invoke(\n    spec: ToolSpec,\n    args: unknown,\n    ctx: import(\"./ToolIntent.js\").ExecContext,\n  ): Promise<{ result: unknown; raw?: unknown }>;\n}\n"]}