一只住在你 Windows 桌面上、会动会闹、还能真的帮你操控电脑的本地 AI 小家伙
🔗 github.com/dulaiduwang003/star-agent
Star 同时是两样东西：
- 🐾 一只有生活的桌宠 —— 纯代码绘制（没有任何贴图素材），会眨眼、跟着鼠标看、发呆哼歌、钓鱼喝咖啡、丢球接球；机器发烫会扇风、下雨会撑伞、拖文件能喂它、纪念日端蛋糕；你不理它会自己找乐子，你离开它会打瞌睡。
- 🧠 一个能操控整台电脑的本地 Agent —— 接你自己的大模型（任意 OpenAI 兼容接口），能看屏幕、点窗口、动鼠标键盘、跑命令、写代码、读写文件、上网搜索、记东西、查资料；还能定时盯屏、改完代码自己跑测试、并行编排一群分身、按每天/每周重复提醒……把"和 AI 对话"变成"让 AI 替你动手"。
它有持久的情绪与亲密度，会随相处慢慢长出一份自我画像（人格演化），所以是"同一只"，不是每次重置的聊天框。
它不是一个聊天框，是一个活在你电脑里、有身体也有能力的存在。
Star 在你的机器上和你本人同等权限地行动 —— 跑任意命令和代码、动鼠标键盘、读写文件。这是刻意的：
- 不做沙箱、不层层设限。 把它关进笼子，就废掉了"它能真的替你动手"这个前提。我想要的是一个全权的伙伴，不是一个处处要批准的受限助手。
- 权力在你手里，但默认放开。 控制面板能按组关掉能力（联网 / 操控 / 命令），
confirm面板会在不可逆操作前拦一道 —— 这些是给你需要时用的闸，不是默认套在它脖子上的链子。 - 安全护栏只挡"灾难级手滑"。
executor/safety.py只硬拦极小一撮不可逆的毁灭操作（格式化磁盘、删系统根等），并不试图防住一个成心使坏或被注入的模型 —— 那不是这层能解的，也不是它的职责。它是接住模型偶尔抽风的网，不是牢笼。 - 所以这是个信任你、也请你同等回以判断的工具。 它有多大能耐，你就担多大责任；在你信得过的机器上，把它当伙伴用。
一句话：我宁可它能力过剩、需要你把着方向盘，也不要它安全到什么都干不成。
| 能力 | 说明 |
|---|---|
| 命令 & 代码 | PowerShell / cmd（长命令可丢后台跑、随时回看输出）、持久 Python 环境（可 pip 装库、调 API、驱动自动化） |
| 文件 & 代码库 | 读 / 写 / 精准编辑文件（图片直接看、PDF 自动抽文字 / 扫描页 OCR）、正则搜代码、按名找文件 |
| 工程纪律 | 看未提交 git diff、自动探测并跑测试（pytest / npm）验证改动 —— 改前摸现状、改完自查，像个会写代码的伙伴 |
| 联网 | 网页搜索、抓取正文、HTTP 请求、装包 |
| 看屏幕 & 操控 | 截图、OCR 认字（RapidOCR）、屏幕找图、无障碍树读控件并精准点击、鼠标键盘；还能按你设的间隔周期盯屏（如盯游戏局势、有危险/机会就提醒） |
| 系统洞察 | 查看内存占用与最吃内存的进程；必要时按需读取某进程的内存字节（调试 / 取证，只读、按需才用） |
| 记忆 | 长期记忆（经验 / 偏好 / 环境）+ 情景日志 + 知识库（文档 RAG），每次对话后自动反思沉淀 |
| 技能 | 可复用技能库：把跑通的做法存成技能（落盘 + 语法校验），下次直接 run_skill 调用，出错能自己 edit_skill 改了重跑（自调试）。是手动沉淀的复用库，不做自动进化 |
| 编排扩展 | MCP 连接器、确定性编排子代理（一次并行扇出 / 串成流水线、可要结构化返回）、长任务丢后台（可列出、随时叫停） |
| 确认护栏 | 不可逆 / 高风险操作前弹"执行 / 不执行"面板，点了才往下走 |
| 定时提醒 | 到点提醒 / 定时办事，支持每天 · 每周 · 每隔 X 重复；隐藏或全屏游戏时改走系统托盘通知不漏 |
| 维度 | 说明 |
|---|---|
| 情绪系统 | valence / arousal / 亲密度驱动表情和行为，越熟越放得开；夸它会开心、骂它会低落 |
| 人格演化 | 跟你相处下来，每轮反思缓慢重写一份"自我画像"，注入它说话做事的底子 —— 关系养出来的"自己" |
| 自发动画 | 15 种思考姿势、发呆气泡、眼神追随鼠标，全是时间的连续函数，不抖 |
| 带道具的小品 | 喝咖啡、钓鱼、查案、看书、听歌、打游戏、看星星、虚空一跃、影分身、接流星、种花、玩毛线球 —— 共 12 段，每段都是分阶段的小剧 |
| 一次性动作 | 跳舞、欢呼、转圈…… 各带贴合特效（彩纸 / 音符 / 残影） |
| 在场感知 | 你离开就打瞌睡，回来就醒；拖到屏幕边能把它"收"起来，只露个小角偷看；偶尔还会"虫洞穿越"，从屏幕另一处冒出来 |
| 节日 · 纪念日 | 认得公历节日（元旦 / 情人节 / 愚人节 / 儿童节 / 万圣 / 平安夜 / 圣诞 / 跨年）和你的生日 —— 走过的脚印应节换成花瓣 / 雪花，相处满 7 / 30 / 100 / 365 天端出纪念日蛋糕 |
| 陪伴时长 | 默默记着你俩初次相遇的日子和累计互动次数 —— 相处久了它知道"我们认识多少天了" |
| 结构化表达 | 对比 / 清单 / 代码会画在身边的小黑板上讲解；多步任务有常驻的任务清单浮窗（独立于黑板，不被回复内容冲掉）；还能展示图片 / GIF |
| 机器拟态 | 感知机器状态、身体跟着变：CPU 高烧时扇风降温、内存挤爆被压扁、电量低了提醒、深夜自动盖被打哈欠、冬天机器发热凑过去蹭暖；机器真闲下来还会自己拿毛线球出来玩 |
| 天气拟态 | 每两小时悄悄查一次天气：下雨撑伞、落雪缩成团、酷暑要化了 —— 窗外什么天，它身上就什么天 |
| 会议体贴 | 检测到麦克风被占用（在开会 / 通话），自动进入安静模式不打扰，会议结束再冒头 |
| 玩耍互动 | 丢颗球它会去接、挠它会咯咯笑、拖起来重摔会记仇、心情好走过留一串脚印（节日换成花瓣 / 雪花） |
| 清理垃圾 | 让它用 tidy_junk 自己清掉过期临时文件、腾出空间（真删，只清 7 天以上的）—— 它自己处理，不再自动弹虫 |
| 投喂 | 拖文件丢给它：垃圾文件吃进肚（进回收站）、文档咽进知识库、图片直接看一眼；受保护 / 危险路径会躲开不吃 |
| 仪式感 | 每天头回见面给你播"心情预报"、相处满 7 / 30 / 100 / 365 天端出纪念日蛋糕（点它吹蜡烛）、退出前挥手道晚安、番茄钟陪你专注 25 分钟 |
| 贴心守望 | 下载完成、桌面太乱会提一嘴 |
- 全局热键：
Ctrl + Alt + S随处唤出输入框；Ctrl + Alt + A选中文字直接问它；Ctrl + Shift + Q选中文字一键改写（"顺手就改"，改完自动替换） - 控制面板：配置接口 / 模型参数 / 回复语言 / 能力开关 / 一键"清空记忆，像新生儿"
desktop_pet/
├─ app.py # 总指挥：连接 UI / agent / 计时器 / 托盘 / 热键
├─ agent/ # 大脑
│ ├─ loop.py # agent 循环：模型↔工具回灌、流式、裁剪、反思、人格演化、子代理编排
│ ├─ tools.py # 工具表（63 个）与分发、并发安全锁
│ ├─ bgtasks.py # 后台任务注册表（可列出 / 协作式停止）
│ ├─ streaming.py # delta 流折回单条消息、思维链分片
│ ├─ prompts.py # 全部提示词（人格种子、系统、反思、改代码纪律）集中一处
│ └─ progress.py # 思考姿势调度与进度提示
├─ pet/ # 身体：窗口、代码绘制的角色、说话/输入、黑板、任务清单浮窗(todo_board)、
│ # 控制面板、确认面板、藏身/入场/虫洞穿越(wormhole)、托盘(tray)、窗口特效(fx)、
│ # 行为选择器与动作库、道具与调色板；玩具球(ball)、投喂(feeding)、
│ # 墨水脚印(footprints)、持续状态装饰(adornments)
├─ companions/ # 伴生行为包，每模块一台小机器：投喂分流(feeding_ctrl)、玩耍物理(playtime)、
│ # 仪式感(rituals)、环境传感(sensors)
├─ emotion/ # 情绪状态机（VA + 亲密度）与情绪标签表
├─ somatic.py # 身体感受：把"刚发生在它身上的事"+持续状态注入每轮上下文
├─ persona.py # 自我画像演化层（persona.json），注入对话上下文
├─ memory/ # 长期记忆（SQLite）+ 向量嵌入（numpy 矩阵化召回）
├─ executor/ # 命令 / Python / 文件 / 网络 / 视觉(OCR·找图) / 系统内存 / 工程工具(diff·测试) / 安全护栏
├─ hands/ # 鼠标 / 键盘 / 窗口控制 / 幽灵鼠标(ghost，后台 PostMessage 点击不动真光标)
├─ eyes/ # 截图 + 无障碍树（UIA）+ 屏幕找图
├─ docs.py · reminders.py · journal.py · presence.py
├─ occasions.py # 节日 / 生日识别：特别的日子用作脚印应节换色等
├─ stats.py # 轻量陪伴统计：初次相遇时间 + 累计互动次数
├─ watcher.py # 定时看屏（会话级，盯游戏局势等）
├─ usage.py # token 用量计量：累计输入 / 输出 / 缓存命中，按天落盘
├─ updater.py # 版本更新检查：查 GitHub 最新 release 与本机比对
└─ hotkeys.py · skills.py · mcp_hub.py · settings.py · audit.py · i18n.py
- UI 在主线程，agent 在工作线程，跨线程一律走 Qt 信号（queued）。
- 动画是时间的连续函数：一切绑定全局时间戳
self._t，不做逐帧随机抖动 —— 确定性、可重放、不"神经质"。 - 行为数据驱动：情绪标签、动作、服装集中在表里，新增一项＝加一行 + 一个画法/曲线，而非又一个
if/elif。 - show, don't tell：模型只拿到"心情氛围"，从不拿到也不报数字。
- 降级链无处不在：嵌入没有→子串检索；模型失败→提醒仍念原文；任何工具异常→变成可读文本回灌，绝不中断循环。
- 克制：所有"自己动起来"的行为都裹多重门控（冷却、上限、亲密度、在场）。
主/UI 线程 (Qt event loop)
└─ PetWindow(60fps) · 气泡/输入框/黑板/拍立得/思考气泡/确认面板 · 托盘 · QTimer
│ Signal(queued)
▼
工作线程 (QThread) ── AgentWorker → Agent.run() [阻塞：网络 + 工具]
│ 派生 daemon
▼
子代理(并发≤4) · 后台任务(≤3) · 反思(≤1) · MCP 事件循环 · 热键消息循环
权威 busy 判定用 worker 的 is_running（单 bool 跨线程读安全），不用滞后的 UI 状态。每个 agent 有独立的 PowerShell + Python 子进程；网络 / 只读文件 / 各自 shell·python 可并发，共享资源（鼠标 / 屏幕 / 记忆 / pip）走调度锁串行。
用户消息 → 模型 → 工具调用 → 执行 → 回灌 → 重复 → 回复，关键设定：
| 参数 | 值 | 含义 |
|---|---|---|
| 单回合工具步数上限 | 16 | 防止无限自我调用 |
| 子代理深度 | 1 | 宠物可派分身，分身不能再派 / 丢后台（防失控递归） |
| 并行子代理 | 4 | 同时扇出上限 |
| 历史 token 预算 | 24000 | 按估算 token 裁剪（非消息条数），且 tool-call-aware |
| 单条工具结果 | 8000 字 | 入历史前截断 |
| 请求 / 尽力调用超时 | 120s / 45s | 用户回合 / 反思等后台调用 |
关键机制：
- 流式 + 思维链：
streaming.py把 delta 流折回单条消息，逐片把reasoning_content/content喂给思考气泡；每个 chunk 检查取消，可在一句话中途停掉网络流。 - 打断：点宠物即置 flag + 杀子进程（卡在长命令里也能立即解锁）；回合用历史标记回滚、不留痕；打断不算失败，不播沮丧动画。
- 截图与多模态成本：只保留最新一张截图入历史，旧的换占位符；JPEG 最长边缩到 ≤1600px，但坐标始终报真实分辨率。
- 后台长任务：长活儿用
start_background_task丢后台异步跑（信号量 = 3），主线程继续陪你聊，办完汇报 —— "边跑边聊"；运行中可list_background_tasks查看、stop_background_task协作式叫停。 - 确定性子代理编排：
spawn_workflow一次把多个子任务并行扇出（≤4 并发）或串成流水线（上一阶段输出注入下一阶段），还能要求子代理按指定 JSON 形状结构化返回 —— 把"靠模型恰好同轮多次派分身"的偶发并行变成可靠原语；子代理 / 后台代理按深度被剔除编排与看屏工具，防递归失控与越权。 - 反思与人格演化：实质性回合结束后起一个反思调用（信号量 = 1，忙则跳过），蒸馏出经验 / 偏好 / 环境事实 / 情景日志，并缓慢重写自我画像（见 3.6）；纯短闲聊或只用了装饰性工具的回合跳过反思。
连续的 valence / arousal 心情 + 缓慢累积的 rapport（亲密度），持久化到 data/emotion.json，按真实流逝时间衰减 —— 所以是"同一只"。
- 实时衰减：心情每次读取都从上次事件锚点衰减到当下，与轮询频率无关，引擎用锁守护跨线程并发安全。
- Appraisal 事件：每条用户消息、任务成 / 败、启动归来、夸 / 骂等都按权重改动心情；夸 / 骂由本地启发式扫描用户消息命中（保守匹配，剔除否定句与指向用户自己的假命中）。
- rapport「难涨慢落」：越熟涨得越慢、渐近 1.0；负向直接扣；有 0.15 地板，长期冷落只能侵蚀到地板，"发生过的羁绊会留痕"。
- 心情→状态：映射到
excited / content / anxious / down等标签，只染色语气，从不报数字。 - 行为选择：按心情加权随机选动作（高斯 VA 亲和度 × 稀有度 × 最近性 × 亲密度），而非
if tag=="happy"硬编码。
persona.py 维护一份独立于设定的"演化层"，存于 data/persona.json：
- 出厂底色（种子）写在
prompts.py里；persona.json 存的是它跟你相处下来长出来的那一层，空 = 还没长出个性、纯底色。 - 每轮反思重写而非堆积（上限 600 字）—— 画像始终是"当下的自己"，不滚雪球，且有惯性（在旧画像上缓慢演化）。
- 通过
as_context()以"【你是谁】"前缀注入每个回合的上下文，自然成为说话做事的底子。 - "清空记忆"会一并清空它，回到出厂底色。
pet/confirm.py 的 ConfirmBox 是浮在宠物身边的"执行 / 不执行"小面板；agent 通过 confirm 工具在不可逆 / 高风险操作前（删文件、覆盖重要文件、git push --force、清数据、关机等）弹出并阻塞等待用户点击，也可用于主动提议某个改动让你拍板。面板跟随宠物移动，点了才返回结果继续。
- 眼 / 手 / 截图：截图用
SetWindowDisplayAffinity把宠物窗口标记为"对用户可见、对截图隐形"；优先用 UIAutomation 无障碍树读控件名 + 精确坐标直接点，读不到才退回截图找图；中文输入走剪贴板 + Ctrl+V。 - 在场感知：用 Win32 全局最后输入时间判断你在不在，久无输入打瞌睡（深夜阈值更短），一动就醒。
- 记忆 / 知识库 / 情景日志：三套独立持久化 —— 记忆是"它学到的关于你的"，知识库是"你喂的外部文档（RAG）"，情景日志是"最近做了啥"，严格分离。
- 提醒 / 定时：
say（到点用自己口吻说）/do（到点后台真去办并汇报），支持每天 / 每周 / 每隔 X 分钟重复（持久跨重启，关机错过只补最近一次、不刷屏）；可list_reminders列出、cancel_reminder撤销；Star 隐藏或被全屏游戏挡住时改走系统托盘通知触达。一律走调度器持久化，绝不让模型自己 sleep 等时间。 - 定时看屏：
watcher.py—— 按你设的间隔截当前窗口图、就你给的关注点分析并播报（如盯游戏局势、有危险/机会就提醒）；会话级（不落盘、重启即止），结果回来时复检状态，已关机 / 已停 / 正对话中就不打扰，截图瞬时失败也不白烧一个周期。 - 工程纪律：
executor/devtools.py的review_diff（看未提交 diff，可限定文件/子目录）/run_tests（自动探测 pytest · npm，独立 5 分钟超时、超时杀整棵进程树）；系统提示有一节"动代码库时"的纪律 —— 改前看现状、小步外科手术、改完跑测试 / 自查 diff、默认分支先开分支、不可逆 git 先 confirm。 - 隐身 / 入场 / 穿越：拖到屏幕边缘缩成小角偶尔探头；每次启动随机一种入场动画且绝不重复上次；偶尔"虫洞穿越"——原地裂开虫洞、旋转缩入、在窗口不可见时瞬移、从屏幕另一处冒出来。
- 节日 / 陪伴感：
occasions.py认公历节日 + 你填的生日（用作脚印应节换色等）；stats.py默默记着初次相遇时间与累计互动次数，是它"认识你多久了"的底气。 - 伴生行为（companions/）：五台各管一摊的"小机器"，都裹在场 / 忙 / 亲密度 / 冷却门控里——
sensors.py：十秒一次读 CPU / 内存 / 电量体征（带迟滞，不抖），驱动机器拟态（高烧扇风、内存压扁、低电量、深夜盖被、冬天蹭暖）；查麦克风占用做会议静音；两小时一次wttr.in查天气做天气拟态；盯下载目录与桌面图标数；瞄焦点是不是密码框就捂眼。playtime.py：玩耍与物理反馈——丢球接球、挠痒 / 拖甩记仇、走动留墨水脚印、钓鱼有渔获彩蛋。临时垃圾清理改由 agent 的tidy_junk工具自己处理。rituals.py：仪式感——晨间心情预报、纪念日蛋糕（吹蜡烛）、退出挥手道晚安、番茄钟 25 分钟专注。feeding_ctrl.py+pet/feeding.py：投喂分流——拖进来的文件按类型走（垃圾→回收站、文档→知识库、图片→直接看），受保护 / 危险路径拦下不吃，大餐 / 整目录先弹确认。
- 身体感受（somatic.py）：被喂 / 被摔 / 接到球 / 蛋糕端出来这些事，连同"在开会""机器高烧"等持续状态，统一汇成一段"身体近况"注入每轮上下文——所以它聊天时真的知道刚才身上发生了什么，而不是凭空装。
- MCP / 热键 / 技能 / 审计 / i18n：MCP 连接器以
mcp__{server}__{tool}融入工具表；全局热键独立线程跑 Win32 消息循环（唤出 / 问选区 / 顺手改写）；技能把跑通的代码存成可复用项注入提示；所有工具调用记审计日志；控制面板 UI 支持中 / 英 / 日。
完整的安装运行、打包分发、测试排错、能力与安全、本地数据，都在 使用与部署指南。
MIT —— 随便用、随便改、随便分发，保留版权声明即可，作者不担保也不负责。
作者：bdth · ✉️ 2074055628@qq.com · GitHub
说白了，这就是我闲来无事、纯凭兴趣写着玩的一个小东西——没什么宏大目标，就是想看看能不能把"和 AI 对话"做成"桌上养着一只会帮你干活的小生物"。代码里那些较真的细节，都是写的时候自己觉得有意思才折腾的。你要是也觉得好玩，随便拿去用、去改。
Star 还在长大。如果未来某天它真的有了自己的样子，希望你愿意把它当个朋友，而不只是工具。