Metadata-Version: 2.4
Name: workflow-cli
Version: 0.6.19
Summary: 公司工作流 CLI 工具 —— 提升日常工作效率
Author-email: TODO <TODO@example.com>
License-Expression: MIT
Project-URL: Homepage, https://gitee.com/fang-shaopeng/share-file-repository/blob/master/workflow-cli-mcp-readme.md
Project-URL: Repository, https://gitee.com/fang-shaopeng/share-file-repository
Project-URL: Issues, https://gitee.com/fang-shaopeng/share-file-repository/issues
Keywords: cli,workflow,feishu,lark
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: mcp>=1.0
Provides-Extra: toml
Requires-Dist: tomli>=2.0; extra == "toml"
Requires-Dist: tomli-w>=1.0; extra == "toml"
Dynamic: license-file

# wf-cli

公司工作流 CLI 工具 —— 提升日常工作效率的命令行助手。

## 功能

| 命令 | 说明 |
|------|------|
| `wf-cli workspace` | 管理工作空间（创建/下载/新增文档类型/更新模板） |
| `wf-cli doc` | 基于模板交互式生成文档 |
| `wf-cli sync` | 与飞书云盘双向同步文件 |
| `wf-cli config` | 查看和修改 CLI 配置 |
| `wf-cli info` | 显示版本和当前工作环境状态 |

## 环境要求

- **Python >= 3.10**（未安装请参考下方指引）
- **Node.js**（lark-cli 依赖 npm 安装）

### Python 安装指引

**检查是否已安装：**

```bash
python3 --version
# 或 Windows 上：
python --version
```

**如果未安装或版本低于 3.10：**

| 平台 | 安装方式 |
|------|---------|
| **macOS** | `brew install python@3.13`（推荐）或从 [python.org](https://www.python.org/downloads/) 下载安装包 |
| **Windows** | 从 [python.org](https://www.python.org/downloads/) 下载安装包，**安装时勾选「Add Python to PATH」** |
| **Linux** | `sudo apt install python3.13`（Ubuntu/Debian）或 `sudo dnf install python3.13`（Fedora） |

> 💡 推荐安装 Python 3.11+，可直接使用内置的 `tomllib`，无需额外依赖。

---

## 第一步：安装 workflow-cli

### macOS（推荐 pipx）

```bash
# 安装 pipx（如果没有）
brew install pipx
pipx ensurepath

# 安装或升级 workflow-cli（已安装则升级到最新版）
pipx install workflow-cli || pipx upgrade workflow-cli
```

### Windows

```bash
# 方式一：安装或升级（已安装则升级到最新版）
pip install --upgrade workflow-cli

# 如果提示 wf-cli 命令找不到，将以下路径加入系统 PATH：
# C:\Users\用户名\AppData\Roaming\Python\Python3xx\Scripts
```

### Linux（推荐 pipx）

```bash
# 安装 pipx（如果没有）
sudo apt install pipx
pipx ensurepath

# 安装或升级 workflow-cli（已安装则升级到最新版）
pipx install workflow-cli || pipx upgrade workflow-cli
```

### 通用方式（虚拟环境）

```bash
pip install workflow-cli
```

### 其他常用命令

| 操作 | pipx | pip |
|------|------|-----|
| 安装 | `pipx install workflow-cli` | `pip install workflow-cli` |
| 升级 | `pipx upgrade workflow-cli` | `pip install --upgrade workflow-cli` |
| 卸载 | `pipx uninstall workflow-cli` | `pip uninstall workflow-cli` |
| 查看信息 | `pipx list` | `pip show workflow-cli` |

> 💡 MCP 依赖现已默认包含，`pip install workflow-cli` 即可，无需额外 `[mcp]`。安装后会自动生成 `~/.wfcli/config.toml`。

---

## ⚠️ 第二步：安装并配置飞书 CLI

**workflow-cli 的飞书云盘功能依赖 `lark-cli`，没有它 workspace/sync 等命令无法使用。**

### 2.1 安装 lark-cli

```bash
npm install -g lark-cli
```

详细安装指南：https://open.feishu.cn/document/no_class/mcp-archive/feishu-cli-installation-guide.md

### 2.2 配置并授权（只需一次）

> 先运行 `wf-cli config show` 确认 `~/.wfcli/config.toml` 已生成。

**Step 1 — 初始化 lark-cli（创建飞书应用）：**

```bash
lark-cli config init --new
```

该命令会输出一个验证 URL，复制在浏览器中打开完成飞书登录，配置自动完成。

**Step 2 — 授权云盘权限：**

```bash
lark-cli auth login --domain drive
```

浏览器中确认云盘权限即可。需要的权限范围见 `~/.wfcli/config.toml` 的 `[feishu.scopes]` 段。

### 2.3 验证

```bash
lark-cli auth status
lark-cli auth scopes
```

---

## 第三步：同步云盘工作空间到本地

lark-cli 授权成功后，将飞书云盘上的工作空间下载到本地：

```bash
wf-cli workspace pull
```

> 💡 下载完成后就可以开始写文档了：`wf-cli doc generate`

## AI 应用 MCP 集成

安装后，`wf-cli` 可以作为一个 MCP Server 被 AI 应用（Claude Desktop、WorkBuddy 等）调用，让 AI 直接操作飞书工作空间和文档。

### 安装

| 平台 | 命令 |
|------|------|
| **macOS (pipx)** | `pipx install workflow-cli` |
| **Windows (pip)** | `pip install workflow-cli` |

### 获取 wf-cli-mcp 路径

AI 应用配置需要知道 `wf-cli-mcp` 命令的完整路径。

**macOS (pipx)：**

```bash
# 查找路径
which wf-cli-mcp
# 通常是: /Users/<用户名>/.local/bin/wf-cli-mcp
```

**macOS (pip/venv)：**

```bash
# 在虚拟环境中
which wf-cli-mcp
# 通常在: <venv目录>/bin/wf-cli-mcp
```

**Windows (pip)：**

```powershell
where wf-cli-mcp
# 通常是: C:\Users\<用户名>\AppData\Roaming\Python\Python3xx\Scripts\wf-cli-mcp.exe
```

### 配置 AI 应用

将以下 JSON 添加到对应应用的 MCP 配置中（注意替换路径）：

#### Claude Desktop

打开 Claude Desktop → Settings → Developer → Edit Config，添加：

```json
{
  "mcpServers": {
    "workflow-cli": {
      "command": "/Users/<用户名>/.local/bin/wf-cli-mcp",
      "args": []
    }
  }
}
```

**Windows 用户**注意：路径用 `\\` 或单个 `/`：

```json
{
  "mcpServers": {
    "workflow-cli": {
      "command": "C:/Users/<用户名>/AppData/Roaming/Python/Python314/Scripts/wf-cli-mcp.exe",
      "args": []
    }
  }
}
```

#### WorkBuddy

与 Claude Desktop 格式相同，填入 WorkBuddy 的 MCP 配置面板。

#### Cursor / VS Code

在项目根目录创建 `.cursor/mcp.json` 或 `.vscode/mcp.json`：

```json
{
  "mcpServers": {
    "workflow-cli": {
      "command": "/Users/<用户名>/.local/bin/wf-cli-mcp",
      "args": []
    }
  }
}
```

### 可用 MCP Tools

配置成功后，AI 应用可以使用以下工具：

| Tool | 功能 |
|------|------|
| `workspace_list` | 列出云盘所有工作空间 |
| `workspace_create` | 创建新工作空间（含目录和模板） |
| `workspace_pull` | 下载工作空间到本地 |
| `doc_list_types` | 列出工作空间可用的文档类型 |
| `doc_get_template` | 获取模板结构、AI 执行指令和自检清单 |
| `doc_generate` | 将 AI 生成的文档保存到工作空间 |
| `sync_push` | 提交本地文件到云盘 |
| `sync_pull` | 从云盘同步更新到本地 |
| `sync_status` | 查看本地与云盘的同步差异 |
| `config_show` | 查看当前配置 |
| `get_info` | 显示版本、Python 环境和 lark-cli 状态 |

### 验证 MCP 是否正常

```bash
# 查看帮助（确保 mcp 子命令存在）
wf-cli mcp --help

# 用 MCP Inspector 测试（需要 Node.js）
npx @modelcontextprotocol/inspector wf-cli-mcp
```

## 快速开始

### 基础命令

| 操作 | macOS/Linux | Windows |
|------|------------|---------|
| 查看帮助 | `wf-cli --help` | `wf-cli --help` |
| 查看版本 | `wf-cli --version` | `wf-cli --version` |
| 查看状态 | `wf-cli info` | `wf-cli info` |

### 配置

| 操作 | macOS/Linux | Windows |
|------|------------|---------|
| 查看配置 | `wf-cli config show` | `wf-cli config show` |
| 修改飞书 token | `wf-cli config set feishu.root_folder_token <token>` | `wf-cli config set feishu.root_folder_token <token>` |

### 工作空间

| 操作 | macOS/Linux | Windows |
|------|------------|---------|
| 列出云盘工作空间 | `wf-cli workspace list` | `wf-cli workspace list` |
| 下载到本地 | `wf-cli workspace pull` | `wf-cli workspace pull` |
| 创建工作空间 | `wf-cli workspace create <名称>` | `wf-cli workspace create <名称>` |

### 文档

| 操作 | macOS/Linux | Windows |
|------|------------|---------|
| 生成文档 | `wf-cli doc generate` | `wf-cli doc generate` |
| 查看可用类型 | `wf-cli doc list` | `wf-cli doc list` |

### 同步

| 操作 | macOS/Linux | Windows |
|------|------------|---------|
| 提交到云盘 | `wf-cli sync push <文件>` | `wf-cli sync push <文件>` |
| 从云盘更新 | `wf-cli sync pull` | `wf-cli sync pull` |
| 查看同步状态 | `wf-cli sync status` | `wf-cli sync status` |

## 配置

配置文件位于 `~/.wfcli/config.toml`（TOML 格式），首次运行时自动生成默认配置。

可配置项：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `feishu.root_folder_token` | 飞书云盘工作空间根目录 token | 已预设 |
| `workspace.default_local_dir` | 默认本地下载路径 | `~/workspaces` |
| `update.enabled` | 是否启用自动更新 | `true` |
| `update.check_interval_days` | 更新检查间隔（天） | `1` |

## Python 3.10 用户注意

Python 3.10 不内置 `tomllib`，请安装时带上 `toml` 额外依赖：

```bash
pip install workflow-cli[toml]
```

Python 3.11+ 用户无需额外操作。

## 许可证

MIT
