Skip to content

UI重写,前后端架构调整 - #233

Open
megumiss wants to merge 138 commits into
masterfrom
page_refine
Open

UI重写,前后端架构调整#233
megumiss wants to merge 138 commits into
masterfrom
page_refine

Conversation

@megumiss

@megumiss megumiss commented Jul 27, 2026

Copy link
Copy Markdown
Owner

Summary by Sourcery

引入基于 SPA 的全新 NKAS Web UI,配套 REST/WebSocket 后端、集中化主题管理以及更新后的管理与更新流程,同时保持现有自动化与流程行为不变。

New Features:

  • 添加基于 Vue 的单页 Web UI,挂载于 /app/ 路径下,并提供面向实例、配置、队列、日志和系统状态的全新 REST 与 WebSocket API 支持。
  • 提供独立的 UI 预览和实现规划文档,用于指导新界面的开发与评审。
  • 在进程管理器中为每个订阅者引入独立日志队列,使多个 WebSocket 消费者可以并行拉取日志流,而不影响现有的 Rich 日志输出。

Bug Fixes:

  • 通过使用锁对更新进行串行化并重置缓存的渲染状态,避免在重新绘制侧边导航时出现竞态条件和过期缓存问题。

Enhancements:

  • 通过 CSS 变量统一明暗两种主题,引入新的核心样式表 nkas.css,并简化主题相关的差异化样式覆盖。
  • 重新设计更新器和实例管理视图,采用卡片式布局,提供更丰富的状态信息,并引入更安全的删除流程。
  • 重构启动提示和导入对话框,使其遵循新的对话框与布局风格,同时保持原有行为不变。
  • 优化 manage() 的初始化流程,将根路径重定向到 SPA 入口,并将 API 路由委托给专门模块处理,而不改变现有自动化 API。
Original summary in English

Summary by Sourcery

Introduce a new SPA-based NKAS web UI with a REST/WebSocket backend, centralized theming, and updated management and updater flows while preserving existing automation and process behavior.

New Features:

  • Add a Vue-based single-page web UI served under /app/, backed by new REST and WebSocket APIs for instances, configuration, queues, logs, and system status.
  • Provide a standalone UI preview and implementation plan for the new interface to guide development and review.
  • Introduce per-subscriber log queues in the process manager so multiple WebSocket consumers can stream logs without affecting existing Rich logging.

Bug Fixes:

  • Avoid races and stale cache issues when redrawing the aside navigation by serializing updates with a lock and resetting cached rendered state.

Enhancements:

  • Unify light and dark themes via CSS variables with a new nkas.css core stylesheet and simplified theme-specific overrides.
  • Redesign the updater and instance management views to use card-based layouts, richer status information, and safer delete flows.
  • Rework the startup notice and import dialogs to follow the new dialog and layout style while keeping behavior consistent.
  • Refine the manage() setup to redirect the root path to the SPA entry and delegate API routing to a dedicated module without changing existing automation APIs.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @megumiss, your pull request is larger than the review limit of 150000 diff characters

@sourcery-ai

sourcery-ai Bot commented Jul 27, 2026

Copy link
Copy Markdown

Reviewer's Guide

引入了一个基于 SPA 的全新 NKAS Web 界面,支持可主题化 CSS;在后端增加了 REST/WebSocket API;更新了 manage/import 流程;重构样式以使用 CSS 变量,同时保留对旧版 Electron 的兼容性,并改进日志记录与性能。

通过 WebSocket 进行实时日志流的时序图

sequenceDiagram
    participant Browser as Browser SPA
    participant WS as ws.log_socket
    participant Broker as LogBroker
    participant PM as ProcessManager

    Browser->>WS: WebSocket connect /ws/{name}/log
    WS->>Broker: replay(name)
    Broker-->>WS: existing ConsoleRenderable[]
    WS-->>Browser: {type: log, html}

    WS->>Broker: subscribe(name)
    Broker-->>WS: subscriberQueue

    loop for each new log line
        PM->>PM: _thread_log_queue_handler()
        PM->>PM: renderables.append(log)
        PM->>PM: _publish_log(log)
        PM-->>Broker: log (via subscriber queues)
        Broker-->>WS: log from subscriberQueue
        WS-->>Browser: {type: log, html}
    end

    Browser--xWS: WebSocket close
    WS->>Broker: unsubscribe(name, subscriberQueue)
Loading

File-Level Changes

Change Details Files
将 NKAS CSS 重构为基于变量、可主题化的设计,并现代化所有 UI 组件样式。
  • nkas.css 中定义全局 --nkas-* CSS 变量以及基础排版、按钮、表单、布局和滚动条样式。
  • light-nkas.cssdark-nkas.css 转换为只做变量赋值的文件,而非组件特定规则。
  • 为侧边栏/菜单按钮、开关、导航按钮、卡片、日志、概览卡片、表格、警告、模态框以及 manage/updater/import 蒙层添加符合新 UI 规范的详细样式。
  • 确保 CSS 仅使用 ASCII 字符,并通过 URL 编码的 data URI 内嵌 SVG 图标,以兼容 JS 注入。
assets/gui/css/nkas.css
assets/gui/css/light-nkas.css
assets/gui/css/dark-nkas.css
添加 REST 和 WebSocket API 层,以服务新的 SPA,并暴露 instance/config/queue/system 等端点。
  • 引入 module.webui.api 包,包含路由挂载、模型、共享依赖、配置/任务服务以及 WebSocket 处理器。
  • 挂载 /app 静态 SPA(webui/dist),并在 /api 下接入用于实例、配置 schema/patch、队列、统计、系统状态/更新/远程、监控、主题/语言以及工具/任务执行的 API 路由。
  • 新增 WebSocket 端点,用于全局实例状态、按实例划分的日志流以及队列更新,并支持增量广播。
  • 将根路由 / 重定向到 SPA 入口 /app/,并在 manage() 中调用 mount_api(app) 以激活新路由。
module/webui/api/__init__.py
module/webui/api/app.py
module/webui/api/models.py
module/webui/api/deps.py
module/webui/api/service_config.py
module/webui/api/service_tasks.py
module/webui/api/routes_instances.py
module/webui/api/routes_config.py
module/webui/api/routes_tasks.py
module/webui/api/routes_stats.py
module/webui/api/routes_system.py
module/webui/api/ws.py
module/webui/app.py
扩展 ProcessManager,加入日志订阅机制以支持非阻塞的 WebSocket 日志流。
  • ProcessManager 中为日志订阅者新增按订阅者分隔的有界队列和锁。
  • 在日志处理线程中将新的 ConsoleRenderable 条目推入订阅者队列,当队列满时进行裁剪以避免阻塞。
  • 暴露 subscribe_log/unsubscribe_log 方法供 WebSocket 日志 broker 使用。
module/webui/process_manager.py
重做侧边栏菜单渲染,使其线程安全并能正确刷新实例按钮。
  • NKASGUI 中添加一个 RLock_aside_lock),用于在定时任务与按钮回调之间串行化侧边栏重绘。
  • 在锁内包装 set_asideset_aside_status,并将状态重绘拆分到辅助方法 _redraw_aside_status 中。
  • 在重建实例作用域时清空 rendered_cache,以便状态被完全重新计算。
  • 将侧边栏中的 manage 按钮改为调用新的 ui_manage 方法,而不是 go_app('manage')
module/webui/app.py
将 updater 和 manage 流程重新设计为现代的卡片式布局,提升 UX 并增加确认流程。
  • 用自定义 HTML 卡片替换 updater 表格渲染,用于展示本地/上游版本和历史行;将作用域重构为 updater_page/updater_status/updater_info/updater_detail
  • 更新 dev_update() 的 HTML/CSS 以匹配新的 updater 设计,并使用新的 system/update API。
  • 重构 ui_add_nkas() 按钮,使其使用专门的 actions 作用域,并采用更语义化的按钮颜色。
  • 实现 ui_manage(),在弹窗中展示实例管理,包括导出/删除(带确认步骤)以及通过 input_group 进行导入,并复用 ProcessManager 和配置相关的辅助工具。
  • 使用 nkas/light-nkas/dark-nkas CSS 重新构建 manage() 应用入口页面,引入新的 manage_page 布局、彩色按钮,以及行内导出/删除控制并带有确认状态。
module/webui/app.py
统一启动提示模态框和导入对话框的内容/布局,使其符合新设计并复用现有 CSS。
  • 简化启动提示弹窗,使其使用共享的 startup-notice-body/icon/message/footer CSS,而不是注入特定主题的内联样式;保持通过本地存储实现的一次性隐藏逻辑。
  • 调整 widgets.py 中的导入路径弹窗,使用更具描述性的 HTML 段落,并设置专用的 actions 作用域和主/次按钮。
module/webui/app.py
module/webui/widgets.py
为贡献者撰写新的 GUI 架构与主题约束文档。
  • AGENTS.md 中添加指南,说明 CSS 变量系统、CSS 必须为 ASCII 的要求,以及如何通过 add_css() 为新页面添加 CSS。
AGENTS.md
提升启动提示 ID,以强制用户显示一次新的消息。
  • startup_notice.yaml 中的 id 更新为 notice_20260718,以便客户端看到更新后的提示。
config/startup_notice.yaml
webui/ 中引入一个使用 Vite 构建的 Vue 3 SPA,并在 webui/dist 中提供静态构建作为主 UI,包括完整的 NKAS 仪表盘、实例/任务配置以及设置/更新视图。
  • 新增 webui/ Vite 项目(package.jsonvite.config.tstsconfigsrc/main.ts),使用 Vue 3、vue-routerpinia,以及自定义 App.vue,实现与预览一致的侧边栏、任务栏、仪表盘、总览、任务/工具、manage、settings 和 about 视图。
  • 实现 REST 客户端(api/client.ts)和 JsonSocket 封装(api/ws.ts),用于与新后端 API 的 HTTP 和 WebSocket 通信。
  • 创建配置字段组件(FieldItemTableFieldStorageFieldPathPickerFieldInterception)以及基础 CSS(base.css),以反映 nkas.css 的设计 token 和卡片/按钮几何样式。
  • 将构建后的静态资源签入 webui/distindex.html、打包后的 JS/CSS/vendor 代码块),以便后端在无需单独构建步骤的情况下提供 /app/
  • 将路由器配置为使用 hash history,并将所有 UI 路径指向 App.vue,让后端仅需提供 /app/ 的静态外壳。
webui/package.json
webui/vite.config.ts
webui/tsconfig.json
webui/index.html
webui/src/main.ts
webui/src/App.vue
webui/src/api/client.ts
webui/src/api/ws.ts
webui/src/components/config/FieldItemTable.vue
webui/src/components/config/FieldStorage.vue
webui/src/components/config/FieldPathPicker.vue
webui/src/styles/base.css
webui/dist/index.html
webui/dist/assets/index-909b3c1e.js
webui/dist/assets/index-35955d22.css
webui/dist/assets/vue-1b072c71.js
添加 UI 预览工具和脚本,用于捕获静态截图并记录迁移计划。
  • 新增 dev_tools/ui_preview/preview.htmlPLAN.md,描述 NKAS UI 重构、REST/SPA 架构以及分阶段计划。
  • 添加基于 Playwright 的脚本,用于拍摄预览截图,并检查当前 K2 导入蒙层行为,以保证布局一致性。
dev_tools/ui_preview/preview.html
dev_tools/ui_preview/PLAN.md
dev_tools/ui_preview/shoot.js
dev_tools/ui_preview/README.md
webapp/scripts/k2_import_overlay.js

Tips and commands

Interacting with Sourcery

  • 触发新的审查: 在 pull request 上评论 @sourcery-ai review
  • 继续讨论: 直接回复 Sourcery 的审查评论。
  • 从审查评论生成 GitHub issue: 在某条审查评论下回复,请 Sourcery 基于该评论创建 issue。你也可以直接回复 @sourcery-ai issue,从该评论生成 issue。
  • 生成 pull request 标题: 在 pull request 标题中任意位置写上 @sourcery-ai,即可随时生成标题。你也可以在 pull request 中评论 @sourcery-ai title 来(重新)生成标题。
  • 生成 pull request 概要: 在 pull request 正文任意位置写上 @sourcery-ai summary,即可在指定位置生成 PR 概要。你也可以评论 @sourcery-ai summary 在任何时间(重新)生成概要。
  • 生成 reviewer's guide: 在 pull request 中评论 @sourcery-ai guide,即可在任何时间(重新)生成 reviewer's guide。
  • 一次性解决所有 Sourcery 评论: 在 pull request 中评论 @sourcery-ai resolve,将所有 Sourcery 评论标记为已解决。如果你已经处理了所有评论且不想再看到它们,这会很有用。
  • 全部撤销 Sourcery 审查: 在 pull request 中评论 @sourcery-ai dismiss,撤销所有现有的 Sourcery 审查。尤其适用于你希望从头开始新的审查——别忘了随后评论 @sourcery-ai review 来触发新一轮审查!

Customizing Your Experience

打开你的 dashboard 以:

  • 启用或禁用诸如 Sourcery 生成的 pull request 概要、reviewer's guide 等审查功能。
  • 更改审查语言。
  • 添加、删除或编辑自定义审查说明。
  • 调整其他审查设置。

Getting Help

Original review guide in English

Reviewer's Guide

Introduces a new SPA-based NKAS web UI with themeable CSS, adds REST/WebSocket APIs on the backend, updates manage/import flows, and refactors styles to use CSS variables while preserving legacy Electron compatibility and improving logging/performance.

Sequence diagram for live log streaming over WebSocket

sequenceDiagram
    participant Browser as Browser SPA
    participant WS as ws.log_socket
    participant Broker as LogBroker
    participant PM as ProcessManager

    Browser->>WS: WebSocket connect /ws/{name}/log
    WS->>Broker: replay(name)
    Broker-->>WS: existing ConsoleRenderable[]
    WS-->>Browser: {type: log, html}

    WS->>Broker: subscribe(name)
    Broker-->>WS: subscriberQueue

    loop for each new log line
        PM->>PM: _thread_log_queue_handler()
        PM->>PM: renderables.append(log)
        PM->>PM: _publish_log(log)
        PM-->>Broker: log (via subscriber queues)
        Broker-->>WS: log from subscriberQueue
        WS-->>Browser: {type: log, html}
    end

    Browser--xWS: WebSocket close
    WS->>Broker: unsubscribe(name, subscriberQueue)
Loading

File-Level Changes

Change Details Files
Refactor NKAS CSS into variable-driven, themeable design and modernize all UI components’ styling.
  • Define global --nkas-* CSS variables and base typography, buttons, forms, layout, and scrollbar styles in nkas.css.
  • Convert light-nkas.css and dark-nkas.css into variable-assignment files instead of component-specific rules.
  • Add detailed styling for aside/menu buttons, toggles, navigator buttons, cards, logs, overview tiles, tables, alerts, modals, and manage/updater/import overlays matching the new UI spec.
  • Ensure CSS is ASCII-safe and embed SVG icons via URL-encoded data URIs for compatibility with JS injection.
assets/gui/css/nkas.css
assets/gui/css/light-nkas.css
assets/gui/css/dark-nkas.css
Add REST and WebSocket API layer to serve a new SPA and expose instance/config/queue/system endpoints.
  • Introduce module.webui.api package with route mounting, models, shared deps, config/task services, and WebSocket handlers.
  • Mount /app static SPA (webui/dist) and wire API routes under /api for instances, config schema/patch, queue, stats, system status/update/remote, monitors, theme/language, and tool/task execution.
  • Add WebSocket endpoints for global instance state, per-instance log streaming, and queue updates with incremental broadcasting.
  • Redirect the root route '/' to the SPA entry /app/ and call mount_api(app) from manage() so new routes are active.
module/webui/api/__init__.py
module/webui/api/app.py
module/webui/api/models.py
module/webui/api/deps.py
module/webui/api/service_config.py
module/webui/api/service_tasks.py
module/webui/api/routes_instances.py
module/webui/api/routes_config.py
module/webui/api/routes_tasks.py
module/webui/api/routes_stats.py
module/webui/api/routes_system.py
module/webui/api/ws.py
module/webui/app.py
Extend ProcessManager with log subscription to support non-blocking WebSocket log streaming.
  • Add per-subscriber bounded queues and a lock to ProcessManager for log subscribers.
  • Push new ConsoleRenderable entries into subscriber queues inside the log handler thread, trimming when full to avoid blocking.
  • Expose subscribe_log/unsubscribe_log methods used by WebSocket log broker.
module/webui/process_manager.py
Rework aside menu rendering to be thread-safe and correctly refresh instance buttons.
  • Add an RLock (_aside_lock) to NKASGUI to serialize aside redraws between periodic tasks and button callbacks.
  • Wrap set_aside and set_aside_status in the lock and split status redraw into a helper _redraw_aside_status.
  • Clear rendered_cache when rebuilding instance scopes so status is fully recomputed.
  • Change the manage button in the aside to call a new ui_manage method instead of go_app('manage').
module/webui/app.py
Redesign updater and manage flows into modern card-based layouts with better UX and confirm flows.
  • Replace updater table rendering with custom HTML cards for local/upstream versions and history rows; restructure scopes to updater_page/updater_status/updater_info/updater_detail.
  • Update dev_update() HTML/CSS to match new updater design and use the new system/update APIs.
  • Refactor ui_add_nkas() buttons to use a dedicated actions scope and more semantic button colors.
  • Implement ui_manage() to show instance management in a popup with export/delete (with confirm step) and import via input_group, reusing ProcessManager and config helpers.
  • Rebuild the manage() app entry page using nkas/light-nkas/dark-nkas CSS, new manage_page layout, colored buttons, and in-row export/delete controls with confirmation state.
module/webui/app.py
Unify startup notice modal and import dialog content/layout with the new design and reuse existing CSS.
  • Simplify startup notice popup to use shared startup-notice-body/icon/message/footer CSS instead of injecting theme-specific inline styles; keep one-shot suppression via local storage.
  • Adjust import path popup in widgets.py to use a descriptive HTML paragraph and a dedicated actions scope with primary/secondary buttons.
module/webui/app.py
module/webui/widgets.py
Document new GUI architecture and theme constraints for contributors.
  • Add guidelines in AGENTS.md describing the CSS variable system, ASCII-only CSS requirement, and how to add CSS for new pages via add_css().
AGENTS.md
Bump startup notice id to force showing the new message once.
  • Update startup_notice.yaml id to notice_20260718 so clients see the revised notice.
config/startup_notice.yaml
Introduce a new Vite-built Vue 3 SPA in webui/ and static build in webui/dist as the primary UI, including a full NKAS dashboard, instance/task configuration, and settings/update views.
  • Add webui/ Vite project (package.json, vite.config.ts, tsconfig, src/main.ts) using Vue 3, vue-router, pinia, and a custom App.vue that implements sidebar, task rail, dashboard, overview, task/tool, manage, settings, and about views matching the preview.
  • Implement REST client (api/client.ts) and JsonSocket wrapper (api/ws.ts) for HTTP and WebSocket communication with the new backend APIs.
  • Create configuration field components (FieldItemTable, FieldStorage, FieldPathPicker, FieldInterception) and base CSS (base.css) that mirror the nkas.css design tokens and card/button geometry.
  • Check in built assets under webui/dist (index.html, bundled JS/CSS/vendor chunks) so the backend can serve /app/ without a separate build step.
  • Wire router to use hash history with routes pointing all UI paths to App.vue, leaving backend to serve only /app/ static shell.
webui/package.json
webui/vite.config.ts
webui/tsconfig.json
webui/index.html
webui/src/main.ts
webui/src/App.vue
webui/src/api/client.ts
webui/src/api/ws.ts
webui/src/components/config/FieldItemTable.vue
webui/src/components/config/FieldStorage.vue
webui/src/components/config/FieldPathPicker.vue
webui/src/styles/base.css
webui/dist/index.html
webui/dist/assets/index-909b3c1e.js
webui/dist/assets/index-35955d22.css
webui/dist/assets/vue-1b072c71.js
Add UI preview tooling and scripts to capture static screenshots and document the migration plan.
  • Add dev_tools/ui_preview/preview.html and PLAN.md describing the NKAS UI refactor, REST/SPA architecture, and phase plan.
  • Add Playwright-based scripts to shoot preview screenshots and to inspect current K2 import overlay behavior for layout parity.
dev_tools/ui_preview/preview.html
dev_tools/ui_preview/PLAN.md
dev_tools/ui_preview/shoot.js
dev_tools/ui_preview/README.md
webapp/scripts/k2_import_overlay.js

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

megumiss added 30 commits August 1, 2026 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant