KunBuddy 未登录时默认进入登录首页，填写平台 URL、用户名和密码即可登录，并自动更新“坤伴订阅”模型。检测到登录过期后返回首页，保留本地会话和账号地址；临时网络故障单独处理。详见 客户端登录首页。
管理员可上传 Windows EXE / macOS DMG 或应用 ZIP，客户端按当前登录平台检查新版本，下载校验后显式打开安装包；切换 URL 会替换更新来源。打包与发布步骤见 坤伴客户端发布。
坤伴订阅会话可自动同步为“人员 → 我的工作区 → 会话”中的原始 Markdown：每个会话一个文件，后续追加、失败重试，superadmin 可查看所有人的会话目录。上传不调用 LLM，不自动解析或编译，后续整理由用户手动触发。详见 会话原文同步。
模型设置支持输入 API Key 后自动检测可用模型、补全已知上下文容量并保存；服务端保留公开元数据目录 data/models/model.json。KunBuddy 的“添加 AI 服务 → 坤伴订阅”可使用 AiAgent 地址和现有账号登录，平台模型密钥留在服务端。协议与验证边界见 模型发现与坤伴订阅。
聊天右上角「+」及右侧空面板提供「资料库」，统一查看本人已发送的上传附件与当前授权项目的文档，按更新时间排序，支持搜索、来源筛选、下载原文件和关联到聊天。HTML、Office、PDF、文本等已保存产物可自动发现，代码后缀及常见源码／构建目录不展示；上传图片显示缩略图。聊天完成、重新打开资料库或窗口恢复焦点时刷新，也可手动刷新。侧栏新增菜单暂时隐藏「侧边任务」「终端」，项目运行的日志入口继续保留。详见 聊天资料库。
聊天“项目程序运行 → 打包”先打开配置弹窗，可从当前代码库根目录逐级选择一个 .sln / .slnx、工程文件或 JSON（如 package.json），填写额外打包要求并预览提示词，再填入聊天发送。多解决方案只构建选定入口及其必要依赖，也可主动选择由 AI 自动判断入口。发送后由 AI 检查技术栈、自行构建和验证，生成 ZIP，并支持继续对话迭代。交付物统一保存在目标仓库 artifacts/aiagent-packages/，项目文档中可刷新查看并下载，聊天中的交付链接显示为下载卡片。此目录应加入目标仓库 .gitignore；提示词要求生成前验证忽略规则，排除密钥、本地配置和用户数据。是否成功以实际工具验证结果为准。
知识库默认将导入文件保存到 raw/。按需使用 Codex CLI 或平台 LLM API 整理为 Markdown 知识表示层，并使用模型检索这些知识页面，无需先创建向量索引。设置 → 知识库可切换到可选 RAG 检索；已有索引保留，重建需手动触发。详见 知识表示层与检索。
编译弹窗支持树状筛选来源、选择资料 / 项目 / 本人产物目录，并选择内置 LLM Wiki 或本人自定义技能；可通过多轮对话生成和编辑技能，保存后立即用于编译。显式产物位于所选目录的“编译产物”子目录，个人来源禁止发布到公共目录，任务重试保持目录与技能快照。详见 知识编译目标与技能。
L0/L1 编译按配置的模型窗口自动分段和归并，新任务调用次数默认 0（不限），可手动设置上限。正常中文输出不再因 UTF-8 字节数被误判超预算；生成输出沿用供应商默认限制。
右侧 KnowAgent 提供 LLM API 流式聊天、模型选择及目录工具调用，展示上下文估算用量、输入上限和压缩比例。输入区带当前目录 URI 前缀，点击 /ls、/read、/search、/status 打开目录命令弹窗；/compiler 可选择原始文件、已配置的 API 或 Codex/CLI Profile，提交 L2 → 文件摘要 → 目录 L0/L1 任务。任务配置独立保存，重试沿用原参数。浏览同目录文件保留聊天，切换目录会停止当前流并清空会话。详见 知识 Agent 流式对话。
生成产物默认按发起用户保存：资料／项目目录保留原始文件和解析正文，L0/L1 概览与摘要显示在「人员 → 我的工作区 → 摘要」，新 Wiki 草稿显示在同一工作区的「Wiki」。任务结束会刷新目录树；旧资料执行「重新解析」即可生成本人的摘要。历史公共产物保留，不自动归入某位用户。生成链路由 Services/Knowledge/KnowAgent/ 统一控制上下文预算、Unicode 分段、摘要归并和已有知识压缩，超出预算会在任务中明确失败。详情见 KnowAgent 与个人知识产物。
目录、预览和 Agent 终端之间支持拖动分隔栏调整宽度，双击恢复对应面板默认宽度，也可聚焦分隔栏后使用方向键；终端默认更宽，调整结果保存在当前浏览器。目录标题旁的「文件处理」打开状态弹窗，可查看当前可见文件的最新任务、正文解析状态、阶段和失败原因，支持搜索、预览及手动刷新，处理中自动刷新。此入口需同步更新后端资源状态接口。
目录资源支持解析后生成语义 Markdown：先保存 L2 解析正文，再通过已配置的 Codex / LLM API 生成文件摘要和目录 L1 .overview.md，从概览提取 L0 .abstract.md。在目录页查看、切换和下载 L0/L1；已有资料点击「重新解析」补建。语义生成失败仍可查看正文，任务中心可重试；相同正文复用已完成结果。此阶段不需要向量索引，详见 目录语义生成。
文档解析保留完整正文，并参考 OpenViking 按 Markdown 标题组织章节、合并短章，超长内容再按段落拆分，表格按行保护。Word／PPT／Excel／HTML 转换保留可识别的结构，PDF 转成 Markdown 后进入同一流程。章节按文档名和标题命名，在来源父目录的「解析正文」只读树中浏览和下载，原文页也有章节入口；不会固定生成 part-1.md。知识设置及 /compiler 可调整拆分开关和阈值，随任务保存快照；2048 token 的章节默认估值与模型上下文窗口无关。旧正文继续可读，重新解析后产生新结构。详见 文档转换与结构解析。
原始文件支持 DOCX 正文／表格／图片和 XLSX 工作表内容预览，无需先知识整理，也不向在线 Office 服务发送文件。旧版 DOC/XLS 通过服务器 LibreOffice 转换后预览与知识整理（需安装并设置 Knowledge__LibreOfficePath）。后台知识整理任务统一在 /task-center 任务中心查看，显示阶段、进度与状态，支持取消、失败重试和刷新后恢复状态；知识库页面保留入口链接。当前任务中心只展示 wiki_compile 知识整理任务，RAG 索引任务仍由原有索引流程管理。详见 Office 预览与知识整理任务。
/knowledge 按公司／项目展示知识库；进入后分别查看「知识」和「原始文件」，知识整理主题可跳回来源文件。原始文件中点击「解析文档」启动独立后台两阶段知识整理：先分析实体、概念与矛盾，再生成带原文证据的知识草稿；支持本地 Codex CLI 和 LLM API，统一配置位于 /settings/knowledge。短文正常需要两次模型调用，长文按完整分段处理；单个任务失败不会终止后台队列。CLI 运行在后端所在机器，沿用该机器的 Codex 登录与模型配置。
知识整理与模型检索逻辑组织在 AiAgent 后端项目的 backed/Services/Knowledge/Core/ 文件夹内，随同后端编译和部署。上传保留原始资料，RAG 索引链路改为按需使用。新知识为可核对的派生草稿，知识整理失败保留上次成功结果；服务重启中断的任务可手动重试。公司／项目目前用于目录归类，不新增权限隔离。模块、接口及验证边界见 知识库重构说明。
原型工作台支持按界面展开 HTML / PSD 产物目录，点击生成并下载桌面、平板、移动端带分组像素图层的 PSD。文字暂为栅格化图层；PSD 在浏览器生成，刷新后可重新导出。详见 PSD 导出说明。
已授权项目可在右侧“项目文档”中选择服务器目录，上传、预览、下载、删除或引用 Markdown、PDF、DOCX、XLSX、PPTX、HTML 和常见文本资料；代码后缀不会混入资料树。PDF/HTML 在当前页的受限 iframe 中打开，Office 与文本使用服务端提取内容预览，下载保留原文件。聊天回答中的这些项目文件引用也会复用右侧资料面板打开，不刷新或跳离聊天页。上传目标仅限项目的 uploads/aiagent-documents 专用目录或该项目已注册仓库内已选中的相对目录；浏览器不能传入任意服务器路径。已注册仓库内的上传、新建和删除均直接作用于真实文件，因而会显示为 Git 变更；专用上传区不纳入仓库 Git。“生成 Agent 文档”会预填当前项目的分析任务，要求 AI 在每个已注册仓库根目录实际写入 AGENT.md；代码问题会受控读取这些真实文档以定位模块和入口。预览、下载、引用和 Prompt 注入均会重新校验项目权限。Windows 服务账户的最小 NTFS 权限和验证步骤见 scripts/deploy/DEPLOYMENT.md。
面向内网开发场景的 AI 工作台：管理模型与 Git 账号、登记服务器代码库、构建知识库，并让 AI 在受限工作区中读取、修改、预览和 Git 管理看板应用。
-
聊天中粘贴或上传 Excel 工作簿／模板（
.xls、.xlt、.xlsx、.xlsm、.xlsb、.xltx、.xltm），后端直接提取工作表文本，无需安装 LibreOffice；保留中文、工作表名称、空列位置，并沿用附件权限及文本长度限制，不执行宏。复制 Excel 单元格时优先保留表格文字，避免被剪贴板附带的图片抢占。CSV 文本附件继续支持。加密或损坏的工作簿需先解密或修复；旧版 DOC 和知识库 Office 预览仍需 LibreOffice。 -
AI 打包与预览默认优先复用已验证流程：由聊天 AI 在仓库
artifacts/aiagent-workflows/保存结构化配方、打包脚本或启动模板，下次核对配置指纹和运行环境后复用。取消“优先复用已验证流程”可重新分析；打包仍构建当前源码，预览仍由后台检查就绪。此版本依赖 AI 实际执行和保存，尚无独立的免模型执行器。详见 流程复用说明。 -
聊天文件卡片：AI 保存到当前项目的 Markdown、HTML、TXT、PDF、DOCX、XLSX、PPTX 等文档链接会显示文件名和格式。已登记仓库根目录的文档无需移入 doc，兼容
/D:/...Windows 链接，生成后可刷新资料列表。点击卡片在右侧项目资料面板预览，点击「下载」保存原文件；历史消息中的链接也适用。Office 新版格式使用内容提取预览；仓库内旧版 DOC、XLS、PPT 和 RTF 支持下载，右侧提示使用本地软件打开。文件须实际存在，外部链接保持普通链接。详见 文件卡片说明。 -
交互图形：聊天 →「可视化」（默认选中「架构」），可使用当前对话、已选资料，或指定代码库目录、解决方案/工程/JSON 分析范围。AI 回复自动显示可探索的图形，支持节点说明与来源、上下游高亮、有向路径追踪、深浅画布、分组配色、节点搜索、节点拖动、画布拖动、重置布局、缩放、大图及 JSON/SVG/PNG/HTML 导出；继续对话可生成新版本，历史图随消息保留。正式图使用本地 React/SVG 画布，无新增服务依赖。详见 使用与边界。
-
Archify 固定示例已从聊天配置弹窗移除，仅保留
/archify/aiagent-demo.html作为开发参考。详见 示例集成与验证。 -
聊天可视化分为交互图形与 Mermaid 图表两类。交互图形提供五种类型：架构、工作流、时序图、数据流、生命周期。使用浅色网格、分组边界、语义形状、折线避让和自动适配窗口；时序图按消息顺序绘制生命线。AI 根据问题自动判断代码分析范围，无需手动选择；支持 Git 摘要来源，以及 JSON/SVG/PNG/HTML 导出；HTML 含可展开的节点说明、来源、关系明细和原始尺寸阅读。Mermaid 分类保留自动选择、架构图、流程图、时序图、类图、ER 图、状态图、思维导图、时间线、甘特图和 Git 分支图。详见 实现范围。
-
双层侧边栏：左侧图标切换聊天、知识中心和研发工作台，右侧显示对应模块内容。聊天列表独立占用剩余高度；保留 Ctrl / ⌘ + K 搜索、项目内新建、置顶、归档、排序及会话重命名，收起后仍可使用图标快捷入口。
-
聊天失败重试：聊天窗底部显示错误提示与逐秒更新的「20 秒后重试」按钮，可立即重试或取消自动重试。重试沿用本轮消息、附件和模型配置；再次失败重新倒计时，手动停止不会自动重试，发送新消息会取消该会话旧的倒计时。倒计时由当前浏览器管理，刷新或关闭页面后不恢复。
-
多会话工作画布：在
/work-canvas创建多个个人画布，把已有会话作为节点加入并拖拽布局；支持项目/关键词筛选、实时运行状态、会话检查器和跳回完整聊天。节点卡片可弹窗预设执行模型、配置 Agent 职责与多个手工填写的 Skill，并可直接在画布内连线，将上游节点的最近产出作为受边界保护的输入；根节点完成后会自动推进满足全部上游条件的下游节点，并保留可回溯的运行时间线、模型与失败记录。画布只引用当前用户有权访问的会话，不复制消息，也不绕过现有 Agent 并发与权限控制。 -
Codex 图片上下文：选择 Codex 本地代理后，聊天框可上传 PNG、JPEG、WebP 或 GIF 截图；后端校验文件签名并以受控
localImage输入传给原生 Codex，不会将浏览器提供的路径交给 CLI。第三方 Codex Profile 可在「设置 → 管理配置 → 第三方代理」的模型卡片上勾选「支持图片上传（原图）」，开启同一区域的「允许聊天上传图片」，点击「保存模型与图片配置」统一保存；新增 Profile 也支持。聊天直接通过 CLI 把原图交给模型，返回聊天时会自动刷新配置，也可在拦截提示中打开设置或手动刷新。界面隐藏原有 OCR 配置与测试入口，旧 Profile 不会自动开启原图。详见 Profile 原图输入。 -
模型服务配置：LLM、Embedding、Search、TTS、STT、图像与视频模型。
-
Git 账号与代码库：支持 Gitee OAuth 授权码登录（令牌仅服务端加密保存）、手工令牌连接测试、克隆、代码库登记、拉取与提交推送。
-
工作项：企业固定为
yun_kun；可在新建或导入时打开企业工作项选择器，查看任务详情和附件后关联到任意 AiAgent 项目，也可导入 OMS CSV；表格支持按项目、负责人、类型、状态和关键词筛选，并支持本地编辑任务标题、详情和关联项目。点击“处理”会将正文中的 Gitee 图片下载、验签为受控本地聊天附件，再带入对应项目的新会话。 -
AI 代码交付：
/deliveries将项目工作区修改固化为变更集，执行固定 Git 校验并生成摘要；具备代码提交权限的人员批准后，系统会再次验证工作区 SHA-256 指纹，再提交、推送并把关联任务回写为完成。审批后发生文件变化时必须重新创建和审批变更集。 -
代码库养护：工作画布下方的
/repository-maintenance支持选择项目、手动执行和定时执行；可只生成分析建议，或在独立副本内优化、编译验证并生成变更集。由有提交权限的用户逐次批准后，交付到独立maintenance/*分支。配置、接口和验收范围见 养护实施说明。 -
知识库：文档导入、分类解析、LLM API/Codex CLI 知识整理、索引、检索与聊天问答；原文件、解析正文和待审核 AI 派生物相互隔离且可追溯。
-
Agent 对话：WebSocket 优先、SSE 降级，实时显示工具调用、Token 与结果。
-
流量统计：成功完成的自有 Agent 与第三方代理轮次会写入用户隔离的 Token 账本，可按代理、模型和日期查看趋势。
Gitee OAuth 服务端配置使用 GiteeOAuth:ClientId、GiteeOAuth:ClientSecret、GiteeOAuth:RedirectUri 和 GiteeOAuth:Scopes（模板见 backed/appsettings.example.json）。生产环境建议使用部署环境变量或密钥管理器注入；RedirectUri 应填写浏览器可访问的公开地址（通常是前端域名下的 /api/v1/gitee-oauth/callback），并且必须与 Gitee 应用的回调地址完全一致。
- Codex 接管：聊天中选择项目后可勾选“Codex 接管”，后端把项目目录与问题交给本机
codex app-server，并实时返回回答、执行轨迹与文件修改完成状态。 - 可靠看板改码：Agent 先检查当前工作区与入口，再搜索、读取、基于 SHA-256 补丁写入并静态校验；不会把关联 Git 仓库作为第二个 AI 写入目标。
- Prompt 模板市场：在聊天入口下按需求、设计、开发、代码理解、测试和交付阶段发现模板；支持项目范围、变量
${field}、点赞收藏、MD 导入导出，并可将渲染结果带入新聊天会话。
以下截图记录当前工作台的主要交互页面，供产品验收、前端实现和后续交接时对照；图片不包含真实账号、令牌或业务数据。
AiAgent/
├─ backed/ # .NET 9 / Furion / SqlSugar 后端
│ ├─ Services/ # Settings、Chat、Knowledge、CodeRepository、DashboardApp 等领域服务
│ ├─ Dtos/ # API DTO
│ ├─ Entities/ # 数据实体
│ ├─ Rag/ # RAG 适配与 Python 工作脚本
│ └─ PythonWorkers/ # 文档解析与索引 Worker
├─ front/ # Next.js 16 / React 19 前端
│ ├─ app/ # App Router 页面
│ ├─ components/ # 设置、聊天、知识库、代码库、看板工作台组件
│ └─ lib/ # API 客户端与类型
├─ dashboard-templates/ # 可创建的看板模板
├─ docs/ # 架构、Agent 与实施记录
├─ handoff/ # 阶段规格与开发交接归档
├─ AGENTS.md # 面向开发者和 AI Agent 的协作规则
└─ backed/appsettings.example.json
复制配置模板并填入本机数据库与允许访问的代码根目录：
cd backed
Copy-Item appsettings.example.json appsettings.json
dotnet restore
dotnet run默认 Swagger：http://localhost:5000/swagger
cd front
npm install
npm run dev默认地址：http://localhost:3782
前端通过 Next.js rewrite 将同源 /api/* 转发到本机 127.0.0.1:5000，浏览器用当前访问地址调用前端代理，不需要配置或随网络变化修改后端 IP。前后端部署在不同机器时，才通过 NEXT_PUBLIC_AIAGENT_API_BASE_URL 显式指定后端地址。开发服务器监听 0.0.0.0，可通过内网 IP 访问；请在防火墙和 next.config.js 的开发来源白名单中配置实际网段。
Codex 本地代理支持 gpt-6.1-sol（GPT-6.1 Sol）和 gpt-6.1-terra（GPT-6.1 Terra），支持 low/medium/high/xhigh/max 推理等级；升级保留原默认模型。详见 Codex 模型策略。
选择 Codex 本地代理时，点击聊天输入框左下角的图片按钮，或在输入区按 Ctrl+V，即可附加截图。默认最多 4 张、单张最大 10 MB，支持 PNG、JPEG、WebP、GIF；未发送图片暂存于后端 data/chat_attachments，发送后的图片会迁移到按用户和会话隔离的历史目录，并随聊天记录回显。CodeBuddy 当前未验证图片输入协议，因此不能使用该功能。
后端运行账户需要能够执行 Codex CLI，且已经完成 Codex 登录。默认执行 codex app-server --stdio；若 codex 不在后端账户的 PATH 中，设置 AIAGENT_CODEX_COMMAND 为可执行文件的绝对路径，或在后端配置中设置 Codex:Command。每个已登录用户的浏览器页签会保留一个已初始化的 CLI，页签每 25 秒发送一次心跳；停止心跳超过 90 秒才回收。用户最多同时保留和运行 3 个 Codex 会话，可通过 Codex:RuntimeLeaseSeconds 与 Codex:MaxSessionsPerUser 配置。Codex:TurnIdleTimeoutSeconds（默认 300 秒）限制连续无 CLI/app-server 事件的等待，Codex:TurnTimeoutSeconds（默认 1800 秒）限制单次任务总时长；任一超时都会终止对应 CLI，下一次任务会创建新的 worker。首次使用页签仍会有一次 CLI 冷启动。聊天窗口选择“Codex 本地”后可选择执行权限：默认“完全控制”会传入 --dangerously-bypass-approvals-and-sandbox，另可切换为“工作区写入”或“只读分析”。完全控制会以后端服务账户的身份不受沙箱和逐步审批限制地执行，请只选择允许 Codex 修改的受信任项目目录。
第三方 profile 的图片 OCR 默认关闭。管理员在“第三方代理”设置中启用后，按 backed/PythonWorkers/ocr/install.ps1 为 PythonWorkers:Ocr:PythonPath 指向的环境安装 CPU PaddleOCR，并确认聊天附件根目录位于 PythonWorkers:AllowedRoots 中。OCR 结果会以图片 SHA-256、引擎与语言为键缓存在 ImageOcr:CachePath；识别失败或超时不会中断聊天。
设置中的“流量统计”会记录每次成功完成的对话，按用户、代理类型、代理标识、模型和日期聚合。当前内置 Agent 与 Codex CLI 的 Token 由本地文本估算，页面会标记为预估；后续适配器若返回原始 usage，可写入同一账本。
接口为 GET /api/v1/usage/summary?scope=me&days=365。普通用户只能读取自己的数据；具备服务端 admin 角色的账号可使用 scope=all 获取全员汇总。不要在示例配置中填写真实账号或其他敏感信息。
聊天“项目程序运行 → 配置 AI 运行”支持勾选当前项目的多个代码库，并逐级选择多个工程、解决方案或配置文件。填写页面路径、补充要求和空闲关闭时间（5–240 分钟，默认 30 分钟），填入聊天后发送。AI 检查前后端依赖、API/代理/CORS 配置及端口，提交启动清单；后端先检查后端服务就绪，再启动前端。支持可运行的 .NET 工程及现有 npm scripts（包括 Node 后端），无需预先保存运行配置。
回复中的“在新窗口测试功能”和浮窗中的“新窗口测试”会打开应用实际端口；历史 /runtime-test 链接也会在服务就绪后跳转，优先选择前端及配置的页面路径。访问地址使用当前浏览器访问 AiAgent 的 IP/域名，端口由 AI 指定，冲突时报错而不静默换号。右下角“运行进程”每 3 秒合并查询 AI 运行请求和项目托管进程，显示真实 PID、端口和状态，可关闭整组服务；其他托管进程可单独结束。请求失败会明确提示，不作为空列表显示。“管理 / 续期”保留测试管理页，可切换服务和页面路径，可见时每 10 秒续期；关闭或隐藏超过设定时间后整组关闭。直接访问应用端口和查看浮窗不续期。外网仍需防火墙/端口映射放行，自动推导 IP 不代表公网连通已验证。
启动清单与结果位于所选代码库的 artifacts/aiagent-runs/（应加入 Git 忽略）。浮窗只管理 AiAgent 运行管理器登记的项目进程，不扫描或接管其他系统进程。运行记录保存在当前后端进程内；正常关闭后端会回收服务，重启后需要重新发起运行请求。实现与验收见 聊天 AI 运行。
Windows 运行服务使用 Job Object 托管子进程，npm/dotnet 启动器先退出后仍能结束本次运行的子进程。关闭操作会核对进程退出及配置端口释放；未完成时显示原因并允许重试，不显示“已关闭”。更新后需重启 AiAgent 后端并重新发起运行，旧版本已经遗留、失去托管的进程不会自动接管。
项目可包含多个前端或后端代码库。每个代码库可在“项目与代码库”中登记多个配置文件，并选择其中哪些允许在聊天菜单中直接编辑；聊天菜单会显示这些已授权文件、单库运行和打包入口。
- AI 多工程运行与已有配置：聊天代码库“运行”进入多选配置弹窗；已有运行配置与运行 API 继续兼容，仍可启动项目内已保存的配置。
- 前端依赖安装：首次点击运行时，如对应
package.json所在目录不存在node_modules，系统会先执行npm install；克隆代码库本身不会自动安装依赖。 - 端口与进程隔离：运行配置保存入口、脚本和首选端口；后端运行使用独立构建产物目录，避免锁定 Visual Studio 的
bin/obj文件。 - 强制结束 Shell：运行菜单仅显示活跃 Shell。每一项均可“强制结束”，会终止对应进程及其子进程；依赖安装阶段同样可结束。
- 配置文件安全：聊天只能读取和保存明确勾选为“聊天可改”的文件，并在保存时使用 SHA-256 检查磁盘版本是否已变化。
看板应用从 dashboard-templates/ 复制到独立工作区。若选择已登记代码库，工作区位于：
<repository>/.aiagent-dashboard/<application-id>
看板 Agent 的安全流程：
检查工作区 → 识别入口/依赖 → 搜索 → 读取真实文件
→ SHA-256 版本保护的补丁 → 静态校验 → 刷新编辑器与预览
因此，类似“在产线趋势旁增加报废柱状图”的请求会定位真实的 ECharts 页面与样式文件，而不是猜测或新建无引用的 App.jsx。
详细设计和实施记录：
- 不提交
backed/appsettings.json、.env、backed/data/、知识库原文、索引、运行时工作区和构建产物。 - 提交前使用
backed/appsettings.example.json作为配置样例，不得在 README、Issue、日志或代码中写入真实密码、Token 或 API Key。 - 代码库访问受后端允许根目录约束；看板 Agent 只能写入当前看板工作区。
| 层 | 技术 |
|---|---|
| 后端 | .NET 9、ASP.NET Core、Furion、SqlSugarCore、Swagger |
| 前端 | Next.js 16、React 19、TypeScript、Tailwind CSS |
| AI/RAG | 可配置 LLM、Python Workers、LlamaIndex 适配 |
| 看板 | React、Vite、ECharts、受控 npm 运行时 |
KunBuddy 桌面客户端位于 client/，完整保留 Electron、React、Rust Host 与插件工具链。使用独立应用标识、数据目录和开发端口 4382；在 client 中执行 pnpm install --frozen-lockfile 后运行 Run-KunBuddy.ps1。迁移与隔离说明见 客户端移植说明。
开始改动前请阅读 AGENTS.md。其中定义了前后端契约、Agent 工具流程、编码/密钥处理和不应提交的本地内容。
- 生产、测试等受控环境首次部署时，必须通过受控配置提供
Authentication:InitialAdministratorUsername和Authentication:InitialAdministratorPassword。两者只用于创建第一个管理员；初始化口令至少 16 个字符，不提供默认值。找不到可用管理员且缺少配置时，后端会拒绝启动，不会创建可猜测账户。 - 仅本地
Development环境可省略这两个初始化配置：当数据库没有可用管理员且启动终端未重定向时，服务会一次性创建superadmin，生成 32 位随机口令并只输出到当前启动终端；口令不会写入配置、数据库明文或 HTTP 响应。该引导不适用于生产、测试等环境。 - 本地
Development环境若显式配置初始化口令，可使用恰好 6 位纯数字；其他本地口令以及生产、测试环境的口令仍至少需要 16 个字符。 - 使用环境变量注入时，对应名称为
Authentication__InitialAdministratorUsername和Authentication__InitialAdministratorPassword；初始化口令应由服务账户环境或 Secret Store 提供，不要放在命令行参数、脚本、日志或版本库中。 - 初始化成功后立即从配置文件和环境变量/Secret Store 中移除
Authentication:InitialAdministratorPassword。已有管理员或用户的密码不会因升级、重启或初始化检查而被重置；后续忘记密码时由现有管理员在管理配置中执行重置，若没有任何可用管理员则需按部署环境的人工账户恢复流程处理。 - 公开注册已关闭，
/register会返回登录页，创建新账号只能通过“设置 → 管理配置 → 用户管理”。 - 管理员可为普通用户分配一个或多个代码项目。聊天的项目选择菜单、项目偏好保存和实际聊天请求都会使用同一授权校验，用户不能通过直接调用接口绕过项目范围。
- 用户管理采用可搜索表格，可按账号或别名筛选；支持新增、编辑授权、重置密码、启用/停用账号，以及下载 Excel 导入模板并批量导入用户。停用或重置密码会使该用户所有现有登录会话失效；系统禁止停用自身和最后一个可用管理员。
- 用户可通过“设置 → 账号安全”验证当前密码并修改自己的密码；成功后会退出全部登录会话，需使用新密码重新登录。
- 管理配置提供三个卡片入口：用户管理、历史会话（只读审计）和用户流量。流量支持按日、周、月、年聚合，并提供时间范围、用户筛选与柱状趋势图。
管理员接口均位于 /api/v1/admin/*，只接受服务端根据会话识别出的管理员身份；浏览器不会提交可伪造的管理员或用户身份字段。
Codex / 第三方 Profile 聊天现默认记录基础诊断。失败消息显示执行阶段、分类错误码和诊断编号，可展开“失败详情”复制诊断信息，并通过消息下方“查看诊断日志”查看本人会话最近记录（默认 7 天）。服务器日志按同一编号关联 CLI 路径、配置目录和运行账号；不记录密钥或聊天正文。更新并重启前后端后生效，定位步骤见 Codex 运行诊断。
plugins/aiagent-remote 可通过账号密码换取 8 小时短期令牌，选择平台允许的远程 LLM 与 Codex 模型，同时由用户本机的 DeepSeek Harness 负责本地文件访问和最终修改。部署与安全边界见 DeepSeek Harness 远程插件。
目录资料上传默认启用解析（可取消勾选），或点击重新解析后进入后台队列。任务中心显示配置校验、正文 L2 解析、L0/L1 语义生成阶段及失败原因；正文保存后语义失败仍可预览正文。失败任务可重试，已完成的历史任务可重新处理以补齐语义文件。旧记录没有阶段信息，不代表已生成 L0/L1。更新代码后需重新部署前后端；不会自动重新执行历史任务。
管理配置 → 用户流量支持指定月份、自定义日期和用户／项目筛选，展示活跃会话、完成轮次、活跃天数、日均轮次及 Token 图表和用户 × 项目明细。日期按 UTC，频率包含零活动日；仅统计已记录用量的成功轮次，项目按会话当前归属。
聊天附件新增 ZIP、RAR、DLL：压缩包提取文件清单和支持的文本／文档／源码，DLL 提取静态结构及 .NET 类型与方法信息，不执行文件、不还原完整源码。每轮最多 4 个、单个最多 20 MB，详见 二进制聊天附件。