dsh-long-plugins 1.3.1

package/lib/md2docx.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Generic Markdown -> styled .docx converter with a page-number footer.
+
+Usage:
+  python3 md2docx.py <input.md> [output.docx]
+
+If output.docx is omitted, it defaults to <input-name>.docx next to the input.
+
+Renders headings (h1-h3), bold/italic inline, tables (pipe syntax),
+ordered/unordered lists, blockquotes, and horizontal rules. Adds a centered
+footer with an auto-updating PAGE field (updates when opened in Word or
+exported to PDF).
+
+Requires: python3 + python-docx (`pip install python-docx`).
+"""
+import re
+import sys
+import os
+
+from docx import Document
+from docx.shared import Pt, RGBColor
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.table import WD_TABLE_ALIGNMENT
+from docx.oxml.ns import qn
+from docx.oxml import OxmlElement
+
+
+def die(msg):
+    print(f"md2docx: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+if len(sys.argv) < 2:
+    die("usage: md2docx.py <input.md> [output.docx]")
+
+SRC = os.path.abspath(sys.argv[1])
+if not os.path.isfile(SRC):
+    die(f"input file not found: {SRC}")
+OUT = (
+    os.path.abspath(sys.argv[2])
+    if len(sys.argv) > 2
+    else os.path.splitext(SRC)[0] + ".docx"
+)
+
+with open(SRC, encoding="utf-8") as f:
+    lines = f.read().splitlines()
+
+
+def add_page_number(paragraph):
+    """Insert an auto-updating '第 N 页' page field into a footer paragraph."""
+    run = paragraph.add_run("第 ")
+    set_east_asia(run)
+    fld = OxmlElement("w:fldChar")
+    fld.set(qn("w:fldCharType"), "begin")
+    instr = OxmlElement("w:instrText")
+    instr.set(qn("xml:space"), "preserve")
+    instr.text = " PAGE "
+    sep = OxmlElement("w:fldChar")
+    sep.set(qn("w:fldCharType"), "separate")
+    t = OxmlElement("w:t")
+    t.text = "1"
+    end = OxmlElement("w:fldChar")
+    end.set(qn("w:fldCharType"), "end")
+    r = paragraph.add_run()
+    set_east_asia(r)
+    for el in (fld, instr, sep, t, end):
+        r._r.append(el)
+    run2 = paragraph.add_run(" 页")
+    set_east_asia(run2)
+
+
+doc = Document()
+doc.add_heading(os.path.splitext(os.path.basename(SRC))[0], level=0)
+
+
+# --- base styles ---
+normal = doc.styles["Normal"]
+normal.font.name = "Calibri"
+normal.font.size = Pt(10.5)
+normal._element.rPr.rFonts.set(qn("w:eastAsia"), "微软雅黑")
+
+
+def set_east_asia(run):
+    run.font.name = "Calibri"
+    r = run._element
+    rPr = r.get_or_add_rPr()
+    rf = rPr.find(qn("w:rFonts"))
+    if rf is None:
+        rf = OxmlElement("w:rFonts")
+        rPr.append(rf)
+    rf.set(qn("w:eastAsia"), "微软雅黑")
+
+
+def add_runs_with_bold(par, text):
+    """Add text to paragraph, honoring **bold** and *italic* markers."""
+    for tok in re.split(r"(\*\*.*?\*\*|\*.*?\*)", text):
+        if not tok:
+            continue
+        if tok.startswith("**") and tok.endswith("**") and len(tok) > 4:
+            r = par.add_run(tok[2:-2])
+            r.bold = True
+        elif tok.startswith("*") and tok.endswith("*") and len(tok) > 2:
+            r = par.add_run(tok[1:-1])
+            r.italic = True
+        else:
+            r = par.add_run(tok)
+        set_east_asia(r)
+
+
+def add_body_paragraph(text, style=None):
+    p = doc.add_paragraph(style=style)
+    add_runs_with_bold(p, text)
+    return p
+
+
+def flush_table():
+    global table_rows, in_table
+    if not table_rows:
+        in_table = False
+        return
+    ncols = max(len(r) for r in table_rows)
+    tbl = doc.add_table(rows=len(table_rows), cols=ncols)
+    tbl.style = "Light Grid Accent 1"
+    tbl.alignment = WD_TABLE_ALIGNMENT.CENTER
+    for ri, row in enumerate(table_rows):
+        for ci in range(ncols):
+            cell = tbl.cell(ri, ci)
+            cell.text = ""
+            cp = cell.paragraphs[0]
+            text = row[ci] if ci < len(row) else ""
+            add_runs_with_bold(cp, text)
+            if ri == 0:
+                for run in cp.runs:
+                    run.bold = True
+    tbl.autofit = True
+    table_rows = []
+    in_table = False
+
+
+table_rows = []
+in_table = False
+
+i = 0
+while i < len(lines):
+    stripped = lines[i].strip()
+    if not stripped:
+        i += 1
+        continue
+    if re.fullmatch(r"-{3,}", stripped):
+        flush_table()
+        doc.add_paragraph()
+        i += 1
+        continue
+    if in_table and "|" in stripped and re.fullmatch(r"\|?[\s:|-]+\|?", stripped):
+        i += 1
+        continue
+    if stripped.startswith("|"):
+        in_table = True
+        table_rows.append([c.strip() for c in stripped.strip("|").split("|")])
+        i += 1
+        continue
+    if in_table:
+        flush_table()
+    if stripped.startswith("### "):
+        h = doc.add_heading(level=3)
+        add_runs_with_bold(h, stripped[4:])
+        i += 1
+        continue
+    if stripped.startswith("## "):
+        h = doc.add_heading(level=2)
+        add_runs_with_bold(h, stripped[3:])
+        i += 1
+        continue
+    if stripped.startswith("# "):
+        h = doc.add_heading(level=1)
+        add_runs_with_bold(h, stripped[2:])
+        i += 1
+        continue
+    if stripped.startswith("> "):
+        p = doc.add_paragraph(style="Intense Quote")
+        add_runs_with_bold(p, stripped[2:] + " ")
+        i += 1
+        continue
+    m = re.match(r"^(\d+)\.\s+(.*)$", stripped)
+    if m:
+        p = doc.add_paragraph(style="List Number")
+        add_runs_with_bold(p, m.group(2))
+        i += 1
+        continue
+    if stripped.startswith("- "):
+        p = doc.add_paragraph(style="List Bullet")
+        add_runs_with_bold(p, stripped[2:])
+        i += 1
+        continue
+    p = doc.add_paragraph()
+    add_runs_with_bold(p, stripped)
+    i += 1
+
+if in_table:
+    flush_table()
+
+# --- footer with page number field ---
+footer = doc.sections[0].footer
+fp = footer.paragraphs[0]
+fp.alignment = WD_ALIGN_PARAGRAPH.CENTER
+add_page_number(fp)
+
+doc.save(OUT)
+print("Saved:", OUT)

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "dsh-long-plugins",
+  "version": "1.3.1",
+  "description": "Merged DSH web plugins: upload manager (drag-and-drop attach any file to the message), workspace output files, skill docs, account balance, Markdown-to-Word (md2docx), polished file preview, and an auto-repair install for DSH core patches (reverse-proxy WebSocket heartbeat, upgrade relink). ｜ 一个插件整合 DSH Web 的常用增强：上传管理（拖放上传：拖任意文件到会话框直接附加）、工作区「输出文件」面板、技能文档浏览、账户余额显示、Markdown 转 Word（md2docx）；并自带修复安装，自动重连 DSH 核心补丁（反代 WebSocket 心跳、升级重连）。",
+  "type": "module",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./client/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "lib/md2docx.py",
+    "client",
+    "!client/*.bak",
+    "cordis.patch.yml",
+    "dsh.plugin.json",
+    "skill/dsh-long-plugins-install/SKILL.md",
+    "skill/dsh-upgrade/SKILL.md",
+    "skill/dsh-common-plugins-install/SKILL.md",
+    "skill/dsh-web-win-service-install/SKILL.md",
+    "skill/dsh-web-start-panel-install/SKILL.md",
+    "patches/dsh-client-connection-heartbeat.sh"
+  ],
+  "dependencies": {
+    "mammoth": "^1.12.1",
+    "exceljs": "^4.4.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-theme",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-input-trigger",
+        "@deepseek-ai/dsh-client-ui-layout"
+      ],
+      "platform": "web"
+    }
+  }
+}

package/patches/dsh-client-connection-heartbeat.sh

@@ -0,0 +1,107 @@
+#!/bin/sh
+# dsh-client-connection-heartbeat.sh — 给 DSH 核心下行 WebSocket 加心跳补丁
+#
+# 作用：反代/中间设备会按只读超时关停长期沉默的上游 WebSocket。提问/审批窗口
+#       等待人类作答时 agent 循环被暂停、无帧流动，mux/host 流被切断后前端清空
+#       「待回答问题」→ 窗口消失，只能靠刷新重连恢复。
+# 修复：给 DSH 核心 dsh-client-connection 的下行 WebSocket 每 15s 只 ping 一次，
+#       保持下游流量，让反代下等待作答的问题窗口不再消失。只 ping、不做 pong 判定、
+#       不 terminate，避免后台/节流的手机端（pong 延迟）被误判为死连接而断开。
+#
+# 该补丁改的是 DSH 核心模块（不在本插件内）。装 dsh-long-plugins 时 install.sh 会
+# 调本脚本自动重打；DSH 升级会覆盖核心 → 需重跑本脚本（或跑插件升级流程）。
+#
+# 幂等：可重复执行，已打过会跳过。
+# 用法：sh dsh-client-connection-heartbeat.sh
+set -e
+echo "==> dsh-client-connection 心跳补丁"
+
+# 定位 DSH 核心里 dsh-client-connection 的 index.js
+# 优先用 npm root -g；找不到再探测常见全局路径。
+NPM_ROOT="$(npm root -g 2>/dev/null || true)"
+CANDIDATES=""
+[ -n "$NPM_ROOT" ] && CANDIDATES="$NPM_ROOT/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-client-connection/lib/index.js"
+CANDIDATES="$CANDIDATES
+/volume1/npm/global/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-client-connection/lib/index.js
+/usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-client-connection/lib/index.js
+$HOME/.dsh/../node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-client-connection/lib/index.js"
+
+IDX=""
+for c in $CANDIDATES; do
+  [ -f "$c" ] && IDX="$c" && break
+done
+if [ -z "$IDX" ]; then
+  echo "错误：找不到 dsh-client-connection/lib/index.js（核心未装或路径不同）" >&2
+  echo "  请确认 DSH 已安装，并把 $IDX 路径填入本脚本，或联系维护者。" >&2
+  exit 1
+fi
+echo "    目标: $IDX"
+
+# 幂等：已含心跳常量则跳过
+if grep -q 'WEBSOCKET_HEARTBEAT_MS' "$IDX"; then
+  echo "    已打过，跳过 ✓"
+  exit 0
+fi
+
+# 待替换的原始代码未在 -> 提示人工核对
+if ! grep -q 'var WebSocketDownlinks = class {' "$IDX"; then
+  echo "    警告：未找到 WebSocketDownlinks 类，可能 DSH 已改逻辑，请人工核对" >&2
+  exit 1
+fi
+
+cp "$IDX" "$IDX.bak-heartbeat-$(date +%Y%m%d-%H%M)"
+python3 - "$IDX" <<'PY'
+import sys
+p = sys.argv[1]
+T = "\t"
+with open(p, encoding="utf-8") as f:
+    s = f.read()
+
+def rep(old, new, label):
+    global s
+    if old not in s:
+        sys.stderr.write("    跳过(未找到): %s\n" % label); return
+    if s.count(old) > 1:
+        sys.stderr.write("    警告(出现%d次,跳过): %s\n" % (s.count(old), label)); return
+    s = s.replace(old, new, 1)
+    print("    已应用: %s" % label)
+
+CONST_COMMENT = ("/** Downlink heartbeat interval: keep the browser streams from idling out under\n"
+                 "* a reverse proxy, whose read timeout would drop a mux/host socket a paused\n"
+                 "* agent leaves silent. Must stay below the proxy's read timeout. */\n")
+rep("var WebSocketDownlinks = class {",
+    CONST_COMMENT + "const WEBSOCKET_HEARTBEAT_MS = 15_000;\nvar WebSocketDownlinks = class {",
+    "心跳常量")
+
+o_ctor = ("host API supplying the typed event streams. */\n" + T + "constructor(api) {\n" + T + T + "this.api = api;")
+p_ctor = ("host API supplying the typed event streams. */\n" + T + "constructor(api) {\n" + T + T + "this.api = api;\n" +
+          T + T + "// A reverse proxy cuts an upstream WebSocket that stays silent for its\n" +
+          T + T + "// read timeout; while a question or approval waits on the human the agent\n" +
+          T + T + "// loop is paused and no frames flow, so the mux/host streams drop and the\n" +
+          T + T + "// client clears its pending question. Pinging the clients every\n" +
+          T + T + "// WEBSOCKET_HEARTBEAT_MS keeps downstream traffic flowing so the proxy does\n" +
+          T + T + "// not idle the downlink out. The pings are only sent, never reaped: a\n" +
+          T + T + "// throttled/backgrounded mobile client may answer a pong late, and\n" +
+          T + T + "// terminating on a missed pong would reopen the very disconnect we are\n" +
+          T + T + "// preventing — dead sockets are cleaned by the ws close/error path anyway.\n" +
+          T + T + "this.heartbeat = setInterval(() => {\n" +
+          T + T + T + "for (const socket of this.server.clients) {\n" +
+          T + T + T + T + "if (socket.readyState === WebSocket.OPEN) socket.ping();\n" +
+          T + T + T + "}\n" +
+          T + T + "}, WEBSOCKET_HEARTBEAT_MS);\n" +
+          T + T + "this.heartbeat.unref?.();")
+rep(o_ctor, p_ctor, "心跳 interval")
+
+o_close = (T + "async close() {\n" + T + T + "for (const socket of this.server.clients) socket.terminate();")
+p_close = (T + "async close() {\n" + T + T + "clearInterval(this.heartbeat);\n" + T + T + "for (const socket of this.server.clients) socket.terminate();")
+rep(o_close, p_close, "close 清理心跳")
+
+with open(p, "w", encoding="utf-8") as f:
+    f.write(s)
+PY
+
+echo "    已应用 ✓"
+[ -f "$IDX" ] && node --check "$IDX" >/dev/null 2>&1 && echo "    语法检查 OK" || echo "    语法检查失败(请核对)" >&2
+echo
+echo "✅ 心跳补丁完成。请重启 dsh 并强刷浏览器。"
+echo "   （DSH 升级会覆盖核心，需重跑本脚本）"

package/skill/dsh-common-plugins-install/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: dsh-common-plugins-install
+description: 在一台已装好 DSH 的机器上自动安装"常用插件"清单（当前：dsh-market/dsh-market、jasonrale/dsh-archive-manager；可扩展）。优先用 `dsh plugin --profile web add <npm包名>`（一条命令装依赖+bundle+install）；未上 npm 的源码插件才用本地 file:链接。凡涉及远程 push 一律停下等用户确认。用户说"安装常用插件"、"装 dsh-market"、"装 dsh-archive-manager"、"新机器装插件清单"时调用。
+whenToUse: 用户要求安装/部署 dsh-market、dsh-archive-manager 等常用 DSH 插件，或在一台新机器上按清单安装常用插件时调用。
+---
+
+# DSH 常用插件安装
+
+作为部署助手，在一台**已装好 DSH** 的机器上安装"常用插件"清单。这些插件都是**自描述的 DSH 插件**（自带 `cordis.patch.yml` / `dsh.bundle.patch`），安装步骤统一；**清单可扩展**——往后加插件只需在"插件目录"加一行。
+
+> 本 skill 是**操作指引**，由你（agent）在目标机器上执行。真实 shell/文件权限来自该机器；凡**远程 push / 打 tag / 发 Release** 一律停下，等用户明确确认（硬性安全边界）。
+
+## 插件目录（当前收录）
+
+| 插件 | 包名 (bundle名) | 安装命令（npm 发布，推荐） | 简介 | 备注 |
+|---|---|---|---|---|
+| dsh-market | `dshmarket` | `dsh plugin --profile web add dshmarket` | DSH 可视化插件市场（浏览/搜索/一键安装社区插件） | npm 已发布；cordis id `dsh-market`；仓库 `dsh-market/dsh-market`（main）；本机已装 1.19.0（latest） |
+| dsh-archive-manager | `dsh-archive-manager` | `dsh plugin --profile web add dsh-archive-manager` | 归档会话管理器（重开/取消归档/硬删归档会话，带搜索与同步） | npm 已发布 v1.1.1；仓库 `jasonrale/dsh-archive-manager`（master）；cordis id `archive-manager`；引擎 node ≥22 |
+
+> **bundle 名 = 该包 `package.json` 的 `name`**。**npm 已发布的插件直接用 `dsh plugin --profile web add <包名>` 安装**——该命令会自动写入 `dependencies`、加入 `dsh.profile.bundles`、并跑 `pnpm install`（本机已实证）。仅当插件**未发布到 npm** 时，才用下方"源码插件"的 git clone + `file:` 方式。
+
+## 前置检查（先探测，再动手）
+
+执行前先探测环境，**不要假设本机路径**。缺了就让用户补：
+
+```
+dsh --version                      # 是否装了 DSH；没有则提示先按官方文档装 DSH
+echo "$DSH_HOME"                   # 未设则查 /volume1/dsh、$HOME/.dsh 常见位置
+ls -d <候选>/profiles/web          # 定位 profile 目录（一般 web）
+node --version                     # 需 >=22（--expose-internals 依赖；archive-manager 也要求 >=22）
+which node ; command -v node       # 找 node 真实路径；找不到让用户给
+```
+
+- **DSH_HOME**：默认 `$HOME/.dsh`（Windows）或 `/volume1/dsh`（NAS），以用户实际值为准。
+- **profile**：默认 `web`；用 `dsh --profile <p> --dump-config` 核对。
+
+## 目录约定（先确认，再动手）
+
+- 插件目录 = `<DSH_HOME>/plugins`（习惯上源码插件放这里；npm 插件由 pnpm 装进 profile 的 `node_modules`，两处不冲突）。
+- bin 目录 = `<DSH_HOME>/bin`（放 DSH 运行时脚本，缺失则创建）。
+- 用户工作/上传目录与本插件清单无关（这两个插件不是文件上传类），**无需**设置 `DSH_UPLOAD_DIR`。
+- 若未约定插件目录，默认用 `<DSH_HOME>/plugins`，并告知"以后所有插件都放这里"。
+
+## 安装步骤（统一机制）
+
+> **两种来源**：① npm 已发布的插件 → `dsh plugin --profile web add <包名>`（推荐）；② 未上 npm 的源码插件 → git clone + `file:` 链接（更新靠手动 `git pull`）。不用 `github:` 依赖（会失去本地 clone 目录、依赖解析更不稳）。
+
+### 路径 A —— npm 已发布的插件（一条命令）
+```sh
+dsh plugin --profile web add <包名>
+# 等效：npx @deepseek-ai/dsh plugin --profile web add <包名>
+```
+> 该命令自动完成：写入 `dependencies` → 加入 `dsh.profile.bundles` → `pnpm install`。装完用 `dsh --profile web --dump-config` 确认插件已插入。
+
+### 路径 B —— 源码插件（未发布到 npm）
+#### B1. 获取源码 → 放入 DSH 插件目录
+```sh
+mkdir -p "$DSH_HOME/plugins" "$DSH_HOME/bin"      # 确保存在，缺失即创建
+git clone https://github.com/<owner>/<repo>.git "$DSH_HOME/plugins/<包名>"
+# 已有则更新：
+git -C "$DSH_HOME/plugins/<包名>" pull --ff-only origin <默认分支>
+```
+> **Windows 下 clone github.com 超时/被墙**时，用 codeload tarball：
+> `Invoke-WebRequest https://codeload.github.com/<owner>/<repo>/tar.gz/refs/heads/<分支> -OutFile p.tgz` + `tar -xzf`，把解压后内层目录移动为 `$DSH_HOME/plugins/<包名>`。
+
+#### B2. 读 package.json，确定 bundle 名与依赖
+- `name` → bundle 名（加入 `dsh.profile.bundles` 与依赖 `file:` 引用名）
+- `dsh.client.platform` / `dsh.client.inject` → 前端是否注入、注入哪些
+- `dsh.bundle.patch`（多为 `./cordis.patch.yml`）→ 插件自带 insert，通常无需在 profile 写配置
+- `peerDependencies` → 多为 `@deepseek-ai/*`、`react`，DSH 宿主已提供，一般不必额外装
+
+#### B3. 注入依赖 + 加 bundle（file: 绝对路径，勿用相对路径）
+```sh
+# 在 profile 目录执行，<profile> 通常为 web
+node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));p.dependencies=p.dependencies||{};p.dependencies['<包名>']='file:'+'$DSH_HOME/plugins/<包名>';p.dsh=p.dsh||{};p.dsh.profile=p.dsh.profile||{};p.dsh.profile.bundles=p.dsh.profile.bundles||[];if(!p.dsh.profile.bundles.includes('<包名>'))p.dsh.profile.bundles.push('<包名>');fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\n')"
+```
+> 任何平台都要把 `<包名>` 加进 `dsh.profile.bundles`。
+
+#### B4. pnpm install
+```sh
+cd "$DSH_HOME/profiles/<profile>" && pnpm install
+```
+
+### 通用：写 cordis.patch.yml（通常不需要）
+插件自带 `cordis.patch.yml`（`dsh.bundle.patch`）会自动 insert 自身。**一般不需要在 profile 的 `cordis.patch.yml` 里加东西。** 仅当要覆盖插件默认配置（如 `priority`、`trustedHosts`、`skillsRoot`）时，才在 `<profile>/cordis.patch.yml` 追加 `- id: <cordis-id>` 的 config 覆盖条目。本清单两个插件都不需要。
+
+### 通用：启动（用户手动执行，agent 不自重启）
+```sh
+node --expose-internals --max-old-space-size=8192 <dsh/lib/bin.js> web --port 3080 &
+```
+> **`--expose-internals` 必须有**，否则插件相关路由 404。以目标机器现有启动方式为准；Windows 可参考本机 `<DSH_HOME>/bin/restart-dsh.cmd`（会停旧进程再带 `--expose-internals` 起新进程，会中断当前会话，由用户在独立终端跑）。
+
+## 验证清单（逐项）
+1. `dsh --profile <profile> --dump-config` 组合树里出现该插件（id + inject）。
+2. 设置面板 / 前端出现对应插件入口（market 有"市场"入口；archive-manager 有归档/会话入口）。
+3. 重启后强刷浏览器（Ctrl/Cmd+Shift+R）。
+4. 上传/预览/md2docx 等其它插件功能不受影响（若本机已装 dsh-long-plugins）。
+
+## 更新插件版本
+- **npm 插件**：`dsh plugin --profile web add <包名>@最新` 或按 npm 版本；之后重启。
+- **源码插件（file:）**：`file:` 目录依赖在 `pnpm install`（含 `--force`）下**不会自动重拷**到 profile 的 `node_modules`，需手动同步：
+```sh
+# 1) 更新源码
+git -C "$DSH_HOME/plugins/<包名>" pull --ff-only origin <分支>
+# 2) 删除 profile 里的陈旧副本，再重装（否则 bundle 仍指向旧拷贝）
+Remove-Item -Recurse -Force "$DSH_HOME/profiles/<profile>/node_modules/<包名>"
+cd "$DSH_HOME/profiles/<profile>" && pnpm install
+# 3) 重启 DSH web
+```
+> 否则会出现"版本显示旧 / 改动不生效"——因为运行的是 node_modules 里的**独立拷贝**，不是源码目录（Windows 上 pnpm 常回退为拷贝而非符号链接）。
+
+## 硬性安全边界（必须遵守）
+- **不主动 `git push` / 打 tag / 发 Release**；需要发版本时停下用 `ask_user_question` 等用户确认。
+- 所有写操作（改 package.json / cordis.patch.yml / 重启服务）先向用户说明将要改哪个文件、做什么，再执行。
+- 探测到 `DSH_HOME`/`node`/profile 目录缺失时**停下提示**，让用户补充，不硬猜。
+
+## 往清单里加新插件
+只需在"插件目录"表加一行（包名、是否上 npm、仓库 `owner/repo`、默认分支、简介）。**若已上 npm** 就填安装命令 `dsh plugin add <包名>`；**若未上 npm** 用路径 B（clone+file:）。若新插件是文件/上传类或需要 `trustedHosts`/`skillsRoot` 等配置，再在"写 cordis.patch.yml"给出对应覆盖项。
+
+## 常见坑速查
+| 症状 | 原因 | 解决 |
+|---|---|---|
+| 设置面板不出现插件 | 未加 bundle | 用 `dsh plugin add`（自动加）；或手动把 `<包名>` 加入 `dsh.profile.bundles` |
+| 插件路由 404 | 启动缺 `--expose-internals` | 启动命令加该 flag |
+| **npm 插件 version 显示旧 / 改动不生效** | 版本没更新 | `dsh plugin add <包名>@<目标版本>` 后重启；源码插件则删 `node_modules/<包名>` 重装 |
+| `file:` 源码插件改动不生效 | pnpm 不重拷副本 | 删 `node_modules/<包名>` 重装 + 重启 |
+| clone github.com 超时/被墙 | 网络不通 github.com（raw/codeload 常可达） | codeload tarball 解压后移动到插件目录 |
+| market 检查不到 `file:` 插件更新 | market 硬编码 `updateAvailable:false` | 手动 `git pull` 更新 |