贡献指南
参与 AgentKit Studio 开发的入口:环境准备、三层门禁、DSH 补丁治理、文档写作规范与公开边界。
AgentKit Studio 是一个产品插件,不是 DSH 的分支。它扩展官方 DeepSeek Harness(DSH)宿主, 并把产品能力作为插件交付。这条边界决定了贡献方式:改 Studio 的行为,遵循 DSH 的公开契约, 不把 DSH 源码树复制进本仓库。
这一章解决什么问题
| 你现在的状态 | 从这一页开始 | 你会得到 |
|---|---|---|
| 刚 clone 仓库,还没跑起来 | 开发环境 | 一条可复制的初始化路径,以及三个数据目录的隔离方式 |
| 改完了,不知道要跑什么 | 门禁与验证 | 三层门禁各自跑什么、哪些 PR 必过、失败怎么定位 |
| 需要改 DSH 宿主行为 | 补丁治理 | 维护提交 → 导出补丁 → 校验的完整闭环 |
| 要写或改文档 | 文档写作规范 | 页面骨架、术语、链接与双语 1:1 规则 |
| 不确定某段内容能不能公开 | 安全与公开边界 | 14 条红线与本地自检命令 |
三条不可协商的守则
- 单一目的:一个 PR 只做一件事。行为变更必须带回归测试;纯文档变更不要顺带改代码。 范围混在一起,评审就无法判断"这条改动的风险边界在哪"。
- 事实有源码依据:任何一个命令、默认值、枚举、错误码,都必须能在
Makefile、package.json、scripts/**、ci/**或src/**里指到具体位置。指不到就不写——旧文档里那些互相矛盾的 版本号与计数,全部来自"凭印象写"。 - 公开边界优先:仓库是公开的。凭证、客户数据、个人路径、内网端点、私有部署证据一律不提交。
make public-surface-audit与secret-scan会在 CI 上拦截这类内容,历史 blob 也会被扫到。
提交前先跑最小集合:
make check这一条覆盖静态契约检查与全部单元测试。
什么时候还要多跑一层
涉及发布包、补丁序列或安全面的改动,再跑 make release-check。分层与失败定位见门禁与验证。
仓库结构速查
| 路径 | 内容 | 你会在这里改什么 |
|---|---|---|
src/ | Studio 的 Host 服务、API 适配与产品插件 | 产品行为、契约、运行时适配 |
src/client/ | 浏览器模块与 DSH UI 扩展 | 界面与交互 |
src/providers/ | 三种运行时的集成 | 运行时准入与执行路径 |
src/contracts/operations.mjs | 控制协议,134 个 operation | 改契约必须同步测试 |
patches/dsh-v0.2.2-rc.1/ | 对固定 DSH 基线的 53 个补丁 | 宿主兼容性修复 |
host-source/ | 归档的维护分支 bundle | 补丁的来源与校验 |
scripts/ | 开发、校验、打包与发布工具 | 门禁与自动化 |
ci/ | CI 专用脚本与 Gitleaks 配置 | 门禁执行环境 |
tests/ | 单元、契约与打包回归 | 回归覆盖 |
docs-site/ | 本站的源码 | 文档与导航 |
你需要什么
| 依赖 | 版本 | 说明 |
|---|---|---|
| Node.js | 24.22.1 | 安全基线 22.23.4+ / 24.22.1+ / 26.12.1+,见 .node-version |
| pnpm | 10.33.2 | 通过 Corepack 启用,版本必须与 packageManager 一致 |
| Git | 任意近期版本 | 补丁治理依赖完整历史,CI 使用 fetch-depth: 0 |
| Make 与 C 工具链 | 任意近期版本 | DSH 原生模块需要编译 |
| DSH 检出 | 固定基线 | 放在仓库之外,用来应用补丁 |
Windows 原生环境不支持这些 Make 目标,请使用 WSL2。完整步骤见开发环境。
提交一篇文档的最小流程
文档改动同样走门禁,但路径更短:
- 读文档写作规范的页面骨架与术语表,确认页面类型。
- 同时改
foo.mdx与foo.en.mdx——双语 1:1 是硬性要求,缺一半会构建失败。 - 在
docs-site/下跑四条自检命令(成对、无残留标记、无内部信息、链接带.mdx)。 - 跑
make public-surface-audit,确认没有越界内容。 - 提交前确认
git diff --check干净。
不要改 meta.json
侧边栏顺序由 meta.json / meta.en.json 统一维护。新增页面时先确认它在导航里的位置,
而不是自己插一条——两个语言文件的 pages 顺序必须完全一致。
常见问题
我只想改一行文档,需要装 DSH 吗?
不需要。文档改动只需要 Node.js 与仓库依赖:pnpm install --frozen-lockfile 之后直接改
docs-site/content/docs/ 下的 .mdx。只有需要跑真实宿主验证时才涉及 DSH 检出。
为什么我的 PR 在本地是绿的,CI 却红了?
最常见的三类原因:pnpm-lock.yaml 与 package.json 不一致(--frozen-lockfile 会失败);
新增依赖进了浏览器包(客户端门禁的体积预算);提交里带了未忽略的临时文件或凭证(公开面审计)。
逐项对照门禁与验证的失败定位表。
我必须同时写中英双语吗?
是。双语 1:1 是构建期硬约束:缺英文页、meta.json 与 meta.en.json 顺序不一致、
标题层级不同,任意一条都会让 docs-site-i18n 测试失败。
可以直接改 patches/ 下的 .patch 吗?
不能。补丁是维护分支的导出物,改了会让摘要、清单与应用顺序三重校验失败。走
补丁治理的四步流程。
make check 要跑多久?
静态契约检查是秒级,全部单元测试取决于机器;make release-check 因为要打包并扫描历史,
通常在分钟级。CI 上 public-gate job 的超时是 35 分钟。