Hinto CLI 技能
此技能涵盖所有 Hinto 终端工作流：安装、身份验证、每个命令组、异步任务处理以及命令链。
安装
此技能驱动 hinto CLI。
包名： 命令是
hinto，但 npm 包是@hintoai/cli。 请不要猜测为@hinto/cli或hinto——那些不存在，会返回 404。 始终安装、升级和引用包为@hintoai/cli。
在运行任何命令之前，请确保 CLI 已安装——如果 hinto 不在 PATH 中，则先安装：
# 全局安装 CLI
npm install -g @hintoai/cli
# 验证
hinto --version
升级到最新版本，运行：
npm install -g @hintoai/cli@latest
然后进行身份验证（见下文）。如果 hinto 命令失败显示"command not found"，请重新运行上述安装步骤。
安装此技能本身（对于任何代理）使用通用的技能 CLI：
npx skills add hintoai/hinto-cli
身份验证
如何获取 API 密钥
API 密钥是按项目（非账户级别）的——每个密钥限定于单个项目，CLI 作用于密钥所属的项目。创建密钥：
- 在 Hinto 应用中打开项目（
https://app.hintoai.com）。 - 点击 设置（顶部栏）打开项目设置。
- 进入 API 密钥和 Webhooks → API 密钥 选项卡。
- 点击 新建 API 密钥 并复制生成的密钥。
配置密钥
优先使用环境变量——它在 CI 中有效并覆盖配置文件：
export HINTO_API_KEY=hinto_...
对于交互式/本地使用，运行一次 init：
hinto init --key hinto_...
# 写入 ~/.hinto/config.json — 权限 600
要针对测试环境或自托管实例，使用 --api-url：
hinto init --key hinto_... --api-url https://staging.hintoai.com
# 或每条命令：
hinto articles list --api-url https://staging.hintoai.com
全局标志
这些标志适用于每条命令：
| 标志 | 用途 |
|---|---|
--json | 输出原始 JSON 到标准输出——在链式命令或解析输出时使用 |
--api-url <url> | 覆盖基础 URL（测试环境、自托管） |
工作风格
当此技能激活时：
- 通过 Bash 运行命令——直接执行
hinto命令，不要只描述它们。 - 在链式命令中使用
--json——管道或解析 JSON 输出以输入下一条命令。 - 对异步任务使用
--wait——仅generate start和generate structure支持。不带--wait时，这些命令立即返回jobId。publish now、publish republish和project retranslate始终是异步的（无--wait）——手动轮询：hinto generate status <jobId>。 - 先检查身份验证——如果命令返回
UNAUTHORIZED，请确认已设置HINTO_API_KEY或已运行hinto init。 - 旋转指示器输出到标准错误输出——即使使用
--wait，标准输出也保持干净以便管道传输。
交互模式：
- 询问 vs. 自动——仅在用户有实际选择（2 个或更多选项）时提示。如果有 0–1 个选项，直接进行并说明你使用了什么。
- 确认破坏性操作——在执行
articles delete和publish unpublish之前，请与用户确认，明确说明将要删除或下线的内容。决不要推测性地运行它们。 - 输出纪律——每项任务结束时提供：运行的命令 + 结果、未等待的异步操作的
jobId、可用时的链接（editUrl/previewUrl）以及下一步验证步骤。
入门——从这里开始
首先运行以下命令以了解密钥所针对的项目（密钥是按项目的——你只作用于一个项目）：
hinto project get --json # 名称、类型、是否已发布、自定义域名
hinto project structure --json # 文件夹 + 文章树
hinto publish status --json # 是否在线，以及 URL
如果结果与用户的期望不符，则密钥可能针对的项目不同——用户必须提供正确的密钥；你无法切换项目。
作用域
每个 API 密钥携带作用域。当缺少作用域时，操作失败并返回 INSUFFICIENT_SCOPE（403）：
| 作用域 | 允许 |
|---|---|
read | 获取 / 列出 / 状态 / 结构 / 语言 / 版本 / 翻译 |
write | 创建 / 更新 / 删除 / 移动 / 复制 / 还原 / 添加语言 |
generate | 生成开始 / 结构、重新生成、重新翻译、触发翻译 |
publish | 立即发布 / 重新发布 / 取消发布 |
恢复：告知用户缺少哪个作用域——必须通过应用 UI 创建具有该作用域的新密钥。
ID 和状态注意事项
- 文章和文件夹 ID 是整数；任务 ID 是UUID。
slug和previewUrl在发布之前为 null（以及对于不在当前发布快照中的文章）。- 视频必须处于
ready状态后才能运行generate start/generate structure。 generate structure生成的是空占位文章，而非完整文章——请参见references/product-behavior.md。- 速率限制：每个密钥每分钟 60 次请求（
RATE_LIMITED429 → 等待Retry-After）。生成操作可能返回QUOTA_EXCEEDED。
CLI 无法执行的操作（仅限应用 UI）
请不要为以下操作发明命令——它们位于 Hinto Web 应用中：
- 创建项目或 API 密钥
- 工作区 / 计费管理
- 品牌和发布设置编辑（未通过已记录的命令提供）
核心工作流：上传 → 生成 → 发布
# 1. 上传本地视频文件
hinto videos upload --file ./video.mp4 --json
# → { "videoId": "..." }
# 或者从 URL 导入（返回一个 Job 对象——轮询直到完成以获取 videoId）
hinto videos import --url https://example.com/video.mp4 --json
# → { "jobId": "...", "type": "import_video_url", "status": "pending", "output": null, ... }
# 然后轮询：hinto generate status <jobId> —— 完成后的输出包含 videoId
# 2. 等待视频准备就绪
hinto videos status <videoId> --json
# → { "videoId": "...", "status": "ready", ... }
# 3. 列出可用模板
hinto templates article --json
# 4. 生成文章并等待完成
hinto generate start --video <videoId> --template <templateId> --wait --json
# 4b. 将新文章的链接交给用户（editUrl 始终存在；previewUrl 仅在已发布时）
hinto articles get <articleId> --json # → 包含 editUrl + previewUrl
# 5. 发布项目（异步——立即返回 jobId）
hinto publish now --json
# → { "jobId": "...", "type": "publish", "status": "pending", ... }
# 轮询：hinto generate status <jobId>
分类路由
阅读相关命令组的参考文件：
| 任务 | 参考文件 |
|---|---|
| 上传、导入、管理视频 | references/videos.md |
| 创建、编辑、移动、翻译文章 | references/articles.md |
| 创建和组织文件夹 | references/folders.md |
| 从视频生成文章或结构 | references/generate.md |
| 项目信息、结构树、语言 | references/project.md |
| 发布、重新发布、取消发布 | references/publish.md |
| 浏览可用模板 | references/templates.md |
| 导出文章、文件夹或整个项目 | references/export.md |
| 将视频转换为内容（单篇文章 vs. 结构） | references/content-from-video.md |
| 常见任务配方（上传→生成→发布、编辑→重新发布、添加图片） | references/recipes.md |
| 产品行为（版本/还原、占位/自动生成、图片、翻译） | references/product-behavior.md |
输出检查清单
留给用户的信息：
- 运行的命令及其输出
- 如果操作是异步且未使用
--wait，则提供jobId - 下一步验证步骤（例如
hinto videos status <id>、hinto generate status <jobId>） - 任何影响结果的作用域或身份验证说明