6.4 KiB
6.4 KiB
开发规范
版本: v2.2 | 更新: 2026-07-17
核心理念
"手脚架降低智商要求" — 不是靠人记住所有规则，而是靠系统让正确路径成为最容易的路径。
三条红线：
- 先写 Spec，再写代码 — 没有 spec 的模块在 dashboard 不可见，视为未完成
- 部署必验 — 部署后不打开 K Tab 验证 = 部署未完成
- 不可见即不存在 — 组件不在 dashboard 中显示 = 等于没部署。离线不告警 = 监控缺陷
- 实现后同步 Spec — 每轮开发完毕后，必须将 specs/{module}.json 更新为与实际实现一致的状态。文档过期 = 等于没写
一、双轨同源规范体系
每新增/修改一个独立功能模块，必须先写 specs/{module}.json。
一个来源同时产出两套文档：
specs/usage_monitor.json
├── human_help → ? 按钮（人类看说明/排错）
└── ai_spec → § 按钮（AI 看接口/约束/依赖）
什么算一个模块
满足以下任一条件即视为独立模块，必须写 spec：
- 暴露独立的 HTTP API 端点
- 在 Dashboard 上有独立 UI 面板（
?+§按钮） - 有独立的配置文件 / 数据文件
- 可独立部署（如 bot、gateway、定时任务）
Spec 字段标准
{
"module": "模块名（与 Dashboard 引用名一致）",
"version": "1.0",
"purpose": "一句话说明这个模块干什么",
"human_help": {
"title": "面向人类的标题",
"description": ["说明段落数组"],
"usage": ["使用步骤数组"],
"troubleshooting": ["常见问题数组"]
},
"ai_spec": {
"apis": [
{"method": "GET", "path": "/api/xxx", "returns": "返回值说明"}
],
"dependencies": ["依赖的服务或文件"],
"constraints": ["AI 必须遵守的约束"],
"must_not": ["AI 绝对不能做的事"],
"tests": [{"id": "T1", "name": "测试用例名"}],
"related_files": ["实现文件路径"]
}
}
当前模块清单
| 模块 | spec | 状态 |
|---|---|---|
| usage_monitor | specs/usage_monitor.json |
✅ |
| easytier | specs/easytier.json |
✅ |
| rdp | specs/rdp.json |
✅ |
| （新增模块） | 待创建 |
二、验证闭环
┌────────────┐ ┌──────────┐ ┌──────────┐
│ G: 规范体系 │────→│ K: 测试 │────→│ F: 健康 │
│ 定义期望 │ │ 验证实现 │ │ 持续监控 │
└────────────┘ └──────────┘ └──────────┘
↑ │
└────────────────────────────────┘
发现偏差 → 更新 Spec
H: 需求文档 — 双轨体系覆盖不到的架构级/跨模块需求（性能、安全、可用性等）
G — 开发规范（Dashboard G Tab）
- 本文档，展示在 Dashboard G Tab
- 包含：双轨同源体系、验证闭环、开发流程
- Dashboard G Tab 底部展示历史版本（
git log）
K — 自动测试（Dashboard K Tab）
tests_api.py自动执行 20+ 项系统检测- Dashboard K Tab 实时展示 PASS/FAIL/EXPECTED
- 部署后必做：打开 K Tab 确认全部通过或已知失败原因
- 新增模块时应在
ai_spec.tests中添加对应的测试标识
F — 系统健康度（Dashboard F Tab）
- 期望矩阵：应该运行的服务 vs 实际状态（Dashboard F Tab）
- 监控数据：Tier1（5min）/ Tier2（日报）作为实时状态输入
- 服务拓扑：所有服务的健康、端口、看门狗状态
H — 需求文档（Dashboard H Tab）
- 存放于
docs/PRD.md - 只描述模块级 spec 覆盖不到的总体性需求（架构约束、可用性、安全、性能基准）
- 具体功能需求全部通过双轨体系
specs/*.json描述 - Dashboard H Tab 底部展示历史版本（
git log）
三、开发流程
新增功能流程
确定模块边界
│
├─ 1. 创建 specs/{module}.json
│ human_help + ai_spec
│
├─ 2. 实现功能代码
│ 包含 /health 端点 + PID 锁（proc_guard）
│
├─ 3. 注册到系统
│ - 端口注册（agents.yaml 或硬编码）
│ - 添加到期望矩阵（F Tab 自动检测）
│
├─ 4. 编写测试
│ - ai_spec.tests 添加对应测试标识
│ - 或在 tests_api.py 添加测试用例
│
├─ 5. 同步更新 Spec
│ - 将 specs/{module}.json 的 api/constraints/dependencies/architecture
│ 更新为与实际实现一致
│ - 删除过时的描述，修正错误的假设
│ - 新增的字段、端点、配置项必须在 spec 中体现
│
└─ 6. 提交 → 部署 → 验证
即以下"操作规范"
Git 操作规范
| # | 规则 | 说明 |
|---|---|---|
| 1 | 开工前必 pull | git pull --rebase 确保基于最新代码 |
| 2 | 改完即 commit | 一个逻辑单元一次提交。禁止含密钥 |
| 3 | 推前必拉 + 配代理 | push 前 git pull --rebase。远程操作前配 :15000 代理 |
| 4 | 推前自查 | git status / git diff / git log --oneline -10 确认只含预期内容 |
| 5 | trunk-based | 日常在 main。仅长周期大改开 task/xxx 分支 |
| 6 | 例外才问 | 删库、清 session、含密钥 commit 才停下确认。其余 routine 自动走完 |
部署规范
1. git push origin master
2. ssh 246
- cd ~/AgentsMeeting && git pull --rebase
- sudo systemctl restart xxx（受影响的服务）
3. 验证：
- curl http://127.0.0.1:5803/api/xxx 确认 API 正常
- **打开 Dashboard K Tab → 确认测试通过**
四、已淘汰的规则
以下内容不再属于本规范，保留在此处说明去向：
| 原规则 | 去向 |
|---|---|
| 旧 A-K 框架（11 项） | 精简为 G + K + F + H 四项 |
| 细碎的操作技巧（弹窗铁律、编码技巧等） | 移入 AGENTS.md + 踩坑记录，不再作为核心规范 |
| Phase 计划（1/2/3） | 移除。开发按实际需求迭代，不按阶段计划 |
| H 需求驱动流程（全量 PRD） | 精简为纯总体性需求（H Tab），具体需求移入 specs/*.json |
| E 元成长回路 | 暂缓。等真遇到"反复犯同一个错"再实现 |