mcpField
S
semantic-line-breaks

semantic-line-breaks

github.com/aircury文档处理584 次安装3 天前更新
代码仓库

关于 semantic-line-breaks

semantic-line-breaks 是用于编辑 `specs/` 或 `doc/` 下 Markdown 正文的写作技能。它依据语义决定换行，并将正文行控制在 80 个字符以内，让差异更易审阅且不改变渲染结果。

主要功能

  1. 01按语义边界换行
  2. 02正文每行不超过 80 个字符
  3. 03保持 Markdown 渲染结果不变
  4. 04代码和表格内部不插入换行
  5. 05指导手动编辑而非自动重排

适用场景

  1. 01编辑 `specs/` 中的 Markdown 正文
  2. 02修改 `doc/` 下的文档
  3. 03让逐句修改更易审阅
  4. 04在保留原意的同时重排长段落

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/aircury/ai-framework --skill semantic-line-breaks

安装后在 Claude Code 中输入/semantic-line-breaks确认已加载。

详细介绍

Markdown 语义换行

在 specs/ 或 doc/ 下的任何 .md 文件中撰写或编辑 prose 时，只有当 句号后的换行在段落中语义恰当（表达不同的想法、要求或便于审阅的单元）， 且该行仍符合下方限制时，才在句号后换新行。

句号并不意味着自动换行：缩写、小数、版本号和其他非句末句号应留在同一行； 有些句子读起来属于同一个整体，应放在同一行。

你可以在主要分句边界处进一步换行（分号、冒号、破折号之后，或较长的 括号补充说明之前）。

这种规范称为语义换行（也称为“通风式 prose”或“语义换行符”）。 规范说明请参阅 https://sembr.org。

行长（80 个字符）

所有适用的 prose 行都必须不超过 80 个字符 （包括空格和行首缩进，例如列表续行）。

如果句子或分句单行长度会超过此限制，请在自然边界处添加软换行 （分句、短语、单词，依次考虑），直到每行长度不超过 80 个字符。

短句保留在单行；长句则在此限制下跨多行书写。

仅凭人工判断（不使用脚本）

句号后换行的位置取决于含义、上下文以及段落在审阅时的阅读效果， 而不只是标点。

自动脚本无法正确应用此规则（包括格式化工具、正则表达式重排工具、 fmt 工具或批量“修复行长”的任务）。 Agent 和作者必须阅读 prose 后自行决定换行；不要对 specs/、doc/ 或 README 文件进行整体自动重排，也不要提议这样做。

原因

Markdown 会将连续的非空行合并为一个渲染段落 （CommonMark / GFM 会将软换行视为一个空格）。 渲染结果不会改变。 改变的是差异：修改一个句子只会显示为一行差异，而不是重排一个 500 字符的段落， 这样 PR 审阅和 git blame 都会更清晰易读。

80 字符限制可以让编辑器和审阅界面中的行更易读，同时不改变渲染后的 HTML。

编辑现有段落时

如果当前段落是一整行长文本，包含多个句子，那么编辑该段落时，应手动重排整个段落， 采用语义换行并遵守 80 字符限制，即使某些句子没有修改也一样。 判断每个句号的位置：只有在有助于理解和审阅时才换新行； 不要不加判断地在每个 . 处拆行。 这只是一次性工作；此后该段落的差异将始终保持清晰。

此规则不适用的情况

不要在以下内容的句子中间插入换行：

  • 围栏代码块或行内代码片段。
  • 表格（每行保持在同一行）。
  • 链接引用定义。
  • YAML frontmatter。
  • 原始 HTML 块。

列表项中的 prose 仍须遵守 80 字符限制；必要时在列表项内按句换行 （续行缩进到列表项文本的起始列）。

段落之间仍以空行分隔，与之前完全相同。

硬换行（行末两个空格）

当必须在一个渲染段落内进行可见换行时（例如地址行，或标签后在下一行补充详情）， 请在换行符前添加恰好两个空格。 在手动编写的 doc/ prose 中，不要使用一个行尾空格、三个或更多行尾空格， 也不要使用行尾 <br> 标签。 读者会将两个行尾空格视为硬换行；make doc-validate 会拒绝其他形式。

示例

错误 — 四个句子写在同一行，每次编辑都会重排整段内容：

The widget SHALL appear in the sidebar. It SHALL be hidden for guests. Administrators SHALL be able to pin it to the top. Pinning SHALL persist across sessions.

正确 — 渲染段落相同，每句的差异各占一行， 每行 ≤ 80 个字符：

The widget SHALL appear in the sidebar.
It SHALL be hidden for guests.
Administrators SHALL be able to pin it to the top.
Pinning SHALL persist across sessions.

如果单个句子太长，无法放在一行，请进一步拆分 （Markdown 软换行）：

This requirement SHALL describe a long policy that would exceed one hundred characters if
kept on one line, so it continues here without exceeding the limit.

评论

支持 Markdown