模式工坊 boston-harness-group/refactory-dsh

Refactory

Refactory — agentic harnesses, built to improve

创建工作流。交互式运行。持续优化它的工作方式。

Refactory 把智能体工作变成可复用的模式：由编码智能体、确定性操作、检查点和审批门组成的显式图。你可以从终端或浏览器驱动它们，在运行过程中随时调整方向，并用可配置的外层循环搜索它们的提示词、图结构和参数。

快速开始 · 终端与 GUI · 命令参考 · 编写模式

浏览器保留了 Refactory 原有的双档位风格和蓝色主题。Modes 面板分为 Run 和 Optimize 两个视图，支持 Package → Mode 选择、上下文帮助和一个大尺寸的 brief 编辑器。实时工作流图和必答问题始终跟随被观察的运行。面板指南 · 上游兼容性

发布状态 · 2026 年 9 月 26 日： 配置档、实时控制/恢复以及 DSH/Codex/Claude Code worker 已通过有界命令行和原生 GUI 验收。快速创作已实现，但能否顺利走完 QA 和有界修复仍未验证。就绪情况与证据 ↓

你能构建什么

- 可复用的 harness： Create 把一份 brief 变成一组模式包。把 Task 绑定到一类输入上，或选择单次运行的 harness。
- 更好的版本： Edit 生成新的模式包，附带来源记录和如实的对比状态。
- 产物： Design 按 brief 和检查命令构建软件、文件或报告。
- 可度量的改进： Optimize 提出允许的改动，验证这些改动，评估候选方案，并在采纳前审计胜出者。

Create 和 Edit 产出可复用的模式；Design 产出产物；带评分的模式可以运行、优化和采纳

为什么要用显式图？

运行时跟踪哪个节点到期、执行操作、强制执行门禁并记录证据。对话式 CEO 分派智能体工作，并接受你的操控。技能可以辅助 worker，但技能文档不是图的执行器。

图和各项参数都是可检查的数据。优化器对这些数据提出带类型的改动；模式的评分函数和声明的约束条件不在可编辑范围内。用户拥有的审批门归用户所有。

快速开始

需要 Git、Node.js ^22.19 或 >=24，以及 uv。安装脚本会装好锁定版本的依赖、Python 环境和 DSH 配置档。

git clone https://github.com/boston-harness-group/refactory-dsh.git
cd refactory-dsh
./install.sh
uv run refactory list
先跑一个随仓库附带的示例，做一次小型离线搜索：

uv run refactory optimize circle_packing/adaptive \
--optimizer random --preset knob_only --evaluator walker \
--epochs 2 --batch-size 4 --max-evaluations 8 --seed 5 \
--runs-root .factory/loop/first-search

uv run refactory leaderboard --run .factory/loop/first-search
uv run refactory best --run .factory/loop/first-search

这个示例不需要模型密钥。它演示候选改动、评分，以及记录下来的停止条件。另做一次搜索时，请换一个新的运行目录。

把胜出方案保留为新包：

uv run refactory adopt --run .factory/loop/first-search --as first_tuned
uv run refactory package smoke first_tuned/adaptive

原包仍然可用。继续走查 →

更新

每次 pull 之后，重新运行安装脚本，并重启正在运行的 GUI：

git pull
./install.sh

./install.sh 可以放心重复执行：它会重新同步 Python 和 Node 依赖，重新构建每个包，并且只在 DSH 配置档有变化时才更新它们。正在运行的 refactory ui 或 ./refactory-dsh 会继续使用启动时的构建，所以之后要重启它。

如果某次运行以 Workflow engine build is out of date … Run pnpm run build 停止，说明源码更新了但没有重新构建。运行 ./install.sh（或 pnpm run build）然后重启。

选择你的界面

| 终端 | 浏览器 |
| refactory ceo 用于对话和审批关卡 | CEO 聊天，用于编写和逐节点交互 |
| refactory optimize 用于显式配置搜索 | Modes 面板，用于保存的配置档、旋钮、搜索和资源限制 |
| status、candidate、steer、adopt 用于查看和控制 | 单次运行、实时图/worker 活动、提问和候选对比 |

uv run refactory ui --port 3081

要启用全部原生 web 预设，外加 CEO 和 Refactory Modes 面板：

./refactory-dsh --additive --port 3081

这会创建并复用 refactory-web，在 $DSH_HOME/profiles/refactory-web/package.json 中声明 web 和 Refactory 两个 bundle。CEO 是默认项，现有的 web 配置档保持不变。

打开服务器打印的确切 URL，把 checkout 选为工作区，然后创建会话。打开右侧边栏的 Modes 标签页；不需要先发一条开场聊天消息。

在做依赖模型的工作之前，先在 Settings → Models 里保存服务商密钥。嵌套 worker 和校验使用托管的凭据存储；对于这些经过清理的进程，仅有 checkout 里的 .env 或导出的密钥是不够的。uv run refactory doctor 检查的是配置，不是认证或配额。模型设置 →

在 GUI 聊天里试试这个：

Open counting_pack/fixed_step with target=20 and step=2. Drive it one node at a time and show me the recorded result.

或者从终端：

uv run refactory ceo counting_pack/fixed_step \bash
--knob target=20 --knob step=2 --intent "Count to twenty and explain the recorded result."

Chat 支持 Create、Edit 和 Design。Modes 面板的 Start 按钮启动对某个计分模式的优化；Run once 执行任意已启用的模式，包括 full 和 fast 两种创作模式。挂上一个运行，就能跟踪持久活动、worker 回执和待答问题。界面指南 →

创建、编辑或设计

| 目标 | 示例 |
| 创建单次运行的 harness | uv run refactory ceo "Draft and check a project README from a supplied brief" --mode create --name readme_pack --single |
| 为一类输入创建 harness | 用 --task module:TaskClass 代替 --single；见 任务与数据集 |
| 修订某个模式 | uv run refactory ceo "Improve the search strategy" --mode edit --revise circle_packing/adaptive --name revised_pack |
| 构建带校验的产物 | uv run refactory ceo "Build wordcount.py and a sample.txt; verify line, word and character counts" --mode design --name wordcount --check "python wordcount.py sample.txt" |

这些命令会调用模型，可能耗时较长。当前的 full 创作模式包含调研和评审；在实现之前，你要先批准策略/设计。生成的包放在 .factory/packages/。Design 运行在 git worktree 里自己的分支上：分支来自你用 --target 指定的仓库，或来自 ~/refactory-projects/ 下的新项目。确切路径和校验结果都会记录在运行里。

任务小而聚焦时，选 create_fast、edit_fast 或 design_fast。Create 先规划一张最小可复用图，然后依次运行一个 coder 和一个 QA 智能体；结构准入和 canonical smoke 仍然必需。Design 用同样的三个顺序角色完成一处小的带校验改动，改动落在 Design 该落的地方：运行自己的分支上，仓库或新项目的 worktree 里。Edit 直接交给一个 coder 和一个 QA 智能体，同时保留源契约和可选的分数比较。这些图省去了调研和评审扇出，默认允许一次修复。三条 fast 路径都完成了各自的受限命令行和原生 GUI 检查，包括真实的结构修复和独立的产物校验；fast Design 的 worktree 路径目前只在命令行上验证过。此前的失败会保留。见 fast 模式与共享预算。

canonical smoke/验收在 QA 和 Overwatch 签核之前、在受限修复内部运行。评审者复用它的回执，把任务简报、已接受的验收标准/设计和当前意图账本映射到实际证据。必需行为没有证据就不能通过；修复和后续指令会让旧的签核失效。full 模式保留独立的健康检查、代码评审和对抗性评审，外加 Overwatch；fast 模式保留一个聚焦的 QA worker。证据与图细节。
有意做 Edit 取舍时，--knob allow_regression=true 会跳过全部原始模式执行与数值比较，但仍会校验修订后的模式，并保留溯源信息。默认值仍为 false。跳过的比较属于未测量，绝不算作非回归通过。

Design 直接产出产物本身，不需要产出打分模式，也不需要进入优化器。编写指南 →

用清晰的契约做优化

选定外层循环策略、候选提议器、评估器和允许的编辑，保存一份命名的优化配置档，预览它的目标与校验契约，再从命令行或 GUI 用同一套设置启动。每次运行都保留当次解析出的精确快照。候选比较涵盖血缘、改动、原始分与调整分、失败、试验波动、耗时，以及可得的成本与用量。

GUI 聊天也能启动已保存的优化配置档，查看胜出者，采纳它，并通过 Refactory 工具重放采纳后的模式。这条路径除了命令行和面板检查，还有单独的 GUI 聊天原生验收。

搜索过程中，你可以追加指令，保留或拒绝候选分支，在代际边界暂停、恢复、停止，并请求采纳。失败或未经审计的候选不能当作已验证的胜出者。一次运行也可能跑完却没找到改进。

候选上限、耗时上限和 token 上限是三套独立控制。 运行级的 token 上限与耗时上限可选，默认不设；快速任务受自身图、修复策略和操作超时约束。选择预算时，看进展和实测用量，别把某个 token 配额当成完成保证。可选的重复试验和最终留出校验会消耗共享的运行配额；校验可以预留一部分。缺失的用量始终记为不可得。换模型会改变质量、成本和延迟。优化教程 →

模型与编码工作进程

DSH 仍是默认的工作进程运行时，与 Cordis 组合使用。它的服务商包括 DeepSeek、OpenAI 和 Anthropic。用 OpenAI 模型的 DSH 工作进程仍然是 DSH 工作进程。两个评估器都携带选定的路由上下文；节点级覆盖优先于角色级设置和运行设置。要看实际执行回执，别只看配置里的选择。路由与工作进程指南 →

Codex 和 Claude Code 是显式可选的工作进程后端，经由已安装的 DSH 服务商注册表接入。它们保留原生认证和产品设置；不支持的能力在派发前就失败。外部 token 受限的运行会被拒绝，因为完整的嵌套计量尚未建立。Refactory 仍掌管图顺序、校验和门禁。
新 worker 默认使用 skip，会绕过原生权限检查；对 DSH/Codex 来说，还会绕过它们的沙箱限制。工具能拿到你操作系统账号拥有的访问权限。想保留后端的检查，请选 --permission-mode default，或在 GUI 里选 Native permission policy。已保存的运行和配置档会保留各自的策略。权限细节

发布能力与验证

四项发布能力都已完成有边界的命令行与原生 GUI 验收。 检查覆盖受支持的路径和抽样的产物契约；不保证任意生成的项目可用，也不保证各模型表现一致。

| 能力 | 命令行与原生 GUI 验收 | 指南 / issue |
| 共享资源核算，以及快速的 Create/Edit/Design 图 | 完成： 三种快速模式、必需校验、实际的有界修复，以及显式标记的未解决失败 | 快速模式与预算 · #234 |
| 实时活动、提问、边界控制与受支持的恢复 | 完成 | 实时控制与恢复 · #235 已关闭 |
| 带版本的配置档、候选对比、精确采纳与重放 | 完成 | 优化配置档 · #236 已关闭 |
| 路由，以及可选的 DSH/Codex/Claude Code worker | 完成 | 模型与 worker · #237 已关闭 |

发布验证记录 分别列出了命令行与 GUI 的证据和资源上限。Codex 和 Claude Code 在新的 skip 默认值下通过了原生 GUI 产物检查；注册的 stopped-owner 恢复在两个界面里都保住了已完成的工作。整树 token 上限和运行中 worker 会话的续跑仍不支持。这些有边界的检查不保证生成产物的质量，不保证各后端表现一致，也不代表整个仓库的测试套件全部通过。

命令行

完整的命令参考涵盖编写、打包、运行、优化、引导与采纳。查看已安装命令的选项，用 uv run refactory <verb> --help。

学习与贡献

| 从这里开始 | 深入了解 |
| 快速上手 | 架构 |
| 核心概念 | Python API |
| 教程 | 任务与数据集 |
| 终端与 GUI | 验证 |
| 模型与凭据 | 参与贡献 |

Refactory 正在积极开发中。执行是否成功、声明的检查结果、生成内容的质量，是三份彼此独立的证据；判断某个产物是否满足你的需求时，请逐项查看。

实时帮助与项目 worker

CEO 启动时自带一份精简操作指南，可以通过 refactory help 查询当前模式和操作 schema，再用 refactory docs 搜索、阅读随包发布的完整文档。模式开关、节点角色、门禁、示例和支持的接口路由，都对模型保持可见。构建过程会检查文档覆盖情况，并拒绝过期的生成引用。参见发现与扩展清单。

把 refactory.workers.json 放到项目根目录，即可选择 DSH、Codex 或 Claude Code worker，其中还包括只用于编码的 node_routes.emit 覆盖项。命令行、原生面板、CEO 工作流和优化流程解析的是同一套默认值；已保存的运行会保留自己的路由。refactory workers 会说明实际生效的设置及其来源。参见 worker 文件示例与优先级。