writer-agent

Writer Agent

将文档和 URL 转换为风格化的系列文章。

快速参考

参考资料	用途	加载步骤	DP	T1	T2	T3
directory-structure.md	输出文件夹布局	步骤 1	✓	✓	✓	✓
dimension-selection.md	自定义模式维度表	步骤 2（自定义）	✓	✓	✓	✓
decision-trees.md	工作流决策指南	仅在遇到疑惑时	✓	✓	✓	✓
retry-workflow.md	错误恢复流程	仅出错时	-	✓	✓	✓
large-doc-processing.md	处理超过 50K 字的文档	步骤 3（若超过 20K）	-	-	✓	✓
article-writer-prompt.md	子 Agent 提示词模板	步骤 4	-	✓	✓	✓
context-extractor-prompt.md	上下文提取模板	步骤 3（Tier 2）	-	-	✓	-
context-optimization.md	上下文优化反模式	步骤 3.1	-	✓	✓	✓
detail-levels.md	输出详细程度选项	步骤 2.5	✓	✓	✓	✓
shared-article-writing.md	共享步骤 4.0-4.6	步骤 4	-	✓	✓	✓

DP = 直接路径 | T1-T3 = Tier 1-3 | ✓ = 加载 | - = 跳过

Tier 工作流文件（在确定 Tier 后于步骤 2.7 加载）：

Tier	文件	适用条件
直接路径	tier-direct-path.md	少于 20K 或（少于 50K 且文章数 ≤3）
Tier 1	tier-1-workflow.md	20K-50K（不符合直接路径条件）
Tier 2	tier-2-workflow.md	50K-100K
Tier 3	tier-3-workflow.md	>=100K

维度文件（在步骤 2 加载）：voices/{voice}.md、structures/{structure}.md、identities/{identity}.md、audiences/{audience}.md、emotional_maps/{emotion}.md

工作流概览

直接路径（少于 20K 字，或少于 50K 字且文章数 <=3）：

主 Agent 直接撰写所有文章，不使用子 Agent。

Input → Convert → Style/Structure → Plan → Write(main) → Synthesize → Verify
  1        1           2               3        4            5           6

标准路径（Tier 1-2，20K-100K 字）：

Input → Convert → Style/Structure → Analyze → Extract → Write → Synthesize → Verify
  1        1           2               3         3         4        5           6

快速路径（Tier 3，>=100K 字）：

Input → Convert → Style/Structure → Plan → Write(parallel) → Synthesize → Verify
  1        1           2              3          4              5           6

步骤 0：解析 Skill 路径（必需）

查找 wa-env → 运行 → 在整个工作流中使用绝对路径。

# Tìm wa-env (thử Glob trước, fallback find nếu plugin installed vào dotdir)
Glob("**/writer-agent/scripts/wa-env")  # hoặc Glob(".claude/**/wa-env")

# Chạy (dùng bash, không dùng source — để BASH_SOURCE resolve đúng)
bash {path_to_wa-env}
# → SCRIPTS_DIR, SKILL_DIR, VOICES_DIR, STRUCTURES_DIR, IDENTITIES_DIR,
#   AUDIENCES_DIR, EMOTIONS_DIR, TEMPLATES_DIR, REFERENCES_DIR

# Verify
assert Glob(f"{SCRIPTS_DIR}/wa-convert") and Glob(f"{VOICES_DIR}/*.md")

失败条件：未找到 wa-env → 停止。不要自行猜测路径。

第 1 步：输入处理

GUARD：SCRIPTS_DIR 已在 Step 0 中解析。如果尚未解析 → STOP，返回 Step 0。

检测输入类型并转换为 Markdown。

输出语言：始终使用越南语，无论源语言是什么。

输入类型	检测方式	操作
文件（PDF/DOCX/EPUB 等）	路径 + 扩展名	wa-convert {path}
URL（网页）	http:// 或 https://	wa-convert {url}
YouTube URL	youtube.com 或 youtu.be	wa-convert {url}
纯文本 / .txt / .md	无复杂扩展名	重写 → wa-paste-text

文件/URL 转换

{SCRIPTS_DIR}/wa-convert [/path/to/file.pdf or url]

输出：writer-agent/{slug}-{timestamp}/input-handling/content.md

纯文本处理

1. 读取内容（如果是文件）
2. 重写为结构化 Markdown（添加标题，保留内容）
3. 提议标题
4. 执行：

echo "{rewritten_content}" | {SCRIPTS_DIR}/wa-paste-text - --title "{title}"

错误处理

错误	操作
找不到文件	请用户提供正确的路径
不支持的格式	尝试使用 Docling，并向用户确认
URL 获取失败	报告并停止
内容为空	警告，并在继续前确认
PDF 已加密	请用户提供解密后的版本

第 2 步：选择写作维度

系统包含 5 个独立维度。用户可选择预设组合，或选择 Custom 自由组合。

预设组合（推荐）

向用户展示下表，并询问选择哪个预设或“Custom”：

预设	语气	结构	身份	受众	情感
教育者	教师	积木式结构	技术构建者	好奇的初学者	赋能与挑战
讲故事者	讲述者	故事弧线	沉思的思想者	深度探索者	反思与发现
分析师	客观	BLUF-证据	知识策展人	忙碌的专业人士	赋能与挑战
探索者	调查者	五层结构	知识策展人	深度探索者	激发与转变
导师	引导者	深度-实践	沉思的思想者	好奇的初学者	反思与发现
反思者	个人	螺旋式回归	沉思的思想者	深度探索者	反思与发现
禅师	对话	师徒式结构	沉思的思想者	深度探索者	反思与发现

用法：显示上表 → 询问用户输入预设名称（例如“Educator”）或“Custom”。

• 如果选择预设：5 个维度均已设置，跳至 Step 2.5
• 如果选择 Custom：转到下方的 Step 2a-2f，逐一选择维度
• 自适应结构：当内容类型混合或不适合固定结构时使用。仅可通过 Custom 模式选择，或由用户直接提出要求。

自定义模式

当用户选择“Custom”时 → 阅读 dimension-selection.md，逐一选择维度（语气 → 结构 → 身份 → 受众 → 情感），并进行兼容性检查。

第 2.5 步：选择详细程度

询问用户确认输出的详细程度。

级别	比例	描述
简洁	15-25%	概述，保留主要观点
标准	30-40%	平衡（推荐）
全面	50-65%	详细，保留更多示例
忠实	75-90%	几乎完整，按指定风格重写

默认值：标准（如果用户跳过或意图不明确）。PASS/FAIL 根据章节覆盖情况判定，而非字数。

详细的计算方法（target_ratio、example_percentage）和演示示例 → detail-levels.md。

第 2.6 步：层级参考表

规范层级定义（在整个文档中引用）：

层级	字数	策略	上下文处理方式	术语表	max_concurrent
Direct Path	<20K 或（<50K 且 ≤3 篇文章）	主 Agent 编写全部内容	不适用（无子 Agent）	内嵌（约 200 个词）	不适用
Tier 1	20K-50K（不符合 Direct Path）	子 Agent 直接读取源文档	无上下文文件	内嵌（约 200 个词）	3
Tier 2	50K-100K	智能压缩	上下文提取器	单独文件（约 600 个词）	3
Tier 3	>=100K	Fast Path，尽量减少开销	无上下文文件	内嵌（约 300 个词）	2

优先级规则：

• 首先检查 Direct Path 条件；这些条件优先于层级边界
• 字数为 20K-50K 且文章数 ≤3 的文档使用 Direct Path（而非 Tier 1）
• 只有不符合 Direct Path 条件的文档才会进入层级选择流程

注意：Direct Path 的 <50K 条件还受语言限制：EN 约 44K、VI 约 32K、混合语言约 38K 字。这些限制已预先计算在 structure.json → direct_path.capacity_ok 中。如果超出容量，则回退到 Tier 1。

主要区别：

• Direct Path：主 Agent 负责处理所有内容（无子 Agent）
• Tier 1：轻量级子 Agent，通过行范围读取源文档
• Tier 2：通过上下文提取进行压缩（唯一使用单独术语表文件的层级）
• Tier 3：与 Tier 1 类似，但分块更大、术语表选择更严格、并发数更低

第 2.7 步：加载层级工作流（必需）

确定 Step 2.6 中的层级后，读取相应的工作流文件：

tier = determine_tier(structure_json)  # Từ structure.json

if tier == "direct_path":
    Read(f"{SKILL_DIR}/references/tier-direct-path.md")
elif tier == 1:
    Read(f"{SKILL_DIR}/references/tier-1-workflow.md")
elif tier == 2:
    Read(f"{SKILL_DIR}/references/tier-2-workflow.md")
elif tier == 3:
    Read(f"{SKILL_DIR}/references/tier-3-workflow.md")

层级工作流文件包含 Steps 3-4。 完成 Step 4 后，加载 references/steps-5-6-synthesize-verify.md，以执行 Steps 5-6。

失败条件：如果未加载层级工作流文件 → 将不知道如何处理该层级的 Steps 3-4。停止并加载正确的文件。