@qzhuli/qzhuli-cli 0.5.0 → 0.5.1

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",
@@ -14921,7 +14921,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.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.5.0",
+  "version": "0.5.1",
   "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.1
 ---
 
 # 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.
@@ -76,12 +69,6 @@ The CLI uses 4 distinct ID types. **Using the wrong type will fail silently or h
 | 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
-
 **Common mistake**: Using UID for `message send` instead of conversationId. Always resolve via `conversation search` or
 `conversation list` first.
 
@@ -116,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                                                                                       |
@@ -160,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>`
 
@@ -176,18 +160,22 @@ 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).
+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"`
@@ -203,23 +191,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 +203,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 |