skyphusion-labs/common-thread
GitHub: skyphusion-labs/common-thread
该项目提供一套文档化的方法论和参考实现，通过社交行为信号对协调运行的傀儡账号进行集群级别的操作者归因。
Stars: 1 | Forks: 0
# 通用线程
这是一份供从业者使用的操作者归因方法论及参考实现，
旨在通过社交平台上的可观察行为信号进行傀儡账号归因。
Common Thread 以**方法论论文**（规范）和**参考实现**（Cloudflare Workers + MySQL + R2）的形式提供。给定一组种子账号，它会将协调一致的不真实行为归因于共同的操作者，并在三个置信区间内输出经过校准的概率声明：`insufficient`、`consistent`、`strongly_consistent`。根据设计，它在集群级别的归因处停止，从不对自然人进行身份识别。
## 适用对象
为自己辩护的诉讼当事人、小型新闻编辑室的记者、OSINT 从业者以及研究人员，他们需要在没有平台内部数据或商业 OSINT 工具的情况下使用有文档记录的方法论。在应用该方法论之前，请阅读论文中的受众排除条款（§1.2）。
## 仓库结构
| 路径 | 用途 |
|------|---------|
| `paper/` | 方法论论文 (CC-BY-4.0) — **规范** |
| `implementation/` | 后端参考实现 (AGPL-3.0) |
| `web/` | 浏览器 UI Worker（代理 API，用于归因的 BYOK） |
| `docs/` | 设置、部署、API、测试 |
| `containers/` | 可选的 VPC 导入和 PDF worker |
| `tests/` | Vitest 测试套件（Workers 池 + MySQL 集成） |
| `examples/` | 详细的案例研究（在 v1 中为占位符） |
## 快速开始
```
git clone https://github.com/skyphusion-labs/common-thread
cd common-thread
npm install
# 后端 config（填入 Hyperdrive + R2 ID）
cp wrangler.toml.example wrangler.toml
# Web 前端 config（service binding 到后端）
cp web/wrangler.toml.example web/wrangler.toml
# 关于 MySQL、R2、Hyperdrive 和本地开发，请参阅 docs/SETUP.md
```
**本地开发**
```
# 终端 1 — 后端 API
npm run dev
# 终端 2 — Web UI（可选）
npm run dev:web
```
打开 Web UI，创建一个调查（保存访问 token），上传 Apify 的 Twitter JSON，通过导入功能运行提取器，然后使用**你自己的** Anthropic / AI Gateway 密钥 (BYOK) 运行归因。详情请参见 `docs/SETUP.md` 和 Web UI 中的“设置”选项卡。
## 文档
| 文档 | 内容 |
|-----|----------|
| [docs/SETUP.md](docs/SETUP.md) | 首次安装、MySQL、密钥、本地开发 |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | 部署后端 + Web、绑定、VPC 容器 |
| [docs/API.md](docs/API.md) | HTTP 路由和典型工作流 |
| [docs/TESTING_SETUP.md](docs/TESTING_SETUP.md) | Vitest、MySQL 测试数据库、LLM 模拟 |
| [docs/contact.md](docs/contact.md) | 公开和私密的联系渠道 |
## Web 前端
`web/worker.js` 是一个单文件 Worker，提供完整的工作流 UI：
- 创建调查（一次性能力 token），并使用 token 或分享链接重新打开
- 上传 Apify 数据；完成后封存调查（只读）
- 轮询导入任务并查看特征
- 使用**自带密钥** (BYOK) 凭证运行归因
- 下载证据包（JSON、Markdown，以及配置后的 PDF）
调查是私密的：没有全局列表。Token 属于能力密钥——UI 说明了它们可以保护什么以及不能保护什么。
在生产环境中，Web Worker 通过**服务绑定**（`BACKEND`）将 `/api/proxy/*` 代理到后端。用户在浏览器中提供 Anthropic / AI Gateway 密钥和调查访问 token；API 密钥不会存储在服务器上。调查 token 可能会保存在用户设备的 `localStorage` 中。
## 自带密钥 (BYOK)
托管方不需要为每个人的 LLM 使用量买单。归因功能接受每次请求提供的凭证（Web UI 或 API 标头）。当所有用户均使用 BYOK 时，服务器端的 `AI_GATEWAY_URL` / `ANTHROPIC_API_KEY` 密钥是可选的。请参阅 `docs/API.md` 和 Web 界面中的“设置”选项卡。
## 许可协议
- **实现代码：** AGPL-3.0
- **方法论论文：** CC-BY-4.0
## 状态
v1 正在进行稳定性维护。方法论论文已完成。后端 Worker、Web 前端以及可选的 VPC 导入/PDF 容器均已实现。
**公开 UI：** https://common-thread.skyphusion.org
**公开 API：** https://common-thread-backend.skyphusion.org（参见 [docs/API.md](docs/API.md)）。
在你自己的项目中使用托管 API 需要事先联系运营者——请发送邮件至 **common-thread@skyphusion.org** 或参阅 [docs/contact.md](docs/contact.md)。
如果想在不经询问的情况下运行自己的实例，请按照 `docs/SETUP.md` 进行自托管。
**Skyphusion Labs：** https://skyphusion.org · **组织：** https://github.com/skyphusion-labs
**代码仓库：** https://github.com/skyphusion-labs/common-thread
标签：ESC4, OSINT, 代码示例, 数据分析, 数据可视化, 机器人与水军识别, 社交媒体分析, 程序员工具, 自动化攻击