Yuxi Web 前端开发约定实践指南Vue 3 / Vite 多租户知识智能体平台的前端工程规范【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/YuxiYuxi 是一个基于 LangGraph、FastAPI、Vue 3 与多种持久化服务构建的可私有部署多租户知识智能体平台本文以其 web/AGENTS.md 为核心骨架系统讲解该前端子树的工程约定API 调用如何统一收敛、权限边界如何划分、UI 状态语义如何保持一致、Lint/测试/构建在提交前如何验证。读者读完可以掌握 Yuxi 前端代码库的实际组织方式、每条约定的源码级依据以及一套可直接复用的提交前验证流程。一、文档定位与前置阅读子约定如何与根文档协作web/AGENTS.md 是仓库根目录 AGENTS.md 在前端子树上的补充约定。根文档明确指出修改backend/、web/或docs/时同时遵循该子树的AGENTS.md子树规则只补充本目录不复制回根文件。因此阅读本约定前应先加载三份更高层的资料AGENTS.md稳定边界、主链路、架构不变量与工程信任系统docs/develop-guides/design.md设计规范ARCHITECTURE.md架构总览。从文件实际内容看web/AGENTS.md 只写了 21 行但它每一条都是对前端代码库可验证的工程契约——它没有停留在风格建议层面而是把 API 收敛、权限边界、状态语义、Lint 纪律和提交前 gate 全部落实到具体命令与代码位置这正是本文要展开的核心。二、API 调用统一收敛组件不得直接拼接 HTTP 请求约定第一条API 调用统一放在src/apis组件不直接拼接普通 HTTP 请求。这是一条架构级约束而不是简单的代码组织偏好。其目的可从 web/src/apis/base.js 的实现中看出统一认证头注入apiRequest在requiresAuth为真时从useUserStore()读取getAuthHeaders()注入请求头若用户未登录直接抛出用户未登录。统一错误映射publicErrorMessage将 HTTP 状态码翻译为面向用户的公共文案覆盖 400/401/403/404/409/410/413/422/423/429/5xx 等场景例如 423 会读取x-lock-remaining响应头显示账户已锁定 N 秒5xx 会提示使用docker compose logs api查看详细日志。统一响应处理支持json、text、blob三种 responseType并依据响应Content-Type判断是否 JSON 解析。日志脱敏safeRequestMetadata只记录 URL 的pathname与方法/状态码注释明确不把无法解析的原始 URL 写入日志其中可能包含凭据或其他敏感查询参数422 校验失败日志同样禁止写入浏览器日志密码、令牌等隐私数据。401 自动登出认证失败时提示登录已过期自动调用userStore.logout()并在 1.5 秒后跳转/login。基础封装之上web/src/apis 目录按领域拆分了 22 个模块agent_api.js、knowledge_api.js、mcp_api.js、skill_api.js、project_api.js、workspace_api.js等并提供了apiAdminGet/Post/Put/Delete与apiSuperAdmin*系列包装。组件层只依赖这些领域 API 模块既保证了组件不直接拼接普通 HTTP 请求也让所有请求天然享受认证、错误映射与日志安全能力。三、权限边界前端守卫只是体验约束后端才是授权终点约定第二条前端权限与路由守卫只提供体验约束后端始终执行最终授权。这条原则在代码中有两处直接体现路由侧web/src/router/index.js 的全局前置守卫router.beforeEach根据meta.requiresAuth / requiresAdmin / requiresSuperAdmin决定是否拦截未登录保存redirect后跳登录页管理员不足时尝试初始化 agent store 并跳回/agent。它只控制能打开哪个页面不产出任何业务授权结论。API 侧web/src/apis/base.js 中的apiAdminGet等函数调用checkAdminPermission()/checkSuperAdminPermission()做前置检查这同样是尽早失败、改善体验的预检而不是授权依据。根文档 AGENTS.md 把这条边界写成了不能破坏的系统事实权限在后端依赖与 repository 可见性查询处最终执行前端守卫、prompt、schema omission 和 UI 隐藏不是授权边界。因此前端开发者可以放心地只做体验约束而绝不能在组件里用v-if隐藏入口来代替后端校验。四、设计系统与依赖纪律复用 base.css 变量与 lucide/vue约定第三条复用src/assets/css/base.css变量和lucide/vue不为一次性视觉需求引入新依赖。这背后是两套可持续复用的工程资产设计令牌web/src/assets/css/base.css 定义了完整的 CSS 变量体系包括主色--main-*十档色阶--main-1000到--main-0、辅助金色系--second-*、灰阶--gray-*以及标准五档--color-primary-* / --color-secondary-*别名。浅/深色适配由 web/src/assets/css/base.dark.css 配合themestore 实现。新页面应直接引用这些变量而不是写死十六进制色值。图标库lucide/vue已在 web/package.json 的 dependencies 中锁定图标需求优先从它取用。依赖纪律的约束对象是package.json当前前端依赖保持精简Vue 3、Vite 8、Pinia、Ant Design Vue、markdown-it、pdfjs-dist、shiki、echarts、antv/g6 等任何为一次性视觉需求新增的依赖都会破坏这个平衡因此被明确禁止。这与根文档只修改验收标准需要的范围不顺手重构、格式化或添加想象中的配置的原则一脉相承。五、UI 状态语义loading / empty / error / 断线恢复 / 终态投影约定第四条是整套约定中信息密度最高的一条保持 loading、empty、error、断线恢复和终态投影语义一致不要用乐观 UI 覆盖 PostgreSQL 返回的最终事实。理解这句话需要结合根文档的系统事实。Yuxi 的普通请求链路是请求先在 PostgreSQL 中持久化 Message 和 AgentRunRequest只有 ready FIFO 队头创建 AgentRun且每次投递 ARQ 前 owning transaction 都已提交同一用户、Agent、线程的普通请求按 FIFO 串行派发。也就是说数据库是最终事实终态的唯一权威来源前端展示的任何中间状态都只是投影。由此推导出三条前端纪律loading/empty/error 是并列的一等状态任何数据渲染组件都必须显式处理三态不能只写成功分支断线恢复语义一致SSE 流中断、轮询失败后的恢复路径要与初始加载路径一致相关实现可参考 web/src/composables/useAgentRunStream.js、web/src/composables/runStreamResume.js 与 web/src/utils/runStreamResume.js 对应的前端工具链禁止乐观 UI 覆盖最终事实在请求尚未得到数据库确认前不得把界面假装成已成功的终态——这正是base.js中不以 HTTP 200 或日志关键词为最终事实这一证据规则的 UI 侧镜像。根文档 AGENTS.md 明确Agent 的完成报告、HTTP 200、日志关键词或 mock 调用次数都不是最终事实重新读取数据库、文件、对象、DOM 或协议结果前端展示同样要等待真实终态。六、Lint 纪律只读 gate 与自动修复的严格区分约定第五条pnpm run lint:check是只读 gatepnpm run lint才允许本地自动修复。这是防止gate 本身会改代码这一反模式的工程实践。从 web/package.json 的 scripts 可以看到两者的真实差异lint: eslint . --fix --cache, lint:check: eslint . --max-warnings0, format: prettier --write --experimental-cli src/lint:check只做检查且要求0 个 warning--max-warnings0适合作为 CI 和提交前 gatelint允许--fix自动修复并带--cache增量缓存仅限本地开发时使用。规则栈由 web/eslint.config.js 定义js.configs.recommendedpluginVue.configs[flat/essential]skipFormattingPrettier 冲突跳过全局忽略**/dist/**、**/dist-ssr/**、**/coverage/**环境为globals.browser。也就是说一个 PR 只有同时通过 ESLint0 warning与 Prettier 格式化才算干净。七、提交前验证lint、单元测试与构建三连文档给出了提交前必须执行的三条命令docker compose exec web pnpm run lint:check docker compose exec web pnpm run test:unit docker compose exec web pnpm run build这些命令都运行在容器内的 web 服务里而非宿主机——web 服务在 docker-compose.yml 中以target: development构建挂载了./web/src、./web/test、./web/public、./web/index.html、./web/vite.config.js命令为pnpm run server即vite serve --host端口 5173并注入VITE_API_URLhttp://api:5050。具体到三条 gatelint:checkESLint 只读检查0 warning 门槛见上文test:unitnode --test --test-concurrency1 test/**/*.test.js test/**/*.spec.js使用 Node 内置测试运行器、串行执行覆盖 web/test/unit 下 90 余个测试文件agentRun.test.js、messageProcessor.test.js、toolApproval.test.js、runStreamResume.test.js等主要断言纯前端逻辑与组件行为buildvite build生产构建。构建期行为由 web/vite.config.js 定义别名指向./src开发服务器将^/api代理到http://api:5050、将^/minio/public/代理到http://minio:9000此外还有两个关键自定义插件——model-display-metadata构建时从opencode-ai/models/snapshot提取模型展示元数据注入虚拟模块浏览器只接收展示字段与yuxi-pdfjs-cmapspdf.js 的 CMap 资源随应用本地发布开发态由中间件读取依赖目录、构建态复制进静态产物PDF 预览不依赖外部 CDN。build 通过意味着这些资源都能正确打包。值得注意这三条只是前端子树的 gate根文档要求提交前在仓库根目录至少运行python3 scripts/verify_engineering_contracts.py、python3 -m unittest scripts.test_verify_engineering_contracts以及docker compose exec api uv run --group test pytest test/unit -m not slow。前端开发者应理解自己的改动面需要哪一级证据可参考根文档 AGENTS.md 中的改动面 × 最低证据表纯 JS 逻辑用 unit 断言业务结果触及数据库/缓存/文件副作用补 integration跨 worker/队列/SSE 补 E2E前端交互则在 lint unit 之上按需补 build 与真实页面验证。八、UI 改动验收真实页面验证与状态覆盖最后一条约定UI 改动必须在真实页面验证并提供最终截图或录屏适用时覆盖浅/深色、响应式、loading、empty 和 error 状态。这条验收标准与前文的状态语义约定互相咬合既然 loading/empty/error 是一等状态改动任何涉及数据渲染的 UI 时就必须逐一验证这几种状态在真实页面上的表现而不是只验证数据正常返回这一条快乐路径。浅/深色验证依赖 web/src/assets/css/base.dark.css 与themestoreweb/src/stores/theme.js响应式验证则覆盖不同视口宽度。截图或录屏是已在真实页面验证的证据载体与根文档实际执行命令、结果和未执行原因写入 PR未验证不能写成通过的证据规则一致。九、小结一份可执行的、可审计的前端契约web/AGENTS.md 虽然篇幅极短但它把 Yuxi 前端的工程底线压缩成了五条可执行契约API 收敛到 web/src/apis由 web/src/apis/base.js 提供认证、错误映射与日志安全、权限只在体验层做约束后端经 AGENTS.md 的授权边界兜底、设计资产复用 web/src/assets/css/base.css 变量与lucide/vue、UI 状态语义与终态投影保持一致不得用乐观 UI 覆盖 PostgreSQL 事实、Lint 区分只读 gate 与本地修复web/package.json 的lint:check/lint、提交前三连验证lint:check / test:unit / build并附真实页面截图或录屏。每条约定都能在仓库的源码、配置或测试中找到对应实现既指导新开发者的日常提交也支撑仓库自动化的质量 gate是一份真正可执行、可审计的前端工程规范。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考