@yejiming/dsh-data-agent 0.0.13 → 0.1.1

package/README.en.md

@@ -44,7 +44,7 @@ This package includes an experimental declaration for the [DSH Ecosystem Specifi
 | --- | --- |
 | Specification and stage | Community v0.15, Draft / Experimental |
 | Pinned baseline | `dsh-ecosystem-spec@ec80a4be5d92bbb971655afd0f097bb5586a1a28`; `dsh-std@614dfa1ac168db79fcf4577cf0ebb34e2e3b944b` |
-| Manifest | `dsh-plugin.json`, `manifestVersion: 0.15`, package identity `@yejiming/dsh-data-agent@0.0.13` |
+| Manifest | `dsh-plugin.json`, `manifestVersion: 0.15`, package identity `@yejiming/dsh-data-agent@0.1.1` |
 | Admission decision | The repository's eligible fixture is `compatible`; this is not an admission result from a real dsh-TUI Host |
 | Evidence level | `Parsed`; fixture negotiation is recorded only as `fixture-only` and does not become `Negotiated` evidence |
 | Exercised environment | Offline parser/projector/definition validation; disposable local mount/unmount with `@dsh-std/adapter-dsh@0.1.0-rc3` |
@@ -59,17 +59,45 @@ The plugin remains **trusted in-process** and is not sandboxed. Manifest permiss
 
 - **Analyze data through conversation**: Describe your goal in natural language. DSH understands the question, breaks it into analysis steps, queries real data, and organizes the conclusions. You can keep asking follow-up questions to explore the same context in greater depth.
 - **Discover business insights automatically**: Data Agent goes beyond returning query results. It helps compare trends, locate anomalies, identify valuable customers or products, and turn the data into explanations that support decisions.
+- **AI-assisted data governance**: Scan a database with the AI model configured in the current DSH session. Using tables, fields, comments, and relations, it generates candidate business meanings for every table and field. Every AI-generated candidate requires human review, and users can also add business terms and metric definitions manually. During later queries and analysis, Data Agent automatically reads the relevant definitions through the built-in `catalog-search`, `catalog-get`, and `metric-get` tools, grounding SQL and conclusions in governed business context.
 - **Cross-surface HTML reports (render-analysis)**: In an ordinary tool call, the agent can choose to produce a single chart or a Dashboard-style report (metric/line/bar/pie/scatter/table views). Every successful call saves an offline HTML file under `analysis-reports/` in the current workspace. Web also shows an inline preview and a “View analysis” Modal; dsh-tui returns the file path. Whether to chart remains the agent's decision — schema exploration, single scalars, and queries without visual value are never forced into charts.
 - **Shares the core path across Web UI and dsh-tui**: For a visual workflow, we recommend [zhu1090093659/dsh-web-ui](https://github.com/zhu1090093659/dsh-web-ui), where you can connect databases, browse schemas, and inspect results in the browser. For a keyboard-first workflow, we recommend [ccch1mneyyy/dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI), where you can use the same Data Mode, connect through `/database`, and move directly into conversational analysis. Both interfaces share the database service and tool protocol; validate the exact version and deployment separately.
 - **Connect common business databases**: Supports MySQL, PostgreSQL, SQLite, Oracle, Hive, Impala, ClickHouse, Apache Doris, and SQL Server across application databases, analytics systems, local data files, and data warehouses.
 - **Let DSH complete the analysis loop**: DSH inspects table structures, writes SQL, runs the query, and adjusts its approach based on errors or returned data instead of stopping at an unverified SQL draft.
-- **Stay focused with Data Mode**: The session uses DSH's native `str_replace_editor` for files and keeps `sql-query`, `sql-write`, `sql-cmd`, and `render-analysis`; Web, Desktop, dsh-tui, and headless profiles use the same tool protocol. Host or community tools such as `describe_image` and `ssh_*` do not leak into Data Mode.
+- **Stay focused with Data Mode**: The session uses DSH's native `str_replace_editor` for files and keeps `sql-query`, `sql-write`, `sql-cmd`, `render-analysis`, `catalog-search`, `catalog-get`, and `metric-get`; Web, Desktop, dsh-tui, and headless profiles use the same eight-tool protocol. Host or community tools such as `describe_image` and `ssh_*` do not leak into Data Mode.
 - **Work safely with real data**: Use read-only mode and a read-only database account when appropriate. TUI passwords are masked and are never restored as part of a form draft. You decide whether the session may modify data.
 
-The Web UI also includes an on-demand database workbench. Click the database button in the top-right of the composer to configure the connection, browse schemas, inspect columns, or run SQL in one Modal. MySQL browsing verifies each schema with the current account and hides only schemas that explicitly deny database access; authorized system and application schemas remain visible. Before and after the conversation starts, it no longer occupies the area above the composer or a left sidebar.
+![Data governance: AI-generated business meanings for tables and fields with human review](assets/data-governance.png)
+
+The Web UI also includes an on-demand database workbench. Click the database button in the top-right of the composer to use four tabs—Connection, Tables, Data Governance, and SQL—in one Modal. The Data Governance tab reads the independent persistent `data_agent_catalog@1` domain. Historical snapshots remain searchable after the live database disconnects; a new scan still requires a connection to the same stable profile.
 
 The SQL tab renders read-query results as a structured table with a sticky header, 100-row pages, and local horizontal scrolling for wide datasets. The complete loaded result can be exported as Excel (`.xlsx`), UTF-8 CSV, or copied to the clipboard, with a hard limit of 50,000 rows per query. Write/administrative commands and errors remain text messages instead of being misparsed as tables.
 
+### Data Catalog and metric governance
+
+A Catalog scan is an explicit human action. Its first stage reads database system catalogs only: it does not read business rows, persist sample rows, or run full-table `COUNT(*)` queries for exact counts. Its second stage uses the model currently configured in the initiating DSH session to generate table-level and field-level business-meaning candidates, one table at a time. The model receives only bounded technical metadata—names, types, nullable flags, database comments, keys, and relations—not sample values, query results, or credentials. Web offers full-source, schema, and single-table scopes in the Data Governance tab, with an extra confirmation for full scans. `/database` and `/catalog` are registered only when the current Cordis composition actually loads `@deepseek-harness-tui/dsh-tui`; the profile label is not consulted, so installing Data Agent or merely naming a profile `dsh-tui` never exposes them. A normal Web composition uses the database workbench instead. dsh-tui uses:
+
+Catalog metadata queries use an independent `catalogMaxResultChars` capture bound (32 MiB by default), so they no longer inherit the smaller `maxResultChars` budget used by ordinary SQL tools. Exceeding the Catalog-specific bound still fails safely with guidance to narrow the scope or adjust the configuration; a truncated snapshot is never published.
+
+```text
+/catalog scan                       Choose a scope interactively; reconfirm a full scan
+/catalog scan --all                 Explicit full-source scan
+/catalog scan --schema sales        Scan one schema
+/catalog scan --schema sales --table orders
+/catalog status [--run <run-id>]
+/catalog cancel [--run <run-id>]
+/catalog diff [--from <run-id> --to <run-id>]
+/catalog view                       Open the read-only full-screen Catalog browser
+```
+
+Scans run in the background, with at most one active run per source. When dsh-tui exposes its public extension services, a persistent line above the prompt follows the real “technical metadata → Catalog publish → AI business meanings” phases. Success, partial success, and failure remain visible until the next scan or `/catalog view`, instead of disappearing with a short notification. `/catalog view` opens a read-only full-screen scene: tables/views are paged on the left, while the selected table's summary, fields, and AI business meanings appear on the right. It supports search, independently scrolling panes, business-schema/all-schema switching, refresh, and Escape to return. Older dsh-tui versions without the public status/scene services keep the scan commands and explicitly fall back to `/catalog status` and the Web Catalog.
+
+Results are stored by stable profile, asset identity, and immutable revision. Unchanged assets do not duplicate revisions. Only a complete successful technical scan may mark absent objects `missing`, and only inside its exact scope. Table/schema scans do not alter out-of-scope assets or the last-full-scan time. Reappearing assets become `restored`. Failed, cancelled, interrupted, or permission-incomplete metadata runs never replace the previous successful snapshot, and ambiguous permission failures are not treated as deletions. AI enrichment has separate queued, running, succeeded, partial, failed, and cancelled states. Model output remains bounded; if a full-table response reaches the token limit, the same model configuration automatically retries smaller field batches and persists only after every field is complete. An AI failure does not erase a committed technical snapshot or publish an incomplete result for a table.
+
+Database facts are `observed`; AI-generated table/field meanings and candidate business terms or metrics are `inferred`. Only human review in Web can verify the current version as `verified`. The Data Catalog groups meanings by table and lets a user confirm or delete each table or field candidate. Delete creates an auditable retired revision, hides it from the default detail, and prevents later scans from reviving or overwriting the human decision. Structural changes mark affected definitions `needs_review` without auto-verifying them. For business analysis, the agent first uses read-only `catalog-search`, then `catalog-get` for technical context or `metric-get` for an exact metric version; it falls back to live schema inspection when the Catalog has no match. AI candidates, database comments, human text, and formulas are always untrusted reference data.
+
+The first release does not include scheduled scans, business-row sampling, AI auto-certification, external-catalog synchronization, complete lineage, Catalog-level RBAC, or physical deletion driven by a scan.
+
 ![Database workbench](assets/tables.webp)
 
 Choose “Data Mode” when creating a session, and DSH will use the data-analysis workflow for everything that follows.
@@ -92,7 +120,7 @@ dsh plugin --profile web add @yejiming/dsh-data-agent
 dsh plugin --profile web add github:omdsh-dev/dsh-data-agent
 ```
 
-The plugin installs the Data Mode preset automatically and preloads its database tools and command when the profile starts. Selecting the preset no longer performs dynamic package-subpath imports. No local build is required.
+The plugin installs the Data Mode preset automatically and preloads its database tools on every surface when the profile starts. `/database` and `/catalog` are enabled only by an actually loaded `@deepseek-harness-tui/dsh-tui` runtime, regardless of the profile name. Selecting the preset no longer performs dynamic package-subpath imports. No local build is required.
 
 ## Using Data Agent in the Web UI
 
@@ -109,6 +137,8 @@ Then:
 3. Once connected, ask an analysis question directly in the conversation.
 4. Follow up on the first result and ask DSH to narrow the scope, compare dimensions, or summarize the conclusions.
 
+A Web composition that does not load `@deepseek-harness-tui/dsh-tui` does not expose `/database` or `/catalog`; use the database workbench to connect, scan, cancel, and review Catalog content.
+
 For example, ask: “Analyze order changes over the last 30 days, identify the regions and products with the largest revenue decline, and explain the main causes.” DSH will inspect the relevant tables, generate and run the queries, and complete the analysis from real results.
 
 ### Analysis reports and HTML artifacts
@@ -124,7 +154,7 @@ Data Mode provides the render-analysis tool on every surface. The agent first ex
 
 ## Using Data Agent in dsh-tui
 
-Install Data Agent into the dsh-tui profile. `render-analysis` does not require a particular dsh-TUI version or scene capability:
+Install Data Agent into the dsh-tui profile. `render-analysis` does not require a particular dsh-TUI version or scene capability. Persistent Catalog status and full-screen result browsing activate automatically when dsh-tui exposes its public `status`/`scene` extension services:
 
 ```sh
 dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent
@@ -151,8 +181,14 @@ After connecting, return to the chat input and ask a business question. Other us
 /database status       Show the current connection
 /database test         Test the current connection
 /database disconnect   Disconnect the current database
+/catalog scan           Choose a scope and start a Catalog scan
+/catalog status [--run <run-id>]  Show the latest result or a specific run
+/catalog diff           Compare the latest two successful snapshots
+/catalog view           Open read-only Catalog results grouped by table
 ```
 
+You do not need to repeat `/catalog status` after a scan starts: the line above the prompt follows technical collection and AI-enrichment progress, then retains the final success/failure state. After completion, run `/catalog view`; use arrows or `j/k` to select and scroll, Tab or ←/→ to switch panes, `/` to search, `a` to switch between the business schema and all schemas, `r` to refresh, and Escape to return. The TUI remains read-only; confirm or delete AI candidates one at a time from Web's Data Governance tab.
+
 After the agent generates a report, the tool card shows dataset, view, empty-data facts, and the absolute HTML path. TUI does not print a character Dashboard and does not register `/analysis`; open the HTML in a local browser to inspect all six view types and raw data. The file belongs to that tool call, and `/resume` does not re-query the database.
 
 When you reopen the form in the same session, it first restores that session's latest database type, host, port, user, database, ClickHouse HTTPS, and read-only mode, and restores the credential-reference name from its connected profile. A new session with no configuration uses the most recently connected non-secret profile as editable defaults, but remains disconnected until you confirm the connection. A temporary password always remains masked and is never restored.
@@ -224,6 +260,7 @@ If you see `failed to mount` or a missing `@yejiming/dsh-data-agent` package err
 - Temporary passwords entered in the Web UI or dsh-tui are used only for the current connection. The TUI displays only `*` and never restores the password when the form is reopened.
 - If authentication must be restored across processes, enter a DSH credential reference in the TUI form or pass it with `--password-ref`. The form restores the reference name, but never reads, displays, or persists its resolved password.
 - MySQL/Doris and SQL Server passwords enter only `MYSQL_PWD` and `SQLCMDPASSWORD`, respectively. A ClickHouse password enters only the official HTTP client's authentication field—not the URL, argv, or persisted configuration.
+- Catalog persistence contains only redacted source summaries, system metadata, versions, and human definitions. It never stores passwords, resolved credentials, client stdout/stderr, business query results, or sample rows.
 - When read-only mode is disabled, Data Agent can run update or administrative statements at your request. Before connecting to a production database, review the account permissions and backup policy.
 - Database connections are isolated by session, making it easier to keep different projects, customers, and analysis environments separate.
 - The plugin and ecosystem adapter run inside the DSH process; neither is an OS, process, or realm sandbox. Ecosystem permissions support admission negotiation and do not replace database-account controls, network isolation, or runtime security policy.
@@ -263,6 +300,7 @@ MIT
 
 ## Related Links
 
-- [dshfind.com](https://dshfind.com): A Chinese learning and sharing community for DeepSeek Harness
-- [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui): A collection of plugins and skins for the DeepSeek Harness Web UI
-- [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui): A Claude Code-style full-screen terminal interface
+- [dshfind.com](https://dshfind.com): A Chinese-language technical community for the DeepSeek Harness ecosystem, featuring project discovery, practical knowledge sharing, and developer collaboration
+- [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui): An extensible Web UI for DeepSeek Harness, with browser-based interaction and a plugin and theme ecosystem
+- [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui): A keyboard-first, full-screen terminal interface for DeepSeek Harness, designed for efficient conversational development workflows
+- [platonai/Browser4](https://github.com/platonai/Browser4): an AI-native browser engine for autonomous agents, intelligent extraction, and large-scale web automation.

package/README.md

@@ -44,7 +44,7 @@ dsh-data-agent是DeepSeek Harness（DSH）的数据分析插件。连接数据
 | --- | --- |
 | 规范与阶段 | Community v0.15，Draft / Experimental |
 | 固定基线 | `dsh-ecosystem-spec@ec80a4be5d92bbb971655afd0f097bb5586a1a28`；`dsh-std@614dfa1ac168db79fcf4577cf0ebb34e2e3b944b` |
-| Manifest | `dsh-plugin.json`，`manifestVersion: 0.15`，包身份 `@yejiming/dsh-data-agent@0.0.13` |
+| Manifest | `dsh-plugin.json`，`manifestVersion: 0.15`，包身份 `@yejiming/dsh-data-agent@0.1.1` |
 | 准入结果 | 仓库内 eligible fixture 为 `compatible`；这不是实际 dsh-TUI Host 的准入结论 |
 | 证据等级 | `Parsed`；fixture negotiation 只记录为 `fixture-only`，不提升为 `Negotiated` |
 | 已执行环境 | 离线 parser/projector/definition 校验；`@dsh-std/adapter-dsh@0.1.0-rc3` 一次性本地 fixture 挂载/卸载 |
@@ -59,17 +59,45 @@ dsh-data-agent是DeepSeek Harness（DSH）的数据分析插件。连接数据
 
 - **通过对话完成数据分析**：直接用自然语言描述目标，DSH会理解问题、拆解分析步骤、查询真实数据并整理结论。你可以继续追问，分析会沿着当前上下文逐步深入。
 - **自动寻找商业洞察**：不仅返回查询结果，还能帮助比较趋势、定位异常、识别高价值客户或商品，并把数据转化为便于业务决策的说明。
+- **AI驱动的数据治理**：使用当前DSH会话配置的AI模型扫描数据库，根据库表、字段、注释和关系，为每张表及每个字段生成业务含义候选。所有AI候选都需要人工确认，用户也可以人工补充业务术语和指标定义。后续查询分析时，数据Agent会通过内置的`catalog-search`、`catalog-get`和`metric-get`工具自动读取相关业务定义，让SQL和分析结论基于经过治理的业务口径。
 - **跨界面HTML分析报告（render-analysis）**：Agent可在普通工具调用里自主生成单图或Dashboard式综合分析报告（metric/line/bar/pie/scatter/table视图）。每次成功调用都会在当前工作目录的`analysis-reports/`中保存一份离线可打开的HTML；Web同时提供内联预览与“查看分析”Modal，dsh-tui直接返回文件路径。是否画图由Agent按问题判断，schema探查、单标量等查询不会被强制生成图表。
 - **共享Web UI与dsh-tui核心路径**：喜欢可视化操作时，可以在Web界面连接数据库、浏览库表和查看结果，推荐使用[zhu1090093659/dsh-web-ui](https://github.com/zhu1090093659/dsh-web-ui)；习惯键盘工作流时，可以在终端中使用同一“数据模式”，通过`/database`完成连接，然后直接开始对话分析，推荐使用[ccch1mneyyy/dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI)。两种界面共享数据Agent的数据库服务和工具协议；具体版本与部署仍应分别验证。
 - **连接常见业务数据库**：支持MySQL、PostgreSQL、SQLite、Oracle、Hive、Impala、ClickHouse、Apache Doris和SQL Server，可用于业务系统、分析库、本地数据文件及数仓场景。
 - **DSH自动完成分析闭环**：DSH会根据当前问题查看表结构、编写SQL、执行查询，并结合报错或返回结果继续调整，而不是只生成一段未经验证的SQL。
-- **专注数据任务的数据模式**：会话使用DSH原生`str_replace_editor`处理文件，并保留`sql-query`、`sql-write`、`sql-cmd`与`render-analysis`；Web、Desktop、dsh-tui和headless profile使用同一工具协议。`describe_image`、`ssh_*`等宿主或社区插件工具不会进入数据模式。
+- **专注数据任务的数据模式**：会话使用DSH原生`str_replace_editor`处理文件，并保留`sql-query`、`sql-write`、`sql-cmd`、`render-analysis`、`catalog-search`、`catalog-get`与`metric-get`；Web、Desktop、dsh-tui和headless profile使用同一套八工具协议。`describe_image`、`ssh_*`等宿主或社区插件工具不会进入数据模式。
 - **安全地使用真实数据**：支持只读模式和数据库只读账号；TUI密码会被隐藏，且不会作为表单草稿恢复。是否允许修改数据由你决定。
 
-Web UI还提供按需数据库工作台：点击输入框右上角的数据库按钮，即可在同一个Modal中配置连接、浏览库表、查看字段结构或临时运行SQL。MySQL库表浏览会用当前账号逐库验证访问权限，只隐藏明确返回无权访问的库；有权限的系统库与业务库都会正常显示。开始对话前后都不占用输入框上方或左侧的对话空间。
+![数据治理：AI生成表和字段业务含义，并由用户审核](assets/data-governance.png)
+
+Web UI还提供按需数据库工作台：点击输入框右上角的数据库按钮，即可在同一个Modal的“连接配置、库表、数据治理、SQL”四个页签中配置连接、浏览结构、治理口径或临时运行SQL。“数据治理”页读取独立的`data_agent_catalog@1`持久化域；只要存在历史snapshot，断开实时数据库后仍可搜索和查看，重新扫描则必须连接到同一个稳定Profile。
 
 SQL命令页会把读查询结果显示为带固定表头的结构化表格，并按100行分页，宽表可在结果区内横向滚动。当前结果可导出为Excel（`.xlsx`）、UTF-8 CSV或复制到剪贴板；三种导出都包含已加载的完整结果，单次最多50,000行。写入/管理命令及错误仍显示为文本消息，不会被误解析成表格。
 
+### 数据目录与口径治理
+
+Catalog扫描是显式人工动作。第一阶段只读取数据库系统目录，不读取业务明细、不保存样例行，也不会为精确行数执行全表`COUNT(*)`；第二阶段调用发起扫描的DSH会话当前配置模型，按表生成表级和字段级业务含义候选。发送给模型的只有表/字段名称、类型、nullable、数据库注释、键和关系等有界技术元数据，不包含样例值、查询结果或凭据。Web可在“数据治理”页选择全库、Schema或单表范围；全库扫描需要二次确认。`/database`和`/catalog`只在当前Cordis组合实际加载`@deepseek-harness-tui/dsh-tui`插件时注册；Profile名称不参与判断，仅安装Data Agent或把Profile命名为`dsh-tui`都不会暴露命令。普通Web组合不展示这两个命令，而是在数据库工作台中完成连接和扫描。dsh-tui使用：
+
+Catalog元数据查询使用独立的`catalogMaxResultChars`捕获上限（默认32 MiB），不会再受普通SQL工具较小的`maxResultChars`限制；超过Catalog专属上限时仍会安全失败，并提示缩小扫描范围或调整配置，不会发布被截断的snapshot。
+
+```text
+/catalog scan                       交互选择范围；选择全库时再次确认
+/catalog scan --all                 显式全库扫描
+/catalog scan --schema sales        扫描一个Schema
+/catalog scan --schema sales --table orders
+/catalog status [--run <run-id>]
+/catalog cancel [--run <run-id>]
+/catalog diff [--from <run-id> --to <run-id>]
+/catalog view                       打开只读全屏目录浏览器
+```
+
+扫描在后台运行，同一个source同时只允许一个活动run。在提供公开扩展接口的dsh-tui中，输入框上方会持续显示“技术元数据采集 → 目录发布 → AI业务含义”的实际进度；成功、部分成功或失败终态会一直保留到下一次扫描或打开`/catalog view`，不再依赖短暂通知。`/catalog view`使用全屏只读场景：左侧按表/视图分页，右侧展示表级说明、字段类型与字段级AI业务含义，支持搜索、左右独立滚动、业务Schema/全部Schema切换和刷新；按Esc返回。旧版dsh-tui没有公开状态/scene服务时，扫描命令仍可用，并明确回退到`/catalog status`和Web“数据治理”页。
+
+结果按稳定Profile、资产身份和不可变revision保存：未变化对象不复制revision；完整成功的技术扫描只在其精确范围内把消失对象标记为`missing`；单表/Schema扫描不会改动范围外对象，也不会更新最近全库扫描时间；对象重新出现时记录为`restored`。元数据失败、取消、中断或权限不完整的run不会覆盖上一份成功snapshot，权限不确定时也不会把对象误判为删除。AI阶段具有独立的排队、运行、成功、部分成功、失败和取消状态；模型输出保持有界，整表输出触及token上限时会沿用当前模型配置并自动按字段分批重试，只有整张表的字段结果齐全后才写入。AI失败不会抹掉已经成功提交的技术snapshot，也不会把不完整表结果写成候选。
+
+数据库事实是`observed`，AI生成的表/字段业务含义以及候选业务术语/指标是`inferred`；只有Web中的人工审核可以基于当前version确认成`verified`。数据目录按表展示表级说明和每个字段说明，用户可以逐项确认或删除；删除会保留审计revision并从默认详情隐藏，后续扫描不会自动复活或覆盖已确认/已删除决策。结构变化会把受影响口径标为`needs_review`，不会自动确认。Agent分析业务问题时先用只读`catalog-search`查找目录，再用`catalog-get`读取技术上下文或`metric-get`读取精确指标版本；目录无命中时再回退到实时Schema探查。目录中的AI候选、数据库注释、人工说明和公式都按不可信参考文本处理。
+
+首版不包含定时扫描、业务明细采样、AI自动认证、外部Catalog同步、完整血缘、Catalog级RBAC或扫描结果物理删除。
+
 ![数据库工作台](assets/tables.webp)
 
 创建会话时选择“数据模式”，DSH就会以数据分析工作流处理后续问题。
@@ -92,7 +120,7 @@ dsh plugin --profile web add @yejiming/dsh-data-agent
 dsh plugin --profile web add github:omdsh-dev/dsh-data-agent
 ```
 
-插件会自动安装“数据模式”预设，并在profile启动时预加载该预设的数据库工具与命令；选择预设时不再动态导入插件子路径，无需本地构建。
+插件会自动安装“数据模式”预设，并在profile启动时为所有界面预加载该预设的数据库工具；`/database`与`/catalog`仅由当前组合中实际加载的`@deepseek-harness-tui/dsh-tui`运行时启用，与Profile名称无关。选择预设时不再动态导入插件子路径，无需本地构建。
 
 ## 在Web UI中使用
 
@@ -109,6 +137,8 @@ dsh --profile web
 3. 连接成功后，直接在对话框中提出分析问题。
 4. 根据第一轮结果继续追问，让DSH缩小范围、比较维度或总结结论。
 
+未加载`@deepseek-harness-tui/dsh-tui`的Web命令目录不会展示`/database`或`/catalog`；连接、扫描、取消和目录审核均从数据库工作台完成。
+
 例如，输入“分析最近30天订单变化，找出销售额下降最明显的地区和商品，并解释主要原因”，DSH会自行查看相关表、生成并执行查询，再根据真实结果完成分析。
 
 ### 分析报告与HTML文件
@@ -124,7 +154,7 @@ dsh --profile web
 
 ## 在dsh-tui中使用
 
-把Data Agent安装到dsh-tui profile即可；`render-analysis`不要求特定dsh-TUI版本或scene能力：
+把Data Agent安装到dsh-tui profile即可；`render-analysis`不要求特定dsh-TUI版本或scene能力。Catalog持续状态和全屏结果浏览会在dsh-tui提供公开`status`/`scene`扩展服务时自动启用：
 
 ```sh
 dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent
@@ -151,8 +181,14 @@ dsh --profile dsh-tui
 /database status       查看当前连接
 /database test         测试当前连接
 /database disconnect   断开当前连接
+/catalog scan           交互选择并启动Catalog扫描
+/catalog status [--run <run-id>]  查看最近结果或指定run
+/catalog diff           比较最近两个成功snapshot
+/catalog view           打开按表组织的只读Catalog结果
 ```
 
+扫描开始后无需反复执行`/catalog status`：输入框上方会持续显示技术采集和AI业务含义进度，并保留最终成功/失败状态。完成后执行`/catalog view`，使用↑↓或`j/k`选择表、Tab或←→切换左右区域、`/`搜索、`a`切换业务Schema/全部Schema、`r`刷新、Esc返回。TUI只提供读取；AI候选的确认与删除仍在Web“数据治理”页逐项完成。
+
 Agent生成分析报告后，工具卡会显示数据集、视图、空数据摘要与HTML绝对路径。TUI不会输出字符Dashboard，也没有`/analysis`命令；直接在本机浏览器中打开该HTML即可查看六类视图和原始数据。文件来自本次工具调用，`/resume`不会重新查询数据库。
 
 同一会话再次打开连接表单时，会优先恢复该会话最近填写的数据库类型、地址、端口、用户、数据库、ClickHouse HTTPS和只读模式，并从已连接profile恢复凭据引用。新会话没有自己的配置时，会用最近一次成功连接的非敏感profile作为表单默认值，但仍是未连接状态，必须确认连接后才能查询。临时密码始终隐藏且不会恢复。
@@ -223,6 +259,7 @@ Windows路径可以写成`C:\Program Files\MySQL\MySQL Server 9.0\bin`。插件
 - Web UI和dsh-tui中的临时密码只用于当前连接；TUI只显示`*`，重新打开表单时不会恢复密码。
 - 需要跨进程恢复认证时，可以在TUI表单填写DSH credential reference，或通过`--password-ref`传入；表单会恢复引用名，但不会读取、显示或持久化解析后的密码。
 - MySQL/Doris和SQL Server密码分别只传入`MYSQL_PWD`和`SQLCMDPASSWORD`；ClickHouse密码只进入官方HTTP客户端的认证字段，不进入URL、argv或持久化配置。
+- Catalog仅持久化脱敏source摘要、系统元数据、版本与人工口径；不保存密码、credential解析值、客户端stdout/stderr、业务查询结果或样例行。
 - 未开启只读模式时，数据Agent可以按你的要求执行更新或管理语句。连接生产数据库前，请先确认账号权限和数据备份策略。
 - 不同会话的数据库连接相互隔离，便于分别处理不同项目、客户或分析环境。
 - 插件及其生态适配器都运行在DSH进程内，不是OS、进程或realm沙箱；生态permission只能用于准入协商，不能替代数据库账号权限、网络隔离或运行环境安全策略。
@@ -262,6 +299,7 @@ MIT
 
 ## 友情链接
 
-- [dshfind.com](https://dshfind.com)：DeepSeek Harness中文学习与分享社区
-- [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui)：DeepSeek Harness Web UI插件与皮肤集合
-- [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui)：Claude Code风格的全屏终端界面
+- [dshfind.com](https://dshfind.com)：面向DeepSeek Harness生态的中文技术社区，提供项目发现、实践分享与开发者交流
+- [dsh-web-ui](https://github.com/dsh-external/dsh-web-ui)：DeepSeek Harness的可扩展Web UI，支持浏览器端交互以及插件与主题扩展
+- [dsh-cc-tui](https://github.com/dsh-external/dsh-cc-tui)：面向DeepSeek Harness的键盘优先全屏终端界面，适用于高效的对话式开发工作流
+- [platonai/Browser4](https://github.com/platonai/Browser4)：面向自主智能体、智能信息抽取与大规模Web自动化的AI原生浏览器引擎

package/conformance/dsh-ecosystem/inventory.json

@@ -10,21 +10,42 @@
       "@deepseek-ai/dsh-persona",
       "@deepseek-ai/dsh-tool-str-replace-editor"
     ],
-    "commands": ["database"],
+    "commands": ["catalog", "database"],
     "tools": [
       "render-analysis",
+      "catalog-get",
+      "catalog-search",
+      "metric-get",
       "sql-cmd",
       "sql-query",
       "sql-write",
       "str_replace_editor"
     ],
-    "services": ["dataAgentConnections"],
+    "services": [
+      "dataAgentCatalog",
+      "dataAgentCatalogReview",
+      "dataAgentCatalogScanner",
+      "dataAgentConnections"
+    ],
     "routes": [
       "GET describe",
+      "GET catalog/assets/:assetId",
+      "GET catalog/diff",
+      "GET catalog/runs",
+      "GET catalog/search",
+      "GET catalog/semantics/:semanticId",
+      "GET catalog/sources",
+      "GET catalog/status",
       "GET schemas",
       "GET status",
       "GET tables",
       "POST connect",
+      "POST catalog/cancel",
+      "POST catalog/scan",
+      "POST catalog/semantics",
+      "POST catalog/semantics/:semanticId/dismiss",
+      "POST catalog/semantics/:semanticId/retire",
+      "POST catalog/semantics/:semanticId/verify",
       "POST disconnect",
       "POST query"
     ],
@@ -32,7 +53,7 @@
       "conversation.input.right",
       "tool.call.toolview"
     ],
-    "storageDomains": ["data_agent_connections@1"],
+    "storageDomains": ["data_agent_catalog@1", "data_agent_connections@1"],
     "surfaces": ["desktop", "headless", "tui", "web"],
     "databaseTypes": [
       "clickhouse",
@@ -63,6 +84,7 @@
     ]
   },
   "abilities": [
+    { "id": "command:catalog", "disposition": "declared", "manifestReference": "io.github.omdsh-dev.dsh-data-agent.catalog" },
     { "id": "command:database", "disposition": "declared", "manifestReference": "io.github.omdsh-dev.dsh-data-agent.database" },
     { "id": "tools:model", "disposition": "upstream-gap", "restrictionId": "tool-extension-not-in-tui-profile" },
     { "id": "preset:data-agent", "disposition": "upstream-gap", "restrictionId": "agent-preset-not-in-tui-profile" },
@@ -70,6 +92,7 @@
     { "id": "routes:data-agent", "disposition": "restriction", "restrictionId": "http-routes-native-only" },
     { "id": "ui:web-slots", "disposition": "restriction", "restrictionId": "web-slots-native-only" },
     { "id": "storage:data_agent_connections", "disposition": "restriction", "restrictionId": "storage-domain-native-only" },
+    { "id": "storage:data_agent_catalog", "disposition": "restriction", "restrictionId": "storage-domain-native-only" },
     { "id": "credentials:resolve", "disposition": "restriction", "restrictionId": "credential-resolution-native-only" },
     { "id": "subprocess:database-clients", "disposition": "restriction", "restrictionId": "database-execution-native-only" },
     { "id": "presentation:local-tty", "disposition": "restriction", "restrictionId": "legacy-local-tty" }

package/conformance/dsh-ecosystem/restrictions.json

@@ -4,10 +4,10 @@
   "items": [
     { "id": "tool-extension-not-in-tui-profile", "kind": "upstream-gap", "requirementId": "DECL-CLOSURE-001", "summary": "The pinned TUI profile does not import the complete model Tool/Preset declaration used by the native data-agent scope." },
     { "id": "agent-preset-not-in-tui-profile", "kind": "upstream-gap", "requirementId": "DECL-CLOSURE-001", "summary": "Agent preset standing-scope composition remains a native DSH contract." },
-    { "id": "cordis-service-not-in-tui-profile", "kind": "upstream-gap", "requirementId": "DECL-CLOSURE-001", "summary": "The dataAgentConnections Cordis service has no admitted Community v0.15 service definition." },
+    { "id": "cordis-service-not-in-tui-profile", "kind": "upstream-gap", "requirementId": "DECL-CLOSURE-001", "summary": "The dataAgentConnections and Catalog Cordis service faces have no admitted Community v0.15 service definition." },
     { "id": "http-routes-native-only", "kind": "restriction", "requirementId": "NATIVE-NO-REGRESSION-001", "summary": "HTTP routes remain owned by the native Web bundle row." },
     { "id": "web-slots-native-only", "kind": "restriction", "requirementId": "NATIVE-NO-REGRESSION-001", "summary": "Web slots remain owned by the native browser client." },
-    { "id": "storage-domain-native-only", "kind": "restriction", "requirementId": "DECL-CLOSURE-001", "summary": "The durable data_agent_connections domain remains owned by native Cordis storage-domain." },
+    { "id": "storage-domain-native-only", "kind": "restriction", "requirementId": "DECL-CLOSURE-001", "summary": "The durable data_agent_connections and data_agent_catalog domains remain owned by native Cordis storage-domain." },
     { "id": "credential-resolution-native-only", "kind": "restriction", "requirementId": "TRUST-001", "summary": "Credential references resolve only inside the existing native runtime and are excluded from evidence." },
     { "id": "database-execution-native-only", "kind": "restriction", "requirementId": "DEPENDENCY-CLOSURE-001", "summary": "Database execution remains native and depends on packaged or external database clients." },
     { "id": "legacy-local-tty", "kind": "restriction", "requirementId": "PRESENTATION-001", "summary": "The masked local TTY form is preserved but is not standard Presentation evidence." },

package/cordis.patch.yml

@@ -1,8 +1,11 @@
 # The dsh-data-agent bundle patch: activates the plugin as a profile layer.
 #
-# Two host rows: `data-agent` provides the connection store, installs the
-# selectable agent preset, and statically preloads that preset's scoped tools
-# and command through the profile bundle path; `data-agent-routes` mounts the
+# Two host rows: `data-agent` provides connection and versioned Catalog stores,
+# installs the selectable agent preset, and statically preloads that preset's
+# scoped tools on every surface and gates the human commands plus optional
+# public status/scene presentation on the actual `dsh-tui` Cordis plugin
+# runtime (independent of profile name);
+# `data-agent-routes` mounts the
 # HTTP routes and only activates where the webserver exists (web profiles).
 # The browser half (lib/client.js) ships in the same package and loads under
 # the data-agent id through the `dsh.client` declaration in package.json.

package/dsh-plugin.json

@@ -3,7 +3,7 @@
   "manifestVersion": "0.15",
   "id": "io.github.omdsh-dev.dsh-data-agent",
   "name": "DSH Data Agent",
-  "version": "0.0.13",
+  "version": "0.1.1",
   "facets": {
     "host": {
       "entry": "lib/ecosystem.js",
@@ -28,8 +28,8 @@
   "permissions": [
     {
       "name": "commands.invoke",
-      "scope": "io.github.omdsh-dev.dsh-data-agent.database",
-      "reason": "invoke the declared database connection command"
+      "scope": "io.github.omdsh-dev.dsh-data-agent",
+      "reason": "invoke the declared database and human-controlled Catalog commands when the dsh-tui runtime is loaded"
     }
   ],
   "contributes": {
@@ -37,7 +37,12 @@
       {
         "id": "io.github.omdsh-dev.dsh-data-agent.database",
         "title": "Database",
-        "description": "Manage the native data-agent database connection"
+        "description": "Manage the native data-agent database connection when the dsh-tui runtime is loaded"
+      },
+      {
+        "id": "io.github.omdsh-dev.dsh-data-agent.catalog",
+        "title": "Data Catalog",
+        "description": "Scan system metadata, follow persistent progress, and browse versioned Catalog results when the dsh-tui runtime is loaded"
       }
     ],
     "panels": []