@hedeqiang/dsh-nl2sql 0.0.0-stage → 0.11.1

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# 更新日志
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [未发布]
+
+## [0.11.1] - 2026-11-12
+
+### 修复
+- 中文界面下渠道类型、配置说明、推荐问题等显示为英文：读取 Harness 语言设置的方式有误（LocaleSnapshot 的 `active` 字段），已修正并加了回归测试。
+
+### 新增
+- GitHub Actions 发布流程：推送 `v*` 版本标签后自动检查、打包，并通过 npm 可信发布（OIDC，带来源证明）发布到 npm，同时创建 GitHub Release。
+
+## [0.11.0] - 2026-11-12
+
+### 新增
+- 渠道架构：IM 平台改为适配器（`channels/`），统一的消息模型、能力声明、表单定义和机器人接口，详见 [docs/CHANNELS.md](docs/CHANNELS.md)。
+- 新平台：Telegram（推送、长轮询机器人、按钮）、企业微信（群机器人推送；智能机器人长连接问答与推送）、钉钉（自定义机器人推送；企业内部应用机器人 Stream 模式问答与推送）。以上新平台仅用模拟服务测试，尚未在真实账号上验证。
+- 成员身份支持多平台（`identities`），机器人按渠道配置，可同时运行多个。
+- 页面：「渠道」按平台分组、两步添加（选平台与类型 → 按表单填写），能力标签、配置步骤、选择群聊、测试；成员页「机器人」总览；成员身份编辑；设置「渠道与机器人」。
+- 问答页「试试这些问题」支持「换一批」；删除单条历史记录；「最近的提问」可删除并支持「显示更多」。
+
+### 兼容
+- 旧的飞书渠道、机器人配置、成员字段和设置在首次加载时自动迁移；旧的 RPC 与数据格式继续可用。
+
+## [0.10.0] - 2026-11-12
+
+### 新增
+- 飞书回复卡片上的交互按钮：按维度拆分、为什么变化、明细、固定到看板（经长连接回传，服务端校验权限）。
+- 业务知识「建议」：从 👍 反馈、重复出现的查询、常用聚合和取值映射中自动生成样例、指标、备注和词表建议，人工确认后采纳。
+- 开源准备：MIT 许可证、README、贡献指南、安全策略、CI。
+
+### 修复
+- `token_code` 等加密货币业务字段不再被误判为敏感字段。
+- 评测比对能识别同一组数字的不同排布（一行多列 / 多行一列）。
+
+## [0.9.0] - 2026-11-12
+- 页面改为 5 个常用页签 + 「管理」区；设置分组（说明、未保存提示、恢复默认、配置导出导入）。
+- 首次使用引导；问答页推荐问题与最近提问。
+- 看板拖拽排序、三档宽度、刷新与缓存状态；页面内提示替代浏览器弹窗；英文界面完整翻译。
+- 上传分块暂存；MySQL / PostgreSQL 大结果流式截断；大库按问题挑选相关表；日志保留条数可配置。
+
+## [0.8.0] - 2026-11-12
+- 只读角色、行级权限、调度器补查与状态、日志迁移到 SQLite、代码拆分为 `service/` 与 `client-src/`、测试套件。
+- 安全修复：按方言词法的只读检查（修复 PostgreSQL 可写入问题）、访问控制绕过、飞书成员数据源范围、飞书回答错位。
+
+## [0.7.0] - 2026-11-11
+- 指标告警、飞书 @机器人问答、下钻与归因、准确率评测、表结构变更检测、指标工具、多看板、Excel 导出、CSV / Excel 上传、结果持久化与缓存、业务知识导入导出、多用户权限与审计。
+
+## [0.6.0] 及更早
+- 界面重设计；飞书推送（Markdown 与原生图表）；访问控制、反馈闭环、看板全局筛选；PostgreSQL / Elasticsearch、SSH 隧道、隐私设置、自动概览、定时报告；语义层、关系图、扫描保护、历史与审计、看板；MVP。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hedeqiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,63 @@
+# dsh-nl2sql · Data Q&A
+
+An enterprise NL2SQL plugin for DeepSeek Harness: connect databases, ask in plain language, and the agent writes read-only SQL, runs it and charts the result in the conversation. Pin results to dashboards, push them to Lark / Feishu, or ask the bot directly in a Lark group.
+
+[中文](README.md)
+
+## Features
+
+- **Data sources:** MySQL 5.7+, PostgreSQL, Elasticsearch SQL (optionally over SSH), and CSV / Excel uploads stored as local SQLite.
+- **Schema analysis:** table roles, column semantics (time / measure / enum / sensitive), inferred relations, ER view.
+- **Asking:** in a Harness conversation through the `nl2sql_*` tools; results render as ECharts charts or tables.
+- **Drill-down and "why did it change":** split by a dimension, show rows, rank dimensions by their contribution to a change.
+- **Metric library and business knowledge:** glossary, governed metrics (`nl2sql_metric`), column notes, verified examples; import / export; accuracy evaluation against the examples.
+- **Dashboards:** multiple boards, global filters, drag-to-reorder, three widths, snapshots, Excel export.
+- **Channels:** Lark / Feishu, Telegram, WeCom and DingTalk through pluggable adapters ([docs/CHANNELS.md](docs/CHANNELS.md)); push Markdown and results (native charts, images or tables per platform), and @-mention bots that need no public URL.
+- **Automation:** scheduled reports, metric alerts (threshold / change / anomaly / missing), schema change detection.
+- **Safety:**
+  - read-only admission with per-dialect lexing, read-only transactions, server-side timeouts, streamed truncation;
+  - table / column access policies with masking, full-scan guard;
+  - member scopes, viewer role and row-level rules for Lark users;
+  - a setting for what result data reaches the model (column statistics by default); audit attributed to people.
+
+## Install
+
+Requires DeepSeek Harness (desktop or `dsh web`).
+
+```bash
+git clone <this repo> dsh-nl2sql && cd dsh-nl2sql
+pnpm install --ignore-scripts
+```
+
+Install the directory as a bundle (plugin manager `install_bundle` with the absolute path), or add `@hedeqiang/dsh-nl2sql` to your profile's `dsh.profile.bundles` with a `link:` dependency. Once published, install `@hedeqiang/dsh-nl2sql` from npm.
+
+## Use
+
+1. Sidebar → **Data Q&A** → **Manage → Data sources**: add a database (a read-only account is recommended) or upload a file.
+2. **Schema** → analyze.
+3. Ask on the **Ask** page, or pick the Data Q&A preset in any conversation.
+4. Pin useful charts to a **Dashboard**; add glossary terms, metrics and examples under **Knowledge**.
+5. **Manage → Push channels / Alerts & reports / Members & access** for Lark push, automation and the Lark bot.
+
+## Data and privacy
+
+- **Configuration:** `~/.dsh/nl2sql/state.json`.
+- **Results, cache and logs:** `~/.dsh/nl2sql/results.sqlite`.
+- **Uploaded files:** `~/.dsh/nl2sql/files/`.
+- **Passwords and app secrets:** the Harness credential store.
+- **What reaches the model:** **Settings → Data shown to the model** decides this; by default it is schema, enum values and per-column result statistics.
+- **Lark:** content pushed to Lark leaves the machine.
+
+## Development
+
+```bash
+npm test                       # whole suite; local MySQL / PostgreSQL optional (skipped when absent)
+npm test -- --fast             # unit + UI tests only
+node scripts/build-client.mjs  # regenerate lib/client.js after editing client-src/
+```
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) and [eval/README.md](eval/README.md).
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# dsh-nl2sql · 数据问答
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[DeepSeek Harness](https://github.com/deepseek-ai) 的企业级 NL2SQL 插件：连接数据库，用自然语言提问，Agent 写只读 SQL、执行并在对话中画图；结果可以固定到看板、推送到飞书，还能在飞书群里直接 @机器人提问。
+
+[English](README.en.md)
+
+## 功能
+
+**问答与分析**
+- 数据源：MySQL 5.7+、PostgreSQL、Elasticsearch（SQL），支持 SSH 隧道；也可以上传 CSV / Excel（存为本机 SQLite）。
+- 表结构分析：识别表的角色、字段语义（时间 / 度量 / 枚举 / 敏感）、推断表间关系，提供关系图。
+- 自然语言提问：在 Harness 对话中进行，Agent 使用 `nl2sql_*` 工具查询，结果在对话中渲染为 ECharts 图表或表格。
+- 下钻与归因：按维度拆分、查看明细、「为什么变化」——比较两个时段并按维度贡献排序。
+- 指标库与业务知识：词表、指标口径（Agent 用 `nl2sql_metric` 按口径查询）、字段备注、样例问答；支持导入导出。
+- 准确率评测：用样例问答作为评测集，Agent 从零作答后与样例结果比对。
+
+**看板与推送**
+- 多看板、全局筛选（时间范围 / 维度）、拖拽排序、三档宽度、快照、Excel 导出。
+- IM 渠道：飞书 / Lark、Telegram、企业微信、钉钉（推送 Markdown 与结果，图表按平台能力用原生图表、图片或表格）；架构见 [docs/CHANNELS.md](docs/CHANNELS.md)，新增平台只需实现一个适配器。
+- 定时报告（基于 Harness 定时任务）、指标告警（阈值 / 环比 / 异常 / 无数据）、表结构变更检测。
+- 群聊 @机器人提问：飞书长连接、Telegram 长轮询、企业微信智能机器人长连接、钉钉 Stream 模式，都不需要公网地址。
+
+**安全与治理**
+- 只读执行：按方言词法检查语句（MySQL / PostgreSQL / SQLite / ES），只读事务，PostgreSQL 使用扩展协议拒绝多语句，服务端超时，大结果流式截断。
+- 访问控制：按表允许 / 排除、隐藏列、脱敏列；大表全表扫描保护。
+- 成员与权限：飞书用户 / 群的数据源范围、只读角色（只能用指标库、已验证样例和看板）、行级权限（自动注入过滤，无法安全改写的查询直接拒绝）。
+- 隐私：可设置发给模型的内容（不发 / 统计摘要 / 前 N 行），敏感字段默认脱敏；审计记录归属到具体的人。
+
+## 安装
+
+需要 DeepSeek Harness 桌面版或 `dsh web`。
+
+```bash
+# 从源码（开发）
+git clone <this repo> dsh-nl2sql && cd dsh-nl2sql
+pnpm install --ignore-scripts      # 依赖：mysql2、pg、ssh2、echarts、@larksuiteoapi/node-sdk、@resvg/resvg-js
+```
+
+然后在 Harness 中让 Agent 安装本地目录（插件管理器 `install_bundle`，目标为本目录的绝对路径），或在 profile 的 `package.json` 中加入：
+
+```json
+{ "dsh": { "profile": { "bundles": ["@hedeqiang/dsh-nl2sql"] } },
+  "dependencies": { "@hedeqiang/dsh-nl2sql": "link:/path/to/dsh-nl2sql" } }
+```
+
+发布到 npm 后可直接安装 `@hedeqiang/dsh-nl2sql`。
+
+## 使用
+
+1. 左侧栏打开「数据问答」→「管理 → 数据源」，添加数据库（建议使用只读账号）或上传文件。
+2. 「表结构」→ 分析表结构。
+3. 「问答」页提问，或在任意对话中选择「数据问答」预设直接提问。
+4. 把满意的图表固定到「看板」；在「业务知识」补充词表、指标和样例，提高准确率。
+5. 「管理 → 推送渠道」添加飞书机器人；「告警与报告」配置自动任务；「成员与权限」开通飞书群提问。
+
+飞书应用机器人所需权限与长连接配置步骤见页面「成员与权限 → 飞书机器人 → 飞书开放平台配置步骤」。
+
+## 数据与隐私
+
+| 内容 | 位置 |
+|---|---|
+| 配置（数据源、看板、知识、告警、成员、设置） | `~/.dsh/nl2sql/state.json` |
+| 查询结果、缓存、快照、日志（历史 / 审计 / 反馈 / 推送 / 告警） | `~/.dsh/nl2sql/results.sqlite` |
+| 上传的文件 | `~/.dsh/nl2sql/files/` |
+| 数据库密码、飞书密钥 | Harness 凭据库 |
+
+发给模型的内容由「设置 → 模型可见数据」决定：默认只发表结构、枚举字段取值和查询结果的统计摘要，不发明细行。推送到飞书的内容会离开本机。
+
+## 开发
+
+```bash
+npm test                      # 全部测试（需要 Harness 桌面版作为 Node 运行时；本机 MySQL / PostgreSQL 可选，不可用时跳过）
+npm test -- --fast            # 仅单元测试和界面测试
+node scripts/build-client.mjs # 修改 client-src/ 后生成 lib/client.js
+node scripts/build-echarts.mjs
+```
+
+目录结构与约定见 [DEVELOPMENT.md](DEVELOPMENT.md)；隔离的准确率评测环境见 [eval/README.md](eval/README.md)。
+
+## 已知限制
+
+- 告警和每日表结构检查在 Harness 进程内调度：Harness 关闭期间不检查，重新打开后补查一次。
+- 行级权限只对飞书成员生效；本机页面始终是所有者权限，没有登录机制。
+- 行级权限下不支持子查询、CTE、UNION（会被拒绝）。
+- 不支持旧版 `.xls`。
+
+## 许可证
+
+[MIT](LICENSE)