AgentKit Studio
贡献

贡献指南

参与 AgentKit Studio 开发的入口:环境准备、三层门禁、DSH 补丁治理、文档写作规范与公开边界。

AgentKit Studio 是一个产品插件,不是 DSH 的分支。它扩展官方 DeepSeek Harness(DSH)宿主, 并把产品能力作为插件交付。这条边界决定了贡献方式:改 Studio 的行为,遵循 DSH 的公开契约, 不把 DSH 源码树复制进本仓库。

这一章解决什么问题

你现在的状态从这一页开始你会得到
刚 clone 仓库,还没跑起来开发环境一条可复制的初始化路径,以及三个数据目录的隔离方式
改完了,不知道要跑什么门禁与验证三层门禁各自跑什么、哪些 PR 必过、失败怎么定位
需要改 DSH 宿主行为补丁治理维护提交 → 导出补丁 → 校验的完整闭环
要写或改文档文档写作规范页面骨架、术语、链接与双语 1:1 规则
不确定某段内容能不能公开安全与公开边界14 条红线与本地自检命令

三条不可协商的守则

  1. 单一目的:一个 PR 只做一件事。行为变更必须带回归测试;纯文档变更不要顺带改代码。 范围混在一起,评审就无法判断"这条改动的风险边界在哪"。
  2. 事实有源码依据:任何一个命令、默认值、枚举、错误码,都必须能在 Makefile、package.json、 scripts/**、ci/** 或 src/** 里指到具体位置。指不到就不写——旧文档里那些互相矛盾的 版本号与计数,全部来自"凭印象写"。
  3. 公开边界优先:仓库是公开的。凭证、客户数据、个人路径、内网端点、私有部署证据一律不提交。 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.js24.22.1安全基线 22.23.4+ / 24.22.1+ / 26.12.1+,见 .node-version
pnpm10.33.2通过 Corepack 启用,版本必须与 packageManager 一致
Git任意近期版本补丁治理依赖完整历史,CI 使用 fetch-depth: 0
Make 与 C 工具链任意近期版本DSH 原生模块需要编译
DSH 检出固定基线放在仓库之外,用来应用补丁

Windows 原生环境不支持这些 Make 目标,请使用 WSL2。完整步骤见开发环境。

提交一篇文档的最小流程

文档改动同样走门禁,但路径更短:

  1. 读文档写作规范的页面骨架与术语表,确认页面类型。
  2. 同时改 foo.mdx 与 foo.en.mdx——双语 1:1 是硬性要求,缺一半会构建失败。
  3. 在 docs-site/ 下跑四条自检命令(成对、无残留标记、无内部信息、链接带 .mdx)。
  4. 跑 make public-surface-audit,确认没有越界内容。
  5. 提交前确认 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 分钟。

获取帮助

  • 提交前先跑门禁与验证里的最小集合,多数问题在本地就能暴露。
  • 卡在 DSH 检出的版本或补丁上:看补丁治理的「常见失败」。
  • 不确定某段内容是否越界:看安全与公开边界,或先按最严格的理解删掉。
  • 发现安全漏洞:不要开公开 issue,按 SECURITY.md 的渠道私下报告。

本页导航