@roll-agent/octopus-agent 0.0.11 → 0.1.1

package/README.md

@@ -75,10 +75,26 @@ roll run octopus-agent query_sponge --json \
 
 `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` 组成，两步必须使用同一个 `traceId`（链路 ID）。同一个用户问题、同一次分析上下文必须复用同一个 `sessionId`（会话 ID）。
+一次完整查询链路先展示查询计划，再由 `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` 发起新链路。
 
@@ -116,6 +132,7 @@ LLM 配置读取 roll-core 现有 `llm` 配置；Agent 不读取模型 API Key
 ## 本地持久化
 
 - `data/sponge-schema-cache.json`：schema 缓存。
+- `data/sponge-clarification-cache.json`：短期确认缓存，保存品牌/项目候选和查询计划确认上下文，默认 10 分钟过期。
 - `logs/octopus-sponge-audit.log`：审计日志。
 
 不新建数据库，不保存真实项目 ID、品牌 ID、数据库账号密码。

package/SKILL.md

@@ -30,53 +30,94 @@ metadata:
 `query_sponge` 不接收用户或设备标识；权限由 Sponge MCP Server 根据 `Authorization` token 解析。
 Agent 只生成业务 SQL，不生成 `:scope.project_ids`、`:scope.brand_ids` 等权限占位符。
 调试时可传 `includeSql=true` 返回 `generatedSql`、`normalizedSql`、`repairedSql` 和 `validation`；默认不返回 SQL。
-`finalAnswerOnly` 默认是 `true`，并返回 `structuredContent.responseMode=verbatim`；上层 Agent 必须把 `content[0].text` 或 `structuredContent.answer` 原样作为最终用户可见答复，不要只放在可折叠工具步骤里，也不要改写成摘要。
-当返回 `needsClarification=true` 时，必须立即停止，原样展示 `structuredContent.answer` 给用户并等待确认；用户未确认前不得再次调用 `query_sponge`，不得自行选择候选项，不得把品牌+地点拼成项目名。
-用户确认品牌/项目后，不要重新发现工具，不要调用 `diagnostic_status` 或 `refresh_schema`，不要解释 schema，不要自行判断“schema 不支持项目维度”。必须直接再次调用 `query_sponge`，并传 `clarificationSelection`。
-`clarificationSelection` 必须包含：`baseQuestion`（原始问题）、`entityType`（brand=品牌，project=项目）、`entityId`（候选实体 ID）、`entityName`（候选实体名称）。优先从上一轮 `structuredContent.clarificationContext` 和 `structuredContent.clarificationPayload` 取值。
-
-示例：
-
-```json
-{
-  "question": "项目",
-  "originalQuestion": "项目",
-  "clarificationSelection": {
-    "baseQuestion": "海绵系统上陈香贵上海有哪些岗位",
-    "entityType": "project",
-    "entityId": 768,
-    "entityName": "陈香贵"
-  }
-}
-```
+`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. 查询前如需排查环境，先调用 `diagnostic_status`。
-2. schema 过期或缺失时，调用 `refresh_schema`。
-3. 用户提出业务数据查询时，调用 `query_sponge`。
-4. 不要求上层提供真实项目 ID 或品牌 ID；权限由 Sponge MCP Server 处理。
-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. 如果 `structuredContent.needsClarification=true`，最终回复只能展示 `structuredContent.answer`，等待用户确认；用户未确认前不得二次查询。
-12. 用户确认品牌/项目后，必须直接带 `clarificationSelection` 再调用 `query_sponge`；不要重新发现工具、不要解释 schema、不要输出“schema 不支持项目维度”这类自行判断。
-13. 如果 `answer` 已包含分析报告，最终回复顺序必须保持：完整分析报告 -> 总结关键发现；不要自行改写成摘要替代报告。
+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` 已包含分析报告，最终回复顺序必须保持：完整分析报告 -> 总结关键发现；不要自行改写成摘要替代报告。
+
+## 最终展示 few-shot
+
+上层 Agent 必须把 `query_sponge` 返回的 `content[0].text` 或 `structuredContent.answer` 原样展示给用户。不得总结、改写、删除表格、删除实体和筛选条件。
+
+### 示例 1：保留实体和筛选条件
+
+用户：查询近一年门店的创建时间，根据每日创建时间计数门店个数，列出所有的门店数量和对应项目
+
+工具返回：
+
+```text
+1. 查询实体：
+门店；项目
+
+2. 筛选条件：
+创建时间 >= 2025-07-07；创建时间 < 2026-07-08；按创建日期、项目统计门店数量
+
+3. 查询结果：
+返回 500 行。
+limited: true
+
+|序号|创建日期|项目名称|门店数量|
+|---|---|---|---|
+|1|2026-07-07|示例项目|12|
+```
+
+最终回复必须原样展示以上两段式内容；不要改写成“我已查询到近一年数据”，也不要删除第一段。
+
+### 示例 2：“所有/全部”不覆盖时间范围
+
+用户：查询近一年门店数据，列出所有项目
+
+正确理解：
+
+- `近一年` 是时间范围，必须保留。
+- `所有` 是返回范围或导出诉求，不是取消时间范围。
+- 如果生成 CSV，也必须在两段式答复中保留实体和筛选条件后再展示文件路径。
+
+### 示例 3：工具返回表格时不得摘要替代
+
+错误回复：
+
+```text
+我查到了门店数量最多的项目，结果如下……
+```
+
+正确回复：完整复制工具返回的 `content[0].text`，包括：
+
+- `1. 查询实体`
+- `2. 筛选条件`
+- `3. 查询结果`
+- 完整表格或 CSV 文件路径说明
 
 ## 查询链路规则
 
-1. 一次完整查询链路是 `validate_sql` 后接 `execute_sql`；两步必须使用同一个 `traceId`（链路 ID）。
+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 审计与澄清续答，**不会**自动继承上一轮的项目/品牌/门店筛选。
+7. `originalQuestion` 只传**当前这一轮**用户原话，不要把同一会话里上一轮问题拼进来；`sessionId` 仅用于 MCP 审计，**不会**自动继承上一轮的项目/品牌/门店筛选。
 8. 用户从「查岗位列表」转为「查操作日志 / 算历史在招数」等新问题时，仍复用 `sessionId` 即可，但 `originalQuestion` 必须是新问题本身，例如「你得查岗位上下架操作日志，给我算一下6月21日有多少在招岗位」。
-9. 品牌/项目澄清续答与问题隔离不冲突：用户确认后必须带 `clarificationSelection` 再调 `query_sponge`；Agent 会把 `baseQuestion` 拼成 `…，按项目「xxx」(id: 941)查询` 这类完整问题，**不会**再对这类续答做子句隔离。
+9. 品牌/项目等多实体命中不追问用户；Agent 会在查询计划中生成同组 OR 条件并直接执行，结果中展示各实体名称字段方便用户自行缩小范围。
 
 ## 持久化
 

package/package.json

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

package/pyproject.toml

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

package/references/env.yaml

@@ -23,3 +23,7 @@ env:
     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"

package/src/octopus_skill/_version.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.0.11"
+__version__ = "0.1.1"