viatris-exam-cli 1.3.0 → 1.4.0

package/README.md

@@ -50,7 +50,7 @@ export VIATRIS_API_KEY_PREFIX="Bearer "
 - API Key 只从 `VIATRIS_API_KEY` 环境变量读取。
 - 默认使用线上环境，可通过 `VIATRIS_API_ENV=development` 切换到开发环境。
 - `VIATRIS_API_BASE_URL` 可覆盖当前环境地址。
-- GET 请求遇到网络错误、HTTP 429 或 5xx 时自动重试，POST/PUT 不自动重试。
+- GET 请求遇到网络错误、HTTP 429 或 5xx 时自动重试，POST/PUT/PATCH/DELETE 不自动重试。
 - `describe` 返回机器可读的命令、参数、认证和退出码清单。
 - ID 路径参数自动进行 URL 编码。
 - HTTP 401/403 使用专用退出码，方便 Agent 判断需要刷新认证。
@@ -80,7 +80,28 @@ viatris-exam products update-knowledge-tree "$PRODUCT_ID" \
   --input knowledge-tree.json
 ```
 
-知识树回写是完整替换操作，必须一次提交全部 10-500 个 L3/L4 动态节点。先查询产品以获取固定 L2 维度的 `clientRef`。
+产品是隐藏系统容器，不属于业务知识树层级。固定维度为 L1；知识树回写是完整替换操作，必须一次提交全部 15-500 个 L2/L3/L4 动态节点。先查询产品以获取固定 L1 维度的 `clientRef`。
+
+### 知识节点与文档
+
+```bash
+viatris-exam knowledge tree <product-code>
+viatris-exam knowledge nodes by-path --input path.json
+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 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 delete <document-id>
+```
+
+节点删除会级联删除整棵子树及文档。产品根和固定维度受保护，不能改名、移动或删除。
+
+`/knowledge` CRUD 响应中的 `level` 是物理存储层级（产品根为 1、固定维度为 2）；产品生成接口使用业务层级（产品隐藏、固定维度为 L1、动态节点为 L2-L4）。
 
 ### 出题任务
 
@@ -92,6 +113,8 @@ viatris-exam gen-tasks submit "$TASK_ID" --input examples/generated-questions.js
 
 `externalRef` 是题目回写的幂等键。Agent 重试 POST 前应复用原值。
 
+产品全节点任务的 `dimension` 为 `all`。应按 `knowledgeContexts` 覆盖每个叶子节点，并在回写题目时携带对应 `knowledgeNodeId`。
+
 ### 考试记录
 
 ```bash
@@ -136,6 +159,8 @@ printf '%s' '{"query":"阿托伐他汀 适应症","limit":4}' |
   viatris-exam medical-search search
 ```
 
+响应中的 `rawJson` 已是结构化对象，可直接读取 `rawJson.documents`，无需再次 `JSON.parse`。
+
 ## 错误格式
 
 ```json

package/package.json

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

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 trees, generation tasks, exam records, scoring, exams, questions, or medical search.
-version: 1.3.0
+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.4.0
 ---
 
 # Viatris Exam CLI
@@ -23,8 +23,10 @@ Use the repository-local CLI for every supported API operation. Do not call the
 - Parse successful `stdout` as JSON.
 - Parse failed `stderr` as JSON and branch on both exit code and `error.type`.
 - Preserve `externalRef` when retrying question submission. It is the idempotency key.
+- For product-wide generation tasks, create one or more questions for every entry in `knowledgeContexts` and include its `knowledgeNodeId`.
 - Prefer scoring rule V2 for generated questions and scoring results. Use stable point and deduction-rule IDs.
-- Do not automatically retry POST or PUT commands. Inspect the returned error and determine whether the server accepted the request.
+- Treat product IDs as hidden containers, not knowledge-tree levels. Fixed dimensions are business L1; generated nodes are L2-L4.
+- 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.
 
 ## Maintain

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

@@ -42,13 +42,13 @@ node src/cli.js --version
 
 ## Commands
 
-Get a product and its fixed L2 dimensions:
+Get a product and its fixed L1 dimensions:
 
 ```bash
 node src/cli.js products get "$PRODUCT_ID" --compact
 ```
 
-Use each returned `fixedDimensions[].clientRef` as the parent reference for an L3 node.
+The product ID represents a hidden system container and is not part of 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`.
 
 Replace a product knowledge tree:
 
@@ -66,17 +66,25 @@ Payload shape:
     {
       "clientRef": "disease.hypertension",
       "parentClientRef": "dimension:disease",
-      "level": 3,
+      "level": 2,
       "dimensionCode": "disease",
       "name": "高血压",
       "sortOrder": 1
     },
     {
-      "clientRef": "disease.hypertension.definition",
+      "clientRef": "disease.hypertension.diagnosis",
       "parentClientRef": "disease.hypertension",
-      "level": 4,
+      "level": 3,
       "dimensionCode": "disease",
       "name": "定义与诊断",
+      "sortOrder": 1
+    },
+    {
+      "clientRef": "disease.hypertension.diagnosis.threshold",
+      "parentClientRef": "disease.hypertension.diagnosis",
+      "level": 4,
+      "dimensionCode": "disease",
+      "name": "诊断阈值",
       "sortOrder": 1,
       "documents": [
         {
@@ -90,7 +98,61 @@ Payload shape:
 }
 ```
 
-Submit the complete L3/L4 node set, between 10 and 500 nodes. Every `clientRef` must be unique within the payload. L3 nodes use `dimension:<code>` as `parentClientRef`; L4 nodes use an L3 `clientRef`. Every L4 node needs at least one document. A successful PUT replaces the previous dynamic nodes, so do not send a partial tree.
+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.
+
+### Incremental Knowledge Management
+
+Get the complete physical tree and all product documents:
+
+```bash
+node src/cli.js 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.
+
+Create or reuse a visible path:
+
+```bash
+node src/cli.js knowledge nodes by-path --json \
+  '{"product":"lipitor","path":["疾病知识","血脂异常基础","ASCVD 风险评估"]}'
+```
+
+The path has one to three entries. The first entry must be a fixed dimension name. The response separates all resolved `nodes` from nodes newly `created`.
+
+Create or reuse one node under a known parent:
+
+```bash
+node src/cli.js 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" \
+  --json '{"name":"血脂异常与他汀治疗","sortOrder":5}'
+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"
+```
+
+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.
+
+Manage documents:
+
+```bash
+node src/cli.js knowledge documents list "$NODE_ID"
+node src/cli.js knowledge documents create "$NODE_ID" \
+  --json '{"title":"说明书","url":"https://example.com/source","summary":"摘录"}'
+node src/cli.js knowledge documents upsert "$NODE_ID" \
+  --json '{"items":[{"title":"说明书","summary":"更新后的摘录"}]}'
+node src/cli.js knowledge documents update "$DOCUMENT_ID" \
+  --json '{"url":null,"summary":"更新后的摘要"}'
+node src/cli.js knowledge documents delete "$DOCUMENT_ID"
+```
+
+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.
 
 List generation tasks:
 
@@ -109,6 +171,8 @@ Get one generation task:
 node src/cli.js 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`.
+
 Submit generated questions:
 
 ```bash
@@ -123,6 +187,7 @@ Payload shape:
     {
       "externalRef": "agent-q-0001",
       "failureId": "optional-failure-id",
+      "knowledgeNodeId": "required-for-product-wide-task",
       "content": {
         "stem": "Question stem",
         "referenceAnswer": "Reference answer",
@@ -177,6 +242,8 @@ Payload shape:
 }
 ```
 
+Omit `knowledgeNodeId` for ordinary tasks. For a product-wide task it is required and must match a node in the task's `knowledgeContexts`.
+
 Get a submitted exam record and its frozen answers:
 
 ```bash
@@ -274,6 +341,8 @@ printf '%s' '{"query":"阿托伐他汀 适应症","limit":4}' |
 
 Do not combine query flags with JSON input.
 
+The response `rawJson` is already a structured object. Read `rawJson.documents` directly; do not call `JSON.parse`. Each result contains `rank`, `doc_info`, optional `medical_info`, and the upstream `logid`.
+
 ## Input Rules
 
 Choose exactly one input form:
@@ -313,7 +382,7 @@ Success writes API JSON to `stdout`. Errors write one JSON object to `stderr`:
 | `1` | API error | Inspect status and response |
 | `2` | Usage, validation, or input error | Correct command or payload |
 | `3` | Configuration error | Check environment configuration |
-| `4` | Network or timeout error | GET may be retried; inspect POST/PUT state first |
+| `4` | Network or timeout error | GET may be retried; inspect write state first |
 | `5` | Authentication or authorization error | Refresh or correct credentials |
 
-GET automatically retries network errors, HTTP 429, and HTTP 5xx. POST and PUT never retry automatically.
+GET automatically retries network errors, HTTP 429, and HTTP 5xx. POST, PUT, PATCH, and DELETE never retry automatically.

package/src/command-handlers/knowledge.js

@@ -0,0 +1,130 @@
+import {
+  assertNoExtraPositionals,
+  assertOptions,
+  requiredId,
+} from "../args.js";
+import { readJsonInput } from "../input.js";
+
+function jsonCommand(method, path, options) {
+  assertOptions(options, ["input", "json"]);
+  return readJsonInput(options).then((body) => ({ method, path, body }));
+}
+
+function nodePath(positionals, label) {
+  return requiredId(positionals, 3, label);
+}
+
+export async function resolveKnowledge(positionals, options) {
+  const [resource, area, action] = positionals;
+  if (resource !== "knowledge") return null;
+
+  if (area === "tree") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options);
+    const product = requiredId(positionals, 2, "product code");
+    return {
+      method: "GET",
+      path: `/openapi/knowledge/tree?product=${product}`,
+    };
+  }
+
+  if (area === "nodes" && action === "by-path") {
+    assertNoExtraPositionals(positionals, 3);
+    return jsonCommand(
+      "POST",
+      "/openapi/knowledge/nodes/by-path",
+      options,
+    );
+  }
+
+  if (area === "nodes" && action === "create") {
+    assertNoExtraPositionals(positionals, 3);
+    return jsonCommand("POST", "/openapi/knowledge/nodes", options);
+  }
+
+  if (area === "nodes" && action === "get") {
+    assertNoExtraPositionals(positionals, 4);
+    assertOptions(options);
+    const id = nodePath(positionals, "knowledge node ID");
+    return { method: "GET", path: `/openapi/knowledge/nodes/${id}` };
+  }
+
+  if (area === "nodes" && action === "update") {
+    assertNoExtraPositionals(positionals, 4);
+    const id = nodePath(positionals, "knowledge node ID");
+    return jsonCommand(
+      "PATCH",
+      `/openapi/knowledge/nodes/${id}`,
+      options,
+    );
+  }
+
+  if (area === "nodes" && action === "delete") {
+    assertNoExtraPositionals(positionals, 4);
+    assertOptions(options);
+    const id = nodePath(positionals, "knowledge node ID");
+    return { method: "DELETE", path: `/openapi/knowledge/nodes/${id}` };
+  }
+
+  if (area === "nodes" && action === "move") {
+    assertNoExtraPositionals(positionals, 4);
+    const id = nodePath(positionals, "knowledge node ID");
+    return jsonCommand(
+      "PUT",
+      `/openapi/knowledge/nodes/${id}/move`,
+      options,
+    );
+  }
+
+  if (area === "documents" && action === "list") {
+    assertNoExtraPositionals(positionals, 4);
+    assertOptions(options);
+    const id = nodePath(positionals, "knowledge node ID");
+    return {
+      method: "GET",
+      path: `/openapi/knowledge/nodes/${id}/documents`,
+    };
+  }
+
+  if (area === "documents" && action === "create") {
+    assertNoExtraPositionals(positionals, 4);
+    const id = nodePath(positionals, "knowledge node ID");
+    return jsonCommand(
+      "POST",
+      `/openapi/knowledge/nodes/${id}/documents`,
+      options,
+    );
+  }
+
+  if (area === "documents" && action === "upsert") {
+    assertNoExtraPositionals(positionals, 4);
+    const id = nodePath(positionals, "knowledge node ID");
+    return jsonCommand(
+      "PUT",
+      `/openapi/knowledge/nodes/${id}/documents`,
+      options,
+    );
+  }
+
+  if (area === "documents" && action === "update") {
+    assertNoExtraPositionals(positionals, 4);
+    const id = nodePath(positionals, "knowledge document ID");
+    return jsonCommand(
+      "PUT",
+      `/openapi/knowledge/documents/${id}`,
+      options,
+    );
+  }
+
+  if (area === "documents" && action === "delete") {
+    assertNoExtraPositionals(positionals, 4);
+    assertOptions(options);
+    const id = nodePath(positionals, "knowledge document ID");
+    return {
+      method: "DELETE",
+      path: `/openapi/knowledge/documents/${id}`,
+    };
+  }
+
+  return null;
+}

package/src/commands.js

@@ -1,6 +1,7 @@
 import { resolveContent } from "./command-handlers/content.js";
 import { resolveExamRecords } from "./command-handlers/exam-records.js";
 import { resolveGenTasks } from "./command-handlers/gen-tasks.js";
+import { resolveKnowledge } from "./command-handlers/knowledge.js";
 import { resolveMedicalSearch } from "./command-handlers/medical-search.js";
 import { resolveProducts } from "./command-handlers/products.js";
 import { resolveScoring } from "./command-handlers/scoring.js";
@@ -8,6 +9,7 @@ import { CliError } from "./errors.js";
 
 const resolvers = [
   resolveProducts,
+  resolveKnowledge,
   resolveGenTasks,
   resolveExamRecords,
   resolveScoring,

package/src/help.js

@@ -10,6 +10,18 @@ Usage:
 Commands:
   products get <product-id>
   products update-knowledge-tree <product-id> --input <file|->
+  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 move <node-id> --input <file|->
+  knowledge documents list <node-id>
+  knowledge documents create <node-id> --input <file|->
+  knowledge documents upsert <node-id> --input <file|->
+  knowledge documents update <document-id> --input <file|->
+  knowledge documents delete <document-id>
   gen-tasks list [--status STATUS] [--limit N]
   gen-tasks get <task-id>
   gen-tasks submit <task-id> --input <file|->

package/src/metadata.js

@@ -1,4 +1,4 @@
-export const VERSION = "1.3.0";
+export const VERSION = "1.4.0";
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const DEFAULT_RETRIES = 2;
 
@@ -26,7 +26,86 @@ export const COMMANDS = Object.freeze([
     method: "PUT",
     path: "/openapi/products/{id}/knowledge-tree",
     input: "{nodes: [...]}",
-    summary: "Replace the product's dynamic L3/L4 knowledge-tree nodes.",
+    summary: "Replace the product's dynamic L2/L3/L4 knowledge-tree nodes.",
+  },
+  {
+    command: "knowledge tree <product-code>",
+    method: "GET",
+    path: "/openapi/knowledge/tree",
+    summary: "Get a product's complete physical knowledge tree and documents.",
+  },
+  {
+    command: "knowledge nodes by-path",
+    method: "POST",
+    path: "/openapi/knowledge/nodes/by-path",
+    input: "{product, path}",
+    summary: "Idempotently create or reuse nodes along a visible path.",
+  },
+  {
+    command: "knowledge nodes create",
+    method: "POST",
+    path: "/openapi/knowledge/nodes",
+    input: "{parentId, name, sortOrder?}",
+    summary: "Idempotently create a node under a parent.",
+  },
+  {
+    command: "knowledge nodes get <node-id>",
+    method: "GET",
+    path: "/openapi/knowledge/nodes/{id}",
+    summary: "Get a knowledge node with its path and documents.",
+  },
+  {
+    command: "knowledge nodes update <node-id>",
+    method: "PATCH",
+    path: "/openapi/knowledge/nodes/{id}",
+    input: "{name?, sortOrder?}",
+    summary: "Update a knowledge node's name or sort order.",
+  },
+  {
+    command: "knowledge nodes delete <node-id>",
+    method: "DELETE",
+    path: "/openapi/knowledge/nodes/{id}",
+    summary: "Delete a knowledge node, its subtree, and documents.",
+  },
+  {
+    command: "knowledge nodes move <node-id>",
+    method: "PUT",
+    path: "/openapi/knowledge/nodes/{id}/move",
+    input: "{newParentId, sortOrder?}",
+    summary: "Move a knowledge node and cascade subtree levels.",
+  },
+  {
+    command: "knowledge documents list <node-id>",
+    method: "GET",
+    path: "/openapi/knowledge/nodes/{id}/documents",
+    summary: "List evidence documents attached to a node.",
+  },
+  {
+    command: "knowledge documents create <node-id>",
+    method: "POST",
+    path: "/openapi/knowledge/nodes/{id}/documents",
+    input: "{title, url?, summary?}",
+    summary: "Idempotently create a document under a node.",
+  },
+  {
+    command: "knowledge documents upsert <node-id>",
+    method: "PUT",
+    path: "/openapi/knowledge/nodes/{id}/documents",
+    input: "{items: [...]}",
+    summary: "Batch upsert node documents by title.",
+  },
+  {
+    command: "knowledge documents update <document-id>",
+    method: "PUT",
+    path: "/openapi/knowledge/documents/{id}",
+    input: "{title?, url?, summary?}",
+    summary: "Update supplied fields on a knowledge document.",
+  },
+  {
+    command: "knowledge documents delete <document-id>",
+    method: "DELETE",
+    path: "/openapi/knowledge/documents/{id}",
+    summary: "Delete a knowledge document.",
   },
   {
     command: "gen-tasks list",
@@ -42,13 +121,13 @@ export const COMMANDS = Object.freeze([
     command: "gen-tasks get <task-id>",
     method: "GET",
     path: "/openapi/gen-tasks/{taskId}",
-    summary: "Get a question-generation task and its pending failures.",
+    summary: "Get a task, knowledge contexts, rules, and pending failures.",
   },
   {
     command: "gen-tasks submit <task-id>",
     method: "POST",
     path: "/openapi/gen-tasks/{taskId}/questions",
-    input: "{items: [...], finished?: boolean}",
+    input: "{items: [{externalRef, knowledgeNodeId?, content}], finished?}",
     summary: "Submit generated questions. externalRef is the idempotency key.",
   },
   {