前言¶

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 迁移：旧工具名¶

适用场景与注意¶

总结¶

精选优惠券

相关文章