# meos-tool **Repository Path**: krismileJ/meos-tool ## Basic Information - **Project Name**: meos-tool - **Description**: meos-tool meos-tool meos-tool - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-10 - **Last Updated**: 2026-06-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MEOS Tool MEOS Tool 是一个基于 Nuxt 4 的鉴权型内部工具平台，用于集中承载权限工作台、地址导航栏、系统管理、API 调试和可控 AI 助手流程。项目底层使用 MySQL 保存 RBAC、配置、公告、反馈、审计、地址导航、工具运行记录和 AI 助手相关数据。 ## 当前能力 - 邮箱验证码自助注册、SMTP 发信配置、密码登录、JWT 访问令牌、刷新令牌 Cookie、退出登录、刷新令牌轮换、刷新令牌复用检测，以及个人中心资料/密码维护。 - 组织上下文、用户、角色、资源、权限，以及基于权限过滤的导航、路由和工具访问控制。 - 系统管理能力：组织、用户、角色、权限资源、配置数据、审计日志、问题反馈和系统公告管理。 - 顶栏公告与反馈：用户可查看公告、维护已读状态、提交问题或建议，管理员可在后台处理。 - 全局、组织、用户级配置解析，支持用户自定义配置和上游版本跟踪。 - 基于显式注册表的工作台： - JSON 处理：格式化、压缩和校验 JSON 文本。 - Cron 表达式：解析 5 段 Cron 表达式，并预览最近执行时间。 - API 调试：支持环境、项目、文件夹、集合、接口、请求预设、请求标签页、cURL 导入、请求头、查询参数、请求体、文档元数据、响应模板、AI 文档导入、历史记录、收藏、响应 artifact，以及服务端代理执行。 - 地址导航栏：支持组织可见的全局链接、个人分类/链接、关联链接、加密凭据、隐藏全局项、JSON 导入导出、全局配置页，以及 Chrome Manifest V3 自动填充扩展配对。 - AI 助手：支持 OpenAI-compatible 和 Anthropic 协议供应商、全局和个人供应商设置、会话、流式聊天、智能体、Skill、能力配置、Skill 包、风险控制、API Plans、结构化待补充信息，以及模型和工具运行审计。 - MySQL 表结构脚本、核心管理员/RBAC 数据初始化脚本，以及既有数据库手工补齐用的幂等生产迁移脚本。 ## 技术栈 - Nuxt 4、Vue 3、TypeScript - Nuxt UI、Tailwind CSS v4、Nuxt Icon、Nuxt Image、Nuxt Content、Nuxt Hints - Pinia、VueUse - Nitro/h3 服务端 API 路由 - Drizzle ORM、MySQL - AI SDK、OpenAI-compatible provider、Anthropic provider - Vitest、Nuxt Test Utils、Playwright - pnpm ## 运行要求 - 与当前 Nuxt 4 工具链兼容的 Node.js 版本 - pnpm `10.33.2` - MySQL 8 兼容数据库 ## 本地初始化 安装依赖： ```powershell pnpm install ``` 复制环境变量示例文件： ```powershell Copy-Item .env.example .env ``` 根据本地环境修改 `.env`。本地开发至少需要配置数据库连接和核心密钥： ```dotenv NUXT_DATABASE_URL=mysql://meos_user:meos_password@localhost:3306/meos_tool NUXT_TEST_DATABASE_URL=mysql://meos_user:meos_password@localhost:3306/meos_tool_test NUXT_JWT_SECRET=replace-with-random-secret NUXT_REFRESH_TOKEN_SECRET=replace-with-random-secret NUXT_EMAIL_VERIFICATION_SECRET=replace-with-random-secret NUXT_SMTP_SECRET=replace-with-random-secret NUXT_API_DEBUGGER_SNAPSHOT_SECRET=replace-with-random-secret NUXT_API_DEBUGGER_AUTH_SECRET=replace-with-random-secret NUXT_QUICK_LINK_SECRET=replace-with-random-secret NUXT_AI_ASSISTANT_SECRET=replace-with-random-secret NUXT_REFRESH_COOKIE_SECURE=false ``` 生产或共享环境必须使用唯一的随机密钥。HTTPS 部署环境应保持 `NUXT_REFRESH_COOKIE_SECURE=true`。 ## 数据库初始化 应用启动时不会自动建表或写入种子数据。新的 MySQL 数据库需要先执行表结构脚本，再执行核心初始化脚本： ```powershell mysql -u meos_user -p meos_tool < scripts/sql/schema.mysql.sql mysql -u meos_user -p meos_tool < scripts/sql/core-bootstrap.mysql.sql ``` 核心初始化脚本会写入默认组织上下文、平台资源、权限、角色和初始超级管理员账号： ```text username: admin password: 123456 ``` 首次登录后请立即修改默认密码。 既有开发、共享或生产数据库如果不是从最新 schema 重建，需要按当前代码和核心数据基线手工校验，并按需执行 `scripts/sql/migrations` 根目录下的正式幂等生产迁移。当前已发布迁移包括 `20260526-ai-assistant-menu-permissions.mysql.sql` 和 `20260604-online-release.mysql.sql`；未发布上线 SQL 草稿暂存在 `scripts/sql/migrations/_drafts/next-release.mysql.sql`。项目目前没有自动迁移执行器。 ## 开发 Windows 下建议使用项目提供的脚本启动或复用 Nuxt 开发服务器： ```powershell powershell -ExecutionPolicy Bypass -File scripts/start-nuxt-dev.ps1 -Port 3000 -Wait ``` 默认访问地址为 `http://127.0.0.1:3000`。 也可以使用通用 Nuxt 开发命令： ```powershell pnpm run dev ``` ## 主要路由 - `/login`：登录页。 - `/register`：邮箱验证码注册页。 - `/profile`：个人中心、密码修改和地址导航栏 Chrome 扩展 Token 管理。 - `/`：按权限过滤的工作台。 - `/announcements`：公告中心。 - `/quick-links`：地址导航栏。 - `/tools/json-processor`：JSON 格式化、压缩和校验。 - `/tools/cron-expression`：Cron 表达式解析和执行时间预览。 - `/tools/api-debugger`：API 调试工作台。 - `/ai-assistant`：AI 助手聊天页面。 - `/admin`：系统概览、组织用户、角色权限、资源、配置、审计、反馈和公告管理。 - `/admin/tool-config/api-debugger`：API 调试器全局配置。 - `/admin/tool-config/quick-links`：地址导航栏全局配置。 - `/admin/ai-assistant/provider`：AI 供应商配置。 - `/admin/ai-assistant/agents`：AI 智能体配置。 - `/admin/ai-assistant/skills`：内置和包化 Skill 配置。 - `/admin/ai-assistant/capabilities`：可控工具能力配置。 - `/admin/ai-assistant/risk`：AI 助手风险控制。 - `/admin/ai-assistant/audit`：AI 助手对话和运行审计。 `/admin/ai-assistant` 和 `/admin/ai` 会重定向到 `/admin/ai-assistant/provider`。 ## AI 助手配置 AI 助手在调用模型前需要先配置可用供应商。可以在 `/admin/ai-assistant/provider` 配置全局供应商，也可以在 AI 助手页面保存个人供应商设置。 支持的供应商协议： - `openai-compatible` - `anthropic` 供应商 API Key 会通过应用配置流程保存，保存后不会再明文返回给前端。 ## 常用脚本 ```powershell pnpm run dev # 启动 Nuxt 开发服务器 pnpm run build # 构建生产版本 pnpm run preview # 预览生产构建 pnpm run lint # 运行 ESLint pnpm run typecheck # 运行 Nuxt 类型检查 pnpm run test # 运行全部 Vitest 项目 pnpm run test:fast # 运行快速 Vitest 项目（单元 + 非数据库 Nuxt） pnpm run test:unit # 运行单元测试 pnpm run test:nuxt # 运行 Nuxt 运行时和组件测试 pnpm run test:nuxt:mysql # 运行 MySQL Nuxt 集成测试 pnpm run test:e2e # 运行 Playwright 端到端测试 pnpm run test:coverage # 运行带覆盖率的 Vitest pnpm run test:coverage:fast # 运行单元 + 非数据库 Nuxt 覆盖率 pnpm run build:extension:quick-link-autofill # 构建地址导航栏 Chrome 自动填充扩展下载包 pnpm run typecheck:extension:quick-link-autofill # 检查地址导航栏 Chrome 扩展类型 pnpm run db:generate # 根据 schema 生成 Drizzle 迁移 pnpm run db:studio # 打开 Drizzle Studio ``` 依赖 MySQL 的测试使用 `NUXT_TEST_DATABASE_URL`，不会回退使用 `NUXT_DATABASE_URL`。 Testing workflow notes: - `pnpm run test:fast` is the normal local feedback path. It runs `unit` plus non-database `nuxt`. - `pnpm run test:nuxt:mysql` is serial by design because all files share `NUXT_TEST_DATABASE_URL`. - Any Nuxt test that uses `createTestDatabase`, `describeWithTestDatabase`, `resetTestDatabase`, or `testAuthConfig` must be covered by `test/config/mysqlNuxtTestFiles.ts`; `test/unit/mysql-test-classification.test.ts` guards this. - `NUXT_TEST_DATABASE_URL` must point to a database whose name contains `test`. The unsafe override is only for isolated disposable databases. - `pnpm run test:e2e` runs named Playwright smoke flows under `tests/`; authenticated smokes reset `NUXT_TEST_DATABASE_URL`, use seeded credentials or `E2E_ADMIN_USERNAME` / `E2E_ADMIN_PASSWORD`, and inject test-only production-valid auth secrets through `playwright.config.ts`. - Playwright smoke tests run single-worker because authenticated smokes share the reset E2E test database. - Known Nuxt Suspense and AI SDK compatibility warning noise is filtered only in `test/setup/filterKnownWarnings.ts`; unrelated warnings should remain visible. ## 项目结构 ```text app/ components/ Vue UI 组件、管理页和工具面板组件 composables/ 客户端组合式函数 middleware/ 全局认证和路由权限中间件 pages/ 工作台、工具、管理、登录、AI 助手页面 stores/ Pinia 状态 tools/ 工具清单和工具页面组件 types/ 前端专用类型 utils/ 前端工具函数 server/ api/ Nitro API 端点 database/ Drizzle schema utils/ 服务端认证、配置、工具、AI、数据库和审计工具 shared/ types/ 前后端共享 API 和领域 DTO utils/ 共享校验、目录、配置和执行工具 scripts/ sql/ MySQL 表结构和初始化脚本 start-nuxt-dev.ps1 Windows 友好的 Nuxt 开发服务器启动脚本 extensions/ chrome-quick-link-autofill/ 地址导航栏 Chrome 自动填充扩展 test/ unit/ Node/Vitest 单元测试 nuxt/ Nuxt 运行时和组件测试 tests/ *.spec.ts Playwright 端到端测试 docs/prd/ 产品需求文档 ``` ## 生产部署注意事项 - 为 `.env` 中所有密钥设置高强度随机值，尤其是 `NUXT_JWT_SECRET`、`NUXT_REFRESH_TOKEN_SECRET`、`NUXT_EMAIL_VERIFICATION_SECRET`、`NUXT_SMTP_SECRET`、`NUXT_API_DEBUGGER_SNAPSHOT_SECRET`、`NUXT_API_DEBUGGER_AUTH_SECRET`、`NUXT_QUICK_LINK_SECRET` 和 `NUXT_AI_ASSISTANT_SECRET`。 - HTTPS 环境使用 `NUXT_REFRESH_COOKIE_SECURE=true`。 - 首次部署新数据库前，先执行 `scripts/sql/schema.mysql.sql`，再执行 `scripts/sql/core-bootstrap.mysql.sql`。 - 既有数据库升级时，按 `scripts/sql/migrations` 中的正式迁移和 `_drafts/next-release.mysql.sql` 的发布状态显式管理执行顺序和回滚。 - 在系统管理的配置数据页启用 SMTP 邮件配置，否则新用户无法收取注册验证码。 - 如果启用地址导航栏 Chrome 自动填充扩展下载，部署前运行 `pnpm run build:extension:quick-link-autofill`，并确认生成的下载包随 Nuxt 静态资源发布。 - 启用 AI 助手前，通过管理页面配置可用供应商。 - 对外开放系统前，检查默认管理员账号、角色和权限配置。 - 将 `.data/api-debugger-response-artifacts` 作为敏感运行数据处理，明确挂载、备份、清理、静态加密和容量治理策略。