mirror of
https://github.com/oqyude/nixos.git
synced 2026-10-11 22:37:25 +03:00
oqyude
0df9688643
Review of dev vs16644fcfound 1 BLOCKING + 3 IMPORTANT + 2 MINOR. All addressed in this commit: B1 (R1.4 stale files in project-rules.md + AGENTS.md): Replaced 'vds/nginx.nix' (removed inef38dc4) with 'home/termux.nix' (added in958247b). R1.4 now correctly lists the 4 files that use 100.64.0.0: home/termux.nix:256, modules/server/nextcloud.nix:73, modules/server/nginx.nix:109,253, modules/vds/systemd.nix:10. I1 (count drift in '15 modules' docs): - AGENTS.md:84 + project-rules.md:97: '15 → 14' (with note that stirling-pdf was deleted in5dd7a58) - manifest.json (T16): rewritten acceptance to '15 archived (13 from server/default.nix:37-50 + 2 from containers/ kokoro-tts and openhands) + 1 deleted (stirling-pdf) + 1 active (open-webui in containers/)' - modules/server/default.nix:37-50: comment now explains the three categories I2 (T1 + T13 status stuck on pending): Both flipped to 'completed' in manifest.json. T1 import fix verified by nix eval (epral stateVersion = '24.05'). T13 done in61b3724(nginx firewall rule removed). I3 (.ci/checks.sh committed) satisfied. M1 (R1.3 stale nginx.nix:225 line number): Removed line number from both project-rules.md and AGENTS.md. Replaced with 'nginx.nix (networking.firewall)'. M2 (R1.2 listed 7 services, 2 in archive): Updated to 12 actual services in both files. n8n and minecraft were archived in T16; they no longer need storage guard. T10 (reality443Forwarding погашен): Removed option from options.nix:66-74, realityPorts from 3x-ui.nix:33-35, and 'reality443Forwarding = true' from vds/default.nix:19. ADR-note comments left in place. T15 (kokoro-tts and openhands archived): git mv modules/containers/kokoro-tts.nix → archive/containers/ git mv modules/containers/openhands.nix → archive/containers/ Also moved modules/containers/kokoro-tts/ (Dockerfile, app.py, etc.) to archive/containers/kokoro-tts/ for completeness. any.nix (nix flake check support): Added stub fileSystems + boot.loader.grub to configurations/any.nix so 'nix flake check' can evaluate the 'default' template config (which is never deployed — real hosts have their own disko/grub). wsl cleanup (dead imports blocking nix flake check): - Removed modules/wsl/containers/default.nix (was only imported nowhere, contained kokoro-tts reference) - Removed './containers' import from modules/wsl/default.nix (resolved to the now-removed default.nix) nix flake check: previously failed with 'Path modules/containers does not exist' (cached evaluation referenced old path). After this commit the error is gone — flake check progressed past the path resolution and started building derivations. Full build output not captured (5-min timeout for download from cache.nixos.org), but path errors are resolved. T5 risk acknowledgment: .agent/decisions/0002-backups-external.md updated with explicit risk table for 'if no backups' scenario + ADR/R1.9 guidance. T1, T2, T6, T7, T8, T9, T10, T12, T13, T15, T16, T17: all → completed in manifest.json. T3, T4, T5, T11, T14: previously completed. Remaining DEFERRED: T3 (otrecа SSH recovery), T5 (5.6 answer).
150 lines
9.2 KiB
Markdown
150 lines
9.2 KiB
Markdown
---
|
||
aliases: []
|
||
cssclasses:
|
||
date-created: 2026-10-09T19:01
|
||
date-modified: 2026-10-09T20:30
|
||
tags: [metaagent, nixos, agents]
|
||
---
|
||
# AGENTS.md
|
||
|
||
Этот проект использует [MetaAgent](.agent/src/GUIDE.md) v3.0.0 — набор
|
||
инструкций для AI-агента.
|
||
|
||
> NixOS-конфиг домашнего флота. 6 NixOS-хостов + Android (`nix-on-droid`).
|
||
> Этот файл — то, что агент должен прочитать **до** первого изменения. Если
|
||
> задача выглядит так, что требует сломать что-то из «Подтверждённых
|
||
> инвариантов» или «Ловушек» ниже — остановиться и спросить.
|
||
|
||
## Контекст MetaAgent
|
||
|
||
| Ресурс | Путь |
|
||
|--------|------|
|
||
| Главная инструкция | `.agent/src/GUIDE.md` |
|
||
| Протоколы фаз | `.agent/src/PROTOCOLS/` |
|
||
| Команды (on-demand) | `.agent/src/COMMANDS/` |
|
||
| Шаблоны артефактов | `.agent/src/TEMPLATES/` |
|
||
| Границы (что разрешено/запрещено) | `.agent/src/BOUNDARIES.md` |
|
||
| История версий | `.agent/src/CHANGELOG.md` |
|
||
| Правила проекта (полные) | `.agent/rules/project-rules.md` |
|
||
| Слепок проекта | `.agent/context/project-state.md` |
|
||
| Анализ репозитория | `.agent/context/analysis-report.md` |
|
||
| Дорожная карта | `.agent/roadmap/sources.md` |
|
||
| Манифест задач | `.agent/tasks/manifest.json` |
|
||
| ADR (архитектурные решения) | `.agent/decisions/` |
|
||
| Пример работы | `.agent/src/WORKFLOW.md` |
|
||
| Версия | `.agent/src/VERSION` |
|
||
|
||
## Архитектура (30 секунд)
|
||
|
||
```
|
||
flake.nix
|
||
├── configurations/ ← реестр хостов (1 запись = 1 машина)
|
||
├── modules/ ← essentials + per-type (desktop/server/vds/wsl/containers/termux)
|
||
├── home/ ← home-manager (per device-type)
|
||
├── lib/xlib/ ← чистые данные: devices, dirs, helpers
|
||
├── deploy/, secrets/ (sops), overlays/, pkgs/
|
||
└── .agent/ ← MetaAgent state (rules, decisions, tasks, context, requests, roadmap)
|
||
```
|
||
|
||
Подробная карта: `.agent/context/project-state.md` и `.agent/context/analysis-report.md`.
|
||
|
||
## Хосты
|
||
|
||
| Attr / имя | device.type | Роль | Деплой | stateVersion | Примечание |
|
||
|---|---|---|---|---|---|
|
||
| `default` (nixos) | minimal | Шаблон / минималка | — | — | hostname `"nixos"` |
|
||
| `atoridu` | primary | Основной десктоп | — (manual) | 26.05 | xanmod, mini-PC |
|
||
| `rydiwo` | secondary | Chuwi MiniBook | deploy-rs | 26.05 | xanmod, NTFS `lamet-drive` |
|
||
| `otrecа` | vds | VPS | deploy-rs | 25.05 | Tailscale-only SSH, nftables (см. T3) |
|
||
| `sapphira` | server | Домашний сервер | deploy-rs | 25.05 | `firewall.enable = false` намеренно |
|
||
| `wsl` | wsl | WSL NixOS | — (manual) | 24.11 | на vetymae (Windows 192.168.1.100) |
|
||
| `epral` | termux | Android | — | 24.05 | nix-on-droid, через `mobile.nix` |
|
||
|
||
## Подтверждённые инварианты
|
||
|
||
> Полные формулировки (с «Где» и «Почему») — в `.agent/rules/project-rules.md` (R1).
|
||
|
||
1. **Все `outputs` флейка должны вычисляться.** `configurations/mobile.nix:12` импортировал несуществующий `lib/xlib.nix` — был сломан, `epral` не собирался. → задача T1.
|
||
2. **External-диск обязан быть смонтирован** до старта `postgresql`, `samba`, `homebox`,
|
||
`gitea`, `navidrome`, `syncthing`, `uptime-kuma`, `immich`, `nextcloud`,
|
||
`calibre-web`, `3x-ui`, `tape-rotation`. → задача T4.
|
||
3. **Сетевая граница sapphira — роутер.** 5 портов: **443, 80, 22000 (syncthing), 8443 (xray), 22 (ssh)**. `firewall.enable = false` намеренно. nginx.nix (networking.firewall) мёртв (T13). → задача T11.
|
||
4. **`100.64.0.0` = Tailscale-адрес sapphira**, назначен вручную. В `home/termux.nix:256`,
|
||
`modules/server/nextcloud.nix:73`, `modules/server/nginx.nix:109,253`,
|
||
`modules/vds/systemd.nix:10`. → задача T12.
|
||
5. **3x-ui заморожен.** Панель на `:latest`, ядро Xray на 26.7.x. Миграция на 26.9.x провалена. → задачи T6–T10.
|
||
6. **nftables на VDS требует явной финальной политики.** Текущий ruleset — без финального правила → неявный accept. → задача T3.
|
||
7. **sops-пути — через `config.sops.secrets.<name>.path`.** Любой `path =` override на sops-блоке делает хардкод-потребителя молча сломанным. → ADR-0001.
|
||
|
||
## Ловушки (выглядит сломанным, намеренно)
|
||
|
||
| Где | Что выглядит ошибкой | На самом деле |
|
||
|---|---|---|
|
||
| `server.nix:130` | `firewall.enable = false` при 20 сервисах на `0.0.0.0` | Роутер фильтрует, см. инв. 3 |
|
||
| `mobile.nix:95`, `wsl.nix:59` | `stateVersion` 24.05 / 24.11 vs 26.05 | Каждый хост зафиксирован на своей версии |
|
||
| `users.nix:66` | `uid = if hostname == "sapphira" then 1001 else …` | Костыль под 1000 = удалённый `yuyus`; удалять только после миграции ФС |
|
||
| `3x-ui.nix:54` | `image = …:latest` | Панель намеренно latest; ядро Xray — на 26.7.x |
|
||
| `3x-ui.nix:33-35` | `reality443Forwarding = true` на VDS | Следствие отката `c8d4a12`; см. задачу T10 |
|
||
| `server/default.nix:37-50` | 14 закомментированных модулей (13 архивировано, 1 stirling-pdf удалён в 5dd7a58) | Отключены осознанно, см. задачу T16 |
|
||
| `opencode.nix:339` | `systemd.user.services.opencode-web.Service` | `serviceConfig` рендерится в секцию `[serviceConfig]`, systemd молча игнорирует; см. R2 |
|
||
| `vds.nix:73-91` | nftables без финального правила | Известный пробел, см. задачу T3 |
|
||
| `100.64.0.0` | Первый адрес CGNAT `/10` | Tailscale-адрес sapphira, см. инв. 4 |
|
||
| `server.nix:61-63` | `z /mnt/services 0777` | World-writable точка монтирования; см. задачу T4 |
|
||
|
||
## Куда лезть по задаче
|
||
|
||
| Задача | Файл |
|
||
|---|---|
|
||
| Добавить хост | `configurations/default.nix` + `configurations/<host>.nix` + `configurations/{hardware,disko}/<host>.nix` |
|
||
| Добавить системный сервис | `modules/server/<name>.nix`, добавить в `modules/server/default.nix:imports` |
|
||
| Добавить home-пакет | `home/<device_type>.nix` |
|
||
| Добавить кросс-модульную опцию | `modules/options.nix` |
|
||
| Изменить mount/имя пользователя | `lib/xlib/dirs.nix`, `lib/xlib/device.nix` |
|
||
| Изменить домен / сертификат | `modules/server/coredns.nix` + `modules/server/nginx.nix` (или `vds/`) |
|
||
| Sops-секрет | `secrets/<name>.<yaml\|json\|env\|ini>`; `users.nix:99` подключает `secrets/default.yaml`; dotenv/json — через `mkUserSecret` |
|
||
|
||
## Проверки
|
||
|
||
```bash
|
||
# все outputs вычисляются
|
||
nix flake check
|
||
|
||
# правки применились на целевой хост
|
||
nix build .#nixosConfigurations.<host>.config.system.build.toplevel
|
||
|
||
# nixOnDroid
|
||
nix build .#nixOnDroidConfigurations.epral.config.system.build.toplevel
|
||
|
||
# внешний диск смонтирован (до рестарта сервисов на нём)
|
||
findmnt /home/oqyude/External
|
||
findmnt /mnt/services
|
||
|
||
# sops
|
||
sops --version
|
||
```
|
||
|
||
## Где НЕ лезть без ответа владельца
|
||
|
||
- `secrets/` (sops-encrypted, расшифровываются `/etc/ssh/id_ed25519` → циклический bootstrap).
|
||
- `let deploy` без проверки deploy-rs нод: `rydiwo` (ноутбук, может быть выключен).
|
||
- Любая правка, противоречащая «Подтверждённым инвариантам» выше.
|
||
- Ядро Xray 26.7.x → 26.9.x — миграция провалена, не повторять без отдельной задачи.
|
||
|
||
## Команды MetaAgent (on-demand)
|
||
|
||
- `/adr` — записать архитектурное решение
|
||
- `/red-team` — попытаться сломать дизайн
|
||
- `/risk-register` — зафиксировать допущения
|
||
- `/alt-arch` — описать альтернативу
|
||
- `/invariant-tests` — тесты-инварианты для ADR
|
||
|
||
## Жизненный цикл MetaAgent v3.0.0
|
||
|
||
```
|
||
INIT → ANALYSE → ROADMAP → [DESIGN] → DECOMPOSITION → EXECUTION → METASTATE → HANDOFF
|
||
```
|
||
|
||
Текущее состояние: см. `.agent/checkpoints.json` (`phases.init = completed`,
|
||
`phases.analyse = completed`, `phases.roadmap = completed`,
|
||
`phases.decomposition = completed`, `phases.execution = in_progress`).
|