close
OpenClaw Internals
  • 中文

      • OpenClaw 中的 PR 和提交约定

      本文档基于存储库分析,记录了关于 OpenClaw git 工作流程、PR 模板和 pre-commit 钩子的观察。这些约定确保 PR 可审查、安全且文档记录正确。

      提交格式: Conventional Commits

      OpenClaw 使用带有作用域的 Conventional Commits。

      格式

      <type>(<scope>): <description>

[optional body]

[optional footer]

      常见类型

      • fix - 错误修复
      • feat - 新功能
      • refactor - 代码重构(无行为变化)
      • docs - 文档更改
      • test - 测试添加或修复
      • chore - 构建、CI 或工具更改
      • perf - 性能改进
      • security - 安全修复

      常见作用域

      基于 git 历史分析:

      • 平台集成: android, ios, macos, telegram, slack, discord
      • 核心系统: gateway, agents, config, skills, sandbox, memory
      • UI: ui, control-ui
      • 基础设施: ci, cd, build, deps
      • 安全: security, auth, secrets

      示例

      fix(gateway): prevent duplicate tenant ID registration
feat(telegram): add support for inline keyboards
refactor(skills): extract skill validation into separate module
docs(contributing): clarify pre-commit hook installation
security(auth): redact API keys in error messages

      PR 模板要求

      PR 模板位于 .github/pull_request_template.md 中,需要特定部分。

      必需部分

      1. 摘要(2-5 个要点)

      解释:

      • 问题: 此 PR 解决的问题
      • 为什么: 为什么需要此更改
      • 更改内容: 更改的高级描述
      • 范围边界: 范围内与范围外的内容

      示例:

      ## Summary

- Problem: 当租户 ID 包含特殊字符时网关崩溃
- Why: 当前验证正则表达式不处理 URL 编码字符
- What changed: 更新验证以支持 RFC 3986 百分比编码
- Scope: 仅影响租户 ID 验证;其他 ID 类型不变

      2. 更改类型(复选框)

      ## Change Type

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Refactoring (code change that neither fixes a bug nor adds a feature)
- [ ] Documentation update
- [ ] Security fix
- [ ] Chore (build, CI, or tooling changes)

      3. 作用域(复选框)

      ## Scope

- [x] Gateway
- [ ] Skills
- [ ] Auth/Security
- [ ] Memory
- [ ] Integrations (Telegram, Slack, Discord, etc.)
- [ ] API
- [ ] UI (Control UI)
- [ ] CI/CD
- [ ] Other: _____

      4. 安全影响(必需)

      关键部分 - 每个 PR 都必须完成。

      ## Security Impact

- [ ] Changes file system permissions or access
- [ ] Handles secrets, API keys, or credentials
- [ ] Makes network requests or opens connections
- [ ] Executes shell commands or spawns processes
- [ ] None of the above

**Details**: [Explain any security considerations]

      5. 重现 + 验证

      ## Repro + Verification

**Environment:**
- OS: macOS 14.2
- Node: v20.10.0
- OpenClaw version: 2026.2.23

**Steps to reproduce (before fix):**
1. 使用 ID `test%20tenant` 创建租户
2. 尝试注册租户
3. 网关因验证错误崩溃

**Expected behavior:** 租户成功注册

**Actual behavior (after fix):** 租户成功注册

      6. 证据

      ## Evidence

- [x] Tests pass locally
- [x] Added unit tests for percent-encoding validation
- [x] Manual verification with encoded IDs
- [ ] Performance benchmarks (if applicable)
- [ ] Screenshots (if UI change)

      7. 人工验证(必需)

      关键部分 - 解释您亲自验证的内容。

      ## Human Verification

**What I verified:**
- 使用各种百分比编码字符创建租户(%, /, ?, #)
- 使用编码的租户 ID 验证网关启动
- 测试无效编码的错误消息

**Edge cases tested:**
- 双重编码字符(%2520)
- 无效的百分比序列(%ZZ)
- 编码形式的 Unicode 字符

**What I did NOT verify:**
- 使用非 UTF-8 编码的行为(超出范围)
- 与旧租户 ID 的交互(单独测试)

      8. 兼容性/迁移

      ## Compatibility/Migration

- Backward compatible: Yes
- Breaking changes: No
- Migration required: No

**Notes**: 没有编码的现有租户 ID 继续工作。

      9. 故障恢复

      ## Failure Recovery

**How to disable/revert this change:**
1. 还原提交或禁用功能标志(如适用)
2. 重启网关

**Symptoms of failure:**
- 网关启动失败并显示验证错误
- 租户注册失败并显示 400 错误
- 日志显示"Invalid tenant ID format"消息

**Rollback plan**: 还原到 `src/gateway/validator.ts` 中的先前验证正则表达式

      Pre-Commit 钩子

      Pre-commit 钩子在 .pre-commit-config.yaml 中配置,并通过 prek install 安装。

      安装

      prek install

      注意: OpenClaw 使用 prek(而非标准的 pre-commit)。

      钩子管道

      钩子按以下顺序运行:

      1. 基本检查

      • 尾随空格删除
      • 文件末尾修复程序
      • 合并冲突检测

      2. 密钥检测

      • detect-secrets 带基线(.secrets.baseline)
      • 防止意外提交 API 密钥、令牌或密码

      3. Shell Linting

      • shellcheck 用于 shell 脚本
      • 强制执行 shell 脚本最佳实践

      4. GitHub Actions Linting

      • actionlint 用于工作流语法
      • zizmor 用于 Actions 中的安全问题

      5. Python 检查(用于技能)

      • ruff 用于 linting 和格式化
      • pytest 用于 Python 技能测试

      6. 依赖审计

      • pnpm audit 用于生产依赖项
      • 高严重性漏洞会失败

      7. TypeScript Linting 和格式化

      • oxlint(不是 ESLint)
      • oxfmt(不是 Prettier)

      8. Swift 检查(用于 macOS/iOS)

      • swiftlint 用于 Swift linting
      • swiftformat 用于 Swift 格式化

      绕过钩子(不推荐)

      git commit --no-verify

      警告: 仅在有特定原因并了解风险时绕过钩子。

      Changelog 约定

      Changelog 更新位于存储库根目录的 CHANGELOG.md 中。

      格式

      ## [Version] - YYYY-MM-DD

### Changes

- feat(scope): Description (thanks @username)
- feat(scope): Description

### Fixes

- fix(scope): Description (thanks @username)
- fix(scope): Description

      指南

      • 仅面向用户 - 不要包含内部重构,除非它们影响用户
      • 感谢贡献者 - 对外部贡献使用 (thanks @username)
      • 按类型分组 - "Changes"用于功能,"Fixes"用于错误修复
      • 使用 conventional commit 格式 - 与提交消息相同的格式

      示例

      ## [2026.2.23] - 2026-02-24

### Changes

- feat(telegram): add inline keyboard support (thanks @contributor)
- feat(gateway): support percent-encoded tenant IDs

### Fixes

- fix(skills): prevent timeout on slow skill execution
- fix(ui): correct theme toggle state persistence (thanks @ui-expert)

      Git 工作流程摘要

      为什么这很重要

      遵循这些约定可确保:

      1. 可审查性 - PR 包含审查者所需的所有必要上下文
      2. 安全性 - Pre-commit 钩子捕获密钥和安全问题
      3. 一致性 - Conventional commits 使历史记录可搜索
      4. 文档 - Changelog 准确反映面向用户的更改
      5. CI 可靠性 - Pre-commit 钩子在 CI 运行之前捕获问题

      交叉引用

      • 代码风格约定: Pre-commit 钩子强制执行的 Oxlint 和 Oxfmt 规则
      • 测试模式: PR 的测试要求
      • 构建失败故障排除 (planned): CI 失败的解决方案