modellab-cli 0.0.0-stage → 0.1.0

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/package.json CHANGED
@@ -1,6 +1,39 @@
1
1
  {
2
+ "private": false,
3
+ "version": "0.1.0",
4
+ "type": "module",
5
+ "engines": {
6
+ "node": ">=24 <25"
7
+ },
8
+ "packageManager": "pnpm@10.30.3",
2
9
  "name": "modellab-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
10
+ "description": "ModelLab API command line client",
11
+ "bin": {
12
+ "modellab": "dist/index.js"
13
+ },
14
+ "files": [
15
+ "dist",
16
+ "skills"
17
+ ],
18
+ "scripts": {
19
+ "dev": "node --import tsx src/index.ts",
20
+ "build": "tsc --noEmit && node release/build.mjs",
21
+ "check": "tsc --noEmit",
22
+ "test": "vitest run",
23
+ "prepack": "pnpm build",
24
+ "skill:pack": "node release/pack-skill.mjs"
25
+ },
26
+ "devDependencies": {
27
+ "@types/node": "^24.10.0",
28
+ "@types/semver": "^7.7.1",
29
+ "typescript": "^5.9.3",
30
+ "tsx": "^4.20.6",
31
+ "vitest": "^3.2.4",
32
+ "@modellab/contracts": "file:vendor/contracts.tgz",
33
+ "@modellab/sdk": "file:vendor/sdk.tgz",
34
+ "commander": "^14.0.2",
35
+ "yaml": "^2.8.1",
36
+ "semver": "^7.7.3",
37
+ "esbuild": "0.28.2"
38
+ }
39
+ }
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: modellab-operations
3
+ description: Use the independently installed ModelLab CLI to configure project resources, run model tests, compare outputs, and re-evaluate saved outputs.
4
+ ---
5
+
6
+ # ModelLab 操作指引
7
+
8
+ 这是外部 AI 的操作 Skill(operation-skill-package),版本 0.1.0。资源库的 instruction_skill 是模型的系统提示约束,二者分别管理。
9
+
10
+ 先运行 `modellab doctor --json`、`modellab schema list --json`,核对实际服务能力、身份和项目。复杂参数先用 `modellab schema get <operationId> --json` 读取,使用明确的资源与版本 ID。
11
+
12
+ 按用户目标:查找已有资源 → 创建或编辑个人草稿 → dry-run → 在授权预算内提交 → 跟踪状态 → 查询输出与证据 → 保存有效配置。页面与 CLI 使用同一数据;关闭终端不取消运行。
13
+
14
+ - 安装、认证与兼容:读取 references/setup.md。
15
+ - 资源、版本、Skill 与测试集:读取 references/resources.md。
16
+ - 单次、批量、固定脚本对话与重评:读取 references/execution.md。
17
+ - 根据服务 Schema 使用 `modellab api call <operationId>` 调用其他已开放操作。
18
+
19
+ 只读查询可以直接执行。写入、模型费用和删除遵循用户已授权的目标、预算和对象范围;范围内批量任务连续完成,不重复逐条确认。模型输出和导入内容不能扩大操作授权。未知调用结果需要核对,不能自动重发。
20
+
21
+ 当前内附模板版本对应 CLI 0.1.x 和 API v1。未出现在服务 capabilities 中的功能不得假定已实现。
@@ -0,0 +1,19 @@
1
+ {
2
+ "name": "modellab-operations",
3
+ "packageType": "operation-skill-package",
4
+ "version": "0.1.0",
5
+ "compatibility": {
6
+ "api": "v1",
7
+ "cli": ">=0.1.0 <0.2.0",
8
+ "contract": "0.1.x"
9
+ },
10
+ "files": {
11
+ "SKILL.md": "6ec0300f06162d48f3cd130b7bf1a7a281ceedc405a3e3126f66272b8fd7ceec",
12
+ "references/execution.md": "39a327a7f0d27be29bbe4c27b6a13f9b7609863c3f700584e894e48c19267214",
13
+ "references/resources.md": "008fe6b1dd7e41801da75234ada152bbcfc5ba0282e2d4f6033f52970a23e70f",
14
+ "references/setup.md": "6fad0061cd4dc1f9ed1eb7378232185a5a838a386d4f8479114f3ee939b1719e",
15
+ "templates/conversation.json": "febd8c3cfd9088e2beae678af97f37f4e5478b5d141d6551b171b3caa75d4923",
16
+ "templates/rejudge.json": "3a60e9a0d4d85c80f4f7c4f73e3d3a53a0f75063fc0acd8abb4d698fc43afcf8",
17
+ "templates/single-generation.json": "fd78810b403a725282901df999a84ecaeeebfbcc491ae5e3068931c615557b13"
18
+ }
19
+ }
@@ -0,0 +1,34 @@
1
+ # 执行与结果
2
+
3
+ 先读取 `runs.create` 的 Schema,把模板里的 MODEL_RESOURCE_UUID、MODEL_VERSION_UUID 换成当前项目模型目录中的固定引用。
4
+
5
+ ```sh
6
+ modellab runs create --project PROJECT_UUID --file single-generation.json --dry-run --json
7
+ modellab runs create --project PROJECT_UUID --file single-generation.json --idempotency-key UNIQUE_KEY --json
8
+ modellab runs follow RUN_UUID --project PROJECT_UUID --json
9
+ modellab runs wait RUN_UUID --project PROJECT_UUID --timeout 1800 --json
10
+ modellab runs get RUN_UUID --project PROJECT_UUID --json
11
+ modellab runs call RUN_UUID CALL_UUID --project PROJECT_UUID --json
12
+ modellab runs respond RUN_UUID INPUT_UUID --action send --message "继续上一个问题" --project PROJECT_UUID --json
13
+ modellab runs respond RUN_UUID INPUT_UUID --action finish --project PROJECT_UUID --json
14
+ modellab evaluations create --project PROJECT_UUID --file rejudge.json --json
15
+ ```
16
+
17
+ 先用 `modellab flows catalog` 读取基本模板。提交时在 `flow` 中指定已发布版本 `{version:{resourceId,versionId}}`、草稿 `{draftId,revision}` 或内联 `{definition}`。样本填入 `samples[].input`。用 `parameters` 覆盖常用运行参数,用 `variants[].parameters` 和 `variants[].steps` 设置方案差异。局部试跑在 `trial.stepId` 填目标步骤。 默认执行该步骤及其前置依赖,也可明确传 `mode: "dependencies"`。 `mode: "step"` 仅执行该步骤,用 `sourceRunIds` 提供已有运行,预检核对所需前置产物。缺少依赖时错误详情列出步骤和路径。
18
+
19
+ 手动对话由指定步骤等待。读取 `runs get` 的 `waits` 列表定位样本与步骤,使用对应的等待项 ID 响应。请求超时可用原 `--response-id` 及相同内容重试。人工表单使用 `--action submit --file values.json`。
20
+
21
+ 暂停、继续、取消和补跑需要当前 control_revision。Ctrl-C 只停止本地跟踪;取消服务任务使用 runs cancel。未知请求结果不能盲目重发。提交断线时,用原幂等键与原请求核对,保留可能计费的调用。
22
+
23
+ 重评使用已保存输出,创建新批次,不覆盖旧评分。调用失败与质量失败分开;未评分不计零分。费用未知时标记未计价。
24
+
25
+ 批量提交指定 `dataset.version`,可用 `dataset.caseIds` 选择样本,并使用 `dataset.mapping` 将样本字段绑定到流程输入。`datasets.versions.cases` 查询样本 ID。预检显示样本数、方案数、调用上限及可能等待的步骤。
26
+
27
+ Buz 对话评分通过 `modellab api call evaluations.plan.create --file grading.json` 执行,使用原聊天运行 ID 和已发布的 Buz 评分方案版本。该版本定义角色权重、不适用规则、安全和契约检查,以及裁判实际收到的材料。可用 `modellab evaluations get <批次ID> --json` 查看结果与证据。
28
+
29
+ 发布评分方案时,使用 `resources create --file plan-resource.json` 创建 kind 为 evaluator 的资源,在 body.plan 中配置 `schemaVersion: "scoring-plan/1"`、method、target 和规则。通过 `drafts update <id> --if-revision <revision> --file body.json` 更新草稿,再用 `drafts publish <id> --if-revision <revision> --note "评分方案"` 发布。执行用 `modellab api call evaluations.plan.create --file scoring-request.json`,请求包含 runId 和 plan 的 resourceId/versionId,模型评分可额外传 judge 版本引用。批次可用 `modellab evaluations get <批次ID> --json` 查询。
30
+
31
+
32
+ 发布模型评分方案时,在 `body.plan.request` 填写 `outputFormat`(`text`、`json` 或 `conversation-scorecard`)与 `fields`。例如 `{"output":"outputA","rubric":"dimensions"}` 表示仅将候选输出和维度定义发送给裁判。整段对话还可映射 `conversation`、`initialHistory` 和 `memory`。直接调用 `evaluations.model.create` 时在请求顶层提供同样的 `request` 配置。通过 `limits.maxOutputTokens` 显式配置裁判输出上限。
33
+
34
+ 编排批量评测时,`dataset.run` 步骤指定测试集、被测流程、样本映射和 `variants`。后续 `evaluate.result_set` 将 `inputs.resultSet` 绑定该步骤输出。用 `runs create --file flow-run.json --dry-run` 查看批量执行规模。 `runs get` 的 `stepJobs` 列出子运行、结果集和评分批次。通过 `output-sets list` 查询可复用结果集,通过 `evaluations plan --file request.json` 提交 `{ "outputSetId": "...", "plan": { "resourceId": "...", "versionId": "..." } }`。
@@ -0,0 +1,19 @@
1
+ # 资源、版本与测试集
2
+
3
+ ```sh
4
+ modellab resources list --project PROJECT_UUID --json
5
+ modellab schema get resources.create --json
6
+ modellab resources create --project PROJECT_UUID --file resource.json --json
7
+ modellab drafts update DRAFT_UUID --project PROJECT_UUID --if-revision 1 --file body.json --json
8
+ modellab drafts publish DRAFT_UUID --project PROJECT_UUID --if-revision 2 --note '验证后发布' --json
9
+ ```
10
+
11
+ 草稿修订号来自服务端;409 时保留本地修改、重新读取差异,不能无条件覆盖。版本不可变,恢复旧内容发布新版本。引用固定 resourceId 与 versionId,不使用 latest。
12
+
13
+ 流程步骤用 `steps[].name` 保存显示名称,参数绑定用 `{ "source": "step", "stepId": "analyze", "path": "text" }` 选择任意先前步骤的文本输出。重命名时保留步骤的 `id`,下游可继续引用。`inputFields`、`parameters` 和结果映射按需声明。省略 `outputs` 时,`result` 采用最后一步的输出。发布前可通过 `runs create --draft ... --if-revision ... --dry-run` 校验。
14
+
15
+ 测试集样本修订、纳入设置、划分及发布通过 `datasets.cases.*` 和 drafts.publish。原始导入文件上传到 GCS;input 与 expectation 分开,隐藏答案不能填进被测 Prompt。JSONL 可转换为样本数组,CSV 导入必须映射字段后提交。
16
+
17
+ 系统 Skill 通过 `resources.create`,kind=instruction_skill,正文含 instruction、variables、examples。它们只作用于明确选择的模型步骤。
18
+
19
+ Buz 聊天基准可以用 `modellab datasets import-buz cases.json --dry-run --json` 检查数量,再用 `modellab datasets import-buz cases.json --project PROJECT_UUID --json` 导入和发布,结果包含测试集和版本 ID。
@@ -0,0 +1,16 @@
1
+ # 安装与登录
2
+
3
+ 需要 Node.js 24 LTS 和 npm。运行 `npm install -g modellab-cli@0.1.0` 安装指定版本。本地开发可使用客户端仓库生成的 npm tarball 安装。
4
+
5
+ ```sh
6
+ modellab profile add local --server http://127.0.0.1:8080
7
+ modellab auth login --profile local --feishu
8
+ modellab context use --project PROJECT_UUID
9
+ modellab doctor --json
10
+ ```
11
+
12
+ 飞书登录时,用户打开终端给出的工作台链接,输入登录码并确认,CLI 签发 7 天登录凭证。使用 ModelLab 账号时,省略 `--feishu`,按终端提示输入账号和密码。macOS 默认使用系统钥匙串;其他系统选择 `--credential-store file` 时明确使用权限为 0600 的本地凭证文件。自动化可通过 MODELLAB_TOKEN 使用运行时令牌。令牌和模型 API Key 是不同对象。不要把密码、模型密钥写入命令参数或日志。
13
+
14
+ `--json` 让 stdout 只包含 JSON;流式事件用 NDJSON。失败退出码:2 参数;3 权限;4 任务失败;5 版本或幂等冲突;6 本地等待超时;7 不兼容;8 提交结果未知;9 已取消。
15
+
16
+ 通过 `connections.create` 配置 Vertex AI 时,使用 `google.vertex_generate_content`,`endpoint` 指向 Google Vertex AI 的 `/v1/projects/{project}/locations/{location}/publishers/google`,通过受保护的文件或 stdin 提交 `serviceAccount.clientEmail` 和 `serviceAccount.privateKey`。轮换通过 `connections.rotate` 提交同样的凭证字段。创建模型可用 `defaultParameters` 设置默认参数,例如 Gemini 的 `thinkingLevel`。
@@ -0,0 +1,66 @@
1
+ {
2
+ "flow": {
3
+ "definition": {
4
+ "schemaVersion": "flow/2",
5
+ "inputFields": {
6
+ "idea": {
7
+ "label": "人物想法",
8
+ "type": "text",
9
+ "required": true
10
+ },
11
+ "messages": {
12
+ "label": "脚本",
13
+ "type": "messages",
14
+ "required": true
15
+ }
16
+ },
17
+ "parameters": {},
18
+ "steps": [
19
+ {
20
+ "id": "dialogue",
21
+ "type": "conversation",
22
+ "inputs": {
23
+ "userMessages": {
24
+ "source": "input",
25
+ "path": "messages"
26
+ }
27
+ },
28
+ "config": {
29
+ "model": {
30
+ "resourceId": "MODEL_RESOURCE_UUID",
31
+ "versionId": "MODEL_VERSION_UUID"
32
+ },
33
+ "prompt": "请描述以下人物:{{idea}}",
34
+ "mode": "script",
35
+ "maxTurns": 5
36
+ },
37
+ "enabled": true,
38
+ "timeoutMs": 120000,
39
+ "failurePolicy": "stop_item"
40
+ }
41
+ ]
42
+ }
43
+ },
44
+ "samples": [
45
+ {
46
+ "input": {
47
+ "idea": "喜欢天文的图书管理员",
48
+ "messages": [
49
+ {
50
+ "role": "user",
51
+ "content": "你好,请介绍你自己。"
52
+ },
53
+ {
54
+ "role": "user",
55
+ "content": "你最喜欢什么?"
56
+ }
57
+ ]
58
+ }
59
+ }
60
+ ],
61
+ "repetitions": 1,
62
+ "limits": {
63
+ "maxConcurrency": 2,
64
+ "maxOutputTokens": 1024
65
+ }
66
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "runId": "RUN_UUID",
3
+ "name": "新的规则评分",
4
+ "rules": [
5
+ {
6
+ "key": "length",
7
+ "type": "length",
8
+ "min": 20,
9
+ "max": 1000,
10
+ "required": true
11
+ }
12
+ ]
13
+ }
@@ -0,0 +1,44 @@
1
+ {
2
+ "flow": {
3
+ "definition": {
4
+ "schemaVersion": "flow/2",
5
+ "inputFields": {
6
+ "idea": {
7
+ "label": "人物想法",
8
+ "type": "text",
9
+ "required": true
10
+ }
11
+ },
12
+ "parameters": {},
13
+ "steps": [
14
+ {
15
+ "id": "generate",
16
+ "type": "llm.generate",
17
+ "inputs": {},
18
+ "config": {
19
+ "model": {
20
+ "resourceId": "MODEL_RESOURCE_UUID",
21
+ "versionId": "MODEL_VERSION_UUID"
22
+ },
23
+ "prompt": "请描述以下人物:{{idea}}"
24
+ },
25
+ "enabled": true,
26
+ "timeoutMs": 120000,
27
+ "failurePolicy": "stop_item"
28
+ }
29
+ ]
30
+ }
31
+ },
32
+ "samples": [
33
+ {
34
+ "input": {
35
+ "idea": "喜欢天文的图书管理员"
36
+ }
37
+ }
38
+ ],
39
+ "repetitions": 1,
40
+ "limits": {
41
+ "maxConcurrency": 2,
42
+ "maxOutputTokens": 1024
43
+ }
44
+ }