dsh-apex

Readme

# APEX v1.0

**研究如何让同一个模型更可靠地完成复杂任务。**

APEX 是面向 DeepSeek Harness 的任务增强插件。我们围绕工具调用、任务协作和结果验证构建执行环境，探索基础模型在实际交付中的能力边界。

> **当前阶段 · 2026-09-16**
>
> v1.0 已完成正式集成、macOS 工程验证和首轮复杂任务对照研究。下一阶段将通过多任务、重复实验和同等预算比较，检验观察到的收益是否稳定。

[开发与安装](docs/APEX-1.0.md) · [实验论文](papers/diesel-engine-2026-09-16/README.md) · [发布验证](docs/PUBLICATION.md)

## 我们在做什么

项目围绕一个核心问题展开：**在保持基础模型不变的前提下，更合适的工具、协作方式和反馈，能否提高完整任务的通过率？**

APEX v1.0 将这项研究落成了可安装的插件：模型可以使用官方工具完成工作，按需要组织团队，并通过浏览器检查、只读审查和执行记录核验结果。任务如何分解、是否委派、何时检查，仍由模型结合任务和用户要求决定。

我们同时维护插件实现与对照实验，分别回答“工程机制是否正确运行”和“最终作品是否更好”这两个问题。

## 为什么这样做

在已完成的四冲程柴油机任务中，两组作品都能生成复杂场景，也都报告过自测通过；进一步检查却发现了机械装配、运动关系或交互稳定性上的错误。这说明，本案例中的自测与展示没有覆盖完整验收要求。

因此，APEX 的开发重点是：

- **让模型能够实际执行和检查。** 使用文件、命令、浏览器及协作工具，把判断建立在可观察结果上。
- **按任务需要组织工作。** 简单任务直接完成，有独立子任务时再使用团队协作。
- **用完整交付衡量收益。** 同时记录任务通过率、质量、严重故障、耗时和资源消耗，判断额外开销是否值得。

## v1.0 已经做出了什么

| 方向 | 当前实现 |
| --- | --- |
| 原生工具执行 | 从首轮使用官方 PTC（通过程序调用工具），组合文件、搜索、Shell、Web 和后台任务能力。 |
| 按需团队协作 | 复用官方 Teams 的成员、消息、任务依赖、取消与恢复机制，补充 APEX 的协作指引和状态诊断。 |
| 浏览器验证与证据 | 在独立无头浏览器中执行指定交互，检查页面状态、DOM 和截图；可读取实际工具执行记录。 |
| 可选只读审查 | 调用仅具备读取能力的审查子代理，提供有依据的发现和后续检查建议。 |
| 执行与取消保护 | 在 macOS 上实现会话私有临时目录、受限写入与进程信号保护；阻止取消后的自动通知继续触发模型请求。 |
| 可分发的插件 | 已公开 v1.0 安装入口、预设、回归测试、开发文档，以及首轮对照论文与脱敏资料。 |

PTC、文件、Shell、Web 和 Teams 的基础能力来自官方 Harness。APEX 的工作集中在这些能力的组合、调用指引、验证工具和必要的执行保护上；各项机制的效果仍需通过实验分别评估。

### 工程验证

- **macOS 原生组件回归：162 项通过，0 失败、0 跳过。** 使用匹配的 Harness 和脚本化模型响应，没有调用付费模型。
- **Linux、macOS、Windows 的公共 CI 已通过。** 每个平台的基础检查为 55 项通过、82 项因缺少 Harness 而明确跳过；这不代表三个平台都完成了真实宿主集成验证。
- 安装、挂载、重复安装、错误拒绝、取消和资源清理已有对应检查。具体范围见 [发布验证记录](docs/PUBLICATION.md)。

### 首轮复杂任务对照

我们使用同一模型配置（`deepseek-flash / max`）完成四冲程柴油机三维交互任务，对照官方原生环境与 APEX v1.0。两组各生成一次，按同一套 37 项量表检查冻结的实际交付。

| 指标 | 官方原生对照 | APEX v1.0 |
| --- | ---: | ---: |
| 原始得分（满分 100） | 72.8 | 83.8 |
| 应用严重故障上限后的得分 | 40.0 | 83.8 |
| 完整任务验收 | 未通过 | 未通过 |
| 完成时间 | 51 分 13.9 秒 | 26 分 44.6 秒 |
| 全会话树输出 token | 265,713 | 1,229,906 |

原生对照因渲染冻结和关键机械连接缺陷触发严重故障上限。APEX 样本得分较高、完成较快，但仍有装配偏移、局部运动及信息一致性问题，输出 token 约为对照的 **4.63 倍**。

**这是一项探索性的单任务观察。** 每组仅一次生成、评价非盲、运行顺序固定且总计算预算不等，尚不能证明稳定、普遍或因果性的能力提升。

[查看中文论文、补充材料和图表](papers/diesel-engine-2026-09-16/README.md)。公开数据支持文中说明的图表与论文复现；完整会话、原始 trace 和冻结应用未公开，完整成品复验仍受限制，详见 [脱敏说明](papers/diesel-engine-2026-09-16/SANITIZATION.md)。

## 目前推进到了哪里

**APEX 当前处于 v1.0 正式集成完成后的效果评估阶段。** 插件已经落地，首轮研究已经公开；稳定收益、收益来源及适用范围仍是待解决的问题。

- **已完成：** v1.0 插件集成、macOS 验证、公共 CI，以及四冲程任务的原生对照和论文整理。
- **下一阶段计划：** 预先冻结多个任务与评分规则，增加独立重复，随机化运行顺序，对成品匿名评分；分别开展自然完成和同等预算比较。
- **随后验证：** 分别关闭团队协作或验证机制，观察收益来自哪里，再决定哪些机制值得保留和优化。
- **平台待办：** 补充 Linux / Windows 真实 Harness 主机验证。当前真实宿主实测范围为 macOS Web。

后续评估将以**完整任务通过率**为主要指标，并同时报告质量、严重故障、耗时和分类用量。

## 使用与进一步了解

当前包名为 `dsh-apex@1.0.0`，预设为 `apex-v1`；固定兼容基线为 **DeepSeek Harness v0.1.6-alpha.1**。源码通过本仓库分发，尚未发布到 npm。安装前请按文档核对官方构建与依赖版本。

- [安装、升级与卸载](docs/APEX-1.0.md#安装与升级)
- [设计、工具行为与运行边界](docs/APEX-1.0.md)
- [测试方法](docs/APEX-1.0.md#测试迁移与验收)与[公开版本验证结果](docs/PUBLICATION.md)
- [实验论文、数据与复现脚本](papers/diesel-engine-2026-09-16/README.md)

项目采用 [MIT 许可证](LICENSE)，复用内容的归属见 [NOTICE](NOTICE)。