AGENT SKILL

hermes-agent

Manage 0xRay framework from Hermes Agent via the native xray-hermes plugin. Covers the 4 plugin tools (validate, codex_check, health, hooks), lifecycle hooks, slash commands, bridge architecture, and CLI fallback.

License 许可
MIT
所属仓库
0xRayAI/xray
最近更新
2026-11-13
Stars
★ 2
Forks
3

01 前言 Front Matter

name
hermes-agent
author
0xRay AI
version
2.1.0
metadata
{ "hermes": { "tags": [ "0xRay", "Plugin", "Validation", "Codex", "GitHooks", "Bridge" ], "related_skills": [] } }
description
Manage 0xRay framework from Hermes Agent via the native xray-hermes plugin. Covers the 4 plugin tools (validate, codex_check, health, hooks), lifecycle hooks, slash commands, bridge architecture, and CLI fallback.

03 SKILL.md 正文

0xRay Hermes Plugin (xray-hermes)

Native Hermes plugin providing 0xRay framework integration — quality gates, codex enforcement, git hooks, and full pre/post processing pipeline. Runs via a Node.js bridge to compiled framework components.

When to Use

  • User asks about 0xRay health, validation, or codex checks
  • User wants to install/manage git hooks for automated enforcement
  • User asks about the plugin's tools, hooks, or slash commands
  • User asks about bridge errors or framework not loading
  • User wants to validate files before committing or pushing

Plugin Architecture

~/.hermes/plugins/xray-hermes/
├── __init__.py         # Plugin registration, hooks, slash commands
├── tools.py            # 4 tool handlers (validate, codex_check, health, hooks)
├── schemas.py          # JSON schemas the LLM sees
├── bridge.mjs          # Node.js bridge to compiled 0xRay framework
├── plugin.yaml         # Plugin metadata (name, version, tools, hooks)
├── types.py            # TypeScript-equivalent type definitions
├── after-install.md    # Post-install instructions
└── test_plugin.py      # Tests

Bridge protocol: JSON over stdin/stdout to bridge.mjs (Node.js). The bridge lazy-loads compiled framework modules from dist/:

  • dist/plugin/quality-gate.js — codex violation detection
  • dist/processors/processor-manager.js — pre/post processor pipeline
  • dist/state/state-manager.js — persistent state
  • dist/core/features-config.js — feature flags

Fallback: When bridge is unavailable, tools fall back to npx 0xray CLI commands.

Config path resolution: XRAY_CONFIG_DIR/ > .xray/ > built-in defaults.

4 Tools

xray_validate

Run pre-commit validation on files. Uses bridge quality gate + processor pipeline, falls back to CLI.

xray_validate(files=["src/my-module.ts"], operation="commit")
xray_validate(files=["src/auth.ts", "src/auth.test.ts"], operation="modify")

Parameters:

  • files (required, array of strings) — file paths to validate
  • operation (string) — commit, create, modify, refactor (default: commit)

Returns: pass/fail with per-file results and violations.

xray_codex_check

Validate code against the 69-term Universal Development Codex. Checks error-handling, type-safety, performance, security, architecture.

xray_codex_check(code="const x: any = foo()", operation="create")
xray_codex_check(code=snippet, operation="modify", focus_areas=["security", "error-handling"])

Parameters:

  • code (string) — code snippet to check. If omitted, returns framework health instead.
  • operation (required, string) — create, modify, refactor
  • focus_areas (array) — error-handling, type-safety, performance, security, architecture

Returns: violations list with actionable remediation.

xray_health

Framework health check. Returns version, loaded components, project root.

xray_health()

Returns: framework status, version, component availability, node version.

xray_hooks

Manage 0xRay git hooks (install, uninstall, list, status).

xray_hooks(action="install")
xray_hooks(action="status")
xray_hooks(action="list")
xray_hooks(action="uninstall", hooks=["pre-commit"])

Parameters:

  • action (required, string) — install, uninstall, list, status
  • hooks (array) — which hooks to manage (default: all four)

Hooks available: pre-commit, post-commit, pre-push, post-push.

Hook Type What it does
pre-commit Blocking TypeScript check + Codex validation before commit
post-commit Non-blocking Log archival + cleanup after commit
pre-push Blocking Full validation suite before push
post-push Non-blocking Comprehensive monitoring after push

2 Lifecycle Hooks

These fire automatically — no action needed from the user or agent.

pre_tool_call

Fires before ANY tool executes:

  1. Tracks session stats
  2. Logs tool-start event to logs/framework/plugin-tool-events.log
  3. For code-producing tools (write_file, patch, execute_code, write, edit): runs quality gate + pre-processors via bridge
  4. For other tools: nudges when a 0xRay MCP alternative exists (e.g., grep → search_codebase, eslint → xray_lint)

post_tool_call

Fires after ANY tool returns:

  1. Logs tool-complete event
  2. For code-producing tools: runs post-processors via bridge

on_session_start (graceful fallback)

Fires when a new session starts. Resets stats and logs to disk. Registration is wrapped in try/except for hosts that don't support it yet.

Slash Command

/xray status    — Plugin and framework health (calls bridge)
/xray stats     — Session pipeline statistics
/xray help      — Show available commands
/sr status        — Alias

Session Stats (tracked automatically)

The plugin tracks per-session counters visible via /xray stats:

  • total_tool_calls, code_operations, xray_mcp_calls, native_tool_calls
  • quality_gate_runs, quality_gate_blocks
  • pre_processor_runs, post_processor_runs
  • bridge_calls, bridge_errors

Logging

All logs go to logs/framework/ in the project root:

File Content
activity.log All pipeline events (quality gates, processors, nudges, errors)
plugin-tool-events.log Tool start/complete events with durations

Quick Decision Guide

User Says Tool / Command
"Is 0xRay working?" xray_health() or /xray status
"Check these files before I commit" xray_validate(files=[...], operation="commit")
"Is this code codex compliant?" xray_codex_check(code=..., operation="create")
"Set up git hooks" xray_hooks(action="install")
"What hooks are installed?" xray_hooks(action="status")
"Show session stats" /xray stats
"Why is the bridge failing?" Check xray_health() → if framework: "not_loaded", verify dist/ symlink

Bridge Commands (internal)

These are called by the Python tools via bridge.mjs, not directly by the LLM:

Command What it does
health Framework health check
validate Run quality gate on files
codex-check Check code against codex rules
pre-process Quality gate + pre-processors before tool
post-process Post-processors after tool
hooks Git hook management
stats Bridge/framework statistics

Bridge can be invoked directly for debugging:

echo '{"command":"health"}' | node ~/.hermes/plugins/xray-hermes/bridge.mjs
node ~/.hermes/plugins/xray-hermes/bridge.mjs health --cwd /path/to/project

Relationship to MCP Servers

The plugin and MCP servers are complementary:

  • Plugin tools = offline-first, always available, lightweight (validate, codex check, health, hooks)
  • MCP servers = deeper analysis requiring running Node.js (lint, security scan, architecture assessment, orchestration, codebase search)

The plugin's pre_tool_call hook nudges when an MCP alternative exists (e.g., "use mcp_xray_lint_lint instead of raw eslint"). This is advisory, not blocking.

Pitfalls

  • Plugin requires restart after install/edit: Hermes loads plugins once at session start.
  • Bridge needs dist/ symlink: The bridge loads compiled .js from dist/ → node_modules/0xray/dist/. If the symlink breaks, bridge returns framework: "not_loaded".
  • xray_codex_check without code param returns health, not a codex check. Pass code for actual validation.
  • CLI fallback requires npx 0xray in PATH. If bridge fails and CLI isn't available, tools return errors.
  • Quality gate blocks are logged but NOT enforced (advisory). The tool returns violations; the agent decides what to do.
  • Git hooks use symlinks from .git/hooks/ → hooks/. If the hooks/ directory doesn't exist in the project, xray_hooks(action="install") skips those hooks.
  • Project root detection walks up from CWD looking for node_modules/0xray, .xray/features.json, or package.json. Override with XRAY_PROJECT_ROOT env var.
  • logs/framework/ is created automatically. Never breaks the agent if permissions fail.

04 同仓库更多 Skills