@roll-agent/octopus-agent 0.0.10 → 0.0.11

package/README.md

@@ -74,6 +74,7 @@ roll run octopus-agent query_sponge --json \
 ```
 
 `includeSql=true` 时会返回 `generatedSql`、`normalizedSql`、`repairedSql` 和 `validation`。
+所有模式都会返回 `needsClarification`。当 `needsClarification=true` 时，上层 Agent 必须原样展示 `answer` 并等待用户确认，不得自行选择候选项或再次调用 `query_sponge`。
 
 ### 查询链路规范
 

package/SKILL.md

@@ -30,6 +30,25 @@ 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": "陈香贵"
+  }
+}
+```
 
 ## 上层调用规则
 
@@ -43,7 +62,9 @@ Agent 只生成业务 SQL，不生成 `:scope.project_ids`、`:scope.brand_ids`
 8. LLM 由 roll-core 通过 MCP Sampling 代调，本 Agent 不读取模型 API Key。
 9. 对“匹配效果”“分析报告”“找出报名多但入职少/在招多但报名少/候选人多但岗位少”等报告类问题，只能调用一次 `query_sponge` 处理完整原始问题，不要拆成多个品牌/项目/城市子查询。
 10. `query_sponge` 返回后，最终回复正文必须完整复制工具返回的 `answer`，不要只把报告放在执行命令、思考过程、工具详情或可折叠步骤里。
-11. 如果 `answer` 已包含分析报告，最终回复顺序必须保持：完整分析报告 -> 总结关键发现；不要自行改写成摘要替代报告。
+11. 如果 `structuredContent.needsClarification=true`，最终回复只能展示 `structuredContent.answer`，等待用户确认；用户未确认前不得二次查询。
+12. 用户确认品牌/项目后，必须直接带 `clarificationSelection` 再调用 `query_sponge`；不要重新发现工具、不要解释 schema、不要输出“schema 不支持项目维度”这类自行判断。
+13. 如果 `answer` 已包含分析报告，最终回复顺序必须保持：完整分析报告 -> 总结关键发现；不要自行改写成摘要替代报告。
 
 ## 查询链路规则
 
@@ -53,6 +74,9 @@ Agent 只生成业务 SQL，不生成 `:scope.project_ids`、`:scope.brand_ids`
 4. 如果 `execute_sql` 成功但结果异常，例如 `rowCount=0`、关键字段大量为空、结果明显不符合问题预期，不自动改口径重跑。
 5. 出现结果异常时，先向用户说明异常点、可能原因、建议口径和影响范围，等待用户确认后再用新口径查询。
 6. 如果只是 SQL 校验失败，可以修正 SQL 后重新校验；涉及业务口径变化时必须先确认。
+7. `originalQuestion` 只传**当前这一轮**用户原话，不要把同一会话里上一轮问题拼进来；`sessionId` 仅用于 MCP 审计与澄清续答，**不会**自动继承上一轮的项目/品牌/门店筛选。
+8. 用户从「查岗位列表」转为「查操作日志 / 算历史在招数」等新问题时，仍复用 `sessionId` 即可，但 `originalQuestion` 必须是新问题本身，例如「你得查岗位上下架操作日志，给我算一下6月21日有多少在招岗位」。
+9. 品牌/项目澄清续答与问题隔离不冲突：用户确认后必须带 `clarificationSelection` 再调 `query_sponge`；Agent 会把 `baseQuestion` 拼成 `…，按项目「xxx」(id: 941)查询` 这类完整问题，**不会**再对这类续答做子句隔离。
 
 ## 持久化
 

package/package.json

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

package/pyproject.toml

@@ -1,10 +1,12 @@
 [project]
 name = "octopus-skill"
-version = "0.0.10"
+version = "0.0.11"
 description = "丸子Agent（Octopus Agent）"
 readme = "README.md"
 requires-python = ">=3.11"
-dependencies = []
+dependencies = [
+    "rapidfuzz>=3.0",
+]
 
 [project.scripts]
 octopus-agent = "octopus_skill.main:main"

package/references/env.yaml

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

package/scripts/refresh_dictionary.py

@@ -0,0 +1,67 @@
+"""One-off: refresh the entity dictionary cache via the MCP server.
+
+Replicates Agent._ensure_dictionary's refresh path: calls get_entity_dictionary
+with the configured entity_types and writes the snapshot to the cache file.
+"""
+from __future__ import annotations
+
+import sys
+
+from octopus_skill.config import load_config
+from octopus_skill.context import new_trace_id
+from octopus_skill.entity_dictionary import EntityDictionaryCache
+from octopus_skill.mcp_client import SpongeMcpClient
+
+
+def main() -> int:
+    config = load_config()
+    if config.dictionary is None:
+        print("dictionary config is None; nothing to refresh")
+        return 1
+
+    client = SpongeMcpClient(
+        base_url=config.sponge_mcp.base_url,
+        access_token=config.sponge_mcp.access_token,
+        timeout_ms=config.sponge_mcp.timeout_ms,
+    )
+    cache = EntityDictionaryCache(config.dictionary.cache_path)
+    cached = cache.load()
+    cached_version = (
+        str(cached.get("dictVersion")) if cached and cached.get("dictVersion") else None
+    )
+
+    print(f"base_url={config.sponge_mcp.base_url}")
+    print(f"token_set={bool(config.sponge_mcp.access_token)}")
+    print(f"cached_version={cached_version}")
+    print(f"entity_types={config.dictionary.entity_types}")
+
+    trace_id = new_trace_id("trace_dict")
+    response = client.get_entity_dictionary(
+        trace_id=trace_id,
+        dict_version=cached_version,
+        entity_types=config.dictionary.entity_types,
+    )
+
+    changed = response.get("changed")
+    print(f"response changed={changed} dictVersion={response.get('dictVersion')}")
+
+    if changed is False and cached is not None:
+        print("server reports no change; cache kept as-is")
+        return 0
+
+    if "entities" in response:
+        cache.save(response)
+        ent = response["entities"]
+        for key, value in ent.items():
+            items = value.get("items") if isinstance(value, dict) else None
+            n = len(items) if isinstance(items, list) else "n/a"
+            print(f"  saved {key}: items={n}")
+        print(f"cache written to {config.dictionary.cache_path}")
+        return 0
+
+    print("response had no 'entities'; cache not updated")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/verify_binding.py

@@ -0,0 +1,47 @@
+"""One-off: verify the brand/location/project binding chain end-to-end.
+
+Builds the resolver from the persisted dictionary cache (same path the agent
+uses) and runs bind_entities on a few real questions, printing what resolved.
+"""
+from __future__ import annotations
+
+import json
+
+from octopus_skill.config import load_config
+from octopus_skill.entity_binding import bind_entities
+from octopus_skill.entity_resolver import EntityResolver, load_geo_aliases
+
+
+def show(question: str, resolver: EntityResolver) -> None:
+    bindings = bind_entities(question, resolver)
+    print(f"\nQ: {question}")
+    print("  brands  :", [(e.id, e.canonical, e.matched_via) for e in bindings.brands])
+    print("  projects:", [(e.id, e.canonical, e.matched_via) for e in bindings.projects])
+    print(
+        "  location:",
+        {lvl: (e.id, e.canonical) for lvl, e in bindings.location.items()},
+    )
+
+
+def main() -> int:
+    config = load_config()
+    assert config.dictionary is not None
+    dictionary = json.loads(config.dictionary.cache_path.read_text(encoding="utf-8"))
+    geo = load_geo_aliases(config.dictionary.geo_alias_path)
+    resolver = EntityResolver.from_payload(dictionary, geo_aliases=geo)
+
+    print("dictVersion:", dictionary.get("dictVersion"))
+    for t in ("brand", "project", "city", "region", "province"):
+        idx = resolver.indexes.get(t)
+        print(f"  index {t}: {len(idx.items) if idx else 0} items")
+
+    # Real project names pulled from the refreshed dictionary.
+    show("西贝莜面村这个项目在上海有多少在招岗位", resolver)
+    show("查一下哈根达斯项目的情况", resolver)
+    show("北京肯德基项目最近招聘多少人", resolver)
+    show("CoCo都可茶饮在南京宝山的门店", resolver)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/octopus_skill/_version.py

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