Hermes 工具链与开发规范全景

综合 hermes-toolchain 项目 134 页内容，提取开发规范、工具选型、环境配置三个维度的关键知识。

一、开发规范体系

1.1 核心原则（通用项目宪法）

通用项目宪法（融合版） 定义了 5 条核心原则：

原则 要点 违反后果
配置驱动 可变参数用 YAML/JSON 管理，禁止硬编码 参数散落各处，修改困难
数据分类存储 实时→TDengine/CH，关系→MySQL，文件→NAS 性能瓶颈或数据不一致
API优先 后端先定义接口，前端并行开发 前后端串行等待
测试驱动 每个模块有单元测试 + 集成测试 回归 bug 频发
文档同步 代码变更必须同步更新文档 文档与代码脱节

1.2 BUG修复AI协作规范

BUG修复AI工作规范 是与 AI coding agent 协作修 bug 的实战经验：

4 条核心原则: 1. 精准定位: BUG 必须明确"现象+根因+影响范围+修复方案" 2. 优先级驱动: P0(阻断)→P1(严重)→P2(一般)→P3(优化) 3. 小步迭代: 单次处理 1-2 个问题，避免批量修改引入新问题 4. 证据驱动: 每个修复提供"修复前+修复后+验证结果"完整证据链

1.3 标准化开发方法论

标准化开发方法论审核 补充了 3 条关键公理： - 结果可见公理: 所有开发动作必须产出可视化、可复现的运行结果 - 越权修复禁令: 禁止超前修复未来还未启用的功能代码 - 周期滚动规则: 每个迭代周期结束必须产出可运行版本

二、工具选型矩阵

2.1 NAS 服务部署

服务 用途 端口 状态
TriliumNext 笔记/素材仓库 8082 ✅
Open Notebook 知识展示 8502/5055 ✅ (worker 待修复)
SearXNG 搜索后端 8030 ✅
MemPalace 语义记忆 8015 ✅
agentmemory agent 记忆 8014 ✅
ClickHouse 量化数据 8123 ✅
MySQL 持仓/交易 3306 ✅
Gitea 代码仓库 3001 ✅
Ollama 本地 embedding 11434 ✅ (WSL)
paperless-ngx 文档管理 - paperless-ngx

2.2 开发工具链

工具 用途 参考
Hermes Agent AI agent 平台 Hermes Agent 安装器
Claude Code AI coding agent 全面工具
flake8 + mypy 代码质量 运行 flake8 和 mypy 确保代码质量
playwright E2E 测试 playwright install
GitHub Actions CI/CD GitHub Actions
tmux 终端复用 tmux
Chrome DevTools MCP 浏览器调试 Chrome DevTools MCP

2.3 WSL2 环境

WSL常用命令 整理了 NAS/WSL 的常用操作： - 文件同步: rsync -avzp --ignore-existing --exclude='#recycle' - 容器管理: docker compose 管理多服务 - 网络配置: WSL2 端口转发/镜像网络模式 - Chrome 调试: 需 --no-sandbox --remote-debugging-port=9222（root 用户）

三、AI 协作最佳实践

3.1 Mock 数据管理

善用mock数据 的核心建议： - 创建独立的 mock_data.py 模块集中管理 - 一个 API 对应一组 mock 数据（DataFrame/JSON） - 替换时只改数据源，不动业务代码

3.2 Skills 体系

问题：Skills 就是个摆设 提出了 Skills 落地的关键问题： - Skills 不应是静态文档，而应是可执行的流程 - Skill 的价值在于减少重复指令，而非增加阅读量 - 好的 Skill 有：触发条件 + 编号步骤 + 命令示例 + 坑点

四、知识缺口

  1. 跨工具编排: Hermes + Claude Code + RD-Agent 的工作流编排缺少标准化
  2. 质量门禁自动化: flake8/mypy/playwright 的集成缺少统一 CI 配置
  3. 文档治理: 完整文档治理结构 定义了规范但缺少执行工具

关联页面