Obsidian Agent Bridge

Obsidian Agent Bridge 将 ChatGPT / Codex 的知识工作流安全地连接到本机 Obsidian。V1.0 通过 OpenAI Secure MCP Tunnel 调用本地 MCP Bridge，在受控路径、并发校验和审计约束下读取或维护 Vault。

ChatGPT / Codex Plugin
        ↓
OpenAI Secure MCP Tunnel
        ↓
tunnel-client managed runtime
        ↓
src/server.ts
        ↓
Obsidian Vault

V1 Skills

V1.0 提供五个职责分离的 Skill：

• Knowledge Retrieval：搜索、读取、比较和综合已有知识。

• Note Maintenance：维护一篇笔记或小范围、聚焦的知识项。

• Daily Knowledge Ingest：把一天中的异构新信息增量整理进已有知识体系。

• Method Training Coach：在主动训练中控制提示强度，保留用户的核心推理机会。

• Method Evidence Review：复核方法证据、归因、迁移和等级准备度，但不自动升级。

Review / Direct 是持久化的行为偏好，不会绕过路径策略、唯一精确匹配、SHA-256 并发保护、安全落盘或审计。

Skill templates and local instances

• skill-templates/ 是可公开、可分发的通用默认模板，应进入版本控制。

• skills/ 是当前用户的本地运行实例，由 .codex-plugin/plugin.json 通过 "skills": "./skills/" 加载。

• npm run init:skills 会把缺失的模板复制到 skills/；已存在的 Skill 目录会跳过，不覆盖用户修改。

• skills/ 已由 .gitignore 排除，因此用户对本地 Skill 的个性化不会进入 Git。

模板不假定固定个人方法编号、项目阶段或 Vault taxonomy。用户可以在本地 skills/ 中按自己的知识结构继续定制。

Related MCP server: obsidian-local-mcp

Trust Boundaries

• Knowledge runtime domain：Obsidian Vault。

• Development source domain：the local project directory selected by the operator。

• Agent 不能通过 Obsidian MCP 修改本项目源码。

• Vault 写入仅限已配置的内容区；系统治理区、隐藏目录、Vault 外路径及 symlink/junction 逃逸均受保护。

• V1 不提供通用 write_file、整篇无条件覆盖、delete、rename 或 move。

Installation

当前 Windows 部署假设：

• 先根据 .env.example 配置当前 PowerShell 环境或等效的用户级环境变量；Secret 不写入仓库。

• Node.js 20 或更高版本。

• OBSIDIAN_VAULT_ROOT 必须指向实际 Vault；缺失时 MCP server 会安全拒绝启动。

• TUNNEL_CLIENT_PATH 指向本机 tunnel-client；也可以让 tunnel-client.exe 位于 PATH。

• 将 .app.example.json 复制为本地 .app.json，再填写部署者注册的 MCP App ID；.app.json 不进入 Git。

• 项目示例路径为 C:\path\to\obsidian-mcp-bridge，实际位置由部署者决定。

• Node.js 和项目依赖已安装；缺失时在项目目录运行 npm install。

• tunnel-client v0.0.11 示例路径为 C:\path\to\tunnel-client.exe，通过 TUNNEL_CLIENT_PATH 配置。

• source Profile 为 %APPDATA%\tunnel-client\obsidian-local.yaml，其中 Key 必须引用 env:CONTROL_PLANE_API_KEY，不能写入明文。

• OBSIDIAN_PROXY_URL 是可选配置；未设置时 tunnel-client 操作不使用 HTTP 代理。需要代理时可显式设置，例如 http://127.0.0.1:7897。

首次配置按以下顺序执行：

cd C:\path\to\obsidian-mcp-bridge
npm ci
npm run init:skills
Copy-Item .app.example.json .app.json
$env:OBSIDIAN_VAULT_ROOT = 'C:\path\to\your-vault'
$env:TUNNEL_CLIENT_PATH = 'C:\path\to\tunnel-client.exe'
npx tsc --noEmit
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-set-credential.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-start.ps1 -PreflightOnly
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-install-autostart.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-start.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-status.ps1

tunnel-set-credential.ps1 在隐藏输入中接收 Runtime control-plane key，完成真实只读控制面认证后，才以 CurrentUser DPAPI 保存。永远不要把 Runtime API Key 发到 ChatGPT / Codex 对话中。

公开发行版的典型启动准备流程为：

git clone
→ npm ci
→ npm run init:skills
→ 配置 .env / OBSIDIAN_VAULT_ROOT
→ 配置本地 App / Tunnel
→ 启动 Agent

重新执行 npm run init:skills 是安全且幂等的：它只补充完全缺失的 Skill 目录，不会用模板覆盖本地实例。

Daily Operations

所有命令均从项目根目录运行。

状态：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-status.ps1

启动或幂等确认已启动：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-start.ps1

停止 managed runtime 及其 MCP 子进程：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-stop.ps1

安装当前用户登录自动启动：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-install-autostart.ps1

移除自动启动（不会停止正在运行的 runtime，也不会删除 Credential、Profile 或日志）：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-remove-autostart.ps1

初始化或更新 Credential：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-set-credential.ps1

Expected Healthy State

Tunnel: RUNNING
MCP: HEALTHY
Mode: managed/runtime
RuntimeAlias: obsidian-agent
Instances: 1
McpProcesses: 1
Credential: CONFIGURED
Autostart: INSTALLED

TaskState: Ready 不表示 runtime 已停止。Task Action 可以在启动或确认 runtime 后退出，managed runtime 会继续在后台运行。当前状态始终以 tunnel-status.ps1 为准。

Tests

自动化测试默认复制 test/fixtures/vault/ 到临时目录，并通过 OBSIDIAN_VAULT_ROOT 启动隔离的测试 server；测试不会访问个人 Vault，也不会修改仓库内 fixture 原件。

npx tsc --noEmit
npm run test:runtime-reliability
npm run test:phase2b
npm run test:phase2c1

Troubleshooting

ChatGPT 无法访问 Obsidian

第一步始终运行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-status.ps1

• Tunnel: STOPPED：运行 tunnel-start.ps1。

• Tunnel: RUNNING 但 MCP: UNREACHABLE：检查 data/runtime/ 和 runtime log，确认 src/server.ts target 是否正常。

• Credential: MISSING：运行 tunnel-set-credential.ps1。

• 已配置的 OBSIDIAN_PROXY_URL 不可达：先恢复对应代理；启动预检会返回 exit 7，不会形成快速重启循环。未配置代理时不会执行代理连通性检查。

• Autostart: NOT_INSTALLED：运行 tunnel-install-autostart.ps1。

8080 被占用

健康的 manual tunnel 使用 127.0.0.1:8080 本身不是异常，不要因为端口占用就随意 kill 进程。Credential doctor 使用临时 loopback health port；脚本还会核对 socket owner、tunnel-client PID 和 health 状态。

Hash Conflict

Hash conflict 是正常的乐观并发保护，表示 preview 后文件已变化。重新执行：

read → preview → 用户确认当前 Diff → apply

不要强行覆盖，也不要复用旧 hash 或旧确认。

Plugin Skill 更新后未生效

重新加载或安装本地 Plugin，然后新开一个 Codex/ChatGPT 任务。已有会话可能缓存旧 Skill metadata。

日志中存在历史 ERROR

运维日志会保留历史失败。判断当前状态时应同时查看错误时间戳、最新 start-succeeded 和 tunnel-status.ps1，不能仅因搜索到 ERROR 就认定当前故障。

Credential Recovery

CurrentUser DPAPI 文件位于：

%LOCALAPPDATA%\ObsidianMcpBridge\secrets\control-plane-api-key.dpapi

• DPAPI 与创建它的 Windows CurrentUser SID 绑定。

• 不要复制到其他 Windows 用户或把它当作跨机器备份。

• 不要提交 Git，不要手动编辑 blob。

• 换电脑、换用户或 Key 被 revoke 后，重新运行 tunnel-set-credential.ps1，在本机隐藏输入中提供新的 Runtime control-plane key。

• tunnels get 的只读认证支持 Runtime control-plane key；日常运行不要求高权限 Admin Key。

失败的 Credential 不会保存为最终 DPAPI 文件。

Autostart Recovery

计划任务名称为 Obsidian Agent Tunnel，使用当前用户、Interactive/Limited 上下文，登录后延迟 30 秒启动，MultipleInstances 为 IgnoreNew，失败后每 5 分钟重试、最多 6 次。

如果 Task 损坏或配置漂移：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-remove-autostart.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\tunnel-install-autostart.ps1

安装脚本会接受完全匹配的已有 Task 并返回 ALREADY INSTALLED；遇到不同定义的同名 Task 会拒绝覆盖。不要手工随意修改 Task 后期待安装脚本无条件覆盖。

Data and Logs

• data/audit.jsonl：Vault 写操作审计，每行一个独立 JSON；记录操作、路径、hash 和结果，不记录完整正文或 Secret。

• data/settings.json：持久化 review / direct Write Mode。

• data/runtime/startup.log：启动、停止和运维状态事件。

• data/runtime/tunnel.log：doctor、runtime connect/stop 等 tunnel-client 诊断摘要。

• %USERPROFILE%\.local\state\tunnel-client\logs\obsidian-agent.log：managed runtime 原生日志。

项目运维日志在达到约 2 MiB 时轮换为同目录 .1，只保留当前文件和一个轮换文件。日志输出会脱敏，但仍应按本地运维数据保护，不要公开上传。

Secret Safety

• 不在对话、README、命令参数、Task 参数或 Git 中记录 API Key。

• Credential 仅在本机隐藏输入中进入进程内存，并以 CurrentUser DPAPI 持久化。

• Task 与 DPAPI 必须运行在同一个 Windows SID 下，不能改为 SYSTEM。

• Profile 只保存 env:CONTROL_PLANE_API_KEY 引用。

• 怀疑 Key 泄漏时，在控制面 revoke，然后在本机重新执行 Credential 初始化。

Backup

V1 建议备份：

1. Obsidian Vault。

2. 工程源码与文档。

3. %APPDATA%\tunnel-client\obsidian-local.yaml 及必要的 managed Profile/配置说明。

4. 部署路径、代理地址、Task 名称和恢复步骤说明。

不要把 DPAPI blob 当作跨机器恢复方案；新环境应重新建立 Credential。V1 不新增自动云同步或复杂自动备份系统。

V1.0 Scope

包含：

• Knowledge Retrieval

• Focused Note Maintenance

• Daily Knowledge Ingest

• Method Training Coach

• Method Evidence Review

• Review / Direct

• SHA-256 patch 乐观并发保护

• 安全临时文件落盘与 audit

• writable/protected/forbidden path policy

• managed runtime

• Windows 当前用户 Autostart

• CurrentUser DPAPI Credential

不包含：

• 自动 L1-L4 等级升级

• delete / rename / move

• 自动后台聊天摄取

• 定时 Daily Ingest

• Vault 外源码自修改

• 全库自动整理

• Router Skill

• Vector DB、Embedding 或 Graph Index

Known Limitations

• Task 真实注册、手动触发、STOPPED 后 Task-only 恢复均已通过；实际 Windows logout/login/reboot 触发尚未实测。

• 当前部署路径、tunnel-client 路径以及可选代理地址属于本机部署约定，迁移环境时需要按需调整运维配置。

• DPAPI 不能跨用户或跨机器迁移。

• V1 的写权限保持受控，不支持任意目录或破坏性文件管理。

• 当前关系检索以显式链接和词法检索为主，不提供向量语义召回。

V1.1 Roadmap — Hybrid Knowledge Retrieval

V1.1 的已确认候选方向是 Hybrid Knowledge Retrieval / Relation Discovery：

Explicit Graph / Backlinks
        +
Lexical Search
        +
Semantic Vector Search
        +
Metadata Filtering
        ↓
Candidate Pool
        ↓
Relation Judgment

原则：semantic similarity 不等于 explicit relation。Vector Search 用于发现潜在未知关系，Explicit Graph 用于沉淀已确认的稳定关系。第一阶段只读，关系发现稳定后再考虑写入双链。

对应 Obsidian 设计记录：03_项目实践/2026-08-10_Obsidian Agent Bridge_V1.1_Hybrid Retrieval.md。

本阶段不实现 Vector DB、Embedding 或 Graph Index。

Release Status

文档产品版本为 Obsidian Agent V1.0。详见 RELEASE_NOTES.md。当前目录不是 Git repository，因此没有执行 git status、git diff、Git tag 或 release commit；V1.0 目前是逻辑版本冻结。