asana-comments

Постраничное чтение комментариев (stories) задачи Asana через REST. Скрипт-эталон - scripts/asana-comments.py (top-level папка scripts/ в корне проекта). Только stdlib, из внешнего - опционально certifi.

Зачем отдельный скрипт под чтение ленты

Лента комментариев - единственная часть Asana, где поштучный запрос молча отдает неполные данные. У хостового Asana MCP (mcp.asana.com/v2/mcp), пока он использовался, в схеме get_task стояло comment_limit = "Max comments to return (1-50)", maximum: 50, а курсора по ленте не было вовсе: пагинация (offset) есть только у get_tasks, то есть для списка задач.

Следствие переживает сам MCP и повторяется в любом наивном запросе одной задачи: часть ленты остается недостижимой, и выглядит это не как обрезка, а как отсутствие комментариев - готовый ложный вывод "там ничего нет" по живой задаче (учебный случай rules/silent-failure.md: ответ одинаков при полной и урезанной ленте). REST-эндпоинт /tasks/{gid}/stories пагинацию поддерживает, скрипт ее и разматывает.

Когда применять

• В задаче много комментариев, а нужны свежие.
• Пользователь ссылается на комментарий, которого в обычной выдаче не видно.
• Нужен отбор по дате или вся история целиком.

Когда НЕ применять

• Задачи, статусы, проекты, создание задач, написание комментария - это единичные операции, они делаются REST напрямую тем же PAT (POST /tasks/{gid}/stories с html_text для комментария). Исключение - пакетное разворачивание/досыпка доски из JSON-плана: скилл asana-project.
• Лента короткая и уже получена целиком - лишний канал не заводить.

CLI

python3 scripts/asana-comments.py <task_gid>                  # последние 10 комментариев
python3 scripts/asana-comments.py <task_gid> --last 30
python3 scripts/asana-comments.py <task_gid> --auth ~/.config/asana/auth-work.json --last 30
python3 scripts/asana-comments.py <task_gid> --all --system   # вся история + системные события
python3 scripts/asana-comments.py <task_gid> --since 2026-07-20

task_gid - последнее число в URL задачи.

Флаги:

• --auth <файл> - файл PAT нужного аккаунта, имеет приоритет над окружением.
• --last <N> - сколько последних показать (по умолчанию 10). Лента приходит от старых к новым, поэтому "последние" берутся с конца.
• --all - показать все, игнорируя --last.
• --system - включить системные события (назначения, смены статуса), а не только комментарии.
• --since <YYYY-MM-DD> - только начиная с этой даты, граница включительно.

Авторизация: нужен именно Personal Access Token

Порядок выбора PAT: --auth <файл> -> непустой ASANA_TOKEN -> ~/.config/asana/auth.json. Краевые пробелы токена удаляются, ~ в пути раскрывается. Формат файла - {"token": "..."}, права 600. Ошибка явно указанного файла останавливает команду без перехода к окружению или стандартному файлу. При нескольких аккаунтах --auth <файл> обязателен в каждой команде, включая чтение и dry-run. Без токена скрипт печатает готовые команды настройки. Токен - секрет: в синкаемые папки, заметки, чаты и артефакты не класть (см. rules/secrets-handling.md).

Как получить PAT - проговаривать пользователю по шагам, здесь ошибаются регулярно:

1. Открыть консоль разработчика Asana - корневую страницу "Мои приложения" (не страницу конкретного приложения).
2. Прокрутить ниже списка приложений до блока "Личные токены доступа" / "Personal access tokens".
3. "+ Create new token" -> скопировать строку вида 2/.... Показывается один раз.
4. Не создавать приложение. Кнопка "Create app" на виду и провоцирует пойти по ней, но credentials приложения к REST не подходят.

Три способа получить 401, каждый пойман на живом инциденте:

• OAuth-токен MCP-сервера не работает против REST - актуально для сервисов, которые еще ведутся через MCP; у самой Asana MCP снят полностью (см. "Граница скилла"). Он audience-bound к mcp.asana.com, а app.asana.com/api/1.0 его не принимает; лежит в ~/.claude/.credentials.json -> mcpOAuth, refresh-токена рядом нет. Доставать его оттуда бессмысленно и хрупко.
• client_id приложения - это цифры. Не подходит.
• client_secret приложения - 32 hex-символа. Не подходит.

Отличать по форме: PAT длинный (50+ символов) и начинается с цифры и слэша (2/...). Если значение на это не похоже - выдан не тот секрет.

Troubleshooting

• 401 при валидном на вид токене - сверить форму значения по признакам выше. Чаще всего это client_id, client_secret или OAuth-токен MCP.
• CERTIFICATE_VERIFY_FAILED на macOS - сборка с python.org не видит системные CA. Скрипт сам подхватывает certifi, если тот установлен (pip3 install --user certifi).
• Пусто по живой задаче - проверить, не отфильтровал ли --since, и не нужен ли --system: по умолчанию показываются только комментарии, без системных событий.

Граница скилла

Скрипт делает ровно одно - постраничное чтение ленты - и ничего не пишет: он read-only по своей природе (только GET). Остальная работа с Asana распределена так:

• пакетная запись (развернуть или досыпать доску из плана) - скилл asana-project, тот же токен;
• единичные операции (одна задача, статус, комментарий) - REST напрямую: база https://app.asana.com/api/1.0, заголовок Authorization: Bearer <token>.

Asana MCP в этой схеме не участвует. Он был основным каналом до 17.08.2026 и снят: за одну сессию дисконнекты, зависание вызова на 300 с и Not Authorized сразу после переавторизации - при нуле сбоев у скриптов на PAT. Плюс OAuth молча берет аккаунт из того браузера, где человек залогинен, так что привязка не к тому аккаунту происходит незаметно (rules/mcp-multi-account.md). Не хватает поштучной операции - дописать маленький скрипт на том же токене, а не возвращать MCP.

Связанные файлы

• scripts/asana-comments.py в корне проекта - эталонный скрипт.
• ~/.config/asana/auth.json - PAT, вне репозитория, права 600.
• rules/secrets-handling.md - общее правило обращения с токенами.

Модель и текущие назначения

Перед новым заданием и запуском применяй маршрутизацию моделей: свежий MODELS выше канонического дефолта. Границы данных и полномочий этого навыка сохраняются.