document-workflows

文件工作流程 (Document Workflows) 工作流程

本技能旨在提供一個標準化的方法來建立、編輯和導出各種格式的文件，包括 Markdown、Word 文件和其他文件格式。

何時使用此技能

• 使用者要求生成一份報告或文件（「請為我寫一份項目報告」）
• 使用者要求將內容導出為特定格式（「請將這個轉換為 Word 文件」）
• 使用者要求編輯或更新現有文件
• 使用者要求生成多個相關的文件
• 使用者要求應用特定的文件範本
• 使用者要求進行文件格式轉換

工具需求

• artifacts.write_file: 將文件內容寫入檔案系統
• Markdown 支援（用於內容編寫）
• 文件格式轉換工具（如 pandoc、python-docx）

文件工作流程

步驟 1: 明確文件需求

與使用者溝通，確定文件的具體需求和規格。

需求澄清清單:

• [ ] 文件的主要目的是什麼？
• [ ] 目標受眾是誰？
• [ ] 文件應該包含哪些主要部分？
• [ ] 期望的格式是什麼（Markdown、Word、PDF 等）？
• [ ] 是否有特定的風格或範本要求？
• [ ] 文件的長度和詳細程度？
• [ ] 是否需要包含圖表、表格或其他視覺元素？
• [ ] 是否有特定的交付期限？

步驟 2: 規劃文件結構

設計文件的邏輯結構和組織方式。

結構規劃清單:

• [ ] 定義主要章節和子章節
• [ ] 確定每個章節的內容和目的
• [ ] 規劃章節之間的流程和連接
• [ ] 識別需要的視覺元素（圖表、圖像、表格）
• [ ] 確定目錄、索引等輔助元素
• [ ] 規劃頁眉、頁腳和其他格式元素

文件結構範例:

# 項目報告

## 目錄
[自動生成]

## 1. 執行摘要
- 項目概述
- 主要成果
- 關鍵建議

## 2. 項目背景
- 項目目標
- 範圍和限制
- 利益相關者

## 3. 方法論
- 研究方法
- 資料收集
- 分析方法

## 4. 發現和結果
- 主要發現 1
- 主要發現 2
- 數據和統計

## 5. 建議和結論
- 建議 1
- 建議 2
- 後續步驟

## 附錄
- 詳細資料
- 參考文獻

步驟 3: 收集和組織內容

收集文件所需的所有內容，包括文字、資料、圖表等。

內容收集清單:

• [ ] 收集所有相關的文字內容
• [ ] 準備統計資料和數據
• [ ] 準備圖表和圖像
• [ ] 收集引用和參考資料
• [ ] 準備任何需要的代碼或技術細節
• [ ] 組織和分類內容

內容組織方法:

• 按章節組織
• 按優先級組織
• 按資料類型組織
• 按時間順序組織

步驟 4: 撰寫文件內容

使用 Markdown 格式撰寫文件內容。Markdown 是一個簡單但強大的格式，易於編寫和轉換。

Markdown 基本語法:

# 一級標題
## 二級標題
### 三級標題

**粗體文字**
*斜體文字*
~~刪除線~~

- 無序列表項 1
- 無序列表項 2

1. 有序列表項 1
2. 有序列表項 2

[連結文字](https://example.com)

![圖片描述](image.png)

| 表頭 1 | 表頭 2 |
|--------|--------|
| 資料 1 | 資料 2 |

> 引用文字

\`\`\`python
# 程式碼區塊
print("Hello, World!")
\`\`\`

撰寫最佳實踐:

• [ ] 使用清晰、簡潔的語言
• [ ] 保持段落簡短（3-4 句）
• [ ] 使用標題和子標題組織內容
• [ ] 使用列表和表格呈現資訊
• [ ] 包含具體的例子和數據
• [ ] 避免過度使用技術術語
• [ ] 定期檢查拼寫和語法

步驟 5: 添加視覺元素

根據需要添加圖表、表格和圖像，增強文件的可讀性。

視覺元素清單:

• [ ] 在適當的位置插入圖表
• [ ] 添加資料表格
• [ ] 插入相關圖像
• [ ] 添加圖表標題和說明
• [ ] 確保視覺元素的品質和清晰度
• [ ] 驗證所有視覺元素的正確性

表格範例:

| 指標 | 2023 年 | 2024 年 | 變化 |
|------|--------|--------|------|
| 收入 | $100M | $120M | +20% |
| 成本 | $60M | $65M | +8% |
| 利潤 | $40M | $55M | +37% |

步驟 6: 審查和編輯

仔細審查文件內容，確保品質和準確性。

審查清單:

• [ ] 檢查內容的準確性
• [ ] 驗證所有事實和數據
• [ ] 檢查拼寫和語法
• [ ] 驗證格式的一致性
• [ ] 檢查所有連結和引用
• [ ] 驗證圖表和圖像的品質
• [ ] 檢查邏輯流程和連接
• [ ] 獲取利益相關者的反饋

編輯技巧:

• 大聲朗讀以檢查流暢性
• 使用拼寫檢查工具
• 讓他人審查內容
• 多次審查不同方面（內容、格式、風格）
• 使用追蹤變更功能記錄修改

步驟 7: 格式化和樣式設定

應用適當的格式和樣式，確保文件外觀專業。

格式化清單:

• [ ] 應用一致的字體和字號
• [ ] 設定適當的行距和段落間距
• [ ] 應用標題和子標題樣式
• [ ] 設定頁邊距和頁面大小
• [ ] 添加頁碼和頁眉/頁腳
• [ ] 應用顏色和強調（適度）
• [ ] 驗證整個文件的視覺一致性

Word 文件格式化範例:

from docx import Document
from docx.shared import Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document()

# 添加標題
title = doc.add_heading('項目報告', 0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER

# 添加段落
p = doc.add_paragraph('這是報告的內容。')
p.paragraph_format.line_spacing = 1.5

# 添加表格
table = doc.add_table(rows=2, cols=2)
table.style = 'Light Grid Accent 1'

# 保存文件
doc.save('report.docx')

步驟 8: 導出和交付

將文件導出為所需的格式，並準備交付。

導出選項:

• [ ] Markdown 格式（用於版本控制和協作）
• [ ] HTML 格式（用於網頁發佈）
• [ ] Word 文件（.docx，用於編輯和共享）
• [ ] PDF 格式（用於打印和存檔）
• [ ] 其他格式（如需要）

導出工具:

• Pandoc: 通用文件轉換工具
• python-docx: Python 中的 Word 文件處理
• WeasyPrint: HTML 到 PDF 轉換

導出範例:

# 使用 Pandoc 轉換
pandoc report.md -o report.docx
pandoc report.md -o report.pdf
pandoc report.md -o report.html

# 使用 Python 轉換
python3 -c "
from weasyprint import HTML
HTML('report.html').write_pdf('report.pdf')
"

交付清單:

• [ ] 驗證導出的檔案品質
• [ ] 測試所有連結和引用
• [ ] 檢查在目標應用程式中的顯示
• [ ] 準備交付說明（如需要）
• [ ] 備份原始檔案
• [ ] 記錄版本和修改歷史

最佳實踐

1. 使用版本控制: 將文件保存在版本控制系統中，追蹤變更。

2. 模板和樣式: 使用預定義的範本和樣式，確保一致性。

3. 協作工作流程: 使用追蹤變更和評論功能進行協作審查。

4. 可訪問性: 確保文件對所有使用者都可訪問（例如，包括圖像替代文字）。

5. 清晰的結構: 使用邏輯的層級結構和清晰的標題。

6. 視覺層次: 使用格式和樣式創建清晰的視覺層次。

7. 一致的風格: 在整個文件中保持一致的寫作風格和格式。

常見的文件問題

• 不一致的格式: 不同部分使用不同的樣式和格式
• 過度複雜: 文件結構過於複雜，難以導航
• 內容過時: 文件包含過時的資訊
• 視覺混亂: 過多的顏色、字體和樣式
• 不清晰的寫作: 句子過長或術語不清楚
• 缺乏組織: 內容沒有邏輯順序
• 品質問題: 拼寫錯誤、語法問題或不準確的資訊