集成方案¶

当前章节还未完善

本文说明外部系统如何与 PE Agent、PowerCore（aipower） 进行接口对接，涵盖架构关系、认证模式、典型集成路径与环境配置。

1. 系统架构与集成边界¶

1.1 组件关系¶

                    ┌─────────────────┐
                    │  Nginx / 网关    │
                    └────────┬────────┘
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
   pe-agent-web          pe-agent-server       PowerCore
   (PE Agent 前端)        (PE Agent 后端)       (基座)
           │                 │                 │
           │                 │ customize.py    │
           │                 │ (LDAP/SSO)      │
           │                 └──── AI_POWER_* ─┘
           │                       REST / WebSocket
           └──── deploy 网关 ──── GraphRAG / PPT / 静态资源

组件	职责	对外集成点
pe-agent-web	用户 Web 界面	品牌定制、入口跳转、功能开关
pe-agent-server	登录、会话、任务入口	`customize.py` 外部账号校验；调用 PowerCore
PowerCore	Agent 引擎、任务、知识库、开放 API	`/peagent/` 内部 API；`/peagent/api/` 开放平台
deploy 网关	GraphRAG、PPT 合并等	由 PowerCore 通过 URL 配置调用

集成原则

PE Agent 不替代 PowerCore。前端/业务入口可定制，但 Agent 执行、任务状态、知识库等核心能力由 PowerCore 提供。PE Agent Server 通过 AI_POWER_* 配置作为 PowerCore 的调用方。

1.2 四类集成场景¶

场景	适用对象	对接方式	典型用途
A. 用户登录集成	企业 IT、已有账号体系	`customize.py` / AD 登录 / JWT 联邦	统一 SSO，关闭本地注册
B. PE Agent 产品集成	部署 PE Agent 完整产品	`AI_POWER_*` 环境变量	PE Agent Web + Server 对接 PowerCore
C. 开放平台 API 集成	第三方业务系统	App 凭证 + 双 Token	ERP/PLM/自研系统程序化调用 Agent
D. PE Agent 开放 API	第三方对接 PE Agent Server	`/open/v1` 轮询 HTTP	无需 WebSocket，JWT 登录 + 轮询结果

四类场景可组合：例如 B + A（PE Agent 对接 PowerCore，同时 SSO 登录），或 C/D 独立接入（不部署 PE Agent Web）。

2. 认证与账号对接¶

2.1 本地账号模式（默认）¶

PowerCore 与 PE Agent Server 均支持手机号/邮箱 + 密码本地注册登录。

PowerCore 初始管理员（docker-aipower-bin/.env）：

INIT_ADMIN_TEL=13800000000
INIT_ADMIN_PASSWORD=change-me

PE Agent Server 账号能力开关：

ENABLE_REGISTER=true
ENABLE_RESET_PASSWORD=true
ENABLE_CHANGE_PASSWORD=true
ENABLE_EXTERNAL_LOGIN_CHECK=false
ENABLE_AUTO_REGISTER=false
REGISTER_INVITE_CODE=
ENABLE_VERIFICATION_CODE=false

用户侧操作说明见用户操作手册 · 注册登录。

2.2 外部账号校验（customize.py）¶

企业统一账号体系对接时，在 pe-agent-server 部署包 中扩展 customize.py：

ENABLE_EXTERNAL_LOGIN_CHECK=true   # 登录时走外部校验，跳过本地密码
ENABLE_AUTO_REGISTER=false         # 外部校验通过但本地无用户时，是否自动建档
ENABLE_REGISTER=false              # 关闭公开注册
ENABLE_RESET_PASSWORD=false
ENABLE_CHANGE_PASSWORD=false

对接流程：

用户提交账号密码
    ↓
pe-agent-server 调用 customize.py
    ↓
向 LDAP / OAuth / 企业内部 SSO 校验
    ↓
返回标准用户对象（用户名、昵称等）
    ↓
签发 JWT，进入 PE Agent 主界面

扩展点说明

customize.py 位于 peagent-onekey-deploy / pe-agent-server 部署包，不在 PowerCore 源码仓库。具体函数签名与返回字段以部署包内注释为准。LDAP、OAuth、内部 SSO 均在此实现。

2.3 PowerCore Active Directory 登录（可选）¶

PowerCore 可在 taida-login 等分支启用 AD 模块，提供独立登录端点：

方法	路径	说明
POST	`/ad-auth/login`	AD 用户名密码登录
POST	`/ad-auth/refresh`	刷新 Token
GET	`/ad-auth/test`	Cookie 测试页

相关环境变量：

AD_DOMAIN=deltaww.com
AD_DOMAIN_NAME=delta.corp
AD_SERVERS=ldap1.example.com,ldap2.example.com
AD_MOCK_MODE=false
JWT_SECRET_KEY=...
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

适用于直接调用 PowerCore、不经过 PE Agent Server 的场景。

2.4 JWT 联邦¶

多系统共享登录态时，需统一 JWT 策略：

JWT_SECRET=...                    # 密钥（生产环境必须更换）
JWT_SUBJECT_CLAIM=username        # Token 主体字段
JWT_ALGORITHM=HS256

PE Agent Server 与 PowerCore 的密钥策略需按安全要求统一或建立联邦映射。

2.5 邀请码与验证码¶

配置位置	变量	说明
pe-agent-web	`ENABLE_INVITE_CODE`	注册页是否展示邀请码
pe-agent-server	`REGISTER_INVITE_CODE`	服务端校验码；留空=不校验
pe-agent-server	`ENABLE_VERIFICATION_CODE`	注册/忘记密码验证码
pe-agent-server	`TENCENTCLOUD_` / `TENCENT_MAIL_`	短信/邮件验证码通道

Web 端与服务端开关需策略一致。

3. PE Agent ↔ PowerCore 对接¶

3.1 必配环境变量¶

在 pe-agent-server/.env 中配置：

AI_POWER_APP_ID=app_default
AI_POWER_APP_SKEY=sk_secret
AI_POWER_API_URL=http://host.docker.internal:5080

变量	说明
`AI_POWER_APP_ID`	与 PowerCore `app_auth.appid` 一致
`AI_POWER_APP_SKEY`	与 PowerCore `app_auth.skey` 一致
`AI_POWER_API_URL`	PowerCore 后端根地址（默认端口 5080）

PowerCore 侧需在 MySQL app_auth 表注册对应应用凭证（可用 gen_keys.py 生成）。

3.2 Agent ID 映射¶

AI_POWER_CURRENT_TASK_AGENT_ID=4221
AI_POWER_HUMAN_MACHINE_DELIVERY_AGENT_ID=4315
AI_POWER_SCHEDULED_TASK_AGENT_ID=4327
AI_POWER_HIDE_END_AGENT_IDS=

变量	用途
`CURRENT_TASK_AGENT_ID`	即时任务 / 入口智能体
`HUMAN_MACHINE_DELIVERY_AGENT_ID`	专家团队 / 人机交付
`SCHEDULED_TASK_AGENT_ID`	定时任务
`HIDE_END_AGENT_IDS`	隐藏结束节点的 Agent ID，逗号分隔

上述 Agent 需在 PowerCore 中已创建且为 Public；定制环境请替换为实际 ID。

3.3 网络与连通性¶

pe-agent-server 与 PowerCore 可不在同一 Docker 网络，通过宿主机端口或 host.docker.internal 互通
deploy 网关（默认 8500）提供 GraphRAG；PowerCore 的 RAG_URL 指向 GraphRAG 服务
PPT_MERGE_BASE_URL 指向 deploy 网关，供 PowerCore 调用 PPT 合并

连通性验证：

docker exec -it pe-agent-server sh
wget -qO- http://host.docker.internal:5080/peagent/login || curl -I http://host.docker.internal:5080/peagent/login

3.4 调用关系¶

pe-agent-web  →  pe-agent-server  →  PowerCore /peagent/*
                      │                      │
                      │                      ├─ Agent 执行
                      │                      ├─ 任务查询
                      │                      └─ WebSocket 对话
                      └─ 用户 JWT / 会话管理

PE Agent Server 使用 App 凭证代表产品调用 PowerCore；用户身份由 PE Agent 登录层维护。

4. 开放平台 API 对接（第三方系统）¶

第三方业务系统不部署 PE Agent Web，可直接对接 PowerCore 开放平台 API。

4.1 接入流程概览¶

① 在 PowerCore 注册 App（appid + skey）
        ↓
② POST /peagent/api/get_token  →  app_token（应用级，约 2h）
        ↓
③ POST /peagent/api/add_user     →  同步外部用户（可选，预注册）
        ↓
④ POST /peagent/api/user_login   →  user_token（用户级，约 24h）
        ↓
⑤ 调用 Agent / 对话 / 任务 API（Bearer user_token）
        ↓
⑥ WebSocket /peagent/api/chat_ws 实时对话（可选）

详细请求参数、响应字段见接口 API；平台协议与联调流程见 PE Agent 集成；本仓库实现见 PowerCore 集成。

4.2 App 凭证与签名¶

get_token 请求头：

Header	说明
`X-App-Id`	应用 ID，如 `APP_XXXXXXXX`
`X-Timestamp`	Unix 时间戳（秒）
`X-Signature`	`HMAC-SHA256(appid + timestamp + skey, key=skey)` 十六进制

Token 类型：

Token	用途	有效期
`app_token`	用户同步、管理类 API	约 2 小时
`user_token`	调用 Agent、对话、任务	约 24 小时

4.3 Agent 授权绑定¶

开放平台调用 Agent 前，需在 PowerCore 将 App 与 Agent 绑定（表 app_auth_agent）。未绑定的 Agent 调用将返回 403。

4.4 主要 API 分组¶

分组	前缀	能力
认证	`/peagent/api/get_token` 等	签名换 Token、用户登录
Agent	`/peagent/api/enter_agent` 等	进入 Agent、CRUD Agent
对话/任务	`/peagent/api/re_generate`、`chat_ws` 等	重生成、暂停/恢复、WebSocket
文件	`/peagent/api/common/upload_file` 等	上传/下载/删除附件

在线文档（运行时）：

Swagger：https://<域名>/peagent/api-docs
OpenAPI JSON：https://<域名>/peagent/openapi.json

4.5 内部 REST API（备选）¶

若对接方已有 PowerCore 平台账号，也可使用内部 REST API（用户 JWT）：

方法	路径	说明
POST	`/peagent/login`	手机号 + 密码 → `access_token`
GET	`/peagent/agents/`	Agent 列表
POST	`/peagent/agents/call-agent`	调用 Agent，返回 `task_id`
GET	`/peagent/tasks/query_task/{task_id}`	查询任务状态与结果

认证：Authorization: Bearer <access_token>

适用于内部脚本、CLI（aiPower.py）等场景；不推荐作为第三方生产对接主路径（无 App 级隔离）。

4.6 PE Agent Server 开放 API（`/open/v1`）¶

部署 pe-agent-server 时，第三方也可通过 Open API 对接（路由前缀 /open/v1），采用 提交运行 + 轮询结果 模式，无需 WebSocket。

要点	说明
鉴权	`POST /open/v1/login`（`username` 或等价字段 `account`）→ JWT
Token 有效期	响应 `access_token_expire` 约为 JWT 有效期减 200 秒（默认 JWT 72h，约 259000 秒）
运行	`POST /open/v1/agent/run` → `record_id` → `GET /open/v1/agent/run/{record_id}` 轮询
多轮	`dialog` / `confirm` + 附件 `upload`
轮询结果	`status=completed` 时读 `content`；若最新 assistant 为「结束」节点，会跳过并返回上一条
错误码	含 `500001` 响应体校验失败

完整接口说明见接口 API。与场景 C（PowerCore App 凭证 + WebSocket）为不同入口，勿混用 Base URL 与 Token。

5. 前端与品牌定制（可选）¶

部署 PE Agent Web 时，可通过环境变量定制品牌与入口，不影响 API 对接逻辑。

# pe-agent-web/.env
APP_DOMAIN=peagent.example.com
BRAND_NAME=XX PE Agent
BRAND_LOGO_PATH=images/common/logo.png
PEAGENT_REDIRECT_BASE_URL=https://example.com
ENABLE_ADMIN_SECTION=true
ENABLE_USER_PASSWORD_CHANGE=true

部署细节见定制与集成 §4。

6. 集成方案选型指南¶

需求	推荐方案	关键配置 / 文档
员工通过 Web 使用 PE Agent，统一公司账号	A + B	`customize.py` + `AI_POWER_*`
已有 PowerCore，仅定制登录页与品牌	A + B	同上
ERP 自动触发 Agent 计算	C	App 凭证 + `enter_agent` / `chat_ws`
第三方仅 HTTP 轮询、不建 WebSocket	D	`/open/v1` + 接口 API
内部脚本批量调用 Agent	内部 API 或 C	`/peagent/login` 或 OpenAPI
知识库 RAG 能力	B 或 C + GraphRAG	`RAG_URL`、deploy 8500
多域名统一入口	B	`PEAGENT_REDIRECT_BASE_URL`

7. 环境变量速查¶

7.1 pe-agent-server（集成相关）¶

变量	说明
`AI_POWER_APP_ID` / `AI_POWER_APP_SKEY`	PowerCore 应用凭证
`AI_POWER_API_URL`	PowerCore 地址
`AI_POWER_*_AGENT_ID`	各场景 Agent 映射
`ENABLE_EXTERNAL_LOGIN_CHECK`	外部登录校验
`JWT_SECRET` / `JWT_SUBJECT_CLAIM`	JWT 配置
`REGISTER_INVITE_CODE`	注册邀请码

7.2 PowerCore（集成相关）¶

变量	说明
`PORT`	默认 5080
`PEAGENT_PATH`	API 前缀，默认 `peagent`
`SYS_INFO_SECRET_KEY`	JWT 签发密钥
`INTERNAL_KEY`	服务间内部调用密钥
`RAG_URL` / `RAG_BASE_URL`	GraphRAG 地址
`PPT_MERGE_BASE_URL`	PPT 合并网关

7.3 MySQL 数据表¶

表	用途
`app_auth`	开放平台 App 凭证
`app_auth_agent`	App 与 Agent 绑定
`app_auth_token`	App Token 记录
`user`	平台用户（含外部用户映射）

8. 安全与上线检查清单¶

[ ] AI_POWER_API_URL 指向正确 PowerCore 地址，容器/主机网络互通
[ ] AI_POWER_APP_ID / SKEY 与 PowerCore app_auth 一致，已更换生产密钥
[ ] Agent ID 与 PowerCore 实际 Public Agent 一致
[ ] 开放平台 App 已绑定需调用的 Agent
[ ] JWT_SECRET / SYS_INFO_SECRET_KEY 已更换，各系统策略对齐
[ ] SSO / customize.py 与 HR 账号体系联调通过
[ ] 邀请码、注册、验证码策略与 Web/Server 一致
[ ] HTTPS、Nginx 路由、CORS（如有跨域）已配置
[ ] LLM / Embedding API 内网可达
[ ] ONLYOFFICE / Sandpack 公网 URL 白名单已配置（若启用文档编辑）

9. 延伸阅读¶

文档	内容
接口 API	PE Agent 开放 API 与文档索引
PE Agent 集成	PowerCore 平台 HTTP/WS 对接
PowerCore 集成	PE Agent 内集成层实现说明
定制与集成	部署侧 SSO、品牌、GraphRAG 配置
PE Agent 部署	pe-agent-web / server 部署
PowerCore 部署	aipower 后端部署
操作说明	用户登录注册操作

注意：接口路径、Agent ID、域名等以实际部署环境为准。生产接入前请在测试环境完成联调并经过安全评审。

集成方案¶

1. 系统架构与集成边界¶

1.1 组件关系¶

1.2 四类集成场景¶

2. 认证与账号对接¶

2.1 本地账号模式（默认）¶

2.2 外部账号校验（customize.py）¶

2.3 PowerCore Active Directory 登录（可选）¶

2.4 JWT 联邦¶

2.5 邀请码与验证码¶

3. PE Agent ↔ PowerCore 对接¶

3.1 必配环境变量¶

3.2 Agent ID 映射¶

3.3 网络与连通性¶

3.4 调用关系¶

4. 开放平台 API 对接（第三方系统）¶

4.1 接入流程概览¶

4.2 App 凭证与签名¶

4.3 Agent 授权绑定¶

4.4 主要 API 分组¶

4.5 内部 REST API（备选）¶

4.6 PE Agent Server 开放 API（/open/v1）¶

5. 前端与品牌定制（可选）¶

6. 集成方案选型指南¶

7. 环境变量速查¶

7.1 pe-agent-server（集成相关）¶

7.2 PowerCore（集成相关）¶

7.3 MySQL 数据表¶

8. 安全与上线检查清单¶

9. 延伸阅读¶

4.6 PE Agent Server 开放 API（`/open/v1`）¶