Leopold-Fitz-AI/soluna-harness

Soluna Harness

将一次编码请求转化为可审计的工程运行

Sol 规划。Luna 构建。Terra 升级。你的测试说了算。

CI
License: MIT
Node.js 20+
Tests: 57 passing
Codex + DSH

一个持久化、策略驱动的软件工程编排器，适用于 OpenAI Codex CLI 和 DeepSeek Harness。

快速开始 · 工作原理 · 配置 · 架构 · 验收证据

[!IMPORTANT]
Soluna Harness 是一个早期的 0.1.0 版本。该实现已经过测试，可从源码使用；npm 包已准备好，但尚未发布。

为什么选择 Soluna？

编码代理擅长修改文件。但要交付可靠的软件还需要更多：有范围的计划、明确的所有权、确定性的验证、独立的审查、有界的重试、取消机制，以及可供日后检查的证据。

Soluna 将这种工程纪律转化为可复用的编排层：

| 角色 | 职责 | 默认路由 |
| --- | --- | --- |
| Sol | 架构规划与独立最终审查 | gpt-5.6-sol，high / xhigh |
| Luna | 仓库探索、实现、测试与修复 | gpt-5.6-luna，max |
| Terra | Luna 耗尽重试预算后的升级处理 | gpt-5.6-terra，high |

你将获得

- 自动 L0–L5 路由 —— 琐碎的编辑保持轻量；有风险的工作则获得真正的计划与审查。
- 经过验证的实现包 —— 文件所有权、不变量、依赖关系、验收标准以及结构化验证命令。
- DAG 感知调度 —— 独立的包可以并发运行；重叠的所有权会被拒绝。
- 以验证为关卡 —— 白名单 argv 执行、有界输出、超时、取消，且无 shell 插值。
- 工作区问责 —— Git HEAD 与内容哈希可检测未报告或超出范围的编辑。
- 持久化运行 —— 原子状态快照，外加仅追加的 worker、工作区、验证与审查证据。
- 故障关闭式安全 —— 严格模式、有界上下文、机密信息脱敏、拒绝符号链接/路径穿越，以及所有权安全的卸载。
- 默认零项目配置 —— 仅当需要策略覆盖时才添加 .soluna.toml。

快速开始

要求

- Node.js >=20
- 对于 Codex CLI/MCP 使用：已认证的 Codex CLI 安装（0.150.1 是经过验证的基线版本）
- 对于原生 DSH 使用：DeepSeek Harness 0.1.x（0.1.0-rc.7 已验证）、进程内 spawn 子代理提供程序，以及已认证的模型提供程序，例如 Codex Connect 的 openai-codex 路由
- 访问已配置的规划、实现和升级模型 ID；可用性因部署而异

从源码安装

git clone https://github.com/Leopold-Fitz-AI/soluna-harness.git
cd soluna-harness
npm ci
npm test
npm link

安装到 Codex：

node dist/cli-entry.js install --platform codex
node dist/cli-entry.js doctor --platform codex

安装到 DeepSeek Harness 的 web 配置文件：

node dist/cli-entry.js install \
--platform dsh \
--dsh-profile web \
--package-spec "$PWD"
node dist/cli-entry.js doctor --platform dsh --dsh-profile web

或者一次安装两者：

node dist/cli-entry.js install \
--platform all \
--dsh-profile web \
--package-spec "$PWD"
node dist/cli-entry.js doctor --platform all --dsh-profile web

npm link 会暴露本地的 soluna 可执行文件；稍后可使用 npm unlink -g @soluna-harness/install 将其移除。Codex 安装程序会创建带时间戳的配置备份，并记录每一个所拥有的设置/文件。DSH 安装程序将包协调委托给 dsh plugin，并在卸载期间保留独立管理或用户修改的依赖项。

在 Codex 中使用它

在受信任的 Git 仓库内启动一个新的 Codex 会话：

cd your-project
codex

然后正常提问：

Implement role-based access control for the API, add regression tests,
and verify backward compatibility.

隐式的 soluna-orchestration 技能会自动路由非平凡的工作。你也可以明确指定：

Use Soluna orchestration. Have Sol produce the plan, let Luna implement and
repair it, run every required verification gate, then have Sol review the result.

有用的操作命令：

soluna doctor                    # validate installation and model routes
soluna status                    # list persisted runs
soluna status            # inspect one run
soluna resume            # continue a cooperative run
soluna cancel            # cancel active work

在 DeepSeek Harness 中使用它

安装该捆绑包后，重启所选的 DSH 配置文件。该配置文件中的会话会收到一个作用域限定的编排提示，以及十个原生工具：

soluna_run          soluna_plan          soluna_submit_plan
soluna_dispatch     soluna_verify        soluna_review
soluna_resume       soluna_status        soluna_cancel
soluna_doctor
在 DSH 中，Sol/Luna/Terra 作为原生进程内 Harness 子代理运行。它们的模型请求默认使用 Codex Connect 的 openai-codex 提供程序，因此 DSH 的 OAuth 连接、代理循环、工具、沙箱、审批和取消操作保持权威。外部 Codex CLI 保留用于独立的 CLI/MCP 使用，但此原生 DSH 路径不需要它。需要时，可使用 SOLUNA_DSH_MODEL_PROVIDER 和 SOLUNA_DSH_SUBAGENT_PROVIDER 覆盖路由。

工作原理

flowchart LR
A[Request] --> B{Classify L0-L5}
B --> C[Bounded repository profile]
C --> D[Sol plan for L3+]
D --> E[Validate packet DAG]
E --> F[Luna Max implementation]
F --> G{Verification gates}
G -- fail --> H[Repair loop]
H --> F
H -- retry budget exhausted --> I[Terra escalation]
I --> F
G -- pass --> J[Sol review for L3+]
J -- changes requested --> H
J -- approved --> K[Done + persisted evidence]

每次运行都遵循经过验证的状态机：

received → classified → recon → planned → ready → implementing
↓
verifying
↓
reviewing → done
↓
ready ← escalating ← repairing

Any active state → cancelled | failed

运行数据位于：

${XDG_STATE_HOME:-~/.local/state}/soluna/runs//

每次运行都包含一个原子性的 run.json 以及仅追加的证据日志，用于记录工作进程、工作区变更、验证和审查。

两个原生集成界面

Codex 插件

- 用于编排、调试、审查和诊断流程的隐式技能；
- 暴露版本化编排工具的 MCP 服务器；
- 六个用户级代理角色；
- 可选的、非阻塞的遥测钩子；
- 协作式原生调度以及自主的 codex exec 回退。

DeepSeek Harness Cordis 包

- 配置文件作用域的包捆绑；
- 十个带有运行时输出模式的原生 DSH 工具定义；
- 一个通过活动 Harness 提供程序（默认为 openai-codex）路由的原生 DshSubagentBackend；
- 一个作用域系统提示词部分；
- 复用宿主代理循环、工具、沙箱、审批、OAuth、生命周期和取消；
- 不修改沙箱、审批、凭据或随附预设。

两个界面共享相同的模式、调度器、持久化、令牌账本、验证引擎和安全模型。

配置

项目不需要任何 Soluna 文件。要覆盖策略，请添加 .soluna.toml：

version = 1

[quality]
requireTests = true
requireReview = true
forbidNewUnsafe = true

[routing]
maxWorkers = 4
plannerFromLevel = "L3"
reviewFromLevel = "L3"

[context]
softTokens = 64000
hardTokens = 128000

[roleModels]
Sol = "gpt-5.6-sol"
Luna = "gpt-5.6-luna"
Terra = "gpt-5.6-terra"
上述模型 ID 与已验证的部署相匹配，但不应假定每个 Codex 账户都存在这些模型。请使用你的模型目录中可用的路由覆盖 roleModels，然后在开始工作前运行 soluna doctor。

优先级顺序为：

内置默认值 → 机器配置 → 用户配置 → 项目 .soluna.toml → 任务覆盖

CLI 参考

soluna install [--platform codex|dsh|all] [--dsh-profile web] [--package-spec SPEC]
soluna uninstall [--platform codex|dsh|all] [--dsh-profile web]
soluna doctor [--platform codex|dsh|all] [--json] [--live]
soluna status [RUN_ID]
soluna run "TASK" [--cwd PATH]
soluna resume RUN_ID
soluna cancel RUN_ID
soluna serve

doctor --live 执行付费的、需主动选择的模型冒烟测试。普通 doctor 检查不涉及生成。

安全模型

Soluna 的设计目标是让编排证据显式化，而不是将不受信任的仓库变为受信任的代码。

- 模型输出跨越严格的 Zod / JSON Schema 边界。
- 上下文编译会拒绝路径遍历、符号链接、类密钥路径、二进制文件以及硬限制溢出。
- 子进程使用 argv 数组；验证具有可执行文件允许列表和仓库内 cwd。
- 在模型/后端输出被持久化或通过状态工具返回之前，密钥会被脱敏。
- 脏工作树、非 Git 根目录、嵌套 Git cwd 以及工作区符号链接默认情况下会失败关闭。
- 安装程序的所有权记录可防止卸载时删除用户修改的配置或 DSH 包。

仓库测试/构建脚本仍是受信任的代码，并以宿主进程的操作系统权限执行。在将 Soluna 用于敏感代码之前，请阅读完整的安全策略。

已验证的验收

当前版本已经过单元测试之外的检验：

- 19 个测试文件 / 57 个测试通过；
- 真实的 Sol、Luna Max 和结构化后端冒烟检查；
- 一次完整的自主 Sol → Luna → verification → Sol review 运行；
- 隔离的 Codex 安装、幂等性、doctor、MCP stdio 以及卸载检查；
- 链接和打包的 DSH 包安装；
- 对原生 soluna_status 的一次真实 DSH 模型调用；
- 最终的安全和产品审计，没有未解决的 P0/P1 问题。

有关确切的证据和明确的边界，请参见 docs/ACCEPTANCE.md。

开发

npm ci
npm run check
npm run lint
npm test
npm pack --dry-run

核心实现：

src/orchestrator.ts   分类、状态机、修复、审查、升级
src/scheduler.ts      数据包 DAG 验证与调度
src/context.ts        有界上下文编译与密钥脱敏
src/workspace.ts      Git 工作区证据
src/verification.ts   结构化验证运行器
src/storage.ts        原子持久化状态与锁定
src/server.ts         MCP 工具接口
src/dsh-backend.ts    原生 DSH 子代理执行后端
dsh/plugin.js         原生 DeepSeek Harness Cordis 工具

路线图

- 将 @soluna-harness/install 发布到 npm。
- 将 DSH 原生后端兼容性扩展到已验证的 Codex Connect/spawn 路由之外。
- 将协作式原生执行扩展到多数据包 DAG。
- 添加更丰富的运行可视化和成本报告。
- 在 CI 中验证更多操作系统和主机版本。

贡献

欢迎提交问题、设计讨论、测试和拉取请求。请从 CONTRIBUTING.md 开始，并且请为行为变更附上验证证据。

对于安全漏洞，请使用 GitHub 的私密漏洞报告，而不是公开问题。

许可证

MIT © 2026 Soluna Harness Contributors