@roll-agent/octopus-agent 0.1.3 → 0.2.0

package/src/mcp-client.js

@@ -0,0 +1,80 @@
+const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+
+export class SpongeMcpError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "SpongeMcpError";
+    this.status = options.status;
+    this.code = options.code;
+  }
+}
+
+export class SpongeMcpClient {
+  constructor({ baseUrl, accessToken, requestTimeoutMs = 30_000, networkRetries = 2, fetchImpl = fetch }) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.accessToken = accessToken;
+    this.requestTimeoutMs = requestTimeoutMs;
+    this.networkRetries = networkRetries;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async call(tool, payload, { signal } = {}) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.networkRetries; attempt += 1) {
+      try {
+        return await this.#post(tool, payload, signal);
+      } catch (error) {
+        lastError = error;
+        if (attempt === this.networkRetries || !isRetryable(error)) throw error;
+      }
+    }
+    throw lastError;
+  }
+
+  async #post(tool, payload, parentSignal) {
+    const timeout = AbortSignal.timeout(this.requestTimeoutMs);
+    const signal = parentSignal ? AbortSignal.any([parentSignal, timeout]) : timeout;
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}/mcp/tools/${tool}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...(this.accessToken ? { authorization: `Bearer ${this.accessToken}` } : {}),
+        },
+        body: JSON.stringify(payload),
+        signal,
+      });
+    } catch (error) {
+      throw new SpongeMcpError(`MCP ${tool} 网络调用失败`, { cause: error, code: "NETWORK_ERROR" });
+    }
+
+    const text = await response.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : {};
+    } catch (error) {
+      throw new SpongeMcpError(`MCP ${tool} 返回非 JSON 数据`, {
+        cause: error,
+        status: response.status,
+        code: "INVALID_RESPONSE",
+      });
+    }
+    if (!response.ok) {
+      const detail = body?.error?.message;
+      throw new SpongeMcpError(
+        detail || `MCP ${tool} 调用失败：HTTP ${response.status}`,
+        {
+        status: response.status,
+        code: body?.errorCode || body?.error?.code || "HTTP_ERROR",
+        },
+      );
+    }
+    return body;
+  }
+}
+
+function isRetryable(error) {
+  return error instanceof SpongeMcpError &&
+    (error.code === "NETWORK_ERROR" || RETRYABLE_STATUS.has(error.status));
+}

package/src/orchestrator.js

@@ -0,0 +1,57 @@
+import { createRequestId } from "./context.js";
+
+const RESULT_FORMATS = new Set(["text", "json", "yaml", "md", "markdown", "html"]);
+
+export class ProtocolError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProtocolError";
+  }
+}
+
+export class QueryOrchestrator {
+  constructor({ client, totalTimeoutMs = 59_000 }) {
+    this.client = client;
+    this.totalTimeoutMs = totalTimeoutMs;
+  }
+
+  async query(input) {
+    validateInput(input);
+    const requestId = createRequestId();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("查询总超时")), this.totalTimeoutMs);
+
+    try {
+      const response = await this.client.call("query_sponge", {
+        requestId,
+        question: input.question,
+        resultFormat: input.resultFormat || "markdown",
+      }, { signal: controller.signal });
+      return validateResponse(response, requestId);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+function validateInput(input) {
+  if (!input || typeof input.question !== "string" || !input.question.trim()) {
+    throw new TypeError("question 必须是非空字符串");
+  }
+  if (input.resultFormat !== undefined && !RESULT_FORMATS.has(input.resultFormat)) {
+    throw new TypeError("resultFormat 仅支持 text/json/yaml/md/markdown/html");
+  }
+}
+
+function validateResponse(response, requestId) {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    throw new ProtocolError("query_sponge 返回值必须是对象");
+  }
+  if (response.requestId !== requestId) throw new ProtocolError("query_sponge 返回的 requestId 不一致");
+  if (response.status !== "succeeded") throw new ProtocolError("query_sponge 返回的 status 非法");
+  if (typeof response.queryId !== "string" || !response.queryId) {
+    throw new ProtocolError("query_sponge 缺少 queryId");
+  }
+  if (typeof response.answer !== "string") throw new ProtocolError("query_sponge 缺少 answer");
+  return response;
+}

package/src/server-core.js

@@ -0,0 +1,67 @@
+export const PROTOCOL_VERSION = "2024-11-05";
+
+export function toolDefinitions() {
+  return [{
+    name: "query",
+    description: "仅用于用户明确提出的业务数据查询。介绍丸子、询问功能或使用方法时禁止调用。查询时原样传入问题，只调用一次 query_sponge（查询 Sponge）。最终回复必须完全等于 content[0].text，保持查询实体、筛选条件、业务逻辑、查询结果的顺序和 Markdown 表格，禁止总结、删减、改写或重排。",
+    inputSchema: {
+      type: "object",
+      required: ["question"],
+      properties: {
+        question: { type: "string", description: "用户原始问题，不得改写" },
+        resultFormat: {
+          type: "string",
+          enum: ["text", "json", "yaml", "md", "markdown", "html"],
+          description: "结果格式，默认 markdown（Markdown 格式）",
+        },
+      },
+      additionalProperties: false,
+    },
+  }];
+}
+
+export async function handleRequest(message, orchestrator) {
+  if (!message || typeof message !== "object" || !("id" in message)) return null;
+  const { id, method } = message;
+  try {
+    if (method === "initialize") {
+      return ok(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: "octopus-agent", version: "0.2.0" },
+      });
+    }
+    if (method === "ping") return ok(id, {});
+    if (method === "tools/list") return ok(id, { tools: toolDefinitions() });
+    if (method === "tools/call") {
+      if (message.params?.name !== "query") return toolError(id, "未知 Tool");
+      const result = await orchestrator.query(message.params?.arguments || {});
+      return ok(id, {
+        content: [{
+          type: "text",
+          text: result.answer,
+          annotations: { audience: ["user"], priority: 1 },
+        }],
+        structuredContent: {
+          queryId: result.queryId,
+          requestId: result.requestId,
+          status: result.status,
+          rowCount: result.rowCount,
+          repairCount: result.repairCount,
+          totalDurationSeconds: result.totalDurationSeconds,
+        },
+        isError: result.status !== "succeeded",
+      });
+    }
+    return fail(id, -32601, `Method not found: ${method}`);
+  } catch (error) {
+    return toolError(id, error instanceof Error ? error.message : String(error));
+  }
+}
+
+const ok = (id, result) => ({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+const toolError = (id, message) => ok(id, {
+  content: [{ type: "text", text: message }],
+  isError: true,
+});

package/src/server.js

@@ -0,0 +1,10 @@
+import { loadConfig } from "./config.js";
+import { SpongeMcpClient } from "./mcp-client.js";
+import { QueryOrchestrator } from "./orchestrator.js";
+import { handleRequest } from "./server-core.js";
+import { StdioTransport } from "./stdio.js";
+
+const config = loadConfig();
+const client = new SpongeMcpClient(config);
+const orchestrator = new QueryOrchestrator({ client, totalTimeoutMs: config.totalTimeoutMs });
+new StdioTransport(process.stdin, process.stdout, (message) => handleRequest(message, orchestrator)).start();

package/src/stdio.js

@@ -0,0 +1,29 @@
+import { createInterface } from "node:readline";
+
+export class StdioTransport {
+  constructor(input, output, onMessage) {
+    this.input = input;
+    this.output = output;
+    this.onMessage = onMessage;
+    this.queue = Promise.resolve();
+  }
+
+  start() {
+    const lines = createInterface({ input: this.input, crlfDelay: Infinity });
+    lines.on("line", (line) => {
+      if (!line.trim()) return;
+      this.queue = this.queue
+        .then(async () => {
+          const response = await this.onMessage(JSON.parse(line));
+          if (response) this.send(response);
+        })
+        .catch((error) => {
+          process.stderr.write(`octopus-agent stdio error: ${error instanceof Error ? error.message : String(error)}\n`);
+        });
+    });
+  }
+
+  send(message) {
+    this.output.write(`${JSON.stringify(message)}\n`);
+  }
+}

package/octopus_skill/__init__.py

@@ -1,11 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-_src_package = Path(__file__).resolve().parent.parent / "src" / "octopus_skill"
-if _src_package.exists():
-    __path__.append(str(_src_package))
-
-from ._version import __version__
-
-__all__ = ["__version__"]

package/pyproject.toml

@@ -1,19 +0,0 @@
-[project]
-name = "octopus-skill"
-version = "0.1.3"
-description = "丸子Agent（Octopus Agent）"
-readme = "README.md"
-requires-python = ">=3.11"
-dependencies = [
-    "rapidfuzz>=3.0",
-]
-
-[project.scripts]
-octopus-agent = "octopus_skill.main:main"
-
-[build-system]
-requires = ["setuptools>=68"]
-build-backend = "setuptools.build_meta"
-
-[tool.setuptools.packages.find]
-where = ["src"]

package/scripts/refresh_dictionary.py

@@ -1,67 +0,0 @@
-"""One-off: refresh the entity dictionary cache via the MCP server.
-
-Replicates Agent._ensure_dictionary's refresh path: calls get_entity_dictionary
-with the configured entity_types and writes the snapshot to the cache file.
-"""
-from __future__ import annotations
-
-import sys
-
-from octopus_skill.config import load_config
-from octopus_skill.context import new_trace_id
-from octopus_skill.entity_dictionary import EntityDictionaryCache
-from octopus_skill.mcp_client import SpongeMcpClient
-
-
-def main() -> int:
-    config = load_config()
-    if config.dictionary is None:
-        print("dictionary config is None; nothing to refresh")
-        return 1
-
-    client = SpongeMcpClient(
-        base_url=config.sponge_mcp.base_url,
-        access_token=config.sponge_mcp.access_token,
-        timeout_ms=config.sponge_mcp.timeout_ms,
-    )
-    cache = EntityDictionaryCache(config.dictionary.cache_path)
-    cached = cache.load()
-    cached_version = (
-        str(cached.get("dictVersion")) if cached and cached.get("dictVersion") else None
-    )
-
-    print(f"base_url={config.sponge_mcp.base_url}")
-    print(f"token_set={bool(config.sponge_mcp.access_token)}")
-    print(f"cached_version={cached_version}")
-    print(f"entity_types={config.dictionary.entity_types}")
-
-    trace_id = new_trace_id("trace_dict")
-    response = client.get_entity_dictionary(
-        trace_id=trace_id,
-        dict_version=cached_version,
-        entity_types=config.dictionary.entity_types,
-    )
-
-    changed = response.get("changed")
-    print(f"response changed={changed} dictVersion={response.get('dictVersion')}")
-
-    if changed is False and cached is not None:
-        print("server reports no change; cache kept as-is")
-        return 0
-
-    if "entities" in response:
-        cache.save(response)
-        ent = response["entities"]
-        for key, value in ent.items():
-            items = value.get("items") if isinstance(value, dict) else None
-            n = len(items) if isinstance(items, list) else "n/a"
-            print(f"  saved {key}: items={n}")
-        print(f"cache written to {config.dictionary.cache_path}")
-        return 0
-
-    print("response had no 'entities'; cache not updated")
-    return 2
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/verify_binding.py

@@ -1,47 +0,0 @@
-"""One-off: verify the brand/location/project binding chain end-to-end.
-
-Builds the resolver from the persisted dictionary cache (same path the agent
-uses) and runs bind_entities on a few real questions, printing what resolved.
-"""
-from __future__ import annotations
-
-import json
-
-from octopus_skill.config import load_config
-from octopus_skill.entity_binding import bind_entities
-from octopus_skill.entity_resolver import EntityResolver, load_geo_aliases
-
-
-def show(question: str, resolver: EntityResolver) -> None:
-    bindings = bind_entities(question, resolver)
-    print(f"\nQ: {question}")
-    print("  brands  :", [(e.id, e.canonical, e.matched_via) for e in bindings.brands])
-    print("  projects:", [(e.id, e.canonical, e.matched_via) for e in bindings.projects])
-    print(
-        "  location:",
-        {lvl: (e.id, e.canonical) for lvl, e in bindings.location.items()},
-    )
-
-
-def main() -> int:
-    config = load_config()
-    assert config.dictionary is not None
-    dictionary = json.loads(config.dictionary.cache_path.read_text(encoding="utf-8"))
-    geo = load_geo_aliases(config.dictionary.geo_alias_path)
-    resolver = EntityResolver.from_payload(dictionary, geo_aliases=geo)
-
-    print("dictVersion:", dictionary.get("dictVersion"))
-    for t in ("brand", "project", "city", "region", "province"):
-        idx = resolver.indexes.get(t)
-        print(f"  index {t}: {len(idx.items) if idx else 0} items")
-
-    # Real project names pulled from the refreshed dictionary.
-    show("西贝莜面村这个项目在上海有多少在招岗位", resolver)
-    show("查一下哈根达斯项目的情况", resolver)
-    show("北京肯德基项目最近招聘多少人", resolver)
-    show("CoCo都可茶饮在南京宝山的门店", resolver)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/octopus_skill/__init__.py

@@ -1,5 +0,0 @@
-"""丸子Agent（Octopus Agent）."""
-
-from ._version import __version__
-
-__all__ = ["__version__"]

package/src/octopus_skill/__main__.py

@@ -1,4 +0,0 @@
-from .main import main
-
-main()
-

package/src/octopus_skill/_version.py

@@ -1,3 +0,0 @@
-from __future__ import annotations
-
-__version__ = "0.1.3"