如何成为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-agentmercury-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 无法合并——提交前永远先跑一遍类型检查。原则 2ESM 导入必须带.js扩展名项目使用 ES2022 模块tsconfig.json相对导入即使是.ts源文件也必须写.js后缀。看这个真实例子src/utils/platform.test.ts 中import { isTermux, resolveShell } from ./platform.js;这是新手最常见的 PR 被拒原因之一。原则 3测试与源码同目录co-locatedvitest 测试文件命名为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.tscreateUseSkillTool通过zodSchema(z.object({...}))声明入参新增工具后记得在 src/capabilities/index.ts 统一导出保持能力注册表完整。原则 6让改动在 CI 的 4 道关卡全部通过.github/workflows/ci.yml 定义了 4 个任务你的 PR 会全部经历CI 任务检查内容typecheckNode 20/22 × Ubuntu/Windows/macOS 矩阵类型检查test构建 全量 vitest 测试pack-verifynpm 打包完整性scripts/verify-package.cjstermuxAndroid Termux 环境构建验证 重点跨平台兼容是硬要求。涉及文件路径、shell 命令的代码要同时考虑 Windows 与 TermuxLinux 风格环境参考 src/utils/platform.ts 的写法。原则 7文档中英双同步项目所有文档均维护双版本。你改了行为就要同步更新README.zh-CN.md / README.mdCHANGELOG.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 的脱敏思路五、新手常见问题 FAQQ1从哪类 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何成为mercury-agent贡献者：必须掌握的8条核心原则与完整代码规范指南
如何成为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-agentmercury-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 无法合并——提交前永远先跑一遍类型检查。原则 2ESM 导入必须带.js扩展名项目使用 ES2022 模块tsconfig.json相对导入即使是.ts源文件也必须写.js后缀。看这个真实例子src/utils/platform.test.ts 中import { isTermux, resolveShell } from ./platform.js;这是新手最常见的 PR 被拒原因之一。原则 3测试与源码同目录co-locatedvitest 测试文件命名为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.tscreateUseSkillTool通过zodSchema(z.object({...}))声明入参新增工具后记得在 src/capabilities/index.ts 统一导出保持能力注册表完整。原则 6让改动在 CI 的 4 道关卡全部通过.github/workflows/ci.yml 定义了 4 个任务你的 PR 会全部经历CI 任务检查内容typecheckNode 20/22 × Ubuntu/Windows/macOS 矩阵类型检查test构建 全量 vitest 测试pack-verifynpm 打包完整性scripts/verify-package.cjstermuxAndroid Termux 环境构建验证 重点跨平台兼容是硬要求。涉及文件路径、shell 命令的代码要同时考虑 Windows 与 TermuxLinux 风格环境参考 src/utils/platform.ts 的写法。原则 7文档中英双同步项目所有文档均维护双版本。你改了行为就要同步更新README.zh-CN.md / README.mdCHANGELOG.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 的脱敏思路五、新手常见问题 FAQQ1从哪类 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
