@whyshu/argent-erp 0.0.0-stage → 0.2.3

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# @whyshu/argent-erp（v0.2.0）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**两件东西，一个货**：
+
+1. **DSH 会话视图插件**：会话顶部 Chat / 轨迹 旁加一个「ERP」tab，把 Argent ERP 的
+   办公室现场 / 待办 / 时间线 / 货件 / 聊一聊入口渲染进 dsh，看 ERP 不用离开当前会话；
+2. **「六禾园办公室助理」preset**：让「和办公室聊一聊」变成一个**真正的 dsh 会话**
+   （原生 Chat，含轨迹/统计/中断），但**边界写死在 preset 里**——只聊办公室、只读 ERP、无本机能力。
+
+> 目标不是把 ERP 后台搬空，而是把"看"和"聊"搬进会话；重编辑与写操作仍在 ERP web。
+> ERP 业务逻辑与数据始终在 `whyshu-svr`；本包**只读**。
+
+## 1. 结构
+
+```
+src/index.js              宿主插件：注册 /api/argent-erp/*（带账号 token 去 whyshu.com，token 不下发浏览器）
+src/data.mjs              数据层：whoami / overview / timeline / flow / shipment / chat 历史（经 vendor/redact 脱敏）
+src/office-guard.js       办公室会话的**工具边界**（preset 内挂载：只放行 mcp__argent__erp_*）
+src/vendor/               account-token.mjs + redact.mjs 的**副本**（插件可发布，不能相对 import core/lib）
+presets/argent-office.patch.yml   「六禾园办公室助理」preset 声明行（dsh 0.2.x 行式 preset）
+dist/client.js            客户端 bundle（手写维护）：注册 conversation.view（id=erp）+ 视图实现
+test/                     客户端 bundle + preset 边界冒烟测试（纯夹具，不启 dsh、不联网）
+```
+
+`package.json#dsh.bundle.patch` 是**数组**：`[cordis.patch.yml, presets/argent-office.patch.yml]`
+⇒ 一次 `install_bundle` 同时落「ERP 视图」与「办公室助理 preset」。
+
+## 2. 它是「会话视图」而不是「侧栏面板」
+
+dsh 0.2.x 的 `conversation.view` 槽 = 对话顶部那排 **Chat / 轨迹 / 统计** 的注册位。
+本插件向该槽注册一项：
+
+```js
+ctx.slots.inject("conversation.view", () => ctx.slots.register({
+  name: "conversation.view",
+  id: "erp",
+  order: 5,                 // Chat=0，本视图=5，轨迹=10
+  label: () => "ERP",
+  inject: () => ({ sessions, workspaceNav, remote }),   // 建会话 / 跳转 / 钉模型
+}, ErpView))
+```
+
+- 纯 UI 视图**不需要**注册 `ctx.uiConversation.views.register({ target })`
+  —— 那个 registry 是"消费 Session 事件"的 target 才需要的；ERP 视图读的是自己的宿主端点。
+- 视图随会话存在：切会话 → 视图重挂；切 tab 不丢别的 tab 状态。
+
+## 3. 视图内容
+
+| tab | 内容 | 数据来源（宿主端点） |
+|---|---|---|
+| 办公室 | KPI（待处理/在办/今日完成/执行机在线）+ 在岗员工 + 执行机 + 现场动态 | `/overview` |
+| 待办 | `workItems`（在办优先）→ 点开货件详情（节点 + 发票状态） | `/overview` → `/shipment` |
+| 时间线 | 最近 14 天 `/sku-flows` 按天分组 → 点开 8 节点详情 | `/timeline` → `/flow` |
+| 货件 | 关键词搜索货件 → 点开详情 | `/shipments` → `/shipment` |
+| 聊一聊 | **一键开「六禾园办公室助理」dsh 会话** + ERP 侧历史（只读） | 客户端 `sessions.create` |
+
+顶部：多租户下拉（`/me/tenants`）、刷新、更新于 HH:mm、完整版 ↗。时间一律 **24 小时制**。
+
+## 4. 「办公室聊一聊」为什么走「dsh 会话 + preset」（C 路线）
+
+### 4.1 直接把 ERP 的 chat 塞进 dsh Chat 视图是错的
+
+| 事实 | 证据 |
+|---|---|
+| ERP「办公室聊一聊」是**服务端** LLM + 工具循环：`POST /tenants/:appId/office/chat`，自定义 SSE（`meta/tool/card/proposal/delta/done`） | `whyshu-svr/admin/argent/office.js:2140-2214`；`whyshu-svr/src/routes/argentV1.js:1045-1263` |
+| 计费在服务端（积分/钱包/成员额度） | `argentV1.js:1071-1080, 1189-1208`；`services/walletBilling.js:28-120` |
+| 会话落 ERP：`OfficeChatSession`，`tenantId+userId` 双隔离 | `models/OfficeChatSession.js`；`services/officeChat.js:441-530` |
+| 而 dsh Chat 视图**硬绑 target `chat`**，其 target 由 `@deepseek-ai/dsh-client-ui-chat` 独占注册、**不允许重复注册** | `node_modules/@deepseek-ai/dsh-client-ui-chat/lib/client.js:15318, 15458-15545` |
+
+⇒ 把 ERP 的 SSE 翻译成 dsh SessionEvent = 给内核喂假事件，会污染轨迹/统计/成本口径。**不做。**
+
+### 4.2 现在的做法：让「办公室聊天」本身成为 dsh 会话
+
+`presets/argent-office.patch.yml` 声明 **`argent-office`（六禾园办公室助理）**：
+
+```
+persona（话题边界） + compaction（长会话自动压缩） + office-guard（工具边界）
+```
+
+从 ERP 视图的「聊一聊」点「和办公室聊一聊（dsh 会话）」⇒
+
+- **建在你当前 workspace**：`ctx.uiWorkspace.connectWorkspace(workspaceId, { agentPreset: 'argent-office' })`
+  （失败退回 `sessions.create({ agentPreset, workspaceId })`）；
+  ⚠️ 不传 workspaceId 会掉进"请选择 workspace"，用户选完后 UI 会另建 blank 会话、preset 被重置成默认（2026-11-07 实测）。
+- **模型钉死**：建好后 `ctx.remote.session.selectModel({ sessionId, provider: 'whyshu', model: 'deepseek-flash' })`
+  ⇒ 走问述代理/积分，而不是宿主默认的 deepseek-account；失败只提示、不阻塞（可在模型选择里手动选）。
+- 打开后就是原生 Chat（轨迹/统计/中断/队列全在）。
+
+ERP 网页里那个「办公室聊一聊」**保持原样**（服务端 SSE + 服务端计费），两条链路并存、互不冒充。
+
+### 4.3 边界是**三层**，不只靠提示词
+
+| 层 | 做法 | 说明 |
+|---|---|---|
+| ① 能力边界 | preset **不挂** `tool-bash` / `tool-pwsh` / `tool-fs` / `tool-fs-search` / `tool-web` / `tool-skill` / `tool-subagent` / `tool-workflow` 行 | 这个会话没有本机、终端、文件、联网、委派能力（web 组合已把宿主级这些工具行 disable，只有 preset 挂才有） |
+| ② 工具边界 | `office-guard` 用 `ctx.tools.restrict({ allow })` 把作用域内可见的**全局**工具收敛成只放行 `mcp__argent__erp_*` | Agent Team 等其余全局工具（它们由 profile 级 bundle 注册，对所有会话可见）对办公室会话**不可见**；按前缀匹配、运行时重算，不写死带后缀的工具名 |
+| ③ 话题边界 | persona 写死：只聊六禾园办公室（在办/待办/货件节点/发票/执行机/成员/日报/异常），其它话题统一拒绝并引导回来；事实必须先用 ERP 工具查证，不许编；只读，不做写操作 | 这是"模型意愿"层，和前两层叠加 |
+
+`office-guard` 的三条红线：永不抛出（否则整个 preset 不可用）、不写死工具名、无 `tools/change` 循环
+（allow 集合从全局视图算，集合不变就不再重注册）。
+
+### 4.4 已知取舍
+
+- **计费口径**：办公室会话在**创建时钉死** `whyshu / deepseek-flash`（走问述积分）；若用户事后手动切模型，以用户选择为准（本插件不抢占）。
+- **ERP「AI 团队」不接管**：那是**问述内部**用的通道，`create_session` 缺省仍走宿主默认 preset（2026-11-07 用户确认后已回退）；
+  只有 ERP **显式**选到 `argent-office` 时，机器侧才把该会话模型钉成同一套
+  （`plugins/argent/src/office-runtime.js`，env 可覆盖：`ARGENT_OFFICE_PRESET` / `ARGENT_OFFICE_MODEL_PROVIDER` / `ARGENT_OFFICE_MODEL`；
+  ⚠️ 该文件属 `@whyshu/argent`，改动要等它下次发版 + 重启才在客户机生效）。
+- **ERP 侧历史不互通**：ERP 的 `OfficeChatSession` 与 dsh Session 是两套存储；本视图的"历史"只读 ERP 那一侧。
+- **ERP 的 chat 续聊本来就没有服务端记忆**（前端只发 `{message, sessionId}`，服务端 messages 仅 = 现场快照 + 当前消息，
+  `argentV1.js:1083-1084`）——换成 dsh 真多轮反而是**能力升级**，但不要再指望两边记录对得上。
+- **反方向通道别混用**：ERP→执行机的 `office/sessions/*` 命令队列 + 「AI 团队」面板
+  （`plugins/argent/src/office-runtime.js` 机器对话执行器，`chatEnabled` 默认关）是"ERP 当 UI、dsh 当执行"，
+  与本方案方向相反。
+
+## 5. 端点（全部 GET，只读）
+
+| 路径 | 作用 |
+|---|---|
+| `/api/argent-erp/health` | 存活 + 版本 + `erpTools`（ERP 工具数；0=缺 @whyshu/argent）+ `officePreset` + `clientPingAt`（bundle 加载）/ `viewPingAt`（视图渲染）|
+| `/api/argent-erp/whoami` | 账号 + 租户列表 + 默认租户 |
+| `/api/argent-erp/overview?tenant=` | 办公室现场（KPI/在岗/执行机/待办 20/动态 10，脱敏） |
+| `/api/argent-erp/timeline?tenant=&days=` | 时间线（`/sku-flows`，按天分组） |
+| `/api/argent-erp/flow?tenant=&id=` | 流程详情（8+ 节点） |
+| `/api/argent-erp/shipment?tenant=&recordId=` | 货件详情 |
+| `/api/argent-erp/shipments?tenant=&q=&limit=` | 货件列表 |
+| `/api/argent-erp/chat/sessions?tenant=` | 「办公室聊一聊」历史列表（只读） |
+| `/api/argent-erp/chat/session?tenant=&id=` | 单个历史会话（只读） |
+
+## 6. 鉴权与隐私
+
+- token 解析唯一入口：`src/vendor/account-token.mjs`（env → `~/.dsh/.credentials.yaml` 的 `refs.WHYSHU_API_KEY`）；
+- token **只在宿主进程内存里**用于请求 whyshu.com，⛔ 不进浏览器、不落日志；
+- 结果经 `src/vendor/redact.mjs`：手机号打码、`token/downloadUrl/tenantId` 丢弃、长文本截断。
+
+## 7. 安装 / 验证 / 回滚
+
+### 7.0 用户安装（发布后）
+
+```text
+dsh 设置 → 插件（Plugins）→ 安装 bundle → @whyshu/argent-erp
+```
+
+- 装完**重启 dsh**（bundle patch 的宿主行与 preset 行在启动时装配）；
+- 之后新建会话的 **preset 选择器**里会出现「六禾园办公室助理」，对话顶部出现「ERP」tab；
+- ⚠️ **同机需要 `@whyshu/argent`**（≥0.2.0）：它提供 `mcp__argent__erp_*` 工具与 `whyshu` provider。
+  缺它时插件仍能装、视图仍能看（端点会报 no_token），但办公室角色会被 `office-guard` **安全降级为无工具**；
+  宿主 `/api/argent-erp/health` 的 `erpTools` 会返回 `0`（= 没有 ERP 工具），`-1` = 读不到 tools 服务。
+- 发布：`bash scripts/npm-publish-argent.sh --only argent-erp`（默认 dry-run；`--apply` 才真发）。
+
+```bash
+# 1) 装进当前 profile（DSH 原生；勿手写 profile 的 package.json / cordis.patch.yml）
+#    会话内用 plugin_manager install_bundle，target = 本包绝对路径
+#    重装（已装过新版）：remove_bundle → install_bundle
+
+# 2) 宿主端点
+curl -s http://127.0.0.1:3080/api/argent-erp/health      # {"ok":true,"version":"0.2.0",...}
+
+# 3) preset 行是否落了（应含 include:preset-argent-office）
+#    cordis_inspect_query host/Config/listConfigs name='@deepseek-ai/dsh-agent-preset'
+
+# 4) 客户端 tab 是否注册
+#    cordis_inspect_query client/Slots/listSubTree root='conversation.view'
+#    ⇒ occupants 含 { registrant: "argent-erp-client", id: "erp", order: 5, active: true }
+
+# 5) 单测（15 项，含 preset 边界断言）
+node plugins/argent-erp/test/client-bundle.test.mjs
+node plugins/argent/test/office-preset-default.test.mjs   # 机器执行器 preset/模型口径一致（8 项）
+```
+
+- 宿主侧改动**需要用户手动重启 dsh**（⛔ agent 不重启）；客户端 bundle 改动只需浏览器硬刷新。
+- 回滚：`plugin_manager remove_bundle @whyshu/argent-erp` 后重启（视图与办公室 preset 一起下线）。
+
+## 8. 已知限制
+
+- 只读：写操作（派单/开票执行/聊天写动作）仍走 ERP web；
+- 工具边界是"收敛全局工具"，**不含**进 ERP 写路径（ERP 还没 `POST /office/actions/prepare`）；
+- 3D 办公室场景（`office-scene-3d.js` + vendored three.js）**不搬**：面板尺寸/性能都不划算，只搬数据卡片；
+- 与旧包 `@whyshu/argent-erp-ui`（右侧栏面板，v0.9.0）**不要同时装**：两者都注册 `/api/argent-erp/*`。
+  旧包保留作回退。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# argent-erp bundle patch：只注册一行。
+#   宿主侧：只读端点 /api/argent-erp/*（token 只在宿主进程，不下发浏览器）
+#   客户端：对话顶部注册一个 conversation.view tab（id=erp），按会话维度渲染 ERP 视图
+- insert:
+    - id: argent-erp
+      name: '@whyshu/argent-erp'