# platformData

**Repository Path**: lyflyy/platform-data

## Basic Information

- **Project Name**: platformData
- **Description**: 自动化数据采集平台1
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Platform Agent

Platform Agent 是一个本地桌面数据采集应用，用于把复杂广告后台中的固定数据获取流程固化为可重复执行的浏览器自动化任务。当前项目优先解决“稳定拿到平台数据文件”的问题：登录、进入平台、选择账号、生成导出任务、下载文件、管理历史产物，都在本地应用中完成。

项目当前处于 MVP 验收阶段：小红书聚光的数据采集链路已经跑通，后续会继续接入第二个平台，并逐步把多平台数据统一整理为可分析的数据资产。

## 当前目标

我们要做的是一个轻量、可落地的数据采集工作台，而不是让应用在运行时临时理解复杂网页流程。

核心思路：

- 由人工和 Codex 先把平台操作流程拆清楚。
- 将稳定流程固化为应用中的确定性执行器和流程配置。
- 应用只负责按已验证流程执行、处理登录态、下载文件、记录产物。
- 后续在多平台数据都能稳定获取后，再做统一数据整理、指标分析和报告生成。

## 已完成状态

当前已完成：

- Electron 桌面应用基础框架。
- 平台配置、模型配置、报表模板配置。
- 小红书聚光确定性采集流程。
- 小红书合作伙伴后台登录邮箱/密码配置。
- 登录时自动勾选 `我已阅读并同意《隐私政策》`。
- 合作伙伴后台子账号匹配。
- 每个目标账号打开新的聚光页面，不关闭原合作伙伴后台页面。
- 聚光创意报表近 7 天数据下载。
- 通过小红书长任务接口直接获取 CSV 文件，避免依赖页面下载按钮。
- 下载文件资产管理。
- 按平台、操作记录、账号、关键词筛选下载文件。
- CSV 文件内容预览。
- 打开文件、打开文件夹、删除文件并二次确认。
- 磁盘实时扫描：文件被外部删除后，应用列表自动消失。
- 本地运行记录、报告文件、下载文件统一展示。
- macOS x64 和 arm64 DMG 发布包。

真实流程验证结果：

- 小红书聚光已完成端到端采集验证。
- 4 个投放账号。
- 每个账号 3 份 CSV。
- 共 12 个文件。
- 下载文件校验通过。

## 应用截图

### 工作台

![工作台](docs/screenshots/dashboard.png)

### 平台配置

![平台配置](docs/screenshots/platform-config.png)

### 下载文件筛选

![下载文件筛选](docs/screenshots/download-history.png)

### CSV 内容预览

![CSV 内容预览](docs/screenshots/file-preview.png)

## 下载与安装

当前发布版本：

- Tag：[`v1.0.0`](https://gitee.com/lyflyy/platform-data/tree/v1.0.0)
- Release 文件目录：[`release/`](https://gitee.com/lyflyy/platform-data/tree/reverse-dmg-analysis/release)
- 当前开发分支：[`reverse-dmg-analysis`](https://gitee.com/lyflyy/platform-data/tree/reverse-dmg-analysis)

仓库中为了规避大文件限制，提交的是 DMG 分片文件：

- `release/PlatformAgent-darwin-x64.dmg.part-aa`
- `release/PlatformAgent-darwin-x64.dmg.part-ab`
- `release/PlatformAgent-darwin-arm64.dmg.part-aa`
- `release/PlatformAgent-darwin-arm64.dmg.part-ab`
- `release/SHA256SUMS`

分片下载入口：

- Intel Mac：
  - [`PlatformAgent-darwin-x64.dmg.part-aa`](https://gitee.com/lyflyy/platform-data/blob/reverse-dmg-analysis/release/PlatformAgent-darwin-x64.dmg.part-aa)
  - [`PlatformAgent-darwin-x64.dmg.part-ab`](https://gitee.com/lyflyy/platform-data/blob/reverse-dmg-analysis/release/PlatformAgent-darwin-x64.dmg.part-ab)
- Apple Silicon Mac：
  - [`PlatformAgent-darwin-arm64.dmg.part-aa`](https://gitee.com/lyflyy/platform-data/blob/reverse-dmg-analysis/release/PlatformAgent-darwin-arm64.dmg.part-aa)
  - [`PlatformAgent-darwin-arm64.dmg.part-ab`](https://gitee.com/lyflyy/platform-data/blob/reverse-dmg-analysis/release/PlatformAgent-darwin-arm64.dmg.part-ab)
- 校验文件：[`SHA256SUMS`](https://gitee.com/lyflyy/platform-data/blob/reverse-dmg-analysis/release/SHA256SUMS)

选择版本：

- Intel Mac 使用 `PlatformAgent-darwin-x64.dmg`
- Apple Silicon Mac 使用 `PlatformAgent-darwin-arm64.dmg`

还原 DMG：

```bash
cd release
cat PlatformAgent-darwin-x64.dmg.part-* > PlatformAgent-darwin-x64.dmg
cat PlatformAgent-darwin-arm64.dmg.part-* > PlatformAgent-darwin-arm64.dmg
```

只需要还原自己电脑对应架构的 DMG。

校验文件：

```bash
shasum -a 256 PlatformAgent-darwin-x64.dmg PlatformAgent-darwin-arm64.dmg
cat SHA256SUMS
```

安装方式：

1. 双击对应架构的 DMG。
2. 打开 `PlatformAgent.app`。
3. 如果 macOS 提示无法验证开发者，在“系统设置 -> 隐私与安全性”中允许打开。

## 如何使用

1. 打开应用。
2. 进入“平台配置”。
3. 选择“小红书聚光”。
4. 填写并保存登录邮箱、登录密码、浏览器状态目录、目标账号等配置。
5. 回到“工作台”，点击“执行/继续启用平台采集”。
6. 如果出现验证码、安全验证或登录异常，按浏览器页面提示人工处理。
7. 采集完成后进入“产物历史”查看下载文件。
8. 按平台、操作记录、账号、关键词筛选文件。
9. 点击“查看内容”预览 CSV，或点击“打开文件”使用系统默认程序打开。

## 小红书聚光采集内容

当前小红书聚光流程会下载基础报表的创意维度数据，时间范围为最近 7 个已完成自然日。

每个账号输出 3 份 CSV：

- `base`：营销诉求 + 投放位置 + 优化目标
- `targeting`：营销诉求 + 投放位置 + 优化目标 + 定向类型
- `search_theme`：营销诉求 + 投放位置 + 优化目标 + 搜索主题名称

文件默认保存到：

```text
~/Library/Application Support/platformdata/app_data/downloads/xhs_juguang/
```

应用数据目录：

```text
~/Library/Application Support/platformdata/app_data/
```

## 配置说明

平台配置保存在本机应用数据目录中：

```text
~/Library/Application Support/platformdata/app_data/config/platforms/
```

小红书聚光配置支持：

- `entry_url`：合作伙伴后台入口。
- `login.username`：登录邮箱。
- `login.password`：登录密码。
- `login.profile_dir`：浏览器登录状态目录。
- `target_account_names`：需要采集的目标投放账号。
- `workflow.segment_sets`：需要导出的细分组合。
- `output.directory`：下载目录。

安全约定：

- 仓库默认配置不包含真实账号密码。
- 账号密码只保存在用户本机应用目录。
- 运行日志和报告不输出密码。
- 遇到验证码、安全校验、人机验证时，应用会等待人工处理，不绕过平台安全机制。

## 开发运行

安装依赖：

```bash
npm install
```

本地启动：

```bash
npm start
```

运行测试：

```bash
npm run test:e2e
```

打包 macOS：

```bash
npm run dmg:mac
npm run dmg:mac:arm64
```

本地打包产物：

```text
dist/PlatformAgent-darwin-x64/PlatformAgent.app
dist/PlatformAgent-darwin-arm64/PlatformAgent.app
release/PlatformAgent-darwin-x64.dmg
release/PlatformAgent-darwin-arm64.dmg
```

## 项目结构

```text
.
├── main.js                         # Electron 主进程
├── preload.js                      # Renderer 安全桥接
├── renderer/                       # 前端页面与样式
├── lib/                            # 采集、存储、报告、验证逻辑
├── flow_specs/                     # 固化流程规格
├── scripts/                        # 流程观测和验证脚本
├── tests/e2e/                      # 端到端测试
├── docs/screenshots/               # README 截图
├── release/                        # 发布包分片和校验文件
└── app_data/                       # 开发期本地数据目录，发布时不打包
```

## 技术栈

- Electron：桌面应用容器。
- Playwright：浏览器自动化执行。
- Node.js：本地文件、配置、任务调度。
- Markdown：报告输出和文档产物。
- DeepSeek/OpenAI-compatible API：用于报告生成和后续智能分析能力。

## 后续规划

短期：

- 接入第二个平台。
- 把第二个平台的数据下载、文件登记、预览、删除、筛选接入同一套资产管理体系。
- 增强平台失败诊断，记录失败截图、页面状态和关键接口响应。

中期：

- 多平台数据统一归档。
- 标准化字段映射。
- 支持按品牌、平台、账号、日期范围汇总数据。
- 生成日报、周报、月报。

长期：

- 建立稳定的数据采集和分析工作流。
- 将平台下载文件整理为结构化数据资产。
- 在多平台数据基础上做投放效果分析、异常识别和运营建议。