后端：🐍 Python 3.12、⚡ FastAPI、🚀 Uvicorn、🗄️ SQLite、🔐 Paramiko、🌐 HTTPX、🔌 WebSockets 前端：⚛️ React 18、📘 TypeScript、🔧 Vite、🎨 TailwindCSS、📈 ECharts 工具：⚡ uv（包管理）、📊 Loguru（日志）、⚡ orjson（JSON）、✅ Pydantic v2

系统架构

┌─────────────────────────────────────────────────────────┐
│                      前端 (React)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │   💬 对话    │  │   ⚡ 执行   │  │    📊 监控      │ │
│  │   ChatView  │  │   Stream    │  │     Charts      │ │
│  └─────────────┘  └─────────────┘  └─────────────────┘ │
└──────────────────────────┬──────────────────────────────┘
                           │ REST API / WebSocket
┌──────────────────────────▼──────────────────────────────┐
│                    后端 (FastAPI)                        │
│  ┌─────────────────────────────────────────────────┐   │
│  │              🧠 AgentCore 核心引擎               │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────┐ │   │
│  │  │  🎯 意图    │  │  🛡️ 风险   │  │  🔄 任务 │ │   │
│  │  │  Parser     │  │  Assessor   │  │ Planner │ │   │
│  │  └─────────────┘  └─────────────┘  └─────────┘ │   │
│  │  ┌─────────────┐  ┌─────────────┐              │   │
│  │  │  ⚙️ 命令    │  │  📝 结果    │              │   │
│  │  │  Generator  │  │  Formatter  │              │   │
│  │  └─────────────┘  └─────────────┘              │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────┐      ┌─────────────────┐          │
│  │  🖥️ Local       │      │  🔗 SSH         │          │
│  │    Adapter      │      │   Adapter       │          │
│  │  (subprocess)   │      │   (Paramiko)    │          │
│  └─────────────────┘      └─────────────────┘          │
└─────────────────────────────────────────────────────────┘

🚀 快速开始

📋 环境要求

🐍 Python 3.12
⬢ Node.js 18+
🗄️ SQLite（内置，无需额外安装）

📦 安装依赖

# 克隆仓库
git clone <repository-url>

# 安装后端依赖
cd backend
pip install -r requirements.txt

# 安装前端依赖
cd ../frontend
npm install

⚙️ 配置

创建后端环境变量文件 backend/.env：

# LLM 配置（必须）
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
LLM_MODEL=glm-4.7
LLM_TEMPERATURE=0.1

# 可选配置
LOG_LEVEL=INFO

▶️ 启动服务

方式一：使用启动脚本（推荐）

# 一键启动前后端服务
./start.sh

方式二：手动启动

# 终端 1：启动后端
cd backend
python main.py

# 终端 2：启动前端
cd frontend
npm run dev

方式三：Docker 部署

# 构建镜像
docker build -t neural-link-os-agent .

# 运行容器
docker run -p 8000:8000 -p 5173:5173 \
  -e LLM_API_KEY=your-api-key \
  -e LLM_BASE_URL=https://api.openai.com/v1 \
  neural-link-os-agent

🌐 访问 http://localhost:5173 开始使用。

🧪 验证安装

# 运行完整测试套件
python tests/test_complete_suite.py

# 后端语法检查
python -m py_compile backend/app/agent/*.py

# 前端类型检查
cd frontend
npm run type-check

# 前端生产构建
cd frontend
npm run build

📁 项目结构

neural-link-os-agent/
├── 🔧 backend/                       # 后端服务
│   ├── 📂 app/
│   │   ├── 🧠 agent/                 # Agent 核心引擎
│   │   │   ├── __init__.py
│   │   │   ├── core.py               # 主调度器
│   │   │   ├── intent_parser.py      # 意图解析（规则）
│   │   │   ├── intent_parser_llm.py  # 意图解析（LLM）
│   │   │   ├── risk_assessor.py      # 风险评估
│   │   │   ├── risk_assessor_llm.py  # 风险评估（LLM）
│   │   │   ├── command_generator.py  # 命令生成
│   │   │   └── command_generator_llm.py # 命令生成（LLM）
│   │   ├── 🔌 adapter/               # 执行适配器
│   │   │   ├── __init__.py
│   │   │   ├── base.py               # 抽象基类
│   │   │   ├── local.py              # 本地执行
│   │   │   └── ssh.py                # SSH 远程执行
│   │   ├── ⚙️ core/                  # 核心服务
│   │   │   ├── __init__.py
│   │   │   ├── environment.py        # 环境检测
│   │   │   ├── session.py            # 会话管理
│   │   │   ├── audit.py              # 审计日志
│   │   │   ├── task_orchestrator.py  # 任务编排
│   │   │   ├── intent_parser.py      # 意图解析（兼容）
│   │   │   ├── intent_parser_llm.py
│   │   │   ├── risk_assessor.py      # 风险评估（兼容）
│   │   │   ├── command_generator.py
│   │   │   └── exceptions.py         # 异常定义
│   │   ├── 🤖 llm/                   # LLM 客户端
│   │   │   ├── __init__.py
│   │   │   ├── base.py               # 基础接口
│   │   │   ├── client.py             # 统一客户端
│   │   │   └── providers/            # 多提供商支持
│   │   │       ├── __init__.py
│   │   │       └── generic.py
│   │   ├── 🛠️ tools/                 # 系统工具
│   │   │   ├── __init__.py
│   │   │   ├── system.py             # 系统信息
│   │   │   ├── process.py            # 进程管理
│   │   │   ├── disk.py               # 磁盘操作
│   │   │   ├── file.py               # 文件操作
│   │   │   └── user.py               # 用户管理
│   │   ├── 🌐 websocket/             # WebSocket 模块
│   │   │   └── __init__.py
│   │   ├── 🛠️ utils/                 # 工具函数
│   │   │   ├── __init__.py
│   │   │   └── helpers.py
│   │   ├── main.py                   # FastAPI 入口
│   │   ├── config.py                 # 配置管理
│   │   └── schemas.py                # 数据模型
│   ├── main.py                       # 启动入口
│   ├── requirements.txt              # Python 依赖
│   └── .env.template                 # 环境变量模板
│
├── 🎨 frontend/                      # 前端应用
│   ├── 📂 src/
│   │   ├── 🧩 components/            # UI 组件
│   │   │   ├── ResponseView.tsx      # 结果展示
│   │   │   ├── OperationStream.tsx   # 执行过程流
│   │   │   ├── SystemCharts.tsx      # 系统监控图表
│   │   │   ├── TaskOrchestrator.tsx  # 任务编排器
│   │   │   ├── RiskWarning.tsx       # 风险警告
│   │   │   ├── ConfirmationDialog.tsx # 确认对话框
│   │   │   ├── AuditLogViewer.tsx    # 审计日志查看器
│   │   │   ├── ErrorRecovery.tsx     # 错误恢复
│   │   │   ├── SidePanelContent.tsx  # 侧边面板
│   │   │   └── index.ts              # 组件导出
│   │   ├── 🎣 hooks/                 # 自定义 Hooks
│   │   │   ├── index.ts
│   │   │   ├── useOperationStream.ts
│   │   │   ├── useSystemMonitor.ts
│   │   │   └── useTaskOrchestrator.ts
│   │   ├── 🎨 styles/                # 样式文件
│   │   │   └── index.css
│   │   ├── 🛠️ utils/                 # 工具函数
│   │   │   ├── index.ts
│   │   │   ├── api.ts                # API 客户端
│   │   │   ├── config.ts             # 配置
│   │   │   └── echarts.ts            # 图表配置
│   │   ├── App.tsx                   # 主应用
│   │   ├── main.tsx                  # 入口
│   │   └── vite-env.d.ts             # Vite 类型声明
│   ├── public/                       # 静态资源
│   │   └── favicon.svg
│   ├── index.html                    # HTML 模板
│   ├── package.json                  # Node 依赖
│   ├── package-lock.json             # 锁定文件
│   ├── vite.config.ts                # Vite 配置
│   ├── tsconfig.json                 # TypeScript 配置
│   ├── tsconfig.node.json            # Node TS 配置
│   ├── tailwind.config.js            # Tailwind 配置
│   └── postcss.config.js             # PostCSS 配置
│
├── 🧪 tests/                         # 测试套件
│   ├── __init__.py
│   ├── test_complete_suite.py        # 完整测试套件
│   ├── test_system_info_risk.py      # 系统信息测试
│   └── test_task_flow.py             # 任务流测试
│
├── 📂 scripts/                       # 脚本工具
│   └── init-codex.sh.example         # 初始化脚本示例
│
├── 📄 file/                          # 文档资料
│   ├── AI_Hackathon_2026.pdf         # 赛题文档
│   ├── DESIGN.md                     # 架构设计文档
│   ├── PROBLEM.md                    # 赛题背景
│   ├── TEST_LOCAL.md                 # 本地测试记录
│   └── TEST_WEB.md                   # Web 测试记录
│
├── 🐳 Dockerfile                     # Docker 构建文件
├── 📜 start.sh                       # 启动脚本
│
├── ⚙️ .cnb.yml                       # CNB 配置
├── 📄 .gitignore                     # Git 忽略规则
│
├── 📄 settings.json                  # 编辑器配置
├── 📜 LICENSE                        # 开源协议
└── 📖 README.md                      # 本文件

🔌 API 接口

REST API

接口	方法	说明
`/api/chat`	POST	💬 发送消息，获取响应
`/api/chat/confirm`	POST	✅ 确认执行待确认的操作
`/api/ssh/connect`	POST	🔗 连接 SSH 服务器
`/api/ssh/disconnect`	POST	👋 断开 SSH 连接
`/api/ssh/status`	GET	📡 获取 SSH 连接状态
`/api/system/info`	GET	🖥️ 获取系统信息
`/api/system/disk`	GET	💾 获取磁盘信息
`/api/system/memory`	GET	🧠 获取内存信息
`/api/system/cpu`	GET	⚙️ 获取 CPU 信息
`/api/system/net`	GET	🌐 获取网络信息
`/api/audit/logs`	GET	📝 查询审计日志
`/api/audit/statistics`	GET	📊 审计统计
`/api/sessions`	GET/POST	💾 会话管理
`/api/sessions/{id}`	GET	📂 获取特定会话
`/api/sessions/{id}/messages`	POST	💬 发送会话消息
`/api/health`	GET	🏥 健康检查
`/api/config`	GET	⚙️ 获取配置信息