feat(memory): 完善记忆及画像相关命令支持并统一参数

- 在 CLI 文档中新增记忆 live 场景说明与变量需求
- 扩展 CLI 命令集，添加记忆画像 Profile 的增删改查功能
- 统一所有记忆相关命令加入 workspace 和 library 参数支持
- 记忆添加命令支持自定义 meta_data，完善输入校验和互斥说明
- 记忆删除、列表、获取用户画像等命令增加工作空间参数支持
- 画像模板相关命令新增分页参数及属性操作接口
- 重构知识命令共享模块，移除重复的 workspace 解析实现，统一导出
- 优化命令输出格式，文本模式下显示更多详细信息和异常提示
- 提供完整的示例参数，增强命令使用说明和提示文档

Author: clark-fc

docs/agents/cli-e2e-tests.md

@@ -71,12 +71,13 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 
 | 场景                    | 条件                                                                                                       |
 | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
-| 文本/搜索/记忆/配置     | `isDashScopeE2EReady()`                                                                                    |
+| 文本/搜索/配置          | `isDashScopeE2EReady()`                                                                                    |
 | 图像/语音               | `isBailianE2EMediaEnabled() && isDashScopeE2EReady()`                                                      |
 | 视频                    | `isBailianE2EVideoEnabled() && isDashScopeE2EReady()`                                                      |
 | OpenAPI AK/SK           | `isOpenApiE2EReady()`（`.env` 中必须同时提供完整 AK/SK）                                                   |
 | 视频 download/task      | 另需 `BAILIAN_E2E_VIDEO_TASK_ID`                                                                           |
 | 知识库 chat/search live | `isChatE2EReady()` / `isSearchE2EReady()`（`knowledge chat/search`，需 `BAILIAN_WORKSPACE_ID` + agent ID） |
+| 记忆 live               | `isMemoryE2EReady()`（另需 `BAILIAN_E2E_MEMORY_LIBRARY_ID`；记忆服务需账号单独开通）                       |
 
 ## 用例类型
 

packages/cli/src/commands.ts

@@ -29,6 +29,10 @@ import {
   memoryUpdate,
   memoryDelete,
   memoryProfileCreate,
+  memoryProfileList,
+  memoryProfileShow,
+  memoryProfileUpdate,
+  memoryProfileDelete,
   memoryProfileGet,
   knowledgeRetrieve,
   knowledgeSearch,
@@ -243,6 +247,10 @@ export const commands: Record<string, AnyCommand> = {
   "memory update": memoryUpdate,
   "memory delete": memoryDelete,
   "memory profile create": memoryProfileCreate,
+  "memory profile list": memoryProfileList,
+  "memory profile show": memoryProfileShow,
+  "memory profile update": memoryProfileUpdate,
+  "memory profile delete": memoryProfileDelete,
   "memory profile get": memoryProfileGet,
   "knowledge retrieve": knowledgeRetrieve,
   "knowledge search": knowledgeSearch,

packages/commands/src/commands/knowledge/shared.ts

@@ -1,7 +1,6 @@
 // Shared building blocks for the knowledge admin commands.
 import {
   BailianError,
-  ExitCode,
   ragEndpoint,
   RAG_PATHS,
   type Client,
@@ -12,18 +11,9 @@ import {
 } from "bailian-cli-core";
 import { poll } from "bailian-cli-runtime";
 
-// Knowledge APIs use a workspace-specific host, so --workspace-id is a per-command
-// flag here (the console credential scope does not apply).
-export const WORKSPACE_FLAG = {
-  workspaceId: {
-    type: "string",
-    valueHint: "<id>",
-    description: {
-      "en-US": "Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)",
-      "zh-CN": "API Endpoint URL 使用的 Workspace ID（也可设置 BAILIAN_WORKSPACE_ID）",
-    },
-  },
-} satisfies FlagsDef;
+// The workspace scope is shared with the memory commands, so it lives in
+// ../shared/workspace.ts; re-exported here to keep the knowledge imports local.
+export { resolveWorkspaceId, WORKSPACE_FLAG } from "../shared/workspace.ts";
 
 // Unified pagination flags for admin list commands. The server-side page/size
 // parameter names differ per endpoint (page_number/page_num/pageNum/pageNumber…)
@@ -43,23 +33,6 @@ export const PAGE_FLAGS = {
   },
 } satisfies FlagsDef;
 
-/** Three-level fallback: flag > BAILIAN_WORKSPACE_ID env > config (env/config are merged into settings); missing → USAGE. */
-export function resolveWorkspaceId(ctx: {
-  flags: { workspaceId?: string };
-  settings: { workspaceId?: string };
-  identity: { binName: string };
-}): string {
-  const workspaceId = ctx.flags.workspaceId || ctx.settings.workspaceId;
-  if (!workspaceId) {
-    throw new BailianError(
-      "Workspace ID is required.",
-      ExitCode.USAGE,
-      `Pass --workspace-id, set BAILIAN_WORKSPACE_ID env, or configure: ${ctx.identity.binName} config set workspace_id <id>`,
-    );
-  }
-  return workspaceId;
-}
-
 /** Truncate text-mode table rows to the terminal width; no truncation when not a TTY (pipe/redirect). */
 export function truncateLine(line: string): string {
   if (!process.stdout.isTTY) return line;

packages/commands/src/commands/memory/add.ts

@@ -2,53 +2,80 @@ import {
   defineCommand,
   UsageError,
   memoryAddPath,
+  memoryEndpoint,
   detectOutputFormat,
   type FlagsDef,
   type ParsedFlags,
   type MemoryAddRequest,
   type MemoryAddResponse,
+  type MemoryMessage,
 } from "bailian-cli-core";
 import { emitResult, emitBare } from "bailian-cli-runtime";
+import {
+  MEMORY_LIBRARY_FLAG,
+  MEMORY_WORKSPACE_NOTE,
+  PROJECT_ID_FLAG,
+  WORKSPACE_FLAG,
+  parseJsonArrayFlag,
+  parseJsonObjectFlag,
+  resolveWorkspaceId,
+} from "./shared.ts";
 
 const ADD_FLAGS = {
   userId: {
     type: "string",
     valueHint: "<id>",
-    description: { "en-US": "User ID (required)", "zh-CN": "用户 ID（必填）" },
+    description: {
+      "en-US": "Memory entity ID that owns the memory (required)",
+      "zh-CN": "记忆实体 ID，标识记忆归属对象（必填）",
+    },
     required: true,
   },
   messages: {
     type: "string",
     valueHint: "<json>",
     description: {
-      "en-US": 'Messages JSON array: [{"role":"user","content":"..."},...]',
-      "zh-CN": '消息 JSON 数组：[{"role":"user","content":"..."},...]',
+      "en-US": 'Messages JSON array: [{"role":"user","content":"..."},...] (max 50)',
+      "zh-CN": '消息 JSON 数组：[{"role":"user","content":"..."},...]（最多 50 条）',
     },
   },
   content: {
     type: "string",
     valueHint: "<text>",
-    description: { "en-US": "Custom content text to memorize", "zh-CN": "要记忆的自定义内容文本" },
+    description: {
+      "en-US": "Custom content to memorize verbatim; takes precedence over --messages",
+      "zh-CN": "要原样记忆的自定义内容；优先级高于 --messages",
+    },
   },
   profileSchema: {
     type: "string",
     valueHint: "<id>",
     description: {
-      "en-US": "Profile schema ID for user profiling",
-      "zh-CN": "用于用户画像的 Profile Schema ID",
+      "en-US": "Profile schema ID; without it no user profile is extracted",
+      "zh-CN": "画像模板 ID；不传则不提取用户画像",
     },
   },
-  memoryLibraryId: {
+  metaData: {
     type: "string",
-    valueHint: "<id>",
+    valueHint: "<json>",
     description: {
-      "en-US": "Memory library ID (isolate memory space)",
-      "zh-CN": "记忆库 ID（用于隔离记忆空间）",
+      "en-US": 'Custom metadata JSON object: {"location_name":"Beijing"}',
+      "zh-CN": '用户自定义信息 JSON 对象：{"location_name":"北京"}',
     },
   },
+  ...PROJECT_ID_FLAG,
+  ...MEMORY_LIBRARY_FLAG,
+  ...WORKSPACE_FLAG,
 } satisfies FlagsDef;
 type AddFlags = ParsedFlags<typeof ADD_FLAGS>;
 
+/** Max messages accepted per AddMemory call (a Q&A pair counts as 2). */
+const MAX_MESSAGES = 50;
+/** Max characters accepted for custom_content. */
+const MAX_CONTENT_LENGTH = 512;
+/** Max characters accepted for user_id. */
+const MAX_USER_ID_LENGTH = 64;
+
 export default defineCommand({
   description: {
     "en-US": "Add memory from messages or custom content",
@@ -57,10 +84,24 @@ export default defineCommand({
   auth: "apiKey",
   usageArgs: "--user-id <id> [--messages <json>] [--content <text>] [flags]",
   flags: ADD_FLAGS,
+  notes: [
+    MEMORY_WORKSPACE_NOTE,
+    {
+      "en-US":
+        "--content and --messages are mutually exclusive: when --content is set, --messages is ignored by the server.",
+      "zh-CN": "--content 与 --messages 互斥：传了 --content 时服务端会忽略 --messages。",
+    },
+    {
+      "en-US":
+        "The response lists the changed memory nodes; one call can add, update or delete several at once.",
+      "zh-CN": "返回结果是变更的记忆片段列表；一次调用可能同时新增、更新或删除多条。",
+    },
+  ],
   exampleArgs: [
     {
-      "en-US": '--user-id user1 --content "The user likes Python programming"',
-      "zh-CN": '--user-id user1 --content "用户喜欢使用 Python 编程"',
+      "en-US":
+        '--user-id user1 --content "The user likes Python programming" --workspace-id ws_xxx',
+      "zh-CN": '--user-id user1 --content "用户喜欢使用 Python 编程" --workspace-id ws_xxx',
     },
     {
       "en-US": '--user-id user1 --messages \'[{"role":"user","content":"I like traveling"}]\'',
@@ -70,46 +111,61 @@ export default defineCommand({
       "en-US": '--user-id user1 --content "Lives in Beijing" --profile-schema schema_xxx',
       "zh-CN": '--user-id user1 --content "居住在北京" --profile-schema schema_xxx',
     },
+    {
+      "en-US": '--user-id user1 --content "Attended WAIC" --meta-data \'{"location":"Shanghai"}\'',
+      "zh-CN": '--user-id user1 --content "参加了 WAIC" --meta-data \'{"location":"上海"}\'',
+    },
   ],
-  validate: (f: AddFlags) =>
-    !f.messages && !f.content ? "Provide --messages or --content." : undefined,
+  validate: (flags: AddFlags) => {
+    if (!flags.messages && !flags.content) return "Provide --messages or --content.";
+    if (flags.userId.length > MAX_USER_ID_LENGTH)
+      return `--user-id must be at most ${MAX_USER_ID_LENGTH} characters.`;
+    if (flags.content && flags.content.length > MAX_CONTENT_LENGTH)
+      return `--content must be at most ${MAX_CONTENT_LENGTH} characters.`;
+    return undefined;
+  },
   async run(ctx) {
     const { settings, flags } = ctx;
-    const userId = flags.userId;
 
-    const body: MemoryAddRequest = { user_id: userId };
+    const body: MemoryAddRequest = { user_id: flags.userId };
 
     if (flags.messages) {
-      try {
-        body.messages = JSON.parse(flags.messages);
-      } catch {
-        throw new UsageError("--messages must be valid JSON array");
+      const messages = parseJsonArrayFlag<MemoryMessage>("--messages", flags.messages);
+      if (messages.length > MAX_MESSAGES) {
+        throw new UsageError(`--messages accepts at most ${MAX_MESSAGES} messages`);
       }
+      body.messages = messages;
     }
 
-    if (flags.content) {
-      body.custom_content = flags.content;
-    }
-
+    if (flags.content) body.custom_content = flags.content;
+    if (flags.metaData) body.meta_data = parseJsonObjectFlag("--meta-data", flags.metaData);
     if (flags.profileSchema) body.profile_schema = flags.profileSchema;
+    if (flags.projectId) body.project_id = flags.projectId;
     if (flags.memoryLibraryId) body.memory_library_id = flags.memoryLibraryId;
 
     const format = detectOutputFormat(settings.output);
+    const url = memoryEndpoint(resolveWorkspaceId(ctx), memoryAddPath());
 
     if (settings.dryRun) {
-      emitResult({ endpoint: ctx.client.url(memoryAddPath()), request: body }, format);
+      emitResult({ endpoint: url, method: "POST", request: body }, format);
       return;
     }
 
     const response = await ctx.client.requestJson<MemoryAddResponse>({
-      path: memoryAddPath(),
+      path: url,
       method: "POST",
       body,
     });
 
     if (settings.quiet || format === "text") {
-      const ids = response.memory_ids?.join(", ") || "none";
-      emitBare(`Memory added. IDs: ${ids}`);
+      const nodes = response.memory_nodes ?? [];
+      if (nodes.length === 0) {
+        emitBare("No memory node changed.");
+        return;
+      }
+      for (const node of nodes) {
+        emitBare(`[${node.event ?? "ADD"}] ${node.memory_node_id} ${node.content}`);
+      }
     } else {
       emitResult(response, format);
     }

packages/commands/src/commands/memory/delete.ts

@@ -1,50 +1,62 @@
-import { defineCommand, memoryNodePath, detectOutputFormat } from "bailian-cli-core";
+import {
+  defineCommand,
+  memoryEndpoint,
+  memoryNodePath,
+  detectOutputFormat,
+  type FlagsDef,
+} from "bailian-cli-core";
 import { emitResult, emitBare } from "bailian-cli-runtime";
+import { buildQuery } from "../shared/params.ts";
+import {
+  MEMORY_LIBRARY_FLAG,
+  MEMORY_WORKSPACE_NOTE,
+  WORKSPACE_FLAG,
+  resolveWorkspaceId,
+} from "./shared.ts";
+
+const DELETE_FLAGS = {
+  nodeId: {
+    type: "string",
+    valueHint: "<id>",
+    description: { "en-US": "Memory node ID (required)", "zh-CN": "记忆节点 ID（必填）" },
+    required: true,
+  },
+  userId: {
+    type: "string",
+    valueHint: "<id>",
+    description: {
+      "en-US": "Memory entity ID that owns the memory (required)",
+      "zh-CN": "记忆实体 ID，标识记忆归属对象（必填）",
+    },
+    required: true,
+  },
+  ...MEMORY_LIBRARY_FLAG,
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
 
 export default defineCommand({
   description: { "en-US": "Delete a memory node", "zh-CN": "删除记忆节点" },
   auth: "apiKey",
-  usageArgs: "--node-id <id> --user-id <id>",
-  flags: {
-    nodeId: {
-      type: "string",
-      valueHint: "<id>",
-      description: { "en-US": "Memory node ID (required)", "zh-CN": "记忆节点 ID（必填）" },
-      required: true,
-    },
-    userId: {
-      type: "string",
-      valueHint: "<id>",
-      description: { "en-US": "User ID (required)", "zh-CN": "用户 ID（必填）" },
-      required: true,
-    },
-    memoryLibraryId: {
-      type: "string",
-      valueHint: "<id>",
-      description: {
-        "en-US": "Memory library ID (non-default library)",
-        "zh-CN": "记忆库 ID（非默认记忆库）",
-      },
-    },
-  },
-  exampleArgs: ["--node-id node_xxx --user-id user1"],
+  usageArgs: "--node-id <id> --user-id <id> [flags]",
+  flags: DELETE_FLAGS,
+  notes: [MEMORY_WORKSPACE_NOTE],
+  exampleArgs: ["--node-id node_xxx --user-id user1 --workspace-id ws_xxx"],
   async run(ctx) {
     const { settings, flags } = ctx;
     const nodeId = flags.nodeId;
-    const userId = flags.userId;
 
     const format = detectOutputFormat(settings.output);
-    const params = new URLSearchParams({ user_id: userId });
-    if (flags.memoryLibraryId) params.set("memory_library_id", flags.memoryLibraryId);
-    const path = `${memoryNodePath(nodeId)}?${params.toString()}`;
+    const url =
+      memoryEndpoint(resolveWorkspaceId(ctx), memoryNodePath(nodeId)) +
+      buildQuery({ user_id: flags.userId, memory_library_id: flags.memoryLibraryId });
 
     if (settings.dryRun) {
-      emitResult({ endpoint: ctx.client.url(path), method: "DELETE" }, format);
+      emitResult({ endpoint: url, method: "DELETE" }, format);
       return;
     }
 
     const response = await ctx.client.requestJson<{ request_id: string }>({
-      path,
+      path: url,
       method: "DELETE",
     });