前言¶

DeepSeek Harness（DSH）的 agent 需要穩定的記憶工具來管理學習資料。墨墨記憶卡（Markji，即 maimemo）是常用的間隔重複記憶工具，但官方 API 每次操作都會請求雲端，大量讀寫時延遲明顯，且沒有本地隊列、衝突處理和崩潰恢復機制。

dsh-markji-bridge 插件爲 DSH agent 提供了一套完整的 Markji 卡片管理能力：本地 SQLite 緩存、純文本搜索、寫入隊列、三方合併、衝突解決、歸檔操作以及支持崩潰恢復的後臺同步。

插件概覽¶

dsh-markji-bridge 是一個 DSH 插件，用於在本地維護 Markji 卡片緩存，讓 agent 可以搜索、閱讀、新建、修改、歸檔卡片。所有修改先寫入本地隊列，再按「先拉取、三方合併、後推送」的順序同步到雲端，衝突單獨報告，不影響其他卡片。

插件只註冊 4 個按 action 組織的工具：
- markji_decks：卡組 / 章節管理
- markji_cards：卡片讀寫、搜索、語法、歸檔、移動
- markji_sync：同步、進度、狀態、失敗與衝突
- markji_file：文件上傳 / 查詢

插件只用 Node 內置模塊實現，無第三方依賴。

核心功能¶

本地緩存¶

插件在本地維護一個 SQLite 文件 cache.db，包含索引、卡片正文、待推送隊列、衝突和同步任務。日常搜索和閱讀不請求 API，速度更快。

純文本搜索¶

每張卡另存一列去掉格式標記、圖片 / 音頻標記、data URI 和 base64 的純文本，搜索只匹配純文本，結果乾淨可讀。

安全寫入¶

修改先排隊，推送前先拉取遠端變更並三方合併，不會用舊數據覆蓋雲端。衝突按卡片去重，可逐條解決。

語法幫助、批量操作、寫前校驗與媒體預檢¶

markji_cards({ action: "syntax_help" }) 可按格式或全部查詢原始 Markji 語法
action=validate 支持單條 content、多條 contents 或按 cards 批量校驗，只檢查正文，不生成或改寫內容
推送前會檢查正文裏的圖片 / 音頻文件是否可用

後臺同步¶

同步任務立即返回句柄，可查進度。進程崩潰或插件重啓後用同一句柄續跑，不重複創建雲端對象。

如果 DSH 加載了 dsh-tool-jobs，markji_sync({ action: "start" }) 還會把任務登記爲當前會話擁有的 DSH 後臺任務，返回 job_id。任務出現在「正在運行的後臺任務」中，可用 job_output 查看，結束後由 DSH 發送完成通知。終止後臺任務會在下一個檢查點取消同步，任務變爲 interrupted，仍可 resume。

歸檔與章節操作¶

markji_cards({ action: "archive" }) 把卡片移入同卡組「歸檔」章節並在正文插入歸檔說明，重複調用冪等
markji_decks 支持章節詳情、新建、重命名和排序（provider 不提供章節刪除接口）

多進程安全¶

同一臺機器的多個 DSH 進程可共用一個緩存目錄，寫入通過文件鎖串行。

安裝與啓用¶

前置要求¶

DSH 0.2.x 的 Host 插件環境
Node >= 22.13（使用內置 node:sqlite，無需啓動參數）
Windows / macOS / Linux

安裝步驟¶

從 GitHub 獲取源碼後，把目錄安裝爲 DSH bundle：

git clone https://github.com/Oxmyxo/dsh-markji-bridge.git dsh-markji-bridge

plugin_manager install_bundle  target=<倉庫目錄的絕對路徑>

升級時：

git pull

plugin_manager remove_bundle   target=dsh-markji-bridge
plugin_manager install_bundle  target=<倉庫目錄的絕對路徑>

只改了 lib/ 裏的代碼時，停用再啓用插件即可加載新代碼：

plugin_manager set_plugin  target=include:dsh-markji-bridge  enabled=false
plugin_manager set_plugin  target=include:dsh-markji-bridge  enabled=true

配置 token¶

在 DSH 主機進程的環境變量裏設置 Markji OpenAPI token：

# Windows：設置用戶環境變量後重啓 DSH
setx MAIMEMO_MARKJI_OPENAPI_TOKEN "<你的 token>"

# macOS / Linux：寫入 shell 配置後重開終端
export MAIMEMO_MARKJI_OPENAPI_TOKEN="<你的 token>"

token 不要提交到倉庫或寫進配置文件。插件配置裏的 apiKey 可以覆蓋 token，但會以明文保存在 profile 配置中，一般不需要。

典型用法¶

列出卡組¶

markji_decks({ action: "list", refresh: true })

讀取卡組詳情¶

markji_decks({ action: "get", deck: "<deck_id>" })

讀取章節及卡片摘要¶

markji_decks({ action: "chapter_get", chapter: "<chapter_id>", with_cards: true })

搜索卡片¶

markji_cards({ action: "search", query: "排序", deck_name: "算法" })

讀取單張或多張卡¶

markji_cards({ action: "get", card: "<card_id>" })
markji_cards({ action: "get", cards: ["<card_id_1>", "<card_id_2>"] })

查語法幫助¶

markji_cards({ action: "syntax_help" })
markji_cards({ action: "syntax_help", format: "picture" })

校驗正文¶

markji_cards({ action: "validate", content: "<Markji 富文本>" })
markji_cards({ action: "validate", cards: ["<card_id_1>", "<card_id_2>"] })
markji_cards({ action: "validate", contents: ["<Markji 富文本 1>", "<Markji 富文本 2>"] })

啓動同步¶

markji_sync({ action: "start", mode: "auto" })

首次調用會拉取雲端數據（卡片多時需要一點時間），之後讀操作走本地緩存。狀態和進度用 markji_sync({ action: "state" }) / markji_sync({ action: "progress" }) 查看。若 DSH 加載了 dsh-tool-jobs，start 還會返回 job_id。

批量操作¶

需要一次處理多張卡時，用 markji_cards 的這些 action：

markji_cards({ action: "get", cards: ["<id1>", "<id2>"] })
markji_cards({ action: "validate", cards: ["<id1>", "<id2>"] })
markji_cards({ action: "validate", contents: ["<正文1>", "<正文2>"] })
markji_cards({ action: "create", deck: "<deck>", chapter: "<chapter>", new_cards: [
  { content: "<正文1>" },
  { content: "<正文2>", deck: "<deck2>", chapter: "<chapter2>" },
] })
markji_cards({ action: "update", updates: [
  { card: "<id1>", content: "<新正文1>" },
  { card: "<id2>", content: "<新正文2>" },
] })
markji_cards({ action: "archive", cards: ["<id1>", "<id2>"] })
markji_cards({ action: "move", cards: ["<id1>", "<id2>"], to_chapter: "<chapter>" })

單次最多 50 項（多卡讀取、語法校驗的 contents / cards、new_cards、updates）；歸檔和移動使用非空數組
action=get 默認不返回冗餘的 text，需要時傳 include_text: true
寫操作不是事務，壞項會被記錄，其他項仍會排隊。成功項仍需 markji_sync({ action: "start" }) 推送
批量語法檢查只做本地語法校驗，不查詢媒體文件是否存在；markji_sync 推送前仍會做媒體預檢
批量輸出可能超過 maxOutputChars，內容多時請拆小批次

工具與 action¶

插件只註冊 4 個工具，具體操作由 action 選擇：

工具	默認 action	作用
`markji_decks`	`list`	卡組列表 / 詳情，章節列表 / 詳情 / 新建 / 重命名 / 排序
`markji_cards`	`list`	卡片列表、搜索、讀取、新建、修改、移動、歸檔、語法幫助與校驗
`markji_sync`	`start`	啓動同步、查看進度 / 插件狀態 / 失敗、解決衝突
`markji_file`	無（必填）	上傳文件到 Markji 或查詢文件信息

markji_decks 的 action¶

action	作用
`list`	列出文件夾與卡組
`get`	讀一個卡組及其章節
`chapter_list`	列出一個或全部卡組的章節
`chapter_get`	讀一個章節，可帶卡片摘要
`chapter_create` / `chapter_rename` / `chapter_sort`	新建 / 重命名 / 排序章節

markji_cards 的 action¶

action	作用
`list` / `search`	分頁、過濾或按卡組名 / 章節名 / 更新時間搜索
`get`	按 id 讀一張或多張卡；未知 id 逐項報告
`create`	用 `new_cards` 批量新建，支持跨章節 / 卡組
`update`	改一張（`card` + `content`）或多張（`updates`）
`move` / `archive`	移動到其他章節 / 歸檔到「歸檔」章節
`validate` / `syntax_help`	校驗正文或已有卡片 / 查原始 Markji 語法

markji_sync 的 action¶

action	作用
`start`	啓動後臺同步（pull / push / auto，可 resume）
`progress`	查看同步任務進度與歷史
`state`	插件與緩存總覽
`failures`	查看失敗卡片、衝突與恢復建議
`resolve`	解決衝突（keep_local / keep_remote / use_content）

markji_file 的 action¶

action	作用
`upload` / `query`	上傳文件 / 查詢文件信息

2.1.0 新增：同步接入 DSH 後臺任務¶

markji_sync({ action: "start" }) 的返回值新增可選字段 job_id。當 DSH 加載了 dsh-tool-jobs 且調用來自一個活動會話時，插件會把同步任務登記爲該會話擁有的 DSH 後臺任務：任務出現在 DSH 的「正在運行的後臺任務」中，進度隨同步階段更新，job_output 可讀取任務結果，任務結束（完成 / 失敗 / 被終止）時由 DSH 發送標準完成通知。

未加載 dsh-tool-jobs 或調用不是來自會話時，沒有 job_id，行爲與 2.0.0 相同。終止該 DSH 後臺任務會在下一個檢查點取消同步：已寫入的隊列不丟，任務狀態變爲 interrupted，之後可用 markji_sync({ action: "start", resume: "<task_id>" }) 續跑。markji_sync 的 progress / state / failures / resolve 仍然可用。

2.0.0 遷移：舊工具名¶

2.0.0 不再註冊 1.x 的細粒度工具；舊調用改成一個工具加 action。字段基本不變，只有新建批量字段改爲 new_cards：

1.x 工具	2.0.0 調用
`markji_chapters` / `markji_chapters_edit`	`markji_decks` 的 `chapter_list` / `chapter_get` / `chapter_create` / `chapter_rename` / `chapter_sort`
`markji_search`	`markji_cards` 的 `search`
`markji_card_get` / `markji_cards_get`	`markji_cards` 的 `get`
`markji_card_syntax`	`markji_cards` 的 `validate` 或 `syntax_help`
`markji_card_create` / `markji_cards_create`	`markji_cards` 的 `create`（批量字段爲 `new_cards`）
`markji_card_update`	`markji_cards` 的 `update`
`markji_card_archive` / `markji_cards_move`	`markji_cards` 的 `archive` / `move`
`markji_sync_status`	`markji_sync` 的 `progress`
`markji_status`	`markji_sync` 的 `state`
`markji_failures`	`markji_sync` 的 `failures`
`markji_conflict`	`markji_sync` 的 `resolve`

適用場景與注意¶

適合需要通過 DSH agent 管理 Markji 卡片的場景，尤其是需要批量操作、本地緩存、衝突解決和後臺同步的場景
插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證
插件要求 Node >= 22.13，DSH 0.2.x 環境
token 不要提交到倉庫或寫進配置文件

總結¶

dsh-markji-bridge 爲 DSH agent 提供了一套完整的 Markji 卡片管理能力，包括本地緩存、純文本搜索、寫入隊列、三方合併、衝突解決、歸檔操作以及支持崩潰恢復的後臺同步。插件只用 Node 內置模塊實現，無第三方依賴，適合需要在 DSH 中使用 Markji 的場景。

插件目錄：https://www.skillhub.cn/plugins/Oxmyxo/dsh-markji-bridge
GitHub：https://github.com/Oxmyxo/dsh-markji-bridge

dsh-markji-bridge：爲 DSH Agent 提供墨墨記憶卡管理

前言¶

插件概覽¶

核心功能¶

本地緩存¶

純文本搜索¶

安全寫入¶

語法幫助、批量操作、寫前校驗與媒體預檢¶

後臺同步¶

歸檔與章節操作¶

多進程安全¶

安裝與啓用¶

前置要求¶

安裝步驟¶

配置 token¶

典型用法¶

列出卡組¶

讀取卡組詳情¶

讀取章節及卡片摘要¶

搜索卡片¶

讀取單張或多張卡¶

查語法幫助¶

校驗正文¶

啓動同步¶

批量操作¶

工具與 action¶

markji_decks 的 action¶

markji_cards 的 action¶

markji_sync 的 action¶

markji_file 的 action¶

2.1.0 新增：同步接入 DSH 後臺任務¶

2.0.0 遷移：舊工具名¶

適用場景與注意¶

總結¶

精选优惠券

dsh-markji-bridge：爲 DSH Agent 提供墨墨記憶卡管理

前言¶

插件概覽¶

核心功能¶

本地緩存¶

純文本搜索¶

安全寫入¶

語法幫助、批量操作、寫前校驗與媒體預檢¶

後臺同步¶

歸檔與章節操作¶

多進程安全¶

安裝與啓用¶

前置要求¶

安裝步驟¶

配置 token¶

典型用法¶

列出卡組¶

讀取卡組詳情¶

讀取章節及卡片摘要¶

搜索卡片¶

讀取單張或多張卡¶

查語法幫助¶

校驗正文¶

啓動同步¶

批量操作¶

工具與 action¶

markji_decks 的 action¶

markji_cards 的 action¶

markji_sync 的 action¶

markji_file 的 action¶

2.1.0 新增：同步接入 DSH 後臺任務¶

2.0.0 遷移：舊工具名¶

適用場景與注意¶

總結¶

精选优惠券

相關文章