@zhizai/cli 0.0.2 → 0.0.4

package/README.md

@@ -4,94 +4,62 @@
 
 查笔记、写总结、管知识库——一条命令搞定，支持脚本和 AI Agent 调用。
 
-> **当前版本：v0.0.2**  
-> 已实现：`auth` / `doctor` / `capabilities` / `version` / `notes` / `note get` / `setup`。  
-> 其余业务命令（`note create` / `ask` / `team` 等）已挂载子命令树，实现中。
+> **当前版本：v0.0.4**  
+> 已可用：`auth` / `doctor` / `capabilities` / `version` / `notes` / `note get` / `setup`。  
+> 其余业务命令（`note create` / `ask` / `team` 等）子命令已挂载，能力逐步完善中。
+
+参与开发、构建与发包请见 [docs/development.md](./docs/development.md)。
 
 ---
 
 ## 安装
 
-### 从源码构建（推荐开发期）
-
-需要 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 后可用）
+推荐使用 npm 全局安装（会自动下载对应平台二进制）：
 
 ```bash
 npm install -g @zhizai/cli@latest
-zhizai auth login --api-key <your-api-key>
-zhizai doctor -o json
 ```
 
-`postinstall` 会下载对应平台的二进制；发布 Release 前请优先用源码构建。
+安装后可用命令：
 
-### 维护者发版
+- `zhizai` — 主命令
+- `zz` — 短别名
 
-仓库已配置 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
+zhizai version
+zz version
 ```
 
+也可从 [GitHub Releases](https://github.com/BoteAI/zhizai-cli/releases) 下载对应平台压缩包，解压后将 `zhizai` / `zhizai.exe` 放到 `PATH` 中。
+
 ---
 
 ## 使用要求
 
-- 需要有效的智在记录 **API Key**
-- 获取入口：[智在记录开发者](https://www.zzjilu.com/pc/developer)
-- OpenAPI 基址：`https://openapi.zzjilu.com/api/v1`
-- 请求头：`Authorization: <api-key>`（**不要**加 `Bearer`）
+- 通过 `zhizai auth login` 完成**网页授权登录**
 - 限流：最高约 **2 次/秒**
 
 ---
 
 ## 开始使用
 
-### 登录
+### 1. 登录
 
 ```bash
-# 直接传入 API Key（推荐脚本/CI）
-zhizai auth login --api-key <your-api-key>
-
-# 或交互粘贴
 zhizai auth login
 ```
 
-登录成功后会写入 `~/.zhizai/config.json`，并调用 `queryNoteList` 做一次探活。
+按提示在浏览器确认授权即可。登录成功后写入 `~/.zhizai/config.json`。
 
-也可用环境变量（优先级高于配置文件）：
+刷新 OAuth access_token（业务请求也会在过期时自动刷新）：
 
 ```bash
-export ZHIZAI_REC_API_KEY=<your-api-key>
+zhizai auth refresh
 ```
 
-### 检查状态
+### 2. 检查状态
 
 ```bash
 zhizai auth status
@@ -102,7 +70,7 @@ zhizai capabilities -o json
 
 `doctor` 返回 `ready=true,status=ready` 表示可正常调用业务接口。
 
-### 查看笔记
+### 3. 查看笔记
 
 ```bash
 zhizai notes
@@ -112,48 +80,49 @@ zhizai note get <id>
 zhizai note get <id> --field summary
 ```
 
-### 接入本机 AI
+### 4. 接入本机 AI
 
 ```bash
 # 预览将执行的操作
 zhizai setup --dry-run -o json
 
-# 正式安装（本地验收可跳过 npm 全局安装）
-zhizai setup --skill-source . --skip-cli-install
+# 正式安装 Skill
+zhizai setup
 ```
 
+`setup` 会把原子 Skill 安装到 Cursor、Claude Code、Codex 等本机 AI 环境，并引导完成授权。
+
 ---
 
-## 命令一览
+## 功能一览
 
 ### 已可用
 
-```
-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/` 为准。
+| 命令 | 说明 |
+|------|------|
+| `zhizai auth login` | 网页设备授权登录 |
+| `zhizai auth refresh` | 刷新 OAuth access_token |
+| `zhizai auth status` | 查看认证状态（凭证掩码） |
+| `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 |
 
 ---
 
@@ -161,7 +130,6 @@ zhizai update                         升级 CLI 并同步 Skill
 
 | 参数 | 说明 |
 |------|------|
-| `--api-key <key>` | 临时覆盖 API Key |
 | `-o, --output table\|json` | 输出格式（默认 `table`） |
 
 机器 / AI Agent 调用时请加 `-o json`，统一读取：
@@ -180,45 +148,21 @@ zhizai update                         升级 CLI 并同步 Skill
 
 ## 配置
 
-凭证保存在 `~/.zhizai/config.json`：
+凭证保存在 `~/.zhizai/config.json`（含 OAuth `access_token` / `refresh_token` 等字段）。
 
-```json
-{
-  "api_key": "xxxx",
-  "expires_at": "2027-12-31 23:59:59",
-  "team_id": ""
-}
-```
+### 鉴权说明
 
-凭证优先级：
+默认使用 **OAuth 设备授权**：`zhizai auth login` → 浏览器确认 → 业务请求头 `X-OAuth2-Access-Token: Bearer …`。
 
-```text
---api-key  >  环境变量 ZHIZAI_REC_API_KEY  >  ~/.zhizai/config.json
-```
+OAuth 过期时 CLI 会自动用 `refresh_token` 刷新；也可手动 `zhizai auth refresh`。
 
-| 环境变量 | 说明 |
-|----------|------|
-| `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 流程。
+仅当网页授权失败时，CLI 会提示可改用 API Key 备用登录。
 
 ---
 
 ## AI Agent 使用
 
-所有命令支持 `-o json`。内置原子 Skill 源在 `skills/`：
+所有命令支持 `-o json`。内置原子 Skill：
 
 | Skill | 职责 |
 |-------|------|
@@ -229,74 +173,17 @@ OAuth 浏览器授权计划在后续版本补齐，不影响当前 API Key 流
 | `zhizai-team` | 团队与成员 |
 | `zhizai-msg` | 消息与录音卡 |
 
-另保留聚合 Skill `zhiji-open-platform`（含完整 OpenAPI 参考文档）。  
-`zhizai setup` 就绪后，会把原子 Skill 安装到 Cursor、Claude Code、Codex 等本机 AI。
+另保留聚合 Skill `zhiji-open-platform`（含完整 OpenAPI 参考文档）。
 
 原则：**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)
+- [开发与发包说明](./docs/development.md)
 - [问题反馈](https://github.com/BoteAI/zhizai-cli/issues)
 
 ## License

package/package.json

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

package/scripts/postinstall.js

@@ -57,7 +57,13 @@ async function installArchive({ platform, binDir, binaryName, binaryPath, url, t
       run('tar', ['-xzf', tmpFile, '-C', binDir, binaryName]);
     }
 
-    fs.chmodSync(binaryPath, 0o755);
+    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 (_) {}
@@ -70,7 +76,9 @@ async function main() {
   const binaryName = getBinaryName(platform);
   const binaryPath = path.join(binDir, binaryName);
   const url = getDownloadURL(platform);
-  const tmpFile = path.join(os.tmpdir(), `zhizai-download-${Date.now()}`);
+  // 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}`);
 
   if (fs.existsSync(binaryPath)) {
     try {

package/skills/zhizai-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zhizai-auth
-description: 安装和连接智在记录，完成 API Key 配置、环境诊断与 CLI 升级。用户说安装、连接、登录、检查为什么不能用时使用。
+description: 安装和连接智在记录，完成网页授权登录、环境诊断与 CLI 升级。用户说安装、连接、登录、检查为什么不能用时使用。
 ---
 
 # 智在记录连接与诊断
@@ -11,9 +11,11 @@ description: 安装和连接智在记录，完成 API Key 配置、环境诊断
 
 | 意图 | 命令 |
 |---|---|
-| 登录 | `zhizai auth login --api-key <key>` |
+| 登录 | `zhizai auth login` |
 | 查看状态 | `zhizai auth status` |
 | 退出 | `zhizai auth logout` |
 | 诊断 | `zhizai doctor -o json` |
 | 能力契约 | `zhizai capabilities -o json` |
 | 安装 Skill | `zhizai setup` |
+
+默认使用网页设备授权。仅当网页授权失败时，再提示用户使用 `zhizai auth login --api-key <key>`。