truthmark 2.3.0 → 2.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +119 -157
- package/dist/main.js +198 -44
- package/dist/main.js.map +1 -1
- package/docs/README.md +45 -33
- package/docs/assets/truthmark-workflow-mobile.svg +118 -0
- package/docs/assets/truthmark-workflow.svg +182 -0
- package/docs/readmes/README.ar.md +125 -151
- package/docs/readmes/README.de.md +127 -153
- package/docs/readmes/README.el.md +127 -153
- package/docs/readmes/README.es.md +125 -151
- package/docs/readmes/README.fr.md +125 -151
- package/docs/readmes/README.id.md +126 -152
- package/docs/readmes/README.it.md +125 -151
- package/docs/readmes/README.ja.md +126 -152
- package/docs/readmes/README.ko.md +127 -153
- package/docs/readmes/README.pl.md +125 -151
- package/docs/readmes/README.pt.md +126 -152
- package/docs/readmes/README.ru.md +124 -150
- package/docs/readmes/README.tr.md +125 -151
- package/docs/readmes/README.vi.md +126 -152
- package/docs/readmes/README.zh.md +128 -154
- package/package.json +3 -1
|
@@ -2,219 +2,193 @@
|
|
|
2
2
|
|
|
3
3
|
**Ваши агенты пишут код. Truthmark поддерживает понятную людям документацию, которую можно проверять в Git.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Truthmark устанавливает нативные для Git рабочие процессы, с помощью которых AI-агенты разработки создают новую продуктовую и инженерную документацию на основе существующего кода и тестов, актуализируют её после каждого изменения кода и предоставляют вам обычные Markdown-диффы для проверки.
|
|
6
6
|
|
|
7
|
-
](https://www.npmjs.com/package/truthmark)
|
|
8
|
+
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
|
9
|
+
[](../../LICENSE)
|
|
10
|
+
[](../../package.json)
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
[Начать работу](#быстрый-старт-создайте-свой-первый-truth-документ) · [Сайт](https://merlinhu1.github.io/truthmark/) · [Руководство пользователя](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
|
10
13
|
|
|
11
|
-
|
|
14
|
+
<details>
|
|
15
|
+
<summary>Читайте этот README на 16 языках</summary>
|
|
12
16
|
|
|
13
|
-
|
|
14
|
-
cd /path/to/your-repo
|
|
15
|
-
npm install -g truthmark
|
|
16
|
-
truthmark init
|
|
17
|
-
truthmark check
|
|
18
|
-
git diff
|
|
19
|
-
```
|
|
17
|
+
[🇺🇸 English](../../README.md) | [🇨🇳 简体中文](README.zh.md) | [🇯🇵 日本語](README.ja.md) | [🇰🇷 한국어](README.ko.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇪🇸 Español](README.es.md) | [🇧🇷 Português](README.pt.md) | [🇷🇺 Русский](README.ru.md) | [🇸🇦 العربية](README.ar.md) | [🇮🇹 Italiano](README.it.md) | [🇵🇱 Polski](README.pl.md) | [🇹🇷 Türkçe](README.tr.md) | [🇻🇳 Tiếng Việt](README.vi.md) | [🇮🇩 Bahasa Indonesia](README.id.md) | [🇬🇷 Ελληνικά](README.el.md)
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
</details>
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
## Создайте первые документы. Поддерживайте их достоверность.
|
|
24
22
|
|
|
25
|
-
|
|
26
|
-
truthmark init --platform codex --platform cursor
|
|
27
|
-
truthmark init --json
|
|
28
|
-
```
|
|
23
|
+
Большинство инструментов документирования останавливаются после генерации. Truthmark предоставляет агентам полный жизненный цикл документации прямо в вашем репозитории:
|
|
29
24
|
|
|
30
|
-
|
|
25
|
+
- **Создавайте новую документацию на основе работающего ПО.** Truth Document анализирует код и тесты, а затем создаёт ограниченную по области продуктовую или инженерную документацию.
|
|
26
|
+
- **Автоматически поддерживайте соответствие документации.** Truth Sync запускается при передаче работы агентом после функциональных изменений кода и обновляет достоверные сведения репозитория до завершения задачи.
|
|
27
|
+
- **Превращайте документацию обратно в код.** Truth Realize реализует утверждённые truth-документы, сохраняя чистый подход от документации к коду.
|
|
28
|
+
- **Восстанавливайте владение по мере роста кодовой базы.** Truth Structure создаёт ограниченные маршруты и начальные документы для новых или перегруженных областей.
|
|
29
|
+
- **Проверяйте всё в Git.** Код, решения, контракты, архитектура, эксплуатация и поведение перемещаются вместе с веткой.
|
|
31
30
|
|
|
32
|
-
|
|
31
|
+
Никаких размещённых в облаке баз знаний. Никакой закрытой памяти агентов. Никакой документации, запертой в истории чатов.
|
|
33
32
|
|
|
34
|
-
|
|
35
|
-
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
|
36
|
-
```
|
|
33
|
+
## Быстрый старт: создайте свой первый truth-документ
|
|
37
34
|
|
|
38
|
-
|
|
35
|
+
**Требования:** Node.js 24 или новее, Git-репозиторий и поддерживаемый AI-хост разработки для агентских рабочих процессов.
|
|
39
36
|
|
|
40
|
-
|
|
37
|
+
Выполните следующие команды в репозитории, которым должен управлять Truthmark:
|
|
41
38
|
|
|
42
|
-
|
|
39
|
+
```bash
|
|
40
|
+
cd /path/to/your-repo
|
|
41
|
+
npm install -g truthmark
|
|
42
|
+
truthmark init
|
|
43
|
+
```
|
|
43
44
|
|
|
44
|
-
|
|
45
|
+
`truthmark init` позволяет выбрать Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor или нейтральную к хосту настройку интерфейса командной строки.
|
|
45
46
|
|
|
46
|
-
|
|
47
|
-
* Архитектурная документация быстро устаревает.
|
|
48
|
-
* Продуктовые решения исчезают после передачи работы.
|
|
49
|
-
* Ревьюерам кода приходится изучать сырые diff кода без понимания «почему».
|
|
50
|
-
* Каждая новая AI-сессия вынуждена заново обнаруживать truth репозитория.
|
|
47
|
+
Теперь попросите настроенного агента задокументировать одно реальное поведение:
|
|
51
48
|
|
|
52
|
-
|
|
49
|
+
```text
|
|
50
|
+
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
|
51
|
+
```
|
|
53
52
|
|
|
54
|
-
|
|
53
|
+
Truth Document создаёт новый ограниченный по области truth-документ, если его ещё нет, обновляет существующий документ-владелец, если он есть, и при необходимости обновляет маршрутизацию. Функциональный код при этом не изменяется.
|
|
55
54
|
|
|
56
|
-
|
|
55
|
+
Проверьте результат:
|
|
57
56
|
|
|
58
|
-
|
|
57
|
+
```bash
|
|
58
|
+
truthmark check
|
|
59
|
+
git status --short --untracked-files=all
|
|
60
|
+
git diff
|
|
61
|
+
```
|
|
59
62
|
|
|
60
|
-
|
|
63
|
+
Теперь у вас должны появиться:
|
|
61
64
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
65
|
+
```text
|
|
66
|
+
docs/truthmark/engineering/behaviors/session-timeout.md
|
|
67
|
+
docs/truthmark/routes/areas/authentication.md
|
|
68
|
+
```
|
|
66
69
|
|
|
67
|
-
|
|
70
|
+
Точные пути определяются структурой владения вашего репозитория. Новые файлы отображаются в `git status`, а изменения отслеживаемых файлов — в `git diff`.
|
|
68
71
|
|
|
69
|
-
|
|
72
|
+
Способ запуска зависит от хоста. OpenCode использует `/skill truthmark-document`, Antigravity — `@truthmark-document`, а другие поддерживаемые хосты используют свои нативные интерфейсы навыков или slash-команд. Точные команды приведены в [таблице платформ](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms).
|
|
70
73
|
|
|
71
|
-
|
|
72
|
-
2. 🧪 **Тест:** выполняются релевантные тесты.
|
|
73
|
-
3. 🔍 **Проверка:** Truthmark проверяет сопоставленную документацию как часть установленного завершающего ревью.
|
|
74
|
-
4. 📝 **Документирование:** агент обновляет docs, когда truth репозитория изменился.
|
|
75
|
-
5. 👀 **Ревью:** человек проверяет *diff кода* + *diff truth*.
|
|
74
|
+
Для скриптов и непрерывной интеграции передавайте выбранные платформы явно:
|
|
76
75
|
|
|
77
|
-
|
|
76
|
+
```bash
|
|
77
|
+
truthmark init --platform codex --platform cursor
|
|
78
|
+
truthmark init --json
|
|
79
|
+
```
|
|
78
80
|
|
|
79
|
-
|
|
81
|
+
Выберите `none` в интерактивном режиме или выполните `truthmark init --clear-platforms`, чтобы репозиторий оставался нейтральным к хосту. Платформы агентов можно добавить позже, повторно запустив `truthmark init`.
|
|
80
82
|
|
|
81
|
-
|
|
83
|
+
Для диагностики актуальности относительно ветки передайте базовую ссылку Git:
|
|
82
84
|
|
|
83
|
-
|
|
85
|
+
```bash
|
|
86
|
+
truthmark check --base <base-ref>
|
|
87
|
+
```
|
|
84
88
|
|
|
85
|
-
|
|
86
|
-
* `truthmark check` - проверяет truth репозитория из терминала.
|
|
89
|
+
## Как работает Truthmark
|
|
87
90
|
|
|
88
|
-
|
|
91
|
+
<picture>
|
|
92
|
+
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
|
93
|
+
<img src="../assets/truthmark-workflow.svg" alt="Как работает Truthmark" width="1440">
|
|
94
|
+
</picture>
|
|
89
95
|
|
|
90
|
-
Truthmark устанавливает
|
|
96
|
+
Интерфейс командной строки Truthmark устанавливает и проверяет контракт репозитория. Ваш агент разработки анализирует доказательства и работает с документацией через установленные нативные для хоста рабочие процессы.
|
|
91
97
|
|
|
92
|
-
|
|
98
|
+
Обычное изменение кода проходит по простому циклу:
|
|
93
99
|
|
|
94
|
-
1.
|
|
95
|
-
2.
|
|
96
|
-
3.
|
|
100
|
+
1. Агент изменяет функциональный код.
|
|
101
|
+
2. Запускаются соответствующие тесты.
|
|
102
|
+
3. Truth Sync проверяет связанную документацию.
|
|
103
|
+
4. Если достоверные сведения репозитория изменились, агент создаёт или обновляет документацию и маршрутизацию.
|
|
104
|
+
5. Вы вместе проверяете дифф кода и дифф достоверной документации.
|
|
97
105
|
|
|
98
|
-
|
|
106
|
+
## Рабочие процессы
|
|
99
107
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
108
|
+
| Рабочий процесс | Когда использовать | Результат |
|
|
109
|
+
| -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
110
|
+
| **Truth Document** | Существующему коду нужна документация | Создаёт или обновляет продуктовую и инженерную документацию, основанную на доказательствах |
|
|
111
|
+
| **Truth Sync** | Изменился функциональный код | До передачи работы синхронизирует связанную документацию и маршрутизацию |
|
|
112
|
+
| **Truth Structure** | Новой области нужен владелец или существующая документация стала слишком широкой | Создаёт ограниченные маршруты и каркасы начальных документов |
|
|
113
|
+
| **Truth Realize** | Утверждённый truth-документ должен стать работающим ПО | Обновляет функциональный код на основе документации |
|
|
114
|
+
| **Truth Check** | Достоверность репозитория нужно проверить | Сообщает о проблемах маршрутизации, владения, доказательств и документации |
|
|
115
|
+
| **Truthmark Portal** | Команде нужен удобный для просмотра сайт документации | Создаёт версионируемое статическое HTML-представление на основе truth-документов Markdown |
|
|
103
116
|
|
|
104
|
-
|
|
105
|
-
Truth Structure — не повседневная команда; она исправляет routing или ownership только тогда, когда это блокирует работу.
|
|
117
|
+
Truthmark устанавливает эти рабочие процессы как нативные поверхности репозитория для Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor.
|
|
106
118
|
|
|
107
119
|
## Что вы получаете
|
|
108
120
|
|
|
109
|
-
|
|
110
|
-
| --- | --- |
|
|
111
|
-
| Git-native truth | Хранит truth репозитория в закоммиченных Markdown и конфигурации. |
|
|
112
|
-
| Документация в пределах ветки | Truth движется с веткой, а не живет в приватной сессии. |
|
|
113
|
-
| CLI для людей | Дает мейнтейнерам команды настройки, обновления, валидации и инспекции. |
|
|
114
|
-
| Установленные инструкции агента | Говорит coding-агентам, когда документировать, тестировать, синхронизировать truth, аудитировать или останавливаться для ревью. |
|
|
115
|
-
| Явная маршрутизация | Сопоставляет области кода с каноническими truth-docs. |
|
|
116
|
-
| Проверяемая передача | Создает обычные Git diff как для кода, так и для truth-docs. |
|
|
117
|
-
| Local-first работа | Не требует hosted-сервиса, daemon, базы данных или MCP-сервера. |
|
|
118
|
-
| Более безопасные границы записи | Разделяет code-first, doc-first, read-only и doc-only workflows. |
|
|
119
|
-
| Валидация | Сообщает о проблемах routing, authority, frontmatter, links, generated-surface, branch-scope, freshness и coverage. |
|
|
120
|
-
| Опциональный Portal | Генерирует закоммиченный статический HTML-сайт презентации из Markdown truth-docs, когда он явно включен и запрошен. |
|
|
121
|
-
|
|
122
|
-
## Визуальный обзор
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
**Возможности:** что устанавливает Truthmark и как агенты используют локальные инструкции репозитория.
|
|
121
|
+
### Документация, основанная на реальности
|
|
127
122
|
|
|
128
|
-
|
|
123
|
+
Truthmark умеет создавать документацию о возможностях продукта, поведении реализации, программных интерфейсах приложений, архитектуре, рабочих процессах, эксплуатации и тестах. Код и тесты дают доказательства, а ограниченные по области документы Markdown сохраняют результат.
|
|
129
124
|
|
|
130
|
-
|
|
125
|
+
### Документация, которая переживает следующее изменение
|
|
131
126
|
|
|
132
|
-
|
|
127
|
+
Маршруты связывают области кода с канонической документацией. Когда агенты меняют поведение, Truth Sync знает, где должны находиться соответствующие достоверные сведения, и сохраняет результат удобным для проверки.
|
|
133
128
|
|
|
134
|
-
|
|
129
|
+
### Продуктовая и инженерная истина в отдельных потоках
|
|
135
130
|
|
|
136
|
-
|
|
131
|
+
Продуктовая истина фиксирует обещания пользователям, границы, решения и критерии приёмки. Инженерная истина фиксирует текущее поведение, контракты, архитектуру, рабочие процессы, эксплуатацию и поведение тестов.
|
|
137
132
|
|
|
138
|
-
|
|
133
|
+
### Нативная для Git совместная работа
|
|
139
134
|
|
|
140
|
-
|
|
135
|
+
Всё важное находится в версионируемых файлах репозитория. Истина следует за веткой, работает с обычными pull request и остаётся видимой каждому сопровождающему и агенту разработки.
|
|
141
136
|
|
|
142
|
-
|
|
137
|
+
### Локальная работа прежде всего
|
|
143
138
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
Truthmark помогает командам отвечать на это с помощью закоммиченных файлов, явной маршрутизации и проверяемых diff.
|
|
147
|
-
|
|
148
|
-
Он полезен, когда вам нужны:
|
|
149
|
-
|
|
150
|
-
- меньший дрейф документации
|
|
151
|
-
- лучшая передача работы
|
|
152
|
-
- branch-specific продуктовая truth
|
|
153
|
-
- долговечная архитектурная и API-документация
|
|
154
|
-
- явное владение между docs и кодом
|
|
155
|
-
- более безопасные границы записи для агентов
|
|
156
|
-
- проверяемая документация вместо скрытой memory
|
|
157
|
-
- инструкции для агентов, которые продолжают работать из закоммиченных файлов репозитория
|
|
139
|
+
Truthmark не нужны размещённый сервис, фоновый процесс, база данных, векторное хранилище или сервер Model Context Protocol. Репозиторий содержит собственный рабочий процесс документирования.
|
|
158
140
|
|
|
159
141
|
## Где уместен Truthmark
|
|
160
142
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
|
166
|
-
|
|
|
167
|
-
|
|
|
168
|
-
|
|
|
169
|
-
| Plan-first работа над функцией | Spec workflow |
|
|
170
|
-
| Branch-scoped truth, которая перемещается вместе с кодом | Truthmark |
|
|
171
|
-
| Проверка корректности поведения | Tests and review |
|
|
172
|
-
| Ревью изменений документации, выполненных с AI | Truthmark плюс Git review |
|
|
173
|
-
|
|
174
|
-
Область Truthmark намеренно узкая:
|
|
143
|
+
| Потребность | Лучшее решение |
|
|
144
|
+
| ---------------------------------------------------------------- | ------------------------------ |
|
|
145
|
+
| Более качественный результат одной сессии агента | Улучшенный промпт |
|
|
146
|
+
| Непрерывность на личном уровне или уровне сессии | Инструмент памяти |
|
|
147
|
+
| Разработка функций, начинающаяся с плана | Рабочий процесс спецификаций |
|
|
148
|
+
| Документация в рамках ветки, которая перемещается вместе с кодом | **Truthmark** |
|
|
149
|
+
| Корректность поведения | Тесты и проверка кода |
|
|
150
|
+
| Проверяемая документация, созданная с помощью ИИ | **Truthmark + проверка в Git** |
|
|
175
151
|
|
|
176
|
-
|
|
177
|
-
make repository truth explicit
|
|
178
|
-
route it to code
|
|
179
|
-
установить вокруг нее инструкции для агентов
|
|
180
|
-
keep the result reviewable in Git
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
## Подробнее
|
|
152
|
+
Truthmark создан для сопровождающих и инженерных команд, которые уже используют AI-агентов разработки и хотят, чтобы репозиторий продолжал говорить правду так же быстро, как меняется код.
|
|
184
153
|
|
|
185
|
-
|
|
154
|
+
## Поддерживаемые хосты и командная строка
|
|
186
155
|
|
|
187
|
-
|
|
156
|
+
Поддерживаемые хосты агентов:
|
|
188
157
|
|
|
189
|
-
|
|
158
|
+
- Codex
|
|
159
|
+
- Claude Code
|
|
160
|
+
- GitHub Copilot
|
|
161
|
+
- OpenCode
|
|
162
|
+
- Antigravity
|
|
163
|
+
- Cursor
|
|
190
164
|
|
|
191
|
-
|
|
165
|
+
<details>
|
|
166
|
+
<summary>Справочник командной строки</summary>
|
|
192
167
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
168
|
+
| Команда | Назначение |
|
|
169
|
+
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
170
|
+
| `truthmark init` | Создаёт или обновляет конфигурацию, маршрутизацию, шаблоны и рабочие процессы выбранных хостов |
|
|
171
|
+
| `truthmark check [--base <ref>]` | Проверяет достоверность репозитория и при необходимости запускает диагностику актуальности ветки |
|
|
172
|
+
| `truthmark index --json` | Показывает производные метаданные репозитория и маршрутизации |
|
|
173
|
+
| `truthmark impact --base <ref> --json` | Сопоставляет изменённые файлы с документацией, владельцами и ближайшими тестами |
|
|
174
|
+
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Показывает применимость и цели рабочего процесса |
|
|
175
|
+
| `truthmark validate ...` | Проверяет отчёты рабочих процессов и разрешения на запись |
|
|
176
|
+
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Предварительно показывает или удаляет созданные поверхности хостов, сохраняя авторскую truth-документацию |
|
|
197
177
|
|
|
198
|
-
|
|
178
|
+
Структурированный вывод JSON доступен во всём интерфейсе командной строки для скриптов и непрерывной интеграции.
|
|
199
179
|
|
|
200
|
-
|
|
201
|
-
- [Индекс документации](../README.md)
|
|
202
|
-
- [Обзор архитектуры](../truthmark/engineering/architecture/overview.md)
|
|
203
|
-
- [Контракты API и CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
|
204
|
-
- [Руководство по поддержанию repository truth](../standards/maintaining-repository-truth.md)
|
|
180
|
+
</details>
|
|
205
181
|
|
|
206
|
-
|
|
182
|
+
## Дополнительные материалы
|
|
207
183
|
|
|
208
|
-
|
|
184
|
+
- [Руководство пользователя Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
|
185
|
+
- [Индекс документации](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
|
186
|
+
- [Обзор архитектуры](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
|
187
|
+
- [Контракты конфигурации, маршрутизации и команд](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
|
188
|
+
- [Участие в разработке](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
|
209
189
|
|
|
210
|
-
Truthmark
|
|
211
|
-
|
|
212
|
-
Это не hosted-сервис, MCP-сервер, векторная база данных, скрытый слой memory, продукт для принудительного CI-контроля или автономный движок переписывания кода. Он помогает truth репозитория оставаться видимой; он не заменяет tests, code review или человеческое суждение.
|
|
190
|
+
**Установите Truthmark, выберите хост разработки и уже сегодня превратите реальное поведение в документацию.**
|
|
213
191
|
|
|
214
192
|
## Лицензия
|
|
215
193
|
|
|
216
194
|
MIT. См. [LICENSE](../../LICENSE).
|
|
217
|
-
|
|
218
|
-
## Безопасное удаление
|
|
219
|
-
|
|
220
|
-
Используйте `truthmark uninstall --dry-run` для проверки точно сгенерированных host-поверхностей, затем `truthmark uninstall --apply` для их удаления. Сформированные truth, конфигурация, шаблоны, вывод Portal, файлы Gemini и несвязанные пользовательские файлы сохраняются; глобальную установку npm удаляйте отдельно через менеджер пакетов.
|