mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2026-11-13 09:13:30 +01:00

Files

T

2245976de4 docs(ai): move agent rules to ai/skills and add an AI development sandbox (#1498 )

The sandbox provides an isolated Docker environment for AI-assisted development
(OpenCode + Claude Code + Qwen Code) against the local AkkudoktorEOS repository.

The sandbox does not protect the repository from harmful changes by the agent.
It limits what a misled agent can reach on the machine, but the agent can still
write any change into the repository.

Primary security defence is to check every change before it is run on the host.
Same holds for opening a pull request or updating one.

Additional changes

- Reduce AGENTS.md to the project summary, baseline rules, completion checklist,
  and an index of the skills.
- Add skills for the Python environment and REST API error responses.
- Add the development guide page docs/develop/ai.md: the AI coding
  workflow, how agents get the project rules from AGENTS.md and ai/skills,
  and how to use the sandbox (start, agent logins, project commands with a
  virtual environment outside the workspace, running EOS and EOSdash,
  GitHub access, persistent data, security model).
- Add a checklist for reviewing agent changes before pushing, starting with
  .git, which stays writable in the sandbox.
- Check out all text files with LF line endings (.gitattributes), also on
  Windows with core.autocrlf, so the sandbox scripts run in the container
  and git in the container agrees with git on the host. Batch files keep CRLF.
- Publish the ports of ai/compose.yaml on request (AI_SANDBOX_PORTS=1).
  docker compose run publishes them only with --service-ports. Off by
  default, so that several sandboxes can run in parallel.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

2026-11-09 09:15:12 +01:00

2.1 KiB

Raw Blame History

name, description

name	description
rest-api	Use when adding or changing EOS REST endpoints (FastAPI, `src/akkudoktoreos/server/eos.py` and `src/akkudoktoreos/server/rest/`). Enforces RFC 7807 problem details via EOSProblem for all errors.

REST API

When to use

Adding or changing an endpoint in server/eos.py or a router in server/rest/.
Changing how an endpoint reports errors.

Errors

EOS answers errors as RFC 7807 problem details (application/problem+json with type, title, status, detail, instance), see src/akkudoktoreos/server/rest/error.py.

Raise EOSProblem, never FastAPI's HTTPException:

from akkudoktoreos.server.rest.error import EOSProblem

try:
    value = get_config().get_nested_value(path)
except KeyError as exc:
    raise EOSProblem(status=404, title="Config value not found", detail=str(exc)) from exc

title: short, stable summary of the kind of problem, the same for all occurrences (e.g. "Error on cache clear", "Total load prediction failed"). detail: the specific message for this occurrence.
Chain the original exception (raise ... from exc).
Pass cause=exc only for server-side failures (5xx, unexpected errors in EOS): the handler logs the cause with its traceback. Leave it out for client errors (bad input, unknown names) so they do not flood the log.
Do not catch broad exceptions just to convert them; unexpected exceptions are already answered as 500 problem details by the registered handler.
HTTPException is only still handled for errors raised by FastAPI and Starlette themselves (e.g. unknown routes).

Tests

Tests that build their own app around a router must register the handlers, otherwise an EOSProblem surfaces as an exception in the test client:
```
app = FastAPI()
register_problem_handlers(app)
app.include_router(router)
```
Check the status code of error responses; check the problem body where the title or detail matters to clients.

Verify

docs/_generated/openapi.md and openapi.json are generated from the endpoints; regenerate them (make gen-docs) after endpoint changes.

2.1 KiB Raw Blame History