Augment-BYOK（请尽快 PR 合并，避免跟不上本仓库）

单一 VSIX：把 Augment 的 8 个 LLM 数据面端点按路由转到 BYOK（支持 Streaming + tool use），其它端点保持官方行为；支持运行时一键回滚（无需 Rust/外部服务）。

默认 relay：https://acemcp.heroman.wtf/relay/。使用官方 /get-models 合并与官方上下文注入前，请先到 https://acemcp.heroman.wtf/login 自行注册并填写自己的 API Token；本项目不再内置或随机分配 key。

安装（推荐：Releases）

• GitHub Releases（tag：rolling）下载 augment.vscode-augment.*-byok.*.vsix
• VS Code → Extensions → ... → Install from VSIX... → Reload Window

快速配置（面板）

1. 运行 BYOK: Open Config Panel
2. 至少配置 1 个 providers[] → Save（Base URL 会按 type 自动填充默认值）
3. 运行 BYOK: Enable（runtimeEnabled=true 才会接管 8 个端点）
4. 可选：在 Model Picker 选择 byok:<providerId>:<modelId>（由 /get-models 注入）

配置存储：VS Code extension globalState（含 Key/Token；不参与 Sync）。字段与约束见本文“配置系统”与“routing.rules（端点路由规则）”；示例见 config.example.json。

可选：面板支持 Self Test（一键验证 models/chat/chat-stream + 工具链路）。

常用命令： - BYOK: Enable / BYOK: Disable (Rollback) - BYOK: Reload Config - BYOK: Import Config / BYOK: Export Config - BYOK: Clear History Summary Cache

Provider 支持（4 类）

• openai_compatible：POST {baseUrl}/chat/completions（SSE）
• openai_responses：POST {baseUrl}/responses（SSE，支持 incomplete_details.reason→stop_reason）
• anthropic：POST {baseUrl}/messages（SSE）
• gemini_ai_studio：.../v1beta/models/<model>:streamGenerateContent?alt=sse

协议适配细节（工具/stop_reason/用量/兜底/常见网关差异）见本文“Provider 支持矩阵”。

8 个端点（会被 BYOK shim 接管）

• callApi（4）：/get-models、/chat、/completion、/chat-input-completion
• callApiStream（4）：/chat-stream、/prompt-enhancer、/next-edit-stream、/generate-commit-message-stream

当前上游 augment/vscode-augment@0.871.0 已无 /edit、/generate-conversation-title、/next_edit_loc、/instruction-stream 与 /smart-paste-stream，因此默认 BYOK 覆盖矩阵同步收敛为 8 个端点。

完整端点范围（48/8）见本文“端点覆盖（48 / 8）与路由策略”。

排障（高频）

• 401/403：检查 apiKey/headers；不要把 Bearer 前缀重复写入（apiKey 会自动加 Bearer，headers.authorization 则应完整填写）。
• 404/HTML：baseUrl 很可能少了 /v1（OpenAI/Anthropic 兼容端点通常要求）。
• 流式无输出：确认上游支持 text/event-stream；建议直接在面板跑 Self Test 定位（models / chat / chat-stream）。
• Anthropic stream 422 system: invalid type: string：多见于“Anthropic 兼容代理”实现差异；已内置 blocks 兼容兜底重试（仍失败时请确认 baseUrl 指向 /messages 且代理支持 SSE）。
• BYOK 未生效：确认已 Save（热更新只影响后续请求）且 BYOK: Enable（runtimeEnabled=true）。

本地构建

前置：Node.js 20+、Python 运行时、可访问 Marketplace（优先 python3；Windows 可用 py -3；否则回退 python）

• 快速检查（不依赖上游缓存）：npm run check:fast
• 完整检查（需要缓存上游 VSIX）：npm run upstream:analyze（一次）→ npm run check
• 构建：npm run build:vsix（产物：dist/augment.vscode-augment.<upstreamVersion>-byok.<buildId>.vsix）

全量修改功能（对上游 VSIX 的“全量改动面”清单）

说明：这里的“修改”指本仓库在构建 *.byok.vsix 时对上游 Augment VSIX 的补丁/替换点 + BYOK 运行时代码新增能力。
状态标记：[x] 已实现；[-] 部分实现/依赖条件（条目内注明）；[ ] 未实现（明确不做 / 未来可能做）。

0) 总体目标与边界（Scope / Non-goals）

• [x] 单一 VSIX：所有能力都打包进一个 *.vsix，无需 Rust/外部代理服务
• [x] 最小破坏面：只接管 8 个 LLM 数据面端点（其余端点维持 official 或按需 disabled）
• [x] 可回滚：运行时一键回滚（runtimeEnabled=false 即回到官方链路）
• [x] 可审计：锁定上游版本与产物 sha256，并产出覆盖矩阵/端点全集报告
• [x] fail-fast：上游升级导致 patch needle / 合约不满足时，构建直接失败（避免 silent break）
• [x] 不依赖 augment.advanced.* settings：构建期移除贡献点 + 运行时不读取/不写入
• [x] 配置来源单一：只用 VS Code extension globalState（含 Key/Token，不参与 Sync）
• [x] 运行时开关单独存储并参与 Sync：仅 augment-byok.runtimeEnabled.v1 加入 Sync，方便“跨设备一键回滚”
• [ ] 非目标：复刻控制面/权限/Secrets/遥测/Remote Agents（保持官方实现；必要时可用 disabled 兜底）
• [ ] 非目标：autoAuth（构建期 guard 明确禁止；命中直接 fail-fast）
• [ ] 非目标：引入 env/yaml/SecretStorage 作为配置源（避免多源漂移与审计难度）

1) 构建与产物（Build / Artifacts）

• [x] 构建单一真相：tools/build/build-vsix.js
• [x] 上游 VSIX 下载/解包：下载到 .cache/upstream/*.vsix，解包到 .cache/work/*
• [x] 支持跳过下载复用缓存：build-vsix --skip-download
• [x] Overlay 运行时代码与 UI：把 payload/extension/out/byok/* 覆盖到上游 extension/out/byok/*
• [x] 上游 VSIX 下载/解包能力复用：tools/lib/upstream-vsix.js（build / analyze / contracts 共用）
• [x] BYOK patch 编排复用：tools/lib/byok-workflow.js（避免构建脚本与合约脚本漂移）
• [x] 产物输出：dist/augment.vscode-augment.<upstreamVersion>-byok.<buildId>.vsix
• [x] 产物锁文件（上游+产物 sha）：upstream.lock.json / dist/upstream.lock.json
• [x] 端点覆盖报告：dist/endpoint-coverage.report.md（LLM 端点覆盖矩阵）
• [x] 上游端点全集分析：.cache/reports/upstream-analysis.json（由 npm run upstream:analyze 生成）
• [x] Release 资产命名去重：dist/upstream.lock.json 会复制为 dist.upstream.lock.json（仅用于 Release assets）

2) 构建期补丁面（Patch Surface：严格受控 & 可审计）

2.1 入口注入（bootstrap）

• [x] 注入方式：在上游 extension/out/extension.js 中注入 BYOK bootstrap
• [x] 注入脚本：tools/patch/patch-extension-entry.js
• [x] 注入一致性审计：contracts 检查 bootstrap marker，锁文件只记录上游与产物 sha
• [x] 设计原则：不再依赖外部 augment-interceptor payload，不做机器指纹/会话伪造类逻辑

2.2 Webview 资产外科式补丁（上游 bundle 层）

• [x] History Summary 节点瘦身：避免 Editable History 等路径对巨型节点 stringify/clone 导致内存爆炸
• [x] patch 脚本：tools/patch/patch-webview-history-summary-node.js
• [x] patch 目标：所有匹配 history_summary_node/HISTORY_SUMMARY/history_end 的 common-webviews/assets/*.js
• [x] 当前默认启用：historyonly 实测正常；构建期固定执行，不再暴露额外环境变量
• [x] contracts 会逐个匹配 asset 校验 marker 与 TEXT/text_node 改写，避免多 bundle 场景漏补丁
• [x] 已移除 Tool Use fallback：tooluseonly 与 toolusefix 都会导致主面板空白，相关 patch/开关/测试已从主线删除
• [x] Webview 资产 cache-bust：对带 __augment_byok_ marker 的 patched JS 改名并重写 common-webviews/* 引用，避免 VS Code/WebView 复用旧缓存

2.3 注入 BYOK 运行时入口（bootstrap）

• [x] 注入 bootstrap：在上游 extension/out/extension.js 中注入 ./byok/runtime/bootstrap
• [x] 注入脚本：tools/patch/patch-extension-entry.js
• [x] bootstrap 能力：初始化配置管理、运行时开关、shim 挂载、热更新监听

2.4 暴露上游少量内部对象（仅 Self Test 用）

• [x] 目的：Self Test 覆盖“真实工具执行”，需要访问上游 toolsModel / store 等内部对象
• [x] 注入脚本：tools/patch/patch-expose-upstream.js
• [x] 约束：仅暴露必要引用到 globalThis，不改变官方业务逻辑

2.5 Official overrides（官方连接参数来源切换）

• [x] 目标：把官方 completionURL/apiToken 来源从 VS Code settings 改为 globalState
• [x] 注入脚本：tools/patch/patch-official-overrides.js
• [x] 行为：支持私有租户 / 官方上下文注入（token 可选；缺 token 时注入会 skip 并输出一次明确降级提示，不影响 BYOK 主链路）

2.6 模型选择器补丁（Model Picker：BYOK-only）

• [x] 目标：runtimeEnabled=true 时，Model Picker 只展示 byok:*（避免“选了官方但 BYOK 实际忽略”的错觉）
• [x] 注入脚本：tools/patch/patch-model-picker-byok-only.js
• [x] 行为：仅在 BYOK 开启时接管；关闭即回到官方模型合并逻辑

2.7 禁用上游 chatHistory 硬裁剪（仅 BYOK 开启时）

• [x] 目标：避免客户端按轮数/体积先截断，导致 historySummary/工具结果变成“孤儿上下文”
• [x] 注入脚本：tools/patch/patch-disable-chat-history-truncation.js
• [-] 触发条件：仅 runtimeEnabled=true 时生效（关闭 BYOK 不改变官方行为）

2.8 callApi / callApiStream shim（端点级接管）

• [x] 注入点：在上游 callApi / callApiStream 方法开头注入一次性拦截
• [x] 注入脚本：tools/patch/patch-callapi-shim.js
• [x] 约定：maybeHandleCallApi*() 返回 undefined → 回落到官方原生逻辑（软回滚关键）
• [x] 副作用边界：注入层只透传 arguments[5]/[10]，不读取上游 config token、不 stringify completionURL、不原地修改 body
• [x] 路由模式：byok | official | disabled

2.9 package.json 补丁（命令/设置贡献点最小化）

• [x] 注入 BYOK 命令：BYOK: Enable/Disable/Reload/Open Panel/Import/Export/Clear Cache
• [x] 移除 augment.advanced.* settings 贡献点：避免误读/误写上游高级设置
• [x] 注入脚本：tools/patch/patch-package-json-commands.js

2.10 构建期 guard + contracts（fail-fast）

• [x] autoAuth=0 guard：构建产物中命中 autoAuth 字符串直接失败
• [x] guard 脚本：tools/patch/guard-no-autoauth.js
• [x] node --check：对关键注入后的 JS 做语法检查（避免产物不可加载）
• [x] 检查脚本：tools/check/node-check-js.js
• [x] BYOK 合约检查：确保 marker/运行时文件/协议枚举/模型注册 feature_flags 满足最小契约
• [x] 合约入口：tools/check/byok-contracts/main.js
• [x] 子检查：tools/check/byok-contracts/check-callapi-shim.js
• [x] 子检查：tools/check/byok-contracts/check-protocol-enums.js
• [x] 子检查：tools/check/byok-contracts/check-augment-protocol-shapes.js

3) 运行时开关与回滚（Runtime Toggle / Rollback）

• [x] BYOK 运行时开关存储：augment-byok.runtimeEnabled.v1
• [x] 配置存储：augment-byok.config.v1（含 Key/Token；不参与 Sync）
• [x] History Summary 缓存存储：augment-byok.historySummaryCache.v1（不参与 Sync）
• [x] 软回滚语义：runtimeEnabled=false 时 maybeHandleCallApi*() 直接返回 undefined/空 stream → 官方逻辑接管
• [x] 软回滚副作用边界：禁用时不加载 BYOK 配置、不清 historySummary cache、不捕获 upstream call host，注入层也不读取上游 token/config 或修改 body
• [x] 一键回滚命令：BYOK: Disable (Rollback)（不清空配置，仅切换运行时）
• [x] 一键开启命令：BYOK: Enable
• [x] 热更新：面板 Save 后对“后续请求”生效（不需要 Reload Window）
• [x] 严格失败：路由为 BYOK 且官方拼接/端点组装失败时直接抛错（避免 silent mismatch）

4) 配置系统（globalState v1：字段/限制/兼容）

4.1 配置入口与编辑体验

• [x] Webview 面板：BYOK: Open Config Panel
• [x] 面板保活：retainContextWhenHidden=true（减少频繁重建导致的状态丢失）
• [x] 仅允许加载本地资源：localResourceRoots=[out/byok/ui/config-panel]
• [x] 面板支持 Reload：丢弃未保存修改，回到 last-good config
• [x] 面板状态提示：保存/导入/导出/自检结果会推送到 UI status 区

4.2 Import / Export（JSON）

• [x] BYOK: Export Config（可选脱敏/包含 secrets）
• [x] Export：include secrets（用于备份/迁移）
• [x] Export：redact secrets（敏感字段替换为 <redacted>，用于分享模板）
• [x] BYOK: Import Config（可选 merge/replace）
• [x] Import：Merge (preserve existing secrets)（导入但保留当前已存密钥：当导入字段为空或 <redacted>）
• [x] Import：Replace (overwrite everything)（完全覆盖，密钥也会被覆盖/清空）

4.3 字段规范与兼容策略

• [x] 配置版本：version=1
• [x] 字段命名严格 camelCase（v1 不再兼容旧别名：如 base_url / history_summary 等）
• [x] 配置归一化：endpoint key 归一化为 pathname（例如 "/chat-stream?x=1" → "/chat-stream"）
• [x] 防原型污染：拒绝/过滤 __proto__ / prototype / constructor 等不安全 key（配置与 UI 消息均做 hasOwnProperty 防护）
• [x] BYOK 内部字段隔离：requestDefaults 中的 BYOK 内部 key 会在发往上游前剥离（避免污染上游请求）

4.4 Official 连接（用于：/get-models 合并；也可切私有租户）

• [x] official.completionUrl：默认 https://acemcp.heroman.wtf/relay/（可切私有租户）
• [x] official.apiToken：默认空；到 https://acemcp.heroman.wtf/login 自行注册并填写自己的 API Token；清空则会跳过官方 /get-models 与上下文注入并输出一次降级提示
• [x] 官方上下文注入入口：agents/codebase-retrieval / search-external-sources / context-canvas/list

4.5 providers[]（BYOK 上游列表）

• [x] 至少 1 个 provider 才能 mode=byok 生效
• [x] provider 基本字段：id / type / baseUrl / models[] / defaultModel / apiKey? / headers? / requestDefaults? / underlyingModelMapping?
• [x] underlyingModelMapping.titleGeneration/summary：仅在 silent=true 且命中“标题生成/对话总结”内部请求时覆盖当前 provider 的模型选择
• [x] providerId 语义：model id 形如 byok:<providerId>:<modelId>
• [x] provider types（生成单一真相，见 tools/gen/sync-provider-types.js）：
• [x] openai_compatible
• [x] openai_responses
• [x] anthropic
• [x] gemini_ai_studio

4.6 routing.rules（端点路由规则）

• [x] 规则结构：routing.rules[endpoint]={ mode, providerId?, model? }
• [x] mode=byok：走 BYOK（仅对 8 个 LLM 数据面端点提供语义实现）
• [x] mode=official：强制走官方（即使 runtimeEnabled=true 也不接管）
• [x] mode=disabled：直接 no-op（callApi 返回 {}，callApiStream 返回空 stream）
• [-] 规则合并：用户 rules 与默认 rules 合并；不建议手填未知端点（上游升级可能改变集合）

4.7 输出上限（max tokens 自动推断）

• [x] 当 providers[].requestDefaults 未配置任何 max tokens 字段时：BYOK 会自动注入 max_output_tokens
• [x] 推断策略：按 model 名称推断上下文窗口大小 + 估算 prompt 体积，尽可能给出“不会轻易截断”的输出预算（并预留安全余量）
• [x] 兼容不同 provider：以 max_output_tokens 为 canonical，provider 映射层会转换到各自字段（例如 Gemini 的 generationConfig.maxOutputTokens）
• [x] 若触发 token-limit 重试：会强制覆盖所有 max tokens 别名 key（含 generationConfig.maxOutputTokens），避免不同映射优先级绕过
• [x] 上游拒绝（token limit/context length）时：自动缩小 max tokens 并重试（流式仅在未输出任何 chunk 时允许重试，避免重复输出）

4.8 historySummary（滚动摘要：上下文压缩）

• [x] historySummary.enabled：默认 false（显式开启才生效）
• [-] historySummary.providerId/model：可空（仅控制“摘要生成模型”；为空时 fallback 到当前 provider/model）
• [x] 触发体积：history + message + prefix/selected_code/suffix/diff（UTF-8 bytes）
• [x] 触发阈值：triggerOnHistorySizeChars（默认 800000）
• [x] 触发策略：triggerStrategy=auto|ratio|chars（推荐 auto）
• [x] 比例阈值：triggerOnContextRatio / targetContextRatio（默认约 0.70 / 0.55，触发阈值自动钳制在 0.60~0.80）
• [x] 上下文窗口估算：contextWindowTokensDefault / contextWindowTokensOverrides（override：最长子串、大小写不敏感）
• [x] 双模型解耦：触发窗口按当前对话模型判定；summary provider/model 仅用于“如何生成摘要”
• [x] 常见 overrides：gpt-5.3-codex=400000、gpt-5.2=400000、claude-4.6-opus=1000000、gemini-3-pro=1000000、kimi-k2=128000
• [x] Tail 保留：historyTailSizeCharsToExclude（按 UTF-8 bytes 估算）+ minTailExchanges
• [x] 切分一致性：触发后不再被“仅 history 阈值”二次否决（避免触发但不注入）
• [x] 摘要生成上限：maxTokens / timeoutSeconds / maxSummarizationInputChars（按 UTF-8 bytes 估算）
• [x] rolling summary 缓存：rollingSummary=true + cacheTtlMs（对话维度缓存，减少重复 summarization）
• [x] 刷新策略：仅“当前请求已含 summary node”才跳过；chat_history 含旧 summary 仍允许刷新
• [x] 提供默认 supervisor prompt 模板：summaryNodeRequestMessageTemplate + abridgedHistoryParams
• [x] 兜底：summary 生成失败/超时/未配置时，仍会注入 fallback summary 强制压缩（避免请求过大导致直接失败）
• [x] 兜底：end_part_full 中的 tool_result / tool_use input 会中间截断（保留尾部引用 id），防止单个工具输出撑爆上下文

5) 端点覆盖（48 / 8）与路由策略

5.1 端点全集与覆盖矩阵

• [x] 上游端点全集：npm run upstream:analyze → .cache/reports/upstream-analysis.json
• [x] LLM 覆盖矩阵：npm run report:coverage → dist/endpoint-coverage.report.md
• [x] 端点说明：本文“端点覆盖（48 / 8）与路由策略”

5.2 8 个 LLM 数据面端点（BYOK 语义实现）

• [x] callApi（4）：/get-models、/chat、/completion、/chat-input-completion
• [x] callApiStream（4）：/chat-stream、/prompt-enhancer、/next-edit-stream、/generate-commit-message-stream
• [x] 单一真相维护：tools/report/llm-endpoints-spec.js
• [x] 自动生成同步：npm run gen:llm-endpoints（更新 UI + 默认 routing rules + official delegation）
• [x] shim 二次约束：未实现端点即使携带 byok:* model override，也保持 official，不进入 BYOK 执行路径
• [x] provider 可执行性约束：除 /get-models 外，目标 provider 未配置 baseUrl + 可用 auth/headers + 已知 type 时，路由保持 official

5.3 其余 40 个端点（默认 official / 按需 disabled）

• [ ] Remote Agents（4）：不接管（依赖控制面/权限/状态机），默认 official
• [ ] Agents / Tools（7）：不接管（远程工具路由），默认 official
• [ ] 文件/Blob/上下文同步（9）：不接管（依赖官方存储/鉴权），默认 official
• [ ] Cloud Agents / Experts（2）：不接管（依赖官方控制面），默认 official
• [ ] 账号/订阅/权限（5）：不接管，默认 official
• [ ] 反馈/遥测/调试（11）：不接管（部分默认 disabled，少量保持 official）
• [ ] 通知（2）：不接管（默认 official）

6) callApi（非流式）实现细目（4）

6.1 /get-models（模型注册 + feature_flags 注入）

• [x] 从 BYOK 配置构建 byok models：仅对“可执行配置”（已配置 baseUrl + 可用 auth/headers + 已知 provider.type）注入 providers[].models → byok:<providerId>:<modelId>
• [x] 默认模型选择：优先第一个“可执行” provider / 其 defaultModel；无可执行 provider 时 default_model 为空且 models=[]
• [-] 尝试调用官方 /get-models 获取基础 flags（用于兼容上游 model registry）
• [x] scrub 官方 feature_flags 中的 model registry 相关字段（避免冲突/双注册）
• [x] 注入 model registry feature_flags（确保上游 Model Picker/featu