企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• 多智能体
• MCP Clients
• Agent 编排

导读：本文围绕 oh-my-openagent（npm 包名为 oh-my-opencode / oh-my-openagent）仓库中内置的pre-publish-review技能，完整剖析其"12-Agent 发布前审查门禁"的设计与实操：包括三层 agent 架构（ultrabrain 逐变更深入分析、review-work 整体审查、oracle 发布综合）、三类发布层（omo pure components/omo opencode/omo codex）、从检测未发布变更到最终裁决的完整 4 阶段流程，并结合仓库源码说明 oracle 等 agent 的底层实现。读完本文，你将掌握如何在发布 npm 前用一套可复制的多 agent 并行评审模板对任何变更集执行门禁式审查，并理解它与/publishship-only 流程的边界。

本文主体以 pre-publish-review 技能定义 为核心（其在 .opencode/skills/pre-publish-review/SKILL.md 中保留了同步副本），源码佐证取自packages/omo-opencode/src下的 agent 实现。

一、它是什么：从 "publish" 到 "release gate"

在 oh-my-openagent 仓库的.agents/skills/目录下，技能系统对"发布"这件事做了明确分工：

• /publish（ship-only）：直接触发 GitHub Actions 发布工作流并验证产物，绝不在发布过程中重新审查代码。其设计前提是origin/dev已被 CI（3 个操作系统上的 test/typecheck/codex-compatibility）门禁过，发布工作流本身也会重跑这些门禁。
• /pre-publish-review（release gate）：仅在用户明确要求发布前审查时运行——例如 "pre-publish review"、"review before publish"、"release review"、"ready to publish?"、"can I publish?"、"safe to publish" 等触发词。一次普通的发布请求绝不会触发它，否则/publish会直接发货。

pre-publish-review技能自身的描述将其定义为：

"Nuclear-grade 12-agent pre-publish release gate."

它做的事情概括为四步：先运行/get-unpublished-changes检测自上次 npm 发布以来的全部变更；孵化最多 10 个 ultrabrain agent对每个变更组做深入分析；调用/review-work（编排者手动 QA + 1 个门禁评审员）做整体审查；最后用1 个 oracle agent做全局发布综合。合计最多 12 个 agent，三层分工，互不重叠。

与之配合的 get-unpublished-changes 技能 与 publish 技能 共同构成了完整的发布链路：检测未发布变更 → 发布前审查 → 发布。

二、三层审查架构与 Release Layer 分类

2.1 三层 agent 分工

技能开头用一张表定义了三个审查层，每层覆盖不同角度，且所有结果最终都会映射到发布层上：

关键设计原则：并行而不是串行。所有 agent 在同一轮中全部孵化（run_in_background=true），每个 ultrabrain 只拿到自己负责的那部分 diff，而非完整变更集；只有 oracle 看到全貌。

2.2 Release Layer 分类学（三发布面）

每个阶段的证据与风险都必须按下面三个发布层归类，并给出各自的版本决策：

| 发布层 | 范围 | 必须做出的版本决策 | ||---|---|---| |omo pure components| 核心包、MCP 包、共享技能、可复用脚本、平台二进制输入 | 被适配器消费的共享逻辑需要 patch/minor/major 影响评估 | |omo opencode| 根oh-my-opencode/oh-my-openagent、src/、OpenCode 插件钩子/工具/CLI/配置/文档、.opencode/、.agents/| OpenCode/OpenAgent npm 发布的 semver bump | |omo codex|packages/omo-codex、lazycodex-ai、Codex 插件元数据/钩子、打包的 MCP 运行时、code-yeongyu/lazycodexmarketplace 载荷 | Codex 适配器 bump、LazyCodex npm 发布风险、marketplace/GitHub 发布需求 |

这一分类与 get-unpublished-changes 技能 中的三层定义完全一致，也和 publish 技能 中"三个发布面"（omo pure components/omo opencode/omo codex）的验证契约一一对应。其中对适配器内部变更（路径匹配senpi、omo-senpi、senpi-task、pi-goal、pi-webfetch）有明确纪律：不进入用户可见的发布说明与版本建议，只记录在单独的"内部适配器排除台账"（internal-adapter exclusion ledger）中。

2.3 源码佐证：oracle 的底层实现

仓库中oracle是一个真实注册的内置 subagent，而非 skill 虚构的角色。证据如下：

• 内置 agent 注册表 中oracle: createOracleAgent与sisyphus、hephaestus、librarian、explore等并列，并注册了ORACLE_PROMPT_METADATA。
• oracle agent 实现 定义const MODE: AgentMode = "subagent"；其元数据分类为category: "advisor"、cost: "EXPENSIVE"，触发场景包括"架构决策""完成重大实现后的自审""2 次以上修复失败后的硬调试"。
• 工具限制 中createOracleAgent通过createAgentToolRestrictions禁用了write、edit、apply_patch、task四类工具，即 oracle 是只读顾问，不能写代码也不能再委派子任务——这正对应 skill 中反模式表里"oracle 无法读文件，必须在 prompt 中喂入关键文件内容"这一条。
• 模型相关配置：gpt-5.5 系模型使用reasoningEffort: "medium"，gpt-5.6/gpt-6 系使用"xhigh"，基础temperature: 0.1（oracle.ts）。
• ultrabrain则是 categories schema 中BuiltinCategoryNameSchema枚举的内置委派类别之一（与visual-engineering、deep、artistry、quick、unspecified-low、unspecified-high、writing并列），可在配置中按类别覆盖reasoningEffort、variant等参数——相关行为有 agent-overrides.test.ts 的测试用例覆盖。

三、Phase 0：检测未发布变更（/get-unpublished-changes）

这是整个门禁的第一步，也是"唯一事实来源"（single source of truth）。技能明确要求：先运行/get-unpublished-changes，其输出必须包含三个发布层的版本建议，并完整保存——它将直接喂给 Phase 1 的分组和所有 agent 的 prompt。

skill(name="get-unpublished-changes")

该命令自动完成：

• 检测已发布 npm 版本 vs 本地版本
• 列出自上次发布以来的所有 commit
• 读取实际 diff（而非仅 commit message）来描述真实变更
• 按类型（feat/fix/refactor/docs）与 scope 分组
• 识别破坏性变更
• 给出每个发布层的版本 bump 建议 + 一个整体工作流 bump

从 get-unpublished-changes 命令 可以看到它的具体执行方式：通过npm view、node -p、git log v{version}..HEAD、git diff等命令动态注入已发布版本、本地版本、commits、diff-stat、文件变更统计，并要求输出 feat/fix/refactor/docs 四类表格、Layered Impact Matrix、逐层版本建议和整体 bump 建议。其中有一条硬性纪律：禁止照抄 commit message——每个 commit 必须读实际 diff，用平实语言描述真实变更及影响。

在调用/get-unpublished-changes后，还需捕获 agent prompt 所需的原始数据（skill 提供可直接执行的 bash 片段）：

# 提取版本（已包含在 /get-unpublished-changes 输出中） PUBLISHED=$(npm view oh-my-opencode version 2>/dev/null || echo "not published") LOCAL=$(node -p "require('./package.json').version" 2>/dev/null || echo "unknown") # 供 agent 使用的原始数据（diffs、文件列表） COMMITS=$(git log "v${PUBLISHED}"..HEAD --oneline 2>/dev/null || echo "no commits") COMMIT_COUNT=$(echo "$COMMITS" | wc -l | tr -d ' ') DIFF_STAT=$(git diff "v${PUBLISHED}"..HEAD --stat 2>/dev/null || echo "no diff") CHANGED_FILES=$(git diff --name-only "v${PUBLISHED}"..HEAD 2>/dev/null || echo "none") FILE_COUNT=$(echo "$CHANGED_FILES" | wc -l | tr -d ' ')

首次发布特例：如果PUBLISHED输出为 "not published"，说明这是首次发布，应改用完整 git 历史（而不是v{version}..HEAD区间）作为变更基线。

四、Phase 1：把变更解析为变更组

以/get-unpublished-changes的输出为起点（它已经按 scope 和类型分组），再按如下策略进一步切分：

1. 沿用其 feat/fix/refactor/docs 分类与 scope；
2. 按模块/领域再次拆分——触及同一模块或同一功能领域的变更归为一组；
3. 目标为最多 10 组：若 commit 少于 10 个，则每个 commit 自成一组；若逻辑领域超过 10 个，则合并最小的组；
4. 对每个组提取五要素：
   • Group name：简短描述性标签（如agent-model-resolution、hook-system-refactor）
   • Release layer(s)：omo pure components/omo opencode/omo codex
   • Commits：commit hash 与 message 列表
   • Files：该组涉及的文件
   • Diff：git diff v${PUBLISHED}..HEAD -- {组内文件}的相关片段

分组质量直接决定 ultrabrain 的并行度与审查粒度——把 1-2 个 ultrabrain 塞进所有变更属于反模式表中的 HIGH 级违规。

五、Phase 2：一次性孵化全部 12 个 Agent

硬性规则：所有 agent 必须在同一轮内启动，全部使用run_in_background=true，严禁串行启动。底层后台任务机制在 .opencode/background-tasks.json 中有真实运行记录（字段包含id、sessionID、agent、status、startedAt/completedAt等），收集阶段即通过background_output(task_id="...")获取各任务的输出。

5.1 Layer 1：ultrabrain 逐变更深入分析（最多 10 个）

每个变更组孵化一个 ultrabrain agent，只拿到自己那一份 diff，不看完整变更集。核心task()调用模板：

task( category="ultrabrain", model="gpt-5.6-sol", run_in_background=true, load_skills=[], description="Deep analysis: {GROUP_NAME}", prompt=""" <review_type>PER-CHANGE DEEP ANALYSIS</review_type> <change_group>{GROUP_NAME}</change_group> <project>oh-my-opencode (npm package)</project> <published_version>{PUBLISHED}</published_version> <target_version>{LOCAL}</target_version> <commits> {GROUP_COMMITS — hash and message for each commit in this group} </commits> <changed_files> {GROUP_FILES — files changed in this group} </changed_files> <diff> {GROUP_DIFF — only the diff for this group's files} </diff> <file_contents> {Read and include full content of each changed file in this group} </file_contents> You are reviewing a specific subset of changes heading into an npm release. Focus exclusively on THIS change group. Other groups are reviewed by parallel agents. ANALYSIS CHECKLIST: 1. **Intent Clarity**: What is this change trying to do? Is the intent clear from the code and commit messages? If you have to guess, that's a finding. 2. **Correctness**: Trace through the logic for 3+ scenarios. Does the code actually do what it claims? Off-by-one errors, null handling, async edge cases, resource cleanup. 3. **Breaking Changes**: Does this change alter any public API, config format, CLI behavior, or hook contract? If yes, is it backward compatible? Would existing users be surprised? 4. **Pattern Adherence**: Does the new code follow the established patterns visible in the existing file contents? New patterns where old ones exist = finding. 5. **Edge Cases**: What inputs or conditions would break this? Empty arrays, undefined values, concurrent calls, very large inputs, missing config fields. 6. **Error Handling**: Are errors properly caught and propagated? No empty catch blocks? No swallowed promises? 7. **Type Safety**: Any `as any`, `@ts-ignore`, `@ts-expect-error`? Loose typing where strict is possible? 8. **Test Coverage**: Are the behavioral changes covered by tests? Are the tests meaningful or just coverage padding? 9. **Side Effects**: Could this change break something in a different module? Check imports and exports — who depends on what changed? 10. **Release Risk**: On a scale of SAFE / CAUTION / RISKY — how confident are you this change won't cause issues in production? OUTPUT FORMAT: <group_name>{GROUP_NAME}</group_name> <verdict>PASS or FAIL</verdict> <risk>SAFE / CAUTION / RISKY</risk> <summary>2-3 sentence assessment of this change group</summary> <has_breaking_changes>YES or NO</has_breaking_changes> <breaking_change_details>If YES, describe what breaks and for whom</breaking_change_details> <findings> For each finding: - [CRITICAL/MAJOR/MINOR] Category: Description - File: path (line range) - Evidence: specific code reference - Suggestion: how to fix </findings> <blocking_issues>Issues that MUST be fixed before publish. Empty if PASS.</blocking_issues> """)

要点拆解：

• 审查清单 10 项覆盖意图清晰度、正确性（要求至少推演 3 个场景）、破坏性变更、模式一致性、边界情况、错误处理、类型安全、测试覆盖有效性、跨模块副作用、发布风险等级。
• 输出为结构化 XML 标签，便于聚合器解析：verdict（PASS/FAIL）、risk（SAFE/CAUTION/RISKY）、findings（每条带 CRITICAL/MAJOR/MINOR 级别、文件路径、代码证据、修复建议）、blocking_issues。
• 若<blocking_issues>非空，该组在发布前必须修复。

5.2 Layer 2：review-work 整体审查（1 个协调者）

孵化一个加载/review-work技能的 sub-agent（category="unspecified-high"）。review-work 本身的工作方式是：先在真实产品表面执行手动 QA，再启动1 个门禁评审员（oracle），审计目标合规性、代码质量、安全性、遗漏上下文与 QA 证据；只有"干净的 QA 矩阵 + APPROVE"才算通过。

task( category="unspecified-high", model="gpt-5.6-sol", run_in_background=true, load_skills=["review-work"], description="Run /review-work on all unpublished changes", prompt=""" Run /review-work on the unpublished changes between v{PUBLISHED} and HEAD. GOAL: Review all changes heading into npm publish of oh-my-opencode. These changes span {COMMIT_COUNT} commits across {FILE_COUNT} files. CONSTRAINTS: - This is a plugin published to npm — public API stability matters - TypeScript strict mode, Bun runtime - No `as any`, `@ts-ignore`, `@ts-expect-error` - Factory pattern (createXXX) for tools, hooks, agents - kebab-case files, barrel exports, no catch-all files BACKGROUND: Pre-publish review of oh-my-opencode, an OpenCode plugin with 1268 TypeScript files, 160k LOC. Changes since v{PUBLISHED} are about to be published. The diff base is: git diff v{PUBLISHED}..HEAD Follow the /review-work skill flow exactly — run the manual QA phase, launch the gate reviewer, and collect its verdict. Do NOT skip the QA phase or the reviewer. """)

注意约束条件本身就是仓库的工程规范沉淀：TypeScript strict mode + Bun 运行时、禁止as any/@ts-ignore/@ts-expect-error、工具/钩子/agent 采用工厂模式（createXXX）、文件用 kebab-case、barrel 导出、禁止 catch-all 文件——这些都可以在 oracle.ts 的createOracleAgent工厂实现与 builtin-agents.ts 的注册模式中得到印证。

5.3 Layer 3：oracle 发布综合（1 个）

oracle 拿到全貌——全部 commit、完整 diff stat、变更文件清单，负责聚焦评审可能漏掉的"鸟瞰视角"。

task( subagent_type="oracle", model="gpt-5.6-sol", run_in_background=true, load_skills=[], description="Oracle: overall release synthesis and version bump recommendation", prompt=""" <review_type>RELEASE SYNTHESIS — OVERALL ASSESSMENT</review_type> <project>oh-my-opencode (npm package)</project> <published_version>{PUBLISHED}</published_version> <local_version>{LOCAL}</local_version> <all_commits> {ALL COMMITS since published version — hash, message, author, date} </all_commits> <diff_stat> {DIFF_STAT — files changed, insertions, deletions} </diff_stat> <changed_files> {CHANGED_FILES — full list of modified file paths} </changed_files> <full_diff> {FULL_DIFF — the complete git diff between published version and HEAD} </full_diff> <file_contents> {Read and include full content of KEY changed files — focus on public API surfaces, config schemas, agent definitions, hook registrations, tool registrations} </file_contents> You are the final gate before an npm publish. 10 ultrabrain agents are reviewing individual changes and the review-work gate reviewer is doing the holistic review. Your job is the bird's-eye view that those focused reviews might miss. SYNTHESIS CHECKLIST: 1. **Release Coherence**: Do these changes tell a coherent story? Or is this a grab-bag of unrelated changes that should be split into multiple releases? 2. **Version Bump**: Based on semver: - PATCH: Bug fixes only, no behavior changes - MINOR: New features, backward-compatible changes - MAJOR: Breaking changes to public API, config format, or behavior Recommend the correct bump for each release layer and the overall workflow with specific justification. 3. **Breaking Changes Audit**: Exhaustively list every change that could break existing users. Check: - Config schema changes (new required fields, removed fields, renamed fields) - Agent behavior changes (different prompts, different model routing) - Hook contract changes (new parameters, removed hooks, renamed hooks) - Tool interface changes (new required params, different return types) - CLI changes (new commands, changed flags, different output) - Skill format changes (SKILL.md schema changes) 4. **Migration Requirements**: If there are breaking changes, what migration steps do users need? Is there auto-migration in place? 5. **Dependency Changes**: New dependencies added? Dependencies removed? Version bumps? Any supply chain risk? 6. **Changelog Draft**: Write a draft changelog entry grouped by: - feat: New features - fix: Bug fixes - refactor: Internal changes (no user impact) - breaking: Breaking changes with migration instructions - docs: Documentation changes 7. **Deployment Risk Assessment**: - SAFE: Routine changes, well-tested, low risk - CAUTION: Significant changes but manageable risk - RISKY: Large surface area changes, insufficient testing, or breaking changes without migration - BLOCK: Critical issues found, do NOT publish 8. **Post-Publish Monitoring**: What should be monitored after publish? Error rates, specific features, user feedback channels. OUTPUT FORMAT: <verdict>SAFE / CAUTION / RISKY / BLOCK</verdict> <recommended_version_bump>PATCH / MINOR / MAJOR</recommended_version_bump> <layer_specific_version_bump>omo pure components: PATCH/MINOR/MAJOR; omo opencode: PATCH/MINOR/MAJOR; omo codex: PATCH/MINOR/MAJOR</layer_specific_version_bump> <version_bump_justification>Why this bump level</version_bump_justification> <release_coherence>Assessment of whether changes belong in one release</release_coherence> <breaking_changes> Exhaustive list, or "None" if none. For each: - What changed - Who is affected - Migration steps </breaking_changes> <changelog_draft> Ready-to-use changelog entry </changelog_draft> <deployment_risk> Overall risk assessment with specific concerns </deployment_risk> <monitoring_recommendations> What to watch after publish </monitoring_recommendations> <blocking_issues>Issues that MUST be fixed before publish. Empty if SAFE.</blocking_issues> """)

oracle 的输出格式是整个门禁的"终审判决书"：verdict扩展到四档（SAFE/CAUTION/RISKY/BLOCK），并给出逐发布层的版本建议、可复用的 changelog 草稿、部署风险与发布后监控建议。

为什么 oracle 需要喂入文件内容？反模式表明确写道 "Not reading file contents for Oracle (it cannot read files)" 属于 HIGH 级违规——因为从 oracle.ts 的实现看，oracle 被禁用了write/edit/apply_patch/task工具且为只读 subagent（prompt 中明确 "You are read-only. You advise; others execute."）。因此必须在 prompt 的<file_contents>段把关键文件内容（公共 API 面、配置 schema、agent 定义、hook 注册、工具注册）直接带进去。

六、Phase 3：收集结果

随着后台 agent 完成（系统通知），通过background_output(task_id="...")逐个收集输出，并在表格中跟踪完成度：

硬性约束：所有 agent 完成之前，不得交付最终报告。

七、Phase 4：最终裁决与报告

7.1 裁决逻辑（verdict_logic）

7.2 最终报告模板

技能提供了可直接套用的报告骨架，包含以下板块：

# Pre-Publish Review — oh-my-opencode ## Release: v{PUBLISHED} -> v{LOCAL} **Commits:** {COMMIT_COUNT} | **Files Changed:** {FILE_COUNT} | **Agents:** {AGENT_COUNT} ## Overall Verdict: SAFE / CAUTION / RISKY / BLOCK ## Recommended Version Bump: PATCH / MINOR / MAJOR {Justification from Oracle} ## Layer-specific Version Recommendation | Layer | Recommendation | Reason | |---|---|---| | omo pure components | PATCH/MINOR/MAJOR | ... | | omo opencode | PATCH/MINOR/MAJOR | ... | | omo codex | PATCH/MINOR/MAJOR | ... | ## Per-Change Analysis (Ultrabrains) | # | Change Group | Verdict | Risk | Breaking? | Blocking Issues | |---|-------------|---------|------|-----------|-----------------| | 1 | {name} | PASS/FAIL | SAFE/CAUTION/RISKY | YES/NO | {count or "none"} | | ... | ... | ... | ... | ... | ... | ### Blocking Issues from Per-Change Analysis {Aggregated from all ultrabrains — deduplicated} ## Holistic Review (Review-Work) | # | Review Area | Verdict | Confidence | |---|------------|---------|------------| | 1 | Manual QA (orchestrator, real surface) | PASS/FAIL | - | | 2 | Gate Review (goal, code quality, security, context, QA audit) | APPROVE/REJECT | HIGH/MED/LOW | ### Blocking Issues from Holistic Review {Aggregated from review-work} ## Release Synthesis (Oracle) ### Breaking Changes {From Oracle — exhaustive list or "None"} ### Changelog Draft {From Oracle — ready to use} ### Deployment Risk {From Oracle — specific concerns} ### Post-Publish Monitoring {From Oracle — what to watch} ## All Blocking Issues (Prioritized) {Deduplicated, merged from all three layers, ordered by severity} ## Recommendations {If BLOCK/RISKY: exactly what to fix, in priority order} {If CAUTION: suggestions worth considering before publish} {If SAFE: non-blocking improvements for future}

报告的两条收尾纪律：所有阻塞问题跨三层去重合并、按严重度排序；建议部分按最终裁决分档给出——BLOCK/RISKY 必须给出按优先级排列的修复清单，CAUTION 给出发布前值得考虑的建议，SAFE 则仅记录面向未来的非阻塞改进。

八、反模式清单（Anti-Patterns）

技能最后列出执行门禁时最常见的违规及其严重度，是直接可用的 QA 检查表：

前三条 CRITICAL 全部指向并发与完整性：门禁之所以是"12-agent"，正是靠并行深挖换取覆盖率；任何一步串行化或提前收尾都会让门禁失效。这也解释了为什么 publish 技能 会单独设立"NO EARLY TURN-END"完成契约——发布与审查两个流程都极度强调"走到终局再收轮"。

九、发布链路闭环：审查与 ship-only 发布的配合

pre-publish-review不是孤立流程。将它与 publish 技能 对照阅读，可以看到完整发布链路的边界设计：

• 触发边界：发布请求（publish/release/deploy/npm publish）直接走/publish的 ship-only 工作流，禁止混入/pre-publish-review、/review-work或任何代码复审；反之，只要用户明确要求"发布前审查"，就必须走完整 12-agent 门禁。二者通过触发词严格互斥。
• 发布面一致性：/publish的"三个发布面"验证（omo pure components的载荷内变更、omo opencode的 npm 包 + GitHub release、omo codex的lazycodex-ai+ marketplace 同步）与pre-publish-review的 Release Layer 分类一一对应——审查时逐层做的版本决策，就是发布时逐层要验证的证据。
• 版本输入：/publish要求用户显式提供patch/minor/major或合法 semver（含预发布如5.0.0-beta.9），否则立即停止询问；这与 oracle 基于破坏性变更审计给出的版本建议直接衔接——审查层"建议 bump"，发布层"接收 bump 并执行"。
• 完成契约：发布触发后必须驱动工作流到终局（gh run view <id> --json conclusion返回 success、release 存在、增强版 release notes 已应用、Discord 公告已发送、npm 版本已验证），任何一环未绿不得收轮——与审查门禁"所有 agent 完成前不得交付报告"是同一套纪律在发布侧的体现。

从仓库结构看，.agents/与.opencode/下的技能/命令保持了字节级同步副本（例如 .agents/skills/pre-publish-review/SKILL.md 与 .opencode/skills/pre-publish-review/SKILL.md，.agents/command/get-unpublished-changes.md 与 .opencode/command/get-unpublished-changes.md），确保无论 agent 从哪一侧加载技能，行为都一致——这本身就是发布门禁所依赖的"单一事实来源"原则在技能分发层的落地。

如果你正维护一个 npm 发布的多 agent 项目，这套模式完全可以迁移复用：一个"变更发现"命令 + 三层并行评审（逐变更深入、整体审查、全局综合）+ 结构化 XML 输出 + 四档裁决逻辑 + 反模式清单，就是一套可审计、可复现、可量化的发布前质量门禁。

• 人工智能
• AI Agent
• 代码智能体
• 多智能体
• MCP Clients
• Agent 编排