# OIP-Agent

**Repository Path**: dauroar/OIP-Agent

## Basic Information

- **Project Name**: OIP-Agent
- **Description**: OIP-Agent 是奥集能开放架构的 认知与决策层（L5）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-09-30
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OIP-Agent · Orginone Agent Service

The **Cognition & Decision Layer (L5)** agent service of the Orginone Open Infrastructure Platform (OIP).
Stack: Node.js ≥ 22 / TypeScript + Hono.

Orginone (奥集能, pronounced [ˈɔːdʒɪnʌn]) puts ownership first and abstracts universal ontologies —
communication, affairs, portal, data, relations — under a self-organizing fractal philosophy, providing a
next-generation distributed application architecture and data-network operating system for converged
B2B/B2C scenarios. This repository hosts the **agent service**: an independent Node.js process that
connects to the kernel through the OIP-GoInOne front door as an agent identity, receives user messages,
and generates replies via large language models.

> Formerly `oiocns-agent`. See [NOTICE](NOTICE) for provenance and licensing; this repository is
> released under the MIT license.

---

## 1. Position within OIP

OIP repositories are decoupled by layer. They communicate over HTTP / WebSocket (including MCP) through
the **OIP-GoInOne front door**, with **zero code-level dependencies**.

| Layer | Repository | Relation to this repository |
| --- | --- | --- |
| L6 Human interaction | OIP-Desktop · OIP-Web · OIP-Mobile · OIP-Lite | Interact via the front door (AgentMessage contract) |
| L5 Agent | **OIP-Agent (this repository)** | Cognition and decision, via the front door |
| L4 Message | OIP-Message | Routed via the front door |
| L3 Rights state machine | OIP-Book | Routed via the front door (sole authority) |
| L2 Data | OIP-Data | Routed via the front door (`DataProxy`) |
| L1 IoT | OIP-IoT | Routed via the front door (`module:'iot'`) |
| — | OIP-GoInOne | **Sole front door**: auth, routing, uplink forwarding |

**Red lines (MUST NOT be violated)**

1. MUST NOT bypass the front door to reach the data cores (OIP-Data / OIP-Book) — all business requests go through the front door.
2. MUST NOT create private network channels — the Hub only uses the existing `@microsoft/signalr`
   wrapper ([src/ts/base/api](src/ts/base/api)); do not assemble hosts or inject tokens at runtime.
3. MUST NOT bypass the protocol layer — do not hand-build `/oip/v1/*` paths or parse error codes
   yourself; always go through [src/ts/base/oip](src/ts/base/oip) and the existing entry points
   (`KernelApi` / `StoreHub` / `UserConnectionManager`).

---

## 2. Protocol carriers (three layers)

Any interaction MUST belong to exactly one of these layers (aligned with
[OIP/docs/OIP-Agent-Design.md](../OIP/docs/OIP-Agent-Design.md) §2.3):

| Layer | Direction | Carrier | Protocol | Purpose |
| --- | --- | --- | --- | --- |
| ① Domain protocol | Agent ↔ OIP core | HTTP REST + MCP | OIP protocol (`/oip/v1/*`) | Tool execution: VET queries, market discovery, transfer, audit |
| ② Interaction protocol | Agent ↔ human | Kernel message channel (SignalR + data core Collection) | AgentMessage | Replies, command dispatch, human confirmation loop |
| ③ Management plane | Agent ↔ ops / developers | Hono REST + SSE | Agent Console API | Debugging, configuration, connection management, SSE chat |

The AgentMessage contract is authoritative in [docs/AgentMessage协议文档.md](docs/AgentMessage协议文档.md);
the backend implementation lives in [src/agent/stream/](src/agent/stream) and its types are re-exported
through [src/ts/base/index.ts](src/ts/base/index.ts). That export chain is a public contract and
**MUST NOT be restructured or relocated**.

---

### 2.1 AgentMessage contract

**The authoritative type definitions and implementation are [docs/AgentMessage协议文档.md](docs/AgentMessage协议文档.md)**
(the backend implementation lives in [src/agent/stream/types.ts](src/agent/stream/types.ts),
re-exported through [src/ts/base/index.ts](src/ts/base/index.ts)). That document together with the
export chain of `src/agent/stream/types.ts` is an external contract: **MUST NOT alter the structure or move the paths**.

### 2.2 Management-plane API

| Resource | Endpoint | Notes |
| --- | --- | --- |
| Health | `/health` · `/metrics` · `/api/health` | — |
| Chat debugging | `/api/chat/stream` (POST + SSE) | — |
| Connection management | `/api/connection/{status,connect,disconnect}` | — |
| Configuration | `/api/config` (GET / PUT) | — |
| Event stream | `/api/events` (GET + SSE) | — |
| Debugging | `/api/debug/*` · `/api/trajectory` · `/api/decision` | — |
| Files / settings / agents | `/api/files` · `/api/settings` · `/api/agent` · `/api/agents` | Not listed in the design document; a superset of this repository |
| Tasks / workspace / model / MCP / skills / knowledge | `/api/tasks/*` · `/api/workspace/*` · `/api/model/*` · `/api/mcp/*` · `/api/skills` · `/api/knowledge` | **Reserved management-plane paths**, not in the current route table; the routes actually registered are in `src/agent/console/consoleServer.ts` |

See [docs/控制台API调用文档.md](docs/控制台API调用文档.md) for the complete endpoint structure.
## 3. OIP integration layer

All protocol adaptation is centralized in [src/ts/base/oip/](src/ts/base/oip); business code consumes it
indirectly through the existing entry points and **never touches protocol details directly**.

### 3.1 Endpoint resolution (dual namespace)

The server dual-mounts `/orginone/kernel/*` and `/oip/v1/*`, so switching the namespace
only changes addresses — never method signatures — and can be reverted at any time with zero downtime.
[src/ts/base/oip/endpointResolver.ts](src/ts/base/oip/endpointResolver.ts) is the single source of truth.

| Endpoint | Default (legacy) | With flag enabled |
| --- | --- | --- |
| Hub (SignalR-compatible wire protocol) | `{origin}/orginone/kernel/hub` | `{origin}/oip/v1/hub` |
| REST fallback channel | `{origin}/orginone/kernel/rest/{method}` | `{origin}/oip/v1/rest/{method}` |
| Node capability declaration | — | `/oip/v1/bootstrap` (the server does not provide this endpoint; see §3.3) |

### 3.2 Feature flags

Flags live in [src/ts/base/oip/oipFeatureFlags.ts](src/ts/base/oip/oipFeatureFlags.ts) and **default to
off** — with everything off, behavior is byte-for-byte identical to pre-migration. Override via
environment variables (only explicit truthy values `1` / `true` / `yes` / `on` enable a flag):

| Flag | Environment variable | Effect |
| --- | --- | --- |
| `oipNamespace` | `OIP_AGENT_FEATURE_OIPNAMESPACE` | Switch Hub / REST to `/oip/v1/*` |
| `oipBootstrap` | `OIP_AGENT_FEATURE_OIPBOOTSTRAP` | Fetch `/oip/v1/bootstrap` at startup; failure falls back and never blocks startup |
| `oipDualTrackError` | `OIP_AGENT_FEATURE_OIPDUALTRACKERROR` | Dual-track error codes: prefer string `oip_code`, fall back to the existing decimal `code` |
| `oipExplicitSubscribe` | `OIP_AGENT_FEATURE_OIPEXPLICITSUBSCRIBE` | Explicit `DataNotify` subscription (`Auth("Subscribe", { flags })`) |

### 3.3 Switch order and degradation

The namespace switch proceeds in the following dependency order; each step is controlled by its own flag,
defaults to off, and can be reverted independently:

| Order | Content | Interruption risk |
| --- | --- | --- |
| Step 1 | Switch Hub / REST URL only (`/orginone/kernel/*` → `/oip/v1/*`) | None (server dual-mounts) |
| Step 2 | Strongly-typed `Auth` calls + dual-track error code parsing | Low |
| Step 3 | Explicit `DataNotify` subscription | Low |

Degradation: when `bootstrap` is unavailable, fall back to the injected configuration layer; when the Hub
is unreachable, fall back to the REST channel (derived from the Hub URL in
[src/ts/base/api/storehub.ts](src/ts/base/api/storehub.ts)). An unreachable peer MUST NOT be degraded
into an allow.

**Known boundaries**: the `/oip/v1/bootstrap` endpoint, the `DataNotify` push protocol, and the
server-side implementations of the management-plane reserved paths listed in the Chinese README §2.2
(`/api/tasks/*`, `/api/workspace/*`, `/api/model/*`, `/api/mcp/*`, `/api/skills`, `/api/knowledge`)
are not provided by this repository.

### 3.4 Protocol-face artifacts

`topics_gen.ts` / `protocol_gen.ts` under [src/ts/base/oip/protocol/](src/ts/base/oip/protocol) are
generated by [../OIP/tools/gen_protocol.py](../OIP/tools/gen_protocol.py) from `../OIP/spec/*.json`.
**MUST NOT be edited by hand** — change the spec and regenerate.

---

## 4. Quick start

```bash
npm install

# Configuration priority: user level (kernel data core) > per-account llm override (agent-accounts.json)
#   > environment (OIP_Agent_*) > config.base.json > code defaults
cp .env.example .env
cp agent-accounts.example.json agent-accounts.json   # fill in the agentKey issued by the platform

npm run dev            # development mode
npm run dev:console    # development mode with the web console
npm run check          # type check (tsc --noEmit)
npm test               # unit tests (vitest)

# Protocol-face drift check (run from ../OIP; artifacts must match the spec)
python3 ../OIP/tools/gen_protocol.py --check
```

| Command | Purpose |
| --- | --- |
| `npm run dev` / `dev:watch` | Run the agent service |
| `npm run dev:console` / `dev:console:watch` | Run with the web console |
| `npm run build` | `tsc` + `tsc-alias`, output to `dist/` |
| `npm run build:console` / `start:console` | Build / run the web console host |
| `npm run dev:docs` / `build:docs` | VitePress documentation site |
| `npm run check` / `test` / `check:dead` | tsc / vitest / knip |

Configuration layering (highest first): user level (kernel data core) > per-account `llm` override
(`agent-accounts.json`) > environment variables (`OIP_Agent_*`, including `.env`) > `config.base.json` >
code defaults. Environment variables use the `OIP_Agent_<SECTION>__<KEY>` naming scheme (`__` denotes a
nested path). `agent-accounts.json` is the sole source of agent accounts (at least one) and holds the
sensitive `agentKey`. See [.env.example](.env.example) for the full list and [README.md](README.md) for
the per-field reference.

**Requirements**: Node.js ≥ 22.0.0 (LTS), TypeScript 5.x.

Docker Compose deployment (base compose plus the personal knowledge-RAG overlay) is documented in
[docs/个人知识RAG-Docker部署.md](docs/个人知识RAG-Docker部署.md).

---

## 5. Directory structure

```text
OIP-Agent/
├── index.ts                  # Entry point (single process: SignalR client + Hono console server)
├── config.base.json          # Shared configuration baseline (no secrets)
├── scripts/                  # Operational scripts (one-off config migration, etc.)
├── src/
│   ├── agent/                # Agent core (console / core / domain / llm / stream / runtime / types)
│   └── ts/                   # Orginone base library
│       ├── base/             # api / common / protocol / oip  (oip = OIP integration layer)
│       └── core/             # Core domain layer
├── console/frontend/         # Web console (React 18 + antd + vite, npm workspace)
├── rag-service/              # Legacy PostgreSQL RAG service (Python)
├── oip-knowledge-rag-worker/ # Data-core knowledge RAG worker (Python MCP service)
├── skills/  knowledge-base/  # Skills and knowledge-base data
├── __tests__/                # Unit tests (vitest)
└── docs/                     # Project docs and VitePress site
```

---

## 6. Command system

The agent exposes `/`-prefixed commands for interactive management. Permissions: `everyone` or
`admin` (admin IDs come from `admin.userIds`, plus each account's `admin.userIds`):

| Command group | Commands | Permission |
| --- | --- | --- |
| Basic | `/help`, `/new`, `/clear`, `/retry`, `/export`, `/search` | everyone |
| Status | `/status` (default) — user config and session info | everyone |
| Status | `/status agent` — agent process state | admin |
| Configuration | `/config`, `/model`, `/context`, `/thinking`, `/preset`, `/autonomy`, `/skill list\|info\|enable\|disable`, `/mcp list\|tools` | everyone |
| Configuration | `/skill reload`, `/mcp connect\|disconnect`, `/log level` | admin |
| Context / memory | `/summarize`, `/memory` | everyone |
| Usage | `/token` (default/stats/history) | everyone |
| Usage | `/token reset\|all` | admin |
| Session / tools | `/session` (default/list/close), `/tool list\|call` | everyone / admin |
| Web search | `/websearch status` | everyone |
| Web search | `/websearch metrics\|clear-cache` | admin |
| Multi-agent | `/agent list\|add\|remove` | admin |
| Operations | `/admin users\|degraded\|sync\|cleanup\|health` | admin |

The full command reference lives in
[src/agent/domain/commands/README.md](src/agent/domain/commands/README.md).

---

## 7. Configuration architecture

The project uses a **multi-user configuration isolation** architecture:

- **Process-level configuration**: `config.base.json` provides a non-sensitive common baseline (bundled); `OIP_Agent_*` environment variables in `.env` carry local differences, secrets and container overrides.
- **User-level configuration**: each user's LLM configuration is persisted in the kernel data core, providing multi-user isolation.
- **Precedence**: user-level (kernel data core) > account-level `llm` override (`agent-accounts.json`) > environment variables (`OIP_Agent_*`, including `.env`) > `config.base.json` > code defaults.

When the backend data core is unavailable the system enters a **runtime degradation mode**: configuration takes effect in memory immediately and is synchronised once the backend recovers.

## Notes

- `.env` and `agent-accounts.json` contain secrets (API keys / agentKey) and are excluded by `.gitignore`; never commit them.
- The LLM context window is configurable (`contextCapacity`, default 10, range 1–50).

---
## 8. Documentation

| Document | Content |
| --- | --- |
| [AGENTS.md](AGENTS.md) | **Collaboration rules (read first)**: layering, red lines, OIP integration conventions |
| [docs/AgentMessage协议文档.md](docs/AgentMessage协议文档.md) | AgentMessage contract (authoritative) |
| [docs/控制台API调用文档.md](docs/控制台API调用文档.md) | Management-plane HTTP API reference |
| [docs/当前架构.md](docs/当前架构.md) | Full system architecture |
| [README.md](README.md) | Chinese README (primary; includes the complete configuration reference) |

---

## 9. Contributing

- Read [AGENTS.md](AGENTS.md) first: layering, the three red lines, OIP integration conventions, and the commit/test rules.
- Run `npm run check` and `npm test` before submitting; keep changes scoped and update the affected documents in the same change.
- Commit messages use `type: subject` (e.g. `feat: add session routing`).
## 10. License

[MIT](LICENSE) © 2026 潘朝晖.

Derived from `oiocns-agent` (Mulan PSL v2). Original provenance and license notice are preserved in
[NOTICE](NOTICE).