feat(workbench): migrate the local workspace to FastAPI and React

.gitignore

@@ -12,6 +12,10 @@ dist/
 build/
 *.egg-info/
 notes/
+node_modules/
+frontend/coverage/
+frontend/playwright-report/
+frontend/test-results/
 .env
 .env.*
 *.sqlite

README.md

@@ -72,6 +72,8 @@ For an isolated installation used outside this source checkout, see the
 
 Run `reposteward web` for the [read-only local workbench](docs/local-workbench.zh-CN.md):
 project guides, task continuity, review evidence and diagnostics in one browser window.
+The FastAPI backend serves a bundled TypeScript/React frontend. Source development
+requires Node 22.12+ and npm; installed release wheels do not require Node.
 `reposteward version` reports installation metadata; `reposteward doctor --local`
 checks configuration sources and database compatibility without authentication or migration.
 

docs/local-workbench.zh-CN.md

@@ -27,7 +27,7 @@ reposteward overview refresh
 
 | 页面 | 可以完成的事 | 事实边界 |
 | --- | --- | --- |
-| 今日待处理 | 跨项目查看待办、来源时间、未知/省略和下一步，跳入任务 | 复用 overview；缓存不是实时 GitHub 状态 |
+| 维护总览 | 跨项目查看待办、来源时间、未知/省略和下一步，跳入任务 | 复用 overview；缓存不是实时 GitHub 状态 |
 | 项目空间 | 查找项目、切换 worktree、查看角色/分支/HEAD、按关注点读导览和代码依据 | 导览过期时要求重新扫描；代码文字不执行 |
 | 任务接续 | 查看最近任务尝试、目标/验收、未完成工作、决定、阻塞，复制接续数据 | 外部任务复用 CLI/MCP 的预算与适用性核对；维护任务显示原 Context Pack/Checkpoint |
 | 审阅依据 | 查看验证适用性、历史状态、任务轨迹和来源 | 历史通过/合并判定不是新的提交或合并授权 |
@@ -55,25 +55,49 @@ API 没有 CORS 授权或写操作，拒绝任意文件路径和跨项目任务
 文本显示，页面使用 CSP 限定脚本和资源。接口重新核对登记身份与工作区绑定。
 已加载的配置文件变化会要求重启；新增配置层也应重启后重新核对生效配置。
 
-这是单机维护入口，使用标准库 HTTP 服务的受限适配层，不提供公网部署、反向代理、
-远程账户或多用户隔离。标准库 HTTP 服务本身只提供基础检查，本项目的固定路由、
-会话和请求边界不能被解释为面向公网的服务器方案。
+这是单机维护入口，使用 FastAPI + Uvicorn 的本地适配层。启动一个服务进程，
+前后端同源；默认不会启用反向代理头信任、多进程 worker 或远程账户隔离。
 
 不存在的数据库不创建，旧数据库不由网页迁移。需要升级时退出相关写入客户端，按
 [升级与备份说明](state-upgrades.zh-CN.md)操作，再启动工作台。更换安装参见
 [独立安装说明](local-installation.zh-CN.md)。
 
 ## 接口与验证
 
-`workbench.Workbench` 组合现有只读应用服务；`web_server` 仅负责本机 HTTP 边界。
-前端调用 `/api/overview`、`projects`、`workspace`、`code`、`tasks`、`task`、`review`
-和 `settings`。接口只接受声明参数，项目/工作区/任务均使用登记 ID；不暴露 Pipeline、
+`workbench.Workbench` 组合现有只读应用服务；`web_api` 提供 FastAPI 查询与 Pydantic
+契约，`web_server` 管理本机 socket 与服务生命周期。React 前端调用 `/api/v1/overview`、
+`projects`、`workspace`、`code`、`tasks`、`task`、`review` 和 `settings`。
+旧 `/api/*` 读取入口保留兼容；新接口使用 `data/meta` 响应。
+接口只接受声明参数，项目/工作区/任务均使用登记 ID；不暴露 Pipeline、
 SQL、shell、原始配置或任意文件服务。没有新增网页任务表或另一套状态机。
 
 回归测试覆盖会话/请求来源、固定路由、写方法拒绝、跨项目隔离、绑定变化、旧库、
 读取不变性以及 CLI/MCP 与网页查询的一致性。浏览器交互与打包检查在加固验证容器中
 执行；用于浏览器验证的额外工具不成为日常安装依赖。
 
-设计依据：[Python HTTP 服务](https://docs.python.org/3.12/library/http.server.html)、
+## 前端开发与分发
+
+前端源码在 `frontend/`，采用 TypeScript、React、React Router、TanStack Query 和 Vite。
+项目选择进入浏览器路由；Query 缓存只代表本地读取缓存，不能替代 GitHub 观测时间。
+切换项目后旧请求结果不会进入新项目页面。
+
+源码开发需要 Node 22.12+ 与 npm。`uv sync --locked` 的构建步骤安装锁定前端依赖，
+从 FastAPI 导出 OpenAPI、生成 TypeScript 类型并构建静态页面；`uv build` 将页面与
+逐文件摘要清单打入 wheel / sdist。已构建发行包的日常安装和运行不需要 Node。
+构建使用清理后的环境，不把 GitHub 凭据传给 Node；依赖脚本默认禁用。
+
+`frontend/openapi.json` 和 `frontend/src/api/generated/schema.ts` 是生成契约；
+后端协议测试核对 OpenAPI 漂移。`npm run check` 在前端目录执行类型、ESLint 和交互检查，
+Python 回归也包含这项检查。测试应在加固 verifier 中运行。构建产物缺失或摘要
+不匹配会明确失败，避免安装包静默使用旧页面。
+
+需要热更新时，先启动 `reposteward web --port 8787`，在 `frontend/` 运行
+`npm run dev`。浏览器打开 `http://127.0.0.1:5173/#session=<终端链接中的会话>`，
+会话仅由浏览器携带；不要将它设置成 Vite 环境变量或写入文件。开发代理固定在
+127.0.0.1:5173，校验来源后将 `/api/` 转发到本机后端。后端端口可通过
+`REPOSTEWARD_DEV_BACKEND=http://127.0.0.1:<port>` 指定。正式服务仍直接提供打包页面。
+
+设计依据：[FastAPI](https://fastapi.tiangolo.com/tutorial/bigger-applications/)、
+[Vite 后端集成](https://vite.dev/guide/backend-integration)、
 [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy)、
 [Fetch Metadata](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Site)。

frontend/eslint.config.mjs

@@ -0,0 +1,11 @@
+import js from "@eslint/js";
+import { defineConfig } from "eslint/config";
+import tseslint from "typescript-eslint";
+
+export default defineConfig(
+  { ignores: ["dist/**", "src/api/generated/**", "coverage/**"] },
+  {
+    files: ["**/*.{ts,tsx}"],
+    extends: [js.configs.recommended, tseslint.configs.recommended],
+  },
+);

frontend/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>RepoSteward · 本地工作台</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>