From 3128db09c649e8c7bdd0cb1a3456303599ae888a Mon Sep 17 00:00:00 2001 From: hmo Date: Sun, 19 Jul 2026 10:19:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20TEMPLATE-GUIDE=20=E2=80=94=20how?= =?UTF-8?q?=20to=20use=20AgentsMeeting=20as=20reference=20template=20for?= =?UTF-8?q?=20new=20projects=20or=20refactoring?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 + docs/TEMPLATE-GUIDE.md | 203 +++++++++++++++++++++++++++++++++++++++++ docs/dev-spec.md | 2 + 3 files changed, 207 insertions(+) create mode 100644 docs/TEMPLATE-GUIDE.md diff --git a/README.md b/README.md index 80fb0e4..3751698 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ > 基于 XMPP 的统一通信系统。按平台（Windows/Linux/Mac）部署，Agent 实例化注册，管理门户统一监控。 > > **仓库**: [git.yoin.fun/hmo/AgentsMeeting](https://git.yoin.fun/hmo/AgentsMeeting) | **Dashboard**: [192.168.1.246:5803](http://192.168.1.246:5803) +> +> 📋 **样板参考**: [`docs/TEMPLATE-GUIDE.md`](docs/TEMPLATE-GUIDE.md) — 如何参照本项目搭建或重构你的项目 ### 当前已注册 Agent diff --git a/docs/TEMPLATE-GUIDE.md b/docs/TEMPLATE-GUIDE.md new file mode 100644 index 0000000..a441670 --- /dev/null +++ b/docs/TEMPLATE-GUIDE.md @@ -0,0 +1,203 @@ +# 样板项目参考指南 + +> 版本: 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/` 两个通用端点 + +**前端（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/` +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 验证通过 diff --git a/docs/dev-spec.md b/docs/dev-spec.md index 82c32b9..67c41b2 100644 --- a/docs/dev-spec.md +++ b/docs/dev-spec.md @@ -16,6 +16,8 @@ 4. **实现后同步 Spec** — 每轮开发完毕后，必须将 specs/{module}.json 更新为与实际实现一致的状态。文档过期 = 等于没写 5. **部署目标即验收标准** — 所有代码必须以部署目标环境（Linux 246）为基准编写和测试。在本地开发机器（Windows/Mac）上跑通不等于验收通过。部署脚本、系统工具（`systemctl`/`crontab`/`ss`/`df`）、Python 版本、文件路径等都必须匹配 246 的实际环境。禁止使用 Windows 专属 API（`tasklist`、`netstat`、`schtasks`、`wmic`）在 246 部署的代码中 +> 📋 如何用本项目做样板搭建新项目或重构旧项目 → [`TEMPLATE-GUIDE.md`](TEMPLATE-GUIDE.md) + --- ## 一、双轨同源规范体系