twinny：留在你网络里的本地 AI 代码补全 VS Code 插件｜部署与使用全指南
适用读者：想在 VS Code 里获得 Copilot 式代码补全与聊天、又不想把代码发到第三方云端的开发者；已经在用 Ollama / LM Studio / llama.cpp 跑本地模型、想给编辑器接一个本地补全的人；以及想给团队搭一个统一模型网关的小团队。本文所有步骤、快捷键、端口与命令均来自官方 GitHub README 与官方文档站，可直接照做；项目 MIT 许可、活跃维护、无遥测、免登录。
一、项目简介
twinny 是一个跑在 Visual Studio Code 里的 AI 编程助手，核心理念是"stays inside your network"（留在你自己的网络里）：代码补全、内联编辑、聊天、代码评审这些能力，全部指向你自己选的模型服务——可以在你本机、局域网另一台机器、某个托管 API，或团队共用的一个网关上。官方 README 明确：免费、开源、MIT 许可、无遥测、免登录。
核心信息一览
| 项目 | 内容 |
|---|---|
| 官方仓库 | https://github.com/twinnydotdev/twinny |
| 扩展市场 | https://marketplace.visualstudio.com/items?itemName=rjmacarthy.twinny |
| 官方文档 | https://docs.twinny.dev/ |
| 许可证 | MIT（"twinny is actively developed and provided as is"） |
| 运行环境 | Visual Studio Code 1.93 或更新版本 |
| 模型服务 | Ollama / LM Studio / llama.cpp / QVAC / Oobabooga / LiteLLM / Open WebUI，或任意 OpenAI 兼容服务；也支持托管 API 与团队网关 |
| 项目状态 | 活跃开发中（README 自述 "actively developed"），自 2023 年起由一人维护 |
适用场景
- 已经在本机用 Ollama 等工具跑了 7B 级模型，想在 VS Code 里得到幽灵文本补全；
- 在意代码隐私，不想把上下文发到某个 SaaS 补全服务；
- 团队想在内部署一个网关，让每人一把 Key、统一模型与用量统计；
- 想要补全用本地小模型、聊天用更强的托管模型这种"混用"组合。
能力边界
- 它是 VS Code 扩展，不是独立编辑器，需要先装 VS Code 1.93+；
- 它不自带模型，必须先有一个能跑的模型服务（本地或远程）；
- Agent 模式是实验性（experimental）功能；
- 团队网关的插件/策略/审计等高级能力属于付费许可，个人本地使用完全免费。
二、功能特性
- 代码补全（Code completion）：边敲边出 Fill-in-the-middle 幽灵文本，在合理处自动停下；上下文来自打开的文件、import、语言服务器与你最近的编辑；官方调校到在 7B 模型上也好用；
- 内联编辑（Inline edit）：
Ctrl+I唤起，描述要改什么，然后在编辑器里以 diff 形式逐块接受/拒绝；也能对任意诊断用"Fix with twinny"； - 聊天（Chat）：与你的代码对话，输入
@可附加文件、符号、问题面板、git diff、终端内容或工作区索引搜索；对话保留； - Agent 模式（实验性）：聊天里切换开关或按
Shift+Tab，让模型自己读、搜索、编辑文件并在工作区跑命令，每一步都在回复里展示；命令默认先问你再执行； - 工作区索引（Workspace index）：对整个工作区做关键词+向量混合检索，重排后再喂给提示，保存时增量更新，回复里会标出来源；
- 代码评审（Code review）：评审工作区改动、某分支相对基线，或直接评审一个 GitHub PR；并能基于已暂存 diff 生成提交信息；
- 终端（Terminal）：用自然语言写命令，执行前先给你看；命令失败时它会定位到具体文件与行并给出修复建议；
- 提示模板（Templates）：所有功能都是一条普通 VS Code 命令，可改键位、可编辑提示模板。
三、官方界面预览
官方 README 未内嵌界面截图，本文按规程不放网络杂图或 AI 占位图，故无配图；装好扩展后，补全以编辑器内幽灵文本出现，聊天与索引面板在 VS Code 侧边栏，具体界面以你安装版本为准。
四、官方链接汇总
| 资源 | 地址 |
|---|---|
| GitHub 仓库 | https://github.com/twinnydotdev/twinny |
| VS Code 扩展市场 | https://marketplace.visualstudio.com/items?itemName=rjmacarthy.twinny |
| 官方文档 | https://docs.twinny.dev/ |
| 快速上手 | https://docs.twinny.dev/getting-started/quick-start/ |
| 故障排查 | https://docs.twinny.dev/getting-started/troubleshooting/ |
| 更新日志 | https://docs.twinny.dev/reference/whats-new/ |
| 团队版介绍 | https://twinny.dev/ |
| 中文 README | 仓库内 README.zh-CN.md |
五、前置要求
- Visual Studio Code 1.93 或更新版本（README 明确要求）；
- 一个模型服务，任选其一：
- 本机：Ollama、LM Studio、llama.cpp、QVAC、Oobabooga、LiteLLM、Open WebUI，或任意 OpenAI 兼容服务；
- 局域网另一台机器：用 Devices 功能配对，走加密 P2P；
- 托管 API：OpenAI、Anthropic、Mistral（补全用 Codestral）、DeepSeek、OpenRouter、Gemini、Groq、Cohere、Perplexity；
- 显卡/内存：官方建议补全用 7B 级别模型即可获得较好体验；具体硬件按所选模型为准，文档站有"哪些模型在什么硬件上能干什么"的列表；
- （可选）Node.js：只有要自己跑团队网关
twinny-server时才需要，普通用户装扩展即可。
端口这件事：README 说 Ollama、LM Studio、llama.cpp 会在首次启动时被 twinny 在它们"常用端口"上自动发现，不用你手填地址；具体默认地址以文档站对应 provider 页为准。
六、安装部署
普通用户（三步）：
- 在 VS Code 扩展市场搜索并安装
twinny（市场页：
rjmacarthy.twinny），确认你的 VS Code ≥ 1.93； - 先把你的模型服务跑起来——比如本地启动 Ollama 并
ollama pull一个模型； - 回到 VS Code，twinny 首次启动会探测常用端口上的模型服务，并问你用哪个模型做补全、哪个做聊天；然后直接开始敲代码，补全会以幽灵文本出现，侧边栏是聊天。
团队网关（可选）：
# 在装着模型的那台机器上一键起网关
npx twinny-server quickstart这条命令会自动发现你的模型服务、写好配置、生成一个管理员 Key 并开始服务。之后在管理页设置团队默认模型、给每位开发者发邀请链接（点开即自动在 VS Code 里连上网关），并查看每人/每模型的用量。
七、配置项说明
twinny 的配置重心是"选哪个模型服务、哪个模型干什么活"：
| 配置项 | 说明 |
|---|---|
| 补全模型（completion） | 用于幽灵文本补全，建议用小而快的模型（官方针对 7B 调校）；Mistral 系可用 Codestral |
| 聊天模型（chat） | 用于侧边栏对话与 agent，可换更强的托管模型 |
| 模型服务地址 | 本地服务（Ollama/LM Studio/llama.cpp）首次自动发现；手动填时按 OpenAI 兼容地址格式 |
| API Key | 接托管 API 时填对应 Key；纯本地服务不需要 |
| Devices 配对码 | 接另一台机器的 GPU 时，用配对码加密直连，无账号、无中转 |
| 工作区索引 | 用 Embeddings 标签页管理；从旧版基于名字的索引升级后，需手动重建一次 |
官方强调可以混用："a local model for completion, a hosted one for chat"——补全走本地、聊天走云端，两边互不影响。
关于隐私：README 反复强调"No telemetry, no sign-in"（无遥测、免登录），并把"模型跑在哪、数据去哪"这件事完全交给你选。接本地 Ollama 时代码上下文不出本机；接托管 API 时则按那家服务商的隐私政策处理。状态条、日志与隐私边界在文档站"Status bar, logs and privacy"一页有专门说明。
八、使用流程
- 装好扩展、跑起模型，首次让 twinny 选好补全/聊天模型；
- 写代码：正常敲字，补全以灰色幽灵文本出现，接受按
Tab类常用键，在合理处自动停； - 改代码：选中一段按
Ctrl+I，用自然语言描述改动，看 diff 逐块接受/拒绝； - 问代码：打开侧边栏聊天，用
@附加文件、git diff、终端内容等； - 让它干活（实验）：聊天里切到 Agent 模式或按
Shift+Tab，它会自己读文件、搜索、改文件、跑命令，每步都展示，执行命令前先问你； - 提交前：让它评审工作区改动、基于暂存 diff 生成提交信息；
- 终端里：用自然语言生成命令，先预览再执行；失败了它会定位到文件行并给修复建议。
九、常用运维 / 更新命令
# 普通用户：在 VS Code 扩展面板里更新 twinny（或等自动更新）
# 团队网关：一键快速启动（自动发现模型服务并写配置）
npx twinny-server quickstart
# 升级后重建工作区索引（从旧版基于名字的索引存储升级时，在 Embeddings 标签页重建一次）
# 官方说明：现有索引不会被自动删除，需手动重建一次
# 开发者跑测试（仓库 CONTRIBUTING）
xvfb-run -a npm test十、常见故障排查
| 现象 | 原因与处理 |
|---|---|
| 完全没有幽灵补全 | 模型服务没起来，或 twinny 没选中补全模型；先确认 Ollama/LM Studio 在跑、模型已 pull，再在扩展设置里指定补全模型 |
| 找不到本地模型 | 首次启动只自动探测常用端口；若你改了端口，手动在 provider 设置里填地址；文档站 troubleshooting 页逐条列了报错含义 |
| 聊天能用、补全不出来 | 补全模型与聊天模型是分开配的；补全建议用快的 7B 模型，别把补全指向一个很慢的大模型 |
| Agent 模式不执行命令 | 它默认"先问你再执行"；按提示确认即可，或按官方说明放开自动执行 |
| 升级后索引不对 | 从旧版名字索引升级后，在 Embeddings 标签页手动重建一次索引 |
| 团队网关连不上 | 先在网关那台机器上跑通
npx twinny-server quickstart，再用管理页发的邀请链接让开发者接入 |
| 担心上传代码 | twinny 无遥测、免登录，数据只发你自己选的模型服务；接纯本地模型时代码不出本机，可对照文档站隐私说明自查 |
十一、风险与责任使用声明
- 本文要求（VS Code
1.93+）、快捷键（
Ctrl+I、Shift+Tab）、命令（npx twinny-server quickstart、xvfb-run -a npm test）、支持的模型服务清单均来自官方 README 与文档站； - twinny 是本地/自托管工具，模型推理产生的费用（接托管 API 时）由你与模型服务商结算；本地模型则占用你自己的显卡与电力；
- Agent 模式为实验性功能，会读、写文件并可执行命令，请在确认每一步操作后再放行，重要改动建议先 git 提交留底；
- 团队网关的插件、策略、审计、录制等高级能力属于付费许可；个人本地使用免费。项目以 MIT 许可证"按现状"提供，使用风险自负，本文不托管、不代理 twinny。