@roll-agent/octopus-agent 0.1.3 → 0.2.0

package/README.md

@@ -1,209 +1,45 @@
-# 丸子Agent（Octopus Agent）
+# Octopus Agent
 
-本仓库实现 Octopus 对接 Sponge MCP Server 的第一版 MVP。
-
-## 能力
-
-- Schema Cache（表结构缓存）：本地保存 Sponge 返回的 schema。
-- MCP Client（MCP 客户端）：按 `get_schema`、`validate_sql`、`execute_sql` 三步调用。
-- MCP Sampling（采样）：由 roll-core 代调 LLM 生成和修正 SQL。
-- SQL Guard（SQL 保护规则）：只允许单条 `SELECT`，必须带 `LIMIT`。
-- Audit Log（审计日志）：记录 trace、session、SQL hash、执行摘要。
+Octopus Agent 是 Node.js 实现的轻量 NL2SQL（自然语言转 SQL）调用客户端。Agent 每次只调用一次 `query_sponge`（查询 Sponge）；所有业务判断、SQL 生成、校验、修复、执行和渲染均由 Sponge MCP Server 完成。
 
 ## 本地运行
 
-```bash
-python -m octopus_skill "查询我能看到的品牌列表"
-```
-
-运行参数由 Agent 内置；用户本地只需要配置 Sponge MCP Server 地址和 Token。
-
-## roll-core 接入
-
-本仓库支持纯 Python stdio MCP 子 Agent 接入 roll-core。
-
-### npm 包安装
-
-发布到 npm 后，可通过 `roll agent install` 安装：
+要求 Node.js 20 或更高版本。
 
 ```bash
-roll agent install @roll-agent/octopus-agent
+npm install
+npm test
+npm start
 ```
 
-该 npm package（npm 包）直接包含 Python 源码；`roll agent install` 不会再从 PyPI 下载 `octopus-skill`。
-安装机器上需要有 Python 3.11+。Agent 启动时会自动尝试 `python3`、`python`、`py -3.11`、`py -3`。
-如果 Python 命令不在这些名称里，可以配置 `OCTOPUS_PYTHON_COMMAND`（Python 命令），例如：
-
-```powershell
-roll config set agents.env.octopus-agent.OCTOPUS_PYTHON_COMMAND "py -3.11"
-```
-
-Windows 用户只要安装 Python 3.11+，通常不需要额外创建 `python3` 别名。
-
-### 首次使用引导（安装后必做）
-
-业务查询前先完成这两步，可减少首次 `query_sponge` 冷启动耗时，并尽早发现配置问题：
-
-```bash
-# 1) 检查 token、schema 缓存、日志路径
-roll run octopus-agent diagnostic_status --json
-
-# 2) 预热本地 schema 缓存（Windows 请用 --input-file，见下文）
-roll run octopus-agent refresh_schema --json \
-  --input-json '{"traceId":"trace_schema_10001"}'
-```
-
-确认 `diagnostic_status` 里 `spongeMcp.accessTokenConfigured=true`，且 `refresh_schema` 成功后，再发起业务查询。
-
-### 本地源码注册
+## Roll Agent 接入
 
 ```bash
 roll agent add .
-roll run octopus-agent diagnostic_status --json
-roll run octopus-agent refresh_schema --json \
-  --input-json '{"traceId":"trace_schema_10001"}'
-roll run octopus-agent query_sponge --json \
-  --input-json '{"question":"查询我能看到的品牌列表","originalQuestion":"查询我能看到的品牌列表"}'
+roll run octopus-agent query --json \
+  --input-json '{"question":"查询本月各门店销售额"}'
 ```
 
-`refresh_schema` 必填 `traceId`。Agent 会自动读取本地缓存里的 `schemaVersion` 并传给 Sponge。
-`query_sponge` 必填 `question` 和 `originalQuestion`；不接收用户或设备标识；Sponge MCP Server 会根据 `Authorization` token 解析用户权限。
-Agent 只生成业务 SQL，不生成 `:scope.project_ids`、`:scope.brand_ids` 等权限占位符。
-权限范围由 Sponge MCP Server 在 `execute_sql` 阶段统一补全，并写入 `mcp_sql_records.scope_bindings`。
-
-#### Windows 调用注意（CMD / PowerShell）
+`query`（自然语言查询）入参：
 
-Windows 的 CMD / PowerShell 会改写命令行里的引号，常见结果是把 JSON 变成 `{'question':...}`，从而报：
-
-```text
-✗ --input-json 不是合法 JSON: Expected property name or '}' in JSON at position 1
-```
-
-推荐优先用 `--input-file`，避免 shell 引号问题：
-
-```powershell
-# 1) 先写无 BOM 的 UTF-8 JSON（Windows PowerShell 5.1 用 .NET 写，避免 BOM）
-$path = Join-Path $env:TEMP "octopus-query.json"
-$json = '{"question":"奥乐齐有哪些在招的岗位","originalQuestion":"奥乐齐有哪些在招的岗位"}'
-[System.IO.File]::WriteAllText($path, $json, (New-Object System.Text.UTF8Encoding $false))
-
-# 2) 再调用
-roll run octopus-agent query_sponge --input-file $path --json
-```
+| 字段 | 必填 | 中文说明 |
+|-|-|-|
+| `question` | 是 | 用户原始问题，不得改写 |
+| `resultFormat` | 否 | 结果格式，支持 text/json/yaml/md/markdown/html，默认 markdown（Markdown 格式） |
 
-若必须内联 JSON：
-
-```powershell
-# PowerShell：用双引号包住 JSON，内部双引号写成 \"
-roll run octopus-agent query_sponge --json --input-json "{\"question\":\"查询我能看到的品牌列表\",\"originalQuestion\":\"查询我能看到的品牌列表\"}"
-```
-
-```bat
-REM CMD：外层用双引号，内部双引号写成 \"
-roll run octopus-agent query_sponge --json --input-json "{\"question\":\"查询我能看到的品牌列表\",\"originalQuestion\":\"查询我能看到的品牌列表\"}"
-```
-
-macOS / Linux / Git Bash 仍可继续用单引号包 JSON：
-
-```bash
-roll run octopus-agent query_sponge --json \
-  --input-json '{"question":"查询我能看到的品牌列表","originalQuestion":"查询我能看到的品牌列表"}'
-```
+## 环境变量
 
-#### `MCP error -32001: Request timed out`
+| 环境变量 | 必填 | 中文说明 | 默认值 |
+|-|-|-|-|
+| `SPONGE_MCP_BASE_URL` | 是 | Sponge MCP Server 地址 | `https://sponge-mcp.duliday.com` |
+| `SPONGE_MCP_ACCESS_TOKEN` | 是 | 身份透传 Token（令牌） | 无 |
 
-这是 **roll-core 调用子 Agent 的 MCP `tools/call` 默认 60 秒超时**（`@modelcontextprotocol/sdk` 的 `DEFAULT_REQUEST_TIMEOUT_MSEC`），不是 Sponge HTTP 客户端自己的 30 秒超时。
-`query_sponge` 会多次走 MCP Sampling（需求分析 / 实体抽取 / SQL 生成）再调 Sponge，整链路经常超过 60 秒，Windows 上网络或首次冷启动更明显。
+Agent 内置单次请求超时 58 秒、query（查询）总超时 59 秒、网络重试 2 次，无需额外配置。每个新问题生成新的 `requestId`（请求编号），仅网络重试复用该编号。总超时低于当前 Roll 的 60 秒固定限制。
 
-可先做这些排查：
+## 安全边界
 
-1. 先跑 `roll run octopus-agent diagnostic_status --json`，确认 `spongeMcp.accessTokenConfigured=true`、schema 缓存存在。
-2. 先跑一次 `refresh_schema`，避免查询时再拉大 schema。
-3. 确认本机到 `SPONGE_MCP_BASE_URL` 和 LLM provider 网络通畅。
-4. 若仍稳定在约 60 秒失败，需要 **升级 / 修复 roll-core**：让 `roll run` 对长耗时 tool（如 `query_sponge`）传入更大的 `callTool` `timeout`（当前 roll v0.15.0 未暴露该参数）。仅改本 Agent 的 `SPONGE_MCP` HTTP timeout 无法消除 `-32001`。
-
-指定输出格式：
-
-```bash
-roll run octopus-agent query_sponge --json \
-  --input-json '{"question":"查询我能看到的品牌列表","originalQuestion":"查询我能看到的品牌列表","resultFormat":"markdown"}'
-```
-
-支持 `text`、`json`、`yaml`、`md`、`markdown`、`html`。不传时会从问题里自动识别。
-
-调试 SQL：
-
-```bash
-roll run octopus-agent query_sponge --json \
-  --input-json '{"question":"查询我能看到的品牌列表","originalQuestion":"查询我能看到的品牌列表","includeSql":true}'
-```
-
-`includeSql=true` 时会返回 `generatedSql`、`normalizedSql`、`repairedSql` 和 `validation`。
-所有模式都会返回 `needsClarification`。当 `needsClarification=true` 时，上层 Agent 必须原样展示 `answer` 并等待用户确认，不得自行选择候选项或再次调用 `query_sponge`。
-默认 `requirePlanConfirmation=true`，`query_sponge` 会先返回查询计划：匹配到的表、字段、筛选条件和执行步骤。用户回复“确认”后，再继续生成、校验和执行 SQL；用户提出修改时，会按修改后的口径重新整理查询计划并再次确认。调试或内部直通场景可以显式传 `requirePlanConfirmation=false`。
-
-普通业务返回使用单 `content` 通道，透传约束改由结构化字段承载：
-
-- `content[0].text`：纯净业务答案，裸客户端可以直接展示。
-- `structuredContent.answer`：同样保存纯净业务答案，作为结构化兜底。
-- `structuredContent.responseMode=verbatim` 和 `structuredContent.finalAnswerOnly=true`：提示上层 Agent 应原样透传答案。约束只放在结构化字段，`content` 数组不再附带元指令文本，避免泄露给用户。
-
-### 查询链路规范
-
-一次完整查询链路先展示查询计划，再由 `validate_sql` 和 `execute_sql` 组成。`validate_sql` 和 `execute_sql` 两步必须使用同一个 `traceId`（链路 ID）。同一个用户问题、同一次分析上下文必须复用同一个 `sessionId`（会话 ID）。
-
-查询计划包含：
-
-- 查询表：来自 `get_schema` 的 schema 中文语义匹配结果。
-- 查询字段：确认后必须尽量出现在 SQL 的 `SELECT` 中。
-- 筛选条件：确认后必须尽量出现在 SQL 的 `WHERE` 中；名称类使用 `LIKE`，状态类使用 `schema.enums` 的枚举值。
-- 执行步骤：从上层调用、意图判断、口径确认、SQL 校验执行到结果渲染。
-
-最终答案顶部会先展示“查询字段”和“筛选条件”，再展示查询结果。
-
-如果执行成功但结果异常，例如 `rowCount=0`、关键字段大量为空、结果明显不符合预期，Agent 不应自动改口径再跑第二次完整链路。应先说明异常点、可能原因、建议口径和影响范围，等待用户确认后，再用新的 `traceId`、原 `sessionId` 发起新链路。
-
-如果只是 SQL 校验失败，可以修正 SQL 后重新校验；只要涉及业务口径变化，必须先确认。
-
-`package.json` 中声明了 roll-core 启动方式：
-
-```json
-{
-  "rollAgent": {
-    "runtime": {"ownership": "on-demand", "transport": "stdio"},
-    "start": {
-      "command": "node",
-      "args": ["scripts/start-octopus-agent.js"]
-    }
-  }
-}
-```
-
-环境变量可放到 `roll.config.yaml`：
-
-```yaml
-agents:
-  env:
-    octopus-agent:
-      SPONGE_MCP_BASE_URL: "https://sponge-mcp.duliday.com"
-      SPONGE_MCP_ACCESS_TOKEN: "xxxx"
-```
-
-`SPONGE_MCP_BASE_URL` 只填域名根地址，不要带 `/mcp/admin/health`；Agent 会调用 `/mcp/tools/...`。
-
-LLM 配置读取 roll-core 现有 `llm` 配置；Agent 不读取模型 API Key。
-`query_sponge` 会通过 MCP Sampling 请求 roll-core 代调模型。
-
-## 本地持久化
-
-- `data/sponge-schema-cache.json`：schema 缓存。
-- `data/sponge-clarification-cache.json`：短期确认缓存，保存品牌/项目候选和查询计划确认上下文，默认 10 分钟过期。
-- `logs/octopus-sponge-audit.log`：审计日志。
-
-不新建数据库，不保存真实项目 ID、品牌 ID、数据库账号密码。
-
-## 自测
-
-```bash
-PYTHONPATH=src python -m unittest discover -s tests
-```
+- Agent 只调用一次 `query_sponge`（查询 Sponge），不调用内部原子能力。
+- Agent 不接收或传入任意 SQL。
+- Agent 不读取 Schema，不调用 LLM，不硬编码业务判断。
+- 认证 Token 仅用于身份透传，数据权限由 Sponge MCP Server 校验。
+- 不新建数据库，不持久化 Schema、SQL 或查询结果。

package/SKILL.md

@@ -1,128 +1,52 @@
 ---
 name: octopus-agent
-description: 丸子Agent（Octopus Agent），把自然语言问题转换为只读 SQL，并通过 Sponge MCP Server 校验和执行。
+description: 丸子Agent（Octopus Agent），单次调用 Sponge MCP Server 完成自然语言数据查询。
 metadata:
   roll-env-file: references/env.yaml
 ---
 
 # 丸子Agent（Octopus Agent）
 
-## 职责
-
-本 Agent 只负责海绵数据查询：
-
-- 读取和刷新 Schema Cache（表结构缓存）。
-- 基于用户问题和 schema context，通过 MCP Sampling（采样）请求 roll-core 代调 LLM 生成只读 SQL。
-- 按 `get_schema`、`validate_sql`、`execute_sql` 三步调用 Sponge MCP Server。
-- 记录 Audit Log（审计日志）。
-
-## Tools
-
-| Tool | 中文解释 | 用途 |
-|-|-|-|
-| `diagnostic_status` | 诊断状态 | 检查配置、缓存和日志路径 |
-| `refresh_schema` | 刷新表结构 | 人工刷新本地 schema 缓存 |
-| `query_sponge` | 查询海绵数据 | 自然语言查询入口 |
-
-`refresh_schema` 必填 `traceId`；Agent 会自动读取本地缓存里的 `schemaVersion` 并传给 Sponge。
-
-`query_sponge` 支持 `resultFormat`：`text`、`json`、`yaml`、`md`、`markdown`、`html`。不传时按用户问题自动识别。
-`query_sponge` 不接收用户或设备标识；权限由 Sponge MCP Server 根据 `Authorization` token 解析。
-Agent 只生成业务 SQL，不生成 `:scope.project_ids`、`:scope.brand_ids` 等权限占位符。
-调试时可传 `includeSql=true` 返回 `generatedSql`、`normalizedSql`、`repairedSql` 和 `validation`；默认不返回 SQL。
-`query_sponge` 不需要用户确认查询计划。工具内部会按 schema 中文语义识别表、字段、筛选条件、枚举和实体，把 `search_entities` 的真实命中项固化进 queryPlan，然后直接生成、校验并执行 SQL，不会在任何节点停下来等待用户确认。
-`finalAnswerOnly` 默认是 `true`，并返回 `structuredContent.responseMode=verbatim`；上层 Agent 必须把 `content[0].text` 或 `structuredContent.answer` 原样作为最终用户可见答复，不要只放在可折叠工具步骤里，也不要改写成摘要。用户可见答复统一为三段式：`1. 查询实体`、`2. 筛选条件` 和 `3. 查询结果`。
-普通业务返回只带一个 `content` 项：`content[0].text` 是三段式用户可见答复。是否原样透传由 `structuredContent.responseMode=verbatim` 和 `finalAnswerOnly=true` 这两个结构化字段承载，不再在 `content` 里附带任何元指令文本，避免元指令泄露给用户。
-`search_entities` 只用于实体别称和模糊召回；品牌、项目等多个实体同时命中时不追问用户，queryPlan 会用同组 OR 条件承载，并在结果中展示各实体名称字段方便用户自行缩小范围。
-状态枚举不单独追问。用户明确提出状态条件时，把状态条件写入 SQL 的 WHERE；用户未提出状态条件或 schema 缺少枚举时，首次查询保持宽泛，但查询结果必须展示相关状态字段的中文含义。
-当 schema 完全匹配不到相关表时，`query_sponge` 会返回 `needsClarification=true`、`clarificationType=schema_no_match`。此时必须立即停止，原样展示 `structuredContent.answer` 给用户；这是"暂不支持该查询"的说明，不是查询计划确认，用户补充明确需求后重新发起查询即可。业务指标口径缺失等其它情况会直接返回普通 `answer`（`needsClarification=false`），上层原样展示即可。
-
-## 上层调用规则
-
-1. 用户只是说使用、启动、检查、看看丸子Agent，或确认 Agent 是否可用时，只调用 `diagnostic_status`，返回状态后停止；不得主动调用 `query_sponge`，不得编造示例业务问题。
-2. **首次安装或新环境**：先调用 `diagnostic_status`，再调用 `refresh_schema` 预热 schema 缓存；确认 token 与缓存正常后，再接受业务查询。
-3. 查询前如需排查环境，先调用 `diagnostic_status`。
-4. schema 过期或缺失时，调用 `refresh_schema`。
-5. 用户提出明确业务数据查询时，调用 `query_sponge`。
-6. 不要求上层提供真实项目 ID 或品牌 ID；权限由 Sponge MCP Server 处理。
-7. 权限范围由 Sponge MCP Server 在 `execute_sql` 阶段统一补全并记录。
-8. 不允许绕过本 Agent 直接连业务数据库。
-9. 运行参数由 Agent 内置；本地只通过环境变量配置 Sponge 地址和 Token。
-10. LLM 由 roll-core 通过 MCP Sampling 代调，本 Agent 不读取模型 API Key。
-11. 对“匹配效果”“分析报告”“找出报名多但入职少/在招多但报名少/候选人多但岗位少”等报告类问题，只能调用一次 `query_sponge` 处理完整原始问题，不要拆成多个品牌/项目/城市子查询。
-12. `query_sponge` 返回后，最终回复正文必须完整复制工具返回的 `answer`，不要只把报告放在执行命令、思考过程、工具详情或可折叠步骤里。
-13. 如果 `structuredContent.needsClarification=true`（`clarificationType=schema_no_match`），最终回复只能展示 `structuredContent.answer`；这是"暂不支持该查询"的说明，用户补充明确需求后重新发起查询即可。
-14. 品牌、项目等实体多候选由 queryPlan 的同组 OR 条件处理；上层不要要求用户先选择品牌或项目。
-15. 如果 `answer` 已包含分析报告，最终回复顺序必须保持：完整分析报告 -> 总结关键发现；不要自行改写成摘要替代报告。
+## Tool
 
-## 最终展示 few-shot
+`query`（自然语言查询）是唯一业务入口：
 
-上层 Agent 必须把 `query_sponge` 返回的 `content[0].text` 或 `structuredContent.answer` 原样展示给用户。不得总结、改写、删除表格、删除实体和筛选条件。
+- `question`：必填，本次用于分析的问题。
+- `resultFormat`：选填，结果格式，默认 markdown（Markdown 格式）。
 
-### 示例 1：保留实体和筛选条件
+## 调用边界
 
-用户：查询近一年门店的创建时间，根据每日创建时间计数门店个数，列出所有的门店数量和对应项目
+- 用户询问“介绍丸子”“丸子有什么功能”“怎么使用丸子”“丸子是否可用”等介绍、能力说明或使用方法时，只直接介绍，不调用 `query`（查询）。
+- 介绍场景禁止编造、发起或执行任何示例查询，也不要声称已经执行过查询。
+- 只有用户提出明确的业务数据查询问题时，才调用 `query`。
+- 用户没有给出明确查询对象和查询诉求时，先说明能力，不自行补充示例问题。
 
-工具返回：
-
-```text
-1. 查询实体：
-门店；项目
-
-2. 筛选条件：
-创建时间 >= 2025-07-07；创建时间 < 2026-07-08；按创建日期、项目统计门店数量
-
-3. 查询结果：
-返回 500 行。
-limited: true
-
-|序号|创建日期|项目名称|门店数量|
-|---|---|---|---|
-|1|2026-07-07|示例项目|12|
-```
-
-最终回复必须原样展示以上两段式内容；不要改写成“我已查询到近一年数据”，也不要删除第一段。
-
-### 示例 2：“所有/全部”不覆盖时间范围
-
-用户：查询近一年门店数据，列出所有项目
+## 职责
 
-正确理解：
+- 每个新问题生成新的 `requestId`（请求编号）。
+- 原样传入 `question`（问题），只调用一次 `query_sponge`（查询 Sponge）。
+- 成功时原样返回 `answer`（答案），失败时返回服务端错误。
+- 仅网络重试复用原 `requestId`，并控制总超时。
 
-- `近一年` 是时间范围，必须保留。
-- `所有` 是返回范围或导出诉求，不是取消时间范围。
-- 如果生成 CSV，也必须在两段式答复中保留实体和筛选条件后再展示文件路径。
+## 最终展示规则
 
-### 示例 3：工具返回表格时不得摘要替代
+上层 Agent 的最终答复必须完全等于 `content[0].text`。该内容带有 `audience: user`（面向用户）和最高优先级注解，禁止总结、删减、改写或重排。必须保留原始换行、Markdown 表格和以下顺序：
 
-错误回复：
+1. 查询实体
+2. 筛选条件
+3. 业务逻辑
+4. 查询结果
 
-```text
-我查到了门店数量最多的项目，结果如下……
-```
+不得先展示查询结果，也不得在四段内容前后添加分析性结论。
 
-正确回复：完整复制工具返回的 `content[0].text`，包括：
+Agent 不调用 LLM（大语言模型），不读取 Schema（表结构），不生成、修改或解析 SQL，不根据自然语言错误做业务判断。
 
-- `1. 查询实体`
-- `2. 筛选条件`
-- `3. 查询结果`
-- 完整表格或 CSV 文件路径说明
+## 查询链路
 
-## 查询链路规则
+`query → query_sponge → answer`（查询 → 查询 Sponge → 答案）
 
-1. 一次完整查询链路直接生成查询计划并执行 `validate_sql` 和 `execute_sql`，不需要用户确认查询计划；后两步必须使用同一个 `traceId`（链路 ID）。
-2. 同一个用户问题、同一次分析上下文必须复用同一个 `sessionId`（会话 ID）。
-3. 口径修正仍属于同一问题，继续复用原 `sessionId`，但使用新的 `traceId` 发起新链路。
-4. 如果 `execute_sql` 成功但结果异常，例如 `rowCount=0`、关键字段大量为空、结果明显不符合问题预期，不自动改口径重跑。
-5. 出现结果异常时，先向用户说明异常点、可能原因、建议口径和影响范围，等待用户确认后再用新口径查询。
-6. 如果只是 SQL 校验失败，可以修正 SQL 后重新校验；涉及业务口径变化时必须先确认。
-7. `originalQuestion` 只传**当前这一轮**用户原话，不要把同一会话里上一轮问题拼进来；`sessionId` 仅用于 MCP 审计，**不会**自动继承上一轮的项目/品牌/门店筛选。
-8. 用户从「查岗位列表」转为「查操作日志 / 算历史在招数」等新问题时，仍复用 `sessionId` 即可，但 `originalQuestion` 必须是新问题本身，例如「你得查岗位上下架操作日志，给我算一下6月21日有多少在招岗位」。
-9. 品牌/项目等多实体命中不追问用户；Agent 会在查询计划中生成同组 OR 条件并直接执行，结果中展示各实体名称字段方便用户自行缩小范围。
+Agent 不追问、不生成或修复 SQL（结构化查询语言），也不调用服务端内部原子能力。
 
 ## 持久化
 
-- `data/sponge-schema-cache.json`：Schema Cache（表结构缓存）。
-- `logs/octopus-sponge-audit.log`：Audit Log（审计日志）。
-
-不新建数据库，不保存真实项目 ID、品牌 ID、数据库账号密码。
+不新建数据库，不缓存 Schema、SQL 或查询结果。链路状态仅保存在单次调用内存中。

package/package.json

@@ -1,27 +1,23 @@
 {
   "name": "@roll-agent/octopus-agent",
-  "version": "0.1.3",
-  "description": "丸子Agent（Octopus Agent）",
+  "version": "0.2.0",
+  "description": "Octopus Agent：编排 Sponge MCP Server 的 NL2SQL 查询链路",
+  "type": "module",
   "license": "UNLICENSED",
-  "keywords": [
-    "roll-agent",
-    "mcp",
-    "nl2sql"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
   "files": [
-    "octopus_skill",
     "src",
     "scripts",
     "references",
     "SKILL.md",
-    "pyproject.toml",
-    "!**/__pycache__/**",
-    "!**/*.pyc",
-    "!**/*.egg-info/**"
+    "README.md"
   ],
+  "scripts": {
+    "start": "node scripts/start-octopus-agent.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "rollAgent": {
     "runtime": {
       "ownership": "on-demand",
@@ -29,9 +25,7 @@
     },
     "start": {
       "command": "node",
-      "args": [
-        "scripts/start-octopus-agent.js"
-      ]
+      "args": ["scripts/start-octopus-agent.js"]
     }
   }
 }

package/references/env.yaml

@@ -5,25 +5,4 @@ env:
     example: https://sponge-mcp.duliday.com
   SPONGE_MCP_ACCESS_TOKEN:
     required: true
-    purpose: Sponge MCP Server 固定访问 Token
-  OCTOPUS_BINDING_SHADOW:
-    required: false
-    purpose: >-
-      实体识别(binding)总开关。false(默认)=识别结果注入 LLM prompt 影响 SQL;
-      true=仅计算并写审计日志(entity_binding_shadow),不改变 SQL 生成(用于回滚观察)。
-    example: "false"
-  OCTOPUS_BINDING_ENABLED:
-    required: false
-    purpose: >-
-      哪些实体类型的识别结果允许注入 prompt,逗号分隔,可选值 brand,location,project。
-      默认 brand,location,project(全开)。仅在 OCTOPUS_BINDING_SHADOW=false 时生效;
-      显式设为空字符串可关闭全部类型。
-    example: brand,location,project
-  OCTOPUS_BINDING_MIN_SCORE:
-    required: false
-    purpose: 实体模糊匹配的最低分数阈值(0~1),低于该分数不视为命中。默认 0.6。
-    example: "0.6"
-  OCTOPUS_SAMPLING_MAX_TOKENS:
-    required: false
-    purpose: MCP sampling/createMessage 请求的 maxTokens（LLM 输出 token 上限）。默认 4096。
-    example: "4096"
+    purpose: 身份透传 Token（令牌）

package/scripts/start-octopus-agent.js

@@ -1,126 +1,2 @@
 #!/usr/bin/env node
-"use strict";
-
-const { spawn, spawnSync } = require("node:child_process");
-const path = require("node:path");
-
-const MIN_MAJOR = 3;
-const MIN_MINOR = 11;
-const VERSION_CHECK = [
-  "import sys",
-  `raise SystemExit(0 if sys.version_info >= (${MIN_MAJOR}, ${MIN_MINOR}) else 1)`,
-].join("; ");
-
-function splitCommand(value) {
-  const parts = [];
-  let current = "";
-  let quote = null;
-
-  for (let index = 0; index < value.length; index += 1) {
-    const char = value[index];
-    if ((char === '"' || char === "'") && quote === null) {
-      quote = char;
-      continue;
-    }
-    if (char === quote) {
-      quote = null;
-      continue;
-    }
-    if (/\s/.test(char) && quote === null) {
-      if (current) {
-        parts.push(current);
-        current = "";
-      }
-      continue;
-    }
-    current += char;
-  }
-
-  if (current) {
-    parts.push(current);
-  }
-  return parts;
-}
-
-function configuredCandidate() {
-  const value = process.env.OCTOPUS_PYTHON_COMMAND;
-  if (!value) {
-    return null;
-  }
-
-  const [command, ...args] = splitCommand(value);
-  if (!command) {
-    return null;
-  }
-  return { command, args, source: "OCTOPUS_PYTHON_COMMAND" };
-}
-
-function pythonCandidates() {
-  return [
-    configuredCandidate(),
-    { command: "python3", args: [], source: "python3" },
-    { command: "python", args: [], source: "python" },
-    { command: "py", args: ["-3.11"], source: "py -3.11" },
-    { command: "py", args: ["-3"], source: "py -3" },
-  ].filter(Boolean);
-}
-
-function isUsablePython(candidate) {
-  const result = spawnSync(candidate.command, [...candidate.args, "-c", VERSION_CHECK], {
-    encoding: "utf8",
-    stdio: "ignore",
-  });
-  return result.status === 0;
-}
-
-function findPython() {
-  return pythonCandidates().find(isUsablePython);
-}
-
-const python = findPython();
-if (!python) {
-  console.error(
-    [
-      `Octopus Agent requires Python ${MIN_MAJOR}.${MIN_MINOR}+.`,
-      "Install Python 3.11+ and make one of these commands available:",
-      "python3, python, py -3.11, py -3",
-      "Or set OCTOPUS_PYTHON_COMMAND to the Python command.",
-    ].join("\n")
-  );
-  process.exit(1);
-}
-
-const packageRoot = path.resolve(__dirname, "..");
-const PYTHON_BOOTSTRAP = [
-  "import runpy",
-  "import sys",
-  "from pathlib import Path",
-  "package_root = Path(sys.argv[1]).resolve()",
-  "sys.path.insert(0, str(package_root / 'src'))",
-  "sys.path.insert(0, str(package_root))",
-  "sys.argv = ['octopus_skill.octopus_run', *sys.argv[2:]]",
-  "runpy.run_module('octopus_skill.octopus_run', run_name='__main__', alter_sys=True)",
-].join("; ");
-
-const child = spawn(
-  python.command,
-  [...python.args, "-c", PYTHON_BOOTSTRAP, packageRoot, ...process.argv.slice(2)],
-  {
-    cwd: packageRoot,
-    stdio: "inherit",
-    windowsHide: true,
-  }
-);
-
-child.on("error", (error) => {
-  console.error(`Failed to start Python via ${python.source}: ${error.message}`);
-  process.exit(1);
-});
-
-child.on("exit", (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code ?? 0);
-});
+import "../src/server.js";

package/src/config.js

@@ -0,0 +1,13 @@
+const REQUEST_TIMEOUT_MS = 58_000;
+const TOTAL_TIMEOUT_MS = 59_000;
+const NETWORK_RETRIES = 2;
+
+export function loadConfig(env = process.env) {
+  return {
+    baseUrl: (env.SPONGE_MCP_BASE_URL || "https://sponge-mcp.duliday.com").replace(/\/+$/, ""),
+    accessToken: (env.SPONGE_MCP_ACCESS_TOKEN || "").trim(),
+    requestTimeoutMs: REQUEST_TIMEOUT_MS,
+    totalTimeoutMs: TOTAL_TIMEOUT_MS,
+    networkRetries: NETWORK_RETRIES,
+  };
+}

package/src/context.js

@@ -0,0 +1,5 @@
+import { randomUUID } from "node:crypto";
+
+export function createRequestId() {
+  return `req_${randomUUID()}`;
+}