用途
编程智能体（coding agent）在一次请求中会读取大量文件、编辑若干文件、运行测试并反复重试，聊天记录滚动而过，diff 分散在多个文件里。dotpals 在编辑器旁保留一份实时、通俗易懂的记录，让你随时回答：它改了什么、运行了什么、是否成功、是否修复了自己弄坏的东西、当前代码是否经过测试、现在正在做什么、今天完成了什么。其核心原则是：一切结论来自文件变更与命令/测试输出本身的证据，而不是智能体的自述。全部数据留在你自己的电脑上，工具为免费、开源。
主要能力
- 记录变更：列出每个被编辑、创建或删除的文件，一键查看 diff。
- 记录命令：每条命令及其输出、耗时和 ✓/✕ 状态；失败后重试会标注“第 2 次修好”或“3 次尝试后仍失败”。
- 让智能体修复失败测试（Claude Code，默认开启）：测试失败时立即告知原因（如“expected 3, got -1 (test/math.test.js:5)”），当它试图结束、提交或推送时把它退回去修复，每次请求最多退回两次，之后可停止并告知用户。不修改代码的请求（如“跑一下测试告诉我结果”）只报告失败；Claude 修改前就已失败的测试只报告、不强制其修复。输出被截断无法判读时会重新运行测试，仍无法判读则请用户查看。
- 识别假通过：若测试变绿只是因为删除了断言、添加了跳过或改了预期值，dotpals 会捕捉到并把 Claude 退回、同时告知用户。无测试的项目不会被阻塞。可在设置或灵动岛齿轮中关闭。
- MCP 查询：
dotpals mcp让 Claude Code、Codex、Cursor 等助手通过check_my_work、ready_to_merge、today、recap、risky_steps等查询真实经过与证据。 - 故事化呈现：每次请求呈现为“改动 5 个文件 +42 −7 · 测试失败两次后通过 · 已提交并推送”这样的几个章节，而非上百条工具调用。
.env变更、强制推送、同一命令连续失败 3 次、两个智能体编辑同一文件、未测试就改代码等会被标记。 - 双智能体冲突提示：某智能体将要修改另一个智能体几分钟前改过的文件时，Claude Code 会先询问用户，或让 Claude 重新读取。其他智能体无法事先拦截，但灵动岛与伙伴会实时告知。
- 会话交接：Continue in ▾ 可将会话交接给 Codex、Claude Code 或 Gemini CLI，在同一项目的新终端中附上任务内容、已完成工作、测试状态与剩余事项；也可复制该说明粘贴到任意位置。
- 与智能体聊天（可选，默认关闭）：在伙伴处向智能体输入文字并就地处理权限请求与提问；目前支持 OpenCode，Claude Code 等后续支持。
- 重试关联：步骤失败后重试会被关联显示，点击可跳转到对应尝试；仪表盘可粘贴步骤 ID（toolu_…）打开。
- 是否测试过：每个会话一行显示“测试通过 · 48 passed · 7:08 PM，在最后一次改动之后”或“3 个文件在 7:08 PM 之后有改动”“智能体未运行测试”，并说明结果来源（各测试框架自身摘要，或仅退出码）。零测试或只有跳过会显示为“测试不明：没有真正运行测试”，绝不显示为通过。可选由本机 Laya（需 Python 3.10+，设置中一键安装或
dotpals laya）或云端 TypeSafe 的 Jev（默认关闭）复核不明结果。只有智能体运行的测试才计数。 - 简单/详细模式：默认为简单模式，每次请求用一句话概括，只显示重要警告；详细模式显示每个章节，小步骤折叠。
- 灵动岛：屏幕顶部的小岛，显示所有智能体、正在编辑文件的实时 diff、计划（如“2/4 · Detecting the system setting”）、上下文窗口以及 Claude 和 Codex 用量限额；智能体需要你时自动打开，可用键盘允许或拒绝。隐藏伙伴后由它接管；按“–”最小化。
- 上下文与限额：会话上下文窗口将满时伙伴会“担心”，压缩后“欢呼”；用量条显示 5 小时与每周限额及重置时间（Claude 需运行一次
dotpals statusline）。 - 仪表盘：查看每个会话的请求、文件与完整日志，支持搜索与导出 Markdown/JSON；还显示每日请求数、按项目用时和已连接智能体的实时视图；设置（伙伴形象、声音通知、历史保留时长或清除）由伙伴与仪表盘共享。
- 历史：重启后保留，保存在本机
~/.dotpals/history.json，默认 7 天。 - 通知与声音：智能体需要确认时提示音，完成时铃声，离开时桌面通知。
- 覆盖所有会话与智能体：所有 Claude Code 会话（包括安装 dotpals 之前启动的）都会显示，与 Codex 及任何接入的智能体并列。小模式下每个智能体各有一个伙伴，上方圆条标明身份。
- 自定义伙伴：可选择身体（round、boxy、fluffy、pointy、heart 或 frog）、眼睛（dots、button、googly、pixel、visor 或 shades）、头顶（cat ears、horns、antenna、sprout、sparkle、bow、crown 或 beret）、颜色和名字，组合数以千计；可在自己的应用中通过
registerCustom({ name: 'Pip', shape: 'bean', eyes: 'googly', top: 'crown', color: '#16c6ae' })和<dot-pal character="custom">调用。内置九个角色，包括挂在丝线上的蜘蛛 Webby，智能体完成时会弹跳下来。
使用方式
Windows、macOS 或 Linux 上一条命令安装；也可直接从 GitHub 安装：npx --allow-git=all github:rikinshah787/dotpals setup。安装程序会把桌面伙伴装入 ~/.dotpals，下载约 100 MB 的运行时（Electron，一次），在已安装 Claude Code 时添加其插件，自动识别已安装的 Codex，启动伙伴、开启“登录时打开”并打开仪表盘；需要 Node 20 或更新版本。安装时终端会询问伙伴形象、灵动岛、简单/详细、批准方式、测试复核（关闭、本机 Laya 或云端 Jev，密钥隐藏输入）等，可回车使用默认值或运行 setup --yes。常用命令：dotpals mcp、dotpals dashboard、dotpals statusline（--off 还原）、dotpals notch --auto | --off、dotpals laya。灵动岛有四档尺寸：无任务运行或离开 3 分钟时隐藏；智能体工作时显示为条；打开态 640 px 含 Now 与 Story 两个标签页。批准卡可点 Deny/Allow，或用 Ctrl+Alt+N/Y（macOS 为 ⌘⌥N/Y）。
适用场景
适合使用 Claude Code、Codex、Cursor、Gemini CLI 等编程智能体的开发者，尤其是关注“智能体声称完成但实际未通过测试”“测试被改绿”“多个智能体改同一文件”等情况时，用于验证工作是否真正完成、是否可合并，并快速生成站会或 PR 说明。
限制
工具为只读监控，不修改代码逻辑；测试复核的 Laya 需 Python 3.10+，云端 Jev 默认关闭；与智能体聊天目前仅支持 OpenCode；其他智能体无法在修改前被拦截；仅智能体运行的测试才计数。其余功能和平台细节资料未提供。
