viatris-exam-cli 1.6.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 不自动重试。
@@ -114,6 +118,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 +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`。
 
 ## 项目结构
 
@@ -217,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.6.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.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.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,6 +22,7 @@ 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`.
+- 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 +30,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

@@ -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
@@ -126,7 +135,6 @@ Payload shape:
       "documents": [
         {
           "title": "药品说明书",
-          "url": "https://example.com/source",
           "summary": "与该知识点直接对应的证据摘录"
         }
       ]
@@ -190,15 +198,27 @@ 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/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.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",
@@ -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}]`,
+          ),
+        ),
+      };
+    }),
+  };
+}