kcode

kcode 是一款基于 Chrome Manifest V3 的 Side Panel 扩展，它通过在一个持续运行的 v86 Alpine Linux 虚拟机中执行受限工具调用，为已登录的网页版 AI 聊天服务（如 ChatGPT, Claude, Gemini, DeepSeek 等）提供了安全、隔离的代码执行环境。

其核心理念是：AI 只能操作用户明确授权的目录，且所有危险操作均需经过严格审批。

核心架构与安全模型

1. 隔离的执行环境 (v86 VM)

• 轻量级虚拟化：使用 v86 在浏览器内运行一个 Alpine Linux VM。
• 9P 文件系统挂载：用户选定的本地目录仅通过 9P 协议挂载到 VM 的 /work 目录。AI 无法访问 VM 之外的任何文件系统。
• 状态复用与销毁：在同一工作目录、网络和内存配置下，连续的工具调用会复用同一个 VM 实例，保留 Shell 工作目录和环境变量。一旦停止、超时或配置变更，VM 会被立即销毁，确保环境纯净。

2. 严格的权限控制

• 默认 confirm-each：每次工具调用、文件变更和结果发送都需要用户手动确认。
• 三种执行模式：
  • 手动：每一步都需确认。
  • 自动写入：自动执行文件读写和提交，但 Shell 命令仍需批准。
  • 全自动：跳过逐步批准（仅限当前会话授权的工作目录）。
• 网络隔离 (WISP)：联网功能需要用户单独配置并确认一个严格的 wss:// WISP 中继 URL。该中继仅允许出站 TCP 连接到特定端口（80, 443, 9418, 22），拒绝直接 IP、私有地址和 UDP。

3. 支持的 AI 平台

kcode 通过内容脚本注入到以下站点的 Side Panel 中工作：

• DeepSeek, 通义千问 (Qwen), Google AI Studio, ChatGPT, HIX.AI, Gemini.
• 注意：扩展不修改提供商的原生系统提示词，而是将自定义 Agent 指令附加到第一条受控消息中。

安装与使用

前提条件

• Node.js 22.12+
• Chrome 116+
• Docker/Podman（仅在重新生成 VM 资源时需要）

快速开始

1. 克隆与构建：

   git clone <repo-url>
   cd kcode
   npm ci
   npm run build
   

   此过程使用仓库中已锁定的 public/v86/ 资源，无需 Docker。

2. 加载扩展：
   • 打开 Chrome chrome://extensions。
   • 启用“开发者模式”。
   • 点击“加载已解压的扩展程序”，选择 dist/ 目录。
3. 启动任务：
   • 登录任一支持的 AI 网站。
   • 从扩展图标菜单打开 kcode Side Panel。
   • 选择工作目录，配置执行模式和网络（如需）。
   • 在 AI 聊天框中输入指令，AI 将通过 kcode 调用工具完成任务。

示例成果

仓库 assets/ 中包含了一个由 kcode 端到端生成的现代极简五子棋游戏 (index.html)，具备木质棋盘、拟物棋子、悔棋功能及本地持久化统计。

高级配置与维护

重新生成 VM 资源 (维护者)

如果需要更新客体系统或固定 v86 资源：

npm run assets:rebuild

这需要 Docker 环境，会重新构建内核/initramfs 并进行深入安全检查。

工作记录与恢复

• 会话历史：启用后，脱敏的任务记录存入 .session/kcode-history.sqlite。
• 断点恢复：浏览器重启后可选择“恢复上次任务”，但不会自动发送，需用户手动触发。
• 安全边界：Auto 模式、WISP 网络、VM 进程和未提交事务在重启后不会恢复，必须重新授权。

WISP 中继部署

kcode 不提供公共中继。用户需自行部署或使用可信的中继。仓库 deploy/wisp/ 提供了一个小型 Docker 模板，限制出站连接以确保安全。

⚠️ 限制与注意事项

• 文件系统：不支持符号链接、硬链接和设备文件。
• 网络：不支持原始套接字、UDP 或入站连接。
• 任务轮次：单次任务最多支持 20 轮工具调用。
• 物理擦除：不提供可靠的物理数据擦除保证。
• UI 交互：如果页面控件存在歧义或变动，扩展会停止操作而非猜测点击，确保安全性。