前言¶
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
