update

specs/006-module-hook-refactor/quickstart.md

@@ -0,0 +1,44 @@
+# Quickstart: Module Hook Refactor
+
+1) 检出分支并安装依赖
+```bash
+git checkout 006-module-hook-refactor
+/home/rogee/.local/go/bin/go test ./...
+```
+
+2) 定义模块 Hook
+```go
+func init() {
+    proxy.RegisterModule(proxy.ModuleRegistration{
+        Key: "npm",
+        Handler: proxyHandler,
+    })
+    hooks.MustRegister("npm", hooks.Hooks{
+        NormalizePath:   myNormalize,
+        ResolveUpstream: myResolve,
+        RewriteResponse: myRewrite,
+        CachePolicy:     myPolicy,
+        ContentType:     myContentType,
+    })
+}
+```
+
+3) 迁移逻辑
+- 读取 `internal/proxy/handler.go` 里的类型分支，对应迁移到模块 Hook。
+- 更新模块单元测试验证缓存、路径、响应重写等行为。
+
+4) 验证
+```bash
+/home/rogee/.local/go/bin/go test ./...
+```
+- 针对迁移模块执行“第一次 miss → 第二次 hit”端到端测试。
+- 触发缺失 handler/panic，确保返回 `module_handler_missing`/`module_handler_panic`。
+
+5) 诊断检查
+```bash
+curl -s http://localhost:8080/-/modules | jq '.modules[].hook_status'
+```
+- 确认新模块标记为 `registered`，未注册模块显示 `missing`，legacy handler 仍可作为兜底。
+- 如果需要查看全局状态，可检查 `hook_registry` 字段，它返回每个 module_key 的注册情况。
+- `hubs[].legacy_only` 为 `true` 时表示该 Hub 仍绑定 legacy 模块；迁移完成后应显式设置 `[[Hub]].Module`。
+- 启动阶段会验证每个模块是否注册 Hook，缺失则直接退出，避免运行期静默回退。