diff --git a/backend/app/auth/chat_policy.py b/backend/app/auth/chat_policy.py index 5811cad7..a4e96a35 100644 --- a/backend/app/auth/chat_policy.py +++ b/backend/app/auth/chat_policy.py @@ -4,13 +4,14 @@ start_run 先查来源和运行类别)。图本身再按这里收窄,理由是同一条:对 user 角色来说遮罩就是边界(A7 第 6 条),它能 碰的只有「读数据、整理、撰写」这一类,不能执行代码、不能调外部系统、不能写任何东西: -- 节点只许:输入、模型、Agent、报告、输出、知识库检索、数据整形、条件分支、口径卡、合并查询、调用工具。代码、协作、 +- 节点只许:输入、模型、Agent、报告、输出、知识库检索、数据整形、条件分支、口径卡、合并查询、分析卡、调用工具。代码、协作、 子工作流、循环、人工审批、记忆写入、校验、双盲复算、反方审稿一律不许——后几种不是危险,而是问数据用不到,多放一种 就多一处要单独核对遮罩的地方; - 工具(Agent 绑的、调用工具节点调的同一份白名单,engine/launch.tool_bindings 一并列出)只许数据源工具(db_query__ / db_schema__,查询结果按 MASK_RESULTS_OPTION 在工具边界遮)和只读的内置工具(计算、当前时间、JSON 取值、知识库检索、 - 记忆读取)。自定义工具、MCP、文件、网页、HTTP、代码执行、平台的写入能力(records_append 这类)一律不许;模板拼出来的 - 工具名({{ vars.tool }})发起时不知道是谁,也不许。调用工具节点放行的理由:它和 Agent 调同一个查询工具等价——同一个 + 记忆读取、分析)。分析工具不查库,只读本节点查过、在工具边界遮过的结果,遮罩列不当维度、度量(app/tools/analysis.py); + 分析卡读上游查询节点的快照,同一套遮罩。自定义工具、MCP、文件、网页、HTTP、代码执行、平台的写入能力(records_append + 这类)一律不许;模板拼出来的工具名({{ vars.tool }})发起时不知道是谁,也不许。调用工具节点放行的理由:它和 Agent 调同一个查询工具等价——同一个 ToolContext 带着遮罩、只读两个开关(engine/nodes/tools.py 的 _tool_ctx),参数由人写死反而比模型挑的更好核对; 周期看板、异常处置这些模板的取数节点就是它(个人应用和问数据同一份白名单,blueprints/personal.policy_problem); - 数据源查询一律只读:可写源上的写语句由守卫拒掉,不交给审批(api/runs.py、个人应用刷新、个人蓝图试运行给运行打上 @@ -28,11 +29,14 @@ from __future__ import annotations from typing import Any +from app.analysis.contract import TOOL_NAMES + #: 问数据运行里 user 角色能用的节点类型(engine/schema.py 的 NodeType 取值) CHAT_NODE_TYPES = frozenset({"input", "llm", "agent", "report", "output", "retrieve", "transform", "branch", - "metrics", "merge", "tool"}) -#: Agent 能绑的只读内置工具(tools/builtin/) -CHAT_BUILTIN_TOOLS = frozenset({"calculator", "current_time", "json_query", "kb_search", "memory_recall"}) + "metrics", "merge", "analysis", "tool"}) +#: Agent 能绑的只读内置工具(tools/builtin/):五个分析工具也在内(contract.TOOL_NAMES,不查库) +CHAT_BUILTIN_TOOLS = frozenset({"calculator", "current_time", "json_query", "kb_search", "memory_recall", + *TOOL_NAMES.values()}) #: 运行时改记忆范围、知识库的配置键(engine/nodes 的 ctx.cfg("memory_scope") / ctx.cfg("collection"),图级 defaults 同样生效) SCOPE_KEYS = ("memory_scope", "collection") SCOPE_REFUSED = "没有权限:使用者在问数据中不能指定记忆范围和知识库,使用的是管理员设好的默认值" @@ -90,7 +94,7 @@ def chat_graph_problem(graph: Any, *, where: str = "问数据") -> str | None: return f"没有权限:{who}的工具名由模板拼成,发起前无法确定是哪个工具,使用者在{where}中不能这样绑定工具" if not _tool_allowed(name): return (f"没有权限:{who}绑定了工具「{name}」。使用者在{where}中只能使用数据源查询和只读的内置工具" - "(计算、当前时间、JSON 取值、知识库检索、记忆读取)") + "(计算、当前时间、JSON 取值、知识库检索、记忆读取、分析)") return None diff --git a/backend/app/engine/nodes/llm.py b/backend/app/engine/nodes/llm.py index bf737196..7dff9e3f 100644 --- a/backend/app/engine/nodes/llm.py +++ b/backend/app/engine/nodes/llm.py @@ -10,6 +10,7 @@ from langchain_core.tools import BaseTool from langgraph.func import task from sqlalchemy import select +from app.analysis.contract import CallError, ledger_entry from app.core import artifact_store from app.core.config import settings from app.core.errors import describe_exception, not_configured, raw_detail @@ -49,6 +50,17 @@ from app.providers.factory import ( ) from app.engine.sql_problems import event_checks from app.data import catalog_view +from app.tools.analysis import ( + REFUSED_CODE as ANALYSIS_REFUSED, + SCOPE_KEY as ANALYSIS_SCOPE_KEY, + AnalysisScope, + call_error_text, + input_snapshot, + is_analysis_tool, + payload_of, + reply_text, + run_snapshot, +) from app.tools.datasource import QUERY_PREFIX, run_masks_results, run_reads_only, run_scope_fixed, run_versions from app.tools.registry import ( ToolArgsError, @@ -57,6 +69,7 @@ from app.tools.registry import ( args_model_of, build_tools, describe_args, + guides_text, prepare_args, ) from app.tools.trust import asks_trustable, ask_gate, call_policy, node_task, trust_key_of @@ -110,7 +123,10 @@ async def _load_skills(names: list[str]) -> str: return "# 适用的方法论\n\n" + "\n\n".join(blocks) -async def _build_messages(state: GraphState, ctx: NodeContext) -> list[BaseMessage]: +async def _build_messages(state: GraphState, ctx: NodeContext, tools: list[BaseTool] | None = None + ) -> list[BaseMessage]: + """发给模型的消息。tools 是这个节点绑定的工具:它们带的方法说明(ToolSpec.guide,如分析方法)接在 Skill 后面,同一份 + 只注入一次。模型调用节点没有工具,不注入;没有带说明的工具时 system 和以前一字不差。""" tctx = template_context(state) messages: list[BaseMessage] = [] @@ -121,6 +137,8 @@ async def _build_messages(state: GraphState, ctx: NodeContext) -> list[BaseMessa skill_text = await _load_skills(ctx.cfg("skills", []) or []) if skill_text: system_parts.append(skill_text) + if guide := guides_text(tools): + system_parts.append(guide) if system_parts: messages.append(SystemMessage(content="\n\n".join(system_parts))) @@ -328,7 +346,9 @@ async def run_llm(state: GraphState, ctx: NodeContext) -> dict[str, Any]: # -------------------------------------------------------------------------- -async def _resolve_tools(ctx: NodeContext, state: GraphState) -> list[BaseTool]: +async def _resolve_tools(ctx: NodeContext, state: GraphState, scope: AnalysisScope | None = None) -> list[BaseTool]: + """建这个节点绑的工具。scope 是本节点的分析容器(绑了分析工具才有):经 ToolContext.extra 交给分析工具,工具建在 + 查询之前,查一次往里放一次(_record_call)。""" names = ctx.cfg("tools", []) or [] # 遮罩、只读的运行:记忆范围、知识库只认运行定下的,模型在参数里挑的也不算(tools/registry.ToolContext.fixed_scope) fixed = run_scope_fixed(ctx.run) @@ -346,6 +366,7 @@ async def _resolve_tools(ctx: NodeContext, state: GraphState) -> list[BaseTool]: catalog_view=catalog_view.of_run(ctx.run), # 数据源工具运行中途补固定版本时经它留一条事件(tools/datasource.py 的 _pin_late) emit=ctx.emit, + extra={ANALYSIS_SCOPE_KEY: scope} if scope is not None else {}, ) async with SessionLocal() as session: try: @@ -425,14 +446,17 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: except ProviderNotConfigured as e: raise NodeError(ctx.node.id, not_configured(e)) from e - tools = await _resolve_tools(ctx, state) + # 绑了分析工具才建分析容器:本节点查过的结果、做过的分析都放在这里(app/tools/analysis.py),编号和交回模型的一致 + scope = (AnalysisScope(node_id=ctx.node.id, snapshot=run_snapshot(ctx.run)) + if any(is_analysis_tool(n) for n in ctx.cfg("tools", []) or []) else None) + tools = await _resolve_tools(ctx, state, scope) tool_map = {t.name: t for t in tools} # 默认串行:一轮只调一个工具,拿到结果再想下一步。并行更快,但一批工具 # 中间没有任何新的思考——第二个调用是照着"还没看到第一个结果"时的判断发出来的 parallel_tools = bool(ctx.cfg("parallel_tools", False)) model = bind_tools_safely(base_model, tools, parallel=parallel_tools) - messages = await _build_messages(state, ctx) + messages = await _build_messages(state, ctx, tools) # 护栏(engine/guards.py)。None 是升级前发起的运行:默认 12 步、没有别的护栏,和以前一样 guard = _guard(ctx, model_id) # 证据台账、工具结果前的编号、cite_fields:升级前发起的运行一样都不加(见 evidence.ledger_enabled) @@ -493,6 +517,10 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: # 到点就收回控制权,驱动的收尾在后台做完。模型拿到的是"等了多久、为什么放弃" content, ok = str(e), False extra = {"error": str(e), "timed_out": True} + except CallError as e: + # 分析调用写错了(列不存在、列被遮罩、分析次数用完……,细案 01 §8.1):不记结论、不进台账,原话交回模型照着改 + content, ok = call_error_text(e), False + extra = {"error": content[:300], "call_error": e.code} except Exception as e: # noqa: BLE001 - 工具失败要喂回模型,让它自己纠错 content = f"工具执行失败:{describe_exception(e)}" schema = args_model_of(tool) @@ -522,6 +550,8 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: query = query_entry_fields(content) if evidence_on and ok and is_platform_query(name) else None if query and not await snapshot_owned(query["artifact"], ctx.run.run_id, name): query = None + # 分析工具交回的结论工件:同查询快照,记进 tool.end(封存范围内),证据接口、时间线从这里认这一步的结论 + analysis = payload_of(content) if ok and is_analysis_tool(name) else None ctx.emit( EventType.TOOL_END if ok else EventType.TOOL_ERROR, tool=name, @@ -530,12 +560,18 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: preview=content[:2000], artifact=snapshot_id, **({"query_artifact": query["artifact"]} if query else {}), + **({"analysis_artifact": analysis["artifact"]} if analysis else {}), # 查询当时数据源的表结构快照:和查询快照一样落在封存范围内,证据接口从这里认它 **({"schema_artifact": query["schema_artifact"]} if query and query.get("schema_artifact") else {}), # 这次查询的 SQL 检查结果单独带上:preview 截到前 2000 个字符,checks 通常在截掉的那段里 **({"checks": checks} if ok and name.startswith(QUERY_PREFIX) and (checks := event_checks(content)) else {}), **extra, ) + if analysis is not None and analysis["result"].get("status") == "refused": + # 算不了是一条结论(照常交回模型、进台账),照实提醒一句。发在 task 里:重放取 checkpoint,不会再发一遍 + ctx.emit(EventType.LOG, level="warn", code=ANALYSIS_REFUSED, call_id=call_id, tool=name, + reason_code=analysis["result"].get("reason_code"), reason=analysis["result"].get("reason"), + message=f"{name} 没有做成:{analysis['result'].get('reason') or '原因未知'}") outcome: dict[str, Any] = {"content": content, "ok": ok, "duration_ms": elapsed} if evidence_on: outcome.update(snapshot=snapshot_id, query_artifact=query["artifact"] if query else None) @@ -731,7 +767,7 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: if evidence_on: # 编号只取决于 tool_step 的返回值(重放时取自 checkpoint),重放出来的还是这一套 content = _record_call(ctx.node.id, exec_no, call_id, name, args, outcome, record, - queries, entries) + queries, entries, scope) transcript.append(record) messages.append(ToolMessage(content=content, tool_call_id=call_id)) if guard: @@ -870,12 +906,16 @@ async def run_agent(state: GraphState, ctx: NodeContext) -> dict[str, Any]: def _record_call(node_id: str, exec_no: int, call_id: str, name: str, args: dict[str, Any], outcome: dict[str, Any], record: dict[str, Any], queries: list[dict[str, Any]], - entries: list[dict[str, Any]]) -> str: + entries: list[dict[str, Any]], scope: AnalysisScope | None = None) -> str: """把一次执行过的工具调用记进台账、调用记录和本节点的查询清单,返回给模型看的内容。 查库成功的结果前面加一行「【证据 Q1】」:模型在循环里就知道每次查询的编号,cite_fields 抽取时照这个编号写出处。编号只在本节点内有效;报告目录里的 Q1… 按全局台账另编,两边 靠工件 id 对应,不靠编号。 + + 绑了分析工具的节点(scope):每次查询另往分析容器里放一份输入快照(编号同上);分析工具交回的结论记一条 kind analysis + 的台账(contract.ledger_entry,带 call_id),编号 An,交回模型的换成「【分析 An】」那一段(app/tools/analysis.py)。 + 编号同样只取决于 tool_step 的返回值,重放出来的还是这一套。 """ content = outcome["content"] record["call_id"] = call_id @@ -884,6 +924,15 @@ def _record_call(node_id: str, exec_no: int, call_id: str, name: str, args: dict record["via"] = snapshot entries.append({"kind": "tool", "node_id": node_id, "exec": exec_no, "artifact": snapshot, "call_id": call_id, "tool": name}) + if scope is not None and outcome.get("ok") and is_analysis_tool(name): + found = payload_of(content) + if found is None: + return content + alias = scope.add_result(found["result"], found["artifact"]) + record.update(alias=alias, analysis_artifact=found["artifact"]) + entries.append(ledger_entry(found["result"], node_id=node_id, exec_no=exec_no, artifact=found["artifact"], + call_id=call_id)) + return reply_text(alias, found["result"]) if not artifact or not is_platform_query(name): return content try: @@ -909,6 +958,8 @@ def _record_call(node_id: str, exec_no: int, call_id: str, name: str, args: dict queries.append({"alias": alias, "call_id": call_id, "tool": name, "sql": str(args.get("sql") or ""), "artifact": artifact, "via": snapshot, "columns": fields["columns"], "rows": data.get("rows") or [], "truncated": fields["truncated"]}) + if scope is not None: + scope.add_query(alias, input_snapshot(data, ref=alias, artifact=artifact, node_id=node_id)) return f"【证据 {alias}】\n{content}" diff --git a/backend/app/engine/nodes/multi.py b/backend/app/engine/nodes/multi.py index f3ff3002..da37a869 100644 --- a/backend/app/engine/nodes/multi.py +++ b/backend/app/engine/nodes/multi.py @@ -9,6 +9,7 @@ from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, Tool from langgraph.errors import GraphRecursionError from langgraph.func import task +from app.analysis.contract import CallError from app.core.config import settings from app.core.errors import describe_exception, raw_detail from app.core.events import EventType @@ -32,12 +33,24 @@ from app.providers import catalog from app.providers.factory import ModelSpec, bind_tools_safely, get_chat_model from app.engine.sql_problems import event_checks from app.data import catalog_view +from app.tools.analysis import ( + REFUSED_CODE as ANALYSIS_REFUSED, + SCOPE_KEY as ANALYSIS_SCOPE_KEY, + AnalysisScope, + call_error_text, + input_snapshot, + is_analysis_tool, + payload_of, + reply_text, + run_snapshot, +) from app.tools.datasource import QUERY_PREFIX, run_masks_results, run_reads_only, run_scope_fixed, run_versions from app.tools.registry import ( ToolArgsError, ToolContext, args_model_of, build_tools, + guides_text, prepare_args, ) from app.tools.trust import ask_gate, call_policy @@ -302,6 +315,10 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: async def _member(name: str, instruction: str, progress: str, tally: dict[str, Any]) -> dict[str, Any]: cfg = agent_map[name] + # 绑了分析工具的成员:这一次执行自己的分析容器(同 Agent 节点)。查询结果照 Agent 的写法编成「【证据 Qn】」,分析结论 + # 编成「【分析 An】」;协作节点不记证据台账,这些编号只给成员自己接着分析、下钻用 + scope = (AnalysisScope(node_id=ctx.node.id, snapshot=run_snapshot(ctx.run)) + if any(is_analysis_tool(t) for t in cfg.get("tools", []) or []) else None) async with SessionLocal() as session: model, model_id = await get_chat_model( session, @@ -325,13 +342,17 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: catalog_view=catalog_view.of_run(ctx.run), # 数据源工具运行中途补固定版本时经它留一条事件(tools/datasource.py 的 _pin_late) emit=ctx.emit, + extra={ANALYSIS_SCOPE_KEY: scope} if scope is not None else {}, ) tools = await build_tools(cfg.get("tools", []) or [], tool_ctx, session=session) bound = bind_tools_safely(model, tools, parallel=False) tool_map = {t.name: t for t in tools} + # 绑定的工具带的方法说明(分析方法)接在成员的 system 后面,同一份只注入一次(同 Agent 节点的 _build_messages) + guide = guides_text(tools) + system = cfg.get("system") or f"你是 {name}。" messages: list[Any] = [ - SystemMessage(content=cfg.get("system") or f"你是 {name}。"), + SystemMessage(content=f"{system}\n\n{guide}" if guide else system), HumanMessage(content=f"团队目标:{goal}\n\n已有进展:\n{progress or '(无)'}\n\n你的任务:{instruction}"), ] calls: list[dict[str, Any]] = [] @@ -426,16 +447,29 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: except ToolTimeout as e: content = str(e) failure = {"error": content, "timed_out": True} + except CallError as e: + # 分析调用写错了:不记结论,原话交回成员照着改(同 Agent 节点) + content = call_error_text(e) + failure = {"error": content[:300], "call_error": e.code} except Exception as e: # noqa: BLE001 content = f"工具失败:{describe_exception(e)}" failure = {"error": content, "detail": raw_detail(e)} # 查库的 SQL 检查结果单独带上:preview 截到前 1500 个字符,checks 通常在截掉的那段里 checks = event_checks(content) if not failure and tname.startswith(QUERY_PREFIX) else [] + analysis = payload_of(content) if scope is not None and not failure and is_analysis_tool(tname) else None ctx.emit(EventType.TOOL_ERROR if failure else EventType.TOOL_END, tool=tname, agent=name, call_id=cid, preview=content[:1500], duration_ms=int((time.perf_counter() - started) * 1000), **failure, - **({"checks": checks} if checks else {})) + **({"checks": checks} if checks else {}), + **({"analysis_artifact": analysis["artifact"]} if analysis else {})) + if analysis is not None and analysis["result"].get("status") == "refused": + ctx.emit(EventType.LOG, level="warn", code=ANALYSIS_REFUSED, agent=name, call_id=cid, tool=tname, + reason_code=analysis["result"].get("reason_code"), + reason=analysis["result"].get("reason"), + message=f"{name} 的 {tname} 没有做成:{analysis['result'].get('reason') or '原因未知'}") calls.append({"tool": tname, "args": targs, "result": content[:2000]}) + if scope is not None and not failure and tname in tool_map: + content = await _numbered(scope, tname, content, analysis, ctx.run.run_id, ctx.node.id) messages.append(ToolMessage(content=content, tool_call_id=cid)) # 步数用完了:最后一步一定是要了工具的,模型从没拿到过"说结论"的那一轮。 @@ -611,6 +645,25 @@ async def run_supervisor(state: GraphState, ctx: NodeContext) -> dict[str, Any]: return updates +async def _numbered(scope: AnalysisScope, tool: str, content: str, analysis: dict[str, Any] | None, run_id: str, + node_id: str) -> str: + """绑了分析工具的协作成员:一次成功的工具调用交回成员的内容。数据源查询(平台执行的,端点读取另核工件是这次运行落下 + 的)编号「【证据 Qn】」并放进分析容器;分析结论编号「【分析 An】」、换成给模型看的那一段。别的工具原样。""" + from app.capabilities.registry import is_platform_query, snapshot_owned + from app.engine.evidence import query_entry_fields + + if analysis is not None: + return reply_text(scope.add_result(analysis["result"], analysis["artifact"]), analysis["result"]) + if not is_platform_query(tool): + return content + fields = query_entry_fields(content) + if fields is None or not await snapshot_owned(fields["artifact"], run_id, tool): + return content + alias = f"Q{len(scope.queries) + 1}" + scope.add_query(alias, input_snapshot(json.loads(content), ref=alias, artifact=fields["artifact"], node_id=node_id)) + return f"【证据 {alias}】\n{content}" + + # -------------------------------------------------------------------------- # 子图:把另一张工作流当成一个节点 # -------------------------------------------------------------------------- diff --git a/backend/app/engine/schema.py b/backend/app/engine/schema.py index 9adf1440..e6e439da 100644 --- a/backend/app/engine/schema.py +++ b/backend/app/engine/schema.py @@ -561,6 +561,13 @@ def _check_dual_check(node: GraphNode, spec: GraphSpec, result: ValidationResult "definitions", "dual_check.definitions_invalid") +def _analysis_tools() -> frozenset[str]: + """五个分析工具的名字(contract.TOOL_NAMES)。""" + from app.analysis.contract import TOOL_NAMES + + return frozenset(TOOL_NAMES.values()) + + def _produces_query(node: GraphNode) -> bool: """这个节点的产出是一份存成快照的查询结果:调用数据库查询工具的「调用工具」节点,或另一个合并查询。""" if node.type == NodeType.MERGE: @@ -938,6 +945,10 @@ def validate_graph(spec: GraphSpec) -> ValidationResult: elif node.type == NodeType.TOOL: if not cfg.get("tool"): result.add("「调用工具」节点还没有选择工具", node_id=node.id, field="tool") + elif str(cfg.get("tool")).strip() in _analysis_tools(): + # 分析工具读的是同一个 Agent 查过的结果(【证据 Qn】),调用工具节点里没有这份容器,运行到这里一定失败 + result.add("「调用工具」节点不能调用分析工具:分析工具分析的是同一个 Agent 查过的结果。模板里要固定做的分析," + "请改用「分析卡」节点", node_id=node.id, field="tool", code="analysis.tool_node") # 写入动作的确认派给谁(应用平台 §3.8):写法同人工节点 from app.engine.lint_process import assignee_problem diff --git a/backend/app/tools/analysis.py b/backend/app/tools/analysis.py new file mode 100644 index 00000000..a969a0e3 --- /dev/null +++ b/backend/app/tools/analysis.py @@ -0,0 +1,397 @@ +"""分析的入口共用的运行期部分(docs/design/analysis-round/00-总方案.md §3.2、§3.4、§3.10)。 + +两个入口——agent 分析工具(tools/builtin/analysis.py)、分析卡(engine/nodes/analysis.py)——和口径卡的可比性检查 +(engine/nodes/metrics.py)都经这里取阈值、拼算子要的运行期依赖、认遮罩列、把结论落成工件,算子只经 app.analysis.run +调用,不各自另起一套: + +- **本节点的查询容器**(AnalysisScope):agent 建工具早于查询(engine/nodes/llm.py),工具经 ToolContext.extra[SCOPE_KEY] + 拿到这个可变容器。节点每记一次查询往里放一份输入快照(编号和交回模型的「【证据 Qn】」同一个),每记一份分析结论往里 + 放一份(编号 An,下钻的 parent 按它找上一层)。只在记台账的地方往里放:工具调用在 @task 里,重放时不执行,记台账的 + 那一步按 checkpoint 里的结果照样放一遍,编号还是同一套。 +- **阈值**:发起时的快照(run.options["analysis"],engine/launch.py)← 分析卡上写的覆盖;没有快照的现读设置。agent 改不了: + 分析工具的参数里没有阈值(契约 D4)。 +- **运行期依赖**(contract.Context):运行当天(服务端时区)、现查表的日期范围(W1-a 的 make_prober,没有这个模块时不给)、 + 数据目录(按运行的目录视图读,和 db_schema 给模型看的同一份)、剖析事实。 +- **遮罩列**:数据源设的遮罩列、查询当时记下的、按 SQL 认出改了名字的(和证据面板、运行对比同一个函数,api/evidence 的 + _mask_sets 的 hidden,宁可多遮),加上遮罩运行里查询时就整列遮掉的。算子不拿它们当维度、度量。 +- **结论**:整份落成内容寻址的工件(contract.ARTIFACT_KIND),台账记 contract.ledger_entry;交回 agent 的是一段短的 + 「【分析 An】」加判定语、关键数、附带说明、算不了的原因。 +""" +from __future__ import annotations + +import json +import logging +from collections.abc import Iterable, Mapping +from dataclasses import dataclass, field +from datetime import date +from typing import Any + +from app.analysis import contract +from app.analysis.contract import AnalysisResult, CallError, InputSnapshot + +logger = logging.getLogger(__name__) + +#: ToolContext.extra 里放本节点分析容器(AnalysisScope)的键 +SCOPE_KEY = "analysis_scope" +#: 五个分析工具的名字(contract.TOOL_NAMES) +ANALYSIS_TOOLS = frozenset(contract.TOOL_NAMES.values()) +#: 交回 agent 的那一段开头的编号写法,和查询的「【证据 Qn】」一个样子 +REPLY_HEAD = "【分析 {alias}】" +#: 调用写错时交回 agent 的那句的开头:说清没有记成结论,下一步照着改 +CALL_ERROR_HEAD = "分析调用有误,没有记成结论:" +#: agent 写的「这次在验证什么」最多留多少字(只在证据面板显示,不进正文) +HYPOTHESIS_MAX = 300 +#: 一份分析算不了(status refused)时那条提醒的 code(运行日志):两个入口同一个。复核信号按它认(engine/review.py 的 +#: WARN_CODES,第 2 波登记) +REFUSED_CODE = "analysis_refused" + + +def is_analysis_tool(name: Any) -> bool: + return isinstance(name, str) and name.strip() in ANALYSIS_TOOLS + + +def call_error_text(error: CallError) -> str: + """调用写错(contract.CallError)交回模型的那句:不记结论、不进台账,模型照着 message 改了再调。""" + return f"{CALL_ERROR_HEAD}{error.message}" + + +# -------------------------------------------------------------------------- +# 本节点的查询容器 +# -------------------------------------------------------------------------- + + +@dataclass +class AnalysisScope: + """一次节点执行里分析工具读的容器(agent 节点、协作成员的一次执行各一个)。 + + queries:编号 Qn → 输入快照(contract.InputSnapshot,masked 留空,用到时由 prepare 补)。results:编号 An → 整份 + 结论;artifacts:An → 结论的工件 id。snapshot:发起时的分析设置快照(没有为 None,现读设置)。mask_cache:快照工件 → + 遮罩列;source_cache:数据源和表 → 目录、剖析事实(一次节点执行里各读一次,只在工具执行时用,不影响编号)。""" + + node_id: str + snapshot: dict[str, Any] | None = None + queries: dict[str, InputSnapshot] = field(default_factory=dict) + results: dict[str, AnalysisResult] = field(default_factory=dict) + artifacts: dict[str, str] = field(default_factory=dict) + mask_cache: dict[str, list[str]] = field(default_factory=dict) + source_cache: dict[str, Any] = field(default_factory=dict) + + def add_query(self, alias: str, snapshot: InputSnapshot) -> None: + self.queries[alias] = snapshot + + def add_result(self, result: AnalysisResult, artifact: str) -> str: + """记一份结论,返回它在本节点的编号(A1、A2……,按记下的先后)。""" + alias = f"{contract.CATALOG_PREFIX}{len(self.results) + 1}" + self.results[alias] = result + self.artifacts[alias] = artifact + return alias + + def resolve(self, name: str) -> InputSnapshot | None: + return self.queries.get(str(name).strip()) + + def parent(self, name: str) -> AnalysisResult | None: + return self.results.get(str(name).strip()) + + +def scope_of(extra: Mapping[str, Any] | None) -> AnalysisScope | None: + scope = (extra or {}).get(SCOPE_KEY) + return scope if isinstance(scope, AnalysisScope) else None + + +# -------------------------------------------------------------------------- +# 阈值 +# -------------------------------------------------------------------------- + + +def run_snapshot(run_ctx: Any) -> dict[str, Any] | None: + """这次运行发起时快照的分析设置(run.options["analysis"],engine/launch.py 写,runner 放进 RunContext.extra 的 + run_options)。没有快照(图里本来没有分析、不经 launch_run 发起的)为 None。""" + from app.engine.runner import RUN_OPTIONS_KEY + + options = (getattr(run_ctx, "extra", None) or {}).get(RUN_OPTIONS_KEY) + snapshot = options.get(contract.SETTINGS_KEY) if isinstance(options, dict) else None + return snapshot if isinstance(snapshot, dict) else None + + +async def settings_of(snapshot: Mapping[str, Any] | None, + overrides: Mapping[str, Any] | None = None) -> dict[str, Any]: + """这次分析实际用的阈值:缺省 ← 发起时的快照(没有就现读设置)← 分析卡上的覆盖(contract.effective_settings)。""" + if snapshot is None: + from app.api.settings import analysis_settings # 在这里导入:api.settings 导入了 engine 里的模块 + from app.db.base import SessionLocal + + async with SessionLocal() as session: + snapshot = await analysis_settings(session) + return contract.effective_settings(snapshot, overrides) + + +# -------------------------------------------------------------------------- +# 输入快照与遮罩列 +# -------------------------------------------------------------------------- + + +def input_snapshot(content: Mapping[str, Any], *, ref: str, artifact: str, node_id: str) -> InputSnapshot: + """一份查询快照(数据源查询工具交回的、工件库里的)→ 算子的一份输入(masked 留空,prepare 时补)。列的类型对齐成和 + columns 同序的列表(快照里记的是 {列: 类型},没记的为 None);行一律写成和 columns 同序的列表。""" + columns = [str(c) for c in content.get("columns") or []] + types = content.get("column_types") + rows: list[list[Any]] = [] + for row in content.get("rows") or []: + if isinstance(row, (list, tuple)): + rows.append(list(row)) + elif isinstance(row, Mapping): + rows.append([row.get(c) for c in columns]) + else: + rows.append([row]) + return { + "ref": ref, "artifact": artifact, "node_id": node_id, "source": str(content.get("source") or ""), + "sql": str(content.get("sql") or ""), "columns": columns, + "column_types": [types.get(c) if isinstance(types, Mapping) else None for c in columns], + "rows": rows, "truncated": bool(content.get("truncated")), "masked": [], + } + + +async def masked_of(content: Mapping[str, Any] | None, artifact: str | None) -> list[str]: + """一份查询快照里不能当维度、度量的列(小写):结果里取自遮罩列的列按快照的列序在前,其余遮罩列名在后。 + + 认法和证据面板查询步骤、运行对比同一个函数(api/evidence 的 _mask_sets 的 hidden:查询当时记下的加数据源现在设的, + SQL 里给遮罩列起了别名、套了函数的结果列也算,SQL 认不准时整份的列都算,合并查询按它的来历认)。遮罩运行 + (mask_results)里查询时就遮掉的列(masked_at_query、整份遮的 masked_whole)格子里已经是「已遮罩」,一并算上。""" + from app.api.evidence import _Masks # 在这里导入:api.evidence 导入了 engine 里的模块 + + if not isinstance(content, Mapping): + return [] + hidden = set((await _Masks().sets(artifact, content.get("source"), dict(content))).hidden) + columns = [str(c) for c in content.get("columns") or []] + hidden |= {str(c).lower() for c in content.get("masked_at_query") or [] if isinstance(c, str)} + if content.get("masked_whole"): + hidden |= {c.lower() for c in columns} + shown = [c.lower() for c in columns if c.lower() in hidden] + return list(dict.fromkeys([*shown, *sorted(hidden - set(shown))])) + + +async def prepare(scope: AnalysisScope) -> None: + """补上容器里每份输入快照的遮罩列(每份工件只认一次)。快照取不回来、和哈希对不上的照实报错:查询明明交回过, + 分析读不到它的快照,不是 agent 写错了参数。""" + import asyncio + + from app.core import artifact_store + + for alias, snapshot in scope.queries.items(): + artifact = snapshot.get("artifact") or "" + if artifact not in scope.mask_cache: + try: + content = await asyncio.to_thread(artifact_store.load, artifact) + except ValueError as e: + raise RuntimeError(f"{alias} 的查询快照与哈希不一致,疑似被修改,不能分析") from e + if content is None: + raise RuntimeError(f"{alias} 的查询快照已不存在,不能分析") + scope.mask_cache[artifact] = await masked_of(content, artifact) + snapshot["masked"] = list(scope.mask_cache[artifact]) + + +# -------------------------------------------------------------------------- +# 运行期依赖:运行当天、目录、剖析事实、现查表范围 +# -------------------------------------------------------------------------- + + +def _tables_of(snapshots: Iterable[Mapping[str, Any]]) -> dict[str, set[str]]: + """数据源名 → 这几份快照的 SQL 里用到的表(evidence.sql_tables,去掉 schema 前缀前的写法)。合并查询不是数据源。""" + from app.engine.evidence import sql_tables + from app.engine.merge_query import MERGE_SOURCE + + out: dict[str, set[str]] = {} + for snap in snapshots: + name = str(snap.get("source") or "") + if not name or name == MERGE_SOURCE: + continue + try: + tables = sql_tables(str(snap.get("sql") or "")) + except Exception: # noqa: BLE001 - 认不出表就只是少给一点目录 + tables = [] + out.setdefault(name, set()).update(str(t) for t in tables) + return out + + +async def context_of(snapshots: Iterable[Mapping[str, Any]], *, tool_ctx: Any, + cache: dict[str, Any] | None = None) -> contract.Context: + """算子要的运行期依赖(contract.Context)。 + + - today:运行当天,服务端时区(算子据此判本期完不完整) + - catalogs:数据源名 → {表名: 这张表的目录(app/data/catalog 的 notes)},按运行的目录视图读(tool_ctx.catalog_view, + 和 db_schema 给模型看的、冻结进表结构快照的同一份),只给快照的 SQL 里用到的表 + - facts:数据源名 → {表名: 剖析事实(catalog_profile_jobs.last_facts)};上传表格的剖析不是这次查的那一版的不给 + - probe:现查一列的实际范围(W1-a 的 make_prober,按这次运行固定的数据版本解析数据源;没有这个模块时为 None) + + tool_ctx 是查询用的那个 ToolContext(固定的数据版本、目录视图都从它取)。cache 是调用方的缓存(同一个节点里分析 + 好几次,目录、剖析事实读一次)。读不到的源当没有:目录、剖析是附加说明,不能挡住分析。""" + cache = cache if cache is not None else {} + catalogs: dict[str, Any] = {} + facts: dict[str, Any] = {} + found: dict[str, Any] = {} + for name, tables in _tables_of(snapshots).items(): + key = f"{name}\n" + "\n".join(sorted(tables)) + if key not in cache: + cache[key] = await _source_context(name, tables, tool_ctx) + entry = cache[key] + if entry is None: + continue + found[name] = entry["source"] + catalogs[name], facts[name] = entry["catalog"], entry["facts"] + return {"today": date.today(), "probe": _prober(found, facts), "catalogs": catalogs, "facts": facts} + + +async def _source_context(name: str, tables: set[str], tool_ctx: Any) -> dict[str, Any] | None: + """一个数据源这几张表的目录、剖析事实,和查询用的那个源(探查用)。读不到为 None。""" + from app.data import catalog as data_catalog + from app.data import catalog_view + from app.data.catalog_profile_jobs import last_facts + from app.db.base import SessionLocal + from app.tools.datasource import resolved_source + + try: + resolved = await resolved_source(name, tool_ctx) + if resolved is None: + return None + row, source = resolved + entries = await catalog_view.read(catalog_view.CatalogView.parse(getattr(tool_ctx, "catalog_view", None)), row) + names = {data_catalog.resolve_table_name(getattr(source, "schema_cache", None), t) or t for t in tables} + async with SessionLocal() as session: + profiled = await last_facts(session, str(row.id), sorted(names)) if names else {} + except Exception: # noqa: BLE001 - 目录、剖析读不到当没有(目录视图指定的快照不在了另由查询工具照实报) + logger.warning("分析读取数据源 %s 的目录、剖析事实失败,这次不附", name, exc_info=True) + return None + snapshot = getattr(source, "snapshot_id", None) + return { + "source": source, + "catalog": {t: dict(entries[t].notes or {}) for t in sorted(names) if t in entries}, + # 上传表格:剖析时是另一版数据,范围对不上这次读的这一版(同 tools/datasource 的 _coverage) + "facts": {t: f for t, f in profiled.items() if not (snapshot and f.get("snapshot_id") != snapshot)}, + } + + +def _probe_factory() -> Any: + """W1-a 的 app.analysis.probe.make_prober;还没有这个模块时为 None(算子只用剖析事实,核对不了的写「核对不了」)。""" + try: + from app.analysis.probe import make_prober # type: ignore[import-not-found] + except ModuleNotFoundError as e: + if e.name not in ("app.analysis.probe", "app.analysis"): + raise + return None + return make_prober + + +def _prober(sources: Mapping[str, Any], facts: Mapping[str, Any]) -> contract.Prober | None: + """按数据源名分派的探查(contract.Prober)。每个源第一次被问到时才建它自己的探查: + + make_prober(查询用的源, masked=遮罩列, cache=coverage.Cache(), facts=按表取剖析事实的协程函数) + + 签名以 W1-a 的交付为准(合并时由编排者对齐这一处)。遮罩列上的不探(data/coverage 的规矩),探查失败由它自己退回 + 剖析事实。""" + make = _probe_factory() + if make is None or not sources: + return None + from app.data import coverage + from app.data.engine import masked_columns + + built: dict[str, Any] = {} + + async def probe(source: str, table: str, column: str) -> contract.Probe | None: + if source not in built: + obj = sources.get(source) + known = (facts.get(source) or {}) if isinstance(facts, Mapping) else {} + + async def by_table(name: str, known: Mapping[str, Any] = known) -> Mapping[str, Any] | None: + return known.get(name) + + built[source] = None if obj is None else make( + obj, masked=masked_columns(getattr(obj, "options", None)), cache=coverage.Cache(), facts=by_table) + found = built[source] + return await found(source, table, column) if found is not None else None + + return probe + + +def tool_context(run_ctx: Any, node_id: str, emit: Any = None) -> Any: + """分析卡、口径卡没有自己的 ToolContext:拼一个只用来解析数据源的(固定的数据版本、目录视图、遮罩、只读同运行)。 + 记忆范围、知识库用不着,不读节点配置。""" + from app.data import catalog_view + from app.tools.datasource import run_masks_results, run_reads_only, run_scope_fixed, run_versions + from app.tools.registry import ToolContext + + return ToolContext(run_id=run_ctx.run_id, node_id=node_id, sandbox_session=run_ctx.thread_id, + data_versions=run_versions(run_ctx), mask_results=run_masks_results(run_ctx), + force_readonly=run_reads_only(run_ctx), fixed_scope=run_scope_fixed(run_ctx), + catalog_view=catalog_view.of_run(run_ctx), emit=emit) + + +# -------------------------------------------------------------------------- +# 结论:落成工件、交回模型 +# -------------------------------------------------------------------------- + + +async def store(result: AnalysisResult, *, run_id: str, node_id: str) -> str: + """整份结论落成内容寻址的工件(contract.ARTIFACT_KIND)。复算、证据面板、导出都按这个 id 取回。""" + from app.core.artifact_store import put_json + + return await put_json(result, kind=contract.ARTIFACT_KIND, run_id=run_id, node_id=node_id, + meta={"op": result.get("op"), "status": result.get("status")}) + + +def payload_of(content: Any) -> dict[str, Any] | None: + """分析工具交回的 JSON(文本或对象)→ {artifact, result};不是一份分析结论的返回 None。""" + data = content + if isinstance(data, str): + if not data.lstrip().startswith("{"): + return None + try: + data = json.loads(data) + except ValueError: + return None + if not isinstance(data, dict): + return None + artifact, result = data.get("analysis_artifact"), data.get("result") + if not (isinstance(artifact, str) and artifact and isinstance(result, dict) and result.get("op") in contract.OPS): + return None + return {"artifact": artifact, "result": result} + + +def reply_text(alias: str, result: AnalysisResult) -> str: + """交回模型的那一段:「【分析 An】」加一个紧凑的 JSON——判定、判定语、判定标准、关键数、附带说明、算不了的原因、 + 结果表的前几段(列几段照结论里记的 table_top_k)。整份结论在工件里,模型要的是能接着往下做的那几样。""" + verdict = result.get("verdict") or {} + body: dict[str, Any] = {"status": result.get("status"), "op": result.get("op")} + if result.get("mode"): + body["mode"] = result.get("mode") + if result.get("status") == "ok": + body.update(verdict=verdict.get("code"), subjects=verdict.get("subjects") or [], + direction=verdict.get("direction")) + else: + body.update(reason_code=result.get("reason_code"), reason=result.get("reason")) + body["phrase"] = result.get("phrase") + if result.get("criterion"): + body["criterion"] = result.get("criterion") + if result.get("values"): + body["values"] = result.get("values") + if caveats := [c.get("text") for c in result.get("caveats") or [] if isinstance(c, dict) and c.get("text")]: + body["caveats"] = caveats + table = result.get("table") + if isinstance(table, dict) and table.get("rows"): + top = int((result.get("settings") or {}).get("table_top_k") or contract.DEFAULTS["table_top_k"]) + rows = list(table.get("rows") or []) + body["table"] = {"columns": table.get("columns"), "rows": rows[:top], + **({"more_rows": len(rows) - top} if len(rows) > top else {})} + return REPLY_HEAD.format(alias=alias) + "\n" + json.dumps(body, ensure_ascii=False, default=str) + + +def hypothesis_of(value: Any) -> str | None: + """agent(或模板作者)写的「这次在验证什么」:去掉首尾空白、截到 HYPOTHESIS_MAX 字;空的为 None。""" + text = str(value or "").strip() + return text[:HYPOTHESIS_MAX] if text else None + + +__all__ = [ + "ANALYSIS_TOOLS", "CALL_ERROR_HEAD", "REFUSED_CODE", "REPLY_HEAD", "SCOPE_KEY", "AnalysisScope", "call_error_text", "context_of", + "hypothesis_of", "input_snapshot", "is_analysis_tool", "masked_of", "payload_of", "prepare", "reply_text", + "run_snapshot", "scope_of", "settings_of", "store", "tool_context", +] diff --git a/backend/app/tools/builtin/__init__.py b/backend/app/tools/builtin/__init__.py index 313410d2..6c3f2551 100644 --- a/backend/app/tools/builtin/__init__.py +++ b/backend/app/tools/builtin/__init__.py @@ -1,5 +1,5 @@ """导入即注册。新增内置工具时在这里加一行。""" -from app.tools.builtin import code, data, files, knowledge, platform, web # noqa: F401 +from app.tools.builtin import analysis, code, data, files, knowledge, platform, web # noqa: F401 -__all__ = ["code", "data", "files", "knowledge", "platform", "web"] +__all__ = ["analysis", "code", "data", "files", "knowledge", "platform", "web"] diff --git a/backend/app/tools/builtin/analysis.py b/backend/app/tools/builtin/analysis.py new file mode 100644 index 00000000..830bbbea --- /dev/null +++ b/backend/app/tools/builtin/analysis.py @@ -0,0 +1,265 @@ +"""agent 分析工具(docs/design/analysis-round/00-总方案.md §3.2):变化拆解、波动基线、趋势、差异检验、可比性检查,一个算子 +一个工具(名字取 contract.TOOL_NAMES),参数各自聚焦,模型少写错。 + +- **参数只有「算什么」**:引用本节点查过的结果(query: "Q3",和交回模型的「【证据 Q3】」同一个编号)、列的角色、期次、 + 总数、上一层拆解、度量的叫法、这次在验证什么。没有任何阈值参数:阈值只来自设置快照(D4),模型不能把阈值调到想要的 + 结论。参数名写错、多写了参数,照别的工具一样交回「它接受什么」(registry.prepare_args)。 +- **调用写错**(contract.CallError:列不存在、列被遮罩、比率当可加、这个节点的分析次数用完……)不记结论,原话交回模型改; + **算不了**(历史不够、本期不完整、截断……)是一条结论,照样落成工件、进台账。 +- **方法说明**:五个工具共用一份「分析方法」(METHOD_GUIDE),绑了任一个就注入 system,同一份只注入一次。 +- 工具本身不查库:读的是本节点的查询容器(app/tools/analysis.AnalysisScope),能力登记里不认它们是查询 + (capabilities.registry.is_platform_query 只认数据源查询和声明了表格的端点读取)。 +""" +from __future__ import annotations + +from typing import Any, Literal + +from pydantic import BaseModel, Field + +from app.analysis import contract +from app.analysis.contract import CallError +from app.tools.registry import ToolContext, ToolGuide, register + +CATEGORY = "分析" + +#: 「分析方法」:五个分析工具共用,绑了任一个就注入 system(第一版,第 2 波定稿)。改了方法就改 id 里的版本号:评测的 +#: prompt_fingerprint 认得出提示词变了 +ANALYSIS_METHOD_PROMPT = """\ +# 分析方法(平台内置,用分析工具时照这个做) + +1. 先定现象:取本期和问题对应的基期,用 analysis_comparable 确认两期能直接比;历史够长(缺省至少 8 期)就用 analysis_baseline 放回历史看——是常规波动就照实说,不硬找原因。 +2. 指标是乘积或比率时,先用 analysis_decompose 的 factor、ratio 模式拆因子、拆结构。 +3. 按数据目录里的候选维度由粗到细拆(additive 模式),每次用 headline 给出总数核对拆开后是否闭合;找到主要来源再用 parent 下钻一层:下钻的 SQL 由你写(只查那一段),系统按上一层那一段的值核对闭合。 +4. 每次调用在 hypothesis 里写明这次在验证什么;拆了没发现集中也是结论,照实写。 +5. 不作因果断言:数据只说明变化来自哪里;原因要有知识库原话或输入作依据,否则写成待核实的推测。 +6. 阈值和方法由平台定,工具参数里没有阈值;算不了时照实说算不了的原因,不要换个说法硬下判断。 + +分析结论的编号「【分析 An】」只在本节点有效:下钻时 parent 写它(如 {"of": "A1", "key": ["华东"]})。判定语由系统写好了,结论里照它的意思说,不要改写判断的强弱。""" +METHOD_GUIDE = ToolGuide(id="analysis.method@1", text=ANALYSIS_METHOD_PROMPT) + +#: 交回 agent 的说法:这个节点里没有可分析的查询容器(调用工具节点、工具库试用、没记台账的老运行) +NO_SCOPE = ("分析工具只能由 Agent 在本节点查过数之后调用:它分析的是本节点交回过的查询结果(【证据 Qn】的编号)。" + "模板里要固定做的分析,请改用「分析卡」节点") +#: 交回 agent 的说法:本节点还没有成功的查询 +NO_QUERIES = "本节点还没有成功的查询可以分析:先用数据库查询工具查出要分析的数,再按交回的编号(Q1、Q2……)调用分析工具" +#: 这个节点的分析次数用完 +MAX_CALLS = ("这个节点已经做了 {done} 次分析,达到「{label}」的上限({limit} 次),不能再分析了。" + "请基于已有的分析结论给出结论,没查清的照实说") + +_QUERY = "要分析的查询结果:本节点交回过的编号,如 Q3(和「【证据 Q3】」同一个)" +_LABEL = "度量的叫法,系统写判定语时用(如「销售额」);不要写数字、百分号和单位,留空就用列名" +_HYPOTHESIS = "这次在验证什么,一句话(如「下降是不是集中在某个地区」):只在证据面板显示,不进报告正文" +_PERIOD = "期次列的列名(日期、周、月……)" +_GRAIN = "期次的粒度:day、week、month、quarter;留空按期次的写法推断" + + +class Headline(BaseModel): + """总数的两格:拆开后各段之和要分别等于它们(拆解闭合)。""" + + base: str = Field(description="基期总数那一格,写成「编号.r行号.列名」,如 Q1.r1.gmv(行号从 0 数)") + target: str = Field(description="本期总数那一格,如 Q1.r0.gmv") + + +class Parent(BaseModel): + """下钻:这一层是上一层拆解里某一段的拆解。""" + + of: str = Field(description="上一层拆解的编号,如 A1(「【分析 A1】」里的那个)") + key: list[str] = Field(description="上一层里要往下拆的那一段的维度值,一个维度一个值(如 华东)") + + +class DecomposeArgs(BaseModel): + mode: Literal["additive", "ratio", "factor"] = Field( + description="additive:可加的量(销售额、订单数)按维度算各段对总变化的贡献;ratio:比率(退款率、客单价)" + "拆成结构变化和各段自身的变化;factor:乘积(销售额 = 订单数 × 客单价)拆成各因子的贡献") + query: str | None = Field(default=None, description=_QUERY + ";这份结果里有期次列,用 base、target 指定比哪两期") + base_query: str | None = Field(default=None, + description="基期、本期是两份查询时:基期那份的编号(这时不写 query、period)") + target_query: str | None = Field(default=None, description="基期、本期是两份查询时:本期那份的编号") + by: list[str] | None = Field(default=None, description="维度列的列名,1 到 2 列(additive、ratio 用)") + period: str | None = Field(default=None, description=_PERIOD) + base: str | None = Field(default=None, description="基期:期次列里的一个值,如 2026-W41") + target: str | None = Field(default=None, description="本期:期次列里的一个值,如 2026-W42") + measure: str | None = Field(default=None, description="度量列(additive 用)") + numerator: str | None = Field(default=None, description="分子列(ratio 用,如退款单数)") + denominator: str | None = Field(default=None, description="分母列(ratio 用,如订单数)") + product: str | None = Field(default=None, description="乘积列(factor 用,如销售额)") + factors: list[str] | None = Field(default=None, description="因子列,2 到 4 列(factor 用,如订单数、客单价)") + headline: Headline | None = Field(default=None, description="可选。总数的两格,用来核对拆开后各段之和对不对得上") + parent: Parent | None = Field(default=None, description="可选。下钻:这一层是哪次拆解里哪一段的拆解") + label: str | None = Field(default=None, description=_LABEL) + hypothesis: str | None = Field(default=None, description=_HYPOTHESIS) + + +class BaselineArgs(BaseModel): + query: str = Field(description=_QUERY + ";要一条按期次排的序列(要看某一段就在 SQL 里筛好)") + period: str = Field(description=_PERIOD) + measure: str = Field(description="度量列") + target: str | None = Field(default=None, description="本期:期次列里的一个值;留空取最后一期") + basis: Literal["change", "level"] | None = Field( + default=None, description="change:和比较期比的变化率(缺省);level:值本身(存量、比率用)") + grain: Literal["day", "week", "month", "quarter"] | None = Field(default=None, description=_GRAIN) + lag: int | None = Field(default=None, description="和往前第几期比:日缺省 7(和上周同一天比),周、月缺省 1;" + "要同比写 52(周)或 12(月),历史要相应够长") + label: str | None = Field(default=None, description=_LABEL) + hypothesis: str | None = Field(default=None, description=_HYPOTHESIS) + + +class TrendArgs(BaseModel): + query: str = Field(description=_QUERY + ";要一条按期次排的序列") + period: str = Field(description=_PERIOD) + measure: str = Field(description="度量列") + grain: Literal["day", "week", "month", "quarter"] | None = Field(default=None, description=_GRAIN) + label: str | None = Field(default=None, description=_LABEL) + hypothesis: str | None = Field(default=None, description=_HYPOTHESIS) + + +class DifferArgs(BaseModel): + mode: Literal["rate", "mean", "rows"] = Field( + description="rate:比率(转化率、退款率),给分子、分母两列;mean:均值,给每组的均值、标准差、样本数三列," + "或合计、平方和、样本数三列;rows:逐行的值,算子自己算均值和方差(结果不能截断)") + query: str = Field(description=_QUERY) + by: list[str] | None = Field(default=None, description="分组列的列名") + reference: str | None = Field(default=None, description="对照组:分组列里的一个值;留空和整体比") + pairs: list[list[str]] | None = Field(default=None, description="只比这几对:每对写两个组在分组列里的值") + period: str | None = Field(default=None, description="按期次比同一组的两期时:期次列") + base: str | None = Field(default=None, description="按期次比时:基期") + target: str | None = Field(default=None, description="按期次比时:本期") + numerator: str | None = Field(default=None, description="分子列:成功数(rate 用,如退款单数)") + denominator: str | None = Field(default=None, description="分母列:试验数(rate 用,如订单数)") + mean: str | None = Field(default=None, description="每组的均值列(mean 用)") + std: str | None = Field(default=None, description="每组的标准差列(mean 用)") + sum: str | None = Field(default=None, description="每组的合计列(mean 用,没有标准差时和平方和一起给)") + sum_sq: str | None = Field(default=None, description="每组的平方和列(mean 用)") + n: str | None = Field(default=None, description="每组的样本数列(mean 用)") + measure: str | None = Field(default=None, description="逐行的值列(rows 用)") + label: str | None = Field(default=None, description=_LABEL) + hypothesis: str | None = Field(default=None, description=_HYPOTHESIS) + + +class ComparableArgs(BaseModel): + base_query: str | None = Field(default=None, description="基期那份查询的编号,如 Q1") + target_query: str | None = Field(default=None, description="本期那份查询的编号,如 Q2") + query: str | None = Field(default=None, description="两期在同一份查询里按期次分组时:那份的编号(这时不写上面两项)") + period: str | None = Field(default=None, description="同一份查询时:期次列") + base: str | None = Field(default=None, description="同一份查询时:基期") + target: str | None = Field(default=None, description="同一份查询时:本期") + label: str | None = Field(default=None, description=_LABEL) + hypothesis: str | None = Field(default=None, description=_HYPOTHESIS) + + +#: 算子 → 参数模型。分析卡的一项按同一份参数模型校验参数(engine/nodes/analysis.py) +ARGS: dict[str, type[BaseModel]] = { + "decompose": DecomposeArgs, "baseline": BaselineArgs, "trend": TrendArgs, "differ": DifferArgs, + "comparable": ComparableArgs, +} +#: 不算「算什么」的参数:模式另放,这次在验证什么另放(contract.AnalysisRequest) +NOT_PARAMS = frozenset({"mode", "hypothesis"}) + + +def param_names(op: str) -> list[str]: + """一个算子的参数名(不含模式和「在验证什么」),按参数模型里的先后。分析卡校验一项的参数时按它。""" + return [k for k in ARGS[op].model_fields if k not in NOT_PARAMS] + + +def request_of(op: str, args: BaseModel) -> contract.AnalysisRequest: + """校验过的参数 → 一次分析的请求(contract.AnalysisRequest):没填的参数不带。""" + from app.tools.analysis import hypothesis_of + + data = args.model_dump(exclude_none=True) + request: contract.AnalysisRequest = { + "op": op, "mode": data.get("mode") if op in contract.MODES else None, + "params": {k: v for k, v in data.items() if k not in NOT_PARAMS}, + } + if hypothesis := hypothesis_of(data.get("hypothesis")): + request["hypothesis"] = hypothesis + return request + + +async def run_tool(op: str, ctx: ToolContext, args: BaseModel) -> dict[str, Any]: + """一次 agent 分析:读本节点的查询容器、按设置快照取阈值、调算子、结论落成工件。交回 {analysis_artifact, result}: + 记台账、编号 An、给模型看的那一段由节点在记台账时做(engine/nodes/llm.py 的 _record_call),重放时照样做一遍。 + + 调用写错(含这个节点的分析次数用完)抛 contract.CallError,节点作为工具错误交回模型、不记台账。""" + import app.analysis as analysis_ops # 按模块取 run:测试、合并前的替身都只换模块上的这一个函数 + + from app.analysis.contract import LABELS + from app.tools.analysis import context_of, prepare, scope_of, settings_of, store + + scope = scope_of(ctx.extra) + if scope is None: + raise CallError("no_scope", NO_SCOPE) + if not scope.queries: + raise CallError("no_queries", NO_QUERIES) + settings = await settings_of(scope.snapshot) + if len(scope.results) >= settings["max_calls"]: + raise CallError("max_calls", MAX_CALLS.format(done=len(scope.results), label=LABELS["max_calls"], + limit=settings["max_calls"])) + request = request_of(op, args) + await prepare(scope) + context = await context_of(list(scope.queries.values()), tool_ctx=ctx, cache=scope.source_cache) + result = await analysis_ops.run(request, scope.resolve, settings=settings, context=context, parents=scope.parent) + artifact = await store(result, run_id=ctx.run_id, node_id=scope.node_id) + return {"analysis_artifact": artifact, "result": result} + + +@register( + name=contract.TOOL_NAMES["decompose"], + category=CATEGORY, + description="变化拆解:说清一个量的变化从哪来。读本节点查过的结果(【证据 Qn】的编号),按维度算各段对总变化的贡献" + "(additive)、把比率的变化拆成结构变化和各段自身的变化(ratio)、把乘积拆成各因子的贡献(factor);给了总数" + "就核对各段之和对不对得上,parent 接着上一次拆解的某一段往下钻。主要来自哪一段、是否分散由系统按平台的阈值判定。", + args_schema=DecomposeArgs, + guide=METHOD_GUIDE, +) +async def analysis_decompose(ctx: ToolContext, **kwargs: Any) -> dict[str, Any]: + return await run_tool("decompose", ctx, DecomposeArgs(**kwargs)) + + +@register( + name=contract.TOOL_NAMES["baseline"], + category=CATEGORY, + description="波动基线:把本期放回它自己的历史里看,判断这次的变化在不在常规波动范围内。要一份按期次排的序列" + "(期次列 + 度量列);历史不够长、本期还没过完时照实交回算不了的原因。", + args_schema=BaselineArgs, + guide=METHOD_GUIDE, +) +async def analysis_baseline(ctx: ToolContext, **kwargs: Any) -> dict[str, Any]: + return await run_tool("baseline", ctx, BaselineArgs(**kwargs)) + + +@register( + name=contract.TOOL_NAMES["trend"], + category=CATEGORY, + description="趋势:判断一条按期次排的序列是在持续上升、持续下降,还是没有明显趋势(只是一次波动)。", + args_schema=TrendArgs, + guide=METHOD_GUIDE, +) +async def analysis_trend(ctx: ToolContext, **kwargs: Any) -> dict[str, Any]: + return await run_tool("trend", ctx, TrendArgs(**kwargs)) + + +@register( + name=contract.TOOL_NAMES["differ"], + category=CATEGORY, + description="差异检验:判断两组(或同一组的两期)的差异站得住,还是可能只是样本波动。比率给分子、分母两列(rate)," + "均值给均值、标准差、样本数(mean),也可以给逐行的值(rows);样本小时照实标出。", + args_schema=DifferArgs, + guide=METHOD_GUIDE, +) +async def analysis_differ(ctx: ToolContext, **kwargs: Any) -> dict[str, Any]: + return await run_tool("differ", ctx, DifferArgs(**kwargs)) + + +@register( + name=contract.TOOL_NAMES["comparable"], + category=CATEGORY, + description="可比性检查:比两期之前先确认能不能直接比——两份查询是不是只差日期、窗口是否一样长、是不是整期、" + "星期构成是否相同。判定为可比、有条件可比或不可比,并列出原因。", + args_schema=ComparableArgs, + guide=METHOD_GUIDE, +) +async def analysis_comparable(ctx: ToolContext, **kwargs: Any) -> dict[str, Any]: + return await run_tool("comparable", ctx, ComparableArgs(**kwargs)) + + +__all__ = ["ANALYSIS_METHOD_PROMPT", "ARGS", "METHOD_GUIDE", "param_names", "request_of", "run_tool"] diff --git a/backend/app/tools/datasource.py b/backend/app/tools/datasource.py index c54a6823..871ef28d 100644 --- a/backend/app/tools/datasource.py +++ b/backend/app/tools/datasource.py @@ -374,6 +374,26 @@ def _pinned_under_name(pins: dict[str, Any], name: str) -> bool: return any(isinstance(entry, dict) and entry.get("name") == name for entry in pins.values()) +async def resolved_source(name: str, ctx: ToolContext) -> tuple[DataSource, Any] | None: + """按名字找启用着的数据源,按这次运行固定的版本解析成查询用的那个源(_resolve,同 build_datasource_tools):(数据源的行, + 查询用的源)。找不到、固定的版本没了返回 None。 + + 分析(app/tools/analysis.py)读目录、剖析事实、现查表的日期范围时用:查的要和这次运行的查询是同一版数据。用自己的短 + 会话,不提交(行上已经读出来的属性会话关了照样能读)。""" + from app.db.base import SessionLocal + + async with SessionLocal() as session: + row = (await session.execute(select(DataSource).where( + DataSource.name == name, DataSource.enabled.is_(True)))).scalar_one_or_none() + if row is None: + return None + try: + source, _ = await _resolve(session, row, ctx) + except table_versions.SnapshotMissing: + return None + return row, source + + async def _resolve(session: AsyncSession, row: DataSource, ctx: ToolContext) -> tuple[Any, bool]: """查询该用的源,以及它的版本是不是这次运行固定的。 diff --git a/backend/app/tools/registry.py b/backend/app/tools/registry.py index bf98754c..82d048c6 100644 --- a/backend/app/tools/registry.py +++ b/backend/app/tools/registry.py @@ -55,6 +55,17 @@ class ToolContext: extra: dict[str, Any] = field(default_factory=dict) +@dataclass(frozen=True) +class ToolGuide: + """绑了这个工具时一并交给模型的方法说明(写进 system,engine/nodes/llm.py 的 _build_messages、协作成员同样)。 + + 几个工具共用一份说明时写同一个 id:同一份只注入一次(guides_of 按 id 去重)。说明随代码升版,不是 Skill——Skill 是库里 + 用户可改、可停用的行,种子只在同名不存在时插入(seed.py),平台的方法要跟着代码走(分析方法,D12)。""" + + id: str + text: str + + @dataclass class ToolSpec: name: str @@ -72,6 +83,8 @@ class ToolSpec: # 能力登记里的效果,写了就照它登记(平台内置的写入能力记 write:只能放在调用工具节点里,经动作流程执行, # capabilities/platform.py)。不写的按 dangerous / writes_state 推 effect: str | None = None + # 绑了它时一并交给模型的方法说明(ToolGuide)。建工具时放进工具的 metadata["guide"],节点按 guides_of 去重注入 + guide: ToolGuide | None = None def json_schema(self) -> dict[str, Any]: return self.args_schema.model_json_schema() @@ -90,6 +103,7 @@ def register( needs_context: bool = True, writes_state: bool = False, effect: str | None = None, + guide: ToolGuide | None = None, ) -> Callable[[ToolFunc], ToolFunc]: def deco(func: ToolFunc) -> ToolFunc: _REGISTRY[name] = ToolSpec( @@ -102,6 +116,7 @@ def register( needs_context=needs_context, writes_state=writes_state, effect=effect, + guide=guide, ) return func @@ -159,9 +174,26 @@ def build_tool(spec: ToolSpec, ctx: ToolContext) -> BaseTool: coroutine=_run, # 只给异步实现;同步路径直接报错,避免在事件循环里被阻塞调用 func=None, + # 方法说明跟着工具走:节点按绑定的工具取(guides_of),没有说明的工具 metadata 和以前一样是空的 + **({"metadata": {"guide": spec.guide}} if spec.guide is not None else {}), ) +def guides_of(tools: Any) -> list[ToolGuide]: + """这批工具带的方法说明,按 id 去重、按第一次出现的先后。没有说明的工具不算。""" + out: dict[str, ToolGuide] = {} + for tool in tools or []: + guide = ((getattr(tool, "metadata", None) or {}) if tool is not None else {}).get("guide") + if isinstance(guide, ToolGuide) and guide.id not in out: + out[guide.id] = guide + return list(out.values()) + + +def guides_text(tools: Any) -> str: + """注入 system 的那一段:每份说明一段,空行隔开。没有说明为空串。""" + return "\n\n".join(g.text.strip() for g in guides_of(tools) if g.text.strip()) + + async def build_tools( names: list[str], ctx: ToolContext, *, session: Any = None, allow_write: bool = False ) -> list[BaseTool]: diff --git a/backend/tests/fixtures/analysis_ops.py b/backend/tests/fixtures/analysis_ops.py new file mode 100644 index 00000000..c9371b10 --- /dev/null +++ b/backend/tests/fixtures/analysis_ops.py @@ -0,0 +1,61 @@ +"""测试用的分析算子替身(第 1 波各包并行:W1-a 的 app.analysis.run 落地前,入口的测试不等它)。 + +FakeOps 换掉模块上的 app.analysis.run(入口都按模块取 run),按请求交回 app.analysis.testing.fake_result 的假结论, +并记下每次调用拿到的请求、按名字解析到的输入快照、阈值、运行期依赖、上一层结论——测试据此断言入口交进去的东西。 +""" +from __future__ import annotations + +from typing import Any + +import app.analysis as analysis_ops +from app.analysis.testing import fake_result + +#: 每个算子缺省给的判定(fake_result 有现成判定语的那几个) +VERDICT = {"decompose": "driver", "baseline": "outside_band", "trend": "rising", "differ": "no_evidence", + "comparable": "comparable"} + + +class FakeOps: + """errors:按调用的先后,每次要抛的异常(None 表示照常交回);用完了都照常交回。statuses / verdicts 同理。""" + + def __init__(self, monkeypatch, *, errors: list[Any] | None = None, statuses: list[str] | None = None, + verdicts: list[str] | None = None, peek: list[str] | None = None, **overrides: Any) -> None: + self.calls: list[dict[str, Any]] = [] + #: 每次调用时看一眼这几个名字能不能按 parents 取到上一层结论(visible) + self.peek = list(peek or []) + self.errors = list(errors or []) + self.statuses = list(statuses or []) + self.verdicts = list(verdicts or []) + self.overrides = overrides + monkeypatch.setattr(analysis_ops, "run", self.run) + + async def run(self, request: dict[str, Any], resolve: Any, *, settings: Any, context: Any, + parents: Any = None) -> dict[str, Any]: + params = request.get("params") or {} + names = [params[k] for k in ("query", "base_query", "target_query") if params.get(k)] + snapshots = {name: resolve(name) for name in names} + parent = None + if isinstance(params.get("parent"), dict) and parents is not None: + parent = parents(params["parent"]["of"]) + self.calls.append({"request": request, "snapshots": snapshots, "settings": dict(settings), "context": context, + "parent": parent, "parents": parents, + "visible": {n: parents is not None and parents(n) is not None for n in self.peek}}) + error = self.errors.pop(0) if self.errors else None + if error is not None: + raise error + status = self.statuses.pop(0) if self.statuses else "ok" + verdict = self.verdicts.pop(0) if self.verdicts else VERDICT[request["op"]] + roles = {"query": "data", "base_query": "base", "target_query": "target"} + inputs = [{"ref": name, "artifact": snap["artifact"], "role": roles[key], "columns": snap["columns"], + "rows": "all"} + for key in ("query", "base_query", "target_query") + if (name := params.get(key)) and (snap := snapshots.get(name)) is not None] + if parent is not None: + from app.core.artifact_store import canonical_json, content_hash + + inputs.append({"ref": params["parent"]["of"], "artifact": content_hash(canonical_json(parent)), + "role": "parent"}) + return fake_result(op=request["op"], mode=request.get("mode"), verdict=verdict, status=status, + reason_code="history_short" if status == "refused" else None, inputs=inputs, + params=dict(params), settings=dict(settings), hypothesis=request.get("hypothesis"), + **self.overrides) diff --git a/backend/tests/test_analysis_tools.py b/backend/tests/test_analysis_tools.py new file mode 100644 index 00000000..88a96815 --- /dev/null +++ b/backend/tests/test_analysis_tools.py @@ -0,0 +1,439 @@ +"""agent 分析工具(docs/design/analysis-round/00-总方案.md §3.2):参数、方法说明、查询容器、台账、编号、下钻、次数上限、 +遮罩列、续跑。 + +算子(app.analysis.run)还没落地:换成按请求交回假结论的替身(tests/fixtures/analysis_ops.FakeOps),断言入口交给算子的 +东西、算子交回后入口做的事。模型换成脚本(MockChatModel._decide),不调用任何模型。库是虚构的零售库 shop。 +""" +from __future__ import annotations + +import asyncio +import json +import sqlite3 + +import pytest +from langchain_core.messages import AIMessage, SystemMessage, ToolMessage +from sqlalchemy import select + +from app.analysis import contract +from app.analysis.contract import CallError +from app.core import artifact_store +from app.core.artifact_store import canonical_json, content_hash +from app.data.engine import engines +from app.db.base import SessionLocal +from app.db.models import Artifact, DataSource, Run, RunEvent +from app.engine.runner import run_manager +from app.tools.analysis import CALL_ERROR_HEAD, REFUSED_CODE +from app.tools.builtin.analysis import ANALYSIS_METHOD_PROMPT, ARGS, MAX_CALLS, METHOD_GUIDE, NO_SCOPE +from tests.fixtures.analysis_ops import FakeOps + +TOOL = "db_query__shop" +DECOMPOSE = contract.TOOL_NAMES["decompose"] +BASELINE = contract.TOOL_NAMES["baseline"] +SQL = "SELECT region, week, SUM(amount) AS gmv FROM orders GROUP BY region, week ORDER BY region, week" +MASKED_SQL = "SELECT region, phone AS tel, SUM(amount) AS gmv FROM orders GROUP BY region, phone ORDER BY region" +ROWS = [(1, "华东", "2026-W41", 820.0, "139-0000-0001"), (2, "华东", "2026-W42", 700.0, "139-0000-0001"), + (3, "华南", "2026-W41", 700.0, "139-0000-0002"), (4, "华南", "2026-W42", 666.0, "139-0000-0002"), + (5, "华北", "2026-W41", 600.0, "139-0000-0003"), (6, "华北", "2026-W42", 560.0, "139-0000-0003")] +DECOMPOSE_ARGS = {"mode": "additive", "query": "Q1", "by": ["region"], "period": "week", "base": "2026-W41", + "target": "2026-W42", "measure": "gmv", "label": "销售额", "hypothesis": "下降是不是集中在某个地区"} + + +@pytest.fixture(autouse=True) +async def engine_up(): + await run_manager.setup() + yield + await run_manager.shutdown() + + +async def _shop(tmp_path, options=None): + path = tmp_path / "shop.db" + db = sqlite3.connect(path) + db.executescript("CREATE TABLE orders (id INTEGER PRIMARY KEY, region TEXT, week TEXT, amount REAL, phone TEXT);") + db.executemany("INSERT INTO orders VALUES (?, ?, ?, ?, ?)", ROWS) + db.commit() + db.close() + async with SessionLocal() as session: + row = (await session.execute(select(DataSource).where(DataSource.name == "shop"))).scalar_one_or_none() + if row is None: + row = DataSource(name="shop", kind="sqlite", database=str(path), readonly=True, enabled=True) + session.add(row) + row.database, row.kind, row.enabled, row.readonly, row.options = str(path), "sqlite", True, True, options or {} + await session.commit() + source_id = row.id + await engines.invalidate(source_id) + return source_id + + +@pytest.fixture +async def shop(tmp_path): + source_id = await _shop(tmp_path) + yield + await engines.invalidate(source_id) + + +class Script: + """Agent(和协作成员)依次发 calls 里的工具调用,再给结论;seen 记下每次带工具的调用看到的消息。""" + + def __init__(self, monkeypatch, calls, *, final="销售额下降,主要来自华东。", route=None): + from app.providers import mock_model + + self.seen: list[list] = [] + self.plain: list[list] = [] + routed = {"n": 0} + + def decide(model, messages): + if model.response_format: + routed["n"] += 1 + if route is not None and routed["n"] == 1: + return AIMessage(content=json.dumps(route, ensure_ascii=False)) + return AIMessage(content=json.dumps({"assignments": [], "done": True, "reason": "完成"})) + if not model.tools: + self.plain.append(list(messages)) + return AIMessage(content="收尾") + self.seen.append(list(messages)) + done = sum(isinstance(m, ToolMessage) for m in messages) + if done < len(calls): + name, args = calls[done] + return AIMessage(content="", tool_calls=[{"name": name, "args": args, "id": f"call_{done}"}]) + return AIMessage(content=final) + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", decide) + + +def node(nid, ntype, **config): + return {"id": nid, "type": ntype, "position": {"x": 0, "y": 0}, "data": {"label": nid, "config": config}} + + +def agent_graph(tools=(TOOL, DECOMPOSE), approval="never", **cfg): + nodes = [node("start", "input"), + node("bot", "agent", prompt="销售额为什么下降", tools=list(tools), approval=approval, **cfg), + node("out", "output", fields=[{"name": "answer", "value": "{{ nodes.bot.text }}"}])] + return {"nodes": nodes, "edges": [{"source": a["id"], "target": b["id"]} for a, b in zip(nodes, nodes[1:])]} + + +async def wait(run_id, statuses=("succeeded", "failed")): + for _ in range(400): + await asyncio.sleep(0.05) + async with SessionLocal() as session: + row = await session.get(Run, run_id) + if row.status in statuses and (row.status == "interrupted" or row.manifest_seq is not None): + return row + raise AssertionError(f"run {run_id} 没有结束:{row.status}") + + +async def events(run_id, etype=None, node_id=None): + async with SessionLocal() as session: + q = select(RunEvent).where(RunEvent.run_id == run_id) + if etype: + q = q.where(RunEvent.type == etype) + if node_id: + q = q.where(RunEvent.node_id == node_id) + return [e.data for e in (await session.execute(q.order_by(RunEvent.seq))).scalars()] + + +async def run_graph(graph, **kw): + run = await run_manager.start(graph=graph, input_payload={}, **kw) + row = await wait(run.id) + assert row.status == "succeeded", row.error + return row + + +def text(message): + return message.content if isinstance(message.content, str) else json.dumps(message.content, ensure_ascii=False) + + +def tool_messages(script): + return [text(m) for m in script.seen[-1] if isinstance(m, ToolMessage)] + + +async def ledger(run_id, node_id="bot"): + [finished] = await events(run_id, "node.finished", node_id) + return finished["evidence"] + + +# -------------------------------------------------------------------------- +# 工具定义:参数只有「算什么」,五个工具共用一份方法说明 +# -------------------------------------------------------------------------- + + +def test_the_five_tools_take_no_thresholds_and_share_one_method(): + from app.capabilities.registry import is_platform_query + from app.tools.registry import all_specs + + specs = all_specs() + for op, name in contract.TOOL_NAMES.items(): + spec = specs[name] + props = spec.args_schema.model_json_schema()["properties"] + assert not set(props) & set(contract.DEFAULTS), f"{name} 的参数里有阈值:{set(props) & set(contract.DEFAULTS)}" + assert spec.args_schema is ARGS[op] and spec.category == "分析" and spec.description + assert spec.guide is METHOD_GUIDE and not spec.dangerous and not spec.writes_state + # 不查库:能力登记、出处链都不把它的结果当查询快照 + assert not is_platform_query(name) + assert "query" in ARGS["decompose"].model_json_schema()["properties"] + assert {"mode", "by", "period", "base", "target", "measure", "numerator", "denominator", "product", "factors", + "headline", "parent", "label", "hypothesis"} <= set(ARGS["decompose"].model_fields) + assert {"basis", "grain", "lag"} <= set(ARGS["baseline"].model_fields) + assert {"reference", "pairs", "mode"} <= set(ARGS["differ"].model_fields) + assert {"base_query", "target_query"} <= set(ARGS["comparable"].model_fields) + + +def test_unknown_parameters_and_thresholds_are_rejected_like_any_tool(): + from app.tools.registry import ToolArgsError, prepare_args + + with pytest.raises(ToolArgsError) as found: + prepare_args(ARGS["decompose"], {**DECOMPOSE_ARGS, "main_share": 0.3}) + assert "main_share 不是该工具的参数" in str(found.value) + with pytest.raises(ToolArgsError): + prepare_args(ARGS["decompose"], {**DECOMPOSE_ARGS, "mode": "average"}) + + +def test_chat_users_may_bind_the_analysis_tools(): + from app.auth.chat_policy import CHAT_BUILTIN_TOOLS, CHAT_NODE_TYPES, chat_graph_problem + + assert set(contract.TOOL_NAMES.values()) <= CHAT_BUILTIN_TOOLS and contract.NODE_TYPE in CHAT_NODE_TYPES + assert chat_graph_problem(agent_graph()) is None + + +def test_a_tool_node_cannot_call_an_analysis_tool(): + from app.engine.schema import GraphSpec, validate_graph + + graph = {"nodes": [node("start", "input"), node("t", "tool", tool=DECOMPOSE, args=DECOMPOSE_ARGS)], + "edges": [{"source": "start", "target": "t"}]} + [issue] = [i for i in validate_graph(GraphSpec.model_validate(graph)).issues if i.code == "analysis.tool_node"] + assert issue.level == "error" and issue.field == "tool" and "分析卡" in issue.message + + +async def test_calling_it_outside_an_agent_says_where_it_belongs(): + from app.tools.registry import ToolContext, Versions, call_tool + + with pytest.raises(CallError) as found: + await call_tool(DECOMPOSE, DECOMPOSE_ARGS, ToolContext(data_versions=Versions.CURRENT)) + assert found.value.message == NO_SCOPE + + +# -------------------------------------------------------------------------- +# 方法说明:绑了分析工具的 Agent 注入一次,模型调用节点、没绑的 Agent 不注入 +# -------------------------------------------------------------------------- + + +async def test_the_method_is_injected_once_into_the_agent_system(monkeypatch, shop): + FakeOps(monkeypatch) + script = Script(monkeypatch, [(TOOL, {"sql": SQL})]) + await run_graph(agent_graph(tools=(TOOL, DECOMPOSE, BASELINE), system="你是零售分析师。")) + [system] = [m for m in script.seen[0] if isinstance(m, SystemMessage)] + assert system.content.startswith("你是零售分析师。") and system.content.count(ANALYSIS_METHOD_PROMPT) == 1 + + script = Script(monkeypatch, [(TOOL, {"sql": SQL})]) + await run_graph(agent_graph(tools=(TOOL,), system="你是零售分析师。")) + [system] = [m for m in script.seen[0] if isinstance(m, SystemMessage)] + assert system.content == "你是零售分析师。", "没绑分析工具的 Agent,system 和以前一字不差" + + +async def test_model_call_nodes_get_no_method(monkeypatch): + from app.providers import mock_model + + seen: list = [] + + def decide(model, messages): + seen.append(list(messages)) + return AIMessage(content="好") + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", decide) + nodes = [node("start", "input"), node("llm", "llm", system="你是零售分析师。", prompt="说一句"), + node("out", "output", fields=[{"name": "a", "value": "{{ nodes.llm.text }}"}])] + await run_graph({"nodes": nodes, "edges": [{"source": "start", "target": "llm"}, {"source": "llm", "target": "out"}]}) + assert ANALYSIS_METHOD_PROMPT not in json.dumps([text(m) for m in seen[0]], ensure_ascii=False) + + +# -------------------------------------------------------------------------- +# 一次分析:查询容器、台账、工件、编号、交回模型的那一段 +# -------------------------------------------------------------------------- + + +async def test_an_analysis_reads_this_nodes_query_and_is_recorded(monkeypatch, shop): + ops = FakeOps(monkeypatch) + script = Script(monkeypatch, [(TOOL, {"sql": SQL}), (DECOMPOSE, DECOMPOSE_ARGS)]) + row = await run_graph(agent_graph()) + + # 算子拿到的:请求只有「算什么」,Q1 解析成本节点那次查询的快照 + [call] = ops.calls + assert call["request"] == {"op": "decompose", "mode": "additive", "hypothesis": "下降是不是集中在某个地区", + "params": {k: v for k, v in DECOMPOSE_ARGS.items() if k not in ("mode", "hypothesis")}} + ends = await events(row.id, "tool.end", "bot") + query_artifact = ends[0]["query_artifact"] + snap = call["snapshots"]["Q1"] + assert snap["ref"] == "Q1" and snap["artifact"] == query_artifact and snap["node_id"] == "bot" + assert snap["source"] == "shop" and snap["sql"] == SQL and snap["truncated"] is False + assert snap["columns"] == ["region", "week", "gmv"] and snap["rows"][0] == ["华东", "2026-W41", 820.0] + assert snap["column_types"] == ["text", "text", "number"] and snap["masked"] == [] + # 阈值:没有发起时的快照,现读设置(没存过就是缺省) + assert call["settings"] == contract.DEFAULTS + assert set(call["context"]) == {"today", "probe", "catalogs", "facts"} + assert call["context"]["probe"] is None, "还没有 W1-a 的 make_prober 时不给探查" + + # 结论落成工件,tool.end 带着它;台账记一条 kind analysis(带 call_id),在那次查询之后 + analysis_artifact = ends[1]["analysis_artifact"] + stored = artifact_store.load(analysis_artifact) + assert stored["op"] == "decompose" and stored["verdict"]["code"] == "driver" + assert stored["hypothesis"] == "下降是不是集中在某个地区" + entries = await ledger(row.id) + assert [e["kind"] for e in entries] == ["tool", "query", "tool", "analysis"] + analysis = entries[-1] + assert analysis == contract.ledger_entry(stored, node_id="bot", exec_no=1, artifact=analysis_artifact, + call_id="call_1") + assert analysis["inputs"] == [query_artifact] + async with SessionLocal() as session: + kinds = {r.kind for r in (await session.execute( + select(Artifact).where(Artifact.id == analysis_artifact))).scalars()} + assert kinds == {contract.ARTIFACT_KIND} + + # 交回模型的:查询是「【证据 Q1】」,分析是「【分析 A1】」加判定语、关键数、结果表的前几段 + first, second = tool_messages(script) + assert first.startswith("【证据 Q1】\n") + head, body = second.split("\n", 1) + assert head == "【分析 A1】" + reply = json.loads(body) + assert reply["verdict"] == "driver" and reply["subjects"] == [["华东"]] and reply["status"] == "ok" + assert reply["phrase"] == stored["phrase"] and reply["values"]["top_share"] == "0.6186" + assert reply["table"]["rows"][0][0] == "华东" and "criterion" in reply + # 调用记录里记着编号和结论工件 + output = artifact_store.load((await events(row.id, "node.finished", "bot"))[0]["artifact"]) + assert [c.get("alias") for c in output["tool_calls"]] == ["Q1", "A1"] + assert output["tool_calls"][1]["analysis_artifact"] == analysis_artifact + + +async def test_a_refused_analysis_is_still_a_recorded_conclusion(monkeypatch, shop): + FakeOps(monkeypatch, statuses=["refused"]) + script = Script(monkeypatch, [(TOOL, {"sql": SQL}), (BASELINE, {"query": "Q1", "period": "week", + "measure": "gmv"})]) + row = await run_graph(agent_graph(tools=(TOOL, BASELINE))) + entries = await ledger(row.id) + assert entries[-1]["kind"] == "analysis" and entries[-1]["status"] == "refused" and entries[-1]["verdict"] is None + reply = json.loads(tool_messages(script)[1].split("\n", 1)[1]) + assert reply["status"] == "refused" and reply["reason_code"] == "history_short" and "8 期" in reply["reason"] + [warn] = [e for e in await events(row.id, "log", "bot") if e.get("code") == REFUSED_CODE] + assert warn["level"] == "warn" and warn["reason_code"] == "history_short" + + +async def test_call_errors_go_back_to_the_model_and_are_not_recorded(monkeypatch, shop): + ops = FakeOps(monkeypatch, errors=[CallError("masked_column", "列「tel」设置了遮罩,不能当维度"), None]) + script = Script(monkeypatch, [(TOOL, {"sql": SQL}), (DECOMPOSE, DECOMPOSE_ARGS), + (DECOMPOSE, {**DECOMPOSE_ARGS, "by": ["week"]})]) + row = await run_graph(agent_graph()) + assert len(ops.calls) == 2 + _, refused, done = tool_messages(script) + assert refused == f"{CALL_ERROR_HEAD}列「tel」设置了遮罩,不能当维度" + assert done.startswith("【分析 A1】"), "写错的那次不占编号" + [error] = [e for e in await events(row.id, "tool.error", "bot")] + assert error["call_error"] == "masked_column" and error["error"] == refused + entries = await ledger(row.id) + assert [e["call_id"] for e in entries if e["kind"] == "analysis"] == ["call_2"] + + +async def test_drill_down_reads_this_nodes_earlier_conclusion(monkeypatch, shop): + ops = FakeOps(monkeypatch) + drill = {**DECOMPOSE_ARGS, "by": ["week"], "parent": {"of": "A1", "key": ["华东"]}, "hypothesis": "华东内部"} + script = Script(monkeypatch, [(TOOL, {"sql": SQL}), (DECOMPOSE, DECOMPOSE_ARGS), (DECOMPOSE, drill)]) + row = await run_graph(agent_graph()) + first, second = ops.calls + # parent 按本节点的编号取回上一层那份结论:就是存下的那一份(按内容寻址,哈希对得上) + stored = artifact_store.load((await events(row.id, "tool.end", "bot"))[1]["analysis_artifact"]) + assert second["parent"] == stored + assert content_hash(canonical_json(second["parent"])) == (await events(row.id, "tool.end", "bot"))[1][ + "analysis_artifact"] + assert second["parents"]("A9") is None + assert tool_messages(script)[2].startswith("【分析 A2】") + + +async def test_the_number_of_analyses_per_node_is_capped(monkeypatch, shop): + ops = FakeOps(monkeypatch) + # 第二次换一个维度(同样的参数会被护栏当成重复调用、直接交回上次的结果,不走到分析) + script = Script(monkeypatch, [(TOOL, {"sql": SQL}), (DECOMPOSE, DECOMPOSE_ARGS), + (DECOMPOSE, {**DECOMPOSE_ARGS, "by": ["week"]})]) + await run_graph(agent_graph(), options={contract.SETTINGS_KEY: {"max_calls": 1}}) + assert len(ops.calls) == 1 + capped = tool_messages(script)[2] + assert capped == CALL_ERROR_HEAD + MAX_CALLS.format(done=1, label=contract.LABELS["max_calls"], limit=1) + # 阈值来自发起时的快照 + assert ops.calls[0]["settings"]["max_calls"] == 1 + + +async def test_masked_columns_reach_the_operator(monkeypatch, tmp_path): + source_id = await _shop(tmp_path, {"mask_columns": ["phone"]}) + try: + ops = FakeOps(monkeypatch) + Script(monkeypatch, [(TOOL, {"sql": MASKED_SQL}), (DECOMPOSE, {**DECOMPOSE_ARGS, "by": ["tel"]})]) + await run_graph(agent_graph()) + masked = ops.calls[0]["snapshots"]["Q1"]["masked"] + # 按 SQL 认出改了名字的遮罩列(phone AS tel)排在前面,数据源设的列名也在 + assert masked[0] == "tel" and "phone" in masked + finally: + await engines.invalidate(source_id) + + +async def test_mask_results_runs_hand_over_the_masked_snapshot(monkeypatch, tmp_path): + source_id = await _shop(tmp_path, {"mask_columns": ["phone"]}) + try: + ops = FakeOps(monkeypatch) + Script(monkeypatch, [(TOOL, {"sql": MASKED_SQL}), (DECOMPOSE, {**DECOMPOSE_ARGS, "by": ["region"]})]) + await run_graph(agent_graph(), options={"mask_results": True, "read_only_data": True}) + snap = ops.calls[0]["snapshots"]["Q1"] + assert "tel" in snap["masked"] + tel = snap["columns"].index("tel") + assert {r[tel] for r in snap["rows"]} == {"已遮罩"}, "遮罩运行里算子拿到的是遮过的快照" + finally: + await engines.invalidate(source_id) + + +# -------------------------------------------------------------------------- +# 续跑:审批恢复时节点整个重放,分析不再执行、编号不错位 +# -------------------------------------------------------------------------- + + +async def test_replay_after_approvals_does_not_repeat_or_renumber(monkeypatch, shop): + ops = FakeOps(monkeypatch) + script = Script(monkeypatch, [(TOOL, {"sql": SQL}), (DECOMPOSE, DECOMPOSE_ARGS), + (DECOMPOSE, {**DECOMPOSE_ARGS, "parent": {"of": "A1", "key": ["华东"]}})]) + run = await run_manager.start(graph=agent_graph(approval="always"), input_payload={}) + for _ in range(3): + row = await wait(run.id, ("interrupted", "failed", "succeeded")) + assert row.status == "interrupted", row.error + await run_manager.resume(run.id, {"approved": True}) + row = await wait(run.id, ("succeeded", "failed", "interrupted")) + assert row.status == "succeeded", row.error + + assert len(ops.calls) == 2, "分析在重放时又执行了一次" + ends = await events(row.id, "tool.end", "bot") + assert len(ends) == 3 + # 重放之后模型看到的编号还是同一套,下钻取到的是同一份结论 + assert [m.split("\n", 1)[0] for m in tool_messages(script)] == ["【证据 Q1】", "【分析 A1】", "【分析 A2】"] + assert ops.calls[1]["parent"] == artifact_store.load(ends[1]["analysis_artifact"]) + entries = [e for e in await ledger(row.id) if e["kind"] == "analysis"] + assert [(e["call_id"], e["artifact"]) for e in entries] == [("call_1", ends[1]["analysis_artifact"]), + ("call_2", ends[2]["analysis_artifact"])] + + +# -------------------------------------------------------------------------- +# 协作成员:同样注入方法说明、同样编号(协作节点不记证据台账) +# -------------------------------------------------------------------------- + + +async def test_a_team_member_gets_the_method_and_numbers(monkeypatch, shop): + ops = FakeOps(monkeypatch) + script = Script(monkeypatch, [(TOOL, {"sql": SQL}), (DECOMPOSE, DECOMPOSE_ARGS)], + route={"assignments": [{"agent": "分析员", "instruction": "拆一下销售额的变化"}], "done": False}) + nodes = [node("start", "input"), + node("team", "supervisor", goal="销售额为什么下降", approval="never", max_rounds=2, agents=[ + {"name": "分析员", "system": "你负责拆解", "tools": [TOOL, DECOMPOSE], "max_steps": 4}]), + node("out", "output", fields=[{"name": "a", "value": "{{ nodes.team.text }}"}])] + run = await run_manager.start(graph={"nodes": nodes, "edges": [{"source": "start", "target": "team"}, + {"source": "team", "target": "out"}]}, + input_payload={}) + row = await wait(run.id) + assert row.status == "succeeded", row.error + [system] = [m for m in script.seen[0] if isinstance(m, SystemMessage)] + assert system.content.startswith("你负责拆解") and system.content.count(ANALYSIS_METHOD_PROMPT) == 1 + assert [m.split("\n", 1)[0] for m in tool_messages(script)] == ["【证据 Q1】", "【分析 A1】"] + assert ops.calls[0]["snapshots"]["Q1"]["node_id"] == "team" + [end] = [e for e in await events(row.id, "tool.end", "team") if e.get("analysis_artifact")] + assert artifact_store.load(end["analysis_artifact"])["op"] == "decompose" diff --git a/backend/tests/test_catalog_view.py b/backend/tests/test_catalog_view.py index 3edd71d2..75760f88 100644 --- a/backend/tests/test_catalog_view.py +++ b/backend/tests/test_catalog_view.py @@ -258,7 +258,7 @@ def test_of_run_reads_the_run_options(): #: 给模型、给自查读目录的模块(四处消费 + 它们的帮手)。要读目录一律经 data/catalog_view.py CONSUMERS = ("tools/datasource.py", "look/tables.py", "data/sqlcheck.py", "engine/nodes/dual_check.py", - "engine/verify_agent.py", "api/copilot_context.py") + "engine/verify_agent.py", "api/copilot_context.py", "tools/analysis.py") FORBIDDEN = re.compile(r"\bread_catalogs?\s*\(|\bread_entry\s*\(|\bCatalogNote\b")