🌳 CoTangent 使用说明 / User Guide

CoTangent = Collaboration + Tangent（切线／分支）。名字里的意思是：你和 AI 协作着，把一段对话长成一棵可以随时分叉、随时长出新枝的树，而不是被困在一条单一、线性的聊天记录里。 CoTangent = Collaboration + Tangent (a branch/offshoot). The name captures what it does: you and the AI collaborate to grow a conversation into a tree that can branch off at any point, instead of being stuck in one single, linear chat log.

CoTangent 是一个树形对话 VS Code 扩展。普通对话可以沿当前分支持续进行，也可以从历史回复创建新分支、合并多个节点，或让小模型把一条完整回复拆成可继续追问的语义要点。后端可在 Claude Code 与 Codex 之间自由切换。 CoTangent is a tree-based conversation VS Code extension. A regular conversation can keep going along its current branch, or you can create a new branch from a past reply, merge multiple nodes, or have a small model split a complete reply into semantic points you can keep asking about. The backend can be switched freely between Claude Code and Codex.

1. 启动 CoTangent / Launching CoTangent

已安装扩展（通过 .vsix 安装） / Installed extension (via .vsix)

最简单的方式：点击 VS Code 窗口底部状态栏上的 CoTangent 按钮即可直接打开面板，不需要走命令面板。 The simplest way: click the CoTangent button in VS Code's bottom status bar to open the panel directly — no need to go through the Command Palette.

也可以通过命令面板打开： You can also open it via the Command Palette:

• macOS：Cmd+Shift+P / macOS: Cmd+Shift+P
• Windows/Linux：Ctrl+Shift+P / Windows/Linux: Ctrl+Shift+P

运行 CoTangent: 打开树形对话画布。 Run CoTangent: Open Conversation Tree.

首次运行：自动下载 SDK / First run: automatic SDK download

CoTangent 的安装包本身不包含 Claude Agent SDK 或 Codex SDK（两者各自带有几十到几百 MB 的平台原生二进制，打包进插件会让安装包过于臃肿）。首次打开面板时，如果本机还没有下载过 SDK，也没有手动放置过离线版本，插件会立刻自动开始下载，不需要你手动触发： CoTangent's install package doesn't bundle the Claude Agent SDK or the Codex SDK — each ships with tens to hundreds of MB of platform-native binaries, and bundling them would make the extension too bloated. The first time you open the panel, if neither SDK has been downloaded yet and no offline version has been placed manually, the extension immediately starts downloading on its own — no manual trigger needed:

• 会弹出一条通知，说明正在下载、大概需要一两分钟；这条通知里同时会给出：手动下载命令、当前使用的 npm 注册源，以及本机离线放置目录的真实绝对路径（不是笼统的 ~——Windows 下会展开成类似 C:\Users\你\.cotangent\sdk-runtime\offline\node_modules\；如果你在 WSL 里运行，还会额外提示这个路径是 WSL 文件系统内部的，跟 Windows 侧的用户目录是两个完全不同的位置）。
• A notification pops up saying the download is in progress and will take roughly a minute or two; this same notification also gives you: the manual download command, the npm registry currently in use, and the actual absolute path for the local offline-placement directory (not a vague ~ — on Windows it expands to something like C:\Users\you\.cotangent\sdk-runtime\offline\node_modules\; if you're running in WSL, it adds a note that this path is inside the WSL filesystem, a completely different location from the Windows-side user directory).
• 下载期间面板里会显示"正在下载所需的 SDK，请稍候"，下载完成后面板自动刷新，不需要重新加载窗口。
• The panel shows "Downloading required SDKs, please wait" during the download, and refreshes automatically once done — no window reload needed.
• 如果网络下载失败（比如内网环境访问不到 npm registry），错误提示里同样会带上手动下载和离线放置的完整说明，可以按提示手动操作，或者等网络恢复后在命令面板运行 CoTangent: 立即检查 SDK 更新 重试。
• If the network download fails (e.g. an internal network with no access to the npm registry), the error message likewise includes the full manual-download and offline-placement instructions — follow them manually, or retry with CoTangent: Check for SDK Updates Now from the Command Palette once your network is back.

如果你所在的网络完全无法访问 npm registry，可以在另一台能联网的同类机器（操作系统和 CPU 架构必须一致，比如都是 macOS Apple Silicon）上提前下载好，再手动拷过来——完整步骤见下文"12. SDK 管理"一节。 If your network can't reach the npm registry at all, you can download the SDK ahead of time on another machine of the same kind with network access (the OS and CPU architecture must match, e.g. both macOS Apple Silicon), then copy it over by hand — see "12. SDK Management" below for the full steps.

首次运行：没有检测到任何配置 / First run: no configuration detected

打开面板时，如果 CoTangent 既没检测到 ~/.claude/settings.json 或 ~/.codex/config.toml（也就是本机完全没装过 Claude Code 或 Codex CLI 并登录过），也没有你之前保存的任何供应商预设，插件会自动弹出"管理供应商"面板，并提示需要先配置一个供应商才能开始对话——不需要自己去找这个入口在哪。配置方式见"10. 引擎、模型与权限 → 切换供应商"一节。 When you open the panel, if CoTangent detects neither ~/.claude/settings.json nor ~/.codex/config.toml (meaning neither Claude Code nor the Codex CLI has ever been installed and logged in locally) and no provider preset you've saved before, the extension automatically opens the "Manage Providers" panel with a prompt that you need to configure one before starting a conversation — you don't need to go hunting for where this entry point is. See "10. Engine, Models, and Permissions → Switching providers" below for how to configure one.

2. 开始对话 / Starting a conversation

1. 在右侧输入框中输入问题。/ Type your question in the input box on the right.
2. 按 Enter 或点击 开始 ▶ 发送。/ Press Enter or click Start ▶ to send.
3. 使用 Shift+Enter 输入换行。/ Use Shift+Enter for a new line.
4. AI 生成期间，内容以稳定的纯文本流式显示；生成完成后统一渲染 Markdown、表格和代码块。 While the AI generates a reply, content streams in as stable plain text; Markdown, tables, and code blocks are all rendered together once generation finishes.

中文输入法确认候选词时产生的 Enter 不会发送消息。 An Enter produced by confirming an IME candidate word never sends the message.

3. 继续当前分支 / Continuing the current branch

1. 在左侧树中单击任意节点。/ Click any node in the tree on the left.
2. 右侧会显示从祖先节点到该节点的完整对话路径。/ The panel on the right shows the full conversation path from the ancestor nodes down to that node.
3. 普通对话节点上继续提问，会把新一轮追加到同一节点；切换 Claude/Codex、切换供应商或节点已有子项都不会自动新建子节点。左侧会显示"· N 轮"。 Asking a follow-up on a regular conversation node appends the new turn to the same node; switching Claude/Codex, switching providers, or the node already having children never auto-creates a new child node. The left panel shows "· N turns".

一个普通节点因此可以代表一段连续对话，右侧按顺序保留其中每一轮用户问题、AI 回复和工具活动。 A regular node can therefore represent one continuous conversation, with every user question, AI reply, and tool activity within it kept in order on the right.

4. 创建分支 / Creating a branch

以下操作会明确创建新节点，而不是追加到当前对话段： The following actions explicitly create a new node instead of appending to the current conversation segment:

• 从 AI 拆分出的语义要点继续追问；/ Continuing to ask from an AI-split semantic point;
• 右键选择 ＋ 插入子节点；/ Right-click and choose ＋ Insert Child Node;
• 多选节点后合并追问。/ Merging and asking from multiple selected nodes.

Claude 分支会尽量从对应的原生会话继续并 fork，避免不同分支互相覆盖。 Claude branches try to continue and fork from the corresponding native session wherever possible, so different branches never overwrite each other.

插入子节点 / Inserting a child node

1. 右键目标节点。/ Right-click the target node.
2. 选择 ＋ 插入子节点。/ Choose ＋ Insert Child Node.
3. 输入问题并点击 生成子节点 ▶。/ Type your question and click Generate Child Node ▶.

如果没有发送，临时子节点会被丢弃。 If nothing is sent, the temporary child node is discarded.

5. 合并多个节点追问 / Merging multiple nodes to ask a follow-up

1. 按住 Cmd（macOS）或 Ctrl（Windows/Linux）。/ Hold Cmd (macOS) or Ctrl (Windows/Linux).
2. 在左侧依次单击需要合并的节点。/ Click the nodes you want to merge, one by one, in the left panel.
3. 右侧标题会显示 合并 N 个要点。/ The header on the right shows Merging N points.
4. 输入需要综合分析的问题。/ Type the question you want analyzed across all of them.
5. 点击 合并展开(N)。/ Click Merge & Expand (N).

新回复会同时引用所选节点作为上下文。再次按住 Cmd/Ctrl 单击节点可取消选择。 The new reply references all selected nodes as context. Cmd/Ctrl-click a node again to deselect it.

6. AI 拆成子要点 / Splitting into AI points

普通回复默认保持完整，只有手动操作时才会拆分。 Regular replies stay whole by default — splitting only happens when triggered manually.

开始拆分 / Starting a split

1. 等待目标 AI 回复生成完成。/ Wait for the target AI reply to finish generating.
2. 在左侧右键该回复节点。/ Right-click that reply node in the left panel.
3. 选择 ⑃ AI 拆成子要点。/ Choose ⑃ Split into AI Points.
4. 等待小模型完成分析，生成的要点会出现在原回复下方。/ Wait for the small model to finish its analysis; the generated points appear below the original reply.

拆分规则 / Splitting rules:

• 只拆该节点中最新一轮 AI 回复，不会把整个多轮对话段重新拆一遍。
• Only the most recent AI reply turn in that node is split — a whole multi-turn conversation segment is never re-split at once.
• "充分拆分"表示重要内容覆盖充分，并非节点数量越多越好；AI 会优先使用最少且足够的节点。
• "Thorough splitting" means covering the important content thoroughly, not maximizing the node count; the AI prefers the fewest sufficient nodes.
• 原文已有清晰标题、编号或顶层并列结构时，一个顶层主题对应一个节点，并保持原有顺序和语义。
• When the original text already has clear headings, numbering, or a top-level parallel structure, one top-level topic maps to one node, preserving the original order and meaning.
• 标题下的子标题、阶段、对象、属性、例子和步骤保留在该节点正文中，不提升为同级节点。例如"K12 功能包"下的小学、初中、高中通常保留在同一节点内。
• Subheadings, stages, objects, attributes, examples, and steps under a heading stay in that node's body text — they're never promoted to sibling nodes. For example, elementary/middle/high school under a "K-12 feature package" topic normally stay inside the same node.
• 原文结构不清时，AI 按真正可独立追问的主题块归组，不按句子、段落或每个属性机械切分。
• When the original text has no clear structure, the AI groups content into topic blocks that can genuinely be followed up on independently, rather than mechanically splitting by sentence, paragraph, or attribute.
• AI 不应补充原文不存在的观点或事实；一次可生成 2～12 个要点。
• The AI must never add opinions or facts absent from the original text; a single split produces 2 to 12 points.

拆分会额外产生一次小模型调用，但不会 resume 或修改原对话会话，也不会调用工具、运行命令或修改文件。 Splitting costs one extra small-model call, but never resumes or modifies the original conversation session, and never calls a tool, runs a command, or modifies a file.

从某个要点继续追问 / Continuing to ask from a point

1. 单击生成的要点。/ Click a generated point.
2. 在右侧输入希望深入讨论的问题。/ Type the question you want to dig into on the right.
3. 点击 追问 ▶。/ Click Ask ▶.

界面中的新分支会挂在所选要点下；模型则从该要点来源的完整回复继续上下文，并把所选要点作为本轮重点。 The new branch in the UI hangs off the selected point; the model continues context from the complete reply that point came from, with the selected point framed as this turn's focus.

重新拆分 / Re-splitting

如果不满意当前结果，可以再次右键原始回复并选择 AI 拆成子要点。新结果成功生成并校验后，才会替换旧要点；如果拆分失败，旧结果保持不变。 If you're not happy with the current result, you can right-click the original reply again and choose Split into AI Points. The new result only replaces the old points once it's fully generated and validated; if the split fails, the old result is left unchanged.

如果已有要点下面产生了后续对话，CoTangent 会拒绝重新拆分，防止误删分支。需要重新拆分时，请先删除相关后续分支。 If a point already has follow-up conversation under it, CoTangent refuses to re-split, to prevent accidentally deleting a branch. To re-split anyway, delete the related follow-up branches first.

取消拆分 / Cancelling a split

拆分过程中可使用任意一种方式取消 / While a split is running, you can cancel it any of these ways:

• 按 Esc；/ Press Esc;
• 点击右侧的 ⏹ 取消拆分；/ Click ⏹ Cancel Split on the right;
• 右键正在拆分的节点，选择 ⏹ 取消 AI 拆分。/ Right-click the node currently splitting and choose ⏹ Cancel AI Split.

取消后会显示"已取消 AI 拆分"，不会改变现有树结构。 Cancelling shows "AI split cancelled" and leaves the existing tree structure unchanged.

Claude 与 Codex 引擎均支持 AI 语义拆分。Claude 靠 tools: [] 彻底禁用工具，保证拆分调用绝对不会执行命令或改文件；Codex 没有等价的"完全禁用工具"选项，改用只读沙箱 + 禁止审批兜底，理论上隔离程度略弱于 Claude，但实际效果一致：拆分调用不会修改你的工作区。 Both the Claude and Codex engines support AI semantic splitting. Claude disables tools entirely via tools: [], guaranteeing a split call can never run a command or modify a file; Codex has no equivalent "disable tools entirely" option, so it falls back to a read-only sandbox plus never-approve — in theory the isolation is slightly weaker than Claude's, but the practical effect is the same: a split call never modifies your workspace.

7. 中断、修改与压缩 / Interrupting, editing, and compacting

中断正在生成的回复 / Interrupting a reply in progress

AI 输出期间 / While the AI is generating output:

• 按 Esc；或 / Press Esc; or
• 点击右侧 ⏹ 中断。/ Click ⏹ Interrupt on the right.

修改上一轮问题 / Editing the last question

在没有生成或拆分任务运行时，快速按两次 Esc，CoTangent 会移除上一轮并把原问题放回输入框，便于修改后重新发送。多轮对话段只移除其中最后一轮；节点仅有一轮时才删除整个节点并返回父节点。 When nothing is generating or splitting, quickly press Esc twice — CoTangent removes the last turn and puts the original question back in the input box for editing and resending. For a multi-turn segment, only the last turn is removed; a node with only one turn is deleted entirely, returning you to its parent.

压缩上下文 / Compacting context

当当前 Claude 节点包含可继续的会话时，右侧会显示 🗜 压缩。点击后会对该分支执行 /compact，用于减少较长会话的上下文占用。 When the currently open Claude node has a resumable session, 🗜 Compact appears on the right. Clicking it runs /compact on that branch, reducing the context footprint of a long conversation.

对话标题栏会从第一轮开始常驻显示 上下文剩余百分比和 token 数，不会等到使用量超过一半才出现。Claude 通常显示精确值；Codex 显示基于本轮完整输入的估算值。若自定义 Codex 网关没有提供上限，请在 ⚙ 管理供应商 → 上下文窗口（tokens） 中填写该模型的上下文长度。 The conversation header always shows the remaining context percentage and token count starting from the very first turn, not just once usage crosses 50%. Claude usually shows an exact value; Codex shows an estimate based on the full input of the current turn. If a custom Codex gateway doesn't report a context limit, enter that model's context length under ⚙ Manage Providers → Context window (tokens).

8. 节点操作 / Node actions

在左侧节点上右键可执行 / Right-clicking a node on the left offers:

• 插入子节点：从该节点创建新分支；/ Insert Child Node: create a new branch from this node;
• AI 拆成子要点：拆分已完成的原始 AI 回复；/ Split into AI Points: split a completed original AI reply;
• 删除该节点及子树：删除节点及其所有后代。/ Delete This Node and Subtree: delete the node and all its descendants.

其他操作 / Other actions:

• 点击节点左侧的 ＋/－：展开或折叠子树；/ Click the ＋/－ to the left of a node: expand or collapse its subtree;
• 将一个节点拖到另一个节点上：把它移动到目标节点下面；/ Drag a node onto another: move it to be a child of the target;
• 点击顶部 ＋ 新建：关闭当前节点并清空多选；下一次提问会创建一个新的顶层根节点，已有节点不会删除。/ Click ＋ New at the top: close the current node and clear the multi-selection; the next prompt creates a new top-level root node while keeping all existing nodes.

删除节点、删除子树和命令面板中的 CoTangent: New Conversation Tree 会移除当前树中的相关内容，操作前请确认不再需要这些分支。 Deleting a node, deleting a subtree, and using CoTangent: New Conversation Tree from the Command Palette remove the relevant content from the current tree — make sure you no longer need those branches before doing so.

9. 澄清式提问 / Clarifying questions

当 Claude 或 Codex 需要向你确认选择，而不是自己猜测时，会调用各自的结构化提问工具。CoTangent 会用专门的问题卡片展示，而不是原始文字或 JSON： When Claude or Codex needs to confirm a choice with you instead of guessing, it calls its own structured question tool. CoTangent renders this with a dedicated question card, not raw text or JSON:

• Claude：AskUserQuestion 工具（Claude Agent SDK 内置能力）；/ Claude: the AskUserQuestion tool (a built-in Claude Agent SDK capability);
• Codex：request_user_input 工具（codex app-server 的实验性能力，插件已内置所需配置，不需要额外设置）。/ Codex: the request_user_input tool (an experimental codex app-server capability — the extension already includes the required configuration, no extra setup needed).

问题卡片支持 / The question card supports:

• 单选：一组按钮，选一个即可；/ Single-select: a group of buttons, pick one;
• 多选：一组勾选框，可以选多个；/ Multi-select: a group of checkboxes, pick several;
• "其他"：题目允许时会额外出现一个自由文本输入框；/ "Other": an extra free-text field appears when the question allows it;
• 跳过：点击 跳过 不作答，对话会照常继续，模型会根据你没有选择的情况调整后续回复，不会中断或报错。
• Skip: clicking Skip leaves the question unanswered and the conversation continues normally — the model adjusts its reply based on nothing being selected, without aborting or erroring out.

提交后卡片会消失，模型基于你的选择继续当前回合。 Once submitted, the card disappears and the model continues the current turn based on your choices.

10. 引擎、模型与权限 / Engine, models, and permissions

切换引擎 / Switching engines

在顶部 引擎 下拉框中选择 / Choose from the Engine dropdown at the top:

• Claude Code：通过 Claude Agent SDK 使用当前 Claude Code/网关配置；/ Claude Code: uses the current Claude Code/gateway configuration via the Claude Agent SDK;
• Codex：通过 codex app-server 长连接运行，支持真实的逐步交互审批（见下文"权限模式"）。/ Codex: runs over a codex app-server long-lived connection, with real step-by-step interactive approval (see "Permission modes" below).

两个引擎的 SDK 都是运行时按需下载的（见"首次运行：自动下载 SDK"），不要求用户另外安装 Claude Code CLI 或 Codex CLI。 Both engines' SDKs are downloaded on demand at runtime (see "First run: automatic SDK download"), so you don't need to separately install the Claude Code CLI or the Codex CLI.

如果名称后显示"未检测到"，请检查对应环境、认证和命令配置，然后点击顶部 ↻ 刷新能力信息；如果是因为 SDK 还在下载中，面板会提示"正在下载所需的 SDK"，等下载完成后会自动刷新。 If a name shows "not detected" next to it, check the corresponding environment, authentication, and command configuration, then click ↻ at the top to refresh capability info; if it's because the SDK is still downloading, the panel shows "Downloading required SDKs" and refreshes automatically once the download completes.

切换供应商 / Switching providers

顶部工具栏的引擎、供应商、模型映射和权限模式都属于当前打开的节点；切换到另一个节点时，工具栏会自动恢复那个节点自己的设置。没有打开节点时，工具栏使用工作区默认值，并会作为新顶层节点的初始设置。/ The toolbar's engine, provider, model mappings, and permission mode belong to the open node. Opening another node restores that node's own settings. With no node open, the toolbar shows workspace defaults, which seed the next top-level node.

• "跟随 ~/.claude/settings.json / ~/.codex/config.toml"保持原有 CLI 配置行为；/ "Follow ~/.claude/settings.json / ~/.codex/config.toml" keeps the original CLI configuration behavior;
• 其他选项来自 CoTangent 顶部 ⚙ 管理供应商 中保存的预设；/ Other options come from presets saved in CoTangent's ⚙ Manage Providers panel;
• 切换后立即刷新该预设的模型列表，后续请求使用新 Host、Key 和默认模型；/ Switching immediately refreshes that preset's model list; subsequent requests use the new host, key, and default model;
• 切换供应商后仍在当前节点内追加。为了防止跨网关恢复错误，会以文本方式带入旧上下文，不会复用旧网关 session。
• After switching providers, the conversation still appends within the current node. To avoid incorrectly resuming across gateways, the old context is carried over as plain text rather than reusing the old gateway's session.

点击顶部 ⚙ 管理供应商 后，可以分别管理 Claude Code 与 Codex 预设 / Clicking ⚙ Manage Providers at the top lets you manage Claude Code and Codex presets separately:

• 本机配置会读取对应的 ~/.claude/settings.json 或 ~/.codex/config.toml，只用于查看和选用，不能在 CoTangent 中修改；/ Local config reads the corresponding ~/.claude/settings.json or ~/.codex/config.toml, for viewing and selecting only — it can't be modified from within CoTangent;
• 点击新增供应商或复制为新供应商，会复制当前显示的配置，再允许修改并另存；/ Clicking Add Provider or Duplicate as New Provider copies the currently shown config, letting you edit and save it as a new one;
• Claude 页面直接填写 Opus、Sonnet、Haiku 三个真实模型名，不需要再配置模型别名或显示名；/ The Claude page lets you fill in the three actual model names for Opus, Sonnet, and Haiku directly — no need to configure model aliases or display names separately;
• 表单最下方可以直接编辑完整供应商 JSON，额外环境变量写在 env 对象中。/ The bottom of the form lets you edit the full provider JSON directly; extra environment variables go in the env object.

保存后再通过顶部供应商下拉框切换。 Switch between presets afterward via the provider dropdown at the top.

预设保存在 VS Code 本机扩展存储中，不会把大量字段写进 settings.json，并在所有工作区共用。API Key 仍以明文存在本机 VS Code 用户数据中。旧版 settings.json 预设会在首次启动时自动导入。预设名称可以任意填写，但 Claude 网关必须兼容 Anthropic Messages 的流式/工具调用，Codex 网关必须兼容 Responses API，仅支持 /chat/completions 的地址不能直接使用。 Presets are saved in VS Code's own local extension storage, without writing a pile of fields into settings.json, and are shared across all workspaces. API keys remain plaintext in your local VS Code user data. Presets from the old settings.json format are auto-imported the first time you launch. Preset names can be anything, but a Claude gateway must be compatible with Anthropic Messages streaming/tool calls, and a Codex gateway must be compatible with the Responses API — an endpoint that only supports /chat/completions can't be used directly.

大、中、小模型映射 / Large/medium/small model mapping

Claude 和 Codex 两种引擎下，顶部都提供同样的操作 / Both the Claude and Codex engines offer the same controls at the top:

1. 级别：选择当前要编辑的映射槽位（大/中/小）；/ Tier: choose the mapping slot you're currently editing (large/medium/small);
2. 映射：为该级别选择 自动匹配 或网关/CLI 返回的具体模型。/ Mapping: set that tier to Auto-match or a specific model returned by the gateway/CLI.

例如，先在"级别"中选择"小"，再在"映射"中选择一个模型，即可配置语义拆分使用的小模型。 For example, choose "small" under "Tier", then pick a model under "Mapping" to configure the small model used for semantic splitting.

模型列表来自当前引擎实际返回的数据，不是插件内硬编码的固定列表。Claude 与 Codex 的大/中/小映射会分别保存在当前节点中，切换引擎不会覆盖另一个引擎或另一个节点的值。 The model list comes from data actually returned by the current engine — it's not a hardcoded fixed list in the extension. Claude's and Codex's large/medium/small mappings are stored separately in the current node, so switching engines never overwrites another engine's or another node's value.

当前顶部"级别"下拉框用于选择要编辑的大/中/小映射，不直接切换本轮路由模式。本轮使用自动路由还是固定级别，请在 VS Code 设置中修改 cotangent.modelRouting。 The "Tier" dropdown at the top is for choosing which large/medium/small mapping to edit — it doesn't directly switch this turn's routing mode. Whether the current turn uses automatic routing or a fixed tier is controlled by cotangent.modelRouting in VS Code settings.

模型设置 / Model settings:

自动路由在本地根据任务长度、代码量、是否合并节点以及架构/重构/翻译等关键词判断，不会为路由额外调用一次模型。 Automatic routing decides locally based on task length, amount of code, whether nodes are being merged, and keywords like architecture/refactor/translate — it never makes an extra model call just to route.

权限模式 / Permission modes

Claude 和 Codex 两种引擎下均可选择，且两者行为语义一致 / Available for both the Claude and Codex engines, with consistent semantics across both:

在输入区域按 Shift+Tab 可以循环切换权限模式。 Press Shift+Tab in the input area to cycle through permission modes.

Codex 侧的说明：Codex 后端走 codex app-server 长连接，"每次询问"模式下会像 Claude 一样对命令执行、文件改动逐个弹出真实的审批卡片（Allow/Deny）。点击 Deny 只会拒绝这一步操作，模型会继续对话并可能换一种方式完成任务，不会打断整个回合。具体沙箱/审批策略对应关系： A note on Codex: the Codex backend runs over a codex app-server long-lived connection; in "Ask every time" mode it pops real approval cards (Allow/Deny) for each command execution or file change, just like Claude. Clicking Deny only rejects that one step — the model continues the conversation and may try a different way to accomplish the task, without aborting the whole turn. The exact sandbox/approval-policy mapping:

使用 全部放行 时，AI 可能直接运行命令或修改工作区文件，请只在可信项目和明确任务中使用。 With Full access, the AI may directly run commands or modify workspace files — use it only on trusted projects with clearly scoped tasks.

图片附件 / Image attachments

Claude 与 Codex 都能接收粘贴/拖入输入框的图片。Claude 走 SDK 原生的图片输入；Codex 会把图片写入一个临时文件传给模型，回合结束后立即清理，不会残留在磁盘上。 Both Claude and Codex can receive images pasted or dropped into the input box. Claude uses the SDK's native image input; Codex writes the image to a temp file and passes it to the model, cleaning up immediately after the turn ends, leaving nothing on disk.

@ 文件附加 / @ file attachments

在输入框任意位置输入 @（前面是空格或在行首），会弹出工作区文件搜索菜单 / Typing @ anywhere in the input box (preceded by a space or at the start of the line) opens a workspace file search menu:

• 继续输入可按文件名/路径过滤；/ Keep typing to filter by filename/path;
• 方向键选择，Enter 或 Tab 确认，鼠标点击也可以；/ Use the arrow keys to navigate, Enter or Tab to confirm, or click with the mouse;
• 按 Esc 关闭菜单。/ Press Esc to close the menu.

选中文件后，输入框里会插入 @相对路径，同时插件会立即读取该文件内容，成功后在输入框上方出现一个文件小标签（chip）。发送后模型会看到这个文件的完整内容（超出约 50000 字符会截断），Claude 与 Codex 都支持。 Once you pick a file, @relativePath is inserted into the input box, and the extension immediately reads that file's content — once successful, a small file chip appears above the input box. When you send, the model sees the file's full content (content beyond roughly 50,000 characters is truncated); both Claude and Codex support this.

• 只支持单个文本文件，不支持文件夹或二进制文件（图片等）；/ Only a single text file is supported — not folders or binary files (like images);
• 一轮最多附加 10 个文件；/ Up to 10 files can be attached per turn;
• 手动删掉输入框里的 @相对路径 文字，或者点击小标签上的 ✕，都会取消这个附件；/ Manually deleting the @relativePath text in the input box, or clicking the ✕ on the chip, both remove that attachment;
• 文件内容只在当前这一轮生效，不会像图片附件一样残留到后续追问里，不会让上下文用量随对话变长而不断增加。
• File content only applies to the current turn — unlike image attachments it's never carried forward into later follow-ups, so context usage doesn't keep growing as the conversation gets longer.

11. Slash 命令 / Slash commands

在输入框中输入 / 会显示当前引擎或网关支持的命令 / Typing / in the input box shows the commands supported by the current engine or gateway:

• 使用方向键选择；/ Use the arrow keys to select;
• 按 Enter 或 Tab 填入命令；/ Press Enter or Tab to fill in the command;
• 按 Esc 关闭菜单。/ Press Esc to close the menu.

命令列表来自当前引擎能力查询。Claude 的命令来自 Claude Code 自身的命令发现机制；Codex 没有等价的实时查询接口，改为扫描本机 ~/.codex/prompts/*.md：文件名（去掉 .md）作为命令名，文件首行作为描述。这是 OpenAI 官方已标记为 deprecated 的旧机制，仅作为过渡期的最低限度支持，字段解析不保证完全准确。 The command list comes from querying the current engine's capabilities. Claude's commands come from Claude Code's own command-discovery mechanism; Codex has no equivalent real-time query interface, so it instead scans ~/.codex/prompts/*.md locally: the filename (minus .md) becomes the command name, and the file's first line becomes the description. This is an officially deprecated mechanism from OpenAI, supported here only as a minimal stopgap, and field parsing isn't guaranteed to be fully accurate.

12. SDK 管理 / SDK management

CoTangent 的 Claude Agent SDK 和 Codex SDK 都是运行时按需下载的，不随插件安装包打包。除了首次运行时的自动下载（见前文"首次运行：自动下载 SDK"），还支持后续自动更新和离线手动放置两种方式。 Both CoTangent's Claude Agent SDK and Codex SDK are downloaded on demand at runtime — neither ships inside the extension's install package. Besides the automatic download on first run (see "First run: automatic SDK download" above), both automatic updates afterward and manual offline placement are supported.

后续自动更新 / Automatic updates afterward

CoTangent 默认每 24 小时自动检查 Claude Agent SDK 和 Codex SDK 是否有新版本。发现新版本后会下载到 VS Code 的扩展全局存储并执行以下校验 / By default, CoTangent automatically checks for new versions of the Claude Agent SDK and Codex SDK every 24 hours. Once a new version is found, it's downloaded into VS Code's extension global storage, and the following checks run:

• npm 包完整性；/ npm package integrity;
• Claude SDK 的 query() 与 Codex SDK 的 Codex 导出；/ the Claude SDK's query() export and the Codex SDK's Codex export;
• 当前操作系统和 CPU 对应的 Claude/Codex 原生运行时；/ the native Claude/Codex runtime matching the current OS and CPU;
• 两个内置 CLI 是否能够正常报告版本。/ whether both bundled CLIs can correctly report their version.

安装过程不会执行 npm 包的 lifecycle scripts。任一步失败都会继续使用当前正在用的版本，不影响现有对话。这类常规更新（区别于首次运行时的初始下载）不会在当前对话中途热切换；下载完成后重新加载窗口，或下次启动 VS Code 时生效。 The install process never runs npm package lifecycle scripts. If any step fails, the extension keeps using the version currently in use, without affecting existing conversations. This kind of routine update (unlike the initial download on first run) never hot-swaps mid-conversation — it takes effect after reloading the window once the download finishes, or the next time VS Code starts.

命令面板中可以运行 / From the Command Palette you can run:

• CoTangent: 立即检查 SDK 更新；/ CoTangent: Check for SDK Updates Now;
• CoTangent: 查看当前 SDK 版本。/ CoTangent: Show Current SDK Versions.

VS Code 设置中的 cotangent.sdkUpdates.mode 支持 / The cotangent.sdkUpdates.mode VS Code setting supports:

• automatic：发现新版后自动下载（默认）；/ automatic: automatically downloads once a new version is found (default);
• notify：只提示，确认后下载；/ notify: notifies only, downloading after confirmation;
• off：不在后台做常规检查，仍可手动检查。注意：这个设置只影响后台的例行更新检查，不影响首次运行时"完全没有 SDK 就必须下载"的那次初始下载——否则插件在全新安装且此设置为 off 时会永久无法运行任何引擎。
• off: disables routine background checks; manual checks remain available. Note: this setting only affects routine background update checks — it does not affect the initial download on first run, when there's no SDK at all and one must be downloaded; otherwise a fresh install with this setting at off could never run either engine at all.

cotangent.sdkUpdates.checkIntervalHours 可修改检查间隔，cotangent.sdkUpdates.registry 可在企业网络中改为可信 npm 镜像。下载会额外占用磁盘空间，因为下载目录需要包含两个 SDK 对应的当前平台原生运行时（通常数百 MB）。 cotangent.sdkUpdates.checkIntervalHours changes the check interval, and cotangent.sdkUpdates.registry can be set to a trusted npm mirror on an enterprise network. Downloading uses extra disk space, since the download directory needs to hold the current platform's native runtime for both SDKs (typically a few hundred MB).

离线环境：手动放置 SDK / Offline environments: placing the SDK manually

如果这台机器完全访问不到 npm registry（内网、无 VPN），可以在另一台能联网的同类机器上把 SDK 下载好，再手动拷贝过来，插件启动时会直接识别并使用，不发任何网络请求： If this machine can't reach the npm registry at all (internal network, no VPN), you can download the SDK on another machine of the same kind that does have network access, then copy it over by hand — the extension recognizes and uses it directly on startup, with no network requests at all:

1. 在一台联网机器上（操作系统和 CPU 架构必须与运行 CoTangent 的机器一致，例如都是 macOS Apple Silicon，或都是 Windows x64），新建一个空目录并执行 / On a networked machine (the OS and CPU architecture must match the machine running CoTangent — e.g. both macOS Apple Silicon, or both Windows x64), create an empty directory and run:

   mkdir sdk-offline-bundle && cd sdk-offline-bundle
   npm init -y
   npm install @anthropic-ai/claude-agent-sdk@0.3.215 @openai/codex-sdk@0.145.0
   

   版本号可以填任意你想要的版本（不填 @版本号 则装最新版），两个包必须一起装，npm 会自动把对应平台的原生运行时一起拉下来。 The version numbers can be whatever you want (omit @version to install latest); both packages must be installed together, and npm automatically pulls in the matching platform's native runtime.

2. 把生成的整个 node_modules/ 目录拷贝到运行 CoTangent 的机器上，放进 / Copy the entire resulting node_modules/ directory to the machine running CoTangent, into:

   • macOS / Linux：~/.cotangent/sdk-runtime/offline/node_modules/（~ 是你的用户主目录） / macOS / Linux: ~/.cotangent/sdk-runtime/offline/node_modules/ (~ is your home directory)
   • Windows：C:\Users\<你的用户名>\.cotangent\sdk-runtime\offline\node_modules\ / Windows: C:\Users\<your username>\.cotangent\sdk-runtime\offline\node_modules\
   • WSL：注意这个路径是 WSL 发行版内部的路径，跟 Windows 侧的用户目录是两个不同的地方。如果你在 Windows 侧下载好了 SDK，需要通过 \\wsl$\<发行版名>\home\<用户名>\.cotangent\... 或 wsl cp 命令拷进 WSL 内部，而不是直接放进 C:\Users\你\ 下面。 WSL: note that this path is inside your WSL distro, a different location from the Windows-side user directory. If you downloaded the SDK on the Windows side, copy it into WSL via \\wsl$\<distro name>\home\<username>\.cotangent\... or a wsl cp command, rather than placing it directly under C:\Users\you\.

   这个路径可以通过 cotangent.sdkUpdates.offlinePath 改成别的位置，例如团队共享盘。命令面板执行 CoTangent: Open Offline SDK Folder 可以直接打开这个目录（如果目录不存在会自动创建）。 This path can be changed to somewhere else, such as a shared team drive, via cotangent.sdkUpdates.offlinePath. Run CoTangent: Open Offline SDK Folder from the Command Palette to open this directory directly (it's created automatically if missing).

3. 命令面板执行 CoTangent: Verify Offline SDK Folder，插件会真实加载两个 SDK 并调用一次原生 CLI 的 --version，确认拷贝无误（尤其是平台/架构是否匹配）。校验通过后按提示重新加载窗口即可生效。 Run CoTangent: Verify Offline SDK Folder from the Command Palette — the extension actually loads both SDKs and calls the native CLI's --version once, confirming the copy is intact (especially platform/architecture match). Once verification passes, reload the window as prompted to take effect.

几点说明 / A few notes:

• 手动放置的离线版本不会被自动更新覆盖或删除，插件从不写入这个目录。
• A manually placed offline version is never overwritten or deleted by automatic updates — the extension never writes to this directory.
• 优先级：如果同时存在"自动下载的版本"和"手动放置的离线版本"，自动下载的版本优先（它本身就是联网校验过的）；只有在没有自动下载版本时才使用离线目录；两者都没有时插件会持续尝试首次下载，或提示你手动放置。
• Priority: if both an "auto-downloaded version" and a "manually placed offline version" exist, the auto-downloaded one wins (it's already been verified online); the offline directory is only used when there's no auto-downloaded version; with neither present, the extension keeps retrying the first-run download, or prompts you to place one manually.
• 校验失败（比如平台不匹配、目录不完整）时会自动跳过离线目录，改走自动下载或提示重新放置，不会导致插件崩溃。
• On verification failure (e.g. platform mismatch, incomplete directory), the offline directory is automatically skipped in favor of an auto-download or a re-placement prompt — it never crashes the extension.

13. 数据保存 / Data storage

对话树会保存到当前 VS Code 工作区状态中。工作区设置只作为空白画布的默认值；每个真实对话节点会保存自己的引擎、供应商、模型映射、路由方式和权限模式。 The conversation tree is saved into the current VS Code workspace state. Workspace settings provide defaults for a blank canvas; every real conversation node saves its own engine, provider, model mappings, routing mode, and permission mode.

切换到另一个工作区时，会使用该工作区自己的树和配置。 Switching to a different workspace uses that workspace's own tree and configuration.

14. 常见问题 / Troubleshooting

打开面板后一直显示"正在下载所需的 SDK" / The panel keeps showing "Downloading required SDKs" after opening

首次运行需要真实从 npm 下载两个 SDK（各自带平台原生二进制，通常需要一两分钟）。如果长时间没有变化 / The first run genuinely needs to download two SDKs from npm (each with platform-native binaries, typically taking a minute or two). If nothing changes for a long time:

1. 确认这台机器能访问 https://registry.npmjs.org（或你在设置里配置的 cotangent.sdkUpdates.registry）；/ Confirm this machine can reach https://registry.npmjs.org (or whatever cotangent.sdkUpdates.registry you've configured in settings);
2. 如果网络受限，改用离线手动放置（见"12. SDK 管理 → 离线环境：手动放置 SDK"），下载失败的提示里也会带上同样的说明；/ If the network is restricted, switch to manual offline placement (see "12. SDK Management → Offline environments: placing the SDK manually") — a failed download's error message includes the same instructions;
3. 命令面板运行 CoTangent: 立即检查 SDK 更新 手动重试。/ Run CoTangent: Check for SDK Updates Now from the Command Palette to retry manually.

打开面板就自动弹出了"管理供应商" / Opening the panel automatically pops up "Manage Providers"

说明本机没有检测到 ~/.claude/settings.json 或 ~/.codex/config.toml，也没有任何已保存的供应商预设——需要先配置一个才能开始对话。可以选择"跟随本机 CLI 配置"（先安装并登录 Claude Code 或 Codex CLI），或者直接在这个面板里填写第三方网关的 API Host/Key。这个提示每个面板只会自动弹一次，配置好之后可以随时通过顶部 ⚙ 管理供应商 按钮再次打开。 This means the local machine has neither ~/.claude/settings.json nor ~/.codex/config.toml detected, nor any saved provider preset — one needs to be configured before starting a conversation. You can choose "follow local CLI config" (install and log in to Claude Code or the Codex CLI first), or fill in a third-party gateway's API host/key directly in this panel. This prompt only auto-opens once per panel; once configured, you can reopen it anytime via the ⚙ Manage Providers button at the top.

修改代码后界面没有变化（仅开发模式） / The UI doesn't change after editing code (dev mode only)

1. 运行 npm run build；/ Run npm run build;
2. 在扩展开发宿主中运行 Developer: Reload Window；/ Run Developer: Reload Window in the Extension Development Host;
3. 必要时关闭并重新按 F5 启动。/ If needed, close and relaunch with F5.

模型列表为空或模型不可用 / The model list is empty or a model is unavailable

1. 确认主对话能正常调用当前网关；/ Confirm the main conversation can call the current gateway normally;
2. 检查 Claude Code 用户、项目和本地设置中的网关与认证配置；/ Check the gateway and authentication configuration in Claude Code's user, project, and local settings;
3. 点击顶部 ↻ 刷新；/ Click ↻ at the top to refresh;
4. 在"映射"中重新选择网关当前公开的模型。/ Re-select a model currently exposed by the gateway under "Mapping".

主对话和 AI 拆分共用同一套 Claude Code 网关与认证配置，只是拆分使用"小模型"映射。 The main conversation and AI splitting share the same Claude Code gateway and authentication configuration — splitting just uses the "small model" mapping.

拆分提示达到最大回合数 / The split prompt hits the maximum turn count

当前版本已为结构化拆分预留多个协议回合。请先重新构建并执行 Developer: Reload Window；如果仍然出现该错误，请确认运行的是最新 dist/extension.js。 The current version reserves multiple protocol turns for structured splitting. Rebuild first and run Developer: Reload Window; if the error still occurs, confirm you're running the latest dist/extension.js.

拆分失败但原要点还在 / A split failed but the original point is still there

这是正常的保护行为。CoTangent 只有在新拆分结果完整生成并通过校验后才会替换旧要点。 This is expected protective behavior. CoTangent only replaces old points once the new split result is fully generated and validated.

无法重新拆分 / Can't re-split

如果旧要点下面已经产生后续对话，系统会阻止替换。请先删除这些后续分支，再右键原始回复重新拆分。 If follow-up conversation already exists under the old points, the system blocks the replacement. Delete those follow-up branches first, then right-click the original reply to re-split.

Markdown 在生成时没有立即渲染 / Markdown isn't rendered immediately while generating

这是预期行为。流式阶段使用纯文本以避免界面反复跳动；回复完成后才统一渲染 Markdown、表格和代码块。 This is expected behavior. The streaming phase uses plain text to avoid the UI jumping around; Markdown, tables, and code blocks are all rendered together once the reply finishes.

Esc 没有效果 / Esc has no effect

请先确认 CoTangent 面板处于当前活动窗口。生成回复或拆分期间按一次 Esc 是中断任务；空闲时快速按两次 Esc 才是编辑上一轮。 First confirm the CoTangent panel is the currently active window. Pressing Esc once while a reply or split is generating interrupts the task; pressing Esc twice quickly while idle edits the last turn instead.

模型问问题时直接输出了文字或 JSON，没有出现卡片 / The model outputs plain text or JSON directly when asking a question, with no card appearing

模型没有一定要调用 AskUserQuestion（Claude）或 request_user_input（Codex）工具，这取决于它当次的判断。可以在提示里明确要求"请使用该工具向我提问"再试一次；如果模型坚持用文字提问，属于模型自身选择，不是插件的问题。 The model isn't required to call AskUserQuestion (Claude) or request_user_input (Codex) — whether it does depends on its own judgment each time. You can explicitly ask it to "please use that tool to ask me" in your prompt and try again; if the model still insists on asking in plain text, that's the model's own choice, not an issue with the extension.

输入 @ 没有弹出文件菜单，或选中文件后没有内容 / Typing @ doesn't open the file menu, or there's no content after picking a file

1. 确认当前 VS Code 已经打开了一个工作区（文件夹），未打开工作区时 @ 搜索不到任何文件；/ Confirm VS Code currently has a workspace (folder) open — @ search finds no files at all without one;
2. 确认 @ 前面是空格或在行首——user@host 这种中间出现的 @ 不会触发菜单，避免误伤邮箱、用户名等正常文本；/ Confirm the @ is preceded by a space or at the start of the line — an @ appearing mid-word, like in user@host, never triggers the menu, to avoid misfiring on emails, usernames, and similar ordinary text;
3. 选中的文件如果是二进制文件（图片、编译产物等），会提示"看起来是二进制文件"，改为手动描述内容或换成文本文件；/ If the picked file is a binary file (an image, a build artifact, etc.), you'll see a message that it "looks like a binary file" — describe its content manually instead, or switch to a text file;
4. 手动删掉了输入框里的 @相对路径 文字，等同于取消该附件，发送前请确认文字还在原处。/ Manually deleting the @relativePath text in the input box is the same as cancelling that attachment — make sure the text is still there before sending.

15. 快捷操作速查 / Keyboard shortcuts