企业官网建设流程全解析

PAUL（Plan-Apply-Unify Loop）是一个面向 Claude Code 的结构化 AI 辅助开发框架，用"计划—执行—统一"循环保证每个任务都闭环完成。本指南带你快速看懂 PAUL 扩展点（Extension Points）的 5 个插件注入点，手把手教你构建自定义集成。

一、PAUL 扩展点是什么：插件注入的基本原理

PAUL 的核心工作流由一组 markdown 工作流文件驱动，分布在 src/workflows/ 目录下。每个工作流文件的末尾都有一个预留的## Extensions区块，由集成安装器（integration installer）统一管理，开发者无需手动修改核心流程：

## Extensions <!-- Extensions are managed by integration installers. Do not edit manually. -->

扩展机制只有三个关键词：

1. 注入（Inject）：安装器把插件声明的@引用注入到指定工作流文件的 Extensions 区块
2. 隔离（Isolation）：每次注入都包裹在<!-- 名称 -->注释块中，互不干扰
3. 后置（After）：扩展永远在核心步骤全部执行完之后才触发，绝不打断核心行为

完整扩展点目录见 src/references/extension-points.md，它是 PAUL 扩展点的权威清单——如果某个扩展点没有列在其中，它就不存在。

自定义集成的三步集成路径

二、PAUL插件注入点全览：5大扩展点清单

下表是全部 5 个扩展点总览（源自 extension-points.md 扩展点总览表）：

💡 记忆口诀：PLAN 管计划、APPLY 管执行、UNIFY 管闭环、VERIFY 管验收、TRANSITION 管收尾。

三、逐个拆解：每个扩展点的触发时机与可用上下文

1. PLAN 注入点：计划就绪后的执行前分析

触发时机：计划创建完成、通过校验、并与 PROJECT.md 和 STATE.md 的决策完成一致性检查之后。

此刻可读到的上下文：

• .paul/phases/{NN}-{name}/{NN}-{plan}-PLAN.md—— 刚刚创建的计划
• .paul/STATE.md—— 已更新计划位置
• .paul/PROJECT.md、.paul/ROADMAP.md—— 项目约束与阶段结构

适合构建的集成：计划分析插件（捕获任务数、预估范围、检查点数量，用于项目健康仪表盘）；依赖检查插件（在 APPLY 开始前验证计划中引用的文件是否真实存在）。

2. APPLY 注入点：全部任务合格后的执行后钩子

触发时机：计划中所有任务都完成了执行，并各自通过了 Execute/Qualify（执行→对照规格验证）循环，所有检查点解决之后。

此刻可读到的上下文：

• files_modified中列出的所有文件（已创建或更新）
• 执行日志：任务状态、验证结果（PASS/GAP/DRIFT）、偏差记录
• 原始 PLAN.md，可与实际构建内容交叉比对

适合构建的集成：构建产物插件（打包或快照本次构建内容，用于部署跟踪）；代码质量插件（在宣告 APPLY 完成前对修改过的文件跑 lint/静态分析）。

3. UNIFY 注入点：闭环完成后的日志与指标采集

触发时机：计划与实际对账完成、SUMMARY.md 创建、STATE.md 更新、阶段完成时 ROADMAP.md 更新之后。这是信息最完整的注入点。

此刻可读到的上下文：

• {NN}-{plan}-SUMMARY.md—— 实际构建内容的完整记录
• 全量更新的 STATE.md、更新阶段进度的 ROADMAP.md
• 所有被修改的源码文件（最终状态）

适合构建的集成：内容流水线插件（读取 SUMMARY.md，提取构建元数据写入.paul/build-logs/）；指标插件（计算计划准确率：计划任务数 vs 实际任务数、偏差趋势、交付速度）。

4. VERIFY 注入点：UAT 验收后的质量门禁

触发时机：基于 SUMMARY.md 验收标准生成的 UAT 检查单走完、用户逐项测试、结果（pass/fail/partial/skip）记录、判定结果生成之后。

此刻可读到的上下文：

• UAT 结果：每条标准的通过情况与用户反馈
• .paul/phases/{NN}-{name}/uat-{plan}.md—— 记录的问题（如有）
• 诊断分类：问题被归类为 intent（意图）/ spec（规格）/ code（代码）

适合构建的集成：QA 报告插件（把 UAT 结果写入结构化测试报告，作为审计留痕）；问题跟踪插件（从失败的 UAT 项在外部系统自动创建 issue）。

5. TRANSITION 注入点：阶段收尾时的报告与通知

触发时机：阶段内所有计划验证完成、PROJECT.md 随验证过的需求演进、STATE.md 指向下一阶段、ROADMAP.md 标记完成、git 提交创建、三份文件状态一致性验证之后。

此刻可读到的上下文：

• 该阶段所有 SUMMARY.md 文件
• 演进后的 PROJECT.md、指向下一阶段的 STATE.md、标记完成并带时间戳的 ROADMAP.md
• 本阶段的 git commit hash

适合构建的集成：阶段报告插件（汇总所有计划摘要、决策、遗留问题生成阶段完成报告）；通知插件（阶段完成时向 Slack、邮件或项目管理工具发送通知）。

四、插件清单编写：manifest 如何声明注入目标

根据 SPEC 规范，插件在自己的manifest.json中声明扩展点目标。声明由三部分组成（见 extension-points.md 插件使用示例）：

声明示例：

{ "extensions": [ { "target": "{paul_framework}/workflows/unify-phase.md", "section": "extensions", "inject": "@content-build-log.md — Capture build log at unify" } ] }

安装器随后把引用注入到## Extensions区块，并用注释块隔离，形如：

## Extensions <!-- Extensions are managed by integration installers. Do not edit manually. --> <!-- CONTENT-PIPELINE --> @content-build-log.md — Capture build log at unify <!-- /CONTENT-PIPELINE -->

@content-build-log.md就是你编写的扩展指令文档——PAUL 执行到该区块时读取并遵循其中的说明。想先体验类似的真实集成，可以参考 SonarQube 质量扫描集成（见 sonarqube-integration.md）与 quality-gate.md 工作流。

五、扩展开发的 5 条硬性规则

来自 extension-points.md 规则章节，逐条遵守才能让你的插件"稳"：

1. 扩展在核心工作流所有步骤之后触发，绝不打断核心行为
2. Extensions 区块永远是工作流文件的最后一个区块
3. 每个插件必须使用注释块隔离：<!-- 名称 -->/<!-- /名称 -->
4. 插件永不修改核心工作流内容——只能通过扩展点新增
5. extension-points.md 是权威清单，不在清单内的扩展点一律视为不存在

六、实战：为 UNIFY 构建构建日志集成

以最典型的"内容流水线"场景为例，走一遍完整流程：

1. 选择注入点：需要"每个计划闭环后记录构建日志"→ 选 UNIFY（unify-phase.md），因为此时 SUMMARY.md 已包含完整构建记录
2. 编写扩展文档content-build-log.md：指示"读取 SUMMARY.md，提取构建内容、关键决策、可教学洞察，写入.paul/build-logs/的结构化日志"
3. 在 manifest.json 中声明注入目标为workflows/unify-phase.md
4. 运行安装器：引用被自动注入 Extensions 区块，带注释隔离，后续升级 PAUL 也不会丢失

其他场景快速匹配：

• 想让静态扫描结果进入闭环 → APPLY 注入点 + config.md 集成模板
• 想让验收失败自动生成工单→ VERIFY 注入点
• 想让阶段完成自动发通知→ TRANSITION 注入点
• 想强制专项技能被调用→ 不需要写插件，直接配置 SPECIAL-FLOWS 专项工作流集成

七、开始你的第一个 PAUL 自定义集成

动手前对照这份清单：

• 已安装 PAUL 并跑通一次完整循环：/paul:init→/paul:plan→/paul:apply→/paul:unify（安装方式见 README.md）
• 已通读 extension-points.md，确认目标注入点在清单内
• 已写好消息注入用的 markdown 扩展文档（@xxx.md）
• 已在 manifest.json 声明target/section/inject
• 注入后检查：Extensions 区块有注释隔离、位于文件末尾、未改动任何核心内容

扩展是 PAUL 生态生长的方式：核心保持简洁，个性化能力全部通过注入点挂载。选对一个注入点、写清一份扩展文档，你的集成就能搭上 PAUL 的闭环循环。