existence-master/Sentient · 上手攻略

  • 仓库：existence-master/Sentient
  • 链接：https://github.com/existence-master/Sentient
  • 分类：agent · llm-infra
  • 作者：Jay
  • 更新：2026-10-13

TLDR

个人 AI 助手，运行在你自己电脑上——长时任务、真实记忆、主动建议、语音通话；支持任意本地或云端模型，无账号、无服务器。所有数据留在本地（~/.sentient），卸载后数据保留。

§0 自检

  • [x] GitHub URL 已 fetch（README + GETTING_STARTED.md + PRIVACY.md）
  • [x] 顶会 anchor：无（experimental 工具类仓库，非论文）
  • [x] README 子模块 anchor：docs/GETTING_STARTED.md · docs/PRIVACY.md · docs/ARCHITECTURE.md · docs/NODES.md
  • ⚠️ 版本：v3 alpha，预构建安装程序尚未签名（Windows 上需"更多 info → 仍然运行"）
  • ⚠️ macOS/Linux 安装程序尚未发布，需从源码运行

§1 是什么

Sentient 是一个本地优先的个人 AI 助手框架，核心是一个运行在用户本机的 Python 引擎，由一个 Agent 循环统一驱动聊天、任务调度、记忆管理、主动建议和语音交互。数据全部存储在 ~/.sentient（Windows 上为 C:\Users\<you>\.sentient）的单个 SQLite 文件中；API 密钥存在系统 Keychain，不落文件。

技术架构（来自 README）：

Desktop App ← → Agent Loop
                ├── Tasks & Scheduler
                ├── Memory & User Model
                ├── Proactivity & Skills
                └── Tools: apps, browser, code, devices
                    ↑
          Local (Ollama) 或 Cloud (你的 API Key)

支持集成的应用（来自 README）： Gmail · Calendar · Drive · Docs · Sheets · GitHub · Slack · Notion · Trello · Discord · WhatsApp · 任意 MCP Server

语音与设备： - 唤醒词"Hey Sentient"（本地语音识别） - Telegram / Discord 消息接入 - 手机/智能眼镜配对（六位码配对，协议开源，有参考眼镜固件） - 摄像头读取（需用户确认）

许可证： GNU AGPL v3

§2 解决什么问题

核心痛点： 市面上大多数 AI 助手都是云服务——你的对话数据、记忆、任务都被上传到第三方服务器。Sentient 试图在保留强大 AI 能力的同时，把数据和计算都留在你自己的机器上。

适用人群： - 对隐私有强需求，不希望对话内容上传云端 - 想用免费本地模型（Ollama）零成本跑个人助手 - 需要一个能在后台运行长时任务、定时任务的本地 Agent - 希望 AI 能主动提醒而非被动回答 - 开发者想基于开源架构构建自己的 AI 设备/助手

§3 快速安装

Windows（推荐方式）

  1. 下载预构建安装包（⚠️ 尚未签名，需手动允许）： 从 GitHub Releases 下载 Sentient-Setup-*.exe
  2. 运行安装程序（安装给当前用户，无需管理员权限）
  3. 启动后按引导选择模型

从源码安装（Windows / macOS / Linux）

需要：Python 3.12 · uv · Node 22

git clone https://github.com/existence-master/Sentient.git && cd Sentient

# 创建 Python 虚拟环境
uv venv .venv --python 3.12

# 安装核心依赖（含语音支持）
uv pip install --python .venv/Scripts/python.exe -e ".[voice]"
# macOS/Linux: uv pip install --python .venv/bin/python -e ".[voice]"

# 安装桌面 UI
cd desktop && npm install && npm run dev

Ollama 本地模型准备（如用免费本地模型）

# 安装 Ollama（https://ollama.com/download）

ollama pull qwen3:8b          # 主模型，约 8GB 显存或 16GB RAM
ollama pull nomic-embed-text  # 向量嵌入模型

# 如需视觉能力（看图问答）
ollama pull qwen2.5vl:3b     # ⚠️ 需 vision 支持的模型

云端 API Key 配置

启动后在 Settings → Models 粘贴你的密钥，支持： - Anthropic · OpenAI · Gemini · OpenRouter · Nous Portal - ChatGPT Plus/Pro（通过官方 OAuth） - 密钥存系统 Keychain，不落文件

§4 核心用法

基本对话（5 分钟上手）

  1. 启动 Sentient 桌面应用，完成初始设置（回答几个关于你的问题 + 选择模型）
  2. 对话示例：
# 天气查询（Sentient 会自动调用天气工具）
"北京这周末天气怎么样？"

# 记忆（告诉它，它会记住并主动关联）
"我姐姐 Anika 下个月要搬去柏林了"
# 第二天可以问："Anika 搬家的事准备得怎么样了？"

# 任务调度
"每个工作日早上 9 点，帮我总结未读邮件"
# Sentient 会起草计划，你批准后按定时执行

# 价格监控（Watcher）
"这个耳机价格降到 250 元以下时告诉我"
# Sentient 写一个小脚本定期检查，价格变化时才唤醒 AI

语音交互

# 开启"Hey Sentient"唤醒词（Settings → Voice）
# 或直接点击麦克风图标进行语音输入

# 本地语音识别全程在本地处理，不上传

设备配对

# 手机配对：Settings → Devices → Add a device
# 打开"Allow devices on my Wi-Fi"，扫描二维码

# Telegram 接入：
# 1. 在 @BotFather 创建一个 Bot，获得 token
# 2. Settings → Devices → Messaging apps → Telegram，粘贴 token
# 3. 向你的 Bot 发送配对码

Skills（自定义技能）

# Sentient 完成实际工作后会写出可复用的 Skills
# 出错时会提出修复建议（以 diff 形式展示）
# 你审批后才会生效

MCP Server 接入

Sentient 支持任意 MCP Server，连接后在 Tools 中可用。配置方式：

# 在 Settings → Integrations 添加 MCP Server
# 支持的 MCP 工具在聊天中直接以 tool card 形式展示

§5 典型适用场景

场景 说明
隐私敏感任务 医疗、法律、财务类对话，数据不离开本机
长时后台任务 定时邮件摘要、价格监控、定期报告生成
本地模型免费用 用 Ollama + qwen3:8b，零 API 成本跑完整助手
多设备联动 手机/眼镜看通知、语音指令、位置共享
开发者自定义 基于开源架构扩展自己的 Agent + 设备协议
MCP 生态接入 连接 Notion/GitHub/Slack 等，通过统一界面管理

§6 坑与注意

⚠️ 重要工程坑

  1. Windows 安装程序未签名：系统会显示"Windows 已保护你的电脑"，需点"更多信息 → 仍然运行"。这是 alpha 阶段临时状态，预签名版本随首个公开版发布。

  2. Ollama 必须先启动：首次运行本地模型前，需确保 Ollama 已在后台运行（ollama serve 或启动 Ollama App）。若"Sentient says Ollama isn't running"，先启动 Ollama 再点 Check again。

  3. 本地模型响应慢：笔记本上的本地模型（qwen3:8b）含工具调用时响应约 15–45 秒；云端模型数秒内返回。关掉其他占用显卡的应用可改善。

  4. 并非所有模型都支持工具调用：qwen3:4b 等旧款小模型无法使用工具，Sentient 会正常回答但不能调用外部能力。README 建议至少 qwen3:8b 或更大模型。

  5. 视觉模型需单独选择：若选用的模型不支持看图，问"这张图里有什么"会失败。需在 Settings → Models 的 Vision 角色中选一个支持 vision 的模型（如 ollama_chat/qwen2.5vl:3b）。

  6. 记忆需人工审核：来自外部内容（邮件/网页）的记忆会进入 Memory → Review 待你批准，不会被直接使用，防止污染。

  7. "Local only"模式是真正的隔离：在模型菜单切换到"Local only"后，Sentient 会拒绝任何云端模型请求，即使备份模型或聊天专用模型设置过也一样——完全不出本机。

  8. macOS / Linux 无安装包：当前需从源码运行（见 §3），有一定技术门槛。

  9. WhatsApp 非官方产品：通过 WhatsApp Web 协议接入，WhatsApp 可能封号，官方未认证。

  10. Claude Code 集成为实验性质：开启后 Sentient 会调用本机 Claude Code 程序，用你的 Claude 登录发送对话——是 Anthropic 的官方产品，但集成方式非官方。

安全边界（来自 PRIVACY.md）

  • Sentient 主动问过你之前，不会发送、删除、购买或运行代码
  • 代码在沙盒中运行，无你的密钥权限
  • 终端命令默认关闭，需手动开启并指定允许目录
  • 禁止执行的命令（无论你怎么设置）：格式化磁盘、关机、删除整个注册表/驱动器
  • 照片/截图需你明确同意才会发送给模型
  • 麦克风仅在"正在录音"提示条显示时工作（最长 2 分钟）

§7 与同类对比

维度 Sentient Ollama（单独用） OpenAI Assistant API LangChain Agent
部署位置 本地 + 可选云 完全本地 完全云端 可本地/云端
个人记忆 SQLite 本地，强隐私 无 会话级 需自己接
主动任务/定时 原生支持 无 需额外调度 需自己接
语音/Wake word 原生支持 无 无 无
MCP 生态 支持 无 无 部分支持
设备配对（手机/眼镜） 原生开源协议 无 无 无
安装难度 中（Windows 有安装包） 低 低 高（需开发）
许可证 AGPL v3 MIT 专有 Apache 2.0

核心差异： Sentient 不是另一个模型运行时，而是一个把 AI 能力（对话+记忆+任务+语音+设备）整合进一个本地可个人部署的助手的完整框架。相比纯 Ollama，Sentient 多了任务系统、记忆管理、MCP 和设备协议；相比云端助手，它多了数据主权。

§8 一句话推荐结论

如果你想要一个数据完全在自己手里、功能完整（记忆+任务+语音+设备）且支持任意模型的个人 AI 助手，Sentient 是目前开源生态中集成度最高、最接近"完整产品"的选择——v3 alpha 已可从源码运行，Windows 安装包开箱即用。

⚠️ 存疑标注：qwen3:8b 的工具调用能力基于 README 描述；具体哪些工具调用场景实际可用，建议以仓库最新 README 为准。macOS/Linux 从源码安装的具体依赖版本以 docs/DEVELOPING.md 为准。