@roll-agent/octopus-agent 0.0.1 → 0.0.4

package/README.md

@@ -5,7 +5,7 @@
 ## 能力
 
 - Schema Cache（表结构缓存）：本地保存 Sponge 返回的 schema。
-- MCP Client（MCP 客户端）：调用 `get_schema`、`get_allowed_context`、`validate_sql`、`execute_sql`。
+- 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、执行摘要。
@@ -13,7 +13,7 @@
 ## 本地运行
 
 ```bash
-python -m octopus_sponge_skill "查询我能看到的品牌列表" --user-id 456
+python -m octopus_sponge_skill "查询我能看到的品牌列表"
 ```
 
 运行参数由 Agent 内置；用户本地只需要配置 Sponge MCP Server 地址和 Token。
@@ -40,32 +40,42 @@ roll run octopus-agent diagnostic_status --json
 roll agent add .
 roll run octopus-agent diagnostic_status --json
 roll run octopus-agent refresh_schema --json \
-  --input-json '{"traceId":"trace_schema_10001","refreshReason":"manual"}'
+  --input-json '{"traceId":"trace_schema_10001"}'
 roll run octopus-agent query_sponge --json \
-  --question "查询我能看到的品牌列表" \
-  --user-id 456
+  --question "查询我能看到的品牌列表"
 ```
 
 `refresh_schema` 必填 `traceId`。Agent 会自动读取本地缓存里的 `schemaVersion` 并传给 Sponge。
+`query_sponge` 不接收用户或设备标识；Sponge MCP Server 会根据 `Authorization` token 解析用户权限。
+Agent 只生成业务 SQL，不生成 `:scope.project_ids`、`:scope.brand_ids` 等权限占位符。
+权限范围由 Sponge MCP Server 在 `execute_sql` 阶段统一补全，并写入 `mcp_sql_records.scope_bindings`。
 
 指定输出格式：
 
 ```bash
 roll run octopus-agent query_sponge --json \
-  --input-json '{"question":"查询我能看到的品牌列表","userId":456,"resultFormat":"markdown"}'
+  --input-json '{"question":"查询我能看到的品牌列表","resultFormat":"markdown"}'
 ```
 
-支持 `text`、`yaml`、`md`、`markdown`、`html`。不传时会从问题里自动识别。
+支持 `text`、`json`、`yaml`、`md`、`markdown`、`html`。不传时会从问题里自动识别。
 
 调试 SQL：
 
 ```bash
 roll run octopus-agent query_sponge --json \
-  --input-json '{"question":"查询我能看到的品牌列表","userId":456,"includeSql":true}'
+  --input-json '{"question":"查询我能看到的品牌列表","includeSql":true}'
 ```
 
 `includeSql=true` 时会返回 `generatedSql`、`normalizedSql`、`repairedSql` 和 `validation`。
 
+### 查询链路规范
+
+一次完整查询链路由 `validate_sql` 和 `execute_sql` 组成，两步必须使用同一个 `traceId`（链路 ID）。同一个用户问题、同一次分析上下文必须复用同一个 `sessionId`（会话 ID）。
+
+如果执行成功但结果异常，例如 `rowCount=0`、关键字段大量为空、结果明显不符合预期，Agent 不应自动改口径再跑第二次完整链路。应先说明异常点、可能原因、建议口径和影响范围，等待用户确认后，再用新的 `traceId`、原 `sessionId` 发起新链路。
+
+如果只是 SQL 校验失败，可以修正 SQL 后重新校验；只要涉及业务口径变化，必须先确认。
+
 `package.json` 中声明了 roll-core 启动方式：
 
 ```json

package/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 - 读取和刷新 Schema Cache（表结构缓存）。
 - 基于用户问题和 schema context，通过 MCP Sampling（采样）请求 roll-core 代调 LLM 生成只读 SQL。
-- 调用 Sponge MCP Server 做权限上下文、SQL 校验和 SQL 执行。
+- 按 `get_schema`、`validate_sql`、`execute_sql` 三步调用 Sponge MCP Server。
 - 记录 Audit Log（审计日志）。
 
 ## Tools
@@ -26,7 +26,9 @@ metadata:
 
 `refresh_schema` 必填 `traceId`；Agent 会自动读取本地缓存里的 `schemaVersion` 并传给 Sponge。
 
-`query_sponge` 支持 `resultFormat`：`text`、`yaml`、`md`、`markdown`、`html`。不传时按用户问题自动识别。
+`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。
 
 ## 上层调用规则
@@ -35,9 +37,22 @@ metadata:
 2. schema 过期或缺失时，调用 `refresh_schema`。
 3. 用户提出业务数据查询时，调用 `query_sponge`。
 4. 不要求上层提供真实项目 ID 或品牌 ID；权限由 Sponge MCP Server 处理。
-5. 不允许绕过本 Agent 直接连业务数据库。
-6. 运行参数由 Agent 内置；本地只通过环境变量配置 Sponge 地址和 Token。
-7. LLM 由 roll-core 通过 MCP Sampling 代调，本 Agent 不读取模型 API Key。
+5. 权限范围由 Sponge MCP Server 在 `execute_sql` 阶段统一补全并记录。
+6. 不允许绕过本 Agent 直接连业务数据库。
+7. 运行参数由 Agent 内置；本地只通过环境变量配置 Sponge 地址和 Token。
+8. LLM 由 roll-core 通过 MCP Sampling 代调，本 Agent 不读取模型 API Key。
+9. 对“匹配效果”“分析报告”“找出报名多但入职少/在招多但报名少/候选人多但岗位少”等报告类问题，只能调用一次 `query_sponge` 处理完整原始问题，不要拆成多个品牌/项目/城市子查询。
+10. `query_sponge` 返回后，最终回复正文必须完整复制工具返回的 `answer`，不要只把报告放在执行命令、思考过程、工具详情或可折叠步骤里。
+11. 如果 `answer` 已包含分析报告，最终回复顺序必须保持：完整分析报告 -> 总结关键发现；不要自行改写成摘要替代报告。
+
+## 查询链路规则
+
+1. 一次完整查询链路是 `validate_sql` 后接 `execute_sql`；两步必须使用同一个 `traceId`（链路 ID）。
+2. 同一个用户问题、同一次分析上下文必须复用同一个 `sessionId`（会话 ID）。
+3. 口径修正仍属于同一问题，继续复用原 `sessionId`，但使用新的 `traceId` 发起新链路。
+4. 如果 `execute_sql` 成功但结果异常，例如 `rowCount=0`、关键字段大量为空、结果明显不符合问题预期，不自动改口径重跑。
+5. 出现结果异常时，先向用户说明异常点、可能原因、建议口径和影响范围，等待用户确认后再用新口径查询。
+6. 如果只是 SQL 校验失败，可以修正 SQL 后重新校验；涉及业务口径变化时必须先确认。
 
 ## 持久化
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/octopus-agent",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "Octopus Sponge NL2SQL Agent",
   "license": "UNLICENSED",
   "keywords": [

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "octopus-skill"
-version = "0.0.1"
+version = "0.0.4"
 description = "Octopus Sponge NL2SQL Agent"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/octopus_sponge_skill/_version.py

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