# CodeDrop

**Repository Path**: dreamszhu/CodeDrop

## Basic Information

- **Project Name**: CodeDrop
- **Description**: 将 ChatGPT 生成的代码直接写入本地项目文件的 Chrome 浏览器扩展。
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## CodeDrop

将 ChatGPT / DeepSeek 生成的代码直接空投到本地项目文件的 Chrome 浏览器扩展。

### 项目目标

让 AI 聊天界面变成本地项目的编程 Agent。用户在 ChatGPT 或 DeepSeek 中对话，AI 不仅能给出建议，还能通过扩展自动浏览项目目录、读写文件、搜索编辑删除、执行 Shell 命令——形成完整的 AI 编程助手闭环。

核心理念：

- AI 是"大脑"，负责理解需求和生成代码
- Chrome 扩展是"手"，负责在页面上检测指令、执行操作、回传结果
- 本地桥接服务器是"通道"，打通浏览器沙箱与本地文件系统之间的隔阂
- 整个过程对用户透明——输入需求，AI 自动完成，无需手动复制粘贴

### 系统架构

```
┌──────────────────────────────────────────────────────┐
│                   AI 聊天页面                         │
│              (ChatGPT / DeepSeek)                    │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │            Chrome 扩展 Content Script           │  │
│  │                                                │  │
│  │  detector.ts        → 检测 codedrop 围栏块     │  │
│  │  ui.ts              → 渲染任务卡片              │  │
│  │  agent-loop.ts      → 自动执行工具并回传结果    │  │
│  │  api-interceptor.ts → 拦截 SSE 流检测响应完成   │  │
│  │  context.ts         → Agent 系统提示词生成      │  │
│  │  context-button.ts  → Agent 发送按钮注入        │  │
│  │  platform.ts        → 多平台适配器              │  │
│  └─────────────────┬──────────────────────────────┘  │
│                    │ chrome.runtime.sendMessage      │
│  ┌─────────────────▼──────────────────────────────┐  │
│  │         Chrome 扩展 Background Worker           │  │
│  │  消息路由、路径解析（resolvePath）、API 调用     │  │
│  └─────────────────┬──────────────────────────────┘  │
└────────────────────┼─────────────────────────────────┘
                     │ HTTP (localhost:19876)
┌────────────────────▼─────────────────────────────────┐
│              本地桥接服务器 (Node.js)                  │
│  文件系统读写 API + Token 认证 + 目录白名单           │
│  validatePath() 强制所有操作限制在项目目录内          │
└──────────────────────────────────────────────────────┘
```

### codedrop 协议

AI 通过输出特殊的 fenced code block 来调用工具，格式如下：

~~~
```codedrop
tool: list_dir | read_file | search_files | edit_file | delete_file | read_multiple_files | run_command | rename_file | mkdir | write_file
path: 相对路径
```
~~~

支持的 10 个工具：

| 工具 | 用途 | 额外参数 |
|------|------|----------|
| `list_dir` | 列出目录内容 | — |
| `read_file` | 读取单个文件 | — |
| `search_files` | 在目录中搜索文件内容 | `pattern:`, `file_pattern:`（可选） |
| `read_multiple_files` | 批量读取多个文件 | `path:` 可出现多次 |
| `run_command` | 在项目目录内执行 Shell 命令 | `command:`，`path:` 通常为 `.` |
| `rename_file` | 重命名/移动文件或目录 | `to:` 目标路径 |
| `mkdir` | 创建目录（递归） | — |
| `edit_file` | 查找替换编辑文件 | `search:`, `replace:` |
| `delete_file` | 安全删除文件（移到 .codedrop-trash） | — |
| `write_file` | 写入/创建文件 | 紧跟代码块作为内容 |

对于 `write_file`，紧跟其后需要一个普通代码块作为文件内容：

~~~
```codedrop
tool: write_file
path: src/utils/logger.ts
```
```typescript
export function createLogger(name: string) { ... }
```
~~~

对于 `search_files`，需要指定搜索模式：

~~~
```codedrop
tool: search_files
path: src
pattern: TODO|FIXME
file_pattern: *.ts
```
~~~

对于 `edit_file`，需要指定搜索和替换内容：

~~~
```codedrop
tool: edit_file
path: src/app.ts
search: oldFunction()
replace: newFunction()
```
~~~

对于 `run_command`，指定要执行的命令（在项目目录内运行）：

~~~
```codedrop
tool: run_command
command: npm run build
path: .
```
~~~
- 超时限制 30 秒，输出截断到 10KB
- 危险命令（rm -rf /、mkfs 等）被安全策略拒绝
- 需要用户在 UI 上手动确认执行

对于 `rename_file`，需要指定源路径和目标路径：

~~~
```codedrop
tool: rename_file
path: src/oldName.ts
to: src/newName.ts
```
~~~

对于 `mkdir`，指定目录路径即可（自动递归创建中间目录）：

~~~
```codedrop
tool: mkdir
path: src/components/auth
```
~~~

扩展通过三种方式识别 codedrop 块（优先级从高到低）：

1. `<code>` 元素上有 `language-codedrop` CSS 类
2. 代码块容器上显示 "codedrop" 语言标签
3. 代码内容中包含 `tool: xxx` 元数据格式（最可靠，不依赖渲染器的语言识别）

### Agent 模式

Agent 模式让 AI 能够自主探索项目结构并执行操作。工作流程：

1. 用户在输入框中输入需求（如"遍历项目目录"）
2. 点击「🤖 Agent 发送」按钮，扩展将 Agent 系统提示词（含项目目录树 + 10 个工具定义 + 调用规则）与用户输入合并为一条消息发送
3. AI 收到完整的 Agent 指令后，以 codedrop 格式回复工具调用
4. 扩展检测到读取类工具（`list_dir` / `read_file` / `search_files` / `read_multiple_files`）后自动执行，并将结果回传给 AI；写入与执行类工具（`write_file` / `edit_file` / `delete_file` / `rename_file` / `mkdir` / `run_command`）需用户在任务卡片上手动确认
5. AI 根据结果继续下一步操作，形成闭环

Agent Loop 双路径检测机制：

```
路径 1（DOM）：
  MutationObserver / 定时扫描 → detector 标记 pre[data-codedrop-task] →
  agent-loop 遍历所有待执行任务 → 自动执行 read 类工具 →
  构建 [Tool Result] 消息 → 插入输入框 → 触发发送

路径 2（API 拦截，ChatGPT + DeepSeek）：
  页面 fetch 拦截 → 读取 SSE 流 → 累积完整响应文本 →
  解析 codedrop 块 → 直接执行（跳过 DOM 依赖）
```

两条路径共享 `executedToolPaths` Set 进行去重，确保同一工具不会被执行两次。

设计要点：

- 重入锁（`isRunning`）防止并发执行
- `executedTaskIds` Set 防止重复执行同一任务
- `executedToolPaths` Set 在 DOM 和 API 两条路径间去重
- Agent Loop 直接从 `<pre data-codedrop-task="true">` 元素解析元数据，不强依赖任务卡片 DOM
- API 拦截路径绕过 `isResponseComplete()` 检测，直接以 `apiFinished=true` 触发

### 多平台适配

`platform.ts` 作为平台适配层，抽象了 ChatGPT 和 DeepSeek 之间的差异：

| 能力 | ChatGPT | DeepSeek |
|------|---------|----------|
| 助手消息选择器 | `[data-message-author-role="assistant"]` | `div[class*="_4f9bf79"]`（哈希类名，可能变化） |
| 输入框 | `contenteditable` + `execCommand('insertText')` | `textarea` + `nativeInputValueSetter`（React 状态） |
| 发送按钮 | 查找 `aria-label` 含 Send/发送 | 查找按钮 + SVG 箭头回退 |
| 流式检测 | `[class*="result-streaming"]` | `[class*="generating"]` / `[class*="typing"]` |
| API 拦截 | 拦截 `/backend-api/f/conversation` SSE 流 | 拦截 `/api/v0/chat/completion` SSE 流 |

### 目录结构

```
openai-work/
├── extension/                      # Chrome 扩展源码
│   ├── manifest.json               # MV3 清单
│   ├── icons/                      # 扩展图标（16/48/128px）
│   └── src/
│       ├── background/
│       │   └── index.ts            # Service Worker：消息路由、路径解析、API 调用
│       ├── content/
│       │   ├── index.ts            # 入口：扫描循环、MutationObserver、API 拦截注入
│       │   ├── detector.ts         # codedrop 块检测：解析元数据（10 种工具）、生成 TaskBlock
│       │   ├── ui.ts               # 任务卡片 UI：自动执行读取 / 手动执行写入 / 确认操作
│       │   ├── agent-loop.ts       # Agent 闭环：双路径检测、自动执行工具并回传结果
│       │   ├── api-interceptor.ts  # ChatGPT / DeepSeek 双平台 SSE 流拦截（页面级 fetch hook）
│       │   ├── context.ts          # Agent 系统提示词生成 + 目录树构建
│       │   ├── context-button.ts   # Agent 发送按钮注入
│       │   ├── platform.ts         # 多平台适配器（ChatGPT / DeepSeek）
│       │   └── styles.css          # 注入页面的样式
│       ├── popup/
│       │   ├── popup.ts            # 弹出页面逻辑（配置服务器、管理项目）
│       │   ├── popup.css           # Popup 样式
│       │   └── index.html          # Popup HTML 模板
│       └── shared/
│           ├── types.ts            # 共享类型定义
│           ├── constants.ts        # 常量（存储 key、选择器、端口）
│           └── api.ts              # 桥接服务器 API 客户端（10 个工具方法）
├── bridge-server/                  # 本地桥接服务器源码
│   ├── package.json
│   ├── tsconfig.json
│   └── src/
│       ├── index.ts                # 入口
│       ├── server.ts               # HTTP 服务器（12 个 API 路由）
│       ├── handlers.ts             # 请求处理器（文件读写、搜索、编辑、删除、重命名、创建目录、命令执行等）
│       ├── security.ts             # Token 认证、目录白名单校验（validatePath）
│       └── types.ts                # 服务端类型
├── package.json                    # 根项目配置
├── webpack.config.js               # Webpack 5 构建配置（3 个入口）
├── tsconfig.json                   # TypeScript 配置
└── launch-test-chrome.bat          # 启动测试 Chrome 的脚本
```

### 构建与运行

```bash
# 安装依赖
npm install
cd bridge-server && npm install && cd ..

# 构建扩展（输出到 dist/）
npm run build

# 开发模式（监听文件变化自动构建）
npm run dev

# 启动桥接服务器
npm run start:server

# 开发模式服务器（带热重载）
npm run dev:server
```

构建完成后，在 `chrome://extensions/` 中加载 `dist/` 目录即可使用。

### 安全设计

- 桥接服务器仅监听 `127.0.0.1`，不暴露到外网
- Bearer Token 认证防止未授权访问
- 双层路径校验：扩展端 `resolvePath()` 解析相对路径 → 桥接端 `validatePath()` 验证目录白名单
- 目录白名单（`allowedDirs`）限制可访问的文件范围
- 写入文件前自动备份原文件到 `.codedrop-backup/`
- 删除文件安全移至 `.codedrop-trash/`，可手动恢复
- 所有 10 个工具的文件与命令操作均受路径白名单约束（`run_command` 工作目录强制为项目根目录，并通过命令黑名单拦截危险模式如 `rm -rf /`、`mkfs`、`dd if=` 等）

### 技术栈

Chrome Extension Manifest V3、TypeScript、Webpack 5、Node.js（原生 http 模块）