feat(agent): 完善分析编排与结果传输

2026-08-26 18:04:51 +08:00
parent a438433068
commit 72ebf4d6c1
33 changed files with 1027 additions and 705 deletions
@@ -8,10 +8,13 @@ model: deepseek/deepseek-v4-flash
 ## 回复要求

 - 工具执行期间不输出过程说明，全部完成后只回复最终结果
+- 最终回答必须通过 `final_answer` 提交；调用前必须完成全部业务动作和其他工具，调用后禁止继续调用工具或输出额外文本
 - 直接给出结论、关键数据和可执行建议，默认仅展示最重要的 Top 5；数据不足或任务失败时简要说明影响和下一步
- 多步骤或预计超过 30 秒的任务，开始时使用 `todowrite` 给用户展示计划，并在每个里程碑更新状态；简单问答不创建计划
+- 多步骤或预计超过 30 秒的任务，开始时使用 `todowrite` 给用户展示计划；简单问答不创建计划
 - `todowrite` 是面向用户的业务任务摘要：每项只描述目标或可验证结果，不出现函数名、脚本/文件名、命令、工具名、参数、内部目录或具体修复实现；这些技术细节仅保留在工具过程信息中
 - 任务标题使用简洁的业务语言，例如“准备供水分区所需数据”“计算供水服务范围”“生成并展示分析结果”“整理可复用分析经验”
+- 开始工作及每次进入新的业务阶段时调用一次 `activity_update`，用 `title` 概括当前阶段、用 `reason` 说明该阶段为何必要；已有计划时必须通过 `todos` 提交完整计划状态快照，使阶段与任务状态同时更新，不再单独调用 `todowrite` 更新里程碑
+- `activity_update` 是过程分组，不是任务清单：活动描述当前正在做的一组动作，`todowrite` 描述整个任务的业务目标与完成状态

 ## 工作流生命周期

@@ -44,9 +47,11 @@ Skills 树是**动态生长的**——工作流不是预置的，而是从实际

 **前端工具仅做显示，不返回数据**，不要假设其返回内容。

+`tjwater_cli.command` 虽然是字符串，但命令空间不是可类推的层级语法。当前会话尚未验证某个完整命令路径和参数时，先调用 `help <命令族或前缀>`；已加载工作流中明确记录且已验证的固定命令可直接使用。禁止根据 `analysis runs` 等已有路径创造其他命令族的同名子路径。收到 `COMMAND_NOT_FOUND` 后只执行返回的 `next_commands` 做命令发现，不得继续猜测近似命令。
+
 ## 执行约束

-1. 每次工具调用必须在 `reason` 字段填写具体理由
+1. 普通工具不填写重复的调用理由，具体动作自动归入当前 `activity_update` 活动；切换业务阶段前先更新活动
 2. `tjwater-cli` 输出为 JSON（`schema_version: tjwater-cli/v1`），`"ok": true` 成功，失败时检查 `error.code`
 3. 大结果集禁止完整读取，优先采样/截断/按字段读取
 4. 避免直接用 `Read` 或 `cat` 读取结果文件，尤其是大文件；优先用 `head`/`tail`/`rg` 截断查看，或用 Python 只向 stdout 输出精简 JSON，避免大文件冲击 stdin/stdout
@@ -15,7 +15,6 @@ description: tjwater-cli 命令行工具使用说明，涵盖命令发现、输

 ```json
 {
-  "reason": "说明调用原因",
  "command": "project list",
  "timeout": 120,
  "store_result": false
@@ -24,7 +23,6 @@ description: tjwater-cli 命令行工具使用说明，涵盖命令发现、输

 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `reason` | string | 是 | 调用原因 |
 | `command` | string | 是 | CLI 子命令（不含二进制路径和 `--auth-context`） |
 | `timeout` | number | 否 | 超时秒数，默认 120，大结果集建议 300+ |
 | `store_result` | boolean | 否 | 强制保存到当前对话目录并返回 `data_file.file_path`；分析脚本需要文件输入时设为 true |
@@ -130,7 +128,7 @@ tjwater-cli help COMMAND           → 子命令与参数详情
 ## 最佳实践

 1. **禁止猜测命令** — 执行任何命令前必须先 `tjwater_cli(command="help ...")` 确认命令存在及参数签名，参数均已写在 help 中，禁止凭经验拼写
-2. **reason 必填** — 每次调用必须说明具体理由
+2. **阶段分组** — 调用 CLI 前确认当前业务阶段已通过 `activity_update` 建立，同一阶段的多个查询无需重复说明理由
 3. **按运行 ID 取结果** — 分析完成后先用 `analysis runs list/get/results` 获取 `run_id` 和非时序结果；元素时序再用 `data timeseries analysis` 查询
 4. **文件分析** — workflow 脚本需要文件时使用 `store_result=true`，不得从 Bash 直接联网调用 CLI
 5. **结果验证** — 始终检查 `ok` 字段，失败时先处理错误码再重试
@@ -142,7 +140,6 @@ tjwater-cli help COMMAND           → 子命令与参数详情
 ### 查询所有实时节点数据
 ```json
 {
-  "reason": "获取最近1小时内全部节点的实时数据",
  "command": "data timeseries realtime nodes --start-time 2026-06-03T08:00:00+08:00 --end-time 2026-06-03T09:00:00+08:00"
 }
 ```
@@ -151,7 +148,6 @@ tjwater-cli help COMMAND           → 子命令与参数详情
 ### 按节点查询分析运行时序字段
 ```json
 {
-  "reason": "查询节点 J-001 最近1小时的压力数据",
  "command": "data timeseries analysis node-field --run-id 00000000-0000-0000-0000-000000000001 --node J-001 --field pressure --start-time 2026-06-03T08:00:00+08:00 --end-time 2026-06-03T09:00:00+08:00"
 }
 ```
@@ -159,7 +155,6 @@ tjwater-cli help COMMAND           → 子命令与参数详情
 ### 查询 SCADA 时序数据
 ```json
 {
-  "reason": "查询 SCADA 设备 170490 在指定时间范围的 monitored_value",
  "command": "data timeseries scada query --device-id 170490 --field monitored_value --start-time 2026-06-02T00:00:00+08:00 --end-time 2026-06-03T00:00:00+08:00"
 }
 ```
@@ -171,17 +166,14 @@ tjwater-cli help COMMAND           → 子命令与参数详情
 ```json
 // step 1: 先尝试获取仿真结果
 {
-  "reason": "尝试获取节点 J-001 09:00 时刻的仿真压力",
  "command": "data timeseries realtime simulation-by-id-time --id J-001 --type junction --time 2026-06-03T09:00:00+08:00"
 }
 // step 2: 若 step 1 无数据（ok: false 或 data 为空），触发仿真
 {
-  "reason": "无已有仿真结果，触发1小时水力仿真",
  "command": "simulation run --start-time 2026-06-03T08:00:00+08:00 --duration 60"
 }
 // step 3: 仿真完成后，再次获取结果（同 step 1）
 {
-  "reason": "获取仿真结果中节点 J-001 09:00 时刻的压力",
  "command": "data timeseries realtime simulation-by-id-time --id J-001 --type junction --time 2026-06-03T09:00:00+08:00"
 }
 ```
@@ -150,4 +150,5 @@ if length < 0.01 and headloss > 0.5 → "短管高水损，检查是否存在模
 - 脚本读取全量 JSON 入内存，峰值内存约 200-300MB，需确保执行环境有足够内存。

 ## Learned Patterns
+- [5cbdaa6bcf4e01c22eb2e544] [2026-08 复验] **schema 适配已固化进脚本**：bottleneck_analysis.py 现已直接使用 link_id/node_id 主键与 UTC target-time，无需再手工改码。本次 91,052 管段管网识别出 56 条瓶颈（0.06%），典型特征：100-110mm 小管径串联瓶颈（多条水损值近等差递减、逐段累计，如 7 段链 478128→460635→479635→508436→506699→484919→406224），宜按整链统一扩径；另有 1.4m 短管水损 67m 的模型异常信号（399832/399820），需核查局部阻塞或模型设置。分析后若用户需要改造建议落地，可按"极危...
 - [5ba58cd24c9cea84b6ab5861] **数据 schema 实测适配（2026-04 验证）**：`data timeseries realtime links` 返回记录的管道主键为 `link_id`（不是 `id`），`data timeseries realtime nodes` 返回记录的节点主键为 `node_id`（不是 `id`），且 `time` 字段为 UTC 格式（如 `2026-04-01T00:00:00+00:00`）。运行 `bottleneck_analysis.py` 前需：① 脚本内将 `r['id']` 改为 `r['link_id']`、`n['id']` 改为 `n['node_id']`；② `--target-tim...
@@ -3,6 +3,8 @@
 水力瓶颈管道综合分析
 数据源：管道属性 + 实时水力 + 节点压力 → 复合评分 → 改造建议
 注：realtime links 的 setting 字段为无效值，已移除所有基于 setting 的判定。
+schema 适配（2026-08 实测）：realtime links 主键为 link_id，realtime nodes 主键为 node_id，
+time 为 UTC 格式，--target-time 需传 UTC 时刻（如北京时间 08:00 对应 00:00+00:00）。
 """
 import json, sys, math, argparse
 from collections import defaultdict
@@ -38,16 +40,16 @@ def main():

    np = load_json(args.node_pressures).get('data', [])
    np = [n for n in np if n.get('time') == TT]
-    node_pressure = {n['id']: n.get('pressure', n.get('value',0)) for n in np}
+    node_pressure = {n['node_id']: n.get('pressure', n.get('value',0)) for n in np}
    print(f"  Pipes: {len(props)}, Realtime: {len(rt)}, Node pressures: {len(node_pressure)}", file=sys.stderr)

    # 2. Merge
    print("[2/5] Merging...", file=sys.stderr)
    merged = []
    for r in rt:
-        pid = r['id']; prop = pipe_map.get(pid)
+        pid = r['link_id']; prop = pipe_map.get(pid)
        if prop:
-            merged.append({**prop, **r, '_prop_id': prop['id'], '_rt_id': r['id']})
+            merged.append({**prop, **r, '_prop_id': prop['id'], '_rt_id': r['link_id']})
    print(f"  Merged: {len(merged)}", file=sys.stderr)

    # 3. Score
@@ -0,0 +1,37 @@
+import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description:
+    "开始一个新的业务活动阶段。仅在语义阶段发生变化时调用一次，用 title 概括阶段，用 reason 说明本阶段为何必要；同一阶段内的多个工具动作不要重复调用。该工具只更新用户可见的过程信息，不执行外部操作。",
+  args: {
+    title: tool.schema
+      .string()
+      .min(1)
+      .describe("面向用户的简短业务阶段标题，不包含工具名、函数名、文件名或命令。"),
+    reason: tool.schema
+      .string()
+      .min(1)
+      .describe("本阶段对完成用户目标的必要性，使用一句简洁的自然语言。"),
+    todos: tool.schema
+      .array(
+        tool.schema.object({
+          id: tool.schema.string().optional(),
+          content: tool.schema.string().min(1),
+          status: tool.schema.enum([
+            "pending",
+            "in_progress",
+            "completed",
+            "cancelled",
+          ]),
+          priority: tool.schema.enum(["low", "medium", "high"]).optional(),
+        }),
+      )
+      .optional()
+      .describe(
+        "已有任务计划时提交完整状态快照，使本阶段与任务状态在同一次更新中生效。",
+      ),
+  },
+  async execute() {
+    return "活动阶段已更新。";
+  },
+});
@@ -4,11 +4,6 @@ export default tool({
  description:
    "在前端地图上对节点或管道图层应用样式，或重置为默认样式。样式参数应尽量与前端样式编辑器字段保持一致。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe(
-        "Why this style action is needed for the current user request.",
-      ),
    layer_id: tool.schema
      .enum(["junctions", "pipes"])
      .describe("Target layer id. Must be exactly 'junctions' or 'pipes'."),
@@ -0,0 +1,15 @@
+import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description:
+    "提交直接展示给用户的最终回答。只能在全部业务动作和其他工具调用完成后调用一次；调用后不得继续调用任何工具或输出额外文本。",
+  args: {
+    answer: tool.schema
+      .string()
+      .min(1)
+      .describe("直接展示给用户的完整最终回答，使用简体中文和 Markdown。"),
+  },
+  async execute() {
+    return "最终回答已提交。";
+  },
+});
@@ -8,9 +8,6 @@ export default tool({
  description:
    "调用 TJWater 后端的天地图地理编码服务，将中国境内结构化地址或地点名称转换为经纬度。若需缩放地图，把返回的 location.lon/location.lat 传给 zoom_to_map，并设置 source_crs='EPSG:4326'。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe("Why geocoding is required for the current user request."),
    keyword: tool.schema
      .string()
      .describe("Address or place name to geocode, such as 北京市人民政府."),
@@ -3,11 +3,6 @@ import { tool } from "@opencode-ai/plugin";
 export default tool({
  description: "在前端地图上定位并高亮指定的管网要素。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe(
-        "Why this map positioning action is needed for the user request.",
-      ),
    ids: tool.schema
      .array(tool.schema.string())
      .describe("Feature ids to locate."),
@@ -11,9 +11,6 @@ export default tool({
    action: tool.schema
      .enum(["add", "list", "replace", "remove"])
      .describe("Memory operation to perform."),
-    reason: tool.schema
-      .string()
-      .describe("Why this memory should be persisted for future requests."),
    scope: tool.schema
      .string()
      .describe(
@@ -4,11 +4,6 @@ export default tool({
  description:
    "在前端地图上对 junctions 图层应用分区渲染。先把包装格式 { metadata, location: { file_path }, data: { node_area_map, area_ids?, area_colors? } } 写入 RESULT_REF_IMPORT_DIR，location.file_path 必须等于文件绝对路径；再调用 store_render_ref 获得 res-... 引用，最后把引用传入本工具。不要读取并转传完整 ref 内容，也不要直接传本地文件路径。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe(
-        "Why this junction rendering action is needed for the user request.",
-      ),
    render_ref: tool.schema
      .string()
      .describe(
@@ -8,9 +8,6 @@ export default tool({
  description:
    "搜索当前用户和项目范围内的历史会话 transcript。适合回忆过去讨论过的案例、约束和结论，避免把一次性案例写入 memory。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe("Why prior session history is needed for the current request."),
    query: tool.schema
      .string()
      .describe("What to search for in prior session history."),
@@ -4,9 +4,6 @@ export default tool({
  description:
    "在前端对话界面中渲染图表。折线图/柱状图必须使用 x_data 作为横轴标签，series[].data 作为同长度的一维数值数组，不要把折线数据写成 ECharts 的 [x, y] 二维点数组。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe("Why this chart should be rendered for the user request."),
    title: tool.schema.string().optional().describe("Chart title."),
    chart_type: tool.schema
      .enum(["line", "bar", "pie"])
@@ -21,9 +21,6 @@ export default tool({
        "remove_script",
      ])
      .describe("Skill maintenance operation."),
-    reason: tool.schema
-      .string()
-      .describe("Why this skill maintenance action is justified for future reuse."),
    skill_path: tool.schema
      .string()
      .describe(
@@ -23,11 +23,6 @@ export default tool({
  description:
    "导入当前对话工作目录下的受控 JSON 包装文件并返回 render_ref。文件必须是 { metadata: object, location: { file_path: string }, data: { node_area_map, area_ids?, area_colors? } }，location.file_path 必须与传入的绝对路径完全一致。只接受当前对话工作目录内的真实文件，不接受其他对话目录、目录外路径或指向目录外的符号链接。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe(
-        "为何需要将此本地渲染数据持久化为 render_ref，以便后续通过 render_junctions 渲染到前端。",
-      ),
    file_path: tool.schema
      .string()
      .optional()
@@ -6,15 +6,12 @@ const internalToken = process.env.TJWATER_AGENT_INTERNAL_TOKEN ?? "";

 export default tool({
  description:
-    "通过本地 Agent 桥接调用 tjwater-cli 命令访问 TJWater 后端服务。提供 CLI 子命令和参数。",
+    "通过本地 Agent 桥接调用 tjwater-cli。命令路径和参数不是可自由拼接的语法；若当前会话或已加载工作流没有经过验证的完整命令，必须先调用 help 或 help <命令族>，再从返回的 command、usage 和 options 中选择。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe("Why this tool call is required for the current user request."),
    command: tool.schema
      .string()
      .describe(
-        "tjwater-cli 子命令，不含二进制路径。示例：'analysis runs list'、'data timeseries realtime links --start-time 2025-01-01T00:00:00+08:00 --end-time 2025-01-01T01:00:00+08:00'",
+        "不含二进制路径。只可使用 help 响应或已验证工作流中出现的完整命令路径和参数，禁止类推不同命令族的层级，例如 analysis runs list 存在不代表 simulation runs list 存在。无法确认时调用 'help'、'help simulation' 或相应前缀的 help。",
      ),
    timeout: tool.schema
      .number()
@@ -38,7 +35,6 @@ export default tool({
        },
        body: JSON.stringify({
          session_id: context.sessionID,
-          reason: args.reason,
          command: args.command,
          store_result: args.store_result,
          timeout: args.timeout,
@@ -3,11 +3,6 @@ import { tool } from "@opencode-ai/plugin";
 export default tool({
  description: "为选定的管网要素打开前端的历史记录或计算结果面板。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe(
-        "Why this history panel should be opened for the current task.",
-      ),
    feature_infos: tool.schema
      .array(tool.schema.tuple([tool.schema.string(), tool.schema.string()]))
      .describe("List of [id, type] pairs."),
@@ -3,9 +3,6 @@ import { tool } from "@opencode-ai/plugin";
 export default tool({
  description: "打开前端的 SCADA 监测数据历史面板。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe("Why SCADA panel interaction is required for this request."),
    device_ids: tool.schema
      .array(tool.schema.string())
      .optional()
@@ -8,9 +8,6 @@ export default tool({
  description:
    "调用 TJWater 后端的实时网页搜索服务。适合查询新闻、政策、规范、产品资料、公开网页事实等可能变化的信息。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe("Why web search is required for the current user request."),
    query: tool.schema.string().describe("Search query text."),
    freshness: tool.schema
      .enum(["no_limit", "one_day", "one_week", "one_month", "one_year"])
@@ -4,9 +4,6 @@ export default tool({
  description:
    "在前端地图上缩放定位到坐标。默认坐标为 EPSG:3857；如果来自天地图 geocode 的 lon/lat，传 source_crs='EPSG:4326'，前端会转换为 EPSG:3857 后缩放。",
  args: {
-    reason: tool.schema
-      .string()
-      .describe("Why this map zoom action is needed for the current request."),
    x: tool.schema
      .number()
      .describe("X coordinate. For EPSG:4326 this is longitude; for EPSG:3857 this is meters."),