烧了30亿+token，超10万+api调用次数养龙虾之后，我彻底转向以hermes为执行者的harness工程agi全自治架构

最近技术圈有个话题很火：如果某个商业闭源顶级项目的代码泄露了，普通人能做什么？

我的答案是：拿到代码只是第一步，真正的挑战是重构。

大型代码库（比如数十万行、多语言混合、复杂依赖关系）不是给人直接读的。你需要：

  • 先理解代码结构（Repo Map）
  • 确定重构边界（Scope Guard）
  • 分解任务（Task Decomposer）
  • 管理 Git 分支（Git Workflow）
  • 验证结果（Code Validator）

这些能力分散在 Aider、Plandex、MetaGPT、CrewAI 等工具中，但没有一个是"开箱即用"的完整方案。所以我决定自己搭建一个。

一、Refactor Agent 架构设计：借鉴四大工具的核心能力

1.1 四大工具的核心能力分析

工具 核心能力 使用场景
Aider Repo Map（代码库地图）、多文件编辑、Git 集成 代码库理解与批量修改
Plandex Plan → Code → Review → Validate 四阶段任务分解 复杂任务的逐步执行
MetaGPT 角色模拟（PM/Architect/Engineer/QA）、完整 SDLC 软件开发流程标准化
CrewAI 角色分工、Sequential/Hierarchical/Parallel 执行模式 多Agent协作编排

1.2 Refactor Agent 架构图

Refactor Agent 架构
├── Skills（5 个核心技能）
│   ├── repo-map-skill          # 生成代码库地图（借鉴 Aider）
│   ├── task-decomposer-skill   # 任务分解（借鉴 Plandex）
│   ├── scope-guard-skill       # 范围守卫（防止越界修改）
│   ├── git-workflow-skill      # Git 安全网（自动提交/回滚）
│   └── code-validator-skill    # 代码验证（静态分析/测试/安全扫描）
├── Knowledge Base（15 个模块，84 个文件）
│   ├── 核心：best-practices, language-guides, design-patterns, refactoring-patterns
│   ├── 质量：testing-strategies, security-checklists, performance-tips, ci-cd
│   ├── 架构：legacy-code, microservices, api-design, data-migration
│   └── 工程：monitoring-observability, team-collaboration, tools-automation
└── 与 Hermes 协作：通过 delegation 路由自动分发重构任务

1.3 知识库目录结构

knowledge_base/
├── __MASTER_INDEX__.md                 # 主索引（必须第一个创建）
├── best-practices/                    # 最佳实践（8 个文件）
│   ├── coding-standards.md
│   ├── naming-conventions.md
│   └── ...
├── language-guides/                   # 语言指南（6 种语言）
│   ├── python-guide.md
│   ├── javascript-guide.md
│   ├── go-guide.md
│   └── ...
├── design-patterns/                   # 设计模式（23 种）
│   ├── singleton.md
│   ├── observer.md
│   └── ...
├── refactoring-patterns/              # 重构模式（30+ 种）
│   ├── extract-method.md
│   ├── replace-temp-with-query.md
│   └── ...
├── testing-strategies/               # 测试策略
├── security-checklists/              # 安全检查清单
├── performance-tips/                # 性能优化
├── ci-cd/                           # 持续集成/部署
├── legacy-code/                     # 遗留代码处理
├── microservices/                   # 微服务架构
├── api-design/                     # API 设计
├── data-migration/                 # 数据迁移
├── monitoring-observability/       # 可观测性
├── team-collaboration/             # 团队协作
└── tools-automation/               # 工具自动化

二、知识库填充：最复杂的工程挑战

这是整个项目中最耗时的部分。15 个模块、84 份文档、27,000+ 行内容，不可能手动写。

2.1 提示词体系设计

我创建了 7 份 Agent 任务书，每份对应一个专业领域：

Agent 负责模块 专长领域
Agent-A best-practices + language-guides 语言特性、代码风格
Agent-B design-patterns + refactoring-patterns 设计模式、重构手法
Agent-C performance-tips + testing-strategies 性能、测试
Agent-D security-checklists + ci-cd 安全、DevOps
Agent-E legacy-code + microservices 遗留系统、架构
Agent-F api-design + data-migration API、数据
Agent-G monitoring-observability + team-collaboration + tools-automation 可观测性、协作

2.2 Agent 任务书模板（可直接复制使用）

Agent-A 任务书：best-practices + language-guides
# Agent-A 任务书：最佳实践与语言指南填充

## 任务目标
填充 `best-practices/` 和 `language-guides/` 目录下的所有文件。

## 内容要求
每个文件必须包含：
- **理论说明**：该最佳实践/语言特性的核心概念
- **代码示例**：至少 2 个对比示例（重构前/后）
- **检查清单**：至少 5 个验证项
- **常见陷阱**：至少 3 个警示案例

## 输出格式
- 语言：中文
- 代码注释：英文
- 文件格式：Markdown

## 质量标准
- 每个文件 ≥ 150 行
- 代码示例覆盖率 100%
- 检查清单完整度 ≥ 90%

## 文件清单
1. best-practices/coding-standards.md
2. best-practices/naming-conventions.md
3. best-practices/code-review-guide.md
4. best-practices/error-handling.md
5. best-practices/logging-best-practices.md
6. best-practices/documentation-standards.md
7. best-practices/git-workflow-standards.md
8. best-practices/security-best-practices.md
9. language-guides/python-guide.md
10. language-guides/javascript-guide.md
11. language-guides/go-guide.md
12. language-guides/java-guide.md
13. language-guides/rust-guide.md
14. language-guides/cpp-guide.md

2.3 协调员提示词设计

# hermes-coordinator.prompt

## 角色
你是一个知识库协调员，负责协调 7 个子 Agent 并行填充知识库。

## 工作流程
1. 读取主索引（__MASTER_INDEX__.md）确认目录结构
2. 运行验证脚本检查当前状态：
   ```bash
   python3 scripts/verify-knowledge-base.py --check完整性
  1. 启动 7 个子 Agent 并行工作： 
    hermes agent --name "KB-Languages" --task-file agent-a-languages.md
hermes agent --name "KB-Patterns" --task-file agent-b-patterns.md
hermes agent --name "KB-Quality" --task-file agent-c-quality.md
hermes agent --name "KB-DevOps" --task-file agent-d-devops.md
hermes agent --name "KB-Architecture" --task-file agent-e-architecture.md
hermes agent --name "KB-Data" --task-file agent-f-data.md
hermes agent --name "KB-Engineering" --task-file agent-g-engineering.md
  2. 监控进度，处理内容冲突（"指定主模块，其他模块引用"规则）
  3. 质量验证： 
    python3 scripts/verify-knowledge-base.py --check覆盖率

冲突解决规则

  • 当两个模块内容重叠时（如 strategy-pattern 同时属于 design-patterns 和 refactoring-patterns）
  • 规则：design-patterns 作为主模块，refactoring-patterns 中只简要提及并链接到主模块

### 2.4 执行命令

```bash
# 启动协调员
hermes agent --name "KB-Coordinator" --task-file hermes-coordinator.prompt

# 7 个 Agent 并行填充
hermes agent --name "KB-Languages" --task-file agent-a-languages.md
hermes agent --name "KB-Patterns" --task-file agent-b-patterns.md
hermes agent --name "KB-Quality" --task-file agent-c-quality.md
hermes agent --name "KB-DevOps" --task-file agent-d-devops.md
hermes agent --name "KB-Architecture" --task-file agent-e-architecture.md
hermes agent --name "KB-Data" --task-file agent-f-data.md
hermes agent --name "KB-Engineering" --task-file agent-g-engineering.md

三、反复验证：3 轮质量检查

3.1 第一轮：完整性检查

指标 目标 实际 结果
文件数 50+ 84 ✅
总行数 5000+ 27,427 ✅
代码示例覆盖率 90%+ 97.6%（82/84） ✅

3.2 第二轮：质量检查

发现问题：

  • inline-method.md：79 行（偏薄）
  • replace-temp-with-query.md：90 行（偏薄）
  • extract-class.md：95 行（偏薄）

手动补充后：

  • inline-method.md：207 行 ✅
  • replace-temp-with-query.md：311 行 ✅
  • extract-class.md：354 行 ✅

3.3 第三轮：功能验证

# 验证 AGENTS.md 是否引用所有 15 个模块
python3 scripts/verify-knowledge-base.py --check agents-md引用

# 验证 Skills 脚本是否完整
python3 scripts/verify-knowledge-base.py --check skills完整性

# 验证结果：发现 10 个模块未被 AGENTS.md 引用，4 个 Skills 脚本缺失
# 已修复所有问题

四、关键困难与解决方案

4.1 困难 1：知识库内容冲突

问题：两个 Agent 同时填充不同模块，但内容有重叠（如 design-patterns 和 refactoring-patterns 都涉及"策略模式"）。

解决：在协调员提示词中明确规则——"指定主模块，其他模块引用"。design-patterns 作为策略模式的主模块，refactoring-patterns 中只简要提及并链接到主模块。

4.2 困难 2：路径硬编码导致迁移困难

问题：初期脚本中硬编码了 /Users/wjj13/harness-knowledge/ 等本地路径，无法迁移到外置硬盘。

解决：

# 1. 全面扫描所有硬编码路径
grep -r "/Users/wjj13/harness-knowledge/" knowledge_base/

# 2. 迁移核心数据到新路径
mv /Users/wjj13/harness-knowledge/* /Volumes/A/SOCIALMEDIA/knowledge_base/harness/

# 3. 批量替换路径引用
find /Volumes/A/SOCIALMEDIA/knowledge_base/harness/ -type f -name "*.md" -exec sed -i '' 's|/Users/wjj13/harness-knowledge/|/Volumes/A/SOCIALMEDIA/knowledge_base/harness/|g' {} \;

# 4. 验证 RAG 索引器在新路径下正常工作
python3 scripts/harness-rag-indexer.py index --path /Volumes/A/SOCIALMEDIA/knowledge_base/harness/

4.3 困难 3：Skills 脚本缺失

问题：task-decomposer-skill 和 scope-guard-skill 只有 SKILL.md 文档，没有实际可执行的脚本。

解决：创建 4 个 Python 脚本：

# skills/task-decomposer-skill/scripts/decompose.py
"""
重构任务分解器：解析重构规范，生成 8 步标准任务流
"""

def decompose_refactor_spec(spec_path: str, output_path: str) -> dict:
    """
    解析重构规范文件，生成任务流

    Args:
        spec_path: 重构规范文件路径（Markdown格式）
        output_path: 输出YAML文件路径

    Returns:
        包含8个步骤的任务流字典
    """
    # 8步标准任务流
    steps = [
        "generate-repo-map",      # 生成Repo Map
        "impact-analysis",        # 影响分析
        "set-scope",              # 设置范围
        "create-branch",          # 创建分支
        "execute-refactor",       # 执行重构
        "verify-scope",           # 验证范围
        "run-validation",          # 运行验证
        "merge-branch"            # 合并分支
    ]

    # 解析规范，计算预估时间和风险等级
    spec = parse_spec(spec_path)
    tasks = generate_tasks(spec, steps)

    # 输出任务流
    save_tasks(tasks, output_path)
    return tasks

# skills/scope-guard-skill/scripts/set-scope.py
"""
范围守卫：扫描项目，定义允许/禁止修改的文件集合
"""

def set_scope(project_path: str, include_patterns: list, exclude_patterns: list) -> ScopeConfig:
    """
    设置重构范围边界

    Args:
        project_path: 项目根目录
        include_patterns: 允许修改的文件模式（如 "src/core/**"）
        exclude_patterns: 禁止修改的文件模式（如 "src/legacy/**"）

    Returns:
        ScopeConfig 对象，包含 allow_list 和 deny_list
    """
    scanner = ProjectScanner(project_path)
    all_files = scanner.scan()

    scope = ScopeConfig()
    scope.add_allowed(include_patterns)
    scope.add_denied(exclude_patterns)

    # 生成边界报告
    report = scope.generate_report()
    print(f"允许修改：{len(scope.allow_list)} 个文件")
    print(f"禁止修改：{len(scope.deny_list)} 个文件")

    return scope

4.4 困难 4：Hermes 无法感知新增知识库

问题：AGENTS.md 只引用了 5 个知识库模块，Hermes 不知道其他 10 个模块的存在。

解决：重写 AGENTS.md，添加：

  • 完整的 15 个模块列表及说明
  • 知识库使用指南（按任务类型查阅对应模块）
  • 所有 Skills 的使用命令示例
  • 10 步重构工作流

五、最终成果数据

维度 数据
知识库模块 15 个
知识库文件 84 个
总行数 27,427 行
代码示例覆盖率 97.6%
检查清单覆盖率 83.3%
覆盖语言 Python, JavaScript, Go, Java, Rust, C++
重构模式 30+ 种
设计模式 23 种（GoF + 重构到模式）
Skills 5 个（含 7 个可执行脚本）
Agent 任务书 7 份

六、实战演示：当泄露发生时

假设某天，某个商业闭源顶级项目的代码泄露了。你拿到代码后：

第一步：生成 Repo Map

python3 skills/repo-map-skill/scripts/generate-map.py \
  --project /path/to/leaked-code \
  --output workspace/repo-map

输出示例：

📊 代码库统计：
├── 文件数：1159
├── 类数：3419
├── 函数数：20780
└── 生成时间：12.3s

第二步：分解重构任务

python3 skills/task-decomposer-skill/scripts/decompose.py \
  --spec workspace/refactor-spec.md \
  --output workspace/tasks.yaml

输出示例：

📋 任务分解结果：
├── 子任务数：8
├── 预估时间：13.25 小时
└── 风险等级：🟡 中等

第三步：设置重构范围

python3 skills/scope-guard-skill/scripts/set-scope.py \
  --project /path/to/leaked-code \
  --include "src/core/**" \
  --exclude "src/legacy/**"

输出示例：

🛡️ 范围守卫已启用：
├── 允许修改：500 个文件
└── 禁止修改：200 个文件

第四步：查阅知识库

# 查阅 Python 重构指南
cat knowledge_base/language-guides/python-guide.md

# 查阅 Extract Method 重构模式
cat knowledge_base/refactoring-patterns/extract-method.md

# 查阅安全检查清单
cat knowledge_base/security-checklists/pre-refactor-security.md

第五步：执行重构

# Git 安全网自动开启
git workflow start-refactor

# 执行重构任务
python3 skills/task-decomposer-skill/scripts/execute.py \
  --tasks workspace/tasks.yaml \
  --scope workspace/scope-config.json

第六步：验证结果

python3 skills/code-validator-skill/scripts/code-validator.py \
  --project /path/to/leaked-code \
  --action all

输出示例：

✅ 语法检查通过
✅ 代码风格通过
✅ 单元测试通过（1567/1567）
✅ 安全扫描通过（0 漏洞）

七、迁移检查清单

- [ ] 安装 Hermes 并配置 delegation 路由
- [ ] 克隆 Refactor Agent 到 `/Volumes/A/Agents/refactor-agent/`
- [ ] 确认知识库完整（84 个文件）
- [ ] 确认 Skills 脚本可执行（7 个 Python 脚本）
- [ ] 测试 Repo Map 生成
- [ ] 测试任务分解
- [ ] 测试范围守卫
- [ ] 测试代码验证
- [ ] 查阅知识库确认内容质量
- [ ] 准备重构规范模板（refactor-spec.md）

总结

本文记录了我花一整天搭建 Refactor Agent 的完整过程：

  1. 架构设计：借鉴 Aider、Plandex、MetaGPT、CrewAI 四大工具的核心能力
  2. 知识库填充：通过 Hermes 多 Agent 协作，自动填充 84 个文件、27,000+ 行内容
  3. 验证优化：3 轮验证确保质量，发现问题及时修复
  4. 工程化：解决路径硬编码、Skills 脚本缺失等问题

核心经验：提示词工程比写代码还累，但结果是值得的。当知识库被精心设计后，Hermes 多 Agent 可以自动填充高质量内容，这是手动编写无法达到的效率。

参考来源

  1. Aider Repo Map 工作原理分析 - CSDN博客 - 2025-03-23
  2. Plandex: 面向真实项目的 AI 编程助手 - 今日头条 - 2025-04-25
  3. MetaGPT & CrewAI 多Agent协作对比 - 知乎 - 2025-01-02
  4. 主流Agent框架2024盘点 - 知乎 - 2025-01-02
  5. 如何在开源项目中做重构 - Databend博客 - 2026-03-28

免责声明

本文为个人技术观察，具体实践请以官方文档为准。文中涉及的工具和框架均为各自所有者的财产。

Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

大模型入门-GSPO 分组序列策略优化

avatar AtomGit开源社区

（毕业必看）实测靠谱的AI论文软件，毕业党收藏备用

你是不是也在为毕业论文发愁？选题纠结、资料找不全、写到一半卡壳、查重反复修改、格式总调不对…… 这份精心整理的AI论文工具合集，涵盖中英文写作、全流程辅助、专项功能、免费与高性价比

avatar AtomGit开源社区

绝地求生：如何在 2026 年把 OpenAI Codex 强行交叉编译到 RISC-V 架构

OpenAI 官方开源的 Codex CLI 是当前极为强大的本地代码 Agent，但官方却唯独没有提供 RISC-V 架构的预编译版本。为了在我们的 Starfive 星光板上跑起这个大杀器，昨晚我们曾试图在 QEMU 模拟器中偷懒编译，结果被 V8 引擎庞大的源码量和指令翻译开销拖到内存爆炸、进程卡死。痛定思痛后，我们决定采用最硬核的方式——。在这场战役中，我们历经重重险阻，连续趟平了 10

avatar AtomGit开源社区