feat: add SCADA frontend action bridge

2026-07-20 19:57:25 +08:00
parent 72019ac1f2
commit 432edaaf2f
16 changed files with 445 additions and 20 deletions
@@ -15,9 +15,7 @@ Agent 负责：
 1. 理解用户意图。
 2. 调用受控工具获取有限上下文或表达展示意图。
 3. 输出文字摘要、结论、追问和建议。
-4. 在没有可用前端工具时，仅输出文字摘要、结论和建议。
-
-当前不向 Agent 暴露前端动作工具。
+4. 在分析结论完成后，可将 SCADA 等级结果作为受控地图动作发送到浏览器。

 ## 工具选择

@@ -26,12 +24,17 @@ Agent 负责：
 | 历史会话检索 | `session_search` |
 | 用户偏好和项目事实 | `memory_manager` |
 | 可复用流程沉淀 | `skill_manager` |
+| 渲染 SCADA 分析结果 | `render_scada_analysis` |
+| 清除 SCADA 分析结果 | `clear_scada_analysis` |

 ## UI 约束

-1. 不生成或调用前端动作。
+1. `render_scada_analysis` 只能在分析结论已经完成后调用，不得让前端计算、猜测或修改高中低等级。
 2. 每次普通工具调用必须填写具体 `reason`。
 3. 不生成 JS、JSX、HTML、CSS 或可执行前端代码。
+4. SCADA 地图结果只允许使用可信 `sensor_id` 和 `high | medium | low | unrated` 等级，不得传入自定义标签、颜色或 HTML。
+5. 同一批结果不得包含重复 `sensor_id`，每次最多 100 个点位。
+6. 只有 SCADA 地图工具返回浏览器的成功结果后，才能声称已渲染或已清除；工具报错、超时或无活跃浏览器连接时，必须明确告知用户动作失败，不得伪造已渲染的点位、编号或等级。

 ## 执行约束

@@ -0,0 +1,13 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+const FRONTEND_ACTION_TOOLS = new Set([
+  "render_scada_analysis",
+  "clear_scada_analysis",
+]);
+
+export const frontendActionCallIdPlugin: Plugin = async () => ({
+  "tool.execute.before": async (input, output) => {
+    if (!FRONTEND_ACTION_TOOLS.has(input.tool)) return;
+    output.args.__frontend_action_call_id = input.callID;
+  },
+});
@@ -0,0 +1,17 @@
+import { tool } from "@opencode-ai/plugin";
+
+import { executeFrontendAction } from "./frontend_action.js";
+
+export default tool({
+  description: "清除当前浏览器地图上的 Agent SCADA 分析结果覆盖层。",
+  args: {
+    reason: tool.schema
+      .string()
+      .trim()
+      .min(1)
+      .describe("Why the current SCADA analysis overlay should be cleared."),
+  },
+  async execute(args, context) {
+    return executeFrontendAction("clear_scada_analysis", args, context);
+  },
+});
@@ -0,0 +1,76 @@
+type FrontendActionArgs = Record<string, unknown> & {
+  __frontend_action_call_id?: string;
+  reason?: string;
+};
+
+type FrontendActionBridgeResult = {
+  version: "frontend-action-result@1";
+  status: "succeeded" | "failed" | "rejected" | "cancelled" | "expired";
+  output?: unknown;
+  error?: { code?: string; message?: string };
+};
+
+const internalBaseUrl =
+  process.env.TJWATER_AGENT_INTERNAL_BASE_URL ?? "http://127.0.0.1:8787";
+const internalToken = process.env.TJWATER_AGENT_INTERNAL_TOKEN ?? "";
+
+export const executeFrontendAction = async (
+  name: "render_scada_analysis" | "clear_scada_analysis",
+  args: FrontendActionArgs,
+  context: { sessionID: string },
+) => {
+  const callId = args.__frontend_action_call_id;
+  if (!callId) {
+    throw new Error("frontend action bridge did not inject the OpenCode call ID");
+  }
+  const { __frontend_action_call_id: _callId, reason, ...params } = args;
+  let response: Response;
+  try {
+    response = await fetch(`${internalBaseUrl}/internal/frontend-actions/request`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-agent-internal-token": internalToken,
+      },
+      body: JSON.stringify({
+        session_id: context.sessionID,
+        call_id: callId,
+        name,
+        params,
+        fallback_text: reason,
+      }),
+    });
+  } catch (error) {
+    throw new Error(
+      `frontend action bridge unavailable: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(
+      `frontend action bridge rejected request (${response.status}): ${text}`,
+    );
+  }
+  return unwrapFrontendActionResult(text);
+};
+
+export const unwrapFrontendActionResult = (text: string) => {
+  let result: FrontendActionBridgeResult;
+  try {
+    result = JSON.parse(text) as FrontendActionBridgeResult;
+  } catch {
+    throw new Error("frontend action bridge returned invalid JSON");
+  }
+  if (result.version !== "frontend-action-result@1" || typeof result.status !== "string") {
+    throw new Error("frontend action bridge returned an invalid result");
+  }
+  if (result.status !== "succeeded") {
+    const code = result.error?.code?.trim() || `ACTION_${result.status.toUpperCase()}`;
+    const message = result.error?.message?.trim() || `browser action ${result.status}`;
+    throw new Error(`${code}: ${message}`);
+  }
+  if (result.output === undefined) {
+    throw new Error("frontend action bridge returned no output");
+  }
+  return JSON.stringify(result.output);
+};
@@ -0,0 +1,36 @@
+import { tool } from "@opencode-ai/plugin";
+
+import { executeFrontendAction } from "./frontend_action.js";
+
+const sensorId = tool.schema.string().trim().min(1).max(128);
+
+export default tool({
+  description:
+    "将已经完成分析并确定等级的 SCADA 点位结果高亮、编号并定位到前端地图。等级只能来自已完成的分析结论。",
+  args: {
+    reason: tool.schema
+      .string()
+      .trim()
+      .min(1)
+      .describe("Why the completed SCADA analysis should be rendered on the map."),
+    items: tool.schema
+      .array(
+        tool.schema.object({
+          sensor_id: sensorId.describe("Trusted SCADA sensor identifier."),
+          level: tool.schema
+            .enum(["high", "medium", "low", "unrated"])
+            .describe("Completed analysis level; use unrated only when no level was concluded."),
+        }),
+      )
+      .min(1)
+      .max(100)
+      .refine(
+        (items) => new Set(items.map((item) => item.sensor_id)).size === items.length,
+        "sensor_id values must be unique",
+      )
+      .describe("One to one hundred unique SCADA analysis results."),
+  },
+  async execute(args, context) {
+    return executeFrontendAction("render_scada_analysis", args, context);
+  },
+});