代码索引
本页给读者一个“当前项目真实能力面在哪里”的代码入口图。它不复制完整目录树，而是把最值得先读的模块按职责聚合出来。
先看哪几层
建议按下面顺序进入：
ai_service/api/：看平台公开了哪些控制面和业务面入口ai_service/orchestrator/：看聊天主运行时如何组织能力链路ai_service/services/：看 RAG、MCP、评测、scheduled task、审计等核心服务ai_service/fusion/：看 Fusion Runtime 的定义、治理与执行ai_service/storage/：看持久化模型、状态枚举和 ORM 真相源
进程与入口
| 路径 | 说明 |
|---|---|
main.py |
本地启动入口 |
ai_service/api/app.py |
FastAPI 应用装配、共享 schema 与少量兼容 wrapper |
ai_service/api/routers/ |
分拆后的控制面与业务面路由 |
ai_service/utils/settings.py |
系统级配置、运行时开关和默认值 |
ai_service/utils/local_dev_runtime.py |
本地多进程开发时的共享运行时 env 协调 |
路由层能力地图
| 路径 | 说明 |
|---|---|
ai_service/api/routers/core.py |
平台级聊天入口：/stream、/models、/release-metadata，以及 MCP quick-match / checkpoint 触发面 |
ai_service/conversations/interfaces/http/router.py |
Conversations 应用入口：session、turn、turn context、WebSocket、knowledge correction、session takeover |
ai_service/api/routers/agents.py |
Agent CRUD、版本管理、orchestrator 选择、模型路由、MCP runtime config、Fusion 绑定 |
ai_service/api/routers/knowledge.py |
Knowledge source、documents、ingestion、manual inspection、snapshot rebuild、retrieval test |
ai_service/api/routers/mcp.py |
MCP server registry、credential、agent mount、health check、test call、response preview |
ai_service/fusion/interfaces/http/router.py |
Fusion HTTP 入口，负责 run routes、multipart inputs、persisted I/O presenter |
ai_service/api/routers/evaluation.py |
Evaluation datasets、CSV import、run lifecycle、gate evaluate、results export |
ai_service/api/routers/scheduled_tasks.py |
Scheduled task 查询、取消、run history、derived token usage |
ai_service/api/routers/skills.py |
Skill asset、skill version、agent skill mount、skill audit |
ai_service/api/routers/admin_auth.py |
Studio 登录、session、管理员身份相关入口 |
ai_service/api/routers/admin_system_settings.py |
系统设置控制面 |
ai_service/api/routers/admin_llm_model_config.py |
模型配置控制面 |
ai_service/api/routers/admin_audit.py |
审计查询入口 |
ai_service/api/routers/admin_users.py |
Studio 用户管理 |
ai_service/api/routers/jobs.py |
ETL job / queue 入口 |
ai_service/document_recognition/interfaces/http/router.py |
Document recognition 应用入口：public run review/download routes、admin overview / runs |
Document Recognition
| 路径 | 说明 |
|---|---|
ai_service/document_recognition/domain/ |
run、field review、issue、summary 模型 |
ai_service/document_recognition/application/use_cases/ |
Fusion run projection / field review 用例 |
ai_service/document_recognition/application/projections.py |
summary / issue / field review 归一化 |
ai_service/document_recognition/infrastructure/runtime/document_recognition_job_runner.py |
后台作业执行入口 |
ai_service/document_recognition/infrastructure/persistence/document_recognition_repository.py |
单证识别 repository adapter |
聊天运行时与编排层
| 路径 | 说明 |
|---|---|
ai_service/orchestrator/registry.py |
Chat orchestrator 插件注册表，当前至少有 chameleon_chat_v1 和 langgraph_react_agent_v1 |
ai_service/orchestrator/graph.py |
默认 Chameleon 聊天编排器 |
ai_service/orchestrator/react_agent.py |
LangGraph ReAct Agent 运行时 |
ai_service/orchestrator/runtime_kernel.py |
trace、event apply、message type、统一 turn 执行包装 |
ai_service/orchestrator/capability_pipeline.py |
能力阶段组织与 capability pipeline 汇总 |
ai_service/orchestrator/state.py |
编排器共享状态对象 |
ai_service/orchestrator/checkpoint_state.py |
approval / checkpoint 相关状态模型 |
ai_service/orchestrator/model_routing.py |
agent 级模型路由规则 |
ai_service/orchestrator/mcp_runtime_config.py |
MCP runtime override 配置 |
ai_service/orchestrator/mcp_response_config.py |
MCP direct response / quick match / intent gate 规则 |
ai_service/orchestrator/mcp_passthrough.py |
MCP passthrough 决策与渲染 |
ai_service/orchestrator/response_grounding_config.py |
grounding / 引用约束配置 |
RAG 与知识链路
| 路径 | 说明 |
|---|---|
ai_service/services/ingestion.py |
摄取主流程、chunk 生成、向量写入 |
ai_service/services/chunking.py |
chunking strategy registry、能力声明与校验 |
ai_service/services/embedding.py |
embedding provider、readiness check、向量生成 |
ai_service/services/rag_retrieval.py |
检索主入口、top-k / score threshold / mounted source 过滤 |
ai_service/services/multi_query.py |
multi-query 扩展 |
ai_service/services/rerank.py |
rerank 阶段 |
ai_service/services/rag_debug.py |
operator-facing retrieval debug report |
ai_service/services/manual_inspection.py |
手动 inspect，支持 vector health 与 chunking preview |
ai_service/services/document_vector_reconciliation.py |
启动期 indexed document 向量核验与状态回写 |
ai_service/services/snapshot_rebuild.py |
从 parse snapshot 重建文档 |
ai_service/services/knowledge_correction_service.py |
对话纠错到 managed correction source 的发布链路 |
MCP、Skill 与外部能力挂载
| 路径 | 说明 |
|---|---|
ai_service/services/mcp_client.py |
stdio / http_sse transport 调用与 URL import mode |
ai_service/services/mcp_registry.py |
agent-mounted MCP 解析 |
ai_service/services/mcp_policy.py |
MCP approval / allow / deny 等策略执行 |
ai_service/services/mcp_secret_manager.py |
MCP 凭据解析与注入 |
ai_service/services/mcp_audit.py |
MCP 调用审计 |
ai_service/services/mcp_tool_capabilities.py |
MCP tool capability 抽象 |
ai_service/services/mcp_tool_runtime_strategies.py |
runtime strategy 协议层 |
ai_service/services/mcp_tool_tracking_runtime.py |
跟踪类 MCP runtime strategy |
ai_service/services/skill_registry.py |
mounted skill 解析 |
ai_service/services/skill_policy.py |
skill 风险与执行策略 |
ai_service/services/skill_executor.py |
skill 执行入口 |
ai_service/services/skill_audit.py |
skill 调用审计 |
Fusion Runtime
| 路径 | 说明 |
|---|---|
ai_service/fusion/domain/ |
Fusion contract、structured output profile、validation error、port 定义 |
ai_service/fusion/application/use_cases/ |
create/get/list/execute/recover definition-aware run lifecycle |
ai_service/fusion/application/dto.py |
definition / run DTO |
ai_service/fusion/interfaces/http/ |
Fusion HTTP router、request parser、response presenter |
ai_service/fusion/infrastructure/persistence/ |
Fusion run / definition repository adapter |
ai_service/fusion/infrastructure/adapters/ |
model / rag / mcp / image generation / storage / governance binding |
ai_service/fusion/infrastructure/runtime/graph.py |
Fusion runtime graph 组装 |
ai_service/fusion/infrastructure/runtime/nodes.py |
输入预处理、prompt assemble、capability 调用、输出持久化 |
ai_service/fusion/infrastructure/runtime/prompt_builder.py |
message list 与 multimodal prompt 构造 |
ai_service/fusion/infrastructure/runtime/output_mapper.py |
模型输出映射到 output slots |
ai_service/fusion/domain/validation.py |
run request 与 contract 校验 |
评测与离线运行
| 路径 | 说明 |
|---|---|
ai_service/services/evaluation_dataset_importer.py |
数据集导入 |
ai_service/services/evaluation_runner.py |
run supervisor、resume、lease、slice 聚合 |
ai_service/services/evaluation_judge.py |
judge prompt 与模型裁判 |
ai_service/services/evaluation_gate.py |
gate 计算 |
ai_service/services/evaluation_metrics.py |
exact match、token f1 等指标 |
ai_service/services/e2e_visual_review.py |
视觉评审相关辅助 |
会话扩展与后台调度
| 路径 | 说明 |
|---|---|
ai_service/services/session_runtime.py |
会话 turn 执行封装 |
ai_service/services/runtime_checkpoint_service.py |
runtime checkpoint 持久化与恢复 |
ai_service/services/scheduled_tasks.py |
scheduled task 校验、next-run 解析、持久化与调度 |
ai_service/services/timer_scheduler.py |
定时调度驱动 |
ai_service/services/agent_memory_service.py |
agent memory 持久化与读取 |
ai_service/services/token_usage.py |
token usage 汇总 |
存储真相源
| 路径 | 说明 |
|---|---|
ai_service/storage/model_domains/agents.py |
agent、version、usage rollup |
ai_service/storage/model_domains/knowledge.py |
knowledge source、agent mount |
ai_service/storage/model_domains/documents.py |
document、chunk、ingestion、manual inspection、snapshot |
ai_service/storage/model_domains/mcp.py |
MCP server、credential、agent mount |
ai_service/storage/model_domains/evaluations.py |
dataset、run、result |
ai_service/storage/model_domains/fusion.py |
Fusion definition、version、run、persisted inputs/outputs |
ai_service/storage/model_domains/skills.py |
skill、skill version、agent link |
ai_service/storage/model_domains/sessions.py |
session、turn、checkpoint、memory |
ai_service/storage/model_domains/enums.py |
状态枚举真相源 |
前端与验证入口
| 路径 | 说明 |
|---|---|
admin-frontend/ |
Studio Admin 控制面 |
admin-frontend/shared/api/ |
前端共享 API types 与 client 层 |
demo-frontend/ |
演示前端 |
demo-backend/ |
demo 实时通道与转发层 |
tests/e2e/ |
独立 TypeScript Playwright 包 |