dsh-data-cleaning-agent 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/CONTRIBUTING.md +47 -0
  3. package/LICENSE +21 -0
  4. package/README.en.md +117 -0
  5. package/README.md +108 -0
  6. package/cordis.patch.yml +6 -0
  7. package/docs/COMPATIBILITY.md +45 -0
  8. package/docs/FIRST-CONTRIBUTION.md +43 -0
  9. package/docs/USER-GUIDE.md +57 -0
  10. package/install.sh +66 -0
  11. package/lib/client.js +38 -0
  12. package/lib/engine.js +290 -0
  13. package/lib/index.js +73 -0
  14. package/lib/jobs.js +144 -0
  15. package/lib/skill.js +32 -0
  16. package/lib/tools.js +144 -0
  17. package/lib/web.js +343 -0
  18. package/marketing/metadata.json +84 -0
  19. package/package.json +87 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,31 @@
1
+ # Changelog
2
+
3
+ 本文件记录 `dsh-data-cleaning-agent` 的版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
4
+
5
+ ## [Unreleased]
6
+
7
+ ### Added
8
+ - 开源社区化工程骨架（README 双语、LICENSE、CONTRIBUTING、install.sh、marketing 元数据、CI/Release workflow）。
9
+
10
+ ## [0.2.0] - 2026-09-01
11
+
12
+ > 首个开源社区版本。包名由 `@qcc/dsh-data-cleaning-agent`（私有 scope）改为 `dsh-data-cleaning-agent`（无 scope），
13
+ > 以便社区 fork / PR / npm 公开安装。
14
+
15
+ ### Added
16
+ - MVP 全量能力：CSV/XLSX/JSON 解析、清洗（trim / 手机号规范化 / 缺失剔除 / 负金额剔除 / 去重）、
17
+ 确定性补全、概览画像、CSV 回写（`lib/engine.js`）。
18
+ - 三个模型工具：`data_clean_rows` / `data_complete_rows` / `data_profile`（`lib/tools.js`）。
19
+ - 内嵌 Skill `data-cleaning`（`lib/skill.js`）。
20
+ - 异步任务状态机 + 持久化存储（`lib/jobs.js`，`ctx.jobs` + `ctx.storageDomain`）。
21
+ - web 半区路由与 UI（`lib/web.js`），同源 `/data-cleaning/` 前缀。
22
+ - Client 半区 seam（`lib/client.js`）。
23
+ - 引擎单元测试 13 例（`test/engine.test.js`）。
24
+
25
+ ### Changed
26
+ - 包名：`@qcc/dsh-data-cleaning-agent` → `dsh-data-cleaning-agent`。
27
+ - 补全 `license` / `repository` / `homepage` / `bugs` / `keywords` / `engines`。
28
+
29
+ ## [0.1.0-mvp] - 2026-08-31
30
+
31
+ > 内部 MVP 基线，双基线（0.1.1-rc.2 + 0.1.2-alpha.2）验证通过。不对外发布。
package/CONTRIBUTING.md ADDED
@@ -0,0 +1,47 @@
1
+ # 贡献指南 / Contributing
2
+
3
+ 感谢你帮助改进 `dsh-data-cleaning-agent`。请不要在 Issue、PR、日志、截图或测试数据中提交 Token、API Key、Cookie、OAuth 凭据或真实业务数据。
4
+
5
+ Thank you for contributing. Never put tokens, API keys, cookies, OAuth credentials, or real business data in issues, pull requests, logs, screenshots, or fixtures.
6
+
7
+ ## 参与方式
8
+
9
+ - 报告缺陷或提交功能建议：[GitHub Issues](https://github.com/duhu2000/dsh-data-cleaning-agent/issues)
10
+ - 修复插件或改进文档：Fork 本仓库，从最新 `main` 创建单一目的的分支并提交 PR。
11
+ - 第一次参与：从带有 [`good first issue`](https://github.com/duhu2000/dsh-data-cleaning-agent/labels/good%20first%20issue) 标签的任务开始，并按[首次贡献路径](docs/FIRST-CONTRIBUTION.md)完成本地校验。
12
+ - 提出企查查 MCP 补全相关需求：先阅读 [docs/PLAN-OSS.md](docs/PLAN-OSS.md) 了解路线图，再开 Issue 讨论。
13
+
14
+ ## 本地开发
15
+
16
+ 要求 Node.js 20 或更高版本。DSH 运行期 peer dependencies 由 Host 提供，本地安装使用：
17
+
18
+ ```bash
19
+ npm install --legacy-peer-deps
20
+ npm run check
21
+ ```
22
+
23
+ `npm run check` = lint（`node --check` 全部 lib）+ 文档版本一致性 + 发布包白名单校验 + 单元测试。
24
+
25
+ ## PR 要求
26
+
27
+ 1. 一个 PR 解决一个明确问题，不要夹带无关重构。
28
+ 2. 新增或修改行为时增加对应测试；纯文档改动也必须通过 `npm run check`。
29
+ 3. 中英文用户文档应同步更新（`README.md` 与 `README.en.md`）。
30
+ 4. README 中展示的版本必须与 `package.json` 一致，`npm run docs:check` 会阻断版本漂移。
31
+ 5. 只使用无凭据 mock 或已脱敏数据做测试与截图；引擎测试夹具不得含真实手机号/企业名。
32
+
33
+ ## 从 Fork 到 PR
34
+
35
+ ```bash
36
+ git switch main
37
+ git pull --ff-only
38
+ git switch -c feat/<short-purpose>
39
+ npm install --legacy-peer-deps
40
+ npm run check
41
+ ```
42
+
43
+ 提交时说明用户问题、解决方案、测试结果与必要的手工验收步骤。
44
+
45
+ ## 维护者如何准备首次贡献任务
46
+
47
+ 首次贡献任务应边界清楚、无需真实凭据或私有 DSH 环境，并在 Issue 中写明背景、建议修改文件、验收标准和验证命令。适合的范围包括文档示例、无凭据测试夹具、可访问性文案和小型校验器改进；涉及发布、OAuth 凭据、企查查 MCP 授权或大规模重构的工作不应标记为 `good first issue`。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-data-cleaning-agent plugin contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md ADDED
@@ -0,0 +1,117 @@
1
+ # dsh-data-cleaning-agent
2
+
3
+ > A data cleaning & completion agent plugin for DeepSeek Harness: local CSV/XLSX/JSON engine plus optional Qichacha (QCC) MCP enterprise-data enrichment. Initiated and maintained by the Qichacha (QCC) team.
4
+ >
5
+ > Current version / 当前版本: **0.2.0**
6
+
7
+ [![CI](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml)
8
+ [![npm](https://img.shields.io/npm/v/dsh-data-cleaning-agent)](https://www.npmjs.com/package/dsh-data-cleaning-agent)
9
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-data-cleaning-agent)](https://www.npmjs.com/package/dsh-data-cleaning-agent)
10
+ [![GitHub stars](https://img.shields.io/github/stars/duhu2000/dsh-data-cleaning-agent?style=social)](https://github.com/duhu2000/dsh-data-cleaning-agent/stargazers)
11
+ [![GitHub forks](https://img.shields.io/github/forks/duhu2000/dsh-data-cleaning-agent?style=social)](https://github.com/duhu2000/dsh-data-cleaning-agent/forks)
12
+ [![GitHub release](https://img.shields.io/github/v/release/duhu2000/dsh-data-cleaning-agent)](https://github.com/duhu2000/dsh-data-cleaning-agent/releases)
13
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
14
+
15
+ ## Overview
16
+
17
+ `dsh-data-cleaning-agent` is a DeepSeek Harness plugin (DSH Bundle plugin) for the common
18
+ "customer gave us a messy list of company names / table data" task. Upload CSV / XLSX / JSON,
19
+ clean name / phone / amount columns (trim, phone normalization, drop missing-required /
20
+ negative-amount / duplicate rows), deterministically complete gaps, profile the batch, and
21
+ export clean CSV.
22
+
23
+ The model only ever receives **aggregate summaries, never raw detail rows**. Details are only
24
+ viewed and exported in the same-origin web UI, keeping customer raw data out of model context
25
+ by construction.
26
+
27
+ ## Quick start
28
+
29
+ ```bash
30
+ dsh plugin --profile web add dsh-data-cleaning-agent
31
+ ```
32
+
33
+ Fully restart DeepSeek Harness afterwards (stop and re-run `dsh web`). Then say
34
+ "help me clean this batch of company list data" and the plugin loads its built-in Skill and
35
+ drives the clean / complete / profile tools.
36
+
37
+ Without the `dsh` CLI, use the install script:
38
+
39
+ ```bash
40
+ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-agent/main/install.sh)
41
+ ```
42
+
43
+ Or let an agent install it for you:
44
+
45
+ > Install this plugin for me: https://github.com/duhu2000/dsh-data-cleaning-agent
46
+
47
+ ## Capability matrix
48
+
49
+ | Capability | Tool / entry | Notes |
50
+ | --- | --- | --- |
51
+ | Clean | `data_clean_rows` | trim, phone normalization, drop missing-required / negative-amount / duplicate rows |
52
+ | Complete | `data_complete_rows` | fill empty amount with 0, empty name with placeholder, report incomplete items |
53
+ | Profile | `data_profile` | column overview and amount distribution |
54
+ | Parse | web `/data-cleaning/api/mvp/parse` | CSV / XLSX / JSON |
55
+ | Async jobs | web `/data-cleaning/api/mvp/jobs` | job state machine + persistent storage |
56
+ | UI | web `/data-cleaning/` | upload → clean/complete → export |
57
+ | Skill | `data-cleaning` | guides the model through the workflow |
58
+ | QCC enrichment | (planned, see below) | backfill list with Qichacha MCP enterprise data |
59
+
60
+ ## Qichacha MCP enrichment (roadmap)
61
+
62
+ Besides local deterministic completion, the plugin will (in later releases) enrich lists with
63
+ Qichacha MCP enterprise data:
64
+
65
+ - **Plan A (model-mediated, first)**: after the user connects Qichacha with
66
+ `qcc-dsh-mcp-oauth`, the Skill guides the model to call
67
+ `mcp__qcc-company__get_company_by_query` / `mcp__qcc-company__get_company_registration_info`
68
+ per company name and feed the fresh registration data back into the completion tool.
69
+ - **Plan B (programmatic, later)**: `lib/qcc.js` calls Qichacha MCP tools directly in the host
70
+ half and batch-completes; the model sees only the final summary.
71
+
72
+ See [docs/PLAN-OSS.md](docs/PLAN-OSS.md) for details.
73
+
74
+ ## Local development
75
+
76
+ Node.js 20 or later. DSH runtime services (`ctx.tools` / `ctx.skills` / `ctx.jobs` /
77
+ `ctx.storageDomain` / `webServer` / `webRuntime`) are provided by the Host; locally you only
78
+ install `xlsx`:
79
+
80
+ ```bash
81
+ npm install --legacy-peer-deps
82
+ npm run check
83
+ ```
84
+
85
+ `npm run check` runs lint, documentation version consistency, pack whitelist verification and
86
+ unit tests.
87
+
88
+ ## Configuration
89
+
90
+ The plugin registers itself as a bundle via `cordis.patch.yml`; `dsh plugin add` adds the
91
+ package to the profile's `dsh.profile.bundles` automatically.
92
+
93
+ ## Documentation
94
+
95
+ - [User guide](docs/USER-GUIDE.md)
96
+ - [First contribution](docs/FIRST-CONTRIBUTION.md)
97
+ - [Compatibility](docs/COMPATIBILITY.md)
98
+ - [Contributing](CONTRIBUTING.md)
99
+
100
+ ## Security & privacy
101
+
102
+ - Model tools return summaries only; raw detail rows never enter model context.
103
+ - Detail data is delivered only via same-origin (`127.0.0.1` / `localhost`) web endpoints;
104
+ untrusted cross-origin requests are rejected.
105
+ - Never put tokens, API keys, cookies, OAuth credentials, or real business data in issues, PRs,
106
+ logs, screenshots, or test fixtures.
107
+
108
+ ## License
109
+
110
+ [MIT](LICENSE) © 2026 dsh-data-cleaning-agent plugin contributors
111
+
112
+ ## Get involved
113
+
114
+ If the plugin helps you clean company lists faster, consider
115
+ [starring the repository](https://github.com/duhu2000/dsh-data-cleaning-agent/stargazers),
116
+ [filing an issue](https://github.com/duhu2000/dsh-data-cleaning-agent/issues), or
117
+ [contributing a fix](CONTRIBUTING.md).
package/README.md ADDED
@@ -0,0 +1,108 @@
1
+ # dsh-data-cleaning-agent
2
+
3
+ > 在 DeepSeek Harness 中清洗、补全、画像企业名单数据的智能体插件：本地 CSV/XLSX/JSON 引擎 + 可选企查查（Qichacha/QCC）MCP 企业数据补全，由企查查（Qichacha/QCC）团队发起并维护。
4
+ >
5
+ > 当前版本 / Current version: **0.2.0**
6
+
7
+ [![CI](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml)
8
+ [![npm](https://img.shields.io/npm/v/dsh-data-cleaning-agent)](https://www.npmjs.com/package/dsh-data-cleaning-agent)
9
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-data-cleaning-agent)](https://www.npmjs.com/package/dsh-data-cleaning-agent)
10
+ [![GitHub stars](https://img.shields.io/github/stars/duhu2000/dsh-data-cleaning-agent?style=social)](https://github.com/duhu2000/dsh-data-cleaning-agent/stargazers)
11
+ [![GitHub forks](https://img.shields.io/github/forks/duhu2000/dsh-data-cleaning-agent?style=social)](https://github.com/duhu2000/dsh-data-cleaning-agent/forks)
12
+ [![GitHub release](https://img.shields.io/github/v/release/duhu2000/dsh-data-cleaning-agent)](https://github.com/duhu2000/dsh-data-cleaning-agent/releases)
13
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
14
+
15
+ ## 简介
16
+
17
+ `dsh-data-cleaning-agent` 是 DeepSeek Harness 的插件（DSH Bundle plugin）。
18
+ 它面向"客户给的一批企业名单 / 表格数据"这个高频场景：上传 CSV / XLSX / JSON，
19
+ 对姓名、手机号、金额等列做清洗（去空格、手机号规范化、剔除缺失/负金额/重复行）、
20
+ 确定性补全与概览画像，并导出干净的 CSV。
21
+
22
+ 模型（LLM）**只拿到统计摘要，从不读取原始明细行**；明细只在同源 web 界面查看与导出，
23
+ 从架构上避免把客户原始数据灌进模型上下文。
24
+
25
+ ## 30 秒开始
26
+
27
+ ```bash
28
+ dsh plugin --profile web add dsh-data-cleaning-agent
29
+ ```
30
+
31
+ 安装后**完全重启** DeepSeek Harness（停止后重新运行 `dsh web`）。
32
+ 之后在对话中说「帮我清洗这批企业名单数据」，插件会自动加载内嵌 Skill 并调度清洗/补全/画像工具。
33
+
34
+ 没有 `dsh` CLI 时，也可以用安装脚本：
35
+
36
+ ```bash
37
+ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-agent/main/install.sh)
38
+ ```
39
+
40
+ 或直接让 Agent 安装：
41
+
42
+ > 帮我安装这个插件 https://github.com/duhu2000/dsh-data-cleaning-agent
43
+
44
+ ## 能力矩阵
45
+
46
+ | 能力 | 工具 / 入口 | 说明 |
47
+ | --- | --- | --- |
48
+ | 清洗 | `data_clean_rows` | trim、手机号规范化、剔除缺失必填/负金额/重复行 |
49
+ | 补全 | `data_complete_rows` | 空金额填 0、空姓名填占位、不可补全项上报 |
50
+ | 画像 | `data_profile` | 列概览与金额分布 |
51
+ | 解析 | web `/data-cleaning/api/mvp/parse` | CSV / XLSX / JSON |
52
+ | 异步任务 | web `/data-cleaning/api/mvp/jobs` | 任务状态机 + 持久化存储 |
53
+ | UI | web `/data-cleaning/` | 上传 → 清洗/补全 → 导出 |
54
+ | Skill | `data-cleaning` | 引导模型按工作流调度上述工具 |
55
+ | 企查查补全 | （规划中，见下文） | 用企查查 MCP 企业数据回填名单 |
56
+
57
+ ## 企查查 MCP 补全（路线图）
58
+
59
+ 插件同时提供本地确定性补全，以及（后续版本）接入企查查 MCP 企业数据的能力：
60
+
61
+ - **方案 A（模型中介，优先）**：用户已用 `qcc-dsh-mcp-oauth` 连接企查查后，
62
+ Skill 引导模型对名单中每个企业名调用 `mcp__qcc-company__get_company_by_query` /
63
+ `mcp__qcc-company__get_company_registration_info`，把返回的最新工商信息回填到补全工具。
64
+ - **方案 B（后台程序化，后续）**：`lib/qcc.js` 在 host 半区直接调用企查查 MCP 工具，
65
+ 批量补全，模型只见最终摘要。
66
+
67
+ 详见 [docs/PLAN-OSS.md](docs/PLAN-OSS.md)。
68
+
69
+ ## 本地开发
70
+
71
+ 要求 Node.js 20 或更高。DSH 运行期服务（`ctx.tools` / `ctx.skills` / `ctx.jobs` /
72
+ `ctx.storageDomain` / `webServer` / `webRuntime`）由 Host 提供，本地只装 `xlsx`：
73
+
74
+ ```bash
75
+ npm install --legacy-peer-deps
76
+ npm run check
77
+ ```
78
+
79
+ `npm run check` 会依次执行 lint、文档版本一致性、发布包白名单校验与单元测试。
80
+
81
+ ## 配置
82
+
83
+ 插件通过 `cordis.patch.yml` 注册为 bundle；`dsh plugin add` 会自动把本包加入 profile 的
84
+ `dsh.profile.bundles`，无需手工配置。
85
+
86
+ ## 文档
87
+
88
+ - [使用指南](docs/USER-GUIDE.md)
89
+ - [首次贡献](docs/FIRST-CONTRIBUTION.md)
90
+ - [兼容性](docs/COMPATIBILITY.md)
91
+ - [贡献指南](CONTRIBUTING.md)
92
+
93
+ ## 安全与隐私
94
+
95
+ - 模型工具只返回摘要，原始明细行永不进入模型上下文。
96
+ - 明细数据仅经同源（`127.0.0.1` / `localhost`）web 端点交付；非可信跨源请求会被拒绝。
97
+ - 不要在任何 Issue、PR、日志、截图或测试夹具中提交 Token、API Key、Cookie、OAuth 凭据或真实业务数据。
98
+
99
+ ## 许可证
100
+
101
+ [MIT](LICENSE) © 2026 dsh-data-cleaning-agent plugin contributors
102
+
103
+ ## 参与
104
+
105
+ 如果这个插件帮你更快地清洗企业名单数据，欢迎
106
+ [GitHub 点个 Star](https://github.com/duhu2000/dsh-data-cleaning-agent/stargazers)、
107
+ [提交 Issue](https://github.com/duhu2000/dsh-data-cleaning-agent/issues) 或
108
+ [参与贡献](CONTRIBUTING.md)。
package/cordis.patch.yml ADDED
@@ -0,0 +1,6 @@
1
+ # 数据清洗补全智能体 插件（DSH Bundle patch）
2
+ # 作为 bundle 被合入 profile 时，自动插入本插件行。
3
+ # 插件负责 CSV/XLSX/JSON 解析、清洗/补全/画像模型工具、内嵌 Skill、任务状态机与 web UI 路由。
4
+ - insert:
5
+ - id: data-cleaning-agent
6
+ name: 'dsh-data-cleaning-agent'
package/docs/COMPATIBILITY.md ADDED
@@ -0,0 +1,45 @@
1
+ # 兼容性 / Compatibility
2
+
3
+ ## 1. 目标基线
4
+
5
+ 本插件面向 DeepSeek Harness（DSH）预发布阶段，双基线验证：
6
+
7
+ | 基线 | 框架 npm 包线 | 备注 |
8
+ | --- | --- | --- |
9
+ | rc.2 | `0.1.1-rc.2` | 本机 Desktop 内置；web 冒烟端口 43136 |
10
+ | alpha.2 | `0.1.2-alpha.2` | 官方最新预发布；web 冒烟端口 43137 |
11
+
12
+ > 生产 GUI（`http://127.0.0.1:43120`）不用于验证，验证一律使用隔离 `DSH_HOME` + 专用端口。
13
+
14
+ ## 2. Node 运行时
15
+
16
+ - 本包 `engines.node` 声明 `>=20`。
17
+ - CI 矩阵按 ADR-0001 收敛为 **Node 22 / 24**（本机 Desktop `engines` 为 `^22.19.0 || >=24.0.0`）。
18
+
19
+ ## 3. 契约面（Spike #1–#6 已实测）
20
+
21
+ | 契约 | 用法 | 备注 |
22
+ | --- | --- | --- |
23
+ | 插件注册 | `dsh.bundle.patch` → `cordis.patch.yml`（`insert` 插件行）+ `dsh.client` | 包声明 `dsh` 字段 |
24
+ | 模型工具 | `ctx.tools.register` | 需 `output.render` 返回 content 块数组 + `output.schema`；`required` 为对象级；name 不得为 `run_code` |
25
+ | 内嵌 Skill | `ctx.skills.register` | name `^[a-z0-9]+(?:-[a-z0-9]+)*$`，非空 description，get() 返回 truthy |
26
+ | 服务注入 | `ctx.inject([...])` | 访问未注入服务会抛 `cannot get property "x" without inject`；inject 数组必须列全 |
27
+ | Logger | `ctx.logger` | 仅 `error/info/warn/debug`，无 `.log` |
28
+ | 任务 | `ctx.jobs` | `attachController('data-cleaning-agent-mvp')` 后 `start({kind,label,run})` |
29
+ | 存储 | `ctx.storageDomain` | `open({name,version,tables})` → `table('jobs')` |
30
+ | web 路由 | `webServer.register({kind:'prefix', path, handler})` | 最长前缀匹配；前缀需以 `/` 结尾且匹配 `pathname.startsWith(prefix + '/')` |
31
+ | 同源守卫 | `isTrusted(req)` | `sec-fetch-site !== 'cross-site'` 且 origin 为 127.0.0.1/localhost |
32
+
33
+ ## 4. 与企查查 MCP OAuth 插件的共存（规划）
34
+
35
+ | | `qcc-dsh-mcp-oauth` | 本插件 |
36
+ | --- | --- | --- |
37
+ | 工具名前缀 | `qcc_oauth_*` + `mcp__qcc-*` | `data_clean_rows` / `data_complete_rows` / `data_profile` |
38
+ | 存储域 | 自有 grant store | `dc_tasks_v1` |
39
+ | 能否共存 | ✅ | ✅（工具名 / 存储域 / 条目 id 全独立） |
40
+
41
+ ## 5. 已知限制
42
+
43
+ - alpha.2 的 `@Remote` 契约仍可能变动，本包不对其作稳定 API 承诺。
44
+ - web 半区仅 web 组合可用；headless 组合自动跳过（工具与 Skill 仍注册）。
45
+ - XLSX 解析依赖 `xlsx`（懒加载），缺失时返回 `XLSX_UNAVAILABLE` 而非崩溃。
package/docs/FIRST-CONTRIBUTION.md ADDED
@@ -0,0 +1,43 @@
1
+ # 首次贡献路径 / First Contribution
2
+
3
+ ## 前提
4
+
5
+ - Node.js 20+、git、npm（DSH 运行期 peer 由 Host 提供，本地无需安装 DSH）。
6
+ - 一个 GitHub 账号。
7
+
8
+ ## 从 Fork 到 PR
9
+
10
+ ```bash
11
+ # 1. Fork 仓库：https://github.com/duhu2000/dsh-data-cleaning-agent
12
+ # 2. 克隆你的 fork
13
+ git clone https://github.com/<你>/dsh-data-cleaning-agent.git
14
+ cd dsh-data-cleaning-agent
15
+
16
+ # 3. 从最新 main 开单目的分支
17
+ git switch main
18
+ git pull --ff-only
19
+ git switch -c feat/<short-purpose>
20
+
21
+ # 4. 安装与自检
22
+ npm install --legacy-peer-deps
23
+ npm run check
24
+ ```
25
+
26
+ ## 适合首次贡献的改动
27
+
28
+ - 补充或修正 README / 使用指南中的示例与措辞。
29
+ - 增加无凭据、已脱敏的引擎测试夹具（`test/` 下新增 `node:test` 用例）。
30
+ - 改进 `lib/engine.js` 的清洗规则（如新增规范化函数）并补测试。
31
+ - 完善 `docs/USER-GUIDE.md` 或 `docs/COMPATIBILITY.md`。
32
+
33
+ ## 提交 PR
34
+
35
+ 1. 提交说明：用户问题 / 解决方案 / 测试结果 / 手工验收步骤。
36
+ 2. 确认 `npm run check` 全绿。
37
+ 3. Push 分支并在 GitHub 发起 PR，描述变更与验收截图（如涉及 UI）。
38
+ 4. 等待 CI 通过与维护者评审；评审意见会以 review 或 comment 形式给出。
39
+
40
+ ## 注意
41
+
42
+ - 不要把 Token / API Key / Cookie / OAuth 凭据 / 真实业务数据写进任何提交。
43
+ - 中英文文档需同步更新；README 中的版本号必须与 `package.json` 一致。
package/docs/USER-GUIDE.md ADDED
@@ -0,0 +1,57 @@
1
+ # 使用指南 / User Guide
2
+
3
+ ## 1. 安装
4
+
5
+ ```bash
6
+ dsh plugin --profile web add dsh-data-cleaning-agent
7
+ ```
8
+
9
+ 没有 `dsh` CLI 时：
10
+
11
+ ```bash
12
+ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-agent/main/install.sh)
13
+ ```
14
+
15
+ 安装后**完全重启** DeepSeek Harness。
16
+
17
+ ## 2. 使用方式
18
+
19
+ ### 2.1 对话式（推荐）
20
+
21
+ 在对话中说：
22
+
23
+ > 帮我清洗这批企业名单数据，先做画像，再清洗，缺失的金额补 0。
24
+
25
+ 插件会加载内嵌 Skill `data-cleaning`，自动按 `data_profile → data_clean_rows → data_complete_rows` 工作流调度。
26
+
27
+ ### 2.2 web 界面
28
+
29
+ 打开 DeepSeek Harness 后访问插件的同源界面（`/data-cleaning/`），可上传 CSV/XLSX/JSON，
30
+ 执行解析、清洗、补全、导出 CSV。web 界面的后端路由前缀为 `/data-cleaning/api/mvp/*`。
31
+
32
+ ## 3. 能力说明
33
+
34
+ | 工具 | 作用 |
35
+ | --- | --- |
36
+ | `data_profile` | 输出列概览与金额分布（min/max/sum/count） |
37
+ | `data_clean_rows` | trim、手机号规范化、剔除缺失必填/负金额/重复行 |
38
+ | `data_complete_rows` | 空金额填 0、空姓名填占位、报告不可确定性补全的项 |
39
+
40
+ ## 4. 数据边界
41
+
42
+ - 模型只收到统计摘要（total / kept / dropped / incomplete），**从不读取原始明细行**。
43
+ - 明细数据只经同源 web 端点（`127.0.0.1` / `localhost`）交付；非可信跨源请求被拒绝。
44
+ - 不要上传含真实敏感业务数据的文件到公开环境做演示；开发测试请用脱敏夹具。
45
+
46
+ ## 5. 支持的数据格式
47
+
48
+ - CSV：RFC4180 子集（引号字段、转义引号、字段内换行、BOM、CRLF）。
49
+ - XLSX / XLS：懒加载 `xlsx` 依赖；headless 组合无 `xlsx` 时返回 `XLSX_UNAVAILABLE`。
50
+ - JSON：对象数组，每项一行。
51
+
52
+ ## 6. 常见问题
53
+
54
+ - **Q：安装后工具不出现？** A：确认已完全重启 DSH；确认 `dsh plugin list`（或 profile 的
55
+ `package.json` → `dsh.profile.bundles`）含 `dsh-data-cleaning-agent`。
56
+ - **Q：XLSX 解析报 `XLSX_UNAVAILABLE`？** A：当前 DSH 组合未安装 `xlsx`；web 组合默认可用。
57
+ - **Q：能接企查查补全企业信息吗？** A：路线图见 [PLAN-OSS.md](PLAN-OSS.md)（方案 A 模型中介，后续版本）。
package/install.sh ADDED
@@ -0,0 +1,66 @@
1
+ #!/usr/bin/env bash
2
+ # dsh-data-cleaning-agent 一键安装脚本（DeepSeek Harness）
3
+ # 用法：
4
+ # 本地： bash install.sh
5
+ # 远端： bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-agent/main/install.sh)
6
+ # 支持：优先 dsh CLI（自动注册 bundle）；无 dsh 时回退 pnpm 并兜底注册 bundles。
7
+ # 幂等：重复执行不会重复注册或破坏已有配置。
8
+ set -euo pipefail
9
+
10
+ PKG="dsh-data-cleaning-agent"
11
+ DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
12
+ PROFILE="${DSH_PROFILE:-web}"
13
+ PROFILE_DIR="$DSH_HOME/profiles/$PROFILE"
14
+ PJ="$PROFILE_DIR/package.json"
15
+
16
+ echo "==> 目标 profile: $PROFILE_DIR"
17
+
18
+ if [ ! -d "$PROFILE_DIR" ]; then
19
+ echo "错误：profile 不存在：$PROFILE_DIR"
20
+ echo "请确认 DSH_HOME 与 DSH_PROFILE（默认 ~/.dsh 与 web）。"
21
+ exit 1
22
+ fi
23
+
24
+ # ── 1) 安装依赖 ──
25
+ if command -v dsh >/dev/null 2>&1; then
26
+ echo "==> dsh plugin --profile $PROFILE add $PKG"
27
+ dsh plugin --profile "$PROFILE" add "$PKG"
28
+ else
29
+ if command -v pnpm >/dev/null 2>&1; then
30
+ echo "==> 未找到 dsh CLI，回退 pnpm 安装（需自行确保 bundle 注册，见下）"
31
+ (cd "$PROFILE_DIR" && pnpm add "$PKG")
32
+ else
33
+ echo "错误：未找到 dsh 或 pnpm，无法安装。请先安装 DeepSeek Harness。"
34
+ exit 1
35
+ fi
36
+ fi
37
+
38
+ # ── 2) 确保 bundle 注册（dsh CLI 通常自动注册；此处兜底） ──
39
+ if [ -f "$PJ" ]; then
40
+ NEED=$(python3 - "$PJ" "$PKG" <<'PY' 2>/dev/null || echo "1"
41
+ import json, sys
42
+ d = json.load(open(sys.argv[1]))
43
+ print("0" if sys.argv[2] in d.get("dsh", {}).get("profile", {}).get("bundles", []) else "1")
44
+ PY
45
+ )
46
+ if [ "$NEED" = "1" ]; then
47
+ echo "==> 注册 bundle：$PKG"
48
+ python3 - "$PJ" "$PKG" <<'PY'
49
+ import json, sys
50
+ p, pkg = sys.argv[1], sys.argv[2]
51
+ d = json.load(open(p))
52
+ d.setdefault("dsh", {}).setdefault("profile", {}).setdefault("bundles", []).append(pkg)
53
+ json.dump(d, open(p, "w"), indent=2)
54
+ print("已添加", pkg)
55
+ PY
56
+ else
57
+ echo "==> bundle 已注册"
58
+ fi
59
+ else
60
+ echo "警告：未找到 $PJ，请确认 profile 完整。"
61
+ fi
62
+
63
+ echo
64
+ echo "✅ 安装完成！最后一步：重启 DeepSeek Harness（停止后重新运行 dsh web）。"
65
+ echo " 重启后在对话中输入「帮我清洗这批企业名单数据」即可使用。"
66
+ echo " 详见：https://github.com/duhu2000/dsh-data-cleaning-agent"
package/lib/client.js ADDED
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Client 半区（Spike #2 已实测的 Host↔Client 契约）：
3
+ * 通过 `window.__ModuleLoader__.load({id, factory})` 注册为惰性 CJS 工厂。
4
+ * materialize 后 `apply(ctx)` 拉取 host seam 并把结果放到 `window.__DC_MVP__`，
5
+ * 证明 client bundle 被扫描进 `__DSH_BOOT__` 并真实执行。
6
+ */
7
+ window.__ModuleLoader__.load({
8
+ id: 'dsh-data-cleaning-agent',
9
+ factory: (require) => {
10
+ var module = { exports: {} };
11
+ var exports = module.exports;
12
+ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
13
+
14
+ const inject = [];
15
+
16
+ function apply(ctx) {
17
+ // eslint-disable-next-line no-console
18
+ console.log('[dc-agent] client apply() ran');
19
+ const state = { applied: true, seam: null, error: null };
20
+ window.__DC_MVP__ = state;
21
+
22
+ fetch('/data-cleaning/api/mvp/seam')
23
+ .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`seam HTTP ${r.status}`))))
24
+ .then((data) => {
25
+ state.seam = data;
26
+ console.log('[dc-agent] client seam fetched:', data?.marker);
27
+ })
28
+ .catch((error) => {
29
+ state.error = error instanceof Error ? error.message : String(error);
30
+ console.warn('[dc-agent] client seam fetch failed:', state.error);
31
+ });
32
+ }
33
+
34
+ exports.apply = apply;
35
+ exports.inject = inject;
36
+ return module.exports;
37
+ },
38
+ });