初始提交：工具安裝與使用筆記

包含 MemPalace、MarkItDown、Playwright 的安裝與使用筆記。 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 09:29:01 +08:00
commit f3f832df20
4 changed files with 479 additions and 0 deletions
--- a/markitdown-notes.md
+++ b/markitdown-notes.md
@@ -0,0 +1,130 @@
+# MarkItDown 安裝與使用筆記
+
+## 基本資訊
+
+- **專案**: https://github.com/microsoft/markitdown
+- **版本**: 0.1.5
+- **作者**: Microsoft
+- **授權**: MIT
+- **需求**: Python 3.10+
+- **安裝日期**: 2026-04-15
+
+## 安裝
+
+```bash
+# 基本安裝
+pip install markitdown
+
+# 完整安裝（所有格式支援）
+pip install 'markitdown[all]'
+```
+
+### 個別功能模組
+
+```bash
+pip install 'markitdown[pdf]'                    # PDF
+pip install 'markitdown[docx]'                   # Word
+pip install 'markitdown[pptx]'                   # PowerPoint
+pip install 'markitdown[xlsx]'                   # Excel（新版）
+pip install 'markitdown[xls]'                    # Excel（舊版）
+pip install 'markitdown[outlook]'                # Outlook 郵件
+pip install 'markitdown[audio-transcription]'    # 音訊轉文字
+pip install 'markitdown[youtube-transcription]'  # YouTube 字幕
+pip install 'markitdown[az-doc-intel]'           # Azure Document Intelligence
+```
+
+## 支援的檔案格式
+
+| 格式 | 說明 |
+|------|------|
+| PDF | PDF 文件 |
+| DOCX | Word 文件 |
+| PPTX | PowerPoint 簡報 |
+| XLSX / XLS | Excel 試算表 |
+| HTML | 網頁 |
+| CSV / JSON / XML | 文字結構化資料 |
+| 圖片 | EXIF 元資料 + OCR |
+| 音訊 | 元資料 + 語音轉文字 |
+| ZIP | 自動解壓處理內容 |
+| EPUB | 電子書 |
+| YouTube URL | 影片字幕擷取 |
+
+## CLI 使用
+
+```bash
+# 基本轉換
+markitdown document.pdf > output.md
+
+# 指定輸出檔
+markitdown document.pdf -o output.md
+
+# 從 stdin 讀取
+cat document.pdf | markitdown
+
+# 搭配 Azure Document Intelligence
+markitdown file.pdf -o output.md -d -e "<endpoint>"
+
+# 外掛管理
+markitdown --list-plugins
+markitdown --use-plugins file.pdf
+```
+
+## Python API
+
+### 基本用法
+
+```python
+from markitdown import MarkItDown
+
+md = MarkItDown()
+result = md.convert("document.pdf")
+print(result.text_content)
+```
+
+### 搭配 LLM 做圖片描述
+
+```python
+from markitdown import MarkItDown
+from openai import OpenAI
+
+client = OpenAI()
+md = MarkItDown(llm_client=client, llm_model="gpt-4o")
+result = md.convert("photo.jpg")
+print(result.text_content)
+```
+
+### 搭配 Azure Document Intelligence
+
+```python
+md = MarkItDown(docintel_endpoint="<endpoint>")
+result = md.convert("scan.pdf")
+```
+
+## 外掛系統
+
+外掛預設關閉，需明確啟用。
+
+### markitdown-ocr 外掛
+
+用 LLM vision 對 PDF、DOCX、PPTX、XLSX 做 OCR，不需額外 ML 套件：
+
+```bash
+pip install markitdown-ocr openai
+```
+
+第三方外掛可在 GitHub 搜尋 `#markitdown-plugin` 找到。
+
+## MCP 整合
+
+MarkItDown 提供 MCP server，可整合到 Claude Desktop 等 LLM 應用：
+
+```bash
+pip install markitdown-mcp
+```
+
+## Docker
+
+```bash
+docker build -t markitdown:latest .
+docker run --rm -i markitdown:latest < file.pdf > output.md
+```
--- a/mempalace-notes.md
+++ b/mempalace-notes.md
@@ -0,0 +1,94 @@
+# MemPalace 安裝與使用筆記
+
+## 基本資訊
+
+- **專案**: https://github.com/MemPalace/mempalace
+- **版本**: 3.3.0
+- **授權**: MIT
+- **需求**: Python 3.9+
+- **安裝日期**: 2026-04-15
+
+## 安裝
+
+```bash
+pip install mempalace
+```
+
+主要相依套件：ChromaDB（向量資料庫）、PyYAML、ONNX Runtime。
+
+## 核心概念
+
+MemPalace 用階層式結構組織記憶：
+
+- **Wing**（翼）— 對應一個專案或一個人
+- **Room**（房間）— 對應一個主題
+- **Drawer**（抽屜）— 原始內容（不做摘要，保留完整原文）
+
+所有資料存在本地，不需要雲端服務或 API key。
+
+## 常用指令
+
+### 初始化專案
+
+```bash
+mempalace init ~/projects/my_app
+mempalace init ~/projects/my_app --yes  # 非互動模式，自動接受
+```
+
+### 匯入資料
+
+```bash
+# 匯入專案檔案（程式碼、文件、筆記）
+mempalace mine ~/projects/my_app
+
+# 匯入對話記錄（Claude、ChatGPT、Slack 匯出檔）
+mempalace mine ~/chats/ --mode convos
+```
+
+### 搜尋
+
+```bash
+mempalace search "為什麼改用 GraphQL"
+mempalace search "定價討論" --wing my_app --room costs
+```
+
+### 其他指令
+
+```bash
+mempalace status                  # 查看已歸檔內容
+mempalace wake-up                 # 顯示 L0 + L1 喚醒上下文（~600-900 tokens）
+mempalace wake-up --wing my_app   # 特定專案的喚醒上下文
+mempalace compress                # 用 AAAK Dialect 壓縮（~30x）
+mempalace split <dir>             # 將合併的大檔拆成個別 session 檔
+mempalace repair                  # 重建向量索引（修復損壞）
+mempalace migrate                 # 跨 ChromaDB 版本遷移
+mempalace mcp                     # 顯示 MCP 設定指令
+```
+
+## Claude Code MCP 整合
+
+### 註冊 MCP Server
+
+```bash
+claude mcp add mempalace -- python -m mempalace.mcp_server
+```
+
+### 指定自訂 palace 路徑
+
+```bash
+claude mcp add mempalace -- python -m mempalace.mcp_server --palace /path/to/palace
+```
+
+### 直接啟動 MCP Server
+
+```bash
+python -m mempalace.mcp_server
+```
+
+註冊後，下次啟動 Claude Code 會自動載入，提供 29 個 MCP 工具可在對話中使用。
+
+## 目前設定
+
+- Palace 設定檔：`./mempalace.yaml`
+- MCP 設定位置：`~/.claude.json`（本專案範圍）
+- 預設 palace 存放路徑：`~/.mempalace/palace`
--- a/mempalace.yaml
+++ b/mempalace.yaml
@@ -0,0 +1,5 @@
+wing: '00'
+rooms:
+- name: general
+  description: All project files
+  keywords: []
--- a/playwright-notes.md
+++ b/playwright-notes.md
@@ -0,0 +1,250 @@
+# Playwright (Python) 安裝與使用筆記
+
+## 基本資訊
+
+- **專案**: https://github.com/microsoft/playwright-python
+- **版本**: 1.51.0
+- **作者**: Microsoft
+- **授權**: Apache-2.0
+- **需求**: Python 3.8+
+- **文件**: https://playwright.dev/python/docs/intro
+- **安裝日期**: 2026-04-15
+
+## 安裝
+
+```bash
+pip install playwright        # 安裝 Python 套件
+playwright install            # 下載瀏覽器（Chromium、Firefox、WebKit）
+playwright install chromium   # 只裝特定瀏覽器
+```
+
+### 已安裝的瀏覽器
+
+| 瀏覽器 | 版本 | 路徑 |
+|--------|------|------|
+| Chromium | — | ~/Library/Caches/ms-playwright/ |
+| Firefox | 135.0 | ~/Library/Caches/ms-playwright/firefox-1475 |
+| WebKit | 18.4 | ~/Library/Caches/ms-playwright/webkit-2140 |
+
+## 同步 API
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()          # 無頭模式
+    # browser = p.chromium.launch(headless=False)  # 有頭模式（看得到瀏覽器）
+    page = browser.new_page()
+    page.goto("https://example.com")
+    print(page.title())
+    page.screenshot(path="screenshot.png")
+    browser.close()
+```
+
+## 非同步 API
+
+```python
+import asyncio
+from playwright.async_api import async_playwright
+
+async def main():
+    async with async_playwright() as p:
+        browser = await p.chromium.launch()
+        page = await browser.new_page()
+        await page.goto("https://example.com")
+        print(await page.title())
+        await page.screenshot(path="screenshot.png")
+        await browser.close()
+
+asyncio.run(main())
+```
+
+## 常用操作
+
+### 選取元素與互動
+
+```python
+# 點擊
+page.click("text=登入")
+page.click("#submit-btn")
+page.click("button.primary")
+
+# 填寫表單
+page.fill("#username", "user@example.com")
+page.fill("#password", "secret")
+
+# 選擇下拉選單
+page.select_option("select#color", "blue")
+
+# 勾選 checkbox
+page.check("#agree")
+
+# 等待元素出現
+page.wait_for_selector(".result")
+
+# 取得文字內容
+text = page.text_content(".message")
+inner = page.inner_text("h1")
+```
+
+### 截圖與 PDF
+
+```python
+# 截圖
+page.screenshot(path="page.png")
+page.screenshot(path="full.png", full_page=True)
+
+# 特定元素截圖
+page.locator(".card").screenshot(path="card.png")
+
+# 存成 PDF（僅 Chromium 支援）
+page.pdf(path="page.pdf")
+```
+
+### Locator（推薦的選取方式）
+
+```python
+# 依角色
+page.get_by_role("button", name="送出")
+
+# 依文字
+page.get_by_text("歡迎光臨")
+
+# 依 label
+page.get_by_label("電子郵件")
+
+# 依 placeholder
+page.get_by_placeholder("搜尋...")
+
+# 依 test id
+page.get_by_test_id("login-form")
+
+# 鏈式操作
+page.locator(".card").filter(has_text="特價").first.click()
+```
+
+### 網路攔截
+
+```python
+# 攔截請求
+def handle_route(route):
+    if "analytics" in route.request.url:
+        route.abort()
+    else:
+        route.continue_()
+
+page.route("**/*", handle_route)
+
+# 攔截並修改回應
+def mock_api(route):
+    route.fulfill(
+        status=200,
+        content_type="application/json",
+        body='{"data": "mocked"}'
+    )
+
+page.route("**/api/data", mock_api)
+```
+
+### Browser Context（隔離環境）
+
+```python
+# 每個 context 有獨立的 cookies、localStorage
+context = browser.new_context(
+    viewport={"width": 1280, "height": 720},
+    locale="zh-TW",
+    timezone_id="Asia/Taipei",
+    user_agent="custom-agent",
+)
+page = context.new_page()
+
+# 帶裝置模擬
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    iphone = p.devices["iPhone 14"]
+    context = browser.new_context(**iphone)
+```
+
+### 等待與自動等待
+
+```python
+# Playwright 預設自動等待元素可操作後才執行動作
+# 以下是額外的等待方法：
+
+page.wait_for_load_state("networkidle")   # 等網路閒置
+page.wait_for_url("**/dashboard")         # 等 URL 變化
+page.wait_for_selector(".loaded")         # 等元素出現
+
+# 等待 response
+with page.expect_response("**/api/data") as response_info:
+    page.click("#load-btn")
+response = response_info.value
+```
+
+## CLI 工具
+
+### Codegen（自動產生程式碼）
+
+```bash
+# 打開瀏覽器錄製操作，自動產生 Python 程式碼
+playwright codegen https://example.com
+
+# 指定裝置模擬
+playwright codegen --device="iPhone 14" https://example.com
+
+# 指定語言
+playwright codegen --target python-async https://example.com
+```
+
+### Trace Viewer（除錯追蹤）
+
+```python
+# 錄製 trace
+context.tracing.start(screenshots=True, snapshots=True, sources=True)
+
+# ... 執行操作 ...
+
+context.tracing.stop(path="trace.zip")
+```
+
+```bash
+# 檢視 trace
+playwright show-trace trace.zip
+```
+
+### 其他 CLI
+
+```bash
+playwright open https://example.com       # 開啟瀏覽器
+playwright screenshot --help              # 截圖工具
+playwright install --with-deps            # 安裝瀏覽器 + 系統相依
+```
+
+## Pytest 整合
+
+```bash
+pip install pytest-playwright
+```
+
+```python
+# test_example.py
+def test_homepage(page):
+    page.goto("https://example.com")
+    assert page.title() == "Example Domain"
+
+def test_login(page):
+    page.goto("https://example.com/login")
+    page.fill("#username", "admin")
+    page.fill("#password", "password")
+    page.click("text=Login")
+    assert page.url == "https://example.com/dashboard"
+```
+
+```bash
+# 執行測試
+pytest
+pytest --headed                   # 顯示瀏覽器
+pytest --browser firefox          # 指定瀏覽器
+pytest --browser chromium --browser firefox  # 多瀏覽器
+```