project-yui · msojocs · Apr 18, 2026 · Apr 11, 2026 · Apr 18, 2026 · Apr 18, 2026
diff --git a/.codex b/.codex
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,25 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Yui: Debug TS via nodestart",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceFolder}",
+      "program": "${workspaceFolder}/tools/yui/nodestart.cjs",
+      "runtimeExecutable": "node",
+      "runtimeArgs": ["--enable-source-maps"],
+      "preLaunchTask": "yui:build",
+      "autoAttachChildProcesses": true,
+      "sourceMaps": true,
+      "outFiles": ["${workspaceFolder}/program/**/*.js"],
+      "resolveSourceMapLocations": [
+        "${workspaceFolder}/program/**/*.js.map",
+        "${workspaceFolder}/src/**/*.ts",
+        "!**/node_modules/**"
+      ],
+      "skipFiles": ["<node_internals>/**"],
+      "console": "integratedTerminal"
+    }
+  ]
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -0,0 +1,14 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "yui:build",
+      "type": "shell",
+      "command": "pnpm run yui:build",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": []
+    }
+  ]
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,122 @@
+# AGENTS
+
+This file gives coding agents and contributors a fast, project-specific map of the Yui repository.
+
+## Project Summary
+
+- Yui is a TypeScript-based bot framework around NTQQ/QQ integration.
+- The runtime entry is `src/index.ts`, which initializes OneBot actions, starts HTTP/WebSocket servers, and loads native pieces on Linux.
+- The main build output is bundled with Vite into `program/index.js` (CommonJS format).
+- The project expects the Node.js version to match the official client version. The current documented version is `v20.18.1` in `README.MD`.
+
+## Package Manager And Toolchain
+
+- Package manager: `pnpm`
+- Language: TypeScript with ESM source files
+- Bundler: Vite
+- Test runner: Vitest
+- Native/runtime coupling: Electron/NTQQ-related native modules and preload hooks are part of normal development flow
+
+## Common Commands
+
+Use the commands defined in `package.json` rather than older names in some docs.
+
+- Install dependencies: `pnpm install`
+- Install Yui runtime assets: `pnpm run yui:install`
+- Start Vite watch build: `pnpm run yui:dev`
+- Build once: `pnpm run yui:build`
+- Start node-mode runtime: `pnpm run yui:nodestart`
+- Install UI assets: `pnpm run ui:install`
+- Start UI mode: `pnpm run ui:start`
+- Start UI mode with log file: `pnpm run ui:start-log-file`
+- Regenerate protobuf TS files: `pnpm run proto:generate`
+- Watch protobuf changes: `pnpm run proto:watch`
+- Compile JS to bytecode helper: `pnpm run compile-jsc`
+- Run tests directly: `pnpm exec vitest run`
+
+## Important Documentation
+
+- Overview: `README.MD`
+- Dev workflow: `docs/dev.md`
+- Manual environment setup: `docs/dev-manual.md`
+- Patch notes / validation removal: `docs/patch.md`
+- Exported function inventory: `docs/function.md`
+
+Note: `docs/dev.md` still uses older command names such as `pnpm run dev` and `pnpm run nodestart`. Prefer the `yui:*` and `ui:*` scripts from `package.json`.
+
+## Repository Map
+
+### Source directories
+
+- `src/index.ts`: main runtime entry
+- `src/bootstrap`: startup/runtime orchestration
+- `src/adapters`: protocol and runtime adapters for HTTP, WebSocket, OneBot, and server startup
+- `src/app`: application services for higher-level use cases such as login and message flows
+- `src/server`: legacy-compatible server entrypoints plus HTTP/WebSocket implementations
+- `src/http`: legacy-compatible HTTP route and handler area; newer route assembly now lives under `src/adapters/http`
+- `src/onebot`: legacy-compatible OneBot entrypoints plus protocol-specific handlers
+- `src/ntqq`: NTQQ-related types, protobuf code, helpers, and store logic
+- `src/wrapper`: wrapper hook logic and exported wrapper service shims
+- `src/native`: native initialization
+- `src/common`: shared utilities, logging, locks, file helpers
+- `src/store`: config and persistence helpers
+- `src/models`: contact and model abstractions
+- `src/transfer`: login/message conversion flow
+- `src/test`: in-repo runtime test hooks used by the entrypoint
+
+### Build/runtime/support directories
+
+- `tools/yui`: install/build/dev/nodestart scripts
+- `tools/ui`: UI startup/install helpers
+- `tools/wrapper`: wrapper-related code generation/helpers
+- `program`: runtime/program assets and generated launcher output
+- `dist`: additional compiled artifacts such as the UI hook bundle
+- `resources`: static assets
+- `docs`: project documentation and reverse-engineering notes
+- `test`: ad hoc scripts and artifacts, not the main Vitest suite
+
+## Change Guidelines
+
+### 1. Respect generated or semi-generated areas
+
+- `src/ntqq/protobuf/*.ts` is generated from `.proto` files. If behavior depends on protobuf schema changes, update the `.proto` files first and regenerate with `pnpm run proto:generate`.
+- Large wrapper export files under `src/wrapper/exports` are repetitive and may be generated or scaffolded by helper scripts in `tools/wrapper`. When making broad changes, inspect the generator path before hand-editing many files.
+
+### 2. Be careful around runtime-coupled code
+
+- `src/index.ts`, `src/wrapper/hook.ts`, `src/native`, and `tools/yui/nodestart.cjs` are tightly coupled to local NTQQ/native runtime behavior.
+- Linux runtime depends on `YUI_PRELOAD` and `YUI_NATIVE` paths. Windows runtime has different hard-coded development assumptions.
+- Avoid “cleanup” changes in these paths unless they are necessary for the task and validated against the existing startup flow.
+
+### 3. Follow existing implementation patterns
+
+- Prefer placing new orchestration and registration logic in `src/adapters/**` and `src/app/**`.
+- Treat files such as `src/onebot/onebot.ts`, `src/onebot/actions/index.ts`, `src/onebot/event/index.ts`, and `src/server/index.ts` as compatibility entrypoints; keep them thin.
+- New OneBot actions should usually be implemented via `src/app/**` or adapter helpers, with `src/onebot/actions/**` remaining thin registration or compatibility layers.
+- Server-facing changes should remain split between HTTP (`src/server/http.ts`, `src/adapters/http/**`) and WebSocket (`src/server/websocket.ts`, `src/adapters/ws/**`) concerns.
+- Shared utilities belong in `src/common` or the nearest domain module instead of adding duplicate helpers.
+
+## Verification Guidance
+
+Choose the lightest useful verification for the files you touch.
+
+- For TypeScript or bundling changes: run `pnpm run yui:build`
+- For protobuf changes: run `pnpm run proto:generate`
+- For unit-testable logic: run `pnpm exec vitest run`
+- For runtime/bootstrap changes: if possible, also validate with `pnpm run yui:nodestart`
+
+Because this repo integrates with local QQ/NTQQ assets and native modules, some runtime validation may not be possible in a clean sandbox. If you cannot run full validation, state that clearly.
+
+## Working Agreements For Agents
+
+- Prefer small, surgical edits over broad formatting churn.
+- Do not rewrite generated protobuf outputs manually unless regeneration is intentionally out of scope and the change is very localized.
+- When editing wrapper export files, preserve logging and call-through structure unless the task is explicitly about changing that behavior.
+- Check for outdated docs before following them blindly; `package.json` is the source of truth for runnable scripts.
+- Treat `program`, native paths, and startup scripts as integration-sensitive areas.
+
+## Known Gotchas
+
+- The repository may already contain built artifacts and local runtime assets such as `program`, `dist`, `cache`, and `tmp`.
+- The working tree may also include local-only files or directories such as `.codex`; avoid touching unrelated files.
+- The Vitest setup exists, but a large portion of the project behavior is integration-driven rather than covered by isolated tests.
diff --git a/README.MD b/README.MD
@@ -29,6 +29,24 @@
 
 获取当前项目，对它进行进一步开发，请阅读[开发文档](./docs/dev.md)
 
+常用命令：
+
+- `pnpm run yui:install`
+- `pnpm run yui:dev`
+- `pnpm run yui:build`
+- `pnpm run yui:nodestart`
+- `pnpm run ui:start`
+- `pnpm run ui:start-log-file`
+
+当前目录约定：
+
+- 启动与运行时初始化优先查看 `src/bootstrap/**`
+- HTTP / WS / OneBot 装配优先查看 `src/adapters/**`
+- 动作用例与注册优先查看 `src/app/**`
+- `src/onebot`、`src/server`、`src/http` 中多数文件已逐步退化为兼容入口
+
+更多结构说明见：[重构计划](./docs/refactor-plan.md) 与 [迁移清单](./docs/refactor-migration-checklist.md)
+
 ## 注意
 
-NodeJs版本要与官方客户端一致。目前是`v20.18.1`。
+NodeJs版本要与官方客户端一致。目前是`v20.18.1`。
diff --git a/docs/dev-manual.md b/docs/dev-manual.md
@@ -33,6 +33,6 @@
 
 ## 4. 启动
 
-  1. pnpm run dev
-  2. pnpm run nodestart
+  1. `pnpm run yui:dev`
+  2. `pnpm run yui:nodestart`
   3. 看到输出中包含：`Hi Yui bot!!`
diff --git a/docs/dev.md b/docs/dev.md
@@ -12,9 +12,9 @@
 
 ### 2.1 使用脚本安装
 
-1. 执行 `pnpm run install-ntqq`
-2. pnpm run dev
-3. pnpm run nodestart
+1. 执行 `pnpm run yui:install`
+2. 执行 `pnpm run yui:dev`
+3. 执行 `pnpm run yui:nodestart`
 
 ### 2.2 手动安装
 
@@ -24,11 +24,11 @@
 
 ## 1. 运行
 
-  1. 执行命令 `pnpm run dev`，开始编译ts文件
-  2. 生成的文件在 `program/resources/app/app_launcher/index.js`
-  3. 启动无UI界面的Yui，执行`pnpm nodestart`
-  4. 启动有UI界面的Yui，执行`pnpm start`
-  5. 启动有UI界面保存Log的Yui，执行`pnpm start-log-file` (分析接口行为使用)
+  1. 执行命令 `pnpm run yui:dev`，开始监听并编译 TypeScript
+  2. Node 运行入口会构建到 `program/index.js`
+  3. 启动无 UI 界面的 Yui，执行 `pnpm run yui:nodestart`
+  4. 启动有 UI 界面的 Yui，执行 `pnpm run ui:start`
+  5. 启动有 UI 界面并保存日志的 Yui，执行 `pnpm run ui:start-log-file`（分析接口行为使用）
 
 ## 2. 关于后续开发
 
@@ -57,14 +57,14 @@
 
 ## 2. 实现功能流程
 
-  相关代码在：[getFriendList](../src/onebot/actions/friend.ts)
+  相关代码在：[getFriendList](../src/app/friend/friend-service.ts)
 
   1. 通过 `sendEvent` 先订阅 `onBuddyListChange` 事件
   2. 再通过 `registerEventListener` 注册一次性的好友列表变更事件 `onBuddyListChange`，用来接收推送
   3. 最后，通过 `sendEvent` 发送 `getBuddyList` 操作触发好友列表变更事件
 
 ## 3. 注册Onebot的动作处理
 
-  相关代码在：[initFriend](../src/onebot/actions/friend.ts)
+  相关代码在：[friendActionHandlers](../src/app/friend/register-friend-actions.ts)
 
-  在这个函数中，通过 `registerActionHandle` 来注册动作调用函数。
+  当前动作注册已经迁移到 `src/app/**` 下的薄注册层中，通过 `action handler map + registerActionHandlers` 的方式统一完成注册。
diff --git a/docs/function.md b/docs/function.md
@@ -1,3 +1,10 @@
+> 说明
+>
+> 本文主要记录 NT wrapper / kernel service 的方法清单，用于排查和能力索引。
+>
+> 当前业务主路径已逐步迁移到 `src/bootstrap/**`、`src/adapters/**`、`src/app/**` 与 `src/ntqq/core/**`。
+> 若要新增或调整实际功能，优先从这些目录进入，而不是回到 `src/onebot/**`、`src/server/**` 等兼容入口扩展逻辑。
+
 ## NodeIKernelAVSDKService
 
 | 方法名 | 参数数量 |
@@ -2285,4 +2292,3 @@
 | 方法名 | 参数数量 |
 |-------|-----|
 | onResult | 4 |
-
diff --git a/docs/refactor-migration-checklist.md b/docs/refactor-migration-checklist.md
@@ -0,0 +1,122 @@
+# 重构迁移清单
+
+> **本文是有限清单。所有条目均已完成并冻结。**
+> 不追加新条目，不提出“下一阶段建议”。
+
+## 状态图例
+
+- `[x]` 已完成，冻结，不再验证
+
+---
+
+## 1. 已完成项（冻结）
+
+### 启动与装配
+- [x] `src/index.ts` 薄入口
+- [x] `src/bootstrap/**` 启动编排与 runtime 初始化
+- [x] `src/adapters/server/**` HTTP/WS 服务启动
+- [x] `src/adapters/http/**` 路由装配
+- [x] `src/adapters/ws/**` 连接管理、请求处理
+- [x] `src/adapters/onebot/**` 事件装配与构造
+
+### Action/Event
+- [x] `src/app/register-onebot-actions.ts` 统一 action handler map
+- [x] `src/app/dispatch-action.ts` 统一分发
+- [x] `src/store/action-registry.ts` 独立注册表
+- [x] `src/adapters/onebot/register-events.ts` 统一事件注册
+- [x] `src/store/event-registry.ts` 独立注册表
+
+### 应用服务层
+- [x] `src/app/login/**` 登录用例
+- [x] `src/app/friend/**` 好友用例
+- [x] `src/app/group/**` 群组用例
+- [x] `src/app/message/**` 消息用例
+
+### NTQQ 生命周期
+- [x] ntqq/core 粒度合理（最大 164 行），不需进一步拆分
+- [x] runtime-store 统一到 current runtime / current self 语义
+
+### 登录与配置
+- [x] `src/ntqq/login/` account-*.ts 系列
+- [x] `src/ntqq/store/` config-*.ts 系列
+- [x] 聚合出口 `@aggregation-boundary` 标注完成
+
+### 消息转换
+- [x] 发送链路 flow / builder / resource 三层
+- [x] 接收链路 `convert-receive.ts`
+
+### Compat 清理
+- [x] 所有旧 compat 文件已删除（server、onebot/actions、onebot/event、http handler、store/store.ts 等）
+- [x] 所有 `use*Service()` facade 已删除
+- [x] `useLogger()` 定性为长期 API
+- [x] kicked offline `process.exit` 已加注释说明设计意图
+
+### 测试
+- [x] `src/common/deep-merge.test.ts`
+- [x] `src/transfer/message/send-basic-element-builders.test.ts`
+- [x] `src/transfer/message/image-resource-preparer.test.ts`
+
+### 依赖方向验证
+- [x] app → adapters: 无（正确）
+- [x] ntqq → adapters: 无（正确）
+- [x] transfer → adapters: 无（正确）
+- [x] 非 bootstrap → bootstrap: 无（正确）
+- [x] ntqq 内部循环: 无（正确）
+
+---
+
+## 2. 已完成收尾项
+
+### [x] 任务 1：删除残留空目录
+
+已删除：
+
+```text
+src/server/error/
+src/onebot/actions/
+src/http/
+```
+
+验证：上述路径已不存在
+
+### [x] 任务 2：迁移 `forward-converter.ts`
+
+- `src/common/forward-converter.ts` 已迁移到 `src/transfer/message/forward-converter.ts`
+- 群合并转发发送链路已由 `src/ntqq/message/group-forward.ts` 承接
+
+### [x] 任务 3：清理 `common/utils.ts` 的 native 依赖
+
+- `getHttpTicket()` 已迁移到 `src/ntqq/message/http-ticket.ts`
+- `src/common/utils.ts` 已不再 import `native/native`
+
+### [x] 任务 4：处理 models 层 native 依赖
+
+- `src/models/contact/group.ts` 已不再直接调用 native，改为通过 `src/ntqq/message/group-forward.ts` 薄委托
+- `src/models/contact/member.ts` 已不再直接调用 native，改为通过 `src/ntqq/group/nudge.ts` 薄委托
+
+---
+
+## 3. 完成定义
+
+- [x] 任务 1 完成
+- [x] 任务 2 完成
+- [x] 任务 3 完成
+- [x] 任务 4 完成
+
+**全部 4 项已完成，本轮重构结束。**
+
+## 4. 约束规则（给执行者）
+
+1. **不追加任务**：完成以上条目后停止
+2. **不重新验证 `[x]` 项**：冻结项不需重新检查
+3. **不扩展范围**：不做批量重命名、不做进一步拆分
+4. **维持当前文档口径**：后续仅在代码状态变化时同步更新
+
+## 5. 验证记录
+
+| 日期 | 命令 | 结果 |
+|---|---|---|
+| 2026-04-18 | `pnpm run yui:build` | 通过 |
+| 2026-04-18 | `pnpm exec jest` | 通过（3 个测试文件） |
+| 2026-04-18 | 空目录检查 | `src/server/error`、`src/onebot/actions`、`src/http` 已不存在 |
+| 2026-04-18 | 依赖方向 grep 验证 | `common → native` 与 `models → native` 已清理 |