Docs / 开发

开发者指南

本地开发、定位正确的修改边界、验证以及文档更新。

Setup

git clone --recurse-submodules https://github.com/tqmane/vyline.git
cd vyline
bun install --frozen-lockfile
bun run typecheck
bun run lint
bun test
bun run build

使用 Bun 1.4 或更高版本。workspace 包括 Vyline/packages/*、Desktop app、Backend 等；Protocol、Plugin、Themes 是 Git submodule。

开发服务器

bun run dev
# 仅 backend:  bun run dev:backend
# 仅 frontend: bun run dev:frontend

dev:backend 通过 Bun watch 重启 Vyline/backend/src/index.ts，dev:frontend 启动 Vite dev server。production build 会把 Frontend 构建成 static asset，并由同一个 Bun/Hono Backend process 提供。

修改位置

要修改的内容	先看这里
Web UI	`Vyline/apps/desktop`
HTTP API / DB / restore	`Vyline/backend`
LINE RPC / E2EE / login	`Vyline/packages/protocol`
Plugin contract	`Vyline/packages/plugin` + Backend plugin runtime
Theme preset	`Vyline/packages/themes`
Desktop LINE reverse research	`tools`

追踪处理时的顺序

处理	Frontend	Backend	Protocol
首次显示	`useLineData.ts` → `api.line.bootstrap`	`GET /line/:accountId/bootstrap` → SQLite	通常不发 RPC
新消息/事件	`useVylineSync.ts` / `pollIncoming`	event buffer / `processFetchedOperations`	`base.talk.sync`
active chat 增量	`pollMessagesDelta`	`/messages/:chatMid/delta`	需要时 remote fetch
发送	`api/client.ts`	`api/line.ts` → `lineService.sendMessage`	Talk / E2EE
登录	auth UI/client	`clientManager`	QR / Email / Token + E2EE ensure
媒体	upload/download API	`lineService` / media storage	Talk metadata + object storage/E2EE

排查问题时不要从 UI 直接跳到 Protocol。按 Frontend request → BFF route → service → session manager → Protocol 的顺序确认每个边界。

修改 Backend API

确认 Vyline/apps/desktop/src/api/client.ts 中的 client contract。
Vyline/backend/src/api/line.ts 负责输入验证、status code 与 HTTP serialization。
涉及 LINE/DB 的处理放到 service/lineService.ts 或对应 service。
需要 account/session 时，复用 line/clientManager.ts 已有的 queue/urgent/send 路径。
修改持久状态时，同时检查 storage、restore 与 backup 的一致性。
添加 route/service test，并让 Frontend 类型与实际 response 对齐。

当前边界要求不要把大量业务逻辑塞进 api/line.ts。与 HTTP 无关的处理保留在 service 中，便于其他 endpoint 或未来 consumer 复用。

修改 Protocol

添加或修改 RPC 时，先在 Vyline/packages/protocol/src/dictionary/rpcMap.ts 确认现有对应关系，再按 Desktop evidence → Protocol stack → domain facade → Backend service/BFF 的顺序追踪。

rpcMap.ts
  canonicalName / desktopEvidence / path
        ↓
stack API / Thrift types
        ↓
domain API
        ↓
backend lineService
        ↓
api/line.ts
        ↓
frontend api/client.ts

如果故障来自 Desktop 更新，用 bun run vyline:delta 或 bun run vyline:find-native -- <name> 确认当前实现。modules.map.ts 中的 feature 可缩小关联 binary、search string 与 analysis docs。

修改 Storage

chat runtime persistence 使用 SQLite，chatStoreSqlite.ts 管理 WAL mode、schema version、chats/messages/message_sync/local_read 等。Vyline 不是在启动时把全部聊天历史 hydrate 到内存。

检查现有 schema 以及 PRAGMA user_version 的处理方式。
设计不会破坏已有 DB 的向前 migration。
restore/import 在 staging DB 或 copy 上验证，失败时不要部分修改原 DB。
Docker 中明确数据应放在 /app/data 还是 /app/storage。
同时确认 backup quota、media sidecar 与 cache 删除语义。

不要混淆 cache 与持久数据。可重新生成的 CDN/icon cache，与 session/chat DB/saved media/backup 在删除后的影响完全不同。

修改 Plugin / Theme

Plugin contract 位于 submodule 的 @vyline/plugin-sdk，执行与按账号保存的 enable 状态由 Backend pluginRuntime.ts/pluginManager.ts 负责。plugin 的 activate/deactivate 与 event handler 会被隔离，避免扩展异常拖垮主程序。

在 manifest 中增加 permission 字符串不会自动增加 capability。要一起检查 SDK 类型、Backend context 实际暴露的方法，以及 manager 的 permission handling。Theme 以 Vyline/packages/themes 的 VyTheme 与 preset token 为准。

验证层级

bun run typecheck
bun run lint
bun test
bun run build

这四项全部通过，也不代表真实 LINE session 或 Docker deployment 已被验证。根据改动内容继续验证 local Backend API、browser UI、Docker image，必要时再验证真实 session。

更新 Docs 网站

web/ 是手工维护的 static HTML/CSS/JavaScript。直接编辑目标 web/docs/<page>/index.html。共用样式在 web/assets/vyline.css，Docs 搜索、主题、目录、代码复制逻辑在 web/assets/docs.js。

不要用脚本自动生成 Web Docs。只更新真正受实现变更影响的页面，并先重新查看当前实现与相关文档；之后通过本地 HTTP server 检查显示与链接。

README

README.src.md 是 README 的编辑源。README 的日语/英语输出属于另一套流程，修改后运行 bun run docs:readme。Web Docs 本身仍由手工编辑 HTML，不由该命令生成。