查找并列出思源笔记中的笔记本。

适用场景: - 快速获取所有笔记本 ID 以便后续写入/查询工具使用。 - 通过名称关键字做轻量筛选。

使用方法: - name: 可选，大小写不敏感的包含匹配。 - limit: 返回数量上限，默认 10。

注意事项: - 返回结果为笔记本原始信息（含 id/name/icon/closed 等字段）。 - 若需要精确匹配名称，请在调用方自行做二次过滤。

Args: name (Optional[str]): 用于模糊搜索笔记本的名称。如果省略，则列出所有笔记本。 limit (int): 返回结果的最大数量，默认为 10。

Returns: list: 包含笔记本信息的字典列表，每个字典包含 'name' 和 'id'。

在指定的笔记本中查找文档，支持多种过滤条件。

适用场景: - 按笔记本、标题、创建/更新时间筛选文档块（type='d'）。

使用方法: - notebook_id: 指定笔记本范围。 - title: 对文档名称字段做 LIKE 模糊匹配。 - created_after / updated_after: 传入 YYYYMMDDHHMMSS。

注意事项: - 本工具按 blocks.name 过滤标题，不按 hpath 过滤。 - 若需要更复杂条件（例如按 hpath 前缀），请使用 execute_sql。

Args: notebook_id (Optional[str]): 在哪个笔记本中查找。如果省略，则在所有打开的笔记本中查找。 title (Optional[str]): 根据文档标题进行模糊匹配。 created_after (Optional[str]): 查找在此日期之后创建的文档，格式为 'YYYYMMDDHHMMSS'。 updated_after (Optional[str]): 查找在此日期之后更新的文档，格式为 'YYYYMMDDHHMMSS'。 limit (int): 返回结果的最大数量，默认为 10。

Returns: list: 包含文档信息的字典列表，每个字典包含 'name', 'id', 和 'hpath'。

根据关键词、类型等多种条件在思源笔记中搜索内容块。

这是最核心和最灵活的查询工具。

适用场景: - 全局关键词检索。 - 按块类型和时间窗口缩小范围。

使用方法: - query: 使用 SQL LIKE 语义匹配 content。 - parent_id: 按直接父块 ID 过滤。 - block_type: 例如 p/h/l。

注意事项: - parent_id 仅匹配直接子块，不会递归后代。 - 返回 content 会做敏感信息打码处理。

Args: query (str): 在块内容中搜索的关键词。 parent_id (Optional[str]): 在哪个文档或父块下进行搜索。如果省略，则全局搜索。 block_type (Optional[str]): 限制块的类型，例如 'p' (段落), 'h' (标题), 'l' (列表)。 created_after (Optional[str]): 查找在此日期之后创建的块，格式为 'YYYYMMDDHHMMSS'。 updated_after (Optional[str]): 查找在此日期之后更新的块，格式为 'YYYYMMDDHHMMSS'。 limit (int): 返回结果的最大数量，默认为 20。

Returns: list: 包含块信息的字典列表。

获取指定块的完整 Markdown 内容。

适用场景: - 读取单个块的 kramdown 原文并用于审阅或后续处理。

注意事项: - 返回的 kramdown 会进行敏感信息打码。 - 思源属性标记中的块 ID / 时间戳会被保留，便于定位。

Args: block_id (str): 块的 ID

Returns: Dict[str, Any]: 包含块内容的字典

批量获取多个块的完整内容。

适用场景: - 一次性拉取多个块内容，减少多次调用开销。

注意事项: - 单个块失败不会中断整体，失败项会返回 error 字段。 - 返回的 kramdown 与 get_block_content 一样会做敏感信息打码。

Args: block_ids (List[str]): 块 ID 列表

Returns: List[Dict[str, Any]]: 包含每个块内容的字典列表

直接对数据库执行只读的 SELECT 查询。

适用场景: - 需要跨字段、跨表的高级筛选能力。 - 内置查询工具无法覆盖的复杂检索。

使用方法: - 仅支持 SELECT 语句。 - 建议显式 LIMIT，避免一次返回过多数据。

注意事项: - 返回的字符串字段会进行敏感信息打码。 - 如需精确审计原始敏感字段值，不适合使用该工具。

Args: query (str): SQL SELECT 查询语句

Returns: List[Dict[str, Any]]: 查询结果列表

Raises: ValueError: 如果查询不是 SELECT 语句

推送前台消息。

适用场景: - 在写入流程中向前台反馈进度或结果。

注意事项: - msg 必须是非空字符串。 - timeout 必须是正整数毫秒值。

Args: msg: 消息内容。 timeout: 消息显示时长（毫秒），默认 7000。

Returns: Dict[str, Any]: 包含消息 id 的字典。

推送前台错误消息。

适用场景: - 在参数校验或接口调用失败时向前台反馈错误。

注意事项: - msg 必须是非空字符串。 - timeout 必须是正整数毫秒值。

Args: msg: 错误消息内容。 timeout: 消息显示时长（毫秒），默认 7000。

Returns: Dict[str, Any]: 包含消息 id 的字典。

通过 Markdown 创建文档。

适用场景: - 根据固定路径批量创建结构化文档。 - 快速写入一篇完整 Markdown 文档。

使用方法: - notebook_id: 目标笔记本 ID。 - path: 以 / 开头的人类可读路径。 - markdown: 文档 Markdown 正文。

注意事项: - path 必须以 / 开头。 - 思源 API 对相同 path 重复创建不会覆盖已有文档。

更新块内容。

适用场景: - 已知块 ID 时，直接替换该块内容。

使用方法: - block_id: 目标块 ID。 - data_type: 仅支持 markdown 或 dom。 - data: 新内容。

注意事项: - 这是整块替换，不是局部 patch。 - 修改前请确保 block_id 指向正确块，避免误改。

删除指定块。

适用场景: - 清理错误插入或不再需要的块。

注意事项: - 删除操作具破坏性，调用前建议先用查询工具确认 block_id。 - 返回值包含操作记录，可用于审计本次删除结果。

插入块（next_id / previous_id / parent_id 至少提供一个）。

适用场景: - 需要按相邻块位置插入（前置/后置锚点）。 - 需要按父块插入（指定 parent_id）。

使用方法: - next_id: 插入到 next_id 对应块之前。 - previous_id: 插入到 previous_id 对应块之后。 - parent_id: 插入为 parent_id 的子块。 - 三者可同时提供，但思源 API 优先级为 next_id > previous_id > parent_id。

注意事项: - 如果你要"确保挂到某个标题（如 H3）下面"，请显式传 parent_id， 或直接使用 append_block / prepend_block。 - 若 next_id/previous_id 与 parent_id 指向不同层级，最终位置会以 next_id/previous_id 优先，可能出现"看起来没挂到标题下"的情况。

与 prepend_block/append_block 的区别: - prepend_block/append_block 是"父块优先"，强制挂到父块下（开头/末尾）。 - insert_block 是"相邻优先"，依赖现有块的位置，可能产生层级歧义。

示例（假设现有结构：父块A -> 子块B -> 子块C）: # 插入到 B 之后（中间插入） insert_block(data="新块", previous_id="block_b") # 结果：A -> B -> 新块 -> C

# 插入到 B 之前
insert_block(data="新块", next_id="block_b")
# 结果：A -> 新块 -> B -> C

# 作为 A 的子块插入（不推荐，可能被相邻锚点覆盖）
insert_block(data="新块", parent_id="block_a")
# 注意：若同时传了 previous_id/next_id，parent_id 会被忽略

插入前置子块。

适用场景: - 需要稳定地插入到某个父块下（强父子关系）。 - 例如把列表、段落挂到某个 H2/H3 下。

使用方法: - parent_id 传入目标父块 ID。 - data 为待插入内容，data_type 支持 markdown 或 dom。

注意事项: - 该工具是"父块优先"的安全写入方式，不依赖 next_id/previous_id。 - 若需要基于相邻块精确定位，请使用 insert_block。

与 insert_block 的区别: - prepend_block 强制作为父块的第一个子块，层级关系稳定。 - insert_block 依赖相邻块定位，层级可能因 next_id/previous_id 而变化。

示例（假设现有结构：父块A -> 子块B -> 子块C）: # 插入到 A 的开头（作为第一个子块） prepend_block(parent_id="block_a", data="新块") # 结果：A -> 新块 -> B -> C

插入后置子块。

适用场景: - 需要稳定地追加到某个父块末尾（强父子关系）。 - 例如把有序/无序列表追加到某个 H2/H3 下。

使用方法: - parent_id 传入目标父块 ID。 - data 为待插入内容，data_type 支持 markdown 或 dom。

注意事项: - 该工具不会使用 next_id/previous_id 锚点，适合避免层级歧义。 - 若需要插入到父块子节点中间位置，请使用 insert_block 并结合锚点。

与 insert_block 的区别: - append_block 强制作为父块的最后一个子块，层级关系稳定。 - insert_block 依赖相邻块定位，层级可能因 next_id/previous_id 而变化。

示例（假设现有结构：父块A -> 子块B -> 子块C）: # 插入到 A 的末尾（作为最后一个子块） append_block(parent_id="block_a", data="新块") # 结果：A -> B -> C -> 新块

移动块（previous_id / parent_id 至少提供一个）。

适用场景: - 调整块顺序（基于 previous_id 锚点）。 - 调整父子归属（基于 parent_id）。 - 调整分节或层级结构时，保持相关内容整体移动。

使用方法: - previous_id: 把 block_id 移动到 previous_id 之后。 - parent_id: 把 block_id 移动到 parent_id 之下。 - allow_heading_only_move: 兼容旧参数，已废弃；传 true 会报错。

注意事项: - 若 block_id 是标题块（h1-h6），将按“分节范围”移动： 从该标题开始，直到下一个同级或更高级标题（level <= 当前 level）之前的所有块一起移动。 - 其他块默认按“子树块组”移动：目标块 + 全部后代，避免父块与子块脱离。 - 思源 API 对同传 previous_id 和 parent_id 时会优先 previous_id。 - previous_id / parent_id 不能指向正在移动的子树内部块。

与 insert_block 的区别: - insert_block 是插入一个新块。 - move_block 是移动已有块的位置。

安全建议（重要）: - 不做“单块父节点移动”，统一执行整组移动，避免父块与内容脱离。 - 若目标是“稳定挂到某个父块”，优先提供 parent_id。

示例（假设现有结构：父块A -> 子块B -> 子块C -> 子块D）: # 调整顺序：移动 C 到 B 之后（不改变层级） move_block(block_id="block_c", previous_id="block_b") # 结果：A -> B -> C -> D（顺序不变，因为 C 原本就在 B 之后）

# 调整层级：移动 C 成为 B 的子块
move_block(block_id="block_c", parent_id="block_b")
# 结果：A -> B -> C（现在 C 是 B 的子块）-> D

# 同时调整顺序和层级
move_block(block_id="block_c", previous_id="block_b", parent_id="block_a")
# 注意：API 会优先处理 previous_id，parent_id 可能被忽略

列出指定路径下的文件和文件夹（只读）。

常用于探索 '/data' 目录结构，例如查看 '/data/history' 下的快照。

注意事项: - 该工具仅读取目录，不会修改任何文件。 - 返回结果依赖思源工作空间内的实际路径权限。

Args: path: 路径，例如 '/data' 或 '/data/history'。

Returns: list: 包含文件和文件夹信息的字典列表。

读取指定文件的内容（只读）。

用于读取历史快照或其他数据文件。

注意事项: - 文本内容会进行敏感信息打码。 - 若文件为二进制且无法解码为 UTF-8，将返回 '[Binary Data]'。

Args: path: 文件路径，例如 '/data/history/2023/01/...'。

Returns: str: 文件内容（文本）或二进制数据提示。

读取指定文件内容并以 Base64 返回（只读）。

适用于需要以 Base64 形式返回的 UTF-8 文本文件（例如历史快照里的 JSON）。

注意事项: - 本实现会先按 UTF-8 解码后再打码并进行 Base64 编码。 - 若文件为纯二进制且无法 UTF-8 解码，将抛出异常（不支持二进制打码）。

Args: path: 文件路径，例如 '/history/.../blocks.msgpack'。

Returns: str: Base64 编码的文件内容（已打码）。

列出历史快照目录下的文件和文件夹。

注意事项: - path 必须以 '/history' 或 '/data/history' 开头。 - 该工具用于枚举历史目录，不直接返回快照内容。

Args: path: 历史目录路径，默认为 "/history"。

Returns: list: 历史目录下的条目列表。

读取历史快照文件内容（只读）。

注意事项: - path 必须以 '/history' 或 '/data/history' 开头。 - 行为与 get_file 一致，文本会做敏感信息打码。

Args: path: 历史快照文件路径，必须以 "/history" 或 "/data/history" 开头。

Returns: str: 历史快照文件内容。

查询指定时间范围内新增或修改的内容块。

适用场景:

• 只需要变更清单/索引, 不关心逐块前后差异。

• 需要快速筛选近期新增或更新的块。

与 get_block_diffs 的区别:

• 本函数不做历史快照对比, 不返回 before/after。

• 返回的是当前块的字段快照(例如 content/markdown)。

注意事项:

• deleted 当前恒为空；删除块需要结合历史快照比对才能识别。

• include_markdown=true 会显著增大返回体量，建议配合 limit 使用。

Args: start_time: 起始时间，格式为 'YYYYMMDDHHMMSS'。 end_time: 结束时间，格式为 'YYYYMMDDHHMMSS'，可选。 limit: 最大返回条目数，默认为 200。 include_markdown: 是否返回 markdown 字段，默认 false。

Returns: Dict[str, Any]: 包含新增与修改块列表以及历史快照可用性信息。

查询指定时间范围内修改的内容块并返回前后对比。

适用场景:

• 需要审计每个块的具体改动(含 before/after)。

• 需要变更类型(新增/删减/替换)和差异统计。

与 get_block_changes 的区别:

• 本函数会读取历史快照并与当前内容对比。

• 返回 before/after 文本和 diff 统计, 但更重且依赖 /history。

注意事项:

• 依赖 history_root 可读；若历史目录不可访问，将无法完成比对。

• before/after 为脱敏文本；max_text_length 会对长文本截断。

Args: start_time: 起始时间，格式为 'YYYYMMDDHHMMSS'。 end_time: 结束时间，格式为 'YYYYMMDDHHMMSS'，可选。 limit: 最大返回条目数，默认为 50。 history_root: 历史快照根目录，默认为 '/history'。 max_text_length: 前后文本最大长度，超出将截断。

Returns: Dict[str, Any]: 包含块变更差异结果。