ide-plugins

DSP IDE 扩展 Monorepo（npm workspaces）：将原 YHFT-IDE 内置能力拆为可独立安装、可版本化的 VS Code 扩展，Publisher 统一为 **yhftide**。

简介

技术栈：TypeScript、VS Code Extension API、vscode-languageclient / vscode-languageserver（语言包）。
设计要点：
- dsp-core：工具路径解析、进程执行、离线索引/安装、dsp-toolchain 与 workspace/.basic 回退。
- 功能模块：调试、构建、工程、AI 等以独立扩展存在，通过 extensionDependencies 依赖 yhftide.dsp-core。
- dsp-suite：扩展包（Extension Pack），一键声明依赖上述扩展。
调试策略：默认双轨（gdb-dap + cppdbg），详见各包 package.json 与 docs。

仓库结构

ide-plugins/
├── package.json              # 根 workspaces、engines、package:all
├── tsconfig.base.json        # TypeScript 基配置
├── scripts/
│   └── build-local.ps1       # 本地：install → build → [package]
├── packages/
│   ├── dsp-core/             # 核心：profile、离线包、工具解析
│   ├── dsp-mod-debug/        # 调试模块
│   ├── dsp-mod-build/        # 构建模块
│   ├── dsp-mod-project/      # 工程管理模块
│   ├── dsp-mod-ai/           # AI 应用模块（占位/演进中）
│   ├── dsp-language/         # 语言服务、语法、片段
│   ├── dsp-suite/            # 扩展包（引用上述扩展）
│   └── */LICENSE             # 各包许可证（vsce 打包需要）
└── docs/                     # 架构、路线图、规范与样例

环境要求

项	要求	说明
Node.js	`>=18.17.1 <19`	与根 `package.json` 中 `engines` 一致；打包优先保证 Node 18 稳定。
npm	`>=9 <10`	Workspaces 与 lockfile 建议固定大版本。
VS Code	`^1.70.0`	各扩展 `engines.vscode` 下限；实际产品以你们定制 IDE 版本为准。

快速开始

使用 PowerShell 一键脚本（Windows）：

# 仅安装依赖并编译全部 workspace
powershell -ExecutionPolicy Bypass -File .\scripts\build-local.ps1

# 编译后打全量 VSIX（7 个包）
powershell -ExecutionPolicy Bypass -File .\scripts\build-local.ps1 -Package

常用命令

在仓库根目录执行：

命令	说明
`npm install`	安装根与各 workspace 依赖。
`npm run build`	对所有含 `build` 脚本的包执行 `tsc`（输出到各包 `dist/`）。
`npm run watch`	开发时监听编译（各包 `tsc -w`）。
`npm run clean`	清理各包 `dist`（若包定义了 `clean` 脚本）。
`npm run lint`	各包若配置了 `lint` 则执行。
`npm run package:all`	对每个含 `package` 脚本的 workspace 执行 `vsce package`（见下文）。

单个扩展打包（示例）：

cd packages/dsp-core
npm run package

生成的 .vsix 位于该包目录下，文件名一般为 <name>-<version>.vsix。

扩展包一览

目录	`package.json` name	扩展 ID（安装名）	角色
`dsp-core`	`dsp-core`	`yhftide.dsp-core`	核心：Profile、离线索引/安装、`resolveBasicPath`、工具解析
`dsp-mod-debug`	`dsp-mod-debug`	`yhftide.dsp-mod-debug`	调试：双轨启动、线程控制命令等
`dsp-mod-build`	`dsp-mod-build`	`yhftide.dsp-mod-build`	构建：脚本构建、单文件构建、输出过滤等
`dsp-mod-project`	`dsp-mod-project`	`yhftide.dsp-mod-project`	工程：打开文件夹等（持续迁移）
`dsp-mod-ai`	`dsp-mod-ai`	`yhftide.dsp-mod-ai`	AI：命令入口（持续迁移）
`dsp-language`	`dsp-language`	`yhftide.dsp-language`	语言：LSP、语法、片段、汇编大纲
`dsp-suite`	`dsp-suite`	`yhftide.dsp-suite`	扩展包：通过 `extensionPack` 聚合上述扩展

安装顺序建议：先装 **yhftide.dsp-core**，或直接安装 **yhftide.dsp-suite**（由市场/IDE 解析依赖）。

安装与使用

在 VS Code / 定制 IDE 中：扩展 → 从 VSIX 安装，选择对应 .vsix。
若使用 dsp-suite：安装 suite 后按提示安装/启用子扩展。
工具链：配置 dsp.core.toolchainPath，或使用 DSP: 安装离线工具包 安装到 globalStorage/dsp-toolchain；旧工程可继续使用工作区下的 .basic（见 docs/07）。

配置说明

部分键由 dsp-core 贡献，可在用户/工作区 settings.json 中设置：

键	说明
`dsp.install.mode`	`offline` / `hybrid` / `online`，默认离线优先。
`dsp.install.offlineIndexPath`	离线索引 `index.json` 路径；空则使用 `<workspace>/.dsp-packages/index.json`。
`dsp.core.toolchainPath`	工具链根目录绝对路径；空则自动：`globalStorage/dsp-toolchain` → `workspace/.basic`。

各功能模块另有独立配置（如 dsp.debug.*、dsp.build.*），见对应包 package.json → contributes.configuration。

离线工具链与打包

索引样例：docs/examples/offline-index.sample.json
制作与目录约定：docs/07-离线工具包制作规范.md（归档内目录需与 dsp-toolchain 下 m7004/、gdb-m7004/ 等约定一致）

打包说明（VSIX）

使用 **vsce@2.14.0**（根 devDependencies），与各包脚本中的 vsce package 一致。
各包脚本形态：vsce package --no-dependencies --allow-missing-repository
- **--no-dependencies**：避免 monorepo 工作区依赖被打进 VSIX 或触发异常路径。
- **--allow-missing-repository**：package.json 未填 repository 时不交互暂停。
各包根目录包含 **LICENSE**，满足 vsce 对许可证文件的检查，实现 npm run package:all 无人值守。

根目录 overrides.cheerio 用于在 Node 18 下避免拉取不兼容的 undici 传递依赖；若升级 vsce/Node，需重新验证打包。

故障排除

现象	处理建议
`vsce package` 报 `ReadableStream` / `undici`	使用 Node 18 + 当前 lockfile；勿随意去掉根 `overrides`。
`invalid relative path: ... .git`	保持 `--no-dependencies`；勿把 monorepo `node_modules` 链进扩展目录。
打包时多次 `[y/N]`	已通过 `LICENSE` + `--allow-missing-repository` 消除；若仍出现，检查是否用了全局其他版本 `vsce`。
工具找不到	检查 `dsp.core.toolchainPath`、是否执行离线安装、工作区是否存在兼容的 `.basic`。

文档索引

文档	内容
docs/00-插件化总结.md	插件化背景与总结（评审材料入口之一）
docs/01-可执行目录重构方案.md	目录与职责划分
docs/02-旧模块映射与迁移边界.md	旧仓库 → 新包映射
docs/03-路线图与模块规划图.md	路线图与模块关系
docs/04-后续实现路线（B阶段后）.md	B 阶段之后任务分解
docs/05-P1实施清单与API契约.md	P1 清单与 API 契约
docs/06-任务看板（当前进度）.md	当前进度看板
docs/07-离线工具包制作规范.md	离线包目录与索引规范
docs/examples/offline-index.sample.json	`index.json` 样例

版本与发布

Publisher：yhftide（各扩展 package.json）。
版本号：当前各包多为 0.1.0；发版时请按语义化版本分别提升各 packages/*/package.json 的 version，并保证 dsp-suite 与依赖扩展版本策略一致（扩展包不强制同版本，但团队宜约定）。
CI：当前以本地 build-local.ps1 / npm run build 为主；接入 CI 时建议固定 Node 18 与 npm ci。

许可证

各扩展包目录下的 LICENSE 为 MIT（Copyright yhftide）。若产品需变更为专有协议，请统一替换各包 LICENSE 并审查第三方依赖许可证。