feishu-docs-cli 0.1.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cliff-byte
+
+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,333 @@
+# feishu-docs-cli
+
+[中文文档](./README.zh.md)
+
+CLI tool for AI Agents to read/write Feishu (Lark) docs via shell commands.
+
+## Features
+
+- **Read** documents as Markdown, raw text, or original Block JSON
+- **Create** documents in knowledge bases or cloud folders
+- **Update** documents with overwrite or append mode
+- **Delete** documents (move to recycle bin)
+- **Info** — view document metadata (title, type, URL, revision)
+- **Browse** knowledge base structure (spaces, tree, cat)
+- **Search** documents by keyword
+- **Share** — manage collaborators (list, add, set public mode)
+- **List** files in cloud folders
+- Written in TypeScript with strict mode
+- Zero extra runtime dependencies — only `@larksuiteoapi/node-sdk`
+- Agent-friendly output — pure text or JSON, no interactive UI
+
+## Install
+
+```bash
+npm install -g github:cliff-byte/feishu-docs-cli
+```
+
+Or use directly with npx:
+
+```bash
+npx github:cliff-byte/feishu-docs-cli read <url>
+```
+
+Requires Node.js >= 18.3.
+
+## Setup
+
+### 1. Create a Feishu App
+
+1. Go to [Feishu Open Platform](https://open.feishu.cn/app) (or [Lark Developer](https://open.larksuite.com/app) for international)
+2. Click **Create Custom App**, fill in the app name and description
+3. After creation, go to the app's **Credentials & Basic Info** page. Copy the **App ID** (`cli_xxx`) and **App Secret** — you'll need them for environment variables
+4. Go to **Permissions & Scopes**, search and add the following scopes:
+
+   | Scope | Description | Required |
+   |-------|-------------|----------|
+   | `wiki:wiki` | Knowledge base access | Yes |
+   | `docx:document` | Document read/write | Yes |
+   | `docx:document.block:convert` | Markdown to block conversion | Yes (for create/update) |
+   | `drive:drive` | File management & permission management | Yes |
+   | `contact:contact.base:readonly` | User name resolution (@mentions) | Recommended |
+   | `board:whiteboard:node:read` | Whiteboard content read | Optional |
+   | `bitable:app:readonly` | Bitable read access | Optional |
+
+5. Go to **Security Settings**, add the OAuth callback URL to the **Redirect URLs** allowlist:
+   - Default: `http://localhost:3456/callback`
+   - This must match exactly what you use during `feishu-docs login`
+
+6. **Publish the app version**: Go to **App Release** → **Create Version** → Submit for review → Approve (self-built apps in your org are usually auto-approved)
+
+> **Note**: For tenant-level access (e.g., CI/CD), the app must be granted access to specific docs or knowledge bases. Add the app as a collaborator, or use the admin console to authorize document scope.
+
+### 2. Set Environment Variables
+
+```bash
+export FEISHU_APP_ID="cli_xxx"        # From step 3 above
+export FEISHU_APP_SECRET="xxx"         # From step 3 above
+```
+
+### 3. Login (for user-level access)
+
+User-level access enables personal docs, search, and collaboration features.
+
+```bash
+feishu-docs login
+```
+
+This opens a browser for OAuth authorization and saves the encrypted token to `~/.feishu-docs/auth.json`.
+
+If your app's registered redirect URL differs from the default (`http://localhost:3456/callback`), pass the exact same value:
+
+```bash
+# Match the exact redirect URI registered in Feishu Open Platform
+feishu-docs login --redirect-uri http://127.0.0.1:3456/callback
+
+# Or change only the port and keep the default localhost path
+feishu-docs login --port 4567
+```
+
+## Usage
+
+### Read
+
+```bash
+# Read document as Markdown
+feishu-docs read https://xxx.feishu.cn/wiki/wikcnXXX
+
+# Read by token
+feishu-docs read wikcnXXX
+
+# Raw Block JSON (lossless)
+feishu-docs read <url> --blocks
+
+# Plain text only
+feishu-docs read <url> --raw
+
+# With metadata header
+feishu-docs read <url> --with-meta
+```
+
+### Knowledge Base
+
+```bash
+# List all knowledge bases
+feishu-docs spaces
+
+# Show node tree
+feishu-docs tree <space_id>
+feishu-docs tree <space_id> --depth 2
+
+# Recursively read all documents
+feishu-docs cat <space_id> --max-docs 20
+feishu-docs cat <space_id> --node <token> --title-only
+```
+
+### Search
+
+```bash
+feishu-docs search "API design" --type docx --limit 10
+```
+
+Requires user access token. Use `feishu-docs login` first.
+
+### Create
+
+```bash
+# In knowledge base
+feishu-docs create "API Docs" --wiki <space_id> --body ./api.md
+
+# In cloud folder
+feishu-docs create "API Docs" --folder <folder_token> --body ./api.md
+
+# Empty document
+feishu-docs create "API Docs"
+
+# From stdin
+cat design.md | feishu-docs create "Design" --wiki <space_id> --body -
+```
+
+### Update
+
+```bash
+# Overwrite (backs up first)
+feishu-docs update <url> --body ./updated.md
+
+# Append
+feishu-docs update <url> --body ./extra.md --append
+
+# From stdin
+echo "## New Section" | feishu-docs update <url> --body - --append
+
+# Restore from backup
+feishu-docs update <url> --restore ~/.feishu-docs/backups/xxx.json
+```
+
+### Delete
+
+```bash
+feishu-docs delete <url> --confirm
+```
+
+Moves document to recycle bin (recoverable for 30 days).
+
+### Info
+
+```bash
+feishu-docs info <url|token>
+feishu-docs info <url> --json
+```
+
+### List Files
+
+```bash
+# List root folder
+feishu-docs ls
+
+# List specific folder
+feishu-docs ls <folder_token>
+
+# Filter by type
+feishu-docs ls --type docx --limit 20
+```
+
+### Share
+
+```bash
+# List collaborators
+feishu-docs share list <url>
+
+# Add collaborator
+feishu-docs share add <url> user@example.com --role view
+feishu-docs share add <url> ou_xxx --role edit
+
+# Set public sharing mode
+feishu-docs share set <url> --public tenant          # org-wide readable
+feishu-docs share set <url> --public tenant:edit      # org-wide editable
+feishu-docs share set <url> --public open             # anyone readable
+feishu-docs share set <url> --public closed           # disable link sharing
+```
+
+Roles: `view`, `edit`, `manage`. Member types are auto-detected (email, openid, unionid, openchat, userid).
+
+### Auth
+
+```bash
+feishu-docs login          # OAuth login (default callback: http://localhost:3456/callback)
+feishu-docs logout         # Clear saved credentials
+feishu-docs whoami         # Show current auth status
+```
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--auth <user\|tenant\|auto>` | Auth mode (default: auto) |
+| `--json` | Output JSON format |
+| `--lark` | Use Lark (international) domain |
+| `--help` | Show help |
+
+## Auth Modes
+
+| Mode | Token Type | Use Case |
+|------|-----------|----------|
+| `user` | user_access_token | Personal docs, collaboration, search |
+| `tenant` | tenant_access_token | App-managed docs, CI/CD |
+| `auto` | Best available | Default — tries user first, falls back to tenant |
+
+## AI Agent Integration
+
+### Claude Code (CLAUDE.md)
+
+```markdown
+## Feishu Docs
+
+Read/write Feishu docs with feishu-docs-cli.
+
+Read:     feishu-docs read <url>
+Search:   feishu-docs search <keyword>
+Tree:     feishu-docs tree <space_id>
+Batch:    feishu-docs cat <space_id> --max-docs 10
+Create:   feishu-docs create <title> --wiki <space_id> --body <file>
+Update:   feishu-docs update <url> --body <file>
+
+Env vars FEISHU_APP_ID and FEISHU_APP_SECRET are in .env.
+Run `feishu-docs login` first.
+```
+
+### Programmatic Usage
+
+All commands output to stdout (results) and stderr (errors/warnings). Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Invalid args |
+| 2 | Auth failure |
+| 3 | API error |
+
+Use `--json` for structured output that agents can parse.
+
+## Write Safety
+
+Overwrite operations (`update` without `--append`) automatically:
+
+1. **Back up** current document to `~/.feishu-docs/backups/`
+2. **Clear** then **rewrite** the document
+3. **Auto-recover** from backup if write fails
+4. **Rotate** backups (keeps last 10)
+
+Feishu also maintains version history — you can always roll back in the Feishu client.
+
+## Development
+
+```bash
+git clone https://github.com/cliff-byte/feishu-docs-cli.git
+cd feishu-docs-cli
+npm install
+
+# Type check
+npm run build:check
+
+# Build (outputs to dist/)
+npm run build
+
+# Run tests
+npm test
+
+# Run CLI from source
+npm run build && node bin/feishu-docs.js --help
+```
+
+### Project Structure
+
+```
+src/
+  types/          # Shared TypeScript type definitions
+  commands/       # CLI command handlers
+  services/       # API service layer
+  parser/         # Block-to-Markdown parser
+  utils/          # Validation, error handling, URL parsing
+test/             # Unit tests (node:test)
+bin/              # CLI entry point (JS shim → dist/)
+dist/             # Compiled output (git-ignored)
+```
+
+## Roadmap
+
+- [x] Feishu cloud document operations (read, create, update, delete, info)
+- [x] Knowledge base operations (spaces, tree, cat, wiki management, share, search)
+- [ ] Feishu Bitable (multi-dimensional table) operations
+- [ ] Feishu Sheets (spreadsheet) operations
+
+## Limitations
+
+- **Supported**: docx (new documents)
+- **Link only**: sheet, bitable, mindnote, board
+- **Not supported**: doc (legacy format)
+- Markdown conversion is lossy (colors, merged cells, layouts are dropped). Use `--blocks` for lossless JSON.
+- Image write is not supported (read returns temporary URLs valid ~24h)
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,332 @@
+# feishu-docs-cli
+
+[English](./README.md)
+
+让 AI Agent（Claude Code、Codex、Trae 等）通过 shell 命令读写飞书云文档和知识库。
+
+## 功能
+
+- **读取** 文档，输出 Markdown、纯文本或原始 Block JSON
+- **创建** 文档到知识库或云空间文件夹
+- **更新** 文档，支持覆盖写入或追加模式
+- **删除** 文档（移至回收站）
+- **详情** — 查看文档元信息（标题、类型、URL、版本号）
+- **浏览** 知识库结构（空间列表、目录树、批量读取）
+- **搜索** 按关键词搜索文档
+- **分享** — 管理协作者（列表、添加、设置公开权限）
+- **文件列表** — 浏览云空间文件夹
+- 使用 TypeScript 编写，严格模式
+- 零额外运行时依赖 — 仅依赖 `@larksuiteoapi/node-sdk`
+- Agent 友好输出 — 纯文本或 JSON，无交互式 UI
+
+## 安装
+
+```bash
+npm install -g github:cliff-byte/feishu-docs-cli
+```
+
+或通过 npx 直接运行：
+
+```bash
+npx github:cliff-byte/feishu-docs-cli read <url>
+```
+
+需要 Node.js >= 18.3。
+
+## 配置
+
+### 1. 创建飞书应用
+
+1. 前往[飞书开放平台](https://open.feishu.cn/app)，点击 **创建企业自建应用**，填写应用名称和描述
+2. 创建完成后，进入应用的 **凭证与基础信息** 页面，复制 **App ID**（`cli_xxx`）和 **App Secret** — 后续配置环境变量需要用到
+3. 进入 **权限管理**，搜索并添加以下权限：
+
+   | 权限 | 说明 | 是否必需 |
+   |------|------|----------|
+   | `wiki:wiki` | 知识库访问 | 是 |
+   | `docx:document` | 文档读写 | 是 |
+   | `docx:document.block:convert` | Markdown 转 Block | 是（创建/更新需要） |
+   | `drive:drive` | 文件管理和权限管理 | 是 |
+   | `contact:contact.base:readonly` | 用户名解析（@提及） | 推荐 |
+   | `board:whiteboard:node:read` | 白板内容读取 | 可选 |
+   | `bitable:app:readonly` | 多维表格只读 | 可选 |
+
+4. 进入 **安全设置**，在 **重定向 URL** 白名单中添加 OAuth 回调地址：
+   - 默认值：`http://localhost:3456/callback`
+   - 该地址必须与 `feishu-docs login` 使用的值完全一致
+
+5. **发布应用版本**：进入 **应用发布** → **创建版本** → 提交审核 → 审核通过（企业自建应用通常自动通过）
+
+> **提示**：使用 tenant（应用）身份访问文档时（如 CI/CD 场景），需要将应用添加为文档或知识库的协作者，或通过管理后台授权文档范围。
+
+### 2. 设置环境变量
+
+```bash
+export FEISHU_APP_ID="cli_xxx"        # 上面第 2 步获取的 App ID
+export FEISHU_APP_SECRET="xxx"         # 上面第 2 步获取的 App Secret
+```
+
+### 3. 登录（获取用户级别访问权限）
+
+用户级别访问支持个人文档、搜索和协作等功能。
+
+```bash
+feishu-docs login
+```
+
+执行后会打开浏览器进行 OAuth 授权，token 加密保存到 `~/.feishu-docs/auth.json`。
+
+如果应用注册的重定向 URL 与默认值（`http://localhost:3456/callback`）不同，需要传入完全一致的值：
+
+```bash
+# 使用与飞书开放平台注册的完全一致的重定向 URI
+feishu-docs login --redirect-uri http://127.0.0.1:3456/callback
+
+# 或仅更改端口，保持默认的 localhost 路径
+feishu-docs login --port 4567
+```
+
+## 使用
+
+### 读取
+
+```bash
+# 读取文档，输出 Markdown
+feishu-docs read https://xxx.feishu.cn/wiki/wikcnXXX
+
+# 通过 token 读取
+feishu-docs read wikcnXXX
+
+# 原始 Block JSON（无损）
+feishu-docs read <url> --blocks
+
+# 纯文本
+feishu-docs read <url> --raw
+
+# 带元信息头
+feishu-docs read <url> --with-meta
+```
+
+### 知识库
+
+```bash
+# 列出所有知识库
+feishu-docs spaces
+
+# 查看目录树
+feishu-docs tree <space_id>
+feishu-docs tree <space_id> --depth 2
+
+# 递归读取所有文档
+feishu-docs cat <space_id> --max-docs 20
+feishu-docs cat <space_id> --node <token> --title-only
+```
+
+### 搜索
+
+```bash
+feishu-docs search "API 设计" --type docx --limit 10
+```
+
+需要用户级别 token，请先执行 `feishu-docs login`。
+
+### 创建
+
+```bash
+# 在知识库中创建
+feishu-docs create "API 文档" --wiki <space_id> --body ./api.md
+
+# 在云空间文件夹中创建
+feishu-docs create "API 文档" --folder <folder_token> --body ./api.md
+
+# 创建空文档
+feishu-docs create "API 文档"
+
+# 从标准输入读取
+cat design.md | feishu-docs create "设计文档" --wiki <space_id> --body -
+```
+
+### 更新
+
+```bash
+# 覆盖写入（自动备份）
+feishu-docs update <url> --body ./updated.md
+
+# 追加内容
+feishu-docs update <url> --body ./extra.md --append
+
+# 从标准输入读取
+echo "## 新章节" | feishu-docs update <url> --body - --append
+
+# 从备份恢复
+feishu-docs update <url> --restore ~/.feishu-docs/backups/xxx.json
+```
+
+### 删除
+
+```bash
+feishu-docs delete <url> --confirm
+```
+
+将文档移至回收站（30 天内可恢复）。
+
+### 详情
+
+```bash
+feishu-docs info <url|token>
+feishu-docs info <url> --json
+```
+
+### 文件列表
+
+```bash
+# 列出根目录
+feishu-docs ls
+
+# 列出指定文件夹
+feishu-docs ls <folder_token>
+
+# 按类型筛选
+feishu-docs ls --type docx --limit 20
+```
+
+### 分享
+
+```bash
+# 查看协作者
+feishu-docs share list <url>
+
+# 添加协作者
+feishu-docs share add <url> user@example.com --role view
+feishu-docs share add <url> ou_xxx --role edit
+
+# 设置公开分享模式
+feishu-docs share set <url> --public tenant          # 组织内可读
+feishu-docs share set <url> --public tenant:edit      # 组织内可编辑
+feishu-docs share set <url> --public open             # 互联网可读
+feishu-docs share set <url> --public closed           # 关闭链接分享
+```
+
+角色：`view`（查看）、`edit`（编辑）、`manage`（管理）。成员类型自动识别（邮箱、openid、unionid、openchat、userid）。
+
+### 认证
+
+```bash
+feishu-docs login          # OAuth 登录（默认回调：http://localhost:3456/callback）
+feishu-docs logout         # 清除保存的凭证
+feishu-docs whoami         # 查看当前认证状态
+```
+
+## 全局选项
+
+| 选项 | 说明 |
+|------|------|
+| `--auth <user\|tenant\|auto>` | 认证模式（默认：auto） |
+| `--json` | JSON 格式输出 |
+| `--lark` | 使用 Lark（国际版）域名 |
+| `--help` | 显示帮助 |
+
+## 认证模式
+
+| 模式 | Token 类型 | 适用场景 |
+|------|-----------|----------|
+| `user` | user_access_token | 个人文档、协作、搜索 |
+| `tenant` | tenant_access_token | 应用管理的文档、CI/CD |
+| `auto` | 自动选择最佳 | 默认 — 优先用户 token，回退到租户 token |
+
+## AI Agent 集成
+
+### Claude Code (CLAUDE.md)
+
+```markdown
+## 飞书文档
+
+通过 feishu-docs-cli 读写飞书文档。
+
+读取:     feishu-docs read <url>
+搜索:     feishu-docs search <关键词>
+目录树:   feishu-docs tree <space_id>
+批量读取: feishu-docs cat <space_id> --max-docs 10
+创建:     feishu-docs create <标题> --wiki <space_id> --body <文件>
+更新:     feishu-docs update <url> --body <文件>
+
+环境变量 FEISHU_APP_ID 和 FEISHU_APP_SECRET 在 .env 中。
+先执行 `feishu-docs login` 登录。
+```
+
+### 程序化调用
+
+所有命令输出到 stdout（结果）和 stderr（错误/警告）。退出码：
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 成功 |
+| 1 | 参数错误 |
+| 2 | 认证失败 |
+| 3 | API 错误 |
+
+使用 `--json` 获取结构化输出，便于 Agent 解析。
+
+## 写入安全
+
+覆盖写入（`update` 不带 `--append`）自动执行：
+
+1. **备份** 当前文档到 `~/.feishu-docs/backups/`
+2. **清空** 后 **重写** 文档
+3. 写入失败时 **自动恢复** 备份
+4. **轮转** 备份文件（保留最近 10 份）
+
+飞书本身也维护版本历史 — 你随时可以在飞书客户端中回滚。
+
+## 开发
+
+```bash
+git clone https://github.com/cliff-byte/feishu-docs-cli.git
+cd feishu-docs-cli
+npm install
+
+# 类型检查
+npm run build:check
+
+# 构建（输出到 dist/）
+npm run build
+
+# 运行测试
+npm test
+
+# 从源码运行
+npm run build && node bin/feishu-docs.js --help
+```
+
+### 项目结构
+
+```
+src/
+  types/          # 共享 TypeScript 类型定义
+  commands/       # CLI 命令处理器
+  services/       # API 服务层
+  parser/         # Block 转 Markdown 解析器
+  utils/          # 校验、错误处理、URL 解析
+test/             # 单元测试（node:test）
+bin/              # CLI 入口（JS shim → dist/）
+dist/             # 编译输出（不提交到 git）
+```
+
+## 路线图
+
+- [x] 飞书云文档操作（读取、创建、更新、删除、详情）
+- [x] 知识库操作（空间列表、目录树、批量读取、Wiki 管理、分享、搜索）
+- [ ] 飞书多维表格操作
+- [ ] 飞书电子表格操作
+
+## 限制
+
+- **支持**：docx（新版文档）
+- **仅链接**：sheet、bitable、mindnote、board
+- **不支持**：doc（旧版格式）
+- Markdown 转换有损（颜色、合并单元格、布局会丢失）。使用 `--blocks` 获取无损 JSON。
+- 不支持图片写入（读取返回约 24 小时有效的临时 URL）
+
+## 许可证
+
+MIT

package/bin/feishu-docs.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { run } from "../dist/cli.js";
+
+run(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`feishu-docs: fatal: ${err.message}\n`);
+  process.exit(err.exitCode ?? 1);
+});