# dsh-basics-panel 使用文档

## 一、版本和入口

当前插件 **0.4.2**，要求 DSH **`>=0.2.1-rc.2 <0.3.0-0`**，本轮实际验证 `0.2.1-rc.2`。未来宿主升级仍需重新运行契约测试；旧 DSH 不应使用本版本。

打开原 DSH Web 界面 → **设置 → 基础能力**，包含 **MCP 服务器 / 技能 / 规则 / 归档会话** 四个页签。

## 二、DSH 升级后 HTTP 405 的修复

0.4.1 的宿主插件声明依赖 `webRuntime`，而 DSH 0.2.1 已不再提供这个服务。客户端页签可以显示，但宿主插件等待服务，`/basics/api/*` 没有挂载；POST 请求落到静态页面处理器，返回空 HTTP 405。

0.4.2 改为依赖 `connection`，调用公开 `connection.admit()`，统一继承宿主的 Host/Origin 检查、浏览器登录 Cookie、API Peer 认证；只有所有者身份能管理基础能力。不保留旧免认证回退，不应通过关闭认证或允许任意 Host 解决错误。

更新安装副本后必须：

1. **重启原 DSH 进程**，不是另外启动一个端口。
2. 在原 GUI 地址 **Ctrl+F5**，重新载入客户端 bundle。
3. 若返回 401，通过 DSH 启动时提供的登录链接重新进入。
4. 逐个打开四个页签，确认列表正常；涉及修改时先确认目标及备份。

本轮根因、验证与未测项见 [兼容性记录](<dsh-0.2.1-compatibility.md>)。

## 三、MCP 服务器

### 展示与修改

- **用户 profile**：扫描 DSH 根补丁、各 profile 补丁与部署方配置的额外文件。
- **预设 preset**：读取 `@deepseek-ai/dsh-agent-preset` 声明的 `config.plugins`，bundle 内声明只读。无 MCP 的预设不显示空组。
- 密码参数、环境变量敏感值、请求头和 URL 密码脱敏展示，不回传原始秘密。
- 状态分为已连接、已启用、未生效或预设作用域未知；没有运行证据时不宣称连接成功。
- 启用/禁用修改 Loader **行级** `disabled`；profile 通常热重载，预设修改对新会话生效，已有会话保持其组合。
- 界面在开关后轮询稳定状态，等待期间显示生效中；可展开配置查看命令、地址、工作目录与超时。

### 限制

- DSH 没有统一的项目级 MCP 配置文件，本面板不虚构此作用域。
- 嵌套 group 内的预设 MCP 行可能无法精确关联运行清单，此时保守显示未知，不按裸 ID 后缀猜测，避免组内重名错配。
- 本面板不负责安装 MCP 程序或验证外部服务自身是否健康。

## 四、技能

- 按项目、自定义、用户、内置、运行时等来源分组，支持搜索与筛选。
- 当前会话通过客户端列表的 `retainedBy.mainView` 定位；宿主以真实 Agent 对象作为技能 scope。无法定位时退到最近活动会话并明确提示，确无活动会话时只能展示全局层。
- 用户级根通常是 `~/.dsh/skills`、`~/.agents/skills`，支持宿主配置覆盖。
- 可编辑描述、使用时机、元数据、调用权限和 Markdown 正文；内置/运行时技能只读。
- 保存会重新从注册表解析技能路径，并检查 mtime 与写入大小；文件已被外部修改时刷新后重新合并，不要盲目覆盖。
- 文件系统技能提供方的 watcher 通常会热刷新；未更新时手动刷新列表。

## 五、规则

### 发现范围

顺序与宿主默认发现机制对应：

1. `$DSH_HOME/AGENTS.md`，默认 `~/.dsh/AGENTS.md`。
2. `$DSH_AGENTS_HOME/AGENTS.md`，默认 `~/.agents/AGENTS.md`。
3. 项目根（默认 `.git` 标记）至当前工作目录的候选文件：`AGENTS.md`、`CLAUDE.md`、`AGENTS.local.md`、`CLAUDE.local.md`。

只列已存在文件；两个全局根相同时去重。自定义全局根由官方 `resolveDshHome()` / `resolveAgentsHome()` 解析，不硬编码用户目录。

### 查看、编辑与创建

- 点击文件打开整文件编辑器，保存前重新发现路径白名单，检查大小和 mtime。
- **新建 → 全局**仍只创建 `$DSH_HOME/AGENTS.md`，不会悄悄改写共享根；共享根已有规则可查看和编辑。
- 项目根/当前目录新建允许四种候选文件；已存在时改为打开编辑。
- 规则作为会话基线加载，保存通常对新会话生效，不承诺改变当前回合已经加载的提示词。

## 六、归档会话

### 展示与恢复

归档只是隐藏，不卸载会话、不删除日志。列表展示标题、ID、工作目录、创建时间、产物大小；事件条数仅在后端可提供时显示，当前 JSONL 列表通常不提供。

- **运行中**：本进程 Agent 正在处理回合，不允许删除。
- **已装载**：会话仍在本进程内存中，但未必在生成回复。
- **文件缺失**：归档记录仍在，未发现有效本地产物。

恢复优先调用公开的 `workspaceRegistry.unarchiveSession()`，保留原工作区位置与日志。可单个/批量恢复；只读或缺少写入通道时拒绝，不只写磁盘造成内存状态漂移。

### 永久删除及风险

删除须二次确认，支持单条、选中和全选；超过单次上限自动分批。只接受归档集合内 ID，由宿主重新扫描会话根，检查目录名、包含关系和日志代际文件，再删除本地会话目录并摘除工作区与归档记账。

**这是文件级删除，不是上游持久化服务公开删除 API：**

- 不清理附件和查询 SQLite 索引等派生数据。
- 只观察本进程 Agent 的运行状态，不协调其他 DSH 进程持有的会话写入租约。**同一会话被其他进程使用时不要删除。**
- 已装载但空闲会话删除后若再次写盘，可能失败或重建日志；确认条会提示，请先关闭对应会话视图。
- 缺失或不符合布局的产物不猜测路径；仍可清理悬空归档记录。
- 删除完成后主动刷新客户端会话列表，侧边栏残留时刷新页面。

本轮只在临时目录回归删除逻辑，未删除用户真实归档记录。

## 七、本地/远程边界

配置、规则、技能文件编辑及会话产物操作通过插件宿主的 Node 文件系统执行，不走可替换的 `ctx.fs` 或 SSH 工作区文件提供方。**本面板管理的是 DSH 宿主本地数据，不是远程服务器的同名路径。** 远程工作区规则请使用明确的远程文件工具，不要把本地面板当作远端编辑器。

## 八、配置

在插件 Cordis 行的 config 中可配置：

```yaml
- id: basics-panel
  name: dsh-basics-panel
  config:
    maxSkillBytes: 524288
    maxRuleBytes: 1048576
    maxBodyBytes: 1048576
    readOnly: false
    extraMcpFiles: []
    maxBatchIds: 200
    allowSessionDelete: true
    sessionsRoot: ''
```

- `readOnly: true` 禁止所有修改，包括归档恢复；`allowSessionDelete: false` 只禁删除。
- `sessionsRoot` 留空取 `$DSH_HOME/sessions`；自定义持久化后端不一定采用 JSONL 布局，不匹配时面板不会猜路径。
- `extraMcpFiles` 是管理员显式授权的宿主本地配置绝对路径。

## 九、构建、安装与校验

本包暂无 npm 发布版本。官方本地安装通道：

```bash
pnpm install
pnpm typecheck
pnpm test
pnpm build
dsh plugin --profile web add file:<源码目录绝对路径>
```

已经用 `file:` 安装时，构建后可定向同步：

```bash
pnpm run sync
pnpm run sync:check
dsh --profile web --dump-config
```

同步前先备份安装副本和 profile。脚本默认同步到 web profile，仅更新本插件发布内容；`sync:check` 有运行文件差异时退出 1。只构建源码、不同步安装副本，即使重启也可能仍是旧代码。

真实宿主回归（PowerShell）：

```powershell
$env:DSH_RUNTIME_NODE_MODULES = '<实际 DSH 安装目录>/node_modules'
pnpm test
```

未指定运行时路径会明确跳过宿主组；显式指定后缺包应失败，不得把旧依赖或替身通过当作真实宿主兼容。`--dump-config` 仅做组合预检，不能证明全部服务已激活或 GUI 已验收。

## 十、常见问题

- **空 HTTP 405**：检查是否安装 0.4.2、是否同步产物、是否重启原 DSH。旧宿主端仍等待 `webRuntime` 时仅刷新无效。
- **401**：登录状态失效，使用启动登录链接重新进入；不要向聊天发送令牌或 Cookie。
- **403**：来源未通过宿主栅栏、身份非所有者，或该操作被只读/路径白名单拒绝；以具体提示区分。
- **技能为空**：确认有活动会话，其预设挂载了文件系统技能提供方；按页顶 scope 提示核对。
- **工作区注册表未挂载**：它是按请求解析的可选服务，稍后刷新；裁剪 profile 没装该服务时归档不可用。
- **保存提示文件已修改**：重读、保留外部变更后再保存，不盲目重试旧内容。