Repository navigation
Description
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 v3Responses.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 列适用);chimiddleware.RequestIDv5.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
JonasGao commentedon Nov 5, 2026
地图走完。 最后一张票 定稿:迁移蓝图与施工顺序 已关闭: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 骨架起步)。docs: add Go + SPA migration blueprint with ADR series 0025-0030