hhzz-cli

面向 AI Agent、开发者和工厂现场的黑湖智造命令行工具。它把黑湖业务能力变成稳定的 CLI 命令，并通过 Agent Skills 将多个命令编排成可直接使用的业务流程。

为什么使用 hhzz-cli

• Agent 友好：稳定 JSON 输出，便于 AI 读取、判断和继续执行。
• 业务对象清晰：命令统一采用 hhzz-cli <业务对象> <操作> [子操作] [参数]。
• 写操作可控：先 --dry-run 预演，再由用户确认后使用 --confirm 执行。
• CLI 与 Skills 同版本：安装、更新和业务规则随同一发布版本交付。

选择安装方式

安装方式取决于 AI Agent 是否能操作用户的本地电脑。

本地 Agent：一句话安装

适用于 WorkBuddy、钉钉悟空、Codex 等能够读取文件并执行本机命令的 Agent。

把下面这句话发送给 Agent：

请按照这个安装指南，在我的电脑上安装并配置 hhzz-cli：
https://bl-v3-cli.oss-cn-shanghai.aliyuncs.com/hhzz-cli/hhzz-cli-installation-guide.md

该公网指南是本地安装、配置和验证的公开操作文档，不包含企业凭证。

纯云端 Agent：上传专用包

适用于飞书 Aily 等不能操作用户本地电脑的 Agent。

1. 登录黑湖智造，进入企业自建应用。
2. 点击“下载 Aily Skill”，获取该自建应用生成的专用 .zip。
3. 将 .zip 上传到飞书 Aily。
4. 直接向 Aily 描述业务目标。

专用包包含 Aily 入口、对应平台的 CLI、官方 Skills 和该自建应用的授权配置。它只能由授权用户从黑湖自建应用下载，不得上传到公开仓库、公开网盘或转发给其他企业。

查看实时命令和参数：

hhzz-cli --help
hhzz-cli material --help
hhzz-cli material list --help
hhzz-cli schema material import

第一期公开范围

1.5.1 提供 169 条业务命令：136 条查询命令和 33 条受控写命令，业务范围与 1.5.0 相同。操作级 --help 提供中英文说明、官方接口名称、参数约束、示例及随当前环境变化的系统页面入口；复杂写请求仍通过 schema 获取完整字段。写入范围保持不变，包括：

• 主数据与生产定义：物料、物料分类、批次、单位、仓库、仓位、供应商、客户、工序、工作中心、工艺路线和 BOM 的建档或维护。
• 计划类单据：入库单、调拨单、出库单、盘点单和生产工单的创建或编辑。
• 状态操作：BOM 启用/停用，以及生产工单下发并生成生产任务。

入库、出库和调拨单创建时 issueFlag 固定为 false。入库单若租户已启用自动下发配置，生产服务仍可能自动下发，执行前必须提示并在写后回查状态。第一期不公开单位启停、仓库/仓位锁定解锁、入库/出库撤回，以及供应商启用、入库/出库/调拨单下发；也不开放物料属性导入、直接库存变更、实际出库、盘点下发/过账和生产任务编辑。生产工单下发会生成生产任务，执行前必须审计并由用户确认，但不表示已经领料、投料、报工或完工。安装 CLI 不会自动授予接口权限，实际可访问范围仍由企业自建应用逐接口授权决定。

业务结果 Skills

用户不需要记住每条 API 或 CLI 参数，只需向已安装 Skills 的 Agent 描述业务目标。

| Skill | 一句话目标 | 流程终点 | |---|---|---| | hhzz-production-launch | 把这个新品投产并生成生产任务 | 生产任务已生成且待执行 | | hhzz-work-order-readiness | 判断这张工单能否开工，还缺哪些物料 | 可开工、存在风险或不可开工 | | hhzz-inventory-trace | 解释物料、批次或二维码的库存为何变化 | 库存事件时间线和可核验来源 |

例如，可以直接对 Agent 说：

帮我把成品 FG-001 投产，检查 BOM 和工艺路线，下发 100 件生产工单并确认生产任务已生成。

查询当前内置规则：

hhzz-cli skills read hhzz-production-launch
hhzz-cli skills read hhzz-work-order-readiness

业务流程、命令选择、完成条件和失败停止规则以当前安装版本的 Skill 为准，README 不维护平行的流程说明或命令清单。

命令格式

所有业务命令遵循：

hhzz-cli <业务对象> <操作> [子操作] [参数]

# 查询物料
hhzz-cli material list --quick-search MAT-001

# 查询工单投入物料
hhzz-cli work-order detail input-material --code WO-001

# 查询盘点任务
hhzz-cli inventory-counting list task --id 123

# 写操作先预演，再确认执行
hhzz-cli schema material import
hhzz-cli material import --body-json '<请求 JSON>' --dry-run
hhzz-cli material import --body-json '<请求 JSON>' --confirm

查询参数以当前安装版本的 --help 为准；写请求字段、枚举、最小示例和回读命令以 hhzz-cli schema <业务对象> <操作> [子操作] 为准。README 不重复维护完整参数表和命令树。

安全边界

• 不要在聊天、命令参数、日志或截图中发送 app_secret。
• 本地凭证只在用户本机的可见终端中配置；Aily 使用自建应用生成的专用包。
• 写操作必须先预演、确认，再查询回读结果。
• “单据已下发”不等于库存已经入账或实物已经移动。
• “生产任务已生成”不等于已经领料、报工或完工。
• CLI 与 Skills 必须使用同一发布版本，避免命令和业务规则不一致。

文档

| 内容 | 入口 | |---|---| | 安装、配置、验证和补全 | 通用 Agent 安装指南 | | 开发、测试、发布和 Cloud Agent/Aily 单 Skill（cloud-agent-skills/hhzz-skills）制作 | 开发指南 | | 当前业务流程和判断规则 | hhzz-cli skills read <skill-name> | | 当前版本的查询参数 | hhzz-cli <业务对象> <操作> --help | | 当前版本的写请求合同 | hhzz-cli schema <业务对象> <操作> [子操作] |