如何成为mercury-agent贡献者：必须掌握的8条核心原则与完整代码规范指南

【免费下载链接】mercury-agentSoul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.项目地址: https://gitcode.com/gh_mirrors/me/mercury-agent

mercury-agent 是一款 soul-driven AI agent（灵魂驱动的 AI 智能体），内置权限加固工具、token 预算与多通道接入，可 7×24 小时从 CLI、Telegram 等渠道运行。本指南面向第一次想给 mercury-agent 提 PR 的贡献者，用 8 条核心原则 + 完整代码规范，帮你从环境搭建到提交代码一次通过。

一、先了解贡献目标：mercury-agent 的核心定位

在动手写代码之前，先花 5 分钟理解这个项目"是什么"，能避免方向性错误：

• 权限加固（permission-hardened）：所有工具调用都经过权限管理器，安全边界优先于功能便利
• token 预算：内置 token 消耗控制与省 token 机制
• 多通道接入：CLI、Telegram、Discord、Slack、Signal 等渠道共享同一套能力层
• 技术栈：TypeScript（严格模式）+ Node.js ≥ 20，前端用 React/Ink 渲染终端界面

📖 三份文档值得先读：

• README.zh-CN.md：项目全貌与功能清单
• ARCHITECTURE.zh-CN.md：架构设计与模块职责
• DECISIONS.md：关键技术决策记录，理解"为什么这样做"

二、快速上手：3 步配好贡献环境

步骤 1：克隆仓库

git clone https://gitcode.com/gh_mirrors/me/mercury-agent cd mercury-agent

步骤 2：安装依赖

项目要求Node.js ≥ 20（见 package.json 的engines字段），推荐使用 20 或 22 版本：

npm ci

步骤 3：验证本地能跑通

npm run typecheck # 类型检查 npm test # 运行全部 vitest 测试

两条命令都绿，说明环境就绪。常用脚本定义在 package.json 中，typecheck和test是每次改动后的必跑命令。

💡 提示：npm run build会产出dist/构建产物，涉及打包或原生依赖（如可选的 better-sqlite3）的改动务必本地构建验证一次。

三、mercury-agent 贡献者必知的 8 条核心原则

原则 1：严格 TypeScript，类型即契约

tsconfig.json 中开启了"strict": true，这意味着：不允许隐式any、必须处理空值、函数返回类型要可推断。你的改动如果导致npm run typecheck失败，PR 无法合并——提交前永远先跑一遍类型检查。

原则 2：ESM 导入必须带.js扩展名

项目使用 ES2022 模块（tsconfig.json），相对导入即使是.ts源文件也必须写.js后缀。看这个真实例子：

src/utils/platform.test.ts 中import { isTermux, resolveShell } from './platform.js';

这是新手最常见的 PR 被拒原因之一。

原则 3：测试与源码同目录（co-located）

vitest 测试文件命名为xxx.test.ts，直接放在被测文件旁边，例如 src/core/completion-verdict.test.ts 紧邻completion-verdict.ts。改动逻辑就补测试，用describe/it/expect组织，可参考 src/utils/platform.test.ts 这种清晰的"正向 + 反向"断言写法。

原则 4：权限优先，安全边界先于功能

mercury-agent 的立身之本是权限加固。任何新增或修改工具的能力，都要先想清楚：它是否经过PermissionManager审批？是否会绕过命令黑名单？相关文件：

• src/capabilities/permissions.ts：权限管理器核心
• src/capabilities/shell/blocklist.ts：命令黑白名单
• src/utils/ssrf.ts 与 src/utils/redact.ts：网络请求防护与敏感信息脱敏

在安全边界上"图省事"的改动，是这个项目最不能接受的。

原则 5：遵循工具工厂模式（createXxxTool）

每个 AI 可调用工具都以createXxxTool工厂函数形式导出，内部使用tool()+ zod schema 定义输入。典型范例：

src/capabilities/skills/use-skill.ts：createUseSkillTool通过zodSchema(z.object({...}))声明入参

新增工具后，记得在 src/capabilities/index.ts 统一导出，保持能力注册表完整。

原则 6：让改动在 CI 的 4 道关卡全部通过

.github/workflows/ci.yml 定义了 4 个任务，你的 PR 会全部经历：

📌 重点：跨平台兼容是硬要求。涉及文件路径、shell 命令的代码，要同时考虑 Windows 与 Termux（Linux 风格）环境，参考 src/utils/platform.ts 的写法。

原则 7：文档中英双同步

项目所有文档均维护双版本。你改了行为，就要同步更新：

• README.zh-CN.md / README.md
• CHANGELOG.zh-CN.md / CHANGELOG.md

只改英文不改中文（或反之）的 PR，会在评审中被要求补齐。

原则 8：每个新增环境变量都要登记

配置项统一以.env变量形式暴露，新增或修改环境变量时，必须同步更新 .env.example 模板文件并附注释说明，否则用户无法感知新配置的存在。

四、提交前自检：PR 五步检查清单

✅ 1.npm run typecheck通过 ✅ 2.npm test全绿，新增逻辑有对应测试 ✅ 3.npm run build构建成功（涉及打包/依赖的改动必查） ✅ 4. 文档双版本（中英文）已同步 ✅ 5. 没有把密钥、token 写进代码或日志（可参考 src/utils/redact.ts 的脱敏思路）

五、新手常见问题 FAQ

Q1：从哪类 issue 开始最合适？建议从小而完整的功能入手：补齐缺失测试、文档勘误、小 bug 修复。先读 DECISIONS.md 理解既有设计意图，再动手。

Q2：本地测试通过但 CI 挂了？多半是跨平台问题。对照 ci.yml 的矩阵（Windows / macOS / Termux），检查路径分隔符、shell 语法等差异。

Q3：需要安装原生依赖吗？better-sqlite3是可选依赖，有 sql.js 作为纯 JS 兜底，普通贡献无需强制安装。

Q4：构建产物在哪里？由 tsup.config.ts 驱动打包，npm run build后产出dist/index.js即mercury命令入口。

🎯小结：mercury-agent 的代码规范可以浓缩为一句话——严格类型、权限优先、测试随行、文档同步。把这 8 条原则内化，你的第一个贡献 PR 就能顺利通过 CI 的四道关卡。现在，去 README.zh-CN.md 里找一个感兴趣的模块，开始你的第一个 PR 吧！

【免费下载链接】mercury-agentSoul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.项目地址: https://gitcode.com/gh_mirrors/me/mercury-agent