@yejiming/dsh-data-agent 0.0.1 → 0.0.3

package/README.en.md

@@ -16,7 +16,7 @@ With this preset, you can configure a database connection right in the conversat
 
   ![Database connection](assets/connection.png)
 
-- **Database workbench** (embedded above the session's input bar): connection config card (collapses into a summary row after connecting, expandable for review); schema explorer (a "Tables" button opens a Modal — single-click a database to expand its table list, up to 5 rows visible with a built-in scrollbar, click a table to inspect its columns); SQL command box (write and run SQL on the non-agent channel, monospace output). The connection config is persisted to browser localStorage — switching pages or restarting restores the form and auto-reconnects. Once the conversation starts, the workbench becomes the left column and the chat records + input bar sit on the right.
+- **Database workbench** (embedded above the session's input bar): connection config card (collapses into a summary row after connecting, expandable for review); schema explorer (a "Tables" button opens a Modal — single-click a database to expand its scrollable table list, click a table to inspect its columns); SQL command box (write and run SQL on the non-agent channel, monospace output). The connection config is persisted to browser localStorage — switching pages or restarting restores the form and auto-reconnects. Once the conversation starts, the workbench becomes the left column and the chat records + input bar sit on the right.
 - **sqlcmd tool**: runs SQL/commands through the database clients (mysql / psql / sqlite3 / sqlplus / beeline / impala-shell); no shell layer (argv arrays + SQL via stdin), timeouts terminate the process tree, output is bounded and truncated.
 - **Data Agent preset**: choose "Data Agent" when creating a session — the tool surface is exactly `sqlcmd`/`read`/`write`/`edit`, and every other project tool (bash, grep, skill, todo, goal, web, subagent, …) is simply absent, i.e. disabled; non-Data-Agent sessions render no workbench at all.
 
@@ -26,39 +26,44 @@ With this preset, you can configure a database connection right in the conversat
 
 ## Quick Install
 
-The repository ships its prebuilt output in `lib/` and declares no
-`prepare`/`prepack` scripts, so git, tarball, and local-directory installs all
-use the committed artifacts — **no build step at install time**.
+Two install methods, neither requires a local build (the prebuilt output in
+`lib/` is committed, and no `prepare`/`prepack` scripts are declared).
+
+### Method 1: npm (recommended)
 
 ```sh
-# Install from git (recommended; initializes the profile on first use)
-dsh plugin --profile demo add github:omdsh-dev/dsh-data-agent
+# Install from npm (initializes the profile on first use)
+dsh plugin --profile web add @yejiming/dsh-data-agent
+```
+
+### Method 2: GitHub source
 
-# Or install from the local source directory (lib/ is committed, no build needed)
-dsh plugin --profile demo add .
+```sh
+# Install from the GitHub source (lib/ is committed, no build at install time)
+dsh plugin --profile web add github:omdsh-dev/dsh-data-agent
 ```
 
 Verify the install:
 
 ```sh
-dsh --profile demo --dump-config   # the data-agent layer should appear
+dsh --profile web --dump-config   # the data-agent layer should appear
 ls $DSH_HOME/.agent-presets/data-agent/   # agent.cordis.yml + preset.yml (auto-installed)
 ```
 
 Start the Web GUI:
 
 ```sh
-dsh --profile demo
+dsh --profile web
 ```
 
-In the Web GUI: create a session → choose the "Data Agent" preset → the database workbench appears above the input bar → fill in the connection info (type/host/port/user/password/database; SQLite uses a file path) → after connecting, browse schemas (double… single-click a database to expand tables, click a table for its structure) or run SQL directly in the command box → once the conversation starts the workbench moves to the left; in Chat ask the AI to "list all tables and count rows" or "write a SQL query for orders in the last 30 days, save it to orders.sql and run it".
+In the Web GUI: create a session → choose the "Data Agent" preset → the database workbench appears above the input bar → fill in the connection info (type/host/port/user/password/database; SQLite uses a file path) → after connecting, browse schemas (single-click a database to expand tables, click a table for its structure) or run SQL directly in the command box → once the conversation starts the workbench moves to the left; in Chat ask the AI to "list all tables and count rows" or "write a SQL query for orders in the last 30 days, save it to orders.sql and run it".
 
 > Database client binaries: sqlite3 usually ships with macOS/Linux; mysql / psql / sqlplus / beeline / impala-shell must be provided by the deployment and can be overridden per type via the `clients` config (missing clients are named in the connect error).
 
 ## Architecture
 
 ```text
-Browser (apps/web)                        Host process (dsh --profile demo)
+Browser (apps/web)                        Host process (dsh --profile web)
 ┌─────────────────────────────┐          ┌──────────────────────────────────────┐
 │ Database workbench (input.dock) │ fetch │ @yejiming/dsh-data-agent (host row)│
 │  · connection config (6 types) │ ─────▶ │  · /plugins/data-agent/* routes       │
@@ -84,7 +89,7 @@ One npm package, three loadable faces, two host rows:
 | Tool half | `lib/tool.js` (exports subpath `./tool`) | Only mounted by the data-agent preset (`tool-sqlcmd` row) |
 | Browser half | `lib/client.js` (`dsh.client` declaration) | Browser: the database workbench in the input dock (`conversation.input.dock`) |
 
-The tool half only consumes host services (`subprocess`, `dataAgentConnections`) and provides none, so the preset guard needs no `isolate` realm.
+The tool half only consumes host services (`tools`, `subprocess`, `dataAgentConnections`) and provides none, so the preset guard needs no `isolate` realm.
 
 ## Configuration
 
@@ -156,7 +161,7 @@ Schema/table identifiers allow only `[A-Za-z0-9_$#.-]` (server-side whitelist; i
 ## Uninstall & Rollback
 
 ```sh
-dsh plugin --profile demo remove @yejiming/dsh-data-agent   # removes the dependency and its layer
+dsh plugin --profile web remove @yejiming/dsh-data-agent   # removes the dependency and its layer
 rm -rf $DSH_HOME/.agent-presets/data-agent                      # manually delete the self-installed preset
 ```
 
@@ -183,3 +188,9 @@ family) and `allowBuilds: esbuild`.
 ## License
 
 MIT
+
+## Friends
+
+- [dshfind.com](https://dshfind.com): Chinese learning & sharing community for DeepSeek Harness — read the papers, write plugins, see the whole ecosystem.
+- [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui): Plugins & skins collection for the DeepSeek Harness (DSH) Web UI
+- [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui): Claude Code style fullscreen interactive terminal plugin

package/README.md

@@ -19,7 +19,7 @@
 - **数据库连接管理**：按会话连接 MySQL / PostgreSQL / SQLite / Oracle / Hive / Impala（SQLite 走文件路径，Oracle 填服务名/SID，Hive/Impala 填默认库），连接状态驻留服务端内存，布局切换不丢；密码仅内存、经环境变量或 stdin 连接前缀传给客户端，绝不落盘。
 
   ![数据库连接](assets/connection.png)
-- **数据库工作台**（内嵌于会话输入框上方）：连接配置卡（连接成功后折叠为摘要行，可展开查看）；库表浏览（点击「库表」按钮弹出 Modal：单击库展开表列表，表列表单页 5 条可滚动，点击表查看结构）；SQL 命令框（编辑并运行 SQL，非 agent 通道，结果等宽展示）。连接配置持久化到浏览器 localStorage，切换页面/重启自动回填并重连。开始对话后工作台自动变为左侧栏，对话记录与输入框在右侧。
+- **数据库工作台**（内嵌于会话输入框上方）：连接配置卡（连接成功后折叠为摘要行，可展开查看）；库表浏览（点击「库表」按钮弹出 Modal：单击库展开表列表（可滚动），点击表查看结构）；SQL 命令框（编辑并运行 SQL，非 agent 通道，结果等宽展示）。连接配置持久化到浏览器 localStorage，切换页面/重启自动回填并重连。开始对话后工作台自动变为左侧栏，对话记录与输入框在右侧。
 
   ![数据库工作台](assets/tables.png)
 - **sqlcmd 工具**：在数据库客户端（mysql / psql / sqlite3 / sqlplus / beeline / impala-shell）执行 SQL/命令；无 shell 层（argv 数组化 + SQL 走 stdin），超时自动终止进程树，输出有界截断。
@@ -30,38 +30,44 @@
 
 ## 快速安装
 
-仓库已提交构建产物 `lib/`（且不设 `prepare`/`prepack` 脚本），因此 git、tarball
-与本地目录安装都直接使用产物，**无需在安装时构建**。
+支持两种安装方式，均**无需本地构建**（构建产物 `lib/` 已提交进仓库，且不设
+`prepare`/`prepack` 脚本）。
+
+### 方式一：npm 安装（推荐）
 
 ```sh
-# 从 git 安装（推荐；首次使用会初始化该 profile）
-dsh plugin --profile demo add github:omdsh-dev/dsh-data-agent
+# 从 npm 安装（首次使用会初始化该 profile）
+dsh plugin --profile web add @yejiming/dsh-data-agent
+```
+
+### 方式二：GitHub 源码安装
 
-# 或从本地源码目录安装（lib/ 已提交，同样无需构建）
-dsh plugin --profile demo add .
+```sh
+# 从 GitHub 源码安装（仓库已提交构建产物 lib/，安装时无需构建）
+dsh plugin --profile web add github:omdsh-dev/dsh-data-agent
 ```
 
 安装后验证：
 
 ```sh
-dsh --profile demo --dump-config   # 输出中应出现 data-agent 层
+dsh --profile web --dump-config   # 输出中应出现 data-agent 层
 ls $DSH_HOME/.agent-presets/data-agent/   # 应有 agent.cordis.yml + preset.yml（由插件自动安装）
 ```
 
 启动 Web GUI：
 
 ```sh
-dsh --profile demo
+dsh --profile web
 ```
 
-在 Web GUI 中：新建会话 → 选择「数据Agent」预设 → 输入框上方出现数据库工作台 → 填写连接信息（类型/主机/端口/用户/密码/库名；SQLite 填文件路径）→ 连接成功后浏览库表（双击库看表、点击表看结构），或在 SQL 命令框直接运行 SQL → 开始对话后工作台移到左侧，在 Chat 让 AI「列出所有表并统计行数」或「写一条 SQL 查出近 30 天订单，保存到 orders.sql 并执行」。
+在 Web GUI 中：新建会话 → 选择「数据Agent」预设 → 输入框上方出现数据库工作台 → 填写连接信息（类型/主机/端口/用户/密码/库名；SQLite 填文件路径）→ 连接成功后浏览库表（单击库展开表、点击表看结构），或在 SQL 命令框直接运行 SQL → 开始对话后工作台移到左侧，在 Chat 让 AI「列出所有表并统计行数」或「写一条 SQL 查出近 30 天订单，保存到 orders.sql 并执行」。
 
 > 数据库客户端二进制要求：sqlite3 一般系统自带（macOS/Linux）；mysql / psql / sqlplus / beeline / impala-shell 需部署方安装，且可在插件配置 `clients` 中覆盖命令名或绝对路径（缺失时连接报错会点名缺失的命令）。
 
 ## 架构
 
 ```text
-浏览器 (apps/web)                         宿主进程 (dsh --profile demo)
+浏览器 (apps/web)                         宿主进程 (dsh --profile web)
 ┌─────────────────────────────┐          ┌──────────────────────────────────────┐
 │ 数据库工作台 (input.dock)    │  fetch   │ @yejiming/dsh-data-agent (宿主行)   │
 │  · 连接配置 (6 类型)         │ ───────▶ │  · /plugins/data-agent/* 路由          │
@@ -87,7 +93,7 @@ dsh --profile demo
 | 工具半体 | `lib/tool.js`（exports 子路径 `./tool`） | 仅 data-agent 预设装载（`tool-sqlcmd` 行） |
 | 浏览器半体 | `lib/client.js`（package.json `dsh.client` 声明） | 浏览器：输入条带内嵌数据库工作台（`conversation.input.dock`） |
 
-工具半体只消费宿主服务（`subprocess`、`dataAgentConnections`），不提供服务，因此预设守卫无需 `isolate` realm。
+工具半体只消费宿主服务（`tools`、`subprocess`、`dataAgentConnections`），不提供服务，因此预设守卫无需 `isolate` realm。
 
 ## 配置
 
@@ -101,12 +107,13 @@ dsh --profile demo
 | `introspectMaxTables` | 表清单上限（默认 500） |
 | `queryTimeoutMs` | sqlcmd 单次查询超时（默认 30000 毫秒） |
 | `maxResultChars` | sqlcmd 捕获输出上限（stdout/stderr 各自，默认 20000 字符） |
+| `readonly` | 只读护栏（默认 false）：true 时 `sqlcmd` 与 `/query` 仅放行读语句（SELECT/SHOW/DESCRIBE/EXPLAIN/PRAGMA 等），写语句直接拒绝 |
 | `clients` | 各数据库类型 CLI 客户端覆盖：`{ command?, args? }`，键为 `mysql` / `postgres` / `sqlite` / `oracle` / `hive` / `impala`（内置默认 mysql/psql/sqlite3/sqlplus/beeline/impala-shell） |
-| `connections` | 配置预置连接，键为 sessionId（`'*'` = 通配符默认，任何无自有连接的会话回落它；headless/keyless 运行与部署固定默认库场景）。**不含 password 字段**——密码只允许经 /connect 路由进入内存 |
+| `connections` | 配置预置连接，键为 sessionId（`'*'` = 通配符默认，任何无自有连接的会话回落它；headless/keyless 运行与部署固定默认库场景）。**不含 password 字段**——密码只允许经 /connect 路由进入内存；可选 `readonly` 字段按连接锁定只读 |
 
-工具行 `tool-sqlcmd`（data-agent 预设内）另有 `maxRows`（默认 100，注入工具描述的 LIMIT 引导），`queryTimeoutMs` / `maxResultChars` / `clients` 与宿主行同名可配。
+工具行 `tool-sqlcmd`（data-agent 预设内）另有 `maxRows`（默认 100，注入工具描述的 LIMIT 引导）与 `readonly`，`queryTimeoutMs` / `maxResultChars` / `clients` 与宿主行同名可配。
 
-路由行 `data-agent-routes` 独立配置：`connectTimeoutMs` / `introspectMaxTables` / `maxResultChars` 与主行同名同默认；另有 `queryTimeoutMs`（/query 与元数据查询超时，默认 30000）与 `maxQueryChars`（/query 单条 SQL 长度上限，默认 65536）。
+路由行 `data-agent-routes` 独立配置：`connectTimeoutMs` / `introspectMaxTables` / `maxResultChars` / `readonly` 与主行同名同默认；另有 `queryTimeoutMs`（/query 与元数据查询超时，默认 30000）与 `maxQueryChars`（/query 单条 SQL 长度上限，默认 65536）。
 
 ```yaml
 # cordis.patch.yml 或 profile 层覆盖示例
@@ -137,28 +144,28 @@ dsh --profile demo
 
 | 方法/路径 | 说明 |
 |---|---|
-| `POST /connect` | body `{ sessionId, type, host?, port?, user?, database, password? }`；校验 → 连通性验证（列出所有表）→ 成功才保存连接，返回 `{ ok, tables }`，失败返回 `{ ok: false, error }` 且不保存 |
+| `POST /connect` | body `{ sessionId, type, host?, port?, user?, database, password?, readonly? }`；校验 → 连通性验证（列出所有表）→ 成功才保存连接，返回 `{ ok, tables }`，失败返回 `{ ok: false, error }` 且不保存 |
 | `POST /disconnect` | body `{ sessionId }`；清除该会话连接 |
-| `GET /status?sessionId=` | `{ connected, summary? }`；summary 为脱敏连接概要（无密码）+ 表清单 |
+| `GET /status?sessionId=` | `{ connected, summary? }`；summary 为脱敏连接概要（无密码，含 `readonly` 当连接显式设定时）+ 表清单 |
 | `GET /schemas?sessionId=` | `{ ok, schemas: string[] }`；库/数据库列表（sqlite 为 `['main']`） |
 | `GET /tables?sessionId=&schema=` | `{ ok, tables: string[] }`；某库的表列表（sqlite 忽略 schema 参数） |
 | `GET /describe?sessionId=&schema=&table=` | `{ ok, columns: [{ name, type, nullable? }] }`；表结构（sqlite 忽略 schema） |
-| `POST /query` | body `{ sessionId, sql }`；运行任意 SQL（工作台命令框，非 agent 通道），返回 `{ ok, result: { exitCode, stdout, stderr, truncated } }`；`sql` 长度上限 `maxQueryChars` |
+| `POST /query` | body `{ sessionId, sql }`；运行任意 SQL（工作台命令框，非 agent 通道），返回 `{ ok, result: { exitCode, stdout, stderr, truncated } }`；`sql` 长度上限 `maxQueryChars`；readonly 开启时拒绝写语句 |
 
-schema/table 标识符仅允许 `[A-Za-z0-9_$#.-]`（服务端白名单校验，拒绝注入形字符）。
+schema/table 标识符仅允许 `[A-Za-z0-9_$]`（服务端白名单校验并转义引用，拒绝注入形字符）。
 
 ## 安全说明
 
 - **密码**：服务端仅存内存，传递通道按类型：mysql 经 `MYSQL_PWD`、postgres 经 `PGPASSWORD` 环境变量；oracle 经 sqlplus `connect user/pass@...` stdin 前缀、hive 经 beeline `!connect` stdin 前缀（均不进 argv）；impala 默认不传密码（LDAP/kerberos 由部署侧 `clients` 覆盖）。`/status` 与连接存储的公开读取面均剥离密码。
-- **连接配置持久化**：工作台在连接成功后把连接配置（**含密码**，明文）保存到浏览器 localStorage（键 `dsh-data-agent.connection.v1`，用户确认的本机单用户场景），用于切换页面/重启后回填表单并自动重连一次；断开不清除。如需清除：浏览器控制台执行 `localStorage.removeItem('dsh-data-agent.connection.v1')`。
-- **无 shell 层**：`ctx.subprocess.spawn` 参数数组化，SQL 与连接前缀经 stdin 传入，不存在 shell 拼接注入面；元数据路由的 schema/table 标识符过白名单校验。
-- **SQL 执行权**：审批策略为 never 时，sqlcmd 与 `/query` 的 DDL/DML 会直接执行——连接按 session 隔离，请自行评估数据面风险（只读模式 `readonly` 列为后续版本）。
+- **连接配置持久化**：工作台把连接配置（type/host/port/user/database）保存到浏览器 localStorage（键 `dsh-data-agent.connection.v1`），用于切换页面/重启后回填表单并自动重连一次。**密码默认不落盘**：仅当用户勾选「记住密码」时才持久化密码（明文 localStorage，本机单用户场景的显式 opt-in）。若需清除：浏览器控制台执行 `localStorage.removeItem('dsh-data-agent.connection.v1')`。
+- **无 shell 层**：`ctx.subprocess.spawn` 参数数组化，SQL 与连接前缀经 stdin 传入，不存在 shell 拼接注入面；元数据路由的 schema/table 标识符经收紧白名单 `[A-Za-z0-9_$]` 校验并按类型转义引用（反引号/双引号），拒绝 `#`、`--`、`;`、`'` 等注入形字符。
+- **SQL 执行权**：审批策略为 never 时，sqlcmd 与 `/query` 的 DDL/DML 会直接执行——连接按 session 隔离，请自行评估数据面风险。可设 `readonly: true`（宿主/工具/路由三行同名，或 `/connect` 传 `readonly: true` 按连接锁定）强制只放行读语句（SELECT/SHOW/DESCRIBE/EXPLAIN/PRAGMA 等），作为误操作防护；对更强对手防护，仍建议配合数据库侧只读账号。
 - **超时与上限**：查询超时、输出截断、表清单上限、/query 单条 SQL 长度均为配置项，无硬编码 tunables。
 
 ## 卸载与回滚
 
 ```sh
-dsh plugin --profile demo remove @yejiming/dsh-data-agent   # 移除依赖与对应层
+dsh plugin --profile web remove @yejiming/dsh-data-agent   # 移除依赖与对应层
 rm -rf $DSH_HOME/.agent-presets/data-agent                      # 手动删除自安装的预设
 ```
 
@@ -183,3 +190,9 @@ dsh 同款约定（`nodeLinker: hoisted`）；pnpm 11 的供应链策略会拦
 ## 许可
 
 MIT
+
+## 友情链接
+
+- [dshfind.com](https://dshfind.com)：DeepSeek Harness 的中文学习与分享社区。读懂论文，写出插件，看见整个生态。
+- [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui)：DeepSeek Harness（DSH）Web UI 的插件与皮肤集合
+- [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui)：Claude Code 风格全屏交互终端插件