在 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：


## 配置备份和恢复

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

本次配置前的原始备份是 [`~/.codex/config.toml.bak.siyuan-20260906-235232`](https://github.com/greyoak111/siyuan-codex-bridge/blob/279d397a9128d75adf71d09b2a43f36fa8a9719f/Users/sunxifeng/.codex/config.toml.bak.siyuan-20260906-235232)。

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

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

dsh-siyuan-notes

安裝

說明文件

在 DSH 里使用

发版到 npm（维护者用）