dsh-dock 0.4.0 → 0.5.0

package/README.md

@@ -3,238 +3,181 @@
 [![npm version](https://img.shields.io/npm/v/dsh-dock)](https://www.npmjs.com/package/dsh-dock)
 [![license](https://img.shields.io/npm/l/dsh-dock)](LICENSE)
 
-**DeepSeek Harness 功能坞插件（dsh-dock）**：用一张管理面板，统一注册、开关所有小功能。
+**DeepSeek Harness 功能坞插件**：用一张管理面板，统一注册、开关所有小功能。
 
-模型余额、用量记录、任务动画……这些散落的小功能，全部收进一个「功能坞」：
+模型余额、用量记录、模型设置、图片理解代理……这些散落的小功能，全部收进一个「功能坞」：
 每个功能是独立模块，有注册表、有开关、有错误隔离。新功能按模块追加，老功能互不牵连。
 
-> **v0.4.0 起为模块化架构**：功能坞 = hub + 一个个独立功能模块（像 dsh 本身由小包组成）。
-> 每个功能是一个 `features/<id>/` 目录（宿主半部 + 客户端视图），**可整体拎出单独打包发布**
-> （`scripts/extract-feature.mjs` 生成独立包骨架）；独立发布的功能包装回后，经
-> **dockBridge** 注册进功能坞菜单——「单独成包」与「完美集成」两全。
->
-> 前身：本地原型 `feature-hub`（已安装验证），本包为其正式发布的 npm 版本。
-> 相关功能包：`@wycto/dsh-balance-panel`、`@wycto/dsh-token-usage`、`@wycto/dsh-task-pulse`
-> （余额功能已于 0.2.0 吸收为中枢内模块；用量记录已于 0.4.0 以模块化方式重吸收）。
-> 开发背景与决策见 [docs/session-notes.md](docs/session-notes.md)。
+![功能坞首页总揽](screenshots/dock-home.png)
 
 ---
 
-## 当前状态（v0.4.0 · 模块化架构 + 用量记录已接入）
-
-- ✅ **模块化架构（0.4.0）**：功能代码从两个大文件拆进 `features/<id>/` 模块目录；
-  宿主半部 `index.js` 与客户端外壳 `src/client.jsx` 只做组装，不含功能逻辑；
-  每个模块可单独提取成包（见下文「提取一个功能成独立包」）
-- ✅ **用量记录（0.4.0）**：记录全部 LLM API 调用并统计——
-  - 秒级时间范围 + 会话/提供商/模型（联动）/状态/推理强度筛选，条件本地暂存（下次打开恢复）；
-  - 9 张 KPI 卡（调用次数 / 总 Token / 输入 / 缓存命中 / 命中率 / 输出 / 金额($) / 金额(¥) / 累计耗时）；
-  - 分组统计（无/provider/model/status/effort 维度切换）；
-  - 明细表 15 列可排序、100 行/页上下双分页、会话 ID 点击即筛选、行详情弹窗、CSV 导出；
-  - 定价引擎：内置 DeepSeek 峰谷价目 + 官网价目每日自动抓取 + `dsh-dock-tokenlog` 命名空间覆盖；
-  - 首页总揽「今日调用/Token/花费」卡片；面板打开期间每 5 秒自动刷新
-- ✅ 设置页「功能坞」面板（侧栏底部 → 设置 → 功能坞）
-- ✅ **侧栏入口按钮**：侧栏底部动作区右端「功能坞」按钮，弹出**功能面板**（居中模态：左导航 = 首页总揽 + 各功能模块按 order 排序，右内容区）
-- ✅ **弹层窗口化**：默认大窗（1080×700 自适应），最大化/最小化/还原、标题栏拖动、右下角缩放；几何页内记忆
-- ✅ **模型设置（0.3.0，集成官方链路）**：编辑各 Provider 模型目录（输入类型 + 思考强度档位），`settings.mutate` 写回官方配置热生效
-- ✅ **模型余额（0.2.0）**：枚举全部已配置 Provider，内置策略表查询余额/配额/控制台链接，5 分钟自动刷新
-- ✅ 每功能独立开关 + 错误隔离：单个功能出错只降级自己（外部包视图另有错误边界保护）
-- ✅ 示例功能：心跳监视、主题信息（纯 Client，开箱可用）
-- ✅ **会话区随身小控件（0.4.0）**：启用后在会话输入区工具行（模型选择器左侧）显示——
-  - **模型余额**：当前选中 Provider 的账户余额（随余额刷新更新），点击打开功能坞并高亮该 Provider 行；
-  - **用量记录**：当前会话总 Token 与估算花费（10s 静默刷新），点击打开功能坞并按该会话筛选；
-  - 每个功能可单独设置「会话页显示/隐藏」（面板页脚与设置页均有开关，localStorage 持久化）
-- 🚧 功能开关为浏览器内存态，刷新重置（持久化在 0.6.0）
-- 🚧 任务动画已登记为规划占位（0.5.0）
-
-### 模块化架构（0.4.0）
+## 功能一览
 
-```
-dsh-dock/
-├── index.js                  # 宿主半部入口（纯 ESM，零构建）：import 各模块组装注册表与生命周期
-├── client.js                 # 客户端 bundle（构建产物，提交仓库；源码见 src/ + features/）
-├── src/
-│   ├── client.jsx            # 客户端外壳：入口按钮/弹层/设置页/首页总揽/slots 注册/外部功能桥
-│   ├── shared.js             # 共享工具（外部视图错误边界等）
-│   └── host-core.js          # 宿主共享内核（DOCK_NS 命名空间、sendJson/readBody/walkPath）
-├── features/                 # ★ 一个目录 = 一个功能模块（整体可拎出单独打包）
-│   ├── balance/              #   host.js + view.js
-│   ├── modelconfig/          #   host.js + view.js（含图片理解代理配置面板）
-│   ├── visionproxy/          #   host.js（纯宿主功能，UI 在 modelconfig 页内）
-│   ├── tokenlog/             #   host.js + view.jsx（用量记录）
-│   ├── heartbeat/            #   view.js（纯客户端功能）
-│   └── theme/                #   view.js（纯客户端功能）
-├── scripts/
-│   ├── build-client.mjs      # esbuild bundle → client.js（改视图后需重跑）
-│   ├── extract-feature.mjs   # 功能提取脚手架：features/<id> → 独立包目录
-│   └── publish.sh            # 一键发布
-└── docs/session-notes.md     # 会话总结与决策记录
-```
+| 功能 | 说明 |
+|---|---|
+| **用量记录** | 记录全部 LLM API 调用：秒级时间筛选、Token/费用统计（峰谷计价 + 官网价目自动同步）、分组汇总、明细检索与 CSV 导出 |
+| **模型设置** | 编辑各 Provider 模型目录：输入类型（文本/图片 + 标注）与思考强度档位；写回官方配置热生效 |
+| **模型余额** | 展示所有模型 Provider 账户余额（5 分钟自动刷新） |
+| **任务动画** | 任务运行动画（流光细线 / 呼吸光点 / 轨道光环 / 环屏巡航 / 代码雨 / 星野 / 极光 / 桌面伙伴 3D 场景，共 8 种氛围模式）与完成通知（通知音、浏览器系统通知、钉钉群机器人推送），动画、通知两组开关独立，配置全部持久化 |
+| **图片理解代理** | 图片识别等（visionproxy） |
+| **心跳监视 / 主题信息** | 示例功能（纯 Client） |
 
-**模块契约**：
+**会话区随身小控件**：启用后，在会话输入区工具行（模型选择器左侧）显示——
 
-- 宿主模块 `features/<id>/host.js` 导出 `feature = { id, name, description, defaultEnabled, setup(ctx) → disposer }`；
-- 视图模块 `features/<id>/view.js(x)` 导出 `feature = { id, name, order, accent, description, css, View, HomeStat? }`；
-  `order` 决定菜单次序（首页固定第一；modelconfig=100 → 第二菜单，tokenlog=110 第三）；
-  视图收到 `{ ctx, feature, params }` props（`params` 来自导航总线：chips 点击可带入
-  `{ provider }` 高亮余额行、`{ sessionId }` 按会话筛选用量）；
-  可选 `Chip` 组件（`{ ctx, session, sessionId, input, feature }` props）：启用且「会话页显示」
-  时渲染在会话输入区工具行左端（`conversation.input.left`，模型选择器左侧），点击通常经
-  `openPanel(id, params)` 打开功能坞定位到对应功能页；
-  每模块自带 `css`（类名前缀隔离：dkb-/dkm-/dtok- …），外壳统一注入；
-- 客户端外壳 `src/client.jsx`：import 模块 → 组装导航/首页/设置页；导出
-  `apply` / `inject` / **`dockBridge`**（外部功能回装通道）。
+- **模型余额**：当前选中 Provider 的账户余额（跟随模型切换实时更新），点击打开功能坞并定位到该 Provider 的余额详情；
+- **用量记录**：当前会话的总 Token 与估算花费（10 秒静默刷新），点击打开功能坞并跳转到该会话的用量记录。
 
-**为什么客户端引入了构建**（v0.4.0 决策，宿主半部仍是零构建纯 ESM）：
-功能模块用真实源码文件 + JSX 组织，esbuild 打成单文件 `client.js`
-（`react`/`react/jsx-runtime` 由运行时 seed，外部化；与 `@wycto/dsh-token-usage`
-已在线上验证的构建模式同款）。改客户端代码后跑 `node scripts/build-client.mjs`。
+![会话区余额/用量小控件](screenshots/dock-chips.png)
 
-## 面板入口
+勾选「启用」即显示，点芯片跳转；每个功能可在面板页脚或设置页单独设置「会话页显示/隐藏」。
 
-```
-① 快捷入口：侧栏底部「功能坞」按钮（与设置按钮同底对齐）→ 弹出功能面板（首页总揽 + 模块导航 + 内容区，窗口可最大化/最小化/拖动/缩放）
-② 完整面板：设置（侧栏底部）→ 功能坞
-```
+## 界面
 
-入口按钮与功能弹层挂载在 shell 的 `sidebar.footer.action` / `shell.overlay` 座位；
-弹层与完整面板共用各功能的模块级共享快照
-（余额 `/dsh-dock/balance`、模型目录 `/dsh-dock/models`、用量 `/dsh-dock/tokenlog/*`，首页总揽概要与各视图同源）。
+点击侧栏底部「功能坞」按钮，弹出功能面板：左侧导航 = 首页总揽 + 各功能模块，右侧内容区。
 
-### 用量记录（0.4.0）
+![用量记录页](screenshots/dock-tokenlog.png)
 
-- **数据源**：DSH 会话日志（`sessionQuery` 服务）。宿主实时监听 `session/event` 增量记账，
-  启动时全量扫描历史（`sessionId:seq` 幂等去重，实时与扫描重叠不双计）；
-  记录含五类 token 桶、状态/错误码（`turn/end` 两遍式回填）、耗时（step/start → assistant/message）。
-- **定价与金额（估算）**：内置 DeepSeek-V4 峰谷刊例（高峰每日 9:00–14:00 双倍）等；
-  每 24h 自动抓取官网价目页（失败静默回退内置）；汇率与价目可在 settings.yaml 覆盖：
+面板支持最大化 / 最小化 / 还原、标题栏拖动、右下角缩放。
 
-  ```yaml
-  dsh-dock-tokenlog:
-    usdCnyRate: 7.2
-    pricingUrl: 'https://api-docs.deepseek.com/zh-cn/quick_start/pricing'
-    pricingFetchIntervalHours: 24
-    pricing:
-      deepseek-v4-flash: { input: 1.5, output: 4.5, cacheRead: 0.05, cacheWrite: 0 }
-  ```
+---
 
-  改价即时生效（查询/导出时按当前价目重算历史）。
-- **RPC**：`POST /dsh-dock/tokenlog/query|export|scan`（同源 webServer 路由）。
-- 已知口径：金额为估算；失败调用（无 `assistant/message`）不产生 token 行，状态反映回合结局。
+## 安装
 
-### 模型余额支持情况（0.2.0）
+dsh-dock 是 DeepSeek Harness（dsh）的插件，通过 dsh 插件命令安装：
 
-内置余额策略表覆盖：**DeepSeek**（官方余额接口）、**StepFun**、**Kimi Coding**（配额）、**OpenRouter**、**MiniMax**、**xAI/grok**；
-按 provider id（含别名）或 baseURL 家族自动匹配；`qwen-token-plan-*`（阿里云百炼）等无 API 余额接口的 Provider 显示"需登录"并提供控制台跳转链接；
-其余未知 Provider 显示"不支持"。自定义余额接口可在 Provider profile 里配 `balance.endpoint` 覆盖（沿用 `dsh-balance-panel` 约定）。
+```bash
+# 安装 npm 版
+dsh plugin --profile web add dsh-dock
 
-密钥全程留在 Host 进程内：只按 `apiKeyEnv` 解析凭证使用，不出 Host、不下发到浏览器。
-数据经回环 webServer 路由同源下发（Client `fetch` 拉取，不依赖 typert RPC，详见 [docs/session-notes.md](docs/session-notes.md)）。
+# 或安装本地开发版（克隆仓库后）
+dsh plugin --profile web add /path/to/dsh-dock
+```
 
-### 模型设置怎么生效（0.3.0）
+查看 / 卸载：
 
-面板保存 → Host 经 `settings.mutate` 写入官方配置（`llm-pi-ai.providers.<route>.models[].reasoningEfforts/input/dockTags`
-或 `llm-deepseek.models[]/thinking/reasoningEffort`）→ 适配器热加载（无需重启）→
-**会话窗口的模型选择器重新打开后，每个模型即可选择配置的强度档**（官方链路按 `model.reasoning.efforts` 展示）。
-输入类型中仅文本/图片为官方真实模态（请求路由生效）；视频/音频/文档为面板标注（持久化但不参与路由）。
+```bash
+dsh web --dump-config                     # 查看合成配置（确认 dsh-dock 已加载）
+dsh plugin --profile web remove dsh-dock  # 卸载
+```
 
-> **思考兼容兜底（0.3.0 修复）**：不在 pi-ai 内置目录里的模型（如部分第三方路由模型）启用思考后，
-> 适配器默认会把 system 改写成 `developer` 角色，百炼等 OpenAI 兼容端点直接 400。面板在启用思考档时
-> 自动写入 `compat.supportsDeveloperRole: false`；qwen/百炼家族再补 `thinkingFormat: qwen`，与官方目录内模型一致。
-> 保存时原条目上的未知字段（含用户自配 compat）原样保留，不会被面板清掉。
+也可以手动在 `cordis.patch.yml` 中声明插件后重启 dsh。
 
-### 图片理解代理（0.3.1）
+要求：DeepSeek Harness 环境（dsh），Node.js 18+。
 
-纯文本模型也能"看图"：在 设置 → 功能坞 → 模型设置 顶部（或弹层同页）启用**图片理解代理**并点选一个
-**视觉模型**（候选 = 模型目录中支持图片输入的全部模型，跨 Provider）后：
+## 使用方法
 
-- 发给**纯文本模型**的消息带图片时，自动先调用所选视觉模型识别，识别文本以 `[图片内容（由视觉模型 … 识别）：…]` 注入请求；
-- **多模态模型不受影响**，按官方链路原样自识别；
-- 识别失败自动降级（注入说明文本，不影响主请求）；同一张图 10 分钟识别缓存；
-- 配置存插件自有 `dsh-dock` 命名空间，保存即热生效。
+### 快速上手
 
-## 新增一个功能（两步）
+1. 启动 dsh：`npx @deepseek-ai/dsh web`
+2. 打开浏览器访问 dsh 的 web 界面
+3. 在**左侧边栏底部**找到 **「功能坞」** 按钮，点击弹出功能面板
+4. 面板左侧是导航：首页总揽 + 各功能模块；右侧是对应内容区
 
-1. 建 `features/<id>/`：
-   - `view.js(x)` 导出 `feature = { id, name, order, accent, description, css, View, HomeStat? }`
-     （纯客户端功能到这就够了）；
-   - 需要宿主逻辑的加 `host.js` 导出 `feature = { id, name, description, defaultEnabled, setup(ctx) → disposer }`；
-2. 在 `src/client.jsx` 的 `BUILTIN_FEATURES` import 一行；宿主功能再在 `index.js` 的 `FEATURES` import 一行；
-   改完跑 `node scripts/build-client.mjs`。
+### 启用 / 停用功能
 
-需要从 Host 拿数据的功能：在模块 `setup(ctx)` 里用 `ctx.get('webServer').register`
-注册同源路由（纯 JSON），视图 `fetch('/dsh-dock/<id>')` 拉取——密钥只进 Host，
-绝不下发浏览器。详见 [docs/session-notes.md](docs/session-notes.md) 8.3。
+每个功能有独立开关，两个入口：
 
-## 提取一个功能成独立包
+- **弹窗页脚**：进入某个功能页，页脚显示「已启用（点击停用）/ 已停用（点击启用）」
+- **设置页**：侧栏底部 → 设置 → 功能坞，每个模块卡片上有开关
 
-```sh
-node scripts/extract-feature.mjs tokenlog --out ../dsh-dock-tokenlog
-```
+停用某功能后，其菜单项、首页卡片、会话区小控件一并隐藏。
 
-生成独立包骨架（镜像本仓库布局，模块内相对导入不变）：宿主入口、独立客户端入口
-（**双形态**：装了 dsh-dock → `ctx.modules.import('dsh-dock')` 成功 → `dockBridge.register`
-注册进功能坞菜单；没装 → 自己的侧栏入口 + 全屏面板）、构建脚本、`cordis.patch.yml`、`package.json`。
-发布前裁剪依赖 → 构建 → 实测两种形态（含与功能坞共存时的菜单合并，独立入口应隐藏）。
+### 会话区随身小控件
 
-## 路线图（后面要干嘛）
+启用「模型余额」「用量记录」后，会话输入区工具行（模型选择器左侧）会出现两个小芯片：
 
-| 版本 | 内容 | 状态 |
-| --- | --- | --- |
-| **0.2.0** | 接入**模型余额**：策略表查询各 Provider 余额/配额；侧栏入口 + 功能弹层 | ✅ 已接入 |
-| **0.3.0** | 接入**模型设置**：官方目录链路集成，写回热生效；弹层窗口化 | ✅ 已接入 |
-| **0.4.0** | **模块化架构**（features/ 模块目录 + 客户端构建 + dockBridge 回装通道）+ 接入**用量记录** + **会话区随身小控件**（余额/用量 chips，模型选择器左侧，可单独开关） | ✅ 已接入（本版） |
-| **0.5.0** | 接入**任务动画**：任务进度动画、完成/卡住通知 | 纯 Client 功能模块；如需挂对话区，在模块内注册对应 slot（如 `conversation.composer.dock`） |
-| **0.6.0** | 开关状态**持久化**、Host↔Client 双侧注册表打通 | 状态写入持久化服务；Host 侧开关与 Client 面板同步；外部功能包的可选依赖注册（面板不在，功能照跑） |
+- **⛁ 会话用量**：显示当前会话的 Token 数与估算费用（10 秒自动刷新）
+- **余额**：显示当前选中模型的 Provider 账户余额（跟随模型切换实时更新）
 
-后续新增功能遵循同一模式：**模块目录 + 注册表一行 import**，即插即用。
+点击芯片直接跳转功能坞对应页。每个功能可在面板页脚或设置页单独设置「会话页显示 / 隐藏」。
 
-## 安装
+### 各功能使用
 
-开发期（link 模式）：
+**用量记录**
+1. 打开功能坞 → 用量记录
+2. 使用顶部筛选：时间范围（秒级）、会话、提供商、模型（与提供商联动）、状态、推理强度
+3. 查看 9 张 KPI 卡（调用次数 / Token / 输入 / 缓存命中 / 命中率 / 输出 / 金额 USD / 金额 CNY / 累计耗时）
+4. 「分组汇总」按 无 / 提供商 / 模型 / 状态 / 强度 维度切换
+5. 明细表 15 列可排序，100 行/页，点击「会话 ID」即筛选该会话；行右侧「详情」看单次调用信息
+6. 「CSV 导出」下载当前筛选结果
 
-```sh
-dsh plugin --profile web add dsh-dock   # npm 版安装
-# 或本地路径：dsh plugin --profile web add /path/to/dsh-dock
-```
+**模型余额**
+1. 打开功能坞 → 模型余额
+2. 列表展示全部已配置 Provider 的余额/配额状态（每 5 分钟自动刷新，可手动「刷新」）
 
-查看/卸载：
+**任务动画**
 
-```sh
-dsh web --dump-config                    # 查看合成层（含 dsh-dock）
-dsh plugin --profile web remove dsh-dock # 卸载
-```
+![任务动画设置页：8 种氛围模式 + 桌面伙伴大小控制](screenshots/dock-animation.png)
 
-### 从 feature-hub 迁移
+1. 打开功能坞 → 任务动画，两组开关完全独立、按需组合：
+   - **运行动画**：任务进行中才出现，8 种氛围模式任选（默认「流光细线」），**速度随任务吞吐自动加快**（Token 速率驱动）：
+     - 流光细线：顶部细线流光往返
+     - 呼吸光点：状态徽标圆点呼吸
+     - 轨道光环：细环绕圆点旋转
+     - 环屏巡航：一颗光点沿屏幕边缘巡航整圈
+     - 桌面伙伴：**CSS 3D 立体**的具象人物（眉眼鼻耳/头发/卫衣/坐姿腿脚）坐在四屏工位前，**流级实时同步任务阶段**——模型思考时仰头冒思考泡泡、正文输出/写代码时低头敲键盘（中屏代码滚动）、查资料时头部左右扫视侧屏；整卡可拖到屏幕任意位置（位置持久化），右下角手柄 / 面板滑块可缩放大小（85%~220%，自动保存）
+     - 代码雨：字符列沿屏幕缓落如数据流
+     - 星野：细碎星点飘移闪烁，带弯月与流星
+     - 极光：屏幕顶部柔光带缓慢呼吸流动
+   - **完成通知**：任务结束时右上角弹出通知卡片（标题 / 模型 / 耗时 / 回合步骤 / Token / 结果摘要 / 结束原因），可分别开关「完成 / 异常」通知、选择停留时长、开启浏览器系统通知（仅页面后台时推送）；**提示音** 6 种 WebAudio 合成音效可选（完成 / 异常各配一音，可单独试听）
+2. 任务结束动效自动消失，完成瞬间一缕流光掠过；功能坞面板打开时环境动效自动隐藏避免重叠
 
-本包是 feature-hub 原型的正式发布版，面板与功能几乎一致：
+![桌面伙伴：任务进行中实时同步阶段（思考/输出/查资料）](screenshots/dock-robot.png)
 
-```sh
-dsh plugin --profile web remove dsh-feature-hub
-dsh plugin --profile web add dsh-dock
-```
+3. **钉钉推送**（可选）：任务结束由宿主直发 markdown 消息到钉钉群机器人（浏览器关着也能推）——填入 Webhook 地址保存，「发送测试消息」验证连通；机器人安全设置选「自定义关键词」填「任务」或「dsh」；推送哪些事件跟随上方「完成 / 异常通知」开关
+4. 所有配置（动画开关 / 动画模式 / 桌面伙伴大小 / 通知各项 / 提示音 / 钉钉 Webhook）经宿主 settings 持久化，重启 dsh 后自动恢复
+
+**模型设置**
+1. 打开功能坞 → 模型设置
+2. 编辑各 Provider 的模型目录：输入类型（文本 / 图片）、思考强度档位
+3. 保存后写回官方配置，即时生效（无需重启）
 
-（两个插件共存亦可，只是面板重复；建议迁移后移除旧版。）
+**图片理解代理（visionproxy）**
+- 用于图片内容识别等场景，模型设置中勾选「图片」输入类型的模型即可走该通道
 
-## 开发与发布
+**心跳监视 / 主题信息**
+- 示例功能，展示纯 Client 功能模块的写法
 
-- **开发提交**：Gitea 开发仓库（本仓库）
-  `ssh://git@172.18.99.124:9022/wycto/dsh-dock.git`
-- **发版**：GitHub 仓库（`github.com/wycto/dsh-dock`，待建）打 tag 发 Release
-- **npm 发布**（无作用域名先到先得，已占用后归本账号所有）：
+### 常见问题
+
+- **插件会消耗 token 吗**：默认不会。用量记录/模型余额/任务动画/模型设置都是被动监听或本地查询，不调用 AI。唯一主动调 AI 的是「图片理解代理」（用视觉模型识图），它**默认关闭**，需你在模型设置里手动开启才生效；开启后每次识图按所选视觉模型计费。
+- **功能开关刷新后重置**：v0.5.0 起功能开关已持久化（浏览器本地存储），刷新/重启后保持。
+- **任务动画/通知不生效**：动画路由与配置持久化在宿主进程内，旧宿主需重启 `dsh web` 加载（面板页会提示「宿主进程是旧版本」）。
+- **用量记录空白**：确认 dsh 是较新版本且插件宿主已加载（查看启动日志含 `[dsh-dock] host half loaded`）；旧宿主进程需重启 dsh web 加载新路由。
+- **余额显示「需登录 / 无密钥」**：对应 Provider 未在 dsh 凭据中配置可查询余额的密钥，属正常状态提示。
+
+## 开发：新增一个功能模块
+
+每个功能是一个 `features/<id>/` 目录，由两部分组成：
 
-```sh
-cd dsh-dock
-npm login          # 首次：登录你的 npm 账号（wycto）
-scripts/publish.sh # 预览 → 登录检查 → 发布
+```
+features/<id>/
+  host.js        # 宿主半部：注册 RPC 路由 / 定时任务（纯 ESM，零构建）
+  view.js(x)     # 客户端视图：渲染面板内容（自带样式，CSS 类名带前缀隔离）
 ```
 
-> 若发布时报 `EPERM`（npm 缓存目录里有 root 属主文件的历史 bug）：
-> 修复一次 `sudo chown -R 501:20 ~/.npm`，或临时绕过
-> `CACHE_DIR=/tmp/dsh-dock-npm-cache ./scripts/publish.sh`。
+在视图模块导出功能描述符：
+
+```js
+export const feature = {
+  id: "my-feature",
+  name: "我的功能",
+  order: 160,              // 菜单排序（首页固定第一，数值越大越靠后）
+  accent: "#22c55e",       // 品牌色
+  description: "…",
+  css: "…",
+  View: MyView,            // 面板内容组件，收到 { ctx, feature, params }
+  HomeStat: MyStat,        // 可选：首页总揽卡片统计
+  Chip: MyChip,            // 可选：会话输入区小控件
+  Overlay: MyOverlay,      // 可选：功能全局浮层（功能启用即常驻整页挂载，如任务动效/通知）
+};
+```
 
-> 注：`package.json` 中 repository 指向 GitHub（发版仓库），Gitea 建好后
-> 建议把两个地址都确认一遍。
+外壳只做组装：宿主半部在 `index.js` 注册，客户端在外壳 `src/client.jsx` 装配。
+每个模块可整体拎出单独打包发布（`scripts/extract-feature.mjs` 生成独立包骨架，
+独立包装回后经 **dockBridge** 注册回功能坞菜单）。
 
-## License
+## 许可
 
-MIT
+[MIT](LICENSE)