内容
# SanTech 内容引擎
SanTech010 的本地优先 YouTube 研究到脚本引擎。
后端执行确定性工作：YouTube 数据抓取、存储、异常值计算、数据包构建、验证、保存/选择/导出和 MCP 工具暴露。连接的 AI 客户端使用后端数据包作为真实来源，执行创造性和判断性工作。
当前状态：离线后端、MCP 主干、配额守卫、资源导入、仅最近的异常值、早期速度信号、组合信号报告和信号目标转录获取已实现。
重要的 MCP 规则：`get_signal_research_pack` 读取当前本地数据库。它不拉取新的 YouTube 数据。使用 `get_project_status` 检查新鲜度，然后在 `recommended_next_action` 表示 `refresh_youtube_data` 或 `calculate_signals` 时使用 `refresh_research_data`。
验证：
```powershell
python -m pytest tests -q
python -m compileall -q src
```
## 新笔记本设置
在新的 Windows 笔记本上：
```powershell
git clone git@github.com:budhasantosh010/san-tech-yt-research-titles-scripts.git
Set-Location -LiteralPath ".\san-tech-yt-research-titles-scripts"
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\bootstrap-windows.ps1
```
然后在本地编辑 `.env` 并添加：
- `YOUTUBE_API_KEYS`
- `MCP_ROUTE_SECRET`
- `ALLOWED_HOSTS` 以及您的 Tailscale Funnel 主机名
不要提交 `.env`。
在任何笔记本上推送之前：
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\check-github-ready.ps1
```
完整的再现性说明位于 `DOCS/FUTURE_PROOF_SETUP.md` 中。
## 每日 MCP 启动
使用两个 PowerShell 终端。
终端 1：
```powershell
$project = "C:\Users\Lenovo\Music\Startups\YT Automations\1 San Tech Channel Research, Title & Script with Codex"
Set-Location -LiteralPath $project
.\scripts\run-mcp-http.ps1
```
终端 2：
```powershell
$project = "C:\Users\Lenovo\Music\Startups\YT Automations\1 San Tech Channel Research, Title & Script with Codex"
Set-Location -LiteralPath $project
.\scripts\start-funnel.ps1
```
良好的 Funnel 输出应显示：
```text
proxy http://127.0.0.1:3001
```
## ChatGPT 连接器 URL 格式
使用以下格式：
```text
https://<机器>.<尾网>.ts.net/mcp/您的路由密钥/
```
切勿在路由密钥周围添加括号。
正确：
```text
https://desktop-fdce9ak.taila47816.ts.net/mcp/abc123.../
```
错误：
```text
https://desktop-fdce9ak.taila47816.ts.net/mcp/<abc123...>/
```
在 ChatGPT 中一次使用一个工具调用。不要并行使用工具调用。对于连接测试，只需调用 `get_project_status`。
实现：
- SQLite 架构
- 配置加载器
- 竞争对手存储
- 视频/快照存储
- 仅最近的异常值数学和持久性
- 早期速度信号数学和持久性
- YouTube 数据 API 适配器，带有假客户端测试
- 用于 CSV/XLSX 的病毒标题集合导入器
- 视频创意保存/列表/选择
- 标题创意保存/列表/选择
- 脚本要点保存/选择
- 上下文包构建器
- 转录保存/获取/列表缺失存储
- 信号目标转录获取适配器
- 转录获取尝试跟踪
- 转录感知异常研究包
- 脚本保存/导出
- FastMCP 服务器包装器
- 工作流提示模板
仍需要实时/用户提供的输入：
- `YOUTUBE_API_KEY`
- `YOUTUBE_API_KEYS` 用于逗号分隔的多个密钥
- 竞争对手频道列表
- 真实的病毒标题/视频集合文件
- ChatGPT MCP 连接器/隧道设置
配额安全：
- `YOUTUBE_MAX_DAILY_QUOTA_FRACTION=0.05` 将应用程序限制为每个密钥配置的每日配额的 5%。
- `YOUTUBE_CACHE_MAX_AGE_HOURS=24` 防止刷新视频详细信息/快照。
- `RESEARCH_STALE_AFTER_HOURS=24` 控制 `get_project_status` 何时警告研究数据已过时。
- API 密钥位于 `.env` 中，该文件被 Git 忽略。
资源文件：
- 竞争对手真实来源：`resources/competitors/santech_competitors.txt`
- 病毒标题：`resources/viral titles in adjacent niches`
竞争对手 TXT 格式：
- 每行一个绝对的 YouTube 频道 URL
- 没有显示名称
- 没有注释
- 没有逗号
- 没有复制的 YouTube 搜索/导出行
可以将 CSV/XLSX/MD/TXT 文件检查/导入，但不要用作规范的竞争对手来源。如果同步源有零个文件、零行或零个有效的 YouTube 频道 URL，则出于安全考虑，停用将被跳过。
### 信号工作流
当前确定性工作流：
1. 从 `resources/competitors/santech_competitors.txt` 同步竞争对手列表，当 TXT 源更改时。
2. 从 `resources/viral titles in adjacent niches` 同步病毒标题集合，当工作表/文件更改时。
3. 刷新 YouTube 数据并为每个集合运行保存新的快照行。
4. 计算最近的异常值。
5. 计算早期速度。
6. 转储组合信号报告。
7. 仅为选定的信号目标获取转录。
8. 构建转录感知的研究包。
9. 稍后，ChatGPT 分析并生成创意/标题/脚本。
MCP 工具边界：
- `sync_competitors_from_file` 将竞争对手工作表/文件视为真实来源，默认情况下停用缺失的频道。它不会删除旧行。
- `sync_viral_collection` 将病毒标题工作表/文件视为真实来源，默认情况下存档缺失的行。它不会删除旧行。
- `refresh_research_data` 是每日操作工具。它可以收集 YouTube 统计数据并重新计算异常值/速度信号。它不会获取转录。
- `get_signal_research_pack` 是 ChatGPT 应该在新鲜度可接受后使用的读取工具。
- `mark_signal_reviewed` 可以将信号标记为 `reviewed`、`approved`、`rejected`、`used` 或 `suppressed`；默认报告排除已审查/拒绝/使用/抑制的信号。
最近的异常值意味着最近的视频已经超过了该频道的最近基线。
早期速度意味着新视频正在异常快速移动，并可能成为异常值。
真正的近期速度需要至少两个快照。如果只有一个快照存在，系统使用生命周期速度作为粗略的回落。
规范的竞争对手来源：
```powershell
python -m santech_engine.cli sync-competitors --file resources/competitors/santech_competitors.txt --no-deactivate-missing
```
信号命令：
```powershell
python -m santech_engine.cli collect-all --limit 10
python -m santech_engine.cli calculate-outliers --recent-only --all-competitors
python -m santech_engine.cli list-outliers --limit 5
python -m santech_engine.cli dump-outlier-report --limit 20 --output exports/recent-outliers.json
python -m santech_engine.cli calculate-velocity --all-competitors
python -m santech_engine.cli list-velocity-signals --limit 10
python -m santech_engine.cli dump-velocity-report --limit 20 --output exports/early-velocity.json
python -m santech_engine.cli dump-signal-report --output exports/signal-report.json
python -m santech_engine.cli fetch-transcripts-for-signal-targets --adapter youtube_transcript_ai --limit-outliers 5 --limit-velocity 5
```
### 转录获取
该项目支持转录感知的研究包。
系统不会为每个竞争对手视频获取转录。
流程：
1. 收集竞争对手视频。
2. 计算最近的异常值和早期速度。
3. 仅为组合信号目标获取转录。
4. 缓存成功的转录。
5. 诚实地标记缺失/失败的转录。
6. 仅当可用时，在异常值包中包含实际转录文本。
默认适配器：
- `youtube_transcript_ai`
备用适配器：
- `youtube_transcript_io` 如果设置了 `YOUTUBE_TRANSCRIPT_IO_API_TOKEN`
手动回退：
- 如果自动获取失败，重要的异常值，用户可以将转录文本粘贴到 ChatGPT 中。
- 然后，ChatGPT 可以通过 MCP 调用 `save_video_transcript` 来缓存它。
警告：
- 转录提供商不是官方的 YouTube 数据 API。
- 它们可能会失败或更改。
- 不要使用激进的抓取/代理绕过。
- 保持获取量低和信号优先。
- 系统不得仅凭标题/指标推断或发明视频内容。
有用本地命令：
```powershell
python -m santech_engine.cli import-competitors
python -m santech_engine.cli import-viral-collection
python -m santech_engine.cli doctor
python -m santech_engine.cli setup-env
python -m santech_engine.cli test-transcript-provider --adapter youtube_transcript_ai
python -m santech_engine.cli smoke-test
python -m santech_engine.cli collect-all --limit 5
python -m santech_engine.cli calculate-outliers --recent-only --all-competitors
python -m santech_engine.cli calculate-velocity --all-competitors
python -m santech_engine.cli dump-signal-report --output .\exports\signal-report.json
python -m santech_engine.cli fetch-transcripts-for-signal-targets --adapter youtube_transcript_ai --limit-outliers 5 --limit-velocity 5
python -m santech_engine.cli transcript-status --video-id 123
python -m santech_engine.cli list-transcript-attempts --limit 20
python -m santech_engine.cli save-transcript --video-id 123 --file .\transcript.txt
python -m santech_engine.cli dump-outlier-pack --include-transcripts --output .\exports\outlier-pack.json
python -m santech_engine.cli dump-title-pack --idea-id 1 --output .\exports\title-pack.json
python -m santech_engine.cli dump-script-pack --title-id 1 --output .\exports\script-pack.json
```
在本地运行 MCP 服务器：
```powershell
python -m santech_engine.mcp_server
```
### 通过 Tailscale Funnel 的 ChatGPT MCP
仅在本地后端数据包真实时使用此功能。
1. 创建本地 `.env`：
```powershell
Copy-Item .env.example .env
```
2. 在 `.env` 中设置 MCP 桥接值。
```env
MCP_HOST=127.0.0.1
MCP_PORT=3001
MCP_ROUTE_SECRET=<您的长密钥>
MCP_BEARER_TOKEN=
ALLOWED_ORIGINS=https://chatgpt.com,https://chat.openai.com
ALLOWED_HOSTS=127.0.0.1,localhost,<您的机器>.<您的尾网>.ts.net
FUNNEL_BASE_URL=
```
规则：
- 至少 32 个字符。
- 不要提交 `.env`。
- 不要将密钥粘贴到文档中。
- 保持 `MCP_BEARER_TOKEN` 为空，如果 ChatGPT 连接器使用 `Authentication: No Auth`。
- 将您的真实 Tailscale Funnel 主机名添加到 `ALLOWED_HOSTS`。
3. 运行 HTTP 桥接医生：
```powershell
.\scripts\doctor-mcp-http.ps1
```
4. 启动本地 MCP HTTP 服务器：
```powershell
.\scripts\run-mcp-http.ps1
```
5. 在另一个终端中，启动 Tailscale Funnel：
```powershell
.\scripts\start-funnel.ps1
```
6. 将此 URL 添加为 ChatGPT 自定义连接器 URL：
```text
https://<机器>.<尾网>.ts.net/mcp/<MCP_ROUTE_SECRET>
```
使用您的真实 Tailscale Funnel 主机名和本地路由密钥值。
7. 在 ChatGPT 中测试：
```text
get_project_status
```
8. 然后测试主要研究包：
```text
get_signal_research_pack
```
预期路由：
```text
ChatGPT 自定义连接器
-> Tailscale Funnel HTTPS URL
-> http://127.0.0.1:3001/mcp/<MCP_ROUTE_SECRET>
-> SanTech MCP 工具
-> SQLite / YouTube API / 转录提供商
```
安全注意事项：
- Python 服务器仅绑定到 `127.0.0.1`。
- 默认 SanTech MCP HTTP 端口是 `3001`。
- MCP 路由安装在 `/mcp/<MCP_ROUTE_SECRET>` 下。
- 允许的来源默认为 `https://chatgpt.com` 和 `https://chat.openai.com`。
- 允许的主机默认为 `127.0.0.1` 和 `localhost`；通过 `ALLOWED_HOSTS` 或 `FUNNEL_BASE_URL` 添加 Tailscale Funnel 主机名。
- 如果另一个 MCP 桥接器（例如 X/Spectre 桥接器）使用相同的 Tailscale Funnel 根主机名，请一次仅运行其中一个通过该公共根。
- 脚本和医生检查不会打印 API 密钥、承载令牌或 MCP 路由密钥。
- 使用以下命令停止 Funnel：
```powershell
.\scripts\stop-funnel.ps1
```
