dots-agent

一个会主动发现任务、主动积累技能的智能体。

包名 dots-agent,命令是 dots(装完就有)。两种用法:命令行,或者 Windows 桌面窗口。

安装

命令行

pip install dots-agent

国内镜像(清华、阿里等)同步新包有延迟,刚发布的几天可能报 No matching distribution found。加官方源即可:

pip install dots-agent -i https://pypi.org/simple

或者不装,直接在仓库里跑(两种方式命令都通用):

git clone https://github.com/duyongan/dots-agent
cd dots-agent
python -m dots serve

桌面版(Windows)

怎么打开

日常使用双击 dots.exe(或者桌面/开始菜单里的 dots 快捷方式)。装好之后它在:

%LOCALAPPDATA%\Programs\dots\dots.exe

dots-<版本>-setup.exe 只是安装器,装一次就行,不是日常打开方式。

安装

安装包由打包命令生成到 release/(该目录不进仓库):

release/dots-<版本>-setup.exe

双击安装。安装器是按用户安装,不需要管理员权限,默认装到 %LOCALAPPDATA%\Programs\dots。安装过程中可以改目录;会创建桌面快捷方式和开始菜单项。 卸载走 Windows 的「设置 → 应用 → 已安装的应用 → dots」。

安装包自带一份嵌入式 Python 和全部依赖(resources/runtime/),机器上没装过 Python 也能跑。

不想安装也可以直接运行 release/win-unpacked/dots.exe。它旁边必须保留 resources/ 目录(运行时都在里面),不能只把这个 exe 单独拷走。

自己打包:

cd desktop
bash make-runtime.sh      # 首次,或 dots/ 源码改动后
npm run dist              # 生成 release/dots-<版本>-setup.exe

在仓库里开发

cd desktop
npm start

开发模式不打包,直接用系统上的 Python;工作目录是仓库根,所以会读仓库根或 ~/.dots/ 下的 dot.toml。

快速开始

dots init --global         # 配一次,以后 cd 到哪都能敲 dots
dots doctor                # 体检一下
dots goal "把 inbox 里的东西整理成一份报告"
dots serve --web           # 常驻跑起来,同时开活动视图

--global 把配置写到 ~/.dots/,数据和 workspace/ 也跟着放那儿 —— 一份到处用,换个目录不用再 init。不带参数就是 dots init,只写当前目录, 那样每个目录都得配一次。

也可以不带子命令,直接进交互终端。里面直接打字就是和它说话, / 开头才是命令:

$ dots
dots> 工作区里现在有什么?帮我看看该先处理哪件事
      (它自己去翻文件,然后回你)

dots> /goal "把 inbox 整理成一份周报"     ← 交给后台慢慢跑
dots> /ls
dots> /exit

对话走的是同一个大脑、同一个工作区,但它不是目标:不进 dot ls, 后台 tick 也不碰它,所以不会算进你的目标队列。要让它后台跑,用 /goal。 它想在对话里做 ask 类动作(比如发邮件)时会当场问你 y/n,不走邮件审批。

每条命令都会重新读一遍配置,所以改完 dot.toml 不用退出来重进。

打开 http://127.0.0.1:8765/ 看它在干什么。

想先不配模型试一遍:

dots selftest              # 不联网、不调模型

桌面界面

一个窗口装下 dots 的全部日常操作:看它在干什么、给它派活、批准它想做的事、跟它说话。 不用开终端,不用背命令。它和命令行版共用同一份配置、同一个数据库、同一个工作区。

第一次启动前必须先有配置

这是最容易卡住的一步:

后端找不到 dot.toml 会直接退出,界面顶栏变成「后端已停」,所有按钮变灰。 此时连「生成全局配置」也点不动 —— 那个按钮要求后端已经就绪。

所以第一次使用,先在终端里生成一份全局配置:

pip install -e .          # 或按上面的方式安装 dots-agent
dots init --global        # 写到 ~/.dots/dot.toml
dots doctor               # 体检,确认模型、目录、数据库都没问题

dots init 会自动探测环境变量里的模型 key。没探到就手填 ~/.dots/dot.toml 的 [model] 段。

打包版查找配置的顺序:

1. %APPDATA%\dots-desktop\dot.toml(也就是应用的当前工作目录)
2. ~/.dots\dot.toml

你的数据跟着配置文件走:全局配置在 ~/.dots/,数据库和工作区也都在那儿。

启动过程

双击图标后:

1. Electron 先画窗口;
2. 拉起 python -m dots bridge;
3. 后端导入 langchain 那一整串依赖,约 10 秒;
4. 后端发出 ready,顶栏从「正在启动后端…」变成「值守中」。

这 10 秒里输入框和按钮是灰的。不是卡死。不要在这个时候狂点 —— 虽然界面会拦住, 但后端准备好之前发的命令会堆在管道里,顺序不可控。

如果后端起不来,顶栏显示「后端已停」,同时底部弹出输出面板,里面是 Python 的 stderr 尾部(常见的:「没找到配置」「ModuleNotFoundError」「API key 缺失」)。

界面总览

窗口从上到下五段:

┌────────────────────────────────────────────────────┐
│ 顶栏:dots  ● 值守中  每 60s 一轮  [停止]   [体检]  │
├────────────────────────────────────────────────────┤
│ 待批横幅(只在有事等你时出现)                       │
├────────────────────────────────────────────────────┤
│ 目标        │ 技能          │ 活动                  │
│ (三栏监控区)                                        │
├────────────────────────────────────────────────────┤
│ 对话                                                │
│ 你/它 的消息……                                      │
│ [ 说点什么…(回车发送)                        ]      │
├────────────────────────────────────────────────────┤
│ ▴ 全部命令(展开后是一整排中文按钮)                 │
└────────────────────────────────────────────────────┘

窗口最小 720×520。窗口高度不足 640px 时,命令抽屉会自动收起且把手不可点, 保证上面的内容不被挤没。

顶栏:状态与值守开关

后端状态:

顶栏中间显示:

• 每 60s 一轮:循环在跑。数字来自 [dot] tick_seconds。
• 循环已停:循环没跑,但后端还活着,你仍然可以手动「跑一轮」、聊天、点命令。

右边按钮:

• 停止:请求停下循环。如果它正跑着一个目标,不会立刻停 —— 要等这一轮结束。 按钮会一直是「停止」,直到后端推来 loop_stopped。急着关窗口也没事, 关闭时会先把没跑完的目标放回队列。
• 开始值守:重新启动循环。

循环默认在界面启动时自动开启。它的存在感就是「主动」:不用你喊,它每轮自己找活干。

顶栏最右边「体检」= dots doctor。逐项检查:配置文件、读配置、审批规则、依赖、模型、 工作区可写、数据库、事件源、审批通道、技能库、bot、成本上限。每项失败都会给一句 「下一步怎么做」。

待批横幅:它停下来等你

只有存在挂起审批时才出现,是整个界面唯一用琥珀色强调的地方。

⚠ a7f3 想发邮件给 alice:「周会改到周四」  (还有 2 个)
   a7f3 [批准] [拒绝]   b91c [批准] [拒绝] …

• 摘要会尽量说人话:send_email 显示收件人和主题,run_shell 显示命令, 其它动作显示工具名。
• 每个审批有唯一编号(token)。点「批准」= dots approve <token>, 「拒绝」= dots reject <token>。
• 决定写进 approvals 表,下一轮 tick 自动续跑对应目标。邮件回复和这里点按钮 走的是同一条路径。
• 一直不批:超过 [approval] timeout_hours(默认 72 小时)自动按拒绝处理。 这比无限等待好 —— 一个永远等不到回复的审批就是一个悄悄卡死的目标。

哪些动作需要批,由 dot.toml 的 [approval.rules] 决定:

[approval.rules]
send_email = "ask"     # 挂起,等人批
save_skill = "allow"   # 直接执行
run_shell  = "deny"    # 永不执行

没写到的动作一律 ask(默认从严)。

目标面板

目标 = 一件要它做的事。每行显示:

七种状态:

「待复核」值得单独说:一个没有证据的结论没法核对,所以不会直接算完成。

面板按钮:

「新建目标」走的是 bridge 的原生命令,不是 CLI:不会在输出面板里打印 「跑起来:python -m dots serve」这种在界面里很误导的提示。它固定交给默认 bot dot。

目标列表最多显示最近 60 条,多了会静默截断。

技能面板

技能是 agent 干活时自己总结出来的可复用流程,存在工作区里,每份是一个目录, 里面有 SKILL.md(YAML frontmatter + 正文)。

面板每行显示技能名和一句话描述。技能库是渐进披露的:只有「名字 + 描述」每轮会进 系统提示,正文等真用到时才读。所以描述被硬性限制在 60 字符,超出部分每轮都会被截断。

每行右侧还有两个小按钮:

• 看:dots skill show <名>,在输出面板里显示 SKILL.md 全文。
• 删:dots skill rm <名>,删除整个技能目录。会弹确认,确认按钮写「删掉」。

技能库为空时,面板会提示:它干活时会自己攒,「学习」也能喂材料。

活动面板

完整流水:收了事件、建了目标、被哪条规则拦下、什么时候跑完、循环启停、错误栈。

数据来源有两份,合并后按时间排序,最多显示最近 120 行:

1. 数据库 audit 表的快照(最近 60 条);
2. 本次运行期间后端实时推来的 log / fatal / loop / 协议错误(最多缓存 300 条)。

每行是 时间 | 类型 | 详情。出问题时先看这里。

对话区

直接打字就是跟它说话,回车发送。它用的是同一个大脑、同一个工作区:让它读文件、 查资料、写东西,它会真的动手,不是只描述打算怎么做。

特点:

• 不是流式的:发送后显示「正在想…」,慢模型下可能要等十几秒才出整段回答。
• 有上下文:对话用固定的 thread_id = "chat",checkpoint 存在 dot.db 里, 关掉应用再打开,之前的对话还在。
• 和后台目标是两条线:聊天不占目标队列,后台 tick 也不碰它。要让一件事在后台慢慢跑, 用「新建目标」。
• 界面里最多保留最近 300 条消息用于显示,更早的仍在 checkpoint 里。

聊天时它如果想做 ask 类动作,会当场弹窗,不走待批队列:

它想干这个
send_email
{ "to": "alice@example.com", "subject": "周会改到周四", ... }
[拒绝] [批准]

• 你在弹窗里做的决定只影响这一次对话。
• 拒绝之后它会记住:同一件事再做,它会引用规则告诉你「被拒了不要重试」。
• 最多等 10 分钟(600 秒)。超时按拒绝处理;如果你在超时后才点「批准」, 界面会明确告诉你「这个审批已经过期了,agent 早按拒绝处理了」,不会假装成功。
• 弹窗期间聊天线程阻塞等待,但读 stdin 的是另一条线程,所以界面不会卡死。

对话功能是懒启动的:第一次发消息才建图,要几秒钟。不聊天就不付这个成本。

命令抽屉:全部按钮

底部「▴ 全部命令」展开后,是 dots 的全部日常子命令。按钮上写中文,不写原始命令名; 鼠标悬停会说明它做什么,并带出对应的 dots xxx。

展开状态记在本地(localStorage),下次打开还是那样。

serve 和 bridge 不在抽屉里:常驻循环由顶栏按钮管;再起一个 worker 会抢同一个数据库。

几个按钮的细节:

• 生成配置:在当前工作目录写一份 dot.toml。打包版的当前目录是 %APPDATA%\dots-desktop,开发版是仓库根。文件已存在时不会覆盖。
• 生成全局配置:写到 ~/.dots/dot.toml,之后在任何目录都能用。
• 跑一轮:只跑一轮就退。循环正在跑时按钮置灰;即使绕过界面,后端也会因为抢不到 tick 锁而拒绝,避免两个 worker 同时写同一个 checkpoint 和事件表。
• 学习:创建的是 ready 目标,真正执行要等后台循环或手动 tick。 [skills] enabled = false 时命令会拒绝。
• 整理技能:真的会删文件和改文件;技能少于 2 份时不会创建目标。
• 批准 / 拒绝:只出现在待批横幅和行内,不出现在抽屉里(抽屉里没有编号可填)。

命令跑在独立的命令线程上,串行排队。一条在跑时点下一条,它会在后面等。 输出以流式事件推到输出面板,面板最终以应答里的完整输出为准。 界面给每条命令 180 秒超时;超时只是界面不再等,后端那条命令可能仍在跑完。

输出面板

命令输出从底部升起,覆盖在界面下方:

• 标题是按钮的中文名;
• 内容是流式追加;
• 跑完显示「退出码 0」或红色「退出码 N」;
• 复制:把全部输出放进剪贴板;
• 关闭:收起面板,不影响命令本身。

「新建目标」不产生输出面板内容(成功时静默,失败时弹面板说明原因)。

界面没覆盖的功能

界面只放了日常操作。下面这些仍然要用命令行(或 dots 交互终端):

交互终端里,/ 开头是命令(如 /ls、/goal "..."),裸文本是和 agent 说话, 和桌面版「对话区」是同一个能力。

网页界面(可选)

不想用桌面窗口,也可以走浏览器:

dots gui

它在本机 127.0.0.1 起一个页面并自动打开,四个页签:聊天、活动(目标/审批/流水)、 配置(模型预设 + API Key、事件源、SMTP、审批规则