hhzz-shared

hhzz-cli 共享规则

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

启动检查

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. 优先读取与用户目标匹配的业务结果 Skill；单对象请求先检查 hhzz-cli skills list，只有存在匹配的对象 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；没有安全替代时停止并说明缺少可执行查询合同。

写入规则

• 所有 create、import、update、issue、execute、post、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。

输出要求

只保留目标、脱敏命令、关键业务编号、必要 ID、状态、数量、结论和阻塞项。不得输出凭证、Token、完整配置或未经脱敏的完整生产响应。

业务结果 Skill 固定按以下六部分输出：

1. 业务结论：已完成、部分完成或未完成，以及对应业务边界。
2. 已完成步骤：按实际执行顺序列出，不包含计划但未执行的动作。
3. 关键数据：必要业务编号、ID、状态和数量。
4. 阻塞或风险：权限、前置数据、状态、库存或返回字段语义问题。
5. 下一步：只给出解除当前阻塞或继续业务流程所需的最短动作。
6. CLI 证据：列出实际运行的脱敏命令及支撑结论的关键返回，不粘贴完整响应。