# 项目 / 功能 / 脚本总览

最后更新：2026-03-31

这份文档用于回答：**我们目前已经做了哪些项目、功能、脚本和辅助能力。**

---

## 1. 主要项目

### 1.1 `ad-creative-system/`
**定位：广告素材分析系统（当前主线项目）**

当前 README 已明确，这不是一条串死的单体 pipeline，而是 3 个相对独立的工作流：

1. **标注（Labeling）**
   - 输入：图片 / 视频素材
   - 输出：结构化因子标签
2. **分析（Analysis）**
   - 输入：已校验标签
   - 输出：因子分析、模式总结
3. **Brief 生成（Briefing）**
   - 输入：分析结果或指定因子
   - 输出：创意 brief

**当前聚焦：** TikTok × MX

#### 已有能力
- 真实素材导入
- 多模态预处理
- 因子标注
- 标签校验
- 因子分析
- brief 生成
- LLM provider 抽象层（非单一模型绑定）
- usage 记录

#### 主要脚本
- `ad-creative-system/scripts/run_labeling_workflow.py`  
  跑标注工作流
- `ad-creative-system/scripts/run_analysis_workflow.py`  
  跑分析工作流
- `ad-creative-system/scripts/run_brief_workflow.py`  
  跑 brief 生成工作流
- `ad-creative-system/scripts/run_pipeline.py`  
  一键串联 wrapper
- `ad-creative-system/scripts/import_real_samples.py`  
  导入真实样本
- `ad-creative-system/scripts/import_from_creative_library.py`  
  从 creative-library 导入素材
- `ad-creative-system/scripts/prepare_creatives.py`  
  素材预处理
- `ad-creative-system/scripts/enrich_multimodal.py`  
  多模态增强
- `ad-creative-system/scripts/tag_creatives.py`  
  打标签
- `ad-creative-system/scripts/validate_labels.py`  
  标签校验
- `ad-creative-system/scripts/analyze_factors.py`  
  因子分析
- `ad-creative-system/scripts/generate_briefs.py`  
  生成 brief
- `ad-creative-system/scripts/llm_adapter.py`  
  LLM 适配
- `ad-creative-system/scripts/provider_bridge.py`  
  provider 桥接
- `ad-creative-system/scripts/usage_logger.py`  
  记录 token / usage
- `ad-creative-system/scripts/labeling_rules.py`  
  标注规则
- `ad-creative-system/scripts/common.py`  
  公共工具
- `ad-creative-system/scripts/init_analysis_tables.py`  
  初始化分析表

#### 当前配置 / 设计要点
- 支持 provider：`mock / gemini / openai / anthropic`
- 标注默认低温（`temperature = 0.0`），强调稳定性
- OCR 保留 `raw / clean`
- 视频增强当前已实现：
  - 抽 5 帧
  - 选 3 帧高信息量帧
- `risk_level` 由 `risk_tags` 派生

#### 输出产物
典型输出位于：
- `ad-creative-system/data/...`
- `ad-creative-system/output/...`

README 中列出的标准产物包括：
- `selected_samples.json`
- `prepared_multimodal_samples.json`
- `tagged_samples.json`
- `validated_samples.json`
- `analysis_report.json`
- `generated_briefs.json`
- `llm_usage.jsonl`

#### 配套文档
- `ad-creative-system/README.md`
- `ad-creative-system/docs/llm_and_import.md`
- `ad-creative-system/docs/workflow_refactor.md`
- `ad-creative-system/docs/video_dual_mode_plan.md`

---

### 1.2 `gemini-proxy/`
**定位：Gemini API 的 Cloudflare Worker 中转代理**

用于把 Gemini API 请求经 Cloudflare Worker 转发，解决接入与区域相关问题，并补一层可选鉴权。

#### 已有能力
- 透传 Gemini API 请求到 `generativelanguage.googleapis.com`
- 支持 `OPTIONS` / `GET` / `POST`
- 支持 CORS
- 支持可选鉴权头：`X-Auth-Token`

#### 关键文件
- `gemini-proxy/src/index.js`
- `gemini-proxy/wrangler.toml`
- `gemini-proxy/README.md`

#### 已知用途
- 作为 Gemini 调用中转层
- 给后续 provider-agnostic LLM 接入做兼容
- 已用于验证 Cloudflare Worker region 相关问题

---

## 2. 工作流辅助脚本（workspace 根目录 `scripts/`）

### 2.1 素材标注 / 分析调度脚本

#### `scripts/start_creative_round.py`
**定位：发起一轮完整的 import + labeling + analysis，并自动挂 watchdog。**

功能：
- 生成新的 run 名称和配置
- 从 `creative-library` SQLite 里抽取样本
- 生成临时 import 脚本
- 跑标注 + 分析
- 自动注册 watchdog 监控

适合：
- 发起新一轮 TikTok / MX 素材分析批次

#### `scripts/start_labeling_from_samples.py`
**定位：从现成 sample JSON 启动 labeling + analysis，并自动挂 watchdog。**

功能：
- 读取已有 sample JSON
- 生成 run config
- 执行标注 + 分析
- 自动注册 watchdog

适合：
- 手头已经有样本 JSON，只想直接跑分析

#### `scripts/export_recent_creatives.py`
**定位：从 `creative-library` 导出最近抓到的素材，转成适合标注系统吃的 JSON。**

功能：
- 从 `creatives.sqlite` 按平台 / 国家 / 时间导出素材
- 输出标准化 JSON
- 补齐常见字段（路径、媒体、文案、CTR、时长等）

适合：
- 把最近抓到的新素材喂给 `ad-creative-system`

---

### 2.2 Watchdog 系统（后台任务监控）

这套脚本是为了满足现在已经定下来的规则：
**凡是后台任务，必须有专属 watchdog。**

#### 已有脚本
- `scripts/watchdog_launch.py`  
  启动后台任务并同时拉起 watchdog monitor
- `scripts/watchdog_monitor.py`  
  轮询日志 / 输出 / 进度，持续更新 watchdog 状态
- `scripts/watchdog_register.py`  
  注册 watchdog 状态
- `scripts/watchdog_refresh.py`  
  刷新 watchdog 状态
- `scripts/watchdog_report.py`  
  输出给 LLM / 人看的精简结构化报告
- `scripts/watchdog_state.py`  
  读取 / 查看 watchdog 状态

#### 当前用途
- 监控标注分析批次
- 监控后台进程日志
- 判断任务状态：正常 / watch / intervene / failed
- 跟踪：
  - 当前阶段
  - 最近进展时间
  - 最近日志摘要
  - 产物是否已落盘
  - 下一步动作建议

#### 相关目录
- `memory/watchdogs/`
- `logs/watchdogs/`

---

### 2.3 分享 / 发布辅助

#### `scripts/share_server.py`
**定位：本机共享目录 HTTP 服务。**

功能：
- 以 `127.0.0.1:18080` 提供 `/Users/Shared/openclaw-share` 静态文件访问
- 开启 CORS
- 禁用缓存

#### `scripts/publish-share`
**定位：把文件或目录发布到共享目录并返回可访问链接。**

功能：
- 按 profile（`main / suyue / xunan / hongjie`）分目录发布
- 自动加时间戳
- 返回可分享 URL

#### `scripts/ai.openclaw.share-server.plist`
**定位：share server 的 LaunchAgent 配置。**

---

## 3. 调研 / 抓取成果（`.firecrawl/`）

**定位：外部网站调研与资料抓取沉淀目录。**

这里不是“正式项目”，但已经积累了不少可复用调研结果。

### 已有主题（从文件名看）
- Adzviser 调研
- TikTok Creative Center / TikTok API / internal API 调研
- Meta Ad Library / GraphQL / 抓取方案调研
- Google Ads Transparency 调研
- 创意评分 / 创意测试 / post-launch evaluation 资料
- Cloudflare region / Gemini placement 调研

### 典型用途
- 给后续方案设计提供资料基础
- 避免重复查同一类竞品 / 技术资料
- 为脚本开发前做方法论预研

> 注意：`.firecrawl/` 更偏“研究素材库”，不是生产代码。

---

## 4. 已安装 / 已接入的自定义技能（`skills/`）

当前 workspace 下已有一些可复用技能包：

- `skills/agent-browser`  
  浏览器自动化
- `skills/find-skills`  
  搜索可用 skills
- `skills/gemini-draw`  
  Gemini 图像生成 / 编辑
- `skills/mem0`  
  语义记忆层
- `skills/openclaw-tavily-search`  
  Tavily 搜索
- `skills/self-improving-agent`  
  自我改进 / learnings 机制

这些更像“能力模块”，不是单独业务项目，但已经属于现有可用能力。

---

## 5. 记忆 / 规则 / 运行辅助

### 5.1 长期记忆与规则
- `MEMORY.md`  
  长期记忆、已确认工作规则、方法论、关键决策
- `memory/YYYY-MM-DD.md`  
  每日原始工作记录

### 5.2 Learnings
- `.learnings/LEARNINGS.md`
- `.learnings/ERRORS.md`

用于沉淀：
- 犯过的错
- 外部工具失败经验
- 更优做法

### 5.3 OpenClaw 自身角色与工作方式文件
- `AGENTS.md`
- `SOUL.md`
- `USER.md`
- `IDENTITY.md`
- `TOOLS.md`
- `HEARTBEAT.md`

这些不是项目代码，但构成了当前 assistant 的工作操作系统。

---

## 6. 目前可以明确说“已经做出来”的功能

按成果而不是按目录来归纳，当前已经具备：

### A. 广告素材分析能力
- 真实素材导入
- 素材预处理
- 多模态增强
- 结构化标注
- 标签校验
- 因子分析
- brief 生成
- provider 抽象
- usage 记录

### B. 批次调度能力
- 从 creative-library 自动抽样发起一轮分析
- 从 sample JSON 发起一轮分析
- 最近素材导出为分析输入

### C. 后台监控能力
- 后台任务启动即注册 watchdog
- 日志 / 输出 / 进度监控
- 结构化状态汇报
- 支持人为判断是否 intervene

### D. 文件分享能力
- 本地 share server
- 按 profile 发布文件 / 目录并生成链接

### E. Gemini 接入中转能力
- Cloudflare Worker 代理
- 可选鉴权
- CORS 支持

### F. 外部网站 / 竞品 / API 调研沉淀能力
- 通过 Firecrawl 持续抓取资料到 `.firecrawl/`

---

## 7. 当前建议的“项目目录视角”总结

如果只看最值得关心的主线，当前可以简化成这几块：

1. **ad-creative-system**  
   主业务项目：素材标注 / 分析 / brief 系统

2. **gemini-proxy**  
   LLM 接入基础设施项目

3. **scripts/watchdog_* + start_* + export_recent_creatives.py**  
   调度与监控层

4. **scripts/share_server.py + publish-share**  
   文件分享层

5. **.firecrawl/**  
   研究资料库

6. **skills/**  
   已接入能力模块

---

## 8. 后续建议

如果你要把这套东西真正变成“我们当前资产清单”，下一步建议做 3 件事：

### 8.1 再补一份“状态表”
给每个项目标：
- 目的
- 当前状态（验证中 / 可用 / 生产中 / 暂停）
- 负责人/主要入口
- 最近更新时间

### 8.2 给根目录脚本补 usage 示例
尤其是：
- `start_creative_round.py`
- `start_labeling_from_samples.py`
- `export_recent_creatives.py`
- watchdog 系列

### 8.3 单独再整理一份“我们做过的决策与结论”
比如：
- v2 / v3 标注体系结论
- MX 小样本验证结果
- 多线程默认策略
- Web 自动化方法论
- Grafana 数据采集方案

这样“资产清单”和“决策清单”就分开了，后面更好查。