Hermes Error Handling Agent

Hermes Error Handling Agent là cấu hình Hermes để xử lý lỗi từ Slack theo mô hình orchestrator + sub-agents. Slack channel chỉ dùng để xác định project; owner sửa lỗi được chọn sau khi các domain agent cùng phân tích evidence.

Cấu trúc project

.
├── .hermes/
│   ├── SOUL.md
│   ├── config.yaml
│   ├── project-context/
│   │   ├── channels.yaml
│   │   ├── projects/
│   │   │   └── retail-store-sample-app.yaml
│   │   ├── reviewers/
│   │   │   └── reviewer-groups.yaml
│   │   ├── skills/
│   │   │   └── skill-registry.yaml
│   │   ├── project.yaml.example
│   │   ├── profile.yaml.example
│   │   ├── domain-skill.md.example
│   │   └── SOUL.md.example
│   ├── profiles/        
│   │   ├── cart-agent/
│   │   ├── checkout-agent/
│   │   ├── catalog-agent/
│   │   ├── ui-agent/
│   │   ├── orders-agent/
│   │   └── infra-agent/
│   ├── skills/
│   │   └── software-development/
│   │       └── hermes-error-orchestrator/
│   └── cart-agent-mock/
├── docs/
│   ├── PROJECT_REPORT.md
│   └── SETUP.md
├── tools/
│   ├── get_project_context.mjs
│   ├── validate_project_config.mjs
│   └── lib/
├── workspace/
├── docker-compose.yml
└── Dockerfile.hermes

Vai trò các thư mục

Path	Vai trò
`.hermes/config.yaml`	Cấu hình Hermes gateway, Slack, delegation, dashboard, MCP GitHub, policy hiển thị output.
`.hermes/SOUL.md`	Identity của orchestrator. Chỉ mô tả phong cách và nguyên tắc, không nhét workflow chi tiết.
`.hermes/project-context/`	Metadata theo project: Slack channel mapping, repo/code-space, profile assignment, reviewer, skill registry.
`.hermes/profiles/<agent>/`	Hermes profile/sub-agent có `SOUL.md`, `config.yaml`, `profile.yaml` và skill riêng.
`.hermes/skills/software-development/hermes-error-orchestrator/`	Skill điều phối chính cho triage, owner selection, fix delegation và Slack replies.
`.hermes/cart-agent-mock/`	Mock Python shopping cart service và unit tests dùng để test/diễn giải cart domain.
`tools/`	Node.js resolver/validator cho project context.
`docs/`	Tài liệu setup và report project.
`workspace/`	Nơi bind mount project thật vào container Hermes.

Workflow

Slack channel
  -> Hermes default orchestrator
  -> tools/get_project_context.mjs
  -> project context + profile assignments
  -> parallel scope_detection by enabled profiles
  -> evidence-based owner selection
  -> Slack scope reply
  -> selected owner fix_error
  -> branch + PR/MR
  -> Slack final reply

Slack chỉ nhận hai checkpoint:

Kết quả scope detection.
Kết quả fixed/blocked cuối cùng.

Các log lệnh, tool output và progress nội bộ nằm trong Hermes session/gateway logs.

Project mock hiện tại

Project đang cấu hình cho repo:

repo: lbngyn/retail-store-sample-app
url: https://github.com/lbngyn/retail-store-sample-app
branch: main
workspace: /workspace/retail-store-sample-app

Slack channel hiện tại:

C0BDD2QA3FT -> retail-store-sample-app

Enabled agents:

cart-agent: src/cart/**
checkout-agent: src/checkout/**
catalog-agent: src/catalog/**
ui-agent: src/ui/**
orders-agent: src/orders/**
infra-agent: deploy/**, docker-compose*.yml, charts/**, terraform/**

Yêu cầu runtime

Docker + Docker Compose.
Node.js 20+ nếu chạy resolver/validator ngoài container.
Hermes Agent gateway.
Slack app token/bot token.
GitHub token có quyền repo/pull request nếu cần tạo branch/PR.

Setup local

Tạo file .env từ các biến cần thiết:

HERMES_DASHBOARD_USERNAME=admin
HERMES_DASHBOARD_PASSWORD=change-me
HERMES_DASHBOARD_SECRET=change-me

SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...
SLACK_ALLOWED_CHANNELS=C0BDD2QA3FT
SLACK_HOME_CHANNEL=C0BDD2QA3FT
SLACK_HOME_CHANNEL_NAME=error-handling

GITHUB_PAT=github_pat_...

Clone hoặc mount project thật vào workspace/.

Với config hiện tại, repo mock nên nằm trong container tại:

/workspace/retail-store-sample-app

Nếu chạy trên host Windows, thư mục tương ứng là:

workspace/retail-store-sample-app

Start Hermes:

docker compose up -d --build

Mở dashboard nếu đã bật:

http://localhost:8642

Validate config

Chạy từ root repo:

node tools/get_project_context.mjs --channel-id C0BDD2QA3FT
node tools/validate_project_config.mjs --project-id retail-store-sample-app

Kết quả mong muốn là ok: true. Trong giai đoạn onboarding, missing local workspace/code-space path có thể là warning nếu repo chưa được clone.

Lưu ý: trong retail-store-sample-app.yaml, startup_checks.commands hiện còn command mẫu dùng C_RETAIL_MOCK. Khi áp dụng thật, đổi sang channel id thực tế hoặc thêm mapping tương ứng vào channels.yaml.

Áp dụng lên project mới

1. Thêm Slack channel mapping

Sửa .hermes/project-context/channels.yaml:

channels:
  C_PROJECT_CHANNEL:
    project_id: my-project

2. Tạo project config

Copy template:

cp .hermes/project-context/project.yaml.example .hermes/project-context/projects/my-project.yaml

Cập nhật các phần chính:

project_id: my-project
project_name: My Project
ownership_model: monorepo-service-folder

workspace:
  path: /workspace/my-project

code_spaces:
  app-repo:
    type: github_repo
    repo: my-org/my-project
    url: https://github.com/my-org/my-project
    default_branch: main
    local_path: /workspace/my-project

  api-directory:
    type: directory
    parent_code_space: app-repo
    path: src/api
    local_path: /workspace/my-project/src/api

Supported code-space types:

github_repo: một repo GitHub đầy đủ.
github_branch: repo + working branch cụ thể.
directory: một folder bên trong code-space cha.
workspace: local/cloud workspace đã provision sẵn.

3. Chọn enabled profiles

Trong project config:

enabled_profiles:
  - api-agent
  - ui-agent
  - infra-agent

Mỗi profile phải tồn tại tại:

.hermes/profiles/<profile>/

4. Tạo hoặc tái sử dụng profile

Copy template:

mkdir -p .hermes/profiles/api-agent/skills/api-error-handling
cp .hermes/project-context/profile.yaml.example .hermes/profiles/api-agent/profile.yaml
cp .hermes/project-context/SOUL.md.example .hermes/profiles/api-agent/SOUL.md
cp .hermes/project-context/domain-skill.md.example .hermes/profiles/api-agent/skills/api-error-handling/SKILL.md

Ví dụ profile.yaml:

profile: api-agent
display_name: API Agent
agent_type: hermes_profile

default_ownership:
  keywords:
    - api
    - controller
    - service

default_skills:
  scope_detection:
    - api-error-handling
    - hermes-error-orchestrator
    - systematic-debugging
    - codebase-inspection
  fix_error:
    - api-error-handling
    - codebase-inspection
    - systematic-debugging
    - test-driven-development
    - github-auth
    - github-pr-workflow
    - github-code-review

5. Gán profile vào code-space

Trong .hermes/project-context/projects/my-project.yaml:

profile_assignments:
  api-agent:
    code_spaces:
      - api-directory
    ownership:
      services:
        - api
      paths:
        - src/api/**
      keywords:
        - api
        - controller
      runtime_signals:
        - api
    reviewers:
      - "@api-lead"
    constraints:
      can_modify_paths:
        - src/api/**
      cannot_modify_paths:
        - src/ui/**

6. Cập nhật reviewer và skill registry

Reviewer group:

reviewer_groups:
  api:
    - "@api-lead"

Nếu skill dùng chung nằm ở .hermes/skills/..., thêm vào .hermes/project-context/skills/skill-registry.yaml. Nếu skill nằm local trong profile, validator vẫn chấp nhận khi file tồn tại tại:

.hermes/profiles/<profile>/skills/<skill>/SKILL.md

7. Cấu hình Slack/GitHub

Trong .env:

SLACK_ALLOWED_CHANNELS=C_PROJECT_CHANNEL
GITHUB_PAT=github_pat_...

Trong .hermes/config.yaml, đảm bảo Slack channel prompt có hướng dẫn resolve đúng channel id nếu bạn dùng prompt theo channel.

GitHub token nên có quyền:

Contents read/write.
Pull requests read/write.
Issues read/write nếu dùng PR comments/issues.
Actions read nếu agent cần đọc CI checks.
workflow scope nếu repo có policy yêu cầu khi push branch.

8. Validate project mới

node tools/get_project_context.mjs --channel-id C_PROJECT_CHANNEL
node tools/validate_project_config.mjs --project-id my-project

Sửa toàn bộ errors trước khi bật Slack incident flow. warnings về path chưa tồn tại có thể chấp nhận nếu workspace chưa clone xong.

Fork PR workflow

Nếu agent không được push trực tiếp lên upstream, cấu hình code-space:

code_spaces:
  app-repo:
    type: github_repo
    repo: upstream-org/app
    url: https://github.com/upstream-org/app
    default_branch: main
    local_path: /workspace/app
    push_strategy: fork_pull_request
    push_remote: fork
    fork_repo: your-user/app
    fork_url: https://github.com/your-user/app
    pr_base_repo: upstream-org/app
    pr_base_branch: main
    pr_head_repo: your-user/app

Agent sẽ push branch lên fork và mở PR về upstream.

Mock cart service

.hermes/cart-agent-mock/ chứa mock Python shopping cart service:

python .hermes/cart-agent-mock/demo.py
python -m unittest .hermes/cart-agent-mock/test_cart_service.py

Mock này bao gồm add/remove/update item, discount code, tax, shipping, total calculation và custom exceptions.

Tài liệu liên quan

Project report
Setup notes
.hermes/skills/software-development/hermes-error-orchestrator/references/ownership-rules.md
.hermes/skills/software-development/hermes-error-orchestrator/references/sub-agent-task-contracts.md
.hermes/skills/software-development/hermes-error-orchestrator/references/reply-templates.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Hermes Error Handling Agent

Cấu trúc project

Vai trò các thư mục

Workflow

Project mock hiện tại

Yêu cầu runtime

Setup local

Validate config

Áp dụng lên project mới

1. Thêm Slack channel mapping

2. Tạo project config

3. Chọn enabled profiles

4. Tạo hoặc tái sử dụng profile

5. Gán profile vào code-space

6. Cập nhật reviewer và skill registry

7. Cấu hình Slack/GitHub

8. Validate project mới

Fork PR workflow

Mock cart service

Tài liệu liên quan

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.hermes		.hermes
docs		docs
tools		tools
.gitignore		.gitignore
Dockerfile.hermes		Dockerfile.hermes
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

Hermes Error Handling Agent

Cấu trúc project

Vai trò các thư mục

Workflow

Project mock hiện tại

Yêu cầu runtime

Setup local

Validate config

Áp dụng lên project mới

1. Thêm Slack channel mapping

2. Tạo project config

3. Chọn enabled profiles

4. Tạo hoặc tái sử dụng profile

5. Gán profile vào code-space

6. Cập nhật reviewer và skill registry

7. Cấu hình Slack/GitHub

8. Validate project mới

Fork PR workflow

Mock cart service

Tài liệu liên quan

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages