HHostingByteSoftware
Ctrl K
ComunidadGuías…

CONTRIBUTING.zh-CN.md

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
# 贡献 kageos

感谢你愿意改进 kageos。本仓库源码公开，当前采用 Business Source License 1.1，并在各版本发布三年后转为 Apache-2.0。贡献前请阅读 [LICENSE](LICENSE) 和 [LICENSE_FAQ.md](LICENSE_FAQ.md)，确认你理解当前授权范围和转换机制。

## 开始之前

- 较大的功能、架构调整或产品方向变化，请先和维护者讨论。
- 保持 PR 聚焦。不要把重构、格式化、依赖升级和产品行为变化混在一个 PR 中。
- 不要提交真实密钥、客户数据、生成的生产文件、license、`namespace/`、`local/` 或运行时数据目录。
- 对外描述请遵循 [源码与授权对外口径](docs/source-available-messaging.md)，统一使用“源码公开、可自托管”。

## 贡献流程

1. Fork 仓库，并从最新 `main` 创建分支。
2. 按本文的本地开发流程启动 kageos。
3. 进行小而清晰的修改。
4. 为 bug fix 或新功能补充测试，或在 PR 中说明验证方式。
5. 行为、部署、公开定位有变化时同步更新 README 或 docs。
6. 提交 Pull Request，并说明改了什么、为什么改、如何验证。

所有代码修改都应通过 Pull Request 合并。PR 需要通过 CI，并由维护者审核后合并。

## 贡献者许可协议

Pull Request 合并前，作者必须阅读并接受 [kageos 贡献者许可协议](CONTRIBUTOR_LICENSE_AGREEMENT.zh-CN.md)。同时提供[英文版本](CONTRIBUTOR_LICENSE_AGREEMENT.md)供国际贡献者阅读。

贡献者通过勾选 Pull Request 模板中的 CLA 确认项接受协议，该确认同时适用于接受前后提交的贡献。如果贡献的权利属于雇主或其他组织，贡献者必须有权授予 CLA 中约定的权利；维护者可以要求贡献者另行提供企业授权证明。

## 分支模型

从 `main` 拉分支，推荐命名：

```text
feat/short-feature-name
fix/short-bug-name
docs/short-doc-change
chore/short-maintenance-change
```

提交 PR 前请同步最新 `main`，解决冲突，并确认没有提交本地运行时文件或私有数据。

## Commit 规范

推荐使用 Conventional Commits：

```text
feat: add scheduled agent notification tool
fix: prevent incomplete tool messages after interruption
docs: update production deployment guide
test: cover service tree bundle import
chore: refresh generated API docs
```

常用类型包括 `feat`、`fix`、`docs`、`refactor`、`test`、`chore`、`ci`。提交说明请尽量清晰，说明用户可见行为或维护目的。

## 本地开发

使用 `kagectl` 作为本地开发入口。仓库中仍保留底层 Compose 文件，但新贡献者不需要直接记住历史路径或手工配置环境变量。

只读运行可直接克隆上游仓库；准备提交 PR 时请先 fork：

```bash
git clone https://github.com/kageos/kageos.git
cd kageos
```

最短路径是运行仓库脚本，它会同时启动基础设施、后端和前端：

```bash
./scripts/dev.sh
```

需要分别调试时，再单独启动本地后端：

```bash
go run ./cmd/kagectl bootstrap --dev
```

这个命令会初始化本地 dev 工作区、启动 MySQL / NATS / MinIO、确保本地 user-app base image 存在，并以前台方式运行后端。默认优先使用 Podman；如果想用 Docker：

```bash
go run ./cmd/kagectl bootstrap --dev --engine docker
```

停止后端可按 `Ctrl-C`。停止本地基础设施：

```bash
go run ./cmd/kagectl down
```

另开终端启动前端：

```bash
cd web
npm install
npm run dev
```

启动后访问 `http://localhost:5173`。`kagectl bootstrap --dev` 会打印 `kageos dev initialization summary`；使用用户名 `system` 和其中的 `Admin password` 登录。如果需要重新查看密码，可以执行 `go run ./cmd/kagectl init --dev`，或读取 `.kageos/dev/env/kageos.env` 中的 `SYSTEM_USER_PASSWORD`。

## 常用开发命令

```bash
go run ./cmd/kagectl status
go run ./cmd/kagectl doctor
go run ./cmd/kagectl verify
go run ./cmd/kagectl logs main
go run ./cmd/kagectl logs infra
go run ./cmd/kagectl down
```

## 维护 AI 套件

公共 `skills/` 目录是 Codex 和 Claude Code 使用的五个 kageos Skill 唯一
源码。社区对本地启动、源码导览、工作空间开发、真实验收或 Hub 发布流程的
改进，都应通过普通 Pull Request 提交到这里。

- 先修改 `skills/<skill-name>`，不要手工修改 `plugins/kageos/skills` 下的生成副本。
- 保持 `SKILL.md` 精简；重复且需要确定性的工作放进 `scripts/`，按需加载的详细说明放进 `references/`。
- 使用可用的通用 Skill 校验器检查每个变更，并实际运行配套脚本测试或代表性命令。
- 提交前运行 `python3 scripts/package-kageos-plugin.py`，同一个 PR 同时包含源 Skill 和生成的插件副本。
- 普通 Skill PR 不要自行修改插件版本；只有明确准备发布时才统一升级版本和更新日志。
- Skill、参考、示例和测试夹具中不得加入凭证、访问令牌、私有工作区内容、本地运行态或客户数据。

修改 `kageos-contributor` 时必须保留本地启动安全门禁：优先复用健康的
Docker/Podman 环境；安装系统软件前解释准确动作；未经检查和明确同意，不得
初始化、删除或重置已经存在的 Podman machine。

## 本地验证

按修改范围运行对应检查。

后端：

```bash
bash scripts/test-core-go.sh
```

前端：

```bash
cd web
npm ci
npm run check:architecture
npm run lint
npm run type-check
npm run test:unit -- --run
npm run build
```

仓库治理：

```bash
bash scripts/check-sensitive-files.sh
bash scripts/check-sdk-boundaries.sh
bash scripts/check-doc-links.sh
git diff --check
```

安全依赖检查：

```bash
cd web
npm audit --omit=dev
```

```bash
go run golang.org/x/vuln/cmd/govulncheck@latest ./cmd/... ./core/... ./dto/... ./pkg/...
```

## PR 清单

- 修改有清晰原因，范围尽量小。
- 用户可见行为有测试，或 PR 中解释了验证方式。
- 行为、部署或公开定位变化时同步更新文档。
- 新日志不泄露 secret、token、license key、客户数据或私有工作区路径。
- 新依赖确有必要、仍在维护，并且与项目授权模型兼容。

## 行为准则和安全问题

参与社区请遵守 [CODE_OF_CONDUCT.zh-CN.md](CODE_OF_CONDUCT.zh-CN.md)。安全漏洞请按 [SECURITY.zh-CN.md](SECURITY.zh-CN.md) 私下报告，不要发公开 issue。

提交贡献即表示你同意将贡献按本仓库当前授权条款发布，并接受对应版本未来按 [LICENSE](LICENSE) 中的 Change License 机制转换为 Apache License 2.0，同时受贡献者许可协议所授予附加权利的约束，除非你和维护者另有书面约定。