168 lines
6.1 KiB
Markdown
168 lines
6.1 KiB
Markdown
# Agent Harness
|
|
|
|
This harness improves discoverability, repeatability, and agent safety for the
|
|
existing Planet project. It does not replace current project rules, scripts, CI,
|
|
or release workflows.
|
|
|
|
## Authority And Conflicts
|
|
|
|
Existing project rules are authoritative:
|
|
|
|
1. `rules.md`
|
|
2. `agents.md`
|
|
3. Current implementation docs under `docs/technical/`
|
|
4. Existing scripts, especially `planet.sh`
|
|
5. Existing Gitea workflow files under `.gitea/workflows/`
|
|
|
|
When harness guidance conflicts with any of the above, keep the existing rule,
|
|
do not overwrite the existing workflow, and add a compatibility note here or in
|
|
`docs/harness-audit.md`.
|
|
|
|
## Starting Work
|
|
|
|
Recommended startup flow:
|
|
|
|
```bash
|
|
git status --short
|
|
scripts/harness/doctor.sh
|
|
```
|
|
|
|
Then read only the relevant implementation docs:
|
|
|
|
- Backend/API/data work: `docs/technical/zh/backend-*.md` and matching English
|
|
docs when public docs are affected.
|
|
- Frontend/admin work: `docs/technical/zh/frontend-admin-frontend-context.md`.
|
|
- Earth work: `docs/technical/zh/earth-frontend-context.md`,
|
|
`docs/technical/zh/earth-render-layer-order.md`, and style docs when visual
|
|
semantics change.
|
|
- Operations work: `docs/technical/zh/ops-runbook.md` and
|
|
`docs/technical/zh/ops-planet-sh-startup.md`.
|
|
- AI Provider work: `docs/technical/zh/agents-aiprovider.md`.
|
|
- Documentation work: `docs/documentation-coverage-rules.md`.
|
|
|
|
Use focused inspection commands before broad reads:
|
|
|
|
```bash
|
|
rg -n "<symbol-or-term>" <path>
|
|
git diff --stat HEAD
|
|
git diff --name-only HEAD
|
|
git diff --unified=0 HEAD -- <path>
|
|
```
|
|
|
|
## Existing Commands
|
|
|
|
| Purpose | Command |
|
|
| --- | --- |
|
|
| First setup | `./planet.sh init` |
|
|
| Start local stack | `./planet.sh start` |
|
|
| Start with LAN access | `./planet.sh start --allow-lan` |
|
|
| Restart all services | `./planet.sh restart` |
|
|
| Restart one area | `./planet.sh restart -b`, `-f`, `-a`, or `-d` |
|
|
| Health check | `./planet.sh health` |
|
|
| Logs | `./planet.sh log`, `./planet.sh log -b`, `-f`, `-a`, or `-m` |
|
|
| Create local user | `./planet.sh createuser` |
|
|
| Destructive local reset | `./planet.sh destroy` |
|
|
| Backend smoke tests | `cd backend && uv run --frozen --group dev --project .. python -m pytest -s tests/test_api.py tests/test_realtime_sources.py -q` |
|
|
| Frontend build | `cd frontend && bun install --frozen-lockfile && bun run build` |
|
|
| Mock AIS WebSocket | `bun run mock:ais-ws` |
|
|
|
|
## Harness Commands
|
|
|
|
| Tier | Command | What It Does |
|
|
| --- | --- | --- |
|
|
| Doctor | `scripts/harness/doctor.sh` | Checks required files, required tools, optional delivery tools, and forbidden frontend lockfiles. |
|
|
| Quick | `scripts/harness/quick-check.sh` | Runs doctor, whitespace diff check, shell syntax checks, and CI backend smoke tests. |
|
|
| Full | `scripts/harness/validate.sh` | Runs quick check, frontend Bun install/build, optional Helm checks, and opt-in Docker image smoke builds. |
|
|
|
|
Docker image smoke builds are expensive and are off by default:
|
|
|
|
```bash
|
|
PLANET_HARNESS_DOCKER_SMOKE=1 scripts/harness/validate.sh
|
|
```
|
|
|
|
## Environment Requirements
|
|
|
|
Required for normal development:
|
|
|
|
- `zsh` for `planet.sh`
|
|
- `uv` for Python dependency and test execution
|
|
- `bun` for frontend dependency and build execution
|
|
- Python resolved by `uv` from the root `pyproject.toml`
|
|
|
|
Required for full local stack operation:
|
|
|
|
- Docker and Docker Compose
|
|
- PostgreSQL and Redis containers started by `planet.sh`
|
|
|
|
Optional for delivery smoke:
|
|
|
|
- Docker daemon for image builds
|
|
- Helm for chart lint/template checks
|
|
|
|
If a required local tool is missing, do not install system software
|
|
automatically. Report the gap and point to `./planet.sh init` or
|
|
`scripts/bootstrap-dev.sh` as the existing bootstrap path.
|
|
|
|
## What Agents Must Not Change Automatically
|
|
|
|
- Do not replace Bun with npm, pnpm, or yarn.
|
|
- Do not migrate CI from `.gitea/workflows/` to `.github/workflows/`.
|
|
- Do not rewrite `planet.sh` lifecycle behavior as a parallel script.
|
|
- Do not run `./planet.sh destroy` unless explicitly requested.
|
|
- Do not commit `.env`, secrets, private keys, logs, or generated build output.
|
|
- Do not add external integrations, hooks, or new dependency managers just to
|
|
satisfy harness structure.
|
|
- Do not publish internal harness docs into the product Docs UI unless a
|
|
maintainer explicitly asks for it.
|
|
|
|
## Hooks And Reminders
|
|
|
|
No automatic hooks are installed in this phase. Manual reminders:
|
|
|
|
- Run `scripts/harness/quick-check.sh` before handing off small changes.
|
|
- Run `scripts/harness/validate.sh` before larger cross-subsystem changes.
|
|
- Add focused tests before modifying backend service behavior or frontend
|
|
workflows.
|
|
- For docs changes, run the checks listed in
|
|
`docs/documentation-coverage-rules.md`.
|
|
|
|
## Reusable Workflows
|
|
|
|
### Feature Work
|
|
|
|
1. Read `rules.md` modules for the touched area.
|
|
2. Check `CODEMAP.md` for entry points and ownership boundaries.
|
|
3. Inspect existing tests and docs before editing.
|
|
4. Make the smallest behavior-preserving or feature-scoped change.
|
|
5. Run `scripts/harness/quick-check.sh` or a narrower documented command.
|
|
6. Update relevant docs when behavior, workflow, or operations change.
|
|
|
|
### Bug Fix
|
|
|
|
1. Reproduce with a focused test or command.
|
|
2. Patch the owning module, not a caller-side workaround.
|
|
3. Run the focused regression test.
|
|
4. Run `scripts/harness/quick-check.sh` when the change is safe to validate
|
|
locally.
|
|
|
|
### Documentation Change
|
|
|
|
1. Read `docs/documentation-coverage-rules.md`.
|
|
2. Route docs by audience: UI users, operations, or second-party developers.
|
|
3. Keep Chinese and English public docs consistent when a public doc pair exists.
|
|
4. Run the repository-specific docs checks that match the changed files.
|
|
|
|
### Release Or Delivery Change
|
|
|
|
Use the existing release skill/workflow and `.gitea/workflows/` files. Harness
|
|
validation can smoke-check Helm and Docker locally, but it must not replace the
|
|
release process.
|
|
|
|
## Implementation Notes
|
|
|
|
- `docs/harness-audit.md` records the discovery pass that led to this harness.
|
|
- `AGENTS.md` is a compatibility entry point for tools that expect the uppercase
|
|
filename. The existing `agents.md` file remains in place.
|
|
- `CODEMAP.md` is intentionally high level; deeper subsystem docs stay in
|
|
`docs/technical/{zh,en}/`.
|