greyoak111/siyuan-codex-bridge

完整的当前操作说明（覆盖官方 29 个能力组）见《思源官方 MCP 使用说明》。

本项目采用 MIT License。

这个本地桥接把 Codex Desktop、Codex CLI 和 IDE 连接到思源笔记内置的官方 MCP。STDIO 代理只把 MCP 请求转发到 http://127.0.0.1:6806/mcp，并在请求头中补充 API Token；它不解析或改写 .sy 文件，也不直接操作 siyuan.db。

同一个仓库还是一个 DSH（DeepSeek Harness）插件：package.json 里的 dsh.bundle 指向 cordis.patch.yml，把同样的官方工具注册成 mcp__siyuan__*，并附带一个 siyuan 使用技能。两侧互不影响——Codex 走 bin/（Python 代理），DSH 走 bridge/（Node 代理），各自的 token、策略与审计彼此独立。

在 DSH 里使用

安装（二选一）：

• DSH 桌面端 → 插件市场搜索 siyuan-codex-bridge（分类 Memory）；
• 命令行（GitHub 源）：dsh plugin --profile web add github:greyoak111/siyuan-codex-bridge
• 命令行（npm 源，预构建、免 allowBuilds 批准）：dsh plugin --profile web add dsh-siyuan-notes

宿主启动不会连带打开思源。 桥接只通过网络跟 127.0.0.1:6806 说话，握手和工具目录都在本地应答， 所以打开编辑器、或客户端来问“有哪些工具”，都不会启动任何桌面应用。 思源没开时，桥接仍会本地应答 MCP 握手、并提供上一次见到的工具目录，所以工具不会在会话里凭空消失； 此时调用会明确返回"SiYuan is not reachable"，你打开思源后下一次调用即恢复（会话失效会自动重新握手）。

可以让"真正调用"顺手把思源拉起来（默认关闭，需要你显式打开）：在 ~/.config/dsh-siyuan/config.json 里加 {"launchOnCall": true}（或设 SIYUAN_LAUNCH_ON_CALL=1）。打开后只有一次真正的 tools/call 会去启动思源—— 握手、列目录、宿主启动都不会，这正是"agent 伸手去拿笔记应用"和"我一开编辑器笔记应用自己弹出来了"的区别。 这个开关和操作级别一样是每次调用现读的：改完 config.json，下一次调用即生效，不用重启桥接或 harness。 启动命令默认是 /Applications/SiYuan.app/Contents/MacOS/SiYuan（可用 SIYUAN_APP 换 App 路径，或用 launchCommand / SIYUAN_LAUNCH_COMMAND 完全自定义），等待上限默认 60 秒（launchTimeoutMs / SIYUAN_LAUNCH_TIMEOUT_MS）。 拉起时会把环境里会弄坏 Mac 应用的键摘掉后交给它：__CFBundleIdentifier（agent shell 会导出它， Electron 应用继承后会误判自己的 bundle，约 80 毫秒后静默退出、退出码 0、日志空白）、ELECTRON_* （尤其 ELECTRON_RUN_AS_NODE 会让 App 变成一个 node 进程）、NODE_*、以及本桥接自己的 DSH_*/SIYUAN_*； 其余（HOME、PATH、区域设置等）原样保留，所以你自定义的启动脚本仍然可用。

桥接还会追加一个自己的 ai 工具，把思源内置 AI（用你在思源里配的那把 API key）接到 MCP 上—— 思源自己的 MCP 端点只发布笔记工具，AI 与它的 agent 回路原本对客户端不可见：

ai 的 action	做什么	档位
capabilities	列出 agent 能力（32 项，带 localWrite 标注）	readonly
chat	普通问答（msg，可选 model）	readonly
action	按块 ID 执行已配置的编辑器动作（ids + name）	authoring
editor	编辑器式对话（input，可选 ids/history）	authoring
agent	启动一次内置 agent 回合（流式聚合；可暂停等审批）	full
status / confirm / answer / permission	读取回合、批准工具调用、回答反问、设会话权限	full

agent 是交互式的：它会在需要审批或提问时停下。桥接保持 SSE 流不关（关掉会取消这一回合）， 先返回当前状态与待办，之后用 confirm/answer 继续、用 status 读结果。

工具目录的优先级是：实时目录 → 本机缓存 → 包内快照。也就是说，即便思源从未连上过（全新安装、还没打开过思源），插件也自带一份目录快照，工具不会显示成空；思源一旦应答即换成实时目录。快照可用 node bridge/mcp-stdio.mjs --dump-catalog > bridge/tools-snapshot.json 重新生成。

装完即用，不需要手填 token。 桥接按 环境变量 SIYUAN_API_TOKEN → ~/.config/dsh-siyuan/config.json → 思源自己的工作区配置（~/.config/siyuan/workspace.json 列出工作区，读其 <工作区>/conf/conf.json 的 api.token）的顺序解析；多数情况下最后一条就能找到，因为 token 本来就在思源自己的设置里。思源没启动时先打开思源桌面端。

操作级别（桥接在每次 tools/call 上重新校验，改完下一次调用即生效）：

级别	允许的动作
readonly	搜索与读取：文档、块、大纲、反链、属性、笔记本列表、系统和工作区信息
authoring（默认）	以上 + 建文档、块 insert/append/prepend/update、属性 set、日记 create/append/prepend
full	官方全部 action：删除、移动、重命名、复制、笔记本管理、文件、SQL、导入导出、历史回滚、仓库、同步、HTTP、网页抓取

思源处于限流状态时（HTTP 429），桥接会把 Retry-After 一并写进错误文案，便于判断等多久。

改级别：编辑 ~/.config/dsh-siyuan/config.json（例如 {"profile": "readonly"}），或设环境变量 SIYUAN_MCP_PROFILE（环境变量优先，避免用户配置里一个多余的键推翻部署时的显式声明）。桥接在每次 tools/call 上重新读取该级别，所以下一次调用即生效，不需要重启桥接或 harness。诊断（不打印 token）：

node node_modules/.bin/dsh-siyuan-bridge --doctor

状态目录 ~/.config/dsh-siyuan/：可选的 config.json，以及 audit.jsonl 审计（只记时间/级别/工具/action/决策，权限 600，不含参数与笔记正文）。插件目录本身不被写入任何东西。

发版到 npm（维护者用）

账号的 2FA 是 passkey（指纹），没有一次性密码可填，所以非交互的 npm publish 会停在 EOTP。 用 scripts/publish-npm.sh：

# 先在 package.json 里改版本号，提交并打 tag
bash scripts/publish-npm.sh            # 已发布的版本会被拦下，不会重发
bash scripts/publish-npm.sh --dry-run  # 只看会发布什么

• ~/.npmrc 里的 token 还没过期时，一条命令直接发完，无需任何交互；
• 过期时脚本会向 npm 申请一个浏览器批准链接、打印并自动打开，你用指纹批准一次， 它自己取回 token、写回 ~/.npmrc 并继续发布。

当前 npm 包：dsh-siyuan-notes（dsh-siyuan 是别人的包，且我们的 bundle patch 靠目录名解析自身文件， 所以那个名字既发不了、也不能共用）。

DSH plugin (English)

The same repository is a DeepSeek Harness plugin: dsh.bundle in package.json points at cordis.patch.yml, which connects the harness to the local SiYuan desktop app's own MCP endpoint, registers its official note tools as mcp__siyuan__<tool>, and adds a siyuan skill describing the read-first, write-on-request etiquette. The bridge is bridge/mcp-stdio.mjs (Node, no dependencies); it resolves the SiYuan API token from the environment, from ~/.config/dsh-siyuan/config.json, or from SiYuan's own workspace settings, so a normal install needs no configuration. One of three operation profiles — readonly, authoring (default) or full — is enforced on every tools/call, and node node_modules/.bin/dsh-siyuan-bridge --doctor reports the endpoint, the token's origin and the active profile without printing the token.

Opening the harness never starts the app, and neither does a client asking which tools exist: the handshake and the catalog are answered locally. With launchOnCall switched on ({"launchOnCall": true} in ~/.config/dsh-siyuan/config.json, or SIYUAN_LAUNCH_ON_CALL=1), a real tools/call brings SiYuan up when it is closed and waits for it. The app is started through /bin/sh with the environment cleaned of the keys that break a Mac app — __CFBundleIdentifier, ELECTRON_*, NODE_* — while the rest of the user's environment is kept, so a launcher of their own still works.

唯一需要手工填写的值

编辑 .env，只填写 SIYUAN_API_TOKEN 的值。SIYUAN_API_URL 和 SIYUAN_MCP_URL 保持默认值。.env 必须是权限 600；Token 不应出现在 git、README、对话、审计日志、截图、命令行参数或普通配置中。

能力和操作级别

思源官方 MCP 的完整工具目录会透传给 Codex。具体版本和工具数量以每次本机端点探测为准；官方端点通常返回按 action 选择读取、写入、管理、导入导出、同步或网络动作的聚合工具。

本地代理按每一次 tools/call 读取 操作策略文件，支持三个级别：

• readonly：搜索、读取文档和块、文档树、大纲、反链、属性、笔记本列表、系统和工作区信息。
• authoring：在 readonly 基础上允许创建文档、插入/追加/前置/更新块、设置属性和创建或追加日记；删除、移动、重命名、复制、文件、数据库管理、SQL、网络、导入导出、同步和仓库操作仍拒绝。
• full：官方 MCP 当前公布的全部工具和 action 都可以转发。Codex 配置仍使用 default_tools_approval_mode = "writes"；代理会保留这个批准设置，并在每次调用前执行策略检查。SiYuan 3.8.3 把多个 action 聚合在同一个 MCP 工具里且没有 action 级 annotations，因此不能把“每个 action 必然弹出单独提示”当作安全边界，代理策略才是硬边界。

当前策略文件默认是 full，因为用户已经选择开放完整官方能力。策略文件只包含级别，不包含 Token，权限为 600。即使处于 full，普通创作请求也只应调用读取动作；需要修改或外部操作时先说明目标，再让 Codex 执行批准流程。

在插件页管理级别

个人插件源目录是 ~/plugins/siyuan-notes。插件页会显示这些技能和一个轻量控制工具：

• $siyuan：创作前检索思源并引用相关文档或块。
• $siyuan-readonly：切换并保持只读级别。
• $siyuan-authoring：切换到受控创作级别，允许内容写入。
• $siyuan-full：切换到完整官方工具级别。
• $siyuan-policy：查看当前级别和可用级别。

siyuan-control.show_siyuan_controls 会请求显示可折叠的范围面板；它会在宿主支持时请求 PiP（通常由宿主放在右下），不支持时回退为对话内卡片或文本范围选项。部分 Codex Desktop 构建目前不会挂载 MCP Apps HTML 资源，此时直接在对话中说“切换思源为只读/创作/全功能”即可完成同一操作。面板只负责选择本地权限范围，不写入思源工作日志。

也可以直接在对话中说“查看思源操作级别”“切换思源为只读”“切换思源为创作”“切换思源为全功能”。这些技能调用插件自带的 siyuan-control 控制 MCP；代理本身仍会在每个 MCP 请求上重新检查策略，所以技能提示不是唯一安全边界。

插件规范的设置页能力取决于宿主，因此权限选择由技能和控制 MCP 共同完成；面板不可用时仍可用对话命令完成同一流程，不改变官方 MCP 或笔记数据格式。打开并选定范围后，相关项目对话会按当前范围先检索思源文档/块；如果任务本身涉及维护或同步相关笔记，代理会主动提出窄范围调整，再按写入审批执行。纯无关问题不会强制查询。

启动、重启和关闭

插件提供 ensure_siyuan、start_siyuan、status_siyuan。创作或检索开始前会检查 127.0.0.1:6806，思源未运行时通过 macOS 后台方式启动 /Applications/SiYuan.app。不需要每次手工开终端。

手工检查：

cd ~/siyuan-codex-bridge
./scripts/check-siyuan.sh
./scripts/test-mcp.sh
codex mcp list

check-siyuan.sh 每次都会请求 /api/system/version，动态显示思源实际返回的版本，并校验响应中存在可用的非空版本值；它不锁定某个最低或目标版本，因此升级思源不会因为版本号变化而被误报为失败。升级后仍应重新运行 tools/list 和 test-mcp.sh，确认官方工具目录与桥接行为没有变化。

切换操作级别后策略会在下一次官方 MCP 调用生效。若 Codex 客户端缓存了旧的工具目录，重启当前 Codex/IDE 会话或新建会话即可；无需重启思源，也不需要把 Token 再填一遍。

如果 macOS 暂时拦截当前 ChatGPT.app 内置的 codex 可执行文件，退出并重新打开 ChatGPT，让官方 Sparkle 更新完成后再运行上面的命令；这与思源桥接或 Token 无关。

在 Codex 中关闭连接：把 siyuan MCP 服务器设为 disabled，或在 ~/.codex/config.toml 中将对应的 enabled 改为 false。这只关闭 Codex 连接，不会退出思源。

如果确实要退出思源，可以在终端运行：

/usr/bin/osascript -e 'tell application "SiYuan" to quit'

插件默认只负责启动和检查，不会在任务结束时强制关闭思源。

配置备份和恢复

每次修改全局 Codex 配置前先创建带时间戳的备份，例如 ~/.codex/config.toml.bak.siyuan-YYYYmmdd-HHMMSS。恢复时先退出 Codex，再选择实际存在的备份文件：

本次配置前的原始备份是 ~/.codex/config.toml.bak.siyuan-20260906-235232。

cp ~/.codex/config.toml.bak.siyuan-20260906-235232 ~/.codex/config.toml
chmod 600 ~/.codex/config.toml

恢复后重新启动 Codex Desktop、CLI 或 IDE 会话。

审计和高风险能力

代理把允许或拒绝的操作写入 audit/operations.jsonl。这是最小的本地安全审计，不是写入思源的工作日志；每行只记录时间、级别、工具、action 和决策，不记录参数、笔记正文、响应、请求头或 Token；日志权限为 600。

官方 MCP 中的文件读写、导入导出、历史回滚、仓库检出、同步、任意 HTTP、网页访问、解压和 SQL 都属于高影响能力。full 会让它们可用；执行前仍应明确目标并让客户端按 writes 配置处理，同时由本地代理执行 action 级策略检查。不要把官方 HTTP 端点直接添加到另一个会自动放行写操作的客户端，否则会绕过本地策略代理。

按当前选择，full 下没有工具组被禁用；切换到 readonly 或 authoring 后，上述高影响动作以及删除、重命名、复制、批量移动和系统管理动作会由代理拒绝。这个边界按每次 tools/call 检查，而不是只依赖插件提示词。

思源端口保持绑定在 127.0.0.1，不会暴露到局域网或公网。升级 SiYuan 后请重新运行 tools/list 和测试，因为官方工具目录可能随版本变化。