你是一个agent领域的专家，基于langchain+python+vue开发一个对标claude code的agent。你需要详细的说明你开发的细节与步骤并向我解释，同时要列出需求说明以及需求文档，同时你需要和我多交流以明白你的需求，不要自己杜撰需求或者减少需求，先从后端开发起

需求与交付

需求未确认前不写代码 — 先确认、再写、多问
不要杜撰需求 — 不确定就问，不猜
不要减少需求 — 我可能会省略我认为”不重要”的部分
不要增加需求 — 不在需求范围内的功能不主动加
分阶段交付 — 每个阶段完成后停下来等我确认
先测后移 — 一个模块测完再进入下一个，不要留半成品

代码风格

代码简洁易懂 — 不炫技，不过度封装，一眼能看懂最好
变量/函数名自解释 — 不需要注释来说明”这个变量是什么”
每个函数不超过 50 行 — 超了就拆
不写无用的空行和空格 — 代码紧凑但不拥挤
先读现有代码再写 — 保持风格一致
重复超过 3 次就抽函数 — 不要复制粘贴
不写永远不会被调用的代码 — 没有死代码
类型提示必须写 — Python 必须有 type hint

项目结构

遵循既定目录结构 — 不自己发明目录组织方式
配置文件外置 — 不硬编码配置
第三方依赖先查重 — 已有的不重复装
不轻易换核心依赖版本 — 比如 FastAPI、SQLAlchemy 大版本升级要说
不修改别人的代码风格 — 接手代码时保持原风格

安全与风险

危险操作（删文件、清数据）必须二次确认 — 不自动执行
不提交密钥/密码到仓库 — .gitignore 要检查
数据库 migration 前先备份或检查 — 特别是生产环境
文件路径做安全校验 — 防止路径穿越
用户输入必须校验 — 不信任任何外部数据
不记录敏感信息到日志 — 密码、Token 等

沟通与反馈

遇到错误完整报告 — 错误信息 + 堆栈 + 复现步骤
不确定时停下来问 — 不要瞎猜然后做错
有重大决策变化时告诉我 — 比如目标用户、优先级、技术选型
完成后说清楚改了什么 — 不是”完成了”，是”改了哪几个文件、为什么改”
有问题不绕过 — 直接说”这里我不确定”，不假装懂

Agent Console - 需求规格文档 (SPEC.md)

对标 Claude Code 的 Web 控制台版本，基于 LangChain + Python + Vue 开发

1. 项目概述

项目名称: Agent Console

项目类型: 智能编程助手 Web 控制台

核心定位: 一个类 Claude Code 的 Agent 系统，用户通过浏览器与 Agent 对话，Agent 自动完成文件操作、代码执行、代码分析等任务。

目标用户: 个人开发者/小团队（<10人）

2. 核心功能需求

2.1 多工作区支持

用户可创建/切换多个工作区（每个工作区 = 一个本地目录）
每个工作区独立维护自己的文件树和 Agent 会话记忆
工作区列表持久化存储

2.2 Agent 对话能力

用户通过输入框向 Agent 发送自然语言指令
Agent 自动理解用户意图，调用工具完成以下操作：
文件读写: 读取、创建、编辑文件
代码执行: 执行 Python/Shell 脚本，返回执行结果
代码分析: 分析现有代码结构，给出解释
工作区感知: 理解当前工作区的代码结构
多轮对话支持，Agent 记住上下文

2.3 工具系统（内置）


工具	描述
`file_read`	读取文件内容
`file_write`	创建/覆盖文件
`file_edit`	编辑文件（行级别替换）
`glob`	按模式搜索文件（如 `*.py`）
`grep`	在文件中搜索关键词
`terminal`	执行 shell 命令
`list_dir`	列出目录结构
`code_analysis`	分析代码结构和逻辑

2.4 记忆系统

会话记忆: 记录当前对话的所有消息历史
持久化记忆: 跨会话记住用户偏好、工作区上下文
使用 PostgreSQL 存储记忆数据

2.5 实时通信

Agent 执行过程通过 SSE（Server-Sent Events）实时推送
用户可实时看到 Agent 的思考过程和工具调用日志
支持流式输出（LLM token 逐字输出）

2.6 危险操作审批

Agent 执行以下操作前需用户确认：
- 删除文件（单文件 > 3 行代码）
- 删除目录
- 执行破坏性 shell 命令（rm -rf、格式化了等）
确认界面列出操作详情，用户点击”确认”后继续执行

2.7 模型配置（可切换）

管理后台配置模型 API 地址和 API Key
支持 OpenAI 兼容格式的 API（Anthropic Claude / 智谱 GLM / 通义 Qwen / Ollama 等）
用户可在不同工作区选择不同模型

3. 非功能需求

3.1 技术栈


层级	技术
后端	Python 3.11+, FastAPI
数据库	PostgreSQL
前端	Vue 3 + Vite + Element Plus
通信	SSE（后端推送）、WebSocket（如需要）
Agent 框架	LangChain

3.2 部署

单机部署，Web 控制台通过浏览器访问
后端端口: 8000，前端端口: 3000
工作区目录: ./workspaces/{workspace_id}/（项目根目录下）

3.3 数据库（可插拔）

默认: SQLite（开发/单机部署）
设计: 使用 SQLAlchemy ORM，抽象数据库接口
切换: 仅需修改配置即可切换 PostgreSQL/MySQL 等
连接池默认关闭（SQLite 单连接适用）

3.4 权限体系

简单 RBAC：管理员 / 普通用户
管理员: 创建工作区、配置模型、管理敏感目录、管理用户
普通用户: 使用已有工作区

3.5 危险操作审批（细粒度）

风险等级（高/低两档）


等级	操作类型	处理方式

| 低风险 | 只读操作：cat、grep、head、tail、ls、find 等 | 直接放行，无需审批 |

| 高风险 | 写/删操作：文件写入、删除文件、删除目录、执行非只读命令 | 需用户审批 |

敏感目录保护

管理员配置全局敏感目录列表（如 ~/.ssh、/etc、C:\Windows 等）
操作涉及敏感目录时，提升为高风险，即使低风险命令也需审批
工作区内可单独标记子目录为敏感（工作区级别配置）

审批流程

Agent 判断操作风险等级
高风险操作 → 暂停执行 → 创建 approval 记录 → 推送待审批通知给前端
用户确认/拒绝 → Agent 继续执行或终止
管理员可在管理后台查看审批历史

3.4 性能要求

文件搜索/读写 < 100ms（本地文件）
Agent 首次响应 < 3s（不含模型 API 延迟）
SSE 推送延迟 < 500ms

4. 系统架构

┌─────────────────────────────────────────────────────────────┐
│                      Web Console (Vue 3)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ 工作区   │  │ 对话窗口  │  │ 文件浏览器│  │ 模型配置 │   │
│  │ 侧边栏   │  │          │  │          │  │          │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└──────────────────────────┬────────────────────────────────┘
                          │ HTTP / SSE
┌──────────────────────────▼────────────────────────────────┐
│                    FastAPI Backend                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ Agent    │  │ Workspace│  │ 记忆系统 │  │ 工具系统 │   │
│  │ Router   │  │ Manager  │  │          │  │          │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │ LangChain│  │ Model    │  │ Approvals│                  │
│  │ Executor │  │ Factory  │  │ Handler  │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
└──────────────────────────┬────────────────────────────────┘
                          │ /workspace/{id}/*
┌──────────────────────────▼────────────────────────────────┐
│                    Local Filesystem                         │
└─────────────────────────────────────────────────────────────┘

5. 数据库模型

5.1 用户表 (`users`)

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    username VARCHAR(50) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(20) DEFAULT 'user', -- 'admin' | 'user'
    created_at TIMESTAMP DEFAULT NOW()
);

5.2 模型配置表 (`model_configs`)

CREATE TABLE model_configs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(100) NOT NULL,
    api_base VARCHAR(500) NOT NULL,
    api_key VARCHAR(255),
    model_name VARCHAR(100) NOT NULL,
    is_default BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT NOW()
);

5.2b 敏感目录表 (`sensitive_paths`)

CREATE TABLE sensitive_paths (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    path_pattern VARCHAR(500) NOT NULL, -- 如 'C:\Windows'、'/etc'、'~/.ssh'
    description VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW()
);

5.2c 工作区敏感目录表 (`workspace_sensitive_paths`)

CREATE TABLE workspace_sensitive_paths (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id UUID REFERENCES workspaces(id) ON DELETE CASCADE,
    path_pattern VARCHAR(500) NOT NULL,
    UNIQUE(workspace_id, path_pattern)
);

5.3 工作区表 (`workspaces`)

CREATE TABLE workspaces (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(100) NOT NULL,
    path VARCHAR(500) NOT NULL, -- 本地目录路径
    owner_id UUID REFERENCES users(id),
    model_config_id UUID REFERENCES model_configs(id),
    created_at TIMESTAMP DEFAULT NOW()
);

5.4 会话表 (`sessions`)

CREATE TABLE sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id UUID REFERENCES workspaces(id) ON DELETE CASCADE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

5.5 消息表 (`messages`)

CREATE TABLE messages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id UUID REFERENCES sessions(id) ON DELETE CASCADE,
    role VARCHAR(20) NOT NULL, -- 'user' | 'assistant' | 'system'
    content TEXT NOT NULL,
    tool_calls JSONB, -- 记录工具调用信息
    created_at TIMESTAMP DEFAULT NOW()
);

5.6 记忆表 (`memories`)

CREATE TABLE memories (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id UUID REFERENCES workspaces(id) ON DELETE CASCADE,
    memory_key VARCHAR(100) NOT NULL,
    memory_value JSONB NOT NULL,
    updated_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(workspace_id, memory_key)
);

5.7 审批表 (`approvals`)

CREATE TABLE approvals (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id UUID REFERENCES sessions(id) ON DELETE CASCADE,
    operation VARCHAR(50) NOT NULL,
    details JSONB NOT NULL,
    status VARCHAR(20) DEFAULT 'pending', -- 'pending' | 'approved' | 'rejected'
    created_at TIMESTAMP DEFAULT NOW(),
    resolved_at TIMESTAMP
);

6. API 接口设计

6.1 认证


方法	路径	描述
POST	`/api/auth/login`	登录
POST	`/api/auth/logout`	登出

6.2 工作区


方法	路径	描述
GET	`/api/workspaces`	列出所有工作区
POST	`/api/workspaces`	创建工作区
GET	`/api/workspaces/{id}`	获取工作区详情
DELETE	`/api/workspaces/{id}`	删除工作区
GET	`/api/workspaces/{id}/files`	获取文件树
POST	`/api/workspaces/{id}/files/read`	读取文件
POST	`/api/workspaces/{id}/files/write`	写入文件

6.3 Agent 对话


方法	路径	描述
GET	`/api/sessions/{id}/stream`	SSE 流式获取响应
POST	`/api/sessions/{id}/send`	发送消息
GET	`/api/sessions/{id}/messages`	获取历史消息

6.4 审批


方法	路径	描述
GET	`/api/approvals/pending`	获取待审批项
POST	`/api/approvals/{id}/approve`	审批通过
POST	`/api/approvals/{id}/reject`	审批拒绝

6.5 管理


方法	路径	描述
GET	`/api/admin/models`	列出模型配置
POST	`/api/admin/models`	添加模型配置
PUT	`/api/admin/models/{id}`	更新模型配置
DELETE	`/api/admin/models/{id}`	删除模型配置
GET	`/api/admin/sensitive-paths`	列出敏感目录
POST	`/api/admin/sensitive-paths`	添加敏感目录
DELETE	`/api/admin/sensitive-paths/{id}`	删除敏感目录
GET	`/api/admin/users`	列出用户
POST	`/api/admin/users`	创建用户

7. 前端页面设计

7.1 页面结构

├── 登录页
├── 主控制台
│   ├── 侧边栏（工作区列表）
│   ├── 对话区（消息列表 + 输入框）
│   ├── 文件浏览器（可折叠）
│   └── 工具栏（模型选择 + 设置）
└── 管理后台（仅管理员）
    ├── 用户管理
    └── 模型配置

7.2 对话窗口交互

用户输入 → 点击发送 → 显示 “Agent 思考中…”
SSE 流式接收 Agent 输出，逐字显示
工具调用时显示日志卡片（如 “调用 file_read 读取 index.ts”）
危险操作时弹出确认对话框

7.3 文件浏览器交互

树形展示目录结构
点击文件读取内容到新 tab
右键菜单：新建文件/文件夹、重命名、删除

8. 开发计划

Phase 1: 后端核心（当前）

项目初始化（FastAPI + SQLAlchemy + SQLite）
数据库模型和迁移（ Alembic 支持多数据库）
认证模块（JWT）
工作区管理（文件操作）
LangChain Agent 集成
内置工具实现（file_read/write/edit/glob/grep/terminal/list_dir/code_analysis）
危险操作审批系统（高/低风险 + 敏感目录）
SSE 实时通信

Phase 2: 前端

Vue 3 项目初始化
登录页
主控制台布局
对话窗口（SSE 连接）
文件浏览器
管理后台

Phase 3: 完善

记忆系统完善
权限系统
部署文档

9. 风险与限制


风险	影响	缓解措施
代码执行无隔离	用户可执行任意危险命令	仅内网部署，危险操作需审批，敏感目录保护
多用户文件冲突	并发操作同一文件可能冲突	后续加文件锁
长会话 token 溢出	对话历史过长超出模型上下文	限制历史消息数量，做摘要

9.1 风险评估规则

命令风险分类


风险等级	判断条件

| 低风险 | 命令为只读操作（cat, ls, grep, find, head, tail, pwd, echo, which, file） |

| 高风险 | 任何删除操作（rm, rmdir, del, rmdir）、写入操作（echo >, tee, dd）、格式化/分区命令（mkfs, format, fdisk）、编译/构建（gcc, make, go build）、网络操作（curl, wget 主动外发）、管道执行（| 组合危险命令） |

敏感目录判断

if 操作路径匹配任意 sensitive_paths 中的模式:
    风险等级 = 高风险

审批决策矩阵


风险等级	敏感目录	是否需要审批
低风险	否	❌ 直接执行
低风险	是	✅ 审批
高风险	否	✅ 审批
高风险	是	✅ 审批

10. 已确认


项目	状态
SQLite 可插拔设计	✅ 已确认
工作区目录 `./workspaces/{id}`	✅ 已确认
敏感目录管理员配置级别	✅ 已确认
风险等级高/低两档	✅ 已确认
全局 + 工作区级别敏感目录	✅ 已确认

请确认以上需求是否符合你的预期，如有调整请告诉我。

Agent 开发 Agent