🔎 Existing issue check
这是 #299 的后续改进,不重新申请父子 Change、依赖关系、readyChildren 或父级最终 Verify 的基础能力。
本 Issue 将 Supervisor 升级为 integration-first、可选多 Agent 加速的 Native 父级模式:
Runtime 管依赖、工作区、验证事实、串行集成和恢复;宿主只负责派发 Agent。多 Agent 可用时并行,不可用时按相同 Runtime 语义顺序执行。
它不是新的 Agent Team、通用 DAG 平台或 worker scheduler。
🧭 Problem
在 beta20 使用 self-evolving-memory-team-contracts 父级 Change 实际推进插件运行时、个人记忆、项目规则、Dashboard 和宿主接入时,当前 Supervisor 模式证明了独立 worktree、依赖顺序、Child 独立 Verify 和父级最终 Verify 的价值,但也暴露出明显的用户体验和 Runtime 建模问题。
1. “已集成”和“已归档”被合并成一个状态
当前 Child 只有完成 Archive 并合入父分支后才算 done。这导致:
- Child 已被移动到 Archive,但父级仍然活跃;
- 每个 Child 都触发一次 Archive、merge、目标工作区 clean 检查和父级刷新;
- unrelated dirty files 会反复阻塞 Child 收尾,而不是只在父级最终交付时检查一次;
- 用户无法区分“实现和独立验证已经完成”“已经进入父级集成结果”和“整个需求已经交付”。
2. 父级直接使用真实目标分支作为集成分支
本次父级的 change branch 与 target branch 都是 beta20。前四个 Child 合入后,父级第一次整体验证仍有 169/333 项失败,但真实目标分支已经包含不完整的组合结果。随后又追加 memory-rules-host-integration-repair 才完成宿主接入。
父级需要一个专用 integration branch/worktree。Child 只能合入该集成分支;父级整体验证通过前,真实目标分支不应发生变化。
3. 用户能力、实施 Child 和验收映射混在一起
本次父级有 3 个目标 Spec、多个领域 Child、横向集成 Child 和修复 Child。这个数量差异本身合理:Spec 描述用户能力,Dashboard、Skill/CLI 或宿主接入可以是横向实施工作。
但当前 children.yaml 使用位置型 A1...An 和逐项 covers。最终归档文件达到 546 行,512 条覆盖记录只对应 333 个唯一验收项。大量映射没有避免宿主接入遗漏,反而增加了维护、上下文和输出成本。
4. 多 Agent 目前只是 Skill 约定,不是稳定交接
当前 Skill 已要求支持时并行推进 readyChildren,不支持时顺序执行,但 Runtime 只提供 Child 列表和派生状态:
- 没有面向宿主 Agent 的精简任务包;
- 父级协调者、Child Builder 和独立 Verifier 的责任边界不明确;
- Child Agent 如果还需要自行启动 Verifier,会依赖宿主是否支持嵌套 Agent;
- Agent 返回的文字结果可能被误当成 Runtime 事实;
- 恢复时缺少最小的重复派发和迟到回报保护。
Comet 需要接入宿主原生 Agent 能力,但不应因此引入共享任务列表、mailbox、claim、lease、heartbeat 或通用 scheduler。
5. Runtime 内部流程泄漏给 Skill 和用户
正常推进过程中出现了多次无决策价值的“继续”,并暴露 runner-input 临时 JSON、candidate、iteration、attempt、Agent 运行标识、Archive preview/finish 等内部步骤。
用户主要通过 Comet Skill 使用能力,这些细节应由 Runtime 和 Skill/宿主协调层吸收。只有产品范围变化、合并冲突、外部授权、无法保护用户文件或配置要求最终确认时才暂停。
6. 父级验证结果存在不必要的精确感
最终 333/333 passed 混合了不同层级的证据:
- Child 自己已经完成的领域验证;
- 父级 integration worktree 实际重新执行的检查;
- 没有重新运行、只继承 Child 验证记录的结果;
- 超时、环境阻塞或未完成检查。
当前父级 Builder 还可以用 checks=[] 和统一理由覆盖全部验收项。父级报告应展示证据来自哪里,而不是把所有条目展平为同一种“通过”。
7. 跨模块接入没有在 Shape 阶段明确负责人
初始 Child 分别负责领域模块,但正常 Comet workflow、Skill/CLI fallback、Git 同步、规则验证循环等横向连接没有明确实施责任,直到父级 Verify 才集中暴露。
最终 Verify 应负责收口,不应第一次发现大面积连接缺失。
✨ Proposed solution
术语约定
本 Issue 只保留下面这些必要概念;代码可以沿用现有内部类型名,但面向开发者的设计和状态输出统一使用这里的说法。
| 术语 |
本 Issue 中的含义 |
| Supervisor / 父级 Change |
代表一个完整用户目标,负责安排 Child、汇总验证并最终交付。 |
| Child |
父级拆出的一个可独立实现和验证的普通 Native Change。 |
| integration branch/worktree |
父级专用的临时集成分支和工作目录。Child 只合入这里;父级最终验证通过前不修改真实 target。 |
verified |
Child 已在某个明确 commit 上通过独立验证,但还没有合入父级集成分支。 |
integrated |
该 verified commit 已合入父级集成分支,并通过必要的集成检查。 |
| Agent task |
Runtime 交给一个 Agent 的单次工作,角色只有 Builder 或 Verifier,并绑定一个 Child worktree。 |
runId(替代旧称 taskToken) |
业界常用的“单次执行 ID”。Runtime 每次派发 Agent task 时生成;返回结果必须携带当前 runId,旧结果或重复结果会被忽略。它不是权限凭证,也不证明 Verifier 独立性。 |
| Child 验证记录 |
Runtime 生成并绑定具体 verified commit 的结构化验证结果。现有实现内部仍可使用 receipt 类型名,但 Issue 和用户输出不再单独引入 receipt 概念。 |
| 修复 Child |
父级 Verify 失败后,为现有失败项新增的普通 Child;它只修复已确认范围,不改写已经完成的 Child。 |
| 最终权威 Specs |
父级最终交付后写入 docs/comet/specs、供后续 Change 继续引用的正式规格。Child 的范围规格只作为本次实施历史保存。 |
| 恢复日志 |
Runtime 记录 merge、归档和清理各步骤是否完成的机器日志,用于进程中断后从未完成步骤继续。实现可以使用 journal,但用户不需要看到该名称。 |
summary / details / history |
status 默认返回 summary 简洁摘要;排查时读取 details 或 history。长列表的 JSON API 使用标准 cursor pagination:响应返回 nextCursor,调用者用它请求下一页;Skill 用户只看到“还有更多详情”,不需要操作 cursor。 |
| 可移植状态(Portable State) |
可以进入 Git、用于跨设备恢复的 Change 状态;本机 Agent run、进程和临时文件不属于可移植状态。 |
needs-reverify |
Runtime 能恢复 Child 和 commit,但缺少可复用验证记录,因此必须重新 Verify。 |
用户最终体验
Skill 在创建、恢复、Agent/Child 状态变化和父级验证后,都显示同一份简洁摘要:
self-evolving-memory-team-contracts Verify passed
├─ plugin runtime Integrated
├─ personal memory Integrated
├─ project rules Integrated
├─ dashboard Integrated
└─ host integration Integrated
Agents
├─ working 0
└─ completed 5
Checks
├─ Child verification 5/5 fresh
├─ Parent integration checks 38 passed
└─ Full suite incomplete: timeout
Next: final delivery
正常消息不显示完整验收编号、临时 JSON、Runtime 文件名、runId 或 Agent 运行标识。
1. children.yaml v2 只保留可读实施计划
新增 comet.native.children.v2,只保留名称、摘要和真实依赖:
schema: comet.native.children.v2
children:
- name: comet-plugin-runtime
summary: 提供第一方和第三方插件的统一运行时
depends_on: []
- name: personal-memory
summary: 实现个人记忆领域能力
depends_on: [comet-plugin-runtime]
- name: host-integration
summary: 接通 Skill、CLI、workflow 和端到端验证
depends_on: [personal-memory, project-rules, dashboard]
Runtime 只做确定性校验:
- Child 名称唯一且合法;
depends_on 引用存在;
- 依赖无环;
- 已 integrated Child 的名称、摘要和历史依赖不可被静默改写;
children.v1 继续可读,已归档 v1 永不重写。
summary 用用户语言说明实施责任,不增加 covers、owns、位置型验收映射或新的用户可见 ID。父级完整目标仍以 brief 和 Specs 为准,由 Shape 做语义拆分确认,由父级 Verify 做最终完整验收。
本 Issue 不改变 Native 验收项的身份模型。现有 A1...An 可继续作为 Runtime 内部兼容字段,但不再进入 children.v2 或默认状态输出。命名验收场景若仍有独立价值,应另行设计,不与 Supervisor integration-first 绑定交付。
2. Shape 明确横向集成责任,但不建立 机器可解析的职责规则
Skill 在确认拆分前执行一次集成责任检查:
- 如果目标跨越两个及以上领域模块、Skill/CLI、Dashboard、Hook 或 workflow,必须由某个现有 Child 的
summary 明确负责,或增加一个小型 integration Child;
- integration Child 依赖相关领域 Child,只负责连接、fallback 和端到端验证,不吞并领域实现;
- Child 数量不需要和 Spec 数量一致;
- 需求文字长、验收项多本身不能触发拆分;
- 用户只确认一次父级 Shape;严格派生的 Child 不重复确认相同范围。
这是 Shape 的语义检查,不由 Runtime 解析 Markdown 标题或强制唯一文件 owner。
父级 Verify 失败后,可以追加处理现有失败项的修复 Child。只要没有新增用户可见范围或产品决定,就不要求用户重新确认;如果范围或决定变化,仍返回父级 Shape。已 integrated Child 的历史不可改写。
3. 分离 Child Verify、Integrate 和 Archive
Supervisor v2 使用以下父级派生状态:
pending → ready → active → verified → integrated
└──────────────→ blocked
parent final delivery → archived
verified:Child 候选和独立验证已经通过,verified commit 已确定,但尚未进入父级 integration branch;
integrated:父级集成器已将 verified commit 串行合入 integration branch,并校验结果;
archived:只有父级最终交付成功后,父级和全部 Child 才统一进入 Archive。
默认用户摘要可将 pending/ready 合并显示为“等待”,将 active/verified 合并显示为“工作中”;详细状态仍保留确定性语义。
Standalone Native Change 和 v1 Child 继续使用原 Archive 语义。该扩展只适用于新建的 Supervisor v2。
4. 父级拥有专用 integration branch/worktree
父级 Shape 确认后,Runtime:
- 记录真实 target branch 的起始 commit;
- 创建专用 integration branch/worktree;
- 从当前 integration HEAD 创建 ready Child 的独立 branch/worktree;
- Child Verify 通过后记录 verified commit;
- 父级集成器串行把 verified commit 合入 integration branch;
- 后继 Child 只有在全部依赖 integrated 后才变为 ready,并从包含依赖结果的 integration HEAD 开始;
- 所有 Child integrated 后,在 integration worktree 运行父级 Verify;
- 父级通过后按
native.archive_confirmation: automatic | required 自动继续或最多确认一次,再统一交付到真实 target。
Runtime 在 Child 创建、验证、集成和最终交付时校验 Git commit 与祖先关系,不能只相信 Agent 报告或 Archive 文件。
集成操作使用短事务锁、Git 引用比较更新和恢复日志,保证中断后不会重复 merge。这是集成安全,不是通用 worker 调度器。
真实 target 在父级最终交付前保持不变。若 target 已产生新 commit,Runtime 将最新 target 重新带入 integration worktree,并重新运行父级 integration checks;不尝试推断“只受影响的部分”。target dirty 和最终合并条件只在最终交付边界处理一次。
5. 使用宿主原生 Agent,但由父级统一协调
多 Agent 是可选加速层。父级协调 Agent 始终保留最终责任,并统一派发 Child Builder 与独立 Verifier,Child Agent 不需要再创建嵌套 Agent。
Runtime/continuation 为当前可执行工作返回精简的内部任务包:
interface NativeSupervisorAgentTask {
role: "builder" | "verifier";
child: string;
projectRoot: string;
baseCommit: string;
runId: string;
}
规则:
builder 只在指定 Child worktree 中推进 Build,达到 Verifier 边界或 blocker 后返回;
verifier 是新的只读 Agent,只验收指定 Child 的当前候选;
- 父级协调 Agent 可以并行派发彼此独立的 Builder 或 Verifier;
- 同一个 Child 同时最多有一个有效任务;
- Agent 之间不直接通信,不共享 mailbox 或宿主任务列表;
- Agent 完成消息只是唤醒信号,Runtime 必须重新读取 Child state、verified commit、Git 状态和Child 验证记录;
runId 只绑定当前 Child、角色、父级状态和 base commit,用于拒绝重复或迟到回报,不证明 Agent 身份或 Verifier 独立性;
- Verifier 独立性继续沿用 Native 现有可信宿主或 skill-coordinated 降级规则,不在本 Issue 中建设新的宿主身份认证协议(provider attestation);
- 宿主返回 Agent 运行标识(例如线程 ID)时可作为本机恢复信息保存,但不作为验收通过依据。
宿主支持原生 Agent 工具时,Skill 按宿主并发上限并行派发;无法获得上限时最多同时派发 2 个。宿主不支持时,同一协调流程按稳定顺序逐项执行,依赖、验证和集成语义不变。
不在平台注册表中硬编码 supportsMultiAgent。能力由当前会话实际可用工具决定,因为同一宿主也可能通过配置关闭 Agent。
恢复时:
- 可恢复的宿主任务优先重新连接;
- 只有宿主确认旧任务已结束或取消后,Runtime 才失效旧 runId 并为同一 Child 发出替代任务;
- 无法确认旧任务是否仍在写入时返回 blocker,不同时启动第二个 Worker;
- 已 verified 或 integrated 的 Child 不会因为协调会话重启而重复派发。
6. 保留 status / next / archive,自动推进无决策步骤
不新增 comet supervisor 命令族,也不把内部 Module 方法变成新的用户概念。
comet native status 返回父级摘要、Child 状态、当前 Agent 任务和按需详情;
comet native next 计算下一批 Builder/Verifier 任务、执行串行集成或进入父级 Verify;
comet native archive 只负责父级最终交付;
- Skill 在一次协调过程中持续执行无决策动作,直到需要真实用户决定、外部授权或遇到 blocker;
- 临时输入文件统一由 Runtime 在
.comet/runtime 内创建、消费和清理;
- Dashboard 只读取同一份
status JSON,不复制 readiness、Agent 或集成状态推导。
Runtime 内部可以抽取更深的 Supervisor Module,但不需要公开 inspect / advance / finish 作为新的产品协议,也不接受一个可以绕过具体动作校验的泛化 result。
7. 默认 status 返回简洁摘要
默认摘要 只包含:
- 父级阶段和整体验证状态;
- Child 总数以及等待、工作中、已集成、阻塞数量;
- 当前 active/blocked Child 的名称、简短职责、实际 worktree 和原因;
- 正在运行的 Agent 数量与对应 Child;
- 下一动作和已知风险;
- 目标 Spec 数量与实施 Child 数量的分别说明。
完整验收项和 Child 验证记录放在 details;状态变化历史与恢复日志放在 history;调试时再显示 Agent 运行标识。默认 status 不内联这些内容。长列表的 JSON API 使用标准 cursor pagination,响应返回 nextCursor,调用者用它读取下一页;Skill 用户只看到“还有更多详情”,无需手动处理 cursor。按父级名称查询时直接定位声明的 Child,不先扫描所有 worktree 的全部 Change。
8. 建立分层验证记录,不再展平全部验收
每个 Child 集成时保存:
- Child 名称和摘要;
- verified commit;
- integration commit;
- Child 验证记录;
- 实际执行的检查及结果引用;
- 未完成检查和已知风险。
父级报告分为:
- Child verification:来自通过验证的准确 commit、且在集成后未漂移的 Child 验证记录;
- Parent integration:在父级 integration worktree 实际重新执行;
- Not rerun:本轮没有重新执行,但保留明确来源和原因;
- Incomplete:超时、环境阻塞或缺少证据。
父级 Verifier 仍需读取完整 brief、Specs、所有 Child 验证记录和最终集成结果,对完整目标作出判断;但默认报告不复制 Child 的全部逐项表格,也不得使用 checks=[] 和同一条泛化理由把所有验收项自动标记为通过。
跨 Child、宿主和 workflow 的结果必须具有父级实际集成验证记录。全量测试超时必须显示为 Incomplete,不能折算为 passed。
9. 一次最终交付和安全清理
父级 Verify 通过后,Runtime 按 native.archive_confirmation 自动继续或最多确认一次,并在一个可恢复流程中:
- 确认 integration HEAD 与父级验证记录一致;
- 确认真实 target 没有未经处理的漂移;
- 由父级唯一发布最终权威 Specs;
- 将 Child scoped Specs、验证记录和 Agent 执行摘要保存为父级 Archive 下的历史,不分别发布最终权威 Specs;
- 将 integration branch 合入真实 target;
- 确认 target 已包含最终结果;
- 统一归档父级和 Child;
- 安全清理不再使用的 Child/integration worktree 与 branch;
- 刷新父级最终状态。
任何步骤中断后都可以恢复且不会重复合并或误删 worktree。存在未提交文件、未合入 commit、当前进程位于待删除 worktree 或合并冲突时,保留现场并返回明确 blocker,禁止强制清理。
#313 中 Archive preview 改变状态并导致重复 Verify 的具体修复继续独立完成;本 Issue 只要求 Supervisor 最终交付调用修复后的统一 Archive 能力。
10. Runtime 文件布局与恢复边界
父级目录只保留用户可读内容:
brief.md
specs/
- 精简后的
children.yaml
- 简洁的最终
verification.md
Supervisor 动态状态、integration worktree 信息、Agent runId、Agent 运行标识、Child 集成记录、验证记录、恢复日志和临时传输文件统一放在:
.comet/runtime/native/changes/<parent>/supervisor/
这些 Runtime 文件不要求提交到 Git。
Runtime 丢失时可以从 children.yaml、父级/Child 用户文档、可移植状态(Portable State)、Git branch/worktree 和已归档结果重建计划、依赖、工作区与集成状态。只有可移植验证记录足以证明准确 commit 的 Child 才恢复为 verified;缺失时进入 needs-reverify 或 blocked。
宿主 Agent 会话本身不是可移植状态:能重连就重连,不能重连就按安全规则取消旧任务并从 Child 当前状态重新派发,不根据 Git 祖先关系猜测 Agent 是否完成。
11. 分阶段实施
该 Feature 可以由一个 Supervisor Change 管理,建议拆成三个可独立评审的 Child/PR:
-
Integration core
children.v2 最小结构与 v1 双读;
- 父级专用 integration branch/worktree;
verified / integrated / archived 生命周期;
- Git 祖先校验、串行集成和一次最终交付;
- 先用单 Agent 完成真实 linked-worktree 全流程。
-
Optional parallel Agents
agentTasks 和 runId;
- 父级统一派发 Builder/Verifier;
- 宿主并行与顺序降级;
- 恢复、取消、重复/迟到回报保护;
- Skill 隐藏内部任务交接。
-
验证记录、状态与恢复
- 默认简洁 status 摘要 与按需详情;
- 分层验证记录;
- 修复 Child;
- Runtime 重建、最终归档和安全清理;
- Dashboard
status JSON 与规模测试。
三个阶段全部完成前,不把 v2 设为默认,避免出现一半使用独立集成、一半仍按 v1 Archive 的混合模式。
🎯 Primary area
Other — Native workflow runtime (domains/comet-native) and bundled Native Skill
🪐 Workflow phase
Not phase-specific
🔀 Alternatives considered
1. 只优化 Skill 文案和状态摘要
可以缓解“看不到 Child”的问题,但不会解决 Child Archive 与集成混淆、真实目标分支提前包含半成品、dirty target 反复阻塞和父级验证证据失真。
2. 保留 v1,每个问题单独打补丁
可以分别修复 status、Archive 和 runner 交互,但这些问题来自相同的生命周期分界。继续叠加补丁会让调用顺序和恢复更加复杂。
3. 使用宿主 Agent Team 或完整多 Agent Scheduler
共享任务列表、Agent 间通信、claim、lease、heartbeat、抢占和自动重试可以构成更通用的多 Agent 平台,但会复制宿主能力,并把 Comet 从 workflow Runtime 扩张成 Agent 调度器。
本 Issue 只使用父级协调者加独立 Builder/Verifier 的一层派发。Agent 不互相通信,Runtime 不管理模型、消息或通用 worker 生命周期。
4. 同时迁移命名验收场景与 机器可解析的职责规则
可以减少位置型 ID 漂移,但与 integration-first 没有必然依赖,会显著扩大 Native acceptance、Verifier、报告、恢复和兼容范围。
本 Issue 通过删除 covers、隐藏默认验收明细和分层报告解决当前用户问题;命名验收模型另行评估。
最终选择:integration-first Supervisor v2 + optional parallel Agents。先让单 Agent 语义可靠,再在相同 Runtime 事实之上并行加速。
🧰 Compatibility notes
- 仅影响 Native Supervisor;Classic 状态机和 Hook Router 语义不变。
- 没有
children.yaml 的普通 Native Change 行为不变。
- 已归档 v1 永不重写;已有 active Child 的 v1 按旧语义完成,并标记为 legacy。
- 只有尚未启动任何 Child 的 v1 可以在用户确认后升级为 v2;不得静默移动分支或改写历史。
children.v1、旧 Verifier response 和旧 status JSON 至少保留一个 beta 周期的读取兼容;JSON 字段语义改变时升级 status schema。
- 多 Agent 能力按当前会话工具检测,不修改 33 平台的 canonical registry 来维护易漂移的静态能力表。
- 新增 Git/worktree 操作继续通过
platform/ Adapter;Windows、macOS 和 Linux 共享同一 Runtime 语义。
- 修改 Native Runtime 后重新生成 Native bundles,并更新
assets/manifest.json 和对应 Runtime 资产测试。
- Native Skill 先更新中文版本,用户语义确认后同步英文版本。
- Dashboard 不新增状态机或编辑能力,只读取 Runtime
status JSON。
- 最终验证包含相关 Native/Skill/Runtime 测试、真实 linked-worktree 与并行 Agent fixture、architecture lint、生成物检查、build,以及一次与风险匹配的全量测试。
🧩 Additional context
Acceptance criteria
User experience
Plan and integration responsibility
Integration lifecycle
Optional parallel Agents
Evidence and reporting
Recovery and compatibility
Suggested implementation ownership
domains/comet-native/:Supervisor plan、Agent tasks、status JSON、integration、evidence、recovery 和 continuation。
platform/paths、platform/process:Git/worktree 的现有 Adapter;不在 domain 内散落平台命令。
app/commands:只组合 Runtime Module,不承载 readiness、Agent 派发、集成或恢复规则。
assets/skills-zh/comet-native/、assets/skills/comet-native/:用户主路径、宿主 Agent 派发、顺序降级和简洁摘要。
domains/dashboard/:仅适配新的只读 status JSON,不复制状态计算。
test/domains/comet-native/:无模型状态、runId、恢复、真实 worktree 和规模测试;Skill、Dashboard、Repository 测试按现有归属补充。
Non-goals
本 Issue 只实现完成 integration-first 所必需的最小 runId 与迟到回报拒绝;真正的 durable multi-agent scheduler 如果以后有明确需求,再单独立项。
🔎 Existing issue check
这是 #299 的后续改进,不重新申请父子 Change、依赖关系、
readyChildren或父级最终 Verify 的基础能力。本 Issue 将 Supervisor 升级为 integration-first、可选多 Agent 加速的 Native 父级模式:
它不是新的 Agent Team、通用 DAG 平台或 worker scheduler。
🧭 Problem
在 beta20 使用
self-evolving-memory-team-contracts父级 Change 实际推进插件运行时、个人记忆、项目规则、Dashboard 和宿主接入时,当前 Supervisor 模式证明了独立 worktree、依赖顺序、Child 独立 Verify 和父级最终 Verify 的价值,但也暴露出明显的用户体验和 Runtime 建模问题。1. “已集成”和“已归档”被合并成一个状态
当前 Child 只有完成 Archive 并合入父分支后才算
done。这导致:2. 父级直接使用真实目标分支作为集成分支
本次父级的 change branch 与 target branch 都是
beta20。前四个 Child 合入后,父级第一次整体验证仍有 169/333 项失败,但真实目标分支已经包含不完整的组合结果。随后又追加memory-rules-host-integration-repair才完成宿主接入。父级需要一个专用 integration branch/worktree。Child 只能合入该集成分支;父级整体验证通过前,真实目标分支不应发生变化。
3. 用户能力、实施 Child 和验收映射混在一起
本次父级有 3 个目标 Spec、多个领域 Child、横向集成 Child 和修复 Child。这个数量差异本身合理:Spec 描述用户能力,Dashboard、Skill/CLI 或宿主接入可以是横向实施工作。
但当前
children.yaml使用位置型A1...An和逐项covers。最终归档文件达到 546 行,512 条覆盖记录只对应 333 个唯一验收项。大量映射没有避免宿主接入遗漏,反而增加了维护、上下文和输出成本。4. 多 Agent 目前只是 Skill 约定,不是稳定交接
当前 Skill 已要求支持时并行推进
readyChildren,不支持时顺序执行,但 Runtime 只提供 Child 列表和派生状态:Comet 需要接入宿主原生 Agent 能力,但不应因此引入共享任务列表、mailbox、claim、lease、heartbeat 或通用 scheduler。
5. Runtime 内部流程泄漏给 Skill 和用户
正常推进过程中出现了多次无决策价值的“继续”,并暴露
runner-input临时 JSON、candidate、iteration、attempt、Agent 运行标识、Archive preview/finish 等内部步骤。用户主要通过 Comet Skill 使用能力,这些细节应由 Runtime 和 Skill/宿主协调层吸收。只有产品范围变化、合并冲突、外部授权、无法保护用户文件或配置要求最终确认时才暂停。
6. 父级验证结果存在不必要的精确感
最终
333/333 passed混合了不同层级的证据:当前父级 Builder 还可以用
checks=[]和统一理由覆盖全部验收项。父级报告应展示证据来自哪里,而不是把所有条目展平为同一种“通过”。7. 跨模块接入没有在 Shape 阶段明确负责人
初始 Child 分别负责领域模块,但正常 Comet workflow、Skill/CLI fallback、Git 同步、规则验证循环等横向连接没有明确实施责任,直到父级 Verify 才集中暴露。
最终 Verify 应负责收口,不应第一次发现大面积连接缺失。
✨ Proposed solution
术语约定
本 Issue 只保留下面这些必要概念;代码可以沿用现有内部类型名,但面向开发者的设计和状态输出统一使用这里的说法。
verifiedintegratedrunId(替代旧称taskToken)runId,旧结果或重复结果会被忽略。它不是权限凭证,也不证明 Verifier 独立性。receipt类型名,但 Issue 和用户输出不再单独引入 receipt 概念。docs/comet/specs、供后续 Change 继续引用的正式规格。Child 的范围规格只作为本次实施历史保存。summary / details / historystatus默认返回summary简洁摘要;排查时读取details或history。长列表的 JSON API 使用标准 cursor pagination:响应返回nextCursor,调用者用它请求下一页;Skill 用户只看到“还有更多详情”,不需要操作 cursor。needs-reverify用户最终体验
Skill 在创建、恢复、Agent/Child 状态变化和父级验证后,都显示同一份简洁摘要:
正常消息不显示完整验收编号、临时 JSON、Runtime 文件名、
runId或 Agent 运行标识。1.
children.yamlv2 只保留可读实施计划新增
comet.native.children.v2,只保留名称、摘要和真实依赖:Runtime 只做确定性校验:
depends_on引用存在;children.v1继续可读,已归档 v1 永不重写。summary用用户语言说明实施责任,不增加covers、owns、位置型验收映射或新的用户可见 ID。父级完整目标仍以 brief 和 Specs 为准,由 Shape 做语义拆分确认,由父级 Verify 做最终完整验收。本 Issue 不改变 Native 验收项的身份模型。现有
A1...An可继续作为 Runtime 内部兼容字段,但不再进入children.v2或默认状态输出。命名验收场景若仍有独立价值,应另行设计,不与 Supervisor integration-first 绑定交付。2. Shape 明确横向集成责任,但不建立 机器可解析的职责规则
Skill 在确认拆分前执行一次集成责任检查:
summary明确负责,或增加一个小型 integration Child;这是 Shape 的语义检查,不由 Runtime 解析 Markdown 标题或强制唯一文件 owner。
父级 Verify 失败后,可以追加处理现有失败项的修复 Child。只要没有新增用户可见范围或产品决定,就不要求用户重新确认;如果范围或决定变化,仍返回父级 Shape。已 integrated Child 的历史不可改写。
3. 分离 Child Verify、Integrate 和 Archive
Supervisor v2 使用以下父级派生状态:
verified:Child 候选和独立验证已经通过,verified commit 已确定,但尚未进入父级 integration branch;integrated:父级集成器已将 verified commit 串行合入 integration branch,并校验结果;archived:只有父级最终交付成功后,父级和全部 Child 才统一进入 Archive。默认用户摘要可将
pending/ready合并显示为“等待”,将active/verified合并显示为“工作中”;详细状态仍保留确定性语义。Standalone Native Change 和 v1 Child 继续使用原 Archive 语义。该扩展只适用于新建的 Supervisor v2。
4. 父级拥有专用 integration branch/worktree
父级 Shape 确认后,Runtime:
native.archive_confirmation: automatic | required自动继续或最多确认一次,再统一交付到真实 target。Runtime 在 Child 创建、验证、集成和最终交付时校验 Git commit 与祖先关系,不能只相信 Agent 报告或 Archive 文件。
集成操作使用短事务锁、Git 引用比较更新和恢复日志,保证中断后不会重复 merge。这是集成安全,不是通用 worker 调度器。
真实 target 在父级最终交付前保持不变。若 target 已产生新 commit,Runtime 将最新 target 重新带入 integration worktree,并重新运行父级 integration checks;不尝试推断“只受影响的部分”。target dirty 和最终合并条件只在最终交付边界处理一次。
5. 使用宿主原生 Agent,但由父级统一协调
多 Agent 是可选加速层。父级协调 Agent 始终保留最终责任,并统一派发 Child Builder 与独立 Verifier,Child Agent 不需要再创建嵌套 Agent。
Runtime/continuation 为当前可执行工作返回精简的内部任务包:
规则:
builder只在指定 Child worktree 中推进 Build,达到 Verifier 边界或 blocker 后返回;verifier是新的只读 Agent,只验收指定 Child 的当前候选;runId只绑定当前 Child、角色、父级状态和 base commit,用于拒绝重复或迟到回报,不证明 Agent 身份或 Verifier 独立性;宿主支持原生 Agent 工具时,Skill 按宿主并发上限并行派发;无法获得上限时最多同时派发 2 个。宿主不支持时,同一协调流程按稳定顺序逐项执行,依赖、验证和集成语义不变。
不在平台注册表中硬编码
supportsMultiAgent。能力由当前会话实际可用工具决定,因为同一宿主也可能通过配置关闭 Agent。恢复时:
6. 保留
status / next / archive,自动推进无决策步骤不新增
comet supervisor命令族,也不把内部 Module 方法变成新的用户概念。comet native status返回父级摘要、Child 状态、当前 Agent 任务和按需详情;comet native next计算下一批 Builder/Verifier 任务、执行串行集成或进入父级 Verify;comet native archive只负责父级最终交付;.comet/runtime内创建、消费和清理;statusJSON,不复制 readiness、Agent 或集成状态推导。Runtime 内部可以抽取更深的 Supervisor Module,但不需要公开
inspect / advance / finish作为新的产品协议,也不接受一个可以绕过具体动作校验的泛化result。7. 默认 status 返回简洁摘要
默认摘要 只包含:
完整验收项和 Child 验证记录放在
details;状态变化历史与恢复日志放在history;调试时再显示 Agent 运行标识。默认status不内联这些内容。长列表的 JSON API 使用标准 cursor pagination,响应返回nextCursor,调用者用它读取下一页;Skill 用户只看到“还有更多详情”,无需手动处理 cursor。按父级名称查询时直接定位声明的 Child,不先扫描所有 worktree 的全部 Change。8. 建立分层验证记录,不再展平全部验收
每个 Child 集成时保存:
父级报告分为:
父级 Verifier 仍需读取完整 brief、Specs、所有 Child 验证记录和最终集成结果,对完整目标作出判断;但默认报告不复制 Child 的全部逐项表格,也不得使用
checks=[]和同一条泛化理由把所有验收项自动标记为通过。跨 Child、宿主和 workflow 的结果必须具有父级实际集成验证记录。全量测试超时必须显示为
Incomplete,不能折算为 passed。9. 一次最终交付和安全清理
父级 Verify 通过后,Runtime 按
native.archive_confirmation自动继续或最多确认一次,并在一个可恢复流程中:任何步骤中断后都可以恢复且不会重复合并或误删 worktree。存在未提交文件、未合入 commit、当前进程位于待删除 worktree 或合并冲突时,保留现场并返回明确 blocker,禁止强制清理。
#313 中 Archive preview 改变状态并导致重复 Verify 的具体修复继续独立完成;本 Issue 只要求 Supervisor 最终交付调用修复后的统一 Archive 能力。
10. Runtime 文件布局与恢复边界
父级目录只保留用户可读内容:
brief.mdspecs/children.yamlverification.mdSupervisor 动态状态、integration worktree 信息、Agent
runId、Agent 运行标识、Child 集成记录、验证记录、恢复日志和临时传输文件统一放在:这些 Runtime 文件不要求提交到 Git。
Runtime 丢失时可以从
children.yaml、父级/Child 用户文档、可移植状态(Portable State)、Git branch/worktree 和已归档结果重建计划、依赖、工作区与集成状态。只有可移植验证记录足以证明准确 commit 的 Child 才恢复为verified;缺失时进入needs-reverify或 blocked。宿主 Agent 会话本身不是可移植状态:能重连就重连,不能重连就按安全规则取消旧任务并从 Child 当前状态重新派发,不根据 Git 祖先关系猜测 Agent 是否完成。
11. 分阶段实施
该 Feature 可以由一个 Supervisor Change 管理,建议拆成三个可独立评审的 Child/PR:
Integration core
children.v2最小结构与 v1 双读;verified / integrated / archived生命周期;Optional parallel Agents
agentTasks和runId;验证记录、状态与恢复
statusJSON 与规模测试。三个阶段全部完成前,不把 v2 设为默认,避免出现一半使用独立集成、一半仍按 v1 Archive 的混合模式。
🎯 Primary area
Other — Native workflow runtime (
domains/comet-native) and bundled Native Skill🪐 Workflow phase
Not phase-specific
🔀 Alternatives considered
1. 只优化 Skill 文案和状态摘要
可以缓解“看不到 Child”的问题,但不会解决 Child Archive 与集成混淆、真实目标分支提前包含半成品、dirty target 反复阻塞和父级验证证据失真。
2. 保留 v1,每个问题单独打补丁
可以分别修复 status、Archive 和 runner 交互,但这些问题来自相同的生命周期分界。继续叠加补丁会让调用顺序和恢复更加复杂。
3. 使用宿主 Agent Team 或完整多 Agent Scheduler
共享任务列表、Agent 间通信、claim、lease、heartbeat、抢占和自动重试可以构成更通用的多 Agent 平台,但会复制宿主能力,并把 Comet 从 workflow Runtime 扩张成 Agent 调度器。
本 Issue 只使用父级协调者加独立 Builder/Verifier 的一层派发。Agent 不互相通信,Runtime 不管理模型、消息或通用 worker 生命周期。
4. 同时迁移命名验收场景与 机器可解析的职责规则
可以减少位置型 ID 漂移,但与 integration-first 没有必然依赖,会显著扩大 Native acceptance、Verifier、报告、恢复和兼容范围。
本 Issue 通过删除
covers、隐藏默认验收明细和分层报告解决当前用户问题;命名验收模型另行评估。最终选择:integration-first Supervisor v2 + optional parallel Agents。先让单 Agent 语义可靠,再在相同 Runtime 事实之上并行加速。
🧰 Compatibility notes
children.yaml的普通 Native Change 行为不变。children.v1、旧 Verifier response 和旧statusJSON 至少保留一个 beta 周期的读取兼容;JSON 字段语义改变时升级statusschema。platform/Adapter;Windows、macOS 和 Linux 共享同一 Runtime 语义。assets/manifest.json和对应 Runtime 资产测试。statusJSON。🧩 Additional context
Acceptance criteria
User experience
runId或 Agent 运行标识。native.archive_confirmation:automatic不再询问,required最多确认一次。Plan and integration responsibility
children.v2只包含name / summary / depends_on,不包含covers / owns。Integration lifecycle
verified,串行合入并校验后进入integrated,不会提前显示为 archived。Optional parallel Agents
Evidence and reporting
checks=[]和同一条泛化理由自动通过完整目标。Recovery and compatibility
needs-reverify或 blocked。Suggested implementation ownership
domains/comet-native/:Supervisor plan、Agent tasks、statusJSON、integration、evidence、recovery 和 continuation。platform/paths、platform/process:Git/worktree 的现有 Adapter;不在 domain 内散落平台命令。app/commands:只组合 Runtime Module,不承载 readiness、Agent 派发、集成或恢复规则。assets/skills-zh/comet-native/、assets/skills/comet-native/:用户主路径、宿主 Agent 派发、顺序降级和简洁摘要。domains/dashboard/:仅适配新的只读statusJSON,不复制状态计算。test/domains/comet-native/:无模型状态、runId、恢复、真实 worktree 和规模测试;Skill、Dashboard、Repository 测试按现有归属补充。Non-goals
comet supervisorCLI 命令族;本 Issue 只实现完成 integration-first 所必需的最小
runId与迟到回报拒绝;真正的 durable multi-agent scheduler 如果以后有明确需求,再单独立项。