docs: add TEMPLATE-GUIDE — how to use AgentsMeeting as reference template for new projects or refactoring

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
 

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/<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 验证通过

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)
+
 ---
 
 ## 一、双轨同源规范体系