feat(plugin): Lua 插件机制 + 计费插件 + 插件文档

插件 = plugin_dir 下的单个 .lua 文件，做两件事：挂请求流水线的钩子、在启动时
贡献 WebUI 界面（整页或往现有页面追加组件）。两者独立。

## 流水线 stage（三个）
  request_start  已解析鉴权、未选源
  routed         已选定 (source, model)、未发往上游
  request_end    每请求恰好一次，带最终计量
request_end 挂在 gateway.writeRec——四条入口路径（直连/AUTO × 流式/非流式）的
唯一汇合点：既不漏（流式 token 只有流结束才知道）也不重。

## 计费插件（plugins/billing.lua，默认 seed，开箱可用）
源 / 模型 / 密钥三个维度定价。token 价优先级 keys > models > default；per_request
固定价是**叠加**的（生图模型可以既算 token 又收固定费）。单位是 USD/单 token，
即各家 provider 的公布口径。累计 total / by_source / by_model / by_key / by_day。
失败请求保留 token 费用、丢弃固定费（可经 count_failures 翻转）。
界面 = 一个独立页 + 状态页顶部一块总开销 tile。

## 一个明确的设计边界
计费插件**只报表，不执法**。网关自己的配额会计（stats.go，入口强制）才是限额
权威，插件不参与任何路由/配额决策。两套独立会计若对不上，比一套功能略少的
更糟。

## ★ 中途改掉的一个根本设计错误
最初让插件复用适配器的**弹性 worker 池**（多状态）。这对适配器是对的（它们无
状态），对插件是错的：计费插件往 plugin.state 累加，多状态意味着总量被劈成
几份；而 SetState 写价格只写进其中一个 worker，钩子恰好跑到另一个时**所有请求
按 0 计费**。改为**单状态 + 互斥锁**。代价写进文档：钩子必须短、同步、不阻塞，
卡住的钩子会卡住所有插件的钩子。
这个 bug 是测试逼出来的——先写了 SetState+Fire 的用例，数字全是 0 才挖出来。

另一个连带缺陷：只带 prices 的 PUT 会整体替换 state，把累计量清零。改为
prices/state 分离——prices 是配置、state 是历史，改价不动账。

## 撞到的三个 Lua 绑定的坑（都写进注释）
  - SetGlobal **会 pop 栈**：连着调两次，第二次从空栈取，赋成 nil
  - GetField 索引越界是 **SIGABRT 整个进程**，不是 panic，recover 救不了
  - Call(nargs, n) **不接受函数索引**，它调的是 nargs 个参数正下方那个；
    传索引会调到参数上（"attempt to call a table value"）
另外 GetField/SetField 用绝对索引，SetTop(0) 之后必须重取。

## 错误隔离
钩子 error() 不影响转发：捕获 → 记进 hook_errors → 跳下一个插件。适配器出错
会让源进冷却，插件出错**零惩罚**——插件是可选功能。/api/plugins 的 hook_errors
让"坏掉的插件"可见而不是静默消失。

## 界面注入
GET /api/ui-inject 一次返回所有插件的扩展（侧栏需要全部 page 才能建好）。
WebUI 在首次 render **之前** await 注入：先插 HTML 再重建 <script> 让它执行
（innerHTML/template 插入的 script 不会执行，这正是要的效果——避免脚本跑在
自己 DOM 之前）。注入失败不影响仪表盘。
browser 侧 pluginAPI 暴露 fetchState / postState / onTabShown。

## 文档
docs/plugins.md —— 快速上手、加载与热更新、三个 stage 的完整字段表、界面扩展、
状态与 HTTP API、运行时约束（单状态/异常隔离/内置函数）、计费插件的定价与
计费策略、排错表、与适配器的对比表。

## 判据（328 个测试全绿，插件相关 33 个）
  - 计费断言的是**具体金额**（0.00625 / 0.0402 / 0.0075…），不是"能加载"
  - 4 个变异都红：钩子异常不隔离 / prices 清空累计 / 忽略 key 优先级 /
    毫秒时间戳不换算
  - UI 侧 6 个判据把注入顺序、script 执行时机、pluginAPI 名称、tab 路由、
    anchor 四种形式、失败非致命全钉住
  - 鉴权：state 读任意角色、写仅 admin

internal/lua/vm.go

@@ -36,7 +36,7 @@ import (
 	golua "github.com/aarzilli/golua/lua"
 )
 
-//go:embed adapters/*.lua
+//go:embed adapters/*.lua plugins/*.lua
 var bundledAdapters embed.FS
 
 // adapterGlobal is the reserved global holding the adapter table after the
@@ -103,6 +103,11 @@ type adapterPool struct {
 	lastGrow   time.Time
 	idleRounds int // consecutive janitor rounds that saw reclaimable slack
 	peakInUse  int // high-water mark of inUse, for observability
+	// pluginMode makes boot() store the returned table under pluginGlobal
+	// instead of adapterGlobal. Everything else (elastic sizing, reclaim) is
+	// identical, which is why plugins reuse this pool rather than getting a
+	// second implementation.
+	pluginMode bool
 }
 
 const (
@@ -116,6 +121,13 @@ const (
 	// growCooldown keeps a burst of misses from batching repeatedly while the
 	// previous batch is still booting.
 	growCooldown = time.Second
+	// maxPluginStates caps how many concurrent VM states ONE plugin may occupy.
+	// A plugin is third-party code on the request path, so its ceiling is much
+	// lower than an adapter's (which is sized from the sources'
+	// max_concurrent): a plugin hook is a short synchronous call, so a handful
+	// of states is already far more parallelism than any real hook needs, and a
+	// runaway plugin cannot balloon memory the way a per-source adapter pool can.
+	maxPluginStates = 4
 	// residentWorkers is how many states an adapter keeps warm once it has
 	// served at least one request. Booting is milliseconds, but keeping one warm
 	// removes that from the critical path of the next request. Adapters that
@@ -265,7 +277,14 @@ func (p *adapterPool) boot() (*worker, error) {
 		L.Close()
 		return nil, fmt.Errorf("adapter %s must return a table", p.name)
 	}
-	L.SetGlobal(adapterGlobal)
+	// SetGlobal POPS the value off the stack, so it can only be called once per
+	// boot. Plugins therefore store under pluginGlobal only, and NOT under
+	// adapterGlobal: a second SetGlobal on the now-empty stack would assign nil.
+	if p.pluginMode {
+		L.SetGlobal(pluginGlobal)
+	} else {
+		L.SetGlobal(adapterGlobal)
+	}
 	L.SetTop(0)
 	return &worker{L: L}, nil
 }
@@ -601,6 +620,55 @@ func (v *VM) Start() error {
 	return nil
 }
 
+// bundledPluginsDir is the directory inside the embedded FS holding the
+// plugins shipped with the gateway. It is separate from adapters/ on purpose:
+// the two are loaded by different machinery into different kinds of Lua state
+// (a protocol transform vs. request-pipeline hooks), and keeping them apart
+// makes it obvious that dropping a file in one does not affect the other.
+const bundledPluginsDir = "plugins"
+
+// ReadBundledPlugin returns the source of a plugin shipped with the gateway.
+// It exists so a test (or an operator tool) can load a bundled plugin without
+// depending on whether seeding has already run for this directory.
+func ReadBundledPlugin(name string) (string, error) {
+	data, err := bundledAdapters.ReadFile(bundledPluginsDir + "/" + name + ".lua")
+	if err != nil {
+		return "", fmt.Errorf("bundled plugin %s: %w", name, err)
+	}
+	return string(data), nil
+}
+
+// writeBundledPlugins seeds the plugin directory with the shipped plugins.
+//
+// It runs only when the directory does not exist yet (same rule as adapters):
+// once the directory exists it is authoritative, so deleting a shipped plugin is
+// a real delete and editing one survives restarts.
+func writeBundledPlugins(dir string) error {
+	if dir == "" {
+		return nil
+	}
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return fmt.Errorf("mkdir plugin dir: %w", err)
+	}
+	entries, err := bundledAdapters.ReadDir(bundledPluginsDir)
+	if err != nil {
+		return nil // nothing embedded; not an error
+	}
+	for _, e := range entries {
+		if e.IsDir() || filepath.Ext(e.Name()) != ".lua" {
+			continue
+		}
+		data, err := bundledAdapters.ReadFile(bundledPluginsDir + "/" + e.Name())
+		if err != nil {
+			continue
+		}
+		if err := os.WriteFile(filepath.Join(dir, e.Name()), data, 0644); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 func (v *VM) Stop() {
 	select {
 	case <-v.janitorStop:
@@ -1104,6 +1172,56 @@ func pushGoValue(L *golua.State, v interface{}) {
 }
 
 func jsonEncode(v interface{}) ([]byte, error) { return json.Marshal(v) }
+
+// luaToJSON converts the Lua value at idx into a Go value via json.encode, then
+// unmarshals it into out. It is the bridge used by the plugin manifest/UI
+// reader: the plugin returns a plain Lua table, and Go wants a typed struct.
+//
+// It goes through JSON rather than walking the Lua stack directly because the
+// adapter/plugin boundary already speaks JSON everywhere else (transform_request
+// gets a JSON string, hooks get a JSON string), so this keeps one representation
+// instead of two.
+func luaToJSON(L *golua.State, idx int, out interface{}) error {
+	if L.GetTop() < 1 {
+		return fmt.Errorf("empty stack")
+	}
+	abs := idx
+	if abs < 0 {
+		abs = L.GetTop() + 1 + abs
+	}
+	if abs < 1 || abs > L.GetTop() {
+		return fmt.Errorf("index %d out of range (top=%d)", idx, L.GetTop())
+	}
+	// Absolute indices throughout: this binding aborts the process (SIGABRT)
+	// on a bad index rather than panicking, so the stack is captured before any
+	// push instead of being addressed relative to a shifting top.
+	//
+	// json.encode is pushed onto the stack and the value is pushed AFTER it, so
+	// Call(1, 1) invokes it (Call takes no function index — it calls whatever
+	// sits below the nargs values).
+	L.GetGlobal("json")
+	if L.IsNil(-1) {
+		L.SetTop(0)
+		return fmt.Errorf("json global missing")
+	}
+	L.GetField(-1, "encode")
+	if L.Type(-1) != golua.LUA_TFUNCTION {
+		L.SetTop(0)
+		return fmt.Errorf("json.encode missing")
+	}
+	L.PushValue(abs)
+	if err := L.Call(1, 1); err != nil {
+		L.SetTop(0)
+		return err
+	}
+	if L.GetTop() < 1 || L.Type(-1) != golua.LUA_TSTRING {
+		L.SetTop(0)
+		return fmt.Errorf("json.encode did not return a string")
+	}
+	s := L.ToString(-1)
+	L.SetTop(0)
+	return json.Unmarshal([]byte(s), out)
+}
 func jsonDecode(s string) (interface{}, error) {
 	var v interface{}
 	if err := json.Unmarshal([]byte(s), &v); err != nil {