> **Languages:** [中文](../../ops/图形界面_安装与排障.md) · English

# Graphical interface: installation, pages, and troubleshooting

> This page is the full version of the "Graphical interface" section in the README: installer behavior, the semantics of the seven pages, three pitfalls confirmed by testing, and how changes take effect.

LINGSHU itself is an MCP server and plugin and ships no interface of its own. `ui/minimal/` is an **optional add-on package**: after it is installed into the LINGSHU plugin directory,
a "LINGSHU" panel appears on the left side of DSH, and you can also visit `http://127.0.0.1:<DSH端口>/lingshu` directly.

```powershell
# 先只检查（不写任何文件，可随时跑）
powershell -ExecutionPolicy Bypass -File ui/minimal/install.ps1 -PluginPath <你的灵枢插件目录> -CheckOnly

# 安装（就地上屏；只改 UI 代码与插件清单）
powershell -ExecutionPolicy Bypass -File ui/minimal/install.ps1 -PluginPath <你的灵枢插件目录>

# 卸载（逐文件恢复安装前内容）
powershell -ExecutionPolicy Bypass -File ui/minimal/install.ps1 -PluginPath <你的灵枢插件目录> -Uninstall
```

> **Since 0.9.15: the wiring ships with the repository and the npm package**: `dsh.client` / `exports["./client"]` (in `package.json`) and the
> `installConsoleWeb(...)` call (in `src/index.ts`) are both in the repository; static artifacts are generated by `scripts/build_ui.py`
> (run automatically by `build` and `prepublishOnly`; `--check` only validates). So **changing the plugin manifest no longer requires reinstalling the UI**.
> When installing from the npm package into a local plugin directory, `install.ps1` only needs to lay down the static artifacts; for **old plugin packages without wiring** it still completes the manifest automatically.

| What the installer lays down | What the installer does **not** touch |
|---|---|
| the 9 payload files (`web/` · `lib/client.js` · `console_web.mjs` · `build-ui.mjs`) | the DSH profile / plugin root / memory store |
| (old packages without wiring only) adds the `dsh.client`, `exports["./client"]`, and `lib/index.js` wiring | credentials, tokens, the automatic memory switch |
| - | your existing node data |

**How changes take effect**: the client bundle and the `/plugins/lingshu/*` routes are registered **when DSH starts**, so **DSH must be restarted** after installation (the installer prints the same reminder).

## The seven pages and the "command panel" semantics

| Page | Content |
|---|---|
| Overview / Memory | loads on open (recent memories, retrieval, and write entry points) |
| Goals and tasks · Self-cognition · Spatiotemporal relations · Review and maintenance | **command panel**: opens empty; pick an operation first, then click "Run query" |
| Toolbench | reads the real LINGSHU tool catalog live; fill in a form or write JSON directly to invoke |

> Write operations and adjudications **require a second confirmation** in the interface (the request carries `confirm:true`, otherwise the server returns 409); read-only queries do not.

## Troubleshooting (three pitfalls confirmed by testing)

| Symptom | Cause | Action |
|---|---|---|
| `分享包文件缺失或损坏：web/index.html` (the file is clearly there) | the payload was checked out with CRLF and mismatches `integrity.json` (which records the sha256 over LF) | since 0.9.15 `.gitattributes` pins `eol=lf`; on older versions, have git re-check out that directory (`git rm --cached -r ui/minimal/payload && git checkout -- ui/minimal/payload`) |
| `之前安装的文件发生改变` / the same message on uninstall | a stale `.lingshu-ui-backup-v1/state.json` from an older version is left in the plugin directory (it records an outdated hash) | move that directory out of the plugin directory as a whole (keeping the backup), then re-run the installer |
| No "LINGSHU" panel on the left after installation | (1) DSH was not restarted (2) `package.json` lacks `dsh.client` (3) the browser cached the old frontend | (1) restart (2) re-run the installer (3) hard refresh (Ctrl+Shift+R) |

> Data does not leave this machine: the UI reuses the local brain bridge of your existing LINGSHU install; `/plugins/lingshu/call` enforces same-origin checks plus CSRF plus the DSH login state, and returns 401 without a login.
> Step-by-step instructions for end users are in [`ui/minimal/使用说明.md`](../ui/minimal.md).