学术研究中枢Yie-zhang/academic-research-hub

学术研究中枢

CI

状态：预发布 Windows 参考实现

学术研究中枢是一个可复现的 Windows 编排层，用于通过 OpenAI Secure MCP Tunnel、Agent Helm、Serena 和 DeepSeek Harness (DSH) 将 ChatGPT 连接到本地研究/编码环境。

ChatGPT
|
OpenAI Secure MCP Tunnel
|
tunnel-client
|
Agent Helm
+-- Serena
+-- DSH / native coding-agent delegation

该项目专注于 Windows 安全的进程编排、凭据隔离、可复现的 DSH 组合、显式的运行时状态诊断以及可审计的发布门禁。

本仓库存在的原因

上游组件已经提供了核心能力。本仓库解决的是当它们被组装成一个持久化的 Windows 工作流时出现的集成问题：

- Agent Helm 的 Windows 命名管道兼容性；
- 无需复制用户私有配置文件的 DSH 配置文件组合；
- 受 DPAPI 保护、位于 Git 之外的 Runtime API 密钥存储；
- 可选代理配置，而非硬编码的本地代理；
- 终止进程前进行安全的进程所有权检查；
- 显式的 STOPPED、STARTING、DEGRADED 和 HEALTHY 状态；
- 区分本地 /readyz 与成功的 OpenAI 控制平面轮询；
- 干净配置文件的安装以及隔离的本地运行时 E2E 测试。

关于这些决策背后的工程历史，请参阅 docs/MIGRATION_STORY.md。

公开 / 私有边界

本仓库包含公开的生命周期脚本、引导逻辑、生成配置文件逻辑、测试、架构文档以及非机密示例。

它不包含或再分发：

- Runtime API 密钥或其他 OpenAI 凭据；
- 真实的 Tunnel ID；
- DPAPI 二进制块；
- 私有工作区 ID 或研究路径；
- 用户名或机器特定的配置文件路径；
- 私有 DSH UI 皮肤、浏览器调试集成、统计软件 MCP 服务器或模型路由器；
- OpenAI tunnel-client。

仅限本地的值会被 Git 忽略，Runtime API 密钥默认位于：

%LOCALAPPDATA%\AcademicResearchHub\runtime-key.dpapi

已测试基线

| 组件 | 已测试版本 |
| --- | --- |
| Node.js | 24.19.0 |
| DeepSeek Harness | 0.1.1-rc.2 |
| Serena | 1.7.0 |
| OpenAI tunnel-client | 0.0.11 |
| @beforewave/dsh-with-chatgpt | 0.1.2 |
| @beforewave/agent-helm | 0.1.2 |

DSH 目前是一个开发者预览项目，因此版本变更可能会带来破坏性改动。上述版本是已测试的基线，并不表示每个更新的版本都不兼容。

先决条件

首先安装上游运行时，并确保这些命令在 PATH 上可用。

- Node.js： 版本 22 或更高。
- DSH： 遵循 DeepSeek Harness 上游的安装/快速开始说明。
- Serena： 上游目前推荐使用 uv tool install -p 3.13 serena-agent，然后运行 serena init。
- OpenAI Secure MCP Tunnel / tunnel-client： 通过 OpenAI 获取访问权限和客户端。本仓库不创建也不分发此先决条件。

参见 docs/INSTALL_WINDOWS.md 和 THIRD_PARTY.md。

快速开始

检查或安装固定版本的 DSH 集成：

.\scripts\Install-AcademicResearchHubDependencies.ps1 -CheckOnly
.\scripts\Install-AcademicResearchHubDependencies.ps1

初始化本地配置和受 DPAPI 保护的 Runtime API 密钥：

.\scripts\Initialize-AcademicResearchHub.ps1

编辑：

config\hub.config.local.psd1

并替换 YOUR_TUNNEL_ID，然后启动并检查：

.\scripts\Start-AcademicResearchHub.ps1
.\scripts\Status-AcademicResearchHub.ps1

仅停止已验证的 Hub 进程：

.\scripts\Stop-AcademicResearchHub.ps1

用于自动化：

.\scripts\Stop-AcademicResearchHub.ps1 -NoPrompt

Windows DSH 组合

@beforewave/dsh-with-chatgpt@0.1.2 提供 Agent Helm / Secure Tunnel 集成。Academic Research Hub 不会复制用户的永久 DSH Web 配置文件。

相反，它会生成一个本地被忽略的覆盖层，并通过 DSH 的 --patch 机制传递。在 Windows 上，该覆盖层提供一个命名管道：

\\.\pipe\agent-helm-daemon

并同步配置的 DSH Web、Agent Helm 和隧道健康端口。

运行时状态

- STOPPED 闁?没有配置的 Hub 组件端口正在监听。
- STARTING 闁?本地组件存在，但就绪/控制平面轮询尚未收敛。
- DEGRADED 闁?仅部分堆栈正在运行，或某个配置的端口被未验证的进程占用。
- HEALTHY 闁?所有组件均已验证，/readyz 成功，且 commands_poll_last_successful_timestamp_seconds > 0。

仅凭 /readyz 有意不被视为端到端连通性的证明。

测试

静态/公共安全门禁：

.\scripts\Test-AcademicResearchHub.ps1

当前基线：

PASS: 61 static/public-safety checks passed.

隔离的本地运行时 E2E：

.\tests\Invoke-LocalRuntimeE2E.ps1

此测试会创建一个临时的干净 DSH_HOME，安装固定版本的集成，仅在 47080/47081 上启动 DSH Web + Agent Helm，有意保持 Secure Tunnel 禁用，验证 DEGRADED，安全停止已验证的测试进程，并移除所有临时状态。

公共 Status 脚本也已针对一个真实可用的三组件 Secure MCP Tunnel 运行时进行了只读验证，并正确返回 HEALTHY。

参见 docs/TESTING.md 和 docs/TROUBLESHOOTING.md。

发布状态

已完成的门禁：

- 公共源代码安全分离；
- Windows PowerShell 解析器/静态安全；
- 全新 DSH 配置文件安装；
- 最小 pnpm 构建批准；
- Windows 命名管道组合；
- 可配置的 DSH/Agent Helm/Tunnel 端口；
- 隔离的本地运行时启动/状态/停止端到端测试；
- 针对真实 Secure MCP Tunnel 运行时的只读 HEALTHY 观测；
- 提交后 Git 历史机密扫描；
- 从 GitHub 进行公开的全新克隆验证；
- MIT 许可证与第三方依赖边界。

仍然有意不自动化：

- 一种破坏性交接，其中公开的 Start 脚本会替换操作员唯一的活动 Secure MCP Tunnel；

对于破坏性的完整 Start/Tunnel 交接测试，应使用单独的测试 Tunnel 或对操作员安全的手动环境。

维护者工作流通过 issue/PR 模板、SUPPORT.md、CODE_OF_CONDUCT.md 和 docs/RELEASE_CHECKLIST.md 进行记录。

仓库布局

.github/      CI 工作流
config/       公开配置模板
docs/         架构、安装、安全、测试、故障排除
examples/     非机密 DSH 覆盖示例
scripts/      引导与生命周期脚本
tests/        隔离的集成/端到端测试框架

许可证

Academic Research Hub 根据 MIT License 发布。

另请参阅 SECURITY.md、SUPPORT.md、CODE_OF_CONDUCT.md、CONTRIBUTING.md、THIRD_PARTY.md 和 docs/RELEASE_CHECKLIST.md。