Writing Style

---
name: writing-style
description: |
  从用户原创内容中提取个人写作风格，生成结构化《风格说明书》并持续迭代。
  当用户说"学习我的写作风格"、"分析我的表达习惯"、"生成风格说明书"、
  "更新我的风格"、"提炼我的风格"、"我的写作特点是什么"，
  或提供原创内容要求提炼风格特征时触发。

  【不适用场景】
  - 用户要求"用我的风格写XX" → 下游内容生成技能
  - 用户只是收藏/管理素材 → 素材管家
user-invocable: true
---

# 风格学习向导

## Trigger

以下任一条件命中即触发：
- 用户明确要求学习/分析/提炼/总结自己的写作风格
- 用户要求生成或更新《风格说明书》
- 用户提供原创内容（文本/文件/链接）并要求从中学习风格
- 用户对 AI 生成的初稿做了修改，累积达到校准阈值

**不触发**：用户要求"用我的风格写XX"（下游技能）、用户只是收藏/管理素材（素材管家）。

## 核心理念

风格 ≠ 模仿名人，而是从用户**自己写过的内容**中提炼"你是怎么说话的"。三层递进：提取 → 显性化为说明书 → 持续校准。

---

## 场景路由

进入技能后，按以下优先级判断当前场景并执行对应流程。

### 场景判断逻辑

**执行方式**：调用 `scripts/material_scanner.py` 自动完成路径扫描和场景判定，LLM 只需读取输出 JSON 的 `scene` 字段。

```bash
.venv/bin/python scripts/material_scanner.py [--base <知识管家根路径>] [--has-spec] [--user-provided]
```

> **路径识别规则**：本技能专为「知识管家」（knowledge-butler）设计。scanner 会自动向上递归查找**同时包含 `1-素材/` 和 `3-AI档案/` 子目录**的目录作为知识管家根路径。识别成功后：
> - `1-素材/文稿/` → 作为**用户原创素材**（正向学习输入）
> - `1-素材/收藏/` → 作为**外部参考素材**（反向学习输入，用于禁用清单）
> - 若未找到知识管家根路径 → 走场景三引导流程，提示用户先在悟空上用「知识管家」skill 初始化一个 wiki

输出 `scene` 字段直接对应：`场景一：首次学习`（≥3篇）、`场景二：内容不够`（1-2篇）、`场景三：引导提供素材`（0篇）、`场景三：用户主动提供素材`、`场场景四：持续校准`。

### 场景一：首次学习风格（≥3 篇原创）

**前置条件**：`material_scanner.py` 输出 `scene = "场景一：首次学习"`，`original_files` 列出 ≥3 个文件。

**Step 0：干扰项检查**
在开始分析前，检查 `material_scanner.py` 输出的 `unrecognized_files` 字段。如果存在压缩包类文件（`.zip`, `.rar`, `.7z` 等），且标记为 `source: "upstream"`，需引导用户解压。

**Step 1：选取样本与内容提取**
从 `original_files` 列表中选取 3-10 篇作为分析样本（优先覆盖不同话题）。对非纯文本文件（.docx / .pdf / 图片），先按 `references/content-sources.md` 的方式提取纯文本，保存为临时 `.txt` 文件。

**Step 2：单篇分析（定量 + 定性）**
*   **定量统计**：运行 `quantitative_analysis.py`，获取句长、TTR、段落分布等五大维度数据。
*   **定性分析**：LLM 针对每篇内容从语气调性、视角人称、修辞手法、标志性表达、开头结尾习惯 5 个维度进行分析，产出“风格卡片”。

**Step 3：跨篇提炼**
运行 `cross_sample_aggregator.py` 汇总所有风格卡片。识别出稳定出现的特征（如高频口头禅、固定句式），并对矛盾特征进行场景化标注。

**Step 4：反面提取（禁用清单）**
对比“参考素材”与“原创内容”，提取参考素材中出现但用户原创中从未使用的词汇或句式，形成“禁用清单”。若无参考素材，则基于领域通用写法进行反向推断。

**Step 5：生成说明书草稿**
*   **元信息**：运行 `spec_metadata.py init` 生成版本号、置信度等头部信息。
*   **模块填充**：按照 `references/style-spec-template.md` 的格式，填充整体调性、语气与视角、句式与节奏、标志性表达、禁用清单、验证样本 6 大模块。
*   **质量检查**：运行 `spec_validator.py` 确保无空模块。

**Step 6：展示风格对比**
选取用户标志性表达最密集的话题，分别撰写“通用版”和“用户风格版”两段文字进行对比，直观展示风格差异。

**Step 7：用户确认与保存**
展示完整说明书，收集用户反馈并微调，最后保存到悟空记忆。

### 场景二：原创内容不够（1-2 篇）

**前置条件**：`material_scanner.py` 输出 `scene = "场景二：内容不够"`。

**概要流程**：
1.  **简化提取**：执行单篇分析，但因样本不足，跨篇提炼结果需标注 `[待验证]`。
2.  **生成低置信度画像**：生成初步风格说明书，明确告知用户哪些特征是确定的、哪些是推测的。
3.  **引导补充**：不进行复杂的风格对比，重点引导用户通过上传历史文章或现场创作来补充素材。
4.  **自动更新机制**：保存后监控 `素材库/我的创作/`，一旦检测到新增内容达到阈值，主动提议重新分析。

### 场景三：没有原创内容 / 用户主动提供素材

**前置条件**：`material_scanner.py` 输出 `scene = "场景三：引导提供素材"` 或 `"场景三：用户主动提供素材"`。

**分支 A（用户已提供内容）**：
1.  **识别与提取**：根据来源类型（链接/文件/文本）提取纯文本。小红书链接优先调用 `skills/xhs-content-reader`。
2.  **归档**：将提取的内容保存到 `素材库/我的创作/`。
3.  **流转**：统计总文件数，若 ≥3 则转入场景一，否则转入场景二。

**分支 B（无任何内容）**：
1.  **引导话术**：明确告知用户需要“你自己写的东西”，提供三种路径：发送链接/文件、手动输入一段文本、或指定本地已有的素材库路径。
2.  **无法识别提示**：若用户指定路径中包含 `.zip` 等无法直接读取的文件，需主动提示用户解压。

### 场景四：持续校准

当用户已有《风格说明书》时，严格按 `references/calibration-protocol.md` 执行校准流程：
1.  **单次修改反馈**：记录 diff 并给出简短反馈。
2.  **累积校准**：调用 `calibration_analyzer.py` 分析修改模式，若触发更新规则则更新说明书。
3.  **增量更新**：计算合并权重并更新元信息。
4.  **验证**：调用 `spec_validator.py` 验证完整度。

---

## 核心约束 (Core Constraints)

以下规则优先级高于所有流程步骤，任何场景下均不可违反：

### 数据真实性（CP10）
- **严禁编造或猜测风格特征**。所有写入说明书的特征必须有用户原创内容作为直接证据，无法确认的特征必须标注 `[待验证]`。
- **严禁伪造验证样本**。说明书中的"验证样本"模块只能使用用户原文片段。

### Agent 行为约束（CP05）
- **禁止跳过用户确认环节**。首次生成和重大更新后必须展示给用户确认。
- **禁止擅自降级置信度**。样本不足时必须如实标注 `confidence: low`。
- **禁止越权调用下游技能**。本技能只负责提取风格和生成说明书。
- **禁止合并参考素材风格**。参考素材仅用于反面对比（提取禁用清单）。

### 异常处理与交互（CP07）
- **脚本失败**：任一脚本返回非零退出码或非法 JSON 时，停止流程并展示错误。
- **小红书提取**：优先 CDP 方案，权限不足时自动降级为 `browser_use + OCR`，仍失败则引导手动复制。
- **无法识别文件**：当 `material_scanner.py` 返回 `unrecognized_files` 非空时，必须向用户展示清单并建议解压或转换格式，不得静默忽略。
- **记忆读写异常**：失败时将说明书内容直接输出到对话中供用户手动保存。

---

## 资源索引

| 文件 | 用途 | 何时读取 |
|------|------|----------|
| `references/extraction-pipeline.md` | 风格提取五步详细流程 | 执行风格提取时 |
| `references/scene-execution-guide.md` | 场景一/二/三的分步执行指令链 | 进入对应场景时 |
| `references/style-spec-template.md` | 风格说明书模板（含深度指标解读） | 生成/更新说明书时 |
| `references/content-sources.md` | 内容提取能力矩阵 + 子技能调用 | 处理用户提供的文件/链接时 |
| `references/calibration-protocol.md` | 持续校准协议（diff格式/映射表/话术） | 场景四持续校准时 |
| `scripts/material_scanner.py` | 素材库扫描 + 场景路由判定 | **进入技能的第一步** |
| `scripts/quantitative_analysis.py` | 单篇定量统计（五大维度深度分析） | Step 1 单篇分析时 |
| `scripts/cross_sample_aggregator.py` | 跨篇特征频率统计与汇总 | Step 2 跨篇提炼时 |
| `scripts/spec_metadata.py` | 说明书元信息管理（version/confidence/加权合并） | 生成/更新说明书时 |
| `scripts/calibration_analyzer.py` | 校准 diff 统计与模式→字段映射 | 场景四累积校准时 |
| `scripts/spec_validator.py` | 说明书完整度自动检查 | 生成/更新说明书后 |
| `skills/xhs-content-reader/` | 小红书内容读取子技能（CDP 协议） | 处理小红书链接时优先调用 |

---

## 上下游衔接

**上游：知识管家 (knowledge-butler)**
本技能专为知识管家用户设计。扫描路径：
- `1-素材/文稿/`（用户自写文字）→ 原创素材，正向学习风格特征
- `1-素材/收藏/`（外部剪藏内容）→ 参考素材，**仅用于反向对比**（提取禁用清单），**不**作为风格学习目标

若检测到目录中存在无法直接读取的文件（如压缩包），将主动引导用户处理。

**下游：风格应用 + 回流知识管家**
生成的《风格说明书》存两个地方：
1. **悟空记忆**：技术性数据，供其他 skill（内容生成、校准）引用
2. **知识管家 wiki**：作为长期资产——用户把说明书内容回贴给知识管家，走其「工作流 4 · 外部材料归档」，最终存为 `2-知识网络/专题/我的写作风格.md`

两份并行存在：悟空记忆 = 引擎室，wiki = 档案馆。用户拥有文件系统的副本，防止平台锁定。

---

## 边界与预期管理

**做的**：提取风格 → 生成说明书 → 展示对比 → 持续校准
**不做的**：不从参考素材学风格、不做内容生成、不做素材管理

**量化说明**：
- **还原度上限**：受限于模型训练数据的分布差异，AI 无法 100% 复刻用户的潜意识表达习惯。
- **迭代必要性**：建议用户在初期至少提供 3-5 篇不同场景的原创内容，并进行不少于 3 次的“即时反馈”，以快速突破 70% 的还原度门槛。