SuperAPI AI 工具集

deepwork

编程与开发

查看项目

更新于 10-27 16:28

技能介绍

用途

Deepwork 是一个用于重型编码会话的编排器工作流。仅当工作明显规模庞大或风险较高时才使用,例如:存在多个相互依赖的阶段、跨领域的架构变更、无法安全地部分交付的迁移,或需要在多个专家通道之间持续协调。

不要仅因为任务涉及多个文件就推断需要使用 Deepwork。不要将其用于琐碎编辑、快速文档修改、简单缺陷修复或常规的有界功能。

核心契约

当 deepwork 处于激活状态时,编排器必须将工作作为调度者来管理,而不是作为默认的实现工作者。

设置与 Deepwork 状态

  • 在 .slim/deepwork/ 下创建并维护一个本地 markdown 进度文件;
  • 将代码/文档交付物保存到项目路径(例如 src/、docs/);.slim/deepwork/ 严格保留用于进度文件。

Deepwork 文件

创建一个任务专属文件,例如:

.slim/deepwork/<short-task-slug>.md

在创建此文件之前——以及在规划和委派之前——检查现有的 .gitignore 和 .ignore。只添加缺失的条目,不要添加重复项:

.gitignore

.slim/deepwork/

.ignore

!.slim/deepwork/ !.slim/deepwork/**

这些规则使 deepwork 状态保持在 git 本地,同时允许 OpenCode 读取它。

不要遵循僵化的模板。选择最适合该工作的 markdown 结构。该文件只需作为持久会话状态保持有用,并应视情况记录:

  • 当前目标与理解;
  • 来自 @librarian 的已研究、事实性上下文,以避免 oracle 自行研究;
  • 计划草稿、Oracle 评审预算/关卡与评审笔记;
  • 实施阶段与状态;
  • 验证结果;
  • 未解决的问题、阻塞项与后续事项。

在重大决策、接受研究、评审、阶段完成、验证结果和范围变更之后更新此文件。记录已接受的发现,并通过路径引用本地文件,而不是复制其内容。

规划

  • 在实施前起草计划;
  • 创建分阶段的实施/委派计划;
  • 在派发之前,根据工作的依赖关系和自然交付边界选择少量连贯的实施阶段;不要仅仅为了缩小 Oracle 评审范围而拆分工作;
  • 在执行之前,定义连贯的交付阶段,并使每个阶段后的 @oracle 评审成为强制项;在 deepwork 文件中记录阶段顺序、专家归属、关卡顺序和一行式关卡理由;向用户分享一个精简版本;
  • 在开始每个阶段之前,将 OpenCode 待办列表替换为仅针对该阶段的可操作交付待办。

阶段执行

在每个实施阶段之前,决定执行路径:哪些可以并行运行、哪些必须顺序执行、委派给哪些专家,以及是否将同一 agent 拆分为多个有界通道。

调度者纪律

全程使用调度者模型:

  • 记录任务/会话 ID 与归属边界;
  • 在消费后台结果之前,等待由 hook 驱动的后台完成;
  • 在后台作业运行时避免阻塞编排器通道;如果没有剩余的独立工作,短暂停止并让完成事件恢复工作流;
  • 在相关作业正在运行或终端结果尚未协调时,不要推进到下一阶段。

阶段关卡与提交

  • 在每个计划阶段之后,运行相关验证,更新 deepwork 文件,然后在继续之前请求其计划的 @oracle 关卡;
  • 在其计划的 Oracle 关卡之前,记录相关已接受的研究和文件引用,以便 Oracle 评审已建立的上下文,而不是重复发现;
  • 在 deepwork 文件中记录阶段目标、变更路径、验证证据以及要评审的具体决策或风险;将这些上下文连同已接受的研究和文件引用提供给 Oracle;
  • 当阶段改变模块边界、依赖方向或文件放置时,与 Oracle 关卡并行运行 @explorer 结构扫描;
  • 协调评审发现,对实质性问题执行一次有界修复,并用聚焦证据验证该次修复;
  • 当阶段是一个独立有效的交付边界时,在开始下一阶段之前创建一个聚焦提交。

Oracle 复审

每个计划的 Oracle 关卡有一次初始评审,并且最多可有两次复审。仅当修复实质性改变了被评审的决策或风险,或原始关注点无法用聚焦证据验证时,才请求复审。不要将复审花费在机械性或已验证的变更上。

在每个 Oracle 提示中说明尝试次数,例如:

Gate 2 — review attempt 2 of 3 (1 re-review remaining)

对于复审,告诉 Oracle 优先处理未解决的实质性发现、修复引入的风险,以及先前发现是否已解决。它不得重新打开已接受、未更改或已解决的关注点。当两次复审用尽时,在 deepwork 文件中记录任何剩余的实质性风险或阻塞项,并询问用户是接受风险、更改范围,还是授权一次额外的例外评审。

设计师交接护栏

当 deepwork 阶段包含 @designer 时,将交付的 UI/UX 视为后续阶段已接受的设计意图。在继续之前,在 deepwork 文件中记录任何重要的设计决策。

在设计师工作之后:

  • 保留布局、节奏、层级、动效、间距、颜色、可供性、响应性和组件手感;
  • 用有依据的、正常的措辞评审和改进面向用户的文案,但不要改变视觉结构或交互意图;
  • 将后续的视觉、响应式、动效、层级、打磨或组件手感变更路由回 @designer;
  • 仅将 @fixer 用于有界的机械性后续工作,且必须精确保留设计,例如接线、测试、类型修复或非视觉行为变更;
  • 如果必须更改设计意图,在更改之前将原因记录在 deepwork 文件中。

完成

以最终验证和简洁总结结束。