PrivateGPT Workbench 的 AI 编码代理约定ui/AGENTS.md如何约束 Codex 等代理安全修改单文件演示 UI【免费下载链接】privateGPTComplete API layer for private AI applications on local models: RAG, skills, tools, MCP, text-to-sql, and more. Works with any OpenAI-compatible inference server.项目地址: https://gitcode.com/GitHub_Trending/pr/privateGPT本文以 ui/AGENTS.md 为核心逐条解读 PrivateGPT 仓库中用于规范 Codex 及其他 OpenAI 风格编码代理在./ui目录下工作流的约定文件并结合 ui/README.md、ui/docs/SOURCE_OF_TRUTH.md、ui/docs/PRD.md、ui/docs/STYLE_GUIDE.md 与 ui/index.html 等真实文件说明每条规则的落地方式。读完本文你将掌握一套可直接复用的“AI 代理 单文件前端”协作模式强制阅读顺序、变更范围边界、文档同步纪律以及一条可复制的node内联脚本校验命令。一、背景ui/ 是 PrivateGPT 的轻量演示层AGENTS.md 是它的代理入口PrivateGPT 是一个面向本地模型的完整 API 层覆盖 RAG、skills、tools、MCP、text-to-Sql 等能力可对接任意 OpenAI 兼容的推理服务。在此之上./ui目录中的PrivateGPT Workbench是一个轻量级静态演示 UI它把 PrivateGPT 的 API 能力文档问答、工具调用、代码执行等变成可直观体验的产品界面但刻意保持为“轻演示器而非主产品”。ui/docs/PRD.md 明确写道This UI should remain a lightweight demonstrator, not the main product. It now lives inside the PrivateGPT repository under./uiand must not become a heavy frontend application or a maintenance burden.正因如此ui/的组织方式极为克制——运行时实现全部收敛在单个文件里其余全部是文档与参考资料。ui/README.md 给出的目录地图如下文件职责ui/index.html唯一的运行时实现文件全文件约 7974 行内联全部 HTML/CSS/JSui/AGENTS.mdCodex / OpenAI 风格代理的工作流约定ui/CLAUDE.mdClaude Code 的工作流约定ui/docs/PRD.md产品行为与信息架构需求ui/docs/STYLE_GUIDE.md视觉与交互方向ui/docs/SOURCE_OF_TRUTH.md权威路径、API 契约与文档所有权ui/references/供风格指南使用的视觉参考图ui/AGENTS.md 的标题是 “Codex Instructions”开篇一句话点明服务对象This file is for Codex and other OpenAI-style coding agents working in./ui.它的结构只有三部分Read First强制阅读顺序、Scope变更范围边界、Codex-Specific Notes执行纪律。下面逐节展开并说明每条规则在仓库中如何被真实文件支撑。二、Read First代理动手前的强制阅读清单ui/AGENTS.md 要求代理在“改变行为、UI 或 API 接线之前”按固定顺序先读以下五个文件README.mddocs/SOURCE_OF_TRUTH.mddocs/PRD.mddocs/STYLE_GUIDE.mdindex.html转换为仓库根相对路径即 ui/README.md、ui/docs/SOURCE_OF_TRUTH.md、ui/docs/PRD.md、ui/docs/STYLE_GUIDE.md、ui/index.html。这个顺序并非随意排列它体现了一条“从地图到实现”的信息漏斗README.md 提供目录地图。如上表所示它先让代理知道每个文件管什么避免把产品规则误写入运行时文件、或把参考图混进实现目录。SOURCE_OF_TRUTH.md 定义文档所有权。ui/docs/SOURCE_OF_TRUTH.md 用一节 “Working Rules” 明确划分产品需求归docs/PRD.md视觉规则归docs/STYLE_GUIDE.md代理专属规则归AGENTS.md和CLAUDE.md参考图归references/运行时代码归index.html。它同时指出 API 契约的权威来源是 Fern 生成的 fern/openapi/openapi.json并特别强调“Do not maintain a duplicated UI-local OpenAPI snapshot”——即 UI 层不得维护第二份 OpenAPI 快照。PRD.md 描述产品行为。ui/docs/PRD.md约 999 行列举了 PrivateGPT 的能力清单Chat/messages API、文件摄取、带引用检索、Text-to-SQL、CSV 沙箱分析、Web 搜索与抓取、MCP、Skills、自定义工具、Embeddings 与底层原语并列出 Workbench 依赖的关键端点如POST /v1/messages、GET /v1/models、POST /v1/artifacts/ingest、POST /v1/primitives/search、POST /v1/tools/database-query等同时要求实现必须以 Fern 生成的 OpenAPI 中ChatBody、MessageInput、ToolSpecBody、ContextFilter、FileArtifact、SqlDatabaseArtifact、McpServerConfig等 Schema 为准PRD 中的示例仅作示意。STYLE_GUIDE.md 约束视觉语言。ui/docs/STYLE_GUIDE.md约 599 行规定深色氛围化工作区风格深海军蓝/炭色底、细噪点纹理、毛玻璃面板、蓝橙紫渐变点缀并声明 ui/references/ 下的四张参考图如primary-chat-layout.png、search-overlay.png、chat-tools-composer.png、context-knowledge-base.png分别对应主聊天布局、搜索弹层、输入区与知识库面板的视觉基准还要求 PrivateGPT Logo 以内联 SVG 方式直接嵌入index.html使页面运行时不依赖外部 Logo 资源。index.html 才是实现本体。代理最后才读它因为前四份文档已经回答了“要做什么、做成什么样、契约是什么”最后一步才是对照现有代码。从源码看ui/index.html 的script块自第 3936 行起状态持久化键为STORAGE_KEY privategpt-workbench-state-v1API 基地址的默认逻辑是window.location.origin null如file://直接打开时回落到http://127.0.0.1:8080否则使用当前 origin见 ui/index.html。这解释了演示 UI 既可以同源部署在 PrivateGPT 服务后面也可以作为静态文件直接打开并指向本地 8080 端口。三、Scope变更的边界规则ui/AGENTS.md 的 “Scope” 一节给出四条边界其本质是把“低维护成本”这一 PRD 级目标翻译成代理可执行的动作Keep the app as a simple static demo—— 保持应用是一个简单的静态演示不允许代理顺手引入构建工具链、模块化拆分或重型框架。这与 PRD 中 “must not become a heavy frontend application or a maintenance burden” 直接对应。Keepindex.htmlas the only runtime implementation file unless the user explicitly asks——index.html保持为唯一运行时实现文件除非用户明确要求不同结构。ui/docs/SOURCE_OF_TRUTH.md 在 “Runtime Implementation” 一节同样声明../index.html即 ui/index.html是 Workbench 演示的唯一运行时实现文件两份文档互为印证。Treatdocs/SOURCE_OF_TRUTH.mdas the canonical pointer to API contract paths and documentation ownership—— 把 ui/docs/SOURCE_OF_TRUTH.md 视为 API 契约路径与文档所有权的权威指针。也就是说代理在“某条规则应该写在哪份文档、某个 API 路径以什么为准”这类问题上不再自行判断而是以该文件为准契约指向 fern/openapi/openapi.json文档归属按 “Working Rules” 划分。Update the relevant docs indocs/whenever behavior, visuals, persistence, security posture, or API request/response handling changes—— 一旦行为、视觉、持久化、安全姿态或 API 请求/响应处理发生变化必须在同一次变更中更新docs/下相应文档。ui/docs/SOURCE_OF_TRUTH.md 末尾重复了这条规则且 ui/README.md 的 “Working Rules” 也以 “Keep docs and implementation aligned” 呼应三处一致说明这是ui/模块最核心的纪律。值得注意的是ui/docs/SOURCE_OF_TRUTH.md 还专设 “Key Implementation Notes” 一节记录那些“光读index.html看不出来”的实现事实例如Collection 名集中存放在 Settings 的state.context.documents.defaultCollection中Appearance 覆写通过applyAppearance()驱动的 CSS 自定义属性生效代码执行开启时必须把chat.id作为container字段随ChatBody发送以复用同一沙箱会话文件上传走POST /v1/files?scope_id{chat.id}下载走GET /v1/files/{file_id}/content?scope_id{chat.id}。这类“非显而易见的实现注记”正是 Read First 清单中第二份文件的实际价值所在——它把散落在近 8000 行单文件代码中的隐性约定提炼成代理可快速检索的文字。四、Codex-Specific Notes执行纪律ui/AGENTS.md 的 “Codex-Specific Notes” 针对代理执行过程定下三条纪律Follow the validation steps documented inREADME.mdanddocs/SOURCE_OF_TRUTH.md—— 遵循 ui/README.md 与 ui/docs/SOURCE_OF_TRUTH.md 中记载的校验步骤而不是自创校验方式。If implementation and docs disagree, fix the disagreement in the same change—— 如果发现实现与文档不一致必须在同一次变更中修掉这种不一致不允许“先改代码、文档以后再补”。When finishing work, summarize what changed, what validation ran, and any known limitations—— 完成工作时必须总结改了什么、跑了哪些校验、存在哪些已知限制。这三条与 “Scope” 第 4 条共同构成了一个闭环文档是契约 → 契约变化必须随代码同步 → 不一致必须当场修复 → 交付时主动披露校验情况与局限。校验命令README 中的一行 node 脚本AGENTS.md 要求遵循 README 中的校验步骤该步骤即 ui/README.md 给出的这条命令在仓库根目录执行node -e const fsrequire(fs); const htmlfs.readFileSync(./ui/index.html,utf8); const mhtml.match(/script([\s\S]*)\/script/); if(!m) throw new Error(script tag not found); new Function(m[1]); console.log(script ok)这条命令的作用是把./ui/index.html中第一个script块的完整内容用正则提取出来交给new Function()做一次语法解析若找不到 script 标签则抛错解析通过则输出script ok。它不启动浏览器、不访问网络是一条零依赖的“内联脚本语法门禁”恰好匹配“单文件运行时”的结构整个应用的 JS 都在一个 script 标签里校验它即可拦截最常见的回归——JS 语法错误。这也解释了为什么单文件结构反而是优点校验目标明确、无构建步骤、代理改动后可立即自检。五、AGENTS.md 与 CLAUDE.md同一契约的两个入口ui/目录同时维护了第二份代理约定文件 ui/CLAUDE.md服务对象是 Claude CodeSee README.md, docs/SOURCE_OF_TRUTH.md, docs/PRD.md, and docs/STYLE_GUIDE.md before editingindex.html.两份文件的分工可以从源码结构看得很清楚核心规则保持静态单文件、以 SOURCE_OF_TRUTH 为权威指针、行为/视觉/持久化/安全/API 处理变化时同步文档在两份文件中保持一致差异只在“入口习惯”——AGENTS.md用编号列表给出五份必读文件含最后的index.htmlCLAUDE.md则用 Claude Code 的file引用语法压缩成一句话并且多出一条代理专属提示“Use the shared docs above as the source of truth instead of duplicating product or design rules here”以共享文档为准不要把产品/设计规则复制进代理指令文件。这种“规则集中在共享文档、代理文件只保留入口与专属纪律”的做法避免了多份代理文件各自演化后互相矛盾。六、设计启示这套约定的可复用要点把 ui/AGENTS.md 放到整个ui/目录的背景下看它示范了一套适合“AI 代理参与维护的静态前端”的工程约束可归纳为五点单一运行时文件 单一契约来源。实现只有 ui/index.html 一个文件API 契约只认 fern/openapi/openapi.json 一份且明确禁止 UI 本地快照。代理的决策空间被压缩到最小幻觉与漂移的余地也最小。固定的阅读顺序代替模糊的“先看文档”。Read First 清单把“理解项目”拆成确定性的五个动作顺序从目录地图README到所有权定义SOURCE_OF_TRUTH再到需求PRD、视觉STYLE_GUIDE、最后才触碰代码index.html。文档所有权显式化。“Working Rules” 逐条规定哪类内容住哪个文件代理改任何一类内容时都能唯一确定落点。同变更同步纪律。“实现与文档不一致时在同一变更中修复”把一致性从口头要求变成验收项配合 “Key Implementation Notes” 记录隐性实现事实文档始终能跟上近 8000 行单文件代码的演化。可执行的轻量校验。一行node -e命令即可完成内联脚本语法门禁与交付时“说明改了什么、跑了什么校验、有哪些局限”的总结要求配套形成最小但完整的验证闭环。七、小结ui/AGENTS.md 全文不长但它与 ui/README.md、ui/docs/SOURCE_OF_TRUTH.md、ui/docs/PRD.md、ui/docs/STYLE_GUIDE.md 一起构成了 PrivateGPT Workbench 这套“代理工作流”的完整契约五步强制阅读顺序定义了信息获取路径四条 Scope 规则定义了变更边界三条 Codex-Specific Notes 定义了执行与交付纪律而 ui/README.md 中的一行node命令则提供了可立即复制执行的校验手段。对于任何需要在单文件静态应用中引入 AI 编码代理的团队这套“共享文档承载规则、代理文件只做入口、同变更同步文档、最小语法门禁”的模式都是值得参照的范本而阅读它的最佳入口正是按 AGENTS.md 指定的顺序从 ui/README.md 读起。【免费下载链接】privateGPTComplete API layer for private AI applications on local models: RAG, skills, tools, MCP, text-to-sql, and more. Works with any OpenAI-compatible inference server.项目地址: https://gitcode.com/GitHub_Trending/pr/privateGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考