Joplin LLM Wiki
gcake119/joplin-llm-wiki
Base de conhecimento Joplin organizada por IA, rodando 100% local
Ver no GitHubMCP server que transforma sua base de conhecimento do Joplin em uma wiki compilada e organizada por IA. Exporta notas SQLite para markdown, compila resumos e conceitos com Ollama/Codex locais, e escreve tudo de volta ao Joplin com interface GUI incluída.
Instalação
npx convez-ai gcake119/joplin-llm-wiki1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Organizar e indexar automaticamente uma biblioteca de notas crescente no Joplin
- Gerar resumos, conceitos e índices cruzados a partir de notas brutas com LLMs locais
- Brainstorming e pesquisa estruturada com histórico armazenado de volta no Joplin
- Manter wiki editável e consultável direto na aplicação Joplin
Veredito

Solução robusta e bem arquitetada para quem precisa transformar caos de notas em conhecimento estruturado, rodando totalmente offline. GUI prática e fluxo claro, mas exige familiaridade com Joplin, CLI e modelos locais.
README
A tradução para o português deste README ainda está na fila.
joplin-llm-wiki
這是一套給 Joplin 用的本機知識庫整理工具。你可以把它想成:
- 從 Joplin Desktop 的
database.sqlite讀出筆記,轉成raw/Markdown。 - 用本機 Ollama 或本機已登入的 Codex CLI,把大量原始筆記整理成
wiki/裡的摘要、概念和索引。 - 把整理好的 wiki 寫回 Joplin 的
@llm-wiki筆記本,方便直接在 Joplin 裡閱讀。 - 需要問問題時,可以先查整理過的
wiki/,不夠再補看raw/原始筆記。
整套流程預設在本機跑;目前不使用 RAG、向量資料庫或 Chroma。若你只是想操作日常流程,可以先用 GUI,不一定要記 CLI 指令。
本專案部分引用 karpathy/442a6bf555914893e9891c11519de94f 與 gatelynch/llm-knowledge-base 的流程概念與 skill 設計。此 repo 不是上述專案的 fork 或 runtime dependency,而是把這些概念實作成以 Joplin 作為主要檢視與筆記管理介面的版本。
GUI
本 repo 內建一個本機 Joplin-LLM-wiki tool,可以用圖形介面做常見操作:
- 檢查設定檔、
raw/、wiki/和 Ollama 連線狀態。 - 編輯常用設定,並用
loadConfig驗證後再儲存。 - 從 Joplin SQLite 載入筆記本清單,勾選要匯出的筆記本。
- 執行初始化管線、只建立 raw 快照、重新編譯 wiki。
- 從 concepts 或 writeback 階段接續,支援 local 與 agent 模式的 dry-run / run。
- 查詢知識庫、確認 query capture、執行 lint。
- 在 macOS 上安裝或解除 Ollama +
sqlite-sync的 LaunchAgent stack。
啟動方式:
pnpm install
pnpm exec joplin-llm-wiki-health-gui --config ./config.yaml
如果你還沒有設定檔,先從 config.yaml.example 複製一份:
cp config.yaml.example config.yaml
pnpm exec joplin-llm-wiki-health-gui --config ./config.yaml
Joplin Plugin: Jarvis
本 repo 不內建向量索引,但很適合搭配 Joplin plugin Jarvis 使用。Jarvis 的 related notes / semantic search 可以在 Joplin 內即時找出與目前筆記、選取文字或搜尋語句語意相近的筆記;若 Jarvis 的向量化模型設定使用 bge-m3 這類多語、多粒度 embedding model,對中文與混合語言的全筆記庫 related notes 參照連結會更自然。
建議分工是:本 repo 負責從 Joplin SQLite 匯出 raw/、編譯 wiki/、並把整理後的 wiki 寫回 @llm-wiki;Jarvis 負責在 Joplin 使用介面中提供全筆記庫的即時語意相似筆記參照。這樣可保留本 repo 的可重建知識層,同時取得 Jarvis 在閱讀與寫作當下的 related notes 體驗。
知識流
| Layer | Path | Purpose |
|---|---|---|
| Raw library | raw/ | 未編輯的原始素材。SQLite 匯出會寫到這裡;人工長期維護內容不應放在這層。 |
| Wiki | wiki/summaries/*.md | 每個來源一份摘要,不建立子資料夾。 |
| Wiki | wiki/concepts/*.md | 概念條目,交叉引用 summaries/concepts,不建立子資料夾。 |
| Wiki | wiki/indexes/All-Sources.md、wiki/indexes/All-Concepts.md | 固定索引入口。 |
| Brainstorming | brainstorming/chat/、brainstorming/health/ | Query 確認後的探索紀錄、健檢與研究方向。 |
| Artifacts | artifacts/ | 完成的作品;Joplin 寫回時必須指定專案筆記本。 |
flowchart TD
SourceNotes["Joplin Desktop:一般筆記"]
Raw["raw/"]
Summaries["wiki/summaries/*.md"]
Concepts["wiki/concepts/*.md"]
Indexes["wiki/indexes/*.md"]
Query["query"]
Pending["pending capture"]
Brainstorming["brainstorming/chat/ 或 brainstorming/health/"]
Artifacts["artifacts/<project>/"]
WikiNotebook["Joplin Desktop:@llm-wiki/wiki"]
BrainstormNotebook["Joplin Desktop:@llm-wiki/brainstorming"]
ArtifactNotebook["Joplin Desktop:@llm-wiki/artifacts/<project>"]
SourceNotes -->|sqlite-sync 匯出| Raw
Raw -->|wiki-compile 或 agent-compile| Summaries
Summaries -->|concept stage| Concepts
Summaries --> Indexes
Concepts --> Indexes
Summaries -->|writeback stage| WikiNotebook
Concepts -->|writeback stage| WikiNotebook
Indexes -->|writeback stage| WikiNotebook
Summaries -->|查詢來源| Query
Concepts -->|查詢來源| Query
Indexes -->|查詢來源| Query
Raw -->|必要時補原始證據| Query
Query -->|值得保存| Pending
Pending -->|confirm capture| Brainstorming
Pending -->|confirm capture + artifact project| Artifacts
Brainstorming -->|按需 workflow writeback| BrainstormNotebook
Artifacts -->|按需 workflow writeback| ArtifactNotebook
BrainstormNotebook -->|workflow-sync pull| Brainstorming
ArtifactNotebook -->|workflow-sync pull| Artifacts
Brainstorming -->|workflow-writeback push| BrainstormNotebook
Artifacts -->|workflow-writeback push| ArtifactNotebook
閉環:
- 匯入:Joplin 筆記先進
raw/。這層是原始資料,通常不要手動改。 - 摘要:
wiki-compile或agent-compile先把 raw 轉成wiki/summaries/*.md與來源索引。 - 概念:concept stage 讀 summaries,依語意整理 canonical concepts,寫到
wiki/concepts/*.md與wiki/indexes/All-Concepts.md。 - 發布:writeback stage 才把已完成的 wiki Markdown 寫回 Joplin 的
@llm-wiki。 - 查詢:
query先看整理好的wiki/,必要時再補raw/原始內容。 - 沉澱:有價值的 Q&A 先形成 pending capture,確認後才寫到
brainstorming/chat/或artifacts/<project>/,不直接污染wiki/。 - Lint:
lint以檔案系統檢查 wiki 佈局、frontmatter、連結、缺漏索引與未沉澱的 brainstorming。
Codex / Cursor MCP
本 repo 也提供本機 MCP server,讓 Codex、Cursor 或其他 MCP client
可以在對話中用 structured tools 操作同一套知識流。MCP 只透過 stdio
包裝既有 CLI/service 行為,不開公網 HTTP listener,也不改變
raw/、wiki/、brainstorming/、artifacts/ 的資料邊界。
MCP 的對話設計是「一個 skill 作為入口,LLM 判斷知識流階段,MCP tools
執行確定性動作」。joplin-knowledge-flow skill 只提供操作規則與
guardrails;真正讀寫檔案、同步 Joplin、編譯 wiki 或歸檔 project 的行為
都由 MCP server tools 執行。
常見意圖與 tool 對應:
| Intent | Tool |
|---|---|
| 查詢本機知識庫 | joplin_query |
| 發散、整理想法 | joplin_brainstorm |
| 查看 pending capture | joplin_show_capture |
| 確認保存 query/brainstorm 結果 | joplin_confirm_capture |
| Project 歸檔前建議命名 | joplin_suggest_archive_project |
| 使用者確認 project 名稱後歸檔 | joplin_archive_project |
| 同步 Joplin sources | joplin_sync_sources |
| 編譯 wiki | joplin_compile_wiki |
Skills 搭配知識沉澱
在本次追蹤實作中,installer 會同時安裝兩個全域 skills:
joplin-knowledge-flow:知識流操作入口,負責把 LLM 導向 MCP tools。knowledge-capture-policy:通用政策(Reusable policy),判斷「常見 skill 成果」是否值得建立 pending capture。
目前只在已整合鏈結上啟用該政策:joplin-knowledge-flow 已接上 knowledge-capture-policy。
spectra-archive、spectra-debug、how、superpowers:brainstorming 等其他 common-skill hooks 僅記錄於 docs/superpowers/plans/2026-06-05-knowledge-capture-external-hooks.md,並標註為「需明確使用者授權」的外部/ignored patch notes,尚未自動啟用。
第一版採用「草稿型 + 規則型」:
- 強訊號工作:當
knowledge-capture-policy判定為 strong signal 時,該 skill 可直接呼叫joplin_brainstorm產生 pending capture 草稿(例如 Spectra archive 完成、debug root cause 驗證完成、架構 mental model 收斂)。 - 中訊號工作:可提示「可能值得沉澱」但不直接草擬。
- 低訊號工作不提示。
- 任何正式寫入都必須由使用者確認,才會透過
joplin_confirm_capture寫入brainstorming/chat/或artifacts/<project>/;或先呼叫joplin_suggest_archive_project,再由使用者確認後由joplin_archive_project寫入。
在 knowledge-capture-policy 的自動判斷流程中,這個流程不會自動寫入
brainstorming/chat/、artifacts/<project>/、raw/ 或 wiki/;不影響 MCP
其他 tool 的正常行為(例如 joplin_sync_sources、joplin_compile_wiki)。若
MCP server 沒有載入,skill 應提示重啟或重新載入 Codex/Cursor,而不是改用
手寫檔案。
快速安裝
這是快速安裝 MCP server 的指令。它會自動把 repo clone 到本機、安裝
dependencies、建立 joplin-llm-wiki-mcp 啟動 shim,並在指定時寫入
Codex/Cursor 的 MCP 設定;使用者不需要先手動 clone 這個專案。
安裝前請先確認本機有:
git- Node.js 20+
pnpm
只安裝 MCP server 並輸出設定範例:
curl -fsSL https://raw.githubusercontent.com/gcake119/joplin-llm-wiki/main/scripts/install-mcp.sh | bash
同時寫入 Cursor 或 Codex 的 MCP 設定:
curl -fsSL https://raw.githubusercontent.com/gcake119/joplin-llm-wiki/main/scripts/install-mcp.sh | bash -s -- --client cursor
curl -fsSL https://raw.githubusercontent.com/gcake119/joplin-llm-wiki/main/scripts/install-mcp.sh | bash -s -- --client codex
curl -fsSL https://raw.githubusercontent.com/gcake119/joplin-llm-wiki/main/scripts/install-mcp.sh | bash -s -- --client both
預設安裝到 $HOME/.local/share/joplin-llm-wiki。若要指定安裝位置:
curl -fsSL https://raw.githubusercontent.com/gcake119/joplin-llm-wiki/main/scripts/install-mcp.sh | bash -s -- --client both "$HOME/.local/share/joplin-llm-wiki"
安裝後,還需要在安裝目錄準備 config.yaml,並依自己的 Joplin 環境設定
Joplin SQLite、raw、wiki、Ollama、Joplin Data API / Web Clipper token
等必要欄位。最小啟動流程:
cd "$HOME/.local/share/joplin-llm-wiki"
cp config.yaml.example config.yaml
$EDITOR config.yaml
pnpm exec joplin-llm-wiki lint --config ./config.yaml
設定完成後,重啟 Codex/Cursor,或在 Cursor 執行 Reload Window,讓 MCP client 重新載入 server 設定。
Cursor 設定可參考 .cursor/mcp.json.example:
{
"mcpServers": {
"joplin-llm-wiki": {
"command": "pnpm",
"args": [
"exec",
"joplin-llm-wiki-mcp"
],
"cwd": "/Users/caiyijun/joplin-llm-wiki"
}
}
}
可用 tools:
| Tool | Purpose |
|---|---|
joplin_query | 從 wiki/ 優先、必要時補 raw/ 回答問題,並可建立 pending capture。 |
joplin_show_capture | 讀取 pending capture,不修改檔案。 |
joplin_confirm_capture | 確認 pending capture,寫入 brainstorming/chat/ 或 artifacts/<project>/。 |
joplin_brainstorm | 以 query 流程進行探索,預設偏向 brainstorming capture。 |
joplin_suggest_archive_project | Project 歸檔前提供 2-3 個 project 名稱建議。 |
joplin_archive_project | 使用已確認的 project 名稱,把成品寫入 artifacts/<project>/。 |
joplin_sync_sources | 包裝 sqlite-sync 的 normal、export-only、snapshot-only 模式。 |
joplin_compile_wiki | 包裝 wiki-compile 或 agent-compile。 |
joplin_sync_workflow_notes | 從 Joplin @llm-wiki/brainstorming / @llm-wiki/artifacts 按需拉回工作目錄檔案。 |
joplin_writeback_workflow_notes | 從 workspace brainstorming/ / artifacts/ 按需寫回 Joplin 既有 workflow notes。 |
Existing Note Updates And Data API
MCP tools remain the default path for query、capture、archive、source sync、workflow pull sync 與 wiki compile。若使用者明確要求補充或修改 Joplin 裡既有筆記,而且目前暴露的 MCP tools 沒有既有 note update tool,可以使用本機 Joplin Data API 作為受控寫入路徑。
規則:
- 先用 MCP 或唯讀 SQLite 查明目標 notebook / note id / title;SQLite 只能當 discovery evidence,不可直接更新
database.sqlite。 - 必須先確認使用者指定或同意要修改的既有筆記。
- 寫入前確認 Joplin Desktop 的 Web Clipper service 已啟用,
joplin_data_api.base_url必須是 loopback,例如http://127.0.0.1:41184。 - 在 Codex sandbox 裡若
curl http://127.0.0.1:41184/ping失敗,但使用者或截圖確認 Web Clipper service 已啟動,應以 sandbox escalation 重試同一個 loopback call;不要改用 SQLite 直寫。 - Data API token 只從 config 讀取,不要印到輸出、筆記或 tool result 摘要。
- 對既有 note append 補充時使用穩定 marker,避免重複寫入;更新後以只讀查詢確認 marker 或內容存在。
- 若 Data API 不可用或 token 失效,停止並請使用者啟用 Web Clipper / 更新 token;不要 fallback 成 ad hoc 檔案寫入。
Project 歸檔必須先呼叫 joplin_suggest_archive_project 取得建議命名,
再由使用者確認 project 名稱。joplin_archive_project 必須收到
confirmed_project: true 才會寫入正式 artifact;未確認時會回傳
PROJECT_CONFIRMATION_REQUIRED 且不寫檔。新 project artifact 路徑固定為
artifacts/<project>/<timestamp>-<slug>.md,不要使用
artifacts/projects/<project>/。
完整 MCP 設定與工具語意見 docs/codex-cursor-mcp.md。
CLI 指令
GUI 之外,也可以用 CLI 做同樣的事,適合排程、自動化或除錯:
pnpm exec joplin-llm-wiki sqlite-sync --config ./config.yaml --export-only
pnpm exec joplin-llm-wiki sqlite-sync --config ./config.yaml --snapshot-only
pnpm exec joplin-llm-wiki wiki-compile --config ./config.yaml
pnpm exec joplin-llm-wiki agent-compile --config ./config.yaml
pnpm exec joplin-llm-wiki workflow-sync --config ./config.yaml --dry-run
pnpm exec joplin-llm-wiki workflow-writeback --config ./config.yaml --dry-run
pnpm exec joplin-llm-wiki query --config ./config.yaml "你的問題"
pnpm exec joplin-llm-wiki query --config ./config.yaml --confirm-capture "<id>"
pnpm exec joplin-llm-wiki lint --config ./config.yaml
Concept Resume Recovery
若已完成 wiki/summaries/*.md,但 concept 產生或 Joplin 寫回出現錯誤,可以先暫停 sqlite-sync 排程,從下游階段接續,不必重新為所有 raw 筆記產生單篇摘要。
pnpm exec joplin-llm-wiki wiki-compile --config ./config.yaml --resume-stage concepts --dry-run
pnpm exec joplin-llm-wiki wiki-compile --config ./config.yaml --resume-stage concepts
pnpm exec joplin-llm-wiki wiki-compile --config ./config.yaml --resume-stage writeback --dry-run
pnpm exec joplin-llm-wiki wiki-compile --config ./config.yaml --resume-stage writeback
pnpm exec joplin-llm-wiki agent-compile --config ./config.yaml --resume-stage concepts --dry-run
pnpm exec joplin-llm-wiki agent-compile --config ./config.yaml --resume-stage concepts
pnpm exec joplin-llm-wiki agent-compile --config ./config.yaml --resume-stage writeback --dry-run
pnpm exec joplin-llm-wiki agent-compile --config ./config.yaml --resume-stage writeback
Concept resume 只讀既有 wiki/summaries/*.md,local 模式用 Ollama、agent 模式用本機 codex exec 依 summary evidence 判斷 canonical concepts,然後只寫 wiki/concepts/*.md 與 wiki/indexes/All-Concepts.md。Writeback resume 才會寫入 Joplin,且只處理 wiki/concepts/*.md 與 wiki/indexes/All-Concepts.md,不重送 summaries。
完整編譯與 resume 都遵守同一個發布邊界:concepts 全部在本機寫完後,才進入 Joplin writeback。Dry-run 不會改寫 wiki 或 Joplin。若 dry-run 顯示 Joplin concept collision 或 orphan candidates,先檢查輸出再決定是否修復;一般 writeback 只會 create/update,不會自動刪除舊 note。需要回復時,可先保留已暫停排程,手動移開錯誤的 wiki/concepts/*.md 或修正 Joplin duplicate note,再重跑 dry-run。
Config
Minimal config:
raw: ./raw
raw_glob: "**/*.md"
wiki: ./wiki
wiki_glob: "**/*.md"
wiki_schema:
path: ./wiki-schema.example.yaml
strict: true
joplin_wiki_writeback:
enabled: false
ollama:
base_url: http://127.0.0.1:11434
chat_model: gemma4:e4b
timeout_ms: 120000
預設資料夾 raw/ 與 wiki/ 已列入 .gitignore。
SQLite Sync Change Gate
sqlite-sync 可在每次匯出後偵測 raw/ 是否有實質變更,再依設定同步 wiki 層:
joplin_sqlite_sync:
enabled: true
database_path: "/ABS/PATH/database.sqlite"
pipeline:
compile_mode: local # local | agent | off
schedule:
every_seconds: 600 # null 表示單輪執行;設秒數才會常駐輪詢
local:偵測到 raw 新增、更新或刪除後執行wiki-compile。agent:偵測到 raw 變更後執行agent-compile,走本機已登入的codex exec。off:只匯出與更新快照狀態,不自動編譯。
狀態檔預設寫在 config 同目錄下的 .joplin-llm-wiki/sqlite-sync-state.json,不放在 raw/,避免 reconcile_mode: mirror 清理。
第一次非 dry-run 同步只建立 baseline,不觸發編譯;之後以 raw-relative path、joplin_note_id 與 Markdown 內容 SHA-256 判斷變更。--export-only 仍會匯出並更新狀態但不編譯;--snapshot-only 只掃現有 raw/ 建立 baseline,不開 SQLite、不刪檔、不編譯,適合 raw/ 已有資料時接上自動變更偵測。
定時檢查不是檔案系統 watcher。要自動週期檢查 SQLite/raw snapshot,必須讓 sqlite-sync 以常駐輪詢或外部排程執行:設定 joplin_sqlite_sync.schedule.every_seconds、CLI 使用 --every <seconds>,或由 launchd/cron 定期啟動。若 every_seconds: null 且沒有 --every,sqlite-sync 只跑一輪後結束。
狀態提交點在 downstream 成功之後:若 raw 已變更且 compile_mode 是 local 或 agent,sqlite-sync 會把變動 raw 對應到變動 summaries,再只重編受影響 concepts,最後只把變動的 downstream relPaths 寫回 Joplin。只有 preflight、compile 與 writeback 全部成功後才更新 .joplin-llm-wiki/sqlite-sync-state.json。若 token 無效、Data API 不通、agent-compile 或 wiki-compile 失敗,state 會保留在上一個已成功處理的 snapshot,下一輪仍會重試同一批 raw 變更。每輪 stdout JSON 會包含 state_committed、state_commit_reason、downstream_status、writeback_preflight_status、changed_summary_paths 與 writeback_relpaths。
macOS LaunchAgent 範本使用 RunAtLoad 啟動;正常週期仍建議由 schedule.every_seconds 的單一常駐行程負責。plist 的 KeepAlive.SuccessfulExit=false 只用來在非零退出時受控重啟,並搭配 ThrottleInterval 限速;不要再同時加 StartInterval 與非空 every_seconds,避免重疊執行。LaunchAgent wrapper 會依 resolved compile_mode 做 readiness:agent 與 off 不等待 Ollama,local 才等待 Ollama /api/tags。
Joplin Writeback
啟用 joplin_wiki_writeback 時必須設定本機 Joplin Web Clipper / Data API token,且 base_url hostname 只能是 127.0.0.1、localhost 或 ::1。
joplin_data_api:
base_url: http://127.0.0.1:41184
token: "<clipper-token>"
joplin_wiki_writeback:
enabled: true
parent_notebook_title: "@llm-wiki"
wiki_notebook_title: wiki
brainstorming_notebook_title: brainstorming
artifacts_notebook_title: artifacts
artifacts_project_notebook_title: ProjectA # 僅 artifacts 按需寫回時需要
wiki-compile / agent-compile 非 dry-run 成功後,若 joplin_wiki_writeback.enabled 為 true,會在本機 wiki 編譯完成後才進入 Joplin writeback。透過 sqlite-sync 自動編譯時,只有 raw snapshot 有變更才會觸發 downstream compile/writeback,且只寫回本輪變動的 compiled wiki relPaths:
@llm-wiki/wiki/summaries@llm-wiki/wiki/concepts@llm-wiki/wiki/indexes
brainstorming/ 與 artifacts/ 不會跟著 wiki compile 自動同步;只有需要整理問答、健康報告或作品時才按需寫回:
@llm-wiki/brainstorming/chat@llm-wiki/brainstorming/health@llm-wiki/artifacts/<artifacts_project_notebook_title>
如果你在 Joplin 的 @llm-wiki/brainstorming/... 或 @llm-wiki/artifacts/...
直接編輯 workflow 筆記,可用明確的 pull sync 把 Joplin 內容同步回工作目錄:
pnpm exec joplin-llm-wiki workflow-sync --config ./config.yaml --dry-run
pnpm exec joplin-llm-wiki workflow-sync --config ./config.yaml --section brainstorming
pnpm exec joplin-llm-wiki workflow-sync --config ./config.yaml --section artifacts
workflow-sync 只處理 brainstorming/ 與 artifacts/,不改寫 raw/ 或
compiled wiki/。Dry-run 只列出 created、updated、unchanged、
skipped、conflicts、errors 與 changed_files,不建立目錄也不寫檔。
遇到重名、未知 workflow folder 或路徑穿越候選時會列入 summary,不會靜默覆蓋檔案。
如果 agent 或你在 workspace 直接修改了 brainstorming/ 或 artifacts/
Markdown,可用反方向的 workflow writeback 把內容寫回 Joplin Desktop 對應的既有 note:
pnpm exec joplin-llm-wiki workflow-writeback --config ./config.yaml --dry-run
pnpm exec joplin-llm-wiki workflow-writeback --config ./config.yaml --dry-run=false --section brainstorming
pnpm exec joplin-llm-wiki workflow-writeback --config ./config.yaml --dry-run=false --section artifacts
workflow-writeback 只處理 brainstorming/ 與 artifacts/,不處理 raw/
或 compiled wiki/,且只透過 Joplin Desktop Data API 更新既有 note,不直接寫
SQLite。預設一定是 dry-run;只有明確傳入 --dry-run=false 才會寫入 Joplin。
workspace path 會依 notebook tree 對應回 Joplin,例如
artifacts/開發框架/AI UI 設計流程:從第零步視覺概念到上線前檢查.md
會對應到
@llm-wiki/artifacts/開發框架/AI UI 設計流程:從第零步視覺概念到上線前檢查,
brainstorming/chat/*.md 會對應到 @llm-wiki/brainstorming/chat。
第一版不自動新增 Joplin notes;找不到對應 note 或 notebook 時會列為
would_create / missing,不會誤寫。若同一路徑在 Joplin 對到多個同名 note,
會列為 conflict 並跳過。同步後會維護
.joplin-llm-wiki/workflow-sync-state.json 作為 baseline;若之後 workspace
與 Joplin note 都相對 baseline 變更,會列為 both_sides_changed conflict,
不自動 merge。
wiki-compile --dry-run 與 agent-compile --dry-run 不會對 Joplin 發送會變更資料的 HTTP。
若 sqlite-sync 的 automatic compile 在 writeback preflight 顯示 writeback_preflight_status: "failed",先確認 Joplin Desktop 的 Web Clipper 服務已啟用、joplin_data_api.base_url 是 loopback、joplin_data_api.token 是目前 Clipper token。若在 Codex sandbox 內 ping loopback 失敗,但 Joplin 顯示 Web Clipper 已在該 port 啟動,應用 sandbox escalation 重試 Data API 連線;不要直接寫 SQLite。修正後重新跑同一個 sqlite-sync 即可;因 state 未提交,raw 變更會被重試。
Query Capture
query 預設會讓 LLM 判斷問答是否值得保存。若值得保存,CLI 只會建立 .joplin-llm-wiki/pending-captures/<id>.json 並列出 CAPTURE_DRAFT,不會直接寫正式筆記。確認後才落地:
pnpm exec joplin-llm-wiki query --config ./config.yaml --confirm-capture "<id>"
pnpm exec joplin-llm-wiki query --config ./config.yaml --confirm-capture "<id>" --artifact-project ProjectA
Pending capture ID 的時間前綴預設維持 UTC Z 格式,例如
2026-05-25T11-46-36-845Z-<slug>-<hash>。若希望新建立的
capture_draft_id 反映臺灣本地時間,可在 config.yaml 設定:
knowledge_flow:
pending_capture_id_timezone: Asia/Taipei
設定後,新 ID 會使用 GMT+8 本地時間前綴,例如
2026-05-25T19-46-36-<slug>-<hash>。既有 UTC Z ID 不需要 migration,
仍可用 joplin_show_capture 讀取,也可用 joplin_confirm_capture 或
query --confirm-capture "<id>" 確認。
--capture=brainstorming 或 --capture=artifacts 可強制提出指定分類的 capture;分類只會是 brainstorming 或 artifacts。若加 --writeback-workflow=true,確認後只把該次確認的 note 按需寫回 Joplin。
Development
pnpm test
pnpm vitest run test/config-schema.test.js
pnpm test 是本 repo 的 Vitest full-suite 入口。需要只跑單一測試檔時,
使用 pnpm vitest run <path>。