From 22319f66d38a25add3d6426369c012387ac5ce6e Mon Sep 17 00:00:00 2001 From: MSCodeBase Agent Date: Fri, 13 Nov 2026 00:22:50 +0300 Subject: [PATCH] docs(agents): align install rules and gate count with the code --- AGENTS.md | 39 ++++++++++++++++++++++++--------------- AGENT_DIARY.md | 10 ++++++++++ 2 files changed, 34 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c4fdf598..135f0ffc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,9 +10,12 @@ SQLite FTS5/BM25 + PropertyGraph), отвечает на вопросы о ко проекта и безопасные правки. По умолчанию работает **без эмбеддингов и без LanceDB** (`MSCODEBASE_DENSE_OFF=true`). -**Кто клиент.** Сейчас основной хост — **OpenCode**; расширение Zed остаётся рабочим -вариантом. `install.py` в обоих случаях доставляет код в каталог расширения -(`%LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence`), откуда MCP запускается. +**Кто клиент.** Любой MCP-хост: OpenCode, Zed, Claude Code, Cursor, generic +`mcpServers` (`docs/en/CLIENTS.md`; проверено `scripts/verify_client_snippets.py`). +`install.py` создаёт обычное Python-окружение в `MSCODEBASE_INSTALL_ROOT` (по умолчанию — +исторический `%LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence`; к Zed относится +только имя). Zed — опциональный адаптер (`--no-zed`), конфиг для остальных хостов +печатает `python install.py --print-config --client `. Отсюда правило: после правки кода сервера — `python install.py --sync-only` и **перезапуск хоста** (сессия OpenCode / окно Zed), иначе работает старый процесс. @@ -77,25 +80,30 @@ git commit/push); два подряд отказа MCP на одном инст `read_live_file`/`get_symbol_info`; `git log` вместо `codebase(action="git", …)`; угадывание номеров строк. -### §0.5. Цикл доставки: исходники → расширение → хост +### §0.5. Цикл доставки: исходники → установка → хост -- **Исходники:** этот репозиторий. **Установленное:** каталог расширения - `%LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence` (venv + код + модели). -- OpenCode запускает MCP как `…\extensions\mscodebase-intelligence\venv\Scripts\mscodebase-mcp.exe - -u -m src.main` с `PYTHONPATH` на каталог расширения (`PROJECT_PATH` = рабочая папка). +- **Исходники:** этот репозиторий. **Установленное:** `MSCODEBASE_INSTALL_ROOT` + (по умолчанию `%LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence`): venv + код + + опциональные модели; данные, логи и кэши — в `MSCODEBASE_DATA_DIR` + (`docs/en/DATA_MAP.md`). +- Хост запускает MCP как `/venv/Scripts/mscodebase-mcp.exe -u -m src.main` + с `PYTHONPATH` на каталог установки (`PROJECT_PATH` = рабочая папка). Точную команду и + env для своего хоста печатает `install.py --print-config --client …`. - Порядок после правки кода: ``` 1. правка в src/… (после edit → notify_change) - 2. python install.py --sync-only # код, без pip/llama/GGUF + 2. python install.py --sync-only # код, без pip/llama/моделей 3. перезапустить хост: сессию OpenCode (или окно Zed) 4. проверить: tool_help() / get_health_report() ``` -- `python install.py` (без флагов) — интерактивная полная установка (pip, llama.cpp, - модели). Запускать только по явной задаче. -- Правки, которых нет в расширении, в рантайме не существуют — «работает» проверять - только после sync + restart. +- `python install.py` — полная установка: venv, pip, копия кода; без `--with-models` + модели не качаются (text-first), без `--no-zed` патчится `settings.json` Zed. + Запускать только по явной задаче. +- `install.py --doctor [--json]` — что стоит и сколько весит; `--clean [--dry-run]` + — что будет удалено; удаление — только с `--yes`. Правки, которых нет в каталоге + установки, в рантайме не существуют — «работает» проверять после sync + restart. ### §0.6. Структура корня @@ -317,8 +325,9 @@ impact-guard). (`-m "not benchmark"`), иначе их падения не видны. 5. `ruff check src/ tests/ scripts/` — чисто (или `scripts/ruff_gate.py`). 6. Хуки: `.githooks/pre-commit` активен (`core.hooksPath = .githooks`). Он гоняет - 12 гейтов, включая gate-zero (полный pytest) — для docs-only коммитов gate-zero - пропускается автоматически. + 14 гейтов (последний — gitleaks), включая gate-zero (полный pytest) — для docs-only + коммитов gate-zero пропускается автоматически; `MSCB_PRECOMMIT_FAST=1` пропускает его + явно и оставляет прогон CI (`.githooks/pre-commit:33,153`). 7. CI проверен не «на словах»: `gh run list --branch <ветка>` и `gh run view --log-failed`. Джобы: `test` (ubuntu + windows, Python 3.14), `clean-state`, `manifest-parity`, `docker-build`, `transport-equiv-e2e`. diff --git a/AGENT_DIARY.md b/AGENT_DIARY.md index b02f6746..181c935c 100644 --- a/AGENT_DIARY.md +++ b/AGENT_DIARY.md @@ -1914,3 +1914,13 @@ BREACH: MSC-P-19 | date: 2026-10-03 | rule: §12 | guard_at_time: no | detected_ **3. Код установщика в диффах есть.** `gh pr diff 120 | grep auto_yes` → удалённая строка `range(0 if auto_yes …)`, добавленная `range(1 if auto_yes …)` и тест `test_auto_yes_runs_each_step_once`. `gh pr diff 121 | grep "def _"` → `models_enabled`, `_doctor_report`, `_doctor_cli`, `_clean_targets`, `_clean_cli` (имена не `cmd_*`; поиск по `cmd_clean|cmd_doctor` пуст по этой причине). **4. Гипотеза «clean-state до фикса валидировал пустую установку» — опровергнута.** `scripts/verify_clean_state.sh` вообще не вызывает `install.py`: он сам создаёт venv и делает `pip install -e .`; `grep "install.py --yes"` по `.github/` и `scripts/` пуст. Значит баг `--yes` с v3.0 не влиял ни на один прогон CI — ровно поэтому его никто и не поймал; поймал только ручной прогон по README. **Урок:** «CI зелёный» и «инструкция работает» — разные утверждения. Пока установщик не запускали как пользователь (по README, в пустом каталоге), его неинтерактивная ветка была мёртвой, а все гейты оставались зелёными. + +## [2026-11-13] main собран из всех семи PR: сверка, новая планка и 5 предсуществующих красных +**Мержи:** #115/#116 → #117 → #118 (Цель 1) → #120 → #121 → #122 (Цель 2, порядок стека соблюдён) → #123 (G4). `origin/main` = `a25627a`. +**Сверка «ничего не потерялось»** на чистом worktree от `origin/main`: `docs/{en,ru,zh}/DATA_MAP.md` есть; `scripts/check_docs_vs_installer.py`, `scripts/check_docs_vs_config.py`, `.github/pull_request_template.md` есть; `install.py` содержит `models_enabled`, `_doctor_cli`, `_clean_cli` и фикс `range(1 if auto_yes else ...)`. +**Планка (замер 2026-11-13, чистое дерево, `-n auto`):** +- гейт по конфигу (`pytest tests/ -q`, pyproject вычитает `slow` и `benchmark`): **2507 passed, 11 skipped, 0 failed**, 159.66 s; +- с включёнными slow (`-m "not integration and not benchmark"`): **2593 passed, 5 failed, 14 skipped**, 167.29 s. +**Находка (вне задачи, не чинил):** эти 5 красных — `tests/test_freshness_checker.py` (verify/hot-reload видят пустой DataFrame). Проверено на до-мержевом `main` `a6524d6` в отдельном worktree: те же 5 тестов красные, значит это не регресс Цели 1/2, а предсуществующее состояние, скрытое тем, что тесты помечены `slow` и в дефолтный гейт не входят. В `KNOWN_ISSUES.md` не записал: файл на 295 строках при лимите 300, нужна ротация — отдельная задача. +**AGENTS.md приведён к коду (долг G7):** §0 «Кто клиент» и §0.5 описывали установку как «всегда в каталог расширения Zed» без `--print-config/--doctor/--clean/--with-models`; §7.6 говорил «12 гейтов» при 14 в `.githooks/pre-commit`. Все упомянутые флаги сверены с `install.py --help` (9 ссылок). +**Урок:** «полный прогон» — это два разных числа (с `slow` и без). Планку фиксировать вместе с командой, иначе следующий агент сравнит несравнимое; пять красных жили в slow-зоне и не были видны ни одному гейту.