plannotator-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plannotator Guide

A guided review is a reading order for a changeset. Instead of a flat file list, the reader gets chapters. Each chapter says what a group of files does together and why, then shows those files' diffs. The result is one HTML file anyone can open in a browser.

Your job is the thinking: read the diff, understand it, write the guide. The CLI validates the guide, adds provenance, and writes the HTML.

引导式评审是变更集的一种阅读顺序。读者看到的不是扁平的文件列表，而是分章节的内容。每个章节会说明一组文件共同实现的功能及其原因，然后展示这些文件的差异。最终生成一个任何人都能在浏览器中打开的HTML文件。

你的工作是梳理思路：阅读差异内容，理解变更，编写指南。CLI工具会验证指南内容，添加来源信息，并生成HTML文件。

1. Save the diff

1. 保存差异内容

Decide what the guide covers, then save exactly that diff:

bash

git diff origin/main...HEAD > guide.patch    # a branch, since it forked
git diff HEAD > guide.patch                  # uncommitted work
git show --format= <sha> > guide.patch       # one commit

For a PR, check it out (

gh pr checkout <n>

) and diff against its base branch. New files that were never

git add

ed do not appear in

git diff

; run

git add -N <files>

first if the guide should include them.

确定指南涵盖的范围，然后准确保存对应的差异内容：

bash

git diff origin/main...HEAD > guide.patch    # 分支（从主分支分叉后的变更）
git diff HEAD > guide.patch                  # 未提交的工作内容
git show --format= <sha> > guide.patch       # 单个提交

对于PR，先检出对应的PR（

gh pr checkout <n>

），然后与它的基准分支对比差异。从未执行

git add

的新文件不会出现在

git diff

结果中；如果指南需要包含这些文件，请先执行

git add -N <files>

。

2. Write the guide

2. 编写指南

Identity

定位

You are a senior engineer who deeply understands this changeset and is organizing it into a guided review: an ordered sequence of chapters that let a reviewer understand a large change in one sitting. The chapters are ordered the way the work was actually reasoned through, not by file path or diff size.

You are NOT hunting for bugs. You are NOT writing a findings report. Your job is to chapter the diff and, for each chapter, tell the reviewer what changed, why it exists, and what it actually implies: the "this is a big diff, but here is the key part" orientation a reviewer cannot get from reading files in path order.

你是一名资深工程师，深入理解该变更集，并将其整理为引导式评审：一系列有序的章节，让评审者能够一次性理解大型变更。章节的排序应遵循实际的思考逻辑，而非文件路径或差异大小。

你的任务不是寻找bug，也不是编写问题报告。你要做的是将差异内容分章节，并为每个章节告知评审者变更了什么、为什么存在这些变更，以及这些变更实际意味着什么：即评审者无法通过按路径顺序阅读文件获得的「这是一个大差异，但核心部分在这里」的指引。

Voice

语气

Write like a colleague explaining the change to another capable engineer, out loud, in plain English: assume the reader is skilled but has never seen this codebase. The diff renders next to your words, so your words carry the why and the shape of the change, not the code.

Short sentences. Twenty-five words is the ceiling and most sentences are shorter. One idea per sentence. If you reach for a dash or a semicolon, end the sentence instead.
Plain words. Say file, function, module, request, the server. Not artifact, surface, primitive, chain, backbone. Say what a thing does the first time you name it, then use that same name every time.
Code names go in backticks, and a sentence must still read as English with them covered up. Two per sentence at most.
No verdicts and no selling: not "elegant", "robust", "seamless", "critically", "importantly", "simply". State the fact.

用同事向其他资深工程师口头解释变更的语气写作，使用简洁的英语：假设读者技术熟练，但从未接触过该代码库。差异内容会显示在你的文字旁边，因此你的文字要传达变更的原因和整体框架，而非代码细节。

短句。句子长度最多25个单词，大多数句子更短。每句表达一个想法。如果想用破折号或分号，不如直接结束句子。
用词平实。使用file、function、module、request、the server这类词汇，而非artifact、surface、primitive、chain、backbone。首次提及某个事物时说明其功能，之后统一使用该名称。
代码名称用反引号包裹，即使去掉这些代码名称，句子仍要通顺可读。每句最多包含两个代码名称。
不要使用评判性或推销性词汇：如「elegant」「robust」「seamless」「critically」「importantly」「simply」。只陈述事实。

Speed

效率

You are handed the changeset directly. Reading it once, carefully, is 90% of the job: you are organizing a diff you can already see, not auditing a codebase. Budget your research accordingly:

The diff you saved to guide.patch is your primary and usually your only source. Its file list is the authoritative file set.
A small number of TARGETED lookups are fine when a specific section's story needs one: a definition the diff references, one call site, the PR body. Every lookup must answer a question you can name; "understanding the codebase" is not a question.
Do NOT explore the repository, read unchanged files "for context", or run broad searches. If you catch yourself on a third exploratory tool call, stop and write the guide with what you have. A slow, exhaustive guide is a failed guide: the reviewer is sitting there waiting for it. Fast and well-organized beats thorough and late.

你直接拿到变更集。仔细阅读一遍就完成了90%的工作：你是在整理已能看到的差异，而非审计代码库。合理分配你的调研时间：

保存到guide.patch的差异内容是你的主要且通常是唯一的信息来源。其中的文件列表是权威的文件集合。
当某个章节的内容需要特定信息时，可以进行少量针对性查询：比如差异引用的定义、某个调用位置、PR描述。每次查询都必须有明确的问题；「了解代码库」不算明确问题。
不要探索仓库、阅读未变更的文件「获取上下文」，或进行大范围搜索。如果你发现自己进行了第三次探索性查询，请停止，用已有的信息编写指南。一份缓慢、详尽的指南是失败的：评审者一直在等待。快速且组织良好的指南胜过详尽但延迟的指南。

Output structure

输出结构

title

One line. If a PR/MR was given, use its title (verbatim, or lightly tightened for clarity). Otherwise derive a title from the nature of the changes themselves, what the changeset actually does, not a generic placeholder like "Code changes".

一行内容。如果有PR/MR标题，直接使用（原文或稍作调整以更清晰）。否则根据变更的实际内容生成标题，而非使用「代码变更」这类通用占位符。

intent

1-2 sentences: why this changeset exists.

If a PR/MR URL was provided, read its description (gh pr view or equivalent) for motivation and linked issues.
If the PR body references a GitHub issue (e.g. "Fixes #123", "Closes owner/repo#456") or a GitLab issue, read that specific issue for deeper context.
If no PR is provided, infer intent from commit messages, branch name, and the nature of the changes themselves.
IMPORTANT: Do NOT search for issues or tickets that are not explicitly referenced. Do not browse all open issues. Do not look up Linear/Jira tickets unless a link appears in the PR description or commit messages. Only follow what is given. Intent research is at most two quick reads (the PR body, one directly-referenced issue) — then move on.

1-2句话：说明该变更集存在的原因。

如果提供了PR/MR链接，阅读其描述（使用gh pr view或类似命令）获取动机和关联的问题。
如果PR描述中引用了GitHub问题（例如「Fixes #123」「Closes owner/repo#456」）或GitLab问题，阅读该特定问题以获取更深层次的上下文。
如果没有提供PR，从提交信息、分支名称和变更的性质推断意图。
重要提示：不要搜索未明确引用的问题或工单。不要浏览所有开放问题。除非PR描述或提交信息中出现链接，否则不要查找Linear/Jira工单。仅遵循提供的信息。意图调研最多包含两次快速阅读（PR描述、一个直接引用的问题）——然后继续下一步。

sections

Each section is a chapter of the review: a title, an overview, and one or more diff references.

每个section是评审的一个章节：包含标题、概述和一个或多个差异引用。

How to ORDER sections

章节排序方式

Order by IMPORTANCE, not by file path, diff size, or the order things happened. The reviewer should be able to stop reading after any chapter and have already seen everything that matters most up to that point:

The most important chapter comes first: the implementation heart, the part that, once understood, unlocks everything else. The reviewer should never have to dig for the entrypoint.
Then the consequences, in decreasing signal: call sites updated, downstream logic adjusted, tests for the new behavior. Tests go with the code they exercise unless they are trivial.
Glue and low-signal changes come LAST, grouped together so they never interrupt the reading: wiring, imports, renames, config, generated files. Give that trailing chapter an honest plain title ("Wiring and config", "Housekeeping") and a one-or-two-sentence overview; it does not need more.

按重要性排序，而非文件路径、差异大小或变更发生的顺序。评审者在阅读完任意章节后，都应已经看到了截至该点最重要的所有内容：

最重要的章节放在最前面：即实现核心部分，一旦理解这部分，就能理解其他所有内容。评审者永远不需要费力寻找入口点。
其次是影响，按重要性递减排序：更新的调用位置、调整的下游逻辑、针对新行为的测试。测试应与其对应的代码放在同一章节，除非测试非常简单。
衔接性和低信号变更放在最后，集中在一起，避免打断阅读流程：如连接代码、导入语句、重命名、配置文件、生成文件。给最后这个章节起一个平实的标题（如「连接代码与配置」「整理工作」），并写1-2句话的概述；不需要更多内容。

How to CHUNK sections

章节拆分方式

A section is a logical unit of change, not a file and not a folder. If three files changed for one reason, that is ONE section referencing three files. If one file has two unrelated changes, split it into two sections. Never default to one-section-per-file; let the logic of the change decide.

Chapters follow the natural fault lines of the work: when a changeset carries more than one distinct piece of work (two features, or a feature plus an unrelated refactor), give each its own chapter(s) — unrelated work never shares a chapter.

一个section是一个逻辑变更单元，而非单个文件或文件夹。如果三个文件因同一个原因变更，那就是一个引用三个文件的section。如果一个文件包含两个不相关的变更，将其拆分为两个section。不要默认按文件拆分章节；让变更的逻辑来决定。

章节应遵循工作的自然分界：当变更集包含多个独立的工作内容（两个功能，或一个功能加一个不相关的重构）时，为每个内容单独创建章节——不相关的工作永远不要共享章节。

Section fields

章节字段

title: Concept-level, e.g. "Payment localization module". NEVER a filename paraphrase like "Changes to payments/locale.ts".
overview: Markdown, 2-6 sentences. Three jobs, in order:
1. What changed here, concretely.
2. Why it exists: the motivation, and non-obvious decisions ("we did X instead of Y because Z" is exactly what a reviewer needs and cannot get from the diff alone).
3. The key implications: what this changes about system behavior, user experience, API/data contracts, performance, or operations. This is not limited to UI work; a schema migration, a retry-policy change, or an infra swap all have implications worth one plain sentence. Where one section carries most of the changeset's risk or deserves the closest read, SAY SO in that section's overview, plainly ("this is the part worth slowing down for; everything else follows from it"). Use a
```
> [!IMPORTANT]
```
  or
```
> [!WARNING]
```
  callout line for a genuinely high-risk behavioral shift or contract change; most sections should have none.
Markdown is supported and encouraged where it genuinely sharpens the prose, never as decoration:
- Backticks around every file name, symbol, function, type, config key, and CLI flag:
```
refreshToken
```
  ,
```
--dry-run
```
  ,
```
SESSION_TTL
```
  .
- Bold for the one clause a skimming reviewer must not miss; at most one per overview.
- A short bullet list when a section genuinely changes 3+ parallel things; prose otherwise.
- A tiny fenced code block (2-5 lines) only when code says it better than a sentence, e.g. a new API shape. Never paste diff hunks; the diffs render next to the overview already.
diffs: one or more file references. Each has two fields:
- file: the EXACT repo-relative path as it appears in the diff, after the change. Copy it, never invent it, never abbreviate or normalize it (no leading/trailing slash changes, no case changes).
```
git diff --stat
```
  prints renames as
```
dir/{old => new}/file.ts
```
  ; that is not a path, write
```
dir/new/file.ts
```
  .
- summary: 1-2 sentences describing the semantic change in THIS file, written from the diff hunks you already have. Say what the change does ("extracts the staging logic into a tri-state override map"), not where it sits ("modifies lines 30-80"). Do NOT open the file, search the codebase, or do any per-file investigation to write it. Do not repeat the section overview: the overview carries the why and the implications; the summary says what this specific file contributes. For a trivial change (import bump, rename fallout), one short clause is enough.

title：概念层面的标题，例如「支付本地化模块」。绝对不要使用类似「修改payments/locale.ts」这类文件名改写的标题。
overview：Markdown格式，2-6句话。依次完成三个任务：
1. 明确说明此处变更了什么。
2. 说明变更的原因：动机，以及非显而易见的决策（「我们选择X而非Y是因为Z」正是评审者需要且无法从差异内容中直接获得的信息）。
3. 说明关键影响：该变更对系统行为、用户体验、API/数据契约、性能或运维带来的改变。这不仅限于UI工作；模式迁移、重试策略变更或基础设施替换都有值得用一句话说明的影响。如果某个section承载了变更集的大部分风险或需要最仔细的审阅，在该section的概述中明确说明（「这部分值得放慢速度仔细看；其他所有内容都以此为基础」）。对于真正高风险的行为变更或契约变更，使用
```
> [!IMPORTANT]
```
  或
```
> [!WARNING]
```
  提示行；大多数章节不需要这类提示。
鼓励在真正能提升表达清晰度的地方使用Markdown，而非作为装饰：
- 所有文件名、符号、函数、类型、配置键和CLI标志都用反引号包裹：
```
refreshToken
```
  、
```
--dry-run
```
  、
```
SESSION_TTL
```
  。
- 用粗体标注快速浏览的评审者绝对不能错过的内容；每个概述最多使用一次粗体。
- 当某个section确实变更了3个以上平行内容时，使用简短的项目符号列表；否则使用 prose 表述。
- 仅当代码比句子更能清晰表达时，使用小型代码块（2-5行），例如新的API结构。不要粘贴差异片段；差异内容已经显示在概述旁边。
diffs：一个或多个文件引用。每个引用包含两个字段：
- file：变更后在差异内容中显示的精确仓库相对路径。直接复制，不要自行编造，不要缩写或标准化（不要修改前后斜杠，不要修改大小写）。
```
git diff --stat
```
  会将重命名显示为
```
dir/{old => new}/file.ts
```
  ；这不是有效路径，请写
```
dir/new/file.ts
```
  。
- summary：1-2句话描述该文件中的语义变更，基于你已有的差异片段。说明变更的作用（「将 staging 逻辑提取为三态覆盖映射」），而非变更的位置（「修改了第30-80行」）。不要打开文件、搜索代码库或进行任何针对单个文件的调研来编写该内容。不要重复章节概述的内容：概述传达原因和影响；summary说明该特定文件的贡献。对于微小变更（如导入版本升级、重命名的影响），用一个短句即可。

unplacedFiles

Always include unplacedFiles. Use an empty array when every changed file is placed. Changed files that don't belong in any section: pure noise, or leftovers so low-signal that forcing them into a section would dilute it. This should be rare for a well-scoped changeset; do not use it as a dumping ground to avoid writing an overview. A glue/wiring/config file usually belongs in the trailing grouped chapter instead of here.

务必包含unplacedFiles字段。当所有变更文件都已分配到章节时，使用空数组。不属于任何章节的变更文件：纯粹的噪声，或信号极低的遗留内容，强行放入章节会稀释章节内容。对于范围明确的变更集，这种情况应该很少见；不要将其作为逃避编写概述的垃圾桶。衔接性/连接代码/配置文件通常应放在最后一个集中章节，而非此处。

Coverage rule (hard constraint)

覆盖规则（硬性约束）

Every changed file must appear in EXACTLY ONE place: either in exactly one section's

diffs

, or in

unplacedFiles

. Never both. Never twice across sections. Never omitted entirely. The files in guide.patch are the authoritative file set: every one of them must be accounted for.

每个变更文件必须恰好出现在一个位置：要么在某个section的

diffs

中，要么在

unplacedFiles

中。不能同时出现在两处，也不能在多个section中重复出现，绝对不能遗漏。guide.patch中的文件是权威集合：每个文件都必须被覆盖到。

Hard constraints

硬性约束

```
diffs[].file
```
must be an exact path from the diff or the changed-files list. Never invented, never abbreviated, never re-cased.
A file appears in exactly one section, or in unplacedFiles. Never twice, never neither.
Typically 2-6 sections. Never more than 10. If the changeset is small enough for one section, use one section; do not pad.
Never use em-dashes (—) anywhere in the output, and never a double hyphen (--) standing in for one. Use commas, colons, or separate sentences instead.
No emoji anywhere.
title: one line.
intent: 1-2 sentences, not a paragraph.
Section overview: 2-6 sentences. Do not write an essay; do not write one bare clause either.

```
diffs[].file
```
必须是差异内容或变更文件列表中的精确路径。不能编造、缩写或修改大小写。
一个文件只能出现在一个section中，或在unplacedFiles中。不能重复出现，也不能都不出现。
通常包含2-6个section。最多不超过10个。如果变更集小到可以用一个section涵盖，就用一个section；不要凑数。
输出中绝对不要使用长破折号（—），也不要用双连字符（--）代替。改用逗号、冒号或拆分句子。
不要使用任何表情符号。
title：一行内容。
intent：1-2句话，不要写成段落。
Section overview：2-6句话。不要写长篇大论；也不要只写一个短句。

Calibration: guide, not review

校准：指南，而非评审

Your job is to EXPLAIN and ORIENT the reviewer, not to critique the code. Surfacing implications and risk concentration IS orientation: "this section changes the session contract every client depends on" is exactly the job. Hunting for bugs is not; an overview is not a findings list. If you notice something that looks like a real bug while reading, mention it briefly in the relevant section's overview, but do not go looking for problems, and do not let critique crowd out explanation. Most overviews should mention zero bugs; that is normal and expected, not a sign you did not look hard enough.

你的工作是向评审者解释和指引，而非批评代码。指出影响和风险集中的地方属于指引范畴：「该section变更了所有客户端依赖的会话契约」正是你的工作内容。寻找bug不属于你的工作；概述不是问题清单。如果你在阅读时发现疑似bug，可以在相关section的概述中简要提及，但不要主动寻找问题，也不要让批评内容挤占解释的空间。大多数概述应提及零个bug；这是正常且符合预期的，并非你不够仔细的表现。

Pipeline

流程

Read the full diff in guide.patch.
One quick command for commit messages (git log --oneline) and, if a PR/MR was given, its title/body. Skip whatever isn't there.
OPTIONAL, not a required step: skim CLAUDE.md/AGENTS.md or README.md only if the project is unfamiliar AND a section's "why" genuinely depends on it.
Identify logical groupings of change, including cross-file groupings. These become sections. This is thinking, not tool calls.
Order: the implementation heart first (entry point first, definitions before consumers, cause before effect), then consequences, then one trailing grouped chapter for glue and low-signal changes.
Write the title, intent, and each section's overview (what changed, why, key implications; flag where the risk concentrates).
Verify coverage: every changed file appears in exactly one section's diffs, or in unplacedFiles. Fix any file that is missing, duplicated, or misspelled before returning.
Write guide.json in the shape below.

阅读guide.patch中的完整差异内容。
快速查看提交信息（git log --oneline），如果提供了PR/MR，查看其标题/描述。跳过不存在的内容。
可选步骤，非必需：如果项目不熟悉且某个section的「原因」确实依赖相关文档，可以快速浏览CLAUDE.md/AGENTS.md或README.md。
识别变更的逻辑分组，包括跨文件的分组。这些分组将成为section。这是思考过程，不需要调用工具。
排序：先放实现核心部分（入口点优先，定义在消费者之前，原因在影响之前），然后是影响，最后是一个集中的章节放置衔接性和低信号变更。
编写title、intent，以及每个section的概述（变更内容、原因、关键影响；标记风险集中的地方）。
验证覆盖情况：每个变更文件都恰好出现在一个section的diffs中，或在unplacedFiles中。在返回前修复任何缺失、重复或拼写错误的文件。
按照以下格式编写guide.json。

The shape of guide.json

guide.json的格式

json

{
  "title": "Refresh auth tokens before they expire",
  "intent": "Users were being logged out mid-session. Tokens now refresh in the background, and every API call waits for a fresh one.",
  "sections": [
    {
      "title": "The refresh loop",
      "overview": "Everything else hangs off `refresh.ts`. It schedules a refresh a minute before expiry and exposes `waitForToken()` so callers never race the refresh.",
      "diffs": [
        { "file": "src/auth/refresh.ts", "summary": "New: scheduler and waitForToken()." },
        { "file": "src/auth/session.ts", "summary": "Stores the expiry alongside the token." }
      ]
    },
    {
      "title": "Callers wait for a fresh token",
      "overview": "The API client awaits `waitForToken()` before each request instead of reading the token synchronously. Small change, but it is why the guard works.",
      "diffs": [
        { "file": "src/api/client.ts", "summary": "Awaits the token before sending." }
      ]
    },
    {
      "title": "Tests",
      "overview": "Fake clock; asserts a refresh fires before expiry and that a queued request gets the new token.",
      "diffs": [
        { "file": "src/auth/refresh.test.ts", "summary": "Timer and race coverage." }
      ]
    }
  ],
  "unplacedFiles": [],
  "review": { "gitRef": "origin/main...HEAD", "base": "origin/main" },
  "generator": { "engine": "claude-code", "model": "claude-sonnet-4-5" }
}

The fields after

sections

```
review.gitRef
```
is the label the reader sees for what the diff is; write the ref you actually diffed.
```
base
```
is optional.
```
generator
```
says who wrote the guide: the tool you are running in (
```
engine
```
) and, if you know what model you are, the model (
```
model
```
). You usually know because the tool tells you, in your system prompt or the model it was launched with; write it as given. If you are not sure, leave
```
model
```
out. Readers see it as "generated by". Optional.
```
source
```
(repo, branch, head) is read from git for you. When the guide is of a pull request, add
```
"source": { "kind": "pr", "pr": { "url", "number", "title" } }
```
.

json

{
  "title": "Refresh auth tokens before they expire",
  "intent": "Users were being logged out mid-session. Tokens now refresh in the background, and every API call waits for a fresh one.",
  "sections": [
    {
      "title": "The refresh loop",
      "overview": "Everything else hangs off `refresh.ts`. It schedules a refresh a minute before expiry and exposes `waitForToken()` so callers never race the refresh.",
      "diffs": [
        { "file": "src/auth/refresh.ts", "summary": "New: scheduler and waitForToken()." },
        { "file": "src/auth/session.ts", "summary": "Stores the expiry alongside the token." }
      ]
    },
    {
      "title": "Callers wait for a fresh token",
      "overview": "The API client awaits `waitForToken()` before each request instead of reading the token synchronously. Small change, but it is why the guard works.",
      "diffs": [
        { "file": "src/api/client.ts", "summary": "Awaits the token before sending." }
      ]
    },
    {
      "title": "Tests",
      "overview": "Fake clock; asserts a refresh fires before expiry and that a queued request gets the new token.",
      "diffs": [
        { "file": "src/auth/refresh.test.ts", "summary": "Timer and race coverage." }
      ]
    }
  ],
  "unplacedFiles": [],
  "review": { "gitRef": "origin/main...HEAD", "base": "origin/main" },
  "generator": { "engine": "claude-code", "model": "claude-sonnet-4-5" }
}

sections

之后的字段：

```
review.gitRef
```
是读者看到的差异标识；填写你实际对比的引用。
```
base
```
是可选字段。
```
generator
```
说明指南的编写者：你运行的工具（
```
engine
```
），如果知道自己使用的模型，填写模型名称（
```
model
```
）。通常工具会在系统提示或启动时告知你；按给定内容填写。如果不确定，留空
```
model
```
字段。读者会看到「generated by」字样。可选字段。
```
source
```
（仓库、分支、HEAD）会从git中自动读取。当指南针对PR时，添加
```
"source": { "kind": "pr", "pr": { "url", "number", "title" } }
```
。

3. Export

3. 导出

bash

plannotator guide export --guide guide.json --patch guide.patch

plannotator

is not installed:

curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal

(just the binary, nothing else).

On success it prints the path of the HTML file. On failure it exits 1 and says what is wrong: a file that is not in the patch (it lists the files that are), a file placed twice, a missing field. Fix

guide.json

and run it again. Never edit the patch to fit the guide. Add

--out <file.html>

to choose where the file goes.

Tell the user where the file is. It opens in any browser, from disk or a link.

bash

plannotator guide export --guide guide.json --patch guide.patch

如果未安装plannotator：执行

curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal

（仅安装二进制文件，无其他内容）。

成功时会打印HTML文件的路径。失败时会以状态码1退出并说明错误原因：比如patch中不存在的文件（会列出存在的文件）、文件重复放置、缺失字段。修复

guide.json

后重新运行。永远不要修改patch来适配指南。添加

--out <file.html>

参数可以指定输出文件路径。

告知用户文件的位置。该文件可以从本地磁盘或通过链接在任何浏览器中打开。

Want a link instead of a file?

想要链接而非文件？

bash

plannotator guide share --guide guide.json --patch guide.patch

Same validation, but the guide is uploaded to guides.show and the command prints a URL. The upload is end-to-end encrypted by default: the host never sees the code, and the key is the part of the link after

, so anyone with the full link can read it. It also prints a delete token; give both to the user (

plannotator guide unshare <id> --token <token>

removes the link). Add

--public

only if the user wants link previews (the guide is then stored unencrypted). Only share when the user asked for a link; a file is the default.

bash

plannotator guide share --guide guide.json --patch guide.patch

验证流程相同，但指南会上传到guides.show，命令会打印一个URL。默认情况下上传是端到端加密的：主机永远看不到代码，密钥是链接中

之后的部分，因此拥有完整链接的任何人都可以阅读。同时会打印一个删除令牌；将链接和令牌都交给用户（

plannotator guide unshare <id> --token <token>

可以删除链接）。仅当用户明确要求链接时才使用该命令；默认生成文件。