Skip to content

Latest commit

 

History

History
209 lines (145 loc) · 5.31 KB

Agent.md

File metadata and controls

209 lines (145 loc) · 5.31 KB

AI Tracer 部署指南

这是给 AI Agent（如 OpenClaw）的部署操作手册。请按顺序执行以下步骤，将 AI Tracer 部署到目标服务器上。

项目概述

AI Tracer 是一个自动化工具：

  • 每天 9:00 从 X(Twitter) 抓取 AI 领域推文，生成小红书风格图片日报，推送到企业微信
  • 每 30 分钟扫描一次推文，发现热点实时推送

Step 1: 环境检查

确认服务器上有以下工具，没有的需要安装：

# 检查 Node.js（需要 >= 18）
node --version

# 如果没有 Node.js，通过 nvm 安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

# 检查 git
git --version

Step 2: 克隆项目并安装依赖

git clone <repo_url> ~/ai-tracer
cd ~/ai-tracer
npm install

Step 3: 安装 CLI 工具

项目依赖两个全局 CLI 工具：

bird（Twitter 抓取工具）

npm install -g @steipete/bird

# 验证
bird --version
# 期望输出类似: 0.8.0

claude CLI（AI 能力）

目标服务器上需要有可用的 claude 命令。根据服务器环境安装：

# 验证
claude --version

重要：ai-client.ts 中调用的命令名是 claude-internal。如果目标服务器上的命令名不同（比如是 claude），需要修改 src/ai-client.ts 第 16 行的 spawn('claude-internal', args) 为实际的命令名。

Step 4: 配置环境变量

cd ~/ai-tracer
cp .env.example .env

编辑 .env，填入以下内容：

# [必填] Twitter 认证 — 从浏览器登录 X 后的 Cookie 中获取
# 浏览器 → 开发者工具(F12) → Application → Cookies → x.com
# 找到 auth_token 和 ct0 的值
TWITTER_AUTH_TOKEN=<填入 auth_token 值>
TWITTER_CT0=<填入 ct0 值>

# [可选] X Lists ID（扩展信息源，逗号分隔）
X_LISTS=

# [可选] 企业微信群机器人 Webhook URL
WECOM_WEBHOOK_URL=<填入 webhook URL>

部署者需要提供这三个值。Twitter Cookie 有效期有限，过期后需要重新获取。

Step 5: 安装中文字体

卡片渲染需要中文字体。项目使用 Hiragino Sans GB，字体文件应放在 fonts/ 目录：

ls ~/ai-tracer/fonts/
# 期望看到: Hiragino Sans GB.ttc

如果 fonts/ 目录为空（字体文件未提交到 git），需要从其他机器拷贝 Hiragino Sans GB.ttc 到 fonts/ 目录。

备选方案：如果无法获取该字体，可以安装系统中文字体包：

# Ubuntu/Debian
sudo apt-get install -y fonts-noto-cjk

# CentOS/RHEL
sudo yum install -y google-noto-sans-cjk-fonts

然后修改 src/card-renderer.ts 中的字体名称为系统可用的中文字体。

Step 6: 验证安装

cd ~/ai-tracer

# 初始化目录结构
npm run dev -- init

# 测试抓取（应该能看到推文数量输出）
npm run dev -- fetch -n 10

# 测试热点雷达（需要先有推文数据）
npm run dev -- monitor

# 测试完整日报（耗时较长，约 2-3 分钟）
npm run dev -- run

每一步都应该正常完成，无报错。如果企业微信配置正确，你应该能在群里收到推送。

Step 7: 配置定时任务

crontab -e

添加以下两行（注意替换 Node.js 路径）：

# 每天 9:00 UTC：完整日报 pipeline
0 9 * * * cd ~/ai-tracer && PATH=$(dirname $(which node)):$PATH npm run dev -- run >> ~/ai-tracer/cron.log 2>&1

# 每 30 分钟：热点雷达（自动抓取 + AI 扫描 + 推送）
*/30 * * * * cd ~/ai-tracer && PATH=$(dirname $(which node)):$PATH npm run dev -- monitor >> ~/ai-tracer/cron_monitor.log 2>&1

注意：cron 环境的 PATH 可能找不到 node/bird/claude，所以需要显式设置。最可靠的方式是用绝对路径：

# 查看实际路径
which node   # 例如 /home/ubuntu/.nvm/versions/node/v22.15.1/bin/node

然后把 cron 里的 PATH 设为该 bin 目录。

验证 cron 生效：

# 查看当前 crontab
crontab -l

# 等几分钟后检查日志
tail -f ~/ai-tracer/cron_monitor.log

Step 8: 日常维护

Twitter Cookie 过期

Cookie 会定期过期，表现为 fetch 报错。需要重新从浏览器获取 auth_token 和 ct0，更新 .env。

查看日志

# 日报日志
tail -100 ~/ai-tracer/cron.log

# 热点雷达日志
tail -100 ~/ai-tracer/cron_monitor.log

手动重跑

# 重新生成今天的日报
cd ~/ai-tracer && npm run dev -- run

# 手动触发一次热点扫描
cd ~/ai-tracer && npm run dev -- monitor

清理数据

# 清理旧的原始推文（保留最近 7 天）
find ~/ai-tracer/data/raw -name "*.json" -mtime +7 -delete

# 清理旧的输出
find ~/ai-tracer/output -name "*_cards" -type d -mtime +7 -exec rm -rf {} +

常见问题

问题 原因 解决
bird 命令执行失败 Twitter Cookie 过期 重新获取 auth_token 和 ct0
claude-internal 启动失败 CLI 命令名不匹配 检查实际命令名，修改 src/ai-client.ts
卡片上中文是方块 缺少中文字体 安装字体到 fonts/ 或安装系统字体包
cron 不执行 PATH 问题 在 cron 中显式设置 Node.js 的 bin 路径
企业微信推送失败 Webhook URL 错误或机器人被禁 检查 .env 中的 URL，确认机器人在群内