C++迭代器失效与安全删除：从vector erase到容器遍历
2026/9/10 9:17:08
SiYuan v3.7.0 版本深度解读：命令行接口、内核插件系统与 AI 知识库的落地路径
【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan
SiYuan v3.7.0 是一次"全面焕新"的发布：界面重设计之外，更关键的是能力层面的三块基石——不启动图形界面即可直接操作数据的命令行接口（CLI）、常驻内核的插件系统、以及进入公测的 SiYuan Agent 与向量嵌入语义搜索。本文以 v3.7.0 官方更新日志为主线，结合内核源码逐项拆解这些能力的实现机制与可用参数，帮助你理解每个新特性的边界条件与底层行为。
一、版本总览：五大主线
官方更新日志 app/changelogs/v3.7.0/v3.7.0.md 将本版本概括为五个方向：
- 重设计的用户界面：更清晰的视觉层级，其中包含合并顶部标题栏与标签栏（issue #10749）、新版设置界面（PR #17675）、底部 Dock 改进（issue #8890）等具体条目；
- 移动端快捷入口（Shorthands）：长按 App 图标即可记录灵感，内容以带时间戳的笔记保存，保存路径可自定义（issue #14414）；
- 内核插件系统：插件常驻内核运行，成为唯一的"数据真相源"，让所有窗口与实例保持一致，终结多窗口数据冲突；
- 命令行接口（CLI）：不启动 SiYuan 即可直连内核数据层，用于批量导入/导出、定时处理与外部系统集成（issue #17674）；
- AI 知识库：SiYuan Agent 与向量嵌入搜索进入公测，支持用自然语言对话笔记、语义化检索与管理知识。
此外，本版本还支持了密钥与变量配置（issue #17933）、跨文档撤销（issue #4866）、本地 HTTPS + HTTP/2（issue #17822），以及乌克兰语、印地语、印尼语、荷兰语、泰语等 5 个新语言包，并为 Linux 提供了 rpm 发布包（PR #17596）。
二、命令行接口（CLI）：直连内核数据层
v3.7.0 最重要的工程性变化是引入了完整的 CLI。它基于 cobra，命令集覆盖笔记块、笔记本、文档、搜索、SQL、导入导出、同步、工作空间等 20 余个领域，对应 kernel/cli/cmd/ 目录下的各命令文件。
2.1 全局参数
从rootCmd的持久化 flag 定义（kernel/cli/cmd/root.go）可以确认四个全局参数：
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
--workspace | -w | 空 | 工作空间路径；留空时依次回退到环境变量SIYUAN_WORKSPACE_PATH，再回退到~/SiYuan |
--format | -f | table | 输出格式：table或json |
--dry-run | — | false | 干跑模式：只校验并打印将发生什么，不实际变更数据 |
--log-level | -v | — | 日志级别：off / trace / debug / info / warn / error / fatal；单次命令默认warn，serve子命令则跟随conf.json的system.logLevel |
2.2 启动时的初始化行为
PersistentPreRunE（kernel/cli/cmd/root.go）揭示了 CLI 单次命令的完整启动流程，也解释了若干使用前提：
- 工作目录解析：
resolveWorkingDir()从内核可执行文件位置探测包含appearance/langs的目录（打包态为resources/，兼容 macOS app bundle），并要求该目录存在，否则报错退出； - 工作空间校验：
-w指定的路径必须存在且通过util.IsWorkspaceDir校验，否则拒绝执行； - 数据库初始化：依次初始化主库、历史库与资产内容库，并按配置设置搜索大小写敏感性与资产路径索引开关；
- 语义搜索可用：调用
model.PrepareEmbeddingSearch()——源码注释说明，常驻的嵌入索引器是死循环不适合立即退出的进程，这里只打开开关，让search -m 4（语义模式）这类一次性命令也能命中向量搜索； - 退出前落库：
PersistentPostRunE在命令结束后统一调用model.FlushTxQueue()与sql.FlushQueue()，把内存中的 SQL 索引队列刷入磁盘——因为单次命令没有 server 模式的 cron 定时 flush，不做这一步"写完即搜"就无法保证。
2.3 加密笔记本的限制
CLI 对加密笔记本是显式拒绝的：rejectEncryptedNotebookCLI（kernel/cli/cmd/root.go）会检查notebook、box、id、parent等 flag 值以及文件/资产路径参数，凡涉及加密笔记本一律报错CLI does not support encrypted notebook [...]。源码注释给出了设计动机：加密笔记本只能通过应用内专用流程解锁与操作，避免 CLI 进程成为明文或密文文件的旁路入口。serve子命令不受此限制。
2.4 典型使用场景
结合命令目录与官方描述，CLI 的典型用法包括：
- 批量导入/导出：
import/export相关命令（kernel/cli/cmd/import.go、kernel/cli/cmd/export.go）； - 直接查询数据：
search、sql、block、database命令（kernel/cli/cmd/sql.go）； - 同步与系统操作：
sync、system、workspace命令。
配合--format json输出与--dry-run校验，CLI 可以安全地嵌入 shell 脚本与 CI 定时任务。
三、Breaking Change：serve 需要显式子命令
本版本明确标注了一条破坏性变更：内核启动服务现在必须显式使用serve子命令（issue #17866）。此前的内核二进制默认即启动 HTTP 服务，现在裸进程只作为 CLI 入口，长期驻留的服务由serve承载。
serve的完整参数定义在 kernel/cli/cmd/serve.go：
| 参数 | 默认值 | 说明 |
|---|---|---|
--wd | 自动探测 | SiYuan 工作目录（含appearance/、stage/的目录） |
--port | 0 | HTTP 服务端口 |
--readonly | false | 只读模式 |
--accessAuthCode | 空 | 访问授权码 |
--lang | 空 | 语言：ar/de/en/es/fr/he/hi/id/it/ja/ko/nl/pl/pt-BR/ru/sk/th/tr/uk/zh-CN/zh-TW |
--mode | prod | dev/prod |
--ssl | false | 启用 HTTPS 与 WSS（对应"Local HTTPS + HTTP/2 support"，issue #17822） |
--attach-ui | false | 将内核生命周期挂载到桌面 UI 进程（Electron 使用） |
--safe-mode | false | 安全模式启动（对应"Supports launching in Safe Mode on Desktop"，issue #17948） |
从serve的Run函数（kernel/cli/cmd/serve.go）可以看到长驻进程的单次命令都做了：启动 HTTP server、初始化三套数据库、启动数据同步、加载闪卡、启动 cron 定时任务、初始化插件管理器（plugin.InitManager()）、启动嵌入索引器（model.StartEmbeddingIndexer()）、监视资产/表情/主题变更。这也解释了为什么 CLI 单次命令路径与serve路径在root.go中要互相绕开对方的初始化逻辑。
四、内核插件系统：单一数据真相源
更新日志描述内核插件系统的核心价值是"插件常驻内核，保持所有窗口与实例一致，终结多窗口数据冲突"（对应 PR #17487）。源码实现位于 kernel/plugin/ 目录，其中 manager.go 定义了PluginManager：
- 单例与生命周期：
InitManager通过sync.Once保证全局唯一，并注册OnKernelPluginStart/Stop等模型层回调，由serve启动流程中的go plugin.InitManager()触发； - 热重载：内置
fsnotify.Watcher监视插件源文件变化，可触发热重载，无需重启内核； - 并发控制：每个插件名一把独立锁（
pluginsMu），允许不同插件并发启停、同一插件串行启停； - RPC 能力：
PluginInfo暴露插件名、状态与 RPC 方法列表，配合 kernel/plugin/rpc.go、websocket.go、worker.go 构成插件与内核之间的调用通道，另有sandbox.go提供沙箱能力； - 安全集成：kernel/plugin/api_secrets_vars.go 使插件也能消费下一节介绍的密钥与变量体系。
插件目录约定为工作空间内的data/plugins（见PluginManager.pluginsDir注释）。这一设计与"单窗口前端 + 常驻内核"的架构相配合：无论打开多少个前端窗口，插件状态与数据变更都收敛到内核这一处。
五、配置密钥与变量（Secrets and Variables）
"Supports configuring secrets and variables"（issue #17933）为智能体、MCP 服务等提供了统一的凭据注入机制，实现在 kernel/conf/secrets.go 与 kernel/conf/variables.go。
5.1 存储与加密
Secrets是全局密钥库，每条Secret由name与value组成。关键设计：
- 落盘加密：
Secrets.Encrypt()在AppConf.Save()序列化前对每个非空Value做util.AESEncrypt；启动加载时Decrypt()反向解密（注释中特别提到 AES 解密结果还需一次 hex 解码才得到明文，与 AI 配置中 API key 的处理模式一致）； - 运行时常驻明文：解析操作必须在
InitConf解密之后进行，因此密钥只在进程内存中短暂以明文存在。
5.2 引用语法与解析优先级
Resolve方法（kernel/conf/secrets.go）支持两类占位符：
- 显式语法
{{secrets.NAME}}：正则\{\{secrets\.([^}]+)\}\}匹配，仅替换已配置的名字，未配置时保留原文，便于调用方（尤其是 LLM）发现尚未配置的密钥； - Shell 风格的
$NAME与${NAME}：正则限定NAME以字母/下划线开头，避免误伤$100、正则表达式等无关文本；且仅当密钥库中存在同名条目时才替换。
统一入口ResolveSecretsVars先执行密钥解析再执行变量解析，由此形成"$NAME先查密钥库、再查变量库"的优先级顺序。其消费场景在源码注释中写明：智能体的http_request工具、MCP 服务 headers 等。
六、AI 知识库：Agent 与向量嵌入搜索
"SiYuan Agent 与向量嵌入搜索进入公测"是本版本向智能化迈出的标志。仓库中对应的实现分为两部分：
6.1 嵌入索引
kernel/model/embedding.go 定义了后台嵌入索引器的完整参数（文件头部的常量块）：
- 批量与并发：每批 10 个块，最大 8 并发；
- 内容长度门槛：短于 7 字符或长于 12000 字符的块被标记为忽略（
embeddingIgnoredByLen）； - 可配置排除：支持
.siyuan/embeddingignore（gitignore 语法）匹配排除的块，对应embeddingIgnoredByConf； - 失败退避：嵌入 API 不可用时按
30s << 失败次数指数退避（上限 30 分钟），单块连续失败 8 次视为永久失败不再调度；并用embeddingErrNotified原子标记避免并发 worker 重复弹窗。
CLI 侧通过model.PrepareEmbeddingSearch()让一次性命令同样可查询这些向量索引（见 2.2 节）。
6.2 SiYuan Agent
kernel/agent/ 目录实现了智能体核心：agent.go内置的系统提示词定义了块的领域概念（容器块/叶子块、标题层级是"后续兄弟节点"而非子节点、hPath 人类可读路径等），并约束了工具使用模式——关键词检索走search.fulltext、语义检索走search.semantic、内容增删改走block.*工具、日记走dailynote.*工具等；session.go管理会话，tools.go与compaction.go分别负责工具注册与上下文压缩，modelmeta.go与 models.json 描述可用模型。Agent 通过 kernel/mcp/client/ 集成 MCP 工具调用，并严格约束"不捏造块 ID，未找到就如实说明"。
七、界面与编辑体验增强（摘要）
本版本 Enhancement 清单非常长（完整条目见更新日志），按主题归纳如下：
- 界面布局：合并顶部标题栏与标签栏（#10749）、底部 Dock 改进（#8890）、Dock 面板最小宽度保存与拖拽保持（#17919）、Windows 下自定义下拉框样式（PR #17861）；
- 块与编辑器：超级块内拖拽调节块宽（#9521）、
Alt+Enter列表末尾插入改进（PR #16314）、块的递归折叠/展开（PR #17651）、嵌入块支持原地编辑（#17800）、块图标支持在块上/下方快速插入（#17900）、块图标提示简化（#17945）； - 数据库/属性视图：过滤器组合（#10550）、条目"创建副本"（#10850）、多选字段拖拽排序（#13468）、页脚字段模板化计算（#14394）、日期字段输入格式化（#13428）、视图性能改进（#17830）；
- 表格：合并单元格粘贴改进（#11888）、撤销编辑时保持横向滚动位置（#13829）、键盘导航不穿越合并单元格（#17587）、取消合并时
<tbody>内<th>转<td>（#17835）； - 移动端：多块选择（#13207）、手机/桌面界面切换（#13952）、平板与移动端拖拽（#17612、#17628）、跟随系统锁屏（#17625）、Android 内核后台进程改进（#17641）；
- 导出：Markdown 导出参数对话框（#17031）、桌面与移动端导出不再依赖浏览器下载（#17405、#17580）、嵌入块标题级别导出改进（#17629）、PDF 导出预览 UI 改进（#17687）；
- 安全与系统：不再向浏览器暴露工作空间绝对路径（#17410）、工作空间丢失后的启动提示改进（#14748）、数据同步 DNS 故障时自动刷新本地 DNS 缓存并重试（#17936）、macOS GPU 占用异常修复（#17087）。
另有两条值得注意的行为变更：废弃（Abolishment）——不再支持把列表块直接插入列表项块（#17890，Agent 系统提示词中也明确"嵌套列表须先在内层列表项下创建新的 list 块"，两者互相印证）；重构（Refactor）——升级 Electron 至 v42.5.0、highlight.js 升级至 v11.11.2、不再创建blocks_fts_case_insensitive表（#17849）。
八、面向开发者的 API 变更
本版本对插件开发者与 API 使用者有若干破坏性变更（完整清单见更新日志 Development 一节）：
- 部分内核 API 存在破坏性变更（#15727）；
/api/history/rollbackDocHistory移除notebook参数（#17411）； updateTransaction弃用，由updateTransactionElement替代（#17828）；lang取值改为符合 RFC 5646（#17855）——对照serve --lang的参数说明可见语言代码集合已按此规范整理；- 新增能力：
/api/query/sql支持只读模式（PR #17696）、新增内核 API/api/lute/md2html（PR #17697）与/api/history/createDocHistory（#17774）、LocalStorage 相关 API 改进（PR #17482）、addDock允许在任意生命周期阶段调用（#17506）、插件函数支持导出文件（#15484）。
文档方面，本版本补齐了三份关键资料，仓库中均可直接查阅：
- docs/SY-FORMAT.md：
.sy文件 JSON 结构规范，面向 AI 读写场景，明确了 HTTP API、MCP、CLI、直接读写.sy四种数据通道的分工与索引重建注意事项； - docs/WORKSPACE.md：工作空间磁盘布局；
- docs/API.md：API 文档，本版本新增了 Database 相关端点（#11130）。
九、小结
SiYuan v3.7.0 的更新日志表面是一份功能清单，实际勾勒出产品架构的三个转向：服务与命令分离（serve子命令化 + 全功能 CLI，脚本化与自动化首次成为官方一等公民）、前端与状态分离（内核插件常驻内核，多窗口共享单一数据真相源）、笔记与智能体融合（Agent 与向量嵌入搜索公测，密钥/变量体系为 LLM 调用提供安全凭据通道）。对运维与开发者而言，理解serve的完整参数、CLI 的全局 flag 与退出前索引落库行为、加密笔记本在 CLI 中的禁用边界，是正确使用本版本新能力的前提。
【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考