@roll-agent/octopus-agent 0.0.4 → 0.0.6

package/README.md

@@ -1,4 +1,4 @@
-# Octopus Sponge NL2SQL Agent
+# 丸子Agent（Octopus Agent）
 
 本仓库实现 Octopus 对接 Sponge MCP Server 的第一版 MVP。
 
@@ -32,7 +32,8 @@ roll run octopus-agent diagnostic_status --json
 ```
 
 该 npm package（npm 包）直接包含 Python 源码；`roll agent install` 不会再从 PyPI 下载 `octopus-sponge-skill`。
-安装机器上的 `python3` 需要是 Python 3.11+。
+安装机器需要 Python 3.11+。Windows 默认检查 `python --version`，macOS/Linux 默认检查 `python3 --version`。
+安装阶段会执行 Python 环境检查；没有 Python 3.11+ 时，Windows 会尝试通过 winget 自动安装，macOS 会尝试通过 Homebrew 自动安装，Linux 会提示手动安装。
 
 ### 本地源码注册
 
@@ -83,13 +84,15 @@ roll run octopus-agent query_sponge --json \
   "rollAgent": {
     "runtime": {"ownership": "on-demand", "transport": "stdio"},
     "start": {
-      "command": "python3",
-      "args": ["-m", "octopus_sponge_skill.roll_server"]
+      "command": "node",
+      "args": ["bin/start-roll-server.js"]
     }
   }
 }
 ```
 
+`start-roll-server.js` 会按系统选择 Python 命令：Windows 优先 `python`，macOS/Linux 优先 `python3`；都不可用或版本低于 3.11 时会报错提示安装。
+
 环境变量可放到 `roll.config.yaml`：
 
 ```yaml

package/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: octopus-agent
-description: Octopus Sponge NL2SQL Agent，把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行。
+description: 丸子Agent（Octopus Agent），把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行。
 metadata:
   roll-env-file: references/env.yaml
 ---
 
-# Octopus Sponge Agent
+# 丸子Agent（Octopus Agent）
 
 ## 职责
 
-本 Agent 只负责 Sponge 数据查询：
+本 Agent 只负责海绵数据查询：
 
 - 读取和刷新 Schema Cache（表结构缓存）。
 - 基于用户问题和 schema context，通过 MCP Sampling（采样）请求 roll-core 代调 LLM 生成只读 SQL。
@@ -22,7 +22,7 @@ metadata:
 |-|-|-|
 | `diagnostic_status` | 诊断状态 | 检查配置、缓存和日志路径 |
 | `refresh_schema` | 刷新表结构 | 人工刷新本地 schema 缓存 |
-| `query_sponge` | 查询 Sponge 数据 | 自然语言查询入口 |
+| `query_sponge` | 查询海绵数据 | 自然语言查询入口 |
 
 `refresh_schema` 必填 `traceId`；Agent 会自动读取本地缓存里的 `schemaVersion` 并传给 Sponge。
 

package/bin/check-python.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+
+const MIN_VERSION = [3, 11, 0];
+
+function pythonCandidates() {
+  if (process.platform === "win32") {
+    return [["python"], ["python3"]];
+  }
+  return [["python3"], ["python"]];
+}
+
+function parseVersion(output) {
+  const match = String(output).match(/Python\s+(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return match.slice(1).map((part) => Number(part));
+}
+
+function versionLabel(version) {
+  return version.join(".");
+}
+
+function isSupported(version) {
+  for (let index = 0; index < MIN_VERSION.length; index += 1) {
+    if (version[index] > MIN_VERSION[index]) return true;
+    if (version[index] < MIN_VERSION[index]) return false;
+  }
+  return true;
+}
+
+function commandLabel(command) {
+  return command.join(" ");
+}
+
+function run(command, args, options = {}) {
+  return spawnSync(command[0], [...command.slice(1), ...args], {
+    encoding: "utf8",
+    stdio: options.stdio || ["ignore", "pipe", "pipe"],
+  });
+}
+
+function findPython() {
+  const checked = [];
+  for (const command of pythonCandidates()) {
+    const result = run(command, ["--version"]);
+    const output = `${result.stdout || ""}${result.stderr || ""}`;
+    const version = parseVersion(output);
+    if (result.status === 0 && version && isSupported(version)) {
+      return { command, version, checked };
+    }
+    checked.push({
+      command,
+      reason: version
+        ? `当前版本 ${versionLabel(version)}，需要 ${versionLabel(MIN_VERSION)}+`
+        : "未找到或无法读取版本",
+    });
+  }
+  return { command: null, version: null, checked };
+}
+
+function installPython() {
+  if (process.platform === "win32") {
+    return run(["winget"], ["install", "--id", "Python.Python.3.11", "-e"], {
+      stdio: "inherit",
+    });
+  }
+  if (process.platform === "darwin") {
+    return run(["brew"], ["install", "python@3.11"], { stdio: "inherit" });
+  }
+  return { status: 1 };
+}
+
+function printInstallHelp() {
+  console.error("未找到 Python 3.11+，且自动安装失败。请手动安装后重试。");
+  console.error("Windows: 安装后确认 `python --version` 可用。");
+  console.error("macOS: 安装 Homebrew 后可执行 `brew install python@3.11`。");
+  console.error("Linux: 请使用当前发行版的包管理器安装 Python 3.11+。");
+  console.error("macOS/Linux: 安装后确认 `python3 --version` 可用。");
+}
+
+function main() {
+  let result = findPython();
+  if (result.command) {
+    console.log(
+      `Found Python ${versionLabel(result.version)}: ${commandLabel(
+        result.command
+      )}`
+    );
+    return;
+  }
+
+  for (const item of result.checked) {
+    console.error(`${commandLabel(item.command)}: ${item.reason}`);
+  }
+
+  console.error("正在尝试自动安装 Python 3.11...");
+  const installResult = installPython();
+  if (installResult.status === 0) {
+    result = findPython();
+    if (result.command) {
+      console.log(
+        `Found Python ${versionLabel(result.version)}: ${commandLabel(
+          result.command
+        )}`
+      );
+      return;
+    }
+  }
+
+  printInstallHelp();
+  process.exit(1);
+}
+
+main();

package/bin/start-roll-server.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+const { spawn, spawnSync } = require("child_process");
+
+const MIN_VERSION = [3, 11, 0];
+
+function pythonCandidates() {
+  if (process.platform === "win32") {
+    return [["python"], ["python3"]];
+  }
+  return [["python3"], ["python"]];
+}
+
+function parseVersion(output) {
+  const match = String(output).match(/Python\s+(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return match.slice(1).map((part) => Number(part));
+}
+
+function versionLabel(version) {
+  return version.join(".");
+}
+
+function isSupported(version) {
+  for (let index = 0; index < MIN_VERSION.length; index += 1) {
+    if (version[index] > MIN_VERSION[index]) return true;
+    if (version[index] < MIN_VERSION[index]) return false;
+  }
+  return true;
+}
+
+function commandLabel(command) {
+  return command.join(" ");
+}
+
+function findPython() {
+  const checked = [];
+  for (const command of pythonCandidates()) {
+    const result = spawnSync(command[0], [...command.slice(1), "--version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const output = `${result.stdout || ""}${result.stderr || ""}`;
+    const version = parseVersion(output);
+    if (result.status === 0 && version && isSupported(version)) {
+      return { command, version, checked };
+    }
+    checked.push({
+      command,
+      reason: version
+        ? `当前版本 ${versionLabel(version)}，需要 ${versionLabel(MIN_VERSION)}+`
+        : "未找到或无法读取版本",
+    });
+  }
+  return { command: null, version: null, checked };
+}
+
+function printPythonError(checked) {
+  for (const item of checked) {
+    console.error(`${commandLabel(item.command)}: ${item.reason}`);
+  }
+  console.error("未找到 Python 3.11+，无法启动 octopus-agent。");
+  console.error("Windows: 请安装 Python 3.11+，并确认 `python --version` 可用。");
+  console.error(
+    "macOS/Linux: 请安装 Python 3.11+，并确认 `python3 --version` 可用。"
+  );
+}
+
+function main() {
+  const passthroughArgs = process.argv.slice(2);
+  const checkOnly = passthroughArgs[0] === "--check";
+  const serverArgs = checkOnly ? [] : passthroughArgs;
+  const result = findPython();
+
+  if (!result.command) {
+    printPythonError(result.checked);
+    process.exit(1);
+  }
+
+  if (checkOnly) {
+    console.log(
+      `${commandLabel(result.command)} ${versionLabel(result.version)}`
+    );
+    return;
+  }
+
+  const child = spawn(
+    result.command[0],
+    [...result.command.slice(1), "-m", "octopus_sponge_skill.roll_server", ...serverArgs],
+    { stdio: "inherit" }
+  );
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code || 0);
+  });
+
+  child.on("error", (error) => {
+    console.error(`启动 Python 失败: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@roll-agent/octopus-agent",
-  "version": "0.0.4",
-  "description": "Octopus Sponge NL2SQL Agent",
+  "version": "0.0.6",
+  "description": "丸子Agent（Octopus Agent）",
   "license": "UNLICENSED",
   "keywords": [
     "roll-agent",
@@ -11,7 +11,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "postinstall": "node bin/check-python.js"
+  },
   "files": [
+    "bin",
     "octopus_sponge_skill",
     "src",
     "references",
@@ -27,10 +31,9 @@
       "transport": "stdio"
     },
     "start": {
-      "command": "python3",
+      "command": "node",
       "args": [
-        "-m",
-        "octopus_sponge_skill.roll_server"
+        "bin/start-roll-server.js"
       ]
     }
   }

package/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "octopus-skill"
-version = "0.0.4"
-description = "Octopus Sponge NL2SQL Agent"
+version = "0.0.6"
+description = "丸子Agent（Octopus Agent）"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = []

package/src/octopus_sponge_skill/__init__.py

@@ -1,4 +1,4 @@
-"""Octopus Sponge NL2SQL Agent."""
+"""丸子Agent（Octopus Agent）."""
 
 from ._version import __version__
 

package/src/octopus_sponge_skill/_version.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.0.4"
+__version__ = "0.0.6"