204 lines
6.8 KiB
Markdown
204 lines
6.8 KiB
Markdown
# 样板项目参考指南
|
||
|
||
> 版本: 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 验证通过
|