@qzhuli/qzhuli-cli 0.5.0 → 0.5.2

package/dist/cmd.js

@@ -11203,6 +11203,7 @@ var commands = {
     searchDesc: "Search user",
     searchArgDesc: "Query string (default: Q\u52A9\u53F7)",
     searchByUid: "Search by UID",
+    searchByQNumber: "Search by Q\u52A9\u53F7",
     addDesc: "Add friend by Q\u52A9\u53F7",
     addArgDesc: "Q\u52A9\u53F7",
     searchNotFound: "No user found with that Q\u52A9\u53F7.",
@@ -11216,6 +11217,7 @@ var commands = {
     profileArgDesc: "Query string (default: nickname)",
     profileByUid: "Search by UID",
     profileByRemark: "Search by remark",
+    profileByNickname: "Search by nickname",
     pageOption: "Page number",
     pageSizeOption: "Page size",
     noFriends: "No friends or contacts found.",
@@ -11234,7 +11236,7 @@ var commands = {
   },
   message: {
     desc: "Message operations",
-    sendDesc: "Send a message to a conversation via WebSocket IM",
+    sendDesc: "Send a message to a conversation",
     historyDesc: "View message history from a conversation",
     fromOption: "Start from message ID",
     directionOption: "Direction to pull",
@@ -11253,11 +11255,17 @@ var commands = {
     profileArgDesc: "Conversation ID",
     typeOption: "Conversation type (1=private, 2=group, auto-detect if omitted)",
     profileSuccess: "Conversation details retrieved.",
-    searchDesc: "Find all conversations with a user by Q\u52A9\u53F7 or UID",
-    searchArgDesc: "Query string (default: Q\u52A9\u53F7)",
-    searchByUid: "Search by UID",
+    searchDesc: "Find conversations by conversation ID, name, or user",
+    searchArgDesc: "Query string (default: conversation ID)",
+    searchByQNumber: "Search by user Q\u52A9\u53F7",
+    searchByUid: "Search by user UID",
+    searchByName: "Search by conversation name",
+    searchByCid: "Search by conversation ID",
     searchNotFound: "No conversations found with {name}.",
-    searchSuccess: "Found {count} conversation(s) with {name}."
+    searchSuccess: "Found {count} conversation(s) with {name}.",
+    searchByIdSuccess: "Found conversation {id}.",
+    searchByNameNotFound: 'No conversations found with name containing "{name}".',
+    searchByNameSuccess: 'Found {count} conversation(s) with name containing "{name}".'
   },
   cache: {
     desc: "Manage local cache",
@@ -11301,7 +11309,7 @@ __export(zh_exports, {
 });
 init_cjs_shims();
 var cli2 = {
-  banner: "qz \u2014 CLI for Q\u52A9\u7406."
+  banner: "qz \u2014 CLI for Q \u52A9\u7406\u3002"
 };
 var options2 = {
   version: "\u8F93\u51FA\u7248\u672C\u53F7",
@@ -11320,7 +11328,7 @@ var auth2 = {
   // 扫码登录
   qrLogin: "\u626B\u7801\u767B\u5F55",
   creatingQr: "\u6B63\u5728\u751F\u6210\u4E8C\u7EF4\u7801...",
-  qrInstruction: "\u8BF7\u4F7F\u7528Q\u52A9\u7406\u624B\u673AApp\u626B\u63CF\u4E0B\u65B9\u4E8C\u7EF4\u7801",
+  qrInstruction: "\u8BF7\u4F7F\u7528 Q \u52A9\u7406\u624B\u673A App \u626B\u63CF\u4E0B\u65B9\u4E8C\u7EF4\u7801\u3002",
   qrWaiting: "\u7B49\u5F85\u626B\u7801\u4E2D...",
   qrLoginSuccess: "\u767B\u5F55\u6210\u529F\uFF01",
   qrLoginSuccessWithName: "\u767B\u5F55\u6210\u529F\uFF01\u6B22\u8FCE\uFF0C{name}",
@@ -11348,12 +11356,13 @@ var commands2 = {
   user: {
     desc: "\u7528\u6237\u64CD\u4F5C",
     searchDesc: "\u641C\u7D22\u7528\u6237",
-    searchArgDesc: "\u67E5\u8BE2\u5185\u5BB9\uFF08\u9ED8\u8BA4\u6309 Q\u52A9\u53F7\uFF09",
+    searchArgDesc: "\u67E5\u8BE2\u5185\u5BB9\uFF08\u9ED8\u8BA4\u6309 Q \u52A9\u53F7\uFF09",
     searchByUid: "\u6309 UID \u641C\u7D22",
-    addDesc: "\u901A\u8FC7 Q\u52A9\u53F7\u6DFB\u52A0\u597D\u53CB",
-    addArgDesc: "Q\u52A9\u53F7",
-    searchNotFound: "\u672A\u627E\u5230\u8BE5 Q\u52A9\u53F7\u7684\u7528\u6237\u3002",
-    addNoAgentId: "\u7528\u6237\u6CA1\u6709\u52A9\u7406ID\uFF0C\u65E0\u6CD5\u6DFB\u52A0\u3002",
+    searchByQNumber: "\u6309 Q \u52A9\u53F7\u641C\u7D22",
+    addDesc: "\u901A\u8FC7 Q \u52A9\u53F7\u6DFB\u52A0\u597D\u53CB",
+    addArgDesc: "Q \u52A9\u53F7",
+    searchNotFound: "\u672A\u627E\u5230\u8BE5 Q \u52A9\u53F7\u7684\u7528\u6237\u3002",
+    addNoAgentId: "\u7528\u6237\u6CA1\u6709\u52A9\u7406 ID\uFF0C\u65E0\u6CD5\u6DFB\u52A0\u3002",
     addSuccess: "\u5DF2\u6DFB\u52A0\u597D\u53CB {name}\u3002"
   },
   friend: {
@@ -11363,6 +11372,7 @@ var commands2 = {
     profileArgDesc: "\u67E5\u8BE2\u5185\u5BB9\uFF08\u9ED8\u8BA4\u6309\u6635\u79F0\uFF09",
     profileByUid: "\u6309 UID \u641C\u7D22",
     profileByRemark: "\u6309\u5907\u6CE8\u641C\u7D22",
+    profileByNickname: "\u6309\u6635\u79F0\u641C\u7D22",
     pageOption: "\u9875\u7801",
     pageSizeOption: "\u6BCF\u9875\u6570\u91CF",
     noFriends: "\u672A\u627E\u5230\u597D\u53CB\u6216\u8054\u7CFB\u4EBA\u3002",
@@ -11381,7 +11391,7 @@ var commands2 = {
   },
   message: {
     desc: "\u6D88\u606F\u64CD\u4F5C",
-    sendDesc: "\u901A\u8FC7 WebSocket IM \u5411\u4F1A\u8BDD\u53D1\u9001\u6D88\u606F",
+    sendDesc: "\u5411\u4F1A\u8BDD\u53D1\u9001\u6D88\u606F",
     historyDesc: "\u67E5\u770B\u4F1A\u8BDD\u6D88\u606F\u5386\u53F2",
     fromOption: "\u8D77\u59CB\u6D88\u606F ID",
     directionOption: "\u62C9\u53D6\u65B9\u5411",
@@ -11393,18 +11403,24 @@ var commands2 = {
     limitOption: "\u6700\u5927\u4F1A\u8BDD\u6570",
     offsetOption: "\u8DF3\u8FC7\u524D N \u6761\u4F1A\u8BDD",
     createDesc: "\u521B\u5EFA\u4F1A\u8BDD",
-    createArgDesc: "\u7528\u6237UID",
-    createAgentIdOption: "\u52A9\u7406ID",
+    createArgDesc: "\u7528\u6237 UID",
+    createAgentIdOption: "\u52A9\u7406 ID",
     createSuccess: "\u4F1A\u8BDD\u521B\u5EFA\u6210\u529F\u3002",
     profileDesc: "\u67E5\u8BE2\u4F1A\u8BDD\u8BE6\u60C5",
-    profileArgDesc: "\u4F1A\u8BDDID",
-    typeOption: "\u4F1A\u8BDD\u7C7B\u578B\uFF081=\u79C1\u804A, 2=\u7FA4\u804A\uFF0C\u4E0D\u4F20\u81EA\u52A8\u5224\u65AD\uFF09",
+    profileArgDesc: "\u4F1A\u8BDD ID",
+    typeOption: "\u4F1A\u8BDD\u7C7B\u578B\uFF081 = \u79C1\u804A, 2 = \u7FA4\u804A\uFF0C\u4E0D\u4F20\u81EA\u52A8\u5224\u65AD\uFF09",
     profileSuccess: "\u5DF2\u83B7\u53D6\u4F1A\u8BDD\u8BE6\u60C5\u3002",
-    searchDesc: "\u901A\u8FC7Q\u52A9\u53F7\u6216UID\u67E5\u627E\u4E0E\u67D0\u7528\u6237\u7684\u6240\u6709\u4F1A\u8BDD",
-    searchArgDesc: "\u67E5\u8BE2\u5185\u5BB9\uFF08\u9ED8\u8BA4\u6309 Q\u52A9\u53F7\uFF09",
-    searchByUid: "\u6309 UID \u641C\u7D22",
+    searchDesc: "\u901A\u8FC7\u4F1A\u8BDD ID\u3001\u4F1A\u8BDD\u540D\u79F0\u6216\u7528\u6237\u67E5\u627E\u4F1A\u8BDD",
+    searchArgDesc: "\u67E5\u8BE2\u5185\u5BB9\uFF08\u9ED8\u8BA4\u6309\u4F1A\u8BDD ID\uFF09",
+    searchByQNumber: "\u6309\u7528\u6237 Q \u52A9\u53F7\u641C\u7D22",
+    searchByUid: "\u6309\u7528\u6237 UID \u641C\u7D22",
+    searchByName: "\u6309\u4F1A\u8BDD\u540D\u79F0\u641C\u7D22",
+    searchByCid: "\u6309\u4F1A\u8BDD ID \u641C\u7D22",
     searchNotFound: "\u672A\u627E\u5230\u4E0E {name} \u7684\u4F1A\u8BDD\u3002",
-    searchSuccess: "\u627E\u5230\u4E0E {name} \u7684 {count} \u4E2A\u4F1A\u8BDD\u3002"
+    searchSuccess: "\u627E\u5230\u4E0E {name} \u7684 {count} \u4E2A\u4F1A\u8BDD\u3002",
+    searchByIdSuccess: "\u627E\u5230\u4F1A\u8BDD {id}\u3002",
+    searchByNameNotFound: '\u672A\u627E\u5230\u540D\u79F0\u5305\u542B "{name}" \u7684\u4F1A\u8BDD\u3002',
+    searchByNameSuccess: '\u627E\u5230 {count} \u4E2A\u540D\u79F0\u5305\u542B "{name}" \u7684\u4F1A\u8BDD\u3002'
   },
   cache: {
     desc: "\u7BA1\u7406\u672C\u5730\u7F13\u5B58",
@@ -12557,7 +12573,96 @@ function profileToItem(profile) {
   };
 }
 async function conversationSearchRun(factory, opts) {
-  const userResult = opts.byUid ? await factory.repos.user.findUserById(opts.query) : await factory.repos.user.searchUserById(opts.query);
+  if (opts.byCid || !opts.byQNumber && !opts.byUid && !opts.byName) {
+    return searchByConversationId(factory, opts.query);
+  }
+  if (opts.byQNumber) {
+    return searchByQNumber(factory, opts.query);
+  }
+  if (opts.byUid) {
+    return searchByUid(factory, opts.query);
+  }
+  return searchByName(factory, opts.query);
+}
+async function searchByConversationId(factory, conversationId) {
+  const profileResult = await factory.repos.conversation.getProfile(conversationId);
+  if (!profileResult.ok) {
+    return {
+      status: "error",
+      code: profileResult.code,
+      message: profileResult.code === "AUTH_FAILED" /* AUTH_FAILED */ ? t("auth.notAuthenticated") : profileResult.message,
+      data: null
+    };
+  }
+  const profile = profileToItem(profileResult.data);
+  const firstUser = profile.users[0];
+  if (!firstUser) {
+    return {
+      status: "success",
+      code: "NOT_FOUND" /* NOT_FOUND */,
+      message: t("commands.conversation.searchNotFound"),
+      data: null
+    };
+  }
+  const result = {
+    id: firstUser.id,
+    uid: firstUser.uid,
+    nickname: firstUser.nickname,
+    conversations: [profile]
+  };
+  return {
+    status: "success",
+    code: "CONVERSATION_LIST" /* CONVERSATION_LIST */,
+    message: t("commands.conversation.searchByIdSuccess").replace("{id}", conversationId),
+    data: result
+  };
+}
+async function searchByQNumber(factory, qNumber) {
+  const userResult = await factory.repos.user.searchUserById(qNumber);
+  if (!userResult.ok) {
+    return {
+      status: "error",
+      code: userResult.code,
+      message: userResult.code === "AUTH_FAILED" /* AUTH_FAILED */ ? t("auth.notAuthenticated") : userResult.message,
+      data: null
+    };
+  }
+  if (!userResult.data) {
+    return {
+      status: "error",
+      code: "USER_NOT_FOUND_NEEDS_RESOLUTION" /* USER_NOT_FOUND_NEEDS_RESOLUTION */,
+      message: t("messages.notFound"),
+      data: null
+    };
+  }
+  const targetId = userResult.data.id;
+  const targetUid = userResult.data.uid;
+  const nickname = userResult.data.nickname;
+  const profilesResult = await factory.repos.conversation.searchByUid(targetUid);
+  if (!profilesResult.ok || profilesResult.data.length === 0) {
+    return {
+      status: "success",
+      code: "NOT_FOUND" /* NOT_FOUND */,
+      message: t("commands.conversation.searchNotFound").replace("{name}", nickname),
+      data: null
+    };
+  }
+  const results = profilesResult.data.map(profileToItem);
+  const result = {
+    id: targetId,
+    uid: targetUid,
+    nickname,
+    conversations: results
+  };
+  return {
+    status: "success",
+    code: "CONVERSATION_LIST" /* CONVERSATION_LIST */,
+    message: t("commands.conversation.searchSuccess").replace("{name}", nickname).replace("{count}", String(results.length)),
+    data: result
+  };
+}
+async function searchByUid(factory, uid) {
+  const userResult = await factory.repos.user.findUserById(uid);
   if (!userResult.ok) {
     return {
       status: "error",
@@ -12600,6 +12705,72 @@ async function conversationSearchRun(factory, opts) {
     data: result
   };
 }
+async function searchByName(factory, name) {
+  const listResult = await factory.repos.conversation.queryAll({ limit: 0, offset: 0 });
+  if (!listResult.ok) {
+    return {
+      status: "error",
+      code: listResult.code,
+      message: listResult.code === "AUTH_FAILED" /* AUTH_FAILED */ ? t("auth.notAuthenticated") : listResult.message,
+      data: null
+    };
+  }
+  const conversations3 = listResult.data ?? [];
+  const matchedIds = conversations3.filter((c) => c.name?.includes(name)).map((c) => c.id);
+  if (matchedIds.length === 0) {
+    return {
+      status: "success",
+      code: "NOT_FOUND" /* NOT_FOUND */,
+      message: t("commands.conversation.searchByNameNotFound").replace("{name}", name),
+      data: null
+    };
+  }
+  const profileResults = await Promise.all(
+    matchedIds.map((convId) => factory.repos.conversation.getProfile(convId))
+  );
+  const profiles = profileResults.filter((r) => r.ok).map((r) => r.data);
+  if (profiles.length === 0) {
+    return {
+      status: "success",
+      code: "NOT_FOUND" /* NOT_FOUND */,
+      message: t("commands.conversation.searchByNameNotFound").replace("{name}", name),
+      data: null
+    };
+  }
+  const items = profiles.map(profileToItem);
+  const groupedByUid = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const primaryUser = item.users[0];
+    if (!primaryUser) continue;
+    const uid = primaryUser.uid;
+    const existing = groupedByUid.get(uid);
+    if (existing) {
+      existing.conversations.push(item);
+    } else {
+      groupedByUid.set(uid, {
+        id: primaryUser.id,
+        uid,
+        nickname: primaryUser.nickname,
+        conversations: [item]
+      });
+    }
+  }
+  const results = [...groupedByUid.values()];
+  if (results.length === 0) {
+    return {
+      status: "success",
+      code: "NOT_FOUND" /* NOT_FOUND */,
+      message: t("commands.conversation.searchByNameNotFound").replace("{name}", name),
+      data: null
+    };
+  }
+  return {
+    status: "success",
+    code: "CONVERSATION_LIST" /* CONVERSATION_LIST */,
+    message: t("commands.conversation.searchByNameSuccess").replace("{name}", name).replace("{count}", String(results.length)),
+    data: results
+  };
+}
 
 // src/commands/conversation/index.ts
 function NewCmdConversation(factory) {
@@ -12622,10 +12793,18 @@ function NewCmdConversation(factory) {
     const result = await conversationCreateRun(factory, { uid, agentId: opts.agentId });
     handleCommand(result);
   });
-  cmd.command("search").description(t("commands.conversation.searchDesc")).argument("<query>", t("commands.conversation.searchArgDesc")).option("--uid", t("commands.conversation.searchByUid")).action(async (query, opts) => {
-    const result = await conversationSearchRun(factory, { query, byUid: opts.uid });
-    handleCommand(result);
-  });
+  cmd.command("search").description(t("commands.conversation.searchDesc")).argument("<query>", t("commands.conversation.searchArgDesc")).option("--qnumber", t("commands.conversation.searchByQNumber")).option("--uid", t("commands.conversation.searchByUid")).option("--name", t("commands.conversation.searchByName")).option("--cid", t("commands.conversation.searchByCid")).action(
+    async (query, opts) => {
+      const result = await conversationSearchRun(factory, {
+        query,
+        byQNumber: opts.qnumber,
+        byUid: opts.uid,
+        byName: opts.name,
+        byCid: opts.cid
+      });
+      handleCommand(result);
+    }
+  );
   return cmd;
 }
 
@@ -12789,14 +12968,17 @@ function NewCmdFriend(factory) {
     const result = await friendListRun(factory);
     handleCommand(result);
   });
-  cmd.command("profile").description(t("commands.friend.profileDesc")).argument("<query>", t("commands.friend.profileArgDesc")).option("--uid", t("commands.friend.profileByUid")).option("--remark", t("commands.friend.profileByRemark")).action(async (query, opts) => {
-    const result = await friendProfileRun(factory, {
-      query,
-      byUid: opts.uid,
-      byRemark: opts.remark
-    });
-    handleCommand(result);
-  });
+  cmd.command("profile").description(t("commands.friend.profileDesc")).argument("<query>", t("commands.friend.profileArgDesc")).option("--uid", t("commands.friend.profileByUid")).option("--remark", t("commands.friend.profileByRemark")).option("--nickname", t("commands.friend.profileByNickname")).action(
+    async (query, opts) => {
+      const result = await friendProfileRun(factory, {
+        query,
+        byUid: opts.uid,
+        byRemark: opts.remark,
+        byNickname: opts.nickname
+      });
+      handleCommand(result);
+    }
+  );
   return cmd;
 }
 
@@ -13065,8 +13247,12 @@ async function userSearchRun(factory, opts) {
 // src/commands/user/index.ts
 function NewCmdUser(factory) {
   const cmd = new import_commander8.Command("user").description(t("commands.user.desc"));
-  cmd.command("search").description(t("commands.user.searchDesc")).argument("<query>", t("commands.user.searchArgDesc")).option("--uid", t("commands.user.searchByUid")).action(async (query, opts) => {
-    const result = await userSearchRun(factory, { query, byUid: opts.uid });
+  cmd.command("search").description(t("commands.user.searchDesc")).argument("<query>", t("commands.user.searchArgDesc")).option("--uid", t("commands.user.searchByUid")).option("--qnumber", t("commands.user.searchByQNumber")).action(async (query, opts) => {
+    const result = await userSearchRun(factory, {
+      query,
+      byUid: opts.uid,
+      byQNumber: opts.qnumber
+    });
     handleCommand(result);
   });
   cmd.command("add").description(t("commands.user.addDesc")).argument("<q-number>", t("commands.user.addArgDesc")).action(async (qNumber) => {
@@ -14921,7 +15107,7 @@ async function main() {
 ${t("cli.banner")}` : t("cli.banner");
   program.addHelpText("beforeAll", `${banner}
 `);
-  program.name("qz").version(`v${"0.5.0"}`, "-v, --version", t("options.version")).helpOption("-h, --help", t("options.help")).option("-q, --jq <expr>", t("options.jq")).option("--dry-run", t("options.dryRun"));
+  program.name("qz").version(`v${"0.5.2"}`, "-v, --version", t("options.version")).helpOption("-h, --help", t("options.help")).option("-q, --jq <expr>", t("options.jq")).option("--dry-run", t("options.dryRun"));
   program.usage("<command> [subcommand] [options]");
   program.hook("preAction", () => {
     const opts = program.opts();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qzhuli/qzhuli-cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "CLI tool for Q助理 (QZhuli)",
   "main": "dist/cmd.js",
   "bin": {

package/skills/qzhuli-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: qzhuli-cli
 description: Use when operating the QZhuli CLI (`qz`), including login, auth status, config, friends, relations, users, conversations, messages, cache management, JSON filtering, dry-run, command help, and interpreting test-environment banners or config files.
-version: 0.1.0
+version: 0.1.2
 ---
 
 # QZhuli CLI
@@ -39,18 +39,11 @@ When ANY of the following applies, STOP and ask the user first:
 - **Friend operations**: Before `user add`, show the target profile and confirm.
 - **Relation changes**: Before `relation set`, show the current value and the new value, then confirm.
 - **Cache clearing**: Before `cache clear`, confirm scope (all tables vs single table).
+- **Message without conversation**: Before `message send`, check if a conversation with the target user exists. If not,
+  ask the user whether to create one first.
 - **Any write operation** (`user add`, `relation set`, `conversation create`, `cache clear`): confirm
   with user.
 
-### Use --dry-run for Preview
-
-Before any write operation the user hasn't explicitly confirmed, run with `--dry-run` first:
-
-```bash
-qz --dry-run message send <id> "hello"
-qz --dry-run relation set <uid> --remark "New Name"
-```
-
 ### Least-Surprise Principle
 
 - Never change a friend's remark without showing both old and new.
@@ -69,18 +62,12 @@ When sending messages, determine the role based on the user's wording:
 
 The CLI uses 4 distinct ID types. **Using the wrong type will fail silently or hit the wrong target.**
 
-| ID Type         | Field Name       | Format                  | Example                      | Used By                                                                                                             |
-|-----------------|------------------|-------------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------|
-| Q助号             | `id`             | Number, short           | `10003`                      | `user add <q-number>`, `user search`, `conversation search` (default)                                               |
-| UID             | `uid`            | 32-char hex string      | `d5b6308e3abad6bc96573c58`   | `relation get/set`, `friend profile --uid`, `user search --uid`, `conversation search --uid`, `conversation create` |
-| Conversation ID | `conversationId` | Base64-like long string | `9boGaR7iii2Jdjhmb5LSo37...` | `message send`, `message history`, `conversation profile`                                                           |
-| Agent ID        | `agent.id`       | Number                  | `5`                          | `conversation create --agent-id`                                                                                    |
-
-**Quick identification by format**:
-
-- A short integer → Q助号
-- A 32-char hex string → UID
-- A long Base64-like string → conversationId
+| ID Type         | Field Name       | Format                  | Example                      | Used By                                                                                    |
+|-----------------|------------------|-------------------------|------------------------------|--------------------------------------------------------------------------------------------|
+| Q助号             | `id`             | Number, short           | `10003`                      | `user add <q-number>`, `user search`, `conversation search` (with `--qnumber`)             |
+| UID             | `uid`            | 32-char hex string      | `d5b6308e3abad6bc96573c58`   | `relation get/set`, `friend profile --uid`, `user search --uid`, `conversation create`     |
+| Conversation ID | `conversationId` | Base64-like long string | `9boGaR7iii2Jdjhmb5LSo37...` | `message send`, `message history`, `conversation profile`, `conversation search` (default) |
+| Agent ID        | `agent.id`       | Number                  | `5`                          | `conversation create --agent-id`                                                           |
 
 **Common mistake**: Using UID for `message send` instead of conversationId. Always resolve via `conversation search` or
 `conversation list` first.
@@ -116,37 +103,38 @@ qz --jq ".data" conversation list --limit 5
 
 `--jq` is not full jq. Prefer simple paths: `.data`, `.data.uid`, `.data.links`.
 
-Use `--dry-run` to preview without side effects. Wired through: output, HTTP API calls, IM WebSocket actions, auth
-login/logout, and preference writes.
-
 ## Command Map
 
-| Goal                       | Command                                                                                       |
-|----------------------------|-----------------------------------------------------------------------------------------------|
-| Check login                | `qz auth status`                                                                              |
-| QR login                   | `qz auth login [--method qr-code]`                                                            |
-| Clear credentials          | `qz auth logout`                                                                              |
-| Show preferences           | `qz config`                                                                                   |
-| Update preferences         | `qz config [--locale en\|zh] [--debug\|--no-debug]`                                           |
-| Search user (Q助号)          | `qz user search <q-number>`                                                                   |
-| Search user (UID)          | `qz user search <uid> --uid`                                                                  |
-| Add friend (Q助号)           | `qz user add <q-number>`                                                                      |
-| List friends               | `qz friend list`                                                                              |
-| Resolve profile (nickname) | `qz friend profile <nickname>`                                                                |
-| Resolve profile (UID)      | `qz friend profile <uid> --uid`                                                               |
-| Resolve profile (remark)   | `qz friend profile <remark> --remark`                                                         |
-| Read relation              | `qz relation get <uid>`                                                                       |
-| Update relation            | `qz relation set <uid> [-r, --remark <name>] [-t, --type <type>]`                             |
-| List conversations         | `qz conversation list [--limit <n>] [--offset <n>]`                                           |
-| Get conversation profile   | `qz conversation profile <conversation-id> [--type <n>]`                                      |
-| Create conversation        | `qz conversation create <uid> --agent-id <id>`                                                |
-| Search conversations (Q助号) | `qz conversation search <q-number>`                                                           |
-| Search conversations (UID) | `qz conversation search <uid> --uid`                                                          |
-| Send message               | `qz message send <conversation-id> <content> [--role <n>]`                                    |
-| Read message history       | `qz message history <conversation-id> [--from <id>] [--direction newer\|older] [--limit <n>]` |
-| Sync cache                 | `qz cache sync`                                                                               |
-| Cache status               | `qz cache status`                                                                             |
-| Clear cache                | `qz cache clear [--table <name>]`                                                             |
+| Goal                                 | Command                                                                                       |
+|--------------------------------------|-----------------------------------------------------------------------------------------------|
+| Check login                          | `qz auth status`                                                                              |
+| QR login                             | `qz auth login [--method qr-code]`                                                            |
+| Clear credentials                    | `qz auth logout`                                                                              |
+| Show preferences                     | `qz config`                                                                                   |
+| Update preferences                   | `qz config [--locale en\|zh] [--debug\|--no-debug]`                                           |
+| Search user (Q助号)                    | `qz user search <q-number>`                                                                   |
+| Search user (Q助号, explicit)          | `qz user search <q-number> --qnumber`                                                         |
+| Search user (UID)                    | `qz user search <uid> --uid`                                                                  |
+| Add friend (Q助号)                     | `qz user add <q-number>`                                                                      |
+| List friends                         | `qz friend list`                                                                              |
+| Resolve profile (nickname)           | `qz friend profile <nickname>`                                                                |
+| Resolve profile (nickname, explicit) | `qz friend profile <nickname> --nickname`                                                     |
+| Resolve profile (UID)                | `qz friend profile <uid> --uid`                                                               |
+| Resolve profile (remark)             | `qz friend profile <remark> --remark`                                                         |
+| Read relation                        | `qz relation get <uid>`                                                                       |
+| Update relation                      | `qz relation set <uid> [-r, --remark <name>] [-t, --type <type>]`                             |
+| List conversations                   | `qz conversation list [--limit <n>] [--offset <n>]`                                           |
+| Get conversation profile             | `qz conversation profile <conversation-id> [--type <n>]`                                      |
+| Create conversation                  | `qz conversation create <uid> --agent-id <id>`                                                |
+| Search conversations (ID)            | `qz conversation search <conversation-id>`                                                    |
+| Search conversations (name)          | `qz conversation search <name> --name`                                                        |
+| Search conversations (Q助号)           | `qz conversation search <q-number> --qnumber`                                                 |
+| Search conversations (UID)           | `qz conversation search <uid> --uid`                                                          |
+| Send message                         | `qz message send <conversation-id> <content> [--role <n>]`                                    |
+| Read message history                 | `qz message history <conversation-id> [--from <id>] [--direction newer\|older] [--limit <n>]` |
+| Sync cache                           | `qz cache sync`                                                                               |
+| Cache status                         | `qz cache status`                                                                             |
+| Clear cache                          | `qz cache clear [--table <name>]`                                                             |
 
 Relation type values: `0=stranger`, `1=friend`, `2=family`, `3=colleague`.
 
@@ -160,8 +148,8 @@ Relation type values: `0=stranger`, `1=friend`, `2=family`, `3=colleague`.
 
 ### Update a Friend Relation
 
-1. Resolve the exact `uid` with `friend list` or `friend profile`.
-2. Show current value to user, confirm the change.
+1. Resolve the exact `uid` via `friend list` or `friend profile`.
+2. Show current value, confirm the change.
 3. Execute: `qz relation set <uid> --remark "New Name" --type 1`
 4. Verify: `qz relation get <uid>`
 
@@ -176,18 +164,25 @@ Relation type values: `0=stranger`, `1=friend`, `2=family`, `3=colleague`.
 ### Find All Conversations with a User
 
 ```bash
-qz conversation search 10000                           # by Q助号 (default)
-qz conversation search d5b6308e3abad6bc96573c58 --uid  # by UID
+qz conversation search <conversation-id>           # default: by conversation ID
+qz conversation search <name> --name               # by conversation name
+qz conversation search <q-number> --qnumber        # by user Q助号
+qz conversation search <uid> --uid                 # by user UID
 ```
 
-Response includes `id` (Q助号), `uid` (internal user ID), and `conversations` with full profile data. Each conversation
-entry contains `conversationId`, `isGroup`, `users`, and `visitors`.
+Response includes `id`, `uid`, and `conversations` with full profile data. Each entry contains `conversationId`,
+`isGroup`, `users`, and `visitors`.
 
 ### Send a Message
 
 1. Confirm auth: `qz auth status`
-2. Get conversations: `qz conversation list --limit 10`
-3. Pick the conversation `id` (conversationId).
+2. **Check existing conversation**: If you have a `conversationId`, use `conversation search <conversation-id>`
+   directly. Otherwise, use `conversation search <q-number> --qnumber`, `conversation search <uid> --uid`,
+   or `conversation search <name> --name` to find conversations with the target user.
+3. **Decision**:
+    - If conversations exist → pick the relevant `conversationId`.
+    - If no conversation exists → **ask the user first** whether to create one, then
+      `qz conversation create <uid> --agent-id <id>`.
 4. Determine role: if the user says "以我的名义" / "帮我发给" / "替我发送" etc., add `--role 1`; otherwise omit (
    defaults to Assistant).
 5. Send: `qz message send <conversation-id> "message text"`
@@ -203,23 +198,7 @@ qz message history <conversation-id> --from <message-id> --direction newer --lim
 
 ### Pre-Sync Cache for Offline Speed
 
-```bash
-qz cache sync       # fetch all data into local SQLite
-qz cache status     # verify record counts and sync time
-qz conversation search 10000  # now instant from cache
-```
-
-## Cache Architecture (Reference)
-
-Read operations use a **Repository Pattern** with SQLite-backed caching (`~/.qzhuli-cli/cache.db`):
-
-- **TTL**: conversations 30 min, contacts/relations 5 min, user profiles 1 hour
-- **Incremental sync**: only fetches profiles for *new* conversations
-- **Cache miss** → auto incremental sync (not full refetch)
-- **Write operations** bypass cache, invalidate relevant entries
-
-Tables: `conversations_index`, `conversation_profiles`, `contacts_cache`, `user_profiles`, `relations_cache`,
-`messages_cache`.
+Run `qz cache sync` before heavy read operations. Verify with `qz cache status`.
 
 ## Troubleshooting
 
@@ -231,6 +210,7 @@ Tables: `conversations_index`, `conversation_profiles`, `contacts_cache`, `user_
 | Too much JSON                   | Use `--jq ".data"` or another simple dot path                               |
 | Need no-op preview              | Use `--dry-run`                                                             |
 | Message send fails              | Re-check `auth status`, verify conversationId via `conversation list`       |
+| Target has no conversation      | Ask user to create one, then `conversation create <uid> --agent-id <id>`    |
 | Slow queries                    | Run `qz cache sync` first (incremental, fast), then retry                   |
 | Cache corrupted                 | `qz cache clear` to reset, then retry (falls back to API)                   |
 | Ambiguous search                | `status: "needs_resolution"` — refine query with `--uid` or `--remark` flag |