旧舟归港，云门初启 · Integrate server preview

.github/workflows/pull-request.yml

@@ -2,6 +2,19 @@ name: pull request
 
 on:
   pull_request:
+    paths:
+      - "CMakeLists.txt"
+      - "CMakePresets.json"
+      - "bindings/node/**"
+      - "cmake/**"
+      - "contracts/**"
+      - "corpus/**"
+      - "include/**"
+      - "models/**"
+      - "oracle/**"
+      - "src/**"
+      - "tests/**"
+      - "tools/**"
 
 permissions:
   contents: read
@@ -22,11 +35,6 @@ jobs:
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
         with:
           node-version: "22"
-      - name: Check the N2 workspace contracts
-        run: |
-          npm ci --ignore-scripts --no-audit --no-fund --omit=optional
-          npm run typecheck
-          npm run test:workspace
       - name: Validate repository and release tooling contracts
         run: python -m unittest discover -s tests/python -p 'test_*.py'
       - name: Bootstrap pinned inputs and prove the dependency cache is complete

.github/workflows/workspace.yml

@@ -0,0 +1,35 @@
+name: workspace
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/**"
+      - "docker-compose.yml"
+      - "package.json"
+      - "package-lock.json"
+      - "packages/**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: workspace-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  node:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "22"
+      - name: Install the exact workspace
+        run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Check types and package contracts
+        run: |
+          npm run typecheck
+          npm test
+      - name: Parse the server Compose definition
+        run: docker compose config --quiet

docker-compose.yml

@@ -0,0 +1,9 @@
+services:
+  light-ocr-server:
+    build:
+      context: .
+      dockerfile: packages/light-ocr-server/Dockerfile
+    ports:
+      - "3000:3000"
+    environment:
+      EXECUTION_MODE: cpu

docs/implementation-status.md

@@ -1,7 +1,7 @@
 # C++ Core 与 Node-API 实施状态
 
 更新时间：2026-07-22<br>
-结论：`@arcships/light-ocr@0.3.4` 与七个依赖包已发布，npm `next`/`latest` 均指向 `0.3.4`。`0.3.0` 交付的 Direct Core ML、Native WebGPU、D112 Auto 与自包含 payload 保持有效；`0.3.4` 修复 N1 CLI ROI 的 native option contract。N2 阶段 1 已按 D107 启动内部 workspace 迁移，但尚未发布 runtime、tiny 或 medium。
+结论：`@arcships/light-ocr@0.3.4` 与七个依赖包已发布，npm `next`/`latest` 均指向 `0.3.4`。`0.3.0` 交付的 Direct Core ML、Native WebGPU、D112 Auto 与自包含 payload 保持有效；`0.3.4` 修复 N1 CLI ROI 的 native option contract。N2 workspace 已包含 runtime、Small facade 与私有 server preview，但尚未发布 runtime、server、tiny 或 medium。
 
 状态含义：
 
@@ -19,6 +19,16 @@
 - `bindings/node/` 暂时保留为 `0.3.x` 兼容发布源。切换前只运行一条 workspace 语义检查，不复制整套原生矩阵。
 - tiny 尚未接入；下一步是消除旧 facade 与 workspace facade 的源码重复，并让 release assembler 能独立产出 runtime + Small meta tarball。
 
+## N2 阶段 2：Server preview
+
+状态：In progress
+
+- 历史 PR #24 的 REST API 已按原约定从 `chatre7/light-ocr-server` 迁回 `packages/light-ocr-server/`，保留来源说明与后续并发上传、优雅停机修复。
+- private `0.1.0` 精确依赖 workspace `@arcships/light-ocr@0.3.4`；当前不发布，也不要求新的 `light-ocr` patch 版本。
+- `/api/v1` 提供 health、info 与 multipart OCR；20 MiB 输入上限、HTTP 层并发拒绝和 `OcrError` HTTP 映射已有 contract tests。
+- Docker preview 复用根 workspace lock，支持 Linux x64/arm64，不再保留历史 `linux/amd64` 强制平台。
+- Workspace PR 使用已发布的 native/model 依赖完成全部包测试和真实 OCR；只有 native/Core 相关路径才进入完整构建，server 不复制原生验证矩阵。
+
 ## 需求验收矩阵
 
 | `requirements.md` §19 条目 | 状态 | 当前证据或缺口 |

docs/monorepo-design.md

@@ -1,6 +1,6 @@
 # light-ocr Monorepo 设计
 
-状态：已接受用于 N2 阶段 1（2026-07-22）。
+状态：阶段 1 已落地，server preview 已提前进入阶段 2（2026-07-22）。
 受众：维护者、贡献者。本文定义 monorepo 的目录结构、包依赖关系、迁移路径和约束，不替代各包自身的实现设计。
 
 ## 1. 动机
@@ -158,10 +158,11 @@ bindings/node/          # @arcships/light-ocr，JS + native addon 混合
 - `bindings/node/` 标记为 deprecated，保留到确认迁移稳定后删除。
 - 此阶段保留 `bindings/node/` 作为 `0.3.x` 发布兼容入口，但只增加一条 workspace 契约检查，不重复运行两套完整原生矩阵；切换发布源之前必须证明 workspace facade 与旧入口的 API、错误类型和真实 OCR 语义一致。
 
-### 5.3 阶段 2：加入 server（N2 完成或 N3 前后）
+### 5.3 阶段 2：加入 server（N2，已启动）
 
-- `packages/light-ocr-server/` 加入 workspace。
-- Dockerfile 使用两阶段构建或从 npm registry 安装依赖。
+- `packages/light-ocr-server/` 已从历史 PR #24 及其独立仓库迁回 workspace，保留原贡献者归属。
+- Server 先以 private `0.1.0` preview 验证 HTTP 契约，不推动 `light-ocr` 版本，也不进入当前 npm release。
+- Preview Dockerfile 从根 workspace lock 安装精确依赖；server 与 runtime 正式发布后再切换为 registry-only production image。
 - 本地开发时 `npm install` 自动 symlink workspace 内的 `light-ocr`，无需先发布。
 
 ### 5.4 阶段 3：加入 tiny、medium（N2 GA）
@@ -175,7 +176,7 @@ bindings/node/          # @arcships/light-ocr，JS + native addon 混合
 
 ## 6. Server Docker 构建
 
-Server 是特殊的包：它既作为 npm 包发布，也作为 Docker 镜像分发。
+Server 是特殊的包：preview 期作为私有 workspace 和 Docker 镜像验证，契约稳定后再同时发布 npm 包与 Docker 镜像。
 
 ### 6.1 Dockerfile 策略
 
@@ -185,11 +186,16 @@ FROM node:22-trixie-slim
 
 WORKDIR /app
 
-# 从 npm registry 安装（生产模式不需要 workspace）
+# Preview 从根 workspace lock 安装，正式发布后可缩为 registry-only image
 COPY package.json package-lock.json ./
-RUN npm ci --omit=dev
+COPY packages/runtime/package.json ./packages/runtime/package.json
+COPY packages/light-ocr/package.json ./packages/light-ocr/package.json
+COPY packages/light-ocr-server/package.json ./packages/light-ocr-server/package.json
+RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund
 
-COPY src/ ./src/
+COPY packages/runtime/src ./packages/runtime/src
+COPY packages/light-ocr/src ./packages/light-ocr/src
+COPY packages/light-ocr-server/src ./packages/light-ocr-server/src
 
 RUN groupadd -r ocr && useradd -r -g ocr ocr
 USER ocr
@@ -198,29 +204,30 @@ EXPOSE 3000
 ENV EXECUTION_MODE=cpu
 ENV QUEUE_CAPACITY=4
 
-CMD ["node", "src/server.js"]
+CMD ["node", "packages/light-ocr-server/src/server.js"]
 ```
 
 ### 6.2 本地开发 vs 生产构建
 
-- **本地开发**：`npm install`（workspace 解析为 `packages/light-ocr/` 的 symlink），直接 `node src/server.js`，改动即时生效。
-- **生产 Docker 构建**：`npm install` 走 npm registry，拉取已发布的 `@arcships/light-ocr`。镜像构建独立于 monorepo。
-- **CI 集成测试**：先 `npm install`（workspace），再 `npm test --workspace packages/light-ocr-server`，验证 server + engine 的端到端行为。
+- **本地开发**：根目录执行 `npm install`，workspace 自动链接三个包；使用 `npm start --workspace @arcships/light-ocr-server`。
+- **Preview Docker 构建**：使用根 `package-lock.json`，把 runtime、Small facade 和 server 源码装入同一镜像；Linux x64/arm64 都使用对应的已发布 native package，不钉死平台。
+- **正式生产构建**：runtime、Small facade 与 server 发布后，可切为 registry-only image，不再复制 workspace 源码。
+- **CI**：workspace 路径使用已发布的 native/model 精确依赖跑类型、HTTP contract 和一条真实 OCR；只有 C++、CMake、native bindings、模型或发布工具变更才进入完整 Core job。
 
 ### 6.3 与 docker-compose 的关系
 
 根目录 `docker-compose.yml` 引用 `packages/light-ocr-server/Dockerfile`：
 
 ```yaml
 services:
-  light-ocr-api:
+  light-ocr-server:
     build:
       context: .
       dockerfile: packages/light-ocr-server/Dockerfile
     ports:
       - "3000:3000"
     environment:
-      - EXECUTION_MODE=cpu
+      EXECUTION_MODE: cpu
 ```
 
 ## 7. 约束