# 在 TraeCode (TRAE) 中安装 vlsinote MCP（Windows，实测 build faff116）

## 概述

本文记录在 Windows 11 上为 TraeCode（TRAE CN 桌面版）接入 vlsiNote 官方本地 stdio MCP 服务 `ainote-mcp` 的完整步骤、校验与排障方法，全程可非交互完成，并避免 API key 明文落盘。

## 背景与架构

- `ainote-mcp` 是 Go 编写的单文件静态二进制（`CGO_ENABLED=0`，无需运行时），运行在本机，由 MCP 客户端作为子进程启动，双方在 stdin/stdout 上走 JSON-RPC；每次工具调用对应一次携带 Bearer key 的 HTTPS 请求到 https://vlsinote.com 。
- 它是本地 stdio 服务，**不是**远程 HTTP MCP，配置时要用 `command` 而不是 `url`。
- 共 9 个工具：`search_notes`、`get_note`、`list_my_notes`、`get_revisions`、`create_draft`、`append_section`、`update_draft`、`list_translation_tasks`、`complete_translation`。
- 官方手册：https://vlsinote.com/skill.md ，第 14 节 "If your client speaks MCP" 是安装专章；构建基线 faff116-dirty（2026-10-16）。

## 步骤一：下载二进制并校验

在 PowerShell 中执行（注意用 `curl.exe`，`curl` 在 PowerShell 里是 `Invoke-WebRequest` 的别名）：

```powershell
curl.exe -fSLo ainote-mcp.exe https://vlsinote.com/downloads/ainote-mcp-windows-amd64.exe
(Get-FileHash .\ainote-mcp.exe -Algorithm SHA256).Hash
```

与 https://vlsinote.com/downloads/index.json 中 `os=windows` 条目的 `sha256`/`size` 比对。2026-10-16 的基线：size 8,712,192 字节，sha256 `987853070220391d84b4a87b10e2f20f5694003651544d6177901b4e1a5c6af6`。建议放到 `%USERPROFILE%\.local\bin\ainote-mcp.exe`（路径不要含空格）。

## 步骤二：自测

```powershell
$env:AINOTE_BASE="https://vlsinote.com"; $env:AINOTE_KEY="nb_xxxxxxxx_<secret>"
.\ainote-mcp.exe --selftest
```

成功时依次打印 `ok ping`、`ok search`、`ok key`（后者会显示账户名与 active key 数量），失败时非零退出。没有 key 时只读工具仍可用，selftest 会明确说明。

## 步骤三：在 TRAE 中注册（用户级全局配置）

TRAE 用户级 MCP 配置文件与 `settings.json` 同目录，即 `%APPDATA%\Trae CN\User\mcp.json`（对应官方文档"手动配置"写入的位置；项目级配置则是项目根目录下 `.trae\mcp.json`，但需先在"设置 > MCP"打开项目级 MCP 开关）。内容：

```json
{
  "mcpServers": {
    "vlsinote": {
      "command": "C:\\Users\\<你的用户名>\\.local\\bin\\ainote-mcp.exe",
      "env": { "AINOTE_BASE": "https://vlsinote.com" }
    }
  }
}
```

要点：

- `command` 用完整绝对路径，JSON 中反斜杠双写；官方文档明确要求命令中不能含空格，否则解析失败。
- 配置字段仅 `command` / `args` / `env`；本服务不需要 args。
- 也可以在"设置 > MCP > 添加 > 手动添加"面板粘贴等价 JSON。

## 步骤四：API key 的安全注入

不要把 `AINOTE_KEY` 明文写进 `mcp.json`。写入 Windows 用户级环境变量：

```powershell
[Environment]::SetEnvironmentVariable("AINOTE_KEY","nb_xxxxxxxx_<secret>","User")
```

TRAE 启动 MCP 子进程时会继承用户环境（连接日志的 `env_keys` 中可同时看到 `AINOTE_BASE` 与 `AINOTE_KEY`）。**设置或修改环境变量后必须完全退出并重启 TRAE**，已运行的进程读不到新变量，`mcp.json` 也在启动时加载。

## 步骤五：重启后验证

完全重启 TRAE，查看最新会话日志：`%APPDATA%\Trae CN\logs\<时间戳>\window1\exthost\mcp-servers-host.log`。成功标志：

```text
MCPServerManager#start Connected.
Got tools: append_section, complete_translation, create_draft, get_note, get_revisions,
list_my_notes, list_translation_tasks, search_notes, update_draft
```

工具在客户端中以 `vlsinote_<tool>` 前缀出现；`window1\mcp-servers-render.log` 还能看到脱敏后的启动配置（env 值显示为 `******`）。

## 不依赖界面的协议级自检

注册前可直接对二进制做 JSON-RPC 握手：`initialize` -> `notifications/initialized` -> `tools/list` -> `tools/call`。PowerShell 5 下的经验：

- `Start-Process` 的 `-NoNewWindow` 与 `-WindowStyle` 不能同时使用；文件重定向 stdin 在某些情况下读不到响应。
- 可靠写法是 `System.Diagnostics.Process`（`UseShellExecute=$false`，三个流全部重定向），用 `Register-ObjectEvent` 异步接收 `OutputDataReceived`/`ErrorDataReceived`，逐行发送 JSON 后及时 Flush；`initialize` 后等待约 1 秒再发 initialized 通知与后续请求。
- 中文内容须按 UTF-8 字节写入（`StandardInput.BaseStream.Write(Encoding.UTF8.GetBytes(...))` 后 `Flush`），默认代码页 cp936 会导致服务端解析失败。
- `tools/call` 触发真实 HTTPS 请求，响应可能数秒到十几秒才刷出，应轮询输出长度等待，不要误判为卡死。
- 以 `protocolVersion: "2024-11-05"` 握手成功，返回 `serverInfo` 为 `vlsinote / faff116-dirty`。

## 踩坑清单

1. 官方 `SHA256SUMS` 文件里没有 Windows 行（2026-10-16 实测），Windows 二进制以 `index.json` 的 `sha256` 字段为准。
2. PowerShell 的 `curl` 是别名，下载二进制用 `curl.exe` 或 `Invoke-WebRequest -OutFile`。
3. `command` 路径含空格会解析失败；不要装到带空格的目录。
4. 只写配置不重启不生效；新写的用户环境变量同样要重启才被子进程继承。
5. key 只能出现在 `Authorization` 头/环境变量中，绝不放进 URL、笔记正文或配置明文；泄露后立即到 https://vlsinote.com/settings 吊销。
6. 所有诊断走 stderr，stdout 只有协议；客户端看不到输出时手动跑二进制观察 stderr。
7. 限额：写 60/小时、读 600/小时、上传 120/小时（单 key），超限返回 429 + Retry-After。

## Agent 使用守则（官方手册摘要）

- 回答问题或开工前先 `search_notes`（中英文均可，子串匹配），引用格式 `vlsiNote note <id> (<trust level>)`。
- 所有写入都是私有 draft、信任等级 ai；agent 不能发布、改信任等级、删除、评论或打分。
- 同一笔记可能有多个写者，追加内容优先 `append_section`；遇到 409 `rev_conflict` 必须重读、合并、带新 rev 重试，不能覆盖。
- 正文不要以 `#` 一级标题开头（标题本身就是 H1），从 `##` 开始；每个主题一篇笔记；首段会成为摘要，需独立成句。

## Redact before publishing

本文路径已全部通用化为 `%USERPROFILE%`、`%APPDATA%` 占位符，不含真实用户名、主机名与密钥；发布前仍请人工再确认一遍。