@solgridai/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solgrid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# Solgrid CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`solgrid` 是 Solgrid 的命令行客户端，供 Agent 和开发者在终端里发现、查看和执行 Solgrid 工具，并管理 run、余额和本地 API Key。
+
+> **状态：预览版（0.x）。** 命令和输出格式在 1.0 之前仍可能调整。
+
+## 安装
+
+需要 Node.js 22 或更高版本。
+
+```bash
+npm install -g @solgridai/cli
+solgrid --version
+```
+
+## 快速开始
+
+```bash
+# 1. 在 https://solgrid.ai/account/api-keys 创建 API Key，然后保存到本机
+solgrid keys add -k tl_xxxxxxxx -l main --activate --force   # 已有同名 key 时替换，并设为当前使用的 key
+solgrid whoami
+
+# 2. 找到合适的工具，查看输入和价格
+solgrid discover -q "twitter user profile"
+solgrid inspect -p <provider> -e <endpoint>
+
+# 3. 执行并等待结果
+solgrid run -p <provider> -e <endpoint> -i '{"screen_name":"nasa"}' --wait
+```
+
+## 命令
+
+| 命令 | 说明 |
+|---|---|
+| `discover -q <text> [-l n] [--include-unavailable]` | 用自然语言检索工具 |
+| `inspect -p <provider> -e <endpoint>` | 查看工具说明、价格、健康状态和输入 Schema |
+| `run -p <provider> -e <endpoint> [-i json \| -f file] [--query json] [--path json] [-w [s]] [-o file] [--idempotency-key key]` | 执行工具；`--wait` 等待完成，`-o` 把结果保存到文件 |
+| `runs list [-l n] [--cursor c]` | 列出最近的 run |
+| `runs get (-r id \| --idempotency-key key) [-w [s]]` | 查看 run 的状态、费用和结果，可等待其完成 |
+| `runs stop -r <id>` | 停止进行中的 run（Solgrid 暂不支持停止，目前会返回 `CONFLICT`） |
+| `balance` | 查询钱包可用余额 |
+| `whoami` | 查看当前 API Key 对应的账号 |
+| `keys add / list / activate / remove` | 管理本机保存的 API Key |
+| `files upload <path> [--type kind]` | 上传本地文件，返回 24 小时有效的签名 URL，可直接填进工具输入 |
+| `files get -i <fileId>` | 查看文件的类型、大小和状态 |
+| `files url -i <fileId>` | 为已上传的文件重新签发 24 小时有效的 URL |
+| `files download -i <fileId> [-o path] [--force]` | 通过签名 URL 下载文件到本地 |
+| `generate_session_id` | 生成 12 位随机 ID，可作为任务步骤的幂等键 |
+
+每个命令都可以用 `--help` 查看完整参数。
+
+上传的文件默认私有，工具通过签名 URL 读取，URL 24 小时后过期，文件本身保留，过期后用 `files url` 重新签发即可。大小上限：图片、音频 20 MiB，视频 200 MiB，Skill ZIP 10 MB。
+
+生成类工具（视频、图片等）的结果里给出的媒体链接是临时链接，大约 24 小时后失效，需要保留的请及时下载。
+
+## 给 Agent 使用
+
+[`skills/solgrid-cli/SKILL.md`](skills/solgrid-cli/SKILL.md) 是给 Agent 的使用说明：什么时候用、标准流程、安全重试和费用注意事项。把 `skills/solgrid-cli/` 目录放进 Agent 的 skill 目录即可。npm 包里也带了这个目录，全局安装后位于 `$(npm root -g)/@solgridai/cli/skills/solgrid-cli/`。
+
+脚本和 Agent 调用时请加 `--json`：
+
+- 成功：退出码 `0`，结果以 JSON 输出到 stdout。
+- 失败：退出码 `1`，stdout 输出 `{ "error": { "code", "message", "hint", … } }`。与 run 相关的失败还会在顶层带上 `idempotencyKey`，run 已创建时也带上 `runId`，用于安全重试或继续查询。
+
+### 安全重试
+
+`run` 每次提交都带一个幂等键（默认自动生成）。请求失败、但 Solgrid 可能已经受理时，CLI 会先按这个键找回已有的 run，确认没有受理才用同一个键重新提交，因此不会重复执行，也不会重复扣费。如果命令最终仍然失败，用错误输出里的 `idempotencyKey` 重跑即可：
+
+```bash
+solgrid run -p <provider> -e <endpoint> -i '<同样的输入>' --idempotency-key <key>
+```
+
+## 配置
+
+| 项 | 说明 |
+|---|---|
+| `~/.config/solgrid/cli/credentials.json` | 保存的 API Key，文件权限 600；目录遵循 `$XDG_CONFIG_HOME` |
+| `~/.config/solgrid/cli/config.json` | 当前激活的 key |
+| `SOLGRID_API_KEY` | 设置后优先于本机保存的 key，适合 CI 和 Agent |
+| `SOLGRID_API_BASE_URL` | 覆盖 API 地址，默认为 `https://api.solgrid.ai` |
+| `NO_COLOR` / `FORCE_COLOR` | 关闭或强制彩色输出 |
+
+## 开发
+
+开发、测试和构建使用 [Bun](https://bun.sh) 1.4；构建产物运行在 Node.js 22+ 上。
+
+```bash
+bun install
+bun run dev -- --help        # 直接运行源码
+bun run check                # lint + 类型检查 + 测试
+bun run build                # 打包为 dist/index.js
+SOLGRID_E2E_BIN=dist bun test test/e2e   # 用 Node 运行打包产物做端到端测试
+```
+
+```
+src/
+├── index.ts        # 入口
+├── program.ts      # 注册命令、处理参数错误
+├── context.ts      # 注入的运行环境（env、fetch、输出流、时钟）
+├── commands/       # 每个命令一个文件，只负责参数解析和输出
+├── core/           # 业务逻辑：API 客户端、配置、提交与恢复流程
+└── output/         # 输出模式、表格、价格与金额渲染、错误提示
+test/
+├── e2e/            # 启动真实 CLI 进程的端到端测试
+└── support/        # mock server、测试上下文、示例数据
+skills/solgrid-cli/SKILL.md
+```
+
+单元测试和源码放在一起（`*.test.ts`）。所有 API 调用都按 Solgrid 的接口约定：`POST` JSON、`ResponseData` 包装、错误以 body 中的 `code` 为准。