From 60db2a719348fe0347bff5a692bc0d597df39c2c Mon Sep 17 00:00:00 2001 From: Jiang Date: Mon, 1 Jun 2026 17:05:26 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=20cli=20=E5=91=BD=E4=BB=A4?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- agent_cli_endpoint_scope.md | 269 ++++++++++++++++++++++++------------ 1 file changed, 180 insertions(+), 89 deletions(-) diff --git a/agent_cli_endpoint_scope.md b/agent_cli_endpoint_scope.md index 8df0f46..0a3d837 100644 --- a/agent_cli_endpoint_scope.md +++ b/agent_cli_endpoint_scope.md @@ -7,7 +7,6 @@ 首批 CLI 采用 **少量顶层入口 + 业务域二级分组 + 只读/分析优先** 的设计。 ```text -tjwater auth tjwater project tjwater network tjwater component @@ -15,7 +14,6 @@ tjwater simulation tjwater analysis tjwater data tjwater help -tjwater result ``` 首批默认不暴露： @@ -31,7 +29,9 @@ tjwater result - CLI 不按 HTTP endpoint 一比一映射，而按 Agent 任务组织。 - 首批只暴露 `schema`、`list`、`get`、`exists`、只读计算和分析类能力。 - CLI 输入优先使用显式选项、可重复选项、枚举值和文件路径，尽量不要求用户直接输入 JSON。 -- CLI 输出统一使用 JSON；大结果写入 result-ref，只在 stdout 返回摘要、路径和元数据。 +- CLI 输出统一使用 JSON；首批默认直接在 stdout 返回结构化结果，不再额外设计 `result_ref` / `--out-ref` 输出层。 +- 首批 CLI 只保留 **Non-interactive / Agent** 认证模式：必须显式注入认证上下文，不隐式复用本机默认登录态，也不设计本地 `login`。 +- stdout/stderr、退出码、输出 schema version 视为 CLI 契约的一部分，需要独立于 HTTP body 明确定义。 - 现有 HTTP 路径的拼写错误、双斜杠、错误方法不继承到 CLI。 - 高频命令可以提供 alias，但文档和 skill 只写规范命令。 @@ -39,26 +39,60 @@ tjwater result | 顶层命令 | 二级范围 | 说明 | |---|---|---| -| `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` | 任务级分析 | +| `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` | `--json`、`COMMAND --json` | Agent 能力发现和命令说明 | -| `result` | `show`、`metadata`、`export` | `result-ref` 读取和导出 | 命令深度建议： -- 常规命令不超过 3 层：`tjwater component curve list` +- 常规命令不超过 3 层：`tjwater component option get` - 时序数据允许 4 层：`tjwater data timeseries realtime links` - `risk` 归入 `analysis risk` - `scada`、`scheme`、`extension` 归入 `data` +## 全局上下文与通用参数 + +首批 CLI 建议统一支持以下全局参数： + +```text +--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 --json` 给出 schema。 + ## 首批 CLI 范围 -### Auth / Project +### Project 来源： @@ -67,17 +101,48 @@ 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 ` + - `X-Project-Id: ` + - `X-User-Id: ` +- 其中 `Authorization` 来自访问令牌，`X-Project-Id` 来自当前项目上下文，`X-User-Id` 来自当前登录用户。 +- 因此前端触发的 agent 调用，应默认支持直接消费这三个字段；不再设计额外的本地 `login` 流程。 +- CLI 侧建议提供两类显式注入方式： + - `--auth-context PATH` + - 环境变量 / 调用方 header 映射 + +认证解析优先级建议固定为： + +1. 命令行显式参数（如 `--auth-context`） +2. 调用方显式注入的环境变量 / header 映射 + +约束： + +- Agent 模式下，若未显式提供认证上下文，应返回明确错误，而不是尝试复用默认登录态。 +- `X-Project-Id` 是当前 project scope 的默认来源；CLI 命令默认直接使用该上下文，不要求重复传参。 +- `X-User-Id` 主要用于审计、结果归属和多用户隔离，不应用来替代 access token 做认证。 + | 命令 | 覆盖接口 | 说明 | |---|---|---| -| `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*` | 项目业务数据 | +| `tjwater project info` | `GET /meta/project` | 当前 project 信息 | +| `tjwater project db-health` | `GET /meta/db/health` | 当前 project 数据库健康 | +| `tjwater project export-inp --output PATH` | `GET /exportinp/`、`GET /dumpinp/`、`GET /downloadinp/` | 导出当前 project 的 INP 到本地文件 | +| `tjwater project data --kind scada-info\|scheme-list\|burst-locate-result` | `GET /scada-info`、`GET /scheme-list`、`GET /burst-locate-result*` | 当前 project 的业务数据 | 暂不暴露： @@ -85,6 +150,8 @@ app/api/v1/endpoints/project_data.py POST /auth/register POST /auth/login POST /auth/login/simple +GET /auth/me +POST /auth/refresh GET /listprojects/ GET /project_info/ GET /haveproject/ @@ -114,19 +181,8 @@ 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/` | 标签信息 | +| `tjwater network get-node-properties --node NODE` | `GET /getnodeproperties/` | 读取当前 project 中指定节点的属性 | +| `tjwater network get-link-properties --link LINK` | `GET /getlinkproperties/` | 读取当前 project 中指定管线的属性 | 暂不暴露： @@ -153,12 +209,14 @@ 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` 下只读接口 | 图形元素、标签、背景 | +| `tjwater component option schema --kind time` | `GET /gettimeschema` | 时间选项 schema | +| `tjwater component option get --kind time` | `GET /gettimeproperties/` | 时间选项属性 | +| `tjwater component option schema --kind energy` | `GET /getenergyschema/` | 全局能耗选项 schema | +| `tjwater component option get --kind energy` | `GET /getenergyproperties/` | 全局能耗选项属性 | +| `tjwater component option schema --kind pump-energy` | `GET /getpumpenergyschema/` | 泵能耗选项 schema | +| `tjwater component option get --kind pump-energy --pump PUMP` | `GET /getpumpenergyproperties//` | 指定泵的能耗选项属性 | +| `tjwater component option schema --kind network` | `GET /getoptionschema/` | 管网选项 schema | +| `tjwater component option get --kind network` | `GET /getoptionproperties/` | 管网选项属性 | 暂不暴露： @@ -197,8 +255,9 @@ POST /setbackdropproperties/ 备注： -- `getsourcechema` 路径拼写疑似错误，CLI 统一使用 `component quality schema --kind source`。 -- `getallvertexlinks`、`getallvertices` 当前返回 JSON 字符串，CLI 应输出标准 JSON。 +- `options` 当前实际只读接口分为 4 组：`time`、`energy`、`pump-energy`、`network`。 +- `pump-energy` 是唯一需要额外资源标识的读取接口，必须带 `--pump PUMP`。 +- 后端现有路径 `GET /getpumpenergyproperties//` 和 `GET /setpumpenergyproperties//` 存在双斜杠 / 方法异常，CLI 不继承这些路径细节，只保留语义化命令。 ### Simulation / Analysis / Risk @@ -214,23 +273,22 @@ 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 simulation run --start-time RFC3339 --duration MINUTES` | `POST /runsimulationmanuallybydate/` | 按指定绝对开始时间触发当前 project 的实时模拟；`start-time` 必须显式带时区，结果写入服务端时序库，后续通过 `tjwater data timeseries realtime *` 查询 | +| `tjwater analysis burst --start-time TIME --duration SEC --scheme SCHEME --burst-file FILE` | `GET /burst_analysis/` | 爆管分析；`FILE` 提供爆管点与流量列表，CLI 负责转换为 `burst_ID[]` / `burst_size[]` | +| `tjwater analysis valve --mode close\|isolation --start-time TIME --valve VALVE` | `GET /valve_close_analysis/`、`GET /valve_isolation_analysis/` | 阀门分析，`--valve` 可重复 | +| `tjwater 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 analysis age --start-time TIME --duration SEC` | `GET /age_analysis/` | 水龄分析 | +| `tjwater analysis contaminant --start-time TIME --duration SEC --source-node NODE --concentration VALUE [--pattern PATTERN] [--scheme SCHEME]` | `GET /contaminant_simulation/` | 污染物模拟 | +| `tjwater analysis sensor-placement kmeans --count N` | `GET /pressuresensorplacementkmeans/` | 基于 kmeans 的传感器放置分析；不包含创建方案 | +| `tjwater analysis leakage identify --scheme SCHEME --start-time TIME --end-time TIME` | `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 detect --scheme SCHEME --start-time TIME --end-time TIME` | `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 locate --scheme SCHEME --start-time TIME --end-time TIME` | `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/` | 全网风险 | +| `tjwater analysis risk pipe-now --pipe PIPE` | `GET /getpiperiskprobabilitynow/` | 单条管道当前风险 | +| `tjwater analysis risk pipe-history --pipe PIPE` | `GET /getpiperiskprobability/` | 单条管道历史风险 | +| `tjwater analysis risk network` | `GET /getnetworkpiperiskprobabilitynow/`、`GET /getpiperiskprobabilitygeometries/` | 当前 project 全网风险 | 暂缓或暂不暴露： @@ -240,13 +298,21 @@ 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/ ``` +执行模型： + +- 首批 CLI 统一按同步命令设计，避免引入额外的异步轮询协议。 +- `simulation run` 不直接回传全量模拟结果；它负责触发服务端模拟，并返回执行摘要、时间窗口和后续查询提示。 +- 当前 `runsimulationmanuallybydate` 接口会从 `start_time` 指定的绝对时间开始，按 15 分钟步长运行直到达到 `duration`，结果持久化到服务端时序存储。 +- `start_time` 必须显式带时区；CLI 推荐直接传 **UTC+8** 时间，服务端统一转换后执行和落库。CLI 文档与帮助信息需要把这条规则写成显式契约，不能把数据库存储时间直接暴露成用户输入语义。 +- 模拟结果读取统一走 `tjwater data timeseries realtime *`，而不是再单独设计 `simulation output`。 +- `analysis` 相关命令首批也按同步请求处理；若后续服务端真的引入任务队列，再单独设计 `job` 类基础设施能力。 + ### Data 来源： @@ -262,21 +328,25 @@ 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 timeseries realtime links --start-time TIME --end-time TIME` | `GET /realtime/links` | 查询指定时间范围内的实时/模拟管道数据 | +| `tjwater data timeseries realtime nodes --start-time TIME --end-time TIME` | `GET /realtime/nodes` | 查询指定时间范围内的实时/模拟节点数据 | +| `tjwater data timeseries realtime simulation-by-id-time --id ID --type pipe\|junction --time TIME` | `GET /realtime/query/by-id-time` | 查询指定元素在指定时间点的模拟结果 | +| `tjwater data timeseries realtime simulation-by-time-property --type pipe\|junction --time TIME --property PROPERTY` | `GET /realtime/query/by-time-property` | 查询指定时间点某类元素某属性的聚合模拟结果 | +| `tjwater data timeseries scheme links --scheme SCHEME --start-time TIME --end-time TIME` | `GET /scheme/links`、`GET /scheme/links/{link_id}/field` | 方案管道数据 | +| `tjwater data timeseries scheme node-field --node NODE --field FIELD` | `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` | `GET /scheme/query/*` | 方案模拟查询 | +| `tjwater 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 data timeseries composite --kind scada-simulation\|element-simulation\|element-scada --feature FEATURE --start-time TIME --end-time TIME` | `GET /composite/*` | 复合查询，`--feature` 可重复 | +| `tjwater data timeseries composite pipeline-health --pipe PIPE --start-time TIME --end-time TIME` | `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/` | 爆管定位结果 | +| `tjwater data scheme schema\|get\|list` | `schemes.py` 下 `GET` 接口 | 当前 project 方案查询 | +| `tjwater data extension keys\|get\|list` | `extension.py` 下 `GET` 查询接口 | 当前 project 扩展数据查询 | +| `tjwater data misc sensor-placements` | `GET /getallsensorplacements/` | 当前 project 传感器位置 | +| `tjwater 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** 条件进行检索。若返回结果直接包含时间戳，必须显式带时区，避免把存储时间和展示时间混淆。 暂不暴露： @@ -358,28 +428,49 @@ POST /users/{user_id}/activate POST /users/{user_id}/deactivate ``` -## Help / Result +## Help -这两个模块不直接对应现有 endpoint，但建议作为 Agent CLI 的基础设施。能力发现更适合复用 CLI 的 `help` 语义，而不是新增一个偏内部化的 `capability` 顶层命令。 +`help` 不直接对应现有 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` | 导出结果 | + +输出补充约束： + +- 首批 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` | 服务端错误 | + 成功： ```json { "ok": true, + "schema_version": "tjwater-cli/v1", "summary": "读取成功", "data": {}, - "result_ref": null, "metadata": {}, "next_commands": [] } @@ -390,26 +481,26 @@ POST /users/{user_id}/deactivate ```json { "ok": false, - "error": "invalid_argument", - "message": "缺少必要参数 --network", - "recoverable": true, - "suggested_command": "tjwater component curve list --network NET" + "schema_version": "tjwater-cli/v1", + "summary": "认证失败", + "error": { + "code": "UNAUTHENTICATED", + "message": "missing access token for agent context", + "retryable": false + }, + "data": null, + "metadata": {}, + "next_commands": [ + "tjwater --auth-context /path/to/auth-context.json" + ] } ``` -大结果： +补充约束： -```json -{ - "ok": true, - "summary": "查询完成，结果已写入 result-ref", - "result_ref": "TJWaterAgent/data/result-refs/example.json", - "metadata": { - "schema": "network_properties_v1", - "rows": 1200 - } -} -``` +- `metadata` 至少建议包含：`request_id`、`server`、`duration_ms`、`generated_at`。 +- `next_commands` 是面向 agent 的推荐后续动作，不影响退出码和主结果语义。 +- 所有 `help --json` 输出也应带 `schema_version`，便于 agent 做能力协商。 ## 后续开放条件