中文 | English
dsh-markji-bridge
给 DeepSeek Harness（DSH）的 agent 用的墨墨记忆卡（Markji）插件。它在本地维护一份卡组 / 章节 / 卡片缓存，agent 可以搜索、阅读、新建、修改、归档卡片；所有修改先写入本地队列，再按「先拉取、三方合并、后推送」的顺序同步到云端，冲突单独报告，不影响其他卡片。
只注册 4 个按 action 组织的 markji_* 工具，只用 Node 内置模块实现，无第三方依赖：markji_decks（卡组 / 章节，含章节详情、新建、重命名、排序）、markji_cards（列表过滤、读写、语法、归档、移动）、markji_sync（同步、等待、进度、状态、失败与冲突）、markji_file（文件）。写卡前用 markji_cards({ action: "syntax_help" }) 查语法；create / update 会在入队前自动校验语法和媒体引用，无需额外调用校验。批量读写用同一工具的 new_cards / updates。
特性
- 本地缓存：单个 SQLite 文件
cache.db，索引、卡片正文、待推送队列、冲突和同步任务都在一个库里，日常搜索和阅读不请求 API。
- 统一列表过滤（JSON 条件树）：
markji_cards 的 list、markji_decks 的 list / chapter_list 使用同一个 filter 参数（字段集各自独立），没有单独的 search action，所有过滤都由 filter 完成：
filter：JSON 条件树，不是 JS。条件为 { field, op, value, case_sensitive?, flags? }，组合为 { all: [...] } / { any: [...] } / { not: {...} }；op 支持 eq、ne、contains、starts_with、ends_with、regex、in、not_in、gt、gte、lt、lte、exists。正则用 flags 设置 imsu（默认 i），case_sensitive: true 也可关闭字符串匹配和正则的默认大小写不敏感。filter 省略或传 {} 表示不过滤。scope：卡片支持 all / deck / chapter，章节支持 all / deck，卡组支持 all / folder；不传时由 deck / chapter / folder_id 推断，显式冲突会报错。- 每个 list 的字段集独立：卡组只认卡组字段（
name / description / id、更新时间、计数等），章节只认章节字段（没有 description，也不支持 deck_name，按父卡组筛选用 scope=deck），卡片保留更宽的条件（text / content / cloud / status 等）。不属于该 list 的字段或操作会报 invalid_argument，不会跨资源匹配。
- 纯文本匹配：每张卡另存一列去掉格式标记、图片 / 音频标记、data URI 和 base64 的纯文本，
text 字段只含纯文本，结果干净可读；content 保留原始富文本，便于正则在正文上匹配。
- 安全写入：修改先排队，推送前先拉取远端变更并三方合并，不会用过期的本地缓存覆盖云端；冲突按卡片去重，可逐条解决。
- 插件页与加密凭证：插件详情页可填 Markji API Key，并选择
cache.db 目录。Key 只以 AES-256-GCM 密文写入 cache.db 的 secrets 表；数据密钥由 DSH 凭据服务或仅当前用户可读的 secret.key 保存，配置文件和源码里不会出现明文 token。
- 自动写前校验与媒体预检：
markji_cards 的 action=syntax_help 可按格式或全部查询原始 Markji 语法；create / update 在入队前自动校验每条正文，并默认批量查询 Pic / Audio 引用的文件 id（checkMediaOnWrite: false 可跳过媒体查询）。语法错误、文件缺失或查询失败会让该条直接失败且不产生待推送卡，批量中的其他项继续。markji_sync 推送前仍保留同一套预检作为最后一道闸。
- 后台同步：同步任务立即返回句柄，可查进度；进程崩溃或插件重启后用同一句柄续跑，不重复创建云端对象。DSH 加载了
dsh-tool-jobs 时，markji_sync({ action: "start" }) 还会把任务登记为当前会话拥有的 DSH 后台任务，返回 job_id；任务出现在「正在运行的后台任务」中，job_output 会随同步进度实时追加输出，结束后由 DSH 发送完成通知；也可以 markji_sync({ action: "wait", task_id }) 阻塞到该任务结束（可选 timeout_ms，超时返回 task.timed_out: true）。终止后台任务会在下一个检查点取消同步，任务变为 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
配置 API Key 与缓存位置
在 DSH 的插件 → 墨墨记忆卡桥接详情页里填写 Markji OpenAPI Key（在墨墨开放平台获取），点「保存并测试」：插件会先调用一次只读接口校验，通过后用 AES-256-GCM 加密写入 cache.db 的 secrets 表，页面只显示 hasKey 和尾 4 位，不回显明文。
同一个插件详情页可以选择 cache.db 所在目录：修改时会把现有 cache.db（以及 secret.key，如果使用文件 DEK）复制到新目录，原目录保留以便回退；需要重启 DSH 生效。
可选引导配置：cordis.patch.yml 的 apiKey、环境变量 MAIMEMO_MARKJI_OPENAPI_TOKEN / MAIMEMO_OPENAPI_TOKEN 可作为首次启动的输入；插件启动时会把它们加密写入 cache.db 并从进程环境清除。推荐直接在插件详情页配置。不要提交 token。
快速开始
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: "list", filter: { field: "text", op: "contains", value: "排序" }, deck_name: "算法" })
markji_decks({ action: "list", filter: { field: "name", op: "contains", value: "算法" } })
markji_decks({ action: "chapter_list", filter: { field: "name", op: "regex", value: "^SPI\s+时钟" } })
markji_cards({ action: "list", scope: "deck", deck: "<deck_id>", filter: { all: [{ field: "status", op: "eq", value: "dirty" }, { field: "updated_time", op: "gte", value: "2026-10-01" }] } })
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: "create", deck: "<deck>", chapter: "<chapter>", new_cards: [{ content: "<Markji 富文本>" }] })
markji_sync({ action: "start", mode: "auto" })
markji_sync({ action: "wait", task_id: "<task_id>", timeout_ms: 300000 })
首次调用会拉取云端数据（卡片多时需要一点时间），之后读操作走本地缓存。状态和进度用 markji_sync({ action: "state" }) / markji_sync({ action: "progress" }) 查看；传 task_id 时只返回该任务的 { task }，不传时返回 { active, tasks }。action: "wait" 会阻塞到指定任务结束，timeout_ms 省略时最多等 30 分钟（与工具超时一致）；超时后返回仍在运行的 task，并带 timed_out: true。若 DSH 加载了 dsh-tool-jobs，start 还会返回 job_id：在 DSH 的后台任务列表里能直接看到进度，job_output 的输出也会按进度实时追加，任务结束后会自动收到完成通知，也可以用 job_output 读取最终结果。
批量操作
需要一次处理多张卡时用 markji_cards 的这些 action：
markji_cards({ action: "get", cards: ["<id1>", "<id2>"] })
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 项（多卡读取、
new_cards、updates、冲突批量解决）；归档和移动使用非空数组。action=get 会去重并保持请求顺序，未知 id 放入 missing，不会中断整批。
action=create 的顶层 deck / chapter 是默认值，可以省略；每个 new_cards 项可写自己的 deck / chapter，所以一次调用能跨章节 / 卡组。未提供目标的项会逐条报错；每项的 order 相对于该项最终的目标章节。- 结果逐项列出
ok、warnings 和错误；写操作不是事务，坏项（语法错误、媒体缺失、目标不存在）不会入队，其他项仍会排队。成功项仍需 markji_sync({ action: "start" }) 推送。
action=get 默认不返回冗余的 text，需要时传 include_text: true。create / update 默认同时做语法和媒体校验；媒体查询失败时该条返回 media_check_failed，可重试。checkMediaOnWrite: false 可跳过这道额外查询，但 markji_sync 推送前仍会检查。- 批量输出可能超过
maxOutputChars，内容多时请拆小批次。
工具
插件只注册 4 个工具，具体操作由 action 选择；省略时用各工具的默认 action。
| 工具 | 默认 action | 作用 |
|---|
markji_decks | list | 卡组列表 / 详情，章节列表 / 详情 / 新建 / 重命名 / 排序 |
markji_cards | list | 卡片列表过滤、读取、新建、修改、移动、归档、语法帮助 |
markji_sync | start | 启动同步、等待任务、查看进度 / 插件状态 / 失败、解决冲突 |
markji_file | 无（必填） | 上传文件到 Markji 或查询文件信息 |
各 action 一览
| 工具 | action | 作用 |
|---|
markji_decks | list | 列出文件夹与卡组 |
markji_decks | get | 读一个卡组及其章节 |
markji_decks | chapter_list | 列出一个或全部卡组的章节 |
markji_decks | chapter_get | 读一个章节，可带卡片摘要 |
markji_decks | chapter_create / chapter_rename / chapter_sort | 新建 / 重命名 / 排序章节 |
markji_cards | list | 分页、按范围（全库 / 卡组 / 章节）过滤，使用 filter JSON 条件树；可同时按卡组名 / 章节名 / 更新时间过滤 |
markji_cards | get | 按 id 读一张或多张卡；未知 id 列入 missing |
markji_cards | create | 用 new_cards 批量新建，支持跨章节 / 卡组 |
markji_cards | update | 改一张（card + content）或多张（updates） |
markji_cards | move / archive | 移动到其他章节 / 归档到「归档」章节 |
markji_cards | syntax_help | 查原始 Markji 语法；create/update 自动校验 |
markji_sync | start | 启动后台同步（pull / push / auto，可 resume） |
markji_sync | wait | 等待指定同步任务结束；timeout_ms 控制最长等待，超时返回 task.timed_out: true |
markji_sync | progress | 查看同步任务进度与历史 |
markji_sync | state | 插件与缓存总览 |
markji_sync | failures | 查看失败卡片、冲突与恢复建议 |
markji_sync | resolve | 解决一个或批量冲突（keep_local / keep_remote / use_content； / 最多 50 个） |
工具参数与返回值
? 表示可选参数。id 都是 Markji OpenAPI id；尚未推送的新对象使用 local_* id。工具结果统一为 JSON，超过 maxOutputChars 会截断。下表的“参数”列只列该 action 用到的字段；同一工具的其他字段在别的 action 生效。
| 工具 / action | 参数 | 返回（主要字段） |
|---|
markji_decks / list | refresh? folder_id? scope? filter? | {folders, decks, total}；folders 为 {id, name, deck_count, parent_id?} |
markji_decks / get | deck refresh? | {deck, chapters}；详情含 description / updated_time |
markji_decks / chapter_list | deck? scope? refresh? filter? | 指定 deck：{deck_id, deck_name, chapters, total}；不指定：{decks, total} |
markji_decks / chapter_get | chapter deck? with_cards? refresh? | {deck_id, deck_name, chapter, cards?, total?} |
markji_decks / chapter_create | deck name order? | {ok, action, chapter_id, deck_id, status, pending, message} |
markji_decks / chapter_rename | chapter name deck? | {ok, action, chapter_id, status, pending, message} |
markji_decks / chapter_sort | deck chapter_ids | {ok, action, deck_id, chapters, status, pending, message} |
markji_cards / list | scope? deck? chapter? filter? deck_name? chapter_name? updated_after? updated_before? limit? offset? refresh? | {total, offset, limit, has_more, cards}；无结果且传了 filter 时带 |
filter 字段
filter 条件的 field 可用点号读取嵌套自有属性；不同列表允许的根字段：
- 卡片：
id、deck_id、deck_name、chapter_id、chapter_name、text、content、snippet、status、grammar_version、revision、updated_time、created_time、local、pending、conflict、last_error、cloud（可继续读 cloud.revision 等）。
- 卡组：
id、name、description、folder_id、card_count、chapter_count、is_private、source、status、missing、created_time、updated_time。
- 章节：
id、deck_id、name、card_count、order、revision、local、pending、missing、updated_time（没有 description 和 deck_name）。
各 list 的字段集按资源独立维护；例如给章节传 description / deck_name，或给卡组传 text / content，都会报 invalid_argument，不会被静默忽略。
字符串比较默认大小写不敏感（case_sensitive: true 可关闭）；正则默认 i，可用 flags 覆盖；数字按数值比较；ISO 时间按字符串比较（同一时区偏移下顺序正确）；未知字段、未知 op、超过深度 / 节点限制都会以 invalid_argument 报错。
语法帮助
用 markji_cards 的 syntax_help 查询静态语法：
markji_cards({ action: "syntax_help" }) // 全部格式
markji_cards({ action: "syntax_help", format: "picture" }) // 只查图片
create / update 在入队前自动校验语法和媒体引用；语法错误会直接返回带行号 / 列号的 errors，该条不入队。
action=syntax_help 时 format 可省略或写 all；写 basic 只返回通用规则和嵌套限制。支持的格式 id 为 text-style、cloze、audio、card-ref、paragraph、choice、picture、formula、answer-line，也接受对应标签（如 Pic）和中文别名（如 图片）。帮助内容是静态的，不会检查或改写正文；语法以 Markji 制卡语法指南 为准。
返回结构
DeckView = {
id, name, card_count, chapter_count,
folder_id?, description?, updated_time?,
is_private?, source?, status?, missing?,
}
ChapterView = {
id, name, card_count,
pending?: { op, name }, local?, missing?,
revision?, order?, updated_time?,
}
CardSummary = {
id, deck_name, chapter_name, snippet,
status?: "dirty" | "new" | "conflict",
}
CardView = {
id, deck_id, deck_name, chapter_id, chapter_name,
content: string, text: string, grammar_version: number,
status, cloud: null | { revision, updated_time },
created_time, updated_time,
local?, pending?, conflict?, last_error?,
}
ConflictView = {
id, kind, entity, deck_id, chapter_id, card_id, op,
local, remote, state, detected_at,
deck_name, chapter_name, card_snippet,
recovery: { tool, arguments, strategies, hint },
}
SyncTask = {
task_id, status: "running" | "completed" | "failed" | "interrupted",
mode: "auto" | "pull" | "push", stage,
started_at, finished_at, resume_count,
progress: {
message, decks_total, decks_done,
chapters?, cards?, cards_deleted?, adopted_cards?, adopted_chapters?,
conflicts_created?, chapters_created?, chapters_renamed?, chapters_sorted?,
cards_created?, cards_updated?, cards_moved?, errors?,
},
full?, error?: { code, message }, hint?,
report?: SyncReport,
}
SyncReport = {
ok, mode, duration_ms,
pull?: {
decks?, chapters?, cards?, cards_deleted?,
adopted_cards?, adopted_chapters?, conflicts?,
},
push?: {
chapters_created?, chapters_renamed?, chapters_sorted?,
cards_created?, cards_updated?, cards_moved?, conflicts?,
errors?: [{ op, id, code, message }], errors_total?,
},
conflicts?: [ConflictView],
errors?: [{ op, id, code, message }], errors_total?,
}
Status = {
version, configured, cache_file,
cache: {
decks, chapters, cards, bytes, pulled_at,
stale?, error?, save_error?,
},
pending: {
cards_new?, cards_dirty?, chapters_new?, chapters_rename?,
moves?, sorts?, conflicts?,
},
conflicts: [ConflictView],
last_sync: { ok, mode, started_at, finished_at, duration_ms, conflicts, errors }|null,
last_error: null | { code, message },
active_task: string|null, tasks: [SyncTask],
auto_sync: { enabled, running },
}
Failures = {
ok, summary: { conflicts, failed_cards, last_task_errors, last_error },
conflicts: [ConflictView],
failed_cards: [{
id, deck_id, deck_name, chapter_id, chapter_name,
status, snippet,
error: { code, message },
recovery: { tool, arguments, strategies, hint },
}],
last_task_errors: [{ task_id, op, id, code, message }],
truncated?: boolean,
}
markji_cards({ action: "archive" }) 的 chapters 是 [{ deck_id, chapter_id, chapter_name, local }]。markji_file 的 file 由 Markji 返回，常见字段为 id、url、mime、size、info、expire_time。
配置
默认配置写在 bundle 的 cordis.patch.yml，都可用默认值：
| 字段 | 默认值 | 说明 |
|---|
enabled | true | 是否注册工具并启动自动同步 |
apiKey | '' | 可选的引导输入；通常用插件详情页保存 Key，这里保持空 |
baseUrl | https://open.maimemo.com/open | API 地址 |
dataDir | <home>/.dsh/dsh-markji-bridge | 默认缓存目录；插件详情页保存的目录优先 |
checkMediaOnWrite | true | create/update 入队前查询媒体文件；false 可省一次请求 |
grammarVersion | 3 | 新卡默认 grammar_version |
requestTimeoutMs | 20000 | 单次请求超时 |
maxRetries | 3 | 网络错误 / 429 / 5xx 重试次数 |
pageSize | 100 | 拉取分页大小 |
pullTtlMs | 600000 | 缓存过期后读操作先增量拉取 |
autoSync | true | 空闲时自动推送并拉取 |
idleCheckMs | 30000 | 空闲检查周期 |
idleQuietMs | 120000 | 最近一次工具调用后的静默时间 |
autoPullMs | 900000 | 无待办时的后台拉取周期 |
retryBackoffMs | 300000 | 自动同步失败后的重试间隔 |
maxOutputChars | 20000 | 单个工具结果最大字符数 |
同步与恢复
- 读操作在缓存过期时先做增量拉取；写操作只改本地缓存并排队。
markji_sync mode=auto：先拉取远端并三方合并，再推送本地队列；推送前一定会先拉取，避免本地缓存覆盖远端修改。create / update 入队前会校验语法，并默认批量调用 POST /api/v1/markji/files/query 检查 Pic#ID/...、Pic#ID/...,MID/... 和 Audio#...,ID/... 里的文件 id；失败条目不入队，批量其他项继续。推送卡片前仍会做同一套语法 + 媒体预检作为最后一道闸（防止入队后文件被删），失败时卡片保持待推送，markji_sync({ action: "failures" }) 会给出错误与恢复建议。- 冲突不会阻塞其他卡片，处理方式：
keep_local（保留本地，下次推送覆盖云端）、keep_remote（采用云端，丢弃本地改动）、use_content（用指定内容替换本地待推送内容）。批量解决用 markji_sync({ action: "resolve", ids: [...], strategy: "keep_remote" })，或 items: [{ id, strategy, content? }] 混用策略，单次最多 50 个；单条 id 调用保持旧结构。
- 同步任务会记录进度与结果，最多保留最近 20 条；进程中断后任务标记为
interrupted，用 markji_sync resume=<task_id> 续跑。等待某个任务结束用 markji_sync({ action: "wait", task_id })，不要反复轮询。
- 失败或冲突用
markji_sync({ action: "failures" }) 查看，处理完再执行 markji_sync({ action: "start", mode: "push" })。
性能与行为
- 读操作优先读本地缓存；缓存超过
pullTtlMs（默认 10 分钟）或显式 refresh: true 时先做增量拉取。
- 未知 id 触发的兜底刷新只拉取“云端标记为变化”的卡组，不会全量拉取所有卡组。实测 5265 张卡 / 82 章节的账号：未知章节重命名约 0.8 秒返回
unknown_chapter，未知卡片约 0.3 秒。
- 确实需要全量刷新时显式运行
markji_sync({ action: "start", mode: "pull", full: true })；全量拉取是后台任务，先返回 task，再用 markji_sync({ action: "wait", task_id }) 等待结束，或用 action: "progress" 查进度。
- 写操作只改本地缓存并立即返回，网络请求发生在同步任务或自动同步里。
- 自动同步：最近一次工具调用后静默
idleQuietMs（默认 2 分钟）触发；无待办时每 autoPullMs（默认 15 分钟）拉取；失败后按 retryBackoffMs（默认 5 分钟）重试。
- 有未解决冲突时自动推送暂停，但拉取继续。
- 请求受滑动窗口限流（默认每 10 秒 18 次、每分钟 36 次、每 5 小时 7800 次），并发同步会自动排队。
- 单张卡内容上限 100000 字符；
markji_cards 的 list 的 limit 上限 200，批量入口单次最多 50 项（归档 / 移动不受此限）。
错误码与故障排查
工具错误一般形如 markji: <code>: <message> (hint: ...)；参数格式错误可能是普通的 markji_xxx: "field" ... 消息（没有 code）。常见 code：
| code | 含义与处理 |
|---|
not_configured | 没有可用的 API Key。打开 DSH 的「插件 → 墨墨记忆卡桥接」详情页，填入 64 位 Key 并「保存并测试」；不需要设置环境变量或改配置文件。 |
unknown_deck / unknown_chapter / unknown_card / unknown_folder | 本地缓存里没有这个 id。兜底刷新已尝试过；如果对象是在其他设备新建的，执行 markji_sync({ action: "start", mode: "pull", full: true }) 后再试。 |
invalid_argument | 参数缺失、类型不对、时间格式不对、chapter_ids 没有列全、内容为空或超过 100000 字符等。按消息修正参数。 |
invalid_content | 卡片内容不合法（例如规范化后为空）。 |
invalid_card_content | 卡片正文未通过原始 Markji 语法校验。create / update 会直接返回带行号 / 列号的 errors 且不入队；修正后重试。 |
media_unavailable | 正文引用的图片 / 遮罩 / 音频文件 id 在 Markji 查不到。create / update 会直接失败且不入队；先用 markji_file 上传，拿到 file.id 后更新正文。 |
media_check_failed | 查询媒体文件失败（网络、鉴权等）。写入条目不进队列，重试即可；推送阶段的失败会保留队列。 |
secret_corrupt / secret_key_invalid / secret_key_missing | cache.db 里的密文、secret.key 或宿主凭据中的 DEK 无法使用（文件损坏、被替换、换了用户 profile 或 DEK 丢失）。插件详情页重新保存 API Key；插件不会静默换新密钥，也不会回退到环境变量。 |
conflict_open | 这张卡有未解决冲突。先用 markji_sync({ action: "resolve" }) 处理。 |
unknown_conflict | 冲突 id 不存在或已解决。用 markji_sync({ action: "failures" }) 重新获取当前冲突列表。 |
unknown_task / task_not_resumable | resume / wait 的任务 id 不存在，或该任务不是 interrupted / 已结束。用 markji_sync({ action: "progress" }) 查任务状态。 |
deck_mismatch | 目标章节或卡片不属于指定卡组。检查 id 与 deck 参数是否匹配。 |
cache_busy | 另一个 DSH 进程正持有 cache.write.lock。等它结束再重试；不要手工删除活动进程的锁。 |
engine_unavailable | 插件引擎没有加载完整。停用再启用插件，或重启 DSH。 |
conflict_resolve_failed | 解决冲突时写入失败，详情见消息；通常可重试或改用 。 |
常见问题：
markji_sync({ action: "state" }) 里 configured: false：打开「插件 → 墨墨记忆卡桥接」详情页，填入 Key 并保存；插件详情页显示 secret_corrupt / secret_key_invalid / secret_key_missing 时重新保存一次。可选环境变量在首次启动时读取并清除。- 401 / 403：token 无效、过期或没有 OpenAPI 权限；到开放平台重新生成。不要把 token 写进
cordis.patch.yml 或提交到仓库。
- 首次调用很慢：首次要拉取全部卡组、章节和卡片；几千张卡通常需要几十秒到几分钟，属正常。用后台任务和
markji_sync({ action: "wait", task_id }) / action: "progress" 观察，不要重复发起。
- 刚在手机 / 网页新建的卡本地找不到：兜底刷新只拉变化的卡组，若卡组
updated_time 没变，执行 markji_sync({ action: "start", mode: "pull", full: true })。
- 自动同步没有推送：先看
markji_sync({ action: "failures" }) 是否有开放冲突；有冲突时推送会暂停。解决后执行 markji_sync({ action: "start", mode: "push" })。
cache_busy 持续出现：确认是否有另一个 DSH 进程在使用同一 dataDir；关闭多余进程。进程崩溃留下的锁会按持有者 pid / 主机名判断后回收。- 缓存损坏：插件会把原库改名备份并重建，然后重新拉取；看 DSH 日志和
markji_sync({ action: "state" }).last_error 确认。
- WSL 中使用：DSH 本身要运行在该 WSL 发行版的 Linux 环境里；在插件详情页填 Key 即可。SQLite 缓存建议放在 Linux 文件系统（如
~/.dsh/...），不要放在 /mnt/c 下，避免文件锁和性能问题。
数据与隐私
- 缓存位于
<dataDir>/cache.db（默认 ~/.dsh/dsh-markji-bridge），只保存在本机，除 Markji API 外不发送到任何地方。
- API Key 只以 AES-256-GCM 密文保存在
cache.db 的 secrets 表；数据密钥由 DSH 凭据服务（dsh-markji-bridge/dek）或仅当前用户可读的 secret.key 保存。插件不会把明文 Key 写入缓存、配置文件或日志，日志中的 Key 会替换为 <redacted>。
- 多个 DSH 进程可共享缓存目录，写入用
cache.write.lock 串行；不建议跨机器共享。
- 缓存损坏时会改名保存并重新拉取。
已知限制
- Markji OpenAPI 不支持创建 / 删除卡组、删除卡片、删除章节；章节只支持新建 / 重命名 / 排序，这些删除操作仍需在网页或客户端完成。
- 只支持单个 Markji 账号。
- 冲突需手动解决，未解决时自动推送会暂停。
grammarVersion 是全局默认值，卡片自身版本未知时使用。
平台验证
| 环境 | 结果 |
|---|
| Windows + Node 25.2.1 | 单元 155/155，E2E 13/13，入口冒烟 4 个工具；真实 DSH 中核对 markji_cards / markji_decks 的 filter（equality、contains、regex、跨资源字段拒绝、未知字段拒绝），并确认插件设置区、工具注册和缓存读取正常。 |
| WSL2 Ubuntu 26.04（Linux 6.18，Node v22.22.1） | 未在当前环境实机复跑；代码只使用 Node 内置模块。 |
| macOS | 未实机测试；代码只使用 Node 内置模块，理论上可用。 |
开发与测试
需要 Node >= 22.13，从仓库源码运行：
node --test "test/*.test.js" # 单元 / 集成测试（155 项）
node test/e2e-mock.mjs # mock 服务端端到端（13 项）
node test/index-smoke.mjs # 入口烟测（4 个工具）
另有一套不随仓库发布的内部独立验证集，用于发布前交叉检查；公开仓库只包含上面列出的测试。
测试需要从本仓库源码运行。主要文件：index.js（入口与配置）、lib/api.js（HTTP 客户端）、lib/store.js（缓存、写锁与 secrets 表）、lib/sync.js（同步引擎）、lib/filter.js（JSON 条件树与正则匹配）、lib/jobs.js（DSH 后台任务桥接）、lib/plain-text.js（纯文本转换）、lib/card-syntax.js（原始语法校验）、lib/preflight.js（写入前语法 + 媒体预检）、lib/secret.js（AES-256-GCM）、lib/settings.js（设置 RPC）、client.js（插件详情页配置区）、lib/tools.js（工具定义）。模块契约见 DESIGN.md。
许可
MIT，见 LICENSE。
