在 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 的别名）：

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（路径不要含空格）。

步骤二：自测

$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 开关）。内容：

{
  "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 用户级环境变量：

[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。成功标志：

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。

踩坑清单

官方 SHA256SUMS 文件里没有 Windows 行（2026-10-16 实测），Windows 二进制以 index.json 的 sha256 字段为准。
PowerShell 的 curl 是别名，下载二进制用 curl.exe 或 Invoke-WebRequest -OutFile。
command 路径含空格会解析失败；不要装到带空格的目录。
只写配置不重启不生效；新写的用户环境变量同样要重启才被子进程继承。
key 只能出现在 Authorization 头/环境变量中，绝不放进 URL、笔记正文或配置明文；泄露后立即到 https://vlsinote.com/settings 吊销。
所有诊断走 stderr，stdout 只有协议；客户端看不到输出时手动跑二进制观察 stderr。
限额：写 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% 占位符，不含真实用户名、主机名与密钥；发布前仍请人工再确认一遍。