@zhizai/cli 0.0.6 → 0.0.8

package/README.md

@@ -82,12 +82,17 @@ zhizai note get <id> --field summary
 
 ### 4. 接入本机 AI
 
+CLI 首次安装请用 npm（见上文「安装」）。`setup` 负责同步 Skills 与授权，**不会**在 CLI 已可用时重复 npm 重装。
+
 ```bash
 # 预览将执行的操作
 zhizai setup --dry-run -o json
 
-# 正式安装 Skill
+# 同步 Skill 并引导授权（CLI 已就绪时跳过重装）
 zhizai setup
+
+# 升级或修复 CLI 二进制（显式触发 npm 重装）
+zhizai setup --force-cli-install
 ```
 
 `setup` 会把原子 Skill 安装到 Cursor、Claude Code、Codex 等本机 AI 环境，并引导完成授权。
@@ -116,7 +121,7 @@ zhizai setup
 | `zhizai knowledge list [--received]` | 笔记集列表（我创建的 / 收到的） |
 | `zhizai knowledge get <id>` | 笔记集详情 |
 | `zhizai knowledge notes <id>` | 笔记集内笔记 |
-| `zhizai setup [--dry-run]` | 为本机 AI 安装原子 Skill 并引导授权 |
+| `zhizai setup [--dry-run] [--force-cli-install]` | 同步原子 Skill 并引导授权；CLI 已就绪时跳过重装 |
 
 ### 规划中
 

package/bin/zhizai.js

@@ -4,6 +4,7 @@
 'use strict';
 
 const { spawn } = require('child_process');
+const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
@@ -11,9 +12,29 @@ const platform = os.platform();
 const binaryName = platform === 'win32' ? 'zhizai.exe' : 'zhizai';
 const binaryPath = path.join(__dirname, binaryName);
 
+function failMissing() {
+  console.error('无法启动智在记录：CLI 可执行文件缺失。');
+  console.error('可能原因：安装中断或文件被移除。');
+  console.error('请重新执行: npm install -g @zhizai/cli@latest');
+  console.error('错误码：CLI_BINARY_MISSING');
+  process.exit(1);
+}
+
+if (!fs.existsSync(binaryPath)) {
+  failMissing();
+}
+
 const child = spawn(binaryPath, process.argv.slice(2), {
   stdio: 'inherit',
-  windowsHide: true
+  windowsHide: true,
+});
+
+child.on('error', (err) => {
+  if (err && err.code === 'ENOENT') {
+    failMissing();
+  }
+  console.error('无法启动智在记录：', err.message);
+  process.exit(1);
 });
 
 child.on('exit', (code, signal) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhizai/cli",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "CLI tool for 智在记录 — manage notes and knowledge from the terminal and AI agents",
   "keywords": [
     "zhizai",

package/scripts/postinstall.js

@@ -6,6 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const http = require('http');
 const https = require('https');
 const crypto = require('crypto');
 const { spawnSync } = require('child_process');
@@ -14,6 +15,34 @@ const pkg = require('../package.json');
 const VERSION = pkg.version;
 const REPO = 'BoteAI/zhizai-cli';
 
+const DEFAULT_CONNECT_TIMEOUT_MS = 15000;
+const DEFAULT_IDLE_TIMEOUT_MS = 30000;
+const DEFAULT_TOTAL_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_RETRIES = 3;
+const RETRY_BACKOFF_MS = [500, 1000, 2000];
+const NON_RETRYABLE_STATUS = new Set([401, 403, 404]);
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function getProtocolModule(urlString) {
+  const protocol = new URL(urlString).protocol;
+  if (protocol === 'http:') return http;
+  if (protocol === 'https:') return https;
+  throw new Error(`Unsupported protocol: ${protocol}`);
+}
+
+function versionMatches(out, expected) {
+  const m = String(out).trim().match(/^zhizai version\s+v?(\S+)/i);
+  if (!m) return false;
+  return m[1] === String(expected).replace(/^v/, '');
+}
+
+function parseVersionFromOutput(out, expectedVersion) {
+  return versionMatches(out, expectedVersion);
+}
+
 function getPlatform() {
   const platform = os.platform();
   const arch = os.arch();
@@ -47,6 +76,209 @@ function getWindowsExtractArgs(archivePath, destinationPath) {
   ];
 }
 
+function unlinkQuiet(filePath) {
+  try { fs.unlinkSync(filePath); } catch (_) {}
+}
+
+function reportProgress(downloaded, contentLength, onProgress) {
+  if (contentLength != null) {
+    console.error(`Downloaded ${downloaded}/${contentLength} bytes`);
+  } else {
+    console.error(`Downloaded ${downloaded} bytes`);
+  }
+  if (onProgress) onProgress({ downloaded, contentLength });
+}
+
+function isNonRetryableError(err) {
+  const statusCode = err && err.statusCode;
+  if (statusCode != null && NON_RETRYABLE_STATUS.has(statusCode)) return true;
+  const message = String((err && err.message) || err);
+  return /HTTP (401|403|404)/.test(message);
+}
+
+function downloadOnce(url, destination, options, redirects = 0) {
+  if (redirects > 5) return Promise.reject(new Error('Too many redirects'));
+
+  const {
+    connectTimeoutMs,
+    idleTimeoutMs,
+    totalTimeoutMs,
+    onProgress,
+  } = options;
+
+  return new Promise((resolve, reject) => {
+    let request = null;
+    let response = null;
+    let output = null;
+    let connected = false;
+    let downloaded = 0;
+    let contentLength = null;
+    let lastProgressTime = 0;
+    let idleTimer = null;
+    let totalTimer = null;
+    let connectTimer = null;
+    let settled = false;
+
+    function finish(err, value) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(idleTimer);
+      clearTimeout(totalTimer);
+      clearTimeout(connectTimer);
+      if (err) reject(err);
+      else resolve(value);
+    }
+
+    function cleanupPartial() {
+      unlinkQuiet(destination);
+    }
+
+    function destroyStreams() {
+      if (response) {
+        try { response.destroy(); } catch (_) {}
+      }
+      if (request) {
+        try { request.destroy(); } catch (_) {}
+      }
+      if (output) {
+        try { output.destroy(); } catch (_) {}
+      }
+    }
+
+    function failTimeout(stage) {
+      destroyStreams();
+      cleanupPartial();
+      finish(new Error(`${stage} timeout`));
+    }
+
+    function resetIdleTimer() {
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => failTimeout('Idle'), idleTimeoutMs);
+    }
+
+    function maybeReportProgress(force = false) {
+      const now = Date.now();
+      if (!force && now - lastProgressTime < 500) return;
+      lastProgressTime = now;
+      reportProgress(downloaded, contentLength, onProgress);
+    }
+
+    totalTimer = setTimeout(() => failTimeout('Total'), totalTimeoutMs);
+
+    const protocol = getProtocolModule(url);
+    request = protocol.get(url, { headers: { 'User-Agent': '@zhizai/cli installer' } }, res => {
+      connected = true;
+      clearTimeout(connectTimer);
+      response = res;
+
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        destroyStreams();
+        clearTimeout(idleTimer);
+        clearTimeout(totalTimer);
+        clearTimeout(connectTimer);
+        settled = true;
+        downloadOnce(new URL(res.headers.location, url).toString(), destination, options, redirects + 1)
+          .then(resolve, reject);
+        return;
+      }
+
+      if (res.statusCode !== 200) {
+        res.resume();
+        destroyStreams();
+        cleanupPartial();
+        const err = new Error(`HTTP ${res.statusCode}: ${url}`);
+        err.statusCode = res.statusCode;
+        finish(err);
+        return;
+      }
+
+      const lengthHeader = res.headers['content-length'];
+      if (lengthHeader != null && lengthHeader !== '') {
+        const parsed = Number(lengthHeader);
+        if (!Number.isNaN(parsed)) contentLength = parsed;
+      }
+
+      output = fs.createWriteStream(destination, { mode: 0o600 });
+      resetIdleTimer();
+
+      res.on('data', chunk => {
+        downloaded += chunk.length;
+        resetIdleTimer();
+        maybeReportProgress();
+      });
+
+      res.pipe(output);
+
+      output.on('finish', () => {
+        output.close(() => {
+          maybeReportProgress(true);
+          finish(null, undefined);
+        });
+      });
+
+      output.on('error', err => {
+        destroyStreams();
+        cleanupPartial();
+        finish(err);
+      });
+
+      res.on('error', err => {
+        destroyStreams();
+        cleanupPartial();
+        finish(err);
+      });
+    });
+
+    connectTimer = setTimeout(() => {
+      if (!connected) failTimeout('Connect');
+    }, connectTimeoutMs);
+
+    request.on('socket', socket => {
+      socket.once('connect', () => {
+        connected = true;
+        clearTimeout(connectTimer);
+        resetIdleTimer();
+      });
+    });
+
+    request.on('error', err => {
+      destroyStreams();
+      cleanupPartial();
+      finish(err);
+    });
+  });
+}
+
+async function download(url, destination, options = {}, redirects = 0) {
+  const opts = {
+    connectTimeoutMs: DEFAULT_CONNECT_TIMEOUT_MS,
+    idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
+    totalTimeoutMs: DEFAULT_TOTAL_TIMEOUT_MS,
+    retries: DEFAULT_RETRIES,
+    onProgress: null,
+    ...options,
+  };
+
+  if (redirects > 5) throw new Error('Too many redirects');
+
+  const maxRetries = opts.retries;
+  let lastError;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+    try {
+      return await downloadOnce(url, destination, opts, redirects);
+    } catch (err) {
+      lastError = err;
+      if (isNonRetryableError(err) || attempt >= maxRetries) throw err;
+      const delay = RETRY_BACKOFF_MS[Math.min(attempt, RETRY_BACKOFF_MS.length - 1)];
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
 async function installArchive({ platform, binDir, binaryName, binaryPath, url, tmpFile }) {
   try {
     await download(url, tmpFile);
@@ -60,13 +292,12 @@ async function installArchive({ platform, binDir, binaryName, binaryPath, url, t
     if (!fs.existsSync(binaryPath)) {
       throw new Error(`Binary missing after extract: ${binaryPath}`);
     }
-    // chmod is meaningful on Unix; Windows may not need it.
     if (platform.platform !== 'windows') {
       fs.chmodSync(binaryPath, 0o755);
     }
     console.log(`zhizai installed at ${binaryPath}`);
   } finally {
-    try { fs.unlinkSync(tmpFile); } catch (_) {}
+    unlinkQuiet(tmpFile);
   }
 }
 
@@ -76,7 +307,6 @@ async function main() {
   const binaryName = getBinaryName(platform);
   const binaryPath = path.join(binDir, binaryName);
   const url = getDownloadURL(platform);
-  // Expand-Archive on Windows requires a .zip extension; tar.gz similarly.
   const archiveExt = platform.platform === 'windows' ? '.zip' : '.tar.gz';
   const tmpFile = path.join(os.tmpdir(), `zhizai-download-${Date.now()}${archiveExt}`);
 
@@ -84,7 +314,7 @@ async function main() {
     try {
       const result = spawnSync(binaryPath, ['version'], { encoding: 'utf8' });
       const out = (result.stdout || '').trim();
-      if (result.status === 0 && out.includes(VERSION)) {
+      if (result.status === 0 && versionMatches(out, VERSION)) {
         console.log(`zhizai v${VERSION} already installed, skipping download.`);
         return;
       }
@@ -104,27 +334,6 @@ function run(command, args) {
   if (result.status !== 0) throw new Error(`${command} exited with status ${result.status}`);
 }
 
-function download(url, destination, redirects = 0) {
-  if (redirects > 5) return Promise.reject(new Error('Too many redirects'));
-  return new Promise((resolve, reject) => {
-    const request = https.get(url, { headers: { 'User-Agent': '@zhizai/cli installer' } }, response => {
-      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-        response.resume();
-        return resolve(download(new URL(response.headers.location, url).toString(), destination, redirects + 1));
-      }
-      if (response.statusCode !== 200) {
-        response.resume();
-        return reject(new Error(`HTTP ${response.statusCode}: ${url}`));
-      }
-      const output = fs.createWriteStream(destination, { mode: 0o600 });
-      response.pipe(output);
-      output.on('finish', () => output.close(resolve));
-      output.on('error', reject);
-    });
-    request.on('error', reject);
-  });
-}
-
 async function verifyChecksum(assetURL, assetName, archivePath) {
   const checksumPath = `${archivePath}.checksums`;
   try {
@@ -139,10 +348,22 @@ async function verifyChecksum(assetURL, assetName, archivePath) {
     const actual = crypto.createHash('sha256').update(fs.readFileSync(archivePath)).digest('hex');
     if (actual !== expected) throw new Error(`Checksum mismatch for ${assetName}`);
   } finally {
-    try { fs.unlinkSync(checksumPath); } catch (_) {}
+    unlinkQuiet(checksumPath);
   }
 }
 
+module.exports = {
+  download,
+  downloadOnce,
+  versionMatches,
+  parseVersionFromOutput,
+  getPlatform,
+  getBinaryName,
+  getDownloadURL,
+  verifyChecksum,
+  installArchive,
+};
+
 if (require.main === module) {
   main().catch(err => {
     console.error('Failed to install zhizai:', err.message);

package/skills/zhizai-ask/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: zhizai-ask
+version: 1.0.0
+description: |
+  用 zhizai CLI 问小智语义问答（ask）：在全部笔记或指定笔记集/目录/笔记范围内提问、追问、带参考文档；动态模版成文（写周报/复盘）；对一段文字流式总结（summarize）；按标题时间查总结和录音（recordings，人资）。
+  用户说找找关于、在某某笔记集里问、待办有哪些、追问、写周报、按模版总结本周会议、给这段话出个总结、查这个月经营会的总结和录音时使用。
+  列表过滤（最近有哪些 / 标题带…）走 zhizai-note 的 notes；禁止用 notes --title 冒充语义搜索。
+---
+
+# 问小智与成文（ask / summarize / recordings）
+
+机器调用加 `-o json`。雪花 ID 当字符串。语义搜索只走 `ask`。
+
+## ask 执行约定
+
+- `zhizai ask "问题" -o json`：对外一次闭环，**默认自动建会话**再流式问答；返回 `chatId` / `contextId` 供追问。
+- 追问：已有 `chatId` 时 `zhizai ask "…" --chat-id <id> --context-id <id>`，不必再建会话；建议带同一批范围 ID。
+- 负向：`--no-session` 且未提供 `--chat-id` 时失败「请先创建问小智会话」，不要偷偷建会话。
+- 空问题：本地失败，不调命令。
+- 范围内无内容（空笔记集/空目录）：如实返回错误原文，不编造检索结果。
+
+## 限定范围（名称必须先查 ID）
+
+范围优先级：目录 > 笔记集 > 笔记 > 个人全部笔记。`--dir` 需同时带所属 `--kb`。
+
+| 用户说法 | 顺序 |
+|---|---|
+| 找找关于支付的笔记（不限范围） | 单步：`zhizai ask "找找关于支付的笔记" -o json`（自动建会话） |
+| 在工作笔记集里问… | ① `zhizai kb list` 匹配得 `knowledgeId` ② `zhizai ask "…" --kb <knowledgeId> -o json` |
+| 只问某目录 | ① `kb list` 得 `knowledgeId` ② `kb catalog --kb <id>` 匹配得 `directoryId` ③ `ask "…" --kb <knowledgeId> --dir <directoryId>`（检索该目录及子目录） |
+| 就那条某某纪要，待办有哪些 | ① `notes --title …` 得 `noteId`（会话已有则跳过）② `ask "待办有哪些" --note <noteId>` |
+| 这几条一起问 | 每条先查真实 ID，再 `ask "…" --note <id1> --note <id2>`（或 `--note-ids <id1,id2>` / 多个 `--kb`） |
+| 带参考文档 | `ask "…" --with-references`；引用详情用 `zhizai ask refs --doc-ids 1,2 --context-id <id>` |
+
+查不到名称则停；禁止把名称当 `--kb` / `--dir` / `--note`。需要显式分步时：`ask session [--kb/--dir/--note]` 先建会话，再 `ask chat "…" --chat-id <id> --context-id <id>`。
+
+## 动态模版成文（写周报 / 复盘）
+
+「按周报结构总结本周会议」走模版管线，**不是问小智，也不是某条笔记的 summary**：
+
+1. `zhizai ask template "生成周报" --with-notes --start "2026-09-21 00:00:00" --end "2026-09-27 23:59:59" -o json`
+2. CLI 只返回模版与笔记 JSON，**不调用 LLM 成文**；由你按模版结构填真实笔记。
+3. 模版要求但笔记里没有的字段标「未提及」，禁止编造。
+
+## summarize（文字流式总结）
+
+用户给了一段文字要总结（不是某条笔记、不是问答）：
+
+- `zhizai summarize --content "…" -o json`；点名场景时先查真实 `sceneId`（见 zhizai-scene）再加 `--scene-id`。
+- 流式输出结束即完成。
+
+## recordings（人资查询）
+
+「查这个月经营会的总结和录音」：
+
+- `zhizai recordings --title 经营 --start "2026-09-01 00:00:00" --end "2026-09-30 23:59:59" -o json`（`--from` / `--to` 为别名）。
+- 返回笔记列表；用户要打开某一条时再 `note get <id>`（变成组合，见 zhizai-note）。

package/skills/zhizai-auth/SKILL.md

@@ -1,23 +1,29 @@
 ---
 name: zhizai-auth
-version: 1.0.0
+version: 1.0.1
 description: 安装和连接智在记录，完成网页授权登录、环境诊断与 CLI 升级。用户说安装、连接、登录、检查为什么不能用时使用。
 ---
 
 # 智在记录连接与诊断
 
-通过官方 `zhizai` CLI 完成真实操作。机器调用优先使用 `-o json`。
+通过官方 `zhizai` CLI 完成真实操作。机器调用优先使用 `-o json`。登录后的业务操作（笔记/笔记集/场景/问小智）分别走 zhizai-note、zhizai-knowledge、zhizai-scene、zhizai-ask。
+
+**安装与升级：** 首次安装 CLI 用 `npm install -g @zhizai/cli@latest`。`zhizai setup` 默认同步 Skills 并引导授权；CLI 已可用时**不会**重复 npm 重装。需要升级或修复二进制时用 `zhizai setup --force-cli-install`。
 
 ## 路由
 
 | 意图 | 命令 |
 |---|---|
+| 首次安装 CLI | `npm install -g @zhizai/cli@latest` |
 | 登录 | `zhizai auth login` |
 | 无头/连接器登录 | `zhizai auth login --no-open` |
 | 查看状态 | `zhizai auth status` |
 | 退出 | `zhizai auth logout` |
 | 诊断 | `zhizai doctor -o json` |
 | 能力契约 | `zhizai capabilities -o json` |
-| 安装 Skill | `zhizai setup` |
+| 同步 Skill / 授权 | `zhizai setup` |
+| 升级或修复 CLI | `zhizai setup --force-cli-install` |
 
 默认使用网页设备授权。`--no-open` 时不打开浏览器，打印 `[verify_url]` / `[device_code]` / `[expires_in]` / `[interval]` 供宿主展示，后台继续轮询。仅当网页授权失败时，再提示用户使用 `zhizai auth login --api-key <key>`。
+
+未登录/未配置时：只提示登录或配置，不调业务命令；不要回显完整 Key。`zhizai doctor` 可探活连通性。

package/skills/zhizai-knowledge/SKILL.md

@@ -1,17 +1,43 @@
 ---
 name: zhizai-knowledge
-version: 1.0.0
-description: 查询和管理智在记录笔记集。
+version: 2.0.0
+description: |
+  用 zhizai CLI 管理笔记集（knowledge，别名 kb）：列出我创建的/收到的笔记集、打开笔记集与目录、新建笔记集、建目录、把笔记移入目录、删目录。
+  用户说我的笔记集、我收到的笔记集、打开某某笔记集、新建笔记集、建目录、把这条笔记放到某某笔记集、删掉目录时使用。
+  名称必须先查 ID 再操作；保存时归档（save --kb）见 zhizai-note。
 ---
 
-# 智在记录笔记集
+# 智在记录笔记集（kb）
 
-| 意图 | 命令 |
-|---|---|
-| 我创建的笔记集 | `zhizai knowledge list -o json` |
-| 我收到的笔记集 | `zhizai knowledge list --received -o json` |
-| 笔记集详情 | `zhizai knowledge get <id> -o json` |
-| 集内笔记 | `zhizai knowledge notes <id> -o json` |
-| 新建笔记集 | `zhizai knowledge create --name <名称>`（后端待开放） |
+`knowledge` 别名 `kb`，以下统一写 `kb`。机器调用加 `-o json`。雪花 ID 当字符串。
 
-字段说明见 `skills/zhizai-open-platform/references/knowledge.md`。
+## 名称 → ID（写操作前必须完成）
+
+| 用户说的 | 先执行 | 得到 |
+|---|---|---|
+| 笔记集名称 | `zhizai kb list -o json`（别人分享的再 `kb shared`），按名称匹配 | `knowledgeId` |
+| 目录名称 | 先有 `knowledgeId`，再 `zhizai kb catalog --kb <knowledgeId> -o json`，按目录名匹配 | `directoryId`（即 `catalogId`） |
+
+零条停、多条让用户选。禁止把名称当 ID、禁止编造 ID。会话里本轮已拿到的 ID 可直接用。
+
+## 命令与组合
+
+| 用户说法 | 执行 | 顺序 |
+|---|---|---|
+| 我的笔记集 | 单步 | `zhizai kb list -o json`。空列表是成功 |
+| 我收到的笔记集 | 单步 | `zhizai kb shared -o json`（等价 `kb list --received`） |
+| 打开某某笔记集 | 组合 2 步 | ① `kb list` 匹配名称 ② `zhizai kb get <knowledgeId>` 或 `kb notes <knowledgeId>` |
+| 看某目录里的笔记 | 组合 3 步 | ① `kb list` ② `kb catalog --kb <id>` 匹配目录 ③ `kb notes <id> --dir <directoryId>` |
+| 新建笔记集 | 单步 | `zhizai kb create --name "工作笔记集" [--detail "…"]`，返回新 `knowledgeId` |
+| 建目录 | 组合 2 步 | ① `kb list` 匹配笔记集 ② `zhizai kb mkdir --kb <knowledgeId> --name "三季度会议" [--parent <父目录Id>]`；不传 `--parent` 或传 `-1` 表示根层。父目录也是名称时先 `kb catalog` 匹配 |
+| 移笔记到目录 | 组合 3～4 步 | ① 查 `noteId`（会话没有则 `notes --title`）② `kb list` 得 `knowledgeId` ③ 点目录则 `kb catalog` 得 `directoryId` ④ `zhizai kb add --kb <knowledgeId> --note-id <noteId> [--dir <directoryId>]` |
+| 批量移笔记 | 组合 3～4 步 | 每条笔记都先查到真实 `noteId`，再一次 `kb add --kb <id> --note-ids <id1,id2> [--dir …]`；指定目录时只能对着一个笔记集 |
+| 移到笔记集根层 | 组合 2～3 步 | ① 查 `noteId` ② 查 `knowledgeId` ③ `kb add --kb <knowledgeId> --note-id <noteId>`（不传 `--dir`） |
+| 删目录 | 组合 2～3 步 | ① 不知在哪个集则 `kb list` 再 `kb catalog --kb <id>` 匹配目录 ② 用户确认 ③ `zhizai kb rmdir <directoryId> --yes` |
+
+## 边界
+
+- `kb add`：未入集则新增关联；已在集内则改目录；不删笔记正文。已在目标目录可能失败「没有需要添加的笔记」。
+- `kb rmdir`：必须 `--yes`；级联去掉子目录与笔记**关联**，不删笔记正文。未确认不删。
+- 目录不存在、父目录无效：如实报「目录不存在」类错误，不假装已建/已删。
+- 保存时归档用 `save --kb [--dir]`（见 zhizai-note）；`--kb` 无效时笔记可能已创建但未归档，须拆开说「已创建但未归档」。

package/skills/zhizai-msg/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: zhizai-msg
-version: 1.0.0
-description: 发送消息与查询录音卡使用情况。
+version: 1.0.1
+description: 发送消息与查询录音卡使用情况。注意：本次 CLI 场景测试不包含消息/录音卡能力，命令保留占位。
 ---
 
 # 智在记录消息与录音卡
 
+> **范围说明：本次场景测试不包含团队/消息/录音卡用例。** 以下命令保留占位，场景测试中勿用；发消息前须确认，展示手机号须脱敏。
+
 | 意图 | 命令 |
 |---|---|
 | 消息与录音卡 | `zhizai msg -o json` |

package/skills/zhizai-note/SKILL.md

@@ -1,33 +1,112 @@
 ---
 name: zhizai-note
-version: 1.0.0
-description: 使用智在记录 CLI 查询、创建（文字）、更新和删除笔记，并查看处理进度。
+version: 2.0.0
+description: |
+  用 zhizai CLI 做笔记：把录音/文档/图片/链接/文字做成笔记（save 自动判型）、只上传文件、列表过滤、打开详情/纪要/原文、改标题/摘要/总结、删除、等处理完成、下载音频。
+  用户说做成笔记、记一条、收藏链接、上传文件、最近有哪些、打开这条、只要转写/纪要、改标题、删掉、等它处理完、下载音频时使用。
+  语义搜索「找找关于…」走 zhizai-ask；笔记集归档走 zhizai-knowledge；场景名查 ID 走 zhizai-scene。
 ---
 
-# 智在记录笔记
+# 智在记录笔记（save / file / notes / note）
 
-通过官方 `zhizai` CLI 完成真实操作。参数与字段说明见仓库内 `skills/zhizai-open-platform/references/note.md`。
+只通过 `zhizai` CLI 操作，禁止直调开放 API。机器调用一律加 `-o json`。雪花 ID 全程当字符串传递。
 
-## 已可用
+## 执行约定（必须先读）
 
-| 意图 | 命令 |
+| 标记 | 怎么做 |
+|---|---|
+| 单步 | 一条 CLI 闭环（如 `notes`、`file upload`）。 |
+| 单步（内部多接口） | 对外仍一条 `save`：内部上传+创建，`--wait` 再轮询。**不要**拆成 `file upload` + 创建 + `note wait` 三步。 |
+| 组合 N 步 | 必须按 ①②③ 做完，缺一步即错；中途失败即停，不跳步、不猜 ID。 |
+| 附加参数 | 不能单独执行，必须并进同一条 `save`。 |
+
+**会话里已有的 ID 才能跳过查询。** 用户只说名称/标题而会话没有对应 ID，必须先查。禁止把名称当 ID，禁止编造雪花 ID。
+
+名称 → ID：
+
+| 用户说的 | 先执行 | 得到 |
+|---|---|---|
+| 笔记 / 「这条纪要」/ 标题 | `zhizai notes --title … -o json`，零条停、多条让用户选 | `noteId` |
+| 笔记集名称 | `zhizai kb list`（别人分享的再 `kb shared`），按名称匹配 | `knowledgeId`（见 zhizai-knowledge） |
+| 目录名称 | 先有 `knowledgeId`，再 `zhizai kb catalog --kb <id>` 按名称匹配 | `directoryId` |
+| 总结场景名称 | `zhizai scene list` 或 `scene builtins`，按名称匹配 | `sceneId`（见 zhizai-scene） |
+
+创建成功 ≠ 转写/总结完成。`save` 成功最低标准是非空 `noteId`；只有 `completed`（或用户明确说不用等）才能宣称完成。
+
+## 意图分流（不要混用）
+
+| 用户说法 | 走哪条 | 不要走 |
+|---|---|---|
+| 最近有哪些 / 我的录音 / 标题带经营分析 / 这个月的 | `notes` 列表过滤 | ask（列表过滤不是语义搜索） |
+| 找找关于… / 待办有哪些（语义问答） | **zhizai-ask** 的 `ask` | 用 `notes --title` 冒充语义搜索 |
+| 做成笔记 / 记一条 / 收藏链接 / 把文件生成笔记 | `save` 一条闭环 | 只 `file upload` 就停；追问「这是录音还是文档」 |
+| 只上传、不做成笔记 | `file upload` | `save` |
+| 打开这条 / 看纪要 / 只要原文 | 无 ID 先 `notes --title` 选定，再 `note get` | 把 summary 当原文 |
+| 改标题/摘要/总结、删除、下载音频 | 无 ID 先查，再 `note update/delete/audio` | 没有 `noteId` 就调用 |
+| 等它处理完 | `note wait`，仅 `completed` 后再 `note get` | 失败自动再 `save` |
+| 给这段话出个总结（用户给了文字） | `zhizai summarize`（见 zhizai-ask） | ask；某条笔记的 `--field summary` |
+
+## save 判型（用户没点名类型时必须用这套，不要追问）
+
+| 用户给了什么 | 判定 | 命令 |
+|---|---|---|
+| 音频 mp3/wav/m4a/aac/ogg/flac/amr/opus | 录音 | `save <file> --wait`；途径默认 offlineImport，不要追问 |
+| 图片 jpg/jpeg/png/gif/webp/bmp/heic | 图片 | 多图合成一条：`save a.jpg b.png --wait` |
+| 文档 pdf/doc/docx/ppt/pptx/xls/xlsx/txt/md | 文档 | `save <file> --wait`；`--title` 优先于文件名 |
+| `http(s)://` URL | 链接 | `save <url>` |
+| 只有文字 | 文字 | `save --title … --content …`；长文用 `--content-file` / `--stdin` |
+| 一份音频 + 若干图片且说「附图/一起保存」 | 录音带附图 | `save a.mp3 --image p1.jpg --image p2.png --wait` |
+| 视频 mp4/mov/avi/mkv/webm/m4v | **不能做成笔记** | 停并说明；用户只要「上传」则 `file upload`。禁止当成录音 |
+| 无法识别的扩展名 | 不创建 | 列出可支持格式（录音/文档/图片/链接/文字），不猜测 |
+
+录音/图片/文档默认 `--wait`（已默认开启）；用户说不用等则 `--no-wait`，立即返回 `noteId` 与 `note_state`，之后要结果再 `note wait`。
+
+## save 附加参数（并进同一条 save，不单独执行）
+
+| 用户说法 | 加进同一条 save |
 |---|---|
-| 笔记列表 | `zhizai notes -o json` |
-| 笔记详情 | `zhizai note get <id> -o json` |
-| 创建文字笔记 | `zhizai note create --title <标题> --content <正文> -o json` |
-| 更新笔记 | `zhizai note update <id> --title/--abstract/--summary -o json` |
-| 删除笔记 | `zhizai note delete <id> --yes -o json` |
-| 处理进度 | `zhizai note status <id> -o json` |
+| 从 14:00 录到 14:30，时长 30 分钟 | `--start "2026-09-18 14:00:00" --end "2026-09-18 14:30:00" --duration 1800`（**录制**时间，不是会议排期） |
+| 手机内录 / 实时录音 / 录音卡 | `--source phoneInternal\|realtime\|recordingCard`（仅用户明确指定才传，默认 offlineImport） |
+| 定位在广州 | `--lat 23.1291 --lng 113.2644` |
+| 再记一句备注 | `--text "会后跟进渠道下沉"`（随手备注，不等于 AI 总结） |
+| 图片备注 | `--remark "白板"` |
+| 已有 fileId 跳过上传 | `--file-id <fileId>`（单文件类型） |
+| 用某某场景 | 先查 `sceneId`，再加 `--scene-id <id>` |
+| 放到某笔记集/目录 | 先查 ID，再加 `--kb <knowledgeId> [--dir <directoryId>]` |
+| 追加到刚才那条会 | 先定 `noteId`，再加 `--append-to <noteId>` |
 
-说明：
+## 哪些必须组合（缺步即错）
 
-- `create` 当前仅支持 `--type text`（默认）。录音/文档/图片/链接依赖 `file upload`，尚未开放。
-- `delete` 必须带 `--yes`。
-- `update` 的 `--abstract` 对应接口字段 `abstractContent`。
+| 用户说法 | 顺序 |
+|---|---|
+| 用会议纪要场景做笔记 | ① `scene list`/`scene builtins` 查 `sceneId` ② `save … --scene-id --wait` |
+| 放到工作笔记集再保存 | ① `kb list` 查 `knowledgeId`（② 点目录再 `kb catalog` 查 `directoryId`）③ `save … --kb [--dir] --wait` |
+| 打开/纪要/原文/短链/改/删/下音频（没给 ID） | ① `notes --title` 选定 ② `note get/update/delete/audio …` |
+| 改标题后再确认 | ① `note update <id> --title …` ② `note get <id>` 读回 |
+| 追加到刚才那条会（无 noteId） | ① `notes --title` 选定 ② `save … --append-to <id> --wait`（不要另存新笔记） |
+| 上次那条还在转，好了叫我 | ① `note wait <id>` ② 仅 `completed` 后 `note get <id>` |
 
-## 尚未实现（勿调用）
+## 命令速查
 
 | 意图 | 命令 |
 |---|---|
-| 上传文件 | `zhizai file upload <path>` |
-| 问答总结 | `zhizai ask "<问题>"` |
+| 做成笔记 | `zhizai save <文件\|URL>... [--title …] [--wait] -o json` |
+| 文字笔记 | `zhizai save --title … --content …`（或 `note create --title … --content …`，仅 text） |
+| 只上传 | `zhizai file upload <path> [--compress] -o json`（音频不建议 `--compress`） |
+| 按 fileId 下载 | `zhizai file get <fileId> --out <path>`（`-o` 是输出格式，下载路径用 `--out`） |
+| 列表 | `zhizai notes [--title/--type/--abstract/--summary/--content …] [--from … --to …] [--page --limit \| --all] [--with-content] [--with-short-url] -o json` |
+| 详情 | `zhizai note get <id> [--field content\|summary\|abstract\|…] [--short-url] [--with-append]` |
+| 进度 / 等待 | `zhizai note status <id>` / `zhizai note wait <id>` |
+| 改 | `zhizai note update <id> [--title --abstract --summary]`（只改传入字段） |
+| 删 | `zhizai note delete <id> --yes` |
+| 下载录音 | `zhizai note audio <id> --out ./a.mp3`（非录音笔记会失败；只有 fileId 走 `file get`） |
+
+## 错误边界
+
+- 本地路径不存在：不执行 `save` / `file upload`。
+- 空列表是成功：「没有符合条件的笔记」。
+- 删除、覆盖性修改先确认；未 `--yes` 不删。无权限/不存在不能说已删。
+- `note wait` 得到 `failed`：展示状态与原因，**禁止自动再 `save`**。
+- `--kb` 无效：笔记可能已创建但未归档，必须拆开说「已创建但未归档」。
+- 处理中（`recognizing`/`analyzing`）如实说明；不把 summary 冒充原文，不假装完成。
+- 用户没要分享时，不主动加 `--short-url` / `--with-short-url`。

package/skills/zhizai-scene/SKILL.md

@@ -1,13 +1,28 @@
 ---
 name: zhizai-scene
-version: 1.0.0
-description: 查询智在记录总结场景与知识卡。
+version: 2.0.0
+description: |
+  用 zhizai CLI 查询总结场景与知识卡：内置场景、我的场景（含共享）、我创建的知识卡。
+  用户说有哪些总结场景、我的场景、我的知识卡，或「用某某场景」做笔记/总结前需要查 sceneId 时使用。
 ---
 
-# 智在记录场景
+# 智在记录场景与知识卡（scene / cards）
 
-| 意图 | 命令 |
-|---|---|
-| 场景与知识卡 | `zhizai scene -o json` |
+机器调用加 `-o json`。`sceneId` 当字符串。
 
-字段说明见 `skills/zhizai-open-platform/references/scene.md`。
+## 命令
+
+| 用户说法 | 命令 | 说明 |
+|---|---|---|
+| 有哪些总结场景 | `zhizai scene builtins -o json` | 内置/平台场景。**返回是按分类分组的 Map**，必须遍历各分类数组取 `id` / `scene_name`，不要当普通 list（否则得到 0 条） |
+| 我的场景 | `zhizai scene list -o json` | 默认含共享场景（`--include-shared=false` 关闭）。空列表是成功 |
+| 我的知识卡 | `zhizai cards [--page 1 --limit 10] -o json` | 等价 `zhizai scene cards`。分页列表，空列表是成功 |
+
+## 名称 → sceneId
+
+用户说「用会议纪要场景…」时，场景名不能直接用：
+
+1. `zhizai scene builtins -o json`（或 `scene list`）按名称匹配，得真实 `sceneId`。
+2. 再把 `sceneId` 传给 `save --scene-id`（做成笔记，见 zhizai-note）或 `summarize --scene-id`（文字总结，见 zhizai-ask）。
+
+禁止把场景名当 `--scene-id`；查不到则停，不要空传。无效场景会导致创建失败。

package/skills/zhizai-team/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: zhizai-team
-version: 1.0.0
-description: 管理智在记录团队与成员。
+version: 1.0.1
+description: 管理智在记录团队与成员。注意：本次 CLI 场景测试不包含团队能力，命令保留占位。
 ---
 
 # 智在记录团队
 
+> **范围说明：本次场景测试不包含团队/消息/录音卡用例。** 以下命令保留占位，场景测试中勿用；真实团队操作前须先确认。
+
 | 意图 | 命令 |
 |---|---|
 | 团队操作 | `zhizai team -o json` |
 
-危险操作须先确认。字段说明见 `skills/zhizai-open-platform/references/team.md`。
+危险操作（新建/改删团队）须先确认。字段说明见 `skills/zhizai-open-platform/references/team.md`。