Docs / 开发

子模块与源码地图

说明 Git submodule 与 monorepo workspace 的分工，以及修改或阅读某项功能时应该从哪里开始。

4 个 Git submodule

下面 4 个路径指向外部仓库。正常 clone 时可用 git clone --recurse-submodules 一并取得。

Path	Repository	职责
`Vyline/packages/protocol`	tqmane/vyline-api	LINE protocol, login, E2EE, RPC, domain facade
`Vyline/packages/plugin`	tqmane/vyline-plugin	plugin SDK / examples / permission model
`Vyline/packages/themes`	tqmane/vyline-theme	VyTheme 类型与 preset
`tools`	tqmane/vyline-search	Desktop LINE version 跟踪、unpack、xref、decompile 辅助

submodule 与 workspace 不是同一个概念

Vyline/packages/ 下并非全部都是 submodule。主 monorepo 还管理 line-types（vendored Thrift 定义）、types / loose-types、cli / vyl / create-plugin、ios-backup 等 workspace package。“4 个 submodule”只计算外部仓库。

Protocol

查 LINE 通信规格时，这里是中心。公开 API 从 src/index.ts 开始，功能到调查线索的地图是 src/modules.map.ts，RPC 对应表是 src/dictionary/rpcMap.ts。

Protocol 内部	作用
`stack/`	Thrift RPC、Talk/Login 等低层通信
`src/login/`	QR/Email/Token、Desktop transport patch、E2EE identity
`src/domain/`	面向 Backend 的 Profile/Contacts/Chat/Talk facade
`src/dictionary/rpcMap.ts`	Desktop evidence → path → stack/domain/backend 对应
`src/modules.map.ts`	按功能整理相关 source 与 Desktop 搜索提示
`src/updater/` / `src/desktop/`	Desktop profile、version/header 更新跟踪

Backend 以 workspace dependency 的形式使用 @vyline/protocol。单独的 Protocol checkout 不包含 @vyline/line-types/@vyline/loose-types 等同级 workspace dependency，因此通常从整个 monorepo 开发。

Plugin

submodule 保存 SDK 与 examples，主仓库 Backend 保存 runtime。@vyline/plugin-sdk 提供 definePlugin、manifest、permission，以及 context/event 类型。

Vyline/packages/plugin (submodule)
  └─ sdk: public contract / examples
          ↓ workspace import
Vyline/backend/src/line/pluginManager.ts
  ├─ discover / enabled state
  └─ pluginRuntime.ts
       ├─ activate / deactivate
       ├─ permission-aware context
       └─ handler isolation

permission 字符串存在，并不代表 runtime 已实现所有 capability。要同时检查 SDK 类型与 Backend runtime 实际暴露的 context。

Themes

themes submodule 提供 THEME_PRESETS 与 VyTheme 类型。Theme 不只是 accent color，还包含 surface/sidebar/message/radius/chat background/pattern 等整套 token；Frontend 按 theme contract 使用，而不是把某个 preset 硬编码进界面。

Tools

Desktop LINE 更新后，用这些工具确认 Protocol 的前提是否仍成立。包括 version check/update、Themida unpack、string/xref 搜索、Ghidra decompile 辅助。它们是决定实现改动时使用的研究工具，不是打包进 Vyline production server 的 runtime dependency。

root script	用途
`bun run vyline:check`	比较 installed/running/latest version
`bun run vyline:update`	更新 Desktop LINE
`bun run vyline:unpack`	unpack 指定 LINE.exe
`bun run vyline:find-native -- <name>`	沿 string/xref/decompile 路径定位 native 实现
`bun run vyline:delta`	利用 Protocol feature map 缩小更新差异范围

决定修改哪个仓库

改动	提交到的 repository	主仓库需要做什么
LINE RPC/E2EE/login	`tqmane/vyline-api`	更新 submodule pointer + integration test
Plugin SDK	`tqmane/vyline-plugin`	确认 Backend runtime 兼容 + 更新 pointer
Theme preset/type	`tqmane/vyline-theme`	Frontend render 验证 + 更新 pointer
Desktop 分析 tool	`tqmane/vyline-search`	从 root scripts 验证 + 更新 pointer
Backend/UI/storage	主 `tqmane/vyline`	普通 workspace 改动

只在 submodule checkout 内修改并不会让主仓库引用新的 commit。先在 submodule 中 commit，再在主仓库显式更新到该 commit 的 pointer。

Clone / update

git clone --recurse-submodules https://github.com/tqmane/vyline.git
cd vyline
git submodule status

已有 clone 的 submodule 目录为空时：

git submodule update --init --recursive

用 git submodule status 查看当前引用 commit，用 git status --short 查看改动。只在 submodule 内执行 git pull 不会更新主仓库保存的可复现引用 commit。