@shundoo-ai/dsh-cosmic 1.0.16 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shundoo-ai/dsh-cosmic",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "苍穹助手：金蝶云苍穹ERP的开发与数据分析，涵盖表单元数据建模、插件开发与热部署、数据可视化报告。",
   "keywords": [
     "dsh",

package/skills/analysis-monthend-compare/SKILL.md

@@ -70,7 +70,9 @@ all_rows = []
 for mon, sd, ed in months:  # mon 已是中性日期（M1N/M2N）
     payload = {
         'entityId': 'sd_weighingbill',
-        'selectFields': 'id,billno,billstatus,netwbqty1,plate,biztime,billtype.name,org.name',
+        # ⚠️ cancelstatus/closestatus 必需：§4.2 findings 的「作废率/关闭率」取 kpi[mon]['canceled_cnt']/['closed_cnt']，
+        #    缺这两个字段会 KeyError（实测 2026-09-25：按本节逐字执行时须自行补上才通过）
+        'selectFields': 'id,billno,billstatus,cancelstatus,closestatus,netwbqty1,plate,biztime,billtype.name,org.name',
         'filters': f"biztime >= TO_DATE('{sd}') AND biztime < TO_DATE('{ed}')",
         'orderBys': 'id', 'pageSize': 10000, 'pageNo': 1, 'cacheId': ''
     }

package/skills/analysis-weighingbill-distribution/SKILL.md

@@ -144,8 +144,13 @@ df_supplier = df_entry.groupby('entryentity.supplier.name').agg(
 
 ```python
 # 净重分布分桶（基于步骤 1 的 df）
-# ⚠️ 单位口径：netwbqty1 单位 kg；桶边界 10000/20000/… = 10吨/20吨/…（pd.cut 默认左开右闭，10000 归「10-20吨」档）
-#   报告净重统一 ÷1000 转吨（如 net_ton = sum/1000），全程勿混 kg/吨
+# ⚠️ 单位口径：netwbqty1 单位 kg（报告统一 ÷1000 转吨，如 net_ton = sum/1000，全程勿混 kg/吨）；
+#   桶边界 10000/20000/… = 10吨/20吨/…，pd.cut 默认左开右闭 (a, b]，边界值归**左侧**桶：
+#   10000 归「0-10吨」、40000 归「30-40吨」（实测 2026-09-25：==10000 的 23 单全落「0-10吨」——勿写成归「10-20吨」）
+# ⚠️ 第 6 桶区间 (50000, ∞] 与标签「≥50吨」差一个边界点，而 findings 用 (netwbqty1 >= 50000)：
+#   恰好 ==50000 kg 的单入「5. 40-50吨」桶却计为异常大车 → 两处数字可差该单量
+#   （实测 2026-09-25：4月 1 单 ==50000 → 区间表 197 vs findings 198；量级 0.006%，不改 🟡 判级，
+#    但同报告内同概念两个值易被质疑 → 可将标签改「>50吨」或在口径说明中注明）
 df['bucket'] = pd.cut(df['netwbqty1'],
     bins=[-1, 0, 10000, 20000, 30000, 40000, 50000, float('inf')],
     labels=['0. 零净重', '1. 0-10吨', '2. 10-20吨', '3. 20-30吨', '4. 30-40吨', '5. 40-50吨', '6. ≥50吨'])

package/skills/erp-analysis/SKILL.md

@@ -124,25 +124,22 @@ HTML/Markdown 参数详见 `references/html-report-guide.md` / `references/markd
 - 数据缓存 `api_data_cache.pkl`、图表、HTML 报告都在同一目录下。
 - HTML 报告 = plotly `fig.to_html()` 交互图（无需 kaleido/PNG）。
 
-## 交付清单（可点击文件，关键机制）
+## 交付清单（present 交付卡片，关键机制）
 
-DSH 会话界面只有 `write`/`edit` 工具**本轮**触碰过的文件才会出现可点击芯片；bash 脚本生成的产物（HTML 报告、pkl 缓存）**默认不可点击**；芯片**按轮生效**（上轮 touch 的，下轮清单里不再出现）；报告 HTML 是 100KB+ 的 plotly JSON，`read`+`write` 全文会无意义灌 token，**禁止**。
+> 🔒 **交付机制的唯一权威是 `references/delivery-contract.md`**（含版本锚点）。本节只留要点，冲突以该文件为准。
 
-### 交付策略（唯一默认：edit 触碰模式）
+**交付物（报告 HTML / 导出 Excel / MD）落盘后，一律用 `present` 工具声明交付**：
 
-报告脚本 `build_and_write()` 生成 HTML 后，Agent 用 `edit` 工具对报告文件做一次**零风险微小改动**（追加一行 HTML 注释），使 HTML 在**本轮**被 write/edit 类工具「触碰」而生成可点击芯片：
-
-1. `grep` 定位唯一锚点 `</html>` 的行号；
-2. `read` 该锚点附近 1–2 行（满足 fs-observation-policy，几乎不耗 token）；
-3. `edit` 把 `</html>` 替换为 `<!-- dsh: <分析主题> -->\n</html>`（HTML 注释无害，不影响渲染与 plotly JSON）。
-
-然后**回复里用 inline code 引用 HTML 报告——须用 `edit` 返回的精确路径（绝对路径）或 basename（本轮唯一时），勿写 `runs/...` 相对路径**（相对路径不渲染成可点击芯片）；chat 报告已在会话界面直接展示，不落盘。
+```
+present(files=[{path, description}])     # 一次 1–2 个最重要的，最多 4 个
+```
 
-### 中间产物（不生成芯片）
+- **`present` 是交付入口的唯一来源**；报告 HTML 由脚本经 bash 生成，**必须** present。
+- 回复里照旧用 inline-code 引用路径（**精确绝对路径**或本轮唯一的 basename；勿写 `runs/...` 相对路径）。
 
-`api_data_cache.pkl` / `analysis_bundle.pkl` / `write_log.json` 是 agent 工作产物（缓存/重跑/追溯），非用户交付物。需要时用 inline code 引用路径即可，**不生成可点击芯片**。
+### 中间产物（不交付）
 
-> ⚠️ 芯片**按轮生效**：默认**不主动处理**历史产物；仅当用户后续轮次明确表示「点不开 / 想打开」时，才对目标 HTML 做一次小 `edit`（追加/移除一个注释）恢复可点击，内容零损伤。
+`api_data_cache.pkl` / `analysis_bundle.pkl` / `write_log.json` 是 agent 工作产物（缓存/重跑/追溯），非用户交付物。需要时用 inline code 引用路径即可，**不 present**。chat 报告已在会话界面直接展示，不落盘。
 
 ## 运行时与凭证
 

package/skills/erp-analysis/references/delivery-contract.md

@@ -0,0 +1,91 @@
+# DSH 交付契约（ERP 数据分析产物）
+
+> **本文是 ERP 数据分析产物「如何交付给用户」的唯一权威。**
+> SKILL.md《交付清单》、`html-report-guide.md` §三、`markdown-report-guide.md` 一律**引用本文**，
+> 不再各自描述交付机制（历史上同一件事写在 3 处，正是它各自漂移、集体过时的原因）。
+>
+> **版本锚点**：`@deepseek-ai/dsh-desktop-runtime 0.1.7-rc.2`（2026-09-25 验证）
+
+## 一. 契约（做什么）
+
+数据分析产物（报告 HTML、导出 Excel/Word、Markdown 报告等）**落盘之后**，
+调用 `present` 工具声明交付：
+
+```
+present(files=[{path, description}])
+```
+
+| 项 | 约定 |
+|---|---|
+| 调用时机 | 文件**已落盘之后**。`present` 只校验常规文件元数据，所以文件必须先真实存在 |
+| 数量 | 一次 **1–2 个最重要的**交付物，最多 4 个 |
+| 路径 | 相对路径按 Session 工作目录解析；绝对路径可用（可指向工作区外，如 `/tmp`、Downloads） |
+| 描述 | 写**业务含义**（如「2026年6月过磅单分布分析（7 张交互图）」），不要只写文件名 |
+| **bash 产物** | **必须** present —— 报告 HTML 由报告脚本经 bash 生成，不经 present 就没有交付入口 |
+
+**效果**：回复下方出现**交付卡片**（basename + 描述 + 侧边栏预览 + 「用默认程序打开」）。
+
+## 二. 边界（不做什么）
+
+1. **不交付中间产物与脚本。**
+   `api_data_cache.pkl` / `analysis_bundle.pkl` / `write_log.json` / 取数与报告脚本都是 agent
+   工作产物（缓存、重跑、追溯），需要时用 inline code 引用路径即可，**不进 present**。
+
+2. **不放任交付物数量。** 一次分析通常只有 1 份主报告；多个变体（如 HTML + Excel）最多 2 份。
+
+3. **不重复展示。** chat 报告已在会话里渲染成表格，HTML 报告走交付卡片，两者内容重叠时不再互相复述。
+
+4. **不为交付而 `read` / `write` 交付物全文。**
+   报告 HTML 是 100KB+ 的 plotly JSON，全文读或写会无意义灌 token。
+   交付前只需确认「文件已落盘」（存在 + 大小），**禁止** `read` 全文、**禁止** `read`+`write` 回写。
+   `present` 本身不读文件内容，这正是它优于文件操作的地方。
+
+5. **不用文件操作去换「可见性」。**
+   交付入口只能由 `present` 产生；不要为了让产物在界面上更好点，对交付物做无意义的写操作。
+
+## 三. 引用与降级
+
+**正文引用**：在回复里用 markdown inline code 写**精确路径** —— 绝对路径，或本轮改动文件中唯一的 basename。
+**勿写** `runs/...` 相对路径（不会被解析）。
+
+```
+/Users/<user>/deepseek/<工作区>/runs/<session_key>/<analysis_id>/过磅单分析_20260716.html
+```
+
+**降级**（`present` 不可用时）：
+
+| 顺位 | 手段 | 用户看到的效果 |
+|---|---|---|
+| 1 | `present` | 交付卡片（预览 + 默认程序打开） |
+| 2 | 正文给出**绝对路径** | 用户手动打开 |
+
+> ⚠️ 降到第 2 档时**如实接受"不能点"**，不要为制造可点效果去折腾文件。
+> 也不要在手写表格里罗列图表清单冒充交付卡片——那是内容，不是交付入口。
+
+## 四. 版本锚点与复验
+
+- **依据版本**：`@deepseek-ai/dsh-desktop-runtime 0.1.7-rc.2`（2026-09-25 实测）
+- **复验触发**：DSH / preset 升级后
+- **复验方法**：确认 `present` 工具仍在工具清单中、且调用后回复下方出现交付卡片。
+  两者任一不成立 → 按实际情况改版本文（判断依据见文末附录）。
+
+## 五. 变更记录
+
+| 日期 | 版本锚点 | 变更 |
+|---|---|---|
+| 2026-09-25 | 0.1.7-rc.2 | 新建。交付手段定为 `present`；移除了旧版「靠文件操作换取可点入口」的整套描述 |
+
+---
+
+## 附录：当时的判断依据（版本锚定 · **非操作指引**）
+
+> 仅用于日后复验「为什么这样定」，**不要**据此推断平台当前行为。
+
+在 `0.1.7-rc.2` 这一版：
+
+- `present` 由 `dsh-web-app/presets/standard.patch.yml` 挂载（工具 schema 见 `dsh-tool-present`），
+  交付卡片由客户端 `ui-deliverables` 消费 `deliverables/presented` 事件渲染。
+- 该版客户端另有一条「正文提及解析」通道，会把**本轮经 `write`/`edit` 改过的路径**也纳入解析范围，
+  使正文引用可点；这条通道**只影响正文提及**，不产生交付卡片。
+  旧文档曾把这条通道误当成交付手段并写成「唯一默认策略」——这是本次改版的直接起因。
+- 上述两条都是**该版本的内部实现**，随时可能变化；契约正文因此只依赖 `present` 这个公开工具。

package/skills/erp-analysis/references/html-report-guide.md

@@ -13,7 +13,7 @@
 
 1. **在取数脚本中生成图表 HTML 片段**：plotly `fig.to_html(full_html=False, include_plotlyjs='cdn')`（第一张图传 `'cdn'` 引入 CDN，其余传 `False`）
 2. **在报告脚本中调用 `build_and_write()`**：传入 title/kpis/detail_sections/charts/findings/trend，函数自动拼接 CSS + HTML + 写入文件（两脚本分工见 §四）
-3. **交付**：`build_and_write()` 返回值即为文件路径，Agent 在回复中用 markdown inline code 引用该路径；并按第三节 edit 触碰让文件生成可点击芯片（见第三节）
+3. **交付**：`build_and_write()` 返回值即为文件路径，**调用 `present` 工具声明交付**，并在回复中用 markdown inline code 引用该路径（**详见第三节 + `delivery-contract.md`**）
 
 | 区域 | 构建方式 |
 |---|---|
@@ -95,22 +95,27 @@ for title in titles:
 
 文件名格式：`{主标题}_{YYYYMMDD}.html`（从 title 前 20 字符 + 当日日期自动拼装，中英文均可）。同 `analysis_id` 目录内同 title 会覆盖——这是正确行为，同一次分析同一主题产物就是同一份。
 
-## 三. 交付方式（edit 触碰模式）
+## 三. 交付方式（`present`）
 
-`build_and_write()` 生成 HTML 后，Agent 用 `edit` 工具对报告文件做一次零风险微小改动（追加 HTML 注释），使 HTML 在**本轮**被 write/edit 类工具触碰而生成可点击芯片——无需 read+write 全文（避免 100KB+ plotly JSON 灌进上下文）：
+> 🔒 **完整契约见 `delivery-contract.md`**（版本锚点、降级链、判断依据）。本节只讲调用。
 
-1. `grep` 定位唯一锚点 `</html>` 的行号；
-2. `read` 该锚点附近 1–2 行（满足 fs-observation-policy，几乎不耗 token）；
-3. `edit` 将 `</html>` 替换为 `<!-- dsh: <分析主题> -->\n</html>`。
+`build_and_write()` 生成 HTML 后，**直接调用 `present` 声明交付**：
 
-然后 Agent 在回复中用 markdown inline code 引用该文件（当轮可点击变蓝）。⚠️ **引用须用 `edit` 工具返回的精确路径（exact file-tool path，即绝对路径）或 basename（本轮改动文件中唯一时）**——写 `runs/...` 相对路径不会渲染成可点击芯片：
+```python
+present(files=[{"path": html_path, "description": "2026年6月过磅单全维度分布分析（7 张交互图）"}])
+```
+
+- 一次 **1–2 个最重要的**交付物，最多 4 个；路径可用绝对路径。
+- **bash 脚本生成的 HTML 必须 present**——否则没有交付入口。
+- ⚠️ **不要 `read` 报告 HTML 全文**（100KB+ 的 plotly JSON 会无意义灌 token）。`present` 只校验文件元数据、不读内容，交付前确认「已落盘」即可；**禁止** `read`+`write` 回写。
+- 然后 Agent 在回复中用 markdown inline code 引用该文件。⚠️ **引用须用精确路径（绝对路径）或 basename（本轮改动文件中唯一时）**——写 `runs/...` 相对路径不会被解析成可点链接：
 
 ```
 /Users/<user>/deepseek/<工作区>/runs/<session_key>/<analysis_id>/过磅单分析_20260716.html
 ```
 
 > 绝对路径直接取 `build_and_write()` 的返回值即可。
-> 可点击芯片**按轮生效**：默认**不主动处理**历史产物；仅当用户后续轮次明确表示「点不开 / 想打开」时，才对目标 HTML 做一次小 `edit`（追加/移除一个注释）恢复可点击，内容零损伤。中间产物（pkl 缓存 / bundle / 写操作日志）不生成芯片，需要时 inline code 引用路径即可。
+> 中间产物（pkl 缓存 / bundle / 写操作日志）不交付，需要时 inline code 引用路径即可。
 
 ## 四. 完整示例（取数脚本 + 报告脚本）
 
@@ -240,7 +245,7 @@ print(f"HTML: {path}")
 | -100% 消失 | == -100% | `pct-drop`（紫底） |
 | 新增 | 字符串"新增" | `pct-new`（蓝底） |
 
-> **浏览器打开场景**（HTML 报告通过 deliverables 文件芯片点开后浏览器打开）：模板的 `linear-gradient` 和 `border-radius` 等 CSS3 特性在浏览器中完全支持。不限制渐变、圆角等现代 CSS 特性。
+> **浏览器打开场景**（HTML 报告通过 `present` 交付卡片点开后浏览器打开）：模板的 `linear-gradient` 和 `border-radius` 等 CSS3 特性在浏览器中完全支持。不限制渐变、圆角等现代 CSS 特性。
 
 ## 八. 常见 API 契约陷阱
 

package/skills/erp-analysis/references/markdown-report-guide.md

@@ -24,7 +24,7 @@ DSH 的 Markdown 报告只有一种载体——**聊天中直接输出 Markdown
 **落盘目录 = 脚本内 `OUT_DIR` 变量**（`OUT_DIR = os.environ["OUT_DIR"]`，由 run.py 注入，cwd = 工作目录）。
 
 1. `build_and_write_md(analysis_id=analysis_id)` → 返回落盘的**绝对路径**（`<标题>.md`）
-2. 返回值即文件路径，Agent 在回复中用 markdown inline code 引用——**用返回值（绝对路径）或 basename（本轮唯一时），勿写 `runs/...` 相对路径**（相对路径不渲染成可点击芯片）：
+2. 返回值即文件路径：**调用 `present` 声明交付**（见 `delivery-contract.md`），并在回复中用 markdown inline code 引用——**用返回值（绝对路径）或 basename（本轮唯一时），勿写 `runs/...` 相对路径**（相对路径不会被解析成可点链接）：
 
 ```
 /Users/<user>/deepseek/<工作区>/runs/<session_key>/<analysis_id>/过磅单异常_20260719.md

package/skills/erp-analysis/templates/AGENTS.template.md

@@ -47,4 +47,17 @@
 > 📌 **发邮件不需要提权**：`send_email.py` 用 `password = "授权码"` 时明文直读、**不起子进程**，纯网络调用，任何平台都无需放开权限。（只有 `auth_cmd` 那条路要起子进程捕获 stdout，Windows 受限令牌下才需提权 —— 见 `references/email-delivery.md`。）
 > 📌 app-build 脚本（`bootstrap_cosmic_context.py` / `appconfig_load.py` / `prepare_plugin_handoff.py` / `compile_plugin_source.py` / `pipeline_gate.py` / `register_plugins.py` / `render_output_cards.py` 等）同样统一用 `{VENV}/bin/python` 执行——app-build SKILL.md 模板里的 `python3 {ROOT_DIR}/scripts/...` 写法与本约定冲突时，以本约定为准。
 
-<!-- 后续按需补充：数据分析、元数据建模等约定 -->
+## 交付约定（数据分析产物 · DSH 界面）
+
+数据分析产物（报告 HTML、导出 Excel/Word）落盘后，**一律用 `present` 工具声明交付**：
+`present(files=[{path, description}])` —— 一次 1–2 个最重要的，最多 4 个。
+
+- **`present` 是交付入口的唯一来源**；bash 脚本生成的报告 HTML **必须** present。
+- 中间产物（`api_data_cache.pkl` / `analysis_bundle.pkl` / `write_log.json`）与脚本**不交付**。
+- 完整契约（降级链、判断依据、版本锚点）：
+  `{PRESET}/skills/erp-analysis/references/delivery-contract.md`
+
+> 版本锚点：`@deepseek-ai/dsh-desktop-runtime 0.1.7-rc.2`（2026-09-25 验证）。
+> DSH / preset 升级后若 `present` 消失或交付卡片不再出现，回到该契约文件复验。
+
+<!-- 后续按需补充：元数据建模等约定 -->