@qzhuli/qzhuli-cli 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qzhuli/qzhuli-cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "CLI tool for Q助理 (QZhuli)",
   "main": "dist/cmd.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "scripts/postinstall.mjs",
     "skills",
     "README.md",
     "CONTRIBUTING.md"
@@ -26,6 +27,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "pnpm build",
+    "postinstall": "node scripts/postinstall.mjs",
     "qz": "node dist/cmd.js",
     "install:local:test": "cross-env QZ_BUILD_ENV=test pnpm build && npm install -g .",
     "install:local:prod": "pnpm build && npm install -g .",
@@ -42,6 +44,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "better-sqlite3": "^12.10.0",
     "commander": "^14.0.3",
     "protobufjs": "^8.0.1",
     "qrcode-terminal": "^0.12.0",
@@ -49,6 +52,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.12",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.6.0",
     "@types/qrcode-terminal": "^0.12.2",
     "@types/ws": "^8.18.1",

package/scripts/postinstall.mjs

@@ -0,0 +1,226 @@
+/**
+ * Postinstall script for @qzhuli/qzhuli-cli
+ *
+ * Auto-installs the qzhuli-cli skill to all detected AI agents.
+ *
+ * Features:
+ * - Detects installed agents by checking home/project config dirs
+ * - Copies the skill to each agent's skill directory (global + project)
+ * - Skips in CI environments (CI, CONTINUOUS_INTEGRATION env vars)
+ * - Skips if AX_SKIP_SKILL_INSTALL=1
+ * - Silent failure — never breaks npm install
+ * - Cross-platform (macOS, Linux, Windows)
+ * - Content-dedup: skips if identical file already exists
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  copyFileSync,
+  mkdirSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ── Agent path mapping ─────────────────────────────────────────────
+// Source: https://www.agentskills.in/docs/getting-started
+const AGENT_PATHS = [
+  { name: 'claude-code', global: '~/.claude/skills',        project: '.claude/skills' },
+  { name: 'cursor',      global: '~/.cursor/skills',        project: '.cursor/skills' },
+  { name: 'codex',       global: '~/.codex/skills',         project: '.codex/skills' },
+  { name: 'copilot',     global: '~/.copilot/skills',       project: '.github/skills' },
+  { name: 'windsurf',    global: '~/.codeium/windsurf/skills', project: '.windsurf/skills' },
+  { name: 'openclaw',    global: '~/.openclaw/skills',      project: 'skills' },
+  { name: 'opencode',    global: '~/.config/opencode/skill',project: '.opencode/skill' },
+  { name: 'cline',       global: '~/.cline/skills',         project: '.cline/skills' },
+  { name: 'gemini-cli',  global: '~/.gemini/skills',        project: '.gemini/skills' },
+  { name: 'amp',         global: '~/.config/agents/skills', project: '.agents/skills' },
+  { name: 'roo',         global: '~/.roo/skills',           project: '.roo/skills' },
+  { name: 'goose',       global: '~/.config/goose/skills',  project: '.goose/skills' },
+  { name: 'kiro',        global: '~/.kiro/skills',          project: '.kiro/skills' },
+  { name: 'qwen-code',   global: '~/.qwen/skills',          project: '.qwen/skills' },
+  { name: 'qoder',       global: '~/.qoder/skills',         project: '.qoder/skills' },
+  { name: 'trae',        global: '~/.trae/skills',          project: '.trae/skills' },
+  { name: 'augment',     global: '~/.augment/skills',       project: '.augment/skills' },
+  { name: 'zed',         global: '~/.config/zed/skills',    project: '.zed/skills' },
+];
+
+const SKILL_NAME = 'qzhuli-cli';
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function resolveHome(p) {
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  return p;
+}
+
+function dirExists(p) {
+  try {
+    return statSync(resolveHome(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function shouldSkip() {
+  return (
+    process.env.CI === 'true' ||
+    process.env.CONTINUOUS_INTEGRATION === 'true' ||
+    process.env.AX_SKIP_SKILL_INSTALL === '1'
+  );
+}
+
+function isInteractive() {
+  return process.stdout.isTTY;
+}
+
+/**
+ * Walk up from startDir to find the project root (where node_modules/@qzhuli/qzhuli-cli lives).
+ * Returns null for global installs, or false for dev/source installs.
+ *
+ * Detection logic:
+ * - If __dirname contains node_modules/@qzhuli/qzhuli-cli → it's an npm install
+ *   - If path matches global node_modules prefix → global install → return null
+ *   - Otherwise → local project install → return project root
+ * - Otherwise → dev/source install → return false (skip skill install)
+ */
+function findProjectRoot() {
+  const scriptDir = resolve(__dirname, '..');
+  const normalized = scriptDir.replace(/\\/g, '/');
+  const nmIdx = normalized.lastIndexOf('node_modules/@qzhuli/qzhuli-cli');
+
+  if (nmIdx === -1) {
+    // Not installed via npm — this is a dev/source checkout, skip
+    return false;
+  }
+
+  // It's in node_modules. Determine if global or project-level.
+  const projectRoot = normalized.slice(0, nmIdx).replace(/\/$/, '');
+
+  // Global installs end up in paths like:
+  //   /usr/lib/node_modules/@qzhuli/qzhuli-cli
+  //   C:/Users/X/AppData/Roaming/npm/node_modules/@qzhuli/qzhuli-cli
+  //   /Users/X/.nvm/versions/node/v22.X/lib/node_modules/@qzhuli/qzhuli-cli
+  // After slicing off node_modules/..., the projectRoot is either empty
+  // or just a system prefix. We check if there's a package.json at projectRoot.
+  if (!projectRoot) return null; // no prefix → treat as global
+
+  const pkgAtRoot = join(projectRoot.replace(/\//g, sep), 'package.json');
+  if (!existsSync(pkgAtRoot)) return null;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgAtRoot, 'utf8'));
+    // If the project root's package.json is our own package, it's global
+    if (pkg.name === '@qzhuli/qzhuli-cli') return null;
+  } catch {
+    return null;
+  }
+
+  return projectRoot.replace(/\//g, sep);
+}
+
+/**
+ * Detect which agents are installed by checking if their config dirs exist globally.
+ */
+function detectAgents() {
+  return AGENT_PATHS
+    .filter(agent => dirExists(agent.global))
+    .map(agent => agent.name);
+}
+
+/**
+ * Recursively copy a directory.
+ */
+function copyDir(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  const entries = readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Check if a skill is already installed with identical content.
+ */
+function isInstalled(skillTarget, sourceDir) {
+  if (!existsSync(skillTarget)) return false;
+  try {
+    const srcFiles = readdirSync(sourceDir);
+    const destFiles = readdirSync(skillTarget);
+    if (srcFiles.length !== destFiles.length) return false;
+    // Compare SKILL.md content (primary file)
+    const srcMd = join(sourceDir, 'SKILL.md');
+    const destMd = join(skillTarget, 'SKILL.md');
+    if (!existsSync(destMd)) return false;
+    return readFileSync(srcMd, 'utf8') === readFileSync(destMd, 'utf8');
+  } catch {
+    return false;
+  }
+}
+
+// ── Main ───────────────────────────────────────────────────────────
+
+function install() {
+  if (shouldSkip()) { console.log('SKIP: CI or env'); return; }
+
+  try {
+    const sourceDir = join(__dirname, '..', 'skills', SKILL_NAME);
+    if (!existsSync(sourceDir)) return;
+
+    const projectRoot = findProjectRoot();
+    // false = dev/source install, skip
+    if (projectRoot === false) { console.log('SKIP: dev install'); return; }
+    const isGlobal = projectRoot === null;
+    const cwd = projectRoot || process.cwd();
+
+    // Detect installed agents
+    const detectedAgents = detectAgents();
+    // Always include claude-code as fallback if nothing detected
+    const targets = detectedAgents.length > 0 ? detectedAgents : ['claude-code'];
+
+    const results = [];
+
+    for (const agentName of targets) {
+      const agentConfig = AGENT_PATHS.find(a => a.name === agentName);
+      if (!agentConfig) continue;
+
+      const targetPath = isGlobal
+        ? resolveHome(agentConfig.global)
+        : join(cwd, agentConfig.project);
+
+      const skillTarget = join(targetPath, SKILL_NAME);
+
+      // Skip if already installed with identical content
+      if (isInstalled(skillTarget, sourceDir)) continue;
+
+      copyDir(sourceDir, skillTarget);
+      results.push(agentName);
+    }
+
+    // Report (only in interactive terminals)
+    if (results.length > 0 && isInteractive()) {
+      const noun = results.length === 1 ? 'agent' : 'agents';
+      console.log(
+        `✓ qzhuli-cli skill installed to ${results.length} ${noun}: ${results.join(', ')}`
+      );
+    }
+  } catch {
+    // Silent failure — never break npm install
+    // Users can follow AGENT-SETUP.md for manual installation
+  }
+}
+
+install();

package/skills/qzhuli-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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
+description: Use when operating the QZhuli CLI with 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: 2
 ---
 
 # QZhuli CLI
@@ -47,7 +47,7 @@ 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
+qz --jq ".data" conversation list --limit 5 --offset 0
 ```
 
 `--jq` is not full jq. Prefer simple paths such as `.data`, `.data.uid`, `.data.links`.
@@ -55,6 +55,28 @@ qz --jq ".data" conversation list --limit 5
 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.
 
+## Cache Architecture
+
+All read operations use a **Repository Pattern** with SQLite-backed caching:
+
+- **Local-first**: reads hit a local SQLite database (`~/.qzhuli-cli/cache.db`) before the remote API
+- **TTL-based expiration**: conversations expire after 30 minutes, contacts/relations after 5 minutes, user profiles after 1 hour
+- **Incremental sync**: sync compares the IM conversation list against a local index, only fetching profiles for *new* conversations
+- **Auto-sync on miss**: cache miss triggers an incremental sync (not full refetch)
+- **Manual sync**: use `qz cache sync` to sync only new data
+
+Cache database tables:
+
+- `conversations_index` — lightweight IM metadata (id, version, members, nicks) for incremental sync
+- `conversation_profiles` — full conversation profile data with user_ids index
+- `contacts_cache` — full contacts list per owner UID
+- `user_profiles` — individual user profiles
+- `relations_cache` — friend relations (remark, type)
+- `messages_cache` — message history per conversation
+
+Write operations (send message, create conversation, update relation) bypass the cache and write directly to the API,
+then invalidate relevant cache entries.
+
 ## Command Map
 
 | Goal                       | Command                                                                                       |
@@ -73,10 +95,15 @@ actions, auth login/logout, and preference writes.
 | 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>]`                                                          |
+| 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 user conversations  | `qz conversation search <query> [--uid]`                                                      |
 | 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>]` |
+| **Sync cache**             | `qz cache sync`                                                                               |
+| **Cache status**           | `qz cache status`                                                                             |
+| **Clear cache**            | `qz cache clear [--table <name>]`                                                             |
 
 Relation type values are `0=stranger`, `1=friend`, `2=family`, `3=colleague`.
 
@@ -123,6 +150,23 @@ Do not run `relation set` without `--remark` or `--type`; the CLI returns `INVAL
    qz user add 10000
    ```
 
+### Find All Conversations with a User
+
+Search by Q助号 (default):
+
+```bash
+qz conversation search 10000
+```
+
+Search by UID:
+
+```bash
+qz conversation search 79345121120f6e5288238749 --uid
+```
+
+The response includes `id` (Q助号, number), `uid` (internal user ID, string), and `conversations` with full profile
+data. Each conversation entry contains `conversationId`, `isGroup`, `users` (with camelCase fields), and `visitors`.
+
 ### Send a Message
 
 1. Confirm auth:
@@ -154,6 +198,14 @@ qz message history <conversation-id> --from <message-id> --direction older --lim
 qz message history <conversation-id> --from <message-id> --direction newer --limit 20
 ```
 
+### 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
+```
+
 ## Troubleshooting
 
 | Symptom                | Action                                                                   |
@@ -164,3 +216,5 @@ qz message history <conversation-id> --from <message-id> --direction newer --lim
 | 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`. |
+| Slow queries           | Run `qz cache sync` first (incremental, fast), then retry — results come from local SQLite. |
+| Cache corrupted        | Run `qz cache clear` to reset, then retry (falls back to API).           |