admin
5ad755116e
1) dsh-server-docs/ 从工作区（原 E:\...\aliyun-dsh-server\dsh-server-docs）**整体并入本仓**，
保留目录名 ⇒ 仓库内 dsh-server-docs/... 的相对引用天然继续有效；旧目录（含其 .git）已归档到
工作区 _中间产物_待清理/，未随本提交带入。
2) .gitattributes：新增 `dsh-server-docs/** -text` —— 原文档库是 `* -text` + autocrlf=false，
必须保持纯 LF，否则会被本仓的 CRLF 规则翻掉。
3) 活引用里的绝对路径已全部改到新位置（docs 的 INDEX / README / scripts / skills + 用户级 skills
+ ~/.workbuddy/settings.json 的 hooks）；历史档案（04-调整方案/、archive/）按「只增不改」未动。
⚠️ hooks 路径改动需「完全重启会话」才生效（配置是会话启动快照）。
4) 交接单/T08：新增 §16「生产整体切换执行记录」（形态 / 落地动作 / **4 个只有真上线才暴露的真 bug** /
验收证据 / 回滚命令 / 残留项）；台账 T08 行 → 已完成并归档；03-路线图 §二 登记 T08 收尾项。
5) 统一称谓：**「本机」只指跑 WorkBuddy 的开发机**，47 / 106 一律写「远程服务器」。
72 lines
5.7 KiB
Markdown
72 lines
5.7 KiB
Markdown
# 38b · 术语统一「业务插件」→「功能插件」（含 0.2.1 与脚本加固）
|
||
|
||
- 日期：2026-09-11
|
||
- 触发：用户要求「将所有业务插件字段 改为 功能插件」
|
||
- 状态：**✅ 已实施（`99de8c5` + `79d9aed`）并验证**
|
||
|
||
> **TL;DR**｜**结论**：「业务插件」统一改名 **功能插件**（字段 / 文案 / 文档），含 v0.2.1 与脚本加固。
|
||
> **关键**：顺带确认：**亮/暗切换与多语言都是 dsh 官方能力**（插件用 `--dsw-*` token + 官方 locale 自动跟随）。
|
||
> **状态**：✅ 已实施并验证
|
||
|
||
## 一、范围界定（重要）
|
||
|
||
**只改显示术语 / 文案 / 注释；不动代码标识符。**
|
||
|
||
| 已改 | 未改（刻意） |
|
||
|---|---|
|
||
| 门户页面文案、client bundle 文案（section label / 空态 / 确认框）、src 注释、运维脚本注释、全部文档（含档案正文）、技能 | 表名 `business_plugins`、包名 `@dsh-local/business-plugins`、section id `business-plugins`、API 路径 `/api/plugins/{business,mine}`、文件名 `business-plugins.ts` / `ensure-biz-plugins.cjs`、目录 `poc/business-plugins/` |
|
||
|
||
**理由**：标识符改名需 DB 迁移 + 全量重铺 profile + 改 API 与前端调用，**用户可见收益为零**，纯风险。若确需，可另立档案。
|
||
|
||
## 二、替换明细
|
||
|
||
- **中文：31 个文件 / 87 处**；**英文侧补 3 处**（`Business plugins` → `Feature plugins`、`Apply business-plugin changes` → `feature-plugin`）。
|
||
- 覆盖：`portal.html`(5) · client bundle 文案(4，含 `section.label` 与 `empty`) · `src` 注释(10) · 运维脚本(3) · 文档（root 级 + `04-调整方案/` 01–37 + `06-工作台UI规范` + `INDEX` + `README` + `skills`）。
|
||
- **档案重命名 3 个**（INDEX / 状态备注 引用同步）：
|
||
- `34-业务插件启用探活与逐插件隔离.md` → `34-功能插件启用探活与逐插件隔离.md`
|
||
- `36-业务插件分区铺给普通用户.md` → `36-功能插件分区铺给普通用户.md`
|
||
- `37-业务插件分区v0.2官方token与i18n.md` → `37-功能插件分区v0.2官方token与i18n.md`
|
||
|
||
**踩坑**：首轮扫描把 `lib/` 放进 `SKIP_DIR_NAMES`（本意跳过构建产物）→ **client bundle 的文案被漏掉**，而那正是最显眼的 section label。已补做（`lib/client.js` 4 处 + `lib/index.js` 1 处）。
|
||
|
||
## 三、顺带修复
|
||
|
||
### A. client bundle v0.2.1（仅文案变更）
|
||
|
||
### B. `ensure-biz-plugins.cjs` 两处缺陷
|
||
|
||
1. **`ARTIFACT` 自动取最新版**：原为硬编码版本号（每次升版都要改脚本）；且中途一版把正则转义写坏成 `\\d`（JS 里是"反斜杠+d"，永远匹配不到，只能靠硬编码兜底）。→ 改为**无正则实现**（`PREFIX` 前后缀 + 语义化版本比较），取产物目录里版本最大的包。
|
||
2. **增加版本感知**：原实现只看 `bundles` 成员 → 已装用户永远"跳过"，**升级不会被应用**。→ 现在会比较 `file:` 依赖 basename 是否等于目标产物名，落后则重新 `pnpm add`。这一条让「丢新包 → 跑一次脚本」成为完整的升级流程。
|
||
|
||
### C. `.gitignore` 防复发
|
||
|
||
`99de8c5` 提交时 `git add src` **误卷了两个未跟踪的 `.bak-*` 备份**（正是项目里反复警告的坑）。→ `git rm --cached` 撤出 + `.gitignore` 增加 `*.bak-*`（`79d9aed`）。
|
||
> **遗留**：仓库里还有 **5 个更早被跟踪的 `.bak-*`**（`src/config.ts`、`src/supervisor/{orchestrator,spawn}.ts`、`src/web/server.ts`、`web/login.html`）—— 属历史遗留，未擅自处理，待确认是否一并撤出跟踪。
|
||
|
||
## 四、验证
|
||
|
||
| 检查项 | 结果 |
|
||
|---|---|
|
||
| 两侧依赖 | ✅ 均指向 `business-plugins-0.2.1.tgz`；ws 内包就位；旧 0.2.0 已清 |
|
||
| 已装版本 | ✅ guest `node_modules/@dsh-local/business-plugins` = **0.2.1** |
|
||
| 脚本幂等 | ✅ 再跑输出「已是 business-plugins-0.2.1.tgz → 跳过」 |
|
||
| **UI 实拍** | ✅ headless Chrome → guest 设置面板，导航项显示「**功能插件**」 |
|
||
| 残留检查 | ✅ 源码/文档中已无「业务插件」 |
|
||
|
||
> **附带发现**：dsh 官方「通用设置」里本来就有 **语言（中文/English）** 与 **外观（浅色 / 深色 / 跟随系统）** —— 这印证了档案 37b 的结论：**亮/暗切换与多语言都是官方能力**，我们的插件用 `--dsw-*` token + 官方 locale 自动跟随，无需自行实现。
|
||
|
||
## 五、后续
|
||
|
||
### 已决策（2026-09-11，用户「按建议处理」）
|
||
|
||
1. **✅ 5 个历史 `.bak-*` 已撤出跟踪**（`6c3fea0`）：`src/config.ts` / `src/supervisor/{orchestrator,spawn}.ts` / `src/web/server.ts` / `web/login.html` 的 `.bak-*`。
|
||
**理由**：与 git 自身历史完全重复，却真实带来「`git add <目录>` 把同目录未跟踪备份一并暂存」的风险（本档案已踩一次）。`.gitignore` 的忽略规则不影响已跟踪文件，故必须显式 `git rm --cached`。**文件保留在磁盘**，工作区现已完全干净（`git status` 无输出）。
|
||
2. **✅ 标识符不改**（维持 §一 的决定）：表名 `business_plugins`、包名 `@dsh-local/business-plugins`、section id `business-plugins`、API 路径 `/api/plugins/{business,mine}`、文件名与目录名一律保持。
|
||
**理由**：改名需要 DB 迁移 + 全量重铺 profile + 同步改 API 与前端调用，**用户可见收益为零**，纯风险。术语层（文案/注释/文档）已统一为「功能插件」，内外称呼差异可接受。
|
||
|
||
### 仍待办
|
||
|
||
- admin 侧事故可见性（`audit` 目前只有写没有读，需加读取方法才能在门户显示「N 个用户启用失败」）
|
||
- 重启前 `dump-config` 预检（可 0 重启拦住配置类错误）
|
||
- 批量上限保护（单批 >5 个插件时只回滚不清洗，避免重启十几次）
|