@kweaver-ai/kweaver-sdk 0.8.1 → 0.8.3

package/dist/commands/agent.js

@@ -1,6 +1,53 @@
 import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/oauth.js";
+import { renderHelp } from "../help/format.js";
+const AGENT_HELP = renderHelp({
+    tagline: "Agent CRUD, chat, sessions, history, publish/unpublish",
+    usage: "kweaver agent <subcommand> [flags]",
+    sections: [
+        {
+            title: "DISCOVERY",
+            items: [
+                { name: "list", desc: "List published agents" },
+                { name: "personal-list", desc: "List personal-space agents" },
+                { name: "category-list", desc: "List agent categories" },
+                { name: "template-list", desc: "List published agent templates" },
+                { name: "template-get", desc: "Get published agent template details" },
+            ],
+        },
+        {
+            title: "CRUD",
+            items: [
+                { name: "get", desc: "Get agent details" },
+                { name: "get-by-key", desc: "Get agent by key" },
+                { name: "create", desc: "Create a new agent" },
+                { name: "update", desc: "Update an existing agent" },
+                { name: "delete", desc: "Delete an agent" },
+                { name: "publish", desc: "Publish an agent" },
+                { name: "unpublish", desc: "Unpublish an agent" },
+            ],
+        },
+        {
+            title: "RUNTIME",
+            items: [
+                { name: "chat", desc: "Interactive chat (or single message with -m)" },
+                { name: "sessions", desc: "List conversations for an agent" },
+                { name: "history", desc: "Show message history for a conversation" },
+                { name: "trace", desc: "Get trace data for a conversation (--view tree|perf|evidence|reasoning|all)" },
+                { name: "skill", desc: "Manage skills attached to an agent (add / remove / list)" },
+            ],
+        },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver agent list --limit 20",
+        "kweaver agent chat <agent_id> -m \"hello\"",
+        "kweaver agent trace <conversation_id> --view all",
+    ],
+    learnMore: ["Use `kweaver agent <subcommand> --help` for flag details"],
+});
 import { runAgentChatCommand } from "./agent-chat.js";
 import { runAgentSkillCommand } from "./agent-members.js";
+import { AGENT_MODE_HELP, applyAgentModeToConfig, normalizeAgentConfigInput, parseAgentMode, } from "./agent/mode.js";
 import { listAgents, getAgent, getAgentByKey, createAgent, updateAgent, deleteAgent, publishAgent, unpublishAgent, listPersonalAgents, listPublishedAgentTemplates, getPublishedAgentTemplate, listAgentCategories, } from "../api/agent-list.js";
 import { listConversations, listMessages, getTracesByConversation } from "../api/conversations.js";
 import { fetchAgentInfo } from "../api/agent-chat.js";
@@ -47,21 +94,21 @@ export async function resolveLlmName(options) {
     }
 }
 /**
- * 生成带时间戳的文件路径
- * @param path 用户提供的路径
- * @returns 带时间戳的文件路径
+ * Generate a timestamped file path.
+ * @param path User-provided output path.
+ * @returns The timestamped file path.
  */
 function generateTimestampedPath(path) {
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-    // 如果路径以 / 结尾，视为目录，在目录下生成文件
+    // Treat paths ending in / as directories.
     if (path.endsWith("/")) {
         return join(path, `agent-config-${timestamp}.json`);
     }
-    // 在文件名中插入时间戳：config.json -> config-2025-01-15T12-30-45.json
+    // Insert the timestamp before the extension: config.json -> config-2025-01-15T12-30-45.json.
     const ext = extname(path);
     const base = basename(path, ext);
     const dir = dirname(path);
-    // 如果 dir 是 "."，说明没有目录前缀，直接返回带时间戳的文件名
+    // No directory prefix was provided, so return only the timestamped file name.
     if (dir === ".") {
         return `${base}-${timestamp}${ext}`;
     }
@@ -537,30 +584,7 @@ export function parseAgentTraceArgs(args) {
 export async function runAgentCommand(args) {
     const [subcommand, ...rest] = args;
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
-        console.log(`kweaver agent
-
-Subcommands:
-  list [options]                     List published agents
-  personal-list [options]            List personal space agents
-  category-list [options]            List agent categories
-  template-list [options]            List published agent templates
-  template-get <tpl_id>              Get published agent template details
-  get <agent_id> [--verbose]         Get agent details
-  get-by-key <key>                   Get agent by key
-  create --name <n> --profile <p>    Create a new agent
-       [--key <key>] [--product-key <pk>] [--system-prompt <sp>]
-       [--llm-id <id>] [--llm-max-tokens <n>]
-  update <agent_id> [options]        Update an existing agent
-  delete <agent_id> [-y]             Delete an agent
-  publish <agent_id>                 Publish an agent
-  unpublish <agent_id>               Unpublish an agent
-  chat <agent_id>                    Start interactive chat with an agent
-  chat <agent_id> -m "message"       Send a single message (non-interactive)
-  skill <verb> ...                   Manage skills attached to an agent (add/remove/list)
-  sessions <agent_id>                List all conversations for an agent
-  history <agent_id> <conversation_id> Show message history for a conversation
-  trace <conversation_id> [--view tree|perf|evidence|reasoning|all] [--json]
-                                       Get trace data for a conversation`);
+        console.log(AGENT_HELP);
         return Promise.resolve(0);
     }
     const dispatch = async () => {
@@ -603,177 +627,230 @@ Subcommands:
     // Show subcommand-specific help inline (no retry needed)
     if (subcommand === "chat") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent chat <agent_id> [-m "message"] [options]
-
-Interactive mode (default when -m is omitted):
-  kweaver agent chat <agent_id>
-  Type your message and press Enter. Type 'exit', 'quit', or 'q' to quit.
-
-Non-interactive mode:
-  kweaver agent chat <agent_id> -m "your message"
-  kweaver agent chat <agent_id> -m "continue" --conversation-id <id>
-
-Options:
-  -m, --message <text>       Single message (non-interactive)
-  --conversation-id <id>     Continue existing conversation
-  -cid <id>                  Short alias for --conversation-id
-  --session-id <id>          Alias for --conversation-id
-  -conversation_id <id>      Compatibility alias for reference examples
-  --version <value>          Agent version used to resolve the agent key (default: v0)
-  --stream                   Enable streaming (default in interactive)
-  --no-stream                Disable streaming (default with -m)
-  --verbose, -v              Print request details to stderr
-  -bd, --biz-domain <value>  Override x-business-domain (default: bd_public)`);
+            console.log(renderHelp({
+                tagline: "Chat with an agent — interactive (default) or single-shot (-m)",
+                usage: [
+                    "kweaver agent chat <agent_id>                       (interactive)",
+                    "kweaver agent chat <agent_id> -m \"message\"          (single-shot)",
+                    "kweaver agent chat <agent_id> -m \"...\" --conversation-id <id>",
+                ],
+                flags: [
+                    {
+                        title: "Message",
+                        flags: [
+                            { name: "-m, --message <text>", desc: "Single message (non-interactive)" },
+                            { name: "--conversation-id <id>", desc: "Continue existing conversation (aliases: -cid, --session-id, -conversation_id)" },
+                            { name: "--version <value>", desc: "Agent version used to resolve agent key (default: v0)" },
+                        ],
+                    },
+                    {
+                        title: "Streaming",
+                        flags: [
+                            { name: "--stream", desc: "Enable streaming (default in interactive)" },
+                            { name: "--no-stream", desc: "Disable streaming (default with -m)" },
+                        ],
+                    },
+                    {
+                        title: "Common",
+                        flags: [
+                            { name: "--verbose, -v", desc: "Print request details to stderr" },
+                            { name: "-bd, --biz-domain <value>", desc: "Override x-business-domain (default: bd_public)" },
+                        ],
+                    },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: [
+                    "kweaver agent chat agt-123",
+                    "kweaver agent chat agt-123 -m \"hello\"",
+                    "kweaver agent chat agt-123 -m \"continue\" --conversation-id conv-456",
+                    "kweaver agent chat agt-123 -m \"hello\" --no-stream --verbose",
+                ],
+                learnMore: ["Interactive mode: type 'exit', 'quit', or 'q' to quit"],
+            }));
             return Promise.resolve(0);
         }
         return runAgentChatCommand(rest);
     }
     if (subcommand === "get") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent get <agent_id> [options]
-
-Get agent details from the agent-factory API.
-
-Options:
-  --verbose, -v             Show full JSON response
-  -bd, --biz-domain <value>  Business domain (default: bd_public)
-  --pretty                   Pretty-print JSON output (default)
-  --save-config <path>       Save config to file with timestamp (output: <path-with-timestamp>)`);
+            console.log(renderHelp({
+                tagline: "Get agent details from the agent-factory API.",
+                usage: "kweaver agent get <agent_id> [options]",
+                flags: [
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                    { name: "--save-config <path>", desc: "Save config to file with timestamp (output: <path-with-timestamp>)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent get <agent_id>"],
+            }));
             return 0;
         }
     }
     if (subcommand === "update") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent update <agent_id> [options]
-
-Update an existing agent.
-
-Options:
-  --name <text>             Agent name (max 50)
-  --profile <text>          Agent description (max 500)
-  --system-prompt <text>    System prompt
-  --knowledge-network-id <id>  Business knowledge network ID to configure
-  --config-path <path>      Path to config file (read from file instead of API)`);
+            console.log(renderHelp({
+                tagline: "Update an existing agent.",
+                usage: "kweaver agent update <agent_id> [options]",
+                flags: [
+                    { name: "--name <text>", desc: "Agent name (max 50)" },
+                    { name: "--profile <text>", desc: "Agent description (max 500)" },
+                    { name: "--system-prompt <text>", desc: "System prompt" },
+                    { name: "--knowledge-network-id <id>", desc: "Business knowledge network ID to configure" },
+                    { name: "--config-path <path>", desc: "Path to config object file, or full agent JSON with config" },
+                    { name: "--mode <mode>", desc: "Agent mode: default, dolphin, react (default: default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent update <agent_id> --name MyAgent"],
+                learnMore: [AGENT_MODE_HELP],
+            }));
             return 0;
         }
     }
     if (subcommand === "list") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent list [options]
-
-List published agents from the agent-factory API.
-
-Options:
-  --name <text>             Filter by name
-  --offset <n>              Pagination offset (default: 0)
-  --limit <n>               Max items to return (default: 30)
-  --category-id <id>        Filter by category
-  --custom-space-id <id>    Filter by custom space
-  --is-to-square <0|1>      Is to square (default: 1)
-  --verbose, -v             Show full JSON response
-  -bd, --biz-domain <value>  Business domain (default: bd_public)
-  --pretty                  Pretty-print JSON output (applies to both modes)`);
+            console.log(renderHelp({
+                tagline: "List published agents from the agent-factory API.",
+                usage: "kweaver agent list [options]",
+                flags: [
+                    { name: "--name <text>", desc: "Filter by name" },
+                    { name: "--offset <n>", desc: "Pagination offset (default: 0)" },
+                    { name: "--limit <n>", desc: "Max items to return (default: 30)" },
+                    { name: "--category-id <id>", desc: "Filter by category" },
+                    { name: "--custom-space-id <id>", desc: "Filter by custom space" },
+                    { name: "--is-to-square <0|1>", desc: "Is to square (default: 1)" },
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (applies to both modes)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent list --limit 10"],
+            }));
             return 0;
         }
     }
     if (subcommand === "personal-list") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent personal-list [options]
-
-List personal space agents from the agent-factory API.
-
-Options:
-  --name <text>                 Filter by name
-  --pagination-marker <str>     Pagination marker
-  --publish-status <status>     Filter by publish status
-  --publish-to-be <value>       Publish to be filter
-  --size <n>                    Max items to return (default: 48)
-  --verbose, -v                 Show full JSON response
-  -bd, --biz-domain <value>     Business domain (default: bd_public)
-  --pretty                      Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "List personal space agents from the agent-factory API.",
+                usage: "kweaver agent personal-list [options]",
+                flags: [
+                    { name: "--name <text>", desc: "Filter by name" },
+                    { name: "--pagination-marker <str>", desc: "Pagination marker" },
+                    { name: "--publish-status <status>", desc: "Filter by publish status" },
+                    { name: "--publish-to-be <value>", desc: "Publish to be filter" },
+                    { name: "--size <n>", desc: "Max items to return (default: 48)" },
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent personal-list --size 20"],
+            }));
             return 0;
         }
     }
     if (subcommand === "category-list") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent category-list [options]
-
-List agent categories from the agent-factory API.
-
-Options:
-  --verbose, -v             Show full JSON response
-  -bd, --biz-domain <value> Business domain (default: bd_public)
-  --pretty                  Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "List agent categories from the agent-factory API.",
+                usage: "kweaver agent category-list [options]",
+                flags: [
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent category-list"],
+            }));
             return 0;
         }
     }
     if (subcommand === "template-list") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent template-list [options]
-
-List published agent templates from the agent-factory API.
-
-Options:
-  --category-id <id>            Filter by category
-  --name <text>                 Filter by name
-  --pagination-marker <str>     Pagination marker
-  --size <n>                    Max items to return (default: 48)
-  --verbose, -v                 Show full JSON response
-  -bd, --biz-domain <value>     Business domain (default: bd_public)
-  --pretty                      Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "List published agent templates from the agent-factory API.",
+                usage: "kweaver agent template-list [options]",
+                flags: [
+                    { name: "--category-id <id>", desc: "Filter by category" },
+                    { name: "--name <text>", desc: "Filter by name" },
+                    { name: "--pagination-marker <str>", desc: "Pagination marker" },
+                    { name: "--size <n>", desc: "Max items to return (default: 48)" },
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent template-list --size 20"],
+            }));
             return 0;
         }
     }
     if (subcommand === "template-get") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent template-get <template_id> [options]
-
-Get published agent template details from the agent-factory API.
-
-Options:
-  --verbose, -v             Show full JSON response
-  -bd, --biz-domain <value> Business domain (default: bd_public)
-  --pretty                   Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "Get published agent template details from the agent-factory API.",
+                usage: "kweaver agent template-get <template_id> [options]",
+                flags: [
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent template-get <template_id>"],
+            }));
             return 0;
         }
     }
     if (subcommand === "sessions") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent sessions <agent_id> [options]
-
-List all conversations for an agent.
-
-Options:
-  --limit <n>              Max conversations to return (default: 30)
-  -bd, --biz-domain <value> Business domain (default: bd_public)
-  --pretty                  Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "List all conversations for an agent.",
+                usage: "kweaver agent sessions <agent_id> [options]",
+                flags: [
+                    { name: "--limit <n>", desc: "Max conversations to return (default: 30)" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent sessions <agent_id>"],
+            }));
             return 0;
         }
     }
     if (subcommand === "history") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent history <agent_id> <conversation_id> [options]
-
-Show conversation detail (messages) for an agent.
-
-Options:
-  -bd, --biz-domain <value> Business domain (default: bd_public)
-  --pretty                  Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "Show conversation detail (messages) for an agent.",
+                usage: "kweaver agent history <agent_id> <conversation_id> [options]",
+                flags: [
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent history <agent_id> <conversation_id>"],
+            }));
             return 0;
         }
     }
     if (subcommand === "trace") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent trace <conversation_id> [options]
-       kweaver agent trace <agent_id> <conversation_id> [options]   (legacy)
-
-Get trace data for a conversation.
-
-Options:
-  --view tree|perf|evidence|reasoning|all   Render style (default: tree)
-  --json                          Emit raw TracesByConversationResult JSON
-  --pretty                        Pretty-print JSON output (default)
-  --compact                       Compact JSON output`);
+            console.log(renderHelp({
+                tagline: "Get trace data for a conversation.",
+                usage: [
+                    "kweaver agent trace <conversation_id> [options]",
+                    "kweaver agent trace <agent_id> <conversation_id> [options]   (legacy)",
+                ],
+                flags: [
+                    { name: "--view tree|perf|evidence|reasoning|all", desc: "Render style (default: tree)" },
+                    { name: "--json", desc: "Emit raw TracesByConversationResult JSON" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                    { name: "--compact", desc: "Compact JSON output" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent trace <conversation_id>"],
+            }));
             return 0;
         }
     }
@@ -868,15 +945,18 @@ async function runAgentGetCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver agent get <agent_id> [options]
-
-Get agent details from the agent-factory API.
-
-Options:
-  --verbose, -v             Show full JSON response
-  -bd, --biz-domain <value>  Business domain (default: bd_public)
-  --pretty                   Pretty-print JSON output (default)
-  --save-config <path>       Save config to file with timestamp (output: <path-with-timestamp>)`);
+            console.log(renderHelp({
+                tagline: "Get agent details from the agent-factory API.",
+                usage: "kweaver agent get <agent_id> [options]",
+                flags: [
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                    { name: "--save-config <path>", desc: "Save config to file with timestamp (output: <path-with-timestamp>)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent get <agent_id>"],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));
@@ -891,12 +971,12 @@ Options:
             businessDomain: options.businessDomain,
         });
         if (body) {
-            // 如果指定了 --save-config，保存 config 到文件（带时间戳）
+            // Save only the agent config object when --save-config is provided.
             if (options.saveConfig) {
                 const parsed = JSON.parse(body);
                 const config = parsed.config ?? {};
                 const timestampedPath = generateTimestampedPath(options.saveConfig);
-                // 确保目录存在
+                // Ensure the output directory exists.
                 const dir = dirname(timestampedPath);
                 await fs.mkdir(dir, { recursive: true });
                 await fs.writeFile(timestampedPath, JSON.stringify(config, null, 2), "utf-8");
@@ -919,20 +999,23 @@ async function runAgentListCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver agent list [options]
-
-List published agents from the agent-factory API.
-
-Options:
-  --name <text>             Filter by name
-  --offset <n>              Pagination offset (default: 0)
-  --limit <n>               Max items to return (default: 30)
-  --category-id <id>        Filter by category
-  --custom-space-id <id>    Filter by custom space
-  --is-to-square <0|1>      Is to square (default: 1)
-  --verbose, -v             Show full JSON response
-  -bd, --biz-domain <value>  Business domain (default: bd_public)
-  --pretty                  Pretty-print JSON output (applies to both modes)`);
+            console.log(renderHelp({
+                tagline: "List published agents from the agent-factory API.",
+                usage: "kweaver agent list [options]",
+                flags: [
+                    { name: "--name <text>", desc: "Filter by name" },
+                    { name: "--offset <n>", desc: "Pagination offset (default: 0)" },
+                    { name: "--limit <n>", desc: "Max items to return (default: 30)" },
+                    { name: "--category-id <id>", desc: "Filter by category" },
+                    { name: "--custom-space-id <id>", desc: "Filter by custom space" },
+                    { name: "--is-to-square <0|1>", desc: "Is to square (default: 1)" },
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (applies to both modes)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent list"],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));
@@ -968,14 +1051,17 @@ async function runAgentSessionsCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver agent sessions <agent_id> [options]
-
-List all conversations for an agent.
-
-Options:
-  --limit <n>              Max conversations to return (default: 30)
-  -bd, --biz-domain <value> Business domain (default: bd_public)
-  --pretty                  Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "List all conversations for an agent.",
+                usage: "kweaver agent sessions <agent_id> [options]",
+                flags: [
+                    { name: "--limit <n>", desc: "Max conversations to return (default: 30)" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent sessions <agent_id>"],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));
@@ -1021,13 +1107,16 @@ async function runAgentHistoryCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver agent history <agent_id> <conversation_id> [options]
-
-Show conversation detail (messages) for an agent.
-
-Options:
-  -bd, --biz-domain <value> Business domain (default: bd_public)
-  --pretty                  Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "Show conversation detail (messages) for an agent.",
+                usage: "kweaver agent history <agent_id> <conversation_id> [options]",
+                flags: [
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent history <agent_id> <conversation_id>"],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));
@@ -1074,18 +1163,21 @@ async function runAgentTraceCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver agent trace <conversation_id> [options]
-       kweaver agent trace <agent_id> <conversation_id> [options]   (legacy)
-
-Get trace data for a conversation. Spans are fetched from trace-ai via a 2-jump
-lookup that recovers pipeline spans (HTTP entry, internal RPCs, prompt-build)
-which the simpler /by-conversation endpoint omits.
-
-Options:
-  --view tree|perf|evidence|reasoning|all   Render style (default: tree)
-  --json                          Emit raw TracesByConversationResult JSON
-  --pretty                        Pretty-print JSON output (default)
-  --compact                       Compact JSON output`);
+            console.log(renderHelp({
+                tagline: "Get trace data for a conversation. Spans are fetched from trace-ai via a 2-jump lookup that recovers pipeline spans (HTTP entry, internal RPCs, prompt-build) which the simpler /by-conversation endpoint omits.",
+                usage: "kweaver agent trace <conversation_id> [options]",
+                flags: [
+                    { name: "--view tree|perf|evidence|reasoning|all", desc: "Render style (default: tree)" },
+                    { name: "--json", desc: "Emit raw TracesByConversationResult JSON" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                    { name: "--compact", desc: "Compact JSON output" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: [
+                    "kweaver agent trace <conversation_id>",
+                    "kweaver agent trace <agent_id> <conversation_id>   (legacy)",
+                ],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));
@@ -1146,25 +1238,29 @@ async function runAgentCreateCommand(args) {
     let llmMaxTokens = 4096;
     let businessDomain = "";
     let configStr = "";
+    let explicitMode;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h") {
-            console.log(`kweaver agent create --name <name> --profile <profile> [options]
-
-Create a new agent.
-
-Required (when --config is not provided):
-  --name <text>            Agent name (max 50)
-  --profile <text>         Agent description (max 500)
-
-Optional:
-  --key <text>             Agent unique key (auto-generated if omitted)
-  --product-key <text>     Product key: dip, AnyShare, ChatBI (default: dip)
-  --system-prompt <text>   System prompt
-  --llm-id <id>            LLM model ID (required for public API)
-  --llm-max-tokens <n>     LLM max tokens (default: 4096)
-  --config <json|path>     Full config object as JSON string or file path (overrides individual config options)
-  -bd, --biz-domain <val>  Business domain (default: bd_public)`);
+            console.log(renderHelp({
+                tagline: "Create a new agent.",
+                usage: "kweaver agent create --name <name> --profile <profile> [options]",
+                flags: [
+                    { name: "--name <text>", desc: "Agent name (max 50) [required when --config not provided]" },
+                    { name: "--profile <text>", desc: "Agent description (max 500) [required when --config not provided]" },
+                    { name: "--key <text>", desc: "Agent unique key (auto-generated if omitted)" },
+                    { name: "--product-key <text>", desc: "Product key: dip, AnyShare, ChatBI (default: dip)" },
+                    { name: "--system-prompt <text>", desc: "System prompt" },
+                    { name: "--llm-id <id>", desc: "LLM model ID (required for public API)" },
+                    { name: "--llm-max-tokens <n>", desc: "LLM max tokens (default: 4096)" },
+                    { name: "--mode <mode>", desc: "Agent mode: default, dolphin, react (default: default)" },
+                    { name: "--config <json|path>", desc: "Full config object as JSON string or file path (overrides individual config options)" },
+                    { name: "-bd, --biz-domain <val>", desc: "Business domain (default: bd_public)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent create --name MyAgent --profile \"desc\""],
+                learnMore: [AGENT_MODE_HELP],
+            }));
             return 0;
         }
         if (arg === "--name") {
@@ -1195,6 +1291,17 @@ Optional:
             llmMaxTokens = parseInt(args[++i] ?? "4096", 10);
             continue;
         }
+        if (arg === "--mode") {
+            const value = args[++i] ?? "";
+            try {
+                explicitMode = parseAgentMode(value);
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+                return 1;
+            }
+            continue;
+        }
         if (arg === "--config") {
             configStr = args[++i] ?? "";
             continue;
@@ -1241,13 +1348,19 @@ Optional:
             system_prompt: systemPrompt,
         };
     }
+    try {
+        applyAgentModeToConfig(config, explicitMode);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
     const payload = {
         name,
         profile,
         avatar_type: 1,
         avatar: "icon-dip-agent-default",
         product_key: productKey,
-        product_name: "DIP",
         config,
     };
     if (key)
@@ -1276,41 +1389,81 @@ Optional:
 // ── Update ───────────────────────────────────────────────────────────────────
 async function runAgentUpdateCommand(args) {
     const agentId = args[0];
+    if (agentId === "--help" || agentId === "-h") {
+        console.log(renderHelp({
+            tagline: "Update an existing agent.",
+            usage: "kweaver agent update <agent_id> [options]",
+            flags: [
+                { name: "--name <text>", desc: "Agent name" },
+                { name: "--profile <text>", desc: "Agent description" },
+                { name: "--system-prompt <text>", desc: "System prompt" },
+                { name: "--knowledge-network-id <id>", desc: "Knowledge network ID" },
+                { name: "--config-path <path>", desc: "Read config object from file, or full agent JSON with config" },
+                { name: "--mode <mode>", desc: "Agent mode: default, dolphin, react (default: default)" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: ["kweaver agent update <agent_id> --name MyAgent"],
+            learnMore: [AGENT_MODE_HELP],
+        }));
+        return 0;
+    }
     if (!agentId || agentId.startsWith("-")) {
-        console.error("Usage: kweaver agent update <agent_id> [--name <n>] [--profile <p>] [--system-prompt <sp>] [--knowledge-network-id <id> [--config-path <path>]]");
+        console.error("Usage: kweaver agent update <agent_id> [--name <n>] [--profile <p>] [--system-prompt <sp>] [--mode <mode>] [--knowledge-network-id <id> [--config-path <path>]]");
         return 1;
     }
     let knowledgeNetworkId = null;
     let configPath = null;
-    try {
-        const token = await ensureValidToken();
-        let current;
-        let configFromFile = null;
-        // 如果指定了 --config-path，从文件读取配置
-        if (args.includes("--config-path")) {
-            const configPathIndex = args.indexOf("--config-path");
-            configPath = args[configPathIndex + 1] ?? "";
+    let explicitMode;
+    for (let i = 1; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--mode") {
+            const value = args[++i] ?? "";
+            try {
+                explicitMode = parseAgentMode(value);
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+                return 1;
+            }
+            continue;
+        }
+        if (arg === "--config-path") {
+            configPath = args[++i] ?? "";
             if (!configPath || configPath.startsWith("-")) {
                 console.error("Missing value for --config-path flag");
                 return 1;
             }
+            continue;
+        }
+    }
+    try {
+        let current;
+        let configFromFile = null;
+        // Read config from file before fetching the current agent so invalid local config fails early.
+        if (configPath) {
             try {
                 const fileContent = await fs.readFile(configPath, "utf-8");
-                configFromFile = JSON.parse(fileContent);
+                configFromFile = normalizeAgentConfigInput(JSON.parse(fileContent));
+                if (!explicitMode) {
+                    applyAgentModeToConfig(configFromFile);
+                }
             }
             catch (error) {
-                console.error(`Failed to read config from ${configPath}: ${error}`);
+                console.error(error instanceof Error && error.message.startsWith("config.mode")
+                    ? error.message
+                    : `Failed to read config from ${configPath}: ${error}`);
                 return 1;
             }
         }
-        // 从API获取当前 agent 配置
+        const token = await ensureValidToken();
+        // Fetch the current agent for read-modify-write updates.
         const currentRaw = await getAgent({
             baseUrl: token.baseUrl,
             accessToken: token.accessToken,
             agentId,
         });
         current = JSON.parse(currentRaw);
-        // 如果从文件读取了 config，合并到 current 中
+        // Replace only current.config when a config file was provided.
         if (configFromFile) {
             current.config = configFromFile;
         }
@@ -1324,6 +1477,14 @@ async function runAgentUpdateCommand(args) {
                 current.profile = args[++i] ?? current.profile;
                 continue;
             }
+            if (arg === "--mode") {
+                i += 1;
+                continue;
+            }
+            if (arg === "--config-path") {
+                i += 1;
+                continue;
+            }
             if (arg === "--system-prompt") {
                 const config = (current.config ?? {});
                 config.system_prompt = args[++i] ?? "";
@@ -1339,21 +1500,28 @@ async function runAgentUpdateCommand(args) {
                 continue;
             }
         }
-        // 如果指定了 --knowledge-network-id，更新 data_source.knowledge_network
+        // Update config.data_source.knowledge_network when requested.
         if (knowledgeNetworkId) {
             const config = (current.config ?? {});
             const dataSource = (config.data_source ?? {});
-            // 获取知识网络名称（如果需要的话，可以查询BKN获取）
             const knowledgeNetwork = [
                 {
                     knowledge_network_id: knowledgeNetworkId,
-                    knowledge_network_name: "", // 可选：通过BKN API获取名称
                 },
             ];
             dataSource.knowledge_network = knowledgeNetwork;
             config.data_source = dataSource;
             current.config = config;
         }
+        const config = (current.config ?? {});
+        try {
+            applyAgentModeToConfig(config, explicitMode);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+        current.config = config;
         const body = await updateAgent({
             baseUrl: token.baseUrl,
             accessToken: token.accessToken,
@@ -1428,13 +1596,16 @@ async function runAgentPublishCommand(args) {
             continue;
         }
         if (arg === "--help" || arg === "-h") {
-            console.log(`kweaver agent publish <agent_id> [options]
-
-Publish an agent.
-
-Options:
-  --category-id <id>    Category ID for the agent
-  -bd, --biz-domain <value> Business domain (default: bd_public)`);
+            console.log(renderHelp({
+                tagline: "Publish an agent.",
+                usage: "kweaver agent publish <agent_id> [options]",
+                flags: [
+                    { name: "--category-id <id>", desc: "Category ID for the agent" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent publish <agent_id>"],
+            }));
             return 0;
         }
     }
@@ -1484,19 +1655,22 @@ async function runAgentPersonalListCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver agent personal-list [options]
-
-List personal space agents from the agent-factory API.
-
-Options:
-  --name <text>                 Filter by name
-  --pagination-marker <str>     Pagination marker
-  --publish-status <status>     Filter by publish status
-  --publish-to-be <value>       Publish to be filter
-  --size <n>                    Max items to return (default: 48)
-  --verbose, -v                 Show full JSON response
-  -bd, --biz-domain <value>     Business domain (default: bd_public)
-  --pretty                      Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "List personal space agents from the agent-factory API.",
+                usage: "kweaver agent personal-list [options]",
+                flags: [
+                    { name: "--name <text>", desc: "Filter by name" },
+                    { name: "--pagination-marker <str>", desc: "Pagination marker" },
+                    { name: "--publish-status <status>", desc: "Filter by publish status" },
+                    { name: "--publish-to-be <value>", desc: "Publish to be filter" },
+                    { name: "--size <n>", desc: "Max items to return (default: 48)" },
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent personal-list"],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));
@@ -1532,18 +1706,21 @@ async function runAgentTemplateListCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver agent template-list [options]
-
-List published agent templates from the agent-factory API.
-
-Options:
-  --category-id <id>            Filter by category
-  --name <text>                 Filter by name
-  --pagination-marker <str>     Pagination marker
-  --size <n>                    Max items to return (default: 48)
-  --verbose, -v                 Show full JSON response
-  -bd, --biz-domain <value>     Business domain (default: bd_public)
-  --pretty                      Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "List published agent templates from the agent-factory API.",
+                usage: "kweaver agent template-list [options]",
+                flags: [
+                    { name: "--category-id <id>", desc: "Filter by category" },
+                    { name: "--name <text>", desc: "Filter by name" },
+                    { name: "--pagination-marker <str>", desc: "Pagination marker" },
+                    { name: "--size <n>", desc: "Max items to return (default: 48)" },
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent template-list"],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));
@@ -1578,15 +1755,18 @@ async function runAgentTemplateGetCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver agent template-get <template_id> [options]
-
-Get published agent template details from the agent-factory API.
-
-Options:
-  --verbose, -v             Show full JSON response
-  -bd, --biz-domain <value> Business domain (default: bd_public)
-  --pretty                   Pretty-print JSON output (default)
-  --save-config <path>       Save config to file with timestamp (output: <path-with-timestamp>)`);
+            console.log(renderHelp({
+                tagline: "Get published agent template details from the agent-factory API.",
+                usage: "kweaver agent template-get <template_id> [options]",
+                flags: [
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                    { name: "--save-config <path>", desc: "Save config to file with timestamp (output: <path-with-timestamp>)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent template-get <template_id>"],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));
@@ -1601,12 +1781,12 @@ Options:
             businessDomain: options.businessDomain,
         });
         if (body) {
-            // 如果指定了 --save-config，保存 config 到文件（带时间戳）
+            // Save only the template config object when --save-config is provided.
             if (options.saveConfig) {
                 const parsed = JSON.parse(body);
                 const config = parsed.config ?? {};
                 const timestampedPath = generateTimestampedPath(options.saveConfig);
-                // 确保目录存在
+                // Ensure the output directory exists.
                 const dir = dirname(timestampedPath);
                 await fs.mkdir(dir, { recursive: true });
                 await fs.writeFile(timestampedPath, JSON.stringify(config, null, 2), "utf-8");
@@ -1630,14 +1810,17 @@ async function runAgentCategoryListCommand(args) {
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h") {
-            console.log(`kweaver agent category-list [options]
-
-List agent categories from the agent-factory API.
-
-Options:
-  --verbose, -v             Show full JSON response
-  -bd, --biz-domain <value> Business domain (default: bd_public)
-  --pretty                  Pretty-print JSON output (default)`);
+            console.log(renderHelp({
+                tagline: "List agent categories from the agent-factory API.",
+                usage: "kweaver agent category-list [options]",
+                flags: [
+                    { name: "--verbose, -v", desc: "Show full JSON response" },
+                    { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+                    { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: ["kweaver agent category-list"],
+            }));
             return 0;
         }
         if (arg === "-bd" || arg === "--biz-domain") {