1. 项目定位与目标用户

kotaemon 是一个开源、可定制的 RAG（Retrieval-Augmented Generation）文档问答系统，对终端用户和开发者都提供了清晰的切入点。仓库根目录的 README.md 将生态参与者划分为三层：终端用户（使用基于 kotaemon 构建的应用）、开发者（在自己的项目中 import kotaemon）、以及贡献者（直接向本仓库提交 PR）。资料来源：README.md

仓库在 libs/kotaemon/README.md 中进一步说明，核心包 kotaemon 是“可快速复用的 AI 组件”，目标是让构建 RAG 流水线变得简单；推荐使用 Conda 创建 Python 3.10 环境并以 pip install -e ".[dev]" 方式安装。资料来源：libs/kotaemon/README.md

2. 仓库顶层结构

项目采用“核心库 + 应用层”的双包结构：

• libs/kotaemon/：可独立发布的 Python 库，提供 RAG 流水线所需的组件抽象、加载器、向量存储、LLM 适配、Agent 等。
• libs/ktem/：基于 Gradio 的应用层，提供多用户登录、文档集合管理、对话界面等终端用户可见的功能。

这一分层使得库可以被其他项目复用，而 UI 与状态管理逻辑被隔离在 ktem 中。

3. 核心子系统

3.1 文档加载器（Loaders）

kotaemon.loaders 提供了多种文件解析器，统一返回 Document 对象并附带 page_label 等元数据：

• ImageReader 通过外部 OCR HTTP 端点（OCR_READER_ENDPOINT 环境变量或默认值）抽取扫描型 PDF 中的文本与表格。资料来源：libs/kotaemon/kotaemon/loaders/ocr_loader.py
• PaddleOCRAdapter 适配 PaddleOCR 家族（PPStructureV3、PaddleOCRVL）的输出结构，将 parsing_res_list 中的 block_label/block_content 归类为文本、表格、图片或公式。资料来源：libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py
• DoclingReader 利用 docling 的页面坐标信息，将 texts、tables、figures 拆分为独立的 Document 并保留页码与文件名。资料来源：libs/kotaemon/kotaemon/loaders/docling_loader.py
• DocxReader 将 DOCX 中的表格以 CSV 形式存入 table_origin 元数据并生成额外的非表格文本 Document。资料来源：libs/kotaemon/kotaemon/loaders/docx_loader.py
• MathpixPDFReader 通过 Mathpix API 处理 PDF，并将表格与正文拆分到带 page_label 的不同 Document 中。资料来源：libs/kotaemon/kotaemon/loaders/mathpix_loader.py

3.2 Agent 与工具

kotaemon.agents.tools 通过 __init__.py 暴露了一组统一接口的工具基类与具体实现：BaseTool、ComponentTool、GoogleSearchTool、WikipediaTool、LLMTool 以及 MCP 工具集。资料来源：libs/kotaemon/kotaemon/agents/tools/__init__.py

MCPTool 是面向 Model Context Protocol 服务的适配层：_json_schema_type_to_python 将 JSON Schema 类型映射为 Python 类型，build_args_model 动态生成 Pydantic 参数模型，使任意 MCP 工具都能被 Agent 调度。资料来源：libs/kotaemon/kotaemon/agents/tools/mcp.py

WikipediaTool 封装 wikipedia Python 包：在 PageError 或 DisambiguationError 时返回相似条目，否则返回带 page URL 元数据的 Document。资料来源：libs/kotaemon/kotaemon/agents/tools/wikipedia.py

ReWOOAgent 沿“规划—执行—求解”三阶段推进：planner 生成 #Plan1/#E1 形式的步骤，worker 并发调用工具并把结果写回 worker_log，最后由 solver 综合输出，并可在 use_citation=True 时附加 CitationPipeline 输出。资料来源：libs/kotaemon/kotaemon/agents/rewoo/agent.py 其提示词模板（含 zero/few-shot 变体）定义在 prompt.py 中。资料来源：libs/kotaemon/kotaemon/agents/rewoo/prompt.py

3.3 UI 渲染

libs/ktem/ktem/utils/render.py 提供了把 RetrievedDocument 转为 HTML 的工具集：Render.collapsible 生成可折叠证据块，get_header 自动拼接 [Page X] 与 file_name，并通过 GR_FILE_ROOT_PATH 环境变量构造 PDF 预览链接（同时根据 fast_langdetect 的语言结果决定高亮策略）。资料来源：libs/ktem/ktem/utils/render.py

4. 整体数据流

flowchart LR
    U[用户] --> UI[Gradio UI / ktem]
    UI --> AG[ReWOO / ReAct Agent]
    AG --> TL[kotaemon.agents.tools]
    TL --> MCP[MCP 服务]
    TL --> EXT[Wikipedia / Google]
    UI --> LD[kotaemon.loaders]
    LD --> DOC[Document + 元数据]
    DOC --> VS[向量库 / 检索器]
    VS --> AG
    AG --> AN[答案 + Citation]
    AN --> UI

5. 社区关注点与扩展方向

• 本地部署体验：Issue #138 反映 Apple Silicon (M1) 用户在 Docker 镜像外的本地安装流程缺乏文档，需要参照 libs/kotaemon/README.md 中的 Conda + pip install -e ".[dev]" 步骤。资料来源：Issue #138
• 新增 LLM Provider：社区对 AWS Bedrock（#392，使用 Converse API 接入 Anthropic、Meta、Mistral、Cohere 等）以及 Gemini（#160）有明确需求，但目前仓库文档中列出的 Provider 仍以 OpenAI、AzureOpenAI、Cohere、Ollama、llama-cpp-python 为主。资料来源：Issue #392、Issue #160
• GraphRAG 替代实现：Issue #243 提出集成 nano-graphrag 等更轻量的 GraphRAG 后端。资料来源：Issue #243
• FastAPI 端点：Issue #647 提议在 Docker 镜像中暴露 FastAPI，以便将 GUI 与程序化调用解耦。资料来源：Issue #647
• 多模态加载器：v0.12.0 版本日志显示 PaddleOCR 已作为新的文档加载器集成，聊天与索引 UI 也获得增强。资料来源：Release v0.12.0

See Also

• 文档加载器与 OCR 适配详情
• ReWOO Agent 与 MCP 工具集成
• Gradio 应用层（ktem）多用户与渲染管线

概述

kotaemon 是一个面向终端用户与开发者的开源 RAG 问答 UI/框架，其核心目标是把任意格式的文档通过统一的 Document 抽象加载、切分、向量化，进而在用户提问时执行混合检索与重排序，最终把相关证据送入 LLM 生成答案。资料来源：README.md:9-18 将项目明确定位为"an open-source clean & customizable RAG UI for chatting with your documents"。资料来源：libs/kotaemon/README.md:3-7 进一步说明 kotaemon 是构建 RAG 流水线所需的 AI 组件库。

整个 RAG 核心由三个相互衔接的阶段组成：文档加载（Loading）→ 索引（Indexing）→ 检索（Retrieval）。前两个阶段发生在用户上传文件时，检索阶段则在每次用户对话时执行。

文档加载层

kotaemon/loaders/ 子包提供多格式、可插拔的加载器，所有加载器都最终产出 Document 对象列表，并保留 page_label、file_name、type（text/table/figure）等元数据，便于后续按页定位。

多格式加载器

OCR 集成

对于扫描件或图片型 PDF，kotaemon 提供两套 OCR 路径。ImageReader（位于 ocr_loader.py）通过调用外部 FullOCR 端点（默认 http://127.0.0.1:8000/v2/ai/infer/，可通过环境变量 OCR_READER_ENDPOINT 覆盖）抽取图片与表格 资料来源：libs/kotaemon/kotaemon/loaders/ocr_loader.py:60-80。在 v0.12.0 版本中，社区新增了 PaddleOCR 加载器，其 PaddleOCRAdapter 将 PPStructureV3/PaddleOCRVL 的原始输出按 text_labels、table_labels、image_labels、formula_labels 分类，并对 figure 进行裁剪与 base64 编码 资料来源：libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py:18-46。两个 OCR 流水线之间还提供了 merge_ocr_and_pdf_texts 工具，基于 IOU 重叠度合并 OCR 与原生 PDF 文本，避免重复 资料来源：libs/kotaemon/kotaemon/loaders/utils/pdf_ocr.py:84-110。

索引与检索流程

加载器输出的 Document 流经索引流水线（切片 → embedding → 写入向量库）后，会在用户提问时触发检索。下面是端到端数据流：

flowchart LR
    A[原始文件<br/>PDF/DOCX/Image] --> B[Loader<br/>多格式解析]
    B --> C[Document 列表<br/>含 page_label/type]
    C --> D[Chunking & Embedding]
    D --> E[(向量库 + 全文索引)]
    F[用户问题] --> G[Hybrid Retriever<br/>向量 + BM25]
    E --> G
    G --> H[Re-ranker]
    H --> I[LLM 生成答案]
    I --> J[Render 渲染<br/>可折叠证据]

检索阶段采用"向量召回 + 全文召回 + 重排序"的混合策略，这是 README 中"Hybrid RAG pipeline"的默认实现 资料来源：README.md:43-46。在多步推理场景下，ReWOO Agent 会先调用 planner 生成 #Plan / #E 计划，再让 worker 串行执行工具调用（如 MCPTool、WikipediaTool），最后由 solver 综合证据得出结论 资料来源：libs/kotaemon/kotaemon/agents/rewoo/agent.py:96-122。MCP 工具通过 build_args_model 把 MCP Server 的 JSON Schema 动态转成 Pydantic 模型，从而无缝接入同一套检索/Agent 框架 资料来源：libs/kotaemon/kotaemon/agents/tools/mcp.py:25-40。

渲染与展示

检索到的证据最终要在 Gradio UI 中以可折叠、含页码定位的方式呈现。ktem.utils.render.Render 负责把 RetrievedDocument 渲染为 HTML：它会从元数据中读取 page_label 与 file_name 作为标题，PDF 还会附带一个 data-page 属性的 [Preview] 链接，点击后跳转到对应页 资料来源：libs/ktem/ktem/utils/render.py:30-39 与 资料来源：libs/ktem/ktem/utils/render.py:90-115。这种"证据 + 预览"双视图是 kotaemon 区别于纯命令行 RAG 框架的关键体验。

常见问题

• Docker 镜像与本地安装差异：社区反馈官方 Docker 镜像在 Apple Silicon 上不可用，建议在 M1/M2 Mac 上直接 pip install -e ".[dev]" 进行本地部署 资料来源：README.md:9-18。
• OCR 后端选择：如需识别公式或复杂版面，优先选择 Mathpix；如需中文场景的版面分析，v0.12.0 新增的 PaddleOCR 加载器是更轻量的替代方案 资料来源：libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py:18-46。
• 检索质量调优：可在 UI 中替换 embedding 模型或重排序模型，无需修改任何加载器代码，因为所有加载器只产出统一的 Document 抽象。

See Also

• README.md — 项目总览与功能列表
• libs/kotaemon/README.md — kotaemon 组件库安装与开发指南
• libs/ktem/ — Gradio 应用层（含 UI 页面、用户管理、对话流程）
• libs/kotaemon/kotaemon/agents/ — ReAct / ReWOO Agent 实现
• libs/kotaemon/kotaemon/loaders/ — 全部文档加载器入口

概述与组件定位

kotaemon 是一个面向终端用户与开发者的开源 RAG 用户界面。在系统中，LLM 与 Embedding 模型承担"生成"与"语义表示"的职责，智能体推理层则负责"调度"与"多步决策"。README 明确写道：项目"支持本地 LLM 与主流 API 提供商（OpenAI、Azure、Ollama、Groq）"，并"使用问题分解回答复杂/多跳问题，且支持基于代理的推理（ReAct、ReWOO 等代理）"（资料来源：README.md:37-49）。

智能体层的核心代码位于 libs/kotaemon/kotaemon/agents/，主要包含 tools/（工具集合）与 rewoo/（ReWOO 代理实现）两个子包；前端的证据渲染则由 libs/ktem/ktem/utils/render.py 提供 HTML 折叠块、表格与标题生成能力。

LLM 与 Embedding 接入

README 在 *Key Features* 中总结了接入策略：

• 多模型组织：用户可在 UI 中切换本地 LLM（Ollama、llama-cpp-python）或 API 提供商（OpenAI、Azure、Groq 等）（资料来源：README.md:46-49）。
• 混合 RAG 默认管道：结合全文本检索与向量检索，并由 re-ranker 保证召回质量（资料来源：README.md:50-52）。
• 多模态问答：可对带图表的文档进行问答，并支持多种文档解析后端（资料来源：README.md:53-56）。

社区请求反映出接入面仍在扩张：例如 #392 要求增加 AWS Bedrock（通过 Converse API 接入 Anthropic、Meta、Mistral、Cohere 等），#160 要求支持 Google Gemini API。这些均显示"模型无关"适配层是当前重点演进方向。开发者在二次开发时应遵循 libs/kotaemon/README.md 的流程：创建 conda 环境、克隆仓库、pip install -e ".[dev]"（资料来源：libs/kotaemon/README.md:11-23）。

智能体推理框架

ReWOO 代理工作流

libs/kotaemon/kotaemon/agents/rewoo/agent.py 实现了 ReWOO 的"规划 → 执行 → 求解"三阶段流程，整体数据流如下：

flowchart LR
    U[用户问题] --> P[Planner LLM]
    P -->|Plan+E 序列| Parse[解析计划与证据映射]
    Parse --> W[Worker 调用工具]
    W -->|worker_log| S[Solver LLM]
    S --> Cite[CitationPipeline 可选]
    Cite --> Out[AgentOutput]

具体执行逻辑：

1. 规划（Plan）：调用 self.planner(instruction) 让 LLM 输出多步计划与对应工具调用，解析为 plan_to_es（计划→证据映射）与 plans（资料来源：libs/kotaemon/kotaemon/agents/rewoo/agent.py:18-30）。
2. 执行（Work）：_get_worker_evidences 真正调用外部工具，把每条证据的回写日志整理为 worker_log（资料来源：libs/kotaemon/kotaemon/agents/rewoo/agent.py:31-45）。
3. 求解（Solve）：self.solver(instruction, worker_log) 汇总计划与证据生成最终回答；若 use_citation=True，再经 CitationPipeline 抽取引用（资料来源：libs/kotaemon/kotaemon/agents/rewoo/agent.py:46-58）。

最终结果被包装为 AgentOutput，包含文本、代理类型、状态、总 token 与总成本，以及可选的 citation 字段。stream 方法以同样的三阶段结构支持流式输出（资料来源：libs/kotaemon/kotaemon/agents/rewoo/agent.py:60-78）。

工具系统（Tools）

libs/kotaemon/kotaemon/agents/tools/__init__.py 统一导出工具抽象与具体实现（资料来源：libs/kotaemon/kotaemon/agents/tools/__init__.py:1-15）：

WikipediaTool 在 wikipedia.py 中调用 wikipedia Python 包：若页面存在则返回内容与 URL，否则返回 Could not find [...] 与相似条目列表（资料来源：libs/kotaemon/kotaemon/agents/tools/wikipedia.py:10-32）。其参数由 WikipediaArgs 定义，强制 query 字段，将任意字符串安全映射为 Pydantic 校验后的输入（资料来源：libs/kotaemon/kotaemon/agents/tools/wikipedia.py:34-43）。

MCP 工具集成

tools/mcp.py 把 MCP SDK 的工具 schema 桥接到 BaseTool，让 ReAct/ReWOO 代理透明使用任意 MCP 服务器暴露的能力。模块提供：

• _json_schema_type_to_python：将 JSON Schema 类型映射到 Python 原生类型（资料来源：libs/kotaemon/kotaemon/agents/tools/mcp.py:36-46）。
• build_args_model：依据 input_schema 动态构建 Pydantic 模型，使每个 MCP 工具具备类型安全的参数 schema（资料来源：libs/kotaemon/kotaemon/agents/tools/mcp.py:48-65）。
• 同时导出 discover_tools_info、create_tools_from_config、parse_mcp_config、format_tool_list 等辅助函数，便于在配置文件中声明 MCP 服务并自动装配工具列表（资料来源：libs/kotaemon/kotaemon/agents/tools/mcp.py:1-15）。

提示词模板与求解策略

libs/kotaemon/kotaemon/agents/rewoo/prompt.py 定义 ReWOO 的核心提示词：

• 规划提示词（默认与 few_shot_planner_prompt）：要求 LLM 输出 #Plan1: ... #E1: toolname[input] 序列，并显式说明"每条证据存入不同变量 #E1, #E2, #E3 … 以便后续工具调用引用"（资料来源：libs/kotaemon/kotaemon/agents/rewoo/prompt.py:1-40）。
• 求解提示词（zero_shot_solver_prompt / few_shot_solver_prompt）：把规划与证据拼接为"先做…再…，所以…"的总结形式，并要求以 {lang} 指定的语言输出（资料来源：libs/kotaemon/kotaemon/agents/rewoo/prompt.py:42-80）。

模板通过 PromptTemplate 注入可用工具描述（{tool_description}）与任务（{task}），实现"工具集合动态拼装 + 规划/求解解耦"的工程模式。

引用与协同渲染

推理结果在 UI 中呈现时，libs/ktem/ktem/utils/render.py 提供统一 HTML 渲染器：

• Render.collapsible 将每条证据渲染为 `

前端、部署与定制化

一、概述

kotaemon 是一个面向终端用户与开发者的开源 RAG（检索增强生成）UI 框架。终端用户可以使用它直接与文档对话，开发者可以基于其组件构建自定义的 RAG 流水线。在前端层面，kotaemon 基于 Gradio 构建可定制的 UI；在部署层面，项目提供本地 pip 安装、conda 环境与 Docker 镜像三种主要途径；在定制化层面，框架通过解耦的 Loader、Tool、Agent 与渲染工具，便于扩展新的数据源、模型与交互行为。资料来源：README.md:1-50。

二、前端渲染与交互管线

前端的职责集中在将检索结果（RetrievedDocument）与聊天内容渲染为可阅读的 HTML。Render 工具类负责多种渲染样式：可折叠证据块（collapsible）、Markdown 表格（table）、PDF 高亮链接、<mark> 标签（highlight）和图片（image）等。资料来源：libs/ktem/ktem/utils/render.py:1-100。

get_header 工具会根据元数据中的 page_label 与 file_name 拼装证据标题，例如 [Page 3] report.pdf，并最终通过 Render.collapsible 形成可折叠 HTML 片段。资料来源：libs/ktem/ktem/utils/render.py:24-31。preview_pdf 还会通过 fast_langdetect 推断文本语言，针对非中日韩文本自动选择高亮片段并生成可在 PDF 阅读器中跳转的 <a class="pdf-link"> 锚点。资料来源：libs/ktem/ktem/utils/render.py:50-100。

flowchart LR
  A[用户提问] --> B[Gradio ChatPanel]
  B --> C[RAG Pipeline]
  C --> D[RetrievedDocument]
  D --> E[Render 工具]
  E --> F[collapsible/table/highlight]
  F --> G[Gradio Markdown 渲染]
  G --> H[浏览器展示]

三、部署方式

社区中 M1 Mac 用户曾反馈 Docker 镜像落后于主分支且与 arm64 平台不兼容（Issue #138），因此在 Apple Silicon 上更推荐使用本地 pip + Conda 的方式。资料来源：README.md:1-30。

四、扩展与定制化

4.1 文档加载器

kotaemon 内置多种 Loader，可通过新增模块加入 kotaemon/loaders/ 目录进行扩展。例如 PaddleOCRAdapter 接收 PPStructureV3 或 PaddleOCRVL 的原始结果，将 parsing_res_list 转换为 Document 对象，并根据 block_label 区分文本、表格、图像与公式。资料来源：libs/kotaemon/kotaemon/loaders/paddleocr_loader/adapter.py:1-50。OCRReader 通过 OCR_READER_ENDPOINT 环境变量连接外部 OCR 服务，用于从扫描 PDF 中提取文本与表格。资料来源：libs/kotaemon/kotaemon/loaders/ocr_loader.py:40-70。DocxReader 使用 docx 解析 DOCX 文件中的表格与非表格文本，分别以 type: table 与 type: text 的元数据标记。资料来源：libs/kotaemon/kotaemon/loaders/docx_loader.py:1-50。

4.2 Agent 与工具

kotaemon/agents/tools/__init__.py 集中暴露了 BaseTool、ComponentTool、LLMTool、GoogleSearchTool、WikipediaTool 与 MCPTool 等可插拔工具。资料来源：libs/kotaemon/kotaemon/agents/tools/__init__.py:1-25。MCPTool 通过 build_args_model 把 MCP Server 返回的 JSON Schema 转成 Pydantic 模型，并支持 parse_mcp_config / create_tools_from_config 进行批量发现。资料来源：libs/kotaemon/kotaemon/agents/tools/mcp.py:1-50。ReWOOAgent 在 _get_worker_evidence 中按计划并行调用这些工具，并在 Solver 阶段结合 zero_shot_solver_prompt 或 few_shot_solver_prompt 汇总证据输出最终答案。资料来源：libs/kotaemon/kotaemon/agents/rewoo/agent.py:1-50、libs/kotaemon/kotaemon/agents/rewoo/prompt.py:1-50。

4.3 LLM 提供方扩展

社区多次请求增加新的 LLM 提供方（Issue #160 Gemini、Issue #392 AWS Bedrock）。LLMTool 抽象了推理接口，结合 ComponentTool 与配置层，可在不改动前端的情况下接入 OpenAI、Azure、Cohere、Ollama 等不同后端。资料来源：libs/kotaemon/kotaemon/agents/tools/__init__.py:1-25。

4.4 渲染层定制

若需要改变证据展示样式，可在 Render 类中新增静态方法并在聊天面板中调用。例如新增加 Render.code_block(text, language)，即可在 UI 中以语法高亮形式展示代码片段，而无需改动 RAG 流水线。资料来源：libs/ktem/ktem/utils/render.py:1-100。

五、常见问题与最佳实践

• Docker 镜像与平台不匹配：在 Apple Silicon 上避免使用过时镜像，优先本地安装。资料来源：README.md:1-30。
• OCR 端点未启动：OCRReader 默认指向 http://127.0.0.1:8000/v2/ai/infer/，启动前需确认服务在线。资料来源：libs/kotaemon/kotaemon/loaders/ocr_loader.py:40-70。
• 扩展 Loader 后未生效：确认新模块已加入 kotaemon/loaders/ 命名空间，并按 BaseReader 接口实现 load_data。资料来源：libs/kotaemon/kotaemon/loaders/docling_loader.py:1-50。
• 自定义 MCP 工具：使用 build_args_model 自动生成参数模型，避免手写 Pydantic。资料来源：libs/kotaemon/kotaemon/agents/tools/mcp.py:1-50。

See Also

• 项目主页与用户指南：README.md
• 开发者贡献流程：libs/kotaemon/README.md
• 文档加载器集合：libs/kotaemon/kotaemon/loaders/
• Agent 工具注册：libs/kotaemon/kotaemon/agents/tools/__init__.py
• 前端渲染工具：libs/ktem/ktem/utils/render.py

Pitfall Log / 踩坑日志

项目：Cinnamon/kotaemon

摘要：发现 12 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Windows Install fails with ImportError: cannot import name 'HfFolder' from 'huggingface_hub'。

1. 安装坑 · 来源证据：Windows Install fails with ImportError: cannot import name 'HfFolder' from 'huggingface_hub'

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows Install fails with ImportError: cannot import name 'HfFolder' from 'huggingface_hub'
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/833 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：Sanitize PaddleOCR table HTML before storage and UI render

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Sanitize PaddleOCR table HTML before storage and UI render
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/834 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -e GRADIO_SERVER_NAME=0.0.0.0 -e GRADIO_SERVER_PORT=7860 -v ./ktem_app_data:/app/ktem_app_data -p 7860:7860 -it --rm ghcr.io/cinnamon/kotaemon:main-full
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -e GRADIO_SERVER_NAME=0.0.0.0 -e GRADIO_SERVER_PORT=7860 -v ./ktem_app_data:/app/ktem_app_data -p 7860:7860 -it --rm ghcr.io/cinnamon/kotaemon:main-full
• 证据：identity.distribution | https://github.com/Cinnamon/kotaemon | docker run -e GRADIO_SERVER_NAME=0.0.0.0 -e GRADIO_SERVER_PORT=7860 -v ./ktem_app_data:/app/ktem_app_data -p 7860:7860 -it --rm ghcr.io/cinnamon/kotaemon:main-full

4. 安装坑 · 来源证据：[BUG] it give no quickstart !

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] it give no quickstart !
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/839 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：[DOCS] README references missing `scripts/run_uv.sh` (uv installation path)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[DOCS] README references missing scripts/run_uv.sh (uv installation path)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/821 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Cinnamon/kotaemon | no_demo; severity=medium

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

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

10. 安全/权限坑 · 来源证据：[BUG] i requested security bug, please check !!!!!

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] i requested security bug, please check !!!!!
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Cinnamon/kotaemon/issues/841 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

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

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