sub2api/issues/plugin-refactor/phase-1.5_devkit/TASK-005_devflow_docs.md

完成报告: [TASK-005] 开发与调试工作流文档

• 完成状态: Success
• 关联任务规格: 链接
• 完成日期: 2026-06-11

1. 任务完成简报

《模块作者指南》新增第 8 章"开发与调试工作流"（251 行），覆盖完整闭环：8.1 脚手架（实测全文输出）→ 8.2 plugintest 单测驱动（API 速览 + 三段真实代码用法）→ 8.3 本地运行（依赖准备/配置/实测启动与优雅关闭日志）→ 8.4 三种观测（结构化日志、admin API curl 实测含 423 合规门注记、前端 /admin/modules 页）→ 8.5 提交前自检（安全网 + bench 阈值四条语义 + wire 重生成坑）→ 8.6 常见坑 8 条表格。指南 465 → 707 行。

2. 衔接处理（消除重复）

原"完整示例"重编号为第 9 章并修正陈旧交叉引用；§7.1 重写（删除已不存在的 newIsolatedRegistry 旧模式，确立 plugintest 为默认入口）；§7.3 预期输出收敛至 8.5；原启用与观测清单压缩为交叉引用。

3. 实测记录（亮点）

• 全部命令实测：脚手架生成（产物已清理）、生成模块 5/5 测试、test-invariants 16.4s、bench compare exit 0、wire 失败复现 + @v0.7.0 重生成 md5 不变；
• 真实服务器运行验证：备份 config.yaml → 启用 job.hello → 构建运行 2 分钟 → 捕获 started/stopped/[Cleanup] 实测日志 → curl 实测 admin API（423 合规门 + 200 模块清单）→ SIGTERM 优雅退出 → 现场完整还原（config md5 一致、临时合规 DB 行删除、二进制/日志清理）；
• 仅静态核对：前端页面渲染（其消费的 API 已实测）、docker-compose.dev 端口映射事实（已在文档如实注明 postgres/redis 默认不映射宿主端口）。

4. 文件变更详情

• 修改: docs/plugin-architecture/MODULE-AUTHOR-GUIDE.md（净增 242 行）；零代码改动；现场零残留（主控 git status 复核）。