truthmark 1.2.2 → 1.3.0

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.
Files changed (8) hide show
  1. package/README.de.md +155 -55
  2. package/README.es.md +149 -49
  3. package/README.md +125 -43
  4. package/README.ru.md +148 -48
  5. package/README.zh.md +146 -46
  6. package/dist/main.js +2974 -863
  7. package/dist/main.js.map +1 -1
  8. package/package.json +2 -2
package/README.zh.md CHANGED
@@ -1,31 +1,68 @@
1
- # Truthmark 是 AI 软件开发的事实层。
1
+ # Truthmark
2
+
3
+ **Truthmark 为 AI 软件开发安装仓库事实工作流。**
2
4
 
3
5
  [English](README.md) | [Deutsch](README.de.md) | 中文 | [Español](README.es.md) | [Русский](README.ru.md)
4
6
 
5
- AI 编码代理已经很会写代码了。它们仍然不擅长从过时文档、零散聊天和短暂的工具记忆中，可靠还原产品意图、架构边界和仓库归属。
6
- Truthmark 通过把分支内的仓库事实变成代理运行时的一等载体来解决这个问题。它把一个 Git 原生、按分支生效的事实层直接安装到仓库里，为代理明确路由和工作流边界，并让这些事实随真正交付的代码一起移动。
7
- 这不是更好的提示词工程，而是在真实代码库中更可治理地使用 AI 的方式：少一些重复决策，少一些陈旧文档，交接更清楚，AI 编码会话也会留下可审查的工程记录，而不是消失在提示历史或不透明的工具状态里。
8
- 它面向这样的团队：你们已经知道代理能生成代码，现在需要仓库本身继续保持清晰、可审查、可治理。
7
+ <img src="docs/assets/truthmark-banner.png" alt="Truthmark 横幅" width="100%" />
9
8
 
10
- ## Truthmark 解决什么问题
9
+ AI 编码代理已经能很快写代码了。真正昂贵的是让仓库事实和实际变更保持一致。
10
+
11
+ Truthmark 在这个流程里加入了一个收尾阶段的工作流保护。正常路径很简单：
12
+
13
+ - 代理修改功能代码
14
+ - 运行相关测试
15
+ - 代理结束前，已安装的 Truth Sync 工作流更新已映射的事实文档
16
+ - 如果产生了事实文档 diff，就审查它
17
+
18
+ 大多数工具要求团队养成一种习惯。Truthmark 把这个习惯变成仓库工作流基础设施。
19
+
20
+ Truthmark 把 AI 工作流变成仓库基础设施，而不是个人工具配置。它把一个 Git 原生、按分支生效的事实层安装到仓库里，为代理提供明确的路由和有边界的工作流载体，并让这些事实继续以 Git diff 的形式可审查，而不是散落在提示历史、陈旧文档或私有工具状态里。
21
+
22
+ 这之所以重要，是因为工作流跟着分支一起存在。仓库一旦初始化，规则、路由和已安装的工作流载体就会随仓库一起移动，协作和交接也就不再过度依赖某个人的本地配置。
23
+
24
+ 对于已经知道代理能生成代码的团队，Truthmark 解决的是下一个问题：当 AI 辅助开发规模化时，怎样让仓库本身继续保持清晰、可审查、可治理。
25
+
26
+ ## 可视化概览
27
+
28
+ <table>
29
+ <tr>
30
+ <td align="center" width="50%">
31
+ <img src="docs/assets/truthmark-features.png" alt="Truthmark 功能" width="100%" />
32
+ <br><strong>功能</strong><br>
33
+ Truthmark 安装了什么，以及工作流载体如何拆分。
34
+ </td>
35
+ <td align="center" width="50%">
36
+ <img src="docs/assets/truthmark-position.png" alt="Truthmark 定位" width="100%" />
37
+ <br><strong>定位</strong><br>
38
+ Truthmark 相对提示词、记忆和规格工作流所处的位置。
39
+ </td>
40
+ </tr>
41
+ <tr>
42
+ <td align="center" colspan="2">
43
+ <img src="docs/assets/truthmark-syncflow.png" alt="Truthmark 同步流程" width="100%" />
44
+ <br><strong>同步流程</strong><br>
45
+ Truth Sync 如何在交接前收束普通代码变更。
46
+ </td>
47
+ </tr>
48
+ </table>
49
+
50
+ ## 为什么团队会采用它
11
51
 
12
- AI 编码现在上手很容易，治理却很昂贵。一旦代理能快速写代码，仓库事实就会成为控制面。
13
- 这种失效模式很常见：需求留在聊天里，架构决策反复重做，代理改到了错误的区域，分支继承了审查者无法可靠检查的上下文。代码也许推进得很快，但仓库会变得越来越难以信任。
14
- Truthmark 改变的是工作模型：
52
+ Truthmark 不是为了让代理显得更聪明，而是为了让 AI 辅助的仓库变更更值得信任。
15
53
 
16
- - 分支内事实随分支一起流转，而不是藏在私有工具存储里。
17
- - Git 让这些事实可以被审查、对比，并在团队内共享。
18
- - 文档跟着代码走，而不是悄悄变成虚构。
19
- - 路由明确保存在 `docs/truthmark/areas.md` 和委托的子路由文件中，让代理知道哪些文档负责哪些代码。
20
- - 当前有效的产品和架构决策保存在它们所治理的规范文档中，而不是带时间戳的规划日志里。
21
- - 本地优先的工作流不需要守护进程、数据库、远程服务或 MCP 依赖。
22
- - 这个模型适用于 JavaScript、TypeScript、Go、Python、C# 和 Java 代码库。
54
+ - 代码变更后的已安装 Truth Sync 工作流，把文档维护从团队习惯变成工作流保护。
55
+ - 按分支生效的事实会跟着代码一起走，所以审查者可以在普通 Git diff 里检查当前事实。
56
+ - 仓库原生的工作流载体让推广更轻、交接更稳，不再只依赖个人本地配置。
57
+ - `docs/truthmark/areas.md` 和委托的子路由文件里的显式路由，为代理提供更清晰的所有权边界和更安全的写入路径。
58
+ - 本地优先的运行方式避免了守护进程、数据库、远程服务或 MCP 依赖。
59
+ - 路由模型与语言无关，并为常见的 JavaScript、TypeScript、Go、Python、C# 和 Java 代码表面提供覆盖率诊断。
23
60
 
24
- 对技术负责人来说，它的价值是没有表演成分的治理：测试、代码审查和所有权仍然承担真正的工作；Truthmark 让代理上下文变得持久、可检查，并且限定在当前分支内。
61
+ 对技术负责人来说，它的价值是没有额外基础设施负担的治理：测试、代码审查和所有权仍然承担真正的工作；Truthmark 让代理上下文变得持久、可检查，并且限定在当前分支内。
25
62
 
26
63
  ## Truthmark 适合放在哪里
27
64
 
28
- Truthmark 并不想取代所有其他 AI 工作流工具。它位于工具栈中的一个特定层级：
65
+ Truthmark 不是一套通用 AI 生产力套件。它占据的是工具栈里的一个特定层级：随实现保持一致、按分支生效、可审查的仓库事实。
29
66
 
30
67
  | 如果你需要 | 最合适的选择 |
31
68
  | -------------------------------------------- | ------------------------------ |
@@ -38,9 +75,9 @@ Truthmark 并不想取代所有其他 AI 工作流工具。它位于工具栈中
38
75
 
39
76
  ## 目录
40
77
 
78
+ - [为什么团队会采用它](#为什么团队会采用它)
41
79
  - [Truthmark 解决什么问题](#truthmark-解决什么问题)
42
80
  - [Truthmark 适合放在哪里](#truthmark-适合放在哪里)
43
- - [工作流载体](#工作流载体)
44
81
  - [快速开始](#快速开始)
45
82
  - [它如何运行](#它如何运行)
46
83
  - [它会安装什么](#它会安装什么)
@@ -51,12 +88,13 @@ Truthmark 并不想取代所有其他 AI 工作流工具。它位于工具栈中
51
88
  - [非目标](#非目标)
52
89
  - [许可证](#许可证)
53
90
 
54
- ## 工作流载体
91
+ ## Truthmark 解决什么问题
55
92
 
56
93
  Truthmark 把仓库事实变成代理可见的显式工作流载体：
57
94
 
58
- - `TRUTHMARK.md` 定义分支内工作流契约。
95
+ - `.truthmark/config.yml` 定义已提交的层级契约。
59
96
  - `docs/truthmark/areas.md` 和委托的子路由文件把代码区域映射到负责它们的文档。
97
+ - Truth Document 在无需修改代码时，为已实现行为生成或修复规范事实文档。
60
98
  - Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
61
99
  - Truth Realize 为文档优先的变更提供有边界的代码更新路径。
62
100
  - `truthmark check` 验证最终形成的事实产物。
@@ -92,88 +130,145 @@ node /path/to/truthmark/dist/main.js check
92
130
 
93
131
  ```text
94
132
  .truthmark/config.yml
95
- TRUTHMARK.md
96
133
  docs/truthmark/areas.md
97
134
  docs/truthmark/areas/repository.md
98
- docs/features/README.md
99
- docs/features/repository/README.md
100
- docs/features/repository/overview.md
135
+ docs/templates/behavior-doc.md
136
+ docs/truth/README.md
137
+ docs/truth/repository/README.md
138
+ docs/truth/repository/overview.md
101
139
  AGENTS.md
102
140
  CLAUDE.md
141
+ GEMINI.md
103
142
  ```
104
143
 
105
144
  支持的平台是 `codex`、`opencode`、`claude-code`、`github-copilot` 和 `gemini-cli`。默认配置包含全部平台；请先从 `.truthmark/config.yml` 中移除不使用的平台，再重新运行 `truthmark init`。
106
- 默认脚手架把功能 `README.md` 作为索引，并把当前行为事实放在有边界的叶子文档中，例如 `docs/features/repository/overview.md`。
145
+ 默认脚手架把 truth `README.md` 作为索引，并把当前行为事实放在有边界的叶子文档中，例如 `docs/truth/repository/overview.md`。
107
146
 
108
147
  现有仓库通常需要在 `init` 之后做一次清理：当生成的 `repository` 路由过宽、所有权跨越多个产品或服务，或路由文件仍指向占位文档时，运行已安装的 Truth Structure 工作流。Truth Structure 会拆分过宽的路由，创建或修复初始的规范事实文档，并在功能代码工作开始前为 Truth Sync 提供精确目标。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-structure` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-structure` 调用它。
109
148
 
110
149
  ## 它如何运行
111
150
 
112
- Truthmark 不规定应该由哪个子代理运行 Truth Sync。由实际执行的代理和宿主环境决定是委托执行，还是内联运行工作流。
113
- 多数用户不需要直接调用 Truth Sync。正常路径是：
151
+ Truthmark 最强的地方是默认路径，而不是一堆手动命令。由实际执行的代理和宿主环境决定是委托执行，还是内联运行已安装的工作流。
152
+
153
+ ### 已实现但无文档的行为
154
+
155
+ 当实现已经存在，但规范事实文档缺失或较弱时，使用这个流程：
156
+
157
+ ```text
158
+ 用户识别一个已实现的行为或 API 端点
159
+ 用户显式调用 Truth Document
160
+ 代理读取实现、测试、路由和现有文档
161
+ 代理只写 truth docs 和路由
162
+ 审查 truth-doc diff
163
+ ```
164
+
165
+ Truth Document 是手动、implementation-first 的流程：代码作为证据，事实文档被创建或修复，且不能修改功能代码。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-document` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-document` 调用它。
166
+
167
+ ```text
168
+ /truthmark-document 在 docs/truth/authentication 下记录已实现的会话超时行为
169
+ ```
170
+
171
+ ### 常规代码变更
172
+
173
+ 多数用户不需要直接调用 Truth Sync。关键在于，只要功能代码发生变化，已安装的代理工作流就会把 Truth Sync 当作收尾保护。正常路径是：
114
174
 
115
175
  ```text
116
176
  代理修改功能代码
117
177
  运行相关测试
118
- 代理结束前触发 Truth Sync
119
- 如果生成了事实文档 diff，就审查它
178
+ 已安装的 Truth Sync 工作流在代理结束前运行
179
+ 如果生成了 truth-doc diff，就审查它
120
180
  提交或交接工作
121
181
  ```
122
182
 
123
- Truth Sync 是 code-first：代码在前，事实文档跟随，且 Truth Sync 不能重写功能代码。它的主要职责是在功能代码发生变化时，作为收尾阶段的自动安全检查。直接调用主要用于排查问题、交接前提前同步，或有意运行这套工作流。
183
+ Truth Sync 是 code-first：代码在前，事实文档跟随，且 Truth Sync 不能重写功能代码。它的主要职责是在功能代码发生变化时，通过已安装的代理工作流充当收尾保护。直接调用主要用于排查问题、交接前提前同步，或有意运行这套工作流。
184
+
124
185
  Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-sync` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-sync` 调用它。
186
+
187
+ ```text
188
+ /truthmark-sync 现在同步仓库 truth，然后再交接
189
+ ```
190
+
191
+ ### 文档优先变更
192
+
125
193
  当产品或架构决策从文档开始时，使用这个流程：
126
194
 
127
195
  ```text
128
- 用户编辑事实文档
196
+ 用户编辑 truth docs
129
197
  用户显式调用 Truth Realize
130
- 代理读取事实文档和相关代码
198
+ 代理读取 truth docs 和相关代码
131
199
  代理只更新代码
132
200
  运行相关测试
133
201
  提交或交接工作
134
202
  ```
135
203
 
136
204
  Truth Realize 是手动、文档优先的流程：事实文档在前，代码跟随，代理不能编辑它正在实现的事实文档。
205
+
137
206
  Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-realize` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-realize` 调用它。
138
207
 
208
+ ```text
209
+ /truthmark-realize 将 docs/truth/authentication/session-timeout.md 实现为代码
210
+ ```
211
+
139
212
  ## 它会安装什么
140
213
 
141
- Truthmark 把持久化的工作流载体保持得很小：
214
+ Truthmark 把持久化的工作流载体保持得很小，而且是仓库原生的。运行 `truthmark init` 之后，仓库本身就携带路由、规则和已安装的工作流载体，因此团队不再只依赖某个人的本地配置。
142
215
 
143
- - `.truthmark/config.yml`，用于机器可读配置
144
- - `TRUTHMARK.md`，用于分支内工作流契约
216
+ - `.truthmark/config.yml`，用于机器可读的已提交层级契约
145
217
  - `docs/truthmark/areas.md`，用于根路由索引
146
218
  - `docs/truthmark/areas/**/*.md`，用于委托的子路由文件
219
+ - `docs/templates/behavior-doc.md` 以及 `docs/templates/` 下其他按类型划分的模板，用作生成工作流采用的可编辑 truth doc 标准
147
220
  - 面向已配置平台的受管说明块，例如 `AGENTS.md`、`CLAUDE.md`、Copilot 指令和 `GEMINI.md`
148
- - 面向 Truth Structure、Truth Sync、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令
221
+ - 面向 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令
149
222
 
150
223
  安装后的工作流载体就是运行时：
151
224
 
152
225
  - Truth Structure 创建或修复区域路由和起始事实文档。
226
+ - Truth Document 为已实现行为创建或修复事实文档。
153
227
  - Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
154
228
  - Truth Realize 更新代码，使其符合事实文档。
155
229
  - Truth Check 审计仓库事实的健康状况。
156
230
 
157
- 功能 `README.md` 是索引。Truth Sync 预期读取并更新用于描述当前行为的有边界叶子文档。
231
+ 功能 `README.md` 是索引。Truth Sync 预期读取并更新用于描述当前行为的有边界叶子文档。生成的工作流载体会保留仓库规则的权威性，同时把实现代码和规范事实文档当作当前行为的证据。
158
232
 
159
233
  生成的载体由 Truthmark 管理，包含版本标记，并可通过 `truthmark init` 刷新。
160
234
 
161
235
  ## 命令
162
236
 
163
- Truthmark V1 有意保持 CLI 很小。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物。
237
+ Truthmark V1 有意保持 CLI 很小，因为持续运行的工作流应该活在已安装的代理载体里，而不是一长串日常手动命令里。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物，而仓库情报命令会在有本地工具时生成派生审查产物。
164
238
 
165
239
  ```bash
166
240
  truthmark config
167
241
  truthmark init
168
242
  truthmark check
243
+ truthmark index
244
+ truthmark impact --base main
245
+ truthmark context --workflow truth-sync --base main
169
246
  truthmark config --json
170
247
  truthmark check --json
248
+ truthmark index --json
249
+ truthmark impact --base main --json
250
+ truthmark context --workflow truth-sync --base main --json
171
251
  ```
172
252
 
173
253
  `config` 只写入 `.truthmark/config.yml`，除非使用 `--stdout`。
254
+
174
255
  `init` 需要 `.truthmark/config.yml`，然后安装或刷新本地工作流文件。
256
+
175
257
  `check` 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。
176
- Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
258
+
259
+ `index` 为当前 checkout 构建 RepoIndex 和 RouteMap JSON。
260
+
261
+ `impact --base <ref>` 会把变更文件映射到已路由的 truth docs、所属路由、附近测试和 public symbols。
262
+
263
+ `context --workflow <workflow> [--base <ref>]` 会为 Truth Sync、Truth Document 或 Truth Realize 生成一个受限的 ContextPack。`--format markdown` 会把它渲染成可读文本。
264
+
265
+ Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
266
+
267
+ 它们通过已配置的代理宿主表面运行，例如 Codex/Claude/Copilot 的 `/truthmark-*`、OpenCode 的 `/skill truthmark-*`，或者 Gemini 的 `/truthmark:*`。
268
+
269
+ ```text
270
+ /truthmark-check 在 review 前审计路由和 truth 覆盖
271
+ ```
177
272
 
178
273
  ## 它为什么存在
179
274
 
@@ -191,16 +286,21 @@ Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代
191
286
 
192
287
  ## 项目状态
193
288
 
194
- Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体。
289
+ Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体，用来把 AI 工作流规则变成仓库基础设施。
290
+
195
291
  V1 目前提供：
196
292
 
197
293
  - `truthmark config`
198
294
  - `truthmark init`
199
295
  - `truthmark check`
296
+ - `truthmark index`
297
+ - `truthmark impact`
298
+ - `truthmark context`
200
299
  - 受管的 `AGENTS.md` 工作流说明
201
- - 为已配置代理宿主生成的 Truth Structure、Truth Sync、Truth Realize 和 Truth Check 技能载体
300
+ - 为已配置代理宿主生成的 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 技能载体
202
301
  - 分支范围元数据
203
302
  - 配置、权限边界、路由、决策结构、frontmatter、链接和多语言覆盖率诊断
303
+ - RepoIndex、RouteMap、ImpactSet 和 ContextPack 派生产物，可在 CLI 可用时加快本地检查
204
304
 
205
305
  ## 文档
206
306
 
@@ -208,10 +308,10 @@ V1 目前提供：
208
308
 
209
309
  - [文档索引](docs/README.md)
210
310
  - [架构概览](docs/architecture/overview.md)
211
- - [API 和 CLI 契约](docs/features/contracts.md)
212
- - [Init 和脚手架行为](docs/features/init-and-scaffold.md)
213
- - [Check 诊断](docs/features/check-diagnostics.md)
214
- - [已安装工作流](docs/features/installed-workflows.md)
311
+ - [API 和 CLI 契约](docs/truth/contracts.md)
312
+ - [Init 和脚手架行为](docs/truth/init-and-scaffold.md)
313
+ - [Check 诊断](docs/truth/check-diagnostics.md)
314
+ - [已安装工作流](docs/truth/workflows/overview.md)
215
315
  - [仓库事实维护指南](docs/standards/maintaining-repository-truth.md)
216
316
 
217
317
  当前行为应放在上面的规范文档树中。