CodeBridge — 网页 AI × 本地文件系统的桥接系统
CodeBridge 打破网页大模型（Gemini、DeepSeek、Claude、Kimi、豆包、通义千问等）与本地文件系统之间的壁垒。
通过在浏览器中运行的用户脚本（Tampermonkey）+ 本地后台服务（Python HTTP Server），CodeBridge 让网页版 AI 直接读取本地代码、修改文件、执行终端命令 —— 将网页 AI 转化为全自动本地编程助手。
核心特性
- 统一适配器基座 —
codebridge/ 14+ ES 模块 + ESBuild 打包，SITE_ADAPTERS 覆盖 8 个 AI 平台，URL 自动切换
- 丰富的命令集
- 读取/搜索：
# 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 连接
- 自动回复闭环 — 开启后，执行结果自动填入输入框反馈给 AI，实现无人值守多轮迭代
- 提示词动态热更新 — 脚本从服务端 API 拉取最新
prompt.md，改提示词无需改脚本
- 人性化 UI — 可拖拽工具栏、侧边日志面板、Toast 通知、按钮状态动画
- 多层安全 — PowerShell ConstrainedLanguage 引擎级保护 + SQL 危险语句拦截 +
--read-before-edit 防止未读就改 + 路径沙箱
- 模块化开发 — ESBuild bundle，
el() HTML→DOM 工具，npm run build 一键打包
- 通用模板 + 脚手架 —
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. 服务端
# 安装依赖
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. 油猴脚本
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：
{
"connections": {
"default": {
"host": "localhost",
"port": 3306,
"user": "root",
"password": "",
"database": "mydb"
}
}
}
然后对话中使用 # SQL: 命令。
4. 开始对话
- 打开任意支持的 AI 平台（Gemini、DeepSeek、Kimi、豆包、通义千问等）
- 点击右下角工具栏 📝 注入提示词
- 给 AI 下发指令：「帮我看一下项目结构」「读 package.json」「跑一下测试」
支持的平台
命令速查
| 命令 |
格式 |
说明 |
# 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 时捕获默认值的问题）。
模板脚手架
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 |
模板使用指南 |
