Skip to content

Карта: окончательная архитектура ycli и refract #602

Open
0 of 7 issues completed

Description

@bim-ba

Карта ведет к окончательной архитектуре ycli и refract. Вопросы к тебе - подзадачи этой карты, ответы - в них самих.

Пункт назначения

Утвержденная и записанная архитектура: как одно описание операции превращается в SDK, CLI и MCP на нескольких языках и для чужих API, а не только для Python и Яндекса. На выходе ADR, глоссарий и спецификация, по которым можно планировать сборку. Код в рамках карты не меняется.

Заметки

  • вопросы, примеры и места, где нужен твой взгляд, я публикую только в issue этой карты (твое решение от 19.11)
  • решение проверяется на матрице «язык × API», одного Python и Яндекса мало
  • сессии по карте опираются на навыки grilling, domain-modeling, codebase-design, showing-the-owner и researching-rigorously
  • исходные материалы:
    • ревью 18.11, четыре волны с проверяющими;
    • реестр 73 решений из чата 12–14.10, он в первом комментарии;
    • архив ycli-research-2026-11-10.tar.zst: спецификация v1.3, брифы, kit13 и kit14

Решения

  • 14.10, в чате. Описания операций пишутся на Python. Из них собирается OpenAPI 3.1 с ключами x-ycli-*. refract, написанный на Python, генерирует по нему код на рукописном ядре каждого языка, и сгенерированное лежит в git. Это отменяет решение Вывод SDK, CLI и MCP из описания операции: итог исследования и пять решений до пробы #508 1-А о выводе во время работы. Подтверждение ждет бенчмарка.
  • 19.11. Ядро не вводит свои типы ошибок поверх неправильной логики чужого API. Такие причуды делаются через точку расширения refract.
  • 19.11. Секреты по именам полей не маскируем, сложных обходов ради маски не делаем.
  • 19.11. Метки needs:, scope:, priority:, type: и wayfinder: (PR ci: manage issue labels from .github/labels.yml #601).
  • 19.11. Доверенный издатель на PyPI настроен - по твоим словам, я этого не проверял.

Еще не уточнено

  • форма описания операции: декоратор, данные или вывод из сигнатуры. Станет ясно после бенчмарка
  • где живут спецификация и ядра других языков: в refract или в отдельных репозиториях
  • как refract проверяет сгенерированный код на чужих API. В старом refract это делали стратегии
  • гибридный MCP по умолчанию. Нужен прогон на настоящей модели

Вне рамок

Activity

  1. bim-ba commented on Nov 18, 2026

    @bim-ba
    OwnerAuthor

    Реестр твоих решений из этого чата за 12-14.10: 73 решения, из них 66 окончательных. Ни одно из них не записано ни в репозиторий, ни в issue. Ниже - все, сгруппированные по теме. Смысл решения написан по-английски, как в будущем ADR, а рядом твои слова. Перекрытые решения перечеркнуты.

    review-process
    решение твои слова
    C01, 10.10: Every area of the #459 tech-debt review gets its own independent checker, not only the final consolidation. «я за то чтобы проверять каждую область»
    C02, 10.10: How many readers run in parallel per wave is the agent's call. «ок, запускай сколько считаешь нужным и правильным»
    C04, 11.10: The test organization may be used for any action during the review; review quality outranks caution (the no-network rule is lifted). «не не, если что это моя тестовая организация с ней можно че угодно делать, мне очень важно качество ревью от тебя, так что делай че хочешь»
    repo-hygiene
    решение твои слова
    C03, 10.10: Delete the 249 merged local branches and 11 merged worktrees; the listed unmerged branches, the 0497be9 head and both stashes stay untouched. «ок»
    research-method
    решение твои слова
    C05, 11.10: Researchers must use external sources (twitter, rdt CLIs; brave, deepwiki, context7 MCP), not only docs and installed sources. «а они же юзают внешние ресурсы типа CLI: twitter, rdt, итд MCP: brave, deepwiki, context7, итд ?»
    C15, 12.10: Validate every hypothesis by measurement, and show pseudocode for each option in the chat. «обязательно валидируй и проверяй любую свою гипотезу, а кстати еще показывай какой-нибудь псевдокод по своим вариантам в будущем здесь в чате»
    C22, 12.10: Add an Opus subagent that both researches (our data, references, social media, external sources) and synthesizes new ideas, beside the Sonnet scout. «я хочу чтобы этот opus 5.5 и свои идеи делал и ресерчил тоже для вдохновение и референсов, короче говоря ему на вход (наши данные, референсы, соцсети, внешние источники)»
    C27, 13.10: Do not keep polishing one line; consider new ideas even if they rework the core, and study how operations are declared in many different languages. «развивать архитектуру какую-то одну… хорошо, но блин какие-то новые крутые идеи чтобы ты из-за этого не рассматривал - вот это очень плохо»
    research-scope
    решение твои слова
    C06, 11.10: The tech-debt review also evaluates external libraries worth installing. «а и еще изучи, мб какие-нибудь внешние либы стоит установить которые нам жизнь упростят»
    C14, 11.10: The agent both researches and proposes/builds the #508 architecture, with any subagents and external tools; the owner returns to it at implementation time. «давай ты будешь и ресерчить и архитектуру тоже предлагать и выстраивать. ты вправе запускать субагентов разных, юзать разные внешние инструменты»
    issue-format
    решение твои слова
    C07, 11.10: All open questions go to GitHub issues labelled needs-decision, with examples, strategies, trade-offs and risks. «а ты можешь вынести мне все открытые вопросы в Issue с меткой needs-decision же? как я люблю, с примерами, стратегиями, трейдоффами, рисками и так далее»
    C13, 11.10: needs-decision issues must be short business-level summaries with before/after or pseudo-examples and rendered diagrams (mermaid or SVG); long prose will not be read. «ты еще в эти issues прикладывай какие-нибудь диаграммы например в svg или mermaid… мне нужна вот прям сжатая конкретика бизнесовая»
    test-org
    решение твои слова
    C08, 11.10: Whichever organization is working and reachable is the test organization; clean up the worktree branches too. «я хз, глянь какая из этих организаций работает и доступна - та и рабочай. уборка рабочих веток - делай»
    security-ci
    решение твои слова
    C09, 11.10: Live e2e on pull requests runs only after explicit approval by the owner or maintainers, enforced by GitHub environment rules (yandex-e2e main-only, yandex-e2e-pr with required reviewer), configured by the agent. «согласен, а ты можешь все это сам настроить правильно? у тебя все доступы есть. google chrome даже естб.»
    C11, 11.10: The agent may fill the second environment's secrets itself from the local credentials (the service account and the personal account are the same account). «нет, сервисная учетка и моя личная это буквально одно и то же, проверь и подставь сам. это буквально мой личный аккаунт»
    C12, 11.10: Publish the safety findings as an ordinary public needs-decision issue (option A), not a private advisory and not fix-first. «да, я за вариант А»
    testing-scope
    решение твои слова
    C10, 11.10: Test 100% of resources and operations, not a sample, everywhere; live tests on the owner's test DataLens are allowed. «делай, если ты хочешь протестировать вот прям все ресурсы и операции, то тестируй 100% а не 20% как ты делаешь сейчас, это касается всего»
    C23, 12.10: Every hypothesis is measured on all APIs of the pool, not only ycli's operations. «а почему только по ycli прогон делается и по его операциям? почему не по всем АПИшкам сразу как мы любим? опять недоделываешь?»
    C36, 13.10: Measure on all target languages and on every Yandex service in the snapshot, not just the four wrapped ones. «и мне кажется на многих языках надо это мерить как получается? … и яндексовскую АПИшку ты полностью тестируешь все прям сервисы или опять только наши 4 текущих?»
    C73, 14.10: Approve a scenario generator from declared rules (74 behaviour classes over the whole pool) and a cross-language comparison of request plans on all 1,924 operations. «ок»
    product-goal
    решение твои слова
    C16, 12.10: Do not integrate existing generator libraries; aim for more unification and nicer interfaces than they give (SDK + CLI + MCP from one source). «если мы интегрируем эти либы к себе, то мы мало что выиграем и надо именно стремиться к еще более большой унификации и красивым интерфейсам»
    C37, 13.10: Product identity: one standard for API wrappers (pagination, retries) plus CLI and MCP, so every API looks the same instead of each wrapper having its own style. «мне всегда было впадлу писать всякие API Wrapper с пагинациями всякими, ретраями… и нету как-будто единого стандарта в CLI и MCP в нашу эру, а наш тул это как раз закрывает»
    refract-scope
    решение твои слова
    C17, 12.10: refract must generate SDKs in other languages from the same description as ycli, so the description has to be portable data (variant III, not code inside the description). «да, я бы хотел чтобы через refract можно было бы генерировать SDK на разных языках, но я пока хз как именно это лучше всего сделать»
    C32, 13.10: refract (alpha) will be rebuilt for the new architecture; its input format is open, OpenAPI preferred, so that clients can generate everything quickly. «refract еще в альфе находится… восстановить этот проект потом вот под то что мы придумаем. но по большому счету формат там любой может быть, конечно я планировал openAPI»
    C33, 13.10: refract serves both external developers with an OpenAPI and ourselves; an agent reverse-engineers an API into OpenAPI, which is extended within the spec and fed to refract. «и то и другое + мне кажется в современном мире будет так, что есть какая-то АПИшка без OpenAPI, ее дадут реверсить какому-нибудь агенту, он из нее выводит OpenAPI»
    C68, 14.10: The old refract alpha is no reference or source of truth; any of its concepts may be revised and refract is rebuilt almost from scratch for the best product. «да бля я наоборот хотел сказать что refract это не показатель вообще, делай как считаешь нужным, не нужно его воспринимать как какой-то источник истины»
    catalogue
    решение твои слова
    C18, 12.10: Our metadata goes into OpenAPI as x-ycli-* extensions, so stripping them gives back the original spec. «ну а почему бы не делать например тоже так: x-ycli-*? типа прям там в спеке указывать метаданные какие-то, мы же можем делать extend этой спецификации»
    C56, 14.10: The catalogue is plain OpenAPI 3.1 with our x-… keys, no format of our own; each extension maps to one core concept. «хм, ну вроде выглядит норм, а типа наши "расширения" это такие штуки которые не описываются в спеке… и типа описаны они будут в ядре?»
    C60, 14.10: The generator is the only reader of OpenAPI and bakes operation tables into generated code; for foreign APIs: original OpenAPI + x-ycli-* extensions, and the rest hand-written on the core, marked in OpenAPI as hand-written. «есть оригиинальная OpenAPI спека, вы ее можете чуть расширить чтобы сгенерить больше SDK, остальное описывайте будьте добры руками через наше ядро»
    procedures
    решение твои слова
    C19, 12.10: Only operations and simple procedures are described declaratively; complex procedures (loops, state, recovery) are code written on the shared core from our operations, not raw HTTP, and are not unified. «есть смысл смотреть в сторону того чтобы декларативно описывать именно простые процедуры. потому что я даже хз как унифицировать сложные процедуры»
    C20, 12.10: A procedure receives the client/session by dependency injection as its first argument instead of yield-based calls. «а почему сессия это не dependency injection первым аргументом сюда же? разве это не покрасивее история?»
    core
    решение твои слова
    C21, 12.10: Endpoint, Operation, Flow and Call may be evolved, decomposed or deleted; the criterion is a beautiful architecture. «нам никто не запрещает развивать и Endpoint и Operation и Flow и Call декомпозировать или удалить правильно… главное просто красиво архитектурно»
    C25, 13.10: The core is an investment judged by payback (the hand-written per-resource layers it removes), not by a hard line cap; the agent has full carte blanche on that trade-off. «да, это буквально инвестиция в будущее, мы пишем ядро, с помощью которого будем экономить кучу строчек кода потом… от меня тебе ПОЛНЫЙ КАРД БЛАНШ»
    C51, 14.10: Each language gets a hand-written typed core with the same concepts (endpoint, pagination, operation, client, serializer…); generation emits a thin typed layer on it, and wrappers can be hand-written on the same core; per-language dependencies are fine. «мы пишем ядро на каждом языке со всеми нужными абстракциями. и ядро - это по факту интерфейс который будет использоваться при генерации… можешь вручную писать API wrapper»
    C52, 14.10: Concepts and names are identical across languages while the public form is idiomatic per language (Azure SDK style); fully identical abstractions may be overkill. «да, абсолютно точно, типа понятия и концепции одни и те же, абстракции могут чуть отличаться от языка к языку, но типа высокоуровнево оперируем именно нашими абстракциями»
    C66, 14.10: Rebuild all five language cores by the common layout (12 same-named modules, the runtime reads no catalogue, unit tests per module). «да, мне вот эта раскладка тоже нравится которую ты предложил, давай попробуем на разных языках посмотреть что с ней будет»
    deliverable
    решение твои слова
    C24, 13.10: Review the hypotheses for UX/DX and Clean Code/SOLID and publish pseudocode of each hypothesis (simple and complex op, pagination, polling) in an issue, in Python, Go, Rust, C#, Java, TypeScript and JavaScript. «расширь языки примеров: Python, Go, Rust, C#, Java, TypeScript, JavaScript»
    authoring-style
    решение твои слова
    C26, 13.10: Declarations use modern FastAPI-style Python with Annotated metadata rather than functions that build the request (segment/comma); the functional style needs an argument. «мне больше нравится современное программирование на python когда мы прям так через Annotated много че описываем, такой знаешь современный вайбик FastAPI стиль»
    C30, 13.10: Declarations are written and maintained by humans and agents equally, so explicit beats short. «но тут нужно думать не кто будет набирать, а поддерживать и так далее, вот тут и агенты и сами люди. поэтому ответ - поровну»
    surfaces
    решение твои слова
    C28, 13.10: Design SDK + core first and extend CLI and MCP from it; tight coupling with the three known surfaces is accepted (no generic future-surface abstraction); refract generates SDK, CLI and MCP. «нужно проектировать отдельно SDK + Ядро, а потом думать как за-extend-ить от этого CLI и MCP… мб tight-coupling оправдан, типа я про то, что refract генерит SDK + MCP + CLI»
    C29, 13.10: Surface hints (CLI flag, help, MCP marks) live in the operation declaration next to the parameter (variant 1, one source of truth); the agent refined it to hints declared once on the type. «как-будто бы 1 вариант хорош, если мы допускаем tight-coupling + все видно в одном месте… мне нравится что 1 источник истины будет»
    compat
    решение твои слова
    C31, 13.10: Existing ycli library users may be broken freely, with no transition layer (there are about zero clients). «можно ломать свободно, вообще не переживай, щас клиентов вообще 0 скорее всего»
    C45, 14.10: A deprecated operation lives for one release. «один»
    source-of-truth
    решение твои слова
    C34, 13.10: In ycli the Python declarations are the single source of truth for every service; OpenAPI is imported once to start a service and exported any time (variant 1). «мне наверное тоже 3 вариант больше нравится, но в целом же можно сделать так, что наша архитектура может и импортировать и экспортировать OpenAPI спеку расширенную, поэтому мб вариант 1?»
    mcp
    решение твои слова
    C35, 13.10: MCP shows frequent operations as separate tools plus search-and-call for the rest (variant 3); the UX/DX details are the agent's to decide. «наверное 3 вариант хорош, но я сам MCP не пользуюсь, им пользуется агент, подумай ты на счет UX/DX»
    C41, 14.10: The hybrid MCP form becomes the default only after a run with a real model. «после прогона. а что за гибридный MCP?»
    C48, 14.10: Operations always loaded into the agent's context are marked by metadata on the operation (load_always=True), not guessed. «ну да, прикольная идея, кстати вот такие частые операции которые всегда подгружаются в контекст можно обозначать метаданными тоже как-нибудь типа load_always=True»
    cli
    решение твои слова
    C38, 14.10: Command and tool names keep the order service resource action, not kubectl-style verb first. «да»
    C47, 14.10: At most two positional CLI arguments (identifiers of the target), everything else flags; exceptions are counted and the rule is revisited above ten. «ну вроде норм история»
    C70 Nested CLI objects: lean to one option with k=v shorthand or JSON (C), pending implementation cost. (заменено C71) «ну наверное да, C вариант прикольно выглядит, но ты глянь что проще в реализации будет и не запаристее, вариант A конечно не человечный поэтому его не смоттри»
    C71, 14.10: Nested CLI objects use option B: one flag per field with the full dotted path (--author.id), JSON accepted in the same option for what B cannot express, --body-file for the whole body. «да, бери B»
    sdk
    решение твои слова
    C39 A request body with more than three fields becomes one model (39 operations change). (заменено C46) «наверное да. нужно примеры глянуть, а ты как сам думаешь?»
    C40, 14.10: Parameters get Python-style names (story_points); responses keep the API's field names. «да»
    C46, 14.10: FastAPI-style declarations: path parameters are scalars; query parameters and body are each scalars up to three fields, otherwise one model; the SDK signature unpacks model fields into keyword arguments. «ну наверное да, кстати а тут же по идее можно в FastAPI стиле сделать же… @tracker.post("/issues/{id}") def issues(id: int, *, params = Params(...), body = Body(...))»
    mcp-safety
    решение твои слова
    C42 Where the client cannot ask a person, confirm a destructive call with a second call carrying a token. (заменено C50) «хз, вторым вызовом мб, а есть примеры?»
    C50, 14.10: Confirming destructive operations is the harness's job; the server only labels effects honestly (the hybrid generic call is split by effect) and invents no confirmation token; the CLI keeps its prompt and --yes. «а что если сделать попроще и типа чтобы харнесс сам определял разрушающая операция или нет? мне кажется другие модельки и харнессы это рано или поздно подхватят»
    config
    решение твои слова
    C43, 14.10: Environment variables win over a named profile (the profile no longer replaces the environment). «окружение побеждает да»
    cli-output
    решение твои слова
    C44, 14.10: Rename the output format pretty to table. «да»
    mcp-output
    решение твои слова
    C49 MCP text part is a short table and the structured part the full data, with the shown fields declared as metadata without tight coupling. (заменено C59) «ну в целом вариант 2 хорош, но тогда там нужно метаданными как-то будет описывать типа какие поля достойны показываться в текстовом варианте»
    C57, 14.10: An MCP tool returns both a text part and structured content. «согласен с "Оба"»
    C59, 14.10: The MCP text part is the same serialized JSON truncated to the result budget, as the MCP spec says; Summary() serves only CLI tables, docs and list previews. «согласен с твоей рекомендацией»
    sdk-null
    решение твои слова
    C53, 14.10: Optional fields the caller did not set are not sent; an explicit null is sent only on request. «да, соглы»
    C61, 14.10: An optional argument defaults to an Omit sentinel and is not sent; None sends null and clears the field (in every language). «мне тоже этот вариант больше нравится»
    standing-asks
    решение твои слова
    C54, 14.10: Standing asks: test ALL APIs (big pool) and ALL languages; Clean Code/SOLID with decomposition (no 1500–2000-line files); creativity and synthesis; propose simplifying trade-offs (cut, use native features); ask and discuss. «тестировать ВСЕ АПИшки, большой пул - тестировать ВСЕ языки - смотреть с точки зрения Clean Code и SOLID принципов… - креативность и синтез идей!!!»
    generation
    решение твои слова
    C55, 14.10: Generate the Python SDK the same way as the other languages (declarations → catalogue → generated code) instead of deriving it at runtime. «хм, ну наверное хорошая идея, мне нравится, а есть примеры типа?»
    C58, 14.10: Generated code is committed to git (CI checks it equals a fresh generation; manual tweaks live in _patch.py). «да. лучше хранить генерацию в гите. полезно будет»
    java
    решение твои слова
    C62 Java passes body fields through a lambda that fills a builder (AWS SDK v2 style). (заменено C63) «да, B вариант мне тож больше нравится»
    C63, 14.10: Java: per-field methods on models plus a lambda overload on every operation; no empty() on a model with required fields. «а, вернее вот, у тебя уже хорошее решение ты придумал»
    refract-lang
    решение твои слова
    C64, 14.10: refract is written in Python and installed via uvx / uv tool install; Rust only if measured speed demands it. «мне наверное хотелось бы на python его написать, потому что distribution просто лучше будет именно на нем из-за uvx… rust хорош… но нужно мерить»
    C65 Maybe refract could be in Rust after all, pending distribution, OS support and library quality. (заменено C67) «а, ну если так, то можно впринципе и на rust наверное сделать, но я хз, надо будет подумать над: distribution и интеграциями»
    C67, 14.10: Decide refract's language by building, profiling and debugging both a Python and a Rust generator (spike result: Python, Rust only for interactive use). «очень важно замерить, профилировать и отдебажить оба варианта, я не отрицаю что refract может быть на python»
    mcp-metadata
    решение твои слова
    C69, 14.10: MCP selection lives in OpenAPI as an x-ycli-mcp object on the operation (ycli's build writes it from Mcp(...); foreign APIs add it directly or by Overlay); audience profiles are a server start flag (--toolsets), not spec; x-ycli-cli by analogy. «да, хорошо звучит архитектурно мне нрав»
    quality
    решение твои слова
    C72, 14.10: Clean Code/SOLID are judged per language by its community canon and standard linters, plus shared rules (modules ≤~400 lines, no cycles, private internals, one concept map). «кстати, здесь на счет этого пункта же Clean Code + SOLID принципы и другие штуки в разных языках свои есть какие-то стандарты де-факто окоторые есть в комьюнити?»
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions