cw-ai-backlog
Version:
AI-powered tool to generate backlog items from meeting documents and output to Google Sheets
240 lines (178 loc) • 6.3 kB
Markdown
# AI Backlog Generator
[](https://badge.fury.io/js/ai-backlog)
[](https://www.npmjs.com/package/ai-backlog)
[](https://opensource.org/licenses/MIT)
一個使用 AI 技術從會議文件自動生成 backlog 項目並直接寫入 Google Sheets 的 CLI 工具。
## 功能特色
- 📄 支援多種檔案格式：PDF、Word (.docx)、純文字檔案
- 🔗 支援 Google Docs 連結解析
- 🤖 使用 OpenAI API 智慧分析會議內容
- ⚡ 自動區分前端/後端 backlog 項目
- � 直接輸出到 Google Sheets，自動建立新工作表
- �📋 包含 Area、Iteration、MoSCoW 欄位供後續管理
- 🔍 每個 backlog 項目都能追溯到原文片段
- ⚙️ 可配置的 AI 模型和參數
## 安裝
```bash
npm install -g ai-backlog
```
或者在專案中本地安裝：
```bash
npm install ai-backlog
```
> 📖 **完整使用指南**：請參閱 [USAGE.md](./USAGE.md) 獲得詳細的安裝和使用說明
## 快速開始
### 🚀 互動式設定（推薦）
```bash
# 執行互動式配置設定精靈
ai-backlog --setup
```
這會引導您完成所有必要的設定，包括：
- OpenAI API Key
- AI 模型選擇
- Google 憑證檔案路徑
- Google Sheets URL
- 進階選項（保留字、自訂 prompt 等）
### 手動配置
如果您偏好手動設定，首次使用時工具會建立 `ai_backlog.config.js` 配置檔案：
```javascript
module.exports = {
// OpenAI API Key (必填)
apiKey: process.env.OPENAI_API_KEY || '你的-openai-api-key',
// Google Sheets URL (必填 - 用於輸出 backlog)
googleSheetUrl: 'https://docs.google.com/spreadsheets/d/your-sheet-id/edit',
// Google API 憑證檔案路徑 (必填)
googleCredentials: './path/to/credentials.json',
// 使用的模型
model: 'gpt-4o', // 或 'gpt-4-turbo', 'gpt-3.5-turbo'
// 保留字 - 在分析時需要特別注意的詞彙
keepPhrases: [
'使用者體驗',
'效能優化',
'安全性',
// ... 更多保留字
],
// AI 參數設定
maxTokens: 4000,
temperature: 0.1
};
```
### 環境變數設定
您也可以使用環境變數設定 API Key：
```bash
export OPENAI_API_KEY="your-openai-api-key"
```
## 使用方法
### 基本用法
```bash
# 解析本地檔案並寫入 Google Sheets
ai-backlog ./meeting-notes.pdf
# 解析 Google Docs 並寫入 Google Sheets
ai-backlog "https://docs.google.com/document/d/your-doc-id/edit"
# 使用自訂配置檔案
ai-backlog ./meeting-notes.txt -c ./custom-config.js
```
### 指令參數
```bash
# 基本使用
ai-backlog [檔案路徑或URL] [選項]
# 配置管理
ai-backlog --setup # 互動式配置設定精靈
ai-backlog --show-config # 顯示配置檔案位置
ai-backlog --edit-config # 快速編輯全域配置檔案
# 自訂配置
ai-backlog input.pdf -c custom-config.js # 使用自訂配置檔案
```
**選項說明：**
- `[input]`: 會議檔案路徑或 Google Docs 連結
- `--setup`: 執行互動式配置設定精靈（首次使用推薦）
- `--show-config`: 顯示配置檔案查找位置和狀態
- `--edit-config`: 在編輯器中開啟全域配置檔案
- `-c, --config <path>`: 指定自訂配置檔案路徑
## 支援的檔案格式
- **PDF**: `.pdf` 檔案
- **Word**: `.docx` 檔案
- **純文字**: `.txt`, `.md` 檔案
- **Google Docs**: 透過連結存取
## 輸出格式
工具會生成包含以下結構的 JSON 檔案：
```json
[
{
"title": "建立使用者登入功能",
"type": "frontend",
"description": "開發使用者登入頁面，包含帳號密碼欄位、驗證機制和錯誤提示。",
"acceptance_criteria": [
"使用者輸入錯誤帳號密碼時需顯示明確的錯誤訊息",
"成功登入後自動導向到使用者的首頁",
"支援記住我功能，7天內免重新登入"
],
"effort": 5,
"effort_analysis": "包含 UI 設計、表單驗證、錯誤處理和狀態管理，屬於中等複雜度的功能",
"source_text": "會議中討論需要建立使用者登入功能，要求有清楚的錯誤訊息和記住我功能",
"ai_suggestions": "建議考慮加入雙因子認證或密碼強度檢查，以提升安全性"
},
{
"title": "實作使用者認證 API",
"type": "backend",
"description": "建立使用者認證相關的後端 API，包含登入驗證、JWT token 生成和驗證。",
"acceptance_criteria": [
"提供 POST /api/auth/login 端點進行使用者驗證",
"成功驗證後回傳 JWT token 和使用者基本資訊",
"實作 token 過期和刷新機制"
],
"effort": 8,
"effort_analysis": "需要設計資料庫認證邏輯、JWT 實作、安全性考量和錯誤處理，複雜度較高",
"source_text": "需要後端 API 支援登入驗證，包含 JWT token 機制",
"ai_suggestions": ""
}
]
```
"effort": 8,
"effort_analysis": "需要實作加密、JWT 機制、資料庫查詢和安全性考量，較為複雜"
}
]
```
### 欄位說明
- **title**: Backlog 項目標題
- **type**: 類型 (`frontend`, `backend`, `fullstack`)
- **description**: 詳細描述
- **acceptance_criteria**: 驗收條件陣列
- **effort**: 工作量評估 (費波那契數列: 1, 2, 3, 5, 8, 13, 21)
- **effort_analysis**: 工作量評估的說明
## Google Docs 整合
### 公開文件
對於公開的 Google Docs，工具會嘗試直接存取內容。
### 私人文件
對於私人文件，您需要：
1. 到 [Google Cloud Console](https://console.cloud.google.com/) 建立專案
2. 啟用 Google Docs API
3. 建立服務帳戶並下載憑證 JSON 檔案
4. 在配置檔案中設定憑證路徑：
```javascript
module.exports = {
// ... 其他設定
googleCredentials: './path/to/your/credentials.json'
};
```
## 開發
### 本地開發
```bash
# 複製專案
git clone <repository-url>
cd ai-backlog
# 安裝依賴
npm install
# 執行
node src/cli.js [arguments]
```
### 測試
```bash
npm test
```
## 授權
MIT License
## 貢獻
歡迎提交 Issue 和 Pull Request！
## 支援
如有問題或建議，請在 GitHub Issues 中提出。