Skip to content

wayfinder 地图:重写为 Go + 静态 SPA(迁移蓝图) #88

Closed
8 of 8 issues completed
Closed

Description

@JonasGao

Destination

weekly-reporter 迁移蓝图定稿:从 Next.js 单体迁移到 Go 单二进制(chi + modernc.org/sqlite + sqlc,go:embed 静态资源)+ React/Vite SPA(React Router v7 库模式),严格行为对等(HTTP API 契约、skills、e2e、NDJSON 事件契约全部冻结),沿用现有 SQLite 与 schema。蓝图以 docs/adr/ 新 ADR 系列 + docs/migration-blueprint.md(索引 + 施工顺序 + 切换 runbook)交付。地图走完 = 开工前没有任何未决问题。

Notes

  • 单用户自托管个人系统(PRODUCT.md);域语言中文,CONTEXT.md 术语与 avoid-list 冻结,重写期间不得改名。
  • 严格对等是地图级不变量:57 个 API 路由契约(含 skills 的 PAT 调用与 {error,code} 响应形状)、e2e 行为、NDJSON 10 事件契约全部不变;唯一允许的 additive 变更:collect 的 'use server' action 变成新路由。
  • 本 effort 纯规划(终点 = 蓝图),不携带施工;施工走正常 feature 迭代。
  • 写 ADR 用 domain-modeling skill;ADR 入 docs/adr/(顺延编号)。
  • HITL 轮次用户偏好 answer-board 网页作答(/answer-board-delivery,持续模式,局域网地址)。
  • 架构盘点基线(charting 时由 Explore agent 产出):57 路由 handler 全纯 HTTP、15 页面 12 个已是 use client、无 cookie/session(localStorage Bearer + withAuth)、26 表 / 41 SQL 迁移 + __drizzle_migrations 账本、NDJSON 生成引擎是最大移植风险。

Decisions so far

  • 基线决策:动机、终点、对等边界与技术栈选型: 动机=单二进制+内存;规划终点;严格对等(契约/skills/e2e 冻结);沿用 SQLite+schema;React+Vite;chi;modernc.org/sqlite;sqlc;同仓双栈一次性切换;React Router v7;go:embed 单二进制;ADR 系列+blueprint.md。

  • 调研:drizzle 迁移账本的 Go 兼容策略: 冻结校验 + 同账本前缀应用器——serve 只读校验账本在冻结头部(41/41),唯一写账本方是显式 wr db migrate 子命令(sha256 + journal when,按序应用);不复制 drizzle 的 max(created_at) 光标、不把 0017-19 修复搬进启动。现实坑:0002-0010 是旧式 16 位哈希且 0002 哈希对应重写前内容、3 处 when 倒挂、go:embed drizzle/meta 会漏 _journal.json(需显式文件模式,embed 包放仓根);Go 连接串需 _pragma=foreign_keys(1)&_pragma=busy_timeout(5000) 对齐 better-sqlite3 默认。详证:research/drizzle-journal-compat 分支 docs/research/drizzle-journal-compat.md。

  • 调研:Go AI 客户端与 NDJSON 生成引擎移植路径: 官方 SDK 只当传输层(anthropic-sdk-go v2 NewStreaming+Accumulate、openai-go v3 Responses.NewStreaming),统一 adapter 与多步 tool-loop 自建;openai-compatible 走裸 SSE 直读 reasoning 字段、不移植标记 hack;明确禁用 BetaToolRunner(表达不了 hasToolCall、消息线程归属与 ADR-0008 冲突)。坑:anthropic-sdk-go 默认 anthropic-version 2026-10-21 会拒 temperature/top_p/top_k,必须钉回 2023-06-01;stopWhen 是 OR 且在工具执行后评估——无效的 propose_final_report 调用也会停轮;跨轮 transcript 重放只含 user/assistant text parts。详证:research/go-ai-engine-port 分支 docs/research/go-ai-engine-port.md。

  • 调研:sqlc + modernc sqlite + chi 数据栈工作流: 配方定稿——合并后的 schema.sql(去反引号)作 sqlc schema 输入、时间戳一律 int64 毫秒、database/sql + modernc、chi 布局 trace 全局中间件 + auth 挂 /api、静态资源与迁移 SQL 用 go:embed all:。已实证修正两点:可空 JSON 列必须 pointer: true(生成 *json.RawMessage,显式 go_type 非指针会 Scan NULL 失败,全库 7 个可空 JSON 列适用);chi middleware.RequestID v5.5.0 只写 context 不设响应头,trace 响应头仍需自写中间件。迁移排序不能靠文件名(0012 倒挂实证),必须按 _journal.json。详证:research/go-datastack-workflow 分支 docs/research/go-datastack-workflow.md。

  • 原型:Vite SPA 壳切片(去 Next 化成本验证): 机械替换实证——alias @→src + 95 行 shim 壳(共 ~200 行新增)零改 src/ 跑通 login+timeline 双认证模式全绿;Geist=fontsource 自托管挂同名变量(globals.css 零改动)、build-info=根脚本模式照搬;坑:workspace 无 packages: 静默吸安装、Vite 需 dedupe 防双 React、Tailwind 需显式 @source、RR v8.5.1 已出、Next 16 单 dev 锁、authEnabled 须挂载前无头探测 verify(200=关/401=开,零新增 API)。用户偏好(供定稿票):next 依赖直接真替换、web/ 进 workspace、RR 钉 v7。详证:prototype/vite-spa-shell 分支 docs/prototype/vite-spa-shell.md。

  • 原型:Go 生成引擎垂直切片(NDJSON + tool-loop + 停止): 能对齐——openai-go/v3 Responses 适配 + 自建循环 + 移植持久层,Go 守两条 generation 路由其余反代 Next,10 种线事件/stopWhen 精确语义(恰 6 步、工具执行后判停)/500ms 节流落库/停止·断连·失败三路径/跨写者 Accept 全链路在现有 UI(零 src/ 改动、0 console errors)验证。修正两调研:时间戳是秒非毫秒、openai-go v3 包路径;新坑:UTF-16 计长贯穿全部字符预算、tool-input 事件需自维护 item_id→call_id 映射、续轮只带增量 output(previous_response_id 不被兼容代理支持时需 items 回放开关)、nil slice→null 会被前端 publicSummary 校验丢弃。真实模型端点待本地代理(:4000 宕机)恢复补跑,已列 定稿:迁移蓝图与施工顺序(ADR 批次 + blueprint.md + 切换 runbook) #96 集成测试。详证:prototype/go-gen-engine 分支 docs/prototype/go-gen-engine.md。

  • 评审:测试与 e2e 基建迁移方案: 8 决议——e2e 只跑生产单二进制且构建入口与发布共享(make build,next-server.ts→go-server.ts,超时 5→2min);E2E_SERVER_MODE/E2E_BUNDLER/NODE_OPTIONS 模式矩阵全退役;/api/e2e/fixtures 原样移植 Go、scripted-AI 留 Node(Go openai-compatible 须保持 /chat/completions 消息形状——marker 协议依赖;现有 e2e 零改动通过=引擎验收);WR_AUTH_DISABLED 同名同值 boot 读一次、XDG 同名沿用、preparePassword 保留;cgroup wrapper 原样保留,memory.peak 兼作「内存不劣于 Next 版」量化验收(基线 6.1–6.2G),workers/上限调整 cutover 后实测;单测边界=测试跟着代码走(33 个 route.test→Go httptest 同用例集、被 client import 的留 vitest);验收时点两段式+预切换演练(施工期 Go httptest 为准、全 57 路由就绪后全套 e2e 对 Go 演练、cutover 门槛=全量 e2e 零改动跑绿、cutover 后删 TS server 测试)。

  • 定稿:迁移蓝图与施工顺序(ADR 批次 + blueprint.md + 切换 runbook): 蓝图本体交付——ADR-0025–0030 + docs/migration-blueprint.md(main 7726bd3)。9 项定稿(7 按推荐 + 2 用户偏离):后端 B0–B6 按域串行、生成引擎殿后 B6;SPA 串行殿后(B7 整体迁移,内部按页分 PR);仓根 module github.com/dev-zapi/weekly-reporter + cmd/wr + internal/;collect 增补 = 两条 POST 1:1 镜像 action(200 + 内嵌 error 形状);dev 终态 dev-api/dev-web 两 target;切换后迁移 = 手写 SQL + wr db new + corpus lint;cutover 单 PR 无观察期(回滚 = git revert,全量 e2e 绿为唯一安全线);build-info 双侧(web 脚本 + Go ldflags)、vitest→Go 随域批次同 PR 走、check:skills 原样保留、blueprint 七节结构。雾区六项全部出雾落档。地图至此走完,施工入口 = blueprint.md §5。

Not yet specified

(空——雾区六项已全部由 定稿票 收进蓝图,地图走完。)

Out of scope

  • 产品功能变更或新功能:对等冻结,重写期间不加产品能力
  • HTTP API 契约重设计与 skills 重新生成:基线决策已拒(严格对等)
  • schema 重设计与数据迁移:基线决策已拒(沿用现有库)
  • 多用户/协作/多租户:PRODUCT.md 持久边界
  • 性能调优专项:内存动机只要求"不劣于 Next 版",不做 benchmark 工程

Activity

  1. JonasGao commented on Nov 5, 2026

    @JonasGao
    CollaboratorAuthor

    地图走完。 最后一张票 定稿:迁移蓝图与施工顺序 已关闭:ADR-0025–0030 + docs/migration-blueprint.md 落 main(7726bd3),雾区清空,开工前无未决问题。

    8 张票的路线:基线决策(#89)→ 三调研(#90/#91/#92,子代理并行)→ 两原型(#93/#94,风险实证消除)→ 测试基建评审(#95)→ 蓝图定稿(#96)。

    施工走正常 feature 迭代,入口 = docs/migration-blueprint.md §5(B0 骨架起步)。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions