AgenticX AGENTS.md

AGENTS.md

Brand note (2026-05-24): The Desktop app was renamed from Machi to Near. Existing references to "Machi" in plan files, conclusions, and historical docs are intentionally preserved.

Learned User Preferences

• 默认使用中文回复；技术术语可按需保留英文。
• 进行 git commit 时，提交信息必须包含 Made-with: Damon Li，并偏好按功能点分组、附结构化需求块（如 FR/NFR/AC）。每个 commit 还须标注过程元数据 trailer：Plan-Model（做 plan 用的模型）与 Impl-Model（做实施用的模型）——这不是 AI 署名（author 始终是 Damon Li），仅记录生产工具链；取值由用户提供，未提供时主动询问、禁止编造，纯实施类小改动可只写 Impl-Model。白名单 trailer 为 Plan-Id / Plan-File / Plan-Model / Impl-Model / Made-with: Damon Li，顺序自上而下，其它一律禁止。
• Plan 文档新建时必须先落盘到 .cursor/plans/pending/（未实施 backlog），命名仍为 YYYY-MM-DD-<feature-name>.plan.md；定稿后随代码一起提交，不能遗漏。开始实施前将对应 plan 移回 .cursor/plans/ 根目录（便于 Cursor plan todo UI 与 commit trailer Plan-File: .cursor/plans/<name>.plan.md 一致），再按 plan 开分支实施。plan 顶部（标题之后）应记录规划模型，如 Planned-with: <模型>，让 plan 自描述。目录分工见 .cursor/plans/pending/README.md。
• Plan 还须给出推荐实施模型（Suggested-Impl-Model）：以高性价比为首要目标，按子任务性质（后端接线/简单 API/前端视觉品味/跨栈高风险收口等）从当时可用模型清单中匹配「够用且最省」的模型——不为简单样板任务上顶配、也不用弱模型碰高回归/高风险/需审美的活；主规划宜提供一张「子规划 → 推荐模型 + 理由」表，各子规划顶部补一行 Suggested-Impl-Model: <模型>。该推荐仅为建议，最终 Impl-Model trailer 仍以实际使用为准、由用户确认。判据示例（随模型清单更新迭代，不硬绑具体型号）：Composer/Fast 档与代码专精便宜档（如 Kimi Code/GLM）适合简单 CRUD 样板与骨架；代码专精中档（如 Codex 系列）适合后端实施；强推理档（如 GPT-5.x）适合跨栈高风险收口与序列/一致性敏感改动；顶配（如 Opus 系列）留给复杂架构规划与需要视觉审美/品味的前端重塑。
• Plan 必须「Composer 2.5 可独立高质量实施」为最低门槛：无论用哪个模型规划，写出的 plan 都要确保一个中等能力的实施模型（基线以 Composer 2.5 为准）在不看本次对话上下文的前提下，仅凭 plan 就能高质量、无歧义地落地。具体要求：(1) 每个改动点必须给出精确落点——文件绝对/相对路径 + 函数/类名 + 大致行号或锚点代码片段，禁止"某处""相关逻辑"这类模糊指代；(2) 关键改动附before/after 代码意图或伪代码，说明改成什么样、为什么，而非只写"修复 X"；(3) 根因与证据链要写进 plan 正文（不依赖对话记忆），让实施者能自行判断改动是否对症；(4) 每条 FR 配可执行的 AC（含具体测试文件名、断言点、复现数据/路径），实施者据此自测；(5) 显式列出 In scope / Out of scope 与 no-scope-creep 边界，防止实施模型顺手乱改；(6) 涉及正则/数据结构/协议字段等细节直接写全，不留"按需推断"。判据：把 plan 交给 Composer 2.5 后若它需要反问"改哪个文件/改成什么样/怎么验证"，则 plan 不达标，须补细节。
• Plan 与 git commit 信息严禁出现客户信息：不得在 plan 标题/正文、Plan-Id slug、commit subject/body 中写入客户名称、客户代号、客户目录路径或可识别标识；一律用「Enterprise 交付」「客户项目」「外部招标文档本地目录」等中性表述；Plan 文件名也不得嵌入客户 slug。
• git commit / PR 信息严禁出现第三方品牌或开源对标表述：commit subject/body 与 PR 标题/正文不得写入竞品或第三方产品名、开源项目名，以及「对齐 X / 对标 X / X-style / inspired by X」等对标措辞；一律用产品内中性描述（如「紧凑附件卡片」「气泡外附件芯片」「输入区附件预览」）。内部对照、调研对话与本地笔记可保留品牌名，但不得进入对外可见的 git 历史与 PR 文案；若改动动机来自外部产品体验，commit 只写本产品行为变化，不点名来源。
• Desktop 端视觉重塑：App 命名为「Machi」，应用图标偏好《全职猎人》玛奇神韵的极客化解构——纯黑白高对比度矢量线稿（类 NousResearch 风格），仅保留至颈部的大头贴（无肩/无头巾），以高马尾和冷酷洞悉的眼神凸显“绝对理性”的高级开发者工具气质，拒绝低端二次元感或渐变色。
• 配置面板遵循关注分离：MCP 独立 tab 不混入 Provider；用户可改配置项必须提供 Desktop 设置面板 GUI；模型切换需持久化；新建或编辑分身时须能设置默认模型并真正落盘生效，点击分身或重启应用后均须按「分身 → 会话」维度回显最后选择的模型，不得退化为「未选模型」或被全局默认覆盖。MCP 市场 UX：默认（未搜索）视图仅展示官方/认证/托管精选，用户主动搜索必须返回全量结果，不得以「官方认证+托管+可安装」等条件继续过滤；已安装/已添加 MCP 在列表中须明确显示「已添加」（绿色状态点），不得仍保留「添加」按钮造成误点；安装/添加需有即时进度或状态反馈，失败/报错 toast 应靠近触发卡片就近展示，避免仅顶栏提示导致未上滚时看不到；列表内解释性长备注（如"点击工具名可启用/禁用 (灰色=已禁用…)"等）宜删除，用户会自行感知；各模型供应商列表侧栏状态点与详情区 ON/OFF 须一致且仅保留红/绿两态（禁用或未实际可调用为红，已配置且启用为绿）——「已配置」指 API 密钥或自定义 API 地址至少一项非空（留空仅用官方默认 Base 不算已配置）；无密钥的本机类供应商（如 Ollama）须填写可访问的 API 地址才算已配置；清空密钥与自定义地址时应自动视为关闭；权限确认文案需对齐 Cursor，且用户选择 Run Everything 后必须严格生效，禁止重复弹窗询问。主要操作按钮（如保存）应使用主题层 --ui-btn-primary-* 变量并按 dark/dim/light 区分，避免长期硬编码 cyan。配置面板 UX 持续以 Cherry Studio 为参照：秘钥记录与校验、模型列表管理与健康检查、@切换模型回答等交互。与防休眠、非高风险自动安装等相关的自动化/系统行为类开关宜放在独立 Automation Tab（或同级分区），不与 Skills 等能力配置混放；定时任务删除等破坏性确认宜用应用内主题化弹窗（或 Electron dialog 配应用图标），避免原生 window.confirm 的系统默认图标与样式不可控。已列入自动连接名单的 MCP（mcp.auto_connect）应在应用启动并完成主会话恢复后对当前会话自动补连并刷新开关状态，避免每次进设置手动点一遍。分身配置弹层（如 AvatarSettingsPanel）的遮罩、主容器背景与输入框/卡片背景须与全局 SettingsPanel 语义对齐（勿用半透叠色导致表单区异常发暗或与主题脱节）。分身设置面板应以右上角 ✕ 为主关闭入口（暗色主题下勿仅依赖低对比度侧向「回退」箭头）；与 ✕ 语义重复的回退按钮宜移除。「灵魂/人设」类字段宜排在基础信息区块之下，与基础设置同屏编排。
• 模型服务交互偏好：点击「从 API 获取模型」时不得自动把所有模型加入可见列表，需先弹出可搜索的选择面板，并按行提供 +/- 控制「可见/不可见」；聊天界面仅展示已标记为可见的模型。该面板视觉应与设置页一致，避免过宽或过透明。
• 多分身/群聊 UX 深度对齐微信体验：支持 @提及指定分身直接回复、未 @ 时由 Meta-Agent（产品名 Machi、显示名以 Meta 窗格为准）充当项目经理统筹/兜底；未 @ 但文本明显指向某成员职责时，路由应优先由该成员实际执行与回复，而非仅靠 Meta 口头代答。用户点名某分身时，该分身应以人类用户为主答对象，避免把主对话改成 @ 组长客套；成员在回复里 @ 其他分身时，路由应尽力让被 @ 方接续发言。群聊须默认智能路由：不强制用户显式选择「团队策略 / 编排模式」（如 SequentialOrchestrator 等枚举），编辑/新建群聊弹窗也不应保留这类硬选项；评测/路由任务无需用户加 /team 前缀，由路由器按 @ 命中与 Meta 兜底自动决策。群聊与多窗格回答须支持「中途打断 + 上下文延续追问」：用户在生成中可立即停止当前回答；紧随的新追问应基于「上一轮 query + 已生成的部分回复 + 新 query」组成的延续上下文继续作答，而非简单排队等当前回答结束。用户需要能感知分身在执行（工具调用、阻塞确认、进度类信号），避免长时间只有「正在输入」却看不到在做什么。新建群聊必须默认隐式包含 Meta-Agent；消息多选需左侧打勾，多选复制须结构化（角色+时间+内容），合并转发卡片点开需见原始历史。Session 创建参考 Cherry Studio；默认布局需视觉均衡，窄屏头像自适应。设置里「群内显示名称」参与群聊上下文标注（user_display_name）。与 Machi 单聊时顶部身份与头像不得误标为「分身」或丢失 Machi 头像；飞书桌面绑定在 avatar_id 为空时默认展示名须为 Machi（不可默认「分身」），avatarId 为空的窗格视为元智能体并走 metaAvatarUrl；助手消息若 avatarName 为空或为「分身」，应回落父级 Machi 展示名以免顶栏与气泡不一致。
• UI 交互必须即时响应（乐观 UI）：打开窗格、删除分身/群聊、切换会话都要先响应再异步回填；删除群聊后应回退到元 Agent 界面而非停留在已删除群聊；转发卡片等消息体必须自适应大小避免内容遮挡；工作区面板：自上而下为成员区 → 工作目录列表；Spawn Agent 列表迁至工作区 Tab 右侧独立列，spawn 启动后宜自动展开该列（可手动关闭）；工作目录项右键宜用自定义上下文菜单（对齐微信式展示，避免原生浏览器菜单），含删除与「在此目录打开终端」等；终端嵌入工作区面板底部（承接原底部 Spawns 区域），支持多终端 tab 与同级目录新开终端；（成员不单独 tab）；消息操作按钮（复制/引用/收藏/转发/重试/多选）应常驻显示而非仅 hover 出现，且用户消息行固定提供重试（非仅失败时才出现）；收藏结果反馈（如「已收藏过」）须贴近该条消息下方操作按钮行展示，避免仅在侧栏或会话列表远端角落弱提示；引用必须优先使用用户选区文本（不要整段带上 <think>）；多选操作必须包含删除且能持久化生效；流式回答禁止出现整段重复拼接；流式输出期间不得强制锁定滚动到底部，用户需能随时向上滚动查看已输出内容；附件上传后须在输入框上方展示预览（对齐豆包/Cherry Studio），图片显示可点击放大的缩略图；重试或复制消息时必须保留图片附件，不得退化成纯文本；工作区 @ 选文件宜插入 @file[显示名](绝对路径) 占位符，附件元数据保留 sourcePath，重试与会话 context_files 构造优先复用绝对路径；工作区目录绑定应按分身/Meta 隔离持久化：同一分身（或 Meta）下可跨其历史会话继承，跨不同分身不得自动共享或串台。输入框宜支持类微信的展开多行模式：展开时 Enter 换行，收起时 Enter 直接发送。删除所有会话后须自动新建默认 session 而非卡在「正在初始化」。分身侧栏与 Machi/群聊入口等列表选中态宜用背景层级区分，避免显眼粗白边框抢视觉。多窗格并行聊天时，各窗格的模型选择须按窗格/会话独立持久化，一侧切换模型不得误改其他窗格的模型展示或选中态；ChatPane 顶部模型 pill、/api/chat 请求与附件视觉判断等须与底部选择器一致，优先用当前窗格 pane.modelProvider/pane.modelName 派生实际请求模型，避免误用全局 activeProvider/activeModel 导致多窗格串台。历史会话面板宜支持按关键词跨会话检索（须命中消息正文，而非仅会话标题）；从结果跳转到某会话时，对话区应高亮关键词并滚动至首个命中；若命中落在默认折叠的工具调用返回文本内，应自动展开对应工具块以便可见。
• Desktop 端 Focus Mode（焦点模式 / 「灵巧模式」）：顶栏主题切换按钮左侧提供简洁入口（类 Siri 轨道）；进入后 Electron 无边框置顶透明窗口收敛为右上角 280×280 圆形语音胶囊（无聊天记录/输入框）；核心为 Machi（Meta-Agent）头像、状态音量环与小挂断钮；按住 Esc 或点挂断恢复原窗口。实时语音链路可走 OpenAI Realtime（WebRTC，SDP 经本机 agx serve 代理密钥）或豆包/火山端到端 WS（经由 Studio /ws/voice/doubao 补齐浏览器无法携带的上游 Header）；配置在「设置 → 语音」，~/.agenticx/config.yaml 新增 voice: 节 persisted。语音轮次的文本摘要写入当前元智能体会话 messages.json，metadata.source = voice-focus。Focus 模式下仍由 Meta-Agent 统一应答，不路由到分身。
• 子智能体须全链路透明（运行状态/摘要/产出/awaiting_confirm 与倒计时）；完成或失败后 Meta-Agent 要主动汇报；代码生成须有类似 Cursor 的流式呈现，等待期间不得只显示 ⏳⏳ 静态符号，应使用类豆包的动态三点动画。委派须为「真委派」：任务在分身真实 session 执行、历史与产出可追溯，禁止影子 spawn 顶替身份，启动后自动打开目标分身窗格；子智能体详情面板须有一键复制按钮。Desktop 端应支持「断点续开」：合盖/重开后优先恢复上次会话与多窗格状态，避免用户重新找上下文；关闭聊天窗格后再打开同一 Machi/分身窗格时，应回到该窗格最近使用的 session，而非默认新建会话。
• LLM <think> 推理内容必须解析为独立 ReasoningBlock：streaming 阶段 spinner + "Thinking" 标签 + 流式推理文本在同一容器内；完成后折叠为 "Thought"；禁用独立边框/白色背景/青蓝色底色——融入消息气泡（参照 Cursor 思考链 UI）。
• 用户对重复噪音提示敏感：须收敛为单次高信号、降低焦虑感；已知非视觉聊天模型下用户尝试附图时，用 Cherry 式文案「模型不支持该文件类型」等明确提示，展示在消息列表与输入区之间的主视区内水平居中（紧邻状态 chips、贴近输入区上方），采用黄色感叹号警示样式，避免缩在窗口右下角或边角弱提示；内部系统消息（如工具调用频率限制日志）对用户不可见。UI 文案区分语义：操作仅取消关联/隐藏时用「移除」，真正删除文件/数据时才用「删除」，避免引起用户不必要的担心。
• 出现线上异常时优先做根因排查和证据链，不接受拍脑袋修复；实现新需求时严禁乱改已有逻辑正确的代码（用户将此称为「严重倒退现象」）；已有 workspace rule no-scope-creep.mdc 强制约束，每次改动必须能追溯到具体需求。涉及 Enterprise 前台用户端（如 http://localhost:3000/workspace、enterprise/ 下 portal/workspace）的需求，范围必须严格限定在前台用户端代码，不能误改 desktop/ 或后台 admin-console；目标端不清时先确认。git commit 必须精准：只 git add 本次任务直接改动的文件，绝不把无关已修改文件一起提交。助手若声称已完成代码修改，应给出可核验信息（具体改动文件或关键 diff 要点），避免用户误判「仓库未变」。
• Desktop toolbar 按钮图标化规范：工作区→文件夹图标（tab 仅显示图标，hover tooltip 显示名称）、Spawns→机器人图标、历史→聊天气泡图标（不用时钟）；toolbar 按钮图标须与对应面板 header 图标一致；历史面板 active 状态须用 bg-surface-card-strong text-text-strong，与工作区/Spawns 按钮激活样式对齐；群聊模式下 toolbar 须加成员按钮，调用 cycleSidePanel(pane.id, "members")。侧边面板（工作区/Spawns/历史/群成员）收起用横线图标；顶栏关闭窗格（销毁）保留 ✕，与「收起面板」语义区分。Topbar 不展示当前分身名（avatarName），只保留展开/收起侧栏按钮。输入框「新对话」采用 Sparkles（全新对话）+ GitBranch（继承上下文）双图标按钮，tooltip 用自定义 HoverTip（约 280ms 延迟）代替原生 title，避免浏览器固有延迟；旁边下拉菜单须用 createPortal 挂到 document.body，避免被父级 overflow 裁掉表现为"点了没反应"。
• 技术笔记和博客偏好"图文并茂"风格，常落盘到飞书文档库（指定文档空间下）；本地长文草稿、交互式爬取备份可按日落盘仓库 .myblog/YYYYMMDD/ 便于归档（与飞书主库并行）；回复 GitHub Issue 时要求简约、非 AI 化、英文版。
• Skills Tab（列表与筛选）：技能列表不宜仅靠固定条数「截断」造成数量误解，应提供类 Cursor 的「Show all / 查看全部」式全量展开；按来源（如 Cursor 等预设路径）筛选时，列表结果必须与所选来源语义一致；技能安全扫描或市场安装前置校验失败时，UI 须给出可读的具体原因（命中类别或规则摘要），避免仅展示泛化「高危」。查看某技能详情时，宜在 Skills Tab 内就地展开/收起（例如双击 tab 展开当前区域、关闭时复原），避免详情面板固定挤到顶栏等位置造成布局与预期不符。全局与分身均须支持单个 skill 粒度启停：全局列表每行开关对应 ~/.agenticx/config.yaml 的 skills.disabled；分身侧在创建向导与 AvatarSettingsPanel「技能」区配置，默认继承全局可用技能，仅将显式关闭项写入分身 skills_enabled。技能列表与分身技能区的「启用」开关视觉样式宜与设置内其他开关组件一致，避免同屏多种控件语义混用。
• 设置界面（SettingsPanel）面向中文用户须全面中文化：Display→显示、Dark/Dim/Light→深色/暗灰/浅色、Permissions→权限、Ask Every Time→每次询问、Use Allowlist→白名单放行、Run Everything→全部自动执行、Computer Use→桌面操控、Agent Harness Trinity→智能体三件套。历史会话等上下文菜单（含飞书绑定、置顶相关项）亦须中文化，避免英文菜单与主界面语言不一致。表单内原生下拉（select）右侧箭头与控件右边缘宜保留适当内边距，对齐 Cherry Studio 式视觉密度。Tools（内置工具）Tab 的工具说明与分组标题须中文化；预置/内置工具分组默认宜折叠；该 Tab 应完整呈现会话可用内置工具集合，信息架构可对齐 Cherry Studio，避免仅展示文档解析子集或误导性窄标题。
• 用户档案与元智能体档案须在设置中分区块：用户档案含称呼、用户消息头像、用户偏好与风格（注入系统提示，localStorage）；**元智能体（Machi）**含 Machi 头像与 SOUL.md（全局人格），与用户偏好分区展示。userNickname/userPreference 等仍随请求 body 传后端；meta_agent.py 在系统提示末尾通过 _build_user_profile_block() 注入别称与偏好；别称在所有对话（单聊与群聊）中对 agent 均可见。产品期望用户自定义头像与 Machi/分身头像在全局头像体系统一。
• 日报/周报写作：只写架构级创新与非显而易见的技术难题才算"亮点"，不硬拔高常规工程补课或 bug 修复；/dailyreport 命令落盘于 .cursor/commands/dailyreport.md，接受口语化日期描述参数。
• Machi Desktop 主窗口宜持久化用户调整的窗口尺寸与屏幕位置，重启应用后恢复。
• 设置表单控件与耗时操作 UX 三条通用偏好：(1) 同一鉴权项（如 API Key）不要并列暴露「API Key + 环境变量名」两个输入框，保留单一输入框并配一个「测试连通性」按钮即可，对齐 Cherry Studio 的极简风格；(2) 同一设置面板顶部与底部不应重复放「保存」按钮，仅保留底部一个，顶部可保留「重置为默认」等非重复操作；(3) 耗时操作（入库/向量化/模型加载等）必须暴露真实百分比或明确阶段文字，不得长时间只有 spinner 让用户无法判断是否卡死。
• iLink/微信对话界面：助手对外展示名宜为 Machi（避免客户端默认「WeixinClawBot」等占位）；助手与用户头像宜与 Machi/用户配置一致；助手回复宜具备可读的基础 Markdown/富文本渲染。IM 侧会话列表标题忌用泛化「微信对话」「新对话」等占位；无用户实质消息的会话不宜持久化为历史条目；标题宜用首轮用户 query 的摘要或前若干字截断。外部渠道新消息写入当前绑定会话后，桌面端消息列表须即时刷新，避免依赖切换 session 后才可见。已绑定微信 IM 的 Machi 会话须在顶栏等主界面位置展示与飞书同级的「微信」可见标记，避免「已绑定但顶栏无提示」造成误判。飞书/微信的桌面绑定与解绑以历史会话右键菜单为主入口，聊天顶栏不宜再保留与右键「绑定飞书」等价的重复按钮，以免与状态标记区功能重叠、增加噪声。
• 长对话与多工具链任务：runtime.max_tool_rounds 等工具轮次上限宜在 Desktop 设置面板（如 Automation/Runtime）可视化调节并持久化到 ~/.agenticx/config.yaml，避免长期依赖用户手改 YAML 才能调大配额或跑完审计类任务。
• 定时任务（automation:*）专属聊天记录不得复制或串入元智能体（Meta）历史；重启与会话列表仍须严格按窗格 avatar_id 隔离。用户触发式定时执行宜每次新开独立 session 承载；执行所用模型与自动化关键参数宜可通过设置或自然语言在 Meta 中调整，避免「仅手改 YAML、对话侧改不动 Automation」的断层。
• 调度自动化打开 Automation 聊天窗格时，用户期望看到当次运行的新 session，不得在新 session 创建完成前向 UI 透出旧 sessionId；窗格绑定的 sessionId 一旦变更，须先清空窗格内消息再加载新会话，避免残留上一轮历史（主进程 desktop/electron/main.ts 的 AutomationScheduler / runAutomationTaskHttp 与 onSessionReady，渲染侧 desktop/src/App.tsx 的 ensureAutomationPane 等应对齐）。
• 历史会话标题（尤其中文摘要标题）在切换去其他 session 再跳回、或重启应用后，须与持久化元数据一致，不得回退为纯数字 session_id 占位。
• MCP（含 Docker 启动的 stdio 服务）在握手或 discover_tools 长时间阻塞时，设置界面应通过超时或明确失败态提示原因，避免长期停留在「连接中：握手并发现工具…」且无反馈。
• Enterprise 前后台视觉基线统一转向 vben 风格 indigo/violet primary + OKLCH tokens + 系统/亮/暗三态主题（不做 dark-only）；大视觉重构偏好「一次大 PR + 三段可验收 commit（ui-foundation → admin-revamp → portal-revamp）」，每段须独立 typecheck + build 绿后再进下一段。客户登录页/品牌区不得展示虚构或不可核实的「已服务企业」类客户名单；左侧品牌区宜松弛大气（栅格比例拉开、字号/行距/留白放大），避免密集拼贴。
• Enterprise 前台 web-portal 聊天空态偏好对齐 Kimi 式：无消息时顶栏不展示「分享会话」等二级动作，待 messages.length > 0 再出现。侧栏折叠（如窄到约 72px）时，主操作用 size="icon" 的按钮勿再叠 w-full+justify-start（易致图标不居中）；收展控制宜放在顶栏品牌行（纯图标），主导航区用纵向堆叠。
• 面向客户的技术评分项须用「业务演示 + 通用描述」语言，严守「满足得 X 分，不满足不得分」二元判定，技术档次（1/2/3 档）标注在评分项标题中，避免暴露 RS256/Blake2b/oklch() 等实现细节。起草前必须逐项回溯仓库真实完成度，坦诚区分「可现场演示 / 需小改 / 模板空壳不可演示」，不因一时好看而承诺仓库尚未落地或只有模板的能力。
• Enterprise admin-console 策略样本测试：blocked 仅在动作为 拦截（block） 时为 true；警告（warn） 仍可有 hits 但不算拦截；测试接口应合并当前表单预览（未保存的 action/payload）与库内规则，避免界面选「拦截」却仍按库里旧动作计算。动作与类型在中文界面宜展示为拦截/脱敏/警告、关键词/正则/PII，脱敏（redact） 为命中替换占位符而非等同拦截。规则迁 PG 后支持「草稿/发布 + 部门/用户级 scope」，仅已发布才进入网关快照；删除等破坏性操作必须二次确认，未发布规则的删除应为软删除（行置灰 + 显眼红色「恢复」按钮），灰色规则不可再编辑只可恢复或永久删除（再次确认后真清），避免一键清空无法回滚。聊天合规拦截 UX 须与正常模型回复视觉上明确区分（拦截原因贴近用户语义，如「检测到银行卡号 / 命中策略 pii-bank-card」），同会话后续追问应按当前请求重新评估命中，不得简单沿用上一轮拦截结论让无关问题继续被「拦截」展示。
• Markdown 代码块在聊天气泡 / 笔记渲染中须在 light / dim / dark 三态主题下都具备可读的代码主题（syntax highlighting + 适配背景），不能在浅色主题下退化为「像把代码复制到 txt 一样」的无高亮纯字；可按主题分别配 light / dark 两套代码主题以保证对比度。
• 群聊里每个分身的过程性广播（「已接收任务 / 开始处理任务 / 正在调用工具：X / 工具已完成：X」等）会被用户视为刷屏噪音，应聚合为该分身一条可折叠的进度 / 工具状态卡（与 ToolCallCard 默认折叠语义一致），仅展示最终产出与必要的打断 / 确认信号；禁止每个工具调用都独立成一条群聊气泡。
• 会话状态指示器须全链路一致：同一会话在聊天气泡（如「正在输入」）、历史会话面板 / 侧栏标签等位置的状态必须同步——不能一边显示生成中、另一边显示「已中断」；空会话或尚未发出首条用户消息的会话不应预先打上「已中断」/「失败」占位，须保持「新会话」中性态。
• 保存类操作（编辑分身、编辑群聊等）必须给出即时反馈（toast 或确认弹窗），保存失败时须保留弹窗并透出底层错误（如 HTTP 400 unknown avatar_id，参考 GitHub issue #20）以便用户与反馈渠道定位；分身 avatar_id 等 ID 体系在新建 / 编辑落库后必须立即被后续 /api/avatars、群聊编辑等接口识别，禁止出现「保存看似成功，下一次请求却 unknown avatar_id」类断层。
• 设置 / 编辑类弹层（含群聊编辑）不可整体过透明（毛玻璃需保留主体可读对比）；对话框宽高不应被异常横向拉伸，主操作（确认 / 取消）按钮位置须保持稳定，不应漂移到中间或与主按钮错位；底部「取消 / 关闭」宜与「保存」同排相邻，取消紧靠保存在左侧，避免主轴 justify/多余 spacer 将取消键单独甩到对话框中部；面向终端用户的"功能说明 / 策略文案"长段（如群聊设置里"智能对话默认……"长备注）宜删除，UI 保持干净。
• 面向终端用户/客户的 enterprise UI（admin-console、web-portal）不得在文案、tooltip、Help 信息中暴露仓库内部路径或运维实现细节（如 enterprise/.runtime/admin/policy-overrides.json、plugins/moderation-*/manifest.yaml、「启停状态落盘到 …」等），运维存储与文件结构说明只在内部文档保留；用户对 enterprise 各模块（身份权限/审计/聊天历史/Token 用量/策略规则中心）明确要求"绝对不能再 mock"，新建 / 编辑接口须真写 PG 否则明确报错，禁止「点击看似成功但不落库」的伪成功。
• admin-console 等管理界面切换子菜单时左侧导航高亮必须跟随当前路由，不应停留在前一项；长内容子页（如「角色权限」）应让侧栏在主轴上保持固定，不与主内容一起整体滚动，避免长表格把导航栏一并下推。
• 撰写客户技术实施方案 / 投标 / 管理类长文（如 OKR 设定方案、客户应答模板）时：必须自然成文，不留 AI 文风或「知识库原回答」残痕（如「主要短板」「（你直管的部门）」等隐含组织关系的称呼），逻辑须严谨可经推敲；客户文档涉及流程图 / 架构图 / 时序图时，须先落盘 md 描述（一图一文件，置于 images/ 等目录），再驱动 GPT Image 等模型作图；客户提到「移动云 / 客户云生态」（如对象存储、IDaaS）等替代方案时，方案以本地 / 自建为主线、运营商生态列为可选，不替客户拍板技术选型；安全策略 / 敏感词的行业 know-how（如「投资决策」「投资立项」）由客户分阶段提供，方案文档只预留接入位与少量示例，不预设完整关键词清单。
• IAM 部门管理 UI 偏好「能力卡片 / 小方块」式展示（一个部门一个卡片），不偏好层级表格树或仅列名称的密集列表；从某部门卡片跳转到「用户管理」时须按 dept_id 过滤展示该部门成员，不可跳到全量用户列表（曾出现「跳过去后是全量用户页」的体验回退需修复）。
• agenticx/studio/server.py 是本地后端唯一入口，其顶部 import 区块（尤其 agenticx.avatar.* 等与 create_studio_app() 初始化直接相关的导入）极其敏感、不能随意改动：曾在 2026-07-06 一次与之完全无关的附件回显修复（commit d8428b73）中，编辑器对相邻 import 段做整块替换时误删了 from agenticx.avatar.group_chat import GroupChatRegistry 这一行，导致 create_studio_app() 里 GroupChatRegistry() 抛 NameError、agx serve 启动即崩溃，Desktop 分身/历史会话/工作区全部表现为空态（数据本身完好无损，纯属这一行误删）。今后触碰该文件必须遵守：(1) 编辑 import 区或任何多行代码块时，只能精确增删目标行，禁止用"整段替换"方式覆盖相邻的无关行；改动前后要对照原文件逐行确认没有误删/误改任何跟本次需求无关的既有代码，这也是 no-scope-creep.mdc 规则在此文件上的具体落地；(2) 只要改了 server.py，提交前必须本地跑一次 agx serve --host 127.0.0.1 --port <临时端口> 冷启动验证（或等效 smoke test），确认进程不崩溃且 /api/session、/api/avatars、/api/sessions 等核心 API 返回 200，把"能正常起服务"作为该文件改动的强制验收门槛，不能只看 diff 语义正确就认为完成；(3) 如果表现是「Desktop 分身/历史/工作区全空」但用户没删过数据，第一优先级应排查 agx serve 是否存活（serve.port 对应端口是否真的在监听），而不是先怀疑数据丢失。