From 27b8c31a52a7a2a0febeec018d2b808279333a03 Mon Sep 17 00:00:00 2001
From: what <what-00@qq.com>
Date: Thu, 20 Aug 2026 17:21:12 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20README=EF=BC=8C?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=E5=BD=93=E5=89=8D=E5=88=86=E6=94=AF=E7=9A=84?=
 =?UTF-8?q?=E8=83=BD=E5=8A=9B=E8=8C=83=E5=9B=B4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

配合 v1-legacy 维护分支的拆分，记录 master 这条线（DI 辅助、插件注册、资源
系统对接、各类服务契约）目前有哪些能力，跟 v1-legacy 分支做区分。
---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2dcb73f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# git.fsdpf.net/go/contracts（master）
+
+跨服务共享的契约层：各类服务（HTTP/gRPC/队列/任务调度/定时任务/MQTT/WebSocket/条件流引擎等）
+的接口定义，以及资源系统相关的类型别名，供 `framework-v2`（服务编排/启动）和各业务项目共同
+依赖，避免互相直接 import 造成循环依赖。配合 "-v2" 系列项目使用。
+
+## 这个仓库有什么
+
+### DI 辅助（`di.go`）
+
+对 `samber/do/v2` 的一层薄封装：`Injector`/`Invoke`/`MustInvoke`/`InvokeNamed`/
+`MustInvokeNamed`，全仓库统一用这几个函数取 DI 容器里的服务，不直接 import `samber/do/v2`。
+
+### 插件与注册（`app.go`）
+
+`App` 接口：`LoadGoPlugin(file string) error` 加载 Go plugin，`RegControllers`/`RegResWatchers`/
+`RegGRpcs`/`RegJobs`/`RegCrons`/`RegMqtts`/`RegFlowDecisions`/`RegGoBridges`/
+`RegResVirtualTables` 一批 `Reg*` 方法把插件里定义的各类实现注册进框架，对应的 `GetApp*`/
+`Get*` 方法按 code 查回来。
+
+### 资源系统对接
+
+- `resource.go`：`GetResource`/`MustResource` 是 `req.GetResource`/`req.MustResource` 的类型
+  别名，`GetUser` 按 uuid 查用户。
+- `res_watcher.go`：`ResEventType`（`resx.ResEventType` 别名）+ `ResWatcher`——资源发生变更时
+  要通知的外部监听方注册信息。
+- `res_virtual_table.go`：`ResVirtualTableSetup`（`req.ResVirtualTableSetup` 别名）——`framework-v2`
+  在 `sqlite_vtable` build tag 下注册进容器，负责给 SQLite 注册虚拟表模块。
+- `event_stream.go`：事件流相关契约。
+
+### 各类服务契约
+
+`http.go`/`grpc.go`/`grpcall.go`/`server.go`（HTTP/gRPC）、`job.go`/`cron.go`/`queue.go`
+（任务调度/定时任务/消息队列）、`mqtt.go`/`ws.go`（MQTT/WebSocket）、`jwt_auth.go`/`captcha.go`
+（鉴权/验证码）、`condflow.go`（条件流引擎对接）、`gobridge.go`（跨语言 bridge）、`mcp.go`
+（Model Context Protocol 对接）、`executor.go`（通用执行器契约）。
+
+### 子包
+
+- `base/`：基础类型（用户、角色等业务通用结构）。
+- `support/`：辅助工具。
+
+## 分支状态
+
+`master` 是持续开发中的新架构，**跟老仓库 `v1-legacy` 分支不完全兼容**——`di.go`/`app.go`/
+`condflow.go`/`gobridge.go`/`mcp.go`/`res_virtual_table.go`/`res_watcher.go` 都是新增的，
+`res_event.go`/`res_type/` 这些老概念已经拆分/移除。还在用老版契约的老项目，参见 `v1-legacy`
+分支。