@zhizai/cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iswalle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,304 @@
+# 智在记录 CLI
+
+智在记录的命令行工具，让你在终端和 AI Agent 里直接管理笔记、笔记集、场景与团队。
+
+查笔记、写总结、管知识库——一条命令搞定，支持脚本和 AI Agent 调用。
+
+> **当前版本：v0.0.1**  
+> 已实现：`auth` / `doctor` / `capabilities` / `version` / `notes` / `note get` / `setup`。  
+> 其余业务命令（`note create` / `ask` / `team` 等）已挂载子命令树，实现中。
+
+---
+
+## 安装
+
+### 从源码构建（推荐开发期）
+
+需要 Go 1.21+：
+
+```bash
+git clone https://github.com/BoteAI/zhizai-cli.git
+cd zhizai-cli
+make build
+make install
+```
+
+构建产物：
+
+| 文件 | 说明 |
+|------|------|
+| `zhizai-cli` | `make build` 直接产物 |
+| `bin/zhizai` | `make dev-link` 复制到 npm 启动器目录 |
+
+安装后可用命令：`zhizai` 与短别名 `zz`（`make install` 会安装符号链接；npm 全局安装同样注册两个入口）。
+
+### npm 全局安装（Release 后可用）
+
+```bash
+npm install -g @zhizai/cli@latest
+zhizai auth login --api-key <your-api-key>
+zhizai doctor -o json
+```
+
+`postinstall` 会下载对应平台的二进制；发布 Release 前请优先用源码构建。
+
+### 维护者发版
+
+仓库已配置 tag 触发：构建多平台二进制 → GitHub Release → `npm publish`。
+
+前置：GitHub Actions Secret 配置 `NPM_TOKEN`；本地 `.npmrc` 仅用于本机 npm，**不要提交**（见 `.npmrc.example`）。
+
+```bash
+# 使用 package.json 当前版本打 tag 并推送
+make release
+# 或
+npm run release
+
+# 升版本后再发（注意用 V=，不要用 VERSION=）
+make release V=patch
+make release V=0.0.2
+```
+
+---
+
+## 使用要求
+
+- 需要有效的智在记录 **API Key**
+- 获取入口：[智在记录开发者](https://www.zzjilu.com/pc/developer)
+- OpenAPI 基址：`https://openapi.zzjilu.com/api/v1`
+- 请求头：`Authorization: <api-key>`（**不要**加 `Bearer`）
+- 限流：最高约 **2 次/秒**
+
+---
+
+## 开始使用
+
+### 登录
+
+```bash
+# 直接传入 API Key（推荐脚本/CI）
+zhizai auth login --api-key <your-api-key>
+
+# 或交互粘贴
+zhizai auth login
+```
+
+登录成功后会写入 `~/.zhizai/config.json`，并调用 `queryNoteList` 做一次探活。
+
+也可用环境变量（优先级高于配置文件）：
+
+```bash
+export ZHIZAI_REC_API_KEY=<your-api-key>
+```
+
+### 检查状态
+
+```bash
+zhizai auth status
+zhizai doctor
+zhizai doctor -o json
+zhizai capabilities -o json
+```
+
+`doctor` 返回 `ready=true,status=ready` 表示可正常调用业务接口。
+
+### 查看笔记
+
+```bash
+zhizai notes
+zhizai notes --limit 10 -o json
+zhizai notes --all
+zhizai note get <id>
+zhizai note get <id> --field summary
+```
+
+### 接入本机 AI
+
+```bash
+# 预览将执行的操作
+zhizai setup --dry-run -o json
+
+# 正式安装（本地验收可跳过 npm 全局安装）
+zhizai setup --skill-source . --skip-cli-install
+```
+
+---
+
+## 命令一览
+
+### 已可用
+
+```
+zhizai auth login [--api-key <key>]   保存 API Key 并验证连接
+zhizai auth status                    查看认证状态（Key 掩码显示）
+zhizai auth logout                    清除本机凭证
+zhizai doctor                         检查安装、登录与 API 连通性
+zhizai capabilities                   查看当前版本的稳定能力契约
+zhizai version                        显示版本
+zhizai notes [--limit|--page|--all]   笔记列表
+zhizai note get <id> [--field ...]    笔记详情
+zhizai setup [--dry-run]              为本机 AI 安装原子 Skill 并引导授权
+```
+
+### 规划中（子命令已挂载，业务逻辑待实现）
+
+```
+zhizai note create|update|delete|status
+zhizai file upload                    文件上传
+zhizai ask "<问题>"                   基于笔记的动态模版问答/总结
+zhizai scene                          场景与知识卡
+zhizai knowledge                      笔记集
+zhizai team                           团队与成员
+zhizai msg                            消息与录音卡
+zhizai update                         升级 CLI 并同步 Skill
+```
+
+字段与接口细节以 `skills/zhiji-open-platform/references/` 为准。
+
+---
+
+## 全局参数
+
+| 参数 | 说明 |
+|------|------|
+| `--api-key <key>` | 临时覆盖 API Key |
+| `-o, --output table\|json` | 输出格式（默认 `table`） |
+
+机器 / AI Agent 调用时请加 `-o json`，统一读取：
+
+```json
+{
+  "success": true,
+  "data": {},
+  "error": null
+}
+```
+
+失败时 `success=false`，读取 `error.code` / `error.message` / `error.reason` / `error.retryable`。
+
+---
+
+## 配置
+
+凭证保存在 `~/.zhizai/config.json`：
+
+```json
+{
+  "api_key": "xxxx",
+  "expires_at": "2027-12-31 23:59:59",
+  "team_id": ""
+}
+```
+
+凭证优先级：
+
+```text
+--api-key  >  环境变量 ZHIZAI_REC_API_KEY  >  ~/.zhizai/config.json
+```
+
+| 环境变量 | 说明 |
+|----------|------|
+| `ZHIZAI_REC_API_KEY` | API Key |
+| `ZHIZAI_API_URL` | 覆盖 API 基址（默认 `https://openapi.zzjilu.com/api/v1`） |
+| `GOPROXY` | 构建时 Go 模块代理，国内可用 `https://goproxy.cn,direct` |
+
+---
+
+## 鉴权说明
+
+v0.1 仅支持 **API Key**：
+
+1. 在开发者页获取 Key，或由管理员下发后自行配置
+2. `zhizai auth login --api-key ...` 保存并探活
+3. 后续请求自动带 `Authorization: <api-key>`
+
+OAuth 浏览器授权计划在后续版本补齐，不影响当前 API Key 流程。
+
+---
+
+## AI Agent 使用
+
+所有命令支持 `-o json`。内置原子 Skill 源在 `skills/`：
+
+| Skill | 职责 |
+|-------|------|
+| `zhizai-auth` | 安装、登录、诊断、升级 |
+| `zhizai-note` | 笔记 CRUD、上传、问答 |
+| `zhizai-knowledge` | 笔记集 |
+| `zhizai-scene` | 场景与知识卡 |
+| `zhizai-team` | 团队与成员 |
+| `zhizai-msg` | 消息与录音卡 |
+
+另保留聚合 Skill `zhiji-open-platform`（含完整 OpenAPI 参考文档）。  
+`zhizai setup` 就绪后，会把原子 Skill 安装到 Cursor、Claude Code、Codex 等本机 AI。
+
+原则：**Skill 只做意图路由，真实请求一律走 `zhizai` CLI**，不自行拼 OpenAPI。
+
+---
+
+## 从源码开发
+
+```bash
+# 依赖
+go version   # >= 1.21
+
+# 构建
+make build
+
+# 本地链接到 bin/zhizai（配合 npm 启动器调试）
+make dev-link
+
+# 安装到 PATH
+make install
+
+# 测试 / 静态检查
+make test
+make lint
+
+# 多平台交叉编译
+make build-all
+```
+
+目录结构：
+
+```text
+zhizai-cli/
+├── main.go
+├── cmd/                 # Cobra 子命令
+├── internal/
+│   ├── client/          # OpenAPI HTTP 客户端（限流、resultCode 适配）
+│   ├── config/          # ~/.zhizai/config.json
+│   ├── output/          # 统一 JSON 输出
+│   ├── platform/        # 本机 AI 平台探测
+│   ├── ui/
+│   └── version/
+├── skills/              # 原子 Skill + 开放平台参考
+├── bin/zhizai.js        # npm 启动器
+├── scripts/postinstall.js
+└── .github/workflows/release.yml
+```
+
+---
+
+## 路线图
+
+| 版本 | 内容 |
+|------|------|
+| **v0.1** | 脚手架、auth、doctor、capabilities（当前） |
+| **v0.2** | notes / note 详情与 CRUD、file upload |
+| **v0.3** | setup 安装 Skill、capabilities 完善 |
+| **v0.4** | scene / knowledge / team / msg |
+| **v0.5** | ask 动态模版总结管线 |
+| **v1.0** | update、Release CI、npm 发布 |
+
+---
+
+## 相关链接
+
+- [智在记录官网](https://www.zzjilu.com)
+- [开发者中心](https://www.zzjilu.com/pc/developer)
+- [问题反馈](https://github.com/BoteAI/zhizai-cli/issues)
+
+## License
+
+[MIT](./LICENSE)

package/bin/zhizai.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Platform-agnostic launcher for zhizai binary
+
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+
+const platform = os.platform();
+const binaryName = platform === 'win32' ? 'zhizai.exe' : 'zhizai';
+const binaryPath = path.join(__dirname, binaryName);
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code);
+  }
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@zhizai/cli",
+  "version": "0.0.1",
+  "description": "CLI tool for 智在记录 — manage notes and knowledge from the terminal and AI agents",
+  "keywords": [
+    "zhizai",
+    "zhiji",
+    "cli",
+    "notes"
+  ],
+  "homepage": "https://github.com/BoteAI/zhizai-cli",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BoteAI/zhizai-cli.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "zhizai": "./bin/zhizai.js",
+    "zz": "./bin/zhizai.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "release": "bash scripts/release.sh"
+  },
+  "files": [
+    "bin/zhizai.js",
+    "scripts/postinstall.js",
+    "skills/",
+    "README.md"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// postinstall.js — downloads the zhizai binary for the current platform.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const pkg = require('../package.json');
+const VERSION = pkg.version;
+const REPO = 'BoteAI/zhizai-cli';
+
+function getPlatform() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const platformMap = { darwin: 'darwin', linux: 'linux', win32: 'windows' };
+  const archMap = { x64: 'amd64', arm64: 'arm64' };
+
+  const p = platformMap[platform];
+  const a = archMap[arch];
+  if (!p || !a) throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  return { platform: p, arch: a };
+}
+
+function getBinaryName(platform) {
+  return platform.platform === 'windows' ? 'zhizai.exe' : 'zhizai';
+}
+
+function getDownloadURL(platform) {
+  const ext = platform.platform === 'windows' ? '.zip' : '.tar.gz';
+  const asset = `zhizai-cli_${VERSION}_${platform.platform}_${platform.arch}${ext}`;
+  return `https://github.com/${REPO}/releases/download/v${VERSION}/${asset}`;
+}
+
+function getWindowsExtractArgs(archivePath, destinationPath) {
+  return [
+    '-NoProfile',
+    '-Command',
+    '& { Expand-Archive -LiteralPath $args[0] -DestinationPath $args[1] -Force }',
+    archivePath,
+    destinationPath,
+  ];
+}
+
+async function installArchive({ platform, binDir, binaryName, binaryPath, url, tmpFile }) {
+  try {
+    await download(url, tmpFile);
+    await verifyChecksum(url, path.basename(url), tmpFile);
+    if (platform.platform === 'windows') {
+      run('powershell', getWindowsExtractArgs(tmpFile, binDir));
+    } else {
+      run('tar', ['-xzf', tmpFile, '-C', binDir, binaryName]);
+    }
+
+    fs.chmodSync(binaryPath, 0o755);
+    console.log(`zhizai installed at ${binaryPath}`);
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch (_) {}
+  }
+}
+
+async function main() {
+  const platform = getPlatform();
+  const binDir = path.join(__dirname, '..', 'bin');
+  const binaryName = getBinaryName(platform);
+  const binaryPath = path.join(binDir, binaryName);
+  const url = getDownloadURL(platform);
+  const tmpFile = path.join(os.tmpdir(), `zhizai-download-${Date.now()}`);
+
+  if (fs.existsSync(binaryPath)) {
+    try {
+      const result = spawnSync(binaryPath, ['version'], { encoding: 'utf8' });
+      const out = (result.stdout || '').trim();
+      if (result.status === 0 && out.includes(VERSION)) {
+        console.log(`zhizai v${VERSION} already installed, skipping download.`);
+        return;
+      }
+    } catch (_) {}
+  }
+
+  console.log(`Downloading zhizai v${VERSION} for ${platform.platform}/${platform.arch}...`);
+  console.log(`URL: ${url}`);
+
+  fs.mkdirSync(binDir, { recursive: true });
+  await installArchive({ platform, binDir, binaryName, binaryPath, url, tmpFile });
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  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 {
+    await download(new URL('checksums.txt', assetURL).toString(), checksumPath);
+    const line = fs.readFileSync(checksumPath, 'utf8').split(/\r?\n/).find(value => {
+      const fields = value.trim().split(/\s+/);
+      return fields.length === 2 && fields[1].replace(/^\*/, '') === assetName;
+    });
+    if (!line) throw new Error(`Checksum for ${assetName} is missing`);
+    const expected = line.trim().split(/\s+/)[0].toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(expected)) throw new Error(`Checksum for ${assetName} is invalid`);
+    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 (_) {}
+  }
+}
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error('Failed to install zhizai:', err.message);
+    process.exitCode = 1;
+  });
+}

package/skills/zhiji-open-platform/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: zhiji-open-platform
+version: 1.0.0
+description: |
+  通过智在记录开放 API 连接笔记数据：鉴权、检索/问答/总结（动态模版路由）、笔记 CRUD、场景与知识卡、笔记集、团队、消息与录音卡。
+  用户要查笔记、写周报/复盘、新建编辑删除笔记、管团队/笔记集/录音卡，或配置 ZHIZAI_REC_API_KEY 时使用。
+  基准地址为常量 ZHIZAI_BASE_URL；鉴权 Header 直接传 Key（无 Bearer）。
+metadata:
+  openclaw:
+    emoji: "📒"
+    requires: {}
+    optionalEnv:
+      - ZHIZAI_REC_API_KEY
+---
+
+# 智在记录 · 开放平台
+
+让用户在当前 AI 中用自然语言访问智在记录：检索与总结、维护笔记、管理场景/笔记集/团队与录音卡。本 Skill 理解意图、加载对应领域参考，再按官方 REST API 执行真实操作。
+
+## 能力与外部影响
+
+- 按用户请求调用 `https://openapi.zzjilu.com/api/v1` 下的开放接口，读取或修改当前 API Key 对应账号的数据。
+- 鉴权依赖环境变量 `ZHIZAI_REC_API_KEY`（请求头 `Authorization` 直接传 Key，**不要**加 `Bearer`）。
+- 新建/编辑/删除笔记、加人删团队、发消息等会修改远端数据，须遵守下方确认规则。
+- 限流最高 **2 次/秒**；连续调用宜间隔 ≥500ms。
+- 不会自行安装其他软件、下载覆盖本 Skill，或在回复中泄露完整 Key。
+
+## 能力概览
+
+| 用户想做什么 | 典型说法 | 完成后应返回什么 |
+| --- | --- | --- |
+| 基于笔记问答/总结 | “本周会议总结一下”“帮我写周报” | 按模版或语义结构整理的真实结论；无笔记时诚实说明 |
+| 查找笔记 | “最近有哪些录音”“找一下报销相关” | 真实 `id`、标题、中文类型、时间、摘要/总结 |
+| 新建/上传笔记 | “存这篇文档”“记一条文本” | 真实笔记 ID、标题、`note_state`；未完成时说明进度 |
+| 改删与进度 | “改标题”“删掉这条”“处理完了吗” | 最终状态；删除/覆盖先确认；进度≠正文 |
+| 场景与知识卡 | “有哪些总结场景”“看知识卡” | 真实场景/卡片列表，可用 ID |
+| 笔记集 | “我创建的笔记集”“打开某某集” | 真实知识库名称、ID、集内条目 |
+| 团队 | “建个团队”“加个成员” | 真实团队/成员 ID；危险操作先确认 |
+| 录音卡 / 发消息 | “查一下这张卡”“给某某发消息” | 用量/连接状态或发送结果；敏感字段脱敏 |
+| 连接与鉴权 | “配置 Key”“用口令换 Key” | Key 是否可用；口令换 Key 不展示完整密钥 |
+
+不要要求用户记接口路径。用户用自然语言表达目标即可。
+
+## 首次连接
+
+1. 检查 `ZHIZAI_REC_API_KEY` 是否已配置且非空。未配置：只提示配置该变量，并推荐 [智在记录开发者](https://www.zzjilu.com/pc/developer)；不继续调业务接口。
+2. 用无写入验收：`POST /note/queryNoteList`，`pageNum=1`、`pageSize=1`。`resultCode=="0"` 才可说已连接。
+3. 只有用户同意时才创建测试笔记；必须返回真实 `id`、标题与 `note_state`。
+4. 本会话已成功调用过任一接口后，可不再重复强调 Key 检查。
+
+常量（非环境变量）：`ZHIZAI_BASE_URL` = `https://openapi.zzjilu.com/api/v1`。下文路径均接在该基准之后。
+
+## 每次任务的执行闭环
+
+1. **理解目标**：对象、动作、时间范围与输出版式；指代不清时先澄清。
+2. **加载领域参考**：只读取本次任务涉及的 `references/*.md`，不要凭印象猜路径、参数或返回字段。
+3. **确认真实 ID**：笔记、场景、笔记集、团队、成员等一律使用接口返回的真实 ID；重名时让用户选择。
+4. **按官方 API 调用**：JSON 用 `content-type: application/json`；上传用 `multipart/form-data`；遵守限流。
+5. **判断结果**：先看 HTTP（400/401/406=无权限），再看 `resultCode=="0"`；异步创建用 `queryNoteStatus` 轮询，不能把“已提交”说成“已完成”。
+6. **必要时复读**：更新、删除、归档类操作后按需再查列表/详情确认最终状态。
+7. **回复用户**：先结论，再给必要字段；失败说明原因与下一步，不泄露 Key/`stack`。
+
+## 路由
+
+匹配用户意图后，**必须读取并遵循**对应领域参考：
+
+- 鉴权、口令换 Key、解析 token：[`references/auth.md`](references/auth.md)
+- 笔记检索/问答/总结（含动态模版）、CRUD、上传下载：[`references/note.md`](references/note.md)
+- 场景与知识卡：[`references/scene.md`](references/scene.md)
+- 笔记集（我创建/我收到/详情）：[`references/knowledge.md`](references/knowledge.md)
+- 团队与成员：[`references/team.md`](references/team.md)
+- 消息与录音卡：[`references/msg-device.md`](references/msg-device.md)
+
+多领域任务按步骤依次读取。例如“按场景总结本周会议笔记”先读 `note`（模版管线），需要 `sceneId` 时再读 `scene`。
+
+边界模糊且答案依赖笔记内容时：**默认走 `note` 中的动态模版管线**。
+
+## 结果呈现标准
+
+- **总结/问答**：按最终选用模版填充真实笔记；缺失标「未提及」；不默认整段贴出模版原文。
+- **笔记列表**：`id`、`title`、中文类型、`create_time`；有 `summary` 用总结否则 `abstract`。`note_type` 必须转中文（见 `note.md`）。
+- **新建成功**：返回真实 ID、标题、`note_state`；`pending` 等说明处理中并可查进度。
+- **进度查询**：只报告系统处理阶段，不当作正文内容。
+- **空结果**：柔和说明未找到及相关检索范围，可建议换词/调时间，禁止编造。
+- **失败**：用户能理解的短句 + 可执行下一步；禁止展示完整 Key、`stack`、未脱敏 `errorInfos`。
+
+## 统一规则
+
+- 真实操作只走开放 API；字段与 curl 以对应 `references/*.md` 的「接口协议」为准。
+- `resultCode != "0"` 一律失败；优先用 `resultMsg` 短句说明。
+- ID、fileId 始终按返回原样传递，禁止臆造。
+- 修改笔记路径为 **`POST /note/updateNoteInfo`**（不是 `updateNote`）；摘要请求字段为 `abstractContent`。
+- 删除笔记、删团队/成员、发消息、覆盖性修改须先确认。
+- 群聊或共享会话中不主动展开私密全文与手机号。
+- 口令换 Key：口令与返回的 Key **禁止**在对话中完整展示。
+
+## 常见恢复方式
+
+- HTTP 400/401/406 或鉴权失败：读 `references/auth.md`，检查 `ZHIZAI_REC_API_KEY`，引导开发者页，不回显 Header。
+- 限流：等待后重试，不高频循环。
+- 笔记不存在 / 非录音却下音频：说明真实原因，改用正确 ID 或接口。
+- 创建后长期 `pending`：用 `queryNoteStatus` 查询，提示稍后查看，不伪造已完成总结。
+- 网络中断或结果不确定：只做查询核验，不自动重复写入。