TJWaterServerBinary/agent_cli_endpoint_scope.md

Agent CLI 接口范围确认

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

结论

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

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

来源：

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*	项目业务数据

暂不暴露：

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

来源：

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/	标签信息

暂不暴露：

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

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

Component

来源：

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 下只读接口	图形元素、标签、背景

暂不暴露：

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

来源：

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/	全网风险

暂缓或暂不暴露：

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

来源：

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/	爆管定位结果

暂不暴露：

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 的运维接口

来源：

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 面向水务业务分析的核心调用范围。

暂不暴露：

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	导出结果

输出规范

成功：

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

失败：

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

大结果：

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

后续开放条件

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

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