vibe

Vibe 治理运行时入口

本文件是面向宿主的标准操作流程（SOP），用于进入规范的 vibe。保持内容简洁：运行时细节见 protocols/runtime.md，执行规范见 protocols/do.md，宿主包装器配置方法见安装器生成的包装器文档。

触发约定

当用户明确调用 $vibe、/vibe 或 vibe 技能，或者宿主有意为复杂任务选择受治理的需求／计划／执行闭环时，应在常规执行前进入规范的 vibe。

不要把所有宽泛相关的任务都导入 vibe。除非用户明确调用此入口，否则轻量问题、单命令检查，或更适合由其他明确指定的技能处理的任务，可以在 vibe 之外进行。

已安装副本的更新应在同一受管理目录上使用 update --skills-dir <skills-dir>。

用户指令（包括 CLAUDE.md、GEMINI.md、AGENTS.md 以及 TDD 例外等直接工作流限制）具有最高优先级。在这些限制范围内保留规范的启动与验证规则。

规范引导

vibe 是一种与宿主语法无关的技能契约。规范启动前，只执行启动所需的最少操作：

• 解析 skill_root 和 workspace_root。
• 将当前用户任务原样作为任务规范传入；可以排除无关的聊天历史。不要总结、改写或缩减为关键词。保留确切的输入路径、输入不可变约束、确切的输出根目录、合成数据的证据边界、模块依赖与安全并行边界，以及验收标准。

启动前，不要在当前工作区、代码库或安装根目录中搜索规范验证文件。 在规范启动返回前，不要检查代码库、协议文档或以往运行输出。 不要模拟阶段，不要声称仅凭阅读本文件或包装器文本就已规范进入，也不要将包装器或 AGENTS 文本视为验证依据。 不要手动创建 outputs/runtime/vibe-sessions/<run-id>/。 不要将 Vibe 安装根目录用作受治理的产物根目录。

本地技能候选审计：语义所有者 packages/runtime-core/src/vgo_runtime/router_contract_runtime.py；兼容桥接 scripts/router/resolve-pack-route.ps1

审计在规范的 vibe 中运行，并提供候选项供检查。继续执行时，应包含工作类型、领域／技术、交付物、明确约束和已验证的冻结事实。其输出仅作为兼容性证据；技能选择、绑定和阶段推进由 Agent 负责。

规范入口命令格式：

$env:PYTHONPATH = "<skill_root>/apps/vgo-cli/src"
py -3 -m vgo_cli.main canonical-entry --repo-root "<skill_root>" --artifact-root "<workspace_root>" --prompt "<current user task, verbatim>"

对于 PowerShell，不要将 $env:PYTHONPATH=... 放在双引号括起的 -Command 字符串中；宿主插值可能会将其破坏为 :PYTHONPATH。

类似 Bash 的宿主（包括 Claude Code）应在外层 Shell 中设置 PYTHONPATH，并直接调用 Python。根据可用情况依次尝试 py -3、python，再尝试 python3。

REPO_ROOT='<skill_root>'
WORKSPACE_ROOT="${WORKSPACE_ROOT:-$PWD}"
PYTHONPATH="$REPO_ROOT/apps/vgo-cli/src" python -m vgo_cli.main canonical-entry --repo-root "$REPO_ROOT" --artifact-root "$WORKSPACE_ROOT" --prompt "<current user task, verbatim>"

--host-id 和 --entry-id 仅为包装器或旧版自动化保留的兼容参数；常规启动时省略。

只有在规范入口返回 session_root 后，才验证规范验证产物。 check 只能证明 installed locally；运行时一致性与交付验收需要各自的证据。 规范启动的证明发生在启动后，并要求返回的 session_root 下存在 host-launch-receipt.json、runtime-input-packet.json、governance-capsule.json 和 stage-lineage.json。 local-agent-kernel 遵循相同的证明规则。如果它无法生成这些真实产物，可以生成本地工作脚手架，但不得将其视为 canonical verified。 如果规范启动失败，应报告 blocked 并说明具体失败原因，而不是模拟缺失的阶段或证明产物。

共识与任务演进

持续使用 deep_interview，直到用户和 Agent 就目标、范围、约束、交付物、相关未知事项和完成标准达成一致。确认该任务专属摘要后，冻结需求；首次澄清是对话的输入。

将共识保留在现有 TaskCard 中。追加已接受的修订，更新受影响的工作和检查项，并且仅在其输入和验收标准仍然有效时复用结果。凡是会改变已商定结果、范围、风险或所需人工判断的决策，都应明确指出。

硬性停止与重新进入

渐进式治理停止点为 requirement_doc、xl_plan 和 phase_cleanup。

当 bounded_return_control.explicit_user_reentry_required = true 时，停止当前助手回合。除非后续用户消息批准或修订当前边界，否则不要使用重新进入凭证。

这是硬性运行时边界，不是建议。它优先于“持续执行直到完成”等常规主机自主规则。详细的原始请求不等于对冻结需求或冻结计划的批准。硬性停止后，不要在同一助手回合中通过治理流程之外的方式执行等效的人工工作：不得编写计划、执行任务、交付手动变通方案或交付最终成果。

重新进入时，检查 runtime-summary.json -> bounded_return_control.host_decision_contract，推断用户意图，并编写结构化的主机决策 JSON 文件。使用相同的 run_id、bounded_reentry_token 和稳定的 workspace_root：

在需求停止点，直接根据 agent_skill_organization_contract 构建 agent_skill_organization；在此之前，preferred_payload 并不完整，且不得通过失败重试或检查运行时源代码来了解架构。 使用引导阶段的相同 REPO_ROOT 和 WORKSPACE_ROOT：

DECISION_JSON="$WORKSPACE_ROOT/.vibeskills/tmp/host-decision.json"
mkdir -p "$(dirname "$DECISION_JSON")"

cat > "$DECISION_JSON" <<'JSON'
{
  "decision_kind": "approval_response",
  "decision_action": "approve_requirement",
  "approval_decision": "approve",
  "agent_skill_organization": {
    "schema_version": "agent_skill_organization_v1", "derived_by": "agent", "workflow_level": "L",
    "modules": [{"module_id": "module-a", "goal": "...", "candidate_skill_ids": ["skill-a"], "depends_on": [], "execution_mode": "skill_assigned", "acceptance_criteria": [{"criterion_id": "module-a-result", "description": "The module result satisfies the frozen requirement.", "verification_mode": "automated"}]}],
    "selected_skills": [{"skill_id": "skill-a", "module_ids": ["module-a"], "responsibility": "...", "reason": "..."}],
    "uncovered_modules": [],
    "workflow_level_contract": {"L": "smallest complete organization", "XL": "bounded multi-lane organization"}
  }
}
JSON

PYTHONPATH="$REPO_ROOT/apps/vgo-cli/src" py -3 -m vgo_cli.main canonical-entry \
  --repo-root "$REPO_ROOT" \
  --artifact-root "$WORKSPACE_ROOT" \
  --prompt "<current user task, verbatim>" \
  --continue-from-run-id "<source_run_id>" \
  --bounded-reentry-token "<reentry_token>" \
  --host-decision-json-file "$DECISION_JSON"

后续用户消息中的结构化批准会推进到下一个渐进式停止点。结构化修订必须包含非空的 revision_delta，并重新冻结同一有界阶段，无需先单独征求用户批准：

{
  "decision_kind": "approval_response",
  "decision_action": "revise_requirement",
  "approval_decision": "revise",
  "revision_delta": ["Use the revised dataset and agreed output scope."]
}

有界批准或修订必须遵守已说明的有界阶段操作约定。

在 requirement_doc 阶段，读取 runtime-summary.json -> host_user_briefing，并以 host_user_briefing.rendered_text 为用户回复的主干。保持相同的字段顺序。 围绕由 Agent 主导的技能搜索指南来说明该停止点：将任务拆分为模块，针对每个模块搜索本地技能，阅读候选 SKILL.md，整理 L / XL 计划，并如实说明未覆盖的模块。在冻结需求时，不要透露候选名单规模、已选技能排名或原始路由顺序。 在回复说明各选项对应的任务专属工作流并列出该选项的任务专属候选技能名称之前，不要让用户选择 L 或 XL。每个列出的技能都必须标明为尚未选中或使用的候选技能；正式选择仍须由需求获批后生成的 Agent 组织方案完成。 需求获批后，Agent 必须将获批的工作拆分为多个模块，针对每个模块搜索所有声明的本地 Skill 根目录，并阅读每个保留候选项的 SKILL.md。进入 xl_plan 前，宿主必须将验证后的结果写入 HostDecisionJson.agent_skill_organization；路由输出可以作为候选项审计证据保留，但不能填入此字段。如果一个选定的 Skill 负责多个模块，则必须为每个模块添加一条 module_assignments，包含准确的模块 ID、owner、support 或 verifier 角色、模块专属职责、一个具体的写入范围、预期输出和验证方式。角色顺序具有执行效力：support 先运行并向 owner 提供支持；verifier 只能在 owner 之后运行。owner 之后的审查或最简性检查必须使用 verifier，不能使用 support。agent_direct 模块必须声明自己的具体 write_scope、expected_outputs 和 verification；运行时不得用通用模块标签或复述目标来替代这些内容。任务工作范围不得声称拥有 module-execution.json 等规范运行时产物；应使用稳定的任务自有输出范围，或在只读工作时填写 no task-file writes。如果计划修订更改了模块、Skills、角色、依赖关系、写入范围、输出、验证方式或工作流级别，则必须重新提交完整的更新后 agent_skill_organization；revision_delta 只记录文本，不会修改已冻结的组织结构。 将直接包含保留的 SKILL.md 的目录名用作 candidate_skill_ids 和 selected_skills[].skill_id 中的准确 skill_id。显示的 Skill 名称或 frontmatter 中的 name 是描述性信息，不是执行标识符。嵌套的保留 SKILL.md 使用其所在目录的名称。提交前应根据候选路径解析此标识符，不要等到重试失败后才确定。 模块验收标准必须能在重新进入规范模块结果流程之前满足。不得要求清理回执、交付验收或允许使用完成性措辞，因为只有在接受 module-execution.json 后，规范的 phase_cleanup 才会生成这些内容。应根据实际交付物以及常规命令或测试输出验证普通模块。不要仅为证明执行顺序、Skill 使用情况或文件范围而臆造特定于任务的哈希、回执、台账、矩阵、扫描或证明文件。只有当用户或领域契约需要额外证据产物时，才要求提供该产物。 计划获批后，plan_execute 和清理阶段必须复用已冻结的 agent_skill_organization，不得重新运行程序化 Skill 选择、悄悄添加 Skills，或替换已声明的缺口，除非用户修订了已冻结的需求或计划。stage_order 记录依赖深度，不代表可以并行运行；即使独立单元共享依赖阶段，L 仍会按每波一个单元顺序执行。XL 每波最多可安排两个依赖已就绪的单元；嵌套或重叠的写入范围必须串行执行。

完成所需的计划确认后，继续执行依赖已就绪的工作，不要在单元之间为常规操作征求许可。在重要节点提供简洁的进度更新。如果用户修订了已达成一致的任务，则记录修订，并仅针对受影响的工作重新规划，然后继续。

统一运行时契约

规范的 vibe 拥有唯一的运行时权威和唯一对用户可见的需求／计划界面。固定状态机如下：

1. skeleton_check
2. deep_interview
3. requirement_doc
4. xl_plan
5. plan_execute
6. phase_cleanup

对于简单任务，这些阶段可以简化，但不得悄然跳过。 完整的运行时契约、阶段职责、溯源规则、内部 M／L／XL 等级、对用户可见的 L／XL 工作流确认、清理规则和输出清单均定义在 protocols/runtime.md 中。

vibe 是唯一的公共包装入口。已安装副本的更新使用上文所述的命令路径。

兼容性阶段包装器仅供内部使用。如果旧版调用方仍发送此类包装器，则应在启动运行时之前将其折叠为规范的 vibe，并将其排除在宿主可见的技能界面之外。

技能执行

冻结的 agent_skill_organization 是任务技能的唯一依据。在计划获批之前，须披露模块、候选项、已选技能及其原因、缺口，以及 L／XL 之间的差异。

将每个已确认模块组织为可验证的工作单元。使用已声明的 Skill 输出来确定职责归属，用 plan_hints 来安排工作步骤，并用 verify_hints 来扩展模块检查。保留明确的模块依赖关系；对于没有合适 Skill 的模块，将 agent_direct 保留为显式回退方案。每个工作单元都必须在现有 WorkPlan 中保留其预期输出、检查项、绑定原因和依赖链接。每项已绑定的任务都必须将这些字段和所选 Skill 的指导投射到现有的 ModuleAssignments 构件中。

只有已选技能才能成为绑定到模块的执行单元。宿主不得臆造技能、将路由候选项提升为已选技能、隐藏技能会话，也不得另行创建需求／计划／运行时界面。选择、加载、规划、派发或通用清单均不能作为贡献证明；只有取得可观察的模块结果并通过 protocols/runtime.md 中定义的模块验收，才算完成。计划获批后，module-work-plan.json 是唯一的派发依据。agent-execution-handoff.json.result_contract 会冻结 module_execution_v1 提交绑定；移交后，复制 result_contract.submission_template，保留所有冻结的绑定，仅填写结果字段。criterion_results 状态必须严格为 passing、failing 或 blocked。如果规范流程在清理前拒绝格式，应修正同一个 module-execution.json 并重复使用同一条返回命令，而不是创建另一份移交文件。如果移交模板包含 tdd_evidence，代码任务的 TDD 证据必须放在同一个 module-execution.json 中；在返回规范流程之前填写该结构化部分，不得创建单独的 tdd-evidence.json 旁置文件。契约本身不是执行证据。 Agent 仍须完成实际工作并创建 module-execution.json；若存在必需的失败项、阻塞项、缺失证据或待人工审核，任务就无法完成。

对于 XL 委派，根／子层级仍受治理：只有 root_governed 可以冻结规范需求／计划或作出最终完成声明。 child_governed 通道继承冻结的上下文，限于分配的写入范围内，验证 delegation-envelope.json，并且仅生成本地回执。

质量规则

没有证据，绝不宣称成功。最低要求：

• 完成前先验证。
• 不得默默声称没有回归。
• 确保需求和计划产物可追溯到已启动的运行。
• 阶段完成前，先提供清理回执。
• 明确说明失败、回退、降级状态或阻塞状态。
• 不得添加模拟成功路径、吞掉错误或仅凭模板给出通过结果。
• 将脚手架或草稿产物视为 needs_execution，并设置 proof_ready = false；不得称其为已完成工作。
• 仅当有效任务输入、选定的 Skill 内容、依赖项输出和已交付产物哈希均未改变时，才可复用已完成的工作。在验证前，重新运行受影响的依赖链；当前置条件失败时，阻止依赖项继续执行。
• 不得利用回退或边界行为绕过实际执行、 验证或根因修复。
• 如果确认范围内的检查失败，针对该失败最多进行一次定向修复，并重新运行受影响的检查。如果修复失败、需要决定范围，或缺少所需证据，则报告尚未解决的阻塞项。

用户交付

使用现有的 WorkDossier 作为详细证据来源。向用户提供简短的交付摘要，其中包含经验证的结果、结果所在位置、实际运行的检查以及真实的阻塞项。不要将脚手架纳入已完成结果。内部回执和 诊断细节应保留在 WorkDossier 中，除非它们有助于用户做出决定。

协议索引

仅在规范启动后或维护代码库时阅读以下参考资料：

• protocols/runtime.md：受管运行时契约和阶段职责
• protocols/think.md：规划、研究和执行前分析
• protocols/do.md：编码、调试和验证
• protocols/review.md：审查和质量门禁
• protocols/team.md：XL 多 Agent 编排
• protocols/retro.md：回顾与基于证据的修正

维护信息

• 运行时系列：受管运行时优先
• 版本：4.1.1
• 更新日期：2026-10-18
• 主要契约元数据：core/skill-contracts/v1/vibe.json