truthmark 1.2.1 → 1.2.3

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 +80 -44
  2. package/README.es.md +81 -45
  3. package/README.md +104 -43
  4. package/README.ru.md +80 -44
  5. package/README.zh.md +80 -44
  6. package/dist/main.js +599 -305
  7. package/dist/main.js.map +1 -1
  8. package/package.json +1 -1
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
+ 这之所以重要，是因为工作流跟着分支一起存在。仓库一旦初始化，规则、路由和已安装的工作流载体就会随仓库一起移动，协作和交接也就不再过度依赖某个人的本地配置。
11
23
 
12
- AI 编码现在上手很容易，治理却很昂贵。一旦代理能快速写代码，仓库事实就会成为控制面。
13
- 这种失效模式很常见：需求留在聊天里，架构决策反复重做，代理改到了错误的区域，分支继承了审查者无法可靠检查的上下文。代码也许推进得很快，但仓库会变得越来越难以信任。
14
- Truthmark 改变的是工作模型：
24
+ 对于已经知道代理能生成代码的团队，Truthmark 解决的是下一个问题：当 AI 辅助开发规模化时，怎样让仓库本身继续保持清晰、可审查、可治理。
15
25
 
16
- - 分支内事实随分支一起流转，而不是藏在私有工具存储里。
17
- - Git 让这些事实可以被审查、对比，并在团队内共享。
18
- - 文档跟着代码走，而不是悄悄变成虚构。
19
- - 路由明确保存在 `docs/truthmark/areas.md` 和委托的子路由文件中，让代理知道哪些文档负责哪些代码。
20
- - 当前有效的产品和架构决策保存在它们所治理的规范文档中，而不是带时间戳的规划日志里。
21
- - 本地优先的工作流不需要守护进程、数据库、远程服务或 MCP 依赖。
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
+ ## 为什么团队会采用它
51
+
52
+ Truthmark 不是为了让代理显得更聪明，而是为了让 AI 辅助的仓库变更更值得信任。
53
+
54
+ - 代码变更后的自动 Truth Sync，把文档维护从团队习惯变成工作流保护。
55
+ - 按分支生效的事实会跟着代码一起走，所以审查者可以在普通 Git diff 里检查当前事实。
56
+ - 仓库原生的工作流载体让推广更轻、交接更稳，不再只依赖个人本地配置。
57
+ - `docs/truthmark/areas.md` 和委托的子路由文件里的显式路由，为代理提供更清晰的所有权边界和更安全的写入路径。
58
+ - 本地优先的运行方式避免了守护进程、数据库、远程服务或 MCP 依赖。
22
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,33 +130,29 @@ 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
135
+ docs/templates/feature-doc.md
98
136
  docs/features/README.md
99
137
  docs/features/repository/README.md
100
138
  docs/features/repository/overview.md
101
139
  AGENTS.md
102
140
  CLAUDE.md
103
- .codex/skills/truthmark-structure/SKILL.md
104
- .codex/skills/truthmark-sync/SKILL.md
105
- .codex/skills/truthmark-realize/SKILL.md
106
- .codex/skills/truthmark-check/SKILL.md
107
- .opencode/skills/truthmark-structure/SKILL.md
108
- .opencode/skills/truthmark-sync/SKILL.md
109
- .opencode/skills/truthmark-realize/SKILL.md
110
- .opencode/skills/truthmark-check/SKILL.md
141
+ GEMINI.md
111
142
  ```
112
143
 
113
- 如果你在 `.truthmark/config.yml` 中启用更多平台，Truthmark 会在下一次 `init` 时刷新对应的受管载体。
144
+ 支持的平台是 `codex`、`opencode`、`claude-code`、`github-copilot` 和 `gemini-cli`。默认配置包含全部平台；请先从 `.truthmark/config.yml` 中移除不使用的平台，再重新运行 `truthmark init`。
114
145
  默认脚手架把功能 `README.md` 作为索引，并把当前行为事实放在有边界的叶子文档中，例如 `docs/features/repository/overview.md`。
115
146
 
116
- 现有仓库通常需要在 `init` 之后做一次清理：当生成的 `repository` 路由过宽、所有权跨越多个产品或服务，或路由文件仍指向占位文档时，运行已安装的 Truth Structure 工作流。Truth Structure 会拆分过宽的路由，创建或修复初始的规范事实文档，并在功能代码工作开始前为 Truth Sync 提供精确目标。Codex 用户可以用 `/truthmark-structure` 或 `$truthmark-structure` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-structure` 调用它。
147
+ 现有仓库通常需要在 `init` 之后做一次清理：当生成的 `repository` 路由过宽、所有权跨越多个产品或服务，或路由文件仍指向占位文档时，运行已安装的 Truth Structure 工作流。Truth Structure 会拆分过宽的路由，创建或修复初始的规范事实文档，并在功能代码工作开始前为 Truth Sync 提供精确目标。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-structure` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-structure` 调用它。
117
148
 
118
149
  ## 它如何运行
119
150
 
120
- Truthmark 不规定应该由哪个子代理运行 Truth Sync。由实际执行的代理和宿主环境决定是委托执行，还是内联运行工作流。
121
- 多数用户不需要直接调用 Truth Sync。正常路径是：
151
+ Truthmark 最强的地方是默认路径，而不是一堆手动命令。由实际执行的代理和宿主环境决定是委托执行，还是内联运行已安装的工作流。
152
+
153
+ 当行为已经实现但规范事实文档缺失或质量较弱时，使用 Truth Document。代理会读取实现、测试、路由和现有文档，只写事实文档和路由，不能修改功能代码。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-document` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-document` 调用它。
154
+
155
+ 多数用户不需要直接调用 Truth Sync。关键在于，只要功能代码发生变化，Truth Sync 就会充当自动收尾保护。正常路径是：
122
156
 
123
157
  ```text
124
158
  代理修改功能代码
@@ -129,7 +163,7 @@ Truthmark 不规定应该由哪个子代理运行 Truth Sync。由实际执行
129
163
  ```
130
164
 
131
165
  Truth Sync 是 code-first：代码在前，事实文档跟随，且 Truth Sync 不能重写功能代码。它的主要职责是在功能代码发生变化时，作为收尾阶段的自动安全检查。直接调用主要用于排查问题、交接前提前同步，或有意运行这套工作流。
132
- Codex 用户可以用 `/truthmark-sync` 或 `$truthmark-sync` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-sync` 调用它。
166
+ Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-sync` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-sync` 调用它。
133
167
  当产品或架构决策从文档开始时，使用这个流程：
134
168
 
135
169
  ```text
@@ -142,33 +176,35 @@ Codex 用户可以用 `/truthmark-sync` 或 `$truthmark-sync` 调用它。OpenCo
142
176
  ```
143
177
 
144
178
  Truth Realize 是手动、文档优先的流程：事实文档在前，代码跟随，代理不能编辑它正在实现的事实文档。
145
- Codex 用户可以用 `/truthmark-realize` 或 `$truthmark-realize` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-realize` 调用它。
179
+ Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-realize` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-realize` 调用它。
146
180
 
147
181
  ## 它会安装什么
148
182
 
149
- Truthmark 把持久化的工作流载体保持得很小：
183
+ Truthmark 把持久化的工作流载体保持得很小，而且是仓库原生的。运行 `truthmark init` 之后，仓库本身就携带路由、规则和已安装的工作流载体，因此团队不再只依赖某个人的本地配置。
150
184
 
151
185
  - `.truthmark/config.yml`，用于机器可读配置
152
- - `TRUTHMARK.md`，用于分支内工作流契约
186
+ - `.truthmark/config.yml`，用于已提交的层级契约
153
187
  - `docs/truthmark/areas.md`，用于根路由索引
154
188
  - `docs/truthmark/areas/**/*.md`，用于委托的子路由文件
155
- - 面向已配置平台的受管说明块，例如 `AGENTS.md`、`CLAUDE.md`、Cursor 规则、Copilot 指令和 `GEMINI.md`
156
- - 面向 Truth Structure、Truth Sync、Truth Realize 和 Truth Check 的 Codex 技能与仓库本地技能
189
+ - `docs/templates/feature-doc.md`，用于生成工作流采用的可编辑功能文档标准
190
+ - 面向已配置平台的受管说明块，例如 `AGENTS.md`、`CLAUDE.md`、Copilot 指令和 `GEMINI.md`
191
+ - 面向 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令
157
192
 
158
193
  安装后的工作流载体就是运行时：
159
194
 
160
195
  - Truth Structure 创建或修复区域路由和起始事实文档。
196
+ - Truth Document 为已实现行为创建或修复事实文档。
161
197
  - Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
162
198
  - Truth Realize 更新代码，使其符合事实文档。
163
199
  - Truth Check 审计仓库事实的健康状况。
164
200
 
165
- 功能 `README.md` 是索引。Truth Sync 预期读取并更新用于描述当前行为的有边界叶子文档。
201
+ 功能 `README.md` 是索引。Truth Sync 预期读取并更新用于描述当前行为的有边界叶子文档。生成的工作流载体会保留仓库规则的权威性，同时把实现代码和规范事实文档当作当前行为的证据。
166
202
 
167
203
  生成的载体由 Truthmark 管理，包含版本标记，并可通过 `truthmark init` 刷新。
168
204
 
169
205
  ## 命令
170
206
 
171
- Truthmark V1 有意保持 CLI 很小。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物。
207
+ Truthmark V1 有意保持 CLI 很小，因为持续运行的工作流应该活在已安装的代理载体里，而不是一长串日常手动命令里。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物。
172
208
 
173
209
  ```bash
174
210
  truthmark config
@@ -181,7 +217,7 @@ truthmark check --json
181
217
  `config` 只写入 `.truthmark/config.yml`，除非使用 `--stdout`。
182
218
  `init` 需要 `.truthmark/config.yml`，然后安装或刷新本地工作流文件。
183
219
  `check` 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。
184
- Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
220
+ Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
185
221
 
186
222
  ## 它为什么存在
187
223
 
@@ -199,14 +235,14 @@ Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代
199
235
 
200
236
  ## 项目状态
201
237
 
202
- Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体。
238
+ Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体，用来把 AI 工作流规则变成仓库基础设施。
203
239
  V1 目前提供：
204
240
 
205
241
  - `truthmark config`
206
242
  - `truthmark init`
207
243
  - `truthmark check`
208
244
  - 受管的 `AGENTS.md` 工作流说明
209
- - 为已配置代理宿主生成的 Truth Structure、Truth Sync、Truth Realize 和 Truth Check 技能载体
245
+ - 为已配置代理宿主生成的 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 技能载体
210
246
  - 分支范围元数据
211
247
  - 配置、权限边界、路由、决策结构、frontmatter、链接和多语言覆盖率诊断
212
248