# 样板项目参考指南

> 版本: 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`：

```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: 部署

```bash
# 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"

### 第二步：清点模块

```bash
# 列出所有暴露 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 验证通过