# codeBridge

**Repository Path**: liu_rui_qi/code_bridge

## Basic Information

- **Project Name**: codeBridge
- **Description**: 基于 http的"浏览器-本地"桥接系统，让 Gemini 网页版拥有操作本地文件系统和执行终端命令的能力。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-03-18
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeBridge — 网页 AI × 本地文件系统的桥接系统

CodeBridge 打破**网页大模型**（Gemini、DeepSeek、Claude、Kimi、豆包、通义千问等）与**本地文件系统**之间的壁垒。

通过在浏览器中运行的用户脚本（Tampermonkey）+ 本地后台服务（Python HTTP Server），CodeBridge 让网页版 AI 直接读取本地代码、修改文件、执行终端命令 —— 将网页 AI 转化为**全自动本地编程助手**。

## 核心特性

1. **统一适配器基座** — `codebridge/` 14+ ES 模块 + ESBuild 打包，`SITE_ADAPTERS` 覆盖 8 个 AI 平台，URL 自动切换
2. **丰富的命令集**
   - 读取/搜索：`# READ:`、`# READ_RANGE:`、`# OUTLINE:`（tree-sitter AST 精度）、`# SEARCH:`（结构化输出）、`# LOCATE:`、`# TREE:`、`# FILE_STATS:`
   - 写入：`# FILE:` 全量写入、`# REPLACE:` 增量替换（行号 / SEARCH 两种模式，支持 `--all` 全局替换）、`# DELETE:` 删除、`# INSERT:` 插入
   - 撤销/查看：`# ROLLBACK:` 快照回滚、`# DIFF:` git diff 变更查看
   - 执行：`# POWERSHELL:` PowerShell 命令（CLM 引擎保护）
   - 数据库：`# SQL:` SQL 查询（MySQL CLI，危险语句拦截）、`# DBLIST` 列出连接、`# REDIS:` Redis 命令、`# REDISLIST` 列出 Redis 连接
3. **自动回复闭环** — 开启后，执行结果自动填入输入框反馈给 AI，实现无人值守多轮迭代
4. **提示词动态热更新** — 脚本从服务端 API 拉取最新 `prompt.md`，改提示词无需改脚本
5. **人性化 UI** — 可拖拽工具栏、侧边日志面板、Toast 通知、按钮状态动画
6. **多层安全** — PowerShell ConstrainedLanguage 引擎级保护 + SQL 危险语句拦截 + `--read-before-edit` 防止未读就改 + 路径沙箱
7. **模块化开发** — ESBuild bundle，`el()` HTML→DOM 工具，`npm run build` 一键打包
8. **通用模板 + 脚手架** — `userscript-template/` 可复用的油猴脚本模板，支持 `npm link` 一键创建新项目

## 项目结构

```
CodeBridge/
├── src/
│   ├── script/
│   │   ├── codebridge/              # ★ 模块化开发源（14+ ES 模块）
│   │   │   ├── index.js             #   IIFE 入口
│   │   │   ├── core.js              #   init() 编排
│   │   │   ├── commands.js          #   命令注册表 + 代码块解析
│   │   │   ├── network.js           #   HTTP 通信 + 心跳
│   │   │   ├── inject.js            #   按钮注入 + 提示词注入
│   │   │   ├── observer.js          #   MutationObserver DOM 监听
│   │   │   ├── ui.js                #   工具栏 / Toast / 日志面板
│   │   │   ├── html.js              #   el() HTML→DOM（6 行）
│   │   │   ├── config.js            #   配置常量 + 全局状态
│   │   │   ├── styles.css           #   CSS 样式（ESBuild text loader 导入）
│   │   │   ├── build.js             #   ESBuild 构建脚本
│   │   │   ├── header.txt           #   UserScript 元数据
│   │   │   ├── adapters/            #   站点适配器（8 个平台）
│   │   │   └── package.json         #   npm build/watch 脚本
│   │   ├── userscript-template/     # ★ 通用油猴脚本模板 + 脚手架
│   │   │   ├── bin/cli.js           #   脚手架（node bin/cli.js my-project）
│   │   │   ├── example.js           #   示例业务代码
│   │   │   └── ...                  #   html / config / styles / network / observer / ui
│   │   └── universal/               # 构建产物（油猴直接加载）
│   │       └── tampermonkey.js      #   ESBuild 打包后的单文件
│   └── server/                      # Python HTTP 服务端
│       ├── server.py                #   主入口
│       ├── cli.py                   #   命令行参数解析（config 对象，动态取值）
│       ├── utils.py                 #   工具函数 + 路径安全
│       ├── security.py              #   语法检查（Python AST / JS / JSON）
│       ├── logger.py                #   日志（延迟初始化，支持 --log-level）
│       ├── utils_snapshot.py        #   快照管理（PATCH 前置自动备份）
│       ├── handlers/                #   命令处理器
│       │   ├── dispatcher.py        #     action → handler 路由
│       │   ├── file.py              #     文件读写 / Patch / Rollback / Diff
│       │   ├── exec.py              #     PowerShell 执行（ConstrainedLanguage）
│       │   ├── search.py            #     搜索 / 目录树 / 大纲
│       │   ├── outline.py           #     tree-sitter AST 大纲提取
│       │   ├── sql_handler.py       #     SQL 查询 + 安全拦截
│       │   └── redis_handler.py     #     Redis 命令 + 安全拦截
│       ├── prompts/                 #   ★ 提示词（动态下发）
│       │   ├── prompt.md            #     主提示词
│       │   └── prompt_short.md      #     精简版提示词
│       └── tools/                   #   代码校验工具
├── doc/                             # 文档 / 设计 / 分析
│   ├── db-json-example.json         #   数据库连接配置模板
├── test/                            # 测试文件（91 个单元测试）
├── start.ps1                        # PowerShell 启动脚本
├── CodeBridge.bat                   # CMD 启动脚本
└── README.md
```

## 快速开始

### 1. 服务端

```bash
# 安装依赖
pip install -r src/server/requirements.txt

# 启动（项目目录作为位置参数，其他参数可默认）
python src/server/server.py /path/to/your/project

# 完整参数
python src/server/server.py /path/to/project \
  --port 8765 \
  --timeout 120 \
  --log-level DEBUG \
  --tree-depth 3 \
  --snapshot-dir /path/to/snapshots \
  --read-before-edit strict \
  --skip-syntax py,java \
  --only-syntax py
```

**命令行参数：**

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `project_dir` | (必需) | 项目根目录 |
| `--port` | 8765 | HTTP 服务端口 |
| `--timeout` | 60 | 命令执行超时秒数 |
| `--log-level` | INFO | 日志级别 (DEBUG/INFO/WARNING/ERROR) |
| `--tree-depth` | 2 | 目录树默认展开深度 |
| `--snapshot-dir` | .codebridge | 快照存储目录 |
| `--read-before-edit` | once | 修改前检查读取: strict=每次修改后需重读 / once=读过即放行 / off=不检查 |
| `--skip-syntax` | — | 跳过指定语言的语法检查 |
| `--only-syntax` | — | 仅检查指定语言的语法 |

### 2. 油猴脚本

```bash
cd src/script/codebridge
npm install && npm run build
# 产物: ../universal/tampermonkey.js
npm run watch   # 监听模式
```

构建后，将 `src/script/universal/tampermonkey.js` 复制到 Tampermonkey 新脚本。

### 3. 数据库连接（可选）

在项目根目录创建 `.codebridge/db.json`：

```json
{
  "connections": {
    "default": {
      "host": "localhost",
      "port": 3306,
      "user": "root",
      "password": "",
      "database": "mydb"
    }
  }
}
```

然后对话中使用 `# SQL:` 命令。

### 4. 开始对话

1. 打开任意支持的 AI 平台（Gemini、DeepSeek、Kimi、豆包、通义千问等）
2. 点击右下角工具栏 **📝 注入提示词**
3. 给 AI 下发指令：「帮我看一下项目结构」「读 package.json」「跑一下测试」

### 支持的平台

| 平台 | URL |
|------|-----|
| Gemini | gemini.google.com |
| DeepSeek | chat.deepseek.com |
| Kimi | www.kimi.com |
| 豆包 | www.doubao.com |
| 通义千问 | www.qianwen.com |
| 智谱清言 | chatglm.cn |
| Claude | claude.ai |
| AI Studio | aistudio.google.com |

## 命令速查

| 命令 | 格式 | 说明 |
|------|------|------|
| `# READ:` | `# READ: <路径>` | 读取完整文件（修改前必经之路） |
| `# READ_RANGE:` | `# READ_RANGE: <路径> N-M` | 读取指定行范围 |
| `# OUTLINE:` | `# OUTLINE: <路径>` | AST 精确大纲（Class/Function/Method/Interface+嵌套） |
| `# SEARCH:` | `# SEARCH: [--files] [--max N] <正则>` | 全局搜索 |
| `# LOCATE:` | `# LOCATE: <路径> [N-M] <正则>` | 单文件搜索 |
| `# TREE:` | `# TREE: [路径]` | 目录树 |
| `# FILE_STATS:` | `# FILE_STATS: <路径>` | 文件信息 |
| `# FILE:` | `# FILE: <路径>` | 全量写入/重写文件 |
| `# REPLACE:` | `# REPLACE: <路径> [--all]` | 替换（行号 / SEARCH 两种模式，--all 全局） |
| `# DELETE:` | `# DELETE: <路径> [--all]` | 删除（行号 / 文本匹配，--all 全局） |
| `# INSERT:` | `# INSERT: <路径>` | 插入（AFTER / BEFORE N） |
| `# ROLLBACK:` | `# ROLLBACK: <路径> [时间戳]` | 回滚到快照版本 |
| `# DIFF:` | `# DIFF: [路径] [--staged]` | 查看 git diff 变更 |
| `# POWERSHELL:` | `# POWERSHELL: <命令>` | 执行 PowerShell（CLM 保护） |
| `# SQL:` | `# SQL: [@连接名]` | SQL 查询（下一行起为 SQL 语句） |
| `# DBLIST` | `# DBLIST` | 列出数据库连接 |
| `# REDIS:` | `# REDIS: [@连接名]` | Redis 命令（下一行起为命令） |
| `# REDISLIST` | `# REDISLIST` | 列出 Redis 连接 |

## 安全机制

| 层面 | 措施 |
|------|------|
| **PowerShell** | ConstrainedLanguage 引擎级保护 + Restricted 执行策略 |
| **CMD** | 已禁用（无执行策略/AMSI/审计保护） |
| **SQL** | DROP / TRUNCATE / ALTER / GRANT / REVOKE 危险语句拦截 |
| **文件** | 路径沙箱（safe_resolve 防穿越）+ `--read-before-edit` 防未读即改 |
| **语法** | PATCH 前 AST 编译检查，语法错误回滚 |
| **快照** | PATCH 前置自动备份，支持 `# ROLLBACK:` 回滚 |

## 开发指南

### 模块化开发（codebridge/）

```
codebridge/
├── index.js        # IIFE 入口
├── core.js         # init() 编排
├── commands.js     # ★ 命令注册表（新增命令从这里开始）
├── network.js      # HTTP + 心跳
├── inject.js       # 按钮 + prompt 注入
├── observer.js     # MutationObserver
├── ui.js           # 工具栏 / Toast / 日志面板
├── html.js         # el() — HTML 字符串 → DOM
├── config.js       # 配置 + 状态
├── styles.css      # CSS 样式（ESBuild loader: text）
└── adapters/       # ★ 站点适配器（新增平台从这里开始）
```

### 新增命令

在 `commands.js` 的 `COMMANDS` 数组追加一项，同时在服务端 `handlers/dispatcher.py` 的 `ACTION_HANDLERS` 中注册对应 handler。

### 新增站点适配器

在 `adapters/default.js` 追加一个 export，然后在 `adapters/index.js` 的 `SITE_ADAPTERS` 中注册。复杂站点可独立文件。

### 配置系统

`cli.py` 使用 `SimpleNamespace` 对象存储全局配置，其他模块通过 `from cli import config` 获取动态值（不会出现 import 时捕获默认值的问题）。

### 模板脚手架

```bash
cd src/script/userscript-template
npm link
create-userscript ~/my-script --name "我的脚本" --match "https://example.com/*"
cd ~/my-script && npm run build
```

## 文档

| 文件 | 说明 |
|------|------|
| `doc/tampermonkey_adapter_tutorial.md` | 适配器开发教程 |
| `doc/search-commands-vs-claude-code-grep-glob.md` | SEARCH vs Claude Code Grep/Glob 对比 |
| `doc/claude-code-edit-tool-analysis.md` | Claude Code Edit 工具分析 |
| `doc/powershell-ast-security-analysis.md` | PowerShell AST 安全方案 |
| `doc/skills-system-for-web-assistant.md` | Skills 系统网页适配方案 |
| `doc/multi-workspace-design.md` | 多工作目录管理设计 |
| `doc/db-json-example.json` | 数据库连接配置模板 |
| `src/script/codebridge/README.md` | codebridge 模块化开发文档 |
| `src/script/userscript-template/README.md` | 模板使用指南 |