diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..93ebbe5 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,20 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Purpose + +This is a personal knowledge base of tool installation and usage notes (工具安裝與使用筆記). Each file is a standalone Markdown note documenting a specific tool's setup, API, and common patterns. + +## Structure + +- `*-notes.md` — Individual tool notes (MarkItDown, MemPalace, Playwright) +- `mempalace.yaml` — MemPalace configuration for this directory (wing: `tool-notes`) + +There is no build system, test suite, or application code. All content is Markdown documentation. + +## Conventions + +- Notes are written in Traditional Chinese (繁體中文) +- Each note follows a consistent structure: basic info, installation, core usage, advanced features +- Notes preserve exact CLI commands and code snippets for reference diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..5f9a21c --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,70 @@ +# QUICKSTART + +三個工具的最短上手路徑。詳細說明請看各自的 `*-notes.md`。 + +--- + +## MarkItDown — 檔案轉 Markdown + +```bash +pip install 'markitdown[all]' +markitdown document.pdf > output.md +``` + +Python: + +```python +from markitdown import MarkItDown +print(MarkItDown().convert("document.pdf").text_content) +``` + +👉 詳情:[markitdown-notes.md](./markitdown-notes.md) + +--- + +## MemPalace — 本地記憶庫 + +```bash +pip install mempalace +mempalace init ~/projects/my_app # 初始化 +mempalace mine ~/projects/my_app # 匯入專案內容 +mempalace search "為什麼改用 GraphQL" # 搜尋 +``` + +註冊到 Claude Code: + +```bash +claude mcp add mempalace -- python -m mempalace.mcp_server +``` + +👉 詳情:[mempalace-notes.md](./mempalace-notes.md) + +--- + +## Playwright — 瀏覽器自動化 + +```bash +pip install playwright +playwright install chromium +``` + +最小範例(同步 API): + +```python +from playwright.sync_api import sync_playwright + +with sync_playwright() as p: + browser = p.chromium.launch() + page = browser.new_page() + page.goto("https://example.com") + page.screenshot(path="out.png") + browser.close() +``` + +錄製操作自動產生程式碼: + +```bash +playwright codegen https://example.com +``` + +👉 詳情:[playwright-notes.md](./playwright-notes.md) diff --git a/README.md b/README.md new file mode 100644 index 0000000..3506b5a --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +# tool-notes + +個人工具安裝與使用筆記(繁體中文)。每份筆記都是獨立的 Markdown 檔,記錄一項工具的安裝、API 與常用範例,方便日後查閱。 + +## 收錄工具 + +| 工具 | 用途 | 筆記 | +|------|------|------| +| **MarkItDown** | 把 PDF / Office / 音訊 / YouTube 等格式轉成 Markdown | [markitdown-notes.md](./markitdown-notes.md) | +| **MemPalace** | 階層式本地記憶庫(Wing / Room / Drawer),支援向量搜尋與 MCP 整合 | [mempalace-notes.md](./mempalace-notes.md) | +| **Playwright (Python)** | 瀏覽器自動化、E2E 測試、截圖與 PDF 輸出 | [playwright-notes.md](./playwright-notes.md) | + +## 目錄結構 + +``` +tool-notes/ +├── README.md # 本檔 +├── QUICKSTART.md # 三個工具的最短上手指令 +├── SUMMARY.md # 工具重點摘要與對照 +├── CLAUDE.md # 給 Claude Code 用的專案說明 +├── markitdown-notes.md +├── mempalace-notes.md +├── playwright-notes.md +└── mempalace.yaml # 本目錄的 MemPalace 設定 +``` + +## 撰寫慣例 + +- 以繁體中文(台灣用語)書寫 +- 每份筆記固定章節:基本資訊 → 安裝 → 核心用法 → 進階功能 +- 保留完整 CLI 指令與程式碼片段,可直接複製使用 +- 不做摘要式描述,以「可執行」為優先 + +## 如何新增一份筆記 + +1. 在根目錄建立 `-notes.md` +2. 依現有筆記結構填寫(可參考 `markitdown-notes.md` 作為模板) +3. 在 `README.md` 的「收錄工具」表格新增一列 +4. 在 `SUMMARY.md` 的對照表新增對應項目 + +## 遠端位置 + +- Gitea:`http://192.168.42.124:31337/timmy/tool-notes` diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..80e771e --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,51 @@ +# SUMMARY + +本 repo 收錄工具的重點摘要與對照,方便快速回憶「這個工具能做什麼、怎麼切入」。 + +## 一覽表 + +| 工具 | 類別 | 核心能力 | 語言 / 介面 | 授權 | +|------|------|----------|-------------|------| +| MarkItDown | 文件轉換 | PDF/Office/音訊/YouTube → Markdown | Python / CLI / MCP | MIT | +| MemPalace | 本地記憶庫 | 向量搜尋、階層式組織、LLM 壓縮 | Python / CLI / MCP | MIT | +| Playwright (Python) | 瀏覽器自動化 | 多瀏覽器控制、E2E 測試、截圖/PDF | Python / CLI | Apache-2.0 | + +## MarkItDown + +- **一句話**:把幾乎所有常見檔案格式轉成 Markdown 給 LLM 讀。 +- **亮點**: + - 支援 PDF、DOCX、PPTX、XLSX、HTML、圖片(EXIF + OCR)、音訊、ZIP、EPUB、YouTube 字幕。 + - 可接 LLM 對圖片做描述(`llm_client=OpenAI()`)。 + - 可接 Azure Document Intelligence 做高品質 OCR。 + - 有 MCP server(`markitdown-mcp`),能直接在 Claude Desktop 使用。 +- **適用時機**:資料前處理、把雜亂檔案餵給 LLM 前的清洗步驟。 + +## MemPalace + +- **一句話**:完全離線的階層式記憶庫,替 LLM 對話提供「長期記憶」。 +- **結構**:Wing(專案/人)→ Room(主題)→ Drawer(原始內容,不做摘要)。 +- **亮點**: + - 本機存放(ChromaDB),不需要雲端或 API key。 + - `wake-up` 指令產出約 600-900 tokens 的 L0+L1 上下文,適合塞進對話開頭。 + - AAAK Dialect 壓縮(約 30x)可進一步縮小 context。 + - 29 個 MCP 工具可在 Claude Code 對話中直接使用。 +- **適用時機**:想為某個專案或個人建立跨對話、可搜尋的長期記憶。 + +## Playwright (Python) + +- **一句話**:Microsoft 出品的瀏覽器自動化框架,官方支援 Chromium / Firefox / WebKit。 +- **亮點**: + - 同步與非同步 API 雙軌。 + - Locator API(`get_by_role`、`get_by_text`、`get_by_label` …)比 CSS selector 更穩定。 + - 預設「自動等待」元素可操作,減少 flaky test。 + - `codegen` 錄製操作直接產生程式碼;`trace viewer` 可視化除錯。 + - `pytest-playwright` 深度整合 pytest。 +- **適用時機**:E2E 測試、爬蟲、批次截圖/PDF、需要模擬真實瀏覽器行為的場景。 + +## 三者如何一起用? + +一個常見組合: + +1. 用 **Playwright** 抓取動態網頁或下載檔案。 +2. 用 **MarkItDown** 把下載的 PDF/DOCX 轉成 Markdown。 +3. 用 **MemPalace** 把 Markdown 匯入(`mempalace mine`)作為長期記憶,供後續 LLM 對話查詢。 diff --git a/mempalace.yaml b/mempalace.yaml index b452d26..8d8c15d 100644 --- a/mempalace.yaml +++ b/mempalace.yaml @@ -1,4 +1,4 @@ -wing: '00' +wing: tool-notes rooms: - name: general description: All project files