---
name: hhzz-shared
description: "hhzz-cli 公共执行规则：负责配置、认证、命令发现、权限、写入确认、结果回查、统一业务结果和错误处理。使用任何黑湖智造业务 Skill 前必须先阅读。不替代具体业务 Skill 或 CLI 合同。"
metadata:
  version: "1.3.8"
  requires:
    bins: ["hhzz-cli"]
  cliHelp: "hhzz-cli config --help; hhzz-cli auth status --help; hhzz-cli skills --help"
---

# hhzz-cli 共享规则

所有业务 Skill 执行前都先阅读本文件。当前 CLI 注册树是命令事实来源；查询参数以操作级 `--help` 为准，写请求以 `schema` 返回的机器合同为准。Skill 只补充业务选择、跨对象流程和 CLI 无法表达的约束。

## 何时使用

执行任一黑湖业务 Skill、首次检查 CLI 环境、发现命令、执行安全写入、处理权限错误或统一输出证据时使用。

## 不在本 Skill 范围

- 不替代具体业务动作或业务结果 Skill，不决定某个对象的业务语义。
- 不复制查询 flags、写请求 Schema、API 路由或生产合同。
- 不直接证明任何业务对象已经创建、下发或执行；结论必须来自实际 CLI 返回和回查。

## 目标与完成边界

本 Skill 的完成结果是 Agent 使用当前安装版本的真实命令和合同，在认证前完成本地校验，安全执行经确认的写入，并按统一证据层级陈述结果。

## 启动检查

```bash
hhzz-cli version
hhzz-cli auth status
```

首次配置运行 `hhzz-cli config init`。只重配自建应用凭证时运行 `hhzz-cli config credentials`。非交互场景通过 stdin 传入密钥，禁止把 `app_secret` 放入参数、日志、案例或回复。

受信云 Agent、CI 等平台可以通过平台 Secret 功能预注入 `HHZZ_AUTH_APP_SECRET`。该变量只作为运行时覆盖值，优先于配置中的 keychain 引用或 `builtin-aes-gcm` 密文，不得写入配置文件或 secret store；变量存在但为空或只有空白时必须认证失败，不得回退到配置密钥。

Agent 不得在对话中索取密钥后自行设置环境变量，也不得运行 `env`、`printenv`、`set`、`Get-ChildItem Env:` 或同类命令读取、打印或回传密钥。只使用 `hhzz-cli auth status` 或 `hhzz-cli config show` 判断凭证是否可用。

## 命令发现

1. 先检查 `hhzz-cli skills list`，只读取清单中与用户目标唯一匹配的业务结果 Skill 或业务动作 Skill。没有匹配 Skill 时直接使用当前 CLI 命令树，不得按业务对象拼接或猜测 `hhzz-<业务对象>` Skill 名称。
2. 运行 `hhzz-cli <业务对象> --help` 和操作级 `--help`。
   需要开通接口权限时，使用其中的“权限中心名称”和“搜索词”原文，不自行翻译命令名。存在多条路径时按当前参数对应的使用条件选择，不能用写接口代替读取接口。
3. 只使用当前命令树真实存在的业务对象、操作、子操作和参数。
4. 写操作运行 `hhzz-cli schema <业务对象> <操作> [子操作]`，按 `inputSchema` 和 `example` 构造参数；不得猜测字段、嵌套结构或枚举，也不得使用当前不存在的 `--body-file`。

## 查询规则

- 通用搜索优先使用 `list`；定位到唯一对象后再使用 `detail`。
- 多条近似结果不得默认取第一条，先依据编码、ID 或其他唯一字段确认。
- 查询操作不需要写前审计或执行确认；完成查询后直接用业务语言返回结果。
- 默认 `--page 1 --size 20`，且 `page >= 1`、`size >= 1`、`page * size <= 10000`。
- 查询时间戳、枚举和参数关系以命令 `--help` 为准；写请求以 `schema` 为准。
- 查询 `--help` 未列出枚举全集时，不得根据中文业务词猜测数字 code，也不得逐值试错。优先去掉该枚举筛选，使用编码、名称或 `quick-search` 做更宽查询，再根据返回的 `{code,message}` 和唯一业务对象收敛；该枚举若是必填且无法确定，停止请求并明确说明查询合同缺口。
- `--help` 未声明 JSON 参数结构时，不得猜测 `--*-json` 的字段或嵌套。优先使用可表达同一目标的普通 flag；没有安全替代时停止并说明缺少可执行查询合同。
- 自定义对象筛选必须先确认当前租户的对象、字段类型和选项 ID；本地结构校验不证明字段存在。没有元数据依据时先查询不带动态条件的受限页面，不猜字段或逐值试错。
- 索引延迟、前缀匹配、默认分类回退和分页结果都以 Help 边界为准；空结果不等于未执行、失败或数据不存在。报告摘要、模板定义不代表报告控件值，附件元数据不等于文件已下载。
- 用户需要报告填写内容时，使用 `report list control-values` 并先读取Help；仅用已查到的报告ID或关联业务ID定位。V2存在性能警告，不自动轮询、翻页或因V3失败切换；value保持原始含义，不猜照片链接。

## 写前业务审计

审计的目的不是只询问“是否确认”，而是帮助用户把写操作需要的业务数据补完整，并在执行前看清实际影响。

1. 根据当前命令的 `schema`、具体业务 Skill 和用户目标列出必要业务信息。
2. 能通过只读命令获得的内部 ID、主数据状态、仓库仓位、单位、关联关系和当前单据状态，必须由 Agent 先查询，不要求用户手工查找。
3. 查询到多个候选时，展示业务名称、编码和影响选择的关键区别，请用户选择；不得默认取第一条。
4. 数据缺失、对象不存在或停用、权限不足、状态不允许、数量或关联关系冲突时停止写入，用业务语言说明缺少什么、为什么需要以及如何补齐。不得向普通用户倾倒 Schema、JSON 字段名或原始 API 错误。
5. 必要数据完整后执行 `--dry-run`。预览通过后，向用户展示业务对象、编号、数量、仓库仓位、预计状态和实际业务影响，再询问是否确认。
6. 未完成上述审计或用户尚未明确确认时，禁止执行 `--confirm`。确认后请求发生任何变化，必须重新审计、预览和确认。

业务结果 Skill 应在流程开始时尽量一次汇总跨对象的缺失项，避免每一步反复追问。只有前一步执行结果才会决定后一步输入时，才在进入后一步前追加审计。

## 写入规则

- 所有 `create`、`import`、`update`、`issue`、`back`、`execute`、`post`、`enable`、`start`、`stop`、`lock`、`unlock` 必须先执行 `--dry-run`。
- 写入必须先读取当次安装版本的 `schema`。Skill 不保存完整字段表；`inputSchema`、`example` 和 `_meta.readback` 是本版本的可执行合同。
- `example` 只用于展示请求结构。执行前必须用用户输入或查询结果替换其中的 `示例值`、`DEMO-001`、示例 ID 和示例时间戳，禁止原样写入租户。
- 只有写前业务审计通过且用户明确确认当前业务内容后，才能改用 `--confirm`。
- `--confirm` 必须完整复用本次已通过 `--dry-run` 展示并获确认的参数和请求体，不得重新构造、补充或修改任何字段。只要请求发生变化，无论变化看似是否安全，都必须重新执行 `--dry-run` 并重新确认。
- 不得同时传 `--dry-run` 和 `--confirm`，也不得静默追加 `--confirm`。
- 使用唯一业务编号，避免覆盖现有生产数据；批量操作前列出影响对象。
- 写请求返回异常时先按唯一编号反查，确认没有落库后再考虑重试。
- `schema` 没有返回 `_meta.readback`、而是返回 `_meta.readbackUnavailableReason` 时，说明当前生产 OpenAPI 没有确定性查询入口；保留服务端结果并标记“未完成回查”，不得因此自动重试写操作。

## 结果回查

写操作成功后使用相同业务对象的 `list` 或 `detail` 回查。证据分为四层：

1. 请求被服务端接受。
2. 对象可以按唯一编号查到。
3. 单据进入已下发等计划状态。
4. 库存、发出量、接收量、过账量、投料量或报工量证明现场动作完成。

不得用前三层证据宣称第四层已经完成。入库单、调拨单、出库单或工单“已下发”只代表计划进入执行阶段。

## 常见前置条件

- 物料业务范围包含 `1=仓储` 时，创建或编辑物料必须提供 `inventoryInfo`；不包含仓储时不得传入该对象。
- 精确出库需要指定维度存在足够可用库存。
- 推荐出库还依赖 FIFO 等推荐策略已经启用。
- 盘点过账需要盘点任务已经产生有效盘点结果。
- 工单下发前应确认 BOM、工艺路线、投入物料和工序计划有效。

## 错误处理

- 配置缺失：本地环境运行 `hhzz-cli config init` 或 `hhzz-cli config credentials`；云平台环境只提示维护者检查 Secret 注入，不得由 Agent 读取环境变量。
- 环境域名错误：运行 `hhzz-cli config endpoint ali-prod`、`hhzz-cli config endpoint hw-prod`、`hhzz-cli config endpoint custom`，或使用 `hhzz-cli config set endpoint <url>`。
- 密钥不可用：本地持久配置重新运行 `hhzz-cli config credentials`；平台注入模式提示维护者确认 `HHZZ_AUTH_APP_SECRET` 存在且非空。
- `OPENAPI-DOMAIN/URL_NO_PERMISSION`：保留 CLI 错误中实际调用的 `/域/open/...` 路径，提示用户在当前环境的 `/customAppManagement` 为正在使用的自建应用增加该接口权限；CLI 未返回路径时只报告命令和错误，不自行猜测，不要求用户提供密钥。
- 参数或业务校验错误：保留 code、sub-code 和 message，修正前置数据或请求后最多重试一次。
- 创建响应异常但对象已能反查：记录为“对象已落库，返回合同异常”，禁止重复创建。
- `_notice.skills`：先完成当前请求，再提示用户之后运行 `hhzz-cli update`。

## 输出要求

默认面向工人或业务人员返回结果，只展示他们能够确认和继续处理的业务信息。不得输出凭证、Token、完整配置、Schema、JSON 请求体、API 路径、完整生产响应或内部执行细节。

写操作完成后固定返回以下业务内容：

1. **业务结果**：已完成、部分完成或未完成。
2. **业务对象**：名称、业务编号、数量、仓库仓位和当前状态等必要信息。
3. **未完成内容**：哪些内容没有完成，以及业务原因。
4. **业务边界**：例如“已下发不等于库存已入账”。
5. **下一步**：用户继续业务流程所需的最短动作。

CLI 命令、内部 ID 和原始返回只用于 Agent 判断，不默认展示；用户明确要求排查技术问题时，才提供必要的脱敏技术信息。