贡献指南

欢迎贡献！本指南说清楚怎么加新组件 / 怎么改老组件 / 怎么确保不被上游变更打破。

设计原则（务必先读）

零外部依赖（核心包）：trace-context / permission-policy-engine / project-container 三个核心包只依赖 Node 内置 API。新组件如果需要外部依赖，请先讨论。
adapter 装饰器不 patch 内核：新增组件不应该 monkey-patch MyAgents Runtime，而要通过 withPolicyEngine / withNewTrace 这类装饰器接入。
数据带 version: "1.0"：每个持久化文件（config.json / ndjson）必须有版本字段，schema 升级走 migration。
fail-closed 默认行为：policy / auth 类组件默认 deny / ask，不要默认 allow。
审计独立：每个写入操作走 ndjson 落盘，且审计文件独立于业务数据目录（业务数据损坏也能查历史）。
损坏行静默跳过：reader 不能因为一行坏掉就 throw。

加一个新组件的步骤

以 "Logging 组件" 为例。

1. 创建 package

mkdir -p packages/logging-component/{src,tests}

2. 写 `package.json`

{
  "name": "@yourname/logging-component",
  "version": "0.1.0",
  "type": "module",
  "license": "AGPL-3.0",
  "engines": { "node": ">=22" }
}

3. 写 `src/log-core.ts`

导出 纯函数 + 类型（不要导类，避免单例污染）
依赖 Node 内置 API 即可
入口文件用 .ts 后缀（用 --experimental-strip-types 跑测试）

4. 写 `tests/log.test.ts`

最少 8 个测试覆盖：

happy path（2 个）
边界（empty / max / min）
错误（invalid input / file not found / permission denied）
性能 / 大数据（防爆）
损坏行处理
跨包 / 版本升级兼容

5. 写 OpenClaw 插件（如适用）

在 packages/openclaw-plugins/openclaw-plugin-{name}/ 写：

import type { OpenClawPluginApi } from "openclaw/plugin-sdk";

const plugin = {
  id: "{name}",
  name: "{Name}",
  register(api: OpenClawPluginApi) {
    api.registerCli(({ program }) => {
      program.command("myagents-{name}").action(...);
    });
  },
};

export default plugin;

加上 openclaw.plugin.json：

{
  "id": "{name}",
  "name": "{Name}",
  "version": "0.1.0",
  "main": "./index.ts"
}

6. 在 `packages/cc-plugin/src/integration-hooks.ts` 加挂载函数

参考现有 mountPermissionPolicy / mountProjectContainer 模式：

export async function mountLogging(api: OpenClawPluginApi, cfg: PluginConfig) {
  // 独立 try-catch，失败不阻塞其他组件
  const instance = new LoggingCore({ logDir: cfg.log_dir });
  (api as any).logging = instance;
}

7. 在 `packages/cc-plugin/src/index.ts` 注册

mountLogging(api, cfg).catch(err =>
  console.warn("[myagents-components] Logging mount failed:", err)
);

8. 加跨包集成测试

在 tests/integration.test.ts 加新场景，验证你的组件和其它组件协同工作。

9. 更新 README + CHANGELOG

在 ROOT README.md 测试矩阵加一行
在 CHANGELOG.md 加 unreleased 条目

10. 跑全测

npm test

确保所有测试通过。

代码风格

TypeScript with --experimental-strip-types
用 ESM（"type": "module"），不用 CommonJS
用 node:test 写测试，不用 jest / vitest
优先用 Node 内置 API（fs/path/crypto），不引入 lodash / axios
中文注释 OK，用户可见的 CLI 输出必须是英文

提交前清单

所有测试通过（npm test）
新组件带 version: "1.0" 字段
失败有优雅降级（不 throw）
没有引入新的 npm 依赖（核心包）
OpenClaw 插件有 openclaw.plugin.json manifest
跨包集成测试覆盖新场景
ROOT README + CHANGELOG 已更新

提 PR 的格式

Title: feat: 加 XX 组件（短描述）

## Why
背景 / 解决什么 issue / 动机

## What
新增什么 / 改了什么

## 测试
- 新增 X 个单测
- 新增 Y 个集成场景
- npm test 跑通截图

## 抗"全丢"特性
- 数据带 version
- 失败降级
- 审计独立

Closes #NNN

联系方式

有问题在 GitHub Issues 开 issue，或者直接看 knowledge/ 目录下的设计文档。

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History