# agentic-work-platform

**Repository Path**: wuchunxu/agentic-work-platform

## Basic Information

- **Project Name**: agentic-work-platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agentic Work Platform

## 仓库目录

```text
apps/                          浏览器应用与独立渲染站点
  web/                         平台前端
  math-renderer/               隔离数学画板站点
services/                      独立后端服务（各自保留依赖与部署边界）
  runtime-api/                  平台 API 与 Agent Runtime
  eiam-server/                  Go 认证服务
  analytics-capability-api/     数据分析能力
  document-capability-api/      文档能力
  sandbox-capability-api/       沙箱能力
  web-capability-api/           联网能力
packages/                      扁平共享代码包，不强制按前后端分层
  agent-runtime/               Vue 运行时 UI SDK（浏览器端）
  math-board-contracts/         跨端画板协议
resources/                     平台发布资源，不是代码依赖包
  skills/                      Skill 源文件、打包脚本与发布清单
  capability-packages/          能力包与 Renderer 发布定义
design/                        探索设计，非实施依据
specs/                         已收敛规范，仅 Approved 可作稳定实施依据
plans/                         实施计划与验收记录
.agents/                       开发 Agent 的规则与技能，非平台 Skill 发布源
```

目录迁移规则与旧路径映射见 [`specs/architecture/repository-layout.md`](specs/architecture/repository-layout.md)。历史设计、计划和验收日志可能保留旧根级路径，按该表定位；历史 Git revision 的路径不改写。

根 pnpm workspace 仅管理 `apps/web`、`apps/math-renderer` 和 `packages/*`；后端仍在各自目录安装依赖，不因目录分组自动加入根工作区。共享包不反向依赖应用或服务。

**已有开发环境迁移：**`.env` 与本地数据随服务目录整体移动，不覆盖已有配置；若包含旧绝对路径，请手动更新。先在根目录执行 `pnpm install --frozen-lockfile` 恢复工作区链接，再按需在后端目录安装依赖（独立服务可使用 `pnpm install --ignore-workspace --frozen-lockfile`，避免误安装根工作区）。既有端口、数据库、能力版本和 Compose 显式项目名保持不变，不执行数据库 reset、能力重发或用户绑定升级。

## 服务端口登记与分配

下表是本仓库**本地开发默认端口登记表**。新增服务先在此登记未占用端口，再同步服务默认值、`.env.example`、Compose 映射、调用端 URL 和健康检查；不得重复分配宿主端口。生产可通过环境变量/反向代理覆盖，但调用端地址必须同步。

### 固定服务端口

| 服务 | 宿主机端口 | 容器内部端口 | 配置/管理位置 | 用途与开放范围 |
| --- | --- | --- | --- | --- |
| Web前端 | **5800** | —（默认本机） | `apps/web/vite.config.ts` | 浏览器入口；占用时报错，不自动换端口 |
| Math Renderer | **5802** | 5802 | `apps/math-renderer/docker-compose*.yml`、`PORT` | 独立绘图站点；开发仅loopback，不与主站同origin |
| EIAM | **8080** | 8080 | `services/eiam-server/.env*`、`docker-compose.yml` | 认证服务；Compose仅绑定`127.0.0.1` |
| Runtime API | **8081** | —（默认本机） | `services/runtime-api/.env`：`RUNTIME_LISTEN_ADDR` | 平台API及浏览器能力代理 |
| Web Capability API | **8082** | 8082 | `services/web-capability-api/docker-compose*.yml` | 联网能力；开发Compose仅loopback |
| Document Capability API | **8083** | 8083 | `services/document-capability-api/docker-compose*.yml` | 文档能力；开发Compose仅loopback |
| SearXNG | **8085** | **8080** | `services/web-capability-api/docker-compose.dev.yml` | 搜索依赖；宿主8085，容器间`searxng:8080` |
| Analytics Capability API | **8086** | 8086 | `services/analytics-capability-api/.env`：`ANALYTICS_PORT` | 默认本机，基础Compose只expose，不发布宿主端口 |
| Sandbox Capability API | **8093** | 8093 | `services/sandbox-capability-api/docker-compose.dev.yml`、`PORT` | 仅显式启用时启动，开发仅loopback |
| MySQL（外部依赖） | **3306** | 由数据库部署决定 | 各服务`DATABASE_URL`/EIAM数据库配置 | 同一实例可用独立逻辑库和账户，不为每个业务库另分端口 |
| Valkey/Redis | **不发布** | **6379** | `services/web-capability-api/docker-compose.yml` | 仅能力服务Docker网络内部访问 |
| MinIO API | **9000** | 9000 | `services/runtime-api/compose.minio.yaml` | 对象存储；非本机可信环境应限制访问 |
| MinIO Console | **9001** | 9001 | `services/runtime-api/compose.minio.yaml` | 运维控制台，非业务API |
| OpenSandbox Control | **18092** | **8090** | `services/sandbox-capability-api/docker-compose.dev.yml` | 默认内部网络，开发显式发布到loopback |

容器内部相同端口（例如 EIAM 与 SearXNG 的8080）位于不同网络命名空间，不构成冲突；**宿主映射端口必须唯一**。端口登记不授予公网开放或认证豁免。

### 保留区与新增服务规则

| 端口/区间 | 分配规则 |
| --- | --- |
| 5800、5802 | 固定前端/绘图入口，不分配给其他服务 |
| 5801、5803–6099 | 浏览器/验收测试保留区，禁止用于日常服务 |
| 8080–8099 | 平台及能力API区；**8084、8087–8092、8094–8099待分配**，先登记再使用 |
| 18090–18099 | OpenSandbox控制/原型验证保留区，18091为已有原型，18092为开发控制面 |
| 47500–47600 | OpenSandbox执行容器动态映射保留区，禁止固定服务使用 |
| 其他端口 | 基础设施沿用登记表；新增时登记宿主端口与内部端口 |

- 新增服务同时检查登记、保留区和机器实际监听，不通过启动失败后自动递增掩盖冲突。
- 修改端口同步所有调用端和 Compose 健康检查，重启相关进程；私密 `.env` 不自动覆盖。
- 部分验收测试复用5802；先停止日常绘图实例，复用固定端口的测试串行运行。
- 覆盖 `SANDBOX_DEV_API_PORT` / `SANDBOX_DEV_CONTROL_PORT` 时，仍须登记且不能覆盖已有端口。

Windows 启动前查看监听（先核实是否为目标服务）：

```powershell
$ports = @(3306,5800,5802,8080,8081,8082,8083,8085,8086,8093,9000,9001,18092)
Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -in $ports } |
  Select-Object LocalAddress,LocalPort,OwningProcess | Sort-Object LocalPort
```

## 开发启动

前置条件：Node 22、pnpm、Go、Docker Desktop 和可访问的 MySQL。分别从服务 `.env.example` 创建 `.env`，不要提交密钥，也不要覆盖已有配置。

推荐：Runtime、Web 和 Analytics 本机运行；EIAM、MinIO、Web/Document 能力用 Docker Compose。Web/Document 开发 Compose 挂载源码执行 `pnpm dev`，支持修改后重启；需要断点时再临时改为本机运行。

以下每段从**仓库根目录**开始，使用独立终端，或先返回仓库根目录。

### 1. 基础依赖和认证

```powershell
cd services/runtime-api
docker compose -f compose.minio.yaml up -d
```

```powershell
# 先从 .env.docker.example 创建 .env.docker，配置管理员变量
cd services/eiam-server
docker compose run --rm --build eiam-migrate
docker compose run --rm eiam-seed-admin
docker compose up -d
```

EIAM 迁移和管理员种子是显式 maintenance 命令，服务启动不会重置密码；MinIO 使用既有 named volume，不删除卷。

### 2. Web 和文档能力

```powershell
cd services/web-capability-api
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
```

```powershell
cd services/document-capability-api
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
```

`WEB_CAPABILITY_SERVICE_TOKEN`、`DOCUMENT_CAPABILITY_SERVICE_TOKEN` 分别与 Runtime 的同名值一致。容器访问本机 EIAM/MinIO 使用 `http://host.docker.internal:8080` / `http://host.docker.internal:9000`；本机 Runtime 仍使用 `127.0.0.1`，不同 Compose 网络之间不能用 `localhost` 访问另一个服务。

查看日志：在相应目录执行 `docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f`。修改 Dockerfile、依赖或 Compose 后重新使用 `--build`。

### 3. Sandbox（可选）

仅使用 Python 执行或脚本 Skill 时启动。需要 Docker Desktop **Linux containers**、服务 `.env` 和固定镜像；首次初始化见 [Sandbox README](services/sandbox-capability-api/README.md)。

```powershell
cd services/sandbox-capability-api
# 保留既有开发项目名，不创建重复实例
docker compose --env-file .env -p pi-sandbox-api -f docker-compose.yml -f docker-compose.dev.yml up -d --build
# 日志与健康检查
docker compose --env-file .env -p pi-sandbox-api -f docker-compose.yml -f docker-compose.dev.yml logs -f --tail 100 sandbox-api opensandbox
Invoke-RestMethod http://127.0.0.1:8093/health
# 停止但不删除资源库、数据库或镜像
docker compose --env-file .env -p pi-sandbox-api -f docker-compose.yml -f docker-compose.dev.yml stop
```

仅重启已有服务可用同一命令前缀加 `restart`，但不会应用新的 `.env`/Compose 或重建镜像；修改配置后使用 `up -d --force-recreate`。不要在任务执行中随意重启。

独立数学实例须同时使用 `--env-file .env.math -p pi-math-sandbox-api`，确认端口和路由不冲突。

**Python HTML 输出更新不能只靠 restart 或 API 的 --build。** `python/runner.py` 在独立 Python 镜像中，需用 `node scripts/build-environment.mjs` 构建新不可变环境，再显式发布匹配的 Sandbox 能力版本、部署路由并显式安装/升级和绑定 Agent；不能覆盖旧环境或静默升级绑定。Runtime 的 `LIBRARY_ALLOWED_MIME_TYPES` 需手动加入 `text/html` 并重启。完整步骤见服务 README；普通重启不执行发布或数据库变更。

### 4. Analytics（可选，本机）

服务使用独立 MySQL 元数据库，不复用 Runtime/Library 表。默认 **8086**；旧 `.env` 中的8085须手动改为8086并同步 Runtime。

- **实际数据源：**从服务 `.env.example` 创建 `.env`，配置独立元库 `DATABASE_URL`、专用影子库 `SHADOW_DATABASE_URL`、至少32字符的 `ANALYTICS_SERVICE_TOKEN`、64位十六进制 `ANALYTICS_CREDENTIAL_KEY` 及源地址/数据库白名单。影子库不得指向业务库；MySQL 8.x 业务源用只读账户及验证TLS，不用管理员账户。
- **本机模拟：**尚无 `.env` 时可显式执行下方初始化；从 `services/runtime-api/.env` 读取本机3306管理连接，创建隔离元库、影子库、模拟业务库和专用账户，生成忽略提交的 `.env`。需要建库/授权权限，幂等upsert，不reset/drop/truncate。已有 `.env` 只有符合模拟配置才可复用；不要先复制占位示例再初始化。

```powershell
cd services/analytics-capability-api
pnpm install
# 仅本机模拟首次需要，实际数据源跳过
pnpm demo:provision -- --confirm-demo --from-runtime
# 启动前检查并应用开发迁移
pnpm prisma migrate status
pnpm prisma:migrate
pnpm prisma:generate
pnpm dev
```

另开终端：`Invoke-RestMethod http://127.0.0.1:8086/healthz`。保持生成的令牌和加密密钥不变，不公开凭据；初始化的非TLS模拟模式不用于生产。

在 `services/runtime-api/.env` 配置并重启 Runtime：

```dotenv
ANALYTICS_CAPABILITY_INTERNAL_URL=http://127.0.0.1:8086
ANALYTICS_CAPABILITY_SERVICE_TOKEN=<与 Analytics 的 ANALYTICS_SERVICE_TOKEN 相同>
```

浏览器只通过 Runtime 认证代理，不直接调用内部接口。Runtime 在容器中时改用 `host.docker.internal`。

首次使用：`/analytics` 创建私有域 → 显式接入模拟招商数据或配置只读连接/白名单并发布语义 → 浏览/执行统计资产。Agent 问数还需配置可用模型、安装问数能力包、让 Agent 采用并显式选域、保存发布；启动不会自动安装或授权。

若市场无问数包，管理员在 `services/runtime-api/` 显式执行：

```powershell
pnpm exec tsx --env-file=.env scripts/publish-analytics-capability.ts
pnpm exec tsx --env-file=.env scripts/publish-analytics-skill.ts
pnpm exec tsx --env-file=.env scripts/publish-analytics-package.ts
```

更多模拟范围、配置和私网部署见 [Analytics README](services/analytics-capability-api/README.md)。其 `compose.yaml` 不发布宿主端口，不能直接替代本机启动。

### 5. Runtime 和 Web

```powershell
cd services/runtime-api
# 首次还需 pnpm install --ignore-workspace --frozen-lockfile、pnpm prisma:generate
pnpm prisma:deploy
pnpm dev
```

```powershell
# 在仓库根目录安装工作区依赖，再启动前端
pnpm install --frozen-lockfile
pnpm dev
```

Runtime 默认 `http://127.0.0.1:8081`，Web 默认 `http://localhost:5800`，前端 EIAM 代理默认 `http://127.0.0.1:8080`。根级 `pnpm server` 也可启动 Runtime。

### 6. 独立绘图（可选）

仅绘图联调时启动，`pnpm dev` 不自动启动绘图服务。主页面 `http://localhost:5800` 的示例：手动检查 `apps/web/.env.development.local`，不覆盖已有配置：

```dotenv
VITE_MATH_BOARDS_ENABLED=true
VITE_MATH_RENDERER_BASE_URL=http://127.0.0.1:5802
```

修改后重启 Web。在仓库根目录另开终端：

```powershell
pnpm --filter @agent-platform/math-renderer build
$env:MATH_RENDERER_PARENT_ORIGINS='http://localhost:5800'
pnpm --filter @agent-platform/math-renderer start
```

另开终端 `Invoke-RestMethod http://127.0.0.1:5802/version.json`，再刷新画板验证实际渲染和交互。主页面和绘图服务必须使用**不同主机名**，仅端口不同不够；主页面用 `127.0.0.1` 时绘图用 `localhost`，同步父 origin 并重启。

`MATH_BOARD_UNAVAILABLE` 时检查5802监听、`/version.json`、浏览器 CSP/加载错误和父 origin。生产开关仍默认关闭，本地联调不替代独立 HTTPS、Cookie 隔离与安全验收。完整配置见 [Math Renderer README](apps/math-renderer/README.md)。

## 验证入口

```powershell
# 根工作区：共享包 + 应用
pnpm typecheck
pnpm test
pnpm build
# 后端各自验证，例如
pnpm --dir services/runtime-api typecheck
pnpm --dir services/runtime-api test
pnpm --dir services/runtime-api build
```

依赖外部数据库、模型、Docker 或真实浏览器的验收按各服务 README 显式启用，不把普通单元测试等同生产验收。目录迁移本身不要求重置数据库或重新发布平台资源。此次整理的验证结果与既有失败见 [迁移记录](plans/repository-layout-migration.md)。