内容
="center">
# 智能笔记本代理
### 面向笔记本管理的个人智能代理 — 私有、安全、离线优先Python](https://img.shields.io/badge/Python-3.3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[
[
[](https://ollama.ai/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
**零 API 密钥。零云调用。完全系统控制 — 带有加密审计追踪。**
*由 [Sunil Gentyala](https://github.com/sunilgentyala) 构建 · IEEE 高级会员 · HCL America Inc.*
</div>
---
## 🤔 这是什么？
LaptopAI-Agent 是一个**完全本地、隐私优先的自主人工智能代理**，用于管理和推理您的笔记本电脑。它结合了：
- **LangGraph 推理循环** — 多步骤规划与工具使用，最多 10 次代理迭代每个查询
- **通过 Ollama 的本地大语言模型** — 默认 `qwen2.5-coder:7b`，用于高工具调用准确率，无需互联网
- **ChromaDB RAG 层** — 提取您的 git 仓库、配置文件、日志和文档；在推理时检索相关上下文
- **MCP 服务器** — 通过 stdio工具暴露给 Claude Desktop / Claude Code
- **SHA 链式审计日志** — 仅追加、抗篡改的 JSONL 记录每个代理操作
询问它： *"哪些仓库有未提交的更改？"* 或 *"我的磁盘已使用 87%，C:\Gitrepos 中占用了多少空间？"* 它将推理、调用工具并响应 — 完全在您的机器上。
---
## ⚡️ 快速入门
```bash
# 1. 拉取推荐的本地模型
ollama pull qwen2.5-coder:7b
# 2. 依赖项
pip install -r requirements.txt
# 3. 开始聊天
python main.py chat
# 4. 检查系统健康仪表盘
python main.py status
# 5. 列出所有 git 仓库 + 远程 URL + 分支
python main.py repos
# 6. 将文档提取到本地 RAG
python main.py ingest C:\Gitrepos\LaptopAI-Agent\docs
# 7. 启动 MCP 服务器（适用于 / Claude Code）
python main.py mcp
# 8. 验证审计日志链完整性
python main.py verify-audit
```
---
## 🏗️ 架构
```
┌─────────────────────────────────────────────────────────────────────┐
│ 用户 / MCP 客户端 │
│ （CLI 聊天或 Claude Desktop） │
└───────────────────────────────┬─────────────────────────────────────┘
│ 查询
▼
┌─────────────────────────────────────────────────────────────────────┐
│ LangGraph 代理循环 │
│ │
│ ┌──────────┐ 工具调用？ ┌──────────────┐ │
│ │ 代理 │ ──────────────► │ 工具节点 │ │
│ │ （大语言模型） │ ◄────────────── │ （LangChain） │ │
│ └──────────┘ 工具结果 └──────────────┘ │
│ │ │ │
│ 最多 10 次迭代 权限守护 │
│ │ + 审计日志 │
│ ▼ │
│ 最终响应 │
└───────────────────────────────┬─────────────────────────────────────┘
│
┌─────────────────────┼────────────────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌─────────────────────┐ ┌────────────────────┐
│ Ollama（大语言模型） │ │ ChromaDB（RAG） │ │ 系统工具 │
│ │ │ │ │ │
│ qwen2.oder:7b │ │ all-MiniLM-v2 │ util, git, │
│ 本地主机:11434 │ │ 余弦相似度 │ pathlib, 子进程│ 温度=0.1 │ │ 令牌块 │ │
│ 无密钥 │ │ 64 令牌重 │ │ │
└────────────────── └──────────────────── └────────────────────```
---
## 🛠️ 可用工具
每个工具调用都由 **权限守护** 拦截并写入 **链式审计日志**。
工具 | 描述 | 权限 |
|---|---|---|
| `get_system_status` | CPU%，内存%，磁盘可用 GB，电池%，启动时间，平台 | 读取 |
| `list_gitrepos` | 所有仓库（在 `C:\Gitrepos` 下）及其远程 URL 和当前分支 | 读取 |
| `run_git_status` | 指定仓库的 `git status --short` | 读取（路径检查） |
| `list_running_processes` | 按 CPU排名的前 N 个进程（通过 psutil） | 读取 |
| `read_file` | 读取任意不超过 2 MB 的文本文件（来自允许的路径） | 读取（允许列表） |
| `write_file` | 在允许的路径中写入文件内容 | 写入（允许列表） |
| `query_knowledge_base` | 提取文档的语义搜索（前 k 个余弦 | 读取 |
###工具（暴露 Desktop / Claude Code）
| MCP 工具 ||---|---|
|_status` | CPU、内存、磁盘、电池快| `list_gitrepos` | 所有仓库及其 |
| `git_status` | 指定仓库的状态 |
top_processes` | CPU 占用率最高的 进程 |
| `rag_query` | 提取知识语义搜索 |
---
## 🔐 安全模型
AI-Agent 建立在以下假设之上：具有文件写入访问权限的本地代理是一种高特权进程。三个控制措施确保安全操作：
### 1. 权限守护
每个工具调用都通过 `PermissionGuard`：
```
允许写入路径： C:\Gitrepos, C:\Users\\Documents, C\Sunil\Desktop
： C:\32, C:\Program Files
允许命令： git, pip, npm, node, powershell, Get-ChildItem, ...
手动审批： rm, Format-*, reg delete
最大文件写入： MB
最大执行时间： 30```
任何违规行为都会引发Error`，将被阻止 — 大语言模型永远不会看到结果。
### 2. 🔗 SHA-256 链式
每个代理操作都写入 `logs/audit.jsonl **哈希链** — 每个条目都提交前一个条目的哈希任何历史修改都：
```jsonc
{
"timestamp2026-06-05T00:00:00:00",
"event_type": "TOOL_CALL",
"actor":aptopAI-Agent",
"action": "read "target": "Gitrepos\\-RA\\paper.tex",
"result": "32650 chars",
"prev_hash": "a3f1cc...",
" "9d2..." SHA-256(this entry + prev_hash)
}
```
在任何时候都可以验证整个链的完整性：
```bash
python main.py verify-audit
# 链有效（847 条目）
```
### 3. 🔒 零外部调用
| 组件 | |
|---|---|
| 大语言模型推理 | 通过 Ollama 本地运行（`localhost:11434`） 嵌入 | 通过 `sentence-transformers` 本地运行 |
| 向量存储 | 通过 ChromaDB 本地运行（`./data/chroma_db/`） |
| 审计日志 | 本地运行（`./logs/audit.jsonl`） |
没有令牌、查询、文件或嵌入会离开您的机器。
---
## 🧩 / Claude Code 添加到 `claude_desktop_config.json`：
-:** `%AP%\Claude\claude_desktop_config.json`
- **Mac:** `~/Library/Application Support//claude_desktop_config.json`
```json
{
"mcpServers": {
"laptop-ai": {
"command": "python",
"args": ["C:\\pos\\Lmain.py", "mcp"],
"cwd": "C:\\Gitrepos\\Laptop"
}
}
}
```
连接后，Claude 可以直接从任何对话中调用 `system_status`、`list_gitrepos`、`git_statustop_processes` 和 `rag_query` — 都记录到踪中。
---
## 📚 RAG 知识库
RAG 层使用滑动窗口分块器与去重合并来提取 `.txt`、`.md`、`.log`、`.py`、`.yaml` 和 `.json` 文件：
| 参数 | 值 |
|---|---|
| 向量数据库 | ChromaDB（持久本地） |
| 嵌入模型 | `all-MiniLM-L6-v2`（sentence-transformers，本地运行） |
| 相似度度量 | 余弦 |
| 分块大小 | 512 令牌 |
| 分块重叠 | 64 令牌 |
| 去重 | `(file_path, chunk_index)` 的 MD5 哈希 — 安全的上载重索引 |
| 默认前 k | 5 个结果 |
```bash
# 递归提取整个目录
python main.py ingest C:\Gitrepos
# 向代理提出 RAG 基础问题
python main.py chat
> ZKP-RA 电路在策略层强制执行什么？
```
---
## ⚙️ 配置
所有行为均由 `config.yaml` 控制 — 无需：
```yaml
llm:
model: "qwen2.5-coder:7b" # 换成.2, mistral, deepseek-r1 等
temperature: 0.1 # 低 = 更确定性的工具调用
rag:
chunk_size:
chunk 64
top_k: 5
max_file_size 100
:
- "Gitrepos"
"C:\\Usersil\\Documents"
_paths:
- "C:\\Windows\\System32"
require_approval_for:
- "rm"
- "Remove-Item"
monitoring:
alert_cpu_percent: 90
alert_memory_percent: 85
alert_disk_percent: 80
```
---
## 📁 项目结构
```
LaptopAI-Agent/
├── main.py # CLI 入口点
├── config.yaml # 所有运行时配置
├── requirements.txt
├── src/
│ ├── agent/
│ │ ├── graph.py # LangGraph StateGraph — 代理 ↔ ToolNode 循环（最多 10 次迭代）
│ │ └── tools.py # LangChain @tool 定义 + PermissionGuard 钩子
│ ├── mcp/
│ │ └── server.py # MCP stdio 服务器 — 向 Claude 暴露 5 种工具
│ ├── rag/
│ │ └── knowledge_base.py # ChromaDB 提取 + 余弦语义查询
│ └── security/
│ ├── audit.py # SHA-256 链式仅追加审计日志
│ └── permissions.py # PermissionGuard — 路径、命令、大小强制执行
├── data/
│ └── chroma_db/ # 本地向量存储（gitignored）
└── logs/
└── audit.jsonl # 防篡改审计追踪（gitignored）
```
---
## 🔬 推荐的本地模型
| 模型 | 大小 | 优势 |
|---|---|---|
| `qwen2.5-coder:7b` ⭐ | ~4.7 GB | 工具调用、代码推理 — **默认** |
| `llama3.2:3b` | ~2.0 GB | 轻量级、快速响应 |
| `mistral:7b` | ~4.1 GB | 通用推理、指令遵循 |
| `deepseek-r1:7b` | ~4.7 GB | 多步骤规划、数学 |
```bash
ollama pull qwen2.5-coder:7b # 推荐
ollama pull llama3.2:3b # 轻量级替代
```
---
## 📦 关键依赖
| 包 | 版本 | 用途 |
|---|---|---|
| `langgraph` | ≥0.2 | 代理状态机 ↔ 工具循环） |
| `langchain-ollama` |.2 | Ollama 大语言模型绑定，带有原生工具调用 |
| `mcp` | ≥1.0 | 模型上下文协议服务器（stdio） |
| `chromadb` | ≥0.5 | 本地持久向量数据库 |
| `sentence-transformers` | ≥3.0 | 本地嵌入（`all-MiniLM-L6-v2`） |
| `psutil` | ≥6.0 | CPU、内存、磁盘、电池、进程检查 |
| `rich` | ≥13.0 | 终端输出格式化 |
| `typer` | ≥0.12 | CLI 命令路由 |
---
## 📖 研究与参考
| 项目 | 链接 |
|---|---|
| LangGraph | [github.com/langchain-ai/langgraph](https://github.com/langchain-ai/langgraph) |
| 模型上下文协议 | [modelcontextprotocol.io](https://modelcontextprotocol.io) |
| RAGFlow | [github.com/infiniflow/ragflow](https://github.com/infiniflow/ragflow) |
| Agent-S | [github.com/simular-ai/Agent-S](https://github.com/simular-ai/Agent-S) |
| AIOS | [github.com/agiresearch/AIOS](https://githubiresearch/AIOS) |
| SoK：区块链的 AI 代理 | [arXiv:2509.07131](https://arxiv.org/abs/2509.07131) |
---
## 👤 作者
**Sunil Gentyala**
美国 HCL America Inc. 网络安全和 AI 安全顾问 — 达拉斯 TX
IEEE 高级会员 No. 101760715 · CISM No. 263076408 · BCS 研究员
[](https://github.com/sunilgentyala)
[](https://www.linkedin.com/in/sunilgentyala/)
[](https://sunilgentyala.github.io)
[](mailto:sunil.gentyala@ieee.org)
---
## 📄 许可证
Apache 2.0 — 参见 [LICENSE](LICENSE) 了解详情。
---
<div align="center">
<sub>为隐私、安全和完全本地控制而构建。无 API 密钥。无云服务。仅限您的机器。</sub>
</div>
