viatris-exam-cli 0.0.0-stage → 1.3.0

package/README.md

@@ -1,3 +1,212 @@
-# Temporary Holding Version
+# Viatris Exam 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.
+面向 Agent 的 Viatris 考试 OpenAPI 命令行客户端。运行时零第三方依赖，要求 Node.js 18 或更高版本。
+
+## 安装
+
+```bash
+npm link
+export VIATRIS_API_KEY="replace-with-real-key"
+```
+
+默认连接线上环境：
+
+```text
+https://apaaspsc.doubaoapps.com/app/app_17gbe211qq5/openapi/
+```
+
+切换到开发环境：
+
+```bash
+export VIATRIS_API_ENV="development"
+```
+
+开发环境地址：
+
+```text
+https://apaaspsc-app_17gbe211qq5-1879207268486311.aiforce.run/app/app_17gbe211qq5/openapi/
+```
+
+`VIATRIS_API_ENV` 支持 `production`、`development`，以及别名 `prod`、`dev`。如需临时连接其他部署，可设置 `VIATRIS_API_BASE_URL`；该变量的优先级高于环境预设。
+
+CLI 不接受 `--api-key` 参数，避免密钥进入 shell history、进程列表或 Agent 日志。默认使用：
+
+```text
+X-API-Key: <VIATRIS_API_KEY>
+```
+
+若服务端使用 Bearer Token：
+
+```bash
+export VIATRIS_API_KEY_HEADER="Authorization"
+export VIATRIS_API_KEY_PREFIX="Bearer "
+```
+
+## Agent 接口约定
+
+- API 成功响应以 JSON 写入 `stdout`。
+- 错误以单行结构化 JSON 写入 `stderr`。
+- POST/PUT 请求从文件、`stdin` 或 `--json` 读取 JSON 对象。
+- API Key 只从 `VIATRIS_API_KEY` 环境变量读取。
+- 默认使用线上环境，可通过 `VIATRIS_API_ENV=development` 切换到开发环境。
+- `VIATRIS_API_BASE_URL` 可覆盖当前环境地址。
+- GET 请求遇到网络错误、HTTP 429 或 5xx 时自动重试，POST/PUT 不自动重试。
+- `describe` 返回机器可读的命令、参数、认证和退出码清单。
+- ID 路径参数自动进行 URL 编码。
+- HTTP 401/403 使用专用退出码，方便 Agent 判断需要刷新认证。
+
+```bash
+viatris-exam describe --compact
+```
+
+退出码：
+
+| 退出码 | 含义 |
+| --- | --- |
+| `0` | 成功 |
+| `1` | API 返回错误 |
+| `2` | 命令、参数、校验或输入错误 |
+| `3` | 环境配置错误 |
+| `4` | 网络或超时错误 |
+| `5` | 认证或授权错误 |
+
+## 命令
+
+### 产品知识树
+
+```bash
+viatris-exam products get "$PRODUCT_ID"
+viatris-exam products update-knowledge-tree "$PRODUCT_ID" \
+  --input knowledge-tree.json
+```
+
+知识树回写是完整替换操作，必须一次提交全部 10-500 个 L3/L4 动态节点。先查询产品以获取固定 L2 维度的 `clientRef`。
+
+### 出题任务
+
+```bash
+viatris-exam gen-tasks list --status generating --limit 20
+viatris-exam gen-tasks get "$TASK_ID"
+viatris-exam gen-tasks submit "$TASK_ID" --input examples/generated-questions.json
+```
+
+`externalRef` 是题目回写的幂等键。Agent 重试 POST 前应复用原值。
+
+### 考试记录
+
+```bash
+viatris-exam exam-records get "$RECORD_ID"
+viatris-exam exam-records scoring-rules "$RECORD_ID"
+```
+
+第二个命令返回答卷绑定版本的完整评分规则及用于回写的 `taskId`。
+
+### 评分任务
+
+```bash
+viatris-exam scoring get "$TASK_ID"
+viatris-exam scoring submit "$TASK_ID" --input examples/scoring-results.json
+```
+
+评分规则 V2 使用稳定的评分点 ID、扣分规则 ID 和题目级封顶规则，由服务端计算最终得分。V1 `pointResults` 结构继续兼容。
+
+### 考试与题库
+
+```bash
+viatris-exam exams create --input exam.json
+viatris-exam questions create < questions.json
+viatris-exam questions version "$QUESTION_ID" --input version.json
+```
+
+### 医疗知识检索
+
+简单查询可直接使用参数：
+
+```bash
+viatris-exam medical-search search "阿托伐他汀 适应症" \
+  --file-type drug \
+  --limit 4 \
+  --max-length 1200
+```
+
+也可提交完整 JSON：
+
+```bash
+printf '%s' '{"query":"阿托伐他汀 适应症","limit":4}' |
+  viatris-exam medical-search search
+```
+
+## 错误格式
+
+```json
+{
+  "error": {
+    "type": "http_error",
+    "message": "API request failed with HTTP 422.",
+    "details": {
+      "status": 422,
+      "method": "POST",
+      "path": "/openapi/questions",
+      "requestId": "request-id",
+      "response": {
+        "message": "validation failed"
+      }
+    }
+  }
+}
+```
+
+## 全局参数
+
+```text
+--base-url <url>       覆盖当前环境地址
+--key-header <name>    覆盖 VIATRIS_API_KEY_HEADER
+--key-prefix <value>   覆盖 VIATRIS_API_KEY_PREFIX
+--timeout <ms>         超时时间，默认 30000
+--retries <n>          GET 重试次数，默认 2
+--compact              输出单行紧凑 JSON
+```
+
+地址选择优先级为 `--base-url`、`VIATRIS_API_BASE_URL`、`VIATRIS_API_ENV` 对应的预设地址。认证 Key 仍必须通过 `VIATRIS_API_KEY` 提供。
+
+## 项目结构
+
+```text
+src/
+├── cli.js       # 入口与异常收口
+├── app.js       # 应用编排
+├── commands.js  # 领域命令路由
+├── command-handlers/
+│   └── *.js     # 各领域到 OpenAPI 请求的映射
+├── args.js      # 参数解析与校验
+├── input.js     # JSON 文件、stdin 与内联输入
+├── config.js    # 环境、地址与认证配置
+├── http.js      # HTTP、重试与响应处理
+├── metadata.js  # 版本、命令和环境元数据
+├── help.js      # 帮助文本
+├── output.js    # 标准 JSON 输出
+└── errors.js    # 错误类型
+skills/
+└── viatris-exam-cli/
+    ├── SKILL.md
+    └── references/cli-reference.md
+```
+
+可分发的 Agent Skill 位于 `skills/viatris-exam-cli/`，与 `src/` 同级并包含在 npm 发布包中。`skills/viatris-exam-cli.zip` 是同步生成的独立分发包。`.trae/skills/viatris-exam-cli` 是指向规范目录的相对符号链接，仅用于本地自动发现。
+
+## 变更规则
+
+任何代码、命令、接口结构、环境地址或文档变化都必须：
+
+1. 更新 `skills/viatris-exam-cli/SKILL.md` 及受影响的参考文件。
+2. 同步递增 `package.json`、`src/metadata.js` 和 Skill frontmatter 中的版本。
+3. 保持 `src/cli.js` 为薄入口，将能力放在职责单一的模块中。
+4. 重新生成 Skill ZIP 并执行验证：
+
+```bash
+npm run pack:skill
+npm test
+npm run check
+npm run check:versions
+npm run check:skill
+```

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "viatris-exam-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.0",
+  "description": "Agent-friendly CLI for the Viatris exam OpenAPI",
+  "type": "module",
+  "bin": {
+    "viatris-exam": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "skills/"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/*.js && node --check src/command-handlers/*.js",
+    "check:versions": "node scripts/check-versions.js",
+    "check:skill": "node scripts/check-skill.js",
+    "pack:skill": "cd skills && /bin/rm -f viatris-exam-cli.zip && /usr/bin/zip -qr viatris-exam-cli.zip viatris-exam-cli -x '*.DS_Store'"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/skills/viatris-exam-cli/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: viatris-exam-cli
+description: Operate the Viatris exam OpenAPI through its agent-friendly CLI. Use for products, knowledge trees, generation tasks, exam records, scoring, exams, questions, or medical search.
+version: 1.3.0
+---
+
+# Viatris Exam CLI
+
+Use the repository-local CLI for every supported API operation. Do not call the HTTP endpoints directly when the CLI covers the task.
+
+## Start
+
+1. Run commands from the repository root.
+2. Require `VIATRIS_API_KEY` in the environment. Never place the key in arguments, files, output, or logs.
+3. Use production by default. Set `VIATRIS_API_ENV=development` only when the user requests development or testing.
+4. Run `node src/cli.js describe --compact` when capability discovery or exact machine-readable metadata is needed.
+5. Read [references/cli-reference.md](references/cli-reference.md) before constructing a write payload or handling a nonzero exit code.
+
+## Execute
+
+- Invoke the CLI as `node src/cli.js ...`. Do not require `npm link`.
+- Prefer `--input <file>` for existing payloads and stdin for generated payloads.
+- Parse successful `stdout` as JSON.
+- Parse failed `stderr` as JSON and branch on both exit code and `error.type`.
+- Preserve `externalRef` when retrying question submission. It is the idempotency key.
+- Prefer scoring rule V2 for generated questions and scoring results. Use stable point and deduction-rule IDs.
+- Do not automatically retry POST or PUT commands. Inspect the returned error and determine whether the server accepted the request.
+- Keep temporary payloads outside the repository unless they are requested deliverables.
+
+## Maintain
+
+Treat every repository behavior, command, schema, URL, documentation, or implementation change as a versioned Skill change.
+
+For every change:
+
+1. Update `skills/viatris-exam-cli/` and its affected references.
+2. Increment the semantic version in `package.json`, `src/metadata.js`, and this frontmatter `version`.
+3. Keep all three versions identical.
+4. Keep `src/cli.js` as a thin entrypoint. Put capabilities in focused modules under `src/`.
+5. Keep `.trae/skills/viatris-exam-cli` as a relative symlink to the distributable Skill directory.
+6. Run `npm run pack:skill` so `skills/viatris-exam-cli.zip` matches the canonical directory.
+7. Run `npm test`, `npm run check`, `npm run check:versions`, and `npm run check:skill`.
+
+Do not finish a code change while the Skill or any version is stale.

package/skills/viatris-exam-cli/references/cli-reference.md

@@ -0,0 +1,319 @@
+# CLI Reference
+
+## Authentication And Environment
+
+Required:
+
+```bash
+export VIATRIS_API_KEY="..."
+```
+
+Environment selection:
+
+| Value | Target |
+| --- | --- |
+| unset, `production`, `prod` | Production |
+| `development`, `dev` | Development |
+
+`VIATRIS_API_BASE_URL` overrides the selected environment. Use it only for an explicitly supplied custom deployment or local mock.
+
+Default authentication header:
+
+```text
+X-API-Key: <VIATRIS_API_KEY>
+```
+
+For Bearer authentication:
+
+```bash
+export VIATRIS_API_KEY_HEADER="Authorization"
+export VIATRIS_API_KEY_PREFIX="Bearer "
+```
+
+## Capability Discovery
+
+```bash
+node src/cli.js describe --compact
+node src/cli.js --help
+node src/cli.js --version
+```
+
+`describe` does not require credentials. It returns commands, paths, environment metadata, authentication metadata, and exit codes as JSON.
+
+## Commands
+
+Get a product and its fixed L2 dimensions:
+
+```bash
+node src/cli.js products get "$PRODUCT_ID" --compact
+```
+
+Use each returned `fixedDimensions[].clientRef` as the parent reference for an L3 node.
+
+Replace a product knowledge tree:
+
+```bash
+node src/cli.js products update-knowledge-tree "$PRODUCT_ID" \
+  --input knowledge-tree.json \
+  --compact
+```
+
+Payload shape:
+
+```json
+{
+  "nodes": [
+    {
+      "clientRef": "disease.hypertension",
+      "parentClientRef": "dimension:disease",
+      "level": 3,
+      "dimensionCode": "disease",
+      "name": "高血压",
+      "sortOrder": 1
+    },
+    {
+      "clientRef": "disease.hypertension.definition",
+      "parentClientRef": "disease.hypertension",
+      "level": 4,
+      "dimensionCode": "disease",
+      "name": "定义与诊断",
+      "sortOrder": 1,
+      "documents": [
+        {
+          "title": "药品说明书",
+          "url": "https://example.com/source",
+          "summary": "与该知识点直接对应的证据摘录"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Submit the complete L3/L4 node set, between 10 and 500 nodes. Every `clientRef` must be unique within the payload. L3 nodes use `dimension:<code>` as `parentClientRef`; L4 nodes use an L3 `clientRef`. Every L4 node needs at least one document. A successful PUT replaces the previous dynamic nodes, so do not send a partial tree.
+
+List generation tasks:
+
+```bash
+node src/cli.js gen-tasks list \
+  --status generating \
+  --limit 20 \
+  --compact
+```
+
+`--status` accepts `generating`, `partial_failed`, or `failed`. `--limit` accepts 1 through 50.
+
+Get one generation task:
+
+```bash
+node src/cli.js gen-tasks get "$TASK_ID" --compact
+```
+
+Submit generated questions:
+
+```bash
+node src/cli.js gen-tasks submit "$TASK_ID" --input payload.json --compact
+```
+
+Payload shape:
+
+```json
+{
+  "items": [
+    {
+      "externalRef": "agent-q-0001",
+      "failureId": "optional-failure-id",
+      "content": {
+        "stem": "Question stem",
+        "referenceAnswer": "Reference answer",
+        "scoringPoints": [
+          {
+            "id": "dose-selection",
+            "point": "Scoring point",
+            "maxScore": 4,
+            "criteria": "Choose one deduction level",
+            "deductionRules": [
+              {
+                "id": "dose-selection-full",
+                "level": "full",
+                "deductScore": 0,
+                "criteria": "Complete answer"
+              },
+              {
+                "id": "dose-selection-zero",
+                "level": "zero",
+                "deductScore": 4,
+                "criteria": "Wrong or missing answer"
+              }
+            ]
+          }
+        ],
+        "scoringRuleVersion": 2,
+        "scoreCapRules": [
+          {
+            "id": "critical-error-1",
+            "description": "Critical contradictory conclusion",
+            "maxTotalScore": 2
+          }
+        ],
+        "evidence": [
+          {
+            "source": "Source",
+            "citation": "Citation",
+            "relevance": "Relevance"
+          }
+        ]
+      },
+      "qcResult": {
+        "outOfScope": false,
+        "insufficientEvidence": false,
+        "answerConflict": false,
+        "duplicateRisk": false,
+        "summary": "No obvious issue"
+      }
+    }
+  ],
+  "finished": true
+}
+```
+
+Get a submitted exam record and its frozen answers:
+
+```bash
+node src/cli.js exam-records get "$RECORD_ID" --compact
+```
+
+Get the complete scoring rules bound to the record:
+
+```bash
+node src/cli.js exam-records scoring-rules "$RECORD_ID" --compact
+```
+
+The response includes the scoring `taskId`, `schemaVersion`, frozen question versions, evidence, V2 deduction rules, score caps, and item IDs. Use its `taskId` for scoring submission.
+
+Get a scoring task:
+
+```bash
+node src/cli.js scoring get "$TASK_ID" --compact
+```
+
+Submit scoring results:
+
+```bash
+node src/cli.js scoring submit "$TASK_ID" --input results.json --compact
+```
+
+Payload shape:
+
+```json
+{
+  "items": [
+    {
+      "itemId": "item-id",
+      "ok": true,
+      "pointJudgements": [
+        {
+          "pointId": "dose-selection",
+          "appliedDeductionRuleId": "dose-selection-full",
+          "reason": "Reason for selecting this deduction level",
+          "quote": "Supporting answer quote"
+        }
+      ],
+      "triggeredScoreCaps": [],
+      "flags": [],
+      "needReview": false
+    }
+  ]
+}
+```
+
+For V2, submit exactly one `pointJudgement` per scoring point. IDs must match the fetched rule set. Add triggered cap rule IDs to `triggeredScoreCaps`; the server calculates the score, so `total` is optional and must match if supplied. V1 remains compatible through `pointResults` and required `total`. For a failed item, set `ok` to `false` and provide `failureReason`.
+
+Create an exam:
+
+```bash
+node src/cli.js exams create --input exam.json --compact
+```
+
+Required top-level fields are `name`, `product`, `questionCount`, `startAt`, `endAt`, `resultPolicy`, and `assigneeIds`. `questionCount` is 1 through 150. Use either `questions` or legacy `questionIds`, never both. Each question score must be a positive integer and the complete exam must total exactly 100.
+
+Create questions directly:
+
+```bash
+node src/cli.js questions create --input questions.json --compact
+```
+
+Payload shape is `{ "items": [...] }`. Each item requires `product`, `dimension`, and `content`; provide `externalRef` for idempotency. Prefer `scoringRuleVersion: 2`, stable IDs on scoring points and deduction rules, and explicit `scoreCapRules`.
+
+The API has partial-success semantics: inspect `accepted`, `duplicates`, and every entry in `rejected` even when the HTTP response is successful.
+
+Add a question version:
+
+```bash
+node src/cli.js questions version "$QUESTION_ID" --input version.json --compact
+```
+
+Required fields are `stem`, `referenceAnswer`, nonempty `scoringPoints`, `evidence`, and `editReason`. V2 versions may also include `scoringRuleVersion: 2`, deduction rules, and `scoreCapRules`.
+
+Search medical evidence:
+
+```bash
+node src/cli.js medical-search search "阿托伐他汀 适应症" \
+  --file-type drug \
+  --limit 4 \
+  --max-length 1200 \
+  --compact
+```
+
+Or use JSON:
+
+```bash
+printf '%s' '{"query":"阿托伐他汀 适应症","limit":4}' |
+  node src/cli.js medical-search search --compact
+```
+
+Do not combine query flags with JSON input.
+
+## Input Rules
+
+Choose exactly one input form:
+
+```bash
+node src/cli.js questions create --input payload.json
+node src/cli.js questions create --input - < payload.json
+node src/cli.js questions create --json '{"items":[]}'
+printf '%s' '{"items":[]}' | node src/cli.js questions create
+```
+
+The top-level JSON value must be an object.
+
+## Output And Errors
+
+Success writes API JSON to `stdout`. Errors write one JSON object to `stderr`:
+
+```json
+{
+  "error": {
+    "type": "http_error",
+    "message": "API request failed with HTTP 422.",
+    "details": {
+      "status": 422,
+      "method": "POST",
+      "path": "/openapi/questions",
+      "requestId": "optional-request-id",
+      "response": {}
+    }
+  }
+}
+```
+
+| Exit | Meaning | Agent action |
+| --- | --- | --- |
+| `0` | Success | Parse stdout JSON |
+| `1` | API error | Inspect status and response |
+| `2` | Usage, validation, or input error | Correct command or payload |
+| `3` | Configuration error | Check environment configuration |
+| `4` | Network or timeout error | GET may be retried; inspect POST/PUT state first |
+| `5` | Authentication or authorization error | Refresh or correct credentials |
+
+GET automatically retries network errors, HTTP 429, and HTTP 5xx. POST and PUT never retry automatically.

package/src/app.js

@@ -0,0 +1,36 @@
+import { assertNoExtraPositionals, parseArgs } from "./args.js";
+import { resolveCommand } from "./commands.js";
+import { configFrom } from "./config.js";
+import { helpText } from "./help.js";
+import { request } from "./http.js";
+import { describeCli, VERSION } from "./metadata.js";
+import { writeJson } from "./output.js";
+
+export async function run(
+  argv,
+  {
+    stdout = process.stdout,
+    environmentVariables = process.env,
+  } = {},
+) {
+  const { positionals, options } = parseArgs(argv);
+
+  if (options.version) {
+    stdout.write(`${VERSION}\n`);
+    return;
+  }
+  if (options.help || positionals.length === 0) {
+    stdout.write(helpText());
+    return;
+  }
+  if (positionals[0] === "describe") {
+    assertNoExtraPositionals(positionals, 1);
+    writeJson(stdout, describeCli(), options.compact);
+    return;
+  }
+
+  const command = await resolveCommand(positionals, options);
+  const config = configFrom(options, environmentVariables);
+  const response = await request(command, config);
+  writeJson(stdout, response, options.compact);
+}