# content-forge / CLAUDE.md

## 1) 项目定位

`content-forge` 是一个「以 Obsidian Vault 为单一内容源」的自媒体内容生产编排项目，目标是把选题、写作、配图、格式化、发布变成可重复执行的流水线。

核心边界：
- 只新增一个本地 skill：`write-article`（文章生成）。
- 其余能力优先复用现有 `baoyu-*`、`image-gen-orchestrator`、`basic-image-gen`、`social-media-pipeline`。
- 所有中间产物必须落到 Vault，禁止在多个系统维护平行真相。

成功标准：
- 可以从 `01-topics` 的选题笔记自动产出 `02-drafts` 草稿。
- 可以把草稿格式化并生成配图资产，再发布到微信/X。
- 全链路状态通过 frontmatter 字段可追踪。

### 1.1 Quick Start

```bash
# 1. 初始化 Vault（创建目录 + 注册到 Obsidian）
bash scripts/init-vault.sh

# 2. 验证环境
command -v obsidian            # CLI 可用
obsidian vault                 # Vault 已注册
obsidian search query="templates"  # 模板可搜索

# 3. 创建第一个选题
obsidian create path="01-topics/2026-03-02-my-first-topic.md" content="---
title: 我的第一个选题
slug: my-first-topic
status: topic
content_type: article
---

# 选题内容"

# 4. 用 write-article skill 生成草稿
# 在 Claude Code 中执行：/write-article
```

### 1.2 项目文件结构

```text
content-forge/
├── CLAUDE.md                          # 项目规范（本文件）
├── scripts/
│   └── init-vault.sh                  # Vault 初始化脚本
├── .claude/
│   └── skills/
│       └── write-article/             # 本项目唯一新增 skill
│           ├── SKILL.md               # skill 定义与工作流
│           └── references/
│               └── writing-styles.md  # 4 种写作风格规范
└── content-forge/                     # Obsidian Vault（内容存储）
    ├── 00-inbox/                      # 临时灵感、原始素材
    ├── 01-topics/                     # 结构化选题
    ├── 02-drafts/                     # 初稿/改稿
    ├── 03-review/                     # 待审核稿
    ├── 04-published/                  # 已发布归档
    ├── 05-assets/                     # 配图、封面等资产
    └── templates/                     # article / tech-blog / social-post
```

---

## 2) 完整依赖关系图

### 2.1 技能依赖图（必读）

```mermaid
graph TD
    WA[write-article<br/>新建] --> OBS[obsidian:obsidian-cli]

    BAI[baoyu-article-illustrator] --> AUTO[image gen skill auto-discover]
    BCI[baoyu-cover-image] --> AUTO
    BXI[baoyu-xhs-images] --> AUTO
    BINF[baoyu-infographic] --> AUTO

    AUTO --> IGO[image-gen-orchestrator]
    IGO --> BIG[basic-image-gen<br/>硬依赖]
    AUTO --> BIMG[baoyu-image-gen<br/>备选]

    PTW[post-to-wechat] --> M2H[baoyu-markdown-to-html<br/>硬依赖]
    PTW --> CDP[Chrome CDP 发布链路]
    PTW --> WXA[WeChat API 发布链路]

    PTX[post-to-x] --> XCDP[Chrome CDP + X 登录态]

    UTM[url-to-markdown] --> UCDP[Chrome CDP]

    FMD[format-markdown] --> REMARK[remark + remark-cjk-friendly]

    SMP[social-media-pipeline] --> NONE[无 skill 运行时依赖]
```

### 2.2 生产链路图（执行顺序）

```text
social-media-pipeline
  -> url-to-markdown（可选：采集外部素材）
  -> write-article
  -> format-markdown
  -> baoyu-cover-image / baoyu-article-illustrator / baoyu-xhs-images / baoyu-infographic
      -> image-gen-orchestrator -> basic-image-gen
  -> post-to-wechat
  -> post-to-x
```

---

## 3) 必需插件 / API 清单

### 3.1 插件与本地技能

| 类型 | 名称 | 作用 | 必要性 | 最小验证 |
|---|---|---|---|---|
| 插件 | `obsidian` | 提供 `obsidian-cli`（Vault 读写） | 必需 | `obs vault` |
| 插件包 | `ai-generation-skills` 或 `content-skills` | 提供 `baoyu-*` 系列技能 | 必需 | 在技能列表可见对应 skill |
| 本地 skill | `basic-image-gen` | 图片生成底层能力 | 必需 | 能被 `image-gen-orchestrator` 调用 |
| 本地 skill | `image-gen-orchestrator` | 批量图片编排 | 必需 | 触发图像任务成功返回 |
| 本地 skill | `social-media-pipeline` | 选题/模板/日历方法论 | 建议启用 | 能输出结构化选题与日历 |
| 本地 skill | `write-article` | 从 Vault 选题生成文章 | 必需（本项目唯一新增） | 生成 `02-drafts/*.md` |

### 3.2 外部依赖与环境变量

| 类别 | 项 | 用途 | 关键配置 |
|---|---|---|---|
| 浏览器 | Google Chrome | CDP 抓取与发布（url-to-markdown / post-to-wechat / post-to-x） | 本机可启动 Chrome |
| 图像 API | OpenAI / Google / DashScope 任一 | `basic-image-gen` 推理 | `OPENAI_API_KEY` 或 `GOOGLE_API_KEY` 或 `DASHSCOPE_API_KEY` |
| 微信发布 | WeChat API（API 模式） | 公众号发布 | `WECHAT_APP_ID`, `WECHAT_APP_SECRET` |
| 微信/X 发布 | 浏览器登录态（CDP 模式） | 无 API 时发布兜底 | 本地已登录对应账号 |
| 配置文档 | `EXTEND.md`（各 skill） | 首次配置入口 | 按 skill 文档逐项完成 |

---

## 4) Vault 目录约定与 frontmatter 规范

### 4.1 目录约定（固定）

默认 Vault 路径：`<PROJECT_ROOT>/content-forge/`（通过 `scripts/init-vault.sh` 初始化，可用 `VAULT_PATH` 环境变量覆盖）。

Obsidian CLI 用**目录名**作为 vault 名称，因此目录名必须是 `content-forge`（非 `vault`），命令中使用 `vault="content-forge"` 指定。

```text
<VAULT_ROOT>/
├── 00-inbox/        # 临时灵感、原始素材、待分类
├── 01-topics/       # 结构化选题（write-article 输入）
├── 02-drafts/       # 初稿/改稿（format-markdown 输入）
├── 03-review/       # 待审核稿（人工或规则审校）
├── 04-published/    # 已发布内容归档
├── 05-assets/       # 配图、封面、信息图等资产
└── templates/       # 模板（article / tech-blog / social-post）
```

命名规则：
- 文件名：`YYYY-MM-DD-<slug>.md`
- 资产目录：`05-assets/<slug>/...`
- 一个内容单元（topic/draft/review/published）使用同一个 `slug`，避免多份身份。

### 4.2 frontmatter 统一规范

所有 `01-topics`、`02-drafts`、`03-review`、`04-published` 笔记必须包含以下字段：

```yaml
---
id: "2026-03-01-example-slug"
title: "示例标题"
slug: "example-slug"
status: "topic" # topic | draft | review | published | archived
content_type: "article" # article | thread | x-post | wechat-post | infographic
channels: ["wechat", "x"]
language: "zh-CN"
source_urls: []
assets: []
cover_image: ""
template: "article"
owner: "content-forge"
created_at: "2026-03-01T00:00:00+08:00"
updated_at: "2026-03-01T00:00:00+08:00"
published_at: null
---
```

字段约束：
- `id` 与 `slug` 一一对应，禁止同 slug 多 id。
- `status` 只能按 `topic -> draft -> review -> published` 前进。
- `assets` 只存 Vault 相对路径（禁止外部临时路径）。

---

## 5) 内容生产流水线（阶段 -> skill -> obs 命令）

> 说明：以下命令是编排约定，默认在已注册 Vault 环境执行。

| 阶段 | 输入/输出 | Skill | obs 命令（最小可执行） |
|---|---|---|---|
| S0 选题入库 | 输入：灵感/素材；输出：`01-topics/*.md` | `social-media-pipeline`（方法论） | `obsidian create path="01-topics/2026-03-01-<slug>.md"` |
| S1 外链采集（可选） | 输入：URL；输出：Markdown 摘要并入 topic | `url-to-markdown` | `obsidian read path="01-topics/2026-03-01-<slug>.md"` |
| S2 草稿生成 | 输入：topic；输出：`02-drafts/*.md` | `write-article` | `obsidian create path="02-drafts/2026-03-01-<slug>.md"` |
| S3 状态标记 | 输入：draft；输出：frontmatter 完整化 | `write-article` | `obsidian property:set path="02-drafts/2026-03-01-<slug>.md" name="status" value="draft"` |
| S4 格式清洗 | 输入：draft；输出：发布友好 Markdown | `format-markdown` | `obsidian read path="02-drafts/2026-03-01-<slug>.md"` |
| S5 视觉资产生成 | 输入：final markdown；输出：`05-assets/<slug>/...` | `baoyu-cover-image` / `baoyu-article-illustrator` / `baoyu-xhs-images` / `baoyu-infographic` -> `image-gen-orchestrator` -> `basic-image-gen` | `obsidian property:set path="02-drafts/2026-03-01-<slug>.md" name="assets" value='["05-assets/<slug>/cover.png"]'` |
| S6 审核入列 | 输入：draft+assets；输出：`03-review/*.md` | 人工审核 + 必要 skill 回修 | `obsidian move path="02-drafts/2026-03-01-<slug>.md" to="03-review"` |
| S7 发布微信 | 输入：review 稿；输出：公众号文章 | `post-to-wechat`（依赖 `baoyu-markdown-to-html`） | `obsidian property:set path="03-review/2026-03-01-<slug>.md" name="channels" value='["wechat","x"]'` |
| S8 发布 X | 输入：review 稿；输出：X 帖子 | `post-to-x` | `obsidian property:set path="03-review/2026-03-01-<slug>.md" name="status" value="published"` |
| S9 发布归档 | 输入：发布结果；输出：`04-published/*.md` | 发布后归档流程 | `obsidian move path="03-review/2026-03-01-<slug>.md" to="04-published"` |

### 5.1 常用命令速查

```bash
# 选题
obsidian create path="01-topics/YYYY-MM-DD-<slug>.md" content="<MARKDOWN>"
obsidian read   path="01-topics/YYYY-MM-DD-<slug>.md"

# 草稿
obsidian create path="02-drafts/YYYY-MM-DD-<slug>.md" content="<MARKDOWN>"
obsidian property:set path="02-drafts/YYYY-MM-DD-<slug>.md" name="status" value="draft"

# 阶段流转
obsidian move path="02-drafts/YYYY-MM-DD-<slug>.md" to="03-review"
obsidian move path="03-review/YYYY-MM-DD-<slug>.md" to="04-published"

# 查找
obsidian search query="<slug>"

# 资产关联
obsidian property:set path="<path>" name="assets" value='["05-assets/<slug>/cover.png"]'
```

### 5.2 端到端最小验证链路

```bash
obsidian vault
obsidian create path="01-topics/2026-03-01-demo.md" content="# Demo Topic"
obsidian read path="01-topics/2026-03-01-demo.md"
obsidian create path="02-drafts/2026-03-01-demo.md" content="# Demo Draft"
obsidian property:set path="02-drafts/2026-03-01-demo.md" name="status" value="draft"
obsidian search query="2026-03-01-demo"
```

---

## 6) Obsidian CLI 使用规范与故障排查

### 6.1 使用规范（强制）

1. 所有写入必须使用 Vault 相对路径，禁止绝对路径。
2. 写入前先创建文件，再写 frontmatter 属性，避免属性写入到不存在文件。
3. 每次阶段切换都要更新 `status` 与 `updated_at`。
4. 资产路径统一写入 `assets` 数组，不在正文硬编码临时 URL。
5. 发布前必须能通过 `obsidian search query="<slug>"` 找到 topic/draft/review/published 至少一个节点。

### 6.2 故障排查（按优先级）

| 症状 | 根因 | 诊断命令 | 处理动作 |
|---|---|---|---|
| `obsidian: command not found` | CLI 未安装或 PATH 未注入 | `command -v obsidian` | 按 obsidian-setup skill 安装 |
| `obsidian vault` 无输出或报错 | Vault 未注册 | `obsidian vault` | 运行 `scripts/init-vault.sh` 或手动注册 |
| `obsidian read` 失败 | 路径拼写或文件不存在 | `obsidian search query="<slug>"` | 先 `obsidian create` 再 `obsidian read` |
| `obsidian property:set` 不生效 | frontmatter 块损坏或 name 拼写错误 | `obsidian read path="<path>"` | 修复 frontmatter 结构后重试 |
| `obsidian vault` 段错误（segfault） | CLI 版本与系统不兼容或内存问题 | `obsidian --version` | 重新安装 CLI：`npm i -g obsidian-cli` 或 `pip install obsidian-cli`；如持续崩溃，用文件系统直接读写 Vault 作为降级方案 |
| 配图 skill 调用失败 | `basic-image-gen` API key 缺失 | 检查环境变量 | 补齐 `OPENAI_API_KEY/GOOGLE_API_KEY/DASHSCOPE_API_KEY` |
| 微信/X 发布失败 | 登录态失效或接口凭证过期 | 检查浏览器登录态/API 凭证 | 重新登录或刷新凭证 |

### 6.3 运行前检查清单

```bash
command -v obsidian
obsidian vault
obsidian search query="templates"
```

通过后再执行流水线，避免中途失败回滚。

---

## 7) 已知问题与限制

| 问题 | 影响 | 状态 | 降级方案 |
|---|---|---|---|
| `obsidian vault` 执行时 segfault（核心已转储） | 无法通过 CLI 操作 Vault | 待修复 | 用文件系统直接读写 `content-forge/` 目录 |
| 所有内容目录为空 | 流水线尚未有端到端产出 | 正常（项目刚初始化） | 按 Quick Start 创建首个选题 |
| `obsidian` 插件 CLI 与 Obsidian 桌面客户端为独立进程 | 桌面端修改不会自动触发 CLI 事件 | 设计如此 | 以文件系统为准，CLI 和桌面端都会读取同一目录 |

---

## 版本

- **CLAUDE.md 版本**：1.1.0
- **最后更新**：2026-03-02
- **项目阶段**：初始化完成，待首次端到端验证