@aliyunrds/ctxdb 1.0.9-beta.1 → 1.0.9

package/README.md

@@ -653,6 +653,63 @@ Output semantics worth knowing:
   incomplete by design (deleted endpoints are omitted); relation items always
   keep denormalized endpoint names.
 
+### Knowledge graph create, update and delete
+
+These six commands operate on entities and relations **inside a knowledge base**.
+`kb create/update/delete` manages the knowledge base itself; `memory entity`
+manages memory entities. Graph mutations use the existing DATA API credentials
+selected by `--agent` / `CTXDB_AGENT`, and require graph write permission.
+
+| Command | DATA API |
+|---|---|
+| `kb entity-create` / `kb entity-update` / `kb entity-delete` | POST / PUT / DELETE `/v1/knowledge/entities` |
+| `kb relation-create` / `kb relation-update` / `kb relation-delete` | POST / PUT / DELETE `/v1/knowledge/entity-relations` |
+
+Every command requires `--kb=<kb-id>` (an ID, not a name). Updates and deletes
+require `--entity-id` or `--relation-id`; names, positional locators and bulk
+selectors are not accepted. Find IDs with `entities` and `relations --verbose`.
+Creates return the new ID; entity renaming preserves that ID and updates incident
+relation names. Relation updates cannot change the endpoints or relation ID.
+
+```sh
+ctxdb kb entity-create --kb=<kb-id> --name=ContextDB --type=Product \
+  --description='Context database' --aliases-json='["ctxdb"]' --json
+ctxdb kb entity-get --kb=<kb-id> --entity-id=<id> --verbose --json
+ctxdb kb entity-update --kb=<kb-id> --entity-id=<id> --name=ContextDB --type=Product \
+  --description='' --aliases-json='[]' --json
+
+ctxdb kb relation-create --kb=<kb-id> --source-entity-id=<a> --target-entity-id=<b> \
+  --relation-type=USES --description='' --keywords-json='[]' --weight=1 --json
+ctxdb kb relations --kb=<kb-id> --verbose --json
+ctxdb kb relation-update --kb=<kb-id> --relation-id=<id> \
+  --relation-type=CALLS --description='' --keywords-json='["api"]' --weight=0.5 --json
+
+# Irreversible: delete a relation; both endpoint entities remain.
+ctxdb kb relation-delete --kb=<kb-id> --relation-id=<id> --yes --json
+# Irreversible: delete an entity and ALL its incoming/outgoing relations.
+ctxdb kb entity-delete --kb=<kb-id> --entity-id=<id> --yes --json
+```
+
+Create and update require every editable field shown above. **Update is a full
+replacement**, so read the current values before editing. Explicitly use
+`--description=''` or `--aliases-json='[]'` / `--keywords-json='[]'` to clear a
+field. Arrays must contain strings; `--weight` must be finite, with the server
+enforcing its 0–1 range and other business limits.
+
+Deletion requires the bare `--yes` switch in both terminals and scripts; without
+it, or with `--yes=false`, the CLI exits 2 without sending a delete request.
+The CLI does not prompt interactively. Entity deletion returns the server's
+`deleted`, `deleted_entity_count` and `deleted_relation_count`. Relation deletion
+returns `deleted` and its IDs; its API does not return counts. A `deleted: false`
+result is printed and exits 1, never reported as successful deletion.
+
+Default output preserves the complete mutation `data`; `--json` formats that as
+JSON and `--raw` retains the Box envelope. HTTP and business errors (including
+HTTP 200 with a failing `errorCode`) exit nonzero even with `--raw`. Missing IDs,
+malformed lists and incomplete arguments exit 2 with usage. A second delete of
+an already deleted ID returns the server's not-found error; mutations are not
+automatically retried after an uncertain response.
+
 ### Knowledge review commands
 
 `kb review` covers the Knowledge Review DATA APIs: review-queue handling

package/dist/cli/main.js

@@ -4164,6 +4164,139 @@ var kbAclSubjects = (args) => kbAcl("subjects", args);
 var kbAclSet = (args) => kbAcl("set", args);
 var kbAclDelete = (args) => kbAcl("delete", args);
 
+// src/cli/kb-graph-cli.ts
+var GRAPH_MUTATION_USAGE = {
+  "entity-create": "ctxdb kb entity-create --kb=<kb-id> --name=<name> --type=<type> --description=<text> --aliases-json='<json-array>'",
+  "entity-update": "ctxdb kb entity-update --kb=<kb-id> --entity-id=<id> --name=<name> --type=<type> --description=<text> --aliases-json='<json-array>'",
+  "entity-delete": "ctxdb kb entity-delete --kb=<kb-id> --entity-id=<id> --yes",
+  "relation-create": "ctxdb kb relation-create --kb=<kb-id> --source-entity-id=<id> --target-entity-id=<id> --relation-type=<type> --description=<text> --keywords-json='<json-array>' --weight=<number>",
+  "relation-update": "ctxdb kb relation-update --kb=<kb-id> --relation-id=<id> --relation-type=<type> --description=<text> --keywords-json='<json-array>' --weight=<number>",
+  "relation-delete": "ctxdb kb relation-delete --kb=<kb-id> --relation-id=<id> --yes"
+};
+var ENTITY_FIELDS = ["name", "type", "description", "aliases-json"];
+var RELATION_FIELDS = ["relation-type", "description", "keywords-json", "weight"];
+function stringFlag2(args, name, allowEmpty = false) {
+  const value = args.flags[name];
+  if (typeof value !== "string" || !allowEmpty && !value.trim()) {
+    throw new Error(`--${name} requires ${allowEmpty ? "a string value (use --description='' to clear)" : "a non-empty value"}`);
+  }
+  return value;
+}
+function stringArrayFlag(args, name) {
+  const text = stringFlag2(args, name);
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error(`--${name} must be a JSON array of strings (use '[]' to clear)`);
+  }
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    throw new Error(`--${name} must be a JSON array of strings (use '[]' to clear)`);
+  }
+  return value;
+}
+function parseMutation(args, resource, action) {
+  const idFlag = `${resource}-id`;
+  const allowed = /* @__PURE__ */ new Set([
+    "kb",
+    "agent",
+    "json",
+    "raw",
+    ...action === "delete" ? [idFlag, "yes"] : [
+      ...resource === "entity" ? ENTITY_FIELDS : RELATION_FIELDS,
+      ...action === "update" ? [idFlag] : resource === "relation" ? ["source-entity-id", "target-entity-id"] : []
+    ]
+  ]);
+  if (args.positional.length) throw new Error("use explicit ID flags; positional locators are not supported");
+  for (const [flag, value] of Object.entries(args.flags)) {
+    if (!allowed.has(flag)) throw new Error(`unknown --${flag}`);
+    if (["yes", "json", "raw"].includes(flag) && value !== true) {
+      throw new Error(`--${flag} is a boolean switch; do not supply a value`);
+    }
+  }
+  if (args.flags.agent !== void 0) stringFlag2(args, "agent");
+  const knowledge_base_id = stringFlag2(args, "kb").trim();
+  const locator = action === "create" ? {} : { [`${resource}_id`]: stringFlag2(args, idFlag).trim() };
+  if (action === "delete") {
+    if (args.flags.yes !== true) {
+      throw new Error(`deletion is irreversible${resource === "entity" ? " and deletes all incoming/outgoing relations" : ""}; pass --yes to confirm`);
+    }
+    return { knowledge_base_id, ...locator };
+  }
+  if (resource === "entity") {
+    return {
+      knowledge_base_id,
+      ...locator,
+      entity_name: stringFlag2(args, "name"),
+      entity_type: stringFlag2(args, "type"),
+      description: stringFlag2(args, "description", true),
+      aliases: stringArrayFlag(args, "aliases-json")
+    };
+  }
+  const weight = Number(stringFlag2(args, "weight"));
+  if (!Number.isFinite(weight)) throw new Error("--weight must be a finite number");
+  return {
+    knowledge_base_id,
+    ...locator,
+    ...action === "create" ? {
+      source_entity_id: stringFlag2(args, "source-entity-id").trim(),
+      target_entity_id: stringFlag2(args, "target-entity-id").trim()
+    } : {},
+    relation_type: stringFlag2(args, "relation-type"),
+    description: stringFlag2(args, "description", true),
+    keywords: stringArrayFlag(args, "keywords-json"),
+    weight
+  };
+}
+async function mutateGraph(args, resource, action) {
+  const command = `${resource}-${action}`;
+  const usage2 = `usage: ${GRAPH_MUTATION_USAGE[command]} [--agent=<name>] [--raw] [--json]
+`;
+  if (args.flags.help || args.flags.h) {
+    process.stdout.write(usage2);
+    return 0;
+  }
+  let payload;
+  try {
+    payload = parseMutation(args, resource, action);
+  } catch (error) {
+    process.stderr.write(`${error.message}
+${usage2}`);
+    return 2;
+  }
+  const { client } = buildContext(args);
+  const path = resource === "entity" ? "/v1/knowledge/entities" : "/v1/knowledge/entity-relations";
+  const response = action === "create" ? await client.postJson(path, payload) : action === "update" ? await client.putJson(path, payload) : await client.delete(path, payload);
+  let data;
+  try {
+    data = unwrapReviewData(response, `kb ${command}`);
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      throw new CtxdbError(`kb ${command} returned no mutation result`);
+    }
+    const result = data;
+    if (typeof result[`${resource}_id`] !== "string" || !result[`${resource}_id`] || result.knowledge_base_id !== payload.knowledge_base_id || action !== "create" && result[`${resource}_id`] !== payload[`${resource}_id`]) {
+      throw new CtxdbError(`kb ${command} returned an invalid mutation locator`);
+    }
+    if (action === "delete") {
+      if (typeof result.deleted !== "boolean") throw new CtxdbError(`kb ${command} returned no deletion status`);
+      if (resource === "entity" && ["deleted_entity_count", "deleted_relation_count"].some(
+        (key) => !Number.isSafeInteger(result[key]) || result[key] < 0
+      )) throw new CtxdbError(`kb ${command} returned invalid deletion counts`);
+    }
+  } catch (error) {
+    const requestId = response?.requestId;
+    throw new CtxdbError(`${error.message}${typeof requestId === "string" ? ` (RequestId: ${requestId})` : ""}`);
+  }
+  printResult(args.flags.raw ? response : data, !!args.flags.json);
+  return action === "delete" && data.deleted !== true ? 1 : 0;
+}
+var kbEntityCreate = (args) => mutateGraph(args, "entity", "create");
+var kbEntityUpdate = (args) => mutateGraph(args, "entity", "update");
+var kbEntityDelete = (args) => mutateGraph(args, "entity", "delete");
+var kbRelationCreate = (args) => mutateGraph(args, "relation", "create");
+var kbRelationUpdate = (args) => mutateGraph(args, "relation", "update");
+var kbRelationDelete = (args) => mutateGraph(args, "relation", "delete");
+
 // src/cli/promotion-cli.ts
 var GENERATE_USAGE = "usage: ctxdb memory promotion generate <topic> [--knowledge-base-id=<kb-id>] [--wait|--no-wait] [--agent=<name>] [--json]";
 var LIST_USAGE = "usage: ctxdb memory promotion list [--status=<generating|pending_review|approving|approved|rejected|generation_failed>] [--page=N] [--page-size=N] [--sort-by=quality_score] [--sort-order=asc|desc] [--raw] [--agent=<name>] [--json]";
@@ -4244,7 +4377,7 @@ ${GENERATE_USAGE}`, 2);
   if (!topic || topic.trim() === "") fail(GENERATE_USAGE, 2);
   const ctx = buildContext(args);
   const body = { topic };
-  const kbId = stringFlag2(args, "knowledge-base-id");
+  const kbId = stringFlag3(args, "knowledge-base-id");
   if (kbId !== void 0) body.knowledge_base_id = kbId;
   const resp = await ctx.client.postJson("/v1/memory_promotions/generate", body);
   let data = unwrapBox(resp, "memory promotion generate");
@@ -4277,7 +4410,7 @@ ${GENERATE_USAGE}`, 2);
 async function promotionList(args) {
   if (showHelp(args, LIST_USAGE)) return 0;
   const params = {};
-  const status2 = stringFlag2(args, "status");
+  const status2 = stringFlag3(args, "status");
   if (status2 !== void 0) {
     if (!PROMOTION_STATUSES.includes(status2)) {
       fail(`invalid --status: ${status2} (expected one of ${PROMOTION_STATUSES.join("|")})
@@ -4289,7 +4422,7 @@ ${LIST_USAGE}`, 2);
   if (page !== void 0) params.page = page;
   const pageSize = intFlag(args, "page-size", LIST_USAGE);
   if (pageSize !== void 0) params.page_size = pageSize;
-  const sortBy = stringFlag2(args, "sort-by");
+  const sortBy = stringFlag3(args, "sort-by");
   if (sortBy !== void 0) {
     if (sortBy !== "quality_score") {
       fail(`invalid --sort-by: ${sortBy} (expected quality_score)
@@ -4297,7 +4430,7 @@ ${LIST_USAGE}`, 2);
     }
     params.sort_by = sortBy;
   }
-  const sortOrder = stringFlag2(args, "sort-order");
+  const sortOrder = stringFlag3(args, "sort-order");
   if (sortOrder !== void 0) {
     if (sortOrder !== "asc" && sortOrder !== "desc") {
       fail(`invalid --sort-order: ${sortOrder} (expected asc|desc)
@@ -4339,7 +4472,7 @@ async function promotionReject(args) {
   const promotionId = requireIdFlag(args, "promotion-id", REJECT_USAGE);
   const ctx = buildContext(args);
   const body = { promotion_id: promotionId };
-  const reason = stringFlag2(args, "reason");
+  const reason = stringFlag3(args, "reason");
   if (reason !== void 0) body.reason = reason;
   const resp = await ctx.client.postJson("/v1/memory_promotions/reject", body);
   emit(args, resp, "memory promotion reject", (data) => data);
@@ -4347,17 +4480,17 @@ async function promotionReject(args) {
 }
 async function promotionBatchAction(args) {
   if (showHelp(args, BATCH_ACTION_USAGE)) return 0;
-  const action = stringFlag2(args, "action");
+  const action = stringFlag3(args, "action");
   if (action === void 0 || !BATCH_ACTIONS.includes(action)) {
     fail(`--action is required and must be one of ${BATCH_ACTIONS.join("|")}
 ${BATCH_ACTION_USAGE}`, 2);
   }
   const ids = parseIdsFlag(args, BATCH_ACTION_USAGE);
-  const kbId = action === "approve" ? requireIdFlag(args, "knowledge-base-id", BATCH_ACTION_USAGE) : stringFlag2(args, "knowledge-base-id");
+  const kbId = action === "approve" ? requireIdFlag(args, "knowledge-base-id", BATCH_ACTION_USAGE) : stringFlag3(args, "knowledge-base-id");
   const ctx = buildContext(args);
   const body = { action, ids };
   if (kbId !== void 0) body.knowledge_base_id = kbId;
-  const reason = stringFlag2(args, "reason");
+  const reason = stringFlag3(args, "reason");
   if (reason !== void 0) body.reason = reason;
   const resp = await ctx.client.postJson("/v1/memory_promotions/batch", body);
   const data = emit(args, resp, "memory promotion batch-action", (data2) => data2);
@@ -4383,8 +4516,8 @@ async function promotionResolveDoubts(args) {
 ${RESOLVE_DOUBTS_USAGE}`, 2);
   }
   const resolutions = parseResolutions(resolutionsRaw, RESOLVE_DOUBTS_USAGE);
-  const title = stringFlag2(args, "title");
-  const content = stringFlag2(args, "content");
+  const title = stringFlag3(args, "title");
+  const content = stringFlag3(args, "content");
   if (resolutions.length === 0 && title === void 0 && content === void 0) {
     fail(`provide a resolution or a non-empty --title/--content edit
 ${RESOLVE_DOUBTS_USAGE}`, 2);
@@ -4478,7 +4611,7 @@ async function promotionSettingsGet(args) {
 async function promotionSettingsUpdate(args) {
   if (showHelp(args, SETTINGS_UPDATE_USAGE)) return 0;
   const body = {};
-  const enabled = stringFlag2(args, "auto-ingest-enabled");
+  const enabled = stringFlag3(args, "auto-ingest-enabled");
   if (enabled !== void 0) {
     if (enabled !== "true" && enabled !== "false") {
       fail(`invalid --auto-ingest-enabled: ${enabled} (expected true|false)
@@ -4486,7 +4619,7 @@ ${SETTINGS_UPDATE_USAGE}`, 2);
     }
     body.auto_ingest_enabled = enabled === "true";
   }
-  const threshold = stringFlag2(args, "auto-ingest-threshold");
+  const threshold = stringFlag3(args, "auto-ingest-threshold");
   if (threshold !== void 0) {
     const n = Number(threshold);
     if (!Number.isFinite(n) || n < 0 || n > 1) {
@@ -4495,7 +4628,7 @@ ${SETTINGS_UPDATE_USAGE}`, 2);
     }
     body.auto_ingest_threshold = n;
   }
-  const defaultKbId = stringFlag2(args, "default-kb-id");
+  const defaultKbId = stringFlag3(args, "default-kb-id");
   const clearDefaultKb = args.flags["clear-default-kb"] === true;
   if (defaultKbId !== void 0 && clearDefaultKb) {
     fail(`cannot use --default-kb-id and --clear-default-kb together
@@ -4512,12 +4645,12 @@ ${SETTINGS_UPDATE_USAGE}`, 2);
   emit(args, resp, "memory promotion settings update", (data) => data);
   return 0;
 }
-function stringFlag2(args, name) {
+function stringFlag3(args, name) {
   const value = args.flags[name];
   return typeof value === "string" && value.trim() !== "" ? value : void 0;
 }
 function requireIdFlag(args, name, usage2) {
-  const value = stringFlag2(args, name);
+  const value = stringFlag3(args, name);
   if (value === void 0) fail(`--${name} is required
 ${usage2}`, 2);
   return value;
@@ -4528,7 +4661,7 @@ function requireTemplateIdPositional(args, usage2) {
   return templateId;
 }
 function intFlag(args, name, usage2) {
-  const raw = stringFlag2(args, name);
+  const raw = stringFlag3(args, name);
   if (raw === void 0) return void 0;
   const n = Number(raw);
   if (!Number.isInteger(n) || n < 1) {
@@ -4538,7 +4671,7 @@ ${usage2}`, 2);
   return n;
 }
 function parseIdsFlag(args, usage2) {
-  const raw = stringFlag2(args, "ids");
+  const raw = stringFlag3(args, "ids");
   if (raw === void 0) fail(`--ids is required (comma-separated)
 ${usage2}`, 2);
   const ids = raw.split(",").map((s) => s.trim()).filter(Boolean);
@@ -4588,7 +4721,7 @@ ${usage2}`, 2);
   });
 }
 function buildTemplateUpsertBody(args, usage2) {
-  const name = stringFlag2(args, "name");
+  const name = stringFlag3(args, "name");
   if (name === void 0) fail(`--name is required
 ${usage2}`, 2);
   const sectionsRaw = args.flags["sections-json"];
@@ -6013,6 +6146,70 @@ var kbAclGroup = group("acl", "Manage direct knowledge-base grants and inspect e
     examples: [{ command: "ctxdb kb acl delete <acl-id> --json" }]
   }))
 ]);
+var graphKbOption = option("--kb", "Knowledge-base ID (not a name).", { valueName: "kb-id", required: true });
+var graphEntityIdOption = option("--entity-id", "Exact entity ID within the knowledge base.", { valueName: "id", required: true });
+var graphRelationIdOption = option("--relation-id", "Exact relation ID within the knowledge base.", { valueName: "id", required: true });
+var graphEntityFields = [
+  option("--name", "Complete entity name.", { valueName: "name", required: true }),
+  option("--type", "Complete entity type.", { valueName: "type", required: true }),
+  option("--description", "Complete description; use --description='' for empty text.", { valueName: "text", required: true }),
+  option("--aliases-json", "Complete string array; use '[]' for no aliases.", { valueName: "json-array", type: "json", required: true })
+];
+var graphRelationFields = [
+  option("--relation-type", "Complete relation type.", { valueName: "type", required: true }),
+  option("--description", "Complete description; use --description='' for empty text.", { valueName: "text", required: true }),
+  option("--keywords-json", "Complete string array; use '[]' for no keywords.", { valueName: "json-array", type: "json", required: true }),
+  option("--weight", "Relation weight between 0 and 1; range checked by the server.", { valueName: "number", type: "number", required: true })
+];
+var graphMutationOutput = [AGENT_OPTION, RAW_OPTION, JSON_OPTION];
+var graphDeleteConfirmation = option("--yes", "Explicitly confirm irreversible deletion; required in terminals and scripts.", { type: "boolean", required: true });
+var graphMutationUsage = (command) => [`${GRAPH_MUTATION_USAGE[command]} [--agent=<name>] [--raw] [--json]`];
+var graphMutationCommands = [
+  leaf("entity-create", "Create one knowledge-graph entity.", kbEntityCreate, details({
+    usage: graphMutationUsage("entity-create"),
+    options: [graphKbOption, ...graphEntityFields, ...graphMutationOutput],
+    notes: ["Returns the server-assigned entity ID and editable fields. This operates on the KB graph, independently of memory entities."],
+    examples: [{ command: "ctxdb kb entity-create --kb=<kb-id> --name=ContextDB --type=Product --description='Context database' --aliases-json='[]' --json" }]
+  })),
+  leaf("entity-update", "Replace the editable fields of one knowledge-graph entity.", kbEntityUpdate, details({
+    usage: graphMutationUsage("entity-update"),
+    options: [graphKbOption, graphEntityIdOption, ...graphEntityFields, ...graphMutationOutput],
+    warnings: ["Full replacement: read entity-get first and supply all editable fields. Empty description/aliases explicitly clear them.", "Renaming preserves the entity ID and updates incident relation names. The server rejects renames exceeding its incident-relation limit."],
+    examples: [{ command: "ctxdb kb entity-update --kb=<kb-id> --entity-id=<id> --name=ContextDB --type=Product --description='' --aliases-json='[]' --json" }]
+  })),
+  leaf("entity-delete", "Irreversibly delete an entity and all incoming/outgoing relations.", kbEntityDelete, details({
+    usage: graphMutationUsage("entity-delete"),
+    options: [graphKbOption, graphEntityIdOption, graphDeleteConfirmation, ...graphMutationOutput],
+    warnings: ["Irreversible: deletes the selected entity and every incident relation. No delete request is sent without --yes."],
+    notes: ["Only exact IDs are accepted; names and bulk deletion are unsupported.", "Returns deleted, deleted_entity_count and deleted_relation_count from the server. A false deleted result exits 1."],
+    examples: [{ command: "ctxdb kb entity-delete --kb=<kb-id> --entity-id=<id> --yes --json" }]
+  })),
+  leaf("relation-create", "Create one relation between knowledge-graph entity IDs.", kbRelationCreate, details({
+    usage: graphMutationUsage("relation-create"),
+    options: [
+      graphKbOption,
+      option("--source-entity-id", "Existing source entity ID.", { valueName: "id", required: true }),
+      option("--target-entity-id", "Existing target entity ID.", { valueName: "id", required: true }),
+      ...graphRelationFields,
+      ...graphMutationOutput
+    ],
+    examples: [{ command: "ctxdb kb relation-create --kb=<kb-id> --source-entity-id=<a> --target-entity-id=<b> --relation-type=USES --description='' --keywords-json='[]' --weight=1 --json" }]
+  })),
+  leaf("relation-update", "Replace the editable fields of one knowledge-graph relation.", kbRelationUpdate, details({
+    usage: graphMutationUsage("relation-update"),
+    options: [graphKbOption, graphRelationIdOption, ...graphRelationFields, ...graphMutationOutput],
+    warnings: ["Full replacement: read relations --verbose first and supply all editable fields. Empty description/keywords explicitly clear them."],
+    constraints: ["Relation ID and source/target entity IDs cannot be changed."],
+    examples: [{ command: "ctxdb kb relation-update --kb=<kb-id> --relation-id=<id> --relation-type=USES --description='' --keywords-json='[]' --weight=1 --json" }]
+  })),
+  leaf("relation-delete", "Irreversibly delete one knowledge-graph relation.", kbRelationDelete, details({
+    usage: graphMutationUsage("relation-delete"),
+    options: [graphKbOption, graphRelationIdOption, graphDeleteConfirmation, ...graphMutationOutput],
+    warnings: ["Irreversible: deletes only this relation; both endpoint entities remain. No delete request is sent without --yes."],
+    notes: ["Only exact relation IDs are accepted. Returns deleted from the server; a false result exits 1. The relation API does not return deletion counts."],
+    examples: [{ command: "ctxdb kb relation-delete --kb=<kb-id> --relation-id=<id> --yes --json" }]
+  }))
+];
 var kbGroup = group("kb", "Manage knowledge bases, documents, retrieval, graph, and review.", [
   leaf("create", "Create a knowledge base.", kbCreate, details({
     usage: ["ctxdb kb create <kb-name> [--description=<text>] [--graph-enabled|--no-graph-enabled] [--review-enabled|--no-review-enabled] [--agent=<name>] [--json]"],
@@ -6277,6 +6474,7 @@ var kbGroup = group("kb", "Manage knowledge bases, documents, retrieval, graph,
     notes: ["--entity-id matches either endpoint; --entity-ids requires both endpoints in the supplied set."],
     examples: [{ command: "ctxdb kb relations --kb=<kb-id> --entity-id=<id> --verbose --json" }]
   })),
+  ...graphMutationCommands,
   reviewGroup
 ]);
 function createCommandTree(options = {}) {

package/dist/setup/skills/contextdb-knowledge/SKILL.md

@@ -143,6 +143,10 @@ init 使用 PUT，part/complete 保持原协议；网络结果不明确时不自
 
 | 子命令 | minimal signature |
 |---|---|
+| `kb entity-create / entity-update` | `ctxdb kb entity-create --help` / `ctxdb kb entity-update --help` |
+| `kb relation-create / relation-update` | `ctxdb kb relation-create --help` / `ctxdb kb relation-update --help` |
+| `kb entity-delete` | `ctxdb kb entity-delete --kb=<kb-id> --entity-id=<id> --yes --agent=<name>` |
+| `kb relation-delete` | `ctxdb kb relation-delete --kb=<kb-id> --relation-id=<id> --yes --agent=<name>` |
 | `kb search` | `ctxdb kb search "<query>" --agent=<name>` |
 | `kb list` | `ctxdb kb list --agent=<name>` |
 | `kb documents-list` | `ctxdb kb documents-list <kb-name> [--sort-by=created_at] [--sort-order=asc|desc] [--fields=field1,field2] --agent=<name>` |
@@ -156,6 +160,11 @@ init 使用 PUT，part/complete 保持原协议；网络结果不明确时不自
 | `kb update-text` | `ctxdb kb update-text <document-id> --text="<body>" --agent=<name>` |
 | `kb update-file` | `ctxdb kb update-file <document-id> <local-path> --agent=<name>` |
 
+图谱写命令的 `--kb` 必须是 KB ID；用 `entities` 和 `relations --verbose` 获取实体/关系 ID。
+create/update 需要完整可编辑字段，update 是全量替换，先回读再修改；空描述和空列表必须显式传入。
+删除不可恢复，实体删除会级联清除全部入边和出边，关系删除保留两端实体。确认用户授权及精确 ID 后
+才使用 `--yes`；省略确认时不会发送删除请求。命令结果不明确时先回读，不要直接重试。
+
 所有命令 JSON 写 stdout、错误写 stderr 非零退出码。
 
 ## 4. Hooks 感知

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliyunrds/ctxdb",
-  "version": "1.0.9-beta.1",
+  "version": "1.0.9",
   "type": "module",
   "description": "Unified access layer for RDS ContextDatabase: `ctxdb` CLI (memory + KB ops), one-shot multi-agent installer, per-agent config, hooks/plugins, and SKILL.md.",
   "license": "Apache-2.0",
@@ -34,7 +34,7 @@
   "dependencies": {
     "semver": "^7.8.5",
     "yaml": "^2.9.0",
-    "@aliyunrds/ctxdb-shared": "~0.0.9-beta.0"
+    "@aliyunrds/ctxdb-shared": "~0.0.9"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",