OrgTJWater/TJWaterServerBinary

Fork 0

Files

T

jiang 40e699e173 拆分代码；约束cli命令

2026-06-02 14:54:08 +08:00

22 KiB

Raw Blame History

Agent CLI 接口范围确认

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

结论

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

tjwater-cli project
tjwater-cli network
tjwater-cli component
tjwater-cli simulation
tjwater-cli analysis
tjwater-cli data
tjwater-cli help

首批默认不暴露：

会修改 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；首批默认直接在 stdout 返回结构化结果，不再额外设计 result_ref / --out-ref 输出层。
首批 CLI 只保留 Non-interactive / Agent 认证模式：必须显式注入认证上下文，不隐式复用本机默认登录态，也不设计本地 login。
stdout/stderr、退出码、输出 schema version 视为 CLI 契约的一部分，需要独立于 HTTP body 明确定义。
现有 HTTP 路径的拼写错误、双斜杠、错误方法不继承到 CLI。
高频命令可以提供 alias，但文档和 skill 只写规范命令。

分级约束

顶层命令	二级范围	说明
`project`	`list`、`info`、`db-health`、`export-inp`、`data`	项目发现和只读项目数据
`network`	`get-node-properties`、`get-link-properties`	管网节点/管线属性查询，只读
`component`	`option`	EPANET 选项设置，只读
`simulation`	`run`	模拟运行
`analysis`	`burst`、`valve`、`flushing`、`age`、`contaminant`、`sensor-placement`、`leakage`、`burst-detection`、`burst-location`、`risk`	任务级分析
`data`	`timeseries`、`scada`、`scheme`、`extension`、`misc`	数据查询
`help`	`COMMAND`	Agent 能力发现和命令说明

命令深度建议：

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

全局上下文与通用参数

首批 CLI 建议统一支持以下全局参数：

--server URL
--auth-context PATH
--scheme SCHEME
--timeout SEC
--request-id ID

参数含义：

参数	含义	作用域	说明
`--server URL`	指定 CLI 要连接的服务端地址	连接上下文	例如 `https://api.example.com`。用于覆盖环境变量或 `auth-context` 中的默认 base URL，便于在 dev / test / prod 间切换。
`--auth-context PATH`	指定一份显式的隔离认证上下文文件	认证上下文	面向 agent / 自动化调用。该文件可包含 access token、server、project、user 等字段；不得隐式回退到本机默认状态。
`--scheme SCHEME`	指定当前命令使用的方案 / 工况 / 配置集标识	业务资源上下文	适用于时序方案、检测方案、定位方案等场景。用于区分当前 project 下的不同分析配置。
`--timeout SEC`	指定本次命令等待响应的超时时间	执行控制	对同步请求表示请求超时上限，超过后 CLI 直接返回超时错误。
`--request-id ID`	为本次调用显式指定链路追踪 ID	追踪与观测	便于跨前端、CLI、服务端串联日志与审计记录。若未提供，CLI 可自动生成，并应在输出 metadata 中回显。

约束：

project 属于认证上下文的一部分，默认从 auth-context 或前端传入的 X-Project-Id 解析，不作为常规全局参数要求重复传入。
首批 CLI 不提供 Interactive / Human 登录态；所有命令都按 Agent 模式处理，不得依赖隐式默认认证状态。
--server、--auth-context 属于连接与认证上下文；--scheme 属于业务资源上下文，两者需要分开建模。
--request-id 用于链路追踪；若未显式传入，CLI 可以自动生成，但必须在输出 metadata 中回显。

参数表达建议：

用户输入的业务时间默认按 UTC+8 理解；若命令直接接收完整时间戳，应使用 ISO 8601 / RFC 3339 并显式包含时区。CLI 可直接传 +08:00，也可传其他时区的绝对时间，由服务端统一归一化。
范围参数优先拆成 --start-time / --end-time，不再引入模糊的 --time-range ... 写法。
复合输入优先使用可重复显式选项或 --input FILE，避免把多个语义字段压进 ID:SIZE、NODE:VALUE、VALVE:OPENING 这类 shell 内联 DSL。
若必须传大批量复合参数，优先支持 --input FILE，文件格式由 help 给出 schema。

首批 CLI 范围

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
TJWaterFrontend_Refine/src/lib/requestHeaders.ts
TJWaterFrontend_Refine/src/lib/api.ts
TJWaterFrontend_Refine/src/lib/apiFetch.ts

认证模式：

Non-interactive / Agent
- 面向 agent、脚本、多用户多 agent 并发调用。
- 必须显式传入认证上下文。
- 不得隐式回退到本机默认状态。

Agent 调用认证上下文：

当前前端调用链会自动附加以下请求头：
- Authorization: Bearer <access_token>
- X-Project-Id: <projectId>
- X-User-Id: <userId>
其中 Authorization 来自访问令牌，X-Project-Id 来自当前项目上下文，X-User-Id 来自当前登录用户。
因此前端触发的 agent 调用，应默认支持直接消费这三个字段；不再设计额外的本地 login 流程。
CLI 侧建议提供两类显式注入方式：
- --auth-context PATH
- 环境变量 / 调用方 header 映射

认证解析优先级建议固定为：

命令行显式参数（如 --auth-context）
调用方显式注入的环境变量 / header 映射

约束：

Agent 模式下，若未显式提供认证上下文，应返回明确错误，而不是尝试复用默认登录态。
X-Project-Id 是当前 project scope 的默认来源；CLI 命令默认直接使用该上下文，不要求重复传参。
X-User-Id 主要用于审计、结果归属和多用户隔离，不应用来替代 access token 做认证。

命令	覆盖接口	说明
`tjwater-cli project list`	`GET /meta/projects`	项目列表
`tjwater-cli project info`	`GET /meta/project`	当前 project 信息
`tjwater-cli project db-health`	`GET /meta/db/health`	当前 project 数据库健康
`tjwater-cli project export-inp --output PATH`	`GET /exportinp/`、`GET /dumpinp/`、`GET /downloadinp/`	导出当前 project 的 INP 到本地文件
`tjwater-cli project data --kind scada-info\|scheme-list\|burst-locate-result`	`GET /scada-info`、`GET /scheme-list`、`GET /burst-locate-result*`	当前 project 的业务数据

暂不暴露：

POST /auth/register
POST /auth/login
POST /auth/login/simple
GET  /auth/me
POST /auth/refresh
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-cli network get-node-properties --node NODE`	`GET /getnodeproperties/`	读取当前 project 中指定节点的属性
`tjwater-cli network get-link-properties --link LINK`	`GET /getlinkproperties/`	读取当前 project 中指定管线的属性

暂不暴露：

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

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

Component

来源：

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

命令	覆盖接口	说明
`tjwater-cli component option schema --kind time`	`GET /gettimeschema`	时间选项 schema
`tjwater-cli component option get --kind time`	`GET /gettimeproperties/`	时间选项属性
`tjwater-cli component option schema --kind energy`	`GET /getenergyschema/`	全局能耗选项 schema
`tjwater-cli component option get --kind energy`	`GET /getenergyproperties/`	全局能耗选项属性
`tjwater-cli component option schema --kind pump-energy`	`GET /getpumpenergyschema/`	泵能耗选项 schema
`tjwater-cli component option get --kind pump-energy --pump PUMP`	`GET /getpumpenergyproperties//`	指定泵的能耗选项属性
`tjwater-cli component option schema --kind network`	`GET /getoptionschema/`	管网选项 schema
`tjwater-cli component option get --kind network`	`GET /getoptionproperties/`	管网选项属性

暂不暴露：

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/

备注：

options 当前实际只读接口分为 4 组：time、energy、pump-energy、network。
pump-energy 是唯一需要额外资源标识的读取接口，必须带 --pump PUMP。
后端现有路径 GET /getpumpenergyproperties// 和 GET /setpumpenergyproperties// 存在双斜杠 / 方法异常，CLI 不继承这些路径细节，只保留语义化命令。

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-cli simulation run --start-time RFC3339 --duration MINUTES`	`POST /runsimulationmanuallybydate/`	按指定绝对开始时间触发当前 project 的实时模拟；`start-time` 必须显式带时区，结果写入服务端时序库，后续通过 `tjwater-cli data timeseries realtime *` 查询
`tjwater-cli analysis burst --start-time TIME --duration SEC --scheme SCHEME --burst-file FILE`	`GET /burst_analysis/`	爆管分析；`FILE` 提供爆管点与流量列表，CLI 负责转换为 `burst_ID[]` / `burst_size[]`
`tjwater-cli analysis valve --mode close\|isolation --start-time TIME --valve VALVE`	`GET /valve_close_analysis/`、`GET /valve_isolation_analysis/`	阀门分析，`--valve` 可重复
`tjwater-cli analysis flushing --start-time TIME --valve-setting-file FILE --drainage-node NODE --flow FLOW [--duration SEC] [--scheme SCHEME]`	`GET /flushing_analysis/`	冲洗分析；`FILE` 提供阀门与开度列表，CLI 负责转换为 `valves[]` / `valves_k[]`
`tjwater-cli analysis age --start-time TIME --duration SEC`	`GET /age_analysis/`	水龄分析
`tjwater-cli analysis contaminant --start-time TIME --duration SEC --source-node NODE --concentration VALUE [--pattern PATTERN] [--scheme SCHEME]`	`GET /contaminant_simulation/`	污染物模拟
`tjwater-cli analysis sensor-placement kmeans --count N`	`GET /pressuresensorplacementkmeans/`	基于 kmeans 的传感器放置分析；不包含创建方案
`tjwater-cli analysis leakage identify --scheme SCHEME --start-time TIME --end-time TIME`	`POST /leakage/identify/`	漏损识别
`tjwater-cli analysis leakage schemes list\|get`	`GET /leakage/schemes/`、`GET /leakage/schemes/{scheme_name}`	漏损方案查询
`tjwater-cli analysis burst-detection detect --scheme SCHEME --start-time TIME --end-time TIME`	`POST /burst-detection/detect/`	爆管检测
`tjwater-cli analysis burst-detection schemes list\|get`	`GET /burst-detection/schemes/`、`GET /burst-detection/schemes/{scheme_name}`	爆管检测方案查询
`tjwater-cli analysis burst-location locate --scheme SCHEME --start-time TIME --end-time TIME`	`POST /burst-location/locate/`	爆管定位
`tjwater-cli analysis burst-location schemes list\|get`	`GET /burst-location/schemes/`、`GET /burst-location/schemes/{scheme_name}`	爆管定位方案查询
`tjwater-cli analysis risk pipe-now --pipe PIPE`	`GET /getpiperiskprobabilitynow/`	单条管道当前风险
`tjwater-cli analysis risk pipe-history --pipe PIPE`	`GET /getpiperiskprobability/`	单条管道历史风险
`tjwater-cli analysis risk network`	`GET /getnetworkpiperiskprobabilitynow/`、`GET /getpiperiskprobabilitygeometries/`	当前 project 全网风险

暂缓或暂不暴露：

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

执行模型：

首批 CLI 统一按同步命令设计，避免引入额外的异步轮询协议。
simulation run 不直接回传全量模拟结果；它负责触发服务端模拟，并返回执行摘要、时间窗口和后续查询提示。
当前 runsimulationmanuallybydate 接口会从 start_time 指定的绝对时间开始，按 15 分钟步长运行直到达到 duration，结果持久化到服务端时序存储。
start_time 必须显式带时区；CLI 推荐直接传 UTC+8 时间，服务端统一转换后执行和落库。CLI 文档与帮助信息需要把这条规则写成显式契约，不能把数据库存储时间直接暴露成用户输入语义。
模拟结果读取统一走 tjwater-cli data timeseries realtime *，而不是再单独设计 simulation output。
analysis 相关命令首批也按同步请求处理；若后续服务端真的引入任务队列，再单独设计 job 类基础设施能力。

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-cli data timeseries realtime links --start-time TIME --end-time TIME`	`GET /realtime/links`	查询指定时间范围内的实时/模拟管道数据
`tjwater-cli data timeseries realtime nodes --start-time TIME --end-time TIME`	`GET /realtime/nodes`	查询指定时间范围内的实时/模拟节点数据
`tjwater-cli data timeseries realtime simulation-by-id-time --id ID --type pipe\|junction --time TIME`	`GET /realtime/query/by-id-time`	查询指定元素在指定时间点的模拟结果
`tjwater-cli data timeseries realtime simulation-by-time-property --type pipe\|junction --time TIME --property PROPERTY`	`GET /realtime/query/by-time-property`	查询指定时间点某类元素某属性的聚合模拟结果
`tjwater-cli data timeseries scheme links --scheme SCHEME --start-time TIME --end-time TIME`	`GET /scheme/links`、`GET /scheme/links/{link_id}/field`	方案管道数据
`tjwater-cli data timeseries scheme node-field --node NODE --field FIELD`	`GET /scheme/nodes/{node_id}/field`	方案节点字段
`tjwater-cli data timeseries scheme simulation --query by-id-time\|by-scheme-time-property --scheme SCHEME --id ID --time TIME --property PROPERTY`	`GET /scheme/query/*`	方案模拟查询
`tjwater-cli data timeseries scada query --device-id ID --start-time TIME --end-time TIME [--device-id ID ...] [--field FIELD]`	`GET /scada/by-ids-time-range`、`GET /scada/by-ids-field-time-range`	SCADA 时序；CLI 把重复 `--device-id` 转换为后端逗号分隔参数
`tjwater-cli data timeseries composite --kind scada-simulation\|element-simulation\|element-scada --feature FEATURE --start-time TIME --end-time TIME`	`GET /composite/*`	复合查询，`--feature` 可重复
`tjwater-cli data timeseries composite pipeline-health --pipe PIPE --start-time TIME --end-time TIME`	`GET /composite/pipeline-health-prediction`	管道健康预测
`tjwater-cli data scada schema --kind device\|device-data\|element\|info`	`GET /getscada*schema/`	`SCADA` 元数据 `schema`
`tjwater-cli data scada get\|list --kind device\|device-data\|element\|info`	`scada.py` 下 `GET` 查询接口	`SCADA` 元数据
`tjwater-cli data scheme schema\|get\|list`	`schemes.py` 下 `GET` 接口	当前 project 方案查询
`tjwater-cli data extension keys\|get\|list`	`extension.py` 下 `GET` 查询接口	当前 project 扩展数据查询
`tjwater-cli data misc sensor-placements`	`GET /getallsensorplacements/`	当前 project 传感器位置
`tjwater-cli data misc burst-location-results`	`GET /getallburstlocateresults/`	当前 project 爆管定位结果

realtime 是首批 simulation 结果的主读取域；CLI 可以按任务语义组合 links、nodes、simulation-by-id-time、simulation-by-time-property，但底层数据源仍以 realtime.py 为准。
realtime、scheme、composite 等时间查询命令面向用户时仍按 UTC+8 输入；CLI/服务端负责转换为后端使用的 UTC0 条件进行检索。若返回结果直接包含时间戳，必须显式带时区，避免把存储时间和展示时间混淆。

暂不暴露：

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

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

命令	说明
`tjwater-cli help`	返回当前 CLI 能力清单，供 Agent 发现可用命令
`tjwater-cli help COMMAND`	返回某个命令的参数、输出、示例和推荐后续命令

输出补充约束：

首批 CLI 不再设计通用 result_ref / --out-ref 机制。
若某业务命令确实需要落本地文件，应由所属命令显式提供 --output PATH，例如 project export-inp --output PATH。
若后续出现超大结果集、必须脱离 stdout 传输时，再单独设计结果引用机制，而不是在首批 CLI 中预埋未闭环能力。

输出规范

进程级契约：

stdout：默认只输出一个 JSON 对象，供 agent / 脚本稳定解析。
stderr：输出进度、警告和诊断信息；不得混入结构化结果 JSON。
退出码必须稳定，不能简单透传底层 HTTP status。

建议退出码：

退出码	含义
`0`	成功
`2`	CLI 参数错误 / 用法错误
`3`	认证失败
`4`	权限不足
`5`	资源不存在
`6`	冲突、前置条件不满足或非法状态
`7`	服务端错误

成功：

{
  "ok": true,
  "schema_version": "tjwater-cli/v1",
  "summary": "读取成功",
  "data": {},
  "metadata": {},
  "next_commands": []
}

失败：

{
  "ok": false,
  "schema_version": "tjwater-cli/v1",
  "summary": "认证失败",
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "missing access token for agent context",
    "retryable": false
  },
  "data": null,
  "metadata": {},
  "next_commands": [
    "tjwater-cli <command> --auth-context /path/to/auth-context.json"
  ]
}

补充约束：

metadata 至少建议包含：request_id、server、duration_ms、generated_at。
next_commands 是面向 agent 的推荐后续动作，不影响退出码和主结果语义。
所有 help 输出也应带 schema_version，便于 agent 做能力协商。

后续开放条件

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

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

22 KiB Raw Blame History Unescape Escape

Agent CLI 接口范围确认

结论

设计原则

分级约束

全局上下文与通用参数

首批 CLI 范围

Project

Network

Component

Simulation / Analysis / Risk

Data

不纳入首批 CLI 的运维接口

Help

输出规范

后续开放条件

22 KiB

Raw Blame History