cli-anything-joplin

cli-anything-joplin 是做什么的？

使用此技能通过一个由真实 joplin 终端二进制文件支持的状态化封装层，自动化 Joplin 笔记本、笔记、待办事项、标签、附件、搜索、同步和导入/导出等工作流。

要求

• Python 3.10+
• 可使用 joplin 命令的 Joplin 终端二进制文件
• 可选：传递 --profile 以定位特定的 Joplin 配置文件

安装

cd joplin/agent-harness
pip install -e .

用法

# REPL 模式（默认）
cli-anything-joplin

# 机器可读的单次命令
cli-anything-joplin --json notebooks list

# 有状态项目
cli-anything-joplin project new --name demo -o ./demo.joplin-harness.json
cli-anything-joplin --project ./demo.joplin-harness.json notes create "会议笔记"

# 试运行（不自动保存）
cli-anything-joplin --json --dry-run --project ./demo.joplin-harness.json notes create temp

JSON 输出契约

启用 --json 时，命令返回：

• ok：布尔值
• command：稳定的命令标识符，例如 notes.list、todos.toggle
• data：命令负载
• error：成功时为 null，失败时为 { type, message }

命令分组

• project：new, open, save, info, json, status
• notebooks：list, create, use, remove
• notes：list, create, set, get, remove, copy, move, rename
• todos：list, create, toggle, clear, done, undone
• tags：list, add, remove, notetags, tagnotes
• search：run
• sync：run（--target, --upgrade, --use-lock）
• interop：import, export
• config：get, set, list, export, import-file
• attach：add
• status：show, restore
• backend：version, dump, keymap, geoloc, export-sync-status
• server：status, start, stop
• e2ee：status, target-status, decrypt, decrypt-file
• session：status, undo, redo, history

代理指导

• 优先使用 --json 以获得可解析的输出。
• 在执行多步工作流时使用 --project，以便持久化历史记录。
• 单次修改命令会自动保存项目，除非设置了 --dry-run。
• REPL 模式不会自动保存；请显式运行 project save。
• 某些 Joplin CLI 构建版本将 search 限制在 GUI 模式下；如果看到 "only available in GUI mode"，请将搜索视为尽力而为。
• Joplin 3.6.x 在 npm 全局布局中可能存在损坏的 version 命令；封装层会回退到已安装包元数据获取 backend version，通过探测符号链接解析后的二进制目录、Windows 样式同级目录 node_modules/joplin、Unix 样式父目录 lib/node_modules/joplin，以及最后的 npm root -g。
• 命令结果中的后端 stdout/stderr 为原样输出；不要假设警告已从笔记正文或导出内容中移除。
• 失败时，使用与成功时相同的 command 字段解析 error（config.import_file、e2ee.decrypt_file）。多词子命令在分组和子命令之间使用单个点。

测试工作流

# 快速反馈循环
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

# 验证已安装的控制台脚本入口点
CLI_ANYTHING_FORCE_INSTALLED=1 python -m pytest -v -s cli_anything/joplin/tests/test_full_e2e.py

当前验证基线（Windows + Joplin CLI 3.6.2）：

• python -m pytest -q cli_anything/joplin/tests/test_core.py -> 107 passed
• python -m pytest -q cli_anything/joplin/tests -> 134 passed, 1 skipped