mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-18 04:51:59 +00:00
分析能力入口(二):五个 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:
@@ -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
|
||||
|
||||
|
||||
|
||||
@@ -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}"
|
||||
|
||||
|
||||
|
||||
@@ -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}"
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 子图:把另一张工作流当成一个节点
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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"]
|
||||
|
||||
@@ -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"]
|
||||
@@ -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]:
|
||||
"""查询该用的源,以及它的版本是不是这次运行固定的。
|
||||
|
||||
|
||||
@@ -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
@@ -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)
|
||||
@@ -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"
|
||||
@@ -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")
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user