@qzhuli/qzhuli-cli 0.1.0-beta.2 → 0.2.0

package/dist/cmd.js

@@ -13641,7 +13641,7 @@ async function main() {
 ${t("cli.banner")}` : t("cli.banner");
   program.addHelpText("beforeAll", `${banner}
 `);
-  program.name("qz").version(`v${"0.1.0-beta.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.name("qz").version(`v${"0.2.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.usage("<command> [subcommand] [options]");
   program.hook("preAction", () => {
     const opts = program.opts();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qzhuli/qzhuli-cli",
-  "version": "0.1.0-beta.2",
+  "version": "0.2.0",
   "description": "CLI tool for Q助理 (QZhuli)",
   "main": "dist/cmd.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "CONTRIBUTING.md"
   ],

package/skills/qzhuli-cli/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: qzhuli-cli
+description: Use when operating the QZhuli CLI with qz, including login, auth status, config, friends, relations, users, conversations, messages, JSON filtering, dry-run, command help, and interpreting test-environment banners or config files.
+version: 1
+---
+
+# QZhuli CLI
+
+Use this skill as a concise operating manual for the `qz` command.
+
+## First Checks
+
+1. Check whether the user is logged in:
+   ```bash
+   qz auth status
+   ```
+2. If auth is missing or expired, run QR login and ask the user to scan:
+   ```bash
+   qz auth login
+   ```
+3. For exact syntax, use command help:
+   ```bash
+   qz --help
+   qz <command> --help
+   qz <command> <subcommand> --help
+   ```
+
+## Environment and Config Files
+
+If the CLI prints a `DEVELOPMENT BUILD` / `Running in TEST environment` banner, it is using the test environment and
+stores config under `./.qzhuli-cli/` relative to the process working directory.
+
+| Visible behavior  | Environment | Config directory |
+|-------------------|-------------|------------------|
+| Shows test banner | test        | `./.qzhuli-cli/` |
+| No test banner    | production  | `~/.qzhuli-cli/` |
+
+Treat `credentials.json` as secret. Preferences live in `preferences.json`.
+
+## Output and Global Options
+
+Commands return JSON with `status`, `code`, `message`, and `data`. Check `status`, not only the exit code; ambiguous
+friend lookups can return `status: "needs_resolution"`.
+
+Use `--jq` for simple dot-path filtering:
+
+```bash
+qz --jq ".data.uid" auth status
+qz --jq ".data.links" friend list
+qz --jq ".data" conversation list --limit 5
+```
+
+`--jq` is not full jq. Prefer simple paths such as `.data`, `.data.uid`, `.data.links`.
+
+Use `--dry-run` when you need to avoid side effects. It is wired through output handling, 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 <query>`                                                                      |
+| Search user (UID)          | `qz user search <query> --uid`                                                                |
+| Add friend (Q助号)           | `qz user add <q-number>`                                                                      |
+| List friends               | `qz friend list`                                                                              |
+| Resolve profile (nickname) | `qz friend profile <query>`                                                                   |
+| Resolve profile (UID)      | `qz friend profile <query> --uid`                                                             |
+| Resolve profile (remark)   | `qz friend profile <query> --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>]`                                                          |
+| Create conversation        | `qz conversation create <uid> --agent-id <id>`                                                |
+| Send message               | `qz message send <conversation-id> <target-cid> <content>`                                    |
+| Read message history       | `qz message history <conversation-id> [--from <id>] [--direction newer\|older] [--limit <n>]` |
+
+Relation type values are `0=stranger`, `1=friend`, `2=family`, `3=colleague`.
+
+## Common Workflows
+
+### Find a Friend and Inspect Relation
+
+1. List candidates:
+   ```bash
+   qz friend list
+   ```
+2. Resolve ambiguous names:
+   ```bash
+   qz friend profile "<nickname>"
+   ```
+3. Use the resolved `uid`:
+   ```bash
+   qz relation get <uid>
+   ```
+
+### Update a Friend Relation
+
+1. Resolve the exact `uid` first with `friend list` or `friend profile`.
+2. Confirm with the user before changing data.
+3. Execute one or both updates:
+   ```bash
+   qz relation set <uid> --remark "Product Manager" --type 1
+   ```
+4. Verify:
+   ```bash
+   qz relation get <uid>
+   ```
+
+Do not run `relation set` without `--remark` or `--type`; the CLI returns `INVALID_ARGUMENT`.
+
+### Search and Add a Friend
+
+1. Search by Q助号:
+   ```bash
+   qz user search 10000
+   ```
+2. Add directly by Q助号:
+   ```bash
+   qz user add 10000
+   ```
+
+### Send a Message
+
+1. Confirm auth:
+   ```bash
+   qz auth status
+   ```
+2. Get conversations:
+   ```bash
+   qz conversation list --limit 10
+   ```
+3. Pick the conversation `id`.
+4. Pick `target-cid` from that conversation's `cids`; for one-to-one chats this is usually the other participant's cid,
+   not the current user's own `cid`.
+5. Confirm recipient and content with the user if there is any ambiguity.
+6. Send:
+   ```bash
+   qz message send <conversation-id> <target-cid> "message text"
+   ```
+7. Verify:
+   ```bash
+   qz message history <conversation-id> --limit 5
+   ```
+
+### Page Through Message History
+
+```bash
+qz message history <conversation-id> --limit 20
+qz message history <conversation-id> --from <message-id> --direction older --limit 20
+qz message history <conversation-id> --from <message-id> --direction newer --limit 20
+```
+
+## Troubleshooting
+
+| Symptom                | Action                                                                   |
+|------------------------|--------------------------------------------------------------------------|
+| Command not found      | Confirm `qz` is installed or available on `PATH`.                        |
+| Auth failure           | Run `qz auth status`; then `qz auth login` if needed.                    |
+| Unexpected language    | Run `qz config --locale en` or `qz config --locale zh`.                  |
+| Too much JSON          | Use `--jq ".data"` or another simple dot path.                           |
+| Need a no-op preview   | Use `--dry-run`.                                                         |
+| Message send cid error | Re-check `auth status` and choose `target-cid` from `conversation list`. |