OpenIsle/bots/AGENTS.md

Bots 协作指引

1) 适用范围

• 作用于 bots/ 目录及其子目录。
• 本文件用于统一 Bot 脚本开发、调度与发布规范。

2) 模块结构与职责

• bot_father.ts：Bot 基类，统一 Agent 初始化、MCP 工具接入、CLI 运行入口。
• instance/reply_bot.ts：常规互动回复 Bot（提及/评论自动处理）。
• instance/open_source_reply_bot.ts：开源问答 Bot（偏代码与贡献流程）。
• instance/daily_news_bot.ts：每日新闻帖 Bot。
• instance/coffee_bot.ts：早安抽奖帖 Bot。

3) 开发约定（新增/改造 Bot）

• 新 Bot 统一继承 BotFather，最少实现：
  • getAdditionalInstructions()
  • getCliQuery()
• 保持导出约定：export const runWorkflow = ...，并保留 if (require.main === module) CLI 入口。
• 不随意改动 bot_father.ts 的 MCP 工具白名单；若必须调整，需同步评估 mcp/ 契约与线上可用性。

4) 环境变量与密钥规范

• 必需：OPENAI_API_KEY（缺失会直接失败）。
• 常用：
  • OPENISLE_TOKEN（用于 OpenIsle MCP 鉴权；GitHub Actions 中可映射不同 secret）
  • APIFY_API_TOKEN（天气 MCP 鉴权）
• News Bot 可选参数：
  • DAILY_NEWS_CATEGORY_ID
  • DAILY_NEWS_TAG_IDS
• 严禁在代码中硬编码真实 token；仅通过 CI secrets 或本地环境变量注入。

5) 工作流同步规则（与 GitHub Actions 对齐）

• 相关工作流：
  • .github/workflows/reply-bots.yml
  • .github/workflows/open_source_reply_bot.yml
  • .github/workflows/news-bot.yml
  • .github/workflows/coffee-bot.yml
• 若改脚本入口、依赖或 env 键名，必须同步更新对应 workflow。
• 若改触发节奏（cron）或 Bot 行为边界，需在变更说明中写明影响（频率、成本、风险）。

6) 行为约束（防重复/防失控）

• 回复类 Bot 需保持幂等：避免对同一上下文重复回复。
• 处理未读后应调用 mark_notifications_read 清理通知。
• 批量处理建议保持上限（当前提示词约定为最多 10 条）。
• 发帖类 Bot（news/coffee）必须控制 create_post 调用次数（一次任务最多一次发帖）。
• Open Source Reply Bot 保持专业技术风格，避免跑题到非开源问答。

7) 本地验证建议

• 依赖安装（与 CI 一致）：
  • npm install --no-save @openai/agents tsx typescript
• 单脚本运行示例：
  • npx tsx bots/instance/reply_bot.ts
  • npx tsx bots/instance/open_source_reply_bot.ts
  • npx tsx bots/instance/daily_news_bot.ts
  • npx tsx bots/instance/coffee_bot.ts
• 验证时至少确认：可启动、可调用 MCP、异常时退出码非 0。

8) 输出要求

• 说明改动影响哪个 Bot、哪个 workflow。
• 说明是否改变了工具调用边界（MCP tools / 发帖次数 / 回复策略）。
• 说明是否需要同步更新文档或运维配置。