COMET

Codex–Obsidian Memory Exploration Toolkit

繁體中文 · English

COMET 是 Codex 桌面 App 的本機 Markdown 閱讀與知識探索插件。你可以直接在 Codex 中閱讀 Obsidian 相容的 Markdown 文件，選取文件內容加入標注，並連同問題 交給 AI agent 分析，不必在筆記軟體與 Codex 之間反覆複製貼上。

功能

• 透過 macOS 原生資料夾選擇器開啟既有 Vault，或選擇位置建立新知識庫。
• 直接在 Codex 中瀏覽與編輯 Markdown 文件。
• 使用 Milkdown Crepe 編輯表格、task list 與程式碼區塊；Properties 沿用 COMET 的結構化屬性面板，支援型別控制、行內清單與標籤、Vault tag 建議及 undo／redo。
• 以待辦看板集中管理帶有 task tag 的 Markdown；跨欄拖曳會同步更新 status Property。
• 選取文件中的文字、加入標注與留言，再交給 AI agent 回答或分析。
• 支援一次加入多則標注，每則保留筆記路徑、選取文字、留言與行號。
• 標注會附加到 Codex composer，只有在使用者送出問題時才交給 AI agent。
• 透過 MCP tools 安全地讀寫筆記；寫入預設關閉。

Obsidian Skills 來源

skills/obsidian-skills 是 kepano/obsidian-skills Git submodule， 目前固定於 commit a1dc48e68138490d522c04cbf5822214c6eb1202，採 MIT License。 此結構保留完整上游 repository，並由 COMET 的 Git commit 明確鎖定版本。

目前 COMET plugin 只打包 submodule 中的 obsidian-markdown；其餘 Skill 等對應 檔案格式或執行環境完成後再啟用。完整授權文字收錄於 NOTICE.md。

使用

安裝後建立新的 Codex task，選擇 @COMET，再輸入「開啟 COMET」。插件更新後 也必須使用新 task，既有 task 不會熱重載 MCP tools。

使用標注詢問 AI agent：

1. 在 COMET 中開啟 Markdown 文件並選取文字。
2. 視需要輸入標注留言，再按「加入聊天」。
3. 回到 Codex composer 輸入問題；送出後，AI agent 會同時取得問題與標注內容。

標注只存在於目前的聊天上下文，不會寫回 Markdown 文件。

開發架構

COMET 以 package 邊界分離 Host 整合、作業系統 adapter 與產品功能， 讓 Codex、Graph、Task 與 Markdown 可由不同貢獻者獨立維護。

COMET
│
├── @comet/codex
│   ├── Codex Plugin manifest 與安裝組裝
│   ├── Codex composer 標注
│   ├── OpenAI 專屬 metadata
│   └── Codex runtime／UI 入口與 fullscreen 顯示請求
│
├── @comet/runtime
│   ├── Node.js 與 stdio 執行入口
│   ├── fs/promises、檔案監控與作業系統垃圾桶
│   └── Vault registry
│
├── @comet/mcp
│   ├── MCP tools、schema 與 MCP Apps bridge
│   ├── Explorer workspace
│   ├── Note／Graph／Task 分頁組裝
│   └── Properties／Tag 編輯 UI
│
├── @comet/graph
│   ├── Graph 資料投影與 Layout 演算法
│   └── GraphPanel 與專屬樣式
│
├── @comet/task
│   ├── Task metadata 投影與 Dashboard
│   └── 狀態拖曳與專屬樣式
│
├── @comet/core
│   ├── Vault domain model、查詢與 mutation
│   └── 路徑、連結同步與 filesystem 抽象
│
└── @comet/markdown
    └── remark AST、frontmatter、Properties、wikilinks 與 tags

依賴方向固定為：

codex ──┬──→ runtime ──┬─→ mcp
        │              └─→ core
        └──→ mcp

mcp ────┬──→ graph ──────→ core
        ├──→ task ───┬───→ core
        │            └───→ markdown
        ├──→ core
        └──→ markdown

core ────────────────────→ markdown

@comet/codex 只能依賴通用 package，下層 package 不得反向依賴 Codex。Graph 與 Task 只要維持公開資料與 panel contract，就可獨立重新 設計，不需要修改 Core 或其他功能 package。

安裝

需求：Node.js 22+、Yarn Classic 1.x，以及支援 Plugins/MCP Apps 的 Codex App。

git clone --recurse-submodules https://github.com/Avery320/comet.git
cd comet
./scripts/install_comet

安裝器會安裝依賴、建置 COMET，並透過本機 marketplace 將插件加入 Codex； 不會上傳或發佈任何內容。完成後請建立新的 Codex task，選擇 @COMET。 Repository 根目錄是開發原始碼；可安裝的 plugin artifact 由安裝器建立於 dist/comet-local/plugins/comet。

更新時在 repository 執行 git pull 與 git submodule update --init --recursive，再重新執行同一個安裝指令。

開發驗證

yarn lint
yarn test

yarn test 會先建置所有 package 一次，再執行 unit 與 E2E 測試。

直接執行 ./scripts/launch_comet_mcp 只會啟動 stdio server，不會顯示 Codex UI。

開發與貢獻方式見 CONTRIBUTING.md，版本變更見 CHANGELOG.md。

寫入

設定 COMET_ALLOW_WRITES=true，或讓 ~/.config/comet/allow-writes 內容為 true，才會啟用寫入 tools。

啟用寫入後，使用文件右上角的單一按鈕切換閱讀與 Live Preview 編輯模式。 切回閱讀模式時會儲存修改；Cmd/Ctrl + S 可在不離開編輯模式時儲存。 編輯模式沿用文件的 Properties 面板，可直接修改、新增或移除屬性。

修改既有筆記必須先呼叫 preview_resource_update，再以回傳的 SHA-256 呼叫 update_resource；檔案已改變時會回傳 conflict，不會覆寫新內容。

授權

本專案採 MIT License。上游與第三方依賴歸屬見 NOTICE.md。COMET 並非 OpenAI 或 Obsidian 官方產品。