mirror of
https://github.com/cjo4m06/mcp-shrimp-task-manager.git
synced 2025-07-27 08:32:27 +08:00
更新 README.md 和使用指南，新增蝦米任務管理器的全局配置與專案特定配置說明，詳細介紹 DATA_DIR 參數的重要性及其配置步驟，並提供多種配置場景範例以協助用戶更有效地管理任務數據。
This commit is contained in:
siage
parent
e0ca35bde5
commit
f8113c7963
33
README.md
33
README.md
@ -237,7 +237,11 @@ npm run build
|
|||||||
|
|
||||||
### 在 Cursor IDE 中配置
|
### 在 Cursor IDE 中配置
|
||||||
|
|
||||||
1. 打開 Cursor IDE 的設定檔案（通常位於 `~/.cursor/settings.json`）
|
蝦米任務管理器提供兩種配置方式：全局配置和專案特定配置。
|
||||||
|
|
||||||
|
#### 全局配置
|
||||||
|
|
||||||
|
1. 打開 Cursor IDE 的全局設定檔案（通常位於 `~/.cursor/settings.json`）
|
||||||
2. 在 `mcpServers` 部分添加蝦米任務管理器的配置
|
2. 在 `mcpServers` 部分添加蝦米任務管理器的配置
|
||||||
|
|
||||||
```json
|
```json
|
||||||
@ -254,7 +258,32 @@ npm run build
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
請將 `path/to/mcp-shrimp-task-manager` 替換為實際的路徑。
|
請將 `/mcp-shrimp-task-manager` 替換為實際的路徑。
|
||||||
|
|
||||||
|
#### 專案特定配置
|
||||||
|
|
||||||
|
您也可以在每個專案中設定專屬的配置，這樣能夠針對不同專案使用不同的數據目錄：
|
||||||
|
|
||||||
|
1. 在專案根目錄創建 `.cursor` 目錄
|
||||||
|
2. 在該目錄下創建 `mcp.json` 文件，內容如下：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"shrimp-task-manager": {
|
||||||
|
"command": "node",
|
||||||
|
"args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"],
|
||||||
|
"env": {
|
||||||
|
"DATA_DIR": "./data" // 使用相對路徑，指向專案內的數據目錄
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**DATA_DIR 參數**是蝦米任務管理器存儲任務數據、對話記錄等信息的目錄，正確設置此參數對於系統的正常運行至關重要。
|
||||||
|
|
||||||
|
更多關於專案特定配置的詳細說明和最佳實踐，請參閱[使用指南：專案特定配置](docs/usage-guide.md#project-specific-configuration)。
|
||||||
|
|
||||||
### 可用的工具
|
### 可用的工具
|
||||||
|
|
||||||
|
|||||||
@ -587,3 +587,391 @@ await mcp.mcp_shrimp_task_manager.clear_conversation_log({
|
|||||||
### Q: 清除所有任務後，如何恢復誤刪的數據？
|
### Q: 清除所有任務後，如何恢復誤刪的數據？
|
||||||
|
|
||||||
**A:** 系統在清除操作前會自動創建備份文件，存放在 `data/backups` 目錄下。可以通過手動恢復這些備份文件來還原數據。建議定期檢查並整理備份目錄，確保重要數據安全。
|
**A:** 系統在清除操作前會自動創建備份文件，存放在 `data/backups` 目錄下。可以通過手動恢復這些備份文件來還原數據。建議定期檢查並整理備份目錄，確保重要數據安全。
|
||||||
|
|
||||||
|
<a id="project-specific-configuration"></a>
|
||||||
|
|
||||||
|
## 專案特定配置指南
|
||||||
|
|
||||||
|
蝦米任務管理器支持兩種配置方式：全局配置和專案特定配置。本章節將詳細介紹如何使用專案特定配置，幫助您更有效地管理多個專案的任務數據。
|
||||||
|
|
||||||
|
### DATA_DIR 參數的作用及重要性
|
||||||
|
|
||||||
|
`DATA_DIR` 是蝦米任務管理器中最關鍵的配置參數之一，它決定了系統存儲數據的位置。具體來說，`DATA_DIR` 參數指定的目錄用於存儲：
|
||||||
|
|
||||||
|
1. **任務數據**：所有任務的詳細信息、狀態和依賴關係（`tasks.json`）
|
||||||
|
2. **對話日誌**：系統與 LLM 之間的交互記錄（`conversation_log.json`）
|
||||||
|
3. **數據備份**：任務數據的定期備份（`backups/` 目錄）
|
||||||
|
4. **臨時文件**：系統操作過程中的臨時數據
|
||||||
|
|
||||||
|
`DATA_DIR` 參數的正確設置對系統穩定性和數據安全至關重要，因為：
|
||||||
|
|
||||||
|
- **數據持久化**：確保任務信息在系統重啟後不會丟失
|
||||||
|
- **數據完整性**：維護任務間的依賴關係和執行歷史
|
||||||
|
- **上下文記憶**：保存 LLM 在執行任務時需要的上下文信息
|
||||||
|
- **備份與恢復**：支持數據備份和災難恢復機制
|
||||||
|
|
||||||
|
### 專案特定配置的優勢
|
||||||
|
|
||||||
|
相比全局配置，在專案目錄中使用專案特定的 `.cursor/mcp.json` 配置有以下明顯優勢：
|
||||||
|
|
||||||
|
#### 1. 數據隔離
|
||||||
|
|
||||||
|
- **獨立數據存儲**：每個專案使用獨立的數據目錄，避免任務數據混淆
|
||||||
|
- **專案內聚性**：任務數據與專案代碼一起管理，增強內聚性
|
||||||
|
- **錯誤防護**：防止跨專案操作錯誤，如誤刪除他專案的任務
|
||||||
|
|
||||||
|
#### 2. 專案可移植性
|
||||||
|
|
||||||
|
- **整體遷移**：專案代碼和任務數據可一起移動或分享
|
||||||
|
- **環境一致性**：確保在不同環境中使用相同的配置
|
||||||
|
- **團隊協作**：團隊成員可以共享完整的專案上下文，包括任務狀態
|
||||||
|
|
||||||
|
#### 3. 多專案管理
|
||||||
|
|
||||||
|
- **同時處理**：可以同時處理多個專案而不互相影響
|
||||||
|
- **上下文切換**：在不同專案間切換時，自動使用相應的任務數據
|
||||||
|
- **專案特化**：可以為不同類型的專案設置不同的配置參數
|
||||||
|
|
||||||
|
#### 4. 版本控制友好
|
||||||
|
|
||||||
|
- **配置跟踪**：`.cursor/mcp.json` 可以納入版本控制系統
|
||||||
|
- **配置共享**：團隊成員自動獲取一致的配置設置
|
||||||
|
- **變更記錄**：配置變更可以通過版本控制系統追蹤和審查
|
||||||
|
|
||||||
|
### mcp.json 配置參數完整說明
|
||||||
|
|
||||||
|
專案特定的 `mcp.json` 文件應放置在專案根目錄的 `.cursor` 目錄下，其完整結構如下：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"shrimp-task-manager": {
|
||||||
|
"command": "node",
|
||||||
|
"args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"],
|
||||||
|
"env": {
|
||||||
|
"DATA_DIR": "./data",
|
||||||
|
"LOG_LEVEL": "info",
|
||||||
|
"MAX_BACKUP_FILES": "5"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 必要參數
|
||||||
|
|
||||||
|
| 參數名 | 說明 | 示例值 |
|
||||||
|
| -------------- | ----------------------------------- | ---------------------------------------------------- |
|
||||||
|
| `command` | 執行命令，通常為 node | `"node"` |
|
||||||
|
| `args` | 命令參數，指向 dist/index.js 的路徑 | `["/path/to/mcp-shrimp-task-manager/dist/index.js"]` |
|
||||||
|
| `env.DATA_DIR` | 數據目錄路徑，可使用絕對或相對路徑 | `"./data"` 或 `"/absolute/path/to/data"` |
|
||||||
|
|
||||||
|
#### 可選環境變數
|
||||||
|
|
||||||
|
| 環境變數名 | 說明 | 默認值 | 示例值 |
|
||||||
|
| ------------------ | ------------------------- | -------- | ---------------------- |
|
||||||
|
| `LOG_LEVEL` | 日誌記錄級別 | `"info"` | `"debug"`, `"warning"` |
|
||||||
|
| `MAX_BACKUP_FILES` | 保留的最大備份文件數量 | `"5"` | `"10"` |
|
||||||
|
| `BACKUP_INTERVAL` | 自動備份間隔（小時） | `"24"` | `"12"` |
|
||||||
|
| `PORT` | HTTP 服務器端口（如啟用） | `"3000"` | `"8080"` |
|
||||||
|
|
||||||
|
### 注意事項和建議
|
||||||
|
|
||||||
|
1. **路徑設置**：
|
||||||
|
|
||||||
|
- 絕對路徑提供明確的位置指向，但降低了可移植性
|
||||||
|
- 相對路徑（如 `"./data"`）增強可移植性，建議在團隊協作環境中使用
|
||||||
|
|
||||||
|
2. **數據目錄**：
|
||||||
|
|
||||||
|
- 建議創建專用的數據目錄（例如 `data/`）
|
||||||
|
- 確保該目錄已納入 `.gitignore`，避免將任務數據提交到版本控制系統（除非有意共享）
|
||||||
|
|
||||||
|
3. **權限考慮**：
|
||||||
|
|
||||||
|
- 確保運行蝦米任務管理器的用戶對 DATA_DIR 目錄有讀寫權限
|
||||||
|
- 在團隊環境中，可能需要考慮目錄的共享權限設置
|
||||||
|
|
||||||
|
4. **備份策略**：
|
||||||
|
- 設置適當的 `MAX_BACKUP_FILES` 值，平衡數據安全和磁盤使用
|
||||||
|
- 考慮定期將備份複製到外部存儲以增強數據安全
|
||||||
|
|
||||||
|
### 專案特定配置的逐步設置指南
|
||||||
|
|
||||||
|
以下是配置專案特定 mcp.json 的詳細步驟指南，幫助您快速設置適合專案需求的配置。
|
||||||
|
|
||||||
|
#### 步驟 1：在專案根目錄創建 .cursor 目錄
|
||||||
|
|
||||||
|
首先，在您的專案根目錄中創建一個名為 `.cursor` 的目錄：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 在專案根目錄執行
|
||||||
|
mkdir -p .cursor
|
||||||
|
```
|
||||||
|
|
||||||
|
> **注意**：在某些操作系統中，以點（.）開頭的目錄可能默認隱藏。如果您在檔案管理器中看不到該目錄，請檢查顯示隱藏文件的選項。
|
||||||
|
|
||||||
|
#### 步驟 2：創建 mcp.json 配置文件
|
||||||
|
|
||||||
|
在 `.cursor` 目錄中創建 `mcp.json` 文件：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
touch .cursor/mcp.json
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 步驟 3：編輯 mcp.json 文件
|
||||||
|
|
||||||
|
使用您喜歡的文本編輯器打開 `mcp.json` 文件，添加以下基本配置：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"shrimp-task-manager": {
|
||||||
|
"command": "node",
|
||||||
|
"args": ["/absolute/path/to/mcp-shrimp-task-manager/dist/index.js"],
|
||||||
|
"env": {
|
||||||
|
"DATA_DIR": "./data"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
請將 `/absolute/path/to/mcp-shrimp-task-manager` 替換為蝦米任務管理器的實際安裝路徑。
|
||||||
|
|
||||||
|
#### 步驟 4：設定 DATA_DIR 參數
|
||||||
|
|
||||||
|
`DATA_DIR` 參數可以使用相對路徑或絕對路徑：
|
||||||
|
|
||||||
|
**使用相對路徑（推薦）**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
"DATA_DIR": "./data"
|
||||||
|
```
|
||||||
|
|
||||||
|
這會在您的專案根目錄中使用 `data` 目錄存儲任務數據。這種方式有利於專案可移植性。
|
||||||
|
|
||||||
|
**使用絕對路徑**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
"DATA_DIR": "/Users/username/projects/my-project/data"
|
||||||
|
```
|
||||||
|
|
||||||
|
絕對路徑提供了明確的位置指向，但降低了專案的可移植性。
|
||||||
|
|
||||||
|
#### 步驟 5：創建數據目錄
|
||||||
|
|
||||||
|
確保 `DATA_DIR` 指向的目錄存在：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 如果使用相對路徑 "./data"
|
||||||
|
mkdir -p data
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 步驟 6：更新 .gitignore（可選但推薦）
|
||||||
|
|
||||||
|
如果您的專案使用 Git 進行版本控制，建議將數據目錄添加到 `.gitignore` 文件中（除非您打算共享任務數據）：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 添加到 .gitignore
|
||||||
|
echo "data/" >> .gitignore
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 完整配置範例
|
||||||
|
|
||||||
|
以下是一個更完整的配置範例，包含常用的可選參數：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"shrimp-task-manager": {
|
||||||
|
"command": "node",
|
||||||
|
"args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"],
|
||||||
|
"env": {
|
||||||
|
"DATA_DIR": "./data",
|
||||||
|
"LOG_LEVEL": "info",
|
||||||
|
"MAX_BACKUP_FILES": "10",
|
||||||
|
"BACKUP_INTERVAL": "12"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 測試配置
|
||||||
|
|
||||||
|
完成配置後，打開 Cursor IDE 並嘗試使用蝦米任務管理器的任何功能（如 `list_tasks`）來測試配置是否生效。系統應該會在您指定的 `DATA_DIR` 路徑創建必要的數據文件。
|
||||||
|
|
||||||
|
#### 常見問題與解決方案
|
||||||
|
|
||||||
|
1. **找不到蝦米任務管理器**
|
||||||
|
|
||||||
|
- 檢查 `args` 中的路徑是否正確指向 dist/index.js
|
||||||
|
- 確保已正確安裝蝦米任務管理器及其依賴
|
||||||
|
|
||||||
|
2. **無法創建或訪問數據目錄**
|
||||||
|
|
||||||
|
- 檢查用戶對指定目錄的讀寫權限
|
||||||
|
- 如果使用相對路徑，確認相對於專案根目錄的位置是否正確
|
||||||
|
|
||||||
|
3. **配置未生效**
|
||||||
|
- 確保 `.cursor/mcp.json` 文件格式正確（有效的 JSON）
|
||||||
|
- 重新啟動 Cursor IDE 以載入新配置
|
||||||
|
- 檢查 Cursor IDE 的日誌是否有錯誤信息
|
||||||
|
|
||||||
|
### 多種配置場景範例
|
||||||
|
|
||||||
|
蝦米任務管理器可以適應多種不同的工作場景，以下提供幾種常見使用場景的配置示例和最佳實踐。
|
||||||
|
|
||||||
|
#### 1. 單一開發者多專案環境
|
||||||
|
|
||||||
|
對於同時處理多個專案的獨立開發者，專案特定配置可以幫助您維護清晰的任務隔離。
|
||||||
|
|
||||||
|
**示例配置**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
// 專案A: .cursor/mcp.json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"shrimp-task-manager": {
|
||||||
|
"command": "node",
|
||||||
|
"args": ["/Users/developer/tools/mcp-shrimp-task-manager/dist/index.js"],
|
||||||
|
"env": {
|
||||||
|
"DATA_DIR": "./data",
|
||||||
|
"LOG_LEVEL": "info"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
// 專案B: .cursor/mcp.json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"shrimp-task-manager": {
|
||||||
|
"command": "node",
|
||||||
|
"args": ["/Users/developer/tools/mcp-shrimp-task-manager/dist/index.js"],
|
||||||
|
"env": {
|
||||||
|
"DATA_DIR": "./data",
|
||||||
|
"LOG_LEVEL": "debug" // 不同的日誌級別
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**最佳實踐**：
|
||||||
|
|
||||||
|
- 在每個專案中使用相對路徑 `"./data"` 作為 DATA_DIR，提高可移植性
|
||||||
|
- 根據專案需求調整日誌級別和備份策略
|
||||||
|
- 使用腳本或別名簡化在多個專案間切換的操作
|
||||||
|
|
||||||
|
#### 2. 團隊協作環境
|
||||||
|
|
||||||
|
在團隊協作的環境中，專案特定配置可以確保團隊成員使用一致的設置。
|
||||||
|
|
||||||
|
**示例配置**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
// 團隊專案: .cursor/mcp.json (納入版本控制)
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"shrimp-task-manager": {
|
||||||
|
"command": "node",
|
||||||
|
"args": [
|
||||||
|
"${workspaceFolder}/node_modules/mcp-shrimp-task-manager/dist/index.js"
|
||||||
|
],
|
||||||
|
"env": {
|
||||||
|
"DATA_DIR": "${workspaceFolder}/data",
|
||||||
|
"LOG_LEVEL": "info",
|
||||||
|
"MAX_BACKUP_FILES": "10"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**最佳實踐**：
|
||||||
|
|
||||||
|
- 使用 `${workspaceFolder}` 變數（在支持的環境中）或相對路徑，確保配置在不同團隊成員的機器上都能正常工作
|
||||||
|
- 將 `.cursor/mcp.json` 文件納入版本控制，但將數據目錄添加到 `.gitignore`
|
||||||
|
- 考慮為共享知識庫專案配置共享的數據目錄（如雲端存儲或版本控制）
|
||||||
|
- 明確記錄配置要求，確保新團隊成員能夠快速設置環境
|
||||||
|
|
||||||
|
#### 3. 臨時/測試專案設置
|
||||||
|
|
||||||
|
對於臨時專案或測試環境，您可能需要更靈活的配置。
|
||||||
|
|
||||||
|
**示例配置**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
// 臨時測試專案: .cursor/mcp.json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"shrimp-task-manager": {
|
||||||
|
"command": "node",
|
||||||
|
"args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"],
|
||||||
|
"env": {
|
||||||
|
"DATA_DIR": "/tmp/test-project-data", // 使用臨時目錄
|
||||||
|
"LOG_LEVEL": "debug",
|
||||||
|
"MAX_BACKUP_FILES": "2" // 減少備份量
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**最佳實踐**：
|
||||||
|
|
||||||
|
- 對於臨時測試，可以使用系統臨時目錄存儲數據
|
||||||
|
- 設置更高的日誌級別（如 `"debug"`）以便更詳細地診斷問題
|
||||||
|
- 減少備份文件數量，避免不必要的磁盤使用
|
||||||
|
- 測試完成後記得清理臨時數據
|
||||||
|
|
||||||
|
#### 4. 絕對路徑與相對路徑的比較
|
||||||
|
|
||||||
|
選擇絕對路徑或相對路徑取決於您的具體需求。以下是兩種方式的對比分析：
|
||||||
|
|
||||||
|
**絕對路徑**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
"DATA_DIR": "/Users/username/projects/my-project/data"
|
||||||
|
```
|
||||||
|
|
||||||
|
優點：
|
||||||
|
|
||||||
|
- 提供明確的數據位置，不受當前工作目錄影響
|
||||||
|
- 可以指向專案外部的數據存儲，便於共享或集中管理
|
||||||
|
- 對於固定的開發環境，配置更明確
|
||||||
|
|
||||||
|
缺點：
|
||||||
|
|
||||||
|
- 降低專案可移植性，在不同機器上需要調整路徑
|
||||||
|
- 在團隊環境中需要每個成員自定義路徑
|
||||||
|
- 可能導致硬編碼的路徑依賴
|
||||||
|
|
||||||
|
**相對路徑**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
"DATA_DIR": "./data"
|
||||||
|
```
|
||||||
|
|
||||||
|
優點：
|
||||||
|
|
||||||
|
- 提高專案可移植性，可以整體移動或分享專案
|
||||||
|
- 在團隊環境中更容易標準化
|
||||||
|
- 與版本控制系統配合更好，無需針對不同環境修改配置
|
||||||
|
|
||||||
|
缺點：
|
||||||
|
|
||||||
|
- 相對於當前工作目錄，可能在某些 IDE 或調用方式下有差異
|
||||||
|
- 可能需要額外步驟確保目錄存在
|
||||||
|
- 在某些複雜的專案結構中可能引起混淆
|
||||||
|
|
||||||
|
**最佳選擇建議**：
|
||||||
|
|
||||||
|
- **團隊專案**：優先使用相對路徑，提高可移植性和一致性
|
||||||
|
- **個人專案**：可以根據個人偏好選擇，但相對路徑通常更靈活
|
||||||
|
- **服務器/CI 環境**：通常絕對路徑更可靠，便於自動化配置
|
||||||
|
- **混合方式**：在某些情況下，可以在配置中使用環境變數，統一管理路徑
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user