agent-hq

核心用法

Agent HQ 是一个完整的任务控制面板部署方案，采用 Express 后端 + React 前端的技术架构。用户通过克隆 GitHub 仓库、安装依赖、构建前端、配置 Telegram 机器人令牌后即可启动服务。系统提供 SQLite 数据持久化、、data/board.json 数据种子、以及完整的 REST API 接口用于卡片创建和状态管理。核心自动化能力包括：Jarvis 摘要生成器（scripts/jarvis-connector.js）和 Telegram 通知器（scripts/notify-jarvis-telegram.js），配合 cron 定时任务实现高优先级任务监控与告警推送。

显著优点

1. 开箱即用的完整方案：前后端、数据库、通知系统一体化打包，无需从零搭建基础设施
2. 灵活的集成接口：提供 POST /api/cards/quick 等快捷端点，支持脚本化、自动化任务录入
3. 多通道通知能力：原生集成 Telegram Bot API，支持实时告警推送
4. 数据可移植性：JSON 种子文件 + SQLite 双模式，便于备份、迁移和版本控制
5. 权限保护机制：AGENT_HQ_API_TOKEN 环境变量保护敏感变更端点

潜在缺点与局限性

1. 单点部署架构：默认单机 SQLite 模式，无内置高可用或集群支持，大规模团队可能遇到性能瓶颈
2. Telegram 强依赖：通知功能完全依赖 Telegram 平台，企业内网环境或 Telegram 受限地区使用受限
3. 前端构建复杂度：需要单独构建 React 前端（npm --prefix frontend-react run build），对纯后端运维人员不够友好
4. 缺乏身份认证体系：除 API Token 外无用户登录/权限分级机制，多团队共用场景下存在越权风险
5. 文档化交付：当前 Skill 为纯部署指南，实际运行时仍需用户自行维护 Node.js 进程和 cron 任务

适合的目标群体

• 中小技术团队：需要快速搭建内部任务看板，但不愿投入大量开发资源的工程团队
• Clawdbot/Agent 生态用户：已在使用 Jarvis 等 AI 助手，希望统一任务入口的自动化团队
• DevOps/运维工程师：需要可脚本化的任务录入接口和告警通道的基础设施负责人
• 开源爱好者：希望基于 Express/React 二次开发自定义 mission-control 系统的开发者

使用风险

1. 配置泄露风险：Telegram Bot Token 和 Chat ID 需严格保密，误提交至版本控制将导致机器人被滥用
2. 进程稳定性：Node.js 服务需配合 pm2/systemd 等进程管理工具，否则崩溃后无自动恢复
3. 数据库并发限制：SQLite 在高并发写入场景下可能出现锁竞争，建议监控 mission.db 文件大小
4. 依赖更新滞后：npm 依赖长期未更新可能引入安全漏洞，需定期执行 npm audit
5. 网络可达性：Telegram API 在某些网络环境下需代理配置，否则通知功能失效

核心用法

Agent HQ 是一套开源的任务指挥中心技术栈，专为需要集中管理多任务、多代理团队的场景设计。用户通过克隆 GitHub 仓库即可在本地或服务器部署完整的 Express 后端（SQLite 数据持久化）和 Vite/React 前端界面。系统核心包含三大自动化组件：任务板可视化 UI、Jarvis 智能摘要脚本（scripts/jarvis-connector.js）以及 Telegram 通知机器人（scripts/notify-jarvis-telegram.js）。

部署流程简明：安装依赖后配置 Telegram Bot Token（支持环境变量注入），构建前端并启动服务（默认 4000 端口），随后通过 cron 定时任务启用心跳检测和通知推送。API 层提供完整的 REST 端点支持任务卡片增删改查、快速创建（/api/cards/quick）及手动触发 Telegram 警报。

显著优点

• 开箱即用的一体化方案：前后端、数据库、自动化脚本一次性配齐，无需拼凑多个工具
• 灵活的触发机制：支持 UI 操作、API 调用、cron 定时任务三种交互方式
• 环境变量友好：Telegram 等敏感配置可通过 AGENT_HQ_TELEGRAM_* 环境变量注入，避免硬编码泄露
• 防重复通知设计：SQLite 的 high_priority_jobs 表内置去重逻辑
• API Token 保护：AGENT_HQ_API_TOKEN 可为变更端点添加鉴权层

潜在缺点与局限性

• T3 来源风险：作者为个人开发者（thibautrey），非知名组织或基金会维护，长期更新承诺存疑
• 本地开发假设重：文档大量示例基于 localhost:4000，生产环境需自行解决 HTTPS、域名、反向代理等配置
• SQLite 并发瓶颈：默认数据库在团队规模扩大后可能遇到锁竞争
• 无内置用户体系：缺乏 RBAC、OAuth 等企业级权限管理
• Telegram 单通道依赖：通知渠道单一，无邮件/Slack/企业微信等备选方案

适合人群

• 5-20 人的敏捷开发小组或 AI 代理研究团队
• 需要快速搭建任务看板但不想订阅 SaaS 的极客团队
• 已将 Telegram 作为主力工作沟通工具的组织
• 具备 Node.js 部署经验、能自行处理运维细节的开发者

常规风险

1. 配置泄露：config/telegram.json 若误提交至 Git 将导致 Bot Token 暴露，必须使用 .gitignore 或纯环境变量方案
2. HTTP 明文传输：文档示例未强制 TLS，生产环境若直接暴露 4000 端口存在中间人攻击风险
3. API Token 弱密码：若设置的 AGENT_HQ_API_TOKEN 过于简单，外部可轻易伪造请求篡改任务板
4. SQLite 数据丢失：未配置自动备份时，单文件数据库损坏将导致全量数据丢失
5. 依赖供应链：npm install 拉取的依赖包需定期审计，防范上游包被投毒