diff --git a/README.md b/README.md index d1a706c..6b4b118 100644 --- a/README.md +++ b/README.md @@ -13,15 +13,16 @@ npx skills add ssh://gitea/agent-skills/skills | 组 | skill | 做什么 | 平台 | |---|---|---|---| -| Writing Clarity | `think-twice` | 重写一段输出,让它脱离上下文也能读懂,并且每条声明都经过验证 | 任意 | -| Writing Clarity | `teach-me` | 逐层讲一个主题,每轮一层,由用户决定什么时候进下一层 | 任意 | +| Writing Clarity | `think-twice` | 重写一段输出,让它脱离上下文也能读懂,每条声明都经过验证,不留只在写作过程中有意义的内容 | 任意 | +| Writing Clarity | `teach-me` | 对接上下文:长任务跑完、隔久回到旧项目、面对陌生代码时,先自己探索,再一轮讲一层 | 任意 | | Windows Tools | `disk-master` | 只读扫描磁盘占用,解释盘为什么满了,生成可交互 HTML 报告 | Windows | | Windows Tools | `everything-file-search` | 借 Everything 的 IPC 按文件名和路径极快定位文件 | Windows,需要 Everything 在跑 | | Image To Data | `baimiao-table-ocr` | 表格截图转 CSV / JSON / Markdown / XLSX | 任意,需要网络 | -`think-twice` 和 `teach-me` 放同一组不是为了好看。`teach-me` 的 SKILL.md 直接引用 -`think-twice` 目录下的 `double-check.md`、`self-contain.md`、`style.md`,只装 -`teach-me` 会让这三个指针掉空。它每个指针都带了内联兜底说明,但拿到的是简写版。 +`think-twice` 和 `teach-me` 各自完整,单独装任何一个都能用,不存在跨 skill 的文件 +依赖。放同一组是因为它们互相交接:`think-twice` 重写一次仍然没打中的时候转给 +`teach-me`,`teach-me` 遇到会活得比对话久的内容时交给 `think-twice` 过一遍。两个都 +装上,这两条路才通。 `baimiao-table-ocr` 会把图片上传到第三方服务。隐私敏感的图不要用它。 diff --git a/skills/teach-me/SKILL.md b/skills/teach-me/SKILL.md index 02505f5..4addbe1 100644 --- a/skills/teach-me/SKILL.md +++ b/skills/teach-me/SKILL.md @@ -1,73 +1,166 @@ --- name: teach-me description: > - Walk the user through something until they actually understand it — layer by - layer, one round at a time, every claim verified before it is taught. Use - when the user asks to be walked through a design, codebase, requirement, or - decision ("讲懂我", "给我讲讲", "teach me"), or wants to understand what - exists from what was built. Also fires on handover from the think-twice - skill after a second miss (a rewrite already failed). + Bring a present reader from "I do not have the context" to "I understand + this", one layer per round, by exploring the subject yourself first and + verifying every claim before you teach it. Use when the user asks to be + walked through a design, a codebase, a decision, or what an agent did on a + long task ("讲懂我", "给我讲讲", "walk me through"); when they are returning + to their own work after a long gap; when they are meeting an unfamiliar + project; or on handover from think-twice after a re-aim at a higher level + still missed. --- # Teach Me -The user is present and can talk back: teaching is a loop, not a lecture. The -goal is their understanding, confirmed by them — never declared by you. An -explainer that re-explains everything, announces the matter settled, and -changes the subject has failed, even if every sentence was true. +The user is present and can talk back, so this is a loop and not a lecture. +Their understanding is the goal, and only they can confirm it. An explainer +that covers everything, declares the matter settled and moves on has failed, +even where every sentence was true. -The rule files referenced below — `double-check.md`, `self-contain.md`, -`style.md` — are parts of the **think-twice** skill; find them in that -skill's own directory. Where think-twice is not installed, the inline clause -at each pointer carries the rule's core. +## What it is for -## Loop +Context transfer. The context exists somewhere and the user does not have it. +An agent ran a long task and they need to know what came of it. They are +returning to their own project after months away. The project is not theirs at +all, and somebody has to go read it before it can be explained. -1. **Map and slice.** Build context from zero — the user starts as a **cold - reader**: assume no earlier names or interfaces remembered. Split the subject into layers, ordered so each - layer stands on the one before it. One layer per round. -2. **Check yourself before you teach.** Every claim in the layer follows - `double-check.md` from the think-twice skill: verify it - (read the code, run the command, open the source) or label it uncertain. - When the stakes warrant, spawn a context-free subagent to blind-check a - claim. Never teach a guess. -3. **Teach one layer.** Settled things are stated directly — not re-opened as - questions. Express under `self-contain.md` from the think-twice skill: every - term glossed at first use, examples drawn from material the conversation - already holds — real files, real numbers, the user's own work — before any - abstraction. Teach the subject, not the method: this skill's own vocabulary - (layers, gates, loop) never appears in what the user reads. Chinese prose - for a human reader also follows `style.md` from the think-twice skill: - plain sentences over bold-label bullets, bold at most twice per paragraph, - no filler connectives, no emoji. -4. **Route real decisions only.** Put to the user only what changes behavior, - scope, or a public interface; digest implementation detail yourself. When a - proper decision interview emerges, hand over to the grilling skill where - installed; otherwise ask the decisions yourself, one per message, each with - a recommended answer. -5. **The user gates the loop.** A round ends with one line — 这段讲了:plus a - one-clause recap — then stop. No question attached, no preview of what - comes next: the user's natural reply is the gate. Advance on "懂了"; stay - on anything else. Never ask "clear?" — it gets a polite yes, and politeness - is not information. On "没懂": first locate the stuck point — one question, - with candidate options so answering is cheap (options belong here and only - here) — then re-teach that same layer from a different angle: a concrete - scenario walked start to end, a contrast with the thing it is most often - confused with, the technical terms reattached last. Never change the subject - yourself — when the user changes it, follow them, and pick the layer back - up when they return. +They are short of context, not of intelligence. Never ask them to remember, to +go look something up, or to explain their own project back to you. - The final round closes differently: a short summary of everything taught, - conclusion first — not a completion announcement. +## Two inversions -## Done when +The **grilling** skill interrogates the user until a design is settled. This +skill runs the same machine backwards: it interrogates itself, on their behalf, +until they are oriented. -The user says they understand, or says it is enough. Nothing else ends the -loop — not your own judgement that the matter is settled. +- **Grill yourself, not the user.** Ask the questions they would ask if they + already knew enough to ask them, then go and answer those questions. +- **Finding out is your job.** Every fact you need, you fetch. A question you + would have to put to the user is a question you have not done the work on + yet. -## Out of scope +## The loop -Multi-session curriculum learning (workspace, lessons, learning records) is -the `teach` skill, where installed. Rewriting one outgoing text is -`think-twice`. This skill is the live loop that gets a present user from -"没懂" to "懂了". +### 1. Go find out first + +Read the code, the history, the task transcript, the files. Dispatch a subagent +for anything wide, and do not block on it: only the layers that depend on a +running search wait for it. + +Never teach a guess. A claim goes in verified, or it goes in carrying an +explicit "I have not checked this". Where verification is impossible from here, +say what is unknown and what would settle it. + +**Complete when:** nothing you are about to say rests on a guess, and no +remaining unknown would change the shape of the story. + +### 2. Slice it into layers + +Order them so each layer stands on what has already been taught. The first +layer is whatever makes the rest make sense, which is usually why the thing +exists and what breaks without it. It is almost never the file tree. + +Keep the ordering live. What the user asks reshapes it. + +**Complete when:** the next layer depends on nothing the user has not already +been told. + +### 3. Grill yourself on this layer + +Before teaching it, put the user's questions to it yourself. Why does this +exist? What breaks without it? How is it different from the thing it is most +often confused with? How do you know? Anything you cannot answer sends you back +to step 1. + +**Complete when:** for every sentence in the layer, you can say why they should +believe it. + +### 4. Teach the layer + +Settled things are stated, not re-opened as questions. + +Two axes set the altitude. **Access** is what they can open right now; +**background** is what they already know. Someone who owns the repository but +has never read it can open everything and still needs the design rather than +the schema. Pitch one level above what feels right and let them pull you down. + +Gloss every term at first use. Quote in the original and put the reader's +language right after it. Say what the thing is, not what somebody earlier +guessed wrong about it. + +Length is part of teaching, not a separate concern. A layer that runs three +screens was two layers. + +This skill's own vocabulary — layers, rounds, exploring — never appears in what +the user reads. Teach the subject. + +**Complete when:** the layer stands on its own and can be read in one pass. + +### 5. Close the round with a divider, and fix where you are + +End the prose, put in a divider, and add a short block that leaves the reader +able to say three things: what is being covered, what this layer concluded, and +what comes next. + +The third one is what makes continuing feel worth it. A reader who cannot tell +whether the end is near has no reason to stay. + +Field names, layout, and whether to show progress are yours to choose each +round. Two rounds that look identical mean you stopped thinking. + +The final round closes differently: recap the whole path, layer by layer, +conclusion first, then ask what is still open. + +**Complete when:** the reader can answer all three without scrolling up. + +### 6. Read what comes back, then move + +No confirmation is required and "got it" is never requested. Asking "is that +clear?" buys a polite yes, and politeness is not information. Any reply is a +signal: + +- They follow the thread you left, so teach the next layer. +- They ask about something else, so follow them there and pick the layer back + up when they return. +- They say they are lost, so find the stuck point first with one cheap question + that offers candidates, then re-teach that same layer from another angle: a + scenario walked start to finish, or a contrast with whatever it gets confused + with, technical terms reattached last. +- A real decision surfaces, so put it to them one at a time, each with a + recommended answer, and only where it changes behaviour, scope or an + interface. Digest implementation detail yourself. Where **grilling** is + installed and a full interview is warranted, hand over to it. + +**Complete when:** they say they have it, or say it is enough. Your own +judgement that the matter is settled does not end the loop. + +## A round ending, filled in + +``` +…(the layer itself) + +--- +Now Why the rules ended up in one file (layer 2 of about 5) +So far Splitting them out made following them optional, and did not + make the file smaller +Next Which rules genuinely do belong somewhere else +``` + +The shape above is one round's answer, not a form to fill in. + +## Working with other skills + +**think-twice**, where installed, owns the rules for prose that has to stand +alone; run a layer through it when that layer will outlive the conversation. +Nothing here depends on it being present. + +**grilling** takes over when the session turns from explaining into deciding. + +**teach**, where installed, owns multi-session curriculum work with its own +workspace and records. This skill is one live session. + +## Boundary + +Rewriting a single outgoing text is think-twice. This skill is the live loop +that gets a present reader from lost to oriented. diff --git a/skills/think-twice/SKILL.md b/skills/think-twice/SKILL.md index bd864f0..9b7d062 100644 --- a/skills/think-twice/SKILL.md +++ b/skills/think-twice/SKILL.md @@ -1,77 +1,173 @@ --- name: think-twice description: > - Rebuild output so a reader with only this text can understand or act, with - every claim verified. Use when the user doesn't understand your last - output, asks to expand / explain / rewrite plainly / make it - self-contained; when shipping prose that must stand alone (handoff, - PR/issue body, doc, subagent brief); or when another skill needs a clarity - or evidence pass. + Rebuild an outgoing text so a reader holding only it can understand or act, + with every claim verified and nothing left in it that only mattered along the + way. Use when the user says they do not understand, asks to expand / explain / + rewrite plainly / make it self-contained; when shipping prose that must stand + alone (handoff, PR or issue body, doc, subagent brief, summary of a system); + or when another skill needs a clarity or evidence pass. --- # Think Twice -Do not polish the last draft with more jargon. Rebuild from **only what will -appear in the output you send**, on two pillars: +Do not polish the last draft. Rebuild it from only what will appear in the text +you send. -- **Self-contained** — the words work alone for the **cold reader**: someone - with this text and only what is guaranteed in front of them. Rules in - [self-contain.md](self-contain.md). -- **Double-checked** — every claim in them is verified or labeled. Rules in - [double-check.md](double-check.md). +Three questions decide every rule below. A rule that answers none of them does +not belong here, however good the writing advice. -Skip trivial one-liners the user already follows. +- **Can they parse it?** The reader hits a word or a pointer they cannot + resolve, and the paragraph stops. +- **Is it true?** They read it, act on it, and reality does not match. +- **How much of it survives?** They open it a week later and have to wade + through what only mattered while it was being written. -## Second miss +A text can pass one and fail the others. Verification comes first: fluent +invention does more damage than clumsy truth. -A rewrite already shipped and they still don't get it, or ask the same -question in other words → invoke the **teach-me** skill (needs a reader who -can talk back); never a third rewrite. Where teach-me is not installed, do the -minimum it would: locate the stuck point with one question, then re-explain -that point through a concrete example. +One case skips the whole process: a throwaway one-line instruction the user has +already acted on, or already knew. Do not rewrite it and do not verify it. + +## The reader + +Two axes, and using only one of them is the common failure. **Access** is what +they can open right now. **Background** is what they already know. + +| | knows the domain | does not | +|--------------------|-------------------------------|-----------------------------------------------------| +| can open the code | exact locations, code, schema | the design one level up; code as an optional anchor | +| cannot | conclusion and boundaries | consequences and comparisons | + +The table is a default, not a verdict. A reader in the top-left cell who is +optimising for speed may still want the design level and no code at all. When +it is unclear, one direct question is faster than a guess. + +Pitch one level higher than feels natural and let them ask downward. Opening +with code or a schema is a choice that needs a reason: they asked for it, or +they have quoted it themselves. + +The **cold reader** holds this text plus whatever is guaranteed in front of them +at the moment they read it, and nothing else. Assume that moment is a week from +now and the conversation is gone. An LLM cold reader is worse off than a human: +it does not error on an undefined reference, it silently invents a plausible +meaning for it. ## Process -1. **Diagnose** — one primary blocker: **concept** | **scope** | **steps** - | **token** (undefined word or dangling reference). Fix the highest one - first. For proactive prose where no one is stuck yet, diagnose the blocker - the reader is most likely to hit. -2. **Three questions**, answered silently: what does the reader have right now - (default: the cold reader)? Can they understand or act from that - alone? Which facts must the text pin — conclusion, scope, evidence, next - step? -3. **Double-check** — verify every claim the text will make, per - [double-check.md](double-check.md). -4. **Rebuild — do not patch.** Substance order: conclusion → what it is in - plain terms → in/out of scope when partial work matters → evidence when - trust matters → minimal path when action matters (success shape; on - failure, the next move, not only an error name). Every line obeys - [self-contain.md](self-contain.md). -5. **Deliver.** Match the shape to the reader and the scene. Only two rules are - fixed: conclusion first, and drop anything that does not change - understanding or action. For a chat reply to a person, short is the - default. This draft shape is scaffolding, not a mould; use it, reshape it, - or discard it: +### 1. Locate the blocker - 1. **Takeaway** — 1–3 sentences - 2. **Need-to-know** — only terms blocking this message (omit if none) - 3. **Next step** — only if boundaries or action matter +Pick the highest one: **level** (pitched at the wrong altitude) | **concept** | +**scope** | **steps** | **token** (undefined word or dangling pointer). Then +name which conclusion, boundary, evidence and next step this text must carry. - The slots name the substance and its order, not literal headings — they can - be plain sentences. Chinese prose for a human reader additionally loads - [style.md](style.md), an optional part. +**Done when:** one blocker is named and every load-bearing slot is listed. -## Done when +### 2. Fill, then verify -- [ ] Passes the [self-contain.md](self-contain.md) final check -- [ ] Passes the [double-check.md](double-check.md) final check -- [ ] Conclusion first; everything left changes understanding or action -- [ ] Chinese human-facing output: every [style.md](style.md) rule swept, rule - by rule -- [ ] A second miss went to teach-me — or, where it is not installed, to its - minimum — not a third rewrite +Two jobs, and the second does not cover the first. -## Out of scope +**Fill** — go find the facts that belong in the text and are not in the draft +yet. A draft that never mentions a thing raises no alarm on its own, so nothing +downstream will catch the omission. -This skill rebuilds the words; tracker/PR mechanics (linking, closing, -labels) belong to whatever process owns them. +**Verify** — every claim already drafted gets checked against its source: read +the file, run the command, open the page. Where verification is impossible from +here, write what is unknown and what would resolve it. + +**Done when:** no load-bearing fact is missing, guessed, or unlabeled. + +### 3. Rebuild, do not patch + +Order: conclusion, then what it is in plain observable terms, then in and out of +scope where partial work could be misread, then evidence where trust matters, +then the minimal path where action matters, including the success shape and the +next move on failure. + +**Done when:** every line obeys the rules below. + +### 4. Deliver + +Conclusion first, always. Short is the default for a person reading in chat. + +Go long only when the artifact itself is long-form (a handoff, a PR or issue +body, a doc), or the user asked for detail, or the load-bearing facts do not fit +without changing meaning. When it has to be long, put the body in a file and +keep the chat message short. + +**Done when:** a reader holding only this can say what it means, how far it +goes, and what to do next, wherever those questions matter. + +## Rules + +### Can they parse it + +- **No dangling references.** Undefined unless the body supplies them: "as + discussed", "per the design", "as usual", "as you mentioned", "see above". + Same for a private path or id used as the only source of a required fact. + Restate the fact, or give a locator **and** what to take from it. +- **Gloss on first use.** Acronyms, nicknames, codenames, internal shorthand: + one clause, at the first appearance, nowhere else. +- **One term, one meaning.** A thing keeps its name for the whole text; a + synonym halfway through reads as a second thing. +- **Mechanism, then name.** What they can see or do comes first; the internal + label second. +- **Define before you label.** Why it matters, what it does and does not do, + then the name for it. +- **Pin partial work.** What this does, what it deliberately does not, and + whether the larger goal is finished or only advanced. +- **Quote in the original, gloss in the reader's language.** A verbatim quote is + evidence; an untranslated one is a wall. + +### Is it true + +- **Verified or labeled.** Evidence you actually checked, or an explicit + "unverified". Never a guess in a conclusion's voice. +- **Evidence is concrete.** The file and line, the command and its real output, + the exact quote. "I checked" is not evidence. +- **Quotes carry attribution.** A decision, constraint or priority is quoted + verbatim, in its original wording, with who said it and when. A paraphrase + presented as fact turns a reversible decision into a law of physics. +- **Fact and judgement stay visibly apart.** A verifiable fact gets checked. + Someone's decision gets attributed. +- **Predict, then look.** Write the expected result before reading the actual + one. Matching afterwards is back-fitting, and the output would have + "confirmed" whatever you wrote. +- **Work already run is evidence.** Copy its real output instead of re-running, + which can repeat side effects. Predict-then-look still applies to it. + +### How much survives + +- **Cut the path you took.** The reader needs the decision and the shortest + route to it, not the dead ends. Evidence attaches to a claim; it is never + narrated as history. Test: if a sentence needs "first, then, and it turned + out" to stand up, it is process, so cut it. +- **Say what it is, not what it is not.** A negation earns its place only if the + reader would arrive at that wrong idea on their own. "This script does not + delete files" is a boundary and stays. "Not used as an SSH jump host", written + only because someone in the conversation had guessed wrong, is a correction + scar and goes. Delete the sentence and check whether the misreading comes + back. +- **Date everything that moves.** Absolute dates, never "last week". Drop "now", + "currently" and "just", or pin the moment they refer to. A pointer to + something that changes, such as a branch head or a running process, is marked + as a snapshot. +- **Drop whatever does not change understanding or action.** +- **No appendix for safety.** Length is not thoroughness. + +### Chinese prose for a human reader + +Also load [style.md](style.md), the only conditional part of this skill. + +## When the rewrite misses + +They still do not get it, or ask the same thing in different words. Diagnose +**level** before anything else: the usual cause is prose pitched below the +reader, and the fix is one re-aim higher, not a handover. A miss that survives +that goes to the **teach-me** skill, which needs a reader who can talk back. +Never a third rewrite. + +## Boundary + +This skill governs the words. Tracker links, close keywords and PR mechanics +belong to whatever process owns them. diff --git a/skills/think-twice/double-check.md b/skills/think-twice/double-check.md deleted file mode 100644 index 2915387..0000000 --- a/skills/think-twice/double-check.md +++ /dev/null @@ -1,36 +0,0 @@ -# Double-check — the claims hold - -A claim that reaches the reader unverified is a guess wearing a conclusion's -clothes. The first mismatch the reader finds costs the whole text its credit. - -## Rules - -- **Verified or labeled.** Every claim either carries evidence you actually - checked — code read, command run, file opened, source quoted — or an - explicit uncertainty label ("unverified", "low confidence, no repro"). - Never write a guess in a conclusion's voice. -- **Evidence is concrete.** The file and line, the command and its real - output, the exact quote. "I checked" is not evidence. -- **Quotes are evidence.** A decision, constraint, or priority is quoted - verbatim, in its original language, with who said it and when. A paraphrase - is your judgement of their words; presented as fact, it turns a reversible - decision into a law of physics for the reader. -- **Fact vs judgement.** A verifiable fact gets checked. Someone's decision - gets attributed. Keep the two visibly distinct in the text. -- **Pre-commit, then look.** When a claim can be tested (a command, a check), - write the expected result before looking at the actual one. Matching after - the fact is **back-fitting** — the output would have "confirmed" whatever - you wrote. -- **Already-run work is evidence.** Something executed earlier in this session - proved itself then — copy its real output; re-running can repeat side - effects. Pre-commit still applies: write the success condition from the - step's original goal before inspecting that old output, or you are - back-fitting. -- **Blocked legwork is stated, not papered over.** If verification is - impossible from here, write what is unknown, why, and what would resolve - it. That sentence is itself the label. - -## Final check - -Strip every sentence you could not defend if the reader asked "how do you -know?". What survives is the text. diff --git a/skills/think-twice/self-contain.md b/skills/think-twice/self-contain.md deleted file mode 100644 index 0597d01..0000000 --- a/skills/think-twice/self-contain.md +++ /dev/null @@ -1,34 +0,0 @@ -# Self-contain — the words work alone - -The **cold reader** has only this text, plus whatever is guaranteed to be in -front of them at the moment they read it. Every reference must resolve inside -that set. An LLM cold reader is worse off than a human: it does not error on -an undefined reference — it silently invents a plausible meaning for it. - -## Rules - -- **No dangling references.** Undefined unless the body supplies them: "as - discussed", "per the design", "as usual"; "see above" with no findable - target; a private path or id as the *only* source of a required fact. - Restate the fact, or give a resolvable locator **and** what to take from it. -- **Gloss on first use.** Acronyms, nicknames, codenames, team shorthand — one - clause, at the first appearance, nowhere else. -- **One term, one meaning.** A thing keeps its name for the whole text; a - synonym midway reads as a second thing. -- **Mechanism → observable consequence.** What the reader can see or do, not - internal names first. Plain words first; technical name second. -- **Define before you label.** Why it matters → what it does and does not do → - this text's scope. The label comes after the reader can already picture it. -- **Pin partial work.** What this can do, what it deliberately does not, - whether a larger goal is finished or only advanced. -- **Match detail to what the reader can use.** If they have only the text, put - boundaries and failure next-moves in the text. If they can open or run - things, say exactly how. -- **Examples fit the reader.** Output that ships beyond this conversation gets - generic, domain-neutral examples. Inside a conversation, the reader's own - material is shared context and the best example there is. - -## Final check - -Hand the text to the cold reader. If they must ask "what is X / how far does -this go / what's out / what next?", not done. diff --git a/skills/think-twice/style.md b/skills/think-twice/style.md index 2be322e..678f8ad 100644 --- a/skills/think-twice/style.md +++ b/skills/think-twice/style.md @@ -1,18 +1,52 @@ # Style — 中文表述 (optional part) -Load only when the output is Chinese prose for a human reader; even then, -skip code-heavy text. This file is a guardrail against model-flavoured -prose; when model writing no longer needs it, delete the file and every -pointer to it (grep both skills for style.md) — neither core depends on it. +Load only when the output is Chinese prose for a human reader; even then, skip +code-heavy text. This file is a guardrail against model-flavoured prose; when +model writing no longer needs it, delete the file and every pointer to it (grep +both skills for style.md) — neither core depends on it. -Every rule is countable. Before delivery, sweep the list once: each rule -passes, or the text changes until it does. +Every rule is countable. Before delivery, sweep the list once: each rule passes, +or the text changes until it does. -1. **删空转连接词**:此外 / 然而 / 值得注意的是 / 需要指出的是。句子没了它们照样成立。 -2. **删填充开场**:为了实现这一目标 → 为了这一点;在这个时间点 → 现在;系统具有处理的能力 → 系统可以处理。 -3. **禁 `**小标题:** 一句话` 式 bullet 列表**。每项都以加粗标签加冒号开头的列表是模型腔;写成句子。(输出文档里操作步骤内的字段标签,如「操作:」「预期结果:」,是结构,保留。) -4. **禁强行三段式**。三个并列项逐个做删除测试:删掉后不改变动作、判断或风险的,删。两项或四项都正常。 -5. **加粗每段最多两处**。加粗是"读者不能错过",多了等于没有。 -6. **连续三句同长,破一句**。 -7. **删中文破折号(——)**,改逗号或句号。 -8. **无 emoji**。 +## 句子 + +1. **成分要齐**。主谓宾缺一个就重写。"一段文字可以过掉其中一个",宾语是什么、 + "一个"指什么,都没说,改成"一段文字可能通过了其中一问"。 +2. **代词不留空**。"这三个"而不是"三个","另外两问"而不是"另外两个"。指代如果 + 要读者往回翻才能确定,就把名词写回去。 +3. **不把动词当名词用**。"读者撞上一个解析不了的指代"里的"指代"是名词化,改成 + "读者遇到一个理解不了的词"。 +4. **一句一个意思**。一句里塞了两件事就拆成两句,长句拆行,不靠逗号串。 +5. **连续三句同长,破一句**。 + +## 用词 + +6. **不用黑话**。判据是把这个词单独拿给没参与过对话的人看,他能不能懂。"入库" + "正本""落点"都不合格,写成"放进仓库""正式版""实现"。 +7. **抽象比喻换直白**。"两个轴"写成"两个互相独立的维度","挑最高的那个"写成 + "挑最该先解决的那个"。 +8. **英文术语原词在前,中文解释跟在括号里**。写 `frontmatter description + (文件头部的 description 字段)`,不写 `头部说明(frontmatter description)`。 + 引用整段英文原文时,紧接着给一句中文释义。 +9. **删空转连接词**:此外 / 然而 / 值得注意的是 / 需要指出的是。句子没了它们 + 照样成立。 +10. **删填充开场**:为了实现这一目标 → 为了这一点;在这个时间点 → 现在; + 系统具有处理的能力 → 系统可以处理。 + +## 篇幅 + +11. **宁可多几个字,也不压缩到读不懂**。"用户已经照做的琐碎单句,跳过"省掉了 + 条件,读者拼不出来,改成"某句话如果只是琐碎的一次性指令,用户又已经照做过 + 或者本来就知道,那就跳过"。 +12. **禁强行三段式**。三个并列项逐个做删除测试:删掉后不改变动作、判断或风险 + 的,删。两项或者四项都正常。 +13. **加粗每段最多两处**。加粗是"读者不能错过",多了等于没有。 +14. **禁 `**小标题:** 一句话` 式 bullet 列表**。每项都以加粗标签加冒号开头的 + 列表是模型腔,写成句子。(输出文档里操作步骤内的字段标签,比如「操作:」 + 「预期结果:」,是结构,保留。) + +## 符号 + +15. **标点跟语境走**。中文语境用全角:,。():;英文语境用半角:`,.():`。 + 一句中文里嵌英文术语或者代码,术语本身按英文写,包住它的标点仍是全角。 +16. **无 emoji**。