Back to Details

graph-memory-bank

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Graph Memory Bank

图形化记忆库

Цель

目标

Сформировать и поддерживать графовую память проекта (как в Obsidian), чтобы ИИ-агенты быстро собирали точный минимальный контекст:
  • много маленьких файлов, каждый про одну сущность/идею;
  • связи через обычные markdown-ссылки;
  • у каждого узла есть краткий YAML frontmatter (машиночитаемый);
  • есть обратные ссылки (backlinks), чтобы граф был двунаправленным.
构建并维护项目的图形化记忆库（类似Obsidian），以便AI Agent能够快速收集精准且极简的上下文：
  • 多个小型文件，每个文件对应一个实体/想法；
  • 通过常规Markdown链接建立关联；
  • 每个节点都包含简短的YAML前置元数据（机器可读）；
  • 包含反向链接（backlinks），使图形结构具备双向关联性。

Результат (что должно получиться)

成果（最终产出）

Обычно: 
docs/graph/
в репозитории, где есть 3 слоя:
  1. tasks/
    (история изменений: релизы/задачи/коммиты, “что менялось”)
  2. project/
    (семантика: архитектура, ключевые сущности, контракты, API, БД, интеграции, “куда смотреть в коде”)
  3. processes/
    или 
    process/
    (процессы: правила ведения графа, как обновлять, как читать, качество, генераторы)
Важно: если в репозитории уже есть один из вариантов (
process/
или 
processes/
) или другая устоявшаяся структура, не переименовывай “ради красоты”. Подстраивайся под текущую структуру, а в индексах дай явные ссылки.
Если слой процессов пока не нужен, начинай с первых двух, но держи место под третий слой.
通常为仓库中的
docs/graph/
目录，包含3个层级：
  1. tasks/
    （变更历史：发布/任务/提交，“变更内容”）
  2. project/
    （语义层：架构、核心实体、契约、API、数据库、集成，“代码查看指引”）
  3. processes/
    或
    process/
    （流程层：图形库维护规则、更新方式、阅读指南、质量标准、生成工具）
重要提示：如果仓库中已存在
process/
或
processes/
其中一种结构，或其他既定结构，请勿为了“规范化”而重命名。应适配现有结构，并在索引中添加明确链接。
如果暂时不需要流程层，可先从前两个层级开始，但需预留流程层的位置。

Инварианты (жесткие правила)

不变规则（硬性要求）

  1. Дроби информацию: один файл = одна сущность/идея/контракт.
  2. Держи узлы короткими: как правило, до 200-300 строк; если разрастается, выноси подузлы.
  3. У каждого узла есть YAML frontmatter (минимум: 
    id
    , 
    type
    , 
    title
    , 
    description
    , 
    status
    , 
    tags
    ).
  4. Всегда добавляй связи:
    • outbound links: “см. также”, “используется в”, “зависит от”
    • backlinks: “где используется” (явные ссылки обратно на индексы/хабы)
  5. Если в проекте есть 
    _generated/
    или другие generated-секции: не редактируй руками, правь генератор или исходный узел.
  6. Если есть сомнения/риски: подсвечивай и задавай вопросы (лучше уточнить, чем зацементировать неверную семантику).
  1. 拆分信息：一个文件 = 一个实体/想法/契约。
  2. 保持节点精简：通常不超过200-300行；若内容过长，需拆分出子节点。
  3. 每个节点必须包含YAML前置元数据（至少包含：
    id
    , 
    type
    , 
    title
    , 
    description
    , 
    status
    , 
    tags
    ）。
  4. 务必添加关联：
    • outbound links（出站链接）：“另请参阅”“应用于”“依赖于”
    • backlinks（反向链接）：“应用场景”（指向索引/枢纽节点的显式链接）
  5. 若仓库中存在
    _generated/
    或其他自动生成目录：请勿手动编辑其中内容，应修改生成器或源节点。
  6. 若存在疑问/风险：需高亮标注并提出问题（宁可确认清楚，也不要固化错误的语义）。

Рекомендованная схема frontmatter (минимум)

推荐的前置元数据模板（必填项）

Делай frontmatter максимально стабильным (для индексирования агентами):
  • id
    : глобально уникальный идентификатор узла
  • type
    : тип узла (
    project
    , 
    dev_task
    , 
    release_review
    , 
    screen
    , 
    rf_procedure
    , 
    db_table
    , ...)
  • title
    : человекочитаемое имя
  • description
    : 1 предложение “зачем этот узел”
  • status
    : 
    stub | curated | generated
  • tags
    : плоский список тегов (короткие)
Опционально (если реально помогает): 
releases
, 
source_paths
, 
owner
, 
risk_level
.
确保前置元数据尽可能稳定（便于Agent索引）：
  • id
    ：节点的全局唯一标识符
  • type
    ：节点类型（
    project
    , 
    dev_task
    , 
    release_review
    , 
    screen
    , 
    rf_procedure
    , 
    db_table
    , ...）
  • title
    ：人类可读的节点名称
  • description
    ：1句话说明“该节点的用途”
  • status
    ：节点状态（
    stub | curated | generated
    ）
  • tags
    ：扁平化标签列表（简洁）
可选字段（若确实有帮助）：
releases
, 
source_paths
, 
owner
, 
risk_level
。

Как оформлять индексы (важно)

索引编写规范（重要）

В индексах пиши не только ссылки, но и микро-аннотацию, чтобы не открывать каждый файл:
  • - [DEV-12345](...): 6-10 слов, что внутри
    .
在索引中不仅要添加链接，还要附上微型注释，避免用户需要打开每个文件查看内容：
  • 示例：
    - [DEV-12345](...): 6-10字的内容说明

Что НЕ делать

禁止操作

  • Не тащи секреты/токены/пароли в 
    docs/
    (максимум: “ищется в переменных окружения X/Y”).
  • Не дублируй большие куски кода/SQL: вместо этого “якоря” + короткая выжимка + ссылка на файл.
  • 请勿将机密信息/令牌/密码存入
    docs/
    目录（最多可标注：“信息位于X/Y环境变量中”）。
  • 请勿复制大段代码/SQL：应使用“锚点”+简短摘要+文件链接替代。

Быстрый workflow (универсальный)

快速工作流（通用）

0) Подготовка

0) 准备工作

  1. Создай отдельную ветку (например 
    graph+memory
    ).
  2. Уточни ограничение записи:
    • по умолчанию пиши только в 
      docs/
      (или другой явно согласованный каталог).
  3. Найди, есть ли уже документация/конвенции (
    docs/
    , 
    ADR
    , 
    mkdocs
    , 
    docusaurus
    ).
  1. 创建独立分支（例如
    graph+memory
    ）。
  2. 明确写入权限限制：
    • 默认仅写入
      docs/
      目录（或其他已明确约定的目录）。
  3. 检查仓库中是否已有文档/规范（
    docs/
    , 
    ADR
    , 
    mkdocs
    , 
    docusaurus
    ）。

1) Сбор каркаса (bootstrap)

1) 搭建框架（Bootstrap）

  1. Создай 
    docs/graph/index.md
    (входная точка).
  2. Создай индексы: 
    • docs/graph/tasks/index.md
    • docs/graph/project/index.md
    • docs/graph/processes/index.md
      или 
      docs/graph/process/index.md
      (в зависимости от структуры репозитория)
  3. Зафиксируй соглашения:
    • схема 
      id
      (обычно префикс + путь, например 
      graph:project/<slug>
      )
    • статусы: 
      stub | curated | generated
    • теги: короткие, стабильные (не плодить)
Шаблоны и чек-листы: см. 
references/templates.md
и 
references/quality-bar.md
.
  1. 创建
    docs/graph/index.md
    （入口文件）。
  2. 创建索引文件： 
    • docs/graph/tasks/index.md
    • docs/graph/project/index.md
    • docs/graph/processes/index.md
      或
      docs/graph/process/index.md
      （取决于仓库现有结构）
  3. 固化约定规则： 
    • id
      命名规则（通常为前缀+路径，例如
      graph:project/<slug>
      ）
    • 状态值：
      stub | curated | generated
    • 标签：简洁、稳定（避免过度创建）
模板和检查清单：请查看
references/templates.md
和
references/quality-bar.md
。

2) Проход по релизам/тегам (release-driven)

2) 基于发布版本的梳理（Release-driven）

Цель: быстро нащупать “важные сущности”, которые реально менялись.
Для каждого релиза:
  1. Найди артефакт релиза: release note / tag / changelog / merge commit.
  2. Вычисли git range (обычно между коммитами релиз-нот или тэгами).
  3. Сними “список сущностей”:
    • задачи/тикеты
    • измененные пути (модули/подсистемы)
    • новые/измененные экранные формы/контракты/DB миграции
  4. Создай узел ревью релиза (type 
    release_review
    ) и список сущностей.
  5. Для каждой DEV-задачи:
    • создай/обнови узел 
      dev_task
    • добавь 
      source_paths
      (минимальный список якорей)
    • свяжи с семантическими узлами (
      project/*
      )
  6. Обнови индексы и backlinks.
目标：快速定位“实际发生变更的重要实体”。
针对每个发布版本：
  1. 获取发布工件：发布说明/标签/变更日志/合并提交记录。
  2. 确定Git范围（通常为两个发布说明或标签之间的提交区间）。
  3. 提取“实体列表”：
    • 任务/工单
    • 变更路径（模块/子系统）
    • 新增/修改的界面/契约/数据库迁移
  4. 创建发布评审节点（类型为
    release_review
    ）并附上实体列表。
  5. 针对每个DEV任务：
    • 创建/更新
      dev_task
      类型的节点
    • 添加
      source_paths
      （最小化锚点列表）
    • 关联语义层节点（
      project/*
      ）
  6. 更新索引和反向链接。

3) Проход по сущностям (entity-driven)

3) 基于实体的梳理（Entity-driven）

Цель: закрыть белые пятна “по всем ключевым сущностям”, а не только по тем, что попали в релизы.
Важно: “сущности” должны быть универсальными. В WMS это могут быть 
экраны/RF-процедуры
, а в вебсайте 
страницы/API
, в CRM 
объекты/воронки
, в шине данных 
топики/схемы/коннекторы
.
Алгоритм:
  1. Выдели 5-12 категорий сущностей, которые реально важны для проекта.
  2. Для каждой категории собери каталог (index/hub) и дальше добирай узлы по одному.
  3. Для каждой сущности обеспечь “кросс-связность”: UI/операции/данные/интеграции/конфиги.
Рекомендованные категории (выбирай релевантные, не все):
  1. Поверхности взаимодействия (entrypoints):
    • Web/UI: страницы, роуты, ключевые компоненты, формы.
    • API: endpoints, controllers/handlers, публичные контракты.
    • CLI/Jobs: команды, cron/quartz, воркеры, фоновые задачи.
    • Events/Streams: топики, события, consumers/producers.
  2. Операции/команды/сценарии (actions):
    • “что система делает”: use-cases, сервисные методы, команды, workflow-степы.
  3. Данные и контракты (data/contracts):
    • DB таблицы/модели, миграции, схемы сообщений, DTO, OpenAPI/AsyncAPI, JSON schema.
  4. Интеграции (integrations):
    • внешние системы, протоколы (HTTP/JMS/Kafka/SFTP), ретраи, таймауты, idempotency.
  5. Конфиги и флаги (config/feature flags):
    • runtime настройки, feature flags, параметры окружений, секреты (только “где берется”, не значения).
  6. Безопасность и доступ (security):
    • authn/authz, роли/права, SSO, аудит.
  7. Надежность и эксплуатация (ops):
    • метрики/логи/трейсинг, алерты, SLO, деградации, recovery-процессы.
Главное правило: не пытайся “описать всё вручную”. Делай:
  • каталоги + хабы (семейства/модули/домены);
  • атомарные узлы с evidence;
  • связи между категориями (например: страница -> API -> сервис -> таблицы -> события).
目标：覆盖所有关键实体的“空白区域”，而不仅仅是发布版本中涉及的实体。
重要提示：“实体”需具备通用性。在仓储管理系统（WMS）中，实体可能是“界面/RF流程”；在网站中可能是“页面/API”；在客户关系管理系统（CRM）中可能是“对象/漏斗”；在数据流管道中可能是“主题/模式/连接器”。
步骤：
  1. 筛选出5-12个对项目至关重要的实体类别。
  2. 为每个类别创建目录（索引/枢纽），然后逐个补充节点。
  3. 确保每个实体具备“交叉关联性”：UI/操作/数据/集成/配置。
推荐的实体类别（选择相关类别，无需全部使用）：
  1. 交互入口（Entrypoints）：
    • Web/UI：页面、路由、核心组件、表单。
    • API：端点、控制器/处理器、公开契约。
    • CLI/任务：命令、定时任务、工作器、后台任务。
    • 事件/流：主题、事件、消费者/生产者。
  2. 操作/命令/场景（Actions）：
    • “系统功能”：用例、服务方法、命令、工作流步骤。
  3. 数据与契约（Data/Contracts）：
    • 数据库表/模型、迁移、消息模式、数据传输对象（DTO）、OpenAPI/AsyncAPI、JSON Schema。
  4. 集成（Integrations）：
    • 外部系统、协议（HTTP/JMS/Kafka/SFTP）、重试机制、超时设置、幂等性。
  5. 配置与功能开关（Config/Feature Flags）：
    • 运行时配置、功能开关、环境参数、机密信息（仅标注“来源位置”，不记录具体值）。
  6. 安全与权限（Security）：
    • 认证/授权、角色/权限、单点登录（SSO）、审计。
  7. 可靠性与运维（Ops）：
    • 指标/日志/链路追踪、告警、服务水平目标（SLO）、性能降级、恢复流程。
核心规则：不要试图“手动描述所有内容”。应采用：
  • 目录+枢纽（家族/模块/领域）；
  • 带证据的原子化节点；
  • 跨类别关联（例如：页面 → API → 服务 → 表 → 事件）。

4) Поддержка по мере изменений (incremental maintenance)

4) 随变更持续维护（Incremental Maintenance）

На каждый новый коммит в 
main
:
  1. Определи затронутые сущности (по diff/путям/ключевым словам).
  2. Обнови соответствующие узлы, не расширяя лишний контекст:
    • добавь 1-3 предложения “что изменилось”
    • добавь ссылки на контракт/код/DB
    • обнови backlinks/индексы
  3. Прогони быстрые проверки:
    • дубликаты 
      id
    • отсутствие frontmatter
    • битые ссылки между узлами
    • orphan nodes (узлы без входящих ссылок внутри 
      docs/graph
      )
    • сломанные относительные ссылки (если есть время)
Для базовой проверки можно использовать 
scripts/graph_memory_lint.py
.
Пример:
bash
python3 scripts/graph_memory_lint.py --root docs/graph
Опционально можно отключать части проверок:
bash
python3 scripts/graph_memory_lint.py --root docs/graph --no-check-links
python3 scripts/graph_memory_lint.py --root docs/graph --no-check-orphans
针对
main
分支的每个新提交：
  1. 根据Diff/路径/关键词确定受影响的实体。
  2. 更新对应节点，避免添加无关内容：
    • 添加1-3句话说明“变更内容”
    • 添加契约/代码/数据库的链接
    • 更新反向链接/索引
  3. 执行快速检查： 
    • id
      重复
    • 缺少前置元数据
    • 节点间的无效链接
    • 孤立节点（
      docs/graph
      目录内无入站链接的节点）
    • 无效相对链接（若时间允许）
基础检查可使用
scripts/graph_memory_lint.py
脚本。
示例：
bash
python3 scripts/graph_memory_lint.py --root docs/graph
可选：可关闭部分检查项：
bash
python3 scripts/graph_memory_lint.py --root docs/graph --no-check-links
python3 scripts/graph_memory_lint.py --root docs/graph --no-check-orphans

Ресурсы в skill

技能资源

  • references/templates.md
    : тонкие шаблоны узлов.
  • references/quality-bar.md
    : качество и “красные флаги”.
  • scripts/graph_memory_lint.py
    : быстрый линтер (frontmatter + дубликаты 
    id
    ).
Appropriate for: Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
Not every skill requires all three types of resources.
  • references/templates.md
    ：轻量节点模板。
  • references/quality-bar.md
    ：质量标准与“红色预警项”。
  • scripts/graph_memory_lint.py
    ：快速检查工具（前置元数据 + 
    id
    重复检查）。
适用场景： 模板、样板代码、文档模板、图片、图标、字体，或任何需要复制并用于最终输出的文件。
并非所有技能都需要上述三类资源。