技术文档
架构 · env 字典 · API · 部署红线
面向开发者对接的技术规格，全部与源码实况对齐，无占位信息。
🏗️ 系统架构 · 双 MCP + Coach + KD + Orchestrator
| 服务 | 职责 | 工具数 | 核心文件 | 传输模式 |
|---|---|---|---|---|
| Outline MCP | 作品设定、章卡、章纲路线图、情绪蓝图、幽默基因 | 37 | outline_mcp_server.py | stdio / SSE / HTTP |
| Writer MCP | 正文生成、主编审核、多杠杆重写、读者共振、CTQA | 22+ | writer_server.py | stdio / SSE / HTTP |
| Coach MCP | AI 写作教练、策略指导、问题诊断、调优建议 | 8 | coach_mcp_server.py | stdio / HTTP |
| KD Export | 口袋写作 .kd 生成、验证、预览 | 3 | kd_export_mcp_server.py | stdio / HTTP |
| Orchestrator | 全流程编排、状态管理、HTTP API | — | orchestrator.py | HTTP :8080 |
🔌 Orchestrator HTTP API
REST 接口POST /api/v1/projects # 创建项目
Body: { high_concept, genre, platform, target_chapters }
→ { project_id, status, estimated_time }
POST /api/v1/projects/{id}/pipeline # 执行全流程
→ { project_id, job_id, status, progress_percent, chapters_total }
GET /api/v1/projects/{id} # 项目状态与质量报告
→ { project, tasks }
GET /health # 健康检查
GET /api/v1/metrics # 系统指标
→ { projects_total, tasks_total, projects_by_status }
⚙️ env 字典（核心）
| env | 默认 | 说明 |
|---|---|---|
DEEPSEEK_API_KEY | 必填 | 写作主力密钥 |
WRITER_MODEL_PROVIDER | deepseek | 写作位 provider（k3 仅审不写） |
DEEPSEEK_MODEL | deepseek-v4-pro | 仅此与 v4-flash 有效 |
KIMI_API_KEY | 可选 | K3 评审（写审分离） |
V9_MEMORY_DIR | D:/v9_memory | 指标/日志/幂等根目录 |
OUTPUT_BASE | D:/第四步正文 | 正文输出根目录 |
FINAL_GATE_MIN_SCORE | 90 | 质量门分数 |
REVIEW_MAX_REWRITE | 3 | 最大重写轮数 |
TOMATO_COMPLETION_TARGET | 0.70 | 番茄完读率目标 |
WORD_COUNT_FLOOR/CEILING | 3600/4500 | 字数契约 |
V2_INTEGRATION_ENABLED | 1 | V2 八模块总闸 |
GATEWAY_MODE | stdio | stdio | http |
ORCHESTRATOR_PORT | 8080 | 编排引擎端口 |
COACH_MODEL_PROVIDER | kimi | 教练模型（kimi-k3） |
🚧 部署与运维红线
| # | 红线 |
|---|---|
| 1 | MCP 版本硬约束：Writer 端严禁 mcp>=2.0，必须 1.28.1/1.26.0（API 不兼容）。 |
| 2 | 改 env 必须重启：Cherry Studio 修改 env 后必须「断开 → 重连」真重启，否则不生效。 |
| 3 | env 用纯文本 KEY=VALUE 逐行，严禁 JSON；KEY=VALUE 之间必须留空格。 |
| 4 | 密钥安全：API key 建议配置在服务端/受控环境，网站不暴露真实 key；对公文档一律脱敏。 |
| 5 | 单实例：WRITE_SINGLE_INSTANCE=1 时锁文件持有者存活则新实例拒绝启动；多开请关闭该开关。 |
| 6 | 零回归原则：新增特性 env 默认关；异常 try/except 吞入并打印 ⚠️ 日志，主流程不中断。 |
🔁 数据流 · 全流程一键写作
Pipeline用户输入: "一句话高概念 + 风格需求 + 平台偏好"
▼
[Orchestrator] 意图解析 → 创作任务蓝图
├──→ [Coach] 创作策略建议
├──→ [Outline] init_novel_project → 作品设定
│ ├──→ sync_genesis_genes → 基因注入
│ ├──→ split_chapter_roadmap → 章纲拆分
│ ├──→ batch_generate_chapter_cards → 批量章卡
│ └──→ design_emotion_blueprint → 情绪蓝图
├──→ [Writer] write_chapters_async → 异步批量正文
│ ├──→ 写前注入 → SPG-3 → 生成(3800字)
│ ├──→ L1 主编审核(四员会审+木桶)
│ ├──→ 定向重写 → 质量门(≥90)
│ └──→ 落盘 + 指标归档
├──→ [Writer] CTQA 闭环 → 情绪穿透验证
├──→ [Coach] 终审报告
└──→ [KD Export] 生成 .kd → 导入口袋写作