Skip to content

PROJECT.md

Latest commit

 

History

History
48 lines (38 loc) · 3.28 KB

PROJECT.md

File metadata and controls

48 lines (38 loc) · 3.28 KB
Raw

PROJECT.md - ButvanAgent 项目规格说明书

1. 项目基本信息

  • 项目名称: ButvanAgent
  • 项目定位: 桌面级 Agent 智能体应用（面向开发者、程序员与 AI 深度使用者，专注代码协作、项目管理、任务自动化与桌面操控）。
  • 技术栈: React 19 + TypeScript + Vite + Tauri (桌面壳层) + Spring Boot + AgentScope Java (后端引擎)。

2. 核心功能架构

2.1 项目与会话管理 (Workspace & Session Management)

  • 双层会话体系:
    • 普通聊天会话: 一次性或通用问答历史，独立存储。
    • 项目级别聊天会话: 基于导入的本地项目文件夹构建。
  • 树状项目工作区 (Tree Workspace):
    • 支持选择并导入本地项目文件夹，在侧边栏树状列出项目与关联文件。
    • 单个项目下可建立多个子聊天会话，所有关联会话自动继承该项目的代码索引、Git 分支状态与工作区配置。

2.2 多模型配置与动态切换 (Model Management)

  • 多厂商引擎适配: 支持 Google Gemini, DeepSeek, OpenAI, Anthropic, 通义千问 (DashScope), Ollama (本地私有) 等不同厂商的模型配置。
  • 零感动态切换: 用户在聊天框中可随时在已配置的模型间无缝切换，前端选择供应商、模型 ID 并输入 API Key，后端服务根据配置动态实例化对应的 ChatModel / AgentScope 编排组件。

2.3 Token 管理与用量监控 (Token Management & Metering)

  • 实时 Token 统计: 监控并记录单次 Prompt 发送与 AI 返回的 Input / Output Token 数量。
  • 成本与用量大盘: 累计统计 Token 消耗总额并提供费用估算。
  • 上下文超长预警: 当对话上下文接近大模型上下文窗口阈值时提供自动裁剪与压缩警示。

2.4 智能体桌面自动化 (Agentic Execution Capabilities)

  • 操控本机电脑: 支持授权执行 Shell 命令行指令、文件系统读写及目录搜索。
  • 联网搜索: 集成 Web API 与网页提取，获取实时资讯与开发文档。
  • 操控浏览器: 支持浏览器页面自动化交互与内容解析。
  • 分级安全审批机制:
    • 默认安全模式: 基础文件读取与联网搜索自动通过，危险写文件或 Shell 执行需界面显示并等待显式确认。
    • 完全访问模式: 赋予完全无感知操控权限，实现高敏捷任务自闭环。
    • 自定义安全规则: 自定义高风险命令拦截名单。

2.5 账户体系与通知机制 (Account & Notification)

  • 渐进式双轨登录:
    • Phase 1 (当前): 免注册 API Key 本地存储即用模式 (~/.butvan-agent/config.json)。
    • Phase 2 (规划): 引入邮箱 / 验证码登录注册体系。
  • 邮件通知服务: 结合邮箱账户，在长耗时 Agent 任务运行完成、部署异常或生成用量周报时，后端通过 SMTP 向用户邮箱发送异步通知。

3. 设计与工程规范

  • 界面审美基线: 遵循极简 Codex 桌面大厂规范，采用 Flat 零阴影设计、1px 高对比细线条描边与 4px - 8px 精致小圆角。
  • 代码交付要求: 始终保持 agent-frontend/src/components/common/ 目录下原子 UI 组件的解耦封装与 TypeScript 严格类型声明；后端控制器使用 @ApiLog 进行日志追踪。