📘 Khy-OS 文档站 🧭 新手先读：核心概念

# KHY Trae Bridge

# KHY Trae Bridge#

将 Trae IDE 的 `icube.marscode` 登录态桥接到 KHY OS CLI，实现一次登录、双端共享。

## 架构#

    Trae Sandbox                              KHY CLI
    ┌──────────────────┐                ┌─────────────────────────┐
    │ icube.marscode   │                │ readMarsCodeAuthProvider │
    │ AuthProvider     │──getSession──▶│ Token()                  │
    │ (内存持有 token) │                │                          │
    └──────────────────┘                └───────────┬─────────────┘
             │                                      │
        khy-trae-bridge                             │
        扩展写入                                    读取
             │                                      │
             ▼                                      ▼
       <globalStorage>/khy-trae-bridge/auth.json
       { accessToken, host, userId, username, region, ts }

## 目录结构#

    extensions/khy-trae-bridge/
    ├── package.json          — 扩展清单 (onStartupFinished 激活)
    ├── extension.js          — 核心逻辑 (~120 行)
    ├── .vscodeignore         — 打包过滤
    ├── README.md             — 本文档
    └── khy-trae-bridge-0.1.0.vsix  — 预构建安装包

## 安装（Windows）#

### 方式一：从预构建 VSIX 安装（推荐）#

仓库已包含 `khy-trae-bridge-0.1.0.vsix`，直接安装即可：

1. 打开 Trae
2. 按 `Ctrl+Shift+X` 打开扩展面板
3. 点击面板右上角 `···` → 从 VSIX 安装...（Install from VSIX）
4. 选择文件：`extensions\khy-trae-bridge\khy-trae-bridge-0.1.0.vsix`
5. 等待安装完成 → 重启 Trae

或使用命令行：

    # Trae CLI（如果已配置 PATH）
    trae --install-extension extensions\khy-trae-bridge\khy-trae-bridge-0.1.0.vsix

    # 也可能是
    code --install-extension extensions\khy-trae-bridge\khy-trae-bridge-0.1.0.vsix

### 方式二：从源码打包后安装#

    cd extensions\khy-trae-bridge

    # 安装打包工具
    npm install --save-dev @vscode/vsce

    # 打包
    npx @vscode/vsce package --allow-missing-repository

    # 安装
    trae --install-extension khy-trae-bridge-0.1.0.vsix

## 使用方法#

### 自动模式（零配置）#

安装完成后 无需任何手动操作：

1. 启动 Trae — 扩展自动激活（`onStartupFinished`）
2. 扩展调用 `vscode.authentication.getSession('icube.marscode', [])` 获取登录态
3. Token 写入 `<globalStorage>/khy-trae-bridge/auth.json`
4. KHY CLI 下次 `detect()` 自动拾取 → 状态从 `encrypted` → `verified`

### 手动同步#

如果需要立即刷新登录态：

- 命令面板：`Ctrl+Shift+P` → 输入 `KHY: 同步 Trae 登录态`
- 状态栏：点击右下角 `🔑 KHY Bridge` 图标

### 查看日志#

`Ctrl+Shift+U` 打开输出面板 → 下拉选择 KHY Trae Bridge 通道

## 刷新策略#

触发方式 | 时机 | 说明
--- | --- | ---
启动同步 | Trae 启动后立即 | `onStartupFinished`
定时刷新 | 每 10 分钟 | `setInterval`
事件驱动 | 登录/登出时 | `onDidChangeSessions`
手动命令 | 用户触发 | 命令面板或状态栏

## auth.json 格式#

    {
      "accessToken": "eyJhbGciOi...",
      "userId": "user_xxxx",
      "username": "example",
      "host": "grow-normal.trae.ai",
      "region": "cn",
      "ts": 1748150400000
    }

未登录时：

    {
      "accessToken": null,
      "status": "no_session",
      "ts": 1748150400000
    }

## 区域检测#

扩展自动根据 Trae 版本和系统语言判断区域：

条件 | 区域 | API 主机
--- | --- | ---
appName 含 "Trae CN" 或 "国内" | `cn` | `grow-normal.trae.ai`
系统语言 `zh-*` | `cn` | `grow-normal.trae.ai`
其他（国际版默认） | `va` | `growva-normal.trae.ai`

完整区域映射：

区域 | 主机
--- | ---
`cn` | `grow-normal.trae.ai`
`sg` | `growsg-normal.trae.ai`
`va` | `growva-normal.trae.ai`
`usttp` | `grow-normal.traeapi.us`

## 故障排查#

### 扩展安装后没反应#

1. 确认 Trae 版本 ≥ 1.80（`engines.vscode: ^1.80.0`）
2. 查看输出面板日志是否有错误
3. 确认 Trae 内已登录 — 如果未登录，auth.json 会写入 `"status": "no_session"`

### KHY CLI 没有拾取到 token#

1. 检查 auth.json 是否存在：

    # globalStorage 路径通常在
    # Windows: %APPDATA%\Trae\User\globalStorage\khy-trae-bridge\auth.json
    dir "%APPDATA%\Trae\User\globalStorage\khy-trae-bridge\auth.json"

1. 确认 `accessToken` 字段不为 `null`
2. 确认 `ts` 是最近的时间戳（不超过 24 小时）

### 手动验证 token 是否有效#

    # 在 KHY CLI 中执行
    khy ai status
    # 应显示 adapter: trae, state: verified

## 卸载#

### 从 Trae 卸载#

`Ctrl+Shift+X` → 搜索 `KHY Trae Bridge` → 点击齿轮图标 → 卸载

### 清理残留文件#

    # 删除桥接数据
    del "%APPDATA%\Trae\User\globalStorage\khy-trae-bridge\auth.json"
    rmdir "%APPDATA%\Trae\User\globalStorage\khy-trae-bridge"

## 开发者信息#

- 激活方式：`onStartupFinished`（不阻塞 Trae 启动）
- 依赖：零运行时依赖，仅使用 VS Code API + Node.js 内置模块
- 体积：打包后 ~4 KB
- 兼容性：VS Code / Trae / 任何兼容 VS Code 扩展 API 的 IDE