mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 |
0f048bf1de | ||
|
MerlinH
|
5050eb0fb7 | ||
|
MerlinH
|
b1655b6e4a |
@@ -1,231 +1,194 @@
|
||||
# Truthmark
|
||||
|
||||
**Your agents write code. Truthmark maintains human-facing, Git-reviewable documentation.**
|
||||
**Your agents write code. Truthmark maintains the human-facing, Git-reviewable documentation.**
|
||||
|
||||
Truthmark installs Git-native workflows that let AI coding agents create new product and engineering documentation from existing code and tests, keep it current after every code change, and hand you ordinary Markdown diffs for review.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](LICENSE)
|
||||
[](package.json)
|
||||
|
||||
[Website](https://merlinhu1.github.io/truthmark/) | [GitHub](https://github.com/merlinhu1/truthmark) | [User Guide](docs/user-guide.md)
|
||||
[Get started](#quick-start-create-your-first-truth-document) · [Website](https://merlinhu1.github.io/truthmark/) · [User Guide](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Read this README in 16 languages</summary>
|
||||
|
||||
[🇺🇸 English](README.md) | [🇨🇳 简体中文](docs/readmes/README.zh.md) | [🇯🇵 日本語](docs/readmes/README.ja.md) | [🇰🇷 한국어](docs/readmes/README.ko.md) | [🇩🇪 Deutsch](docs/readmes/README.de.md) | [🇫🇷 Français](docs/readmes/README.fr.md) | [🇪🇸 Español](docs/readmes/README.es.md) | [🇧🇷 Português](docs/readmes/README.pt.md) | [🇷🇺 Русский](docs/readmes/README.ru.md) | [🇸🇦 العربية](docs/readmes/README.ar.md) | [🇮🇹 Italiano](docs/readmes/README.it.md) | [🇵🇱 Polski](docs/readmes/README.pl.md) | [🇹🇷 Türkçe](docs/readmes/README.tr.md) | [🇻🇳 Tiếng Việt](docs/readmes/README.vi.md) | [🇮🇩 Bahasa Indonesia](docs/readmes/README.id.md) | [🇬🇷 Ελληνικά](docs/readmes/README.el.md)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Quick Start: running locally in five minutes
|
||||
## Create the first docs. Keep them true.
|
||||
|
||||
Run this inside the Git repository you want Truthmark to manage:
|
||||
Most documentation tools stop after generation. Truthmark gives agents a complete documentation lifecycle inside your repository:
|
||||
|
||||
- **Create new docs from working software.** Truth Document reads code and tests, then creates bounded product or engineering documentation.
|
||||
- **Keep docs aligned automatically.** Truth Sync runs at agent handoff after functional code changes and updates repository truth before the work is finished.
|
||||
- **Turn docs back into code.** Truth Realize implements approved truth docs while preserving a clean doc-first workflow.
|
||||
- **Repair ownership as the codebase grows.** Truth Structure creates bounded routes and starter docs for new or overloaded areas.
|
||||
- **Review everything in Git.** Code, decisions, contracts, architecture, operations, and behavior travel together with the branch.
|
||||
|
||||
No hosted knowledge base. No private agent memory. No documentation trapped in chat history.
|
||||
|
||||
## Quick Start: create your first truth document
|
||||
|
||||
**Requirements:** Node.js 24 or newer, a Git repository, and a supported AI coding host for agent workflows.
|
||||
|
||||
Run this inside the repository you want Truthmark to manage:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` lets you select Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor, or a host-neutral command-line interface setup.
|
||||
|
||||
Now ask your configured agent to document one real behavior:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document creates a new bounded truth doc when one does not exist, updates an existing owner when it does, and updates routing when needed. It does not change functional code.
|
||||
|
||||
Review the result:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
In an interactive terminal, `truthmark init` shows a numbered multi-select for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor. Select zero or more hosts; choose `none` for a host-neutral, CLI-only repository.
|
||||
You should now have:
|
||||
|
||||
For scripts and CI, repeat `--platform` to replace the selected host set without prompting:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
The exact paths follow your repository’s ownership structure. New files appear in `git status`; changes to tracked files appear in `git diff`.
|
||||
|
||||
Invocation varies by host. OpenCode uses `/skill truthmark-document`, Antigravity uses `@truthmark-document`, and other supported hosts use their native skill or slash-command surface. See the [platform table](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) for exact commands.
|
||||
|
||||
For scripts and continuous integration, pass the selected platforms explicitly:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
`--json` never prompts. On a first noninteractive run with no `--platform`, initialization stays host-neutral; later reruns retain the platforms already saved in `.truthmark/config.yml`.
|
||||
Choose `none` interactively or run `truthmark init --clear-platforms` for a host-neutral repository. You can add agent platforms later by rerunning `truthmark init`.
|
||||
|
||||
Now try the most common adoption path: document one existing behavior from code and tests. In your AI coding host, ask the installed workflow:
|
||||
For branch-relative freshness diagnostics, pass a Git base:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
After that, users should not normally invoke Truth Sync directly. Keep coding through your AI host; the installed repository instructions tell the agent to run relevant tests and perform the Truth Sync review before handoff when functional code changes. You review the resulting code diff plus truth-doc diff.
|
||||
## How Truthmark works
|
||||
|
||||
If you only want CLI validation and do not want host-specific AI workflows yet, select `none` and continue with `truthmark check`; you can rerun `truthmark init` later to select platforms.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="docs/assets/truthmark-workflow-mobile.svg">
|
||||
<img src="docs/assets/truthmark-workflow.svg" alt="How Truthmark works" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 The Problem: The AI Documentation Gap
|
||||
The Truthmark command-line interface installs and validates the repository contract. Your coding agent performs the evidence review and documentation work through the installed host-native workflows.
|
||||
|
||||
AI coding agents are incredible at writing code fast. But this speed creates a dangerous new failure mode: **the repository's story drifts from reality.**
|
||||
A normal code change follows one simple loop:
|
||||
|
||||
* Behavior is lost in ephemeral chat histories.
|
||||
* Architecture documents quickly fall behind.
|
||||
* Product decisions vanish after handoff.
|
||||
* Code reviewers are left examining raw code diffs without understanding the "why."
|
||||
* Every new AI session is forced to rediscover your repository's truth from scratch.
|
||||
1. The agent changes functional code.
|
||||
2. Relevant tests run.
|
||||
3. Truth Sync checks the mapped documentation.
|
||||
4. The agent creates or updates docs and routing when repository truth changed.
|
||||
5. You review the code diff and truth diff together.
|
||||
|
||||
## 🎯 The Solution: Truthmark
|
||||
## Workflows
|
||||
|
||||
**Truthmark** installs a Git-native workflow layer into your repository. It fixes the part of AI development that usually breaks: keeping documentation aligned with code after the first draft.
|
||||
| Workflow | Use it when | Result |
|
||||
| -------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| **Truth Document** | Existing code needs documentation | Creates or updates evidence-backed product and engineering docs |
|
||||
| **Truth Sync** | Functional code changed | Keeps mapped docs and routing aligned before handoff |
|
||||
| **Truth Structure** | A new area needs ownership or existing docs are too broad | Creates bounded routes and skeletal starter docs |
|
||||
| **Truth Realize** | An approved truth doc should become working software | Updates functional code from documentation |
|
||||
| **Truth Check** | Repository truth needs an audit | Reports routing, ownership, evidence, and documentation issues |
|
||||
| **Truthmark Portal** | The team wants a browsable documentation site | Generates a committed static HTML presentation from Markdown truth docs |
|
||||
|
||||
Instead of hoping humans and AI agents remember to update docs, Truthmark makes documentation a systematic, reviewable habit right inside your repo.
|
||||
|
||||
Truthmark is not a one-shot docs generator. It is an ongoing truth-doc curation loop that keeps human-facing docs small, owned, evidence-backed, and reviewable as agents keep changing code.
|
||||
|
||||
### ✨ Why Truthmark is Unique
|
||||
|
||||
Truthmark isn't just another documentation tool. It is deeply integrated into the AI workflow:
|
||||
|
||||
* **🚫 Zero Vendor Lock-in:** No hosted services, no hidden databases, no extra servers to operate.
|
||||
* **🌳 100% Git-Native:** Everything lives in your repository. The truth moves with your branch.
|
||||
* **🤝 Human-owned, agent-followed contract:** Maintainers own the repo contract; agents follow the installed instructions while coding.
|
||||
* **🧭 Ongoing truth curation:** Broad or messy docs are routed toward Structure instead of becoming giant catch-all files.
|
||||
* **✅ Trust Through Verification:** AI work becomes easier to trust because behavior-changing work includes a human-reviewable truth-doc decision or diff.
|
||||
|
||||
## 🔄 How It Works
|
||||
|
||||
When an AI agent modifies your code, the job isn't finished. Truthmark installs a finish-time workflow guard that agents follow before handoff:
|
||||
|
||||
1. 💻 **Code:** Agent modifies functional code.
|
||||
2. 🧪 **Test:** Relevant tests are executed.
|
||||
3. 🔍 **Check:** Truthmark checks mapped documentation as part of the installed finish-time review.
|
||||
4. 📝 **Document:** Docs are updated by the agent when repository truth has changed.
|
||||
5. 👀 **Review:** A human reviews the *code diff* + the *truth diff*.
|
||||
|
||||
## 🛠 How you interact with Truthmark
|
||||
|
||||
Truthmark has one repo-local contract with two ways to use it.
|
||||
|
||||
### Humans install and validate the contract
|
||||
|
||||
Maintainers and CI use the CLI:
|
||||
|
||||
* `truthmark init` - create or refresh configuration, select zero or more platforms, and install routing, truth-doc scaffolds, and selected AI-host instructions.
|
||||
* `truthmark check` - validate the repository truth from the terminal.
|
||||
* `truthmark uninstall --dry-run|--apply` - preview or remove generated host surfaces while preserving authored truth and configuration.
|
||||
|
||||
### Agents follow the contract while coding
|
||||
|
||||
Truthmark installs repo-local instructions for supported AI coding hosts such as Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor.
|
||||
|
||||
The normal loop is simple:
|
||||
|
||||
1. Ask your agent for a code change, or ask it to document existing behavior.
|
||||
2. The installed instructions tell the agent when to test, when to update truth docs, and when to stop for human review.
|
||||
3. You review ordinary Git diffs: code plus any truth-doc changes.
|
||||
|
||||
The user-started agent requests are intentionally few:
|
||||
|
||||
* `/truthmark-document` - document existing implemented behavior from code and tests.
|
||||
* `/truthmark-realize` - implement code from existing truth docs.
|
||||
* `/truthmark-check` - audit repository truth.
|
||||
|
||||
Truth Sync is not the usual way to start work; it is the finish-time review after functional code changes.
|
||||
Truth Structure is not a day-to-day command; it repairs routing or ownership only when that blocks the work.
|
||||
Truthmark installs these workflows as native repository surfaces for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor.
|
||||
|
||||
## What you get
|
||||
|
||||
| Capability | What it does |
|
||||
| --- | --- |
|
||||
| Git-native truth | Keeps repository truth in committed Markdown and config. |
|
||||
| Branch-scoped documentation | Truth moves with the branch instead of living in a private session. |
|
||||
| Human CLI | Gives maintainers setup, refresh, validation, and inspection commands. |
|
||||
| Installed agent guidance | Tells coding agents when to document, test, sync truth, audit, or stop for review. |
|
||||
| Explicit routing | Maps code areas to canonical truth docs. |
|
||||
| Durable truth curation | Keeps docs bounded, evidence-backed, and reviewable instead of letting them grow into catch-all files. |
|
||||
| Reviewable handoffs | Produces ordinary Git diffs for both code and truth docs. |
|
||||
| Local-first operation | Requires no hosted service, daemon, database, or MCP server. |
|
||||
| Safer write boundaries | Separates code-first, doc-first, read-only, and doc-only workflows. |
|
||||
| Validation | Reports routing, authority, frontmatter, link, generated-surface, branch-scope, freshness, and coverage issues. |
|
||||
| Optional Portal | Generates a committed static HTML presentation site from Markdown truth docs when explicitly enabled and requested. |
|
||||
### Documentation that starts from reality
|
||||
|
||||
## Visual overview
|
||||
Truthmark can create documentation for product capabilities, implementation behavior, application programming interfaces, architecture, workflows, operations, and tests. Code and tests provide the evidence; bounded Markdown docs preserve the result.
|
||||
|
||||
|
||||
### Documentation that survives the next change
|
||||
|
||||
**Features:** what Truthmark installs and how agents use repo-local instructions.
|
||||
Routes connect code areas to canonical docs. When agents change behavior, Truth Sync knows where the corresponding truth belongs and keeps the handoff reviewable.
|
||||
|
||||
|
||||
### Product and engineering truth in separate lanes
|
||||
|
||||
**Position:** where Truthmark fits relative to prompts, memory, and spec workflows.
|
||||
Product truth captures user-facing promises, boundaries, decisions, and acceptance criteria. Engineering truth captures current behavior, contracts, architecture, workflows, operations, and test behavior.
|
||||
|
||||
|
||||
### Git-native collaboration
|
||||
|
||||
**Sync flow:** how Truth Sync closes out normal code changes before handoff.
|
||||
Everything important lives in committed repository files. Truth follows the branch, works with ordinary pull requests, and remains visible to every maintainer and coding agent.
|
||||
|
||||
## Why teams adopt it
|
||||
### Local-first operation
|
||||
|
||||
Truthmark is for teams that already know AI agents can generate code.
|
||||
|
||||
The next problem is governance.
|
||||
|
||||
Not governance as ceremony. Governance as a simple question:
|
||||
|
||||
> After this AI-assisted change, does the repository still tell the truth?
|
||||
|
||||
Truthmark helps teams answer that with committed files, explicit routing, and reviewable diffs.
|
||||
|
||||
Most AI tools can draft documentation. Truthmark keeps repository truth curated after the draft, after the next code change, and after the doc starts getting too broad.
|
||||
|
||||
It is useful when you need:
|
||||
|
||||
- less documentation drift
|
||||
- better handoffs
|
||||
- branch-specific product truth
|
||||
- durable architecture and API documentation
|
||||
- explicit ownership between docs and code
|
||||
- safer agent write boundaries
|
||||
- reviewable documentation instead of hidden memory
|
||||
- agent guidance that still works from committed repo files
|
||||
Truthmark needs no hosted service, daemon, database, vector store, or Model Context Protocol server. The repository carries its own documentation workflow.
|
||||
|
||||
## Where Truthmark fits
|
||||
|
||||
Truthmark does not replace prompts, memory, specs, tests, or code review.
|
||||
| Need | Best fit |
|
||||
| -------------------------------------------------- | -------------------------- |
|
||||
| Better output from one agent session | Better prompt |
|
||||
| Personal or session-level continuity | Memory tool |
|
||||
| Plan-first feature work | Specification workflow |
|
||||
| Branch-scoped documentation that travels with code | **Truthmark** |
|
||||
| Behavior correctness | Tests and code review |
|
||||
| Reviewable AI-assisted documentation | **Truthmark + Git review** |
|
||||
|
||||
It gives those workflows a durable place to land in Git.
|
||||
Truthmark is built for maintainers and engineering teams that already use AI coding agents and want the repository to keep telling the truth as fast as the code changes.
|
||||
|
||||
| Need | Better fit |
|
||||
| --- | --- |
|
||||
| Better output from one agent session | Better prompt |
|
||||
| Personal or session-level continuity | Memory tool |
|
||||
| Plan-first feature work | Spec workflow |
|
||||
| Branch-scoped truth that travels with code | Truthmark |
|
||||
| Validating behavior correctness | Tests and review |
|
||||
| Reviewing AI-assisted documentation changes | Truthmark plus Git review |
|
||||
## Supported hosts and command line
|
||||
|
||||
Truthmark’s lane is narrow by design:
|
||||
Supported agent hosts:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
install agent guidance around it
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Go deeper
|
||||
<details>
|
||||
<summary>Command-line reference</summary>
|
||||
|
||||
The README is the storefront: fast context, quick start, and the core mental model.
|
||||
| Command | Purpose |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Create or refresh configuration, routing, templates, and selected host workflows |
|
||||
| `truthmark check [--base <ref>]` | Validate repository truth and optionally run branch-freshness diagnostics |
|
||||
| `truthmark index --json` | Inspect derived repository and routing metadata |
|
||||
| `truthmark impact --base <ref> --json` | Map changed files to docs, owners, and nearby tests |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Inspect workflow applicability and targets |
|
||||
| `truthmark validate ...` | Validate workflow reports and write leases |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Preview or remove generated host surfaces while preserving authored truth |
|
||||
|
||||
The [static website](https://merlinhu1.github.io/truthmark/) is the concise public introduction for GitHub Pages.
|
||||
Structured JSON output is available throughout the command-line interface for scripts and continuous integration.
|
||||
|
||||
For command-by-command usage, surface comparisons, supported platform details, configuration, routing, Portal, and examples, read the [Truthmark User Guide](docs/user-guide.md).
|
||||
</details>
|
||||
|
||||
## Project status
|
||||
## Learn more
|
||||
|
||||
Truthmark 2.3 provides:
|
||||
- [Truthmark User Guide](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Documentation index](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Architecture overview](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Configuration, routing, and command contracts](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Maintaining repository truth](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Contributing](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
- local CLI commands for init, uninstall, check, index, impact, workflow status, and validate
|
||||
- generated repo-local agent instructions for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor
|
||||
- route, authority, frontmatter, link, freshness, generated-surface, branch-scope, and coverage diagnostics
|
||||
- branch-scoped truth docs and derived repository-intelligence artifacts
|
||||
|
||||
## Documentation
|
||||
|
||||
- [User guide](docs/user-guide.md)
|
||||
- [Docs index](docs/README.md)
|
||||
- [Architecture overview](docs/truthmark/engineering/architecture/overview.md)
|
||||
- [API and CLI contracts](docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Repository truth maintenance guide](docs/standards/maintaining-repository-truth.md)
|
||||
|
||||
For local development and contribution commands, see [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## Design boundaries
|
||||
|
||||
Truthmark is intentionally small: local, committed, branch-scoped, and reviewable.
|
||||
|
||||
It is not a hosted service, MCP server, vector database, hidden memory layer, CI enforcement product, or autonomous code rewrite engine. It helps repository truth stay visible; it does not replace tests, code review, or human judgment.
|
||||
**Install Truthmark, select your coding host, and turn one real behavior into documentation today.**
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.5 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.4 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.4 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.4 MiB |
@@ -0,0 +1,118 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="720" height="1600" viewBox="0 0 720 1600" role="img" aria-labelledby="title desc">
|
||||
<title id="title">How Truthmark works</title>
|
||||
<desc id="desc">Truthmark creates documentation from code and tests, keeps documentation current as code changes, and turns approved truth documents back into working code. Every path ends in one reviewable Git diff.</desc>
|
||||
<defs>
|
||||
<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#090D1A"/><stop offset="0.55" stop-color="#10162B"/><stop offset="1" stop-color="#0B1220"/></linearGradient>
|
||||
<radialGradient id="glow" cx="0.2" cy="0.15" r="0.7"><stop offset="0" stop-color="#8B5CF6" stop-opacity="0.24"/><stop offset="1" stop-color="#8B5CF6" stop-opacity="0"/></radialGradient>
|
||||
<linearGradient id="purple" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#A78BFA"/><stop offset="1" stop-color="#7C3AED"/></linearGradient>
|
||||
<linearGradient id="cyan" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#67E8F9"/><stop offset="1" stop-color="#0891B2"/></linearGradient>
|
||||
<linearGradient id="amber" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#FCD34D"/><stop offset="1" stop-color="#D97706"/></linearGradient>
|
||||
<linearGradient id="review" x1="0" y1="0" x2="1" y2="0"><stop offset="0" stop-color="#16A34A"/><stop offset="0.55" stop-color="#22C55E"/><stop offset="1" stop-color="#0D9488"/></linearGradient>
|
||||
<filter id="shadow" x="-20%" y="-20%" width="140%" height="160%"><feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000814" flood-opacity="0.42"/></filter>
|
||||
<pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse"><path d="M32 0H0V32" fill="none" stroke="#94A3B8" stroke-opacity="0.045"/></pattern>
|
||||
<marker id="purpleArrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="#A78BFA"/></marker>
|
||||
<marker id="cyanArrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="#67E8F9"/></marker>
|
||||
<marker id="amberArrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="#FCD34D"/></marker>
|
||||
<style>
|
||||
.ui { font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
|
||||
.brand { font-size: 16px; font-weight: 780; letter-spacing: 2.5px; fill: #C4B5FD; }
|
||||
.headline { font-size: 42px; font-weight: 790; letter-spacing: -0.8px; fill: #F8FAFC; }
|
||||
.subhead { font-size: 20px; font-weight: 460; fill: #94A3B8; }
|
||||
.eyebrow { font-size: 17px; font-weight: 780; letter-spacing: 2px; }
|
||||
.cardTitle { font-size: 29px; font-weight: 770; fill: #F8FAFC; }
|
||||
.label { font-size: 22px; font-weight: 670; fill: #E2E8F0; }
|
||||
.muted { font-size: 17px; font-weight: 490; fill: #94A3B8; }
|
||||
.pill { font-size: 21px; font-weight: 770; fill: #FFFFFF; }
|
||||
.reviewTitle { font-size: 26px; font-weight: 830; fill: #FFFFFF; }
|
||||
.reviewSub { font-size: 17px; font-weight: 560; fill: #DCFCE7; }
|
||||
</style>
|
||||
</defs>
|
||||
|
||||
<rect width="720" height="1600" rx="30" fill="url(#bg)"/>
|
||||
<rect width="720" height="1600" rx="30" fill="url(#grid)"/>
|
||||
<rect width="720" height="1600" rx="30" fill="url(#glow)"/>
|
||||
|
||||
<g class="ui">
|
||||
<g transform="translate(48 42)">
|
||||
<rect width="158" height="36" rx="18" fill="#8B5CF6" fill-opacity="0.16" stroke="#A78BFA" stroke-opacity="0.45"/>
|
||||
<circle cx="20" cy="18" r="5" fill="#A78BFA"/>
|
||||
<text x="37" y="23" class="brand">TRUTHMARK</text>
|
||||
<text x="0" y="82" class="headline">Create. Sync. Realize.</text>
|
||||
<text x="0" y="115" class="subhead">Documentation that moves with your code.</text>
|
||||
</g>
|
||||
|
||||
<!-- Create -->
|
||||
<g transform="translate(48 184)" filter="url(#shadow)">
|
||||
<rect width="624" height="350" rx="26" fill="#141A2F" stroke="#8B5CF6" stroke-opacity="0.52" stroke-width="1.5"/>
|
||||
<rect width="624" height="7" rx="3.5" fill="url(#purple)"/>
|
||||
<g transform="translate(27 27)">
|
||||
<rect width="58" height="58" rx="17" fill="#8B5CF6" fill-opacity="0.15" stroke="#A78BFA" stroke-opacity="0.45"/>
|
||||
<path d="M19 21L11 29L19 37M39 21L47 29L39 37M34 15L24 43" fill="none" stroke="#C4B5FD" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</g>
|
||||
<text x="105" y="49" class="eyebrow" fill="#A78BFA">01 · CREATE</text>
|
||||
<text x="105" y="79" class="cardTitle">Create from code</text>
|
||||
<rect x="28" y="106" width="568" height="62" rx="16" fill="#0C1224" stroke="#334155"/>
|
||||
<text x="52" y="133" class="label">Code + tests</text><text x="52" y="156" class="muted">Evidence from working software</text>
|
||||
<path d="M312 176V197" fill="none" stroke="#A78BFA" stroke-width="2.5" marker-end="url(#purpleArrow)"/>
|
||||
<rect x="186" y="202" width="252" height="58" rx="29" fill="url(#purple)"/>
|
||||
<text x="312" y="238" class="pill" text-anchor="middle">Truth Document</text>
|
||||
<path d="M312 268V289" fill="none" stroke="#A78BFA" stroke-width="2.5" marker-end="url(#purpleArrow)"/>
|
||||
<rect x="28" y="294" width="568" height="42" rx="14" fill="#21153E" stroke="#8B5CF6" stroke-opacity="0.55"/>
|
||||
<text x="52" y="322" class="label">New product + engineering docs</text>
|
||||
</g>
|
||||
|
||||
<!-- Sync -->
|
||||
<g transform="translate(48 558)" filter="url(#shadow)">
|
||||
<rect width="624" height="350" rx="26" fill="#141A2F" stroke="#22D3EE" stroke-opacity="0.52" stroke-width="1.5"/>
|
||||
<rect width="624" height="7" rx="3.5" fill="url(#cyan)"/>
|
||||
<g transform="translate(27 27)">
|
||||
<rect width="58" height="58" rx="17" fill="#06B6D4" fill-opacity="0.14" stroke="#67E8F9" stroke-opacity="0.45"/>
|
||||
<path d="M17 23A15 15 0 0 1 43 20L47 24M42 13L43 20L36 21M42 36A15 15 0 0 1 16 39L12 35M17 46L16 39L23 38" fill="none" stroke="#A5F3FC" stroke-width="3.1" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</g>
|
||||
<text x="105" y="49" class="eyebrow" fill="#67E8F9">02 · SYNC</text>
|
||||
<text x="105" y="79" class="cardTitle">Stay current</text>
|
||||
<rect x="28" y="106" width="568" height="62" rx="16" fill="#0C1224" stroke="#334155"/>
|
||||
<text x="52" y="133" class="label">Agent changes code</text><text x="52" y="156" class="muted">Tests prove the behavior</text>
|
||||
<path d="M312 176V197" fill="none" stroke="#67E8F9" stroke-width="2.5" marker-end="url(#cyanArrow)"/>
|
||||
<rect x="204" y="202" width="216" height="58" rx="29" fill="url(#cyan)"/>
|
||||
<text x="312" y="238" class="pill" text-anchor="middle">Truth Sync</text>
|
||||
<path d="M312 268V289" fill="none" stroke="#67E8F9" stroke-width="2.5" marker-end="url(#cyanArrow)"/>
|
||||
<rect x="28" y="294" width="568" height="42" rx="14" fill="#0B2C36" stroke="#22D3EE" stroke-opacity="0.55"/>
|
||||
<text x="52" y="322" class="label">Docs stay current before handoff</text>
|
||||
</g>
|
||||
|
||||
<!-- Realize -->
|
||||
<g transform="translate(48 932)" filter="url(#shadow)">
|
||||
<rect width="624" height="350" rx="26" fill="#141A2F" stroke="#F59E0B" stroke-opacity="0.52" stroke-width="1.5"/>
|
||||
<rect width="624" height="7" rx="3.5" fill="url(#amber)"/>
|
||||
<g transform="translate(27 27)">
|
||||
<rect width="58" height="58" rx="17" fill="#F59E0B" fill-opacity="0.13" stroke="#FCD34D" stroke-opacity="0.45"/>
|
||||
<path d="M31 12L16 32H28L25 47L42 25H30Z" fill="#FDE68A" stroke="#FCD34D" stroke-width="1.4" stroke-linejoin="round"/>
|
||||
</g>
|
||||
<text x="105" y="49" class="eyebrow" fill="#FCD34D">03 · REALIZE</text>
|
||||
<text x="105" y="79" class="cardTitle">Build from truth</text>
|
||||
<rect x="28" y="106" width="568" height="62" rx="16" fill="#0C1224" stroke="#334155"/>
|
||||
<text x="52" y="133" class="label">Approved truth docs</text><text x="52" y="156" class="muted">The repository contract</text>
|
||||
<path d="M312 176V197" fill="none" stroke="#FCD34D" stroke-width="2.5" marker-end="url(#amberArrow)"/>
|
||||
<rect x="193" y="202" width="238" height="58" rx="29" fill="url(#amber)"/>
|
||||
<text x="312" y="238" class="pill" text-anchor="middle">Truth Realize</text>
|
||||
<path d="M312 268V289" fill="none" stroke="#FCD34D" stroke-width="2.5" marker-end="url(#amberArrow)"/>
|
||||
<rect x="28" y="294" width="568" height="42" rx="14" fill="#33230A" stroke="#F59E0B" stroke-opacity="0.55"/>
|
||||
<text x="52" y="322" class="label">Working code implemented from truth</text>
|
||||
</g>
|
||||
|
||||
<!-- Review -->
|
||||
<path d="M360 1282V1329" stroke="#22C55E" stroke-width="3"/>
|
||||
<g transform="translate(48 1329)" filter="url(#shadow)">
|
||||
<rect width="624" height="190" rx="28" fill="url(#review)"/>
|
||||
<g transform="translate(34 38)" fill="none" stroke="#FFFFFF" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round">
|
||||
<circle cx="10" cy="8" r="6"/><circle cx="10" cy="48" r="6"/><circle cx="52" cy="8" r="6"/><path d="M10 14V42M16 8H34Q46 8 46 22V34Q46 48 30 48H16"/>
|
||||
</g>
|
||||
<text x="113" y="59" class="reviewTitle">ONE REVIEWABLE GIT DIFF</text>
|
||||
<text x="34" y="111" class="reviewSub">Code and documentation move together</text>
|
||||
<text x="34" y="136" class="reviewSub">with the branch.</text>
|
||||
<rect x="500" y="111" width="86" height="45" rx="22.5" fill="#FFFFFF" fill-opacity="0.16" stroke="#FFFFFF" stroke-opacity="0.35"/>
|
||||
<path d="M523 133H562M553 124L562 133L553 142" fill="none" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 9.3 KiB |
@@ -0,0 +1,182 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="820" viewBox="0 0 1440 820" role="img" aria-labelledby="title desc">
|
||||
<title id="title">How Truthmark works</title>
|
||||
<desc id="desc">Truthmark creates documentation from code and tests, keeps documentation current as code changes, and turns approved truth documents back into working code. Every path ends in one reviewable Git diff.</desc>
|
||||
<defs>
|
||||
<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0" stop-color="#090D1A"/>
|
||||
<stop offset="0.55" stop-color="#10162B"/>
|
||||
<stop offset="1" stop-color="#0B1220"/>
|
||||
</linearGradient>
|
||||
<radialGradient id="glowPurple" cx="0.2" cy="0.25" r="0.55">
|
||||
<stop offset="0" stop-color="#8B5CF6" stop-opacity="0.22"/>
|
||||
<stop offset="1" stop-color="#8B5CF6" stop-opacity="0"/>
|
||||
</radialGradient>
|
||||
<radialGradient id="glowCyan" cx="0.75" cy="0.3" r="0.55">
|
||||
<stop offset="0" stop-color="#22D3EE" stop-opacity="0.16"/>
|
||||
<stop offset="1" stop-color="#22D3EE" stop-opacity="0"/>
|
||||
</radialGradient>
|
||||
<linearGradient id="purple" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0" stop-color="#A78BFA"/>
|
||||
<stop offset="1" stop-color="#7C3AED"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="cyan" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0" stop-color="#67E8F9"/>
|
||||
<stop offset="1" stop-color="#0891B2"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="amber" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0" stop-color="#FCD34D"/>
|
||||
<stop offset="1" stop-color="#D97706"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="review" x1="0" y1="0" x2="1" y2="0">
|
||||
<stop offset="0" stop-color="#16A34A"/>
|
||||
<stop offset="0.5" stop-color="#22C55E"/>
|
||||
<stop offset="1" stop-color="#0D9488"/>
|
||||
</linearGradient>
|
||||
<filter id="shadow" x="-20%" y="-20%" width="140%" height="160%">
|
||||
<feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000814" flood-opacity="0.45"/>
|
||||
</filter>
|
||||
<filter id="softGlow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="7" result="blur"/>
|
||||
<feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
|
||||
</filter>
|
||||
<pattern id="grid" width="36" height="36" patternUnits="userSpaceOnUse">
|
||||
<path d="M36 0H0V36" fill="none" stroke="#94A3B8" stroke-opacity="0.045" stroke-width="1"/>
|
||||
</pattern>
|
||||
<marker id="arrowPurple" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10Z" fill="#A78BFA"/></marker>
|
||||
<marker id="arrowCyan" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10Z" fill="#67E8F9"/></marker>
|
||||
<marker id="arrowAmber" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10Z" fill="#FCD34D"/></marker>
|
||||
<style>
|
||||
.ui { font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
|
||||
.eyebrow { font-size: 15px; font-weight: 750; letter-spacing: 2.6px; }
|
||||
.headline { font-size: 42px; font-weight: 780; letter-spacing: -1px; fill: #F8FAFC; }
|
||||
.subhead { font-size: 19px; font-weight: 450; fill: #94A3B8; }
|
||||
.cardTitle { font-size: 30px; font-weight: 760; letter-spacing: -0.45px; fill: #F8FAFC; }
|
||||
.label { font-size: 19px; font-weight: 620; fill: #E2E8F0; }
|
||||
.muted { font-size: 16px; font-weight: 480; fill: #94A3B8; }
|
||||
.pill { font-size: 18px; font-weight: 760; fill: #FFFFFF; }
|
||||
.reviewTitle { font-size: 25px; font-weight: 820; letter-spacing: 0.2px; fill: #FFFFFF; }
|
||||
.reviewSub { font-size: 17px; font-weight: 560; fill: #DCFCE7; }
|
||||
</style>
|
||||
</defs>
|
||||
|
||||
<rect width="1440" height="820" rx="28" fill="url(#bg)"/>
|
||||
<rect width="1440" height="820" rx="28" fill="url(#grid)"/>
|
||||
<rect width="1440" height="820" rx="28" fill="url(#glowPurple)"/>
|
||||
<rect width="1440" height="820" rx="28" fill="url(#glowCyan)"/>
|
||||
|
||||
<g class="ui">
|
||||
<g transform="translate(62 48)">
|
||||
<rect x="0" y="0" width="154" height="34" rx="17" fill="#8B5CF6" fill-opacity="0.16" stroke="#A78BFA" stroke-opacity="0.45"/>
|
||||
<circle cx="20" cy="17" r="5" fill="#A78BFA" filter="url(#softGlow)"/>
|
||||
<text x="36" y="22" class="eyebrow" fill="#C4B5FD">TRUTHMARK</text>
|
||||
<text x="0" y="78" class="headline">Create docs. Keep them true. Build from truth.</text>
|
||||
<text x="0" y="112" class="subhead">A complete documentation lifecycle inside your repository.</text>
|
||||
</g>
|
||||
|
||||
<!-- Create card -->
|
||||
<g transform="translate(60 195)" filter="url(#shadow)">
|
||||
<rect width="400" height="420" rx="26" fill="#141A2F" stroke="#8B5CF6" stroke-opacity="0.5" stroke-width="1.5"/>
|
||||
<rect width="400" height="7" rx="3.5" fill="url(#purple)"/>
|
||||
<g transform="translate(30 31)">
|
||||
<rect width="62" height="62" rx="18" fill="#8B5CF6" fill-opacity="0.15" stroke="#A78BFA" stroke-opacity="0.45"/>
|
||||
<path d="M20 23L12 31L20 39M42 23L50 31L42 39M36 16L26 46" fill="none" stroke="#C4B5FD" stroke-width="3.4" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</g>
|
||||
<text x="112" y="55" class="eyebrow" fill="#A78BFA">01 · CREATE</text>
|
||||
<text x="112" y="84" class="cardTitle">Create from code</text>
|
||||
|
||||
<rect x="30" y="126" width="340" height="63" rx="16" fill="#0C1224" stroke="#334155"/>
|
||||
<text x="54" y="153" class="label">Code + tests</text>
|
||||
<text x="54" y="176" class="muted">Evidence from working software</text>
|
||||
|
||||
<path d="M200 197V225" fill="none" stroke="#A78BFA" stroke-width="2.5" marker-end="url(#arrowPurple)"/>
|
||||
<rect x="84" y="229" width="232" height="58" rx="29" fill="url(#purple)"/>
|
||||
<text x="200" y="265" class="pill" text-anchor="middle">Truth Document</text>
|
||||
<path d="M200 296V324" fill="none" stroke="#A78BFA" stroke-width="2.5" marker-end="url(#arrowPurple)"/>
|
||||
|
||||
<rect x="30" y="328" width="340" height="63" rx="16" fill="#21153E" stroke="#8B5CF6" stroke-opacity="0.55"/>
|
||||
<g transform="translate(49 344)" fill="none" stroke="#C4B5FD" stroke-width="2.2">
|
||||
<rect x="6" y="0" width="24" height="29" rx="3"/><path d="M11 8H25M11 14H25M11 20H21"/>
|
||||
<rect x="0" y="6" width="24" height="29" rx="3" opacity="0.6"/>
|
||||
</g>
|
||||
<text x="101" y="355" class="label">New truth docs</text>
|
||||
<text x="101" y="378" class="muted">Product + engineering</text>
|
||||
</g>
|
||||
|
||||
<!-- Sync card -->
|
||||
<g transform="translate(520 195)" filter="url(#shadow)">
|
||||
<rect width="400" height="420" rx="26" fill="#141A2F" stroke="#22D3EE" stroke-opacity="0.5" stroke-width="1.5"/>
|
||||
<rect width="400" height="7" rx="3.5" fill="url(#cyan)"/>
|
||||
<g transform="translate(30 31)">
|
||||
<rect width="62" height="62" rx="18" fill="#06B6D4" fill-opacity="0.14" stroke="#67E8F9" stroke-opacity="0.45"/>
|
||||
<path d="M18 24A16 16 0 0 1 45 21L49 25M44 14L45 21L38 22M44 38A16 16 0 0 1 17 41L13 37M18 48L17 41L24 40" fill="none" stroke="#A5F3FC" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</g>
|
||||
<text x="112" y="55" class="eyebrow" fill="#67E8F9">02 · SYNC</text>
|
||||
<text x="112" y="84" class="cardTitle">Stay current</text>
|
||||
|
||||
<rect x="30" y="126" width="340" height="63" rx="16" fill="#0C1224" stroke="#334155"/>
|
||||
<text x="54" y="153" class="label">Agent changes code</text>
|
||||
<text x="54" y="176" class="muted">Tests prove the behavior</text>
|
||||
|
||||
<path d="M200 197V225" fill="none" stroke="#67E8F9" stroke-width="2.5" marker-end="url(#arrowCyan)"/>
|
||||
<rect x="101" y="229" width="198" height="58" rx="29" fill="url(#cyan)"/>
|
||||
<text x="200" y="265" class="pill" text-anchor="middle">Truth Sync</text>
|
||||
<path d="M200 296V324" fill="none" stroke="#67E8F9" stroke-width="2.5" marker-end="url(#arrowCyan)"/>
|
||||
|
||||
<rect x="30" y="328" width="340" height="63" rx="16" fill="#0B2C36" stroke="#22D3EE" stroke-opacity="0.55"/>
|
||||
<g transform="translate(49 344)" fill="none" stroke="#A5F3FC" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round">
|
||||
<path d="M2 17L11 26L30 5"/>
|
||||
<rect x="0" y="0" width="35" height="35" rx="8" opacity="0.5"/>
|
||||
</g>
|
||||
<text x="101" y="355" class="label">Docs stay current</text>
|
||||
<text x="101" y="378" class="muted">Before the agent hands off</text>
|
||||
</g>
|
||||
|
||||
<!-- Realize card -->
|
||||
<g transform="translate(980 195)" filter="url(#shadow)">
|
||||
<rect width="400" height="420" rx="26" fill="#141A2F" stroke="#F59E0B" stroke-opacity="0.52" stroke-width="1.5"/>
|
||||
<rect width="400" height="7" rx="3.5" fill="url(#amber)"/>
|
||||
<g transform="translate(30 31)">
|
||||
<rect width="62" height="62" rx="18" fill="#F59E0B" fill-opacity="0.13" stroke="#FCD34D" stroke-opacity="0.45"/>
|
||||
<path d="M34 13L18 34H31L27 50L45 27H32Z" fill="#FDE68A" stroke="#FCD34D" stroke-width="1.5" stroke-linejoin="round"/>
|
||||
</g>
|
||||
<text x="112" y="55" class="eyebrow" fill="#FCD34D">03 · REALIZE</text>
|
||||
<text x="112" y="84" class="cardTitle">Build from truth</text>
|
||||
|
||||
<rect x="30" y="126" width="340" height="63" rx="16" fill="#0C1224" stroke="#334155"/>
|
||||
<text x="54" y="153" class="label">Approved truth docs</text>
|
||||
<text x="54" y="176" class="muted">The repository contract</text>
|
||||
|
||||
<path d="M200 197V225" fill="none" stroke="#FCD34D" stroke-width="2.5" marker-end="url(#arrowAmber)"/>
|
||||
<rect x="91" y="229" width="218" height="58" rx="29" fill="url(#amber)"/>
|
||||
<text x="200" y="265" class="pill" text-anchor="middle">Truth Realize</text>
|
||||
<path d="M200 296V324" fill="none" stroke="#FCD34D" stroke-width="2.5" marker-end="url(#arrowAmber)"/>
|
||||
|
||||
<rect x="30" y="328" width="340" height="63" rx="16" fill="#33230A" stroke="#F59E0B" stroke-opacity="0.55"/>
|
||||
<g transform="translate(49 344)" fill="none" stroke="#FDE68A" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
|
||||
<rect x="0" y="0" width="38" height="35" rx="7"/><path d="M0 9H38M8 21L13 26L8 31M19 29H30"/>
|
||||
</g>
|
||||
<text x="101" y="355" class="label">Working code</text>
|
||||
<text x="101" y="378" class="muted">Implemented from truth</text>
|
||||
</g>
|
||||
|
||||
<!-- Merge lines -->
|
||||
<path d="M260 615V649Q260 666 278 666H630" fill="none" stroke="#8B5CF6" stroke-opacity="0.65" stroke-width="2.3"/>
|
||||
<path d="M720 615V666" fill="none" stroke="#22D3EE" stroke-opacity="0.7" stroke-width="2.3"/>
|
||||
<path d="M1180 615V649Q1180 666 1162 666H810" fill="none" stroke="#F59E0B" stroke-opacity="0.65" stroke-width="2.3"/>
|
||||
|
||||
<!-- Git review bar -->
|
||||
<g transform="translate(236 666)" filter="url(#shadow)">
|
||||
<rect width="968" height="108" rx="28" fill="url(#review)"/>
|
||||
<g transform="translate(35 28)" fill="none" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
|
||||
<circle cx="10" cy="8" r="6"/><circle cx="10" cy="44" r="6"/><circle cx="49" cy="8" r="6"/>
|
||||
<path d="M10 14V38M16 8H29Q43 8 43 22V30Q43 44 29 44H16"/>
|
||||
</g>
|
||||
<text x="111" y="48" class="reviewTitle">ONE REVIEWABLE GIT DIFF</text>
|
||||
<text x="111" y="76" class="reviewSub">Code and documentation move together with the branch.</text>
|
||||
<g transform="translate(815 29)">
|
||||
<rect width="114" height="50" rx="25" fill="#FFFFFF" fill-opacity="0.16" stroke="#FFFFFF" stroke-opacity="0.35"/>
|
||||
<path d="M28 25H78M69 16L78 25L69 34" fill="none" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 11 KiB |
+131
-156
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**وكلاؤك يكتبون الكود. يحافظ Truthmark على توثيق موجّه للبشر وقابل للمراجعة عبر Git.**
|
||||
**وكلاؤك يكتبون الكود. ويحافظ Truthmark على التوثيق الموجّه للبشر والقابل للمراجعة عبر Git.**
|
||||
|
||||
يثبّت Truthmark مسارات عمل أصلية لـ Git تتيح لوكلاء البرمجة بالذكاء الاصطناعي إنشاء توثيق جديد للمنتج والهندسة من الكود والاختبارات الموجودة، والحفاظ على حداثته بعد كل تغيير في الكود، وتسليمك فروق Markdown عادية لمراجعتها.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[ابدأ الآن](#البدء-السريع-أنشئ-أول-وثيقة-حقيقة) · [الموقع](https://merlinhu1.github.io/truthmark/) · [دليل المستخدم](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>اقرأ ملف README هذا بـ 16 لغة</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 البدء السريع: التشغيل محلياً خلال خمس دقائق
|
||||
## أنشئ الوثائق الأولى. وحافظ على صدقها.
|
||||
|
||||
شغّل هذا داخل مستودع Git الذي تريد أن يديره Truthmark:
|
||||
تتوقف معظم أدوات التوثيق بعد التوليد. أما Truthmark فيمنح الوكلاء دورة حياة كاملة للتوثيق داخل مستودعك:
|
||||
|
||||
- **أنشئ توثيقاً جديداً من برمجيات عاملة.** يقرأ Truth Document الكود والاختبارات، ثم ينشئ توثيقاً محدد النطاق للمنتج أو الهندسة.
|
||||
- **حافظ على توافق الوثائق تلقائياً.** يعمل Truth Sync عند تسليم الوكيل بعد تغييرات الكود الوظيفية، ويحدّث حقيقة المستودع قبل اكتمال العمل.
|
||||
- **حوّل الوثائق مجدداً إلى كود.** ينفّذ Truth Realize وثائق الحقيقة المعتمدة مع الحفاظ على مسار عمل نظيف يبدأ بالتوثيق.
|
||||
- **أصلح الملكية مع نمو قاعدة الكود.** ينشئ Truth Structure مسارات محددة النطاق ووثائق أولية للمناطق الجديدة أو المثقلة.
|
||||
- **راجع كل شيء في Git.** ينتقل الكود والقرارات والعقود والمعمارية والعمليات والسلوك معاً ضمن الفرع.
|
||||
|
||||
لا قاعدة معرفة مستضافة. لا ذاكرة خاصة للوكلاء. لا توثيق عالق في سجل المحادثات.
|
||||
|
||||
## البدء السريع: أنشئ أول وثيقة حقيقة
|
||||
|
||||
**المتطلبات:** Node.js 24 أو أحدث، ومستودع Git، ومضيف برمجة بالذكاء الاصطناعي مدعوم لمسارات عمل الوكلاء.
|
||||
|
||||
شغّل ما يلي داخل المستودع الذي تريد أن يديره Truthmark:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
يتيح لك `truthmark init` اختيار Codex أو Claude Code أو GitHub Copilot أو OpenCode أو Antigravity أو Cursor أو إعداد واجهة سطر أوامر محايد تجاه المضيف.
|
||||
|
||||
اطلب الآن من الوكيل الذي أعددته توثيق سلوك حقيقي واحد:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
ينشئ Truth Document وثيقة حقيقة جديدة محددة النطاق عند عدم وجودها، ويحدّث الوثيقة المالكة الموجودة عند وجودها، ويحدّث التوجيه عند الحاجة. ولا يغيّر الكود الوظيفي.
|
||||
|
||||
راجع النتيجة:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
في الطرفية التفاعلية يعرض `truthmark init` قائمة اختيار متعددة مرقمة. اختر صفراً أو أكثر من المنصات، أو أدخل `none` لإعداد محايد تجاه المضيف ويقتصر على CLI.
|
||||
ينبغي أن يصبح لديك الآن:
|
||||
|
||||
في السكربتات وCI كرّر `--platform`؛ ولا يعرض `--json` أي مطالبة تفاعلية أبداً:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
تتبع المسارات الدقيقة بنية الملكية في مستودعك. تظهر الملفات الجديدة في `git status`، وتظهر تغييرات الملفات المتتبعة في `git diff`.
|
||||
|
||||
تختلف طريقة الاستدعاء بحسب المضيف. يستخدم OpenCode الأمر `/skill truthmark-document`، ويستخدم Antigravity الأمر `@truthmark-document`، بينما تستخدم المضيفات الأخرى المدعومة واجهتها الأصلية للمهارات أو أوامر الشرطة المائلة. راجع [جدول المنصات](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) لمعرفة الأوامر الدقيقة.
|
||||
|
||||
بالنسبة إلى السكربتات والتكامل المستمر، مرّر المنصات المختارة صراحةً:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
في أول تشغيل غير تفاعلي من دون `--platform` يبقى الإعداد محايداً تجاه المضيف؛ وتحافظ التشغيلات اللاحقة على الاختيار المحفوظ في `.truthmark/config.yml`.
|
||||
اختر `none` تفاعلياً أو شغّل `truthmark init --clear-platforms` للحصول على مستودع محايد تجاه المضيف. ويمكنك إضافة منصات الوكلاء لاحقاً بإعادة تشغيل `truthmark init`.
|
||||
|
||||
جرّب الآن مسار الاعتماد الأكثر شيوعاً: توثيق سلوك موجود من الكود والاختبارات. في مضيف البرمجة بالذكاء الاصطناعي، اطلب من سير العمل المثبّت:
|
||||
للحصول على تشخيصات الحداثة نسبةً إلى الفرع، مرّر مرجع Git أساسياً:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
بعد ذلك، لا ينبغي للمستخدمين عادةً استدعاء Truth Sync مباشرة. واصل البرمجة عبر مضيف الذكاء الاصطناعي؛ فتعليمات المستودع المثبّتة تطلب من الوكيل تشغيل الاختبارات ذات الصلة وتنفيذ مراجعة Truth Sync قبل التسليم عندما تتغير الشيفرة الوظيفية. أنت تراجع فرق الكود الناتج مع فرق توثيق الحقيقة.
|
||||
## كيف يعمل Truthmark
|
||||
|
||||
إذا كنت تريد التحقق عبر CLI فقط، فاختر `none` ثم شغّل `truthmark check`؛ ويمكنك إعادة تشغيل `truthmark init` لاحقاً لاختيار المنصات.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="كيف يعمل Truthmark" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 المشكلة: فجوة توثيق الذكاء الاصطناعي
|
||||
تثبّت واجهة سطر أوامر Truthmark عقد المستودع وتتحقق منه. وينفّذ وكيل البرمجة مراجعة الأدلة وأعمال التوثيق من خلال مسارات العمل الأصلية للمضيف التي جرى تثبيتها.
|
||||
|
||||
وكلاء البرمجة بالذكاء الاصطناعي مذهلون في كتابة الكود بسرعة. لكن هذه السرعة تخلق نمط فشل جديداً وخطيراً: **قصة المستودع تنحرف عن الواقع.**
|
||||
يتبع تغيير الكود المعتاد حلقة بسيطة:
|
||||
|
||||
* يضيع السلوك داخل سجلات محادثة عابرة.
|
||||
* تتأخر وثائق المعمارية بسرعة.
|
||||
* تختفي قرارات المنتج بعد التسليم.
|
||||
* يُترك مراجعو الكود لفحص فروق كود خام من دون فهم "السبب".
|
||||
* تُجبر كل جلسة ذكاء اصطناعي جديدة على إعادة اكتشاف حقيقة مستودعك من الصفر.
|
||||
1. يغيّر الوكيل الكود الوظيفي.
|
||||
2. تُشغّل الاختبارات ذات الصلة.
|
||||
3. يتحقق Truth Sync من التوثيق المرتبط.
|
||||
4. ينشئ الوكيل الوثائق والتوجيه أو يحدّثهما عندما تتغير حقيقة المستودع.
|
||||
5. تراجع فرق الكود وفرق الحقيقة معاً.
|
||||
|
||||
## 🎯 الحل: Truthmark
|
||||
## مسارات العمل
|
||||
|
||||
يثبّت **Truthmark** طبقة سير عمل أصلية لـ Git داخل مستودعك. وهو يعالج الجزء الذي يتعطل عادةً في تطوير الذكاء الاصطناعي: مساعدة التوثيق على البقاء متوافقاً مع الكود.
|
||||
| مسار العمل | متى تستخدمه | النتيجة |
|
||||
| -------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| **Truth Document** | يحتاج الكود الموجود إلى توثيق | ينشئ توثيقاً للمنتج والهندسة مدعوماً بالأدلة أو يحدّثه |
|
||||
| **Truth Sync** | تغيّر الكود الوظيفي | يحافظ على توافق الوثائق المرتبطة والتوجيه قبل التسليم |
|
||||
| **Truth Structure** | تحتاج منطقة جديدة إلى ملكية أو أصبحت الوثائق الموجودة واسعة أكثر من اللازم | ينشئ مسارات محددة النطاق وهياكل أولية للوثائق |
|
||||
| **Truth Realize** | ينبغي تحويل وثيقة حقيقة معتمدة إلى برمجيات عاملة | يحدّث الكود الوظيفي انطلاقاً من التوثيق |
|
||||
| **Truth Check** | تحتاج حقيقة المستودع إلى تدقيق | يبلّغ عن مشكلات التوجيه والملكية والأدلة والتوثيق |
|
||||
| **Truthmark Portal** | يريد الفريق موقع توثيق سهل التصفح | ينشئ عرض HTML ثابتاً وملتزماً به من وثائق الحقيقة بصيغة Markdown |
|
||||
|
||||
بدلاً من الأمل في أن يتذكر البشر ووكلاء الذكاء الاصطناعي تحديث الوثائق، يجعل Truthmark التوثيق عادةً منهجية قابلة للمراجعة داخل مستودعك مباشرةً.
|
||||
|
||||
### ✨ لماذا يتميّز Truthmark
|
||||
|
||||
Truthmark ليس مجرد أداة توثيق أخرى. إنه مدمج بعمق في سير عمل الذكاء الاصطناعي:
|
||||
|
||||
* **🚫 بلا ارتباط بمورّد واحد:** لا خدمات مستضافة، ولا قواعد بيانات مخفية، ولا خوادم إضافية للتشغيل.
|
||||
* **🌳 أصلي 100% لـ Git:** كل شيء يعيش في مستودعك. تنتقل الحقيقة مع فرعك.
|
||||
* **🤝 عقد يملكه البشر ويتبعه الوكلاء:** الصائنون يملكون عقد المستودع؛ والوكلاء يتبعون التعليمات المثبّتة أثناء البرمجة.
|
||||
* **✅ الثقة عبر التحقق:** يصبح عمل الذكاء الاصطناعي أسهل للثقة لأن العمل الذي يغيّر السلوك يتضمن قراراً أو فرقاً في توثيق الحقيقة يمكن للبشر مراجعته.
|
||||
|
||||
## 🔄 كيف يعمل
|
||||
|
||||
عندما يعدّل وكيل ذكاء اصطناعي كودك، لا تكون المهمة قد انتهت. يثبّت Truthmark حاجز سير عمل عند وقت الإنهاء يتبعه الوكلاء قبل التسليم:
|
||||
|
||||
1. 💻 **الكود:** يغيّر الوكيل الكود الوظيفي.
|
||||
2. 🧪 **الاختبار:** تُشغّل الاختبارات ذات الصلة.
|
||||
3. 🔍 **التحقق:** يتحقق Truthmark من التوثيق المربوط كجزء من مراجعة وقت الإنهاء المثبّتة.
|
||||
4. 📝 **التوثيق:** يحدّث الوكيل الوثائق عندما تتغير حقيقة المستودع.
|
||||
5. 👀 **المراجعة:** يراجع إنسان *فرق الكود* + *فرق الحقيقة*.
|
||||
|
||||
## 🛠 كيف تتفاعل مع Truthmark
|
||||
|
||||
لدى Truthmark عقد واحد محلي داخل المستودع، وطريقتان لاستخدامه.
|
||||
|
||||
### البشر يثبّتون العقد ويتحققون منه
|
||||
|
||||
يستخدم الصائنون وCI واجهة CLI:
|
||||
|
||||
* `truthmark init` - إنشاء الإعدادات أو تحديثها، واختيار صفر أو أكثر من المنصات، وتثبيت التوجيه وقوالب وثائق الحقيقة وتعليمات المضيفات المختارة.
|
||||
* `truthmark check` - التحقق من حقيقة المستودع من الطرفية.
|
||||
|
||||
### الوكلاء يتبعون العقد أثناء البرمجة
|
||||
|
||||
يثبّت Truthmark تعليمات محلية في المستودع لمضيفي البرمجة بالذكاء الاصطناعي المدعومين مثل Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor.
|
||||
|
||||
الحلقة العادية بسيطة:
|
||||
|
||||
1. اطلب من الوكيل تغيير كود، أو اطلب منه توثيق سلوك موجود.
|
||||
2. تخبر التعليمات المثبّتة الوكيل متى يختبر، ومتى يحدّث وثائق الحقيقة، ومتى يتوقف للمراجعة البشرية.
|
||||
3. أنت تراجع فروق Git العادية: الكود وأي تغييرات في وثائق الحقيقة.
|
||||
|
||||
طلبات الوكيل التي يبدأها المستخدم قليلة عمداً:
|
||||
|
||||
* `/truthmark-document` - توثيق سلوك منفّذ موجود من الكود والاختبارات.
|
||||
* `/truthmark-realize` - تنفيذ الكود من وثائق الحقيقة الموجودة.
|
||||
* `/truthmark-check` - تدقيق حقيقة المستودع.
|
||||
|
||||
Truth Sync ليس الطريقة المعتادة لبدء العمل؛ إنه مراجعة وقت الإنهاء بعد تغييرات الكود الوظيفية.
|
||||
Truth Structure ليس أمراً يومياً؛ إنه يصلح التوجيه أو الملكية فقط عندما يعيق ذلك العمل.
|
||||
يثبّت Truthmark مسارات العمل هذه كأسطح أصلية للمستودع في Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor.
|
||||
|
||||
## ما الذي تحصل عليه
|
||||
|
||||
| القدرة | ما تفعله |
|
||||
| --- | --- |
|
||||
| حقيقة أصلية لـ Git | تُبقي حقيقة المستودع في Markdown وإعدادات ملتزم بها. |
|
||||
| توثيق مرتبط بالفرع | تنتقل الحقيقة مع الفرع بدلاً من العيش في جلسة خاصة. |
|
||||
| CLI بشري | يمنح الصائنين أوامر للإعداد والتحديث والتحقق والفحص. |
|
||||
| إرشادات الوكيل المثبّتة | تخبر وكلاء البرمجة متى يوثقون، أو يختبرون، أو يزامنون الحقيقة، أو يدققون، أو يتوقفون للمراجعة. |
|
||||
| توجيه صريح | يربط مناطق الكود بوثائق الحقيقة المعتمدة. |
|
||||
| تسليمات قابلة للمراجعة | ينتج فروق Git عادية لكل من الكود ووثائق الحقيقة. |
|
||||
| تشغيل محلي أولاً | لا يتطلب خدمة مستضافة أو daemon أو قاعدة بيانات أو خادم MCP. |
|
||||
| حدود كتابة أكثر أماناً | يفصل بين مسارات العمل التي تبدأ بالكود، أو تبدأ بالتوثيق، أو للقراءة فقط، أو للتوثيق فقط. |
|
||||
| التحقق | يبلّغ عن مشكلات التوجيه والسلطة وfrontmatter والروابط والأسطح المولّدة ونطاق الفرع والحداثة والتغطية. |
|
||||
| Portal اختياري | يولّد موقع عرض HTML ثابتاً وملتزماً به من وثائق حقيقة Markdown عندما يُفعّل ويُطلب ذلك صراحةً. |
|
||||
### توثيق يبدأ من الواقع
|
||||
|
||||
## نظرة بصرية عامة
|
||||
يستطيع Truthmark إنشاء توثيق لقدرات المنتج وسلوك التنفيذ وواجهات برمجة التطبيقات والمعمارية ومسارات العمل والعمليات والاختبارات. يقدّم الكود والاختبارات الأدلة، وتحفظ وثائق Markdown محددة النطاق النتيجة.
|
||||
|
||||
|
||||
### توثيق يصمد أمام التغيير التالي
|
||||
|
||||
**الميزات:** ما يثبّته Truthmark وكيف ينقسم سطح سير العمل.
|
||||
تربط المسارات مناطق الكود بالوثائق المعتمدة. وعندما يغيّر الوكلاء السلوك، يعرف Truth Sync أين تنتمي الحقيقة المقابلة ويحافظ على قابلية مراجعة التسليم.
|
||||
|
||||
|
||||
### حقيقة المنتج والهندسة في مسارين منفصلين
|
||||
|
||||
**الموضع:** أين يندرج Truthmark مقارنةً بالمطالبات والذاكرة ومسارات عمل المواصفات.
|
||||
تسجّل حقيقة المنتج الوعود الموجّهة للمستخدم والحدود والقرارات ومعايير القبول. وتسجّل حقيقة الهندسة السلوك الحالي والعقود والمعمارية ومسارات العمل والعمليات وسلوك الاختبارات.
|
||||
|
||||
|
||||
### تعاون أصلي لـ Git
|
||||
|
||||
**تدفق المزامنة:** كيف ينهي Truth Sync تغييرات الكود العادية قبل التسليم.
|
||||
يعيش كل ما يهم في ملفات المستودع الملتزم بها. تتبع الحقيقة الفرع، وتعمل مع طلبات السحب العادية، وتبقى مرئية لكل صائن ووكيل برمجة.
|
||||
|
||||
## لماذا تتبناه الفرق
|
||||
### تشغيل محلي أولاً
|
||||
|
||||
Truthmark مخصص للفرق التي تعرف بالفعل أن وكلاء الذكاء الاصطناعي يستطيعون توليد الكود.
|
||||
|
||||
المشكلة التالية هي الحوكمة.
|
||||
|
||||
ليست الحوكمة كطقوس. بل الحوكمة كسؤال بسيط:
|
||||
|
||||
> بعد هذا التغيير المدعوم بالذكاء الاصطناعي، هل ما زال المستودع يقول الحقيقة؟
|
||||
|
||||
يساعد Truthmark الفرق على الإجابة عن ذلك بملفات ملتزم بها، وتوجيه صريح، وفروق قابلة للمراجعة.
|
||||
|
||||
يكون مفيداً عندما تحتاج إلى:
|
||||
|
||||
- انحراف أقل في التوثيق
|
||||
- تسليمات أفضل
|
||||
- حقيقة منتج خاصة بالفرع
|
||||
- توثيق معماري وAPI دائم
|
||||
- ملكية صريحة بين الوثائق والكود
|
||||
- حدود كتابة أكثر أماناً للوكلاء
|
||||
- توثيق قابل للمراجعة بدلاً من ذاكرة مخفية
|
||||
- مسارات عمل ذكاء اصطناعي تستمر في العمل من ملفات المستودع الملتزم بها
|
||||
لا يحتاج Truthmark إلى خدمة مستضافة أو برنامج خفي أو قاعدة بيانات أو مخزن متجهات أو خادم Model Context Protocol. يحمل المستودع مسار عمل التوثيق الخاص به.
|
||||
|
||||
## أين يندرج Truthmark
|
||||
|
||||
لا يستبدل Truthmark المطالبات أو الذاكرة أو المواصفات أو الاختبارات أو مراجعة الكود.
|
||||
| الحاجة | الأنسب |
|
||||
| -------------------------------------------- | -------------------------- |
|
||||
| مخرجات أفضل من جلسة وكيل واحدة | مطالبة أفضل |
|
||||
| استمرارية شخصية أو على مستوى الجلسة | أداة ذاكرة |
|
||||
| تطوير ميزات يبدأ بالخطة | مسار عمل للمواصفات |
|
||||
| توثيق مرتبط بالفرع ينتقل مع الكود | **Truthmark** |
|
||||
| صحة السلوك | الاختبارات ومراجعة الكود |
|
||||
| توثيق مدعوم بالذكاء الاصطناعي وقابل للمراجعة | **Truthmark + مراجعة Git** |
|
||||
|
||||
إنه يمنح تلك المسارات مكاناً دائماً للرسو في Git.
|
||||
صُمّم Truthmark للصائنين وفرق الهندسة التي تستخدم بالفعل وكلاء البرمجة بالذكاء الاصطناعي وتريد أن يواصل المستودع قول الحقيقة بالسرعة نفسها التي يتغير بها الكود.
|
||||
|
||||
| الحاجة | الأنسب |
|
||||
| --- | --- |
|
||||
| مخرجات أفضل من جلسة وكيل واحدة | مطالبة أفضل |
|
||||
| استمرارية شخصية أو على مستوى الجلسة | أداة ذاكرة |
|
||||
| عمل ميزات يبدأ بالخطة | سير عمل مواصفات |
|
||||
| حقيقة مرتبطة بالفرع تنتقل مع الكود | Truthmark |
|
||||
| التحقق من صحة السلوك | الاختبارات والمراجعة |
|
||||
| مراجعة تغييرات التوثيق المدعومة بالذكاء الاصطناعي | Truthmark مع مراجعة Git |
|
||||
## المضيفات المدعومة وسطر الأوامر
|
||||
|
||||
مجال Truthmark ضيق عمداً بحسب التصميم:
|
||||
مضيفات الوكلاء المدعومة:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
تثبيت إرشادات الوكلاء حولها
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## تعمّق أكثر
|
||||
<details>
|
||||
<summary>مرجع سطر الأوامر</summary>
|
||||
|
||||
README هو الواجهة: سياق سريع، وبدء سريع، والنموذج الذهني الأساسي.
|
||||
| الأمر | الغرض |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| `truthmark init` | ينشئ الإعدادات والتوجيه والقوالب ومسارات عمل المضيفات المختارة أو يحدّثها |
|
||||
| `truthmark check [--base <ref>]` | يتحقق من حقيقة المستودع ويشغّل اختيارياً تشخيصات حداثة الفرع |
|
||||
| `truthmark index --json` | يفحص بيانات المستودع والتوجيه الوصفية المشتقة |
|
||||
| `truthmark impact --base <ref> --json` | يربط الملفات المتغيرة بالوثائق والمالكين والاختبارات القريبة |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | يفحص قابلية تطبيق مسار العمل وأهدافه |
|
||||
| `truthmark validate ...` | يتحقق من تقارير مسارات العمل وتصاريح الكتابة |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | يعاين أسطح المضيف المولّدة أو يزيلها مع الحفاظ على الحقيقة المؤلّفة |
|
||||
|
||||
للاستخدام أمراً بأمر، ومقارنات الأسطح، وتفاصيل المنصات المدعومة، والإعداد، والتوجيه، وPortal، والأمثلة، اقرأ [دليل مستخدم Truthmark](../user-guide.md).
|
||||
تتوفر مخرجات JSON منظّمة في جميع أجزاء واجهة سطر الأوامر للسكربتات والتكامل المستمر.
|
||||
|
||||
## حالة المشروع
|
||||
</details>
|
||||
|
||||
يوفر الإصدار الحالي:
|
||||
## اعرف المزيد
|
||||
|
||||
- أوامر CLI محلية للتهيئة والتحقق والفهرسة وتحليل الأثر وحالة سير العمل
|
||||
- تعليمات وكلاء محلية مولّدة لـ Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor
|
||||
- تشخيصات للتوجيه والسلطة وfrontmatter والروابط والحداثة والأسطح المولّدة ونطاق الفرع والتغطية
|
||||
- وثائق حقيقة مرتبطة بالفرع وعناصر مستمدة لاستخبارات المستودع
|
||||
- [دليل مستخدم Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [فهرس التوثيق](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [نظرة عامة على المعمارية](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [عقود الإعداد والتوجيه والأوامر](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [صيانة حقيقة المستودع](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [المساهمة](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## التوثيق
|
||||
|
||||
- [دليل المستخدم](../user-guide.md)
|
||||
- [فهرس الوثائق](../README.md)
|
||||
- [نظرة عامة على المعمارية](../truthmark/engineering/architecture/overview.md)
|
||||
- [عقود API وCLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [دليل صيانة حقيقة المستودع](../standards/maintaining-repository-truth.md)
|
||||
|
||||
لأوامر التطوير المحلي والمساهمة، راجع [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## حدود التصميم
|
||||
|
||||
Truthmark صغير عمداً: محلي، ملتزم به، مرتبط بالفرع، وقابل للمراجعة.
|
||||
|
||||
إنه ليس خدمة مستضافة، ولا خادم MCP، ولا قاعدة بيانات متجهات، ولا طبقة ذاكرة مخفية، ولا منتج إنفاذ CI، ولا محركاً مستقلاً لإعادة كتابة الكود. يساعد حقيقة المستودع على البقاء مرئية؛ ولا يستبدل الاختبارات أو مراجعة الكود أو حكم البشر.
|
||||
**ثبّت Truthmark، واختر مضيف البرمجة، وحوّل سلوكاً حقيقياً إلى توثيق اليوم.**
|
||||
|
||||
## الترخيص
|
||||
|
||||
MIT. راجع [LICENSE](../../LICENSE).
|
||||
|
||||
## إزالة آمنة
|
||||
|
||||
استخدم `truthmark uninstall --dry-run` لمراجعة أسطح الاستضافة المولّدة بدقة، ثم `truthmark uninstall --apply` لإزالتها. يتم الاحتفاظ بـ truth المؤلفة والتكوين والقوالب ومخرجات البوابة وملفات Gemini والملفات غير المتعلقة بالمستخدم؛ أزل التثبيت العالمي لـ npm بشكل منفصل عبر مدير الحزم.
|
||||
|
||||
+133
-158
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**Deine Agenten schreiben Code. Truthmark pflegt menschenorientierte, in Git überprüfbare Dokumentation.**
|
||||
**Deine Agenten schreiben Code. Truthmark pflegt die menschenlesbare Dokumentation, die du direkt in Git prüfen kannst.**
|
||||
|
||||
Truthmark installiert Git-native Workflows, mit denen KI-Coding-Agenten aus bestehendem Code und Tests neue Produkt- und Engineering-Dokumentation erstellen, sie nach jeder Codeänderung aktuell halten und dir gewöhnliche Markdown-Diffs zur Prüfung vorlegen.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Jetzt starten](#schnellstart-dein-erstes-truth-dokument-erstellen) · [Website](https://merlinhu1.github.io/truthmark/) · [Benutzerhandbuch](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Dieses README in 16 Sprachen lesen</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Schnellstart: lokal in fünf Minuten ausführen
|
||||
## Erstelle die ersten Dokumente und halte sie wahr
|
||||
|
||||
Führe dies in dem Git-Repository aus, das Truthmark verwalten soll:
|
||||
Die meisten Dokumentationswerkzeuge enden bei der Generierung. Truthmark gibt Agenten einen vollständigen Dokumentationslebenszyklus direkt in deinem Repository:
|
||||
|
||||
- **Neue Dokumentation aus funktionierender Software erstellen.** Truth Document liest Code und Tests und erstellt daraus klar abgegrenzte Produkt- oder Engineering-Dokumentation.
|
||||
- **Dokumentation automatisch auf Kurs halten.** Truth Sync läuft nach Änderungen an funktionalem Code bei der Agentenübergabe und aktualisiert die Repository-Wahrheit, bevor die Arbeit abgeschlossen ist.
|
||||
- **Dokumentation wieder in Code verwandeln.** Truth Realize setzt freigegebene Truth-Dokumente um und wahrt dabei einen sauberen Doc-first-Workflow.
|
||||
- **Ownership mit dem Codebestand weiterentwickeln.** Truth Structure erstellt klar abgegrenzte Routen und Startdokumente für neue oder überlastete Bereiche.
|
||||
- **Alles in Git prüfen.** Code, Entscheidungen, Verträge, Architektur, Betrieb und Verhalten reisen gemeinsam mit dem Branch.
|
||||
|
||||
Keine gehostete Wissensdatenbank. Kein privates Agentengedächtnis. Keine Dokumentation, die in Chatverläufen gefangen bleibt.
|
||||
|
||||
## Schnellstart: dein erstes Truth-Dokument erstellen
|
||||
|
||||
**Voraussetzungen:** Node.js 24 oder neuer, ein Git-Repository und ein unterstützter KI-Coding-Host für Agenten-Workflows.
|
||||
|
||||
Führe Folgendes in dem Repository aus, das Truthmark verwalten soll:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
Mit `truthmark init` kannst du Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor oder eine host-neutrale Einrichtung der Befehlszeilenschnittstelle auswählen.
|
||||
|
||||
Bitte nun deinen konfigurierten Agenten, ein echtes Verhalten zu dokumentieren:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document erstellt ein neues, klar abgegrenztes Truth-Dokument, wenn noch keines vorhanden ist, aktualisiert andernfalls das bestehende zuständige Dokument und passt bei Bedarf das Routing an. Funktionalen Code ändert es nicht.
|
||||
|
||||
Prüfe das Ergebnis:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
In einem interaktiven Terminal zeigt `truthmark init` eine nummerierte Mehrfachauswahl. Wähle null oder mehr Plattformen oder `none` für eine host-neutrale, reine CLI-Einrichtung.
|
||||
Nun solltest du Folgendes haben:
|
||||
|
||||
Für Skripte und CI kannst du `--platform` wiederholen; `--json` fragt niemals interaktiv nach:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Die genauen Pfade folgen der Ownership-Struktur deines Repositories. Neue Dateien erscheinen in `git status`; Änderungen an verfolgten Dateien erscheinen in `git diff`.
|
||||
|
||||
Der Aufruf unterscheidet sich je nach Host. OpenCode verwendet `/skill truthmark-document`, Antigravity verwendet `@truthmark-document`, und andere unterstützte Hosts nutzen ihre native Skill- oder Slash-Command-Oberfläche. Die genauen Befehle findest du in der [Plattformtabelle](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms).
|
||||
|
||||
Übergib die ausgewählten Plattformen für Skripte und Continuous Integration ausdrücklich:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
Beim ersten nicht interaktiven Lauf ohne `--platform` bleibt die Einrichtung host-neutral; spätere Läufe behalten die in `.truthmark/config.yml` gespeicherte Auswahl bei.
|
||||
Wähle interaktiv `none` oder führe `truthmark init --clear-platforms` für ein host-neutrales Repository aus. Agentenplattformen kannst du später hinzufügen, indem du `truthmark init` erneut ausführst.
|
||||
|
||||
Probiere nun den häufigsten Einstiegspfad: ein bestehendes Verhalten anhand von Code und Tests dokumentieren. Bitte in deinem KI-Coding-Host den installierten Workflow:
|
||||
Übergib für Branch-relative Aktualitätsdiagnosen eine Git-Basis:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Danach sollten Nutzer Truth Sync normalerweise nicht direkt aufrufen. Programmiere weiter über deinen KI-Host; die installierten Repository-Anweisungen weisen den Agenten an, relevante Tests auszuführen und vor der Übergabe die Truth Sync-Prüfung durchzuführen, wenn funktionaler Code geändert wurde. Du prüfst den daraus entstehenden Code-Diff plus den Truth-Doc-Diff.
|
||||
## So funktioniert Truthmark
|
||||
|
||||
Wenn du nur CLI-Validierung möchtest, wähle `none` und fahre mit `truthmark check` fort; du kannst `truthmark init` später erneut ausführen und Plattformen auswählen.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="So funktioniert Truthmark" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 Das Problem: die KI-Dokumentationslücke
|
||||
Die Truthmark-Befehlszeilenschnittstelle installiert und validiert den Repository-Vertrag. Dein Coding-Agent prüft die Evidenz und erledigt die Dokumentationsarbeit über die installierten host-nativen Workflows.
|
||||
|
||||
KI-Coding-Agenten sind unglaublich gut darin, schnell Code zu schreiben. Doch diese Geschwindigkeit erzeugt einen gefährlichen neuen Fehlermodus: **die Geschichte des Repositories driftet von der Realität ab.**
|
||||
Eine normale Codeänderung folgt einer einfachen Schleife:
|
||||
|
||||
* Verhalten geht in flüchtigen Chatverläufen verloren.
|
||||
* Architekturdokumente geraten schnell in Rückstand.
|
||||
* Produktentscheidungen verschwinden nach der Übergabe.
|
||||
* Code-Reviewer prüfen rohe Code-Diffs, ohne das „Warum“ zu verstehen.
|
||||
* Jede neue KI-Sitzung muss die Wahrheit deines Repositories von Grund auf neu entdecken.
|
||||
1. Der Agent ändert funktionalen Code.
|
||||
2. Relevante Tests werden ausgeführt.
|
||||
3. Truth Sync prüft die zugeordnete Dokumentation.
|
||||
4. Wenn sich die Repository-Wahrheit geändert hat, erstellt oder aktualisiert der Agent Dokumentation und Routing.
|
||||
5. Du prüfst Code-Diff und Truth-Diff gemeinsam.
|
||||
|
||||
## 🎯 Die Lösung: Truthmark
|
||||
## Workflows
|
||||
|
||||
**Truthmark** installiert eine Git-native Workflow-Schicht in deinem Repository. Es behebt den Teil der KI-Entwicklung, der normalerweise kaputtgeht: die Dokumentation dabei zu unterstützen, mit dem Code synchron zu bleiben.
|
||||
| Workflow | Einsatzzeitpunkt | Ergebnis |
|
||||
| -------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| **Truth Document** | Bestehender Code benötigt Dokumentation | Erstellt oder aktualisiert evidenzgestützte Produkt- und Engineering-Dokumentation |
|
||||
| **Truth Sync** | Funktionaler Code wurde geändert | Hält zugeordnete Dokumentation und Routing vor der Übergabe synchron |
|
||||
| **Truth Structure** | Ein neuer Bereich benötigt Ownership oder vorhandene Dokumentation ist zu breit | Erstellt klar abgegrenzte Routen und skelettartige Startdokumente |
|
||||
| **Truth Realize** | Ein freigegebenes Truth-Dokument soll funktionierende Software werden | Aktualisiert funktionalen Code anhand der Dokumentation |
|
||||
| **Truth Check** | Die Repository-Wahrheit muss auditiert werden | Meldet Probleme mit Routing, Ownership, Evidenz und Dokumentation |
|
||||
| **Truthmark Portal** | Das Team wünscht eine durchsuchbare Dokumentationswebsite | Erzeugt aus Markdown-Truth-Dokumenten eine committete statische HTML-Präsentation |
|
||||
|
||||
Statt darauf zu hoffen, dass Menschen und KI-Agenten daran denken, Dokumentation zu aktualisieren, macht Truthmark Dokumentation direkt in deinem Repo zu einer systematischen, überprüfbaren Gewohnheit.
|
||||
Truthmark installiert diese Workflows als native Repository-Oberflächen für Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor.
|
||||
|
||||
### ✨ Warum Truthmark einzigartig ist
|
||||
## Das erhältst du
|
||||
|
||||
Truthmark ist nicht einfach nur ein weiteres Dokumentationstool. Es ist tief in den KI-Workflow integriert:
|
||||
### Dokumentation, die von der Realität ausgeht
|
||||
|
||||
* **🚫 Kein Vendor-Lock-in:** keine gehosteten Dienste, keine versteckten Datenbanken, keine zusätzlichen Server im Betrieb.
|
||||
* **🌳 100 % Git-nativ:** alles lebt in deinem Repository. Die Wahrheit bewegt sich mit deinem Branch.
|
||||
* **🤝 Von Menschen besessener, von Agenten befolgter Vertrag:** Maintainer besitzen den Repository-Vertrag; Agenten folgen beim Coden den installierten Anweisungen.
|
||||
* **✅ Vertrauen durch Verifikation:** KI-Arbeit wird leichter vertrauenswürdig, weil verhaltensändernde Arbeit eine für Menschen überprüfbare Truth-Doc-Entscheidung oder einen Diff enthält.
|
||||
Truthmark kann Produktfunktionen, Implementierungsverhalten, Programmierschnittstellen, Architektur, Workflows, Betrieb und Tests dokumentieren. Code und Tests liefern die Evidenz; klar abgegrenzte Markdown-Dokumente bewahren das Ergebnis.
|
||||
|
||||
## 🔄 Wie es funktioniert
|
||||
### Dokumentation, die die nächste Änderung übersteht
|
||||
|
||||
Wenn ein KI-Agent deinen Code verändert, ist die Arbeit nicht erledigt. Truthmark installiert eine Workflow-Schutzschiene zum Abschluss, der Agenten vor der Übergabe folgen:
|
||||
Routen verbinden Codebereiche mit kanonischer Dokumentation. Wenn Agenten Verhalten ändern, weiß Truth Sync, wohin die zugehörige Wahrheit gehört, und hält die Übergabe überprüfbar.
|
||||
|
||||
1. 💻 **Code:** Der Agent ändert funktionalen Code.
|
||||
2. 🧪 **Test:** Relevante Tests werden ausgeführt.
|
||||
3. 🔍 **Prüfen:** Truthmark prüft zugeordnete Dokumentation als Teil der installierten Abschlussprüfung.
|
||||
4. 📝 **Dokumentation:** Docs werden vom Agenten aktualisiert, wenn sich die Repository-Wahrheit geändert hat.
|
||||
5. 👀 **Review:** Ein Mensch prüft den *Code-Diff* + den *Truth-Diff*.
|
||||
### Produkt- und Engineering-Wahrheit in getrennten Bahnen
|
||||
|
||||
## 🛠 Wie du mit Truthmark interagierst
|
||||
Produktwahrheit erfasst nutzerorientierte Versprechen, Grenzen, Entscheidungen und Akzeptanzkriterien. Engineering-Wahrheit erfasst aktuelles Verhalten, Verträge, Architektur, Workflows, Betrieb und Testverhalten.
|
||||
|
||||
Truthmark hat einen repo-lokalen Vertrag und zwei Arten, ihn zu nutzen.
|
||||
### Git-native Zusammenarbeit
|
||||
|
||||
### Menschen installieren und validieren den Vertrag
|
||||
Alles Wichtige lebt in committeten Repository-Dateien. Die Wahrheit folgt dem Branch, funktioniert mit gewöhnlichen Pull Requests und bleibt für alle Maintainer und Coding-Agenten sichtbar.
|
||||
|
||||
Maintainer und CI nutzen die CLI:
|
||||
### Local-first-Betrieb
|
||||
|
||||
* `truthmark init` - erstellt oder aktualisiert die Konfiguration, lässt null oder mehr Plattformen auswählen und installiert Routing, Truth-Doc-Scaffolds und die ausgewählten KI-Host-Anweisungen.
|
||||
* `truthmark check` - validiert die Repository-Truth im Terminal.
|
||||
Truthmark benötigt keinen gehosteten Dienst, Daemon, keine Datenbank, keinen Vektorspeicher und keinen Model Context Protocol Server. Das Repository bringt seinen eigenen Dokumentations-Workflow mit.
|
||||
|
||||
### Agenten folgen dem Vertrag beim Coden
|
||||
## Wo Truthmark passt
|
||||
|
||||
Truthmark installiert repo-lokale Anweisungen für unterstützte KI-Coding-Hosts wie Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor.
|
||||
| Bedarf | Beste Lösung |
|
||||
| ----------------------------------------------------- | -------------------------- |
|
||||
| Bessere Ergebnisse aus einer einzelnen Agentensitzung | Besserer Prompt |
|
||||
| Persönliche oder sitzungsbezogene Kontinuität | Memory-Tool |
|
||||
| Plan-first-Feature-Arbeit | Spezifikations-Workflow |
|
||||
| Branch-bezogene Dokumentation, die mit dem Code reist | **Truthmark** |
|
||||
| Korrektes Verhalten | Tests und Code-Review |
|
||||
| Überprüfbare KI-gestützte Dokumentation | **Truthmark + Git-Review** |
|
||||
|
||||
Der normale Ablauf ist einfach:
|
||||
Truthmark ist für Maintainer und Engineering-Teams konzipiert, die bereits KI-Coding-Agenten einsetzen und möchten, dass ihr Repository so schnell die Wahrheit weiterschreibt, wie sich der Code ändert.
|
||||
|
||||
1. Bitte deinen Agenten um eine Codeänderung oder darum, vorhandenes Verhalten zu dokumentieren.
|
||||
2. Die installierten Anweisungen sagen dem Agenten, wann er testen, wann er Truth-Dokumente aktualisieren und wann er für menschliche Prüfung stoppen soll.
|
||||
3. Du prüfst normale Git-Diffs: Code plus alle Truth-Doc-Änderungen.
|
||||
## Unterstützte Hosts und Befehlszeile
|
||||
|
||||
Die vom Nutzer gestarteten Agentenanfragen bleiben bewusst wenige:
|
||||
Unterstützte Agenten-Hosts:
|
||||
|
||||
* `/truthmark-document` - dokumentiert vorhandenes implementiertes Verhalten aus Code und Tests.
|
||||
* `/truthmark-realize` - implementiert Code aus vorhandenen Truth-Dokumenten.
|
||||
* `/truthmark-check` - auditiert die Repository-Truth.
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
Truth Sync ist nicht der übliche Weg, Arbeit zu starten; es ist die Abschlussprüfung nach funktionalen Codeänderungen.
|
||||
Truth Structure ist kein Alltagsbefehl; es repariert Routing oder Ownership nur, wenn das die Arbeit blockiert.
|
||||
<details>
|
||||
<summary>Befehlszeilenreferenz</summary>
|
||||
|
||||
## Was du bekommst
|
||||
| Befehl | Zweck |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Konfiguration, Routing, Vorlagen und ausgewählte Host-Workflows erstellen oder aktualisieren |
|
||||
| `truthmark check [--base <ref>]` | Repository-Wahrheit validieren und optional Branch-Aktualitätsdiagnosen ausführen |
|
||||
| `truthmark index --json` | Abgeleitete Repository- und Routing-Metadaten prüfen |
|
||||
| `truthmark impact --base <ref> --json` | Geänderte Dateien Dokumentation, Verantwortlichen und nahen Tests zuordnen |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Anwendbarkeit und Ziele eines Workflows prüfen |
|
||||
| `truthmark validate ...` | Workflow-Berichte und Schreib-Leases validieren |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Generierte Host-Oberflächen anzeigen oder entfernen und verfasste Wahrheit bewahren |
|
||||
|
||||
| Fähigkeit | Was sie tut |
|
||||
| --- | --- |
|
||||
| Git-native Wahrheit | Hält Repository-Wahrheit in committetem Markdown und Konfiguration. |
|
||||
| Branch-bezogene Dokumentation | Die Wahrheit bewegt sich mit dem Branch, statt in einer privaten Sitzung zu leben. |
|
||||
| Menschliche CLI | Gibt Maintainern Befehle für Einrichtung, Aktualisierung, Validierung und Inspektion. |
|
||||
| Installierte Agentenanleitung | Sagt Coding-Agenten, wann sie dokumentieren, testen, Truth synchronisieren, auditieren oder für Review stoppen sollen. |
|
||||
| Explizites Routing | Ordnet Codebereiche kanonischen Truth-Dokumenten zu. |
|
||||
| Überprüfbare Übergaben | Erzeugt normale Git-Diffs sowohl für Code als auch für Truth-Dokumente. |
|
||||
| Local-first-Betrieb | Benötigt keinen gehosteten Dienst, Daemon, keine Datenbank und keinen MCP-Server. |
|
||||
| Sicherere Schreibgrenzen | Trennt code-first-, doc-first-, read-only- und doc-only-Workflows. |
|
||||
| Validierung | Meldet Probleme bei Routing, Autorität, Frontmatter, Links, generierten Oberflächen, Branch-Scope, Aktualität und Abdeckung. |
|
||||
| Optionales Portal | Erzeugt bei ausdrücklicher Aktivierung und Anforderung eine committete statische HTML-Präsentationssite aus Markdown-Truth-Dokumenten. |
|
||||
Strukturierte JSON-Ausgabe ist in der gesamten Befehlszeilenschnittstelle für Skripte und Continuous Integration verfügbar.
|
||||
|
||||
## Visueller Überblick
|
||||
</details>
|
||||
|
||||
|
||||
## Mehr erfahren
|
||||
|
||||
**Funktionen:** was Truthmark installiert und wie Agenten repo-lokale Anweisungen nutzen.
|
||||
- [Truthmark-Benutzerhandbuch](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Dokumentationsindex](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Architekturüberblick](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Konfigurations-, Routing- und Befehlsverträge](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Repository-Wahrheit pflegen](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Mitwirken](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
|
||||
|
||||
**Position:** wo Truthmark im Verhältnis zu Prompts, Memory und Spec-Workflows steht.
|
||||
|
||||
|
||||
|
||||
**Sync-Ablauf:** wie Truth Sync normale Codeänderungen vor der Übergabe abschließt.
|
||||
|
||||
## Warum Teams es einsetzen
|
||||
|
||||
Truthmark ist für Teams, die bereits wissen, dass KI-Agenten Code erzeugen können.
|
||||
|
||||
Das nächste Problem ist Governance.
|
||||
|
||||
Nicht Governance als Zeremonie. Governance als einfache Frage:
|
||||
|
||||
> Sagt das Repository nach dieser KI-gestützten Änderung noch die Wahrheit?
|
||||
|
||||
Truthmark hilft Teams, diese Frage mit committeten Dateien, explizitem Routing und überprüfbaren Diffs zu beantworten.
|
||||
|
||||
Es ist nützlich, wenn du Folgendes brauchst:
|
||||
|
||||
- weniger Dokumentationsdrift
|
||||
- bessere Übergaben
|
||||
- branch-spezifische Produktwahrheit
|
||||
- dauerhafte Architektur- und API-Dokumentation
|
||||
- explizite Ownership zwischen Docs und Code
|
||||
- sicherere Schreibgrenzen für Agenten
|
||||
- überprüfbare Dokumentation statt versteckter Memory
|
||||
- Agentenanleitung, die weiterhin aus committeten Repo-Dateien funktioniert
|
||||
|
||||
## Wo Truthmark hineinpasst
|
||||
|
||||
Truthmark ersetzt keine Prompts, Memory, Specs, Tests oder Code-Reviews.
|
||||
|
||||
Es gibt diesen Workflows einen dauerhaften Ort in Git.
|
||||
|
||||
| Bedarf | Besser geeignet |
|
||||
| --- | --- |
|
||||
| Bessere Ausgabe aus einer Agentensitzung | Besserer Prompt |
|
||||
| Persönliche oder sitzungsbezogene Kontinuität | Memory-Tool |
|
||||
| Plan-first-Feature-Arbeit | Spec-Workflow |
|
||||
| Branch-bezogene Wahrheit, die mit Code reist | Truthmark |
|
||||
| Verhaltenskorrektheit validieren | Tests und Review |
|
||||
| KI-gestützte Dokumentationsänderungen prüfen | Truthmark plus Git-Review |
|
||||
|
||||
Truthmarks Spur ist bewusst schmal:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
Agentenanleitung darum installieren
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
|
||||
## Tiefer einsteigen
|
||||
|
||||
Das README ist das Schaufenster: schneller Kontext, Schnellstart und das zentrale Denkmodell.
|
||||
|
||||
Für befehlsweise Nutzung, Oberflächenvergleiche, Details zu unterstützten Plattformen, Konfiguration, Routing, Portal und Beispiele lies den [Truthmark-Benutzerleitfaden](../user-guide.md).
|
||||
|
||||
## Projektstatus
|
||||
|
||||
Die aktuelle Version bietet:
|
||||
|
||||
- lokale CLI-Befehle für init, check, index, impact und Workflow-Status
|
||||
- generierte repo-lokale Agentenanweisungen für Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor
|
||||
- Diagnosen für Routing, Autorität, Frontmatter, Links, Aktualität, generierte Oberflächen, Branch-Scope und Abdeckung
|
||||
- branch-bezogene Truth-Dokumente und abgeleitete Repository-Intelligence-Artefakte
|
||||
|
||||
## Dokumentation
|
||||
|
||||
- [Benutzerleitfaden](../user-guide.md)
|
||||
- [Docs-Index](../README.md)
|
||||
- [Architekturüberblick](../truthmark/engineering/architecture/overview.md)
|
||||
- [API- und CLI-Verträge](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Leitfaden zur Pflege der Repository-Wahrheit](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Für lokale Entwicklungs- und Beitragsbefehle siehe [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Designgrenzen
|
||||
|
||||
Truthmark ist bewusst klein: lokal, committet, branch-bezogen und überprüfbar.
|
||||
|
||||
Es ist kein gehosteter Dienst, MCP-Server, keine Vektordatenbank, versteckte Memory-Schicht, kein CI-Enforcement-Produkt und keine autonome Code-Rewrite-Engine. Es hilft, Repository-Wahrheit sichtbar zu halten; es ersetzt keine Tests, Code-Reviews oder menschliches Urteil.
|
||||
**Installiere Truthmark, wähle deinen Coding-Host und verwandle noch heute ein echtes Verhalten in Dokumentation.**
|
||||
|
||||
## Lizenz
|
||||
|
||||
MIT. Siehe [LICENSE](../../LICENSE).
|
||||
|
||||
## Sichere Entfernung
|
||||
|
||||
Verwenden Sie `truthmark uninstall --dry-run`, um die exakt erzeugten Host-Surfaces zu prüfen, und anschließend `truthmark uninstall --apply`, um sie zu entfernen. Erstellte truth, Konfiguration, Templates, Portal-Ausgabe, Gemini-Dateien und nicht zusammenhängende Benutzerdateien bleiben erhalten; entfernen Sie eine globale npm-Installation separat mit Ihrem Paketmanager.
|
||||
|
||||
+133
-158
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**Οι πράκτορές σας γράφουν κώδικα. Το Truthmark διατηρεί τεκμηρίωση προσανατολισμένη στον άνθρωπο και ελέγξιμη μέσω Git.**
|
||||
**Οι πράκτορές σας γράφουν κώδικα. Το Truthmark διατηρεί την τεκμηρίωση για ανθρώπους, έτοιμη για έλεγχο στο Git.**
|
||||
|
||||
Το Truthmark εγκαθιστά ροές εργασίας εγγενείς στο Git, ώστε οι πράκτορες προγραμματισμού AI να δημιουργούν νέα τεκμηρίωση προϊόντος και μηχανικής από υπάρχοντα κώδικα και tests, να τη διατηρούν ενημερωμένη μετά από κάθε αλλαγή κώδικα και να σας παραδίδουν συνηθισμένα Markdown diffs για έλεγχο.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Ξεκινήστε](#γρήγορη-εκκίνηση-δημιουργήστε-το-πρώτο-έγγραφο-truth) · [Ιστότοπος](https://merlinhu1.github.io/truthmark/) · [Οδηγός χρήστη](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Διαβάστε αυτό το README σε μία από 16 γλώσσες</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Γρήγορη εκκίνηση: τοπική εκτέλεση σε πέντε λεπτά
|
||||
## Δημιουργήστε την πρώτη τεκμηρίωση. Διατηρήστε την ακριβή.
|
||||
|
||||
Εκτελέστε το μέσα στο αποθετήριο Git που θέλετε να διαχειρίζεται το Truthmark:
|
||||
Τα περισσότερα εργαλεία τεκμηρίωσης σταματούν μετά τη δημιουργία περιεχομένου. Το Truthmark προσφέρει στους πράκτορες έναν πλήρη κύκλο ζωής τεκμηρίωσης μέσα στο αποθετήριό σας:
|
||||
|
||||
- **Δημιουργήστε νέα τεκμηρίωση από λογισμικό που λειτουργεί.** Το Truth Document διαβάζει κώδικα και tests και έπειτα δημιουργεί τεκμηρίωση προϊόντος ή μηχανικής με σαφή όρια.
|
||||
- **Διατηρήστε αυτόματα ευθυγραμμισμένη την τεκμηρίωση.** Το Truth Sync εκτελείται κατά την παράδοση του πράκτορα μετά από αλλαγές λειτουργικού κώδικα και ενημερώνει την αλήθεια του αποθετηρίου πριν ολοκληρωθεί η εργασία.
|
||||
- **Μετατρέψτε την τεκμηρίωση ξανά σε κώδικα.** Το Truth Realize υλοποιεί εγκεκριμένα έγγραφα truth, διατηρώντας μια καθαρή ροή εργασίας doc-first.
|
||||
- **Αποκαταστήστε την ιδιοκτησία καθώς μεγαλώνει η βάση κώδικα.** Το Truth Structure δημιουργεί διαδρομές με σαφή όρια και αρχικά έγγραφα για νέες ή υπερφορτωμένες περιοχές.
|
||||
- **Ελέγξτε τα πάντα στο Git.** Κώδικας, αποφάσεις, συμβόλαια, αρχιτεκτονική, λειτουργίες και συμπεριφορά ταξιδεύουν μαζί με το branch.
|
||||
|
||||
Χωρίς φιλοξενούμενη βάση γνώσης. Χωρίς ιδιωτική μνήμη πράκτορα. Χωρίς τεκμηρίωση παγιδευμένη στο ιστορικό συνομιλιών.
|
||||
|
||||
## Γρήγορη εκκίνηση: δημιουργήστε το πρώτο έγγραφο truth
|
||||
|
||||
**Απαιτήσεις:** Node.js 24 ή νεότερο, ένα αποθετήριο Git και ένας υποστηριζόμενος host προγραμματισμού AI για ροές εργασίας πρακτόρων.
|
||||
|
||||
Εκτελέστε τις παρακάτω εντολές μέσα στο αποθετήριο που θέλετε να διαχειρίζεται το Truthmark:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
Το `truthmark init` σάς επιτρέπει να επιλέξετε Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor ή μια ρύθμιση διεπαφής γραμμής εντολών ανεξάρτητη από host.
|
||||
|
||||
Τώρα ζητήστε από τον διαμορφωμένο πράκτορά σας να τεκμηριώσει μία πραγματική συμπεριφορά:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Το Truth Document δημιουργεί ένα νέο έγγραφο truth με σαφή όρια όταν δεν υπάρχει ήδη, ενημερώνει τον υπάρχοντα ιδιοκτήτη όταν υπάρχει και ενημερώνει τη δρομολόγηση όταν χρειάζεται. Δεν αλλάζει λειτουργικό κώδικα.
|
||||
|
||||
Ελέγξτε το αποτέλεσμα:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
Σε διαδραστικό τερματικό, το `truthmark init` εμφανίζει αριθμημένη πολλαπλή επιλογή. Επιλέξτε μηδέν ή περισσότερες πλατφόρμες ή εισαγάγετε `none` για ρύθμιση ουδέτερη ως προς τον host και μόνο με CLI.
|
||||
Τώρα θα πρέπει να έχετε:
|
||||
|
||||
Για scripts και CI, επαναλάβετε το `--platform`· το `--json` δεν εμφανίζει ποτέ προτροπή:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Οι ακριβείς διαδρομές ακολουθούν τη δομή ιδιοκτησίας του αποθετηρίου σας. Τα νέα αρχεία εμφανίζονται στο `git status` και οι αλλαγές σε παρακολουθούμενα αρχεία στο `git diff`.
|
||||
|
||||
Ο τρόπος κλήσης διαφέρει ανά host. Το OpenCode χρησιμοποιεί `/skill truthmark-document`, το Antigravity χρησιμοποιεί `@truthmark-document` και οι άλλοι υποστηριζόμενοι hosts χρησιμοποιούν τη δική τους εγγενή επιφάνεια skill ή slash command. Δείτε τον [πίνακα πλατφορμών](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) για τις ακριβείς εντολές.
|
||||
|
||||
Για scripts και συνεχή ενοποίηση, δηλώστε ρητά τις επιλεγμένες πλατφόρμες:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
Στην πρώτη μη διαδραστική εκτέλεση χωρίς `--platform`, η ρύθμιση παραμένει ουδέτερη· οι επόμενες εκτελέσεις διατηρούν την επιλογή που έχει αποθηκευτεί στο `.truthmark/config.yml`.
|
||||
Επιλέξτε διαδραστικά `none` ή εκτελέστε `truthmark init --clear-platforms` για ένα αποθετήριο ανεξάρτητο από host. Μπορείτε να προσθέσετε πλατφόρμες πρακτόρων αργότερα, εκτελώντας ξανά το `truthmark init`.
|
||||
|
||||
Τώρα δοκιμάστε την πιο συνηθισμένη διαδρομή υιοθέτησης: τεκμηριώστε μια υπάρχουσα συμπεριφορά από κώδικα και tests. Στον AI coding host σας, ζητήστε από την εγκατεστημένη ροή εργασίας:
|
||||
Για διάγνωση ενημερότητας σε σχέση με το branch, δώστε μια βάση Git:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Μετά από αυτό, οι χρήστες συνήθως δεν πρέπει να καλούν απευθείας το Truth Sync. Συνεχίστε να γράφετε κώδικα μέσω του AI host σας· οι εγκατεστημένες οδηγίες του αποθετηρίου λένε στον πράκτορα να εκτελεί τα σχετικά tests και να πραγματοποιεί την ανασκόπηση Truth Sync πριν από την παράδοση όταν αλλάζει λειτουργικός κώδικας. Εσείς ανασκοπείτε το προκύπτον code diff μαζί με το truth-doc diff.
|
||||
## Πώς λειτουργεί το Truthmark
|
||||
|
||||
Αν θέλετε μόνο επικύρωση CLI, επιλέξτε `none` και εκτελέστε `truthmark check`· μπορείτε αργότερα να εκτελέσετε ξανά `truthmark init` για να επιλέξετε πλατφόρμες.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Πώς λειτουργεί το Truthmark" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 Το πρόβλημα: το κενό τεκμηρίωσης της AI
|
||||
Η διεπαφή γραμμής εντολών του Truthmark εγκαθιστά και επικυρώνει το συμβόλαιο του αποθετηρίου. Ο πράκτορας προγραμματισμού σας εκτελεί την εξέταση αποδεικτικών στοιχείων και την εργασία τεκμηρίωσης μέσω των εγκατεστημένων, εγγενών ροών εργασίας του host.
|
||||
|
||||
Οι AI coding agents είναι απίστευτοι στο να γράφουν κώδικα γρήγορα. Όμως αυτή η ταχύτητα δημιουργεί έναν επικίνδυνο νέο τρόπο αποτυχίας: **η ιστορία του αποθετηρίου απομακρύνεται από την πραγματικότητα.**
|
||||
Μια συνηθισμένη αλλαγή κώδικα ακολουθεί έναν απλό κύκλο:
|
||||
|
||||
* Η συμπεριφορά χάνεται σε εφήμερα ιστορικά συνομιλιών.
|
||||
* Τα έγγραφα αρχιτεκτονικής μένουν γρήγορα πίσω.
|
||||
* Οι αποφάσεις προϊόντος εξαφανίζονται μετά την παράδοση.
|
||||
* Οι reviewers κώδικα μένουν να εξετάζουν ωμά code diffs χωρίς να καταλαβαίνουν το «γιατί».
|
||||
* Κάθε νέα AI session αναγκάζεται να ανακαλύψει ξανά την αλήθεια του αποθετηρίου σας από την αρχή.
|
||||
1. Ο πράκτορας αλλάζει λειτουργικό κώδικα.
|
||||
2. Εκτελούνται τα σχετικά tests.
|
||||
3. Το Truth Sync ελέγχει τη χαρτογραφημένη τεκμηρίωση.
|
||||
4. Ο πράκτορας δημιουργεί ή ενημερώνει τεκμηρίωση και δρομολόγηση όταν έχει αλλάξει η αλήθεια του αποθετηρίου.
|
||||
5. Ελέγχετε μαζί το diff κώδικα και το diff truth.
|
||||
|
||||
## 🎯 Η λύση: Truthmark
|
||||
## Ροές εργασίας
|
||||
|
||||
Το **Truthmark** εγκαθιστά ένα Git-native επίπεδο ροής εργασίας μέσα στο αποθετήριό σας. Διορθώνει το μέρος της ανάπτυξης με AI που συνήθως σπάει: βοηθά την τεκμηρίωση να παραμένει ευθυγραμμισμένη με τον κώδικα.
|
||||
| Ροή εργασίας | Πότε χρησιμοποιείται | Αποτέλεσμα |
|
||||
| -------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| **Truth Document** | Ο υπάρχων κώδικας χρειάζεται τεκμηρίωση | Δημιουργεί ή ενημερώνει τεκμηρίωση προϊόντος και μηχανικής που βασίζεται σε αποδεικτικά στοιχεία |
|
||||
| **Truth Sync** | Άλλαξε λειτουργικός κώδικας | Διατηρεί ευθυγραμμισμένα τη χαρτογραφημένη τεκμηρίωση και τη δρομολόγηση πριν από την παράδοση |
|
||||
| **Truth Structure** | Μια νέα περιοχή χρειάζεται ιδιοκτησία ή η υπάρχουσα τεκμηρίωση είναι υπερβολικά ευρεία | Δημιουργεί διαδρομές με σαφή όρια και σκελετικά αρχικά έγγραφα |
|
||||
| **Truth Realize** | Ένα εγκεκριμένο έγγραφο truth πρέπει να γίνει λογισμικό που λειτουργεί | Ενημερώνει λειτουργικό κώδικα από την τεκμηρίωση |
|
||||
| **Truth Check** | Η αλήθεια του αποθετηρίου χρειάζεται έλεγχο | Αναφέρει ζητήματα δρομολόγησης, ιδιοκτησίας, αποδεικτικών στοιχείων και τεκμηρίωσης |
|
||||
| **Truthmark Portal** | Η ομάδα θέλει έναν εύχρηστο ιστότοπο τεκμηρίωσης | Δημιουργεί μια committed στατική παρουσίαση HTML από έγγραφα truth σε Markdown |
|
||||
|
||||
Αντί να ελπίζετε ότι οι άνθρωποι και οι AI agents θα θυμηθούν να ενημερώσουν τα docs, το Truthmark κάνει την τεκμηρίωση μια συστηματική, ελέγξιμη συνήθεια ακριβώς μέσα στο repo σας.
|
||||
Το Truthmark εγκαθιστά αυτές τις ροές εργασίας ως εγγενείς επιφάνειες αποθετηρίου για Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor.
|
||||
|
||||
### ✨ Γιατί το Truthmark είναι μοναδικό
|
||||
## Τι αποκτάτε
|
||||
|
||||
Το Truthmark δεν είναι απλώς άλλο ένα εργαλείο τεκμηρίωσης. Είναι βαθιά ενσωματωμένο στη ροή εργασίας AI:
|
||||
### Τεκμηρίωση που ξεκινά από την πραγματικότητα
|
||||
|
||||
* **🚫 Μηδενικό κλείδωμα σε προμηθευτή:** Καμία hosted υπηρεσία, καμία κρυφή βάση δεδομένων, κανένας επιπλέον server προς λειτουργία.
|
||||
* **🌳 100% Git-native:** Όλα ζουν στο αποθετήριό σας. Η αλήθεια κινείται μαζί με το branch σας.
|
||||
* **🤝 Συμβόλαιο που ανήκει σε ανθρώπους και ακολουθείται από agents:** Οι συντηρητές κατέχουν το συμβόλαιο του αποθετηρίου· οι agents ακολουθούν τις εγκατεστημένες οδηγίες ενώ γράφουν κώδικα.
|
||||
* **✅ Εμπιστοσύνη μέσω επαλήθευσης:** Η εργασία AI γίνεται ευκολότερο να εμπιστευτεί, επειδή η εργασία που αλλάζει συμπεριφορά περιλαμβάνει μια απόφαση ή ένα diff εγγράφου αλήθειας που μπορεί να ελεγχθεί από άνθρωπο.
|
||||
Το Truthmark μπορεί να δημιουργήσει τεκμηρίωση για δυνατότητες προϊόντος, συμπεριφορά υλοποίησης, διεπαφές προγραμματισμού εφαρμογών, αρχιτεκτονική, ροές εργασίας, λειτουργίες και tests. Ο κώδικας και τα tests παρέχουν τα αποδεικτικά στοιχεία· τα έγγραφα Markdown με σαφή όρια διατηρούν το αποτέλεσμα.
|
||||
|
||||
## 🔄 Πώς λειτουργεί
|
||||
### Τεκμηρίωση που αντέχει στην επόμενη αλλαγή
|
||||
|
||||
Όταν ένας AI agent τροποποιεί τον κώδικά σας, η δουλειά δεν έχει τελειώσει. Το Truthmark εγκαθιστά έναν φραγμό ροής εργασίας στο τέλος, τον οποίο ακολουθούν οι πράκτορες πριν από την παράδοση:
|
||||
Οι διαδρομές συνδέουν περιοχές κώδικα με κανονικά έγγραφα. Όταν οι πράκτορες αλλάζουν συμπεριφορά, το Truth Sync γνωρίζει πού ανήκει η αντίστοιχη αλήθεια και διατηρεί την παράδοση ελέγξιμη.
|
||||
|
||||
1. 💻 **Κώδικας:** Ο πράκτορας τροποποιεί λειτουργικό κώδικα.
|
||||
2. 🧪 **Test:** Εκτελούνται τα σχετικά tests.
|
||||
3. 🔍 **Έλεγχος:** Το Truthmark ελέγχει τη χαρτογραφημένη τεκμηρίωση ως μέρος της εγκατεστημένης τελικής ανασκόπησης.
|
||||
4. 📝 **Τεκμηρίωση:** Τα docs ενημερώνονται από τον πράκτορα όταν αλλάζει η αλήθεια του αποθετηρίου.
|
||||
5. 👀 **Ανασκόπηση:** Ένας άνθρωπος ανασκοπεί το *code diff* + το *diff αλήθειας*.
|
||||
### Αλήθεια προϊόντος και μηχανικής σε ξεχωριστές ροές
|
||||
|
||||
## 🛠 Πώς αλληλεπιδράτε με το Truthmark
|
||||
Η αλήθεια προϊόντος καταγράφει υποσχέσεις προς τους χρήστες, όρια, αποφάσεις και κριτήρια αποδοχής. Η αλήθεια μηχανικής καταγράφει την τρέχουσα συμπεριφορά, τα συμβόλαια, την αρχιτεκτονική, τις ροές εργασίας, τις λειτουργίες και τη συμπεριφορά των tests.
|
||||
|
||||
Το Truthmark έχει ένα repo-local συμβόλαιο και δύο τρόπους χρήσης του.
|
||||
### Συνεργασία εγγενής στο Git
|
||||
|
||||
### Οι άνθρωποι εγκαθιστούν και επικυρώνουν το συμβόλαιο
|
||||
Όλα τα σημαντικά στοιχεία βρίσκονται σε committed αρχεία του αποθετηρίου. Η αλήθεια ακολουθεί το branch, συνεργάζεται με συνηθισμένα pull requests και παραμένει ορατή σε κάθε συντηρητή και πράκτορα προγραμματισμού.
|
||||
|
||||
Οι συντηρητές και το CI χρησιμοποιούν το CLI:
|
||||
### Τοπική λειτουργία κατά προτεραιότητα
|
||||
|
||||
* `truthmark init` - δημιουργεί ή ανανεώνει τη διαμόρφωση, επιτρέπει επιλογή μηδέν ή περισσότερων πλατφορμών και εγκαθιστά routing, truth-doc scaffolds και οδηγίες για τους επιλεγμένους AI hosts.
|
||||
* `truthmark check` - επικυρώνει την αλήθεια του αποθετηρίου από το τερματικό.
|
||||
|
||||
### Οι agents ακολουθούν το συμβόλαιο ενώ γράφουν κώδικα
|
||||
|
||||
Το Truthmark εγκαθιστά repo-local οδηγίες για υποστηριζόμενους AI coding hosts όπως Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor.
|
||||
|
||||
Ο κανονικός κύκλος είναι απλός:
|
||||
|
||||
1. Ζητήστε από τον agent αλλαγή κώδικα ή τεκμηρίωση υπάρχουσας συμπεριφοράς.
|
||||
2. Οι εγκατεστημένες οδηγίες λένε στον agent πότε να δοκιμάσει, πότε να ενημερώσει truth docs και πότε να σταματήσει για ανθρώπινη ανασκόπηση.
|
||||
3. Εσείς ελέγχετε κανονικά Git diffs: κώδικα και τυχόν αλλαγές σε truth docs.
|
||||
|
||||
Τα user-started αιτήματα προς agents είναι σκόπιμα λίγα:
|
||||
|
||||
* `/truthmark-document` - τεκμηριώνει υπάρχουσα υλοποιημένη συμπεριφορά από κώδικα και tests.
|
||||
* `/truthmark-realize` - υλοποιεί κώδικα από υπάρχοντα truth docs.
|
||||
* `/truthmark-check` - ελέγχει την αλήθεια του αποθετηρίου.
|
||||
|
||||
Το Truth Sync δεν είναι ο συνηθισμένος τρόπος έναρξης εργασίας· είναι η τελική ανασκόπηση μετά από λειτουργικές αλλαγές κώδικα.
|
||||
Το Truth Structure δεν είναι καθημερινή εντολή· επισκευάζει routing ή ownership μόνο όταν αυτό μπλοκάρει την εργασία.
|
||||
|
||||
## Τι παίρνετε
|
||||
|
||||
| Δυνατότητα | Τι κάνει |
|
||||
| --- | --- |
|
||||
| Git-native αλήθεια | Διατηρεί την αλήθεια του αποθετηρίου σε committed Markdown και config. |
|
||||
| Τεκμηρίωση με scope branch | Η αλήθεια κινείται με το branch αντί να ζει σε ιδιωτική session. |
|
||||
| Ανθρώπινο CLI | Δίνει στους συντηρητές εντολές setup, refresh, validation και inspection. |
|
||||
| Εγκατεστημένη καθοδήγηση agent | Λέει στους coding agents πότε να τεκμηριώσουν, να δοκιμάσουν, να συγχρονίσουν truth, να κάνουν audit ή να σταματήσουν για review. |
|
||||
| Ρητή δρομολόγηση | Αντιστοιχίζει περιοχές κώδικα σε κανονικά έγγραφα αλήθειας. |
|
||||
| Ελέγξιμες παραδόσεις | Παράγει συνηθισμένα Git diffs τόσο για κώδικα όσο και για έγγραφα αλήθειας. |
|
||||
| Local-first λειτουργία | Δεν απαιτεί hosted service, daemon, βάση δεδομένων ή MCP server. |
|
||||
| Ασφαλέστερα όρια εγγραφής | Διαχωρίζει code-first, doc-first, read-only και doc-only workflows. |
|
||||
| Επικύρωση | Αναφέρει ζητήματα routing, authority, frontmatter, links, generated surfaces, branch scope, freshness και coverage. |
|
||||
| Προαιρετικό Portal | Δημιουργεί ένα committed στατικό HTML presentation site από έγγραφα αλήθειας Markdown όταν ενεργοποιηθεί και ζητηθεί ρητά. |
|
||||
|
||||
## Οπτική επισκόπηση
|
||||
|
||||
|
||||
|
||||
**Χαρακτηριστικά:** τι εγκαθιστά το Truthmark και πώς χωρίζεται η επιφάνεια ροής εργασίας.
|
||||
|
||||
|
||||
|
||||
**Θέση:** πού εντάσσεται το Truthmark σε σχέση με prompts, memory και spec workflows.
|
||||
|
||||
|
||||
|
||||
**Ροή συγχρονισμού:** πώς το Truth Sync κλείνει τις κανονικές αλλαγές κώδικα πριν από την παράδοση.
|
||||
|
||||
## Γιατί το υιοθετούν οι ομάδες
|
||||
|
||||
Το Truthmark είναι για ομάδες που ήδη γνωρίζουν ότι οι AI agents μπορούν να παράγουν κώδικα.
|
||||
|
||||
Το επόμενο πρόβλημα είναι η διακυβέρνηση.
|
||||
|
||||
Όχι διακυβέρνηση ως τελετουργία. Διακυβέρνηση ως μια απλή ερώτηση:
|
||||
|
||||
> Μετά από αυτή την AI-assisted αλλαγή, λέει ακόμη το αποθετήριο την αλήθεια;
|
||||
|
||||
Το Truthmark βοηθά τις ομάδες να απαντήσουν σε αυτό με committed files, ρητή δρομολόγηση και ελέγξιμα diffs.
|
||||
|
||||
Είναι χρήσιμο όταν χρειάζεστε:
|
||||
|
||||
- λιγότερη απόκλιση τεκμηρίωσης
|
||||
- καλύτερες παραδόσεις
|
||||
- αλήθεια προϊόντος ειδική ανά branch
|
||||
- ανθεκτική τεκμηρίωση αρχιτεκτονικής και API
|
||||
- ρητή ιδιοκτησία μεταξύ docs και code
|
||||
- ασφαλέστερα όρια εγγραφής πρακτόρων
|
||||
- ελέγξιμη τεκμηρίωση αντί για κρυφή μνήμη
|
||||
- καθοδήγηση για agents που εξακολουθεί να λειτουργεί από committed αρχεία του repo
|
||||
Το Truthmark δεν χρειάζεται φιλοξενούμενη υπηρεσία, daemon, βάση δεδομένων, διανυσματική αποθήκη ή διακομιστή Model Context Protocol. Το αποθετήριο μεταφέρει τη δική του ροή εργασίας τεκμηρίωσης.
|
||||
|
||||
## Πού ταιριάζει το Truthmark
|
||||
|
||||
Το Truthmark δεν αντικαθιστά prompts, memory, specs, tests ή code review.
|
||||
| Ανάγκη | Καλύτερη επιλογή |
|
||||
| ----------------------------------------------------------- | ------------------------------- |
|
||||
| Καλύτερο αποτέλεσμα από μία συνεδρία πράκτορα | Καλύτερο prompt |
|
||||
| Προσωπική συνέχεια ή συνέχεια σε επίπεδο συνεδρίας | Εργαλείο μνήμης |
|
||||
| Εργασία σε λειτουργίες με πρώτο βήμα τον σχεδιασμό | Ροή εργασίας προδιαγραφών |
|
||||
| Τεκμηρίωση με εύρος branch που ταξιδεύει μαζί με τον κώδικα | **Truthmark** |
|
||||
| Ορθότητα συμπεριφοράς | Tests και έλεγχος κώδικα |
|
||||
| Ελέγξιμη τεκμηρίωση με τη βοήθεια AI | **Truthmark + έλεγχος στο Git** |
|
||||
|
||||
Δίνει σε αυτές τις ροές εργασίας ένα ανθεκτικό μέρος για να προσγειωθούν στο Git.
|
||||
Το Truthmark έχει σχεδιαστεί για συντηρητές και ομάδες μηχανικής που χρησιμοποιούν ήδη πράκτορες προγραμματισμού AI και θέλουν το αποθετήριο να συνεχίζει να λέει την αλήθεια με την ίδια ταχύτητα που αλλάζει ο κώδικας.
|
||||
|
||||
| Ανάγκη | Καλύτερη επιλογή |
|
||||
| --- | --- |
|
||||
| Καλύτερη έξοδος από μία session πράκτορα | Καλύτερο prompt |
|
||||
| Προσωπική ή session-level συνέχεια | Εργαλείο μνήμης |
|
||||
| Feature work με σχέδιο πρώτα | Spec workflow |
|
||||
| Αλήθεια με scope branch που ταξιδεύει με τον κώδικα | Truthmark |
|
||||
| Επικύρωση ορθότητας συμπεριφοράς | Tests και review |
|
||||
| Ανασκόπηση AI-assisted αλλαγών τεκμηρίωσης | Truthmark μαζί με Git review |
|
||||
## Υποστηριζόμενοι hosts και γραμμή εντολών
|
||||
|
||||
Η λωρίδα του Truthmark είναι σκόπιμα στενή:
|
||||
Υποστηριζόμενοι hosts πρακτόρων:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
εγκατάσταση καθοδήγησης για agents γύρω από αυτή
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Πηγαίνετε βαθύτερα
|
||||
<details>
|
||||
<summary>Αναφορά γραμμής εντολών</summary>
|
||||
|
||||
Το README είναι η βιτρίνα: γρήγορο πλαίσιο, γρήγορη εκκίνηση και το βασικό νοητικό μοντέλο.
|
||||
| Εντολή | Σκοπός |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| `truthmark init` | Δημιουργεί ή ανανεώνει τη διαμόρφωση, τη δρομολόγηση, τα πρότυπα και τις ροές εργασίας των επιλεγμένων hosts |
|
||||
| `truthmark check [--base <ref>]` | Επικυρώνει την αλήθεια του αποθετηρίου και προαιρετικά εκτελεί διάγνωση ενημερότητας branch |
|
||||
| `truthmark index --json` | Εξετάζει παράγωγα μεταδεδομένα αποθετηρίου και δρομολόγησης |
|
||||
| `truthmark impact --base <ref> --json` | Χαρτογραφεί τα αλλαγμένα αρχεία σε τεκμηρίωση, ιδιοκτήτες και κοντινά tests |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Εξετάζει τη δυνατότητα εφαρμογής και τους στόχους της ροής εργασίας |
|
||||
| `truthmark validate ...` | Επικυρώνει αναφορές ροών εργασίας και άδειες εγγραφής |
|
||||
| `truthmark uninstall --dry-run\|--apply` | Προεπισκοπεί ή αφαιρεί τις παραγόμενες επιφάνειες host, διατηρώντας τα έγγραφα truth που έχουν συνταχθεί |
|
||||
|
||||
Για χρήση ανά εντολή, συγκρίσεις επιφανειών, λεπτομέρειες υποστηριζόμενων πλατφορμών, διαμόρφωση, δρομολόγηση, Portal και παραδείγματα, διαβάστε τον [Οδηγό χρήστη Truthmark](../user-guide.md).
|
||||
Δομημένη έξοδος JSON είναι διαθέσιμη σε ολόκληρη τη διεπαφή γραμμής εντολών για scripts και συνεχή ενοποίηση.
|
||||
|
||||
## Κατάσταση έργου
|
||||
</details>
|
||||
|
||||
Η τρέχουσα έκδοση παρέχει:
|
||||
## Μάθετε περισσότερα
|
||||
|
||||
- τοπικές CLI commands για init, check, index, impact και workflow status
|
||||
- παραγόμενες repo-local οδηγίες για agents για Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor
|
||||
- diagnostics για route, authority, frontmatter, link, freshness, generated-surface, branch-scope και coverage
|
||||
- έγγραφα αλήθειας με scope branch και παράγωγα τεχνουργήματα ευφυΐας αποθετηρίου
|
||||
- [Οδηγός χρήστη Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Ευρετήριο τεκμηρίωσης](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Επισκόπηση αρχιτεκτονικής](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Συμβόλαια διαμόρφωσης, δρομολόγησης και εντολών](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Συντήρηση της αλήθειας του αποθετηρίου](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Συνεισφορά](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Τεκμηρίωση
|
||||
|
||||
- [Οδηγός χρήστη](../user-guide.md)
|
||||
- [Ευρετήριο docs](../README.md)
|
||||
- [Επισκόπηση αρχιτεκτονικής](../truthmark/engineering/architecture/overview.md)
|
||||
- [Συμβάσεις API και CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Οδηγός συντήρησης αλήθειας αποθετηρίου](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Για εντολές τοπικής ανάπτυξης και συνεισφοράς, δείτε το [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Όρια σχεδιασμού
|
||||
|
||||
Το Truthmark είναι σκόπιμα μικρό: τοπικό, committed, με scope branch και ελέγξιμο.
|
||||
|
||||
Δεν είναι hosted service, MCP server, vector database, κρυφό memory layer, προϊόν επιβολής CI ή αυτόνομη μηχανή επανεγγραφής κώδικα. Βοηθά την αλήθεια του αποθετηρίου να παραμένει ορατή· δεν αντικαθιστά tests, code review ή ανθρώπινη κρίση.
|
||||
**Εγκαταστήστε το Truthmark, επιλέξτε τον host προγραμματισμού σας και μετατρέψτε σήμερα μία πραγματική συμπεριφορά σε τεκμηρίωση.**
|
||||
|
||||
## Άδεια
|
||||
|
||||
MIT. Δείτε [LICENSE](../../LICENSE).
|
||||
|
||||
## Ασφαλής κατάργηση
|
||||
|
||||
Χρησιμοποιήστε το `truthmark uninstall --dry-run` για να ελέγξετε τις ακριβώς παραγόμενες επιφάνειες host και στη συνέχεια το `truthmark uninstall --apply` για να τις αφαιρέσετε. Το δημιουργημένο truth, η διαμόρφωση, τα templates, η έξοδος του Portal, τα αρχεία Gemini και τα μη σχετιζόμενα αρχεία χρήστη διατηρούνται. Καταργήστε την παγκόσμια εγκατάσταση του npm ξεχωριστά με το εργαλείο διαχείρισης πακέτων σας.
|
||||
MIT. Δείτε το [LICENSE](../../LICENSE).
|
||||
|
||||
+131
-156
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**Tus agentes escriben código. Truthmark mantiene documentación orientada a humanos y revisable en Git.**
|
||||
**Tus agentes escriben código. Truthmark mantiene la documentación orientada a las personas y revisable en Git.**
|
||||
|
||||
Truthmark instala flujos de trabajo nativos de Git que permiten a los agentes de programación con IA crear nueva documentación de producto e ingeniería a partir del código y las pruebas existentes, mantenerla actualizada después de cada cambio de código y ofrecerte diffs de Markdown convencionales para su revisión.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Comenzar](#inicio-rápido-crea-tu-primer-documento-de-verdad) · [Sitio web](https://merlinhu1.github.io/truthmark/) · [Guía de usuario](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Lee este README en 16 idiomas</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Inicio rápido: ejecutarlo localmente en cinco minutos
|
||||
## Crea los primeros documentos. Mantenlos fieles a la realidad.
|
||||
|
||||
Ejecuta esto dentro del repositorio Git que quieres que Truthmark gestione:
|
||||
La mayoría de las herramientas de documentación se detienen después de generar contenido. Truthmark proporciona a los agentes un ciclo de vida completo para la documentación dentro de tu repositorio:
|
||||
|
||||
- **Crea documentación nueva a partir de software funcional.** Truth Document lee el código y las pruebas y, a continuación, crea documentación acotada de producto o ingeniería.
|
||||
- **Mantén la documentación alineada automáticamente.** Truth Sync se ejecuta durante la entrega del agente después de cambios funcionales en el código y actualiza la verdad del repositorio antes de que finalice el trabajo.
|
||||
- **Convierte la documentación de nuevo en código.** Truth Realize implementa documentos de verdad aprobados y conserva un flujo de trabajo limpio que parte de la documentación.
|
||||
- **Repara la propiedad a medida que crece el código base.** Truth Structure crea rutas acotadas y documentos iniciales para áreas nuevas o sobrecargadas.
|
||||
- **Revísalo todo en Git.** El código, las decisiones, los contratos, la arquitectura, las operaciones y el comportamiento viajan juntos en la rama.
|
||||
|
||||
Sin bases de conocimiento alojadas. Sin memoria privada de los agentes. Sin documentación atrapada en el historial del chat.
|
||||
|
||||
## Inicio rápido: crea tu primer documento de verdad
|
||||
|
||||
**Requisitos:** Node.js 24 o posterior, un repositorio Git y un host de programación con IA compatible con flujos de trabajo de agentes.
|
||||
|
||||
Ejecuta lo siguiente dentro del repositorio que quieres que gestione Truthmark:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` te permite seleccionar Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor o una configuración de interfaz de línea de comandos neutral respecto al host.
|
||||
|
||||
Ahora pide al agente configurado que documente un comportamiento real:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document crea un nuevo documento de verdad acotado cuando no existe ninguno, actualiza al propietario existente cuando ya lo hay y actualiza el enrutamiento cuando es necesario. No modifica el código funcional.
|
||||
|
||||
Revisa el resultado:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
En una terminal interactiva, `truthmark init` muestra una selección múltiple numerada. Elige cero o más plataformas, o `none` para una configuración neutral respecto al host y solo de CLI.
|
||||
Ahora deberías tener:
|
||||
|
||||
Para scripts y CI, repite `--platform`; `--json` nunca solicita entrada interactiva:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Las rutas exactas siguen la estructura de propiedad de tu repositorio. Los archivos nuevos aparecen en `git status`; los cambios en archivos con seguimiento aparecen en `git diff`.
|
||||
|
||||
La invocación varía según el host. OpenCode utiliza `/skill truthmark-document`, Antigravity utiliza `@truthmark-document` y los demás hosts compatibles emplean su superficie nativa de habilidades o comandos con barra. Consulta la [tabla de plataformas](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) para conocer los comandos exactos.
|
||||
|
||||
Para scripts e integración continua, pasa explícitamente las plataformas seleccionadas:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
En la primera ejecución no interactiva sin `--platform`, la configuración permanece neutral; las ejecuciones posteriores conservan la selección guardada en `.truthmark/config.yml`.
|
||||
Elige `none` de forma interactiva o ejecuta `truthmark init --clear-platforms` para obtener un repositorio neutral respecto al host. Puedes añadir plataformas de agentes más adelante volviendo a ejecutar `truthmark init`.
|
||||
|
||||
Ahora prueba la ruta de adopción más común: documentar un comportamiento existente a partir del código y las pruebas. En tu host de codificación con IA, pídele al workflow instalado:
|
||||
Para diagnósticos de vigencia relativos a la rama, pasa una base de Git:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Después de eso, normalmente los usuarios no deberían invocar Truth Sync directamente. Sigue programando mediante tu host de IA; las instrucciones instaladas en el repositorio le dicen al agente que ejecute las pruebas pertinentes y realice la revisión de Truth Sync antes de la entrega cuando haya cambios de código funcional. Tú revisas el diff de código resultante junto con el diff de los documentos de verdad.
|
||||
## Cómo funciona Truthmark
|
||||
|
||||
Si solo quieres validación por CLI, elige `none` y continúa con `truthmark check`; más tarde puedes volver a ejecutar `truthmark init` para seleccionar plataformas.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Cómo funciona Truthmark" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 El problema: la brecha de documentación de la IA
|
||||
La interfaz de línea de comandos de Truthmark instala y valida el contrato del repositorio. Tu agente de programación realiza la revisión de evidencias y el trabajo de documentación mediante los flujos de trabajo nativos del host instalados.
|
||||
|
||||
Los agentes de codificación con IA son increíbles escribiendo código rápidamente. Pero esa velocidad crea un nuevo modo de fallo peligroso: **la historia del repositorio se desvía de la realidad.**
|
||||
Un cambio de código normal sigue un ciclo sencillo:
|
||||
|
||||
* El comportamiento se pierde en historiales de chat efímeros.
|
||||
* Los documentos de arquitectura se quedan atrás rápidamente.
|
||||
* Las decisiones de producto desaparecen después de la entrega.
|
||||
* Los revisores de código acaban examinando diffs de código sin procesar, sin entender el «por qué».
|
||||
* Cada nueva sesión de IA se ve obligada a redescubrir desde cero la verdad de tu repositorio.
|
||||
1. El agente modifica el código funcional.
|
||||
2. Se ejecutan las pruebas pertinentes.
|
||||
3. Truth Sync comprueba la documentación asociada.
|
||||
4. El agente crea o actualiza la documentación y el enrutamiento cuando cambia la verdad del repositorio.
|
||||
5. Revisas juntos el diff de código y el diff de verdad.
|
||||
|
||||
## 🎯 La solución: Truthmark
|
||||
## Flujos de trabajo
|
||||
|
||||
**Truthmark** instala en tu repositorio una capa de workflow nativa de Git. Arregla la parte del desarrollo con IA que normalmente se rompe: ayudar a que la documentación permanezca alineada con el código.
|
||||
| Flujo de trabajo | Cuándo usarlo | Resultado |
|
||||
| -------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| **Truth Document** | El código existente necesita documentación | Crea o actualiza documentación de producto e ingeniería respaldada por evidencias |
|
||||
| **Truth Sync** | Ha cambiado el código funcional | Mantiene alineados la documentación asociada y el enrutamiento antes de la entrega |
|
||||
| **Truth Structure** | Un área nueva necesita propiedad o la documentación existente es demasiado amplia | Crea rutas acotadas y documentos iniciales básicos |
|
||||
| **Truth Realize** | Un documento de verdad aprobado debe convertirse en software funcional | Actualiza el código funcional a partir de la documentación |
|
||||
| **Truth Check** | La verdad del repositorio necesita una auditoría | Informa de problemas de enrutamiento, propiedad, evidencias y documentación |
|
||||
| **Truthmark Portal** | El equipo quiere un sitio de documentación navegable | Genera una presentación HTML estática y versionada a partir de documentos de verdad en Markdown |
|
||||
|
||||
En lugar de esperar que humanos y agentes de IA recuerden actualizar la documentación, Truthmark convierte la documentación en un hábito sistemático y revisable dentro de tu propio repositorio.
|
||||
|
||||
### ✨ Por qué Truthmark es único
|
||||
|
||||
Truthmark no es simplemente otra herramienta de documentación. Está profundamente integrado en el workflow de IA:
|
||||
|
||||
* **🚫 Sin dependencia de proveedor:** no hay servicios alojados, bases de datos ocultas ni servidores adicionales que operar.
|
||||
* **🌳 100 % nativo de Git:** todo vive en tu repositorio. La verdad se mueve con tu rama.
|
||||
* **🤝 Contrato propiedad de humanos y seguido por agentes:** Los mantenedores poseen el contrato del repositorio; los agentes siguen las instrucciones instaladas mientras programan.
|
||||
* **✅ Confianza mediante verificación:** el trabajo de la IA resulta más fácil de confiar porque el trabajo que cambia comportamiento incluye una decisión o un diff de documento de verdad revisable por humanos.
|
||||
|
||||
## 🔄 Cómo funciona
|
||||
|
||||
Cuando un agente de IA modifica tu código, el trabajo no ha terminado. Truthmark instala una protección de workflow al final de la tarea que los agentes siguen antes de la entrega:
|
||||
|
||||
1. 💻 **Código:** el agente modifica código funcional.
|
||||
2. 🧪 **Prueba:** se ejecutan las pruebas pertinentes.
|
||||
3. 🔍 **Comprobación:** Truthmark revisa la documentación mapeada como parte de la revisión de cierre instalada.
|
||||
4. 📝 **Documentación:** el agente actualiza los docs cuando la verdad del repositorio ha cambiado.
|
||||
5. 👀 **Revisión:** una persona revisa el *diff de código* + el *diff de verdad*.
|
||||
|
||||
## 🛠 Cómo interactúas con Truthmark
|
||||
|
||||
Truthmark tiene un contrato local del repositorio y dos formas de usarlo.
|
||||
|
||||
### Las personas instalan y validan el contrato
|
||||
|
||||
Los mantenedores y CI usan la CLI:
|
||||
|
||||
* `truthmark init` - crea o actualiza la configuración, permite elegir cero o más plataformas e instala el enrutamiento, los andamios de documentos de verdad y las instrucciones de los hosts elegidos.
|
||||
* `truthmark check` - valida la verdad del repositorio desde la terminal.
|
||||
|
||||
### Los agentes siguen el contrato mientras programan
|
||||
|
||||
Truthmark instala instrucciones locales del repositorio para hosts de codificación con IA compatibles, como Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor.
|
||||
|
||||
El ciclo normal es simple:
|
||||
|
||||
1. Pide a tu agente un cambio de código o que documente un comportamiento existente.
|
||||
2. Las instrucciones instaladas le dicen al agente cuándo probar, cuándo actualizar documentos de verdad y cuándo detenerse para revisión humana.
|
||||
3. Revisas diffs Git normales: código más cualquier cambio en documentos de verdad.
|
||||
|
||||
Las solicitudes de agente iniciadas por el usuario son deliberadamente pocas:
|
||||
|
||||
* `/truthmark-document` - documenta comportamiento implementado existente a partir de código y tests.
|
||||
* `/truthmark-realize` - implementa código a partir de documentos de verdad existentes.
|
||||
* `/truthmark-check` - audita la verdad del repositorio.
|
||||
|
||||
Truth Sync no es la forma habitual de iniciar trabajo; es la revisión de cierre después de cambios funcionales de código.
|
||||
Truth Structure no es un comando cotidiano; repara enrutamiento o propiedad solo cuando eso bloquea el trabajo.
|
||||
Truthmark instala estos flujos de trabajo como superficies nativas del repositorio para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor.
|
||||
|
||||
## Lo que obtienes
|
||||
|
||||
| Capacidad | Qué hace |
|
||||
| --- | --- |
|
||||
| Verdad nativa de Git | Mantiene la verdad del repositorio en Markdown y configuración versionados. |
|
||||
| Documentación con alcance de rama | La verdad se mueve con la rama en lugar de vivir en una sesión privada. |
|
||||
| CLI humana | Da a los mantenedores comandos de configuración, actualización, validación e inspección. |
|
||||
| Guía de agente instalada | Indica a los agentes de codificación cuándo documentar, probar, sincronizar verdad, auditar o detenerse para revisión. |
|
||||
| Enrutamiento explícito | Mapea áreas de código a documentos de verdad canónicos. |
|
||||
| Entregas revisables | Produce diffs Git ordinarios tanto para el código como para los documentos de verdad. |
|
||||
| Operación local-first | No requiere servicio alojado, demonio, base de datos ni servidor MCP. |
|
||||
| Límites de escritura más seguros | Separa workflows code-first, doc-first, read-only y doc-only. |
|
||||
| Validación | Informa problemas de enrutamiento, autoridad, frontmatter, enlaces, superficies generadas, alcance de rama, frescura y cobertura. |
|
||||
| Portal opcional | Genera, cuando se activa y solicita explícitamente, un sitio estático HTML versionado a partir de documentos de verdad Markdown. |
|
||||
### Documentación que parte de la realidad
|
||||
|
||||
## Panorama visual
|
||||
Truthmark puede crear documentación sobre capacidades del producto, comportamiento de la implementación, interfaces de programación de aplicaciones, arquitectura, flujos de trabajo, operaciones y pruebas. El código y las pruebas aportan las evidencias; los documentos Markdown acotados conservan el resultado.
|
||||
|
||||
|
||||
### Documentación que sobrevive al siguiente cambio
|
||||
|
||||
**Funciones:** lo que instala Truthmark y cómo se divide la superficie de workflow.
|
||||
Las rutas conectan áreas del código con documentos canónicos. Cuando los agentes cambian el comportamiento, Truth Sync sabe dónde debe quedar registrada la verdad correspondiente y mantiene la entrega lista para revisión.
|
||||
|
||||
|
||||
### La verdad de producto e ingeniería en carriles separados
|
||||
|
||||
**Posición:** dónde encaja Truthmark en relación con prompts, memoria y workflows de especificación.
|
||||
La verdad de producto recoge promesas orientadas al usuario, límites, decisiones y criterios de aceptación. La verdad de ingeniería recoge el comportamiento actual, los contratos, la arquitectura, los flujos de trabajo, las operaciones y el comportamiento de las pruebas.
|
||||
|
||||
|
||||
### Colaboración nativa de Git
|
||||
|
||||
**Flujo de sincronización:** cómo Truth Sync cierra los cambios de código normales antes de la entrega.
|
||||
Todo lo importante reside en archivos versionados del repositorio. La verdad sigue a la rama, funciona con solicitudes de incorporación de cambios convencionales y permanece visible para cada mantenedor y agente de programación.
|
||||
|
||||
## Por qué los equipos lo adoptan
|
||||
### Operación local primero
|
||||
|
||||
Truthmark es para equipos que ya saben que los agentes de IA pueden generar código.
|
||||
|
||||
El siguiente problema es la gobernanza.
|
||||
|
||||
No la gobernanza como ceremonia. Gobernanza como una pregunta sencilla:
|
||||
|
||||
> Después de este cambio asistido por IA, ¿el repositorio sigue diciendo la verdad?
|
||||
|
||||
Truthmark ayuda a los equipos a responder con archivos versionados, enrutamiento explícito y diffs revisables.
|
||||
|
||||
Es útil cuando necesitas:
|
||||
|
||||
- menos deriva de documentación
|
||||
- mejores entregas
|
||||
- verdad de producto específica de la rama
|
||||
- documentación duradera de arquitectura y API
|
||||
- propiedad explícita entre docs y código
|
||||
- límites de escritura de agentes más seguros
|
||||
- documentación revisable en lugar de memoria oculta
|
||||
- guía de agente que sigue funcionando desde archivos versionados del repositorio
|
||||
Truthmark no necesita servicios alojados, demonios, bases de datos, almacenes vectoriales ni servidores del Protocolo de Contexto de Modelo. El repositorio contiene su propio flujo de trabajo de documentación.
|
||||
|
||||
## Dónde encaja Truthmark
|
||||
|
||||
Truthmark no reemplaza prompts, memoria, especificaciones, pruebas ni revisión de código.
|
||||
| Necesidad | Mejor opción |
|
||||
| ------------------------------------------------------- | ------------------------------------- |
|
||||
| Mejor resultado de una sesión de agente | Un prompt mejor |
|
||||
| Continuidad personal o a nivel de sesión | Una herramienta de memoria |
|
||||
| Desarrollo de funcionalidades partiendo de un plan | Un flujo de trabajo de especificación |
|
||||
| Documentación acotada a la rama que viaja con el código | **Truthmark** |
|
||||
| Corrección del comportamiento | Pruebas y revisión de código |
|
||||
| Documentación asistida por IA y revisable | **Truthmark + revisión en Git** |
|
||||
|
||||
Les da a esos workflows un lugar duradero donde aterrizar en Git.
|
||||
Truthmark está diseñado para mantenedores y equipos de ingeniería que ya utilizan agentes de programación con IA y quieren que el repositorio siga diciendo la verdad con la misma rapidez con la que cambia el código.
|
||||
|
||||
| Necesidad | Mejor opción |
|
||||
| --- | --- |
|
||||
| Mejor salida de una sesión de agente | Mejor prompt |
|
||||
| Continuidad personal o a nivel de sesión | Herramienta de memoria |
|
||||
| Trabajo de funcionalidad con plan primero | Workflow de especificación |
|
||||
| Verdad con alcance de rama que viaja con el código | Truthmark |
|
||||
| Validar la corrección del comportamiento | Pruebas y revisión |
|
||||
| Revisar cambios de documentación asistidos por IA | Truthmark más revisión Git |
|
||||
## Hosts compatibles y línea de comandos
|
||||
|
||||
El carril de Truthmark es estrecho por diseño:
|
||||
Hosts de agentes compatibles:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
instalar guía de agente alrededor de ella
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Profundizar
|
||||
<details>
|
||||
<summary>Referencia de la línea de comandos</summary>
|
||||
|
||||
El README es el escaparate: contexto rápido, inicio rápido y el modelo mental central.
|
||||
| Comando | Propósito |
|
||||
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Crea o actualiza la configuración, el enrutamiento, las plantillas y los flujos de trabajo de los hosts seleccionados |
|
||||
| `truthmark check [--base <ref>]` | Valida la verdad del repositorio y, opcionalmente, ejecuta diagnósticos de vigencia de la rama |
|
||||
| `truthmark index --json` | Inspecciona los metadatos derivados del repositorio y del enrutamiento |
|
||||
| `truthmark impact --base <ref> --json` | Asocia los archivos modificados con la documentación, los propietarios y las pruebas cercanas |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Inspecciona la aplicabilidad y los objetivos del flujo de trabajo |
|
||||
| `truthmark validate ...` | Valida los informes de los flujos de trabajo y las concesiones de escritura |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Previsualiza o elimina las superficies de host generadas sin alterar la verdad creada |
|
||||
|
||||
Para uso comando por comando, comparaciones de superficies, detalles de plataformas compatibles, configuración, enrutamiento, Portal y ejemplos, lee la [guía de usuario de Truthmark](../user-guide.md).
|
||||
La salida JSON estructurada está disponible en toda la interfaz de línea de comandos para scripts e integración continua.
|
||||
|
||||
## Estado del proyecto
|
||||
</details>
|
||||
|
||||
La versión actual proporciona:
|
||||
## Más información
|
||||
|
||||
- comandos CLI locales para init, check, index, impact y estado de workflows
|
||||
- instrucciones de agente locales del repositorio generadas para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor
|
||||
- diagnósticos de enrutamiento, autoridad, frontmatter, enlaces, frescura, superficies generadas, alcance de rama y cobertura
|
||||
- documentos de verdad con alcance de rama y artefactos derivados de inteligencia del repositorio
|
||||
- [Guía de usuario de Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Índice de documentación](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Descripción general de la arquitectura](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Contratos de configuración, enrutamiento y comandos](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Mantenimiento de la verdad del repositorio](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Contribuir](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Documentación
|
||||
|
||||
- [Guía de usuario](../user-guide.md)
|
||||
- [Índice de docs](../README.md)
|
||||
- [Vista general de arquitectura](../truthmark/engineering/architecture/overview.md)
|
||||
- [Contratos de API y CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Guía de mantenimiento de la verdad del repositorio](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Para comandos de desarrollo local y contribución, consulta [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Límites de diseño
|
||||
|
||||
Truthmark es intencionadamente pequeño: local, versionado, con alcance de rama y revisable.
|
||||
|
||||
No es un servicio alojado, servidor MCP, base de datos vectorial, capa de memoria oculta, producto de aplicación de CI ni motor autónomo de reescritura de código. Ayuda a que la verdad del repositorio permanezca visible; no reemplaza pruebas, revisión de código ni juicio humano.
|
||||
**Instala Truthmark, selecciona tu host de programación y convierte hoy un comportamiento real en documentación.**
|
||||
|
||||
## Licencia
|
||||
|
||||
MIT. Consulta [LICENSE](../../LICENSE).
|
||||
|
||||
## Eliminación segura
|
||||
|
||||
Use `truthmark uninstall --dry-run` para revisar las superficies de host generadas exactas, luego `truthmark uninstall --apply` para eliminarlas. Los truth creados, la configuración, las plantillas, la salida de Portal, los archivos de Gemini y los archivos de usuario no relacionados se conservan; quite una instalación global de npm por separado con su gestor de paquetes.
|
||||
|
||||
+131
-156
@@ -2,219 +2,194 @@
|
||||
|
||||
**Vos agents écrivent du code. Truthmark maintient une documentation destinée aux humains et vérifiable dans Git.**
|
||||
|
||||
Truthmark installe des workflows natifs de Git qui permettent aux agents de codage IA de créer de nouveaux documents produit et d’ingénierie à partir du code et des tests existants, de les maintenir à jour après chaque changement de code et de vous remettre des diffs Markdown ordinaires à examiner.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Commencer](#démarrage-rapide-créez-votre-premier-document-de-vérité) · [Site web](https://merlinhu1.github.io/truthmark/) · [Guide d’utilisation](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Lire ce README en 16 langues</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Démarrage rapide : exécution locale en cinq minutes
|
||||
## Créez les premiers documents et gardez-les vrais
|
||||
|
||||
Exécutez ceci dans le dépôt Git que vous voulez faire gérer par Truthmark :
|
||||
La plupart des outils de documentation s’arrêtent après la génération. Truthmark offre aux agents un cycle de vie documentaire complet au sein de votre dépôt :
|
||||
|
||||
- **Créer de nouveaux documents à partir d’un logiciel fonctionnel.** Truth Document lit le code et les tests, puis crée une documentation produit ou d’ingénierie au périmètre clairement défini.
|
||||
- **Maintenir automatiquement l’alignement des documents.** Truth Sync s’exécute lors de la remise de l’agent après les changements de code fonctionnel et actualise la vérité du dépôt avant la fin du travail.
|
||||
- **Transformer les documents en code.** Truth Realize implémente les documents de vérité approuvés tout en préservant un workflow propre, axé d’abord sur la documentation.
|
||||
- **Réparer la propriété à mesure que le code grandit.** Truth Structure crée des routes au périmètre clair et des documents de démarrage pour les zones nouvelles ou surchargées.
|
||||
- **Tout examiner dans Git.** Le code, les décisions, les contrats, l’architecture, les opérations et le comportement voyagent ensemble avec la branche.
|
||||
|
||||
Aucune base de connaissances hébergée. Aucune mémoire d’agent privée. Aucune documentation prisonnière de l’historique des discussions.
|
||||
|
||||
## Démarrage rapide : créez votre premier document de vérité
|
||||
|
||||
**Prérequis :** Node.js 24 ou version ultérieure, un dépôt Git et un hôte de codage IA compatible avec les workflows d’agents.
|
||||
|
||||
Exécutez ces commandes dans le dépôt que Truthmark doit gérer :
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` vous permet de sélectionner Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor ou une configuration de l’interface en ligne de commande indépendante de l’hôte.
|
||||
|
||||
Demandez maintenant à votre agent configuré de documenter un comportement réel :
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document crée un nouveau document de vérité au périmètre clair s’il n’en existe pas, actualise le document propriétaire existant dans le cas contraire et met à jour le routage si nécessaire. Il ne modifie pas le code fonctionnel.
|
||||
|
||||
Examinez le résultat :
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
Dans un terminal interactif, `truthmark init` affiche une sélection multiple numérotée. Choisissez zéro ou plusieurs plateformes, ou `none` pour une installation neutre vis-à-vis des hôtes et limitée à la CLI.
|
||||
Vous devriez maintenant disposer de :
|
||||
|
||||
Pour les scripts et la CI, répétez `--platform` ; `--json` ne déclenche jamais d’invite :
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Les chemins exacts suivent la structure de propriété de votre dépôt. Les nouveaux fichiers apparaissent dans `git status` ; les modifications apportées aux fichiers suivis apparaissent dans `git diff`.
|
||||
|
||||
L’invocation varie selon l’hôte. OpenCode utilise `/skill truthmark-document`, Antigravity utilise `@truthmark-document`, et les autres hôtes compatibles utilisent leur surface native de skill ou de commande slash. Consultez le [tableau des plateformes](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) pour connaître les commandes exactes.
|
||||
|
||||
Pour les scripts et l’intégration continue, transmettez explicitement les plateformes sélectionnées :
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
Lors d’une première exécution non interactive sans `--platform`, l’installation reste neutre ; les exécutions suivantes conservent la sélection enregistrée dans `.truthmark/config.yml`.
|
||||
Choisissez `none` en mode interactif ou exécutez `truthmark init --clear-platforms` pour obtenir un dépôt indépendant de l’hôte. Vous pourrez ajouter des plateformes d’agents plus tard en relançant `truthmark init`.
|
||||
|
||||
Essayez maintenant le chemin d’adoption le plus courant : documenter, à partir du code et des tests, un comportement existant. Dans votre hôte de codage IA, demandez au workflow installé :
|
||||
Pour les diagnostics de fraîcheur relatifs à une branche, transmettez une base Git :
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Après cela, les utilisateurs ne devraient normalement pas invoquer Truth Sync directement. Continuez à coder dans votre hôte d’IA ; les instructions installées dans le dépôt indiquent à l’agent d’exécuter les tests pertinents et d’effectuer la revue Truth Sync avant la remise lorsqu’il y a des changements de code fonctionnel. Vous examinez le diff de code obtenu ainsi que le diff des documents de vérité.
|
||||
## Fonctionnement de Truthmark
|
||||
|
||||
Si vous voulez seulement la validation CLI, choisissez `none` puis exécutez `truthmark check` ; vous pourrez relancer `truthmark init` plus tard pour sélectionner des plateformes.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Fonctionnement de Truthmark" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 Le problème : l’écart de documentation avec l’IA
|
||||
L’interface en ligne de commande Truthmark installe et valide le contrat du dépôt. Votre agent de codage effectue l’examen des preuves et le travail documentaire via les workflows natifs de l’hôte qui ont été installés.
|
||||
|
||||
Les agents de codage IA sont incroyablement efficaces pour écrire du code rapidement. Mais cette vitesse crée un nouveau mode de défaillance dangereux : **le récit du dépôt s’éloigne de la réalité.**
|
||||
Un changement de code normal suit une boucle simple :
|
||||
|
||||
* Les comportements se perdent dans des historiques de discussion éphémères.
|
||||
* Les documents d’architecture deviennent vite obsolètes.
|
||||
* Les décisions produit disparaissent après la remise.
|
||||
* Les réviseurs de code se retrouvent face à des diffs de code bruts sans comprendre le « pourquoi ».
|
||||
* Chaque nouvelle session IA est contrainte de redécouvrir la vérité de votre dépôt depuis zéro.
|
||||
1. L’agent modifie le code fonctionnel.
|
||||
2. Les tests pertinents sont exécutés.
|
||||
3. Truth Sync vérifie la documentation mappée.
|
||||
4. Lorsque la vérité du dépôt a changé, l’agent crée ou actualise les documents et le routage.
|
||||
5. Vous examinez ensemble le diff de code et le diff de vérité.
|
||||
|
||||
## 🎯 La solution : Truthmark
|
||||
## Workflows
|
||||
|
||||
**Truthmark** installe dans votre dépôt une couche de workflow native Git. Il corrige la partie du développement avec l’IA qui casse généralement : aider la documentation à rester alignée sur le code.
|
||||
| Workflow | Quand l’utiliser | Résultat |
|
||||
| -------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| **Truth Document** | Du code existant doit être documenté | Crée ou actualise des documents produit et d’ingénierie fondés sur des preuves |
|
||||
| **Truth Sync** | Du code fonctionnel a changé | Maintient l’alignement des documents mappés et du routage avant la remise |
|
||||
| **Truth Structure** | Une nouvelle zone doit avoir un propriétaire ou les documents existants sont trop larges | Crée des routes au périmètre clair et des documents de démarrage sous forme de structure |
|
||||
| **Truth Realize** | Un document de vérité approuvé doit devenir un logiciel fonctionnel | Actualise le code fonctionnel à partir de la documentation |
|
||||
| **Truth Check** | La vérité du dépôt doit être auditée | Signale les problèmes de routage, de propriété, de preuves et de documentation |
|
||||
| **Truthmark Portal** | L’équipe veut un site documentaire consultable | Génère une présentation HTML statique commitée à partir des documents de vérité Markdown |
|
||||
|
||||
Au lieu d’espérer que les humains et les agents IA se souviennent de mettre les docs à jour, Truthmark transforme la documentation en habitude systématique et vérifiable directement dans votre dépôt.
|
||||
|
||||
### ✨ Pourquoi Truthmark est unique
|
||||
|
||||
Truthmark n’est pas simplement un autre outil de documentation. Il est profondément intégré au workflow IA :
|
||||
|
||||
* **🚫 Zéro dépendance fournisseur :** aucun service hébergé, aucune base de données cachée, aucun serveur supplémentaire à exploiter.
|
||||
* **🌳 100 % natif Git :** tout vit dans votre dépôt. La vérité se déplace avec votre branche.
|
||||
* **🤝 Contrat possédé par les humains, suivi par les agents :** Les mainteneurs possèdent le contrat du dépôt ; les agents suivent les instructions installées pendant qu’ils codent.
|
||||
* **✅ Confiance par la vérification :** le travail de l’IA devient plus facile à faire confiance, car tout travail qui change le comportement inclut une décision ou un diff de document de vérité vérifiable par un humain.
|
||||
|
||||
## 🔄 Fonctionnement
|
||||
|
||||
Lorsqu’un agent IA modifie votre code, le travail n’est pas terminé. Truthmark installe une garde de workflow de fin de tâche que les agents suivent avant la remise :
|
||||
|
||||
1. 💻 **Code :** l’agent modifie le code fonctionnel.
|
||||
2. 🧪 **Test :** les tests pertinents sont exécutés.
|
||||
3. 🔍 **Vérifier :** Truthmark vérifie la documentation mappée dans le cadre de la revue de fin installée.
|
||||
4. 📝 **Documentation :** les docs sont mises à jour par l’agent lorsque la vérité du dépôt a changé.
|
||||
5. 👀 **Revue :** un humain examine le *diff de code* + le *diff de vérité*.
|
||||
|
||||
## 🛠 Comment vous utilisez Truthmark
|
||||
|
||||
Truthmark fournit un contrat local au dépôt, avec deux façons de l’utiliser.
|
||||
|
||||
### Les humains installent et valident le contrat
|
||||
|
||||
Les mainteneurs et la CI utilisent la CLI :
|
||||
|
||||
* `truthmark init` - crée ou actualise la configuration, permet de choisir zéro ou plusieurs plateformes et installe le routage, les échafaudages de documents de vérité et les instructions des hôtes sélectionnés.
|
||||
* `truthmark check` - valide la vérité du dépôt depuis le terminal.
|
||||
|
||||
### Les agents suivent le contrat pendant qu’ils codent
|
||||
|
||||
Truthmark installe des instructions locales au dépôt pour les hôtes de codage IA pris en charge, comme Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity et Cursor.
|
||||
|
||||
La boucle normale est simple :
|
||||
|
||||
1. Demandez à votre agent de modifier du code ou de documenter un comportement existant.
|
||||
2. Les instructions installées indiquent à l’agent quand tester, quand mettre à jour les documents de vérité et quand s’arrêter pour une revue humaine.
|
||||
3. Vous relisez des diffs Git ordinaires : le code plus les éventuels changements de documents de vérité.
|
||||
|
||||
Les demandes agent lancées par l’utilisateur restent volontairement peu nombreuses :
|
||||
|
||||
* `/truthmark-document` - documente un comportement implémenté existant à partir du code et des tests.
|
||||
* `/truthmark-realize` - implémente le code à partir de documents de vérité existants.
|
||||
* `/truthmark-check` - audite la vérité du dépôt.
|
||||
|
||||
Truth Sync n’est pas la façon habituelle de commencer un travail ; c’est la revue de fin après des changements de code fonctionnel.
|
||||
Truth Structure n’est pas une commande quotidienne ; elle répare le routage ou la propriété uniquement lorsque cela bloque le travail.
|
||||
Truthmark installe ces workflows sous forme de surfaces natives au dépôt pour Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity et Cursor.
|
||||
|
||||
## Ce que vous obtenez
|
||||
|
||||
| Capacité | Ce qu’elle fait |
|
||||
| --- | --- |
|
||||
| Vérité native Git | Conserve la vérité du dépôt dans du Markdown et de la configuration commités. |
|
||||
| Documentation limitée à la branche | La vérité se déplace avec la branche au lieu de vivre dans une session privée. |
|
||||
| CLI humaine | Fournit aux mainteneurs des commandes de configuration, d’actualisation, de validation et d’inspection. |
|
||||
| Guidance agent installée | Indique aux agents de codage quand documenter, tester, synchroniser la vérité, auditer ou s’arrêter pour revue. |
|
||||
| Routage explicite | Mappe les zones de code vers des documents de vérité canoniques. |
|
||||
| Remises vérifiables | Produit des diffs Git ordinaires pour le code comme pour les documents de vérité. |
|
||||
| Fonctionnement local d’abord | Ne nécessite aucun service hébergé, démon, base de données ni serveur MCP. |
|
||||
| Limites d’écriture plus sûres | Sépare les workflows code-first, doc-first, read-only et doc-only. |
|
||||
| Validation | Signale les problèmes de routage, d’autorité, de frontmatter, de liens, de surfaces générées, de portée de branche, de fraîcheur et de couverture. |
|
||||
| Portal optionnel | Génère, lorsqu’il est explicitement activé et demandé, un site de présentation HTML statique commité à partir des documents de vérité Markdown. |
|
||||
### Une documentation qui part de la réalité
|
||||
|
||||
## Aperçu visuel
|
||||
Truthmark peut créer de la documentation pour les capacités produit, le comportement de l’implémentation, les interfaces de programmation d’applications, l’architecture, les workflows, les opérations et les tests. Le code et les tests fournissent les preuves ; des documents Markdown au périmètre clair préservent le résultat.
|
||||
|
||||
|
||||
### Une documentation qui survit au prochain changement
|
||||
|
||||
**Fonctionnalités :** ce que Truthmark installe et comment les agents utilisent les instructions locales au dépôt.
|
||||
Les routes relient les zones de code aux documents canoniques. Lorsque les agents modifient un comportement, Truth Sync sait où placer la vérité correspondante et maintient une remise vérifiable.
|
||||
|
||||
|
||||
### La vérité produit et la vérité d’ingénierie dans des voies distinctes
|
||||
|
||||
**Position :** où Truthmark se situe par rapport aux prompts, à la mémoire et aux workflows de spécification.
|
||||
La vérité produit consigne les promesses destinées aux utilisateurs, les limites, les décisions et les critères d’acceptation. La vérité d’ingénierie consigne le comportement actuel, les contrats, l’architecture, les workflows, les opérations et le comportement des tests.
|
||||
|
||||
|
||||
### Collaboration native de Git
|
||||
|
||||
**Flux de synchronisation :** comment Truth Sync conclut les changements de code ordinaires avant la remise.
|
||||
Tout ce qui compte réside dans des fichiers commités dans le dépôt. La vérité suit la branche, fonctionne avec les pull requests ordinaires et reste visible pour chaque mainteneur et chaque agent de codage.
|
||||
|
||||
## Pourquoi les équipes l’adoptent
|
||||
### Fonctionnement local d’abord
|
||||
|
||||
Truthmark s’adresse aux équipes qui savent déjà que les agents IA peuvent générer du code.
|
||||
Truthmark ne nécessite ni service hébergé, ni démon, ni base de données, ni magasin vectoriel, ni serveur Model Context Protocol. Le dépôt transporte son propre workflow documentaire.
|
||||
|
||||
Le prochain problème est la gouvernance.
|
||||
## La place de Truthmark
|
||||
|
||||
Pas la gouvernance comme cérémonie. La gouvernance comme une question simple :
|
||||
| Besoin | Meilleur choix |
|
||||
| ---------------------------------------------------------- | ------------------------- |
|
||||
| Obtenir un meilleur résultat d’une seule session d’agent | Meilleur prompt |
|
||||
| Continuité personnelle ou au niveau de la session | Outil de mémoire |
|
||||
| Travail fonctionnel axé d’abord sur la planification | Workflow de spécification |
|
||||
| Documentation limitée à la branche qui voyage avec le code | **Truthmark** |
|
||||
| Exactitude du comportement | Tests et revue de code |
|
||||
| Documentation assistée par l’IA et vérifiable | **Truthmark + revue Git** |
|
||||
|
||||
> Après ce changement assisté par l’IA, le dépôt dit-il encore la vérité ?
|
||||
Truthmark est conçu pour les mainteneurs et les équipes d’ingénierie qui utilisent déjà des agents de codage IA et veulent que le dépôt continue à dire la vérité aussi vite que le code évolue.
|
||||
|
||||
Truthmark aide les équipes à y répondre avec des fichiers commités, un routage explicite et des diffs vérifiables.
|
||||
## Hôtes compatibles et ligne de commande
|
||||
|
||||
Il est utile lorsque vous avez besoin de :
|
||||
Hôtes d’agents compatibles :
|
||||
|
||||
- moins de dérive documentaire
|
||||
- meilleures remises
|
||||
- vérité produit spécifique à la branche
|
||||
- documentation d’architecture et d’API durable
|
||||
- propriété explicite entre docs et code
|
||||
- limites d’écriture d’agents plus sûres
|
||||
- documentation vérifiable plutôt que mémoire cachée
|
||||
- une guidance agent qui fonctionne toujours depuis des fichiers commités dans le dépôt
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Où Truthmark se situe
|
||||
<details>
|
||||
<summary>Référence de la ligne de commande</summary>
|
||||
|
||||
Truthmark ne remplace pas les prompts, la mémoire, les spécifications, les tests ni la revue de code.
|
||||
| Commande | Objectif |
|
||||
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Créer ou actualiser la configuration, le routage, les modèles et les workflows des hôtes sélectionnés |
|
||||
| `truthmark check [--base <ref>]` | Valider la vérité du dépôt et, facultativement, exécuter les diagnostics de fraîcheur de la branche |
|
||||
| `truthmark index --json` | Examiner les métadonnées dérivées du dépôt et du routage |
|
||||
| `truthmark impact --base <ref> --json` | Mapper les fichiers modifiés vers les documents, les propriétaires et les tests proches |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Examiner l’applicabilité et les cibles du workflow |
|
||||
| `truthmark validate ...` | Valider les rapports de workflow et les baux d’écriture |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Prévisualiser ou supprimer les surfaces d’hôtes générées tout en préservant la vérité rédigée |
|
||||
|
||||
Il donne à ces workflows un endroit durable où atterrir dans Git.
|
||||
Une sortie JSON structurée est disponible dans toute l’interface en ligne de commande pour les scripts et l’intégration continue.
|
||||
|
||||
| Besoin | Meilleur choix |
|
||||
| --- | --- |
|
||||
| Meilleure sortie d’une session d’agent | Meilleur prompt |
|
||||
| Continuité personnelle ou au niveau de la session | Outil de mémoire |
|
||||
| Travail fonctionnel planifié d’abord | Workflow de spécification |
|
||||
| Vérité limitée à une branche qui voyage avec le code | Truthmark |
|
||||
| Validation de la correction du comportement | Tests et revue |
|
||||
| Revue de changements de documentation assistés par l’IA | Truthmark plus revue Git |
|
||||
</details>
|
||||
|
||||
Le périmètre de Truthmark est étroit par conception :
|
||||
## En savoir plus
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
installer une guidance agent autour d’elle
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- [Guide d’utilisation de Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Index de la documentation](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Vue d’ensemble de l’architecture](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Contrats de configuration, de routage et de commande](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Maintenir la vérité du dépôt](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Contribuer](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Aller plus loin
|
||||
|
||||
Le README est la vitrine : contexte rapide, démarrage rapide et modèle mental central.
|
||||
|
||||
Pour l’utilisation commande par commande, les comparaisons de surfaces, les détails des plateformes prises en charge, la configuration, le routage, Portal et des exemples, lisez le [guide d’utilisation Truthmark](../user-guide.md).
|
||||
|
||||
## État du projet
|
||||
|
||||
La version actuelle fournit :
|
||||
|
||||
- des commandes CLI locales pour init, check, index, impact et l’état des workflows
|
||||
- instructions agent locales au dépôt générées pour Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity et Cursor
|
||||
- des diagnostics de routage, d’autorité, de frontmatter, de liens, de fraîcheur, de surfaces générées, de portée de branche et de couverture
|
||||
- des documents de vérité limités à la branche et des artefacts dérivés d’intelligence du dépôt
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Guide d’utilisation](../user-guide.md)
|
||||
- [Index des docs](../README.md)
|
||||
- [Vue d’ensemble de l’architecture](../truthmark/engineering/architecture/overview.md)
|
||||
- [Contrats API et CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Guide de maintenance de la vérité du dépôt](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Pour les commandes de développement local et de contribution, consultez [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Limites de conception
|
||||
|
||||
Truthmark est volontairement petit : local, commité, limité à la branche et vérifiable.
|
||||
|
||||
Ce n’est pas un service hébergé, un serveur MCP, une base de données vectorielle, une couche de mémoire cachée, un produit d’application CI ni un moteur autonome de réécriture de code. Il aide la vérité du dépôt à rester visible ; il ne remplace pas les tests, la revue de code ni le jugement humain.
|
||||
**Installez Truthmark, sélectionnez votre hôte de codage et transformez dès aujourd’hui un comportement réel en documentation.**
|
||||
|
||||
## Licence
|
||||
|
||||
MIT. Voir [LICENSE](../../LICENSE).
|
||||
|
||||
## Suppression sûre
|
||||
|
||||
Utilisez `truthmark uninstall --dry-run` pour examiner précisément les surfaces hôtes générées, puis `truthmark uninstall --apply` pour les supprimer. Les truth rédigées, la configuration, les templates, la sortie Portal, les fichiers Gemini et les fichiers utilisateur non liés sont conservés ; supprimez séparément une installation npm globale avec votre gestionnaire de paquets.
|
||||
|
||||
+132
-157
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**Agen Anda menulis kode. Truthmark memelihara dokumentasi yang ditujukan untuk manusia dan dapat ditinjau melalui Git.**
|
||||
**Agen Anda menulis kode. Truthmark menjaga dokumentasi yang ditujukan untuk manusia dan siap ditinjau di Git.**
|
||||
|
||||
Truthmark memasang alur kerja native Git yang memungkinkan agen pengodean AI membuat dokumentasi produk dan rekayasa baru dari kode serta pengujian yang sudah ada, menjaganya tetap mutakhir setelah setiap perubahan kode, dan memberikan diff Markdown biasa untuk Anda tinjau.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Mulai](#mulai-cepat-buat-dokumen-truth-pertama-anda) · [Situs web](https://merlinhu1.github.io/truthmark/) · [Panduan pengguna](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Baca README ini dalam salah satu dari 16 bahasa</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Mulai cepat: berjalan lokal dalam lima menit
|
||||
## Buat dokumentasi pertama. Jaga agar tetap benar.
|
||||
|
||||
Jalankan ini di dalam repositori Git yang ingin Anda kelola dengan Truthmark:
|
||||
Sebagian besar alat dokumentasi berhenti setelah pembuatan. Truthmark memberi agen siklus hidup dokumentasi lengkap di dalam repositori Anda:
|
||||
|
||||
- **Buat dokumentasi baru dari perangkat lunak yang berfungsi.** Truth Document membaca kode dan pengujian, lalu membuat dokumentasi produk atau rekayasa dengan cakupan yang jelas.
|
||||
- **Jaga dokumentasi tetap selaras secara otomatis.** Truth Sync berjalan saat serah terima agen setelah perubahan kode fungsional dan memperbarui kebenaran repositori sebelum pekerjaan dinyatakan selesai.
|
||||
- **Ubah dokumentasi kembali menjadi kode.** Truth Realize mengimplementasikan dokumen truth yang disetujui sambil mempertahankan alur kerja doc-first yang rapi.
|
||||
- **Perbaiki kepemilikan seiring pertumbuhan basis kode.** Truth Structure membuat rute dengan cakupan jelas dan dokumen awal untuk area baru atau yang terlalu luas.
|
||||
- **Tinjau semuanya di Git.** Kode, keputusan, kontrak, arsitektur, operasi, dan perilaku bergerak bersama branch.
|
||||
|
||||
Tanpa basis pengetahuan ter-host. Tanpa memori agen privat. Tanpa dokumentasi yang terjebak dalam riwayat chat.
|
||||
|
||||
## Mulai cepat: buat dokumen truth pertama Anda
|
||||
|
||||
**Persyaratan:** Node.js 24 atau yang lebih baru, repositori Git, dan host pengodean AI yang didukung untuk alur kerja agen.
|
||||
|
||||
Jalankan perintah berikut di dalam repositori yang ingin Anda kelola dengan Truthmark:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` memungkinkan Anda memilih Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor, atau penyiapan antarmuka baris perintah yang netral terhadap host.
|
||||
|
||||
Sekarang minta agen yang telah dikonfigurasi untuk mendokumentasikan satu perilaku nyata:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document membuat dokumen truth baru dengan cakupan jelas jika belum ada, memperbarui pemilik yang sudah ada jika tersedia, dan memperbarui perutean bila diperlukan. Alur ini tidak mengubah kode fungsional.
|
||||
|
||||
Tinjau hasilnya:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
Di terminal interaktif, `truthmark init` menampilkan pilihan ganda bernomor. Pilih nol atau lebih platform, atau masukkan `none` untuk penyiapan netral terhadap host yang hanya memakai CLI.
|
||||
Sekarang Anda akan memiliki:
|
||||
|
||||
Untuk skrip dan CI, ulangi `--platform`; `--json` tidak pernah menampilkan prompt:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Path yang tepat mengikuti struktur kepemilikan repositori Anda. File baru muncul di `git status`; perubahan pada file yang dilacak muncul di `git diff`.
|
||||
|
||||
Cara pemanggilan berbeda menurut host. OpenCode menggunakan `/skill truthmark-document`, Antigravity menggunakan `@truthmark-document`, dan host lain yang didukung menggunakan permukaan skill atau perintah garis miring native masing-masing. Lihat [tabel platform](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) untuk perintah yang tepat.
|
||||
|
||||
Untuk skrip dan integrasi berkelanjutan, berikan platform yang dipilih secara eksplisit:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
Pada proses noninteraktif pertama tanpa `--platform`, penyiapan tetap netral terhadap host; proses berikutnya mempertahankan pilihan yang tersimpan di `.truthmark/config.yml`.
|
||||
Pilih `none` secara interaktif atau jalankan `truthmark init --clear-platforms` untuk repositori yang netral terhadap host. Anda dapat menambahkan platform agen nanti dengan menjalankan ulang `truthmark init`.
|
||||
|
||||
Sekarang coba jalur adopsi yang paling umum: dokumentasikan satu perilaku yang sudah ada dari kode dan pengujian. Di host pengodean AI Anda, minta alur kerja yang terpasang:
|
||||
Untuk diagnostik kesegaran relatif terhadap branch, berikan basis Git:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Setelah itu, pengguna biasanya tidak perlu memanggil Truth Sync secara langsung. Teruslah membuat kode melalui host AI Anda; instruksi repositori yang terpasang memberi tahu agen untuk menjalankan pengujian yang relevan dan melakukan tinjauan Truth Sync sebelum serah terima ketika kode fungsional berubah. Anda meninjau diff kode yang dihasilkan beserta diff dokumen truth.
|
||||
## Cara kerja Truthmark
|
||||
|
||||
Jika Anda hanya menginginkan validasi CLI, pilih `none` lalu jalankan `truthmark check`; Anda dapat menjalankan ulang `truthmark init` nanti untuk memilih platform.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Cara kerja Truthmark" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 Masalah: kesenjangan dokumentasi AI
|
||||
Antarmuka baris perintah Truthmark memasang dan memvalidasi kontrak repositori. Agen pengodean Anda melakukan peninjauan bukti dan pekerjaan dokumentasi melalui alur kerja native host yang telah terpasang.
|
||||
|
||||
Agen pengodean AI luar biasa dalam menulis kode dengan cepat. Namun kecepatan ini menciptakan mode kegagalan baru yang berbahaya: **cerita repositori menyimpang dari kenyataan.**
|
||||
Perubahan kode normal mengikuti satu putaran sederhana:
|
||||
|
||||
* Perilaku hilang dalam riwayat chat yang sementara.
|
||||
* Dokumen arsitektur cepat tertinggal.
|
||||
* Keputusan produk lenyap setelah serah terima.
|
||||
* Peninjau kode dibiarkan memeriksa diff kode mentah tanpa memahami "mengapa".
|
||||
* Setiap sesi AI baru dipaksa menemukan ulang kebenaran repositori Anda dari awal.
|
||||
1. Agen mengubah kode fungsional.
|
||||
2. Pengujian yang relevan dijalankan.
|
||||
3. Truth Sync memeriksa dokumentasi yang dipetakan.
|
||||
4. Agen membuat atau memperbarui dokumentasi dan perutean saat kebenaran repositori berubah.
|
||||
5. Anda meninjau diff kode dan diff truth secara bersamaan.
|
||||
|
||||
## 🎯 Solusi: Truthmark
|
||||
## Alur kerja
|
||||
|
||||
**Truthmark** memasang lapisan alur kerja native Git ke dalam repositori Anda. Ini memperbaiki bagian pengembangan AI yang biasanya rusak: membantu dokumentasi tetap selaras dengan kode.
|
||||
| Alur kerja | Gunakan saat | Hasil |
|
||||
| -------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| **Truth Document** | Kode yang sudah ada memerlukan dokumentasi | Membuat atau memperbarui dokumentasi produk dan rekayasa berbasis bukti |
|
||||
| **Truth Sync** | Kode fungsional berubah | Menjaga dokumentasi yang dipetakan dan perutean tetap selaras sebelum serah terima |
|
||||
| **Truth Structure** | Area baru memerlukan kepemilikan atau dokumentasi yang ada terlalu luas | Membuat rute dengan cakupan jelas dan kerangka dokumen awal |
|
||||
| **Truth Realize** | Dokumen truth yang disetujui harus menjadi perangkat lunak yang berfungsi | Memperbarui kode fungsional dari dokumentasi |
|
||||
| **Truth Check** | Kebenaran repositori perlu diaudit | Melaporkan masalah perutean, kepemilikan, bukti, dan dokumentasi |
|
||||
| **Truthmark Portal** | Tim menginginkan situs dokumentasi yang mudah dijelajahi | Menghasilkan presentasi HTML statis yang di-commit dari dokumen truth Markdown |
|
||||
|
||||
Alih-alih berharap manusia dan agen AI ingat memperbarui dokumen, Truthmark menjadikan dokumentasi sebagai kebiasaan sistematis dan dapat ditinjau langsung di dalam repositori Anda.
|
||||
|
||||
### ✨ Mengapa Truthmark unik
|
||||
|
||||
Truthmark bukan sekadar alat dokumentasi lain. Ia terintegrasi mendalam ke dalam alur kerja AI:
|
||||
|
||||
* **🚫 Tanpa ketergantungan vendor:** Tidak ada layanan ter-host, tidak ada basis data tersembunyi, tidak ada server tambahan untuk dioperasikan.
|
||||
* **🌳 100% native Git:** Semuanya hidup di repositori Anda. Kebenaran bergerak bersama branch Anda.
|
||||
* **🤝 Kontrak yang dimiliki manusia dan diikuti agen:** Pemelihara memiliki kontrak repositori; agen mengikuti instruksi yang terpasang saat membuat kode.
|
||||
* **✅ Kepercayaan melalui verifikasi:** Pekerjaan AI menjadi lebih mudah dipercaya karena pekerjaan yang mengubah perilaku menyertakan keputusan atau diff dokumen kebenaran yang dapat ditinjau manusia.
|
||||
|
||||
## 🔄 Cara kerjanya
|
||||
|
||||
Ketika agen AI memodifikasi kode Anda, pekerjaannya belum selesai. Truthmark memasang penjaga alur kerja saat penyelesaian yang diikuti agen sebelum serah terima:
|
||||
|
||||
1. 💻 **Kode:** Agen memodifikasi kode fungsional.
|
||||
2. 🧪 **Uji:** Pengujian yang relevan dijalankan.
|
||||
3. 🔍 **Periksa:** Truthmark memeriksa dokumentasi yang dipetakan sebagai bagian dari tinjauan akhir yang terpasang.
|
||||
4. 📝 **Dokumentasikan:** Dokumen diperbarui oleh agen ketika kebenaran repositori berubah.
|
||||
5. 👀 **Tinjau:** Manusia meninjau *diff kode* + *diff kebenaran*.
|
||||
|
||||
## 🛠 Cara Anda berinteraksi dengan Truthmark
|
||||
|
||||
Truthmark memiliki satu kontrak lokal repositori dengan dua cara pemakaian.
|
||||
|
||||
### Manusia memasang dan memvalidasi kontrak
|
||||
|
||||
Pemelihara dan CI menggunakan CLI:
|
||||
|
||||
* `truthmark init` - membuat atau menyegarkan konfigurasi, memilih nol atau lebih platform, lalu memasang perutean, scaffold dokumen kebenaran, dan instruksi untuk host AI yang dipilih.
|
||||
* `truthmark check` - memvalidasi kebenaran repositori dari terminal.
|
||||
|
||||
### Agen mengikuti kontrak saat membuat kode
|
||||
|
||||
Truthmark memasang instruksi lokal repositori untuk host pengodean AI yang didukung seperti Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, dan Cursor.
|
||||
|
||||
Alur normalnya sederhana:
|
||||
|
||||
1. Minta agen Anda melakukan perubahan kode, atau minta ia mendokumentasikan perilaku yang sudah ada.
|
||||
2. Instruksi yang terpasang memberi tahu agen kapan harus menguji, kapan memperbarui dokumen kebenaran, dan kapan berhenti untuk tinjauan manusia.
|
||||
3. Anda meninjau diff Git biasa: kode plus perubahan dokumen kebenaran apa pun.
|
||||
|
||||
Permintaan agen yang dimulai pengguna sengaja dibuat sedikit:
|
||||
|
||||
* `/truthmark-document` - mendokumentasikan perilaku terimplementasi yang sudah ada dari kode dan pengujian.
|
||||
* `/truthmark-realize` - mengimplementasikan kode dari dokumen kebenaran yang sudah ada.
|
||||
* `/truthmark-check` - mengaudit kebenaran repositori.
|
||||
|
||||
Truth Sync bukan cara biasa untuk memulai pekerjaan; itu adalah tinjauan akhir setelah perubahan kode fungsional.
|
||||
Truth Structure bukan perintah harian; ia memperbaiki perutean atau kepemilikan hanya ketika hal itu memblokir pekerjaan.
|
||||
Truthmark memasang alur kerja ini sebagai permukaan repositori native untuk Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, dan Cursor.
|
||||
|
||||
## Yang Anda dapatkan
|
||||
|
||||
| Kapabilitas | Apa yang dilakukan |
|
||||
| --- | --- |
|
||||
| Kebenaran native Git | Menyimpan kebenaran repositori dalam Markdown dan konfigurasi yang di-commit. |
|
||||
| Dokumentasi berlingkup branch | Kebenaran bergerak bersama branch alih-alih hidup dalam sesi privat. |
|
||||
| CLI manusia | Memberi pemelihara perintah penyiapan, penyegaran, validasi, dan inspeksi. |
|
||||
| Kontrak agen terpasang | Memberi agen panduan native host untuk dokumentasi, realisasi, audit, sinkronisasi akhir, dan perbaikan perutean terbatas. |
|
||||
| Perutean eksplisit | Memetakan area kode ke dokumen kebenaran kanonis. |
|
||||
| Serah terima yang dapat ditinjau | Menghasilkan diff Git biasa untuk kode maupun dokumen kebenaran. |
|
||||
| Operasi lokal terlebih dahulu | Tidak membutuhkan layanan ter-host, daemon, basis data, atau server MCP. |
|
||||
| Batas tulis yang lebih aman | Memisahkan alur kerja code-first, doc-first, read-only, dan doc-only. |
|
||||
| Validasi | Melaporkan masalah perutean, otoritas, frontmatter, tautan, permukaan yang dihasilkan, cakupan branch, kesegaran, dan coverage. |
|
||||
| Portal opsional | Menghasilkan situs presentasi HTML statis yang di-commit dari dokumen kebenaran Markdown ketika diaktifkan dan diminta secara eksplisit. |
|
||||
### Dokumentasi yang berawal dari kenyataan
|
||||
|
||||
## Gambaran visual
|
||||
Truthmark dapat membuat dokumentasi untuk kapabilitas produk, perilaku implementasi, antarmuka pemrograman aplikasi, arsitektur, alur kerja, operasi, dan pengujian. Kode dan pengujian menyediakan bukti; dokumen Markdown dengan cakupan jelas mempertahankan hasilnya.
|
||||
|
||||
|
||||
### Dokumentasi yang bertahan melewati perubahan berikutnya
|
||||
|
||||
**Fitur:** apa yang dipasang Truthmark dan bagaimana permukaan alur kerja dibagi.
|
||||
Rute menghubungkan area kode ke dokumen kanonis. Saat agen mengubah perilaku, Truth Sync mengetahui tempat kebenaran terkait harus berada dan menjaga serah terima tetap dapat ditinjau.
|
||||
|
||||
|
||||
### Kebenaran produk dan rekayasa di jalur terpisah
|
||||
|
||||
**Posisi:** di mana Truthmark berada relatif terhadap prompt, memori, dan alur kerja spesifikasi.
|
||||
Kebenaran produk merekam janji kepada pengguna, batasan, keputusan, dan kriteria penerimaan. Kebenaran rekayasa merekam perilaku saat ini, kontrak, arsitektur, alur kerja, operasi, dan perilaku pengujian.
|
||||
|
||||
|
||||
### Kolaborasi native Git
|
||||
|
||||
**Alur sinkronisasi:** bagaimana Truth Sync menutup perubahan kode normal sebelum serah terima.
|
||||
Semua yang penting berada dalam file repositori yang di-commit. Kebenaran mengikuti branch, bekerja dengan pull request biasa, dan tetap terlihat oleh setiap pemelihara serta agen pengodean.
|
||||
|
||||
## Mengapa tim mengadopsinya
|
||||
### Operasi yang mengutamakan lokal
|
||||
|
||||
Truthmark ditujukan untuk tim yang sudah tahu bahwa agen AI dapat menghasilkan kode.
|
||||
Truthmark tidak memerlukan layanan ter-host, daemon, basis data, penyimpanan vektor, atau server Model Context Protocol. Repositori membawa alur kerja dokumentasinya sendiri.
|
||||
|
||||
Masalah berikutnya adalah tata kelola.
|
||||
## Posisi Truthmark
|
||||
|
||||
Bukan tata kelola sebagai seremoni. Tata kelola sebagai pertanyaan sederhana:
|
||||
| Kebutuhan | Pilihan terbaik |
|
||||
| ------------------------------------------------- | ---------------------------- |
|
||||
| Output yang lebih baik dari satu sesi agen | Prompt yang lebih baik |
|
||||
| Kontinuitas pribadi atau tingkat sesi | Alat memori |
|
||||
| Pekerjaan fitur yang dimulai dengan perencanaan | Alur kerja spesifikasi |
|
||||
| Dokumentasi berlingkup branch yang mengikuti kode | **Truthmark** |
|
||||
| Kebenaran perilaku | Pengujian dan tinjauan kode |
|
||||
| Dokumentasi berbantuan AI yang dapat ditinjau | **Truthmark + tinjauan Git** |
|
||||
|
||||
> Setelah perubahan berbantuan AI ini, apakah repositori masih mengatakan kebenaran?
|
||||
Truthmark dibuat untuk pemelihara dan tim rekayasa yang sudah menggunakan agen pengodean AI dan ingin repositori terus menyampaikan kebenaran secepat kode berubah.
|
||||
|
||||
Truthmark membantu tim menjawabnya dengan file yang di-commit, perutean eksplisit, dan diff yang dapat ditinjau.
|
||||
## Host yang didukung dan baris perintah
|
||||
|
||||
Ini berguna saat Anda membutuhkan:
|
||||
Host agen yang didukung:
|
||||
|
||||
- penyimpangan dokumentasi yang lebih kecil
|
||||
- serah terima yang lebih baik
|
||||
- kebenaran produk khusus branch
|
||||
- dokumentasi arsitektur dan API yang tahan lama
|
||||
- kepemilikan eksplisit antara dokumen dan kode
|
||||
- batas tulis agen yang lebih aman
|
||||
- dokumentasi yang dapat ditinjau alih-alih memori tersembunyi
|
||||
- alur kerja AI yang tetap bekerja dari file repositori yang di-commit
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Di mana Truthmark cocok
|
||||
<details>
|
||||
<summary>Referensi baris perintah</summary>
|
||||
|
||||
Truthmark tidak menggantikan prompt, memori, spesifikasi, pengujian, atau tinjauan kode.
|
||||
| Perintah | Tujuan |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Membuat atau menyegarkan konfigurasi, perutean, template, dan alur kerja host yang dipilih |
|
||||
| `truthmark check [--base <ref>]` | Memvalidasi kebenaran repositori dan secara opsional menjalankan diagnostik kesegaran branch |
|
||||
| `truthmark index --json` | Memeriksa metadata turunan repositori dan perutean |
|
||||
| `truthmark impact --base <ref> --json` | Memetakan file yang berubah ke dokumentasi, pemilik, dan pengujian terdekat |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Memeriksa penerapan dan target alur kerja |
|
||||
| `truthmark validate ...` | Memvalidasi laporan alur kerja dan sewa penulisan |
|
||||
| `truthmark uninstall --dry-run\|--apply` | Meninjau atau menghapus permukaan host yang dihasilkan sambil mempertahankan truth yang ditulis pengguna |
|
||||
|
||||
Ia memberi alur kerja tersebut tempat yang tahan lama untuk mendarat di Git.
|
||||
Output JSON terstruktur tersedia di seluruh antarmuka baris perintah untuk skrip dan integrasi berkelanjutan.
|
||||
|
||||
| Kebutuhan | Lebih cocok |
|
||||
| --- | --- |
|
||||
| Output lebih baik dari satu sesi agen | Prompt yang lebih baik |
|
||||
| Kontinuitas pribadi atau tingkat sesi | Alat memori |
|
||||
| Pekerjaan fitur yang dimulai dengan rencana | Alur kerja spesifikasi |
|
||||
| Truth berlingkup branch yang ikut bersama kode | Truthmark |
|
||||
| Memvalidasi kebenaran perilaku | Pengujian dan tinjauan |
|
||||
| Meninjau perubahan dokumentasi berbantuan AI | Truthmark plus tinjauan Git |
|
||||
</details>
|
||||
|
||||
Jalur Truthmark sengaja dirancang sempit:
|
||||
## Pelajari lebih lanjut
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
memasang panduan agen di sekelilingnya
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- [Panduan pengguna Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Indeks dokumentasi](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Ikhtisar arsitektur](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Kontrak konfigurasi, perutean, dan perintah](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Memelihara kebenaran repositori](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Berkontribusi](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Pelajari lebih dalam
|
||||
|
||||
README adalah etalase: konteks cepat, mulai cepat, dan model mental inti.
|
||||
|
||||
Untuk penggunaan per perintah, perbandingan permukaan, detail platform yang didukung, konfigurasi, perutean, Portal, dan contoh, baca [Panduan Pengguna Truthmark](../user-guide.md).
|
||||
|
||||
## Status proyek
|
||||
|
||||
Rilis saat ini menyediakan:
|
||||
|
||||
- perintah CLI lokal untuk init, check, index, impact, dan status alur kerja
|
||||
- instruksi agen lokal repositori yang dihasilkan untuk Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, dan Cursor
|
||||
- diagnostik perutean, otoritas, frontmatter, tautan, kesegaran, permukaan yang dihasilkan, cakupan branch, dan coverage
|
||||
- dokumen kebenaran berlingkup branch dan artefak kecerdasan repositori turunan
|
||||
|
||||
## Dokumentasi
|
||||
|
||||
- [Panduan pengguna](../user-guide.md)
|
||||
- [Indeks dokumen](../README.md)
|
||||
- [Ikhtisar arsitektur](../truthmark/engineering/architecture/overview.md)
|
||||
- [Kontrak API dan CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Panduan pemeliharaan kebenaran repositori](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Untuk perintah pengembangan lokal dan kontribusi, lihat [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Batas desain
|
||||
|
||||
Truthmark sengaja kecil: lokal, di-commit, berlingkup branch, dan dapat ditinjau.
|
||||
|
||||
Ini bukan layanan ter-host, server MCP, basis data vektor, lapisan memori tersembunyi, produk penegakan CI, atau mesin penulisan ulang kode otonom. Ini membantu kebenaran repositori tetap terlihat; tidak menggantikan pengujian, tinjauan kode, atau penilaian manusia.
|
||||
**Pasang Truthmark, pilih host pengodean Anda, dan ubah satu perilaku nyata menjadi dokumentasi hari ini.**
|
||||
|
||||
## Lisensi
|
||||
|
||||
MIT. Lihat [LICENSE](../../LICENSE).
|
||||
|
||||
## Penghapusan aman
|
||||
|
||||
Gunakan `truthmark uninstall --dry-run` untuk meninjau permukaan host yang tepat dihasilkan, lalu `truthmark uninstall --apply` untuk menghapusnya. Truth hasil penulisan, konfigurasi, template, keluaran Portal, berkas Gemini, dan berkas pengguna yang tidak terkait akan tetap dipertahankan; hapus instalasi npm global secara terpisah melalui pengelola paket Anda.
|
||||
|
||||
+131
-156
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**I tuoi agenti scrivono codice. Truthmark mantiene documentazione pensata per le persone e revisionabile in Git.**
|
||||
**I tuoi agenti scrivono codice. Truthmark mantiene la documentazione pensata per le persone e revisionabile in Git.**
|
||||
|
||||
Truthmark installa workflow nativi di Git che permettono agli agenti di coding IA di creare nuova documentazione di prodotto e ingegneria a partire dal codice e dai test esistenti, mantenerla aggiornata dopo ogni modifica al codice e consegnarti normali diff Markdown da revisionare.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Inizia](#avvio-rapido-crea-il-tuo-primo-documento-di-verità) · [Sito web](https://merlinhu1.github.io/truthmark/) · [Guida utente](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Leggi questo README in 16 lingue</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Avvio rapido: eseguirlo localmente in cinque minuti
|
||||
## Crea i primi documenti. Mantienili fedeli alla realtà.
|
||||
|
||||
Esegui questo comando nel repository Git che vuoi far gestire a Truthmark:
|
||||
La maggior parte degli strumenti di documentazione si ferma dopo la generazione. Truthmark offre agli agenti un ciclo di vita completo della documentazione all’interno del tuo repository:
|
||||
|
||||
- **Crea nuova documentazione da software funzionante.** Truth Document legge codice e test, quindi crea documentazione di prodotto o ingegneria con un perimetro definito.
|
||||
- **Mantieni la documentazione allineata automaticamente.** Truth Sync viene eseguito al passaggio di consegne dell’agente dopo modifiche funzionali al codice e aggiorna la verità del repository prima che il lavoro sia concluso.
|
||||
- **Trasforma nuovamente la documentazione in codice.** Truth Realize implementa documenti di verità approvati mantenendo un workflow pulito che parte dalla documentazione.
|
||||
- **Ripristina la proprietà man mano che la codebase cresce.** Truth Structure crea percorsi delimitati e documenti iniziali per aree nuove o sovraccariche.
|
||||
- **Revisiona tutto in Git.** Codice, decisioni, contratti, architettura, operazioni e comportamento viaggiano insieme al branch.
|
||||
|
||||
Nessuna knowledge base ospitata. Nessuna memoria privata degli agenti. Nessuna documentazione intrappolata nella cronologia delle chat.
|
||||
|
||||
## Avvio rapido: crea il tuo primo documento di verità
|
||||
|
||||
**Requisiti:** Node.js 24 o versione successiva, un repository Git e un host di coding IA supportato per i workflow degli agenti.
|
||||
|
||||
Esegui quanto segue nel repository che vuoi far gestire a Truthmark:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` permette di selezionare Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor oppure una configurazione dell’interfaccia a riga di comando neutrale rispetto all’host.
|
||||
|
||||
Ora chiedi all’agente configurato di documentare un comportamento reale:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document crea un nuovo documento di verità delimitato quando non ne esiste uno, aggiorna il documento proprietario esistente quando è presente e aggiorna il routing quando necessario. Non modifica il codice funzionale.
|
||||
|
||||
Revisiona il risultato:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
In un terminale interattivo, `truthmark init` mostra una selezione multipla numerata. Scegli zero o più piattaforme, oppure `none` per una configurazione neutrale rispetto all’host e solo CLI.
|
||||
Ora dovresti avere:
|
||||
|
||||
Per script e CI, ripeti `--platform`; `--json` non mostra mai prompt:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
I percorsi esatti seguono la struttura di proprietà del tuo repository. I nuovi file compaiono in `git status`; le modifiche ai file tracciati compaiono in `git diff`.
|
||||
|
||||
La modalità di invocazione varia in base all’host. OpenCode usa `/skill truthmark-document`, Antigravity usa `@truthmark-document` e gli altri host supportati utilizzano la propria interfaccia nativa per skill o comandi slash. Consulta la [tabella delle piattaforme](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) per i comandi esatti.
|
||||
|
||||
Per script e integrazione continua, passa esplicitamente le piattaforme selezionate:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
Alla prima esecuzione non interattiva senza `--platform`, la configurazione resta neutrale; le esecuzioni successive mantengono la selezione salvata in `.truthmark/config.yml`.
|
||||
Scegli `none` in modalità interattiva oppure esegui `truthmark init --clear-platforms` per ottenere un repository neutrale rispetto all’host. Puoi aggiungere piattaforme per agenti in seguito rieseguendo `truthmark init`.
|
||||
|
||||
Ora prova il percorso di adozione più comune: documentare un comportamento esistente a partire da codice e test. Nel tuo host di coding IA, chiedi al workflow installato:
|
||||
Per la diagnostica di aggiornamento relativa al branch, passa una base Git:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Dopo questo, di norma gli utenti non dovrebbero invocare Truth Sync direttamente. Continua a scrivere codice tramite il tuo host IA; le istruzioni installate nel repository dicono all’agente di eseguire i test pertinenti e svolgere la revisione Truth Sync prima della consegna quando cambiano parti di codice funzionale. Tu revisioni il diff di codice risultante insieme al diff dei documenti di verità.
|
||||
## Come funziona Truthmark
|
||||
|
||||
Se vuoi solo la validazione CLI, scegli `none` e continua con `truthmark check`; potrai rieseguire `truthmark init` in seguito per selezionare le piattaforme.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Come funziona Truthmark" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 Il problema: il divario di documentazione dell’IA
|
||||
L’interfaccia a riga di comando di Truthmark installa e convalida il contratto del repository. Il tuo agente di coding esegue la revisione delle evidenze e il lavoro di documentazione attraverso i workflow nativi dell’host installati.
|
||||
|
||||
Gli agenti di coding IA sono straordinari nello scrivere codice rapidamente. Ma questa velocità crea una nuova modalità di errore pericolosa: **la storia del repository si allontana dalla realtà.**
|
||||
Una normale modifica al codice segue un ciclo semplice:
|
||||
|
||||
* Il comportamento si perde in cronologie chat effimere.
|
||||
* I documenti di architettura restano rapidamente indietro.
|
||||
* Le decisioni di prodotto scompaiono dopo la consegna.
|
||||
* I revisori del codice si ritrovano a esaminare diff di codice grezzi senza capire il “perché”.
|
||||
* Ogni nuova sessione IA è costretta a riscoprire da zero la verità del repository.
|
||||
1. L’agente modifica il codice funzionale.
|
||||
2. Vengono eseguiti i test pertinenti.
|
||||
3. Truth Sync controlla la documentazione mappata.
|
||||
4. L’agente crea o aggiorna documentazione e routing quando cambia la verità del repository.
|
||||
5. Revisioni insieme il diff del codice e il diff della verità.
|
||||
|
||||
## 🎯 La soluzione: Truthmark
|
||||
## Workflow
|
||||
|
||||
**Truthmark** installa nel tuo repository un livello di workflow nativo di Git. Risolve la parte dello sviluppo con IA che di solito si rompe: aiutare la documentazione a restare allineata al codice.
|
||||
| Workflow | Quando usarlo | Risultato |
|
||||
| -------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
||||
| **Truth Document** | Il codice esistente ha bisogno di documentazione | Crea o aggiorna documentazione di prodotto e ingegneria basata su evidenze |
|
||||
| **Truth Sync** | Il codice funzionale è cambiato | Mantiene allineati la documentazione mappata e il routing prima della consegna |
|
||||
| **Truth Structure** | Una nuova area ha bisogno di proprietà o la documentazione esistente è troppo ampia | Crea percorsi delimitati e strutture iniziali per i documenti |
|
||||
| **Truth Realize** | Un documento di verità approvato deve diventare software funzionante | Aggiorna il codice funzionale a partire dalla documentazione |
|
||||
| **Truth Check** | La verità del repository deve essere sottoposta ad audit | Segnala problemi di routing, proprietà, evidenze e documentazione |
|
||||
| **Truthmark Portal** | Il team desidera un sito di documentazione navigabile | Genera una presentazione HTML statica e versionata dai documenti di verità Markdown |
|
||||
|
||||
Invece di sperare che persone e agenti IA si ricordino di aggiornare la documentazione, Truthmark rende la documentazione un’abitudine sistematica e revisionabile direttamente nel repository.
|
||||
|
||||
### ✨ Perché Truthmark è unico
|
||||
|
||||
Truthmark non è semplicemente un altro strumento di documentazione. È profondamente integrato nel workflow IA:
|
||||
|
||||
* **🚫 Nessun lock-in del fornitore:** nessun servizio ospitato, nessun database nascosto, nessun server aggiuntivo da gestire.
|
||||
* **🌳 100% nativo di Git:** tutto vive nel tuo repository. La verità si muove con il tuo branch.
|
||||
* **🤝 Contratto posseduto dagli umani e seguito dagli agenti:** I maintainer possiedono il contratto del repository; gli agenti seguono le istruzioni installate mentre scrivono codice.
|
||||
* **✅ Fiducia tramite verifica:** il lavoro dell’IA diventa più facile da fidare perché il lavoro che cambia comportamento include una decisione o un diff di documento di verità revisionabile da una persona.
|
||||
|
||||
## 🔄 Come funziona
|
||||
|
||||
Quando un agente IA modifica il tuo codice, il lavoro non è finito. Truthmark installa una protezione di workflow a fine attività che gli agenti seguono prima della consegna:
|
||||
|
||||
1. 💻 **Codice:** l’agente modifica codice funzionale.
|
||||
2. 🧪 **Test:** vengono eseguiti i test pertinenti.
|
||||
3. 🔍 **Controllo:** Truthmark controlla la documentazione mappata come parte della revisione finale installata.
|
||||
4. 📝 **Documentazione:** i docs vengono aggiornati dall’agente quando la verità del repository è cambiata.
|
||||
5. 👀 **Revisione:** una persona revisiona il *diff di codice* + il *diff di verità*.
|
||||
|
||||
## 🛠 Come interagisci con Truthmark
|
||||
|
||||
Truthmark ha un contratto locale al repository e due modi per usarlo.
|
||||
|
||||
### Gli esseri umani installano e validano il contratto
|
||||
|
||||
Maintainer e CI usano la CLI:
|
||||
|
||||
* `truthmark init` - crea o aggiorna la configurazione, consente di scegliere zero o più piattaforme e installa routing, scaffold dei documenti di verità e istruzioni per gli host selezionati.
|
||||
* `truthmark check` - valida la verità del repository dal terminale.
|
||||
|
||||
### Gli agenti seguono il contratto mentre scrivono codice
|
||||
|
||||
Truthmark installa istruzioni locali al repository per host di coding IA supportati come Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor.
|
||||
|
||||
Il ciclo normale è semplice:
|
||||
|
||||
1. Chiedi al tuo agente una modifica al codice o di documentare un comportamento esistente.
|
||||
2. Le istruzioni installate dicono all’agente quando testare, quando aggiornare i documenti di verità e quando fermarsi per la revisione umana.
|
||||
3. Tu revisioni normali diff Git: codice più eventuali modifiche ai documenti di verità.
|
||||
|
||||
Le richieste agente avviate dall’utente sono intenzionalmente poche:
|
||||
|
||||
* `/truthmark-document` - documenta comportamento implementato esistente da codice e test.
|
||||
* `/truthmark-realize` - implementa codice da documenti di verità esistenti.
|
||||
* `/truthmark-check` - audita la verità del repository.
|
||||
|
||||
Truth Sync non è il modo abituale per iniziare il lavoro; è la revisione finale dopo modifiche funzionali al codice.
|
||||
Truth Structure non è un comando quotidiano; ripara routing o ownership solo quando ciò blocca il lavoro.
|
||||
Truthmark installa questi workflow come superfici native del repository per Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor.
|
||||
|
||||
## Cosa ottieni
|
||||
|
||||
| Capacità | Cosa fa |
|
||||
| --- | --- |
|
||||
| Verità nativa di Git | Mantiene la verità del repository in Markdown e configurazione committati. |
|
||||
| Documentazione con ambito di branch | La verità si muove con il branch invece di vivere in una sessione privata. |
|
||||
| CLI umana | Offre ai maintainer comandi di setup, aggiornamento, validazione e ispezione. |
|
||||
| Guida agente installata | Dice agli agenti di coding quando documentare, testare, sincronizzare la verità, auditare o fermarsi per revisione. |
|
||||
| Routing esplicito | Mappa aree di codice a documenti di verità canonici. |
|
||||
| Consegne revisionabili | Produce normali diff Git sia per il codice sia per i documenti di verità. |
|
||||
| Operatività local-first | Non richiede servizi ospitati, daemon, database o server MCP. |
|
||||
| Confini di scrittura più sicuri | Separa workflow code-first, doc-first, read-only e doc-only. |
|
||||
| Validazione | Segnala problemi di routing, autorità, frontmatter, link, superfici generate, ambito di branch, freschezza e copertura. |
|
||||
| Portal opzionale | Genera, quando esplicitamente abilitato e richiesto, un sito statico HTML committato a partire da documenti di verità Markdown. |
|
||||
### Documentazione che parte dalla realtà
|
||||
|
||||
## Panoramica visiva
|
||||
Truthmark può creare documentazione per funzionalità di prodotto, comportamento dell’implementazione, interfacce di programmazione delle applicazioni, architettura, workflow, operazioni e test. Codice e test forniscono le evidenze; documenti Markdown delimitati conservano il risultato.
|
||||
|
||||
|
||||
### Documentazione che supera il cambiamento successivo
|
||||
|
||||
**Funzionalità:** cosa installa Truthmark e come è divisa la superficie di workflow.
|
||||
I percorsi collegano le aree di codice ai documenti canonici. Quando gli agenti modificano il comportamento, Truth Sync sa dove deve risiedere la verità corrispondente e mantiene la consegna revisionabile.
|
||||
|
||||
|
||||
### Verità di prodotto e ingegneria su percorsi separati
|
||||
|
||||
**Posizione:** dove Truthmark si colloca rispetto a prompt, memoria e workflow di specifica.
|
||||
La verità di prodotto raccoglie promesse rivolte agli utenti, limiti, decisioni e criteri di accettazione. La verità di ingegneria raccoglie comportamento corrente, contratti, architettura, workflow, operazioni e comportamento dei test.
|
||||
|
||||
|
||||
### Collaborazione nativa di Git
|
||||
|
||||
**Flusso di sincronizzazione:** come Truth Sync conclude le normali modifiche di codice prima della consegna.
|
||||
Tutto ciò che conta risiede in file versionati del repository. La verità segue il branch, funziona con normali pull request e rimane visibile a ogni maintainer e agente di coding.
|
||||
|
||||
## Perché i team lo adottano
|
||||
### Operatività local-first
|
||||
|
||||
Truthmark è per team che sanno già che gli agenti IA possono generare codice.
|
||||
|
||||
Il problema successivo è la governance.
|
||||
|
||||
Non governance come cerimonia. Governance come una semplice domanda:
|
||||
|
||||
> Dopo questa modifica assistita dall’IA, il repository dice ancora la verità?
|
||||
|
||||
Truthmark aiuta i team a rispondere con file committati, routing esplicito e diff revisionabili.
|
||||
|
||||
È utile quando hai bisogno di:
|
||||
|
||||
- meno deriva della documentazione
|
||||
- consegne migliori
|
||||
- verità di prodotto specifica per branch
|
||||
- documentazione durevole di architettura e API
|
||||
- ownership esplicita tra docs e codice
|
||||
- confini di scrittura degli agenti più sicuri
|
||||
- documentazione revisionabile invece di memoria nascosta
|
||||
- guida agente che funziona ancora da file committati nel repository
|
||||
Truthmark non richiede servizi ospitati, daemon, database, archivi vettoriali o server Model Context Protocol. Il repository contiene il proprio workflow di documentazione.
|
||||
|
||||
## Dove si colloca Truthmark
|
||||
|
||||
Truthmark non sostituisce prompt, memoria, specifiche, test o code review.
|
||||
| Esigenza | Soluzione migliore |
|
||||
| ------------------------------------------------------------- | ----------------------------- |
|
||||
| Output migliore da una sessione di agente | Un prompt migliore |
|
||||
| Continuità personale o a livello di sessione | Uno strumento di memoria |
|
||||
| Sviluppo di funzionalità che parte da un piano | Un workflow di specifica |
|
||||
| Documentazione con ambito di branch che viaggia con il codice | **Truthmark** |
|
||||
| Correttezza del comportamento | Test e code review |
|
||||
| Documentazione assistita dall’IA e revisionabile | **Truthmark + revisione Git** |
|
||||
|
||||
Offre a questi workflow un luogo durevole in cui atterrare in Git.
|
||||
Truthmark è progettato per maintainer e team di ingegneria che usano già agenti di coding IA e vogliono che il repository continui a dire la verità con la stessa rapidità con cui cambia il codice.
|
||||
|
||||
| Esigenza | Scelta migliore |
|
||||
| --- | --- |
|
||||
| Output migliore da una sessione di agente | Prompt migliore |
|
||||
| Continuità personale o a livello di sessione | Strumento di memoria |
|
||||
| Lavoro su funzionalità guidato prima da un piano | Workflow di specifica |
|
||||
| Verità con ambito di branch che viaggia con il codice | Truthmark |
|
||||
| Validare la correttezza del comportamento | Test e revisione |
|
||||
| Revisionare modifiche di documentazione assistite dall’IA | Truthmark più revisione Git |
|
||||
## Host supportati e riga di comando
|
||||
|
||||
La corsia di Truthmark è stretta per progettazione:
|
||||
Host per agenti supportati:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
installare guida agente intorno a essa
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Approfondisci
|
||||
<details>
|
||||
<summary>Riferimento della riga di comando</summary>
|
||||
|
||||
Il README è la vetrina: contesto rapido, avvio rapido e il modello mentale centrale.
|
||||
| Comando | Scopo |
|
||||
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Crea o aggiorna configurazione, routing, template e workflow degli host selezionati |
|
||||
| `truthmark check [--base <ref>]` | Convalida la verità del repository e, facoltativamente, esegue la diagnostica di aggiornamento del branch |
|
||||
| `truthmark index --json` | Ispeziona i metadati derivati del repository e del routing |
|
||||
| `truthmark impact --base <ref> --json` | Mappa i file modificati su documenti, proprietari e test vicini |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Ispeziona applicabilità e obiettivi del workflow |
|
||||
| `truthmark validate ...` | Convalida i report dei workflow e le concessioni di scrittura |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Mostra in anteprima o rimuove le superfici host generate preservando la verità creata |
|
||||
|
||||
Per l’uso comando per comando, confronti tra superfici, dettagli sulle piattaforme supportate, configurazione, routing, Portal ed esempi, leggi la [guida utente di Truthmark](../user-guide.md).
|
||||
L’output JSON strutturato è disponibile in tutta l’interfaccia a riga di comando per script e integrazione continua.
|
||||
|
||||
## Stato del progetto
|
||||
</details>
|
||||
|
||||
La release attuale fornisce:
|
||||
## Scopri di più
|
||||
|
||||
- comandi CLI locali per init, check, index, impact e stato dei workflow
|
||||
- istruzioni agente locali al repository generate per Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor
|
||||
- diagnostica su routing, autorità, frontmatter, link, freschezza, superfici generate, ambito di branch e copertura
|
||||
- documenti di verità con ambito di branch e artefatti derivati di intelligence del repository
|
||||
- [Guida utente di Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Indice della documentazione](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Panoramica dell’architettura](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Contratti di configurazione, routing e comandi](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Manutenzione della verità del repository](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Contribuire](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Documentazione
|
||||
|
||||
- [Guida utente](../user-guide.md)
|
||||
- [Indice docs](../README.md)
|
||||
- [Panoramica dell’architettura](../truthmark/engineering/architecture/overview.md)
|
||||
- [Contratti API e CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Guida alla manutenzione della verità del repository](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Per i comandi di sviluppo locale e contribuzione, vedi [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Confini di progettazione
|
||||
|
||||
Truthmark è intenzionalmente piccolo: locale, committato, con ambito di branch e revisionabile.
|
||||
|
||||
Non è un servizio ospitato, un server MCP, un database vettoriale, un livello di memoria nascosto, un prodotto di enforcement CI o un motore autonomo di riscrittura del codice. Aiuta la verità del repository a restare visibile; non sostituisce test, code review o giudizio umano.
|
||||
**Installa Truthmark, seleziona il tuo host di coding e trasforma oggi stesso un comportamento reale in documentazione.**
|
||||
|
||||
## Licenza
|
||||
|
||||
MIT. Vedi [LICENSE](../../LICENSE).
|
||||
|
||||
## Rimozione sicura
|
||||
|
||||
Usa `truthmark uninstall --dry-run` per rivedere le superfici host generate con precisione, quindi `truthmark uninstall --apply` per rimuoverle. I truth creati, la configurazione, i template, l’output di Portal, i file Gemini e i file utente non correlati vengono preservati; rimuovi separatamente un’installazione npm globale con il tuo gestore pacchetti.
|
||||
|
||||
+132
-157
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**あなたのエージェントはコードを書きます。Truthmark は、人間向けで Git 上でレビュー可能なドキュメントを維持します。**
|
||||
**あなたのエージェントはコードを書きます。Truthmark は、人が読み、Git でレビューできるドキュメントを維持します。**
|
||||
|
||||
Truthmark は Git ネイティブなワークフローをインストールし、AI コーディングエージェントが既存のコードとテストから新しいプロダクトおよびエンジニアリングドキュメントを作成し、コードが変更されるたびに最新の状態を保ち、通常の Markdown diff としてレビューできるようにします。
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[今すぐ始める](#クイックスタート最初の-truth-ドキュメントを作成する) · [ウェブサイト](https://merlinhu1.github.io/truthmark/) · [ユーザーガイド](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>この README を 16 言語で読む</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 クイックスタート：5 分でローカル実行
|
||||
## 最初のドキュメントを作り、常に真実に保つ
|
||||
|
||||
Truthmark に管理させたい Git リポジトリ内でこれを実行します：
|
||||
多くのドキュメントツールは生成した時点で役目を終えます。Truthmark は、リポジトリ内でエージェントに完全なドキュメントライフサイクルを提供します。
|
||||
|
||||
- **動作するソフトウェアから新しいドキュメントを作成。** Truth Document がコードとテストを読み、範囲の明確なプロダクトまたはエンジニアリングドキュメントを作成します。
|
||||
- **ドキュメントを自動的に整合。** 機能コードの変更後、Truth Sync がエージェントの引き渡し時に実行され、作業完了前にリポジトリの事実を更新します。
|
||||
- **ドキュメントをコードに戻す。** Truth Realize が承認済みの truth ドキュメントを実装し、明快なドキュメントファーストのワークフローを維持します。
|
||||
- **コードベースの成長に合わせて所有範囲を修復。** Truth Structure が、新しい領域や肥大化した領域に、範囲の明確なルートと初期ドキュメントを作成します。
|
||||
- **すべてを Git でレビュー。** コード、意思決定、契約、アーキテクチャ、運用、振る舞いがブランチと一緒に移動します。
|
||||
|
||||
ホスト型ナレッジベースは不要。非公開のエージェントメモリも不要。チャット履歴に閉じ込められるドキュメントもありません。
|
||||
|
||||
## クイックスタート：最初の Truth ドキュメントを作成する
|
||||
|
||||
**要件：** Node.js 24 以降、Git リポジトリ、エージェントワークフローに対応する AI コーディングホスト。
|
||||
|
||||
Truthmark に管理させたいリポジトリ内で実行します。
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` では、Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor、またはホストに依存しないコマンドラインインターフェース設定を選択できます。
|
||||
|
||||
次に、設定済みのエージェントへ、実際の振る舞いを 1 つドキュメント化するよう依頼します。
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
対応するドキュメントがなければ、Truth Document は範囲の明確な truth ドキュメントを新規作成します。既存の所有ドキュメントがあれば更新し、必要に応じてルーティングも更新します。機能コードは変更しません。
|
||||
|
||||
結果をレビューします。
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
対話型ターミナルでは、`truthmark init` が番号付きの複数選択を表示します。0 個以上のプラットフォームを選ぶか、`none` を入力してホスト非依存の CLI 専用セットアップにします。
|
||||
これで、次のファイルが作成されているはずです。
|
||||
|
||||
スクリプトや CI では `--platform` を繰り返します。`--json` は決してプロンプトを表示しません：
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
正確なパスは、リポジトリの所有構造に従います。新規ファイルは `git status` に表示され、追跡済みファイルへの変更は `git diff` に表示されます。
|
||||
|
||||
呼び出し方法はホストによって異なります。OpenCode は `/skill truthmark-document`、Antigravity は `@truthmark-document`、その他の対応ホストは各ホスト固有のスキルまたはスラッシュコマンドを使用します。正確なコマンドは[プラットフォーム表](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms)を参照してください。
|
||||
|
||||
スクリプトと継続的インテグレーションでは、選択するプラットフォームを明示的に渡します。
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
初回の非対話実行で `--platform` がなければホスト非依存のままです。以後の実行では `.truthmark/config.yml` に保存済みの選択を維持します。
|
||||
対話形式で `none` を選択するか、`truthmark init --clear-platforms` を実行すると、ホストに依存しないリポジトリになります。後から `truthmark init` を再実行して、エージェントプラットフォームを追加できます。
|
||||
|
||||
次に、最も一般的な導入パスを試します。コードとテストから既存の振る舞いを 1 つドキュメント化します。AI コーディングホストで、インストール済みワークフローに依頼してください：
|
||||
ブランチを基準とした鮮度診断には、Git のベースを渡します。
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
その後、通常ユーザーが Truth Sync を直接呼び出す必要はありません。AI ホストを通じてコーディングを続けてください。インストールされたリポジトリ指示が、機能コードの変更時に関連テストを実行し、引き渡し前に Truth Sync レビューを行うようエージェントに伝えます。あなたは結果のコード diff と truth-doc diff をレビューします。
|
||||
## Truthmark の仕組み
|
||||
|
||||
CLI 検証だけが必要なら `none` を選び、`truthmark check` を実行してください。後から `truthmark init` を再実行してプラットフォームを選択できます。
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Truthmark の仕組み" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 問題：AI ドキュメントギャップ
|
||||
Truthmark のコマンドラインインターフェースがリポジトリ契約をインストールして検証します。コーディングエージェントは、インストール済みのホストネイティブなワークフローを通じて、証拠の確認とドキュメント作業を実行します。
|
||||
|
||||
AI コーディングエージェントは、コードを高速に書くことに非常に優れています。しかしその速度は、危険な新しい失敗モードを生みます：**リポジトリの物語が現実からずれていく**ことです。
|
||||
通常のコード変更は、次のシンプルなループに従います。
|
||||
|
||||
* 振る舞いが一時的なチャット履歴の中に失われます。
|
||||
* アーキテクチャ文書はすぐに遅れます。
|
||||
* プロダクト上の決定は引き渡し後に消えます。
|
||||
* コードレビュー担当者は「なぜ」を理解できないまま生のコード diff を見ることになります。
|
||||
* 新しい AI セッションのたびに、リポジトリの truth を一から再発見しなければなりません。
|
||||
1. エージェントが機能コードを変更します。
|
||||
2. 関連するテストを実行します。
|
||||
3. Truth Sync が対応付けられたドキュメントを確認します。
|
||||
4. リポジトリの事実が変わった場合、エージェントがドキュメントとルーティングを作成または更新します。
|
||||
5. コード diff と truth diff を一緒にレビューします。
|
||||
|
||||
## 🎯 解決策：Truthmark
|
||||
## ワークフロー
|
||||
|
||||
**Truthmark** は、Git ネイティブなワークフロー層をリポジトリにインストールします。AI 開発で通常壊れやすい部分、つまりドキュメントをコードと整合させ続けることを修復します。
|
||||
| ワークフロー | 使用する場面 | 結果 |
|
||||
| -------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
|
||||
| **Truth Document** | 既存のコードにドキュメントが必要 | 証拠に基づくプロダクトおよびエンジニアリングドキュメントを作成または更新 |
|
||||
| **Truth Sync** | 機能コードが変更された | 引き渡し前に、対応付けられたドキュメントとルーティングを整合 |
|
||||
| **Truth Structure** | 新しい領域に所有範囲が必要、または既存ドキュメントの範囲が広すぎる | 範囲の明確なルートと骨組みとなる初期ドキュメントを作成 |
|
||||
| **Truth Realize** | 承認済みの truth ドキュメントを動作するソフトウェアにする | ドキュメントに基づいて機能コードを更新 |
|
||||
| **Truth Check** | リポジトリの事実を監査する必要がある | ルーティング、所有範囲、証拠、ドキュメントの問題を報告 |
|
||||
| **Truthmark Portal** | チームが閲覧可能なドキュメントサイトを必要としている | Markdown の truth ドキュメントから、コミットされる静的 HTML プレゼンテーションを生成 |
|
||||
|
||||
人間や AI エージェントがドキュメント更新を忘れないことに期待するのではなく、Truthmark はドキュメントを体系的でレビュー可能な習慣としてリポジトリ内に組み込みます。
|
||||
|
||||
### ✨ Truthmark が独自である理由
|
||||
|
||||
Truthmark は単なる別のドキュメントツールではありません。AI ワークフローに深く統合されています：
|
||||
|
||||
* **🚫 ベンダーロックインなし：** ホステッドサービスも、隠れたデータベースも、運用すべき追加サーバーもありません。
|
||||
* **🌳 100% Git ネイティブ：** すべてがリポジトリ内にあります。truth はブランチと一緒に移動します。
|
||||
* **🤝 人間が所有し、エージェントが従う契約:** メンテナーがリポジトリ契約を所有し、エージェントはコーディング中にインストール済み指示に従います。
|
||||
* **✅ 検証による信頼：** 振る舞いを変える作業には、人間がレビューできる truth-doc の判断または diff が含まれるため、AI の作業を信頼しやすくなります。
|
||||
|
||||
## 🔄 仕組み
|
||||
|
||||
AI エージェントがコードを変更しても、仕事はまだ終わりではありません。Truthmark は、引き渡し前にエージェントが従う完了時ワークフローガードをインストールします：
|
||||
|
||||
1. 💻 **コード：** エージェントが機能コードを変更します。
|
||||
2. 🧪 **テスト：** 関連テストを実行します。
|
||||
3. 🔍 **チェック:** Truthmark は、インストール済みの終了時レビューの一部として、対応するドキュメントを確認します。
|
||||
4. 📝 **ドキュメント化：** リポジトリの truth が変わった場合、エージェントがドキュメントを更新します。
|
||||
5. 👀 **レビュー：** 人間が*コード diff* + *truth diff*をレビューします。
|
||||
|
||||
## 🛠 Truthmark との関わり方
|
||||
|
||||
Truthmark には、リポジトリローカルな契約が 1 つあり、それを使う方法が 2 つあります。
|
||||
|
||||
### 人間が契約をインストールして検証する
|
||||
|
||||
メンテナーと CI は CLI を使います:
|
||||
|
||||
* `truthmark init` - 設定を作成または更新し、0 個以上のプラットフォームを選択して、ルーティング、truth-doc の足場、選択した AI ホスト向け指示をインストールします。
|
||||
* `truthmark check` - ターミナルからリポジトリ truth を検証します。
|
||||
|
||||
### エージェントはコーディング中に契約に従う
|
||||
|
||||
Truthmark は、Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor などの対応 AI コーディングホスト向けに、リポジトリローカルな指示をインストールします。
|
||||
|
||||
通常の流れは単純です:
|
||||
|
||||
1. エージェントにコード変更を依頼するか、既存の振る舞いの文書化を依頼します。
|
||||
2. インストール済みの指示が、いつテストし、いつ truth docs を更新し、いつ人間レビューのために止まるかをエージェントに伝えます。
|
||||
3. あなたは通常の Git diff をレビューします。コードと、必要なら truth-doc の変更です。
|
||||
|
||||
ユーザーが開始するエージェント依頼は意図的に少なくしています:
|
||||
|
||||
* `/truthmark-document` - コードとテストから既存の実装済み振る舞いを文書化します。
|
||||
* `/truthmark-realize` - 既存の truth docs からコードを実装します。
|
||||
* `/truthmark-check` - リポジトリ truth を監査します。
|
||||
|
||||
Truth Sync は作業を始める通常の方法ではありません。機能コード変更後の終了時レビューです。
|
||||
Truth Structure は日常コマンドではありません。作業をブロックしている場合にだけ、ルーティングや所有者情報を修復します。
|
||||
Truthmark は、Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor 向けのネイティブなリポジトリサーフェスとして、これらのワークフローをインストールします。
|
||||
|
||||
## 得られるもの
|
||||
|
||||
| 機能 | 内容 |
|
||||
| --- | --- |
|
||||
| Git ネイティブな truth | リポジトリの truth をコミット済み Markdown と設定に保持します。 |
|
||||
| ブランチ単位のドキュメント | truth はプライベートセッションではなく、ブランチと一緒に移動します。 |
|
||||
| 人間向け CLI | メンテナーにセットアップ、更新、検証、確認のコマンドを提供します。 |
|
||||
| インストール済みエージェント契約 | ドキュメント化、実現、監査、終了時 sync、限定的なルーティング修復のためのホストネイティブなガイダンスをエージェントに提供します。 |
|
||||
| 明示的なルーティング | コード領域を正規の truth ドキュメントに対応付けます。 |
|
||||
| レビュー可能な引き渡し | コードと truth ドキュメントの両方について通常の Git diff を生成します。 |
|
||||
| ローカルファースト運用 | ホステッドサービス、デーモン、データベース、MCP サーバーを必要としません。 |
|
||||
| より安全な書き込み境界 | コードファースト、ドキュメントファースト、読み取り専用、ドキュメント専用のワークフローを分離します。 |
|
||||
| 検証 | ルーティング、権限、frontmatter、リンク、生成サーフェス、ブランチスコープ、鮮度、カバレッジの問題を報告します。 |
|
||||
| 任意の Portal | 明示的に有効化され要求された場合、Markdown truth ドキュメントからコミット済みの静的 HTML プレゼンテーションサイトを生成します。 |
|
||||
### 現実から始まるドキュメント
|
||||
|
||||
## ビジュアル概要
|
||||
Truthmark は、プロダクト機能、実装の振る舞い、アプリケーションプログラミングインターフェース、アーキテクチャ、ワークフロー、運用、テストのドキュメントを作成できます。コードとテストが証拠を提供し、範囲の明確な Markdown ドキュメントが結果を保持します。
|
||||
|
||||
|
||||
### 次の変更にも耐えるドキュメント
|
||||
|
||||
**機能：** Truthmark が何をインストールし、ワークフローサーフェスがどのように分割されるか。
|
||||
ルートがコード領域と正規ドキュメントを結び付けます。エージェントが振る舞いを変更すると、Truth Sync は対応する事実の格納先を把握し、引き渡しをレビュー可能な状態に保ちます。
|
||||
|
||||
|
||||
### プロダクトの事実とエンジニアリングの事実を別レーンで管理
|
||||
|
||||
**位置づけ：** Truthmark がプロンプト、メモリ、仕様ワークフローに対してどこに位置するか。
|
||||
プロダクトの事実は、ユーザー向けの約束、境界、意思決定、受け入れ基準を記録します。エンジニアリングの事実は、現在の振る舞い、契約、アーキテクチャ、ワークフロー、運用、テストの振る舞いを記録します。
|
||||
|
||||
|
||||
### Git ネイティブなコラボレーション
|
||||
|
||||
**同期フロー：** Truth Sync が通常のコード変更を引き渡し前にどのように締めくくるか。
|
||||
重要なものはすべて、コミットされたリポジトリファイルに存在します。事実はブランチに従い、通常のプルリクエストで機能し、すべてのメンテナーとコーディングエージェントから確認できます。
|
||||
|
||||
## チームが採用する理由
|
||||
### ローカルファーストの運用
|
||||
|
||||
Truthmark は、AI エージェントがコードを生成できることをすでに理解しているチームのためのものです。
|
||||
Truthmark に、ホスト型サービス、デーモン、データベース、ベクトルストア、Model Context Protocol サーバーは不要です。リポジトリ自体がドキュメントワークフローを保持します。
|
||||
|
||||
次の問題はガバナンスです。
|
||||
## Truthmark が適する領域
|
||||
|
||||
儀式としてのガバナンスではありません。ガバナンスとは、単純な問いです：
|
||||
| ニーズ | 最適な選択肢 |
|
||||
| -------------------------------------------------- | ---------------------------- |
|
||||
| 1 回のエージェントセッションからより良い出力を得る | より良いプロンプト |
|
||||
| 個人またはセッション単位の継続性 | メモリツール |
|
||||
| 計画優先の機能開発 | 仕様ワークフロー |
|
||||
| コードと一緒に移動するブランチ単位のドキュメント | **Truthmark** |
|
||||
| 振る舞いの正しさ | テストとコードレビュー |
|
||||
| レビュー可能な AI 支援ドキュメント | **Truthmark + Git レビュー** |
|
||||
|
||||
> この AI 支援の変更後も、リポジトリはまだ真実を伝えているか？
|
||||
Truthmark は、すでに AI コーディングエージェントを利用し、コードの変化と同じ速さでリポジトリが真実を伝え続けることを求めるメンテナーとエンジニアリングチームのために作られています。
|
||||
|
||||
Truthmark は、コミット済みファイル、明示的なルーティング、レビュー可能な diff によって、チームがこの問いに答えるのを助けます。
|
||||
## 対応ホストとコマンドライン
|
||||
|
||||
次のようなものが必要なときに有用です：
|
||||
対応するエージェントホスト：
|
||||
|
||||
- ドキュメントのずれを減らす
|
||||
- より良い引き渡し
|
||||
- ブランチ固有のプロダクト truth
|
||||
- 長持ちするアーキテクチャおよび API ドキュメント
|
||||
- ドキュメントとコードの間の明示的な所有関係
|
||||
- より安全なエージェントの書き込み境界
|
||||
- 隠れたメモリではなく、レビュー可能なドキュメント
|
||||
- コミット済みリポジトリファイルから引き続き動作する AI ワークフロー
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Truthmark の適用範囲
|
||||
<details>
|
||||
<summary>コマンドラインリファレンス</summary>
|
||||
|
||||
Truthmark は、プロンプト、メモリ、仕様、テスト、コードレビューを置き換えません。
|
||||
| コマンド | 目的 |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| `truthmark init` | 設定、ルーティング、テンプレート、選択したホストのワークフローを作成または更新 |
|
||||
| `truthmark check [--base <ref>]` | リポジトリの事実を検証し、必要に応じてブランチの鮮度診断を実行 |
|
||||
| `truthmark index --json` | 導出されたリポジトリおよびルーティングのメタデータを確認 |
|
||||
| `truthmark impact --base <ref> --json` | 変更されたファイルをドキュメント、所有者、近隣のテストに対応付け |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | ワークフローの適用可否と対象を確認 |
|
||||
| `truthmark validate ...` | ワークフローレポートと書き込みリースを検証 |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | 作成済みの事実を保持したまま、生成されたホストサーフェスをプレビューまたは削除 |
|
||||
|
||||
それらのワークフローが Git に永続的に着地する場所を提供します。
|
||||
スクリプトと継続的インテグレーション向けに、コマンドラインインターフェース全体で構造化 JSON 出力を利用できます。
|
||||
|
||||
| ニーズ | より適したもの |
|
||||
| --- | --- |
|
||||
| 1 回のエージェントセッションからより良い出力を得る | より良いプロンプト |
|
||||
| 個人またはセッション単位の継続性 | メモリツール |
|
||||
| 計画ファーストの機能開発 | 仕様ワークフロー |
|
||||
| コードと一緒に移動するブランチ単位の truth | Truthmark |
|
||||
| 振る舞いの正しさを検証する | テストとレビュー |
|
||||
| AI 支援によるドキュメント変更をレビューする | Truthmark と Git レビュー |
|
||||
</details>
|
||||
|
||||
Truthmark のレーンは意図的に狭く設計されています：
|
||||
## 詳細情報
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
その周囲にエージェント指示をインストールする
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- [Truthmark ユーザーガイド](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [ドキュメント索引](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [アーキテクチャ概要](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [設定、ルーティング、コマンドの契約](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [リポジトリの事実を維持する](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [コントリビューション](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## さらに詳しく
|
||||
|
||||
README は店頭のようなものです。素早い文脈、クイックスタート、核となるメンタルモデルを提供します。
|
||||
|
||||
コマンドごとの使い方、サーフェス比較、対応プラットフォームの詳細、設定、ルーティング、Portal、例については、[Truthmark ユーザーガイド](../user-guide.md)を読んでください。
|
||||
|
||||
## プロジェクトの状態
|
||||
|
||||
現在のリリースは次を提供します：
|
||||
|
||||
- init、check、index、impact、workflow status のためのローカル CLI コマンド
|
||||
- Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor 向けに生成されるリポジトリローカルなエージェント指示
|
||||
- ルーティング、権限、frontmatter、リンク、鮮度、生成サーフェス、ブランチスコープ、カバレッジの診断
|
||||
- ブランチ単位の truth ドキュメントと、派生したリポジトリインテリジェンス成果物
|
||||
|
||||
## ドキュメント
|
||||
|
||||
- [ユーザーガイド](../user-guide.md)
|
||||
- [ドキュメント索引](../README.md)
|
||||
- [アーキテクチャ概要](../truthmark/engineering/architecture/overview.md)
|
||||
- [API と CLI の契約](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [リポジトリ truth メンテナンスガイド](../standards/maintaining-repository-truth.md)
|
||||
|
||||
ローカル開発とコントリビューション用コマンドについては、[CONTRIBUTING.md](../../CONTRIBUTING.md)を参照してください。
|
||||
|
||||
## 設計上の境界
|
||||
|
||||
Truthmark は意図的に小さく保たれています：ローカル、コミット済み、ブランチ単位、レビュー可能。
|
||||
|
||||
これはホステッドサービス、MCP サーバー、ベクトルデータベース、隠れたメモリ層、CI 強制製品、自律的なコード書き換えエンジンではありません。リポジトリの truth を見える状態に保つのを助けますが、テスト、コードレビュー、人間の判断を置き換えるものではありません。
|
||||
**Truthmark をインストールし、コーディングホストを選び、今日から実際の振る舞いをドキュメントに変えましょう。**
|
||||
|
||||
## ライセンス
|
||||
|
||||
MIT。[LICENSE](../../LICENSE) を参照してください。
|
||||
|
||||
## 安全な削除
|
||||
|
||||
`truthmark uninstall --dry-run` を使用して正確に生成されたホストサーフェスを確認し、次に `truthmark uninstall --apply` でそれらを削除します。作成した truth、設定、テンプレート、Portal の出力、Gemini ファイル、関連のないユーザーファイルは保持されます。npm のグローバルインストールはパッケージマネージャーで別途削除してください。
|
||||
|
||||
+133
-158
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**당신의 에이전트는 코드를 작성합니다. Truthmark는 사람이 읽고 Git에서 검토할 수 있는 문서를 유지합니다.**
|
||||
**에이전트는 코드를 작성합니다. Truthmark는 사람이 읽고 Git에서 검토할 수 있는 문서를 유지합니다.**
|
||||
|
||||
Truthmark는 Git 네이티브 워크플로를 설치하여 AI 코딩 에이전트가 기존 코드와 테스트에서 새로운 제품 및 엔지니어링 문서를 만들고, 코드가 변경될 때마다 최신 상태로 유지하며, 일반적인 Markdown diff로 검토할 수 있게 합니다.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[시작하기](#빠른-시작-첫-truth-문서-만들기) · [웹사이트](https://merlinhu1.github.io/truthmark/) · [사용자 가이드](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>16개 언어로 이 README 읽기</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 빠른 시작: 5분 안에 로컬에서 실행하기
|
||||
## 첫 문서를 만들고, 언제나 진실하게 유지하세요
|
||||
|
||||
Truthmark가 관리하길 원하는 Git 저장소 안에서 실행하세요:
|
||||
대부분의 문서화 도구는 생성에서 멈춥니다. Truthmark는 저장소 안에서 에이전트에게 완전한 문서 수명 주기를 제공합니다.
|
||||
|
||||
- **작동하는 소프트웨어에서 새 문서를 만듭니다.** Truth Document는 코드와 테스트를 읽고 범위가 명확한 제품 또는 엔지니어링 문서를 만듭니다.
|
||||
- **문서를 자동으로 일치시킵니다.** 기능 코드가 변경되면 Truth Sync가 에이전트 인계 시 실행되어 작업이 끝나기 전에 저장소의 진실을 업데이트합니다.
|
||||
- **문서를 다시 코드로 만듭니다.** Truth Realize는 승인된 truth 문서를 구현하면서 깔끔한 문서 우선 워크플로를 유지합니다.
|
||||
- **코드베이스가 성장함에 따라 소유권을 정비합니다.** Truth Structure는 새 영역이나 과도하게 넓어진 영역을 위해 범위가 명확한 경로와 시작 문서를 만듭니다.
|
||||
- **모든 것을 Git에서 검토합니다.** 코드, 결정, 계약, 아키텍처, 운영, 동작이 브랜치와 함께 이동합니다.
|
||||
|
||||
호스팅 지식 베이스가 필요 없습니다. 비공개 에이전트 메모리도 없습니다. 채팅 기록에 갇힌 문서도 없습니다.
|
||||
|
||||
## 빠른 시작: 첫 Truth 문서 만들기
|
||||
|
||||
**요구 사항:** Node.js 24 이상, Git 저장소, 에이전트 워크플로를 지원하는 AI 코딩 호스트.
|
||||
|
||||
Truthmark가 관리할 저장소 안에서 실행하세요.
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init`에서 Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor 또는 호스트 중립적인 명령줄 인터페이스 설정을 선택할 수 있습니다.
|
||||
|
||||
이제 설정된 에이전트에게 실제 동작 하나를 문서화하도록 요청하세요.
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
해당 문서가 없으면 Truth Document가 범위가 명확한 새 truth 문서를 만들고, 기존 소유 문서가 있으면 업데이트하며, 필요할 때 라우팅도 업데이트합니다. 기능 코드는 변경하지 않습니다.
|
||||
|
||||
결과를 검토하세요.
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
대화형 터미널에서 `truthmark init`은 번호가 붙은 다중 선택을 표시합니다. 플랫폼을 0개 이상 선택하거나 `none`을 입력해 호스트 중립적인 CLI 전용 설정을 사용하세요.
|
||||
이제 다음 파일이 있어야 합니다.
|
||||
|
||||
스크립트와 CI에서는 `--platform`을 반복해서 사용합니다. `--json`은 절대 입력을 요청하지 않습니다:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
정확한 경로는 저장소의 소유권 구조를 따릅니다. 새 파일은 `git status`에 표시되고, 추적 중인 파일의 변경 사항은 `git diff`에 표시됩니다.
|
||||
|
||||
호출 방식은 호스트마다 다릅니다. OpenCode는 `/skill truthmark-document`, Antigravity는 `@truthmark-document`를 사용하며, 그 밖의 지원 호스트는 각자의 네이티브 스킬 또는 슬래시 명령 표면을 사용합니다. 정확한 명령은 [플랫폼 표](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms)를 참조하세요.
|
||||
|
||||
스크립트와 지속적 통합에서는 선택한 플랫폼을 명시적으로 전달하세요.
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
처음 비대화형으로 실행할 때 `--platform`이 없으면 호스트 중립 상태를 유지하고, 이후 실행에서는 `.truthmark/config.yml`에 저장된 선택을 유지합니다.
|
||||
대화형으로 `none`을 선택하거나 `truthmark init --clear-platforms`를 실행하면 호스트 중립적인 저장소가 됩니다. 나중에 `truthmark init`을 다시 실행해 에이전트 플랫폼을 추가할 수 있습니다.
|
||||
|
||||
이제 가장 흔한 도입 경로를 시도해 보세요. 코드와 테스트에서 기존 동작 하나를 문서화합니다. AI 코딩 호스트에서 설치된 워크플로에 요청하세요:
|
||||
브랜치 기준 최신성 진단에는 Git 기준점을 전달하세요.
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
그 이후에는 사용자가 일반적으로 Truth Sync를 직접 호출할 필요가 없습니다. AI 호스트를 통해 계속 코딩하세요. 설치된 저장소 지침이 기능 코드가 변경될 때 에이전트에게 관련 테스트를 실행하고 인계 전에 Truth Sync 검토를 수행하라고 알려줍니다. 사용자는 결과 코드 diff와 truth-doc diff를 함께 검토합니다.
|
||||
## Truthmark 작동 방식
|
||||
|
||||
CLI 검증만 원한다면 `none`을 선택하고 `truthmark check`를 실행하세요. 나중에 `truthmark init`을 다시 실행해 플랫폼을 선택할 수 있습니다.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Truthmark 작동 방식" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 문제: AI 문서화 격차
|
||||
Truthmark 명령줄 인터페이스는 저장소 계약을 설치하고 검증합니다. 코딩 에이전트는 설치된 호스트 네이티브 워크플로를 통해 근거를 검토하고 문서화 작업을 수행합니다.
|
||||
|
||||
AI 코딩 에이전트는 코드를 빠르게 작성하는 데 탁월합니다. 하지만 이 속도는 위험한 새로운 실패 모드를 만듭니다. **저장소가 말하는 이야기가 현실과 어긋나는 것**입니다.
|
||||
일반적인 코드 변경은 하나의 단순한 순환을 따릅니다.
|
||||
|
||||
* 동작은 일시적인 채팅 기록 속에서 사라집니다.
|
||||
* 아키텍처 문서는 빠르게 뒤처집니다.
|
||||
* 제품 결정은 인계 후 사라집니다.
|
||||
* 코드 리뷰어는 “왜”를 이해하지 못한 채 원시 코드 diff만 보게 됩니다.
|
||||
* 모든 새 AI 세션은 저장소의 truth를 처음부터 다시 발견해야 합니다.
|
||||
1. 에이전트가 기능 코드를 변경합니다.
|
||||
2. 관련 테스트가 실행됩니다.
|
||||
3. Truth Sync가 매핑된 문서를 확인합니다.
|
||||
4. 저장소의 진실이 변경되면 에이전트가 문서와 라우팅을 만들거나 업데이트합니다.
|
||||
5. 코드 diff와 truth diff를 함께 검토합니다.
|
||||
|
||||
## 🎯 해결책: Truthmark
|
||||
## 워크플로
|
||||
|
||||
**Truthmark**는 저장소에 Git 네이티브 워크플로 계층을 설치합니다. AI 개발에서 보통 깨지는 부분, 즉 문서가 코드와 계속 정렬되도록 돕는 일을 해결합니다.
|
||||
| 워크플로 | 사용 시점 | 결과 |
|
||||
| -------------------- | ------------------------------------------------------------- | -------------------------------------------------------------- |
|
||||
| **Truth Document** | 기존 코드에 문서가 필요할 때 | 근거 기반 제품 및 엔지니어링 문서를 만들거나 업데이트 |
|
||||
| **Truth Sync** | 기능 코드가 변경되었을 때 | 인계 전에 매핑된 문서와 라우팅을 일치시킴 |
|
||||
| **Truth Structure** | 새 영역에 소유권이 필요하거나 기존 문서의 범위가 너무 넓을 때 | 범위가 명확한 경로와 골격형 시작 문서를 만듦 |
|
||||
| **Truth Realize** | 승인된 truth 문서를 작동하는 소프트웨어로 구현해야 할 때 | 문서를 기반으로 기능 코드를 업데이트 |
|
||||
| **Truth Check** | 저장소의 진실을 감사해야 할 때 | 라우팅, 소유권, 근거, 문서 문제를 보고 |
|
||||
| **Truthmark Portal** | 팀에 탐색 가능한 문서 사이트가 필요할 때 | Markdown truth 문서에서 커밋되는 정적 HTML 프레젠테이션을 생성 |
|
||||
|
||||
사람과 AI 에이전트가 문서 업데이트를 기억하길 기대하는 대신, Truthmark는 문서화를 저장소 안의 체계적이고 검토 가능한 습관으로 만듭니다.
|
||||
Truthmark는 Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor의 네이티브 저장소 표면으로 이러한 워크플로를 설치합니다.
|
||||
|
||||
### ✨ Truthmark가 특별한 이유
|
||||
## 제공되는 가치
|
||||
|
||||
Truthmark는 단순한 또 하나의 문서화 도구가 아닙니다. AI 워크플로에 깊이 통합되어 있습니다:
|
||||
### 현실에서 시작하는 문서
|
||||
|
||||
* **🚫 벤더 종속 없음:** 호스팅 서비스, 숨겨진 데이터베이스, 운영해야 할 추가 서버가 없습니다.
|
||||
* **🌳 100% Git 네이티브:** 모든 것이 저장소 안에 있습니다. truth는 브랜치와 함께 이동합니다.
|
||||
* **🤝 사람이 소유하고 에이전트가 따르는 계약:** 유지관리자가 저장소 계약을 소유하고, 에이전트는 코딩 중 설치된 지침을 따릅니다.
|
||||
* **✅ 검증을 통한 신뢰:** 동작을 바꾸는 작업에는 사람이 검토할 수 있는 truth-doc 결정 또는 diff가 포함되므로 AI 작업을 더 쉽게 신뢰할 수 있습니다.
|
||||
Truthmark는 제품 기능, 구현 동작, 애플리케이션 프로그래밍 인터페이스, 아키텍처, 워크플로, 운영, 테스트를 위한 문서를 만들 수 있습니다. 코드와 테스트가 근거를 제공하고, 범위가 명확한 Markdown 문서가 결과를 보존합니다.
|
||||
|
||||
## 🔄 작동 방식
|
||||
### 다음 변경에도 살아남는 문서
|
||||
|
||||
AI 에이전트가 코드를 수정해도 작업은 끝난 것이 아닙니다. Truthmark는 인계 전에 에이전트가 따르는 완료 시점 워크플로 보호 장치를 설치합니다:
|
||||
경로는 코드 영역을 표준 문서에 연결합니다. 에이전트가 동작을 변경하면 Truth Sync는 해당 진실이 속할 위치를 알고 인계를 계속 검토 가능한 상태로 유지합니다.
|
||||
|
||||
1. 💻 **코드:** 에이전트가 기능 코드를 수정합니다.
|
||||
2. 🧪 **테스트:** 관련 테스트가 실행됩니다.
|
||||
3. 🔍 **확인:** Truthmark는 설치된 마무리 검토의 일부로 매핑된 문서를 확인합니다.
|
||||
4. 📝 **문서화:** 저장소 truth가 변경되면 에이전트가 문서를 업데이트합니다.
|
||||
5. 👀 **검토:** 사람이 *코드 diff* + *truth diff*를 검토합니다.
|
||||
### 제품의 진실과 엔지니어링의 진실을 분리된 흐름으로 관리
|
||||
|
||||
## 🛠 Truthmark와 상호작용하는 방식
|
||||
제품의 진실은 사용자 대상 약속, 경계, 결정, 인수 기준을 담습니다. 엔지니어링의 진실은 현재 동작, 계약, 아키텍처, 워크플로, 운영, 테스트 동작을 담습니다.
|
||||
|
||||
Truthmark에는 저장소 로컬 계약 하나와 그것을 사용하는 두 가지 방식이 있습니다.
|
||||
### Git 네이티브 협업
|
||||
|
||||
### 사람은 계약을 설치하고 검증합니다
|
||||
중요한 모든 것은 커밋된 저장소 파일에 있습니다. 진실은 브랜치를 따르고, 일반적인 풀 리퀘스트와 함께 작동하며, 모든 유지관리자와 코딩 에이전트에게 보입니다.
|
||||
|
||||
유지관리자와 CI는 CLI를 사용합니다:
|
||||
### 로컬 우선 운영
|
||||
|
||||
* `truthmark init` - 설정을 만들거나 새로 고치고, 플랫폼을 0개 이상 선택하며, 라우팅, truth-doc 스캐폴드와 선택한 AI 호스트 지침을 설치합니다.
|
||||
* `truthmark check` - 터미널에서 저장소 truth를 검증합니다.
|
||||
Truthmark에는 호스팅 서비스, 데몬, 데이터베이스, 벡터 저장소, Model Context Protocol 서버가 필요 없습니다. 저장소 자체가 문서 워크플로를 가지고 있습니다.
|
||||
|
||||
### 에이전트는 코딩하는 동안 계약을 따릅니다
|
||||
## Truthmark가 적합한 영역
|
||||
|
||||
Truthmark는 Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor 같은 지원 AI 코딩 호스트를 위해 저장소 로컬 지침을 설치합니다.
|
||||
| 필요 | 최적의 선택 |
|
||||
| -------------------------------------- | ------------------------ |
|
||||
| 한 번의 에이전트 세션에서 더 나은 결과 | 더 나은 프롬프트 |
|
||||
| 개인 또는 세션 수준의 연속성 | 메모리 도구 |
|
||||
| 계획 우선 기능 개발 | 사양 워크플로 |
|
||||
| 코드와 함께 이동하는 브랜치 범위 문서 | **Truthmark** |
|
||||
| 동작 정확성 | 테스트와 코드 리뷰 |
|
||||
| 검토 가능한 AI 지원 문서 | **Truthmark + Git 리뷰** |
|
||||
|
||||
일반적인 루프는 단순합니다:
|
||||
Truthmark는 이미 AI 코딩 에이전트를 사용하며, 코드가 변하는 속도만큼 빠르게 저장소가 계속 진실을 말하기를 원하는 유지관리자와 엔지니어링 팀을 위해 만들어졌습니다.
|
||||
|
||||
1. 에이전트에게 코드 변경을 요청하거나 기존 동작을 문서화해 달라고 요청합니다.
|
||||
2. 설치된 지침은 에이전트에게 언제 테스트하고, 언제 truth docs를 업데이트하고, 언제 사람 검토를 위해 멈출지 알려 줍니다.
|
||||
3. 당신은 일반 Git diff를 검토합니다. 코드와 필요한 truth-doc 변경입니다.
|
||||
## 지원 호스트와 명령줄
|
||||
|
||||
사용자가 시작하는 에이전트 요청은 의도적으로 적습니다:
|
||||
지원되는 에이전트 호스트:
|
||||
|
||||
* `/truthmark-document` - 코드와 테스트에서 기존 구현 동작을 문서화합니다.
|
||||
* `/truthmark-realize` - 기존 truth docs에서 코드를 구현합니다.
|
||||
* `/truthmark-check` - 저장소 truth를 감사합니다.
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
Truth Sync는 작업을 시작하는 일반적인 방법이 아니라, 기능 코드 변경 후의 마무리 검토입니다.
|
||||
Truth Structure는 일상 명령이 아니라, 작업을 막는 경우에만 라우팅이나 소유권을 복구합니다.
|
||||
<details>
|
||||
<summary>명령줄 참조</summary>
|
||||
|
||||
## 얻는 것
|
||||
| 명령 | 목적 |
|
||||
| ----------------------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `truthmark init` | 구성, 라우팅, 템플릿, 선택한 호스트 워크플로를 만들거나 새로 고침 |
|
||||
| `truthmark check [--base <ref>]` | 저장소의 진실을 검증하고 선택적으로 브랜치 최신성 진단을 실행 |
|
||||
| `truthmark index --json` | 파생된 저장소 및 라우팅 메타데이터를 검사 |
|
||||
| `truthmark impact --base <ref> --json` | 변경된 파일을 문서, 소유자, 인접 테스트에 매핑 |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | 워크플로 적용 가능성과 대상을 검사 |
|
||||
| `truthmark validate ...` | 워크플로 보고서와 쓰기 임대를 검증 |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | 작성된 진실을 보존하면서 생성된 호스트 표면을 미리 보거나 제거 |
|
||||
|
||||
| 역량 | 하는 일 |
|
||||
| --- | --- |
|
||||
| Git 네이티브 truth | 저장소 truth를 커밋된 Markdown과 설정에 보관합니다. |
|
||||
| 브랜치 범위 문서화 | truth는 비공개 세션에 머무르지 않고 브랜치와 함께 이동합니다. |
|
||||
| 사람용 CLI | 유지관리자에게 설정, 새로고침, 검증, 검사 명령을 제공합니다. |
|
||||
| 설치된 에이전트 지침 | 코딩 에이전트에게 언제 문서화, 테스트, truth 동기화, 감사, 검토 중지를 할지 알려 줍니다. |
|
||||
| 명시적 라우팅 | 코드 영역을 정식 truth 문서에 매핑합니다. |
|
||||
| 검토 가능한 인계 | 코드와 truth 문서 모두에 대해 일반 Git diff를 생성합니다. |
|
||||
| 로컬 우선 운영 | 호스팅 서비스, 데몬, 데이터베이스, MCP 서버가 필요 없습니다. |
|
||||
| 더 안전한 쓰기 경계 | 코드 우선, 문서 우선, 읽기 전용, 문서 전용 워크플로를 분리합니다. |
|
||||
| 검증 | 라우팅, 권한, frontmatter, 링크, 생성 표면, 브랜치 범위, 신선도, 커버리지 문제를 보고합니다. |
|
||||
| 선택적 Portal | 명시적으로 활성화하고 요청한 경우 Markdown truth 문서에서 커밋된 정적 HTML 프레젠테이션 사이트를 생성합니다. |
|
||||
스크립트와 지속적 통합을 위해 명령줄 인터페이스 전반에서 구조화된 JSON 출력을 사용할 수 있습니다.
|
||||
|
||||
## 시각적 개요
|
||||
</details>
|
||||
|
||||
|
||||
## 더 알아보기
|
||||
|
||||
**기능:** Truthmark가 무엇을 설치하고 워크플로 표면이 어떻게 나뉘는지.
|
||||
- [Truthmark 사용자 가이드](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [문서 색인](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [아키텍처 개요](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [구성, 라우팅, 명령 계약](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [저장소의 진실 유지관리](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [기여하기](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
|
||||
|
||||
**위치:** Truthmark가 프롬프트, 메모리, 사양 워크플로와 비교해 어디에 들어맞는지.
|
||||
|
||||
|
||||
|
||||
**동기화 흐름:** Truth Sync가 일반적인 코드 변경을 인계 전에 어떻게 마무리하는지.
|
||||
|
||||
## 팀이 도입하는 이유
|
||||
|
||||
Truthmark는 AI 에이전트가 코드를 생성할 수 있음을 이미 아는 팀을 위한 것입니다.
|
||||
|
||||
다음 문제는 거버넌스입니다.
|
||||
|
||||
의식으로서의 거버넌스가 아닙니다. 거버넌스란 단순한 질문입니다:
|
||||
|
||||
> 이 AI 지원 변경 이후에도 저장소는 여전히 truth를 말하는가?
|
||||
|
||||
Truthmark는 커밋된 파일, 명시적 라우팅, 검토 가능한 diff로 팀이 그 질문에 답하도록 돕습니다.
|
||||
|
||||
다음이 필요할 때 유용합니다:
|
||||
|
||||
- 문서 드리프트 감소
|
||||
- 더 나은 인계
|
||||
- 브랜치별 제품 truth
|
||||
- 지속 가능한 아키텍처 및 API 문서
|
||||
- 문서와 코드 사이의 명시적 소유권
|
||||
- 더 안전한 에이전트 쓰기 경계
|
||||
- 숨겨진 메모리가 아닌 검토 가능한 문서
|
||||
- 커밋된 저장소 파일에서 계속 작동하는 에이전트 지침
|
||||
|
||||
## Truthmark가 들어맞는 곳
|
||||
|
||||
Truthmark는 프롬프트, 메모리, 사양, 테스트, 코드 리뷰를 대체하지 않습니다.
|
||||
|
||||
그 워크플로들이 Git 안에 지속적으로 자리 잡을 수 있는 장소를 제공합니다.
|
||||
|
||||
| 필요 | 더 적합한 것 |
|
||||
| --- | --- |
|
||||
| 한 번의 에이전트 세션에서 더 나은 출력 | 더 나은 프롬프트 |
|
||||
| 개인 또는 세션 수준의 연속성 | 메모리 도구 |
|
||||
| 계획 우선 기능 작업 | 사양 워크플로 |
|
||||
| 코드와 함께 이동하는 브랜치 범위 truth | Truthmark |
|
||||
| 동작 정확성 검증 | 테스트와 리뷰 |
|
||||
| AI 지원 문서 변경 검토 | Truthmark와 Git 리뷰 |
|
||||
|
||||
Truthmark의 영역은 의도적으로 좁게 설계되었습니다:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
그 주위에 에이전트 지침을 설치하기
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
|
||||
## 더 깊이 보기
|
||||
|
||||
README는 쇼윈도입니다. 빠른 맥락, 빠른 시작, 핵심 사고 모델을 제공합니다.
|
||||
|
||||
명령별 사용법, 표면 비교, 지원 플랫폼 상세, 설정, 라우팅, Portal, 예시는 [Truthmark 사용자 가이드](../user-guide.md)를 읽어보세요.
|
||||
|
||||
## 프로젝트 상태
|
||||
|
||||
현재 릴리스는 다음을 제공합니다:
|
||||
|
||||
- init, check, index, impact, workflow status를 위한 로컬 CLI 명령
|
||||
- Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor용으로 생성된 저장소 로컬 에이전트 지침
|
||||
- 라우팅, 권한, frontmatter, 링크, 신선도, 생성 표면, 브랜치 범위, 커버리지 진단
|
||||
- 브랜치 범위 truth 문서와 파생된 저장소 인텔리전스 산출물
|
||||
|
||||
## 문서
|
||||
|
||||
- [사용자 가이드](../user-guide.md)
|
||||
- [문서 색인](../README.md)
|
||||
- [아키텍처 개요](../truthmark/engineering/architecture/overview.md)
|
||||
- [API 및 CLI 계약](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [저장소 truth 유지관리 가이드](../standards/maintaining-repository-truth.md)
|
||||
|
||||
로컬 개발 및 기여 명령은 [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참조하세요.
|
||||
|
||||
## 설계 경계
|
||||
|
||||
Truthmark는 의도적으로 작습니다. 로컬이고, 커밋되며, 브랜치 범위이고, 검토 가능합니다.
|
||||
|
||||
Truthmark는 호스팅 서비스, MCP 서버, 벡터 데이터베이스, 숨겨진 메모리 계층, CI 강제 제품, 자율 코드 재작성 엔진이 아닙니다. 저장소 truth가 보이도록 돕지만, 테스트, 코드 리뷰, 사람의 판단을 대체하지는 않습니다.
|
||||
**Truthmark를 설치하고 코딩 호스트를 선택해 오늘 바로 실제 동작 하나를 문서로 바꾸세요.**
|
||||
|
||||
## 라이선스
|
||||
|
||||
MIT. [LICENSE](../../LICENSE)를 참조하세요.
|
||||
|
||||
## 안전한 제거
|
||||
|
||||
`truthmark uninstall --dry-run`을(를) 사용하여 정확히 생성된 호스트 표면을 검토한 후 `truthmark uninstall --apply`를 사용해 제거하세요. 작성된 truth, 구성, 템플릿, Portal 출력, Gemini 파일 및 관련 없는 사용자 파일은 보존되며, npm 전역 설치는 패키지 관리자에서 별도로 제거하십시오.
|
||||
|
||||
+131
-156
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**Twoi agenci piszą kod. Truthmark utrzymuje dokumentację dla ludzi, możliwą do przeglądu w Git.**
|
||||
**Twoi agenci piszą kod. Truthmark dba o dokumentację dla ludzi, gotową do przeglądu w Git.**
|
||||
|
||||
Truthmark instaluje natywne dla Git przepływy pracy, dzięki którym agenci programistyczni AI tworzą nową dokumentację produktu i inżynierii na podstawie istniejącego kodu i testów, aktualizują ją po każdej zmianie kodu oraz przekazują Ci zwykłe diffy Markdown do przeglądu.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Zacznij](#szybki-start-utwórz-swój-pierwszy-dokument-truth) · [Strona internetowa](https://merlinhu1.github.io/truthmark/) · [Przewodnik użytkownika](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Przeczytaj ten plik README w jednym z 16 języków</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Szybki start: lokalne uruchomienie w pięć minut
|
||||
## Twórz dokumentację od podstaw. Dbaj, by pozostawała prawdziwa.
|
||||
|
||||
Uruchom to w repozytorium Git, którym ma zarządzać Truthmark:
|
||||
Większość narzędzi do dokumentacji kończy pracę po jej wygenerowaniu. Truthmark zapewnia agentom pełny cykl życia dokumentacji wewnątrz repozytorium:
|
||||
|
||||
- **Twórz nową dokumentację na podstawie działającego oprogramowania.** Truth Document odczytuje kod i testy, a następnie tworzy precyzyjnie ograniczoną dokumentację produktu lub inżynierii.
|
||||
- **Automatycznie utrzymuj zgodność dokumentacji.** Truth Sync uruchamia się przy przekazaniu pracy przez agenta po zmianach kodu funkcjonalnego i aktualizuje prawdę repozytorium przed zakończeniem zadania.
|
||||
- **Zamieniaj dokumentację z powrotem w kod.** Truth Realize implementuje zatwierdzone dokumenty truth, zachowując przejrzysty przepływ pracy doc-first.
|
||||
- **Naprawiaj własność wraz z rozwojem bazy kodu.** Truth Structure tworzy precyzyjne trasy i dokumenty startowe dla nowych lub przeciążonych obszarów.
|
||||
- **Przeglądaj wszystko w Git.** Kod, decyzje, kontrakty, architektura, operacje i zachowanie podążają razem z gałęzią.
|
||||
|
||||
Bez hostowanej bazy wiedzy. Bez prywatnej pamięci agenta. Bez dokumentacji uwięzionej w historii czatu.
|
||||
|
||||
## Szybki start: utwórz swój pierwszy dokument truth
|
||||
|
||||
**Wymagania:** Node.js 24 lub nowszy, repozytorium Git oraz obsługiwany host programistyczny AI do przepływów pracy agentów.
|
||||
|
||||
Uruchom poniższe polecenia w repozytorium, którym ma zarządzać Truthmark:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` pozwala wybrać Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor albo konfigurację interfejsu wiersza poleceń niezależną od hosta.
|
||||
|
||||
Teraz poproś skonfigurowanego agenta o udokumentowanie jednego rzeczywistego zachowania:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document tworzy nowy, precyzyjnie ograniczony dokument truth, jeśli taki jeszcze nie istnieje, aktualizuje istniejącego właściciela, gdy już istnieje, i w razie potrzeby aktualizuje routing. Nie zmienia kodu funkcjonalnego.
|
||||
|
||||
Przejrzyj rezultat:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
W terminalu interaktywnym `truthmark init` wyświetla numerowany wybór wielokrotny. Wybierz zero lub więcej platform albo wpisz `none`, aby skonfigurować tryb neutralny wobec hosta i tylko CLI.
|
||||
Powinny teraz istnieć:
|
||||
|
||||
W skryptach i CI powtarzaj `--platform`; `--json` nigdy nie wyświetla pytania:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Dokładne ścieżki wynikają ze struktury własności w Twoim repozytorium. Nowe pliki pojawiają się w `git status`, a zmiany w śledzonych plikach — w `git diff`.
|
||||
|
||||
Sposób wywołania zależy od hosta. OpenCode używa `/skill truthmark-document`, Antigravity używa `@truthmark-document`, a pozostałe obsługiwane hosty korzystają ze swoich natywnych umiejętności lub poleceń z ukośnikiem. Dokładne polecenia znajdziesz w [tabeli platform](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms).
|
||||
|
||||
W skryptach i ciągłej integracji jawnie przekaż wybrane platformy:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
Przy pierwszym nieinteraktywnym uruchomieniu bez `--platform` konfiguracja pozostaje neutralna; kolejne uruchomienia zachowują wybór zapisany w `.truthmark/config.yml`.
|
||||
Wybierz interaktywnie `none` albo uruchom `truthmark init --clear-platforms`, aby uzyskać repozytorium niezależne od hosta. Platformy agentów możesz dodać później, ponownie uruchamiając `truthmark init`.
|
||||
|
||||
Teraz wypróbuj najczęstszą ścieżkę adopcji: udokumentuj jedno istniejące zachowanie na podstawie kodu i testów. W swoim hoście kodowania AI poproś zainstalowany workflow:
|
||||
Aby uzyskać diagnostykę aktualności względem gałęzi, przekaż bazę Git:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Po tym użytkownicy zwykle nie powinni wywoływać Truth Sync bezpośrednio. Kontynuuj kodowanie przez swojego hosta AI; zainstalowane instrukcje repozytorium mówią agentowi, aby przy zmianach kodu funkcjonalnego uruchomił odpowiednie testy i wykonał przegląd Truth Sync przed przekazaniem pracy. Ty przeglądasz wynikowy diff kodu oraz diff truth-doc.
|
||||
## Jak działa Truthmark
|
||||
|
||||
Jeśli chcesz tylko walidacji CLI, wybierz `none` i uruchom `truthmark check`; później możesz ponownie uruchomić `truthmark init`, aby wybrać platformy.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Jak działa Truthmark" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 Problem: luka w dokumentacji AI
|
||||
Interfejs wiersza poleceń Truthmark instaluje i sprawdza kontrakt repozytorium. Twój agent programistyczny analizuje dowody i wykonuje pracę dokumentacyjną za pomocą zainstalowanych, natywnych dla hosta przepływów pracy.
|
||||
|
||||
Agenci kodujący AI są niezwykle dobrzy w szybkim pisaniu kodu. Ta prędkość tworzy jednak groźny nowy tryb awarii: **historia repozytorium zaczyna rozmijać się z rzeczywistością.**
|
||||
Typowa zmiana kodu przebiega w jednej prostej pętli:
|
||||
|
||||
* Zachowanie ginie w ulotnych historiach czatu.
|
||||
* Dokumenty architektoniczne szybko zostają w tyle.
|
||||
* Decyzje produktowe znikają po przekazaniu pracy.
|
||||
* Recenzenci kodu oglądają surowe diffy kodu bez zrozumienia „dlaczego”.
|
||||
* Każda nowa sesja AI musi od zera odkrywać truth repozytorium.
|
||||
1. Agent zmienia kod funkcjonalny.
|
||||
2. Uruchamiane są odpowiednie testy.
|
||||
3. Truth Sync sprawdza zmapowaną dokumentację.
|
||||
4. Gdy prawda repozytorium się zmieniła, agent tworzy lub aktualizuje dokumentację oraz routing.
|
||||
5. Wspólnie przeglądasz diff kodu i diff dokumentów truth.
|
||||
|
||||
## 🎯 Rozwiązanie: Truthmark
|
||||
## Przepływy pracy
|
||||
|
||||
**Truthmark** instaluje w Twoim repozytorium warstwę workflow natywną dla Git. Naprawia tę część rozwoju z AI, która zwykle się psuje: pomaga utrzymać dokumentację w zgodzie z kodem.
|
||||
| Przepływ pracy | Kiedy go używać | Rezultat |
|
||||
| -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| **Truth Document** | Istniejący kod wymaga dokumentacji | Tworzy lub aktualizuje opartą na dowodach dokumentację produktu i inżynierii |
|
||||
| **Truth Sync** | Zmienił się kod funkcjonalny | Przed przekazaniem pracy utrzymuje zgodność zmapowanej dokumentacji i routingu |
|
||||
| **Truth Structure** | Nowy obszar potrzebuje właściciela albo istniejąca dokumentacja jest zbyt szeroka | Tworzy precyzyjne trasy i szkieletowe dokumenty startowe |
|
||||
| **Truth Realize** | Zatwierdzony dokument truth powinien stać się działającym oprogramowaniem | Aktualizuje kod funkcjonalny na podstawie dokumentacji |
|
||||
| **Truth Check** | Prawda repozytorium wymaga audytu | Zgłasza problemy z routingiem, własnością, dowodami i dokumentacją |
|
||||
| **Truthmark Portal** | Zespół potrzebuje witryny z dokumentacją do wygodnego przeglądania | Generuje zatwierdzoną statyczną prezentację HTML z dokumentów truth w Markdown |
|
||||
|
||||
Zamiast liczyć, że ludzie i agenci AI będą pamiętać o aktualizowaniu dokumentów, Truthmark zamienia dokumentację w systematyczny, możliwy do przeglądu nawyk wewnątrz repozytorium.
|
||||
|
||||
### ✨ Dlaczego Truthmark jest wyjątkowy
|
||||
|
||||
Truthmark nie jest tylko kolejnym narzędziem do dokumentacji. Jest głęboko zintegrowany z workflow AI:
|
||||
|
||||
* **🚫 Zero zależności od dostawcy:** brak usług hostowanych, ukrytych baz danych i dodatkowych serwerów do utrzymywania.
|
||||
* **🌳 100% natywny dla Git:** wszystko mieszka w Twoim repozytorium. Truth porusza się razem z gałęzią.
|
||||
* **🤝 Kontrakt należący do ludzi i wykonywany przez agentów:** Opiekunowie posiadają kontrakt repozytorium; agenci podczas kodowania podążają za zainstalowanymi instrukcjami.
|
||||
* **✅ Zaufanie przez weryfikację:** pracy AI łatwiej zaufać, ponieważ zmiany wpływające na zachowanie zawierają decyzję lub diff truth-doc możliwy do przeglądu przez człowieka.
|
||||
|
||||
## 🔄 Jak to działa
|
||||
|
||||
Gdy agent AI modyfikuje Twój kod, praca nie jest skończona. Truthmark instaluje strażnika workflow na zakończenie pracy, którego agenci przestrzegają przed przekazaniem:
|
||||
|
||||
1. 💻 **Kod:** agent modyfikuje kod funkcjonalny.
|
||||
2. 🧪 **Test:** wykonywane są odpowiednie testy.
|
||||
3. 🔍 **Sprawdzenie:** Truthmark sprawdza zmapowaną dokumentację jako część zainstalowanego końcowego przeglądu.
|
||||
4. 📝 **Dokumentacja:** agent aktualizuje dokumenty, gdy truth repozytorium się zmieniła.
|
||||
5. 👀 **Przegląd:** człowiek przegląda *diff kodu* + *diff truth*.
|
||||
|
||||
## 🛠 Jak używasz Truthmark
|
||||
|
||||
Truthmark ma jeden lokalny kontrakt repozytorium i dwa sposoby korzystania z niego.
|
||||
|
||||
### Ludzie instalują i walidują kontrakt
|
||||
|
||||
Opiekunowie i CI używają CLI:
|
||||
|
||||
* `truthmark init` - tworzy lub odświeża konfigurację, pozwala wybrać zero lub więcej platform oraz instaluje routing, szkielety truth-doc i instrukcje dla wybranych hostów AI.
|
||||
* `truthmark check` - waliduje truth repozytorium z terminala.
|
||||
|
||||
### Agenci podążają za kontraktem podczas kodowania
|
||||
|
||||
Truthmark instaluje lokalne instrukcje repozytorium dla obsługiwanych hostów kodowania AI, takich jak Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity i Cursor.
|
||||
|
||||
Normalna pętla jest prosta:
|
||||
|
||||
1. Poproś agenta o zmianę kodu albo o udokumentowanie istniejącego zachowania.
|
||||
2. Zainstalowane instrukcje mówią agentowi, kiedy testować, kiedy aktualizować truth docs i kiedy zatrzymać się do ludzkiego przeglądu.
|
||||
3. Przeglądasz zwykłe diffy Git: kod plus ewentualne zmiany w truth-doc.
|
||||
|
||||
Żądania agenta uruchamiane przez użytkownika są celowo nieliczne:
|
||||
|
||||
* `/truthmark-document` - dokumentuje istniejące zaimplementowane zachowanie z kodu i testów.
|
||||
* `/truthmark-realize` - implementuje kod z istniejących truth docs.
|
||||
* `/truthmark-check` - audytuje truth repozytorium.
|
||||
|
||||
Truth Sync nie jest zwykłym sposobem rozpoczynania pracy; to końcowy przegląd po funkcjonalnych zmianach kodu.
|
||||
Truth Structure nie jest codzienną komendą; naprawia routing lub własność tylko wtedy, gdy blokuje to pracę.
|
||||
Truthmark instaluje te przepływy pracy jako natywne powierzchnie repozytorium dla Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity i Cursor.
|
||||
|
||||
## Co otrzymujesz
|
||||
|
||||
| Możliwość | Co robi |
|
||||
| --- | --- |
|
||||
| Truth natywny dla Git | Utrzymuje truth repozytorium w zatwierdzonych plikach Markdown i konfiguracji. |
|
||||
| Dokumentacja w zakresie gałęzi | Truth porusza się z gałęzią zamiast mieszkać w prywatnej sesji. |
|
||||
| CLI dla ludzi | Daje opiekunom komendy konfiguracji, odświeżania, walidacji i inspekcji. |
|
||||
| Zainstalowana instrukcja agenta | Mówi agentom kodującym, kiedy dokumentować, testować, synchronizować truth, audytować lub zatrzymać się do przeglądu. |
|
||||
| Jawny routing | Mapuje obszary kodu na kanoniczne dokumenty truth. |
|
||||
| Przekazania możliwe do przeglądu | Tworzy zwykłe diffy Git zarówno dla kodu, jak i dokumentów truth. |
|
||||
| Działanie local-first | Nie wymaga hostowanej usługi, demona, bazy danych ani serwera MCP. |
|
||||
| Bezpieczniejsze granice zapisu | Rozdziela workflow code-first, doc-first, read-only i doc-only. |
|
||||
| Walidacja | Raportuje problemy z routingiem, uprawnieniami, frontmatter, linkami, wygenerowaną powierzchnią, zakresem gałęzi, świeżością i pokryciem. |
|
||||
| Opcjonalny Portal | Generuje zatwierdzoną statyczną witrynę prezentacyjną HTML z dokumentów truth w Markdown, gdy jest wyraźnie włączony i zażądany. |
|
||||
### Dokumentację, która zaczyna od rzeczywistości
|
||||
|
||||
## Przegląd wizualny
|
||||
Truthmark potrafi tworzyć dokumentację możliwości produktu, zachowania implementacji, interfejsów programistycznych aplikacji, architektury, przepływów pracy, operacji i testów. Kod i testy dostarczają dowodów, a precyzyjnie ograniczone dokumenty Markdown utrwalają wynik.
|
||||
|
||||
|
||||
### Dokumentację, która przetrwa kolejną zmianę
|
||||
|
||||
**Funkcje:** co Truthmark instaluje i jak podzielona jest powierzchnia workflow.
|
||||
Trasy łączą obszary kodu z kanonicznymi dokumentami. Kiedy agenci zmieniają zachowanie, Truth Sync wie, gdzie należy zapisać odpowiadającą mu prawdę, i utrzymuje przekazanie pracy w formie gotowej do przeglądu.
|
||||
|
||||
|
||||
### Prawdę produktu i inżynierii w osobnych obszarach
|
||||
|
||||
**Pozycja:** gdzie Truthmark mieści się względem promptów, pamięci i workflow specyfikacji.
|
||||
Prawda produktu obejmuje obietnice dla użytkowników, granice, decyzje i kryteria akceptacji. Prawda inżynierii obejmuje bieżące zachowanie, kontrakty, architekturę, przepływy pracy, operacje oraz zachowanie testów.
|
||||
|
||||
|
||||
### Współpracę natywną dla Git
|
||||
|
||||
**Przepływ synchronizacji:** jak Truth Sync zamyka zwykłe zmiany kodu przed przekazaniem.
|
||||
Wszystko, co ważne, znajduje się w zatwierdzonych plikach repozytorium. Prawda podąża za gałęzią, współpracuje ze zwykłymi pull requestami i pozostaje widoczna dla każdego opiekuna oraz agenta programistycznego.
|
||||
|
||||
## Dlaczego zespoły go przyjmują
|
||||
### Działanie local-first
|
||||
|
||||
Truthmark jest dla zespołów, które już wiedzą, że agenci AI potrafią generować kod.
|
||||
|
||||
Następnym problemem jest governance.
|
||||
|
||||
Nie governance jako ceremonia. Governance jako proste pytanie:
|
||||
|
||||
> Czy po tej zmianie wspieranej przez AI repozytorium nadal mówi truth?
|
||||
|
||||
Truthmark pomaga zespołom odpowiedzieć na to pytanie za pomocą zatwierdzonych plików, jawnego routingu i diffów możliwych do przeglądu.
|
||||
|
||||
Jest przydatny, gdy potrzebujesz:
|
||||
|
||||
- mniejszego rozjazdu dokumentacji
|
||||
- lepszych przekazań pracy
|
||||
- truth produktu specyficznego dla gałęzi
|
||||
- trwałej dokumentacji architektury i API
|
||||
- jawnej własności między dokumentami a kodem
|
||||
- bezpieczniejszych granic zapisu dla agentów
|
||||
- dokumentacji możliwej do przeglądu zamiast ukrytej pamięci
|
||||
- instrukcje agenta, które nadal działają z commitowanych plików repozytorium
|
||||
Truthmark nie potrzebuje hostowanej usługi, demona, bazy danych, magazynu wektorowego ani serwera Model Context Protocol. Repozytorium zawiera własny przepływ pracy dokumentacyjnej.
|
||||
|
||||
## Gdzie pasuje Truthmark
|
||||
|
||||
Truthmark nie zastępuje promptów, pamięci, specyfikacji, testów ani przeglądu kodu.
|
||||
| Potrzeba | Najlepsze rozwiązanie |
|
||||
| ----------------------------------------------------- | ------------------------------ |
|
||||
| Lepszy wynik z jednej sesji agenta | Lepszy prompt |
|
||||
| Ciągłość osobista lub na poziomie sesji | Narzędzie pamięci |
|
||||
| Praca nad funkcją rozpoczynana od planu | Przepływ pracy specyfikacji |
|
||||
| Dokumentacja w zakresie gałęzi, która podąża za kodem | **Truthmark** |
|
||||
| Poprawność zachowania | Testy i przegląd kodu |
|
||||
| Dokumentacja wspierana przez AI i gotowa do przeglądu | **Truthmark + przegląd w Git** |
|
||||
|
||||
Daje tym workflow trwałe miejsce w Git.
|
||||
Truthmark powstał dla opiekunów i zespołów inżynierskich, które już korzystają z agentów programistycznych AI i chcą, aby repozytorium nadążało z prawdą za każdą zmianą kodu.
|
||||
|
||||
| Potrzeba | Lepsze dopasowanie |
|
||||
| --- | --- |
|
||||
| Lepszy wynik z jednej sesji agenta | Lepszy prompt |
|
||||
| Ciągłość osobista lub na poziomie sesji | Narzędzie pamięci |
|
||||
| Praca nad funkcją zaczynająca się od planu | Workflow specyfikacji |
|
||||
| Truth w zakresie gałęzi, która podróżuje z kodem | Truthmark |
|
||||
| Walidacja poprawności zachowania | Testy i przegląd |
|
||||
| Przegląd zmian dokumentacji wspieranych przez AI | Truthmark plus przegląd Git |
|
||||
## Obsługiwane hosty i wiersz poleceń
|
||||
|
||||
Zakres Truthmark jest celowo wąski:
|
||||
Obsługiwane hosty agentów:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
zainstalować wokół niej instrukcje agenta
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Więcej szczegółów
|
||||
<details>
|
||||
<summary>Dokumentacja wiersza poleceń</summary>
|
||||
|
||||
README jest witryną sklepową: szybki kontekst, szybki start i podstawowy model myślowy.
|
||||
| Polecenie | Zastosowanie |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Tworzy lub odświeża konfigurację, routing, szablony i przepływy pracy wybranych hostów |
|
||||
| `truthmark check [--base <ref>]` | Sprawdza prawdę repozytorium i opcjonalnie uruchamia diagnostykę aktualności gałęzi |
|
||||
| `truthmark index --json` | Wyświetla pochodne metadane repozytorium i routingu |
|
||||
| `truthmark impact --base <ref> --json` | Mapuje zmienione pliki na dokumentację, właścicieli i pobliskie testy |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Wyświetla zastosowanie przepływu pracy i jego cele |
|
||||
| `truthmark validate ...` | Sprawdza raporty przepływów pracy i dzierżawy zapisu |
|
||||
| `truthmark uninstall --dry-run\|--apply` | Wyświetla podgląd lub usuwa wygenerowane powierzchnie hosta, zachowując utworzone dokumenty truth |
|
||||
|
||||
Aby poznać użycie komenda po komendzie, porównanie powierzchni, szczegóły obsługiwanych platform, konfigurację, routing, Portal i przykłady, przeczytaj [Przewodnik użytkownika Truthmark](../user-guide.md).
|
||||
Strukturyzowane dane wyjściowe JSON są dostępne w całym interfejsie wiersza poleceń na potrzeby skryptów i ciągłej integracji.
|
||||
|
||||
## Status projektu
|
||||
</details>
|
||||
|
||||
Obecne wydanie zapewnia:
|
||||
## Dowiedz się więcej
|
||||
|
||||
- lokalne komendy CLI dla init, check, index, impact i workflow status
|
||||
- wygenerowane lokalne instrukcje agenta dla Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity i Cursor
|
||||
- diagnostykę route, authority, frontmatter, link, freshness, generated-surface, branch-scope i coverage
|
||||
- dokumenty truth w zakresie gałęzi oraz pochodne artefakty inteligencji repozytorium
|
||||
- [Przewodnik użytkownika Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Indeks dokumentacji](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Przegląd architektury](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Kontrakty konfiguracji, routingu i poleceń](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Utrzymywanie prawdy repozytorium](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Współtworzenie](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Dokumentacja
|
||||
|
||||
- [Przewodnik użytkownika](../user-guide.md)
|
||||
- [Indeks dokumentacji](../README.md)
|
||||
- [Przegląd architektury](../truthmark/engineering/architecture/overview.md)
|
||||
- [Kontrakty API i CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Przewodnik utrzymania repository truth](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Komendy lokalnego rozwoju i kontrybuowania znajdziesz w [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Granice projektu
|
||||
|
||||
Truthmark jest celowo mały: lokalny, zatwierdzony, ograniczony do gałęzi i możliwy do przeglądu.
|
||||
|
||||
Nie jest usługą hostowaną, serwerem MCP, wektorową bazą danych, ukrytą warstwą pamięci, produktem wymuszającym CI ani autonomicznym silnikiem przepisywania kodu. Pomaga utrzymać widoczność truth repozytorium; nie zastępuje testów, przeglądu kodu ani ludzkiego osądu.
|
||||
**Zainstaluj Truthmark, wybierz host programistyczny i już dziś zamień jedno rzeczywiste zachowanie w dokumentację.**
|
||||
|
||||
## Licencja
|
||||
|
||||
MIT. Zobacz [LICENSE](../../LICENSE).
|
||||
|
||||
## Bezpieczne usuwanie
|
||||
|
||||
Użyj `truthmark uninstall --dry-run`, aby przejrzeć dokładnie wygenerowane powierzchnie hosta, a następnie `truthmark uninstall --apply`, aby je usunąć. Utworzone truth, konfiguracja, szablony, wyjście Portalu, pliki Gemini i niezwiązane pliki użytkownika są zachowane; globalną instalację npm usuń oddzielnie za pomocą swojego menedżera pakietów.
|
||||
|
||||
+132
-157
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**Seus agentes escrevem código. O Truthmark mantém documentação voltada para humanos e revisável no Git.**
|
||||
**Seus agentes escrevem código. O Truthmark mantém a documentação voltada para pessoas e revisável no Git.**
|
||||
|
||||
O Truthmark instala fluxos de trabalho nativos do Git que permitem que agentes de programação com IA criem nova documentação de produto e engenharia a partir de código e testes existentes, mantenham-na atualizada após cada mudança de código e entreguem diffs comuns de Markdown para sua revisão.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Comece agora](#início-rápido-crie-seu-primeiro-documento-de-verdade) · [Site](https://merlinhu1.github.io/truthmark/) · [Guia do usuário](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Leia este README em 16 idiomas</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Início rápido: rodando localmente em cinco minutos
|
||||
## Crie os primeiros documentos. Mantenha-os verdadeiros.
|
||||
|
||||
Execute isto dentro do repositório Git que você quer que o Truthmark gerencie:
|
||||
A maioria das ferramentas de documentação para depois da geração. O Truthmark oferece aos agentes um ciclo de vida completo da documentação dentro do seu repositório:
|
||||
|
||||
- **Crie novos documentos a partir de software funcional.** O Truth Document lê código e testes e, em seguida, cria documentação delimitada de produto ou engenharia.
|
||||
- **Mantenha os documentos alinhados automaticamente.** O Truth Sync é executado na entrega do agente após mudanças funcionais no código e atualiza a verdade do repositório antes que o trabalho seja concluído.
|
||||
- **Transforme documentos de volta em código.** O Truth Realize implementa documentos de verdade aprovados e preserva um fluxo de trabalho limpo que começa pela documentação.
|
||||
- **Repare a propriedade conforme a base de código cresce.** O Truth Structure cria rotas delimitadas e documentos iniciais para áreas novas ou sobrecarregadas.
|
||||
- **Revise tudo no Git.** Código, decisões, contratos, arquitetura, operações e comportamento viajam juntos com a branch.
|
||||
|
||||
Sem base de conhecimento hospedada. Sem memória privada de agentes. Sem documentação presa no histórico de chats.
|
||||
|
||||
## Início rápido: crie seu primeiro documento de verdade
|
||||
|
||||
**Requisitos:** Node.js 24 ou mais recente, um repositório Git e um host de programação com IA compatível com fluxos de trabalho de agentes.
|
||||
|
||||
Execute isto dentro do repositório que você quer que o Truthmark gerencie:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` permite selecionar Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor ou uma configuração de interface de linha de comando neutra em relação ao host.
|
||||
|
||||
Agora peça ao agente configurado que documente um comportamento real:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
O Truth Document cria um novo documento de verdade delimitado quando nenhum existe, atualiza o proprietário existente quando ele já existe e atualiza o roteamento quando necessário. Ele não altera o código funcional.
|
||||
|
||||
Revise o resultado:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
Em um terminal interativo, `truthmark init` mostra uma seleção múltipla numerada. Escolha zero ou mais plataformas, ou `none` para uma configuração neutra em relação a host e somente de CLI.
|
||||
Agora você deve ter:
|
||||
|
||||
Para scripts e CI, repita `--platform`; `--json` nunca exibe uma solicitação interativa:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Os caminhos exatos seguem a estrutura de propriedade do seu repositório. Novos arquivos aparecem em `git status`; mudanças em arquivos rastreados aparecem em `git diff`.
|
||||
|
||||
A forma de invocação varia conforme o host. O OpenCode usa `/skill truthmark-document`, o Antigravity usa `@truthmark-document` e os outros hosts compatíveis usam sua superfície nativa de skills ou comandos com barra. Consulte a [tabela de plataformas](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) para ver os comandos exatos.
|
||||
|
||||
Para scripts e integração contínua, informe explicitamente as plataformas selecionadas:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
Na primeira execução não interativa sem `--platform`, a configuração permanece neutra; execuções posteriores mantêm a seleção salva em `.truthmark/config.yml`.
|
||||
Escolha `none` interativamente ou execute `truthmark init --clear-platforms` para ter um repositório neutro em relação ao host. Você pode adicionar plataformas de agentes mais tarde executando `truthmark init` novamente.
|
||||
|
||||
Agora experimente o caminho de adoção mais comum: documentar, a partir do código e dos testes, um comportamento existente. No seu host de codificação com IA, peça ao workflow instalado:
|
||||
Para diagnósticos de atualidade relativos à branch, informe uma base do Git:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Depois disso, usuários normalmente não devem invocar o Truth Sync diretamente. Continue codificando por meio do seu host de IA; as instruções instaladas no repositório dizem ao agente para executar os testes relevantes e realizar a revisão Truth Sync antes da entrega quando houver mudanças em código funcional. Você revisa o diff de código resultante junto com o diff dos documentos de verdade.
|
||||
## Como o Truthmark funciona
|
||||
|
||||
Se você quer apenas validação por CLI, escolha `none` e continue com `truthmark check`; depois você pode executar `truthmark init` novamente para selecionar plataformas.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Como o Truthmark funciona" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 O problema: a lacuna de documentação da IA
|
||||
A interface de linha de comando do Truthmark instala e valida o contrato do repositório. Seu agente de programação realiza a revisão de evidências e o trabalho de documentação por meio dos fluxos de trabalho nativos do host que foram instalados.
|
||||
|
||||
Agentes de codificação com IA são incríveis para escrever código rapidamente. Mas essa velocidade cria um novo modo de falha perigoso: **a história do repositório se afasta da realidade.**
|
||||
Uma mudança normal de código segue um ciclo simples:
|
||||
|
||||
* Comportamentos se perdem em históricos de chat efêmeros.
|
||||
* Documentos de arquitetura ficam desatualizados rapidamente.
|
||||
* Decisões de produto desaparecem após a entrega.
|
||||
* Revisores de código acabam examinando diffs de código crus sem entender o “porquê”.
|
||||
* Cada nova sessão de IA é forçada a redescobrir do zero a verdade do seu repositório.
|
||||
1. O agente altera o código funcional.
|
||||
2. Os testes relevantes são executados.
|
||||
3. O Truth Sync verifica a documentação mapeada.
|
||||
4. O agente cria ou atualiza documentos e roteamento quando a verdade do repositório muda.
|
||||
5. Você revisa o diff de código e o diff de verdade juntos.
|
||||
|
||||
## 🎯 A solução: Truthmark
|
||||
## Fluxos de trabalho
|
||||
|
||||
**Truthmark** instala no seu repositório uma camada de workflow nativa do Git. Ele corrige a parte do desenvolvimento com IA que geralmente quebra: ajudar a documentação a permanecer alinhada com o código.
|
||||
| Fluxo de trabalho | Quando usar | Resultado |
|
||||
| -------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| **Truth Document** | O código existente precisa de documentação | Cria ou atualiza documentação de produto e engenharia respaldada por evidências |
|
||||
| **Truth Sync** | O código funcional mudou | Mantém os documentos mapeados e o roteamento alinhados antes da entrega |
|
||||
| **Truth Structure** | Uma área nova precisa de propriedade ou os documentos existentes são abrangentes demais | Cria rotas delimitadas e documentos iniciais básicos |
|
||||
| **Truth Realize** | Um documento de verdade aprovado deve se tornar software funcional | Atualiza o código funcional a partir da documentação |
|
||||
| **Truth Check** | A verdade do repositório precisa de uma auditoria | Relata problemas de roteamento, propriedade, evidências e documentação |
|
||||
| **Truthmark Portal** | A equipe quer um site de documentação navegável | Gera uma apresentação HTML estática e versionada a partir de documentos de verdade em Markdown |
|
||||
|
||||
Em vez de esperar que humanos e agentes de IA se lembrem de atualizar a documentação, o Truthmark transforma a documentação em um hábito sistemático e revisável dentro do próprio repositório.
|
||||
|
||||
### ✨ Por que o Truthmark é único
|
||||
|
||||
Truthmark não é apenas mais uma ferramenta de documentação. Ele é profundamente integrado ao workflow de IA:
|
||||
|
||||
* **🚫 Sem dependência de fornecedor:** nenhum serviço hospedado, nenhum banco de dados oculto, nenhum servidor extra para operar.
|
||||
* **🌳 100% nativo do Git:** tudo vive no seu repositório. A verdade se move com a sua branch.
|
||||
* **🤝 Contrato pertencente a humanos e seguido por agentes:** Mantenedores possuem o contrato do repositório; agentes seguem as instruções instaladas enquanto programam.
|
||||
* **✅ Confiança por verificação:** o trabalho da IA fica mais fácil de confiar porque trabalhos que mudam comportamento incluem uma decisão ou diff de documento de verdade revisável por humanos.
|
||||
|
||||
## 🔄 Como funciona
|
||||
|
||||
Quando um agente de IA modifica seu código, o trabalho não está terminado. O Truthmark instala uma proteção de workflow no fim da tarefa que os agentes seguem antes da entrega:
|
||||
|
||||
1. 💻 **Código:** o agente modifica código funcional.
|
||||
2. 🧪 **Teste:** testes relevantes são executados.
|
||||
3. 🔍 **Verificar:** Truthmark verifica a documentação mapeada como parte da revisão de encerramento instalada.
|
||||
4. 📝 **Documentação:** os docs são atualizados pelo agente quando a verdade do repositório mudou.
|
||||
5. 👀 **Revisão:** uma pessoa revisa o *diff de código* + o *diff de verdade*.
|
||||
|
||||
## 🛠 Como você interage com o Truthmark
|
||||
|
||||
Truthmark tem um contrato local do repositório e duas formas de usá-lo.
|
||||
|
||||
### Pessoas instalam e validam o contrato
|
||||
|
||||
Mantenedores e CI usam a CLI:
|
||||
|
||||
* `truthmark init` - cria ou atualiza a configuração, permite escolher zero ou mais plataformas e instala roteamento, scaffolds de documentos de verdade e instruções dos hosts selecionados.
|
||||
* `truthmark check` - valida a verdade do repositório pelo terminal.
|
||||
|
||||
### Agentes seguem o contrato enquanto programam
|
||||
|
||||
Truthmark instala instruções locais do repositório para hosts de codificação com IA compatíveis, como Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor.
|
||||
|
||||
O ciclo normal é simples:
|
||||
|
||||
1. Peça ao seu agente uma mudança de código ou que documente um comportamento existente.
|
||||
2. As instruções instaladas dizem ao agente quando testar, quando atualizar documentos de verdade e quando parar para revisão humana.
|
||||
3. Você revisa diffs Git comuns: código mais quaisquer mudanças em documentos de verdade.
|
||||
|
||||
As solicitações de agente iniciadas pelo usuário são intencionalmente poucas:
|
||||
|
||||
* `/truthmark-document` - documenta comportamento implementado existente a partir de código e testes.
|
||||
* `/truthmark-realize` - implementa código a partir de documentos de verdade existentes.
|
||||
* `/truthmark-check` - audita a verdade do repositório.
|
||||
|
||||
Truth Sync não é o modo usual de começar trabalho; é a revisão de encerramento após mudanças funcionais de código.
|
||||
Truth Structure não é um comando cotidiano; ele repara roteamento ou propriedade somente quando isso bloqueia o trabalho.
|
||||
O Truthmark instala esses fluxos de trabalho como superfícies nativas do repositório para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor.
|
||||
|
||||
## O que você recebe
|
||||
|
||||
| Capacidade | O que faz |
|
||||
| --- | --- |
|
||||
| Verdade nativa do Git | Mantém a verdade do repositório em Markdown e configuração commitados. |
|
||||
| Documentação com escopo de branch | A verdade se move com a branch em vez de viver em uma sessão privada. |
|
||||
| CLI humana | Dá aos mantenedores comandos de configuração, atualização, validação e inspeção. |
|
||||
| Orientação de agente instalada | Diz aos agentes de codificação quando documentar, testar, sincronizar verdade, auditar ou parar para revisão. |
|
||||
| Roteamento explícito | Mapeia áreas de código para documentos de verdade canônicos. |
|
||||
| Entregas revisáveis | Produz diffs Git comuns tanto para código quanto para documentos de verdade. |
|
||||
| Operação local-first | Não requer serviço hospedado, daemon, banco de dados nem servidor MCP. |
|
||||
| Limites de escrita mais seguros | Separa workflows code-first, doc-first, read-only e doc-only. |
|
||||
| Validação | Relata problemas de roteamento, autoridade, frontmatter, links, superfícies geradas, escopo de branch, frescor e cobertura. |
|
||||
| Portal opcional | Gera, quando explicitamente ativado e solicitado, um site estático HTML commitado a partir de documentos de verdade em Markdown. |
|
||||
### Documentação que parte da realidade
|
||||
|
||||
## Visão geral visual
|
||||
O Truthmark pode criar documentação de recursos do produto, comportamento da implementação, interfaces de programação de aplicações, arquitetura, fluxos de trabalho, operações e testes. Código e testes fornecem as evidências; documentos Markdown delimitados preservam o resultado.
|
||||
|
||||
|
||||
### Documentação que resiste à próxima mudança
|
||||
|
||||
**Recursos:** o que o Truthmark instala e como a superfície de workflow é dividida.
|
||||
As rotas conectam áreas de código a documentos canônicos. Quando agentes alteram o comportamento, o Truth Sync sabe onde a verdade correspondente deve ficar e mantém a entrega pronta para revisão.
|
||||
|
||||
|
||||
### Verdade de produto e engenharia em faixas separadas
|
||||
|
||||
**Posição:** onde o Truthmark se encaixa em relação a prompts, memória e workflows de especificação.
|
||||
A verdade de produto registra promessas voltadas ao usuário, limites, decisões e critérios de aceitação. A verdade de engenharia registra o comportamento atual, contratos, arquitetura, fluxos de trabalho, operações e comportamento dos testes.
|
||||
|
||||
|
||||
### Colaboração nativa do Git
|
||||
|
||||
**Fluxo de sincronização:** como o Truth Sync conclui mudanças normais de código antes da entrega.
|
||||
Tudo que importa vive em arquivos versionados do repositório. A verdade acompanha a branch, funciona com pull requests comuns e permanece visível para cada mantenedor e agente de programação.
|
||||
|
||||
## Por que equipes o adotam
|
||||
### Operação local-first
|
||||
|
||||
Truthmark é para equipes que já sabem que agentes de IA podem gerar código.
|
||||
|
||||
O próximo problema é governança.
|
||||
|
||||
Não governança como cerimônia. Governança como uma pergunta simples:
|
||||
|
||||
> Depois desta mudança assistida por IA, o repositório ainda diz a verdade?
|
||||
|
||||
Truthmark ajuda equipes a responder isso com arquivos commitados, roteamento explícito e diffs revisáveis.
|
||||
|
||||
Ele é útil quando você precisa de:
|
||||
|
||||
- menos desvio de documentação
|
||||
- melhores entregas
|
||||
- verdade de produto específica por branch
|
||||
- documentação duradoura de arquitetura e API
|
||||
- ownership explícito entre docs e código
|
||||
- limites de escrita de agentes mais seguros
|
||||
- documentação revisável em vez de memória oculta
|
||||
- orientação de agente que ainda funciona a partir de arquivos commitados no repositório
|
||||
O Truthmark não precisa de serviço hospedado, daemon, banco de dados, banco vetorial ou servidor do Model Context Protocol. O repositório carrega seu próprio fluxo de trabalho de documentação.
|
||||
|
||||
## Onde o Truthmark se encaixa
|
||||
|
||||
Truthmark não substitui prompts, memória, specs, testes nem revisão de código.
|
||||
| Necessidade | Melhor opção |
|
||||
| ------------------------------------------------------- | ------------------------------------- |
|
||||
| Melhor resultado de uma sessão de agente | Um prompt melhor |
|
||||
| Continuidade pessoal ou no nível da sessão | Uma ferramenta de memória |
|
||||
| Desenvolvimento de recursos que começa por um plano | Um fluxo de trabalho de especificação |
|
||||
| Documentação no escopo da branch que viaja com o código | **Truthmark** |
|
||||
| Correção do comportamento | Testes e revisão de código |
|
||||
| Documentação assistida por IA e revisável | **Truthmark + revisão no Git** |
|
||||
|
||||
Ele dá a esses workflows um lugar durável para pousar no Git.
|
||||
O Truthmark foi criado para mantenedores e equipes de engenharia que já usam agentes de programação com IA e querem que o repositório continue dizendo a verdade na mesma velocidade em que o código muda.
|
||||
|
||||
| Necessidade | Melhor encaixe |
|
||||
| --- | --- |
|
||||
| Melhor saída de uma sessão de agente | Prompt melhor |
|
||||
| Continuidade pessoal ou no nível da sessão | Ferramenta de memória |
|
||||
| Trabalho de funcionalidade com plano primeiro | Workflow de especificação |
|
||||
| Verdade com escopo de branch que viaja com o código | Truthmark |
|
||||
| Validar correção de comportamento | Testes e revisão |
|
||||
| Revisar mudanças de documentação assistidas por IA | Truthmark mais revisão Git |
|
||||
## Hosts compatíveis e linha de comando
|
||||
|
||||
A faixa de atuação do Truthmark é estreita por design:
|
||||
Hosts de agentes compatíveis:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
instalar orientação de agente ao redor dela
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Aprofunde-se
|
||||
<details>
|
||||
<summary>Referência da linha de comando</summary>
|
||||
|
||||
O README é a vitrine: contexto rápido, início rápido e o modelo mental central.
|
||||
| Comando | Finalidade |
|
||||
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Cria ou atualiza a configuração, o roteamento, os templates e os fluxos de trabalho dos hosts selecionados |
|
||||
| `truthmark check [--base <ref>]` | Valida a verdade do repositório e, opcionalmente, executa diagnósticos de atualidade da branch |
|
||||
| `truthmark index --json` | Inspeciona metadados derivados do repositório e do roteamento |
|
||||
| `truthmark impact --base <ref> --json` | Mapeia arquivos alterados para documentos, proprietários e testes próximos |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Inspeciona a aplicabilidade e os alvos do fluxo de trabalho |
|
||||
| `truthmark validate ...` | Valida relatórios de fluxos de trabalho e concessões de escrita |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Visualiza ou remove superfícies de host geradas, preservando a verdade criada |
|
||||
|
||||
Para uso comando por comando, comparações de superfícies, detalhes de plataformas compatíveis, configuração, roteamento, Portal e exemplos, leia o [guia do usuário do Truthmark](../user-guide.md).
|
||||
A saída JSON estruturada está disponível em toda a interface de linha de comando para scripts e integração contínua.
|
||||
|
||||
## Status do projeto
|
||||
</details>
|
||||
|
||||
A versão atual fornece:
|
||||
## Saiba mais
|
||||
|
||||
- comandos CLI locais para init, check, index, impact e status de workflows
|
||||
- instruções de agente locais do repositório geradas para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor
|
||||
- diagnósticos de roteamento, autoridade, frontmatter, links, frescor, superfícies geradas, escopo de branch e cobertura
|
||||
- documentos de verdade com escopo de branch e artefatos derivados de inteligência do repositório
|
||||
- [Guia do usuário do Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Índice da documentação](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Visão geral da arquitetura](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Contratos de configuração, roteamento e comandos](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Manutenção da verdade do repositório](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Como contribuir](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Documentação
|
||||
|
||||
- [Guia do usuário](../user-guide.md)
|
||||
- [Índice de docs](../README.md)
|
||||
- [Visão geral da arquitetura](../truthmark/engineering/architecture/overview.md)
|
||||
- [Contratos de API e CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Guia de manutenção da verdade do repositório](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Para comandos de desenvolvimento local e contribuição, consulte [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Limites de design
|
||||
|
||||
Truthmark é intencionalmente pequeno: local, commitado, com escopo de branch e revisável.
|
||||
|
||||
Ele não é um serviço hospedado, servidor MCP, banco de dados vetorial, camada de memória oculta, produto de enforcement de CI nem motor autônomo de reescrita de código. Ele ajuda a verdade do repositório a permanecer visível; não substitui testes, revisão de código nem julgamento humano.
|
||||
**Instale o Truthmark, selecione seu host de programação e transforme hoje um comportamento real em documentação.**
|
||||
|
||||
## Licença
|
||||
|
||||
MIT. Veja [LICENSE](../../LICENSE).
|
||||
|
||||
## Remoção segura
|
||||
|
||||
Use `truthmark uninstall --dry-run` para revisar as superfícies de host geradas com precisão, e depois `truthmark uninstall --apply` para removê-las. Truth criada, configuração, templates, saída do Portal, arquivos Gemini e arquivos de usuário não relacionados são preservados; remova uma instalação global de npm separadamente com seu gerenciador de pacotes.
|
||||
MIT. Consulte [LICENSE](../../LICENSE).
|
||||
|
||||
+130
-155
@@ -2,219 +2,194 @@
|
||||
|
||||
**Ваши агенты пишут код. Truthmark поддерживает понятную людям документацию, которую можно проверять в Git.**
|
||||
|
||||
Truthmark устанавливает нативные для Git рабочие процессы, с помощью которых AI-агенты разработки создают новую продуктовую и инженерную документацию на основе существующего кода и тестов, актуализируют её после каждого изменения кода и предоставляют вам обычные Markdown-диффы для проверки.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Начать работу](#быстрый-старт-создайте-свой-первый-truth-документ) · [Сайт](https://merlinhu1.github.io/truthmark/) · [Руководство пользователя](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Читайте этот README на 16 языках</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Быстрый старт: локальный запуск за пять минут
|
||||
## Создайте первые документы. Поддерживайте их достоверность.
|
||||
|
||||
Выполните это внутри Git-репозитория, которым должен управлять Truthmark:
|
||||
Большинство инструментов документирования останавливаются после генерации. Truthmark предоставляет агентам полный жизненный цикл документации прямо в вашем репозитории:
|
||||
|
||||
- **Создавайте новую документацию на основе работающего ПО.** Truth Document анализирует код и тесты, а затем создаёт ограниченную по области продуктовую или инженерную документацию.
|
||||
- **Автоматически поддерживайте соответствие документации.** Truth Sync запускается при передаче работы агентом после функциональных изменений кода и обновляет достоверные сведения репозитория до завершения задачи.
|
||||
- **Превращайте документацию обратно в код.** Truth Realize реализует утверждённые truth-документы, сохраняя чистый подход от документации к коду.
|
||||
- **Восстанавливайте владение по мере роста кодовой базы.** Truth Structure создаёт ограниченные маршруты и начальные документы для новых или перегруженных областей.
|
||||
- **Проверяйте всё в Git.** Код, решения, контракты, архитектура, эксплуатация и поведение перемещаются вместе с веткой.
|
||||
|
||||
Никаких размещённых в облаке баз знаний. Никакой закрытой памяти агентов. Никакой документации, запертой в истории чатов.
|
||||
|
||||
## Быстрый старт: создайте свой первый truth-документ
|
||||
|
||||
**Требования:** Node.js 24 или новее, Git-репозиторий и поддерживаемый AI-хост разработки для агентских рабочих процессов.
|
||||
|
||||
Выполните следующие команды в репозитории, которым должен управлять Truthmark:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` позволяет выбрать Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor или нейтральную к хосту настройку интерфейса командной строки.
|
||||
|
||||
Теперь попросите настроенного агента задокументировать одно реальное поведение:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document создаёт новый ограниченный по области truth-документ, если его ещё нет, обновляет существующий документ-владелец, если он есть, и при необходимости обновляет маршрутизацию. Функциональный код при этом не изменяется.
|
||||
|
||||
Проверьте результат:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
В интерактивном терминале `truthmark init` показывает нумерованный множественный выбор. Выберите ноль или несколько платформ либо введите `none` для нейтральной к хосту настройки только с CLI.
|
||||
Теперь у вас должны появиться:
|
||||
|
||||
В скриптах и CI повторяйте `--platform`; `--json` никогда не показывает запрос:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Точные пути определяются структурой владения вашего репозитория. Новые файлы отображаются в `git status`, а изменения отслеживаемых файлов — в `git diff`.
|
||||
|
||||
Способ запуска зависит от хоста. OpenCode использует `/skill truthmark-document`, Antigravity — `@truthmark-document`, а другие поддерживаемые хосты используют свои нативные интерфейсы навыков или slash-команд. Точные команды приведены в [таблице платформ](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms).
|
||||
|
||||
Для скриптов и непрерывной интеграции передавайте выбранные платформы явно:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
При первом неинтерактивном запуске без `--platform` настройка остаётся нейтральной; последующие запуски сохраняют выбор из `.truthmark/config.yml`.
|
||||
Выберите `none` в интерактивном режиме или выполните `truthmark init --clear-platforms`, чтобы репозиторий оставался нейтральным к хосту. Платформы агентов можно добавить позже, повторно запустив `truthmark init`.
|
||||
|
||||
Теперь попробуйте самый распространенный путь внедрения: задокументируйте одно существующее поведение по коду и тестам. В вашем AI-хосте для разработки попросите установленный рабочий процесс:
|
||||
Для диагностики актуальности относительно ветки передайте базовую ссылку Git:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
После этого пользователям обычно не следует напрямую вызывать Truth Sync. Продолжайте писать код через ваш AI-хост; установленные инструкции репозитория скажут агенту запускать релевантные тесты и выполнять проверку Truth Sync перед передачей, когда меняется функциональный код. Вы просматриваете получившийся diff кода вместе с diff truth-документов.
|
||||
## Как работает Truthmark
|
||||
|
||||
Если нужна только CLI-валидация, выберите `none` и выполните `truthmark check`; позже можно снова выполнить `truthmark init` и выбрать платформы.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Как работает Truthmark" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 Проблема: разрыв в AI-документации
|
||||
Интерфейс командной строки Truthmark устанавливает и проверяет контракт репозитория. Ваш агент разработки анализирует доказательства и работает с документацией через установленные нативные для хоста рабочие процессы.
|
||||
|
||||
AI-агенты разработки невероятно быстро пишут код. Но эта скорость создает новый опасный режим отказа: **история репозитория начинает расходиться с реальностью.**
|
||||
Обычное изменение кода проходит по простому циклу:
|
||||
|
||||
* Поведение теряется в эфемерных историях чатов.
|
||||
* Архитектурная документация быстро устаревает.
|
||||
* Продуктовые решения исчезают после передачи работы.
|
||||
* Ревьюерам кода приходится изучать сырые diff кода без понимания «почему».
|
||||
* Каждая новая AI-сессия вынуждена заново обнаруживать truth репозитория.
|
||||
1. Агент изменяет функциональный код.
|
||||
2. Запускаются соответствующие тесты.
|
||||
3. Truth Sync проверяет связанную документацию.
|
||||
4. Если достоверные сведения репозитория изменились, агент создаёт или обновляет документацию и маршрутизацию.
|
||||
5. Вы вместе проверяете дифф кода и дифф достоверной документации.
|
||||
|
||||
## 🎯 Решение: Truthmark
|
||||
## Рабочие процессы
|
||||
|
||||
**Truthmark** устанавливает в ваш репозиторий Git-native слой рабочего процесса. Он исправляет ту часть AI-разработки, которая обычно ломается: помогает документации оставаться согласованной с кодом.
|
||||
| Рабочий процесс | Когда использовать | Результат |
|
||||
| -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| **Truth Document** | Существующему коду нужна документация | Создаёт или обновляет продуктовую и инженерную документацию, основанную на доказательствах |
|
||||
| **Truth Sync** | Изменился функциональный код | До передачи работы синхронизирует связанную документацию и маршрутизацию |
|
||||
| **Truth Structure** | Новой области нужен владелец или существующая документация стала слишком широкой | Создаёт ограниченные маршруты и каркасы начальных документов |
|
||||
| **Truth Realize** | Утверждённый truth-документ должен стать работающим ПО | Обновляет функциональный код на основе документации |
|
||||
| **Truth Check** | Достоверность репозитория нужно проверить | Сообщает о проблемах маршрутизации, владения, доказательств и документации |
|
||||
| **Truthmark Portal** | Команде нужен удобный для просмотра сайт документации | Создаёт версионируемое статическое HTML-представление на основе truth-документов Markdown |
|
||||
|
||||
Вместо надежды на то, что люди и AI-агенты вспомнят об обновлении документации, Truthmark делает документирование системной и проверяемой привычкой прямо внутри репозитория.
|
||||
|
||||
### ✨ Почему Truthmark уникален
|
||||
|
||||
Truthmark — не просто очередной инструмент документации. Он глубоко интегрирован в AI workflow:
|
||||
|
||||
* **🚫 Никакой привязки к поставщику:** нет hosted-сервисов, скрытых баз данных и дополнительных серверов для эксплуатации.
|
||||
* **🌳 100% Git-native:** всё находится в вашем репозитории. Truth движется вместе с веткой.
|
||||
* **🤝 Контракт, принадлежащий людям и выполняемый агентами:** Мейнтейнеры владеют контрактом репозитория; агенты следуют установленным инструкциям во время кодинга.
|
||||
* **✅ Доверие через проверку:** AI-работе проще доверять, потому что работа, меняющая поведение, включает human-reviewable решение или diff в truth-doc.
|
||||
|
||||
## 🔄 Как это работает
|
||||
|
||||
Когда AI-агент меняет ваш код, работа еще не завершена. Truthmark устанавливает guard рабочего процесса на момент завершения, которому агенты следуют перед передачей:
|
||||
|
||||
1. 💻 **Код:** агент изменяет функциональный код.
|
||||
2. 🧪 **Тест:** выполняются релевантные тесты.
|
||||
3. 🔍 **Проверка:** Truthmark проверяет сопоставленную документацию как часть установленного завершающего ревью.
|
||||
4. 📝 **Документирование:** агент обновляет docs, когда truth репозитория изменился.
|
||||
5. 👀 **Ревью:** человек проверяет *diff кода* + *diff truth*.
|
||||
|
||||
## 🛠 Как вы взаимодействуете с Truthmark
|
||||
|
||||
У Truthmark есть один локальный контракт репозитория и два способа его использовать.
|
||||
|
||||
### Люди устанавливают и проверяют контракт
|
||||
|
||||
Мейнтейнеры и CI используют CLI:
|
||||
|
||||
* `truthmark init` - создаёт или обновляет конфигурацию, позволяет выбрать ноль или несколько платформ и устанавливает маршруты, scaffold для truth-doc и инструкции выбранных AI-хостов.
|
||||
* `truthmark check` - проверяет truth репозитория из терминала.
|
||||
|
||||
### Агенты следуют контракту во время кодинга
|
||||
|
||||
Truthmark устанавливает локальные инструкции репозитория для поддерживаемых AI coding hosts, таких как Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor.
|
||||
|
||||
Обычный цикл прост:
|
||||
|
||||
1. Попросите агента изменить код или задокументировать существующее поведение.
|
||||
2. Установленные инструкции говорят агенту, когда тестировать, когда обновлять truth docs и когда остановиться для человеческого ревью.
|
||||
3. Вы ревьюите обычные Git diff: код плюс любые изменения truth-doc.
|
||||
|
||||
Пользовательских запросов к агенту намеренно мало:
|
||||
|
||||
* `/truthmark-document` - документирует существующее реализованное поведение по коду и тестам.
|
||||
* `/truthmark-realize` - реализует код из существующих truth docs.
|
||||
* `/truthmark-check` - аудитирует truth репозитория.
|
||||
|
||||
Truth Sync — не обычный способ начать работу; это завершающее ревью после функциональных изменений кода.
|
||||
Truth Structure — не повседневная команда; она исправляет routing или ownership только тогда, когда это блокирует работу.
|
||||
Truthmark устанавливает эти рабочие процессы как нативные поверхности репозитория для Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor.
|
||||
|
||||
## Что вы получаете
|
||||
|
||||
| Возможность | Что она делает |
|
||||
| --- | --- |
|
||||
| Git-native truth | Хранит truth репозитория в закоммиченных Markdown и конфигурации. |
|
||||
| Документация в пределах ветки | Truth движется с веткой, а не живет в приватной сессии. |
|
||||
| CLI для людей | Дает мейнтейнерам команды настройки, обновления, валидации и инспекции. |
|
||||
| Установленные инструкции агента | Говорит coding-агентам, когда документировать, тестировать, синхронизировать truth, аудитировать или останавливаться для ревью. |
|
||||
| Явная маршрутизация | Сопоставляет области кода с каноническими truth-docs. |
|
||||
| Проверяемая передача | Создает обычные Git diff как для кода, так и для truth-docs. |
|
||||
| Local-first работа | Не требует hosted-сервиса, daemon, базы данных или MCP-сервера. |
|
||||
| Более безопасные границы записи | Разделяет code-first, doc-first, read-only и doc-only workflows. |
|
||||
| Валидация | Сообщает о проблемах routing, authority, frontmatter, links, generated-surface, branch-scope, freshness и coverage. |
|
||||
| Опциональный Portal | Генерирует закоммиченный статический HTML-сайт презентации из Markdown truth-docs, когда он явно включен и запрошен. |
|
||||
### Документация, основанная на реальности
|
||||
|
||||
## Визуальный обзор
|
||||
Truthmark умеет создавать документацию о возможностях продукта, поведении реализации, программных интерфейсах приложений, архитектуре, рабочих процессах, эксплуатации и тестах. Код и тесты дают доказательства, а ограниченные по области документы Markdown сохраняют результат.
|
||||
|
||||
|
||||
### Документация, которая переживает следующее изменение
|
||||
|
||||
**Возможности:** что устанавливает Truthmark и как агенты используют локальные инструкции репозитория.
|
||||
Маршруты связывают области кода с канонической документацией. Когда агенты меняют поведение, Truth Sync знает, где должны находиться соответствующие достоверные сведения, и сохраняет результат удобным для проверки.
|
||||
|
||||
|
||||
### Продуктовая и инженерная истина в отдельных потоках
|
||||
|
||||
**Позиция:** где Truthmark находится относительно prompts, memory и spec workflows.
|
||||
Продуктовая истина фиксирует обещания пользователям, границы, решения и критерии приёмки. Инженерная истина фиксирует текущее поведение, контракты, архитектуру, рабочие процессы, эксплуатацию и поведение тестов.
|
||||
|
||||
|
||||
### Нативная для Git совместная работа
|
||||
|
||||
**Поток синхронизации:** как Truth Sync завершает обычные изменения кода перед передачей.
|
||||
Всё важное находится в версионируемых файлах репозитория. Истина следует за веткой, работает с обычными pull request и остаётся видимой каждому сопровождающему и агенту разработки.
|
||||
|
||||
## Почему команды выбирают его
|
||||
### Локальная работа прежде всего
|
||||
|
||||
Truthmark создан для команд, которые уже знают, что AI-агенты могут генерировать код.
|
||||
|
||||
Следующая проблема — governance.
|
||||
|
||||
Не governance как церемония. Governance как простой вопрос:
|
||||
|
||||
> После этого AI-assisted изменения репозиторий все еще говорит truth?
|
||||
|
||||
Truthmark помогает командам отвечать на это с помощью закоммиченных файлов, явной маршрутизации и проверяемых diff.
|
||||
|
||||
Он полезен, когда вам нужны:
|
||||
|
||||
- меньший дрейф документации
|
||||
- лучшая передача работы
|
||||
- branch-specific продуктовая truth
|
||||
- долговечная архитектурная и API-документация
|
||||
- явное владение между docs и кодом
|
||||
- более безопасные границы записи для агентов
|
||||
- проверяемая документация вместо скрытой memory
|
||||
- инструкции для агентов, которые продолжают работать из закоммиченных файлов репозитория
|
||||
Truthmark не нужны размещённый сервис, фоновый процесс, база данных, векторное хранилище или сервер Model Context Protocol. Репозиторий содержит собственный рабочий процесс документирования.
|
||||
|
||||
## Где уместен Truthmark
|
||||
|
||||
Truthmark не заменяет prompts, memory, specs, tests или code review.
|
||||
| Потребность | Лучшее решение |
|
||||
| ---------------------------------------------------------------- | ------------------------------ |
|
||||
| Более качественный результат одной сессии агента | Улучшенный промпт |
|
||||
| Непрерывность на личном уровне или уровне сессии | Инструмент памяти |
|
||||
| Разработка функций, начинающаяся с плана | Рабочий процесс спецификаций |
|
||||
| Документация в рамках ветки, которая перемещается вместе с кодом | **Truthmark** |
|
||||
| Корректность поведения | Тесты и проверка кода |
|
||||
| Проверяемая документация, созданная с помощью ИИ | **Truthmark + проверка в Git** |
|
||||
|
||||
Он дает этим workflows долговечное место для фиксации в Git.
|
||||
Truthmark создан для сопровождающих и инженерных команд, которые уже используют AI-агентов разработки и хотят, чтобы репозиторий продолжал говорить правду так же быстро, как меняется код.
|
||||
|
||||
| Потребность | Лучше подходит |
|
||||
| --- | --- |
|
||||
| Лучший результат из одной сессии агента | Лучший prompt |
|
||||
| Персональная или сессионная непрерывность | Memory tool |
|
||||
| Plan-first работа над функцией | Spec workflow |
|
||||
| Branch-scoped truth, которая перемещается вместе с кодом | Truthmark |
|
||||
| Проверка корректности поведения | Tests and review |
|
||||
| Ревью изменений документации, выполненных с AI | Truthmark плюс Git review |
|
||||
## Поддерживаемые хосты и командная строка
|
||||
|
||||
Область Truthmark намеренно узкая:
|
||||
Поддерживаемые хосты агентов:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
установить вокруг нее инструкции для агентов
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Подробнее
|
||||
<details>
|
||||
<summary>Справочник командной строки</summary>
|
||||
|
||||
README — это витрина: быстрый контекст, быстрый старт и основная ментальная модель.
|
||||
| Команда | Назначение |
|
||||
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Создаёт или обновляет конфигурацию, маршрутизацию, шаблоны и рабочие процессы выбранных хостов |
|
||||
| `truthmark check [--base <ref>]` | Проверяет достоверность репозитория и при необходимости запускает диагностику актуальности ветки |
|
||||
| `truthmark index --json` | Показывает производные метаданные репозитория и маршрутизации |
|
||||
| `truthmark impact --base <ref> --json` | Сопоставляет изменённые файлы с документацией, владельцами и ближайшими тестами |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Показывает применимость и цели рабочего процесса |
|
||||
| `truthmark validate ...` | Проверяет отчёты рабочих процессов и разрешения на запись |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Предварительно показывает или удаляет созданные поверхности хостов, сохраняя авторскую truth-документацию |
|
||||
|
||||
Для пошагового использования команд, сравнения поверхностей, деталей поддерживаемых платформ, конфигурации, маршрутизации, Portal и примеров читайте [руководство пользователя Truthmark](../user-guide.md).
|
||||
Структурированный вывод JSON доступен во всём интерфейсе командной строки для скриптов и непрерывной интеграции.
|
||||
|
||||
## Статус проекта
|
||||
</details>
|
||||
|
||||
Текущий релиз предоставляет:
|
||||
## Дополнительные материалы
|
||||
|
||||
- локальные CLI-команды для init, check, index, impact и workflow status
|
||||
- сгенерированные локальные инструкции агента для Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor
|
||||
- диагностику route, authority, frontmatter, links, freshness, generated-surface, branch-scope и coverage
|
||||
- branch-scoped truth docs и производные артефакты repository intelligence
|
||||
- [Руководство пользователя Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Индекс документации](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Обзор архитектуры](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Контракты конфигурации, маршрутизации и команд](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Поддержание достоверности репозитория](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Участие в разработке](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Документация
|
||||
|
||||
- [Руководство пользователя](../user-guide.md)
|
||||
- [Индекс документации](../README.md)
|
||||
- [Обзор архитектуры](../truthmark/engineering/architecture/overview.md)
|
||||
- [Контракты API и CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Руководство по поддержанию repository truth](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Команды для локальной разработки и участия см. в [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Границы дизайна
|
||||
|
||||
Truthmark намеренно мал: локальный, закоммиченный, scoped по ветке и проверяемый.
|
||||
|
||||
Это не hosted-сервис, MCP-сервер, векторная база данных, скрытый слой memory, продукт для принудительного CI-контроля или автономный движок переписывания кода. Он помогает truth репозитория оставаться видимой; он не заменяет tests, code review или человеческое суждение.
|
||||
**Установите Truthmark, выберите хост разработки и уже сегодня превратите реальное поведение в документацию.**
|
||||
|
||||
## Лицензия
|
||||
|
||||
MIT. См. [LICENSE](../../LICENSE).
|
||||
|
||||
## Безопасное удаление
|
||||
|
||||
Используйте `truthmark uninstall --dry-run` для проверки точно сгенерированных host-поверхностей, затем `truthmark uninstall --apply` для их удаления. Сформированные truth, конфигурация, шаблоны, вывод Portal, файлы Gemini и несвязанные пользовательские файлы сохраняются; глобальную установку npm удаляйте отдельно через менеджер пакетов.
|
||||
|
||||
+131
-156
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**Ajanlarınız kod yazar. Truthmark, insanlara yönelik ve Git üzerinden incelenebilir belgeleri korur.**
|
||||
**Ajanlarınız kod yazar. Truthmark, insanlara yönelik ve Git üzerinden incelenebilir belgeleri güncel tutar.**
|
||||
|
||||
Truthmark, AI kodlama ajanlarının mevcut kod ve testlerden yeni ürün ve mühendislik belgeleri oluşturmasını, her kod değişikliğinden sonra bunları güncel tutmasını ve incelemeniz için sıradan Markdown farkları sunmasını sağlayan Git'e özgü iş akışlarını kurar.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Başlayın](#hızlı-başlangıç-ilk-truth-belgenizi-oluşturun) · [Web sitesi](https://merlinhu1.github.io/truthmark/) · [Kullanıcı kılavuzu](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Bu README'yi 16 dilden birinde okuyun</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Hızlı Başlangıç: beş dakikada yerelde çalıştırma
|
||||
## İlk belgeleri oluşturun. Doğru kalmalarını sağlayın.
|
||||
|
||||
Bunu Truthmark tarafından yönetilmesini istediğiniz Git deposunun içinde çalıştırın:
|
||||
Çoğu dokümantasyon aracı üretimden sonra durur. Truthmark, ajanlara doğrudan deponuzun içinde eksiksiz bir dokümantasyon yaşam döngüsü sunar:
|
||||
|
||||
- **Çalışan yazılımdan yeni belgeler oluşturun.** Truth Document kodu ve testleri okur, ardından sınırları belirli ürün veya mühendislik belgeleri oluşturur.
|
||||
- **Belgeleri otomatik olarak uyumlu tutun.** Truth Sync, işlevsel kod değişikliklerinden sonra ajan tesliminde çalışır ve iş tamamlanmadan önce depo gerçeğini günceller.
|
||||
- **Belgeleri yeniden koda dönüştürün.** Truth Realize, temiz bir doc-first iş akışını korurken onaylanmış truth belgelerini uygular.
|
||||
- **Kod tabanı büyürken sahipliği onarın.** Truth Structure, yeni veya aşırı yüklenmiş alanlar için sınırları belirli rotalar ve başlangıç belgeleri oluşturur.
|
||||
- **Her şeyi Git'te inceleyin.** Kod, kararlar, sözleşmeler, mimari, operasyonlar ve davranış aynı dalla birlikte ilerler.
|
||||
|
||||
Barındırılan bilgi tabanı yok. Özel ajan belleği yok. Sohbet geçmişine hapsolmuş dokümantasyon yok.
|
||||
|
||||
## Hızlı başlangıç: ilk truth belgenizi oluşturun
|
||||
|
||||
**Gereksinimler:** Node.js 24 veya daha yenisi, bir Git deposu ve ajan iş akışları için desteklenen bir AI kodlama ana bilgisayarı.
|
||||
|
||||
Aşağıdaki komutları Truthmark'ın yönetmesini istediğiniz deponun içinde çalıştırın:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init`; Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor veya ana bilgisayardan bağımsız bir komut satırı arayüzü kurulumu seçmenizi sağlar.
|
||||
|
||||
Şimdi yapılandırılmış ajanınızdan gerçek bir davranışı belgelemesini isteyin:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document, henüz yoksa sınırları belirli yeni bir truth belgesi oluşturur; varsa mevcut sahibini günceller ve gerektiğinde yönlendirmeyi yeniler. İşlevsel kodu değiştirmez.
|
||||
|
||||
Sonucu inceleyin:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
Etkileşimli bir terminalde `truthmark init`, numaralı bir çoklu seçim gösterir. Sıfır veya daha fazla platform seçin ya da ana makineden bağımsız, yalnızca CLI kurulumu için `none` girin.
|
||||
Artık şunlara sahip olmalısınız:
|
||||
|
||||
Betikler ve CI için `--platform` seçeneğini tekrarlayın; `--json` hiçbir zaman istem göstermez:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Kesin yollar, deponuzun sahiplik yapısını izler. Yeni dosyalar `git status` içinde, izlenen dosyalardaki değişiklikler ise `git diff` içinde görünür.
|
||||
|
||||
Çağırma biçimi ana bilgisayara göre değişir. OpenCode `/skill truthmark-document`, Antigravity `@truthmark-document` kullanır; desteklenen diğer ana bilgisayarlar ise kendi yerel beceri veya eğik çizgi komutu yüzeylerini kullanır. Kesin komutlar için [platform tablosuna](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) bakın.
|
||||
|
||||
Betikler ve sürekli entegrasyon için seçilen platformları açıkça iletin:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
`--platform` olmadan ilk etkileşimsiz çalıştırmada kurulum ana makineden bağımsız kalır; sonraki çalıştırmalar `.truthmark/config.yml` içinde kayıtlı seçimi korur.
|
||||
Ana bilgisayardan bağımsız bir depo için etkileşimli olarak `none` seçin veya `truthmark init --clear-platforms` çalıştırın. Daha sonra `truthmark init` komutunu yeniden çalıştırarak ajan platformları ekleyebilirsiniz.
|
||||
|
||||
Şimdi en yaygın benimseme yolunu deneyin: kod ve testlerden mevcut bir davranışı belgeleyin. AI kodlama ana makinenizde, kurulu iş akışına şunu isteyin:
|
||||
Dala göre güncellik tanılaması için bir Git tabanı iletin:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Bundan sonra kullanıcılar normalde Truth Sync'i doğrudan çağırmamalıdır. AI ana makineniz üzerinden kod yazmaya devam edin; kurulu depo yönergeleri, işlevsel kod değiştiğinde teslimden önce ajana ilgili testleri çalıştırmasını ve Truth Sync incelemesini yapmasını söyler. Siz ortaya çıkan kod farkını ve truth-belge farkını incelersiniz.
|
||||
## Truthmark nasıl çalışır
|
||||
|
||||
Yalnızca CLI doğrulaması istiyorsanız `none` seçip `truthmark check` çalıştırın; platform seçmek için daha sonra `truthmark init` komutunu yeniden çalıştırabilirsiniz.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Truthmark nasıl çalışır" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 Sorun: AI dokümantasyon boşluğu
|
||||
Truthmark komut satırı arayüzü depo sözleşmesini kurar ve doğrular. Kodlama ajanınız, kurulu ve ana bilgisayara özgü iş akışları üzerinden kanıt incelemesini ve dokümantasyon çalışmasını gerçekleştirir.
|
||||
|
||||
AI kodlama ajanları hızlı kod yazma konusunda olağanüstüdür. Ancak bu hız tehlikeli yeni bir hata biçimi yaratır: **deponun anlattığı hikâye gerçeklikten uzaklaşır.**
|
||||
Normal bir kod değişikliği tek ve basit bir döngü izler:
|
||||
|
||||
* Davranış, geçici sohbet geçmişlerinde kaybolur.
|
||||
* Mimari belgeleri hızla geride kalır.
|
||||
* Ürün kararları teslimden sonra kaybolur.
|
||||
* Kod inceleyenler, "neden"i anlamadan ham kod farklarını incelemek zorunda kalır.
|
||||
* Her yeni AI oturumu, deponuzun gerçeğini sıfırdan yeniden keşfetmeye zorlanır.
|
||||
1. Ajan işlevsel kodu değiştirir.
|
||||
2. İlgili testler çalıştırılır.
|
||||
3. Truth Sync, eşlenen belgeleri kontrol eder.
|
||||
4. Depo gerçeği değiştiğinde ajan belgeleri ve yönlendirmeyi oluşturur veya günceller.
|
||||
5. Kod farkını ve truth farkını birlikte incelersiniz.
|
||||
|
||||
## 🎯 Çözüm: Truthmark
|
||||
## İş akışları
|
||||
|
||||
**Truthmark**, deponuza Git'e özgü bir iş akışı katmanı kurar. AI geliştirmesinde genellikle bozulan kısmı düzeltir: belgelerin kodla uyumlu kalmasına yardımcı olmak.
|
||||
| İş akışı | Ne zaman kullanılır | Sonuç |
|
||||
| -------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| **Truth Document** | Mevcut kodun belgelenmesi gerekir | Kanıta dayalı ürün ve mühendislik belgeleri oluşturur veya günceller |
|
||||
| **Truth Sync** | İşlevsel kod değişmiştir | Teslimden önce eşlenen belgeleri ve yönlendirmeyi uyumlu tutar |
|
||||
| **Truth Structure** | Yeni bir alanın sahipliğe ihtiyacı vardır veya mevcut belgeler fazla geniştir | Sınırları belirli rotalar ve iskelet başlangıç belgeleri oluşturur |
|
||||
| **Truth Realize** | Onaylanmış bir truth belgesi çalışan yazılıma dönüşmelidir | İşlevsel kodu dokümantasyondan günceller |
|
||||
| **Truth Check** | Depo gerçeğinin denetlenmesi gerekir | Yönlendirme, sahiplik, kanıt ve dokümantasyon sorunlarını bildirir |
|
||||
| **Truthmark Portal** | Ekip, göz atılabilir bir dokümantasyon sitesi ister | Markdown truth belgelerinden commit edilmiş statik bir HTML sunumu üretir |
|
||||
|
||||
İnsanların ve AI ajanlarının belgeleri güncellemeyi hatırlamasını ummak yerine, Truthmark dokümantasyonu doğrudan deponuzun içinde sistematik ve incelenebilir bir alışkanlığa dönüştürür.
|
||||
|
||||
### ✨ Truthmark neden benzersizdir
|
||||
|
||||
Truthmark sıradan bir dokümantasyon aracı değildir. AI iş akışına derinlemesine entegredir:
|
||||
|
||||
* **🚫 Tedarikçi kilidi yok:** Barındırılan hizmet yok, gizli veritabanı yok, işletilecek ek sunucu yok.
|
||||
* **🌳 %100 Git'e özgü:** Her şey deponuzda yaşar. Gerçek, dalınızla birlikte hareket eder.
|
||||
* **🤝 İnsanların sahip olduğu, ajanların izlediği sözleşme:** Bakımcılar depo sözleşmesine sahiptir; ajanlar kod yazarken kurulu talimatları izler.
|
||||
* **✅ Doğrulama yoluyla güven:** Davranışı değiştiren işlerde insan tarafından incelenebilir bir gerçeklik belgesi kararı veya farkı bulunduğu için AI çalışmasına güvenmek kolaylaşır.
|
||||
|
||||
## 🔄 Nasıl çalışır
|
||||
|
||||
Bir AI ajanı kodunuzu değiştirdiğinde iş bitmiş sayılmaz. Truthmark, ajanların teslimden önce izlediği bir bitiş zamanı iş akışı koruması kurar:
|
||||
|
||||
1. 💻 **Kod:** Ajan işlevsel kodu değiştirir.
|
||||
2. 🧪 **Test:** İlgili testler çalıştırılır.
|
||||
3. 🔍 **Kontrol:** Truthmark, kurulu bitiş incelemesinin parçası olarak eşlenen dokümantasyonu kontrol eder.
|
||||
4. 📝 **Belgeleme:** Depo gerçeği değiştiğinde belgeler ajan tarafından güncellenir.
|
||||
5. 👀 **İnceleme:** Bir insan *kod farkını* + *gerçeklik farkını* inceler.
|
||||
|
||||
## 🛠 Truthmark ile nasıl etkileşirsiniz
|
||||
|
||||
Truthmark’ın depo yerelinde tek bir sözleşmesi ve onu kullanmanın iki yolu vardır.
|
||||
|
||||
### İnsanlar sözleşmeyi kurar ve doğrular
|
||||
|
||||
Bakımcılar ve CI, CLI kullanır:
|
||||
|
||||
* `truthmark init` - yapılandırmayı oluşturur veya yeniler, sıfır ya da daha fazla platform seçtirir ve yönlendirmeyi, truth-doc iskelelerini ve seçilen AI ana makine talimatlarını kurar.
|
||||
* `truthmark check` - depo gerçeğini terminalden doğrular.
|
||||
|
||||
### Ajanlar kod yazarken sözleşmeyi izler
|
||||
|
||||
Truthmark, Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity ve Cursor gibi desteklenen AI kodlama ana makineleri için depo yerelinde talimatlar kurar.
|
||||
|
||||
Normal döngü basittir:
|
||||
|
||||
1. Ajanınızdan kod değişikliği isteyin veya mevcut bir davranışı belgelemesini isteyin.
|
||||
2. Kurulu talimatlar ajana ne zaman test edeceğini, ne zaman truth dokümanlarını güncelleyeceğini ve ne zaman insan incelemesi için duracağını söyler.
|
||||
3. Siz sıradan Git diff’lerini incelersiniz: kod ve varsa truth-doc değişiklikleri.
|
||||
|
||||
Kullanıcı tarafından başlatılan ajan istekleri bilinçli olarak azdır:
|
||||
|
||||
* `/truthmark-document` - kod ve testlerden mevcut uygulanmış davranışı belgeler.
|
||||
* `/truthmark-realize` - mevcut truth dokümanlarından kod uygular.
|
||||
* `/truthmark-check` - depo gerçeğini denetler.
|
||||
|
||||
Truth Sync işe başlamanın olağan yolu değildir; işlevsel kod değişikliklerinden sonraki bitiş incelemesidir.
|
||||
Truth Structure günlük bir komut değildir; yalnızca çalışmayı engellediğinde yönlendirmeyi veya sahipliği onarır.
|
||||
Truthmark bu iş akışlarını Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity ve Cursor için yerel depo yüzeyleri olarak kurar.
|
||||
|
||||
## Neler elde edersiniz
|
||||
|
||||
| Yetenek | Ne yapar |
|
||||
| --- | --- |
|
||||
| Git'e özgü gerçeklik | Depo gerçeğini commit edilmiş Markdown ve yapılandırmada tutar. |
|
||||
| Dal kapsamlı dokümantasyon | Gerçek, özel bir oturumda yaşamak yerine dalla birlikte hareket eder. |
|
||||
| İnsan CLI'si | Bakımcılara kurulum, yenileme, doğrulama ve inceleme komutları sağlar. |
|
||||
| Kurulu ajan rehberliği | Kodlama ajanlarına ne zaman belge yazacağını, test edeceğini, gerçeği senkronize edeceğini, denetleyeceğini veya inceleme için duracağını söyler. |
|
||||
| Açık yönlendirme | Kod alanlarını kanonik gerçeklik belgelerine eşler. |
|
||||
| İncelenebilir teslimler | Hem kod hem de gerçeklik belgeleri için sıradan Git farkları üretir. |
|
||||
| Yerel-öncelikli çalışma | Barındırılan hizmet, daemon, veritabanı veya MCP sunucusu gerektirmez. |
|
||||
| Daha güvenli yazma sınırları | Kod-öncelikli, belge-öncelikli, salt-okunur ve yalnızca-belge iş akışlarını ayırır. |
|
||||
| Doğrulama | Yönlendirme, yetki, frontmatter, bağlantı, üretilmiş yüzey, dal kapsamı, güncellik ve kapsam sorunlarını raporlar. |
|
||||
| İsteğe bağlı Portal | Açıkça etkinleştirilip istendiğinde Markdown gerçeklik belgelerinden commit edilmiş statik bir HTML sunum sitesi üretir. |
|
||||
### Gerçeklikten başlayan dokümantasyon
|
||||
|
||||
## Görsel genel bakış
|
||||
Truthmark; ürün yetenekleri, uygulama davranışı, uygulama programlama arayüzleri, mimari, iş akışları, operasyonlar ve testler için belgeler oluşturabilir. Kod ve testler kanıtı sağlar; sınırları belirli Markdown belgeleri sonucu kalıcılaştırır.
|
||||
|
||||
|
||||
### Bir sonraki değişiklikten sağ çıkan dokümantasyon
|
||||
|
||||
**Özellikler:** Truthmark'ın ne kurduğu ve iş akışı yüzeyinin nasıl bölündüğü.
|
||||
Rotalar, kod alanlarını kanonik belgelere bağlar. Ajanlar davranışı değiştirdiğinde Truth Sync, ilgili gerçeğin nereye ait olduğunu bilir ve teslimi incelenebilir tutar.
|
||||
|
||||
|
||||
### Ayrı kulvarlarda ürün ve mühendislik gerçeği
|
||||
|
||||
**Konum:** Truthmark'ın istemlere, belleğe ve spesifikasyon iş akışlarına göre nerede yer aldığı.
|
||||
Ürün gerçeği; kullanıcıya dönük vaatleri, sınırları, kararları ve kabul kriterlerini kapsar. Mühendislik gerçeği; mevcut davranışı, sözleşmeleri, mimariyi, iş akışlarını, operasyonları ve test davranışını kapsar.
|
||||
|
||||
|
||||
### Git'e özgü iş birliği
|
||||
|
||||
**Senkronizasyon akışı:** Truth Sync'in normal kod değişikliklerini teslimden önce nasıl kapattığı.
|
||||
Önemli olan her şey commit edilmiş depo dosyalarında yaşar. Gerçek dalla birlikte ilerler, sıradan pull request'lerle çalışır ve her bakımcı ile kodlama ajanına görünür kalır.
|
||||
|
||||
## Ekipler neden benimser
|
||||
### Yerel öncelikli çalışma
|
||||
|
||||
Truthmark, AI ajanlarının kod üretebildiğini zaten bilen ekipler içindir.
|
||||
|
||||
Sıradaki sorun yönetişimdir.
|
||||
|
||||
Tören anlamında yönetişim değil. Basit bir soru olarak yönetişim:
|
||||
|
||||
> Bu AI destekli değişiklikten sonra depo hâlâ gerçeği söylüyor mu?
|
||||
|
||||
Truthmark, commit edilmiş dosyalar, açık yönlendirme ve incelenebilir farklarla ekiplerin buna yanıt vermesine yardımcı olur.
|
||||
|
||||
Şunlara ihtiyaç duyduğunuzda yararlıdır:
|
||||
|
||||
- daha az dokümantasyon kayması
|
||||
- daha iyi teslimler
|
||||
- dala özgü ürün gerçeği
|
||||
- kalıcı mimari ve API dokümantasyonu
|
||||
- belgeler ile kod arasında açık sahiplik
|
||||
- daha güvenli ajan yazma sınırları
|
||||
- gizli bellek yerine incelenebilir dokümantasyon
|
||||
- commit edilmiş depo dosyalarından çalışmaya devam eden AI iş akışları
|
||||
Truthmark barındırılan hizmet, daemon, veritabanı, vektör deposu veya Model Context Protocol sunucusu gerektirmez. Depo kendi dokümantasyon iş akışını taşır.
|
||||
|
||||
## Truthmark nerede yer alır
|
||||
|
||||
Truthmark istemlerin, belleğin, spesifikasyonların, testlerin veya kod incelemesinin yerini almaz.
|
||||
| İhtiyaç | En iyi seçenek |
|
||||
| ---------------------------------------------------- | ------------------------------ |
|
||||
| Tek bir ajan oturumundan daha iyi çıktı | Daha iyi prompt |
|
||||
| Kişisel veya oturum düzeyinde süreklilik | Bellek aracı |
|
||||
| Plan öncelikli özellik çalışması | Spesifikasyon iş akışı |
|
||||
| Kodla birlikte ilerleyen, dal kapsamlı dokümantasyon | **Truthmark** |
|
||||
| Davranış doğruluğu | Testler ve kod incelemesi |
|
||||
| İncelenebilir, AI destekli dokümantasyon | **Truthmark + Git incelemesi** |
|
||||
|
||||
Bu iş akışlarına Git içinde kalıcı bir iniş alanı sağlar.
|
||||
Truthmark, AI kodlama ajanlarını zaten kullanan ve depo gerçeğinin kod kadar hızlı güncellenmesini isteyen bakımcılar ile mühendislik ekipleri için tasarlanmıştır.
|
||||
|
||||
| İhtiyaç | Daha uygun seçenek |
|
||||
| --- | --- |
|
||||
| Tek bir ajan oturumundan daha iyi çıktı | Daha iyi istem |
|
||||
| Kişisel veya oturum düzeyinde süreklilik | Bellek aracı |
|
||||
| Plan-öncelikli özellik çalışması | Spesifikasyon iş akışı |
|
||||
| Kodla birlikte taşınan dal kapsamlı gerçek | Truthmark |
|
||||
| Davranış doğruluğunu doğrulama | Testler ve inceleme |
|
||||
| AI destekli dokümantasyon değişikliklerini inceleme | Truthmark artı Git incelemesi |
|
||||
## Desteklenen ana bilgisayarlar ve komut satırı
|
||||
|
||||
Truthmark'ın alanı tasarım gereği dardır:
|
||||
Desteklenen ajan ana bilgisayarları:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
etrafına ajan rehberliği kurmak
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Daha derine inin
|
||||
<details>
|
||||
<summary>Komut satırı başvurusu</summary>
|
||||
|
||||
README vitrin görevi görür: hızlı bağlam, hızlı başlangıç ve temel zihinsel model.
|
||||
| Komut | Amaç |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Yapılandırmayı, yönlendirmeyi, şablonları ve seçilen ana bilgisayar iş akışlarını oluşturur veya yeniler |
|
||||
| `truthmark check [--base <ref>]` | Depo gerçeğini doğrular ve isteğe bağlı olarak dal güncelliği tanılamasını çalıştırır |
|
||||
| `truthmark index --json` | Türetilmiş depo ve yönlendirme meta verilerini inceler |
|
||||
| `truthmark impact --base <ref> --json` | Değişen dosyaları belgelere, sahiplerine ve yakındaki testlere eşler |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | İş akışının uygulanabilirliğini ve hedeflerini inceler |
|
||||
| `truthmark validate ...` | İş akışı raporlarını ve yazma kiralarını doğrular |
|
||||
| `truthmark uninstall --dry-run\|--apply` | Yazılmış truth belgelerini koruyarak oluşturulan ana bilgisayar yüzeylerini önizler veya kaldırır |
|
||||
|
||||
Komut komut kullanım, yüzey karşılaştırmaları, desteklenen platform ayrıntıları, yapılandırma, yönlendirme, Portal ve örnekler için [Truthmark Kullanıcı Kılavuzu](../user-guide.md) sayfasını okuyun.
|
||||
Betikler ve sürekli entegrasyon için komut satırı arayüzünün tamamında yapılandırılmış JSON çıktısı bulunur.
|
||||
|
||||
## Proje durumu
|
||||
</details>
|
||||
|
||||
Mevcut sürüm şunları sağlar:
|
||||
## Daha fazlasını öğrenin
|
||||
|
||||
- init, check, index, impact ve iş akışı durumu için yerel CLI komutları
|
||||
- Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity ve Cursor için oluşturulan depo yerelinde ajan talimatları
|
||||
- yönlendirme, yetki, frontmatter, bağlantı, güncellik, üretilmiş yüzey, dal kapsamı ve kapsam tanıları
|
||||
- dal kapsamlı gerçeklik belgeleri ve türetilmiş depo zekâsı artefaktları
|
||||
- [Truthmark kullanıcı kılavuzu](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Dokümantasyon dizini](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Mimariye genel bakış](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Yapılandırma, yönlendirme ve komut sözleşmeleri](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Depo gerçeğini koruma](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Katkıda bulunma](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Dokümantasyon
|
||||
|
||||
- [Kullanıcı kılavuzu](../user-guide.md)
|
||||
- [Dokümanlar dizini](../README.md)
|
||||
- [Mimari genel bakışı](../truthmark/engineering/architecture/overview.md)
|
||||
- [API ve CLI sözleşmeleri](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Depo gerçeği bakım kılavuzu](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Yerel geliştirme ve katkı komutları için [CONTRIBUTING.md](../../CONTRIBUTING.md) dosyasına bakın.
|
||||
|
||||
## Tasarım sınırları
|
||||
|
||||
Truthmark bilinçli olarak küçüktür: yerel, commit edilmiş, dal kapsamlı ve incelenebilir.
|
||||
|
||||
Barındırılan bir hizmet, MCP sunucusu, vektör veritabanı, gizli bellek katmanı, CI yaptırım ürünü veya otonom kod yeniden yazma motoru değildir. Depo gerçeğinin görünür kalmasına yardımcı olur; testlerin, kod incelemesinin veya insan yargısının yerini almaz.
|
||||
**Truthmark'ı kurun, kodlama ana bilgisayarınızı seçin ve gerçek bir davranışı bugün belgeye dönüştürün.**
|
||||
|
||||
## Lisans
|
||||
|
||||
MIT. Bkz. [LICENSE](../../LICENSE).
|
||||
|
||||
## Güvenli kaldırma
|
||||
|
||||
`truthmark uninstall --dry-run` komutunu kullanarak tam olarak oluşturulan ana bilgisayar yüzeylerini inceleyin, ardından kaldırmak için `truthmark uninstall --apply` komutunu çalıştırın. Oluşturulan truth, yapılandırma, şablonlar, Portal çıktısı, Gemini dosyaları ve alakasız kullanıcı dosyaları korunur; global npm kurulumunu paket yöneticinizle ayrı olarak kaldırın.
|
||||
|
||||
+132
-157
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**Các tác tử của bạn viết mã. Truthmark duy trì tài liệu hướng tới con người và có thể được xem xét qua Git.**
|
||||
**Các tác nhân của bạn viết mã. Truthmark duy trì tài liệu dành cho con người và sẵn sàng để xem xét trong Git.**
|
||||
|
||||
Truthmark cài đặt các quy trình làm việc gốc Git, giúp tác nhân lập trình AI tạo tài liệu sản phẩm và kỹ thuật mới từ mã cùng các bài kiểm thử hiện có, giữ tài liệu luôn cập nhật sau mỗi thay đổi mã và cung cấp cho bạn các diff Markdown thông thường để xem xét.
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[Bắt đầu](#bắt-đầu-nhanh-tạo-tài-liệu-truth-đầu-tiên) · [Trang web](https://merlinhu1.github.io/truthmark/) · [Hướng dẫn người dùng](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>Đọc README này bằng một trong 16 ngôn ngữ</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 Bắt đầu nhanh: chạy cục bộ trong năm phút
|
||||
## Tạo tài liệu đầu tiên. Giữ tài liệu luôn đúng.
|
||||
|
||||
Chạy lệnh này bên trong kho Git mà bạn muốn Truthmark quản lý:
|
||||
Hầu hết công cụ tài liệu dừng lại sau khi tạo nội dung. Truthmark mang đến cho tác nhân một vòng đời tài liệu hoàn chỉnh ngay trong kho mã của bạn:
|
||||
|
||||
- **Tạo tài liệu mới từ phần mềm đang hoạt động.** Truth Document đọc mã và các bài kiểm thử, sau đó tạo tài liệu sản phẩm hoặc kỹ thuật có phạm vi rõ ràng.
|
||||
- **Tự động giữ tài liệu luôn đồng bộ.** Truth Sync chạy khi tác nhân bàn giao sau các thay đổi mã chức năng và cập nhật sự thật của kho trước khi công việc hoàn tất.
|
||||
- **Biến tài liệu trở lại thành mã.** Truth Realize triển khai các tài liệu truth đã được phê duyệt mà vẫn duy trì quy trình doc-first rõ ràng.
|
||||
- **Sửa quyền sở hữu khi cơ sở mã phát triển.** Truth Structure tạo các tuyến có phạm vi rõ ràng và tài liệu khởi đầu cho khu vực mới hoặc quá tải.
|
||||
- **Xem xét mọi thứ trong Git.** Mã, quyết định, hợp đồng, kiến trúc, vận hành và hành vi cùng di chuyển với nhánh.
|
||||
|
||||
Không cơ sở tri thức được lưu trữ trên máy chủ. Không bộ nhớ tác nhân riêng tư. Không tài liệu bị mắc kẹt trong lịch sử trò chuyện.
|
||||
|
||||
## Bắt đầu nhanh: tạo tài liệu truth đầu tiên
|
||||
|
||||
**Yêu cầu:** Node.js 24 trở lên, một kho Git và một host lập trình AI được hỗ trợ cho quy trình làm việc của tác nhân.
|
||||
|
||||
Chạy các lệnh sau trong kho mà bạn muốn Truthmark quản lý:
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` cho phép bạn chọn Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor hoặc thiết lập giao diện dòng lệnh trung lập với host.
|
||||
|
||||
Bây giờ, hãy yêu cầu tác nhân đã cấu hình ghi tài liệu cho một hành vi thực tế:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
Truth Document tạo một tài liệu truth mới có phạm vi rõ ràng khi chưa có tài liệu nào, cập nhật tài liệu sở hữu hiện có khi đã có và cập nhật định tuyến khi cần. Quy trình này không thay đổi mã chức năng.
|
||||
|
||||
Xem xét kết quả:
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
Trong terminal tương tác, `truthmark init` hiển thị danh sách đa lựa chọn được đánh số. Chọn không, một hoặc nhiều nền tảng, hoặc nhập `none` để thiết lập chỉ dùng CLI và không gắn với host.
|
||||
Giờ đây bạn sẽ có:
|
||||
|
||||
Với script và CI, hãy lặp lại `--platform`; `--json` không bao giờ hiển thị lời nhắc:
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
Đường dẫn chính xác tuân theo cấu trúc quyền sở hữu của kho. Tệp mới xuất hiện trong `git status`; thay đổi đối với tệp được theo dõi xuất hiện trong `git diff`.
|
||||
|
||||
Cách gọi khác nhau tùy theo host. OpenCode dùng `/skill truthmark-document`, Antigravity dùng `@truthmark-document`, còn các host được hỗ trợ khác dùng bề mặt skill hoặc lệnh gạch chéo gốc của mình. Xem [bảng nền tảng](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms) để biết chính xác các lệnh.
|
||||
|
||||
Đối với script và tích hợp liên tục, hãy truyền rõ các nền tảng đã chọn:
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
Ở lần chạy không tương tác đầu tiên mà không có `--platform`, thiết lập vẫn trung lập với host; các lần chạy sau giữ lựa chọn đã lưu trong `.truthmark/config.yml`.
|
||||
Chọn `none` trong chế độ tương tác hoặc chạy `truthmark init --clear-platforms` để có một kho trung lập với host. Bạn có thể thêm nền tảng tác nhân sau bằng cách chạy lại `truthmark init`.
|
||||
|
||||
Bây giờ hãy thử lộ trình áp dụng phổ biến nhất: ghi tài liệu cho một hành vi hiện có từ mã và kiểm thử. Trong máy chủ lập trình AI của bạn, hãy yêu cầu quy trình đã cài đặt:
|
||||
Để chẩn đoán độ mới theo nhánh, hãy truyền một mốc Git cơ sở:
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
Sau đó, người dùng thường không nên gọi Truth Sync trực tiếp. Hãy tiếp tục lập trình qua máy chủ AI của bạn; các chỉ dẫn kho đã cài đặt yêu cầu tác tử chạy các kiểm thử liên quan và thực hiện đánh giá Truth Sync trước khi bàn giao khi mã chức năng thay đổi. Bạn xem xét phần diff mã kết quả cùng với diff tài liệu truth.
|
||||
## Cách Truthmark hoạt động
|
||||
|
||||
Nếu bạn chỉ muốn xác thực bằng CLI, hãy chọn `none` rồi chạy `truthmark check`; bạn có thể chạy lại `truthmark init` sau để chọn nền tảng.
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Cách Truthmark hoạt động" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 Vấn đề: khoảng trống tài liệu AI
|
||||
Giao diện dòng lệnh Truthmark cài đặt và xác thực hợp đồng của kho. Tác nhân lập trình của bạn thực hiện việc xem xét bằng chứng và viết tài liệu thông qua các quy trình gốc của host đã được cài đặt.
|
||||
|
||||
Các tác tử lập trình AI cực kỳ giỏi viết mã nhanh. Nhưng tốc độ này tạo ra một kiểu lỗi mới nguy hiểm: **câu chuyện của kho lệch khỏi thực tế.**
|
||||
Một thay đổi mã thông thường đi theo một vòng lặp đơn giản:
|
||||
|
||||
* Hành vi bị mất trong lịch sử trò chuyện tạm thời.
|
||||
* Tài liệu kiến trúc nhanh chóng tụt lại phía sau.
|
||||
* Quyết định sản phẩm biến mất sau khi bàn giao.
|
||||
* Người xem xét mã phải xem các diff mã thô mà không hiểu "vì sao".
|
||||
* Mỗi phiên AI mới buộc phải khám phá lại sự thật của kho từ đầu.
|
||||
1. Tác nhân thay đổi mã chức năng.
|
||||
2. Các bài kiểm thử liên quan được chạy.
|
||||
3. Truth Sync kiểm tra tài liệu đã được ánh xạ.
|
||||
4. Tác nhân tạo hoặc cập nhật tài liệu và định tuyến khi sự thật của kho đã thay đổi.
|
||||
5. Bạn xem xét diff mã và diff truth cùng nhau.
|
||||
|
||||
## 🎯 Giải pháp: Truthmark
|
||||
## Quy trình làm việc
|
||||
|
||||
**Truthmark** cài đặt một lớp quy trình làm việc gốc Git vào kho của bạn. Nó khắc phục phần thường bị hỏng trong phát triển bằng AI: giúp tài liệu luôn khớp với mã.
|
||||
| Quy trình | Dùng khi | Kết quả |
|
||||
| -------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| **Truth Document** | Mã hiện có cần được ghi tài liệu | Tạo hoặc cập nhật tài liệu sản phẩm và kỹ thuật dựa trên bằng chứng |
|
||||
| **Truth Sync** | Mã chức năng đã thay đổi | Giữ tài liệu đã ánh xạ và định tuyến đồng bộ trước khi bàn giao |
|
||||
| **Truth Structure** | Khu vực mới cần quyền sở hữu hoặc tài liệu hiện có quá rộng | Tạo các tuyến có phạm vi rõ ràng và tài liệu khởi đầu dạng khung |
|
||||
| **Truth Realize** | Một tài liệu truth đã phê duyệt cần trở thành phần mềm hoạt động | Cập nhật mã chức năng từ tài liệu |
|
||||
| **Truth Check** | Sự thật của kho cần được kiểm tra | Báo cáo vấn đề về định tuyến, quyền sở hữu, bằng chứng và tài liệu |
|
||||
| **Truthmark Portal** | Nhóm muốn có một trang tài liệu dễ duyệt | Tạo bản trình bày HTML tĩnh được commit từ các tài liệu truth Markdown |
|
||||
|
||||
Thay vì hy vọng con người và tác tử AI nhớ cập nhật tài liệu, Truthmark biến việc ghi tài liệu thành một thói quen có hệ thống, có thể xem xét ngay trong kho của bạn.
|
||||
Truthmark cài đặt các quy trình này dưới dạng bề mặt gốc của kho cho Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity và Cursor.
|
||||
|
||||
### ✨ Vì sao Truthmark khác biệt
|
||||
## Những gì bạn nhận được
|
||||
|
||||
Truthmark không chỉ là một công cụ tài liệu khác. Nó được tích hợp sâu vào quy trình AI:
|
||||
### Tài liệu bắt đầu từ thực tế
|
||||
|
||||
* **🚫 Không bị khóa vào nhà cung cấp:** Không dịch vụ lưu trữ, không cơ sở dữ liệu ẩn, không máy chủ bổ sung để vận hành.
|
||||
* **🌳 100% gốc Git:** Mọi thứ nằm trong kho của bạn. Sự thật di chuyển cùng nhánh của bạn.
|
||||
* **🤝 Hợp đồng do con người sở hữu, tác tử tuân theo:** Người bảo trì sở hữu hợp đồng kho; tác tử tuân theo hướng dẫn đã cài đặt khi viết mã.
|
||||
* **✅ Tin cậy qua xác minh:** Công việc AI dễ được tin tưởng hơn vì công việc thay đổi hành vi bao gồm một quyết định hoặc diff tài liệu sự thật mà con người có thể xem xét.
|
||||
Truthmark có thể tạo tài liệu cho năng lực sản phẩm, hành vi triển khai, giao diện lập trình ứng dụng, kiến trúc, quy trình làm việc, vận hành và kiểm thử. Mã cùng các bài kiểm thử cung cấp bằng chứng; tài liệu Markdown có phạm vi rõ ràng lưu giữ kết quả.
|
||||
|
||||
## 🔄 Cách hoạt động
|
||||
### Tài liệu vẫn bền vững qua thay đổi tiếp theo
|
||||
|
||||
Khi một tác tử AI sửa mã của bạn, công việc chưa kết thúc. Truthmark cài đặt một chốt quy trình lúc hoàn tất mà tác tử tuân theo trước khi bàn giao:
|
||||
Các tuyến kết nối khu vực mã với tài liệu chuẩn. Khi tác nhân thay đổi hành vi, Truth Sync biết sự thật tương ứng thuộc về đâu và giữ cho phần bàn giao luôn sẵn sàng để xem xét.
|
||||
|
||||
1. 💻 **Mã:** Tác tử sửa mã chức năng.
|
||||
2. 🧪 **Kiểm thử:** Các kiểm thử liên quan được chạy.
|
||||
3. 🔍 **Kiểm tra:** Truthmark kiểm tra tài liệu được ánh xạ như một phần của bước xem xét kết thúc đã cài đặt.
|
||||
4. 📝 **Ghi tài liệu:** Tài liệu được tác tử cập nhật khi sự thật của kho thay đổi.
|
||||
5. 👀 **Xem xét:** Con người xem xét *diff mã* + *diff sự thật*.
|
||||
### Sự thật sản phẩm và kỹ thuật trên các luồng riêng biệt
|
||||
|
||||
## 🛠 Cách bạn tương tác với Truthmark
|
||||
Sự thật sản phẩm ghi lại cam kết hướng tới người dùng, ranh giới, quyết định và tiêu chí chấp nhận. Sự thật kỹ thuật ghi lại hành vi hiện tại, hợp đồng, kiến trúc, quy trình làm việc, vận hành và hành vi kiểm thử.
|
||||
|
||||
Truthmark có một hợp đồng cục bộ trong kho và hai cách sử dụng nó.
|
||||
### Cộng tác gốc Git
|
||||
|
||||
### Con người cài đặt và xác thực hợp đồng
|
||||
Mọi thứ quan trọng đều nằm trong các tệp kho đã commit. Sự thật đi theo nhánh, hoạt động với pull request thông thường và luôn hiển thị với mọi người bảo trì cùng tác nhân lập trình.
|
||||
|
||||
Người bảo trì và CI dùng CLI:
|
||||
### Vận hành ưu tiên cục bộ
|
||||
|
||||
* `truthmark init` - tạo hoặc làm mới cấu hình, cho phép chọn không, một hoặc nhiều nền tảng, rồi cài đặt định tuyến, scaffold truth-doc và hướng dẫn cho các AI host đã chọn.
|
||||
* `truthmark check` - xác thực sự thật của kho từ terminal.
|
||||
|
||||
### Tác tử tuân theo hợp đồng khi viết mã
|
||||
|
||||
Truthmark cài đặt hướng dẫn cục bộ trong kho cho các AI coding host được hỗ trợ như Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity và Cursor.
|
||||
|
||||
Vòng lặp bình thường rất đơn giản:
|
||||
|
||||
1. Yêu cầu tác tử thay đổi mã hoặc ghi tài liệu cho một hành vi hiện có.
|
||||
2. Hướng dẫn đã cài đặt cho tác tử biết khi nào cần kiểm thử, khi nào cập nhật truth docs và khi nào dừng để con người xem xét.
|
||||
3. Bạn xem xét các Git diff thông thường: mã cộng với mọi thay đổi truth-doc.
|
||||
|
||||
Các yêu cầu tác tử do người dùng khởi động được cố ý giữ ít:
|
||||
|
||||
* `/truthmark-document` - ghi tài liệu cho hành vi đã triển khai hiện có từ mã và kiểm thử.
|
||||
* `/truthmark-realize` - triển khai mã từ truth docs hiện có.
|
||||
* `/truthmark-check` - kiểm toán sự thật của kho.
|
||||
|
||||
Truth Sync không phải cách thông thường để bắt đầu công việc; đó là bước xem xét kết thúc sau các thay đổi mã chức năng.
|
||||
Truth Structure không phải lệnh hằng ngày; nó chỉ sửa định tuyến hoặc quyền sở hữu khi điều đó chặn công việc.
|
||||
|
||||
## Bạn nhận được gì
|
||||
|
||||
| Khả năng | Tác dụng |
|
||||
| --- | --- |
|
||||
| Sự thật gốc Git | Giữ sự thật của kho trong Markdown và cấu hình đã commit. |
|
||||
| Tài liệu theo phạm vi nhánh | Sự thật di chuyển cùng nhánh thay vì sống trong một phiên riêng tư. |
|
||||
| CLI dành cho con người | Cung cấp cho người bảo trì các lệnh thiết lập, làm mới, xác thực và kiểm tra. |
|
||||
| Hướng dẫn tác tử đã cài đặt | Cho tác tử lập trình biết khi nào ghi tài liệu, kiểm thử, đồng bộ sự thật, kiểm toán hoặc dừng để xem xét. |
|
||||
| Định tuyến rõ ràng | Ánh xạ các vùng mã tới tài liệu sự thật chuẩn. |
|
||||
| Bàn giao có thể xem xét | Tạo các diff Git thông thường cho cả mã và tài liệu sự thật. |
|
||||
| Vận hành ưu tiên cục bộ | Không yêu cầu dịch vụ lưu trữ, daemon, cơ sở dữ liệu hoặc máy chủ MCP. |
|
||||
| Ranh giới ghi an toàn hơn | Tách các quy trình code-first, doc-first, chỉ đọc và chỉ tài liệu. |
|
||||
| Xác thực | Báo cáo vấn đề về định tuyến, thẩm quyền, frontmatter, liên kết, bề mặt sinh ra, phạm vi nhánh, độ mới và độ phủ. |
|
||||
| Portal tùy chọn | Tạo một trang trình bày HTML tĩnh đã commit từ tài liệu sự thật Markdown khi được bật và yêu cầu rõ ràng. |
|
||||
|
||||
## Tổng quan trực quan
|
||||
|
||||
|
||||
|
||||
**Tính năng:** Truthmark cài đặt gì và bề mặt quy trình được chia như thế nào.
|
||||
|
||||
|
||||
|
||||
**Vị trí:** Truthmark nằm ở đâu so với prompt, bộ nhớ và quy trình đặc tả.
|
||||
|
||||
|
||||
|
||||
**Luồng đồng bộ:** Truth Sync kết thúc các thay đổi mã thông thường trước khi bàn giao như thế nào.
|
||||
|
||||
## Vì sao các nhóm áp dụng
|
||||
|
||||
Truthmark dành cho các nhóm đã biết tác tử AI có thể tạo mã.
|
||||
|
||||
Vấn đề tiếp theo là quản trị.
|
||||
|
||||
Không phải quản trị như nghi thức. Quản trị như một câu hỏi đơn giản:
|
||||
|
||||
> Sau thay đổi được AI hỗ trợ này, kho có còn nói đúng sự thật không?
|
||||
|
||||
Truthmark giúp các nhóm trả lời điều đó bằng các tệp đã commit, định tuyến rõ ràng và diff có thể xem xét.
|
||||
|
||||
Nó hữu ích khi bạn cần:
|
||||
|
||||
- ít trôi lệch tài liệu hơn
|
||||
- bàn giao tốt hơn
|
||||
- sự thật sản phẩm theo từng nhánh
|
||||
- tài liệu kiến trúc và API bền vững
|
||||
- quyền sở hữu rõ ràng giữa tài liệu và mã
|
||||
- ranh giới ghi an toàn hơn cho tác tử
|
||||
- tài liệu có thể xem xét thay vì bộ nhớ ẩn
|
||||
- quy trình AI vẫn hoạt động từ các tệp kho đã commit
|
||||
Truthmark không cần dịch vụ lưu trữ, daemon, cơ sở dữ liệu, kho vector hay máy chủ Model Context Protocol. Kho tự mang theo quy trình tài liệu của mình.
|
||||
|
||||
## Truthmark phù hợp ở đâu
|
||||
|
||||
Truthmark không thay thế prompt, bộ nhớ, đặc tả, kiểm thử hoặc xem xét mã.
|
||||
| Nhu cầu | Phù hợp nhất |
|
||||
| ---------------------------------------- | --------------------------------- |
|
||||
| Đầu ra tốt hơn từ một phiên tác nhân | Prompt tốt hơn |
|
||||
| Tính liên tục cá nhân hoặc theo phiên | Công cụ bộ nhớ |
|
||||
| Phát triển tính năng theo kế hoạch trước | Quy trình đặc tả |
|
||||
| Tài liệu theo phạm vi nhánh đi cùng mã | **Truthmark** |
|
||||
| Tính đúng đắn của hành vi | Kiểm thử và xem xét mã |
|
||||
| Tài liệu có AI hỗ trợ và có thể xem xét | **Truthmark + xem xét trong Git** |
|
||||
|
||||
Nó cho các quy trình đó một nơi bền vững để hạ cánh trong Git.
|
||||
Truthmark được xây dựng cho người bảo trì và các nhóm kỹ thuật đã dùng tác nhân lập trình AI, đồng thời muốn kho luôn nói đúng sự thật nhanh như tốc độ thay đổi của mã.
|
||||
|
||||
| Nhu cầu | Phù hợp hơn |
|
||||
| --- | --- |
|
||||
| Đầu ra tốt hơn từ một phiên tác tử | Prompt tốt hơn |
|
||||
| Tính liên tục cá nhân hoặc cấp phiên | Công cụ bộ nhớ |
|
||||
| Làm tính năng theo kế hoạch trước | Quy trình đặc tả |
|
||||
| Truth theo nhánh đi cùng mã | Truthmark |
|
||||
| Xác thực tính đúng của hành vi | Kiểm thử và xem xét |
|
||||
| Xem xét thay đổi tài liệu do AI hỗ trợ | Truthmark cộng với xem xét Git |
|
||||
## Host được hỗ trợ và dòng lệnh
|
||||
|
||||
Làn đường của Truthmark được thiết kế có chủ ý là hẹp:
|
||||
Các host tác nhân được hỗ trợ:
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
cài đặt hướng dẫn tác tử quanh nó
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
## Tìm hiểu sâu hơn
|
||||
<details>
|
||||
<summary>Tham chiếu dòng lệnh</summary>
|
||||
|
||||
README là mặt tiền: ngữ cảnh nhanh, bắt đầu nhanh và mô hình tư duy cốt lõi.
|
||||
| Lệnh | Mục đích |
|
||||
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `truthmark init` | Tạo hoặc làm mới cấu hình, định tuyến, mẫu và quy trình của các host đã chọn |
|
||||
| `truthmark check [--base <ref>]` | Xác thực sự thật của kho và tùy chọn chạy chẩn đoán độ mới theo nhánh |
|
||||
| `truthmark index --json` | Kiểm tra siêu dữ liệu dẫn xuất về kho và định tuyến |
|
||||
| `truthmark impact --base <ref> --json` | Ánh xạ tệp đã thay đổi tới tài liệu, chủ sở hữu và các bài kiểm thử lân cận |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Kiểm tra khả năng áp dụng và mục tiêu của quy trình |
|
||||
| `truthmark validate ...` | Xác thực báo cáo quy trình và quyền thuê ghi |
|
||||
| `truthmark uninstall --dry-run\|--apply` | Xem trước hoặc xóa các bề mặt host đã tạo trong khi vẫn giữ tài liệu truth do người dùng viết |
|
||||
|
||||
Để biết cách sử dụng từng lệnh, so sánh bề mặt, chi tiết nền tảng được hỗ trợ, cấu hình, định tuyến, Portal và ví dụ, hãy đọc [Hướng dẫn người dùng Truthmark](../user-guide.md).
|
||||
Đầu ra JSON có cấu trúc được cung cấp trên toàn bộ giao diện dòng lệnh cho script và tích hợp liên tục.
|
||||
|
||||
## Trạng thái dự án
|
||||
</details>
|
||||
|
||||
Bản phát hành hiện tại cung cấp:
|
||||
## Tìm hiểu thêm
|
||||
|
||||
- các lệnh CLI cục bộ cho init, check, index, impact và trạng thái quy trình
|
||||
- hướng dẫn tác tử cục bộ trong kho được tạo cho Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity và Cursor
|
||||
- chẩn đoán về định tuyến, thẩm quyền, frontmatter, liên kết, độ mới, bề mặt sinh ra, phạm vi nhánh và độ phủ
|
||||
- tài liệu sự thật theo phạm vi nhánh và các hiện vật trí tuệ kho được suy dẫn
|
||||
- [Hướng dẫn người dùng Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [Chỉ mục tài liệu](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [Tổng quan kiến trúc](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [Hợp đồng cấu hình, định tuyến và lệnh](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Duy trì sự thật của kho](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [Đóng góp](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
## Tài liệu
|
||||
|
||||
- [Hướng dẫn người dùng](../user-guide.md)
|
||||
- [Chỉ mục tài liệu](../README.md)
|
||||
- [Tổng quan kiến trúc](../truthmark/engineering/architecture/overview.md)
|
||||
- [Hợp đồng API và CLI](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [Hướng dẫn bảo trì sự thật của kho](../standards/maintaining-repository-truth.md)
|
||||
|
||||
Để xem các lệnh phát triển cục bộ và đóng góp, hãy xem [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
|
||||
## Ranh giới thiết kế
|
||||
|
||||
Truthmark được cố ý giữ nhỏ: cục bộ, được commit, theo phạm vi nhánh và có thể xem xét.
|
||||
|
||||
Nó không phải dịch vụ lưu trữ, máy chủ MCP, cơ sở dữ liệu vector, lớp bộ nhớ ẩn, sản phẩm cưỡng chế CI hay động cơ tự động viết lại mã. Nó giúp sự thật của kho luôn hiển thị; nó không thay thế kiểm thử, xem xét mã hay phán đoán của con người.
|
||||
**Cài đặt Truthmark, chọn host lập trình và biến một hành vi thực tế thành tài liệu ngay hôm nay.**
|
||||
|
||||
## Giấy phép
|
||||
|
||||
MIT. Xem [LICENSE](../../LICENSE).
|
||||
|
||||
## Gỡ cài đặt an toàn
|
||||
|
||||
Sử dụng `truthmark uninstall --dry-run` để xem lại chính xác các bề mặt host đã tạo ra, rồi `truthmark uninstall --apply` để loại bỏ chúng. Các truth đã tạo, cấu hình, mẫu, đầu ra Portal, tệp Gemini và các tệp người dùng không liên quan sẽ được giữ nguyên; hãy gỡ bỏ cài đặt npm toàn cục riêng biệt bằng trình quản lý gói của bạn.
|
||||
|
||||
+134
-159
@@ -1,220 +1,195 @@
|
||||
# Truthmark
|
||||
|
||||
**你的代理会写代码。Truthmark 维护面向人类、可在 Git 中审查的文档。**
|
||||
**您的代理负责写代码。Truthmark 负责维护面向人、可在 Git 中审查的文档。**
|
||||
|
||||
Truthmark 安装 Git 原生工作流，让 AI 编码代理能够根据现有代码和测试创建新的产品与工程文档，在每次代码变更后持续保持文档最新，并将普通的 Markdown diff 交给您审查。
|
||||
|
||||
[](https://www.npmjs.com/package/truthmark)
|
||||
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
||||
[](../../LICENSE)
|
||||
[](../../package.json)
|
||||
|
||||
[立即开始](#快速开始创建您的第一份事实文档) · [网站](https://merlinhu1.github.io/truthmark/) · [用户指南](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
|
||||
|
||||
<details>
|
||||
<summary>阅读其他 15 种语言版本</summary>
|
||||
|
||||
[🇺🇸 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)
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
## 🚀 快速开始：五分钟本地运行
|
||||
## 创建首批文档，并让它们始终真实
|
||||
|
||||
在你希望由 Truthmark 管理的 Git 仓库中运行：
|
||||
大多数文档工具生成文档后便止步于此。Truthmark 在您的仓库中为代理提供完整的文档生命周期：
|
||||
|
||||
- **从可运行的软件创建新文档。** Truth Document 读取代码和测试，然后创建边界清晰的产品或工程文档。
|
||||
- **自动保持文档一致。** 功能代码变更后，Truth Sync 会在代理交接时运行，并在工作完成前更新仓库事实。
|
||||
- **将文档变回代码。** Truth Realize 实现已获批准的事实文档，同时保持清晰的文档优先工作流。
|
||||
- **随着代码库增长修复所有权。** Truth Structure 为新区域或负载过重的区域创建边界清晰的路由和起始文档。
|
||||
- **在 Git 中审查一切。** 代码、决策、契约、架构、运维和行为与分支始终同行。
|
||||
|
||||
无需托管知识库。无需私有代理记忆。文档不会被困在聊天记录中。
|
||||
|
||||
## 快速开始：创建您的第一份事实文档
|
||||
|
||||
**要求：** Node.js 24 或更高版本、一个 Git 仓库，以及支持代理工作流的 AI 编码宿主。
|
||||
|
||||
在您希望由 Truthmark 管理的仓库中运行：
|
||||
|
||||
```bash
|
||||
cd /path/to/your-repo
|
||||
npm install -g truthmark
|
||||
truthmark init
|
||||
```
|
||||
|
||||
`truthmark init` 可让您选择 Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor，或与宿主无关的命令行界面设置。
|
||||
|
||||
现在，让已配置的代理记录一个真实行为：
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```
|
||||
|
||||
如果尚不存在对应文档，Truth Document 会创建一份边界清晰的新事实文档；如果已有所有者文档，则更新该文档；需要时还会更新路由。它不会更改功能代码。
|
||||
|
||||
审查结果：
|
||||
|
||||
```bash
|
||||
truthmark check
|
||||
git status --short --untracked-files=all
|
||||
git diff
|
||||
```
|
||||
|
||||
在交互式终端中，`truthmark init` 会显示带编号的多选列表。可选择零个或多个平台，也可输入 `none`，仅进行与宿主无关的 CLI 设置。
|
||||
此时您应该会看到：
|
||||
|
||||
在脚本和 CI 中可重复使用 `--platform`；`--json` 永远不会提示输入：
|
||||
```text
|
||||
docs/truthmark/engineering/behaviors/session-timeout.md
|
||||
docs/truthmark/routes/areas/authentication.md
|
||||
```
|
||||
|
||||
确切路径取决于仓库的所有权结构。新文件会出现在 `git status` 中；对已跟踪文件的更改会出现在 `git diff` 中。
|
||||
|
||||
不同宿主的调用方式有所不同。OpenCode 使用 `/skill truthmark-document`，Antigravity 使用 `@truthmark-document`，其他受支持宿主则使用各自原生的技能或斜杠命令界面。有关准确命令，请参阅[平台表](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms)。
|
||||
|
||||
对于脚本和持续集成，请显式传入所选平台：
|
||||
|
||||
```bash
|
||||
truthmark init --platform codex --platform cursor
|
||||
truthmark init --json
|
||||
```
|
||||
|
||||
首次非交互运行且没有 `--platform` 时，初始化保持宿主中立；之后的运行会保留 `.truthmark/config.yml` 中保存的选择。
|
||||
在交互模式中选择 `none`，或运行 `truthmark init --clear-platforms`，即可获得与宿主无关的仓库。之后可重新运行 `truthmark init` 添加代理平台。
|
||||
|
||||
现在尝试最常见的采用路径：根据代码和测试记录一个已有行为。在你的 AI 编码宿主中，请求已安装的工作流：
|
||||
如需相对于分支的时效性诊断，请传入 Git 基准：
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
|
||||
```bash
|
||||
truthmark check --base <base-ref>
|
||||
```
|
||||
|
||||
之后，用户通常不应直接调用 Truth Sync。继续通过你的 AI 宿主编写代码；已安装的仓库指令会告诉代理：当功能代码发生变化时，在交接前运行相关测试并执行 Truth Sync 审查。你审查最终的代码 diff 和事实文档 diff。
|
||||
## Truthmark 的工作原理
|
||||
|
||||
如果暂时只需要 CLI 验证，请选择 `none`，然后运行 `truthmark check`；之后可重新运行 `truthmark init` 来选择平台。
|
||||
<picture>
|
||||
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
||||
<img src="../assets/truthmark-workflow.svg" alt="Truthmark 的工作原理" width="1440">
|
||||
</picture>
|
||||
|
||||
## 💡 问题：AI 文档缺口
|
||||
Truthmark 命令行界面负责安装并验证仓库契约。您的编码代理通过已安装的宿主原生工作流完成证据审查和文档工作。
|
||||
|
||||
AI 编码代理非常擅长快速编写代码。但这种速度会产生一种危险的新失效模式：**仓库所讲述的故事与现实发生偏移。**
|
||||
一次常规代码变更遵循一个简单循环：
|
||||
|
||||
* 行为遗失在短暂的聊天历史中。
|
||||
* 架构文档很快落后。
|
||||
* 产品决策在交接后消失。
|
||||
* 代码审查者只能查看原始代码 diff，却不了解“为什么”。
|
||||
* 每个新的 AI 会话都被迫从头重新发现仓库事实。
|
||||
1. 代理更改功能代码。
|
||||
2. 运行相关测试。
|
||||
3. Truth Sync 检查已映射的文档。
|
||||
4. 当仓库事实发生变化时，代理创建或更新文档和路由。
|
||||
5. 您同时审查代码 diff 和事实 diff。
|
||||
|
||||
## 🎯 解决方案：Truthmark
|
||||
## 工作流
|
||||
|
||||
**Truthmark** 会在你的仓库中安装一个 Git 原生的工作流层。它修复 AI 开发中通常会坏掉的部分：帮助文档与代码保持一致。
|
||||
| 工作流 | 使用时机 | 结果 |
|
||||
| -------------------- | ---------------------------------------- | -------------------------------------------------------- |
|
||||
| **Truth Document** | 现有代码需要文档 | 创建或更新以证据为基础的产品与工程文档 |
|
||||
| **Truth Sync** | 功能代码发生变化 | 在交接前保持已映射的文档和路由一致 |
|
||||
| **Truth Structure** | 新区域需要明确所有权，或现有文档范围过大 | 创建边界清晰的路由和骨架式起始文档 |
|
||||
| **Truth Realize** | 已获批准的事实文档应转化为可运行软件 | 根据文档更新功能代码 |
|
||||
| **Truth Check** | 需要审计仓库事实 | 报告路由、所有权、证据和文档问题 |
|
||||
| **Truthmark Portal** | 团队需要可浏览的文档站点 | 根据 Markdown 事实文档生成提交到仓库的静态 HTML 展示站点 |
|
||||
|
||||
Truthmark 不是指望人类和 AI 代理都记得更新文档，而是在你的仓库中把文档变成一种系统化、可审查的习惯。
|
||||
Truthmark 将这些工作流安装为 Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity 和 Cursor 的原生仓库界面。
|
||||
|
||||
### ✨ Truthmark 的独特之处
|
||||
## 您将获得什么
|
||||
|
||||
Truthmark 不只是另一个文档工具。它深度集成到 AI 工作流中：
|
||||
### 从现实出发的文档
|
||||
|
||||
* **🚫 零供应商锁定：** 没有托管服务、隐藏数据库，也没有需要额外运维的服务器。
|
||||
* **🌳 100% Git 原生：** 一切都存在于你的仓库中。事实随分支一起移动。
|
||||
* **🤝 人类拥有、代理遵循的契约：**维护者拥有仓库契约；代理在编码时遵循已安装的指令。
|
||||
* **✅ 通过验证建立信任：** 因为改变行为的工作会包含可由人类审查的事实文档决策或 diff，AI 工作更容易被信任。
|
||||
Truthmark 可以为产品能力、实现行为、应用程序编程接口、架构、工作流、运维和测试创建文档。代码和测试提供证据；边界清晰的 Markdown 文档保存成果。
|
||||
|
||||
## 🔄 工作原理
|
||||
### 经得起下一次变更的文档
|
||||
|
||||
当 AI 代理修改你的代码时，工作并未完成。Truthmark 会安装一个交接前的收尾工作流保护，代理在交接前遵循它：
|
||||
路由将代码区域连接到规范文档。当代理改变行为时，Truth Sync 知道对应事实应归属何处，并让交接始终可审查。
|
||||
|
||||
1. 💻 **代码：** 代理修改功能代码。
|
||||
2. 🧪 **测试：** 执行相关测试。
|
||||
3. 🔍 **检查：**Truthmark 会把映射到的文档作为已安装收尾审查的一部分进行检查。
|
||||
4. 📝 **记录：** 当仓库事实发生变化时，代理更新文档。
|
||||
5. 👀 **审查：** 人类审查*代码 diff* + *事实 diff*。
|
||||
### 分道管理的产品事实与工程事实
|
||||
|
||||
## 🛠 你如何使用 Truthmark
|
||||
产品事实记录面向用户的承诺、边界、决策和验收标准。工程事实记录当前行为、契约、架构、工作流、运维和测试行为。
|
||||
|
||||
Truthmark 有一个仓库本地契约，以及两种使用方式。
|
||||
### Git 原生协作
|
||||
|
||||
### 人类安装并验证契约
|
||||
一切重要内容都存在于提交到仓库的文件中。事实跟随分支，适用于普通的拉取请求，并对每位维护者和编码代理保持可见。
|
||||
|
||||
维护者和 CI 使用 CLI：
|
||||
### 本地优先运行
|
||||
|
||||
* `truthmark init` - 创建或刷新配置，选择零个或多个平台，并安装路由、事实文档脚手架及所选 AI 宿主的指令。
|
||||
* `truthmark check` - 从终端验证仓库事实。
|
||||
Truthmark 不需要托管服务、守护进程、数据库、向量存储或 Model Context Protocol 服务器。仓库自身就携带完整的文档工作流。
|
||||
|
||||
### 代理在编码时遵循契约
|
||||
## Truthmark 的定位
|
||||
|
||||
Truthmark 会为 Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity 和 Cursor 等受支持的 AI 编码宿主安装仓库本地指令。
|
||||
| 需求 | 最佳选择 |
|
||||
| ---------------------- | ------------------------ |
|
||||
| 提升单次代理会话的输出 | 更好的提示词 |
|
||||
| 个人或会话级连续性 | 记忆工具 |
|
||||
| 计划优先的功能开发 | 规格工作流 |
|
||||
| 随代码同行的分支级文档 | **Truthmark** |
|
||||
| 行为正确性 | 测试和代码审查 |
|
||||
| 可审查的 AI 辅助文档 | **Truthmark + Git 审查** |
|
||||
|
||||
正常循环很简单：
|
||||
Truthmark 专为已经使用 AI 编码代理，并希望仓库事实与代码同速更新的维护者和工程团队打造。
|
||||
|
||||
1. 让代理修改代码，或让它记录已有行为。
|
||||
2. 已安装的指令会告诉代理何时测试、何时更新事实文档、何时停下来交给人类审查。
|
||||
3. 你审查普通的 Git diff：代码，以及任何事实文档变更。
|
||||
## 支持的宿主和命令行
|
||||
|
||||
用户主动发起的代理请求刻意保持很少：
|
||||
支持的代理宿主：
|
||||
|
||||
* `/truthmark-document` - 根据代码和测试记录已有实现行为。
|
||||
* `/truthmark-realize` - 根据已有事实文档实现代码。
|
||||
* `/truthmark-check` - 审计仓库事实。
|
||||
- Codex
|
||||
- Claude Code
|
||||
- GitHub Copilot
|
||||
- OpenCode
|
||||
- Antigravity
|
||||
- Cursor
|
||||
|
||||
Truth Sync 不是通常的开工方式；它是功能代码变更后的收尾审查。
|
||||
Truth Structure 不是日常命令；只有当路由或所有权阻塞工作时，它才进行修复。
|
||||
<details>
|
||||
<summary>命令行参考</summary>
|
||||
|
||||
## 你会得到什么
|
||||
| 命令 | 用途 |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------- |
|
||||
| `truthmark init` | 创建或刷新配置、路由、模板和所选宿主的工作流 |
|
||||
| `truthmark check [--base <ref>]` | 验证仓库事实，并可选择运行分支时效性诊断 |
|
||||
| `truthmark index --json` | 检查派生的仓库和路由元数据 |
|
||||
| `truthmark impact --base <ref> --json` | 将变更文件映射到文档、所有者和附近的测试 |
|
||||
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | 检查工作流适用性和目标 |
|
||||
| `truthmark validate ...` | 验证工作流报告和写入租约 |
|
||||
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | 预览或移除生成的宿主界面，同时保留已编写的事实内容 |
|
||||
|
||||
| 能力 | 作用 |
|
||||
| --- | --- |
|
||||
| Git 原生事实 | 将仓库事实保存在已提交的 Markdown 和配置中。 |
|
||||
| 按分支生效的文档 | 事实随分支移动，而不是存在于私有会话中。 |
|
||||
| 人类 CLI | 为维护者提供设置、刷新、验证和检查命令。 |
|
||||
| 已安装的代理指引 | 告诉编码代理何时记录文档、测试、同步事实、审计或停下来等待审查。 |
|
||||
| 显式路由 | 将代码区域映射到规范事实文档。 |
|
||||
| 可审查交接 | 为代码和事实文档都产生普通 Git diff。 |
|
||||
| 本地优先运行 | 不需要托管服务、守护进程、数据库或 MCP 服务器。 |
|
||||
| 更安全的写入边界 | 区分代码优先、文档优先、只读和仅文档工作流。 |
|
||||
| 验证 | 报告路由、权限、frontmatter、链接、生成界面、分支范围、新鲜度和覆盖率问题。 |
|
||||
| 可选 Portal | 在明确启用并请求时，从 Markdown 事实文档生成已提交的静态 HTML 展示站点。 |
|
||||
整个命令行界面都提供结构化 JSON 输出，便于脚本和持续集成使用。
|
||||
|
||||
## 视觉概览
|
||||
</details>
|
||||
|
||||
|
||||
## 了解更多
|
||||
|
||||
**功能：** Truthmark 会安装什么，以及代理如何使用仓库本地指令。
|
||||
- [Truthmark 用户指南](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md)
|
||||
- [文档索引](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
|
||||
- [架构概览](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
|
||||
- [配置、路由和命令契约](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [维护仓库事实](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
|
||||
- [参与贡献](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
|
||||
|
||||
|
||||
|
||||
**定位：** Truthmark 相对于提示、记忆和规格工作流的位置。
|
||||
|
||||
|
||||
|
||||
**同步流程：** Truth Sync 如何在交接前收尾普通代码变更。
|
||||
|
||||
## 团队为什么采用它
|
||||
|
||||
Truthmark 面向已经知道 AI 代理能够生成代码的团队。
|
||||
|
||||
下一个问题是治理。
|
||||
|
||||
不是作为仪式的治理。治理只是一个简单问题：
|
||||
|
||||
> 在这次 AI 辅助变更之后，仓库仍然讲述事实吗？
|
||||
|
||||
Truthmark 通过已提交文件、显式路由和可审查 diff 帮助团队回答这个问题。
|
||||
|
||||
当你需要以下内容时，它很有用：
|
||||
|
||||
- 减少文档漂移
|
||||
- 更好的交接
|
||||
- 按分支生效的产品事实
|
||||
- 持久的架构和 API 文档
|
||||
- 文档和代码之间的明确所有权
|
||||
- 更安全的代理写入边界
|
||||
- 可审查的文档，而不是隐藏记忆
|
||||
- 仍然能从已提交仓库文件运行的 AI 工作流
|
||||
|
||||
## Truthmark 的位置
|
||||
|
||||
Truthmark 不替代提示、记忆、规格、测试或代码审查。
|
||||
|
||||
它为这些工作流提供一个可以持久落在 Git 中的位置。
|
||||
|
||||
| 需求 | 更合适的选择 |
|
||||
| --- | --- |
|
||||
| 从单次代理会话获得更好输出 | 更好的提示 |
|
||||
| 个人或会话级连续性 | 记忆工具 |
|
||||
| 先计划后实现的功能工作 | 规格工作流 |
|
||||
| 随代码一起移动的按分支事实 | Truthmark |
|
||||
| 验证行为正确性 | 测试和审查 |
|
||||
| 审查 AI 辅助的文档变更 | Truthmark 加 Git 审查 |
|
||||
|
||||
Truthmark 的边界有意很窄：
|
||||
|
||||
```text
|
||||
make repository truth explicit
|
||||
route it to code
|
||||
围绕它安装代理指引
|
||||
keep the result reviewable in Git
|
||||
```
|
||||
|
||||
## 深入了解
|
||||
|
||||
README 是门面：快速背景、快速开始和核心心智模型。
|
||||
|
||||
如需逐条命令的用法、界面对比、受支持平台详情、配置、路由、Portal 和示例，请阅读 [Truthmark 用户指南](../user-guide.md)。
|
||||
|
||||
## 项目状态
|
||||
|
||||
当前版本提供：
|
||||
|
||||
- 用于 init、check、index、impact 和 workflow status 的本地 CLI 命令
|
||||
- 为 Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity 和 Cursor 生成的仓库本地代理指令
|
||||
- 路由、权限、frontmatter、链接、新鲜度、生成界面、分支范围和覆盖率诊断
|
||||
- 按分支生效的事实文档和派生的仓库智能产物
|
||||
|
||||
## 文档
|
||||
|
||||
- [用户指南](../user-guide.md)
|
||||
- [文档索引](../README.md)
|
||||
- [架构概览](../truthmark/engineering/architecture/overview.md)
|
||||
- [API 和 CLI 契约](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
|
||||
- [仓库事实维护指南](../standards/maintaining-repository-truth.md)
|
||||
|
||||
有关本地开发和贡献命令，请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。
|
||||
|
||||
## 设计边界
|
||||
|
||||
Truthmark 有意保持小而明确：本地、已提交、按分支生效、可审查。
|
||||
|
||||
它不是托管服务、MCP 服务器、向量数据库、隐藏记忆层、CI 强制执行产品，也不是自主代码重写引擎。它帮助仓库事实保持可见；它不替代测试、代码审查或人类判断。
|
||||
**立即安装 Truthmark，选择您的编码宿主，今天就把一个真实行为转化为文档。**
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT。见 [LICENSE](../../LICENSE)。
|
||||
|
||||
## 安全移除
|
||||
|
||||
使用 `truthmark uninstall --dry-run` 查看精确生成的主机表面（host surfaces），然后使用 `truthmark uninstall --apply` 将其移除。已创建的 truth、配置、模板、Portal 输出、Gemini 文件以及不相关的用户文件将被保留；请使用包管理器单独移除全局 npm 安装。
|
||||
MIT。请参阅 [LICENSE](../../LICENSE)。
|
||||
|
||||
Generated
+6
-6
@@ -2315,9 +2315,9 @@
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/fast-uri": {
|
||||
"version": "3.1.4",
|
||||
"resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.4.tgz",
|
||||
"integrity": "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw==",
|
||||
"version": "3.1.5",
|
||||
"resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz",
|
||||
"integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==",
|
||||
"funding": [
|
||||
{
|
||||
"type": "github",
|
||||
@@ -2762,9 +2762,9 @@
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/js-yaml": {
|
||||
"version": "4.3.0",
|
||||
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz",
|
||||
"integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==",
|
||||
"version": "4.3.1",
|
||||
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
|
||||
"integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
|
||||
"dev": true,
|
||||
"funding": [
|
||||
{
|
||||
|
||||
@@ -26,6 +26,8 @@
|
||||
"files": [
|
||||
"dist",
|
||||
"README.md",
|
||||
"docs/assets/truthmark-workflow-mobile.svg",
|
||||
"docs/assets/truthmark-workflow.svg",
|
||||
"docs/readmes/README.ar.md",
|
||||
"docs/readmes/README.de.md",
|
||||
"docs/readmes/README.el.md",
|
||||
|
||||
@@ -31,6 +31,8 @@ const localizedReadmeFiles = [
|
||||
|
||||
const expectedPackageFiles = [
|
||||
"LICENSE",
|
||||
"docs/assets/truthmark-workflow-mobile.svg",
|
||||
"docs/assets/truthmark-workflow.svg",
|
||||
...localizedReadmeFiles,
|
||||
"README.md",
|
||||
"dist/main.js",
|
||||
|
||||
Reference in New Issue
Block a user