# Brand Profile 配置指南

> **Brand Profile** 是 md2wechat 的品牌档案功能，让 AI Agent 在每次排版时都能体现你的个人风格、语气和品牌识别度。

---

## 目录

- [什么是 Brand Profile](#什么是-brand-profile)
- [快速开始](#快速开始)
- [配置文件详解](#配置文件详解)
- [最佳实践](#最佳实践)
- [好与坏的配置示例](#好与坏的配置示例)
- [Agent 如何使用它](#agent-如何使用它)
- [常见问题](#常见问题)

---

## 什么是 Brand Profile

Brand Profile 是一个 Markdown 文件，位于 `~/.config/md2wechat/brand.md`。

它不是一个"设置文件"，而是一封写给 AI Agent 的信，告诉 Agent：

> **"我是谁，我怎么说话，我的文章应该长什么样。"**

### 与 CLI 配置的区别

| 配置文件 | 位置 | 用途 | 谁读取 |
|---------|------|------|--------|
| CLI 运行时配置 | `~/.config/md2wechat/config.yaml` | API keys、provider、主题 | CLI |
| **Brand Profile** | `~/.config/md2wechat/brand.md` | 品牌风格、排版偏好 | **Agent** |

Brand Profile 由 AI Agent 读取，CLI 不解析此文件。这意味着你可以用**完全自然的语言**书写，越具体越好。

### 为什么是 Markdown 而不是 YAML？

因为品牌风格本质上是语言性的，而不是结构化的。

YAML 能告诉 Agent "tone: sharp"，但 Markdown 可以告诉 Agent：

> "我写作像在和朋友聊天。直接说结论，然后给证据。
> 从不用'希望对你有帮助'结尾。
> 反例：'在这个充满变化的时代...' — 这种开头我从来不写。"

**越具体，Agent 越能准确还原你的风格。**

---

## 快速开始

### 1. 初始化 Brand Profile

```bash
md2wechat brand init
```

这会在 `~/.config/md2wechat/brand.md` 创建一个带注释的模板文件。

### 2. 编辑你的档案

用任意编辑器打开并填写：

```bash
# macOS
open ~/.config/md2wechat/brand.md

# 或用 VS Code
code ~/.config/md2wechat/brand.md
```

### 3. 验证 Agent 能读到它

```bash
md2wechat brand show --json
```

响应中 `data.content` 是你的档案内容，`data.path` 是文件路径。

---

## 文件内容建议

Brand Profile 是一个自由格式的 Markdown 文件。下面这些章节只是建议写法，不是 CLI schema。CLI 不解析字段名，Agent 也不应把它当作 YAML 或固定结构读取。

### 基本信息

```markdown
## 基本信息

**名字 / 品牌名**：极客杰尼

**简介**：AI 应用开发者，记录 AI 工具、内容系统和独立产品实践。
```

告诉 Agent 你是谁。Agent 可把这些信息作为作者卡片、个人化表达和品牌锚点的上下文；是否插入具体模块仍要看文章内容和 `layout` discovery 结果。

---

### 语气与风格（最重要）

```markdown
## 语气与风格

**我的风格**：
犀利实用，第一人称。直接说结论，然后给证据。
像在和朋友聊干货，不废话，不升华，不说"希望对你有帮助"。

**我要避免的表达**：
- 过多 emoji（最多 1-2 个）
- 空泛鸡汤（"在这个充满变化的时代..."）
- 过度营销词汇（"革命性"、"颠覆性"）
- 被动语态（"被认为"、"据悉"）
```

这是最影响最终效果的章节。**越具体越好**，写出正例和反例。

---

### 文章开头偏好

```markdown
## 文章开头偏好

**我的偏好**：verdict_first（先结论）

我喜欢开门见山，第一段就给出核心判断。
例如："这个工具我用了三个月，值得推荐，原因有三。"
```

参考选项：
- `verdict_first` — 先给结论，再解释（适合观点型文章）
- `story_first` — 先讲故事或场景（适合案例型文章）
- `question_first` — 先抛问题（适合教程型文章）
- `data_first` — 先给数据（适合报告型文章）

---

### 排版偏好

```markdown
## 排版偏好

- 我偏好模块少而准，不喜欢过度结构化
- 通常只需要一个 CTA
- 观点文章可以多用金句，但不要连续堆 quote
- 除非文章特别长，否则不要用 TOC
```

Agent 会把这些自然语言偏好当作软约束，并用 `md2wechat layout list/show/validate` 验证最终选择。不要把这里写成必须被 CLI 解析的硬字段。

```markdown
## 排版偏好

- 如果文章很短，只用一个 verdict 或 callout 就够了
- 如果文章超过 3000 字，可以考虑 TOC 或 steps
- 如果是教程，优先让读者更容易操作，而不是追求视觉复杂度
```

---

### 默认 CTA

```markdown
## 默认 CTA（行动引导）

**标题**：如果这篇对你有启发
**正文**：欢迎关注，我在持续记录 AI 工具和独立开发实践。每周更新，不灌水。
**行动**：关注 / 转发给有需要的朋友
```

Agent 可在适合的文章末尾参考这个 CTA。如果文章目标不适合转化模块，Agent 可以跳过。

---

### 作者卡片

```markdown
## 作者卡片

**名字**：极客杰尼
**头衔**：AI 应用开发者 / 独立开发者
**简介**：记录 AI 工具、内容系统和独立产品实践。关注从 idea 到 MVP 的完整路径。
```

用于文章末尾的作者介绍模块。

---

### 风格参考（可选）

```markdown
## 风格参考（可选）

我最像这些文章：
- [这里可以粘贴你喜欢的一段文字]
- [这里可以描述一个公开文章或历史稿件]
```

如果你写了本地路径，Agent 可以在用户允许且路径可读时参考，但这不是 CLI 功能，也不是固定字段协议。

---

## 最佳实践

### ✅ 写具体，不写抽象

```markdown
# 好
**我的风格**：
每个观点配一个具体案例。
结论放第一句，细节放后面。
句子控制在 20 字以内。

# 差
**我的风格**：
简洁有力，有深度。
```

### ✅ 写反例

反例对 Agent 的约束力比正例更强：

```markdown
**我要避免的表达**：
- "在 AI 快速发展的今天..." （这种开头我从来不写）
- 结尾用"希望对你有帮助"
- 超过 3 个连续的无序列表
```

### ✅ 可以随时更新

Brand Profile 不是一次性配置。随着你的风格成熟，随时编辑更新：

```bash
code ~/.config/md2wechat/brand.md
```

更新后 Agent 下次读取时立即生效，无需重启或重新配置。

### ✅ 用你自己的话

不需要用特定格式或关键词。Agent 理解自然语言：

```markdown
## 语气

我不喜欢那种"干货博主"的感觉。
我更像是在和一个聪明的朋友分享我真实踩过的坑。
所以我的文章会有自我怀疑，会有"但其实我也不确定"。
```

### ⚠️ 避免过度约束

Brand Profile 是引导，不是硬规则。如果你写了太多限制，Agent 可能很难同时满足所有要求：

```markdown
# 不建议这样写（过度约束）
- 不超过 500 字
- 必须有 3 个标题
- 必须有表格
- 不能用引用
- 必须有代码块
- ...
```

---

## 好与坏的配置示例

### 案例 A：过于简单（效果一般）

```markdown
## 语气与风格

**我的风格**：专业、简洁

**我要避免的表达**：废话
```

Agent 能做的很有限——"专业简洁"几乎适用于所有文章。

### 案例 B：具体有效（推荐）

```markdown
## 语气与风格

**我的风格**：
我是一个 AI 工具评测者，关注"这个工具能帮我省多少时间"而不是"这个工具有多少功能"。
写作直接，第一人称。第一段必须包含我的核心判断。
类比和举例优先于抽象描述。

**我要避免的表达**：
- "全面解析 XXX 的 N 大功能"（功能列表型标题和开头）
- 结尾的"希望对你有帮助"
- 超过 2 层的嵌套列表
- 任何"赋能"、"颠覆"、"革命"等词
```

### 案例 C：带风格参考（最完整）

```markdown
## 语气与风格

**我的风格**：见风格参考文件，已有详细说明。

## 风格参考

我希望更接近这类表达：
- 先讲具体场景，再给判断
- 少用抽象概念，多用真实使用细节
```

Brand Profile 可以直接写风格规则、正例和反例。不要依赖某个固定字段名来驱动 Agent。

---

## Agent 如何使用它

1. **任务开始前**，Agent 检查 Brand Profile 是否存在：
   ```bash
   md2wechat brand show --json
   ```

2. **存在时**，Agent 读取 `data.content`，将全文作为自然语言上下文注入排版决策：
   - 语气和风格应用于全文表达
   - 排版偏好作为软约束
   - CTA 和作者卡片只在适合文章目标时插入

3. **不存在时**，Agent 不阻塞当前任务，只提示一次并继续使用系统默认风格。只有用户明确要求设置时，才发起 3 问引导。

4. **优先级链**（高→低）：
   ```
   CLI flag（--theme 等）
     ↓
   用户本轮明确指令
     ↓
   Brand Profile（brand.md）
     ↓
   CLI 运行时配置（~/.config/md2wechat/config.yaml）
     ↓
   CLI discovery 可验证能力
     ↓
   Agent 保守默认选择
   ```

---

## 常见问题

**Q：修改了 brand.md 后需要重启什么吗？**
A：不需要。Agent 每次任务时重新读取文件，立即生效。

**Q：brand.md 会被同步到 GitHub 吗？**
A：文件位于 `~/.config/` 目录，在项目目录之外，不会被 git 追踪。

**Q：可以有多个 Brand Profile 吗？**
A：目前只支持一个全局 Brand Profile。如果有多品牌需求，可以在本轮任务里明确告诉 Agent 使用哪套品牌语气，或临时编辑 `brand.md` 后再执行。

**Q：brand show 显示的内容是什么格式？**
A：JSON envelope，其中 `data.content` 是你的 brand.md 原始文本，`data.path` 是文件路径。

**Q：如果 brand.md 格式不对会怎样？**
A：Markdown 没有"格式错误"。只要文件可读，Agent 就能使用它。唯一可能失败的情况是文件权限问题（`BRAND_READ_FAILED`）。

**Q：brand.md 里的数量偏好 Agent 一定会遵守吗？**
A：Agent 会把自然语言数量偏好当作软约束；最终仍以 `md2wechat layout list/show/validate` 能验证的模块能力为准。

---