@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.0

package/README.md

@@ -1,121 +1,158 @@
 # @chengxianglibra/dsh-data-analysis
 
-由个人维护的 DeepSeek Harness 社区插件，并非 DeepSeek 官方发行或维护的软件包。
+在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 中，用自然语言完成数据分析，
+浏览和复用业务指标定义，并将结果整理为可交互、可离线阅读的图表、报告和看板。
+语义分析能力由 [Marivo](https://github.com/chengxianglibra/marivo) 提供；本地文件也可直接使用 pandas 或 DuckDB。
 
-DeepSeek Harness 的 Marivo 集成插件。当前包提供：
+本项目是个人维护的社区插件，并非 DeepSeek 官方发行或维护的软件。
 
-- 精确 Marivo 0.5.4 共享 Runtime 与 zero-init per-Workspace binding；
-- `marivo_help` 实时公共 Help transport；
-- 会话标题旁的“语义层”对象浏览器：Workspace 分类搜索、只读详情与局部关系图；
-- `marivo_datasource_test` 的 DSH Credentials 收集与显式 connection test；
-- `marivo_python` 的本次执行准入与单次 resolver 凭证注入；
-- 会话标题旁的“数据源与凭证”管理、测试与缺失输入提交后的原调用续接；
-- `marivo_present({ draft_path })` 的一次文件提交、结果卡片、打开与离线 HTML 下载；
-- 唯一插件 Skill `dsh-data-analysis-presentation`，组织图表、表格、报告、看板与可读来源展示；
-- `dsh_data_analysis_presentation.write_dataset(frame, path)` 的 computed typed JSON writer；
-- 内部 Artifact/computed/source-only 数据投影，保存精确来源及 unavailable 状态。
+## 安装
 
-共享 reader、离线 builder、`marivo_present` 和展示 Skill 提供统一的展示交付；
-两个 Marivo Runtime Skill `marivo-analysis`、`marivo-semantic` 继续从当前 Runtime 挂载。
-旧 report-kit、report Skill、经典 JS 与 Evidence 卡协议不再分发。升级说明见
-[0.1.2 发布说明](../../docs/releases/0.1.2.md)。
+### 环境准备
 
-## Compatibility
+- Node.js `^22.19.0 || >=24.0.0`，与 DeepSeek Harness 一致：22.x 需至少 22.19.0，或使用 24.0.0 及以上版本；不支持 23.x。
+- 已安装并配置好 DeepSeek Harness `>=0.1.5-rc.1`（rc.1 验收状态见验证指南；范围内未来版本不视为已验收）。
+- `pnpm` 可在命令行中使用，供 Harness 安装插件。
+- 已安装 Python 3.10+，命令行可运行 `python3`（Windows 为 `python`），且支持 `venv`/`ensurepip`；部分 Linux 发行版需额外安装 `python3-venv`。
 
-包内 `dshDataAnalysisCompatibility` 是唯一运行时兼容声明：
+默认安装方式会在首次启动时使用本机 Python 创建独立的虚拟环境，并通过 pip 安装 Marivo，无需预装 Marivo 或 uv。
+首次启动需要联网下载依赖，请等待环境准备完成。
 
-- DSH distribution 与所有必需 peer 精确使用 `0.1.1-rc.2`；
-- Runtime 通过 pip 安装已发布的 Marivo 0.5.4；版本约束为 `marivo[duckdb,trino,clickhouse]==0.5.4`；
-- 项目自有 Runtime marker 为 `dsh-data-analysis-runtime/v3`；
-- 子进程策略为 `direct-argv-inherited-env-snapshot-overlay-v2`。
+### 安装并启动
 
-管理员解释器的 `marivo.__version__` 与 package identity 必须精确匹配；不使用 capability/version matrix。
+将插件安装到 Web Profile：
 
-## Tool contracts
-
-```text
-marivo_help({ targets: string[] })
-marivo_datasource_test({ name: string })
-marivo_python({ code: string, datasources: string[] })
-marivo_present({ draft_path: string, report_id?: string, expected_build_id?: string })
+```bash
+dsh plugin --profile web add @chengxianglibra/dsh-data-analysis
 ```
 
-`marivo_datasource_test` 只拥有缺失 Credentials 的 DSH/Web 闭环和显式连接测试；
-`marivo_python` 在本次调用内等待全部数据源凭证就绪、核验身份并取得 fresh snapshot，再通过 DSH 前台
-执行服务与 Marivo 公开 resolver 启动一次代码。配置齐全时不额外测试；普通 Shell 不获得凭证。
-缺失输入时默认等待 Web 表单，提交测试成功后继续原调用；取消、轮换或 Workspace 变化终止旧准备，
-已启动代码失败不重放。无 Web 场景配置 `credentialInteraction: 'none'`，subagent 同样不等待表单。
-详见[凭证模块](../../docs/modules/datasource-credentials.md)。`md.inspect(...)`、
-Session recovery、Artifact revalidation、Quality、Evidence 读取、Session Graph 与 `to_pandas()` 都直接使用
-Marivo 公共 API，不增加 convenience Tool。
-
-## 语义层对象浏览器
-
-点击 DSH 会话标题旁的“语义层”，默认查看该会话所属 Workspace，也可在面板内显式切换 Workspace。
-可按业务域和类型筛选，搜索名称、引用与业务定义，
-复制对象引用、查看定义位置，并在对象关系中逐层浏览。桌面采用三栏布局，窄屏支持列表与详情切换。
-
-页面不要求 live Agent，只读取 Marivo Catalog 元数据，不执行 `observe`、数据预览或连接测试。
-打开和手动刷新重新加载；读取失败时明确标注上次成功内容。数据源连接配置、凭证值与原始源码不展示。
-使用及验收边界见[模块说明](../../docs/modules/semantic-browser.md)。
-
-“数据源与凭证”位于同一会话标题旁，打开时同样使用该会话所属 Workspace，面板内保留 Workspace 选择。
-两个入口随 Harness 的会话标题显示，无会话或空会话时不显示，侧栏底部不保留入口。
-
-## 分析与展示
-
-普通事实问答使用文字。图表、表格、报告、看板和可读来源展示加载 `dsh-data-analysis-presentation`，
-按 Skill 编写 Workspace 相对 Draft，再调用 `marivo_present`。已有 Artifact 或 computed 数据无需先激活
-`marivo-analysis`；需要新分析或语义编写时，按需加载对应 Runtime Skill 与 live Help。
-Skill 只指导内容组织、声明来源和交付，不承担分析计算或来源有效性判断；布局由 reader 自适应。
-完整流程见[展示 Skill](../../docs/modules/presentation-skill.md)。
-
-Python helper 的可选 `labels={列名: 展示名}` 设置中文表头、图例和 tooltip，字段绑定仍使用原列名。
-Python helper 只接受 pandas DataFrame，写入 `schemaVersion: 1` 的 typed JSON；int64/Decimal 保留精确字符串，
-null 保留缺失含义，datetime 必须带时区。它不保存来源或转换代码；来源在展示 Draft 中声明。
-固定 projection 从同一 bound Workspace 恢复 persisted Artifact 和可选 Finding，不自动 observe、revalidate 或读取凭据。
-直接 Artifact dataset 缺必要数据会失败，computed 和 source-only 可以保留 unavailable 来源。
-
-共享 reader 展示 Markdown、metric、18 类 chart、table 和 source，保留精确值、单位、截断与 unavailable 来源。chart 支持 bar/line 变体与当前页面的字段、图形及过滤探索；统计量由分析阶段准备，探索不改写保存快照。
-`marivo_present` 读取 Workspace 相对 Draft 路径，生成不可变新 build 的 JSON/自包含 HTML。
-默认创建新 Report；修改已有报告时成对传入 `report_id` 与本次修改所基于的 `expected_build_id`，以完整 Draft 更新同一 Report。
-版本冲突时读取当前保存内容并合并需保留的编辑，不强行覆盖，也不回退新建。
-原卡片通过 reportId 打开最近保存结果；阅读器可编辑标题、正文、指标标签、图表和表格配置，以及移动／删除 cell（允许删空），支持撤销／重做和保存／取消。
-保存生成同报告的新 build，保留底层数据、来源和代码，不运行 Agent 或 Python。
-全部 18 种 chart 与同 dataset 的表格和数据预览共享临时筛选；筛选不重算指标、不标记编辑修改、不进入保存、下载或打印。
-文档、receipt 与 delivery 使用 schema v2，Draft 和 typed dataset 保持 v1；旧报告不读取、不迁移，旧文件保留。文本始终包含两份文件的位置、digest 和字节数，headless 也能取得交付物。
-展开来源仅使用保存的快照；文件变化、缺失或 Workspace 归属变化会明确失败。
-实现与验收见[展示数据投影](../../docs/modules/presentation-projection.md)、[展示 reader](../../docs/modules/presentation-reader.md)、
-[展示交付](../../docs/modules/presentation-delivery.md)。
-
-## 验证
+安装后启动 Web Profile；如果已在运行，请先退出再重新启动：
 
 ```bash
-npm run check
-npm run build
-npm run verify:plugin-package
+dsh --profile web
+```
+
+在 Web 界面选择分析使用的工作区（Workspace），新建会话并发送一条消息。
+会话标题旁按顺序显示“数据源”“语义层”“报告”三个入口，浏览页面在原生右侧标签页打开。本文以 Web 界面为例。
+
+### 本地文件分析
+
+上传文件后直接提问，或指定 Workspace 中已有文件。助手可在插件绑定的 Python 环境中使用 pandas
+或原生 DuckDB 分析 CSV、JSON、Parquet，无需先配置数据源或建立语义模型；需要时可继续生成报告。
+默认安装包含 Marivo 的 `duckdb` extra（同时保留 `trino`、`clickhouse`）。Excel `.xlsx` 通过 DuckDB 的
+[excel 扩展](https://duckdb.org/docs/stable/core_extensions/excel.html)读取；首次使用需要联网下载扩展，
+并允许写入 DuckDB 扩展缓存。它不是额外的 Python 包，无需为此安装 `openpyxl`。
+旧版 `.xls` 不在该扩展支持范围内，需要先转换为 `.xlsx`、CSV 或 Parquet。
+
+纯文件分析无需经过 Marivo `md.raw_sql`。下面的数据源配置流程适用于数据库连接和需要复用的 Marivo 数据源。
+
+## 能力
+
+| 你想做什么 | 插件提供的能力 |
+| --- | --- |
+| 回答业务问题 | 用自然语言提出问题，分析指标趋势、比较不同时间或业务分组、探索变化原因 |
+| 分析本地文件 | 复用原生附件路径，以 pandas 或 DuckDB 直接计算，并按需交付图表或报告 |
+| 连接数据 | 配置数据源、管理连接凭证并测试连接；默认包含 DuckDB、Trino、ClickHouse 支持 |
+| 统一分析口径 | 与 Agent 一起整理和复用指标、维度等业务定义，浏览语义对象及其关系 |
+| 明确分析对象 | 在输入框通过 `@` 搜索并引用已有语义对象 |
+| 展示分析结果 | 生成包含文字、指标卡、图表、表格和来源说明的报告或看板 |
+| 阅读与分享 | 交互筛选、调整呈现、保存版本，并下载 HTML 离线阅读 |
+
+## 如何使用
+
+### 1. 准备数据源
+
+在会话标题旁打开“数据源”，查看所属工作区的连接属性与配置状态：
+
+1. 点击“新增数据源”，选择引擎，按表单填写名称及连接信息。
+2. 如果需要身份认证，在同一表单的“连接凭证”中直接填写用户名、密码或令牌。
+3. 测试连接，根据结果检查地址、凭证或访问权限。
+
+凭证引用名自动生成，可展开“凭证引用名 · 确认或修改”查看和调整；也可填写已有引用，并将值留空以复用凭证。
+编辑时已保存的凭证值不回显，留空沿用；填写新值默认使用新的引用，不删除旧的共享凭证。
+手动指定已存在的引用并填写新值时，不会自动覆盖，需到凭证页确认更新。
+已有数据源可点击“编辑配置”修改连接信息，名称和引擎保持不变；保存后重新测试。
+
+管理员可在 Harness 当前 profile 的本插件配置项下设置 `datasourceDefaults`，按引擎类型为新建表单填入默认值：
+
+```yaml
+datasourceDefaults:
+  trino:
+    host: trino.internal.example
+    port: 443
 ```
 
-当前架构与验收边界见仓库根目录的[总体架构](../../docs/architecture.md)和
-[展示交付](../../docs/modules/presentation-delivery.md)。
+这是插件配置片段，随 Harness 现有配置加载机制生效；不是独立配置文件。未指定的字段保持原样，用户可修改或清空填充值；
+切换引擎时清空表单并应用目标引擎的默认值。编辑或复用已有数据源不应用这些默认值。
+只配置非敏感普通字段，不能设置 `*_env` 凭据引用或凭据值；内部地址只保存在部署环境的配置中，不必加入插件源码。
+打开新建表单时按当前 Runtime 校验引擎、字段和类型，错误会明确显示且不回显配置值；配置错误不阻止已有数据源编辑。
+
+分析需要新增或修复数据源时，助手可自动打开所属会话的右侧配置页。填写后点击“保存并测试，成功后继续”；
+缺少凭证时继续在凭证表单补齐，测试成功后原调用返回，助手再核验目标表并继续分析。
+请求页默认显示新增表单；切换“使用已有数据源”后，可选择已有连接并验证，无需重复创建。测试失败保留已保存的配置，允许修正后重试；取消请求不会作为成功继续。
+
+更新插件后，如果旧浏览器页面中工具正在等待、却没有打开配置 Tab，也没有“待配置”入口，
+先刷新浏览器页面以加载当前客户端。仍存活的原请求会重新显示；刷新页面不等于重启 Host。
+若原调用已取消或 Host 已重启，需要重新发起配置请求。
+请通过凭证表单提交密码或令牌，不要粘贴到聊天消息中。
+
+### 2. 用自然语言提出分析问题
+
+说明使用哪些数据、时间范围、指标口径和希望得到的结果。例如：
+
+> 使用订单数据，分析 2026 年 8 月的销售额和订单量，与 7 月比较，按渠道拆分，并说明数据来源和口径。
+
+> 检查最近七天的查询耗时，找出耗时最高的查询类型，给出趋势图和明细表。
+
+如果还没有整理业务定义，可以先让 Agent 帮助梳理：
+
+> 先查看当前数据源中有哪些订单相关表，和我确认销售额、支付订单数的统计口径，再保存为可复用的业务定义。
+
+需要报告时，直接说明希望的内容：
+
+> 将这次分析整理为一份报告，包含结论、关键指标、趋势图、渠道对比表和来源说明，并提供可下载的 HTML。
+
+### 3. 浏览和引用业务定义
+
+点击会话标题旁的“语义层”，按分类或关键词查找指标、维度等对象，查看业务定义和对象关系。
+这里展示已有定义；浏览页面不会执行分析查询。浏览页固定属于入口所在会话的工作区，支持把语义对象独立打开。
+
+在聊天输入框输入 `@` 可搜索并选择当前工作区的对象；多词搜索可输入 `@"monthly revenue"`。
+选中后将显示完整的 `kind:path` 引用，便于 Agent 使用你指定的对象开展分析。
+
+### 4. 阅读、调整和追问报告
+
+当前会话交付新报告后，右侧自动打开该次交付的固定版本；后台完成、历史回放和重连不会抢占阅读页面。
+同工作区的后台交付会更新已打开的报告目录，并在 current 页提示新版本，保留正在阅读的内容。
+报告生成后自动在右侧 tab 打开固定版本，主对话不附加报告 block。默认只保存 JSON，点击下载或显式调用导出工具时才生成 HTML。“报告”目录按标题查找并打开 current；可以并排阅读不同报告和版本。
+
+用户要求离线 HTML 文件时，DSH 可直接调用 `marivo_export_html({ report_id, build_id?, output_path })`，例如输出到 `reports/analysis.html`。省略 `build_id` 时固定调用开始时的 current；指定时导出该历史版本。输出是完整、自包含且可交互的报告，不含未保存编辑或临时筛选。路径必须位于当前 Workspace，已有文件不会覆盖；导出不需要 Python、数据源或发布配置。成功返回实际路径、Build ID、字节数和 SHA-256；DSH 随后通过原生 `present({ files: [{ path, description }] })` 交付该文件。
+发现新版本时 current 先提示，点击刷新或重新打开才切换，旧版本筛选随切换重置。
+没有活动会话时，侧栏的“报告”入口仍可阅读 Workspace 中的报告。
+
+- **探索数据**：筛选图表和表格，调整支持的图形及展示字段。交互使用报告中已保存的数据；获取新数据或重新计算时，在会话中提出要求。
+- **查看来源**：查看报告内容附带的来源信息，核对分析依据。
+- **调整呈现**：从 current 页点击“编辑报告”，在原编辑窗口编辑标题、正文、指标标签和图表／表格配置，移动或删除内容，支持撤销、重做和保存。
+- **继续追问**：在支持的报告内容菜单中选择“加入提问”，在输入框插入 `# <cell名称>` 引用标签，补充问题后发送；完整上下文会随引用一起提交。
+- **查看历史**：保存编辑后可在历史侧栏查看和下载已保存的版本，历史版本只读。
+
+页面筛选不会重新计算指标卡，也不会写入保存的报告。希望保留当前筛选结果时，使用“导出当前视图”。
+
+### 5. 下载与分享
+
+报告右上角的导出菜单提供两种方式：
 
-## 语义对象引用
+| 选项 | 适合的用途 |
+| --- | --- |
+| 下载完整报告 | 下载所查看版本的完整 HTML 报告，供离线阅读 |
+| 导出当前视图 | 将当前筛选、图形和表格排序固定为 HTML，附带来源版本及导出时间，分享当前看到的内容 |
 
-在 Web 输入框输入 `@` 选择当前 Workspace 的 Marivo 对象；多词检索使用 `@"monthly revenue"`。
-选中后显示完整 `kind:path`，提交只携带精确 ref。最近七个自然日热度保存在 DSH profile；候选缓存为 30 秒。
-对象有效性由执行时 Marivo Catalog 验证，删除对象不会被相似对象自动替换。
+编辑模式下，请先保存或取消编辑再导出。下载的文件可直接用浏览器打开。
 
+## 许可证
 
-## 草稿静态预检
+本项目采用 [MIT License](LICENSE)。
 
-在 Workspace 根目录运行 `dsh-data-analysis-presentation-lint analysis/presentation.draft.json`，
-或通过 `--project-root PATH` 显式指定 Workspace。CLI 复用 present 的草稿与 TypedDataset 校验及文件边界，
-检查草稿结构和引用的 computed JSON；不启动 Runtime、不执行分析、不生成报告文件。
-输出 JSON 的 `ok` 仅表示这些静态检查通过；`deferredChecks` 列出仍由 `marivo_present` 完成的
-Artifact 可用性与数据、codeRefs、投影后文档与渲染检查。退出码为 0（通过）、1（校验失败）、2（参数错误）。
-草稿结构通过后逐份检查 computed 文件，每份保留首个错误，修正后可再次预检。
+## 报告发布到对象存储
 
-int64 单元格必须是精确整数字符串，例如 `"42"`；JSON number `42` 也不接受。
-诊断保留 JSON pointer，并显示 `column query_count type=int64`、原因与修复建议。
-超过 JS 安全整数范围的 number 可能已舍入，不能转成字符串来恢复精度；应从原始精确数据重写，
-或使用绑定 Runtime 中的 `write_dataset`。预检通过不等于成功交付，仍需 present 的成功 receipt。
+通过 `reportPublishing.enabled` 开启 S3 兼容对象存储发布；在“数据源与凭证”管理独立 AK/SK 和可选 Token。开启后报告菜单的完整 HTML 与当前视图下载均替换为发布，成功返回链接。配置示例与边界见[报告 HTML 发布](../../docs/modules/report-publishing.md)。

package/cordis.patch.yml

@@ -1,5 +1,5 @@
 # Web-profile Marivo disclosure layer. One profile-owned plugin installation
-# serves every Agent and session Workspace in native, code, or both mode.
+# serves every Agent and session Workspace in native, ptc, or both mode.
 
 - insert:
     - id: dsh-data-analysis

package/lib/bin/environment.js

@@ -5,7 +5,7 @@ import { MarivoEnvironmentError } from "../environment/errors.js";
 import { ensureSharedMarivoRuntime, MarivoWorkspaceEnvironmentManager, } from "../environment/index.js";
 import { environmentPayload } from "../environment/summary.js";
 function usage() {
-    return `Usage: dsh-data-analysis-env [--project-root PATH] [--python PATH] [--runtime-root PATH] [--uv PATH]
+    return `Usage: dsh-data-analysis-env [--project-root PATH] [--python PATH] [--runtime-root PATH] [--bootstrap-python PATH]
 
 Ensures the shared pinned Marivo and presentation-kit Runtime, initializes the minimal
 Workspace layout, and checks the exact interpreter, import identities, and doctor
@@ -23,7 +23,7 @@ function parseArguments(argv) {
     let projectRoot = process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ?? process.env.DSH_CWD ?? process.cwd();
     let pythonExecutable = process.env.DSH_DATA_ANALYSIS_PYTHON;
     let runtimeRoot = process.env.DSH_DATA_ANALYSIS_RUNTIME_ROOT;
-    let uvExecutable = process.env.DSH_DATA_ANALYSIS_UV;
+    let bootstrapPythonExecutable = process.env.DSH_DATA_ANALYSIS_BOOTSTRAP_PYTHON;
     for (let index = 0; index < argv.length; index++) {
         const option = argv[index];
         if (option === '--help' || option === '-h')
@@ -43,8 +43,8 @@ function parseArguments(argv) {
             index++;
             continue;
         }
-        if (option === '--uv') {
-            uvExecutable = requireValue(argv, index, option);
+        if (option === '--bootstrap-python') {
+            bootstrapPythonExecutable = requireValue(argv, index, option);
             index++;
             continue;
         }
@@ -54,7 +54,7 @@ function parseArguments(argv) {
         projectRoot,
         ...(pythonExecutable === undefined ? {} : { pythonExecutable }),
         ...(runtimeRoot === undefined ? {} : { runtimeRoot }),
-        ...(uvExecutable === undefined ? {} : { uvExecutable }),
+        ...(bootstrapPythonExecutable === undefined ? {} : { bootstrapPythonExecutable }),
     };
 }
 async function main(argv) {
@@ -74,7 +74,9 @@ async function main(argv) {
         const runtime = await ensureSharedMarivoRuntime({
             ...(args.pythonExecutable === undefined ? {} : { pythonExecutable: args.pythonExecutable }),
             ...(args.runtimeRoot === undefined ? {} : { runtimeRoot: args.runtimeRoot }),
-            ...(args.uvExecutable === undefined ? {} : { uvExecutable: args.uvExecutable }),
+            ...(args.bootstrapPythonExecutable === undefined
+                ? {}
+                : { bootstrapPythonExecutable: args.bootstrapPythonExecutable }),
         });
         const manager = new MarivoWorkspaceEnvironmentManager(runtime);
         const environment = await manager.resolve(args.projectRoot);

package/lib/client/credentials/changes.js

@@ -0,0 +1,74 @@
+import { credentialChangesRemote, } from "../../datasource/changes-contract.js";
+/** Mount before opening a logical stream, using the existing Gateway WebSocket. */
+export function credentialChanges(ctx) {
+    const mounted = ctx.remote.$mount(credentialChangesRemote);
+    // Initialization may be withdrawn before a Session starts consuming the mount.
+    void mounted.catch(() => { });
+    ctx.effect(() => async () => (await mounted)());
+    // Host and browser Context augmentations share this build; use the browser contract here.
+    const connection = ctx.connection;
+    return (sessionId) => {
+        let snapshot;
+        const stopConnection = connection.generation.subscribe(() => {
+            if (!connection.generation.getSnapshot())
+                snapshot?.abort();
+        });
+        const stream = ctx.remote.$stream({
+            name: 'dsh-data-analysis credential changes',
+            async *open(signal) {
+                const current = new AbortController();
+                snapshot = current;
+                try {
+                    await mounted;
+                    signal.throwIfAborted();
+                    // A dynamically mounted namespace needs its own declared Cordis consumer.
+                    let namespace;
+                    const consumer = ctx.inject(['remote.dshDataAnalysisCredentials'], (scoped) => {
+                        namespace = scoped.remote.dshDataAnalysisCredentials;
+                    });
+                    const stop = () => {
+                        void consumer.dispose();
+                    };
+                    signal.addEventListener('abort', stop, { once: true });
+                    if (signal.aborted)
+                        stop();
+                    try {
+                        await consumer;
+                        signal.throwIfAborted();
+                        if (!namespace)
+                            throw new Error('credential-notification-unavailable');
+                        yield* namespace.changes(sessionId, signal);
+                    }
+                    finally {
+                        // Abort snapshots before RemoteStream starts waiting for reconnection.
+                        current.abort();
+                        signal.removeEventListener('abort', stop);
+                        await consumer.dispose();
+                    }
+                }
+                finally {
+                    current.abort();
+                }
+            },
+            carrierFailed: () => snapshot?.abort(),
+            ended: () => new Error('credential-notification-ended'),
+        });
+        const dispose = async () => {
+            stopConnection();
+            snapshot?.abort();
+            await stream.dispose();
+        };
+        return {
+            async *[Symbol.asyncIterator]() {
+                try {
+                    for await (const item of stream)
+                        yield { ...item, signal: AbortSignal.any([item.signal, snapshot.signal]) };
+                }
+                finally {
+                    await dispose();
+                }
+            },
+            dispose,
+        };
+    };
+}

package/lib/client/credentials/create-datasource.js

@@ -1,67 +1,171 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // @ts-nocheck -- JSX is bundled by the plugin client build.
-import { useEffect, useState } from 'react';
-export function CreateDatasource({ model, workspaceId, close }) {
+import { useEffect, useId, useRef, useState } from 'react';
+import { useCopy } from "./../i18n/context.js";
+import { errorMessage, message } from "./../i18n/copy.js";
+import { credentialReference, prepareCredentials } from "./credential-draft.js";
+import { creationFieldValues } from "./defaults.js";
+import { datasourceDescription } from "./descriptions.js";
+function credentialLabel(field) {
+    return ({
+        user_env: 'marivo.credentials.username',
+        password_env: 'marivo.credentials.password',
+        http_bearer_token_env: 'marivo.credentials.access-token',
+        http_headers_env: 'marivo.credentials.header-credential-value',
+    }[field] ?? field.replace(/_env$/, ''));
+}
+function credentialRows(schema, backend, values = {}) {
+    return (schema.backends.find((item) => item.name === backend)?.fields ?? [])
+        .filter((field) => field.name.endsWith('_env'))
+        .flatMap((field) => field.type === 'json'
+        ? Object.entries(values[field.name] ?? {}).map(([key, existing]) => ({
+            id: crypto.randomUUID(),
+            field: field.name,
+            key,
+            existing,
+            value: '',
+        }))
+        : [{ id: crypto.randomUUID(), field: field.name, existing: values[field.name], value: '' }]);
+}
+export function CreateDatasource({ model, workspaceId, close, name, requestId }) {
+    const t = useCopy();
+    const formId = useId();
+    const active = useRef(false);
     const [schema, setSchema] = useState(null);
+    const [original, setOriginal] = useState(null);
     const [backend, setBackend] = useState('');
     const [values, setValues] = useState({});
+    const [credentials, setCredentials] = useState([]);
     const [busy, setBusy] = useState(false);
     const [error, setError] = useState('');
     useEffect(() => {
         const controller = new AbortController();
-        model
-            .authoring(workspaceId, controller.signal)
-            .then((value) => {
+        active.current = true;
+        Promise.all([
+            model.authoring(workspaceId, controller.signal, name ? 'edit' : 'create'),
+            name ? model.configuration(workspaceId, name, controller.signal) : Promise.resolve(null),
+        ])
+            .then(([value, configuration]) => {
             if (controller.signal.aborted)
                 return;
             setSchema(value);
-            setBackend(value.backends[0]?.name ?? '');
+            setOriginal(configuration);
+            setBackend(configuration?.backend ?? value.backends[0]?.name ?? '');
+            setCredentials(credentialRows(value, configuration?.backend ?? value.backends[0]?.name, configuration?.fields));
+            if (!configuration)
+                setValues(creationFieldValues(value, value.backends[0]?.name ?? ''));
+            if (configuration) {
+                const fields = value.backends.find((item) => item.name === configuration.backend)?.fields;
+                if (!fields)
+                    throw new Error('marivo.credentials.this-runtime-cannot-fully-edit-this-datasource');
+                setValues(Object.fromEntries(fields
+                    .filter((field) => !field.name.endsWith('_env') && configuration.fields[field.name] !== undefined)
+                    .map((field) => [
+                    field.name,
+                    field.type === 'string'
+                        ? configuration.fields[field.name]
+                        : JSON.stringify(configuration.fields[field.name]),
+                ])));
+            }
         })
             .catch((error) => {
             if (!controller.signal.aborted)
-                setError(error.message);
+                setError(errorMessage(error));
         });
-        return () => controller.abort();
-    }, [model, workspaceId]);
+        return () => {
+            active.current = false;
+            controller.abort();
+        };
+    }, [model, workspaceId, name]);
     const fields = schema?.backends.find((item) => item.name === backend)?.fields ?? [];
+    const credentialFields = fields.filter((field) => field.name.endsWith('_env'));
+    const updateCredential = (id, change) => setCredentials((rows) => rows.map((row) => (row.id === id ? { ...row, ...change } : row)));
     async function submit(event) {
         event.preventDefault();
         if (busy)
             return;
         setError('');
         const input = {};
+        let changes = {};
         try {
-            for (const field of fields) {
+            for (const field of fields.filter((field) => !field.name.endsWith('_env'))) {
                 const value = values[field.name];
-                if (value === undefined || value === '')
+                if (value === undefined)
+                    continue;
+                if (value === '' &&
+                    (field.type !== 'string' ||
+                        (name
+                            ? original?.fields[field.name] !== ''
+                            : schema.creationDefaults?.[backend]?.[field.name] !== '')))
                     continue;
                 input[field.name] = field.type === 'string' ? value : JSON.parse(value);
             }
+            const prepared = prepareCredentials(input.name ?? '', credentials);
+            Object.assign(input, prepared.fields);
+            changes = prepared.changes;
         }
-        catch {
-            setError('请检查数字、布尔值或 JSON 字段的格式。');
+        catch (error) {
+            setError(error instanceof SyntaxError
+                ? 'marivo.credentials.check-the-format-of-number-boolean-and-json-fields'
+                : errorMessage(error));
             return;
         }
         setBusy(true);
+        // Remove secrets from mounted inputs as soon as the explicit submission begins.
+        setCredentials((rows) => rows.map((row) => ({ ...row, value: '' })));
         try {
-            await model.createDatasource(workspaceId, schema, { backend, fields: input });
-            close();
+            await model.saveConfiguration(workspaceId, schema, { backend, fields: input }, original, requestId, changes);
+            if (active.current)
+                close();
         }
         catch (error) {
-            setError(error.message);
+            if (active.current)
+                setError(message('marivo.credentials.value-credential-inputs-have-been-cleared-enter-them-again', {
+                    p0: errorMessage(error),
+                }));
         }
         finally {
-            setBusy(false);
+            for (const ref of Object.keys(changes))
+                delete changes[ref];
+            if (active.current)
+                setBusy(false);
         }
     }
-    return (_jsxs("form", { className: "mc-form", "aria-label": "\u65B0\u589E\u6570\u636E\u6E90", onSubmit: submit, children: [_jsxs("div", { className: "mc-form-body", children: [_jsx("div", { className: "mc-detail-heading", children: _jsx("h3", { children: "\u65B0\u589E\u6570\u636E\u6E90" }) }), error && (_jsx("p", { role: "alert", className: "mc-result", "data-tone": "error", children: error })), !schema && !error && _jsx("p", { role: "status", children: "\u6B63\u5728\u8BFB\u53D6\u6570\u636E\u6E90\u914D\u7F6E\u5B57\u6BB5\u2026" }), schema && (_jsxs("fieldset", { className: "mc-field", disabled: busy, children: [_jsxs("label", { className: "mc-secret-input", children: ["\u5F15\u64CE", _jsx("select", { "aria-label": "\u5F15\u64CE", value: backend, onChange: (event) => {
+    return (_jsxs("form", { className: "mc-form", "aria-label": name ? t('marivo.credentials.edit-datasource') : t('marivo.credentials.add-datasource'), onSubmit: submit, children: [_jsxs("div", { className: "mc-form-body", children: [_jsx("div", { className: "mc-detail-heading", children: _jsx("h3", { children: name
+                                ? t('marivo.credentials.edit-datasource')
+                                : t('marivo.credentials.add-datasource') }) }), error && (_jsx("p", { role: "alert", className: "mc-result", "data-tone": "error", children: t(error) })), !schema && !error && (_jsx("p", { role: "status", children: t('marivo.credentials.loading-datasource-configuration-fields') })), schema && (_jsxs("fieldset", { className: "mc-field", disabled: busy, children: [_jsxs("label", { className: "mc-secret-input", children: [t('marivo.credentials.engine'), _jsx("select", { "aria-label": t('marivo.credentials.engine'), disabled: !!name, value: backend, onChange: (event) => {
                                             setBackend(event.target.value);
-                                            setValues({});
+                                            setValues(creationFieldValues(schema, event.target.value));
+                                            setCredentials(credentialRows(schema, event.target.value));
                                             setError('');
-                                        }, children: schema.backends.map((item) => (_jsx("option", { value: item.name, children: item.name }, item.name))) })] }), fields.map((field) => (_jsxs("label", { className: "mc-secret-input", htmlFor: `mc-create-${field.name}`, children: [_jsxs("span", { className: "mc-input-heading", children: [_jsxs("span", { className: "mc-input-name", children: [field.name, field.name.endsWith('_env') ? '（凭证引用名）' : '', field.required ? ' *' : ''] }), (field.description || field.name.endsWith('_env')) && (_jsxs("span", { className: "mc-input-description", children: [field.description, field.name.endsWith('_env') &&
-                                                        ' 填写引用名，如 MY_DB_PASSWORD；仅使用字母、数字和下划线，不能以数字开头。实际用户名或密码请在创建后的“新增凭证”中填写。'] }))] }), field.type === 'boolean' ? (_jsxs("select", { id: `mc-create-${field.name}`, "aria-label": field.name, value: values[field.name] ?? '', onChange: (event) => setValues({ ...values, [field.name]: event.target.value }), children: [_jsxs("option", { value: "", children: ["\u9ED8\u8BA4", field.default == null ? '' : ` (${field.default})`] }), _jsx("option", { value: "true", children: "true" }), _jsx("option", { value: "false", children: "false" })] })) : (_jsx("input", { id: `mc-create-${field.name}`, "aria-label": field.name, required: field.required, autoComplete: "off", type: field.type === 'number' ? 'number' : 'text', placeholder: field.default == null
+                                        }, children: schema.backends.map((item) => (_jsx("option", { value: item.name, children: item.name }, item.name))) })] }), fields
+                                .filter((field) => !field.name.endsWith('_env'))
+                                .map((field) => (_jsxs("label", { className: "mc-secret-input", htmlFor: `${formId}-${field.name}`, children: [_jsxs("span", { className: "mc-input-heading", children: [_jsxs("span", { className: "mc-input-name", children: [field.name, field.required ? ' *' : ''] }), field.description && (_jsx("span", { className: "mc-input-description", children: t(datasourceDescription(field.description)) }))] }), field.type === 'boolean' ? (_jsxs("select", { id: `${formId}-${field.name}`, "aria-label": field.name, value: values[field.name] ?? '', onChange: (event) => setValues({ ...values, [field.name]: event.target.value }), children: [_jsxs("option", { value: "", children: [t('marivo.credentials.default'), field.default == null ? '' : ` (${field.default})`] }), _jsx("option", { value: "true", children: "true" }), _jsx("option", { value: "false", children: "false" })] })) : (_jsx("input", { id: `${formId}-${field.name}`, "aria-label": field.name, required: field.required, disabled: !!name && field.name === 'name', autoComplete: "off", type: field.type === 'number' ? 'number' : 'text', placeholder: field.default == null
                                             ? field.type === 'json'
                                                 ? 'JSON'
                                                 : ''
-                                            : String(field.default), value: values[field.name] ?? '', onChange: (event) => setValues({ ...values, [field.name]: event.target.value }) }))] }, field.name)))] }))] }), _jsxs("div", { className: "mc-form-footer", children: [_jsx("button", { className: "mc-primary", type: "submit", disabled: !backend || busy, children: busy ? '正在新增…' : '确认新增数据源' }), _jsx("button", { type: "button", onClick: close, disabled: busy, children: "\u53D6\u6D88" })] })] }));
+                                            : String(field.default), value: values[field.name] ?? '', onChange: (event) => setValues({ ...values, [field.name]: event.target.value }) }))] }, field.name))), credentialFields.length > 0 && (_jsxs("section", { className: "mc-inline-credentials", "aria-label": t('marivo.credentials.connection-credentials'), children: [_jsx("h4", { children: t('marivo.credentials.connection-credentials') }), _jsxs("p", { className: "mc-note", children: [t('marivo.credentials.enter-credential-values-directly-for-harness-to-save-references'), name ? t('marivo.credentials.leave-blank-to-keep-the-current-value-a-new') : ''] }), credentialFields.map((field) => (_jsxs("div", { className: "mc-credential-group", children: [credentials
+                                                .filter((row) => row.field === field.name)
+                                                .map((row) => {
+                                                const label = credentialLabel(field.name);
+                                                const reference = credentialReference(values.name ?? '', row);
+                                                return (_jsxs("div", { className: "mc-credential-entry", children: [row.key !== undefined && (_jsxs("label", { className: "mc-secret-input", children: [t('marivo.credentials.header-name'), _jsx("input", { "aria-label": t('marivo.credentials.header-name'), value: row.key, onChange: (event) => updateCredential(row.id, { key: event.target.value }) })] })), _jsxs("label", { className: "mc-secret-input", children: [_jsxs("span", { className: "mc-input-heading", children: [_jsxs("span", { className: "mc-input-name", children: [t(label), field.required ? ' *' : ''] }), _jsx("span", { className: "mc-input-description", children: row.existing
+                                                                                ? t('marivo.credentials.a-reference-is-configured-leave-blank-to-keep-it')
+                                                                                : t('marivo.credentials.enter-the-value-directly-no-need-to-create-a') })] }), _jsx("input", { "aria-label": t(label), type: "password", autoComplete: "new-password", maxLength: 65536, required: field.required && !reference, value: row.value, placeholder: row.existing
+                                                                        ? t('marivo.credentials.leave-blank-to-keep-enter-a-new-value-to')
+                                                                        : t('marivo.credentials.enter-credential-value'), onChange: (event) => updateCredential(row.id, { value: event.target.value }) })] }), _jsxs("details", { className: "mc-reference-options", children: [_jsx("summary", { children: t('marivo.credentials.credential-reference-review-or-change') }), _jsxs("label", { className: "mc-secret-input", children: [field.name, _jsx("input", { "aria-label": field.name, autoComplete: "off", value: reference, placeholder: t('marivo.credentials.generated-after-entering-a-credential-value'), onChange: (event) => updateCredential(row.id, { reference: event.target.value }) })] }), _jsx("p", { className: "mc-note", children: t('marivo.credentials.to-reuse-a-saved-credential-enter-its-reference-and') }), row.reference !== undefined && (_jsx("button", { type: "button", onClick: () => updateCredential(row.id, { reference: undefined }), children: t('marivo.credentials.restore-automatic-reference') }))] }), row.key !== undefined && (_jsx("button", { type: "button", className: "mc-quiet", onClick: () => setCredentials((rows) => rows.filter((item) => item.id !== row.id)), children: t('marivo.credentials.remove-header') }))] }, row.id));
+                                            }), field.type === 'json' && (_jsx("button", { type: "button", onClick: () => setCredentials((rows) => [
+                                                    ...rows,
+                                                    { id: crypto.randomUUID(), field: field.name, key: '', value: '' },
+                                                ]), children: t('marivo.credentials.add-header-credential') }))] }, field.name)))] }))] }))] }), _jsx("p", { className: "mc-note", children: requestId
+                    ? t('marivo.credentials.save-configuration-and-credentials-then-test-the-connection-the')
+                    : name
+                        ? t('marivo.credentials.test-the-connection-again-after-saving-name-and-engine')
+                        : '' }), _jsxs("div", { className: "mc-form-footer", children: [_jsx("button", { className: "mc-primary", type: "submit", disabled: !backend || busy, children: busy
+                            ? t('marivo.credentials.saving-or-validating')
+                            : requestId
+                                ? t('marivo.credentials.save-and-test-then-continue')
+                                : name
+                                    ? t('marivo.credentials.save-configuration')
+                                    : t('marivo.credentials.confirm-new-datasource') }), _jsx("button", { type: "button", onClick: close, disabled: busy, children: t('marivo.credentials.cancel') })] })] }));
 }