@qoder-ai/qmind-cli 1.1.0 → 1.1.1
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/CHANGELOG.md +6 -0
- package/README.md +77 -47
- package/dist/qmind.js +2 -2
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# `@qoder-ai/qmind-cli`
|
|
2
2
|
|
|
3
|
-
QMind
|
|
3
|
+
QMind 命令行工具，可用于登录、管理知识库和来源、检索内容、运行 RAG/编译任务，以及把本地目录同步到知识库。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
本包只提供 `qmind` 可执行命令，不提供 JavaScript/TypeScript 模块导出。不要从 `@qoder-ai/qmind-cli` import `createQMindCliHost`、`runQMindCli` 或其他 API；需要在应用中集成 QMind 时，请使用 `@ali/qmind-sdk`。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## 安装
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
需要 Node.js `>=20.18.1`：
|
|
10
10
|
|
|
11
11
|
```sh
|
|
12
12
|
npm install --global @qoder-ai/qmind-cli
|
|
@@ -14,69 +14,99 @@ qmind version
|
|
|
14
14
|
qmind --help
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
升级和卸载也交给 npm：
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
```sh
|
|
20
|
+
npm update --global @qoder-ai/qmind-cli
|
|
21
|
+
npm uninstall --global @qoder-ai/qmind-cli
|
|
22
|
+
```
|
|
20
23
|
|
|
21
|
-
|
|
22
|
-
import { createQMindCliHost } from '@qoder-ai/qmind-cli';
|
|
24
|
+
`qmind self-update` 仅用于提示 npm 升级方式，不会修改 npm 管理的文件。
|
|
23
25
|
|
|
24
|
-
|
|
25
|
-
flags: { token: process.env.QMIND_TOKEN },
|
|
26
|
-
});
|
|
26
|
+
## 快速开始
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
|
|
28
|
+
交互式登录会打开浏览器完成授权，并把凭证安全保存到本机：
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
qmind login
|
|
32
|
+
qmind notebook list
|
|
33
|
+
qmind source list --nb <notebook-id>
|
|
34
|
+
qmind retrieve --nb <notebook-id> "部署流程是什么？"
|
|
30
35
|
```
|
|
31
36
|
|
|
32
|
-
|
|
37
|
+
CI 或 Agent 场景建议使用环境变量和结构化输出：
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
export QMIND_TOKEN='<token>'
|
|
41
|
+
qmind notebook list --non-interactive --format json
|
|
42
|
+
qmind retrieve --nb <notebook-id> --format agent "发布前要检查什么？"
|
|
43
|
+
```
|
|
33
44
|
|
|
34
|
-
|
|
35
|
-
import { runQMindCli } from '@qoder-ai/qmind-cli';
|
|
45
|
+
不要把 token 写进脚本参数、仓库或日志。使用完本机凭证后可执行：
|
|
36
46
|
|
|
37
|
-
|
|
47
|
+
```sh
|
|
48
|
+
qmind logout
|
|
38
49
|
```
|
|
39
50
|
|
|
40
|
-
|
|
51
|
+
## 命令
|
|
52
|
+
|
|
53
|
+
| 命令 | 用途 |
|
|
54
|
+
| --------------------------- | -------------------------------------- |
|
|
55
|
+
| `login` / `logout` | 登录或清除本机凭证 |
|
|
56
|
+
| `notebook` | 创建、列出、查看、删除知识库 |
|
|
57
|
+
| `cards` / `list` / `search` | 列出或搜索卡片 |
|
|
58
|
+
| `source` | 创建、上传、下载、移动、读取或删除来源 |
|
|
59
|
+
| `retrieve` | 检索知识库上下文，不发起 LLM 调用 |
|
|
60
|
+
| `rag` | 基于知识库提问 |
|
|
61
|
+
| `compile` / `lint` | 启动编译或检查工作流 |
|
|
62
|
+
| `task` | 创建、查询或列出任务运行 |
|
|
63
|
+
| `upload-folder` / `sync` | 将本地目录同步到知识库 |
|
|
64
|
+
| `image` | 获取图片上传地址或访问地址 |
|
|
65
|
+
| `version` | 查看版本和构建信息 |
|
|
41
66
|
|
|
42
|
-
|
|
67
|
+
使用 `qmind <command> --help` 查看完整参数。例如：
|
|
43
68
|
|
|
44
|
-
|
|
69
|
+
```sh
|
|
70
|
+
qmind source upload --help
|
|
71
|
+
qmind upload-folder --help
|
|
72
|
+
```
|
|
45
73
|
|
|
46
|
-
|
|
47
|
-
- stdout 只承载结果，诊断、progress 与 download 信息进入 stderr；
|
|
48
|
-
- 成功/help 为 `0`，运行失败/部分成功/取消为 `1`，usage 与 `INVALID_ARGUMENT` 为 `2`；
|
|
49
|
-
- JSON runtime error 使用稳定 `{ "error": { "code", "message", "status", "errorCode", "requestId", "rawBody", "details" } }` envelope；
|
|
50
|
-
- `source upload` 复用 SDK 的 50/500 MiB strategy；download 默认不覆盖并流式原子落盘；
|
|
51
|
-
- `upload-folder` 支持默认扩展/隐藏文件过滤、`--ignore` glob、`skip|overwrite|if-changed`、`--delete`、`--dry-run`、mapping、1..10 并发与 retryable-only 三次上传。`--delete` 明确把 notebook source root 当作该本地目录的镜像，会删除远端多余项；为避免空计划误删，它不能与 `--skip-upload` 组合，建议先用 `--dry-run` 审阅 stats。
|
|
74
|
+
## 输出与退出码
|
|
52
75
|
|
|
53
|
-
|
|
76
|
+
领域命令支持 `table`、`json`、`agent`、`ndjson` 等输出格式；具体可用值以命令的 `--help` 为准。
|
|
54
77
|
|
|
55
|
-
|
|
78
|
+
- stdout 只输出命令结果，进度与诊断信息输出到 stderr；
|
|
79
|
+
- `0` 表示成功或正常显示帮助；
|
|
80
|
+
- `1` 表示运行失败、部分成功或用户取消；
|
|
81
|
+
- `2` 表示参数用法错误或 `INVALID_ARGUMENT`。
|
|
56
82
|
|
|
57
|
-
|
|
58
|
-
- `login()` / `logout()`：Device Flow + PKCE 与完整凭证清理；
|
|
59
|
-
- `createFileSource()`：可重复打开、流式读取的 `QMindBinarySource`；
|
|
60
|
-
- `downloadToFile()`：credential-free signed URL 的流式、原子、默认 no-clobber 下载；
|
|
61
|
-
- `config`：不含 token、proxy credentials 或 TLS material 的安全 runtime metadata；
|
|
62
|
-
- `close()`：释放 host-owned Undici dispatchers。
|
|
83
|
+
JSON 错误使用稳定的 `error` envelope，包含 `code`、`message`，以及服务端提供时的 `status`、`errorCode`、`requestId` 和 `details`。
|
|
63
84
|
|
|
64
|
-
|
|
85
|
+
## 同步目录
|
|
65
86
|
|
|
66
|
-
|
|
87
|
+
先用 `--dry-run` 审阅计划，再决定是否执行删除：
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
qmind upload-folder \
|
|
91
|
+
--nb <notebook-id> \
|
|
92
|
+
--dir ./docs \
|
|
93
|
+
--mode if-changed \
|
|
94
|
+
--ignore '**/drafts/**' \
|
|
95
|
+
--dry-run
|
|
96
|
+
```
|
|
67
97
|
|
|
68
|
-
|
|
98
|
+
移除 `--dry-run` 后才会写入远端。`--delete` 会把知识库的来源根目录视为本地目录的镜像，并删除远端多余项；使用前请确认 dry-run 结果。并发范围为 `1..10`。
|
|
69
99
|
|
|
70
|
-
|
|
71
|
-
- device token 在过期前 30 秒主动 refresh；
|
|
72
|
-
- host `401` 触发一次 refresh 和严格一次 retry，并发失败共享同一个 refresh；
|
|
73
|
-
- credential schema v1 在 refresh 时先备份，再原子迁移为 schema v2；
|
|
74
|
-
- `credentials.json` 位于 mode `0700` 目录中，自身为 mode `0600` regular file；
|
|
75
|
-
- `@napi-rs/keyring` 是可选、仍维护的 OS-keyring 增强；不可用时确定性回退到私有文件；
|
|
76
|
-
- secrets 不进入 public config、debug URL、error 或 login result。
|
|
100
|
+
## 配置与网络
|
|
77
101
|
|
|
78
|
-
|
|
102
|
+
常用环境变量：
|
|
79
103
|
|
|
80
|
-
|
|
104
|
+
- `QMIND_TOKEN`：非交互 token；
|
|
105
|
+
- `QMIND_ENV`：`prod`、`daily` 或 `test`；
|
|
106
|
+
- `QMIND_SASH_URL` / `QMIND_DASHBOARD_URL`：覆盖服务 origin；
|
|
107
|
+
- `QMIND_HOME`：覆盖配置与凭证目录，默认 `~/.qmind`；
|
|
108
|
+
- `QMIND_NON_INTERACTIVE=1`：禁止打开浏览器；
|
|
109
|
+
- `QMIND_REQUEST_TIMEOUT_MS` / `QMIND_STREAM_IDLE_TIMEOUT_MS`：请求与流空闲超时；
|
|
110
|
+
- `QMIND_TLS_CA_FILE`：私有 CA 文件。
|
|
81
111
|
|
|
82
|
-
|
|
112
|
+
CLI 支持 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。TLS 默认严格校验；上传到签名对象地址时不会携带 QMind 的 Authorization、Cookie、CSRF 或代理凭证。
|
package/dist/qmind.js
CHANGED
|
@@ -2024,7 +2024,7 @@ function requestsJsonOutput(argv) {
|
|
|
2024
2024
|
}
|
|
2025
2025
|
//#endregion
|
|
2026
2026
|
//#region src/build-info.ts
|
|
2027
|
-
const QMIND_CLI_VERSION = "1.1.
|
|
2027
|
+
const QMIND_CLI_VERSION = "1.1.1";
|
|
2028
2028
|
const QMIND_CLI_BUILD_TIME = "development";
|
|
2029
2029
|
const QMIND_CLI_UPDATE_BASE_URL = typeof __QMIND_CLI_UPDATE_BASE_URL__ === "string" ? __QMIND_CLI_UPDATE_BASE_URL__ : "https://qoder-ide-cn.oss-cn-hangzhou.aliyuncs.com/qmind/cli/";
|
|
2030
2030
|
function qmindCliPlatform() {
|
|
@@ -4833,7 +4833,7 @@ function registerUpdateCommand(context, program) {
|
|
|
4833
4833
|
publicKey: String(raw.publicKey ?? "")
|
|
4834
4834
|
});
|
|
4835
4835
|
if (result.updated) context.io.stdout(`[self-update] updated ${QMIND_CLI_VERSION} -> ${result.version}\n`);
|
|
4836
|
-
else if (result.version === "1.1.
|
|
4836
|
+
else if (result.version === "1.1.1".replace(/^v/, "")) context.io.stdout(`[self-update] already current: ${result.version}\n`);
|
|
4837
4837
|
else context.io.stdout(`[self-update] verified available version: ${result.version}\n`);
|
|
4838
4838
|
});
|
|
4839
4839
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@qoder-ai/qmind-cli",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.1",
|
|
4
4
|
"description": "QMind command line interface",
|
|
5
5
|
"bin": {
|
|
6
6
|
"qmind": "bin/cli.js"
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"devDependencies": {
|
|
38
38
|
"@types/picomatch": "4.0.3",
|
|
39
39
|
"@types/proper-lockfile": "4.1.4",
|
|
40
|
-
"@ali/qmind-sdk": "^0.1.
|
|
40
|
+
"@ali/qmind-sdk": "^0.1.1"
|
|
41
41
|
},
|
|
42
42
|
"license": "UNLICENSED",
|
|
43
43
|
"scripts": {
|