XNCF 模块文档地图

本覆盖审计于 2026-08-14 基于 NcfPackageSources 开发分支完成。 它描述的是文档覆盖度，不代表模块是否受支持或是否适合生产使用。

针对 NcfPackageSources_Include_NcfSimulatedSite.sln 的完整项目审计维护在 解决方案项目地图。该解决方案中的每个运行时 项目都已经在那里提供面向小白的介绍；本页继续追踪需要独立深入源码剖析的模块。

NCF 面对两类合理但不同的读者，一种文档无法同时服务好两者：

读者首先需要什么文档类型
Template/应用使用者如何安装、配置、授权、操作和验证模块使用说明
NcfPackageSources 贡献者Register/生命周期、AppService 链路、持久化、关键方法和扩展约束模块源码剖析

NuGet/Template 项目的使用者不应为了操作功能而定位实现文件；反过来，源码贡献者也不能只靠 Admin 菜单导览。因此新模块文档应先提供使用说明，并在需要源码深度时链接独立的源码剖析页。

当前已有的详细覆盖

模块/能力使用说明源码剖析说明
Senparc.Xncf.XncfBuilder有有创建/修改/预览/评审/合入边界。
Senparc.Xncf.Sandbox环境准备已在 XncfBuilder/Sandbox 集成剖析中说明Docker 准备与固定 NCF 预览工作负载。
Senparc.Xncf.AIKernel本地微调使用说明已覆盖 worker 契约与生命周期；通用模型/向量内部机制仍待补充SFT/LoRA/QLoRA、离线模型、数据集、部署、评估与运维边界。
Senparc.Xncf.NeuCharWorkflow操作说明已结合节点级机制说明触发器、节点、受限表达式和回放。
Senparc.Xncf.AgentsManagerHIL 与 Workflow 集成、3D 状态视图已覆盖集成与运行态视图Agent / Group / A2A 的 HIL 请求、3D 状态、技能标记和空间布局边界。
Senparc.Xncf.MCP独立文档通用 Register 剖析为部分覆盖已有安装、使用、API、FAQ；仍需要模块内部专页。
Senparc.Web / Senparc.Areas.Admin宿主与 Admin 说明已说明宿主组合与 Admin 边界运行、安装、登录、启用模块和源码归属。
XNCF 框架/自定义模块Template 开发能力导览属于框架级而非单个官方模块。

项目地图现在已经覆盖目标解决方案中的全部运行时项目。下面的清单收窄为仍需要独立深度页面的模块，不再把项目地图中已经说明的内容重复标记为缺失。

完整模块清单与文档补齐计划

P0：模块治理与平台基线

这些模块决定所有已安装模块的生命周期、菜单、授权或租户前提，应最先补齐。

模块缺少的必要内容
Senparc.Xncf.XncfModuleManager使用：发现/安装/开关/Function 排障；源码：模块状态迁移、Register 扫描、AI 友好安装动作。
Senparc.Xncf.SystemCore使用：基础数据与安装顺序；源码：DbContext/Factory 注册和系统实体生命周期。
Senparc.Xncf.SystemManager使用：系统配置和运维依赖；源码：配置读写边界与后台服务。
Senparc.Xncf.SystemPermission使用：角色/权限管理；源码：策略映射、鉴权检查与 Admin 范围。
Senparc.Xncf.Menu使用：菜单管理；源码：菜单注册与本地化链路。
Senparc.Xncf.Tenant使用：租户启用/隔离；源码：租户解析与 IIgnoreMulitTenant 例外。
Senparc.Xncf.AreasBase源码：Area 基线约定以及与 Senparc.Ncf.AreaBase 的关系。

P1：AI、Prompt、Agent 与知识链路

这些模块应在运维层串成一条端到端链路，同时保留各自的数据和执行模型的独立源码页。

模块缺少的必要内容
Senparc.Xncf.AIKernel本地微调已覆盖。仍缺：通用模型/向量提供方配置、凭据归属、推理模型选择与源码服务选择机制。
Senparc.Xncf.PromptRangePrompt 资产/PromptCode 生命周期、版本/Range 选择；AppService/事件/存储模型。
Senparc.Xncf.AgentsManagerAgent 模板、ChatGroup、任务和 A2A 的使用；任务运行器、成员解析、流式/异常边界。
Senparc.Xncf.KnowledgeBase导入/向量化/召回操作和数据保留预期；资源策略、分块/向量生命周期。
Senparc.Xncf.MCP端点映射、Function 暴露、鉴权/限流/审计边界的源码专页。
Senparc.Xncf.AIAgentsHub在推广使用前说明当前成熟度、支持的集成和明确不支持的场景。

P1：开发、运维与高风险能力

这些模块应先具备包含权限、回滚和生产限制的使用说明，再补充源码剖析。

模块缺少的必要内容
Senparc.Xncf.DatabaseToolkit备份/更新/查询权限、多数据库范围、事务/回滚限制、AI 查询边界。
Senparc.Xncf.FileManager上传/存储/资源用途策略、公开资源与知识库资源的边界、路径遍历防护。
Senparc.Xncf.DesktopBridge配对、桥接 Token 轮换、SSE 生命周期、桌面兼容性和网络边界。
Senparc.Xncf.FirmwareUpdateFeed/镜像配置、限流/退避、手动与后台同步、失败隔离。
Senparc.Xncf.Terminal严格的运维专用使用方式、命令白名单/审计/宿主权限模型；命令执行源码链路。
Senparc.Xncf.Swagger启用方式、路由暴露和生产鉴权策略。
Senparc.Xncf.DynamicData当前成熟度和受支持的动态数据边界。

P2：集成、通信与工具类模块

这些模块先补齐面向任务的简明使用说明，待契约稳定后再添加源码剖析。

模块缺少的必要内容
Senparc.Xncf.WeixinManager账号/App 配置、凭据保护、消息/API 生命周期、可选 MCP 暴露。
Senparc.Xncf.Dapr启用、组件前置条件、本地/集群差异、重试/可观测性边界。
Senparc.Xncf.Application外部程序注册、宿主权限、超时/日志与回滚。
Senparc.Xncf.SenMapic爬取目标策略、限流、法律/运维约束和示例状态。

每个模块推荐的页面形态

1. 使用说明：无需源码即可完成工作

  1. 目的、成熟度、依赖与非目标；
  2. 安装/启用/配置/授权步骤；
  3. 一个正常工作流和一个失败/回滚工作流；
  4. 安全与生产检查表：密钥、权限、网络、资源限制、审计、数据保留；
  5. 排障顺序和相关模块链接。

2. 源码剖析：支持贡献者

  1. 项目/分层地图：Register、Register.Area、Register.Database、Domain、Application、OHS、Areas、资源和测试；
  2. Register 元数据、生命周期钩子、DbContext/Migration 归属和模块依赖；
  3. 关键 AppService 入口、领域服务、后台任务/事件和请求/数据流；
  4. 关键方法的输入校验、鉴权、并发、失败处理和扩展约束；
  5. 测试切面与保护公共契约的变更检查表。

维护规则

模块出现以下变化时，应同时更新两类页面，或至少在本地图中显式登记缺口：

  • Register 版本/顺序、安装状态或模块依赖；
  • 公共 FunctionRender/MCP 面或 AI 调用资格；
  • 鉴权/策略、密钥处理、网络或数据保留行为；
  • Migration/数据库模型、后台任务或外部服务契约；
  • 用户可见流程、回滚路径或运维前置条件。

阅读路径