sub2api/issues/plugin-refactor/phase-1_plugin-kernel/PHASE_SUMMARY.md

阶段总结报告: Phase-1 插件内核（Plugin Kernel）

• 阶段状态: Completed
• 完成时间: 2026-06-11
• 关联阶段计划: 链接

1. 阶段目标达成情况（对照 PHASE_PLAN §3）

1. ✅ 内核接口按契约实现（签名与 ROADMAP 架构树逐项核对一致），单测覆盖硬性清单全部条目（含 Start 半途失败逆序回滚、Stop ctx deadline 专测，-race 全绿）；
2. ✅ 零行为变更：默认配置下 Phase-0 安全网 42 包全绿；bench-baseline.sh compare 7 个基准 allocs/op 完全一致、ns/op 全在噪声内；
3. ✅ wire v0.7.0 工具生成且复跑字节级一致；启动/优雅关闭含模块阶段日志（runtime.Stop 在 cleanup 并行组首位、先于 Redis/Ent）；
4. ✅ GET /api/v1/admin/modules 可列出全部模块与状态；job.hello 启用后全生命周期测试通过、禁用后零副作用；
5. ✅ 《模块作者指南》入库（含 .gitignore 白名单放行）；CLAUDE.md 更新（Ent 修正 + 插件开发小节 + 结构树）。

2. 任务完成统计

任务ID	任务描述	状态	完成报告
TASK-001	内核包：module/registry	Completed	链接
TASK-002	Host/配置子树/Runtime	Completed	链接
TASK-003	Wire/启动接入 + 插装清单 + hello	Completed	链接
TASK-004	Admin 模块可观测 API	Completed	链接
TASK-005	作者指南 + CLAUDE.md	Completed	链接

总计: 5 个任务全部完成。新增 internal/plugin/（5 文件内核 + 4 文件单测）、internal/modules/（standard 插装清单 + hello 示例）、admin handler、作者指南；对现有代码改动极小且全部纯增量（config.go +41、main.go +10、wire.go +20、handler/routes 各数行、wire_gen.go 工具生成）。

3. 关键技术成果

• Caddy 式进程内插件内核就位：命名空间注册表（init() 注册 + panic 校验）、四段可选生命周期、Host ports 能力面、modules: 配置子树（enabled 三态）、Runtime 状态机（含逆序回滚/逆序关闭）、唯一插装清单 modules/standard/imports.go；
• 新增一个模块 = 新建模块包 + 插装清单加一行 import，核心零改动——Phase-2/3 的迁移底座已通电。

4. 遇到的问题与解决方案

• viper 含点 key 拆层坑：viper.Unmarshal 把 modules.job.hello 错拆两级 → Modules 字段 mapstructure:"-" + viper.Get("modules") 手工提取 + 形状校验；
• 规格与内核语义冲突（未知模块 ID 处理）：架构师裁定以内核为准（格式非法 fail-fast / 合法未注册忽略），规格文件已加注裁定记录；
• 交付物被 .gitignore 忽略：按现有白名单模式补 !docs/plugin-architecture/。

5. 技术债务与待优化项

• make generate 的无版本号 wire 调用因 go.sum 缺 github.com/google/subcommands 失败（预存在，与本阶段改动无关）：建议主线单独 PR go get github.com/google/wire/cmd/wire@v0.7.0 或 Makefile 改带版本调用；
• modules 子树暂不支持环境变量逐键覆盖（viper AutomaticEnv 限制），需要时后续补充；
• CLAUDE.md 既有过时描述（service/ports/ 目录、make wire 目标）与 usage_log.go 残留 gorm tag，留待后续梳理；
• golangci-lint 在 WSL /mnt 盘超时，以 CI lint job 为最终判定。

6. 经验总结与建议

• "接口契约写进 PHASE_PLAN + 实施自由度留给工程师"运转良好：三个实施代理的裁量决定（EnabledByDefault 字段、独立 context、ProviderSet 拆分）都在契约内且有理有据；
• 每任务"主控复跑门禁"的双重验证流程两次发现了值得归档的信息（错误体路径差异、gitignore 问题），建议 Phase-2 保持。

7. 下一阶段准备

• Phase-2（试点迁移：payment.provider + moderation 钩子）就绪，待规划任务清单（按渐进式规划原则，PHASE_PLAN 在阶段启动时细化）；
• 当前全部改动尚未 git commit——建议先按"PR 粒度规划"提交：①Phase-0 安全网（测试+脚本+CI+Makefile）②Phase-1 内核与接入（plugin/modules/wire/main/config）③文档（指南+CLAUDE.md+gitignore），三个独立可 revert 的提交/PR。