# https://github.com/Zhonghao1995/agentic-swmm-workflow 项目说明书 生成时间：2026-07-03 21:36:37 UTC ## 目录 - [项目概览与设计理念](#page-1) - [系统总体架构与目录结构](#page-2) - [核心特性与运行产物](#page-3) - [数据流、案例与制品管理](#page-4) - [CLI、REPL 与用户界面](#page-5) - [MCP 服务器矩阵](#page-6) - [Skill 层体系](#page-7) - [LLM 提供商与 Agent 编排](#page-8) - [建模记忆与 RAG 子系统](#page-9) - [安装方式、依赖与运行环境](#page-10) - [技能扩展与跨 Agent 适配](#page-11) - [审计框架、可重现性与运维故障处理](#page-12) ## 项目概览与设计理念 ### 相关页面 相关主题：[系统总体架构与目录结构](#page-2), [核心特性与运行产物](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/README.md) - [CHANGELOG.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/CHANGELOG.md) - [CITATION.cff](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/CITATION.cff) - [LICENSE](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/LICENSE) - [pyproject.toml](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/pyproject.toml)
# 项目概览与设计理念 ## 项目使命与定位 `agentic-swmm-workflow`（PyPI 包名 `aiswmm`）是一个面向 EPA SWMM（Stormwater Management Model）建模流程的**智能体驱动工作流**，旨在把传统上分散、依赖人工操作的雨水建模步骤，整合为可审计、可复现、可由自然语言触发的端到端流水线。项目的核心定位是：让一个仅包含 WGS84 边界框的自然语言句子，能够驱动排水网络合成、SWMM 运行、确定性审计报告生成与空间网络制图这一整套流程 资料来源：[CHANGELOG.md:1-15]()。 项目配套论文发表于 *AI for Engineering* 期刊（DOI: 10.3390/aieng1010005），标题为《Agentic SWMM: Auditable and Reproducible Stormwater Modelling Workflow with Agent Skills and Model Context Protocol》，奠定了其学术与工程双重身份 资料来源：[CITATION.cff:1-15]()。 ## 核心设计理念 ### 可审计与可复现优先 工作流把每一次运行结果落到标准化的 `runs///` 目录布局下，确保审计溯源（audit dossier）与制图产物都能在文件系统中追溯。自 v0.6.4 起，项目明确主张**字节级可复现性**（byte-reproducibility），通过固定依赖版本与自动构建 Docker 镜像来支撑论文中的可复现性声明 资料来源：[CHANGELOG.md:1-20]()。 ### 智能体技能（Agent Skills）+ 模型上下文协议（MCP） 项目采用**技能化架构**，把不同建模能力封装为可独立调用的「技能」，并通过 Model Context Protocol 暴露给上层智能体。这种设计使得校准（calibration）、灵敏度分析（sensitivity）、设计暴雨（design storms）、记忆可观测性（memory observability）等能力能够被智能体按需拉起，而不是硬编码在单一脚本里 资料来源：[CHANGELOG.md:1-30]()。 ### 内存与状态的可观测性 建模记忆（modeling memory）是 0.7.x 系列的主线之一。`aiswmm doctor` 命令新增了 `Sessions store` 状态行（ok / corrupt / unreadable / absent），并在出现数据损坏时返回非零退出码，使 CI 健康检查能够捕捉数据丢失风险 资料来源：[CHANGELOG.md:1-40]()。 ### 渐进式发布与不可变性 项目采用 PEP 440 的预发布标签机制（`a1`、`a2`）来管理 alpha 阶段，使 `pip install aiswmm` 始终指向稳定版，而预发布特性通过 `pip install aiswmm==0.x.y a1` 显式启用 资料来源：[CHANGELOG.md:1-50]()。 ## 架构概览 工作流从用户输入到最终产物的数据流，可概括为四个阶段： ```mermaid flowchart LR A[自然语言请求
含 WGS84 bbox] --> B[网络合成
OSM + DEM] B --> C[SWMM 引擎运行] C --> D[审计 dossier
+ 空间网络图] D --> E[runs/日期/ID/
目录产物] ``` 合成阶段依赖 SWMManywhere（Imperial College 团队成果），从公开的 OSM 与 DEM 数据中重建排水网络 资料来源：[CHANGELOG.md:1-15]()。安装体验方面，v0.7.3 重写了一行式安装脚本，Windows 平台默认克隆到 `%LOCALAPPDATA%` 并设置进程级 `ExecutionPolicy Bypass`，避免写入受保护的 `C:\Windows\System32` 目录 资料来源：[CHANGELOG.md:1-10]()。 ## 关键能力矩阵 下表汇总了当前版本（v0.7.4）所累积的核心能力，按发布线区分： | 能力 | 引入版本 | 用途 | 资料来源 | |---|---|---|---| | 端到端自然语言流水线 | v0.7.1 | 由 bbox 句子驱动完整建模 | [CHANGELOG.md:1-15]() | | 设计暴雨（design storms） | v0.7.2 | 合成降雨情景输入 | [CHANGELOG.md:1-30]() | | 智能体可达的校准与灵敏度 | v0.7.2 | 参数标定与不确定性分析 | [CHANGELOG.md:1-30]() | | 建模记忆可观测性 | v0.7.0 | sessions 状态检查与修复 | [CHANGELOG.md:1-40]() | | 字节级可复现性 | v0.6.4 | 固定依赖 + Docker 镜像 | [CHANGELOG.md:1-20]() | ## 安装与版本契约 - 默认安装：`pip install aiswmm` 获取最新稳定版。 - 可选 provider：`pip install "aiswmm[claude]==0.7.0a1"` 启用 Claude Agent SDK 提供方。 - 预发布：`pip install --pre aiswmm` 允许任意预发布版本 资料来源：[CHANGELOG.md:1-50]()。 这种双轨发布契约保证了主线用户不被 alpha 变更打扰，同时让早期采用者能锁定特定 pre-release 进行内部验证。 ## 设计权衡与边界 项目在「智能体自治」与「确定性输出」之间做了显式权衡： - **自治面**：自然语言驱动、技能按需调用、智能体可在多个技能间编排。 - **确定性面**：固定目录布局、字节级可复现声明、Sessions 完整性校验、CI 友好的非零退出码。 这两条线分别落在不同的子系统里：自治由 MCP 智能体运行时承担，确定性由文件系统布局、版本钉死与 Docker 镜像承担 资料来源：[CHANGELOG.md:1-40]()。 ## 许可与引用 项目采用开源许可证（详见 [LICENSE]()）。学术使用时，建议通过 [CITATION.cff]() 中提供的 DOI 引用配套论文，以确保方法学可追溯。 --- ## 系统总体架构与目录结构 ### 相关页面 相关主题：[项目概览与设计理念](#page-1), [MCP 服务器矩阵](#page-6), [Skill 层体系](#page-7)
相关源码文件 以下源码文件用于生成本页说明： - [agentic_swmm/__init__.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/__init__.py) - [agentic_swmm/cli.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/cli.py) - [agentic_swmm/config.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/config.py) - [agentic_swmm/runtime/registry.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/runtime/registry.py) - [agentic_swmm/runtime/agent.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/runtime/agent.py) - [agentic_swmm/mcp/server.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/mcp/server.py) - [agentic_swmm/memory/store.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/memory/store.py) - [agentic_swmm/skills/__init__.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/skills/__init__.py) - [pyproject.toml](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/pyproject.toml) - [docs/repo-map.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/docs/repo-map.md)
# 系统总体架构与目录结构 ## 1. 设计目标与架构概览 `agentic-swmm-workflow`（发布到 PyPI 时包名为 `aiswmm`）是一个面向 EPA SWMM（暴雨水管理模型）的"代理化"工作流框架。它通过 **Agent Skills** 与 **Model Context Protocol (MCP)** 把自然语言意图转化为可审计、可复现的 SWMM 建模流程（资料来源：[agentic_swmm/__init__.py:1-40]()）。整个系统强调三点：确定性审计（每次运行产出 `runs/<日期>//` 目录）、字节级可复现（v0.6.4 起锁定依赖与 Docker 镜像）、以及记忆可观测（v0.7.0a2 起 `Sessions store` 健康检查成为 `aiswmm doctor` 的标准动作）。 整体架构由四层组成，自顶向下依次为 CLI 入口层、运行时层、技能层与记忆/外部引擎层： ```mermaid flowchart TB U[用户 / 代理客户端] --> CLI[aiswmm CLI
cli.py] CLI --> RT[运行时层
runtime/] RT --> SK[技能库
skills/] RT --> MEM[记忆子系统
memory/] SK --> SWMM[SWMM / SWMManywhere
外部引擎] RT --> MCP[MCP 服务
mcp/server.py] ``` - **CLI 入口层**：以 `aiswmm` 命令对外暴露，包含 `doctor`、`memory`、`calibrate` 等子动词（资料来源：[agentic_swmm/cli.py:1-80]()）。 - **运行时层**：注册中心与代理循环，负责调度技能、维护会话状态（资料来源：[agentic_swmm/runtime/registry.py:1-60]()）。 - **技能层**：每个技能封装一段可被代理调用的类型化工具，例如管网综合、敏感性、设计暴雨、校准（资料来源：[agentic_swmm/skills/__init__.py:1-50]()）。 - **记忆与外部引擎层**：持久化建模记忆，调用 SWMM 或 SWMManywhere（Imperial College 开源管网合成器）完成水力计算（资料来源：[agentic_swmm/memory/store.py:1-80]()）。 ## 2. 顶层目录布局 项目根目录按"包代码 / 配置 / 文档 / 安装脚本"四类组织（资料来源：[docs/repo-map.md:1-120]()）： - `agentic_swmm/`：核心 Python 包，对外发布名为 `aiswmm`。 - `agentic_swmm/runtime/`：代理运行时，包含 `registry.py`、`agent.py` 等模块，负责技能注册与循环调度。 - `agentic_swmm/skills/`：技能定义目录，按能力垂直拆分（网络综合、敏感性、设计暴雨、校准等）。 - `agentic_swmm/mcp/`：MCP 服务端实现，供外部代理（如 Claude Agent SDK）发现与调用工具。 - `agentic_swmm/memory/`：会话与建模记忆存储，提供 `repair-sessions` 等修复动词。 - `docs/`：用户文档、仓库地图、教程；`repo-map.md` 是仓库结构的权威说明。 - `pyproject.toml`：构建、打包与可选 extras（如 `aiswmm[claude]`）的声明文件（资料来源：[pyproject.toml:1-60]()）。 - `install_*.{ps1,sh}`：一行安装脚本，在 v0.7.3 中被修订为默认安装最新发布版，并将 Windows 端克隆到 `%LOCALAPPDATA%` 以避开 `C:\Windows\System32` 的写保护。 ## 3. 核心子系统划分 ### 3.1 CLI 与入口 `agentic_swmm/cli.py` 是唯一的命令行入口，使用 Click/Typer 风格的子命令组织方式。`aiswmm doctor` 在 v0.7.0a2 之后增加了 `Sessions store` 行，状态枚举为 `ok / corrupt / unreadable / absent`，当出现 `CORRUPT/UNREADABLE` 时返回非零退出码，便于 CI 捕获数据丢失（资料来源：[agentic_swmm/cli.py:30-120]()）。 ### 3.2 运行时与技能注册 `runtime/registry.py` 维护"技能名 → 调用对象"的映射，技能通过装饰器或显式注册方式注入。运行时驱动"思考—调用技能—写入记忆"的循环，确保每次运行都能在 `runs/<日期>//` 下留下确定性审计材料（资料来源：[agentic_swmm/runtime/agent.py:1-100]()）。v0.6.3a1 起，原本散落在 6 个文件中的关键词匹配逻辑被合并到注册中心，统一技能发现语义。 ### 3.3 记忆子系统 `memory/store.py` 提供会话的写入、读取与一致性校验。`aiswmm memory repair-sessions` 动词即调用该模块的修复路径，使运维或 CI 能识别并恢复损坏的会话存储（资料来源：[agentic_swmm/memory/store.py:40-140]()）。 ### 3.4 MCP 服务 `mcp/server.py` 把同一组技能通过 Model Context Protocol 暴露给外部代理，实现"同一能力、双通道调用"——既可走 CLI，也可被支持 MCP 的客户端直接发现。这也是 v0.7.2 论文 *Agentic SWMM: Auditable and Reproducible Stormwater Modelling Workflow with Agent Skills and Model Context Protocol* 的核心贡献之一（资料来源：[agentic_swmm/mcp/server.py:1-80]()）。 ## 4. 一次典型运行的数据流 以"给定 WGS84 边界框，端到端生成 SWMM 模型"为例（v0.7.1 引入），数据流如下： 1. 用户通过 CLI 或 MCP 提交自然语言指令，运行时在 `agentic_swmm/config.py` 解析全局配置后启动会话。 2. 运行时从 `runtime/registry.py` 中检索"网络综合"与"运行 SWMM"两类技能。 3. 技能层调用 SWMManywhere 合成管网（基于 OSM + DEM），再调用 SWMM 完成水力求解。 4. `memory/store.py` 把每一步的输入、参数、产物写入 `runs///`，形成审计 dossier。 5. 渲染脚本产出空间网络图与确定性报告（资料来源：[agentic_swmm/runtime/agent.py:60-160]()）。 这种"分层 + 显式审计目录"的设计，是项目同时满足**可复现性**（v0.6.4 起锁定依赖与 Docker 镜像）与**可审计性**（v0.7.0 起 Sessions 完整性检查）两大诉求的结构基础（资料来源：[docs/repo-map.md:80-140]()）。 --- ## 核心特性与运行产物 ### 相关页面 相关主题：[数据流、案例与制品管理](#page-4), [建模记忆与 RAG 子系统](#page-9)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/README.md) - [agentic_swmm/agent/single_shot.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/single_shot.py) - [agentic_swmm/audit/run_folder_layout.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/audit/run_folder_layout.py) - [docs/modeling-memory-and-skill-evolution.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/docs/modeling-memory-and-skill-evolution.md) - [agentic_swmm/memory/sessions.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/memory/sessions.py) - [agentic_swmm/cli.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/cli.py) - [pyproject.toml](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/pyproject.toml)
# 核心特性与运行产物 ## 概述与项目定位 agentic-swmm-workflow 是一个面向 SWMM（Storm Water Management Model）城市雨洪建模的智能体化工作流框架，对外由 `aiswmm` CLI 统一入口提供服务。其核心理念是把分散的建模动作——**网络合成、水力计算、结果审计、地图渲染**——编排为一个可审计、可复现的端到端流程，并由自然语言提示（natural-language prompt）直接驱动。框架通过 MCP（Model Context Protocol）以类型化工具（typed tools）的形式把建模能力暴露给 LLM，避免自由文本解析带来的歧义。论文 *Agentic SWMM: Auditable and Reproducible Stormwater Modelling Workflow with Agent Skills and Model Context Protocol*（DOI: 10.3390/aieng1010005）随 v0.7.2 一同发布，对该定位做了形式化描述。 资料来源：[README.md:1-40]()、[docs/modeling-memory-and-skill-evolution.md:1-25]() ## 端到端工作流：自然语言一句直达产物 自 v0.7.1 起，用户只需要一句仅引用 WGS84 包围盒（BBOX）的自然语言指令，系统即可完成全流程，由 `agentic_swmm/agent/single_shot.py` 中的 single-shot agent 编排： 1. **网络合成**：从公开 OSM + DEM 数据出发，借助 SWMManywhere（Imperial College）合成排水管网。 2. **水力计算**：调用 SWMM 引擎执行模拟。 3. **审计档案**：写入确定性审计 dossier（deterministic audit dossier），包含输入哈希、依赖指纹、引擎版本。 4. **空间可视化**：渲染空间网络地图（spatial network map）。 整个流水线在用户视角下是一条不可拆分的"一句话任务"，但内部被拆解为多个类型化工具调用，从而保留可追溯性。 资料来源：[agentic_swmm/agent/single_shot.py:1-80]()、[README.md:42-78]() ## 标准运行产物布局 `runs///` 每一次执行都被写入统一目录 **`runs///`**，由 `agentic_swmm/audit/run_folder_layout.py` 定义与校验，保证跨环境、跨时间的 byte-level 可复现。 | 子目录 / 文件 | 用途 | | --- | --- | | `inp/` | SWMM `.inp` 输入文件，以及从 OSM / DEM 合成得到的原始管网数据 | | `out/` | SWMM 引擎输出报告（`.rpt` / `.out`） | | `audit/` | 确定性审计档案、配置快照、依赖锁文件 | | `map/` | 渲染后的空间网络地图（PNG / HTML） | | `manifest.json` | 本次运行的元数据哈希、版本指纹、引擎版本号 | `manifest.json` 是审计的关键锚点：相同 manifest 在不同机器上应能复现出 byte-identical 的 `out/` 结果，对应 v0.6.4 引入的 byte-reproducibility hardening 承诺。 资料来源：[agentic_swmm/audit/run_folder_layout.py:1-120]()、[README.md:80-110]()、[pyproject.toml:1-30]() ## 智能体技能与建模记忆 v0.7.2 引入三项智能体可直接调用的技能，并以 MCP 类型化工具方式暴露： - **calibration**：参数率定 - **sensitivity**：敏感性分析 - **design storms**：设计暴雨生成 LLM 不再通过关键词匹配或自由文本来猜测意图，而是直接调用这些技能。这一变化来自 v0.6.3a1 的关键词匹配重构（散落在 6 个文件中的逻辑被合并到单一调度器），以及 v0.7.2 的 typed-tool surface。 建模记忆（modeling memory）通过 `agentic_swmm/memory/sessions.py` 持久化到本地 sessions 存储；`aiswmm doctor` 命令自 v0.7.0a2 起新增 *Sessions store* 行，以四态（ok / corrupt / unreadable / absent）报告完整性，并在 CORRUPT 或 UNREADABLE 时返回非零退出码，便于 CI 健康检查；`aiswmm memory repair-sessions` 可在上述异常状态下执行修复。 资料来源：[docs/modeling-memory-and-skill-evolution.md:1-50]()、[agentic_swmm/memory/sessions.py:1-60]()、[agentic_swmm/cli.py:60-140]() ## 审计、可复现性与运维保障 围绕"产物可信"这一目标，框架提供三层保障： 1. **依赖锁定**：`pyproject.toml` 锁定精确版本字符串；`pip install aiswmm==` 或 Docker 镜像给出确定的运行时。 2. **运行期审计**：每次运行写入环境指纹、输入哈希、SWMM 版本号，第三方可对照同一 manifest 复现。 3. **运行期健康检查**：`aiswmm doctor` 把 sessions 存储的损坏情况纳入 CI 闸口，避免数据丢失条件被静默忽略。 社区用户在 v0.7.3 之前曾反馈 Windows one-line installer 写入 `C:\Windows\System32` 失败的问题，该版本已修复：克隆目录改为 `%LOCALAPPDATA%`，并设置进程级 `ExecutionPolicy Bypass`，使产物生成链路在新机器上可一键搭建。 资料来源：[pyproject.toml:1-40]()、[agentic_swmm/cli.py:1-60]()、[README.md:110-150]() --- ## 数据流、案例与制品管理 ### 相关页面 相关主题：[核心特性与运行产物](#page-3), [审计框架、可重现性与运维故障处理](#page-12)
相关源码文件 以下源码文件用于生成本页说明： - [agentic_swmm/case/case_registry.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/case/case_registry.py) - [agentic_swmm/case/case_defaults.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/case/case_defaults.py) - [agentic_swmm/case/case_id.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/case/case_id.py) - [cases/tecnopolo/case_meta.yaml](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/cases/tecnopolo/case_meta.yaml) - [cases/todcreek/case_meta.yaml](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/cases/todcreek/case_meta.yaml) - [runs/README.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/runs/README.md)
# 数据流、案例与制品管理 ## 概述与目标 `agentic-swmm-workflow` 把每一次 SWMM 运行都视为一个**案例（case）**：由一份可复现的元数据驱动，经过数据合成、SWMM 模拟、审计与制图，最终落到一个确定性的目录布局里。该子系统负责把"输入约定 → 案例检索 → 制品落盘"这条链路显式化，使 Agent 在自然语言指令下仍能产出可审计、可重放的产物。 资料来源：[runs/README.md:1-40]() ## 案例注册表（CaseRegistry） `case_registry.py` 提供 `CaseRegistry` 类，作为案例的生命中枢。其职责包括： - **索引扫描**：启动时扫描 `cases/` 目录，识别含 `case_meta.yaml` 的子目录作为合法案例；非法目录会被忽略但不会中断启动。 - **ID 解析**：将每个案例目录名映射为短 ID，可通过前缀模糊匹配定位案例，便于 Agent 在不知道完整路径时仍能解析意图。 - **元数据装载**：每个 `case_meta.yaml` 反序列化为字典缓存，供下游 Skill 与 Tool 查询。 - **来源区分**：内置案例（`cases/`）与运行产生案例（`runs/`）来自不同根路径，注册表维护两套视图，避免相互污染。 ```mermaid flowchart LR A[用户/Agent 指令] --> B[CaseRegistry] C[cases/ 案例树] --> B D[runs/ 历史产物] --> B B --> E[case_meta.yaml 装载] B --> F[前缀匹配/短 ID 解析] E --> G[下游 Skill/Tool] F --> G G --> H[runs/lt;date/gt;lt;id/gt;/ 制品] ``` 资料来源：[agentic_swmm/case/case_registry.py:1-80]() ## 案例默认值与 ID 生成 `case_defaults.py` 集中维护**跨案例共享的默认值**（单位、时间步、报告字段、空间参考等），被各案例的 `case_meta.yaml` 通过继承式合并引用。这种方式有两个收益： - **降低重复**：常规建模参数只写一次，案例文件只覆盖差异字段。 - **统一版本**：当默认值随 SWMMAnywhere、pyswmm 等依赖更新时，仅需修改一处。 `case_id.py` 则提供确定性的短 ID 生成： - 基于案例名、创建日期、随机后缀组合为 `--` 形式的目录名。 - ID 写入 `runs///` 路径，确保每次运行都自带可追溯的指纹目录。 资料来源：[agentic_swmm/case/case_defaults.py:1-60]()、[agentic_swmm/case/case_id.py:1-50]() ## 案例元数据样例 两个内置案例 `tecnopolo` 与 `todcreek` 展示了 `case_meta.yaml` 的常见字段： - **空间范围**：以 WGS84 边界框或 GeoJSON 多边形给定研究区； - **数据源声明**：OSM 路段、DEM、降雨驱动等外部数据集的统一资源标识； - **场景表**：设计暴雨、降雨时间序列或多组参数化情景； - **目标字段**：水位、流量、溢流等被报告的指标与阈值。 | 字段类别 | `tecnopolo` 示例值 | `todcreek` 示例值 | | --- | --- | --- | | 边界输入 | WGS84 bbox | WGS84 bbox + 子集多边形 | | 合成后端 | SWMManywhere | SWMManywhere | | 设计暴雨 | 2/5/10 年 | 2/5/10/50 年 | | 报告字段 | depth, flooding | depth, flow, flooding | 资料来源：[cases/tecnopolo/case_meta.yaml:1-40]()、[cases/todcreek/case_meta.yaml:1-40]() ## 制品与运行目录布局 每次运行都在 `runs/` 下创建独立的、按日期+ID 分层的目录，所有中间与最终制品均写入该目录，确保一份"审计凭证"独立且自洽。 典型 `runs///` 内容： - `case_meta.yaml`——运行时刻冻结的元数据副本； - `model.inp` 与 `model.rpt`/`model.out`——SWMM 输入与原始输出； - `audit/`——确定性审计档案（哈希、参数表、依赖锁）； - `network_map.html`/`.png`——空间网络可视化； - `log.txt`——Agent 与 Skill 的调用轨迹。 `runs/README.md` 明确指出该布局的不可变性约束：同 ID 的运行一旦落盘便不再覆盖，二次运行将获得新目录，从而保证历史制品的字节级可追溯（v0.6.4 起）。 ```text runs/ ├── 2026-05-27/ │ ├── 20260527-tecnopolo-7af3/ │ │ ├── case_meta.yaml │ │ ├── model.inp │ │ ├── audit/ │ │ └── network_map.html │ └── 20260527-todcreek-1b22/ │ └── ... ``` 资料来源：[runs/README.md:1-60]() ## 与审计 / 复现性的关系 自 v0.6.4（byte-reproducibility hardening）以来，案例元数据、依赖锁与制品哈希共同构成复现单元；`aiswmm doctor` 在 v0.7.0a2 后还会对 `runs/` 存储做完整性巡检，读到损坏或缺失会返回非零退出码以便 CI 接入。这意味着 **案例与制品管理不仅是文件组织约定，还是系统的健康度信号源**。 资料来源：[agentic_swmm/case/case_registry.py:60-120]() --- ## CLI、REPL 与用户界面 ### 相关页面 相关主题：[MCP 服务器矩阵](#page-6), [LLM 提供商与 Agent 编排](#page-8)
相关源码文件 以下源码文件用于生成本页说明： - [agentic_swmm/cli.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/cli.py) - [agentic_swmm/agent/repl.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/repl.py) - [agentic_swmm/agent/ui.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/ui.py) - [agentic_swmm/agent/welcome.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/welcome.py) - [agentic_swmm/agent/warm_intro.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/warm_intro.py) - [agentic_swmm/agent/session_bootstrap.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/session_bootstrap.py)
# CLI、REPL 与用户界面 ## 一、整体架构：CLI、REPL、UI 三层职责 `aiswmm` 的用户入口由三层组成：CLI 命令层（`agentic_swmm/cli.py`）、Agent REPL 循环（`agentic_swmm/agent/repl.py`、`agentic_swmm/agent/session_bootstrap.py`）与用户界面渲染（`agentic_swmm/agent/ui.py`、`agentic_swmm/agent/welcome.py`、`agentic_swmm/agent/warm_intro.py`）。CLI 把脚本式调用、子命令分发与诊断（`aiswmm doctor`、`aiswmm memory ...`）串起来；REPL 维护一次会话的输入/输出循环与状态；UI 层把 agent 的中间事件渲染为富文本或纯文本，并把"欢迎语"和"暖场介绍"做成有状态的内容，避免每次问候都重发同一段文案。 ``` ┌──────────────────────────────────────────────────────────┐ │ CLI (cli.py) — aiswmm [...] │ │ ├─ doctor / memory.* 子动词 │ │ ├─ 一行安装命令（Windows / Linux / macOS） │ │ └─ 关键字匹配（v0.6.3a1 后收敛到单一来源） │ └──────────────────────────┬───────────────────────────────┘ │ ┌──────────────────────────▼───────────────────────────────┐ │ REPL (repl.py + session_bootstrap.py) │ │ ├─ 首次会话：建模记忆加载、目录可写性校验 │ │ └─ 主循环：标准输入读取、状态门控 │ └──────────────────────────┬───────────────────────────────┘ │ ┌──────────────────────────▼───────────────────────────────┐ │ UI (ui.py / welcome.py / warm_intro.py) │ │ ├─ 欢迎横幅（每次启动） │ │ ├─ 暖场介绍（每会话一次，受状态门控） │ │ └─ 工具事件富文本渲染（颜色 / 表格 / 进度） │ └──────────────────────────────────────────────────────────┘ ``` 资料来源：[agentic_swmm/cli.py]()，[agentic_swmm/agent/repl.py]()，[agentic_swmm/agent/session_bootstrap.py]() ## 二、CLI 命令层与 REPL 会话循环 ### 2.1 CLI 子动词体系 `cli.py` 是 `pip install aiswmm` 安装后的入口二进制。从 v0.7.x 系列发布说明看，CLI 已经形成了"主命令 + 子动词"的形态： - `aiswmm doctor`：环境与状态自检，包含 `Sessions store` 完整性检查（ok / corrupt / unreadable / absent 四态），CORRUPT/UNREADABLE 时退出码非零，便于 CI 捕获数据丢失情况。 - `aiswmm memory repair-sessions`：对损坏的会话存储执行就地修复（v0.7.0a2 引入）。 - 一次性安装命令：v0.7.3 重写后，Windows 改为克隆到 `%LOCALAPPDATA%`（避开 `C:\Windows\System32` 的写保护）并在进程内设置 `ExecutionPolicy Bypass`；Linux/macOS 直接走官方安装脚本，默认指向最新发布版本。 CLI 在 0.6.x 期间经历过一次重构：原本散落在 6 个文件里的关键字匹配被合并到单一来源（v0.6.3a1），目的是把"用一句话识别用户意图"的入口统一在 CLI 阶段就完成，避免下游 REPL 与各 skill 重复解析同一份输入。 资料来源：[agentic_swmm/cli.py]() ### 2.2 REPL 与会话引导 `repl.py` 提供交互式 REPL：当用户不指定子命令、或显式进入 agent 模式时，由它接管标准输入循环。`session_bootstrap.py` 负责"会话首次打开"的工作——加载历史会话、初始化 v0.7.0 引入的"建模记忆"、校验存储目录是否可写，并把控制权交给 REPL 主循环。 REPL 的输入与 CLI 共享同一套关键字解析，但会话级别的状态（例如"已经做过暖场介绍"）由 `warm_intro.py` 内的状态标记维护：v0.6.2a1 修复 #108 后，暖场介绍只在每次会话首次出现，而不会在每次用户说 `hi`/`hello` 时重复触发——这是 REPL 与 UI 协同的关键：解析层只关心意图，门控层只关心"是否首次"。 资料来源：[agentic_swmm/agent/repl.py]()，[agentic_swmm/agent/session_bootstrap.py]()，[agentic_swmm/agent/warm_intro.py]() ## 三、用户界面渲染：欢迎、暖场与富文本 `ui.py` 是 agent 输出层的渲染工具，负责把工具调用、文件写入、SWMM 运行日志等事件格式化为终端可读的片段（颜色、表格、进度条）。`welcome.py` 在每次启动时打印欢迎横幅与版本信息；`warm_intro.py` 则是一段简短的"我能帮你做什么"式介绍，受会话状态门控。 三者协同工作，确保：首次安装后第一次运行既有欢迎横幅也有能力介绍；后续交互不会重复触发介绍造成噪音；当 agent 调用工具时，`ui.py` 把中间事件转成结构化展示，便于审计——这与 v0.7.1 引入的"确定性审计档案"理念一致，所有中间事件在终端可见的同时也会落到 `runs///` 的结构化目录中。 资料来源：[agentic_swmm/agent/ui.py]()，[agentic_swmm/agent/welcome.py]()，[agentic_swmm/agent/warm_intro.py]() ## 四、版本演进与安装体验时间线 - v0.6.2a1：暖场介绍修复为每会话一次（#108），修复前用户重复打招呼会反复打印同一段介绍。 - v0.6.3a1：关键字匹配从 6 个文件收敛到单一来源，影响 CLI 与 REPL 的入口解析路径。 - v0.7.0：默认 `pip install aiswmm` 指向 0.7.0，安装体验整体改善。 - v0.7.0a2：`doctor` 新增 `Sessions store` 完整性行与 `memory repair-sessions` 动词；CLI 退出码可被 CI 用于失败判定。 - v0.7.3：重写 Windows / Linux / macOS 一行安装命令，默认安装最新发布版本；Windows 修复了写入 `C:\Windows\System32` 的权限问题，改为克隆到 `%LOCALAPPDATA%`。 资料来源：[agentic_swmm/cli.py]()，[agentic_swmm/agent/warm_intro.py]() ## 附：源码定位入口 要在本地复现这套用户面，从下面三个文件入手最直观： - 顶层入口：[agentic_swmm/cli.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/cli.py) - 会话循环：[agentic_swmm/agent/repl.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/repl.py) - 渲染与欢迎：[agentic_swmm/agent/ui.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/ui.py) --- ## MCP 服务器矩阵 ### 相关页面 相关主题：[Skill 层体系](#page-7), [技能扩展与跨 Agent 适配](#page-11)
相关源码文件 以下源码文件用于生成本页说明： - [mcp/swmm-builder/server.js](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/mcp/swmm-builder/server.js) - [mcp/swmm-runner/server.js](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/mcp/swmm-runner/server.js) - [mcp/swmm-calibration/server.js](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/mcp/swmm-calibration/server.js) - [mcp/swmm-network/server.js](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/mcp/swmm-network/server.js) - [integrations/mcp/README.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/integrations/mcp/README.md) - [integrations/mcp/generated/openclaw-mcp.config.json](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/integrations/mcp/generated/openclaw-mcp.config.json)
# MCP 服务器矩阵 ## 1. 概述与设计目标 Agentic SWMM 将 SWMM（暴雨水管理模型）的整个建模生命周期拆解为四个并行的 Model Context Protocol（MCP）服务器，统称为"MCP 服务器矩阵"。它们各自暴露一组类型化工具（typed tools），供 Claude、OpenClaw 等智能体直接调用，从而把"自然语言意图 → 可审计的 SWMM 工作流"这一闭环以协议化方式暴露给上层 agent runtime。资料来源：[integrations/mcp/README.md:1-40]()。 矩阵的设计目标包括： - **职责单一**：每个服务器对应一个建模阶段（构建、运行、率定、网络合成），避免单一巨型 server.js 难以维护。 - **本地可执行**：服务器以 Node.js `server.js` 形态直接运行，无需额外守护进程，便于在 `runs///` 产物目录下记录调用日志。 - **可发现性**：通过 `integrations/mcp/generated/openclaw-mcp.config.json` 自动生成配置，使 agent runtime 在启动时按矩阵声明发现工具。资料来源：[integrations/mcp/generated/openclaw-mcp.config.json:1-40]()。 ## 2. 矩阵中的四个服务器 | 服务器 | 入口文件 | 主要职责 | 关键工具类型 | | --- | --- | --- | --- | | `swmm-builder` | [mcp/swmm-builder/server.js]() | 由 WGS84 边界框 + OSM/DEM 数据合成排水网络并生成 `.inp` | 网络合成、输入文件构造 | | `swmm-runner` | [mcp/swmm-runner/server.js]() | 调用 SWMM 引擎执行 `.inp`，产出报告与确定性审计档案 | 模拟执行、结果解析 | | `swmm-calibration` | [mcp/swmm-calibration/server.js]() | 暴露率定与敏感性分析能力，供 agent 在 v0.7.2 之后调用 | 参数率定、敏感度扫描 | | `swmm-network` | [mcp/swmm-network/server.js]() | 提供空间网络渲染与查询工具 | 地图渲染、子网查询 | 四个 server.js 均位于 `mcp//` 子目录下，保持入口文件命名前缀 `server.js` 一致，便于运行时枚举。资料来源：[integrations/mcp/README.md:20-60]()。 ## 3. 与 Agent Runtime 的集成方式 集成层位于 `integrations/mcp/`，它承担三件事： 1. **配置生成**：`integrations/mcp/generated/openclaw-mcp.config.json` 中列出每个服务器的命名、入口命令和传输协议，agent runtime 据此按矩阵并行启动多个 MCP 连接。资料来源：[integrations/mcp/generated/openclaw-mcp.config.json:1-40]()。 2. **使用说明**：`integrations/mcp/README.md` 描述了如何将矩阵注册到不同的 agent runtime（OpenClaw、Claude Agent SDK 等），并解释了类型化工具在 v0.7.2 中由"散落在 6 个文件的关键词匹配"统一收敛后的发现方式。资料来源：[integrations/mcp/README.md:40-80]()。 3. **可观测性**：矩阵内每个调用都通过 `runs///` 布局落地，确保 agent 决策与底层 SWMM 产物可逐次回放。资料来源：[integrations/mcp/README.md:60-100]()。 ## 4. 端到端调用流程 ```mermaid flowchart LR A[Agent Runtime] --> B[swmm-builder] B --> C[.inp 文件] C --> D[swmm-runner] D --> E[审计档案 / 报告] D --> F[swmm-calibration] F --> D D --> G[swmm-network] G --> A ``` 流程说明： - **构造阶段**：`swmm-builder` 接收 WGS84 边界框或 OSM/DEM 输入，合成排水网络并写出 `.inp`。资料来源：[mcp/swmm-builder/server.js:1-60]()。 - **执行阶段**：`swmm-runner` 加载该 `.inp`，调用 SWMM 引擎，并把 stdout/stderr、报告文件归档到 `runs///`。资料来源：[mcp/swmm-runner/server.js:1-60]()。 - **率定阶段**：当用户提出校准或敏感性需求时，`swmm-calibration` 介入，必要时回写到 runner 重跑。资料来源：[mcp/swmm-calibration/server.js:1-60]()。 - **可视化阶段**：`swmm-network` 把节点、管道、子汇水区渲染为空间地图，供 agent 在对话中回贴给用户。资料来源：[mcp/swmm-network/server.js:1-60]()。 ## 5. 版本演进与社区关注点 - v0.7.2 在矩阵中正式加入 **agent-reachable calibration & sensitivity** 能力，对应 `swmm-calibration` 的类型化工具面。资料来源：[v0.7.2 发布说明]()。 - v0.6.3a1 将"散落在 6 个文件的关键词匹配"统一收敛到单一发现器，使四个 server.js 不再各自维护解析逻辑，对长期维护矩阵稳定性影响显著。资料来源：[v0.6.3a1 发布说明]()。 - 论文 *Agentic SWMM: Auditable and Reproducible Stormwater Modelling Workflow with Agent Skills and Model Context Protocol*（DOI: 10.3390/aieng1010005）以该矩阵作为可审计、可复现工作流的核心论证材料。资料来源：[v0.7.2 发布说明]()。 ## 6. 扩展新服务器的建议 新增一个 MCP 服务器时，建议遵循矩阵既有约定： 1. 在 `mcp//server.js` 下实现入口，遵循既有 server.js 的命名与导出风格。资料来源：[integrations/mcp/README.md:80-120]()。 2. 在 `integrations/mcp/generated/openclaw-mcp.config.json` 中追加对应条目，使 agent runtime 自动发现。资料来源：[integrations/mcp/generated/openclaw-mcp.config.json:1-40]()。 3. 确保所有产物写入标准的 `runs///` 布局，并补充 `aiswmm doctor` 中相应健康检查行，以维持矩阵整体的可观测性。资料来源：[integrations/mcp/README.md:100-140]()。 如此，MCP 服务器矩阵既能持续承载 SWMM 建模各阶段，也能让 agent runtime 在不改动协议层的前提下获得新增能力。 --- ## Skill 层体系 ### 相关页面 相关主题：[MCP 服务器矩阵](#page-6), [技能扩展与跨 Agent 适配](#page-11)
相关源码文件 以下源码文件用于生成本页说明: - [skills/swmm-end-to-end/SKILL.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/skills/swmm-end-to-end/SKILL.md) - [skills/swmm-builder/SKILL.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/skills/swmm-builder/SKILL.md) - [skills/swmm-calibration/SKILL.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/skills/swmm-calibration/SKILL.md) - [skills/swmm-climate/SKILL.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/skills/swmm-climate/SKILL.md) - [skills/swmm-network/SKILL.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/skills/swmm-network/SKILL.md) - [skills/skill-author/SKILL.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/skills/skill-author/SKILL.md)
# Skill 层体系 ## 概述 Skill 层是 agentic-swmm-workflow 项目中通过 Model Context Protocol (MCP) 暴露给 AI agent 的"原子能力包"。项目把 SWMM 建模流水线拆解为若干可独立调用的领域 Skill,使自然语言意图能够映射到标准化的目录产物与可审计的运行指令。该架构在 [v0.7.2 发布说明](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.7.2) 中被作为"Agent Skills and Model Context Protocol"的核心对外能力正式公开。每个 Skill 在仓库内对应一个 `skills//` 子目录,并以同目录下的 `SKILL.md` 作为协议入口,由 TypeScript typed-tool surface 统一装配,供 Claude Agent SDK 等 provider 经由 MCP 调用 (资料来源:[skills/swmm-end-to-end/SKILL.md:1-40]()). ## SKILL.md 协议骨架 所有 Skill 共享同一 `SKILL.md` 骨架,以避免 agent 逐技能手写适配逻辑。文档通常包含四个区段: - **Frontmatter 区段**:声明 Skill 名称、版本、可调用工具与触发关键词,与 [v0.6.3a1](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.6.3a1) 中"关键字匹配从 6 处分散文件统一收敛"的改造完全一致 (资料来源:[skills/swmm-end-to-end/SKILL.md:1-12]()). - **输入契约区段**:描述输入文件(WGS84 边界框、设计降雨序列、率定目标等)与必备目录布局 `runs///` (资料来源:[skills/swmm-builder/SKILL.md:15-40]()). - **处理步骤区段**:以编号方式列出 agent 应依次执行的动作,例如合成排水网络 → 调用 SWMM 引擎 → 写出审计档案 (资料来源:[skills/swmm-end-to-end/SKILL.md:42-88]()). - **输出契约区段**:声明退出码、强制日志文件以及可被下游 Skill 复用的中间产物路径,例如 `.inp` 文件、网络 GIS 表达等 (资料来源:[skills/swmm-network/SKILL.md:30-60]()). 这四个区段把"触发条件 → 输入合法性 → 执行步骤 → 输出可追溯性"完整封装在一份 Markdown 文档里,使 MCP 客户端无需关心底层 CLI 实现差异。 ## 内置 Skill 与职责 主分支内置六个 Skill,职责按 SWMM 工作流阶段切分: - **`swmm-end-to-end`** — 单句自然语言驱动完整 SWMM 工作流,衔接网络合成、引擎调用、审计档案与空间制图 (资料来源:[skills/swmm-end-to-end/SKILL.md:5-30]()). - **`swmm-builder`** — 构造或修改 SWMM `.inp` 模型,处理子汇水区、河段、节点等要素 (资料来源:[skills/swmm-builder/SKILL.md:18-42]()). - **`swmm-calibration`** — 率定与灵敏度分析,接收观测流量/水位与参数范围并产出 Pareto 前沿 (资料来源:[skills/swmm-calibration/SKILL.md:10-35]()). - **`swmm-climate`** — 处理设计暴雨与气候变化情景,接入设计降雨序列与情景因子 (资料来源:[skills/swmm-climate/SKILL.md:12-30]()). - **`swmm-network`** — 对已有 `.inp` 或 GIS 图层做空间分析与可视化,产出空间网络图 (资料来源:[skills/swmm-network/SKILL.md:8-30]()). - **`skill-author`** — 编写或审阅 Skill 自身的元 Skill,可被 agent 用来内生地扩展能力集 (资料来源:[skills/skill-author/SKILL.md:6-22]()). 其中 `swmm-calibration`、`swmm-climate` 与 `skill-author` 是 [v0.7.2](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.7.2) 中集中加入的"agent-reachable"三件套,使校核、设计暴雨与 Skill 元编程都能直接经 LLM 调用,把建模 - 评估 - 率定链路上的所有步骤打通到同一 MCP 表面。 ## 与 MCP 运行时的协作及扩展方式 Skill 在运行时并不是独立文档,而是 `aiswmm` CLI 与 MCP 服务之间的中间桥梁: ```mermaid flowchart LR A[用户自然语言] --> B[Claude Agent SDK] B --> C{MCP 路由} C --> D[swmm-end-to-end] C --> E[swmm-builder] C --> F[swmm-calibration] C --> G[swmm-climate] C --> H[swmm-network] C --> I[skill-author] D --> J[runs/<date>/<id>/] E --> J F --> J G --> J H --> J I --> K[新 Skill 草稿] J --> L[审计档案 + 可重现产物] ``` 每个 Skill 在执行前会调用 `aiswmm doctor` 校验依赖,执行后在标准目录生成可被后续 Skill 引用的中间产物,从而把"自然语言 → 可审计建模"这一闭环完整锁定在 Skill 层 (资料来源:[skills/swmm-end-to-end/SKILL.md:88-110]()).`skill-author` 与箭头 K 形成内循环,使新增能力可以沿同一 SKILL.md 协议装配,无需改动 MCP 运行时。 扩展新 Skill 时,开发者遵循 `skill-author` 给出的元流程:在前置 frontmatter 中一致声明触发词;在输入/输出契约中使用与既有 Skill 兼容的 `runs///` 目录约定;并通过 typed-tool surface 进行注册 (资料来源:[skills/skill-author/SKILL.md:6-40]()).该框架同样适用于新增设计暴雨、可视化与离线分析等场景,与 [v0.7.2](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.7.2) 中"design storms"等新能力一脉相承,也与 [v0.6.3a1](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.6.3a1) 开始的"关键词集中管理"改造保持兼容。 --- ## LLM 提供商与 Agent 编排 ### 相关页面 相关主题：[CLI、REPL 与用户界面](#page-5), [建模记忆与 RAG 子系统](#page-9)
相关源码文件 以下源码文件用于生成本页说明： - [agentic_swmm/providers/factory.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/providers/factory.py) - [agentic_swmm/providers/openai_api.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/providers/openai_api.py) - [agentic_swmm/providers/anthropic_api.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/providers/anthropic_api.py) - [agentic_swmm/agent/planner.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/planner.py) - [agentic_swmm/agent/intent_classifier.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/intent_classifier.py) - [agentic_swmm/agent/tool_registry.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/tool_registry.py) - [agentic_swmm/agent/runtime.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/runtime.py)
# LLM 提供商与 Agent 编排 本页说明 `aiswmm`（agentic-swmm-workflow）如何抽象多家大语言模型（LLM）提供商，并在此之上用 Planner / Intent Classifier / Tool Registry 把自然语言请求编排成可审计、可复现的 SWMM 建模工作流。 ## 一、整体定位 Agent 运行时按三层组织： 1. **Provider 层**：屏蔽 OpenAI、Anthropic、可选 Claude Agent SDK 之间的差异。 2. **Agent 核心层**：依据意图分类结果制订计划、调度工具。 3. **Skill / Tool 层**：以 Model Context Protocol（MCP）暴露类型化工具（typed tools），涵盖校准、敏感性、设计暴雨、内存可观测性等。 默认 `pip install aiswmm` 走 OpenAI / Anthropic 主线；若需 Claude Agent SDK 沙箱，需显式声明可选依赖 `pip install "aiswmm[claude]"`。Provider 解耦是 v0.6.4 起"字节级复现"能够成立的前提——锁定依赖与 Docker 镜像后，切换 Provider 不会改变 `.inp` 输出。 ## 二、LLM 提供商抽象 `agentic_swmm/providers/factory.py` 中的工厂方法按配置或环境变量选择具体实现，使上层不感知后端差异。 | 后端 | 模块 | 适用场景 | | --- | --- | --- | | OpenAI 兼容 API | `agentic_swmm/providers/openai_api.py` | 默认后端，兼容任何 Chat Completions 形态的服务 | | Anthropic Messages API | `agentic_swmm/providers/anthropic_api.py` | Claude 直连 | | Claude Agent SDK（可选） | 通过 `[claude]` extra 启用 | 需要 MCP 沙箱与文件工具的复杂任务 | 资料来源：[agentic_swmm/providers/factory.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/providers/factory.py)、[agentic_swmm/providers/openai_api.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/providers/openai_api.py)、[agentic_swmm/providers/anthropic_api.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/providers/anthropic_api.py) ## 三、Agent 编排三件套 ### 3.1 意图分类器 `agentic_swmm/agent/intent_classifier.py` 在 v0.6.3a1 中完成了重构：原本分散在 6 个文件里的关键词匹配被收敛到统一入口，分类结果直接驱动 Planner 走向。资料来源：[agentic_swmm/agent/intent_classifier.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/intent_classifier.py) ### 3.2 规划器 `agentic_swmm/agent/planner.py` 接收意图，构造多轮对话计划并按需触发 Skill。v0.7.0 的 "agent runtime" 重构为 Planner 划清了运行时边界——Session / Memory 语义不再混入 Planner 内部。资料来源：[agentic_swmm/agent/planner.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/planner.py) ### 3.3 工具注册表 `agentic_swmm/agent/tool_registry.py` 是 v0.7.2 "typed-tool" 重构的核心载体：每个 Skill 都注册为带 JSON Schema 的类型化工具，使模型能以结构化方式请求调用，并与外部 MCP 流程对接。资料来源：[agentic_swmm/agent/tool_registry.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/tool_registry.py) ## 四、典型请求流 ```mermaid flowchart LR U[用户自然语言] --> IC[Intent Classifier] IC --> P[Planner] P --> TR[Tool Registry] TR -->|MCP| S1[Skill: 合成管网] TR -->|MCP| S2[Skill: 运行 SWMM] TR -->|MCP| S3[Skill: 写审计 dossier] P --> PF[Provider Factory] PF --> OA[OpenAI API] PF --> AN[Anthropic API] PF --> CA[Claude Agent SDK] ``` v0.7.1 中"输入 WGS84 边界框"即可触发的端到端工作流，正是沿上述链路执行：OSM + DEM 合成排水网 → 跑 SWMM → 写确定性审计报告 → 渲染空间网络地图，全部落到 `runs///` 标准化目录。 ## 五、社区关注与版本演进 - **v0.6.3a1**：关键词匹配 6 → 1，意图层从此可单测、可独立迭代。资料来源：[agentic_swmm/agent/intent_classifier.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/intent_classifier.py) - **v0.7.0 / v0.7.0a2**：明确 Agent 运行时边界；`aiswmm doctor` 新增 `Sessions store` 完整性校验、`aiswmm memory repair-sessions` 入口——这些 CLI 入口的存在本身依赖 Planner / Registry 的稳定契约。 - **v0.7.2**：随 *AI for Engineering* 论文发布 typed-tool surface，使 Agent 可被外部 agent 直接调用，校准与敏感性分析首次对 Agent 可达。 - **v0.7.3**：一键安装器与 Provider / Agent 解耦，全新机器的单命令 provisioning 不再受 onboarding 卡点阻塞。 --- ## 建模记忆与 RAG 子系统 ### 相关页面 相关主题：[核心特性与运行产物](#page-3), [审计框架、可重现性与运维故障处理](#page-12)
相关源码文件 以下源码文件用于生成本页说明： - [agentic_swmm/memory/memory_archive.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/memory/memory_archive.py) - [agentic_swmm/memory/session_db.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/memory/session_db.py) - [agentic_swmm/memory/lessons_lifecycle.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/memory/lessons_lifecycle.py) - [agentic_swmm/memory/parametric_memory.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/memory/parametric_memory.py) - [agentic_swmm/agent/memory_verbs.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/memory_verbs.py) - [agentic_swmm/agent/memory_context.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/agent/memory_context.py)
# 建模记忆与 RAG 子系统 `agentic-swmm-workflow` 中的"建模记忆与 RAG 子系统"承担两个互补的角色:一方面为 SWMM 建模会话提供可审计、可回放的长期持久化层;另一方面把历史经验转化为可被 Agent 在新会话中检索使用的上下文证据。该能力在 v0.7.0 发布说明中被冠以"Modeling memory, agent runtime, install UX"的标题并作为核心稳定下来,随后 v0.7.0a2、v0.7.2 又分别强化了可观测性与自愈能力。资料来源:[agentic_swmm/memory/memory_archive.py:1-40]() ## 子模块职责划分 | 模块 | 角色 | 关键职责 | | --- | --- | --- | | `memory/memory_archive.py` | 长期归档层 | 将 `runs///` 下的建模产物、报告与可复现物写入只读式归档 | | `memory/session_db.py` | 会话存储 | 以 SQLite 形式保存每个会话的状态机快照,供 `aiswmm doctor` 做完整性检查 | | `memory/lessons_lifecycle.py` | 经验生命周期 | 维护"教训"从 pending → accepted → retired 的晋级与退役规则 | | `memory/parametric_memory.py` | 参数化记忆 | 记录可调参数与先验分布,便于新场景复用 | | `agent/memory_verbs.py` | Agent 动词接口 | 把上述能力暴露为 `memory repair-sessions`、`memory list` 等 CLI 子命令 | | `agent/memory_context.py` | 上下文注入 | 在每轮对话之前按相关度检索片段,拼接到 system prompt | 各文件之间不是松散的工具箱,而是一条分层的数据通路:会话落盘 → 提取经验 → 晋升参数 → 归档检索。资料来源:[agentic_swmm/memory/session_db.py:1-120]() [agentic_swmm/memory/lessons_lifecycle.py:1-80]() ## RAG 检索与上下文组装 当一次新会话启动或既有会话被续接时,`memory_context.py` 会按以下顺序加载证据: ```mermaid flowchart LR A[新会话/续接] --> B[parametric_memory
读取先验] B --> C[lessons_lifecycle
已接受教训] C --> D[memory_archive
相似场景片段] D --> E[memory_context
拼装 system prompt] E --> F[Agent 推理] ``` 这一流程保证在同一研究项目中反复开展 SWMM 模拟时,Agent 能够即时借鉴历史参数和失败教训,而不是每次都从零推断。`memory_verbs` 中的检索动词负责把数据通路里的每一段都暴露为可调试接口,便于在不重启 Agent 的前提下重放上下文。资料来源:[agentic_swmm/agent/memory_context.py:1-150]() [agentic_swmm/agent/memory_verbs.py:1-90]() ## 运维命令与可观测性 v0.7.0a2 起,`aiswmm doctor` 在诊断表格中新增 `Sessions store` 行,把 `session_db` 的健康度归一为 `ok / corrupt / unreadable / absent` 四态,并在 `CORRUPT / UNREADABLE` 时返回非零退出码,使 CI 能真正捕获数据丢失条件。同版本引入的 `aiswmm memory repair-sessions` 子命令可对损坏的会话存储执行事务安全修复;这两条命令都通过 `memory_verbs.py` 统一暴露,避免散落在多个 CLI 入口处。资料来源:[agentic_swmm/agent/memory_verbs.py:90-220]() [agentic_swmm/memory/session_db.py:120-260]() v0.7.2 发布说明把"内存可观测性"作为正式卖点:用户可以读取已存储会话数、检索命中率、平均上下文长度等指标,从而判断 RAG 是否真正提供了增益,而不是默默增加了 token 成本。资料来源:[agentic_swmm/memory/memory_archive.py:40-200]() ## 生命周期与归档策略 建模过程的所有重产物(`.inp`、报告、参数散列)都会在会话结束时被 `memory_archive` 切片为可重现的 manifest,决定哪些条目可进入下一轮检索,哪些仅做合规留档;`lessons_lifecycle` 负责把候选教训按显式规则淘汰陈旧条目,避免检索语料被噪声占据;`parametric_memory` 则把"在流域 X 使用糙率 0.015"这样的事实升格为后续会话可引用的参数化先验。三者共同保证 RAG 在长期使用下不会出现"老教训干扰新结论"的回退问题。资料来源:[agentic_swmm/memory/lessons_lifecycle.py:80-200]() [agentic_swmm/memory/parametric_memory.py:1-160]() --- ## 安装方式、依赖与运行环境 ### 相关页面 相关主题：[项目概览与设计理念](#page-1), [技能扩展与跨 Agent 适配](#page-11)
相关源码文件 以下源码文件用于生成本页说明： - [pyproject.toml](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/pyproject.toml) - [setup.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/setup.py) - [requirements.txt](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/requirements.txt) - [Dockerfile](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/Dockerfile) - [Dockerfile.anywhere](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/Dockerfile.anywhere) - [scripts/install.sh](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/scripts/install.sh)
# 安装方式、依赖与运行环境 本页说明 `aiswmm` 包（对应仓库 `agentic-swmm-workflow`）的安装方式、运行时依赖以及运行环境的最低要求，覆盖 PyPI 正式版与 alpha/beta 预发布版本，并整理一行安装脚本与 Docker 镜像两条平行通道。 ## 一、概览与版本节奏 `agentic-swmm-workflow` 通过 PyPI 包名 `aiswmm` 分发。`pyproject.toml` 中定义 PEP 621 元数据、构建后端以及可选 extras；`setup.py` 作为兼容垫片存在，以保证旧版 setuptools 也能解析元数据。资料来源：[pyproject.toml:1-40]() 自 v0.6.4 起，发布节奏以"字节级可复现"为底线：`requirements.txt` 中的依赖被精确钉死，配合 Dockerfile 的自动构建，保证同一 PyPI 版本在任意平台拉取到的产物一致。资料来源：[requirements.txt:1-30]() [Dockerfile:1-25]() 版本语义遵循 PEP 440： - 稳定版（stable）：`v0.6.x`、`v0.7.0` 等，按 `pip install aiswmm` 即装即得。 - 预发布（pre-release）：`v0.6.2a1`、`v0.6.3a1`、`v0.7.0a1`、`v0.7.0a2`，需要显式 `--pre` 或精确版本号。 - 一行安装脚本（`scripts/install.sh`）从 v0.7.3 起重新设计，使 Linux/macOS 与 Windows 在空白机器上一条命令即可完成完整工具链配置。资料来源：[scripts/install.sh:1-50]() ## 二、支持的安装方式 ### 1. PyPI 安装 最常见的安装方式： ```bash pip install aiswmm # 默认拉取最新稳定版 pip install aiswmm==0.7.4 # 精确钉版（推荐用于复现实验） pip install --pre aiswmm # 允许预发布版本 pip install "aiswmm[claude]==0.7.0a1" # 启用 Claude Agent SDK 提供方 ``` `pip install aiswmm` 在不同历史节点拉取到的版本不同：v0.6.2a1/v0.6.3a1 阶段仍指向 v0.6.1；v0.7.0 之后改为指向最新的 0.7.x 稳定版。带方括号的 extras 由 `pyproject.toml` 中声明的 `optional-dependencies` 控制，例如 `claude` 后端所需的 `claude-agent-sdk` 不会进入默认安装。资料来源：[pyproject.toml:40-80]() ### 2. 一行安装脚本（Linux / macOS / Windows） `scripts/install.sh` 提供跨平台的脚本化安装入口，从 v0.7.3 起经历以下重写： - 默认目标改为最新已发布版本，而非 main 分支 HEAD。 - Windows 分支不再克隆到 `C:\Windows\System32`（该目录默认对普通用户写保护），而是克隆到 `%LOCALAPPDATA%`，并在执行前为当前进程设置 `ExecutionPolicy Bypass`，避免 PowerShell 拦截 `irm | iex` 流程。 - 脚本内部调用 `pip install aiswmm` 完成 Python 侧依赖，再补齐 SWMM 可执行文件、SWMManywhere、DEM/OSM 数据源所需的外部 CLI。 资料来源：[scripts/install.sh:1-80]() ### 3. Docker 镜像 提供两条 Dockerfile： - `Dockerfile`：标准运行时镜像，封装 SWMM、Python 依赖与 `aiswmm` CLI，对应 `pip install aiswmm==X.Y.Z` 的字节级可复现结果。 - `Dockerfile.anywhere`：用于驱动 v0.7.1 引入的"自然语言一句话 + WGS84 包围盒"端到端流程，预装 SWMManywhere（Imperial College 的合成管网工具）、DEM/OSM 下载与裁剪组件。 从 v0.6.4 起镜像由 CI 自动构建并发布到容器注册表，标签与 PyPI 版本一一对应。资料来源：[Dockerfile:1-30]() [Dockerfile.anywhere:1-30]() ## 三、运行时依赖与可选组件 核心 Python 依赖固化在 `requirements.txt` 中，包含 SWMM Python 绑定（`pyswmm`）、地理空间处理栈（`geopandas`、`rasterio`、`shapely`）、LLM/Agent SDK 抽象层以及 MCP 通信所需库。所有依赖均使用 `==` 精确版本钉死，避免隐式升级破坏可复现性。资料来源：[requirements.txt:1-30]() 可选 extras 通过 `pyproject.toml` 暴露，目前至少包含： - `claude`：启用 Anthropic Claude Agent SDK 作为 Provider。 - 其余 extras 视版本演进可能新增，例如与 SWMManywhere、DEM 拼接工具相关的可选加速库。 由于依赖被精确钉死，建议在生产/CI 场景使用虚拟环境（`python -m venv .venv` 或 `conda create`）隔离，避免被系统级 numpy/geopandas 干扰。资料来源：[pyproject.toml:40-80]() ## 四、运行环境与平台要求 | 维度 | 最低要求 | 说明 | | --- | --- | --- | | Python | 3.10+ | 0.7.x 系列使用 PEP 604 类型注解与 `match` 语句 | | 操作系统 | Linux、macOS、Windows 10/11 | Windows 需支持 PowerShell 5+ | | 磁盘 | ≥ 2 GB（不含 DEM 缓存） | DEM 区域瓦片按需下载 | | 网络 | 安装期可访问 PyPI 与 GitHub | 离线环境需预先 `pip download` | | SWMM | 由包内置或 Docker 提供 | `pyswmm` 绑定需与本地 SWMM 版本匹配 | 一行安装脚本在 Linux/macOS 上需要 `bash`、`curl`/`git`、`pip`；在 Windows 上依赖 PowerShell 的 `irm`（Invoke-RestMethod）和 `iex`（Invoke-Expression）。`ExecutionPolicy Bypass` 仅作用于脚本自身进程，不修改用户/机器全局策略。资料来源：[scripts/install.sh:50-120]() ## 五、安装后自检 完成安装后，可通过以下命令验证环境： ```bash aiswmm --version # 打印 aiswmm 版本 aiswmm doctor # v0.7.0a2 起含 Sessions store 完整性检查，CORRUPT/UNREADABLE 时返回非零退出码 ``` `aiswmm doctor` 的退出码语义使其适合接入 CI 健康检查，从而在数据丢失条件出现时立即告警。资料来源：[pyproject.toml:80-120]() --- ## 技能扩展与跨 Agent 适配 ### 相关页面 相关主题：[MCP 服务器矩阵](#page-6), [Skill 层体系](#page-7)
相关源码文件 以下源码文件用于生成本页说明： - [integrations/README.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/integrations/README.md) - [integrations/skills/README.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/integrations/skills/README.md) - [integrations/mcp/README.md](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/integrations/mcp/README.md) - [integrations/mcp/generated/codex-mcp-add.sh](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/integrations/mcp/generated/codex-mcp-add.sh) - [integrations/mcp/generated/codex-mcp-add.ps1](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/integrations/mcp/generated/codex-mcp-add.ps1) - [integrations/mcp/generated/hermes-mcp.config.yaml](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/integrations/mcp/generated/hermes-mcp.config.yaml)
# 技能扩展与跨 Agent 适配 ## 概述与设计目标 `integrations/` 目录是 agentic-swmm-workflow 对外能力的统一出口，承担两件事：一是把 SWMM 建模能力封装为可被智能体调用的「技能（Skill）」单元，二是把这些技能通过标准协议（Model Context Protocol，MCP）暴露给不同的 Agent 运行时。`integrations/README.md` 把整个集成层划分为 `skills/` 与 `mcp/` 两条主线，前者面向能力建模，后者面向协议适配，二者共同实现「一份能力、多端复用」。资料来源：[integrations/README.md:1-40]() 该设计的核心目标是**解耦**：技能定义与具体 Agent 框架无关，Agent 只需要一个 MCP 客户端即可发现并调用任意已注册技能。从社区反馈看，v0.7.2 起随论文 *Agentic SWMM: Auditable and Reproducible Stormwater Modelling Workflow with Agent Skills and Model Context Protocol* 正式发布，三个月内已扩展到校准/灵敏度、设计暴雨、内存可观测性等多个新技能。资料来源：[v0.7.2 发布说明](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.7.2) ## Skills 体系结构 `integrations/skills/README.md` 定义了技能的最小契约：每个 Skill 是一个具备「输入 schema → 副作用 → 输出工件」三段式描述的能力包，对应 SWMM 工作流中的一个原子动作（如生成 inp、运行模拟、抽取结果）。`aiswmm` 命令在安装时会把这些 Skill 注册到本地 `Sessions store`，并由 `aiswmm doctor` 周期性检查其完整性。资料来源：[integrations/skills/README.md:1-60](), [v0.7.0a2 发布说明](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.7.0a2) 技能扩展遵循三条约束： 1. **无副作用外溢**：所有写入必须落在 `runs///` 目录树下，保证可审计、可复现； 2. **强类型 I/O**：输入输出采用 JSON Schema 校验，避免 Agent 自由发挥造成不可重放； 3. **可观测**：技能执行会在会话存储中留下结构化记录，v0.7.0a2 引入的 `aiswmm memory repair-sessions` 即可针对这些记录做一致性修复。资料来源：[integrations/skills/README.md:60-120](), [v0.7.0a2 发布说明](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.7.0a2) 新增技能只需要在该目录下追加一个标准化的技能描述文件即可，无需改动 Agent 侧代码。 ## MCP 与跨 Agent 适配层 `integrations/mcp/README.md` 描述了 MCP 服务器的启动方式与注册流程：`aiswmm` 内置了一个 stdio MCP 服务器，监听 Agent 客户端的 `tools/list` 与 `tools/call` 请求，并把 Skills 目录下的技能映射为 MCP tools。资料来源：[integrations/mcp/README.md:1-80]() 为了让不同 Agent 运行时「开箱即用」，仓库在 `integrations/mcp/generated/` 下预生成三份适配脚本： | Agent | 适配产物 | 用途 | |---|---|---| | Codex（POSIX） | `codex-mcp-add.sh` | 把 MCP 服务器注册到 Codex CLI 的配置目录 | | Codex（Windows） | `codex-mcp-add.ps1` | PowerShell 等价脚本，绕开 `C:\Windows\System32` 写入限制 | | Hermes | `hermes-mcp.config.yaml` | YAML 形式的 MCP endpoint 声明 | 资料来源：[integrations/mcp/generated/codex-mcp-add.sh:1-30](), [integrations/mcp/generated/codex-mcp-add.ps1:1-30](), [integrations/mcp/generated/hermes-mcp.config.yaml:1-20]() 下图给出一次典型的跨 Agent 调用流程： ```mermaid sequenceDiagram participant Agent as Agent Runtime (Codex/Hermes/Claude) participant MCP as aiswmm MCP Server participant Skill as Skill Registry participant FS as runs/// Agent->>MCP: tools/list MCP->>Skill: enumerate registered skills Skill-->>MCP: typed schemas MCP-->>Agent: tools/catalog Agent->>MCP: tools/call (skill, args) MCP->>FS: 执行并落盘 FS-->>Agent: 工件路径 + 审计摘要 ``` 社区已验证的兼容端包括 Claude Agent SDK（通过 `pip install "aiswmm[claude]"` 启用）、Codex CLI、Hermes，以及任何符合 MCP 规范的客户端。资料来源：[v0.7.0a1 发布说明](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.7.0a1) ## 扩展指南 新增一个 Agent 接入只需两步： 1. 在 `integrations/mcp/generated/` 下新增 `-mcp.{sh,ps1,yaml}` 之一，写入 MCP 服务器的 stdio 启动命令（`aiswmm mcp serve`）与必要的元数据； 2. 在对应 Agent 的配置目录中执行该脚本，使其把 MCP endpoint 注册到 Agent 自身的工具表。 新增技能则聚焦于 `integrations/skills/`：补充 JSON Schema、副作用约束与会话存储钩子即可，由 `aiswmm doctor` 自动纳入健康检查。v0.7.3 修复 Windows 路径与 ExecutionPolicy 的过程证明，这一「脚本生成 + 幂等注册」的范式对一次性的客户端非常友好。资料来源：[v0.7.3 发布说明](https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/tag/v0.7.3), [integrations/README.md:40-90]() 至此，技能扩展与跨 Agent 适配在仓库中形成「Skill 定义 → MCP 暴露 → 适配脚本注册」的闭环，使得 SWMM 工作流既能在 Claude 中对话式驱动，也能在 Codex、Hermes 等 CLI Agent 中以脚本方式批量化复用。 --- ## 审计框架、可重现性与运维故障处理 ### 相关页面 相关主题：[数据流、案例与制品管理](#page-4), [建模记忆与 RAG 子系统](#page-9)
相关源码文件 以下源码文件用于生成本页说明： - [agentic_swmm/audit/provenance_v1_2.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/audit/provenance_v1_2.py) - [agentic_swmm/audit/chat_note.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/audit/chat_note.py) - [agentic_swmm/audit/llm_calls.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/audit/llm_calls.py) - [agentic_swmm/audit/moc_generator.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/audit/moc_generator.py) - [agentic_swmm/diagnostics/doctor_report.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/diagnostics/doctor_report.py) - [agentic_swmm/diagnostics/fixes.py](https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/agentic_swmm/diagnostics/fixes.py)
# 审计框架、可重现性与运维故障处理 ## 1. 审计框架总览与目标 `agentic_swmm/audit` 子包构成项目的"可审计性骨架"，由四个核心模块协同完成全链路证据留痕： - `provenance_v1_2.py` 负责输出版本化的 provenance manifest，记录每次运行的输入数据、工具调用、随机种子、容器镜像摘要以及依赖版本，是 v0.6.4 字节级可重现性声明的依据。 - `chat_note.py` 负责将会话中的人类消息、Agent 回复以及关键工具事件落盘到 `runs///chat.log`，确保每一条自然语言指令都可回溯。 - `llm_calls.py` 负责记录模型推理请求的 token 用量、prompt hash、completion hash 与模型指纹，作为审计追溯 LLM 行为的唯一凭证。 - `moc_generator.py` 负责从已落盘的会话与 LLM 调用日志生成"Model of Context (MOC)"摘要，供后续 skill 复用与同行复核。 资料来源：[agentic_swmm/audit/provenance_v1_2.py:1-40]() 资料来源：[agentic_swmm/audit/llm_calls.py:1-30]() ## 2. 字节级可重现性机制 自 v0.6.4 起，框架承诺在相同输入下产出比特级一致的输出，关键支撑来自三处： 1. **依赖钉死**：每次 `runs//provenance.json` 中记录 `pip freeze` 的精确哈希；通过环境变量 `AISWMM_PIN_LOCK=1` 强制使用 lock 文件而非浮点版本。 2. **容器镜像摘要**：provenance manifest 第 7 段会写入当前运行所在 Docker 镜像的 SHA-256 摘要，复现者只需拉取同一 digest 即可得到一致 libc/glibc 行为。 3. **随机种子归一**：`provenance_v1_2.py` 内 `seed_everything()` 函数统一注入 numpy、PCG、SWMManywhere、pyswmm 四类 RNG 的种子，并将其明文写入 manifest，便于反演。 | 字段 | 含义 | 写入位置 | | --- | --- | --- | | `seed` | 统一随机种子 | `provenance.json::runtime` | | `image_digest` | Docker 镜像 SHA-256 | `provenance.json::env` | | `pip_freeze_sha` | 依赖 lock 哈希 | `provenance.json::deps` | | `swmm_cli_version` | swmm5 CLI 版本号 | `provenance.json::tools` | 资料来源：[agentic_swmm/audit/provenance_v1_2.py:55-110]() ## 3. 会话、LLM 调用与 MOC 的协同审计 `chat_note.py` 与 `llm_calls.py` 通过共享 `RunContext` 对象保持写入顺序的一致性，避免在并发会话中产生交叉污染。每次 `append_chat_turn()` 调用都会同时向 `chat.log` 追加一行 JSONL，并向 `llm_calls.jsonl` 写入一条仅含元数据的占位记录；待模型返回后，`record_llm_call()` 再回填该占位并补全 token 数与哈希。资料来源：[agentic_swmm/audit/chat_note.py:20-65]() 资料来源：[agentic_swmm/audit/llm_calls.py:35-90]() `moc_generator.py` 在 run 收尾阶段被调用，扫描 `chat.log` 与 `llm_calls.jsonl` 抽取"用户意图 → 工具选择 → 模型响应"三元组，按时间序列拼装为 `moc.md`，并附带 SHA-256 校验。MOC 文件随后可作为下一次会话的 `skill_context` 输入，实现上下文记忆的可验证传递。资料来源：[agentic_swmm/audit/moc_generator.py:12-58]() ## 4. 运维故障诊断与自动修复 `agentic_swmm/diagnostics` 提供两段式排障路径：先由 `doctor_report.py` 完成只读体检，再由 `fixes.py` 在获得用户确认后执行可逆修复。 `doctor_report.py` 中的 `run_doctor()` 会探测五类健康状态，每类对应一个状态码： - `ok`：完全正常。 - `absent`：资源或目录未创建（如首次安装时无 `~/.aiswmm/sessions`）。 - `unreadable`：权限或编码异常。 - `corrupt`：JSON/JSONL 解析失败、必需字段缺失。 - `inconsistent`：跨文件哈希不一致（常因并发写入未完成）。 自 v0.7.0a2 起，`Sessions store` 行的 CORRUPT/UNREADABLE 状态会让 `aiswmm doctor` 返回非零退出码，使 CI 环境可被有效拦截。资料来源：[agentic_swmm/diagnostics/doctor_report.py:40-120]() `fixes.py` 暴露的 `repair_sessions_store()` 是目前唯一带破坏性的修复动词，其内部流程为： ```mermaid flowchart LR A[doctor 报告 CORRUPT] --> B[备份至 .bak-] B --> C[逐行解析 JSONL] C --> D{解析成功?} D -- 否 --> E[截断至上一条 OK 行] D -- 是 --> F[写回原子重命名] E --> F F --> G[重跑 doctor 校验] ``` 所有写入均使用 `os.replace()` 完成原子替换，确保修复过程中即便进程被 kill 也不会留下半截文件。资料来源：[agentic_swmm/diagnostics/fixes.py:25-95]() ## 5. 常见故障模式与社区应对 依据社区证据中记录的 release notes，常见排障路径如下： - **Windows 一键安装失败**（v0.7.3 修复）：克隆目标必须落在 `%LOCALAPPDATA%`，并在运行 clo 脚本前以进程级 `ExecutionPolicy Bypass` 解除系统写保护。资料来源：[v0.7.3 release notes]() - **Sessions store 数据损坏**（v0.7.0a2 引入 `repair-sessions`）：先用 `aiswmm doctor` 确认状态码，再执行 `aiswmm memory repair-sessions`，最后重跑 doctor 校验退出码。资料来源：[v0.7.0a2 release notes]() - **Warm intro 重复触发**（v0.6.2a1 修复 #108）：旧版每次 `hi/hello` 都会重放欢迎语，修复后改为每会话仅一次，并通过 `chat_note` 写入 `intro_fired=true` 标记防止误判。资料来源：[v0.6.2a1 release notes]() ## 6. 与上层 skill 的契约 审计与诊断子系统对外暴露稳定的命令行动词 (`audit`、`memory`、`doctor`、`repair-sessions`) 与一致的退出码语义，skill 层在执行任意模型调用前都会先调用 `provenance_v1_2.begin_run()` 开启一次会话，并在结束阶段调用 `moc_generator.finalize()` 关闭证据链。这一契约使 v0.7.2 引入的"calibration 与 sensitivity"等新技能无需重写审计逻辑即可直接获得可重现性背书。资料来源：[agentic_swmm/audit/provenance_v1_2.py:15-30]() 资料来源：[agentic_swmm/audit/moc_generator.py:60-80]() --- --- ## Doramagic 踩坑日志 项目：Zhonghao1995/agentic-swmm-workflow 摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。 ## 1. 安装坑 · 依赖 Docker 环境 - 严重度：medium - 证据强度：runtime_trace - 发现：安装/运行入口包含 Docker 命令：docker run --rm -v "$PWD/runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.7.4 acceptance - 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。 - 复现命令：`docker run --rm -v "$PWD/runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.7.4 acceptance` - 证据：identity.distribution | https://github.com/Zhonghao1995/agentic-swmm-workflow | docker run --rm -v "$PWD/runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.7.4 acceptance ## 2. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/Zhonghao1995/agentic-swmm-workflow | host_targets=openclaw, mcp_host, claude_code, claude, hermes, chatgpt ## 3. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/Zhonghao1995/agentic-swmm-workflow | README/documentation is current enough for a first validation pass. ## 4. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/Zhonghao1995/agentic-swmm-workflow | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/Zhonghao1995/agentic-swmm-workflow | no_demo; severity=medium ## 6. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/Zhonghao1995/agentic-swmm-workflow | no_demo; severity=medium ## 7. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/Zhonghao1995/agentic-swmm-workflow | issue_or_pr_quality=unknown ## 8. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/Zhonghao1995/agentic-swmm-workflow | release_recency=unknown