picoclaw/docs/affine-integration/development-notes/測試腳本使用說明.md

測試腳本使用說明

📋 可用的測試腳本

我們提供了兩個自動化測試腳本：

1. test-affine-features.sh - PicoClaw 整合測試

測試透過 PicoClaw 使用 Affine 工具的完整流程

2. test-affine-mcp-direct.sh - MCP 端點直接測試

直接測試 Affine MCP API，不透過 PicoClaw

---

🚀 在 Codespace 中執行測試

步驟 1: 拉取最新程式碼

cd /workspaces/picoclaw
git pull origin main

步驟 2: 給予執行權限

chmod +x test-affine-features.sh
chmod +x test-affine-mcp-direct.sh

步驟 3: 執行測試

選項 A: 執行 PicoClaw 整合測試（推薦）

./test-affine-features.sh

這個腳本會：

• ✅ 自動檢查環境
• ✅ 如果需要會自動編譯 picoclaw
• ✅ 執行 7 個測試案例
• ✅ 顯示彩色的測試結果
• ✅ 統計通過/失敗數量

選項 B: 執行 MCP 端點直接測試

./test-affine-mcp-direct.sh

這個腳本會：

• ✅ 直接測試 MCP API 端點
• ✅ 顯示完整的請求和回應
• ✅ 測試 6 個不同的 MCP 工具
• ✅ 不需要編譯 PicoClaw

---

📊 測試項目

PicoClaw 整合測試包含：

1. 列出所有文件 - 測試 list_docs 基本功能
2. 列出前 5 個文件 - 測試 list_docs 的 limit 參數
3. 關鍵字搜尋 - 測試 keyword_search（已知可用）
4. 取得文件元資料 - 測試 get_doc
5. 匯出 Markdown - 測試 export_doc_markdown
6. 自然語言 - 列出文件 - 測試 AI 理解能力
7. 自然語言 - 取得資訊 - 測試 AI 理解能力

MCP 端點直接測試包含：

1. list_docs - 列出文件
2. keyword_search - 關鍵字搜尋
3. get_doc - 取得元資料
4. export_doc_markdown - 匯出 Markdown
5. semantic_search - 語意搜尋
6. list_tags - 列出標籤

---

🎨 輸出範例

成功的測試輸出

==========================================
Affine 工具自動測試腳本
==========================================

1. 檢查環境...

✓ 環境檢查完成

==========================================
開始測試
==========================================

測試 1: 列出所有文件
指令: ./picoclaw agent -m 'List all documents in my Affine workspace'

[... PicoClaw 輸出 ...]

✓ 測試通過

------------------------------------------

...

==========================================
測試結果總結
==========================================

總測試數: 7
通過: 7
失敗: 0

🎉 所有測試都通過了！

失敗的測試輸出

測試 3: 關鍵字搜尋
指令: ./picoclaw agent -m 'Search my Affine workspace for the'

[... 錯誤訊息 ...]

✗ 測試失敗

------------------------------------------

==========================================
測試結果總結
==========================================

總測試數: 7
通過: 5
失敗: 2

⚠️  有 2 個測試失敗

---

🐛 故障排除

問題 1: 權限被拒絕

bash: ./test-affine-features.sh: Permission denied

解決方案:

chmod +x test-affine-features.sh

問題 2: 找不到設定檔

錯誤: 找不到設定檔 ~/.picoclaw/config.json

解決方案: 確保你已經設定了 Affine 連線資訊：

cat ~/.picoclaw/config.json

如果不存在，請參考 CODESPACE_NEXT_STEPS.md 建立設定檔。

問題 3: 編譯失敗

go: github.com/mymmrac/telego@v1.6.0 requires go >= 1.25.5

解決方案:

export GOTOOLCHAIN=auto
go build -o picoclaw ./cmd/picoclaw

問題 4: API Token 過期

HTTP 401: Unauthorized

解決方案:

1. 前往 AFFiNE Cloud
2. Settings → Integrations → MCP Server
3. 產生新的 Token
4. 更新 ~/.picoclaw/config.json

---

📝 手動測試

如果自動測試失敗，你可以手動執行單一測試：

# 測試列出文件
./picoclaw agent -m "List all documents in my Affine workspace"

# 測試取得元資料
./picoclaw agent -m "Get metadata for document eDebZI1h3F from Affine"

# 測試匯出 Markdown
./picoclaw agent -m "Export document eDebZI1h3F as markdown from Affine"

---

🔍 查看詳細日誌

如果需要更詳細的除錯資訊，使用 debug 模式：

./picoclaw agent -d -m "List all documents in my Affine workspace"

---

📊 測試結果記錄

完成測試後，請記錄結果：

測試項目	狀態	備註
list_docs	⏳
get_doc	⏳
export_markdown	⏳
keyword_search	✅	已知可用
semantic_search	⏳

---

🎯 下一步

測試完成後：

1. 如果全部通過 ✅

   • 更新 AFFINE_整合總結.md
   • 繼續實作階段 1.3（標籤功能）

2. 如果有失敗 ❌

   • 使用 test-affine-mcp-direct.sh 測試 MCP 端點
   • 檢查回應格式
   • 調整解析邏輯
   • 重新測試

---

💡 提示

• 測試腳本會自動編譯 PicoClaw（如果需要）
• 使用彩色輸出更容易閱讀結果
• 可以修改腳本來測試其他文件 ID
• 建議先執行 MCP 直接測試，確認 API 可用

---

建立日期: 2026-02-26
適用環境: GitHub Codespace
需求: bash, curl, jq (選用)