文档版本: 1.0
创建日期: 2025年6月14日
设计依据: URD V1.1, ADD V1.0
撰写人: “植耕大师”程序员

1. 文档引言

本模块设计文档（MDD）旨在详细阐述“植耕大师”平台中四大核心模块（设计参数 DP₁ 至 DP₄）的内部结构、接口定义、数据模型、核心算法及测试方案。本文档是连接高层架构设计与底层编码实现的枢纽，其目标是确保开发过程的精确性、一致性与高质量。

2. 系统架构总览

依据公理设计（ADD），系统被解耦为四个核心模块，它们之间通过定义清晰的数据契约进行交互，形成一个单向的数据流，确保了系统的稳定与可维护性。

数据流示意图:

[ DP₁: 项目数据核心 ]
     |
     v (核心数据: 角色, 世界, 冲突)
[ DP₂: 结构化规划器 ]
     |
     v (结构化大纲)
[ DP₃: 沉浸式写作环境 ]
     |
     v (章节稿件)
[ DP₄: 全局分析引擎 ]
     |
     v (最终修订报告)
[   完稿   ]

此结构确保了“先有骨，后生肉”的设计哲学在工程层面的实现。

3. 模块详细设计

模块一：项目数据核心 (DP₁: Project Data Core)

  • 3.1.1 模块职责 (Purpose)
    此模块是整个项目的数据中枢与“真理之源”。它不执行复杂的业务逻辑，其核心职责是为所有项目数据（设定、角色、世界等）提供统一的、类型安全的存储、访问接口与验证机制。它将数据之经纬，为故事之生长立下基石。

  • 3.1.2 对外接口 (Interfaces)
    此模块主要通过定义数据模型（契约）与服务接口来对外暴露功能。

    • 服务接口: ProjectDataService
      • createProject(config: ProjectConfig): Promise<ProjectID>
      • loadProject(id: ProjectID): Promise<ProjectData>
      • saveProject(data: ProjectData): Promise<void>
      • validate(data: ProjectData): Promise<{isValid: boolean, errors: any[]}>

  • 3.1.3 数据模型 (Data Models - JSON Schema)
    这是本模块的核心产出，是整个应用的数据契约。

    • ProjectConfig:

      {
  "type": "object",
  "properties": {
    "projectName": { "type": "string" },
    "writingStyle": { "type": "string" },
    "pov": { "enum": ["FirstPerson", "ThirdPersonLimited", "ThirdPersonOmniscient"] },
    "coreTheme": { "type": "string" },
    "targetWordCount": { "type": "integer" },
    "creativeMode": { "enum": ["Explore", "Refine"] }
  },
  "required": ["projectName", "coreTheme"]
}

    • CoreConcept:

      {
  "type": "object",
  "properties": {
    "oneSentenceSummary": { "type": "string", "maxLength": 100 },
    "fiveSentenceSynopsis": {
      "type": "object",
      "properties": {
        "act1_setup": { "type": "string" },
        "act1_disaster1": { "type": "string" },
        "act2_disaster2": { "type": "string" },
        "act2_disaster3": { "type": "string" },
        "act3_resolution": { "type": "string" }
      }
    }
  }
}

    • CharacterProfile:

      {
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "background": { "type": "string" },
    "psychology": {
      "type": "object",
      "properties": {
        "fear": { "type": "string", "description": "最大的恐惧" },
        "desire": { "type": "string", "description": "内心最深的渴望" },
        "secret": { "type": "string" },
        "philosophy": { "type": "string" }
      }
    },
    "arc": {
      "type": "object",
      "properties": {
        "externalGoal": { "type": "string", "description": "想要什么 (Want)" },
        "internalNeed": { "type": "string", "description": "需要什么 (Need)" },
        "epiphany": { "type": "string", "description": "为达成目标必须学习的顿悟" }
      },
      "required": ["externalGoal", "internalNeed", "epiphany"]
    }
  },
  "required": ["name", "psychology", "arc"]
}

    • WorldSetting: (结构同理，此处从略)

    • ConflictMatrix: (结构同理，此处从略)

  • 3.1.4 核心逻辑与算法 (Core Logic & Algorithms)

    • 数据验证: validate函数将使用标准的JSON Schema验证库，对传入的ProjectData对象进行深度验证，确保数据完整性与类型正确性。

  • 3.1.5 错误处理 (Error Handling)

    • 文件读写失败时，向上层抛出IOException。
    • 数据验证失败时，返回包含详细错误信息的errors数组。

  • 3.1.6 测试驱动开发计划 (TDD Plan)

    • Test Case 1: test_create_and_load_project: 验证项目创建后，能被成功加载，且数据一致。
    • Test Case 2: test_character_profile_validation: 创建一个缺少epiphany字段的角色档案，断言validate函数返回isValid: false。
    • Test Case 3: test_immutability_on_save: 加载一个项目，修改其数据后保存，再次加载，断言数据为修改后的新状态，证明保存操作的原子性。

模块二：结构化规划器 (DP₂: Structural Planner)

  • 3.2.1 模块职责 (Purpose)
    此模块是“建筑师”的核心工具。它接收故事的“原材料”（冲突、角色），并依据经典的叙事学理论，将其锻造成坚实的情节骨架（大纲）。

  • 3.2.2 对外接口 (Interfaces)

    • 函数签名: 
      function generateOutline(
    conflicts: ConflictMatrix,
    template: OutlineTemplate,
    characters: CharacterProfile[]
): StoryOutline;

  • 3.2.3 数据模型 (Data Models)

    • OutlineTemplate: 
      {
  "name": "三幕式结构",
  "nodes": [
    { "id": "setup", "label": "开端设定", "promptHint": "介绍主角的日常生活和核心渴望" },
    { "id": "inciting_incident", "label": "激励事件", "promptHint": "一个打破主角日常的事件，通常与一个强烈的外部冲突相关", "conflictAffinity": "ExternalConflict.ProtagonistVsWorld" },
    { "id": "midpoint", "label": "中点", "promptHint": "主角由被动转为主动，价值观受到重大挑战", "conflictAffinity": "InternalConflict.DesireVsFear" },
    // ...其他节点
  ]
}
    • StoryOutline: 一个树状结构，每个节点包含id, label, 和由AI填充的content。

  • 3.2.4 核心逻辑与算法 (Core Logic & Algorithms)

    • 冲突-节点映射算法:
      1. 遍历OutlineTemplate的每一个node。
      2. 读取节点的conflictAffinity元数据标签。
      3. 根据标签，在ConflictMatrix中查找最匹配的冲突项。
        • 例如，对于conflictAffinity: "InternalConflict.DesireVsFear"，算法会优先寻找主角的内在冲突。
        • 若无精确匹配，则采用备用策略（如选择最强烈的冲突）。
      4. 将选定的冲突作为核心上下文，构建一个精确的prompt，调用Writer_AI，请求其为该节点生成一段描述性文本。
      5. 汇总所有节点的生成结果，构成完整的StoryOutline。

  • 3.2.5 错误处理 (Error Handling)

    • 若ConflictMatrix为空，返回一个带有提示信息的空大纲。
    • 若AI调用失败，允许用户对该节点进行手动填充或重试。

  • 3.2.6 测试驱动开发计划 (TDD Plan)

    • Test Case 1: test_inciting_incident_uses_external_conflict: 提供一个包含明确内外冲突的ConflictMatrix，使用“三幕式”模板，断言为“激励事件”节点生成的prompt中包含了那个外部冲突。
    • Test Case 2: test_custom_template_functionality: 用户自定义一个包含5个节点的模板，断言generateOutline能成功处理并返回一个含5个节点的StoryOutline。

模块三：沉浸式写作环境 (DP₃: Immersive Writing Environment)

  • 3.3.1 模块职责 (Purpose)
    此模块是“园丁”的耕作之地。它提供一个无干扰的写作界面，同时将所有必需的上下文信息（由RAG_AI提供）和强大的生成能力（由Writer_AI提供）无缝整合，让创作在框架内自由生长。

  • 3.3.2 对外接口 (Interfaces)

    • 函数签名: 
      // RAG_AI 调用
function retrieveContextForChapter(chapterIndex: number, projectData: ProjectData): ChapterContext;

// Writer_AI 调用
function generateDraft(context: ChapterContext, prompt: string): Promise<string[]>; // 返回1-3个版本

// 本地逻辑
function checkConsistency(text: string, character: CharacterProfile): ConsistencyAlert[];

  • 3.3.3 数据模型 (Data Models)

    • ChapterContext: 包含本章梗概、涉及角色的关键信息（恐惧、目标等）、相关世界观条目。
    • ConsistencyAlert: { level: 'warning' | 'info', message: string, location: [start, end] }

  • 3.3.4 核心逻辑与算法 (Core Logic & Algorithms)

    • retrieveContextForChapter (RAG):
      1. 从StoryOutline中获取第chapterIndex章的梗概。
      2. 通过简单的NLP实体识别，找出梗概中提及的角色和地点。
      3. 从ProjectDataCore中抽取这些实体对应的完整档案。
      4. 将以上信息打包成一个简洁、聚焦的ChapterContext对象。
    • generateDraft Prompt Engineering:
      • 系统角色: "你是一位荣获多项大奖的小说家，精通[项目设定的文风]，擅长‘于无声处听惊雷’的细节描写。"
      • 任务描述: "请根据以下上下文，撰写[小说名]第[X]章的初稿。本章的核心目标是：[本章梗概]。"
      • 上下文注入:
        • "主要角色：[角色A]，他此刻的目标是[...], 但他最大的恐惧是[...]."
        • "世界规则：请记住，在这个世界里，魔法的使用必须[...]."
      • 指令: "请聚焦于角色的行动与感受，‘展示’而非‘告知’。允许在遵循核心逻辑的前提下，探索角色可能做出的、符合其性格的意外之举。"
    • checkConsistency: 使用正则表达式和关键词匹配，检测文本中是否出现与角色核心设定（如恐高症、绝不杀生）相悖的描述。

  • 3.3.5 测试驱动开发计划 (TDD Plan)

    • Test Case 1: test_context_retrieval: 给定一个章节梗概“张三见到了李四”，断言返回的ChapterContext中包含张三和李四的CharacterProfile。
    • Test Case 2: test_draft_prompt_contains_character_fear: 断言为包含特定角色的章节生成的prompt中，明确提到了该角色的核心恐惧。
    • Test Case 3: test_consistency_alert_for_phobia: 输入一个恐高角色档案和“他站在塔顶，俯瞰众生”的文本，断言checkConsistency返回一个非空的警报数组。

模块四：全局分析引擎 (DP₄: Global Analysis Engine)

  • 3.4.1 模块职责 (Purpose)
    此模块是作品的“终审官”与“铸魂师”。它从全局视角审视作品，检查逻辑的严密性、角色弧光的完整性与主题思想的共鸣，确保最终成品不仅结构完整，更拥有深刻的灵魂。

  • 3.4.2 对外接口 (Interfaces)

    • 函数签名: 
      function generateGlobalReview(
    allChaptersText: string,
    projectData: ProjectData
): Promise<ReviewReport>;

  • 3.4.3 数据模型 (Data Models)

    • ReviewReport: 
      {
  "reportId": "uuid",
  "timestamp": "iso-date",
  "summary": { "overallScore": 85, "strengths": ["..."], "weaknesses": ["..."] },
  "logicConsistency": [ { "type": "Contradiction", "message": "角色'李四'在第3章已死，但在第8章出现", "locations": ["Chapter 3", "Chapter 8"] } ],
  "characterArcAnalysis": [ { "characterName": "张三", "arcCompletion": "Positive", "analysis": "角色从初期的犹豫不决到结尾的果断行动，完成了预设的'顿悟'。", "evidence": [ ... ] } ],
  "themeAnalysis": {
    "mainTheme": "自由 vs. 秩序",
    "motifTracking": [ { "motif": "鸟", "occurrences": 15, "sentimentTrend": [0.2, 0.5, 0.9] } ]
  },
  "pacingAnalysis": { "plotPoints": [...], "lowContributionScenes": [ { "location": "Chapter 5", "reason": "场景对情节推进或角色发展贡献度低" } ] }
}

  • 3.4.4 核心逻辑与算法 (Core Logic & Algorithms)

    • 逻辑一致性检查: 使用命名实体识别（NER）追踪关键角色和物品。建立一个状态机，记录每个实体的状态（如{entity: '李四', status: 'dead', chapter: 3}）。当后续章节出现与状态矛盾的行为时，标记为错误。
    • 角色弧光分析:
      1. 定位主角在开篇、中点、结尾等关键情节中的场景。
      2. 使用情感分析和语义向量模型，将这些场景中的主角行为/对话，与其CharacterProfile中的internalNeed和epiphany进行向量空间上的余弦相似度计算。
      3. 相似度随故事进展而提高，则视为正面弧光。
    • 主题意象追踪:
      1. 用户在ProjectConfig中定义核心主题词/意象（如“自由”、“锁链”、“鸟”）。
      2. 使用文本搜索和词嵌入模型，在全书中找到所有相关词汇的出现位置。
      3. 分析每个出现点周围的上下文情感，绘制情感趋势图。

  • 3.4.5 测试驱动开发计划 (TDD Plan)

    • Test Case 1: test_detect_dead_character_speaking: 构造一个包含角色死后复活发言的文本，断言logicConsistency部分能准确报告此错误。
    • Test Case 2: test_positive_character_arc_detection: 输入一个主角从懦弱到勇敢的完整故事，断言characterArcAnalysis结果为Positive。
    • Test Case 3: test_motif_tracker: 输入一篇反复出现“鸟”这个意象的文本，断言motifTracking能准确统计其出现次数并分析其情感。

4. 结论

本模块设计文档（MDD）为“植耕大师”平台的四大核心模块提供了详尽、可操作的设计蓝图。它严格遵循了公理设计的解耦原则，并融入了函数式编程的纯粹性与TDD的可测试性。

至此，从哲学（工作流）到需求（URD），再到架构（ADD）与模块（MDD），我们已完成了所有在工程实现之前的设计工作。设计之舟已备，只待扬帆起航，进入编码的广阔海洋。

植耕大师”程序员
2025年6月14日