docz-cli 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +125 -64
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,118 +1,179 @@
1
+ <div align="center">
2
+
1
3
  # docz-cli
2
4
 
3
- DocSync 命令行工具 — 在终端读写公司文档。
5
+ **DocSync CLI & MCP Server — read and write company documents from terminal and AI agents**
4
6
 
5
- ## 安装
7
+ [![npm version](https://img.shields.io/npm/v/docz-cli.svg)](https://www.npmjs.com/package/docz-cli)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
9
 
7
- ```bash
8
- pnpm install && pnpm build
9
- ```
10
+ </div>
10
11
 
11
- 全局使用：
12
+ ---
13
+
14
+ ## Quick Start
12
15
 
13
16
  ```bash
14
- npm link
15
- # 或直接
16
- alias docz="node /path/to/docz-cli/dist/index.js"
17
+ # Login
18
+ npx docz-cli login --token <your-token>
19
+
20
+ # Browse
21
+ npx docz-cli spaces
22
+ npx docz-cli ls 研发
23
+ npx docz-cli cat 研发:docs/guide.md
24
+
25
+ # Write
26
+ npx docz-cli write 吴鹏飞:notes/todo.md '# TODO List'
17
27
  ```
18
28
 
19
- ## 配置
29
+ ## Features
20
30
 
21
- 两种方式任选：
31
+ - **Simple addressing** — `<space>:<path>` format, Space supports name or ID
32
+ - **Full file operations** — ls, cat, upload, write, mkdir, rm, mv
33
+ - **Git-backed** — every write creates a commit, built-in version history
34
+ - **Trash recovery** — deleted files recoverable within 30 days
35
+ - **MCP Server** — built-in stdio MCP server for AI agent integration
36
+ - **Zero config** — single token, works immediately
22
37
 
23
- ```bash
24
- # 方式一：环境变量
25
- export DOCSYNC_API_TOKEN=<your-token>
38
+ ## Installation
39
+
40
+ **Requirements:** Node.js >= 22.0.0
26
41
 
27
- # 方式二：login 命令（保存到 ~/.docz/config.json）
28
- docz login --token <your-token>
42
+ ```bash
43
+ npx docz-cli <command> # Use directly via npx
44
+ npm install -g docz-cli # Or global install, then use `docz` shorthand
29
45
  ```
30
46
 
31
- Token 获取方式：
47
+ > Global install registers both `docz-cli` and `docz` commands. Examples below use `docz-cli`; replace with `docz` if installed globally.
32
48
 
33
- 1. 登录 https://docz.zhenguanyu.com（SSO 自动登录）
34
- 2. 点击左下角用户邮箱旁的 **`···`** 按钮，或直接访问 https://docz.zhenguanyu.com/settings
35
- 3. 在 **Settings → Account** 页面找到 **API Tokens** 区域
36
- 4. 点击 **New Token**，输入名称（如 `my-cli`），确认创建
37
- 5. 复制生成的 token（只会显示一次）
49
+ ## Authentication
38
50
 
39
- ## 使用
51
+ Get your API Token:
40
52
 
41
- 所有命令的寻址格式统一为 `<space>:<path>`，Space 支持名称或 ID。
53
+ 1. Login to https://docz.zhenguanyu.com (SSO)
54
+ 2. Go to **Settings → Account → API Tokens** (or visit `/settings` directly)
55
+ 3. Click **New Token**, name it, copy the token (shown only once)
42
56
 
43
- ### 浏览
57
+ Then configure:
44
58
 
45
59
  ```bash
46
- docz spaces # 列出所有 Space
47
- docz ls 研发 # 列出根目录
48
- docz ls 研发:docs # 列出子目录
49
- docz cat 研发:docs/guide.md # 读取文件内容
60
+ # Option 1: login command (saved to ~/.docz/config.json)
61
+ docz-cli login --token <your-token>
62
+
63
+ # Option 2: environment variable
64
+ export DOCSYNC_API_TOKEN=<your-token>
50
65
  ```
51
66
 
52
- ### 写入
67
+ ## Commands
53
68
 
54
- ```bash
55
- # 直接写内容
56
- docz write 吴鹏飞:notes/todo.md '# TODO List'
69
+ | Command | Description |
70
+ |---------|-------------|
71
+ | `login --token <t>` | Configure credentials |
72
+ | `whoami` | Show current user |
73
+ | `spaces` | List all accessible spaces |
74
+ | `ls <space>[:<path>]` | List files and folders |
75
+ | `cat <space>:<path>` | Read file content |
76
+ | `upload <file> <space>[:<dir>]` | Upload local file |
77
+ | `write <space>:<path> <content>` | Write content to file (`-` for stdin) |
78
+ | `mkdir <space>:<path>` | Create folder |
79
+ | `rm <space>:<path>` | Delete file/folder (30-day trash) |
80
+ | `mv <space>:<from> <to>` | Rename or move |
81
+ | `log <space>[:<path>]` | Show change history |
82
+ | `trash <space>` | Show deleted files |
83
+ | `mcp` | Start MCP stdio server |
57
84
 
58
- # 从 stdin 写入
59
- echo '# Generated Report' | docz write 吴鹏飞:reports/daily.md -
85
+ ## Usage Examples
60
86
 
61
- # 上传本地文件
62
- docz upload ./report.pdf 研发:reports
87
+ ### Browse
63
88
 
64
- # 创建文件夹
65
- docz mkdir 研发:new-project
89
+ ```bash
90
+ docz-cli spaces # List all spaces
91
+ docz-cli ls 研发 # List root directory
92
+ docz-cli ls 研发:docs # List subdirectory
93
+ docz-cli cat 研发:docs/guide.md # Read file content
66
94
  ```
67
95
 
68
- ### 管理
96
+ ### Write
69
97
 
70
98
  ```bash
71
- docz mv 研发:old-name.md new-name.md # 重命名/移动
72
- docz rm 研发:deprecated.md # 删除（30 天内可从回收站恢复）
73
- docz log 研发 # Space 操作历史
74
- docz log 研发:docs/guide.md # 单文件变更历史
75
- docz trash 研发 # 查看回收站
99
+ docz-cli write 吴鹏飞:notes/todo.md '# TODO List' # Write content
100
+ echo '# Report' | docz-cli write 吴鹏飞:reports/daily.md - # From stdin
101
+ docz-cli upload ./report.pdf 研发:reports # Upload file
102
+ docz-cli mkdir 研发:new-project # Create folder
76
103
  ```
77
104
 
78
- ### 其他
105
+ ### Manage
79
106
 
80
107
  ```bash
81
- docz whoami # 当前登录用户
82
- docz --help # 完整帮助
83
- docz ls --help # 单命令帮助
108
+ docz-cli mv 研发:old.md new.md # Rename
109
+ docz-cli rm 研发:deprecated.md # Delete (recoverable)
110
+ docz-cli log 研发 # Space history
111
+ docz-cli log 研发:docs/guide.md # File history
112
+ docz-cli trash 研发 # View trash
84
113
  ```
85
114
 
86
- ## 在 AI Agent 中使用
115
+ ## MCP Server
116
+
117
+ Built-in MCP server for AI agent integration (Claude Code, Cursor, etc.).
87
118
 
88
- docz-cli 设计为终端原生工具，任何能执行 shell 命令的 AI Agent 都能直接调用：
119
+ ### Configuration
89
120
 
121
+ Add to your MCP settings:
122
+
123
+ ```json
124
+ {
125
+ "mcpServers": {
126
+ "docsync": {
127
+ "command": "npx",
128
+ "args": ["-y", "docz-cli", "mcp"],
129
+ "env": {
130
+ "DOCSYNC_API_TOKEN": "<your-token>"
131
+ }
132
+ }
133
+ }
134
+ }
90
135
  ```
91
- 用户：帮我看看研发 Space 里有什么文档
92
- Agent：执行 docz ls 研发
93
- Agent：研发 Space 下有 3 个文件...
94
136
 
95
- 用户：把这份分析报告上传到我的 Space
96
- Agent：执行 docz write 吴鹏飞:reports/analysis.md '<内容>'
97
- Agent：已上传到 reports/analysis.md
137
+ ### MCP Tools
138
+
139
+ | Tool | Description |
140
+ |------|-------------|
141
+ | `docsync_list_spaces` | List all accessible spaces |
142
+ | `docsync_list_files` | List files in a directory |
143
+ | `docsync_read_file` | Read file content |
144
+ | `docsync_upload_file` | Upload/create a file |
145
+ | `docsync_mkdir` | Create a folder |
146
+ | `docsync_delete` | Delete file/folder |
147
+ | `docsync_file_history` | View change history |
148
+
149
+ ## AI Agent Skill
150
+
151
+ Install as a [reskill](https://github.com/kanyun-inc/reskill) skill to teach AI agents how to use docz-cli:
152
+
153
+ ```bash
154
+ npx reskill install github:kanyun-inc/docz-cli/skills -a claude-code cursor -y
98
155
  ```
99
156
 
100
- 环境变量 `DOCSYNC_API_TOKEN` 配置好后，Agent 的 Bash 工具可以直接使用所有命令。
157
+ The skill provides command reference, usage scenarios, and addressing format documentation so agents can autonomously browse, read, and write DocSync documents.
101
158
 
102
- ## DocSync API
159
+ ## API Reference
103
160
 
104
- docz-cli 封装了以下 DocSync REST API：
161
+ docz-cli wraps the DocSync REST API:
105
162
 
106
- | 命令 | API |
107
- |------|-----|
163
+ | Command | API Endpoint |
164
+ |---------|-------------|
108
165
  | `spaces` | `GET /api/spaces` |
109
166
  | `ls` | `GET /api/spaces/{id}/tree?path=` |
110
167
  | `cat` | `GET /api/spaces/{id}/blob/{path}` |
111
- | `upload` / `write` | `POST /api/spaces/{id}/files/upload` (FormData) |
168
+ | `upload` / `write` | `POST /api/spaces/{id}/files/upload` |
112
169
  | `mkdir` | `POST /api/spaces/{id}/files/mkdir` |
113
170
  | `rm` | `POST /api/spaces/{id}/files/delete` |
114
171
  | `mv` | `POST /api/spaces/{id}/files/rename` |
115
172
  | `log` | `GET /api/spaces/{id}/log/[{path}]` |
116
173
  | `trash` | `GET /api/spaces/{id}/trash` |
117
174
 
118
- 认证统一使用 `Authorization: Bearer <token>`。DocSync 底层基于 Git，所有写操作自动产生 commit，天然有版本历史。
175
+ Auth: `Authorization: Bearer <token>`. Backend is Git — every write is a commit.
176
+
177
+ ## License
178
+
179
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "docz-cli",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "DocSync CLI — read and write company documents",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",