Csl

CSL 样式生成器

所有模板、参数、规则均位于 ${CLAUDE_SKILL_DIR} 目录下。

以下路径常量贯穿全流程：

Step 0: 收集信息

分析用户输入 $ARGUMENTS，判断信息是否充足。如果不足，必须先向用户确认以下内容再开始生成：

1. 正文引用方式（三选一，决定 CSL class 和 citation 配置）：

• 上标角标：正文中 [1-3] 以上标形式出现 → class="in-text", vertical-align="sup"
• 行内编号：正文中 [1-3] 与正文同行同字号 → class="in-text"
• 脚注/尾注：正文中插入脚注标记，引用内容出现在页脚或文末 → class="note"

2. 参考文献列表示例：至少需要用户提供 2-3 条不同类型（期刊、书籍、会议等）的参考文献原文，用于反推格式参数。

3. 正文引用示例（可选）：包含引用标记的原文段落，用于确认引用样式。

如果用户已经提供了上述信息（如粘贴了参考文献和正文），直接进入 Step 1 分析。

Step 1: 解析需求

从用户输入提取格式需求，匹配预设关键词：

• 匹配到 → 进入 Step 2a
• 未匹配 → 进入 Step 2b（从用户描述或参考文献示例反推参数）

Step 2: 读取配方

2a 预设路径： 读取 ${CLAUDE_SKILL_DIR}/presets/{preset}.md，获取全部参数。

2b 自定义路径： 按需读取 ${CLAUDE_SKILL_DIR}/components/ 下的组件模板：

根据用户需求选择性读取相关组件，无需全部加载。

Step 3: 生成 CSL

按以下骨架组装完整 .csl 文件：

style (xmlns, class, version, default-locale)
  ├── info (title, id, category, updated)
  ├── locale × N (术语覆盖)
  ├── macro × N (按组件模板填充)
  ├── citation (正文引用 / 脚注)
  └── bibliography (参考文献列表)

• 各宏的 XML 实现从组件模板中获取，按预设参数调整属性值
• 输出到 ${CLAUDE_SKILL_DIR}/output/{style-name}.csl

Step 4: 校验

python ${CLAUDE_SKILL_DIR}/scripts/validate_csl.py <file>

• 脚本输出 JSON 格式结果
• 如 "status": "FAIL"，根据 errors 修复后重新校验，直到 PASS
• 读取 ${CLAUDE_SKILL_DIR}/validate/rules.md 做补充审核（常见陷阱检查）

Step 5: 预览

python ${CLAUDE_SKILL_DIR}/scripts/preview_csl.py <file>

• 展示真实渲染结果给用户
• 等待用户确认，或根据反馈返回 Step 3 修改

Step 6: 修改已有样式（可选）

当用户提供现有 .csl 文件要求修改时： 1. 读取文件，定位需修改的部分 2. 参考对应组件模板进行修改 3. 重新执行 Step 4 + Step 5

access -- DOI/URL

参数

模板

DOI 优先（有 DOI 显示 DOI，否则显示 URL）

<macro name="access">
  <choose>
    <if variable="DOI">
      <!-- doi="prefix" 时加前缀 -->
      <text variable="DOI" prefix="https://doi.org/"/>
    </if>
    <else-if variable="URL">
      <text variable="URL"/>
    </else-if>
  </choose>
  <!-- accessed-date="true" 时追加访问日期 -->
  <group prefix="（" suffix="）">
    <date variable="accessed" form="text"/>
  </group>
</macro>

仅 URL

<macro name="access">
  <text variable="URL"/>
  <!-- 可选：附加访问日期 -->
  <group prefix=" [" suffix="]">
    <date variable="accessed" form="text"/>
  </group>
</macro>

仅 webpage 类型显示 URL

这是《太平洋学报》等中文社科期刊的常见做法。参考 太平洋学报.csl 中的实现：

<!-- 英文 -->
<macro name="access-en">
  <choose>
    <if type="post post-weblog software webpage" match="any">
      <text variable="URL"/>
    </if>
  </choose>
</macro>

<!-- 中文 -->
<macro name="access-zh">
  <choose>
    <if type="post post-weblog software webpage" match="any">
      <text variable="URL"/>
    </if>
  </choose>
</macro>

不显示任何链接

<macro name="access">
  <!-- 空 macro，不输出任何内容 -->
</macro>

注意事项

• CSL 中 DOI 变量名为全大写 DOI，URL 变量名为全大写 URL。
• doi="prefix" 需要手动拼接前缀 https://doi.org/，因为 Zotero 存储的 DOI 字段通常只是标识符（如 10.1234/xxx），不含协议前缀。
• accessed-date 对应 CSL 的 accessed 日期变量，通常在网页类型中使用，格式如 2024-01-15。
• 中文样式中访问日期常用中文括号包裹，英文样式常用方括号。
• webpage-only 模式通过 <if type="post post-weblog software webpage"> 限定类型，是中文学术期刊最常见的策略。
• 如果同时需要 DOI 和 accessed-date，应将访问日期放在 DOI 之后，用适当分隔符连接。

bibliography -- bibliography 元素

参数

模板

numeric 带编号 [1]，flush 对齐

参考 太平洋学报.csl 中的实际定义：

<bibliography entry-spacing="0" second-field-align="flush">
  <!-- 中文条目 -->
  <layout locale="zh">
    <text variable="citation-number" prefix="[" suffix="]"/>
    <text macro="entry-layout-zh" suffix="。"/>
  </layout>
  <!-- 英文条目（默认） -->
  <layout>
    <text variable="citation-number" prefix="[" suffix="]"/>
    <text macro="entry-layout-en" suffix="."/>
  </layout>
</bibliography>

效果：

[1]  张三：《论文标题》，《期刊名》，2024年第1期。
[2]  Smith, "Article Title," Journal Name, 2024.

second-field-align="flush" 使 [1] 之后的正文文字对齐到同一列，编号不占用正文空间。

author-date 悬挂缩进

<bibliography hanging-indent="true" entry-spacing="1" line-spacing="1">
  <sort>
    <key macro="author"/>
    <key macro="date" sort="ascending"/>
  </sort>
  <layout suffix=".">
    <group delimiter=". ">
      <text macro="author"/>
      <text macro="date" prefix="(" suffix=")"/>
      <text macro="title"/>
      <text macro="container"/>
    </group>
  </layout>
</bibliography>

效果：

Smith, John. (2024). "Article Title." Journal Name, Vol. 10, No. 2.
    Continued text wraps with hanging indent.

hanging-indent="true" 使首行顶格、续行缩进，便于快速定位作者姓氏。

note 样式参考文献列表

note 样式也可以附带 bibliography，通常按作者排序，不带编号：

<bibliography hanging-indent="true" entry-spacing="0" line-spacing="1">
  <sort>
    <key macro="author"/>
    <key macro="date" sort="ascending"/>
  </sort>
  <layout locale="zh">
    <text macro="entry-layout-zh" suffix="。"/>
  </layout>
  <layout>
    <text macro="entry-layout-en" suffix="."/>
  </layout>
</bibliography>

效果：

张三：《论文标题》，《期刊名》，2024年第1期。
Smith, "Article Title," Journal Name, 2024.

无编号，按作者字母/拼音排序，悬挂缩进。

中文样式（"。"结尾）

中文参考文献以句号"。"结尾，英文以 period "." 结尾。通过双语 layout 分别指定 suffix：

<bibliography entry-spacing="0" second-field-align="flush">
  <layout locale="zh">
    <text variable="citation-number" prefix="[" suffix="]"/>
    <text macro="entry-layout-zh" suffix="。"/>
  </layout>
  <layout>
    <text variable="citation-number" prefix="[" suffix="]"/>
    <text macro="entry-layout-en" suffix="."/>
  </layout>
</bibliography>

subsequent-author-substitute（连续相同作者替代）

当参考文献列表中多条连续条目的作者相同时，用长划线替代重复的作者名：

<bibliography hanging-indent="true" subsequent-author-substitute="———">
  <sort>
    <key macro="author"/>
    <key macro="date" sort="ascending"/>
  </sort>
  <layout suffix=".">
    <group delimiter=". ">
      <text macro="author"/>
      <text macro="date" prefix="(" suffix=")"/>
      <text macro="title"/>
    </group>
  </layout>
</bibliography>

效果：

Smith, John. (2023). First Article.
———. (2024). Second Article.
———. (2025). Third Article.

注意事项

• `second-field-align`：此属性专为带编号的参考文献设计。flush 将编号视为独立列，正文从编号后对齐；margin 将编号放入页边距区域。如果不需要编号，通常使用 hanging-indent 代替。
• `entry-spacing`：单位为标准行高。0 表示条目间无额外空白（紧凑排列），1 表示条目间空一行。中文学术期刊通常使用 0。
• `subsequent-author-substitute`：仅在 bibliography 有 <sort> 且按作者排序时有效。替代符号在中文样式中常用三字线"———"，英文样式中常用三个 em dash "———" 或六个短横线 "------"。
• `sort` 的位置：<sort> 必须是 <bibliography> 的第一个子元素（在 <layout> 之前）。numeric 格式不需要显式排序（默认按 citation-number 排），但 author-date 和 note 格式通常需要按作者+年份排序。
• 双语 layout 的 suffix：中文条目 suffix="。" 和英文条目 suffix="." 是分别设置在各自的 <layout> 元素上的，这样可以确保不同语言的条目使用对应的标点符号。
• `太平洋学报.csl` 的 bibliography 特征：使用 entry-spacing="0"（紧凑）、second-field-align="flush"（编号对齐），带 [n] 编号，中英文条目分别以 。 和 . 结尾。没有显式 <sort>，因为 note 格式的 bibliography 默认按 citation-number 排序。

citation -- citation 元素

参数

模板

numeric: [1], [1, 3], [1-3]

<!-- style 根元素需设置 class="in-text" -->
<citation collapse="citation-number">
  <sort>
    <key variable="citation-number"/>
  </sort>
  <layout prefix="[" suffix="]" delimiter=", ">
    <text variable="citation-number"/>
  </layout>
</citation>

效果：[1]、[1, 3]、[1-3]（连续编号自动合并为范围）。

author-date: (Author, 2024)

<!-- style 根元素需设置 class="in-text" -->
<citation et-al-min="3" et-al-use-first="1" disambiguate-add-year-suffix="true" disambiguate-add-names="true" disambiguate-add-givenname="true" collapse="year">
  <sort>
    <key macro="author"/>
    <key macro="date" sort="ascending"/>
  </sort>
  <layout prefix="(" suffix=")" delimiter="; ">
    <group delimiter=", ">
      <text macro="author-short"/>
      <text macro="date"/>
      <text macro="locator"/>
    </group>
  </layout>
</citation>

效果：(Smith, 2024)、(Smith, 2024a, 2024b)（同作者同年用后缀区分）、(Smith, 2024; Jones, 2023)。

note - 首次引用（完整引用）

参考 太平洋学报.csl 中的实际 note 格式：

<!-- style 根元素需设置 class="note" -->
<citation>
  <!-- 中文条目 layout -->
  <layout delimiter="；" suffix="。" locale="zh">
    <text macro="entry-layout-zh"/>
  </layout>
  <!-- 英文条目 layout（默认） -->
  <layout delimiter="; " suffix=".">
    <text macro="entry-layout-en"/>
  </layout>
</citation>

首次引用时输出完整的书目信息（作者、标题、出版信息、页码等），由 entry-layout-zh 和 entry-layout-en 宏控制。

note - ibid（同上）

在支持 ibid 的 note 样式中，紧接相同来源的重复引用可简化为"同上"：

<citation>
  <layout delimiter="；" suffix="。" locale="zh">
    <choose>
      <if position="ibid-with-locator">
        <group delimiter="，">
          <text term="ibid"/>
          <text macro="locator-zh"/>
        </group>
      </if>
      <else-if position="ibid">
        <text term="ibid"/>
      </else-if>
      <else>
        <text macro="entry-layout-zh"/>
      </else>
    </choose>
  </layout>
  <layout delimiter="; " suffix=".">
    <choose>
      <if position="ibid-with-locator">
        <group delimiter=", ">
          <text term="ibid"/>
          <text macro="locator-en"/>
        </group>
      </if>
      <else-if position="ibid">
        <text term="ibid"/>
      </else-if>
      <else>
        <text macro="entry-layout-en"/>
      </else>
    </choose>
  </layout>
</citation>

中文输出"同上"（由 <term name="ibid">同上</term> 定义），英文输出 "Ibid."。

note - subsequent（简写引用）

后续引用使用简写形式（通常只保留作者+标题缩写+页码）：

<citation>
  <layout delimiter="；" suffix="。" locale="zh">
    <choose>
      <if position="ibid-with-locator">
        <group delimiter="，">
          <text term="ibid"/>
          <text macro="locator-zh"/>
        </group>
      </if>
      <else-if position="ibid">
        <text term="ibid"/>
      </else-if>
      <else-if position="subsequent">
        <group delimiter="，">
          <text macro="author-zh"/>
          <text macro="title-short-zh"/>
          <text macro="locator-zh"/>
        </group>
      </else-if>
      <else>
        <text macro="entry-layout-zh"/>
      </else>
    </choose>
  </layout>
  <layout delimiter="; " suffix=".">
    <choose>
      <if position="ibid-with-locator">
        <group delimiter=", ">
          <text term="ibid"/>
          <text macro="locator-en"/>
        </group>
      </if>
      <else-if position="ibid">
        <text term="ibid"/>
      </else-if>
      <else-if position="subsequent">
        <group delimiter=", ">
          <text macro="author-short-en"/>
          <text macro="title-short-en"/>
          <text macro="locator-en"/>
        </group>
      </else-if>
      <else>
        <text macro="entry-layout-en"/>
      </else>
    </choose>
  </layout>
</citation>

注意事项

• `class` 属性：CSL 的 <style> 根元素必须指定 class="in-text" 或 class="note"。numeric 和 author-date 使用 class="in-text"，note 使用 class="note"。此属性决定 citation 是行内插入还是脚注/尾注。
• `collapse`：citation-number 合并策略仅在 numeric 格式下有效，可将 [1, 2, 3] 合并为 [1-3]。year 和 year-suffix 在 author-date 格式下有效，可将 (Smith, 2024a; Smith, 2024b) 合并为 (Smith, 2024a, b)。
• `disambiguate` 系列属性：在 <citation> 元素上设置，仅对 author-date 格式有意义。disambiguate-add-year-suffix="true" 会给同作者同年的条目添加 a/b/c 后缀。disambiguate-add-names="true" 会展开更多作者名以消除歧义。disambiguate-add-givenname="true" 会添加作者名来区分同姓作者。
• `position` 条件：note 样式中 <if position="..."> 可判断引用位置。支持的值包括 first（首次引用）、ibid（紧接重复引用）、ibid-with-locator（紧接重复引用但有不同页码）、subsequent（非首次非紧接的重复引用）。判断顺序应为 ibid-with-locator > ibid > subsequent > first（else 分支）。
• 双语 layout：如 太平洋学报.csl 所示，通过在 <layout> 上指定 locale="zh" 区分中英文条目。中文条目使用中文标点（分隔符 ；，后缀 。），英文条目使用英文标点（分隔符 ; ，后缀 .）。
• `sort` 元素：在 <citation> 内部的 <sort> 控制同一 citation 中多条引用的排列顺序。numeric 格式通常按 citation-number 排序，author-date 通常按作者+年份排序。note 格式一般不排序（按引用顺序）。
• `太平洋学报.csl` 不使用 position 判断：该样式在 citation 中直接输出完整引用，没有 ibid 或 subsequent 简写。这是因为其《规定》要求每次脚注都给出完整信息。

容器格式

参数

模板

英文期刊（斜体）

典型输出：*American Economic Review*, Vol.112, No.3

<macro name="container-periodical-en">
  <choose>
    <if type="article-newspaper">
      <text variable="container-title" text-case="title"/>
    </if>
    <else>
      <group delimiter=", ">
        <text variable="container-title" text-case="title" font-style="italic"/>
        <group>
          <label variable="volume" form="short" text-case="capitalize-first"/>
          <number variable="volume"/>
        </group>
        <group>
          <label variable="issue" form="short" text-case="capitalize-first"/>
          <number variable="issue"/>
        </group>
      </group>
    </else>
  </choose>
</macro>

说明：<label variable="volume" form="short"/> 输出 "Vol."，<label variable="issue" form="short"/> 输出 "No."。报纸的 container-title 不使用斜体。

英文会议/章节（in Editor, Book Title）

典型输出：in John Smith and Jane Doe eds., *Handbook of Economics*

<macro name="container-booklike-en">
  <choose>
    <if variable="container-title">
      <group delimiter=" ">
        <text term="in"/>
        <group delimiter=", ">
          <names variable="editor">
            <name and="text"/>
            <label form="short" prefix=", "/>
          </names>
          <text variable="container-title" text-case="title" font-style="italic"/>
        </group>
      </group>
    </if>
  </choose>
</macro>

说明：<text term="in"/> 输出小写 "in"。编者姓名使用正常顺序（Given Surname），<label form="short"/> 输出 "eds." 或 "ed."。

GB/T 7714 风格（// 连接）

典型输出：// 张三, 李四. 经济学手册

GB/T 7714 标准使用 // 作为析出文献与来源文献的分隔符。

<macro name="container-booklike-gbt">
  <choose>
    <if variable="container-title">
      <group prefix="// ">
        <group delimiter=". ">
          <names variable="editor">
            <name delimiter=", "/>
          </names>
          <text variable="container-title"/>
        </group>
      </group>
    </if>
  </choose>
</macro>

中文期刊（书名号《》）

典型输出：《太平洋学报》（北京），2024年第3期

<macro name="container-periodical-zh">
  <group delimiter="，">
    <group>
      <text variable="container-title" prefix="《" suffix="》"/>
      <text variable="section" prefix="（" suffix="）"/>
      <text variable="publisher-place" prefix="（" suffix="）"/>
    </group>
    <group>
      <text macro="date-zh"/>
      <choose>
        <if variable="issue">
          <text macro="issue-zh"/>
        </if>
        <else>
          <text macro="volume-zh"/>
        </else>
      </choose>
    </group>
  </group>
</macro>

说明：中文期刊的卷期信息直接跟在日期后面（如"2024年第3期"）。section 用于报纸的版面信息，publisher-place 用于区分同名期刊的出版地。

需要依赖的辅助宏：

<macro name="issue-zh">
  <choose>
    <if is-numeric="issue">
      <text value="第"/>
      <number variable="issue"/>
      <label variable="issue" form="short"/>
    </if>
    <else>
      <text variable="issue"/>
    </else>
  </choose>
</macro>

<macro name="volume-zh">
  <choose>
    <if is-numeric="volume">
      <text value="第"/>
      <number variable="volume"/>
      <label variable="volume" form="short"/>
    </if>
    <else>
      <text variable="volume"/>
    </else>
  </choose>
</macro>

中文章节/会议（冒号连接编者与书名）

典型输出：张三、李四主编：《经济学手册》

<macro name="container-booklike-zh">
  <group delimiter="：">
    <names variable="editor">
      <name delimiter="、"/>
      <label form="short"/>
    </names>
    <group>
      <choose>
        <if variable="container-title">
          <text variable="container-title" prefix="《" suffix="》"/>
          <choose>
            <if type="classic" match="none">
              <text macro="edition-zh" prefix="（" suffix="）"/>
              <text macro="volume-zh"/>
            </if>
          </choose>
        </if>
        <else-if type="paper-conference" variable="event-title" match="all">
          <text variable="event-title"/>
          <text value="论文"/>
        </else-if>
      </choose>
    </group>
  </group>
</macro>

说明：中文用全角冒号 ： 连接编者和书名。编者后附"主编"标签。会议论文若无 container-title 则使用 event-title 加"论文"。

双语完整方案（container-en + container-zh）

<!-- 英文期刊容器 -->
<macro name="container-periodical-en">
  <choose>
    <if type="article-newspaper">
      <text variable="container-title" text-case="title"/>
    </if>
    <else>
      <group delimiter=", ">
        <text variable="container-title" text-case="title" font-style="italic"/>
        <group>
          <label variable="volume" form="short" text-case="capitalize-first"/>
          <number variable="volume"/>
        </group>
        <group>
          <label variable="issue" form="short" text-case="capitalize-first"/>
          <number variable="issue"/>
        </group>
      </group>
    </else>
  </choose>
</macro>

<!-- 英文书籍类容器 -->
<macro name="container-booklike-en">
  <choose>
    <if variable="container-title">
      <group delimiter=" ">
        <text term="in"/>
        <group delimiter=", ">
          <names variable="editor">
            <name and="text"/>
            <label form="short" prefix=", "/>
          </names>
          <text variable="container-title" text-case="title" font-style="italic"/>
        </group>
      </group>
    </if>
  </choose>
</macro>

<!-- 中文期刊容器 -->
<macro name="container-periodical-zh">
  <group delimiter="，">
    <group>
      <text variable="container-title" prefix="《" suffix="》"/>
      <text variable="section" prefix="（" suffix="）"/>
      <text variable="publisher-place" prefix="（" suffix="）"/>
    </group>
    <group>
      <text macro="date-zh"/>
      <choose>
        <if variable="issue">
          <text macro="issue-zh"/>
        </if>
        <else>
          <text macro="volume-zh"/>
        </else>
      </choose>
    </group>
  </group>
</macro>

<!-- 中文书籍类容器 -->
<macro name="container-booklike-zh">
  <group delimiter="：">
    <names variable="editor">
      <name delimiter="、"/>
      <label form="short"/>
    </names>
    <group>
      <choose>
        <if variable="container-title">
          <text variable="container-title" prefix="《" suffix="》"/>
          <choose>
            <if type="classic" match="none">
              <text macro="edition-zh" prefix="（" suffix="）"/>
              <text macro="volume-zh"/>
            </if>
          </choose>
        </if>
        <else-if type="paper-conference" variable="event-title" match="all">
          <text variable="event-title"/>
          <text value="论文"/>
        </else-if>
      </choose>
    </group>
  </group>
</macro>

注意事项

1. 期刊 vs 书籍容器：期刊文章（article-journal/article-magazine）使用期刊容器宏，章节（chapter）和会议论文（paper-conference）使用书籍类容器宏。在 entry-layout 宏中通过 <choose> 按类型调用不同的容器宏。 2. `container-title` vs `collection-title`：container-title 是直接包含当前文献的容器（如期刊名、论文集名），collection-title 是系列丛书名。中文丛书用书名号包裹。 3. 报纸容器：中文报纸有特殊格式，包含出版地、版面号等信息，需要单独的宏处理（如 container-newspaper-zh）。 4. `text-case="title"`：仅对英文容器标题使用。中文不使用 text-case。 5. 卷期信息的位置：英文中卷期跟在期刊名后（如 Journal, Vol.1, No.2），中文中卷期跟在日期后（如 2024年第3期）。 6. `<text term="in"/>`：在中文 locale 中可定义为"载"（<term name="in">载</term>），但实际中文学术引用中更常用冒号或 // 连接，而非"载"字。

日期格式

参数

模板

仅年份

典型输出：2024

<macro name="date">
  <date variable="issued" form="text" date-parts="year"/>
</macro>

完整日期

典型输出（text 格式）：January 15, 2024 典型输出（numeric 格式）：1/15/2024

<!-- text 格式 -->
<macro name="date">
  <date variable="issued" form="text"/>
</macro>

<!-- numeric 格式 -->
<macro name="date">
  <date variable="issued" form="numeric"/>
</macro>

带括号年份 (2024)

典型输出：(2024)

用于 APA 等在作者后紧跟括号年份的风格。

<macro name="date">
  <date variable="issued" prefix="(" suffix=")">
    <date-part name="year"/>
  </date>
</macro>

中文年份（2024年 / 2024年第X期）

典型输出：2024年 / 2024年第3期

<!-- 中文日期宏：按文献类型区分详细程度 -->
<macro name="date-zh">
  <choose>
    <if variable="issued">
      <choose>
        <!-- 报纸、网页等需要完整日期 -->
        <if type="article-newspaper collection manuscript personal_communication post post-weblog software webpage" match="any">
          <date variable="issued" form="text"/>
        </if>
        <!-- 书籍、章节附加"版"字 -->
        <else-if type="book chapter classic" match="any">
          <date variable="issued" form="text" date-parts="year"/>
          <text term="edition" form="short"/>
        </else-if>
        <!-- 其他类型仅显示年份 -->
        <else>
          <date variable="issued" form="text" date-parts="year"/>
        </else>
      </choose>
    </if>
    <!-- 无日期时的回退 -->
    <else-if type="classic post post-weblog software webpage" match="none">
      <text term="no date"/>
    </else-if>
  </choose>
</macro>

说明：中文 locale 下 form="text" 和 date-parts="year" 会输出如 "2024年" 的格式（取决于 locale 的日期格式定义）。<text term="edition" form="short"/> 在 zh locale 下输出"版"。

需要配合的 locale 定义：

<locale xml:lang="zh">
  <terms>
    <term name="edition" form="short">版</term>
    <term name="no date">出版时间不详</term>
  </terms>
</locale>

双语完整方案（date-en + date-zh）

<macro name="date-en">
  <choose>
    <!-- 档案、手稿等需要完整日期 -->
    <if type="collection manuscript personal_communication" match="any">
      <date variable="issued" form="text"/>
    </if>
    <!-- 期刊仅年份 -->
    <else-if type="article-journal article-magazine" match="any">
      <date variable="issued" form="text" date-parts="year"/>
    </else-if>
    <!-- 报纸需要完整日期 -->
    <else-if type="article-newspaper">
      <date variable="issued" form="text"/>
    </else-if>
    <!-- 网页需要完整日期 -->
    <else-if type="post post-weblog webpage" match="any">
      <date variable="issued" form="text"/>
    </else-if>
    <!-- 其他仅年份 -->
    <else>
      <date variable="issued" form="text" date-parts="year"/>
    </else>
  </choose>
</macro>

<macro name="date-zh">
  <choose>
    <if variable="issued">
      <choose>
        <if type="article-newspaper collection manuscript personal_communication post post-weblog software webpage" match="any">
          <date variable="issued" form="text"/>
        </if>
        <else-if type="book chapter classic" match="any">
          <date variable="issued" form="text" date-parts="year"/>
          <text term="edition" form="short"/>
        </else-if>
        <else>
          <date variable="issued" form="text" date-parts="year"/>
        </else>
      </choose>
    </if>
    <else-if type="classic post post-weblog software webpage" match="none">
      <text term="no date"/>
    </else-if>
  </choose>
</macro>

注意事项

1. `form` vs `date-part` 子元素：使用 form="text" 或 form="numeric" 会调用 locale 的预定义日期格式，这是最简单的方式。若需自定义格式，可改用 <date-part> 子元素逐一指定。 2. `date-parts` 属性：只能与 form 一起使用，用于截断日期精度。date-parts="year" 只显示年，date-parts="year-month" 显示年月。 3. 中文"版"字：对于书籍再版，中文习惯在年份后加"版"（如"2020年版"），通过 <text term="edition" form="short"/> 实现。 4. 无日期处理：当 issued 变量为空时，英文输出 "n.d."（CSL 默认），中文可通过 locale 定义 <term name="no date">出版时间不详</term> 自定义。 5. `original-date`：用于古籍的原始年代（年号等），通过单独的宏处理：

   <macro name="original-date-zh">
     <date variable="original-date">
       <date-part name="year"/>
     </date>
   </macro>

6. 括号年份：使用 prefix="(" suffix=")" 直接在 <date> 元素上添加，而非包裹在 <group> 中，以确保无日期时括号也不会输出。

locale-en -- 英文本地化

参数

模板

英文 locale（使用 hyphen 作页码连接号）

参考 太平洋学报.csl 中的实际定义：

<locale xml:lang="en">
  <style-options punctuation-in-quote="false"/>
  <terms>
    <!-- 英文页码的连接号使用 hyphen -->
    <term name="page-range-delimiter">-</term>
    <term name="translator" form="short">trans.</term>
  </terms>
</locale>

英文 locale（使用 en dash 作页码连接号）

部分英文期刊（如 APA、Chicago）要求使用 en dash：

<locale xml:lang="en">
  <style-options punctuation-in-quote="true"/>
  <terms>
    <term name="page-range-delimiter">&#8211;</term>
    <term name="translator" form="short">trans.</term>
  </terms>
</locale>

英文 locale（美式标点规则）

美式英语将逗号和句号放在引号内：

<locale xml:lang="en">
  <style-options punctuation-in-quote="true"/>
  <terms>
    <term name="page-range-delimiter">&#8211;</term>
    <term name="translator" form="short">trans.</term>
  </terms>
</locale>

英文 locale（英式标点规则）

英式英语将标点放在引号外（中文学术期刊常用此设置）：

<locale xml:lang="en">
  <style-options punctuation-in-quote="false"/>
  <terms>
    <term name="page-range-delimiter">-</term>
    <term name="translator" form="short">trans.</term>
  </terms>
</locale>

注意事项

• `punctuation-in-quote`：此选项控制句号和逗号是否移入引号内。设为 true 时，"Title", 变为 "Title," ——这是美式英语的标点规则。中文社科期刊引用英文文献时通常设为 false。
• `page-range-delimiter`：CSL 规范默认使用 en dash (–, –)。如果期刊要求使用 hyphen (-)，需要在 locale 中显式覆盖。注意此设置需要配合 <style> 根元素的 page-range-format 属性才能生效。
• `translator` 缩写：form="short" 的 translator 术语用于 <label form="short"/> 输出。英文中通常缩写为 trans.，显示为 trans. John Smith 或 John Smith, trans.（取决于 <names> 中 <label> 的位置）。
• `xml:lang="en"` 的匹配范围：此 locale 会匹配所有以 en 开头的语言（en-US、en-GB 等），除非有更具体的 locale 块（如 xml:lang="en-GB"）覆盖。
• 与 `default-locale` 的关系：<style> 根元素的 default-locale 属性决定了没有 language 字段的条目使用哪个 locale。如果设为 default-locale="en-US"，则无语言标记的条目默认按英文处理。

locale-zh -- 中文本地化 + 双语模式

参数

模板

完整中文 locale 术语覆盖

参考 太平洋学报.csl 中的实际定义：

<locale xml:lang="zh">
  <terms>
    <term name="anonymous">佚名</term>
    <term name="edition" form="short">版</term>
    <term name="ibid">同上</term>
    <term name="in">载</term>
    <term name="no date">出版时间不详</term>
    <term name="open-quote">"</term>
    <term name="close-quote">"</term>
    <term name="open-inner-quote">'</term>
    <term name="close-inner-quote">'</term>
    <!-- 中文页码的连接号使用一字线（em dash） -->
    <term name="page-range-delimiter">&#8212;</term>
    <term name="author" form="short">著</term>
    <term name="editor" form="short">主编</term>
    <term name="compiler" form="short">整理</term>
    <term name="thesis">博士论文</term>
  </terms>
</locale>

citation 双语 layout（zh + default）

在 <citation> 中通过 locale 属性区分中英文条目的渲染方式。Zotero 根据条目的 language 字段判断是否匹配 zh locale：

<citation>
  <!-- 中文条目使用此 layout -->
  <layout delimiter="；" suffix="。" locale="zh">
    <text macro="entry-layout-zh"/>
  </layout>
  <!-- 非中文条目（默认）使用此 layout -->
  <layout delimiter="; " suffix=".">
    <text macro="entry-layout-en"/>
  </layout>
</citation>

bibliography 双语 layout（zh + default）

<bibliography entry-spacing="0" second-field-align="flush">
  <!-- 中文条目 -->
  <layout locale="zh">
    <text variable="citation-number" prefix="[" suffix="]"/>
    <text macro="entry-layout-zh" suffix="。"/>
  </layout>
  <!-- 非中文条目（默认） -->
  <layout>
    <text variable="citation-number" prefix="[" suffix="]"/>
    <text macro="entry-layout-en" suffix="."/>
  </layout>
</bibliography>

注意事项

• 双语 layout 机制：CSL 1.0 支持在 <layout> 上指定 locale 属性。Zotero 会检查条目的 language 字段，若以 zh 开头（如 zh、zh-CN、zh-TW），则匹配带有 locale="zh" 的 layout；否则使用不带 locale 的默认 layout。
• `language` 字段的填写：用户需要在 Zotero 条目的「语言」字段中填入 zh 或 zh-CN，否则中文条目将按英文 layout 渲染。
• 引号覆盖：中文引号 "" 和 '' 通过覆盖 open-quote/close-quote/open-inner-quote/close-inner-quote 四个术语实现。在 XML 中使用 quotes="true" 属性时会自动使用这些引号。
• page-range-delimiter：— 是 Unicode em dash（一字线 —），用于中文页码范围（如"第 23—45 页"）。必须同时在 <style> 根元素上设置 page-range-format="expanded" 才能正确展开页码。
• author/editor/compiler 的 `form="short"`：这些术语在 <label form="short"/> 时输出，用于在作者名后追加角色标签（如"张三著""李四主编"）。
• `et-al` 和 `and`：如果使用 CSL 内置的 <name> 元素的 et-al-min/et-al-use-first 属性来截断作者列表，et-al 术语会被自动使用。中文 locale 下默认应为"等"。and 术语在 <name and="text"> 时用于连接最末两位作者。
• `ibid` 术语：仅在 note 样式（class="note"）中且使用 position="ibid" 条件判断时生效。

卷/期/页

参数

模板

紧凑格式: 15(3): 245-260

典型输出：15(3): 245-260

<!-- 卷期部分（通常嵌入容器宏中） -->
<group>
  <number variable="volume"/>
  <number variable="issue" prefix="(" suffix=")"/>
</group>

<!-- 页码部分（通常作为独立宏） -->
<macro name="page">
  <number variable="page"/>
</macro>

完整组合示例（在容器宏内）：

<macro name="container-periodical">
  <group delimiter=", ">
    <text variable="container-title" font-style="italic"/>
    <group>
      <number variable="volume"/>
      <number variable="issue" prefix="(" suffix=")"/>
    </group>
  </group>
</macro>

<!-- 页码在 entry-layout 中单独引用 -->
<macro name="page">
  <number variable="page"/>
</macro>

英文标签: Vol. 15, No. 3, pp. 245-260

典型输出：Vol. 15, No. 3, pp. 245-260

<!-- 卷 -->
<macro name="volume-en">
  <choose>
    <if is-numeric="volume">
      <label variable="volume" form="short" suffix=" "/>
      <number variable="volume"/>
    </if>
    <else>
      <text variable="volume"/>
    </else>
  </choose>
</macro>

<!-- 期刊容器中包含卷期 -->
<macro name="container-periodical-en">
  <group delimiter=", ">
    <text variable="container-title" text-case="title" font-style="italic"/>
    <group>
      <label variable="volume" form="short" text-case="capitalize-first"/>
      <number variable="volume"/>
    </group>
    <group>
      <label variable="issue" form="short" text-case="capitalize-first"/>
      <number variable="issue"/>
    </group>
  </group>
</macro>

<!-- 页码 -->
<macro name="page-en">
  <choose>
    <if is-numeric="page">
      <label variable="page" form="short"/>
      <number variable="page"/>
    </if>
    <else>
      <text variable="page"/>
    </else>
  </choose>
</macro>

说明：<label variable="volume" form="short"/> 输出 "Vol."，<label variable="issue" form="short"/> 输出 "No."，<label variable="page" form="short"/> 输出 "p." 或 "pp."（自动根据单页/多页切换）。

页码范围连接号通过 locale 控制：

<locale xml:lang="en">
  <terms>
    <term name="page-range-delimiter">-</term>
  </terms>
</locale>

中文格式: 第15卷第3期，第245-260页

典型输出：第15卷第3期，第245—260页

<!-- 卷 -->
<macro name="volume-zh">
  <choose>
    <if is-numeric="volume">
      <text value="第"/>
      <number variable="volume"/>
      <label variable="volume" form="short"/>
    </if>
    <else>
      <text variable="volume"/>
    </else>
  </choose>
</macro>

<!-- 期 -->
<macro name="issue-zh">
  <choose>
    <if is-numeric="issue">
      <text value="第"/>
      <number variable="issue"/>
      <label variable="issue" form="short"/>
    </if>
    <else>
      <text variable="issue"/>
    </else>
  </choose>
</macro>

<!-- 页码 -->
<macro name="page-zh">
  <choose>
    <if is-numeric="page">
      <text value="第"/>
      <number variable="page"/>
      <choose>
        <if type="article-newspaper">
          <text value="版"/>
        </if>
        <else>
          <label variable="page" form="short"/>
        </else>
      </choose>
    </if>
    <else>
      <text variable="page"/>
    </else>
  </choose>
</macro>

说明：中文的 <label variable="volume" form="short"/> 需在 locale 中定义为"卷"，<label variable="issue" form="short"/> 为"期"，<label variable="page" form="short"/> 为"页"。报纸的页码用"版"而非"页"。

中文页码范围使用一字线（em dash）：

<locale xml:lang="zh">
  <terms>
    <term name="page-range-delimiter">&#8212;</term>
  </terms>
</locale>

Locator（引用定位）

除了 page（参考文献的页码范围），CSL 还支持 locator（引注中的具体位置）。两者格式类似但用途不同：

<!-- 英文 locator -->
<macro name="locator-en">
  <choose>
    <if is-numeric="locator">
      <label variable="locator" form="short"/>
      <number variable="locator"/>
    </if>
    <else>
      <text variable="locator"/>
    </else>
  </choose>
</macro>

<!-- 中文 locator -->
<macro name="locator-zh">
  <choose>
    <if is-numeric="locator">
      <text value="第"/>
      <number variable="locator"/>
      <choose>
        <if type="article-newspaper" locator="page" match="all">
          <text value="版"/>
        </if>
        <else>
          <label variable="locator" form="short"/>
        </else>
      </choose>
    </if>
    <else>
      <text variable="locator"/>
    </else>
  </choose>
</macro>

<!-- 优先显示 locator，无 locator 时显示 page -->
<macro name="locator-or-page-en">
  <choose>
    <if variable="locator">
      <text macro="locator-en"/>
    </if>
    <else>
      <text macro="page-en"/>
    </else>
  </choose>
</macro>

<macro name="locator-or-page-zh">
  <choose>
    <if variable="locator">
      <text macro="locator-zh"/>
    </if>
    <else-if type="article-journal article-magazine" match="none">
      <text macro="page-zh"/>
    </else-if>
  </choose>
</macro>

说明：locator-or-page 宏的逻辑是：有 locator 时优先显示 locator（用户在引注中指定的具体页码），否则显示 page（参考文献的完整页码范围）。中文期刊文章不显示 page（页码信息已包含在期刊容器中）。

注意事项

1. `<number>` vs `<text variable>`：对于卷、期、页码，优先使用 <number> 元素，它支持 is-numeric 条件判断和自动格式化。<text variable="..."/> 适用于非数字内容的回退。 2. `is-numeric` 判断：使用 <choose><if is-numeric="volume"> 来区分纯数字和非数字卷号。非数字时直接输出原文（如 "Special Issue"）。 3. `page-range-format`：在 <style> 根元素上设置，控制页码范围的压缩方式。expanded = 完整显示（245-260），chicago = Chicago 风格压缩（245-60）。 4. `page-range-delimiter`：通过 locale term 控制，英文通常用连字符 - 或 en dash –，中文用一字线（em dash —）。 5. 卷期与容器的关系：卷期信息通常嵌入容器宏中，而非作为独立宏。英文格式中卷期紧跟期刊名，中文格式中卷期跟在日期之后。 6. 报纸的"版"：中文报纸的 page 不是"页"而是"版"（如"第3版"），需在 page 宏中特殊处理。

作者/姓名格式

参数

模板

标准英文（Surname Initial, 逗号分隔）

典型输出：Smith J. K., Johnson L. M., Wang H.

<macro name="author">
  <names variable="author">
    <name name-as-sort-order="all" sort-separator=", " initialize-with=". " delimiter=", "/>
    <substitute>
      <names variable="editor"/>
    </substitute>
  </names>
</macro>

APA 风格（Surname, I., & 连接）

典型输出：Smith, J. K., Johnson, L. M., & Wang, H.

<macro name="author">
  <names variable="author">
    <name name-as-sort-order="all" sort-separator=", " initialize-with=". "
          delimiter=", " and="symbol" delimiter-precedes-last="always"/>
    <substitute>
      <names variable="editor"/>
    </substitute>
  </names>
</macro>

带 et al. 省略（7 人以上只显示前 6 人）：

<macro name="author">
  <names variable="author">
    <name name-as-sort-order="all" sort-separator=", " initialize-with=". "
          delimiter=", " and="symbol" delimiter-precedes-last="always"
          et-al-min="7" et-al-use-first="6"/>
    <substitute>
      <names variable="editor"/>
    </substitute>
  </names>
</macro>

中文风格（姓名全称，顿号分隔，加"著/主编"标签）

典型输出（book 类型）：王明远、李华著 / 张三、李四主编

<macro name="author-zh">
  <choose>
    <if type="book classic" match="any">
      <names variable="author">
        <name delimiter="、"/>
        <label form="short"/>
        <substitute>
          <names variable="editor"/>
          <names variable="compiler"/>
        </substitute>
      </names>
    </if>
    <else>
      <names variable="author">
        <name delimiter="、"/>
        <substitute>
          <names variable="editor">
            <name delimiter="、"/>
            <label form="short"/>
          </names>
          <names variable="compiler">
            <name delimiter="、"/>
            <label form="short"/>
          </names>
        </substitute>
      </names>
    </else>
  </choose>
</macro>

说明：中文 <name> 不设置 initialize-with，确保显示全名。<label form="short"/> 在 zh locale 下输出"著""主编""整理"等标签（需配合 locale 定义）。Book 类型直接在作者后附标签，非 book 类型仅在 substitute 的 editor/compiler 后附标签。

需要配合的 locale 定义：

<locale xml:lang="zh">
  <terms>
    <term name="author" form="short">著</term>
    <term name="editor" form="short">主编</term>
    <term name="compiler" form="short">整理</term>
  </terms>
</locale>

双语（author-en + author-zh 两个宏）

同时定义两个宏，在 <citation> / <bibliography> 的 <layout locale="zh"> 和默认 <layout> 中分别调用。

<macro name="author-en">
  <names variable="author">
    <name and="text"/>
    <label form="short" prefix=", "/>
    <substitute>
      <names variable="editor"/>
      <names variable="compiler"/>
    </substitute>
  </names>
</macro>

<macro name="author-zh">
  <choose>
    <if type="book classic" match="any">
      <names variable="author">
        <name delimiter="、"/>
        <label form="short"/>
        <substitute>
          <names variable="editor"/>
          <names variable="compiler"/>
        </substitute>
      </names>
    </if>
    <else>
      <names variable="author">
        <name delimiter="、"/>
        <substitute>
          <names variable="editor">
            <name delimiter="、"/>
            <label form="short"/>
          </names>
          <names variable="compiler">
            <name delimiter="、"/>
            <label form="short"/>
          </names>
        </substitute>
      </names>
    </else>
  </choose>
</macro>

注意事项

1. `initialize` 与 `initialize-with` 的关系：initialize-with 同时控制是否缩写和缩写字符。若要显示全名但仍需 initialize-with 定义的句点格式，需在 <style> 根元素上设 initialize="false"。 2. 中文姓名不应缩写：中文宏中不设 initialize-with，CSL 会自动显示全名。 3. `<label>` 位置：<label> 必须作为 <names> 的直接子元素，紧跟 <name> 之后。它输出的是 <names> 对应 variable 的角色标签（如 author/editor）。 4. `<substitute>` 的回退逻辑：当 author 为空时依次尝试 editor -> compiler。substitute 内的 <names> 可以有自己的 <name> 和 <label> 子元素来覆盖格式。 5. 英文默认 delimiter：<name> 的默认 delimiter 是 ", "，默认 and 是不设置（即不加连接词），所以 <name and="text"/> 会输出 "A, B, and C"。 6. `delimiter-precedes-last`：APA 要求始终在 & 前加逗号（Oxford comma），所以设为 always。

出版信息

参数

模板

标准：New York: Academic Press

典型输出：New York: Academic Press

<macro name="publisher">
  <group delimiter=": ">
    <text variable="publisher-place"/>
    <text variable="publisher"/>
  </group>
</macro>

也可以反转顺序（Publisher, Place）：

<macro name="publisher">
  <group delimiter=", ">
    <text variable="publisher"/>
    <text variable="publisher-place"/>
  </group>
</macro>

仅出版社

典型输出：Academic Press

参考文件中英文出版社宏的实际做法——只输出出版社名称，不含出版地：

<macro name="publisher-en">
  <text variable="publisher"/>
</macro>

说明：部分人文社科风格（如太平洋学报）英文引用中只需要出版社名称，不要求出版地。

中文出版社

典型输出：商务印书馆 / 北京：商务印书馆

<!-- 仅出版社 -->
<macro name="publisher-zh">
  <text variable="publisher"/>
</macro>

<!-- 含出版地 -->
<macro name="publisher-zh">
  <group delimiter="：">
    <text variable="publisher-place"/>
    <text variable="publisher"/>
  </group>
</macro>

说明：中文使用全角冒号 ： 连接出版地与出版社。部分风格（如 GB/T 7714）要求包含出版地，部分风格（如太平洋学报）省略出版地。

学位论文（仅学校名）

典型输出（英文）：Harvard University 典型输出（中文）：北京大学，博士论文

学位论文的 publisher 字段通常存储学校名。

<!-- 英文学位论文 -->
<macro name="publisher-en">
  <text variable="publisher"/>
</macro>

<!-- 中文学位论文（含论文类型） -->
<macro name="publisher-zh">
  <choose>
    <if type="thesis">
      <text variable="publisher"/>
      <group delimiter="，">
        <choose>
          <if variable="genre">
            <text variable="genre"/>
          </if>
          <else>
            <text term="thesis"/>
          </else>
        </choose>
      </group>
    </if>
    <else>
      <text variable="publisher"/>
    </else>
  </choose>
</macro>

说明：英文学位论文的类型信息（Ph.D. Dissertation）通常在标题宏中处理（参见 title.md），出版社宏只输出学校名。中文学位论文的类型标签（博士论文/硕士论文）放在出版社宏中，通过 genre 变量获取用户填写的类型，无 genre 时回退到 locale term <term name="thesis">博士论文</term>。

需要配合的 locale 定义：

<locale xml:lang="zh">
  <terms>
    <term name="thesis">博士论文</term>
  </terms>
</locale>

双语完整方案（publisher-en + publisher-zh）

<macro name="publisher-en">
  <text variable="publisher"/>
</macro>

<macro name="publisher-zh">
  <choose>
    <if type="thesis">
      <text variable="publisher"/>
      <group delimiter="，">
        <choose>
          <if variable="genre">
            <text variable="genre"/>
          </if>
          <else>
            <text term="thesis"/>
          </else>
        </choose>
      </group>
    </if>
    <else>
      <text variable="publisher"/>
    </else>
  </choose>
</macro>

会议/事件出版信息

会议论文若无 container-title，则出版信息来自 event 相关字段：

<!-- 英文会议 -->
<macro name="event-en">
  <choose>
    <if variable="container-title" match="none">
      <group delimiter=", ">
        <group delimiter=" ">
          <text value="Paper Prepared for"/>
          <text variable="event-title"/>
        </group>
        <names variable="organizer">
          <name delimiter="、"/>
          <substitute>
            <text variable="publisher"/>
            <text variable="publisher-place"/>
          </substitute>
        </names>
        <choose>
          <if variable="event-date">
            <date variable="event-date" form="text"/>
          </if>
          <else>
            <date variable="issued" form="text"/>
          </else>
        </choose>
      </group>
    </if>
  </choose>
</macro>

<!-- 中文会议 -->
<macro name="event-zh">
  <choose>
    <if variable="container-title" match="none">
      <group delimiter="，">
        <group>
          <text variable="event-title"/>
          <text value="论文"/>
        </group>
        <names variable="organizer">
          <name delimiter="、"/>
          <substitute>
            <text variable="publisher"/>
            <text variable="publisher-place"/>
          </substitute>
        </names>
        <choose>
          <if variable="event-date">
            <date variable="event-date" form="text"/>
          </if>
          <else>
            <date variable="issued" form="text"/>
          </else>
        </choose>
      </group>
    </if>
  </choose>
</macro>

注意事项

1. 出版地的取舍：不同引用风格对出版地的要求不同。APA 第 7 版已取消出版地要求，GB/T 7714 仍要求出版地。根据目标风格决定是否包含 publisher-place。 2. 中英文标点差异：英文用半角冒号+空格 ": "，中文用全角冒号 "："。 3. 学位论文的特殊性：publisher 在学位论文中存储的是学校名而非出版社名。英文论文类型放在 title 宏中，中文论文类型放在 publisher 宏中——这是两种语言风格的习惯差异。 4. `publisher-place` 的多用途：该变量在不同文献类型中含义不同——书籍中是出版地，报纸中是发行地，档案中是馆藏地。容器宏和出版社宏需要注意不要重复输出。 5. 缺失值处理：当 publisher 或 publisher-place 为空时，<group> 会自动抑制分隔符。不需要额外的条件判断。 6. 与容器宏的配合：在 entry-layout 宏中，出版社信息通常跟在容器信息之后。对于期刊文章，不需要出版社信息（期刊名已足够）；对于书籍和章节，出版社信息必不可少。

标题格式

参数

模板

纯文本（所有类型无格式）

所有文献类型标题均为纯文本，无引号、无斜体、无书名号。

<macro name="title">
  <text variable="title"/>
</macro>

英文学术（book=italic, article=quotes）

典型输出：

• article-journal: "The Role of Institutions in Growth"
• book: The Wealth of Nations
• thesis: "Essays on Economic Growth", Ph.D. Dissertation
• webpage: Policy Brief on Climate

<macro name="title-en">
  <choose>
    <if type="article-journal article-magazine article-newspaper chapter paper-conference report" match="any">
      <text variable="title" text-case="title" quotes="true"/>
    </if>
    <else-if type="thesis">
      <group delimiter=", ">
        <text variable="title" text-case="title" quotes="true"/>
        <choose>
          <if variable="genre">
            <text variable="genre" text-case="title"/>
          </if>
          <else>
            <text value="Ph.D. Dissertation"/>
          </else>
        </choose>
      </group>
    </else-if>
    <else-if type="post post-weblog webpage" match="any">
      <text variable="title" text-case="title" font-style="italic"/>
    </else-if>
    <else>
      <!-- book, report 等独立出版物 -->
      <text variable="title" text-case="title" font-style="italic"/>
    </else>
  </choose>
</macro>

说明：quotes="true" 使用 locale 中定义的引号字符（英文默认为 ""，中文可配置为 ""）。text-case="title" 将标题转为 Title Case。

中文学术（book=书名号《》, article=引号""）

典型输出：

• article-journal: "制度变迁与经济增长"
• book: 《国富论》
• webpage: "气候政策简报"

<macro name="title-zh">
  <choose>
    <if type="article-journal article-magazine article-newspaper" match="any">
      <text variable="title" quotes="true"/>
    </if>
    <else-if type="post post-weblog webpage" match="any">
      <text variable="title" quotes="true"/>
    </else-if>
    <else>
      <!-- book, chapter, thesis 等使用书名号 -->
      <text variable="title" prefix="《" suffix="》"/>
    </else>
  </choose>
</macro>

说明：中文引号通过 locale 定义 <term name="open-quote">"</term> 和 <term name="close-quote">"</term> 实现，quotes="true" 会自动使用 locale 引号。书名号则通过 prefix/suffix 手动添加。

需要配合的 locale 定义：

<locale xml:lang="zh">
  <terms>
    <term name="open-quote">"</term>
    <term name="close-quote">"</term>
    <term name="open-inner-quote">'</term>
    <term name="close-inner-quote">'</term>
  </terms>
</locale>

双语（title-en + title-zh）

完整双语方案，包含 volume 信息和 edition 处理：

<macro name="title-en">
  <choose>
    <if type="article-journal article-magazine article-newspaper chapter paper-conference report" match="any">
      <text variable="title" text-case="title" quotes="true"/>
    </if>
    <else-if type="thesis">
      <group delimiter=", ">
        <text variable="title" text-case="title" quotes="true"/>
        <choose>
          <if variable="genre">
            <text variable="genre" text-case="title"/>
          </if>
          <else>
            <text value="Ph.D. Dissertation"/>
          </else>
        </choose>
      </group>
    </else-if>
    <else-if type="collection manuscript personal_communication software" match="any">
      <text variable="title" text-case="title"/>
    </else-if>
    <else-if type="post post-weblog webpage" match="any">
      <text variable="title" text-case="title" font-style="italic"/>
    </else-if>
    <else>
      <group delimiter=", ">
        <text variable="title" text-case="title" font-style="italic"/>
        <text macro="volume-en"/>
      </group>
    </else>
  </choose>
</macro>

<macro name="title-zh">
  <choose>
    <if type="article-journal article-magazine article-newspaper" match="any">
      <text variable="title" quotes="true"/>
    </if>
    <else-if type="post post-weblog webpage" match="any">
      <text variable="title" quotes="true"/>
    </else-if>
    <else>
      <text variable="title" prefix="《" suffix="》"/>
      <choose>
        <if variable="container-title" match="none">
          <text macro="edition-zh" prefix="（" suffix="）"/>
          <text macro="volume-zh"/>
        </if>
      </choose>
    </else>
  </choose>
</macro>

注意事项

1. `quotes="true"` vs 手动引号：始终使用 quotes="true" 而非手动添加引号字符，这样可以通过 locale 统一控制引号样式，也能正确处理嵌套引号（inner-quote）。 2. 书名号只能手动添加：CSL 没有内置的书名号支持，必须通过 prefix="《" suffix="》" 实现。 3. `text-case="title"`：仅对英文有效，会将标题转为 Title Case。中文宏中不应使用此属性。 4. thesis 的 genre 字段：用于区分硕士/博士论文。若用户未填写 genre，英文默认输出 "Ph.D. Dissertation"，中文可通过 locale term <term name="thesis">博士论文</term> 控制。 5. book 类型的 volume：英文中 volume 信息附加在标题后（如 Title, Vol. 2），中文中 volume 放在书名号之后（如《书名》第2卷）。 6. classic 类型：古籍类型在中文中有特殊处理（年代前缀、卷册分层），需要单独处理，参见参考 CSL 文件中的 title-zh 宏。

name

name-as-sort-order: all
sort-separator: ", "
initialize-with: ". "           # 缩写名带句点+空格: I. M.
delimiter: ", "
and: symbol                     # & 连接最后两位
et-al-min: 21
et-al-use-first: 19
delimiter-precedes-last: always  # Oxford comma: A, B, & C
delimiter-precedes-et-al: always

是否双语: 否                     # 纯英文

citation

format: author-date
collapse: year
prefix: "("
suffix: ")"
delimiter: "; "
disambiguate: add-year-suffix   # 同作者同年加 a/b 后缀
sort: author+year
# citation 内 et-al: min=3, use-first=1（行内引用更激进省略）

bibliography

hanging-indent: true
second-field-align:             # 不设置
entry-spacing: 1
line-spacing: 2                 # APA 要求双倍行距
sort: author+year               # 按作者姓氏 + 年份排序
numbering: false                # 无编号
suffix: "."

title

article-journal: plain          # 期刊文章标题：纯文本（sentence case）
book: italic                    # 书名：斜体
chapter: plain                  # 章节标题：纯文本
thesis: italic                  # 学位论文：斜体
webpage: italic                 # 网页标题：斜体

是否双语: 否

date

default-parts: year
form: text
括号: 有                         # 作者后紧跟 (2024)

container

journal: italic                 # 期刊名：斜体
book-in: "in"                   # 章节用 "In Editor (Ed.), Book Title"
conference: "in"

是否双语: 否

publisher

# APA 7 仅出版社，不含出版地
format: 仅 Publisher

access

doi: prefix                     # 输出完整链接 https://doi.org/10.xxxx
url: webpage-only               # 仅网页类型显示 URL
accessed-date: false            # APA 7 通常不要求访问日期

locators

volume-format: 纯数字            # 斜体卷号（继承容器斜体后紧跟）
issue-format: (X)               # 非斜体括号期号
page-format: 纯数字              # 纯数字页码，无 pp. 前缀
page-range-delimiter: "–"       # en dash
separator: ", "

locale-en

page-range-delimiter: "\u2013"   # en dash –
punctuation-in-quote: true       # 美式标点：句号逗号在引号内
translator-form-short: "trans."

name

# 脚注中的作者（名在前 Given Surname）
name-as-sort-order:             # 不设置，默认名在前
sort-separator: ", "
initialize-with:                # 不设置，显示全名
initialize: true
delimiter: ", "
and: text                       # "and" 连接最后两位
et-al-min: 4
et-al-use-first: 1
delimiter-precedes-last: contextual

# 参考文献中的作者（姓在前 Surname, Given）
# bibliography 中覆盖:
#   name-as-sort-order: first   # 仅第一作者倒序
#   sort-separator: ", "
#   and: text
#   delimiter: ", "

是否双语: 否

citation

format: note
collapse:                       # 不设置
prefix:                         # 不设置（脚注格式无行内前缀）
suffix:                         # 不设置
delimiter: "; "
note-position: first / ibid / subsequent
  # first: 完整引用（作者全名+标题+出版信息+页码）
  # ibid: "Ibid." 或 "Ibid., 页码"
  # ibid-with-locator: "Ibid., 页码"
  # subsequent: 简写（Surname, Title-short, 页码）
sort:                           # 不设置（按引用顺序）

bibliography

hanging-indent: true
second-field-align:             # 不设置（无编号，用悬挂缩进）
entry-spacing: 0
line-spacing: 1
sort: author+year               # 按作者姓氏+年份排序
subsequent-author-substitute: "———"   # 连续相同作者用三字线替代
suffix: "."
numbering: false

title

# book/report 等独立出版物: 斜体
article-journal: quotes         # 期刊文章用引号
book: italic                    # 书籍用斜体
chapter: quotes                 # 章节用引号
thesis: quotes                  # 学位论文用引号
webpage: italic                 # 网页用斜体

是否双语: 否

date

default-parts: year
form: text
括号: 无
# 脚注中日期作为出版信息的一部分，用括号包裹
# 参考文献中日期紧跟作者后，也可加括号

中文年份: 无

container

# 期刊名: 斜体
journal: italic

# 章节/会议: "in" 连接
book-in: "in"
conference: "in"

是否双语: 否

publisher

# Place: Publisher
format: "Place: Publisher"

是否双语: 否

access

doi: false
url: webpage-only
accessed-date: false

locators

# 卷期: 紧凑格式
volume-format: 纯数字
issue-format: ", no. X"          # 小写 no.
page-format: 纯数字
separator: ": "                  # 卷期与页码之间

locale-en

page-range-delimiter: "\u2013"   # en dash –
punctuation-in-quote: true       # 美式标点（逗号句号在引号内）
translator-form-short: "trans."

name

# 英文作者（名在前 Given Surname，全名）
name-as-sort-order:             # 不设置，名在前
sort-separator: ", "
initialize-with: ". "           # 缩写首字母（initialize="false" 在 style 根元素上阻止缩写）
initialize: false               # 设在 <style> 根元素，实际不缩写
delimiter: ", "
and: text                       # "and" 连接
et-al-min:                      # 不设置，显示全部作者
et-al-use-first:                # 不设置

# 中文作者
# delimiter: "、"（顿号分隔）
# 不设 initialize-with，显示全名
# 不设 and（中文不使用连接词）
# book 类型: 作者名后附"著"标签（<label form="short"/>）
# 非 book 类型: 仅 substitute 的 editor/compiler 附标签

是否双语: 是

citation

format: note
collapse:                       # 不设置
prefix:                         # 不设置
suffix:                         # 不设置
delimiter: "; "                 # 英文多条引用分隔
# 中文 delimiter: "；"（全角分号）
# 英文 suffix: "."
# 中文 suffix: "。"
note-position: first / ibid     # 首次完整引用 + ibid 简写
  # first: 完整引用（entry-layout-zh / entry-layout-en）
  # ibid: 中文"同上"，英文 "Ibid."
  # ibid-with-locator: "同上，第X页" / "Ibid., p. X"
  # subsequent: 不使用（太平洋学报不区分 subsequent，每次完整引用）
sort:                           # 不设置（按引用顺序）

bibliography

hanging-indent: false
second-field-align: flush       # [1] 编号后文字左对齐
entry-spacing: 0                # 紧凑排列
line-spacing: 1
sort: citation-number           # 按引用编号排序（note 格式 bibliography 默认）
numbering: true                 # [1] 编号
suffix: "."                     # 英文条目结尾
# 中文条目 suffix: "。" （通过双语 layout 分别设置）

title

# 英文
article-journal: quotes         # "Article Title"（引号）
book: italic                    # *Book Title*（斜体）
chapter: quotes                 # "Chapter Title"
thesis: quotes                  # "Thesis Title", Ph.D. Dissertation
webpage: italic                 # *Webpage Title*

# 中文
# article-journal: 引号 ""（quotes="true"，使用 locale 中文引号）
# book: 书名号《》（prefix/suffix 手动添加）
# chapter: 书名号《》
# thesis: 书名号《》
# webpage: 引号 ""

是否双语: 是

date

# 英文：根据类型决定精度
# 期刊: 仅年份 year
# 报纸/网页: 完整日期 text
# 其他: 仅年份 year
default-parts: year
form: text
括号: 无

# 中文：2024年 / 2024年版
# book/chapter: 年份 + "版"（<text term="edition" form="short"/>）
# 报纸/网页: 完整日期
# 其他: 仅年份
# 无日期: "出版时间不详"
中文年份: 有

container

# 英文期刊: 斜体 + Vol./No. 标签
journal: italic
# 英文章节/会议: "in" 连接
book-in: "in"
conference: "in"

# 中文期刊: 书名号《》 + 2024年第X期
# 中文章节/会议: 冒号连接编者与书名
# journal: 书名号
# book-in: "："（编者主编：《书名》）
# conference: "："

是否双语: 是

publisher

# 英文: 仅出版社名（不含出版地）
format: "Publisher"

# 中文: 仅出版社名
# thesis 特殊: 学校名 + 论文类型（博士论文/硕士论文）

是否双语: 是

access

doi: false
url: webpage-only               # 仅 post/webpage 等类型显示 URL
accessed-date: false

locators

# 英文
volume-format: "Vol. X"         # <label variable="volume" form="short"/>
issue-format: "No. X"           # <label variable="issue" form="short"/>
page-format: "pp. X"            # <label variable="page" form="short"/>，自动 p./pp.
separator: ", "

# 中文
# volume-format: "第X卷"
# issue-format: "第X期"
# page-format: "第X页"（报纸为"第X版"）
# page-range-delimiter: "—"（一字线 em dash）

locale-zh

et-al: "等"
and: "和"
edition: "版"
ibid: "同上"
in: "载"
no-date: "出版时间不详"
open-quote: "\u201C"            # "
close-quote: "\u201D"           # "
open-inner-quote: "\u2018"      # '
close-inner-quote: "\u2019"     # '
page-range-delimiter: "\u2014"  # em dash —（一字线）
author: "著"
editor: "主编"
compiler: "整理"
thesis: "博士论文"
anonymous: "佚名"

locale-en

page-range-delimiter: "-"       # hyphen
punctuation-in-quote: false     # 英式标点（中文社科期刊常用）
translator-form-short: "trans."

name

# 英文作者
name-as-sort-order: all
sort-separator: ", "
initialize-with: " "
delimiter: ", "
and: text                      # "and" 连接最后两位
et-al-min: 4
et-al-use-first: 3
delimiter-precedes-last: never
delimiter-precedes-et-al: never

# 中文作者
# delimiter: "、"
# 不设 initialize-with，显示全名
# 不设 and
# et-al-min: 4
# et-al-use-first: 3

是否双语: 是

citation

format: author-date
collapse: year
prefix: "("
suffix: ")"
delimiter: "; "
disambiguate: add-year-suffix   # 同作者同年加 a/b 后缀
sort: author+year
# citation 内 et-al: min=3, use-first=1（行内引用更激进省略）

bibliography

hanging-indent: true
second-field-align:             # 不设置，无编号对齐
entry-spacing: 1
line-spacing: 1
sort: author+year               # 按作者姓氏 + 年份排序
numbering: false                # 无编号
suffix: "."                     # 英文条目结尾
# 中文条目 suffix: "。"

title

# 英文：所有类型均为纯文本，无斜体无引号
article-journal: plain
book: plain
chapter: plain
thesis: plain
webpage: plain

# 中文：书名号 + 引号
# article-journal: 引号 ""（quotes="true"）
# book: 书名号《》
# chapter: 书名号《》
# thesis: 书名号《》
# webpage: 引号 ""

是否双语: 是

date

# 英文：仅年份，纯文本
default-parts: year
form: text
括号: 无                        # bibliography 中无括号，作者后紧跟年份

# 中文：2024年 格式
中文年份: 有

container

# 英文期刊：纯文本，无斜体
journal: plain

# 中文期刊：书名号《》
# journal: 书名号

# 章节/会议：// 连接（GB/T 7714 特有）
book-in: "//"
conference: "//"

是否双语: 是

publisher

# 英文：Place: Publisher
format: "Place: Publisher"

# 中文：出版地：出版社（全角冒号）
是否双语: 是

access

doi: false
url: webpage-only
accessed-date: false

locators

# 英文
volume-format: 纯数字
issue-format: (X)              # 紧凑格式 15(3)
page-format: 纯数字
separator: ": "

# 中文
# volume-format: "第X卷"
# issue-format: "第X期"
# page-format: "第X页"（报纸为"第X版"）

locale-zh

et-al: "等"
and: "和"
edition: "版"
ibid: "同上"
in: "载"
no-date: "出版时间不详"
open-quote: "\u201C"
close-quote: "\u201D"
open-inner-quote: "\u2018"
close-inner-quote: "\u2019"
page-range-delimiter: "\u2014"   # em dash —
author: "著"
editor: "主编"
compiler: "整理"
thesis: "博士论文"
anonymous: "佚名"

locale-en

page-range-delimiter: "-"
punctuation-in-quote: false
translator-form-short: "trans."

name

# 英文作者
name-as-sort-order: all
sort-separator: ", "
initialize-with: " "
delimiter: ", "
and:                          # 不设置，无连接词
et-al-min: 4
et-al-use-first: 3
delimiter-precedes-et-al: never

# 中文作者
# delimiter: "、"
# 不设 initialize-with，显示全名
# 不设 and
# et-al-min: 4
# et-al-use-first: 3

是否双语: 是

citation

format: numeric
collapse: citation-number
prefix: "["
suffix: "]"
delimiter: ", "
sort: citation-number

bibliography

hanging-indent: false
second-field-align: flush
entry-spacing: 0
line-spacing: 1
sort: citation-number
numbering: true                # [1] 编号
suffix: "."                    # 英文条目结尾
# 中文条目 suffix: "。" （通过双语 layout 分别设置）

title

# 英文：所有类型均为纯文本，无斜体无引号
article-journal: plain
book: plain
chapter: plain
thesis: plain
webpage: plain

# 中文：书名号 + 引号
# article-journal: 引号 ""（quotes="true"）
# book: 书名号《》
# chapter: 书名号《》
# thesis: 书名号《》
# webpage: 引号 ""

是否双语: 是

date

# 英文：仅年份，纯文本
default-parts: year
form: text
括号: 无

# 中文：2024年 格式
中文年份: 有

container

# 英文期刊：纯文本，无斜体
journal: plain

# 中文期刊：书名号《》
# journal: 书名号

# 章节/会议：// 连接（GB/T 7714 特有）
book-in: "//"
conference: "//"

是否双语: 是

publisher

# 英文：Place: Publisher
format: "Place: Publisher"

# 中文：出版地：出版社（全角冒号）
是否双语: 是

access

doi: false
url: webpage-only
accessed-date: false

locators

# 英文
volume-format: 纯数字
issue-format: (X)              # 紧凑格式 15(3)
page-format: 纯数字
separator: ": "                # 卷期与页码之间

# 中文
# volume-format: "第X卷"
# issue-format: "第X期"
# page-format: "第X页"（报纸为"第X版"）

locale-zh

et-al: "等"
and: "和"
edition: "版"
ibid: "同上"
in: "载"
no-date: "出版时间不详"
open-quote: "\u201C"
close-quote: "\u201D"
open-inner-quote: "\u2018"
close-inner-quote: "\u2019"
page-range-delimiter: "\u2014"   # em dash —
author: "著"
editor: "主编"
compiler: "整理"
thesis: "博士论文"
anonymous: "佚名"

locale-en

page-range-delimiter: "-"
punctuation-in-quote: false
translator-form-short: "trans."

name

# 名在前，缩写首字母: I. M. Surname
name-as-sort-order:             # 不设置，名在前 Given Surname
sort-separator: ", "
initialize-with: ". "           # 缩写名，用句点+空格连接
initialize: true
delimiter: ", "
and: text                       # "and" 连接最后两位
et-al-min: 7
et-al-use-first: 1             # 7人以上只显示第1人 + et al.
delimiter-precedes-last: contextual
delimiter-precedes-et-al: contextual

是否双语: 否

citation

format: numeric
collapse: citation-number       # [1]-[3] 连续编号合并
prefix: "["
suffix: "]"
delimiter: ", "
sort: citation-number

bibliography

hanging-indent: false
second-field-align: flush       # [1] 编号后文字左对齐
entry-spacing: 0
line-spacing: 1
sort: citation-number           # 按引用顺序（编号排序）
numbering: true                 # [1] 编号
suffix: "."

title

# article: 引号，book: 斜体
article-journal: quotes         # "Article Title"
book: italic                    # *Book Title*
chapter: quotes                 # "Chapter Title"
thesis: quotes                  # "Thesis Title"
webpage: italic                 # *Webpage Title*

是否双语: 否

date

default-parts: year-month       # 期刊可显示月份缩写
form: text
括号: 无

中文年份: 无

container

# 期刊名: 斜体
journal: italic

# 章节/会议: "in" 连接
book-in: "in"
conference: "in"

是否双语: 否

publisher

# Place: Publisher
format: "Place: Publisher"

是否双语: 否

access

doi: prefix                     # 显示完整 DOI 链接 https://doi.org/...
url: webpage-only               # 无 DOI 时网页类型显示 URL
accessed-date: true             # 显示访问日期（网页类型）

locators

# 英文标签格式: Vol. X, No. Y, pp. Z
volume-format: "Vol. X"         # <label variable="volume" form="short"/>
issue-format: "No. X"           # <label variable="issue" form="short"/>
page-format: "pp. X"            # <label variable="page" form="short"/>，自动单页p./多页pp.
separator: ", "                 # 卷、期、页码之间逗号分隔

locale-en

page-range-delimiter: "\u2013"  # en dash –
punctuation-in-quote: false     # 标点在引号外
translator-form-short: "trans."

name

name-as-sort-order: first              # 仅第一作者倒排: Surname, First M.
sort-separator: ", "
initialize-with: ". "                  # 缩写中间名: M.
delimiter: ", "
and: text                              # "and" 连接最后两位
et-al-min: 3
et-al-use-first: 1
delimiter-precedes-last: never         # A and B（无 Oxford comma）
delimiter-precedes-et-al: never

是否双语: 否

citation

format: author                         # author-page（无年份）
prefix: "("
suffix: ")"
delimiter: "; "
disambiguate: add-names                # 同姓加名字区分
sort: none                             # 不排序，按出现顺序
suppress-author: false
# locator（页码）无前缀标签，直接跟在作者后

bibliography

hanging-indent: true
second-field-align:                    # 不设置
entry-spacing: 0
line-spacing: 2                        # MLA 要求双倍行距
sort: author+title                     # 按作者 + 标题排序
numbering: false
suffix: "."
subsequent-author-substitute: "---"    # 连续同作者用三短线替代

title

article-journal: quotes               # 期刊文章标题：引号
book: italic                           # 书名：斜体
chapter: quotes                        # 章节标题：引号
thesis: italic                         # 学位论文：斜体
webpage: quotes                        # 网页标题：引号
container: italic                      # 容器名（期刊/论文集）：斜体

是否双语: 否

date

default-parts: year-month-day          # MLA 完整日期（日 月缩写 年）
form: text
括号: 无
# 英文 locale 日期格式: "15 Jan. 2024"

container

journal: italic                        # 期刊名：斜体
book-in: none                          # 无 "In" 前缀，直接用容器名
conference: italic

是否双语: 否

publisher

format: 仅 Publisher                    # MLA 9 仅出版社，不含出版地

access

doi: prefix                            # https://doi.org/10.xxxx
url: always                            # 所有类型有 URL 就显示
accessed-date: false                   # MLA 通常不要求访问日期

locators

volume-format: 纯数字                   # vol. 15 → 用 label
issue-format: "No. X"                  # no. 3 → 用 label
page-format: "pp. X"                   # pp. 245-60 → 用 label
page-range-delimiter: "–"             # en dash
page-range-format: minimal-two         # 245-60 压缩格式
separator: ", "

locale-en

page-range-delimiter: "\u2013"         # en dash –
punctuation-in-quote: true             # 美式标点

CSL Style Generator — Claude Code Skill

English | 中文

<div align="center">

</div>

---

<a id="中文"></a>

中文

简介

这是一个 Claude Code Skill，用于根据用户描述的引用格式，自动生成 Zotero 可用的 CSL（Citation Style Language）样式文件。

支持从标准预设（GB/T 7714、APA、IEEE 等）一键生成，也支持根据用户提供的参考文献示例反推格式参数，生成完全自定义的 .csl 文件。

功能特性

• 7 种内置预设：GB/T 7714 顺序编码 / 著者-出版年、APA 7、Chicago Notes、IEEE、MLA 9、中文社科脚注
• 模块化组件：作者、标题、日期、容器、卷期页、出版信息、DOI/URL、正文引用、文献列表、中英文 locale，共 11 个可组合组件
• 中英文双语支持：支持按 language 字段自动切换中英文格式（中文顿号、书名号、"等" vs 英文逗号、斜体、"et al."）
• 三阶段自动校验：XML 语法检查 → CSL RelaxNG Schema 验证 → 逻辑规则审核（R1-R6）
• 实时预览：基于 citeproc-py 渲染真实的 citation 和 bibliography 输出
• 内置测试数据：包含 10 条覆盖期刊、书籍、会议、章节、网页、学位论文、报纸、报告以及中文条目的测试数据

项目结构

csl-skill/
├── SKILL.md                  # Skill 入口定义与工作流
├── presets/                   # 预设格式配方
│   ├── gbt7714-numeric.md     #   GB/T 7714 顺序编码
│   ├── gbt7714-author-date.md #   GB/T 7714 著者-出版年
│   ├── apa7.md                #   APA 第 7 版
│   ├── chicago-notes.md       #   Chicago 脚注
│   ├── ieee.md                #   IEEE
│   ├── mla9.md                #   MLA 第 9 版
│   └── chinese-note.md        #   中文社科脚注
├── components/                # 可组合的组件模板
│   ├── name.md                #   作者/姓名格式
│   ├── title.md               #   标题格式
│   ├── date.md                #   日期格式
│   ├── container.md           #   期刊/书籍容器
│   ├── locators.md            #   卷/期/页码
│   ├── publisher.md           #   出版信息
│   ├── access.md              #   DOI/URL
│   ├── citation.md            #   正文引用布局
│   ├── bibliography.md        #   参考文献列表布局
│   ├── locale-zh.md           #   中文本地化术语
│   └── locale-en.md           #   英文本地化术语
├── scripts/                   # 工具脚本
│   ├── validate_csl.py        #   CSL 校验（XML + Schema + 逻辑规则）
│   ├── preview_csl.py         #   CSL 预览（citeproc-py 渲染）
│   ├── test_data.json         #   10 条测试数据（中英文混合）
│   └── schema/v1.0.2/         #   CSL 1.0.2 RelaxNG Schema
├── validate/                  # 校验规则
│   ├── rules.md               #   R1-R7 逻辑一致性规则
│   └── schema-checklist.md    #   CSL 1.0.2 属性枚举速查表
├── output/                    # 生成的 CSL 文件
└── references/                # 参考 CSL 样式

使用方法

在 Claude Code 中使用 /csl 命令触发：

/csl GB/T 7714 顺序编码格式

/csl 帮我生成一个 APA 第 7 版的引用样式

/csl 我需要一个自定义格式，参考文献示例如下：
[1] 张伟, 李明. 基于深度学习的文本分析[J]. 计算机学报, 2024, 47(5): 1023-1035.
[2] Smith J. Introduction to Machine Learning. 3rd ed. New York: Academic Press, 2023.

工作流程

1. 收集信息 — 确认引用方式（上标编号 / 行内编号 / 脚注）+ 参考文献示例 2. 解析需求 — 匹配预设或从示例反推参数 3. 读取配方 — 从 presets 或 components 获取格式参数 4. 生成 CSL — 按骨架组装完整 XML 文件 5. 校验 — 三阶段自动校验，修复至通过 6. 预览 — 渲染真实输出，等待用户确认

依赖

校验和预览脚本需要以下 Python 依赖：

pip install lxml rnc2rng citeproc-py

手动使用脚本

# 校验 CSL 文件
python scripts/validate_csl.py output/my-style.csl

# 详细输出
python scripts/validate_csl.py --verbose output/my-style.csl

# 预览渲染效果
python scripts/preview_csl.py output/my-style.csl

# 使用自定义测试数据预览
python scripts/preview_csl.py output/my-style.csl --data my_data.json

---

<a id="english"></a>

English

Overview

A Claude Code Skill that generates Zotero-compatible CSL (Citation Style Language) style files from natural language descriptions.

Supports one-click generation from built-in presets (GB/T 7714, APA, IEEE, etc.) as well as fully custom .csl files reverse-engineered from user-provided reference examples.

Features

• 7 built-in presets: GB/T 7714 Numeric / Author-Date, APA 7, Chicago Notes, IEEE, MLA 9, Chinese Social Science Notes
• Modular components: 11 composable building blocks — author, title, date, container, locators, publisher, access, citation, bibliography, zh-locale, en-locale
• Bilingual support: Automatic Chinese/English format switching based on the language field (Chinese: dunhao, guillemets, "等"; English: commas, italics, "et al.")
• 3-stage validation: XML syntax check → CSL RelaxNG Schema validation → Logic rules audit (R1-R6)
• Live preview: Real citation and bibliography rendering via citeproc-py
• Built-in test data: 10 entries covering journal articles, books, conferences, chapters, webpages, theses, newspapers, reports, and Chinese-language items

Project Structure

csl-skill/
├── SKILL.md                  # Skill entry point & workflow definition
├── presets/                   # Format presets
│   ├── gbt7714-numeric.md     #   GB/T 7714 Numeric
│   ├── gbt7714-author-date.md #   GB/T 7714 Author-Date
│   ├── apa7.md                #   APA 7th Edition
│   ├── chicago-notes.md       #   Chicago Notes
│   ├── ieee.md                #   IEEE
│   ├── mla9.md                #   MLA 9th Edition
│   └── chinese-note.md        #   Chinese Social Science Notes
├── components/                # Composable component templates
│   ├── name.md                #   Author/name formatting
│   ├── title.md               #   Title formatting
│   ├── date.md                #   Date formatting
│   ├── container.md           #   Journal/book container
│   ├── locators.md            #   Volume/issue/page
│   ├── publisher.md           #   Publisher info
│   ├── access.md              #   DOI/URL
│   ├── citation.md            #   In-text citation layout
│   ├── bibliography.md        #   Bibliography layout
│   ├── locale-zh.md           #   Chinese locale terms
│   └── locale-en.md           #   English locale terms
├── scripts/                   # Utility scripts
│   ├── validate_csl.py        #   CSL validator (XML + Schema + logic)
│   ├── preview_csl.py         #   CSL preview (citeproc-py rendering)
│   ├── test_data.json         #   10 test entries (mixed zh/en)
│   └── schema/v1.0.2/         #   CSL 1.0.2 RelaxNG Schema files
├── validate/                  # Validation rules
│   ├── rules.md               #   R1-R7 logic consistency rules
│   └── schema-checklist.md    #   CSL 1.0.2 attribute reference
├── output/                    # Generated CSL files
└── references/                # Reference CSL styles

Usage

Invoke with the /csl command in Claude Code:

/csl GB/T 7714 numeric style

/csl Generate an APA 7th edition citation style

/csl I need a custom format. Here are sample references:
[1] Zhang W, Li M. Deep learning text analysis[J]. Journal of Computers, 2024, 47(5): 1023-1035.
[2] Smith J. Introduction to Machine Learning. 3rd ed. New York: Academic Press, 2023.

Workflow

1. Gather info — Confirm citation style (superscript / inline / footnote) + reference examples 2. Parse requirements — Match a preset or reverse-engineer parameters from examples 3. Load recipe — Retrieve format parameters from presets or components 4. Generate CSL — Assemble complete XML from the skeleton structure 5. Validate — 3-stage automatic validation, fix until pass 6. Preview — Render real output, await user confirmation

Dependencies

The validation and preview scripts require the following Python packages:

pip install lxml rnc2rng citeproc-py

Running Scripts Manually

# Validate a CSL file
python scripts/validate_csl.py output/my-style.csl

# Verbose output
python scripts/validate_csl.py --verbose output/my-style.csl

# Preview rendered output
python scripts/preview_csl.py output/my-style.csl

# Preview with custom test data
python scripts/preview_csl.py output/my-style.csl --data my_data.json

Validation Rules

The validator checks 7 rule categories: