Halo 项目 OpenSpec Explore 模式实战：变更前探索、需求澄清与代码库调查指南

• 后端
• 前端
• CMS

导读

本文讲解 Halo 开源建站工具仓库中基于 OpenSpec 的Explore（探索）模式：一种在发起代码变更之前，用于梳理想法、调查问题、澄清需求、对比方案并沉淀结论的"思考搭档"式工作方式。读完本文，你将掌握openspecCLI 在探索阶段的核心用法（list、status）、探索与实现（implement）的边界规则、洞察如何落入 proposal / design / tasks 等产物，以及 Halo 仓库中真实归档变更（如分类层级迁移、评论固定链接）是如何从探索走向落地的完整路径。

一、Explore 模式是什么：思考的场所，不是实现的场所

在 Halo 仓库中，OpenSpec 以spec-driven（规格驱动）方式运作，仓库根目录的 openspec/config.yaml 声明了schema: spec-driven，并通过context向所有 AI 提示注入项目技术栈（Java 21 / Spring Boot 4.x / WebFlux / R2DBC、Vue 3 / TypeScript / Vite、pnpm workspaces 等）与架构约定（PF4J 插件体系、Extension Points、主题模板渲染）。

openspec-explore 技能文档 定义了其中第一个关键环节：

Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.

Explore 模式的核心定位是"a stance, not a workflow"（一种姿态，而非一套流程）——没有固定的步骤序列、没有强制的产出物，它只是 AI 作为"思考搭档"陪伴用户探索问题。

最重要的边界是：

• 可以：读文件、搜代码、调查代码库、绘制示意图、对比方案；
• 绝不：编写应用代码或实现功能（创建 OpenSpec 产物属于"记录思考"，不算实现）。

如果用户要求实现功能，应提醒其先退出探索模式并创建变更提案（change proposal）。这一点在 opsx:explore 命令 中被同样强调：explore 模式允许的工具被限定为Bash(openspec:*)，从工具权限上就杜绝了实现动作。

二、探索者的六条姿态（The Stance）

探索模式的行为准则可以概括为六条，它们决定了整个会话的节奏与气质：

其中Grounded一条对 Halo 这类大型仓库尤为重要：探索阶段就应该真实地去读 api/、application/、ui/ 的源码，把讨论锚定在现实之上，而不是凭空设想架构。

三、探索模式下可以做哪些事（What You Might Do）

3.1 探索问题空间

• 从用户话语中自然提出澄清性问题；
• 挑战既有假设；
• 重构问题表述（reframe）；
• 寻找类比（analogy）。

3.2 调查代码库

• 绘制与讨论相关的现有架构地图；
• 寻找集成点（integration points）；
• 识别已在使用的模式；
• 暴露隐藏的复杂性。

3.3 对比选项

• 头脑风暴多种方案；
• 构建对比表；
• 勾画权衡取舍（tradeoffs）；
• 在被要求时给出路径建议。

3.4 可视化

原文档强调"好的示意图胜过许多段落"，鼓励大胆使用 ASCII 图表达系统结构、状态机、数据流、架构草图、依赖图、对比表。例如：

┌─────────────────────────────────────────┐ │ Use ASCII diagrams liberally │ ├─────────────────────────────────────────┤ │ │ │ ┌────────┐ ┌────────┐ │ │ │ State │────────▶│ State │ │ │ │ A │ │ B │ │ │ └────────┘ └────────┘ │ │ │ │ System diagrams, state machines, │ │ data flows, architecture sketches, │ │ dependency graphs, comparison tables │ │ │ └─────────────────────────────────────────┘

3.5 暴露风险与未知

• 识别可能出错的地方；
• 找出理解中的缺口（gaps）；
• 建议 spike 或专项调查。

四、OpenSpec 感知：开局先看上下文

进入探索模式后，应快速感知当前 OpenSpec 系统的状态，而非强行套用。

4.1 检查现有内容

openspec list --json

这条命令会告诉你：

• 是否存在活跃的变更（active changes）；
• 每个变更的名称、schema 与状态；
• 用户可能正在做什么。

4.2 仓库级上下文注入

在 Halo 仓库中，探索时的"背景知识"来自 openspec/config.yaml 的context段——它向所有 AI 提示注入技术栈与约定，而更细致的编码规范放在AGENTS.md（如 AGENTS.md、platform/application/AGENTS.md、ui/AGENTS.md）。

同时，config.yaml 的rules段为不同产物定义了具体、可执行的约束，这些约束会在探索沉淀为提案后生效：

• proposal 类规则：评估对现有插件/主题 API 的兼容性影响；数据库 schema 变更必须包含迁移策略；安全相关变更必须评估认证/授权影响；UI 变更必须考虑 i18n 支持；
• tasks 类规则：后端变更必须通过./gradlew spotlessCheck；前端变更必须通过pnpm lint与pnpm typecheck；API 变更要求更新 OpenAPI 文档并重新生成 api-client；新依赖必须检查许可证兼容性。

这些规则解释了为何 Halo 的变更产物（如归档中的 tasks.md）几乎总包含spotlessCheck、pnpm lint、openspec validate --strict等验证步骤——它们是规格驱动工作流的内置质量闸门。

五、两种探索情境的处理方式

5.1 当仓库中还没有变更（When no change exists）

自由思考即可。当洞察结晶时，可以主动提供选项：

• "这个思路已经足够扎实，可以开始一个 change 了，需要我创建 proposal 吗？"
• 或者继续探索——不施压，不强制形式化。

5.2 当存在变更时（When a change exists）

如果用户提到某个变更，或你发现某个变更与讨论相关：

1. 解析并阅读现有产物以获取上下文

openspec status --change "<name>" --json

从返回的 JSON 中读取changeRoot、artifactPaths、actionContext三个字段；再通过artifactPaths.<artifact>.existingOutputPaths读取既有产物文件。

2. 在对话中自然地引用它们

   • "你的设计提到用 Redis，但我们刚意识到 SQLite 更合适……"
   • "提案把范围限定在付费用户，但现在我们在考虑所有人……"

3. 在决策产生时提供记录入口（由用户决定是否记录）

六、洞察捕获映射表：想法该落到哪里

探索过程中产生的各类洞察，对应不同的 OpenSpec 产物存放位置：

典型的话术示例：

• "这是设计决策，记录到 design.md 吗？"
• "这是新需求，加到 specs 里？"
• "这改变了范围，需要更新 proposal。"

关键原则：用户决定一切。只提供记录入口，不施压、不自动记录（Don't pressure. Don't auto-capture）。

在 Halo 仓库的归档变更中，可以清晰看到这套映射的实际效果。例如 2026-07-10-support-category-parent-editing 的产物布局：

• proposal.md（Why / What Changes / Capabilities / Impact）：说明"分类创建已支持选择父分类，但编辑现有分类时未暴露层级控制"这一动机，并将受影响 UI 定位到ui/console-src/modules/contents/posts/categories/；
• design.md（Context / Goals / Non-Goals / Decisions / Risks）：记录"复用 tree-aware categorySelect 并增加 opt-in 排除能力""仅当父分类变化时才调用updateCategoryPosition""后端将移动的分类追加到目标兄弟列表"等决策及备选方案；
• tasks.md：把工作拆成"分类父级工具函数 / 编辑弹窗集成 / 验证"三个可勾选区块，每项带- [x]完成标记；
• specs/category-hierarchy/spec.md：以 Gherkin 风格（WHEN/THEN）描述需求。

七、不必做的事（What You Don't Have To Do）

探索模式明确豁免以下义务，以避免把"思考时间"变成"任务时间"：

• 不必照脚本走（Follow a script）；
• 不必每次都问同样的问题（Ask the same questions every time）；
• 不必产出特定产物（Produce a specific artifact）；
• 不必得出结论（Reach a conclusion）；
• 不必死守主题，如果有价值的支线可以随时展开（Stay on topic）；
• 不必简短——这是思考时间（Be brief）。

八、不同入口场景的实战示例

8.1 用户带来模糊想法

例如 "我在考虑加入实时协作"——此时 AI 不应直接给答案，而应画出"协作光谱"（awareness → coordination → sync），让用户自己定位兴趣点：

COLLABORATION SPECTRUM ════════════════════════════════════════════ Awareness Coordination Sync │ │ │ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │Presence│ │Cursors │ │ CRDT │ │ "3 │ │ Multi │ │Conflict│ │online" │ │ select │ │ free │ └────────┘ └────────┘ └────────┘ │ │ │ trivial moderate complex Where's your head at?

8.2 用户带来具体问题

例如 "认证系统一团糟"——此时应真的去读代码库，画出当前流程（如 Google OAuth / GitHub OAuth / Email Magic → Session → Perms），并指出"我看到三个缠绕点，哪一个最让你头疼？"，而不是泛泛而谈。

8.3 用户卡在实现中途

例如用户带着 change 名称进入探索：/opsx:explore add-auth-system。此时应读取变更产物（任务 4 "Implement OAuth flow"），顺着当前任务梳理涉及内容、绘制图示、探索选项、建议路径，并询问是否需要更新设计或添加 spike 任务。

8.4 用户想对比选项

例如 "该用 Postgres 还是 SQLite？"——先追问上下文（CLI 工具 / 本地开发环境），再基于约束做对比表（部署方式、离线能力、单文件特性），最后给出有依据的判断："SQLite. Not even close." 除非存在同步组件。

九、结束探索（Ending Discovery）

探索没有强制结局，可能的走向包括：

• 流入提案："准备好开始了吗？我可以创建一个 change proposal。"
• 更新产物："已把这些决策更新到 design.md。"
• 仅提供澄清：用户拿到了所需信息，继续前行；
• 稍后再续："我们随时可以继续。"

当感觉思路正在结晶时，可以主动给出可选摘要：

## What We Figured Out **The problem**: [crystallized understanding] **The approach**: [if one emerged] **Open questions**: [if any remain] **Next steps** (if ready): - Create a change proposal - Keep exploring: just keep talking

但这份摘要可选——有时"思考本身就是价值"，不需要任何收尾。

十、守卫护栏（Guardrails）

探索模式的六条硬性边界：

• Don't implement—— 绝不编写代码或实现功能；创建 OpenSpec 产物可以，写应用代码不可以；
• Don't fake understanding—— 有不清楚的地方就深挖，不要假装理解；
• Don't rush—— 探索是思考时间，不是任务时间；
• Don't force structure—— 让模式自然浮现，不要强加结构；
• Don't auto-capture—— 提供保存洞察的选项，但不要擅自保存；
• Do visualize—— 好的示意图抵得上很多段落；
• Do explore the codebase—— 把讨论锚定在现实代码上；
• Do question assumptions—— 包括用户的假设和你自己的假设。

十一、在 Halo 仓库中的真实落地：从探索到归档

探索模式的终极检验是它能否催生高质量、可验证的变更。Halo 仓库的openspec/changes/archive/目录保存了大量已完成变更，展示了探索 → 提案 → 实现 → 验证 → 归档的完整生命周期。

以 2026-09-15-comment-reply-permalinks 为例，其验证文档展示了落地质量：

• 自动化检查：123 个聚焦后端测试通过，覆盖 permalink 格式化与富化、评论/回复读取、内容更新兼容性、通知发布器与真实默认模板渲染；
• 集成测试：CommentPermalinkIntegrationTest使用随机端口 Halo 服务器、真实扩展存储、HTTP 与 Basic 认证，16 个用例覆盖两种可见级别、匿名/所有者/无关/版主访问等边界；
• 质量闸门：./gradlew spotlessCheck、pnpm -C ui typecheck、pnpm -C ui lint、openspec validate comment-reply-permalinks --strict、git diff --check全部通过；
• 实机验证：启动独立的 Halo 2.27.0-SNAPSHOT 实例 + Console 开发服务器，真实创建根评论、访客评论、管理员回复与引用回复，逐一核对 permalink 与 DOM 行为。

这套验证习惯与 config.yaml 中rules.tasks的约定一脉相承（spotlessCheck / lint / typecheck / OpenAPI 同步 /openspec validate --strict），说明探索阶段形成的结论最终会通过规格驱动的校验闭环落地。

十二、探索之外：OpsX 完整工作流

探索只是 OpsX 工作流的第一环。在 .claude/commands/opsx/ 与 .claude/skills/ 下，Halo 仓库还提供了完整的相邻环节：

• propose / openspec-propose：openspec new change "<name>"创建变更，一次性生成 proposal.md（what & why）、design.md（how）、tasks.md（implementation steps），并用openspec status --change "<name>" --json按依赖顺序构建产物直至 apply-ready；
• apply / openspec-apply-change：按 tasks 实施实现；
• update / openspec-update-change：实现中途更新产物；
• archive / openspec-archive-change：openspec list --json选择变更，检查产物与任务完成度，评估 delta spec 同步状态后归档到changes/archive/YYYY-MM-DD-<change-name>/；
• sync / openspec-sync-specs：将变更中的 delta spec 同步回openspec/specs/<capability>/spec.md。

此外，所有读写 spec 与 change 的命令都支持store 选择：如果用户指定了 store（本机注册的独立 OpenSpec 仓库），先运行openspec store list --json发现注册的 store id，再在new change、status、instructions、list、show、validate、archive、doctor、context等命令后追加--store <id>；其余命令不接受该标志。未指定 store 时，命令作用于最近的本地openspec/根目录。

结语

对于 Halo 这样体量庞大、插件体系复杂（PF4J 插件、Extension Points、主题系统、OpenAPI 文档化）的仓库，任何变更前都值得先进入 Explore 模式：它是把"模糊想法"变成"可验证提案"的孵化器。牢记核心姿态——思考，而非实现；保持好奇、可视化、接地气，让洞察自然结晶，再通过openspecCLI 将其落入 proposal、design、specs 与 tasks，最终汇入仓库的规格驱动开发闭环。

• 后端
• 前端
• CMS