六模型能力栈架构设计

⚠️ 二次审计标注（灵通, 2026-04-14）：

本文档引用的所有 6 个 .py 文件路径经逐一验证，100% 不存在：

引用路径	目标项目	存在？
lingresearch/model/retrieval.py	LingResearch	❌ 项目目录不存在 (/home/ai/LingResearch not found)
lingresearch/model/intent.py	LingResearch	❌ 同上
lingresearch/model/reasoning.py	LingResearch	❌ 同上
lingresearch/train.py	LingResearch	❌ 同上
lingminopt/meta_optimizer.py	LingMinOpt	❌ 目录存在但文件不存在
lingflow/knowledge_graph.py	LingFlow	❌ 文件不存在

结论：本文档是设计蓝图，不是实现文档。所有代码示例中的 from lingresearch.* 和 from lingflow.knowledge_graph 导入都无法执行。

灵克代码本身是真的（14K 行、46 个 class、673 个测试），但这份架构文档从已知事实过度外推。

建议：将本文档重命名为 LINGAI_STACK_BLUEPRINT.md，明确标注为未实现的设计。

项目代号: LingAI-Stack 版本: v1.0.0 日期: 2026-04-12 协调方: 灵克 (LingClaude) 协作方: 灵通 (LingFlow) + 灵研 (LingResearch) + 灵极优 (LingMinOpt)

---

一、总览

1.1 能力栈分层

┌─────────────────────────────────────────────────────────┐
│                   用户交互层                            │
│                    User Layer                          │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                 理解层 (Understanding)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐│
│  │ 语义检索     │→ │ 意图识别     │→ │ 认知推理     ││
│  │ Semantic     │  │ Intent       │  │ Cognitive    ││
│  │ Retrieval    │  │ Recognition  │  │ Reasoning    ││
│  └──────────────┘  └──────────────┘  └──────────────┘│
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                 优化层 (Optimization)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐│
│  │ 元知识优化   │←→│ 知识图谱增强 │←→│ 知识蒸馏     ││
│  │ Meta         │  │ Knowledge    │  │ Knowledge    ││
│  │ Knowledge    │  │ Graph       │  │ Distillation ││
│  │ Optimizer   │  │ Enhancement  │  │              ││
│  └──────────────┘  └──────────────┘  └──────────────┘│
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                   执行层 (Execution)                   │
│    灵通 Workflow + 灵通 Agent + 灵通 Skill            │
└─────────────────────────────────────────────────────────┘

1.2 模型矩阵

模型	负责方	当前状态	优先级	依赖
语义检索 (Semantic Retrieval)	灵研	✅ 已开跑	P0	无
意图识别 (Intent Recognition)	灵研	✅ 已开跑	P0	无
认知推理 (Cognitive Reasoning)	灵研	✅ 已开跑	P0	意图识别
元知识优化 (Meta Knowledge Optimizer)	灵极优	🔄 设计中	P1	理解层三模型
知识图谱增强 (Knowledge Graph Enhancement)	灵通	🔄 设计中	P2	语义检索
知识蒸馏 (Knowledge Distillation)	灵研	🔄 设计中	P1	全部模型

---

二、理解层模型 (Understanding Layer)

2.1 语义检索 (Semantic Retrieval)

职责：代码/知识库快速定位，支持模糊匹配和语义相似度

输入： - 查询文本（自然语言/代码片段） - 上下文信息（项目结构、当前文件、光标位置）

输出： - 相关代码片段列表（按相似度排序） - 知识库条目列表 - 文件路径 + 行号

接口设计：

# 接口: lingresearch/model/retrieval.py
from lingresearch.model.retrieval import SemanticRetriever

class RetrievalRequest:
    query: str
    context: dict[str, Any]  # project_path, current_file, cursor_pos
    max_results: int = 10
    min_similarity: float = 0.3

class RetrievalResult:
    code_snippets: list[CodeSnippet]
    knowledge_items: list[KnowledgeItem]
    metadata: dict[str, Any]

class CodeSnippet:
    file_path: str
    start_line: int
    end_line: int
    content: str
    similarity: float
    context_before: str | None
    context_after: str | None

# 使用示例
retriever = SemanticRetriever()
result = retriever.retrieve(
    query="如何实现用户认证",
    context={"project_path": "/path/to/project"},
    max_results=5
)

与灵通集成： - 替代/增强 ProjectIndex 的代码搜索能力 - 为 skill-creator 技能提供参考代码 - 为 code-review 技能提供相关代码上下文

评估指标： - 召回率 (Recall) @ K = 5, 10 - 精确率 (Precision) @ K = 5, 10 - MRR (Mean Reciprocal Rank) - 查询响应时间 < 100ms

---

2.2 意图识别 (Intent Recognition)

职责：判断任务类型，精准路由到合适的 agent/skill

输入： - 用户查询文本 - 历史对话上下文（可选） - 项目状态信息（可选）

输出： - 意图类别（8大类） - 置信度分数 - 推荐的 Agent 类型 - 推荐的 Skill 名称

意图类别：

class IntentType(str, Enum):
    CODE_GENERATION = "code_generation"      # 代码生成
    CODE_REFACTORING = "code_refactoring"     # 代码重构
    BUG_FIXING = "bug_fixing"                 # Bug 修复
    CODE_REVIEW = "code_review"               # 代码审查
    ARCHITECTURE_DESIGN = "architecture_design" # 架构设计
    TESTING = "testing"                       # 测试相关
    DOCUMENTATION = "documentation"           # 文档生成
    GENERAL_CHAT = "general_chat"             # 一般对话

接口设计：

# 接口: lingresearch/model/intent.py
from lingresearch.model.intent import IntentRecognizer

class IntentRequest:
    query: str
    conversation_history: list[dict] | None
    project_context: dict | None

class IntentResult:
    intent: IntentType
    confidence: float  # 0.0-1.0
    recommended_agent: str  # implementation, reviewer, tester, etc.
    recommended_skill: str | None  # brainstorming, code-review, etc.
    reasoning: str  # 可解释性

# 使用示例
recognizer = IntentRecognizer()
result = recognizer.recognize(
    query="帮我写一个用户登录的API",
    conversation_history=None
)

print(f"意图: {result.intent}, 代理: {result.recommended_agent}")
# 输出: 意图: CODE_GENERATION, 代理: implementation

与灵通集成： - 强化 BehaviorAwareRouter 的意图识别能力 - 为 AgentCoordinator 提供 agent 选择建议 - 为 WorkflowOrchestrator 提供 skill 路由

评估指标： - 准确率 (Accuracy) - 置信度校准 (Brier Score) - F1-score (每个意图类别) - 响应时间 < 50ms

---

2.3 认知推理 (Cognitive Reasoning)

职责：多步推理、隐含需求推导、上下文理解

输入： - 用户查询 - 检索到的代码/知识（来自语义检索） - 意图识别结果（来自意图识别） - 项目状态信息

输出： - 推理步骤列表（可解释） - 隐含需求列表 - 推荐行动方案（优先级排序） - 依赖关系图

推理类型：

class ReasoningType(str, Enum):
    CAUSAL_ANALYSIS = "causal_analysis"       # 因果分析
    DEPENDENCY_INFERENCE = "dependency_inference"  # 依赖推导
    CONTEXTUAL_UNDERSTANDING = "contextual_understanding"  # 上下文理解
    MULTI_STEP_PLANNING = "multi_step_planning"  # 多步规划

接口设计：

# 接口: lingresearch/model/reasoning.py
from lingresearch.model.reasoning import CognitiveReasoner

class ReasoningRequest:
    query: str
    retrieval_result: RetrievalResult | None  # 来自语义检索
    intent_result: IntentResult | None  # 来自意图识别
    project_context: dict

class ReasoningStep:
    step_id: int
    reasoning_type: ReasoningType
    description: str
    input_data: dict
    output_data: dict
    confidence: float

class ReasoningResult:
    steps: list[ReasoningStep]
    implicit_requirements: list[str]
    action_plans: list[ActionPlan]
    dependency_graph: dict[str, list[str]]

class ActionPlan:
    plan_id: str
    description: str
    priority: int  # 1-10
    estimated_effort: str  # small/medium/large
    dependencies: list[str]

# 使用示例
reasoner = CognitiveReasoner()
result = reasoner.reason(
    query="实现用户登录功能",
    retrieval_result=retrieval_out,
    intent_result=intent_out,
    project_context={"framework": "FastAPI"}
)

print(f"隐含需求: {result.implicit_requirements}")
# 输出: 隐含需求: ['密码加密存储', 'JWT token 生成', 'Session 管理', '错误处理']

与灵通集成： - 为 brainstorming 技能提供需求分析 - 为 systematic-debugging 技能提供根因分析 - 为 writing-plans 技能提供多步规划

评估指标： - 推理完整性（覆盖率） - 推理准确性（人工评估） - 隐含需求召回率 - 响应时间 < 500ms

---

三、优化层模型 (Optimization Layer)

3.1 元知识优化 (Meta Knowledge Optimizer)

职责：动态优化提示词、路由策略、重试策略，提升系统性能

输入： - 历史会话记录（session_history.json） - 优化触发信息（来自 LingClaude 的 OptimizationTrigger） - 当前系统状态（性能指标、错误率）

输出： - 优化的系统提示词模板 - 优化的 agent 路由规则 - 优化的重试策略参数 - 优化建议报告

优化目标：

class OptimizationGoal(str, Enum):
    REDUCE_TOKEN_USAGE = "reduce_token_usage"      # 减少 token 使用
    IMPROVE_ACCURACY = "improve_accuracy"          # 提升准确率
    REDUCE_LATENCY = "reduce_latency"              # 降低延迟
    IMPROVE_SUCCESS_RATE = "improve_success_rate"   # 提升成功率

接口设计：

# 接口: lingminopt/meta_optimizer.py
from lingminopt import MinimalOptimizer, SearchSpace, ExperimentConfig
from lingminopt.meta_optimizer import MetaKnowledgeOptimizer

class OptimizationRequest:
    goal: OptimizationGoal
    session_history_path: str
    current_system_prompt: str
    current_routing_config: dict
    current_retry_config: dict

class OptimizationResult:
    optimized_system_prompt: str
    optimized_routing_rules: dict
    optimized_retry_config: dict
    expected_improvement: dict[str, float]
    confidence: float
    recommendation_report: str

# 使用示例 - 灵极优驱动
optimizer = MetaKnowledgeOptimizer()

# 定义搜索空间
search_space = SearchSpace()
search_space.add_continuous("temperature", 0.0, 1.0)
search_space.add_discrete("model", ["gpt-4o", "gpt-4o-mini", "claude-3.5-sonnet"])
search_space.add_integer("max_tokens", 1024, 8192, step=512)

# 定义评估函数（由 LingClaude 提供）
def evaluate_meta_params(params):
    # 调用 LingClaude API 测试参数效果
    result = test_configuration(params, sample_queries)
    return result["score"]  # 综合 token、准确率、延迟的分数

# 运行优化
config = ExperimentConfig(
    max_experiments=50,
    time_budget=600,  # 10分钟
    direction="maximize"
)

optimizer = MinimalOptimizer(
    evaluate=evaluate_meta_params,
    search_space=search_space,
    config=config,
    search_strategy="bayesian"
)

result = optimizer.run()

与灵克集成： - 替代/增强 LingClaude 的 SelfOptimizer 系统 - 为 QueryEngine 提供动态配置 - 为 GlmRetryPolicy 提供参数优化

与灵研集成： - 使用 lingresearch/train.py 训练元知识模型 - 使用 prepare.py 准备历史会话数据

评估指标： - Token 节省率（%） - 准确率提升（%） - 延迟降低（%） - 成功率提升（%）

---

3.2 知识图谱增强 (Knowledge Graph Enhancement)

职责：AST 分析、依赖关系追踪、重构建议、风险检测

输入： - 项目源代码（Python/JavaScript/TypeScript） - 代码变更历史（git diff） - 当前查询上下文

输出： - 项目依赖图（模块级、函数级） - 代码影响范围分析 - 重构建议（安全/风险/收益） - 技术债识别

图谱结构：

class GraphNodeType(str, Enum):
    MODULE = "module"           # 模块节点
    CLASS = "class"             # 类节点
    FUNCTION = "function"       # 函数节点
    VARIABLE = "variable"       # 变量节点
    DEPENDENCY = "dependency"   # 依赖关系
    CALL = "call"              # 调用关系
    INHERIT = "inherit"         # 继承关系

class KnowledgeGraph:
    nodes: dict[str, GraphNode]
    edges: dict[str, GraphEdge]
    metadata: dict[str, Any]

class GraphNode:
    id: str
    type: GraphNodeType
    file_path: str
    line_number: int
    properties: dict[str, Any]

class GraphEdge:
    source_id: str
    target_id: str
    type: GraphNodeType
    weight: float  # 依赖强度
    metadata: dict[str, Any]

接口设计：

# 接口: lingflow/knowledge_graph.py
from lingflow.knowledge_graph import KnowledgeGraphBuilder

class GraphBuildRequest:
    project_path: str
    include_tests: bool = False
    granularity: str = "function"  # module/class/function

class RefactoringSuggestion:
    target_node_id: str
    suggestion_type: str  # extract_method, inline_var, rename, etc.
    reason: str
    risk_level: str  # low/medium/high
    expected_benefit: str

class GraphAnalysisResult:
    knowledge_graph: KnowledgeGraph
    refactoring_suggestions: list[RefactoringSuggestion]
    technical_debt_items: list[dict]
    impact_analysis: dict[str, list[str]]

# 使用示例
builder = KnowledgeGraphBuilder()
result = builder.build_and_analyze(
    project_path="/home/ai/LingClaude",
    granularity="function"
)

# 查询影响范围
affected_nodes = result.knowledge_graph.find_affected_nodes(
    node_id="lingclaude.core.query_engine.QueryEngine.submit",
    max_depth=3
)

# 重构建议
for suggestion in result.refactoring_suggestions:
    print(f"{suggestion.target_node_id}: {suggestion.suggestion_type}")

与灵通集成： - 为 code-review 技能提供影响分析 - 为 code-refactor 技能提供重构建议 - 为 verification-before-completion 技能提供风险检测

与灵克集成： - 为 agent_loop 提供函数调用追踪 - 增强代码编辑工具的安全检查

评估指标： - 图构建覆盖率（节点/边） - 影响分析准确率（%） - 重构建议采纳率（%） - 风险检测召回率（%）

---

3.3 知识蒸馏 (Knowledge Distillation)

职责：用大模型的决策数据训练小模型，减少 API 成本

输入： - 教师模型（GPT-4o/Claude-3.5）的决策数据 - 学生模型（Qwen-2.5B/GLM-4B）的初始权重 - 蒸馏策略（logits / features / response）

输出： - 蒸馏后的学生模型 - 模型性能对比报告 - 推荐的部署策略

蒸馏策略：

class DistillationStrategy(str, Enum):
    LOGITS = "logits"              # 逻辑蒸馏
    FEATURES = "features"          # 特征蒸馏
    RESPONSE = "response"          # 响应蒸馏
    HYBRID = "hybrid"              # 混合蒸馏

接口设计：

# 接口: lingresearch/train.py (修改以支持蒸馏)
from lingresearch.distillation import KnowledgeDistiller

class DistillationConfig:
    teacher_model: str  # gpt-4o, claude-3.5-sonnet
    student_model: str  # qwen-2.5b, glm-4b
    strategy: DistillationStrategy
    temperature: float = 2.0  # 软标签温度
    alpha: float = 0.5  # 蒸馏损失权重
    batch_size: int = 8
    max_epochs: int = 3

class DistillationResult:
    student_model_path: str
    teacher_performance: dict
    student_performance: dict
    cost_savings: dict  # token 节省、时间节省
    recommendation: str

# 使用示例
distiller = KnowledgeDistiller(config=distillation_config)

# 第一步：生成教师数据
teacher_data = distiller.generate_teacher_data(
    prompts=sample_prompts,
    teacher_model="gpt-4o"
)

# 第二步：蒸馏训练
result = distiller.distill(
    teacher_data=teacher_data,
    student_init="qwen-2.5b"
)

# 第三步：评估
teacher_perf = distiller.evaluate(result.student_model_path, test_prompts)
print(f"Token 节省: {result.cost_savings['token_savings']}%")
print(f"准确率: {result.student_performance['accuracy']}")

与灵研集成： - 使用 lingresearch/train.py 执行蒸馏训练 - 使用 prepare.py 准备教师数据 - 使用 evaluate_bpb 评估学生模型

与灵克集成： - 蒸馏后的模型集成到 LingClaude 的 OpenAIProvider - 为低优先级任务使用学生模型 - 为高优先级任务保留教师模型

与灵通集成： - 为 AgentCoordinator 提供低成本 agent 配置 - 为 L1/L2 skills 使用学生模型 - 为 L3 skills 保留教师模型

评估指标： - 学生模型准确率 vs 教师模型 - Token 节省率（%） - API 成本降低（%） - 响应时间降低（%）

---

四、协同协议

4.1 数据流协议

[用户查询]
    ↓
[意图识别] → 语义检索 → 认知推理
    ↓
[元知识优化] ← [历史会话记录]
    ↓
[知识图谱增强] ← [当前代码状态]
    ↓
[知识蒸馏] ← [教师模型决策数据]
    ↓
[灵通 Agent 执行]
    ↓
[结果返回]
    ↓
[更新知识图谱]
    ↓
[记录会话历史]

4.2 接口规范

所有模型遵循统一的接口规范：

from dataclasses import dataclass
from typing import Generic, TypeVar

T = TypeVar('T')

@dataclass
class ModelInput:
    """统一模型输入接口"""
    query: str
    context: dict[str, Any]
    metadata: dict[str, Any] | None = None

@dataclass
class ModelOutput(Generic[T]):
    """统一模型输出接口"""
    data: T
    confidence: float
    reasoning: str | None = None
    metadata: dict[str, Any] | None = None
    execution_time_ms: float = 0.0

class BaseModel:
    """统一模型基类"""
    def __init__(self, config: dict):
        self.config = config

    def predict(self, input: ModelInput) -> ModelOutput:
        raise NotImplementedError

    def evaluate(self, test_data: list) -> dict:
        raise NotImplementedError

4.3 错误处理协议

class ModelError(Exception):
    """统一模型错误基类"""
    code: str
    message: str
    details: dict | None

class IntentRecognitionError(ModelError):
    """意图识别错误"""
    pass

class RetrievalError(ModelError):
    """检索错误"""
    pass

class ReasoningError(ModelError):
    """推理错误"""
    pass

class OptimizationError(ModelError):
    """优化错误"""
    pass

class GraphBuildError(ModelError):
    """图谱构建错误"""
    pass

class DistillationError(ModelError):
    """蒸馏错误"""
    pass

4.4 性能监控协议

所有模型必须提供性能指标：

@dataclass
class ModelMetrics:
    """统一性能指标"""
    inference_latency_p50_ms: float
    inference_latency_p95_ms: float
    inference_latency_p99_ms: float
    throughput_qps: float
    error_rate: float
    memory_usage_mb: float
    gpu_utilization: float | None

class BaseModel:
    def get_metrics(self) -> ModelMetrics:
        """获取模型性能指标"""
        pass

---

五、实施计划

Phase 1: 理解层强化 (Week 1-2)

任务： 1. 语义检索模型优化 - 接入 LingClaude 的 ProjectIndex 数据 - 实现实时代码索引更新 - 评估指标：Recall@5 > 0.8

1. 意图识别模型优化
2. 接入 LingClaude 的 BehaviorMetrics
3. 集成到 BehaviorAwareRouter

4. 评估指标：Accuracy > 0.85

5. 认知推理模型优化

6. 接入语义检索和意图识别结果
7. 实现多步推理引擎
8. 评估指标：推理完整性 > 0.75

负责人：灵研 (lingresearch)

里程碑：理解层三模型集成测试通过

Phase 2: 优化层基础 (Week 3-4)

任务： 1. 元知识优化模型开发 - 使用 LingMinOpt 实现优化引擎 - 接入 LingClaude 的 OptimizationTrigger - 评估指标：Token 节省 > 10%

1. 知识图谱增强模型开发
2. 基于 LingFlow 的 AST 分析器
3. 实现依赖关系追踪

4. 评估指标：影响分析准确率 > 0.7

5. 知识蒸馏模型开发

6. 使用灵研的 train.py 框架
7. 准备教师数据集
8. 评估指标：学生模型准确率 > 0.9 × 教师

负责人：灵极优 (LingMinOpt) + 灵通 (LingFlow) + 灵研 (lingresearch)

里程碑：优化层三模型集成测试通过

Phase 3: 协同集成 (Week 5-6)

任务： 1. 数据流管道搭建 - 实现模型间数据传递 - 错误处理和重试机制 - 性能监控和日志

1. 协同策略优化
2. 模型调度策略
3. 资源分配优化

4. 性能调优

5. 端到端测试

6. 完整流程测试
7. 性能基准测试
8. 压力测试

负责人：灵克 (LingClaude) 协调

里程碑：六模型协同系统上线

---

六、风险评估

风险	可能性	影响	缓解措施
模型性能不达标	中	高	增加训练数据、调整模型架构
集成复杂度高	高	中	接口规范化、分阶段集成
资源消耗过大	中	中	使用小模型、优化推理效率
数据依赖冲突	低	高	数据版本管理、冲突检测
维护成本高	中	中	文档完善、自动化测试

---

七、成功指标

7.1 理解层指标

• 语义检索 Recall@5 > 0.8
• 意图识别 Accuracy > 0.85
• 认知推理完整性 > 0.75

7.2 优化层指标

• Token 节省率 > 15%
• API 成本降低 > 20%
• 响应时间降低 > 30%

7.3 系统指标

• 端到端准确率 > 0.8
• 系统可用性 > 99%
• 平均响应时间 < 2s

---

八、后续优化方向

1. 模型压缩：量化、剪枝、蒸馏
2. 联邦学习：多节点协同训练
3. 在线学习：实时模型更新
4. 多模态：支持图像、视频输入
5. 迁移学习：跨项目知识迁移

---

文档版本: v1.0.0 最后更新: 2026-04-12 下次审查: 2026-04-19