生花笔 (shenghuabi)

基于 VS Code 源码二次开发的 Windows / Linux 桌面写作与知识管理工具：脑图、知识库、RAG 检索、本地模型、工作流编排。

一个发行版 = 打过补丁的 VS Code 源码 + 一个内置扩展，本仓库只包含后者以及驱动前者的构建脚本。

发行版（Electron 应用）
├─ VS Code 源码            lib/vscode（构建时从官方 tag 拉取，脚本打补丁，不入库）
└─ 内置扩展 shenghuabi     本仓库 src/ → dist/ → resources/app/extensions/shenghuabi
   ├─ 扩展宿主进程（Node）  服务层 / tRPC / 知识库 / 工作流 / 本地模型
   ├─ webview 渲染层        webview/main（Angular 21 + React 19 混合）
   └─ 子进程 / worker       embedding、rerank、OCR（onnxruntime-node）、llama.cpp

四条进程边界：

1. Electron main：源码里注册了自定义 ShengHuabi channel 与 shb: scheme，用于主进程文件读取桥接和 webview 资源策略。
2. 扩展宿主：src/index.ts 激活，用 static-injector（Angular DI 的独立版本）搭根容器，所有服务靠 token 注入。
3. webview：Angular standalone 组件；脑图 / 手绘用 React 组件（@xyflow/react、excalidraw）通过 custom elements 挂载，两套渲染体系在同一页面共存。
4. 推理子进程：tinypool worker 跑本地模型，与扩展宿主隔离；llama.cpp 由 llama-swap 以独立进程管理。

# Node 22.22.1（见 .nvmrc）、pnpm 11.x、Python 3.11（native 模块编译）
# Windows 另需 Visual Studio 2022 + MSVC；Linux 需 gcc / make / dpkg-dev
pnpm i                       # workspace 包含 src 与 webview/main
pnpm run build:contributes   # 生成 package.json 的 contributes 段
pnpm run watch               # esbuild watch：扩展宿主 + 3 个 worker
cd webview/main && pnpm start # Angular watch

VS Code 里 F5 → Run Extension（.vscode/launch.json 已带 --enable-proposed-api wszgrcy.shenghuabi，fixture/ 作为测试工作区）。 另有 端口开发监听 配置，attach 到 5870 调试宿主进程。

dev.env 里的 PUBLISH_VERSION 会被 define 进构建产物，作为运行期版本号。

只改扩展层不需要 VS Code 源码；只有要改源码行为（§4）时才需要 lib/vscode。

没有维护 fork 分支。 每次构建从 microsoft/vscode 拉指定 tag，然后重放一份声明式补丁清单：

// script/change-vscode/index.ts
{
  path: 'src/vs/workbench/api/common/extHostLanguageModelTools.ts',
  list: [
    {
      query: `VariableDeclaration:has(>Identifier[value=dto])>ObjectLiteralExpression>SyntaxList::children(-1)`,
      replace: `,tags: definition.tags,`,
      description: '增加tag',
    },
  ],
}

• 执行器是 @code-recycle/cli，query 是 CSS 选择器风格的 AST / token 查询（TS 文件走 TS AST，JSON 走 jsonc-parser），支持 replace / insertBefore / insertAfter / delete / multi / offset，{{''|ctxValue}} 可取原节点内容。
• 因为按语法结构定位而不是按行号打 patch，官方代码上下移动行不会失效，只有结构真变了才需要修。
• build-common-package.ts 的顺序：git reset --hard <VSCODE_VERSION> + git clean -f → 移除 Copilot 扩展 → code-recycle 打补丁 → 清理未使用 import → git commit → npm i → gulp 构建。
• 所以升级 VS Code = 改一个 tag + 修少量失效 query，不需要 rebase。

补丁按用途分类（doc/vscode修改记录.md 有逐条记录）：

其中 extHostLanguageModelTools.ts 的 tags 透传修复已作为 PR 提交官方并随 1.126 发布，本地补丁与官方实现一致。

自有子包以 npm 依赖形式引入：@shenghuabi/knowledge（qdrant、file-parser、worker）、@shenghuabi/workflow（引擎 + NodeRunnerBase）、@shenghuabi/llama、@shenghuabi/python-addon（TTS）、@shenghuabi/openai，源码在 shb-knowledge / shb-lib 仓库。

Angular 21 standalone + Angular Material。

构建：pnpm --filter main-webview build（ng build，脚本里已放宽堆内存），产物由主构建拷贝进 dist/。

script/build.ts（pnpm run build / watch）用 esbuild 输出 ESM：

• 入口：src/index.ts + 三个 worker（ocr text2vec reranker，来自 @shenghuabi/knowledge/worker）
• banner 注入 createRequire shim，让 ESM 扩展能 require 原生模块
• swc 插件做转译，importRequirePlugin 处理 vscode 外部依赖
• PROD_ENV / PUBLISH_VERSION / navigator 等通过 define 内联

pnpm run move:extension 调用 script/build-extension.ts：并行执行扩展的 build:prod 与 webview 的 ng build，完成后删除 dist/**/*.map 与 dist/node_modules/**/*.ts（保留 @types/node）。Sentry sourcemap 上传逻辑保留在 updateSourceMap() 里、由 --capture 开关控制，目前注释未启用。

完整发行版：

# 1) 拉官方源码（CI 里 ref = VSCODE_VERSION）
git clone https://github.com/microsoft/vscode lib/vscode && git -C lib/vscode checkout 1.122.0

# 2) 打补丁 + min 构建（win32 走 build:common:win32，linux 走 build:linux）
pnpm run build:common-package

# 3) 构建扩展并拷进产物目录
pnpm run move:extension

# 4) 出安装包（这两个 gulp 任务由 script/change-vscode/index.ts 注入到 lib/vscode/package.json，官方没有）
cd lib/vscode
npm run build:user:win32-x64        # → .build/win32-x64/*.exe
npm run package:linux:deb           # → .build/linux-x64/*.deb

调试用：pnpm run copytovscode 把 dist/ 拷进 lib/vscode/extensions/shenghuabi，配合从源码启动的 VS Code 使用。

插件就是普通 VS Code 扩展，通过 SDK 注册：

import { shbPluginRegister, createConfig } from '@shenghuabi/sdk';

export function activate(context: vscode.ExtensionContext) {
  shbPluginRegister(context, {
    providers: { root: [{ provide: SomeToken, useClass: MyImpl }] },
    workflow: { node: [{ client, runner, config }] },
    tts: {
      /* ... */
    },
  });
}

• manifest 用 valibot 定义并校验（src/service/plugin/define.ts）：providers（root / knowledge 两组 DI 覆盖，带 priority）、workflow.node（自定义节点：client 渲染 + runner 执行 + config 定义）、workflow.context、tts。
• 配置项用 createConfig(valibotSchema, prefix) 转 JSON Schema 写进插件 package.json，配置界面由表单方案自动渲染。
• 发布：pnpm run build:plugin-sdk / pnpm run publish:plugin-sdk。

package.json 的 contributes 段由 script/metadata/contributes.ts 生成（pnpm run build:contributes）：TS 里以数组声明 command / title / icon / category / display.menus，避免多人协作时手改大 JSON 冲突。菜单位置类型在 MenuType 里穷举（editor/title、explorer/context、view/item/context 等）。

src/service/server/server.service.ts：Fastify + fastify-sse-v2。

• POST /workflow/stream：body 由 valibot schema 转 JSON Schema 做校验，工作流输出以 SSE 流式返回，客户端断连即 AbortController 中止执行。
• 开关与端口在应用配置里，默认不启用。

pnpm test          # @vscode/test-cli，配置见 .vscode-test.mjs
pnpm run coverage  # c8，配置见 .c8rc.json

.vscode-test.mjs 指定下载 VS Code 版本、--enable-proposed-api、测试工作区 test/fixture/workspace，用例编译到 test-dist/test/**/*.spec.js。测试按 knowledge / mind / workflow / config / util 分目录。

.github/workflows/windows-builder.yml、linux-builder.yml：

1. pnpm i（Node 取 .nvmrc，pnpm 11.5.0）
2. check-version：git ls-remote 比较 package.json 版本与已有 tag，相同则跳过构建
3. checkout microsoft/vscode@VSCODE_VERSION 到 lib/vscode
4. build:common-package → move:extension → 在 lib/vscode 内跑 user 安装包任务
5. softprops/action-gh-release 发布 .build/**/*.{exe,deb,tar.gz}，tag = 版本号
6. 通知版本管理服务，客户端自动更新

发版只需要改 package.json 的 version 并推 master。

• 必须与 VS Code 版本对齐。升级流程：改 workflow 里的 VSCODE_VERSION 与 package.json 版本 → 跑 build:common-package → 修 script/change-vscode/index.ts 中失效的 query。
• lib/vscode、lib/VSCode-*、dist、test-dist 均不入库，首次构建耗时主要在 VS Code 依赖安装与 min 构建。
• 依赖 enabledApiProposals（chat provider、text search provider、language model tools 等），本地运行需 --enable-proposed-api。
• Windows 构建需要 MSVC 与 Python：onnxruntime-node、sharp、@napi-rs/canvas、@shenghuabi/python-addon 都要编译。
• pnpm-workspace.yaml 里对 onnxruntime-node 做了版本 override，避免多版本共存导致推理崩溃。