viatris-exam-cli 1.5.0 → 1.8.0

package/README.md

@@ -7,6 +7,8 @@
 ```bash
 npm link
 export VIATRIS_API_KEY="replace-with-real-key"
+viatris-exam login
+unset VIATRIS_API_KEY
 ```
 
 默认连接线上环境：
@@ -29,25 +31,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 不自动重试。
@@ -77,9 +81,10 @@ viatris-exam describe --compact
 ```bash
 viatris-exam products list
 viatris-exam products create --input product.json
+viatris-exam products update "$PRODUCT_ID" --input verified-medical-data.json
 ```
 
-创建产品时必须提供全局唯一的 `code`、中文名称 `name` 和英文名称 `nameEn`，并会同步初始化规范知识树根节点。创建请求不会自动重试；网络结果不确定时，应先按列表中的稳定编码确认是否已创建。
+创建产品时仅中文名称 `name` 必填；`code` 和 `nameEn` 可省略，省略 `code` 时由服务端生成。创建会同步初始化规范知识树根节点。更新命令仅用于补充经资料核验的英文名、通用名、适应症、剂型规格和备注。
 
 ### 产品知识树
 
@@ -87,9 +92,10 @@ viatris-exam products create --input product.json
 viatris-exam products get "$PRODUCT_ID"
 viatris-exam products update-knowledge-tree "$PRODUCT_ID" \
   --input knowledge-tree.json
+viatris-exam products delete-knowledge-tree "$PRODUCT_ID"
 ```
 
-产品主数据不属于业务知识树层级；详情查询使用产品主数据 ID，并兼容历史知识树根节点 ID。固定维度为 L1；知识树回写是完整替换操作，必须一次提交全部 15-500 个 L2/L3/L4 动态节点。先查询产品以获取固定 L1 维度的 `clientRef`。
+产品主数据不属于业务知识树层级；详情查询使用产品主数据 ID，并兼容历史知识树根节点 ID。固定维度为 L1；知识树回写是完整替换操作，必须一次提交全部 15-500 个 L2/L3/L4 动态节点。整树删除会保留产品根和固定维度，但级联删除动态节点及文档并解绑题目，只能在明确要求时执行。
 
 ### 知识节点与文档
 
@@ -100,7 +106,7 @@ viatris-exam knowledge nodes create --input node.json
 viatris-exam knowledge nodes get <node-id>
 viatris-exam knowledge nodes update <node-id> --input changes.json
 viatris-exam knowledge nodes move <node-id> --input move.json
-viatris-exam knowledge nodes delete <node-id>
+viatris-exam knowledge nodes delete <node-id> [--recursive]
 viatris-exam knowledge documents list <node-id>
 viatris-exam knowledge documents create <node-id> --input document.json
 viatris-exam knowledge documents upsert <node-id> --input documents.json
@@ -108,10 +114,12 @@ viatris-exam knowledge documents update <document-id> --input changes.json
 viatris-exam knowledge documents delete <document-id>
 ```
 
-节点删除会级联删除整棵子树及文档。产品根和固定维度受保护，不能改名、移动或删除。
+节点删除默认在存在子节点或题目绑定时返回冲突；`--recursive` 才会级联删除整棵子树及文档并解绑题目。产品根和固定维度受保护，不能改名、移动或删除。
 
 `/knowledge` CRUD 响应中的 `level` 是物理存储层级（产品根为 1、固定维度为 2）；产品生成接口使用业务层级（产品隐藏、固定维度为 L1、动态节点为 L2-L4）。
 
+所有文档写入都会在请求发出前从 `title`、`url`、`summary` 中移除“小荷”“小荷医疗”和“小荷 AI 医生”及其空格变体。当前写接口只接受 `title` 和 `summary`，输入中的 `url` 会在净化后从出站载荷移除，但 URL 净化能力作为永久兼容规则保留。该规则覆盖文档创建、批量 upsert、单文档更新和整树回写中的嵌套文档；标题清洗后为空会直接返回校验错误。
+
 ### 出题任务
 
 ```bash
@@ -194,14 +202,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`。
 
 ## 项目结构
 
@@ -215,7 +223,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.5.0",
+  "version": "1.8.0",
   "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,7 +1,7 @@
 ---
 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.5.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.0
 ---
 
 # Viatris Exam CLI
@@ -11,7 +11,7 @@ Use the repository-local CLI for every supported API operation. Do not call the
 ## 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.
+2. Prefer the saved credential. To initialize or rotate it, set `VIATRIS_API_KEY` and run `node src/cli.js login`; never place the key in command arguments, 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.
@@ -22,12 +22,17 @@ Use the repository-local CLI for every supported API operation. Do not call the
 - 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`.
-- Use `products list` to resolve product master IDs and stable codes before product-specific workflows. `products create` also initializes the canonical knowledge-tree root.
+- 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.
 - For product-wide generation tasks, create one or more questions for every entry in `knowledgeContexts` and include its `knowledgeNodeId`.
 - 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

@@ -2,12 +2,21 @@
 
 ## Authentication And Environment
 
-Required:
+Login once:
 
 ```bash
 export VIATRIS_API_KEY="..."
+node src/cli.js 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,17 +26,17 @@ 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
@@ -48,15 +57,13 @@ List product master data:
 node src/cli.js products list --compact
 ```
 
-The response is `{ "items": [...] }`, ordered by `sortOrder` and then name. Each record includes the stable `code`, Chinese and English names, optional generic name, indication, dosage form, `active` or `inactive` status, remark, and timestamps.
+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.
 
 Create a product and initialize its canonical knowledge-tree root:
 
 ```bash
 node src/cli.js products create --json '{
-  "code": "norvasc",
   "name": "络活喜",
-  "nameEn": "Norvasc",
   "genericName": "苯磺酸氨氯地平片",
   "indication": "高血压、冠心病",
   "dosageForm": "片剂",
@@ -65,7 +72,7 @@ node src/cli.js products create --json '{
 }'
 ```
 
-`code`, `name`, and `nameEn` are required. The code must contain only lowercase letters, digits, and hyphens and must be globally unique. The Chinese name must also be unique. Omitted `sortOrder` defaults to 0. This POST is not automatically retried; after an uncertain network outcome, list products and resolve by code before attempting another create.
+Only `name` is required and the Chinese name must be unique. `code` is optional; when supplied it must contain only lowercase letters, digits, and hyphens and be globally unique, while omission lets the server generate it. `nameEn` and the remaining fields are optional. Omitted `sortOrder` defaults to 0. This POST is not automatically retried; after an uncertain network outcome, list products and resolve by name or code before attempting another create.
 
 Get a product and its fixed L1 dimensions:
 
@@ -73,7 +80,21 @@ Get a product and its fixed L1 dimensions:
 node src/cli.js products get "$PRODUCT_ID" --compact
 ```
 
-Use the product master `id`; historical knowledge-tree root IDs remain accepted for compatibility. 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`.
+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`.
+
+Update verified optional medical master data:
+
+```bash
+node src/cli.js products update "$PRODUCT_ID" --json '{
+  "nameEn": "Lipitor",
+  "genericName": "阿托伐他汀钙片",
+  "indication": "高胆固醇血症、混合型血脂异常及心血管疾病预防",
+  "dosageForm": "片剂 10mg/20mg/40mg",
+  "remark": "生产企业：辉瑞制药有限公司"
+}'
+```
+
+Only supplied fields are updated. Each supplied value must be a nonempty string within the API length limit. Update these fields only from verified source material; this endpoint does not update `code`, Chinese `name`, status, or sort order.
 
 Replace a product knowledge tree:
 
@@ -114,7 +135,6 @@ Payload shape:
       "documents": [
         {
           "title": "药品说明书",
-          "url": "https://example.com/source",
           "summary": "与该知识点直接对应的证据摘录"
         }
       ]
@@ -125,6 +145,14 @@ Payload shape:
 
 Submit the complete L2/L3/L4 node set, between 15 and 500 nodes. Every `clientRef` must be unique within the payload. L2 nodes use `dimension:<code>` as `parentClientRef`; L3/L4 nodes use their direct parent's `clientRef`. Every L4 node needs at least one document. A successful PUT replaces the previous dynamic nodes, so do not send a partial tree.
 
+Delete all dynamic knowledge-tree content:
+
+```bash
+node src/cli.js 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.
+
 ### Incremental Knowledge Management
 
 Get the complete physical tree and all product documents:
@@ -160,24 +188,37 @@ node src/cli.js knowledge nodes update "$NODE_ID" \
 node src/cli.js 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
 ```
 
-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. Deleting a node deletes its entire subtree and attached documents; inspect the node first and only delete when explicitly required.
+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.
 
 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":"摘录"}'
+  --json '{"title":"说明书","summary":"摘录"}'
 node src/cli.js knowledge documents upsert "$NODE_ID" \
   --json '{"items":[{"title":"说明书","summary":"更新后的摘录"}]}'
 node src/cli.js knowledge documents update "$DOCUMENT_ID" \
-  --json '{"url":null,"summary":"更新后的摘要"}'
+  --json '{"summary":"更新后的摘要"}'
 node src/cli.js 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:
 

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/args.js

@@ -1,6 +1,6 @@
 import { CliError } from "./errors.js";
 
-const BOOLEAN_OPTIONS = new Set(["help", "compact", "version"]);
+const BOOLEAN_OPTIONS = new Set(["help", "compact", "version", "recursive"]);
 const GLOBAL_OPTIONS = [
   "base_url",
   "key_header",

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) {
@@ -61,9 +74,12 @@ export async function resolveKnowledge(positionals, options) {
 
   if (area === "nodes" && action === "delete") {
     assertNoExtraPositionals(positionals, 4);
-    assertOptions(options);
+    assertOptions(options, ["recursive"]);
     const id = nodePath(positionals, "knowledge node ID");
-    return { method: "DELETE", path: `/openapi/knowledge/nodes/${id}` };
+    return {
+      method: "DELETE",
+      path: `/openapi/knowledge/nodes/${id}${options.recursive ? "?recursive=true" : ""}`,
+    };
   }
 
   if (area === "nodes" && action === "move") {
@@ -93,6 +109,7 @@ export async function resolveKnowledge(positionals, options) {
       "POST",
       `/openapi/knowledge/nodes/${id}/documents`,
       options,
+      sanitizeDocumentPayload,
     );
   }
 
@@ -103,6 +120,7 @@ export async function resolveKnowledge(positionals, options) {
       "PUT",
       `/openapi/knowledge/nodes/${id}/documents`,
       options,
+      sanitizeDocumentBatchPayload,
     );
   }
 
@@ -113,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;
@@ -32,6 +33,17 @@ export async function resolveProducts(positionals, options) {
     return { method: "GET", path: `/openapi/products/${id}` };
   }
 
+  if (action === "update") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options, ["input", "json"]);
+    const id = requiredId(positionals, 2, "product ID");
+    return {
+      method: "PATCH",
+      path: `/openapi/products/${id}`,
+      body: await readJsonInput(options),
+    };
+  }
+
   if (action === "update-knowledge-tree") {
     assertNoExtraPositionals(positionals, 3);
     assertOptions(options, ["input", "json"]);
@@ -39,7 +51,17 @@ export async function resolveProducts(positionals, options) {
     return {
       method: "PUT",
       path: `/openapi/products/${id}/knowledge-tree`,
-      body: await readJsonInput(options),
+      body: sanitizeKnowledgeTreePayload(await readJsonInput(options)),
+    };
+  }
+
+  if (action === "delete-knowledge-tree") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options);
+    const id = requiredId(positionals, 2, "product ID");
+    return {
+      method: "DELETE",
+      path: `/openapi/products/${id}/knowledge-tree`,
     };
   }
 

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,19 +5,23 @@ 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>
+  products update <product-id> --input <file|->
   products update-knowledge-tree <product-id> --input <file|->
+  products delete-knowledge-tree <product-id>
   knowledge tree <product-code>
   knowledge nodes by-path --input <file|->
   knowledge nodes create --input <file|->
   knowledge nodes get <node-id>
   knowledge nodes update <node-id> --input <file|->
-  knowledge nodes delete <node-id>
+  knowledge nodes delete <node-id> [--recursive]
   knowledge nodes move <node-id> --input <file|->
   knowledge documents list <node-id>
   knowledge documents create <node-id> --input <file|->
@@ -46,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.
@@ -57,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.5.0";
+import { CREDENTIAL_FILE_DISPLAY } from "./credentials.js";
+import { DOCUMENT_SANITIZATION_POLICY } from "./sanitizers/documents.js";
+
+export const VERSION = "1.8.0";
 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",
@@ -25,7 +34,7 @@ export const COMMANDS = Object.freeze([
     command: "products create",
     method: "POST",
     path: "/openapi/products",
-    input: "{code, name, nameEn, genericName?, indication?, dosageForm?, sortOrder?, remark?}",
+    input: "{name, code?, nameEn?, genericName?, indication?, dosageForm?, sortOrder?, remark?}",
     summary: "Create a product and initialize its canonical knowledge-tree root.",
   },
   {
@@ -34,6 +43,13 @@ export const COMMANDS = Object.freeze([
     path: "/openapi/products/{id}",
     summary: "Get a product, knowledge-tree status, and fixed dimensions.",
   },
+  {
+    command: "products update <product-id>",
+    method: "PATCH",
+    path: "/openapi/products/{id}",
+    input: "{nameEn?, genericName?, indication?, dosageForm?, remark?}",
+    summary: "Update verified optional medical product master data.",
+  },
   {
     command: "products update-knowledge-tree <product-id>",
     method: "PUT",
@@ -41,6 +57,12 @@ export const COMMANDS = Object.freeze([
     input: "{nodes: [...]}",
     summary: "Replace the product's dynamic L2/L3/L4 knowledge-tree nodes.",
   },
+  {
+    command: "products delete-knowledge-tree <product-id>",
+    method: "DELETE",
+    path: "/openapi/products/{id}/knowledge-tree",
+    summary: "Delete all dynamic product knowledge-tree nodes and documents.",
+  },
   {
     command: "knowledge tree <product-code>",
     method: "GET",
@@ -78,7 +100,10 @@ export const COMMANDS = Object.freeze([
     command: "knowledge nodes delete <node-id>",
     method: "DELETE",
     path: "/openapi/knowledge/nodes/{id}",
-    summary: "Delete a knowledge node, its subtree, and documents.",
+    options: {
+      "--recursive": "delete descendants, documents, and node bindings",
+    },
+    summary: "Delete a node, optionally recursing through its subtree.",
   },
   {
     command: "knowledge nodes move <node-id>",
@@ -97,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.",
   },
   {
@@ -111,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.",
   },
   {
@@ -219,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",
@@ -228,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}]`,
+          ),
+        ),
+      };
+    }),
+  };
+}