贡献指南

August 16, 2026 · View on GitHub

感谢参与 @nacocx/dsh-ui-context-menu。本文件说明开发环境、代码结构、如何新增功能以及如何发布新版本。

环境准备

Node.js ^22.19.0 || >=24.0.0，包管理器用 pnpm（不要用 npm）。
安装依赖并跑一遍完整检查：

pnpm install
pnpm run check

check = typecheck + test + build + smoke，提交前必须全部通过（见仓库根目录 AGENTS.md）。

常用命令

命令	作用
`pnpm run typecheck`	TypeScript 类型检查
`pnpm run test`	jsdom 测试套件（覆盖每个分支与卸载行为）
`pnpm run build`	构建 `lib/`（Node 半体 + 浏览器闭包）
`pnpm run smoke`	对构建产物做最小加载冒烟验证
`pnpm run pack:check`	`pnpm pack --dry-run`，检查发布内容

架构概览

自包含浏览器闭包。 src/client/** 经 tsdown 打包成一个模块加载器闭包（lib/client.js），没有运行时 import；React 通过加载器的 shell 自有模块 require('react') 获取，并在构建配置里用 deps.neverBundle 保持外部化，绝不打包进 bundle。
手势策略链。 src/client/index.ts 的一个文档级捕获监听器按优先级分类指针表面：工作区行 → 会话行 → 文本框 → 指针下的选区 → 交互控件 → 空白处；每层先读 loadPolicyConfig()（src/client/config.ts，浏览器本地存储），开关关闭时该表面保持原生菜单。
声明式条目表。 src/client/policy.ts 的 openKindMenu 为每个表面维护一个 MenuEntry[] 表；所有宿主动作共用 hostRpc(method, payload)（同源 /api RPC 网关的 client-request 信封），所以新条目 = 一行表项 + 一行调用。
行身份解析。 工作区行：workspace.list 的稳定宿主顺序 + 标题唯一匹配；会话行：从行操作按钮的固定 aria-label 解析显示标题，经 session.list（projections.values.title → cwd 基名 → id 的显示回退）唯一匹配，无法唯一解析时点击该行自己的操作按钮回退到默认菜单，绝不误操作。
覆盖层与对话框。 src/client/menu.ts 提供单实例菜单、prompt/confirm 对话框与注入样式表；全部副作用（监听器、定时器、样式、打开的菜单/对话框）都经 ctx.effect() 注册并在卸载时移除，卸载行为有测试覆盖。
设置卡片。 src/client/settings.ts 通过公开的 slots/locale 服务（可选依赖）把配置卡片注册进设置 → 插件 → 可配置插件页；服务缺失时插件照常工作。

新增一个菜单条目

在 src/client/menu.ts 的 LABELS 中加文案键（zh 与 en 两套）。
在 src/client/policy.ts 的 openKindMenu 对应表面条目表里加一行 { id, label, danger?, disabled?, onSelect }。
需要宿主动作时调用 hostRpc('方法名', payload)；需要对话框时复用 openPromptDialog / openConfirmDialog。
若这是新的可开关区域：在 src/client/config.ts 的 PolicyConfig 加字段、在 settings.ts 的 ROW_KEYS 与字典中加开关行、在 src/client/index.ts 的策略链中加门控分支（关闭 = 保持原生菜单）。
补测试：tests/plugin.spec.ts（手势/菜单/对话框）与 tests/settings.spec.ts（配置与卡片）。

文档约定

默认语言为中文：README.md（中文）与 README.en.md（英文）镜像；本文件与 CONTRIBUTING.en.md 镜像。修改任一侧必须同步另一侧。

发布流程

pnpm run check 全绿。
在 package.json 中递增 version（遵循语义化版本）。
提交并打标签：

git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z

发布（prepublishOnly 自动跑 typecheck + test，prepare 自动构建 lib/，publishConfig.access 已设为 public）：

pnpm publish

用户更新：重新运行 dsh plugin --profile web add @nacocx/dsh-ui-context-menu。

环境准备

常用命令

架构概览

新增一个菜单条目

文档约定

发布流程

许可证