From 8f2f3466b73b8622206e9ea56aa71dc90aaae688 Mon Sep 17 00:00:00 2001 From: hmo Date: Thu, 16 Jul 2026 18:19:40 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20dev-spec.md=20=E7=A7=BB=E5=85=A5=20git?= =?UTF-8?q?=20=E8=B7=9F=E8=B8=AA=E7=9B=AE=E5=BD=95=20docs/=20+=20api=20can?= =?UTF-8?q?didates=20=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/dev-spec.md | 180 +++++++++++++++++++++++++++++++++++ gateway/scripts/dashboard.py | 10 +- 2 files changed, 188 insertions(+), 2 deletions(-) create mode 100644 docs/dev-spec.md diff --git a/docs/dev-spec.md b/docs/dev-spec.md new file mode 100644 index 0000000..c96a104 --- /dev/null +++ b/docs/dev-spec.md @@ -0,0 +1,180 @@ +# 开发规范 + +> 版本: v2.1 | 更新: 2026-07-16 + +--- + +## 核心理念 + +**"手脚架降低智商要求"** — 不是靠人记住所有规则，而是靠系统让正确路径成为最容易的路径。 + +三条红线： + +1. **先写 Spec，再写代码** — 没有 spec 的模块在 dashboard 不可见，视为未完成 +2. **部署必验** — 部署后不打开 K Tab 验证 = 部署未完成 +3. **不可见即不存在** — 组件不在 dashboard 中显示 = 等于没部署。离线不告警 = 监控缺陷 + +--- + +## 一、双轨同源规范体系 + +每新增/修改一个独立功能模块，必须先写 `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 | 状态 | +|------|------|------| +| 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. 提交 → 部署 → 验证 + 即以下"操作规范" +``` + +### 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 元成长回路 | 暂缓。等真遇到"反复犯同一个错"再实现 | diff --git a/gateway/scripts/dashboard.py b/gateway/scripts/dashboard.py index 59e3c99..5799b41 100644 --- a/gateway/scripts/dashboard.py +++ b/gateway/scripts/dashboard.py @@ -1156,10 +1156,13 @@ def api_spec(): """返回开发规范文档内容""" # Try multiple possible locations candidates = [ + # Git-tracked copy in project docs/ + os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "docs", "dev-spec.md"), + os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))), "projects", "AgentsMeeting", "docs", "dev-spec.md"), + # Legacy .memory/ locations (gitignored, no history) os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))), ".memory", "dev-spec.md"), os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), ".memory", "dev-spec.md"), os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "..", "..", ".memory", "dev-spec.md"), - # 246 venv: ~/ (5 dirname ups from venv/dashboard.py) os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))), ".memory", "dev-spec.md"), os.path.expanduser("~/.memory/dev-spec.md"), ] @@ -1194,8 +1197,11 @@ def api_prd_history(): def _git_history_for(filepath): """Helper: run git log for a file and return formatted history""" project_root = _PROJECT_DIR + # For dev-spec.md, also check docs/ variant which is git-tracked + if filepath == ".memory/dev-spec.md": + filepath = "docs/dev-spec.md" try: - cmd = ["git", "log", "--oneline", "--date=short", "--format=%h %ai %s", "--", filepath] + cmd = ["git", "log", "--format=%h %ai %s", "--", filepath] result = subprocess.run( cmd, cwd=project_root,