FluidGraph Skill

一个由确定性流体网络求解器驱动、通过 Tool Calling 提供 Agent 能力的流体网络分析 Skill。

1. 功能描述

FluidGraph 把一个简化的稳态、不可压缩流体网络建模成图结构，按 TOML 配置和 指定工况计算节点压力、管路流量、流速与压力损失，判定每个负载的功能可靠性， 并给出可解释的失败原因。

所有数值由确定性求解器计算，不由模型产生。 本 Skill 的职责是把这套计算能力 以结构化工具的形式暴露给 Agent，让 Agent 能"问对问题、读懂结果、讲清结论"。

求解是确定性的（无需迭代），同一个网络 + 工况永远得到同一组数值。

2. 支持能力

3. 不支持的能力

遇到不支持的拓扑时

工具不会报错，而是返回合法结论：

{
  "ok": true,
  "data": {
    "topology": {
      "supported": false,
      "unsupported_elements": ["E1", "E2", "E3"],
      "unsupported_reason": "检测到非树状拓扑：元件 E1, E2, E3 位于环上……"
    },
    "loads": [{ "load_id": "L1", "status": "UNSUPPORTED", "pressure": null, "flow": null }]
  }
}

Agent 必须如实告知用户"当前模型不支持该拓扑，无法可靠求解"。

⛔ 禁止编造数值

topology.supported = false 时，pressure / flow / velocity / pressure_drop 全部为 null。禁止自行估算、禁止给出任何数字、禁止"大约是多少"。

supported 为 false 有两种来源，负载状态不同：

4. 三条硬约束

约束 1：null ≠ 0

值	含义
null	没有有效计算值（该部件未参与计算 / 负载不可达）
0	真实的计算结果为零（算过了，结果确实是 0）

pressure = null 表示"根本没有供液"，不是"压力为 0 Pa"。 把两者混为一谈会误导工程判断：0 Pa 意味着"有流体但压力很低"， 与"压根没接上供液"完全是两回事。

报告时一律写"无有效值（null）"，绝不写成 0。

约束 2：required_flow ≠ actual_flow ≠ min_flow

字段	含义
required_flow	该负载在当前工况下需要的流量（求解时的目标值）
flow（actual）	实际送达该负载的流量
min_flow	该负载正常工作的最低要求（阈值）

三者不可互换。判断负载是否正常，看 status 字段，不要自己拿这几个数去比。 当供液受限（配置了 supply_limit）时，实际送达量会小于需求量。

约束 3：Agent 不得自行计算任何物理量

pressure、flow、velocity、pressure_drop、可靠性状态、工况间的数值变化 —— 全部必须来自工具返回的 AnalysisResult。

你没有能力做这些计算。凭空给出数字会误导用户。 工具没有返回某个数值时，如实说"没有这个数据"，不要估算。

5. 业务参数不得猜测

⛔ 这是本 Skill 最重要的一条纪律

如果 TOML 缺少 min_pressure、min_flow、required_flow、resistance、 diameter 等业务/物理参数，Skill 不得自行猜测真实值。

这些参数是工艺设计数据，只有用户知道。举例：

• min_pressure = 300000 取决于下游设备的工作要求；
• resistance = 1.6e9 取决于管材、管长、粗糙度；
• diameter = 0.05 是实际选型。

编造这些数字，再基于编造的数字给出"分析结论"，比直接报错危险得多 —— 用户会以为结论是基于他的真实管网得出的。

正确做法

1. 工具返回结构化错误，含字段位置与修复建议：

   {
     "code": "invalid_numeric_range",
     "location": "[[nodes]][1]",
     "field": "min_pressure",
     "message": "负载节点 'L1' 的 min_pressure 必须为正数，当前值 None",
     "suggestion": "补上 min_pressure 字段，取值必须是正数"
   }
   

2. Agent 向用户询问真实值，而不是自己填一个。

3. 只有在用户明确授权（"随便填个值先跑通"）时，才可以补占位值 —— 且必须在回答里显式标注：

   "min_pressure = 200000.0 是我补的占位值，不是你的原始数据， 它直接影响 LOW_PRESSURE 判定，请按实际工艺要求替换。"

不要做的事

• ❌ 不要因为"这样 Demo 跑起来更方便"就自动补 min_pressure = 200000
• ❌ 不要从同类型元素的其它实例"推断"一个值
• ❌ 不要建立任何隐式的业务推断规则

工具不会自动补这些值（parse_network 会如实报错），Agent 也必须同样克制。

6. 工具列表

所有工具返回统一的 SkillResult 结构。

6.1 parse_network

6.2 analyze_scenario

6.3 analyze_all_scenarios

6.4 explain_load

explanation 字段是一句可直接转述给人听的完整解释，优先使用它。

6.5 compare_scenarios

delta 可能为 null。 当一侧有值、另一侧为 null（负载变得不可达）时， delta 返回 null 并在 notes 说明原因。 这表示"当前值不存在"，不是"下降了很多"。 禁止说"压力下降了 350400 Pa"这种话 —— 那个值根本不存在。 只有两侧都有值时才报告真实变化（如 355650 → 371650，delta = +16000）。

6.6 render_report

报告含：工况、网络状态、流路分析、负载状态、管路状态、可靠性结论、异常与警告。 数值全部取自 AnalysisResult，只做单位换算（Pa→kPa、m³/s→L/s）。

6.7 read_file

没有这个工具就无法完成修复闭环 —— 模型手里只有路径时看不到 TOML 原文， 也就无从修改。

7. 推荐 Agent 调用模式

模式 A：单工况分析

用户：「分析 V1 故障。」

analyze_scenario(scenario_id="v1_failure")
        ↓
直接解释结果

模式 B：故障原因

用户：「为什么 L1 失效？」

analyze_scenario(scenario_id="v1_failure")
        ↓
explain_load(load_id="L1")
        ↓
结合 isolation_point 与 reason 回答

模式 C：工况比较

用户：「比较正常运行和 V1 故障。」

analyze_all_scenarios()                          ← 或两次 analyze_scenario
        ↓
compare_scenarios([normal, v1_failure])
        ↓
逐负载说明变化（注意 null 与 delta 语义）

模式 D：配置修复

用户：给出一份有问题的 TOML

read_file(path)                                  ← 先看到原文
        ↓
parse_network(toml)
        ↓  ok=false，读 errors[].location + suggestion
按 suggestion 修正
        ↓
parse_network(修正后的内联 TOML)                  ← 复验
        ↓
（可能重复多轮）
parse_network 成功
        ↓
analyze_scenario(...)

关键点：Skill 没有写盘权限。修复只能通过 Agent 内联生成 TOML → parse_network 完成，不要尝试写回文件。

8. 输出格式

所有工具返回统一结构：

{
  "ok": true,
  "tool": "analyze_scenario",
  "data": { },
  "errors": [],
  "warnings": []
}

errors 与 warnings 的元素都是结构化诊断：

{
  "code": "unknown_endpoint",
  "severity": "error",
  "message": "管路 'E1' 的 to 引用了不存在的节点 'GHOST'",
  "location": "[[pipes]][0].to",
  "field": "to",
  "suggestion": "把 to 改成已存在的节点 id；当前可用节点：L1, P1",
  "context": { "referenced_node": "GHOST", "available_nodes": ["L1", "P1"] }
}

suggestion 是自我修复的关键 —— Agent 应据此修正后重试，而不是把错误抛给用户。

9. 错误处理

常见错误码

失败不暴露 traceback

任何情况下都不会把 Python traceback 返回给 Agent。 未预期异常会被兜住并 转成 internal_error，异常类型保留在 context.exception_type 里供人排查， 详细堆栈只写日志。

一次性返回全部问题

parse_network 遇到多处错误时会一次报全，而不是改一个跑一次：

{ "ok": false, "errors": [ {"code":"duplicate_id",...}, {"code":"unknown_endpoint",...} ] }

10. 物理模型

严格按照简化模型，未引入任何额外公式（无摩擦因子、无密度、无雷诺数）：

单位一律为 SI，求解器内部不做任何隐式换算：

展示层负责换算（Pa → kPa 除以 1000、m³/s → L/s 乘以 1000）。 JSON 里永远是 SI 原值。

求解方式

以泵为根的树状网络，每条元件都是割边，因此：

• 每条管路的流量 = 它下游全部负载需求之和（节点守恒的直接推论）
• 每个节点的压力 = 父节点压力 − R·Q²
• 确定性，无需迭代

一旦出现环（闭合回路、平行冗余通路、同一对节点上的重边），环上各支路的分流量 必须联立方程求解 —— 此时返回 topology.supported = false，不猜测。

11. 安全边界

read_file 的限制

明确禁止

• ❌ 任意系统路径（C:\Windows\...）
• ❌ /etc/passwd
• ❌ ~/.ssh/id_rsa
• ❌ 路径穿越（../../../../etc/passwd）
• ❌ 与白名单前缀相近的同级目录（/data-evil 不是 /data 的子路径）

越界时返回 path_not_allowed，建议里会列出允许的目录。 拒绝信息中不含被拒文件的内容。

未配置白名单时

read_file 在没有配置沙箱时拒绝一切读取 —— 安全默认是拒绝，而非放行。

Skill 无写盘能力

Agent 不能写任何文件。配置修复只能通过：

Agent 内联生成修正后的 TOML  →  parse_network

12. 版本与兼容性

兼容规则

• ✅ 可以新增字段 —— 消费方必须忽略未知字段
• ❌ 不随意删除字段
• ❌ 不改变字段已有语义
• ⬆️ schema_version 只在 breaking change 时递增

因此：新增能力不会导致版本号变化，只有删除字段或改变语义才会。

消费方应当：

# 好：按需取字段，忽略未知字段
status = data["loads"][0]["status"]

# 不好：假设字段集合固定
assert set(payload) == {...}

13. 独立运行

Skill 可以脱离 Agent 独立使用（Core 与 Skill 层零 LLM 依赖）：

python skill_runner.py parse_network examples/example.toml
python skill_runner.py analyze_scenario examples/example.toml v1_failure
python skill_runner.py explain_load outputs/v1_failure.json L1
python skill_runner.py compare_scenarios outputs/normal.json outputs/v1_failure.json
python skill_runner.py render_report outputs/v1_failure.json
python skill_runner.py --list
python skill_runner.py --schema --format anthropic   # 或 openai / mcp

退出码：0 成功 / 1 工具报告失败 / 2 用法或参数错误。

14. 示例网络

examples/example.toml 是一个可直接运行的演示网络：

       [P1]  泵，出口定压 400 kPa
        |
     MainPipe
        |
       [J1]
      /    \
    [V1]   [V2]
     |       |
    [N1]   [N2]
     |       |
   PipeA    PipeB
     |       |
    [L1]   [L2]     负载，均要求 ≥ 300 kPa

包含两个工况：

另有：

• examples/broken.toml —— 故意写错，用于演示错误自动修复
• examples/ring.toml —— 闭环网络，用于演示 supported = false