mirror of
https://fastgit.cc/github.com/HKUDS/CLI-Anything
synced 2026-04-22 05:41:33 +08:00
130 lines
4.5 KiB
Markdown
130 lines
4.5 KiB
Markdown
# Contributing to CLI-Anything
|
|
|
|
Thank you for your interest in contributing to CLI-Anything! This guide will help you get started.
|
|
|
|
## Types of Contributions
|
|
|
|
We welcome three main categories of contributions:
|
|
|
|
### A) CLIs for New Software
|
|
|
|
Adding a new CLI harness is the most impactful contribution. Before submitting a PR, ensure the following are in place:
|
|
|
|
1. **`<SOFTWARE>.md`** — the SOP document exists at `<software>/agent-harness/<SOFTWARE>.md` describing the harness architecture.
|
|
2. **`SKILL.md`** — the AI-discoverable skill definition exists inside the Python package at `cli_anything/<software>/SKILL.md`.
|
|
3. **Tests** — unit tests (`test_core.py`, passable without backend) and E2E tests (`test_full_e2e.py`) are present and passing.
|
|
4. **`README.md`** — the project README includes the new software with a link to its harness directory.
|
|
5. **`registry.json`** — add an entry for the new software so it appears on the [CLI-Hub](https://hkuds.github.io/CLI-Anything/hub/).
|
|
6. **`repl_skin.py`** — an unmodified copy from the plugin exists in `utils/`.
|
|
|
|
### B) New Features
|
|
|
|
Feature contributions improve existing harnesses or the plugin framework. Examples include new CLI commands, output formats, backend improvements, or cross-platform fixes.
|
|
|
|
- Open an issue first to discuss the feature before starting work.
|
|
- Follow existing code patterns and conventions in the target harness.
|
|
- Include tests for any new functionality.
|
|
|
|
### C) Bug Fixes
|
|
|
|
Bug fixes resolve incorrect behavior in existing harnesses or the plugin.
|
|
|
|
- Reference the related issue in your PR (e.g., `Fixes #123`).
|
|
- Include a test that reproduces the bug and verifies the fix.
|
|
- Ensure all existing tests for the affected harness still pass.
|
|
|
|
## CLI-Hub & Registry
|
|
|
|
All available CLIs are listed in `registry.json` at the repo root and displayed on the [CLI-Hub](https://hkuds.github.io/CLI-Anything/hub/). The hub reads `registry.json` directly from `main`, so it updates immediately when a PR is merged.
|
|
|
|
### Adding a new CLI to the Hub
|
|
|
|
Include an entry in `registry.json` as part of your PR. Each entry has this shape:
|
|
|
|
```json
|
|
{
|
|
"name": "my-software",
|
|
"display_name": "My Software",
|
|
"version": "1.0.0",
|
|
"description": "Short description of what the CLI does",
|
|
"requires": "backend software or null",
|
|
"install_cmd": "pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=my-software/agent-harness",
|
|
"entry_point": "cli-anything-my-software",
|
|
"skill_md": "my-software/agent-harness/cli_anything/my_software/skills/SKILL.md",
|
|
"category": "category-name"
|
|
}
|
|
```
|
|
|
|
### Updating an existing CLI on the Hub
|
|
|
|
When you modify an existing harness, update its `registry.json` entry in the same PR:
|
|
|
|
- Bump the `version` field to reflect the change.
|
|
- Update `description`, `requires`, or `category` if they changed.
|
|
- The hub will reflect the update as soon as the PR is merged to `main`.
|
|
|
|
## Development Setup
|
|
|
|
Each generated CLI lives in `<software>/agent-harness/` and is an independent Python package:
|
|
|
|
```bash
|
|
# Clone the repo
|
|
git clone https://github.com/HKUDS/CLI-Anything.git
|
|
cd CLI-Anything
|
|
|
|
# Install a harness in editable mode
|
|
cd <software>/agent-harness
|
|
pip install -e .
|
|
|
|
# Run tests
|
|
python3 -m pytest cli_anything/<software>/tests/ -v
|
|
```
|
|
|
|
### Requirements
|
|
|
|
- Python 3.10+
|
|
- Click 8.0+
|
|
- pytest 7.0+
|
|
|
|
## Code Style
|
|
|
|
- Follow PEP 8 conventions.
|
|
- Use type hints where practical.
|
|
- All CLI commands must support the `--json` flag for machine-readable output.
|
|
|
|
## Commit Messages
|
|
|
|
Use clear, descriptive commit messages following the conventional format:
|
|
|
|
```
|
|
feat: add Krita CLI harness
|
|
fix: resolve Blender backend path on macOS
|
|
docs: update README with new software entry
|
|
test: add unit tests for Inkscape layer commands
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
# Unit tests (no backend software needed)
|
|
python3 -m pytest cli_anything/<software>/tests/test_core.py -v
|
|
|
|
# E2E tests (requires real backend installed)
|
|
python3 -m pytest cli_anything/<software>/tests/test_full_e2e.py -v
|
|
|
|
# All tests for a harness
|
|
python3 -m pytest cli_anything/<software>/tests/ -v
|
|
```
|
|
|
|
## Submitting a Pull Request
|
|
|
|
1. Fork the repository and create a feature branch from `main`.
|
|
2. Make your changes following the guidelines above.
|
|
3. Ensure all tests pass for any harnesses you modified.
|
|
4. Push your branch and open a Pull Request against `main`.
|
|
5. Fill out the PR template completely.
|
|
|
|
## Questions?
|
|
|
|
If you have questions, feel free to open a [Discussion](https://github.com/HKUDS/CLI-Anything/discussions) or an issue tagged with `type: question`.
|