AgentsMeeting/docs/TEMPLATE-GUIDE.md

样板项目参考指南

版本: v1.0 | 基于 AgentsMeeting 实践

---

一、这个项目示范了什么

AgentsMeeting 不仅是多智能体通信系统，更是一套可复制的工程实践。以下模式可以直接搬到任何需要长期维护的 AI 辅助开发项目：

模式	体现	价值
Spec 双轨	gateway/scripts/specs/*.json → ?§ 按钮	AI 和人类共享同一份接口文档，不过期
三层健康管线	Tier1 → TODO → Tier3 → auto_heal	监控自动化到可以无人值守
Dashboard 统一入口	单页 Web UI，所有信息聚合	不黑盒、不可见即不存在
部署即验收	代码以生产环境（Linux 246）为准	杜绝"本地跑通但部署就炸"
crontab 调度	所有定时任务用 crontab，不用 systemd timer	简单、可观测、一行命令部署

---

二、五条红线（开发规范核心）

来自 docs/dev-spec.md，每一行都是血的教训：

1. 先读/写 Spec，再写代码 — 没有 spec 的模块在 Dashboard 不可见，视为未完成
2. 部署必验 — 部署后不打开 K Tab 验证 = 部署未完成
3. 不可见即不存在 — 组件不在 Dashboard 中显示 = 等于没部署
4. 实现后同步 Spec — 代码改了但 spec 没改 = 文档过期 = 等于没写
5. 部署目标即验收标准 — 禁止生产代码中出现 Windows 专属 API

---

三、新项目搭建流程

Step 1: 复制核心结构

my-project/
├── gateway/
│   ├── scripts/
│   │   ├── dashboard.py          # Flask 单文件后端
│   │   ├── templates/
│   │   │   └── dashboard.html    # 单文件前端（深色主题）
│   │   └── specs/                # Spec 文件目录
│   │       └── {module}.json
│   ├── logs/                     # 运行时日志
│   └── temp/                     # 临时文件（JSON 报告、TODO）
├── docs/
│   ├── dev-spec.md               # 开发规范（含五条红线）
│   ├── ARCHITECTURE.md           # 架构设计
│   ├── DEPLOY.md                 # 部署指南
│   ├── HEALTH-PIPELINE.md        # 健康管线文档
│   ├── DASHBOARD.md              # Dashboard API 参考
│   └── QUICKSTART.md             # 快速操作
├── config/                       # 配置文件
└── README.md                     # 项目入口

Step 2: 定制 Dashboard

后端（dashboard.py）:

• 复制 AgentsMeeting 的 dashboard.py 作为骨架
• 修改服务列表、Agent 注册方式
• 添加项目特有的 API 端点
• 保持 /api/monitor、/api/module-spec/<module> 两个通用端点

前端（dashboard.html）:

• 复制深色主题 CSS 变量（:root 块）
• 复制 showModuleHelp() 函数（?§ 系统核心）
• 自定义 Tab 结构（T 数组）
• 添加项目特有的面板

Step 3: 建立 Spec 体系

为每个模块创建 specs/{module}.json：

{
  "module": "模块名",
  "version": "1.0",
  "purpose": "一句话",
  "human_help": {
    "title": "人类标题",
    "description": ["说明"],
    "usage": ["怎么用"],
    "troubleshooting": ["常见问题"]
  },
  "ai_spec": {
    "apis": [{"method": "GET", "path": "/api/x", "returns": "说明"}],
    "dependencies": ["依赖列表"],
    "constraints": ["AI 必须遵守的约束"],
    "related_files": ["相关文件路径"]
  }
}

规则:

• 每个暴露 API 的模块必须有 spec
• 每个在 Dashboard 上有 ?§ 按钮的模块必须有 spec
• Spec 文件名 = module 字段值 = Dashboard 引用的名字

Step 4: 搭建健康管线

复制三件套，改服务列表：

脚本	频率	改什么
agents_health_check.py	*/5	SERVICES 列表（名称/端口/health_url）
agents_daily_health.py	0 8	SERVICES + EXPECTED_CRON + 磁盘阈值
auto_heal.py	*/5	SERVICE_UNIT_MAP（服务名 → systemd 单元）
self_todo_executor.py	*/10	FIX_MAP（服务名 → 修复命令）

部署到 crontab 后，Dashboard 的 /api/monitor 自动读取报告文件。

Step 5: 部署

# 1. 部署 Dashboard
sudo cp deploy/my-project.service /etc/systemd/system/
sudo systemctl enable --now my-project

# 2. 部署健康管线
(crontab -l; echo '*/5 * * * * cd /path && python3 health_check.py >> logs/health.log 2>&1') | crontab -

# 3. 验证
curl http://127.0.0.1:5803/api/health
curl http://127.0.0.1:5803/api/monitor | python3 -m json.tool

---

四、旧项目重构流程

第一步：建立开发规范

1. 在项目根目录创建 docs/dev-spec.md，写入五条红线
2. 确定生产环境是哪个机器/哪个目录
3. 在 README 中标注 "部署目标: XXX"

第二步：清点模块

# 列出所有暴露 API 的模块
grep -r "@app.route\|@router\." --include="*.py" .

# 列出所有定时任务
crontab -l

对每个模块判断：有没有 spec？没有就补一个。

第三步：搭建 Dashboard

最简单的起步方式：

1. 复制 AgentsMeeting 的 dashboard.html（修改 CSS 颜色即可换皮）
2. 写一个最小 dashboard.py：只有 /api/health + /api/services + /api/module-spec/<module>
3. 部署上去，打开浏览器确认能看到

第四步：接入健康管线

1. 写 agents_health_check.py：把现有服务列进去
2. 加到 crontab，跑一次确认
3. Dashboard 的监控面板就能看到数据了

第五步：逐步迁移

优先级：监控 > 文档 > 重构

• 先让系统可见（Dashboard + 健康检查）
• 再让系统可理解（补 spec）
• 最后才重构代码（有了监控和文档，重构才有安全网）

---

五、检查清单

新项目或重构完成后，逐项打勾：

基础

• docs/dev-spec.md 存在，含五条红线
• README.md 标注部署目标和环境
• docs/ARCHITECTURE.md 或等效架构文档
• docs/DEPLOY.md 含部署步骤
• docs/QUICKSTART.md 含常用操作命令

Spec 体系

• 每个暴露 API 的模块有 specs/{module}.json
• 每个 spec 含 human_help 和 ai_spec 两部分
• Dashboard 上相关模块显示 ?§ 按钮
• 按钮点击能正确弹出帮助内容

监控管线

• agents_health_check.py 覆盖所有关键服务
• auto_heal.py 能修复本机可重启的服务
• 所有定时任务在 crontab 中
• Dashboard /api/monitor 返回正确数据
• F Tab（或等效面板）显示定时任务状态为绿色

部署

• Dashboard 通过 systemd 守护（或等效进程管理）
• 代码仓库 HEAD = 部署环境 HEAD
• 代码中无 Windows 专属 API（tasklist/netstat/schtasks）
• 部署后实际打开 Dashboard 验证通过