loom/README.md

Loom

企业级 Agent 任务自动化平台。统一管理龙虾 Agent 与本地脚本引擎两类执行器，提供 Skill 注册、四维 RBAC、任务调度、LLM 路由与审计观测。

目录

loom/
├── backend/        FastAPI + SQLAlchemy (async) + subprocess 执行器 + 内嵌 scheduler
├── frontend/       React 18 + Vite + Ant Design 5 + Zustand
├── docker/         nginx 配置 / 通用 Docker 片段
├── docs/           PRD、架构设计、原型
├── docker-compose.yml
└── .env.example    所有外部配置项（含详细注释）

快速开始（开发模式）

1. 准备配置

cp .env.example .env
# 生成必须的密钥
openssl rand -hex 32                                           # → APP_SECRET_KEY
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"  # → FERNET_KEY

# 联调时再填：LOBSTER_API_BASE / LOBSTER_API_KEY / LOBSTER_CALLBACK_SECRET
# OpenAI：OPENAI_API_KEY（留空会走 mock 回显）

2. 起 pg + redis

docker compose up -d postgres redis

3. 后端

cd backend
uv venv --python 3.11 && source .venv/bin/activate
uv pip install -e '.[dev]'
alembic upgrade head
# 初始化种子数据（超管/业务员 + 菜单 + 示例产品/Skill/LLM Provider）
python -m app.scripts.seed
python -m app.scripts.seed_p4
python -m app.scripts.seed_p6
uvicorn app.main:app --reload
# → http://localhost:8000/api/v1/healthz
# → http://localhost:8000/docs
# → 内嵌 scheduler 已启动，每分钟扫 due schedules

种子账号：

• admin / admin123（超级管理员，全部菜单 + 权限）
• operator / operator123（业务员，仅仪表盘 + Skill + 任务中心）

4. 前端

cd frontend
npm i                                   # 或 pnpm / yarn
npm run dev
# → http://localhost:5173

5. 一键全栈（构建镜像后启动）

# 修改 .env 的 DATABASE_URL 等为容器内服务名（compose 已在 environment: 覆写，可保持 localhost）
docker compose --profile full up -d --build
# → http://localhost/ (前端 + nginx 反代 /api 到后端)

技术栈

• 前端：React 18 · TypeScript · Vite 5 · Ant Design 5 · Zustand · React Router 6 · Axios · Tailwind（原子工具类）
• 后端：FastAPI · SQLAlchemy 2.0 (async, asyncpg) · Pydantic v2 · Alembic · httpx · structlog · bcrypt · cryptography (Fernet)
• 基础设施：PostgreSQL 16 · Redis 7 · Nginx · Docker Compose
• 部署域名：ai.aidfxn.com

模块地图

区块	页面	后端模块
仪表盘	/dashboard	dashboard_summary
权限	组织/角色/用户/菜单	rbac_service + 4 维权限装饰器
产品	产品/渠道码/平台套件 + 平台账号（Fernet 加密）	product_service / channel_code_service
Skill	Skill 管理（双执行器 + JSON Schema 参数 + 测试台）	skill_service
任务	四步向导 + 列表 + 实时日志轮询	task_service（LOBSTER httpx / SCRIPT subprocess）
定时	cron 5 段 + 启停 + 手动触发	schedule_service（进程内 scheduler loop）
日志	操作日志（OpLog ASGI 中间件）+ 统计报表	op_log / dashboard_report
系统	执行器状态 + LLM Provider/Model/Routing + 调试台 + 脚本模板	llm_service / executor / script_template_service

开发阶段

项目按 6 个 Phase 分期推进：

Phase	目标
P1	基建：工程骨架、健康检查、登录页
P2	RBAC + 动态布局：四维权限、菜单树、路由守卫
P3	基础资产：组织/角色/用户/菜单 + 平台账号 + OpLog 审计
P4	Skill 与脚本：JSON Schema 表单、产品范围绑定、测试台
P5	任务执行核心：四步向导、双执行器、实时日志、定时任务
P6	LLM Provider/Model/Routing、执行器配置、调试台、生产部署包

测试：cd backend && pytest — 45 个集成测试全绿

详细路线参见 docs/ 与 PRD。