项目使命与定位

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/<date>/<id>/ 目录布局下，确保审计溯源（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。

架构概览

工作流从用户输入到最终产物的数据流，可概括为四个阶段：

flowchart LR
    A[自然语言请求<br/>含 WGS84 bbox] --> B[网络合成<br/>OSM + DEM]
    B --> C[SWMM 引擎运行]
    C --> D[审计 dossier<br/>+ 空间网络图]
    D --> E[runs/日期/ID/<br/>目录产物]

合成阶段依赖 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）所累积的核心能力，按发布线区分：

安装与版本契约

• 默认安装：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 引用配套论文，以确保方法学可追溯。

1. 设计目标与架构概览

agentic-swmm-workflow（发布到 PyPI 时包名为 aiswmm）是一个面向 EPA SWMM（暴雨水管理模型）的"代理化"工作流框架。它通过 Agent Skills 与 Model Context Protocol (MCP) 把自然语言意图转化为可审计、可复现的 SWMM 建模流程（资料来源：agentic_swmm/__init__.py:1-40）。整个系统强调三点：确定性审计（每次运行产出 runs/<日期>/<id>/ 目录）、字节级可复现（v0.6.4 起锁定依赖与 Docker 镜像）、以及记忆可观测（v0.7.0a2 起 Sessions store 健康检查成为 aiswmm doctor 的标准动作）。

整体架构由四层组成，自顶向下依次为 CLI 入口层、运行时层、技能层与记忆/外部引擎层：

flowchart TB
  U[用户 / 代理客户端] --> CLI[aiswmm CLI<br/>cli.py]
  CLI --> RT[运行时层<br/>runtime/]
  RT --> SK[技能库<br/>skills/]
  RT --> MEM[记忆子系统<br/>memory/]
  SK --> SWMM[SWMM / SWMManywhere<br/>外部引擎]
  RT --> MCP[MCP 服务<br/>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/<日期>/<id>/ 下留下确定性审计材料（资料来源：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/<date>/<id>/，形成审计 dossier。
5. 渲染脚本产出空间网络图与确定性报告（资料来源：agentic_swmm/runtime/agent.py:60-160）。

这种"分层 + 显式审计目录"的设计，是项目同时满足可复现性（v0.6.4 起锁定依赖与 Docker 镜像）与可审计性（v0.7.0 起 Sessions 完整性检查）两大诉求的结构基础（资料来源：docs/repo-map.md:80-140）。

概述与项目定位

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/<date>/<id>/`

每一次执行都被写入统一目录 runs/<date>/<id>/，由 agentic_swmm/audit/run_folder_layout.py 定义与校验，保证跨环境、跨时间的 byte-level 可复现。

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==<ver> 或 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

概述与目标

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/）来自不同根路径，注册表维护两套视图，避免相互污染。

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 生成：

• 基于案例名、创建日期、随机后缀组合为 <YYYYMMDD>-<slug>-<hash> 形式的目录名。
• ID 写入 runs/<date>/<id>/ 路径，确保每次运行都自带可追溯的指纹目录。

资料来源：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、降雨驱动等外部数据集的统一资源标识；
• 场景表：设计暴雨、降雨时间序列或多组参数化情景；
• 目标字段：水位、流量、溢流等被报告的指标与阈值。

资料来源：cases/tecnopolo/case_meta.yaml:1-40、cases/todcreek/case_meta.yaml:1-40

制品与运行目录布局

每次运行都在 runs/ 下创建独立的、按日期+ID 分层的目录，所有中间与最终制品均写入该目录，确保一份"审计凭证"独立且自洽。

典型 runs/<date>/<id>/ 内容：

• 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 起）。

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、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 <verb> [...]                       │
│   ├─ 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/<date>/<id>/ 的结构化目录中。

资料来源：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
• 会话循环：agentic_swmm/agent/repl.py
• 渲染与欢迎：agentic_swmm/agent/ui.py

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/<date>/<id>/ 产物目录下记录调用日志。
• 可发现性：通过 integrations/mcp/generated/openclaw-mcp.config.json 自动生成配置，使 agent runtime 在启动时按矩阵声明发现工具。资料来源：integrations/mcp/generated/openclaw-mcp.config.json:1-40。

2. 矩阵中的四个服务器

四个 server.js 均位于 mcp/<server-name>/ 子目录下，保持入口文件命名前缀 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/<date>/<id>/ 布局落地，确保 agent 决策与底层 SWMM 产物可逐次回放。资料来源：integrations/mcp/README.md:60-100。

4. 端到端调用流程

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/<date>/<id>/。资料来源：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/<new-server>/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/<date>/<id>/ 布局，并补充 aiswmm doctor 中相应健康检查行，以维持矩阵整体的可观测性。资料来源：integrations/mcp/README.md:100-140。

如此，MCP 服务器矩阵既能持续承载 SWMM 建模各阶段，也能让 agent runtime 在不改动协议层的前提下获得新增能力。

概述

Skill 层是 agentic-swmm-workflow 项目中通过 Model Context Protocol (MCP) 暴露给 AI agent 的"原子项目"。项目把 SWMM 建模流水线拆解为若干可独立调用的领域 Skill,使自然语言意图能够映射到标准化的目录产物与可审计的运行指令。该架构在 v0.7.2 发布说明 中被作为"Agent Skills and Model Context Protocol"的核心对外能力正式公开。每个 Skill 在仓库内对应一个 skills/<skill-name>/ 子目录,并以同目录下的 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 中"关键字匹配从 6 处分散文件统一收敛"的改造完全一致 (资料来源:skills/swmm-end-to-end/SKILL.md:1-12).
• 输入契约区段:描述输入文件(WGS84 边界框、设计降雨序列、率定目标等)与必备目录布局 runs/<date>/<id>/ (资料来源: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 中集中加入的"agent-reachable"三件套,使校核、设计暴雨与 Skill 元编程都能直接经 LLM 调用,把建模 - 评估 - 率定链路上的所有步骤打通到同一 MCP 表面。

与 MCP 运行时的协作及扩展方式

Skill 在运行时并不是独立文档,而是 aiswmm CLI 与 MCP 服务之间的中间桥梁:

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/<date>/<id>/ 目录约定;并通过 typed-tool surface 进行注册 (资料来源:skills/skill-author/SKILL.md:6-40).该框架同样适用于新增设计暴雨、可视化与离线分析等场景,与 v0.7.2 中"design storms"等新能力一脉相承,也与 v0.6.3a1 开始的"关键词集中管理"改造保持兼容。

一、整体定位

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 中的工厂方法按配置或环境变量选择具体实现，使上层不感知后端差异。

资料来源：agentic_swmm/providers/factory.py、agentic_swmm/providers/openai_api.py、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

3.2 规划器

agentic_swmm/agent/planner.py 接收意图，构造多轮对话计划并按需触发 Skill。v0.7.0 的 "agent runtime" 重构为 Planner 划清了运行时边界——Session / Memory 语义不再混入 Planner 内部。资料来源：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

四、典型请求流

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/<date>/<id>/ 标准化目录。

五、社区关注与版本演进

• v0.6.3a1：关键词匹配 6 → 1，意图层从此可单测、可独立迭代。资料来源：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 卡点阻塞。

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

子模块职责划分

各文件之间不是松散的工具箱,而是一条分层的数据通路:会话落盘 → 提取经验 → 晋升参数 → 归档检索。资料来源:agentic_swmm/memory/session_db.py:1-120 agentic_swmm/memory/lessons_lifecycle.py:1-80

RAG 检索与上下文组装

当一次新会话启动或既有会话被续接时,memory_context.py 会按以下顺序加载证据:

flowchart LR
    A[新会话/续接] --> B[parametric_memory<br/>读取先验]
    B --> C[lessons_lifecycle<br/>已接受教训]
    C --> D[memory_archive<br/>相似场景片段]
    D --> E[memory_context<br/>拼装 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

一、概览与版本节奏

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 安装

最常见的安装方式：

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

四、运行环境与平台要求

一行安装脚本在 Linux/macOS 上需要 bash、curl/git、pip；在 Windows 上依赖 PowerShell 的 irm（Invoke-RestMethod）和 iex（Invoke-Expression）。ExecutionPolicy Bypass 仅作用于脚本自身进程，不修改用户/机器全局策略。资料来源：scripts/install.sh:50-120

五、安装后自检

完成安装后，可通过以下命令验证环境：

aiswmm --version          # 打印 aiswmm 版本
aiswmm doctor             # v0.7.0a2 起含 Sessions store 完整性检查，CORRUPT/UNREADABLE 时返回非零退出码

aiswmm doctor 的退出码语义使其适合接入 CI 健康检查，从而在数据丢失条件出现时立即告警。资料来源：pyproject.toml:80-120

概述与设计目标

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 发布说明

Skills 体系结构

integrations/skills/README.md 定义了技能的最小契约：每个 Skill 是一个具备「输入 schema → 副作用 → 输出工件」三段式描述的项目，对应 SWMM 工作流中的一个原子动作（如生成 inp、运行模拟、抽取结果）。aiswmm 命令在安装时会把这些 Skill 注册到本地 Sessions store，并由 aiswmm doctor 周期性检查其完整性。资料来源：integrations/skills/README.md:1-60, v0.7.0a2 发布说明

技能扩展遵循三条约束：

1. 无副作用外溢：所有写入必须落在 runs/<date>/<id>/ 目录树下，保证可审计、可复现；
2. 强类型 I/O：输入输出采用 JSON Schema 校验，避免 Agent 自由发挥造成不可重放；
3. 可观测：技能执行会在会话存储中留下结构化记录，v0.7.0a2 引入的 aiswmm memory repair-sessions 即可针对这些记录做一致性修复。资料来源：integrations/skills/README.md:60-120, 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/ 下预生成三份适配脚本：

资料来源：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 调用流程：

sequenceDiagram
    participant Agent as Agent Runtime (Codex/Hermes/Claude)
    participant MCP as aiswmm MCP Server
    participant Skill as Skill Registry
    participant FS as runs/<date>/<id>/
    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 发布说明

扩展指南

新增一个 Agent 接入只需两步：

1. 在 integrations/mcp/generated/ 下新增 <agent>-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 发布说明, integrations/README.md:40-90

至此，技能扩展与跨 Agent 适配在仓库中形成「Skill 定义 → MCP 暴露 → 适配脚本注册」的闭环，使得 SWMM 工作流既能在 Claude 中对话式驱动，也能在 Codex、Hermes 等 CLI Agent 中以脚本方式批量化复用。

1. 审计框架总览与目标

agentic_swmm/audit 子包构成项目的"可审计性骨架"，由四个核心模块协同完成全链路证据留痕：

• provenance_v1_2.py 负责输出版本化的 provenance manifest，记录每次运行的输入数据、工具调用、随机种子、容器镜像摘要以及依赖版本，是 v0.6.4 字节级可重现性声明的依据。
• chat_note.py 负责将会话中的人类消息、Agent 回复以及关键工具事件落盘到 runs/<date>/<id>/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/<id>/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，便于反演。

资料来源：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() 是目前唯一带破坏性的修复动词，其内部流程为：

flowchart LR
    A[doctor 报告 CORRUPT] --> B[备份至 .bak-<ts>]
    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

Pitfall Log / 踩坑日志

项目：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