SmartDock

SmartDock 是一个开源的智能体工作台：左侧是会话，右侧是工作区，技能点一下就能开工，工具调用全程可见，写操作先确认再执行。它就是你在截图里看到的那个界面——不是 SDK 加一个聊天框的示例。

引擎侧按 agentId 注册多智能体，走 ReAct 工具循环；业务能力通过「工具 SPI」接进来，不用改引擎核心。同一套底座上还带一条用户画像引擎（事件 → 指标 → 快照），让助手能查「这个人最近怎么样」，而不只是查任务列表。

30 秒了解

智能体工作台

进门就是这一步：一句「今天帮你做点什么」，下面是这个租户里你能用的技能卡——点一张，输入框自动填好完整问法，不用想怎么开口。

会话页长这样：左边是会话历史，中间是消息流。工具调用不是黑盒——「已完成 · 用了 1 个工具 · 37 秒」点开就是每一步的耗时和参数。

技能：点一张，直接开工

技能是一个 Markdown 文件（官方 SKILL.md 格式，YAML frontmatter + 正文），业务和运维同学可以直接在管理台改，不用发版。本仓内置 10 个，成员默认能用 7 个：

---
name: weekly-report
description: 用户说「帮我写周报/周报怎么写/本周总结」时，按三步问法帮用户成稿（进展/问题/下周计划）
displayName: 写周报
minRole: member
---
你正在使用「写周报」技能。目标：帮用户把这一周的事整理成一份能直接发出去的周报。
1. 先问：本周主要做了哪些事？（用户可能随手列几条，帮他归类，不要追问细节）
2. 再问：过程中遇到什么问题或卡点？怎么处理的？
3. 最后问：下周打算做什么？
成稿要求：三段式，进展写结果不写过程，问题写「卡在哪 + 谁来解决」，计划写具体动作。

• 渐进披露：只有 description 常驻技能目录（模型靠它判断何时调用），正文默认不占上下文、用到才读——单技能正文上限 20000 字符
• 三层装载：内置 classpath → config/skills/ 部署期覆写 → 管理台在线编辑（优先级最高，下一轮会话生效）
• 权限双重闸：minRole 控制谁能用，租户工具开关矩阵控制是否启用（停用后对所有角色整技能遮罩，超管也看不见）
• 可度量：每个技能的使用次数与最近使用时间都落在管理台

自动化：到点自己跑一轮

写一句要它做什么，选个时间；到点用只读工具跑一轮，结果放通知和会话里。写操作一律不执行——这是自动化与「定时脚本」的区别，也是它敢在生产环境跑的原因。失败不会静默：页面上能看原因，连续 3 次失败自动停用。

设置与能力开关

技能与工具是只读的——能力和权限在「AI 助手管理」里配，工作台只负责让你看清「我现在能用什么」。这条边界是有意为之：使用者不该在会话页里改权限。

一次请求怎么跑

接入 → ReAct 推理循环 → 工具行动 → AGUI 流式输出；模型装饰器链与权限闸贯穿同一次请求。分层细节、模块边界与判定顺序见 docs/architecture.md。

技术架构

客户端只调 REST/SSE；智能体引擎与画像引擎同进程、互不依赖——智能体通过「工具 SPI」接业务能力，画像通过「业务事件」收业务动作；平台能力（多租户、权限、计费、文件安全、风控、调度、监控、对象存储）全部来自底座。

核心能力

🧩 智能体引擎（主打）

• 多智能体注册：按 agentId 注册与路由，共用工具注册、权限、记忆、技能与计费
• ReAct 工具循环：模型自主决策调用工具，全程流式输出（AGUI/SSE，28 类事件）
• 工具 SPI 机制：业务能力通过 BizToolProvider 扩展，无需修改引擎核心
• 写操作先确认：readOnly=false 的工具在落库前停下来出确认卡，写明将改什么；待确认期间输入暂停、草稿保留
• 会话能力：多会话历史、@ 引用文件与业务对象、/ 调技能与命令、计划卡（多步任务先列计划）、结构化反问（缺信息时给选项而不是瞎猜）
• 安全防护：PII 出网脱敏、工具结果注入打标、16K 输入闸、权限三态与工具开关矩阵
• 计费系统：钱包/积分双轨、19 家预置供应商 + 自定义、多 Key 池

📊 用户画像引擎（配套）

• 事件源评分：业务动作 → 事件 → 规则 → 版本化快照，可回放、可对账
• 配置化维度：六种算子 + 时间窗 + 打分映射 + 缺失策略，80% 维度零代码
• 通用接入：任意业务源通过同构事件接入，配置维度即可产出画像

画像的完整界面与运营细节见 画像引擎文档。

🏢 平台基线

继承 RuoYi-Vue-Plus 5.6.1，多租户、权限、字典、OSS、文件安全、风控、调度、监控一应俱全。

快速开始

只想最快看到效果？ 按「方式一」起好后端与前端（约 3 分钟），用内置演示账号登录，进「智能体工作台」—— 先在「AI 模型配置」录入一个供应商 Key，就能在工作台里对话、点技能卡、看工具调用链。 画像侧想看满数据，再跑一次造数脚本、点一次「重建汇总」（约 292 事件 / 81 会话 / 4 位同事的合成演示口径； 实时看板只统计最近 5 分钟，演示种子是历史数据、显示为空属正常）。画像 Java 接入 10 分钟指南见 docs/profile-integration.md，协议字段表见 docs/profile-engine.md。

前置条件

• JDK 21、Maven 3.8+
• Node.js ≥ 20.19.0、npm ≥ 8.19.0
• PostgreSQL 14+、Redis 7
• 本机演示建议可用内存 ≥ 4G；浏览器需支持 ES2020
• 可选：MinIO（附件存储）

方式一：本地开发

1. 建库执行 SQL

export PGCLIENTENCODING=UTF8
createdb -U postgres -E UTF8 smartdock

psql -U postgres -d smartdock -f backend/script/sql/baseline/01_schema.sql
psql -U postgres -d smartdock -f backend/script/sql/baseline/02_reference.sql
psql -U postgres -d smartdock -f backend/script/sql/baseline/03_identity.sql
psql -U postgres -d smartdock -f backend/script/sql/baseline/04_role_menu.sql
# 可选：一条演示任务；跳过即为干净空库
psql -U postgres -d smartdock -f backend/script/sql/baseline/05_demo_data.optional.sql
psql -U postgres -d smartdock -f backend/script/sql/baseline/06_profile_protocol.sql
psql -U postgres -d smartdock -f backend/script/sql/baseline/07_analytics.sql

Windows CMD 用 set PGCLIENTENCODING=UTF8，PowerShell 用 $env:PGCLIENTENCODING='UTF8'。

2. 启动后端

启动前先设置两把加密密钥（16/24/32 位可见 ASCII，两把必须不同；未配置会拒绝启动）：

export SMARTDOCK_AI_CONFIG_KEY=$(openssl rand -base64 24)
export SMARTDOCK_MCP_HEADERS_KEY=$(openssl rand -base64 24)

前者保护 AI 厂商 Key（dcs_ai_config.api_key / dcs_ai_provider_access.api_key）， 后者保护 MCP 服务器请求头令牌（dcs_mcp_server.headers）。禁止写进源码或提交进仓库。 从旧版本升级时，首次启动会自动把历史密文换成新钥匙；之后请到厂商后台把对应 API Key/令牌 也换新——旧版内置钥匙已随公开源码泄露，换锁救不回已经流出去的凭证。

cd backend
mvn clean package -DskipTests
java -Duser.timezone=GMT+8 -jar ruoyi-admin/target/ruoyi-admin.jar --server.port=8090

默认连接 PostgreSQL 127.0.0.1:5432/smartdock（postgres / postgres）、Redis 127.0.0.1:6379 db0 无口令。 口令不同时用启动参数覆盖：

java -Duser.timezone=GMT+8 -jar ruoyi-admin/target/ruoyi-admin.jar \
  --spring.datasource.dynamic.datasource.master.password=你的库口令 \
  --spring.data.redis.password=你的Redis口令

3. 启动前端

cd frontend
npm ci
npm run dev

访问 http://localhost:5188，使用 admin / admin123 登录。端口冲突时，前端改 frontend/.env.development 的 VITE_APP_PORT，后端用 --server.port= 覆盖。

需要浏览器里的 Vue 调试面板时（默认关闭，避免向页面注入调试浮层）：VITE_DEVTOOLS=1 npm run dev（Windows PowerShell：$env:VITE_DEVTOOLS='1'; npm run dev）。

4. 造一份演示数据（可选）

空库也能跑，但界面没数据。想快速看到截图里的效果：

node backend/script/demo/seed-internal-ops-demo.js --base http://localhost:8090 --days 30

脚本走管理员登录 + CSV 导入端点写入合成事件（4 位同事 30 天的登录/发布/提交/审核/关闭，约 292 条），再到「数据分析 → 重建汇总」跑一次重建，即可得到约 81 会话 / 4 位同事的内部协作演示口径。同一天重复执行幂等；跨天重播请先清掉旧的 demo-io- 前缀数据，否则会叠加。

方式二：Docker Compose（Linux 服务器推荐）

编排文件在 deploy/docker-compose.yml，包含 postgres / redis / minio / backend / frontend 五个服务。 Dockerfile 的构建上下文是仓库根目录，镜像会直接拷 backend/ruoyi-admin/target/ruoyi-admin.jar 与 frontend/dist/——所以必须先构建产物，再启动编排。

1. 准备环境

• Docker Engine 24+ 与 Docker Compose v2（按官方文档安装：https://docs.docker.com/engine/install/）
• 构建工具：JDK 21、Maven 3.8+、Node.js ≥ 20.19
• 也可以在本地构建好 ruoyi-admin.jar 与 dist/ 后上传到服务器，只装 Docker

2. 构建产物

git clone https://gitee.com/rickie182/smart-dock.git
cd smart-dock

cd backend && mvn clean package -DskipTests && cd ..
cd frontend && npm ci && npm run build:prod && cd ..

3. 配置口令并启动

在 deploy/ 下新建 .env（compose 会自动读取，勿提交）：

POSTGRES_PASSWORD=换成强口令
REDIS_PASSWORD=换成强口令
MINIO_PASSWORD=换成强口令
HTTP_PORT=80
# 两把加密密钥：各执行一次 openssl rand -base64 24 生成，必须不同，勿提交
SMARTDOCK_AI_CONFIG_KEY=换成32位随机串
SMARTDOCK_MCP_HEADERS_KEY=换成另一个32位随机串

cd deploy
docker compose up -d --build
docker compose ps        # 五个服务应为 running / healthy

4. 访问与首启配置

浏览器打开 http://<服务器IP>/，用 admin / admin123 登录并立即改密； 再到「AI 模型配置」录入供应商 Key 与 CNY 价格行，在「AI 助手管理」设为默认模型 （基线不含任何 Key，未配置时助手会明确提示）。

5. Linux 运维要点

• 端口：HTTP_PORT（默认 80）对外；MinIO API 9000 对外供附件直链；管理台 9001 只绑 127.0.0.1，远程用 ssh -L 9001:127.0.0.1:9001 user@host 访问。
• 防火墙：只放行 80/443 与 9000；不要暴露 9001 与数据库/Re