DeepSeek-Reasonix 贡献指南：从第一个PR到CI通过的新手完整教程-编程实验室

DeepSeek-Reasonix 贡献指南：从第一个PR到CI通过的新手完整教程

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix

DeepSeek-Reasonix是一个运行在终端的 DeepSeek 原生 AI 编程智能体（AI coding agent），以**前缀缓存稳定性（prefix-cache stability）**为核心设计——你可以把它长期挂着跑而不怕 token 成本悄悄爆炸。本文是一份面向新手的完整贡献教程：从搭建 Go 环境、本地构建，到读懂 CI 会查什么，最终提交一个能顺利合并的 PR。

为什么它适合新手做第一个开源贡献

📖 贡献规范集中在一份文档：CONTRIBUTING.md
🔍 CI 规则全部公开可读：.github/workflows/ci.yml
📝 PR 模板直接告诉你"该写什么"：.github/pull_request_template.md
🧩 项目主体用 Go 编写，分层清晰，改动范围容易界定

环境准备：两个必装工具 + 一个可选工具

工具	要求	用途
Go	1.25+	项目主体语言，必装
Git	较新版本	版本控制，必装
Node.js + Wails CLI	可选	仅当你想开发`desktop/`桌面端时需要

💡 只改 CLI 或核心 Go 代码的话，Go + Git 两件套就够。桌面端开发请记得先跑make wails-install安装与项目锁定版本一致的 Wails CLI。

克隆仓库并构建第一个二进制

git clone https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix cd DeepSeek-Reasonix make build # 编译 CLI 与插件示例 make test # 运行全量测试

make build会在bin/目录生成reasonix可执行文件，入口代码在 cmd/reasonix/ 目录。构建脚本统一封装在 Makefile 中，后面会反复用到。

隔离环境调试：不碰你的正式配置

用REASONIX_HOME环境变量给开发版一个独立的"家目录"：

REASONIX_HOME=/tmp/reasonix-dev go run ./cmd/reasonix

首次启动时该目录是空的，像全新安装一样，配置、凭据、会话、缓存全部独立存放，不会读写你的生产数据——这是新手最安全的调试姿势。

看懂项目结构：先知道代码该放哪

贡献前建议先扫一遍这张"地图"（来自 CONTRIBUTING.md 的 Project structure 章节）：

目录	职责
`cmd/reasonix`	CLI 入口
`internal/agent`	智能体主循环、会话、协调器
`internal/cli`	TUI 界面、子命令、初始化向导
`internal/provider`	模型后端抽象层
`internal/tool/builtin`	内置工具（bash、read_file 等）
`internal/memory`	REASONIX.md 层级与自动记忆
`internal/skill`	从 Markdown 发现技能
`internal/hook`	Shell 钩子（PreToolUse 等）
`desktop/`	Wails 桌面应用（独立 Go module）
`docs/`	工程规范与用户文档

依赖方向是单向的：cli → {agent, plugin, config} → {tool, provider}。父包永不导入子包，子包通过init()自注册。记住这一点，你就不会把代码写错位置。

📌 新手友好的切入方向：给internal/i18n/补一条中英文文案、给docs/补文档、或新增一个小工具——都是低风险的第一个 PR。

本地开发流程：CI 查什么，你就先跑什么

在 Makefile 中，本地跑绿下面这条链，CI 基本就稳了：

make build # 编译 make test # go test ./... make vet # go vet 静态检查 make fmt # gofmt 格式化 make lint # golangci-lint + 仓库规范检查

必须遵守的四条代码风格规则

gofmt由 CI 强制执行，提交前必须先格式化
错误用fmt.Errorf("...: %w", err)包装，不静默丢弃
库代码（internal/）永不直接os.Exit或打印到标准输出
导出的标识符必须写文档注释

CI 通关解析：你的 PR 会经历哪些关卡

打开 .github/workflows/ci.yml 即可看到完整流水线，新手重点看五关：

① 变更过滤：只跑相关的测试

CI 先用changes任务分析 diff 范围：纯文档改动跳过重型 Go 测试；只改site/只跑网站测试——PR 反馈更快。

② 三平台测试矩阵

test任务在Ubuntu / macOS / Windows上并行执行gofmt、go vet、go build、go test ./...。注意 Linux 端额外开启了REASONIX_RELEASE_CACHE_GUARD=1，会运行前缀缓存稳定性守卫测试（TestCacheHit*）——缓存命中率回归会直接挂 CI，因为这是项目的立身之本。

③ 并发测试（-race）

race任务用-race模式扫描并发密集包（agent、plugin、jobs、proc 等），防止竞态条件溜进主线。

④ Lint 与仓库规范

lint任务依次执行：

go run ./tools/repolint——项目自研的仓库规范扫描器
golangci-lint（版本由 .golangci-version 锁定，本地用make lint-install可装同款，避免版本漂移）
跨平台构建标签检查，确保 Windows/macOS 专属文件同样通过检查
Wails 版本锁校验：scripts/check-wails-pin.sh

⑤ 其他关卡

coverage任务收集覆盖率报告；govulncheck扫描标准库漏洞（信息性，不阻塞）；动了桌面端还会额外跑前端 Playwright 测试和 WebKitGTK 原生冒烟测试。

PR 模板：三个 TODO 是新手最常翻车的地方

提交 PR 前对照 .github/pull_request_template.md 填写，重点盯三处：

① Issues 区——想让 issue 自动关闭，Fixes #123必须单独成行；写在列表项里是无效的。

② Documentation-impact 行——用户可见的 CLI / 配置 / 工具行为变化必须二选一：

Documentation-impact: updated - <改了什么>（同步更新docs/*.md）
Documentation-impact: none - <为什么现有文档仍然正确>

③ Cache-impact 三行——本项目特色门槛。若改动碰了系统提示词构造、记忆前缀、输出风格、技能索引、工具 schema 或 MCP 注册等缓存敏感路径，必须填写Cache-impact（none/low/medium/high + 原因）、Cache-guard（新增或运行过的守卫测试）、System-prompt-review（提示词类改动需评审人审批）。CI 会对这些路径强制校验元数据（见 .github/workflows/cache-impact.yml），漏填会被直接拦截。

提交前检查清单

go test ./...本地全绿，gofmt -l .输出为空
功能分支从main-v2创建，PR 也指向main-v2
提交信息遵循 Conventional Commits 格式，如feat(agent): …、fix: …、test(event): …
PR 模板中Documentation-impact与Cache-impact已填写
修 bug 时：Fixes #123单独成行

⏱️ 小技巧：先跑make hooks安装 git 钩子，pre-push 会自动执行go vet，把低级错误拦在提交之前。

常见 CI 失败与快速修复

CI 报错	原因	快速修复
gofmt 失败	格式未对齐	本地跑`make fmt`后重新提交
golangci-lint 失败	风格或写法建议	`make lint-install`装 CI 同款版本，本地`make lint-go`复现
Cache-impact 拦截	缓存敏感改动漏填元数据	按 PR 模板补全三行说明
测试偶发超时	runner 机器抖动	本地`go test -count=1 ./...`复跑确认