@qzhuli/qzhuli-cli 0.4.3 → 0.5.1

package/README.md

@@ -28,38 +28,35 @@ npx qz --version
 The CLI ships with a `SKILL.md` that teaches AI agents how to use it. During `npm install -g`, the skill is
 automatically installed to your agent's skill directory.
 
-### Supported agents (18)
+### Install skill to your agent
 
-Claude Code, Cursor, Codex, Copilot, Windsurf, OpenClaw, OpenCode, Cline, Gemini CLI, Amp, Roo, Goose, Kiro, Qwen Code,
-Qoder, Trae, Augment, Zed.
+```bash
+npx -p @qzhuli/qzhuli-cli qz-install-skill --target <your-agent-skill-dir>
+```
 
-### Manual skill install
+Replace `<your-agent-skill-dir>` with your agent's skill path (e.g. `~/.claude/skills` for Claude Code, `~/.agents/skills` as universal fallback).
 
-If the automatic install didn't work (e.g. local `npm install` without `-g`):
+### Check skill version
 
 ```bash
-# Install to all detected agents (global)
-npx -p @qzhuli/qzhuli-cli qz-install-skill
+npx -p @qzhuli/qzhuli-cli qz-install-skill --version
+```
 
-# Install to current project's skill directory
-npx -p @qzhuli/qzhuli-cli qz-install-skill --project
+### Update installed skills
 
-# Install to a specific agent only
-npx -p @qzhuli/qzhuli-cli qz-install-skill --agent claude-code
+If a newer version is available, update all installed skills:
 
-# Update existing installs if skill version changed
+```bash
 npx -p @qzhuli/qzhuli-cli qz-install-skill --update
 ```
 
-### Updating
+### Verify installation
 
-```bash
-npm update -g @qzhuli/qzhuli-cli
-npx -p @qzhuli/qzhuli-cli qz-install-skill --update
-```
+After install or update, confirm everything works:
 
-The postinstall script auto-installs the skill on `npm install -g`. Use the `npx` command above to update skills without
-reinstalling the whole package.
+1. `qz --version` — CLI version matches the installed package
+2. `npx -p @qzhuli/qzhuli-cli qz-install-skill --version` — skill version is current
+3. Check that `SKILL.md` exists in your agent's skill directory and contains valid `name` and `version` fields
 
 ## Commands
 
@@ -92,7 +89,7 @@ qz conversation list [--limit <n>] [--offset <n>]      # List conversations, def
 qz conversation profile <conversation-id> [--type <n>] # Get conversation details with user profiles
 
 # Messages
-qz message send <conversation-id> <target-cid> <content>
+qz message send <conversation-id> <content> [--role <n>]  # 0=Assistant(default), 1=User
 qz message history <conversation-id> [--from <id>] [--direction newer|older] [--limit <n>]
 ```
 

package/dist/cmd.js

@@ -11234,7 +11234,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",
@@ -11381,7 +11381,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",
@@ -11529,12 +11529,14 @@ init_cjs_shims();
 var TEST_CONFIG = {
   name: "test",
   baseURL: "https://test.client.qzhuli.com",
-  wsURL: "wss://test.im.qzhuli.com/ws"
+  imBaseURL: "https://test.im.qzhuli.com",
+  imWsURL: "wss://test.im.qzhuli.com/ws"
 };
 var PRODUCTION_CONFIG = {
   name: "production",
   baseURL: "https://client.qzhuli.com",
-  wsURL: "wss://im.qzhuli.com/ws"
+  imBaseURL: "https://im.qzhuli.com",
+  imWsURL: "wss://im.qzhuli.com/ws"
 };
 var ENV_MAP = {
   test: TEST_CONFIG,
@@ -11616,7 +11618,8 @@ function loadAppConfig(env) {
     locale: prefs.locale ?? "en",
     debug: prefs.debug ?? false,
     baseURL: envConfig.baseURL,
-    wsURL: envConfig.wsURL
+    imBaseURL: envConfig.imBaseURL,
+    imWsURL: envConfig.imWsURL
   };
 }
 
@@ -12829,12 +12832,8 @@ async function messageHistoryRun(factory, opts) {
 // src/commands/message/send.ts
 init_cjs_shims();
 async function messageSendRun(factory, opts) {
-  const result = await factory.imGateway.sendMessage(
-    opts.conversationId,
-    opts.targetCid,
-    opts.content
-  );
-  if (result.status === "error" && result.code === "AUTH_FAILED" /* AUTH_FAILED */) {
+  const cid = factory.config.cid;
+  if (!cid) {
     return {
       status: "error",
       code: "AUTH_FAILED" /* AUTH_FAILED */,
@@ -12842,14 +12841,39 @@ async function messageSendRun(factory, opts) {
       data: null
     };
   }
-  return result;
+  const req = {
+    sender_cid: cid,
+    conv_id: opts.conversationId,
+    content: opts.content,
+    role: opts.role ?? 0,
+    msg_type: 0 /* Text */
+  };
+  const result = await factory.gateway.pushMessage(req);
+  if (!result.ok) {
+    return {
+      status: "error",
+      code: result.code,
+      message: result.message,
+      data: null
+    };
+  }
+  return {
+    status: "success",
+    code: "MESSAGE_SENT" /* MESSAGE_SENT */,
+    message: result.data.message,
+    data: null
+  };
 }
 
 // src/commands/message/index.ts
 function NewCmdMessage(factory) {
   const cmd = new import_commander6.Command("message").description(t("commands.message.desc"));
-  cmd.command("send <conversation-id> <target-cid> <content>").description(t("commands.message.sendDesc")).action(async (conversationId, targetCid, content) => {
-    const result = await messageSendRun(factory, { conversationId, targetCid, content });
+  cmd.command("send <conversation-id> <content>").description(t("commands.message.sendDesc")).option("--role <n>", "Sender role: 0=Assistant, 1=User (default 0)", "0").action(async (conversationId, content, options3) => {
+    const result = await messageSendRun(factory, {
+      conversationId,
+      content,
+      role: parseInt(options3.role, 10)
+    });
     handleCommand(result);
   });
   cmd.command("history <conversation-id>").description(t("commands.message.historyDesc")).option("--from <id>", t("commands.message.fromOption")).option("--direction <newer|older>", t("commands.message.directionOption"), "older").option("--limit <n>", t("commands.message.limitOption"), "20").action(async (conversationId, options3) => {
@@ -13055,150 +13079,7 @@ function NewCmdUser(factory) {
 // src/factory.ts
 init_cjs_shims();
 
-// src/internal/api/api-gateway.ts
-init_cjs_shims();
-var ApiGateway = class {
-  constructor(client) {
-    this.client = client;
-  }
-  client;
-  setDryRun(enabled) {
-    this.client.setDryRun(enabled);
-  }
-  /** Check auth and return uid or a fail result. */
-  requireAuth() {
-    const uid = this.client.getAuthUid();
-    if (!uid) {
-      return {
-        ok: false,
-        code: "AUTH_FAILED" /* AUTH_FAILED */,
-        message: "Authentication required."
-      };
-    }
-    return { ok: true, data: uid };
-  }
-  // MARK: Friends / Contacts
-  /** POST /user/get_links_contacts — auth required */
-  getLinksContacts() {
-    const auth3 = this.requireAuth();
-    if (!auth3.ok) return Promise.resolve(auth3);
-    return this.client.performRequest("/user/get_links_contacts", "POST", {
-      uid: auth3.data
-    });
-  }
-  // MARK: Relation
-  /** POST /user/get_link_name_type — auth required, body: uid + friend_uid */
-  getLinkNameType(friendUid) {
-    const auth3 = this.requireAuth();
-    if (!auth3.ok) return Promise.resolve(auth3);
-    return this.client.performRequest("/user/get_link_name_type", "POST", {
-      uid: auth3.data,
-      friend_uid: friendUid
-    });
-  }
-  /** POST /user/update_link_name — auth required */
-  updateLinkName(friendUid, remark) {
-    const auth3 = this.requireAuth();
-    if (!auth3.ok) return Promise.resolve(auth3);
-    return this.client.performSimpleRequest("/user/update_link_name", "POST", {
-      uid: auth3.data,
-      friend_uid: friendUid,
-      link_name: remark
-    });
-  }
-  /** POST /user/update_link_type — auth required, body: friend_uid + link_type (string) */
-  updateLinkType(friendUid, groupType) {
-    const auth3 = this.requireAuth();
-    if (!auth3.ok) return Promise.resolve(auth3);
-    return this.client.performSimpleRequest("/user/update_link_type", "POST", {
-      friend_uid: friendUid,
-      link_type: String(groupType)
-    });
-  }
-  // MARK: User
-  /** POST /user/user_agent_profile — auth required, body: friend_uid + uid (+ agent_id) */
-  findUserById(id) {
-    const auth3 = this.requireAuth();
-    if (!auth3.ok) return Promise.resolve(auth3);
-    return this.client.performRequest("/user/user_agent_profile", "POST", {
-      friend_uid: id,
-      uid: auth3.data
-    });
-  }
-  /** POST /user/user_agent_profile — auth required, body: friend_uid + uid (+ agent_id) */
-  getUserAgentProfile(friendUid, agentId) {
-    const auth3 = this.requireAuth();
-    if (!auth3.ok) return Promise.resolve(auth3);
-    const params = {
-      friend_uid: friendUid,
-      uid: auth3.data
-    };
-    if (agentId) {
-      params.agent_id = agentId;
-    }
-    return this.client.performRequest("/user/user_agent_profile", "POST", params);
-  }
-  // MARK: QR Login
-  /** POST /user/qr_login_create/3 — no auth required */
-  qrLoginCreate() {
-    return this.client.performUnauthenticated(
-      "/user/qr_login_create/3",
-      "POST",
-      {}
-    );
-  }
-  /** POST /user/qr_login_status — no auth required */
-  qrLoginStatus(sceneId) {
-    return this.client.performUnauthenticated("/user/qr_login_status", "POST", {
-      scene_id: sceneId
-    });
-  }
-  // MARK: Connectivity
-  /** Quick connectivity check — calls the simplest endpoint. */
-  async ping() {
-    const result = await this.getLinksContacts();
-    if (result.ok) {
-      return { ok: true, data: true };
-    }
-    return result;
-  }
-  // MARK: Friend Add
-  /** POST /user/find_user_by_id — search any user by Q助号 */
-  searchUserById(id) {
-    return this.client.performRequest("/user/find_user_by_id", "POST", {
-      id
-    });
-  }
-  /** POST /user/create_conversation — auth required, body: uid + friend_uid + friend_agent_id */
-  createConversation(friendUid, friendAgentId) {
-    const auth3 = this.requireAuth();
-    if (!auth3.ok) return Promise.resolve(auth3);
-    return this.client.performRequest("/user/create_conversation", "POST", {
-      uid: auth3.data,
-      friend_uid: friendUid,
-      friend_agent_id: friendAgentId
-    });
-  }
-  /** POST /user/get_profile_by_conversation_id — auth required */
-  getProfileByConversationId(conversationId, conversationType) {
-    const auth3 = this.requireAuth();
-    if (!auth3.ok) return Promise.resolve(auth3);
-    const params = {
-      uid: auth3.data,
-      conversation_id: conversationId
-    };
-    if (conversationType !== void 0) {
-      params.conversation_type = conversationType;
-    }
-    return this.client.performRequest(
-      "/user/get_profile_by_conversation_id",
-      "POST",
-      params
-    );
-  }
-};
-
-// src/internal/api-client.ts
+// src/internal/api/api-client.ts
 init_cjs_shims();
 var import_node_crypto = require("crypto");
 var APIClient = class {
@@ -13378,6 +13259,238 @@ function printDryRun(url, method, body) {
   console.log();
 }
 
+// src/internal/api/api-gateway.ts
+init_cjs_shims();
+var ApiGateway = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  imApiClient = null;
+  /** Inject the IM HTTP client after gateway creation. */
+  setIMApiClient(client) {
+    this.imApiClient = client;
+  }
+  setDryRun(enabled) {
+    this.client.setDryRun(enabled);
+    this.imApiClient?.setDryRun(enabled);
+  }
+  /** Check auth and return uid or a fail result. */
+  requireAuth() {
+    const uid = this.client.getAuthUid();
+    if (!uid) {
+      return {
+        ok: false,
+        code: "AUTH_FAILED" /* AUTH_FAILED */,
+        message: "Authentication required."
+      };
+    }
+    return { ok: true, data: uid };
+  }
+  // MARK: Friends / Contacts
+  /** POST /user/get_links_contacts — auth required */
+  getLinksContacts() {
+    const auth3 = this.requireAuth();
+    if (!auth3.ok) return Promise.resolve(auth3);
+    return this.client.performRequest("/user/get_links_contacts", "POST", {
+      uid: auth3.data
+    });
+  }
+  // MARK: Relation
+  /** POST /user/get_link_name_type — auth required, body: uid + friend_uid */
+  getLinkNameType(friendUid) {
+    const auth3 = this.requireAuth();
+    if (!auth3.ok) return Promise.resolve(auth3);
+    return this.client.performRequest("/user/get_link_name_type", "POST", {
+      uid: auth3.data,
+      friend_uid: friendUid
+    });
+  }
+  /** POST /user/update_link_name — auth required */
+  updateLinkName(friendUid, remark) {
+    const auth3 = this.requireAuth();
+    if (!auth3.ok) return Promise.resolve(auth3);
+    return this.client.performSimpleRequest("/user/update_link_name", "POST", {
+      uid: auth3.data,
+      friend_uid: friendUid,
+      link_name: remark
+    });
+  }
+  /** POST /user/update_link_type — auth required, body: friend_uid + link_type (string) */
+  updateLinkType(friendUid, groupType) {
+    const auth3 = this.requireAuth();
+    if (!auth3.ok) return Promise.resolve(auth3);
+    return this.client.performSimpleRequest("/user/update_link_type", "POST", {
+      friend_uid: friendUid,
+      link_type: String(groupType)
+    });
+  }
+  // MARK: User
+  /** POST /user/user_agent_profile — auth required, body: friend_uid + uid (+ agent_id) */
+  findUserById(id) {
+    const auth3 = this.requireAuth();
+    if (!auth3.ok) return Promise.resolve(auth3);
+    return this.client.performRequest("/user/user_agent_profile", "POST", {
+      friend_uid: id,
+      uid: auth3.data
+    });
+  }
+  /** POST /user/user_agent_profile — auth required, body: friend_uid + uid (+ agent_id) */
+  getUserAgentProfile(friendUid, agentId) {
+    const auth3 = this.requireAuth();
+    if (!auth3.ok) return Promise.resolve(auth3);
+    const params = {
+      friend_uid: friendUid,
+      uid: auth3.data
+    };
+    if (agentId) {
+      params.agent_id = agentId;
+    }
+    return this.client.performRequest("/user/user_agent_profile", "POST", params);
+  }
+  // MARK: QR Login
+  /** POST /user/qr_login_create/3 — no auth required */
+  qrLoginCreate() {
+    return this.client.performUnauthenticated(
+      "/user/qr_login_create/3",
+      "POST",
+      {}
+    );
+  }
+  /** POST /user/qr_login_status — no auth required */
+  qrLoginStatus(sceneId) {
+    return this.client.performUnauthenticated("/user/qr_login_status", "POST", {
+      scene_id: sceneId
+    });
+  }
+  // MARK: Connectivity
+  /** Quick connectivity check — calls the simplest endpoint. */
+  async ping() {
+    const result = await this.getLinksContacts();
+    if (result.ok) {
+      return { ok: true, data: true };
+    }
+    return result;
+  }
+  // MARK: Friend Add
+  /** POST /user/find_user_by_id — search any user by Q助号 */
+  searchUserById(id) {
+    return this.client.performRequest("/user/find_user_by_id", "POST", {
+      id
+    });
+  }
+  /** POST /user/create_conversation — auth required, body: uid + friend_uid + friend_agent_id */
+  createConversation(friendUid, friendAgentId) {
+    const auth3 = this.requireAuth();
+    if (!auth3.ok) return Promise.resolve(auth3);
+    return this.client.performRequest("/user/create_conversation", "POST", {
+      uid: auth3.data,
+      friend_uid: friendUid,
+      friend_agent_id: friendAgentId
+    });
+  }
+  /** POST /user/get_profile_by_conversation_id — auth required */
+  getProfileByConversationId(conversationId, conversationType) {
+    const auth3 = this.requireAuth();
+    if (!auth3.ok) return Promise.resolve(auth3);
+    const params = {
+      uid: auth3.data,
+      conversation_id: conversationId
+    };
+    if (conversationType !== void 0) {
+      params.conversation_type = conversationType;
+    }
+    return this.client.performRequest(
+      "/user/get_profile_by_conversation_id",
+      "POST",
+      params
+    );
+  }
+  // MARK: IM
+  /** POST /api/v1/conversations/push_message — JSON body, no HMAC signature */
+  async pushMessage(req) {
+    if (!this.imApiClient) {
+      return {
+        ok: false,
+        code: "INTERNAL_ERROR" /* INTERNAL_ERROR */,
+        message: "IM API client not configured."
+      };
+    }
+    return this.imApiClient.pushMessage(req);
+  }
+};
+
+// src/internal/api/im-api-client.ts
+init_cjs_shims();
+var IMApiClient = class {
+  baseURL;
+  debugEnabled = false;
+  dryRun = false;
+  constructor(baseURL, debugEnabled = false) {
+    this.baseURL = baseURL;
+    this.debugEnabled = debugEnabled;
+  }
+  setDryRun(enabled) {
+    this.dryRun = enabled;
+  }
+  setDebug(enabled) {
+    this.debugEnabled = enabled;
+  }
+  async pushMessage(req) {
+    const url = `${this.baseURL}/api/v1/conversations/push_message`;
+    if (this.dryRun) {
+      this.log("[dry-run]", url, req);
+      return ok({
+        status: "success",
+        sender_cid: req.sender_cid ?? "",
+        conv_id: req.conv_id,
+        message: "Message sent successfully"
+      });
+    }
+    this.log("POST", url, req);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(req)
+      });
+      const text = await response.clone().text();
+      this.log(`${response.status} ${response.statusText}`, text);
+      if (!response.ok) {
+        return fail(
+          response.status === 401 || response.status === 403 ? "AUTH_FAILED" /* AUTH_FAILED */ : "NETWORK_ERROR" /* NETWORK_ERROR */,
+          `HTTP ${response.status}: ${response.statusText}`
+        );
+      }
+      let json;
+      try {
+        json = JSON.parse(text);
+      } catch {
+        return fail("DECODE_ERROR" /* DECODE_ERROR */, "Failed to parse push_message response");
+      }
+      if (json.code !== 200) {
+        return fail("API_ERROR" /* API_ERROR */, json.msg || `API error (code: ${json.code})`);
+      }
+      if (json.data === null) {
+        return fail("NOT_FOUND" /* NOT_FOUND */, "push_message returned empty data");
+      }
+      return ok(json.data);
+    } catch (error) {
+      return fail(
+        "NETWORK_ERROR" /* NETWORK_ERROR */,
+        error instanceof Error ? error.message : "Failed to push message"
+      );
+    }
+  }
+  log(...args) {
+    if (this.debugEnabled) {
+      console.log("[PUSH]", ...args);
+    }
+  }
+};
+
 // src/internal/im/im-gateway.ts
 init_cjs_shims();
 
@@ -13738,7 +13851,7 @@ var IMClient = class {
   }
   // MARK: - Private
   buildWsUrl() {
-    const httpUrl = this.config.wsUrl;
+    const httpUrl = this.config.imWsURL;
     let wsUrl = httpUrl.replace(/^http/, "ws");
     wsUrl = wsUrl.replace(/\/+$/, "");
     if (!wsUrl.endsWith("/ws")) {
@@ -14736,8 +14849,9 @@ function createFactory(config) {
     client.setAuth({ uid: config.uid, tk: config.tk, token: config.token });
   }
   const gateway = new ApiGateway(client);
+  gateway.setIMApiClient(new IMApiClient(config.imBaseURL, config.debug));
   const imGateway = new IMGateway({
-    wsUrl: config.wsURL,
+    imWsURL: config.imWsURL,
     cid: config.cid,
     debugEnabled: config.debug
   });
@@ -14807,7 +14921,7 @@ async function main() {
 ${t("cli.banner")}` : t("cli.banner");
   program.addHelpText("beforeAll", `${banner}
 `);
-  program.name("qz").version(`v${"0.4.3"}`, "-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.1"}`, "-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.4.3",
+  "version": "0.5.1",
   "description": "CLI tool for Q助理 (QZhuli)",
   "main": "dist/cmd.js",
   "bin": {

package/scripts/install-skill.mjs

@@ -6,6 +6,7 @@
  *   node scripts/install-skill.mjs                            # install to all detected agents (global)
  *   node scripts/install-skill.mjs --project                  # install to current project's skills dir
  *   node scripts/install-skill.mjs --agent claude-code        # install to specific agent only
+ *   node scripts/install-skill.mjs --target /path/to/skills   # install to custom directory
  *   node scripts/install-skill.mjs --help                     # show help
  *
  * Works with:
@@ -51,8 +52,27 @@ function getPkgVersion() {
 
 // ── CLI parsing ────────────────────────────────────────────────────
 
+function printVersion(sourceDir) {
+  const pkgVersion = getPkgVersion();
+  const skillVersion = sourceDir ? readSkillVersion(sourceDir) : 'n/a';
+  console.log(`@qzhuli/qzhuli-cli  v${pkgVersion}`);
+  console.log(`qzhuli skill        v${skillVersion}`);
+}
+
+function readSkillVersion(sourceDir) {
+  const skillMd = join(sourceDir, 'SKILL.md');
+  if (!existsSync(skillMd)) return 'n/a';
+  try {
+    const content = readFileSync(skillMd, 'utf8');
+    const match = content.match(/^version:\s*(.+)$/m);
+    return match ? match[1].trim() : 'n/a';
+  } catch {
+    return 'n/a';
+  }
+}
+
 function parseArgs(argv) {
-  const args = { project: false, agent: null, help: false, update: false };
+  const args = { project: false, agent: null, help: false, update: false, target: null, version: false };
   for (let i = 0; i < argv.length; i++) {
     switch (argv[i]) {
       case '--project':
@@ -64,6 +84,12 @@ function parseArgs(argv) {
       case '--update':
         args.update = true;
         break;
+      case '--target':
+        args.target = argv[++i];
+        break;
+      case '--version':
+        args.version = true;
+        break;
       case '--help':
       case '-h':
         args.help = true;
@@ -80,13 +106,16 @@ Usage: node install-skill.mjs [options]
 Options:
   --project            Install to current project's .claude/skills (or equivalent)
   --agent <name>       Install to a specific agent only (e.g. claude-code, cursor)
+  --target <path>      Install to a custom directory path (skips agent detection)
   --update             Check for updates and reinstall if version changed
+  --version            Show package and skill version
   --help, -h           Show this help message
 
 Examples:
   node scripts/install-skill.mjs                       # global, all agents
   node scripts/install-skill.mjs --project             # project-level, all agents
   node scripts/install-skill.mjs --agent claude-code   # global, claude-code only
+  node scripts/install-skill.mjs --target /path/to/skills  # custom directory
   node scripts/install-skill.mjs --update              # update all installed agents
   npx @qzhuli/qzhuli-cli scripts/install-skill.mjs     # from published npm
 `);
@@ -97,6 +126,7 @@ Examples:
 function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) { printHelp(); process.exit(0); }
+  if (opts.version) { printVersion(findSourceDir()); process.exit(0); }
 
   const sourceDir = findSourceDir();
   if (!sourceDir) {
@@ -109,7 +139,11 @@ function main() {
 
   // Resolve target agents
   let targets = [];
-  if (opts.update) {
+  if (opts.target) {
+    // --target: install to an arbitrary directory path
+    const targetPath = resolve(opts.target);
+    targets.push({ cfg: { name: `custom:${targetPath}`, global: targetPath }, isProject: false, isCustom: true });
+  } else if (opts.update) {
     // --update: check agents that already have the skill installed
     const candidates = opts.agent
       ? [AGENT_PATHS.find(a => a.name === opts.agent)]

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: 3
+version: 0.1.1
 ---
 
 # QZhuli CLI
@@ -38,45 +38,36 @@ When ANY of the following applies, STOP and ask the user first:
 - **Ambiguous search results**: `status: "needs_resolution"` — show options and ask.
 - **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.
-- **Message sending**: Before `message send`, show the target conversation, recipient, and message content.
 - **Cache clearing**: Before `cache clear`, confirm scope (all tables vs single table).
-- **Any write operation** (`user add`, `relation set`, `message send`, `conversation create`, `cache clear`): confirm
+- **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> <cid> "hello"
-qz --dry-run relation set <uid> --remark "New Name"
-```
-
 ### Least-Surprise Principle
 
-- Never auto-send messages without explicit content approval.
 - Never change a friend's remark without showing both old and new.
 - Never delete cache data without confirming scope.
 - If the user says "send a message" but doesn't specify content, draft it and ask before sending.
 
-## ID Reference
+### Message Role Detection
 
-The CLI uses 5 distinct ID types. **Using the wrong type will fail silently or hit the wrong target.**
+When sending messages, determine the role based on the user's wording:
 
-| 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` |
-| CID             | `cid`            | UUID                    | `5c2f46c2-b0d3-405d-ad21-d833538b77f7` | `message send <target-cid>` — **use the OTHER participant's cid, not your own**                                     |
-| Conversation ID | `conversationId` | Base64-like long string | `9boGaR7iii2Jdjhmb5LSo37...`           | `message send`, `message history`, `conversation profile`                                                           |
-| Agent ID        | `agent.id`       | Number                  | `5`                                    | `conversation create --agent-id`                                                                                    |
+- If the user says something like **"以我的名义"** (in my name), **"帮我发给"** (help me send to), **"替我发送"** (send
+  on my behalf), or similar phrasing indicating they want to send as themselves → use `--role 1` (User).
+- Otherwise, send normally without `--role` (defaults to `0` = Assistant).
+
+## ID Reference
 
-**Quick identification by format**:
+The CLI uses 4 distinct ID types. **Using the wrong type will fail silently or hit the wrong target.**
 
-- A short integer → Q助号
-- A 32-char hex string → UID
-- A UUID with dashes → CID
-- 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` (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`                                                                                    |
 
 **Common mistake**: Using UID for `message send` instead of conversationId. Always resolve via `conversation search` or
 `conversation list` first.
@@ -112,9 +103,6 @@ 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                                                                                       |
@@ -138,7 +126,7 @@ login/logout, and preference writes.
 | 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> <target-cid> <content>`                                    |
+| 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`                                                                             |
@@ -156,8 +144,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>`
 
@@ -172,22 +160,26 @@ 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 <q-number>
+qz conversation search <uid> --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).
-4. Pick `target-cid` from that conversation's `users` array — **use the OTHER participant's cid**.
-5. Show recipient name and message content to user, confirm.
-6. Send: `qz message send <conversation-id> <target-cid> "message text"`
-7. Verify: `qz message history <conversation-id> --limit 5`
+2. **Check existing conversation**: Use `conversation search <q-number>` or `conversation search <uid> --uid` 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"`
+6. Verify: `qz message history <conversation-id> --limit 5`
 
 ### Page Through Message History
 
@@ -199,35 +191,20 @@ 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
 
-| Symptom                         | Action                                                                                                        |
-|---------------------------------|---------------------------------------------------------------------------------------------------------------|
-| Command not found               | Confirm `qz` is on PATH. Install: `npm install -g @qzhuli/qzhuli-cli`                                         |
-| Auth failure                    | `qz auth status`; then `qz auth login` if needed                                                              |
-| Unexpected language             | `qz config --locale en` or `--locale zh`                                                                      |
-| Too much JSON                   | Use `--jq ".data"` or another simple dot path                                                                 |
-| Need no-op preview              | Use `--dry-run`                                                                                               |
-| Message send cid error          | Re-check `auth status`, choose `target-cid` from `conversation list` — it must be the other participant's cid |
-| 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                                   |
-| `relation set` INVALID_ARGUMENT | Must include at least one of `--remark` or `--type`                                                           |
+| Symptom                         | Action                                                                      |
+|---------------------------------|-----------------------------------------------------------------------------|
+| Command not found               | Confirm `qz` is on PATH. Install: `npm install -g @qzhuli/qzhuli-cli`       |
+| Auth failure                    | `qz auth status`; then `qz auth login` if needed                            |
+| Unexpected language             | `qz config --locale en` or `--locale zh`                                    |
+| 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 |
+| `relation set` INVALID_ARGUMENT | Must include at least one of `--remark` or `--type`                         |