内容
# 池统计
**基于代理的产品分析**。池统计是一个轻量级的、类似PostHog的分析系统，其主要用户是通过MCP的编码代理，而不是人类点击仪表盘。
核心思想是从一开始就创建具有语义的指标。每个指标都有一个必填的`目的`，每个漏斗都有一个`目标`，因此仪器可以被代理检查、维护和查询，而不是作为未命名的事件混乱存在。
## 源代码可用
池统计在 [PolyForm Shield License 1.0.0](LICENSE) 下源代码可用。您可以阅读、运行和修改软件以满足允许的用例，但不能将池统计作为竞争性产品出售或提供竞争性托管或管理服务。
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md) 和 [源代码可用发布检查清单](docs/09-source-available-release.md)，了解项目规则和发布卫生。
此仓库包含系统本身：后端、摄入API、MCP服务器、SDK、无头管理员SPA、迁移、技术文档和Docker自托管。营销网站、公共文档UI、等待名单和未来仅限云端代码存放在单独的仓库中。
## 工作原理
1. 编码代理在产品中安装仪器，并通过MCP在池统计中注册指标。
2. 产品将事件和实体发送到HTTP摄入API。
3. 池统计存储数据并公开类型化的查询工具，以便客户可以在自己的环境中构建仪表盘、检查和洞察。
## 文档
| 文档 | 内容 |
| --- | --- |
| [ARCHITECTURE.md](ARCHITECTURE.md) | 系统概述、组件和原则 |
| [docs/01-data-model.md](docs/01-data-model.md) | 租户、数据类型和表模式 |
| [docs/02-storage.md](docs/02-storage.md) | 存储设计和Postgres到ClickHouse的路径 |
| [docs/03-mcp-server.md](docs/03-mcp-server.md) | MCP服务器工具和资源 |
| [docs/04-http-api.md](docs/04-http-api.md) | 摄入和查询API |
| [docs/05-gap-analysis.md](docs/05-gap-analysis.md) | 当前范围与PostHog和下一个优先级 |
| [docs/06-instrumenting-a-product.md](docs/06-instrumenting-a-product.md) | 代理和手动仪器工作流 |
| [docs/07-vps-deployment.md](docs/07-vps-deployment.md) | 部署平台API、MCP、SDK和技能 |
| [docs/09-source-available-release.md](docs/09-source-available-release.md) | 源代码可用发布和GitHub卫生 |
| [docs/10-self-host.md](docs/10-self-host.md) | 短Docker Compose自托管路径 |
| [docs/11-repository-split.md](docs/11-repository-split.md) | 系统、站点和云端仓库边界 |
| [sdk/README.md](sdk/README.md) | `@poolstatis/sdk`客户端用法 |
| [.claude/skills/poolstatis-instrument](.claude/skills/poolstatis-instrument/SKILL.md) | 产品仪器代理技能 |
## 本地开发
```bash
docker compose up -d
pnpm install
pnpm migrate
pnpm bootstrap "池统计" poolstatis "本地项目"
pnpm serve
pnpm --dir web dev
```
在打开PR之前运行后端和共享逻辑检查：
```bash
pnpm typecheck && pnpm test
```
在发布UI更改之前运行管理员构建：
```bash
pnpm --dir web build
```
## 3条命令自托管
```bash
docker compose -f docker-compose.selfhost.yml up -d --build
curl http://localhost:3300/health
docker compose -f docker-compose.selfhost.yml run --rm poolstatis \
node dist/cli/bootstrap.js "Acme" acme "Acme产品"
```
然后打开 `http://localhost:8080` 并粘贴打印的 `sk_` 或 `pt_` token。
在 [docs/10-self-host.md](docs/10-self-host.md) 中查看完整的自托管指南。
## 托管设置
1. 打开托管管理员并在入职过程中创建第一个项目。
2. 保存一次性 `pt_` token用于MCP客户端和 `pk_` token用于摄入。
3. 在Claude Code、Claude Desktop、Codex、Cursor、Warp、Windsurf、VS Code/Copilot、Cline、Zed、Continue、Replit、OpenCode、Hermes-style启动器或任何兼容的自定义MCP主机中添加池统计作为MCP服务器。
```json
{
"mcpServers": {
"poolstatis": {
"command": "pnpm",
"args": ["--silent", "dlx", "@poolstatis/mcp"],
"env": {
"POOLSTATIS_URL": "https://api.poolstatis.com",
"POOLSTATIS_TOKEN": "pt_..."
}
}
}
}
```
`--silent` 是必需的，因为 `pnpm` 可以将横幅打印到stdout，这会破坏stdio MCP协议。
在 `@poolstatis/mcp` 发布之前，将上面的JSON视为发布就绪模板。托管部署应在配置实际MCP运行器命令和参数后公开复制粘贴设置。
通过摄入API发送产品事件：
```bash
curl -X POST https://api.poolstatis.com/i/v1/events \
-H 'Authorization: Bearer pk_...' \
-H 'content-type: application/json' \
-d '{"events":[{"event":"signup.completed","distinct_id":"u1"}]}'
```
## 平台管理员
`web/` 是一个最小的无头平台管理员。它不是每个项目的分析仪表盘；客户通过MCP、SDK集成或自己的仪表盘消费分析。
管理员包括项目、指标注册管理、数据健康、事件、实体、API密钥、入职和设置&MCP预设的表格。在托管模式下，通过Auth0/OIDC处理人类登录，而作用域池统计密钥保留运行时访问模型：
- `pk_` 摄入密钥仅可写入，产品客户端安全。
- `sk_` 机密密钥提供项目级平台访问。
- `pt_` 个人令牌提供组织范围的MCP访问。
## 状态
已实现：
- HTTP摄入API
- 语义指标注册
- 漏斗
- 实体
- `trend`、`funnel`、`entities`、`retention`、`lifecycle` 和 `stickiness` 的查询DSL
- 确定性特性标志、自动曝光事件和贝叶斯A/B实验结果，基于注册指标
- 具有类型化工具和资源的MCP服务器
- 无头管理员SPA
- 仪器标准
- 代理仪器技能
- Docker Compose自托管路径
下一个优先级在 [docs/05-gap-analysis.md](docs/05-gap-analysis.md) 中跟踪：actor合并和身份、静态群体、漏斗相关性、浏览器体验信号/交互映射和隐私门控会话重放插件。
