由 @altf1be 提供的 OpenProject
透過 API v3 管理 OpenProject 工作套件、專案、群組、新聞、使用者、觀察者、關聯、通知、時間記錄、評論、附件、Wiki 頁面與工作流程轉換。適用於雲端與自託管實例。
設定
- 登入你的 OpenProject 實例
- 前往 我的帳號 → 存取權杖 → + 新增
- 建立 API 權杖並複製
- 設定環境變數(或在
{baseDir}中建立.env):
OP_HOST=https://projects.xflowdata.com
OP_API_TOKEN=your-api-token
OP_DEFAULT_PROJECT=my-project
- 安裝相依套件:
cd {baseDir} && npm install
指令
工作套件
# 列出工作套件(可選篩選條件)
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 "修復登入錯誤" --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
專案
# 列出所有專案
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
評論(活動)
# 列出工作套件的評論
node {baseDir}/scripts/openproject.mjs comment-list --wp-id 42
# 新增評論
node {baseDir}/scripts/openproject.mjs comment-add --wp-id 42 --body "準備好進行審查"
附件
# 列出工作套件的附件
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
時間記錄
# 列出時間記錄
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
狀態與轉換
# 列出所有狀態
node {baseDir}/scripts/openproject.mjs status-list
# 更新工作套件狀態
node {baseDir}/scripts/openproject.mjs wp-update --id 42 --status "進行中"
使用者
# 列出所有使用者(可選篩選條件)
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
通知
# 列出通知(全部或僅未讀)
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
文件
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 "已更新標題"
修訂
node {baseDir}/scripts/openproject.mjs revision-read --id 10
node {baseDir}/scripts/openproject.mjs revision-list-by-wp --wp-id 42
能力與動作
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
我的偏好設定
node {baseDir}/scripts/openproject.mjs my-preferences-read
node {baseDir}/scripts/openproject.mjs my-preferences-update --time-zone "Europe/Brussels" --comment-order desc
渲染
node {baseDir}/scripts/openproject.mjs render-markdown --text "**粗體** 和 *斜體*"
node {baseDir}/scripts/openproject.mjs render-plain --text "純文字"
文章(論壇)
node {baseDir}/scripts/openproject.mjs post-read --id 5
node {baseDir}/scripts/openproject.mjs post-attachment-list --id 5
提醒
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
專案狀態
node {baseDir}/scripts/openproject.mjs project-status-read --id on_track
專案階段(企業版)
# 列出專案階段定義
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
投資組合(企業版)
# 列出投資組合
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
方案(企業版)
# 列出方案
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
佔位使用者(企業版)
# 列出佔位使用者
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
預算(企業版)
# 列出專案預算
node {baseDir}/scripts/openproject.mjs budget-list --project my-project
# 讀取預算詳細資訊
node {baseDir}/scripts/openproject.mjs budget-read --id 3
會議(企業版)
# 讀取會議
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
工作日(工作日/非工作日)
# 檢查日期是否為工作日
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
設定
# 查看實例設定
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
說明文字
# 列出所有屬性說明文字
node {baseDir}/scripts/openproject.mjs help-text-list
# 讀取說明文字
node {baseDir}/scripts/openproject.mjs help-text-read --id 1
自訂欄位與選項
# 列出階層式自訂欄位的項目
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
自訂動作
# 讀取自訂動作
node {baseDir}/scripts/openproject.mjs custom-action-read --id 1
# 在工作套件上執行自訂動作
node {baseDir}/scripts/openproject.mjs custom-action-execute --id 1 --wp-id 42
群組
# 列出所有群組
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
新聞
# 列出所有新聞
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 "錯誤修復與效能最佳化" --description "此處提供完整詳細資訊..."
# 更新新聞項目
node {baseDir}/scripts/openproject.mjs news-update --id 5 --title "已更新標題"
# 刪除新聞項目(需要 --confirm)
node {baseDir}/scripts/openproject.mjs news-delete --id 5 --confirm
觀察者
# 列出工作套件的觀察者
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
關聯
# 列出所有關聯(可依工作套件或類型篩選)
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 頁面
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
參考資料
# 列出工作套件類型
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 Token 認證(基本認證,使用者名稱為
apikey) - 機密或權杖不會輸出到 stdout
- 所有刪除操作都需要明確的
--confirm標誌 - 防止路徑遍歷攻擊的檔案上傳保護
- 內建速率限制與指數退避重試機制
- 懶載入配置驗證(僅在指令執行時檢查)
相依套件
commander— CLI 框架dotenv— 環境變數載入- Node.js 內建
fetch(需要 Node >= 18)
作者
Abdelkrim BOUJRAF — ALT-F1 SRL,布魯塞爾 🇧🇪 🇲🇦 X:@altf1be