内容
# AgentClip
将选定的浏览器文本 — 通过确认/编辑步骤 — 保存到 Cloudflare 的个人存储中，然后通过**AI 代理（MCP）**和工具使用每个用户令牌认证的 **REST API** 进行检索。
- **代理** — AI 客户端通过 MCP / REST 使用每个用户令牌访问您的剪辑。
- **剪辑** — Chrome 扩展（Manifest V3）添加了“保存到 AgentClip”上下文菜单；您可以编辑文本，然后再保存。
生产环境作为**单个 Cloudflare Worker** 在 `https://agentclip.0xkaz.com` 运行，提供 API、MCP 服务器、Google OAuth 和仪表板。
- **在线应用：** https://agentclip.0xkaz.com
- **源码：** https://github.com/0xkaz/agentclip
- **日语版 README：** [README.ja.md](README.ja.md)
## 功能
- **剪辑和编辑** — 右键单击任意选择 → 编辑内容/标题/标签/来源 → 保存。
- **关键词搜索** — 内容/标题/标签的子字符串匹配（也适用于日语）。
- **语义搜索** — 基于 Workers AI 嵌入 + Vectorize 的含义搜索。
- **每个剪辑加密** — 标记剪辑以加密保存；加密剪辑不参与搜索（显示为掩码，有显示切换）。
- **分享链接** — 在公共只读 `/s/<slug>` URL 上发布单个剪辑；随时撤销（加密剪辑不能分享）。
- **MCP + REST** — AI 代理和工具使用每个用户令牌读写剪辑。
- **Google 登录** 用于仪表板；不透明的每个用户 Bearer 令牌用于机器。
## 使用托管应用
最快捷的方式 — 无需本地设置：
1. 打开 **https://agentclip.0xkaz.com** 并 **使用 Google 登录**。
2. 进入 **API 令牌** → 创建令牌（`ac_live_…`，仅显示一次 — 复制它）。
3. 在应用中打开 **设置和使用** — 显示您的确切 MCP 配置和 `curl` 示例，以及下面的 Chrome 扩展步骤。
仪表板有三个页面：
| 页面 | 功能 |
|------|--------------|
| **代码片段** | 浏览、添加/编辑/删除、关键词和语义搜索您的剪辑 |
| **API 令牌** | 创建/撤销每个用户的 Bearer 令牌 |
| **设置和使用** | 复制粘贴 MCP 配置、REST `curl` 和扩展设置 |
## 单体仓库布局
```
apps/api Cloudflare Worker — REST + MCP + Google OAuth, D1, 提供仪表板
apps/web React + Vite 仪表板 — 登录页面 + 代码片段 / 令牌 / 设置
apps/extension Chrome MV3 扩展 — 捕获 + 确认/编辑
packages/shared 共享 TypeScript 类型
```
本 README 的其余部分涵盖了自行运行和部署。要求：**Node 20+**，**pnpm 9+**（`npm i -g pnpm`），Cloudflare 账户和 Google OAuth 客户端。
---
## 1. 克隆和安装
```sh
git clone https://github.com/0xkaz/agentclip.git
cd agentclip
pnpm install # 或：make install
```
## 2. 配置 Cloudflare D1
```sh
pnpm --filter @agentclip/api exec wrangler d1 create agentclip
```
将返回的 `database_id` 粘贴到 `apps/api/wrangler.toml` 中的两个 `[[d1_databases]]` 块中（顶级块和 `[env.production]` 块）。
```sh
make db-init # 将 schema.sql 应用于本地 D1
# 稍后，用于生产环境：
pnpm --filter @agentclip/api db:init:remote
```
## 3. 配置 Google OAuth
在 Google Cloud 控制台 → 凭证 → 创建 **OAuth 客户端 ID（Web 应用程序）**。
添加授权重定向 URI：
- 本地：`http://localhost:8787/auth/google/callback`
- 生产环境：`https://agentclip.0xkaz.com/auth/google/callback`
然后创建本地机密：
```sh
cp apps/api/.dev.vars.example apps/api/.dev.vars
# 编辑 apps/api/.dev.vars：
# GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, SESSION_SECRET（任意 32+ 字节字符串）
```
## 4. 本地运行
```sh
make dev # API + MCP 在 http://localhost:8787
pnpm --filter @agentclip/web dev # 仪表板在 http://localhost:5173
```
打开 `http://localhost:5173`，使用 Google 登录，并创建 API 令牌。
## 5. 安装 Chrome 扩展
```sh
pnpm --filter @agentclip/extension build # 输出 apps/extension/dist
```
1. 打开 `chrome://extensions` → 启用 **开发者模式**。
2. **加载解压** → 选择 `apps/extension/dist`。
3. 点击 AgentClip 图标 → 设置 **API 基本 URL** 并粘贴仪表板中的 **令牌**。
- 本地：`http://localhost:8787`
- 生产环境：`https://agentclip.0xkaz.com`
4. 选择任意页面上的文本 → 右键单击 → **保存到 AgentClip** → 编辑 → **保存**。
## 6. 部署到生产环境（`agentclip.0xkaz.com`）
```sh
# 一次性：设置生产环境机密
pnpm --filter @agentclip/api exec wrangler secret put GOOGLE_CLIENT_ID --env production
pnpm --filter @agentclip/api exec wrangler secret put GOOGLE_CLIENT_SECRET --env production
pnpm --filter @agentclip/api exec wrangler secret put SESSION_SECRET --env production
pnpm --filter @agentclip/api db:init:remote # 远程 D1 上的 schema
make deploy # 构建仪表板，然后部署 Worker (--env production)
```
> 自定义域名路由（`agentclip.0xkaz.com`）需要 Cloudflare API 令牌在 `0xkaz.com` 上具有 **Zone:Edit** 权限，此外还需要 Workers/D1 编辑权限。没有它，部署 Worker 并从仪表板绑定域名，或使用 `*.workers.dev` URL。
---
## 使用 REST API
```sh
# 保存（添加 "encrypted": true 以加密保存 + 从搜索中排除）
curl -X POST https://agentclip.0xkaz.com/api/snippets \
-H "Authorization: Bearer ac_live_..." \
-H "Content-Type: application/json" \
-d '{"content":"hello","tags":"demo"}'
# 关键词搜索（子字符串；适用于日语）
curl "https://agentclip.0xkaz.com/api/snippets?q=hello" -H "Authorization: Bearer ac_live_..."
# 语义搜索（基于含义）
curl "https://agentclip.0xkaz.com/api/snippets?q=greeting&mode=semantic" -H "Authorization: Bearer ac_live_..."
# 更新 / 删除
curl -X PATCH https://agentclip.0xkaz.com/api/snippets/1 -H "Authorization: Bearer ac_live_..." -H "Content-Type: application/json" -d '{"content":"updated"}'
curl -X DELETE https://agentclip.0xkaz.com/api/snippets/1 -H "Authorization: Bearer ac_live_..."
```
## 使用 MCP
将 MCP 客户端指向 `https://agentclip.0xkaz.com/mcp`，并使用 `Authorization: Bearer ac_live_...` 头部。工具：`store_snippet`、`search_snippets`、`semantic_search`、`get_snippet`、`list_recent`、`update_snippet`、`delete_snippet`。
> 语义搜索会自动索引新剪辑；要索引早期创建的剪辑，请打开 **代码片段** 页面，切换到 **语义**，然后点击 **重建索引**（或 `POST /api/my/reindex`）。Vectorize 最终一致（新剪辑在约 1 分钟内变得可搜索）。
参见 [docs/architecture.md](docs/architecture.md) 和 [docs/agent-workflow.md](docs/agent-workflow.md) 以获取详细信息。
