termlnk-code-style

name

termlnk-code-style

description

Termlnk 仓库专属编码规范（叠加在 code-style-core/architecture/react/monorepo 四个通用 skill 之上的增量层）。编写、审查或重构 Termlnk 仓库（packages/*、packages-internal/*、apps/{desktop,web,mobile}）任何 .ts/.tsx 时使用，尤其涉及：菜单系统（下拉/右键/mergeMenu/triggerContextMenu/commandId）、Base46 主题与颜色（tm: 前缀类/base_30/base_16/IThemeService/xterm 配色/换肤透明度）、插件配置键（config.schema.ts/ConfigRepository 持久化 subKey）、tRPC 双进程契约（rpc-server/rpc-client 对称实现）、目录与包名契约（plugin.ts/@termlnk 包名/*-mobile 后缀）、mobile babel 限制时。新建插件包或 plugin.ts 必读。

Termlnk 专属代码规范

概述

Termlnk 遵循四个通用 skill 的全部规范（code-style-core / code-style-architecture / code-style-react / code-style-monorepo），本 skill 只记录 Termlnk 特有的增量约定。通用规则冲突时以通用 skill 为准，本 skill 的例外都已显式标注。

Termlnk 参数固定值

通用规范中的占位	Termlnk 取值
@<core>	@termlnk/core
@<scope>	@termlnk
infra 包	internal/shared（@termlnk/shared，eslint/vite/tsconfig/tailwind 预设）
Tailwind 前缀	tm:（冒号），cn() 来自 @termlnk/design
语义色 token	Base46（base_30 30 个 UI 色 + base_16 16 个语法色）
DI 桥接 re-export	@termlnk/design（useDependency / useObservable / useObservableRef）
命令系统	简化变体：只有 COMMAND 一种运行时类型，id 三段格式保留
License 头	PolyForm Noncommercial，全量 .ts/.tsx 强制
locale 语言集	zh-CN / en-US / ja-JP / ko-KR / zh-TW（5 语言齐全）

关键增量规则速查 (违反必改)

菜单系统 — 所有动作菜单走菜单系统 + 命令系统

• ❌ 禁止业务里手写 DropdownMenu + 内联 onSelect；唯一渲染层是 DesktopContextMenu（@termlnk/ui）
• 菜单项绑 commandId（必填，渲染层执行 item.commandId 非 id）
• schema 集中声明：mergeMenu({ '<包名>.context-menu.<scope>': {...} })
• 触发（右键/左键统一）：contextMenuService.triggerContextMenu(e.nativeEvent, MENU)
• 命令从服务读目标（focused/target service），不靠菜单参数；变长/数据驱动项才用 SELECTOR + selections$ + params
• 详见 references/04-menu.md

Base46 颜色 — 禁硬编码、禁 tm:dark: 切色

• 颜色只用语义类：tm:bg-one-bg / tm:text-light-grey / tm:border-line（前缀 tm: 冒号，下划线转连字符）
• ❌ 禁 bg-gray-800 / #1e222a；❌ 禁 tm:dark:bg-xxx（颜色随主题自动切换）
• 背景层级：black（页面）→ one_bg（卡片）→ one_bg2（hover）→ one_bg3（active）
• 新主题 base_30 必填 30 键、base_16 可 Partial；改终端配色改 base_30 语义色
• 业务只调 IThemeService.setTheme(theme)；移动端用语义 token 不用 tm: 类
• 详见 references/05-base46-theme.md

插件配置键 — 运行时 + 持久化共用一个 key

• 运行时字段 → IConfigService；持久化字段 → ConfigRepository.setField/getField（按 subKey），同一 IXxxConfig 接口声明
• 详见 references/02-plugin-config.md

双进程契约 — tRPC 对称实现

• 契约放 @termlnk/shared-* 等契约包；主进程 rpc-server/*-core 与渲染端 rpc-client 各 implements 同一接口
• ❌ 禁 *ClientService 后缀；流式用 trpcSubscriptionToObservable
• 详见 references/03-rpc-contract.md

包名与目录契约

• 共享包 @termlnk/<name>；mobile 私有插件 @termlnk/<name>-mobile（❌ mobile-<name> 前缀）
• 插件入口固定 plugin.ts；每插件必有 controllers/config.schema.ts
• 详见 references/01-structure.md

Mobile 已知限制

• mobile 的 service/repository/controller 受 babel 链 bug 影响须临时拆字段注入（工具链债，plugin 不受影响）——见 references/02-plugin-config.md §2.2

章节索引 — 按需打开

#	主题	文件	何时查阅
1	目录与包名契约	references/01-structure.md	新建插件包、放新文件时（必读）
2	插件配置键 + mobile 工具链	references/02-plugin-config.md	写 config.schema、持久化字段、mobile 代码时
3	tRPC 双进程契约	references/03-rpc-contract.md	新增跨进程服务、写 rpc-client 门面时
4	菜单系统	references/04-menu.md	写下拉/右键/工具栏菜单时（必读，禁手写 DropdownMenu）
5	Base46 主题系统	references/05-base46-theme.md	写带颜色的 UI、新建主题、改终端配色时（必读）