# Obsidian Agent Bridge

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

```text
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/` 中按自己的知识结构继续定制。

## 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`。

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

```powershell
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 对话中。**

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

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

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

## Daily Operations

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

状态：

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

启动或幂等确认已启动：

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

停止 managed runtime 及其 MCP 子进程：

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

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

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

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

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

初始化或更新 Credential：

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

## Expected Healthy State

```text
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 原件。

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

## Troubleshooting

### ChatGPT 无法访问 Obsidian

第一步始终运行：

```powershell
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 后文件已变化。重新执行：

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

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

### Plugin Skill 更新后未生效

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

### 日志中存在历史 ERROR

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

## Credential Recovery

CurrentUser DPAPI 文件位于：

```text
%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
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：

```text
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](./RELEASE_NOTES.md)。当前目录不是 Git repository，因此没有执行 `git status`、`git diff`、Git tag 或 release commit；V1.0 目前是逻辑版本冻结。