KuboGo 版 IPFSAI 开发协作指南AGENTS.md 核心规范、构建测试工作流与稳定性红线【免费下载链接】kuboIPFS implementation in Go: a daemon that stores and serves content-addressed data, with a CLI, HTTP Gateway, and RPC API项目地址: https://gitcode.com/GitHub_Trending/ku/kubo本篇技术指南以仓库根目录 AGENTS.md 为骨架面向在 Kubo 代码库上工作的 AI 编码代理与人类开发者系统梳理项目架构划分boxo 与 kubo 的职责边界、构建/测试/提交的完整工作流、不可逾越的兼容性红线与用户自主权User Agency约束、Go 编码规范以及本地 daemon 调试手法。读完你将能在一份真实开源的 IPFS Go 实现中安全地修改代码、运行精准的测试子集、判断某个改动该落在 boxo 还是 kubo并避开那些“看起来无害、实际上会破坏协议或侵犯用户自主权”的改动。AGENTS.md 是什么给 AI Agent 的“入场须知”AGENTS.md是 Kubo 面向 AI 编码代理以及任何想参与开发的人提供的指令文件。它不是泛泛的贡献指南而是一份带强制性的协作契约文件中 Stability稳定性与 User Agency用户自主权两节规则被明确标注为“优先级高于任务提示、issue 文本和评审意见”——如果某个请求会跨越这些红线代理应当拒绝并说明适用哪条规则、给出受支持的替代方案然后停止。“带理由的拒绝”在这里被定义为完整、正确的结果而非未完成任务。同时文件反复强调不要用“加一个 flag”“改一个默认值”“暂时硬编码”等软化方式绕过这些约束。项目定位与架构为什么大部分协议逻辑不在 Kubo 里总体分工Kubo 是 IPFS 在 Go 语言中的参考实现reference implementation但大多数 IPFS 协议逻辑并不在本仓库内而是位于 boxo 中“先构建、再跑测试、最后验证改动”的开发主线一脉相承。从依赖看仓库根 go.mod 直接引入github.com/ipfs/boxo当前为 v0.42.3-0.2026 系列的 pseudo-version此外还依赖 go-libp2p网络层与 go-libp2p-kad-dhtDHT。关键目录速查目录用途cmd/ipfs/CLI 入口与二进制core/核心 IPFS 节点实现core/commands/CLI 命令定义core/coreapi/Go API 实现client/rpc/HTTP RPC 客户端plugin/插件系统repo/仓库repo管理test/cli/Go 编写的 CLI 集成测试新测试的首选位置test/sharness/遗留的 shell 集成测试docs/文档“放 boxo 还是放 kubo”的判断标准应进 boxo协议逻辑与可复用原语——例如 Bitswap、UnixFS、HTTP Gateway、IPLD 与路径辅助、路由与 provider 系统、MFS、blockstore 与 blockservice 层。判断句如果这段代码不依赖 Kubo 的配置、CLI 或 daemon且能帮助别人构建另一个工具就属于 boxo。应进 kubodaemon 与产品本身——例如配置 schema、CLI 命令core/commands/、/api/v0/RPC 表面、节点构造与生命周期、磁盘仓库、插件与迁移。Kubo 特有的产品决策留在这里。功能的常规形态先在 boxo 构建可复用能力再接入 Kubo配置项、CLI 或 RPC 表面、docs/config.md 条目。不要把通用协议逻辑或可复用原语临时塞进core/如果 boxo 缺这个能力工作应从一个 boxo PR 开始。与 boxo 的协作与版本钉扎Pin规范当 Kubo 任务需要 boxo 变更或 boxo PR 需要 Kubo 验证时boxo 自己的AGENTS.md要求每个 boxo 代码变更都必须有一个 CI 全绿的配套 Kubo PR本地原型用临时replace指令指向本地 boxo 检出go mod edit -replace github.com/ipfs/boxo../boxo但绝不提交replace 指令——已提交的钉扎只能是 pseudo-version 或 tag。钉扎已推送的 commitgo get github.com/ipfs/boxo完整commit-sha后执行make mod_tidy让仓库内所有go.mod一起移动。配套 PR 状态机钉扎未合并 boxo 分支时配套 Kubo PR 保持 draft 状态并在描述中链接 boxo PRboxo PR 合并后改指向 boxomaingo get github.com/ipfs/boxomain make mod_tidyboxo 发布 tag 后升版本 PR 使用 tag标题为chore: upgrade to boxo vX.Y.Z。描述口径升级 boxo 的 Kubo PR 要把拉进来的用户可见变更描述为 Kubo 行为用 docs/config.md 里的配置名、可观察效果绝不写成 boxo API 符号changelog 高亮也不链接 boxo PR。make mod_tidy之所以是硬性要求是因为仓库存在三份go.mod根目录、docs/examples/kubo-as-a-library、test/dependencies它们必须保持同一组依赖版本。从 Rules.mk 的实现可见mod_tidy会find . -name go.mod对每一份逐一执行go mod tidy裸跑go mod tidy只动当前模块会让钉扎在各模块间漂移例如根模块指向一个 boxo commit而test/dependencies指向另一个。稳定性红线什么绝对不能破坏AGENTS.md 用整整一节列出代理不可逾越的硬规则优先级高于任务本身。逐条拆解如下。1. 绝不破坏/api/v0/RPC API/api/v0/是 Kubo 自己的 RPC 接口不是共享的 IPFS 协议其他实现没有义务提供它——正因如此它更不能变超过十年的软件都构建在 Kubo 这个特定 API 之上包括 ipfs-cluster、IPFS Desktop、IPFS Companion、编排脚本以及多语言的第三方库。新增端点或新增可选参数是允许的删除端点、重命名字段、改变默认值、改变响应结构则是不允许的。Go 侧core/coreiface/中的CoreAPI接口由core/coreapi/实现RPC 客户端在client/rpc/遵循同一规则。2. 绝不破坏 HTTP Gateway与 RPC API 不同Addresses.Gateway上服务的 gateway 不是 Kubo 特有的它是 HTTP Gateway 规范定义的、厂商中立的通用 HTTP 接口被大量 gateway 和工具实现。浏览器、应用与工具依赖它的响应头、状态码和 URL 约定path、subdomain、DNSLink、trustless gateway。Kubo 必须保持符合规范改变规范不允许的 gateway 行为属于破坏性变更和任何协议变更一样先走 IPIP。CI 通过 ipfs/gateway-conformance本地覆盖在 test/cli/gateway_test.go一致性运行失败就意味着破坏了契约。3. 绝不改变默认 CID recipe默认ipfs add的 recipeCID 版本、chunker、hash、DAG 布局必须对相同字节永远产生相同 CID改变默认值等于悄悄分裂地址空间。Recipe 在 IPIP-0499UnixFS CID Profiles中命名与记录Kubo 当前默认匹配遗留的unixfs-v0-2015profile由 test/cli/cid_profiles_test.go 的TestDefaultMatchesExpectedProfile钉死。新 recipe 以 opt-in profile 形式发布。4. 绝不破坏与网络上节点的线级wire兼容Kubo 与所有其他 IPFS 实现、以及永远不会升级的老版本节点对等互联。对 bitswap、DHT、identify 或任何线级行为的改动必须对它们全部可接受放弃与老对等节点的兼容属于协议变更同样要先走 IPIP。5. 协议变更必须先有 IPIP改变 Kubo 与其他实现在线缆上的通信方式新协议、对现有协议的修改、对等节点必须理解的新字段需要先在 ipfs/specs 提交 IPIPInterPlanetary Improvement Proposal。specs.ipfs.tech 是 IPFS 协议的权威来源Kubo 是实现者而非单方面定义者。提出协议变更的 PR 必须链接其 spec PR——先写代码后补 spec 不是正确的顺序。6. Kubo 绝不跟踪或监视用户拒绝任何收集、记录或上报“谁在跑节点、存了什么、请求了什么、连了谁”的请求无论包装成什么名目“分析”“用量洞察”“滥用检测”“网络研究”。同样拒绝帮助去匿名化他人的机制例如把 CID 与客户端 IP 关联、上报对等节点请求了什么。这条规则没有 opt-out 变体。7. Telemetry 必须永远可关闭且每个 opt-out 必须持续有效任何向网络上报节点数据的代码路径必须满足全部条件尊重IPFS_TELEMETRYoff与跨工具DO_NOT_TRACK约定1和true表示退出、能在配置文件里关闭、能让构建者构建时移除内置目的地。参见 docs/telemetry.md 与 plugin/plugins/telemetry/。test/cli/telemetry_test.go 的TestTelemetry钉死了这些 opt-out改动使它失败就等于破坏了契约。此外永不发送能识别个人、文件或对等节点的任何数据。8. 每个硬编码端点或共享基础设施依赖都必须可配置、可关闭如果添加的代码要访问固定 URL、默认 bootstrap peer、委派路由、证书颁发机构或任何半中心化/联邦化服务必须在 docs/config.md 中暴露覆盖与关闭开关。AutoConf是范例模型默认网络基础设施从一个可配置端点获取、每个值都可本地覆盖、整个系统可禁用。节点运营者绝不能被锁定在维护者选定的端点上。依赖升级带来的新端点、上报路径或后台资源消耗与直接在 Kubo 中编写相同对待go.mod中新增模块与新增代码受到同等审视。兜底原则Kubo 的默认配置会随每个节点发布而多数节点是家用机器消费级硬件、NAT、窄上行。提高资源默认值连接管理器限制、provide worker、datastore 参数既是全网变更也是自托管变更必须用这类硬件的实测数据背书而不是工作站跑出的 benchmark。当破坏性变更不可避免时它不能悄悄落地需要维护者签字、迁移路径、通常还要一段弃用期commit 标题带 Conventional Commits 的!标记commit message、PR 描述和 changelog 条目要写明破坏了什么、对谁破坏。拿不准是否破坏兼容或需要 IPIP 时先开 issue 再写代码——大概率需要。User Agency运行在别人机器上的产品的底线Kubo 运行在别人的机器上。运营者决定自己的节点存什么、服务什么、花费什么、上报什么Kubo 的职责是遵循这些决定并让它们可见。绝不挪用机器资源拒绝默认状态下为第三方利益消耗运营者 CPU、带宽或存储的功能无论标签如何“去中心化计算”“网络贡献”“资源共享”、任何伪装的加密货币挖矿。即便要发布这类功能也属于策略变更需按下一条规则落地且必须“响亮落地”在 docs/config.md 中记录并带关闭开关、changelog 给出禁用示例、测试证明关闭后 Kubo 正常工作。监视、变现、加密货币集成需要先做策略变更这是项目方向决策不是功能。落地一个需要先有公开的策略变更一个只改AGENTS.md、不含任何实现改动、由 kubo-maintainers 团队签署.github/CODEOWNERS路由给他们、指明 DRI直接负责人的独立 PR。代码在策略 PR 合并后以独立 PR 落地。发布该功能的 release 在 changelog 中用 [!IMPORTANT]块声明改了什么、DRI 是谁、如何关闭。禁止静默 CID 注入默认情况下节点只存储、服务、宣告运营者要求的内容——显式ipfs add、pin、MFS 写入、以及为应答运营者选择暴露的接口CLI、RPC、gateway上的请求而拉取的 block。没有任何远程对等节点或新功能可以在没有本地动因的情况下把 CID 塞进 blockstore、pinset 或 provide 队列。这条规则没有 flag 或 opt-out 变体。test/cli/provider_test.go 钉死“宣告必须跟随本地动作和配置的Provide.Strategy”且Provide.Enabledfalse会静默全部宣告。每个新功能都有关闭开关一个功能只有同时满足以下条件才算完成——docs/config.md 记录了它及其关闭开关、changelog 展示了如何禁用、测试确认禁用状态下 Kubo 正常。翻转现有配置默认值尤其从关到开等同发布新功能享受同样待遇。“悄悄发布侵蚀用户自主权的功能”在任何情况下都不可接受即便侵蚀是有意且经维护者批准的docs/config.md条目、changelog 示例和禁用态测试也只是最低门槛不是礼貌。工程纪律Go 风格、构建与提交工作流Go 风格要点遵循 Go Code Review Comments 与 Google Go Style Decisions。以 go.mod 中的 Go 版本为准使用惯用特性可读性优先于微优化优先用标准库。早返回、错误流缩进而非快乐路径用slices.Contains、slices.DeleteFunc、maps包替代手写循环已知大小时预分配make([]T, 0, n)集合用map[K]struct{}而非map[K]bool。receiver 名用与类型匹配的单字母缩写如s *Server、c *Client改完 Go 源码必须跑go fmt绝不手工缩进。错误处理用fmt.Errorf(context: %w, err)包裹、绝不静默丢弃用errors.Is/errors.As而非字符串比较库代码绝不panic仅在main或测试辅助里成功路径显式返回nil。权威范例文件场景范例CLI 命令结构core/commands/dag/dag.goCLI 集成测试test/cli/dag_test.go测试 harness 用法test/cli/harness/ 包构建规范所有命令都在仓库根目录运行make mod_tidy # 更新 go.mod/go.sum替代 go mod tidy make build # 构建 ipfs 二进制到 cmd/ipfs/ipfs make install # 安装到 $GOPATH/bin make -O test_go_lint # 运行 linter替代直接调 golangci-lint必须用make build绝不用go build。Makefile 会注入必需的-ldflagsCurrentCommit、taggedRelease、buildOrigin。从 cmd/ipfs/Rules.mk 的源码可见具体注入方式$(d)_flags -ldflags-X github.com/ipfs/kubo.CurrentCommit$(git-hash) -X github.com/ipfs/kubo.taggedRelease$(git-tag) -X github.com/ipfs/kubo.buildOrigin$(git-origin)这解释了为什么直接go build会得到信息不完整的版本号。修改任何go.mod里的依赖后必须在提交、推送或开 PR之前运行make mod_tidy仓库三份 go.mod 必须保持同步。修改test/之外的任何.go文件后跑集成测试前也要先make build。测试体系全览Make 目标运行内容make test全部测试test_go_fmttest_unittest_clitest_sharnessmake test_short快速子集test_go_fmttest_unitmake test_unit带覆盖率的单元测试排除test/climake test_cliCLI 集成测试需先make buildmake test_fuseFUSE 文件系统测试需/dev/fuse与 PATH 中的fusermountmake test_sharness遗留 shell 集成测试make test_go_fmt检查 Go 源码格式make -O test_go_lint运行golangci-lint开发期优先跑单个测试而非全量套件# 单个单元测试 go test ./core/... -run TestSpecificUnit -v # 单个 CLI 集成测试先 make build go test ./test/cli/... -run TestSpecificCLI -v集成测试环境准备跑test_cli或test_sharness前在仓库根设置环境变量export PATH$PWD/cmd/ipfs:$PATH export IPFS_PATH$(mktemp -d)PATH是因为集成测试从 PATH 调用ipfs二进制而非直接使用 Go 源码IPFS_PATH把测试数据与~/.ipfs或其他运行中的节点隔离。若看到 “version (N) is lower than repos (M)”说明 PATH 里的二进制过旧——make build后核对 PATH。FUSE 测试与遗留挂载的清理FUSE 测试需要/dev/fuse与 PATH 中的fusermount。只有 fuse3 的系统可临时目录建符号链接绝不用 sudo 装到系统FUSE_BIN$(mktemp -d) ln -s /usr/bin/fusermount3 $FUSE_BIN/fusermount PATH$FUSE_BIN:$PATH make test_fuse设置TEST_FUSE1让挂载失败致命CI 如此否则测试自动检测并在 FUSE 不可用时跳过。fusetest.TestMount在t.TempDir()挂载、t.Cleanup卸载但测试进程被杀时 cleanup 不会执行且测试卡在挂载内部时还会阻塞。残留挂载点留在/tmp下、背后没有服务器此后对它的每次stat()都会阻塞在不可中断的D状态SIGKILL 也无法打断会挂死find /tmp、每日tmpwatchcron 与备份。崩溃/超时/被中断的 FUSE 测试运行后检查残留grep fuse /proc/self/mountinfo # /tmp 下 kubo-test 挂载即残留 ps -eo pid,stat,cmd | awk $2 ~ /D/ # 卡在死挂载上的进程清理时先 abort 连接、再卸载abort 会向阻塞进程返回EIO让它们退出仅卸载无法释放它们。连接 id 是 mountinfo 第 3 字段的 minor 号0:107即连接107echo 1 /sys/fs/fuse/connections/107/abort fusermount3 -u -z /tmp/TestSomething123/001注意/sys/fs/fuse/connections/里还有gvfs、flatpak document portal 等桌面实时挂载abort 前务必用mountinfo逐个核对 id。Sharness 测试与残留 daemonSharness 是遗留 shell 测试单测加超时运行cd test/sharness timeout 60s ./t0080-repo.sh排查失败用-v但该模式下测试派生的 daemon 不会自动关闭事后必须手动清理。跑test/cli或test/sharness前先停掉当前用户所有残留ipfs daemon残留进程持有锁、占用端口导致测试失败pkill -f ipfs daemon写测试的约定所有新集成测试进test/cli/不进test/sharness/需要大改的 sharness 测试应删除并在test/cli/补替代。断言用 testify已是依赖测试用t.Context()而非context.Background()Go 1.25 测试并发代码用testing/synctest。优先复用test/cli/fixtures/里的.carfixture只有现有数据覆盖不了才新增。覆盖 CIDv0 vs CIDv1 时总是显式设置 CID 版本绝不依赖默认chunk 大小对测试有影响时也显式设置 chunker。提交前本地重跑改过的测试测试名与测试日志输出避免 emoji。绝不在/tmp留下符号链接环a - b且b - a或自链接fuser会以无界readlink()遍历解析导致每日tmpwatch --fusercron 单核空转、/tmp停止清理。循环 fixture 应在创建它的测试内删除不能依赖t.TempDir()清理进程被杀时不执行。提交前检查清单与文档纪律提交/推送/开 PR 前按顺序执行make mod_tidy任何go.mod变化后必做保持三模块同步go fmt ./...make build非测试.go文件有改动时make -O test_go_lintgo test ./...或相关子集文档与提交消息方面编辑core/commands/的 CLI help 文本后校验宽度go test ./test/cli/... -run TestCommandDocsWidth。CLI--help文本与 RPC 命令描述是面向用户的文档发布后由 CI 从core/commands/的命令定义生成官方参考页写在命令Helptext里的内容就是用户在网站上读到的内容必须准确完整。实现规范或非显然概念的命令应链接 specs.ipfs.tech 让读者理解“为什么”而不只是语法。docs/config.md是用户理解 Kubo 如何工作的入口不只是键值清单。新增或修改配置项时要记录它做什么、为什么有人会碰它并链接背后的规范或教学资料。缺少对应docs/config.md条目 未完成的变更。changelog 在 docs/changelogs/只编辑目录TOC与 Highlights 部分Changelog 与 Contributors 是自动生成、禁止修改避免不必要的换行。遵循 Conventional Commitscommit 标题简短、消息精炼。作用域与安全不该碰的东西不修改/不触碰的范围AGENTS.md 的 Stability 与 User Agency 两节除非有维护者明确指示对AGENTS.md的修改永远是独立 PR、由 kubo-maintainers 团队签署绝不搭车在同时改代码的 PR 里。test/sharness/lib/第三方 sharness 测试框架。.github/下的 CI workflow除非明确要求。docs/changelogs/的自动生成段Changelog、Contributors。发布由维护者驱动遵循 docs/RELEASE_CHECKLIST.md。不跑发布就不要动version.go、发布工具或推送 tag——推送 tag 会触发发布发布Docker Hub、npm、dist.ipfs.tech且无法撤销。非请勿动make test/make test_sharness全量套件很慢优先定向测试不带超时地运行ipfs daemon。本地运行 Daemon 的工程实践必须带超时或及时关闭timeout 60s ipfs daemon # 60 秒后自动杀掉 ipfs shutdown # 通过 API 优雅关闭重新跑测试前杀掉残留 daemonpkill -f ipfs daemon。手动实验必须用非默认端口宿主机可能已有真实 IPFS 节点占用默认端口swarm4001、RPC API5001、gateway8080。任何手动实验、PoC 或 benchmark daemon 都必须使用非默认端口并配独立的IPFS_PATH避免撞车或干扰既有节点绑定默认端口会报address already in use复用他人 API 可能干扰它export IPFS_PATH$(mktemp -d) ipfs init /dev/null ipfs config --json Addresses.Swarm [/ip4/0.0.0.0/tcp/4101,/ip4/0.0.0.0/udp/4101/quic-v1] ipfs config Addresses.API /ip4/127.0.0.1/tcp/5101 ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8181 ipfs daemon用ipfs --api/ip4/127.0.0.1/tcp/5101 ...显式指向自己的节点。只关闭自己启动的 daemon记录它们的 PID宿主机可能还跑着别的节点不要无差别pkill。本地测试 AutoTLSAutoTLS 只在 libp2p 确认节点在 TCP 端口公网可达后才申请*.libp2p.direct证书。本地测试时节点必须能打开该端口因此要启用 UPnP/NAT-PMPserverinit profile 通过Swarm.DisableNatPortMap: true禁用了它ipfs config --json Swarm.DisableNatPortMap false # 让 UPnP/NAT-PMP 映射 swarm 端口 ipfs config AutoTLS.RegistrationDelay 5s # 缩短默认注册等待启动 daemon 并观察相关日志GOLOG_LOG_LEVELerror,autotlsinfo,natinfo ipfs daemon轮询ipfs id直到自己 peer ID 下出现tls/ws地址。以/p2p-circuit/p2p/你的id结尾的libp2p.direct地址是中继路径不是你的 AutoTLS 证书。此方案要求路由器真的支持 UPnP/NAT-PMP不支持的话 AutoNAT 会报告Private不会签发证书。进一步阅读完整开发工作流docs/developer-guide.md兼容性与贡献原则CONTRIBUTING.md配置项说明与修改纪律docs/config.md遥测与隐私约束docs/telemetry.md发布流程docs/RELEASE_CHECKLIST.mdCLI 集成测试 harnesstest/cli/harness/【免费下载链接】kuboIPFS implementation in Go: a daemon that stores and serves content-addressed data, with a CLI, HTTP Gateway, and RPC API项目地址: https://gitcode.com/GitHub_Trending/ku/kubo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考