Skip to content

web-ui-guide.md

Latest commit

 

History

History
executable file
·
570 lines (416 loc) · 12.2 KB

web-ui-guide.md

File metadata and controls

executable file
·
570 lines (416 loc) · 12.2 KB
Raw

Web UI 指南

版本：v0.2.0-alpha

English | Deutsch | 中文 | 繁體中文 | Español | 日本語 | 한국어 | Čeština | Русский

概述

Web UI 提供了一個全面的介面，用於管理矽基生命體、監控系統狀態和與 AI 智能體互動。系統採用純服務端渲染架構，零前端框架依賴，透過 H、CssBuilder 和 JsBuilder 建構器生成 HTML、CSS 和 JavaScript。

存取

預設 URL：http://localhost:8080

導航

主要部分

  1. 儀表板 - 系統概覽和指標
  2. 生命體 - 管理矽基生命體
  3. 聊天 - 與生命體互動（支援檔案上傳、即時 SSE）
  4. 聊天歷史 - 檢視矽基生命體的聊天歷史記錄（會話清單、訊息詳情）
  5. 任務 - 任務管理（個人任務）
  6. 定時器 - 定時器設定（建立、暫停、執行歷史）
  7. 設定 - 系統設定（AI 用戶端、在地化）
  8. 權限 - 存取控制（ACL 管理、權限查詢）
  9. 日誌 - 系統日誌（按等級過濾、時間範圍查詢）
  10. 審計 - Token 使用和審計追蹤
  11. 記憶 - 生命體記憶（時間線檢視、進階過濾）
  12. 知識 - 知識庫（三元組管理、路徑發現）
  13. 程式碼瀏覽器 - 程式碼探索（檔案樹、語法高亮）
  14. 程式碼編輯器 - 帶懸浮提示的程式碼編輯（Monaco Editor）
  15. 專案 - 專案管理（工作區、任務、工作筆記）
  16. 執行器 - 執行器管理（磁碟、網路、命令列）
  17. 幫助 - 幫助文件系統（多語言支援、主題搜尋）
  18. 關於 - 系統資訊和版本

儀表板

功能

  • 系統效能指標（CPU、記憶體、運行時間）
  • 生命體狀態概覽
  • AI 使用統計
  • 快速操作

即時更新

使用 SSE（伺服器傳送事件）取得即時資料：

const dashboard = new EventSource('/api/dashboard/events');
dashboard.onmessage = (event) => {
    const data = JSON.parse(event.data);
    updateMetrics(data);
};

生命體管理

生命體清單

顯示所有生命體，包含：

  • 名稱和 ID
  • 目前狀態（運行中/已停止/錯誤）
  • 靈魂檔案連結
  • 快速操作（啟動/停止/設定）

生命體詳情

  • 完整設定
  • 靈魂檔案編輯器
  • 任務歷史
  • 記憶檢視器
  • 效能指標

建立生命體

  1. 點擊建立新生命體
  2. 填寫：
    • 名稱
    • 靈魂內容（Markdown 編輯器）
    • 初始設定
  3. 點擊建立

聊天介面

功能

  • 即時訊息流
  • 訊息歷史
  • 多會話支援
  • 工具呼叫視覺化

使用聊天

  1. 選擇生命體
  2. 輸入訊息
  3. 檢視串流回應
  4. 即時檢視工具執行

工具呼叫顯示

當 AI 呼叫工具時：

🔧 工具：calendar
📥 輸入：{"date": "2026-04-20"}
📤 輸出："農曆四月初三"

設定

AI 用戶端

設定 AI 後端：

  • Ollama（本地）
  • 百煉（雲端）
  • 火山引擎 Ark（雲端）
  • 牧馬人推理引擎（本地/雲端，無需認證）
  • 美團 LongCat（雲端）
  • 七牛雲 AI（雲端）
  • 自訂用戶端

儲存設定

  • Default 版本：基礎路徑、時間索引、清理策略
  • Fast 版本：SpeedyPack 儲存引擎設定、.spk 檔案管理、自動壓縮設定

在地化

在 34 種語言變體之間切換：

  • 中文（6 種）：簡體中文、繁體中文、新加坡中文、澳門中文、台灣中文、馬來西亞中文
  • 英文（10 種）：美式、英式、加拿大、澳洲、印度、新加坡、南非、愛爾蘭、紐西蘭、馬來西亞英語
  • 西班牙語（2 種）：西班牙、墨西哥
  • 德語（5 種）：德國、奧地利、瑞士、盧森堡、列支敦斯登
  • 法語（3 種）：法國、加拿大、瑞士
  • 日語、韓語、捷克語
  • 俄語、葡萄牙語（2 種）、義大利語、荷蘭語、波蘭語、瑞典語

皮膚系統

可用皮膚

  1. Admin - 專業管理介面
  2. Chat - 以對話為中心的設計
  3. Creative - 創意和藝術風格
  4. Dev - 面向開發者的佈局
  5. HighContrast - 高對比度主題（Fast 版本）
  6. Minimal - 極簡風格（Fast 版本）
  7. Light - 明亮主題（Fast 版本）

切換皮膚

  1. 點擊設定（齒輪圖示）
  2. 選擇皮膚
  3. 選擇所需皮膚
  4. 介面立即更新

自訂皮膚

透過實作 ISkin 建立自訂皮膚：

public class MySkin : ISkin
{
    public string Name => "MySkin";
    
    public string GetCss()
    {
        return ":root { --primary: #color; }";
    }
}

權限管理

檢視權限

  • 列出所有權限規則
  • 按使用者或資源過濾
  • 檢視過期日期

新增權限規則

  1. 點擊新增規則
  2. 設定：
    • 權限類型（如 FileAccess, NetworkAccess）
    • 資源前綴（如 C:\Projects, api.github.com）
    • 允許/拒絕
    • 描述
  3. 儲存

審計追蹤

檢視所有權限決策：

  • 時間戳
  • 使用者
  • 資源
  • 決策
  • 原因

工具權限管理

管理矽基生命體和專案的工具操作權限：

  1. 矽基生命體工具權限：

    • 導航到生命體 → 選擇生命體 → 工具權限
    • 檢視目前權限設定
    • 逐操作設定允許/拒絕
    • 套用權限範本（readonly/restricted/full）

  2. 專案工具權限：

    • 導航到專案 → 選擇專案 → 工具權限
    • 專案級別的工具權限獨立於矽基生命體級別
    • 實作專案間的權限隔離

任務管理

任務清單

  • 所有任務及其狀態
  • 按生命體或狀態過濾
  • 優先級指示器

任務詳情

  • 描述
  • 優先級
  • 截止日期
  • 執行歷史
  • 結果輸出

建立任務

  1. 點擊建立任務
  2. 填寫：
    • 生命體分配
    • 描述
    • 優先級（1-10）
    • 截止日期
  3. 建立

定時器管理

活動定時器

  • 運行中的定時器清單
  • 下次執行時間
  • 重複狀態

建立定時器

  1. 點擊建立定時器
  2. 設定：
    • 生命體分配
    • 間隔或 cron 表示式
    • 要執行的操作
    • 重複設定
  3. 啟動

日誌檢視器

功能

  • 按等級過濾（資訊/警告/錯誤）
  • 按關鍵詞搜尋
  • 時間範圍選擇
  • 即時更新

日誌詳情

每個日誌條目顯示：

  • 時間戳
  • 等級
  • 來源
  • 訊息
  • 堆疊追蹤（用於錯誤）

審計報告

Token 使用

  • 使用的總 token
  • 按模型細分
  • 成本計算
  • 基於時間的圖表

匯出報告

下載審計資料：

  • CSV 格式
  • 日期範圍選擇
  • 按生命體或模型過濾

程式碼編輯器

功能

  • 語法高亮（Monaco Editor）
  • 程式碼補全
  • 識別符的懸浮提示
  • 即時編譯

懸浮提示

將滑鼠懸停在任何識別符上以檢視：

  • 類型資訊
  • 文件
  • 定義位置
  • 引用

聊天歷史檢視

功能

  • 矽基生命體聊天歷史瀏覽
  • 會話清單展示
  • 訊息詳情檢視
  • 時間線檢視

使用聊天歷史

  1. 導航到生命體頁面
  2. 點擊矽基生命體的聊天歷史連結
  3. 檢視會話清單：
    • 會話標題
    • 建立時間
    • 訊息數量
  4. 點擊會話檢視詳情：
    • 完整訊息歷史
    • 時間戳
    • 發送者資訊
    • 工具呼叫記錄

技術實作

  • 控制器：ChatHistoryController
  • 檢視模型：ChatHistoryViewModel
  • 檢視：
    • ChatHistoryListView - 會話清單
    • ChatHistoryDetailView - 訊息詳情
  • API 路由：
    • /api/chat-history/{beingId}/conversations - 取得會話清單
    • /api/chat-history/{beingId}/conversation/{conversationId} - 取得訊息詳情

檔案上傳

功能

  • 檔案來源對話框
  • 多檔案上傳支援
  • 檔案元資料管理
  • 上傳進度顯示

使用檔案上傳

  1. 在聊天介面點擊上傳檔案按鈕
  2. 檔案來源對話框開啟
  3. 選擇檔案來源：
    • 本地檔案
    • 檔案系統路徑
  4. 選擇檔案（支援多選）
  5. 確認上傳
  6. 檔案資訊將附加到訊息中

支援的檔案類型

  • 文字檔案（.txt, .md, .json, .xml, 等）
  • 程式碼檔案（.cs, .js, .py, .java, 等）
  • 設定檔案（.yml, .yaml, .ini, .conf, 等）
  • 文件檔案（.csv, .log, 等）

載入指示器

功能

  • 聊天頁面載入狀態顯示
  • 主理人會話自動選擇
  • 資料載入進度回饋

行為

  • 頁面載入時顯示載入動畫
  • 資料載入完成後自動隱藏
  • 主理人會話自動選中（如果存在）
  • 多語言載入提示文字

幫助文件系統（新增）

功能概述

幫助文件系統為矽基生命體和使用者提供多語言的幫助文件支援。

使用幫助文件

  1. 導航到幫助頁面
  2. 檢視幫助主題清單：
    • 快速入門指南
    • 工具使用參考
    • 權限管理指南
    • 故障排除手冊
    • 開發指南
  3. 點擊主題檢視詳細內容：
    • 結構化的文件內容（Markdown 渲染）
    • 多語言支援（跟隨系統在地化設定）
    • 相關主題推薦
  4. 使用搜尋功能快速定位：
    • 關鍵詞搜尋（支援中文、英文）
    • 搜尋結果按相關性排序

矽基生命體存取幫助

矽基生命體可以透過 help 工具存取幫助文件：

{
  "action": "get_topics"
}

技術實作

  • 控制器：HelpController
  • 工具：HelpTool
  • API 路由：
    • /api/help - 取得幫助主題清單
    • /api/help/{topicId} - 取得主題詳情
    • /api/help/search?q=keyword - 搜尋幫助文件

專案工作區（新增）

功能概述

專案工作區提供了一個結構化的工作環境，支援專案管理、任務追蹤和工作筆記。

專案管理

  1. 建立專案：
    • 專案名稱和描述
    • 專案標籤（分類）
    • 專案狀態（進行中、已完成、已歸檔）
  2. 檢視專案詳情：
    • 專案基本資訊
    • 關聯任務清單
    • 工作筆記清單
    • 專案進度統計
  3. 歸檔專案：保留歷史資料但不再活躍
  4. 專案角色管理：
    • 為矽基生命體分配專案角色（如 developer、reviewer、manager）
    • 移除角色分配
    • 檢視專案成員和角色清單
  5. 專案工作流：
    • 檢視工作流範本清單
    • 為專案綁定工作流範本
    • 檢視工作流實例狀態
    • 檢視工作流執行日誌

工作筆記（私有）

矽基生命體的個人工作筆記，類似日記本：

  1. 建立筆記：
    • 摘要（簡短描述）
    • 內容（支援 Markdown 格式）
    • 關鍵詞（用於搜尋）
    • 自動時間戳記錄
  2. 管理筆記：
    • 按時間線瀏覽（頁式設計）
    • 搜尋筆記（按關鍵詞、摘要、內容）
    • 生成目錄（快速瀏覽筆記結構）
    • 更新和刪除筆記
  3. 權限控制：
    • 預設私有，僅生命體自身可存取
    • 矽基主理人可管理所有筆記

技術實作

  • 控制器：WorkNoteController
  • 工具：WorkNoteTool、ProjectTool、ProjectWorkNoteTool
  • API 路由：
    • /api/worknotes - 取得工作筆記清單
    • /api/worknotes/{id} - 取得筆記詳情
    • /api/worknotes/search?q=keyword - 搜尋筆記
    • /api/worknotes/directory - 生成筆記目錄
    • /api/projects - 專案管理 API

響應式設計

Web UI 適應不同的螢幕尺寸：

  • 桌面：完整佈局
  • 平板：壓縮側邊欄
  • 行動裝置：可摺疊選單

鍵盤快速鍵

快速鍵 操作
Ctrl+K 快速搜尋
Ctrl+B 切換側邊欄
Ctrl+Enter 發送訊息
Esc 取消/關閉

故障排除

無法連線

檢查：

  • 伺服器正在運行
  • 連接埠 8080 未被封鎖
  • 防火牆設定

SSE 不工作

檢查：

  • 瀏覽器支援 SSE
  • 無代理緩衝 SSE
  • 網路穩定性

效能慢

最佳化：

  • 降低日誌詳細程度
  • 清理舊審計資料
  • 檢查系統資源

下一步