cli-anything-joplin 工作流清单深度解读：12 类 Joplin 自动化能力、端到端验证与新增扩展指南

cli-anything-joplin 是一个封装真实 joplin 终端二进制的有状态 CLI 驱动框架（harness），它把笔记、笔记本、待办、标签、同步、导入导出等操作统一收敛到一套稳定的 JSON 命令信封之下。仓库中的 WORKFLOWS.md 正是这份 harness 的"工作流清单总账"——它是唯一事实来源（single source of truth），用来回答"这套 harness 到底已经覆盖了什么"。阅读本文后，你将系统掌握这套 harness 已实现并验证的全部工作流能力矩阵、测试分层架构、端到端集成流程，以及向其中安全新增一条工作流的标准动作与底层约定。

1. 背景：为什么需要一份"工作流清单"

对 Agent 自动化而言，"能力边界清晰"比"功能堆得多"更重要。一份真正被测试验证过的工作流清单，让 Agent 在下发命令前就能判断某类操作是否可行、是否依赖 GUI 模式、是否受版本限制。这正是 WORKFLOWS.md 被定位为"harness 已覆盖内容唯一事实来源"的原因：它逐条枚举了实现并验证过的工作流，而不是停留在"理论上支持"的口号层面。

与本文配套的权威依据还包括：JOPLIN.md（harness 的标准作业流程）、README.md（功能与用法总览）、TEST.md（完整测试计划），以及承载全部命令注册的 joplin_cli.py。

2. 12 类工作流能力目录：harness 覆盖了什么

WORKFLOWS.md 将 harness 的验证范围划分为 12 个类别。结合 joplin_cli.py 中的 Click 命令分组，可以精确对应到每条命令的真实实现：

1. CLI 表面（CLI surface）——--help、每个命令组的帮助文本、JSON 信封契约。在 joplin_cli.py 中由顶层 cli 组统一提供 --json/--project/--binary/--profile/--dry-run 全局选项。
2. 项目生命周期（Project lifecycle）——project new/open/info/json/save/status，外加 session status/undo/redo/history。
3. 笔记本生命周期（Notebook lifecycle）——notebooks list/create/use/remove。底层分别对应 Joplin 原生 ls/mkbook/use/rmbook。
4. 笔记生命周期（Note lifecycle）——notes list/create/set/get/remove，底层为 ls/mknote/set/cat/rmnote（见 core/notes.py）。
5. 笔记组织（Note organization）——notes copy/move/rename，底层为 Joplin 的 cp/mv/ren。
6. 待办生命周期（To-do lifecycle）——todos create/list/toggle/clear/done/undone。
7. 标签管理（Tag management）——tags list/add/remove/notetags/tagnotes，实现双向查询：从笔记看标签（notetags）与从标签看笔记（tagnotes）。
8. 搜索（Search）——search run。注意标注为 best-effort（尽力而为），因为部分 Joplin CLI 构建版本将 search 限制在 GUI 模式下（详见后文"已知限制"）。
9. 同步（Sync）——sync run，已在默认"无同步目标"配置下验证可返回负载。
10. 导入/导出（Import / export）——interop import 支持 md、jex、enex、raw、html 格式；interop export 支持 jex、md、raw、md_frontmatter。在 joplin_cli.py 中，export 默认格式为 jex，import 还额外透传 --force 与 --output-format。
11. 附件与状态（Attachments and status）——attach add、status show、status restore（后者用于从回收站恢复）。
12. 后端工具（Backend utilities）——backend version/dump/keymap/geoloc/export-sync-status，外加 API 服务器控制 server status/start/stop 与 E2EE 加密工具 e2ee status/target-status/decrypt/decrypt-file。

值得注意的设计取舍：清单把"搜索"与"同步"明确标注为能力受环境影响的工作流，而不是打包票式的"全部可用"。这种诚实的边界声明正是面向 Agent 的 harness 与普通脚本的差异所在——Agent 可以根据清单决定回退策略。

3. 真实后端工作流：10 条端到端短脚本

WORKFLOWS.md 第 2 节记录了 TestBackendWorkflows 类在真实 Joplin profile 上逐条执行并验证的短脚本。这组测试需要真后端（Joplin CLI 必须存在于 PATH），覆盖了"单命令可用"之外最重要的"命令串起来之后依然正确"：

• 笔记生命周期——创建笔记本 → use 切换 → 创建笔记 → 通过 set 改名 → get 读回 → 删除笔记 → 删除笔记本；
• 笔记组织——创建源/目标两个笔记本 → 创建笔记 → copy 到目标 → 重命名源 → 把改名后的笔记 move 到目标 → 列出目标 → 清理；
• 待办生命周期——创建 → 列出 → done → undone → toggle → clear → 清理；
• 打标签——创建笔记本/笔记 → tag add → 列出标签 → notetags → tagnotes → tag remove → 清理；
• 搜索——创建数据 → search（容忍 GUI 模式拒绝）→ 清理；
• 同步——sync run 在未配置同步目标时仍返回负载（no-target 空操作验证）；
• 导出——同一组笔记分别导出 JEX 与 Markdown 两种格式；
• 导入——将 Markdown 目录导入全新笔记本；
• 附件——创建笔记本/笔记 → 附加真实文本文件 → verbose get 读回 → 清理；
• Unicode 往返——用 CJK + 希腊字母执行笔记本/笔记的创建、使用与删除（在 Windows 上跳过，原因见第 7 节"已知限制"）；
• 会话历史持久化——连续执行三个变更命令 → 重新加载保存的项目 → 断言每个动作都出现在 history 中。

最后一条"会话历史持久化"是 harness 有状态性的核心证明：它不是无状态的 joplin 薄封装，而会把每次变更写入项目文件的历史日志，供 Agent 在会话恢复、审计与回放时使用。

4. 完整端到端集成：一条贯穿全生命周期的 roundtrip

比短脚本更高一层的是 TestBackendIntegration.test_full_backend_roundtrip——它在同一个进程里对真实 Joplin profile 依次执行 10 个阶段，然后校验保存的项目历史是否包含每一个预期动作：

1. 检查项目（status / info / session）；
2. 笔记本搭建（list，创建 main 与 archive，use main）；
3. 笔记生命周期（list、create、经 set 改名、get、copy 到 archive、创建后 move、经 ren 改名）；
4. 待办（create、list、done、undone、toggle、clear）；
5. 标签（添加主/次标签、list、notetags、tagnotes、remove）；
6. 附件（附加真实文件、verbose get）；
7. 状态与配置（status show、config get sync.target、config list）；
8. 同步（无目标空操作）；
9. 导出（JEX + Markdown）；
10. 清理（删除笔记、删除笔记本、保存、最终状态与会话历史）。

保存后校验的历史动作清单完整如下：

notebook.create, notebook.use, note.create, note.set, note.copy, note.move,
note.rename, todo.create, todo.toggle, todo.done, todo.undone, todo.clear,
tag.add, tag.remove, attach.add, interop.export, note.remove, notebook.remove

这条 roundtrip 的意义在于回归保障与演示价值双收：任何改动只要破坏了上述任意一环的历史记录一致性，就会被唯一一个集成测试立刻抓住；同时它本身就是一次可复现的 Agent 演示脚本，展示"从零建库到清理完毕"的完整自动化旅程。

从源码看，历史动作的写入点在每条变更命令内部：例如 joplin_cli.py 的 notes create 在成功执行后调用 project_mod.add_history(...) 追加 note.create，并调用 sess.snapshot("Create note: ...") 创建撤销点。add_history 的实现位于 core/project.py，每条记录包含 at（UTC 时间戳）、action（动作名）与 payload（参数载荷）。

5. 测试分层：四层从快到慢的验证金字塔

WORKFLOWS.md 第 4 节给出了一张测试分层表，核心思想是：后端无关的测试优先、快且便宜；后端相关的测试后置、慢但真实。各层在测试文件中的落点如下：

分层	文件 / 类	是否需要后端	工作流覆盖
单元 + CLI 契约	tests/test_core.py 中 test_core.py	否	107 个测试
CLI 子进程	TestCLISubprocess	否	10 个测试
真实后端单命令	TestBackendCommands	是	6 个测试
真实后端工作流	TestBackendWorkflows	是	11 个测试（Windows 上跳过 1 个）
端到端集成	TestBackendIntegration	是	1 个测试

所有真实后端测试类都通过 test_full_e2e.py 组织，其完整说明见 TEST.md。值得强调的设计哲学：第一层 107 个纯 Python 单元测试"任何没有 Joplin 后端的机器上都能跑"，覆盖项目 schema、会话快照/撤销/重做、跨进程文件锁、后端运行器的警告处理、JSON 信封形状与各命令组契约、--permanent 守卫逻辑、backend version 的 npm 布局回退等；CLI 子进程层则以安装后的控制台脚本（或 python -m cli_anything.joplin.joplin_cli）为被测对象，验证对外可见的 JSON 契约。

对应 JOPLIN.md 给出的测试命令，任何具备 Joplin CLI 的环境都可以按如下方式逐层复现验证：

# 快反馈环（无需后端）
python -m pytest -q cli_anything/joplin/tests/test_core.py
python -m pytest -q cli_anything/joplin/tests/test_full_e2e.py::TestCLISubprocess

# 真实后端（要求 joplin 在 PATH 中）
python -m pytest -v cli_anything/joplin/tests/test_full_e2e.py::TestBackendCommands
python -m pytest -v cli_anything/joplin/tests/test_full_e2e.py::TestBackendWorkflows
python -m pytest -v cli_anything/joplin/tests/test_full_e2e.py::TestBackendIntegration

# 全套
python -m pytest -v --tb=no cli_anything/joplin/tests

6. 如何新增一条工作流：五步标准动作

WORKFLOWS.md 第 5 节为"给 harness 增加新工作流"定义了清晰且可复制的五步流程。结合源码展开，每一步都有对应的强制约定：

1. 添加薄 core 模块：在 cli_anything/joplin/core/ 下新增模块（如 core/notes.py、core/tags.py 同级），模块内只做"拼参数、调 Joplin、返回结果"的薄逻辑。

2. 在 joplin_cli.py 注册单条 Click 命令，且该命令必须做到两件事：

   • 成功时调用 project_mod.add_history(...) 记录历史动作；
   • 调用 sess.snapshot(reason)（创建撤销点）或 sess.mark_dirty()（仅标记脏）以触发自动保存。

   两条路径的分工在 core/session.py 中定义得很清楚：snapshot 会把当前项目深拷贝压入撤销栈、清空重做栈并追加一条 snapshot 历史；而 mark_dirty 只把 _modified 置真，不增加撤销/重做深度。像 sync run、interop export 这类"不应产生独立撤销点、但历史里应保留痕迹"的命令就走 mark_dirty 路径（见 joplin_cli.py）。

3. 在 test_core.py 添加单元测试：验证参数形状与 JSON 信封（无需后端）。

4. 在 test_full_e2e.py 的 TestBackendWorkflows 下添加真实后端工作流测试。

5. 若工作流较大或值得演示，扩展现有的 TestBackendIntegration.test_full_backend_roundtrip。

JOPLIN.md 还补充了一条配套开发纪律：优先把小改动做成单命令测试，再升级为长旅程工作流测试，且只保留一条完整集成流程用于演示与回归。

7. 实现保证：原样透传 stdout/stderr，信封契约统一

WORKFLOWS.md 第 6 节列出了两条容易踩坑的实现保证，两者都有对应的源码佐证：

第一，子进程输出的原样性。 后端结果中的 stdout/stderr 是 Joplin 的逐字节原样输出（verbatim）。良性的 Node.js 弃用警告只在"判定非零退出码是否真失败"时才被过滤，绝不会从返回流中剥离——否则多段落的笔记正文与导出内容会被破坏。这一逻辑落在 utils/joplin_backend.py：非零退出时先对副本做 _strip_benign_node_warnings 清洗再决策，返回结果仍保留原始流。清洗器按行剔除 dep0040/punycode、dep0169/url.parse 等已知良性警告及其后随的 (Use node --trace-deprecation ...) 提示行。

该模块还有一个值得注意的失败保护（P1 silent-failure guard）：若进程非零退出但 stdout/stderr 均为空，会直接抛出带退出码与命令信息的 RuntimeError，而不是静默返回 ok=true，杜绝"命令静默失败却被 Agent 当成成功"的隐患。

第二，错误信封的命令标识一致性。 JSON 错误信封与成功响应使用同一个 command 标识符——例如 config.import_file、backend.export_sync_status、e2ee.decrypt_file。多词子命令在组名与子命令之间只使用一个点。这一约定在 joplin_cli.py 的 _json_envelope 与 joplin_cli.py 的 handle_error 装饰器中落实：错误标识由 func.__name__.replace("_", ".", 1) 派生，因此 import_file 变成 config.import_file 而不是 config.import.file，保证 Agent 解析成功/失败路径时无须维护两套 ID 映射。

8. 已知限制：harness 诚实声明的边界

WORKFLOWS.md 第 7 节记录了四条已识别限制，理解它们对 Agent 编排尤其重要：

搜索的 GUI 门槛。 部分 Joplin CLI 3.x 构建版本将 joplin search 限制在 GUI 模式。harness 的做法不是硬造成功，而是返回干净的 ok=false JSON 信封并携带原始错误信息；工作流测试也只断言"接受该形状"。因此 Agent 应把搜索视为 best-effort。

Windows 非 ASCII 参数。 非 ASCII 进程参数在 Windows 上经 joplin.cmd → cmd.exe 传递时会被降级到活动代码页，导致截断。harness 自身的 JSON 状态能正确处理 Unicode（test_core.py 中有纯 Python 层的 Unicode 往返测试），只有 argv 转发路径受影响，因此 Unicode 工作流测试在 Windows 上被跳过。

joplin version 的 npm 全局布局缺陷。 上游 joplin version 在 npm 全局安装布局下可能因查找 ../package.json 而失败。backend version 的降级路径（core/backend.py）会在多种常见布局下回退到已安装 Joplin 的 package.json 元数据：symlink 解析后的二进制目录（Unix npm 全局、Homebrew、nvm）、Windows 风格的兄弟目录 node_modules/joplin、Unix 风格的父级 lib/node_modules/joplin，最后以 npm root -g 兜底，并且只接受 "name": "joplin" 的元数据以防冒充。

--permanent 与 server/e2ee 标志的探测守卫。 notes remove --permanent / notebooks remove --permanent 要求 Joplin 终端 CLI ≥ 3.0。因为 Joplin 会静默忽略未知选项，harness 会对 joplin help rmnote/rmbook 每种二进制探测一次，在旧版本上直接抛出明确错误，而不是让"永久删除"悄悄降级成"移入回收站"。标志一律以长格式 --permanent/--force 转发，刻意避开短格式 -p——因为 mkbook 中 -p 的含义是 --parent。同理，server start --exit-early/--quiet 与 e2ee decrypt --force 也通过共享的 _cli_supports_flag 助手（core/backend.py）做探测守卫：没有 --exit-early 时 harness 子进程会因前台服务器永久阻塞；没有 --force 时 e2ee decrypt 会死锁在交互式主密码提示上。探测结果按 (binary, command, flag) 缓存，因此执行大量 server start 的工作流每种标志只多付出一次 help 调用。

这一组限制在 TEST.md 中全部有对应的负向测试覆盖，例如"旧构建上拒绝发送 --permanent 并抛 RuntimeError""探测缓存（N 次永久删除只触发一次 help）""server start --wait 模式不设硬超时"等。

9. 结语：把 WORKFLOWS.md 当 API 文档来用

对开发者和 Agent 来说，WORKFLOWS.md 的价值不在于它只是测试记录，而在于它是可信能力清单 + 扩展契约 + 边界声明的三合一文档：12 类能力目录告诉你"能用什么"，五步新增流程告诉你"怎么加"，四类已知限制告诉你"哪里会翻车"。配合 JOPLIN.md 的安装与使用说明（pip install -e . 后通过 cli-anything-joplin 进入 REPL，或以 cli-anything-joplin --json notebooks list 方式做机器可读的一次性调用），任何环境只要满足 Python 3.10+ 且 joplin 可执行，就能把整套经过真后端验证的笔记自动化能力交付给 Agent。