名称： logseq
描述： 通过 Logseq 插件 API 与本地 Logseq 实例交互。可用于创建页面、插入块、查询图谱数据库、管理任务、检索内容或自动化 Logseq 工作流。仅适用于已启用 API 的本地运行实例；默认端口或为 [$API 可访问技能] 设置路径。

Logseq 插件 API

通过 JavaScript 插件 API 与您的本地 Logseq 实例交互。此技能支持在您的 Logseq 图谱中进行读取、写入、查询和自动化工作流。

前提条件

Logseq 必须在本地运行，并且有一个暴露 API 的插件。标准方法是：

1. 安装桥接插件：通过 HTTP 暴露 logseq API（例如，通过自定义插件或 localhost 端点）。
2. 替代方案：使用 Node.js 和 @logseq/libs 包来编写脚本与运行的 Logseq 实例交互。

该 API 主要为浏览器内插件设计，因此从外部脚本访问需要一个桥接/代理。

核心 API 命名空间

Logseq 插件 API 组织为以下几个主要代理：

logseq.App

应用级操作：获取应用信息、用户配置、当前图谱、命令、UI 状态、外部链接。

关键方法：
- getInfo() - 获取应用版本和信息
- getUserConfigs() - 获取用户偏好设置（主题、格式、语言等）
- getCurrentGraph() - 获取当前图谱信息（名称、路径、URL）
- registerCommand(type, opts, action) - 注册自定义命令
- pushState(route, params, query) - 导航到路由

logseq.Editor

块和页面编辑操作：创建、更新、移动、查询内容。

关键方法：
- getBlock(uuid) - 通过 UUID 获取块
- getCurrentPage() - 获取当前页面实体
- getCurrentPageBlocksTree() - 获取当前页面的所有块
- getPageBlocksTree(page) - 获取特定页面的所有块
- insertBlock(target, content, opts) - 插入新块
- updateBlock(uuid, content) - 更新块内容
- createPage(pageName, properties, opts) - 创建新页面
- deletePage(pageName) - 删除页面
- getPageLinkedReferences(page) - 获取页面的反向链接
- registerSlashCommand(tag, action) - 添加自定义斜杠命令

logseq.DB

使用 Datalog 进行数据库查询。

关键方法：
- q(query, ...inputs) - 运行 Datalog 查询
- datascriptQuery(query, ...inputs) - 直接 Datascript 查询

logseq.UI

UI 操作：消息、对话框、主 UI 可见性。

关键方法：
- showMsg(content, status) - 显示 toast 通知
- queryElementById(id) - 查询 DOM 元素

logseq.Git

当前图谱的 Git 操作。

关键方法：
- execCommand(args) - 执行 git 命令

logseq.Assets

资产管理。

关键方法：
- listFilesOfCurrentGraph(path) - 列出图谱中的文件

常用工作流

读取内容

// 获取当前页面
const page = await logseq.Editor.getCurrentPage();

// 获取页面上的所有块
const blocks = await logseq.Editor.getPageBlocksTree('Daily Notes');

// 获取特定块
const block = await logseq.Editor.getBlock('block-uuid-here');

// 使用 Datalog 查询
const results = await logseq.DB.q(`
  [:find (pull ?b [*])
   :where [?b :block/marker "TODO"]]
`);

写入内容

// 创建新页面
await logseq.Editor.createPage('Project Notes', {
  tags: 'project',
  status: 'active'
}, { redirect: false });

// 插入块
const block = await logseq.Editor.insertBlock(
  'target-block-uuid',
  '- New task item',
  { before: false, sibling: true }
);

// 更新块
await logseq.Editor.updateBlock('block-uuid', 'Updated content');

// 批量插入多个块
const blocks = [
  { content: 'First item' },
  { content: 'Second item', children: [
    { content: 'Nested item' }
  ]}
];
await logseq.Editor.insertBatchBlock('parent-uuid', blocks, { sibling: false });

任务管理

// 查找所有 TODO 项
const todos = await logseq.DB.q(`
  [:find (pull ?b [*])
   :where
   [?b :block/marker ?marker]
   [(contains? #{"TODO" "DOING"} ?marker)]]
`);

// 将任务标记为 DONE
await logseq.Editor.updateBlock('task-uuid', 'DONE Task content');

// 获取当前页面上的任务
const page = await logseq.Editor.getCurrentPage();
const blocks = await logseq.Editor.getPageBlocksTree(page.name);
const tasks = blocks.filter(b => b.marker === 'TODO' || b.marker === 'DOING');

导航与 UI

// 导航到页面
logseq.App.pushState('page', { name: 'Project Notes' });

// 显示通知
logseq.UI.showMsg('✅ Task completed!', 'success');

// 获取应用配置
const configs = await logseq.App.getUserConfigs();
console.log('Theme:', configs.preferredThemeMode);
console.log('Format:', configs.preferredFormat);

实现方法

由于 Logseq 的插件 API 是基于浏览器的，您有以下几种选择：

选项 1：桥接插件

创建一个最小的 Logseq 插件，通过 HTTP 暴露 API 调用：

// 在 Logseq 插件中 (index.js)
logseq.ready(() => {
  // 暴露 API 端点
  logseq.provideModel({
    async handleAPICall({ method, args }) {
      return await logseq.Editor[method](...args);
    }
  });
});

// 然后通过 HTTP POST 从外部脚本调用

选项 2：使用 @logseq/libs 的 Node.js 脚本

对于自动化脚本，使用 @logseq/libs 包：

npm install @logseq/libs

注意： 这需要一个正在运行的 Logseq 实例和正确的连接设置。

选项 3：直接插件开发

按照以下示例开发一个完整的 Logseq 插件：
https://github.com/logseq/logseq-plugin-samples

API 参考

完整的 API 文档，请参阅：
- API 文档: https://logseq.github.io/plugins/
- 插件示例: https://github.com/logseq/logseq-plugin-samples
- 类型定义: references/api-types.md (从 @logseq/libs 提取)

关键数据结构

BlockEntity

{
  id: number,           // 实体 ID
  uuid: string,         // 块 UUID
  content: string,      // 块内容
  format: 'markdown' | 'org',
  page: { id: number }, // 父页面
  parent: { id: number }, // 父块
  left: { id: number }, // 前一个兄弟块
  properties: {},       // 块属性
  marker?: string,      // TODO/DOING/DONE
  children?: []         // 子块
}

PageEntity

{
  id: number,
  uuid: string,
  name: string,              // 页面名称（小写）
  originalName: string,       // 原始大小写
  'journal?': boolean,
  properties: {},
  journalDay?: number,       // 日记的 YYYYMMDD 格式
}

技巧与最佳实践

1. 始终检查 null：如果实体不存在，API 方法可能返回 null
2. 使用 UUID 而非 ID：块 UUID 是稳定的，实体 ID 可能改变
3. 批量操作：对于多次插入，使用 insertBatchBlock
4. 高效查询：Datalog 查询功能强大，但在大型图谱上可能较慢
5. 属性是对象：使用 block.properties.propertyName 访问
6. 格式很重要：尊重用户的首选格式（markdown 与 org-mode）
7. 全程异步：所有 API 调用都返回 Promise

常见陷阱

• 页面名称是小写的：查询时，使用小写的页面名称
• 日记页面：使用 journalDay 格式 (YYYYMMDD)，而非日期字符串
• 块层次结构：插入时尊重父/子关系
• 格式差异：Markdown 使用 - 作为项目符号，Org 使用 *
• 属性语法：Markdown (prop::) 和 Org (:PROPERTIES:) 之间不同