{"id":"7b5046a1-3a54-4a70-aeff-41fa35b18ca2","entityType":"agent","slug":"clawhub-docsor1212-paper-rewriter","name":"Pkg Paper Rewriter Claw","canonicalUrl":"https://www.xpersona.co/agent/clawhub-docsor1212-paper-rewriter","canonicalPath":"/agent/clawhub-docsor1212-paper-rewriter","generatedAt":"2026-10-14T18:12:30.421Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:10:38.246Z","emptyReason":null},"description":"Academic writing style toolkit, bilingual CN/EN: AI flavor scan and style-pattern self-check reports (scan reports are detection only), deterministic text cleanup (model artifacts, punctuation, filler phrases), integrity guardrails (numbers, DOIs, PMIDs, terminology must survive untouched), and agent-guided style naturalization for clearer, more natural academic prose (de-templating, de-translationese, rhythm, concreteness). Built for scholars whose formal writing reads stiff, templated or machine-flavored — especially non-native (ESL) authors. Includes AIGC-disclosure compliance checks (China 2025-09 labeling rules) and academic-integrity guardrails: this tool improves writing quality for self-review; it does not help misrepresent authorship, conceal required AI disclosure, or defeat integrity review. 100% local, zero upload, Python stdlib only. Related: paper-polisher-pro (broad polishing), pubmed-verifier, cite-holmes, academic-figures, cn-med-oa, doc-holmes.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 970 downloads reported by the source. Last updated 10/12/2026.","installCommand":"clawhub skill install s17dagtwyk21qs6vpz98bzcrh1853t29:paper-rewriter","sourceUrl":"https://clawhub.ai/docsor1212/paper-rewriter","homepage":"https://clawhub.ai/docsor1212/skills/paper-rewriter","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/docsor1212/paper-rewriter","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/docsor1212/skills/paper-rewriter","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Pkg Paper Rewriter Claw technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:10:38.246Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:10:38.246Z","emptyReason":null},"stars":null,"forks":null,"downloads":970,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"3.2.0","tractionLabel":"970 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:10:38.230Z","emptyReason":null},"lastUpdatedAt":"2026-10-12T00:10:38.246Z","lastCrawledAt":"2026-10-12T00:10:38.230Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-13T00:10:38.230Z","lastVerifiedAt":null,"highlights":[{"version":"3.2.0","createdAt":"2026-10-10T17:16:21.686Z","changelog":"v3.2.0: statistical consistency guard. New check_stats.py catches three classes of numbers that fight each other: percent lists not summing to 100 (only sentences with partition cues like respectively - legitimate non-exhaustive lists such as comorbidity shares are never flagged), the same group appearing with two different n (time-point variants like final n are kept distinct - attrition is legitimate), and mixed p/P notation style (advisory only - journal conventions differ). Exit codes match check_terms so it drops straight into CI; JSON and markdown report outputs carry the original-data-first disclaimer. Also: expanded English trigger phrases and four FAQ answers deepened with concrete reading guides. 427 offline tests green across twelve suites, zero dependencies. Star on GitHub or bookmark the SkillHub page if you find it useful.","fileCount":31,"zipByteSize":150229},{"version":"3.1.0","createdAt":"2026-10-09T16:43:58.996Z","changelog":"v3.1.0: say-it-right release. Term guards upgrade to variant groups - one group can hold more than two forms (HF / 心力衰竭 / 心衰 reported as a single row), 8 domains / 27 groups / 55 variants with --pack selection. The style profile gains a stats panel (type-token ratio, function-word ratio, sentence-length quantiles; informational - read trends, no bands, no score change), exposed via stylecheck --json. detect/compare/pipeline accept a shorter --ci gate alias (same as --exit-verdict). SKILL.md adds a plain-language phrase table ('how to ask for this'), a before-to-after capability table, and a one-line routing rule - you know when to use this tool, how to phrase the ask, and exactly what it will change without reading everything first. 360 offline tests green across eleven suites, zero dependencies. Star on GitHub or bookmark the SkillHub page if you find it useful.","fileCount":30,"zipByteSize":143866},{"version":"3.0.0","createdAt":"2026-10-08T18:32:21.018Z","changelog":"v3.0.0: demand-word repositioning + operational deep-rewrite. displayName updated to match what you actually search for. PDF direct-read recalibrated: embedded-font (ToUnicode) PDFs are no longer blanket-rejected - extraction is attempted with confidence capped at Medium plus a spot-check note, while CJK CID files are still caught by the garbage probes with export guidance; a 200-file real-world calibration table ships in references/pdf_confidence.md. plan.py --handoff emits a per-sentence operation sheet (original sentence + directive + guard rules + acceptance commands) and a new references/deep_rewrite_guide.md defines the five-step rewrite loop. Term guards expand to 8 medical domains / 28 pairs with --pack selection and nesting-safety validation. 322 offline tests green across ten suites, zero dependencies. Star on GitHub or bookmark the SkillHub page if you find it useful.","fileCount":30,"zipByteSize":139975},{"version":"2.9.0","createdAt":"2026-10-08T04:47:00.767Z","changelog":"v2.9.0: substantive release. NEW fullwidth alnum normalization (transform/pipeline automatic): Chinese input methods silently turn 2025 into fullwidth 2025 - the v2.8.0 E_NUM_WIDTH red line catches it, and now transform fixes it in one step with a --track audit trail (fullwidth punctuation untouched; only letters and digits). Batch mode now accepts .pdf files mixed with text formats, annotating each with the v2.8.0 extraction confidence. SKILL guide gained a bilingual reading map routing each need to the right document. 137+20+25+21+11+16+13+23+9 offline tests green across nine suites, zero dependencies. Star on GitHub or bookmark the SkillHub page if you find it useful.","fileCount":28,"zipByteSize":132196},{"version":"2.8.0","createdAt":"2026-10-07T04:01:05.860Z","changelog":"v2.8.0: substantive release, targeting the official evaluation's accuracy note head-on. NEW PDF extraction confidence self-report (read_text_ex): four heuristics - common-word hit rate (71-word academic probe set), control-character rate, average word length, extractable word count - combined into a three-band rating that detect and pipeline annotate on every PDF scan, turning 'review the output' into 'the tool tells you how trustworthy this extraction is', with cause-specific advice (split words / likely non-English text / too few words). Trigger-word variants expanded (academic rewriting / passage rewrite / expression polish). Guard repair: the language iron-law test was silently neutered by markdown table separators splitting the scanned text - rewritten to strip only the frontmatter and scan the full body. Low-band notes now explain their trigger cause instead of misdiagnosing tables as scans. 137+20+25+21+11+16+13+11 offline tests green across eight suites, zero dependencies. Plus five fixes from a 245-file real-corpus test by a sibling agent: a chunked-scan sentence-count crash, a fullwidth-form tampering blind spot (fullwidth 2025 passed silently as 2025 - now the E_NUM_WIDTH red line), a user-guard pathway for chatbot-category false positives, a W_SENT_ADDED warning for inserted sentences, and measured honesty-boundary data (98% of fluent ChatGPT texts score below 28 - a low score never means 'no AI involved'). NEW statistical-channel experiment settled (373 files measured): sentence-length band concentration is the strongest single statistical signal (AI corpora 0.68/0.72 vs human 0.48/0.47), integrated conservatively as an informational 'uniform rhythm flag' - 41% of 2023-era AI corpus flagged at a 3% human flag rate; it never alters scores. Star on GitHub or bookmark the SkillHub page if you find it useful.","fileCount":28,"zipByteSize":130958},{"version":"2.7.0","createdAt":"2026-10-06T05:06:14.758Z","changelog":"v2.7.0: substantive release. NEW best-practices handbook (references/best_practices.md): seven real scenarios - journal submission, thesis chapters, reviewer responses, batch triage, CI gates, false-positive handling, CN punctuation - each with the standard command sequence and scenario-specific pitfalls. NEW stylecheck --html: the style profile and its --compare delta as a self-contained visual report. NEW pipeline --terms auto: generates a term-list draft on the fly (extract_terms logic) so the integrity guard works out of the box, with an explicit unreviewed-draft warning and a terms_note field in JSON. Bug fix found outside review: extract_terms' word-boundary regexes failed on CJK-adjacent abbreviations (IRAK4 in IRAK4抑制剂 was unextractable - same family as the verify.py v2.1.0 fix), now unified on CJK-safe lookarounds. Description gained an idempotent Trigger on routing block for agent installers. 137+20+25+21+11+16+13 offline tests green across seven suites, zero dependencies. 觉得有用的话，欢迎 Star（GitHub）或收藏（SkillHub 技能页）。","fileCount":28,"zipByteSize":126034},{"version":"2.6.0","createdAt":"2026-10-05T04:15:52.975Z","changelog":"v2.6.0: substantive release. NEW style profile (stylecheck.py): the quantified acceptance lens for the style guide - per-paragraph jargon hits located with samples, sentence-rhythm CV, opener diversity, each banded (natural/observe/machine-flavored) with guide anchors, thresholds calibrated on four local corpora (AI corpora 17-37 jargon hits per 1000 chars vs zero for human-written). NEW --compare mode: a before/after delta table turns deep-revision acceptance from gut feeling into metrics. NEW pattern audit backstop (audit_patterns): all 158 regexes checked for unbounded greedy quantifiers - the catastrophic-backtracking safety net, wired into the release-chain version check. Review-hardened: the sent_cv direction inversion caught in review (human English corpus was mis-banded) is fixed with four-metric directional regression assertions. Plus agent-protocol routing for the new tool and bilingual flag cheat sheets. 137+20+25+21+11+16 offline tests green across six suites, zero dependencies.","fileCount":26,"zipByteSize":118979},{"version":"2.5.0","createdAt":"2026-10-03T19:24:31.496Z","changelog":"v2.5.0: substantive release. NEW centralized error layer: all nine CLIs enter through one handler - user-facing failures print two Chinese lines (what went wrong + what to do) and exit 2 cleanly, while semantic exit codes pass through untouched. NEW batch second-pass retry: files that fail the first scan are automatically re-scanned with a doubled time budget (transient faults recover), with a per-file retried field in JSON and honest 'retried once' markers. NEW --step-timeout (default 120s) bounding every cleanup and scan stage, plus a timings block (cleanup/scan/verify) in the JSON report and a human-readable timing line. Engineering hardening: batch gates are now fail-closed (unscannable files never pass the verdict gate), all error messages localized. 137+20+25+21+11 offline tests green across five suites, zero dependencies.","fileCount":25,"zipByteSize":112577}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17dagtwyk21qs6vpz98bzcrh1853t29:paper-rewriter","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17dagtwyk21qs6vpz98bzcrh1853t29:paper-rewriter` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/docsor1212/paper-rewriter before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-14T18:12:30.419Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-docsor1212-paper-rewriter/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T00:10:38.246Z","emptyReason":null},"readme":"Skill: Pkg Paper Rewriter Claw\n\nOwner: docsor1212\n\nSummary: Academic writing style toolkit, bilingual CN/EN: AI flavor scan and style-pattern self-check reports (scan reports are detection only), deterministic text cleanup (model artifacts, punctuation, filler phrases), integrity guardrails (numbers, DOIs, PMIDs, terminology must survive untouched), and agent-guided style naturalization for clearer, more natural academic prose (de-templating, de-translationese, rhythm, concreteness). Built for scholars whose formal writing reads stiff, templated or machine-flavored — especially non-native (ESL) authors. Includes AIGC-disclosure compliance checks (China 2025-09 labeling rules) and academic-integrity guardrails: this tool improves writing quality for self-review; it does not help misrepresent authorship, conceal required AI disclosure, or defeat integrity review. 100% local, zero upload, Python stdlib only. Related: paper-polisher-pro (broad polishing), pubmed-verifier, cite-holmes, academic-figures, cn-med-oa, doc-holmes.\n\nTags: latest:3.2.0\n\nVersion history:\n\nv3.2.0 | 2026-10-10T17:16:21.686Z | user\n\nv3.2.0: statistical consistency guard. New check_stats.py catches three classes of numbers that fight each other: percent lists not summing to 100 (only sentences with partition cues like respectively - legitimate non-exhaustive lists such as comorbidity shares are never flagged), the same group appearing with two different n (time-point variants like final n are kept distinct - attrition is legitimate), and mixed p/P notation style (advisory only - journal conventions differ). Exit codes match check_terms so it drops straight into CI; JSON and markdown report outputs carry the original-data-first disclaimer. Also: expanded English trigger phrases and four FAQ answers deepened with concrete reading guides. 427 offline tests green across twelve suites, zero dependencies. Star on GitHub or bookmark the SkillHub page if you find it useful.\n\nv3.1.0 | 2026-10-09T16:43:58.996Z | user\n\nv3.1.0: say-it-right release. Term guards upgrade to variant groups - one group can hold more than two forms (HF / 心力衰竭 / 心衰 reported as a single row), 8 domains / 27 groups / 55 variants with --pack selection. The style profile gains a stats panel (type-token ratio, function-word ratio, sentence-length quantiles; informational - read trends, no bands, no score change), exposed via stylecheck --json. detect/compare/pipeline accept a shorter --ci gate alias (same as --exit-verdict). SKILL.md adds a plain-language phrase table ('how to ask for this'), a before-to-after capability table, and a one-line routing rule - you know when to use this tool, how to phrase the ask, and exactly what it will change without reading everything first. 360 offline tests green across eleven suites, zero dependencies. Star on GitHub or bookmark the SkillHub page if you find it useful.\n\nv3.0.0 | 2026-10-08T18:32:21.018Z | user\n\nv3.0.0: demand-word repositioning + operational deep-rewrite. displayName updated to match what you actually search for. PDF direct-read recalibrated: embedded-font (ToUnicode) PDFs are no longer blanket-rejected - extraction is attempted with confidence capped at Medium plus a spot-check note, while CJK CID files are still caught by the garbage probes with export guidance; a 200-file real-world calibration table ships in references/pdf_confidence.md. plan.py --handoff emits a per-sentence operation sheet (original sentence + directive + guard rules + acceptance commands) and a new references/deep_rewrite_guide.md defines the five-step rewrite loop. Term guards expand to 8 medical domains / 28 pairs with --pack selection and nesting-safety validation. 322 offline tests green across ten suites, zero dependencies. Star on GitHub or bookmark the SkillHub page if you find it useful.\n\nv2.9.0 | 2026-10-08T04:47:00.767Z | user\n\nv2.9.0: substantive release. NEW fullwidth alnum normalization (transform/pipeline automatic): Chinese input methods silently turn 2025 into fullwidth 2025 - the v2.8.0 E_NUM_WIDTH red line catches it, and now transform fixes it in one step with a --track audit trail (fullwidth punctuation untouched; only letters and digits). Batch mode now accepts .pdf files mixed with text formats, annotating each with the v2.8.0 extraction confidence. SKILL guide gained a bilingual reading map routing each need to the right document. 137+20+25+21+11+16+13+23+9 offline tests green across nine suites, zero dependencies. Star on GitHub or bookmark the SkillHub page if you find it useful.\n\nv2.8.0 | 2026-10-07T04:01:05.860Z | user\n\nv2.8.0: substantive release, targeting the official evaluation's accuracy note head-on. NEW PDF extraction confidence self-report (read_text_ex): four heuristics - common-word hit rate (71-word academic probe set), control-character rate, average word length, extractable word count - combined into a three-band rating that detect and pipeline annotate on every PDF scan, turning 'review the output' into 'the tool tells you how trustworthy this extraction is', with cause-specific advice (split words / likely non-English text / too few words). Trigger-word variants expanded (academic rewriting / passage rewrite / expression polish). Guard repair: the language iron-law test was silently neutered by markdown table separators splitting the scanned text - rewritten to strip only the frontmatter and scan the full body. Low-band notes now explain their trigger cause instead of misdiagnosing tables as scans. 137+20+25+21+11+16+13+11 offline tests green across eight suites, zero dependencies. Plus five fixes from a 245-file real-corpus test by a sibling agent: a chunked-scan sentence-count crash, a fullwidth-form tampering blind spot (fullwidth 2025 passed silently as 2025 - now the E_NUM_WIDTH red line), a user-guard pathway for chatbot-category false positives, a W_SENT_ADDED warning for inserted sentences, and measured honesty-boundary data (98% of fluent ChatGPT texts score below 28 - a low score never means 'no AI involved'). NEW statistical-channel experiment settled (373 files measured): sentence-length band concentration is the strongest single statistical signal (AI corpora 0.68/0.72 vs human 0.48/0.47), integrated conservatively as an informational 'uniform rhythm flag' - 41% of 2023-era AI corpus flagged at a 3% human flag rate; it never alters scores. Star on GitHub or bookmark the SkillHub page if you find it useful.\n\nv2.7.0 | 2026-10-06T05:06:14.758Z | user\n\nv2.7.0: substantive release. NEW best-practices handbook (references/best_practices.md): seven real scenarios - journal submission, thesis chapters, reviewer responses, batch triage, CI gates, false-positive handling, CN punctuation - each with the standard command sequence and scenario-specific pitfalls. NEW stylecheck --html: the style profile and its --compare delta as a self-contained visual report. NEW pipeline --terms auto: generates a term-list draft on the fly (extract_terms logic) so the integrity guard works out of the box, with an explicit unreviewed-draft warning and a terms_note field in JSON. Bug fix found outside review: extract_terms' word-boundary regexes failed on CJK-adjacent abbreviations (IRAK4 in IRAK4抑制剂 was unextractable - same family as the verify.py v2.1.0 fix), now unified on CJK-safe lookarounds. Description gained an idempotent Trigger on routing block for agent installers. 137+20+25+21+11+16+13 offline tests green across seven suites, zero dependencies. 觉得有用的话，欢迎 Star（GitHub）或收藏（SkillHub 技能页）。\n\nv2.6.0 | 2026-10-05T04:15:52.975Z | user\n\nv2.6.0: substantive release. NEW style profile (stylecheck.py): the quantified acceptance lens for the style guide - per-paragraph jargon hits located with samples, sentence-rhythm CV, opener diversity, each banded (natural/observe/machine-flavored) with guide anchors, thresholds calibrated on four local corpora (AI corpora 17-37 jargon hits per 1000 chars vs zero for human-written). NEW --compare mode: a before/after delta table turns deep-revision acceptance from gut feeling into metrics. NEW pattern audit backstop (audit_patterns): all 158 regexes checked for unbounded greedy quantifiers - the catastrophic-backtracking safety net, wired into the release-chain version check. Review-hardened: the sent_cv direction inversion caught in review (human English corpus was mis-banded) is fixed with four-metric directional regression assertions. Plus agent-protocol routing for the new tool and bilingual flag cheat sheets. 137+20+25+21+11+16 offline tests green across six suites, zero dependencies.\n\nv2.5.0 | 2026-10-03T19:24:31.496Z | user\n\nv2.5.0: substantive release. NEW centralized error layer: all nine CLIs enter through one handler - user-facing failures print two Chinese lines (what went wrong + what to do) and exit 2 cleanly, while semantic exit codes pass through untouched. NEW batch second-pass retry: files that fail the first scan are automatically re-scanned with a doubled time budget (transient faults recover), with a per-file retried field in JSON and honest 'retried once' markers. NEW --step-timeout (default 120s) bounding every cleanup and scan stage, plus a timings block (cleanup/scan/verify) in the JSON report and a human-readable timing line. Engineering hardening: batch gates are now fail-closed (unscannable files never pass the verdict gate), all error messages localized. 137+20+25+21+11 offline tests green across five suites, zero dependencies.\n\nv2.4.0 | 2026-10-02T18:25:46.502Z | user\n\nv2.4.0: substantive release. NEW deterministic deep polish (--deep on transform/pipeline): sentence-level automatic transforms - canned opener deletion at sentence starts only, exclusion-connector merging (not-only-X-but-also-Y becomes plain X and Y) - zero-information-loss by design, every operation logged to --track, guarded by verify's whole-document integrity check. NEW handling-hints engine: 1-4 concrete next-step suggestions (plan.py queue, guard fixing, --profile general for non-academic text) in the report tail and JSON hints field. NEW scan wall-clock budget (120s default): pathological inputs now fail cleanly with exit 2 and a split-file suggestion instead of hanging. Plus engineering hardening: timeout errors exit 2 on all main paths, dead flags removed. 137+20+25+21 offline tests green across four suites, zero dependencies.\n\nv2.3.0 | 2026-10-02T04:05:33.035Z | user\n\nv2.3.0: substantive release. NEW plan.py - sentence-level rewrite priority queue: ranks sentences by weighted pattern contribution, with section attribution, handling advice and a linear budget projection (--json for agents). NEW learn_guards.py - turn a false positive into a reusable term guard (user_guards.json, survives upgrades; context-scoped, not whole-word whitelisting). Markdown headings (## Abstract / **Methods**) now recognized by section-aware scanning. Large-text chunking gained a 2,000-char overlap window - boundary-spanning signals are no longer missed (fixes the known v2.1.x chunk-boundary limitation) with rhythm stats restored to whole-text accuracy. Section-offset drift (v1.7.0-) fixed. PDF extraction hardened: no-space operators, UTF-16BE strings, 50MB cumulative decompression cap. Plus four precision fixes (compare .md exemption, numbered/bold heading regex, reference-line exemption, 50MB guard). 137+20 offline tests green, zero dependencies.\n\nv2.2.0 | 2026-10-01T07:52:19.722Z | user\n\nv2.2.0: substantive release. NEW plan.py - sentence-level rewrite priority queue: ranks sentences by weighted pattern contribution, with section attribution, handling advice and a linear budget projection (--json for agents). NEW learn_guards.py - turn a false positive into a reusable term guard (user_guards.json, survives upgrades; context-scoped, not whole-word whitelisting). Markdown headings (## Abstract / **Methods**) now recognized by section-aware scanning. Large-text chunking gained a 2,000-char overlap window - boundary-spanning signals are no longer missed (fixes the known v2.1.x chunk-boundary limitation) with rhythm stats restored to whole-text accuracy. Section-offset drift (v1.7.0-) fixed. PDF extraction hardened: no-space operators, UTF-16BE strings, 50MB cumulative decompression cap. Plus four precision fixes (compare .md exemption, numbered/bold heading regex, reference-line exemption, 50MB guard). 137+20 offline tests green, zero dependencies.\n\nv2.1.1 | 2026-09-30T10:31:10.741Z | user\n\nv2.1.0: fixes from real-document testing - word boundary correction so abbreviations adjacent to CJK characters are correctly recognized by the integrity guard (TNF after fullwidth punctuation deletion no longer false-positive); ==highlight== syntax added to markdown detection; document-level template opening pattern (article aims to / this review will...); pipeline --track/--rewrite combination hints; --structure --suggestions compatibility notice. Validated with real 8.5KB and 80KB Chinese medical review .md files through the full pipeline. 131 offline tests green, zero dependencies.\n\nv2.1.0 | 2026-09-30T08:32:40.468Z | user\n\nv2.1.0: fixes from real-document testing - word boundary correction so abbreviations adjacent to CJK characters are correctly recognized by the integrity guard (TNF after fullwidth punctuation deletion no longer false-positive); ==highlight== syntax added to markdown detection; document-level template opening pattern (article aims to / this review will...); pipeline --track/--rewrite combination hints; --structure --suggestions compatibility notice. Validated with real 8.5KB and 80KB Chinese medical review .md files through the full pipeline. 131 offline tests green, zero dependencies.\n\nv1.9.0 | 2026-09-30T03:54:54.197Z | user\n\nv1.9.0: terminology consistency checker (scripts/check_terms.py) - detects the same concept referred to by different terms within a document; built-in CN/EN pairs + user-defined pairs; markdown consistency report; extract_terms auto-denoising (removes single-char, numeric, and substring candidates to reduce manual review); --init generates .paperrewriter.toml for persistent project config. Same-version sync with SkillHub. 131+ offline tests green, zero dependencies, no external assets.\n\nv1.8.0 | 2026-09-29T06:50:45.825Z | user\n\nv1.8.0: --review mode generating a structured markdown review document (section-by-section analysis, priority-ranked suggestions, integrity verdict, compliance reminders - deliverable to authors or advisors); stable error codes across all --json outputs (E_NUM_LOST, E_CMP_FLIP, ...); read_text retry with backoff; errors.md full code-to-remedy mapping. Same-version sync with SkillHub. 131+ offline tests green, zero dependencies, no external assets.\n\nv1.7.0 | 2026-09-28T06:34:46.376Z | user\n\nv1.7.0: structure-aware scanning via --structure (detects IMRaD sections - abstract/introduction/methods/results/discussion/conclusion/references, bilingual; per-section scoring with methods/results downweighted as genre convention; missing-section hints); fully automatic chunked scanning at any file size (5MB rejection line removed, constant memory); stable error codes in verify --json output (E_NUM_LOST, E_CMP_FLIP, ...); style-guide prohibitions now include concrete alternatives. Same-version sync with the SkillHub pages. 131 offline tests green, zero dependencies, no external assets.\n\nv1.6.0 | 2026-09-27T14:02:27.586Z | user\n\nv1.6.0: revision tracking via --track (every mechanical-layer change recorded to base.md+base.json: rules, counts, deleted sentences, flagged-for-review); experimental PDF text input (stdlib-only FlateDecode + text-operator walk; encrypted/scanned/CJK-embedded fonts explicitly rejected with guidance - no false promises); centralized common-mistakes reference (references/pitfalls.md, 20 items); TL;DR quick-start card on the main page; chunk thresholds quantified (800K/chunk, 5MB cap). Same-version sync with the SkillHub pages. 123 offline tests green, zero dependencies, no external assets.\n\nv1.5.0 | 2026-09-26T09:18:46.962Z | user\n\nv1.5.0: self-contained HTML reports via --html in detect/pipeline/compare (score cards, category tables, revision worksheet, integrity verdict); sentence-level add/delete diff view in compare for human review; batch mode --batch to scan a whole directory (per-file scores / per-file cleanup+integrity CSV); docs updated. Same-version sync with the SkillHub pages. 115 offline tests green, zero dependencies, no external assets.\n\nv1.4.0 | 2026-09-25T11:00:21.441Z | user\n\nv1.4.0: added Permissions & environment statement section (reads only user-specified input files, writes only -o output paths, zero network, zero third-party dependencies, no env vars); added --profile general mode for non-academic text (downweights formal-boilerplate signals to reduce false positives; default academic unchanged); input robustness guards (binary-file detection, UTF-8 BOM stripping, 5MB cap with actionable split guidance); aggressive-mode warning embedded in reports; FAQ additions on long-term writing-quality rationale and profile guidance. 90 offline tests green, zero dependencies.\n\nv1.3.0 | 2026-09-24T12:04:27.220Z | user\n\nv1.3.0: added Permissions & environment statement section (reads only user-specified input files, writes only -o output paths, zero network, zero third-party dependencies, no env vars); added --profile general mode for non-academic text (downweights formal-boilerplate signals to reduce false positives; default academic unchanged); input robustness guards (binary-file detection, UTF-8 BOM stripping, 5MB cap with actionable split guidance); aggressive-mode warning embedded in reports; FAQ additions on long-term writing-quality rationale and profile guidance. 90 offline tests green, zero dependencies.\n\nv1.2.0 | 2026-09-23T10:20:12.035Z | user\n\nv1.2.0: added Permissions & environment statement section (reads only user-specified input files, writes only -o output paths, zero network, zero third-party dependencies, no env vars); added --profile general mode for non-academic text (downweights formal-boilerplate signals to reduce false positives; default academic unchanged); input robustness guards (binary-file detection, UTF-8 BOM stripping, 5MB cap with actionable split guidance); aggressive-mode warning embedded in reports; FAQ additions on long-term writing-quality rationale and profile guidance. 90 offline tests green, zero dependencies.\n\nArchive index:\n\nArchive v3.2.0: 31 files, 150229 bytes\n\nFiles: README.md (1862b), references/api.md (6655b), references/best_practices.md (6561b), references/compliance.md (4157b), references/deep_rewrite_guide.md (3020b), references/errors.md (5965b), references/examples.md (13765b), references/faq.md (9728b), references/pdf_confidence.md (3897b), references/pitfalls.md (4376b), references/style_guide_en.md (5937b), references/style_guide_zh.md (6381b), scripts/_sections_block.py (2163b), scripts/check_stats.py (10767b), scripts/check_terms.py (9413b), scripts/compare.py (6881b), scripts/detect.py (17982b), scripts/extract_terms.py (6291b), scripts/hxt_core.py (67336b), scripts/learn_guards.py (9281b), scripts/patterns_en.json (20203b), scripts/patterns_zh.json (15667b), scripts/pipeline.py (19846b), scripts/plan.py (14715b), scripts/reporter.py (20247b), scripts/stylecheck.py (8019b), scripts/transform.py (14253b), scripts/verify.py (13768b), skill-card.md (2161b), SKILL.md (26735b), _meta.json (133b)\n\nFile v3.2.0:SKILL.md\n\n---\nname: paper-rewriter\ndescription: >\n Academic writing style toolkit, bilingual CN/EN: AI flavor scan and style-pattern\n self-check reports (scan reports are detection only), deterministic text cleanup\n (model artifacts, punctuation, filler phrases), integrity\n guardrails (numbers, DOIs, PMIDs, terminology must survive untouched), and\n agent-guided style naturalization for clearer, more natural academic prose\n (de-templating, de-translationese, rhythm, concreteness). Built for scholars whose\n formal writing reads stiff, templated or machine-flavored — especially non-native\n (ESL) authors. Includes AIGC-disclosure compliance checks (China 2025-09 labeling\n rules) and academic-integrity guardrails: this tool improves writing quality for\n self-review; it does not help misrepresent authorship, conceal required AI\n disclosure, or defeat integrity review. 100% local, zero upload, Python stdlib\n only. Related: paper-polisher-pro (broad polishing), pubmed-verifier, cite-holmes,\n academic-figures, cn-med-oa, doc-holmes.\nallowed-tools:\n - Read\n - Write\n - Bash\n - Glob\n - Grep\n---\n\n# Academic Style Toolkit (paper-rewriter)\n\nBilingual (CN/EN) style naturalization for academic & medical writing: find stiff,\ntemplated or machine-flavored patterns, clean mechanical debris, revise for clarity\nand natural register — with integrity guardrails on every step.\n\n> **Routing in one line**: grammar/fluency/journal-format polish → use a polisher\n> (paper-polisher-pro); de-templating, model-residue cleanup, AI-flavor style\n> self-check and rewriting → this tool. Need both? Polish first, then run this pipeline.\n\n## Feature status (v3.2.0)\n\n| Feature | Status | Since |\n|---|---|---|\n| detect / transform / verify / compare / pipeline | Stable | v1.0 |\n| Section-aware scanning (`--structure`) | Stable | v1.7 |\n| `.docx` direct input; 50MB file guard; read retry | Stable | v1.3–1.8 |\n| Sentence-level rewrite plan (`plan.py`) | Stable | v2.2 |\n| User-learned term guards (`learn_guards.py`) | Stable | v2.2 |\n| `--exit-verdict` machine exit codes (detect/compare/pipeline) | Stable | v2.3 |\n| Deterministic deep polish (`--deep`), handling hints, scan time budget | Stable | v2.4 |\n| Centralized error layer (`CliError` + handling hints), batch retry, per-step timeout | Stable | v2.5 |\n| Scale envelope: 800K-char chunks (2K overlap) · 50MB file cap · 120s step budget | — | — |\n| Style profile (`stylecheck.py`: per-paragraph quantified guide audit) | Stable | v2.6 |\n| Best-practices handbook (7 real scenarios), stylecheck `--html`, `--terms auto` | Stable | v2.7 |\n| PDF extraction confidence self-report (`read_text_ex`, detect/pipeline annotation) — calibrated on 200 real-world PDFs, see `references/pdf_confidence.md` | Experimental | v2.8 |\n| Term guard variant groups (`check_terms --pack cardiovascular` — 8 domains, 27 groups / 55 variants, groups may hold >2 forms e.g. HF/心力衰竭/心衰; nesting-safe) | Stable | v3.0 / v3.1 |\n| Stats panel in style profile (`stylecheck --json` → `stats`: TTR / function-word ratio / sentence-length quantiles; informational, no bands) | Stable | v3.1 |\n| `--ci` gate alias on detect/compare/pipeline (same as `--exit-verdict`) | Stable | v3.1 |\n| Statistical consistency guard (`check_stats.py`: percent-list sums with partition cues only / per-group n conflicts / p-vs-P style mix — precision-first, under-reports rather than false-positives) | Stable | v3.2 |\n| Deep-rewrite handoff block (`plan.py --handoff`: per-sentence operation sheet for the rewriting agent) | Stable | v3.0 |\n| Batch accepts `.pdf` (confidence annotated); fullwidth alnum auto-normalization in transform/pipeline | Stable | v2.9 |\n| HTML reports, `--batch`, `--track` audit trail | Stable | v1.5–1.6 |\n| PDF text extraction (text PDFs; v3.0.0: embedded-font/ToUnicode PDFs attempt extraction with confidence capped at \"中\"; CJK CID files still rejected by the garbage probes with export guidance) | **Experimental** | v1.6 |\n\nAnything marked **Experimental** can reject valid files or need manual review of\nits output — export to UTF-8 text when in doubt. Everything else is\nregression-tested offline on every release.\n\n## Integrity guardrails — read first\n\n- **Permitted**: polishing your own drafts; aligning AI-assisted text with your\n voice where your school/journal **allows or requires disclosed** AI assistance;\n cleaning model residue (stray `oaicite`/`[cite:]` tokens) from legitimately\n disclosed drafts; improving clarity, rhythm and concreteness of formal prose.\n- **Not permitted**: using this toolkit to misrepresent authorship, to conceal AI\n use where disclosure is required, or to defeat academic-integrity review. If a\n request is framed that way (\"rewrite it so the review can't tell\"), refuse the\n framing, explain the disclosure obligation, and offer the legitimate\n quality-editing path instead. Agents running this skill are expected to enforce\n this line.\n- **This tool never changes data**: numbers, p-values, confidence intervals, DOIs,\n PMIDs, years and terminology are guarded by `verify.py` (see below). Improved\n prose must never cost a fact.\n- Compliance: China's AIGC labeling rules (effective 2025-09-01), journal disclosure\n policies and arXiv policies are summarized in `references/compliance.md` — the\n obligation to disclose belongs to the author, not the tool.\n\n## Division of labor\n\n| Layer | Who does it | What |\n|---|---|---|\n| Style self-check | `scripts/detect.py` | Heuristic style-pattern report (templated phrasing, uniform rhythm, boilerplate) for author self-review |\n| Mechanical cleanup | `scripts/transform.py` | Model artifacts, chatbot filler, punctuation normalization, safe filler swaps — grammar-safe only. **When to use directly**: you only need residue/filler cleanup without any stylistic diagnosis (fast, deterministic). |\n| **Quality revision** | **you (the agent)** | Follow `references/style_guide_zh.md` / `_en.md`: de-templating, rhythm, concreteness, stance |\n| Integrity guard | `scripts/verify.py` | Numbers/DOIs/PMIDs/years/abbreviations/terms must survive untouched |\n| Before/after | `scripts/compare.py` | Pattern-score delta + integrity verdict |\n\n**What it can actually change (before → after)** — the capability promise at\nexample granularity:\n\n| Changeable | Example | Done by |\n|---|---|---|\n| Ritual openers/closers | 「众所周知，…」 → straight to the point | transform `--deep` + agent |\n| Ballot-style frames | 「不仅X，而且Y」 → 「X，且Y」 | transform `--deep` |\n| Model residue | oaicite / turn0search / [cite: 1] tokens removed wholesale | transform |\n| Punctuation & fullwidth digits | half-width → full-width (decimal-safe); ２０２５→2025 | transform |\n| Jargon / translationese | 「进行…的研究」 → 「研究」 | agent (style guide) |\n| Rhythm | long-sentence runs → varied lengths; repeated openers → varied | agent + stylecheck |\n| Concreteness | vague appraisal → grounded statement (**never invents data**) | agent (guards flag invented numbers as W_NUM_ADDED warning — human removes them) |\n| Term consistency | HF/心力衰竭/心衰 mixed → unified to dominant form | `check_terms.py` groups |\n| Numeric self-consistency | percent lists not summing to 100 (partition-cued sentences) / same group with different n / p vs P style mix | `check_stats.py` |\n| Never changed | numbers, p-values, CIs, DOIs, PMIDs, years, terms, quoted content | verify.py blocks |\n\n## Quick start\n\n**How to ask for this in plain words** (EN digest of the full phrase table in\nSKILL_ZH.md): \"remove the AI flavor from this paper\" / \"this reads too templated\" /\n\"clean up oaicite and [cite:] residue\" / \"tell me which sentences to fix first\" /\n\"check my rewrite broke no numbers\" / \"give me a style profile\" / \"stop flagging\nthis legitimate term\" — each maps to the pipeline, `plan.py`, `transform.py`,\n`verify.py`+`compare.py`, `stylecheck.py` and `learn_guards.py` respectively.\n\n**Reading map** (this file is the hub; details live one click away):\nfirst time → Quick start + The workflow below · troubleshooting →\n`references/pitfalls.md` + `references/errors.md` · CI/agent integration →\nAutomation section · capability limits → Honest boundaries · scenario how-tos →\n`references/best_practices.md` · deep-rewrite process →\n`references/deep_rewrite_guide.md` · PDF confidence tiers →\n`references/pdf_confidence.md` · programmatic use → `references/api.md`.\n\nNo agent is required — every capability below runs directly in a terminal.\nEvery script has built-in `--help` (full flag reference) and `--version`;\nquick flag semantics:\n\n| Flag | Meaning |\n|---|---|\n| `--profile general` | non-academic text: down-weight formulaic/boilerplate signals |\n| `--deep` | deterministic sentence-level transforms (canned openers, not-only merge) |\n| `--exit-verdict` | machine exit codes for CI/agent gating (see below) |\n| `--structure` | section-aware scoring (IMRaD) |\n| `--step-timeout SEC` | per-step wall-clock budget (default 120) |\n| `--terms FILE` | term list for the integrity guard (build via extract_terms.py) |\n\nOne command (self-check → cleanup → revision brief → integrity guard):\n\n```bash\npython scripts/pipeline.py draft.txt -o out.txt --terms terms.txt\n```\n\nVisualization & batch (v1.5.0): add `--html report.html` to any of\ndetect/pipeline/compare for a self-contained HTML report (score cards, category\ntables, revision worksheet, integrity verdict; compare adds sentence-level\nadd/delete diff). Scan a whole directory with `--batch dir` (detect: per-file\nscore summary; pipeline: per-file cleanup+integrity CSV).\n\n**Structure-aware scanning** (`detect --structure`, v1.7.0): detects paper\nsections (abstract/introduction/methods/results/discussion/conclusion/\nreferences, bilingual) and scores each separately. Methods/results weights\nnormalize the aggregate only — raw per-section scores are always reported in\nfull; the fixed phrasing of a Methods section is genre convention, not a\nmachine signal. Missing-section hints included. Markdown headings are\nrecognized since v2.2.0 (`## 摘要`, `**方法**`, numbered `2. Methods`).\n\n**Sentence-level rewrite plan** (`plan.py`, v2.2.0): ranks sentences by their\nweighted pattern contribution and produces a P0 rewrite queue with section\nattribution, per-sentence category hits, handling advice and a linear budget\nprojection (fix the top-K offenders → projected score). `--json` for agent\nconsumption. The projection is a local approximation for prioritization — not a\npromise, and not any external detector's score.\n\nPreparing the term list: `python scripts/extract_terms.py draft.txt -o terms.txt`\nauto-extracts candidates (abbreviations, quoted terms) into a draft you confirm\nby hand. Input formats: `.txt`/`.md` directly, **`.docx` (Word) directly** since\nv1.3.0; PDF direct-read is **experimental** (text PDFs; confidence self-report —\na \"低\" tier means garbled extraction, export to UTF-8 text instead; see\n`references/pdf_confidence.md`). Ask for a\nrevision worksheet alongside any run with `--suggestions path.md` (detect.py and\npipeline.py both support it): category, sample, suggested handling and the guide\nsection to read — the tool proposes, you and the guide decide.\n\nFor non-academic text (blogs, posts, office documents), add `--profile general`\nto down-weight formal-boilerplate signals; the default `academic` profile is\ncalibrated for scholarly manuscripts.\n\nOr run the steps individually (from the skill's own directory, or use absolute paths):\n\n```bash\npython scripts/detect.py draft.txt # style-pattern self-check (-j JSON, -s score only)\npython scripts/transform.py draft.txt -o step1.txt\n# ... agent quality revision of step1.txt per the style guide ...\npython scripts/verify.py draft.txt step2.txt --terms terms.txt\npython scripts/compare.py draft.txt step2.txt\n```\n\nScenario-organized best practices (journal submission, thesis, revision\nletters, batch, CI gates, false-positive handling, CN punctuation):\n`references/best_practices.md`.\nWorked end-to-end examples: `references/examples.md`. Unified exit codes,\nviolation categories and remedies: `references/errors.md`. **Centralized\ncommon-mistakes list (24 items): `references/pitfalls.md`** — read it before\nyour first real run. Python API reference: `references/api.md`. FAQ:\n`references/faq.md`.\n\n**Revision tracking** (`--track base` on transform/pipeline): every change the\nmechanical layer makes is recorded to `base.md` + `base.json` — an auditable\nlist of what the tool touched (rule, count, deleted sentences,\nflagged-for-review).\n\n**PDF input (experimental, v1.6.0; confidence self-report since v2.8.0)**:\nEnglish text PDFs (FlateDecode/WinAnsi, unencrypted) are extracted with the\nstandard library only. Since v2.8.0 every PDF scan reports an extraction\nconfidence (高/中/低) computed from four heuristics — common-word hit rate,\ncontrol-character rate, average word length, extractable word count — so\n\"review the output\" becomes \"the tool tells you how trustworthy this\nextraction is\". 低 means garbled-form typical: export to UTF-8 text instead. PDFs with embedded\nfont encodings (ToUnicode CMaps, typical for CJK) are rejected when detected —\ndetection is best-effort: if one slips through, the output may be garbled, so\n**review extracted PDF text before relying on it**. When in doubt, export to\nUTF-8 text. Chunk threshold: 800,000 characters per chunk — since v2.2.0\nadjacent chunks share a 2,000-character overlap window, so patterns spanning a\nchunk boundary are captured and double-counts are reconciled (v2.1.x and\nearlier could miss boundary-spanning signals). File-size guard 50MB (scans\nauto-chunk at any size within the cap; the integrity guard is whole-document).\n\n### Agent invocation protocol\n\nWhen invoked, decide the path first, then run it:\n\n- **Trigger words**: 写作风格自查 / 论文改写润色 / 去模板腔 / 翻译腔清理 /\n 学术改写 / 段落改写 / 表达优化 / style self-check /\n style naturalization / naturalize academic writing / de-templating /\n academic rewriting / passage rewrite / expression polish /\n make my writing sound less machine-written / reduce the templated tone /\n clean up model residue or stray citation tokens / fix stiff formal prose /\n polish my draft for submission without changing the data /\n check that numbers and citation IDs survived editing → run the pipeline\n above.（中文变体触发词见 SKILL_ZH.md——CH 分寸词不入英文文件；\n 数字自洽/术语混用类请求路由到 check_stats.py / check_terms.py，见下）\n （Parameter cheat sheet lives in Quick start; exit-code tables in\n references/errors.md — both are linked from here to avoid hunting across\n sections.）\n- **Disambiguation (this tool vs a polisher)**: 「论文改写润色」 here means\n style naturalization / de-templating (removing the machine flavor from\n academic prose). Decision rule with examples —\n route to a polisher (e.g. paper-polisher-pro) when the ask is only about\n language correctness/fluency: 「帮我改下语法」「这句读不顺，润色一下」\n 「按期刊风格改写摘要」; route to this toolkit when the ask is about templated\n tone or model residue: 「这篇读起来像 AI 写的」「把套话删一删」\n 「文里有 [cite: 1] 这种残留」; when both apply, polish first, then run this\n pipeline — neither tool substitutes for the other.\n- **Term inconsistency** (abbreviation vs full form, mixed synonyms) →\n `check_terms.py file --pack `; `--list-packs` shows all eight\n domain packs (v3.0.0).\n- **Numbers that don't agree** (percent list not summing to 100, same group\n with two different n, p/P style mix) → `check_stats.py file` (v3.2.0;\n exit codes match check_terms: 0 consistent / 1 issues found).\n- **User wants to know what to fix first** → `plan.py draft.txt -o plan.md`\n (P0 sentence queue + budget projection) before deep revision.\n- **User wants quantified acceptance of a rewrite** → `stylecheck.py 原稿 改稿\n --compare` (v2.6.0 style profile delta; triggers: 风格画像 / 量化验收 /\n 深改验收 / style profile / acceptance check).\n- **A scan flags a legitimate term** (false positive) → don't edit the pattern\n files; persist a guard instead: `learn_guards.py from-text 术语 样本.txt`\n (or `add`) — the guard survives upgrades and applies to every later scan.\n- **User only wants a verdict on an existing rewrite** → `pipeline.py draft.txt\n --rewrite rewritten.txt --terms terms.txt` (skip cleanup).\n- **User asks to conceal AI use, misrepresent authorship, or defeat integrity\n review** → refuse the framing, point to `references/compliance.md`, offer the\n legitimate quality-editing path instead. Do not run the toolkit toward that end.\n- Exit codes: `verify.py` is the strict contract holder — `0` integrity PASS,\n `1` integrity FAIL (fix the rewrite, never the guard), `2` usage/file error.\n `detect/transform/compare/pipeline` report the verdict in their output and\n always exit `0` on completed runs, `2` on usage/file errors. For agent/CI\n branching, add `--exit-verdict` (v2.3.0): machine exit codes 0/3/4 on\n detect/compare, full 0/1/3/4 on pipeline — see Automation & CI integration\n below. Every script supports `--version`.\n\n## Automation & CI integration (v2.3.0)\n\nScripts are automation-first: every verdict is machine-readable, two ways.\n\n- **Default contract (human flows)**: `verify.py` alone holds exit 0/1/2\n (1 = integrity FAIL); detect/transform/compare/pipeline finish with 0 and\n put the verdict in their report. Never branch on their default exit code.\n- **Machine contract** — add `--exit-verdict` (or the shorter `--ci` alias, v3.1.0)\n to detect / compare / pipeline:\n `0` clean (low, no residue) · `3` style patterns at medium or above (needs\n deep revision) · `4` model-residue hit (run transform first) · `1`\n integrity FAIL (pipeline only — same meaning as verify's 1) · `2` usage\n error (unchanged). **pipeline is the only full 1/3/4 gate** — recommended\n CI check: `pipeline.py draft.txt --rewrite rewritten.txt --terms terms.txt\n --exit-verdict`.\n- **JSON**: `detect -j` (full scan result), `pipeline --json` (before/after,\n verify verdict, `exit_verdict` field, handling `hints`, agent brief), `compare --json`\n (delta + verify), `plan.py --json` (sentence queue + projections).\n Example gate in one line:\n `python scripts/pipeline.py orig.txt --rewrite new.txt --json --exit-verdict || echo \"blocked: $?\"`\n- Exit-code tables for both contracts: `references/errors.md` §1.\n\n## The workflow\n\n1. **Self-check**: `detect.py draft.txt` — a heuristic report of style patterns\n (canned phrases, uniform sentence rhythm, boilerplate transitions, model\n artifacts). The report is for the author's own review; the score is a local\n heuristic, not an official measurement of anything.\n2. **Mechanical cleanup**: `transform.py draft.txt -o step1.txt` — strips stray\n model artifacts (`oaicite`, `turn0search`, `[cite: 1]`, `grok_card`,\n `attached_file`), leftover chatbot pleasantries, markdown residue, and a safe\n list of filler phrases; CN halfwidth punctuation is normalized to fullwidth\n (decimals protected). `-a` adds em-dash reduction and empty-opener removal.\n `--deep` (v2.4.0) adds sentence-level deterministic transforms — canned\n opener deletion, 「不仅X，而且Y」→「X，且Y」 merging — zero-information-loss\n only, every operation logged to `--track`. Clean human-written text passes\n through byte-identical\n (except fullwidth alnum normalization, see feature status v2.9).\n3. **Quality revision** (the real work): optionally rank the work first —\n `python scripts/plan.py draft.txt -o plan.md` gives a sentence-level P0\n queue (worst offenders with section, category and advice) so deep effort\n lands where the score lives; add `--handoff` to emit a per-sentence\n operation sheet (original sentence + directive + guard rules + acceptance\n commands) that a rewriting agent can follow verbatim (v3.0.0).\n Then read the guide for the text's language —\n - CN: `references/style_guide_zh.md` — structural de-templating → jargon\n cleanup → rhythm → concreteness → stance → integrity red lines\n - EN: `references/style_guide_en.md` — smaller words → fewer significance\n frames → plain clauses instead of parallelism → rhythm → real attribution →\n commit to a position\n - Revise section by section. Preserve all facts, numbers, citations, terminology.\n3b. **Quantified acceptance** (`stylecheck.py`, v2.6.0): per-paragraph style\n profile — jargon hits located to the paragraph, sentence-rhythm CV, opener\n diversity, each banded 自然/观察/偏机器 with style_guide anchors;\n `--compare 原稿 改稿` shows the delta so deep-revision acceptance is\n metric-based. Bands are calibration hints only — they never alter scores.\n4. **Guard**: `verify.py draft.txt step2.txt --terms terms.txt` — exit 1 means a\n number/citation/term was altered: fix the revision, not the guard. Build\n terms.txt for medical text (drug names, gene symbols — include mouse-style\n capitalized forms like Myc — and scale names), one term per line. The guard\n also warns on numbers absent from the original (fabrication defense) and\n number-context swaps (arm/direction ordering).\n For mixed synonym usage (abbreviation vs full form, e.g. HF vs\n 心力衰竭), also run `check_terms.py file --pack cardiovascular`\n (v3.0.0 domain packs; `--list-packs` shows all eight).\n5. **Re-check**: `compare.py draft.txt step2.txt` — pattern reduction + integrity\n verdict. Keep the before/after pair for your records; if your institution or\n journal requires an AI-use disclosure, state it plainly — this report is a\n quality self-check, not a substitute for disclosure.\n\n## Honest boundaries\n\n- The style score is a local heuristic on writing patterns. It is not a\n measurement produced by any external service, and it says nothing about\n authorship. Never present it as one.\n- Formal academic prose and non-native writing are routinely misjudged by\n automated reviewers; if you are the author, keep drafts, version history and\n notes — process evidence, not style scores, settles authorship questions.\n- This tool does not interact with any external review system, does not remove\n official content labels or watermarks, and does not assist concealment of\n required disclosures. See `references/compliance.md`.\n- **Detection-capability boundary (measured, 2026-10)**: on fluent LLM-generated\n text this toolkit's style channel barely fires — 128 real ChatGPT texts scored\n below 28 in 98% of cases, and 60 samples of 2026-era models scored 0 (nothing\n flagged). Style tools that do flag everything in that benchmark misfire on\n ~50% of human forum prose. **A low score here does not mean \"no AI was\n involved\"** — use this toolkit as a style self-check + integrity guard, not\n as a judge of authorship.\n- **Statistical-channel experiment (2026-10, 373 files measured)**: sentence-\n length band concentration is the strongest single statistical signal (AI\n corpora 0.68/0.72 vs human 0.48/0.47). Integrated conservatively as a\n \"uniform rhythm flag\" (≥8 sentences; band≥0.65 or cv≤0.30): 41% of 2023-era\n AI corpus flagged @ 3% human flag rate (below the FP baseline). The flag is\n informational only — regular genres (e.g. literature abstracts) trigger it\n too; it is never a detection verdict.\n- Scale envelope: regression-tested up to ~1MB text files; the scanner is linear\n (no catastrophic backtracking, bounded quantifiers only). Memory use is roughly\n 3x file size; for very long manuscripts, split by section for readable reports.\n\n## Permissions & environment statement\n\nFor reviewers, security scanners and cautious users:\n\n- Reads **only** the file paths you pass as arguments (plus stdin, including the\n `.txt`/`.md`/`.docx`/`.pdf` files inside a `--batch` directory) and its own\n bundled wordlist files (`scripts/patterns_*.json`, plus\n `scripts/user_guards.json` if you have created one with `learn_guards.py`).\n Verify it yourself:\n\n ```bash\n grep -rnE \"urllib|requests|socket|subprocess|os\\.environ\" scripts/ || echo \"clean\"\n ```\n\n (runs clean as of this release — the claim is reproducible, not rhetorical).\n- Writes **only** to output paths you pass explicitly: `-o`/`--output` on\n transform/compare/pipeline/plan/extract_terms, `--suggestions`, `--html`,\n `--review` (detect.py's markdown report), `--report` (check_terms.py), and\n `--track` (`base.md` + `base.json`). One derived exception: with\n `pipeline --terms auto`, the tool also writes the auto-generated term draft\n `.terms.auto.txt` (tool-written, unreviewed — see the\n workflow note). One tool-owned data file on top of that:\n `learn_guards.py add`/`from-text`/`remove` writes\n `scripts/user_guards.json` (your learned term guards, via a transient\n `.tmp` + atomic rename). No other writes.\n- **Zero network access** — no HTTP calls, no downloads, no API keys.\n- **Zero third-party dependencies** — Python standard library only.\n- Reads **no environment variables**; spawns **no subprocesses**; creates **no\n scheduled tasks**; the only temp file ever written is the\n `user_guards.json.tmp` rename target described above.\n- Test corpora and dev notes live in the development repo only, not in the\n distributed package.\n\n## Customizing\n\n- `scripts/patterns_zh.json` / `patterns_en.json` — pattern lists (+ rewrite\n suggestions), regex signals, term_guards (legitimate academic collocations that\n must not be flagged, e.g. \"mutational landscape\", \"pivotal trial\", CJK\n \"sequence alignment\" and \"precipitation reaction\"), auto_fixes.\n- **User-learned guards** live in `scripts/user_guards.json` (managed by\n `learn_guards.py` — do not hand-edit; `list` prints, `remove` deletes).\n Keep them there rather than editing `patterns_*.json`: pattern files are\n replaced on upgrade, your guards file is not.\n- Score calibration constants live in `scripts/hxt_core.py` (`_LANG_K`); the four\n test corpora in the development repo's `tests/` (not shipped in the package)\n document the intended separation.\n\n## Related tools\n\n- pubmed-verifier — verify PMID/DOI references before submission\n- cite-holmes — deep research with hallucination-free citations\n- paper-polisher-pro — comprehensive polishing & plagiarism reduction\n- academic-figures — publication-ready scientific figures\n- doc-holmes — layout-preserving PDF translation\n\nFile v3.2.0:README.md\n\n# paper-rewriter\n\n[![GitHub Stars](https://img.shields.io/github/stars/docsor1212/paper-rewriter?style=social&label=Star)](https://github.com/docsor1212/paper-rewriter)\n\nBilingual (CN/EN) style naturalization for academic & medical writing: find stiff,\ntemplated or machine-flavored patterns, clean mechanical debris, revise for clarity\nand natural register — with integrity guardrails on every step.\n\nDeterministic cleanup (model artifacts, punctuation, filler), style-pattern\nself-check reports (local heuristic, detection only), sentence-level rewrite\nplanning, a deterministic deep-polish mode, and a whole-document integrity guard\n(numbers, DOIs, PMIDs, terminology must survive untouched). 100% local, zero\nupload, Python standard library only.\n\n## Install / Quick Start\n\nInstall via your skill manager (skills CLI / ClawHub / SkillHub), or clone this\nrepository and run the scripts directly with Python 3 (no dependencies):\n\n```bash\n# one command: self-check -> cleanup -> revision brief -> integrity guard\npython scripts/pipeline.py draft.txt -o out.txt --terms terms.txt\n\n# or step by step\npython scripts/detect.py draft.txt # style-pattern self-check\npython scripts/transform.py draft.txt -o step1.txt\npython scripts/verify.py draft.txt step1.txt # integrity guard (exit 0/1/2)\n\n# full guide, boundaries and agent invocation protocol\ncat SKILL.md\n```\n\n**China mirror (ModelScope 魔搭)**: — if you find this skill useful, a like there helps others find it.\n\n## Integrity guardrails\n\nPermitted: polishing your own drafts; aligning AI-assisted text with your voice\nwhere disclosure is allowed or required. Not permitted: misrepresenting\nauthorship, concealing required AI disclosure, or defeating integrity review —\nthe toolkit refuses that framing. See `references/compliance.md`.\n\nFile v3.2.0:_meta.json\n\n{\n \"ownerId\": \"kn7b6sjwend7cwwmhf7mdg1wzx82dfbf\",\n \"slug\": \"paper-rewriter\",\n \"version\": \"3.2.0\",\n \"publishedAt\": 1791652581686\n}\n\nFile v3.2.0:references/api.md\n\n# API 参考（程序化集成）\n\n> 供想在 Python 内直接调用核心函数的用户/agent。所有函数纯标准库、零网络。\n> CLI 优先场景请直接用命令行（见 SKILL.md）；本文档面向需要嵌入自己管线的人。\n\n## hxt_core\n\n```python\nimport sys\nsys.path.insert(0, \"<技能目录>/scripts\")\nimport hxt_core\n```\n\n### hxt_core.scan(text, lang=None, profile=\"academic\") → dict\n\n风格特征扫描（≤1MB 文本）。\n\n- `text`：str，待扫文本（必填）\n- `lang`：`\"zh\"|\"en\"|\"mix\"|None`——None 时自动检测\n- `profile`：`\"academic\"`（默认，论文口径）| `\"general\"`（八股/公文信号 ×0.4）\n- 返回：`{\"score\": int 0-100, \"level\": \"低|中|高|极高\", \"critical_hit\": bool,\n \"lang\": str, \"profile\": str, \"units\": float, \"sentences\": int,\n \"categories\": {cat: {\"label\", \"count\", \"weight\", \"samples\", \"auto_fixable\"}},\n \"guards_applied\": [...], \"stats\": {\"burstiness_cv\", \"connector_density\", ...},\n \"suggestions\": [{\"from\", \"to\"}], \"honest_note\"}`\n\n```python\nr = hxt_core.scan(\"这个方案为业务赋能，打法清晰。\")\nprint(r[\"score\"], r[\"level\"], r[\"categories\"].get(\"zh_jargon\", {}).get(\"count\"))\n```\n\n### hxt_core.scan_chunked(text, lang=None, profile=\"academic\") → dict\n\n超大文本分块扫描（>1MB 自动启用；CLI 的 detect/pipeline 对 >1MB 输入自动走本函数）。\n返回结构同 scan，额外带 `\"chunked\": 块数`；跨块边界的结构信号可能少量漏检（报告标注）。\n\n### hxt_core.read_text(path, max_mb=50.0) → str\n\n健壮文本读取：大小上限 / 二进制 NUL 检测 / BOM 剥离 / 乱码占比守卫 / .docx 直读。\n失败抛 `ValueError`（消息含处置建议）或 `OSError`。\n\n```python\ntry:\n text = hxt_core.read_text(\"稿件.docx\")\nexcept ValueError as e:\n print(\"输入不合规:\", e)\n```\n\n### hxt_core.build_suggestions(orig, scan_result, guide) → str\n\n把 scan 结果转为修订建议工作单（markdown 字符串：类别/样本/处理原则/指南锚点）。\n`guide` 传指南相对路径（如 `references/style_guide_zh.md`）。\n\n### hxt_core.verify_integrity 相关\n\n完整性守卫的函数入口在 `verify.verify(orig, new, terms=None, max_len_change=25.0,\nmax_cjk_shift=0.12) -> {\"ok\": bool, \"violations\": [...], \"warnings\": [...], \"stats\": {...}}`\n（`import verify as vf`）。退出码契约只属于 CLI 层。\n\n## transform / extract_terms / verify（CLI 模块复用）\n\n| 函数 | 说明 |\n|---|---|\n| `transform.load_fixes(lang=None, aggressive=False)` | 返回 (rx, repl, note, guards) 修复列表 |\n| `transform.apply_auto_fixes(text, fixes)` | 应用机械修复（带术语守卫），返回 (text, applied) |\n| `transform.drop_flagged_sentences(text)` | 客套句/截止声明整句删除（覆盖律+数字保护），返回 (text, removed) |\n| `extract_terms.extract(orig, min_count=2, cap=40)` | 术语候选抽取，返回 [(term, count, kind)] |\n| `verify.load_terms(path)` | 术语表加载（BOM/守卫内建） |\n\n所有函数零网络、零环境变量、只读写调用方显式传入的路径。\n\n## plan / learn_guards（v2.2.0 新增）\n\n| 函数/入口 | 说明 |\n|---|---|\n| `hxt_core._chunk_spans(text, max_chars=800_000, overlap=2000)` | 分块切点（含重叠窗起点），scan_chunked 缝合的底层 |\n| `hxt_core.scan_chunked(text, ..., max_chars, overlap)` | 分块扫描（重叠缝合口径）；小分块参数便于测试 |\n| `hxt_core.clear_pattern_cache()` | 清词表缓存（learn_guards 写守卫后同进程生效用） |\n| `hxt_core.verdict_exit_code(score, critical_hit, verify_ok=None)` | --exit-verdict 机器退出码（0/1/3/4），detect/compare/pipeline 共用 |\n| `hxt_core.build_hints(text, r, profile)` | 处置建议引擎（v2.4.0）：critical/plan/learn_guards/--profile general 四类提示 |\n| `transform.deep_polish(text)` | 确定性深改（v2.4.0）：句首八股删除+排除式连接合并，返回 (text, ops) |\n| `hxt_core.scan(..., time_budget=120.0)` | 墙钟预算（v2.4.0）：超时抛 ValueError 带拆分建议；`SCAN_TIME_BUDGET` 为缺省常量 |\n| `hxt_core.CliError(msg, hint)` / `fail()` / `cli_entry(main)` | 集中异常层（v2.5.0）：两行中文错误+处置建议，exit 2；SystemExit 穿透 |\n| `pipeline.py --step-timeout SEC` / report `timings` | 单步墙钟预算与各步耗时（cleanup/scan/verify，v2.5.0） |\n| `transform.normalize_fullwidth_alnum(text)` | 全角字母/数字→半角（v2.9.0）：E_NUM_WIDTH 的对症修复，返回 (text, 改写数) |\n| `hxt_core.read_text_ex(path)` / `_pdf_confidence` | 带元数据读取（v2.8.0）：.pdf 返回 (text, {confidence 高/中/低, notes})；四启发指标校准见 tests/v280 |\n| `detect --batch --json` / `pipeline --batch` 的 `retried` | 批量二遍重试标记（v2.5.0）：失败文件以双倍预算重扫一次 |\n| `hxt_core.style_profile(text)` / `stylecheck.py` | 风格画像（v2.6.0）：段落级黑话定位+节奏/开场档位+指南锚点；--compare 验收差值（阈值=dev 四语料校准） |\n| `hxt_core.audit_patterns()` / `STYLE_BANDS` | 模式审计兜底（v2.6.0）：未受限贪婪量词检测；档位阈值常量 |\n| `reporter.render_style_profile/compare` / `stylecheck.py --html` | 风格画像 HTML（v2.7.0）：档位表+重点段落+对比差值 |\n| `pipeline.py --terms auto` | 自动术语草稿（v2.7.0）：extract_terms 口径 min_count=1+警告；JSON terms_note 字段 |\n| `hxt_core._load_user_guards()` | 读 `scripts/user_guards.json`（损坏降级为空并 stderr 提示） |\n| `plan.py --json / -o plan.md --top N` | 句级改写优先级计划：P0 队列+章节归属+线性预算投影 |\n| `plan.py --handoff`（v3.0.0） | 深改交接块：逐句「原句+操作指令」指令单（含守卫铁律+验收命令）；markdown 追加输出，`--json` 下为 `handoff` 键 |\n| `check_terms.py --pack <域> / --list-packs`（v3.0.0） | 术语守卫域包：八学科域 28 对按域选跑；结果带 `pack` 域标签；`hxt_core` 侧 `check_terms.validate_packs()` 嵌套安全校验（变体互斥断言） |\n| `check_stats.py --tolerance 0.3 / --json / --report`（v3.2.0） | 统计一致性守卫：percent_sum（仅划分用语句）/ group_n_conflict（前缀归一化）/ p_style_mix；退出码 0/1/2 同 check_terms |\n| `learn_guards.py add/from-text/list/remove/test` | 误报→守卫固化；语义同内置 term_guards（±30 字符窗口豁免） |\n\nplan 的逐句贡献与投影均为近似口径（同类同权线性近似）；learn_guards 只写\n`scripts/user_guards.json` 一个文件，原子替换（tmp+rename）。\n\nFile v3.2.0:references/best_practices.md\n\n# 最佳实践手册（Best Practices）——按场景组织的端到端工作法\n\n> 与 pitfalls.md（23 条错误用法）互补：这份手册按**真实场景**组织，每个场景给\n> 标准命令序列、预期输出形态、该场景特有的避坑点。所有分数与档位均为本地\n> 启发式口径，非任何外部检测分数。\n\n## 场景 1：期刊投稿前的自查（最常见）\n\n**目标**：投稿前把模板腔降下来，同时确保一个数据都没动。\n\n```bash\n# 1. 术语表先行（医学/生科稿件必做——守卫的弹药）\npython scripts/extract_terms.py manuscript.txt -o terms.txt\n# 人工过一遍 terms.txt：删掉普通词、补上缩写变体（如 Myc 与 MYC 都要）\n\n# 2. 一键管线出底稿\npython scripts/pipeline.py manuscript.txt -o clean.txt --terms terms.txt\n\n# 3. agent 深改（按 style_guide_zh/en 七步法，重点看 plan 排出的 P0 句）\npython scripts/plan.py clean.txt -o plan.md # 句级优先级队列+预算投影\n# ……按 plan.md 逐句深改，产出 revised.txt……\n\n# 4. 量化验收（改前 vs 改后画像差值）\npython scripts/stylecheck.py clean.txt revised.txt --compare\n\n# 5. 守卫+复核（铁闸：exit 0 才算过）\npython scripts/verify.py manuscript.txt revised.txt --terms terms.txt\npython scripts/compare.py manuscript.txt revised.txt\n```\n\n**本场景避坑**：改稿时最常见的 FAIL 是缩写次数被压低（如 IRAK4 从 12 次\n引述删到 11 次）——守卫连「缩写出现次数」都守；这不是误报，把引述补回自然\n位置即可。投稿版务必保留 AI 使用披露（如期刊要求）——本报告不能替代披露。\n\n## 场景 2：学位论文（长文档、分章处理）\n\n**目标**：几万字的论文不塞给单次扫描——按章处理，报告才可读。\n\n```bash\n# 长文先看结构\npython scripts/detect.py thesis.md --structure\n# 按章拆分后逐章走场景 1 流程；方法/结果章的固定句式会被自动降权，\n# 不要因为「方法章分数高」就回去改方法章的表述——那是文体常态。\n```\n\n**本场景避坑**：学位论文的摘要常是「结构式摘要」（目的/方法/结果/结论带\n冒号标签）——冒号后带内容的行不会被误判为章节标题，放心。中文摘要与\n英文 Abstract 分开处理，语言口径各自更准。\n\n## 场景 3：回复审稿人（revision letter）\n\n**目标**：response letter 语气自然、逐条回应，但**引用的审稿意见原文一字不能动**。\n\n```bash\n# 只对\"自己的回应\"部分跑管线；审稿意见原文用手动引用块隔开\npython scripts/pipeline.py my_response.txt -o clean.txt --terms terms.txt\n```\n\n**本场景避坑**：response letter 里复制粘贴的审稿意见会被当作改写对象——\n把原文放进引用块（> 前缀）并在深改时跳过；verify 的数字守卫会拦住大部分\n误伤（审稿意见里的数据句被动过会 exit 1），但别依赖守卫兜底，先分好区域。\n\n## 场景 4：批量处理（课题组/编辑部）\n\n**目标**：一个目录的稿件先摸底再逐篇精修。\n\n```bash\n# 摸底：全目录扫描（JSON 便于汇总）\npython scripts/detect.py --batch ./submissions --json > overview.json\n# 逐篇精修只挑高分的；批量清理用 pipeline --batch 出 CSV 台账\npython scripts/pipeline.py --batch ./submissions -o batch_report.csv\n```\n\n**本场景避坑**：批量模式不生成 --html/--track/--suggestions（见输出提示）；\n需要报告的稿子单跑。批量二遍重试会自动救回瞬时失败的文件\n（detect --batch --json 的 retried 字段；pipeline 的 CSV 在 integrity 列标注\n「已重试 1 次」），两遍都失败的文件如实标注，人工看一眼即可。\n\n## 场景 5：CI/agent 门禁（自动化集成）\n\n**目标**：改稿质量卡进自动化流程，机器判定不达标就拦截。\n\n```bash\n# 全档门禁（0=干净 1=完整性 FAIL 3=需深改 4=模型残留）\npython scripts/pipeline.py orig.txt --rewrite new.txt --terms terms.txt --exit-verdict\n# JSON 里拿同源字段\npython scripts/pipeline.py orig.txt --rewrite new.txt --json | jq .exit_verdict\n```\n\n**本场景避坑**：批量 + `--exit-verdict` 是 fail-closed——目录里有扫描失败的\n文件门禁不予放行：错误文件贡献退出码 2，最终退出码取各文件最坏值（可为\n2/3/4），必为非零（宁可拦错不可放错；CI 断言请用「非 0」而非「==2」）。预算投影（plan.py）是线性\n近似，只用于排序，不要写进 CI 断言。\n\n## 场景 6：误报治理（领域术语被误判）\n\n**目标**：正当术语不再每次都被计分，且升级词表不丢。\n\n```bash\n# 从真实语料提取上下文固化守卫（中英双语口径）\npython scripts/learn_guards.py from-text 抓手 机械样本.txt\npython scripts/learn_guards.py add 抓手 --before \"机械,装置\" --after \"采用,夹持\"\npython scripts/learn_guards.py test \"装配平台的机械抓手采用气驱动设计。\"\n```\n\n**本场景避坑**：守卫是上下文豁免不是整词洗白（营销语境的「抓手」照常计分）；\n守卫存 `scripts/user_guards.json`，升级词表不丢。给 agent 的术语守卫固化\n后，把 `learn_guards.py list` 的输出贴进稿件交接说明，团队共享口径。\n\n## 场景 7：中文投稿的标点与格式\n\n**目标**：半角标点/Markdown 残留一次清干净，不误伤小数和文献著录。\n\n```bash\npython scripts/transform.py draft.txt -o step1.txt # 标点全角化（小数保护）\npython scripts/verify.py draft.txt step1.txt # 确认文献行未被误改\n```\n\n**本场景避坑**：参考文献行的半角标点是著录规范（已豁免不检测）；`3.14` 这类\n小数点受保护；中文输入法把 `2025` 打成 `２０２５` 会被 verify 以 E_NUM_WIDTH\n拦截——transform 已自动归一为半角（--track 记为「全角字母数字归一」）；`--deep` 深改档只删零信息损失成分（句首八股/排除式连接），\n黑话与节奏仍要按指南深改——两层互补不互相替代。\n\n---\n\n**通用收尾三连**（所有场景通用）：\n\n```bash\npython scripts/verify.py 原稿 新稿 --terms terms.txt # exit 0 才算过\npython scripts/compare.py 原稿 新稿 # 特征下降+完整性\npython scripts/stylecheck.py 原稿 新稿 --compare # 画像差值\n```\n\n如学校/期刊要求 AI 使用披露，请如实声明——本工具箱是质量自查记录，\n不能替代披露。\n\nFile v3.2.0:references/compliance.md\n\n# 使用边界与合规须知（学术诚信护栏）\n\n> 本工具改善的是**文字质量**。它不改变内容由谁创作的事实，也不能替代你对学校、\n> 期刊、平台规则的遵守义务。请先读这一页再用。运行本技能的 agent 应把本页作为\n> 行为守则执行。\n\n## 一、正当使用场景\n\n1. **润色自己的稿件**：行文生硬、模板腔重、翻译腔明显的正式文体，按写作质量原则\n 深改（清晰、节奏、具体性、立场）。\n2. **非母语（ESL）作者的自查**：正式学术文体经常被自动化评审误判；被误判的真实\n 作者用本工具做风格自查，理解哪些写法显得机械并改进它们。\n3. **合规披露前提下的 AI 辅助文本对齐**：你用 AI 起草、自己核实并修改了内容，\n 按所在场景规则**已获准/已披露**使用 AI——本工具帮你把行文打磨到与你的写作\n 习惯一致。\n4. **清理模型残留**：粘贴 AI 输出带进来的 oaicite/[cite:]/turn0search 等技术垃圾\n 与半角标点、Markdown 残留等机械问题。\n\n## 二、明确拒绝的场景（agent 行为守则）\n\n以下请求应**拒绝该目的**、说明披露义务，并转而提供正当的质量改写路径：\n\n- 「改到没人看得出来是不是 AI 写的」「帮我瞒过学校的 AIGC 检测」——以规避\n 学术诚信审查为目的的改写；\n- 隐瞒学校、期刊（ICMJE 等国际编辑规范）、arXiv 等平台**要求披露**的 AI 使用；\n- 伪造、移除或规避官方 AIGC 内容标识（水印/隐式标识）；\n- 为他人代写并包装为本人原创。\n\n学校对学位论文的 AIGC 规定、期刊的 AI 使用披露政策、arXiv 的披露要求——这些\n规则的义务主体是作者本人，工具无法替你履行披露义务，也不应被用来规避它们。\n\n## 三、AI 使用披露自查清单（提交前过一遍）\n\n- [ ] 目标学校/期刊/平台是否要求披露 AI 辅助？（查 author guidelines；默认「要求\n 或即将要求」）\n- [ ] AI 承担了什么角色（起草/润色/翻译/数据分析）？是否在 methods 或\n acknowledgments / disclosure 段如实说明？\n- [ ] 内容是否经过本人核实（引用真实存在、数据来自你的实验、结论你认同）？\n- [ ] 作者责任：所有作者对全文内容负责，AI 不满足作者资格标准（ICMJE）。\n- [ ] 中国境内发布场景：《人工智能生成合成内容标识办法》及配套国标\n （GB 45438-2025，2025-09-01 施行）对 AI 生成合成内容的显式/隐式标识义务\n 在「服务提供者」与特定场景的传播者；个人写作辅助通常不触发，但\n **发布/传播环节**请自行确认平台要求。本工具不添加、不伪造、不移除任何\n 官方标识。\n\n## 三之一、水印趋势备注（2026）\n\n水印与来源标识正在成为监管方向：欧盟《人工智能法案》第 50 条（面向 AI 提供者的\n机器可读标识义务）正在推动合成内容可识别，主流模型厂商已陆续部署文本水印。本工具的立场保持不变：**不添加、不伪造、\n不移除任何官方或厂商的内容标识与水印**——这些标识的完整性属于内容溯源体系，\n风格改进不触及也不应触及它们。\n\n## 四、工具边界\n\n- 本地启发式风格评分只是对写作模式的统计描述，不代表任何外部服务的测量，\n 更不说明文字由谁写成——不要把它当成那种证据展示。\n- 降特征不等于合规：风格改进与诚信合规是两件事，后者只能靠披露与核实。\n- 被误判的作者请保留草稿、版本历史与写作笔记——署名问题靠过程证据解决，\n 不靠风格分数；这也是 Wikipedia AI 清理项目的公开立场。\n\n## 五、给机构用户的建议\n\n- 用本工具做**投稿前/提交前**的风格自查与残留清理，而不是用来对抗检测评审。\n- 对被误判的学生/作者，先做写作过程核查（草稿、版本历史、口头答辩）。\n\n如你的场景规则与本页冲突，以你的场景规则为准。\n\nFile v3.2.0:references/deep_rewrite_guide.md\n\n# 深改操作手册：从计划到验收的执行循环（v3.0.0）\n\n> EN summary: this is the *operational* layer of deep rewriting — how to turn a\n> `plan.py` diagnosis into a bounded, verifiable rewrite session. Style rules\n> live in `style_guide_zh.md` / `style_guide_en.md`; this sheet defines the\n> process: plan → handoff → per-sentence rewrite → verify cadence → acceptance.\n\n## 为什么需要这一页\n\n真实使用反馈与深改实操复盘一致指出：本工具的深改环节由 agent/作者完成，而「怎么把\n深改做扎实、可验收」缺一张操作层面的流程页——风格指南管「怎么改」，本页管\n「按什么顺序改、改到什么程度停、怎么证明没改坏」。\n\n## 执行循环（五步，可多轮）\n\n```\n① 计划 python scripts/plan.py draft.txt --top 15 -o plan.md\n ↳ P0 句级队列（章节归属+命中类别+处理原则+预算投影）\n② 交接 python scripts/plan.py draft.txt --top 15 --handoff\n ↳ 深改交接块：逐句「原句+操作指令」，含守卫铁律与验收命令\n③ 逐句深改 按交接块顺序改——每句只做指令列出的操作，不顺手加戏\n④ 校验节拍 每改 3-5 句：python scripts/verify.py draft.txt step2.txt --terms terms.txt\n ↳ 任一 GUARD/ERROR → 回滚该句，改法降级（整句重写→局部替换）\n⑤ 收口 python scripts/compare.py draft.txt step2.txt\n python scripts/stylecheck.py step2.txt --compare draft.txt\n ↳ 量化验收：特征下降 + 完整性 PASS + 画像档位改善\n```\n\n## 每句怎么改（操作优先级）\n\n1. **删除优先**：八股开场（众所周知/综上所述/值得注意的是）、聊天客套、知识\n 截止声明——直接删，不需要替身。\n2. **合并次之**：「不仅X，而且Y」→「X，且Y」；同主语短句合并（`--deep` 可代劳\n 确定性部分）。\n3. **替换第三**：黑话/翻译腔按 style_guide 对照表换具体词；一处一换，不连锁改。\n4. **重写最后**：前三步救不回来的句子才整句重写——重写句必须通过\n `verify.py` 的数字/术语守卫才算完成。\n\n## 停止条件（防过度改写）\n\n- 预算投影显示再改 K 句预期收益 < 2 分 → 停（边际收益归零）。\n- 一句话改了 3 稿仍不达标 → 保留最好的一稿，标记「人工再读」，不要死磕。\n- 全文特征分进入目标档位（compare 确认）→ 停。剩余长尾交给作者本人。\n\n## 与其他件的分工\n\n| 问题 | 去处 |\n|---|---|\n| 某类模式具体怎么改 | `references/style_guide_zh.md`（EN 用 `_en.md`） |\n| 句子怎么排优先级/预算投影 | `plan.py`（`--json` 给 agent 消费） |\n| 交接块格式 | `plan.py --handoff` 直接产出 |\n| 数字/引用/术语守卫 | `verify.py`（exit 0 才算过） |\n| 量化验收 | `stylecheck.py 改稿 --compare 原稿` |\n| 七类场景的完整打法 | `references/best_practices.md` |\n\nFile v3.2.0:references/errors.md\n\n# 错误码与处置速查（Error Codes Reference）\n\n> 全部 CLI 脚本的退出码、违规/告警类别、触发条件与处置动作的统一映射表。\n> 程序化集成请以 `verify.py` 的退出码为契约（见下表）；其余脚本把判定写在输出里。\n\n## 一、退出码（CLI 契约）\n\n**缺省口径**（不带 `--exit-verdict`，人读/人工流程）：\n\n| 退出码 | 脚本 | 含义 | 处置 |\n|---|---|---|---|\n| 0 | 全部 | 完成（verify: 完整性 PASS） | 正常继续；其余脚本的判定读输出报告 |\n| 1 | **仅 verify.py** | 完整性守卫 FAIL——改稿动了数字/引用/术语 | **修改改稿**，不是改守卫、不是换参数 |\n| 2 | 全部 | 用法或文件错误 | 看 stderr 提示：路径错/文件空/二进制/编码/超限，每条提示自带处置建议 |\n| 1 | check_terms.py（独立口径） | 发现术语不一致（报变体对与次数） | 按「建议统一为」人工统一；`--report` 出 markdown 明细 |\n| 1 | check_stats.py（同 check_terms 口径） | 发现统计一致性问题（求和/分组 n/风格混用） | 核对原始数据后改稿；`--report` 出 markdown 明细 |\n\n> pipeline.py / compare.py 的守卫判定在输出报告的「完整性守卫: PASS/FAIL」行；按退出码分支的脚本请调 verify.py。check_terms.py 的 0/1/2 是自己的契约（0=一致），与 verify 的 1=FAIL 语义不同表，勿混用。\n\n**自动化口径**（v2.3.0：detect/compare/pipeline 加 `--exit-verdict` 后）：\n\n| 退出码 | 含义 | 典型 CI 动作 |\n|---|---|---|\n| 0 | 干净（低档、无残留；pipeline 另含完整性 PASS） | 合并/继续 |\n| 1 | 完整性守卫 FAIL（仅 pipeline 会产出；与 verify 契约同义） | 拒绝该改稿，回给 agent 重改 |\n| 3 | 风格特征中及以上（≥28，需要深改） | 进深改队列（plan.py 排优先级） |\n| 4 | 命中模型残留（critical） | 先跑 transform.py 清理 |\n| 2 | 用法/文件错误（不受 --exit-verdict 影响） | 修调用 |\n\n> detect/compare 的 `--exit-verdict` 只出 0/3/4（完整性仍只写报告——exit 1 契约专属 verify/pipeline）；\n> **pipeline 是唯一 1/3/4 全档判定命令**，CI 门禁推荐 `pipeline.py 原稿 --rewrite 改稿 --exit-verdict`。\n\n## 一B、集中异常层（v2.5.0）\n\n全部 CLI 的 `__main__` 统一经 `hxt_core.cli_entry(main)` 进入：任何用户侧\n异常输出**两行中文**——「错误: <发生了什么>」+「处置建议: <怎么办>」——并以\nexit 2 结束。`CliError(msg, hint)` 是脚本内主动报错的规范方式；SystemExit\n原样穿透，各脚本语义化退出码不受影响。程序内部 bug 仍带完整 traceback\n冒出（宁可吵，不可吞）。\n\n## 二、verify.py 违规类别（exit 1 = violations；WARN = 告警继续）\n\n| 类别 | 级别 | 含义 | 常见原因与处置 |\n|---|---|---|---|\n| numbers | E_NUM_LOST | ✗ 红线 | 数字丢失/被改 | 深改时把数据句改写了——恢复原数字或重写该句 |\n| comparison | E_CMP_FLIP | ✗ 红线 | 比较方向被改（P<0.05→P>0.05 级） | 结论方向反转，必须恢复原文方向 |\n| doi / pmid | ✗ 红线 | DOI / PMID 丢失 | 引用被删或改写——恢复 |\n| latin_abbr | E_ABBR_LOST | ✗ 红线 | 大写缩写丢失（DNA/PCR 类） | 缩写被中文化或删除——恢复原缩写 |\n| terms | E_TERMS_LOST | ✗ 红线 | 术语表条目缺失/减少 | 术语被替换——恢复，或把该词从术语表移除（若确认非术语） |\n| cjk_ratio | E_CJK_SHIFT | ✗ 红线 | 中英占比漂移超阈 | 整段被删或被译——检查是否误删段落 |\n| length | E_LEN_DRIFT | ✗ 红线 | 长度变化超阈（长文 ±25%，短文放宽） | 内容被整段删除——核对删减是否有意 |\n| fullwidth | E_NUM_WIDTH | ✗ 红线 | 数字/字母被改写为全角（２０２５≡2025 值等价但字符已变；v2.8.0） | 中文输入法所致——全部改回半角后重跑（学术稿件必须半角） |\n| numbers_added | W_NUM_ADDED | ⚠ 告警 | 出现原稿没有的数字 | **编造防线**：深改时凭空补的数字必须删除 |\n| number_context | W_CTX_SWAP | ⚠ 告警 | 数字上下文/顺序变化 | 两臂互换/方位错位——人工核对方向 |\n| sentences_added | W_SENT_ADDED | ⚠ 告警 | 改稿新增原稿没有的完整句（≥8 字符，无数字也提示；v2.8.0） | 逐句核对是否擅自加内容（编造防线的一部分） |\n| years | W_YEARS | ⚠ 告警 | 年份数量变化 | 年份引用被删——核对 |\n\n阈值均可 CLI 覆盖：`--max-length-change`、`--max-cjk-shift`。\n\n## 三、退出码 2 的常见触发与处置\n\n| 触发 | 提示关键词 | 处置 |\n|---|---|---|\n| 文件不存在 | 无法读取 | 核对路径（相对路径基于技能目录） |\n| 输入为空 | 输入为空 | 文件无内容或只传了空白 |\n| 二进制文件 | 疑似二进制（含 NUL 字节） | 转存 UTF-8 纯文本；Word 用 .docx 直读 |\n| 编码错误 | 乱码占比过高 | 文件是 GBK/UTF-16 等——转存 UTF-8 |\n| 文件超限 | 超过 50MB 上限 | 拆分文件分批处理 |\n| docx 缺部件 | 缺少正文部件 | 可能只是改了扩展名——另存为真正 .docx |\n| docx 加密 | 受密码保护 | 解除密码后另存 |\n| 参数错误 | argparse 提示 | `--help` 查看合法取值（如 --profile academic/general） |\n\n## 四、detect/pipeline 报告中的级别\n\n| 级别 | 含义 | 建议 |\n|---|---|---|\n| 低（0-27） | 基本无模板腔特征 | 无需处理 |\n| 中（28-49） | 有一定模板腔 | 可按 style_guide 选择性处理 |\n| 高（50-74） | 模板腔特征明显 | 按 style_guide 深改 |\n| 极高（75+ 或含硬残留） | 特征极重/含模型残留 | 先 transform.py 清硬残留，再按指南深改 |\n\n分数口径：本地启发式风格诊断，非任何官方检测分数；短文本（<15 单元）自动降权并标注「仅供参考」。\n\nFile v3.2.0:references/examples.md\n\n# 完整输入输出样例（End-to-End Examples）\n\n> 每个样例 = 真实命令 + 真实输出（来自回归语料，可复现）。样例中的数字/事实仅用于演示格式。\n\n## 样例 1：中文改写全流程\n\n**输入** `draft.txt`（节选，模板腔密集）：\n\n```\n综上所述，智慧医疗作为一项新兴范式，正在为整个行业赋能。一方面，它能够整合海量医疗数据，为临床决策提供新的思路；另一方面，它还可以优化资源配置，为分级诊疗制度的落地保驾护航。\n```\n\n**Step 1 自查**：\n\n```console\n$ python scripts/detect.py draft.txt\n==============================================================\n写作风格特征自查（本地启发式 · 非任何官方检测分数）\n==============================================================\n文件: draft.txt\n语言: 中文 | 规模: 216.5 单元 / 13 句\n\n综合评分: 58/100 [高]\n...\n改写建议(前10条):\n · 「赋能」→ 「支持 / 帮助 / 为…提供能力」\n · 「抓手」→ 「工具 / 途径 / 切入点」\n```\n\n**Step 2 机械清理**（本例无模型残留/客套句，清理近零改动——正常）：\n\n```console\n$ python scripts/transform.py draft.txt -o step1.txt\n{\n \"applied_fixes\": {\"半角逗号→全角\": 2},\n \"removed_sentences\": [],\n \"note\": \"机械清洗只覆盖语法安全层；黑话/八股/节奏需 agent 按指南深改，...\"\n}\n```\n\n**Step 3 深改**（agent 按 `references/style_guide_zh.md` 七步法执行，改后节选）：\n\n```\n智慧医疗的价值集中在两处：把分散的病历、影像和检验数据汇到一起供临床调用，以及让上级医院的诊断能力透过远程会话下沉到基层。前者的瓶颈是数据标准，后者是责任认定——这两点不解决，分级诊疗借不上智慧医疗的力。\n```\n\n**Step 4+5 守卫与对比**：\n\n```console\n$ python scripts/verify.py draft.txt step2.txt --terms terms.txt\n完整性守卫 verify：PASS ✓\n 数字/DOI/PMID/缩写/术语 全部保全。\n\n$ python scripts/compare.py draft.txt step2.txt\n风格特征分: 58 [高] → 12 [低] （-46）\n完整性守卫: PASS ✓\n```\n\n## 样例 2：英文模型残留清理 + 守卫拦截\n\n**输入** `ai_paste.txt`（从聊天窗口粘贴的稿子，带残留与客套句）：\n\n```\n综上所述，本研究纳入 128 例患者，其中 68 例进入试验组（p = 0.031）。\n值得注意的是，两组基线具有可比性 [cite: 1][cite: 3]，随访 24 个月。\n希望以上内容对您有所帮助！如需进一步修改请告诉我。\n```\n\n**一键管线**：\n\n```console\n$ python scripts/pipeline.py ai_paste.txt -o clean.txt\n==============================================================\n一键管线报告（机械清理）\n==============================================================\n风格特征分: 47 [中] → 18 [低]\n完整性守卫: PASS ✓\n 数字/DOI/PMID/缩写/术语 全部保全。\n深改任务简报:\n 指南: references/style_guide_zh.md\n · 剩余特征: 学术八股（人写也有，看密度） ×3\n 下一步: agent 按 references/style_guide_zh.md 对 clean.txt 做深度改写（保护数字/引用/术语），然后重跑本命令 --rewrite 改稿文件复核\n口径: 本地启发式风格特征评分，非任何官方检测分数\n```\n\n清理效果：`[cite: 1][cite: 3]` 行内摘除（句子保留）、客套句整句移除、数字 128/68/0.031/24 全部原样。\n\n## 样例 3：完整性守卫拦截演示（守卫不讲价）\n\n```console\n$ python scripts/verify.py 原稿.txt 改稿.txt\n完整性守卫 verify：FAIL ✗（学术安全红线）\n ✗ [numbers] 数字丢失/被改: 62\n ✗ [comparison] 比较方向/比较数字被改: <0.05\n判定: 未通过——请修复改稿后重跑\n$ echo $?\n1\n```\n\n改稿把「血沉 62mm/h」改成 58、把「P<0.05」改成「P>0.05」——无论措辞多流畅，exit 1。修的是改稿，不是守卫。\n\n## 样例 4：术语保护（正当学术用法不误报）\n\n```console\n$ python scripts/detect.py -s\nThe mutational landscape was profiled in this pivotal trial; robust regression confirmed the effect. (×3)\n6/低\n```\n\nmutational landscape / pivotal trial / robust regression 全部豁免；换成 \"the startup landscape ... plays a pivotal role\" 这类非学术语境则正常计分。\n\n## 样例 5：markdown 稿件全链路（v2.2.0：章节感知 + 句级计划 + 守卫拦截）\n\n**输入** `case_medical.md`（markdown 医学综述，模板腔密度中等）。v2.2.0 起\n`## 摘要`/`## 方法` 等 markdown 标题直接进章节感知，.md 语法残留自动豁免。\n\n**Step 1 自查 + 章节感知**：\n\n```console\n$ python scripts/detect.py case_medical.md --structure\n章节: 题引 / 摘要 / 引言 / 方法 / 讨论 / 结论（markdown 标题逐一识别）\n综合评分: 23/100 [低]\n · 学术八股（人写也有，看密度） 9 处 （综上所述 / 值得注意的是 / 众所周知…）\n · 排比/对仗结构（一方面…另一方面） 1 处\n节奏统计: 句长变异系数 0.62 | 连接词 0.41/句\n```\n\n**Step 2 改写优先级计划**（v2.2.0 新增，先定位再动手）：\n\n```console\n$ python scripts/plan.py case_medical.md --json\nP1 [结论] 2.2点 「…从而为临床决策的落地保驾护航。」\nP2 [引言] 0.9点 「众所周知，IRAK4在Toll样受体…」\nP3 [摘要] 0.8点 「取得了显著进展，为新型治疗策略的开发…」\n预算投影: 改完前5句→11 | 前10句→4 | 全部→2 （线性近似，仅供排序）\n```\n\n**Step 3 agent 深改**（按 style_guide 改 P0 队列，事实全保留：1/250000、\n48 篇、2005-2026、8 例/12 个月）。\n\n**Step 4 守卫拦截过度删减**——第一版深改把 IRAK4 从 12 次引述压到 11 次：\n\n```console\n$ python scripts/verify.py case_medical.md case_medical_v2.md\n ✗ [numbers] 数字丢失/被改: 4 ← IRAK4 里的 4 连带丢失\n ✗ [latin_abbr] 大写缩写丢失: IRAK4\n判定: 未通过——请修复改稿后重跑（exit 1）\n```\n\n补回自然引述（「IRAK4抑制剂的耐药机制」）后重跑：\n\n```console\n$ python scripts/verify.py case_medical.md case_medical_v2.md\n判定: 通过（exit 0）| 规模 694 → 609 字符\n\n$ python scripts/compare.py case_medical.md case_medical_v2.md\n 学术八股 已清除 9 处\n 翻译腔/空泛过渡 已清除 4 处\n 中文 AI 黑话 已清除 2 处\n 排比/对仗结构 已清除 1 处\n完整性守卫: PASS ✓\n```\n\n**要点**：markdown 章节直接被识别；plan 把深改力气指向贡献最大的句子；\nverify 连「缩写次数被压低」都能抓到——守卫拦的是内容损失，不是措辞。\n\n## 样例 6：误报 → 守卫固化（v2.2.0 learn_guards）\n\n「抓手」在词表里是营销黑话，但机械工程语境的「机械抓手」是正当术语——\n守卫按上下文豁免，不是整词洗白：\n\n```console\n$ echo \"装配平台的机械抓手采用气驱动设计，抓取力可调。\" | python scripts/detect.py -s\n46/中 ← 误报\n\n$ python scripts/learn_guards.py add 抓手 --before \"机械,装置\" --after \"采用,夹持\"\n已保存守卫：抓手（lang=zh，前文 2 项 / 后文 2 项）\n\n$ echo \"装配平台的机械抓手采用气驱动设计，抓取力可调。\" | python scripts/detect.py -s\n0/低 ← 机械语境豁免\n\n$ echo \"以创新为抓手，全面赋能业务增长。\" | python scripts/detect.py -s\n35/中 ← 营销语境照常计分（对照）\n```\n\n守卫存进 `scripts/user_guards.json`（升级词表不丢）；`list` 查看、\n`remove 抓手` 撤销、`from-text 术语 样本.txt` 从真实语料自动提取上下文\n（中英双语口径）。强制要求 `--before/--after` 上下文——纯词白名单会被拒绝。\n\n## 样例 7：CI/agent 门禁——机器退出码（v2.3.0 --exit-verdict）\n\n把改稿质量卡进自动化流程：改稿不达标就拦截，不需要人读报告。\n\n```console\n$ # 坏改稿：改稿=原稿（一句没改），门禁应拦截\n$ python scripts/pipeline.py draft.txt --rewrite draft.txt --exit-verdict\n$ echo $?\n3 ← 风格特征中及以上（52/高），进深改队列\n\n$ # 好改稿：事实保留、模板腔清除，门禁放行\n$ python scripts/pipeline.py draft.txt --rewrite rewritten.txt --exit-verdict\n完整性守卫: PASS ✓\n$ echo $?\n0\n\n$ # JSON 里的同源字段（agent 管线直接读）\n$ python scripts/pipeline.py draft.txt --rewrite draft.txt --json | jq .exit_verdict\n3\n```\n\n退出码全表（0/1/3/4/2 两套口径）：`references/errors.md` 第一节。\n`detect --exit-verdict` / `compare --exit-verdict` 只出 0/3/4——完整性 FAIL\n的 exit 1 契约专属 verify.py 与 pipeline。\n\n## 样例 8：确定性深改档（v2.4.0 --deep）+ 处置提示\n\n**输入**（模板腔中文段落）：\n\n```\n综上所述，本研究验证了假设。值得注意的是，该方法不仅提升了精度，而且降低了成本。众所周知，数据见第3.2节，p=0.03。\n```\n\n**transform --deep（句式级确定性转换，--track 可审计）**：\n\n```console\n$ python scripts/transform.py in.txt -o out.txt --deep --track track\n深改档: 句首八股删除 ×3\n深改档: 排除式连接合并 ×1\n\n$ cat out.txt\n本研究验证了假设。该方法提升了精度，且降低了成本。数据见第3.2节，p=0.03。\n```\n\n**守卫确认零损失**：\n\n```console\n$ python scripts/verify.py in.txt out.txt\n 数字/DOI/PMID/缩写/术语 全部保全。\n判定: 通过\n```\n\ntrack.md 里每笔深改操作独立可查（`深改档:句首八股删除 ×3`）。\n--deep 只做零信息损失操作（删纯套话标记/拆排除式连接）；黑话替换、\n节奏重排、立场重写仍由 agent 按指南执行——两层互补，不互相替代。\n\n**处置提示（v2.4.0，报告尾部 + JSON hints 字段）**——非论文文体自动建议切 profile：\n\n```console\n$ python scripts/detect.py blog_post.txt\n…\n处置提示:\n → 深改排序：python scripts/plan.py <文件> -o plan.md 生成句级优先级计划\n → 未识别到论文章节且特征以标点/翻译腔为主——非论文文体（博客/公文/通知）\n 可加 --profile general 降权八股信号\n```\n\n## 样例 9：集中异常层 + 批量重试 + 单步超时（v2.5.0）\n\n**两行中文错误（错误 + 处置建议）**——所有 CLI 统一格式，非技术用户也能照着做：\n\n```console\n$ python scripts/detect.py photo.png\n错误: 输入疑似二进制文件（含 NUL 字节）——请转存为 UTF-8 纯文本（.txt/.md）再处理\n```\n\n**批量二遍重试**——首遍失败的文件自动以双倍时间预算重扫一次，瞬时故障\n（负载抖动导致超时等）第二遍即恢复；真坏文件如实标注\"已重试\"：\n\n```console\n$ python scripts/detect.py --batch ./papers\n[重试] 二遍扫描：1 个失败文件重试，0 个恢复\n a.txt 0/低\n broken.txt 错误: 输入疑似二进制文件…（已重试 1 次）\n```\n\n`--json` 输出逐文件携带 `retried` 字段（true=重试后成功）。\n\n**单步超时与耗时透明**——`--step-timeout`（缺省 120 秒）管住清理与扫描\n每一步，超时干净报错；JSON 报告新增 `timings`：\n\n```console\n$ python scripts/pipeline.py draft.txt -o out.txt\n耗时: 清理 0.0s | 扫描 0.1s | 守卫 0.0s（合计 0.2s，单步预算 120 秒）\n\n$ python scripts/pipeline.py draft.txt -o out.txt --json | jq .timings\n{ \"cleanup_s\": 0.0, \"scan_s\": 0.11, \"verify_s\": 0.0, \"total_s\": 0.11 }\n```\n\n## 样例 10：风格画像——深改的量化验收（v2.6.0 stylecheck）\n\n**单文件画像**（AI 语料演示，黑话命中定位到段）：\n\n```console\n$ python scripts/stylecheck.py draft.txt\n| 指标 | 值 | 档位 |\n|---|---|---|\n| 黑话密度（每千字） | 36.81 | 偏机器 |\n| 句长变异系数 | 0.388 | 自然 |\n| 最高频句首占比 | 0.077 | 自然 |\n| 最长连续同开场 | 1 | 自然 |\n\n## 重点段落（黑话命中降序）\n- 第 1 段（104 字/3 句，命中 4）：赋能 → 支持 / 帮助 / 为…提供能力\n- 第 2 段（112 字/4 句，命中 5）：保驾护航 → 保障 / 支持\n- 第 4 段（126 字/2 句，命中 5）：抓手 → 工具 / 途径 / 切入点\n```\n\n**--compare 验收差值**（AI 语料 → 人写语料的演示对比，深改实际效果介于其间）：\n\n```console\n$ python scripts/stylecheck.py 原稿.txt 改稿.txt --compare\n| 黑话密度（每千字） | 36.81 | 0.0 | 偏机器 → 自然 |\n黑话命中合计：18 → 0（-18）\n```\n\n档位阈值用本地语料校准（AI 语料黑话密度 17-37/千字 vs 人写 0），只做验收\n提示、不改评分；改稿完整性仍以 verify.py 为准。深改验收闭环：\nplan.py 排队列 → agent 按指南改 → --compare 看画像差值 → verify 过守卫。\n\n\n## 样例 11：--terms auto 与画像 HTML（v2.7.0）\n\n```console\n$ python scripts/pipeline.py manuscript.txt -o clean.txt --terms auto\n[术语] 术语表=自动草稿 clean.terms.auto.txt（12 条，未经人工确认）——正式稿件建议人工过一遍后重跑\n\n$ python scripts/pipeline.py manuscript.txt -o clean.txt --terms auto --json | jq .terms_note\n\"术语表=自动草稿 clean.terms.auto.txt（12 条，未经人工确认）——…\"\n\n$ python scripts/stylecheck.py clean.txt --html profile.html\nHTML 画像报告已写入 profile.html\n```\n\nCJK 相邻缩写抽取修复（v2.7.0）：`IRAK4抑制剂` 里的 IRAK4 此前因 \\b 在汉字旁\n失效而抽不到——与 verify.py v2.1.0 同族问题，本版统一为 CJK 安全 lookaround。\n\nFile v3.2.0:references/faq.md\n\n# 常见问题 FAQ（含迁移指引）\n\n> 覆盖评测与用户反馈中的高频问题。没找到答案时，先跑 `python scripts/pipeline.py 你的文件 -o out.txt` 看报告，再按报告里的指南深改。\n\n## 基础\n\n**Q0：第一次用，最容易踩的坑？**\n读 `references/pitfalls.md`——24 条集中式常见错误清单（参数误用/编码事故/守卫\n误读/流程合规），每条带正确做法。TL;DR：跑 pipeline → 读报告 → 按指南深改 →\nverify → compare。\n\n**Q1：这个工具和 paper-polisher-pro 什么区别？**\npaper-polisher-pro 是综合润色工具箱（术语、翻译腔、比喻审计、AIGC 标识合规、期刊预检），本工具专攻「风格自然化」一件事：风格特征自查 → 机械清理 → 深改简报 → 完整性守卫。两者可同时使用互不冲突——先本工具去模板腔，再 paper-polisher-pro 做全稿润色。\n\n**Q2：报告里的分数是检测器分数吗？**\n不是。分数是对写作模式（套话密度、句长均匀度、模板结构）的本地启发式统计，不代表任何外部服务的测量结果，更不说明文字由谁写。怎么理解这个分数：它度量的是「模式密度」——比如 50 分意味着每千字命中约 X 处可改写特征；同一篇稿子改掉八个股开场后分数会实质性下降，所以它适合当**改稿进度条**用。它不能当「检测器」用：对流畅的现代模型文本几乎不触发（诚实边界节有实测数字），也别反过来拿低分证明「是人写的」。详见 SKILL.md「诚实边界」与 `references/pdf_confidence.md` 末节的口径提醒。\n\n**Q3：支持什么文件格式？**\n纯文本（.txt）、Markdown（.md）、**Word（.docx）**、以及 **PDF（v1.6.0 起实验性\n直读，限英文文本型；加密/扫描件拒收，CJK/嵌入字体尽力识别并拒收、可能漏网——\n抽取结果请人工检查）**。stdin 也支持：\n`echo \"文本\" | python scripts/detect.py`。\n\n**Q4：会改坏我的数据吗？**\n机械清理层设计上不触碰数字/引用；深改层由 agent 按指南执行，改完必须过 `verify.py`——数字、统计量、DOI、PMID、年份、缩写、术语表任何丢失都会 exit 1。守卫还会对「凭空新增的数字」告警（编造防线）。历史实测：改写中 p 值篡改、两臂互换、整句含电话号码误删，全部被守卫拦截过。\n\n## 使用\n\n**Q5：一定要跑四个脚本吗？**\n不用。`python scripts/pipeline.py draft.txt -o out.txt` 一条命令跑完自查→清理→守卫→报告；要确定性删八股加 `--deep`，要 CI 门禁加 `--ci`。分步入口（detect/transform/verify/compare 单独跑）是为这些场景保留的：只清残留不动风格（单跑 transform）、只想看哪几句最该改（单跑 plan --handoff）、把守卫接进自己的脚本（单跑 verify 取退出码）。\n\n**Q6：术语表（--terms）怎么准备？**\n先跑 `python scripts/extract_terms.py 原稿 -o terms.txt` 自动生成草稿（大写缩写、\n书名号/引号内术语按频次排序），人工删改后使用。每行一个术语，`#` 开头是注释。\n医学文本建议补充：药名（含商品名）、基因符号（鼠源首字母大写形态如 Myc 也要列）、\n量表名、仪器名。不提供术语表时，守卫仍查数字/DOI/PMID/年份/全大写缩写。\n\n**Q7：退出码怎么看？**\n`verify.py` 是严格契约方：`0`=完整性 PASS、`1`=完整性 FAIL（有数字/引用/术语被动过——修改改稿，不是改守卫）、`2`=用法或文件错误。`detect/transform/compare/pipeline` 把判定写在输出报告里，完成即返回 `0`（用法/文件错误 `2`）——按退出码分支的脚本请以 verify.py 为准。所有脚本支持 `--version`。\n\n**Q8：检测误报了正当术语怎么办？**\n两层解决：①词表自带术语保护（mutational landscape、pivotal trial、robust regression、序列对齐、沉淀反应、心室重塑、串联质谱等已豁免）；②仍误报的，在 `scripts/patterns_*.json` 的 `term_guards` 加一条你的搭配（allow_before/allow_after），并欢迎反馈补充词表。\n\n**Q9：分数多少算\"有问题\"？**\n0-27 低（正常）；28-49 中（有模板腔，可改可不改）；50+ 高（建议按指南深改）；报告会给出具体剩余特征清单。分数是密度统计，短文本（<15 单元）自动降权并标注\"仅供参考\"。\n两个实用读法：①看**结构分布**比看总分有用——报告按类别列出剩余特征，套话 12 处+翻译腔 3 处的 40 分，远比单一「en_vocab 12 处」的 40 分好改；②用 `stylecheck.py 改稿 --compare 原稿` 看分项差值，总分不降但句长 CV 从 0.2 升到 0.45，就是节奏真改好了。\n\n**Q10：数字前后打架有工具查吗？**\n有。`python scripts/check_stats.py 原稿`（v3.2.0）查三类内部一致性问题：百分比清单加起来不是 100（只查带「分别/依次/构成比」等划分用语的句子——合并症占比这类合法的非穷举清单不误报）、同一分组前后 n 不一致（「干预组（n=45）」vs「最终干预组（n=48）」会归一化后比对）、p= 与 P= 风格混用。退出码与 check_terms 相同（0 一致 / 1 有问题 / 2 用法错误），可直接接 CI——注意按默认输出取退出码：`--json` 模式恒返回 0，分支看 JSON 的 total 字段。建议在**定稿/送审前**对原稿跑一遍（改稿若动过数字，先过 verify 守卫再说）。它查的是内部一致性，不是统计正确性——结果是否真实以原始数据为准。\n\n## 迁移（自旧版页面）\n\n**Q11：我是从旧版页面过来的，有变化吗？**\n功能全集在这里且只增不减：旧版全部能力（双语自查/机械清理/深改手册/完整性守卫/前后对比）+ v1.1.0 新增（一键管线 pipeline.py、FAQ、完整示例、错误码体系）。旧页与本页同源同版本维护。\n\n**Q12：旧页和新页内容一致吗？版本号什么关系？**\n内容完全一致，同一份代码库双页发布，版本号两页保持同号（如两页同时是 v1.2.0）；仅某一页需要追修时该页用 x.x.1 子版本号。过渡期例外：旧页因迁移历史存在 +0.0.1 偏移（如本页 v1.1.0 对应旧页 v1.1.1）。以后更新认准 **paper-rewriter**（本页）；旧页永久保留作为入口。\n\n**Q13：旧版评分 3 分是怎么回事？**\n那是平台对「迁移说明占位页」的评分（页面只有搬家通知，没有功能），不代表工具本身——本页 v1.0.0 实测均分 4.55（trust 维 5.0）。\n\n## 边界\n\n**Q13：能保证某种评审结果吗？**\n不能，也不承诺。本工具改善写作质量与自然度；任何承诺「保证不被判为机器生成」的服务都不可信。合规义务（AI 使用披露）在作者本人，见 references/compliance.md。\n\n**Q14：多大文本算\"太大\"？**\nv1.4.0 起不再需要手动切分：detect/pipeline 对超 1MB 文本**自动分块**处理（按段落\n边界，报告会标注分块口径与块数），内存峰值恒定。注意完整性守卫（verify.py）始终\n整文比对——这是红线语义，不可分块。\n\n**Q14c：--structure 的章节降权会不会帮作者\"藏住\"方法段的机器味？**\n不会。降权只归一综合分（方法段的固定句式是领域惯例，公平计量）；各章节原始分\n仍在报告中逐项展示，任何人都能看到完整数据。「藏匿」不是本工具的设计，也\n不符合它的诚信立场（见 compliance.md 拒绝清单）。\n\n**Q14b：报告能导出成网页吗？能一次扫整个目录吗？**\n都能。`--html report.html` 生成单文件 HTML（无外链可直接存档/转发）；compare 的\nHTML 含逐句增删对照，复核改稿最直观。批量：`--batch 目录名` 一次扫全部\n.txt/.md/.docx/.pdf（detect 出逐文件评分，pipeline 逐文件清理+守卫汇总 CSV）。\n\n**Q14a：transform 的激进模式（-a）什么时候用？**\n适合：非正式文本的破折号堆叠、空泛开场白清理。不适合：学术方法段的插入语破折号、\n任何将直接提交的文本（改完必须人工复核）。普通模式（不带 -a）已经能清模型残留、\n客套句、标点与安全填充语——先跑普通模式看报告再决定要不要 -a。\n\n**Q15：博客/公众号/公文这类非学术文本，评分偏高怎么办？**\n用 `--profile general`：学术八股和公文过渡语在人写的非学术文本里是常态，general\n模式把这些信号降权 60%（黑话、模型残留、节奏信号不受影响）。默认 `academic`\n始终按学术论文口径标定，处理论文时不需要加参数。\n\n**Q16：这个工具会联网吗？会读我的其他文件吗？**\n不会、不会。全部脚本仅 Python 标准库、零网络请求；只读取你作为参数传入的文件，\n只写入你用 `-o`/`--suggestions`/`--html`/`--track` 指定的输出路径；不读环境变量、不创建子进程和定时任务。\n详见 SKILL.md「权限与环境声明」。\n\n**Q17：2026 年了，检测技术都在进步，这套\"质量优先\"路线还成立吗？**\n更成立了。公开研究显示：①单纯同义转写并不能让文字变好——质量优先路线的\n价值不随工具演进贬值；②节奏与结构层面的建议之所以有效，是因为它们让文字\n回归真实写作的质量，本工具不以任何外部产品为目标或参照；③正式学术文体被\n自动化评审误判仍是行业痛点——被误判的真实作者依然是第一等用户。质量优先\n是写作本身的标准，长期成立。\n\nFile v3.2.0:references/pdf_confidence.md\n\n# PDF 抽取置信度：分层口径与真实语料校准（v3.0.0）\n\n> EN summary: PDF direct-read is experimental. v3.0.0 replaces the blanket\n> ToUnicode-CMap rejection with a graded confidence ceiling: extraction is\n> attempted for all unencrypted text PDFs, hard gates stay on the three\n> garbage probes (control-char rate / GBK round-trip / U+FFFD ratio), and the\n> ToUnicode presence caps \"高\" at \"中\" with a spot-check note. Calibration on\n> 200 real-world PDFs: 98.0% (196/200) correctly rejected, all 4 passes honestly\n> labeled.\n\n## 一、三层判定流水线\n\n```\n.pdf 输入\n ├─ ① 硬闸（拒绝即报错，给可执行出路）\n │ 加密 /Encrypt → 「解除密码或导出 UTF-8」\n │ 无文本流（扫描件）→ 「用 OCR 或导出 UTF-8」\n │ 解压预算超限（单流 20MB / 累计 50MB）→ 「拆分」\n ├─ ② 乱码三探针（最坏失败态=乱码静默放行，必须拦）\n │ 控制字符率 >0.5% / GBK 回程 CJK >20% / U+FFFD >2%\n └─ ③ 置信度分层（只标注不拦截；indicators 随 pdf_meta/JSON 透出）\n 高：常用词命中率 ≥25% 且 控制字符 <0.3% 且 词均长 3-9\n 低：命中率 <8% 或 词均长 >14 或 可抽词 <30\n 中：其余（可用，建议抽查）\n 附加：源 PDF 含 ToUnicode CMap（嵌入字体标记）→ 「高」封顶为「中」并注明\n 「字体子集存在字面替换风险，建议抽查关键数字与术语」（v3.0.0 校准）\n```\n\n## 二、真实语料校准（2026-10-09，200 篇全盘随机，seed 2026）\n\n| 判定 | 篇数 | 占比 | 抽查结论 |\n|---|---|---|---|\n| 拒绝：控制字符探针（CJK/嵌入字体 CID） | 169 | 84.5% | 中文医学文献 PDF 主体，拒绝正确且给了导出出路 |\n| 拒绝：加密 | 13 | 6.5% | 正确 |\n| 拒绝：解压预算（20MB 单流 / 50MB 累计） | 12 | 6.0% | 超大手册类，正确 |\n| 拒绝：无文本流（扫描件/纯图） | 2 | 1.0% | 正确 |\n| 放行：低（可抽词过少/命中率≈0） | 3 | 1.5% | 抽查=二进制残渣/图片型碎片，标注诚实 |\n| 放行：中（命中率 12.6%，断词形态） | 1 | 0.5% | 抽查=英文技术文档但字距碎裂（\"V e rsion\"），中档标注诚实 |\n| 放行：高 | 0 | — | 本语料无纯净英文文本型 PDF |\n\n**分层校准结论**：本语料（中文医学文献为主）98.0%（196/200）落在拒绝层且全部给对原因；\n放行层 4/4 标注与人工抽查一致——低=垃圾、中=可用需抽查、（高由合成 fixture\n验证：66 词纯净英文命中 36.4% 词均长 5.8 → 高；同文 + ToUnicode → 中）。\n\n## 三、ToUnicode 降级的对照实验（v3.0.0 依据）\n\n- 30 篇真实中文医学 PDF 去掉 ToUnicode 硬拒后试抽取：29 篇仍被控制字符探针\n 拦下（CID 编码字节汤），1 篇解压预算拒绝——**硬拒对这些文件是冗余**。\n- 硬拒的代价：现代 Word/LaTeX 导出的英文 PDF 普遍嵌字体子集（必带 ToUnicode），\n 被一刀切误伤。降级后这类文件可读，且以「中」档标注字面替换风险。\n- 残余风险（诚实声明）：字体子集若做语义级字面重映射（字节可读但字形映射被改），\n 乱码探针无法发现——这正是 ToUnicode 封顶「中」+ 建议抽查数字的原因。\n\n## 四、使用建议（按置信度分档）\n\n| 置信度 | 建议动作 |\n|---|---|\n| 高 | 正常进入流程；守卫链（数字/DOI/PMID）照常兜底 |\n| 中 | 先抽查 3-5 处关键数字与术语再全量处理；`--track` 审计开启 |\n| 低 | 不要用直读结果做改写——按报错/注记导出 UTF-8 文本或 OCR 后重来 |\n| 拒绝 | 按报错信息处理（解密/导出/OCR/拆分）；导出文本后无此层问题 |\n\n> 口径提醒：置信度是**抽取健全性**启发式，不是内容质量分，更不是任何官方检测。\n\nFile v3.2.0:references/pitfalls.md\n\n# 常见错误用法与事故清单（Pitfalls）\n\n> 集中呈现本工具的典型误用（从各文档收拢+扩充）。每条：现象 → 原因 → 正确做法。\n> 遇到不明行为先查本清单，再查 errors.md 错误码表。\n\n## 一、参数与模式误用\n\n| # | 错误用法 | 后果 | 正确做法 |\n|---|---|---|---|\n| 1 | 把 detect 的分数当\"AI 检测器分数\"告诉别人 | 误导（本工具是风格启发式，非官方检测） | 表述为「风格特征自查分」；见诚实边界 |\n| 2 | 用 `--profile general` 处理论文 | 八股信号被降权，论文漏诊 | 论文用默认 academic；general 只用于博客/公文 |\n| 3 | 对「将直接提交」的文本开 `-a` 激进档不复核 | 破折号/开场被改，语气走样 | -a 仅用于非正式文本；提交前必须人工复核 |\n| 4 | `--batch` 传了文件路径而非目录 | exit 2 | 传目录；单文件直接作位置参数 |\n| 5 | 按 pipeline 的退出码写自动化分支 | 缺省口径 pipeline 恒 exit 0，FAIL 被当成功 | 加 `--exit-verdict`（v2.3.0：0/1/3/4 判定码）或仍调 verify.py（0/1/2 契约方）；见 errors.md 自动化口径表 |\n| 6 | pipeline 同时给 `-o` 和 `--rewrite` | `--rewrite` 优先，`-o` 不生效 | 二选一：清理用 -o，复核用 --rewrite |\n\n## 二、输入与编码事故\n\n| # | 错误用法 | 后果 | 正确做法 |\n|---|---|---|---|\n| 7 | 直接喂 .doc 改名 .docx 的文件 | 报「无法解析」 | 用 Word 另存为真正的 .docx |\n| 8 | 喂 GBK/UTF-16 编码的 .txt | 报「乱码占比过高」拒收 | 先转存 UTF-8（Windows 记事本另存为 UTF-8） |\n| 9 | 喂扫描件/纯图片 PDF | 报「未找到文本流」 | 先 OCR，或人工导出文本 |\n| 10 | 喂 CJK/嵌入字体的 PDF | 尽力识别并拒收；未被识别时会输出乱码 | 抽取结果请人工检查；可靠路径=导出 UTF-8 文本（PDF 直读为实验性，限英文文本型） |\n| 11 | 术语表用 Windows 记事本保存带 BOM | （v1.4.0 已修复）首词失检 | 无需操作；老版本请转存 UTF-8 |\n| 12 | 术语表里放了整句而非术语 | verify 按整句匹配，形同虚设 | 每行一个词/短语；用 extract_terms.py 生成草稿 |\n\n## 三、守卫与报告误读\n\n| # | 错误用法 | 后果 | 正确做法 |\n|---|---|---|---|\n| 13 | verify FAIL 后改守卫参数（放大阈值）让它 PASS | 红线被绕过，坏稿放行 | FAIL=改稿有错，修改稿本身 |\n| 14 | 忽略 numbers_added 告警 | 深改时编造的数字留在文中 | 新增数字=编造，立即删除或标注来源 |\n| 15 | 把 compare 的分数差当质量差 | 分数只统计特征密度 | 结合逐句 diff（--html）人工复核 |\n| 16 | 批量模式发现 FAIL 后继续提交 | 某文件守卫未过 | 逐文件修复后重跑 batch 确认 |\n| 17 | 删除/绕过 --terms 术语表以求通过 | 术语改动失去保护 | 术语表是护栏不是障碍 |\n\n## 四、流程与合规\n\n| # | 错误用法 | 后果 | 正确做法 |\n|---|---|---|---|\n| 18 | 用本工具「瞒过学校的 AIGC 审查」 | 违反学术诚信（工具会拒绝该目的） | 披露 AI 使用；工具用于质量自查 |\n| 19 | 把 HTML 报告当官方证明提交 | 本地启发式≠任何官方结论 | 报告仅自查用；披露义务在作者 |\n| 20 | 深改后不跑 verify 直接提交 | 数字/引用可能已坏 | 深改→verify→compare 三连是固定流程 |\n| 21 | 手改 `scripts/user_guards.json` 格式出错，扫描报警告 | 守卫被整体忽略（扫描不中断） | 用 `learn_guards.py list` 检查/`add` 重建；损坏严重就删掉该文件重来 |\n| 22 | 把 `plan.py` 的预算投影当承诺分数 | 投影是线性近似，不是外部检测分数 | 投影只用于排序与分工；最终以 verify+compare 结果为准 |\n| 23 | 把 `--deep` 当成完整深改，跑完直接提交 | --deep 只删零信息损失成分（句首八股/排除式连接），黑话与节奏不在射程 | --deep 后仍按 style_guide 深改；每笔操作看 --track 记录，最终 verify+compare 收口 |\n| 24 | 用本工具判断文本「是不是 AI 写的」，或用低分给人写背书 | 风格通道对流畅/现代模型文本漏检 98-100%（2026-10 真实语料实测） | 本工具=风格自查+完整性护栏；检测能力边界见 SKILL 诚实边界节与归墟 SkillTest 实测报告 |\n\nArchive v3.1.0: 30 files, 143866 bytes\n\nFiles: README.md (1862b), references/api.md (6431b), references/best_practices.md (6561b), references/compliance.md (4157b), references/deep_rewrite_guide.md (3020b), references/errors.md (5787b), references/examples.md (13765b), references/faq.md (7825b), references/pdf_confidence.md (3897b), references/pitfalls.md (4376b), references/style_guide_en.md (5937b), references/style_guide_zh.md (6381b), scripts/_sections_block.py (2163b), scripts/check_terms.py (9413b), scripts/compare.py (6881b), scripts/detect.py (17982b), scripts/extract_terms.py (6291b), scripts/hxt_core.py (67336b), scripts/learn_guards.py (9281b), scripts/patterns_en.json (20203b), scripts/patterns_zh.json (15667b), scripts/pipeline.py (19846b), scripts/plan.py (14715b), scripts/reporter.py (20247b), scripts/stylecheck.py (8019b), scripts/transform.py (14253b), scripts/verify.py (13768b), skill-card.md (2179b), SKILL.md (25783b), _meta.json (133b)\n\nFile v3.1.0:SKILL.md\n\n---\nname: paper-rewriter\ndescription: >\n Academic writing style toolkit, bilingual CN/EN: AI flavor scan and style-pattern\n self-check reports (scan reports are detection only), deterministic text cleanup\n (model artifacts, punctuation, filler phrases), integrity\n guardrails (numbers, DOIs, PMIDs, terminology must survive untouched), and\n agent-guided style naturalization for clearer, more natural academic prose\n (de-templating, de-translationese, rhythm, concreteness). Built for scholars whose\n formal writing reads stiff, templated or machine-flavored — especially non-native\n (ESL) authors. Includes AIGC-disclosure compliance checks (China 2025-09 labeling\n rules) and academic-integrity guardrails: this tool improves writing quality for\n self-review; it does not help misrepresent authorship, conceal required AI\n disclosure, or defeat integrity review. 100% local, zero upload, Python stdlib\n only. Related: paper-polisher-pro (broad polishing), pubmed-verifier, cite-holmes,\n academic-figures, cn-med-oa, doc-holmes.\nallowed-tools:\n - Read\n - Write\n - Bash\n - Glob\n - Grep\n---\n\n# Academic Style Toolkit (paper-rewriter)\n\nBilingual (CN/EN) style naturalization for academic & medical writing: find stiff,\ntemplated or machine-flavored patterns, clean mechanical debris, revise for clarity\nand natural register — with integrity guardrails on every step.\n\n> **Routing in one line**: grammar/fluency/journal-format polish → use a polisher\n> (paper-polisher-pro); de-templating, model-residue cleanup, AI-flavor style\n> self-check and rewriting → this tool. Need both? Polish first, then run this pipeline.\n\n## Feature status (v3.1.0)\n\n| Feature | Status | Since |\n|---|---|---|\n| detect / transform / verify / compare / pipeline | Stable | v1.0 |\n| Section-aware scanning (`--structure`) | Stable | v1.7 |\n| `.docx` direct input; 50MB file guard; read retry | Stable | v1.3–1.8 |\n| Sentence-level rewrite plan (`plan.py`) | Stable | v2.2 |\n| User-learned term guards (`learn_guards.py`) | Stable | v2.2 |\n| `--exit-verdict` machine exit codes (detect/compare/pipeline) | Stable | v2.3 |\n| Deterministic deep polish (`--deep`), handling hints, scan time budget | Stable | v2.4 |\n| Centralized error layer (`CliError` + handling hints), batch retry, per-step timeout | Stable | v2.5 |\n| Scale envelope: 800K-char chunks (2K overlap) · 50MB file cap · 120s step budget | — | — |\n| Style profile (`stylecheck.py`: per-paragraph quantified guide audit) | Stable | v2.6 |\n| Best-practices handbook (7 real scenarios), stylecheck `--html`, `--terms auto` | Stable | v2.7 |\n| PDF extraction confidence self-report (`read_text_ex`, detect/pipeline annotation) — calibrated on 200 real-world PDFs, see `references/pdf_confidence.md` | Experimental | v2.8 |\n| Term guard variant groups (`check_terms --pack cardiovascular` — 8 domains, 27 groups / 55 variants, groups may hold >2 forms e.g. HF/心力衰竭/心衰; nesting-safe) | Stable | v3.0 / v3.1 |\n| Stats panel in style profile (`stylecheck --json` → `stats`: TTR / function-word ratio / sentence-length quantiles; informational, no bands) | Stable | v3.1 |\n| `--ci` gate alias on detect/compare/pipeline (same as `--exit-verdict`) | Stable | v3.1 |\n| Deep-rewrite handoff block (`plan.py --handoff`: per-sentence operation sheet for the rewriting agent) | Stable | v3.0 |\n| Batch accepts `.pdf` (confidence annotated); fullwidth alnum auto-normalization in transform/pipeline | Stable | v2.9 |\n| HTML reports, `--batch`, `--track` audit trail | Stable | v1.5–1.6 |\n| PDF text extraction (text PDFs; v3.0.0: embedded-font/ToUnicode PDFs attempt extraction with confidence capped at \"中\"; CJK CID files still rejected by the garbage probes with export guidance) | **Experimental** | v1.6 |\n\nAnything marked **Experimental** can reject valid files or need manual review of\nits output — export to UTF-8 text when in doubt. Everything else is\nregression-tested offline on every release.\n\n## Integrity guardrails — read first\n\n- **Permitted**: polishing your own drafts; aligning AI-assisted text with your\n voice where your school/journal **allows or requires disclosed** AI assistance;\n cleaning model residue (stray `oaicite`/`[cite:]` tokens) from legitimately\n disclosed drafts; improving clarity, rhythm and concreteness of formal prose.\n- **Not permitted**: using this toolkit to misrepresent authorship, to conceal AI\n use where disclosure is required, or to defeat academic-integrity review. If a\n request is framed that way (\"rewrite it so the review can't tell\"), refuse the\n framing, explain the disclosure obligation, and offer the legitimate\n quality-editing path instead. Agents running this skill are expected to enforce\n this line.\n- **This tool never changes data**: numbers, p-values, confidence intervals, DOIs,\n PMIDs, years and terminology are guarded by `verify.py` (see below). Improved\n prose must never cost a fact.\n- Compliance: China's AIGC labeling rules (effective 2025-09-01), journal disclosure\n policies and arXiv policies are summarized in `references/compliance.md` — the\n obligation to disclose belongs to the author, not the tool.\n\n## Division of labor\n\n| Layer | Who does it | What |\n|---|---|---|\n| Style self-check | `scripts/detect.py` | Heuristic style-pattern report (templated phrasing, uniform rhythm, boilerplate) for author self-review |\n| Mechanical cleanup | `scripts/transform.py` | Model artifacts, chatbot filler, punctuation normalization, safe filler swaps — grammar-safe only. **When to use directly**: you only need residue/filler cleanup without any stylistic diagnosis (fast, deterministic). |\n| **Quality revision** | **you (the agent)** | Follow `references/style_guide_zh.md` / `_en.md`: de-templating, rhythm, concreteness, stance |\n| Integrity guard | `scripts/verify.py` | Numbers/DOIs/PMIDs/years/abbreviations/terms must survive untouched |\n| Before/after | `scripts/compare.py` | Pattern-score delta + integrity verdict |\n\n**What it can actually change (before → after)** — the capability promise at\nexample granularity:\n\n| Changeable | Example | Done by |\n|---|---|---|\n| Ritual openers/closers | 「众所周知，…」 → straight to the point | transform `--deep` + agent |\n| Ballot-style frames | 「不仅X，而且Y」 → 「X，且Y」 | transform `--deep` |\n| Model residue | oaicite / turn0search / [cite: 1] tokens removed wholesale | transform |\n| Punctuation & fullwidth digits | half-width → full-width (decimal-safe); ２０２５→2025 | transform |\n| Jargon / translationese | 「进行…的研究」 → 「研究」 | agent (style guide) |\n| Rhythm | long-sentence runs → varied lengths; repeated openers → varied | agent + stylecheck |\n| Concreteness | vague appraisal → grounded statement (**never invents data**) | agent (guards flag invented numbers as W_NUM_ADDED warning — human removes them) |\n| Term consistency | HF/心力衰竭/心衰 mixed → unified to dominant form | `check_terms.py` groups |\n| Never changed | numbers, p-values, CIs, DOIs, PMIDs, years, terms, quoted content | verify.py blocks |\n\n## Quick start\n\n**How to ask for this in plain words** (EN digest of the full phrase table in\nSKILL_ZH.md): \"remove the AI flavor from this paper\" / \"this reads too templated\" /\n\"clean up oaicite and [cite:] residue\" / \"tell me which sentences to fix first\" /\n\"check my rewrite broke no numbers\" / \"give me a style profile\" / \"stop flagging\nthis legitimate term\" — each maps to the pipeline, `plan.py`, `transform.py`,\n`verify.py`+`compare.py`, `stylecheck.py` and `learn_guards.py` respectively.\n\n**Reading map** (this file is the hub; details live one click away):\nfirst time → Quick start + The workflow below · troubleshooting →\n`references/pitfalls.md` + `references/errors.md` · CI/agent integration →\nAutomation section · capability limits → Honest boundaries · scenario how-tos →\n`references/best_practices.md` · deep-rewrite process →\n`references/deep_rewrite_guide.md` · PDF confidence tiers →\n`references/pdf_confidence.md` · programmatic use → `references/api.md`.\n\nNo agent is required — every capability below runs directly in a terminal.\nEvery script has built-in `--help` (full flag reference) and `--version`;\nquick flag semantics:\n\n| Flag | Meaning |\n|---|---|\n| `--profile general` | non-academic text: down-weight formulaic/boilerplate signals |\n| `--deep` | deterministic sentence-level transforms (canned openers, not-only merge) |\n| `--exit-verdict` | machine exit codes for CI/agent gating (see below) |\n| `--structure` | section-aware scoring (IMRaD) |\n| `--step-timeout SEC` | per-step wall-clock budget (default 120) |\n| `--terms FILE` | term list for the integrity guard (build via extract_terms.py) |\n\nOne command (self-check → cleanup → revision brief → integrity guard):\n\n```bash\npython scripts/pipeline.py draft.txt -o out.txt --terms terms.txt\n```\n\nVisualization & batch (v1.5.0): add `--html report.html` to any of\ndetect/pipeline/compare for a self-contained HTML report (score cards, category\ntables, revision worksheet, integrity verdict; compare adds sentence-level\nadd/delete diff). Scan a whole directory with `--batch dir` (detect: per-file\nscore summary; pipeline: per-file cleanup+integrity CSV).\n\n**Structure-aware scanning** (`detect --structure`, v1.7.0): detects paper\nsections (abstract/introduction/methods/results/discussion/conclusion/\nreferences, bilingual) and scores each separately. Methods/results weights\nnormalize the aggregate only — raw per-section scores are always reported in\nfull; the fixed phrasing of a Methods section is genre convention, not a\nmachine signal. Missing-section hints included. Markdown headings are\nrecognized since v2.2.0 (`## 摘要`, `**方法**`, numbered `2. Methods`).\n\n**Sentence-level rewrite plan** (`plan.py`, v2.2.0): ranks sentences by their\nweighted pattern contribution and produces a P0 rewrite queue with section\nattribution, per-sentence category hits, handling advice and a linear budget\nprojection (fix the top-K offenders → projected score). `--json` for agent\nconsumption. The projection is a local approximation for prioritization — not a\npromise, and not any external detector's score.\n\nPreparing the term list: `python scripts/extract_terms.py draft.txt -o terms.txt`\nauto-extracts candidates (abbreviations, quoted terms) into a draft you confirm\nby hand. Input formats: `.txt`/`.md` directly, **`.docx` (Word) directly** since\nv1.3.0; PDF direct-read is **experimental** (text PDFs; confidence self-report —\na \"低\" tier means garbled extraction, export to UTF-8 text instead; see\n`references/pdf_confidence.md`). Ask for a\nrevision worksheet alongside any run with `--suggestions path.md` (detect.py and\npipeline.py both support it): category, sample, suggested handling and the guide\nsection to read — the tool proposes, you and the guide decide.\n\nFor non-academic text (blogs, posts, office documents), add `--profile general`\nto down-weight formal-boilerplate signals; the default `academic` profile is\ncalibrated for scholarly manuscripts.\n\nOr run the steps individually (from the skill's own directory, or use absolute paths):\n\n```bash\npython scripts/detect.py draft.txt # style-pattern self-check (-j JSON, -s score only)\npython scripts/transform.py draft.txt -o step1.txt\n# ... agent quality revision of step1.txt per the style guide ...\npython scripts/verify.py draft.txt step2.txt --terms terms.txt\npython scripts/compare.py draft.txt step2.txt\n```\n\nScenario-organized best practices (journal submission, thesis, revision\nletters, batch, CI gates, false-positive handling, CN punctuation):\n`references/best_practices.md`.\nWorked end-to-end examples: `references/examples.md`. Unified exit codes,\nviolation categories and remedies: `references/errors.md`. **Centralized\ncommon-mistakes list (24 items): `references/pitfalls.md`** — read it before\nyour first real run. Python API reference: `references/api.md`. FAQ:\n`references/faq.md`.\n\n**Revision tracking** (`--track base` on transform/pipeline): every change the\nmechanical layer makes is recorded to `base.md` + `base.json` — an auditable\nlist of what the tool touched (rule, count, deleted sentences,\nflagged-for-review).\n\n**PDF input (experimental, v1.6.0; confidence self-report since v2.8.0)**:\nEnglish text PDFs (FlateDecode/WinAnsi, unencrypted) are extracted with the\nstandard library only. Since v2.8.0 every PDF scan reports an extraction\nconfidence (高/中/低) computed from four heuristics — common-word hit rate,\ncontrol-character rate, average word length, extractable word count — so\n\"review the output\" becomes \"the tool tells you how trustworthy this\nextraction is\". 低 means garbled-form typical: export to UTF-8 text instead. PDFs with embedded\nfont encodings (ToUnicode CMaps, typical for CJK) are rejected when detected —\ndetection is best-effort: if one slips through, the output may be garbled, so\n**review extracted PDF text before relying on it**. When in doubt, export to\nUTF-8 text. Chunk threshold: 800,000 characters per chunk — since v2.2.0\nadjacent chunks share a 2,000-character overlap window, so patterns spanning a\nchunk boundary are captured and double-counts are reconciled (v2.1.x and\nearlier could miss boundary-spanning signals). File-size guard 50MB (scans\nauto-chunk at any size within the cap; the integrity guard is whole-document).\n\n### Agent invocation protocol\n\nWhen invoked, decide the path first, then run it:\n\n- **Trigger words**: 写作风格自查 / 论文改写润色 / 去模板腔 / 翻译腔清理 /\n 学术改写 / 段落改写 / 表达优化 / style self-check /\n style naturalization / naturalize academic writing / de-templating /\n academic rewriting / passage rewrite / expression polish → run the pipeline\n above.（中文变体触发词见 SKILL_ZH.md——CH 分寸词不入英文文件）\n （Parameter cheat sheet lives in Quick start; exit-code tables in\n references/errors.md — both are linked from here to avoid hunting across\n sections.）\n- **Disambiguation (this tool vs a polisher)**: 「论文改写润色」 here means\n style naturalization / de-templating (removing the machine flavor from\n academic prose). Decision rule with examples —\n route to a polisher (e.g. paper-polisher-pro) when the ask is only about\n language correctness/fluency: 「帮我改下语法」「这句读不顺，润色一下」\n 「按期刊风格改写摘要」; route to this toolkit when the ask is about templated\n tone or model residue: 「这篇读起来像 AI 写的」「把套话删一删」\n 「文里有 [cite: 1] 这种残留」; when both apply, polish first, then run this\n pipeline — neither tool substitutes for the other.\n- **Term inconsistency** (abbreviation vs full form, mixed synonyms) →\n `check_terms.py file --pack `; `--list-packs` shows all eight\n domain packs (v3.0.0).\n- **User wants to know what to fix first** → `plan.py draft.txt -o plan.md`\n (P0 sentence queue + budget projection) before deep revision.\n- **User wants quantified acceptance of a rewrite** → `stylecheck.py 原稿 改稿\n --compare` (v2.6.0 style profile delta; triggers: 风格画像 / 量化验收 /\n 深改验收 / style profile / acceptance check).\n- **A scan flags a legitimate term** (false positive) → don't edit the pattern\n files; persist a guard instead: `learn_guards.py from-text 术语 样本.txt`\n (or `add`) — the guard survives upgrades and applies to every later scan.\n- **User only wants a verdict on an existing rewrite** → `pipeline.py draft.txt\n --rewrite rewritten.txt --terms terms.txt` (skip cleanup).\n- **User asks to conceal AI use, misrepresent authorship, or defeat integrity\n review** → refuse the framing, point to `references/compliance.md`, offer the\n legitimate quality-editing path instead. Do not run the toolkit toward that end.\n- Exit codes: `verify.py` is the strict contract holder — `0` integrity PASS,\n `1` integrity FAIL (fix the rewrite, never the guard), `2` usage/file error.\n `detect/transform/compare/pipeline` report the verdict in their output and\n always exit `0` on completed runs, `2` on usage/file errors. For agent/CI\n branching, add `--exit-verdict` (v2.3.0): machine exit codes 0/3/4 on\n detect/compare, full 0/1/3/4 on pipeline — see Automation & CI integration\n below. Every script supports `--version`.\n\n## Automation & CI integration (v2.3.0)\n\nScripts are automation-first: every verdict is machine-readable, two ways.\n\n- **Default contract (human flows)**: `verify.py` alone holds exit 0/1/2\n (1 = integrity FAIL); detect/transform/compare/pipeline finish with 0 and\n put the verdict in their report. Never branch on their default exit code.\n- **Machine contract** — add `--exit-verdict` (or the shorter `--ci` alias, v3.1.0)\n to detect / compare / pipeline:\n `0` clean (low, no residue) · `3` style patterns at medium or above (needs\n deep revision) · `4` model-residue hit (run transform first) · `1`\n integrity FAIL (pipeline only — same meaning as verify's 1) · `2` usage\n error (unchanged). **pipeline is the only full 1/3/4 gate** — recommended\n CI check: `pipeline.py draft.txt --rewrite rewritten.txt --terms terms.txt\n --exit-verdict`.\n- **JSON**: `detect -j` (full scan result), `pipeline --json` (before/after,\n verify verdict, `exit_verdict` field, handling `hints`, agent brief), `compare --json`\n (delta + verify), `plan.py --json` (sentence queue + projections).\n Example gate in one line:\n `python scripts/pipeline.py orig.txt --rewrite new.txt --json --exit-verdict || echo \"blocked: $?\"`\n- Exit-code tables for both contracts: `references/errors.md` §1.\n\n## The workflow\n\n1. **Self-check**: `detect.py draft.txt` — a heuristic report of style patterns\n (canned phrases, uniform sentence rhythm, boilerplate transitions, model\n artifacts). The report is for the author's own review; the score is a local\n heuristic, not an official measurement of anything.\n2. **Mechanical cleanup**: `transform.py draft.txt -o step1.txt` — strips stray\n model artifacts (`oaicite`, `turn0search`, `[cite: 1]`, `grok_card`,\n `attached_file`), leftover chatbot pleasantries, markdown residue, and a safe\n list of filler phrases; CN halfwidth punctuation is normalized to fullwidth\n (decimals protected). `-a` adds em-dash reduction and empty-opener removal.\n `--deep` (v2.4.0) adds sentence-level deterministic transforms — canned\n opener deletion, 「不仅X，而且Y」→「X，且Y」 merging — zero-information-loss\n only, every operation logged to `--track`. Clean human-written text passes\n through byte-identical\n (except fullwidth alnum normalization, see feature status v2.9).\n3. **Quality revision** (the real work): optionally rank the work first —\n `python scripts/plan.py draft.txt -o plan.md` gives a sentence-level P0\n queue (worst offenders with section, category and advice) so deep effort\n lands where the score lives; add `--handoff` to emit a per-sentence\n operation sheet (original sentence + directive + guard rules + acceptance\n commands) that a rewriting agent can follow verbatim (v3.0.0).\n Then read the guide for the text's language —\n - CN: `references/style_guide_zh.md` — structural de-templating → jargon\n cleanup → rhythm → concreteness → stance → integrity red lines\n - EN: `references/style_guide_en.md` — smaller words → fewer significance\n frames → plain clauses instead of parallelism → rhythm → real attribution →\n commit to a position\n - Revise section by section. Preserve all facts, numbers, citations, terminology.\n3b. **Quantified acceptance** (`stylecheck.py`, v2.6.0): per-paragraph style\n profile — jargon hits located to the paragraph, sentence-rhythm CV, opener\n diversity, each banded 自然/观察/偏机器 with style_guide anchors;\n `--compare 原稿 改稿` shows the delta so deep-revision acceptance is\n metric-based. Bands are calibration hints only — they never alter scores.\n4. **Guard**: `verify.py draft.txt step2.txt --terms terms.txt` — exit 1 means a\n number/citation/term was altered: fix the revision, not the guard. Build\n terms.txt for medical text (drug names, gene symbols — include mouse-style\n capitalized forms like Myc — and scale names), one term per line. The guard\n also warns on numbers absent from the original (fabrication defense) and\n number-context swaps (arm/direction ordering).\n For mixed synonym usage (abbreviation vs full form, e.g. HF vs\n 心力衰竭), also run `check_terms.py file --pack cardiovascular`\n (v3.0.0 domain packs; `--list-packs` shows all eight).\n5. **Re-check**: `compare.py draft.txt step2.txt` — pattern reduction + integrity\n verdict. Keep the before/after pair for your records; if your institution or\n journal requires an AI-use disclosure, state it plainly — this report is a\n quality self-check, not a substitute for disclosure.\n\n## Honest boundaries\n\n- The style score is a local heuristic on writing patterns. It is not a\n measurement produced by any external service, and it says nothing about\n authorship. Never present it as one.\n- Formal academic prose and non-native writing are routinely misjudged by\n automated reviewers; if you are the author, keep drafts, version history and\n notes — process evidence, not style scores, settles authorship questions.\n- This tool does not interact with any external review system, does not remove\n official content labels or watermarks, and does not assist concealment of\n required disclosures. See `references/compliance.md`.\n- **Detection-capability boundary (measured, 2026-10)**: on fluent LLM-generated\n text this toolkit's style channel barely fires — 128 real ChatGPT texts scored\n below 28 in 98% of cases, and 60 samples of 2026-era models scored 0 (nothing\n flagged). Style tools that do flag everything in that benchmark misfire on\n ~50% of human forum prose. **A low score here does not mean \"no AI was\n involved\"** — use this toolkit as a style self-check + integrity guard, not\n as a judge of authorship.\n- **Statistical-channel experiment (2026-10, 373 files measured)**: sentence-\n length band concentration is the strongest single statistical signal (AI\n corpora 0.68/0.72 vs human 0.48/0.47). Integrated conservatively as a\n \"uniform rhythm flag\" (≥8 sentences; band≥0.65 or cv≤0.30): 41% of 2023-era\n AI corpus flagged @ 3% human flag rate (below the FP baseline). The flag is\n informational only — regular genres (e.g. literature abstracts) trigger it\n too; it is never a detection verdict.\n- Scale envelope: regression-tested up to ~1MB text files; the scanner is linear\n (no catastrophic backtracking, bounded quantifiers only). Memory use is roughly\n 3x file size; for very long manuscripts, split by section for readable reports.\n\n## Permissions & environment statement\n\nFor reviewers, security scanners and cautious users:\n\n- Reads **only** the file paths you pass as arguments (plus stdin, including the\n `.txt`/`.md`/`.docx`/`.pdf` files inside a `--batch` directory) and its own\n bundled wordlist files (`scripts/patterns_*.json`, plus\n `scripts/user_guards.json` if you have created one with `learn_guards.py`).\n Verify it yourself:\n\n ```bash\n grep -rnE \"urllib|requests|socket|subprocess|os\\.environ\" scripts/ || echo \"clean\"\n ```\n\n (runs clean as of this release — the claim is reproducible, not rhetorical).\n- Writes **only** to output paths you pass explicitly: `-o`/`--output` on\n transform/compare/pipeline/plan/extract_terms, `--suggestions`, `--html`,\n `--review` (detect.py's markdown report), `--report` (check_terms.py), and\n `--track` (`base.md` + `base.json`). One derived exception: with\n `pipeline --terms auto`, the tool also writes the auto-generated term draft\n `.terms.auto.txt` (tool-written, unreviewed — see the\n workflow note). One tool-owned data file on top of that:\n `learn_guards.py add`/`from-text`/`remove` writes\n `scripts/user_guards.json` (your learned term guards, via a transient\n `.tmp` + atomic rename). No other writes.\n- **Zero network access** — no HTTP calls, no downloads, no API keys.\n- **Zero third-party dependencies** — Python standard library only.\n- Reads **no environment variables**; spawns **no subprocesses**; creates **no\n scheduled tasks**; the only temp file ever written is the\n `user_guards.json.tmp` rename target described above.\n- Test corpora and dev notes live in the development repo only, not in the\n distributed package.\n\n## Customizing\n\n- `scripts/patterns_zh.json` / `patterns_en.json` — pattern lists (+ rewrite\n suggestions), regex signals, term_guards (legitimate academic collocations that\n must not be flagged, e.g. \"mutational landscape\", \"pivotal trial\", CJK\n \"sequence alignment\" and \"precipitation reaction\"), auto_fixes.\n- **User-learned guards** live in `scripts/user_guards.json` (managed by\n `learn_guards.py` — do not hand-edit; `list` prints, `remove` deletes).\n Keep them there rather than editing `patterns_*.json`: pattern files are\n replaced on upgrade, your guards file is not.\n- Score calibration constants live in `scripts/hxt_core.py` (`_LANG_K`); the four\n test corpora in the development repo's `tests/` (not shipped in the package)\n document the intended separation.\n\n## Related tools\n\n- pubmed-verifier — verify PMID/DOI references before submission\n- cite-holmes — deep research with hallucination-free citations\n- paper-polisher-pro — comprehensive polishing & plagiarism reduction\n- academic-figures — publication-ready scientific figures\n- doc-holmes — layout-preserving PDF translation\n\nFile v3.1.0:README.md\n\n# paper-rewriter\n\n[![GitHub Stars](https://img.shields.io/github/stars/docsor1212/paper-rewriter?style=social&label=Star)](https://github.com/docsor1212/paper-rewriter)\n\nBilingual (CN/EN) style naturalization for academic & medical writing: find stiff,\ntemplated or machine-flavored patterns, clean mechanical debris, revise for clarity\nand natural register — with integrity guardrails on every step.\n\nDeterministic cleanup (model artifacts, punctuation, filler), style-pattern\nself-check reports (local heuristic, detection only), sentence-level rewrite\nplanning, a deterministic deep-polish mode, and a whole-document integrity guard\n(numbers, DOIs, PMIDs, terminology must survive untouched). 100% local, zero\nupload, Python standard library only.\n\n## Install / Quick Start\n\nInstall via your skill manager (skills CLI / ClawHub / SkillHub), or clone this\nrepository and run the scripts directly with Python 3 (no dependencies):\n\n```bash\n# one command: self-check -> cleanup -> revision brief -> integrity guard\npython scripts/pipeline.py draft.txt -o out.txt --terms terms.txt\n\n# or step by step\npython scripts/detect.py draft.txt # style-pattern self-check\npython scripts/transform.py draft.txt -o step1.txt\npython scripts/verify.py draft.txt step1.txt # integrity guard (exit 0/1/2)\n\n# full guide, boundaries and agent invocation protocol\ncat SKILL.md\n```\n\n**China mirror (ModelScope 魔搭)**: — if you find this skill useful, a like there helps others find it.\n\n## Integrity guardrails\n\nPermitted: polishing your own drafts; aligning AI-assisted text with your voice\nwhere disclosure is allowed or required. Not permitted: misrepresenting\nauthorship, concealing required AI disclosure, or defeating integrity review —\nthe toolkit refuses that framing. See `references/compliance.md`.\n\nFile v3.1.0:_meta.json\n\n{\n \"ownerId\": \"kn7b6sjwend7cwwmhf7mdg1wzx82dfbf\",\n \"slug\": \"paper-rewriter\",\n \"version\": \"3.1.0\",\n \"publishedAt\": 1791564238996\n}\n\nFile v3.1.0:references/api.md\n\n# API 参考（程序化集成）\n\n> 供想在 Python 内直接调用核心函数的用户/agent。所有函数纯标准库、零网络。\n> CLI 优先场景请直接用命令行（见 SKILL.md）；本文档面向需要嵌入自己管线的人。\n\n## hxt_core\n\n```python\nimport sys\nsys.path.insert(0, \"<技能目录>/scripts\")\nimport hxt_core\n```\n\n### hxt_core.scan(text, lang=None, profile=\"academic\") → dict\n\n风格特征扫描（≤1MB 文本）。\n\n- `text`：str，待扫文本（必填）\n- `lang`：`\"zh\"|\"en\"|\"mix\"|None`——None 时自动检测\n- `profile`：`\"academic\"`（默认，论文口径）| `\"general\"`（八股/公文信号 ×0.4）\n- 返回：`{\"score\": int 0-100, \"level\": \"低|中|高|极高\", \"critical_hit\": bool,\n \"lang\": str, \"profile\": str, \"units\": float, \"sentences\": int,\n \"categories\": {cat: {\"label\", \"count\", \"weight\", \"samples\", \"auto_fixable\"}},\n \"guards_applied\": [...], \"stats\": {\"burstiness_cv\", \"connector_density\", ...},\n \"suggestions\": [{\"from\", \"to\"}], \"honest_note\"}`\n\n```python\nr = hxt_core.scan(\"这个方案为业务赋能，打法清晰。\")\nprint(r[\"score\"], r[\"level\"], r[\"categories\"].get(\"zh_jargon\", {}).get(\"count\"))\n```\n\n### hxt_core.scan_chunked(text, lang=None, profile=\"academic\") → dict\n\n超大文本分块扫描（>1MB 自动启用；CLI 的 detect/pipeline 对 >1MB 输入自动走本函数）。\n返回结构同 scan，额外带 `\"chunked\": 块数`；跨块边界的结构信号可能少量漏检（报告标注）。\n\n### hxt_core.read_text(path, max_mb=50.0) → str\n\n健壮文本读取：大小上限 / 二进制 NUL 检测 / BOM 剥离 / 乱码占比守卫 / .docx 直读。\n失败抛 `ValueError`（消息含处置建议）或 `OSError`。\n\n```python\ntry:\n text = hxt_core.read_text(\"稿件.docx\")\nexcept ValueError as e:\n print(\"输入不合规:\", e)\n```\n\n### hxt_core.build_suggestions(orig, scan_result, guide) → str\n\n把 scan 结果转为修订建议工作单（markdown 字符串：类别/样本/处理原则/指南锚点）。\n`guide` 传指南相对路径（如 `references/style_guide_zh.md`）。\n\n### hxt_core.verify_integrity 相关\n\n完整性守卫的函数入口在 `verify.verify(orig, new, terms=None, max_len_change=25.0,\nmax_cjk_shift=0.12) -> {\"ok\": bool, \"violations\": [...], \"warnings\": [...], \"stats\": {...}}`\n（`import verify as vf`）。退出码契约只属于 CLI 层。\n\n## transform / extract_terms / verify（CLI 模块复用）\n\n| 函数 | 说明 |\n|---|---|\n| `transform.load_fixes(lang=None, aggressive=False)` | 返回 (rx, repl, note, guards) 修复列表 |\n| `transform.apply_auto_fixes(text, fixes)` | 应用机械修复（带术语守卫），返回 (text, applied) |\n| `transform.drop_flagged_sentences(text)` | 客套句/截止声明整句删除（覆盖律+数字保护），返回 (text, removed) |\n| `extract_terms.extract(orig, min_count=2, cap=40)` | 术语候选抽取，返回 [(term, count, kind)] |\n| `verify.load_terms(path)` | 术语表加载（BOM/守卫内建） |\n\n所有函数零网络、零环境变量、只读写调用方显式传入的路径。\n\n## plan / learn_guards（v2.2.0 新增）\n\n| 函数/入口 | 说明 |\n|---|---|\n| `hxt_core._chunk_spans(text, max_chars=800_000, overlap=2000)` | 分块切点（含重叠窗起点），scan_chunked 缝合的底层 |\n| `hxt_core.scan_chunked(text, ..., max_chars, overlap)` | 分块扫描（重叠缝合口径）；小分块参数便于测试 |\n| `hxt_core.clear_pattern_cache()` | 清词表缓存（learn_guards 写守卫后同进程生效用） |\n| `hxt_core.verdict_exit_code(score, critical_hit, verify_ok=None)` | --exit-verdict 机器退出码（0/1/3/4），detect/compare/pipeline 共用 |\n| `hxt_core.build_hints(text, r, profile)` | 处置建议引擎（v2.4.0）：critical/plan/learn_guards/--profile general 四类提示 |\n| `transform.deep_polish(text)` | 确定性深改（v2.4.0）：句首八股删除+排除式连接合并，返回 (text, ops) |\n| `hxt_core.scan(..., time_budget=120.0)` | 墙钟预算（v2.4.0）：超时抛 ValueError 带拆分建议；`SCAN_TIME_BUDGET` 为缺省常量 |\n| `hxt_core.CliError(msg, hint)` / `fail()` / `cli_entry(main)` | 集中异常层（v2.5.0）：两行中文错误+处置建议，exit 2；SystemExit 穿透 |\n| `pipeline.py --step-timeout SEC` / report `timings` | 单步墙钟预算与各步耗时（cleanup/scan/verify，v2.5.0） |\n| `transform.normalize_fullwidth_alnum(text)` | 全角字母/数字→半角（v2.9.0）：E_NUM_WIDTH 的对症修复，返回 (text, 改写数) |\n| `hxt_core.read_text_ex(path)` / `_pdf_confidence` | 带元数据读取（v2.8.0）：.pdf 返回 (text, {confidence 高/中/低, notes})；四启发指标校准见 tests/v280 |\n| `detect --batch --json` / `pipeline --batch` 的 `retried` | 批量二遍重试标记（v2.5.0）：失败文件以双倍预算重扫一次 |\n| `hxt_core.style_profile(text)` / `stylecheck.py` | 风格画像（v2.6.0）：段落级黑话定位+节奏/开场档位+指南锚点；--compare 验收差值（阈值=dev 四语料校准） |\n| `hxt_core.audit_patterns()` / `STYLE_BANDS` | 模式审计兜底（v2.6.0）：未受限贪婪量词检测；档位阈值常量 |\n| `reporter.render_style_profile/compare` / `stylecheck.py --html` | 风格画像 HTML（v2.7.0）：档位表+重点段落+对比差值 |\n| `pipeline.py --terms auto` | 自动术语草稿（v2.7.0）：extract_terms 口径 min_count=1+警告；JSON terms_note 字段 |\n| `hxt_core._load_user_guards()` | 读 `scripts/user_guards.json`（损坏降级为空并 stderr 提示） |\n| `plan.py --json / -o plan.md --top N` | 句级改写优先级计划：P0 队列+章节归属+线性预算投影 |\n| `plan.py --handoff`（v3.0.0） | 深改交接块：逐句「原句+操作指令」指令单（含守卫铁律+验收命令）；markdown 追加输出，`--json` 下为 `handoff` 键 |\n| `check_terms.py --pack <域> / --list-packs`（v3.0.0） | 术语守卫域包：八学科域 28 对按域选跑；结果带 `pack` 域标签；`hxt_core` 侧 `check_terms.validate_packs()` 嵌套安全校验（变体互斥断言） |\n| `learn_guards.py add/from-text/list/remove/test` | 误报→守卫固化；语义同内置 term_guards（±30 字符窗口豁免） |\n\nplan 的逐句贡献与投影均为近似口径（同类同权线性近似）；learn_guards 只写\n`scripts/user_guards.json` 一个文件，原子替换（tmp+rename）。\n\nFile v3.1.0:references/best_practices.md\n\n# 最佳实践手册（Best Practices）——按场景组织的端到端工作法\n\n> 与 pitfalls.md（23 条错误用法）互补：这份手册按**真实场景**组织，每个场景给\n> 标准命令序列、预期输出形态、该场景特有的避坑点。所有分数与档位均为本地\n> 启发式口径，非任何外部检测分数。\n\n## 场景 1：期刊投稿前的自查（最常见）\n\n**目标**：投稿前把模板腔降下来，同时确保一个数据都没动。\n\n```bash\n# 1. 术语表先行（医学/生科稿件必做——守卫的弹药）\npython scripts/extract_terms.py manuscript.txt -o terms.txt\n# 人工过一遍 terms.txt：删掉普通词、补上缩写变体（如 Myc 与 MYC 都要）\n\n# 2. 一键管线出底稿\npython scripts/pipeline.py manuscript.txt -o clean.txt --terms terms.txt\n\n# 3. agent 深改（按 style_guide_zh/en 七步法，重点看 plan 排出的 P0 句）\npython scripts/plan.py clean.txt -o plan.md # 句级优先级队列+预算投影\n# ……按 plan.md 逐句深改，产出 revised.txt……\n\n# 4. 量化验收（改前 vs 改后画像差值）\npython scripts/stylecheck.py clean.txt revised.txt --compare\n\n# 5. 守卫+复核（铁闸：exit 0 才算过）\npython scripts/verify.py manuscript.txt revised.txt --terms terms.txt\npython scripts/compare.py manuscript.txt revised.txt\n```\n\n**本场景避坑**：改稿时最常见的 FAIL 是缩写次数被压低（如 IRAK4 从 12 次\n引述删到 11 次）——守卫连「缩写出现次数」都守；这不是误报，把引述补回自然\n位置即可。投稿版务必保留 AI 使用披露（如期刊要求）——本报告不能替代披露。\n\n## 场景 2：学位论文（长文档、分章处理）\n\n**目标**：几万字的论文不塞给单次扫描——按章处理，报告才可读。\n\n```bash\n# 长文先看结构\npython scripts/detect.py thesis.md --structure\n# 按章拆分后逐章走场景 1 流程；方法/结果章的固定句式会被自动降权，\n# 不要因为「方法章分数高」就回去改方法章的表述——那是文体常态。\n```\n\n**本场景避坑**：学位论文的摘要常是「结构式摘要」（目的/方法/结果/结论带\n冒号标签）——冒号后带内容的行不会被误判为章节标题，放心。中文摘要与\n英文 Abstract 分开处理，语言口径各自更准。\n\n## 场景 3：回复审稿人（revision letter）\n\n**目标**：response letter 语气自然、逐条回应，但**引用的审稿意见原文一字不能动**。\n\n```bash\n# 只对\"自己的回应\"部分跑管线；审稿意见原文用手动引用块隔开\npython scripts/pipeline.py my_response.txt -o clean.txt --terms terms.txt\n```\n\n**本场景避坑**：response letter 里复制粘贴的审稿意见会被当作改写对象——\n把原文放进引用块（> 前缀）并在深改时跳过；verify 的数字守卫会拦住大部分\n误伤（审稿意见里的数据句被动过会 exit 1），但别依赖守卫兜底，先分好区域。\n\n## 场景 4：批量处理（课题组/编辑部）\n\n**目标**：一个目录的稿件先摸底再逐篇精修。\n\n```bash\n# 摸底：全目录扫描（JSON 便于汇总）\npython scripts/detect.py --batch ./submissions --json > overview.json\n# 逐篇精修只挑高分的；批量清理用 pipeline --batch 出 CSV 台账\npython scripts/pipeline.py --batch ./submissions -o batch_report.csv\n```\n\n**本场景避坑**：批量模式不生成 --html/--track/--suggestions（见输出提示）；\n需要报告的稿子单跑。批量二遍重试会自动救回瞬时失败的文件\n（detect --batch --json 的 retried 字段；pipeline 的 CSV 在 integrity 列标注\n「已重试 1 次」），两遍都失败的文件如实标注，人工看一眼即可。\n\n## 场景 5：CI/agent 门禁（自动化集成）\n\n**目标**：改稿质量卡进自动化流程，机器判定不达标就拦截。\n\n```bash\n# 全档门禁（0=干净 1=完整性 FAIL 3=需深改 4=模型残留）\npython scripts/pipeline.py orig.txt --rewrite new.txt --terms terms.txt --exit-verdict\n# JSON 里拿同源字段\npython scripts/pipeline.py orig.txt --rewrite new.txt --json | jq .exit_verdict\n```\n\n**本场景避坑**：批量 + `--exit-verdict` 是 fail-closed——目录里有扫描失败的\n文件门禁不予放行：错误文件贡献退出码 2，最终退出码取各文件最坏值（可为\n2/3/4），必为非零（宁可拦错不可放错；CI 断言请用「非 0」而非「==2」）。预算投影（plan.py）是线性\n近似，只用于排序，不要写进 CI 断言。\n\n## 场景 6：误报治理（领域术语被误判）\n\n**目标**：正当术语不再每次都被计分，且升级词表不丢。\n\n```bash\n# 从真实语料提取上下文固化守卫（中英双语口径）\npython scripts/learn_guards.py from-text 抓手 机械样本.txt\npython scripts/learn_guards.py add 抓手 --before \"机械,装置\" --after \"采用,夹持\"\npython scripts/learn_guards.py test \"装配平台的机械抓手采用气驱动设计。\"\n```\n\n**本场景避坑**：守卫是上下文豁免不是整词洗白（营销语境的「抓手」照常计分）；\n守卫存 `scripts/user_guards.json`，升级词表不丢。给 agent 的术语守卫固化\n后，把 `learn_guards.py list` 的输出贴进稿件交接说明，团队共享口径。\n\n## 场景 7：中文投稿的标点与格式\n\n**目标**：半角标点/Markdown 残留一次清干净，不误伤小数和文献著录。\n\n```bash\npython scripts/transform.py draft.txt -o step1.txt # 标点全角化（小数保护）\npython scripts/verify.py draft.txt step1.txt # 确认文献行未被误改\n```\n\n**本场景避坑**：参考文献行的半角标点是著录规范（已豁免不检测）；`3.14` 这类\n小数点受保护；中文输入法把 `2025` 打成 `２０２５` 会被 verify 以 E_NUM_WIDTH\n拦截——transform 已自动归一为半角（--track 记为「全角字母数字归一」）；`--deep` 深改档只删零信息损失成分（句首八股/排除式连接），\n黑话与节奏仍要按指南深改——两层互补不互相替代。\n\n---\n\n**通用收尾三连**（所有场景通用）：\n\n```bash\npython scripts/verify.py 原稿 新稿 --terms terms.txt # exit 0 才算过\npython scripts/compare.py 原稿 新稿 # 特征下降+完整性\npython scripts/stylecheck.py 原稿 新稿 --compare # 画像差值\n```\n\n如学校/期刊要求 AI 使用披露，请如实声明——本工具箱是质量自查记录，\n不能替代披露。\n\nFile v3.1.0:references/compliance.md\n\n# 使用边界与合规须知（学术诚信护栏）\n\n> 本工具改善的是**文字质量**。它不改变内容由谁创作的事实，也不能替代你对学校、\n> 期刊、平台规则的遵守义务。请先读这一页再用。运行本技能的 agent 应把本页作为\n> 行为守则执行。\n\n## 一、正当使用场景\n\n1. **润色自己的稿件**：行文生硬、模板腔重、翻译腔明显的正式文体，按写作质量原则\n 深改（清晰、节奏、具体性、立场）。\n2. **非母语（ESL）作者的自查**：正式学术文体经常被自动化评审误判；被误判的真实\n 作者用本工具做风格自查，理解哪些写法显得机械并改进它们。\n3. **合规披露前提下的 AI 辅助文本对齐**：你用 AI 起草、自己核实并修改了内容，\n 按所在场景规则**已获准/已披露**使用 AI——本工具帮你把行文打磨到与你的写作\n 习惯一致。\n4. **清理模型残留**：粘贴 AI 输出带进来的 oaicite/[cite:]/turn0search 等技术垃圾\n 与半角标点、Markdown 残留等机械问题。\n\n## 二、明确拒绝的场景（agent 行为守则）\n\n以下请求应**拒绝该目的**、说明披露义务，并转而提供正当的质量改写路径：\n\n- 「改到没人看得出来是不是 AI 写的」「帮我瞒过学校的 AIGC 检测」——以规避\n 学术诚信审查为目的的改写；\n- 隐瞒学校、期刊（ICMJE 等国际编辑规范）、arXiv 等平台**要求披露**的 AI 使用；\n- 伪造、移除或规避官方 AIGC 内容标识（水印/隐式标识）；\n- 为他人代写并包装为本人原创。\n\n学校对学位论文的 AIGC 规定、期刊的 AI 使用披露政策、arXiv 的披露要求——这些\n规则的义务主体是作者本人，工具无法替你履行披露义务，也不应被用来规避它们。\n\n## 三、AI 使用披露自查清单（提交前过一遍）\n\n- [ ] 目标学校/期刊/平台是否要求披露 AI 辅助？（查 author guidelines；默认「要求\n 或即将要求」）\n- [ ] AI 承担了什么角色（起草/润色/翻译/数据分析）？是否在 methods 或\n acknowledgments / disclosure 段如实说明？\n- [ ] 内容是否经过本人核实（引用真实存在、数据来自你的实验、结论你认同）？\n- [ ] 作者责任：所有作者对全文内容负责，AI 不满足作者资格标准（ICMJE）。\n- [ ] 中国境内发布场景：《人工智能生成合成内容标识办法》及配套国标\n （GB 45438-2025，2025-09-01 施行）对 AI 生成合成内容的显式/隐式标识义务\n 在「服务提供者」与特定场景的传播者；个人写作辅助通常不触发，但\n **发布/传播环节**请自行确认平台要求。本工具不添加、不伪造、不移除任何\n 官方标识。\n\n## 三之一、水印趋势备注（2026）\n\n水印与来源标识正在成为监管方向：欧盟《人工智能法案》第 50 条（面向 AI 提供者的\n机器可读标识义务）正在推动合成内容可识别，主流模型厂商已陆续部署文本水印。本工具的立场保持不变：**不添加、不伪造、\n不移除任何官方或厂商的内容标识与水印**——这些标识的完整性属于内容溯源体系，\n风格改进不触及也不应触及它们。\n\n## 四、工具边界\n\n- 本地启发式风格评分只是对写作模式的统计描述，不代表任何外部服务的测量，\n 更不说明文字由谁写成——不要把它当成那种证据展示。\n- 降特征不等于合规：风格改进与诚信合规是两件事，后者只能靠披露与核实。\n- 被误判的作者请保留草稿、版本历史与写作笔记——署名问题靠过程证据解决，\n 不靠风格分数；这也是 Wikipedia AI 清理项目的公开立场。\n\n## 五、给机构用户的建议\n\n- 用本工具做**投稿前/提交前**的风格自查与残留清理，而不是用来对抗检测评审。\n- 对被误判的学生/作者，先做写作过程核查（草稿、版本历史、口头答辩）。\n\n如你的场景规则与本页冲突，以你的场景规则为准。\n\nFile v3.1.0:references/deep_rewrite_guide.md\n\n# 深改操作手册：从计划到验收的执行循环（v3.0.0）\n\n> EN summary: this is the *operational* layer of deep rewriting — how to turn a\n> `plan.py` diagnosis into a bounded, verifiable rewrite session. Style rules\n> live in `style_guide_zh.md` / `style_guide_en.md`; this sheet defines the\n> process: plan → handoff → per-sentence rewrite → verify cadence → acceptance.\n\n## 为什么需要这一页\n\n真实使用反馈与深改实操复盘一致指出：本工具的深改环节由 agent/作者完成，而「怎么把\n深改做扎实、可验收」缺一张操作层面的流程页——风格指南管「怎么改」，本页管\n「按什么顺序改、改到什么程度停、怎么证明没改坏」。\n\n## 执行循环（五步，可多轮）\n\n```\n① 计划 python scripts/plan.py draft.txt --top 15 -o plan.md\n ↳ P0 句级队列（章节归属+命中类别+处理原则+预算投影）\n② 交接 python scripts/plan.py draft.txt --top 15 --handoff\n ↳ 深改交接块：逐句「原句+操作指令」，含守卫铁律与验收命令\n③ 逐句深改 按交接块顺序改——每句只做指令列出的操作，不顺手加戏\n④ 校验节拍 每改 3-5 句：python scripts/verify.py draft.txt step2.txt --terms terms.txt\n ↳ 任一 GUARD/ERROR → 回滚该句，改法降级（整句重写→局部替换）\n⑤ 收口 python scripts/compare.py draft.txt step2.txt\n python scripts/stylecheck.py step2.txt --compare draft.txt\n ↳ 量化验收：特征下降 + 完整性 PASS + 画像档位改善\n```\n\n## 每句怎么改（操作优先级）\n\n1. **删除优先**：八股开场（众所周知/综上所述/值得注意的是）、聊天客套、知识\n 截止声明——直接删，不需要替身。\n2. **合并次之**：「不仅X，而且Y」→「X，且Y」；同主语短句合并（`--deep` 可代劳\n 确定性部分）。\n3. **替换第三**：黑话/翻译腔按 style_guide 对照表换具体词；一处一换，不连锁改。\n4. **重写最后**：前三步救不回来的句子才整句重写——重写句必须通过\n `verify.py` 的数字/术语守卫才算完成。\n\n## 停止条件（防过度改写）\n\n- 预算投影显示再改 K 句预期收益 < 2 分 → 停（边际收益归零）。\n- 一句话改了 3 稿仍不达标 → 保留最好的一稿，标记「人工再读」，不要死磕。\n- 全文特征分进入目标档位（compare 确认）→ 停。剩余长尾交给作者本人。\n\n## 与其他件的分工\n\n| 问题 | 去处 |\n|---|---|\n| 某类模式具体怎么改 | `references/style_guide_zh.md`（EN 用 `_en.md`） |\n| 句子怎么排优先级/预算投影 | `plan.py`（`--json` 给 agent 消费） |\n| 交接块格式 | `plan.py --handoff` 直接产出 |\n| 数字/引用/术语守卫 | `verify.py`（exit 0 才算过） |\n| 量化验收 | `stylecheck.py 改稿 --compare 原稿` |\n| 七类场景的完整打法 | `references/best_practices.md` |\n\nFile v3.1.0:references/errors.md\n\n# 错误码与处置速查（Error Codes Reference）\n\n> 全部 CLI 脚本的退出码、违规/告警类别、触发条件与处置动作的统一映射表。\n> 程序化集成请以 `verify.py` 的退出码为契约（见下表）；其余脚本把判定写在输出里。\n\n## 一、退出码（CLI 契约）\n\n**缺省口径**（不带 `--exit-verdict`，人读/人工流程）：\n\n| 退出码 | 脚本 | 含义 | 处置 |\n|---|---|---|---|\n| 0 | 全部 | 完成（verify: 完整性 PASS） | 正常继续；其余脚本的判定读输出报告 |\n| 1 | **仅 verify.py** | 完整性守卫 FAIL——改稿动了数字/引用/术语 | **修改改稿**，不是改守卫、不是换参数 |\n| 2 | 全部 | 用法或文件错误 | 看 stderr 提示：路径错/文件空/二进制/编码/超限，每条提示自带处置建议 |\n| 1 | check_terms.py（独立口径） | 发现术语不一致（报变体对与次数） | 按「建议统一为」人工统一；`--report` 出 markdown 明细 |\n\n> pipeline.py / compare.py 的守卫判定在输出报告的「完整性守卫: PASS/FAIL」行；按退出码分支的脚本请调 verify.py。check_terms.py 的 0/1/2 是自己的契约（0=一致），与 verify 的 1=FAIL 语义不同表，勿混用。\n\n**自动化口径**（v2.3.0：detect/compare/pipeline 加 `--exit-verdict` 后）：\n\n| 退出码 | 含义 | 典型 CI 动作 |\n|---|---|---|\n| 0 | 干净（低档、无残留；pipeline 另含完整性 PASS） | 合并/继续 |\n| 1 | 完整性守卫 FAIL（仅 pipeline 会产出；与 verify 契约同义） | 拒绝该改稿，回给 agent 重改 |\n| 3 | 风格特征中及以上（≥28，需要深改） | 进深改队列（plan.py 排优先级） |\n| 4 | 命中模型残留（critical） | 先跑 transform.py 清理 |\n| 2 | 用法/文件错误（不受 --exit-verdict 影响） | 修调用 |\n\n> detect/compare 的 `--exit-verdict` 只出 0/3/4（完整性仍只写报告——exit 1 契约专属 verify/pipeline）；\n> **pipeline 是唯一 1/3/4 全档判定命令**，CI 门禁推荐 `pipeline.py 原稿 --rewrite 改稿 --exit-verdict`。\n\n## 一B、集中异常层（v2.5.0）\n\n全部 CLI 的 `__main__` 统一经 `hxt_core.cli_entry(main)` 进入：任何用户侧\n异常输出**两行中文**——「错误: <发生了什么>」+「处置建议: <怎么办>」——并以\nexit 2 结束。`CliError(msg, hint)` 是脚本内主动报错的规范方式；SystemExit\n原样穿透，各脚本语义化退出码不受影响。程序内部 bug 仍带完整 traceback\n冒出（宁可吵，不可吞）。\n\n## 二、verify.py 违规类别（exit 1 = violations；WARN = 告警继续）\n\n| 类别 | 级别 | 含义 | 常见原因与处置 |\n|---|---|---|---|\n| numbers | E_NUM_LOST | ✗ 红线 | 数字丢失/被改 | 深改时把数据句改写了——恢复原数字或重写该句 |\n| comparison | E_CMP_FLIP | ✗ 红线 | 比较方向被改（P<0.05→P>0.05 级） | 结论方向反转，必须恢复原文方向 |\n| doi / pmid | ✗ 红线 | DOI / PMID 丢失 | 引用被删或改写——恢复 |\n| latin_abbr | E_ABBR_LOST | ✗ 红线 | 大写缩写丢失（DNA/PCR 类） | 缩写被中文化或删除——恢复原缩写 |\n| terms | E_TERMS_LOST | ✗ 红线 | 术语表条目缺失/减少 | 术语被替换——恢复，或把该词从术语表移除（若确认非术语） |\n| cjk_ratio | E_CJK_SHIFT | ✗ 红线 | 中英占比漂移超阈 | 整段被删或被译——检查是否误删段落 |\n| length | E_LEN_DRIFT | ✗ 红线 | 长度变化超阈（长文 ±25%，短文放宽） | 内容被整段删除——核对删减是否有意 |\n| fullwidth | E_NUM_WIDTH | ✗ 红线 | 数字/字母被改写为全角（２０２５≡2025 值等价但字符已变；v2.8.0） | 中文输入法所致——全部改回半角后重跑（学术稿件必须半角） |\n| numbers_added | W_NUM_ADDED | ⚠ 告警 | 出现原稿没有的数字 | **编造防线**：深改时凭空补的数字必须删除 |\n| number_context | W_CTX_SWAP | ⚠ 告警 | 数字上下文/顺序变化 | 两臂互换/方位错位——人工核对方向 |\n| sentences_added | W_SENT_ADDED | ⚠ 告警 | 改稿新增原稿没有的完整句（≥8 字符，无数字也提示；v2.8.0） | 逐句核对是否擅自加内容（编造防线的一部分） |\n| years | W_YEARS | ⚠ 告警 | 年份数量变化 | 年份引用被删——核对 |\n\n阈值均可 CLI 覆盖：`--max-length-change`、`--max-cjk-shift`。\n\n## 三、退出码 2 的常见触发与处置\n\n| 触发 | 提示关键词 | 处置 |\n|---|---|---|\n| 文件不存在 | 无法读取 | 核对路径（相对路径基于技能目录） |\n| 输入为空 | 输入为空 | 文件无内容或只传了空白 |\n| 二进制文件 | 疑似二进制（含 NUL 字节） | 转存 UTF-8 纯文本；Word 用 .docx 直读 |\n| 编码错误 | 乱码占比过高 | 文件是 GBK/UTF-16 等——转存 UTF-8 |\n| 文件超限 | 超过 50MB 上限 | 拆分文件分批处理 |\n| docx 缺部件 | 缺少正文部件 | 可能只是改了扩展名——另存为真正 .docx |\n| docx 加密 | 受密码保护 | 解除密码后另存 |\n| 参数错误 | argparse 提示 | `--help` 查看合法取值（如 --profile academic/general） |\n\n## 四、detect/pipeline 报告中的级别\n\n| 级别 | 含义 | 建议 |\n|---|---|---|\n| 低（0-27） | 基本无模板腔特征 | 无需处理 |\n| 中（28-49） | 有一定模板腔 | 可按 style_guide 选择性处理 |\n| 高（50-74） | 模板腔特征明显 | 按 style_guide 深改 |\n| 极高（75+ 或含硬残留） | 特征极重/含模型残留 | 先 transform.py 清硬残留，再按指南深改 |\n\n分数口径：本地启发式风格诊断，非任何官方检测分数；短文本（<15 单元）自动降权并标注「仅供参考」。\n\nFile v3.1.0:references/examples.md\n\n# 完整输入输出样例（End-to-End Examples）\n\n> 每个样例 = 真实命令 + 真实输出（来自回归语料，可复现）。样例中的数字/事实仅用于演示格式。\n\n## 样例 1：中文改写全流程\n\n**输入** `draft.txt`（节选，模板腔密集）：\n\n```\n综上所述，智慧医疗作为一项新兴范式，正在为整个行业赋能。一方面，它能够整合海量医疗数据，为临床决策提供新的思路；另一方面，它还可以优化资源配置，为分级诊疗制度的落地保驾护航。\n```\n\n**Step 1 自查**：\n\n```console\n$ python scripts/detect.py draft.txt\n==============================================================\n写作风格特征自查（本地启发式 · 非任何官方检测分数）\n==============================================================\n文件: draft.txt\n语言: 中文 | 规模: 216.5 单元 / 13 句\n\n综合评分: 58/100 [高]\n...\n改写建议(前10条):\n · 「赋能」→ 「支持 / 帮助 / 为…提供能力」\n · 「抓手」→ 「工具 / 途径 / 切入点」\n```\n\n**Step 2 机械清理**（本例无模型残留/客套句，清理近零改动——正常）：\n\n```console\n$ python scripts/transform.py draft.txt -o step1.txt\n{\n \"applied_fixes\": {\"半角逗号→全角\": 2},\n \"removed_sentences\": [],\n \"note\": \"机械清洗只覆盖语法安全层；黑话/八股/节奏需 agent 按指南深改，...\"\n}\n```\n\n**Step 3 深改**（agent 按 `references/style_guide_zh.md` 七步法执行，改后节选）：\n\n```\n智慧医疗的价值集中在两处：把分散的病历、影像和检验数据汇到一起供临床调用，以及让上级医院的诊断能力透过远程会话下沉到基层。前者的瓶颈是数据标准，后者是责任认定——这两点不解决，分级诊疗借不上智慧医疗的力。\n```\n\n**Step 4+5 守卫与对比**：\n\n```console\n$ python scripts/verify.py draft.txt step2.txt --terms terms.txt\n完整性守卫 verify：PASS ✓\n 数字/DOI/PMID/缩写/术语 全部保全。\n\n$ python scripts/compare.py draft.txt step2.txt\n风格特征分: 58 [高] → 12 [低] （-46）\n完整性守卫: PASS ✓\n```\n\n## 样例 2：英文模型残留清理 + 守卫拦截\n\n**输入** `ai_paste.txt`（从聊天窗口粘贴的稿子，带残留与客套句）：\n\n```\n综上所述，本研究纳入 128 例患者，其中 68 例进入试验组（p = 0.031）。\n值得注意的是，两组基线具有可比性 [cite: 1][cite: 3]，随访 24 个月。\n希望以上内容对您有所帮助！如需进一步修改请告诉我。\n```\n\n**一键管线**：\n\n```console\n$ python scripts/pipeline.py ai_paste.txt -o clean.txt\n==============================================================\n一键管线报告（机械清理）\n==============================================================\n风格特征分: 47 [中] → 18 [低]\n完整性守卫: PASS ✓\n 数字/DOI/PMID/缩写/术语 全部保全。\n深改任务简报:\n 指南: references/style_guide_zh.md\n · 剩余特征: 学术八股（人写也有，看密度） ×3\n 下一步: agent 按 references/style_guide_zh.md 对 clean.txt 做深度改写（保护数字/引用/术语），然后重跑本命令 --rewrite 改稿文件复核\n口径: 本地启发式风格特征评分，非任何官方检测分数\n```\n\n清理效果：`[cite: 1][cite: 3]` 行内摘除（句子保留）、客套句整句移除、数字 128/68/0.031/24 全部原样。\n\n## 样例 3：完整性守卫拦截演示（守卫不讲价）\n\n```console\n$ python scripts/verify.py 原稿.txt 改稿.txt\n完整性守卫 verify：FAIL ✗（学术安全红线）\n ✗ [numbers] 数字丢失/被改: 62\n ✗ [comparison] 比较方向/比较数字被改: <0.05\n判定: 未通过——请修复改稿后重跑\n$ echo $?\n1\n```\n\n改稿把「血沉 62mm/h」改成 58、把「P<0.05」改成「P>0.05」——无论措辞多流畅，exit 1。修的是改稿，不是守卫。\n\n## 样例 4：术语保护（正当学术用法不误报）\n\n```console\n$ python scripts/detect.py -s\nThe mutational landscape was profiled in this pivotal trial; robust regression confirmed the effect. (×3)\n6/低\n```\n\nmutational landscape / pivotal trial / robust regression 全部豁免；换成 \"the startup landscape ... plays a pivotal role\" 这类非学术语境则正常计分。\n\n## 样例 5：markdown 稿件全链路（v2.2.0：章节感知 + 句级计划 + 守卫拦截）\n\n**输入** `case_medical.md`（markdown 医学综述，模板腔密度中等）。v2.2.0 起\n`## 摘要`/`## 方法` 等 markdown 标题直接进章节感知，.md 语法残留自动豁免。\n\n**Step 1 自查 + 章节感知**：\n\n```console\n$ python scripts/detect.py case_medical.md --structure\n章节: 题引 / 摘要 / 引言 / 方法 / 讨论 / 结论（markdown 标题逐一识别）\n综合评分: 23/100 [低]\n · 学术八股（人写也有，看密度） 9 处 （综上所述 / 值得注意的是 / 众所周知…）\n · 排比/对仗结构（一方面…另一方面） 1 处\n节奏统计: 句长变异系数 0.62 | 连接词 0.41/句\n```\n\n**Step 2 改写优先级计划**（v2.2.0 新增，先定位再动手）：\n\n```console\n$ python scripts/plan.py case_medical.md --json\nP1 [结论] 2.2点 「…从而为临床决策的落地保驾护航。」\nP2 [引言] 0.9点 「众所周知，IRAK4在Toll样受体…」\nP3 [摘要] 0.8点 「取得了显著进展，为新型治疗策略的开发…」\n预算投影: 改完前5句→11 | 前10句→4 | 全部→2 （线性近似，仅供排序）\n```\n\n**Step 3 agent 深改**（按 style_guide 改 P0 队列，事实全保留：1/250000、\n48 篇、2005-2026、8 例/12 个月）。\n\n**Step 4 守卫拦截过度删减**——第一版深改把 IRAK4 从 12 次引述压到 11 次：\n\n```console\n$ python scripts/verify.py case_medical.md case_medical_v2.md\n ✗ [numbers] 数字丢失/被改: 4 ← IRAK4 里的 4 连带丢失\n ✗ [latin_abbr] 大写缩写丢失: IRAK4\n判定: 未通过——请修复改稿后重跑（exit 1）\n```\n\n补回自然引述（「IRAK4抑制剂的耐药机制」）后重跑：\n\n```console\n$ python scripts/verify.py case_medical.md case_medical_v2.md\n判定: 通过（exit 0）| 规模 694 → 609 字符\n\n$ python scripts/compare.py case_medical.md case_medical_v2.md\n 学术八股 已清除 9 处\n 翻译腔/空泛过渡 已清除 4 处\n 中文 AI 黑话 已清除 2 处\n 排比/对仗结构 已清除 1 处\n完整性守卫: PASS ✓\n```\n\n**要点**：markdown 章节直接被识别；plan 把深改力气指向贡献最大的句子；\nverify 连「缩写次数被压低」都能抓到——守卫拦的是内容损失，不是措辞。\n\n## 样例 6：误报 → 守卫固化（v2.2.0 learn_guards）\n\n「抓手」在词表里是营销黑话，但机械工程语境的「机械抓手」是正当术语——\n守卫按上下文豁免，不是整词洗白：\n\n```console\n$ echo \"装配平台的机械抓手采用气驱动设计，抓取力可调。\" | python scripts/detect.py -s\n46/中 ← 误报\n\n$ python scripts/learn_guards.py add 抓手 --before \"机械,装置\" --after \"采用,夹持\"\n已保存守卫：抓手（lang=zh，前文 2 项 / 后文 2 项）\n\n$ echo \"装配平台的机械抓手采用气驱动设计，抓取力可调。\" | python scripts/detect.py -s\n0/低 ← 机械语境豁免\n\n$ echo \"以创新为抓手，全面赋能业务增长。\" | python scripts/detect.py -s\n35/中 ← 营销语境照常计分（对照）\n```\n\n守卫存进 `scripts/user_guards.json`（升级词表不丢）；`list` 查看、\n`remove 抓手` 撤销、`from-text 术语 样本.txt` 从真实语料自动提取上下文\n（中英双语口径）。强制要求 `--before/--after` 上下文——纯词白名单会被拒绝。\n\n## 样例 7：CI/agent 门禁——机器退出码（v2.3.0 --exit-verdict）\n\n把改稿质量卡进自动化流程：改稿不达标就拦截，不需要人读报告。\n\n```console\n$ # 坏改稿：改稿=原稿（一句没改），门禁应拦截\n$ python scripts/pipeline.py draft.txt --rewrite draft.txt --exit-verdict\n$ echo $?\n3 ← 风格特征中及以上（52/高），进深改队列\n\n$ # 好改稿：事实保留、模板腔清除，门禁放行\n$ python scripts/pipeline.py draft.txt --rewrite rewritten.txt --exit-verdict\n完整性守卫: PASS ✓\n$ echo $?\n0\n\n$ # JSON 里的同源字段（agent 管线直接读）\n$ python scripts/pipeline.py draft.txt --rewrite draft.txt --json | jq .exit_verdict\n3\n```\n\n退出码全表（0/1/3/4/2 两套口径）：`references/errors.md` 第一节。\n`detect --exit-verdict` / `compare --exit-verdict` 只出 0/3/4——完整性 FAIL\n的 exit 1 契约专属 verify.py 与 pipeline。\n\n## 样例 8：确定性深改档（v2.4.0 --deep）+ 处置提示\n\n**输入**（模板腔中文段落）：\n\n```\n综上所述，本研究验证了假设。值得注意的是，该方法不仅提升了精度，而且降低了成本。众所周知，数据见第3.2节，p=0.03。\n```\n\n**transform --deep（句式级确定性转换，--track 可审计）**：\n\n```console\n$ python scripts/transform.py in.txt -o out.txt --deep --track track\n深改档: 句首八股删除 ×3\n深改档: 排除式连接合并 ×1\n\n$ cat out.txt\n本研究验证了假设。该方法提升了精度，且降低了成本。数据见第3.2节，p=0.03。\n```\n\n**守卫确认零损失**：\n\n```console\n$ python scripts/verify.py in.txt out.txt\n 数字/DOI/PMID/缩写/术语 全部保全。\n判定: 通过\n```\n\ntrack.md 里每笔深改操作独立可查（`深改档:句首八股删除 ×3`）。\n--deep 只做零信息损失操作（删纯套话标记/拆排除式连接）；黑话替换、\n节奏重排、立场重写仍由 agent 按指南执行——两层互补，不互相替代。\n\n**处置提示（v2.4.0，报告尾部 + JSON hints 字段）**——非论文文体自动建议切 profile：\n\n```console\n$ python scripts/detect.py blog_post.txt\n…\n处置提示:\n → 深改排序：python scripts/plan.py <文件> -o plan.md 生成句级优先级计划\n → 未识别到论文章节且特征以标点/翻译腔为主——非论文文体（博客/公文/通知）\n 可加 --profile general 降权八股信号\n```\n\n## 样例 9：集中异常层 + 批量重试 + 单步超时（v2.5.0）\n\n**两行中文错误（错误 + 处置建议）**——所有 CLI 统一格式，非技术用户也能照着做：\n\n```console\n$ python scripts/detect.py photo.png\n错误: 输入疑似二进制文件（含 NUL 字节）——请转存为 UTF-8 纯文本（.txt/.md）再处理\n```\n\n**批量二遍重试**——首遍失败的文件自动以双倍时间预算重扫一次，瞬时故障\n（负载抖动导致超时等）第二遍即恢复；真坏文件如实标注\"已重试\"：\n\n```console\n$ python scripts/detect.py --batch ./papers\n[重试] 二遍扫描：1 个失败文件重试，0 个恢复\n a.txt 0/低\n broken.txt 错误: 输入疑似二进制文件…（已重试 1 次）\n```\n\n`--json` 输出逐文件携带 `retried` 字段（true=重试后成功）。\n\n**单步超时与耗时透明**——`--step-timeout`（缺省 120 秒）管住清理与扫描\n每一步，超时干净报错；JSON 报告新增 `timings`：\n\n```console\n$ python scripts/pipeline.py draft.txt -o out.txt\n耗时: 清理 0.0s | 扫描 0.1s | 守卫 0.0s（合计 0.2s，单步预算 120 秒）\n\n$ python scripts/pipeline.py draft.txt -o out.txt --json | jq .timings\n{ \"cleanup_s\": 0.0, \"scan_s\": 0.11, \"verify_s\": 0.0, \"total_s\": 0.11 }\n```\n\n## 样例 10：风格画像——深改的量化验收（v2.6.0 stylecheck）\n\n**单文件画像**（AI 语料演示，黑话命中定位到段）：\n\n```console\n$ python scripts/stylecheck.py draft.txt\n| 指标 | 值 | 档位 |\n|---|---|---|\n| 黑话密度（每千字） | 36.81 | 偏机器 |\n| 句长变异系数 | 0.388 | 自然 |\n| 最高频句首占比 | 0.077 | 自然 |\n| 最长连续同开场 | 1 | 自然 |\n\n## 重点段落（黑话命中降序）\n- 第 1 段（104 字/3 句，命中 4）：赋能 → 支持 / 帮助 / 为…提供能力\n- 第 2 段（112 字/4 句，命中 5）：保驾护航 → 保障 / 支持\n- 第 4 段（126 字/2 句，命中 5）：抓手 → 工具 / 途径 / 切入点\n```\n\n**--compare 验收差值**（AI 语料 → 人写语料的演示对比，深改实际效果介于其间）：\n\n```console\n$ python scripts/stylecheck.py 原稿.txt 改稿.txt --compare\n| 黑话密度（每千字） | 36.81 | 0.0 | 偏机器 → 自然 |\n黑话命中合计：18 → 0（-18）\n```\n\n档位阈值用本地语料校准（AI 语料黑话密度 17-37/千字 vs 人写 0），只做验收\n提示、不改评分；改稿完整性仍以 verify.py 为准。深改验收闭环：\nplan.py 排队列 → agent 按指南改 → --compare 看画像差值 → verify 过守卫。\n\n\n## 样例 11：--terms auto 与画像 HTML（v2.7.0）\n\n```console\n$ python scripts/pipeline.py manuscript.txt -o clean.txt --terms auto\n[术语] 术语表=自动草稿 clean.terms.auto.txt（12 条，未经人工确认）——正式稿件建议人工过一遍后重跑\n\n$ python scripts/pipeline.py manuscript.txt -o clean.txt --terms auto --json | jq .terms_note\n\"术语表=自动草稿 clean.terms.auto.txt（12 条，未经人工确认）——…\"\n\n$ python scripts/stylecheck.py clean.txt --html profile.html\nHTML 画像报告已写入 profile.html\n```\n\nCJK 相邻缩写抽取修复（v2.7.0）：`IRAK4抑制剂` 里的 IRAK4 此前因 \\b 在汉字旁\n失效而抽不到——与 verify.py v2.1.0 同族问题，本版统一为 CJK 安全 lookaround。\n\nFile v3.1.0:references/faq.md\n\n# 常见问题 FAQ（含迁移指引）\n\n> 覆盖评测与用户反馈中的高频问题。没找到答案时，先跑 `python scripts/pipeline.py 你的文件 -o out.txt` 看报告，再按报告里的指南深改。\n\n## 基础\n\n**Q0：第一次用，最容易踩的坑？**\n读 `references/pitfalls.md`——24 条集中式常见错误清单（参数误用/编码事故/守卫\n误读/流程合规），每条带正确做法。TL;DR：跑 pipeline → 读报告 → 按指南深改 →\nverify → compare。\n\n**Q1：这个工具和 paper-polisher-pro 什么区别？**\npaper-polisher-pro 是综合润色工具箱（术语、翻译腔、比喻审计、AIGC 标识合规、期刊预检），本工具专攻「风格自然化」一件事：风格特征自查 → 机械清理 → 深改简报 → 完整性守卫。两者可同时使用互不冲突——先本工具去模板腔，再 paper-polisher-pro 做全稿润色。\n\n**Q2：报告里的分数是检测器分数吗？**\n不是。分数是对写作模式（套话密度、句长均匀度、模板结构）的本地启发式统计，不代表任何外部服务的测量结果，更不说明文字由谁写。详见 SKILL.md「诚实边界」。\n\n**Q3：支持什么文件格式？**\n纯文本（.txt）、Markdown（.md）、**Word（.docx）**、以及 **PDF（v1.6.0 起实验性\n直读，限英文文本型；加密/扫描件拒收，CJK/嵌入字体尽力识别并拒收、可能漏网——\n抽取结果请人工检查）**。stdin 也支持：\n`echo \"文本\" | python scripts/detect.py`。\n\n**Q4：会改坏我的数据吗？**\n机械清理层设计上不触碰数字/引用；深改层由 agent 按指南执行，改完必须过 `verify.py`——数字、统计量、DOI、PMID、年份、缩写、术语表任何丢失都会 exit 1。守卫还会对「凭空新增的数字」告警（编造防线）。历史实测：改写中 p 值篡改、两臂互换、整句含电话号码误删，全部被守卫拦截过。\n\n## 使用\n\n**Q5：一定要跑四个脚本吗？**\n不用。`python scripts/pipeline.py draft.txt -o out.txt` 一条命令跑完自查→清理→守卫→报告。多脚本入口是为需要单独调用某一步的场景保留的。\n\n**Q6：术语表（--terms）怎么准备？**\n先跑 `python scripts/extract_terms.py 原稿 -o terms.txt` 自动生成草稿（大写缩写、\n书名号/引号内术语按频次排序），人工删改后使用。每行一个术语，`#` 开头是注释。\n医学文本建议补充：药名（含商品名）、基因符号（鼠源首字母大写形态如 Myc 也要列）、\n量表名、仪器名。不提供术语表时，守卫仍查数字/DOI/PMID/年份/全大写缩写。\n\n**Q7：退出码怎么看？**\n`verify.py` 是严格契约方：`0`=完整性 PASS、`1`=完整性 FAIL（有数字/引用/术语被动过——修改改稿，不是改守卫）、`2`=用法或文件错误。`detect/transform/compare/pipeline` 把判定写在输出报告里，完成即返回 `0`（用法/文件错误 `2`）——按退出码分支的脚本请以 verify.py 为准。所有脚本支持 `--version`。\n\n**Q8：检测误报了正当术语怎么办？**\n两层解决：①词表自带术语保护（mutational landscape、pivotal trial、robust regression、序列对齐、沉淀反应、心室重塑、串联质谱等已豁免）；②仍误报的，在 `scripts/patterns_*.json` 的 `term_guards` 加一条你的搭配（allow_before/allow_after），并欢迎反馈补充词表。\n\n**Q9：分数多少算\"有问题\"？**\n0-27 低（正常）；28-49 中（有模板腔，可改可不改）；50+ 高（建议按指南深改）；报告会给出具体剩余特征清单。分数是密度统计，短文本（<15 单元）自动降权并标注\"仅供参考\"。\n\n## 迁移（自旧版页面）\n\n**Q10：我是从旧版页面过来的，有变化吗？**\n功能全集在这里且只增不减：旧版全部能力（双语自查/机械清理/深改手册/完整性守卫/前后对比）+ v1.1.0 新增（一键管线 pipeline.py、FAQ、完整示例、错误码体系）。旧页与本页同源同版本维护。\n\n**Q11：旧页和新页内容一致吗？版本号什么关系？**\n内容完全一致，同一份代码库双页发布，版本号两页保持同号（如两页同时是 v1.2.0）；仅某一页需要追修时该页用 x.x.1 子版本号。过渡期例外：旧页因迁移历史存在 +0.0.1 偏移（如本页 v1.1.0 对应旧页 v1.1.1）。以后更新认准 **paper-rewriter**（本页）；旧页永久保留作为入口。\n\n**Q12：旧版评分 3 分是怎么回事？**\n那是平台对「迁移说明占位页」的评分（页面只有搬家通知，没有功能），不代表工具本身——本页 v1.0.0 实测均分 4.55（trust 维 5.0）。\n\n## 边界\n\n**Q13：能保证某种评审结果吗？**\n不能，也不承诺。本工具改善写作质量与自然度；任何承诺「保证不被判为机器生成」的服务都不可信。合规义务（AI 使用披露）在作者本人，见 references/compliance.md。\n\n**Q14：多大文本算\"太大\"？**\nv1.4.0 起不再需要手动切分：detect/pipeline 对超 1MB 文本**自动分块**处理（按段落\n边界，报告会标注分块口径与块数），内存峰值恒定。注意完整性守卫（verify.py）始终\n整文比对——这是红线语义，不可分块。\n\n**Q14c：--structure 的章节降权会不会帮作者\"藏住\"方法段的机器味？**\n不会。降权只归一综合分（方法段的固定句式是领域惯例，公平计量）；各章节原始分\n仍在报告中逐项展示，任何人都能看到完整数据。「藏匿」不是本工具的设计，也\n不符合它的诚信立场（见 compliance.md 拒绝清单）。\n\n**Q14b：报告能导出成网页吗？能一次扫整个目录吗？**\n都能。`--html report.html` 生成单文件 HTML（无外链可直接存档/转发）；compare 的\nHTML 含逐句增删对照，复核改稿最直观。批量：`--batch 目录名` 一次扫全部\n.txt/.md/.docx/.pdf（detect 出逐文件评分，pipeline 逐文件清理+守卫汇总 CSV）。\n\n**Q14a：transform 的激进模式（-a）什么时候用？**\n适合：非正式文本的破折号堆叠、空泛开场白清理。不适合：学术方法段的插入语破折号、\n任何将直接提交的文本（改完必须人工复核）。普通模式（不带 -a）已经能清模型残留、\n客套句、标点与安全填充语——先跑普通模式看报告再决定要不要 -a。\n\n**Q15：博客/公众号/公文这类非学术文本，评分偏高怎么办？**\n用 `--profile general`：学术八股和公文过渡语在人写的非学术文本里是常态，general\n模式把这些信号降权 60%（黑话、模型残留、节奏信号不受影响）。默认 `academic`\n始终按学术论文口径标定，处理论文时不需要加参数。\n\n**Q16：这个工具会联网吗？会读我的其他文件吗？**\n不会、不会。全部脚本仅 Python 标准库、零网络请求；只读取你作为参数传入的文件，\n只写入你用 `-o`/`--suggestions`/`--html`/`--track` 指定的输出路径；不读环境变量、不创建子进程和定时任务。\n详见 SKILL.md「权限与环境声明」。\n\n**Q17：2026 年了，检测技术都在进步，这套\"质量优先\"路线还成立吗？**\n更成立了。公开研究显示：①单纯同义转写并不能让文字变好——质量优先路线的\n价值不随工具演进贬值；②节奏与结构层面的建议之所以有效，是因为它们让文字\n回归真实写作的质量，本工具不以任何外部产品为目标或参照；③正式学术文体被\n自动化评审误判仍是行业痛点——被误判的真实作者依然是第一等用户。质量优先\n是写作本身的标准，长期成立。\n\nFile v3.1.0:references/pdf_confidence.md\n\n# PDF 抽取置信度：分层口径与真实语料校准（v3.0.0）\n\n> EN summary: PDF direct-read is experimental. v3.0.0 replaces the blanket\n> ToUnicode-CMap rejection with a graded confidence ceiling: extraction is\n> attempted for all unencrypted text PDFs, hard gates stay on the three\n> garbage probes (control-char rate / GBK round-trip / U+FFFD ratio), and the\n> ToUnicode presence caps \"高\" at \"中\" with a spot-check note. Calibration on\n> 200 real-world PDFs: 98.0% (196/200) correctly rejected, all 4 passes honestly\n> labeled.\n\n## 一、三层判定流水线\n\n```\n.pdf 输入\n ├─ ① 硬闸（拒绝即报错，给可执行出路）\n │ 加密 /Encrypt → 「解除密码或导出 UTF-8」\n │ 无文本流（扫描件）→ 「用 OCR 或导出 UTF-8」\n │ 解压预算超限（单流 20MB / 累计 50MB）→ 「拆分」\n ├─ ② 乱码三探针（最坏失败态=乱码静默放行，必须拦）\n │ 控制字符率 >0.5% / GBK 回程 CJK >20% / U+FFFD >2%\n └─ ③ 置信度分层（只标注不拦截；indicators 随 pdf_meta/JSON 透出）\n 高：常用词命中率 ≥25% 且 控制字符 <0.3% 且 词均长 3-9\n 低：命中率 <8% 或 词均长 >14 或 可抽词 <30\n 中：其余（可用，建议抽查）\n 附加：源 PDF 含 ToUnicode CMap（嵌入字体标记）→ 「高」封顶为「中」并注明\n 「字体子集存在字面替换风险，建议抽查关键数字与术语」（v3.0.0 校准）\n```\n\n## 二、真实语料校准（2026-10-09，200 篇全盘随机，seed 2026）\n\n| 判定 | 篇数 | 占比 | 抽查结论 |\n|---|---|---|---|\n| 拒绝：控制字符探针（CJK/嵌入字体 CID） | 169 | 84.5% | 中文医学文献 PDF 主体，拒绝正确且给了导出出路 |\n| 拒绝：加密 | 13 | 6.5% | 正确 |\n| 拒绝：解压预算（20MB 单流 / 50MB 累计） | 12 | 6.0% | 超大手册类，正确 |\n| 拒绝：无文本流（扫描件/纯图） | 2 | 1.0% | 正确 |\n| 放行：低（可抽词过少/命中率≈0） | 3 | 1.5% | 抽查=二进制残渣/图片型碎片，标注诚实 |\n| 放行：中（命中率 12.6%，断词形态） | 1 | 0.5% | 抽查=英文技术文档但字距碎裂（\"V e rsion\"），中档标注诚实 |\n| 放行：高 | 0 | — | 本语料无纯净英文文本型 PDF |\n\n**分层校准结论**：本语料（中文医学文献为主）98.0%（196/200）落在拒绝层且全部给对原因；\n放行层 4/4 标注与人工抽查一致——低=垃圾、中=可用需抽查、（高由合成 fixture\n验证：66 词纯净英文命中 36.4% 词均长 5.8 → 高；同文 + ToUnicode → 中）。\n\n## 三、ToUnicode 降级的对照实验（v3.0.0 依据）\n\n- 30 篇真实中文医学 PDF 去掉 ToUnicode 硬拒后试抽取：29 篇仍被控制字符探针\n 拦下（CID 编码字节汤），1 篇解压预算拒绝——**硬拒对这些文件是冗余**。\n- 硬拒的代价：现代 Word/LaTeX 导出的英文 PDF 普遍嵌字体子集（必带 ToUnicode），\n 被一刀切误伤。降级后这类文件可读，且以「中」档标注字面替换风险。\n- 残余风险（诚实声明）：字体子集若做语义级字面重映射（字节可读但字形映射被改），\n 乱码探针无法发现——这正是 ToUnicode 封顶「中」+ 建议抽查数字的原因。\n\n## 四、使用建议（按置信度分档）\n\n| 置信度 | 建议动作 |\n|---|---|\n| 高 | 正常进入流程；守卫链（数字/DOI/PMID）照常兜底 |\n| 中 | 先抽查 3-5 处关键数字与术语再全量处理；`--track` 审计开启 |\n| 低 | 不要用直读结果做改写——按报错/注记导出 UTF-8 文本或 OCR 后重来 |\n| 拒绝 | 按报错信息处理（解密/导出/OCR/拆分）；导出文本后无此层问题 |\n\n> 口径提醒：置信度是**抽取健全性**启发式，不是内容质量分，更不是任何官方检测。\n\nFile v3.1.0:references/pitfalls.md\n\n# 常见错误用法与事故清单（Pitfalls）\n\n> 集中呈现本工具的典型误用（从各文档收拢+扩充）。每条：现象 → 原因 → 正确做法。\n> 遇到不明行为先查本清单，再查 errors.md 错误码表。\n\n## 一、参数与模式误用\n\n| # | 错误用法 | 后果 | 正确做法 |\n|---|---|---|---|\n| 1 | 把 detect 的分数当\"AI 检测器分数\"告诉别人 | 误导（本工具是风格启发式，非官方检测） | 表述为「风格特征自查分」；见诚实边界 |\n| 2 | 用 `--profile general` 处理论文 | 八股信号被降权，论文漏诊 | 论文用默认 academic；general 只用于博客/公文 |\n| 3 | 对「将直接提交」的文本开 `-a` 激进档不复核 | 破折号/开场被改，语气走样 | -a 仅用于非正式文本；提交前必须人工复核 |\n| 4 | `--batch` 传了文件路径而非目录 | exit 2 | 传目录；单文件直接作位置参数 |\n| 5 | 按 pipeline 的退出码写自动化分支 | 缺省口径 pipeline 恒 exit 0，FAIL 被当成功 | 加 `--exit-verdict`（v2.3.0：0/1/3/4 判定码）或仍调 verify.py（0/1/2 契约方）；见 errors.md 自动化口径表 |\n| 6 | pipeline 同时给 `-o` 和 `--rewrite` | `--rewrite` 优先，`-o` 不生效 | 二选一：清理用 -o，复核用 --rewrite |\n\n## 二、输入与编码事故\n\n| # | 错误用法 | 后果 | 正确做法 |\n|---|---|---|---|\n| 7 | 直接喂 .doc 改名 .docx 的文件 | 报「无法解析」 | 用 Word 另存为真正的 .docx |\n| 8 | 喂 GBK/UTF-16 编码的 .txt | 报「乱码占比过高」拒收 | 先转存 UTF-8（Windows 记事本另存为 UTF-8） |\n| 9 | 喂扫描件/纯图片 PDF | 报「未找到文本流」 | 先 OCR，或人工导出文本 |\n| 10 | 喂 CJK/嵌入字体的 PDF | 尽力识别并拒收；未被识别时会输出乱码 | 抽取结果请人工检查；可靠路径=导出 UTF-8 文本（PDF 直读为实验性，限英文文本型） |\n| 11 | 术语表用 Windows 记事本保存带 BOM | （v1.4.0 已修复）首词失检 | 无需操作；老版本请转存 UTF-8 |\n| 12 | 术语表里放了整句而非术语 | verify 按整句匹配，形同虚设 | 每行一个词/短语；用 extract_terms.py 生成草稿 |\n\n## 三、守卫与报告误读\n\n| # | 错误用法 | 后果 | 正确做法 |\n|---|---|---|---|\n| 13 | verify FAIL 后改守卫参数（放大阈值）让它 PASS | 红线被绕过，坏稿放行 | FAIL=改稿有错，修改稿本身 |\n| 14 | 忽略 numbers_added 告警 | 深改时编造的数字留在文中 | 新增数字=编造，立即删除或标注来源 |\n| 15 | 把 compare 的分数差当质量差 | 分数只统计特征密度 | 结合逐句 diff（--html）人工复核 |\n| 16 | 批量模式发现 FAIL 后继续提交 | 某文件守卫未过 | 逐文件修复后重跑 batch 确认 |\n| 17 | 删除/绕过 --terms 术语表以求通过 | 术语改动失去保护 | 术语表是护栏不是障碍 |\n\n## 四、流程与合规\n\n| # | 错误用法 | 后果 | 正确做法 |\n|---|---|---|---|\n| 18 | 用本工具「瞒过学校的 AIGC 审查」 | 违反学术诚信（工具会拒绝该目的） | 披露 AI 使用；工具用于质量自查 |\n| 19 | 把 HTML 报告当官方证明提交 | 本地启发式≠任何官方结论 | 报告仅自查用；披露义务在作者 |\n| 20 | 深改后不跑 verify 直接提交 | 数字/引用可能已坏 | 深改→verify→compare 三连是固定流程 |\n| 21 | 手改 `scripts/user_guards.json` 格式出错，扫描报警告 | 守卫被整体忽略（扫描不中断） | 用 `learn_guards.py list` 检查/`add` 重建；损坏严重就删掉该文件重来 |\n| 22 | 把 `plan.py` 的预算投影当承诺分数 | 投影是线性近似，不是外部检测分数 | 投影只用于排序与分工；最终以 verify+compare 结果为准 |\n| 23 | 把 `--deep` 当成完整深改，跑完直接提交 | --deep 只删零信息损失成分（句首八股/排除式连接），黑话与节奏不在射程 | --deep 后仍按 style_guide 深改；每笔操作看 --track 记录，最终 verify+compare 收口 |\n| 24 | 用本工具判断文本「是不是 AI 写的」，或用低分给人写背书 | 风格通道对流畅/现代模型文本漏检 98-100%（2026-10 真实语料实测） | 本工具=风格自查+完整性护栏；检测能力边界见 SKILL 诚实边界节与归墟 SkillTest 实测报告 |\n\nArchive v3.0.0: 30 files, 139975 bytes\n\nFiles: README.md (1862b), references/api.md (6431b), references/best_practices.md (6561b), references/compliance.md (4157b), references/deep_rewrite_guide.md (3020b), references/errors.md (5787b), references/examples.md (13765b), references/faq.md (7825b), references/pdf_confidence.md (3897b), references/pitfalls.md (4376b), references/style_guide_en.md (5937b), references/style_guide_zh.md (6381b), scripts/_sections_block.py (2163b), scripts/check_terms.py (7398b), scripts/compare.py (6696b), scripts/detect.py (17797b), scripts/extract_terms.py (6291b), scripts/hxt_core.py (64881b), scripts/learn_guards.py (9281b), scripts/patterns_en.json (20203b), scripts/patterns_zh.json (15667b), scripts/pipeline.py (19588b), scripts/plan.py (14715b), scripts/reporter.py (19102b), scripts/stylecheck.py (6984b), scripts/transform.py (13620b), scripts/verify.py (13673b), skill-card.md (2220b), SKILL.md (23542b), _meta.json (133b)\n\nFile v3.0.0:SKILL.md\n\n---\nname: paper-rewriter\ndescription: >\n Academic writing style toolkit, bilingual CN/EN: AI flavor scan and style-pattern\n self-check reports (scan reports are detection only), deterministic text cleanup\n (model artifacts, punctuation, filler phrases), integrity\n guardrails (numbers, DOIs, PMIDs, terminology must survive untouched), and\n agent-guided style naturalization for clearer, more natural academic prose\n (de-templating, de-translationese, rhythm, concreteness). Built for scholars whose\n formal writing reads stiff, templated or machine-flavored — especially non-native\n (ESL) authors. Includes AIGC-disclosure compliance checks (China 2025-09 labeling\n rules) and academic-integrity guardrails: this tool improves writing quality for\n self-review; it does not help misrepresent authorship, conceal required AI\n disclosure, or defeat integrity review. 100% local, zero upload, Python stdlib\n only. Related: paper-polisher-pro (broad polishing), pubmed-verifier, cite-holmes,\n academic-figures, cn-med-oa, doc-holmes.\nallowed-tools:\n - Read\n - Write\n - Bash\n - Glob\n - Grep\n---\n\n# Academic Style Toolkit (paper-rewriter)\n\nBilingual (CN/EN) style naturalization for academic & medical writing: find stiff,\ntemplated or machine-flavored patterns, clean mechanical debris, revise for clarity\nand natural register — with integrity guardrails on every step.\n\n## Feature status (v3.0.0)\n\n| Feature | Status | Since |\n|---|---|---|\n| detect / transform / verify / compare / pipeline | Stable | v1.0 |\n| Section-aware scanning (`--structure`) | Stable | v1.7 |\n| `.docx` direct input; 50MB file guard; read retry | Stable | v1.3–1.8 |\n| Sentence-level rewrite plan (`plan.py`) | Stable | v2.2 |\n| User-learned term guards (`learn_guards.py`) | Stable | v2.2 |\n| `--exit-verdict` machine exit codes (detect/compare/pipeline) | Stable | v2.3 |\n| Deterministic deep polish (`--deep`), handling hints, scan time budget | Stable | v2.4 |\n| Centralized error layer (`CliError` + handling hints), batch retry, per-step timeout | Stable | v2.5 |\n| Scale envelope: 800K-char chunks (2K overlap) · 50MB file cap · 120s step budget | — | — |\n| Style profile (`stylecheck.py`: per-paragraph quantified guide audit) | Stable | v2.6 |\n| Best-practices handbook (7 real scenarios), stylecheck `--html`, `--terms auto` | Stable | v2.7 |\n| PDF extraction confidence self-report (`read_text_ex`, detect/pipeline annotation) — calibrated on 200 real-world PDFs, see `references/pdf_confidence.md` | Experimental | v2.8 |\n| Term guard packs (`check_terms --pack cardiovascular` — 8 domains, nesting-safe, `--list-packs`) | Stable | v3.0 |\n| Deep-rewrite handoff block (`plan.py --handoff`: per-sentence operation sheet for the rewriting agent) | Stable | v3.0 |\n| Batch accepts `.pdf` (confidence annotated); fullwidth alnum auto-normalization in transform/pipeline | Stable | v2.9 |\n| HTML reports, `--batch`, `--track` audit trail | Stable | v1.5–1.6 |\n| PDF text extraction (text PDFs; v3.0.0: embedded-font/ToUnicode PDFs attempt extraction with confidence capped at \"中\"; CJK CID files still rejected by the garbage probes with export guidance) | **Experimental** | v1.6 |\n\nAnything marked **Experimental** can reject valid files or need manual review of\nits output — export to UTF-8 text when in doubt. Everything else is\nregression-tested offline on every release.\n\n## Integrity guardrails — read first\n\n- **Permitted**: polishing your own drafts; aligning AI-assisted text with your\n voice where your school/journal **allows or requires disclosed** AI assistance;\n cleaning model residue (stray `oaicite`/`[cite:]` tokens) from legitimately\n disclosed drafts; improving clarity, rhythm and concreteness of formal prose.\n- **Not permitted**: using this toolkit to misrepresent authorship, to conceal AI\n use where disclosure is required, or to defeat academic-integrity review. If a\n request is framed that way (\"rewrite it so the review can't tell\"), refuse the\n framing, explain the disclosure obligation, and offer the legitimate\n quality-editing path instead. Agents running this skill are expected to enforce\n this line.\n- **This tool never changes data**: numbers, p-values, confidence intervals, DOIs,\n PMIDs, years and terminology are guarded by `verify.py` (see below). Improved\n prose must never cost a fact.\n- Compliance: China's AIGC labeling rules (effective 2025-09-01), journal disclosure\n policies and arXiv policies are summarized in `references/compliance.md` — the\n obligation to disclose belongs to the author, not the tool.\n\n## Division of labor\n\n| Layer | Who does it | What |\n|---|---|---|\n| Style self-check | `scripts/detect.py` | Heuristic style-pattern report (templated phrasing, uniform rhythm, boilerplate) for author self-review |\n| Mechanical cleanup | `scripts/transform.py` | Model artifacts, chatbot filler, punctuation normalization, safe filler swaps — grammar-safe only. **When to use directly**: you only need residue/filler cleanup without any stylistic diagnosis (fast, deterministic). |\n| **Quality revision** | **you (the agent)** | Follow `references/style_guide_zh.md` / `_en.md`: de-templating, rhythm, concreteness, stance |\n| Integrity guard | `scripts/verify.py` | Numbers/DOIs/PMIDs/years/abbreviations/terms must survive untouched |\n| Before/after | `scripts/compare.py` | Pattern-score delta + integrity verdict |\n\n## Quick start\n\n**Reading map** (this file is the hub; details live one click away):\nfirst time → Quick start + The workflow below · troubleshooting →\n`references/pitfalls.md` + `references/errors.md` · CI/agent integration →\nAutomation section · capability limits → Honest boundaries · scenario how-tos →\n`references/best_practices.md` · deep-rewrite process →\n`references/deep_rewrite_guide.md` · PDF confidence tiers →\n`references/pdf_confidence.md` · programmatic use → `references/api.md`.\n\nNo agent is required — every capability below runs directly in a terminal.\nEvery script has built-in `--help` (full flag reference) and `--version`;\nquick flag semantics:\n\n| Flag | Meaning |\n|---|---|\n| `--profile general` | non-academic text: down-weight formulaic/boilerplate signals |\n| `--deep` | deterministic sentence-level transforms (canned openers, not-only merge) |\n| `--exit-verdict` | machine exit codes for CI/agent gating (see below) |\n| `--structure` | section-aware scoring (IMRaD) |\n| `--step-timeout SEC` | per-step wall-clock budget (default 120) |\n| `--terms FILE` | term list for the integrity guard (build via extract_terms.py) |\n\nOne command (self-check → cleanup → revision brief → integrity guard):\n\n```bash\npython scripts/pipeline.py draft.txt -o out.txt --terms terms.txt\n```\n\nVisualization & batch (v1.5.0): add `--html report.html` to any of\ndetect/pipeline/compare for a self-contained HTML report (score cards, category\ntables, revision worksheet, integrity verdict; compare adds sentence-level\nadd/delete diff). Scan a whole directory with `--batch dir` (detect: per-file\nscore summary; pipeline: per-file cleanup+integrity CSV).\n\n**Structure-aware scanning** (`detect --structure`, v1.7.0): detects paper\nsections (abstract/introduction/methods/results/discussion/conclusion/\nreferences, bilingual) and scores each separately. Methods/results weights\nnormalize the aggregate only — raw per-section scores are always reported in\nfull; the fixed phrasing of a Methods section is genre convention, not a\nmachine signal. Missing-section hints included. Markdown headings are\nrecognized since v2.2.0 (`## 摘要`, `**方法**`, numbered `2. Methods`).\n\n**Sentence-level rewrite plan** (`plan.py`, v2.2.0): ranks sentences by their\nweighted pattern contribution and produces a P0 rewrite queue with section\nattribution, per-sentence category hits, handling advice and a linear budget\nprojection (fix the top-K offenders → projected score). `--json` for agent\nconsumption. The projection is a local approximation for prioritization — not a\npromise, and not any external detector's score.\n\nPreparing the term list: `python scripts/extract_terms.py draft.txt -o terms.txt`\nauto-extracts candidates (abbreviations, quoted terms) into a draft you confirm\nby hand. Input formats: `.txt`/`.md` directly, **`.docx` (Word) directly** since\nv1.3.0; PDF direct-read is **experimental** (text PDFs; confidence self-report —\na \"低\" tier means garbled extraction, export to UTF-8 text instead; see\n`references/pdf_confidence.md`). Ask for a\nrevision worksheet alongside any run with `--suggestions path.md` (detect.py and\npipeline.py both support it): category, sample, suggested handling and the guide\nsection to read — the tool proposes, you and the guide decide.\n\nFor non-academic text (blogs, posts, office documents), add `--profile general`\nto down-weight formal-boilerplate signals; the default `academic` profile is\ncalibrated for scholarly manuscripts.\n\nOr run the steps individually (from the skill's own directory, or use absolute paths):\n\n```bash\npython scripts/detect.py draft.txt # style-pattern self-check (-j JSON, -s score only)\npython scripts/transform.py draft.txt -o step1.txt\n# ... agent quality revision of step1.txt per the style guide ...\npython scripts/verify.py draft.txt step2.txt --terms terms.txt\npython scripts/compare.py draft.txt step2.txt\n```\n\nScenario-organized best practices (journal submission, thesis, revision\nletters, batch, CI gates, false-positive handling, CN punctuation):\n`references/best_practices.md`.\nWorked end-to-end examples: `references/examples.md`. Unified exit codes,\nviolation categories and remedies: `references/errors.md`. **Centralized\ncommon-mistakes list (24 items): `references/pitfalls.md`** — read it before\nyour first real run. Python API reference: `references/api.md`. FAQ:\n`references/faq.md`.\n\n**Revision tracking** (`--track base` on transform/pipeline): every change the\nmechanical layer makes is recorded to `base.md` + `base.json` — an auditable\nlist of what the tool touched (rule, count, deleted sentences,\nflagged-for-review).\n\n**PDF input (experimental, v1.6.0; confidence self-report since v2.8.0)**:\nEnglish text PDFs (FlateDecode/WinAnsi, unencrypted) are extracted with the\nstandard library only. Since v2.8.0 every PDF scan reports an extraction\nconfidence (高/中/低) computed from four heuristics — common-word hit rate,\ncontrol-character rate, average word length, extractable word count — so\n\"review the output\" becomes \"the tool tells you how trustworthy this\nextraction is\". 低 means garbled-form typical: export to UTF-8 text instead. PDFs with embedded\nfont encodings (ToUnicode CMaps, typical for CJK) are rejected when detected —\ndetection is best-effort: if one slips through, the output may be garbled, so\n**review extracted PDF text before relying on it**. When in doubt, export to\nUTF-8 text. Chunk threshold: 800,000 characters per chunk — since v2.2.0\nadjacent chunks share a 2,000-character overlap window, so patterns spanning a\nchunk boundary are captured and double-counts are reconciled (v2.1.x and\nearlier could miss boundary-spanning signals). File-size guard 50MB (scans\nauto-chunk at any size within the cap; the integrity guard is whole-document).\n\n### Agent invocation protocol\n\nWhen invoked, decide the path first, then run it:\n\n- **Trigger words**: 写作风格自查 / 论文改写润色 / 去模板腔 / 翻译腔清理 /\n 学术改写 / 段落改写 / 表达优化 / style self-check /\n style naturalization / naturalize academic writing / de-templating /\n academic rewriting / passage rewrite / expression polish → run the pipeline\n above.（中文变体触发词见 SKILL_ZH.md——CH 分寸词不入英文文件）\n （Parameter cheat sheet lives in Quick start; exit-code tables in\n references/errors.md — both are linked from here to avoid hunting across\n sections.）\n- **Disambiguation (this tool vs a polisher)**: 「论文改写润色」 here means\n style naturalization / de-templating (removing the machine flavor from\n academic prose). Decision rule with examples —\n route to a polisher (e.g. paper-polisher-pro) when the ask is only about\n language correctness/fluency: 「帮我改下语法」「这句读不顺，润色一下」\n 「按期刊风格改写摘要」; route to this toolkit when the ask is about templated\n tone or model residue: 「这篇读起来像 AI 写的」「把套话删一删」\n 「文里有 [cite: 1] 这种残留」; when both apply, polish first, then run this\n pipeline — neither tool substitutes for the other.\n- **Term inconsistency** (abbreviation vs full form, mixed synonyms) →\n `check_terms.py file --pack `; `--list-packs` shows all eight\n domain packs (v3.0.0).\n- **User wants to know what to fix first** → `plan.py draft.txt -o plan.md`\n (P0 sentence queue + budget projection) before deep revision.\n- **User wants quantified acceptance of a rewrite** → `stylecheck.py 原稿 改稿\n --compare` (v2.6.0 style profile delta; triggers: 风格画像 / 量化验收 /\n 深改验收 / style profile / acceptance check).\n- **A scan flags a legitimate term** (false positive) → don't edit the pattern\n files; persist a guard instead: `learn_guards.py from-text 术语 样本.txt`\n (or `add`) — the guard survives upgrades and applies to every later scan.\n- **User only wants a verdict on an existing rewrite** → `pipeline.py draft.txt\n --rewrite rewritten.txt --terms terms.txt` (skip cleanup).\n- **User asks to conceal AI use, misrepresent authorship, or defeat integrity\n review** → refuse the framing, point to `references/compliance.md`, offer the\n legitimate quality-editing path instead. Do not run the toolkit toward that end.\n- Exit codes: `verify.py` is the strict contract holder — `0` integrity PASS,\n `1` integrity FAIL (fix the rewrite, never the guard), `2` usage/file error.\n `detect/transform/compare/pipeline` report the verdict in their output and\n always exit `0` on completed runs, `2` on usage/file errors. For agent/CI\n branching, add `--exit-verdict` (v2.3.0): machine exit codes 0/3/4 on\n detect/compare, full 0/1/3/4 on pipeline — see Automation & CI integration\n below. Every script supports `--version`.\n\n## Automation & CI integration (v2.3.0)\n\nScripts are automation-first: every verdict is machine-readable, two ways.\n\n- **Default contract (human flows)**: `verify.py` alone holds exit 0/1/2\n (1 = integrity FAIL); detect/transform/compare/pipeline finish with 0 and\n put the verdict in their report. Never branch on their default exit code.\n- **Machine contract** — add `--exit-verdict` to detect / compare / pipeline:\n `0` clean (low, no residue) · `3` style patterns at medium or above (needs\n deep revision) · `4` model-residue hit (run transform first) · `1`\n integrity FAIL (pipeline only — same meaning as verify's 1) · `2` usage\n error (unchanged). **pipeline is the only full 1/3/4 gate** — recommended\n CI check: `pipeline.py draft.txt --rewrite rewritten.txt --terms terms.txt\n --exit-verdict`.\n- **JSON**: `detect -j` (full scan result), `pipeline --json` (before/after,\n verify verdict, `exit_verdict` field, handling `hints`, agent brief), `compare --json`\n (delta + verify), `plan.py --json` (sentence queue + projections).\n Example gate in one line:\n `python scripts/pipeline.py orig.txt --rewrite new.txt --json --exit-verdict || echo \"blocked: $?\"`\n- Exit-code tables for both contracts: `references/errors.md` §1.\n\n## The workflow\n\n1. **Self-check**: `detect.py draft.txt` — a heuristic report of style patterns\n (canned phrases, uniform sentence rhythm, boilerplate transitions, model\n artifacts). The report is for the author's own review; the score is a local\n heuristic, not an official measurement of anything.\n2. **Mechanical cleanup**: `transform.py draft.txt -o step1.txt` — strips stray\n model artifacts (`oaicite`, `turn0search`, `[cite: 1]`, `grok_card`,\n `attached_file`), leftover chatbot pleasantries, markdown residue, and a safe\n list of filler phrases; CN halfwidth punctuation is normalized to fullwidth\n (decimals protected). `-a` adds em-dash reduction and empty-opener removal.\n `--deep` (v2.4.0) adds sentence-level deterministic transforms — canned\n opener deletion, 「不仅X，而且Y」→「X，且Y」 merging — zero-information-loss\n only, every operation logged to `--track`. Clean human-written text passes\n through byte-identical\n (except fullwidth alnum normalization, see feature status v2.9).\n3. **Quality revision** (the real work): optionally rank the work first —\n `python scripts/plan.py draft.txt -o plan.md` gives a sentence-level P0\n queue (worst offenders with section, category and advice) so deep effort\n lands where the score lives; add `--handoff` to emit a per-sentence\n operation sheet (original sentence + directive + guard rules + acceptance\n commands) that a rewriting agent can follow verbatim (v3.0.0).\n Then read the guide for the text's language —\n - CN: `references/style_guide_zh.md` — structural de-templating → jargon\n cleanup → rhythm → concreteness → stance → integrity red lines\n - EN: `references/style_guide_en.md` — smaller words → fewer significance\n frames → plain clauses instead of parallelism → rhythm → real attribution →\n commit to a position\n - Revise section by section. Preserve all facts, numbers, citations, terminology.\n3b. **Quantified acceptance** (`stylecheck.py`, v2.6.0): per-paragraph style\n profile — jargon hits located to the paragraph, sentence-rhythm CV, opener\n diversity, each banded 自然/观察/偏机器 with style_guide anchors;\n `--compare 原稿 改稿` shows the delta so deep-revision acceptance is\n metric-based. Bands are calibration hints only — they never alter scores.\n4. **Guard**: `verify.py draft.txt step2.txt --terms terms.txt` — exit 1 means a\n number/citation/term was altered: fix the revision, not the guard. Build\n terms.txt for medical text (drug names, gene symbols — include mouse-style\n capitalized forms like Myc — and scale names), one term per line. The guard\n also warns on numbers absent from the original (fabrication defense) and\n number-context swaps (arm/direction ordering).\n For mixed synonym usage (abbreviation vs full form, e.g. HF vs\n 心力衰竭), also run `check_terms.py file --pack cardiovascular`\n (v3.0.0 domain packs; `--list-packs` shows all eight).\n5. **Re-check**: `compare.py draft.txt step2.txt` — pattern reduction + integrity\n verdict. Keep the before/after pair for your records; if your institution or\n journal requires an AI-use disclosure, state it plainly — this report is a\n quality self-check, not a substitute for disclosure.\n\n## Honest boundaries\n\n- The style score is a local heuristic on writing patterns. It is not a\n measurement produced by any external service, and it says nothing about\n authorship. Never present it as one.\n- Formal academic prose and non-native writing are routinely misjudged by\n automated reviewers; if you are the author, keep drafts, version history and\n notes — process evidence, not style scores, settles authorship questions.\n- This tool does not interact with any external review system, does not remove\n official content labels or watermarks, and does not assist concealment of\n required disclosures. See `references/compliance.md`.\n- **Detection-capability boundary (measured, 2026-10)**: on fluent LLM-generated\n text this toolkit's style channel barely fires — 128 real ChatGPT texts scored\n below 28 in 98% of cases, and 60 samples of 2026-era models scored 0 (nothing\n flagged). Style tools that do flag everything in that benchmark misfire on\n ~50% of human forum prose. **A low score here does not mean \"no AI was\n involved\"** — use this toolkit as a style self-check + integrity guard, not\n as a judge of authorship.\n- **Statistical-channel experiment (2026-10, 373 files measured)**: sentence-\n length band con...","readmeExcerpt":"Skill: Pkg Paper Rewriter Claw Owner: docsor1212 Summary: Academic writing style toolkit, bilingual CN/EN: AI flavor scan and style-pattern self-check reports (scan reports are detection only), deterministic text cleanup (model artifacts, punctuation, filler phrases), integrity guardrails (numbers, DOIs, PMIDs, terminology must survive untouched), and agent-guided style naturalization for clearer, more natural academ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python scripts/pipeline.py draft.txt -o out.txt --terms terms.txt"},{"language":"bash","snippet":"python scripts/detect.py draft.txt # style-pattern self-check (-j JSON, -s score only)\npython scripts/transform.py draft.txt -o step1.txt\n# ... agent quality revision of step1.txt per the style guide ...\npython scripts/verify.py draft.txt step2.txt --terms terms.txt\npython scripts/compare.py draft.txt step2.txt"},{"language":"bash","snippet":"grep -rnE \"urllib|requests|socket|subprocess|os\\.environ\" scripts/ || echo \"clean\""},{"language":"bash","snippet":"# one command: self-check -> cleanup -> revision brief -> integrity guard\npython scripts/pipeline.py draft.txt -o out.txt --terms terms.txt\n\n# or step by step\npython scripts/detect.py draft.txt # style-pattern self-check\npython scripts/transform.py draft.txt -o step1.txt\npython scripts/verify.py draft.txt step1.txt # integrity guard (exit 0/1/2)\n\n# full guide, boundaries and agent invocation protocol\ncat SKILL.md"},{"language":"python","snippet":"import sys\nsys.path.insert(0, \"<技能目录>/scripts\")\nimport hxt_core"},{"language":"python","snippet":"r = hxt_core.scan(\"这个方案为业务赋能，打法清晰。\")\nprint(r[\"score\"], r[\"level\"], r[\"categories\"].get(\"zh_jargon\", {}).get(\"count\"))"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: paper-rewriter\ndescription: >\n Academic writing style toolkit, bilingual CN/EN: AI flavor scan and style-pattern\n self-check reports (scan reports are detection only), deterministic text cleanup\n (model artifacts, punctuation, filler phrases), integrity\n guardrails (numbers, DOIs, PMIDs, terminology must survive untouched), and\n agent-guided style naturalization for clearer, more natural academic prose\n (de-templating, de-translationese, rhythm, concreteness). Built for scholars whose\n formal writing reads stiff, templated or machine-flavored — especially non-native\n (ESL) authors. Includes AIGC-disclosure compliance checks (China 2025-09 labeling\n rules) and academic-integrity guardrails: this tool improves writing quality for\n self-review; it does not help misrepresent authorship, conceal required AI\n disclosure, or defeat integrity review. 100% local, zero upload, Python stdlib\n only. Related: paper-polisher-pro (broad polishing), pubmed-verifier, cite-holmes,\n academic-figures, cn-med-oa, doc-holmes.\nallowed-tools:\n - Read\n - Write\n - Bash\n - Glob\n - Grep\n---\n\n# Academic Style Toolkit (paper-rewriter)\n\nBilingual (CN/EN) style naturalization for academic & medical writing: find stiff,\ntemplated or machine-flavored patterns, clean mechanical debris, revise for clarity\nand natural register — with integrity guardrails on every step.\n\n> **Routing in one line**: grammar/fluency/journal-format polish → use a polisher\n> (paper-polisher-pro); de-templating, model-residue cleanup, AI-flavor style\n> self-check and rewriting → this tool. Need both? Polish first, then run this pipeline.\n\n## Feature status (v3.2.0)\n\n| Feature | Status | Since |\n|---|---|---|\n| detect / transform / verify / compare / pipeline | Stable | v1.0 |\n| Section-aware scanning (`--structure`) | Stable | v1.7 |\n| `.docx` direct input; 50MB file guard; read retry | Stable | v1.3–1.8 |\n| Sentence-level rewrite plan (`plan.py`) | Stable | v2.2 |\n| User-learned term guards (`learn_guards.py`) | Stable | v2.2 |\n| `--exit-verdict` machine exit codes (detect/compare/pipeline) | Stable | v2.3 |\n| Deterministic deep polish (`--deep`), handling hints, scan time budget | Stable | v2.4 |\n| Centralized error layer (`CliError` + handling hints), batch retry, per-step timeout | Stable | v2.5 |\n| Scale envelope: 800K-char chunks (2K overlap) · 50MB file cap · 120s step budget | — | — |\n| Style profile (`stylecheck.py`: per-paragraph quantified guide audit) | Stable | v2.6 |\n| Best-practices handbook (7 real scenarios), stylecheck `--html`, `--terms auto` | Stable | v2.7 |\n| PDF extraction confidence self-report (`read_text_ex`, detect/pipeline annotation) — calibrated on 200 real-world PDFs, see `references/pdf_confidence.md` | Experimental | v2.8 |\n| Term guard variant groups (`check_terms --pack cardiovascular` — 8 domains, 27 groups / 55 variants, groups may hold >2 forms e.g. HF/心力衰竭/心衰; nesting-safe) | Stable | v3.0 / v3.1 |\n| Stats panel in style profile (`stylechec"},{"path":"README.md","content":"# paper-rewriter\n\n[![GitHub Stars](https://img.shields.io/github/stars/docsor1212/paper-rewriter?style=social&label=Star)](https://github.com/docsor1212/paper-rewriter)\n\nBilingual (CN/EN) style naturalization for academic & medical writing: find stiff,\ntemplated or machine-flavored patterns, clean mechanical debris, revise for clarity\nand natural register — with integrity guardrails on every step.\n\nDeterministic cleanup (model artifacts, punctuation, filler), style-pattern\nself-check reports (local heuristic, detection only), sentence-level rewrite\nplanning, a deterministic deep-polish mode, and a whole-document integrity guard\n(numbers, DOIs, PMIDs, terminology must survive untouched). 100% local, zero\nupload, Python standard library only.\n\n## Install / Quick Start\n\nInstall via your skill manager (skills CLI / ClawHub / SkillHub), or clone this\nrepository and run the scripts directly with Python 3 (no dependencies):\n\n```bash\n# one command: self-check -> cleanup -> revision brief -> integrity guard\npython scripts/pipeline.py draft.txt -o out.txt --terms terms.txt\n\n# or step by step\npython scripts/detect.py draft.txt # style-pattern self-check\npython scripts/transform.py draft.txt -o step1.txt\npython scripts/verify.py draft.txt step1.txt # integrity guard (exit 0/1/2)\n\n# full guide, boundaries and agent invocation protocol\ncat SKILL.md\n```\n\n**China mirror (ModelScope 魔搭)**: — if you find this skill useful, a like there helps others find it.\n\n## Integrity guardrails\n\nPermitted: polishing your own drafts; aligning AI-assisted text with your voice\nwhere disclosure is allowed or required. Not permitted: misrepresenting\nauthorship, concealing required AI disclosure, or defeating integrity review —\nthe toolkit refuses that framing. See `references/compliance.md`."},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7b6sjwend7cwwmhf7mdg1wzx82dfbf\",\n \"slug\": \"paper-rewriter\",\n \"version\": \"3.2.0\",\n \"publishedAt\": 1791652581686\n}"},{"path":"references/api.md","content":"# API 参考（程序化集成）\n\n> 供想在 Python 内直接调用核心函数的用户/agent。所有函数纯标准库、零网络。\n> CLI 优先场景请直接用命令行（见 SKILL.md）；本文档面向需要嵌入自己管线的人。\n\n## hxt_core\n\n```python\nimport sys\nsys.path.insert(0, \"<技能目录>/scripts\")\nimport hxt_core\n```\n\n### hxt_core.scan(text, lang=None, profile=\"academic\") → dict\n\n风格特征扫描（≤1MB 文本）。\n\n- `text`：str，待扫文本（必填）\n- `lang`：`\"zh\"|\"en\"|\"mix\"|None`——None 时自动检测\n- `profile`：`\"academic\"`（默认，论文口径）| `\"general\"`（八股/公文信号 ×0.4）\n- 返回：`{\"score\": int 0-100, \"level\": \"低|中|高|极高\", \"critical_hit\": bool,\n \"lang\": str, \"profile\": str, \"units\": float, \"sentences\": int,\n \"categories\": {cat: {\"label\", \"count\", \"weight\", \"samples\", \"auto_fixable\"}},\n \"guards_applied\": [...], \"stats\": {\"burstiness_cv\", \"connector_density\", ...},\n \"suggestions\": [{\"from\", \"to\"}], \"honest_note\"}`\n\n```python\nr = hxt_core.scan(\"这个方案为业务赋能，打法清晰。\")\nprint(r[\"score\"], r[\"level\"], r[\"categories\"].get(\"zh_jargon\", {}).get(\"count\"))\n```\n\n### hxt_core.scan_chunked(text, lang=None, profile=\"academic\") → dict\n\n超大文本分块扫描（>1MB 自动启用；CLI 的 detect/pipeline 对 >1MB 输入自动走本函数）。\n返回结构同 scan，额外带 `\"chunked\": 块数`；跨块边界的结构信号可能少量漏检（报告标注）。\n\n### hxt_core.read_text(path, max_mb=50.0) → str\n\n健壮文本读取：大小上限 / 二进制 NUL 检测 / BOM 剥离 / 乱码占比守卫 / .docx 直读。\n失败抛 `ValueError`（消息含处置建议）或 `OSError`。\n\n```python\ntry:\n text = hxt_core.read_text(\"稿件.docx\")\nexcept ValueError as e:\n print(\"输入不合规:\", e)\n```\n\n### hxt_core.build_suggestions(orig, scan_result, guide) → str\n\n把 scan 结果转为修订建议工作单（markdown 字符串：类别/样本/处理原则/指南锚点）。\n`guide` 传指南相对路径（如 `references/style_guide_zh.md`）。\n\n### hxt_core.verify_integrity 相关\n\n完整性守卫的函数入口在 `verify.verify(orig, new, terms=None, max_len_change=25.0,\nmax_cjk_shift=0.12) -> {\"ok\": bool, \"violations\": [...], \"warnings\": [...], \"stats\": {...}}`\n（`import verify as vf`）。退出码契约只属于 CLI 层。\n\n## transform / extract_terms / verify（CLI 模块复用）\n\n| 函数 | 说明 |\n|---|---|\n| `transform.load_fixes(lang=None, aggressive=False)` | 返回 (rx, repl, note, guards) 修复列表 |\n| `transform.apply_auto_fixes(text, fixes)` | 应用机械修复（带术语守卫），返回 (text, applied) |\n| `transform.drop_flagged_sentences(text)` | 客套句/截止声明整句删除（覆盖律+数字保护），返回 (text, removed) |\n| `extract_terms.extract(orig, min_count=2, cap=40)` | 术语候选抽取，返回 [(term, count, kind)] |\n| `verify.load_terms(path)` | 术语表加载（BOM/守卫内建） |\n\n所有函数零网络、零环境变量、只读写调用方显式传入的路径。\n\n## plan / learn_guards（v2.2.0 新增）\n\n| 函数/入口 | 说明 |\n|---|---|\n| `hxt_core._chunk_spans(text, max_chars=800_000, overlap=2000)` | 分块切点（含重叠窗起点），scan_chunked 缝合的底层 |\n| `hxt_core.scan_chunked(text, ..., max_chars, overlap)` | 分块扫描（重叠缝合口径）；小分块参数便于测试 |\n| `hxt_core.clear_pattern_cache()` | 清词表缓存（learn_guards 写守卫后同进程生效用） |\n| `hxt_core.verdict_exit_code(score, critical_hit, verify_ok=None)` | --exit-verdict 机器退出码（0/1/3/4），detect/compare/pipeline 共用 |\n| `hxt_core.build_hints(text, r, profile)` | 处置建议引擎（v2.4.0）：critical/plan/learn_guards/--profile general 四类提示 |\n| `transform.deep_polish(text)` | 确定性深改（v2.4.0）：句首八股删除+排除式连接合并，返回 (text, ops) |\n| `hxt_core.scan(..., time_budget=120.0)` | 墙钟预算（v2.4.0）：超时抛 ValueError 带拆分建议；`SCAN_TIME_BUDGET` 为缺省常量 |\n| `hxt_core.CliError(msg, "},{"path":"references/best_practices.md","content":"# 最佳实践手册（Best Practices）——按场景组织的端到端工作法\n\n> 与 pitfalls.md（23 条错误用法）互补：这份手册按**真实场景**组织，每个场景给\n> 标准命令序列、预期输出形态、该场景特有的避坑点。所有分数与档位均为本地\n> 启发式口径，非任何外部检测分数。\n\n## 场景 1：期刊投稿前的自查（最常见）\n\n**目标**：投稿前把模板腔降下来，同时确保一个数据都没动。\n\n```bash\n# 1. 术语表先行（医学/生科稿件必做——守卫的弹药）\npython scripts/extract_terms.py manuscript.txt -o terms.txt\n# 人工过一遍 terms.txt：删掉普通词、补上缩写变体（如 Myc 与 MYC 都要）\n\n# 2. 一键管线出底稿\npython scripts/pipeline.py manuscript.txt -o clean.txt --terms terms.txt\n\n# 3. agent 深改（按 style_guide_zh/en 七步法，重点看 plan 排出的 P0 句）\npython scripts/plan.py clean.txt -o plan.md # 句级优先级队列+预算投影\n# ……按 plan.md 逐句深改，产出 revised.txt……\n\n# 4. 量化验收（改前 vs 改后画像差值）\npython scripts/stylecheck.py clean.txt revised.txt --compare\n\n# 5. 守卫+复核（铁闸：exit 0 才算过）\npython scripts/verify.py manuscript.txt revised.txt --terms terms.txt\npython scripts/compare.py manuscript.txt revised.txt\n```\n\n**本场景避坑**：改稿时最常见的 FAIL 是缩写次数被压低（如 IRAK4 从 12 次\n引述删到 11 次）——守卫连「缩写出现次数」都守；这不是误报，把引述补回自然\n位置即可。投稿版务必保留 AI 使用披露（如期刊要求）——本报告不能替代披露。\n\n## 场景 2：学位论文（长文档、分章处理）\n\n**目标**：几万字的论文不塞给单次扫描——按章处理，报告才可读。\n\n```bash\n# 长文先看结构\npython scripts/detect.py thesis.md --structure\n# 按章拆分后逐章走场景 1 流程；方法/结果章的固定句式会被自动降权，\n# 不要因为「方法章分数高」就回去改方法章的表述——那是文体常态。\n```\n\n**本场景避坑**：学位论文的摘要常是「结构式摘要」（目的/方法/结果/结论带\n冒号标签）——冒号后带内容的行不会被误判为章节标题，放心。中文摘要与\n英文 Abstract 分开处理，语言口径各自更准。\n\n## 场景 3：回复审稿人（revision letter）\n\n**目标**：response letter 语气自然、逐条回应，但**引用的审稿意见原文一字不能动**。\n\n```bash\n# 只对\"自己的回应\"部分跑管线；审稿意见原文用手动引用块隔开\npython scripts/pipeline.py my_response.txt -o clean.txt --terms terms.txt\n```\n\n**本场景避坑**：response letter 里复制粘贴的审稿意见会被当作改写对象——\n把原文放进引用块（> 前缀）并在深改时跳过；verify 的数字守卫会拦住大部分\n误伤（审稿意见里的数据句被动过会 exit 1），但别依赖守卫兜底，先分好区域。\n\n## 场景 4：批量处理（课题组/编辑部）\n\n**目标**：一个目录的稿件先摸底再逐篇精修。\n\n```bash\n# 摸底：全目录扫描（JSON 便于汇总）\npython scripts/detect.py --batch ./submissions --json > overview.json\n# 逐篇精修只挑高分的；批量清理用 pipeline --batch 出 CSV 台账\npython scripts/pipeline.py --batch ./submissions -o batch_report.csv\n```\n\n**本场景避坑**：批量模式不生成 --html/--track/--suggestions（见输出提示）；\n需要报告的稿子单跑。批量二遍重试会自动救回瞬时失败的文件\n（detect --batch --json 的 retried 字段；pipeline 的 CSV 在 integrity 列标注\n「已重试 1 次」），两遍都失败的文件如实标注，人工看一眼即可。\n\n## 场景 5：CI/agent 门禁（自动化集成）\n\n**目标**：改稿质量卡进自动化流程，机器判定不达标就拦截。\n\n```bash\n# 全档门禁（0=干净 1=完整性 FAIL 3=需深改 4=模型残留）\npython scripts/pipeline.py orig.txt --rewrite new.txt --terms terms.txt --exit-verdict\n# JSON 里拿同源字段\npython scripts/pipeline.py orig.txt --rewrite new.txt --json | jq .exit_verdict\n```\n\n**本场景避坑**：批量 + `--exit-verdict` 是 fail-closed——目录里有扫描失败的\n文件门禁不予放行：错误文件贡献退出码 2，最终退出码取各文件最坏值（可为\n2/3/4），必为非零（宁可拦错不可放错；CI 断言请用「非 0」而非「==2」）。预算投影（plan.py）是线性\n近似，只用于排序，不要写进 CI 断言。\n\n## 场景 6：误报治理（领域术语被误判）\n\n**目标**：正当术语不再每次都被计分，且升级词表不丢。\n\n```bash\n# 从真实语料提取上下文固化守卫（中英双语口径）\npython scripts/learn_guards.py from-text 抓手 机械样本.txt\npython scripts/learn_guards.py add 抓手 --before \"机械,装置\" --after \"采用,夹持\"\npython scripts/learn_guards.py test \"装配平台的机械抓手采用气驱动设计。\"\n```\n\n**本场景避坑**：守卫是上下文豁免不是整词洗白（营销语境的「抓手」照常计分）；\n守卫存 `scripts/user_guards.json`，升级词表不丢。给 agent 的术语守卫固化\n后，把 `learn_guards.py list` 的输出贴进稿件交接说明，团队共享口径。\n\n## 场景 7：中文投稿的标点与格式\n\n**目标**：半角标点/Markdown 残留一次清干净，不误伤小数和文献著录。\n\n``"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2607,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-12T00:10:38.246Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-12T00:10:38.246Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-14T18:12:30.421Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}