CLI-Anything 与思源笔记基于 SiYuan 内核 HTTP API 的终端知识库管理实战【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本文围绕cli-anything-siyuan这一 Agent 原生 CLI 工具展开讲解如何通过命令行与 SiYuan思源笔记内核的 HTTP API默认http://127.0.0.1:6806交互实现笔记本、文档、内容块Block、全文检索、SQL 查询与 Markdown 导出等完整知识库管理能力。读完本文你将掌握该 CLI 的全部命令组与参数细节、连接与鉴权配置的三种方式、面向 Agent 的 JSON 输出与 stdin 管道技巧并能基于仓库源码理解其底层调用链与错误处理机制。一、为什么思源笔记需要一个 CLI 桥接层思源笔记是本地优先、隐私至上的知识管理与笔记应用后端为 Go 内核、前端为 Electron/TypeScript数据以.sy文件存储并配套 SQLite 数据库用于索引与检索。它原生只提供桌面 GUI 与移动端没有独立的 headless CLI 模式——内核随 GUI 自动启动默认监听 6806 端口但没有任何命令行管理入口。cli-anything-siyuan正是为此而生它作为 Agent 原生桥接层连接到一个已在运行的思源内核实例通过内核暴露的 HTTP API 提供结构化访问能力。仓库内 SIYUAN.md 对该桥接策略有明确描述归纳为五点连接运行中的实例、覆盖全部主要 API 分组、持久化连接状态、支持 SQL 高级查询、支持 Markdown 导入导出。从数据模型看思源采用三层结构Notebook笔记本即 Box→ Document文档树节点对应 .sy 文件→ Block内容块段落/标题/列表等块之上还可挂接custom-*前缀的属性键值对。所有 ID 均为时间戳型形如20210817205410-2kvfpfn日期时间 随机后缀。这一模型直接决定了 CLI 的命令分组设计。二、前置条件与安装使用该 CLI 需要满足以下条件与 SKILL.md 一致思源笔记必须处于运行状态且 API 服务已启用默认端口 6806Python 3.10安装 CLI 包。安装方式有两种二选一# 方式一从 PyPI 安装 pip install cli-anything-siyuan # 方式二从仓库 agent-harness/ 目录本地安装开发模式 cd agent-harness pip install -e .若需要交互式 REPL 支持推荐安装带replextra 的版本pip install -e .[repl]从 setup.py 可以看到该包声明python_requires3.10运行时依赖仅两个click8.0命令行框架与requests2.28HTTP 客户端repl可选依赖为prompt_toolkit3.0test可选依赖为pytest7.0。安装后通过 entry point 注册cli-anything-siyuan命令其指向 siyuan_cli.py 中的cli入口函数。三、连接与鉴权配置CLI 通过 Token 鉴权访问思源内核。Token 可以在思源界面设置 → 关于 → API Token中查看。3.1 三种配置途径配置遵循「显式路径 → 环境变量 → 默认值」的优先级顺序由 client.py 中的load_config()实现① CLI 参数优先级最高cli-anything-siyuan --host 127.0.0.1 --port 6806 --token your-token notebook list② 环境变量export SIYUAN_HOST127.0.0.1 export SIYUAN_PORT6806 export SIYUAN_TOKENyour-token③ 配置文件~/.siyuan-cli.json默认持久化方式{ host: 127.0.0.1, port: 6806, token: your-api-token-here }也可用--config path显式指定其他配置文件路径。源码中load_config()的实际解析逻辑为若文件存在则读取 JSON用utf-8-sig编码以兼容带 BOM 的文件文件值作为基础环境变量优先覆盖文件值当 CLI 显式传入--host/--port/--token时siyuan_cli.py 会用它们构造最终配置并覆盖前面所有来源。SiYuanConfig是一个 frozen dataclass默认值为host127.0.0.1、port6806、token其base_url属性拼接为http://{host}:{port}。这些默认值在单元测试 test_core.py 的test_default_config中被逐一断言。3.2 请求鉴权细节SiYuanClient初始化时会创建requests.Session若配置了 token 则设置Authorization: Token {token}请求头并固定Content-Type: application/json见 client.py。所有 API 请求均通过_post()统一发送超时时间为 30 秒。小技巧仓库还提供了 siyuan_backend.py其中find_siyuan_data_dir()按平台探测思源数据目录Windows 为%USERPROFILE%\SiYuan\data\Linux/macOS 为~/.config/siyuan/data/get_api_token_from_conf()还能尝试直接从思源conf/conf.json中的api.token字段读取 token方便免手动复制。四、命令组全景CLI 按思源的数据模型划分为notebook、doc、block三大命令组外加sql、search、export、tag、version、status、repl等顶层命令。4.1 notebook — 笔记本管理子命令说明notebook list列出全部笔记本notebook create name新建笔记本notebook rename id name重命名笔记本notebook remove id删除笔记本notebook open id打开笔记本同时写入会话状态示例cli-anything-siyuan notebook list cli-anything-siyuan notebook create AI Research cli-anything-siyuan notebook rename 20210817205410-2kvfpfn AI 研究 cli-anything-siyuan notebook open 20210817205410-2kvfpfn底层调用链清晰可见notebook list对应 client.py 中的list_notebooks()→POST /api/notebook/lsNotebookscreate调用create_notebook()→POST /api/notebook/createNotebook创建成功后 CLI 还会自动open_notebook()并更新会话。文本模式下列表以三列表格输出ID、名称、Closed 状态宽度对齐为 30 字符。4.2 doc — 文档管理子命令说明doc create notebook path [--md content]按路径创建文档可带 Markdown 内容doc list notebook [path]列出指定路径下的文档默认/doc tree notebook [--path / --depth]以树形展示文档层级doc get id通过 ID 获取文档的人类可读路径hpathdoc rename id title按 ID 重命名文档doc remove id按 ID 删除文档示例# 创建空文档 cli-anything-siyuan doc create nb1 /projects/new # 创建带 Markdown 内容的文档 cli-anything-siyuan doc create nb1 /projects/new --md ## Title\n\nContent # 列出文档 cli-anything-siyuan doc list nb1 /projects # 查看整棵树支持 --path 指定根路径、--depth 限制深度 cli-anything-siyuan doc tree nb1 --path / --depth 3实现细节doc create对应create_doc_with_md()→POST /api/filetree/createDocWithMd请求体为{notebook, path, markdown}三字段测试test_create_doc_with_md精确断言了这三个字段。doc list调list_docs_by_path()时显式传入maxListCount: 0以解除默认列表条数上限对应/api/filetree/listDocsByPath。doc tree调list_doc_tree()并利用 siyuan_cli.py 中的_walk_tree()递归扁平化嵌套children为每个条目附加depth字段后再渲染缩进树--depth对应 API 的maxDepth参数默认-1表示不限制。4.3 block — 内容块操作子命令说明block insert data [--previous / --parent / --next]在锚点位置插入块block update id data更新块内容block delete id删除块block get id获取块的 kramdown 源码block children id获取子块列表块插入必须指定三个锚点参数之一--parent id作为首子块、--previous id插入到某块之前、--next id插入到某块之后。缺少锚点时 CLI 会抛出UsageError: An anchor is required: --parent, --previous, or --next测试test_block_insert_without_anchor_errors验证了该行为。示例# 作为父块的子块插入 cli-anything-siyuan block insert hello world --parent pid123 # 插入到指定块之前 cli-anything-siyuan block insert hello --previous prev123 # 更新块多行内容可经 stdin 传入 cat note.md | cli-anything-siyuan block update block-id # 查看块源码与子块 cli-anything-siyuan block get block-id cli-anything-siyuan block children block-id对应 APIinsertBlock可选parentID/previousID/nextID、updateBlock、deleteBlock、getBlockKramdown、getChildBlocks。默认--data-type markdown也支持dom类型对应--data-type参数。数据参数传-或省略时CLI 会从 stdin 读取完整内容——这是 SIYUAN.md 中明确记载的用法可避免 shell 转义问题。4.4 其他命令命令说明sql stmt在块数据库上执行 SQL如SELECT * FROM blockssearch query跨块全文检索export md doc-id将文档导出为 Markdowntag list列出全部标签含嵌套标签version显示思源内核版本status显示连接与会话状态repl进入交互式 REPL五、面向 Agent 的使用指导SKILL.md 中明确给出了四条面向 Agent/LLM 的核心指引这是该技能文件作为「Agent 原生技能」的关键设计机器可读输出一律使用--json所有命令都支持全局--json标志输出为标准 JSONensure_asciiFalse保留中文便于 Agent 直接解析。高级检索使用 SQLsql SELECT id, content FROM blocks WHERE content LIKE %keyword%可进行 SQL 级精准访问这比全文检索更可控。文档 ID 为时间戳型形如20210817205410-2kvfpfn可用作doc get、export md等命令的参数。连接默认值http://127.0.0.1:6806Token 在思源设置 → 关于中查看。5.1 SQL 检索的威力思源内核内置 SQLite 块数据库sql命令对应query_sql()→POST /api/query/sql。这让 Agent 可以突破普通搜索的局限# 精确检索含关键词的块 cli-anything-siyuan sql SELECT id, content FROM blocks WHERE content LIKE %meeting% LIMIT 5 # 限定块类型标题/段落/代码 cli-anything-siyuan sql SELECT id, type, content FROM blocks WHERE type h2 # 结合时间戳 ID 排序取最新文档 cli-anything-siyuan sql SELECT id, content FROM blocks ORDER BY id DESC LIMIT 10JSON 模式下结果以行数组输出每条记录是列名到值的映射文本模式下则渲染为表格。5.2 多行内容与 stdin 管道doc create的--md -、block insert/block update的数据参数-或省略都会触发 stdin 读取彻底规避 shell 转义问题。SKILL.md 给出了两种典型场景PowerShell here-string无需转义原样保留反引号、括号、引号 ## Title Content with backticks and (parentheses) and quotes | cli-anything-siyuan doc create nb1 /projects/new --md -Bash heredoccat EOF | cli-anything-siyuan doc create nb1 /projects/new --md - ## Title Content with backticks and (parentheses) EOF底层实现值得一提siyuan_cli.py 中的_read_stdin()不是直接读文本而是读取sys.stdin.buffer原始字节并以utf-8-sig解码。这是为了兼容中文 Windows 下 PowerShell 按控制台代码页如 GBK输出文本导致 CJK 乱码的问题——先读字节再按 UTF-8 解码是最稳妥的方案。六、交互式 REPL不带任何子命令直接运行cli-anything-siyuan即进入 REPL 模式源码中若未指定子命令会先ping()校验连接成功才进入 REPL。REPL 支持与 CLI 相同的命令集额外提供help、status、quit/exit/qsiyuan ❯ notebook list siyuan ❯ doc tree notebook-id siyuan ❯ search meeting notes siyuan ❯ help siyuan ❯ quitREPL 内部由 repl_skin.py 提供横幅、提示符、表格与成功/错误消息等皮肤渲染。会话状态当前笔记本、当前文档等由 session.py 的SessionManager管理持久化到~/.cli-anything-siyuan/session.json——例如notebook open后当前笔记本名称会显示在 REPL 提示符上下文里doc create后会记录当前文档路径。状态采用「标记脏 → flush 落盘」机制避免每次操作都写磁盘。七、搜索与导出实战全文检索# 普通输出默认展示前 20 条内容截断 120 字符 cli-anything-siyuan search 机器学习 # JSON 输出Agent 友好 cli-anything-siyuan --json search 机器学习search对应search_blocks()→POST /api/search/fullTextSearchBlock。测试 test_cli_commands.py 专门覆盖了思源真实返回格式{blocks: [...], rootBlocks: {...}}与扁平列表两种形态的兼容处理。Markdown 导出cli-anything-siyuan export md 20210817205410-2kvfpfn对应export_md_content()→POST /api/export/exportMdContent返回{hPath, content}。文本模式下 CLI 会把 hPath 作为标题行打印后跟完整 Markdown 正文。标签管理cli-anything-siyuan tag list对应get_tags()→POST /api/tag/getTag请求体中固定携带ignoreMaxListHint: true确保即使超过Conf.FileTree.MaxListCount阈值也返回完整标签列表见 SIYUAN.md 中的说明。文本输出支持嵌套标签的递归缩进与计数显示。八、错误处理与排障SKILL.md 归纳了三类典型错误及排查方向错误类型现象排查方法连接错误Cannot connect to SiYuan at http://...确认思源已运行、端口默认 6806正确API 错误API error: {...}或{code: N, msg: ...}查看返回的msg字段定位具体原因鉴权错误401/鉴权失败核对~/.siyuan-cli.json中的 token 或SIYUAN_TOKEN环境变量底层机制上SiYuanClient._post()对异常做了统一封装client.pyrequests.ConnectionError→ 提示「思源是否在运行」并附带完整 URL超时30 秒→ 明确的超时提示非 200 状态码 → 附带响应正文前 200 字符思源业务错误码非 0 → 抛出SiYuanClientError(API error: {msg})。CLI 顶层通过_CatchErrors继承 Click Group统一捕获SiYuanClientError以Error: ...形式输出到 stderr 并以退出码 1 结束避免打印 Python 堆栈。无参数启动时若连接失败会直接给出配置提示Configure via: --host --port --token或SIYUAN_HOST, SIYUAN_PORT, SIYUAN_TOKEN。另外 CLI 启动时会把 stdout/stderr 重配置为 UTF-8 编码保证中文输出在 Windows 终端不乱码。九、测试验证体系仓库为该 CLI 提供了三层测试test_core.py纯单元测试使用 MagicMock 模拟 HTTP 响应覆盖默认/自定义配置、环境变量与文件配置加载、ping()成功/失败、list_notebooks解析、create_doc_with_md请求体字段、SQL 查询、会话状态保存/加载、find_replace的k/r/ids载荷、maxListCount: 0等。test_cli_commands.py基于 ClickCliRunner的命令级测试验证 search/doc list/doc tree/notebook list/tag list/sql/status/block insert/doc get/doc create 等命令的文本与 JSON 输出格式包括「块插入缺锚点报错」「search 兼容两种返回形态」「doc tree 递归渲染嵌套 children」等边界场景。test_full_e2e.py端到端测试要求真实思源实例运行在http://127.0.0.1:6806可设SIYUAN_TOKEN否则自动跳过覆盖--help、--json version、--json status、真实版本获取与笔记本枚举。运行方式# 单元测试无需外部依赖 cd agent-harness pip install -e .[test] python -m pytest cli_anything/siyuan/tests/test_core.py -v # E2E 测试需要运行中的思源实例 python -m pytest cli_anything/siyuan/tests/test_full_e2e.py -v -s十、从技能文件到 Agent 原生能力cli-anything-siyuan不仅是一个 CLI 工具仓库还把它包装为 Agent 可直接调用的技能文件skills/cli-anything-siyuan/SKILL.md即本指南对应的技能文档同时在 siyuan/agent-harness/cli_anything/siyuan/skills/SKILL.md 维护源文件并由 setup.py 的package_data打包发布。技能文件通过 front-matter 声明技能名称与描述正文给出命令表、Agent 指引、可直接执行的示例含跨平台 stdin 管道方案与错误处理速查表使 LLM/Agent 无需阅读源码即可正确调用。对于希望深入底层的开发者建议按以下路径研读仓库源码siyuan_cli.py全部 Click 命令定义、REPL 调度与 stdin 读取逻辑client.pyHTTP 客户端、配置加载与全部 API 封装session.pyREPL 会话状态持久化SIYUAN.md思源 API Surface 全量清单与桥接策略分析README.md安装、配置、命令与测试运行的完整说明。结语通过cli-anything-siyuan思源笔记这座「本地优先」的知识库被完整地暴露给了终端与 AI Agent笔记本与文档的组织、内容块的精细操作、基于 SQLite 的 SQL 级检索、全文搜索与 Markdown 导出全部可在一条命令内完成。其设计要点——默认连接http://127.0.0.1:6806、--json机器可读输出、stdin 管道规避转义、会话状态持久化、统一的错误封装——共同构成了一个可靠、可自动化、可被 Agent 直接消费的 CLI 桥接层为「让所有软件 Agent 原生化」这一 CLI-Anything 项目理念提供了一个完整的落地方案。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考