文档代理技能
概览
文档代理负责维护 Unite-Hub 项目的准确、最新的文档：
- README.md - 项目概览、安装、使用
- .claude/claude.md - 系统概览和配置
- .claude/agent.md - 代理定义（规范）
- API 文档 - 端点参考
- 架构文档 - 系统设计文档
- 变更日志 - 版本历史和发布说明
模型配置
模型: claude-haiku-4-5-20251001
原因: 快速、成本效益高，非常适合文档任务
成本: ~$0.10-0.20 每个文档更新（与 Sonnet/Opus 的 $1-2 相比）
如何使用此代理
触发
用户说：“更新 README”、“记录新的 API 端点”、“添加变更日志条目”、“同步文档与代码”
代理的工作内容
1. 确定文档需求
要问的问题：
- 代码中有哪些变化？
- 哪些文档文件需要更新？
- 这是一个新功能、bug修复还是重构？
- 目标受众是谁（开发者、用户或两者）？
2. 阅读当前文档
步骤 A: 定位文档文件
# 查找所有 markdown 文件
find . -name "*.md" | grep -v node_modules
关键文档文件：
README.md- 主项目 README.claude/claude.md- 系统概览.claude/agent.md- 代理定义ARCHITECTURE.md- 系统架构API_DOCUMENTATION.md- API 参考DEPLOYMENT_GUIDE.md- 部署说明- 根目录下的
*.md文件（各种指南）
步骤 B: 阅读相关文件
// 使用 text_editor 工具
text_editor.view("README.md");
text_editor.view(".claude/claude.md");
3. 更新文档
步骤 A: README.md 更新
Unite-Hub 的 README 结构：
# 项目名称
简短描述（1-2 句话）
## 特性
- 特性 1
- 特性 2
- 特性 3
## 技术栈
### 前端
- Next.js 16
- React 19
- Tailwind CSS
### 后端
- Supabase
- Next.js API 路由
### AI
- Claude Opus 4
- Claude Sonnet 4.5
## 安装
逐步安装说明
## 使用方法
如何使用应用程序
## API 文档
链接到 API 文档
## 部署
部署说明
## 贡献
如何贡献
## 许可证
许可证信息
更新流程：
- 阅读当前 README
- 识别过时部分
- 更新相关部分
- 保持结构
- 保持一致的语气
步骤 B: API 文档更新
当创建新的 API 端点时：
## API 端点
### POST /api/contacts/bulk-update
**描述**：批量更新多个联系人
**认证**：需要（Supabase 认证）
**请求正文**：
```json
{
"workspaceId": "uuid",
"contactIds": ["uuid1", "uuid2"],
"updates": {
"status": "prospect",
"tags": ["warm", "interested"]
}
}
响应：
{
"success": true,
"updated": 2,
"contacts": [...]
}
错误：
400- 输入无效401- 未授权500- 服务器错误
示例：
const res = await fetch("/api/contacts/bulk-update", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
workspaceId: "...",
contactIds: ["..."],
updates: { status: "prospect" }
})
});
const data = await res.json();
**步骤 C: .claude/claude.md 更新**
在重大代码更改后：
1. **更新“当前系统状态”部分**：
- 将修复的问题从“关键问题”移动到“工作组件”
- 如果发现新问题，则添加新问题
- 更新组件计数（例如，“21 个仪表板页面” → “22 个仪表板页面”）
2. **更新“技术栈详情”部分**：
- 添加新依赖项
- 更新版本号
- 记录新集成
3. **更新“数据流分析”部分**：
- 添加新工作流
- 修复断开的流程
- 记录关键断点
4. **更新“立即下一步”部分**：
- 移除已完成的任务
- 添加新优先任务
- 重新确定剩余工作优先级
**步骤 D: .claude/agent.md 更新**
当代理更改时：
1. **添加新代理定义**：
```markdown
### 7. 新代理名称
**ID**: `unite-hub.new-agent`
**模型**: `claude-sonnet-4-5-20250929`
**技能文件**: `.claude/skills/new-agent/SKILL.md`
#### 角色
这个代理做什么
#### 能力
- 能力 1
- 能力 2
#### 可用工具
- 工具 1
- 工具 2
#### 何时调用
- 场景 1
- 场景 2
-
如果工作流程更改，则更新代理交互模式
-
如果添加了新工具，则更新工具使用指南
4. 生成变更日志条目
当代码更改发布时：
# 变更日志
## [1.1.0] - 2025-11-16
### 添加
- 新的联系人批量更新 API 端点
- 仪表板分析页面
- 热门潜在客户电子邮件发送功能
### 变更
- 更新 README，添加新的 API 文档
- 在所有页面上改进工作区过滤
### 修复
- 修复仪表板概览中缺失的工作区过滤器
- 修复 AuthContext 中的未定义组织
- 修复 src/lib/db.ts 中的缺失导入
### 安全
- 在所有 API 路由上重新启用认证
- 为新表添加 RLS 策略
变更日志类别：
- 添加：新功能
- 变更：对现有功能的更改
- 弃用：将被移除的功能
- 移除：已移除的功能
- 修复：错误修复
- 安全：安全改进
5. 更新架构图
当系统架构更改时：
基于文本的图（使用 Markdown）：
## 系统架构
┌─────────────────┐ │ Next.js 应用 │ │ (React 19 + │ │ App Router) │ └────────┬────────┘ │ ┌────┴────┐ │ │ ┌───▼───┐ ┌──▼─────────┐ │ API │ │ 仪表板 │ │路由 │ │ 页面 │ └───┬───┘ └────────────┘ │ ┌───▼────────────────┐ │ AI 代理层 │ │ • 电子邮件代理 │ │ • 内容代理 │ │ • 协调器 │ └───┬────────────────┘ │ ┌───▼────────────────┐ │ Supabase 层 │ │ • PostgreSQL │ │ • 行级安全 │ │ • 实时订阅 │ └────────────────────┘
Mermaid 图（用于复杂流程）：
## 数据流
```mermaid
graph TD
A[用户登录] --> B[OAuth]
B --> C[Supabase 认证]
C --> D[仪表板]
D --> E[加载联系人]
E --> F[显示热门潜在客户]
## 常见任务
### 任务 1: 记录新的 API 端点
**步骤**：
1. 阅读 API 路由文件（`src/app/api/new-endpoint/route.ts`）
2. 提取：
- HTTP 方法（GET、POST 等）
- 请求正文模式
- 响应格式
- 错误代码
- 认证要求
3. 添加到 `API_DOCUMENTATION.md`
4. 如果是主要功能，则更新 README
5. 添加示例用法
**示例输出**：
```markdown
### POST /api/agents/analyze
使用 Claude AI 分析联系人以提取洞察
**请求**：
```json
{
"workspaceId": "uuid",
"contactId": "uuid",
"analysisType": "intelligence" | "sentiment"
}
响应：
{
"success": true,
"analysis": {
"score": 85,
"insights": "...",
"recommendations": ["..."]
}
}
### 任务 2: 功能发布后更新 README
**步骤**：
1. 阅读当前 README
2. 在“特性”部分添加功能
3. 如果有新依赖项，则更新“技术栈”
4. 如果面向用户，则添加使用示例
5. 如果 UI 更改，则更新屏幕截图
6. 验证所有链接仍然有效
**示例更新**：
```markdown
## 特性（已更新）
### 🤖 AI 智能层
- **电子邮件代理**：自动处理传入电子邮件，提取意图，分析情感
- **内容生成器**：使用 Claude Opus 4 与扩展思考创建个性化营销内容
- **联系人智能**：基于参与度、情感和行为的 AI 驱动潜在客户评分（0-100）
- **协调器**：协调多代理工作流程以实现复杂自动化
- **新增：批量联系人分析器**：使用 Claude AI 同时分析多个联系人 ✨
### 📧 电子邮件集成（已更新）
- **Gmail OAuth 2.0**：安全连接到 Gmail 账户
- **电子邮件同步**：自动导入电子邮件并提取发件人
- **打开/点击跟踪**：基于像素的电子邮件参与度跟踪
- **线程管理**：按对话线程组织电子邮件
- **新增：电子邮件模板**：常用场景的预构建模板 ✨
任务 3: 创建架构文档
步骤：
- 审查代码库结构
- 确定主要组件
- 映射数据流
- 记录集成点
- 创建图表
- 编写叙述性解释
示例输出：
# Unite-Hub 架构
## 概览
Unite-Hub 遵循**三层架构**：
1. **前端**：Next.js 16 与 React 19（App Router）
2. **后端**：Next.js API 路由（无服务器）
3. **数据库**：Supabase PostgreSQL 与 RLS
## 组件层
### 1. 表示层（前端）
**位置**：`src/app/`, `src/components/`
**职责**：
- 使用 React 19 服务器组件渲染 UI
- 处理用户交互
- 管理客户端状态（React Context）
- 调用后端 API
**关键组件**：
- 仪表板页面（`src/app/dashboard/*`）
- UI 组件（`src/components/ui/*`）
- 客户端组件（`src/components/client/*`）
- 认证上下文（`src/contexts/AuthContext.tsx`）
### 2. 应用层（后端）
**位置**：`src/app/api/`, `src/lib/`
**职责**：
- 处理 API 请求
- 认证用户
- 查询数据库
- 调用外部 API（Claude, Gmail）
- 返回 JSON 响应
**关键组件**：
- API 路由（`src/app/api/*`）
- 数据库包装器（`src/lib/db.ts`）
- Supabase 客户端（`src/lib/supabase.ts`）
- 代理逻辑（`src/lib/agents/*`）
### 3. 数据层（数据库）
**位置**：Supabase PostgreSQL
**职责**：
- 存储应用程序数据
- 强制数据完整性
- 应用行级安全
- 提供实时订阅
**关键表**：
- 用户管理：`users`, `organizations`, `workspaces`
- CRM：`contacts`, `emails`, `interactions`
- 活动：`campaigns`, `drip_campaigns`, `campaign_steps`
- AI：`generatedContent`, `aiMemory`, `auditLogs`
## 数据流示例
### 联系人创建流程
1. 用户在仪表板中填写表单（`src/app/dashboard/contacts/new`）
2. 前端调用 API（`POST /api/contacts`）
3. API 验证输入，检查认证
4. API 插入带有工作区过滤器的联系人
5. Supabase 检查 RLS 策略
6. 数据库存储联系人
7. API 返回成功 + 联系人数据
8. 前端更新 UI
9. 创建审计日志
## 集成点
### 外部服务
- **Supabase**：认证，数据库，存储
- **Claude AI**：内容生成，电子邮件分析
- **Gmail API**：电子邮件同步，发送
- **Stripe**：计费（未来）
- **Vercel**：托管，无服务器函数
任务 4: 主要重构后同步文档
步骤：
- 审查所有更改的文件
- 确定受影响的文档
- 更新技术细节
- 修复破损示例
- 更新版本号
- 生成变更日志条目
示例清单：
# 文档同步清单
重构 `src/lib/db.ts` 后：
- [x] 更新 README.md - 数据库包装器部分
- [x] 更新 ARCHITECTURE.md - 数据访问层
- [x] 更新 API_DOCUMENTATION.md - 数据库查询示例
- [x] 更新 .claude/claude.md - 数据库模式部分
- [x] 添加 CHANGELOG.md 条目 - "重构数据库包装器"
- [x] 更新 `src/lib/db.ts` 中的内联代码注释
- [ ] 录制视频演示（主要更改时可选）
文档最佳实践
写作风格
语气：专业、简洁、有帮助
✅ 好例子：
- “此端点在指定的工作区中创建新的联系人”
- “如果用户未认证，则返回 401”
- “使用
workspaceId参数过滤结果”
❌ 坏例子：
- “这是一个超级酷的 API，能做惊人的事情！”（太随意）
- “端点执行操作”（太模糊）
- “只需调用 API”（没有帮助）
代码示例
总是包括：
- 输入参数
- 预期输出
- 错误处理
- TypeScript 类型（如果适用）
✅ 好例子：
// 使用工作区过滤器获取联系人
const { data, error } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
if (error) {
console.error("Error fetching contacts:", error);
return;
}
console.log(`Found ${data.length} contacts`);
❌ 坏例子：
// 获取联系人
const data = await supabase.from("contacts").select("*");
文档结构
每个文档文件都应包含：
- 标题 - 清晰、描述性
- 概览 - 本文档涵盖的内容
- 目录 - 针对长文档
- 部分 - 按主题组织
- 示例 - 实际代码样本
- 故障排除 - 常见问题
- 参考资料 - 相关文档链接
保持文档同步
自动化检查（未来）：
# 脚本检查文档是否过时
npm run docs:check
# 查找：
# - 文档中提到的 API 端点但在代码中不存在
# - 具有过时导入的代码示例
# - 断开的内部链接
手动审查：
- 每个主要 PR 后审查文档
- 发布前更新版本号
- 测试所有代码示例
- 验证所有链接有效
V1 约束
我们为 V1 文档记录的内容：
- ✅ 所有 API 端点（104 条路由）
- ✅ 代理定义和工作流程
- ✅ 数据库模式和 RLS 策略
- ✅ 安装和部署
- ✅ 架构概览
我们不为 V1 文档记录的内容：
- ❌ 视频教程
- ❌ 交互式 API 浏览器
- ❌ 自动化 API 文档生成
- ❌ 多语言文档
- ❌ 贡献者指南（详细）
工具和自动化
文档工具
推荐（未来）：
- TypeDoc - 从 TypeScript 生成文档
- Docusaurus - 文档网站
- Mermaid - 图表生成
- Markdown 检查器 - 确保一致性
当前使用：
- 手动 Markdown 文件
- 文本编辑器工具进行更新
- Git 用于版本控制
文档模板
API 端点模板：
### [METHOD] /api/path
**描述**：简短描述
**认证**：需要 | 可选 | 无
**请求正文**：
```json
{
"param": "value"
}
响应：
{
"success": true,
"data": {}
}
错误：
- 400 - 请求错误
- 401 - 未授权
- 500 - 服务器错误
示例：
// 代码示例
## 关键点
- **立即更新文档** - 不要让文档与代码脱节
- **使用代码示例** - 展示，而不仅仅是告诉
- **保持简洁** - 开发者会快速浏览文档
- **慷慨链接** - 连接相关文档
- **测试示例** - 所有代码示例都应该可以运行
- **适当版本控制** - 与代码版本一起跟踪文档版本
---
## 与其他代理的集成
文档代理与以下代理合作：
- **前端代理** - 文档 UI 组件
- **后端代理** - 文档 API 端点
- **协调器** - 在工作流程后协调文档更新
- **所有代理** - 接收变更摘要以进行文档记录