内容
# AI 代理团队
单个 **Claude 代码**中心，运行创始人的全部业务——内容、Instagram 分析、付费广告、竞争情报、视频再利用和业务运营——基于官方 Meta/Instagram MCP 和一组本地 Python 引擎、自定义技能和有纪律的会话工作流。
> **这是框架**，从一个实时中心提取：引擎、技能、文档和工作方法。
> 个人数据——所有者 的 Obsidian 保险库、私人分析、渲染媒体和所有机密——通过 `.gitignore` 有意排除。请自带凭证（参见 [设置](#设置)）。
## 功能
- **了解数据。** 自更新的 Instagram 分析引擎跟踪最近 300 篇帖子，拥有每日历史记录，超出了 Meta 的 30 天窗口，为本地仪表板和代理人阅读的自动生成统计文件提供数据。
- **监测竞争。** 竞争和趋势雷达通过官方 `business_discovery` API（不涉及爬虫）拉取竞争者的短视频 **及观看次数**，并从免费、无密钥的来源中标记新兴话题。
- **制作内容。** 技能草拟轮播/线程和评论（三步骤：草拟 → 批准 → 回复，绝不自动发送）；本地 **自动剪辑** 引擎将长视频转换为排名的垂直短视频（转录 → 重点突出 → 重新构图），并提供 Remotion/HyperFrames 编辑套件。
- **规划和记忆。** 基于文件的上下文系统（个人资料 + 记忆）和书面人工制品（计划、交接）在这几个会话中传递；上下文卫生规则保持长会话的清晰。
## 内部结构
| 区域 | 描述 |
|---|---|
| **`ig-dashboard/`** | 自更新的 IG 分析引擎（`refresh.py`）涵盖您的最近 300 篇帖子 + 自包含的本地仪表板（`dashboard.html`）。每日历史记录超出 Meta 的 30 天窗口；自动检测令牌过期。 |
| **`intel/`** | 竞争和趋势情报。`competitor-radar.py` 通过官方 `business_discovery` API（不涉及爬虫）拉取竞争者的短视频 **及观看次数**。`trend-radar.py` 是基于免费、无密钥来源（维基百科页面浏览量 + GDELT + Hacker News）的病毒式传播早期预警雷达。 |
| **`auto-clip/`** | 本地长视频 → 垂直短视频引擎：`transcribe.py`（逐词快速转录）→ `highlight.py`（LLM 时刻选择器）→ `reframe.py`（9:16 剪辑 + 通过 FFmpeg 编码）。重用编辑套件；仅限文件输出，**绝不自动发布**。 |
| **`team/`** | 基于文件的上下文系统 — `profile.md`（操作员信息）+ `memory.md`（累积的学习成果）。`stats.md` 由仪表板自动生成（被 gitignore 忽略）。 |
| **`.claude/skills/`** | 自定义技能（如下）+ `dev-workflow` 和 `context-checkpoint` — 工作方法。 |
| **`.claude/workflows/`** | `research-lean.js` — 节流安全的深度研究工作流（批量验证；参见 `docs/RESEARCH-PROTOCOL.md`）。 |
| **`docs/`** | 工作方法（改编自 [tworkflow](https://github.com/clarity-digital-development/tworkflow)）+ 研究协议 + 产品/策略文档 + 有日期的能力研究 + 可重复使用的计划/审查/质量保证模板。 |
| **根目录文档** | `CLAUDE.md`（中心的运营合同，每个会话自动加载）、`HANDOFF.md`（运营状态）、`AGENT-TEAM-BLUEPRINT.md` 和 `CONTENT-INTEL-PROTOCOL.md`（研究的工具路线图）。 |
## 自定义技能
- **`carousel-builder`** — 将创意或成熟的短视频转化为可保存的 IG 轮播（+ 可选线程），草拟为保险库笔记。优化以获得 *保存*。
- **`comment-triage`** — 分类传入的评论并草拟品牌回复（+ 可逆隐藏）以便一键批准。**绝不自动发送**。
- **`weekly-content-plan`** — 基于实时绩效数据的 7 天内容计划。
- **`niche-intel`** — 竞争对手 + 趋势扫描转化为品牌内容创意。
- **`research`** — 通过中心的节流安全协议路由任何研究请求。
- **`dev-workflow` / `context-checkpoint`** — 计划 → 构建 → 审查 → 质量保证循环，和刻意的上下文重置规则。
## 连接能力（MCPs）
通过 `.mcp.json` 使用环境变量占位符连接 —— **不提交机密**：
- **Instagram Graph** — 洞察、评论、媒体、人口统计、发布 *(发布需要明确的逐操作确认)*。
- **Meta 广告** — 广告活动 / 广告组 / 广告 / 受众 / 洞察 *(自由读取；任何写入都需先确认)*。
- **研究** — Exa + Tavily（搜索）+ Firecrawl（深度爬取 / JS 渲染）。
- **媒体 & 生成** — Higgsfield（图像/视频/广告 + 病毒式传播预测器）、ElevenLabs（文本转语音/语音）、FFmpeg、视频分析器。
- **控制** — Chrome 中的 Claude + 计算机使用，仅在公共页面上使用且使用频率有限。
## 设置
1. **前提条件：** Python 3.12+、Node 20+ (`npx`)、`uv`/`uvx`、git、Claude Code（桌面版或 CLI）、FFmpeg 在 PATH 上。
2. **通过 OS 环境变量存储机密（绝不存储在文件中）：**
```
setx INSTAGRAM_ACCESS_TOKEN "<您的 IG Graph 令牌>"
setx INSTAGRAM_ACCOUNT_ID "<您的 IG 商业账户 ID>"
```
可选（研究 / 媒体 / 自动剪辑）：`EXA_API_KEY`、`TAVILY_API_KEY`、`FIRECRAWL_API_KEY`、
`ANTHROPIC_API_KEY`（用于 `auto-clip/highlight.py`，或运行本地 Ollama）、`ELEVENLABS_API_KEY`、`GEMINI_API_KEY`。
3. **MCP 服务器** 从 `.mcp.json`（环境变量占位符）加载。**完全退出并重启** Claude Code
在设置环境变量后 — 仅在全新进程中加载。Meta 广告连接器通过浏览器 OAuth 添加。
4. **运行引擎：** `python ig-dashboard/refresh.py` · `python intel/competitor-radar.py` ·
`python intel/trend-radar.py`（或 `Daily Agent Refresh.bat` 用于全部三个）。每日计划任务保持历史记录累积。
5. **自动剪辑（可选）：** `python auto-clip/transcribe.py <视频>` → `python auto-clip/highlight.py data/<词干>.transcript.json`
→ `python auto-clip/reframe.py <视频> data/<词干>.highlights.json`。输出位于 `auto-clip/out/`。
## 设计原则
- **官方 API 优先，爬虫最后** — 大多数竞争数据可通过 `business_discovery`
和广告库以零爬虫风险获取。参见 `CONTENT-INTEL-PROTOCOL.md`。
- **人工干预发布** — 代理草拟、创建容器并排队操作；操作员
执行每次最终发布/回复/直接消息点击。
- **机密仅存储在 OS 环境变量中** — 此树是云同步的；任何敏感信息都不存储在磁盘上。
- **上下文卫生** — 长会话在大约 40% 时有意重置（`context-checkpoint` 技能 + 钩子）。
- **书面人工制品优于对话** — 计划、交接和记忆文件在会话间传递。
## 项目状态
- **已构建且运行中：** IG 仪表板、情报雷达、基于文件的上下文系统、内容/情报技能、节流安全研究栈和 **自动剪辑基础**（转录 → 重点突出 → 重新构图，在真实视频上端到端验证）。
- **进行中 / 研发中：** 自动剪辑增强（人脸跟踪重新构图、完全自动化的重点选择、烧录字幕、可选的 GPU 加速）和 **受众模拟** 实验 — 一个基于 OASIS 的发布前反应预测器，它是有意先证明后验证的，尚未在 Instagram 上验证，直到反向测试验证它。
## 致谢
工作方法改编自 Tanner Carlson 的 [tworkflow](https://github.com/clarity-digital-development/tworkflow)（MIT）。
在 Claude Code 中协同构建。
