@roll-agent/octopus-agent 0.1.2 → 0.1.3

package/README.md

@@ -28,7 +28,6 @@ python -m octopus_skill "查询我能看到的品牌列表"
 
 ```bash
 roll agent install @roll-agent/octopus-agent
-roll run octopus-agent diagnostic_status --json
 ```
 
 该 npm package（npm 包）直接包含 Python 源码；`roll agent install` 不会再从 PyPI 下载 `octopus-skill`。
@@ -41,6 +40,21 @@ 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` 成功后，再发起业务查询。
+
 ### 本地源码注册
 
 ```bash
@@ -49,19 +63,70 @@ 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 \
-  --question "查询我能看到的品牌列表"
+  --input-json '{"question":"查询我能看到的品牌列表","originalQuestion":"查询我能看到的品牌列表"}'
 ```
 
 `refresh_schema` 必填 `traceId`。Agent 会自动读取本地缓存里的 `schemaVersion` 并传给 Sponge。
-`query_sponge` 不接收用户或设备标识；Sponge MCP Server 会根据 `Authorization` token 解析用户权限。
+`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）
+
+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
+```
+
+若必须内联 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`
+
+这是 **roll-core 调用子 Agent 的 MCP `tools/call` 默认 60 秒超时**（`@modelcontextprotocol/sdk` 的 `DEFAULT_REQUEST_TIMEOUT_MSEC`），不是 Sponge HTTP 客户端自己的 30 秒超时。
+`query_sponge` 会多次走 MCP Sampling（需求分析 / 实体抽取 / SQL 生成）再调 Sponge，整链路经常超过 60 秒，Windows 上网络或首次冷启动更明显。
+
+可先做这些排查：
+
+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":"查询我能看到的品牌列表","resultFormat":"markdown"}'
+  --input-json '{"question":"查询我能看到的品牌列表","originalQuestion":"查询我能看到的品牌列表","resultFormat":"markdown"}'
 ```
 
 支持 `text`、`json`、`yaml`、`md`、`markdown`、`html`。不传时会从问题里自动识别。
@@ -70,7 +135,7 @@ roll run octopus-agent query_sponge --json \
 
 ```bash
 roll run octopus-agent query_sponge --json \
-  --input-json '{"question":"查询我能看到的品牌列表","includeSql":true}'
+  --input-json '{"question":"查询我能看到的品牌列表","originalQuestion":"查询我能看到的品牌列表","includeSql":true}'
 ```
 
 `includeSql=true` 时会返回 `generatedSql`、`normalizedSql`、`repairedSql` 和 `validation`。

package/SKILL.md

@@ -40,19 +40,20 @@ Agent 只生成业务 SQL，不生成 `:scope.project_ids`、`:scope.brand_ids`
 ## 上层调用规则
 
 1. 用户只是说使用、启动、检查、看看丸子Agent，或确认 Agent 是否可用时，只调用 `diagnostic_status`，返回状态后停止；不得主动调用 `query_sponge`，不得编造示例业务问题。
-2. 查询前如需排查环境，先调用 `diagnostic_status`。
-3. schema 过期或缺失时，调用 `refresh_schema`。
-4. 用户提出明确业务数据查询时，调用 `query_sponge`。
-5. 不要求上层提供真实项目 ID 或品牌 ID；权限由 Sponge MCP Server 处理。
-6. 权限范围由 Sponge MCP Server 在 `execute_sql` 阶段统一补全并记录。
-7. 不允许绕过本 Agent 直接连业务数据库。
-8. 运行参数由 Agent 内置；本地只通过环境变量配置 Sponge 地址和 Token。
-9. LLM 由 roll-core 通过 MCP Sampling 代调，本 Agent 不读取模型 API Key。
-10. 对“匹配效果”“分析报告”“找出报名多但入职少/在招多但报名少/候选人多但岗位少”等报告类问题，只能调用一次 `query_sponge` 处理完整原始问题，不要拆成多个品牌/项目/城市子查询。
-11. `query_sponge` 返回后，最终回复正文必须完整复制工具返回的 `answer`，不要只把报告放在执行命令、思考过程、工具详情或可折叠步骤里。
-12. 如果 `structuredContent.needsClarification=true`（`clarificationType=schema_no_match`），最终回复只能展示 `structuredContent.answer`；这是"暂不支持该查询"的说明，用户补充明确需求后重新发起查询即可。
-13. 品牌、项目等实体多候选由 queryPlan 的同组 OR 条件处理；上层不要要求用户先选择品牌或项目。
-14. 如果 `answer` 已包含分析报告，最终回复顺序必须保持：完整分析报告 -> 总结关键发现；不要自行改写成摘要替代报告。
+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` 已包含分析报告，最终回复顺序必须保持：完整分析报告 -> 总结关键发现；不要自行改写成摘要替代报告。
 
 ## 最终展示 few-shot
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/octopus-agent",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "丸子Agent（Octopus Agent）",
   "license": "UNLICENSED",
   "keywords": [

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "octopus-skill"
-version = "0.1.2"
+version = "0.1.3"
 description = "丸子Agent（Octopus Agent）"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/octopus_skill/_version.py

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