From 8da10d04c920f0dcd67f0ccf7d020cf890084f3c Mon Sep 17 00:00:00 2001 From: Alexey Martemyanov Date: Wed, 18 Nov 2026 19:05:28 +0600 Subject: [PATCH] [2026-11-18] eagle: personal/knowledge/obsidian/reference/knowledge-lifecycle.md personal/knowledge/obsidian/reference/obsidian-mcp-setup.md personal/knowledge/obsidian/reference/obsidian-mcp-wrapper.md personal/knowledge/obsidian/reference/obsidian-vault-strategy.md personal/knowledge/obsidian/reference/research-queue.md personal/knowledge/obsidian/reference/vault-agent-integration.md personal/knowledge/obsidian/reference/vault-filling-guide.md personal/knowledge/obsidian/reference/vault-namespace.md personal/knowledge/obsidian/reference/wiki-ingest-process.md personal/knowledge/obsidian/reference/wiki-schema.md --- .../obsidian/reference/knowledge-lifecycle.md | 82 + .../obsidian/reference/obsidian-mcp-setup.md | 216 + .../reference/obsidian-mcp-wrapper.md | 25 + .../reference/obsidian-vault-strategy.md | 550 + .../obsidian/reference/research-queue.md | 20 + .../reference/vault-agent-integration.md | 84 + .../obsidian/reference/vault-filling-guide.md | 78 + .../obsidian/reference/vault-namespace.md | 35 + .../obsidian/reference/wiki-ingest-process.md | 100 + .../obsidian/reference/wiki-schema.md | 125 + .../personal-os-operating-plan-2026-10-03.md | 213 +- .../personal-os-source-audit-2026-10-03.md | 52 +- personal/plans/personal-os-v2-plan.md | 191 +- .../reference/agent-memory-architecture.md | 75 + .../reference/agent-names-brainstorm.md | 78 + .../reference/ai-agent-landscape-2026.md | 91 + .../reference/autonomous-agent-safety.md | 113 + .../reference/claude-proxy-node-internals.md | 181 + .../reference/claude-python-cli-proxy.md | 219 + .../hermes/reference/claude-wrapper-proxy.md | 54 + .../hermes/reference/eagle-dashboard.md | 346 + .../executor-orchestrator-redesign.md | 155 + .../reference/executor-security-analysis.md | 750 + .../hermes/reference/executor-skip-report.md | 39 + .../reference/executor-spawning-research.md | 133 + .../hermes/reference/executor-v2-redesign.md | 207 + .../reference/glm-provider-migration.md | 199 + .../reference/hermes-agent-improvements.md | 355 + .../reference/hermes-calendar-access.md | 50 + .../hermes/reference/hermes-cron-jobs.md | 92 + .../reference/hermes-deployment-patterns.md | 95 + .../reference/hermes-native-vs-docker.md | 85 + .../reference/kraken-obsidian-write-bug.md | 57 + .../reference/multi-agent-design-patterns.md | 107 + .../reference/multi-host-cron-topology.md | 71 + .../personal-os/agent-memory-architecture.md | 76 +- .../personal-os/agent-names-brainstorm.md | 79 +- .../personal-os/ai-agent-landscape-2026.md | 92 +- .../personal-os/ai-psychologist-research.md | 285 +- .../personal-os/autonomous-agent-safety.md | 114 +- .../claude-proxy-node-internals.md | 182 +- .../personal-os/claude-python-cli-proxy.md | 220 +- .../personal-os/claude-wrapper-proxy.md | 55 +- .../deliverables/personal-os-first-day.pptx | Bin 45675 -> 0 bytes .../projects/personal-os/eagle-dashboard.md | 347 +- .../executor-orchestrator-redesign.md | 156 +- .../personal-os/executor-security-analysis.md | 751 +- .../personal-os/executor-skip-report.md | 40 +- .../personal-os/executor-spawning-research.md | 134 +- .../personal-os/executor-v2-redesign.md | 208 +- .../personal-os/glm-provider-migration.md | 200 +- .../personal-os/hermes-agent-improvements.md | 356 +- .../personal-os/hermes-calendar-access.md | 51 +- .../projects/personal-os/hermes-cron-jobs.md | 93 +- .../personal-os/hermes-deployment-patterns.md | 96 +- .../personal-os/hermes-native-vs-docker.md | 86 +- .../personal-os/knowledge-lifecycle.md | 83 +- .../personal-os/kraken-obsidian-write-bug.md | 58 +- .../multi-agent-design-patterns.md | 108 +- .../personal-os/multi-host-cron-topology.md | 72 +- .../personal-os/obsidian-mcp-setup.md | 217 +- .../personal-os/obsidian-mcp-wrapper.md | 26 +- .../personal-os/obsidian-vault-strategy.md | 551 +- .../personal-os/personal-os-agent-rules.md | 108 +- ...nal-os-architecture-decision-2026-10-04.md | 48 +- .../personal-os-best-practices-2026-10-04.md | 126 +- .../personal-os-buy-adapt-build-2026-10-05.md | 53 +- .../personal-os-catchup-plan-2026-04-27.md | 94 +- ...al-os-data-analysis-workflow-2026-10-09.md | 325 +- ...nal-os-evidence-graph-design-2026-10-04.md | 96 +- .../scenario-automation-update.json | 19 - .../personal-os-failed-approaches.md | 51 +- ...rsonal-os-independent-review-2026-11-17.md | 42 +- .../personal-os-production-acceptance.md | 1 + .../personal-os/personal-os-purpose.md | 2 +- ...-os-ready-systems-and-skills-2026-10-04.md | 103 +- ...ersonal-os-rlm-stand-results-2026-10-10.md | 166 +- .../personal-os/personal-os-schema.md | 93 +- .../personal-os-self-modification.md | 158 +- ...rsonal-os-six-layer-analysis-2026-10-05.md | 378 +- .../personal-os-state-2026-04-27.md | 102 +- .../personal-os/personal-os-status-2026-10.md | 80 +- .../personal-os/personal-os-sync-pipeline.md | 92 +- .../personal-os-system-review-2026-10-04.md | 460 +- .../personal-os-system-review-index.md | 70 +- ...sonal-os-windmill-system-map-2026-10-10.md | 108 +- ...sonal-os-work-graph-research-2026-10-04.md | 252 +- .../personal-os/project-truth-analyzer.md | 56 +- .../projects/personal-os/research-queue.md | 21 +- .../unprejudiced-ai-psychologist.md | 102 +- .../personal-os/vault-agent-integration.md | 85 +- .../personal-os/vault-filling-guide.md | 79 +- .../projects/personal-os/vault-namespace.md | 36 +- .../personal-os/wiki-ingest-process.md | 101 +- personal/projects/personal-os/wiki-schema.md | 126 +- .../work-claims-results-2026-10-12.md | 15521 +--------------- .../personal-os/zoom-ai-transcript-export.md | 108 +- .../reference/ai-psychologist-research.md | 284 + .../reference/unprejudiced-ai-psychologist.md | 101 + 99 files changed, 5376 insertions(+), 24330 deletions(-) create mode 100644 personal/knowledge/obsidian/reference/knowledge-lifecycle.md create mode 100644 personal/knowledge/obsidian/reference/obsidian-mcp-setup.md create mode 100644 personal/knowledge/obsidian/reference/obsidian-mcp-wrapper.md create mode 100644 personal/knowledge/obsidian/reference/obsidian-vault-strategy.md create mode 100644 personal/knowledge/obsidian/reference/research-queue.md create mode 100644 personal/knowledge/obsidian/reference/vault-agent-integration.md create mode 100644 personal/knowledge/obsidian/reference/vault-filling-guide.md create mode 100644 personal/knowledge/obsidian/reference/vault-namespace.md create mode 100644 personal/knowledge/obsidian/reference/wiki-ingest-process.md create mode 100644 personal/knowledge/obsidian/reference/wiki-schema.md create mode 100644 personal/projects/hermes/reference/agent-memory-architecture.md create mode 100644 personal/projects/hermes/reference/agent-names-brainstorm.md create mode 100644 personal/projects/hermes/reference/ai-agent-landscape-2026.md create mode 100644 personal/projects/hermes/reference/autonomous-agent-safety.md create mode 100644 personal/projects/hermes/reference/claude-proxy-node-internals.md create mode 100644 personal/projects/hermes/reference/claude-python-cli-proxy.md create mode 100644 personal/projects/hermes/reference/claude-wrapper-proxy.md create mode 100644 personal/projects/hermes/reference/eagle-dashboard.md create mode 100644 personal/projects/hermes/reference/executor-orchestrator-redesign.md create mode 100644 personal/projects/hermes/reference/executor-security-analysis.md create mode 100644 personal/projects/hermes/reference/executor-skip-report.md create mode 100644 personal/projects/hermes/reference/executor-spawning-research.md create mode 100644 personal/projects/hermes/reference/executor-v2-redesign.md create mode 100644 personal/projects/hermes/reference/glm-provider-migration.md create mode 100644 personal/projects/hermes/reference/hermes-agent-improvements.md create mode 100644 personal/projects/hermes/reference/hermes-calendar-access.md create mode 100644 personal/projects/hermes/reference/hermes-cron-jobs.md create mode 100644 personal/projects/hermes/reference/hermes-deployment-patterns.md create mode 100644 personal/projects/hermes/reference/hermes-native-vs-docker.md create mode 100644 personal/projects/hermes/reference/kraken-obsidian-write-bug.md create mode 100644 personal/projects/hermes/reference/multi-agent-design-patterns.md create mode 100644 personal/projects/hermes/reference/multi-host-cron-topology.md delete mode 100644 personal/projects/personal-os/deliverables/personal-os-first-day.pptx delete mode 100644 personal/projects/personal-os/personal-os-evidence/2026-11-18/scenario-automation-update.json create mode 100644 personal/projects/psychologist-app/reference/ai-psychologist-research.md create mode 100644 personal/projects/psychologist-app/reference/unprejudiced-ai-psychologist.md diff --git a/personal/knowledge/obsidian/reference/knowledge-lifecycle.md b/personal/knowledge/obsidian/reference/knowledge-lifecycle.md new file mode 100644 index 00000000..80753ac6 --- /dev/null +++ b/personal/knowledge/obsidian/reference/knowledge-lifecycle.md @@ -0,0 +1,82 @@ +--- +namespace: work +tags: + - agent + - memory + - wiki + - synthesis + - vault +created: '2026-05-19' +updated: '2026-10-14' +type: concept +confidence: 0.9 +sources: + - wiki/concepts/agent-memory-architecture.md + - wiki/concepts/vault-strategy.md + - wiki/wiki-ingest-process.md + - wiki/personal-os-self-modification.md +--- +# Knowledge Lifecycle — From Session to Permanent Memory + +Синтез: как знание движется от рабочей сессии к постоянной памяти в personal-os. Объединяет [[personal/projects/personal-os/agent-memory-architecture]], [[personal/projects/personal-os/obsidian-vault-strategy]] и [[wiki-ingest-process]]. + +## Общая схема + +``` +Событие/Разговор + │ + ▼ +Working Memory (контекст сессии, эфемерный) + │ session_search + SHA256 hash + ▼ +Episodic Memory (SQLite sessions, сжатые саммари) + │ crystallization (wiki-curation cron 02:00) + ▼ +Semantic Memory (wiki/ pages, постоянное знание) + │ wiki-ingest 22:00 (launchd, claude -p) + │ overflow rule (>150 chars → vault) + ▼ +Procedural Memory (skills/, workflows) +``` + +## Три барьера кристаллизации + +Не всё знание заслуживает кристаллизации. Барьеры: + +| Уровень | Критерий | Место | +|---------|----------|-------| +| Session → Wiki | Painful to re-derive? Fits domain? Contains facts (not conversation)? | `wiki/` | +| Wiki → MEMORY.md | Стабильный факт, ≤150 символов? | `~/.hermes/MEMORY.md` | +| Any → Skills | Пошаговая процедура, повторяемая? | `~/.hermes/skills/` | + +**Правило overflow:** MEMORY.md — только короткие стабильные факты. Детали → в wiki с pointer в MEMORY.md: `"media-pipeline питфолы → wiki/tech/media-pipeline-pitfalls.md"`. + +## Три задачи vault (не смешивать) + +1. **Vault Enrichment** — frontmatter + aliases + wikilinks на `personal/`, `family/` +2. **LLM Wiki** — crystallization sessions → `wiki/` (этот файл про это) +3. **Proactive Research** — агент генерирует гипотезы → `wiki/research-queue.md` → Saturday cron + +## Риски деградации + +- **Summarization drift:** после 3+ циклов сжатия теряются критические инструкции. Решение: vault как immutable store (не перезаписывать, только аппендить/обновлять dated sections). +- **Repetitive behavior:** без weekly reflection агент деградирует (Generative Agents, 48ч без рефлексии). Фикс: Retrospector каждую пятницу читает corrections_log. +- **Orphaned knowledge:** факт записан, но никогда не читается. Фикс: lint (orphan pages), провалидированные wikilinks. + +## Инструменты в personal-os + +| Инструмент | Функция | +|-----------|---------| +| wiki-curation cron (02:00) | Crystallization: sessions → wiki | +| wiki-ingest launchd (22:00) | Synthesis: raw/ symlinks → wiki pages | +| `session_search` | Episodic retrieval | +| obsidian MCP | Semantic retrieval | +| MEMORY.md | Fast facts, overflow pointers | +| research-queue.md | Proactive research agenda | + +## Связанные страницы + +- [[personal/projects/personal-os/agent-memory-architecture]] — когнитивная таксономия памяти (episodic/semantic/procedural) +- [[personal/projects/personal-os/obsidian-vault-strategy]] — три задачи vault: enrichment, LLM wiki, proactive research +- [[wiki-ingest-process]] — hash-based incremental ingest из raw/ symlinks +- [[personal-os-self-modification]] — как система эволюционирует через корректировки diff --git a/personal/knowledge/obsidian/reference/obsidian-mcp-setup.md b/personal/knowledge/obsidian/reference/obsidian-mcp-setup.md new file mode 100644 index 00000000..ea933432 --- /dev/null +++ b/personal/knowledge/obsidian/reference/obsidian-mcp-setup.md @@ -0,0 +1,216 @@ +> [!IMPORTANT] Актуальная конфигурация для Balda (2026-10-09) +> Текущая Balda использует Codex ACP и Streamable HTTP: `type: http`, URL `http://host.docker.internal:3101/mcp`. +> Указания ниже про Balda + SSE или `/sse` относятся к прежним клиентам/развёртываниям. Канонический runbook: [[personal/projects/balda/setup]]. + +# Obsidian MCP — текущая архитектура + +## Факт: что стоит сейчас + +**Hermes native MCP client** (встроен в Hermes Agent, не wrapper). + +Конфиг в `~/.hermes/config.yaml` (и в `~/.hermes/hermes-whale/config.yaml`): +```yaml +mcp_servers: + obsidian: + command: mcpvault + args: + - /Users/admin/obsidian +``` + +Пакет: **`@bitbonsai/mcpvault`** v0.12.1 (npm). Команда `mcpvault`. + +Hermes на старте: +1. Читает `mcp_servers` из config.yaml +2. Спавнит `mcpvault /Users/admin/obsidian` как subprocess +3. Init + list_tools → регистрирует инструменты как `mcp_obsidian_*` +4. Агент видит инструменты `mcp_obsidian_read_note`, `mcp_obsidian_patch_note`, и т.д. + +**Схема:** +``` +Hermes (native MCP client) → spawn: mcpvault → reads/writes /Users/admin/obsidian/ +``` + +### Инструменты, доступные через эту связку + +`read_note`, `write_note`, `patch_note`, `list_directory`, `delete_note`, `search_notes`, `move_note`, `move_file`, `read_multiple_notes`, `update_frontmatter`, `get_notes_info`, `get_frontmatter`, `manage_tags`, `get_vault_stats`, `list_all_tags`. + +## Факт: что такое ~/scripts/obsidian-mcp-wrapper.js и почему он НЕ используется + +**Создан** 2026-05-09, когда вместо `mcpvault` стоял `npx obsidian-mcp` (старый пакет, автор Steven, ещё до переименования в `@bitbonsai/mcpvault`). Пакет постоянно падал: +- ZodError на `"id": null` в notifications — `.strict()` валидация +- Race condition при рестарте gateway +- UTF-8 chunk split портил большие JSON +- Зависания без watchdog + +Wrapper решал всё это. **Сейчас НЕ используется.** Конфиг в `~/.hermes/config.yaml`: +```yaml +mcp_servers: + obsidian: + command: mcpvault # ← не node wrapper.js + args: + - /Users/admin/obsidian +``` + +**Почему:** после перехода на `@bitbonsai/mcpvault` (пришёл на смену старому obsidian-mcp), пакет стабильно работает с Hermes native MCP client. Wrapper стал не нужен. Конфиг поменяли, а doc не обновили. + +**Файл `~/scripts/obsidian-mcp-wrapper.js`** лежит на диске, не используется. Надо удалить. + +## Факт: корень проблем с patch_note + +`mcp_obsidian_patch_note` падает с `"String not found"` — это **НЕ проблема транспорта**. Это проблема **самого mcpvault**: +- Файл: `dist/src/filesystem.js`, строка 217 +- Механизм: `fullContent.split(oldString).length - 1` +- **Exact string match** — без trim, без fuzzy, без нормализации whitespace + +Workaround: использовать Hermes `patch()` (fuzzy matching, 9 стратегий) для сложных строк. `mcp_obsidian_patch_note` — только для простого текста без спецсимволов. + +## Fact: Obsidian MCP на Kraken — есть, и это stdio-процесс Hermes + +Проверено 2026-09-26. На Kraken MCP-сервер **не является отдельным контейнером** — +его спавнит агент Hermes как дочерний процесс. Первый поиск «нет контейнера → +нет MCP» был **ошибочным**: искать надо было процессы, а не `docker ps`. + +``` +# на хосте Kraken +ps aux | grep mcpvault +→ UID 10000 1168741 ... node /opt/data/.local/bin/mcpvault /vault + PPID 5039 → /opt/hermes/.venv/bin/hermes gateway (контейнер hermes-kraken) +``` + +Конфиг (`/opt/data/config.yaml` **внутри** контейнера `hermes-kraken`): + +```yaml +mcp_servers: + obsidian: + command: /opt/data/.local/bin/mcpvault + args: + - /vault +``` + +`mcpvault` там — симлинк на npm-пакет: `/opt/data/.local/lib/node_modules/@bitbonsai/mcpvault/dist/server.js`. + +### Волт на Kraken — реальный, не пустой + +``` +/home/kraken/obsidian -> /srv/dev-disk-by-uuid-49e8f586-…/obsidian + (тот же HDD, что и docker-data) +``` + +Внутри: `personal/`, `family/`, `.obsidian/`, `.git/`, `_index.md` — полноценная +git-реплика волта Mac. То есть **волт существует в обоих местах**, а не только на Mac. + +### Итог: два независимых Obsidian MCP + +| Где | Как | Транспорт | Порт | +|---|---|---|---| +| Mac | контейнер `obsidian-mcp` (`mcp-proxy` → `mcpvault`) | SSE | `:3101`, публикуется на `0.0.0.0` | +| Kraken | `mcpvault` как дочерний процесс `hermes-kraken` | **stdio** | нет | +| Kraken (для Балды) | контейнер `obsidian-mcp` — **создан 2026-09-26** | SSE | `:3101`, только внутри `mattermost_mm-net` | + +📌 `mcpvault` **не умеет HTTP** — только stdio (`--help` подтверждает: только `[vault-path]`). +Чтобы отдать его по сети, нужен `mcp-proxy` (обёртка stdio → SSE). Именно так сделано +на Mac и повторено на Kraken. + +--- + +## Fact: obsidian-mcp на Kraken для Балды (создан 2026-09-26) + +Собрано для шага 5 [[personal/plans/balda-mm-phase4-agents]]: Балде нужен доступ к +волту, чтобы читать документацию при формировании ТЗ. + +**Точная копия рабочей схемы с Mac** — пара `mcp-proxy` + `mcpvault`: + +| Что | Путь / значение | +|---|---| +| Проект (Mac) | `~/Developer/obsidian-mcp-kraken/` | +| Dockerfile | `node:24-bookworm` + `@bitbonsai/mcpvault@0.11.0` + `mcp-proxy@6.4.4` | +| Образ | `obsidian-mcp-image:0.1.0` (загружен на Kraken) | +| Compose (Kraken) | `/home/kraken/obsidian-mcp/docker-compose.yml` | +| Контейнер | `obsidian-mcp`, сеть `mattermost_mm-net` | +| Волт | `/srv/dev-disk-by-uuid-49e8f586-…/obsidian` → `/vault` **`:ro`** | +| Команда | `mcp-proxy --port 3101 -- mcpvault /vault` | + +🔴 **Волт смонтирован только для чтения (`:ro`).** Балда читает документацию, но не +правит её. Запись в волт через Балду — отдельное решение, требует апрува Alex. + +```yaml +services: + obsidian-mcp: + image: obsidian-mcp-image:0.1.0 + container_name: obsidian-mcp + restart: unless-stopped + command: ["--port", "3101", "--", "mcpvault", "/vault"] + volumes: + - /srv/dev-disk-by-uuid-49e8f586-…/obsidian:/vault:ro + networks: + - mm-net # mattermost_mm-net, external +``` + +### Питфоллы, пройденные при сборке + +| # | Питфолл | Симптом | Фикс | +|---|---|---|---| +| 1 | `--host` у `mcp-proxy` **нет** | контейнер падает на разборе аргументов | только `--port N -- `; слушает `0.0.0.0` по умолчанию | +| 2 | Точка монтирования должна существовать в образе | `mkdir -p /vault` в Dockerfile + `WORKDIR /vault` | иначе mcpvault стартует не в том каталоге | + +### Проверка + +```bash +# /sse отвечает 200 (и локально, и из docker-сети Kraken) +curl -s -o /dev/null -w "%{http_code}\n" http://obsidian-mcp:3101/sse + +# ⚠️ Порт именно 3101, НЕ 8080. Проба на 8080 даёт "Connection refused" при живом +# контейнере — mcp-proxy слушает порт из --port. +``` + +✅ **ПРИМЕНЕНО 2026-09-26.** Конфиг Балды на Kraken теперь содержит оба сервера: + +```yaml +runtime: + mcp_servers: + executor-mcp: + type: http # ⚠️ НЕ streamable-http — валидатор: stdio|http|sse + url: "http://balda-executor-mcp:8890/mcp" + obsidian: + type: sse # ⚠️ НЕ http — у obsidian-mcp SSE-транспорт + url: "http://obsidian-mcp:3101/sse" +balda: + mcp_servers: + - executor-mcp + - obsidian +``` + +🔴 **Тип транспорта — источник двух подряд ошибок.** Obsidian отдаёт **SSE**, поэтому +`type: sse`. Если поставить `type: http`, Балда упадёт с +`failed to init MCP session: … session not found`. +Полная таблица типов — [[personal/tech/balda-executor-mcp]] §10e. + +Бэкапы: `config.yaml.bak-obsidian-20260926-214849` (на Kraken, рядом с `config.yaml`). + +⚠️ Туннель к Obsidian MCP **не нужен** — Балда ходит по docker-сети по имени +`obsidian-mcp`. Наружу порт не публикуется. + +--- + +## Эволюция Obsidian MCP у нас + +| Период | Что было | Проблемы | +|--------|----------|----------| +| До 2026-05-09 | `npx obsidian-mcp` (пакет Steven, прямой) | ZodError, race condition, UTF-8 chunk split, зависания | +| 2026-05-09 → ? | `npx obsidian-mcp` через wrapper | Wrapper решил проблемы | +| Сейчас | `mcpvault` (Hermes native MCP client) | Стабильно. patch_note exact match — единственная боль | + +## Рекомендация по замене (2026-06-24) + +При проблемах с mcpvault (зависания, память, exact match) — **cyanheads/obsidian-mcp-server**: +- `obsidian_replace_in_note` с regex + flexible whitespace (решает exact match) +- 9.7K dl/week, dual transport (stdio + HTTP), active +- Требует Obsidian Local REST API plugin (Obsidian должен быть открыт) +- Есть Docker support (`ghcr.io/cyanheads/obsidian-mcp-server`) + +Подробнее: `personal/tech/obsidian-mcp-ecosystem.md` + +## См. также + +- `personal/tech/obsidian-mcp-ecosystem.md` — обзор всех 6 реализаций +- ⚠️ `personal/projects/personal-os/obsidian-mcp-wrapper.md` — **УСТАРЕЛ**, не отражает реальность diff --git a/personal/knowledge/obsidian/reference/obsidian-mcp-wrapper.md b/personal/knowledge/obsidian/reference/obsidian-mcp-wrapper.md new file mode 100644 index 00000000..9f72cb8e --- /dev/null +++ b/personal/knowledge/obsidian/reference/obsidian-mcp-wrapper.md @@ -0,0 +1,25 @@ +--- +status: deprecated +superseded_by: personal/projects/personal-os/obsidian-mcp-setup.md +reason: >- + wrapper не используется с 2026-05. Реальность: Hermes native MCP client → + mcpvault +--- + +# obsidian-mcp-wrapper — УСТАРЕЛ + +> **⚠️ Этот документ не отражает реальность.** Wrapper не используется с мая 2026. +> См. `personal/projects/personal-os/obsidian-mcp-setup.md` и +> `personal/tech/obsidian-mcp-ecosystem.md`. + +Актуальная архитектура: **Hermes native MCP client → spawn `mcpvault /Users/admin/obsidian`** +(пакет `@bitbonsai/mcpvault` v0.12.1). Конфиг в `~/.hermes/config.yaml` → `mcp_servers.obsidian`. + +Wrapper (`~/scripts/obsidian-mcp-wrapper.js`) когда-то решал проблемы старого пакета `obsidian-mcp` +(автор Steven), который падал с ZodError, race condition и UTF-8 chunk split. +После смены пакета на `@bitbonsai/mcpvault` — wrapper стал не нужен. + +Корень проблем с `patch_note` (`"String not found"`) — exact string match в самом mcpvault, +**не в транспорте**. Workaround: использовать Hermes `patch()` с fuzzy matching. + +Историческая документация по wrapper сохранена ниже для ретроспективы. diff --git a/personal/knowledge/obsidian/reference/obsidian-vault-strategy.md b/personal/knowledge/obsidian/reference/obsidian-vault-strategy.md new file mode 100644 index 00000000..a7c6e842 --- /dev/null +++ b/personal/knowledge/obsidian/reference/obsidian-vault-strategy.md @@ -0,0 +1,550 @@ +--- +title: "Obsidian Vault Strategy & LLM Wiki" +aliases: + - "Vault Strategy" + - "obsidian-vault-strategy" + - "LLM Wiki Plan" +created: '2026-05-15' +updated: '2026-10-14' +tags: + - personal-os + - obsidian + - vault + - strategy + - llm-wiki +status: active +related: + - "[[personal/projects/personal-os/personal-os-architecture]]" + - "[[personal/projects/personal-os/executor-security-analysis]]" +--- +# Obsidian Vault Strategy & LLM Wiki Plan + +> Deep research 2026-05-15. +> Источники: Karpathy LLM Wiki gist (5000+ stars), LLM Wiki v2 (rohitg00, 1200+ stars), claude-obsidian (PyShine), Ar9av/obsidian-wiki (DeepWiki), Tom Nguyen 6-month report, Nodus Labs knowledge graph extension, mathisgauthey (r/ObsidianMD, 1000+ upvotes), MOC+Dataview guide, Obsidian+Claude Code integration, LifeOS, Obsidian Forum. + +--- + +## Часть 1 — Текущее состояние vault + +### Что есть + +| Тип контента | Примеры | Где лежит | +|---|---|---| +| Личные списки | Список дел, Фильмы, Книги, Покупки | `personal/documents/`, `family/documents/` | +| Брифы и планы | Daily brief, weekly plan, inbox triage | `work/briefs/` | +| Проектные заметки | executor, media-pipeline, wiki | `personal/projects/`, `family/projects/` | +| How-to документация | HTPC, Кракен, WireGuard | `family/how-to/` | +| Knowledge wiki | Архитектура personal-os, схема БД | `wiki/` | + +### Что не работает + +- **Граф пустой** — 90% заметок без frontmatter, aliases, wikilinks. Поиск находит только по точному имени файла. +- **Воркер переименовал файлы** без aliases → `✅ Список дел` → `todo-list.md`, поиск сломан. +- **Wiki-curation делает лишнее** — Task 3b (раскладка файлов по папкам) не относится к Karpathy, добавлен ошибочно. +- **Нет накопления знаний** — каждый research-сеанс начинается с нуля. Пример: анализ Obsidian PKM занял 15 минут и 10+ web запросов, которые нужно будет повторять снова. +- **Нет проактивных исследований** — агент реагирует на запросы, не инициирует изучение пробелов. + +--- + +## Часть 2 — Анализ подходов из research + +### Karpathy LLM Wiki (оригинал, апрель 2026) + +**Суть:** LLM читает сырые источники → строит wiki с entity/concept pages → cross-references → compounding knowledge base. Человек почти не пишет в wiki руками. + +**Ключевые цифры:** Karpathy вырастил wiki на одну тему до ~100 статей, 400k слов, не написав ни одной напрямую. Tom Nguyen (6 месяцев в production): 77 wiki pages, 30+ источников, 13 custom skills читают из wiki. + +**Три операции:** +1. **Ingest** — дропаешь источник, агент создаёт/обновляет 10-15 wiki pages +2. **Query** — агент читает index.md, находит нужные pages, даёт ответ со ссылками +3. **Lint** — проверка orphan pages, противоречий, stale claims, пробелов + +**Применимость к нам:** Wiki для накопления knowledge (техника, workflows, инфраструктура, AI tools) — да. Для личных списков — нет. + +--- + +### LLM Wiki v2 (rohitg00) — production extensions + +**Ключевые расширения:** + +**4-tier memory pipeline:** +``` +Working Memory → сырые наблюдения текущей сессии +Episodic Memory → сжатые саммари сессий +Semantic Memory → кросс-сессионные факты (wiki) +Procedural Memory → паттерны, workflows, skills +``` + +**Confidence scoring:** каждый факт имеет score (кол-во источников, свежесть, противоречия). Устаревает со временем, усиливается при подтверждении. + +**Event-driven automation:** +``` +On new source → auto-ingest, extract entities, update graph +On session end → compress session into observations, file insights +On query → check if answer worth filing back +On schedule → periodic lint, consolidation +``` + +**Кристаллизация:** завершённые debug/research сессии автоматически дистиллируются в wiki pages. + +--- + +### claude-obsidian / Ar9av/obsidian-wiki — автономные skills + +Наиболее зрелые production реализации. Ключевые skills: + +**`wiki-synthesize`** — сканирует vault, находит concept pairs которые часто co-occur но не имеют synthesis page. Строит `Concept A × Concept B` pages автоматически. + +**`wiki-research` (3-round autonomous loop):** +- Round 1: decompose topic → 3-5 angles → broad search +- Round 2: find gaps/contradictions → targeted search +- Round 3: resolve contradictions → synthesis + +**`wiki-capture`** — конвертирует AI-human сессии в declarative wiki notes. Эта сессия (анализ Obsidian PKM) должна была бы стать wiki pages автоматически. + +**`autoresearch` (claude-obsidian):** +``` +/autoresearch topic +→ Round 1: query wiki → identify gaps → ingest sources +→ Round 2: re-query → find remaining gaps → more sources +→ Round 3: synthesis → comprehensive result with citations +``` + +**Session hooks:** +- `SessionStart` → load hot cache, read schema +- `PostToolUse` → auto-commit if files changed +- `Stop` → save final state, update manifest + +--- + +### Knowledge Graph extension (Nodus Labs) + +Добавляет структурную самоосознанность поверх Karpathy: + +**Gap detection:** находит disconnected clusters в wiki graph. Там, где два тематических кластера не связаны — это часто место для нового insight или исследования. + +**Prompt-to-structure:** вместо "объясни X" → "как A связан с B, учитывая что они в разных кластерах?" → более точные, оригинальные ответы. + +--- + +### Проактивные исследования — PersonalAgent pattern (arxiv 2512.15302) + +**Идея:** агент строит user profile → из профиля выводит гипотезы что пользователю может быть интересно → инициирует исследования без запроса. + +**Применительно к нам:** агент знает что ты работаешь над personal-os, media-pipeline, executor — и проактивно исследует смежные темы: новые подходы к orchestration, медиа-библиотеки, home automation. + +**Реализация:** weekly cron который читает wiki + профиль + последние сессии → формирует список hypothesis → запускает `wiki-research` по каждой → результаты в inbox для review. + +--- + +## Часть 3 — Что реально нужно нам + +### Три разных задачи (не смешивать!) + +**Задача A: Vault enrichment** — сделать личные заметки searchable и связными +- frontmatter + aliases на существующие файлы +- wikilinks между связанными заметками +- MOC/index files для навигации + +**Задача B: LLM Wiki для knowledge accumulation** — накапливать research результаты +- `wiki/` как compounding knowledge base +- Research сессии → wiki pages +- Lint + gap detection + +**Задача C: Проактивные автономные исследования** — агент сам генерирует гипотезы и исследует +- User profile → hypothesis generation +- Scheduled research runs +- Results → inbox для review + +--- + +## Часть 4 — План: три проекта + +### Проект 1: Vault Enrichment + +**Цель:** граф живой, поиск работает по aliases, Dataview агрегирует, файлы связаны по смыслу. + +#### Ключевой принцип: topic map как источник правды + +`family/index.md` и `personal/index.md` — это не просто каталоги файлов, а **топик-карты vault**. + +Карта содержит: +- Топики / кластеры (Алтай, Лаки Парк, Kraken, psychologist-app, …) +- Какие файлы принадлежат каждому кластеру +- Ссылку на hub-note кластера (основную заметку) + +**Enrichment воркер читает карту первым делом и работает по ней** — не по хардкоду в промпте. Если находит новый кластер которого в карте нет — добавляет его туда сам. Карта самодополняется. + +``` +family/index.md (topic map) + ├── ## Место: Алтай + │ hub: family/places/altai.md (создать при необходимости) + │ files: altai-shopping, altai-house-inventory + ├── ## Место: Лаки Парк (Тайга) + │ hub: family/how-to/truenas-infrastructure.md + │ files: lerua-shopping, fasteners-nomenclature + ├── ## Инфраструктура: Kraken + │ hub: family/how-to/kraken-access.md + │ files: kraken-portainer-access, openmediavault-rpi5, … + └── … +``` + +#### Шаги + +1. ✅ Убрать Task 3b из wiki-curation промпта — **сделано 2026-05-16** +2. ✅ Добавить frontmatter + aliases на 24 файла documents/ — **сделано 2026-05-16** +3. ✅ Создать enrichment cron (воскресенье 03:00) — **запущен 2026-05-16** +4. **Пересобрать `family/index.md` и `personal/index.md` как топик-карты** (кластеры вместо плоских списков) +5. **Обновить промпт enrichment воркера**: читать index как карту, линковать по ней, дополнять при находке новых кластеров — **никакого хардкода в промпте** +6. Создать `personal/places/` и `family/places/` hub-notes для физических мест если нужны (Алтай, Лаки Парк) + +**Стек:** Hermes cron + obsidian MCP + terminal toolset + +**Правило:** воркер **никогда** не хардкодит конкретные файлы или топики в промпте. Карта = единственный источник правды о кластерах. + +--- + +### Проект 2: LLM Wiki — Knowledge Accumulation + +**Цель:** каждая research-сессия накапливается. Следующий вопрос про memory architectures → читаю 2 страницы wiki вместо 10 web запросов. + +#### Компоненты + +**Crystallization** — сессии → wiki pages (ежедневно в wiki-curation-daily) +- Воркер сканирует дневные сессии +- Критерий: знание painful to re-derive + fit wiki domain +- Дистиллирует факты (не разговор), создаёт/обновляет wiki pages +- ✅ Добавлено в wiki-curation-daily промпт (2026-05-16) + +**Wiki-Synthesize** — co-occurring concepts → synthesis pages +- Воркер ищет темы из 3+ страниц без synthesis page +- Создаёт `comparisons/A-vs-B.md` или `concepts/A-and-B.md` +- Лимит: 1 страница за прогон +- ✅ Добавлено в wiki-curation-daily промпт (2026-05-16) + +**Inbox drop** — быстрый путь добавить knowledge в очередь +- Файл в `wiki/raw/inbox/research-SLUG-YYYYMMDD.md` → обрабатывается следующей ночью +- ✅ Сегодняшняя сессия (vault strategy + memory architecture) заброшена в инбокс + +#### Что войдёт в wiki +AI/ML memory architectures, Obsidian PKM patterns, personal-os architecture decisions, Swift/iOS patterns, media pipeline learnings, enrichment patterns. + +**Стек:** wiki-curation-daily (расширенный) + inbox mechanism + +**Статус:** ✅ Реализован 2026-05-16 + +--- + +### Проект 3: Proactive Research Agent + +**Цель:** агент сам инициирует исследования исходя из профиля и пробелов в wiki. + +#### Архитектура + +``` +Gap Detector (читает vault, находит темы без wiki-страниц) + ↓ +research-queue.md (приоритизированный список) + ↓ +proactive-research cron (суббота 05:00, 1 тема за прогон) + ↓ +3-round research loop → wiki page + ↓ +queue item помечается [x], wiki/index.md обновляется +``` + +#### Компоненты + +**research-queue.md** (`wiki/research-queue.md`) +- Живой список тем для исследования +- Воркер берёт top-1 `[ ]` item каждую субботу +- Alex может добавлять вручную +- ✅ Создан с 7 начальными темами (2026-05-16) + +**proactive-research cron** (суббота 05:00) +- Gap detection: темы 3+ упоминаний в vault без wiki-страницы → добавляет в queue +- 3-round research loop: broad → deep → synthesis +- Создаёт/обновляет wiki page, обновляет index.md, отмечает queue item +- ✅ Cron создан (job: 41896d17f5fc, 2026-05-16) + +**Начальная очередь:** +- Obsidian Bases vs Dataview 2026 +- Skip.tools production-readiness +- Home Assistant + Zigbee для RPi5 +- AI mental health apps landscape +- Swift Concurrency 2026 +- Personal OS orchestration alternatives +- Indie iOS monetization 2026 + +**Статус:** ✅ Инфраструктура создана 2026-05-16. Первый прогон: 2026-05-23. + +--- + +### Проект 4: Cross-domain Enrichment Agent + +**Цель:** vault note + external signal → personalized insight. Два режима: разовое обогащение и регулярный мониторинг. + +#### Архитектура + +``` +Enrichment: Vault note + External (web) → companion note рядом с исходником +Monitoring: External stream → фильтр через user-profile → digest delivered +``` + +**vault-cross-enrichment cron** (воскресенье 04:00, web+file+terminal toolsets) +- Target discovery: `enrich-me` тег, файлы 30+ дней без обновления, app-ideas +- Enrichment types: app-ideas competitive analysis, wishlists (games/books/movies), travel, home automation +- Profile-aware: всё фильтруется через `wiki/user-profile.md` +- Output isolation: результат в `-enriched.md` companion файле, исходник не трогает +- Monitoring digest: tech stack updates, indie/App Store news, Bishkek local +- ✅ Cron создан (job: f3de00040aac, 2026-05-16) + +--- + +## Часть 5 — Последовательность + +``` +Сейчас → Проект 1 (enrichment) — быстро, ощутимый результат + ↓ + Проект 2 (wiki accumulation) — параллельно или после + ↓ + Проект 3 (proactive research) — когда wiki достаточно наполнена +``` + +Проект 3 имеет смысл только когда в wiki есть достаточно контента чтобы gap detection давал сигнал. Сначала нужно наполнить wiki (Проект 2). + +--- + +--- + +## Часть 5a — Паттерн: Personal Context → External Signal → Insight + +Это отдельный класс задач — **cross-domain enrichment с внешними данными**. Агент читает личные данные из vault, учитывает профиль пользователя, обогащает внешними сигналами и возвращает персонализированный результат. + +**Ключевое отличие от Google:** контекст про тебя уже внутри — агент не ищет абстрактный ответ, а фильтрует под конкретного человека. + +### Общий паттерн + +``` +Заметка/список в vault + + Связанные заметки (через wikilinks / поиск) + + User Profile (возраст, интересы, текущий стек, предпочтения) + + External signal (web, API, RSS, marketplace) + ↓ +Enrichment Agent (по триггеру или расписанию) + ↓ +Enriched note в vault (insights + cross-links + источники) +``` + +### Два режима агента + +Примеры выше делятся на два разных паттерна — важно не смешивать: + +**Enrichment** — обогащаешь данные один раз (или при изменении) +- Исходная заметка есть, нужно добавить внешний контекст +- Запускается по триггеру (новая запись) или периодически +- Результат стабилен, обновляется редко +- _Примеры: анализ идей приложений, learning path по списку книг, фильтрация игр под профиль_ + +**Monitoring** — следишь за потоком внешнего мира, фильтруешь через твой контекст +- Внешний мир меняется, vault — точка отсчёта для фильтрации +- Запускается регулярно (ежедневно / еженедельно) +- Результат — дайджест / алерт, не постоянная заметка +- _Примеры: новые заведения в Бишкеке, распродажи билетов под планы поездок, конференции по твоим темам, апдейты инструментов из стека_ + +``` +Enrichment: Vault (данные) + External (контекст) → Enriched note в vault +Monitoring: External (поток) → фильтр через Vault (профиль) → Алерт / Дайджест +``` + +Оба нужны, но реализуются по-разному: enrichment — разовый агент с obsidian MCP, monitoring — регулярный cron с web toolset и доставкой в inbox/Zulip. + +### Иллюстративные примеры (не задачи, а цепочки мышления) + +**1. Список идей приложений → конкурентный анализ** +Читает каждую идею → ищет по YC directory / ProductHunt / web по ключевым словам → кто уже делает, funding, незакрытые ниши → сохраняет анализ рядом с идеей + +**2. Активности с ребёнком × список игр × профиль ребёнка** +Читает списки активностей + игр → читает профиль (возраст, интересы, темперамент, что работает) → cross-links между файлами → фильтрует игры под совместную игру → ищет новые по интересам → персонализированные рекомендации с обоснованием + +**3. Список для чтения → learning path** +Книги/статьи + текущие знания из wiki → определяет prerequisites, оптимальный порядок, находит пробелы в теме + +**4. Wishlist путешествий → план поездок** +Список мест + сезонность + текущие проекты (когда реально есть время) → какие места удобно совмещать, оптимизированный план на год + +**5. Профили контактов → напоминания о связи** +Список людей с датой последнего общения + интересы → "давно не писал X, вот повод" (вышла статья по его теме, etc.) + +**6. Wishlist умного дома → совместимость и реализация** +Хотелки + текущий стек (Zigbee, HA версия) → что реально интегрируется, community-решения, очерёдность + +**7. Дневник тренировок → инсайты** +Лог активностей + самочувствие + погода → что коррелирует с хорошими результатами, когда лучше тренироваться + +**8. Скетчи музыкальных идей → рыночный контекст** +Заметки по трекам (BPM, настроение, референсы) → Spotify анализ похожих, что в тренде в жанре + +**9. Список подарков → актуальные варианты** +Профили близких (интересы, что уже есть) × ближайшие даты → marketplace search с обоснованием почему подходит + +**10. Wishlist ресторанов → фильтр по контексту** +Список + предпочтения + что уже посетил → фильтр под конкретный контекст (с ребёнком / романтический / деловой), актуальные часы + +**11. Темы для изучения → дайджест новостей** +Список интересующих тем → еженедельный дайджест из HN / arxiv / RSS, отфильтрованный от шума под твои конкретные темы + +**12. Финансовый watchlist → контекст для решений** +Список активов/инструментов → агрегация сигналов (не трейдинг, а понимание контекста для своих решений) + +**13. Проекты и интересы → конференции, семинары, learning events** +Текущие рабочие и личные проекты + домены интереса → поиск конференций, митапов, онлайн-курсов, воркшопов по теме → дайджест "что скоро, что стоит посетить" с приоритизацией по релевантности + +**14. Планы поездок × текущее местоположение → акции на билеты и туры** +Wishlist мест + даты отпуска (если есть) + текущий город → поиск распродаж, горящих туров, пакетов (не только авиа) → алерт когда появляется подходящее предложение + +**15. Контакты → дни рождения и поводы** +Профили людей с датами рождения + история общения → заблаговременное напоминание + идея подарка по интересам человека + +**16. Проекты и интересы → новые идеи, best practices, апдейты инструментов** +Текущий технический стек + активные проекты → мониторинг HN / changelog / блогов → "вышел X, релевантно для твоего проекта Y", "новый паттерн для Z", "есть решение лучше чем то что ты сейчас используешь" + +**17. Место проживания → новые заведения и места** +Текущий город + категории интереса (рестораны, кофейни, etc.) → мониторинг новых открытий → периодический дайджест "что открылось, что стоит попробовать" + +### Триггеры обогащения + +1. **По изменению** — новая запись в списке → автоматически запускает анализ (git diff) +2. **По расписанию** — раз в неделю проходит по спискам, обновляет что устарело +3. **По запросу** — "проведи анализ по этой теме" + +--- + +### Проект 5: Memory Organizer + +**Цель:** память агента актуальна, не переполнена, детальные факты живут в vault а не в MEMORY.md. + +#### Контекст + +Hermes хранит память в двух файлах (`~/.hermes/memories/`): + +| Файл | Назначение | Лимит | +|---|---|---| +| `MEMORY.md` | Факты об окружении, проектах, инструментах | ~3000 chars | +| `USER.md` | Профиль пользователя — предпочтения, стиль | ~1375 chars | + +Оба инжектируются в system prompt **как frozen snapshot** при старте сессии. Агент видит их как часть контекста. + +**Три уровня памяти** (по когнитивной науке, arXiv 2603.07670): +- **Episodic** — сессионные логи (SQLite, session_search). Уже работает. +- **Semantic** — факты/предпочтения (MEMORY.md + USER.md). Нужна curation. +- **Procedural** — навыки и workflows (skills/). Уже работает. + +**Текущие проблемы (2026-05-16):** +- MEMORY.md переполнен — 3164 chars при лимите ~3000 +- 8 записей про media-pipeline баги/§9.x/транслит — это детальные технические заметки, а не факты для быстрого доступа. Должны жить в `wiki/tech/` или в project notes. +- Нет механизма устаревания — записи про баги давно пофикшенные продолжают занимать место +- Нет связи memory ↔ vault: детальный контекст дублируется, не синергирует + +#### Правило разграничения (что куда) + +``` +MEMORY.md → короткие стабильные факты: SSH хосты, namespace rules, + активные токены, конфиги. Макс ~150 chars на запись. +USER.md → предпочтения, стиль, ожидания. Не меняется часто. +wiki/tech/ → детальные технические заметки: питфолы, баг-паттерны, + разборы архитектур. Длинные, с контекстом. +personal/projects/ → статус проектов, решения, дебаггинг-логи +skills/ → процедуры и workflows пошагово +``` + +**Overflow pattern:** если запись в MEMORY.md > 150 chars или содержит пошаговые инструкции → переносим в vault, в MEMORY.md оставляем pointer: `media-pipeline питфолы → wiki/tech/media-pipeline.md` + +#### Шаги + +**Шаг 0 — One-time audit & purge (сейчас)** +1. Пройти по всем записям MEMORY.md +2. Записи про media-pipeline (bugs, §9.x, транслит, KP rate limit, Docker cmd) → создать `wiki/tech/media-pipeline-pitfalls.md`, в MEMORY.md оставить короткий pointer +3. Удалить записи про пофикшенные баги (они уже в истории сессий) +4. Проверить USER.md — убрать устаревшее +5. После: MEMORY.md < 2000 chars, USER.md < 1100 chars (оставить запас для новых фактов) + +**Шаг 1 — Создать `wiki/tech/` как хранилище детальных техфактов** +- `wiki/tech/media-pipeline-pitfalls.md` — все §9.x, транслит, баги +- `wiki/tech/kraken-infra.md` — SSH, WireGuard, Docker deploy паттерны +- `wiki/tech/gitea.md` — токены, repos, API endpoints +- Эти страницы живут в wiki (curation воркер их maintainит) + +**Шаг 2 — Memory curation cron (еженедельно, воскресенье 04:00)** + +``` +Читает ~/.hermes/memories/MEMORY.md и USER.md + ↓ +Для каждой записи: + - Старше 60 дней И не изменялась → кандидат на архивацию + - > 150 chars → кандидат на перенос в vault + - Противоречит другой записи → флажок для review + ↓ +Детальные записи → переносит в wiki/tech/ (создаёт/обновляет страницы) +В MEMORY.md → заменяет на pointer (1 строка) +Совсем устаревшие (проект завершён) → удаляет + ↓ +Репортирует: что удалено, что перенесено, текущий % заполненности +``` + +**Стек:** Hermes cron + terminal + obsidian MCP + +**Оценка:** Шаг 0 — 30 мин сейчас. Шаг 1-2 — 1 день. + +--- + +## Статус проектов (2026-05-16) + +| Проект | Статус | Следующий шаг | +|---|---|---| +| Проект 1: Vault Enrichment | 🟡 В процессе | Воскресный прогон по топик-картам | +| Проект 2: LLM Wiki Accumulation | ✅ Готов | crystallization + synthesize + inbox в wiki-curation | +| Проект 3: Proactive Research | ✅ Готов | research-queue.md + cron суббота 05:00 | +| Проект 4: Cross-domain Enrichment | ✅ Готов | vault-cross-enrichment cron воскресенье 04:00 | +| Проект 5: Memory Organizer | 🟡 В процессе | daily cron 04:00; wiki/tech/ частично заполнена | + +### Что сделано (2026-05-16) +- Task 3b убран из wiki-curation +- frontmatter + aliases + titles на 24 файла documents/ +- Enrichment воркер создан (воскресенье 03:00) +- wiki/tech/media-pipeline-pitfalls.md создан +- MEMORY.md разгружена: 105% → 50% + +### Известные долги +- ❗ `wiki/tech/` не отражена в `wiki/index.md` и `wiki/SCHEMA.md` +- ❗ `family/index.md` и `personal/index.md` — плоские списки, не топик-карты +- ❗ Memory curation cron не создан (только описан в плане) + +--- + +## Что НЕ нужно делать + +- ❌ Task 3b в wiki-curation (убрать) ✅ сделано 2026-05-16 +- ❌ Переименовывать файлы с кириллицей/эмодзи +- ❌ Применять Karpathy-wiki к личным спискам (разные задачи) +- ❌ Глубже вкладывать папки +- ❌ Внешние сервисы (LifeOS plugin, Todoist) — у нас есть Asana + Hermes +- ❌ Хранить в MEMORY.md записи > 150 chars — детали → в vault + +--- + +## Ссылки + +- [Karpathy LLM Wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) +- [LLM Wiki v2 — rohitg00](https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2) +- [claude-obsidian](https://pyshine.com/2026/04/claude-obsidian-self-organizing-ai-knowledge-engine/) +- [Ar9av/obsidian-wiki skills](https://deepwiki.com/Ar9av/obsidian-wiki/3.5-knowledge-building-skills) +- [Nodus Labs knowledge graph](https://support.noduslabs.com/hc/en-us/articles/26724863249180) +- [mathisgauthey vault template](https://github.com/mathisgauthey/obsidian-workflow-template) +- [MOC + Dataview guide](https://github.com/seqis/ObsidianMOC) + +--- + +## Связанные заметки +- [[personal/projects/personal-os/personal-os-architecture|Personal OS Architecture]] +- [[personal/projects/personal-os/executor-security-analysis|Executor Security Analysis]] diff --git a/personal/knowledge/obsidian/reference/research-queue.md b/personal/knowledge/obsidian/reference/research-queue.md new file mode 100644 index 00000000..5f88fc92 --- /dev/null +++ b/personal/knowledge/obsidian/reference/research-queue.md @@ -0,0 +1,20 @@ +--- +title: Research Queue +updated: '2026-10-14' +type: meta +--- + +# Research Queue + +> Topics detected as gaps in the wiki — mentioned in vault but no wiki page. +> Ordered by priority. Completed items move to ## Completed with link + date. + +## Queue + +(empty) + +## Completed + +- [x] WireGuard VPN → [[family/how-to/wireguard-vpn]] (2026-05-23) +- [x] Executor Architecture v2 → [[personal/projects/personal-os/executor-orchestrator-redesign]] (2026-05-19) +- [x] Executor Security Incident → [[personal/projects/personal-os/executor-security-analysis]] (2026-05-22) diff --git a/personal/knowledge/obsidian/reference/vault-agent-integration.md b/personal/knowledge/obsidian/reference/vault-agent-integration.md new file mode 100644 index 00000000..32819d4d --- /dev/null +++ b/personal/knowledge/obsidian/reference/vault-agent-integration.md @@ -0,0 +1,84 @@ +--- +title: Vault ↔ Agent Integration +created: '2026-05-23' +updated: '2026-05-23' +type: concept +namespace: work +tags: [vault, obsidian, wiki, ingest, mcp, hermes, system, architecture] +sources: [wiki/obsidian-mcp-wrapper.md, wiki/wiki-ingest-process.md, wiki/personal-os-architecture.md, wiki/vault-filling-guide.md] +confidence: high +--- + +# Vault ↔ Agent Integration + +How Eagle, wiki-ingest, and the obsidian-mcp-wrapper work together as a +unified knowledge layer. Three distinct subsystems each own a slice of +the vault. + +## The Three Subsystems + +### 1. obsidian-mcp-wrapper (runtime read/write) + +A Node.js proxy (`~/scripts/obsidian-mcp-wrapper.js`) wraps `obsidian-mcp` +to fix four production bugs: ZodError on init, race condition at gateway +restart, UTF-8 chunk corruption on large payloads, and a 5-second watchdog +for hung child processes. + +Eagle reads the vault through this wrapper via MCP tool calls. It can search, +read, and write notes in real time during conversations. + +**Allowed write paths** (Eagle only, with prior draft shown): +- `work/projects/`, `work/decisions/`, `personal/`, `family/` +- Never `wiki/` — that's wiki-ingest territory + +### 2. wiki-ingest (nightly synthesis, 22:00 launchd) + +A `claude -p` session (not Hermes) that runs nightly. It reads files in +`~/obsidian/raw/` (symlinks to external project files), computes SHA256 +hashes, and synthesises wiki pages only when the source has changed. + +**Invariants:** +- Output is synthesis, never verbatim copy +- Frontmatter `source` + `content_hash` are the ingestion contract +- Pages with `confidence: 1.0` are immutable + +### 3. wiki-curation (daily Hermes cron, 02:00) + +A Hermes cron job (this script) that maintains the wiki as a compounding +knowledge base: processes inbox, crystallises session knowledge, creates +synthesis pages, lints orphans and broken links. + +## Division of Labour + +| Layer | Tool | Vault path | Trigger | +|-------|------|-----------|---------| +| Reactive reads/writes | obsidian-mcp-wrapper | `work/`, `personal/`, `family/` | On-demand | +| Source synthesis | wiki-ingest (claude -p) | `wiki/` ← `raw/` | 22:00 nightly | +| Knowledge curation | wiki-curation (Hermes cron) | `wiki/` | 02:00 daily | +| Vault sync | sync-vault.sh | entire vault | Hourly | + +## Why obsidian-mcp Is Wrapped + +The wrapper exists because `obsidian-mcp` v1.0.6 had four production-breaking +bugs that would have been too fragile to fix upstream (updates would reintroduce +them). A proxy wrapper is cleaner: it intercepts the MCP protocol stream without +modifying the underlying package. + +See [[obsidian-mcp-wrapper]] for the four bugs and their fixes. + +## Vault Sync (Eagle ↔ Taiga ↔ Kraken) + +All three nodes share a sparse vault via a TrueNAS bare git repo. Eagle has +the full vault; Kraken and Taiga have `personal/` and `family/` only (sparse +checkout). The `sync-vault.sh` cron runs hourly on all three. + +``` +Eagle (full) ──push/pull──┐ +Taiga (sparse) ────────────├── mallexxx.duckdns.org:/mnt/RED_2TB/storage/git/obsidian-vault.git +Kraken (sparse) ───────────┘ +``` + +## See Also + +[[obsidian-mcp-wrapper]] [[wiki-ingest-process]] [[vault-filling-guide]] +[[personal-os-architecture]] diff --git a/personal/knowledge/obsidian/reference/vault-filling-guide.md b/personal/knowledge/obsidian/reference/vault-filling-guide.md new file mode 100644 index 00000000..8cdba0cf --- /dev/null +++ b/personal/knowledge/obsidian/reference/vault-filling-guide.md @@ -0,0 +1,78 @@ +--- +namespace: work +tags: [system, vault, guide] +last_synced: 2026-04-27 +confidence: 1.0 +--- + +# Vault Filling Guide + +How to populate `~/obsidian/`. Eagle can write to any section below except `wiki/` and `raw/`. + +## Directory Map + +``` +~/obsidian/ +├── wiki/ ← LLM-generated ONLY (wiki-ingest). Never write here manually. +├── raw/ ← Symlinks to external files ONLY. Never write content here. +├── work/ ← Alex's work notes. Eagle can write with confirmation. +│ ├── projects/ One file per active project. +│ ├── decisions/ Architectural/process decisions with date prefix. +│ └── tech-design/ References to designs, review notes. +├── personal/ ← Alex's personal notes. Eagle can write with confirmation. +│ ├── documents/ WHERE docs live (not the docs themselves). +│ ├── instructions/ Personal how-tos and procedures. +│ └── projects/ Personal side projects. +└── family/ ← Household knowledge. Eagle can write with confirmation. + ├── how-to/ Practical guides (devices, home equipment, procedures). + ├── documents/ WHERE family documents live. + ├── contacts/ Emergency contacts, doctors, services. + └── schedule/ Recurring schedules, school, events. +``` + +## File Naming + +- `work/projects/` → `kebab-case-project-name.md` (e.g. `ios-duck-ai-toggle.md`) +- `work/decisions/` → `YYYY-MM-topic.md` (e.g. `2026-04-personal-os-arch.md`) +- `family/how-to/` → `kebab-case-topic.md` (e.g. `truenas-access.md`, `router-reset.md`) +- `family/contacts/` → `emergency.md`, `doctors.md`, `services.md` +- `family/documents/` → `apartment.md`, `insurance.md`, `passports.md` (location pointers, not the files) + +## Frontmatter + +Every file should have: +```yaml +--- +namespace: work | personal | family +tags: [tag1, tag2] +created: YYYY-MM-DD +updated: YYYY-MM-DD +--- +``` + +## What Goes Where + +| Info type | Location | +|-----------|----------| +| Active work project status, decisions, links | `work/projects/SLUG.md` | +| "We decided X because Y" (architectural) | `work/decisions/YYYY-MM-TOPIC.md` | +| Home network / NAS / router config | `family/how-to/DEVICE.md` | +| Where passport/insurance/lease is stored | `family/documents/TOPIC.md` | +| Emergency contacts, doctors | `family/contacts/CATEGORY.md` | +| Recurring events, school schedule | `family/schedule/TOPIC.md` | +| Personal project notes | `personal/projects/SLUG.md` | +| Personal procedures (backups, etc.) | `personal/instructions/TOPIC.md` | + +## Eagle Write Protocol + +1. Show draft content before writing (never silently create) +2. Confirm namespace (`work` / `personal` / `family`) +3. Write the file +4. Run `cd ~/obsidian && git add -A && git commit -m "..."` to save + +## What Eagle Should NOT Do + +- Write anything to `wiki/` — that's wiki-ingest's job +- Modify `raw/` — those are symlinks managed manually +- Create files without showing the content first +- Overwrite existing files without showing a diff diff --git a/personal/knowledge/obsidian/reference/vault-namespace.md b/personal/knowledge/obsidian/reference/vault-namespace.md new file mode 100644 index 00000000..f175b213 --- /dev/null +++ b/personal/knowledge/obsidian/reference/vault-namespace.md @@ -0,0 +1,35 @@ +--- +title: Vault Namespace Rules +created: '2026-05-23' +updated: '2026-10-14' +type: tech +namespace: personal +tags: [vault, meta, conventions] +related: + - "[[vault-filling-guide]]" +--- + +# Vault Namespace Rules + +Rules for where notes live in the Obsidian vault. See also [[personal/projects/personal-os/wiki-schema]] for +full frontmatter conventions. + +## Namespace Assignments + +- `personal`: Eagle infra, personal projects, dev tooling +- `family`: Kraken media stack, HTPC, Jellyfin, family content +- `work`: DuckDuckGo / DDG tasks and tooling + +## Directory Map + +``` +wiki/concepts/ — how-it-works explanations +wiki/tech/ — infra how-tos, tool configs, pitfalls +wiki/ideas/ — speculative, not yet decided +personal/projects/ — project status & decisions +family/projects/ — family-shared project status +family/how-to/ — family infra procedures +``` + +Note: this file was reconstructed from a lost pointer. Extend with actual +rules as they emerge. diff --git a/personal/knowledge/obsidian/reference/wiki-ingest-process.md b/personal/knowledge/obsidian/reference/wiki-ingest-process.md new file mode 100644 index 00000000..5e801b25 --- /dev/null +++ b/personal/knowledge/obsidian/reference/wiki-ingest-process.md @@ -0,0 +1,100 @@ +--- +source: raw/wiki-ingest-prompt.md +content_hash: 29f6a0914d428cf62eeb2a832d6b3048edf3e1d16aa7714c09f686377394d128 +namespace: work +last_synced: 2026-04-27 +confidence: 0.9 +tags: [wiki, ingest, agent, prompt] +--- + +# Wiki Ingest Process + +The agent prompt that maintains `~/obsidian/wiki/` as a synthesised +knowledge base over external project files exposed via symlinks in +`~/obsidian/raw/`. Run locally by `claude -p` (the launchd job +`run-wiki-ingest.sh` at 22:00) — not via API, because file-system +writes require a local Claude Code session. See +[[personal-os-architecture]] for where this fits in the broader system. + +## Discovery loop + +For every file in `~/obsidian/raw/`: + +1. Read the file (skip if the symlink target is missing). +2. Compute SHA256 with `shasum -a 256`. +3. Look for a wiki page whose frontmatter has `source: raw/`. +4. If a page exists and its `content_hash` already matches, skip. +5. Otherwise enqueue for synthesis. + +If nothing changed, the agent prints +"Wiki is up to date. Nothing to ingest." and exits. + +## Synthesis rules + +- Wiki pages are named by **topic**, not source filename + (e.g. `personal-os-schema.md`, not `schema.md`). +- Output is a **synthesis**, never a verbatim copy. Extract facts, + decisions, and structure. Hard cap of 800 words per page; split + into linked pages if the topic is larger. +- Use `[[double brackets]]` for cross-references between wiki pages. + +## Page format + +Frontmatter is the source of truth for incremental ingestion: + +```yaml +source: raw/ +content_hash: +namespace: work +last_synced: +confidence: 0.8 +tags: [tag1, tag2] +``` + +Body has a title, synthesis prose, a `## Key Points` list, and a +`## Related` line of `[[wiki-links]]`. + +## Confidence ladder + +- **1.0** — reserved for human-written notes in `work/`, `personal/`, + `family/`. The agent must never edit these files. +- **0.9** — highly structured / authoritative source (e.g. a schema). +- **0.8** — clear single source. Default. +- **0.6** — inferred or partial content. + +## Hard rules + +- Never copy source files verbatim — always synthesise. +- Never edit any file with `confidence: 1.0`. +- Never process files in `namespace: family` unless explicitly told. +- Always update `content_hash` and `last_synced` after writing a page. +- Skip broken symlinks; do not create a wiki page for them. + +## Reporting + +After the run, the agent emits a summary: + +``` +Wiki Ingest — + +Processed: N files +Created: N new pages +Updated: N pages +Skipped: N (unchanged) + +Pages updated: +- wiki/ (source: raw/) +``` + +## Key Points +- Hash-based incremental: re-runs are cheap when nothing changed. +- Topic-named pages decouple the wiki from source-file naming. +- Frontmatter `source` + `content_hash` is the ingestion contract; + the [[personal-os-schema]] mirrors the same idea in `wiki_pages`. +- Human-edited (confidence 1.0) pages are immutable to the agent — + the trust boundary between synthesis and curated knowledge. +- Local-only execution: writes to `~/obsidian/` need a real FS, + so the job runs under launchd via `claude -p`, not the API. + +## Related +[[personal-os-architecture]] [[personal-os-schema]] diff --git a/personal/knowledge/obsidian/reference/wiki-schema.md b/personal/knowledge/obsidian/reference/wiki-schema.md new file mode 100644 index 00000000..e5788d9b --- /dev/null +++ b/personal/knowledge/obsidian/reference/wiki-schema.md @@ -0,0 +1,125 @@ +--- +title: Wiki Schema +created: '2026-05-13' +updated: '2026-05-25' +type: meta +--- + +# Wiki Schema + +## Domain + +Knowledge base covering Alex's Personal OS ecosystem: the multi-agent +productivity/context system, home infrastructure (Eagle Mac M4, Taiga TrueNAS, +Kraken RPi5), personal projects (Reflect app, etc.), and DuckDuckGo work tooling. + +**In scope:** agent architecture, data pipelines, home infra, dev tooling, +personal projects, vault management. +**Out of scope:** raw Asana tasks, family documents, ephemeral briefs. + +## Conventions + +- File names: lowercase, hyphens, no spaces (e.g., `personal-os-architecture.md`) +- Every wiki page starts with YAML frontmatter (see below) +- Use `[[wikilinks]]` to link between pages (minimum 2 outbound links per page) +- When updating a page, always bump the `updated` or `last_synced` date +- Every new page must be added to `index.md` under the correct section +- Every action must be appended to `log.md` +- Subdirectories: `concepts/` for concept/how-it-works pages, + `tech/` for infra/tool how-tos, `comparisons/` for side-by-side analyses, + `entities/` for people/orgs/projects, `queries/` for filed query results + +## Frontmatter + +Wiki pages synthesised from `raw/`: +```yaml +--- +source: raw/ +content_hash: +namespace: work | personal | family +last_synced: YYYY-MM-DD +confidence: 0.8 +tags: [tag1, tag2] +--- +``` + +Hand-written or agent-synthesised pages: +```yaml +--- +title: Human Readable Title +created: YYYY-MM-DD +updated: YYYY-MM-DD +type: concept | entity | comparison | tech | query +namespace: work | personal | family +tags: [from taxonomy below] +sources: [raw/articles/source.md] +confidence: high | medium | low +--- +``` + +**Confidence ladder:** +- `1.0` / `high` — human-written; agent must never edit these files +- `0.9` — highly structured / authoritative source (schema, infra docs) +- `0.8` / `medium` — single clear source; default for agent synthesis +- `0.6` / `low` — inferred or partial content + +Pages with `confidence: 1.0` are immutable to the wiki-curation agent. + +## Tag Taxonomy + +Personal OS: +- `system` `architecture` `agent` `eagle` `executor` `pipeline` `sync` +- `rules` `self-modification` `meta` `purpose` + +Work / DDG: +- `asana` `ddg` `workflow` `task-management` + +Infrastructure: +- `infra` `kraken` `taiga` `htpc` `docker` `nas` `raspberry-pi` `vps` +- `obsidian` `vault` `wiki` `ingest` +- `media-pipeline` `arr` + +Projects: +- `reflect-app` `psychology` `ios` `android` `skip-tools` +- `project` `startup` + +Technical: +- `schema` `postgres` `database` `mcp` `hermes` +- `debugging` `pitfalls` `how-to` + +Rule: every tag on a page must appear in this taxonomy. Add new tags HERE +before using them. Avoid tag sprawl. + +## Page Thresholds + +- **Create a page** when an entity/concept appears in 2+ sources OR is + central to one source +- **Add to existing page** when a source mentions something already covered +- **DON'T create a page** for passing mentions or things outside the domain +- **Split a page** when it exceeds ~200 lines +- **Never edit** pages with `confidence: 1.0` + +## Update Policy + +When new information conflicts with existing content: +1. Check dates — newer sources generally supersede older ones +2. If genuinely contradictory, note both positions with dates +3. Never silently overwrite — show what changed + +## Directory Structure + +``` +wiki/ +├── SCHEMA.md ← this file +├── index.md ← page catalog +├── log.md ← action log (append-only) +├── *.md ← root-level pages (legacy + core) +├── concepts/ ← how-it-works, design rationale +├── tech/ ← infra/tool how-tos (device-specific) +├── comparisons/ ← side-by-side analyses +├── entities/ ← people, projects, products +├── queries/ ← filed query results +└── raw/ ← immutable sources + ├── inbox/ ← new files to process + └── inbox/processed/ ← after ingestion +``` diff --git a/personal/plans/personal-os-operating-plan-2026-10-03.md b/personal/plans/personal-os-operating-plan-2026-10-03.md index f4bace7f..e813057b 100755 --- a/personal/plans/personal-os-operating-plan-2026-10-03.md +++ b/personal/plans/personal-os-operating-plan-2026-10-03.md @@ -1,212 +1,3 @@ ---- -namespace: personal -tags: - - personal-os - - execution-plan - - focus - - work-life-balance -date: '2026-10-03T00:00:00.000Z' -status: approved-for-implementation -approved_on: '2026-10-03T00:00:00.000Z' -implementation_status: shadow-running -mission: '[[personal/projects/personal-os/personal-os-purpose]]' -updated: '2026-10-04' ---- +# План работ Personal OS -# Personal OS — аудит и план запуска вокруг фокуса - -> План реализации заменён пакетом R2: [[personal/projects/personal-os/personal-os-system-review-index]]. Ниже сохранены история и прежняя постановка; текущий порядок R0–R4, контракты и пороги приёмки находятся в R2. - - -> **Архитектура production v1 пока не согласована.** Выбор Node/TypeScript vs n8n/Node-RED, data flow, контуры планнера/ретроспектора, канал взаимодействия и критерии завершения собраны в [проекте архитектурного решения](/Users/admin/Developer/personal-os/planning/personal-os-architecture-decision-2026-10-04.md). Это предложение для обсуждения; оно не разрешает новые расписания, агентские запуски, миграции или доставку. Утверждённый ранее read-only shadow остаётся в своей прежней границе. - -**Утверждённое решение от 2026-10-03:** сначала запустить контур управления самочувствием, фокусом и посильной нагрузкой Алекса. Его главная проблема сейчас — **рваный фокус**: одновременно идут его задачи и много агентных задач, которые неожиданно возвращаются к нему как ревью/решения. Технические источники дают факты, но само приложение на переднем плане не определяет рабочую тему. Кодинговые агенты — второй контур, ограниченный человеческим временем ревью и токенами. Этот документ заменяет прежнюю версию плана от 2026-10-03, где на первое место ошибочно поставлена техническая надёжность feed. - -**Состояние выполнения на 2026-10-04:** пакеты A–C реализованы для подтверждённых источников; D работает как локальный shadow-фокус с явными `unknown`; E запущен как тихий сбор. `com.personalos.focus-shadow` работает по будням 08:00–20:00 каждые 15 минут; проверка 4 октября: 54 запуска, последний код 0, последний снимок 00:41 +06. Корпоративный Mattermost собирается отдельным read-only клиентом. Zoom: два transcript сохранены, ночной LaunchAgent включён на 02:15, первый запуск по расписанию ещё впереди. Через Balda на Monterey/Xcode 13 запущено создание пустого iPad-проекта; сборка и установка нового приложения не подтверждены. Двухдневная калибровка, ручная проверка 20 интервалов и пользовательский пилот ещё не завершены. Старый Executor, push-уведомления и запись в Asana/GitHub не включены. Миссия: [[personal/projects/personal-os/personal-os-purpose]]. Текущее состояние: [[personal/projects/personal-os/personal-os-status-2026-10]]. - -## 1. Системная задача и критерий пользы - -В каждый момент система поддерживает состояние: **над какой рабочей темой я сейчас занят, какие агентные работы идут параллельно и ждут моего ревью, энергия/настроение (если я их указал), посильная нагрузка и граница рабочего дня, обязательства, встречи, накопившиеся изменения и цена переключения**. Рабочая тема может быть Asana-задачей, ревью PR/Tech Design/Ship Review, планированием, развитием команды, встречей или контролем агента; непосредственный кодинг — лишь один из видов работы. На основе этого система предлагает выполнимый фокус дня, защищает его, помогает вернуться после переключения, пересобирает план и сохраняет карьерные факты. Алекс может в один шаг сменить фокус, снизить нагрузку или отложить предложение. - -Приоритеты строго такие: (1) хорошо себя чувствовать, (2) эффективно распределять нагрузку и фокус, (3) сохранять баланс жизни/работы, (4) выполнять и улучшать рабочие и карьерные результаты. Больший объём работы не компенсирует ухудшение первых трёх целей. ActivityWatch — наблюдение за поведением компьютера, **не датчик самочувствия и не оценка продуктивности человека**. - -### P0: актуальное состояние проектов для всех агентных сценариев - -Аудит к career advisor call 2026-10-04 показал сбой: обсуждённое в Zoom предложение о code-initialized Core Data models было позже отменено, но агент трактовал закрытую Asana-подзадачу и старый разговор как действующий результат. **Первый read-only project-truth analyzer для VSCode/SPM реализован и подключён к shadow** между сбором источников и focus/career/advisor выводом; рабочий JSON-only путь проверен без DB-миграции; playbook для подготовки advisor call создан, вторничная автоматизация на 09:00 включена; первый запуск ещё не проверен. Он различает предложение, решение, отмену, внедрение, проверку и открытый follow-up; хранит время, ссылку, свежесть, confidence и supersedes. При конфликте даёт `unknown` и не выдаёт неподтверждённое внедрение. Первый fixture — [[personal/projects/personal-os/project-truth-analyzer]]: Core Data code-init отменён, существующие модели сохранены под Xcode 27, cleanup открыт. Параллельная калибровка shadow-сбора продолжается; выпуск карьерных claims о проекте зависит от этой проверки. - -### Сигнал раздражения из выгруженных транскриптов агентов — требование Алекса от 2026-10-04 - -**Источником служит выгрузка транскриптов общения Алекса с другими агентами, а не диалог с Personal OS.** Явная грубость или брань в сообщении Алекса агенту — предварительный сигнал раздражения в соответствующем рабочем интервале. Анализировать вместе с темой задачи, повторными неудачами агента и очередью ревью: это может объяснять цену работы и перегрузку. Не превращать сигнал в диагноз, оценку продуктивности или окончательный вывод о самочувствии; явная оценка Алекса имеет приоритет. - -**Контракт реализации:** локально импортировать уже выгруженные транскрипты Codex/Claude/других используемых агентов, отделить сообщения Алекса от ответов агента, извлечь `irritation_signal` с временем, ссылкой на источник и confidence. В производном timeline/focus state хранить метку и ссылку на исходный транскрипт, без дублирования его текста. Проверить резкое обращение, техническую брань о коде и просто короткую команду; последние два случая не должны автоматически означать раздражение. Нынешний `session-observer.js` читает только metadata, поэтому импорт и анализ транскриптов **ещё не реализованы**, а сигнал пока `unknown`. - -**Режим использования:** Personal OS пассивно анализирует выгрузки и учитывает результат при оценке нагрузки и качества работы агентов. В обычной жизни Алекс не ведёт переписку с «агентом Personal OS»; этот сигнал не запускает сообщения, вопросы или вмешательства в момент раздражения. - -### Целевой цикл - -1. **Понимание факта:** собирает временную линию человеческой работы и параллельных агентных задач, связывает рабочую тему с Asana/PR/встречей/worktree по доказательствам; неизвестное оставляет неизвестным. -2. **Понимание спроса и ёмкости:** определяет, что действительно требуется от Алекса, сколько времени/энергии займёт, где возникнет человеческое ревью; вычитает встречи, перерывы, переключения и окончание рабочего дня, учитывает добровольную отметку энергии/настроения. -3. **Выбор фокуса:** предлагает одну основную работу и ограниченное число обязательств, объясняет перенос/делегирование/ожидание остальных; Tech Design, Ship Review, team growth и карьерные дела не исчезают за срочным шумом. -4. **Защита и восстановление:** в фокусе обычные изменения копятся молча, при естественном переходе приходит короткая карточка «где остановился → что изменилось → что дальше». Критическое исключение имеет явное правило и ссылку. -5. **Обратная связь:** Алекс одним действием отмечает полезность/ошибку/перегрузку или меняет план; система измеряет последствия и корректирует правила. Агенты развивают систему только в пределах бюджета внимания и токенов. - -### Два первичных блокера - -**Блокер 1 — достоверность и смысл наблюдений.** Нужна единая модель `временной интервал человека ↔ рабочая тема ↔ конкретный объект Asana/PR/TD/Ship Review/meeting ↔ агентная задача ↔ ожидаемое ревью`. ActivityWatch даёт окна/AFK/переключения, а Asana, browser URL, VS Code/worktree, Codex/Claude, GitHub и Zoom дают смысл. Агент разбирает неоднозначные интервалы, но помечает уверенность и не строит решение на догадке. Первое доказательство: один рабочий день можно восстановить как последовательность реальных тем и агентных ожиданий без выдуманных привязок. - -**Блокер 2 — решение «что надо делать» при ограниченном ресурсе.** Это отдельный анализ поверх фактов: роль и ответственность Алекса, важность для проекта/карьеры/команды, срок и цена ожидания, зависимые люди, доступные окна, энергия, перерывы, стоимость переключения, очередь агентных ревью. Выход — `сейчас / выделить окно / делегировать / ждать / перенести` с причиной и влиянием на баланс. Первое доказательство: в перегруженный день система защищает основной фокус и явно переносит низкоценное агентное ревью, не теряя настоящее обязательство. - -Короткая доставка и обратная связь — следующий этап, который проверяет, что оба блокера действительно решены. Ровный сбор ActivityWatch без семантики рабочей темы не закрывает блокер 1; точная временная линия без выбора посильной работы не закрывает блокер 2. - -### Что проверяем после сбора данных - -Сбор событий — вход в цикл проверки, а не самостоятельная цель. **Первая проверка: можно ли восстановить человеческую рабочую тему и очередь его решений. Вторая: помогает ли предложенный выбор сохранить самочувствие и фокус, не теряя обязательств.** Ниже — гипотезы пилота; пороги уточняются по исходному замеру, а не выдаются за уже доказанный эффект. - -| Гипотеза | Наблюдение и опровержение | Что меняем при ошибке | -|---|---|---| -| H1. ID/URL Asana и PR, worktree/ветка и явное состояние agent run позволяют связать большую часть важных интервалов и ожиданий без угадывания по приложению. | На 20 интервалах из разных типов работы вручную по исходным ссылкам проверяем `work_thread_id`, `actor`, `activity`, `needs_human` и свежесть; считаем долю верных `high-confidence`, долю `unknown`, ложные связи и пропущенные обязательства. Любая уверенная привязка, противоречащая источнику, опровергает правило, давшее её. | Исправить конкретный adapter/binding; снизить confidence; оставить `unknown`. Не повышать confidence только ради покрытия. | -| H2. «Рваный фокус» лучше объясняют переходы **между рабочими темами** и неожиданные agent review/approval, чем число смен приложений. | За два дня сопоставить реальные переходы, время возврата к теме и неплановые запросы с короткой добровольной оценкой «насколько рваным был день» 1–5. Если смены приложений без смены темы считаются прерываниями или оценка не согласуется с наблюдаемыми событиями, модель фрагментации неверна. | Пересмотреть правила границ темы и события прерывания; не оптимизировать счётчик окон. Субъективная оценка не заменяется ActivityWatch. | -| H3. Роли, зависимости, последствия ожидания и доступная ёмкость дают полезнее выбор «сейчас/позже», чем overdue/easiest-first. | На обычном и перегруженном дне в shadow-режиме сравнить предложение с проверенными Asana/PR/meeting обязательствами, свободным временем, перерывами и границей работы. Проверять: нет пропущенного важного действия, нет работы сверх ёмкости, есть причина переноса. Одного неверно названного срочным FYI достаточно для исправления роли. | Исправить извлечение `work_demand` или правило приоритета; явно показать неопределённость. Не повышать срочность из-за одного комментария, красного CI или даты без последствий. | -| H4. Пакетное ревью готовых agent results уменьшает неплановые обращения без накопления действительно срочных решений. | В пятидневном пилоте сравнить число обращений, минуты ревью, возраст очереди и пропущенные сроки с исходным замером. Если обращений меньше, но обязательства теряются или вечер занят ревью, гипотеза не подтверждена. | Изменить reviewer slot, WIP и правило критического исключения; не увеличивать параллельность агентов ради throughput. | -| H5. Добровольная отметка энергии/настроения улучшает посильность плана без дополнительной нагрузки. | Сравнить корректировки в дни с отметкой и `unknown`, частоту «слишком много», самочувствие и время на ввод. Если отметка не даёт пользы или раздражает, убрать запрос и оставить консервативный `unknown`. | Изменить `capacity-model.js`/момент запроса, а не выводить настроение из окна или активности. | - -### Калибровка и исправление правил - -1. **Тихий baseline, два рабочих дня.** Проверить свежесть каждого источника и восстановить события без уведомлений. Для Asana отдельно различать `assigned`, `mentioned`, `commented`, `blocked_by`, `requested_review`, `FYI`; для GitHub — мой PR, CI, approvals/changes requested и PR, где ожидается именно моё ревью. Отсутствующий канал обозначать `unknown`, не «нет обязательств». -2. **Выборка и эталон.** Взять 20 интервалов поперёк Asana, браузера/PR, VS Code/worktrees, agent sessions, встреч и личного контекста. Для каждого сохранить исходный ID/URL, тип источника, время наблюдения, автоматическую метку, confidence и проверенную метку. Личные проекты и статьи различать как `personal_project`, `work_research`, `leisure_or_break` или `unknown` по контексту и намерению; домен сайта сам по себе не доказывает «отвлечение». Без подтверждения Алекса не приписывать намерение или самочувствие. -3. **Разбор расхождений.** Сначала исправлять неверный/устаревший источник, затем связь объектов, затем роль и приоритет, затем момент/формат обращения. Менять одно правило за раз; сохранить в `calibration_cases` и `calibration_changes` исходный пример, исправление и результат повторного прогона. Уточнение у Алекса только на естественном переходе и лишь когда неоднозначность меняет его план; в пилоте максимум один такой вопрос в день. -4. **Shadow-план и пятидневный пилот.** На двух днях воспроизвести решения без доставки и проверить H3; после согласованного включения короткой карточки проверить H2/H4/H5 на пяти рабочих днях. Ежедневно смотреть только критические ложные срочности и пропущенные обязательства; по завершении сравнить субъективный фокус/самочувствие, неплановые обращения, review minutes, границу дня и расход токенов. Если карточки не читаются или вредят фокусу, остановить доставку и исправить правило. Отсутствие обратной связи не считать согласием. - -**Аудит источников:** [[personal/plans/personal-os-source-audit-2026-10-03]] фиксирует `есть / нет / свежесть / достоверность / что требуется от Алекса / точная правка / проверка` для Asana, GitHub, браузера, worktrees и Codex/Claude/Balda. Его выводы уточняют P0.1; аудит не включал автозапуск сборщиков. - -### Первый исполняемый срез — выполняется - -**Пакет A — выполнен 2026-10-03.** Добавлены локальная очередь `work_demands`, статус источника и классификация прямых вопросов, ревью, назначений и неопределённостей. После одного read-only refresh очередь `fresh`: 2 прямых вопроса и 1 запрос на ревью из Asana; FYI и автоматические напоминания не названы обязанностью. Проверены 20 реальных комментариев без переноса текста в отчёт, 6 автоматических тестов проходят. Обновлён `~/context/attention.md`. Старый Executor и расписание не запускались. - -**Ход 2026-10-03, 22:42 +06.** `com.personalos.focus-shadow` загружен с интервалом 15 минут: 3 октября тихий сбор продолжается до полуночи, затем — рабочие дни 08:00–20:00; два полных read-only прогона сегодня завершились без ошибок. Снимок сохраняется в `~/context/shadow.json`, `focus.json` и `shadow-history/`. GitHub: 27 моих open PR и 5 текущих review requests, оба набора точно совпали с независимым REST API; CI, head SHA, approvals и unresolved threads читаются. ActivityWatch: 254 локальных интервала; текущая тема `unknown`, потому что AFK-данные сейчас stale. DDG URL watcher загружен, но свежего URL ещё нет — не строить привязку по названию окна. Метаданные Codex/Claude и локальные worktrees читаются без текста разговоров; `needs_human` остаётся unknown без подтверждённого события. Календарь и Balda не имеют подтверждённого read-path/контракта в этом срезе. 18 тестов проходят. Два рабочих дня shadow и проверка 20 разнообразных интервалов остаются впереди; доставка карточек, Zoom, iPad и старый Executor не включены. - -**Обновление 2026-10-04, 00:41 +06.** Последний полный снимок: Asana/GitHub и AW window/AFK/DDG URL `fresh`; Xcode/VS Code `stale` из-за отсутствия недавних событий. Обнаружены 78 worktrees, 40 с незавершёнными изменениями, 2157 изменённых путей и 64 коммита за 30 дней; учитываются размеры и пути без diff. Из 53 интервалов iTerm 18 привязаны к точному worktree по пути в заголовке. 65 Codex и 24 Claude сессии видны по metadata без бесед. Корпоративный Mattermost авторизован отдельным Chrome-клиентом: первый сбор 21 сообщение из 202 каналов, далее каждые 15 минут; на mm.qentra.top проверен сбор 265 сообщений из 9 каналов без фонового расписания. Outlook виден только как активность окна; чтения писем/встреч нет, доступные коннекторы отключены администратором, для Graph нужен разрешённый app/client ID. Календарь и Balda остаются `unknown`. Последний полный snapshot и 27 тестов прошли. Исторические цифры в абзаце выше относятся к 3 октября и не описывают текущую свежесть источников. - - - -**Режим разработки:** одна активная coding-задача Personal OS за раз, один проверяемый результат на задачу, без unattended respawn; текущие Balda/Broker/Virfield уже занимают часть reviewer capacity. До достоверного учёта токенов не выдавать агенту бесконечный Ralph loop. Лимиты первого среза: одна попытка исправления после неудачной проверки, один пакет на ревью Алексу в день, целевой размер ревью до 20 минут. Фактические токены/стоимость логировать, отсутствие usage обозначать `unmetered`; численные token caps P1 согласуются отдельно. Параллельно coding-задаче можно вести read-only диагностику следующего адаптера без нового запроса к Алексу. - -1. **Собрать достоверную очередь человеческих обязательств из Asana и GitHub.** В [`sync.js`](file:///Users/admin/Developer/personal-os/sync.js) и новом `work-demand.js` различить назначение, прямой запрос/вопрос, dependency, ревью и FYI с `source ID`, временем, ролью и confidence; комментарий без ответа сам по себе не равен обязательству. В [`gh-snapshot.js`](file:///Users/admin/Developer/personal-os/gh-snapshot.js) получить все мои open PR в рабочих репозиториях и полный список текущих review requests независимо от unread, а для PR — head SHA, CI failures, approvals/changes requested и unresolved review threads. Репозитории брать из явной конфигурации и подтверждённых локальных worktrees, не только из текущего hardcoded `duckduckgo/apple-browsers`. Хранить раздельные `observed_at/stale/error`; ошибка GitHub не превращается в «нет PR». **Приёмка:** на выбранных Asana examples ложный FYI не становится «ответь»; мои 19 текущих PR в `duckduckgo/apple-browsers` не теряются из-за лимита 20; проверка review queue совпадает с текущим API/UI и имеет ссылки. **Польза:** система впервые показывает, что от меня реально ждут, без общего backlog dump. -2. **Привязать текущую работу и агентные ожидания к объектам шага 1.** В [`aw-query.js`](file:///Users/admin/Developer/personal-os/aw-query.js) вычислять `Now` из свежего переднего окна и AFK; DDG URL восстанавливать через существующий watcher или явно показывать `unknown`. Новый `context-links.js` связывает точный Asana task ID/browser PR/repo-worktree-branch-head SHA; новый `session-observer.js` читает только metadata Codex/Claude, `agent-run-adapters.js` принимает подтверждённый `needs_human` или оставляет `unknown`. **Приёмка:** Asana→browser PR→worktree→agent run даёт одну человеческую тему и отдельное агентное время; личный проект/статья не становятся автоматически «плохим отвлечением»; старое событие Xcode/VS Code не побеждает текущее окно. **Польза:** меньше ручного поиска «где остановился» и ложных переключений. -3. **Собрать один локальный focus state по обязательствам и доступной ёмкости.** Новый `capacity-model.js` вычитает подтверждённые встречи, перерывы, резерв на переключение/неожиданное и reviewer slot из установленной границы дня; неизвестный календарь/энергия явно остаются неизвестными. Новый `day-coordinator.js` выбирает одну основную тему, не более трёх ближайших действий и явные переносы; `focus.json`/`focus.md` по запросу заменяют длинный статус. Никаких push и расписания на этом шаге. **Приёмка:** перегруженный fixture-день оставляет перерыв и один reviewer slot; настоящий deadline показан с причиной, FYI и готовый agent PR не прерывают фокус. **Польза:** появляется короткий ответ «что делать сейчас и почему это посильно». -4. **Калибровать без нагрузки на Алекса.** Новый локальный `scripts/run-focus-shadow.sh`/LaunchAgent запускает только read-only incremental Asana/GitHub refresh и локальную сборку timeline/решений без карточек и уведомлений; отдельные каналы помечают `fresh/stale/failed`, целевая свежесть важных обязательств в рабочее время — до 15 минут, с проверкой API затрат и задержек. Два рабочих дня shadow-сбора и 20 интервалов разных типов сравнить с ID/URL/состояниями источников; два дня воспроизвести focus-рекомендации без доставки. Исправлять по одному правилу и сохранять пример/до/после в `calibration_cases/changes`; у Алекса уточнять максимум один вопрос в день только если ответ меняет рекомендацию. **Приёмка:** ноль ложных high-confidence привязок и выдуманных `needs_human`, нет скрытого пропуска важного обязательства, неизвестное не маскируется. **Польза:** рекомендации опираются на проверенные факты, а не на названия окон. -5. **Включить ограниченный пользовательский пилот.** После отдельного согласования границы дня и канала показывать одну карточку на естественном переходе; обычные обновления копить молча. Пять рабочих дней измерять добровольную оценку самочувствия/рваного фокуса, неплановые обращения, минуты ревью, пропущенные обязательства и использование карточки. На «неверно/слишком много» исправлять следующее предложение; неиспользуемую карточку остановить. **Приёмка:** нет обычных прерываний во время focus/meeting и после границы дня; Алекс за ≤10 секунд корректирует план. **Польза:** система начинает помогать в моменте, не создавая новый поток сообщений. - -**Утверждённая граница плана от 3 октября:** локальные read-only интеграции, файлы контекста, проверка на выборке и тихий автозапуск shadow-сборщика. Позже Zoom-экспорт отдельно включён и создание пустого iPad-проекта запущено; это не означает приёмку iPad-клиента или автоматического импорта новых встреч. Старый `com.personalos.readonly` и Executor остаются выключенными. Push-уведомления и запись в Asana/GitHub не включены. До пользовательского пилота нужны граница рабочего дня и канал короткой карточки. - -### Передача в следующую сессию — исполняемые пакеты - -**Стартовая инструкция:** «Выполни утверждённый первый срез Personal OS из этого документа. Начни с пакета A ниже; учитывай [[personal/plans/personal-os-source-audit-2026-10-03]] и миссию. Код и тихий локальный сбор разрешены в указанной границе. Не превращай это в новый раунд общего планирования. Дай один короткий отчёт о результате и проверках; не запрашивай ревью чаще одного раза в день». Разработка стартует в новой сессии; запись этого документа не запускает агентов или сервисы. - -1. **Пакет A — Asana obligations.** Проверить текущее `git status` и схему без изменения существующих чужих файлов; сохранить локальные изменения. Из [`asana.js`](file:///Users/admin/Developer/personal-os/asana.js), [`sync.js`](file:///Users/admin/Developer/personal-os/sync.js) и `stories` сделать `work-demand.js` + аддитивную миграцию `migrations/003_focus_core.sql`: `role`, `requested_action`, `requester`, `evidence_gid`, `observed_at`, `confidence`, `unknown`. Отделить прямой вопрос/назначение/ревью от FYI и комментария без ответа. **Готово, когда:** на проверенной выборке прямой запрос показан со ссылкой, FYI не назван обязанностью, ошибка источника не выглядит как пустой список; есть тесты на эти три случая и краткий отчёт о реальных примерах без копирования чувствительного текста. -2. **Пакет B — GitHub obligations.** После пакета A обновить [`gh-snapshot.js`](file:///Users/admin/Developer/personal-os/gh-snapshot.js): текущие мои PR и review assignments по подтверждённым рабочим репозиториям, CI/checks, approvals/changes requested, unresolved threads, head SHA, timestamps/errors по каждому источнику. `unread notification` оставить подсказкой, не источником истины для review queue. **Готово, когда:** число моих PR и текущих запросов на ревью совпадает с прямым GitHub API на момент проверки; сценарии failed CI, новый push после approval и resolved/unresolved comment дают правильное действие или `unknown`. -3. **Пакет C — наблюдаемый контекст.** После пакета B исправить [`aw-query.js`](file:///Users/admin/Developer/personal-os/aw-query.js) и добавить `context-links.js`/`session-observer.js`/`agent-run-adapters.js`: переднее окно+AFK, точный URL/ID, локальные worktrees, metadata сессий и только подтверждённые `needs_human`. Проверить DDG watcher; при отсутствии свежего URL сохранять `browser_url_unknown`. **Готово, когда:** Asana→PR→worktree→агент соединены доказанной связью, человеческое и агентное время раздельны, старый Xcode/VS Code bucket не называется текущим фокусом. -4. **Пакет D — посильное решение.** После пакета C добавить `capacity-model.js`, `day-coordinator.js` и локальные `focus.json`/`focus.md` по запросу: одна основная тема, до трёх действий, причины переносов, встреча/перерыв/граница дня/reviewer slot; отсутствие энергии и календаря остаётся `unknown`. **Готово, когда:** обычный и перегруженный fixture-дни дают выполнимые планы, FYI/готовый agent PR не прерывают фокус, карточка занимает один экран. -5. **Пакет E — тихая проверка и пилот.** После пакета D проверить один read-only прогон, затем включить только новый `run-focus-shadow` для двух рабочих дней без уведомлений, проверить 20 интервалов и зафиксировать исправления. До пользовательского пятидневного пилота получить от Алекса границу рабочего дня и канал карточки; включить доставку только после этого. **Готово, когда:** источник/связь/роль/решение проверены по ссылкам, ноль ложных уверенных `needs_human`, измерены человеческие прерывания и reviewer minutes. - -**Общие правила приёмки пакетов:** каждый пакет завершается работающим кодом, тестом фактического риска, коротким diff/артефактом и указанием оставшихся `unknown`; следующий пакет может готовиться автономно, но новые результаты к ревью Алексу не отправлять сверх одного пакета в день. Даты и числа из аудита — снимок 3 октября: в новой сессии проверить свежесть Asana/GitHub/AW, а не считать 19 PR постоянной величиной. - -## 2. Что действительно есть 2026-10-03 - -| Слой | Проверенный факт | Граница факта | -|---|---|---| -| Asana | [`sync.js`](file:///Users/admin/Developer/personal-os/sync.js) читает задачи/комментарии в локальную PostgreSQL; разовый прогон 3 октября дал свежие данные. [`generate-status.js`](file:///Users/admin/Developer/personal-os/generate-status.js#L890) создал `~/context/status.md` (402 строки), пробный [`generate-attention.js`](file:///Users/admin/Developer/personal-os/generate-attention.js#L32) — 28-строчный список. | Фоновый `com.personalos.readonly` после остановки не загружен; разовый прогон не означает работающую Personal OS. Список не учитывает энергию, встречи, перерывы и контекст возврата. | -| ActivityWatch | Локальный `aw-server` слушает 127.0.0.1:5600. 3 октября в 14:13 UTC у bucket `window` и `afk` были свежие записи. [`aw-query.js`](file:///Users/admin/Developer/personal-os/aw-query.js#L220) считает активное время, приложения, проекты, сессии и worktrees. Расширение `activitywatch.aw-watcher-vscode` установлено и в `~/.vscode/extensions/`, и в старом `~/.cursor/extensions/`; [`README.md`](file:///Users/admin/Developer/personal-os/README.md#L106) описывает только Cursor и устарел. | Xcode bucket обновлён последний раз 1 октября, `aw-watcher-vscode` — 2 октября, DDG URL — 8 июня; отсутствие более свежего события не доказывает поломку. Нужно различить источники bucket и проверить работу именно в VS Code. `currentFocus` берёт первый bucket по приоритету xcode→vscode→ddg→window за 20 минут, а не фактически переднее окно; последний [`status.md`](file:///Users/admin/context/status.md) написал `Now: loginwindow (18m ago)`. | -| GitHub и связь с работой | [`gh-snapshot.js`](file:///Users/admin/Developer/personal-os/gh-snapshot.js) получает мои PR/CI и некоторые review requests; [`aw-projects.json`](file:///Users/admin/Developer/personal-os/aw-projects.json) умеет сопоставлять отдельные worktree/URL с проектом. Локально обнаружены 397 Codex и 59 Claude JSONL session files; последний Codex `session_meta` содержит `cwd/git`, Claude session — `cwd/gitBranch` в метаданных (проверено без чтения текста бесед). | Связь worktree ↔ ветка ↔ PR ↔ Asana task и sessions не собрана в единую историю дня. Работу агента нельзя автоматически считать человеческой активностью. Review requests зависят от unread notifications. | -| Встречи/Zoom | В старых промптах есть расписание и попытка MS365-проверки; записи бесед Zoom существуют по сообщению Алекса. | Подтверждённого текущего календарного канала и импорта этих записей в рабочий/карьерный профиль нет. Папка `~/Documents/Zoom` не указывает место всех записей. | -| Агенты | Старый Executor и Hermes-briefs выключены после инцидента. В [`executor_worker_runner.py`](file:///Users/admin/Developer/personal-os/agent/executor_worker_runner.py#L195) задано `max_turns=200`, а [`executor-runner.sh`](file:///Users/admin/Developer/personal-os/executor/executor-runner.sh#L17) допускает двух workers. В текущей Codex desktop задаче доступен read-only список задач с `active/idle/notLoaded`, но это не полный статус запросов к Алексу. | В видимом runner нет учёта токенов/денег и оценки минут ревью Алекса. Логи одного задания содержат повторные respawn без прогресса. Codex/Claude/Balda состояние `needs_human` пока нельзя достоверно собрать из одного списка или mtime; Balda/Broker/Virfield развиваются отдельно. | -| Карьера и день | [`generate-status.js`](file:///Users/admin/Developer/personal-os/generate-status.js#L731) показывает Advisor opportunities и visibility gaps; `activity_daily` хранит агрегаты времени по проектам. | Нет единого состояния для управленческой работы: PR/TD/Ship Review/team growth, баланса, энергии, встреч, ревью агентов и доказательств вклада. Карьерные сигналы оказываются внизу большого статуса; минуты кодинга не отражают менеджерский вклад. | - -## 3. Почему старая версия не стала полезной - -Алекс сообщил, что быстро перестал читать сгенерированные daily statuses. Точную причинную долю каждого фактора телеметрия не измеряла; ниже — **подтверждённые дефекты дизайна и вывод о вероятном эффекте**. - -| Что было | Подтверждение | Почему это мешало | Что меняем в парадигме | -|---|---|---|---| -| Daily brief = большой отчёт. | В `briefs/daily/` 32 сохранившихся файла: медиана 115,5 строк, 30 из 32 длиннее 80; [`2026-05-15.md`](file:///Users/admin/Developer/personal-os/briefs/daily/2026-05-15.md) — 110 строк, с повторными просрочками и исторической trivia. [`daily-brief.md`](file:///Users/admin/Developer/personal-os/agent/prompts/daily-brief.md#L152) предписывает trivia и все разделы. | Высокая цена чтения в начале дня; сигналов больше, чем решений. Формат не был подстроен под то, открыл ли Алекс предыдущий выпуск. | Живое состояние и короткая карточка в нужный момент; подробности по запросу. Публикация не считается успехом без полезности для Алекса. | -| План дня строился от Asana-очереди и фиксированных правил. | [`daily-brief.md`](file:///Users/admin/Developer/personal-os/agent/prompts/daily-brief.md#L205) требует первым «1 Must» или самую лёгкую задачу, затем overdue/urgent; в нём нет запроса энергии и расчёта ёмкости дня. | Предлагаемый объём мог превышать доступное после встреч и перерывов; «первое лёгкое дело» могло вытеснять лучший фокус. | Сначала вместимость, энергия и фокус, затем выбор посильной работы. Перегрузка приводит к явному переносу. | -| «Фокус» выводился из приложения/времени, а не из рабочей темы. | [`aw-query.js`](file:///Users/admin/Developer/personal-os/aw-query.js#L279) сопоставляет window events с Xcode/VSCode/DDG, [`aw-projects.json`](file:///Users/admin/Developer/personal-os/aw-projects.json) в основном классифицирует приложения, URL и имена worktree; связей с Codex/Claude runs, Asana-обязательствами и ревью TD/Ship Review нет. | Asana, browser PR и Claude могут относиться к одной рабочей теме; Codex на экране может быть управлением агентом. Смена приложения ≠ смена работы, и наоборот. | Временная линия рабочих тем с объектами и агентными ожиданиями, confidence и честным `unknown`. | -| Система не знала реальный момент для вмешательства. | [`inbox-triage.md`](file:///Users/admin/Developer/personal-os/agent/prompts/inbox-triage.md#L22) проверяет `Now` из 30-минутного status; [`aw-query.js`](file:///Users/admin/Developer/personal-os/aw-query.js#L305) может выбрать старое Xcode событие или `loginwindow` как текущий фокус. | Даже верный сигнал мог появиться во время deep work или пропасть из-за ошибочной оценки фокуса. | Временная модель `focused / meeting / break / available / unknown`, с отдельной свежестью источников и ручным override. | -| Генерация не замыкала обратную связь. | [`heartbeat.sh`](file:///Users/admin/Developer/personal-os/scripts/heartbeat.sh#L140) проверяет существование файла brief, а не открытие, действие, отложение или неверность; в `schema.sql` нет принятия/полезности карточки. | Система не замечала, что документы перестали помогать, и продолжала производить их по графику. | Измерять добровольное использование и коррекции; прекращать неиспользуемые формы. | -| Автономия агентов создавала долг ревью и расход без ограничителя. | История инцидента в [[personal/projects/personal-os/executor-security-analysis]]; `max_turns=200`, `MAX_WORKERS=2`, нет ledger токенов; в [`executor/logs/1214071796247142/`](file:///Users/admin/Developer/personal-os/executor/logs/1214071796247142/) есть многократные `conflict_no_action` respawns. | Параллельные результаты и вопросы могут рвать фокус Алекса быстрее, чем он успевает проверять; повторы сжигали токены и внимание. | Планировать агентную работу как нагрузку на человека и бюджет; admission control, WIP, stop rules, пакетное ревью. | - -## 4. Очерёдность правок — было → станет → проверка - -### P0.1 — блокер 1: достоверная временная линия человека, рабочих тем и агентных задач - -**Было:** [`aw-query.js`](file:///Users/admin/Developer/personal-os/aw-query.js#L305) считает время приложений/проектов и может назвать старое Xcode/Cursor/DDG событие или `loginwindow` «текущим фокусом». Asana, браузерные PR, VS Code, Codex/Claude, worktrees, встречи и очередь агентных ревью не соединены. Название приложения не говорит, планирует ли Алекс работу, ревьюит TD, контролирует агента или пишет код. - -**Станет:** локальная `work_timeline` из интервалов `start/end`, `actor=human|agent`, `work_thread_id`, `activity=planning|asana|pr_review|td_review|ship_review|team_growth|coding|agent_supervision|meeting|break|unknown`, `context_type=work_task|work_research|personal_project|leisure_or_break|unknown`, `source`, `evidence_url/id`, `confidence` и `state` агентной задачи (`running|blocked|waiting_review|done`). Несколько приложений могут соответствовать одной рабочей теме; две параллельные агентные задачи — двум отдельным потокам. Статья и личный проект не получают автоматически ярлык «отвлечение»: возможны работа, осознанный перерыв и неизвестный контекст. Переход между темами и входящий агентный запрос на ревью отмечаются отдельно; именно их частота и время возврата характеризуют «рваный фокус». Никакой интервал с низкой уверенностью не становится основанием для срочного прерывания. - -**Как привязывать:** (1) точные ID/URL Asana task и GitHub PR; (2) git branch/worktree и явная связь с PR/Asana; (3) Codex/Claude session metadata `cwd/git/branch/time`, без текста разговоров; (4) календарь/Zoom для встречи; (5) классификация агентом только оставшихся неоднозначных интервалов, со ссылкой на улики и `unknown`, когда доказательств мало. Агент не задаёт вопрос по каждому `unknown`: уточнение допускается на естественном переходе, только если ответ изменит план, в пилоте — не более одного в день. Статус `waiting_review/needs_human` берётся из явного состояния задачи/запроса на approval, **не** из mtime файла или непрочитанного чата. В текущем Codex desktop read-only список задач показывает `active/idle/notLoaded`, но это ещё не полная семантика «ждёт Алекса»; доступ к pending approvals/ответам должен быть проверен отдельным адаптером. Для Claude и Balda/Broker аналогично использовать подтверждённые состояния или `unknown`. ActivityWatch определяет *когда* человек активен/AFK и какое окно впереди, не подменяет смысл работы. Учёт токенов и человеко-минут ревью привязан к отдельным agent runs. - -**Правки:** [`aw-query.js`](file:///Users/admin/Developer/personal-os/aw-query.js) — frontmost window + AFK как основа, свежесть, интервалы, исключить lock и старые bucket из `Now`; проверить установленное VS Code расширение, обновить [`README.md`](file:///Users/admin/Developer/personal-os/README.md#L106), диагностировать старый DDG URL watcher в [`DDGWatcher.swift`](file:///Users/admin/Developer/aw-watcher-ddg/Sources/AWWatcherDDG/DDGWatcher.swift) и Xcode watcher только если их данные нужны для связки. [`aw-projects.json`](file:///Users/admin/Developer/personal-os/aw-projects.json) — обновить правила рабочих тем и личного контекста. Новые `session-observer.js` (метаданные Codex/Claude), `agent-run-adapters.js` (явные состояния и запросы на human action из доступных Codex/Claude/Balda источников), `context-links.js` (worktree→branch→PR→Asana), `work-timeline.js` (нормализованный timeline и confidence), миграция `migrations/003_focus_core.sql` (`work_threads`, `work_intervals`, `agent_obligations`, `activity_bindings`, `calibration_cases`, `calibration_changes`). [`gh-snapshot.js`](file:///Users/admin/Developer/personal-os/gh-snapshot.js) — регулярный refresh моих PR, CI failures, approvals/changes requested, review comments и полного списка PR на моё ревью, не только unread notifications; [`sync.js`](file:///Users/admin/Developer/personal-os/sync.js) — Asana ownership, роли и явные requests к Алексу; у каждого источника `observed_at/ok/stale/failed`. Точные интервалы обновления определить после аудита источников и измерения задержек; старый `generate-status.js` перестать использовать как единственный источник «Now». - -**Приёмка:** два рабочих дня тихого shadow-сбора, без новых сообщений Алексу. На 20 проверенных интервалах ни одна `high-confidence` привязка не противоречит исходной Asana/PR/session ссылке; неоднозначные остаются `unknown`. Fixture `Asana task → browser PR → Claude по той же задаче` показывает одну рабочую тему и отдельную работу агента; fixture с двумя агентами показывает два `waiting_review` без удвоения человеческих часов. Xcode→browser, VS Code→Asana, lock/AFK и устаревший watcher дают корректное состояние, а не ложное «сейчас кодит». - -### P0.2 — блокер 2: анализ «что надо делать» при реальном фокусе и самочувствии - -**Было:** даже точные Asana/PR и минуты ActivityWatch выдавались как срочность/список задач. Не определялись роль Алекса и цена ожидания, вклад в карьеру и команду, доступная энергия, размер окна до следующей встречи, цена переключения и очередь агентных ревью. Календарь/Zoom пока не подтверждены как полный источник расписания. - -**Станет:** `day_state` содержит явно выбранный фокус, добровольную энергию/настроение (1–5 или `unknown`), границу рабочего дня, подтверждённые встречи, доступные окна, перерывы, задачи и зависимости, карьерные обязательства, reviewer minutes/WIP и перенесённые пункты. `work_demand` для каждого кандидата хранит: роль `owner|reviewer|advisor|manager|observer`, кто ждёт, проверяемый срок и последствия ожидания, пользу для проекта/карьеры, длительность и когнитивную тяжесть, состояние агента, source links и уверенность. Результат по кандидату — `делать сейчас / выделить окно / делегировать / ждать / перенести` с человеческим объяснением. - -**Приоритетный принцип:** сначала самочувствие и законные/реальные границы дня, затем защитить основную рабочую тему, затем обязательства перед другими людьми и узкие окна, затем карьерный/командный вклад; количество просроченных дат или готовых agent PR не является порядком дня. Один и тот же PR/Asana task дедуплицируется. У задачи с сомнительной ролью — `needs_clarification`, а не императив «ответить». При низкой энергии сложное ревью можно отложить, но настоящий hard deadline явно показать вместе с вариантом делегирования/сокращения другой работы. - -**Правки:** `migrations/003_focus_core.sql` добавить `day_state`, `work_demands`, `focus_feedback` и использовать `agent_obligations` из P0.1 для оценки reviewer load; новый `work-demand.js` извлекает роли/зависимости из Asana, текущих PR, TD, Ship Reviews, meeting commitments и agent outputs, сохраняет доказательство и сомнения; новый `capacity-model.js` считает рабочую ёмкость; новый `day-coordinator.js` выбирает фокус и объясняет переносы. [`agent/task-role-classifier.md`](file:///Users/admin/Developer/personal-os/agent/task-role-classifier.md) и соответствующие playbooks обновить для advisor/manager/reviewer и контроля агентов; [`agent/prompts/daily-brief.md`](file:///Users/admin/Developer/personal-os/agent/prompts/daily-brief.md) убрать автоматическое «easiest first», полный overdue dump и неконтекстный план. Минимальный локальный ввод `focus-input.js`: сменить фокус/энергию/конец работы/«сегодня легче», без обязательного дневника. Для встреч сначала проверить фактический calendar read-path; при его отсутствии `meeting_schedule_unknown`, а не время, выведенное из Asana-задачи. - -**Расчёт ёмкости:** время до границы работы − подтверждённые встречи − переходы между темами − защищённые перерывы − резерв на неожиданное − согласованное время человеческого ревью. Сложность работы соотносится с *явно указанной* энергией; `unknown` даёт консервативное предложение. Если спрос выше ёмкости, система показывает **что переносит/делегирует/оставляет ждать и почему**; не превращает личное время в рабочий резерв. - -**Приёмка:** на fixture-дне с двумя встречами, низкой энергией, одним PR-review, одним TD/Ship Review, тремя Asana-задачами и двумя готовыми агентными результатами система оставляет одну основную рабочую тему, один ограниченный reviewer slot, перерыв и явные переносы; не предъявляет сразу два агентных ревью. На fixture-дне без календаря не выдумывает время встречи. На fixture с прямым запросом коллеги отличает реальное обязательство от FYI. Все решения имеют ссылку и расчёт ёмкости, личное время остаётся вне плана. - -### P0.3. Управлять моментом и формой обращения к Алексу - -**Было:** [`scripts/heartbeat.sh`](file:///Users/admin/Developer/personal-os/scripts/heartbeat.sh#L140) выпускал daily brief по часам и inbox каждые 30 минут; [`daily-brief.md`](file:///Users/admin/Developer/personal-os/agent/prompts/daily-brief.md#L205) требует длинный фиксированный формат. Пробный [`attention.md`](file:///Users/admin/context/attention.md) короче, но всё ещё список событий без плана нагрузки и состояния фокуса. - -**Станет:** один короткий `focus_state` с текущей рабочей темой (не только app), доступной ёмкостью, **не более трёх** ближайших осмысленных действий, одной причиной сменить приоритет, временем следующего перехода/перерыва, числом/минутами ожидающих агентных ревью и ссылками. Подробный контекст открывается по желанию. Во время focus/meeting обычные изменения и готовые результаты агентов остаются в локальной очереди; после перехода — одна карточка восстановления. Критическое прерывание требует подтверждённого владельца, последствий ожидания и указанного deadline; возраст комментария или красная иконка недостаточны. Старое «3 часа» из миссии — кандидат на калибровку, не автоматическое правило для всех задач. - -**Правки:** новый `focus-policy.js` (классы состояний, quiet hours, исключения); `day-coordinator.js` (динамический выбор после перехода); [`generate-attention.js`](file:///Users/admin/Developer/personal-os/generate-attention.js) заменить секции «Ответить/Ревью/Текущая работа» на компактный объект `focus_state` + фоновые обязательства и связи с источниками; `agent-run-adapters.js` складывает **уже существующие** Codex/Claude/Balda результаты и запросы в одну review queue, отличая genuine approval от обычного статуса. Там, где промпты/транспорт управляются Personal OS, заменить прямые статусные пинги единым review packet с оценкой времени; внешние неперехватываемые уведомления явно показывать как пробел. [`agent/prompts/daily-brief.md`](file:///Users/admin/Developer/personal-os/agent/prompts/daily-brief.md) заменить обязательные trivia, overdue dump и «easiest first» правилом краткой карточки с capacity/reason; [`scripts/heartbeat.sh`](file:///Users/admin/Developer/personal-os/scripts/heartbeat.sh) оставить старые brief jobs выключенными, позже вызвать только согласованный новый рендер. Выходы `~/context/focus.json` и `~/context/focus.md` атомарны; iPad позже читает тот же контракт в ограниченном виде. - -**Приёмка:** во время 45-минутной работы над одной темой через Asana → browser PR → Claude два законченных agent jobs и обычный комментарий не создают три прерывания; переключение приложений внутри темы не обнуляет фокус. После блока доступна **одна** карточка с исходной темой, изменениями, ссылками и посильным следующим действием; агентные ревью остаются в выделенном окне. После встречи видно, к какой теме вернуться без поиска по нескольким приложениям. После границы рабочего дня обычных рабочих сигналов нет. - -### P0.4. Замкнуть цикл на ощущении пользы, а не на числе сгенерированных файлов - -**Было:** файл существует → job считает успех; невозможно узнать, пригодился ли план, был ли он слишком длинным, насколько посильным оказался день. Старые brief-форматы могли копиться, даже когда Алекс перестал их читать. - -**Станет:** у карточки есть необязательные одношаговые элементы управления `полезно / неверно / слишком много / отложить` и оценка энергии/самочувствия 1–5, без переписки с агентом Personal OS. Система хранит correction с причиной и меняет следующий план: неверный сигнал удаляет ложное правило, «слишком много» уменьшает объём, пропуск карточки не порождает дополнительных напоминаний. Личные оценки остаются локальными и не становятся performance-метрикой. - -**Правки:** `migrations/003_focus_core.sql` для `focus_feedback`; новый `focus-feedback.js`; [`agent/prompts/weekly-review.md`](file:///Users/admin/Developer/personal-os/agent/prompts/weekly-review.md) заменить обзор backlog на оценку: самочувствие (если добровольно указано), восстановление контекста, защищённые focus/break blocks, пропущенные обязательства, reviewer load, ложные прерывания. Отчёт не чаще раза в неделю и с одним предложением изменения правила. - -**Приёмка 5 рабочих дней:** каждый день можно открыть состояние за один экран; ноль обычных прерываний во время подтверждённых focus blocks, ноль рабочих push после установленной границы, ни одно критическое сообщение без ссылки/причины. Начальный и итоговый замер включают число переходов **между рабочими темами**, число неплановых обращений к Алексу от агентов, накопленные минуты ревью и короткую добровольную оценку «рваности фокуса»/самочувствия; цель — уменьшение неплановых обращений и отсутствие ухудшения самочувствия, а не максимизация активных минут. Алекс может за ≤10 секунд отметить ошибку или перегрузку; его коррекция меняет следующий расчёт. Если он снова не читает карточку, формат пересматривается, а не размножается. - -### P1. Допустить кодинговых агентов только через два бюджета - -**Было:** `MAX_WORKERS=2`, `max_turns=200`, повторные respawn и подробные сообщения в чат; очередь ревью Алекса и токены не учитываются в плане дня. - -**Станет:** перед запуском есть **два независимых лимита**: (A) человеческий — ожидаемые минуты ревью, уже ожидающие результаты, доступный reviewer slot с учётом энергии/фокуса; (B) агентный — токены/стоимость, время, число попыток и параллельность. Ledger хранит `provider/model`, input/output/cache tokens, оценку денег по фактическому тарифу, длительность, retries, прогноз и факт минут ревью. Агентная задача получает прогноз пользы и затрат; admission разрешён, только если оба остатка достаточны. На 80% дневного/недельного лимита новые coding jobs не стартуют, на 100% текущий job завершает безопасную точку и останавливается с артефактом/блокером. После двух попыток без нового проверяемого прогресса — stop без самоперезапуска. Готовый результат сверх reviewer capacity остаётся в очереди без уведомления Алекса. - -**Правки:** `migrations/004_agent_capacity.sql` (`agent_runs`, `agent_usage`, `review_queue`, лимиты, прогноз/факт); новый `agent-budget.js` как admission/stop policy; [`agent/executor_worker_runner.py`](file:///Users/admin/Developer/personal-os/agent/executor_worker_runner.py#L195) логирует usage из ResultMessage/провайдера и прерывает по budget, не выдаёт `max_turns` за успех; [`executor/executor-runner.sh`](file:///Users/admin/Developer/personal-os/executor/executor-runner.sh#L17) в будущей замене/адаптере ограничивает WIP и запрещает бесконечный respawn; правила в `agent/prompts/executor-*.md` требуют одного проверяемого артефакта и оценки времени ревью, без полного trace в чат. Balda/Broker/Virfield остаются своим параллельным проектом; Personal OS пользуется их зрелым интерфейсом после приёмки. - -**Предлагаемые стартовые лимиты для пилота, не включены:** одновременно 1 coding worker; 1 результат, ожидающий Алекса; до 20 минут ревью в рабочий день; максимум 1 автоматическая повторная попытка; 30 000 суммарных input+output токенов на задачу, 60 000 в день, 120 000 в неделю (cache tokens хранить отдельно для расчёта стоимости). После 3 измеренных задач пересчитать лимиты по реальной стоимости и времени ревью; стоимость в деньгах считать по фактическому провайдеру/плану, без выдуманной цены за токен. Если провайдер не отдаёт usage, пометить `unmetered` и не запускать следующий unattended loop. В день с низкой энергией reviewer slot можно обнулить без накопления срочных запросов. - -**Приёмка:** два законченных агентных результата не вызывают два одновременных запроса к Алексу; второй ждёт свободного slot. Задача с повтором без diff/test progress останавливается; ledger показывает токены, время, оценку и факт человеческого ревью. Агентная работа не съедает защищённый focus block и не делает вечер новым рабочим временем. - -### Параллельно: Zoom и iPad, но по контракту P0 - -- **Zoom:** текущий доступ к My Notes подтверждён через отдельный headless Chrome. Два transcript сохранены с `note_id` и источником; первый запуск по расписанию 5 октября и импорт первой новой заметки ещё нужно проверить. Следующий содержательный этап — из сохранённого transcript извлечь проверяемые решения, обещания, сроки и вклад с ссылкой на фрагмент; кандидаты проходят review перед попаданием в рабочий/карьерный профиль. Повторный импорт не должен создавать дубль. См. [[personal/projects/personal-os/zoom-ai-transcript-export]]. -- **iPad Desk:** установка прежнего тестового проекта на физический iPad была подтверждена; создание нового пустого проекта через Balda на Monterey/Xcode 13 запущено 4 октября. Следующая контрольная точка — собираемый проект и артефакт установки нового приложения. Первый экран читает ограниченный `focus.json` по LAN: «фокус сейчас / одно ожидание меня / свежесть / нет связи». Приёмка: на iPad виден тот же focus state, после отключения сети ясно показана устаревшая версия; нет лишних алертов. - -## 5. Последовательность, зависимости, участие Алекса - -1. **Сейчас — тихий сбор запущен, калибровка не завершена.** Сверить 20 интервалов на двух рабочих днях, включая iTerm, DDG URL, личную работу и агентные ожидания; отметить ошибочные привязки. До пятидневного пользовательского пилота уточнить границу рабочего дня и канал карточки. -2. **P0.1 — блокер фактов:** после аудита собрать тихую временную линию человека/агентов/рабочих тем, проверить привязки к Asana/PR/meeting/worktree и честно показать неизвестные интервалы. Проверить 20 интервалов и два дня без новых сообщений Алексу. -3. **P0.1b — проектная правда:** первый датированный `project_state` для VSCode/SPM реализован, fixture, отдельный live-прогон и полный shadow-прогон во временную папку проходят; недостающий Asana-комментарий читается напрямую в read-only режиме. Полный shadow-прогон проверен в режиме `json_only`; следующий этап — подключить дополнительные проекты. Локальная DB-история остаётся необязательным улучшением. Затем направлять advisor/career outputs через claim-gate до новых утверждений о статусе. См. [[personal/projects/personal-os/project-truth-analyzer]]. -4. **P0.2 — затем блокер решений:** выбрать посильную работу из Asana, PR, TD, Ship Review, встреч, team growth и агентных ревью по роли, пользе, сроку, энергии и доступному времени; испытать перегруженный день до включения schedule. -5. **P0.3 → P0.4:** показать один короткий живой focus state, провести 5 рабочих дней измеряемого пилота с возможностью исправить перегрузку. Только после этого решать о регулярной доставке. -6. **P1 и параллельные ветки:** продолжить ограниченный coding loop с учётом review/tokens; проверить первый ночной Zoom-запуск и извлечение кандидатов из transcript; принять пустой iPad-проект и затем вывести тот же focus state на устройство. Balda/Broker/Virfield не дублировать. - -**Необходимое участие Алекса в пилоте:** перед доставкой карточки — граница рабочего дня и канал; затем по желанию один короткий сигнал «полезно/неверно/слишком много» и ручная смена энергии/фокуса, когда захочется. Система не требует ежедневного ведения журнала. Внешние записи и старый автономный Executor этим планом не разрешены. +Актуальная последовательность и критерии: [план E1–E5](../projects/personal-os/personal-os-action-plan-2026-10-05.md). [Текущая готовность](../projects/personal-os/personal-os-production-acceptance.md). diff --git a/personal/plans/personal-os-source-audit-2026-10-03.md b/personal/plans/personal-os-source-audit-2026-10-03.md index 1bd36be7..e813057b 100755 --- a/personal/plans/personal-os-source-audit-2026-10-03.md +++ b/personal/plans/personal-os-source-audit-2026-10-03.md @@ -1,51 +1,3 @@ ---- -namespace: personal -tags: - - personal-os - - source-audit - - focus -date: '2026-10-03T00:00:00.000Z' -status: read-only-audit -plan: '[[personal/plans/personal-os-operating-plan-2026-10-03]]' -updated: '2026-10-04' ---- +# План работ Personal OS -# Personal OS — аудит источников для P0 - -**Вывод:** технические факты уже собираются частично, но текущий feed не может надёжно ответить на два вопроса: **чем Алекс занят как рабочей темой** и **какого действия от него действительно ждут**. Это граница P0.1, а не повод включать старые briefs/Executor. Аудит выполнен чтением кода, локальной БД, ActivityWatch и проверкой доступа GitHub 3 октября; полнота каждого рабочего обязательства ещё не проверена по эталонной выборке. - -## Обновление 2026-10-04 - -Таблица ниже сохраняет исходные выводы аудита 3 октября. Текущий проверенный статус находится в [[personal/projects/personal-os/personal-os-status-2026-10]]; изменение по источникам: - -| Источник | Что работает сейчас | Оставшаяся граница | -|---|---|---| -| Asana/GitHub | Полный shadow-снимок `fresh`; 27 моих PR, 5 review requests; прямые запросы Asana отделены от FYI. | Семантические привязки ещё ждут проверки 20 интервалов. | -| ActivityWatch/DDG | Window, AFK и DDG URL `fresh`; URL watcher работает. Xcode/VS Code buckets `stale` при отсутствии недавних событий. | Свежесть специализированных bucket проверять при реальной активности приложения. | -| Git worktrees | 78 проверены; 40 с незавершёнными изменениями, 2157 изменённых путей, 64 коммита за 30 дней. Размеры изменений учитываются без diff. | Worktree без PR/Asana связи остаётся `unknown`. | -| Codex/Claude | 65/24 сессии по metadata без текста бесед. | `needs_human` нельзя выводить из mtime/idle. | -| Выгрузки транскриптов агентов | Алекс уточнил 4 октября: явная грубость в его сообщениях другим агентам — предварительный сигнал раздражения. Personal OS не должен становиться собеседником. | Сейчас читаются только metadata сессий. Нужен локальный импорт выгруженных транскриптов, разделение сообщений Алекса и агента, производная метка с временем/источником и проверка ложных срабатываний. | -| Mattermost | Отдельный авторизованный read-only клиент: корпоративный сервер собирается каждые 15 минут (первый сбор 21 сообщение / 202 канала); Qentra проверена (265 / 9). | Qentra была тестом; корпоративные сообщения пока хранятся отдельным локальным потоком. | -| iTerm | 18 из 53 окон привязаны к worktree по точному пути prompt в заголовке. | Остальные окна не имеют доказанной темы. | -| Outlook | Активность окна классифицируется как mail/calendar browsing. | Письма и события не читаются: доступные коннекторы отключены администратором, нужен разрешённый Graph app с `Mail.Read`/`Calendars.Read`. | -| Календарь/Balda | `unknown`. | Подтверждённого read-only контракта нет. | - - -| Источник | Есть сейчас | Пробел, который влияет на P0 | Конкретная следующая правка и проверка | -|---|---|---|---| -| Asana | [`sync.js`](file:///Users/admin/Developer/personal-os/sync.js) читает мои, отслеживаемые, делегированные и проектные задачи, stories и часть зависимостей. `sync_state` для `my_tasks`, `following`, `delegated` обновлён 3 октября около 19:15 +06. В [`schema.sql`](file:///Users/admin/Developer/personal-os/schema.sql#L15) есть assignee, creator, due date, stories, edges и raw JSON. | [`generate-attention.js`](file:///Users/admin/Developer/personal-os/generate-attention.js#L125) считает любой чужой комментарий без моего ответа кандидатом «ответить»; это может быть FYI. [`asana.js`](file:///Users/admin/Developer/personal-os/asana.js#L57) сохраняет только первую project membership в нормализованных полях; источник обнаружения сводится к одному `source`. Нет структурированного `owner/reviewer/advisor/observer`, прямого запроса, ожидающего человека, последствий ожидания и confidence. | Добавить `work_demand` с `role`, `requested_action`, `requester`, `due_evidence`, `evidence_gid/story_gid`, `confidence`, `observed_at`; классифицировать assignment, mention, вопрос, dependency и FYI отдельно. Проверить 20 разных Asana событий по исходным stories: ложное «ответь» не проходит приёмку. | -| GitHub | [`gh-snapshot.js`](file:///Users/admin/Developer/personal-os/gh-snapshot.js#L74) читает до 20 моих open PR с агрегированным CI/review decision. CLI авторизован; проверка 3 октября нашла 19 открытых PR в `duckduckgo/apple-browsers`. | Review requests берутся из `notifications?all=false&participating=true` и потому зависят от unread; team requests отбрасываются. `reviewDecision` и `ci` — агрегаты, нет модели новых review comments, конкретного required action, approval после последнего push, timestamps и независимого refresh state. Ограничение 20 PR близко к текущим 19. | Заменить notification-only review queue на запрос текущих reviewer assignments; отдельно получать reviews, unresolved threads, CI checks и head SHA для моих PR. Хранить `fetched_at` и ошибку по каждому потоку. Сверить set PR на ревью с GitHub UI/API, затем fixture: новый push после approval, failed CI, resolved/unresolved comment. | -| ActivityWatch, браузер и VS Code | Локальный AW отвечает. Buckets `window/afk_Mac` обновлены 3 октября около 21:08 +06; Xcode — 1 октября, VS Code — 2 октября, DDG URL — 8 июня. [`aw-query.js`](file:///Users/admin/Developer/personal-os/aw-query.js#L269) совмещает foreground window с editor/browser событиями для агрегатов. | [`currentFocus`](file:///Users/admin/Developer/personal-os/aw-query.js#L319) выбирает Xcode→VS Code→DDG→window из последних 20 минут, а не последнее активное окно; app у VS Code обозначен `Cursor`. DDG URL сегодня недоступен, поэтому Asana/PR/статью в браузере нельзя надёжно привязать. [`aw-projects.json`](file:///Users/admin/Developer/personal-os/aw-projects.json) классифицирует проекты по regex, не конкретные задачи и намерение. | Исправить `Now` по свежему foreground window + AFK, строго проверить перекрытие и freshness специализированных buckets; восстановить URL watcher либо пометить `browser_url_unknown`. Разбирать точные Asana task ID/PR number из URL; article URL связывать с задачей только при доказательстве. Проверить 20 интервалов, включая browser→Asana, lock, VS Code, статью и личный проект. | -| Git worktrees ↔ рабочая тема | Xcode watcher сообщает имя worktree/repo; [`aw-query.js`](file:///Users/admin/Developer/personal-os/aw-query.js#L262) агрегирует время. У старого Executor `executor_runs` хранит `task_gid`, `worktree_path`, `branch_name`, `pr_url`. | Нет общего индекса актуальных локальных worktrees, связей `repo/worktree/branch/head SHA ↔ PR ↔ Asana task`. Regex проекта не объясняет, что именно ревьюится или решается. Executor охватывает только собственные runs. | `context-links.js`: read-only `git worktree list --porcelain` по зарегистрированным репозиториям, branch/head SHA и явные PR/Asana ссылки; сохранять origin каждой связи и confidence. Проверить один PR с двумя worktrees и один worktree без PR; последний оставить `unknown`. | -| Codex/Claude/Balda и окна | Локальные Codex/Claude session JSONL существуют; metadata содержит `cwd/git` или `cwd/gitBranch` (без чтения бесед). Codex desktop даёт список задач со статусами `active/idle/notLoaded`. Старый Executor имеет отдельные run states и PR links. | Список задач не означает `needs_human`; desktop approval/request, завершённый результат и ответ нельзя вывести из mtime или `idle`. В Personal OS нет адаптера окон/сессий и единой review queue. Balda/Broker развивается отдельно, стабильный контракт пока не подтверждён. | `session-observer.js` читает только metadata и времена; `agent-run-adapters.js` принимает подтверждённые события `running/blocked/needs_human/done`, artifact URL, estimate review minutes и usage. Неизвестный approval = `unknown`. На двух одновременно активных агентах проверить отдельный agent time и один ограниченный human review slot. | -| Личный контекст | В [`aw-projects.json`](file:///Users/admin/Developer/personal-os/aw-projects.json) есть несколько `namespace: personal` проектов и общий класс Documentation/Research. | Статья может быть рабочим исследованием, отдыхом или незапланированным переключением; приложение/домен не доказывают намерение или самочувствие. | `context_type=work_task|work_research|personal_project|leisure_or_break|unknown`; источник/уверенность отдельно. Попросить уточнение лишь когда оно меняет рекомендацию, не более одного в день в пилоте. | - -## Состояние запуска на момент аудита 3 октября, до нового shadow-сбора - -[`com.personalos.readonly.plist`](file:///Users/admin/Developer/personal-os/com.personalos.readonly.plist) описывает 30-минутный `sync → status → attention`, но 3 октября `launchctl` не нашёл загруженный `com.personalos.readonly`. Следовательно, свежие данные Asana были результатом разового запуска; регулярный refresh сейчас не подтверждён. GitHub и ActivityWatch доступны в read-only проверке, но это не означает, что Personal OS регулярно объединяет их в рабочую тему. - -## Минимальный сквозной пилот P0.1 - -**Один реальный рабочий поток:** Asana task с явным запросом к Алексу → связанный browser PR → локальный worktree → Codex/Claude run → итог, ожидающий его ревью. Система показывает текущую тему, источник запроса, свежесть, confidence и отдельно время человека/агента. Вторая ветка: статья или личный проект остаётся `unknown/personal`, пока нет доказательства намерения. Приёмка — 20 вручную проверенных интервалов из двух дней: ни одной ложной high-confidence связи и ни одного выдуманного `needs_human`. - -**Следующий шаг по состоянию на 4 октября:** тихий сбор уже запущен. Проверить 20 интервалов на двух рабочих днях и исправить ложные связи; Outlook ждёт разрешённый Microsoft Graph app. Исполняемые пакеты и условия пилота — [[personal/plans/personal-os-operating-plan-2026-10-03]]. +Актуальная последовательность и критерии: [план E1–E5](../projects/personal-os/personal-os-action-plan-2026-10-05.md). [Текущая готовность](../projects/personal-os/personal-os-production-acceptance.md). diff --git a/personal/plans/personal-os-v2-plan.md b/personal/plans/personal-os-v2-plan.md index c81a0834..e813057b 100755 --- a/personal/plans/personal-os-v2-plan.md +++ b/personal/plans/personal-os-v2-plan.md @@ -1,190 +1,3 @@ ---- -title: Personal OS v2 — план перезапуска -tags: - - personal-os - - plan - - v2 -created: '2026-10-03' -updated: '2026-10-04' -status: draft ---- -# Personal OS v2 — план перезапуска +# План работ Personal OS -> **Текущий план R2:** [[personal/projects/personal-os/personal-os-system-review-index]]. Целевая архитектура и порядок реализации ниже заменены R2; исторические решения и описание прототипа сохранены для происхождения требований. - -> Исторический черновик: предложение полного Swift-порта и расписаний ниже не утверждено как текущая реализация. Сопоставление с работающим Node-контуром и решение на ревью: [[personal/projects/personal-os/personal-os-system-review-index]]. - - -> Исторический черновик 2026-10-03: заменён утверждённым [[personal/plans/personal-os-operating-plan-2026-10-03]]. iPad-идея здесь описывает старый тестовый проект, не новое приложение, создание которого запущено через Balda 4 октября. Текущий статус: [[personal/projects/personal-os/personal-os-status-2026-10]]. -> -> Исходный вход: [[personal/projects/personal-os/personal-os-status-2026-10]] · -> уроки: [[personal/projects/personal-os/personal-os-failed-approaches]]. -> Пометка **⚠️ проверить** = моё допущение, не подтверждено фактом. - -## 0. Цель и рамки - -Быстро вернуть работающий контур «что происходит / что дальше / как я на самом деле работаю», -**без автономных действий**. v2 = наблюдение + отображение + ревью. Никакого Executor, пока не -закрыты контроли из [[personal/projects/personal-os/executor-security-analysis]]. - -Состав v2: -1. Data-слой: Asana + GitHub + ActivityWatch → локальная БД (как было, read-only). -2. **Desk** — дашборд на старом iPad (iOS 9.3.5). -3. Иконки для задач Asana (уникальные, ночная генерация). -4. ActivityWatch++: точная привязка активности к worktree → задаче Asana / личному проекту. -5. Трекинг GitHub PR. -6. Трекинг фокуса + Ретроспектор. -7. Переезд с Node.js на натив. -8. Постоянные AI-сессии ревью (что работает, что нет). - -## 1. Guidelines (обязательны для всех компонентов) - -1. **Read-only во внешние системы.** Asana/GitHub — только GET. Обёртка API в коде разрешает только чтение - (Asana PAT не скоупится на read-only — ⚠️ проверить, значит контроль в коде). -2. **Рабочие данные не покидают Mac/LAN.** Никаких чатов/облачных сервисов как транспорта для данных задач. - iPad получает данные только по LAN. -3. **Redaction до любой модели и до iPad:** стоп-слова SILO, ACP, attorney-client, PIP, termination, - M&A, audit, performance, compensation → задача показывается как «🔒 скрыто», в LLM не уходит. -4. **Защита фокуса:** дашборд пассивный — без звуков, без всплывающих алертов во время focus-блока. -5. **Человек решает:** AI-сессии пишут только в Obsidian (отчёты/предложения), ничего не применяют сами. -6. **Детерминизм по умолчанию, LLM — для суждений** (классификация, выбор иконки, ревью). -7. **Один статус-документ** обновляется при каждом повороте. - -## 2. Целевая архитектура - -``` -Asana API (GET) ─┐ -GitHub (gh/GraphQL, GET) ─┤ -ActivityWatch + новые watchers ─┼─► posd (macOS daemon, launchd) ─► PostgreSQL (как сейчас) -Claude/Codex session logs ─┤ │ reducer + redaction -Calendar (EventKit, позже) ─┘ ├─► dashboard.json + icons/*.png ─► HTTP (LAN) ─► iPad Desk - ├─► status.md / Obsidian daily note - └─► AI-сессии (claude -p, read-only) ─► Obsidian reviews/ -``` - -- БД остаётся **PostgreSQL** — схема и данные уже есть, менять незачем. - -## 3. Desk — дашборд на iPad (iOS 9.3.5) - -Лёгкое приложение, следует guidelines §1: пассивный экран, только чтение, данные по LAN, redaction на стороне Mac. - -### Экран (4 зоны из исходного Desk-дизайна + PR) -1. **Сейчас** — текущий проект/задача (из AW) vs план дня; таймер focus-блока. -2. **Сегодня** — 3–7 задач дня с иконками, статус, дедлайны. -3. **Ждут меня** — комментарии без ответа, review requests, CI failures моих PR. -4. **День** — полоса времени по проектам, focus-score, переключения. -Тап по задаче = только просмотр деталей (без действий во внешних системах). - -## 4. Иконки для задач Asana - -**Задача:** у каждой активной задачи — узнаваемая иконка, **уникальная среди видимых на дашборде**, -стабильная во времени (не меняется, пока задача жива). - -Пайплайн (ночная задача планера дня): -1. Новые/изменённые активные задачи → LLM извлекает 3–5 концептов (на redacted-тексте). -2. Поиск по каталогу иконок (keyword + embedding по тегам/категориям). -3. Выбор первой иконки, **не занятой** другой видимой задачей; в рамках проекта — общий цветовой акцент. -4. Нет подходящей → генерация (LLM → SVG по стилю набора, 24×24 stroke) → валидация (рендер, размер, контраст) → в библиотеку как переиспользуемую. -5. Рендер SVG → PNG @1x/@2x на Mac; кэш по `task_gid` в Postgres (`task_icons`: gid, icon_id, source, created_at). - -**Каталоги — исследовать (не проверено, web в этой сессии не использовался):** -- [ ] **Lucide** — metadata JSON на иконку (tags, categories); лицензия ISC — основной кандидат. -- [ ] **Grida icons** — заявлен как icons database — проверить формат метаданных и лицензии. -- [ ] **NeedIcons** — проверить, что это и есть ли API/датасет. -- [ ] **Damask** — проверить, что это (набор/генератор?). -- Критерии: машиночитаемые теги, SVG, единый стиль, лицензия для личного использования, размер каталога. - -## 5. ActivityWatch++ — привязка активности к задачам - -**Сейчас есть:** aw-watcher-ddg (URL), aw-watcher-xcode (worktree), aw-watcher-vscode (Cursor: файл/проект), window. - -**Добавить:** -| Источник | Как получить worktree | ⚠️ | -|---|---|---| -| **Claude Code CLI / Claude desktop (Code-сессии)** | транскрипты `~/.claude/projects//*.jsonl` — `cwd`, `gitBranch` у сообщений; активность = mtime + последние записи | проверить поля | -| **Codex CLI/desktop** | `~/.codex/sessions/**/rollout-*.jsonl` — `cwd` в session meta | проверить формат | -| **Claude desktop (чат/Cowork)** | только заголовок окна + проект Cowork-сессии; нет cwd → AI-классификация | | -| **VS Code / Cursor** | файл из aw-watcher-vscode → `git rev-parse --show-toplevel` + ветка | | -| **Terminal** | zsh `precmd` hook → heartbeat в AW-бакет (`cwd`, branch) | | -| **Браузер** | URL GitHub PR → ветка; URL Asana → GID напрямую | | - -**Цепочка привязки (детерминированно → AI):** -1. GID в имени ветки (`fix-1234567890-...`, executor-конвенция). -2. Ссылка на Asana в теле PR этой ветки. -3. Ручное правило (`aw-projects.json` / таблица `bindings`). -4. **AI-классификатор** (фоллбек): окно активности + коммиты + заголовки → кандидаты из активных задач - Asana **или личных проектов** (список из Obsidian `personal/projects/`) с confidence. - < порога → «не привязано», вопрос в вечернем ревью; подтверждение → правило (не спрашивать дважды). - -## 6. Трекинг GitHub PR - -База уже есть: `gh-snapshot.js` (мои PR + CI через `statusCheckRollup`, review requests через notifications). -Доработать: -- [ ] Мои открытые PR: draft/ready, CI (какой job упал + ссылка), **неразрешённые review threads** (GraphQL `reviewThreads.isResolved`), возраст, ждёт ли меня ответ. -- [ ] **Для меня на ревью:** `search: is:open review-requested:@me` (надёжнее notifications) + возраст запроса. -- [ ] Связь PR ↔ задача Asana (§5) → в «Ждут меня» и в дневной картине. -- [ ] Метрики для ретро: cycle time PR, время до первого ответа на review, число CI-перезапусков. - -## 7. Фокус и Ретроспектор - -**Фокус (детерминированно из AW):** -- focus-блок = непрерывная работа над одним проектом ≥ 25 мин, переключения < N, AFK < 3 мин. -- метрики дня: deep-work минуты, число блоков, переключения/час, фрагментация, доля «план vs факт». -- источники прерываний: открытия чатов/Asana/почты во время блока. -- Отображение: пассивно на iPad. **Никаких интервенций** во время блока (урок ADHD-профиля); подсказки — только в паузах/вечером. - -**Ретроспектор (еженедельно, AI-сессия, §9):** -- план недели vs факт по проектам; переносы задач; latency ответов на комментарии; PR cycle time; - тренды фокуса; повторяющиеся коррекции. -- Формат: факты с цифрами → 3 паттерна → **один вопрос-решение**. Пишет в Obsidian. - -## 8. Переезд с Node.js на натив - -**Рекомендация: Swift** (SwiftPM, `posd` как launchd-демон). -- Нужны macOS-API: AX (URL браузера), NSWorkspace, EventKit (календарь) — нативно в Swift. -- aw-watcher-ddg уже на Swift; watchers можно влить в один процесс. -- Общие модели с iPad-клиентом. -- Альтернатива **Go** (как Balda: один бинарь, проще сервер) — хуже по macOS-API. Python — только для прототипов. - -**Стратегия «strangler», не big-bang** (иначе «кратчайшие сроки» не выполнимы): -1. Запускаем v2 на **существующем Node-пайплайне** (работал стабильно). -2. Swift-модули пишутся по одному и идут в **shadow-режиме** (тот же вход → сравнение выхода с Node). -3. Порядок: HTTP/dashboard-сервер → AW-агрегатор + watchers → GitHub → Asana sync → отключение Node. - -## 9. Постоянные AI-сессии (ревью, паттерны, что работает) - -Запуск: launchd + `claude -p` (подписка, официальный путь, без прокси) или scheduled tasks; **без -сетевых инструментов записи**, вход — redacted-снимки из БД/файлов, выход — заметки в Obsidian. - -| Сессия | Когда | Что делает | Выход | -|---|---|---|---| -| **Утро / планер дня** | 07:30 будни | план дня из Asana + PR + вчерашнего факта; **генерация иконок** (§4) | `dashboard.json`, daily note | -| **Вечернее ревью** | 18:30 будни | план vs факт, непривязанная активность (вопросы), фокус | `work/reviews/YYYY-MM-DD.md` | -| **Ретроспектор** | Пт 17:30 | недельные паттерны (§7) | `work/reviews/week-YYYY-WW.md` | -| **Мета-ревью системы** | раз в 2 недели | здоровье пайплайна (падения, задержки), какие сигналы я реально использовал/игнорировал, ложные срабатывания; гипотеза → метрика → вердикт | `personal/projects/personal-os/experiments.md` + предложения изменений (не применяются сами) | - -Health-check: каждый запуск пишет heartbeat в БД; дашборд показывает «данные устарели», если > 2 ч. - -## 10. Кратчайший путь к работающей системе - -| Шаг | Срок | Готово, когда | -|---|---|---| -| **S0. Data-слой оживить** — sync.js + generate-status.js через launchd (не Hermes), read-only, проверить status.md | 1 день | свежий status.md каждые 30 мин в рабочие часы | -| **S1. `dashboard.json` + мини HTTP-сервер** (сначала любой: Node/Python, потом Swift) | 1 день | JSON отдаётся по LAN, redaction применён | -| **S2. iPad-приложение: каркас** | 1–2 дня | приложение запускается на iPad и тянет `dashboard.json` | -| **S3. Desk MVP** — 4 зоны, polling, иконки = детерминированный матч по Lucide-тегам | 3 дня | дашборд живёт весь день без ручных действий | -| **S4. PR-трекинг** (§6) + «Ждут меня» | 2 дня | review requests / CI failures видны на iPad | -| **S5. AW++** (Claude/Codex/terminal watchers, цепочка привязки шаги 1–3) | 3–4 дня | ≥ 80% рабочего времени привязано к задаче/проекту | -| **S6. Вечернее ревью + Ретроспектор** (§9) | 2 дня | две недели отчётов в Obsidian | -| **S7. Иконки v2** (уникальность, генерация, ночной прогон) + AI-классификатор (§5 шаг 4) | 1 нед | новые задачи утром уже с иконками | -| **S8. Swift-порт в shadow** (§8) | параллельно, 3–4 нед | Node выключен | -| **S9. Мета-ревью** каждые 2 недели | постоянно | решения о том, что выкинуть/усилить | - -MVP (S0–S3) ≈ **1 неделя**. - -## 11. Открытые решения - -- [ ] Swift vs Go для `posd` (рекомендация — Swift). -- [ ] Где хостить AI-сессии: launchd `claude -p` vs Balda (Balda пока NO-GO → старт с launchd). -- [ ] Calendar-источник для режима MEETING (EventKit локально?). -- [ ] Иконки: результаты проверки Lucide/Grida/NeedIcons/Damask. +Актуальная последовательность и критерии: [план E1–E5](../projects/personal-os/personal-os-action-plan-2026-10-05.md). [Текущая готовность](../projects/personal-os/personal-os-production-acceptance.md). diff --git a/personal/projects/hermes/reference/agent-memory-architecture.md b/personal/projects/hermes/reference/agent-memory-architecture.md new file mode 100644 index 00000000..1d483cf8 --- /dev/null +++ b/personal/projects/hermes/reference/agent-memory-architecture.md @@ -0,0 +1,75 @@ +--- +namespace: work +tags: [system, agent, memory, architecture, ai] +created: '2026-05-18' +updated: '2026-05-18' +last_synced: '2026-05-18' +confidence: 0.85 +sources: + - arXiv 2603.07670 (Memory for Autonomous LLM Agents, март 2026) + - zylos.ai AI Agent Memory Architectures survey (апрель 2026) + - wiki/raw/inbox/research-vault-strategy-memory-20260516.md +--- +# Agent Memory Architecture + +Когнитивная таксономия памяти для LLM-агентов, основанная на arXiv 2603.07670. Применительно к personal-os (Hermes). + +## Три уровня памяти + +| Уровень | Определение | Реализация в Hermes | +|---------|-------------|----------------------| +| **Episodic** | Сессионные логи — что произошло в конкретных взаимодействиях | SQLite + `session_search` ✅ | +| **Semantic** | Факты, предпочтения, постоянное знание | `MEMORY.md` + `USER.md` (нужна curation) | +| **Procedural** | Навыки, workflows, пошаговые паттерны | `skills/` ✅ | + +## Ключевые выводы из arXiv 2603.07670 + +- **Gap между "есть память" и "нет памяти"** > gap между разными LLM backbone. Выбор памяти важнее выбора модели. +- **Без рефлексии агент деградирует:** в Generative Agents эксперименте — 48 ч без memory reflection → repetitive behavior. +- **Summarization drift:** после 3+ циклов сжатия критические инструкции теряются. Решение: vault как immutable store, не только MEMORY.md. + +## Overflow Rule (MEMORY.md) + +Запись в MEMORY.md — только короткие стабильные факты: +- Длина > 150 символов → перенести в vault, оставить pointer +- Содержит пошаговые инструкции → в `skills/` +- Детальный технический контекст → в `wiki/tech/` + +``` +MEMORY.md: "media-pipeline питфолы → wiki/tech/media-pipeline-pitfalls.md" +wiki/tech/media-pipeline-pitfalls.md: (полный разбор) +``` + +## 4-tier pipeline (LLM Wiki v2 / rohitg00) + +Расширенная модель: +``` +Working Memory → сырые наблюдения текущей сессии +Episodic Memory → сжатые саммари сессий +Semantic Memory → кросс-сессионные факты (wiki) +Procedural Memory → паттерны, workflows, skills +``` + +**Confidence scoring:** каждый факт имеет score (кол-во источников, свежесть, противоречия). Устаревает со временем. + +**Event-driven automation:** +- New source → auto-ingest +- Session end → compress into observations +- On query → check if answer worth filing back +- On schedule → periodic lint + +## Правило разграничения (Alex's personal-os) + +``` +MEMORY.md → SSH хосты, namespace rules, токены, конфиги (≤150 chars) +USER.md → предпочтения, стиль (редко меняется) +wiki/tech/ → технические питфолы, баг-паттерны (длинные, с контекстом) +personal/projects/ → статус проектов, дебаггинг-логи +skills/ → процедуры и workflows пошагово +``` + +## Связанные страницы + +- [[personal-os-architecture]] — как память встроена в общий стек +- [[wiki-ingest-process]] — как сессии кристаллизуются в wiki +- [[personal-os-self-modification]] — как система эволюционирует diff --git a/personal/projects/hermes/reference/agent-names-brainstorm.md b/personal/projects/hermes/reference/agent-names-brainstorm.md new file mode 100644 index 00000000..798a27a6 --- /dev/null +++ b/personal/projects/hermes/reference/agent-names-brainstorm.md @@ -0,0 +1,78 @@ +--- +title: "🦅 Brainstorm имён ассистентов" +aliases: ["Имена", "Agent names", "Орёл", "Тайга", "agent-names"] +tags: ["personal", "projects", "personal-os"] +related: + - "[[personal/projects/personal-os/obsidian-vault-strategy]]" + - "[[personal/projects/personal-os/executor-orchestrator-redesign]]" +updated: "2026-05-17" +--- +# 🦅 Brainstorm имён ассистентов + +🌊 +Чайка +Волна +Маяк +Кракен +Парус +Плюх +Килька +Манта + +🕊️ +👉Орёл +Сокол +Чайка + +Вжух +Пыщ +Флип + +Госпожа, +Астра +👉Тайга +Пыщ +Вжух +Кощей +Компьютер +Машина +Центральный +Дом +Скайнет +Ихтиандр +Винт +Эльза +Астра + +Локи +Харон +Фауст +Лилит +Иштар + +Оракул + +Пульс +Компас +Синтез +Фрактал +Атлас +Каскад +Вектор +Палач +Фантом +Тьма +Светоч +Вестник +Искра +Заря +Шорох +Кварк +Блиц +Скар +Голлум +Буцефал +## Связанные заметки + +- [[personal/projects/personal-os/obsidian-vault-strategy]] — стратегия развития vault +- [[personal/projects/personal-os/executor-orchestrator-redesign]] — архитектура агентов diff --git a/personal/projects/hermes/reference/ai-agent-landscape-2026.md b/personal/projects/hermes/reference/ai-agent-landscape-2026.md new file mode 100644 index 00000000..f4dad50c --- /dev/null +++ b/personal/projects/hermes/reference/ai-agent-landscape-2026.md @@ -0,0 +1,91 @@ +--- +tags: + - research + - agents + - landscape + - ai + - trends +created: '2026-09-02' +updated: '2026-09-02' +related: + - personal-os-architecture + - hermes-agent-improvements + - agent-memory-architecture +--- +# AI Agent Landscape — прогресс и тренды (сентябрь 2026) + +> Запрос Whale: «какой сейчас прогресс и что трендится в ИИ-агентских системах как замена текущему Hermes-конфигу». +> Дата обзора: 2026-09-02. Ниша Whale = self-hosted, always-on персонал-агент (Hermes + Obsidian-MCP + cron + webhook + Zulip). + +## Главный вывод + +**Hermes Agent — не «устаревший конфиг», а один из двух доминирующих open-source рантаймов в своей нише** (личный self-hosted агент с memory/skills). Поле «замен» в этой категории очень узкое, и ближайший конкурент OpenClaw не является функциональной заменой, а скорее дополнением (или сценарием «полного переезда», невыгодным после вложенных кастомизаций). Плюс есть движок «пилотирования» / оркестратора сверху. + +## Тренды отрасли (2026) + +- **От демо к инфраструктуре**: 2026 = год, когда агенты перестали быть демо и стали инфраструктурой. Автономность измеряется «как долго агент работает до вмешательства человека» (Prosus State of AI Agents). +- **Adoption gap 4–8×**: 88% orgs используют AI в ≥1 функции, но только 17–23% разворачивают агентов; ≤10% в каждой отдельной функции. Gartner: 40% агент-проектов отменят к 2027 (неясный ROI). +- **Фреймворк-использование ≠ звёзды GitHub**: OpenClaw 345–373K★, Hermes ~110–160K★. Но по фактическому объёму токенов Hermes берёт верх (8.14 трлн cumulative, #1 на OpenRouter с ~апреля-мая 2026). Kейс «звёзды измеряют любопытство, токены — работу». +- **Модельная универсальность = стандарт**: маршрутизация (дорогая модель на сложный reasoning, дешёвая — на фон) едва ли не главный рычаг экономии. Спред 100×+ (open-weight $0.07–0.12/1M против фронтира $15/1M). +- **Память стала конкурентным преимуществом**: gap «есть/нет памяти» важнее gap между backbone-моделями. Три уровня (episodic/semantic/procedural) + proc-memory (навыки как процедурная память) — распространённая зрелая архитектура (ваша уже так построена). +- **Governance/ROI/security — блокер масштабирования**: лучшие практики — least-privilege creds, approval на destructive-действия, аудит скиллов до установки. +- **Регулирование**: EU AI Act high-risk требования вступают в силу с 2026-08-02. Прозрачность фондовых моделей падает (Stanford Transparency Index 40 vs 58 в 2025) → риск для procurement. + +## Матрица «замен» применительно к Whale-конфигу + +### 1. OpenClaw — НЕ замена, конкурент/гибрид +- Gateway «control plane», первая-class интеграции с мессенджерами, 13.7K+ community-скиллов. +- Слабее Hermes по: self-improving learning loop (у OpenClaw скиллы статичны/человеко-писаны), память кросс-сессионная слабее, нет checkpoint/rollback. +- **Security-инциденты**: CVE-2026-25253 (RCE, CVSS 8.8, 40K+ инстансов раскрыты, 63% уязвимы на момент), 341 вредоносных скилла в ClawHub (supply-chain poisoning). +- Миграция: у Hermes есть `hermes claw migrate`. +- *Паттерн комьюнити* (~25% Reddit): **OpenClaw как оркестратор + Hermes как исполнитель** (через ACP/profiles). + +### 2. Кодинг-агенты (Claude Code, Cursor, OpenHands, Swarm…) — НЕ в этой нише +- Если работа — в основном кодинг → релевантны, но способности OpenHands (72% SWE-Bench) к персональному always-on агенту отношения не имеют. Whale этим заниматься не должен. + +### 3. Узкие фреймворки (LangGraph, CrewAI, Microsoft Agent Framework, Google ADK, OpenAI Agents SDK, Mastra, AutoGen) +- Это **продукт-ориентированные SDK для building apps**, НЕ self-hosted персональные рантаймы. Для Whale-сценария — не конкуренты. Полезны как справочник паттернов (оракестрация, human-in-the-loop, observability), но переписывать на них личную систему незачем. + - LangGraph: state control / durable execution лидирует (38M PyPI downloads/mo, v1.0). + - CrewAI: ~44–49K★, role-based teams, 82% task success, но pain points (async, отладка, память). + - Microsoft Agent Framework: наследник AutoGen+Semantic Kernel. + - OpenAI Agents SDK: «opinionated handoff», простые multi-agent. + - AutoGen/AG2: Microsoft перевёл в maintenance (заменён Agent Framework). + +## Куда движется поле — тренды, релевантные Whale + +### a) Длительный автономный ран (суверенность) +- «Deep Agents»/harness для long-running задач (research/coding): планирование + context management. Прямой аналог широты ваших cron-agent'ов. +- Валюта рынка = **continuous-time autonomy**; ставит вопрос о функциях типа pause/resume, отмена mid-flight у Whale агентов. + +### b) Пилотирование/проактивность +- Трендовые личные агенты (rho «checks in on its own», Gaia с расписаниями) — эксперимент: агент сам инициирует. У вас уже есть cron-слой (по расписанию) и watchdogs; рынок двигается в сторону **условно-событийной** проактивности (не только по таймеру). +- Дуальность «timer-driven vs event-driven automation» — зрелая тема в memory stacks (event-driven triggers: new source→ingest etc.). Частично покрыто вашей архитектурой, но выраженно event-driven (на изменения в vault, новые MCP-инструменты) — точка роста. + +### c) Память и контекст +- **Summarization drift** и overflow правила (это у вас уже есть). +- Confidence scoring + temporal decay (smart-aвторы памяти: Mem0/Letta/LangMem pattern) — ваш MEMORY.md overflow и curation похожи, но «система без явного scoring» может добавить confidence + decay для SEMANTIC. +- Сторонние движки памяти (Letta/Mem0/Agno memory) — кандидаты на «апгрейд» semantic-tier позже, но сегодня у вас связка собственный MEMORY + SQLite already. + +### d) Observability / отладка агентов +- LangSmith/её аналоги + «action trace против фактического исполнения» — известная боль CrewAI (traces не отражают реальное исполнение). У вас подход «facts over self-reports», verify handles — уже в правильную сторону. Формальный лог «намерение→факт» — вещь, которую рынок догоняет. + +### e) Физический/десктопный контур +- Desktop app (Hermes v0.16 native desktop, June 2026) и iMessage-support (Photón/Agents, v0.17 June 2026) — движение к «агент в каждом приложении». Вы on macOS + webhook/Zulip — десктопный/локальный контур для вас опционален (Apple-скиллы уже есть: Notes/Reminders/FindMy). + +## Рекомендации (кратко) + +1. **Гонку «сменить фреймворк» не выигрывает никто из альтернатив** — текущий Hermes-конфиг уже implemented лучшие практики (3-tier memory, skills как proc-memory, SOUL.md, Observable vault-as-truth). Switching = решение проблем, которых у вас нет, ценой переписывания кастомизаций. +2. **Присмотреться к OpenClaw** исключительно как к оркестратору на *дополнительных* каналах/аппах, если появится потребность «один агент во всех чатах» шире текущих (webhook/Zulip + локальные скиллы). Не как замена. +3. **Усилить event-driven проактивность** (триггеры на изменение vault/новые файлы/сигналы) поверх timer-driven cron. +4. **Security posture как у фронтира**: least-privilege, approval на деструктив, аудит любых устанавливаемых скиллов (урок из ClawHub poisoning + собственный CVE-опыт Hermes v0.16). +5. **Модельная маршрутизация** — самый дешёвый рычаг снижения токен-расхода в личной системе в 2026. +6. **Не полагаться на звёзды как на критерий** при сравнении — смотреть на устойчивый объём работы (у Hermes он вверху — #1 OpenRouter). + +## Источники +- DEV: 10 Best Open-Source AI Agents 2026 +- Turing Post: Hermes Agent vs OpenClaw (2026-06-13) +- HundredTabs: Hermes vs OpenClaw honest comparison (2026-05-10) — 1,300+ Reddit comments +- Context Studios: OpenClaw vs Hermes 2026 (2026-06-22) +- LangChain: best AI agent frameworks 2026 (2026-06-06) +- DigitalApplied: State of AI Agents 2026 (220+ data points, 2026-05-22) — McKinsey/Stanford HAI/Gartner/IDC +- openclaw/hermes GitHub (статистика на дату обзора) diff --git a/personal/projects/hermes/reference/autonomous-agent-safety.md b/personal/projects/hermes/reference/autonomous-agent-safety.md new file mode 100644 index 00000000..d2afb905 --- /dev/null +++ b/personal/projects/hermes/reference/autonomous-agent-safety.md @@ -0,0 +1,113 @@ +--- +title: Autonomous Agent Safety Patterns +created: '2026-05-24' +updated: '2026-10-14' +type: concept +tags: [agent, security, architecture, executor, rules] +sources: + - wiki/concepts/executor-security-incident.md + - wiki/concepts/executor-orchestrator.md + - wiki/personal-os-agent-rules.md +confidence: high +related: + - "[[personal/projects/personal-os/executor-security-analysis]]" + - "[[personal/projects/personal-os/executor-orchestrator-redesign]]" + - "[[personal-os-agent-rules]]" +--- + +# Autonomous Agent Safety Patterns + +Design principles for autonomous LLM agents distilled from the 2026-05-11 +executor security incident. General enough to apply beyond the personal-os context. + +## The Three Failure Modes (from incident) + +### 1. Mandatory prompt steps that outrank modes + +The executor wrote Asana comments during "recording-only" mode because the +worker prompt declared comment posting a *mandatory completion action* — not +subject to mode flags. + +**Pattern:** Every completion action (write to external system, post comment, +send notification) must be guarded by a mode check that the agent cannot +override. + +``` +IF mode == "recording-only": + SKIP external writes + LOG "would have posted: ..." instead +``` + +### 2. Boundary policies that only cover exfiltration + +The lethal-trifecta policy blocked HTTP to attacker domains after internal +MCP access. It did NOT block writes *to* internal systems (Asana). + +**Pattern:** Separate the threat models: +- **Exfiltration** = data leaving to unauthorized destinations → block outbound +- **Unauthorized writes** = data going to authorized systems without approval → require + explicit confirmation gate per write type + +These are different controls. A policy that only covers one leaves the other open. + +### 3. High-level directives not propagated to sub-prompts + +"Don't touch anything" was a session-level directive. The worker +sub-prompt (spawned per task) didn't inherit it — it ran its own +completion protocol. + +**Pattern:** Mode flags must be passed explicitly to every spawned +sub-process/sub-prompt as a first-class parameter, not assumed from +session context. + +## The Auto-Approve Table Pattern + +From [[personal/projects/personal-os/executor-orchestrator-redesign]]: instead of blanket trust or blanket +denial, classify actions by risk tier: + +| Risk | Action type | Default | +|------|-------------|---------| +| Low | git, build, test, worktree | auto-approve | +| Medium | draft PR, push branch | auto-approve with log | +| High | post Asana comment, merge PR | require Alex confirmation | +| Blocked | autonomous Asana write | denied always | + +This table lives in the orchestrator, not the worker. Workers *request* +actions; orchestrator decides. + +## Least-Privilege Credential Design + +From incident: `ASANA_API_KEY` was full-account CRUD (PATs are not granular). +One compromised agent → full Asana write access. + +**Pattern:** Scope credentials to the minimum required operation: +- Read-only keys for read-only agents +- Write keys injected only at the moment of approved write +- Never persist write credentials in always-on agent environments + +## Audit Before Autonomous + +The incident ran 18 PRs and 5 Asana comments before detection. Detection only +happened because Alex checked manually. + +**Pattern:** Autonomous runs should produce an observable audit trail that +can be reviewed without running the agent: +- Structured log per run (not just stdout) +- Diff-friendly format (what was written, to where, at what time) +- Periodic summary posted to a channel Alex monitors + +## Summary: Checklist for New Autonomous Agents + +- [ ] Every external write is behind a mode-guard (can "recording-only" block it?) +- [ ] Exfiltration and unauthorized-write policies are separate controls +- [ ] Mode flags propagate explicitly to sub-prompts +- [ ] Auto-approve table is in the orchestrator, not the worker +- [ ] Credentials are scoped to minimum; write keys not always-on +- [ ] Each run produces a structured audit log +- [ ] Audit log goes somewhere Alex sees without hunting + +## See Also + +- [[personal/projects/personal-os/executor-security-analysis]] — incident post-mortem with full timeline +- [[personal/projects/personal-os/executor-orchestrator-redesign]] — post-incident architecture (orchestrator pattern) +- [[personal-os-agent-rules]] — Eagle's specific rules derived from these patterns diff --git a/personal/projects/hermes/reference/claude-proxy-node-internals.md b/personal/projects/hermes/reference/claude-proxy-node-internals.md new file mode 100644 index 00000000..96498bc4 --- /dev/null +++ b/personal/projects/hermes/reference/claude-proxy-node-internals.md @@ -0,0 +1,181 @@ +--- +title: openclaw-claude-proxy (Node.js) — внутреннее устройство и проблемы +type: reference +namespace: personal +tags: + - hermes + - mac + - eagle + - claude-proxy + - nodejs + - llm-backend + - pitfalls + - docker +created: '2026-06-15' +updated: '2026-06-15' +confidence: 0.9 +--- +# openclaw-claude-proxy (Node.js) — внутреннее устройство и проблемы + +## Обзор + +**npm пакет:** `openclaw-claude-proxy` v1.0.8+ +**Порт:** 3456 +**Язык:** TypeScript (компилируется в JS) +**Репозиторий:** [mehdic/openclaw-claude-proxy](https://github.com/mehdic/openclaw-claude-proxy) +**Форк:** `mnemon-dev/claude-max-api-proxy` + OpenClaw compatibility PR +**Текущий статус:** fallback (активен Python wrapper на порту 8090) + +## Архитектура + +``` +Hermes → POST /v1/chat/completions (порт 3456, Node.js Express) + └── proxy преобразует OpenAI-формат → stream-json протокол + └── спавнит claude CLI как child process + └── claude --output-format stream-json --verbose + └── читает/пишет JSON через stdin/stdout pipe +``` + +### Runtime-модели (CLAUDE_PROXY_RUNTIME) + +**stream-json** (default): +- init pool: несколько долгоживущих `claude` subprocess'ов +- session pool: переиспользование сессий между запросами +- промпт-кэш между вызовами сохраняется +- использует `--output-format stream-json --input-format stream-json` + +**print** (fallback): +- на каждый запрос spawn'ит свежий `claude --print` +- медленнее, но изолированно +- не требует совместимости stream-json протокола + +## Контейнерный сетап + +`~/Docker/claude-proxy-node/Dockerfile` — образ на node:20-alpine: +``` +FROM node:20-alpine +RUN npm install -g openclaw-claude-proxy @anthropic-ai/claude-code +EXPOSE 3456 +CMD ["claude-proxy", "3456"] +``` + +Образ не собран — в работе. + +## Проблемы + +### 1. Orphaned claude subprocess'ы + +**Механизм:** `stream-json` runtime держит пул долгоживущих `claude` child process'ов через `child_process.spawn()`. Proxy управляет их жизненным циклом: при нормальном shutdown (SIGTERM) должен завершить pool. Но: + +- **SIGKILL** родительского proxy (kill -9, docker stop --time=0, launchd force quit) — Node.js не успевает выполнить cleanup +- **SIGTERM с таймаутом** — если graceful shutdown превышает лимит времени, Node.js процесс убивается до завершения pool +- **launchd KeepAlive** — при падении proxy по любой причине launchd убивает и перезапускает, но старые `claude` процессы с PPID 1 остаются в системе +- **docker restart** — если контейнер перезапускается без `--time` (grace period), старые процессы переживают контейнер + +На macOS orphan'ы выглядят как `claude` с PPID=1. Их количество растёт со временем. + +### 2. Нет живого вывода claude CLI + +**Причина:** proxy читает stdout `claude` исключительно как JSON pipe. Человеческий вывод markdown/thinking/прогресса `claude` пишет в **stderr**, но proxy его не форвардит. + +По умолчанию stderr `claude` либо: +- не пипруется вообще (pipe не открывается) — stderr уходит в /dev/null контейнера +- пипруется и выбрасывается + +В режиме `print` проблема та же — proxy ждёт завершения `claude --print` и возвращает результат целиком, не транслируя промежуточный вывод. + +### 3. Claude CLI сам исполняет инструменты вместо Hermes + +**Проблема:** Claude Code CLI **сам выполняет Bash/Read/Write/Edit инструменты внутри своей сессии**, а не возвращает tool_use блоки Hermes'у для исполнения. + +Текущий flow: + +``` +Hermes → claude-proxy (Node.js) → claude CLI + └── сам делает Bash, Read, Write + └── bash -c "..." +``` + +Hermes видит только финальный текст ответа. Он теряет контроль над: +- какие файлы читаются +- какие команды выполняются +- кто их логирует и аудитит +- allower/denier политики Hermes игнорируются + +Правильный flow (caller-dispatched tools): + +``` +Hermes → claude-proxy (Node.js) → claude CLI (только генерация) + ↓ текст ответа с tool_use блоками +Hermes ── парсит tool_use ── выполняет через свои инструменты ── результат → обратно в claude CLI +``` + +Для этого proxy должен: +1. Выключить инструменты в `claude` CLI — передать `disallowed_tools = ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]` +2. Остановиться после первого assistant-сообщения +3. Отдать tool_use блоки Hermes'у как OpenAI `tool_calls` +4. Принять результат выполнения от Hermes и передать обратно в `claude` для продолжения (multi-turn) + +**Текущий `openclaw-claude-proxy` не поддерживает этот flow корректно:** stream-json протокол для multi-turn interaction сломан начиная с claude CLI 2.1.141. В режиме `print` multi-turn вообще невозможен. + +**Python wrapper (`claude-code-openai-wrapper`) этот flow поддерживает** — у него есть `stop_after_first_assistant` и `disallowed_tools`. Именно поэтому он активен, а Node.js — fallback. + +## Обзор альтернатив + +| Проект | Язык | Проблема 1 (orphaned) | Проблема 2 (вывод CLI) | Проблема 3 (caller-dispatched tools) | +|--------|------|-----------------------|------------------------|--------------------------------------| +| `openclaw-claude-proxy` (порт 3456) | TypeScript | ❌ — pool без SIGTERM cleanup | ❌ — stderr не форвардится | ❌ — stream-json сломан с CLI ≥ 2.1.141 | +| `claude-code-openai-wrapper` (RichardAtCT, порт 8090) | Python | ❌ — uvicorn без tini | ❌ — SDK pipe без логирования | ✅ — `stop_after_first_assistant` + `disallowed_tools` | +| `claude-code-openai-wrapper` (clebermasters) | Rust | ❌ — tokio без reaper | ❌ — pipe | ❌ — CLI сам исполняет инструменты | +| `claude-max-api-proxy` (mnemon-dev) | TypeScript | ❌ | ❌ | ❌ — родительский проект openclaw | +| **Hermes `provider: claude-code`** | встроен | N/A | N/A | ✅ — но упирается в rate limit OAuth API | + +**Ни один существующий проект не решает все три проблемы одновременно.** + +### `openclaw-claude-proxy` — форки и состояние + +Репозиторий [mehdic/openclaw-claude-proxy](https://github.com/mehdic/openclaw-claude-proxy): +- **v1.0.8** (May 2026) — последний релиз +- 2 форка (habibtalik, ppcvote), 0 звёзд +- Нет открытых issues +- **subprocess/manager.ts** (311 строк): `spawn()` + `EventEmitter`, есть `disallowedTools` в опциях, но они работают только в `--print` режиме. В `stream-json` режиме multi-turn сломан протоколом CLI ≥ 2.1.141. +- `kill()` отправляет SIGTERM на один процесс, но **глобального cleanup при SIGTERM/SIGKILL родителя нет**. + +### `clebermasters/claude-code-openai-wrapper` (Rust) + +Альтернатива, переписанная на Rust: +- Один статический бинарник 4.7 MB, без зависимостей времени выполнения +- Использует `tokio::process::Command` + `--print --output-format stream-json` +- Проблемы те же — запускает `claude` как subprocess, CLI сам исполняет инструменты +- Проект новый — 0 issues, 0 форков + +### `claude-code-openai-wrapper` (RichardAtCT, Python) + +Единственный проект, решающий **проблему 3** (caller-dispatched tools): +- Логика: `stop_after_first_assistant` останавливает итерацию после первого assistant-сообщения, `disallowed_tools=['Bash','Read',...]` не даёт CLI самому исполнять инструменты +- Возвращает tool_use блоки как OpenAI `tool_calls` для исполнения Hermes'ом +- Проблема 1 (orphaned): если запущен через uvicorn без `--init`, при SIGKILL дочерний `claude` процесс остаётся orphan. SDK `atexit` не срабатывает при SIGKILL. +- Проблема 2 (вывод): SDK читает stdout `claude` через pipe → JSON → memory channel. Человеческий вывод не транслируется. stderr CLI читается тихо в `_handle_stderr` и никуда не выводится. + +## Предложенные подходы + +### Против orphaned процессов (все проекты) + +1. **Docker `--init` флаг:** запускать контейнер с `init: true` в docker-compose (или `docker run --init`). Использует `tini` как PID 1 — корректно форвардит SIGTERM и перезахоранивает orphan'ов. +2. **SIGTERM handler:** в Node.js — `process.on('SIGTERM', pool.killAll())`, в Python — `uvicorn` lifespan shutdown c force kill. +3. **Health check + restart policy:** `unless-stopped` с `--time=30` grace period. + +### Против отсутствия вывода CLI + +1. **Python SDK:** добавить `stderr` callback в `ClaudeAgentOptions`, который пишет в `stderr` uvicorn → видно в `docker logs`. +2. **Node.js proxy:** форвардить stderr `claude` в stderr родителя. +3. **Логирование JSON:** логировать каждую N-ную строку из stdout `claude` для отладки. + +### Против изоляции инструментов (caller-dispatched tools) + +Единственное работающее решение — **Python wrapper** (`claude-code-openai-wrapper` RichardAtCT) с: +- `stop_after_first_assistant = True` +- `disallowed_tools = ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep']` +- `permission_mode = 'bypassPermissions'` + +Для полного решения всех трёх проблем нужно взять Python wrapper, запустить в Docker с `init: true` и добавить проброс stderr из SDK. diff --git a/personal/projects/hermes/reference/claude-python-cli-proxy.md b/personal/projects/hermes/reference/claude-python-cli-proxy.md new file mode 100644 index 00000000..3a840971 --- /dev/null +++ b/personal/projects/hermes/reference/claude-python-cli-proxy.md @@ -0,0 +1,219 @@ +--- +title: claude-code-openai-wrapper — Python Claude CLI Proxy +type: reference +namespace: work +tags: + - hermes + - mac + - eagle + - claude-proxy + - python + - llm-backend + - pitfalls +created: 2026-06-03 +updated: 2026-06-03 +confidence: 0.95 +--- + +# claude-code-openai-wrapper — Python Claude CLI Proxy + +OpenAI-compatible FastAPI server that wraps the `claude` CLI via the official +`claude-agent-sdk`. Runs at **port 8090** on Eagle. Hermes uses it as its LLM +backend (`base_url: http://localhost:8090/v1`). + +## Why this exists + +Hermes needs an OpenAI-compatible endpoint that routes calls through the local +`claude` CLI session (Max/OAuth subscription, no API key). Two wrappers were +evaluated — see below. The Python one is currently active. + +### Node.js wrapper (port 3456) — status: broken streaming, kept as fallback + +**Package:** `openclaw-claude-proxy` v1.0.8 (npm) +**Repo:** [mehdic/openclaw-claude-proxy](https://github.com/mehdic/openclaw-claude-proxy) +**LaunchAgent:** `ai.claude-proxy.plist` → `~/.local/bin/claude-proxy-start.sh` + +**Issue:** uses a reverse-engineered `stream-json` protocol to talk to `claude` +as a long-lived subprocess. This protocol broke with claude CLI ≥ 2.1.141. +Streaming requests stall after the initial role chunk — only keepalives come +through. Non-streaming (`--print` fallback path) still works. + +The proxy has `CLAUDE_PROXY_RUNTIME=stream-json` (default) and +`CLAUDE_PROXY_RUNTIME=print` (fallback). Switching to `print` fixes +hangs but removes true incremental streaming. + +--- + +### Python wrapper (port 8090) — status: **active** + +**Repo:** [RichardAtCT/claude-code-openai-wrapper](https://github.com/RichardAtCT/claude-code-openai-wrapper) +**Local path:** `/Users/admin/openclaw/claude-proxy/` +**Version (pyproject.toml):** 2.2.0 +**SDK:** `claude-agent-sdk` 0.2.88 (updated June 2026 from 0.1.56) +**Bundled CLI:** 2.1.161 (inside SDK venv, used instead of system CLI — see pitfalls) +**LaunchAgent:** `com.openclaw.claude-proxy.plist` → `~/.local/bin/claude-python-proxy-start.sh` + +#### How it works + +``` +Hermes → POST /v1/chat/completions (port 8090) + └── FastAPI (uvicorn) + └── claude-agent-sdk query() + └── spawns .venv/…/_bundled/claude 2.1.161 + --output-format stream-json --verbose + (reads CLAUDE_CODE_OAUTH_TOKEN from env) + → streams AssistantMessage events → SSE chunks +``` + +Key: the SDK uses its own **bundled** `claude` binary (not the system one at +`/opt/homebrew/bin/claude`) because the SDK's stream-json protocol must match +the exact CLI version it was built against. + +#### Hermes config + +`~/.hermes/config.yaml`: +```yaml +model: + default: claude-sonnet-4-6 + provider: custom + base_url: 'http://localhost:8090/v1' +``` + +--- + +## What was fixed (June 2026) + +### 1. Venv Python version mismatch + +Venv was created with Python 3.14.3, Homebrew had upgraded to 3.14.5. +Compiled C extensions (`.so` files) were incompatible → `pip install` crashed +with `ImportError: Symbol not found: _XML_SetAllocTrackerActivationThreshold`. + +**Fix:** rebuilt venv with `uv`: +```bash +cd /Users/admin/openclaw/claude-proxy +uv venv .venv --python python3.14 --clear +uv pip install fastapi "uvicorn[standard]" pydantic python-dotenv httpx \ + sse-starlette python-multipart claude-agent-sdk slowapi +``` + +### 2. SDK too old — bundled CLI mismatch + +`claude-agent-sdk` 0.1.56 bundled `claude` 2.1.92. Between 2.1.92 and +2.1.141+, Anthropic changed how the stream-json protocol is initiated: +- Old: inferred from `--output-format stream-json` +- New: requires `--input-format stream-json` flag explicitly + +Result: SDK sent `control_request` on stdin; new CLI ignored it (no output, +exited code 1). + +**Fix:** `uv pip install claude-agent-sdk` → upgraded to 0.2.88, bundled CLI +2.1.161 which matches the updated SDK protocol. + +### 3. `cli_path=SYSTEM_CLAUDE_PATH` override + +The wrapper hard-coded `cli_path = shutil.which("claude")` (system 2.1.145) +in `ClaudeAgentOptions`. This forced the SDK to use the system CLI instead +of its own bundled binary, breaking the protocol handshake. + +**Fix:** set `SYSTEM_CLAUDE_PATH = None` in `src/claude_cli.py` so the SDK +auto-discovers and uses its bundled CLI. + +### 4. LaunchAgent missing auth token + +The original plist ran `uvicorn` directly and only set `CLAUDE_AUTH_METHOD=cli`. +The `claude` subprocess (spawned by the SDK) inherits the process env, which +had no `CLAUDE_CODE_OAUTH_TOKEN`. CLI responded: *"Not logged in"*. + +**Fix:** added wrapper script `~/.local/bin/claude-python-proxy-start.sh` that +sources `~/.hermes/.env` before starting uvicorn (same pattern as the Node.js +proxy). Updated plist `ProgramArguments` to call the wrapper instead of +uvicorn directly. + +### 5. Expired OAuth token (root cause of 401s) + +`CLAUDE_CODE_OAUTH_TOKEN` in `~/.hermes/.env` expires (access tokens are +short-lived). When the stored token is expired and passed to the CLI +explicitly via env, the CLI uses it as-is → 401 from Anthropic API. The +CLI does **not** auto-refresh when `CLAUDE_CODE_OAUTH_TOKEN` is set to an +expired value in the env. + +**Symptom:** both proxies return `401 Invalid authentication credentials` +even though `claude` works fine in the terminal (terminal has a fresh token +from a previous session). + +**Immediate fix:** copy fresh token from terminal into `~/.hermes/.env`: +```bash +# In the terminal that has a working claude session: +grep CLAUDE_CODE_OAUTH_TOKEN <(env) +# Then update: +sed -i '' "s|CLAUDE_CODE_OAUTH_TOKEN=.*|CLAUDE_CODE_OAUTH_TOKEN=|" \ + ~/.hermes/.env +# Restart both proxies: +launchctl unload ~/Library/LaunchAgents/ai.claude-proxy.plist +launchctl load ~/Library/LaunchAgents/ai.claude-proxy.plist +launchctl unload ~/Library/LaunchAgents/com.openclaw.claude-proxy.plist +launchctl load ~/Library/LaunchAgents/com.openclaw.claude-proxy.plist +``` + +**Long-term:** a token-refresh cron/daemon that keeps `~/.hermes/.env` updated +is needed. Not yet implemented. + +--- + +## Wrapper script + +`~/.local/bin/claude-python-proxy-start.sh`: +```bash +#!/bin/zsh +set -a +source /Users/admin/.hermes/.env 2>/dev/null +set +a +export PATH="/Users/admin/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:$PATH" +cd /Users/admin/openclaw/claude-proxy +exec .venv/bin/python -m uvicorn src.main:app --host 127.0.0.1 --port 8090 +``` + +## LaunchAgent + +`~/Library/LaunchAgents/com.openclaw.claude-proxy.plist`: +```xml +ProgramArguments + + /bin/zsh + /Users/admin/.local/bin/claude-python-proxy-start.sh + +WorkingDirectory +/Users/admin/openclaw/claude-proxy +StandardOutPath/tmp/claude-proxy.log +StandardErrorPath/tmp/claude-proxy.err +``` + +## Pitfall summary + +| Pitfall | Symptom | Fix | +|---------|---------|-----| +| Token expired in `.env` | 401 from both proxies, terminal claude works | Copy fresh token from terminal to `~/.hermes/.env`, restart proxies | +| Venv Python version mismatch | `pip` crashes, `ImportError` on `.so` | Rebuild with `uv venv --clear`, reinstall deps | +| `cli_path` set to system claude | SDK exits code 1, no response | Set `SYSTEM_CLAUDE_PATH = None` in `src/claude_cli.py` | +| LaunchAgent has no OAuth token | "Not logged in" | Wrapper script must `source ~/.hermes/.env` | +| SDK version too old | CLI protocol mismatch, exit code 1 | `uv pip install claude-agent-sdk` to update | +| Node.js proxy stream-json | Streaming hangs after role chunk | Use Python proxy on 8090 instead | + +## Health check + +```bash +curl http://localhost:8090/health +curl http://localhost:8090/v1/auth/status +# Test streaming: +curl -s -X POST http://localhost:8090/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{"model":"claude-haiku-4-5-20251001","messages":[{"role":"user","content":"hi"}],"stream":true}' +``` + +--- + +## Related + +- [[hermes-eagle-mac]] — full Eagle setup including Zulip, MCP, launchd +- [[hermes-deployment-patterns]] — comparison of Eagle/Kraken deployment models diff --git a/personal/projects/hermes/reference/claude-wrapper-proxy.md b/personal/projects/hermes/reference/claude-wrapper-proxy.md new file mode 100644 index 00000000..81f64323 --- /dev/null +++ b/personal/projects/hermes/reference/claude-wrapper-proxy.md @@ -0,0 +1,54 @@ +# Claude Wrapper Proxy — Docker + +## Расположение + +| Item | Value | +|------|-------| +| Путь | `~/Docker/claude-wrapper-proxy/` | +| Compose | `docker-compose.yml` | +| Dockerfile | `Dockerfile` | +| Env | `.env` — содержит `CLAUDE_CODE_OAUTH_TOKEN` | +| Порт | 3457 (хостовый на 3456) | + +## Основа + +ChrisCross3/claude-proxy-full — самый продвинутый форк с MCP injection, Isolated mode, Caller-Dispatched Tools. + +## Проблемы + +### "Not logged in" при старте + +**Причина**: OAuth токен expired. `~/.claude/.credentials.json` имеет `expiresAt`, который истекает. Claude CLI не может обновить через read-only volume. + +**Решение**: передать `CLAUDE_CODE_OAUTH_TOKEN` в `.env`. Токен берётся из живой сессии Claude CLI или из `.hermes/.env`. + +### Node.js на Alpine не отвечает на внешние запросы + +**Причина**: `index.js` слушает на `127.0.0.1` внутри контейнера. Docker port mapping не перенаправляет с `0.0.0.0` на `127.0.0.1`. + +**Решение**: в Dockerfile пропатчен `index.js` — `host` заменён с `127.0.0.1` на `0.0.0.0`. + +### JsonWebTokenError при старте + +**Причина**: пустой OAuth токен. Claude CLI внутри контейнера требует `CLAUDE_CODE_OAUTH_TOKEN` в env. + +**Решение**: токен передан через `.env` + env_file в docker-compose. + +## Сборка и запуск + +```bash +cd ~/Docker/claude-wrapper-proxy +docker-compose build +docker-compose up -d +``` + +Проверка: `curl http://localhost:3457/v1/health` → должен вернуть `Hello.` + +## Использование в Hermes + +В `~/.hermes/config.yaml`: +```yaml +providers: + claude: + base_url: http://localhost:3457/v1 +``` diff --git a/personal/projects/hermes/reference/eagle-dashboard.md b/personal/projects/hermes/reference/eagle-dashboard.md new file mode 100644 index 00000000..e798a4ec --- /dev/null +++ b/personal/projects/hermes/reference/eagle-dashboard.md @@ -0,0 +1,346 @@ +# Eagle Dashboard + +Process supervisor and control panel for all Eagle local services. + +**URL:** `http://localhost:8880` (internal) · `https://dashboard.qentra.top` (external, token-required) +**Source:** `~/Developer/eagle-dash/` +**LaunchAgent:** `com.eagle.dashboard` (single Login Item, KeepAlive=true) + +--- + +## Management Policy + +**Hermes gateway (Eagle и Whale) стартуются, стопаются и перезапускаются ТОЛЬКО через Eagle Dashboard или его API (`POST /api/services//start|stop|restart`).** + +Нельзя: +- `kill` процесс Hermes вручную +- `launchctl` stop/start Hermes +- supervisorctl +- любой другой прямой способ + +Dashboard supervisor управляет процессами через PID-файлы, отслеживает состояние, не рестартует после ручного стопа (`stop` выставляет флаг, autorestart игнорируется до явного `start`). Health check верится по supervisor PID (точное совпадение), а не по подстроке в cmdline. + +Для дашборда самого (`com.eagle.dashboard`, type: self) — кнопки управления скрыты, так как supervisor не может restart/stop/start свой процесс. + +### 🔴 Текущее состояние hermes-сервисов (проверено 2026-09-29) + +``` +id | autostart | pid | состояние +hermes | false | none | ОСТАНОВЛЕН Alex'ом — не перезапустится +hermes_whale | true | 12706 | работает (Кит) +``` + +Алекс **осознанно отключил Eagle** через дашборд. Проверка состояния одной командой: + +```bash +curl -s http://127.0.0.1:8880/api/services \ + | jq -r '.[] | select(.id|test("hermes")) | "\(.id) | autostart=\(.autostart) | pid=\(.supervisor.pid // "none")"' +``` + +⚠️ **`autostart=false` + `pid=none` = сервис НЕ поднимется сам.** Это ожидаемое состояние, +не поломка. Не «чинить» его запуском. +📌 Поле `autostart` берётся из `services.yaml`; `running` в API лежит **вложенно** в +`supervisor`, не на верхнем уровне (иначе увидишь `running=null` и решишь, что сервис мёртв). + +## Architecture + +FastAPI + HTMX + Tailwind CDN + Alpine.js. No build step, CDN-only frontend. + +``` +~/Developer/eagle-dash/ +├── main.py # FastAPI app, lifespan, SSE +├── auth.py # Origin-aware auth: 127.0.0.1 → free; cloudflared → token +├── supervisor.py # PID-file-based process supervisor (asyncio, setsid) +├── registry.py # Service registry + YAML loader +├── health.py # Health checks: http / port / process / launchctl +├── control.py # /restart /stop /start endpoints +├── memory.py # RSS tracking (main process + children) +├── loader.py # services.yaml loader +├── services.yaml # Service definitions (source of truth) +├── .env # EAGLE_TOKEN= (not committed) +├── templates/ +│ └── index.html # Dashboard UI — 4 tabs: Services, Crons, Pages, Files +└── com.eagle.dashboard.plist +``` + +### Auth + +- `127.0.0.1` direct access → no auth +- Requests via cloudflared (have `X-Forwarded-For`) → require `Authorization: Bearer ` + or `eagle_token` cookie (set on first login, 30-day expiry) +- Token stored in `.env` + +### Supervisor (supervisor.py) + +PID-file-based — survives Dashboard restarts without crashing. + +- Services launched with `start_new_session=True` (setsid) → run in own session +- PID written to `~/.eagle-dash/pids/.pid` immediately on launch +- On Dashboard restart: reads PID file → if process alive → adopts without re-launching +- If process dead → launches fresh +- Auto-restart with exponential backoff (2s → 60s max) + +### macOS integration + +- `pf` anchor: `localhost:80` → `127.0.0.1:8880` (setup-pf-redirect.sh) +- cloudflared tunnel: `dashboard.qentra.top` → `localhost:8880` +- FileBrowser: `http://127.0.0.1:8181` (FB_NOAUTH=true, auth delegated to Dashboard) + +--- + +## Services + +24 services in `services.yaml`, 10 with `autostart: true`. Секция **Docker** — сервисы, запускающиеся через docker-compose — отображается первой в дашборде. + +### Docker + +| ID | Name | Access | Type | +|----|------|--------|------| +| zulip | Zulip Connector | localhost | container | +| filebrowser | FileBrowser | localhost | container | + +### AI + +| ID | Name | Access | Type | +|----|------|--------|------| +| hermes | Hermes Eagle | localhost | daemon | +| hermes_whale | Hermes Whale | localhost | daemon | +| claude_proxy_node | Claude Proxy (node) | localhost | daemon | +| claude_proxy_python | Claude Proxy (python) | localhost | daemon | +| asana_mcp | Asana MCP | localhost | daemon | +| virfield | [[personal/projects/virfield\|Virfield (Tart + SSH nodes)]] | `127.0.0.1:7780` by default | system Virfield LaunchDaemon; dashboard integration not verified | + +### ML + +| ID | Name | Access | Type | +|----|------|--------|------| +| mlx_lm | MLX LM Server | lan (0.0.0.0:8080) | on-demand | +| ollama | Ollama | lan (0.0.0.0:11434) | on-demand | + +### Reflect + +| ID | Name | Access | Type | +|----|------|--------|------| +| reflect_proxy | Reflect Proxy | lan | daemon | +| reflect_fdroid | Reflect F-Droid Server | lan | daemon | + +### Monitoring + +| ID | Name | Access | Type | +|----|------|--------|------| +| aw_ddg | AW Watcher DDG | localhost | daemon | +| aw_xcode | AW Watcher Xcode | localhost | daemon | + +### Orchestration + +| ID | Name | Access | Type | +|----|------|--------|------| +| wiki_ingest | Wiki Ingest | localhost | cron | + +**Remaining LaunchAgents (not under Dashboard):** +- `com.colima.start` — Homebrew managed +- `homebrew.mxcl.postgresql@17` — Homebrew managed +- `personal.os.wiki-ingest` — cron schedule +- `com.personalos.heartbeat` — cron schedule + +--- + +## Network Access Badges + +- 🟢 `localhost` — bound to 127.0.0.1, safe +- 🟡 `lan` — bound to 0.0.0.0, accessible on home network (mlx_lm, ollama) +- 🔵 `tunnel` — cloudflared-managed, token-protected + +--- + +## Tabs — заглушка урл + +Каждый таб имеет свой URL через `?tab=` query-параметр. Переключение через Alpine.js `setUrlTab()`, который использует `history.replaceState()`. При загрузке `activeTab` инициализируется из `URLSearchParams` (с fallback на `'services'`). При клике на таб URL обновляется без перезагрузки страницы. Бэкенд также принимает `?tab=` в `GET /` и передаёт его как `initial_tab` в шаблон (пока не используется). + +**Урлы:** +- `http://dashboard.qentra.top/` — Services +- `http://dashboard.qentra.top/?tab=crons` — Crons +- `http://dashboard.qentra.top/?tab=pages` — Pages +- `http://dashboard.qentra.top/?tab=files` — Files + +## Tabs + +**Services** — health cards with: status badge, PID, uptime, memory (RSS + children), start/stop/restart controls, log tail drawer (last 200 lines). + +**Pages** — URL input + metadata table for `/Library/WebServer/Documents/*.html` test pages. Each row shows filename, title, purpose, contents, modified date, and opens the page in a new browser tab. + +### Как добавить страницу в Pages (2026-08-24, проверено) + +Механика — просто копия `*.html` файла в webroot `/Library/WebServer/Documents/`. Дашборд читает каталог **живьём** через `GET /api/pages` → `_read_page_metadata()` — рестарт дашборда и `launchctl kickstart` **не нужны**. Страница отдаётся по `/local-pages/` (mount `app.mount("/local-pages", StaticFiles(...))`). + +Метаданные парсятся из HTML: +| Поле дашборда | Источник | +|---|---| +| `title` | `...` | +| `purpose` | ``, fallback — `` | +| `contains` | `` | + +**Pitfall — относительные `href`/`src`:** если страница ссылается на свои `.js`/`.css` относительными путями (как `bilety.html` → `bilety.js`, `bilety.css`), эти файлы тоже обязаны лежать рядом в `/Library/WebServer/Documents/`, иначе запрос уйдёт на `/local-pages/bilety.js` и не найдётся. + +**Pitfall — права (блокер):** `/Library/WebServer/Documents/` имеет public write permission, sudo. не требуется для записи в него: cp ~/Downloads/bilety.* /Library/WebServer/Documents/`. + +**Files** — FileBrowser iframe at `http://localhost:8181`. + +**Crons** (2-я вкладка) — управление cron jobs из 3 источников: +- **Hermes Eagle** (22 jobs) — read/write напрямую в `~/.hermes/cron/jobs.json` +- **Hermes Whale** (0 jobs) — read/write в `~/.hermes/hermes-whale/cron/jobs.json` +- **Launchd (User)** — launchd plist-ы из `~/Library/LaunchAgents/` с `StartInterval` или `StartCalendarInterval` (редактируемые через launchctl + plistlib) + +Для каждого крона на карточке: name, schedule, enabled/disabled, last run, prompt preview, chips (skills, toolsets, model, workdir). Кнопки: +- **+ Cron** — создать новый крон (выбор source: Hermes Eagle / Hermes Whale / Launchd (User)). При выборе Launchd поля Deliver, Prompt, Model/Provider, Skills/Toolsets динамически скрываются через `x-show="cronModal.source !== 'launchd'"`. +- ✎ — открыть модал редактирования всех полей (name, schedule, deliver, prompt, script, model, provider, skills, toolsets, workdir) +- ⏸/▶ — pause/resume (toggle enabled) +- 🗑 — удалить крон + +||**Launchd create** — `POST /api/crons` с `source=launchd` генерирует plist. Принимает: `name` (→ Label, префикс `com.` если не указан), `schedule` (только `every Ns/m/h/d` → StartInterval в секундах), `script` (→ ProgramArguments, разбивка по пробелам), `workdir` (→ WorkingDirectory), `run_at_load` (→ RunAtLoad, boolean, default false). Cron-выражения и ISO-даты для launchd **не поддерживаются** — валидатор на фронтенде их отклоняет с сообщением "Launchd: используйте every 30m / every 2h / every 1d". Поля prompt, deliver, skills, toolsets, model, provider игнорируются. Backend парсит `every N` + суффикс s/m/h/d → множитель 1/60/3600/86400. + +**RunAtLoad** — чекбокс \"Run on load\" в модалке создания/редактирования launchd крона. Сквозь `x-show="cronModal.source === 'launchd'"` показывается только для launchd. Описание: \"запускать при логине / загрузке системы\". При открытии редактирования — читается из `c.run_at_load` (backend отдаёт `plist.get("RunAtLoad", False)`). Сохраняется как `body.run_at_load → pd["RunAtLoad"]`. По умолчанию `false`. + +**`_list_launchd_crons()`** теперь показывает **все** plist-ы из `~/Library/LaunchAgents/`, не только с StartInterval/StartCalendarInterval. Для plist без schedule — `schedule: "none (manual)"`. Это фикс: раньше plist без schedule (например созданный с cron-выражением) не отображался в дашборде. + +**Schedule input — формат подсказки и валидация зависят от source:** + +- Для **launchd**: подсказка только `every 30s / 30m / 2h / 1d — интервал`. Плейсхолдер `every 30m / every 2h`. Валидатор reject cron и ISO. +- Для **Eagle/Whale**: полная cron-схема (5 полей), пояснения `*`, `*/N`, `N-M`, `A,B`, `N`, плюс `every 30s / 30m / 2h / 1d` и ISO-дата. + +**Schedule hint** — сворачиваемый multiline блок над полем ввода, открывается по кнопке `? подсказка`. Финальный рабочий текст: + +``` +┌── минута (0-59) +│ ┌── час (0-23) +│ │ ┌── день месяца (1-31) +│ │ │ ┌── месяц (1-12) +│ │ │ │ ┌── день недели (0-6, вс=0) +│ │ │ │ │ +* * * * * + +* — любое значение +*/N — с шагом N (*/30 = каждые 30) +N-M — диапазон (1-5 = пн-пт) +A,B — список (0,6 = вс,сб) +N — точное число (0 = в 0 мин) + +every 30s / 30m / 2h / 1d — человеческий формат +2026-07-01T09:00 — ISO, одноразово (только Eagle/Whale) +``` + +- `scheduleHintOpen` — boolean в `cronModal`, по умолчанию `false` +- При открытии модала сбрасывается в `false` +- ISO-строка скрыта для launchd через `x-if="cronModal.source !== 'launchd'"` + +**API эндпоинты:** +- `GET /` — главная страница, опционально `?tab=crons|pages|files|services` +- `GET /api/crons` — список всех кронов +- `POST /api/crons` — создать новый крон (body: source, name, schedule, prompt, script, deliver, skills, enabled_toolsets, model, provider, workdir). Для source=launchd: только name, schedule, script, workdir используются — генерируется plist и загружается через launchctl +- `PATCH /api/crons/{source}/{job_id}` — редактировать поля +- `POST /api/crons/{source}/{job_id}/toggle` — включить/выключить +- `DELETE /api/crons/{source}/{job_id}` — удалить + +**Формат Hermes cron jobs.json:** +```json +{ + "jobs": [ + { + "id": "531b242c30ad", + "name": "data-pipeline", + "prompt": "[SILENT] bash ...", + "skills": [], + "skill": null, + "model": null, + "provider": null, + "script": null, + "schedule": { "kind": "cron", "expr": "*/30 7-21 * * 1-5", "display": "*/30 7-21 * * 1-5" }, + "schedule_display": "*/30 7-21 * * 1-5", + "enabled": false, + "state": "paused", + "deliver": "local", + "enabled_toolsets": null, + "workdir": null + } + ] +} +``` + +--- + +## Deployment + +```bash +cd ~/Developer/eagle-dash + +# Install deps +uv sync + +# Generate token +python3 -c "import secrets; print('EAGLE_TOKEN='+secrets.token_hex(32))" > .env + +# Setup pf redirect (localhost:80 → :8880) +sudo bash setup-pf-redirect.sh + +# Load LaunchAgent +launchctl load ~/Library/LaunchAgents/com.eagle.dashboard.plist +``` + +--- + +## Troubleshooting + +**Services show `running: null`** — check `supervisor.supervisor_status` field in `/api/services` (not top-level `running`). The supervisor status is in the nested `supervisor` object. + +**PID files stale** — `ls ~/.eagle-dash/pids/` and compare with `ps`. Supervisor adopts automatically on next poll. + +**Ghost launchctl entries** — after removing plists, use `launchctl remove