duyongan / dots-agent

# dots-agent
一个会主动发现任务、主动积累技能的智能体。
包名 `dots-agent`,命令是 `dots`(装完就有)。两种用法:**命令行**,或者 **Windows 桌面窗口**。
## 安装
### 命令行
 [code] 
> 国内镜像(清华、阿里等)同步新包有延迟,刚发布的几天可能报
> `No matching distribution found`。加官方源即可:
>
> [code] 
或者不装,直接在仓库里跑(两种方式命令都通用):
 [code] 
### 桌面版(Windows)
#### 怎么打开
日常使用**双击 `dots.exe`**(或者桌面/开始菜单里的 `dots` 快捷方式)。装好之后它在:
 [code] 
`dots- -setup.exe` 只是**安装器**,装一次就行,不是日常打开方式。
#### 安装
安装包由打包命令生成到 `release/`(该目录不进仓库):
 [code] 
双击安装。安装器是**按用户安装**,不需要管理员权限,默认装到
`%LOCALAPPDATA%\Programs\dots`。安装过程中可以改目录;会创建桌面快捷方式和开始菜单项。
卸载走 Windows 的「设置 → 应用 → 已安装的应用 → dots」。
安装包自带一份嵌入式 Python 和全部依赖(`resources/runtime/`),**机器上没装过 Python 也能跑**。
不想安装也可以直接运行 `release/win-unpacked/dots.exe`。它旁边必须保留 `resources/`
目录(运行时都在里面),不能只把这个 exe 单独拷走。
自己打包:
 [code] 
#### 在仓库里开发
 [code] 
开发模式不打包,直接用系统上的 Python;工作目录是仓库根,所以会读仓库根或 `~/.dots/`
下的 `dot.toml`。
## 快速开始
 [code] 
`--global` 把配置写到 `~/.dots/`,数据和 `workspace/` 也跟着放那儿 ——
一份到处用,换个目录不用再 init。不带参数就是 `dots init`,只写当前目录,
那样每个目录都得配一次。
也可以不带子命令,直接进交互终端。里面**直接打字就是和它说话**,
`/` 开头才是命令:
 [code] 
| 输入 | 干什么 |
|---|---|
| 直接打字 | 和它对话。**记得上下文**,能接着追问 |
| `/命令` | 命令行那些命令,前面加个 `/`(见下表) |
| `/help` | 看全部命令 |
| `/exit` | 退出(Ctrl-D、Ctrl-C 也行) |
对话走的是同一个大脑、同一个工作区,但它**不是目标**:不进 `dot ls`,
后台 tick 也不碰它,所以不会算进你的目标队列。要让它后台跑,用 `/goal`。
它想在对话里做 `ask` 类动作(比如发邮件)时会当场问你 y/n,不走邮件审批。
每条命令都会重新读一遍配置,所以改完 `dot.toml` 不用退出来重进。
打开 http://127.0.0.1:8765/ 看它在干什么。
想先不配模型试一遍:
 [code] 
## 桌面界面
一个窗口装下 `dots` 的全部日常操作:看它在干什么、给它派活、批准它想做的事、跟它说话。
不用开终端,不用背命令。它和命令行版共用同一份配置、同一个数据库、同一个工作区。
### 第一次启动前必须先有配置
这是最容易卡住的一步:
> **后端找不到 `dot.toml` 会直接退出**,界面顶栏变成「后端已停」,所有按钮变灰。
> 此时连「生成全局配置」也点不动 —— 那个按钮要求后端已经就绪。
所以第一次使用,先在终端里生成一份全局配置:
 [code] 
`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 缺失」)。
### 界面总览
窗口从上到下五段:
 [code] 
窗口最小 720×520。窗口高度不足 640px 时,命令抽屉会自动收起且把手不可点,
保证上面的内容不被挤没。
### 顶栏:状态与值守开关
后端状态:
| 文字 | 含义 |
|---|---|
| 正在启动后端… | Python 子进程正在导入依赖,按钮全灰 |
| 值守中 | 后端就绪,可以操作 |
| 正在停止… | 正在优雅退出后端 |
| 后端已停 | 进程退出或起不来,详情看输出面板 |
顶栏中间显示:
- `每 60s 一轮`:循环在跑。数字来自 `[dot] tick_seconds`。
- `循环已停`:循环没跑,但后端还活着,你仍然可以手动「跑一轮」、聊天、点命令。
右边按钮:
- **停止**:请求停下循环。如果它正跑着一个目标,**不会立刻停** —— 要等这一轮结束。
 按钮会一直是「停止」,直到后端推来 `loop_stopped`。急着关窗口也没事,
 关闭时会先把没跑完的目标放回队列。
- **开始值守**:重新启动循环。
循环默认在界面启动时自动开启。它的存在感就是「主动」:不用你喊,它每轮自己找活干。
顶栏最右边「体检」= `dots doctor`。逐项检查:配置文件、读配置、审批规则、依赖、模型、
工作区可写、数据库、事件源、审批通道、技能库、bot、成本上限。每项失败都会给一句
「下一步怎么做」。
### 待批横幅:它停下来等你
只有存在挂起审批时才出现,是整个界面唯一用琥珀色强调的地方。
 [code] 
- 摘要会尽量说人话:`send_email` 显示收件人和主题,`run_shell` 显示命令,
 其它动作显示工具名。
- 每个审批有唯一编号(token)。点「批准」= `dots approve `,
 「拒绝」= `dots reject `。
- 决定写进 `approvals` 表,下一轮 tick 自动续跑对应目标。邮件回复和这里点按钮
 **走的是同一条路径**。
-