lakutata 3.0.0 → 3.1.0

package/doc/zh/MCP.md

@@ -0,0 +1,265 @@
+# Lakutata MCP
+
+模型上下文协议（MCP）让 AI 助手使用一个应用：调用它的**工具**，读取它的**资源**，填写它的**提示词**。`@lakutata/mcp` 包把控制器方法作为这些内容提供出来，可以通过子进程的标准输入输出，也可以通过 HTTP。它不属于 `lakutata`：
+
+```bash
+npm install lakutata @lakutata/mcp
+```
+
+| 声明方式 | 是什么 | 谁来使用 |
+|---|---|---|
+| `@MCPTool(name)` | 模型带着参数调用的动作 | 模型，在它决定调用时 |
+| `@MCPResource(uri)` | 按 URI 读取的数据 | 客户端，把它交给模型 |
+| `@MCPPrompt(name)` | 用参数填写的消息模板 | 用户，在客户端中选择它 |
+
+## 1. 基于 stdio 的服务器
+
+```typescript
+import {Application, DTO, Exception} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {Prefix} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+import {Logger} from 'lakutata/com/logger'
+import {MCPPrompt, MCPResource, MCPTool, stdioMCPEntrypoint} from '@lakutata/mcp'
+
+class DeviceSnDTO extends DTO {
+    @Expect(DTO.String().required().description('The serial number of the device'))
+    public sn: string
+}
+
+class StatusDTO extends DTO {
+    @Expect(DTO.String().required())
+    public sn: string
+
+    @Expect(DTO.Boolean().required())
+    public online: boolean
+}
+
+class OfflineException extends Exception {
+    public errno: string = 'E_OFFLINE'
+}
+
+@Prefix({mcp: 'device'})
+class DeviceController extends Controller {
+    //工具 device_status
+    @MCPTool('status', DeviceSnDTO, {description: 'The online status of a device', readOnly: true, output: StatusDTO})
+    public async status(input: DeviceSnDTO): Promise<StatusDTO> {
+        return {sn: input.sn, online: input.sn !== 'off'} as StatusDTO
+    }
+
+    @MCPTool('reboot', DeviceSnDTO, {description: 'Reboot a device', destructive: true})
+    public async reboot(input: DeviceSnDTO): Promise<string> {
+        if (input.sn === 'off') throw new OfflineException('The device {sn} is offline', {sn: input.sn})
+        return `Rebooting ${input.sn}`
+    }
+
+    //每台设备的资源：device://A1/status
+    @MCPResource('device://{sn}/status', DeviceSnDTO, {mimeType: 'application/json', description: 'The status of a device'})
+    public async statusResource(input: DeviceSnDTO): Promise<StatusDTO> {
+        return {sn: input.sn, online: true} as StatusDTO
+    }
+
+    //提示词 device_diagnose
+    @MCPPrompt('diagnose', DeviceSnDTO, {description: 'Diagnose the failures of a device'})
+    public async diagnose(input: DeviceSnDTO): Promise<string> {
+        return `Diagnose the device ${input.sn} from its status and its logs.`
+    }
+}
+
+Application.run(() => ({
+    id: 'devices.app',
+    name: 'Devices',
+    components: {
+        //标准输出属于协议：日志写到标准错误
+        log: {class: Logger, destinations: [process.stderr]},
+        entrypoint: buildEntrypoints({
+            controllers: [DeviceController],
+            mcp: stdioMCPEntrypoint({instructions: 'Check the status of a device before rebooting it.'})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+- 客户端用 `node build/App.js` 这样的命令把应用作为子进程运行，通过它的标准输入输出与它通信。客户端关闭它的输入后，应用就会退出（`exitOnClose: false` 让它继续运行）。
+- 标准输出承载协议的消息：日志要像上面那样写到标准错误，也不能调用 `console.log()`。
+- `stdioMCPEntrypoint()` 的选项：`serverName`（默认为应用的名字）、`serverVersion`（`'1.0.0'`）、给模型的 `instructions`、`stdin` 和 `stdout`、`exitOnClose`、`name` 以及 `middlewares`。
+- 在 stdio 上，服务器使用 2025 年的几个协议版本。
+
+## 2. 工具
+
+```text
+@MCPTool(name, DTO?, options?)
+```
+
+| 选项 | 含义 |
+|---|---|
+| `description` | 工具做什么，写给模型看；没有它时，模型看到的是 `ControllerClass:method` |
+| `title` | 用于显示的名字 |
+| `readOnly`、`destructive`、`idempotent`、`openWorld` | 给客户端的提示：工具不做任何修改、会做出不可撤销的修改、再次调用结果相同、会访问外部系统 |
+| `output` | 结果的 DTO：发送它的 JSON Schema，结果也会同时作为结构化内容给出 |
+| `acl`、`rule`、`middlewares`…… | 所有动作共有的选项（见 [Controllers](Controllers.md) 第 3 节） |
+
+- 名字由 1 到 128 个字母、数字、`_`、`-` 或 `.` 组成。`@Prefix({mcp: 'device'})` 给控制器中工具和提示词的名字加上前缀：`status` 变成 `device_status`。
+- 参数由 DTO 的 JSON Schema 描述；`.description()` 向模型说明一个参数。DTO 校验参数，与所有动作一样。
+- 两个控制器声明了同一个工具时，由后注册的那个提供，与其他传输方式相同。
+
+工具的返回值成为它的结果：
+
+| 返回 | 结果 |
+|---|---|
+| 字符串 | 一段文本 |
+| 对象 | 它的 JSON 文本，同时把对象作为结构化内容 |
+| `undefined` | 没有内容 |
+| `Result.file(buffer, {contentType})` | 对应类型时是图片或音频，否则是嵌入的资源 |
+| `Result.status(status, data)` | 它的数据 |
+
+- 类的实例（DTO）只有在工具声明了 `output` 时才作为结构化内容给出。声明了 `output` 却没有返回对象的工具会失败。
+- 服务器不按 `output` 检查结构化内容；由客户端检查，不符合的结果会被客户端拒绝。
+- 工具抛出的错误，包括参数校验和访问控制的错误，会作为标记为错误的结果交给模型，文本是 `errno: message`（`E_OFFLINE: The device off is offline`）。模型可以据此修正它的调用。
+
+## 3. 资源
+
+```text
+@MCPResource(uri, DTO?, options?)
+```
+
+- 没有变量的 URI（`device://catalog`）是一个独立的资源；带变量的 URI（`device://{sn}/status`）是一个模板，由客户端填写。URI 不会加前缀。
+- 变量就是动作的输入。它们是字符串：把它们声明为字符串，或者像 HTTP 请求的查询参数那样，用 `.strict(false)` 转换。
+- 选项：`resourceName`（列出的名字，默认是动作的名字）、`title`、`mimeType`、`audience`（`['user']`、`['assistant']`）、`priority`（0 到 1），以及所有动作共有的选项。
+
+| 返回 | 内容 |
+|---|---|
+| 字符串 | 文本，类型为 `mimeType`（默认 `text/plain`） |
+| 其他值 | 它的 JSON，类型为 `mimeType`（默认 `application/json`） |
+| `Buffer`、`Result.file()` | 按类型给出文本或二进制数据 |
+
+读取资源时抛出的错误以协议错误响应：`statusCode` 是客户端错误（400 到 499，包括输入无效）时为参数无效（`-32602`），否则为内部错误（`-32603`）。错误消息是 `errno: message`。
+
+## 4. 提示词
+
+```text
+@MCPPrompt(name, DTO?, options?)
+```
+
+- DTO 的属性就是提示词的参数，会列给客户端。它们是字符串：把它们声明为字符串，或者用 `.strict(false)` 转换。
+- 字符串成为一条用户消息；数组的每一项成为一条消息（字符串，或者 `{role, content}`）；对象 `{messages}` 按原样发送。
+- 选项 `title`，以及所有动作共有的选项。错误的处理与资源相同。
+
+## 5. 上下文
+
+在 MCP 动作中，`this.context` 是一个 `MCPContext`：
+
+| 属性 | 是什么 |
+|---|---|
+| `kind` | `'tool'`、`'resource'` 或 `'prompt'` |
+| `name` | 工具或提示词的名字，包括前缀；对于资源，是声明时的 URI |
+| `uri` | 读取的 URI，用于资源 |
+| `data` | 校验之前的参数（资源的 `data` 为空，它的变量就是输入） |
+| `authInfo` | `authenticate` 的返回值（第 6 节） |
+| `progress(progress, total?, message?)` | 向客户端报告耗时调用的进度 |
+
+```typescript
+import {Controller} from 'lakutata/com/entrypoint'
+import {MCPTool, type MCPContext} from '@lakutata/mcp'
+
+class ImportController extends Controller {
+    @MCPTool('import', {description: 'Import the devices'})
+    public async import(): Promise<string> {
+        const context: MCPContext = this.context as MCPContext
+        for (let step: number = 1; step <= 3; step++) {
+            //客户端取消了这次调用
+            if (this.signal?.aborted) return 'cancelled'
+            await context.progress(step, 3, `step ${step}`)
+        }
+        return 'imported'
+    }
+}
+```
+
+- 客户端取消调用时，`this.signal` 会被中止。
+- 一个方法可以同时服务多种传输方式（`@GET` 和 `@MCPTool`）：对于 MCP 的请求，`this.context.type` 是 `'MCP'`（`MCP_CONTEXT_TYPE`）。
+- 入口的访问规则适用于以 `acl: true` 声明的 MCP 动作，前提是规则的 `supportContextTypes()` 包含 `MCP_CONTEXT_TYPE`（见 [Middlewares](Middlewares.md)）。
+- 服务器不会向客户端请求任何东西：没有采样（sampling）、征询（elicitation），也不向客户端发送日志。
+
+**通知。** `MCPNotifier` 是一个可以注入的组件（`@Inject(MCPNotifier)`），用来告诉客户端有内容变化：`resourceUpdated(uri)`、`resourcesChanged()`、`toolsChanged()`、`promptsChanged()`。在 stdio 上，只有订阅了某个 URI 的客户端才会收到这个资源的更新。在 HTTP 上，只有使用 2026-07-28 协议版本、并且监听变化的客户端才会收到通知。
+
+## 6. 基于 HTTP
+
+```typescript
+import type {IncomingMessage} from 'node:http'
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {httpMCPEntrypoint, MCPTool, type MCPAuthInfo} from '@lakutata/mcp'
+
+class ClockController extends Controller {
+    @MCPTool('now', {description: 'The current time of the server', readOnly: true})
+    public async now(): Promise<string> {
+        return new Date().toISOString()
+    }
+}
+
+//抛出错误时以 401 响应
+function verifyToken(request: IncomingMessage): MCPAuthInfo {
+    const token: string = request.headers.authorization?.replace(/^Bearer /, '') ?? ''
+    if (token !== process.env.MCP_TOKEN) throw new Error('Invalid token')
+    return {token: token, clientId: 'assistant', scopes: []}
+}
+
+//客户端连接 http://127.0.0.1:3000/mcp
+Application.run(() => ({
+    id: 'clock.app',
+    name: 'Clock',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [ClockController],
+            mcp: httpMCPEntrypoint({port: 3000, authenticate: verifyToken})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `port`、`host`、`path` | `3000`、`'127.0.0.1'`、`'/mcp'` | 监听的位置 |
+| `authenticate` | | `(request) => MCPAuthInfo \| undefined`：客户端的身份认证；抛出错误时以 401 响应，返回 `undefined` 时不认证，照常处理请求 |
+| `allowedHosts`、`allowedOrigins` | 在本机地址上时为本机的名字 | 接受的 `Host` 和 `Origin` 请求头（否则为 403）；`false` 表示不检查 |
+| `legacy` | `'stateless'` | 2025 年协议版本的客户端：以无会话的方式服务，或者用 `'reject'` 拒绝 |
+| `maxRequestBodySize` | 4 MiB | 更大的请求体以 413 响应 |
+| `bus` | 内存中 | 通知的去向，用于在应用的多个实例之间共享 |
+| `listen` | `true` | `false` 表示不打开端口：把 `handler` 挂到其他服务器上 |
+| `serverName`、`serverVersion`、`instructions`、`server`、`listening`、`name`、`middlewares` | | 与 stdio 相同；`server` 是 `node:http` 服务器的选项 |
+
+- 它通过 Streamable HTTP 提供协议：2026-07-28 版本，以及无会话方式的 2025 年版本。
+- 在本机地址上，`Host` 和 `Origin` 请求头会与本机的名字比对，防止 DNS 重绑定攻击：在代理之后时，要列出客户端使用的名字。在其他地址上，除非列出名字，否则不做检查。
+- 应用停止时，正在处理的调用会得到响应，然后端口关闭。
+
+**与 HTTP 适配器共用端口。** 设置 `listen: false`，在 Express 应用的 `before` 钩子中挂载适配器的 `handler`：
+
+```typescript
+import {buildEntrypoints} from 'lakutata/com/entrypoint'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {httpMCPEntrypoint} from '@lakutata/mcp'
+
+//客户端连接时使用的名字（http://localhost:8080/mcp）
+const mcp = httpMCPEntrypoint({listen: false, allowedHosts: ['localhost', '127.0.0.1', 'mcp.example.com']})
+
+export const entrypoint = buildEntrypoints({
+    controllers: [],
+    http: expressHTTPEntrypoint({port: 8080, before: (app): void => void app.all('/mcp', mcp.handler)}),
+    mcp: mcp
+})
+```
+
+挂载的 `handler` 只按给出的名字检查 `Host` 和 `Origin` 请求头；在适配器启动之前和停止之后，它以 503 响应。
+
+## 7. 错误
+
+| 情形 | 客户端收到 |
+|---|---|
+| 工具失败：异常、参数无效、访问被拒绝 | 标记为错误的结果：`errno: message` |
+| 资源或提示词因客户端错误（400 到 499）失败 | 协议错误 `-32602`，消息为 `errno: message`，数据为 `{errno}` |
+| 资源或提示词因其他原因失败 | 协议错误 `-32603` |
+| 未知的工具、提示词或资源 | 协议错误 `-32602`（`Tool nope not found`） |
+| 工具或提示词的名字无效，资源 URI 没有协议名 | 声明类时抛出 `TypeError` |

package/doc/zh/Middlewares.md

@@ -0,0 +1,198 @@
+# Lakutata 中间件与访问控制
+
+中间件在动作前后运行：它在动作之前看到每个请求，在动作之后看到结果。访问控制决定一个请求能不能到达它的动作。两者对所有传输方式都以同样的方式工作。
+
+## 1. 中间件
+
+中间件是一个函数 `(invocation, next) => Promise<unknown>`。它调用 `next()` 让请求继续，并返回请求的结果：
+
+```typescript
+import {type ActionInvocation, Controller, type Next} from 'lakutata/com/entrypoint'
+import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
+
+async function timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
+    const started: number = Date.now()
+    try {
+        return await next()
+    } finally {
+        console.log(`${invocation.action.name} took ${Date.now() - started} ms`)
+    }
+}
+
+@UseMiddlewares(timing)
+class HealthController extends Controller {
+    @GET('/health')
+    public async health(): Promise<string> {
+        return 'ok'
+    }
+}
+```
+
+中间件也可以是一个继承 `Middleware` 并实现 `handle(invocation, next)` 的类。这个类在每个请求的作用域里创建，所以可以注入其他对象：
+
+```typescript
+import {Component} from 'lakutata'
+import {type ActionInvocation, Middleware, type Next} from 'lakutata/com/entrypoint'
+import {Inject} from 'lakutata/decorator/di'
+
+class Metrics extends Component {
+    public record(name: string, milliseconds: number): void {
+        console.log(name, milliseconds)
+    }
+}
+
+export class Timing extends Middleware {
+    //在应用的 components 中声明为 metrics 的组件
+    @Inject('metrics')
+    protected readonly metrics: Metrics
+
+    public async handle(invocation: ActionInvocation, next: Next): Promise<unknown> {
+        const started: number = Date.now()
+        try {
+            return await next()
+        } finally {
+            this.metrics.record(invocation.action.name, Date.now() - started)
+        }
+    }
+}
+```
+
+`invocation` 描述当前请求：
+
+| 属性 | 含义 |
+|---|---|
+| `context` | 请求的上下文（动作中的 `this.context`）。它的 `data`（校验之前的输入）可以修改 |
+| `action` | 动作：`name`、`description`、`groups` 和地址（`route`、`command`、`pattern`） |
+| `container` | 请求作用域的容器，用来获取这个请求的对象 |
+| `signal` | 请求的 `AbortSignal` |
+
+- 不调用 `next()` 直接返回的中间件，会自己回复这个请求：动作不会执行。缓存就可以这样实现。
+- 抛出错误的中间件会让请求失败，效果与动作抛出错误相同。
+- `next()` 只能调用一次：第二次调用会抛出 `MiddlewareNextCalledException`。
+- 中间件对所有传输方式都会执行，包括定时任务。可以用 `invocation.context.type` 区分它们。
+
+## 2. 在哪里声明
+
+| 位置 | 作用于 |
+|---|---|
+| `buildEntrypoints({middlewares})` | 所有动作 |
+| 适配器的 `middlewares` 选项 | 通过这个适配器到达的动作 |
+| 控制器类上的 `@UseMiddlewares(...)` | 这个类及其子类的动作 |
+| 动作选项 `middlewares` | 这个动作 |
+| 方法上的 `@UseMiddlewares(...)` | 这个方法 |
+
+它们按照表中的顺序执行，从第一行（最外层）到最后一行：入口、适配器、控制器类、动作选项、方法。在控制器上，父类的中间件先于子类的执行。最后一个中间件之后，依次是输入校验、访问控制和动作本身。
+
+## 3. 向动作传递数据
+
+中间件常常会得到动作需要的东西，比如发送请求的用户。不要把它放进输入：DTO 在中间件之后才校验输入，还会去掉没有声明的键。应该改用请求的提供者：`@Scoped` 提供者在每个请求中只有一个实例，中间件给它赋值，动作注入的就是同一个实例。
+
+```typescript
+import {Exception, Provider} from 'lakutata'
+import {type ActionInvocation, Controller, type HTTPContext, Middleware, type Next} from 'lakutata/com/entrypoint'
+import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
+import {Autoload, Inject, Scoped} from 'lakutata/decorator/di'
+
+class UnauthorizedException extends Exception {
+    public errno: string = 'E_UNAUTHORIZED'
+
+    public statusCode: number = 401
+}
+
+//每个请求一个实例，第一次使用时自动注册
+@Autoload()
+@Scoped()
+export class CurrentUser extends Provider {
+    public name: string
+
+    public role: string
+}
+
+class Authenticate extends Middleware {
+    public async handle(invocation: ActionInvocation, next: Next): Promise<unknown> {
+        const token: string | undefined = (invocation.context as HTTPContext).request.headers.authorization
+        if (!token) throw new UnauthorizedException('Not logged in')
+        const user: CurrentUser = await invocation.container.get(CurrentUser)
+        //实际应用中要根据令牌查出用户
+        user.name = token
+        user.role = token === 'ada' ? 'admin' : 'user'
+        return await next()
+    }
+}
+
+@UseMiddlewares(Authenticate)
+class ProfileController extends Controller {
+    @Inject(CurrentUser)
+    protected readonly user: CurrentUser
+
+    @GET('/me')
+    public async me(): Promise<{ name: string, role: string }> {
+        return {name: this.user.name, role: this.user.role}
+    }
+}
+```
+
+```text
+$ curl localhost:8080/me -H 'Authorization: ada'
+{"name":"ada","role":"admin"}
+$ curl localhost:8080/me
+{"errno":"E_UNAUTHORIZED","errMsg":"Not logged in"}
+```
+
+## 4. 访问控制
+
+声明了 `acl: true` 的动作，会由入口的访问规则检查。访问规则是继承 `AccessControlRule` 的类，列在 `buildEntrypoints({rules})` 中：
+
+```typescript
+import {Provider} from 'lakutata'
+import {AccessControlRule, ContextType, Controller, type HTTPContext} from 'lakutata/com/entrypoint'
+import {DELETE, GET} from 'lakutata/decorator/ctrl'
+import {Autoload, Inject, Scoped} from 'lakutata/decorator/di'
+
+//第 3 节的提供者，由中间件 Authenticate 赋值
+@Autoload()
+@Scoped()
+class CurrentUser extends Provider {
+    public name: string
+
+    public role: string
+}
+
+//admin 分组的动作只允许管理员访问
+export class AdminRule extends AccessControlRule<HTTPContext> {
+    @Inject(CurrentUser)
+    protected readonly user: CurrentUser
+
+    public get supportContextTypes(): ContextType[] {
+        return [ContextType.HTTP]
+    }
+
+    public async rule(): Promise<boolean> {
+        if (!this.targetAction.groups.includes('admin')) return true
+        return this.user.role === 'admin'
+    }
+}
+
+export class StatsController extends Controller {
+    @GET('/admin/stats', {acl: true, groups: ['admin']})
+    public async stats(): Promise<string> {
+        return 'stats'
+    }
+
+    //只属于这个动作的规则，不需要 acl
+    @DELETE('/drafts/:id', {rule: async (context): Promise<boolean> => (context as HTTPContext).request.headers['x-owner'] === 'yes'})
+    public async removeDraft(): Promise<void> {
+    }
+}
+
+//buildEntrypoints({controllers: [StatsController], rules: [AdminRule], httpActionGroups: {admin: 'Administration'}})
+```
+
+- 访问规则在每个请求的作用域里创建，所以可以注入这个请求的对象，比如中间件赋值过的 `CurrentUser`。
+- 在规则里，`this.context` 是请求的上下文，`this.input` 是校验后的输入，`this.targetAction` 是目标动作（它的 `name`、`groups`），`this.actions` 是该传输方式的全部动作。
+- `supportContextTypes` 列出规则要检查的传输方式，其他传输方式会跳过这条规则。
+- 先按 `rules` 选项的顺序执行各条规则，再执行动作的 `rule` 选项。第一个返回 `false` 的规则会以 `AccessDeniedException` 拒绝请求（errno 为 `E_ACCESS_DENY`，HTTP 上是状态码 403）；抛出错误的规则会以它自己的错误拒绝请求（比如 401）。
+- 动作的 `rule` 选项可以单独使用：没有 `acl` 时，只检查这一条规则。
+- 既没有 `acl` 也没有 `rule` 的动作不做检查。`acl: true` 的动作只要没有规则拒绝就允许访问。
+
+访问控制在中间件和输入校验之后、动作之前执行。要改变整个应用的判断方式，见 [Entrypoint](Entrypoint.md) 第 7 节。

package/doc/zh/Migrations.md

@@ -0,0 +1,178 @@
+# Lakutata 迁移
+
+`synchronize: true` 会在每次连接数据库时，让表结构与实体保持一致：开发时很方便，但在生产环境中并不安全，比如重命名的列会连同数据一起被删掉。生产环境中的表结构通过**迁移**来变更：每个迁移是一个类，只做一处变更，按顺序执行，并记录在数据库中，保证每个迁移只执行一次。
+
+## 1. 一个迁移
+
+迁移实现 `lakutata/orm` 中的 `MigrationInterface`。`up()` 执行变更，`down()` 撤销变更：
+
+```typescript
+import type {MigrationInterface, QueryRunner} from 'lakutata/orm'
+
+export class AddBookAuthor1792161460658 implements MigrationInterface {
+    public name: string = 'AddBookAuthor1792161460658'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query('ALTER TABLE "books" ADD "author" character varying')
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query('ALTER TABLE "books" DROP COLUMN "author"')
+    }
+}
+```
+
+- 迁移的名字以毫秒时间戳（13 位数字）结尾：迁移按时间戳的顺序执行。两个迁移同名会报错。
+- 数据库的 `migrations` 选项列出迁移：迁移类，或者编译后文件的 glob（相对于工作目录）。
+
+  ```typescript
+  import {buildDatabaseOptions} from 'lakutata/com/database'
+
+  export const db = buildDatabaseOptions({
+      type: 'postgres',
+      url: process.env.DATABASE_URL,
+      entities: [],
+      migrations: ['build/migrations/*.js']
+  })
+  ```
+
+- 已执行的迁移记录在名为 `migrations` 的表中（`migrationsTableName` 可以改名）。每个迁移只执行一次，即使它的时间戳早于最后执行的那个迁移。
+
+## 2. `lakutata` 命令
+
+用 `lakutata` 创建的项目自带迁移相关的脚本：
+
+```bash
+npm run migration:generate          # 根据实体的变化生成迁移
+npm run migration:create -- seed    # 一个空迁移，src/migrations/<时间戳>-seed.ts
+npm run migration:run               # 执行待执行的迁移
+npm run migration:show              # 列出已执行和待执行的迁移
+npm run migration:revert            # 撤销最后执行的迁移
+```
+
+这些脚本调用 `lakutata migration <action>`：
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `--dir` | `src/migrations` | 写入迁移的目录（`generate`、`create`） |
+| `--script` | `dev` | 构建并启动应用的 npm 脚本 |
+| `--database` | 所有数据库 | 命令针对的数据库；有多个数据库时，撤销必须指定 |
+| `--transaction` | 数据库的 `migrationsTransactionMode` | `all`、`each` 或 `none`（第 6 节） |
+| `--fake` | `false` | 只把迁移记录为已执行（或已撤销），不真正执行 |
+| `--package` | 当前目录 | 在工作区的哪个包中执行命令 |
+
+`create` 只写一个空迁移，不启动应用。其他操作会带着第 3 节的环境变量运行应用的 npm 脚本：命令由应用自己完成。
+
+## 3. 应用的迁移命令
+
+带着下面某个环境变量启动的应用不会正常启动，而是执行命令：它读取自己的选项，连接数据库，执行命令，然后退出。它的 `bootstrap` 和 `onLaunched` 回调都不会执行，也不会启动任何服务。
+
+| 变量 | 命令 |
+|---|---|
+| `MIGRATION_GENERATE=<目录>` | 把实体与表之间的差异写成一个迁移（第 4 节） |
+| `MIGRATION_RUN=1` | 执行待执行的迁移 |
+| `MIGRATION_REVERT=1` | 撤销最后执行的迁移 |
+| `MIGRATION_SHOW=1` | 列出选项中的迁移：已执行（`[X]`）和待执行（`[ ]`） |
+| `MIGRATION_DATABASE=<名字>` | 命令针对的数据库：它的组件或提供者的名字（默认所有数据库） |
+| `MIGRATION_TRANSACTION=all\|each\|none` | `MIGRATION_RUN` 和 `MIGRATION_REVERT` 使用的事务方式（第 6 节） |
+| `MIGRATION_FAKE=1` | 只把迁移记录为已执行（或已撤销），不真正执行 |
+
+```text
+$ MIGRATION_SHOW=1 node build/App.js
+[db] [ ] Migrations1792161460658
+[db] 1 pending migration
+$ MIGRATION_RUN=1 node build/App.js
+[db] Migration Migrations1792161460658 has been run
+$ MIGRATION_REVERT=1 node build/App.js
+[db] Migration Migrations1792161460658 has been reverted
+```
+
+- 开关变量的值为 `1`、`true` 或 `yes` 时才生效：`MIGRATION_RUN=0` 会让应用照常启动。
+- 命令作用于选项顶层（`components`、`providers`）声明的 `Database` 组件和提供者，每个数据库以它的键作为名字。
+- 命令成功时退出码为 0，失败时为 1。有多个数据库时，`MIGRATION_REVERT` 需要 `MIGRATION_DATABASE`。
+
+## 4. 生成迁移
+
+`MIGRATION_GENERATE` 比较实体与数据库中的表，把差异的 SQL 写成一个迁移：
+
+```text
+$ MIGRATION_GENERATE=src/migrations node build/App.js
+Migration /home/app/src/migrations/1792161460658-db.ts has been generated successfully.
+```
+
+```typescript
+import { MigrationInterface, QueryRunner } from "lakutata/orm";
+
+export class Migrations1792161460658 implements MigrationInterface {
+    name = 'Migrations1792161460658'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            CREATE TABLE "books" (
+                "id" SERIAL NOT NULL,
+                "title" character varying NOT NULL,
+                CONSTRAINT "PK_f3f2f25a099d24e12545b70b022" PRIMARY KEY ("id")
+            )
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            DROP TABLE "books"
+        `);
+    }
+
+}
+```
+
+- 数据库必须能连上，并且已经执行了已有的迁移：差异是根据它当前的表计算的。
+- 文件是 `<目录>/<时间戳>-<数据库名>.ts`，类名取自目录（`src/migrations` 得到 `Migrations<时间戳>`），是 TypeScript 文件。随应用一起编译：`migrations` 选项列出的是编译后的文件。
+- 执行迁移之前先读一遍：重命名的属性会变成删除一列再新增一列，旧列的数据会丢失。必要时修改其中的 SQL。
+- 没有任何变化时，命令什么都不写，并以退出码 1 退出（`No changes in database schema were found`）。
+- 有多个数据库时，每个表结构有差异的数据库各自生成一个文件。给每个数据库的 `migrations` 选项只列出它自己的文件（`'build/migrations/*-db.js'`），否则各个数据库会执行彼此的迁移。
+
+## 5. 启动时执行迁移
+
+除了使用命令，数据库也可以在每次连接时执行待执行的迁移，只要设置 `migrationsRun: true`。此时的顺序是：`dropSchema`（如果设置了），迁移，然后是 `synchronize`（如果设置了）。
+
+- `Database` 组件只连接一次：列在 `bootstrap` 里时，它在应用启动过程中执行迁移。
+- `Database` 提供者每次被解析时都会连接，所以每次都会检查迁移。
+
+组件和提供者还有 `runMigrations({transaction, fake})`、`undoLastMigration({transaction, fake})` 和 `showMigrations()`（返回是否有待执行的迁移）三个方法。
+
+## 6. 事务
+
+数据库的选项 `migrationsTransactionMode`，或者单次命令的 `MIGRATION_TRANSACTION`：
+
+| 方式 | 待执行的迁移…… |
+|---|---|
+| `all`（默认） | 在同一个事务中执行：失败时全部撤销 |
+| `each` | 各自在自己的事务中执行：失败时保留之前已执行的迁移 |
+| `none` | 不使用事务 |
+
+- 在 `each` 和 `none` 方式下，迁移可以设置自己的 `transaction` 属性（`true` 或 `false`）；在 `all` 方式下这样做会报错。
+- PostgreSQL 和 SQLite 在事务中执行表结构的变更。MySQL 和 MariaDB 会立即提交每一处表结构的变更：失败的迁移可能已经执行了一部分变更。
+
+## 7. MongoDB
+
+MongoDB 数据库（`mongodb`、`mongo-embedded`）没有可以比较的表结构：`MIGRATION_GENERATE` 不会为它们生成任何内容，它们的迁移需要手写。不支持 `queryRunner.query()`，要用 MongoDB 的实体管理器来完成工作：
+
+```typescript
+import type {MigrationInterface, MongoEntityManager, QueryRunner} from 'lakutata/orm'
+
+export class RenameTitle1792161460700 implements MigrationInterface {
+    public name: string = 'RenameTitle1792161460700'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        const manager: MongoEntityManager = queryRunner.manager as MongoEntityManager
+        await manager.updateMany('notes', {}, {$rename: {title: 'name'}})
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        const manager: MongoEntityManager = queryRunner.manager as MongoEntityManager
+        await manager.updateMany('notes', {}, {$rename: {name: 'title'}})
+    }
+}
+```
+
+MongoDB 不使用事务执行这些迁移：迁移失败时，之前已执行的迁移，以及它自己在失败前做出的变更，都会保留。