hhzz-shared

hhzz-cli 共享规则

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

何时使用

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

不在本 Skill 范围

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

目标与完成边界

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

启动检查

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 判断，不默认展示；用户明确要求排查技术问题时，才提供必要的脱敏技术信息。