# opc-nexus

**Repository Path**: yingyiyl/opc-nexus

## Basic Information

- **Project Name**: opc-nexus
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-29
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OPC-Nexus · Digital Employee AI Box

> A local-first workbench for solo companies and small studios: the owner gives the order, Hermes understands and coordinates it, digital employees execute it, and the system delivers verifiable artifacts.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![CI](https://github.com/h4dex/opc-nexus/actions/workflows/ci.yml/badge.svg)](https://github.com/h4dex/opc-nexus/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/h4dex/opc-nexus?display_name=tag)](https://github.com/h4dex/opc-nexus/releases)

## Current Version

| Component | Version | Notes |
| --- | --- | --- |
| OPC-Nexus desktop | `2.0.1` | Windows 10/11 and Ubuntu 22.04+ |
| Hermes Runtime | `0.19.0` | The only Quest orchestrator, pinned fork and upstream commit |
| Android Bridge | `0.4.3` | Optional mobile execution worker, not a Quest orchestrator |

Version 2.0.1 is the runtime enhancement after the Hermes architecture release and is intentionally different from the Nexus orchestration architecture in 1.x. Back up user data before upgrading. The application migrates the legacy data directory, but it does not re-enable DSH as a second control plane.

Release packages may carry pinned Codex CLI and Pi Agent runtimes under the application resources directory. The Main process prefers these application-owned runtimes and only falls back to PATH when no bundled or managed copy exists. The source tree does not commit `node_modules` or native binaries; run `npm run agents:prepare` before packaging and `npm run agents:verify` after preparation.

## How It Works

```text
Owner
  -> Quest / Hermes conversation
  -> Clarification (for complex requests)
  -> Draft plan and staffing proposal
  -> OPC-Nexus Main validates, approves and dispatches
  -> Codex / Claude / Pi / Hermes Worker / mobile worker
  -> Project directory, preview, run command, screenshots and channel receipt
```

- **Hermes** handles conversation understanding, clarification, memory, plan content and delegation proposals.
- **OPC-Nexus Main** owns project scope, employee policy, permissions, budgets, task/Run state, approvals, cancellation, recovery, delivery and audit facts.
- **Digital employees** are independent entities. A project may use a dynamic employee pool or an explicit employee allow-list; one-to-one project binding is not required.
- **DSH** is not a scheduler or a second Web workbench. If a DSH CLI is retained, it can only execute work admitted by Main.

## Hermes Project Workbench

Every project needs a real, accessible working directory. Choose it in Quest, or use the default:

```text
%USERPROFILE%/opc-nexus/projects/<project-name>-<id>/
```

Each project runtime has an isolated `HERMES_HOME`, loopback ports, a short-lived authentication lease, sessions and memory. The Hermes Web UI is embedded in Quest. Renderer code never receives the service token and cannot read another project's files, sessions or memory.

### Configure a Provider

Open Quest's **Connection settings**, enter a Provider Base URL, model and API Key, then use **Fetch models** and **Test**. API keys are stored only through Electron `safeStorage`; they are never written to this README, logs, Renderer state or Hermes memory.

Hermes performs these checks before spawning a project runtime:

1. The project directory exists and is not a symbolic link.
2. The Provider has a decryptable API Key, Base URL and model.
3. Both the Dashboard and API Gateway pass the 0.19.x health checks.

Failures show the real cause and a recovery path to Connection settings. The application never reports a fake online or completed state.

## Main Capabilities

- Embedded Hermes Chat, clarification, plans, worker progress, independent acceptance and delivery panels in Quest.
- Simple requests can return directly; complex requests follow **clarify -> plan -> approve -> dispatch -> deliver**.
- Dynamic staffing or project employee allow-lists, `@employee` mentions, sub-agent teams and independent validation workers.
- Codex, Claude Code, Pi, Hermes CLI Worker and Android Worker through one execution policy.
- Project-scoped MCP and Skill selection from one capability center, without duplicate legacy DSH plugins.
- Delivery manifests, directory reveal, Markdown/file preview, run commands, runtime URLs, screenshots and channel delivery.
- Hermes mobile Web access using TLS, one-time pairing and viewer/operator roles.
- Real WeCom, Feishu and WeChat iLink channels can bind to project conversations; remote approve, pause and cancel actions are audited.
- Debug mode writes redacted JSONL to the user data `logs/` directory for runtime, proxy, gateway, task and channel diagnosis.

## v2.0.1 Workflow

Use this sequence for a complete task:

```text
Project -> Provider -> Quest -> Clarify (when needed) -> Plan -> Approve -> Dispatch -> Verify -> Deliver
```

1. Select a real project workspace. A project does not have to bind to one employee. Simple tasks may `@` a specific employee; complex tasks let Hermes assemble a team from capability, permission and budget policies.
2. In Quest connection settings, configure the Base URL, API key and model, then use **Fetch models** and **Test**. Dispatch is blocked when a real Provider or execution runtime is unavailable.
3. Send the owner's instruction. Hermes asks persistent clarification questions when needed and creates a draft plan. After approval, Main creates the authoritative version and dispatches to Codex, Pi, Claude, Hermes Worker or a mobile worker.
4. Use the Quest governance panel to inspect employee progress, tool calls, acceptance and the delivery manifest. Delivered files can be previewed, revealed in the workspace, launched with the reported command or sent through a bound channel.
5. Mobile pairing connects only to the current project's Hermes conversation. It does not open the Android control console or expose another project. Mobile viewer/operator permissions match the desktop policy.

Simple questions can return directly. Complex work must pass through plan and approval. When a service, Provider, employee or permission is unavailable, the UI reports the real error and recovery action; it never creates Mock employees, fake success or fictional artifacts.

## Screenshots

These images are from real Quest/Hermes acceptance runs and show staffing, delivery and mobile conversation flows:

![Quest Hermes staffing](./docs/screenshots/quest-hermes-staffing.png)

![Quest Hermes delivery](./docs/screenshots/quest-hermes-delivery.png)

![Hermes mobile chat](./docs/screenshots/hermes-mobile-chat.png)

## Acceptance Boundary

Version 2.0.1 passes type checking, unit tests, production build, Hermes runtime smoke and desktop UI smoke. The complete "owner order -> Hermes staffing -> Codex/Pi multi-worker execution -> independent acceptance -> complex delivery" remains a release gate. The full writing of two 300,000-character novels is not complete, so that scenario must not be described as delivered. Release notes record actual artifacts, elapsed time and blocking causes for each scenario.

## Development and Verification

Requirements: Node.js 20+, npm 10+ and Python 3.11. The Hermes preparation scripts use `uv` to obtain the pinned Python runtime.

```bash
npm ci
npm run hermes:prepare
npm run typecheck
npm test
npm run hermes:verify
npm run hermes:smoke
npm run build
```

Run development mode with:

```bash
npm run dev
```

Build installers with:

```bash
npm run pack:win
npm run pack:linux
```

GitHub Actions repeats type checking, unit tests, Hermes runtime preparation, health smoke and production builds on Windows and Ubuntu. Release jobs also inspect the packaged Hermes runtime.

## Security Boundaries

- `contextIsolation: true` and `nodeIntegration: false`; Renderer code cannot use Node.js APIs.
- Renderer-to-Main calls go through typed preload APIs; the generic `ipcRenderer` object is never exposed.
- API keys, tokens and channel credentials remain inside Main/safeStorage.
- Every task is checked against its project directory, employee policy, permissions, budget and engine availability.
- If a Hermes process, proxy or Gateway crashes, the runtime becomes offline/error and related queue items stop; success is never inferred.

## Documentation

- [Chinese README](./README.md)
- [User guide](./docs/USER-GUIDE.md)
- [Changelog](./CHANGELOG.md)
- [Release guide](./docs/RELEASING.md)
- [Architecture](./src/docs/architecture.md)
- [API reference](./src/docs/api-reference.md)
- [Third-party notices](./THIRD-PARTY-NOTICES.md)

## License

[MIT](./LICENSE) © Senke