AidKit 是全网稀缺的单文件微型本地AI Agent桌面工具箱，主打「单AK文件微型智能体、即用即毁、无常驻、低配置适配、纯本地离线」。
区别于 Open-WebUI 聊天臃肿端、LangGraph 重型框架，AidKit 专注：
- 极简轻量：手写 ReAct 调度内核，无重型 Agent 框架
- 单文件 Agent：
.ak单文件包含完整 Agent 配置（含魔数校验，防篡改） - 全 Windows 兼容：适配 Windows 7 SP1 / 10 / 11
- 本地离线：数据不出本机，兼容 Ollama 本地模型
- 直接对话（带工具）：不选 Agent 也能读取本地文件、解析文档、读剪贴板、安全查询系统命令
- 微型 Agent 调度：手写 ReAct 循环（Thought / Action / Observation），内置步数限制防死循环
- 9 大原子工具：文件读写、剪贴板读写、文档解析（含 PDF/DOCX/XLSX）、安全命令行、多 Agent 委托、知识库记忆
- 多 Agent 协作：主 Agent 可将子任务委托给其他 Agent（
agent_delegate），支持专业分工与任务分解 - 知识库长期记忆：跨会话持久化记忆（
kb_add/kb_search），Agent 任务自动检索注入相关知识 - 风险管控：文件写入、剪贴板写入、命令执行、知识写入等高危操作执行前弹窗用户确认，超时自动拒绝
- 多模型适配：DeepSeek / 火山引擎 / MiniMax / 智谱 / 阿里云 / Ollama 等 18 家 OpenAI 兼容接口
- 本地聊天记录：多会话持久化存储，自动保存，随时回溯
| 工具 | 功能 | 风险等级 |
|---|---|---|
file_read |
读取本地文件（限 10MB，自动识别编码） | 低（只读） |
file_write |
写入本地文件（需沙盒路径校验） | 高（需确认） |
clipboard_read |
读取系统剪贴板 | 低（只读） |
clipboard_write |
覆盖系统剪贴板 | 高（需确认） |
doc_parse |
解析文档 txt/md/json/csv/log/docx/xlsx/pdf | 低（只读） |
shell_exec |
安全执行系统命令（只读白名单） | 高（需确认） |
agent_delegate |
委托子任务给其他 Agent（多 Agent 协作） | 低 |
kb_add |
向知识库添加知识（长期记忆写入） | 高（需确认） |
kb_search |
从知识库检索知识（长期记忆读取） | 低（只读） |
支持 8 种格式，DOCX/XLSX/PDF 均用标准库实现（零第三方依赖）：
- DOCX：zip+xml 解析正文段落（
word/document.xml） - XLSX：zip+xml 解析工作表（共享字符串 + 内联字符串 + 数值）
- PDF：优先 pypdf（如已安装），否则标准库 zlib+正则提取文本层
- 主 Agent 调用
agent_delegate将子任务委托给指定 Agent - 子 Agent 独立运行自己的 ReAct 循环（自己的工具集/沙盒/系统提示词）
- 委托深度限制 2 层（防循环委托）+ 超时保护 120 秒
- 子 Agent 内部高风险操作仍走用户确认
- 持久化：存储于
storage/knowledge_base.json，跨会话保留 - 检索：中文分词 + 倒排索引 + 子串回退（零依赖）
- 自动注入：Agent 每次任务自动检索相关知识注入上下文（"回忆"）
- 知识库管理 API：
/kb/list、/kb/add、/kb/delete、/kb/clear、/kb/search
- 命令白名单：仅允许 20 个只读命令（dir/type/whoami/ipconfig/tasklist/findstr 等）
- 高危黑名单：拦截 del/format/rmdir/reg/taskkill/shutdown/powershell 等 40+ 模式
- 危险操作符：拒绝重定向、管道、嵌套执行
- 路径校验：命令中的路径必须通过沙盒白名单
- 超时控制：默认 10 秒、最大 30 秒，防命令卡死
- 输出截断：最多 4000 字符，防上下文过长
- 用户确认：执行前弹窗确认，超时自动拒绝
| 层级 | 技术 | 版本 |
|---|---|---|
| 桌面框架 | Electron | 33（跨平台桌面壳） |
| 前端 | Vue 3 + Vite | ES6 兼容 |
| 后端 | Python 3.10+ | 标准库优先（零第三方依赖） |
| 数据存储 | JSON 本地文件 | 纯本地无上传 |
| 模型适配 | Ollama / 18 家 OpenAI 兼容接口 | 本地优先 |
| 沙盒 | 手写路径/工具/命令三重校验 | 无外部依赖 |
AidKit/
├── core/ # 核心运行时（手写极简，无重型框架）
│ ├── micro_runtime.py # 微型Agent ReAct调度核心（含直接对话工具模式）
│ ├── ak_serializer.py # .ak单文件序列化/导入导出
│ ├── sandbox.py # 本地工具权限沙盒（路径白名单/工具绑定/步数限制）
│ ├── risk_guard.py # 风险管控（高风险操作用户确认）
│ ├── model_bridge.py # 模型统一适配层（18家提供商）
│ ├── chat_store.py # 聊天记录本地存储
│ ├── knowledge_base.py # 知识库长期记忆（持久化+检索+记忆注入）
│ ├── data_manager.py # 数据导出/导入管理（JSON备份）
│ └── tiny_memory.py # 单Agent微型独立记忆（任务内短期）
├── atom_tools/ # 原子工具集（9个：读写/剪贴板/解析/命令/委托/记忆）
├── micro_agents/ # 内置微型AK模板（.ak单文件）
├── configs/ # 全局极简配置（模型提供商/API Key）
├── storage/ # 本地数据存储（聊天记录/知识库，纯本地）
├── internal/ # 打包产物（aidkit-backend.exe Python后端）
├── electron/ # Electron 主进程（main.cjs + preload.cjs）
├── src/ # Vue3前端源码
│ └── components/ # AgentList/AgentRunner/SettingsPage/DataManager 等
├── dist/ # 前端构建产物
└── main.py # 后端入口（HTTP API）
# 1. 安装依赖
npm install
# 2. 构建前端（产物到 dist/）
npm run build
# 3. 启动 Electron 应用（自动拉起 Python 后端）
npm run electron# 终端1: 启动 Vite dev server（端口自动递增，不冲突）
npm run dev
# 终端2: 以开发模式启动 Electron（加载 Vite dev server）
AIDKIT_DEV_URL=http://127.0.0.1:5173 npm run electronnpm run dist # 执行 vite build + electron-builder，产出 NSIS 安装包到 release/端口说明：生产模式 Electron 直接从
dist/加载前端（file://协议），不占用任何端口；开发模式 Vite 端口冲突时自动递增，不会报错。后端仅占用本地回环端口 37210。
直接对话或 Agent 模式下，对助手说：
- "帮我读一下 D 盘某文件夹里的 xxx.docx / xxx.xlsx / xxx.pdf"（文档解析）
- "看看桌面上的文件列表"（shell_exec 安全查询）
- "记住：我的会议时间是每周五下午3点"（知识库记忆写入，会弹窗确认）
- "把整理任务交给文件整理助手"（多 Agent 协作委托）
在「设置」→「数据管理」中可导出/导入 AidKit 全部本地数据（JSON 格式）：
- 选择性导出：可勾选 Agent 配置 / 聊天记录 / 知识库 / 模型设置，生成
aidkit_backup_*.json - 导入自动识别：选择之前导出的 JSON 文件，自动识别包含哪些类型数据
- 覆盖确认：导入前明确提示"将覆盖现有数据"，确认后才执行
已取消 .ak 单文件导出/导入，统一使用 JSON 数据备份。
| 接口 | 方法 | 说明 |
|---|---|---|
/health |
GET | 健康检查 |
/agents |
GET | Agent 列表 |
/agent/load |
POST | 加载 Agent（.ak 文件） |
/agent/builtin |
POST | 加载内置 Agent 模板 |
/agent/parse |
POST | 解析 Agent 配置 |
/agent/export |
POST | 导出 Agent（.ak 文件） |
/agent/save |
POST | 保存 Agent |
/agent/delete |
POST | 删除 Agent |
/agent/template |
GET | 空白 Agent 模板 + 合法工具列表 |
/agent/run |
POST | 运行 Agent（ReAct 调度） |
/agent/pending |
GET | 待确认的高风险操作 |
/agent/confirm |
POST | 用户确认/拒绝高风险操作 |
/models |
GET | 模型提供商列表（18 家） |
/models/config |
GET | 当前模型配置 |
/models/save |
POST | 保存模型配置 |
/models/test |
POST | 测试模型连接 |
/chat/create |
POST | 创建会话 |
/chat/list |
GET | 会话列表 |
/chat/get |
POST | 会话详情 |
/chat/save |
POST | 保存会话 |
/chat/append |
POST | 追加消息到会话 |
/chat/delete |
POST | 删除会话 |
/chat/send |
POST | 发送消息（纯对话带工具 / Agent 模式） |
/kb/list |
GET | 知识库列表（分页） |
/kb/add |
POST | 添加知识到知识库 |
/kb/delete |
POST | 删除一条知识 |
/kb/clear |
POST | 清空知识库 |
/kb/search |
POST | 检索知识库 |
/data/export |
POST | 选择性导出数据（JSON） |
/data/import/preview |
POST | 导入文件自动识别 |
/data/import |
POST | 执行导入（覆盖现有数据） |
/shutdown |
POST | 优雅关闭 |
.ak 单文件 = 完整 Agent 配置（JSON 格式 + 魔数校验）：
{
"magic": "AIDKIT",
"version": "1.0",
"name": "Agent名称",
"desc": "功能描述",
"system_prompt": "系统提示词",
"tools": ["file_read", "file_write", "doc_parse", "shell_exec", "kb_search"],
"permissions": {
"allow_paths": ["D:\\Users\\xxx\\Desktop"],
"max_steps": 10
},
"model_hint": ""
}- magic 校验：加载时校验魔数，拒绝非 AidKit 文件
- 工具绑定：tools 列表决定 Agent 可用工具（经白名单校验）
- 沙盒权限：allow_paths 限定可访问路径，max_steps 限制最大循环步数
用户指令
│
▼
ReAct 调度（MicroRuntime）
│
├── 工具绑定校验 ──── 非绑定工具 → 拒绝
├── 风险管控 ──────── 高危操作 → 弹窗用户确认（超时自动拒绝）
├── 沙盒路径校验 ──── 越权路径 → 拒绝（防目录穿越）
├── 命令安全校验 ──── 白名单/黑名单/操作符拦截
├── 委托深度限制 ──── 多Agent委托超2层 → 拒绝（防循环委托）
└── 步数限制 ──────── 超限自动终止
安全要点：
- 零第三方依赖：核心运行时、文档解析（docx/xlsx/pdf）、知识库检索全部标准库实现
- 本地隔离：所有数据存于本机
storage/，无任何上传 - 双重沙盒：工具级（绑定校验）+ 路径级（白名单），高风险操作均需用户确认
- 本地回环：后端 HTTP 服务仅监听 127.0.0.1，杜绝远程访问
- 第一步：搭建基础项目架构 + Windows 桌面壳子
- 第二步：实现 .ak 文件序列化、导入导出核心能力
- 第三步：开发极简 Micro-Agent ReAct 运行时
- 第四步：对接多模型适配层（18 家 OpenAI 兼容接口 + Ollama）
- 第五步：开发基础原子工具 + 沙盒权限管控 + 风险确认
- 第六步：内置官方微型 AK 模板
- 第七步：Windows 7 兼容性专项适配
- 第八步：直接对话接入工具能力（run_direct）
- 第九步：PDF/DOCX/XLSX 文档解析扩展
- 第十步：多 Agent 协作（agent_delegate 委托）
- 第十一步：知识库长期记忆（持久化 + 检索 + 记忆注入）
- 第十二步：数据导出/导入（JSON 选择性导出 + 自动识别导入 + 覆盖确认）
- 第十三步：设置界面重构（二级菜单：模型设置/数据管理/关于）
- 第十四步：桌面框架迁移 Tauri → Electron（零端口占用）
- 后续：知识库向量检索增强、多 Agent 并行调度、前端知识库管理界面
MIT License - 基础功能完全开源免费