CodeSampleX

CodeSampleX

经过测试，而非猜测。

语言： English · 한국어 · 日本語 · 简体中文 · Español · Français · Deutsch · Português (BR) · Русский

从这里开始： CLI 快速开始 · 无需安装即可使用公共 REST API · 连接 MCP 客户端

CLI 快速开始（Windows PowerShell）

安装并检查二进制文件，然后在 PowerShell 中提出第一个问题：

irm https://codesamplex.dev/install.ps1 | iex
csx version
csx search "axios multipart upload" --package pkg:npm/axios

安装程序会让你选择 JOIN COMMUNITY 或 LOCAL ONLY。社区模式会预热首个缓存并启动后台同步；仅本地模式会禁用自动网络访问，缓存为空时可能无法返回结果。之后可以通过 csx init --community 或 csx init --local-only 更改模式。

csx version 会输出 csx v<version>。搜索会返回针对检测到的环境评估过的答案；使用结果前，请先查看各项结果的环境差异。NO_SAFE_MATCH 表示没有找到经过验证的匹配项，并不表示安装失败。请在项目目录中运行搜索，以纳入项目的依赖项和运行时环境信息。

如果 PowerShell 找不到 csx，请打开新的终端，或使用 & "$env:LOCALAPPDATA\csx\csx.exe" version 检查已安装的二进制文件。有关 macOS / Linux 和安装详情，或 MCP 客户端设置，请继续阅读下文。

CodeSampleX 记录什么

CodeSampleX 是一个面向开发者库、运行时和工具链的开放兼容性测试网络。它不会总结文档，也不会收集轶事。它记录真实构建实际发生的情况，环境以记录为准，而非凭空假设——然后告诉你哪些地方运行正常、哪些地方出了问题，以及具体在哪种环境中。

有两项核心资产，第三项是额外福利：

• 证据 — 开发者的真实机器上的真实构建记录，包含环境、阶段、结构化终止信息，以及经过秘密信息安全处理的规范化故障指纹。缺失或过时的故障详情会显示为证据缺口，绝不会被编造为原因。只要安装了 csx，证据就会自动产生，因此它能覆盖容器测试环境无法覆盖的平台：没有容器能复现 macOS 主机——Mac 上的 Docker 运行的是 Linux 虚拟机，那是另一台机器，只是披着同一台笔记本的外衣——npm 不发布 Windows 镜像，而 musl、ARM、企业基础镜像和实际安装的运行时版本更是无穷无尽。只有这一项才能填满兼容性地图。
• 发现 — 我们从这些证据中发现的矛盾：称职的开发者或模型会如何预期，与实际发生的情况之间的差异。这些发现是我们愿意为之负责的内容，也是模型最常出错的地方，因为文档恰恰不会说明这些内容。
• 示例 — 我们亲自编写并验证的可运行代码。这是刻意提供的额外福利：容器集群永远无法覆盖所有情况，因此经过验证的示例是高于证据的可信度等级，而不是得到任何答案的前提条件。

所以，没有命中也不代表一无所有。若没有任何内容能证明适用于你的情况，评级仍会是 NO_SAFE_MATCH——并会一并返回已记录的观察结果，如实呈现。

• 兼容性地图：https://codesamplex.dev
• 它回答的问题：在那里能运行吗？——这个 API，在这个版本、这个操作系统和这个运行时下。
• 它给出的答案：这是实际发生的情况，以及运行环境。 报告器使用轮换的对等分桶；独立的第一方活动分析则使用稳定的假名化客户端 ID，从不使用姓名或 IP 身份。请参阅分析语义。

当前提供的功能

CodeSampleX 不再只是一个搜索命令。当前发布的产品提供多个功能入口，且都基于同一证据模型：

功能入口	当前用途
兼容性	按软件包、版本、符号和环境浏览已记录的兼容性
依赖项	反向依赖关系图谱：哪些已记录的父版本引入了某个依赖版本；一条边不代表兼容性判定
缺口	对 Sample / Evidence / Dependency 的完整性进行普查，取代旧版网站的 Wanted 排名
发现	由可复现样本支持的实测矛盾以及版本／环境边界
功能	零安装 REST 快速入门、REST / MCP / CLI 功能矩阵、MCP 工具契约和 skill.md
样本 · 适配器 · 统计数据	已验证的工件、生态系统功能矩阵和公开网络汇总数据

CLI 是规范的本地接口。csx help 根据二进制文件中的命令生成；测试会确保此表与其保持一致，避免新增命令在 README 中被遗漏。

命令	功能
config	读取或更改本地设置
daemon	运行、启动、停止或检查后台同步守护进程
doctor	诊断本地安装；--fix 会修复由 CSX 安全管理的状态，并再次验证
hook	启用、禁用、检查或自测安装到受支持编码 Agent 中的自动构建失败查询功能
init	选择社区／仅本地模式，配置 Agent、预热首个缓存并启动后台同步
login	使用 GitHub 登录，以便发布带署名的样本
mcp	运行供 Agent 客户端使用的 stdio MCP 服务
mcp-config	输出供 MCP 客户端使用的 JSON/TOML/路径配置
run	运行命令并为公开依赖记录经脱敏处理的证据
sample	提议、创建、预览、验证、发布、移除、列出或审核待处理的净室样本
sample-worker	操作私有创作工作／会话交接通道
scan	无需运行构建即可检测公开依赖
search	搜索已验证且按目标环境评定的样本
stats	显示本地缓存、队列、命中和采用计数
sync	预热兼容性分片并刷新排队中的社区上传（必要时使用 --uploads-only）
ui	打开本地仪表板和隐私预览
update	安全地检查、安装、查看或回滚签名更新
version	输出已安装的 csx 版本
worker	贡献 Docker 隔离的跨环境／矩阵验证工作

该网络还会在受支持的编码 Agent 中安装可选的构建失败钩子。当 Agent 的 shell 构建失败时，钩子会对失败的构建步骤进行分类，在本地清理错误信息，搜索 CodeSampleX；未找到结果或命令无关时则保持静默。csx hook status 可显示已安装的内容；csx hook check 会通过一次临时的失败构建，验证已注册的钩子路径。

无需安装即可读取网络

CodeSampleX 为 Agent、浏览器和脚本提供公开的 REST 接口。网站呈现的每个答案，只需一次普通 HTTPS 请求即可获取——无需密钥、无需账户、无需客户端库，任何源都能读取。只有在需要捕获本地执行情况、自动触发构建失败钩子、发布或使用 worker 功能时，才需要安装 CLI。

一次请求，获取真实的生产环境 JSON——照原样复制：

curl 'https://codesamplex.dev/v2/search?package=pkg:npm/axios&symbol=axios.post&os=linux&runtime=node&runtimeVersion=22'

答案包含 grade，并且每条结果都会列出匹配的环境维度（exact[]）和不匹配的维度（different[]）。未命中时会标记为 grade: "NO_SAFE_MATCH"——这是真实答案，并非未能作答。通用的 Web 能力 Agent 可从 https://codesamplex.dev/skill.md 读取完整约定；docs/rest.md 则为用户提供相同的快速入门指南。

三种方式对比。每个标记都由测试对照路由器和命令列表进行检查，Features 页面也列出了相同的表格：

能力	Web REST（无需安装）	MCP	已安装 CLI
搜索经过验证、按环境评定等级的示例	✅	✅	✅
按软件包、版本、符号和环境查询兼容性	✅	✅	⚠️ csx search 根据已同步的分片评定等级；没有 explain 命令
读取单个示例的清单、回执和文件	✅	✅	⚠️ 通过 csx search --json；没有专用的示例读取命令
读取发现集合	✅	❌ 仅限 Web 和 REST	❌ 仅限 Web 和 REST
读取缺口、需求和公开统计数据	✅	❌	⚠️ csx stats 仅显示本地计数器
在浏览器、云端 Agent 或脚本中使用	✅	⚠️ Agent 的 MCP 主机必须在本地运行 csx	❌ 需要本地二进制文件
零安装使用	✅	⚠️ MCP 服务就是 csx 二进制文件；客户端主机必须安装 csx	❌
自动检测本地项目和环境	❌	⚠️ 只能检测 MCP 主机运行的本地 csx 所能看到的内容	✅
运行真实的本地构建或测试	❌	⚠️ run_observed_command 通过本地 csx 运行	✅
捕获经清理的结构化执行证据	❌	⚠️ 只能通过 MCP 主机运行的本地 csx 捕获	✅
提交未签名的执行足迹	✅	❌ 改为提交关联的采用证据	❌ 改为提交关联的采用证据
自动构建失败查询钩子	❌	❌	✅
后台同步和离线缓存	❌	❌	✅
上传任何内容前预览隐私影响	❌	❌	✅
发布经过验证的示例	❌	❌ 刻意不提供发布工具	✅ 由用户在 CLI 中确认
Worker 和矩阵验证	❌	❌	✅
经过签名的验证回执（ed25519，由 worker 生成）	❌	❌	✅

REST 用于读取网络。CLI 让网络观察现实。 MCP 是 CLI 的适配器：csx mcp 本身就是 csx 二进制文件，因此没有安装 csx 的主机上的 MCP 客户端无服务可连接。

它能在那里运行吗？

每条结果都与生成它的环境相关联，因此同一组数据可以按版本 × 符号、操作系统 × 运行时、版本 × 架构、浏览器/运行时、libc 以及其他已记录维度进行透视。当前统计数量请使用实时兼容性探索器或 pgx/v5 这样的包页面；README 不会把实时网络数据冻结成带日期的截图。下方示例仅用于说明：

                                         v5.10.0     v5.9.2
github.com/jackc/pgx/v5                  ▤ —         —
Batch                                    ▤ —         —

矩阵单元格会显示观测记录，并在有样本文档时一并显示。观测数量表示已记录的构建在哪些阶段通过——编译、类型检查、测试；它们既不是用户数，也不是机器数。样本文档则表明该坐标存在可复现的契约；其状态反映这些样本验证运行的结果。这两类证据不会合并计算。

因此，项目能够编译绝不会被描述为某个符号可用。— 仍表示未知，缺少样本仍表示缺少样本。该地图记录该坐标上实际发生的情况，而不会把少量运行结果拔高为通用的 PASS 判定。

为什么测试很重要

Documentation   → what should work
Code search     → how somebody used it
Community       → what somebody says worked
CodeSampleX     → what was actually tested

让地图保持准确的规则：

• 项目能够编译绝不会被描述为某个符号可用。观测记录与验证结果分别计数，绝不相加。
• 未知原因保持为 UNKNOWN。错误的 HIT 比 MISS 更糟——NO_SAFE_MATCH 是一个真实答案。
• 证据不会随时间衰减，也不会将任何单元格标记为过期。一次观测是在某个阶段、某个固定环境类别中对某个固定版本进行的记录，这些条件都不会改变：某次构建在那里失败，一年后仍然是事实。可能发生变化的是环境，而不同的环境就是不同的单元格。
• 失败原因以概率分布形式报告，绝不凭空给出确定结论。

安装 CLI

CLI 是本地测试器：它会封装真实构建，将其结果转化为匿名证据，并从网络获取答案。

Windows（PowerShell）：请按照上方的 CLI 快速入门完成安装、检查版本并进行首次搜索。

macOS / Linux：

curl -fsSL https://codesamplex.dev/install.sh | sh

该命令需要 curl 和 CA 证书，而精简镜像（debian-slim、alpine、大多数 Agent 容器）通常不包含这些组件——并且如果缺少 curl，curl … | sh 仍会以 0 退出，因为管道会报告最后一个命令的状态。请先安装所需组件，或改用 wget：

apt-get install -y curl ca-certificates            # debian / ubuntu slim
apk add --no-cache curl ca-certificates            # alpine
wget -qO- https://codesamplex.dev/install.sh | sh  # needs neither

在 Windows 上，安装程序会将稳定版启动器保存在 %LOCALAPPDATA%\csx\csx.exe，并将 %LOCALAPPDATA%\csx 添加到用户 PATH。在 macOS/Linux 上，默认路径为 ${CSX_INSTALL_DIR:-$HOME/.local/bin}/csx；如果该目录尚未位于 PATH 中，请将其添加进去：

export PATH="$HOME/.local/bin:$PATH"
csx version    # install check — the supported spelling is `csx version`

一个二进制文件，一个问题。csx init 会显示下方的契约，并询问一个选项——加入社区或仅本地使用。通过 sh 管道传入时，标准输入会被下载管道占用，因此 init 会采用所示默认值：加入社区。可随时使用 csx init --local-only 选择退出；两种模式标志均可重复运行，且支持非交互模式。对于脚本或 CI 设置：csx init --community --yes --no-agents。

PurplePulse v2 激活时，每个 UTC 日最多发送一次以下信息：project_id、持久化的随机 install_id、版本、操作系统、platform（cli 或 mcp）、schema_version: 2，以及可选环境信息；设置 DO_NOT_TRACK=1 或 CSX_TELEMETRY=0 可将其禁用，CI/容器/无服务器运行不会发送生产遥测数据。

测试与检查

csx run -- pnpm build                 # wrap a build/test; its result becomes sanitized evidence
csx search "axios multipart upload"   # verified answers graded for YOUR environment
csx --debug search "axios multipart upload" # same answer plus local decision trace
csx hook status                       # see which supported coding-agent hooks are installed
csx hook check                        # prove the failure-hook path with a throwaway failing build
csx scan                              # record public dependency usage without running a build
csx stats                             # local dashboard: cache, hits, adoption, queues
csx ui                                # browser dashboard + privacy preview
csx sync                              # manually refresh shards / flush queues when needed
csx mcp-config                        # print MCP client configuration
csx update check                      # verify whether a signed update is available

在社区模式下，csx init 已会执行有界的首次缓存预热，并启动后台同步守护进程。新安装状态正常时，首次提问前不需要例行执行 csx sync。如果安装程序提示预热不完整或不可用，csx sync 就是明确的恢复途径；csx sync --uploads-only 会刷新排队等待上传的内容，而不执行分片重新扫描。在示例作者会话中（已设置 CSX_SESSION_TOKEN），同步始终采用仅上传路径，并设有五分钟的截止时间，包括直接调用二进制文件时也是如此；取消操作会返回非零状态，并保留待处理数据。

local-only 则有意采用不同的行为：它会禁用自动网络访问，因此按设计可能只有冷启动的兼容性缓存。之后若要加入网络，明确的方式是重新运行 csx init --community。

csx search 会根据记录的目标环境为每条结果评级——EXACT、COMPATIBLE、ADAPTATION_REQUIRED、REFERENCE_ONLY 或 NO_SAFE_MATCH——并列出具体的环境差异，而不会把相近的运行环境说成完全相同。

自动查找失败原因

Agent 不应该需要记住 hook 路径。对于受支持的编码 Agent，失败的 shell 构建可以自动交由 CodeSampleX 处理。该钩子只会介入可识别的构建／测试命令，不会发送原始日志；如果没有安全匹配项，也不会给出提示。使用 csx hook off 可将其禁用；需要确认已注册的钩子是否仍会触发时，可运行 csx hook check 获取实测结果。

已验证的示例

示例不是代码片段，而是一个最小化、以内容寻址的项目（其规范化制品的哈希为 sha256:<hex>），并附带一份契约：在固定容器中离线执行并通过的断言。镜像由摘要固定，而非由标签固定——标签只是供读者识别的别名，实际运行的是摘要所指向的镜像；已签名的收据会注明确切的镜像引用，因此任何人都可以重新运行相同的字节，而不必只听信他人的说法（docs/adapters.md）。隔离环境中的创作流程仅通过 CLI 完成：

csx sample propose --goal "upload a file with axios"   # sanitized brief + scaffolded workspace
csx sample create <dir>      # ingest the clean-room project
csx sample preview <id>      # show EVERYTHING that would be published
csx sample verify <id>       # resolve → compile → contract, sandboxed
csx sample publish <id>      # requires typing exactly "yes"; leakage findings hard-refuse
csx sample pending           # list agent-prepared drafts waiting for human review

如果你希望示例发布内容归属于自己的 GitHub 身份，请使用 csx login github；匿名发布仍是 CLI 中的一项明确选择。发布时会扫描机密信息、路径、项目名称和私有 URL——发现问题会阻止发布，且没有可绕过的标志。上传示例源代码并非 MCP 能力；只有通过 CLI 操作的人类才能发布。

发现

问题出在哪里？发现列出了实测到的矛盾：将文档（或普遍认知）中的说法与契约测量结果并列展示，包括文档不符、特定环境下的失败和版本边界。每一条都链接到证明该结果的已发布示例，你可以重新测量并提出异议。

机器推导的发现来自已发布的示例，其作者记录了他们要纠正的认知；无需任何人编辑页面来添加这些发现。

依赖关系图谱

依赖关系从依赖项一侧读取已记录的依赖关系图：**哪些父版本引入了这个确切的依赖版本？**这有助于回答仅凭软件包页面无法解答的影响范围和升级问题。一条边表示解析器曾在一个实测项目中将这些版本组合在一起；我们有意不把它当作这对版本兼容的证明。

覆盖缺口

缺口展示语料库的完整程度。它列出每个坐标在三种相互独立的资源——示例、证据、依赖关系——方面仍缺少什么，而不是只对某人碰巧搜索过的内容排序。需求队列仍以 GET /v1/wanted 的形式供自动化和调度使用，但公共网站采用 /gaps，因为需求与完整度是两个不同的问题。

证据与评级

为什么要相信某个单元格？每项结果都附带其证据等级，从弱到强：

等级	实际发生的情况
USAGE_OBSERVATION	使用该软件包构建／类型检查／测试了真实项目——已观察到，证据较弱
ADOPTION_EVIDENCE	有人应用了示例，并报告之后构建是否通过
SAMPLE_VERIFICATION	示例的契约在固定版本的容器中执行并通过
CROSS_PASS	除发布该结果的密钥之外，另一个对等方密钥重新运行并再次通过
MATRIX_PASS	通过的凭据涵盖 ≥2 种操作系统／运行时主版本／浏览器系列边界
STABLE	≥3 个不同的对等方密钥通过，且 30 天内未记录失败

对等方是一个密钥，不是一个人，也不是一台机器。对等方 ID 是自生成 ed25519 密钥的哈希值，没有注册机制，因此一名操作者可以持有任意数量的密钥，只要他们运行相应数量的工作进程即可。“不同的对等方密钥”表示同一坐标由多个地方报告；这绝不代表人数，而且这里的任何信息都无法识别是谁运行了什么。

示例页面也会标注验证阶梯 L0_SOURCE_ONLY → L5_MATRIX_PASS，矩阵单元格则附带置信度（HIGH／MEDIUM／LOW）、失败增多标记和最近观察日期。只有经过签名的 v2 凭据可以声明 resolvedPackages——即验证器实际安装的版本，而非作者填写的版本；快照会将每份凭据存放在实际运行的版本目录下。

公开计数器是汇总数据，无需账户即可通过 JSON 获取：

curl -fsSL https://codesamplex.dev/v1/stats

字段	统计内容
packages / symbols	覆盖情况：兼容性数据中的公开软件包名称和观察到的符号
evidence	已接受的观察记录；不是用户、项目或已验证示例的数量
verifiedSamples	带有沙箱契约通过凭据的不同示例数量
peers / projectsMonth	不同的匿名每日／每月贡献者分组
activeInstallations1d / activeInstallations7d / activeInstallations30d	当前对齐的 UTC 1／7／30 天时段内，来自普通或外部客户端的不同匿名在线令牌；这些不是滚动时间窗口，也不是人数
postHitBuildsReported	包含测量结果 PASS 或 FAIL 的采用情况报告

CodeSampleX 尚不能可靠地衡量独立／活跃用户、运行中的 MCP 进程或成功安装次数。统计响应中的任何 estimated* 字段都明确基于公式计算，不应视为实测计数。测量严格划分为两个不同层面——内部检索质量与用户结果价值——并遵循字段优先的防护原则，不捏造提升幅度（docs/measurement-layers.md）。

贡献者工作进程

网络中的环境是其他人的机器。闲置机器可以参与 Docker 隔离验证，而无需触碰 MCP 或 Agent 配置：

csx init --community --yes --no-agents --no-daemon
csx worker start                         # idle-aware, 2 Docker lanes
csx worker start --parallel 4 --budget 15m

工作进程只接受服务器分配的 VERIFY 任务（cross／matrix）——队列绝不会发送任意 shell 命令。构件采用内容寻址并经过哈希校验；解析过程在容器中运行；编译和契约阶段在一次性 Docker 工作区中断网运行，内存限制固定为 512m，PID 限制固定为 256；如果 Docker 守护进程缺失，则会直接拒绝执行，绝不会回退到宿主机运行。结果是经过 ed25519 签名的 v2 凭据；原始阶段日志仅保留在本地。

API

无需账户即可通过 JSON 获取网站呈现的相同数据。读取路由接受来自任意源的请求（CORS *）；零安装调用方唯一可以进行的写入是执行足迹，它会作为未签名的自我报告记录，不会对任何评分产生影响：

端点	提供内容
GET /v2/search?q=&package=&symbol=&os=&runtime=&runtimeVersion=	通过 URL 获取经过评分的答案：使用与 MCP 工具和 CLI 相同的处理流程；未命中时为 grade: NO_SAFE_MATCH
POST /v2/search	通过 JSON 请求体获取相同答案（{schemaVersion:2, query, packages[], symbols[], environment{}}）
POST /v1/search	提供冻结的 v1 响应格式，供固定使用该格式的客户端使用
GET /v1/registry/packages/{purl}	软件包详情和软件包级快照
GET /v1/registry/symbols/{eco}/{package}/{family}	某个符号的逐版本快照
GET /v1/samples/{id}, …/artifact	样本元数据、凭据和 tar.gz 源码
GET /findings.json	Findings 页面展示的所有已测量矛盾，以及证明每项矛盾的样本
GET /v1/wanted	需求队列 API：用户请求但尚未得到答复的内容（网站完整性视图位于 /gaps）
GET /v1/adapters	各生态系统的能力矩阵
GET /v1/stats	每日网络汇总数据
GET /v1/shards/{eco}/{package}/{major}	预先物化的兼容性分片（使用 ETag 缓存）
GET /v1/peers/for-sample/{sampleId}	持有该样本的节点，可用于不经由此服务获取样本
POST /v1/footprints/execution	可选的零安装执行足迹：{sampleId, outcome: pass|fail|could_not_run, stage, environment{os,arch,runtime,runtimeVersion}}；未签名，绝不会提升样本
GET /skill.md	面向只能获取 URL 的 Agent 的本接口机器可读指南
GET /version	响应请求的服务构建版本及其运行环境

通过真实请求快速开始：docs/rest.md。

Agent 适配器（MCP）

编码 Agent 通过适配器使用同一网络——MCP 是 CLI 之上的连接器，而不是产品本身。REST API 是主体；CLI、MCP 以及未来的任何 Agent 协议都是基于同一数据的适配器：

CodeSampleX
├─ REST      ← zero-install read surface: agents, browsers, scripts, CI
├─ Web       ← compatibility map / reports, drawn from the same routes
├─ CLI       ← local execution, evidence capture, hooks, privacy preview, publishing, worker
├─ MCP       ← adapter on the CLI for MCP-capable agent clients (csx mcp IS the csx binary)
└─ skill.md  ← usage guide for generic web-capable agents, no adapter needed

csx init 会自动配置 Claude Code、Codex、Gemini CLI、Antigravity (agy) 和 OpenCode。其他任何 stdio MCP 客户端（Cursor、Windsurf、Cline、Zed、VS Code）都可以使用 csx mcp-config 输出的内容（Codex 使用 --toml）——它会输出绝对二进制路径，这是由编辑器启动的客户端所需的路径。实时契约也会在 功能 中呈现。服务器本身是 csx mcp。共有十个工具：search_known_solution、get_sample、explain_compatibility、run_observed_command、report_sample_adoption、report_anomaly、report_csx_issue、propose_public_sample、list_local_hits、get_local_stats——并且有意不提供发布工具。

主机 IDE、编码 Agent 和开发者平台可以将 CodeSampleX 作为内置或推荐选项提供，而不暴露连接器细节。合作伙伴集成契约及其机器可读配置文件定义了这一路径的受管软件包生命周期、同意边界、能力策略和证据语义。

report_anomaly 的作用方向相反。当 CSX 的答案与 Agent 自己机器上的实际情况明确不符时——网络针对某个坐标给出了通过的结论，但该坐标在本机失败；返回的符号签名与软件包导出的内容不符——Agent 可以将其提交为验证请求。这不是错误报告：报告会在生成所有其他凭证的同一设备集群上排入独立的重新运行队列，且只有该凭证才能确认问题。没有任何测量结果作为依据的提交会被拒绝；同一不匹配重复报告只会生成一条报告和一次重新运行；报告中的任何内容在验证器确认之前都不会出现在任何公开页面上。报告者对原因的猜测会放在独立字段中，绝不会决定判定结果。

report_csx_issue 的思路相同，但针对的是我们，而非某个软件包：答案转移了你实际在查看的故障、推荐了问题中从未提及的生态系统，或工具契约导致模型行为错误。此功能为可选且刻意保持低调——没有任何内容会提示 Agent 在失败后调用它，不会创建工单，而且一周内没有报告也是正常情况。一百个 Agent 遇到的缺陷只会对应一条记录，出现次数会递增；一旦该记录关联到错误，之后的每份报告都会返回该链接。这两个渠道共用接收、脱敏和去重流程，此后便不再共享任何内容：本产品中的缺陷绝不会成为兼容性证据。

面向 Agent 的安装步骤（包括 MCPB 捆绑包和直接二进制下载，以及 SHA256SUMS.txt）：llms-install.md。独立社区安装会通过 Ed25519 签名清单自动更新——由正在运行的后台同步守护进程、csx mcp 或 csx worker start 检查，因此即使只有 CLI 和守护进程在运行，MCP 和 worker 均未运行，也仍会自动更新——并提供 csx update rollback；local-only 安装不会发出更新请求。

合约

You get                              You contribute
✓ Public compatibility knowledge     ✓ Public package/version usage
✓ Verified code answers              ✓ Public API/symbol usage when detectable
✓ Local agent integration            ✓ Build/typecheck/test result
✓ Public sample cache                ✓ Sanitized failure fingerprints

Never shared automatically
✕ Source code        ✕ Repository/project name   ✕ File names or paths
✕ Source snippets    ✕ Secrets or env variables  ✕ Private packages
✕ Raw compiler/runtime logs

这不是隐藏的遥测数据，而是协议本身。社区节点既是消费者，也是生产者。仅本地模式绝不会发送任何内容。错误会在使用前于本地清理并转换为指纹；私有和未知的软件包绝不会离开设备；csx ui 中的隐私预览会显示即将发送的确切载荷。NO_SAFE_MATCH 会贡献一个保护隐私的 Wanted 元组——包括公开软件包、其确切版本，以及（当请求中指定了一个明确的软件包时）所请求的公开符号；绝不包含用户的提示词。公开部署仅提供预置的示例源代码；搜索、证据、收据和需求看板均无需账户即可访问。

隐私政策

上述合约就是代码的实际行为。PRIVACY.md 以政策形式逐项说明了同一内容，指出每道边界由哪个文件实施：社区模式会上传哪些确切文档、哪些请求是下载而非上传、服务器会存储什么以及存储多久，以及 local-only 所说的“什么都不发送”具体意味着什么。该政策在此代码库中进行版本管理，而不是托管在一个可以悄无声息地编辑的网页上；MCPB 包的 privacy_policies 数组也指向这个 URL。

生态系统（公开版 v1）

已扫描并验证——检测项目、解析锁文件中的软件包，并端到端验证示例：Node/TypeScript（npm、pnpm、yarn——参考实现）、Python（pip、uv）、Go、Rust/Cargo。Node 示例会在其声明的运行时上执行，因此 Bun 和 Deno 的结果是真实运行所得，而非推测。

仅已验证——尚无项目扫描器，但已发布的示例会在固定的容器中构建并通过合约测试：PHP/Composer、Ruby/Bundler、Dart/pub、Elixir/Hex。Java（Maven/Gradle）合约验证会锁定 JDK 8/11/17/21/25 的确切运行通道。

仅观察到证据——检测项目并观察构建，但没有容器验证器：Unreal Engine（通过 adapters/unreal 识别 .uproject——在开发者工作站上将目标引擎版本报告为观察到的证据；无容器验证通道）。

如实呈现的能力矩阵：docs/adapters.md——符号解析置信度始终会标注为（EXACT/PROBABLE/UNKNOWN）。

架构

单个 Go 二进制文件（csx：守护进程 + CLI + MCP + 对等节点 + 验证器）和一个小型服务器（csx-server：PostgreSQL + 位于 Caddy 后方、由服务器渲染的兼容性浏览器）。示例采用内容寻址，并按本地缓存优先 → 对等节点 → 主种子节点的顺序分发。下载的示例绝不会直接在主机上运行：解析过程会在固定的沙箱中执行，并在生态系统支持的情况下禁用安装脚本；解析后会重新计算制品哈希，编译和合约阶段则会断网运行。当前的规范参考文档为 docs/architecture.md、docs/schema.md、docs/execution-context.md、docs/diagnostics.md、docs/operations.md 和 docs/activation-funnel.md——后者说明了从安装到首次获得有效答复之间，哪些内容可以或不可以衡量，以及为什么独立用户数和活跃用户数不在衡量范围内。goal.md 是最初的产品计划。

运行模式、原则与 Public v1 范围

以下是从初始计划沿用的长期产品决策（goal.md — 现已弃用，仅保留空白占位；完整计划文本保存在 git 历史记录中）。如果实现已超出计划，以代码和上述文档为准。

运行模式。 公共网络免费开放。运营资金来自赞助（初始计划中的 GitHub Sponsors 模式；网站页脚提供赞助链接）。计划为未来可能推出的付费 Hosted API 预留了空间，面向不贡献证据、存储或验证的纯 API 用户——该层级明确不在 Public v1 范围内。

不可妥协的原则。 违反以下任何一项都需要项目所有者明确批准：

• 不会自动传输真实项目源代码，自动收集证据仅涵盖公共注册表中的包。
• 社区节点既是消费者，也是生产者——这是协议本身，而非隐藏遥测。
• Evidence 网络与 Sample 池始终是独立系统，绝不会把项目编译成功说成某个 API 单独调用成功。
• 未知原因保持为 UNKNOWN；宁可返回 NO_SAFE_MATCH，也不强行判定为 HIT。
• 产品的默认行为不依赖服务端 LLM 推理或中心化构建集群；只要可行，本地功能在中央服务器宕机时仍会继续运行。
• 发布示例源代码和贡献闲置 CPU 进行验证，均须分别明确征得同意。
• 没有契约的示例，在验证阶梯上不会超过 L2（已编译）。
• 永远不使用区块链、代币经济或全局账本。
• 核心客户端和公共协议始终保持开源。

不在 Public v1 范围内（初始计划的范围决定；如果已发布产品后来实现了更多功能——例如上述仅限经过验证的生态系统——则以已发布产品为准）：企业／私有包网络、SSO／SLA／本地部署、纯 API 计费、为每种编辑器提供专用 IDE 扩展、拦截每种 Agent 的完整 Shell、为每种语言提供运行时符号检测、Android／iOS／Unreal／Unity／C++ 验证器（注意：通过 adapters/unreal 支持 Unreal Engine 项目检测和引擎版本观察）、中心化大规模构建集群、通用项目记忆或架构／业务逻辑共享、自动发布源代码、确定性的失败原因判定，以及仅使用 DHT 的网络。

成功指标。 成功与示例数量或注册人数无关。初始计划承诺跟踪以下指标：Agent 搜索调用率、Precision@1、已接受 HIT 的比例、HIT 后构建通过率、适配距离、证据覆盖率、交叉验证率、失败归因置信度，以及估算的推理工作量避免量——最后一项明确是估算值，而非测量得出的数量（参见上方统计表）。

从源代码构建

go build ./cmd/csx && go build ./cmd/csx-server
go test ./...

这不需要数据库：如果未设置 CSX_TEST_DSN，internal/serverstore 中的 PostgreSQL 测试会自行跳过。在 CI 中，这些测试不可跳过——.github/workflows/ci.yml 会针对一次性 postgres:17-alpine 运行每个拉取请求；如果其中任何测试被跳过，运行就会失败。这项运行是 main 上的必需检查，因此一旦失败就会阻止合并——其背后的规则集以及任务重命名后的处理方式，详见 docs/operations.md。如需在本地以相同方式运行：

docker run -d --rm --name csx-pg -e POSTGRES_USER=csx -e POSTGRES_PASSWORD=csx \
  -e POSTGRES_DB=csx -p 5432:5432 postgres:17-alpine
CSX_TEST_DSN="postgres://csx:csx@localhost:5432/csx?sslmode=disable" \
  CSX_REQUIRE_TEST_DSN=1 go test ./...

每项测试都会迁移自己的临时架构，并在之后将其删除，因此测试套件可重复运行，两次运行也可以共用一个数据库。CSX_REQUIRE_TEST_DSN 会将缺少 DSN 从跳过测试改为测试失败；CI 设置的就是该变量。

许可证

代码：Apache-2.0。已发布的示例默认采用 MIT-0。证据和汇总的兼容性数据：CDLA-Permissive-2.0（参见 DATA_TERMS.md）。

作者主管可以设置 CSX_SAMPLE_WORKER_RESERVATION=SAMPLE（或传入 csx sample-worker next --reservation SAMPLE），为示例预留新的声明。现有声明会按常规进行协调；符合条件的示例队列为空时会返回 NO_WORK。不支持的服务会拒绝该预留，不会回退到混合工作模式。