viatris-exam-cli 1.6.0 → 1.8.1

package/README.md

@@ -5,8 +5,17 @@
 ## 安装
 
 ```bash
-npm link
+npm install -g viatris-exam-cli
 export VIATRIS_API_KEY="replace-with-real-key"
+viatris-exam login
+unset VIATRIS_API_KEY
+```
+
+开始任务前更新到最新版本：
+
+```bash
+npm install -g viatris-exam-cli@latest
+viatris-exam --version
 ```
 
 默认连接线上环境：
@@ -29,25 +38,27 @@ https://apaaspsc-app_17gbe211qq5-1879207268486311.aiforce.run/app/app_17gbe211qq
 
 `VIATRIS_API_ENV` 支持 `production`、`development`，以及别名 `prod`、`dev`。如需临时连接其他部署，可设置 `VIATRIS_API_BASE_URL`；该变量的优先级高于环境预设。
 
-CLI 不接受 `--api-key` 参数，避免密钥进入 shell history、进程列表或 Agent 日志。默认使用：
+`login` 将 Key 写入 `~/.viatris-exam/.credentials.json`。隐藏目录权限为 `0700`，凭证文件权限为 `0600`。CLI 不接受 `--api-key` 参数，也不会输出 Key。
 
-```text
-X-API-Key: <VIATRIS_API_KEY>
-```
+读取顺序：
 
-若服务端使用 Bearer Token：
+1. 优先读取隐藏凭证文件。
+2. 文件不存在时读取 `VIATRIS_API_KEY`。
 
-```bash
-export VIATRIS_API_KEY_HEADER="Authorization"
-export VIATRIS_API_KEY_PREFIX="Bearer "
+默认认证格式：
+
+```text
+Authorization: Bearer <API key>
 ```
 
+无需设置 `VIATRIS_API_KEY_HEADER` 或 `VIATRIS_API_KEY_PREFIX`。
+
 ## Agent 接口约定
 
 - API 成功响应以 JSON 写入 `stdout`。
 - 错误以单行结构化 JSON 写入 `stderr`。
 - POST/PUT 请求从文件、`stdin` 或 `--json` 读取 JSON 对象。
-- API Key 只从 `VIATRIS_API_KEY` 环境变量读取。
+- API Key 优先从隐藏凭证文件读取，环境变量作为兜底。
 - 默认使用线上环境，可通过 `VIATRIS_API_ENV=development` 切换到开发环境。
 - `VIATRIS_API_BASE_URL` 可覆盖当前环境地址。
 - GET 请求遇到网络错误、HTTP 429 或 5xx 时自动重试，POST/PUT/PATCH/DELETE 不自动重试。
@@ -114,6 +125,8 @@ viatris-exam knowledge documents delete <document-id>
 
 `/knowledge` CRUD 响应中的 `level` 是物理存储层级（产品根为 1、固定维度为 2）；产品生成接口使用业务层级（产品隐藏、固定维度为 L1、动态节点为 L2-L4）。
 
+所有文档写入都会在请求发出前从 `title`、`url`、`summary` 中移除“小荷”“小荷医疗”和“小荷 AI 医生”及其空格变体。当前写接口只接受 `title` 和 `summary`，输入中的 `url` 会在净化后从出站载荷移除，但 URL 净化能力作为永久兼容规则保留。该规则覆盖文档创建、批量 upsert、单文档更新和整树回写中的嵌套文档；标题清洗后为空会直接返回校验错误。
+
 ### 出题任务
 
 ```bash
@@ -196,14 +209,14 @@ printf '%s' '{"query":"阿托伐他汀 适应症","limit":20}' |
 
 ```text
 --base-url <url>       覆盖当前环境地址
---key-header <name>    覆盖 VIATRIS_API_KEY_HEADER
---key-prefix <value>   覆盖 VIATRIS_API_KEY_PREFIX
+--key-header <name>    覆盖认证头，默认 Authorization
+--key-prefix <value>   覆盖认证前缀，默认 "Bearer "
 --timeout <ms>         超时时间，默认 30000
 --retries <n>          GET 重试次数，默认 2
 --compact              输出单行紧凑 JSON
 ```
 
-地址选择优先级为 `--base-url`、`VIATRIS_API_BASE_URL`、`VIATRIS_API_ENV` 对应的预设地址。认证 Key 仍必须通过 `VIATRIS_API_KEY` 提供。
+地址选择优先级为 `--base-url`、`VIATRIS_API_BASE_URL`、`VIATRIS_API_ENV` 对应的预设地址。认证 Key 优先使用隐藏凭证文件，文件不存在时使用 `VIATRIS_API_KEY`。
 
 ## 项目结构
 
@@ -217,7 +230,10 @@ src/
 ├── args.js      # 参数解析与校验
 ├── input.js     # JSON 文件、stdin 与内联输入
 ├── config.js    # 环境、地址与认证配置
+├── credentials.js # 隐藏凭证文件读写
 ├── http.js      # HTTP、重试与响应处理
+├── sanitizers/
+│   └── documents.js # 文档永久净化规则
 ├── metadata.js  # 版本、命令和环境元数据
 ├── help.js      # 帮助文本
 ├── output.js    # 标准 JSON 输出

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viatris-exam-cli",
-  "version": "1.6.0",
+  "version": "1.8.1",
   "description": "Agent-friendly CLI for the Viatris exam OpenAPI",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "check": "node --check src/*.js && node --check src/command-handlers/*.js",
+    "check": "node --check src/*.js && node --check src/command-handlers/*.js && node --check src/sanitizers/*.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'"

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

@@ -1,27 +1,31 @@
 ---
 name: viatris-exam-cli
-description: Operate the Viatris exam OpenAPI through its agent-friendly CLI. Use for products, knowledge nodes or documents, generation tasks, exam records, scoring, exams, questions, or medical search.
-version: 1.6.0
+description: Operate the Viatris exam OpenAPI through its agent-friendly CLI. Use for login, products, knowledge, generation tasks, exam records, scoring, exams, questions, or medical search.
+version: 1.8.1
 ---
 
 # 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.
+Use the installed 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.
+1. Read the install and update sections in [references/cli-reference.md](references/cli-reference.md).
+2. Install `viatris-exam-cli` from npm when unavailable.
+3. Update to `viatris-exam-cli@latest` at the start of a task so capability instructions match the installed CLI.
+4. Verify with `viatris-exam --version`.
+5. Prefer the saved credential. To initialize or rotate it, set `VIATRIS_API_KEY` and run `viatris-exam login`; never place the key in command arguments, output, or logs.
+6. Use production by default. Set `VIATRIS_API_ENV=development` only when the user requests development or testing.
+7. Run `viatris-exam describe --compact` when capability discovery or exact machine-readable metadata is needed.
+8. Read the relevant command section in the reference 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`.
+- Invoke commands through the installed `viatris-exam` binary.
 - 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`.
+- Authentication defaults to `Authorization: Bearer <key>`. Read the hidden credential file first and use `VIATRIS_API_KEY` only when no saved credential exists.
 - Use `products list` to resolve product master IDs and stable codes before product-specific workflows. `products create` requires only a Chinese name and also initializes the canonical knowledge-tree root.
 - Use `products update` only for verified optional medical master data. Do not infer English names, generic names, indications, dosage forms, or remarks without evidence.
 - Preserve `externalRef` when retrying question submission. It is the idempotency key.
@@ -29,6 +33,8 @@ Use the repository-local CLI for every supported API operation. Do not call the
 - Apply every returned generation rule. Product-scoped rules identify applicable product codes through `products`; global rules return an empty `products` array.
 - Prefer scoring rule V2 for generated questions and scoring results. Use stable point and deduction-rule IDs.
 - Treat product master records as outside business knowledge-tree levels. Fixed dimensions are business L1; generated nodes are L2-L4. Product detail lookup also accepts a historical knowledge-tree root ID.
+- Document writes automatically remove 小荷 source-brand labels, including 小荷医疗 and whitespace variants of 小荷 AI 医生, from title, URL, and summary. Never reintroduce these labels after CLI sanitization.
+- Current document write APIs accept only `title` and `summary`; the CLI drops an input `url` before sending. Keep URL sanitization in the permanent sanitizer for backward and future compatibility.
 - Treat knowledge-tree and recursive node deletion as destructive. Inspect the target first and perform them only when the user explicitly requests deletion.
 - Do not automatically retry POST, PUT, PATCH, or DELETE commands. Inspect the returned error and determine whether the server accepted the request.
 - Keep temporary payloads outside the repository unless they are requested deliverables.

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

@@ -1,13 +1,40 @@
 # CLI Reference
 
+## Install
+
+Install the CLI globally so every example below can use the `viatris-exam` command directly:
+
+```bash
+npm install -g viatris-exam-cli
+viatris-exam --version
+```
+
+## Update
+
+Update before starting a task so the installed capabilities and this Skill remain aligned:
+
+```bash
+npm install -g viatris-exam-cli@latest
+viatris-exam --version
+```
+
 ## Authentication And Environment
 
-Required:
+Login once:
 
 ```bash
 export VIATRIS_API_KEY="..."
+viatris-exam login
+unset VIATRIS_API_KEY
 ```
 
+Login writes `~/.viatris-exam/.credentials.json` with file mode `0600`; its containing directory uses mode `0700`. The command never prints the key. Run login again with a new environment value to rotate the saved key.
+
+API key lookup order:
+
+1. Hidden credential file.
+2. `VIATRIS_API_KEY` environment variable when the file does not exist.
+
 Environment selection:
 
 | Value | Target |
@@ -17,25 +44,25 @@ Environment selection:
 
 `VIATRIS_API_BASE_URL` overrides the selected environment. Use it only for an explicitly supplied custom deployment or local mock.
 
-Default authentication header:
+Default authentication:
 
 ```text
-X-API-Key: <VIATRIS_API_KEY>
+Authorization: Bearer <API key>
 ```
 
-For Bearer authentication:
+No header or prefix environment variables are required. Advanced overrides remain available when connecting to a different compatible service:
 
 ```bash
-export VIATRIS_API_KEY_HEADER="Authorization"
-export VIATRIS_API_KEY_PREFIX="Bearer "
+export VIATRIS_API_KEY_HEADER="Custom-Header"
+export VIATRIS_API_KEY_PREFIX=""
 ```
 
 ## Capability Discovery
 
 ```bash
-node src/cli.js describe --compact
-node src/cli.js --help
-node src/cli.js --version
+viatris-exam describe --compact
+viatris-exam --help
+viatris-exam --version
 ```
 
 `describe` does not require credentials. It returns commands, paths, environment metadata, authentication metadata, and exit codes as JSON.
@@ -45,7 +72,7 @@ node src/cli.js --version
 List product master data:
 
 ```bash
-node src/cli.js products list --compact
+viatris-exam products list --compact
 ```
 
 The response is `{ "items": [...] }`, ordered by `sortOrder` and then name. Each record includes the stable `code`, Chinese name, optional English name, generic name, indication, dosage form, `active` or `inactive` status, remark, and timestamps.
@@ -53,7 +80,7 @@ The response is `{ "items": [...] }`, ordered by `sortOrder` and then name. Each
 Create a product and initialize its canonical knowledge-tree root:
 
 ```bash
-node src/cli.js products create --json '{
+viatris-exam products create --json '{
   "name": "络活喜",
   "genericName": "苯磺酸氨氯地平片",
   "indication": "高血压、冠心病",
@@ -68,7 +95,7 @@ Only `name` is required and the Chinese name must be unique. `code` is optional;
 Get a product and its fixed L1 dimensions:
 
 ```bash
-node src/cli.js products get "$PRODUCT_ID" --compact
+viatris-exam products get "$PRODUCT_ID" --compact
 ```
 
 Use the product master `id`; historical knowledge-tree root IDs remain accepted for compatibility. The response also contains nullable `nameEn`, `genericName`, `indication`, `dosageForm`, and `remark`. Product master data is outside business levels L1-L4. Use each returned `fixedDimensions[].clientRef` as the parent reference for an L2 node. Each fixed dimension also returns `level: 1` and a display `codePrefix`.
@@ -76,7 +103,7 @@ Use the product master `id`; historical knowledge-tree root IDs remain accepted
 Update verified optional medical master data:
 
 ```bash
-node src/cli.js products update "$PRODUCT_ID" --json '{
+viatris-exam products update "$PRODUCT_ID" --json '{
   "nameEn": "Lipitor",
   "genericName": "阿托伐他汀钙片",
   "indication": "高胆固醇血症、混合型血脂异常及心血管疾病预防",
@@ -90,7 +117,7 @@ Only supplied fields are updated. Each supplied value must be a nonempty string
 Replace a product knowledge tree:
 
 ```bash
-node src/cli.js products update-knowledge-tree "$PRODUCT_ID" \
+viatris-exam products update-knowledge-tree "$PRODUCT_ID" \
   --input knowledge-tree.json \
   --compact
 ```
@@ -126,7 +153,6 @@ Payload shape:
       "documents": [
         {
           "title": "药品说明书",
-          "url": "https://example.com/source",
           "summary": "与该知识点直接对应的证据摘录"
         }
       ]
@@ -140,7 +166,7 @@ Submit the complete L2/L3/L4 node set, between 15 and 500 nodes. Every `clientRe
 Delete all dynamic knowledge-tree content:
 
 ```bash
-node src/cli.js products delete-knowledge-tree "$PRODUCT_ID"
+viatris-exam products delete-knowledge-tree "$PRODUCT_ID"
 ```
 
 This destructive operation preserves the product root and five fixed L1 dimensions, deletes all L2-L4 nodes and evidence documents, and unbinds affected questions. Inspect the product and tree first, and execute only when the user explicitly requests the full reset.
@@ -150,7 +176,7 @@ This destructive operation preserves the product root and five fixed L1 dimensio
 Get the complete physical tree and all product documents:
 
 ```bash
-node src/cli.js knowledge tree lipitor --compact
+viatris-exam knowledge tree lipitor --compact
 ```
 
 The incremental `/knowledge` responses expose physical storage levels where the product root is 1 and fixed dimensions are 2. This differs from the product-generation business taxonomy, where the product is hidden, fixed dimensions are L1, and generated content is L2-L4.
@@ -158,7 +184,7 @@ The incremental `/knowledge` responses expose physical storage levels where the
 Create or reuse a visible path:
 
 ```bash
-node src/cli.js knowledge nodes by-path --json \
+viatris-exam knowledge nodes by-path --json \
   '{"product":"lipitor","path":["疾病知识","血脂异常基础","ASCVD 风险评估"]}'
 ```
 
@@ -167,20 +193,20 @@ The path has one to three entries. The first entry must be a fixed dimension nam
 Create or reuse one node under a known parent:
 
 ```bash
-node src/cli.js knowledge nodes create --json \
+viatris-exam knowledge nodes create --json \
   '{"parentId":"PARENT_ID","name":"ASCVD 风险评估","sortOrder":20}'
 ```
 
 Read, update, move, or delete a node:
 
 ```bash
-node src/cli.js knowledge nodes get "$NODE_ID"
-node src/cli.js knowledge nodes update "$NODE_ID" \
+viatris-exam knowledge nodes get "$NODE_ID"
+viatris-exam knowledge nodes update "$NODE_ID" \
   --json '{"name":"血脂异常与他汀治疗","sortOrder":5}'
-node src/cli.js knowledge nodes move "$NODE_ID" \
+viatris-exam knowledge nodes move "$NODE_ID" \
   --json '{"newParentId":"NEW_PARENT_ID","sortOrder":30}'
-node src/cli.js knowledge nodes delete "$NODE_ID"
-node src/cli.js knowledge nodes delete "$NODE_ID" --recursive
+viatris-exam knowledge nodes delete "$NODE_ID"
+viatris-exam knowledge nodes delete "$NODE_ID" --recursive
 ```
 
 Product roots and fixed dimensions are protected from rename, move, and deletion. Moving cannot cross products, target the node itself or its descendants, or produce levels deeper than L4. Plain deletion is the safe default and returns HTTP 409 when children or question bindings exist. `--recursive` deletes the full subtree and documents and unbinds affected questions. Inspect the node first and use recursive deletion only when explicitly requested.
@@ -188,22 +214,34 @@ Product roots and fixed dimensions are protected from rename, move, and deletion
 Manage documents:
 
 ```bash
-node src/cli.js knowledge documents list "$NODE_ID"
-node src/cli.js knowledge documents create "$NODE_ID" \
-  --json '{"title":"说明书","url":"https://example.com/source","summary":"摘录"}'
-node src/cli.js knowledge documents upsert "$NODE_ID" \
+viatris-exam knowledge documents list "$NODE_ID"
+viatris-exam knowledge documents create "$NODE_ID" \
+  --json '{"title":"说明书","summary":"摘录"}'
+viatris-exam knowledge documents upsert "$NODE_ID" \
   --json '{"items":[{"title":"说明书","summary":"更新后的摘录"}]}'
-node src/cli.js knowledge documents update "$DOCUMENT_ID" \
-  --json '{"url":null,"summary":"更新后的摘要"}'
-node src/cli.js knowledge documents delete "$DOCUMENT_ID"
+viatris-exam knowledge documents update "$DOCUMENT_ID" \
+  --json '{"summary":"更新后的摘要"}'
+viatris-exam knowledge documents delete "$DOCUMENT_ID"
 ```
 
-Create reuses a document with the same title under the node. Batch upsert accepts 1-20 items and updates `url` and `summary` for existing titles. A single-document update changes only supplied fields; send `null` to clear `url` or `summary`. Inspect a document before an explicitly requested delete.
+Create reuses a document with the same title under the node. Batch upsert accepts 1-20 items and updates `summary` for existing titles. A single-document update changes only supplied fields; send `summary: null` to clear the summary. Current write contracts accept only `title` and `summary`; if input contains `url`, the CLI drops it before sending. Read responses may still contain historical URL data. Inspect a document before an explicitly requested delete.
+
+### Document Sanitization
+
+Before every document write, the CLI removes source-brand labels from `title`, `url`, and `summary`. This applies to document create, batch upsert, single-document update, and documents nested in `products update-knowledge-tree`. URL filtering remains a permanent compatibility rule even though the current API drops URL from write payloads.
+
+Removed forms include:
+
+- `小荷`
+- `小荷医疗`, including whitespace between `小荷` and `医疗`
+- `小荷AI医生` with arbitrary whitespace, including `小荷 AI 医生`, `小荷 AI医生`, and `小荷AI 医生`
+
+Whitespace is normalized after removal, and leading or trailing title separators are removed. If a supplied title becomes empty, the CLI returns `validation_error` without sending the request.
 
 List generation tasks:
 
 ```bash
-node src/cli.js gen-tasks list \
+viatris-exam gen-tasks list \
   --status generating \
   --limit 20 \
   --compact
@@ -214,7 +252,7 @@ node src/cli.js gen-tasks list \
 Get one generation task:
 
 ```bash
-node src/cli.js gen-tasks get "$TASK_ID" --compact
+viatris-exam gen-tasks get "$TASK_ID" --compact
 ```
 
 For a leaf-node task, `knowledgeContext` is the mandatory target context. For a product-wide task, `dimension` is `all`, `knowledgeContext` is null, and `knowledgeContexts` contains every leaf context. Generate `questionsPerNode` questions for every listed context and follow all returned `rules`.
@@ -224,7 +262,7 @@ Each rule has `scope` and `products`. For `scope: "product"`, `products` contain
 Submit generated questions:
 
 ```bash
-node src/cli.js gen-tasks submit "$TASK_ID" --input payload.json --compact
+viatris-exam gen-tasks submit "$TASK_ID" --input payload.json --compact
 ```
 
 Payload shape:
@@ -295,13 +333,13 @@ Omit `knowledgeNodeId` for ordinary tasks. For a product-wide task it is require
 Get a submitted exam record and its frozen answers:
 
 ```bash
-node src/cli.js exam-records get "$RECORD_ID" --compact
+viatris-exam 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
+viatris-exam 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.
@@ -309,13 +347,13 @@ The response includes the scoring `taskId`, `schemaVersion`, frozen question ver
 Get a scoring task:
 
 ```bash
-node src/cli.js scoring get "$TASK_ID" --compact
+viatris-exam scoring get "$TASK_ID" --compact
 ```
 
 Submit scoring results:
 
 ```bash
-node src/cli.js scoring submit "$TASK_ID" --input results.json --compact
+viatris-exam scoring submit "$TASK_ID" --input results.json --compact
 ```
 
 Payload shape:
@@ -347,7 +385,7 @@ For V2, submit exactly one `pointJudgement` per scoring point. IDs must match th
 Create an exam:
 
 ```bash
-node src/cli.js exams create --input exam.json --compact
+viatris-exam 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.
@@ -355,7 +393,7 @@ Required top-level fields are `name`, `product`, `questionCount`, `startAt`, `en
 Create questions directly:
 
 ```bash
-node src/cli.js questions create --input questions.json --compact
+viatris-exam 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`.
@@ -365,7 +403,7 @@ The API has partial-success semantics: inspect `accepted`, `duplicates`, and eve
 Add a question version:
 
 ```bash
-node src/cli.js questions version "$QUESTION_ID" --input version.json --compact
+viatris-exam 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`.
@@ -373,7 +411,7 @@ Required fields are `stem`, `referenceAnswer`, nonempty `scoringPoints`, `eviden
 Search medical evidence:
 
 ```bash
-node src/cli.js medical-search search "阿托伐他汀 适应症" \
+viatris-exam medical-search search "阿托伐他汀 适应症" \
   --file-type drug \
   --limit 20 \
   --max-length 1200 \
@@ -384,7 +422,7 @@ Or use JSON:
 
 ```bash
 printf '%s' '{"query":"阿托伐他汀 适应症","limit":20}' |
-  node src/cli.js medical-search search --compact
+  viatris-exam medical-search search --compact
 ```
 
 Do not combine query flags with JSON input. `limit` accepts 1-20 and defaults to 20 when omitted. `maxLength` defaults to 1200.
@@ -396,10 +434,10 @@ The response `rawJson` is already a structured object. Read `rawJson.documents`
 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
+viatris-exam questions create --input payload.json
+viatris-exam questions create --input - < payload.json
+viatris-exam questions create --json '{"items":[]}'
+printf '%s' '{"items":[]}' | viatris-exam questions create
 ```
 
 The top-level JSON value must be an object.

package/src/app.js

@@ -1,6 +1,11 @@
-import { assertNoExtraPositionals, parseArgs } from "./args.js";
+import {
+  assertNoExtraPositionals,
+  assertOptions,
+  parseArgs,
+} from "./args.js";
 import { resolveCommand } from "./commands.js";
 import { configFrom } from "./config.js";
+import { loginWithEnvironmentKey } from "./credentials.js";
 import { helpText } from "./help.js";
 import { request } from "./http.js";
 import { describeCli, VERSION } from "./metadata.js";
@@ -28,9 +33,16 @@ export async function run(
     writeJson(stdout, describeCli(), options.compact);
     return;
   }
+  if (positionals[0] === "login") {
+    assertNoExtraPositionals(positionals, 1);
+    assertOptions(options);
+    const result = await loginWithEnvironmentKey(environmentVariables);
+    writeJson(stdout, result, options.compact);
+    return;
+  }
 
   const command = await resolveCommand(positionals, options);
-  const config = configFrom(options, environmentVariables);
+  const config = await configFrom(options, environmentVariables);
   const response = await request(command, config);
   writeJson(stdout, response, options.compact);
 }

package/src/command-handlers/knowledge.js

@@ -4,10 +4,23 @@ import {
   requiredId,
 } from "../args.js";
 import { readJsonInput } from "../input.js";
-
-function jsonCommand(method, path, options) {
+import {
+  sanitizeDocumentBatchPayload,
+  sanitizeDocumentPayload,
+} from "../sanitizers/documents.js";
+
+async function jsonCommand(
+  method,
+  path,
+  options,
+  transform = (body) => body,
+) {
   assertOptions(options, ["input", "json"]);
-  return readJsonInput(options).then((body) => ({ method, path, body }));
+  return {
+    method,
+    path,
+    body: transform(await readJsonInput(options)),
+  };
 }
 
 function nodePath(positionals, label) {
@@ -96,6 +109,7 @@ export async function resolveKnowledge(positionals, options) {
       "POST",
       `/openapi/knowledge/nodes/${id}/documents`,
       options,
+      sanitizeDocumentPayload,
     );
   }
 
@@ -106,6 +120,7 @@ export async function resolveKnowledge(positionals, options) {
       "PUT",
       `/openapi/knowledge/nodes/${id}/documents`,
       options,
+      sanitizeDocumentBatchPayload,
     );
   }
 
@@ -116,6 +131,7 @@ export async function resolveKnowledge(positionals, options) {
       "PUT",
       `/openapi/knowledge/documents/${id}`,
       options,
+      sanitizeDocumentPayload,
     );
   }
 

package/src/command-handlers/products.js

@@ -4,6 +4,7 @@ import {
   requiredId,
 } from "../args.js";
 import { readJsonInput } from "../input.js";
+import { sanitizeKnowledgeTreePayload } from "../sanitizers/documents.js";
 
 export async function resolveProducts(positionals, options) {
   const [resource, action] = positionals;
@@ -50,7 +51,7 @@ export async function resolveProducts(positionals, options) {
     return {
       method: "PUT",
       path: `/openapi/products/${id}/knowledge-tree`,
-      body: await readJsonInput(options),
+      body: sanitizeKnowledgeTreePayload(await readJsonInput(options)),
     };
   }
 

package/src/config.js

@@ -1,4 +1,5 @@
 import { integerOption } from "./args.js";
+import { readStoredApiKey } from "./credentials.js";
 import { CliError } from "./errors.js";
 import {
   API_ENVIRONMENT_ALIASES,
@@ -7,7 +8,10 @@ import {
   DEFAULT_TIMEOUT_MS,
 } from "./metadata.js";
 
-export function configFrom(options, environmentVariables = process.env) {
+export async function configFrom(
+  options,
+  environmentVariables = process.env,
+) {
   const baseUrlOverride =
     options.base_url ?? environmentVariables.VIATRIS_API_BASE_URL;
   let environment = null;
@@ -28,13 +32,16 @@ export function configFrom(options, environmentVariables = process.env) {
     baseUrl = API_ENVIRONMENTS[environment];
   }
 
-  const apiKey = environmentVariables.VIATRIS_API_KEY;
+  const storedApiKey = await readStoredApiKey(environmentVariables);
+  const apiKey = storedApiKey ?? environmentVariables.VIATRIS_API_KEY;
   const keyHeader =
     options.key_header ??
     environmentVariables.VIATRIS_API_KEY_HEADER ??
-    "X-API-Key";
+    "Authorization";
   const keyPrefix =
-    options.key_prefix ?? environmentVariables.VIATRIS_API_KEY_PREFIX ?? "";
+    options.key_prefix ??
+    environmentVariables.VIATRIS_API_KEY_PREFIX ??
+    "Bearer ";
   const timeoutMs = integerOption(
     options.timeout ?? String(DEFAULT_TIMEOUT_MS),
     "timeout",
@@ -63,9 +70,11 @@ export function configFrom(options, environmentVariables = process.env) {
     );
   }
   if (!apiKey) {
-    throw new CliError("config_error", "VIATRIS_API_KEY is required.", {
-      exitCode: 3,
-    });
+    throw new CliError(
+      "config_error",
+      "API key not found. Run `viatris-exam login` with VIATRIS_API_KEY set, or set VIATRIS_API_KEY for this request.",
+      { exitCode: 3 },
+    );
   }
   if (!/^[A-Za-z0-9-]+$/.test(keyHeader)) {
     throw new CliError("config_error", "API key header name is invalid.", {
@@ -77,6 +86,7 @@ export function configFrom(options, environmentVariables = process.env) {
     baseUrl: baseUrl.replace(/\/+$/, ""),
     environment,
     apiKey,
+    apiKeySource: storedApiKey === null ? "environment" : "credential_file",
     keyHeader,
     keyPrefix,
     timeoutMs,

package/src/credentials.js

@@ -0,0 +1,100 @@
+import {
+  chmod,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { CliError } from "./errors.js";
+
+export const CREDENTIAL_FILE_DISPLAY =
+  "~/.viatris-exam/.credentials.json";
+
+export function credentialFilePath(environmentVariables = process.env) {
+  const home = environmentVariables.HOME || homedir();
+  return join(home, ".viatris-exam", ".credentials.json");
+}
+
+export async function readStoredApiKey(
+  environmentVariables = process.env,
+) {
+  const path = credentialFilePath(environmentVariables);
+  let content;
+  try {
+    content = await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw new CliError(
+      "config_error",
+      `Unable to read the credential file: ${error.message}`,
+      { exitCode: 3, details: { credentialFile: path } },
+    );
+  }
+
+  try {
+    const credentials = JSON.parse(content);
+    if (
+      credentials === null ||
+      typeof credentials !== "object" ||
+      typeof credentials.apiKey !== "string" ||
+      !credentials.apiKey
+    ) {
+      throw new Error("apiKey is missing or invalid");
+    }
+    return credentials.apiKey;
+  } catch (error) {
+    throw new CliError(
+      "config_error",
+      `Invalid credential file: ${error.message}`,
+      { exitCode: 3, details: { credentialFile: path } },
+    );
+  }
+}
+
+export async function loginWithEnvironmentKey(
+  environmentVariables = process.env,
+) {
+  const apiKey = environmentVariables.VIATRIS_API_KEY;
+  if (!apiKey) {
+    throw new CliError(
+      "config_error",
+      "VIATRIS_API_KEY is required for login.",
+      { exitCode: 3 },
+    );
+  }
+
+  const path = credentialFilePath(environmentVariables);
+  const directory = dirname(path);
+  const temporaryPath = join(
+    directory,
+    `.credentials.${process.pid}.${Date.now()}.tmp`,
+  );
+
+  try {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    await writeFile(
+      temporaryPath,
+      `${JSON.stringify({ version: 1, apiKey }, null, 2)}\n`,
+      { encoding: "utf8", mode: 0o600 },
+    );
+    await rename(temporaryPath, path);
+    await chmod(path, 0o600);
+  } catch (error) {
+    await rm(temporaryPath, { force: true });
+    throw new CliError(
+      "config_error",
+      `Unable to save the credential file: ${error.message}`,
+      { exitCode: 3, details: { credentialFile: path } },
+    );
+  }
+
+  return {
+    status: "saved",
+    credentialFile: path,
+    permissions: "0600",
+  };
+}

package/src/help.js

@@ -5,9 +5,11 @@ export function helpText() {
 
 Usage:
   viatris-exam <resource> <action> [id|query] [options]
+  viatris-exam login
   viatris-exam describe
 
 Commands:
+  login
   products list
   products create --input <file|->
   products get <product-id>
@@ -48,8 +50,8 @@ Medical search:
 
 Global options:
   --base-url <url>       Override the selected environment URL.
-  --key-header <name>    Override VIATRIS_API_KEY_HEADER (default: X-API-Key).
-  --key-prefix <value>   Override VIATRIS_API_KEY_PREFIX (default: empty).
+  --key-header <name>    Override the auth header (default: Authorization).
+  --key-prefix <value>   Override the auth prefix (default: "Bearer ").
   --timeout <ms>         Request timeout (default: 30000).
   --retries <n>          GET retries for 429/5xx/network errors (default: 2).
   --compact              Emit compact JSON.
@@ -59,9 +61,12 @@ Global options:
 Environment:
   VIATRIS_API_ENV        API environment: production (default) or development.
   VIATRIS_API_BASE_URL   Optional URL override with highest priority.
-  VIATRIS_API_KEY        Required API key. It cannot be passed as a CLI argument.
+  VIATRIS_API_KEY        Login input or fallback key when no saved key exists.
   VIATRIS_API_KEY_HEADER Optional authentication header name.
-  VIATRIS_API_KEY_PREFIX Optional header value prefix, for example "Bearer ".
+  VIATRIS_API_KEY_PREFIX Optional authentication header value prefix.
+
+Credentials:
+  ~/.viatris-exam/.credentials.json (read before VIATRIS_API_KEY, mode 0600)
 
 Agent contract:
   Successful API JSON is written to stdout. Structured errors are written to

package/src/metadata.js

@@ -1,4 +1,7 @@
-export const VERSION = "1.6.0";
+import { CREDENTIAL_FILE_DISPLAY } from "./credentials.js";
+import { DOCUMENT_SANITIZATION_POLICY } from "./sanitizers/documents.js";
+
+export const VERSION = "1.8.1";
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const DEFAULT_RETRIES = 2;
 
@@ -15,6 +18,12 @@ export const API_ENVIRONMENT_ALIASES = Object.freeze({
 });
 
 export const COMMANDS = Object.freeze([
+  {
+    command: "login",
+    local: true,
+    input: "VIATRIS_API_KEY environment variable",
+    summary: "Save the API key to the local hidden credential file.",
+  },
   {
     command: "products list",
     method: "GET",
@@ -113,7 +122,7 @@ export const COMMANDS = Object.freeze([
     command: "knowledge documents create <node-id>",
     method: "POST",
     path: "/openapi/knowledge/nodes/{id}/documents",
-    input: "{title, url?, summary?}",
+    input: "{title, summary?}",
     summary: "Idempotently create a document under a node.",
   },
   {
@@ -127,7 +136,7 @@ export const COMMANDS = Object.freeze([
     command: "knowledge documents update <document-id>",
     method: "PUT",
     path: "/openapi/knowledge/documents/{id}",
-    input: "{title?, url?, summary?}",
+    input: "{title?, summary?}",
     summary: "Update supplied fields on a knowledge document.",
   },
   {
@@ -235,7 +244,10 @@ export function describeCli() {
     authentication: {
       keyEnvironmentVariable: "VIATRIS_API_KEY",
       baseUrlEnvironmentVariable: "VIATRIS_API_BASE_URL",
-      defaultHeader: "X-API-Key",
+      defaultHeader: "Authorization",
+      defaultPrefix: "Bearer ",
+      credentialFile: CREDENTIAL_FILE_DISPLAY,
+      keySourcePriority: ["credential_file", "environment"],
     },
     environments: {
       environmentVariable: "VIATRIS_API_ENV",
@@ -244,6 +256,7 @@ export function describeCli() {
       urls: API_ENVIRONMENTS,
       baseUrlOverrideEnvironmentVariable: "VIATRIS_API_BASE_URL",
     },
+    documentSanitization: DOCUMENT_SANITIZATION_POLICY,
     commands: COMMANDS,
     exitCodes: EXIT_CODES,
   };

package/src/sanitizers/documents.js

@@ -0,0 +1,113 @@
+import { CliError } from "../errors.js";
+
+export const DOCUMENT_SANITIZATION_POLICY = Object.freeze({
+  fields: ["title", "url", "summary"],
+  writableFields: ["title", "summary"],
+  droppedWriteFields: ["url"],
+  removedLabels: [
+    "小荷",
+    "小荷医疗",
+    "小荷AI医生（AI 与医生之间允许任意空格）",
+  ],
+  appliesTo: [
+    "products update-knowledge-tree",
+    "knowledge documents create",
+    "knowledge documents upsert",
+    "knowledge documents update",
+  ],
+  emptyTitle: "validation_error",
+});
+
+const PROHIBITED_LABEL = /小荷\s*(?:AI\s*医生|医疗)?/giu;
+const TITLE_EDGE_SEPARATOR = /^[\s\-—–_:：|｜·]+|[\s\-—–_:：|｜·]+$/gu;
+
+function sanitizeText(value) {
+  return value
+    .replace(PROHIBITED_LABEL, "")
+    .replace(/[ \t]{2,}/g, " ")
+    .trim();
+}
+
+function sanitizeTitle(value) {
+  return sanitizeText(value).replace(TITLE_EDGE_SEPARATOR, "").trim();
+}
+
+export function sanitizeDocument(document, location = "document") {
+  if (
+    document === null ||
+    Array.isArray(document) ||
+    typeof document !== "object"
+  ) {
+    return document;
+  }
+
+  const sanitized = { ...document };
+  if (typeof sanitized.title === "string") {
+    sanitized.title = sanitizeTitle(sanitized.title);
+    if (!sanitized.title) {
+      throw new CliError(
+        "validation_error",
+        `${location}.title is empty after prohibited source labels are removed.`,
+      );
+    }
+  }
+  for (const field of ["url", "summary"]) {
+    if (typeof sanitized[field] === "string") {
+      sanitized[field] = sanitizeText(sanitized[field]);
+    }
+  }
+  return sanitized;
+}
+
+function prepareDocumentForWrite(document, location) {
+  const sanitized = sanitizeDocument(document, location);
+  if (
+    sanitized === null ||
+    Array.isArray(sanitized) ||
+    typeof sanitized !== "object"
+  ) {
+    return sanitized;
+  }
+  const { url: _unsupportedUrl, ...writableDocument } = sanitized;
+  return writableDocument;
+}
+
+export function sanitizeDocumentPayload(body) {
+  return prepareDocumentForWrite(body, "document");
+}
+
+export function sanitizeDocumentBatchPayload(body) {
+  if (!Array.isArray(body.items)) return body;
+  return {
+    ...body,
+    items: body.items.map((document, index) =>
+      prepareDocumentForWrite(document, `items[${index}]`),
+    ),
+  };
+}
+
+export function sanitizeKnowledgeTreePayload(body) {
+  if (!Array.isArray(body.nodes)) return body;
+  return {
+    ...body,
+    nodes: body.nodes.map((node, nodeIndex) => {
+      if (
+        node === null ||
+        Array.isArray(node) ||
+        typeof node !== "object" ||
+        !Array.isArray(node.documents)
+      ) {
+        return node;
+      }
+      return {
+        ...node,
+        documents: node.documents.map((document, documentIndex) =>
+          prepareDocumentForWrite(
+            document,
+            `nodes[${nodeIndex}].documents[${documentIndex}]`,
+          ),
+        ),
+      };
+    }),
+  };
+}