@hy-sde-org dsh-tool-logseq

英语| 中文

总结

dsh-tool-logseq 允许代理从终端驱动Logseq数据库图形：列表、显示、搜索、datalog查询、删除和删除块、页面、标签、属性、任务和资产，以及图形和服务器生命周期操作。当你想要确定的JSON输出、数据日志查询、结构化任务更新或完全无头操作时，选择桌面应用程序MCP桥，而不是MCP桥，MCP桥需要打开应用程序，缺乏删除、数据日志和任务命令。这些工具运行已安装的 logseq CLI，所以CLI必须安装，每次调用支付一个进程衍生；最便宜的路径是批量写入单个 logseq_upsert 调用并启动一个无头服务器 logseq_server start.

目录表

• 工具表面
• 为什么是CLI而不是MCP
• 配置
• 模型经验
• 已知的限制和延迟的工作
• Dev注意

Model-facing Logseq 直接从终端驱动Logseq数据库图的CLI工具。surface是桌面应用程序MCP桥的本地替代品：除了基本的读写功能外，它还增加了MCP桥不能做的事情——数据记录 query， remove、一流的 task Upserts，以及图形/服务器生命周期-全部从安装包中打包 logseq CLI (opam exec -- dune build @bundle，或预构建的二进制文件)。

工具表面

• logseq_list [entityType=page] [limit] [offset] [sort] [order] [fields] [includeBuiltIn] [journalOnly] [includeHidden] [withProperties] [withExtends] [taskStatus] [taskPriority] [content] -列表页面，标签，属性，任务，节点或资产从图形与实体特定的切换。
• logseq_show [page | id | uuid] [level] [pageHierarchy] [linkedReferences] -将块/页面树渲染为文本。
• logseq_search [entityType] [content] [limit] -全文搜索块/页/属性/标签。
• logseq_query [query | name] [inputs] [limit] -数据脚本查询（结构性问题一跳不能回答）。
• logseq_upsert [entityType] [...] -创建/更新块，页面，标签，属性和任务；任务变得有条理 status/priority/scheduled/deadline，标签/属性是edn映射的，从不嵌入到内容中。
• logseq_remove [entityType] [id|uuid|page|name] -永久清除（仅在确定时使用）。
• logseq_graph [action] [...] - validate/info/export (edn|sqlite)/import/backup lifecycle。
• logseq_server [action] -列出/启动/停止/重启/清理db-worker-node服务器； start 启用完全无头操作，没有桌面应用程序。

为什么是CLI而不是MCP

桌面MCP桥在应用程序打开时提供相同的图，但需要app +令牌头，没有Datalog，没有删除，没有任务命令，并且将大型原始模式转储到每个请求中。CLI包装器是确定性JSON (--output json → {"status":"ok","data":…})，无头，全表面，紧凑。如果您想要零维护的回退，请保持禁用MCP行。

配置

import { Context } from '@deepseek-ai/cordis'
import toolLogseqPackage from '@hy-sde-org/dsh-tool-logseq'

const ctx = new Context()
ctx.plugin(toolLogseqPackage, {
  cliPath: 'logseq', // CLI executable (default: on PATH)
  graph: 'llm-wiki', // always pass --graph <name>
  timeoutMs: 60000, // per-call process timeout
  maxItems: 50, // cap on rendered list/search items
})

设置 graph 使每个调用都显示其目标图。当缺少CLI时，插件激活不变量会快速失败，并伴有安装提示。

模型经验

工具模式

模型看到了什么

工具描述+模式对CLI契约进行编码，因此模型更倾向于CLI路径而不是MCP桥接，每次调用批量写入一个逻辑更改，并在内容中使用结构化任务状态而不是TODO标记。

牌效应

8个手工编写的模式一次添加到请求前缀中（总共约1-2 KB），远小于MCP upsertNodes 每个调用的Schema；结果是紧凑的渲染(上限为 maxItems)，因此无论图形大小如何，令牌成本都是有限的。

高速缓存效应

所有模式都是静态的；每次调用的参数不同，但从不限制请求前缀。缓存的前缀在调用之间保持有效。

结果值

模型看到了什么

结构化枚举和查询行作为纯数据，再加上CLI的人工树文本 show． 人为错误信封(Error (...) 印刷)表面 LogseqCliError 有了argv，就永远不会有虚假的成功。

牌效应

列表/搜索结果的上限为(maxItems，默认为50)并汇总；查询行被平展为紧凑的行；服务器/图形表通过小的纯文本传递。

高速缓存效应

结果是每个调用的快照；没有会改变模型的rerun前缀的回读。

提示部分

模型看到了什么

一个 logseq:tools card：更喜欢CLI而不是MCP，每次调用一个逻辑更改，创建前检查存在，删除是永久的，任务使用结构化状态，以及 logseq_server 从无头使用开始。

牌效应

六个简短的行添加到请求前缀一次；每回合可以忽略不计。

高速缓存效应

静态节文本-没有无效。

已知的限制和延迟的工作

• 必须安装CLI -工具刷出 logseq;没有捆绑的二进制文件（CLI是从logseq repo构建的）。激活不变量给出安装提示和 cliPath 支持非path二进制文件。
• 每个调用进程生成 -每个工具调用启动一个新的CLI进程（CLI自己的模型）。高频壳（许多独立编辑）成本流程初创公司；单批结构化更改 logseq_upsert 调用。
• 需要图形服务器 -图需要一个db-worker-node服务器这些工具重用正在运行的应用程序（包括桌面应用程序）或 logseq_server start 发射一个无头炸弹。停止的服务器显示为CLI错误，而不是一个干净的重试路径。
• JSON形状是在运行时读取的 - - - - - - list/search/query item字段遵循CLI的JSON契约；如果未来的CLI改变了形状，压缩渲染会优雅地降级，而不是崩溃。
• 不上传资产 - - - - - - logseq_upsert/logseq_list 仅通过通用节点/资产列表覆盖资产；二进制资产摄取目前仍然是一个文件/CLI问题。

Dev注意