# @hy-sde-org/dsh-tool-logseq 中文文档

规范地址：https://npmcn.com/package/%40hy-sde-org/dsh-tool-logseq/

版本：0\.2\.1-rc\.5
npm 元数据更新时间：2026-11-01T04:23:32.806Z
中文译文更新时间：2026-11-01T09:39:03.153Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40hy-sde-org/dsh-tool-logseq
原文对照：https://npmcn.com/package/%40hy-sde-org/dsh-tool-logseq/?lang=original
项目主页：https://github.com/hy-sde/dsh-logseq#readme
源码仓库：https://github.com/hy-sde/dsh-logseq

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：94.2 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/cordis ~4\.0\.5，@deepseek-ai/dsh-tools ^0\.2\.1-rc\.5，@hy-sde-org/dsh-logseq-graph ^0\.2\.1-rc\.5，@deepseek-ai/dsh-system-prompt ^0\.2\.1-rc\.5
- 首次发布：2026-09-06T03:18:53.919Z
- 最新版本发布：2026-11-01T04:23:32.630Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

面向模型的Logseq命令行工具（logseq\_list/upsert/remove/query/show/search/graph/server），用于从终端驱动Logseq数据库图形，可替代桌面MCP桥接

## 安装

```sh
npm install @hy-sde-org/dsh-tool-logseq
```

也可以使用：`pnpm add @hy-sde-org/dsh-tool-logseq`、`yarn add @hy-sde-org/dsh-tool-logseq`、`bun add @hy-sde-org/dsh-tool-logseq`

## README

# @hy-sde-org dsh-tool-logseq

英语| [中文](https://npmcn.com/package/%40hy-sde-org/dsh-tool-logseq/README.zh.md)

## 总结

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

## 目录表

-   [工具表面](https://npmcn.com/package/%40hy-sde-org/dsh-tool-logseq/#readme-tool-surface)
-   [为什么是CLI而不是MCP](https://npmcn.com/package/%40hy-sde-org/dsh-tool-logseq/#readme-why-cli-over-mcp)
-   [配置](https://npmcn.com/package/%40hy-sde-org/dsh-tool-logseq/#readme-configuration)
-   [模型经验](https://npmcn.com/package/%40hy-sde-org/dsh-tool-logseq/#readme-model-experience)
-   [已知的限制和延迟的工作](https://npmcn.com/package/%40hy-sde-org/dsh-tool-logseq/#readme-known-limitations-and-deferred-work)
-   [Dev注意](https://npmcn.com/package/%40hy-sde-org/dsh-tool-logseq/#readme-dev-note)

* * *

Model-facing [Logseq](https://logseq.com/) 直接从终端驱动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行。

## 配置

```ts
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注意

维护人员的工作上下文-单击展开

无。

## 常见问题

### @hy-sde-org/dsh-tool-logseq 是什么？

面向模型的Logseq命令行工具（logseq\_list/upsert/remove/query/show/search/graph/server），用于从终端驱动Logseq数据库图形，可替代桌面MCP桥接

### 如何安装 @hy-sde-org/dsh-tool-logseq？

在项目目录运行 npm install @hy-sde-org/dsh-tool-logseq，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（~4\.0\.5）、@deepseek-ai/dsh-tools（^0\.2\.1-rc\.5）、@hy-sde-org/dsh-logseq-graph（^0\.2\.1-rc\.5）、@deepseek-ai/dsh-system-prompt（^0\.2\.1-rc\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @hy-sde-org/dsh-tool-logseq 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @hy-sde-org/dsh-tool-logseq 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @hy-sde-org/dsh-tool-logseq 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @hy-sde-org/dsh-tool-logseq 可以商用吗？

@hy-sde-org/dsh-tool-logseq 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @hy-sde-org/dsh-tool-logseq 还在维护吗？

最新版本 0\.2\.1-rc\.5 发布于 2026/11/01（2 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/09/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。