TJWaterServerBinary/agent_cli_endpoint_scope.md

# Agent CLI 接口范围确认

本文档确认 `app/api/v1/endpoints/` 面向 Agent CLI 的首批封装范围。

## 结论

首批 CLI 采用 **少量顶层入口 + 业务域二级分组 + 只读/分析优先** 的设计。

```text
tjwater auth
tjwater project
tjwater network
tjwater component
tjwater simulation
tjwater analysis
tjwater data
tjwater help
tjwater result
```

首批默认不暴露：

- 会修改 network 的接口：`add*`、`set*`、`delete*`、`generate*`
- 项目生命周期接口：创建、删除、导入、打开、关闭、锁定、解锁、复制
- 数据写入/清理接口：insert、update、delete、clean、clear、batch store
- 用户管理接口：创建、更新、删除、激活、停用
- 快照回滚和批量命令执行接口：undo、redo、pick、batch

## 设计原则

- CLI 不按 HTTP endpoint 一比一映射，而按 Agent 任务组织。
- 首批只暴露 `schema`、`list`、`get`、`exists`、只读计算和分析类能力。
- CLI 输入优先使用显式选项、可重复选项、枚举值和文件路径，尽量不要求用户直接输入 JSON。
- CLI 输出统一使用 JSON；大结果写入 result-ref，只在 stdout 返回摘要、路径和元数据。
- 现有 HTTP 路径的拼写错误、双斜杠、错误方法不继承到 CLI。
- 高频命令可以提供 alias，但文档和 skill 只写规范命令。

## 分级约束

| 顶层命令 | 二级范围 | 说明 |
|---|---|---|
| `auth` | `me`、`refresh` | 登录态和当前用户 |
| `project` | `list`、`info`、`status`、`export-inp`、`data` | 项目发现和只读项目数据 |
| `network` | `list`、`get`、`schema`、`exists`、`geometry`、`region`、`tag` | 管网拓扑、元素、几何、分区，只读 |
| `component` | `curve`、`pattern`、`option`、`control`、`quality`、`visual` | EPANET 组件类能力 |
| `simulation` | `run`、`run-inp`、`output` | 模拟运行和模拟输出 |
| `analysis` | `burst`、`leakage`、`valve`、`flushing`、`age`、`sensor-placement`、`risk` | 任务级分析 |
| `data` | `timeseries`、`scada`、`scheme`、`extension`、`misc` | 数据查询 |
| `help` | `--json`、`COMMAND --json` | Agent 能力发现和命令说明 |
| `result` | `show`、`metadata`、`export` | `result-ref` 读取和导出 |

命令深度建议：

- 常规命令不超过 3 层：`tjwater component curve list`
- 时序数据允许 4 层：`tjwater data timeseries realtime links`
- `risk` 归入 `analysis risk`
- `scada`、`scheme`、`extension` 归入 `data`

## 首批 CLI 范围

### Auth / Project

来源：

```text
app/api/v1/endpoints/auth.py
app/api/v1/endpoints/meta.py
app/api/v1/endpoints/project.py
app/api/v1/endpoints/project_data.py
```

| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater auth me` | `GET /auth/me` | 当前登录用户 |
| `tjwater auth refresh` | `POST /auth/refresh` | 仅在 CLI 需要维护登录态时暴露 |
| `tjwater project list` | `GET /meta/projects` | 项目列表 |
| `tjwater project info --project PROJECT` | `GET /meta/project` | 项目信息 |
| `tjwater project db-health --project PROJECT` | `GET /meta/db/health` | 项目数据库健康 |
| `tjwater project export-inp --project PROJECT --out-ref` | `GET /exportinp/`、`GET /dumpinp/`、`GET /downloadinp/` | 导出 INP，写 `result-ref` |
| `tjwater project data --project PROJECT --kind scada-info\|scheme-list\|burst-locate-result` | `GET /scada-info`、`GET /scheme-list`、`GET /burst-locate-result*` | 项目业务数据 |

暂不暴露：

```text
POST /auth/register
POST /auth/login
POST /auth/login/simple
GET  /listprojects/
GET  /project_info/
GET  /haveproject/
GET  /isprojectopen/
GET  /isprojectlocked/
GET  /isprojectlockedbyme/
POST /createproject/
POST /deleteproject/
POST /openproject/
POST /closeproject/
POST /copyproject/
POST /importinp/
POST /readinp/
POST /lockproject/
POST /unlockproject/
POST /uploadinp/
GET  /convertv3tov2/
```

### Network

来源：

```text
app/api/v1/endpoints/network/*.py
```

| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater network list --network NET --type nodes\|links` | `GET /getnodes/`、`GET /getlinks/` | 节点/管线 ID 列表 |
| `tjwater network exists --network NET --type node\|link\|junction\|pipe\|... --id ID` | `GET /isnode/`、`GET /islink/` 等 | 元素存在性 |
| `tjwater network type --network NET --id ID` | `GET /getnodetype/`、`GET /getlinktype/`、`GET /getelementtype/` | 元素类型 |
| `tjwater network get --network NET --id ID` | `GET /getelementproperties/`、`GET /getnodeproperties/`、`GET /getlinkproperties/` | 自动识别类型并取属性 |
| `tjwater network get --network NET --type junction\|pipe\|pump\|... --id ID` | 各类 `get*properties` | 指定类型取属性 |
| `tjwater network list-properties --network NET --type junction\|pipe\|pump\|... --out-ref` | 各类 `getall*properties` | 全量属性，写 `result-ref` |
| `tjwater network schema --network NET --type junction\|reservoir\|tank\|pipe\|pump\|valve\|demand\|tag\|region` | 各类 `get*schema` | 属性架构 |
| `tjwater network links-of-node --network NET --node NODE` | `GET /getnodelinks/` | 节点关联管线 |
| `tjwater network geometry --network NET --scope full\|extent\|major-nodes\|major-pipes\|link-nodes --out-ref` | `geometry.py` 下 `GET` 接口 | 几何数据 |
| `tjwater network demand-calc --network NET --scope node\|region\|network --out-ref` | `GET /calculatedemandto*/` | 需水量计算 |
| `tjwater network region get\|list\|schema --network NET --kind dma\|service-area\|virtual-district` | `regions.py` 下 `GET` 查询接口 | 分区信息 |
| `tjwater network region-calc --network NET --kind dma\|service-area\|virtual-district --out-ref` | `GET /calculate*/` | 分区计算 |
| `tjwater network tag get\|list\|schema --network NET` | `GET /gettag/`、`GET /gettags/`、`GET /gettagschema/` | 标签信息 |

暂不暴露：

```text
add*
set*
delete*
generate*
POST /generatedistrictmeteringarea/
POST /generatesubdistrictmeteringarea/
POST /generateservicearea/
POST /generatevirtualdistrict/
```

备注：`GET /settitle/` 语义是修改标题，首批不暴露。

### Component

来源：

```text
app/api/v1/endpoints/components/*.py
```

| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater component curve schema\|list\|get\|exists` | `curves.py` 下只读接口 | 曲线 |
| `tjwater component pattern schema\|list\|get\|exists` | `patterns.py` 下只读接口 | 模式 |
| `tjwater component option schema\|get --kind time\|energy\|pump-energy\|general` | `options.py` 下只读接口 | 时间、能耗、泵能耗、通用选项 |
| `tjwater component control schema\|get --kind control\|rule` | `controls.py` 下只读接口 | 控制和规则 |
| `tjwater component quality schema\|get --kind quality\|emitter\|source\|reaction\|pipe-reaction\|tank-reaction\|mixing` | `quality.py` 下只读接口 | 水质相关组件 |
| `tjwater component visual schema\|list\|get --kind vertex\|label\|backdrop\|vertex-links\|vertices` | `visuals.py` 下只读接口 | 图形元素、标签、背景 |

暂不暴露：

```text
POST /addcurve/
POST /setcurveproperties/
POST /deletecurve/
POST /addpattern/
POST /setpatternproperties/
POST /deletepattern/
POST /settimeproperties/
POST /setenergyproperties/
GET  /setpumpenergyproperties//
POST /setoptionproperties/
POST /setcontrolproperties/
POST /setruleproperties/
POST /setqualityproperties/
POST /setemitterproperties/
POST /setsource/
POST /addsource/
POST /deletesource/
POST /setreaction/
POST /setpipereaction/
POST /settankreaction/
POST /setmixing/
POST /addmixing/
POST /deletemixing/
POST /setvertexproperties/
POST /addvertex/
POST /deletevertex/
POST /setlabelproperties/
POST /addlabel/
POST /deletelabel/
POST /setbackdropproperties/
```

备注：

- `getsourcechema` 路径拼写疑似错误，CLI 统一使用 `component quality schema --kind source`。
- `getallvertexlinks`、`getallvertices` 当前返回 JSON 字符串，CLI 应输出标准 JSON。

### Simulation / Analysis / Risk

来源：

```text
app/api/v1/endpoints/simulation.py
app/api/v1/endpoints/leakage.py
app/api/v1/endpoints/burst_detection.py
app/api/v1/endpoints/burst_location.py
app/api/v1/endpoints/risk.py
```

| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater simulation run --project PROJECT --out-ref` | `GET /runprojectreturndict/` | 运行项目模拟，使用结构化 JSON 返回 |
| `tjwater simulation run-inp --inp PATH --out-ref` | `GET /runinp/` | 运行 INP |
| `tjwater simulation output --project PROJECT --out-ref` | `GET /dumpoutput/` | 导出模拟输出 |
| `tjwater analysis burst --project PROJECT --start-time TIME --duration SEC --burst ID:SIZE --out-ref` | `GET /burst_analysis/` | 爆管分析，`--burst` 可重复 |
| `tjwater analysis valve --project PROJECT --mode close\|isolation --start-time TIME --valve VALVE --out-ref` | `GET /valve_close_analysis/`、`GET /valve_isolation_analysis/` | 阀门分析，`--valve` 可重复 |
| `tjwater analysis flushing --project PROJECT --start-time TIME --valve VALVE:OPENING --drainage-node NODE --flow FLOW --out-ref` | `GET /flushing_analysis/` | 冲洗分析，`--valve` 可重复 |
| `tjwater analysis age --project PROJECT --start-time TIME --duration SEC --out-ref` | `GET /age_analysis/` | 水龄分析 |
| `tjwater analysis contaminant --project PROJECT --start-time TIME --duration SEC --source NODE:VALUE --out-ref` | `GET /contaminant_simulation/` | 污染物模拟 |
| `tjwater analysis sensor-placement --project PROJECT --method sensitivity\|kmeans --count N --out-ref` | 传感器放置分析接口 | 不包含创建方案 |
| `tjwater analysis leakage identify --scheme SCHEME --start-time TIME --end-time TIME --out-ref` | `POST /leakage/identify/` | 漏损识别 |
| `tjwater analysis leakage schemes list\|get` | `GET /leakage/schemes/`、`GET /leakage/schemes/{scheme_name}` | 漏损方案查询 |
| `tjwater analysis burst-detection detect --scheme SCHEME --start-time TIME --end-time TIME --out-ref` | `POST /burst-detection/detect/` | 爆管检测 |
| `tjwater analysis burst-detection schemes list\|get` | `GET /burst-detection/schemes/`、`GET /burst-detection/schemes/{scheme_name}` | 爆管检测方案查询 |
| `tjwater analysis burst-location locate --scheme SCHEME --start-time TIME --end-time TIME --out-ref` | `POST /burst-location/locate/` | 爆管定位 |
| `tjwater analysis burst-location schemes list\|get` | `GET /burst-location/schemes/`、`GET /burst-location/schemes/{scheme_name}` | 爆管定位方案查询 |
| `tjwater analysis risk pipe --network NET --pipe PIPE --time-range ...` | `risk.py` 下管道风险 `GET` 接口 | 管道风险 |
| `tjwater analysis risk network --network NET --out-ref` | `GET /getnetworkpiperiskprobabilitynow/`、`GET /getpiperiskprobabilitygeometries/` | 全网风险 |

暂缓或暂不暴露：

```text
POST /network_project/
GET  /runproject/
POST /network_update/
POST /project_management/
POST /sensorplacementscheme/create
POST /runsimulationmanuallybydate/
POST /pump_failure/
POST /pressure_regulation/
POST /scheduling_analysis/
POST /daily_scheduling_analysis/
```

### Data

来源：

```text
app/api/v1/endpoints/timeseries/*.py
app/api/v1/endpoints/scada.py
app/api/v1/endpoints/schemes.py
app/api/v1/endpoints/extension.py
app/api/v1/endpoints/misc.py
app/api/v1/endpoints/project_data.py
```

| 命令 | 覆盖接口 | 说明 |
|---|---|---|
| `tjwater data timeseries realtime links --start-time TIME --end-time TIME --out-ref` | `GET /realtime/links` | 实时管道数据 |
| `tjwater data timeseries realtime nodes --start-time TIME --end-time TIME --out-ref` | `GET /realtime/nodes` | 实时节点数据 |
| `tjwater data timeseries realtime simulation --query by-id-time\|by-time-property --id ID --time TIME --property PROPERTY --out-ref` | `GET /realtime/query/*` | 实时模拟查询 |
| `tjwater data timeseries scheme links --scheme SCHEME --start-time TIME --end-time TIME --out-ref` | `GET /scheme/links`、`GET /scheme/links/{link_id}/field` | 方案管道数据 |
| `tjwater data timeseries scheme node-field --node NODE --field FIELD --out-ref` | `GET /scheme/nodes/{node_id}/field` | 方案节点字段 |
| `tjwater data timeseries scheme simulation --query by-id-time\|by-scheme-time-property --scheme SCHEME --id ID --time TIME --property PROPERTY --out-ref` | `GET /scheme/query/*` | 方案模拟查询 |
| `tjwater data timeseries scada query --device-ids ... --time-range ... --out-ref` | `GET /scada/by-ids-time-range`、`GET /scada/by-ids-field-time-range` | SCADA 时序 |
| `tjwater data timeseries composite --kind scada-simulation\|element-simulation\|element-scada --feature FEATURE --start-time TIME --end-time TIME --out-ref` | `GET /composite/*` | 复合查询，`--feature` 可重复 |
| `tjwater data timeseries composite pipeline-health --pipe PIPE --start-time TIME --end-time TIME --out-ref` | `GET /composite/pipeline-health-prediction` | 管道健康预测 |
| `tjwater data scada schema --kind device\|device-data\|element\|info` | `GET /getscada*schema/` | `SCADA` 元数据 `schema` |
| `tjwater data scada get\|list --kind device\|device-data\|element\|info` | `scada.py` 下 `GET` 查询接口 | `SCADA` 元数据 |
| `tjwater data scheme schema\|get\|list --network NET` | `schemes.py` 下 `GET` 接口 | 方案查询 |
| `tjwater data extension keys\|get\|list --network NET` | `extension.py` 下 `GET` 查询接口 | 扩展数据查询 |
| `tjwater data misc sensor-placements --network NET --out-ref` | `GET /getallsensorplacements/` | 传感器位置 |
| `tjwater data misc burst-location-results --network NET --out-ref` | `GET /getallburstlocateresults/` | 爆管定位结果 |

暂不暴露：

```text
POST   /realtime/*/batch
DELETE /realtime/*
PATCH  /realtime/*
POST   /realtime/simulation/store
POST   /scheme/*/batch
PATCH  /scheme/*
DELETE /scheme/*
POST   /scheme/simulation/store
POST   /scada/batch
PATCH  /scada/{device_id}/field
DELETE /scada/by-id-time-range
POST   /composite/clean-scada
POST   /setscadadevice/
POST   /addscadadevice/
POST   /deletescadadevice/
POST   /cleanscadadevice/
POST   /setscadadevicedata/
POST   /addscadadevicedata/
POST   /deletescadadevicedata/
POST   /cleanscadadevicedata/
POST   /setscadaelement/
POST   /addscadaelement/
POST   /deletescadaelement/
POST   /cleanscadaelement/
POST   /setextensiondata/
POST   /test_dict/
GET    /getjson/
```

### 不纳入首批 CLI 的运维接口

来源：

```text
app/api/v1/endpoints/snapshots.py
app/api/v1/endpoints/cache.py
app/api/v1/endpoints/audit.py
app/api/v1/endpoints/users.py
app/api/v1/endpoints/user_management.py
```

这些接口不纳入首批 Agent CLI。原因是它们更偏运维、审计、用户管理或状态回滚，不属于 Agent 面向水务业务分析的核心调用范围。

暂不暴露：

```text
GET  /getcurrentoperationid/
GET  /getsnapshots/
GET  /havesnapshot/
GET  /havesnapshotforoperation/
GET  /havesnapshotforcurrentoperation/
GET  /getrestoreoperation/
POST /undo/
POST /redo/
POST /takesnapshot*/
POST /picksnapshot/
POST /pickoperation/
GET  /syncwithserver/
POST /batch/
POST /compressedbatch/
POST /setrestoreoperation/
GET  /queryredis/
POST /clearrediskey/
POST /clearrediskeys/
POST /clearallredis/
GET  /audit/logs
GET  /audit/logs/my
GET  /audit/logs/count
GET  /getuserschema/
GET  /getuser/
GET  /getallusers/
PUT    /users/{user_id}
DELETE /users/{user_id}
POST   /users/{user_id}/activate
POST   /users/{user_id}/deactivate
```

## Help / Result

这两个模块不直接对应现有 endpoint，但建议作为 Agent CLI 的基础设施。能力发现更适合复用 CLI 的 `help` 语义，而不是新增一个偏内部化的 `capability` 顶层命令。

| 命令 | 说明 |
|---|---|
| `tjwater help --json` | 返回当前 CLI 能力清单，供 Agent 发现可用命令 |
| `tjwater help COMMAND --json` | 返回某个命令的参数、输出、示例和推荐后续命令 |
| `tjwater result show REF` | 读取 `result-ref` 内容，必要时分页或摘要 |
| `tjwater result metadata REF` | 读取 `result-ref` 元数据 |
| `tjwater result export REF --format json\|csv` | 导出结果 |

## 输出规范

成功：

```json
{
  "ok": true,
  "summary": "读取成功",
  "data": {},
  "result_ref": null,
  "metadata": {},
  "next_commands": []
}
```

失败：

```json
{
  "ok": false,
  "error": "invalid_argument",
  "message": "缺少必要参数 --network",
  "recoverable": true,
  "suggested_command": "tjwater component curve list --network NET"
}
```

大结果：

```json
{
  "ok": true,
  "summary": "查询完成，结果已写入 result-ref",
  "result_ref": "TJWaterAgent/data/result-refs/example.json",
  "metadata": {
    "schema": "network_properties_v1",
    "rows": 1200
  }
}
```

## 后续开放条件

如后续要开放写操作，需要单独设计：

- 权限校验
- dry-run / preview
- 显式确认机制
- 审计日志
- 变更快照
- 回滚策略
- Agent 可读的错误恢复建议