SDK、Server、CLI 与 Web UI

统一能力模型

Embedded SDK、本地 Server API、CLI 和 Web UI 共享同一领域接口与错误模型。任何交付界面都不能直接修改 Runtime 文件或跳过事务、权限和 Merge Plan。

主要领域能力包括：

Database Open、Close、Check、Backup 与 Index Rebuild；
受管理 Database Create/Delete 与现有 Runtime Database Connect/Disconnect；
Collection、Schema、Index 与 Reference；
Query、Mutation 与 Transaction；
Workspace Init、Update、Status、Plan 与 Apply；
User、Role、Credential 与 Audit；
Transaction Event 与健康状态。

TypeScript SDK

TypeScript SDK 是主要编程接口，提供 Embedded 与 Remote 两种连接方式：

const embedded = await openDatabase({ path, credentials })
const remote = await connectDatabase({ endpoint: "http://127.0.0.1:3000", credentials })

两种连接返回相同的高层 Database API。Collection 使用类型安全 Document 风格：

const projects = db.collection<Project>("projects")
 
const active = await projects.find({
  where: {
    op: "and",
    conditions: [
      { field: "status", operator: "eq", value: "active" },
      { field: "priority", operator: "gte", value: 3 },
      { field: "tags", operator: "contains", value: "database" },
    ],
  },
  orderBy: [{ field: "createdAt", direction: "desc" }],
  select: ["title", "status", "createdAt"],
  limit: 20,
})

事务使用 callback，并可以跨 Collection：

await db.transaction(async (tx) => {
  await tx.collection<Project>("projects").patch(projectId, {
    status: "completed",
  })
  await tx.collection<Event>("events").insert({
    projectId,
    type: "completed",
  })
})

SDK 还提供 Workspace API：

await db.workspace.update(path)
let plan = await db.workspace.planMerge(path)
plan = resolveMergeConflict(plan, conflictId, resolution)
await db.workspace.applyMerge(plan)

Local Server 与 HTTP API

Local Server 作为 Writer Host 打开数据库，提供：

Versioned HTTP JSON API；
流式查询和大结果分页；
Server-Sent Events 事务事件流；
Web UI 静态资源；
健康、完整性和 Writer Lock 状态；
其他语言可以实现的公开协议描述。

HTTP API 与 Embedded SDK 使用相同的操作、错误代码、版本冲突和事务语义。需要双向实时交互的界面可以使用 WebSocket，但普通提交事件优先使用 SSE。

当前 Versioned API 位于 /v1，包含 Health、Metadata、Query、Query Plan、Mutation Changeset、Remote Snapshot Transaction、Schema、Check、SSE Event、Audit、User Role、Credential、Token、Session、Index Rebuild、Snapshot、Workspace 完整流程以及多数据库管理。POST /v1/databases/attach 可以把 Local Server 主机上的既有 Runtime Database 目录连接到管理列表；请求需要默认数据库 Owner Credential，并使用目标数据库 Credential 完成目标鉴权和完整性检查。连接保存规范化后的真实路径而不复制文件，DELETE /v1/databases/{id} 对连接数据库只断开 Writer Host 和删除注册信息，不删除源目录。/v1/meta 同时返回 Writer Lock、Prepared WAL、受限状态、Snapshot 和 Catalog Version，但不返回物理路径或秘密。数据库列表只向已通过控制面鉴权的管理界面返回连接数据库路径；目标 Credential 永远不会持久化到注册表。/v1/openapi.json 提供带请求 Schema、认证和错误响应的 OpenAPI 3.1 机器契约。JSON 请求默认限制 1 MiB；重复请求超过 Server 配置预算时返回 RATE_LIMITED 和 Retry-After。

CLI

CLI 是人和 Agent 都可以使用的稳定接口，支持人类可读与 JSON 输出：

md-db-engine serve <database> [--open]
md-db-engine init scan <vault> [--output <external-directory>]
md-db-engine init preview <vault> --config <file> [--plan <external-file>]
md-db-engine init apply <vault> --plan <file> --database <path> --yes
md-db-engine init --workspace <path> --database <path> --yes
md-db-engine query --database <path> --collection <name>
md-db-engine workspace export|update|status --database <path> --workspace <path>
md-db-engine merge plan|apply --database <path> --workspace <path>
md-db-engine check --database <path>
md-db-engine index rebuild --database <path> --yes
md-db-engine backup --database <path>
md-db-engine restore --database <path> --snapshot <id> --target <new-path> --yes
md-db-engine user create|disable|list|rotate

知识库迁移的 Scan 和 Preview 是只读操作，输出文件与 Plan 必须位于知识库外部；Apply 需要显式确认，并返回外部 Backup 路径、导入数量、pending 数量和 Collection 分布。兼容 Init、Update 和 Merge 必须同时允许非交互参数，Agent 不能依赖模拟终端按键完成操作。危险选择需要显式参数和结构化确认对象。

Web UI

Web UI 是类似 phpMyAdmin 的数据库管理器，不是 Markdown 编辑器。它通过 Local Server API 提供：

数据库、Collection、Record、Schema 和 Index 浏览；
受管理数据库创建、可恢复删除，以及现有 Runtime Database 目录的连接和无损断开；
Query Builder、查询结果、分页和执行计划；
Runtime Record 创建、修改和删除；
Transaction Changeset 预览；
Workspace Update、状态与隐藏目录诊断；
Merge Plan、删除影响、冲突解决与 Apply；
User、Role、Credential 和审计管理；
WAL、锁、索引、完整性、备份和健康状态。

Web UI 修改权限时使用管理 API；修改普通数据时使用 Runtime Mutation API；提交 Workspace 时使用 Merge API。Query 支持分页与 Explain Plan，危险的删除、Schema、Index、Role、Transaction 和 Merge 操作需要显式确认；Restore 只提示管理员停止 Server 后使用 CLI 写入新目录。三条路径共享同一权限与事务引擎。

浏览器不能直接读取 Server 文件系统。连接既有数据库时，Owner 在 Web UI 中输入 Local Server 主机上的绝对目录；Server 解析 realpath、检查 .mddb/state.json、打开唯一 Writer Host，并验证目标数据库。非数据库 Markdown 文件夹应当继续使用 Workspace Init，而不能作为已初始化 Runtime Database 连接。

错误模型

所有接口返回稳定错误代码、用户说明、机器可读详情和可执行操作。错误类别至少包括：

AUTHENTICATION_FAILED
PERMISSION_DENIED
WRITER_LOCKED
SCHEMA_INVALID
RECORD_INVALID
VERSION_CONFLICT
MERGE_CONFLICT
WORKSPACE_BASE_INVALID
PLAN_STALE
TRANSACTION_ABORTED
DATABASE_CORRUPTED
REQUEST_TOO_LARGE
RATE_LIMITED

错误不能只返回自由文本。Web UI、CLI 与 Agent 应当能够根据同一错误详情采取一致操作。