一、项目定位与目标

MaxKB（Maximally Knowledge Base）是一款面向企业的开源智能体（Agent）平台，旨在帮助开发者与业务团队快速搭建具备知识检索、工具调用与流程编排能力的 AI 应用。根据 README.md 的描述，MaxKB 的核心目标是"强大易用的企业级智能体平台"，通过将大语言模型（LLM）、向量检索与工作流编排整合在同一系统中，降低企业构建 AI 应用的门槛。

项目以 GPLv3 协议开源，对外提供 Docker 镜像与发布包，支持私有化部署。从代码组织上可以观察到项目同时覆盖了知识库管理、文档处理、工具扩展、应用编排、权限与工作空间管理等模块，是一个面向生产场景的综合平台，而不仅仅是单一功能的工具。

二、技术栈

依据 README.md 中的"Technical stack"章节，MaxKB 的核心技术选型如下：

在前端类型层，ui/src/api/type/common.ts 定义了 pageRequest、PageList、Dict 等通用类型，说明前端采用 TypeScript 并通过统一分页协议与后端交互。后端则在 apps/knowledge/api/knowledge.py 与 apps/tools/api/tool.py 等文件中通过 OpenApiParameter 与 APIMixin 显式声明参数与响应，体现了 Django REST Framework + drf-spectacular 的接口契约风格。

三、系统架构与模块划分

3.1 总体架构

MaxKB 采用前后端分离的 B/S 架构，后端以 Django 多应用（apps）组织业务模块，前端以 Vue 多模块（ui/src/api/*）组织 API 调用层。下图描述了主要模块的依赖关系与数据流。

flowchart LR
    Browser[浏览器 / 前端 Vue] -->|HTTP/JSON| Gateway[Django URL 路由]
    Gateway --> Apps
    subgraph Apps[后端 Django Apps]
        Knowledge[knowledge 知识库]
        Tools[tools 工具]
        Application[application 应用]
        Trigger[trigger 触发器]
        System[system 系统]
    end
    Apps --> ORM[Django ORM]
    ORM --> PG[(PostgreSQL + pgvector)]
    Apps --> LLM[LangChain / 大模型]
    LLM --> Apps
    Browser <-->|WebSocket/Streaming| Apps

3.2 后端 Django 应用模块

后端通过 apps/<module>/api/*.py 拆分业务接口，遵循统一的 OpenAPI 声明规范：

• knowledge 模块：负责知识库、文档、段落、术语库与版本管理。apps/knowledge/api/knowledge.py 暴露知识库分页、检索、同步等接口；apps/knowledge/api/document.py 提供文档迁移、源文件下载等能力；apps/knowledge/api/paragraph.py 维护段落顺序与内容；apps/knowledge/api/knowledge_version.py 则管理知识库的版本号，便于回滚与差异对比。
• tools 模块：apps/tools/api/tool.py 中可见工具按 SHARED 与 WORKSPACE 两种 scope 划分，并支持 PylintInstance 校验、EditIconAPI 等扩展点，便于接入自定义函数与第三方 API。
• trigger / application / system 模块：分别承载触发器调度、智能体应用编排以及用户、角色、权限与工作空间管理。这些模块在 ui/src/api/trigger/trigger.ts 与 ui/src/api/system/role.ts 的前端调用定义中得到对应体现。

3.3 前端 Vue 模块

前端 ui/src/api 目录按照"业务域 + 共享层"的方式组织：

• 业务域 API：如 knowledge/、trigger/ 等目录内的 .ts 文件，对应后端具体业务模块，例如 ui/src/api/knowledge/document.ts 中定义了 getDocumentDetail、putDocument 等与文档相关的请求方法。
• 共享层 API：system-shared/、system-resource-management/、shared-workspace.ts 等文件提供跨模块复用的接口，例如 ui/src/api/shared-workspace.ts 中 getUserGroupList、getUserGroupUserList 等方法用于在共享工作空间下访问知识库资源。
• 类型定义：type/ 目录集中声明通用类型，其中 ui/src/api/type/application.ts 定义了 chatType、Chunk 等流式对话相关结构，反映出 MaxKB 支持节点级工作流与流式响应（SSE/WebSocket）的能力。

四、数据模型与接口契约要点

从前端 API 与后端 OpenAPI 声明中可以提炼出几个贯穿全系统的设计要点：

1. 统一的分页协议：所有列表接口均要求 current_page 与 page_size，并通过 folder_id、scope、name 等查询参数做过滤，参见 apps/knowledge/api/knowledge.py 与 ui/src/api/type/common.ts 中的 pageRequest 接口。
2. 资源范围（scope）与工作空间隔离：知识库、工具等资源通过 workspace_id 路径参数与 scope 查询参数控制可见性，体现多租户设计，例如 apps/tools/api/tool.py 中的 scope 枚举 ["SHARED", "WORKSPACE"]。
3. 资源级触发器绑定：ui/src/api/trigger/trigger.ts 中 postResourceTrigger 等方法按 source_type 与 source_id 将触发器挂载到任意资源上，pageTriggerTaskRecord 则用于查询执行记录，方便审计与排错。
4. 角色与权限管理：ui/src/api/system/role.ts 提供角色成员增删、权限保存等接口，与后端的 RBAC 能力相对应。
5. 流式对话结构：前端 chatType、Chunk 等类型（见 ui/src/api/type/application.ts）表明应用层采用"节点 + 流式片段"的协议设计，每个 Chunk 携带 chat_id、chat_record_id、node_id、up_node_id 等字段，便于在 UI 中以工作流节点维度渲染对话过程。

五、典型请求流程示例

以"在工作空间中创建一个知识库文档"为例，请求链路如下：

1. 前端在 knowledge/document.ts 调用 postDocument，构造 { name, is_active, meta } 等字段。
2. 请求经 prefix.value（工作空间前缀）拼装后到达 Django URL 路由，匹配 apps/knowledge/api/document.py 中声明的参数与序列化器。
3. 视图层通过 ORM 将记录写入 PostgreSQL，并触发 LangChain 流水线完成文档解析、向量化与段落入库。
4. 前端通过 getDocumentDetail 拉取最新状态，结合 chatType 中的流式协议在 UI 上呈现。

六、See Also

• 知识库与文档管理：参考 apps/knowledge/api/ 目录下各接口文件以及 ui/src/api/knowledge/ 前端封装。
• 工具与触发器扩展：参考 apps/tools/api/tool.py 与 ui/src/api/trigger/trigger.ts。
• 角色与工作空间权限：参考 ui/src/api/system/role.ts 与 ui/src/api/shared-workspace.ts。
• 流式对话与节点渲染：参考 ui/src/api/type/application.ts 中 chatType、Chunk 类型定义。

1. 概述

MaxKB 是一套面向企业级智能体场景的开源平台，技术栈由 Vue.js 前端、Python/Django 后端、LangChain 框架以及 PostgreSQL + pgvector 组成。在该体系中，"知识库"（Knowledge Base）是 RAG（检索增强生成）能力的核心载体，承载文档入库、段落切分、向量化、相似度检索、术语管理以及与触发器/工具的协同等能力。

资料来源：README.md:23-26

围绕"知识库"这一领域，系统在前后端分别提供了多套 API 客户端与 OpenAPI 描述：

• 后端使用 DRF 风格的 APIMixin 描述参数与请求/响应 Schema，参数语义在中文注释中显式给出（如"知识库id"、"工作空间id"），方便国际化与 OpenAPI 文档生成。
• 前端将相同语义封装为 TypeScript 函数，按 knowledge / document / problem / trigger / tool 等模块拆分，并通过 Result<T> 统一返回类型。

资料来源：apps/knowledge/api/paragraph.py:1-90、ui/src/api/knowledge/document.ts:1-20

2. 知识库与文档/段落处理 API

2.1 文档级别的迁移与下载

文档级别的迁移涉及"源知识库 → 目标知识库"的跨库搬运，以及"源文档 → 目标文档"的精确迁移两个层级。

• DocumentMigrateAPI 仅要求 workspace_id / knowledge_id / target_knowledge_id 三个路径参数，使用 DocumentMigrateSerializer 作为请求体，语义为"把当前知识库的文档批量迁到目标知识库"。
• Paragraph 维度则提供更细粒度的 BatchSerializer 入口，使用 target_knowledge_id + target_document_id 联合定位，使段落级数据可在不同文档间重排。

DocumentDownloadSourceAPI 用于下载文档原始来源，参数只到 workspace_id / knowledge_id，代表原始资源在知识库粒度进行索引。

资料来源：apps/knowledge/api/document.py:1-90、apps/knowledge/api/paragraph.py:1-60

2.2 段落顺序与版本管理

段落顺序的微调由 ParagraphAdjustOrderAPI 提供，参数为 paragraph_id（查询串）与 new_position（查询串），响应使用 DefaultResultSerializer，体现"段落顺序可单独维护、不需要重新触发向量化"的设计思路。

KnowledgeVersionAPI、KnowledgeVersionOperateAPI、KnowledgeVersionListAPI 与 KnowledgeVersionPageAPI 组成了知识库的版本子系统：

• KnowledgeVersionListAPI 在 KnowledgeVersionOperateAPI 的基础上额外接受 name（Version Name）查询参数，用于按版本名过滤。
• KnowledgeVersionPageAPI 复用了 List 的参数定义，但响应从列表升级为分页 KnowledgePageVersionResult，符合列表 → 详情 → 分页的常见 API 演进模式。

资料来源：apps/knowledge/api/paragraph.py:60-90、apps/knowledge/api/knowledge_version.py:1-50

2.3 术语库（Termbase）

TermbasePageAPI 与 TermbaseDeleteAPI 把"术语/问题"作为知识库下的二级资源进行管理：

• 分页接口要求 workspace_id / knowledge_id / current_page / page_size，与 pageRequest 约定一致。
• 删除接口在路径中追加 problem_id，与 ui/src/api/knowledge/problem.ts 中 delProblems(knowledge_id, problem_id) 的前端封装形成对应，后端 problem_id 即前端"问题"的实体键。

资料来源：apps/knowledge/api/termbase.py:1-60、ui/src/api/knowledge/problem.ts:1-30

3. 工具、触发器与 RAG 协同

工具（Tool）与触发器（Trigger）通过显式的 scope 与 source_type 字段，与知识库解耦地挂载到工作空间或具体资源上：

source_type + source_id 的设计意味着：知识库既可作为触发器的"被作用资源"（如"文档变更时同步重建索引"），也可被应用（Application）作为长期记忆的载体——这一点与 chatType 中的 long_term_enable / long_term_model_id / long_term_trigger_setting 字段呼应。

资料来源：ui/src/api/type/application.ts:1-40、ui/src/api/trigger/trigger.ts:30-90

4. 前端 API 客户端与分页约定

前端 TypeScript 层将后端 API 拆为 system-shared（跨工作空间共享）与 system-resource-management（资源端管理）两个 bundle，再按业务域 knowledge / document / problem / trigger / tool 进一步拆分。

通用分页类型在 type/common.ts 中统一定义：

interface pageRequest { current_page: number; page_size: number }
interface PageList<T>  { current: number; size: number; total: number; records: T }

该约定贯穿 TermbasePageAPI、pageTriggerTaskRecord、pageKnowledgeDocument 等所有分页接口，避免前后端在 current_page 与 current、page_size 与 size 上的命名漂移。

资料来源：ui/src/api/type/common.ts:1-20、ui/src/api/system-shared/knowledge.ts:1-20、ui/src/api/system-shared/document.ts:1-20

flowchart LR
  A[Workspace] --> B[Knowledge Base]
  B --> C[Document]
  C --> D[Paragraph]
  C --> E[Problem/Termbase]
  B --> F[Knowledge Version]
  D --> G[Embedding Task]
  G --> H[(pgvector)]
  H --> I[RAG 检索 / Chat]
  F -.回滚/对比.-> I
  E -.术语加权.-> I
  J[Tool SHARED/WORKSPACE] --> I
  K[Trigger source_type/source_id] --> C
  K --> G

上述流程仅基于源码中可见的字段与 API 形态（段落顺序、文档迁移、版本列表、术语库、工具 scope、触发器 source_type）抽象而成，未引入未经源码验证的组件。

See Also

• 智能体与应用对话：ui/src/api/type/application.ts
• 工具与工作流：ui/src/api/system-shared/tool.ts
• 触发器执行记录：ui/src/api/trigger/trigger.ts
• 通用分页约定：ui/src/api/type/common.ts

一、概述

MaxKB 是一个面向企业级场景的开源智能体（Agent）平台，其核心能力由"应用（Application）"、"对话流水线（Chat Pipeline）"以及"Agentic 工作流引擎"三层结构协同提供。应用层负责将用户会话、模型与外部资源封装为可发布的服务；对话流水线负责在一次问答中按步骤完成问题改写、知识检索、上下文组装、模型推理与回复渲染；而 Agentic 工作流引擎则以知识库工作流（Knowledge Workflow）和触发器（Trigger）为载体，使应用能够基于事件或调度自动执行多步骤推理与外部动作。

本说明围绕仓库中可直接观察到的接口定义、类型声明以及 API 视图类展开，重点说明对话数据结构、知识库工作流的版本化机制、触发器驱动的 Agentic 任务执行以及工具调用等关键能力。

二、应用与对话数据结构

前端通过统一的 TypeScript 类型描述一次应用会话的完整生命周期。

2.1 会话（chatType）

ui/src/api/type/application.ts 中定义的 chatType 描述了一条对话记录的全部状态：包括问题文本 problem_text、回答文本 answer_text、用于流式渲染的缓冲区 buffer 与 answer_text_list、投票状态 vote_status、执行详情 execution_details 以及上传的媒体元数据 upload_meta。该类型同时暴露 write_ed（是否写入结束）与 is_stop（是否暂停）等运行时标志，用于驱动前端流式 UI。

2.2 流式片段（Chunk）

Chunk 类型是流水线单步产出的最小渲染单元，其关键字段包括 content、reasoning_content、node_id、up_node_id、runtime_node_id、view_type、node_type 与 is_end / node_is_end。child_node 字段允许一个片段携带子节点，从而支撑多分支、工具嵌套调用等 Agentic 行为。

2.3 节点（Node）

Node 类型描述流水线图中单个节点的运行态，包含 buffer、node_id、up_node_id 等。结合 Chunk.child_node，可以看出 MaxKB 的对话流水线本质上是一棵按节点 ID 与父节点 ID 串联的执行树，而非线性管道。

flowchart LR
    A[用户问题] --> B[问题改写 Step]
    B --> C[知识库检索 Step]
    C --> D[历史消息生成 Step]
    D --> E[LLM 推理 Step]
    E --> F[工具调用 Step]
    F --> G[回复渲染 Chunk 流]

三、知识库工作流与版本化

知识库工作流是把多步数据处理（采集、清洗、向量化、入库）编排为可视化 DAG 的机制，并由版本系统保证可回滚、可发布。

3.1 工作流动作 API

apps/knowledge/api/knowledge_workflow.py 通过 KnowledgeWorkflowActionApi 暴露工作流执行入口，其 Operate 子类要求路径参数 workspace_id 与 knowledge_id，请求体由 KnowledgeWorkflowActionRequestSerializer 序列化。该视图类既支持单步运行，也支持触发完整的 DAG 执行。

3.2 工作流版本 API

apps/knowledge/api/knowledge_version.py 定义了 KnowledgeVersionAPI、KnowledgeVersionOperateAPI、KnowledgeVersionListAPI 与 KnowledgeVersionPageAPI 四类接口，用于版本创建、按 knowledge_version_id 操作、按名称过滤以及分页查询。其中 KnowledgeVersionOperateAPI 通过 *KnowledgeVersionAPI.get_parameters() 复用基础路径参数，体现出 MaxKB 在 OpenAPI Schema 组合上的复用约定。版本响应体 KnowledgeWorkflowVersionResult 描述了某一发布快照的全部参数。

3.3 段落顺序调整

apps/knowledge/api/paragraph.py 中的段落重排接口要求 document_id、paragraph_id 与 new_position，表明知识库工作流的执行结果（段落）支持运行时顺序调整，属于 Agentic 工作流对下游数据再编排的能力。

四、触发器驱动的 Agentic 任务

Agentic 行为的关键不在单次问答，而在"何时、以何种上下文、自动触发"。

4.1 触发器任务记录

ui/src/api/trigger/trigger.ts 提供了 pageTriggerTaskRecord 与 getTriggerTaskRecordDetails 等接口，用于按 trigger_id 分页查询触发器执行历史及单条记录的详情。每条记录包含 trigger_task_id 与 trigger_task_record_id 两级 ID，便于对一次自动执行链路进行审计与回放。

4.2 资源端触发器创建

同文件中的 postResourceTrigger(source_type, source_id, data) 接口允许针对某一资源（如知识库、应用）创建触发器，路径为 ${prefixWorkspace.value}/${source_type}/${source_id}/trigger。source_type 的设计使触发器成为可挂载到任意资源上的横切能力，构成 Agentic 工作流的事件入口。

五、工具调用与作用域

Agentic 工作流通常需要调用外部工具。apps/tools/api/tool.py 在工具分页查询接口中显式声明了 scope 查询参数，其枚举值为 SHARED 与 WORKSPACE，并以 folder_id 限定目录、user_id 限定创建者、name 限定名称。这意味着：

工具接口同时暴露 PylintAPI 与 EditIconAPI，说明工具在保存前会进行代码校验（适用于脚本型 / 函数型工具），并允许上传自定义图标以改善 Agent 编排画布的视觉表现。

六、常见注意事项

1. 流式渲染必须正确处理 is_end 与 node_is_end 的差异：前者表示整条对话结束，后者仅表示当前节点结束，二者均需在前端 chunk 处理逻辑中考虑。资料来源：ui/src/api/type/application.ts
2. 知识库版本一旦发布，修改段落顺序需要走专门的 new_position 接口，而非直接编辑文档内容。资料来源：apps/knowledge/api/paragraph.py
3. 触发器任务记录采用两级 ID 设计（trigger_task_id / trigger_task_record_id），用于区分"任务定义的一次执行"与"该次执行中产生的某条历史"。资料来源：ui/src/api/trigger/trigger.ts
4. 工具的 SHARED 与 WORKSPACE 作用域在创建后不可更改，新建工具时必须确认所属。资料来源：apps/tools/api/tool.py
5. 工作流版本的查询支持按名称模糊匹配并分页，便于在大规模知识库中定位历史快照。资料来源：apps/knowledge/api/knowledge_version.py

See Also

• 知识库文档与段落管理：apps/knowledge/api/document.py
• 知识库问题与术语库：apps/knowledge/api/termbase.py
• 通用类型定义：ui/src/api/type/common.ts
• 角色与权限：ui/src/api/system/role.ts

概述

MaxKB 作为企业级智能体平台，核心扩展能力围绕"工具（Tool）"、"MCP（Model Context Protocol）"、"触发器（Trigger）"以及"工作流（Workflow）"四条主线构建。模型提供商（Model Provider）层负责接入大语言模型；工具与 MCP 层负责让模型在对话中调用外部能力；触发器层负责把"事件"接入到工作流；工作流层则把工具、模型、数据源编排成可复用的扩展单元。本页基于平台暴露的 API 契约说明其交互关系。

工具系统架构

工具（Tool）是 MaxKB 扩展机制的基础单元，每个工具既可作为"内置工具（Internal）"使用，也可来源于"工具市场（Store）"或通过"工作流工具"动态生成。平台对工具的管理分为两类作用域：SHARED（共享）与 WORKSPACE（工作空间级），这一约束在 OpenAPI 参数中显式声明。

flowchart LR
    A[LLM 应用] --> B[工具调用网关]
    B --> C{工具来源}
    C -->|内置| D[addInternalTool]
    C -->|市场| E[addStoreTool / updateStoreTool]
    C -->|工作流| F[putToolWorkflow / debugToolWorkflow]
    B --> G[postToolTestConnection]
    B --> H[delTool / putToolIcon]

关键 API 入口集中在两个文件：后端的 apps/tools/api/tool.py 通过 OpenApiParameter 定义了 workspace_id、folder_id、user_id、scope（["SHARED", "WORKSPACE"]）和 name 等参数，用于工具的列表分页与查询；前端的 ui/src/api/system-resource-management/tool.ts 暴露了 getToolListPage、getToolById、putTool、delTool、postToolTestConnection 等方法，与资源管理界面绑定。

工具相关的扩展能力进一步通过 ui/src/api/system-shared/tool.ts 暴露，包括 addInternalTool、addStoreTool、updateStoreTool（市场工具安装与升级）、uploadSkillFile 与 downloadSkillFile（技能文件管理）、generateCode（代码生成）、postPylint（静态校验，由 PylintAPI 暴露）、exportTool/importToolWorkflow（工具导入导出）、listToolWorkflowVersion 与 updateToolWorkflowVersion（工具工作流版本管理）、debugToolWorkflow（调试入口），共同构成"工具即代码 + 工具即工作流"的双形态。

MCP 集成机制

MCP（Model Context Protocol）作为模型与外部工具/数据源之间的标准协议，在 MaxKB 中通过知识库共享工作空间统一暴露。getMcpTools 是 MCP 工具的核心获取入口，定义在 ui/src/api/system-shared/knowledge.ts 的导出列表中。同一文件还导出了 postTransformWorkflow，用于将既有工作流转换为 MCP 协议暴露的形态；以及 exportKnowledgeBundle 与 importKnowledgeBundle，用于以"知识包"形式整体迁移含 MCP 工具的工作流。这意味着 MCP 工具在平台内被视为"知识库 + 工作流"的复合产物，而非单纯的 API 包装。

触发器与扩展点

触发器（Trigger）是 MaxKB 把外部事件接入工作流的核心机制。资源端（Resource）可对 APPLICATION、KNOWLEDGE 等资源绑定触发器，由 ui/src/api/trigger/trigger.ts 提供完整 API：

触发器与"长期记忆"在应用层也有显式关联：应用类型 long_term_trigger_type 与 long_term_trigger_setting 字段（见 ui/src/api/type/application.ts）允许把外部触发器作为长期记忆的写入条件，从而形成"事件 → 触发器 → 工作流 → 记忆/回复"的闭环。

工作流扩展与版本管理

工作流既是工具的实现形态，也是知识库的处理流水线。getWorkflowAction、getKnowledgeWorkflowFormList、getKnowledgeWorkflowDatasourceDetails 与 workflowAction 用于工作流的查询与执行；workflowUpload 与 putKnowledgeWorkflow 用于上传与更新；publish 触发发布；listKnowledgeVersion 与 getWorkflowActionPage 提供版本与分页；exportKnowledgeWorkflow 与 importKnowledgeWorkflow 支持跨环境迁移。postTransformWorkflow 进一步把"普通工作流"提升为"MCP 暴露形态"，与上一节的 MCP 机制形成连接。

See Also

• 知识库与文档管理：ui/src/api/knowledge/document.ts
• 应用与对话类型定义：ui/src/api/type/application.ts
• 触发器任务记录查询：ui/src/api/trigger/trigger.ts

Pitfall Log / 踩坑日志

项目：1Panel-dev/MaxKB

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

1. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb
• 证据：identity.distribution | https://github.com/1Panel-dev/MaxKB | docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/1Panel-dev/MaxKB | host_targets=mcp_host, claude, chatgpt

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/1Panel-dev/MaxKB | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/1Panel-dev/MaxKB | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/1Panel-dev/MaxKB | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/1Panel-dev/MaxKB | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/1Panel-dev/MaxKB | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/1Panel-dev/MaxKB | release_recency=unknown