配置
VS Code 设置
在 VS Code 设置中配置 Cortex（搜索 “Cortex”）。设置位于 cortex.* 命名空间——不是项目的 config.json。
| 设置 | 默认值 | 说明 |
|---|---|---|
cortex.opencodeBinary | "opencode" | OpenCode CLI 二进制路径 |
cortex.opencodePort | 4096 | opencode serve 的首选端口；若被其他工作区占用，Cortex 会使用下一个空闲端口 |
cortex.agent | "build" | 默认 OpenCode 主代理（如 build、plan） |
cortex.providerID | "opencode" | 已弃用的离线镜像 — 默认模型为 opencode.json 的 `model` |
cortex.modelID | "big-pickle" | 已弃用的离线镜像 — 请优先使用 OpenCode 配置 / 聊天选择器 |
cortex.modelMode | "auto" | 模型选择：auto / turbo / manual |
cortex.routing.useAllConnectedProviders | false | 为 true 时，Auto/Turbo 可使用任何已连接提供商；为 false 时仅使用 OpenCode 默认模型所属提供商 |
cortex.models.optimizeFor | "balance" | Auto 路由成本与质量权衡：cost / balance / intelligence |
cortex.models.zenBillingEnabled | false | 在选择器中解锁付费 Zen 模型（默认关闭 — 避免意外计费） |
cortex.models.byokEnabled | false | 解锁 BYOK 提供商模型（OpenAI、Anthropic 等） |
cortex.context.topK | 8 | 每个提示注入的本地上下文块数量 |
cortex.context.maxChars | 16000 | 每个提示检索上下文的最大字符数 |
cortex.context.embedWeight | 0.45 | 排序上下文时嵌入相似度的权重（0–1），其余为词法匹配 |
cortex.context.embeddings | "hash" | 检索模式：hash = 性能（快速、离线）；minilm = 质量（语义 MiniLM）。质量模式会将原生 runtime 下载一次到 ~/.cache/cortex-minilm（不进 VSIX）；就绪前锁定发送（首次索引通常 ≤约30秒）；向量存在 .cortex/index；之后启动只预热模型；文件改动仅重新嵌入变更文件。引导/聊天会显示硬件适配提示（质量约增加150MB；紧张机器上限制嵌入并发） |
cortex.context.chunkMode | "symbols" | 索引拆分模式：symbols（LSP）或 lines |
cortex.context.include | [] | 可选 include glob（相对工作区）。空 = 所有可索引文件 |
cortex.context.exclude | [] | 在 gitignore 之外的额外 exclude glob |
cortex.context.extensionPriority | {".ts":1,".tsx":1,".js":0.8,".jsx":0.8,".py":0.9} | 按扩展名的检索排序分数倍率（越高越优先） |
cortex.autocomplete.enabled | true | 通过快速无工具 OpenCode 代理提供幽灵补全 |
cortex.autocomplete.debounceMs | 350 | 停止输入后请求自动补全建议前的防抖（毫秒） |
cortex.locale | "en" | Cortex UI 语言（独立于 VS Code 显示语言） |
cortex.chat.pinEditorTab | true | 固定 Cortex 聊天标签并保持在其所在组的第一位 |
cortex.chat.maxOpenTabs | 5 | 启动时保持并恢复的聊天标签上限（0 = 不限） |
cortex.chat.maxHistorySessions | 100 | 历史中列出的聊天上限（最新优先；0 = 全部） |
cortex.ui.showHeaderVersion | true | 在 Cortex 标题旁显示淡化版本号（演示时可关闭） |
cortex.ui.showReasoningSummaries | true | 在聊天时间线中显示 thinking / reasoning 摘要块 |
cortex.ui.shellToolPartsExpanded | true | 默认展开时间线中的 shell/bash 输出块 |
cortex.ui.editToolPartsExpanded | true | 默认展开时间线中的 edit/write/patch 卡片 |
cortex.permissions.autoAccept | false | 自动以一次性 allow 接受 OpenCode 权限提示 |
cortex.appearance.uiFont | "" | 聊天 UI 的可选 CSS 字体族；空则使用 VS Code UI 字体 |
cortex.appearance.codeFont | "" | 聊天中等宽/代码的可选 CSS 字体族；空则使用编辑器字体 |
cortex.notifications.agent | false | 代理完成一轮时显示 VS Code 通知 |
cortex.notifications.permissions | false | 出现权限提示时显示 VS Code 通知 |
cortex.notifications.errors | true | 聊天出错时显示 VS Code 通知 |
cortex.sounds.agent | "none" | 代理完成一轮时的声音（none 或 Web Audio 预设） |
cortex.sounds.permissions | "none" | 出现权限提示时的声音 |
cortex.sounds.errors | "none" | 聊天出错时的声音 |
cortex.theme.id | "follow" | 聊天配色主题：follow（OpenCode tui.json）、cortex，或 OpenCode Desktop 主题 id（GitHub 目录 + 缓存） |
cortex.theme.mode | "system" | OpenCode 主题的亮/暗变体；system 跟随 VS Code 颜色主题 |
cortex.theme.remoteRef | "dev" | 用于列出官方 Desktop 主题的 anomalyco/opencode Git ref |
cortex.policy.t0MaxChars | 2000 | Tier T0 最大字符数（不可变安全 / neverDo / hooks） |
cortex.policy.t1MaxChars | 12000 | Tier T1 最大字符数（always-apply 规则、AGENTS.md、user rules） |
cortex.policy.t2MaxChars | 8000 | Tier T2 最大字符数（glob 规则、skills、requestable 目录） |
cortex.policy.includeCursorRules | true | 将 .cursor/rules 载入 Policy Brain |
cortex.policy.includeCortexRules | true | 将 .cortex/rules 载入 Policy Brain |
cortex.skills.autoInvoke | true | 在 turn 匹配时自动注入 SKILL.md 正文 |
cortex.skills.topK | 2 | 启用 auto-invoke 时每轮完整注入的 skills 上限 |
cortex.hooks.enabled | true | 运行 .cortex/hooks.json 与内置 changelog gate |
cortex.hooks.strict | false | 为 true 时，失败的 prePrompt hook 会拒绝该 turn |
键盘快捷键
VS Code 快捷键（非 OpenCode Desktop）。可在键盘快捷方式中自定义：
| 快捷键 | 操作 |
|---|---|
Ctrl/Cmd+Alt+C | 打开聊天（右侧编辑器面板） |
Ctrl+Alt+I / Cmd+Alt+Shift+I | Inline Edit |
Ctrl/Cmd+Alt+\ | 触发幽灵补全 |
Ctrl/Cmd+Alt+T | 将终端选区发送到聊天 |
命令面板
所有 Cortex 命令都在 VS Code 命令面板（Ctrl/Cmd+Shift+P）中。搜索 “Cortex”：
| 命令 | 说明 |
|---|---|
Cortex: Open Session | 打开聊天面板（右侧编辑器组） |
Cortex: New Session | 开始新的聊天会话 |
Cortex: Stop Generation | 中止当前代理回合 |
Cortex: Send Terminal Selection to Session | 将终端选中文本发送到聊天 |
Cortex: Reindex Workspace | 重建本地代码库索引 |
Cortex: Trigger Inline Completion | 立即请求幽灵文本补全 |
Cortex: Inline Edit (Ctrl+Alt+I) | 对当前选区/文件进行内联编辑 |
Cortex: Connect | 打开 Providers 以连接 OpenCode 账户 |
Cortex: Connect / Models | 打开 Models（默认模型、可见性、收藏） |
Cortex: Remember preference | 将偏好保存到 Policy Brain 记忆 |
Cortex: Open rules / memory | 打开规则与记忆文件 |
Cortex: Edit user rules | 编辑用户规则 |
Cortex: Show Policy Inspector | 检查本回合活跃的 Policy Brain 层级 |
Cortex: Run Diagnostics | 运行连通性与设置诊断 |
Cortex: Show Log | 打开 Cortex 输出通道 |
Cortex: Dump last retrieval | 写出最近一次上下文检索转储以便排查 |
Cortex: Report Issue / Feedback | 打开反馈 / Issue 报告流程 |
通过 OpenCode 的模型
Cortex 将 OpenCode 用作代理提供商。你从 OpenCode 订阅（免费 Zen、付费 Zen 或 OpenCode Go）中可用的模型里选择。OpenCode 账单在 Cortex 之外管理，与 Cortex 许可无关。
- Servers — 在 Settings → Servers 中管理本地 OpenCode 连接与远程 HTTP OpenCode 服务器（健康检查、添加/编辑/删除、默认/活动）— 与 OpenCode Desktop 相同思路。
- Providers — 打开 Providers（Cortex: Connect）连接 Zen、Go、Anthropic、Copilot、自定义 OpenAI 兼容端点等 — 与 OpenCode Desktop 同类的目录。认证仍使用 OpenCode 本地 auth.json。
- OpenCode Go — 在 opencode.ai 订阅 Go 后，Cortex 会在启动 / Recheck 时自动检测并切换（复用 API key）。也可在 Models 中启用 OpenCode Go。
- 付费 Zen / BYOK — 免费 Zen 保持解锁。付费 Zen 与 BYOK 需在 Models 中显式解锁（或 cortex.models.zenBillingEnabled / cortex.models.byokEnabled）。
- 模型选择器 — 从已连接的 OpenCode 提供商中选择任意模型。Auto/Turbo 遵循 cortex.models.optimizeFor（cost / balance / intelligence）。若目录提供，可选择变体（Default / Low / Medium / High）。
- 主题 — 聊天主题遵循 OpenCode Desktop：GitHub 官方目录（缓存）、~/.config/opencode/themes 自定义主题，或 follow tui.json。配置 cortex.theme.id / mode / remoteRef，或在 Models 中选择。
- 通知与声音 — 代理完成、出现权限提示或出错时的可选 VS Code 通知与 Web Audio 预设（cortex.notifications.* / cortex.sounds.*）。permissions.autoAccept 对应 Desktop 的 auto-accept。
- Composer + — composer 的 + 菜单（OpenCode Desktop 对等）：图片与文件（Ctrl/Cmd+U）、Commands（/）、Context（@）、Shell（!）。附件按当前模型的输入模态过滤。
- 默认值 — 默认模型位于 opencode.json（`model`）。cortex.modelMode（Auto/Turbo/Manual）在 VS Code；可见性/收藏在 Models
- 未打开文件夹 — 可在空窗口中聊天；Cortex 将用户主目录用作 OpenCode cwd。打开项目文件夹以进行代码索引与项目计划。
密钥保存在 OpenCode 本地存储（~/.local/share/opencode/auth.json；Windows：%USERPROFILE%\.local\share\opencode\auth.json）。Cortex 读写该文件 — 不重复保存凭证。OpenCode 也可能使用 ~/.config/opencode/opencode.json 管理代理权限；那与 Cortex 的 VS Code 设置分开。
上下文来源
Cortex 自动从以下来源收集上下文：
- Policy Brain (T0–T2) — 分层规则：user rules、AGENTS.md、.cursor/rules、.cortex/rules、skills、neverDo — 也可通过命令面板：Remember preference、Open rules / memory、Edit user rules、Show Policy Inspector
- 活动文件 — 你正在编辑的文件（每轮自动附加）
- 选择 — 高亮文本
- 词法搜索 — 项目中的关键词匹配
- Embeddings — 默认性能(hash)；聊天工具栏可切换质量(MiniLM) — 本地模型就绪后才解锁发送（加载期间不会静默回退性能）
- Memory — .cortex/memory.json 中的 facts、偏好与 neverDo
- @ mentions — 聊天中的文件、文件夹、终端与代理（也可通过 composer + → Context）
- Hooks — .cortex/hooks.json 的 prePrompt/postTurn 与内置 changelog gate