企业官网建设流程全解析

cq 是由 Mozilla.ai 发起的共享 Agent 学习的开放标准：AI 智能体把踩过的坑沉淀为结构化的知识单元（Knowledge Unit），其他 Agent 查询即可直接复用，不再重复发现同样的失败。本文带你走完从提交第一个 PR 到参与开放标准制定的全部流程——包括环境搭建、分支规范、PR 评审节奏，以及普通人也能上手的两条贡献路径。

🧭 为什么值得给 cq 做贡献

cq 的目标被官方称为"Agent 界的 Stack Overflow"：由 Agent 写、为 Agent 用、由人类把关质量。它目前处于 0.x 阶段，正处于标准成型期——这意味着：

• 早期贡献者影响力大：Schema 字段、审查机制、治理规则都还开放讨论；
• 门槛友好：官方专门标记了适合新手的任务（good-first-issue和help-wanted标签）；
• 反馈明确：PR 承诺 5 个工作日内首次响应。

项目的完整愿景和治理思路见 docs/CQ-Proposal.md。

🛤️ 两条贡献路径，先选对方向

cq 明确区分两种贡献，各有独立的治理文件，动手前先确认你走的是哪条路：

第二条路径对纯使用者格外友好：只要你在日常使用 Agent 时把"未记录的 API 行为""已验证的变通方案"作为知识单元提交，就是在参与共享知识库建设。注意知识单元要求不含个人数据，提交后会经过自动护栏过滤与人工评审（详见 CONTRIBUTOR_AGREEMENT.md 的原文约定）。

本文聚焦代码贡献这条主线。

⚙️ 开发环境一键搭建：5 个依赖 + 一条命令

依赖清单

cq 是 monorepo，包含 CLI（Go）、Go/Python 双 SDK 和 FastAPI + React 服务器，开发前需准备：

克隆并初始化

git clone https://gitcode.com/gh_mirrors/cq9/cq cd cq make setup

make setup会串行完成 CLI、Schema、Go SDK、Python SDK、服务器前后端的全部依赖安装，入口定义在根目录 Makefile 中。

想先跑起来看看效果？两条命令起本地服务栈：

export CQ_JWT_SECRET=dev-secret make compose-up # 启动远程 API（http://localhost:3000） make seed-all USER=demo PASS=demo123 # 另一终端：建用户 + 灌入示例知识单元

详细命令对照（dev-api、seed-users等）都在 DEVELOPMENT.md 的 Docker Compose 与 Validation 小节里。

🌱 提交第一个 PR：完整操作步骤

第 1 步：认领一个适合新手的 Issue

在 Issue 列表中筛选good-first-issue或help-wanted标签，先在 Issue 下评论认领，避免和别人撞车。官方建议：

"Start small. A well-scoped first PR is easier to review and merge."（从小处着手，范围清晰的第一个 PR 更容易通过评审。）

该建议原文见 CONTRIBUTING.md 的 "Your First Contribution" 章节。

第 2 步：规划分支——先看 Issue，再动代码

在开始新功能、API 变更、架构调整、破坏性变更或新增依赖之前，必须先开 Issue 讨论，这能避免白干。

第 3 步：按规范命名分支

第 4 步：修改 + 测试 + 提交

官方对提交质量有 3 条硬要求（CONTRIBUTING.md）：

1. 每个变更都要有测试，Bug 修复必须包含能复现问题的测试；
2. Commit message 说明为什么改，而不只是改了什么；
3. 保持提交原子化：一个 commit 只做一件事。

第 5 步：发起 PR，写对描述

推送分支到你的 fork，向main发起 PR。描述里必须包含三件事：

• 改了什么、为什么改；
• 如何验证该变更（测试命令 / 复现步骤）;
• 关联 Issue（写Fixes #123或Closes #456可自动关闭）。

✅ 让 PR 快速过审：本地自测清单

评审前本地跑通这两条，可大幅减少往返：

make lint # 全组件格式化、lint、类型检查 make test # 全组件测试（含 Schema 校验）

💡 两个容易踩的坑：

• Prompt 同步：插件目录plugins/cq/是提示词的唯一权威来源，改动后需make sync-prompts同步到两个 SDK，否则check-prompts-sync会失败；
• Schema 同步：修改schema/下的 JSON 后需make sync-schema，并用make validate-schema验证 fixture（示例数据在 schema/fixtures/）。

评审期间的行为规范：

• 用追加新 commit回应评审意见，不要在评审中 force-push；
• 简单修复通常约 1 周合入，复杂功能 2–3 周；
• 超过 30 天无活动的 PR 可能被关闭，回来后可重新提交。

以上节奏均来自 CONTRIBUTING.md 的 "Review Process" 章节。

🏛️ 进阶：如何参与开放标准制定

cq 的"标准"核心落在三处，也是普通贡献者最有发言权的地方：

1. 知识单元 Schema —— 标准的"接口定义"

知识单元的数据格式由 schema/knowledge_unit.json 定义，配套查询、提案、确认等接口的 Schema 也在同一目录（query.json、propose.json、confirm.json、flag.json）。字段命名、枚举值、必填项的每次讨论都直接决定全球所有 Agent 的互操作方式。修改 Schema 后务必跑make validate-schema。

2. 设计文档与架构 —— 标准的"白皮书"

• docs/CQ-Proposal.md：标准提案原文，涵盖信任层（身份、信誉、防投毒）、隐私层、治理模型，其中"开放问题"部分明确欢迎社区输入；
• docs/architecture.md：知识流转、分级晋升（本地 → 组织 → 全球 Commons）、审查关卡的详细设计。

3. 治理规则本身

知识单元的许可、溯源、审查职责在 CONTRIBUTOR_AGREEMENT.md 中仍在演进（当前标注为 Draft）——对"Agent 生成的知识归谁所有、如何溯源"这类问题的讨论，正是标准制定最稀缺的参与。

参与路径建议：先读提案中的开放问题 → 在相关 Issue 下给出你的场景和观点 → 用代码或文档 PR 落地一个小改进。标准类项目欢迎"带着场景来"的贡献者。

⚠️ 三个别踩的雷区

另外注意：项目处于 0.x 探索期，数据库格式和 SDK 接口可能出现破坏性变更（官方会尽量提供迁移脚本，参考 server/scripts/migrate-v1.sh），提交依赖相关的 PR 前先看 Issue 讨论。

📌 一图流速查

从修一个文档错别字（docs/分支），到给知识单元 Schema 提出一条字段建议——每一步都是参与这个开放标准的方式。现在就打开 CONTRIBUTING.md，认领你的第一个 Issue 吧。