企业官网建设流程全解析

本篇技术指南聚焦 gsd-core 项目中一个明确的架构范围决策：OMP（Oh My Pi）不会被注册为 gsd-core 的一等（first-class）运行时。文章完整还原了这一决策的来龙去脉、底层维护成本模型、与现有pi运行时描述符的关系，并给出项目官方支持的正确替代路径——基于 ADR-1239 的 Embeddable Orchestration System（EOS）主机插件机制。读完本文，你将理解 gsd-core 运行时注册表的工作方式、GSD_AGENTS_DIR覆盖契约、role: runtime与role: feature两种能力维度的区别，以及如何在仓库内核对每一次运行时支持请求的真实落地状态。

一、决策全景：这不是质量判断，而是范围判断

gsd-core 的仓库中明确记录（见.out-of-scope/omp-runtime-in-core.md）：项目不会将omp（Oh My Pi）添加为一等运行时。具体而言，这意味着以下四项都不会发生：

• 不会出现capabilities/omp/capability.json描述符；
• 不会在运行时注册表（Capability Registry）中新增omp条目；
• 不会为omp增加别名规范化（alias canonicalization）；
• 不会为 OMP 增加安装器运行时选择（installer runtime selection）。

需要特别强调的是：这是一个范围（scope）决策，而非对 OMP 项目本身或其提案质量的评判。gsd-core 的文档体系中有专门的.out-of-scope/目录来沉淀这类决策，其作用是把"不做某事"的理由以可追溯的方式写下来，避免同一请求反复提交、反复消耗维护者时间。

从仓库结构可以验证当前状态：capabilities/目录下共有 40+ 个能力描述符目录，包含claude、codex、pi、vscode、cursor、windsurf等运行时，以及research、security、code-review等特性能力，但确实不存在capabilities/omp/目录。这一事实与决策文档的描述完全一致。

二、为什么不纳入：一等运行时的永久维护义务

决策文档给出了两条核心理由，理解它们需要先了解 gsd-core 的能力（Capability）架构。

2.1 运行时的方向是"做减法"，不是"做加法"

gsd-core 长期的技术方向是减少而非增加受支持运行时的数量（除非有资金支持的发展计划）。这背后的成本模型非常具体：每一个一等运行时都是一项永久维护义务，需要横跨以下全部环节持续跟进：

• 注册表（registry）：运行时描述符与能力注册表的维护；
• 安装器（installer）：运行时安装路径与安装流程的适配；
• 制品转换（artifact conversion）：技能、Agent、hooks 等制品在不同运行时约定间的投影与转换；
• Agent 发现（agent discovery）：运行时自身的 Agent 加载机制；
• 模型路由（model routing）：GSD 模型分层与运行时模型 ID 的映射；
• 派发隔离（dispatch isolation）：子 Agent 派发的隔离模型；
• 黄金安装一致性测试夹具（golden install-parity fixtures）：用于验证安装结果与预期一致的基准夹具；
• 本地化能力矩阵（localized capability matrices）：多语言/多区域文档中对应的能力矩阵同步。

capabilities/pi/capability.json中可以看到这种维护义务的具象化——仅pi一个运行时的描述符就包含runtime.configHome、localConfigDir、artifactLayout、triggerPrecedence、commandStyle、hooksSurface、extensionEvents、sandboxTier、supportTier、installSurface、hostIntegration（含embeddingMode、commandSurface、dispatch、modelMode、hookBus、stateIO、transport、runtime、effortSurface）以及hostBehaviors等十余个维度的精确声明。任何一个新运行时都要为这套词汇表提供完整、经测试的取值。

关键点在于：这些义务由项目无限期承担，而服务的主机（host）却不受项目控制。主机一旦变更其扩展机制或配置约定，项目就得跟进适配。这就是"每个一等运行时都是永久维护义务"这句话的完整含义。

2.2 主机集成才是受支持的方向，而且已经可用

决策的核心正面主张是：Embeddable Orchestration System（EOS，ADR-1239）就是为这种情况设计的。EOS 的理念是把依赖方向反转——不是 GSD 主动"投影"到某个主机上，而是主机把 GSD 作为引擎嵌入，并由主机声明自己的能力（capabilities）。

在该模型下，一个仓库外的（out-of-tree）主机插件不需要任何运行时描述符。docs/registries/eos.json就是这一生态的注册表，当前已列出gsd-cursor、gsd-omp、gsd-qoder、gsd-reasonix等四个 EOS 插件条目，其中gsd-omp（"GSD for Oh My Pi"）明确存在且保持列出状态。

此外，GSD_AGENTS_DIR是一个文档化的 Priority-1 覆盖项，对任何运行时名称都生效。在src/agent-install-check.cts中，getAgentsDir(runtime?, projectRoot?)函数的实现首先检查process.env['GSD_AGENTS_DIR']：

if (process.env['GSD_AGENTS_DIR']) { return process.env['GSD_AGENTS_DIR']; }

也就是说，插件可以完全拥有自己的文件系统布局，而核心无需知道该运行时的存在——这是 OMP 这类第三方主机接入 GSD 的"官方车道"。

2.3 原始提案本身携带缺陷：#3037 的别名规范化问题

决策文档还记录了一个技术细节，值得单独说明：提案#3037曾提议将pi、oh-my-pi、pi-coding-agent三个名称规范化（canonicalize）为omp。

问题在于：OMP 是 pi（pi.dev）的一个 fork，而 gsd-core 已经随包提供了独立的pi运行时。查看capabilities/pi/capability.json可以确认：

• id为pi，role为runtime，tier为core；
• 配置主目录为~/.pi/agent（runtime.configHome中parent: ".pi"、name: "agent"）；
• supportTier: 2（tier-2 支持）；
• 引擎要求gsd >= 1.7.0；
• 通过原生扩展~/.pi/agent/extensions/gsd.js集成，并支持PI_CODING_AGENT_DIR环境变量。

如果执行 #3037 的别名表，效果将是把现有已发布运行时的配置主目录迁移到别处，而不是新增一个运行时——这与"新增 OMP 支持"的诉求背道而驰。决策文档将其记录为"修正（correction）"，目的是防止未来修订重蹈覆辙，而不是作为决策的额外依据。

三、此决策"不涵盖"什么：边界清单

理解一个范围决策，最重要的往往是搞清楚它没有否决什么。本条目否决的仅仅是仓库内、一等、正式注册的 OMP 运行时，下列事项一律不受影响，且不应被本条目援引来反对：

3.1 仓库外的 OMP 主机插件——欢迎且受支持

为 OMP（或任何其他主机）发布仓库外主机插件是明确欢迎且受支持的方向。docs/registries/eos.json中已列出gsd-omp条目并持续保留，其描述为：

"Embeds GSD in Oh My Pi through OMP's native ExtensionAPI, programmatic slash commands, task isolation, lifecycle events, filesystem state, and managed agent and skill projection."

该条目还声明了完整的交互轴：embeddingMode: "imperative"、commandSurface: "slash-programmatic"、dispatch（原生命名与嵌套 OMP 任务派发，支持后台执行、完整子 Agent 工具集与主机托管隔离）、modelMode: "passive"、hookBus: "host"、stateIO: "filesystem"、transport: "native-extension"、runtime: "bun"，并附带安装命令npm install --global github:tchivs/gsd-omp#v1.0.0 && gsd-omp install与卸载命令。需要特别指出的是，注册表收录明确是非背书（non-endorsement）性质的——列在 EOS 注册表中不代表核心项目为其背书，这一点不受本决策影响。

3.2 特性能力（role: "feature"）——不同的维度

在仓库外发布role: "feature"的特性能力属于 ADR-1244（Capability Ecosystem）管辖的范畴。这是一个不同的轴：特性能力解决的是"向 GSD 循环行为中添加什么"（例如research、security、code-review、graphify、intel、audit等），而运行时能力解决的是"你是哪个运行时"。OMP 若想通过插件增强 GSD 的某个环节行为，走的是特性能力通道，与本决策无冲突。

3.3 缺陷修复与覆盖契约改进——不受影响

• 修复恰好通过非注册运行时暴露出来的缺陷，不受本决策影响；
• 改进主机插件所依赖的文档化覆盖契约（如GSD_AGENTS_DIR的解析行为），同样不受影响。

3.4 其他运行时的支持层级——不产生连带效应

本条目只针对 OMP，对现有运行时（包括pi）的支持层级不做任何说明、不产生任何变化。换句话说，OMP 是 fork 自 pi 这一事实，并不意味着 pi 的现有状态会被波及。

四、重审条件（Revisit if）：什么情况下可以重新讨论

范围决策并非永久封死，文档明确给出了两个未来可能触发重审的条件：

1. 第三方role: "runtime"描述符可从仓库外加载。ADR-857 的 Decision 8 将第三方 CLI 支持推迟到一个纯增量的外部加载器（purely additive external loader），该加载器目前尚未交付。一旦它落地，第三方主机就可以通过受信任的外部加载机制注册运行时描述符，而不必要求仓库内一等注册。
2. 有资金支持的发展改变了维护成本测算。如果"每个一等运行时都是永久维护义务"这一前提因资金支持而变化，使得新增一等运行时变得可负担，则决策可重新评估。

对第一条的补充说明：ADR-857 是 gsd-core 能力系统的奠基性决策（五步循环为核心、特性作为插件），其 Decision 8 明确"注册表只加载仓库内描述符（in-tree descriptors only）"，第三方运行时支持被推迟到外部加载器 + 信任/验证门（trust/validation gate）。ADR-1244 进一步实现了该加载器——但按其决议范围，它交付的是**特性能力（feature capability）**的第三方作者、版本化清单与 URL 导入/升级/移除能力，第三方runtime描述符的加载仍是未交付的增量。这也解释了为何本条目把"第三方 runtime 描述符可加载"列为重审触发条件。

五、被否决的请求记录：为什么这个文件存在

决策文档完整记录了历次 OMP 运行时支持请求及其处置结果，这份记录本身就是重要的项目治理档案：

文档末尾用一句话点明了该文件存在的根本原因：

The first denial was never written down here, so the same request returned twice more. That is the reason this file exists.

（第一次否决从未被书面记录，因此同样的请求又重复出现了两次。这就是本文件存在的原因。）

这句话对理解 gsd-core 的治理风格至关重要：范围决策需要沉淀为可检索的书面记录，否则请求会反复回流。.out-of-scope/目录就是这种"否决的可追溯性"机制的载体。

六、从源码验证：如何核对运行时支持的真实状态

作为工程实践，本文给出三条在仓库内核对"某运行时是否为一等支持"的验证路径：

1. 检查能力描述符：一等运行时必然以role: "runtime"描述符存在于capabilities/<id>/capability.json。对照capabilities/pi/capability.json的字段结构（role、tier、engines.gsd、runtime.configHome、supportTier、hostIntegration、hostBehaviors等），即可判断一个运行时是否被正式注册。capabilities/目录中不存在omp/，即为最直接的证据。
2. 检查 EOS 注册表：仓库外主机插件会出现在docs/registries/eos.json，其中gsd-omp条目证明了 OMP 的受支持接入方式不是一等运行时注册，而是 EOS 主机插件。
3. 检查覆盖契约实现：src/agent-install-check.cts的getAgentsDir()（约 L144-L187）展示了GSD_AGENTS_DIR作为 Priority-1 覆盖项对任意运行时名称生效的实现——它先于所有运行时特定解析逻辑返回。相关设计约束在文件头注释（约 L130-L142）中有详细说明，包括 claude 与 manifest-backed 项目本地安装的解析规则。

七、结论与工程启示

OMP 不在 gsd-core 的一等运行时集合中，这是经过论证的、可追溯的架构范围决策，而非对 OMP 的评价。其底层逻辑可以概括为三条原则：

• 运行时是重资产：每个一等运行时都是一项横跨注册表、安装器、制品转换、模型路由、派发隔离与测试夹具的永久维护义务，在无资金支持下项目选择收缩而非扩张运行时集合；
• 集成优于注册：对第三方主机，官方路径是 EOS（ADR-1239）主机插件 +GSD_AGENTS_DIR等文档化覆盖契约，仓库外插件完全不需要仓库内运行时描述符；
• 记录否决：范围决策必须书面化、可检索，避免同一请求反复回流消耗维护精力。

对有意为 OMP（或任何新主机）接入 GSD 的开发者，正确的做法是：参考docs/registries/eos.json中现有条目（尤其是gsd-omp、gsd-qoder、gsd-reasonix的声明结构与安装/卸载命令），编写仓库外的 EOS 主机插件，并在该插件的交互轴声明中精确描述六个接口点（命令调用、Agent 派发、模型调用、生命周期 hooks、状态与配置 IO、制品表面）的能力取值。这一路径从架构到注册表都是项目官方支持且明确欢迎的。

参考文档索引

• 决策原文：.out-of-scope/omp-runtime-in-core.md
• 运行时描述符示例：capabilities/pi/capability.json
• EOS 插件注册表：docs/registries/eos.json
• 覆盖契约实现：src/agent-install-check.cts
• 能力系统架构：docs/adr/857-capability-system.md
• 可嵌入编排引擎：docs/adr/1239-gsd-embeddable-orchestration-engine.md
• 能力生态（第三方作者/版本化清单/URL 导入）：docs/adr/1244-capability-ecosystem.md