@pracmo/pracmo-cli 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +87 -0
- package/package.json +8 -8
package/README.md
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# pracmocli — 练成（Pracmo）App 的 AI 练习助手命令行
|
|
2
|
+
|
|
3
|
+
`pracmocli` 是[练成 App](https://www.pracmo.com) 提供的命令行工具：把对话、资料或目标整理成**私人练习题**，加入你已有的甲程与练习册；也可以创建练习册，以及制作、校验并上传事实可靠的图片。
|
|
4
|
+
|
|
5
|
+
它面向**任何 AI Agent / 编程工具 / 脚本**直接调用：所有命令输出 JSON、给出明确退出码，不依赖任何特定 Agent 平台。`auth login / status / logout` 是标准的“登录/状态/登出”三钩子，方便各种平台做连接管理。
|
|
6
|
+
|
|
7
|
+
> 获取 API Key：<https://www.pracmo.com/app/api-key>
|
|
8
|
+
|
|
9
|
+
## 安装
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g @pracmo/pracmo-cli
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
也可以不全局安装，在项目里本地安装后使用 `npx pracmocli`。
|
|
16
|
+
|
|
17
|
+
### 包结构（主包是干什么的）
|
|
18
|
+
|
|
19
|
+
- **主包 `@pracmo/pracmo-cli`**：入口包。它本身只有几十 KB（一个 Node 启动器 + 元信息），安装时通过 `optionalDependencies` 自动挑选并安装与你当前系统匹配的**平台包**：
|
|
20
|
+
- `@pracmo/pracmo-cli-darwin-x64/arm64`（macOS Intel/Apple Silicon）
|
|
21
|
+
- `@pracmo/pracmo-cli-linux-x64/arm64`（Linux）
|
|
22
|
+
- `@pracmo/pracmo-cli-win32-x64`（Windows）
|
|
23
|
+
- **平台包**：各自包含对应系统的**静态编译二进制**（Go 编写、无运行时依赖），是真正干活的程序。
|
|
24
|
+
- 所以无论你在哪个平台，一条 `npm install -g @pracmo/pracmo-cli` 即可，剩下的交给 npm 自动匹配；直接安装二进制时，产物名形如 `pracmocli-darwin-amd64`。
|
|
25
|
+
|
|
26
|
+
## 快速开始
|
|
27
|
+
|
|
28
|
+
1. 生成 API Key：<https://www.pracmo.com/app/api-key>。
|
|
29
|
+
2. 绑定授权（任选其一）：
|
|
30
|
+
- **网页绑定**：运行 `pracmocli auth login`，打开输出的链接并确认绑定码即可；
|
|
31
|
+
- **直接使用 Key**：`export PRACMO_API_KEY=sk-...`（旧变量名 `PRACMO_APIKEY` 兼容）。
|
|
32
|
+
3. 查看登录状态：`pracmocli auth status`。
|
|
33
|
+
4. 使用：
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pracmocli tracks list "线性代数" # 列出存量甲程
|
|
37
|
+
pracmocli collections list <trackId> # 列出练习册
|
|
38
|
+
pracmocli collections create <trackId> collection.json # 新建练习册
|
|
39
|
+
pracmocli exercises add <trackId> exercise.json # 创建成品练习
|
|
40
|
+
pracmocli exercises image-replace <trackId> <exerciseId> <questionId> replace.json
|
|
41
|
+
pracmocli images compress/validate/finalize # 图片流水线
|
|
42
|
+
pracmocli doctor # 环境自检
|
|
43
|
+
pracmocli version # 版本
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### 练习 JSON 格式（要点）
|
|
47
|
+
|
|
48
|
+
- `schemaVersion: "pracmo-track-exercise@v1"` + 稳定 `clientRequestId`（8–64 位，仅字母数字点下划线短横线）+ `exercise{title, collectionId, userRequest, difficultyLevel, questions}`。
|
|
49
|
+
- 10–100 道题；支持单选/多选/判断/简答；解析写在 `options[].explanation`，题目对象不含解析字段。
|
|
50
|
+
- 最终请求只含 HTTPS 图片地址；`trackId`/`collectionId` 必须来自 API 响应，不得臆造。
|
|
51
|
+
- 图片流水线：`asset://` 占位 → `images compress` → 逐像素审阅（manifest 的 `review` 全 true）→ `images validate --stage reviewed` → `images finalize`（OSS 直传、哈希回读）→ `images validate --stage finalized`。
|
|
52
|
+
|
|
53
|
+
## 环境变量
|
|
54
|
+
|
|
55
|
+
| 变量 | 默认 | 说明 |
|
|
56
|
+
|------|------|------|
|
|
57
|
+
| `PRACMO_OPEN_API_BASE` | `https://apis.pracmo.com/open/v1` | 后端 Open API 地址（支持自建/预发环境） |
|
|
58
|
+
| `PRACMO_ENV` | `prod` | 预设档：`prod` / `local`（`pre`/`global` 需显式设置 BASE） |
|
|
59
|
+
| `PRACMO_API_KEY` 或 `PRACMO_APIKEY` | 空 | API Key（直接提供时无需网页绑定） |
|
|
60
|
+
| `PRACMO_CREDENTIALS_DIR` | `~/.pracmo` | 绑定凭证目录（0600，跨重启有效） |
|
|
61
|
+
| `PRACMO_HTTP_TIMEOUT_SECONDS` | 30 | HTTP 超时 |
|
|
62
|
+
| `PRACMO_OSS_ENDPOINT` / `PRACMO_OSS_BUCKET` | 取自服务端 | 仅联调覆盖（如本地 minio） |
|
|
63
|
+
|
|
64
|
+
## 退出码
|
|
65
|
+
|
|
66
|
+
| 码 | 含义 | 处理 |
|
|
67
|
+
|----|------|------|
|
|
68
|
+
| 0 | 成功 | 解析 JSON |
|
|
69
|
+
| 1 | 参数/用法错误 | 查看 `pracmocli help` |
|
|
70
|
+
| 2 | 未登录/凭证失效 | `pracmocli auth login` |
|
|
71
|
+
| 3 | 业务错误（后端 4xx 非冲突） | 按错误信息处理 |
|
|
72
|
+
| 4 | 网络/超时 | 相同 `clientRequestId` 与 JSON 重试 |
|
|
73
|
+
| 5 | 冲突（409） | 内容未改则核对已有结果；已改则换新 ID |
|
|
74
|
+
| 6 | 本地门禁未过（校验失败） | 修正后重新校验，不得创建 |
|
|
75
|
+
|
|
76
|
+
## 验证安装
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pracmocli --version
|
|
80
|
+
pracmocli doctor # 输出 baseUrl / 登录方式等
|
|
81
|
+
pracmocli auth status # 未登录时退出码为 2，属正常
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## 安全说明
|
|
85
|
+
|
|
86
|
+
- 不要把 API Key 粘贴到聊天或提交进仓库；流水线也不会把图片字节发给后端（OSS 直传）。
|
|
87
|
+
- 开发与发布：见 [RELEASE.md](./RELEASE.md)（`make release` 构建，`make publish` 一键发布到 npm）。
|
package/package.json
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pracmo/pracmo-cli",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Pracmo
|
|
3
|
+
"version": "0.1.3",
|
|
4
|
+
"description": "练成（Pracmo）App 的 AI 练习助手命令行：把对话、资料或目标整理成私人练习题，加入已有甲程与练习册。任何 AI Agent 都可直接调用；不绑定任何特定 Agent 平台。",
|
|
5
5
|
"bin": { "pracmocli": "bin/pracmocli.js" },
|
|
6
6
|
"optionalDependencies": {
|
|
7
|
-
"@pracmo/pracmo-cli-darwin-
|
|
8
|
-
"@pracmo/pracmo-cli-darwin-
|
|
9
|
-
"@pracmo/pracmo-cli-linux-x64": "0.1.
|
|
10
|
-
"@pracmo/pracmo-cli-linux-arm64": "0.1.
|
|
11
|
-
"@pracmo/pracmo-cli-win32-x64": "0.1.
|
|
7
|
+
"@pracmo/pracmo-cli-darwin-amd64": "0.1.3",
|
|
8
|
+
"@pracmo/pracmo-cli-darwin-arm64": "0.1.3",
|
|
9
|
+
"@pracmo/pracmo-cli-linux-x64": "0.1.3",
|
|
10
|
+
"@pracmo/pracmo-cli-linux-arm64": "0.1.3",
|
|
11
|
+
"@pracmo/pracmo-cli-win32-x64": "0.1.3"
|
|
12
12
|
},
|
|
13
|
-
"files": ["bin"],
|
|
13
|
+
"files": ["bin", "README.md"],
|
|
14
14
|
"publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
|
|
15
15
|
"license": "UNLICENSED"
|
|
16
16
|
}
|