# AgentCMSPro

**Repository Path**: xueshu_space/agent-cms-pro

## Basic Information

- **Project Name**: AgentCMSPro
- **Description**: AgentCMS 既是一个能调用工具的智能体，也是一个网站后台。你可以手动管理文章、产品、栏目、图片和网站模板，也可以在“AI 管理”中用自然语言让智能体帮你完成这些工作。网站、后台、API 和模板编辑器都由 `Web` 一个程序提供。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-05
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentCMS（糖糕AgentCMS）

2.3.5：后台统一使用 MainLayout，嵌入的静态管理页面仅渲染右侧内容。侧栏样式集中到公共菜单样式，统一宽度、字体、行高、间距和手机折叠断点。

2.3.1：master/free 热插件共用公开业务契约，同一插件 ZIP 可在两版使用，不限制宿主版本；后台身份、菜单权限、功能开关及写保护统一由宿主处理。

AgentCMS 既是一个能调用工具的智能体，也是一个网站后台。你可以手动管理文章、产品、栏目、图片和网站模板，也可以在“AI 管理”中用自然语言让智能体帮你完成这些工作。网站、后台、API 和模板编辑器都由 `Web` 一个程序提供。

## 版本信息

`Web/appsettings.json` 的 `Product.Edition` 标注发行版：`Professional` 表示专业版，`Community` 表示社区版；具体发行版以该配置为准。此字段用于标识发行版，不代替商业授权校验。

`Product.Version` 为产品版本号，与 `Directory.Build.props` 的 `VersionPrefix`、`Version`、`InformationalVersion` 保持一致。版本格式为 `主版本.次版本.修订号`：较大功能或架构更新递增次版本，修订号归零；小功能、修复、样式或文档更新递增修订号；不兼容升级递增主版本，其余归零。当前版本为 `2.3.6`，后续每个更新任务递增一次，不按提交次数自动计算，规则见[版本说明](docs/版本说明.md)。

## 项目特点

- **网站与智能体合一**：只有一个系统 Agent，能读取和编辑网站内容、管理媒体与模板，并记录任务过程。
- **模型服务已适配**：后台“站点设置 → 兼容配置”提供国家超算中心和硅基流动的接口模板。填入所选平台的 API Key，选择模型并保存后即可使用 AI 对话。模型由服务商提供，实际可用范围以账号权限和服务商当前列表为准。
- **内置工具与技能**：工具负责实际操作，例如查询文章、保存内容、上传媒体、生成图片和备份数据库；技能是 `skills/` 中的任务说明，指导智能体按步骤使用工具。新安装默认启用内置工具和技能，视频生成工具默认关闭；可在后台“Agent 设置”调整。
- **本地 MCP**：网站本身提供 MCP 服务。将后台生成的接入链接填入支持 Streamable HTTP 的 AI 软件，就能从这些软件查询和编辑网站内容。也可以在 Agent 设置中连接其他 MCP 服务，让站内智能体使用外部工具。
- **安装简单**：首次访问会进入 `/install`，填写空 MySQL 数据库及管理员账号密码，由安装向导初始化数据库。

### 已适配的模型示例

| 服务商 | 对话模型候选示例 |
| --- | --- |
| <a href="https://www.scnet.cn/"><img src="https://www.scnet.cn/home/front/static/images/logo_phone.png" alt="国家超算互联网官网" height="26" /></a> | `DeepSeek-V4.1-Flash`、`DeepSeek-V4-Pro-0813`、`Spark-X2.5`、`Qwen3.8-Flash`、`Qwen3.8-Max`、`Kimi-K3`、`Kimi-K2.7-Code`、`MiniMax-M3` |
| <a href="https://cloud.siliconflow.cn/i/OLHviMiS"><img src="https://siliconflow.cn/logo-new.svg" alt="硅基流动官网" height="26" /></a> | `deepseek-ai/DeepSeek-V4-Flash`、`deepseek-ai/DeepSeek-V4-Pro`、`tencent/Hy4-preview` |

图像生成模板也包含硅基流动的 `Tongyi-MAI/Z-Image-Turbo`、`Qwen/Qwen-Image-Edit`、`Kwai-Kolors/Kolors`；视频模板包含国家超算中心的 `HappyHorse-1.0-T2V`、`Seedance2.0`。图像和视频功能需要各自的服务配置。候选名称来自项目当前模板，服务商调整模型时可在后台修改。

## 快速开始

发行版是一份 Windows、Linux 共用的开发项目，不生成 ZIP。根目录有 `agentOne.sln`，`core/` 存放配套的预编译 DLL；第三方依赖通过 `PackageReference` 在编译时由 NuGet 自动还原。Web 宿主、网站和会员前端、后台客户端、Orchestrator、知识库后端与界面、MiniProgram、公开契约及五个 Components 类库可编辑编译，`Plugin.Hot/` 是插件 SDK 工作区。开发者发布时选择平台。详见[发行与 SDK 说明](docs/发行与SDK说明.md)和[内容模型管理](docs/内容模型管理.md)。

### 1. 准备环境

安装 [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)。SDK 用于编译网站，模板编辑器已附带构建后的静态资源。打开终端运行 `dotnet --version`，确认命令可用。首次编译需要联网下载依赖。

开源导出包已在 `core/` 放好配套的 AI 运行库 DLL；其他依赖由项目引用在编译时还原，不需要手动往该目录复制文件。默认安装使用 SQLite，无需提前准备 MySQL、手动导入 SQL 或编辑数据库配置。

### 2. 编译并启动

在项目根目录打开 PowerShell，首次运行：

```powershell
.\start.ps1 -Build
```

以后只需启动时运行：

```powershell
.\start.ps1
```

Linux 或 macOS 首次运行 `dotnet build Web/Web.csproj`，再使用 `bash ./start.sh --no-build --no-restore` 启动。终端保持打开，按 `Ctrl+C` 停止网站。

### 3. 在浏览器完成安装

打开 [http://localhost:37710/](http://localhost:37710/)，未安装时会自动跳转到 `/install`。安装前必须阅读并同意[软件安装与合法使用协议](docs/软件安装与合法使用协议.md)（版本 `2026-10-11.7`），特别注意安装页加粗加黑的授权、合法使用与停止授权条款，然后选择数据库并填写你自己的超级管理员邮箱和密码。默认 SQLite 数据库保存在根目录 `database/TanggaoCMS.sqlite`；如果选择 MySQL，按安装页提示填写一个空数据库的连接信息。安装完成后网站会请求重启；如果没有自动恢复，重新运行启动命令。

如果手动导入 MySQL 安装数据，请先创建并选中目标空数据库，再导入 `database/TanggaoCMS.sql`（例如 `mysql -u 用户名 -p 数据库名 < database/TanggaoCMS.sql`）。脚本不会创建数据库或切换数据库；网站连接配置中的数据库名必须与导入目标一致。完整安装 SQL 仅用于空库，已有网站升级请使用对应的增量 SQL。

| 页面 | 默认地址 |
| --- | --- |
| 网站首页 | http://localhost:37710/ |
| 管理后台 | http://localhost:37710/admin/ |
| 安装页面 | http://localhost:37710/install |

后台路径可以在“站点设置 → 后台设置”修改，重启后生效；修改后以新路径访问后台。安装完成后，在“站点设置 → 兼容配置”中填写模型服务的 API Key、选择模型，再打开“AI 管理”对话。本机直接通过 `localhost` 或 `127.0.0.1` 访问时无需激活授权；使用域名访问时，按“Agent 设置 → 授权”页面提示获取并填写序列号。

## 编译与调试

后台使用 Blazor WebAssembly。Debug 开发资源未裁剪，首次加载可能达到几十 MB；上线应使用 Release 发布产物（`dotnet publish Web/Web.csproj -c Release`）。宿主将 `/_framework` 和 `/_content` 交给 `MapStaticAssets`，协商预生成的 Brotli/Gzip 压缩并缓存带指纹的资源。浏览器网络面板应同时检查实际传输大小与解压后大小；HTTPS 请求支持 Brotli 时，响应应带 `Content-Encoding: br`，支持 Gzip 时可返回 `gzip`。反向代理应保留 `Accept-Encoding`、`Content-Encoding`、`Vary` 和缓存头，并将这些请求转发给宿主。

修改 C# 或 Razor 源码后，在项目根目录执行：

```powershell
dotnet build .\Web\Web.csproj
dotnet run --project .\Web\Web.csproj --no-build --no-restore
```

先编译、再运行。直接使用 `dotnet run` 启动时，安装完成或修改需要重启的设置后，要手动停止并再次运行；PowerShell 启动脚本 `start.ps1` 会处理应用请求的重启。

若 SDK 10.0.401 构建出现 Roslyn `Fatal error` / `AccessViolationException`，项目已对该 SDK 禁用编译器内部并发，并在启动构建时禁用共享编译服务器。重新运行 `.\start.ps1 -Build`：发行项目使用 `core/` 中的配套 DLL，直接构建 Web。串行编译是崩溃规避措施；若仍失败，请保留完整日志继续排查，不跳过错误使用旧 DLL。

根目录 `data/` 是运行数据目录：本地 Web 配置 `Storage:DataDirectory=../data`、`Cms:Directory=../data/cms`，其中包含 CMS 模板、媒体、插件安装状态、生成文件和授权缓存等，不能当作编译临时目录整体删除。实际位置以配置为准；`key/` 保存登录 Cookie 等使用的持久加密密钥，也需要保留。

使用 Visual Studio 调试时，将 `Web` 设为启动项目并按 **F5**；也可以在编辑器中附加到 `Web` 进程，查看断点和异常。浏览器页面问题可按 **F12** 查看控制台与网络请求，服务端问题看启动终端的输出。`Orchestrator` 是类库，不单独启动。

`Web/appsettings.json` 中的 `Debug` 默认是 `false`。改为 `true` 并重启 Web 后，错误页面会显示异常详情和堆栈，Blazor 也会返回详细错误信息，无需修改 `ASPNETCORE_ENVIRONMENT`；调试完成后改回 `false` 并重启。

第一次使用时，可按 [Debug 调试与性能日志说明](docs/Debug调试与性能日志说明.md) 操作，了解面板数字的含义、日志位置和关闭方法。

开启 `Debug` 后会启用 OpenTelemetry，管理员后台底部中间显示可展开的性能面板，每 5 秒刷新 Web 进程驻留内存、GC 堆与回收次数、请求数量、平均耗时和运行时指标，无需 Docker 或外部监控平台。面板只保留最新采样，请求与平均耗时按进程启动后累计统计，不计面板轮询；进程内存不包含数据库、LightRAG 或整机内存。关闭 `Debug` 并重启后，面板和指标接口停用，OpenTelemetry 不再注册采集与导出；普通日志和健康检查保留。仅在开启 `Debug` 且配置了 `OTEL_EXPORTER_OTLP_ENDPOINT` 时向外部平台导出遥测。

性能面板提供“记录慢操作与异常到日志”开关，立即生效，重启后恢复 `Diagnostics:SlowOperations:Enabled` 配置值（默认开启，仅在 Debug 开启时记录）。`ThresholdMilliseconds` 默认 `1000`，记录超过或等于该阈值的服务端请求和外部 HTTP 调用；不自动记录数据库 SQL 或任意业务方法。慢操作日志为 UTF-8 JSON Lines，保存在 Web 内容根目录下的 `data/logs/performance/slow-operations-yyyyMMdd.jsonl`，按 UTC 日期分文件，仅包含时间、操作类型、路由模板或 HTTP 方法、目标主机、耗时、状态码和 TraceId。

同一开关还记录开启之后的运行时首次异常通知（包含已捕获异常），不受慢操作耗时阈值限制。异常日志位于 `data/logs/performance/runtime-exceptions-yyyyMMdd.jsonl`，包含异常类型、消息、抛出位置堆栈、直接内部异常的类型和消息，以及可用时的 TraceId/SpanId；消息和堆栈限制长度，不保留异常对象。面板的累计异常使用与日志相同的过滤规则，不等于失败请求数；正常取消另列为“正常取消（已忽略）”。统计不依赖文件日志开关，历史累计次数无法补回详情；重抛可能产生多条记录，日志系统自身的异常不递归记录。不额外采集查询参数、请求头或正文。

诊断日志不将 Blazor/WebSocket 长连接的存续时间当作慢请求。异常记录跳过已中止请求或应用关闭期间的取消/连接中止、已取消的周期计时器等待，以及 Blazor 登录状态校验循环结束和渲染批次产生的正常取消。框架用于重定向的 NavigationException、登录 Cookie 解密失败和框架重新签发旧防伪 Cookie 的已处理异常也不计入诊断异常；其他取消、超时、业务解密错误及提交时的防伪校验失败仍保留。面板显示过滤后的异常数；外部 OpenTelemetry 平台的 .NET 原始异常指标仍按运行时原始计数。

旧浏览器登录 Cookie 无法通过认证时，宿主清除该 Cookie 及其分片，继续按匿名请求处理。持久密钥、Cookie 名称和共享应用名保持原设置；密钥已丢失的旧登录状态需要重新登录，登录页会由框架生成新的防伪令牌。

两类日志均默认保留 7 天（`RetentionDays`），每类每天最多 10 MiB（`MaxFileSizeMegabytes`）；有界队列满、达到文件上限或写入失败时跳过记录，面板显示跳过数量。关闭开关后停止写入，已有日志保留；过期文件在下一次写入时清理。关闭 `Debug` 后两类诊断日志均停用。

请求异常由宿主直接返回错误 HTML 或 API 的 Problem Details JSON，不再重新执行登录、权限查询或页面渲染，因此数据库不可用时也能返回错误响应。后台用户权限与导航菜单使用五分钟的进程内缓存，并合并并发加载；通过后台或 AI 修改角色、角色成员关系、权限或菜单后会自动失效。权限缓存最多保留 2048 个用户，数据库读取失败不会被缓存。直接用 SQL 修改权限或使用多个 Web 实例时，其他实例最多需要等待五分钟刷新。

## 本地 MCP 怎么用

1. 登录后台，打开“Agent 设置 → MCP 管理”。
2. 在“本地 MCP”卡片点击“复制链接”。链接有效期为 30 天，拥有链接的人可以按你的账号权限操作网站，请妥善保管。
3. 在支持 MCP 的 AI 软件中新增服务，粘贴链接；需要选择连接方式时选 **Streamable HTTP**。
4. 连接后可以试着说：“帮我查询网站的文章列表。”

本地 MCP 提供文章、产品、栏目、站点设置和媒体等 CMS 操作工具。外部 AI 软件实际能调用哪些操作，仍取决于登录账号权限。后台“Agent 设置 → MCP 管理”还可以连接其他 MCP 服务；这属于让站内智能体使用外部工具。

## 工具、技能与插件

**工具**是智能体执行动作的能力，例如查询或保存 CMS 内容、管理图片、调用图像生成和备份数据库。可在“Agent 设置 → 内置工具”查看和调整。**技能**是智能体完成一类任务的说明书，项目内置了网站内容管理、图片处理、模板编辑等技能，文件位于 `skills/<技能名>/`，可在后台“技能管理”查看和启停。

知识库、代码编辑器和小程序相关能力位于 `Plugins/`。知识库需要另外配置 LightRAG；普通网站管理和 AI 对话不依赖它。模板编辑器从后台“网站模板”进入。

更多功能的操作步骤见 [使用说明](docs/使用说明.md)。

## 项目结构

| 目录 | 用途 |
| --- | --- |
| `Web/` | 唯一的网站启动入口，也提供后台、安装页和 API |
| `Web/Admin.Client/` | 后台页面与组件 |
| `Web/UIComponents/` | 网站及服务端后台的页面、布局、登录组件和独立路由入口 |
| `Web/Admin.Client/UIComponents/` | 后台 Blazor 前端组件 |
| `Components/` | 可独立编译为 DLL 的生成文件、数据库备份、图片处理、API 模板和 SMTP 邮件五个开放组件，见 [组件说明](Components/README.md) |
| `Orchestrator/` | Agent 配置、CMS 与网站业务逻辑 |
| `Common/`、`Agent.Abstractions/`、`Plugin.Abstractions/` | 共享模型与公开契约 |
| `Plugins/Knowledge/` | 知识库后端与后台界面源码 |
| `MiniProgram/` | 小程序前端源码 |
| `Plugin.Hot/` | 插件 SDK、模板与示例 |
| `skills/` | 内置技能说明 |
| `template/default/` | 默认网站模板 |
| `core/` | 开源导出包附带的预编译 AI 运行库 |

新增或修改代码组件前阅读 [组件开发说明](docs/组件开发说明.md)，修改后同步更新该说明和对应组件 README。

## 许可证

开放源码部分采用 **MIT 许可证**，详见 [LICENSE](LICENSE)。第三方依赖和静态资源遵循各自的许可证。社区发行包附带 Runtime、AiJson、CmsTemplates 配套 DLL，不包含这些闭源实现的源码。

会员注册协议：在后台「站点设置 → 用户协议」维护用户协议（纯文本，最多 20000 字）。点击《用户协议》弹窗阅读，必须勾选同意才能注册；服务端同时校验。