Super Dolphin Harness Driver

开始之前

准备以下工具：

Go 1.26.5。
Node.js ^20.19.0 || ^22.13.0 || >=24 与 npm。
已安装并完成认证的 OpenAI Codex CLI，即终端中可以运行 codex。
gopls。
typescript-language-server 与 TypeScript 5.9.3。

当前桌面 Provider 主流程依赖 Codex。Claude 仅用于仓库中明确面向 Claude Provider 的集成，不是桌面主流程的替代配置。

获取项目

项目对外地址已经确定，但目前还不能匿名访问。已有权限的维护者可使用现有 checkout；仓库公开后使用：

git clone https://github.com/lihah111222333-cloud/Super-Dolphin.git
cd Super-Dolphin
make install-hooks

make install-hooks 会安装仓库自有的 Git hooks。它们是交付约束的一部分，不建议跳过。

安装工具链

在项目根目录执行：

go install golang.org/x/tools/gopls@latest
npm install -g typescript-language-server typescript@5.9.3
( cd frontend-app && npm ci )

确认 go、node、npm、codex、gopls 和 typescript-language-server 都能从当前终端找到。若使用 linked Git worktree，还需要按贡献指南先构建并验证该 worktree 自己的 LSP peer，不能复用其他 checkout 的二进制或 scope。

启动桌面应用

macOS：

./run-new-ui-desktop.sh

Windows PowerShell：

.\run-new-ui-desktop.ps1

启动成功后，应看到 Super Dolphin 桌面工作区，并且 Provider 初始化不会报告身份或认证缺失。系统对配置、身份和所有权采用 fail-fast：缺少必要信息时会明确失败，而不是静默切换到默认值。

验证环境

先运行基础构建与测试：

make build-plain
make test
make frontend-app-build && go test ./... -count=1
( cd frontend-app && npm run lint && npm test && npm run build )

查看一个文件变更会选择哪些维护门禁，但不实际执行：

./scripts/ai_maintenance_gates.sh --print-plan --changed-file README.md

需要复核仓库核心治理真源时运行：

make guard
make codemap-check
make project-map-check
make capcontract-check

这些门禁只治理本仓库，并会在生成真源过期或约束被破坏时失败。不要为了通过检查直接刷新生成物；只有所属真源被有意修改时，才使用对应的 *-refresh 目标。

MCP/LSP 启动契约

独立运行 mcp-lsp stdio 服务时，每个客户端配置必须显式提供：

SUPER_DOLPHIN_RUNTIME_MODE=dev
SUPER_DOLPHIN_RUNTIME_RESOURCES_DIR=<运行时资源根目录>
SUPER_DOLPHIN_DEPENDENCY_PROFILE=production

源码构建使用 checkout 根目录作为运行时资源根；跨平台 bin/LSP 包使用制品资源根。Windows 原生与 WSL 原生进程分别使用对应二进制和路径语义；Windows host 可以通过 wsl.exe 显式桥接 Linux sidecar，但禁止隐式混用。Windows 原生还需要受信 gopls bundle 字段。完整三模式示例见 Harness/LSP 兼容配置。

数据位置

SQLite 默认创建在 SUPER_DOLPHIN_HOME/super-dolphin.db。需要使用其他本地文件时设置 SUPER_DOLPHIN_SQLITE_PATH。PostgreSQL 环境变量不是产品数据库配置入口。

不要提交 Provider home、本地数据库、日志、用户 Memory、凭据或机器特定配置。

下一步

完成启动与验证后，阅读系统架构了解桌面、应用组合、业务模块、Store 与 Provider 的责任边界，或进入治理与证明理解为什么 Agent 的“完成”状态不能代替仓库证据。

快速开始