# oiocns-agent

**Repository Path**: nanayin/oiocns-agent

## Basic Information

- **Project Name**: oiocns-agent
- **Description**: 奥集能智能体服务
- **Primary Language**: TypeScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2026-10-12
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# oiocns-agent

奥集能智能体服务端 — 基于 Node.js 的智能体服务。

## 项目概述

oiocns-agent 是奥集能（OrginOne）平台的智能体后端服务。它作为独立的 Node.js 进程运行，通过 SignalR 长连接与奥集能内核通信，接收用户消息并调用大语言模型生成智能回复。项目采用 TypeScript 编写，使用 ESM 模块系统。

**核心功能：**

- 通过 SignalR 与奥集能内核实时通信，接收用户消息

- 调用大语言模型（LLM）生成智能回复，支持流式传输

- Function Calling 工具调用（平台知识查询、内核目标搜索、当前时间查询、办事定义/实例查询与创建等），支持自定义停止条件和补充总结

- 知识库外部化（`knowledge-base/*-knowledge.json` 与 `*-knowledge.md`），支持热重载（单文件和目录模式）和文档摘要整合

- 技能系统（Skill）：将"提示词片段 + 工具定义"封装为可独立加载、按用户隔离启禁用的技能单元；`soul.md` 承载智能体人格定义，技能提示词按 priority 组装注入；技能可携带 `references/` 参考资料与 `scripts/` 只读脚本

- MCP 客户端（Model Context Protocol）：基于 `@ai-sdk/mcp` 实现多 MCP Server 管理，支持 stdio / sse / http 传输，通过 `/mcp` 指令查看与连接管理；已通过 Echo Server 子进程与 RAG MCP 端到端测试验证

- 指令系统（`/` 前缀）进行交互式配置与管理

- 多用户配置隔离，支持运行时降级

- 支持 DeepSeek 思考模式（其他厂商待 API 行为验证）

- Agent 输出验证中间件（默认关闭，环境变量 `OIP_Agent_OUTPUT_VALIDATION=1` 开启）：发送前校验禁止内容 / 输出格式 / 知识一致性 / 主题相关度，未通过时追加修复提示驱动自我修正

- RAG 智能审批（基于知识库驱动的审批决策，详见 [apps/docs/RAG智能审批实现技术文档.md](apps/docs/RAG智能审批实现技术文档.md)）

## 平台架构文档

![奥集能平台架构总览](apps/docs/architecture-overview.png)

> 完整架构设计文档：[奥集能平台架构设计文档](apps/docs/platform-architecture.md) —— 涵盖双核分离架构、各子系统职责、协议契约、数据模型、端到端关键流程与技术债清单。

## 技术栈

| 类别            | 技术                                          |
| ------------- | ------------------------------------------- |
| 运行时           | Node.js >= 22 (ES2022)                      |
| 语言            | TypeScript 5.x                              |
| 实时通信          | @microsoft/signalr 7.x                      |
| Vercel AI SDK | ai ^6.x                                     |
| MCP 客户端       | @ai-sdk/mcp ^2.x                            |
| LLM Provider  | @ai-sdk/openai ^3.x, @ai-sdk/anthropic ^3.x |
| 加密            | crypto-js (AES-ECB)                         |
| 压缩            | pako (gzip/ungzip)                          |
| 工具库           | lodash、dayjs                                |
| HTTP 框架（控制台）  | Hono                                        |
| 文档站           | VitePress ^1.6（`apps/docs/` 构建为静态站点，随控制台以 `/docs/` 托管） |
| 开发工具          | tsx (开发运行)、tsc (编译构建)                       |
| 测试框架          | Vitest ^4.x                                 |

## 环境要求

- **Node.js >= 22.0.0 (LTS)**：项目依赖 `@microsoft/signalr` 的浏览器兼容 `WebSocket` API，Node.js 22 及以上版本内置了稳定的全局 `WebSocket` 客户端；`package.json` 已通过 `engines` 字段声明

- Node.js 18 及更低版本已停止维护，不再提供支持

- **TypeScript 类型定义**：`@types/node` ^22 与 `engines` 声明的最低 Node 版本对齐；`tsconfig.json` 已启用 `strict: true`（新增代码需满足全部严格项，详见 [AGENTS.md](AGENTS.md) 的「编码约定」章节）

## 目录结构

```
oiocns-agent/
├── index.ts                  # 应用入口
├── config.base.json          # 通用配置基线（不含敏感信息）
├── package.json              # 项目依赖与脚本
├── tsconfig.json             # TypeScript 编译配置
├── vitest.config.ts          # 测试框架配置
├── .gitignore                # Git 忽略文件配置
├── LICENSE                   # 项目许可证文件
├── knowledge-base/           # 知识库数据目录
│   ├── platform-knowledge.md     # 平台知识库（Markdown 格式）
│   ├── command-knowledge.md      # 指令知识库（Markdown 格式）
│   ├── approval-knowledge.json   # 审批知识库（JSON 格式）
│   └── README.md             # 知识库维护说明
├── skills/                   # 技能系统目录（详见 skills/README.md）
│   ├── soul.md               # 智能体人格定义（始终注入的 system prompt 基础）
│   ├── platform-assistant/   # 技能：平台助手（SKILL.md 标准格式）
│   ├── time-helper/          # 技能：时间助手（含 references/ 与 scripts/）
│   └── work-creator/         # 技能：办事创建（含 references/ 与 scripts/）
├── src/
│   ├── core/                # 基础设施层（lifecycle / messaging / processing）
│   ├── domain/              # 业务领域层（context / config / commands / tools / skills / records / planner 等）
│   ├── llm/                 # LLM 编排层
│   ├── stream/              # 流式传输模块
│   ├── console/             # Web 控制台后端
│   ├── runtime/             # 运行时配置支撑
│   ├── types/               # 类型定义
│   ├── index.ts             # 智能体核心统一出口
├── packages/
│   ├── protocol/            # @orginone/protocol：协议层（详见 packages/protocol/README.md）
│   ├── oip-connection/      # @orginone/oip-connection：内核连接参数层（双命名空间端点解析 + 迁移开关）
│   ├── platform-link/       # @orginone/platform-link：链接平台层（runtime-agnostic）
│   ├── console-contract/    # @orginone/console-contract：前后端 HTTP 契约类型
│   ├── infra/               # @orginone-agent/infra：日志 / 脱敏 / 通用工具（零仓内依赖）
│   ├── event-bus/           # @orginone-agent/event-bus：内部事件总线与事件类型契约
│   ├── decision-audit/      # @orginone-agent/decision-audit：通用决策审计链
│   ├── contract/            # @orginone-agent/contract：跨包契约（消息上下文 / LLM 事件 / 运行时上下文）
│   ├── trajectory/          # @orginone-agent/trajectory：运行轨迹（事件溯源 / 落盘 / 回放）
│   ├── mcp/                 # @orginone-agent/mcp：MCP 客户端与多 Server 管理
│   ├── web-search/          # @orginone-agent/web-search：联网搜索（Responses API + 缓存 + 指标）
│   ├── memory/              # @orginone-agent/memory：用户长期记忆（自研文件记忆 / 向量检索 / tdai 直连）
│   ├── workspace/           # @orginone-agent/workspace：本地工作空间引擎（目录层 / 路径校验 / 原子写 / 行窗口 / 编辑匹配）
│   └── plugin-oip-knowledge-rag/ # @orginone-agent/plugin-oip-knowledge-rag：OIP 个人知识 RAG 插件
├── apps/
│   ├── console-frontend/    # Web 控制台前端（React + Vite + AntD + Zustand，详见 apps/console-frontend/README.md）
│   └── docs/                # VitePress 文档站应用（站点产物 apps/docs/.vitepress/dist，随控制台以 /docs/ 托管）
├── __tests__/                # 单元测试（详见 __tests__/README.md）
├── archive/                  # 归档（历史协议模块 / 未启用的 Wiki 骨架；不参与编译与测试，详见 archive/README.md）
└── docs/                     # 原文档站位置的冻结副本（活跃内容见 apps/docs/）
```

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置

配置按 **env（`OIP_Agent_*`）> config.base.json > 默认值** 的优先级叠加：

- `config.base.json`：通用配置基线，存放非敏感、常切换的配置（已内置，无需复制）。

- `agent-accounts.json`：**多智能体账号配置**（数组，含敏感 `agentKey`），所有智能体账号的唯一来源（至少配置一个，单账号即账号数为 1 的特例）。独立于上述配置层，已被 `.gitignore` 排除；参照模板创建后按需填写，控制台 `/api/agents` 与 `/agent` 指令的运行时增删会写回该文件。每个账号可另配 `admin.userIds`（该账号管理员，与进程级取并集生效）、`skills.defaultEnabled`（该账号默认技能，与进程级取并集生效）与 `llm` 覆盖段（账号级模型配置，未填写字段回退 `.env` / `config.base.json` 的全局 LLM 兜底模板）：

```bash
cp agent-accounts.example.json agent-accounts.json
```

- `.env`：**推荐配置入口**。模型 API Key 等敏感信息和运行时开关通过 `OIP_Agent_` 环境变量传入，dev 脚本（`--env-file-if-exists=.env`）会自动加载。其中的 LLM 配置为全局兜底模板，未在账号级 `llm` 段显式覆盖的账号统一使用该模板。`.env` 已被 `.gitignore` 排除，请勿提交。参照模板创建：

```bash
cp .env.example .env
```

**环境变量配置说明：**

命名规则 `OIP_Agent_<SECTION>__<KEY>`（`__` 表示嵌套路径）；数字/布尔按目标字段现类型自动转换，未设置时回退到 `config.base.json`。常用变量：

| 配置项（config.base.json 字段）            | 环境变量（.env）                                                                    |
| ----------------------------------- | ----------------------------------------------------------------------------- |
| kernel.hubUrl                       | `OIP_Agent_KERNEL__HUBURL`（或别名 `OIP_Agent_KERNEL_URL`）                        |
| llm.apiKey                          | `OIP_Agent_API_KEY`                                                           |
| llm.apiUrl                          | `OIP_Agent_LLM__BASEURL`                                                      |
| llm.modelName                       | `OIP_Agent_LLM__MODELNAME`                                                    |
| llm.temperature                     | `OIP_Agent_LLM__TEMPERATURE`                                                  |
| llm.maxTokens                       | `OIP_Agent_LLM__MAXTOKENS`                                                    |
| llm.timeoutMs                       | `OIP_Agent_LLM__TIMEOUTMS`                                                    |
| webSearch.enabled                   | `OIP_Agent_WEBSEARCH__ENABLED`                                                |
| mcp.servers 中 RAG 的 transport / url | `OIP_Agent_MCP__SERVERS__RAG__TRANSPORT` / `OIP_Agent_MCP__SERVERS__RAG__URL` |

开关型变量（`OIP_Agent_` 前缀，由 `loadRuntimeConfig` 组装时收口进 config）：输出验证 `OIP_Agent_OUTPUT_VALIDATION`、控制台 CORS 白名单 `OIP_Agent_CONSOLE_ALLOWED_ORIGINS`、用户配置缓存上限 `OIP_Agent_USER_CONFIG_CACHE_SIZE`。另有保持原名的散落直读变量（不纳入 `OIP_Agent_` 体系）：反馈加密密钥 `ASSISTANT_FEEDBACK_ENCRYPTION_KEY`；RAG 专属变量（`RAG_PYTHON_COMMAND` 等）与 python/rag-service 部署生态共用 `RAG_*` 命名。完整清单见 [.env.example](.env.example)。

以下为各配置字段说明（`config.base.json` 字段形态，环境变量等价写法见上表与 [.env.example](.env.example)）：

**内核连接配置：**

```json
{
  "kernel": {
    "hubUrl": "https://assetcloud.zj.gov.cn/orginone/kernel/hub",
    "publicOrigin": "https://assetcloud.zj.gov.cn"
  }
}
```

> 各账号认证密钥（agentKey）不在 kernel 中配置，统一在 `agent-accounts.json` 的 `agents[].agentKey` 填写。该 Key 由 OrginOne 平台生成，本仓库和 Compose 不会自动获取；它与下面的 `llm.apiKey` 是两类密钥。

> 内核可选重连参数（均有默认值，仅需覆盖时填写）：`reconnectBaseDelayMs`（重连基础延迟，默认 1000）、`reconnectMaxDelayMs`（重连最大延迟，默认 60000）、`maxReconnectAttempts`（最大重连次数，默认 50）、`autoReauthOnExpired`（登录过期自动重新登录，默认 true）、`metadataMaxRetries`（Agent 元数据获取最大重试次数，默认 3）。

**LLM 配置（全局兜底模板）：**

> `llm` 为全局兜底模板；账号级差异在 `agent-accounts.json` 的 `agents[].llm` 覆盖段配置（仅覆盖显式填写字段，空字符串视同未配置），未填写字段回退此模板。

```json
{
  "llm": {
    "provider": "deepseek",
    "apiKey": "sk-your-api-key",
    "modelName": "deepseek-v4-flash",
    "systemPrompt": "你是一个专业的技术支持工程师...",
    "temperature": 0.7,
    "maxTokens": 2000,
    "timeoutMs": 60000,
    "contextCapacity": 10
  }
}
```

| 参数              | 必填 | 说明                                                                                      |
| --------------- | -- | --------------------------------------------------------------------------------------- |
| provider        | 是  | LLM 服务商（deepseek / qwen / kimi / siliconflow / custom）                                  |
| apiUrl          | 否  | API 服务基础地址，不含具体路径。已知 provider 会自动填充默认值，仅 custom 或需覆盖时填写                                 |
| apiMode         | 否  | API 模式（openai-chat / openai-response / anthropic）。已知 provider 会自动填充默认值，仅 custom 或需覆盖时填写 |
| apiKey          | 是  | API 密钥                                                                                  |
| modelName       | 是  | 模型名称                                                                                    |
| systemPrompt    | 否  | 系统提示词，定义智能体角色与行为                                                                        |
| temperature     | 否  | 采样温度（0\~2），控制回复随机性                                                                      |
| maxTokens       | 否  | 单次回复最大 token 数                                                                          |
| timeoutMs       | 否  | 请求超时时间（毫秒）                                                                              |
| contextCapacity | 否  | 上下文窗口大小（1\~50），默认 10                                                                    |
| toolMaxSteps    | 否  | 工具调用最大步数（1\~200），默认 8                                                                    |

**上下文管理配置：**

```json
{
  "context": {
    "defaultCapacity": 10,
    "fetchCount": 30,
    "maxCapacity": 50,
    "maxFetchCount": 100,
    "contextTtlMs": 1800000
  }
}
```

| 参数              | 必填 | 说明                                                |
| --------------- | -- | ------------------------------------------------- |
| defaultCapacity | 否  | 默认上下文容量，与 `llm.contextCapacity` 共同决定发送给 LLM 的消息条数 |
| fetchCount      | 否  | 首次从后端拉取历史消息的数量                                    |
| maxCapacity     | 否  | 上下文容量上限（1\~50），用户配置超过此值时会被截断                      |
| maxFetchCount   | 否  | 单次拉取历史消息的最大数量，补充拉取时不超过此值                          |
| contextTtlMs    | 否  | 内存上下文缓存过期时间（毫秒），默认 30 分钟                          |

**管理员配置：**

```json
{
  "admin": {
    "userIds": []
  }
}
```

| 参数      | 必填 | 说明                                                         |
| ------- | -- | ---------------------------------------------------------- |
| userIds | 否  | 管理员用户 ID 列表，`/log`、`/admin`、`/skill reload` 等管理员指令仅对这些用户生效 |

**技能系统配置：**

```json
{
  "skills": {
    "skillsDir": "skills",
    "defaultEnabled": []
  }
}
```

| 参数             | 必填 | 说明                                                  |
| -------------- | -- | --------------------------------------------------- |
| skillsDir      | 否  | 技能目录路径，默认 `skills`                                  |
| defaultEnabled | 否  | 默认启用的技能 ID 列表（`injectionMode=on-demand` 的技能，作为全局默认） |
| pythonCommand  | 否  | Python 解释器命令（技能 scripts 执行用），默认 `python`            |

> 技能系统启动时扫描 `skillsDir` 目录，加载 `soul.md`（人格定义）和所有子目录下的技能（`SKILL.md`：YAML frontmatter + Markdown body）。技能的启禁用按用户隔离，`injectionMode=always` 的技能对所有用户始终启用。技能目录可选包含 `references/`（参考资料）和 `scripts/`（只读脚本）子目录，由 `SkillLoader` 扫描清单后按需加载。详见 [skills/README.md](skills/README.md)。

> **已知 provider 自动填充**：当 `provider` 设为 `deepseek`、`qwen`、`kimi`、`minimax`、`xiaomi`、`siliconflow` 时，系统会自动从内置配置中获取 `apiUrl` 和 `apiMode` 的默认值，无需手动填写。仅在使用 `custom` provider 或需要覆盖默认值时才需指定这两个字段。
>
> `apiUrl` 填写 API 服务基础地址，允许包含版本号前缀（如 `/v1`、`/v4`），不允许包含具体 endpoint 路径（如 `/v1/chat/completions`）。不含版本号时系统自动追加 `/v1`。

支持的 provider：`deepseek`、`qwen`、`kimi`、`minimax`、`xiaomi`、`siliconflow`、`custom`

支持的 apiMode：`openai-chat`、`openai-response`、`anthropic`

**运行轨迹 / 工具守卫 / 会话消息队列配置（Loop 三环）：**

```json
{
  "trajectory": {
    "enabled": false,
    "ttlMs": 604800000
  },
  "toolGuard": {
    "enabled": false,
    "maxRetry": 3
  },
  "sessionQueue": {
    "maxSize": 100,
    "ttlMs": 3600000
  }
}
```

| 参数                   | 必填 | 说明                                 |
| -------------------- | -- | ---------------------------------- |
| trajectory.enabled   | 否  | 是否启用运行轨迹（事件溯源落盘，默认 `false`）        |
| trajectory.ttlMs     | 否  | 轨迹文件 TTL（毫秒），默认 604800000（7 天）     |
| toolGuard.enabled    | 否  | 是否启用工具结果守卫（错误分类 + 分级处置，默认 `false`） |
| toolGuard.maxRetry   | 否  | 守卫对可重试错误的最大重试次数，默认 3               |
| sessionQueue.maxSize | 否  | 每会话消息队列上限，超限丢弃并告警，默认 100           |
| sessionQueue.ttlMs   | 否  | 会话队列记录 TTL（毫秒），默认 3600000（1 小时）    |

> Loop 三环默认关闭或渐进开启，对既有行为零破坏；详见 [apps/docs/当前架构.md](apps/docs/当前架构.md) 第 19 章。

**RAG 服务配置：**

```json
{
  "rag": {
    "enabled": false,
    "mcpServerName": "rag",
    "adminHostname": "127.0.0.1",
    "adminPort": 5179,
    "timeoutMs": 60000,
    "useCache": true,
    "useSearch": false,
    "maxResultChars": 12000,
    "source": {
      "belongMode": "current",
      "directoryCode": "RAGZSK",
      "directoryName": "RAG知识库"
    }
  }
}
```

| 参数 | 必填 | 说明 |
|------|------|------|
| rag.enabled | 否 | 是否启用独立 RAG 服务（旧 PostgreSQL RAG，仅开发者本机使用），默认 `false` |
| rag.mcpServerName | 否 | 对应的 MCP Server 名称，默认 `rag` |
| rag.adminHostname | 否 | RAG 管理接口监听地址，本地默认 `127.0.0.1`；容器内由 Compose 覆盖为 `0.0.0.0`，宿主机仍只映射回环地址 |
| rag.adminPort | 否 | RAG 服务管理端口，默认 5179 |
| rag.timeoutMs | 否 | RAG 请求超时（毫秒），默认 60000 |
| rag.useCache | 否 | 是否启用检索缓存，默认 `true` |
| rag.useSearch | 否 | 是否开启语义搜索，默认 `false` |
| rag.maxResultChars | 否 | 单次检索结果最大字符数，默认 12000 |
| rag.source | 否 | 检索文档源（`directoryCode` RAGZSK / `directoryName` / `belongMode`） |

**联网搜索配置：**

```json
{
  "webSearch": {
    "enabled": false,
    "model": "deepseek-v4-flash",
    "baseUrl": "https://api.deepseek.com",
    "apiKey": "",
    "timeoutMs": 60000,
    "maxOutputTokens": 800,
    "force": false,
    "cacheTtlMs": 300000,
    "maxRetries": 1,
    "retryDelayMs": 500
  }
}
```

`webSearch.enabled` 默认关闭。启用后注册 `web__search` 系统常驻工具。`apiKey` 优先使用联网搜索独立 Key；仅当该值为空且主 LLM 同为 `deepseek` 时才复用 `llm.apiKey`，主 LLM 为其他厂商时不会复用（其 Key 不适用于 DeepSeek Responses API），此时工具跳过注册并在启动日志中告警。`baseUrl` 只填写服务基础地址，不包含 `/responses`。

**MCP 配置：**

```json
{
  "mcp": {
    "servers": [
      {
        "name": "rag",
        "transport": "stdio",
        "command": "python",
        "args": ["mcp_server.py"],
        "cwd": "python/rag-service",
        "namespace": "rag"
      }
    ],
    "builtinServices": []
  }
}
```

| 参数                  | 必填 | 说明                                                                                  |
| ------------------- | -- | ----------------------------------------------------------------------------------- |
| mcp.servers         | 否  | 预注册的 MCP Server 列表（`name` / `transport` / `command` / `args` / `cwd` / `namespace`） |
| mcp.builtinServices | 否  | 内置服务注册（如 RAG 作为内置 MCP Server）                                                       |

### 3. 运行

```bash
npm run dev        # 开发模式
npm run dev:watch  # 监听模式
npm run dev:console # 开发模式（启用 Web 控制台）
npm run dev:console:watch # 监听模式（启用 Web 控制台）
npm run check      # 类型检查
```

> ⚠️ 注意：`tsx watch` 模式下信号处理存在已知问题，Ctrl+C 可能无法正常终止进程导致崩溃。

### 4. Web 控制台构建与启动

```bash
npm run build:console      # 构建前端产物到 apps/console-frontend/dist/
npm run start:console      # 生产模式启动（托管 apps/console-frontend/dist/ 静态文件）
```

控制台同时托管 `apps/docs/` 下的 VitePress 文档站，控制台顶部菜单亦有「文档」入口：

```bash
npm run dev:docs           # 文档写作热更新（独立端口 4173）
npm run build:docs         # 构建文档站到 apps/docs/.vitepress/dist/
```

`/docs/` 由控制台服务托管，开发模式与生产模式一致：开发模式经 Vite 代理访问 `http://localhost:5173/docs/`，生产模式访问 `http://<console>/docs/`。两种模式都读取构建产物，首次使用需执行一次 `npm run build:docs`（`npm run start:console` 会自动执行）；产物缺失时 `/docs/*` 不可用，其余功能不受影响。新增或删除 `apps/docs/*.md` 时，需同步更新 `apps/docs/.vitepress/config.mts` 的导航与侧边栏。

### 5. Docker Compose 部署

当前数据核知识 RAG 使用基础 Compose 加 `docker-compose.personal-rag.yml`：

```text
React -> 平台既有数据核 CRUD -> 数据核（权威文件/配置）
                                  -> Agent 已认证内核连接
                                  -> 内部 knowledge-rag-worker
                                  -> OIP-KVS 派生索引
```

React 不再上传文件到 Agent，也不访问 `/rag-admin`。Agent 复用已有内核连接，在获权数据核的集群层级下按固定代码 `RAGZSK` 定位知识目录；目录名称可变，不参与身份判断。Worker 只在内部网络提供 MCP，不持有平台令牌、不映射宿主机端口。消息中携带的数据核和文件条件只能收窄真实授权。

```bash
cp .env.example .env
# 填写 OIP_Agent_API_KEY、RAG_DB_PASSWORD
# 复制 agent-accounts.example.json 为 agent-accounts.json，并填写平台生成的 agentKey
cp agent-accounts.example.json agent-accounts.json
docker compose -f docker-compose.yml -f docker-compose.personal-rag.yml config
docker compose -f docker-compose.yml -f docker-compose.personal-rag.yml up -d --build
```

首次部署或镜像变化时才使用 `--build`。不要执行 `docker compose down -v`，以免删除索引和历史数据卷。`agent-accounts.json` 中的 `agentKey` 与模型 API Key 不是同一密钥；缺少 Agent Key 时无法读取数据核，知识 RAG 必须失败关闭。

基础 Compose 中的旧 PostgreSQL RAG 服务仍为历史兼容能力，但不参与当前浏览器辅助搜索链路，可在迁移验收后另行规划下线。完整安全边界与验收步骤见 [apps/docs/个人知识RAG-Docker部署.md](apps/docs/个人知识RAG-Docker部署.md)。旧 `/rag-admin` 方案只保留在 [历史部署手册](apps/docs/辅助搜索部署手册.md) 中用于追溯。

`agentKey` 由 OrginOne 平台生成，当前仓库和 Compose 只负责从 `agent-accounts.json` 读取，不会调用平台接口获取；部署时须挂载该文件，也可以在启动后通过控制台 `/api/agents` 添加。`OIP_Agent_API_KEY` 是 DeepSeek 等模型服务的 API Key，二者互不替代。

### 6. 测试

```bash
npm run verify              # 提交前完整校验：类型检查 + 死代码 + 全部测试
npm test                    # 运行全部测试
npm run test:watch          # 监听模式
npm test -- __tests__/mcp          # MCP 测试（含 e2e，基于 Echo Server 子进程）
```

> RAG MCP stdio 端到端测试（`__tests__/mcp/ragMcp.e2e.test.ts`）默认不执行，需设置环境变量 `RAG_MCP_E2E=1` 启用（依赖本地嵌入模型）。

## 指令系统

智能体支持通过 `/` 前缀指令进行交互式管理：

| 指令                                        | 权限      | 说明                                      |
| ----------------------------------------- | ------- | --------------------------------------- |
| /help                                     | 所有人     | 查看可用指令列表                                |
| /status (默认/agent)                        | 所有人/管理员 | 查看用户配置和会话信息 / 查看 Agent 进程状态             |
| /config show/set/reset/export             | 所有人     | 配置管理                                    |
| /model list/set/test                      | 所有人     | 模型管理                                    |
| /new                                      | 所有人     | 新建对话                                    |
| /clear                                    | 所有人     | 清除上下文（重新从后端加载历史）                        |
| /retry                                    | 所有人     | 重新生成回复                                  |
| /context (默认/list/capacity)               | 所有人     | 上下文管理                                   |
| /export md/json/txt                       | 所有人     | 对话导出                                    |
| /thinking show/on/off/effort/budget       | 所有人     | 思考模式管理（DeepSeek 已适配）                    |
| /preset list/apply/save/delete            | 所有人     | 预设配置快速切换                                |
| /session (默认/list/close)                  | 所有人/管理员 | 会话管理                                    |
| /tool list/call                           | 所有人/管理员 | 工具查看与手动调用（enable/disable 已废弃，改用 /skill） |
| /search                                   | 所有人     | 内核目标搜索（依赖 FrontendSearchGateway）        |
| /skill list/info/enable/disable           | 所有人     | 技能管理（查看/启禁用）                            |
| /skill reload                             | 管理员     | 重新加载技能                                  |
| /mcp list/tools                           | 所有人     | 查看 MCP 服务器与工具                           |
| /mcp connect/disconnect                   | 管理员     | MCP 服务器连接管理                             |
| /admin users/degraded/sync/cleanup/health | 管理员     | 管理员运维指令                                 |
| /log level                                | 管理员     | 设置日志级别                                  |

> 完整指令说明详见 [src/domain/commands/README.md](src/domain/commands/README.md)

## 配置架构

项目采用**多用户配置隔离**架构：

- **进程级配置**：`config.base.json` 提供无敏感信息的通用基线（已内置），`.env` 中的 `OIP_Agent_*` 环境变量用于本地差异、敏感信息注入与容器运行时覆盖；存量 `config.json` 在启动时由一次性迁移脚本自动转换为 `.env`（迁移后请手动删除）

- **用户级配置**：每个用户的 LLM 配置保存在内核数据核，实现多用户配置隔离

- **配置优先级**：用户配置 > 环境变量（`OIP_Agent_*`）> `config.base.json` > 代码默认值

当后端数据核不可用时，系统自动进入**运行时降级模式**：配置在内存中立即生效，后端恢复后自动同步。

## 注意事项

- `.env` 与 `agent-accounts.json` 包含敏感信息（API Key / agentKey 等），已被 `.gitignore` 排除，切勿提交到版本库

- LLM 上下文窗口可配置（`contextCapacity`，默认 10，范围 1\~50）

## 文档导航

| 文档                                                                         | 说明                                                                                                  |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [apps/docs/控制台API调用文档.md](apps/docs/控制台API调用文档.md)                                   | 控制台 HTTP API 完整文档（含已实现与规划端点）                                                                        |
| [src/README.md](src/README.md)                                 | 源代码结构总览 / 智能体核心模块说明，涵盖服务生命周期、消息处理、LLM 编排、流式传输、工具调用、上下文管理等                                                   |
| [packages/README.md](packages/README.md)                                 | 独立包清单与新增包约定：何时该新增包、落地步骤与漏改表现、包内结构约定、新增能力的落点速查                                                   |
| [packages/platform-link/README.md](packages/platform-link/README.md)         | 链接平台层说明（内核连接 / 事件映射 / 桥接，runtime-agnostic）                |
| [apps/console-frontend/README.md](apps/console-frontend/README.md)         | Web 控制台前端应用说明，包含目录结构、技术栈、启动方式、核心功能和构建优化                                                        |
| [src/console/README.md](src/console/README.md)                 | Web 控制台后端模块说明，包含 HTTP API、SSE 事件推送、调试子系统和连接管理                                                       |
| [src/domain/commands/README.md](src/domain/commands/README.md) | 指令处理器完整文档，包含所有已实现和计划中的指令接口定义、使用示例与开发规范                                                              |
| [src/domain/tools/README.md](src/domain/tools/README.md)       | 内置工具模块说明，包含工具列表、知识库外部化、新增工具指南                                                                       |
| [skills/README.md](skills/README.md)                                       | 技能系统说明，包含 soul.md 人格定义、SKILL.md（YAML frontmatter + Markdown body）规范、references/scripts 子目录用法和技能开发流程 |
| [knowledge-base/README.md](knowledge-base/README.md)                       | 知识库数据维护说明，包含数据格式、新增条目操作流程和维护注意事项                                                                    |
| [packages/protocol/README.md](packages/protocol/README.md)                                       | 奥集能基础库说明，包含内核 API 通信层、SignalR 协议、通用工具库及从前端迁移的修改要点                                                   |
| [packages/oip-connection/README.md](packages/oip-connection/README.md)                             | 内核连接参数层说明：双命名空间（`/orginone/kernel` ↔ `/oip/v1`）端点解析与迁移开关集中点                                        |
| [packages/console-contract/README.md](packages/console-contract/README.md)             | 前后端共享 HTTP 契约类型说明（ApiResponse、配置/调试/连接/轨迹响应体）                                                              |
| [archive/README.md](archive/README.md)             | 归档说明：从协议包移出的历史模块（组织模型、事物管理、工作流、脚本引擎）与未启用的 Wiki 骨架                                                            |
| [packages/infra/README.md](packages/infra/README.md)                | 智能体运行时基建说明（日志、敏感信息脱敏、通用工具），不依赖仓内其他模块                                              |
| [packages/event-bus/README.md](packages/event-bus/README.md)          | 智能体内部事件总线说明（类型安全的发布订阅层）                                                |
| [packages/decision-audit/README.md](packages/decision-audit/README.md)     | 通用决策审计链说明（四类决策统一审计、可重放验证的抗篡改日志）                                            |
| [packages/contract/README.md](packages/contract/README.md)           | 智能体跨包契约说明（被多模块共同依赖的纯类型契约）                                                 |
| [packages/trajectory/README.md](packages/trajectory/README.md)         | 运行轨迹（事件溯源）说明，包含逐事件落盘、查询与回放                                                |
| [packages/mcp/README.md](packages/mcp/README.md)                | MCP 领域说明，包含客户端与多 Server 管理及类型契约                                                |
| [packages/web-search/README.md](packages/web-search/README.md)         | 联网搜索说明，包含 Responses API 调用、来源提取、超时重试、缓存与指标                                          |
| [packages/memory/README.md](packages/memory/README.md)         | 用户长期记忆说明，包含 MemoryBlock 三分类、向量检索降级与 TencentDB Agent Memory 直连适配                                          |
| [packages/workspace/README.md](packages/workspace/README.md)          | 本地工作空间引擎说明（受管入口 / 路径硬校验 / 原子写 / 行窗口读取 / 多段编辑匹配 / 包边界）                                  |
| [packages/plugin-oip-knowledge-rag/README.md](packages/plugin-oip-knowledge-rag/README.md) | OIP 个人知识 RAG 插件说明，含插件化路线的目录职能与生命周期                                           |
| [__tests__/README.md](__tests__/README.md)          | 测试目录说明，包含测试文件清单、共享 Mock 工具使用方法和新测试编写规范                                                              |