# 用户指南

## 安装

```sh
# 从源码目录（独立仓库，一插件一仓库）
dsh plugin --profile web add <本仓库路径>

# 或从 npm
dsh plugin --profile web add dsh-bot
```

装好后**刷新页面**。左侧栏出现 `bot` 条目 —— 那是这一组 bot 的入口。

## 建第一个实例

点开 `bot`，主区是首页：**选一个类型就开始**。

内置四种：

| 类型 | 定位 |
| --- | --- |
| 伴侣 | 常驻身边的同伴，记得住事，会自己惦记着开口 |
| 助手 | 替你推进手头的事，交办之后自己盯着 |
| 研究员 | 持续查证、整理结论，把过程留成可回看的笔记 |
| 记录员 | 把你的决定和事实记下来，需要时能找回来 |

**四种都不是固定的**。设置页里可以改它们的名字、说明、人设，也可以自己建一个。内置的也能改 —— 一个人设作为合理默认发出去，它仍然是默认，而运行它的人才知道自己想让它怎么说话。

创建时给个名字，默认是「屿」。

## 侧边栏那一行

每个实例在 `bot` 下面各占一行，**缩进一级**，读起来像上一级的子项。

行上是：**状态点 · 名字 · 上次活跃 · 更多菜单**。

状态点四态：

| 颜色 | 意思 |
| --- | --- |
| 绿 | 有新消息 |
| 橙 | 等你回答（有任务停在边界上） |
| 红 | 出错了 |
| 灰 | 安静 |

**绿比橙优先，橙比红优先** —— 一件新消息比一个旧错误更值得先看。

更多菜单（行右端的 `…`）里是：置顶 / 重命名 / 删除。

## 记忆

### 它记在哪

`$DSH_HOME$DSH_HOME/bot/memory/`。**是一棵 `.md` 文件树，你能直接编辑。**

设置页的「记忆」栏里能看清单、能编辑、能从磁盘**重新导入**（在外部改完文件后点一下）。

### 分层怎么理解

```
MEMORY.md / SOUL.md / USER.md / MEMORY-CORE.md   ← 全文进上下文，一直在
notes/、以及你自己建的目录                        ← 只贡献名字和一句话描述
```

所以：

- **想让它一直记得某件事** → 写进根文件；
- **想留个档案但不必一直想着** → 放进子目录。

**把文件从根挪进子目录就是降级**，挪出来就是升级。用文件管理器改就行。

### 一条记忆长什么样

每条带：正文、类型（`decision` / `fact` / `focus` / `note`）、**来源**、时间。

**来源是它的可信度标签**：

- `user` —— 你亲口说的
- `agent` —— 它自己的结论
- `tool` —— 它从某个文件或网页读到的

第三条最需要留意：**它读了一个网页，然后把网页上的话写进了长期记忆**，那等于让那个网页可以往它的信念里写东西。标着 `tool` 的条目不该被当成事实用。

### 什么记不进去

**永远记不进去**的：身份证号、社保号、银行卡号、密码密钥、会话令牌。

这不是偏好，是硬门，**任何设置都改不动它**。它被拒绝时还会告诉你该怎么办 —— 要使用一个凭据，走设置页的凭据栏，而不是把它写下来。**写下来会把「能用它而不知道它」这个性质永久毁掉。**

**默认记不进去、但可以开**的：健康、财务、法律、家庭私事。改成「记」之后仍然会带着敏感标签，之后每次读到都看得见。

### 陈旧

每条记忆算得出「多少天前」。超过阈值（默认 90 天）的会被标成陈旧并在提示里注明。

**算不出时间时标 `-1`** —— 未知既不是新也不是旧，它不参与比较。

## 派活

### 从对话里

直接说，它会用 `bot_task` 排上。

### 从设置页

「任务」栏里能看队列：等待中 / 进行中 / **等你回答** / 已完成。

建任务时可以给：标题、备注、优先级（1–5）、到点时间、循环周期。

### 循环任务的两种语义

- **续跑同一上下文**（默认）：下次带上这次的结论。**例行公事要的就是这个** —— 每日摘要不拿着上一份，就不叫摘要了。
- **另起独立任务**：从零开始，不看上次的结论。**审计要的就是这个** —— 先读自己上次的结论，一个检查就悄悄变成了橡皮图章。

## 审批

它想动**工作区外面的东西**时会停下来。

停下的任务出现在「等你回答」里，**带着它想用的工具名和完整参数**。你看到的是**一个具体动作**，不是「它想干点什么」。

三个选择：

| 选择 | 效果 |
| --- | --- |
| 允许这一次 | 任务回到队列重跑，**这一步不会再拦你** |
| 授权一段时间 | 同一个工具名、在期限内、不再问 |
| 拒绝 | 任务取消，并记下「你拒绝了这一步」 |

**授权只匹配完全相同的工具名**，换个参数就不算命中。而且**一定带期限** —— 没有「永久允许」这个选项。

改任务的标题或备注会撤销已有批准：**你当初批准的是当时读到的那个任务。**

## 自主时间

**默认关闭。** 打开之前，它只在被交办时动。

打开后，**空闲只是前置条件，不是理由本身**。必须有一个可检查的条件成立：

| 条件 | 什么时候算成立 |
| --- | --- |
| 队列里有它自己的活 | 你或它之前排的任务还没做（**默认唯一开启的**） |
| 有没回应过的外部消息 | 从连接进来的消息还没被回应 |
| 有到点的日程 | 日程时间过了还没完成 |
| 工作区有更新 | 有文件比它上次看过更新 |

一个都不成立时，它会明确报告「空闲够了，但没有任何符合条件的理由」，**而不是自己找点事填满**。

还要设：空闲多久才算空闲、两轮之间最少隔多久、以及**它自己的权限**（默认**只读**）。

**权限默认只读是刻意的**：主动行为拿不到写的能力，除非你明确给。

## 连接

让它能把消息**发出去**、也能**收进来**。插件**不内置任何平台** —— 你填自己的。

| 类型 | 需要填 |
| --- | --- |
| Telegram | bot token、chat id |
| HTTP | 端点地址、方法、请求头 |

每条连接可以限制成某几个实例能用；不设就是全部。

**收到的消息会被标明来源并限长**（默认 4000 字，可调）。这不是不信任谁，是因为**「谁说的」和「说了多久」都是判断的一部分**。

「检测」按钮让你不改任何配置就能验一次连通性，结果同时显示在旁边的状态灯上。

## MCP 服务

插件带一个 **MCP 客户端**和一个输入框。填一个 **streamable HTTP** 地址，那边的工具就出现在它能用的工具里。

工具名是 `mcp__服务名__工具名` —— 和别的客户端一致，所以**从任何别处复制过来的名字在这里原样可用**。

每行左边有个状态点：

| 灯 | 意思 |
| --- | --- |
| 绿 | 真的测过一次并且通过 |
| 红 | 测过一次并且失败（原因留在旁边） |
| 灰 | 还没测过 |

**「没看过」和「没问题」不是同一个说法**，所以灯不合并这两种。点「检测」会连一次、把工具列表取回来、并把结果记下来 —— 下次打开页面还看得见。

## 头像

设置页的「头像」栏能直接上传一张图片（PNG / JPEG / WebP / GIF，4 MB 以内）。

留空则用它内置的形象。填一个本地路径也可以。

## 限额

**没有任何写死的配额。** 全部在设置页的「限额」栏，`0` 一律表示不限。

默认值见 README 的表格。唯一两个有范围的设置是自主时间的并发数与轮询间隔 —— 它们是机制参数而不是配额。

## 数据在哪

| 路径 | 内容 |
| --- | --- |
| `$DSH_HOME$DSH_HOME/bot/bot.json` | 实例、类型、记忆索引、任务、连接、MCP 服务、限额、规则 |
| `$DSH_HOME$DSH_HOME/bot/memory/` | 记忆本体（`.md` 文件树） |
| `$DSH_HOME$DSH_HOME/bot/avatars/` | 上传的头像 |

**备份就是复制这三个**。记忆是纯文本，换台机器带过去照样能用。