yu-zhi-ran/YUZHIRAN_PLATFORM.md

# 宇之然内容管理平台 - 完整项目文档

## 📦 项目概览

宇之然内容管理平台是一个集**自动化流水线**与**Web管理界面**于一体的内容生产系统。

- **自动化模块**: 采集→创作→优化→发布的全自动脚本
- **管理平台**: Web UI 监控、控制、发布包管理
- **数据源**: 单一 JSON 文件 + 本地案例库
- **目标**: 每日自动生成高质量原创内容，多平台分发

## 🏗️ 目录结构

```
yu-zhi-ran/
├── platform/                 # 管理平台（FastAPI + Vue 3）
│   ├── backend/              # FastAPI 后端
│   │   └── app/
│   │       ├── api/          # REST API
│   │       │   ├── system.py # 系统状态、流水线控制
│   │       │   ├── topics.py # 选题管理
│   │       │   ├── publisher.py # 发布包管理
│   │       │   └── articles.py
│   │       └── core/         # 业务逻辑封装
│   │           ├── generator.py → 调用 scripts/creator.py
│   │           ├── optimizer.py → 调用 scripts/compliance_optimizer.py
│   │           └── sync.py    → 同步 automation/data/*.json
│   └── frontend/             # Vue 3 前端（CDN依赖）
│       └── index.html
├── automation/               # 自动化流水线（脚本+数据+日志）
│   ├── scripts/ (软链) → ../scripts/
│   ├── data/                # JSON 数据源
│   │   ├── sustainability_topics.json  # 选题库
│   │   ├── drafts/          # 草稿目录
│   │   └── releases/        # 发布包（按日期）
│   └── logs/                # 运行日志
│       ├── collector_*.log
│       ├── creator_*.log
│       ├── optimizer_*.log
│       └── publisher_*.log
├── scripts/                  # 底层CLI脚本（被automation/scripts/引用）
│   ├── collector.py         # 采集热点
│   ├── creator.py           # 内容创作
│   ├── compliance_optimizer.py  # 合规优化
│   ├── publisher.py         # 发布包生成
│   ├── research.py          # 研究资料
│   ├── outline.py           # 大纲生成
│   └── writer.py            # 撰写主力
├── content/                  # 已发布内容存储
│   ├── published/           # 按 topic_id 组织
│   ├── drafts/              # 草稿
│   ├── ideas/               # 选题记录
│   └── images/              # 配图资源
├── config/                   # 配置文件
│   ├── sources.yaml         # RSS/网页源配置
│   └── wecom_config.yaml    # 企业微信通知
├── brand/                    # 品牌资产
│   ├── brand-book.md
│   └── guidelines.md
├── research/                 # 行业研究
│   └── trends-2026.md
├── strategy/                 # 内容策略
│   └── 全球-本土比较研究与全新内容战略规划-2026-04-15.md
├── tasks/                    # 项目管理
│   └── todo.md
├── logs/                     # 根目录日志（兼容）
├── backup/                   # 备份归档
├── README.md                 # 项目总览
├── TEST_FULL_PIPELINE.md     # 测试指南
└── run_publisher.sh          # 快速启动发布任务

# 软链接（保持路径兼容）
automation/scripts → ../scripts/
```

---

## 🚀 快速开始

### 方式一：直接运行自动化流水线（CLI）

```bash
cd /root/openclaw-workspace/projects/yu-zhi-ran

# 手动执行各步骤
python scripts/collector.py        # 采集选题
python scripts/creator.py          # 创作内容
python scripts/compliance_optimizer.py  # 合规优化
python scripts/publisher.py        # 生成发布包

# 或使用测试脚本
python test_full_pipeline.py --topic-id A01
```

### 方式二：启动 Web 管理平台

```bash
cd platform
./run.sh 8001

# 访问
# - 界面: http://localhost:8001/
# - API文档: http://localhost:8001/docs
```

**功能**：
- 📊 仪表盘：选题统计、今日生成
- 🔄 控制台：一键触发 collector/creator/optimizer
- 📝 选题管理：列表、预览、状态
- 📦 发布管理：生成发布包、查看HTML、复制
- 📋 日志查看：所有模块实时日志

### 方式三：定时自动运行（cron）

```bash
# 编辑 crontab
crontab -e

# 添加以下任务（参考）
0 5 * * * cd /path/to/yu-zhi-ran && python automation/scripts/collector.py
30 5 * * * cd /path/to/yu-zhi-ran && python automation/scripts/creator.py
45 5 * * * cd /path/to/yu-zhi-ran && python automation/scripts/compliance_optimizer.py
0 6 * * * cd /path/to/yu-zhi-ran && python automation/scripts/publisher.py
```

---

## 🔄 系统架构

### 数据流

```
┌─────────────────┐
│  采集/创作/优化  │ ←─ automation/scripts/*.py
│  (CLI 脚本)     │
└────────┬────────┘
         │ 读写 JSON
         ▼
┌─────────────────┐
│ automation/data │
│ sustainability_ │
│   topics.json   │
└────────┬────────┘
         │ 同步
         ▼
┌─────────────────┐
│  platform/      │
│  FastAPI +      │
│  SQLite DB      │
└────────┬────────┘
         │ HTTP API
         ▼
┌─────────────────┐
│  Web 前端        │
│  (Vue 3)        │
└─────────────────┘
```

### 触发流程

| 操作 | API端点 | 执行脚本 | 结果 |
|------|---------|----------|------|
| 点击"运行创作任务" | POST `/api/system/generate/run` | `scripts/creator.py` | 生成草稿 → 状态: 待审查 |
| 点击"运行合规优化" | POST `/api/system/optimize/run` | `scripts/compliance_optimizer.py` | 全自动通过 → 状态: 待发布 |
| 点击"生成发布包" | POST `/api/publisher/generate/{id}` | `scripts/publisher.py` | HTML包 → content/published/ |
| 页面刷新 | GET `/api/system/status` | - | 显示最新状态 |

---

## 📊 当前状态（2026-04-19）

- **选题库**: 22 个（20 待处理 + 2 待发布）
- **自动运行**: ✅ 每日 05:00-06:00 全流程
- **上次运行**: 2026-04-19 05:30（A02 选题，8秒完成）
- **合规通过率**: 100%（小样本）
- **发布包**: A01、A02 已就绪（知乎+小红书）

查看详细日志：
```bash
tail -f automation/logs/creator_$(date +%Y-%m-%d).log
tail -f automation/logs/publisher_$(date +%Y-%m-%d).log
```

---

## 🔧 开发调试

### 检查环境
```bash
cd platform
python check.py
```

### 手动测试流水线
```bash
python test_full_pipeline.py --topic-id A05
```

### API 测试
```bash
# 系统状态
curl http://localhost:8000/api/system/status

# 触发创作
curl -X POST http://localhost:8000/api/system/generate/run

# 流水线状态
curl http://localhost:8000/api/system/pipeline/status
```

### 数据库重置
```bash
cd platform/backend
rm -f data/yzr.db
python -c "from app.database import init_db; init_db()"
```

---

## 📝 配置说明

### automation/config/sources.yaml

配置外部信息源（RSS/网页）：

```yaml
sources:
  - name: "新华网-环保频道"
    type: "rss"
    url: "http://www.news.cn/..."
    focus: "可持续性"

  - name: "人民网-生态环境"
    type: "rss"
    url: "http://env.people.com.cn/..."
    focus: "环保政策"
```

### platform/.env (可选)

```bash
PROJECT_ROOT=/path/to/yu-zhi-ran
DATA_DIR=/path/to/data
LOG_LEVEL=INFO
```

---

## 🎯 核心特性

| 特性 | 实现 |
|------|------|
| **降级策略** | 外部源失败 → 本地数据库 → Markdown案例库 |
| **锁机制** | 2小时超时，防止并发冲突 |
| **状态同步** | JSON ↔ SQLite 自动同步 |
| **发布准备** | 生成多平台HTML + 发布指南，人工发布（风控） |
| **Web管理** | Vue 3 单页应用，无需构建 |
| **日志聚合** | 所有模块日志按日期归档 |

---

## 🚧 待办事项

- [ ] 添加用户认证（目前仅本地访问）
- [ ] 实现异步任务状态轮询（创作/优化耗时较长）
- [ ] Nginx 反向代理配置（外网访问）
- [ ] 监控告警（失败通知）
- [ ] 多账号/IP策略（小红书多号分散风险）
- [ ] 数据导出功能（选题库、发布记录）

---

## 📚 相关文档

- `platform/PORTFOLIO.md` - 平台架构详解
- `platform/README.md` - 管理平台使用说明
- `PROJECT_PLAN_V2.md` - 盈利模式与5平台矩阵
- `HERMES_AND_YUZHRAN_STATUS.md` - 多Agent共享状态
- `2026-04-18-YUZHRAN-FIXES-SUMMARY.md` - 技术修复总结

---

**版本**: 2.0 (2026-04-19)
**维护**: 宇之然 AI 助手
**最后更新**: 2026-04-19