ide-plugins

YHFT-IDE插件化扩展：将原 YHFT-IDE 内置能力拆为可独立安装、可版本化的 VS Code 扩展，Publisher 统一为 yhftide。

---

目录

• 简介
• 仓库结构
• 环境要求
• 快速开始
• 常用命令
• 扩展包一览
• 安装与使用
• 配置说明
• 离线工具链与打包
• 打包说明（VSIX）
• 故障排除
• 文档索引
• 版本与发布
• 许可证

---

简介

• 技术栈：TypeScript、VS Code Extension API、vscode-languageclient / vscode-languageserver（语言包）。
• 设计要点：
  • dsp-core：工具路径解析、进程执行、离线索引/安装、dsp-toolchain 与 workspace/.basic 回退。
  • 内部模块：调试、构建、工程、AI、语言等仍保持模块化源码结构，便于独立演进。
  • dsp-suite：统一对外交付的主扩展，内部聚合 core / project / build / debug / ai / language。
• 调试策略：默认双轨（gdb-dap + cppdbg），详见各包 package.json 与 docs。

---

目标插件分层

目标插件清单

插件	职责定位
dsp-core	公共能力内核，负责工具链解析、进程调用、安装策略与 profile 等基础设施能力。
dsp-mod-debug	调试模块，负责双轨调试、能力探测以及调试相关命令与流程编排。
dsp-mod-build	构建模块，负责编译流程、符号分析与反汇编辅助等构建能力。
dsp-mod-project	工程模块，负责工程入口、上下文管理与工程级协同能力。
dsp-mod-ai	AI 模块，承载 IDE 内 AI 相关能力与后续扩展入口。
dsp-language	语言服务模块，负责语言支持能力，并为后续完整 LSP 架构演进预留空间。
dsp-suite	聚合套件模块，作为统一安装入口，对外提供单插件交付形态。

旧模块到新模块映射

旧模块	新模块	调整说明
baseDebug/project-index	dsp-mod-debug + dsp-core	将调试业务逻辑与通用基础能力拆分，降低模块间耦合。
projectManage/project-index	dsp-mod-build + dsp-mod-project + dsp-core	将构建能力、工程管理能力与公共能力分层沉淀，便于独立演进。
ai-application/project-index	dsp-mod-ai	将 AI 相关能力独立封装，形成单独模块。
dsp-language	dsp-language	保持语言服务模块独立，后续逐步演进为完整 LSP 体系。

---

仓库结构

ide-plugins/
├── package.json              # 根 workspaces、engines、package:all
├── tsconfig.base.json        # TypeScript 基配置
├── scripts/
│   ├── prepare-local-vsix.ps1   # 本地：增量构建 / 增量打包 VSIX
│   ├── install-local-vsix.ps1   # 本地：安装 / 卸载 VSIX 到目标 IDE
│   └── dev-update-local-vsix.ps1# 本地：一条命令完成增量打包 + 增量安装
├── 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\prepare-local-vsix.ps1

# 默认只打包 dsp-suite；如需子模块请显式指定 -Targets
powershell -ExecutionPolicy Bypass -File .\scripts\prepare-local-vsix.ps1 -Package -Targets dsp-suite

# 安装当前最新的 dsp-suite VSIX 到默认 VS Code
powershell -ExecutionPolicy Bypass -File .\scripts\install-local-vsix.ps1

# 从默认 VS Code 一键卸载整套扩展
powershell -ExecutionPolicy Bypass -File .\scripts\install-local-vsix.ps1 -Uninstall

# 开发阶段推荐使用：增量打包 + 增量安装 dsp-suite
powershell -ExecutionPolicy Bypass -File .\scripts\dev-update-local-vsix.ps1

---

常用命令

在仓库根目录执行：

命令	说明
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	主扩展：对外唯一交付入口，内部聚合上述模块

用户侧安装建议：直接安装 yhftide.dsp-suite。

---

安装与使用

1. 先执行 .\scripts\prepare-local-vsix.ps1 -Package -Targets dsp-suite 生成 dsp-suite.vsix。
2. 开发环境推荐执行 .\scripts\install-local-vsix.ps1 或 .\scripts\dev-update-local-vsix.ps1，默认只处理 dsp-suite。
3. 若手工安装 VSIX：在 VS Code / 定制 IDE 中选择“从 VSIX 安装”，安装 dsp-suite 即可。
4. 如需单独调试某个内部模块，可显式传入 -Targets dsp-core,dsp-mod-project 等参数。
5. 工具链：配置 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；发版时以 dsp-suite 为用户交付主版本，内部模块可根据需要保持同步版本策略。
• CI：当前以本地 prepare-local-vsix.ps1 / npm run build 为主；接入 CI 时建议固定 Node 18 与 npm ci。

---

许可证

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

开发脚本速查（增量）

开发阶段推荐默认使用增量脚本，避免每次全量打包、全量安装所有插件。

# 一条命令完成增量打包 + 增量安装（默认只处理 dsp-suite）
powershell -ExecutionPolicy Bypass -File .\scripts\dev-update-local-vsix.ps1

# 只处理指定内部模块
powershell -ExecutionPolicy Bypass -File .\scripts\dev-update-local-vsix.ps1 -Targets dsp-core,dsp-mod-project

# 全量重打包 + 全量重装
powershell -ExecutionPolicy Bypass -File .\scripts\dev-update-local-vsix.ps1 -All

相关脚本说明：

• scripts\prepare-local-vsix.ps1 默认增量构建；传入 -Package 时增量打包 VSIX。dsp-suite 会自动走单插件聚合打包流程；传入 -All 时全量处理。
• scripts\install-local-vsix.ps1 默认增量安装 dsp-suite；只安装新生成或更新过的 VSIX；传入 -Targets 可安装指定内部模块；传入 -All 时全量安装。
• scripts\dev-update-local-vsix.ps1 一条命令完成“增量打包 + 增量安装”，默认只更新 dsp-suite。