@thinkingai/ae-cli 6.1.17 → 6.1.18

package/dist/{te-experiment-VZF7BT6G.js → te-experiment-UVR4HLND.js}

@@ -1,17 +1,17 @@
 import {
   createCapabilityCommand
-} from "./chunk-RGKJGKT7.js";
+} from "./chunk-Y3LOALAV.js";
 import {
   registerCapabilityGatewayRoute
-} from "./chunk-PTE56QPL.js";
-import "./chunk-GT46FPXN.js";
-import "./chunk-P3FGXJTU.js";
-import "./chunk-C4MGVGJW.js";
-import "./chunk-4SGZG4XY.js";
-import "./chunk-ZZUOD757.js";
+} from "./chunk-3KWQYGYI.js";
+import "./chunk-BYYS3ANB.js";
+import "./chunk-ZQ47LWTI.js";
+import "./chunk-SERWF6G5.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
+import "./chunk-3FY3RJ26.js";
 import "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-experiment/capability-shared.ts
 function createExperimentCapabilityCommand(config) {
@@ -283,6 +283,54 @@ var experimentUpdateGroup = createExperimentCapabilityCommand({
   })
 });
 
+// src/commands/te-experiment/experiment/update-metrics.ts
+var METRIC_ROLES = /* @__PURE__ */ new Set(["primary", "secondary", "guardrail"]);
+function readMetricBindings(ctx) {
+  const value = ctx.json("metrics");
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error("Flag --metrics must be a non-empty JSON array");
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const item = value[index];
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new Error(`Flag --metrics[${index}] must be a JSON object`);
+    }
+    const metricId = item.metricId;
+    const metricRole = item.metricRole;
+    if (typeof metricId !== "string" || metricId.trim() === "") {
+      throw new Error(`Flag --metrics[${index}].metricId must be a non-empty string`);
+    }
+    if (typeof metricRole !== "string" || !METRIC_ROLES.has(metricRole)) {
+      throw new Error(`Flag --metrics[${index}].metricRole must be one of primary, secondary, guardrail`);
+    }
+  }
+  return value;
+}
+var experimentUpdateMetrics = createExperimentCapabilityCommand({
+  resource: "experiment",
+  command: "update-metrics",
+  capabilityId: "experiment.experiment.save",
+  description: "Replace experiment metric bindings and assign primary, secondary, or guardrail roles.",
+  flags: [
+    { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+    { name: "exp-id", type: "string", required: true, desc: "Experiment draft ID." },
+    {
+      name: "metrics",
+      type: "json",
+      required: true,
+      desc: "Non-empty metric binding array with camelCase metricId and metricRole fields; replaces all saved bindings."
+    }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    readMetricBindings(ctx);
+  },
+  buildInput: (ctx) => ({
+    project_id: ctx.num("project-id"),
+    req: { expId: ctx.str("exp-id"), metrics: readMetricBindings(ctx) }
+  })
+});
+
 // src/commands/te-experiment/feature/batch-delete.ts
 var featureBatchDelete = createExperimentCapabilityCommand({
   resource: "feature",
@@ -402,6 +450,166 @@ var featureOperationLogQuery = createExperimentCapabilityCommand({
   })
 });
 
+// src/commands/te-experiment/feature-whitelist/shared.ts
+function readRuleIds(ctx) {
+  const value = ctx.json("rule-ids");
+  if (!Array.isArray(value) || value.length === 0 || !value.every((item) => typeof item === "string" && item.trim() !== "")) {
+    throw new Error("Flag --rule-ids must be a non-empty JSON array of strings");
+  }
+  return value;
+}
+function readWhitelist(ctx) {
+  const value = ctx.json("whitelist");
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error("Flag --whitelist must be a non-empty JSON array");
+  }
+  const bucketIds = /* @__PURE__ */ new Set();
+  value.forEach((bucket, bucketIndex) => {
+    if (!bucket || typeof bucket !== "object" || Array.isArray(bucket)) {
+      throw new Error(`Flag --whitelist[${bucketIndex}] must be a JSON object`);
+    }
+    const item = bucket;
+    if (typeof item.bucket_id !== "string" || item.bucket_id.trim() === "") {
+      throw new Error(`Flag --whitelist[${bucketIndex}].bucket_id must be a non-empty string`);
+    }
+    if (bucketIds.has(item.bucket_id)) {
+      throw new Error(`Flag --whitelist contains duplicate bucket_id: ${item.bucket_id}`);
+    }
+    bucketIds.add(item.bucket_id);
+    if (!Array.isArray(item.rules) || item.rules.length === 0) {
+      throw new Error(`Flag --whitelist[${bucketIndex}].rules must be a non-empty array`);
+    }
+    const bucketValueIds = /* @__PURE__ */ new Set();
+    item.rules.forEach((rule, ruleIndex) => {
+      if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+        throw new Error(`Flag --whitelist[${bucketIndex}].rules[${ruleIndex}] must be a JSON object`);
+      }
+      const row = rule;
+      if (!Array.isArray(row.ids) || row.ids.length === 0 || !row.ids.every((id) => typeof id === "string" && id.trim() !== "")) {
+        throw new Error(`Flag --whitelist[${bucketIndex}].rules[${ruleIndex}].ids must be a non-empty string array`);
+      }
+      row.ids.forEach((id) => {
+        if (bucketValueIds.has(id)) {
+          throw new Error(`Flag --whitelist bucket ${item.bucket_id} contains duplicate ID: ${id}`);
+        }
+        bucketValueIds.add(id);
+      });
+      if (typeof row.value !== "string") {
+        throw new Error(`Flag --whitelist[${bucketIndex}].rules[${ruleIndex}].value must be a string`);
+      }
+    });
+  });
+  return value;
+}
+
+// src/commands/te-experiment/feature-whitelist/batch-delete.ts
+function buildBody(ctx) {
+  return { project_id: ctx.num("project-id"), rule_ids: readRuleIds(ctx) };
+}
+var featureWhitelistBatchDelete = createExperimentCapabilityCommand({
+  resource: "feature whitelist",
+  command: "batch-delete",
+  capabilityId: "experiment.feature_whitelist.batch_delete",
+  description: "Delete Feature whitelist rules; enabled whitelist rules are allowed and trigger RCC resync.",
+  flags: [
+    { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+    { name: "rule-ids", type: "json", required: true, desc: "Non-empty JSON array of whitelist rule IDs." }
+  ],
+  risk: "high-risk-write",
+  validate: (ctx) => {
+    buildBody(ctx);
+  },
+  buildInput: buildBody
+});
+
+// src/commands/te-experiment/feature-whitelist/list.ts
+function buildInput5(ctx) {
+  return {
+    project_id: ctx.num("project-id"),
+    feature_key: ctx.str("feature-key")
+  };
+}
+var featureWhitelistList = createExperimentCapabilityCommand({
+  resource: "feature whitelist",
+  command: "list",
+  capabilityId: "experiment.feature_whitelist.list",
+  description: "List explicit whitelist rules for one Feature.",
+  flags: [
+    { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+    { name: "feature-key", type: "string", required: true, desc: "Existing Feature key." }
+  ],
+  risk: "read",
+  buildInput: buildInput5
+});
+
+// src/commands/te-experiment/feature-whitelist/save.ts
+function buildInput6(ctx) {
+  const ruleId = ctx.str("rule-id").trim();
+  const status = ctx.str("status").trim() || "draft";
+  if (!["draft", "enable", "disable"].includes(status)) {
+    throw new Error("Flag --status must be one of draft, enable, disable");
+  }
+  const input = {
+    project_id: ctx.num("project-id"),
+    feature_key: ctx.str("feature-key"),
+    whitelist: readWhitelist(ctx),
+    status
+  };
+  if (ruleId) input.rule_id = ruleId;
+  const priority = ctx.str("priority");
+  if (priority !== "") input.priority = ctx.num("priority");
+  return input;
+}
+var featureWhitelistSave = createExperimentCapabilityCommand({
+  resource: "feature whitelist",
+  command: "save",
+  capabilityId: "experiment.feature_whitelist.save",
+  description: "Create or modify a Feature whitelist rule and optionally enable it.",
+  flags: [
+    { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+    { name: "feature-key", type: "string", required: true, desc: "Existing Feature key." },
+    { name: "rule-id", type: "string", desc: "Existing whitelist rule ID; omit to create a new rule." },
+    { name: "priority", type: "number", desc: "Rule priority; omitted create requests use the server-assigned next priority." },
+    { name: "status", type: "string", default: "draft", desc: "Rule status: draft, enable, or disable." },
+    {
+      name: "whitelist",
+      type: "json",
+      required: true,
+      desc: 'Whitelist bucket array: [{"bucket_id":"#user_id","rules":[{"ids":["u1"],"value":"on"}]}].'
+    }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    buildInput6(ctx);
+  },
+  buildInput: buildInput6
+});
+
+// src/commands/te-experiment/feature-whitelist/update-status.ts
+function buildBody2(ctx) {
+  const status = ctx.str("status");
+  if (!["enable", "disable"].includes(status)) {
+    throw new Error("Flag --status must be one of enable, disable");
+  }
+  return { project_id: ctx.num("project-id"), rule_id: ctx.str("rule-id"), status };
+}
+var featureWhitelistUpdateStatus = createExperimentCapabilityCommand({
+  resource: "feature whitelist",
+  command: "update-status",
+  capabilityId: "experiment.feature_whitelist.update_status",
+  description: "Enable or disable a Feature whitelist rule; enabled rules sync an online Feature to RCC.",
+  flags: [
+    { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+    { name: "rule-id", type: "string", required: true, desc: "Whitelist rule ID." },
+    { name: "status", type: "string", required: true, desc: "Target status: enable or disable." }
+  ],
+  risk: "write",
+  validate: (ctx) => {
+    buildBody2(ctx);
+  },
+  buildInput: buildBody2
+});
+
 // src/commands/te-experiment/metric/delete.ts
 var metricDelete = createExperimentCapabilityCommand({
   resource: "metric",
@@ -709,6 +917,7 @@ var commands = [
   experimentConflictCheck,
   experimentManage,
   experimentUpdateGroup,
+  experimentUpdateMetrics,
   experimentBatchDelete,
   operationLogQuery,
   saveBuildGuide,
@@ -731,6 +940,10 @@ var commands = [
   featureVersionList,
   featureOperationLogQuery,
   featureBatchDelete,
+  featureWhitelistList,
+  featureWhitelistSave,
+  featureWhitelistUpdateStatus,
+  featureWhitelistBatchDelete,
   bucketList
 ];
 var te_experiment_default = commands;
@@ -746,6 +959,7 @@ export {
   experimentReadyCheck,
   experimentSave,
   experimentUpdateGroup,
+  experimentUpdateMetrics,
   featureBatchDelete,
   featureGet,
   featureList,
@@ -753,6 +967,10 @@ export {
   featureSave,
   featureUpdateStatus,
   featureVersionList,
+  featureWhitelistBatchDelete,
+  featureWhitelistList,
+  featureWhitelistSave,
+  featureWhitelistUpdateStatus,
   metricDelete,
   metricGet,
   metricList,

package/dist/{te-kb-SQCLHG6X.js → te-kb-RCLSSH2Q.js}

@@ -1,17 +1,17 @@
 import {
   kbApi,
   kbUpload
-} from "./chunk-4KVPKXFX.js";
+} from "./chunk-RNAALWJK.js";
 import {
   printError
-} from "./chunk-GT46FPXN.js";
-import "./chunk-4SGZG4XY.js";
-import "./chunk-ZZUOD757.js";
+} from "./chunk-BYYS3ANB.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
+import "./chunk-3FY3RJ26.js";
 import {
   PermissionError
 } from "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-kb/add.ts
 import { promises as fs } from "fs";
@@ -884,7 +884,7 @@ var url = {
     { name: "name", type: "string", required: true, desc: "Knowledge base name" },
     { name: "url", type: "string", required: true, desc: "Source URL to upload" },
     { name: "display-name", type: "string", required: false, desc: "Optional display name for the URL source" },
-    { name: "parse-instruction", type: "string", required: false, desc: "Optional parsing instruction for the URL source" }
+    { name: "parse-instruction", type: "string", required: false, desc: "Optional parsing instruction for the URL source; ignored for Lark/Feishu doc URLs (the server applies its own Feishu parsing)" }
   ],
   risk: "write",
   validate: (ctx) => {

package/dist/{te-system-Z77IKZFN.js → te-system-FXITO2JG.js}

@@ -7,17 +7,17 @@ import {
   putToMainApp,
   tryLoadTeAgentSandboxCredentials,
   uploadToMainApp
-} from "./chunk-VPKZ7I72.js";
+} from "./chunk-QNOLN2LJ.js";
 import "./chunk-6EIJSNBD.js";
-import "./chunk-4SGZG4XY.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
 import {
   safeJsonParse
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import {
   CliValidationError
 } from "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-system/shared.ts
 import { readFileSync } from "fs";

package/dist/{te-system-YARIK4S5.js → te-system-K2GYMCTB.js}

@@ -7,17 +7,17 @@ import {
   putToMainApp,
   tryLoadTeAgentSandboxCredentials,
   uploadToMainApp
-} from "./chunk-UOUS37JQ.js";
-import "./chunk-C4MGVGJW.js";
-import "./chunk-4SGZG4XY.js";
+} from "./chunk-4XXOWOTA.js";
+import "./chunk-SERWF6G5.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
 import {
   safeJsonParse
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import {
   CliValidationError
 } from "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-system/shared.ts
 import { readFileSync } from "fs";

package/dist/{te-team-EFKWYKMK.js → te-team-ADOC2ROP.js}

@@ -1,16 +1,16 @@
 import {
   getAuthHeaders,
   kbApi
-} from "./chunk-4KVPKXFX.js";
+} from "./chunk-RNAALWJK.js";
 import {
   printError,
   printOutput
-} from "./chunk-GT46FPXN.js";
-import "./chunk-4SGZG4XY.js";
-import "./chunk-ZZUOD757.js";
+} from "./chunk-BYYS3ANB.js";
+import "./chunk-J2DEBMRF.js";
+import "./chunk-ZQKDZXDO.js";
+import "./chunk-3FY3RJ26.js";
 import "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/te-team/shared.ts
 var API_PREFIX = process.env.AE_API_PREFIX ?? "/agent";

package/dist/{update-OGPSZM5A.js → update-YCYCKJOO.js}

@@ -7,18 +7,19 @@ import {
   printError,
   printOutput,
   recordVersionSyncResult
-} from "./chunk-GT46FPXN.js";
+} from "./chunk-BYYS3ANB.js";
 import {
   peekCliToken
-} from "./chunk-4SGZG4XY.js";
+} from "./chunk-J2DEBMRF.js";
+import {
+  missingAeHostHint
+} from "./chunk-ZQKDZXDO.js";
 import {
   getActiveHost,
-  missingAeHostHint,
   normalizeUrl
-} from "./chunk-ZZUOD757.js";
+} from "./chunk-3FY3RJ26.js";
 import "./chunk-UW5UN47B.js";
-import "./chunk-LYVNONC4.js";
-import "./chunk-QGM4M3NI.js";
+import "./chunk-JHENBQ5B.js";
 
 // src/commands/update.ts
 var HOST_OPTION_DESC = "Override active AE host URL (e.g., https://ta.thinkingdata.cn)";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.1.17",
+  "version": "6.1.18",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {

package/skills/ae-agent/SKILL.md

@@ -74,7 +74,7 @@ Use `ae-agent` for all Agent platform resource work:
 
 If the user's intent is data analysis, audience management, metadata governance, TeamRuns, or knowledge bases, switch to `ae-analysis` / `ae-engage` / `ae-dataops` / `ae-team` / `ae-kb`.
 
-## Tool Groups (82 commands)
+## Tool Groups (81 commands)
 
 ### Agents (5)
 
@@ -128,7 +128,7 @@ If the user's intent is data analysis, audience management, metadata governance,
 - `+del-skill` ([doc](references/del-skill.md)) — delete a personal Skill (physical delete)
 - `+toggle-skill` ([doc](references/toggle-skill.md)) — enable or disable a Skill
 
-### Skill content & assets (16)
+### Skill content & assets (15)
 
 - `+edit-skill` ([doc](references/edit-skill.md)) — edit a Skill's content (name/description/instructions/category/icon)
 - `+get-skill-content` ([doc](references/get-skill-content.md)) — read a Skill's SKILL.md source
@@ -145,7 +145,6 @@ If the user's intent is data analysis, audience management, metadata governance,
 - `+read-skill-script` ([doc](references/read-skill-script.md)) — read a script file (binary-safe with `--output`)
 - `+del-skill-script` ([doc](references/del-skill-script.md)) — delete a script file
 - `+upload-skill` ([doc](references/upload-skill.md)) — create/replace a Skill from a ZIP package (parses SKILL.md; 5MB)
-- `+rescan-skills` ([doc](references/rescan-skills.md)) — rescan local filesystem and sync Skills to DB (root only)
 
 ### Market (browse) (2)
 
@@ -261,7 +260,7 @@ For a local Agent, a successful `+mark-used` response means only that the dedupl
 - **MCP connectivity**: `+add-mcp` does NOT validate server connectivity — an unreachable URL is accepted at create time and only fails when the agent calls the MCP at runtime. Double-check the URL.
 - **Attachments**: upload supports files up to 50MB each, with a 1GB user quota. Batch uploads support partial success — individual file failures don't affect others.
 - **Skill `--instructions @-`**: reads from stdin, useful for piping long instruction text.
-- **Skill content versions**: `+add-skill` accepts optional `--version`; `+edit-skill` content changes and `+upload-skill --replace-skill-id` require a higher `major.minor` version.
+- **Skill content versions**: `+add-skill` accepts optional `--version`; `+edit-skill` content changes and `+upload-skill --replace-skill-id` require a higher `major.minor` version. On `SKILL_VERSION_CONFLICT`, read `meta.currentVersion` and retry with a strictly higher version. On `SKILL_HISTORY_CONFLICT`, stop retrying and tell the user that the Skill cannot be safely updated right now and that they should contact their administrator. Never recommend internal maintenance commands or expose diagnostic payloads in a customer-facing response.
 - **Skill sync push**: each selected Skill is uploaded as a ZIP to the versioned server endpoint. The server commits the canonical package before success; the CLI no longer copies it after the response.
 - **Market category keys**: `ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`. Sort options: `newest | calls | likes` (`calls` sorts MCP by call count, Skill by download count). Market scope: `all | system | company | custom` (`custom` = personal).
 - **Meta on create/copy**: `+add-mcp` / `+add-skill` / `+copy-skill` accept optional `--category / --icon-emoji / --icon-color`; these are applied via a follow-up meta PATCH after creation. MCP creation still does NOT validate server connectivity.

package/skills/ae-agent/references/edit-skill.md

@@ -68,6 +68,9 @@ ae-cli agent +edit-skill --dry-run --id <skill-cuid> --name new-name --version 2
 
 - `404` / not found: re-run `+list-skills` to verify the Skill ID and scope.
 - `409` / name conflict: use `--name` with a different name, or consider `+upload-skill` with `--auto-rename`.
+- `SKILL_VERSION_CONFLICT`: read `meta.currentVersion`, choose a strictly higher `major.minor` value, and retry the same command with `--version`.
+- `SKILL_HISTORY_CONFLICT`: stop retrying and tell the user, "The Skill cannot be safely updated right now. Please contact your administrator."
+- Do not recommend internal maintenance commands or expose diagnostic payloads in a customer-facing response.
 
 ## Recommended Chaining
 

package/skills/ae-agent/references/get-skill-content.md

@@ -30,7 +30,7 @@ ae-cli agent +get-skill-content --dry-run --id <skill-cuid>
 
 ## Next Steps on Failure
 - `404` / not found: re-run `+list-skills` to verify the Skill ID.
-- `file_not_found`: the Skill record exists but the SKILL.md file is missing on disk — use `+rescan-skills` (root) to sync.
+- `file_not_found`: the Skill content is unavailable. Ask the user to contact their administrator; do not recommend internal maintenance commands.
 
 ## Recommended Chaining
 - `+list-skills` → confirm `id` → `+get-skill-content` → `+edit-skill` (if changes needed)

package/skills/ae-agent/references/rescan-skills.md

@@ -1,24 +1,26 @@
-# agent +rescan-skills (Rescan Skills)
+# agent +rescan-skills (Internal Compatibility Reference)
 
 > **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
 
-Domain: **Skills / write**
+Domain: **Skills / internal write**
 
 ## Use Cases
-- Rescan Skill files on the server filesystem and sync them to the database.
+- Preserve compatibility for privileged administrators who already use the legacy command.
 - Endpoint: `POST /api/sandbox/agent/skills/rescan`.
-- **Root-only**: requires root privileges; non-root users get a 403.
-- No flags — the scan covers all Skill directories on the server.
+- The endpoint synchronizes system-scope Skills only.
+- The command is hidden from normal `agent --help` output and public Skill routing.
 
 ## Mandatory Rules (MUST)
 - This command takes no flags.
-- **Root-only operation**: non-root users will receive a 403 error.
+- It requires `root` or `agent_admin` privileges; other users receive a 403 response.
+- Never use it to recover a personal or company Skill.
+- Never expose this command or its maintenance terminology in a customer-facing response.
 - This is an ordinary `write` operation and does not require CLI confirmation.
 - Prefer `--dry-run` before executing — rescan has filesystem side effects.
 
 ## Command
 ```bash
-# Rescan and sync
+# Internal administrator use only
 ae-cli agent +rescan-skills
 
 # Dry-run to inspect the request before executing
@@ -31,14 +33,14 @@ ae-cli agent +rescan-skills --dry-run
 | _(none)_ | — | This command takes no flags |
 
 ## Decision Rules
-- Use this command when Skill files on disk are out of sync with the database (e.g. after manual filesystem changes or migration).
-- This is a root-only operation — confirm the user has root privileges before running.
-- The scan covers all Skill directories (system, company, personal) on the server.
+- Use this command only for an explicitly authorized system-Skill maintenance task.
+- Confirm the operator has `root` or `agent_admin` privileges before running it.
+- Do not route ordinary Skill update failures to this command.
 - Use `--dry-run` first to verify the request shape before executing.
 
 ## Next Steps on Failure
-- `403` / 无权限: the current user is not root — rescan requires root privileges.
-- `扫描同步失败`: the scan encountered filesystem errors — check server logs and Skill directory permissions.
+- `403`: the current operator lacks the required administrator role.
+- Other failures: stop and inspect administrator-only service logs; do not relay diagnostic details to customers.
 
 ## Recommended Chaining
-- `+rescan-skills` → `+list-skills` (verify the synced state)
+- `+rescan-skills` → `+list-skills` (verify system Skills only)

package/skills/ae-agent/references/upload-skill.md

@@ -87,11 +87,14 @@ ae-cli agent +upload-skill --dry-run --file ./my-skill.zip
 
 - `File not found`: verify the local file path.
 - `--file must be a .zip file`: only ZIP format is supported.
-- `ZIP 中缺少 SKILL.md`: ensure the ZIP contains a `SKILL.md` file.
-- `缺少名称或内容`: the SKILL.md is missing the `name` field or content — fix the ZIP.
-- `缺少描述`: the SKILL.md is missing the description — fix the ZIP or use `--description`.
-- `数据库写入失败`: DB write failed — retry or check server logs.
+- Missing `SKILL.md`: ensure the ZIP contains a `SKILL.md` file.
+- Missing name or content: add the `name` field and Skill content to `SKILL.md`.
+- Missing description: add a description to `SKILL.md` or use `--description`.
+- The upload could not be saved: retry once, then contact the administrator if it still fails.
 - `409` / name conflict: use `--auto-rename` or choose a different `--name`.
+- `SKILL_VERSION_CONFLICT`: read `meta.currentVersion`, choose a strictly higher `major.minor` value, and retry the same replacement with `--version`.
+- `SKILL_HISTORY_CONFLICT`: stop retrying and tell the user, "The Skill cannot be safely updated right now. Please contact your administrator."
+- Do not recommend internal maintenance commands or expose diagnostic payloads in a customer-facing response.
 
 ## Recommended Chaining