dsh-siyuan-notes

Readme

# SiYuan MCP 桥接：Codex 与 DeepSeek Harness

完整的当前操作说明（覆盖官方 29 个能力组）见[《思源官方 MCP 使用说明》](/Users/sunxifeng/siyuan-codex-bridge/docs/思源官方MCP使用说明.md)。

本项目采用 [MIT License](/Users/sunxifeng/siyuan-codex-bridge/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`](./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）：

```sh
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](./scripts/publish-npm.sh)：

```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`](/Users/sunxifeng/siyuan-codex-bridge/.env)，只填写 `SIYUAN_API_TOKEN` 的值。`SIYUAN_API_URL` 和 `SIYUAN_MCP_URL` 保持默认值。`.env` 必须是权限 600；Token 不应出现在 git、README、对话、审计日志、截图、命令行参数或普通配置中。

## 能力和操作级别

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

本地代理按每一次 `tools/call` 读取 [操作策略文件](/Users/sunxifeng/siyuan-codex-bridge/config/siyuan-policy.json)，支持三个级别：

- `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`](/Users/sunxifeng/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`。不需要每次手工开终端。

手工检查：

```sh
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`](/Users/sunxifeng/.codex/config.toml) 中将对应的 `enabled` 改为 `false`。这只关闭 Codex 连接，不会退出思源。

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

```sh
/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`](/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 会话。

## 审计和高风险能力

代理把允许或拒绝的操作写入 [`audit/operations.jsonl`](/Users/sunxifeng/siyuan-codex-bridge/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` 和测试，因为官方工具目录可能随版本变化。