OpenProject（作者：@altf1be）

通过 OpenProject API v3 管理工作包（Work Packages）、项目（Projects）、用户组（Groups）、新闻（News）、用户（Users）、关注者（Watchers）、关联关系（Relations）、通知（Notifications）、工时记录（Time Entries）、评论（Comments）、附件（Attachments）、Wiki 页面（Wiki Pages）以及工作流状态转换（Workflow Transitions）。支持 OpenProject 云版与自托管实例。

配置步骤

1. 登录您的 OpenProject 实例
2. 进入 我的账户 → 访问令牌 → + 添加
3. 创建一个 API 令牌并复制该令牌
4. 设置环境变量（或在 {baseDir} 目录下创建 .env 文件）：

OP_HOST=https://projects.xflowdata.com
OP_API_TOKEN=your-api-token
OP_DEFAULT_PROJECT=my-project

5. 安装依赖项：cd {baseDir} && npm install

命令列表

工作包（Work Packages）

# 列出工作包（支持可选过滤器）
node {baseDir}/scripts/openproject.mjs wp-list --project my-project --status open --assignee me

# 创建工作包
node {baseDir}/scripts/openproject.mjs wp-create --project my-project --type Task --subject "修复登录 Bug" --description "用户无法登录"

# 查看工作包详情
node {baseDir}/scripts/openproject.mjs wp-read --id 42

# 更新工作包
node {baseDir}/scripts/openproject.mjs wp-update --id 42 --subject "新标题" --priority High

# 删除工作包（需指定 --confirm 参数）
node {baseDir}/scripts/openproject.mjs wp-delete --id 42 --confirm

项目（Projects）

# 列出所有项目
node {baseDir}/scripts/openproject.mjs project-list

# 查看项目详情
node {baseDir}/scripts/openproject.mjs project-read --id my-project

# 创建项目
node {baseDir}/scripts/openproject.mjs project-create --name "我的项目" --identifier my-project

评论（Activities）

# 列出某工作包下的所有评论
node {baseDir}/scripts/openproject.mjs comment-list --wp-id 42

# 添加评论
node {baseDir}/scripts/openproject.mjs comment-add --wp-id 42 --body "已就绪，待评审"

附件（Attachments）

# 列出某工作包下的所有附件
node {baseDir}/scripts/openproject.mjs attachment-list --wp-id 42

# 上传附件
node {baseDir}/scripts/openproject.mjs attachment-add --wp-id 42 --file ./screenshot.png

# 删除附件（需指定 --confirm 参数）
node {baseDir}/scripts/openproject.mjs attachment-delete --id 10 --confirm

工时记录（Time Entries）

# 列出工时记录
node {baseDir}/scripts/openproject.mjs time-list --project my-project

# 记录工时
node {baseDir}/scripts/openproject.mjs time-create --wp-id 42 --hours 2.5 --comment "代码评审" --activity-id 1

# 更新工时记录
node {baseDir}/scripts/openproject.mjs time-update --id 5 --hours 3 --comment "已更新"

# 删除工时记录（需指定 --confirm 参数）
node {baseDir}/scripts/openproject.mjs time-delete --id 5 --confirm

状态（Statuses）与状态转换（Transitions）

# 列出所有状态
node {baseDir}/scripts/openproject.mjs status-list

# 更新工作包状态
node {baseDir}/scripts/openproject.mjs wp-update --id 42 --status "进行中"

用户（Users）

# 列出所有用户（支持可选过滤器）
node {baseDir}/scripts/openproject.mjs user-list
node {baseDir}/scripts/openproject.mjs user-list --status active --name "John"

# 查看用户详情
node {baseDir}/scripts/openproject.mjs user-read --id 5

# 查看当前认证用户信息
node {baseDir}/scripts/openproject.mjs user-me

通知（Notifications）

# 列出通知（全部或仅未读）
node {baseDir}/scripts/openproject.mjs notification-list
node {baseDir}/scripts/openproject.mjs notification-list --unread
node {baseDir}/scripts/openproject.mjs notification-list --reason mentioned --project 5

# 查看通知详情
node {baseDir}/scripts/openproject.mjs notification-read --id 100

# 标记为已读（单条或全部）
node {baseDir}/scripts/openproject.mjs notification-mark-read --id 100
node {baseDir}/scripts/openproject.mjs notification-mark-read --all
node {baseDir}/scripts/openproject.mjs notification-mark-read --all --project 5

# 标记为未读
node {baseDir}/scripts/openproject.mjs notification-mark-unread --id 100
node {baseDir}/scripts/openproject.mjs notification-mark-unread --all

文档（Documents）

node {baseDir}/scripts/openproject.mjs document-list
node {baseDir}/scripts/openproject.mjs document-read --id 5
node {baseDir}/scripts/openproject.mjs document-update --id 5 --title "已更新的标题"

修订版本（Revisions）

node {baseDir}/scripts/openproject.mjs revision-read --id 10
node {baseDir}/scripts/openproject.mjs revision-list-by-wp --wp-id 42

能力（Capabilities）与操作（Actions）

node {baseDir}/scripts/openproject.mjs capability-list --principal me
node {baseDir}/scripts/openproject.mjs capability-global
node {baseDir}/scripts/openproject.mjs action-list
node {baseDir}/scripts/openproject.mjs action-read --id work_packages/create

我的偏好设置（My Preferences）

node {baseDir}/scripts/openproject.mjs my-preferences-read
node {baseDir}/scripts/openproject.mjs my-preferences-update --time-zone "Europe/Brussels" --comment-order desc

渲染（Render）

node {baseDir}/scripts/openproject.mjs render-markdown --text "**粗体** 和 _斜体_"
node {baseDir}/scripts/openproject.mjs render-plain --text "纯文本"

帖子（Posts，论坛）

node {baseDir}/scripts/openproject.mjs post-read --id 5
node {baseDir}/scripts/openproject.mjs post-attachment-list --id 5

提醒（Reminders）

node {baseDir}/scripts/openproject.mjs reminder-list
node {baseDir}/scripts/openproject.mjs reminder-create --wp-id 42 --remind-at "2026-03-20T09:00:00Z" --note "检查状态"
node {baseDir}/scripts/openproject.mjs reminder-update --id 3 --remind-at "2026-03-21T09:00:00Z"
node {baseDir}/scripts/openproject.mjs reminder-delete --id 3 --confirm

项目状态（Project Statuses）

node {baseDir}/scripts/openproject.mjs project-status-read --id on_track

项目阶段（Project Phases，企业版）

# 列出项目阶段定义
node {baseDir}/scripts/openproject.mjs project-phase-definition-list

# 查看某阶段定义
node {baseDir}/scripts/openproject.mjs project-phase-definition-read --id 1

# 查看某项目阶段
node {baseDir}/scripts/openproject.mjs project-phase-read --id 5

投资组合（Portfolios，企业版）

# 列出所有投资组合
node {baseDir}/scripts/openproject.mjs portfolio-list

# 查看某投资组合
node {baseDir}/scripts/openproject.mjs portfolio-read --id 1

# 更新某投资组合
node {baseDir}/scripts/openproject.mjs portfolio-update --id 1 --name "Q1 投资组合"

# 删除某投资组合（需指定 --confirm 参数）
node {baseDir}/scripts/openproject.mjs portfolio-delete --id 1 --confirm

项目集（Programs，企业版）

# 列出所有项目集
node {baseDir}/scripts/openproject.mjs program-list

# 查看某项目集
node {baseDir}/scripts/openproject.mjs program-read --id 1

# 更新某项目集
node {baseDir}/scripts/openproject.mjs program-update --id 1 --name "平台项目集"

# 删除某项目集（需指定 --confirm 参数）
node {baseDir}/scripts/openproject.mjs program-delete --id 1 --confirm

占位用户（Placeholder Users，企业版）

# 列出所有占位用户
node {baseDir}/scripts/openproject.mjs placeholder-user-list

# 查看某占位用户
node {baseDir}/scripts/openproject.mjs placeholder-user-read --id 10

# 创建占位用户
node {baseDir}/scripts/openproject.mjs placeholder-user-create --name "未来开发者"

# 更新占位用户
node {baseDir}/scripts/openproject.mjs placeholder-user-update --id 10 --name "高级开发者"

# 删除占位用户（需指定 --confirm 参数）
node {baseDir}/scripts/openproject.mjs placeholder-user-delete --id 10 --confirm

预算（Budgets，企业版）

# 列出某项目的预算
node {baseDir}/scripts/openproject.mjs budget-list --project my-project

# 查看预算详情
node {baseDir}/scripts/openproject.mjs budget-read --id 3

会议（Meetings，企业版）

# 查看某会议
node {baseDir}/scripts/openproject.mjs meeting-read --id 10

# 列出某会议的附件
node {baseDir}/scripts/openproject.mjs meeting-attachment-list --id 10

# 向会议上传附件
node {baseDir}/scripts/openproject.mjs meeting-attachment-add --id 10 --file ./agenda.pdf

工作日/非工作日（Days）

# 检查某日期是否为工作日
node {baseDir}/scripts/openproject.mjs day-read --date 2026-03-18

# 列出某时间段内的所有日期
node {baseDir}/scripts/openproject.mjs days-list --from 2026-03-01 --to 2026-03-31

# 列出所有非工作日（节假日）
node {baseDir}/scripts/openproject.mjs non-working-days-list

# 查看某非工作日详情
node {baseDir}/scripts/openproject.mjs non-working-day-read --date 2026-12-25

# 查看周工作日安排（哪些天为工作日）
node {baseDir}/scripts/openproject.mjs week-days-list

# 查看某特定星期几的配置
node {baseDir}/scripts/openproject.mjs week-day-read --day 6

配置（Configuration）

# 查看实例级配置
node {baseDir}/scripts/openproject.mjs config-read

# 查看项目级配置
node {baseDir}/scripts/openproject.mjs project-config-read --project my-project

OAuth

# 查看 OAuth 应用
node {baseDir}/scripts/openproject.mjs oauth-app-read --id 1

# 查看 OAuth 客户端凭据
node {baseDir}/scripts/openproject.mjs oauth-credentials-read --id 1

帮助文本（Help Texts）

# 列出所有属性的帮助文本
node {baseDir}/scripts/openproject.mjs help-text-list

# 查看某帮助文本
node {baseDir}/scripts/openproject.mjs help-text-read --id 1

自定义字段（Custom Fields）与选项（Options）

# 列出某层级式自定义字段的所有条目
node {baseDir}/scripts/openproject.mjs custom-field-items --id 10

# 查看某自定义字段条目
node {baseDir}/scripts/openproject.mjs custom-field-item-read --id 25

# 获取某自定义字段条目的分支（祖先节点）
node {baseDir}/scripts/openproject.mjs custom-field-item-branch --id 25

# 查看某自定义选项值
node {baseDir}/scripts/openproject.mjs custom-option-read --id 3

自定义操作（Custom Actions）

# 查看某自定义操作
node {baseDir}/scripts/openproject.mjs custom-action-read --id 1

# 在工作包上执行某自定义操作
node {baseDir}/scripts/openproject.mjs custom-action-execute --id 1 --wp-id 42

用户组（Groups）

# 列出所有用户组
node {baseDir}/scripts/openproject.mjs group-list

# 查看用户组详情（含成员列表）
node {baseDir}/scripts/openproject.mjs group-read --id 3

# 创建带成员的用户组
node {baseDir}/scripts/openproject.mjs group-create --name "开发团队" --members 5,6,7

# 更新用户组（将完全替换现有成员列表）
node {baseDir}/scripts/openproject.mjs group-update --id 3 --name "工程部" --members 5,6,7,8

# 删除用户组（需指定 --confirm 参数）
node {baseDir}/scripts/openproject.mjs group-delete --id 3 --confirm

新闻（News）

# 列出所有新闻
node {baseDir}/scripts/openproject.mjs news-list

# 查看新闻详情
node {baseDir}/scripts/openproject.mjs news-read --id 5

# 创建新闻条目
node {baseDir}/scripts/openproject.mjs news-create --project my-project --title "Sprint 12 已发布" --summary "Bug 修复与性能优化" --description "完整详情见此处..."

# 更新新闻条目
node {baseDir}/scripts/openproject.mjs news-update --id 5 --title "已更新的标题"

# 删除新闻条目（需指定 --confirm 参数）
node {baseDir}/scripts/openproject.mjs news-delete --id 5 --confirm

关注者（Watchers）

# 列出某工作包的关注者
node {baseDir}/scripts/openproject.mjs watcher-list --wp-id 42

# 添加关注者
node {baseDir}/scripts/openproject.mjs watcher-add --wp-id 42 --user-id 5

# 移除关注者
node {baseDir}/scripts/openproject.mjs watcher-remove --wp-id 42 --user-id 5

# 列出可作为关注者的用户
node {baseDir}/scripts/openproject.mjs watcher-available --wp-id 42

关联关系（Relations）

# 列出所有关联关系（可按工作包 ID 或类型筛选）
node {baseDir}/scripts/openproject.mjs relation-list --wp-id 42
node {baseDir}/scripts/openproject.mjs relation-list --type blocks

# 查看关联关系详情
node {baseDir}/scripts/openproject.mjs relation-read --id 5

# 创建关联关系（支持类型：relates、duplicates、blocks、precedes、follows、includes、partof、requires）
node {baseDir}/scripts/openproject.mjs relation-create --wp-id 42 --to-wp-id 43 --type blocks
node {baseDir}/scripts/openproject.mjs relation-create --wp-id 42 --to-wp-id 43 --type precedes --lag 2

# 更新关联关系
node {baseDir}/scripts/openproject.mjs relation-update --id 5 --type follows --lag 1

# 删除关联关系（需指定 --confirm 参数）
node {baseDir}/scripts/openproject.mjs relation-delete --id 5 --confirm

Wiki 页面（Wiki Pages）

# 查看 Wiki 页面
node {baseDir}/scripts/openproject.mjs wiki-read --id 72

# 列出 Wiki 页面的附件
node {baseDir}/scripts/openproject.mjs wiki-attachment-list --id 72

# 向 Wiki 页面上传附件
node {baseDir}/scripts/openproject.mjs wiki-attachment-add --id 72 --file ./diagram.png

参考数据（Reference Data）

# 列出工作包类型
node {baseDir}/scripts/openproject.mjs type-list

# 列出优先级
node {baseDir}/scripts/openproject.mjs priority-list

# 列出项目成员
node {baseDir}/scripts/openproject.mjs member-list --project my-project

# 列出版本/里程碑
node {baseDir}/scripts/openproject.mjs version-list --project my-project

# 列出分类
node {baseDir}/scripts/openproject.mjs category-list --project my-project

安全性

• 采用 API 令牌认证（使用 apikey 作为用户名的 Basic Auth）
• 不向 stdout 输出任何密钥或令牌
• 所有删除操作均需显式指定 --confirm 参数
• 对文件上传路径进行遍历防护
• 内置速率限制，并支持指数退避重试机制
• 延迟配置校验（仅在命令实际运行时执行检查）

依赖项

• commander — CLI 框架
• dotenv — 环境变量加载工具
• Node.js 内置 fetch（要求 Node.js 版本 ≥ 18）

作者

Abdelkrim BOUJRAF — ALT-F1 SRL，布鲁塞尔 🇧🇪 🇲🇦
Twitter（X）：@altf1be