分析能力入口(二):五个 agent 分析工具(analysis_decompose / baseline / trend / differ / comparable,名字取 contract.TOOL_NAMES),参数只有「算什么」(引用本节点查过的结果 Q3、列的角色、期次、总数 headline、下钻 parent、度量叫法、在验证什么),没有阈值参数;五个工具共用一份「分析方法」说明(ToolSpec 新增 guide:方法说明 + 去重用的 id,register / build_tools 透传进工具的 metadata),Agent 节点、协作成员绑了任一分析工具就接在 Skill 后面注入 system,同一份只注入一次,模型调用节点不注入。Agent 建工具时经 ToolContext.extra 交一个本节点的分析容器(app/tools/analysis.py 的 AnalysisScope),每次查询记台账时往里放一份输入快照(编号和「【证据 Qn】」同一个),分析结论落成 analysis_result 工件、台账记 contract.ledger_entry(带 call_id),交回模型「【分析 An】」加判定语、判定标准、关键数、附带说明、算不了的原因、结果表前几段;tool.end 带 analysis_artifact;下钻按 An 取本节点的结论;调用写错(contract.CallError,含这个节点的分析次数用完 max_calls)作为工具错误交回、不记台账、不占编号;算不了照样记结论并发一条 analysis_refused。编号只在记台账时放进容器,审批恢复重放时分析不再执行、编号不错位。遮罩列按证据面板同一个函数认(数据源设的、按 SQL 认出改了名字的),遮罩运行交给算子的是遮过的快照。阈值读发起时的快照,没有就现读设置;运行期依赖给运行当天、按运行目录视图读的目录、剖析事实、现查表范围的探查(W1-a 的 make_prober,还没有时不给)。协作成员同样注入方法、同样编号(协作节点不记台账)。使用者问数据的白名单加上五个分析工具和分析卡;调用工具节点调分析工具在画布上就报错(analysis.tool_node)。能力登记不把它们当查询(is_platform_query 不认)

This commit is contained in:
ThearchyHelios
2026-10-21 13:02:30 +08:00
parent a9f1555da2
commit 601b84918d
12 changed files with 1351 additions and 18 deletions
+11 -7
View File
@@ -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
+57 -6
View File
@@ -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}"
+55 -2
View File
@@ -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}"
# --------------------------------------------------------------------------
# 子图:把另一张工作流当成一个节点
# --------------------------------------------------------------------------
+11
View File
@@ -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
+397
View File
@@ -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",
]
+2 -2
View File
@@ -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"]
+265
View File
@@ -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"]
+20
View File
@@ -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]:
"""查询该用的源,以及它的版本是不是这次运行固定的。
+32
View File
@@ -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]:
+61
View File
@@ -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)
+439
View File
@@ -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"
+1 -1
View File
@@ -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")