---
name: write-project-docs
description: 按 NixKits 风格为任意项目编写或重新生成完整的多语言文档 — 简洁、表驱动、含语言切换器标题和模块分类 README。覆盖 README、各模块文档及技能文档。
---

# 项目文档编写（NixKits 风格）

为任意项目生成完整的多语言文档体系。

## 何时使用

- 用户要求"编写文档"或"生成文档"
- 用户希望采用 NixKits 风格（简洁、多语言、表驱动）
- 用户有含模块/包/服务的现有项目需要文档化

## 自动发现契约

1. **扫描** — `skills/translate-*/` 下查找所有翻译技能
2. **读取** — 解析 frontmatter 中的 `language_code`、`display_name`、`base_language`
3. **注册** — 将发现的语言扩展纳入目录结构、语言切换器、列名映射等生成逻辑

## 编写规则

- **零废话** — 没有引导性修辞，没有"欢迎来到"
- **表格优先于段落** — 用 `基本信息` 表格展示元数据
- **代码块完整可运行** — 可直接复制粘贴
- **技术术语保持英文** — 即使在中文/日文文档中
- **语言切换器标签** — 统一用各语言 `display_name`（语言自称），自身不加链接
- **中文标题 2 或 4 字词** — 优先简洁对称词汇（如 `组件`、`基本信息`）
- **不生成目录** — 文档足够短，直接扫读
- **目标行数 ~40-60 行** — 补丁/模块文档以 `rcc-fix.md`（39 行）为标杆
- **标准节结构** — `基本信息` → `修正内容`/`功能` → `安装` → `注意`
- **禁止反模式**：

| 反模式 | 正确做法 |
|--------|----------|
| 硬编码语言列表 | 自动发现 `translate-*/` |
| 硬编码文档路径（如 `docs/zh/`） | 根据语言代码动态生成 |
| 链接修复只改路径不改显示文本 | 路径和显示文本同步修正 |
| README 只更新主语言 | 同步所有已发现的本地化版本 |
| 源文件修改后不跟新文档 | 每次源变更后立即校对相关文档 |
| 在已有节之前插入内容时未检查是否已存在 | 逐行 `grep` 确认目标文本不重复后再写入 |

## 工作流程

### 第 1 步：评估项目

读取所有可用的模块/包/服务元数据，对每个模块提取名称、描述、类型、依赖、安装命令、使用示例。

### 第 2 步：模块分类

按功能类别分组。对于 Nix flake 项目：

| 分类 | 发现方式 |
|------|---------|
| 软件 | `packages/*.nix` 中的 `callPackage` |
| 模块 | `modules/*.nix` 中的 NixOS 模块定义 |
| 覆盖层 | `overlays/*.nix` 中的 overlay 函数 |
| 技能 | `skills/*/SKILL.md` 中的 frontmatter |
| 开发 | `devShells` 在 `flake.nix` 中 |

### 第 3 步：生成 README

主语言 README 放根目录（无后缀），本地化版本放 `docs/README.<code>.md`。

### 第 4 步：生成模块文档

`docs/<lang>/<module>.md`，遵循四段式结构，每组自动包含对应分类标题。

### 第 5 步：生成技能文档

`docs/<lang>/skills/<skill>.md`，每技能包含基本信息 + 功能 + 使用。

### 第 6 步：语言切换器

按 `zh → en → ja → 扩展语言（自动发现顺序）` 生成。从源文件提取路径，用脚本逐个精确构造（**禁止 sed 模式匹配**）。

### 第 7 步：最终检查

- 无死链接
- 各模板满员（无缺失语言版本）
- 中文 2/4 字标题一致
- 引用块格式统一