# OIP-Agent **Repository Path**: orginone/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-25 - **Last Updated**: 2026-10-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # OIP-Agent · 奥集能智能体服务端 开放互联协议（Open Interconnect Protocol, OIP）**认知与决策层（L5）**的智能体服务端，Node.js ≥ 22 / TypeScript + Hono 技术栈。 奥集能（Orginone，发音 [ˈɔːdʒɪnʌn]）以所有权为第一优先级，按自组织分形理念抽象"沟通、办事、 门户、数据、关系"等通用本体，为 B/C 端融合的全场景业务提供新一代分布式应用架构与数据网络 操作系统。本仓库承载其中的**智能体服务端**：作为独立 Node.js 进程运行，以智能体账号身份经 OIP-GoInOne 前门连接内核，接收用户消息并调用大语言模型生成智能回复。 > 前身为 `oiocns-agent`，派生关系与许可声明见 [NOTICE](NOTICE)；本仓库以 MIT 协议发布。 --- ## 一、在 OIP 中的定位 OIP 各仓库按层解耦，彼此通过 HTTP / WebSocket（含 MCP）经 **OIP-GoInOne 前门**耦合，**零代码级依赖**。 | 层 | 仓库 | 与本仓库的关系 | | --- | --- | --- | | L6 人机交互 | OIP-Desktop · OIP-Web · OIP-Mobile · OIP-Lite | 经前门与之交互（AgentMessage 契约） | | L5 智能体 | **OIP-Agent（本仓库）** | 认知与决策，经前门收发 | | L4 消息 | OIP-Message | 经前门路由 | | L3 权利状态机 | OIP-Book | 经前门路由（唯一权威源） | | L2 数据 | OIP-Data | 经前门 `DataProxy` 路由 | | L1 物联网 | OIP-IoT | 经前门 `module:'iot'` 路由 | | — | OIP-GoInOne | **唯一前门**：认证、路由、上行转发 | **红线（MUST NOT 违反）** 1. MUST NOT 绕过前门直连数据核（OIP-Data / OIP-Book）——一切业务请求经前门。 2. MUST NOT 私建网络通道——Hub 只用 `@microsoft/signalr` 既有封装 （[src/ts/base/api](src/ts/base/api)），不在运行时自拼 host、手动塞 token。 3. MUST NOT 绕过协议层——不得自行拼接 `/oip/v1/*` 路径或自行解析错误码， 一律经 [src/ts/base/oip](src/ts/base/oip) 接入层与既有入口 （`KernelApi` / `StoreHub` / `UserConnectionManager`）间接使用。 ### 1.1 命名对应关系 | OIP 规范文档中的称谓 | 本仓库 | 说明 | | --- | --- | --- | | `OIP-Agent` | **OIP-Agent** | 一致 | | `oiocns-agent` | **OIP-Agent** | 迁移前的原始仓库名（派生来源，见 [NOTICE](NOTICE)） | > 平台级快照文档 [docs/辅助搜索部署手册.md](docs/辅助搜索部署手册.md) 记述的是迁移前整个 OrginOne 平台 > 的多仓全貌（`oiocns-goinone` / `oiocns-data` / `oiocns-react` / `oiocns-flutter` …）， > 其中 `oiocns-agent` 即本仓库的历史称谓，为保持与其他原始仓库名的一致记述而未改写。 --- ## 二、协议承载（三层） 本仓库对外通信按承载面分为三层，任一次交互须明确所在层次（对齐 [OIP/docs/OIP-Agent-Design.md](../OIP/docs/OIP-Agent-Design.md) §2.3）： | 层 | 方向 | 承载 | 协议 | 用途 | | --- | --- | --- | --- | --- | | ① 域协议层 | Agent ↔ OIP 核心 | HTTP REST + MCP | OIP 协议（`/oip/v1/*`） | 工具执行：VET 查询、市场发现、转移、审计 | | ② 交互协议层 | Agent ↔ 人 | 内核消息通道（SignalR + 数据核 Collection） | AgentMessage | 回复、命令下发、人工确认闭环 | | ③ 管理面 | Agent ↔ 运维 / 开发者 | Hono REST + SSE | Agent Console API | 调试、配置、连接管理、SSE 对话 | - **② 为交互主通道**：前端与智能体的对话、确认、卡片交互全部经内核消息通道完成； 后端实现位于 [src/agent/stream/](src/agent/stream)，类型经 [src/ts/base/index.ts](src/ts/base/index.ts) 重导出。 - **① 是智能体的工具底座**：OIP Tool Set 的每次调用即一次 OIP API 调用（可经 MCP 封装）。 - **③ 不承载业务交互**：仅服务部署运维与开发调试，统一 `/api/*` REST + SSE 风格。 ### 2.1 AgentMessage 契约 **类型定义与实现以 [docs/AgentMessage协议文档.md](docs/AgentMessage协议文档.md) 为准** （后端 [src/agent/stream/types.ts](src/agent/stream/types.ts) 经 [src/ts/base/index.ts](src/ts/base/index.ts) 重导出）。该文档与 `src/agent/stream/types.ts` 的导出链属对外契约，**MUST NOT 改写结构或迁移路径**。 ### 2.2 管理面 API | 资源 | 端点 | 备注 | | --- | --- | --- | | 健康检查 | `/health` · `/metrics` · `/api/health` | — | | 对话调试 | `/api/chat/stream`（POST + SSE） | — | | 连接管理 | `/api/connection/{status,connect,disconnect}` | — | | 配置 | `/api/config`（GET / PUT） | — | | 事件流 | `/api/events`（GET + SSE） | — | | 调试 | `/api/debug/*` · `/api/trajectory` · `/api/decision` | — | | 文件 / 设置 / 智能体 | `/api/files` · `/api/settings` · `/api/agent` · `/api/agents` | 设计文档未列，属本仓超集 | | 任务 / 工作空间 / 模型 / MCP / 技能 / 知识库 | `/api/tasks/*` · `/api/workspace/*` · `/api/model/*` · `/api/mcp/*` · `/api/skills` · `/api/knowledge` | **管理面预留路径**，不在当前路由表内；实际注册路由见 `src/agent/console/consoleServer.ts` | 完整端点结构见 [docs/控制台API调用文档.md](docs/控制台API调用文档.md)。 --- ## 三、OIP 接入层 所有 OIP 协议适配集中在 [src/ts/base/oip/](src/ts/base/oip)，业务代码经既有入口间接使用， **不直接触碰协议细节**。 ### 3.1 端点解析（双命名空间） 服务端同时挂载 `/orginone/kernel/*` 与 `/oip/v1/*`（双挂载），因此命名空间 切换只改地址、不改方法签名，可由开关随时回退（零中断）。 [src/ts/base/oip/endpointResolver.ts](src/ts/base/oip/endpointResolver.ts) 是唯一定值点： | 端点 | 默认（legacy） | 开关开启后 | | --- | --- | --- | | Hub（SignalR 兼容线协议） | `{origin}/orginone/kernel/hub` | `{origin}/oip/v1/hub` | | REST 降级通道 | `{origin}/orginone/kernel/rest/{method}` | `{origin}/oip/v1/rest/{method}` | | 节点能力声明 | — | `/oip/v1/bootstrap`（服务端不提供该端点，见 §3.3） | ### 3.2 功能开关 开关集中在 [src/ts/base/oip/oipFeatureFlags.ts](src/ts/base/oip/oipFeatureFlags.ts)， **默认全部关闭**——关闭时行为与迁移前逐字等价。经环境变量覆盖（仅显式真值 `1` / `true` / `yes` / `on` 生效）： | 开关 | 环境变量 | 作用 | | --- | --- | --- | | `oipNamespace` | `OIP_AGENT_FEATURE_OIPNAMESPACE` | Hub / REST 地址切到 `/oip/v1/*` | | `oipBootstrap` | `OIP_AGENT_FEATURE_OIPBOOTSTRAP` | 启动拉取 `/oip/v1/bootstrap` 做节点能力协商；失败按降级表回退，不阻塞启动 | | `oipDualTrackError` | `OIP_AGENT_FEATURE_OIPDUALTRACKERROR` | 双轨错误码：优先读字符串 `oip_code`，缺失回退既有十进制 `code` | | `oipExplicitSubscribe` | `OIP_AGENT_FEATURE_OIPEXPLICITSUBSCRIBE` | `DataNotify` 显式订阅（`Auth("Subscribe", { flags })`） | ### 3.3 切换顺序与降级 命名空间切换按下列依赖顺序推进，每一步由独立开关控制、默认关闭，可单独回退： | 顺序 | 内容 | 中断风险 | | --- | --- | --- | | 第一步 | 仅切 Hub / REST URL（`/orginone/kernel/*` → `/oip/v1/*`） | 零中断（服务端双挂载） | | 第二步 | `Auth` 调用强类型化 + 双轨错误码解析 | 低 | | 第三步 | `DataNotify` 显式订阅 | 低 | **降级策略**：`bootstrap` 端点不可用时回退到配置注入层；Hub 不可达时回退 REST 通道 （由 [src/ts/base/api/storehub.ts](src/ts/base/api/storehub.ts) 按 Hub URL 推导）； 对端不可达 MUST NOT 降级为放行。 **已知边界**：`/oip/v1/bootstrap`、`DataNotify` 推送协议，以及 §2.2 表中标注为管理面预留的 `/api/tasks/*`、`/api/workspace/*`、`/api/model/*`、`/api/mcp/*`、`/api/skills`、`/api/knowledge` 端点的服务端实现，均不由本仓提供。端点契约演进见 [OIP-Agent-Design.md](../OIP/docs/OIP-Agent-Design.md)。 ### 3.4 协议面产物 [src/ts/base/oip/protocol/](src/ts/base/oip/protocol) 下的 `topics_gen.ts` / `protocol_gen.ts` 由 [../OIP/tools/gen_protocol.py](../OIP/tools/gen_protocol.py) 从 `../OIP/spec/*.json` 生成，**MUST NOT 手工编辑**——变更一律回到 spec 后重新生成。 --- ## 四、快速开始 ### 1. 安装依赖 ```bash npm install ``` ### 2. 配置 配置按 **用户级（内核数据核）> 账号级 llm 覆盖段（`agent-accounts.json`）> 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_
__`（`__` 表示嵌套路径）；数字/布尔按目标字段现类型自动转换，未设置时回退到 `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_CONSOLE_TOKEN`、管理面 Host 白名单 `OIP_Agent_CONSOLE_ALLOWED_HOSTS`、用户配置缓存上限 `OIP_Agent_USER_CONFIG_CACHE_SIZE`；MCP 只读工具登记 `OIP_Agent_MCP__READONLY_TOOLS`；注入预算 `OIP_Agent_LLM__EVIDENCE_MAX_CHARS` / `OIP_Agent_LLM__MEMORY_MAX_CHARS`；新增的 OIP 接入层开关见 §3.2。另有保持原名的散落直读变量（不纳入 `OIP_Agent_` 体系）：反馈加密密钥 `ASSISTANT_FEEDBACK_ENCRYPTION_KEY`；RAG 专属变量（`RAG_PYTHON_COMMAND` 等）与 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" } } ``` > `hubUrl` 的具体取值由 [src/ts/base/oip/endpointResolver.ts](src/ts/base/oip/endpointResolver.ts) 收口： > 留空则按 `publicOrigin` + 当前命名空间推导；`oipNamespace` 开关开启时，legacy 形态会被改写为 > `/oip/v1/hub`（见 §3.1）。 > 各账号认证密钥（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 / minimax / xiaomi / 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 三环默认关闭或渐进开启，对既有行为零破坏；详见 [docs/当前架构.md](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": "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 # 构建前端产物到 console/dist/ npm run start:console # 生产模式启动（托管 console/dist/ 静态文件） ``` 控制台同时托管 `docs/` 下的 VitePress 文档站，控制台顶部菜单亦有「文档」入口： ```bash npm run dev:docs # 文档写作热更新（独立端口 4173） npm run build:docs # 构建文档站到 docs/.vitepress/dist/ ``` `/docs/` 由控制台服务托管，开发模式与生产模式一致：开发模式经 Vite 代理访问 `http://localhost:5173/docs/`，生产模式访问 `http:///docs/`。两种模式都读取构建产物，首次使用需执行一次 `npm run build:docs`（`npm run start:console` 会自动执行）；产物缺失时 `/docs/*` 不可用，其余功能不受影响。新增或删除 `docs/*.md` 时，需同步更新 `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 服务为历史兼容能力，不参与当前浏览器辅助搜索链路，其数据卷不在迁移中删除。完整安全边界与验收步骤见 [docs/个人知识RAG-Docker部署.md](docs/个人知识RAG-Docker部署.md)。旧 `/rag-admin` 方案只保留在 [历史部署手册](docs/辅助搜索部署手册.md) 中用于追溯。 `agentKey` 由 OrginOne 平台生成，当前仓库和 Compose 只负责从 `agent-accounts.json` 读取，不会调用平台接口获取；部署时须挂载该文件，也可以在启动后通过控制台 `/api/agents` 添加。`OIP_Agent_API_KEY` 是 DeepSeek 等模型服务的 API Key，二者互不替代。 ### 6. 测试 ```bash npm test # 运行全部测试 npm run test:watch # 监听模式 npx vitest run __tests__/domain/mcp/mcp.e2e.test.ts # MCP 端到端测试（基于 Echo Server 子进程） npx vitest run __tests__/domain/mcp/mcp.protocol.test.ts # MCP 协议测试 # 协议面产物漂移校验（在 ../OIP 下执行；产物必须与 spec 一致） python3 ../OIP/tools/gen_protocol.py --check ``` > RAG MCP stdio 端到端测试（`__tests__/domain/mcp/ragMcp.e2e.test.ts`）默认不执行，需设置环境变量 `RAG_MCP_E2E=1` 启用（依赖本地嵌入模型）。 **环境要求**：Node.js >= 22.0.0（LTS，`package.json` 的 `engines` 已声明），TypeScript 5.x。 --- ## 五、目录结构 ```text OIP-Agent/ ├── index.ts # 应用入口（单进程：SignalR 客户端 + Hono 控制台服务） ├── config.base.json # 通用配置基线（不含敏感信息） ├── package.json # 项目依赖与脚本 ├── tsconfig.json # TypeScript 编译配置 ├── vitest.config.ts # 测试框架配置 ├── Dockerfile # 容器构建 ├── docker-compose*.yml # 部署编排 ├── .env.example # 环境变量模板（.env 不入库） ├── LICENSE / NOTICE # 许可与原始来源声明 ├── scripts/ # 运维脚本（配置一次性迁移等） ├── knowledge-base/ # 知识库数据目录（详见 knowledge-base/README.md） ├── skills/ # 技能系统目录（详见 skills/README.md） ├── src/ │ ├── agent/ # 智能体核心模块（详见 src/agent/README.md） │ │ ├── console/ # 管理面后端（/api/*） │ │ ├── core/ # 基础设施层（生命周期 / 消息 / 处理） │ │ ├── domain/ # 业务领域层（上下文 / 指令 / 工具 / 网关 / MCP / 技能） │ │ ├── llm/ # LLM 编排层 │ │ ├── plugins/ # 插件（数据核知识 RAG 等） │ │ ├── stream/ # 流式传输（AgentMessage 契约实现） │ │ ├── runtime/ # 运行时配置与支撑 │ │ └── types/ # 类型定义 │ └── ts/ # 奥集能基础库（详见 src/ts/README.md） │ ├── base/ # 基础层（api / common / protocol / oip） │ └── core/ # 核心领域层 ├── console/ # Web 控制台（前端 + 构建产物，详见 console/README.md） │ └── frontend/ # React 前端源码（npm workspace） ├── rag-service/ # 旧 PostgreSQL RAG 服务（Python，独立服务） ├── oip-knowledge-rag-worker/ # 数据核知识 RAG worker（Python MCP 服务） ├── __tests__/ # 单元测试（详见 __tests__/README.md） └── docs/ # 项目文档与 VitePress 文档站，站点产物 docs/.vitepress/dist ``` --- ## 六、指令系统 智能体支持通过 `/` 前缀指令进行交互式管理： | 指令 | 权限 | 说明 | | ----------------------------------------- | ------- | --------------------------------------- | | /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 | 所有人 | 思考模式管理 | | /preset list/apply/save/delete | 所有人 | 预设配置快速切换 | | /summarize preview/restore | 所有人 | 上下文摘要预览与回滚 | | /memory view/update/delete/blocks | 所有人 | 用户记忆查看与维护 | | /token (默认)/stats/history/reset/all | 所有人/管理员 | 用量统计查询；reset/all 为管理员操作 | | /autonomy set/show | 所有人 | 自主分级设置与查看 | | /session (默认/list/close) | 所有人/管理员 | 会话管理 | | /tool list/call | 所有人/管理员 | 工具查看与手动调用 | | /search | 所有人 | 内核目标搜索（依赖 FrontendSearchGateway） | | /websearch status/metrics/clear-cache | 所有人/管理员 | 联网搜索状态查询；metrics/clear-cache 为管理员操作 | | /skill list/info/enable/disable | 所有人 | 技能管理（查看/启禁用） | | /skill reload | 管理员 | 重新加载技能 | | /mcp list/tools | 所有人 | 查看 MCP 服务器与工具 | | /mcp connect/disconnect | 管理员 | MCP 服务器连接管理 | | /agent list/add/remove | 管理员 | 多智能体账号管理 | | /admin users/degraded/sync/cleanup/health | 管理员 | 管理员运维指令 | | /log level | 管理员 | 设置日志级别 | > 完整指令说明详见 [src/agent/domain/commands/README.md](src/agent/domain/commands/README.md) --- ## 七、配置架构 项目采用**多用户配置隔离**架构： - **进程级配置**：`config.base.json` 提供无敏感信息的通用基线（已内置），`.env` 中的 `OIP_Agent_*` 环境变量用于本地差异、敏感信息注入与容器运行时覆盖 - **用户级配置**：每个用户的 LLM 配置保存在内核数据核，实现多用户配置隔离 - **配置优先级**：用户级（内核数据核）> 账号级 llm 覆盖段（`agent-accounts.json`）> 环境变量（`OIP_Agent_*`，含 `.env`）> `config.base.json` > 代码默认值 当后端数据核不可用时，系统自动进入**运行时降级模式**：配置在内存中立即生效，后端恢复后自动同步。 ## 注意事项 - `.env` 与 `agent-accounts.json` 包含敏感信息（API Key / agentKey 等），已被 `.gitignore` 排除，切勿提交到版本库 - LLM 上下文窗口可配置（`contextCapacity`，默认 10，范围 1\~50） --- ## 八、文档导航 | 文档 | 说明 | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | [AGENTS.md](AGENTS.md) | **协作规范（先读）**：目录分层、三条红线、OIP 接入层约定、提交与测试规范 | | [docs/AgentMessage协议文档.md](docs/AgentMessage协议文档.md) | **AgentMessage 契约**：交互协议层的权威类型定义与解析规范（对外契约，MUST NOT 改写结构） | | [docs/控制台API调用文档.md](docs/控制台API调用文档.md) | 管理面 HTTP API 完整文档（含端点契约与管理面预留端点清单） | | [docs/当前架构.md](docs/当前架构.md) | 完整系统架构（22 章） | | [docs/配置系统.md](docs/配置系统.md) | 运行时配置系统实现：分层与优先级、加载流水线、环境变量覆盖规则 | | [docs/技能与MCP使用指南.md](docs/技能与MCP使用指南.md) | 技能系统与 MCP 使用说明 | | [src/README.md](src/README.md) | 源代码目录结构总览 | | [src/agent/README.md](src/agent/README.md) | 智能体核心模块详细说明 | | [src/agent/console/README.md](src/agent/console/README.md) | 管理面后端模块说明 | | [src/agent/domain/commands/README.md](src/agent/domain/commands/README.md) | 指令处理器文档 | | [src/agent/domain/tools/README.md](src/agent/domain/tools/README.md) | 内置工具模块说明 | | [console/README.md](console/README.md) | Web 控制台前端应用说明 | | [skills/README.md](skills/README.md) | 技能系统说明（soul.md、SKILL.md 规范、references/scripts 用法） | | [knowledge-base/README.md](knowledge-base/README.md) | 知识库数据维护说明 | | [src/ts/README.md](src/ts/README.md) | 奥集能基础库说明（内核 API 通信层、SignalR 协议、通用工具库） | | [__tests__/README.md](__tests__/README.md) | 测试目录说明 | --- ## 九、贡献 - 分支前缀：`common` / `feature` / `fix` / `hotfix` / `perf` / `other` + 姓名缩写 + 描述/日期。 - 提交信息：`type: subject`（如 `feat: 新增会话路由`）。 - 提交前运行 `npm run check` 与 `npm test`，并确认未误提交敏感文件与构建产物。 - 默认中文沟通；修改前先读相关文件，只做需求相关改动。 - 详见 [AGENTS.md](AGENTS.md) §13 协作工作流。 --- ## 十、许可 [MIT](LICENSE) © 2026 潘朝晖。 派生自 `oiocns-agent`（木兰宽松许可证第 2 版），原始来源与许可声明保留于 [NOTICE](NOTICE)。