hmo/AgentsMeeting
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
AgentsMeeting/docs/dev-spec.md
T

12 KiB
Raw Permalink Blame History

开发规范

版本: v2.3 | 更新: 2026-07-19

核心理念

"手脚架降低智商要求" — 不是靠人记住所有规则，而是靠系统让正确路径成为最容易的路径。

三条红线：

  1. 先读/写 Spec，再写代码 — 新增功能先写 spec 再实现；修改已有功能先读对应 spec 了解架构和约束再动手。没有 spec 的模块在 dashboard 不可见，视为未完成
  2. 部署必验 — 部署后不打开 K Tab 验证 = 部署未完成
  3. 不可见即不存在 — 组件不在 dashboard 中显示 = 等于没部署。离线不告警 = 监控缺陷
  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

一、双轨同源规范体系

每新增/修改一个独立功能模块，必须先写 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 路径 § 入口 状态
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 元成长回路 暂缓。等真遇到"反复犯同一个错"再实现
Reference in New Issue View Git Blame Copy Permalink