@qzhuli/qzhuli-cli 0.3.0 → 0.4.0-rc.2

package/README.md

@@ -23,6 +23,41 @@ npm install @qzhuli/qzhuli-cli
 npx qz --version
 ```
 
+## AI Agent Skill
+
+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)
+
+Claude Code, Cursor, Codex, Copilot, Windsurf, OpenClaw, OpenCode, Cline, Gemini CLI, Amp, Roo, Goose, Kiro, Qwen Code, Qoder, Trae, Augment, Zed.
+
+### Manual skill install
+
+If the automatic install didn't work (e.g. local `npm install` without `-g`):
+
+```bash
+# Install to all detected agents (global)
+npx @qzhuli/qzhuli-cli scripts/install-skill.mjs
+
+# Install to current project's skill directory
+npx @qzhuli/qzhuli-cli scripts/install-skill.mjs --project
+
+# Install to a specific agent only
+npx @qzhuli/qzhuli-cli scripts/install-skill.mjs --agent claude-code
+
+# Update existing installs if skill version changed
+npx @qzhuli/qzhuli-cli scripts/install-skill.mjs --update
+```
+
+### Updating
+
+```bash
+npm update -g @qzhuli/qzhuli-cli
+npx @qzhuli/qzhuli-cli scripts/install-skill.mjs --update
+```
+
+The postinstall script auto-installs the skill on `npm install -g`. Use the `npx` command above to update skills without reinstalling the whole package.
+
 ## Commands
 
 ```bash

package/dist/cmd.js

@@ -14807,7 +14807,7 @@ async function main() {
 ${t("cli.banner")}` : t("cli.banner");
   program.addHelpText("beforeAll", `${banner}
 `);
-  program.name("qz").version(`v${"0.3.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.4.0-rc.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.3.0",
+  "version": "0.4.0-rc.2",
   "description": "CLI tool for Q助理 (QZhuli)",
   "main": "dist/cmd.js",
   "bin": {
@@ -9,6 +9,8 @@
   "files": [
     "dist",
     "scripts/postinstall.mjs",
+    "scripts/install-skill.mjs",
+    "scripts/skill-agent.mjs",
     "skills",
     "README.md",
     "CONTRIBUTING.md"

package/scripts/install-skill.mjs

@@ -0,0 +1,201 @@
+/**
+ * Standalone skill installer for @qzhuli/qzhuli-cli
+ *
+ * Usage:
+ *   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 --help                     # show help
+ *
+ * Works with:
+ *   - Published npm package: `npx @qzhuli/qzhuli-cli scripts/install-skill.mjs`
+ *   - Dev/source checkout:   `node scripts/install-skill.mjs` (from repo root)
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENT_PATHS, SKILL_NAME, resolveHome, copyDir, isInstalled, detectAgents, writeManifest, needsUpdate, readManifest } from './skill-agent.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function findSourceDir() {
+  // Case 1: running from repo root (dev checkout)
+  const repoSkills = resolve(__dirname, '..', 'skills', SKILL_NAME);
+  if (existsSync(join(repoSkills, 'SKILL.md'))) return repoSkills;
+
+  // Case 2: running from npm package (node_modules)
+  const pkgSkills = resolve(__dirname, '..', '..', 'skills', SKILL_NAME);
+  if (existsSync(join(pkgSkills, 'SKILL.md'))) return pkgSkills;
+
+  // Case 3: skills dir is at package root (flattened install)
+  const flatSkills = resolve(__dirname, '..', 'skills');
+  if (existsSync(join(flatSkills, SKILL_NAME, 'SKILL.md'))) return join(flatSkills, SKILL_NAME);
+
+  return null;
+}
+
+function getPkgVersion() {
+  try {
+    const pkgJson = resolve(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgJson, 'utf8'));
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+// ── CLI parsing ────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { project: false, agent: null, help: false, update: false };
+  for (let i = 0; i < argv.length; i++) {
+    switch (argv[i]) {
+      case '--project':
+        args.project = true;
+        break;
+      case '--agent':
+        args.agent = argv[++i];
+        break;
+      case '--update':
+        args.update = true;
+        break;
+      case '--help':
+      case '-h':
+        args.help = true;
+        break;
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+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)
+  --update             Check for updates and reinstall if version changed
+  --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 --update              # update all installed agents
+  npx @qzhuli/qzhuli-cli scripts/install-skill.mjs     # from published npm
+`);
+}
+
+// ── Main ───────────────────────────────────────────────────────────
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { printHelp(); process.exit(0); }
+
+  const sourceDir = findSourceDir();
+  if (!sourceDir) {
+    console.error('Error: Cannot find skill source directory.');
+    console.error('Run this script from the repo root, or install the npm package first.');
+    process.exit(1);
+  }
+
+  const pkgVersion = getPkgVersion();
+
+  // Resolve target agents
+  let targets = [];
+  if (opts.update) {
+    // --update: check agents that already have the skill installed
+    const candidates = opts.agent
+      ? [AGENT_PATHS.find(a => a.name === opts.agent)]
+      : AGENT_PATHS;
+
+    if (opts.agent && !candidates[0]) {
+      console.error(`Error: Unknown agent "${opts.agent}".`);
+      console.error('Supported agents:', AGENT_PATHS.map(a => a.name).join(', '));
+      process.exit(1);
+    }
+
+    for (const cfg of candidates) {
+      if (!cfg) continue;
+      const globalPath = resolveHome(cfg.global);
+      const skillTarget = join(globalPath, SKILL_NAME);
+      if (existsSync(skillTarget) && needsUpdate(skillTarget, sourceDir)) {
+        targets.push({ cfg, isProject: false });
+      }
+      if (opts.project) {
+        const projectPath = join(process.cwd(), cfg.project);
+        const projectTarget = join(projectPath, SKILL_NAME);
+        if (existsSync(projectTarget) && needsUpdate(projectTarget, sourceDir)) {
+          targets.push({ cfg, isProject: true });
+        }
+      }
+    }
+    if (targets.length === 0) {
+      console.log('All skills are up to date.');
+      return;
+    }
+  } else if (opts.agent) {
+    const cfg = AGENT_PATHS.find(a => a.name === opts.agent);
+    if (!cfg) {
+      console.error(`Error: Unknown agent "${opts.agent}".`);
+      console.error('Supported agents:', AGENT_PATHS.map(a => a.name).join(', '));
+      process.exit(1);
+    }
+    targets.push({ cfg, isProject: opts.project });
+  } else {
+    const detected = detectAgents();
+    const fallback = AGENT_PATHS.find(a => a.name === 'claude-code');
+    if (detected.length === 0) {
+      targets.push({ cfg: fallback, isProject: false });
+    } else {
+      for (const name of detected) {
+        const cfg = AGENT_PATHS.find(a => a.name === name);
+        if (cfg) targets.push({ cfg, isProject: false });
+      }
+    }
+  }
+
+  let installed = 0;
+  let skipped = 0;
+  let updated = 0;
+
+  for (const target of targets) {
+    const agentConfig = target.cfg;
+    const targetPath = target.isProject
+      ? join(process.cwd(), agentConfig.project)
+      : resolveHome(agentConfig.global);
+
+    const skillTarget = join(targetPath, SKILL_NAME);
+
+    if (!opts.update && isInstalled(skillTarget, sourceDir)) {
+      console.log(`  (skip) ${agentConfig.name}: already up to date`);
+      skipped++;
+      continue;
+    }
+
+    copyDir(sourceDir, skillTarget);
+    writeManifest(skillTarget, sourceDir, pkgVersion);
+
+    if (opts.update) {
+      const manifest = readManifest(skillTarget);
+      console.log(`  ✓ ${agentConfig.name}: updated to skill v${manifest?.skill_version || '?'}`);
+      updated++;
+    } else {
+      console.log(`  ✓ ${agentConfig.name}: ${targetPath}`);
+      installed++;
+    }
+  }
+
+  const total = installed + updated;
+  console.log(`\nInstalled: ${installed}, Updated: ${updated}, Skipped: ${skipped}`);
+  if (total === 0 && skipped === 0) {
+    console.log('No targets found. Use --agent to specify one manually.');
+  }
+}
+
+main();

package/scripts/postinstall.mjs

@@ -6,6 +6,7 @@
  * Features:
  * - Detects installed agents by checking home/project config dirs
  * - Copies the skill to each agent's skill directory (global + project)
+ * - Writes a manifest file for version tracking and future updates
  * - Skips in CI environments (CI, CONTINUOUS_INTEGRATION env vars)
  * - Skips if AX_SKIP_SKILL_INSTALL=1
  * - Silent failure — never breaks npm install
@@ -13,62 +14,14 @@
  * - Content-dedup: skips if identical file already exists
  */
 
-import {
-  existsSync,
-  readdirSync,
-  readFileSync,
-  copyFileSync,
-  mkdirSync,
-  rmSync,
-  statSync,
-} from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
+import { AGENT_PATHS, SKILL_NAME, resolveHome, copyDir, isInstalled, detectAgents, writeManifest } from './skill-agent.mjs';
 
 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' ||
@@ -84,12 +37,6 @@ function isInteractive() {
 /**
  * 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, '..');
@@ -97,28 +44,18 @@ function findProjectRoot() {
   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;
+    return false; // dev/source checkout, skip
   }
 
-  // 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
+  if (!projectRoot) return null;
 
   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;
+    if (pkg.name === '@qzhuli/qzhuli-cli') return null; // global install
   } catch {
     return null;
   }
@@ -127,47 +64,15 @@ function findProjectRoot() {
 }
 
 /**
- * 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.
+ * Get the CLI package version from the nearest package.json.
  */
-function isInstalled(skillTarget, sourceDir) {
-  if (!existsSync(skillTarget)) return false;
+function getPkgVersion() {
   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');
+    const pkgJson = resolve(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgJson, 'utf8'));
+    return pkg.version || 'unknown';
   } catch {
-    return false;
+    return 'unknown';
   }
 }
 
@@ -181,17 +86,16 @@ function install() {
     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();
+    const pkgVersion = getPkgVersion();
 
-    // 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 = [];
+    const updated = [];
 
     for (const agentName of targets) {
       const agentConfig = AGENT_PATHS.find(a => a.name === agentName);
@@ -203,23 +107,43 @@ function install() {
 
       const skillTarget = join(targetPath, SKILL_NAME);
 
-      // Skip if already installed with identical content
-      if (isInstalled(skillTarget, sourceDir)) continue;
+      // Update flow: if installed but version changed, re-copy
+      if (isInstalled(skillTarget, sourceDir)) {
+        // Still write manifest (in case it was missing)
+        writeManifest(skillTarget, sourceDir, pkgVersion);
+        continue;
+      }
+
+      // Check if existing install needs update
+      if (existsSync(skillTarget)) {
+        copyDir(sourceDir, skillTarget);
+        writeManifest(skillTarget, sourceDir, pkgVersion);
+        updated.push(agentName);
+        continue;
+      }
 
       copyDir(sourceDir, skillTarget);
+      writeManifest(skillTarget, sourceDir, pkgVersion);
       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
+    if (updated.length > 0 && isInteractive()) {
+      const noun = updated.length === 1 ? 'agent' : 'agents';
+      console.log(
+        `✓ qzhuli-cli skill updated in ${updated.length} ${noun}: ${updated.join(', ')}`
+      );
+    }
+  } catch (err) {
+    if (isInteractive()) {
+      console.warn('[qzhuli-cli] Skill installation failed:', err?.message || err);
+      console.warn('[qzhuli-cli] Manual install: node scripts/install-skill.mjs');
+    }
   }
 }
 

package/scripts/skill-agent.mjs

@@ -0,0 +1,149 @@
+/**
+ * Shared agent detection and skill installation utilities.
+ * Used by both postinstall.mjs and install-skill.mjs.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  copyFileSync,
+  mkdirSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// ── Agent path mapping ─────────────────────────────────────────────
+// Source: https://www.agentskills.in/docs/getting-started
+export 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' },
+];
+
+export const SKILL_NAME = 'qzhuli-cli';
+export const MANIFEST_FILE = '.qzhuli-manifest.json';
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+export function resolveHome(p) {
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  return p;
+}
+
+export function dirExists(p) {
+  try {
+    return statSync(resolveHome(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function copyDir(src, dest) {
+  mkdirSync(dest, { recursive: true });
+
+  // Remove stale files from dest that no longer exist in source
+  const srcNames = new Set(readdirSync(src).map(e => e));
+  if (existsSync(dest)) {
+    for (const name of readdirSync(dest)) {
+      if (!srcNames.has(name)) {
+        rmSync(join(dest, name), { recursive: true, force: true });
+      }
+    }
+  }
+
+  // Copy source to dest
+  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 if (entry.isSymbolicLink()) {
+      continue;
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+export function isInstalled(skillTarget, sourceDir) {
+  if (!existsSync(skillTarget)) return false;
+  try {
+    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;
+  }
+}
+
+export function detectAgents() {
+  return AGENT_PATHS
+    .filter(agent => dirExists(agent.global))
+    .map(agent => agent.name);
+}
+
+// ── Manifest tracking ──────────────────────────────────────────────
+
+export function writeManifest(skillTarget, sourceDir, pkgVersion) {
+  const manifestPath = join(skillTarget, MANIFEST_FILE);
+  const files = readdirSync(sourceDir, { withFileTypes: true })
+    .filter(e => !e.isDirectory())
+    .map(e => e.name);
+  const manifest = {
+    source: `@qzhuli/qzhuli-cli@${pkgVersion || 'unknown'}`,
+    installed_at: new Date().toISOString(),
+    skill_version: readSkillVersion(sourceDir),
+    files,
+  };
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+}
+
+export function readManifest(skillTarget) {
+  const manifestPath = join(skillTarget, MANIFEST_FILE);
+  if (!existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function needsUpdate(skillTarget, sourceDir) {
+  const manifest = readManifest(skillTarget);
+  if (!manifest) return true;
+  const currentVersion = readSkillVersion(sourceDir);
+  return manifest.skill_version !== currentVersion;
+}
+
+function readSkillVersion(sourceDir) {
+  const skillMd = join(sourceDir, 'SKILL.md');
+  if (!existsSync(skillMd)) return 'unknown';
+  try {
+    const content = readFileSync(skillMd, 'utf8');
+    const match = content.match(/^version:\s*(.+)$/m);
+    return match ? match[1].trim() : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}

package/skills/qzhuli-cli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: qzhuli-cli
-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
+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
 ---
 
 # QZhuli CLI
 
-Use this skill as a concise operating manual for the `qz` command.
+Concise operating manual for the `qz` command.
 
 ## First Checks
 
@@ -22,60 +22,96 @@ Use this skill as a concise operating manual for the `qz` command.
    ```bash
    qz --help
    qz <command> --help
-   qz <command> <subcommand> --help
    ```
 
-## Environment and Config Files
+## Safety Rules
 
-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.
+**These rules prevent data loss and unwanted side effects. Follow them strictly.**
 
-| Visible behavior  | Environment | Config directory |
-|-------------------|-------------|------------------|
-| Shows test banner | test        | `./.qzhuli-cli/` |
-| No test banner    | production  | `~/.qzhuli-cli/` |
+### Ask Before Acting
 
-Treat `credentials.json` as secret. Preferences live in `preferences.json`.
+When ANY of the following applies, STOP and ask the user first:
 
-## Output and Global Options
+- **Ambiguous search results**: `user search` returns multiple candidates or `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
+  with user.
 
-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 --dry-run for Preview
 
-Use `--jq` for simple dot-path filtering:
+Before any write operation the user hasn't explicitly confirmed, run with `--dry-run` first:
 
 ```bash
-qz --jq ".data.uid" auth status
-qz --jq ".data.links" friend list
-qz --jq ".data" conversation list --limit 5 --offset 0
+qz --dry-run message send <id> <cid> "hello"
+qz --dry-run relation set <uid> --remark "New Name"
 ```
 
-`--jq` is not full jq. Prefer simple paths such as `.data`, `.data.uid`, `.data.links`.
+### 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
 
-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.
+The CLI uses 5 distinct ID types. **Using the wrong type will fail silently or hit the wrong target.**
 
-## Cache Architecture
+| 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`                                                                                    |
 
-All read operations use a **Repository Pattern** with SQLite-backed caching:
+**Quick identification by format**:
 
-- **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
+- A short integer → Q助号
+- A 32-char hex string → UID
+- A UUID with dashes → CID
+- A long Base64-like string → conversationId
 
-Cache database tables:
+**Common mistake**: Using UID for `message send` instead of conversationId. Always resolve via `conversation search` or
+`conversation list` first.
+
+## Environment and Config Files
+
+| Visible behavior                                               | Environment | Config directory                   |
+|----------------------------------------------------------------|-------------|------------------------------------|
+| Shows `DEVELOPMENT BUILD / Running in TEST environment` banner | test        | `./.qzhuli-cli/` (relative to CWD) |
+| No test banner                                                 | production  | `~/.qzhuli-cli/`                   |
+
+Treat `credentials.json` as secret. Preferences live in `preferences.json`.
+
+## Output and Global Options
 
-- `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
+Commands return JSON with `status`, `code`, `message`, and `data`.
 
-Write operations (send message, create conversation, update relation) bypass the cache and write directly to the API,
-then invalidate relevant cache entries.
+| status               | Meaning                             | Exit code |
+|----------------------|-------------------------------------|-----------|
+| `"success"`          | Operation completed                 | 0         |
+| `"needs_resolution"` | Ambiguous result (multiple matches) | 0         |
+| `"error"`            | Failed operation                    | 1         |
+
+**Always check `status`, not just exit code.**
+
+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: `.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
 
@@ -101,94 +137,54 @@ then invalidate relevant cache entries.
 | 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>]`                                                             |
+| 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`.
+Relation type values: `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>
-   ```
+1. `qz friend list` — list candidates
+2. `qz friend profile "<nickname>"` — resolve ambiguous names
+3. `qz relation get <uid>` — inspect relation with resolved 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>
-   ```
+1. Resolve the exact `uid` with `friend list` or `friend profile`.
+2. Show current value to user, confirm the change.
+3. Execute: `qz relation set <uid> --remark "New Name" --type 1`
+4. Verify: `qz relation get <uid>`
 
-Do not run `relation set` without `--remark` or `--type`; the CLI returns `INVALID_ARGUMENT`.
+**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
-   ```
+1. Search: `qz user search 10000`
+2. Show profile to user, confirm.
+3. Add: `qz user add 10000` (internally: search → create conversation)
 
 ### Find All Conversations with a User
 
-Search by Q助号 (default):
-
-```bash
-qz conversation search 10000
-```
-
-Search by UID:
-
 ```bash
-qz conversation search 79345121120f6e5288238749 --uid
+qz conversation search 10000                           # by Q助号 (default)
+qz conversation search d5b6308e3abad6bc96573c58 --uid  # by 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`.
+Response includes `id` (Q助号), `uid` (internal user ID), and `conversations` with full profile data. Each conversation
+entry contains `conversationId`, `isGroup`, `users`, and `visitors`.
 
 ### 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
-   ```
+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`
 
 ### Page Through Message History
 
@@ -206,15 +202,29 @@ 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`.
+
 ## 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`. |
-| 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).           |
+| 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`                                                           |