|
| 1 | +# Contributing to AgentHub |
| 2 | + |
| 3 | +## Getting Started |
| 4 | + |
| 5 | +1. Clone and checkout the development branch: |
| 6 | + ```powershell |
| 7 | + git clone <repo-url> |
| 8 | + cd AgentHub |
| 9 | + git checkout dev/delicious233 |
| 10 | + ``` |
| 11 | + |
| 12 | +2. Run setup to enable git hooks and verify tooling: |
| 13 | + ```powershell |
| 14 | + # Windows |
| 15 | + .\scripts\setup.ps1 |
| 16 | +
|
| 17 | + # macOS / Linux |
| 18 | + ./scripts/setup.sh |
| 19 | + ``` |
| 20 | + |
| 21 | +3. Read `AGENTS.md` for project conventions, architecture boundaries, and agent workflow rules. |
| 22 | + |
| 23 | +## Development Flow |
| 24 | + |
| 25 | +- Always branch from `dev/delicious233` (master is lagging behind). |
| 26 | +- Sync before starting: |
| 27 | + ```powershell |
| 28 | + git checkout dev/delicious233 |
| 29 | + git pull --ff-only |
| 30 | + ``` |
| 31 | +- Branch naming: `feat/xxx`, `fix/xxx`, `docs/xxx`, `refactor/xxx` |
| 32 | +- Commit format: |
| 33 | + ``` |
| 34 | + type(scope): 中文摘要 |
| 35 | + ``` |
| 36 | + Types: `init|feat|fix|docs|refactor|chore|test|perf|ci|revert` |
| 37 | +- PR to `dev/delicious233`, not master directly. |
| 38 | +- Keep PRs small and focused. Rebase onto latest `dev/delicious233` before opening a PR. |
| 39 | +- Push frequently -- do not leave uncommitted changes across days. |
| 40 | + |
| 41 | +## Testing |
| 42 | + |
| 43 | +| Layer | Command | |
| 44 | +|-------|---------| |
| 45 | +| Edge Server | `cd edge-server && go test ./... -short -count=1` | |
| 46 | +| Hub Server | `cd hub-server && go test ./... -short -count=1` | |
| 47 | +| Desktop (unit) | `cd app/desktop && pnpm test` | |
| 48 | +| Desktop (typecheck) | `cd app/desktop && pnpm typecheck` | |
| 49 | +| Web (build) | `cd app/web && pnpm build` | |
| 50 | +| Web (typecheck) | `cd app/web && corepack.cmd pnpm typecheck` (Windows) | |
| 51 | + |
| 52 | +For Edge changes, also run: |
| 53 | +```powershell |
| 54 | +.\scripts\verify-runtime-readiness.ps1 |
| 55 | +``` |
| 56 | + |
| 57 | +For security-sensitive changes, run: |
| 58 | +```powershell |
| 59 | +..\scripts\verify-security-risks.ps1 -StrictReleaseGate |
| 60 | +``` |
| 61 | + |
| 62 | +## Code Style |
| 63 | + |
| 64 | +| Language | Tool | |
| 65 | +|----------|------| |
| 66 | +| Go | Standard `gofmt` formatting | |
| 67 | +| TypeScript | Prettier + ESLint (`pnpm lint`) | |
| 68 | +| Styles | CSS Modules + OKLCH design tokens (`var(--primary)`, `var(--border)`) | |
| 69 | + |
| 70 | +- Documentation and commit messages in Chinese; code identifiers, paths, API fields, and CLI commands in English. |
| 71 | +- Use `@shared/ui` for all reusable components -- do not create duplicate local UI copies in desktop or web. |
| 72 | +- Run `git diff --check` before committing to catch whitespace errors. |
| 73 | + |
| 74 | +## Project Structure |
| 75 | + |
| 76 | +| Directory | Purpose | |
| 77 | +|-----------|---------| |
| 78 | +| `app/desktop/` | Tauri desktop app (port 5173) | |
| 79 | +| `app/mobile/` | Tauri mobile app (port 5174) | |
| 80 | +| `app/web/` | Web workbench (port 5175 reserved) | |
| 81 | +| `app/shared/` | Shared UI, types, API client (`@agenthub/shared`) | |
| 82 | +| `hub-server/` | Hub: accounts, IM, sync, relay (port 8090) | |
| 83 | +| `edge-server/` | Edge: execution node, runtime adapters (port 3210) | |
| 84 | +| `api/` | REST OpenAPI spec + WebSocket event contract | |
| 85 | +| `docs/` | Architecture, governance, operations, roadmap | |
| 86 | +| `scripts/` | Setup, dev start/stop, verification scripts | |
| 87 | + |
| 88 | +Desktop and Mobile are independent Tauri projects. Do not modify each other's `tauri.conf.json`, `Cargo.toml`, or `lib.rs`. |
| 89 | + |
| 90 | +## Security |
| 91 | + |
| 92 | +- Never commit `.env`, API keys, tokens, cookies, private keys, certificates, SSH configs, or production database connection strings. |
| 93 | +- Use `.env.example` as a template with placeholder values. |
| 94 | +- Server aliases (hk1, hk2, us1, gz1) must not appear in repository files. |
| 95 | +- Production secrets live in `.env.production` (already in `.gitignore`). |
| 96 | +- Check diff output for sensitive data before pushing. |
| 97 | +- If you accidentally commit secrets, stop pushing immediately, notify the maintainer, rotate keys, then clean up git history. |
| 98 | +- Report security issues privately -- do not file public issues. |
| 99 | + |
| 100 | +## Architecture Boundaries |
| 101 | + |
| 102 | +- **Agent Runtime** (what runs): Claude Code, Codex, OpenCode CLI/SDK adapters in `edge-server/internal/adapters/` |
| 103 | +- **Agent Profile** (who acts): User-managed agent entities combining Runtime + Model + Skill + MCP + approval policy |
| 104 | +- **Agent Configuration**: Rules, memory, context, chat history, working directory |
| 105 | +- **Execution Target** (where it runs): Local Edge, Remote Edge, Cloud Edge, Hub Relay |
| 106 | + |
| 107 | +Local execution does not require Hub. Hub enters the path for accounts, cloud IM, multi-device sync, remote viewing/approval, device routing, and relay. |
| 108 | + |
| 109 | +## Documentation |
| 110 | + |
| 111 | +- Three primary docs: product requirements, system architecture, implementation guide |
| 112 | +- Reference and research go in `docs/reference/`; historical proposals in `docs/archive/` |
| 113 | +- Before modifying APIs, read `api/README.md`, `api/openapi.yaml`, `api/events.md` |
| 114 | +- Before auth/i18n/Feishu changes, read the corresponding docs under `../docs/` (TokenDance workspace level) |
0 commit comments