Communitygithub.com

truepath

生成一个自包含的HTML模拟,逐步解释流程或Bug路径——一个点沿着实际路径移动,数据面板显示每一步的变化,并排播放“之前/之后”场景,标记首次分歧点。裁决由仓库自身代码(在冻结的Git快照上执行预言机)或声明的JS移植版本计算,构建过程拒绝编写任何与裁决相矛盾的内容。

truepath 是什么?

truepath是一个专为开发者和AI代理设计的技能,用于生成独立的HTML模拟,直观展示流程执行、Bug路径或规则决策过程。它通过一个`spec.json`文件定义流程(节点和边)、场景(路径、消息、标题、输入)以及裁决来源。`build.py`脚本负责计算裁决结果、布局图形、执行检查,并最终生成一个离线可用的HTML文件。该技能支持两种裁决来源:当规则存在于仓库代码中时使用“预言机”(Oracle,基于冻结的Git快照运行),否则使用声明的JS移植版本(Port)。生成的HTML页面包含一个动画路径(一个点沿着真实路径移动)、一个显示每一步变化的数据面板,并支持“之前/之后”场景并排对比,自动标记首次分歧点。truepath适用于Claude Code、Cursor、Codex等AI编程助手平台,特别适合在开发者要求“展示流程运行”、“动画化这个Bug”、“比较修复前后效果”或解释带真实或示意案例的决策规则时使用。其核心优势在于确保模拟与真实代码逻辑一致,任何与裁决相矛盾的内容都会被构建过程拒绝。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bastien-gallay/truepath/tree/HEAD/skills/truepath

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

truepath 是做什么的?

One spec.json describes the process (nodes, edges), the scenarios (path, messages, captions, inputs) and where the verdicts come from. build.py computes the verdicts, lays the graph out, runs the checks, and writes one offline .html — or nothing.

spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html   (or nothing)
layout.py ──┘                                └► fixture.json (--export)

Workflow

  1. Copy the nearest example next to the subject's notes (see Files), rename spec.json to <subject>.spec.json.

  2. Describe nodes and edges. Every sink node (an outcome) gets a kind; kinds are the only colours, each with a legend label.

  3. Choose where the verdicts come from (see below): an oracle when the rule exists in code, a JS port otherwise.

  4. Write the scenarios. Each declares its origin, its inputs, the expected verdict fields, and its steps along real edges.

  5. Build, then open the file:

    python3 <skill-dir>/scripts/build.py <subject>.spec.json
    
  6. Read the violations, fix the spec — never the check.

spec.json builds sim.html, <subject>.spec.json builds <subject>.sim.html; -o names another file.

The page opens on the first tab with the detail panel open. Folding the panel switches to the overview: the whole path drawn, one dot looping on it.

Where verdicts come from

SourceSpec keyUse whenMarked in the panel
Oracleoraclethe rule exists in a repository✓ code
Portport: "decide.js"no code yet, a rule under discussion, a process with no code⚠ ported

Oracle protocol. build.py takes git archive of oracle.ref (never the live checkout: a branch under work may move during the build), extracts oracle.paths, links oracle.link (typically node_modules) and copies oracle.files into it, then runs oracle.cmd in oracle.cwd with:

  • TRUEPATH_ORACLE_IN: a JSON array of every scenario's inputs;
  • TRUEPATH_ORACLE_OUT: where to write a JSON array of verdicts, same order.

oracle.repo is read from the spec's folder when it is relative. link and files are both written {path in the snapshot: where it comes from}: a path in the repository for link, a file next to the spec for files.

A verdict is an object of fields. outcome is required: it names the node the path must end on, and is what ties a scenario to the logic. basis optionally says, per field, whether real code computed it ("code: …"), the glue copied a behaviour ("port: …"), or the simulation defines it (any other text, shown ◇ definition). The page shows that mark next to every panel value whose field has a basis, its full text on hover, and --export asserts only fields whose basis is code: a field with no basis counts as code under an oracle, as ported under a port. One oracle can mix them: a rule still under discussion is ported beside the rules the code already runs. Any runner works: a test file of the project's own framework, a script, a JUnit test for Java. The footer names the ref and the short sha that produced the verdicts.

A test-file oracle can double as a regression suite: when TRUEPATH_ORACLE_IN is set it writes the verdicts, otherwise it reads the exported fixture and asserts it. The scenarios then live once, in the spec, and run in CI. examples/loyalty-tier/src/oracle.js does both.

Spec reference

KeyShapeNotes
title, subtitle, sourcestringssource lands in the footer; like every text of the spec they are shown as text, never read as HTML
langen (default) or frlanguage of the page's own words; the spec's text is written in that language
kinds{id: {label, color}}at most 4
nodes[{id, label, role?, kind?}]role: "decision" marks a branching point; where a path starts is found, and drawn round; sinks need kind
edges[[from, to, label]]label "" for none
panel[{label, value, at, labels?, digits?, compared?}]value reads inputs.x or verdict.y; shown from step at (0 is the first); labels maps a value to what the page shows ("true", "false", "null", "[]" for those values); digits zero-pads a numeric code to that length; compared: true for the row naming what a pair compares (the fix, the rule), left out of the first-divergence search
scenarios[{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}]origin: {kind: real|illustrative, text}; steps: [{hop: [from, to], message, caption}]; undecided: true flags a rule not decided yet; caseName names the case in an exported fixture
pairs[{before, after, tab, summary}]two scenario ids, played side by side as − and +; same number of steps
grid{baseline, questions | variants, cases, steps, expect?, show?, hover, summary?}cases × answers (or rules, fixes), instead of scenarios and pairs: see below
oracle{repo, ref, paths, link?, files?, cwd, cmd}see above
portpath to a CommonJS file exporting decide(inputs)used when there is no oracle
export{dir, fixture, assert}--export <worktree> writes the fixture there

Comparing several rules: the grid

When the question is "what does each possible answer do to each case", declare a grid. Prefer questions to a flat list of rules: the reader decides question by question, so the page should be laid out that way.

  • baseline: {id, label, short?, inputs}, what happens today;
  • questions: [{id, text, options: [{id, label, inputs}], cases, if?}]. cases lists the cases that question is decided on; if: {"Q1": "1A"} asks it only after that answer. build.py derives one variant per coherent set of answers (1A+2A, 1A+2B, 1B), merging the options' inputs;
  • cases: [{id, label, summary, origin, inputs, steps?}]; label names the row in words a reader knows, not a case code;
  • steps: shared by all cells unless a case brings its own;
  • expect: {case: {variant: {field: value}}}, checked by C3;
  • show: the one panel row a matrix cell shows (by default the first of hover); hover: the rows a cell shows on hover;
  • summary: a line above the matrix.

A flat variants: [{id, label, short?, note?, inputs}] with baseline as an id still works: the matrix then has one section, every case against every variant.

The page opens on the matrix: one table per question, its cases against today and each answer, the cell's line marked ≠ where it differs from today. There is no tab per case: a click on a cell opens it, today next to that answer, with the first divergence marked. Two button rows, − and +, pick either side among the section's answers (1A next to 1B, not only next to today), each named as its question names it; ← matrix goes back. In the panel, a row with "value": "answer" and "compared": true names the answer played.

Step templates. message, caption and hop may quote {inputs.x} or {verdict.y}: they are filled after the logic ran, formatted like the panel row reading the same path. A hop to {verdict.outcome} lets one step list serve every rule.

Checks

IdRefuses
C1a step whose hop is not an edge
C2a path that breaks, does not start at a source node, or has no step
C3an expect field the logic contradicts
C4a path that ends elsewhere than the logic's outcome, or a logic that gives none
C5an outcome without a kind, a kind without a legend, more than 4 kinds
C6a label wider than its box (13px monospace)
C7a scenario without an origin saying real or illustrative, and where from
C8a pair whose scenarios cannot advance together, or are unknown
C9a panel row that reads a field a scenario lacks
C10a matrix cell naming a panel row that does not exist
C11a case shown under a question whose cell still depends on another question
C12a case in no matrix section, or a section naming an unknown case
C13a panel row set to appear at a step the scenario does not have

C3 and C4 are the point: a scenario that says something the code does not do cannot be published. C6 guards the layout rather than the spec: boxes are sized to their labels, so it fires only if layout.py stops doing so. Prove a new check bites by breaking its input once, in tests/. Each check is one function in build.py, listed in CHECKS under the id of this table.

A spec the build cannot read at all (a missing key, an edge to an unknown node, a port that throws) is refused the same way, in plain words, before the checks run.

Design rules

  • One moving element per diagram: a single dot, constant speed, one hop at a time. Two diagrams side by side move in step.
  • Taken edges are solid, untaken ones dashed and grey; nodes off the path fade.
  • Colour encodes the outcome kind only. In a pair, the first divergence (the first step where a panel value differs) is outlined amber and marked ≠ on both sides, and the panel shows − / + columns.
  • Illustrative scenarios only where no real case reaches that outcome; say where the real case comes from (ticket, record, measure, date).
  • A grid shows one field per cell; three fields per cell made the matrix unreadable.
  • Light theme by default, dark under prefers-color-scheme; no web font, so the file works offline.

Files

PathRole
scripts/build.pyreads the spec, gets the verdicts, runs the checks, writes the page and the export
scripts/runtime.htmlthe page; build.py gives it what it shows, already formatted, and nothing else of the spec
scripts/layout.pylayered layout: boxes sized to their label, orthogonal edges
examples/refund-window/a JS port and a before/after pair
examples/free-shipping/a grid: two open questions, each decided on the cases it changes
examples/loyalty-tier/an oracle on the folder's own src/, its glue and the fixture --export writes

Generated files (.truepath/, where an oracle's snapshots live, and *.html next to a spec) are build output. The port examples keep their sim.html so the skill can be seen without running it. loyalty-tier keeps none: its footer names the commit that produced the verdicts, so the page changes with every commit, and it builds only inside a git repository that holds it.

Limits

  • One diagram type: the process flow. Sequence and architecture views are not built.
  • C6 is measured on macOS (ui-monospace); a narrower Windows font only adds air.
  • Steps are declared, not derived from the logic: C3 and C4 catch a wrong outcome, not a wrong intermediate message.

相关技能