zames_pro 2.65.1 → 2.66.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.66.0] - 2026-10-07
+
+### Added
+
+- **release:** add scripts/release.mts for one-command release prep (G4)
+
+### Fixed
+
+- **reload:** include commands, run-task and attach-refs in hot-reload (G2)
+
+### Changed
+
+- apply prettier to files touched by G2/F1
+
 ## [2.65.1] - 2026-10-07
 
 ### Fixed

package/README.md

@@ -14,6 +14,12 @@
   <a href="https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml"><img src="https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml/badge.svg" alt="tests"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
   <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178c6.svg" alt="TypeScript"></a>
+  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome"></a>
+</p>
+
+<p align="center">
+  <strong>English</strong> | <a href="https://github.com/Viqto0r/zames_pro/blob/master/README.ru.md">Русский</a>
 </p>
 
 A terminal coding agent that works on top of [chat.deepseek.com](https://chat.deepseek.com/) through Playwright.
@@ -27,6 +33,28 @@ directory, reads and edits files, runs commands, and commits to git.
   <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/demo.png" alt="zames session in the terminal" width="860">
 </p>
 
+## Quick start
+
+```bash
+npm install -g zames_pro   # Chromium for Playwright is downloaded automatically
+cd your-project            # any folder the agent should work in
+zames                      # sign in once, then describe your task
+```
+
+There is **no API key and no per-token bill**: zames signs in to **your own
+[chat.deepseek.com](https://chat.deepseek.com/) account** in a real (headless)
+Chromium and drives the web chat like a regular user. The first launch asks for
+your DeepSeek login once (the session is stored in `~/.zames/profile`); after
+that just run `zames` and type a task in plain language:
+
+```text
+❯ refactor the config loader and add a test for the new default
+```
+
+While the agent works you can keep typing — a message sent mid-task is queued
+and runs right after it, in the same chat. `Esc` aborts the current generation,
+`/help` lists commands, `/exit` quits.
+
 ## How it works
 
 zames does not call the model API. It launches a headless Chromium with a
@@ -54,7 +82,7 @@ Key pieces:
 
 ## Table of contents
 
-- [Features](#features) · [Why zames?](#why-zames) · [Requirements](#requirements)
+- [Quick start](#quick-start) · [Features](#features) · [Why zames?](#why-zames) · [Requirements](#requirements)
 - [How it works](#how-it-works) · [Installation](#installation) · [Signing in](#signing-in) · [Usage](#usage)
 - [Tools](#tools) · [Slash commands](#slash-commands)
 - [Project context, skills and memory](#project-context-skills-and-memory) · [MCP (external tools)](#mcp-external-tools) · [Configuration](#configuration)

package/README.ru.md

@@ -0,0 +1,502 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/logo-small.jpg" alt="zames logo" width="430">
+</p>
+
+<h1 align="center">zames_pro</h1>
+
+<p align="center">
+  <strong>Терминальный coding-агент, который управляет chat.deepseek.com через Playwright — API-ключ не нужен.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/zames_pro"><img src="https://img.shields.io/npm/v/zames_pro.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/zames_pro"><img src="https://img.shields.io/npm/dm/zames_pro.svg" alt="npm downloads"></a>
+  <a href="https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml"><img src="https://github.com/Viqto0r/zames_pro/actions/workflows/test.yml/badge.svg" alt="tests"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178c6.svg" alt="TypeScript"></a>
+  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Viqto0r/zames_pro/blob/master/README.md">English</a> | <strong>Русский</strong>
+</p>
+
+Терминальный coding-агент, работающий поверх [chat.deepseek.com](https://chat.deepseek.com/) через Playwright.
+По духу он похож на Claude Code / Codex CLI: запускается в текущей
+директории, читает и правит файлы, выполняет команды и коммитит в git.
+
+> API-ключ не нужен — агент управляет веб-чатом DeepSeek как обычный
+> пользователь через настоящий (headless) браузер.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/demo.png" alt="сессия zames в терминале" width="860">
+</p>
+
+## Быстрый старт
+
+```bash
+npm install -g zames_pro   # Chromium для Playwright скачается автоматически
+cd your-project            # любая папка, в которой должен работать агент
+zames                      # один раз войти, дальше просто описывайте задачу
+```
+
+Здесь **нет API-ключа и нет оплаты за токены**: zames входит в **ваш
+собственный аккаунт [chat.deepseek.com](https://chat.deepseek.com/)** в
+настоящем (headless) Chromium и управляет веб-чатом как обычный пользователь.
+При первом запуске он один раз спросит логин DeepSeek (сессия сохраняется в
+`~/.zames/profile`); после этого достаточно запустить `zames` и написать
+задачу обычным языком:
+
+```text
+❯ отрефактори загрузчик конфига и добавь тест на новый дефолт
+```
+
+Пока агент работает, можно продолжать печатать — сообщение, отправленное
+посреди задачи, встанет в очередь и уйдёт сразу после неё, в тот же чат.
+`Esc` прерывает текущую генерацию, `/help` показывает команды, `/exit` — выход.
+
+## Как это работает
+
+zames не вызывает API модели. Он запускает headless Chromium с постоянным
+профилем, входит в `chat.deepseek.com` как человек, печатает задачу в поле
+чата и читает ответ обратно.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Viqto0r/zames_pro/master/docs/how-it-works.png" alt="как работает zames" width="860">
+</p>
+
+Словами: вы вводите задачу → zames отправляет системный промпт и задачу в
+веб-чат DeepSeek → модель отвечает → zames разбирает вызов инструмента,
+выполняет его локально, возвращает результат обратно и печатает финальный
+ответ.
+
+Ключевые детали:
+
+- **Ответ читается из сырого сетевого потока** (SSE), а не из отрендеренного
+  DOM, поэтому JSON вызова инструмента с шаблонными строками и экранированием
+  остаётся целым.
+- **Постоянный профиль** (`~/.zames/profile`) держит вас залогиненным;
+  User-Agent headless-браузера подменяется, чтобы CDN DeepSeek не отдавал 403
+  на вход.
+- **Троттлинг отправки** (15 с по умолчанию) щадит рейт-лимит веб-чата во
+  время долгих прогонов с инструментами.
+- **Агент запесочен** в директорию запуска — ни один инструмент не может
+  читать или писать выше неё.
+
+## Содержание
+
+- [Быстрый старт](#быстрый-старт) · [Возможности](#возможности) · [Почему zames?](#почему-zames) · [Требования](#требования)
+- [Как это работает](#как-это-работает) · [Установка](#установка) · [Вход в аккаунт](#вход-в-аккаунт) · [Использование](#использование)
+- [Инструменты](#инструменты) · [Слэш-команды](#слэш-команды)
+- [Контекст проекта, навыки и память](#контекст-проекта-навыки-и-память) · [MCP (внешние инструменты)](#mcp-внешние-инструменты) · [Конфигурация](#конфигурация)
+- [FAQ](#faq) · [Ссылки](#ссылки) · [Лицензия](#лицензия)
+
+## Возможности
+
+- **Инструменты как в Claude Code / Codex** — `Read`, `Write`, `Edit`, `Bash`,
+  `Glob`, `Grep`, плюс `MultiEdit`, `ApplyPatch`, `LS`, `TodoWrite`, git- и
+  веб-инструменты. Каждая правка подкреплена `/undo`.
+- **Работает, пока вы печатаете** — сообщения, набранные во время задачи,
+  встают в очередь и уходят сразу после неё, в тот же чат (как набор текста
+  во время генерации на сайте).
+- **Режим плана** — `/plan` (или `--plan`) убирает все мутирующие инструменты,
+  чтобы агент изучал код, не трогая дерево.
+- **Контекст проекта** — читает `AGENTS.md`, `MEMORY.md`, навыки (`SKILL.md`) и
+  пользовательские команды из репозитория и `~/.zames`, как в Codex / Claude
+  Code.
+- **Поддержка MCP** — подключение внешних серверов инструментов (например,
+  `@playwright/mcp`).
+- **Планировщик** — `/loop`, `/cron` и `/jobs` повторяют задачи по таймеру.
+- **Двуязычный интерфейс** — русский / английский (`/config lang`).
+
+## Почему zames?
+
+- **Нет API-ключа и счёта за токены** — используется ваш собственный аккаунт
+  чата DeepSeek, а не платный API. Удобно для долгих задач с инструментами.
+- **Тот же рабочий процесс, что в Claude Code / Codex** — инструменты,
+  `AGENTS.md`, навыки, MCP и слэш-команды, так что всё знакомо с первого дня.
+- **Работает без присмотра** — headless по умолчанию, возобновляемые сессии,
+  `/loop` и `/cron` для задач по расписанию.
+- **Local-first** — профиль браузера, учётные данные и логи не покидают вашу
+  машину, а агент запесочен в директорию проекта.
+
+## Требования
+
+- Node.js >= 20
+- Аккаунт DeepSeek. При первом запуске zames спросит логин/пароль DeepSeek в
+  терминале (и сохранит их в `~/.zames/config.json` после успешного входа,
+  поэтому более поздний разлогин обрабатывается автоматически, без повторных
+  вопросов). Можно также войти вручную в окне браузера, когда он headed.
+
+## Вход в аккаунт
+
+Браузер по умолчанию работает **headless**. Когда DeepSeek требует входа,
+zames:
+
+1. переиспользует сессию из постоянного профиля (`~/.zames/profile`), если она
+   ещё валидна;
+2. иначе входит автоматически по сохранённым учётным данным
+   (`browser.auth.username` / `browser.auth.password`);
+3. иначе спрашивает логин/пароль в терминале (в TTY) и после успешного входа
+   запоминает их для следующего раза;
+4. иначе показывает подсказку про ручной вход.
+
+Чтобы войти руками (например, если DeepSeek показывает капчу), запустите с
+видимым окном:
+
+```bash
+zames --headed
+```
+
+Флаг `--headless` (значение по умолчанию) и `headless: true` в конфиге держат
+браузер без окна; `--headed` / `headless: false` показывают его.
+
+Headless работает из коробки: headless Chrome обычно представляется как
+`HeadlessChrome/...`, и CDN DeepSeek блокирует такой User-Agent ответом 403,
+поэтому zames срезает этот маркер перед загрузкой страницы (сохраняя реальную
+версию движка). `--headed` нужен не только ради входа.
+
+Учётные данные и переключатели можно также править из `/config`
+(`browser.auth.username`, `browser.auth.password`, `browser.auth.saveSession`).
+
+## Установка
+
+```bash
+npm install -g zames_pro
+```
+
+Chromium для Playwright скачивается автоматически при установке. На Linux/WSL
+необходимые системные библиотеки тоже ставятся, если доступен `sudo` без
+пароля; иначе выполните один раз вручную:
+
+```bash
+npx playwright install chromium
+sudo npx playwright install-deps chromium
+```
+
+## Использование
+
+Перейдите в папку проекта и запустите:
+
+```bash
+zames
+```
+
+Агент работает внутри директории, из которой он запущен, и не может её покинуть (песочница).
+
+Пока агент работает, можно продолжать печатать: Enter ставит сообщение в
+очередь (оно уйдёт сразу после текущей задачи, в тот же чат), а Esc / Ctrl+C
+прерывают текущую генерацию. Это повторяет набор текста во время генерации на
+сайте DeepSeek.
+
+### Строка ввода
+
+Промпт — это небольшой редактор строки с постоянной историей:
+
+- `↑` / `↓` — переход по истории сообщений (сохраняется в
+  `~/.zames/history.json`, поэтому переживает перезапуск); внутри
+  многострочного сообщения стрелки двигают по строкам.
+- `Ctrl+R` — инкрементальный поиск по истории в обратном порядке (как в bash):
+  печатайте для фильтра, `Ctrl+R` — за более старыми совпадениями, `Enter` —
+  принять, `Esc` — отменить.
+- `Ctrl+_` — отменить последнюю правку строки ввода (случайно нажатые
+  `Ctrl+U` / `Ctrl+K` можно вернуть).
+- `Ctrl+U` — очистить строку, `Ctrl+K` — удалить до конца строки, `Ctrl+W` —
+  удалить слово перед курсором, `Ctrl+←`/`Ctrl+→` — переход по словам.
+- `\` + `Enter`, `Ctrl+J`, `Ctrl+Enter` или `Shift+Enter` — вставить новую
+  строку.
+- `/` + `Tab` — подсказки и автодополнение слэш-команд.
+- `!команда` — выполнить shell-команду напрямую, минуя модель (как bash-режим
+  Claude Code). Действует та же песочница, что и для инструмента `Bash`, так
+  что прямая команда тоже не может выйти за пределы проекта.
+
+Установите `NO_COLOR=1`, чтобы отключить цвета (иначе используется спокойная
+палитра по умолчанию).
+
+### Картинки и файлы
+
+В строку ввода можно вставить картинку или файл (Ctrl+Shift+V / Shift+Insert
+или собственной вставкой терминала). zames сохраняет его в `<project>/tmp` и
+показывает маркер в строке — `[image#1]` для картинок, `[file#1]` для прочих
+файлов — затем загружает реальный файл в чат вместе с вашим сообщением. Это те
+же форматы, что принимает веб-чат DeepSeek (PNG, JPEG, GIF, WEBP, BMP, SVG и
+обычные типы документов).
+
+Вставка картинки работает, когда терминал передаёт её как `data:` URL или как
+base64-блок с узнаваемой сигнатурой изображения. Можно также вставить путь к
+локальному файлу (перетащите файл в терминал или скопируйте его путь); если
+файл существует — он прикрепляется, иначе текст вставляется как обычно.
+
+Нажмите Ctrl+V (или сделайте пустую вставку), и zames прочитает картинку прямо
+из буфера обмена: Linux через wl-paste (Wayland) или xclip/xsel (X11), macOS
+через pngpaste, Windows через PowerShell. Нужные Linux-утилиты ставятся
+автоматически при `npm install` (best-effort, через определённый пакетный
+менеджер). Если картинка не найдена, zames сообщит об этом и напишет, какой
+инструмент пробовал, вместо молчания.
+
+### Опции
+
+```
+zames --task <текст задачи>
+zames --chat <id>
+zames --new-chat
+zames --resend-prompt
+zames --dir <path>
+zames --headless
+zames --headed
+zames --plan
+zames --output-format jsonl
+zames --debug
+zames --version
+zames --help
+```
+
+### Машиночитаемый вывод (скрипты / CI)
+
+Для одноразовых запусков (`--task`) агент может выдавать поток событий как JSON
+lines в stdout, оставляя весь человеческий текст в stderr:
+
+```bash
+zames --task "summarize the diff" --output-format jsonl
+```
+
+Каждая строка — одно событие (`tool_call`, `tool_result`, `assistant_final`, …),
+так что это сразу пайпится в `jq`:
+
+```bash
+zames --task "..." --output-format jsonl \
+  | jq -r 'select(.type=="assistant_final") | .message'
+```
+
+## Инструменты
+
+У агента тот же стиль инструментов, что в Claude Code / Codex CLI:
+
+- **Файловые** — `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`. `Read` по
+  умолчанию отдаёт сырое содержимое; передайте `numbered=true`, чтобы получить
+  нумерацию строк в стиле `cat -n` (только для справки — не вставляйте её в
+  `Edit`).
+- **Дополнительные** — `LS` (список директории), `MultiEdit` (несколько правок
+  одного файла атомарно), `TodoWrite` (чек-лист задач сессии), `ApplyPatch`
+  (мультифайловый патч в формате V4A от Codex: `*** Begin Patch` … `*** End Patch`).
+- **Git** — `GitStatus`, `GitDiff`, `GitLog`, `GitShow`, `GitBranchList`,
+  `GitAdd`, `GitCommit`, `GitPush`.
+- **Web** — `WebFetch`, `WebSearch`.
+- **Служебный** — `respond` (финальный ответ оператору, завершает задачу).
+
+Все файловые инструменты остаются внутри рабочей директории (песочница).
+`Write`/`Edit` и `MultiEdit`/`ApplyPatch` делают резервную копию (undo) перед
+изменением файла.
+
+## Слэш-команды
+
+Введите / в промпте для подсказок (Tab дополняет). Кроме команд сессии и
+конфига (/new, /chats, /resume, /cd, /status, /config, /undo, /transcript,
+/mcp, /skills, /memory, /init, /reload, /debug-dom, /help, /exit) есть
+несколько в духе Claude Code / Codex CLI:
+
+- /diff [--staged] — показать git-диф рабочего дерева (--staged для индекса).
+- /diffstat — сводка изменений одной строкой (`git diff --stat`).
+- /context — показать, что загружено в промпт (AGENTS.md, MEMORY.md, навыки,
+  пользовательские команды) и размер системного промпта.
+- /retry — отправить последнюю задачу в тот же чат заново (удобно после
+  обрезанного или пустого ответа).
+- /rename <title> — задать заголовок текущей сессии (виден в /sessions).
+- /copy — скопировать последний ответ ассистента в буфер обмена ОС.
+- /cost (алиас /usage) — статистика сессии: задачи, вызовы инструментов,
+  длительность и размер контекста в токенах (DeepSeek
+  `accumulated_token_usage`).
+- /export [file] — записать транскрипт сессии в Markdown-файл
+  (по умолчанию zames-export-<stamp>.md).
+- /doctor — диагностика node, git, конфига, браузера, буфера обмена и MCP.
+- /add-dir <path> — проверить дополнительную директорию (песочница
+  фиксируется при старте; для записи туда перезапустите с --dir).
+- /resume <n> (после /chats) и /resume-id <id> — открыть чат и НАПЕЧАТАТЬ его
+  диалог в терминал, чтобы восстановленный контекст был виден. Показываются
+  только последние 20 сообщений (`RESTORED_HISTORY_LIMIT`). /last открывает
+  последний чат текущей директории без поиска; /sessions показывает сохранённые
+  сессии с их относительным возрастом.
+- /help <command> — полное описание одной команды (например, `/help diff`)
+  вместо всего списка.
+- /review [focus] [--staged] — попросить агента проверить незакоммиченные
+  изменения и сообщить находки (без правок кода).
+- /plan [on|off] — режим плана (только чтение). Пока он включён, мутирующие
+  инструменты (Write/Edit/MultiEdit/ApplyPatch/Bash, GitAdd/GitCommit/GitPush)
+  убраны из набора, чтобы агент изучал код, не трогая дерево. Стартовать в нём
+  можно с `--plan`.
+- /compact — попросить DeepSeek сжать текущий чат в передаточное резюме, затем
+  открыть НОВЫЙ чат, заново отправить системный промпт и положить резюме как
+  перенесённый контекст. Используйте, когда контекст разрастается.
+- /goal [text|clear] — задать долгоживущую цель сессии. Она добавляется в
+  начало каждого сообщения задачи, поэтому модель держит общую картину через
+  много ходов. Хранится в `<project>/.zames-goal` (git-ignored) и
+  восстанавливается при следующем запуске.
+- /loop <interval> <task> — повторять задачу периодически (например,
+  `/loop 10m run the tests`). /cron "<min> <hour> <dom> <month> <dow>" <task> —
+  запуск по расписанию. /jobs [rm <id>|clear] перечисляет и останавливает их.
+  Сработавшая задача попадает в ту же очередь сообщений, что и ваш ввод, так
+  что выполняется, когда агент свободен (никогда посреди генерации), и всё
+  равно соблюдает троттлинг отправки.
+- /thinking [on|off] и /web [on|off] — переключить Deep thinking / Smart search.
+  Их (а также /queue, /jobs, /goal, `/config <sub>`) можно использовать, ПОКА
+  агент работает — они не трогают текущую генерацию.
+- /queue [clear] — показать или очистить сообщения, ждущие отправки после
+  текущей задачи.
+
+Контекст в токенах показывается и вживую: в строке статуса над вводом слева
+спиннер/текст, справа — контекст (например, `125k · 13%`, процент от 1M
+контекста). Он ОКРАШЕН по уровню заполнения: зелёный ниже 50%, жёлтый 50-80%,
+красный выше 80%. Значение приходит из DeepSeek `accumulated_token_usage` и
+скрыто до первого ответа.
+
+## Контекст проекта, навыки и память
+
+Как в Codex / Claude Code, zames читает инструкции проекта и переиспользуемые
+процессы из вашего репозитория и из `~/.zames`.
+
+- **AGENTS.md** — инструкции проекта. Положите его в корень репозитория (или в
+  любую родительскую папку рабочей директории). Глобальные инструкции живут в
+  `~/.zames/AGENTS.md` (и `~/.claude/CLAUDE.md`). Запустите `/init`, и агент
+  изучит проект и напишет AGENTS.md на основе реальных команд сборки/тестов и
+  соглашений (`/init --force` перезапишет существующий файл).
+- **MEMORY.md** — долговечные заметки, переживающие сессии. Агент дописывает
+  сюда полезные факты; можно править вручную или добавить из промпта через
+  `/remember <text>`.
+- **Навыки** — папка с файлом `SKILL.md` (YAML-фронтматтер: `name`,
+  `description`, опционально `allowed-tools`, `user-invokable`) плюс любые
+  вспомогательные файлы. Ищутся в `.zames/skills/`, `.claude/skills/`,
+  `.agents/skills/`, `skills/` и `~/.zames/skills/`. Агент читает тело только
+  когда задача совпадает с описанием. Список — `/skills`; вызов —
+  `/<skill-name>`.
+- **Пользовательские команды** — `.md`-файлы в `.zames/commands/` (или
+  `.claude/commands/`). Поддерживают подстановки `$ARGUMENTS` / `{{args}}` и
+  вызываются как `/<command-name>`.
+
+Навыки и пользовательские команды видны в списке автодополнения «/» и в
+`/help`.
+
+```
+/skills                       список найденных навыков
+/memory                       показать действующие AGENTS.md / MEMORY.md
+/remember <text>              дописать долговечную заметку в MEMORY.md
+/init [--force]               проанализировать проект и создать AGENTS.md
+```
+
+## MCP (внешние инструменты)
+
+zames может использовать инструменты с серверов [MCP](https://modelcontextprotocol.io).
+Главный пример — @playwright/mcp: он даёт агенту настоящий браузер
+(navigate, click, snapshot, type, ...) поверх того, который zames уже
+использует для чата DeepSeek.
+
+Положите файл конфига (той же формы, что в Claude Code / Cursor):
+
+- `~/.zames/mcp.json` — глобальный
+- `<project>/.zames/mcp.json` — на уровне проекта (поздние файлы побеждают)
+- `<project>/.mcp.json` — привычное имя MCP
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--headless", "--isolated"]
+    }
+  }
+}
+```
+
+ВАЖНО: держите MCP-браузер изолированным. @playwright/mcp по умолчанию
+использует ТУ ЖЕ директорию профиля, что и zames (~/.zames/profile). Если
+запустить его без --isolated (или без собственного --user-data-dir),
+MCP-браузер и браузер агента подерутся за один профиль, и чат DeepSeek
+покажет «Something went wrong when opening your profile». Всегда передавайте
+--isolated, как в примере выше.
+Серверы бывают и удалёнными ("url": "https://...", "transport": "sse").
+Их инструменты видны агенту как `server__tool` (например,
+`playwright__browser_navigate`) и перечисляются в `/mcp` и `/status`.
+Сервер, который не смог подключиться, пропускается с предупреждением и
+никогда не роняет агента.
+
+## Конфигурация
+
+Глобальный конфиг: `~/.zames/config.json`
+Локальный (на проект): `.zamesrc.json`
+
+Просматривать и менять настройки можно не выходя из агента — командой
+`/config`. Запустите её без аргументов, чтобы открыть интерактивное меню
+(↑/↓ — навигация, Enter — изменение, `d` — сброс, `q` — выход). Булевы и
+enum переключаются на месте; числа и строки открывают ввод.
+
+```
+/config                       интерактивное меню настроек
+/config list                  показать все изменяемые настройки
+/config get <path>            показать настройку
+/config set <path> <value>    изменить настройку
+/config reset <path>          сбросить настройку к дефолту
+/config path                  показать пути файлов конфига
+/config lang <ru|en>          переключить язык интерфейса и агента
+```
+
+Примеры:
+
+```
+/config set maxIterations 20
+/config set browser.deepThinking true   # DeepSeek Deep thinking (медленно; рассуждения скрыты)
+/config set browser.webSearch false     # DeepSeek Smart web search
+/config lang en
+```
+
+Изменения пишутся в проектный `.zamesrc.json` и применяются сразу (где это
+возможно без перезапуска).
+
+### Язык
+
+`/config lang ru` или `/config lang en` переключает и язык интерфейса
+(справка, сообщения, спиннер), и язык, на котором агент вам отвечает. Локаль
+хранится в `ui.locale` в файле конфига.
+
+Данные агента хранятся в `~/.zames`: профиль браузера, логи, история undo,
+сессии.
+
+## FAQ
+
+**Это официальный продукт DeepSeek?**
+Нет. zames управляет публичным веб-интерфейсом chat.deepseek.com через
+настоящий браузер, как обычный пользователь. Он не связан с DeepSeek.
+
+**Нужен ли API-ключ?**
+Нет. Вы один раз входите в свой аккаунт DeepSeek; сессия хранится в
+`~/.zames/profile` и переиспользуется.
+
+**Какую модель он использует?**
+Ту, которую использует веб-чат DeepSeek (DeepSeek-V3 или reasoning-модель при
+включённом «Deep thinking»). zames никогда не вызывает API напрямую.
+
+**Работает ли headless / на сервере?**
+Да — headless по умолчанию, а `--output-format jsonl` делает его скриптуемым.
+`--headed` нужен только для ручного входа или отладки селекторов.
+
+**Разрешена ли автоматизация веб-интерфейса?**
+Это зависит от условий DeepSeek; автоматизация сайта может их нарушать.
+Используйте на свой риск и держите троттлинг отправки (15 с по умолчанию),
+чтобы не бить по рейт-лимиту.
+
+**Чем отличается от Claude Code / Codex?**
+Та же форма (инструменты, `AGENTS.md`, навыки, MCP, слэш-команды), но работает
+на вашем аккаунте DeepSeek вместо API, как автоматизация браузера, а не
+first-party API-клиент.
+
+## Ссылки
+
+- **npm:** <https://www.npmjs.com/package/zames_pro>
+- **GitHub:** <https://github.com/Viqto0r/zames_pro>
+- **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
+- **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- **Security policy:** [`SECURITY.md`](SECURITY.md)
+- **Code of conduct:** [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
+
+## Лицензия
+
+MIT

package/dist/index.js

@@ -19,13 +19,10 @@ import { Transcript } from './transcript.js';
 import { UndoStore } from './undo.js';
 import { CheckpointStore, pickRecord as pickCheckpoint } from './checkpoint.js';
 import { selfReview, selfDiff, selfApply, selfList } from './self-review.js';
-import { formatDiff, formatDiffStat, formatContextSources, diffGitArgs, parseTranscript, summarizeTranscript, renderCost, formatExport, defaultExportPath, renderDoctor, resolveExtraDir, buildReviewPrompt, isDevOnlyCommand, parseBacklogItems, nextBacklogItem, buildImprovePrompt, formatRelativeTime, trimRestoredMessages, RESTORED_HISTORY_LIMIT, hasQueuedJob, buildSlashCommandHints, parseQueueCommand, parseLiveToggle, parseGoalCommand, isLiveConfigCommand, formatQueueList, ctrlCEscalation, expandCommandArgs, missingCommandArgs, } from './commands.js';
 import { performCompact } from './compact.js';
 import { Scheduler, parseInterval, formatInterval, formatJobLine, parseCron, } from './scheduler.js';
 import { renderMarkdown, setAnswerWidth } from './markdown.js';
-import { resolveAttachPath, inlineAtRefs } from './attach-refs.js';
 import { parseBacklogNote } from './backlog.js';
-import { runTask } from './run-task.js';
 import { closeWeb } from './web.js';
 import { assertCommandInsideRoot, runShell } from './shell.js';
 import { saveSession, loadLastSession, readSession, listSessions, sessionsDir, loadHistory, saveHistory, } from './sessions.js';
@@ -198,8 +195,19 @@ const RELOADABLE = [
     'config',
     'fsutil',
     'backlog',
+    // C3 modules index.ts now calls through the mod bag (G2): without this a
+    // /reload silently kept the OLD commands/run-task/attach-refs until a restart.
+    // 'input/layout' is NOT listed: its only live consumers are input.ts (the
+    // long-lived LineEditor, itself not reloadable) and spinner.ts, which already
+    // picks up a fresh copy transitively.
+    'commands',
+    'run-task',
+    'attach-refs',
 ];
 const mod = {
+    commands: null,
+    attach: null,
+    runTask: null,
     createTools,
     runAgentLoop,
     buildSystemPrompt: null,
@@ -260,6 +268,12 @@ async function reloadModules() {
         mod.backlogStats = pick('backlog', 'backlogStats');
     if (pick('backlog', 'backlogNeedsPruning'))
         mod.backlogNeedsPruning = pick('backlog', 'backlogNeedsPruning');
+    if (pick('commands', 'missingCommandArgs'))
+        mod.commands = loaded.get('commands');
+    if (pick('attach-refs', 'resolveAttachPath'))
+        mod.attach = loaded.get('attach-refs');
+    if (pick('run-task', 'runTask'))
+        mod.runTask = pick('run-task', 'runTask');
     return { count: loaded.size, errors };
 }
 // Initial load so that mod.buildSystemPrompt and the rest are populated.
@@ -508,10 +522,10 @@ async function expandSlashTarget(workdir, name, rest) {
         const cmd = commands.find((c) => c.name.toLowerCase() === name.toLowerCase());
         if (cmd) {
             // B7: refuse to run when declared positional arguments are missing.
-            const missing = missingCommandArgs(cmd.arguments, rest);
+            const missing = mod.commands.missingCommandArgs(cmd.arguments, rest);
             if (missing.length)
                 return { missing };
-            const body = expandCommandArgs(cmd.body, rest, cmd.arguments);
+            const body = mod.commands.expandCommandArgs(cmd.body, rest, cmd.arguments);
             return { text: body || rest };
         }
         const skills = await loadSkills(workdir);
@@ -549,7 +563,11 @@ async function expandSlashTarget(workdir, name, rest) {
 // in commands.ts (buildSlashCommandHints); here we only supply the runtime
 // data (dev flag, translator, dynamic skills/commands).
 function buildSlashCommands() {
-    return buildSlashCommandHints({ devMode, t, dynamic: dynamicCommands });
+    return mod.commands.buildSlashCommandHints({
+        devMode,
+        t,
+        dynamic: dynamicCommands,
+    });
 }
 // We put the agent's temporary files (one-off scripts, etc.) in
 // <project>/tmp — this folder is in .gitignore and is cleaned on every launch.
@@ -805,8 +823,8 @@ async function printRestoredHistory(browser, ui, chatId = null) {
     // those. The "truncated" note must compare the DISPLAYABLE count with the
     // limit (comparing `all.length` always fired, because tool-calls are
     // dropped and the raw history is always longer).
-    const displayable = trimRestoredMessages(all, 0);
-    const messages = trimRestoredMessages(all);
+    const displayable = mod.commands.trimRestoredMessages(all, 0);
+    const messages = mod.commands.trimRestoredMessages(all);
     // Always surface the diagnostic line when the history could not be turned
     // into anything printable — otherwise "the dialogue is empty" is a dead end
     // (was the fetch blocked? did the chat really have no user turns?).
@@ -857,7 +875,9 @@ async function printRestoredHistory(browser, ui, chatId = null) {
         }
     }
     if (displayable.length > messages.length) {
-        out(theme.dim(t('chats.history_truncated', { n: String(RESTORED_HISTORY_LIMIT) })));
+        out(theme.dim(t('chats.history_truncated', {
+            n: String(mod.commands.RESTORED_HISTORY_LIMIT),
+        })));
     }
 }
 // Build the explicit dependency bag for runTask() (src/run-task.ts). The
@@ -1011,7 +1031,7 @@ async function main() {
             }
         }
         await autoReload();
-        await runTask(runTaskDeps(), browser, tools, task, currentWorkdir, {
+        await mod.runTask(runTaskDeps(), browser, tools, task, currentWorkdir, {
             transcript,
             freshChat,
             sendSystemPrompt,
@@ -1132,7 +1152,7 @@ async function main() {
                 // this job already has a pending message in the queue, skip this fire.
                 // Otherwise a 1-minute loop would add a new task every minute while a
                 // long task is in flight, and they would all run back-to-back.
-                if (hasQueuedJob(pendingQueue, job.id)) {
+                if (mod.commands.hasQueuedJob(pendingQueue, job.id)) {
                     transcript.log('scheduled_skip_queued', {
                         id: job.id,
                         task: job.task,
@@ -1300,7 +1320,7 @@ async function main() {
                 return att;
             }
             // Case 2: the paste is a path to a local file (drag&drop or copy path).
-            const filePath = await resolveAttachPath(currentWorkdir, raw);
+            const filePath = await mod.attach.resolveAttachPath(currentWorkdir, raw);
             if (!filePath)
                 return null;
             const data = await fs.readFile(filePath).catch(() => null);
@@ -1378,7 +1398,7 @@ async function main() {
             // `await runTask()`, so ONLY commands that make sense without the main
             // loop are handled here (a queued slash-command would run too late).
             if (ed.busy) {
-                const q = parseQueueCommand(text);
+                const q = mod.commands.parseQueueCommand(text);
                 if (q) {
                     if (q.sub === 'clear') {
                         const n = pendingQueue.length;
@@ -1390,7 +1410,7 @@ async function main() {
                     }
                     else {
                         ed.printAbove(theme.system(t('msg.queue_title')));
-                        for (const line of formatQueueList(pendingQueue)) {
+                        for (const line of mod.commands.formatQueueList(pendingQueue)) {
                             ed.printAbove(theme.assistant(line));
                         }
                         ed.printAbove(theme.dim(t('msg.queue_cleared_hint')));
@@ -1401,7 +1421,7 @@ async function main() {
                 // browser's DESIRED state and the status icons; it does not touch the
                 // in-flight generation, so it is safe mid-run. The actual DeepSeek
                 // toggles are applied on the next send by _applyToggles().
-                const tg = parseLiveToggle(text);
+                const tg = mod.commands.parseLiveToggle(text);
                 if (tg) {
                     applyLiveToggle(tg);
                     return;
@@ -1412,7 +1432,7 @@ async function main() {
                 // it pauses the editor and would fight the running task, so it stays
                 // queued. `setConfigRuntime` already applies hot values (locale,
                 // toggles, context limit) to the live objects immediately.
-                if (isLiveConfigCommand(text)) {
+                if (mod.commands.isLiveConfigCommand(text)) {
                     void handleConfigCommand(text);
                     return;
                 }
@@ -1458,7 +1478,7 @@ async function main() {
                 // (sets _stopped, which also halts the queue). This makes the two
                 // intents distinguishable instead of one press doing everything.
                 const now = Date.now();
-                if (ctrlCEscalation(now - lastCtrlCAt) === 'run') {
+                if (mod.commands.ctrlCEscalation(now - lastCtrlCAt) === 'run') {
                     ed.printAbove(theme.warn(t('msg.abort_ctrlc_short')));
                     browser.stopGeneration().catch(() => { });
                 }
@@ -1605,7 +1625,7 @@ async function main() {
     // variable and a file, never the chat). Output goes above the input line
     // when the editor is active, otherwise to stdout.
     async function handleGoal(input) {
-        const g = parseGoalCommand(input);
+        const g = mod.commands.parseGoalCommand(input);
         if (!g)
             return;
         const emit = (line) => {
@@ -1864,7 +1884,7 @@ async function main() {
         // Hiding them from /help is not enough: a user could type the command by
         // hand, and it would rewrite their project's BACKLOG.md or snapshot src/.
         if (!devMode) {
-            const devCmd = isDevOnlyCommand(lower);
+            const devCmd = mod.commands.isDevOnlyCommand(lower);
             if (devCmd) {
                 console.error(theme.warn(t('msg.dev_only', { v: devCmd })));
                 continue;
@@ -2240,7 +2260,7 @@ async function main() {
                     const mark = s.id === currentChatId ? theme.user(' *') : '';
                     const title = s.title ? `  ${s.title}` : '';
                     const wd = s.workdir ? theme.dim(`  [${dirLabel(s.workdir)}]`) : '';
-                    const age = formatRelativeTime(s.updatedAt, t);
+                    const age = mod.commands.formatRelativeTime(s.updatedAt, t);
                     const ageText = age ? theme.dim('  ' + age) : '';
                     console.log(`  ${theme.user(n)}. ${s.id.slice(0, 8)}…${title}${wd}${ageText}${mark}`);
                 });
@@ -2415,7 +2435,7 @@ async function main() {
             continue;
         }
         if (lower === '/queue' || lower.startsWith('/queue ')) {
-            const q = parseQueueCommand(trimmed);
+            const q = mod.commands.parseQueueCommand(trimmed);
             if (!q) {
                 console.error(theme.error(t('msg.queue_usage')));
                 continue;
@@ -2431,7 +2451,7 @@ async function main() {
                 continue;
             }
             console.log(theme.system(t('msg.queue_title')));
-            for (const line of formatQueueList(pendingQueue)) {
+            for (const line of mod.commands.formatQueueList(pendingQueue)) {
                 console.log(theme.assistant(line));
             }
             console.log(theme.dim(t('msg.queue_cleared_hint')));
@@ -2452,7 +2472,7 @@ async function main() {
             continue;
         }
         if (lower.startsWith('/thinking') || lower.startsWith('/web')) {
-            const tg = parseLiveToggle(trimmed);
+            const tg = mod.commands.parseLiveToggle(trimmed);
             if (tg) {
                 applyLiveToggle(tg);
                 continue;
@@ -2751,7 +2771,7 @@ async function main() {
                     locale: currentLocale,
                     context: ctx,
                 }).length;
-                console.log(theme.system(formatContextSources(ctx.agents, ctx.memory, ctx.skills, ctx.commands, { systemPromptChars: sysLen }, t)));
+                console.log(theme.system(mod.commands.formatContextSources(ctx.agents, ctx.memory, ctx.skills, ctx.commands, { systemPromptChars: sysLen }, t)));
             }
             catch (e) {
                 console.error(theme.error(e.message));
@@ -2807,7 +2827,7 @@ async function main() {
             if (editor)
                 editor.busy = true;
             try {
-                await runTask(runTaskDeps(), browser, tools, lastTaskText, currentWorkdir, {
+                await mod.runTask(runTaskDeps(), browser, tools, lastTaskText, currentWorkdir, {
                     transcript,
                     freshChat: false,
                     sendSystemPrompt: false,
@@ -2838,8 +2858,8 @@ async function main() {
                 console.error(theme.error(t('diff.not_repo')));
                 continue;
             }
-            const out = await runGit(diffGitArgs(staged), currentWorkdir, 20_000);
-            console.log(theme.system(formatDiff(out, { maxLines: 400 }, t)));
+            const out = await runGit(mod.commands.diffGitArgs(staged), currentWorkdir, 20_000);
+            console.log(theme.system(mod.commands.formatDiff(out, { maxLines: 400 }, t)));
             continue;
         }
         if (lower === '/diffstat') {
@@ -2850,28 +2870,28 @@ async function main() {
                 continue;
             }
             const out = await runGit('git diff --stat', currentWorkdir, 20_000);
-            console.log(theme.system(formatDiffStat(out, { maxLines: 60 }, t)));
+            console.log(theme.system(mod.commands.formatDiffStat(out, { maxLines: 60 }, t)));
             continue;
         }
         if (lower === '/cost' || lower === '/usage') {
-            let stats = summarizeTranscript([]);
+            let stats = mod.commands.summarizeTranscript([]);
             if (transcript.file) {
                 try {
                     const body = await fs.readFile(transcript.file, 'utf-8');
-                    stats = summarizeTranscript(parseTranscript(body));
+                    stats = mod.commands.summarizeTranscript(mod.commands.parseTranscript(body));
                 }
                 catch {
                     // best-effort
                 }
             }
-            console.log(theme.system(renderCost(stats, transcript.file, browser.getLastTokenUsage(), t)));
+            console.log(theme.system(mod.commands.renderCost(stats, transcript.file, browser.getLastTokenUsage(), t)));
             continue;
         }
         if (lower === '/export' || lower.startsWith('/export ')) {
             const arg = trimmed.slice('/export'.length).trim();
             const target = arg
                 ? path.resolve(currentWorkdir, arg)
-                : defaultExportPath(currentWorkdir);
+                : mod.commands.defaultExportPath(currentWorkdir);
             const rel = path.relative(sandboxRoot, target);
             if (rel.startsWith('..') || path.isAbsolute(rel)) {
                 console.error(theme.error(t('export.outside')));
@@ -2880,13 +2900,13 @@ async function main() {
             let entries = [];
             if (transcript.file) {
                 try {
-                    entries = parseTranscript(await fs.readFile(transcript.file, 'utf-8'));
+                    entries = mod.commands.parseTranscript(await fs.readFile(transcript.file, 'utf-8'));
                 }
                 catch {
                     entries = [];
                 }
             }
-            const md = formatExport(entries, {
+            const md = mod.commands.formatExport(entries, {
                 chatId: currentChatId,
                 workdir: currentWorkdir,
             });
@@ -2918,7 +2938,7 @@ async function main() {
             const mcpStatus = mcpPool
                 ? mcpPool.status()
                 : { servers: [], toolCount: 0 };
-            console.log(theme.system(renderDoctor({
+            console.log(theme.system(mod.commands.renderDoctor({
                 nodeVersion: process.version,
                 platform: process.platform,
                 workdir: currentWorkdir,
@@ -2944,7 +2964,7 @@ async function main() {
         }
         if (lower === '/add-dir' || lower.startsWith('/add-dir ')) {
             const arg = trimmed.slice('/add-dir'.length).trim();
-            const res = resolveExtraDir(arg, currentWorkdir, t);
+            const res = mod.commands.resolveExtraDir(arg, currentWorkdir, t);
             if ('error' in res) {
                 console.error(theme.warn(res.error));
                 continue;
@@ -3000,8 +3020,8 @@ async function main() {
                 console.error(theme.warn(t('improve.no_backlog')));
                 continue;
             }
-            const items = parseBacklogItems(backlogText);
-            const item = nextBacklogItem(items, arg || undefined);
+            const items = mod.commands.parseBacklogItems(backlogText);
+            const item = mod.commands.nextBacklogItem(items, arg || undefined);
             if (!item) {
                 console.log(theme.dim(arg ? t('improve.not_found', { v: arg }) : t('improve.all_done')));
                 continue;
@@ -3017,7 +3037,7 @@ async function main() {
             if (editor)
                 editor.busy = true;
             try {
-                await runTask(runTaskDeps(), browser, improveTools, buildImprovePrompt(item), currentWorkdir, {
+                await mod.runTask(runTaskDeps(), browser, improveTools, mod.commands.buildImprovePrompt(item), currentWorkdir, {
                     transcript,
                     freshChat: false,
                     sendSystemPrompt: false,
@@ -3094,7 +3114,7 @@ async function main() {
             const rest = trimmed.slice('/review'.length).trim();
             const staged = rest.indexOf('--staged') !== -1;
             const focus = rest.replace(/--staged/g, '').trim();
-            const reviewTask = buildReviewPrompt(focus, staged);
+            const reviewTask = mod.commands.buildReviewPrompt(focus, staged);
             const reviewTools = mod.createTools(currentWorkdir, {
                 undo,
                 todos: todoStore,
@@ -3102,7 +3122,7 @@ async function main() {
             if (editor)
                 editor.busy = true;
             try {
-                await runTask(runTaskDeps(), browser, reviewTools, reviewTask, currentWorkdir, {
+                await mod.runTask(runTaskDeps(), browser, reviewTools, reviewTask, currentWorkdir, {
                     transcript,
                     freshChat: false,
                     sendSystemPrompt: false,
@@ -3317,7 +3337,7 @@ async function main() {
         // existing files are inlined; a bare `@name` in prose is left untouched.
         let finalTaskText = taskText;
         {
-            const refRes = await inlineAtRefs(currentWorkdir, taskText);
+            const refRes = await mod.attach.inlineAtRefs(currentWorkdir, taskText);
             if (refRes.inlined.length) {
                 finalTaskText = refRes.text;
                 console.log(theme.system(t('msg.at_refs', { n: refRes.inlined.length }) +
@@ -3357,7 +3377,7 @@ async function main() {
         if (editor)
             editor.busy = true;
         try {
-            await runTask(runTaskDeps(), browser, tools, finalTaskText, currentWorkdir, {
+            await mod.runTask(runTaskDeps(), browser, tools, finalTaskText, currentWorkdir, {
                 transcript,
                 freshChat: freshChatNext,
                 sendSystemPrompt: sendSystemPromptNext,

package/dist/system-prompt.js

@@ -98,11 +98,20 @@ export function renderContextSection(context) {
     }
     return out;
 }
-export function buildSystemPrompt({ workdir, tools, gitContext = null, locale = 'ru', attachments = [], context = null, selfImprovement = false, }) {
-    const t = translate(locale);
-    const toolDescriptions = tools
+// The tool list in the prompt is GENERATED from the ToolDefs (createTools),
+// never hand-written: a second copy drifts (the prompt promises a tool that
+// no longer exists, or misses one that was added). This is the single source
+// of truth for `### <Tool>` blocks; the prose that cannot be derived
+// ("Choosing the right tool", the call formats) stays hard-coded below.
+// Guarded by test/system-prompt-tools.test.ts.
+export function renderToolSection(tools) {
+    return tools
         .map((t2) => `### ${t2.name}\n${t2.description}\nParameters: ${JSON.stringify(t2.parameters)}`)
         .join('\n\n');
+}
+export function buildSystemPrompt({ workdir, tools, gitContext = null, locale = 'ru', attachments = [], context = null, selfImprovement = false, }) {
+    const t = translate(locale);
+    const toolDescriptions = renderToolSection(tools);
     const gitSection = gitContext
         ? `\n## Git context\n\n${gitContext}\n`
         : '\n## Git context\n\nNot a git repository (or git is not installed).\n';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zames_pro",
-  "version": "2.65.1",
-  "description": "Terminal coding agent that drives chat.deepseek.com through Playwright: reads and edits files, runs commands, commits to git.",
+  "version": "2.66.0",
+  "description": "Terminal coding agent that drives chat.deepseek.com through Playwright — no API key required. Reads and edits files, runs commands, commits to git, like Claude Code / Codex CLI.",
   "type": "module",
   "bin": {
     "zames": "dist/index.js"
@@ -10,6 +10,7 @@
     "dist",
     "scripts",
     "README.md",
+    "README.ru.md",
     "CHANGELOG.md",
     "LICENSE",
     "logo-small.jpg"
@@ -21,6 +22,7 @@
     "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
     "coverage:gate": "node scripts/coverage-gate.mjs",
     "changelog:draft": "tsx scripts/changelog-draft.mts",
+    "release": "tsx scripts/release.mts",
     "typecheck": "tsc --noEmit",
     "lint": "node scripts/eslint-ts6.mjs",
     "lint:fix": "node scripts/eslint-ts6.mjs --fix",
@@ -37,14 +39,21 @@
   "keywords": [
     "agent",
     "ai",
-    "deepseek",
-    "cli",
+    "ai-agent",
+    "ai-coding-assistant",
     "coding-agent",
+    "code-assistant",
+    "terminal-agent",
+    "deepseek",
+    "deepseek-chat",
     "claude-code",
     "codex",
+    "cli",
     "terminal",
     "playwright",
+    "browser-automation",
     "llm",
+    "no-api-key",
     "automation"
   ],
   "license": "MIT",

package/scripts/release.mts

@@ -0,0 +1,157 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  parseConventionalCommit,
+  groupCommits,
+  renderChangelogDraft,
+} from '../src/changelog.js'
+
+// One-command release prep (BACKLOG G4). The manual sequence — bump
+// package.json, write a dated CHANGELOG section, commit `chore: release X.Y.Z`,
+// tag — is easy to get wrong, so this script does the deterministic parts and
+// STOPS before the push. Pushing the branch and the tag is deliberately a
+// separate, explicit step: the tag triggers the npm publish workflow, and that
+// must never happen by accident.
+//
+// Usage:
+//   npm run release patch            # bug fixes
+//   npm run release minor            # new features
+//   npm run release major            # breaking changes
+//   npm run release patch --no-tests # skip the local test run (CI still runs)
+//   npm run release patch --dry-run  # print the plan, change nothing
+//
+// Run via tsx so it can reuse src/changelog.ts (the conventional-commit
+// parser) — a plain .mjs cannot import the TypeScript sources.
+
+const NL = String.fromCharCode(10)
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+function git(args: string[], allowFail = false): string {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf-8' })
+  if (r.status !== 0 && !allowFail) {
+    console.error('git ' + args.join(' ') + ' failed:' + NL + (r.stderr || ''))
+    process.exit(1)
+  }
+  return (r.stdout || '').toString()
+}
+
+function fail(msg: string): never {
+  console.error('release: ' + msg)
+  process.exit(1)
+}
+
+function run(cmd: string, args: string[]): void {
+  const r = spawnSync(cmd, args, { cwd: root, stdio: 'inherit', shell: process.platform === 'win32' })
+  if (r.status !== 0) fail(cmd + ' ' + args.join(' ') + ' exited ' + r.status)
+}
+
+const argv = process.argv.slice(2)
+const flags = new Set(argv.filter((a) => a.startsWith('--')))
+const bump = argv.find((a) => !a.startsWith('--'))
+const dryRun = flags.has('--dry-run')
+const skipTests = flags.has('--no-tests')
+
+if (bump !== 'patch' && bump !== 'minor' && bump !== 'major') {
+  fail('usage: npm run release patch|minor|major [--no-tests] [--dry-run]')
+}
+
+// 1. Clean tree: a release commit must contain ONLY the version bump and the
+// changelog section, never half-finished work.
+const dirty = git(['status', '--porcelain']).trim()
+if (dirty) {
+  fail('working tree is not clean:' + NL + dirty)
+}
+
+// 2. Gates. The git hooks run these on commit/push too, but a release should
+// fail EARLY, before package.json/CHANGELOG are touched.
+if (!skipTests) {
+  run('npm', ['run', 'typecheck'])
+  run('npm', ['test'])
+}
+
+// 3. Compute the next version from package.json.
+const pkgPath = path.join(root, 'package.json')
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as {
+  version: string
+}
+const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(pkg.version)
+if (!m) fail('package.json version is not a plain x.y.z: ' + pkg.version)
+let [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])]
+if (bump === 'major') {
+  major += 1
+  minor = 0
+  patch = 0
+} else if (bump === 'minor') {
+  minor += 1
+  patch = 0
+} else {
+  patch += 1
+}
+const next = major + '.' + minor + '.' + patch
+const tag = 'v' + next
+
+if (git(['tag', '--list', tag]).trim()) {
+  fail('tag ' + tag + ' already exists')
+}
+
+// 4. Build the dated CHANGELOG section from conventional commits since the
+// last tag. English commit subjects become the section body; the operator can
+// still reword the section afterwards.
+const latestTag = git(['describe', '--tags', '--abbrev=0'], true).trim()
+const ref = latestTag || git(['rev-list', '--max-parents=0', 'HEAD']).trim().split(NL).pop() || 'HEAD'
+const subjects = git(['log', '--no-merges', '--pretty=format:%s', ref + '..HEAD'])
+  .split(NL)
+  .map((s) => s.trim())
+  .filter(Boolean)
+const parsed = subjects
+  .map(parseConventionalCommit)
+  .filter((c): c is NonNullable<typeof c> => c !== null)
+const body = renderChangelogDraft(groupCommits(parsed))
+
+// CHANGELOG groups are `### Added` (Keep a Changelog), the draft renders
+// `## Added` — normalize here.
+const sectionBody = body
+  .split(NL)
+  .map((line) => (line.startsWith('## ') ? '#' + line : line))
+  .join(NL)
+const date = new Date().toISOString().slice(0, 10)
+const section =
+  '## [' + next + '] - ' + date + NL + NL + (sectionBody || '### Changed' + NL + NL + '- Internal improvements.') + NL
+
+if (dryRun) {
+  console.log('release(dry-run): ' + pkg.version + ' -> ' + next)
+  console.log('tag: ' + tag)
+  console.log('since: ' + ref)
+  console.log('CHANGELOG section:' + NL + section)
+  process.exit(0)
+}
+
+// 5. Insert the section right after the `## [Unreleased]` heading.
+const changelogPath = path.join(root, 'CHANGELOG.md')
+const changelog = fs.readFileSync(changelogPath, 'utf-8')
+const anchor = '## [Unreleased]'
+const idx = changelog.indexOf(anchor)
+if (idx < 0) fail('CHANGELOG.md has no "' + anchor + '" heading')
+const afterAnchor = idx + anchor.length
+const updated =
+  changelog.slice(0, afterAnchor) +
+  NL + NL + section +
+  changelog.slice(afterAnchor).replace(/^\n+/, NL)
+fs.writeFileSync(changelogPath, updated)
+
+// 6. Bump package.json, preserving its exact formatting (single-line replace
+// of the version value only).
+const pkgText = fs.readFileSync(pkgPath, 'utf-8')
+fs.writeFileSync(pkgPath, pkgText.replace('"version": "' + pkg.version + '"', '"version": "' + next + '"'))
+
+// 7. Commit + tag. The push is intentionally NOT done here.
+git(['add', 'package.json', 'CHANGELOG.md'])
+git(['commit', '-m', 'chore: release ' + next])
+git(['tag', tag])
+
+console.log(NL + 'release: committed and tagged ' + tag)
+console.log('Next (explicit) step — publish via CI:')
+console.log('  git push')
+console.log('  git push origin ' + tag)