253 lines
11 KiB
Markdown
253 lines
11 KiB
Markdown
# 开发规范
|
||
|
||
> 版本: v2.2 | 更新: 2026-07-17
|
||
|
||
---
|
||
|
||
## 核心理念
|
||
|
||
**"手脚架降低智商要求"** — 不是靠人记住所有规则，而是靠系统让正确路径成为最容易的路径。
|
||
|
||
三条红线：
|
||
|
||
1. **先读/写 Spec，再写代码** — 新增功能先写 spec 再实现；修改已有功能先读对应 spec 了解架构和约束再动手。没有 spec 的模块在 dashboard 不可见，视为未完成
|
||
2. **部署必验** — 部署后不打开 K Tab 验证 = 部署未完成
|
||
3. **不可见即不存在** — 组件不在 dashboard 中显示 = 等于没部署。离线不告警 = 监控缺陷
|
||
4. **实现后同步 Spec** — 每轮开发完毕后，必须将 specs/{module}.json 更新为与实际实现一致的状态。文档过期 = 等于没写
|
||
|
||
---
|
||
|
||
## 一、双轨同源规范体系
|
||
|
||
每新增/修改一个独立功能模块，必须先写 `specs/{module}.json`。
|
||
一个来源同时产出两套文档：
|
||
|
||
```
|
||
specs/usage_monitor.json
|
||
├── human_help → ? 按钮（人类看说明/排错）
|
||
└── ai_spec → § 按钮（AI 看接口/约束/依赖）
|
||
```
|
||
|
||
### 什么算一个模块
|
||
|
||
满足以下任一条件即视为独立模块，必须写 spec：
|
||
|
||
- 暴露独立的 HTTP API 端点
|
||
- 在 Dashboard 上有独立 UI 面板（`?` + `§` 按钮）
|
||
- 有独立的配置文件 / 数据文件
|
||
- 可独立部署（如 bot、gateway、定时任务）
|
||
|
||
### Spec 字段标准
|
||
|
||
```json
|
||
{
|
||
"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 路径 | § 入口 | 状态 |
|
||
|------|----------|--------|------|
|
||
| agents | `gateway/scripts/specs/agents.json` | Dashboard A Tab → Agent 卡片 | ✅ |
|
||
| api_proxy | `gateway/scripts/specs/api_proxy.json` | Dashboard I Tab → API Proxy (:8787) | ✅ |
|
||
| article_processor | `gateway/scripts/specs/article_processor.json` | Dashboard F/I Tab → 文章抓取服务 | ✅ |
|
||
| chat_bridge | `gateway/scripts/specs/chat_bridge.json` | Dashboard A Tab → SessionBridge | ✅ |
|
||
| dashboard | `gateway/scripts/specs/dashboard.json` | Dashboard 全局 | ✅ |
|
||
| dev_spec | `gateway/scripts/specs/dev_spec.json` | Dashboard G Tab | ✅ |
|
||
| easytier | `gateway/scripts/specs/easytier.json` | Dashboard I Tab → EasyTier | ✅ |
|
||
| ejabberd | `gateway/scripts/specs/ejabberd.json` | Dashboard F Tab → XMPP 服务器 | ✅ |
|
||
| health | `gateway/scripts/specs/health.json` | Dashboard F Tab → 健康检查 | ✅ |
|
||
| health_service | `gateway/scripts/specs/health_service.json` | Dashboard F Tab → 健康服务 | ✅ |
|
||
| infra | `gateway/scripts/specs/infra.json` | Dashboard I Tab | ✅ |
|
||
| kanban | `gateway/scripts/specs/kanban.json` | Dashboard K Tab | ✅ |
|
||
| prd | `gateway/scripts/specs/prd.json` | Dashboard H Tab | ✅ |
|
||
| rdp | `gateway/scripts/specs/rdp.json` | Dashboard I Tab → RDP | ✅ |
|
||
| session_router | `gateway/scripts/specs/session_router.json` | Dashboard A Tab → SessionRouter | ✅ |
|
||
| tests | `gateway/scripts/specs/tests.json` | Dashboard K Tab | ✅ |
|
||
| usage_collector | `gateway/scripts/specs/usage_collector.json` | Dashboard I Tab → Usage 采集 | ✅ |
|
||
| usage_monitor | `gateway/scripts/specs/usage_monitor.json` | Dashboard I Tab → OpenCode Go Usage | ✅ |
|
||
| wechat_bridge | `gateway/scripts/specs/wechat_bridge.json` | Dashboard F/I Tab → 微信桥接 | ✅ |
|
||
| xmpp_bot | `gateway/scripts/specs/xmpp_bot.json` | Dashboard A/F Tab → XMPP Bot | ✅ |
|
||
| xmpp_watchdog | `gateway/scripts/specs/xmpp_watchdog.json` | Dashboard F Tab → 看门狗 | ✅ |
|
||
| 开发规范本身 | `docs/dev-spec.md` | Dashboard G Tab | ✅ |
|
||
|
||
---
|
||
|
||
## 二、验证闭环
|
||
|
||
```
|
||
┌────────────┐ ┌──────────┐ ┌──────────┐
|
||
│ G: 规范体系 │────→│ K: 测试 │────→│ F: 健康 │
|
||
│ 定义期望 │ │ 验证实现 │ │ 持续监控 │
|
||
└────────────┘ └──────────┘ └──────────┘
|
||
↑ ↑ │
|
||
└────────────────┼────────────────┘
|
||
│
|
||
┌────────┴────────┐
|
||
│ F 异常 → 触发 K │
|
||
│ K 失败 → 更新 G │
|
||
└─────────────────┘
|
||
|
||
H: 需求文档 — 双轨体系覆盖不到的架构级/跨模块需求（性能、安全、可用性等）
|
||
```
|
||
|
||
### 核心反馈链路
|
||
|
||
| 方向 | 触发条件 | 动作 |
|
||
|------|---------|------|
|
||
| G → K | 新增/修改 spec | K Tab 对应测试 ID 必须新增/更新 |
|
||
| K → F | 测试全部通过 | F Tab 组件标记为已验证 |
|
||
| **F → K** | **F Tab 发现异常** | **应触发 K Tab 对应测试重跑，确认是服务故障还是测试过期** |
|
||
| **F → G** | **F Tab 持续异常但测试通过** | **说明期望矩阵或 spec 过时，应更新 G 和对应的 spec** |
|
||
|
||
### G — 开发规范（Dashboard G Tab）
|
||
|
||
- 本文档，展示在 Dashboard G Tab
|
||
- 包含：双轨同源体系、验证闭环、开发流程
|
||
- Dashboard G Tab 底部展示历史版本（`git log`）
|
||
|
||
### K — 自动测试（Dashboard K Tab）
|
||
|
||
- `gateway/scripts/tests_api.py` 自动执行系统检测（Dashboard 运行时从 `gateway/scripts/tests_api` import）
|
||
- Dashboard K Tab 实时展示 PASS/FAIL/EXPECTED
|
||
- **部署后必做**：打开 K Tab 确认全部通过或已知失败原因
|
||
- **测试追溯链**：`tests_api.py` 中的每个测试用例（A1/A2/B1/B2...）应在其测试逻辑的注释中注明所验证的 `ai_spec.tests` ID（如 `# UM01`、`# XB03`）。Dashboard K Tab 前端应尽量在测试名称列展示对应的 spec 测试 ID，用于快速定位 spec 来源
|
||
- 新增模块时应在 `ai_spec.tests` 中添加对应的测试标识，并在 `tests_api.py` 中实现
|
||
|
||
### F — 系统健康度（Dashboard F Tab）
|
||
|
||
- **期望矩阵**：应该运行的服务 vs 实际状态（Dashboard F Tab），从 `agents.yaml` + `PLATFORM_SERVICES` 动态生成
|
||
- **监控数据**：Tier1（5min）/ Tier2（日报）作为实时状态输入
|
||
- **服务拓扑**：所有服务的健康、端口、看门狗状态
|
||
- **跨平台检测**：远程服务（非本机）标记为 `remote（见平台Tab）`，避免误报
|
||
- **命名唯一性**：F Tab 中的每条服务必须有唯一的 `key`（实例级，如 `agent-001:xmpp_bot`），禁止按类型折叠导致多条同名。M 映射表必须逐条定义友好标签，不可复用同一条目
|
||
- **跨 Tab 一致性**：同一模块在 F Tab、I Tab、K Tab 中的展示名称必须一致。例如 `article_processor` 在 F Tab 叫"文章抓取服务"，在 I Tab 也应叫"文章抓取服务"，不能一处叫"微信全文抓取"
|
||
- **?§ 覆盖**：F Tab 中的每条服务必须有对应的 ?（human_help）和 §（ai_spec）按钮，链接到 `specs/{spec_module}.json`。没有 spec 的服务不应出现在 F Tab 中
|
||
|
||
### 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. 提交 → 部署 → 验证
|
||
即以下"操作规范"
|
||
```
|
||
|
||
### 修改已有功能流程
|
||
|
||
```
|
||
识别要修改的模块（查看模块清单确定 module 名）
|
||
│
|
||
├─ 1. 读 specs/{module}.json
|
||
│ 重点读 ai_spec 部分：
|
||
│ - apis：了解接口定义和调用方式
|
||
│ - constraints：了解必须遵守的约束
|
||
│ - dependencies：了解依赖关系和部署位置
|
||
│ - architecture.flow：了解数据流向
|
||
│ - must_not：了解绝对不能做的事
|
||
│
|
||
├─ 2. 确认理解
|
||
│ - 如果 spec 描述与代码实际行为不一致，优先怀疑 spec 过期
|
||
│ - 确认后先更新 spec 再做修改
|
||
│
|
||
├─ 3. 修改功能代码
|
||
│ 只改动需求直接涉及的部分，不顺手优化无关代码
|
||
│
|
||
├─ 4. 同步更新 Spec
|
||
│ - 将 specs/{module}.json 更新为与实际实现一致
|
||
│ - api/constraints/dependencies/architecture 逐一核对
|
||
│ - 删除过时描述，修正错误假设
|
||
│
|
||
└─ 5. 提交 → 部署 → 验证
|
||
即以下"操作规范"
|
||
```
|
||
|
||
### 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 元成长回路 | 暂缓。等真遇到"反复犯同一个错"再实现 |
|