viatris-exam-cli 1.8.0 → 1.9.0

package/README.md

@@ -5,12 +5,19 @@
 ## 安装
 
 ```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
+```
+
 默认连接线上环境：
 
 ```text
@@ -95,7 +102,7 @@ viatris-exam products update-knowledge-tree "$PRODUCT_ID" \
 viatris-exam products delete-knowledge-tree "$PRODUCT_ID"
 ```
 
-产品主数据不属于业务知识树层级；详情查询使用产品主数据 ID，并兼容历史知识树根节点 ID。固定维度为 L1；知识树回写是完整替换操作，必须一次提交全部 15-500 个 L2/L3/L4 动态节点。整树删除会保留产品根和固定维度，但级联删除动态节点及文档并解绑题目，只能在明确要求时执行。
+产品主数据不属于业务知识树层级；详情、整树回写和整树删除均接受产品编码、产品主数据 ID 或历史知识树根节点 ID，推荐使用稳定的产品编码。固定维度为 L1；知识树回写是完整替换操作，必须一次提交全部 15-500 个 L2/L3/L4 动态节点。整树删除会保留产品根和固定维度，但级联删除动态节点及文档并解绑题目，只能在明确要求时执行。
 
 ### 知识节点与文档
 
@@ -111,6 +118,9 @@ 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
 viatris-exam knowledge documents update <document-id> --input changes.json
+viatris-exam knowledge documents get <document-id>
+viatris-exam knowledge documents link <node-id> <document-id> --input reference.json
+viatris-exam knowledge documents unlink <node-id> <document-id>
 viatris-exam knowledge documents delete <document-id>
 ```
 
@@ -118,7 +128,9 @@ viatris-exam knowledge documents delete <document-id>
 
 `/knowledge` CRUD 响应中的 `level` 是物理存储层级（产品根为 1、固定维度为 2）；产品生成接口使用业务层级（产品隐藏、固定维度为 L1、动态节点为 L2-L4）。
 
-所有文档写入都会在请求发出前从 `title`、`url`、`summary` 中移除“小荷”“小荷医疗”和“小荷 AI 医生”及其空格变体。当前写接口只接受 `title` 和 `summary`，输入中的 `url` 会在净化后从出站载荷移除，但 URL 净化能力作为永久兼容规则保留。该规则覆盖文档创建、批量 upsert、单文档更新和整树回写中的嵌套文档；标题清洗后为空会直接返回校验错误。
+知识原文以产品级文档保存，L4 节点通过 `documentRefs` 引用文档，并可携带必须为原文逐字子串的 `markedExcerpts`。关联与解除关联只改变节点引用，不删除文档本体。
+
+所有文档写入都会在请求发出前从 `title`、`url`、`summary`、`content` 和 `markedExcerpts` 中移除“小荷”“小荷医疗”和“小荷 AI 医生”及其空格变体。新版写接口发送 `title`、`url`、`content` 和适用场景下的 `markedExcerpts`；兼容字段 `summary` 仍执行净化，但不再写入新版接口。该规则覆盖文档创建、批量 upsert、单文档更新、文档关联和整树回写；标题或原文清洗后为空会直接返回校验错误。
 
 ### 出题任务
 
@@ -130,7 +142,7 @@ viatris-exam gen-tasks submit "$TASK_ID" --input examples/generated-questions.js
 
 `externalRef` 是题目回写的幂等键。Agent 重试 POST 前应复用原值。
 
-产品全节点任务的 `dimension` 为 `all`。应按 `knowledgeContexts` 覆盖每个叶子节点，并在回写题目时携带对应 `knowledgeNodeId`。
+产品全节点任务的 `dimension` 为 `all`。应按 `knowledgeContexts` 覆盖每个叶子节点，并在回写题目时携带对应 `knowledgeNodeId`。上下文中的证据文档通过 `excerpts` 提供可用于出题的标记片段；未标记时该数组包含完整原文。
 
 ### 考试记录
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viatris-exam-cli",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Agent-friendly CLI for the Viatris exam OpenAPI",
   "type": "module",
   "bin": {

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

@@ -1,24 +1,27 @@
 ---
 name: viatris-exam-cli
 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
+version: 1.9.0
 ---
 
 # Viatris Exam CLI
 
-Use the repository-local CLI for every supported API operation. Do not call the HTTP endpoints directly when the CLI covers the task.
+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. 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.
+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`.
@@ -30,8 +33,9 @@ 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.
+- Store full evidence sources as product-level documents and attach them to L4 nodes through document references. Keep `markedExcerpts` as exact substrings of the referenced `content`.
+- Document writes automatically remove 小荷 source-brand labels, including 小荷医疗 and whitespace variants of 小荷 AI 医生, from title, URL, summary, content, and marked excerpts. Never reintroduce these labels after CLI sanitization.
+- Current document write APIs accept `title`, `url`, `content`, and `markedExcerpts` as applicable. The CLI retains summary sanitization for compatibility but drops an input `summary` from current outbound document payloads.
 - 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,12 +1,30 @@
 # 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
 
 Login once:
 
 ```bash
 export VIATRIS_API_KEY="..."
-node src/cli.js login
+viatris-exam login
 unset VIATRIS_API_KEY
 ```
 
@@ -42,9 +60,9 @@ 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.
@@ -54,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.
@@ -62,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": "高血压、冠心病",
@@ -77,15 +95,15 @@ 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`.
+Product detail, full-tree update, and full-tree deletion accept a stable product code, product master ID, or historical knowledge-tree root ID. Prefer the product code. 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 '{
+viatris-exam products update "$PRODUCT_ID" --json '{
   "nameEn": "Lipitor",
   "genericName": "阿托伐他汀钙片",
   "indication": "高胆固醇血症、混合型血脂异常及心血管疾病预防",
@@ -99,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
 ```
@@ -108,6 +126,14 @@ Payload shape:
 
 ```json
 {
+  "documents": [
+    {
+      "clientRef": "doc.lipitor_pi",
+      "title": "立普妥说明书",
+      "url": "https://example.com/evidence/lipitor.pdf",
+      "content": "阿托伐他汀每日一次，给药剂量为10～80mg。"
+    }
+  ],
   "nodes": [
     {
       "clientRef": "disease.hypertension",
@@ -132,10 +158,12 @@ Payload shape:
       "dimensionCode": "disease",
       "name": "诊断阈值",
       "sortOrder": 1,
-      "documents": [
+      "documentRefs": [
         {
-          "title": "药品说明书",
-          "summary": "与该知识点直接对应的证据摘录"
+          "documentRef": "doc.lipitor_pi",
+          "markedExcerpts": [
+            "阿托伐他汀每日一次，给药剂量为10～80mg"
+          ]
         }
       ]
     }
@@ -143,12 +171,12 @@ 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.
+Submit up to 200 product-level source documents and the complete L2/L3/L4 node set, between 15 and 500 nodes. Every document and node `clientRef` must be unique within its collection. L2 nodes use `dimension:<code>` as `parentClientRef`; L3/L4 nodes use their direct parent's `clientRef`. Only L4 nodes may use `documentRefs`, every L4 node needs at least one reference, and every marked excerpt must be an exact substring of the referenced document content. 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"
+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.
@@ -158,7 +186,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.
@@ -166,7 +194,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 风险评估"]}'
 ```
 
@@ -175,20 +203,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.
@@ -196,21 +224,27 @@ 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":"说明书","summary":"摘录"}'
-node src/cli.js knowledge documents upsert "$NODE_ID" \
-  --json '{"items":[{"title":"说明书","summary":"更新后的摘录"}]}'
-node src/cli.js knowledge documents update "$DOCUMENT_ID" \
-  --json '{"summary":"更新后的摘要"}'
-node src/cli.js knowledge documents delete "$DOCUMENT_ID"
+viatris-exam knowledge documents list "$NODE_ID"
+viatris-exam knowledge documents create "$NODE_ID" \
+  --json '{"title":"说明书","url":"https://example.com/pi.pdf","content":"完整原文","markedExcerpts":["完整原文"]}'
+viatris-exam knowledge documents upsert "$NODE_ID" \
+  --json '{"items":[{"title":"说明书","content":"更新后的完整原文","markedExcerpts":["完整原文"]}]}'
+viatris-exam knowledge documents update "$DOCUMENT_ID" \
+  --json '{"content":"更新后的完整原文"}'
+viatris-exam knowledge documents get "$DOCUMENT_ID"
+viatris-exam knowledge documents link "$NODE_ID" "$DOCUMENT_ID" \
+  --json '{"markedExcerpts":["更新后的完整原文"]}'
+viatris-exam knowledge documents unlink "$NODE_ID" "$DOCUMENT_ID"
+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 `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.
+Documents are product-level source records containing full `content`; nodes hold references to them. Create requires `title` and `content`, reuses a document with the same title, and attaches it to the node. Batch upsert accepts 1-20 items. For an existing title, omitted `content` keeps the stored source, omitted `markedExcerpts` keeps the reference marks, and an empty `markedExcerpts` array clears them. A single-document update changes only supplied `title`, `url`, or `content`; send `url: null` to clear the URL.
+
+`get` returns the full source and every referencing node. `link` attaches an existing document from the same product; its request body is optional. Supplying `markedExcerpts` replaces the existing marks, an empty array clears them, and omission preserves them. `unlink` deletes only the node reference. Inspect references before an explicitly requested document 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.
+Before every document write, the CLI removes source-brand labels from `title`, `url`, `summary`, `content`, and `markedExcerpts`. This applies to document create, batch upsert, single-document update, node links, and product-level documents plus L4 references in `products update-knowledge-tree`. The compatibility `summary` field remains sanitized but is dropped from current outbound document payloads.
 
 Removed forms include:
 
@@ -218,12 +252,12 @@ 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.
+Whitespace is normalized after removal, and leading or trailing title separators are removed. If a supplied title, content, or marked excerpt becomes empty, the CLI returns `validation_error` without sending the request. When source content and excerpts are supplied together, the CLI also verifies every sanitized excerpt remains an exact substring of the sanitized content.
 
 List generation tasks:
 
 ```bash
-node src/cli.js gen-tasks list \
+viatris-exam gen-tasks list \
   --status generating \
   --limit 20 \
   --compact
@@ -234,17 +268,17 @@ 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`.
+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`. Each context document exposes `excerpts`; these are the marked source substrings when marks exist, otherwise the array contains the full source content.
 
 Each rule has `scope` and `products`. For `scope: "product"`, `products` contains one or more applicable product codes. For `scope: "global"`, `products` is an empty array. Do not read the removed single-value `product` field.
 
 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:
@@ -315,13 +349,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.
@@ -329,13 +363,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:
@@ -367,7 +401,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.
@@ -375,7 +409,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`.
@@ -385,7 +419,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`.
@@ -393,7 +427,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 \
@@ -404,7 +438,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.
@@ -416,10 +450,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/command-handlers/knowledge.js

@@ -3,10 +3,11 @@ import {
   assertOptions,
   requiredId,
 } from "../args.js";
-import { readJsonInput } from "../input.js";
+import { readJsonInput, readOptionalJsonInput } from "../input.js";
 import {
   sanitizeDocumentBatchPayload,
   sanitizeDocumentPayload,
+  sanitizeDocumentReferencePayload,
 } from "../sanitizers/documents.js";
 
 async function jsonCommand(
@@ -27,6 +28,16 @@ function nodePath(positionals, label) {
   return requiredId(positionals, 3, label);
 }
 
+async function optionalJsonCommand(method, path, options, transform) {
+  assertOptions(options, ["input", "json"]);
+  const body = await readOptionalJsonInput(options);
+  return {
+    method,
+    path,
+    ...(body === undefined ? {} : { body: transform(body) }),
+  };
+}
+
 export async function resolveKnowledge(positionals, options) {
   const [resource, area, action] = positionals;
   if (resource !== "knowledge") return null;
@@ -135,6 +146,47 @@ export async function resolveKnowledge(positionals, options) {
     );
   }
 
+  if (area === "documents" && action === "get") {
+    assertNoExtraPositionals(positionals, 4);
+    assertOptions(options);
+    const id = nodePath(positionals, "knowledge document ID");
+    return {
+      method: "GET",
+      path: `/openapi/knowledge/documents/${id}`,
+    };
+  }
+
+  if (area === "documents" && action === "link") {
+    assertNoExtraPositionals(positionals, 5);
+    const nodeId = nodePath(positionals, "knowledge node ID");
+    const documentId = requiredId(
+      positionals,
+      4,
+      "knowledge document ID",
+    );
+    return optionalJsonCommand(
+      "PUT",
+      `/openapi/knowledge/nodes/${nodeId}/documents/${documentId}`,
+      options,
+      sanitizeDocumentReferencePayload,
+    );
+  }
+
+  if (area === "documents" && action === "unlink") {
+    assertNoExtraPositionals(positionals, 5);
+    assertOptions(options);
+    const nodeId = nodePath(positionals, "knowledge node ID");
+    const documentId = requiredId(
+      positionals,
+      4,
+      "knowledge document ID",
+    );
+    return {
+      method: "DELETE",
+      path: `/openapi/knowledge/nodes/${nodeId}/documents/${documentId}`,
+    };
+  }
+
   if (area === "documents" && action === "delete") {
     assertNoExtraPositionals(positionals, 4);
     assertOptions(options);

package/src/help.js

@@ -27,6 +27,9 @@ Commands:
   knowledge documents create <node-id> --input <file|->
   knowledge documents upsert <node-id> --input <file|->
   knowledge documents update <document-id> --input <file|->
+  knowledge documents get <document-id>
+  knowledge documents link <node-id> <document-id> [--input <file|->]
+  knowledge documents unlink <node-id> <document-id>
   knowledge documents delete <document-id>
   gen-tasks list [--status STATUS] [--limit N]
   gen-tasks get <task-id>

package/src/input.js

@@ -11,8 +11,7 @@ export function hasPipedInput() {
   return !process.stdin.isTTY;
 }
 
-export async function readJsonInput(options) {
-  const canReadStdin = hasPipedInput();
+async function readJsonSource(options, required) {
   if (options.input !== undefined && options.json !== undefined) {
     throw new CliError("usage_error", "Use only one of --input and --json.");
   }
@@ -25,10 +24,11 @@ export async function readJsonInput(options) {
   } else if (options.json !== undefined) {
     source = "--json";
     text = options.json;
-  } else if (canReadStdin) {
+  } else if (hasPipedInput()) {
     source = "stdin";
     text = await readStdin();
   } else {
+    if (!required) return undefined;
     throw new CliError(
       "usage_error",
       "JSON input is required. Use --input <file>, --input -, --json <value>, or stdin.",
@@ -36,6 +36,7 @@ export async function readJsonInput(options) {
   }
 
   if (!text.trim()) {
+    if (!required && source === "stdin") return undefined;
     throw new CliError("input_error", `JSON input from ${source} is empty.`);
   }
   try {
@@ -51,3 +52,11 @@ export async function readJsonInput(options) {
     );
   }
 }
+
+export async function readJsonInput(options) {
+  return readJsonSource(options, true);
+}
+
+export async function readOptionalJsonInput(options) {
+  return readJsonSource(options, false);
+}

package/src/metadata.js

@@ -1,7 +1,7 @@
 import { CREDENTIAL_FILE_DISPLAY } from "./credentials.js";
 import { DOCUMENT_SANITIZATION_POLICY } from "./sanitizers/documents.js";
 
-export const VERSION = "1.8.0";
+export const VERSION = "1.9.0";
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const DEFAULT_RETRIES = 2;
 
@@ -54,8 +54,8 @@ export const COMMANDS = Object.freeze([
     command: "products update-knowledge-tree <product-id>",
     method: "PUT",
     path: "/openapi/products/{id}/knowledge-tree",
-    input: "{nodes: [...]}",
-    summary: "Replace the product's dynamic L2/L3/L4 knowledge-tree nodes.",
+    input: "{documents?: [...], nodes: [...documentRefs]}",
+    summary: "Replace product documents and dynamic L2/L3/L4 nodes.",
   },
   {
     command: "products delete-knowledge-tree <product-id>",
@@ -122,8 +122,8 @@ export const COMMANDS = Object.freeze([
     command: "knowledge documents create <node-id>",
     method: "POST",
     path: "/openapi/knowledge/nodes/{id}/documents",
-    input: "{title, summary?}",
-    summary: "Idempotently create a document under a node.",
+    input: "{title, content, url?, markedExcerpts?}",
+    summary: "Create or reuse a product document and attach it to a node.",
   },
   {
     command: "knowledge documents upsert <node-id>",
@@ -136,9 +136,28 @@ export const COMMANDS = Object.freeze([
     command: "knowledge documents update <document-id>",
     method: "PUT",
     path: "/openapi/knowledge/documents/{id}",
-    input: "{title?, summary?}",
+    input: "{title?, url?, content?}",
     summary: "Update supplied fields on a knowledge document.",
   },
+  {
+    command: "knowledge documents get <document-id>",
+    method: "GET",
+    path: "/openapi/knowledge/documents/{id}",
+    summary: "Get document source content and all referencing nodes.",
+  },
+  {
+    command: "knowledge documents link <node-id> <document-id>",
+    method: "PUT",
+    path: "/openapi/knowledge/nodes/{id}/documents/{documentId}",
+    input: "{markedExcerpts?} (optional)",
+    summary: "Attach an existing product document or update its excerpts.",
+  },
+  {
+    command: "knowledge documents unlink <node-id> <document-id>",
+    method: "DELETE",
+    path: "/openapi/knowledge/nodes/{id}/documents/{documentId}",
+    summary: "Remove a node reference without deleting the document.",
+  },
   {
     command: "knowledge documents delete <document-id>",
     method: "DELETE",

package/src/sanitizers/documents.js

@@ -1,9 +1,9 @@
 import { CliError } from "../errors.js";
 
 export const DOCUMENT_SANITIZATION_POLICY = Object.freeze({
-  fields: ["title", "url", "summary"],
-  writableFields: ["title", "summary"],
-  droppedWriteFields: ["url"],
+  fields: ["title", "url", "summary", "content", "markedExcerpts"],
+  writableFields: ["title", "url", "content", "markedExcerpts"],
+  droppedWriteFields: ["summary"],
   removedLabels: [
     "小荷",
     "小荷医疗",
@@ -14,8 +14,10 @@ export const DOCUMENT_SANITIZATION_POLICY = Object.freeze({
     "knowledge documents create",
     "knowledge documents upsert",
     "knowledge documents update",
+    "knowledge documents link",
   ],
   emptyTitle: "validation_error",
+  emptyContent: "validation_error",
 });
 
 const PROHIBITED_LABEL = /小荷\s*(?:AI\s*医生|医疗)?/giu;
@@ -51,14 +53,57 @@ export function sanitizeDocument(document, location = "document") {
       );
     }
   }
-  for (const field of ["url", "summary"]) {
+  for (const field of ["url", "summary", "content"]) {
     if (typeof sanitized[field] === "string") {
       sanitized[field] = sanitizeText(sanitized[field]);
     }
   }
+  if (typeof sanitized.content === "string" && !sanitized.content) {
+    throw new CliError(
+      "validation_error",
+      `${location}.content is empty after prohibited source labels are removed.`,
+    );
+  }
+  if (Array.isArray(sanitized.markedExcerpts)) {
+    sanitized.markedExcerpts = sanitizeMarkedExcerpts(
+      sanitized.markedExcerpts,
+      `${location}.markedExcerpts`,
+    );
+    validateMarkedExcerpts(
+      sanitized.markedExcerpts,
+      sanitized.content,
+      `${location}.markedExcerpts`,
+    );
+  }
   return sanitized;
 }
 
+function sanitizeMarkedExcerpts(excerpts, location) {
+  return excerpts.map((excerpt, index) => {
+    if (typeof excerpt !== "string") return excerpt;
+    const sanitized = sanitizeText(excerpt);
+    if (!sanitized) {
+      throw new CliError(
+        "validation_error",
+        `${location}[${index}] is empty after prohibited source labels are removed.`,
+      );
+    }
+    return sanitized;
+  });
+}
+
+function validateMarkedExcerpts(excerpts, content, location) {
+  if (typeof content !== "string") return;
+  excerpts.forEach((excerpt, index) => {
+    if (typeof excerpt === "string" && !content.includes(excerpt)) {
+      throw new CliError(
+        "validation_error",
+        `${location}[${index}] must be an exact substring of the sanitized document content.`,
+      );
+    }
+  });
+}
+
 function prepareDocumentForWrite(document, location) {
   const sanitized = sanitizeDocument(document, location);
   if (
@@ -68,7 +113,7 @@ function prepareDocumentForWrite(document, location) {
   ) {
     return sanitized;
   }
-  const { url: _unsupportedUrl, ...writableDocument } = sanitized;
+  const { summary: _unsupportedSummary, ...writableDocument } = sanitized;
   return writableDocument;
 }
 
@@ -86,28 +131,92 @@ export function sanitizeDocumentBatchPayload(body) {
   };
 }
 
+export function sanitizeDocumentReferencePayload(
+  body,
+  location = "documentReference",
+) {
+  if (
+    body === null ||
+    Array.isArray(body) ||
+    typeof body !== "object"
+  ) {
+    return body;
+  }
+  return prepareDocumentForWrite(body, location);
+}
+
 export function sanitizeKnowledgeTreePayload(body) {
-  if (!Array.isArray(body.nodes)) return body;
+  const documents = Array.isArray(body.documents)
+    ? body.documents.map((document, documentIndex) =>
+        prepareDocumentForWrite(
+          document,
+          `documents[${documentIndex}]`,
+        ),
+      )
+    : body.documents;
+  const documentsByRef = new Map(
+    Array.isArray(documents)
+      ? documents
+          .filter(
+            (document) =>
+              document &&
+              typeof document === "object" &&
+              typeof document.clientRef === "string",
+          )
+          .map((document) => [document.clientRef, document])
+      : [],
+  );
+  const nodes = Array.isArray(body.nodes)
+    ? body.nodes.map((node, nodeIndex) => {
+        if (
+          node === null ||
+          Array.isArray(node) ||
+          typeof node !== "object"
+        ) {
+          return node;
+        }
+        const sanitizedNode = { ...node };
+        if (Array.isArray(node.documentRefs)) {
+          sanitizedNode.documentRefs = node.documentRefs.map(
+            (reference, referenceIndex) => {
+              const location =
+                `nodes[${nodeIndex}].documentRefs[${referenceIndex}]`;
+              const sanitizedReference =
+                sanitizeDocumentReferencePayload(reference, location);
+              const document = documentsByRef.get(
+                sanitizedReference?.documentRef,
+              );
+              if (
+                document &&
+                Array.isArray(sanitizedReference.markedExcerpts)
+              ) {
+                validateMarkedExcerpts(
+                  sanitizedReference.markedExcerpts,
+                  document.content,
+                  `${location}.markedExcerpts`,
+                );
+              }
+              return sanitizedReference;
+            },
+          );
+        }
+        // Keep sanitizing the legacy shape so no document write path can bypass
+        // the permanent source-label policy.
+        if (Array.isArray(node.documents)) {
+          sanitizedNode.documents = node.documents.map(
+            (document, documentIndex) =>
+              prepareDocumentForWrite(
+                document,
+                `nodes[${nodeIndex}].documents[${documentIndex}]`,
+              ),
+          );
+        }
+        return sanitizedNode;
+      })
+    : body.nodes;
   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}]`,
-          ),
-        ),
-      };
-    }),
+    ...(body.documents !== undefined ? { documents } : {}),
+    ...(body.nodes !== undefined ? { nodes } : {}),
   };
 }