feishu-project-cli

飞书项目 CLI 工具 — 通过命令行操作飞书项目空间的工作项，支持查询、搜索、筛选、文件上传等功能。

为什么用 CLI 而不是网页版？

| 场景 | 网页版 | CLI | |------|--------|-----| | 批量查看某类工作项 | 手动翻页，逐个点击 | list-items --type bug --all 一键导出 | | 跨类型关联查询 | 需要在多个页面之间跳转 | list-related <ID> 直接查看关联 | | 数据导出分析 | 手动复制或导出 Excel | --format csv 直接管道到其他工具 | | 自动化 / CI 集成 | 不支持 | 所有命令支持脚本调用 | | 与 AI 工具集成 | 不支持 | 支持 MCP 协议，可与 Claude 等 AI 工具联动 |

典型使用场景：

• 产品经理：快速查看迭代进度、需求池状态、用户故事工作流
• 开发工程师：查看任务列表、关联缺陷、工作项详情
• 测试工程师：批量查看缺陷、按优先级搜索、统计状态分布
• 运维 / DevOps：查看线上更新记录、工单列表、发布版本

安装

方式一：npx 直接使用（推荐）

npx feishu-project-cli setup
npx feishu-project-cli list-types

方式二：全局安装

npm install -g feishu-project-cli
feishu-project setup

方式三：从源码构建

git clone <repo-url> && cd feishu-project-cli
npm install
npm run build
npm link   # 可选：链接为全局命令

配置

管理员首次配置

feishu-project setup

向导会引导你创建插件、验证凭据、选择用户身份。完成后会显示团队成员接入所需的信息。

团队成员快速接入

管理员完成配置后，将 Plugin ID / Secret / Project Key 发给成员，成员运行：

feishu-project setup --join

只需输入管理员提供的凭据，然后从团队列表中选择自己即可。

CI/CD 非交互模式

export FEISHU_PROJECT_KEY=my-project
export FEISHU_PLUGIN_ID=MII_xxx
export FEISHU_PLUGIN_SECRET=xxx
export FEISHU_USER_KEY=xxx
feishu-project setup --env

配置文件位置

配置按以下优先级加载：环境变量 > 项目级 .env > 全局配置

| 位置 | 路径 | 说明 | |------|------|------| | 全局配置 | ~/.feishu-project/config | setup 向导写入，所有目录通用 | | 项目级覆盖 | 当前目录 .env | 可选，覆盖全局配置中的同名项 | | 环境变量 | - | 最高优先级，适合 CI/CD |

手动配置

详细的凭据获取步骤请参考 配置指南。

| 环境变量 | 说明 | |---------|------| | FEISHU_BASE_URL | 飞书项目地址，默认 https://project.feishu.cn | | FEISHU_PROJECT_KEY | 项目空间 key | | FEISHU_PLUGIN_ID | 插件 ID | | FEISHU_PLUGIN_SECRET | 插件 Secret | | FEISHU_USER_KEY | 用户 key | | MCP_USER_TOKEN | MCP 用户令牌（可选，用于 Claude 集成） |

诊断问题

feishu-project doctor

自动检查配置文件、凭据有效性、网络连通性和 API 访问权限，并给出修复建议。

使用

# 开发模式
npm run dev -- <command> [options]

# 构建后
feishu-project <command> [options]

全局选项

| 选项 | 说明 | 默认值 | |------|------|-------| | --project-key <key> | 覆盖 .env 中的项目空间 key | .env 中的值 | | --format <type> | 输出格式：json / table / csv | json | | --verbose | 详细输出（含 API 请求日志） | false |

命令

setup — 交互式配置向导

feishu-project setup [options]

| 选项 | 说明 | |------|------| | --join | 成员快速接入模式（管理员已提供凭据） | | --env | 从环境变量生成 .env（CI/CD 非交互模式） | | --force | 跳过已有配置的覆盖确认 | | --skip-verify | 跳过凭据验证 |

doctor — 诊断配置和连接

feishu-project doctor

检查配置文件、凭据有效性、网络连通性、API 访问权限，并给出修复建议。

list-types — 列出工作项类型

feishu-project list-types

list-teams — 列出团队成员

feishu-project list-teams

list-items — 列出工作项

feishu-project list-items --type <type> [options]

| 选项 | 说明 | |------|------| | --type <type> | 必填 工作项类型，支持 api_name 或中文别名 | | --tags <tags> | 标签过滤，逗号分隔 | | --status <status> | 状态过滤（state_key） | | --name <name> | 名称模糊搜索 | | --page <n> | 页码，默认 1 | | --size <n> | 每页条数，默认 50 | | --all | 自动分页获取全部数据 |

示例：

# 列出所有用户故事
feishu-project list-items --type 故事 --all

# 按状态筛选缺陷
feishu-project list-items --type bug --status resolved

# 表格格式输出
feishu-project list-items --type 任务 --format table

get-item <id> — 获取工作项详情

feishu-project get-item <id> --type <type> [--expand <fields>]

--expand 支持：workflow（默认）、multi_text、relations，逗号分隔。

get-workflow <id> — 查看工作流状态与排期

feishu-project get-workflow <id> --type <type>

返回工作流各节点的状态（未开始/进行中/已完成）、负责人、排期和实际完成时间。

search — 按字段搜索工作项

feishu-project search --type <type> --field <field_key> --value <value> [--operator <op>]

--operator 支持：=（默认）、!=、>、<、contains。

list-related <id> — 获取关联工作项

feishu-project list-related <id> --type <type>

查看工作项的关联关系（如合同→回款、bug→故事等）。

list-states — 列出状态分布

feishu-project list-states --type <type> [--sample-size <n>]

通过采样发现该类型下所有可能的状态及其分布，默认采样 500 条。

upload-file — 上传文件到工作项

feishu-project upload-file --type <type> --id <id> --field <field_key> --url <file_url>

支持的工作项类型

类型参数支持 api_name 和中文别名：

| 中文别名 | api_name | 说明 | |---------|----------|------| | 用户故事 / 故事 | story | 用户故事 | | 缺陷 / bug | issue | Bugs | | 工单 | workorder | 工单 | | 迭代 | sprint | 迭代 | | 史诗 | system_epic | 史诗 | | 特性 | characteristic_ | 特性 | | 发布版本 / 版本 | version | 发布版本 | | 线上更新 / 线上系统更新 | update | 线上系统更新 | | 任务 | sub_task | 任务 | | 需求池 | backlog | 需求池 | | 测试计划 | test_plans | 测试计划 | | 用例管理 | test_cases_set | 用例管理 | | 客户 | client | 客户 | | 合同 | contract | 合同 | | 回款 | refund | 回款 |

项目结构

src/
├── cli.ts                  # 入口，注册所有命令
├── config.ts               # 环境变量、类型映射、别名解析
├── formatter.ts            # 输出格式化（json/table/csv）
├── types.ts                # TypeScript 类型定义
├── commands/
│   ├── setup.ts            # 交互式配置向导
│   ├── doctor.ts           # 诊断配置和连接
│   ├── list-types.ts       # 列出工作项类型
│   ├── list-teams.ts       # 列出团队成员
│   ├── list-items.ts       # 列出工作项（筛选/分页）
│   ├── list-states.ts      # 列出状态分布
│   ├── list-related.ts     # 获取关联工作项
│   ├── get-item.ts         # 获取工作项详情
│   ├── get-workflow.ts     # 查看工作流状态
│   ├── search.ts           # 按字段搜索
│   └── upload-file.ts      # 上传文件
├── services/
│   └── api-client.ts       # 飞书 API 客户端（认证、请求、分页、缓存）
└── utils/
    ├── batch.ts            # 批量处理工具
    ├── cache.ts            # Token/数据缓存
    ├── config-path.ts      # 配置文件路径管理（全局/项目级）
    ├── prompt.ts           # 交互式输入工具
    └── quarter.ts          # 季度时间工具

开发

# 开发模式运行
npm run dev -- list-types --verbose

# 构建
npm run build

# 运行构建产物
npm start -- list-items --type story --all --format table

License

ISC