article-writer

文章撰写器

创建技术文章，并提供配套项目和多语言支持。

快速开始

1. 确定作者（从任务中获取，或使用数据库中的默认作者）
2. 创建文件夹结构（包括 code/ 文件夹）
3. 从数据库加载作者资料
4. 加载设置（包括 article_limits.max_words）
5. 按照以下阶段执行：初始化 → 规划 → 调研 → 起草 → 配套项目 → 集成 → 审阅 → 精简 → 翻译 → 定稿

工作流概览

Plan → Research → Draft (initial) → Create Companion Project → Update Draft → Review → Condense → Translate → Finalize
                         ↑                              ↓               ↓
                         └──────── Iterate ─────────────┘               │
                                                                        ↓
                                                            (if over max_words)

文件夹结构

content/articles/YYYY_MM_DD_slug/
├── 00_context/              # author_profile.json
├── 01_planning/             # classification.md, outline.md
├── 02_research/
│   ├── sources.json         # All researched sources
│   └── research_notes.md
├── 03_drafts/
│   ├── draft_v1.{lang}.md   # Initial draft
│   └── draft_v2.{lang}.md   # After companion project integration
├── 04_review/               # checklists
├── 05_assets/images/
├── code/                    # COMPANION PROJECT
│   ├── README.md            # How to run the companion project
│   ├── src/                 # Companion project source code/files
│   └── tests/               # Tests (if applicable)
├── {slug}.{primary_lang}.md # Primary article
└── {slug}.{other_lang}.md   # Translations

阶段

阶段 0：初始化

• 获取作者，生成 slug，创建文件夹
• 创建 code/ 目录，用于存放配套项目
• 将作者资料复制到 00_context/
• 从设置中加载 article_limits.max_words

阶段 1：规划

• 对文章类型进行分类
• 创建大纲
• 规划配套项目的类型和范围
• 检查点： 获取批准

阶段 2：调研（网页搜索）

• 搜索官方文档
• 查找近期新闻（技术类文章需在 1 年以内）
• 记录所有来源

阶段 3：起草（初稿）

• 使用主要语言撰写初稿
• 标记示例代码的位置：``
• 保存为 03_drafts/draft_v1.{lang}.md

应用作者风格

写作时使用作者资料中的所有数据：

1. 手动填写的资料数据

   • tone.formality：1 = 非常随意，10 = 非常正式
   • tone.opinionated：1 = 始终有所保留，10 = 观点鲜明
   • phrases.signature：自然使用（不要过度使用）
   • phrases.avoid：绝不使用这些表达
   • vocabulary.use_freely：假设读者熟悉这些词汇
   • vocabulary.always_explain：首次使用时进行解释

2. 风格分析数据（如果 voice_analysis 中存在）

   • sentence_structure.avg_length：以此为目标句长
   • sentence_structure.variety：匹配风格（短句／适中／长句）
   • communication_style：在语气中体现主要特征
   • characteristic_expressions：自然穿插这些表达
   • sentence_starters：使用这些句式开头
   • signature_vocabulary：优先使用这些词语

示例：

对于具有以下特点的作者：

{
  "tone": { "formality": 4, "opinionated": 7 },
  "voice_analysis": {
    "sentence_structure": { "avg_length": 14, "variety": "moderate" },
    "communication_style": [{ "trait": "enthusiasm", "percentage": 32 }],
    "characteristic_expressions": ["na prática", "o ponto é"],
    "sentence_starters": ["Então", "O interessante é"]
  }
}

写作时应采用：

• 轻松对话式但自信的语气
• 中等长度的句子（约 14 个词）
• 充满热情
• 偶尔使用 “na prática” 和 “o ponto é”
• 部分句子以 “Então” 或 “O interessante é” 开头

阶段 4：创建配套项目 ⭐

此阶段使用 Skill(companion-project-creator)

重要：配套项目必须完整、可运行且经过验证。

Laravel 配套项目是完整的 Laravel 安装。Node 配套项目是完整的 Node 项目。

只有实际运行并测试过，配套项目才算完成。

步骤 1：从设置中加载配套项目默认值

先从数据库加载设置：

# View defaults for the companion project type
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings code

或者读取 JSON 并提取：

// Settings are loaded from the database via show.ts or article-stats.ts
const codeDefaults = settings.companion_project_defaults.code;
// codeDefaults.scaffold_command
// codeDefaults.verification.install_command
// codeDefaults.verification.run_command
// codeDefaults.verification.test_command

步骤 2：与文章覆盖值合并

如果文章任务包含 companion_project 字段，则其中的值会覆盖设置默认值。

步骤 3：执行脚手架命令

# From settings.companion_project_defaults.code.scaffold_command
composer create-project laravel/laravel code --prefer-dist

步骤 4：添加文章专属代码

在脚手架生成的项目上添加自定义代码：

• 模型、控制器、路由
• 迁移、数据填充器
• 测试

绝不要只创建几个文件就交付不完整的项目。

步骤 5：验证（必做）⚠️

必须实际运行以下命令并确认执行成功：

cd code

# 1. Install dependencies - MUST SUCCEED
composer install
# ✓ Check: No errors, vendor/ directory exists

# 2. Setup - MUST SUCCEED
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate
# ✓ Check: No errors

# 3. Run application - MUST START
php artisan serve &
# ✓ Check: "Server running on http://127.0.0.1:8000"
# Stop the server after confirming

# 4. Run tests - ALL MUST PASS
php artisan test
# ✓ Check: "Tests: X passed" with 0 failures

如果任何步骤失败：

1. 阅读错误消息
2. 修复代码
3. 从步骤 1 开始重新运行验证
4. 重复以上步骤，直到全部通过

验证通过前，不要继续执行阶段 5。

配套项目类型

文章主题	项目类型	创建内容
Laravel/PHP 代码	code	通过 composer create-project 创建完整的 Laravel 项目
JavaScript/Node	node	通过 npm init 创建完整的 Node 项目
Python	python	创建完整的 Python 项目并配置 venv
DevOps/Docker	config	完整的 docker-compose 配置
架构	diagram	完整的 Mermaid 图表
项目管理	document	完整的模板和填写好的示例

验证清单

继续进入第 5 阶段之前：

• 脚手架命令已成功执行
• 已添加所有文章专属代码
• install_command 已成功执行（存在 vendor/node_modules）
• run_command 已启动应用程序且没有错误
• test_command 已运行，失败数为 0
• README.md 说明了设置和使用方法

对于代码配套项目（Laravel）

code/
├── README.md              # Setup and run instructions
├── app/
│   └── ...                # Minimal app code
├── database/
│   ├── migrations/
│   └── seeders/
├── tests/
│   └── Feature/           # Pest tests for main features
├── composer.json
└── .env.example           # SQLite by default

Laravel 配套项目标准：

• 使用 SQLite（无需外部数据库）
• 使用 Pest 进行测试
• 为主要功能至少编写 2-3 个测试
• 添加引用文章的注释：// See article section: "Rate Limiting Basics"
• 尽量减少依赖
• 如果设置过程复杂，请包含设置脚本

对于文档配套项目

code/
├── README.md              # What the documents demonstrate
├── templates/
│   └── ...                # Reusable templates
└── examples/
    └── ...                # Filled-in examples

第 5 阶段：将配套项目集成到草稿中

• 将 `` 标记替换为实际代码片段
• 添加文件引用：“参见 code/app/Models/Post.php”
• 在相应章节中添加运行说明
• 保存为 03_drafts/draft_v2.{lang}.md

第 6 阶段：审阅（全面检查）

整体审阅文章：

1. 讲解流程

   • 叙述是否合乎逻辑、流畅？
   • 是否先介绍概念，再使用这些概念？
   • 配套项目是否在恰当的时机出现？

2. 配套项目集成

   • 代码片段是否与完整的配套项目相符？
   • 文件路径是否正确？
   • 读者能否跟着操作？

3. 风格一致性

   • 是否符合作者的正式程度？
   • 是否恰当地使用了标志性短语？
   • 是否避免了禁用短语？
   • 表达的观点是否符合作者的立场？
   • 如果存在 voice_analysis：
     • 句子长度是否符合 avg_length？
     • 是否体现了沟通风格特征？
     • 是否使用了特征表达（但不过度使用）？

4. 技术准确性

   • 代码片段是否正确？
   • 配套项目是否确实可以运行？
   • 测试是否通过？

5. 完整性

   • 是否涵盖了大纲中的所有要点？
   • 是否正确引用了来源？
   • 配套项目是否完整地展示了主题？

检查点： 确认文章和配套项目已准备就绪

第 6b 阶段：精简（执行字数限制）⚠️

如果文章超过设置中的 max_words，则此阶段为必需阶段。

第 1 步：检查字数

# Count words in article (excluding frontmatter and code blocks)
# Frontmatter: lines between first --- and second ---
# Code blocks: lines between ``` markers

# Simple word count of prose content only:
sed '/^---$/,/^---$/d; /^```/,/^```$/d' draft_v2.{lang}.md | wc -w

第 2 步：从设置中读取字数限制

# Read max_words from settings
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings
# Or read JSON directly:
# bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings

第 3 步：超出限制时进行精简

如果字数 > max_words：

1. 确定精简目标（按优先级排序）：

   • 对同一概念的重复解释
   • 过于冗长的过渡内容
   • 重复的注意事项或免责声明
   • 与主题无关的冗长旁支内容
   • 数量过多的示例（适当减少即可说明问题时）

2. 精简技巧（保持质量）：

   • 合并相关段落
   • 用简洁的总结替代冗长的解释
   • 将冗长的列表改为精简的项目符号列表
   • 删除填充词和短语
   • 精简句子结构

3. 关键：保留作者风格

   • 保留标志性短语和表达
   • 保持相同的语气（正式程度）
   • 保留作者表达观点的风格
   • 保留特征句式
   • 保持与风格档案一致的热情和活力

4. 不要删除：

   • 代码示例或片段（这些不计入字数限制）
   • 关键技术说明
   • 先决条件或设置说明
   • 安全警告或重要说明
   • 对配套项目的引用

第 4 步：验证精简后的版本

精简后：

• 字数现在 ≤ max_words
• 文章读起来仍然流畅自然（没有生硬感）
• 所有关键要点均已保留
• 技术准确性得到保持
• 全文作者风格一致
• 流程和叙述结构保持完整

第 5 步：保存精简后的草稿

# Save as draft_v3 (condensed version)
# 03_drafts/draft_v3.{lang}.md

如果无法在不损失质量的情况下将字数精简到 max_words 以内：

• 在任务中记录原因
• 注明最终字数
• 标记以供人工审阅

检查点： 文章在保持质量的同时符合字数限制

阶段 7：翻译

• 创建其他语言版本
• 保持代码片段不变
• 如有需要，翻译代码中的注释

阶段 8：定稿

• 编写带有 frontmatter 的最终文章
• 使用以下内容更新数据库：
  • output_files
  • sources_used
  • companion_project 信息
• 确认 companion project README 内容完整

何时跳过 Companion Projects

仅当 companion project 完全没有意义时才跳过：

• 没有可执行内容的纯观点文章
• 新闻／公告摘要
• 历史回顾
• 哲学讨论

如果跳过，请在任务中记录：

{
  "companion_project": {
    "skipped": true,
    "skip_reason": "Opinion piece with no actionable code or templates"
  }
}

Companion Project README 模板

# Companion Project: [Topic]

Demonstrates [what this companion project shows] from the article "[Article Title]".

## Requirements

- PHP 8.2+
- Composer
- (any other requirements)

## Setup

\`\`\`bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
\`\`\`

## Run Tests

\`\`\`bash
php artisan test
\`\`\`

## Key Files

| File | Description |
|------|-------------|
| `app/Models/Post.php` | Demonstrates eager loading |
| `tests/Feature/QueryTest.php` | Tests N+1 detection |

## Article Reference

This companion project accompanies the article:
- **Title**: [Article Title]
- **Section**: See "Implementing Eager Loading" section

Companion Project 注释风格

<?php
// ===========================================
// ARTICLE: Rate Limiting in Laravel 11
// SECTION: Creating Custom Rate Limiters
// ===========================================

namespace App\Providers;

use Illuminate\Support\Facades\RateLimiter;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Custom rate limiter for API endpoints
        // See article section: "Dynamic Rate Limits"
        RateLimiter::for('api', function (Request $request) {
            return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
        });
    }
}

在任务中记录 Companion Project

{
  "companion_project": {
    "type": "code",
    "path": "code/",
    "description": "Minimal Laravel app demonstrating rate limiting",
    "technologies": ["Laravel 11", "SQLite", "Pest 3"],
    "has_tests": true,
    "files": [
      "app/Providers/AppServiceProvider.php",
      "routes/api.php",
      "tests/Feature/RateLimitTest.php"
    ],
    "run_instructions": "composer install && php artisan test"
  }
}

参考资料

• references/article-types.md
• references/companion-project-templates.md
• references/checklists.md
• references/frontmatter.md
• references/research-templates.md