ai-office-example
AGENTS.md0 starsChanged 23 days agoApache-2.0View on GitHub
本文件适用于本仓库及其生成的企业项目。先遵守当前环境更高优先级指令;子目录若存在更具体的 AGENTS.md,再结合其约束执行。本文是源码协作入口,员工实际使用技能仍以 技能入口 为准,不能假设所有 AI 工具都会自动读取本文件。 本仓库是企业智能办公基座模板:每家企业独立部署服务端,企业内部多名员工、多台设备共享服务;员工通过 AI 工具加载技能,调用 CLI/SDK 或受控 MCP 完成操作。 开始前确认工作目录、Git 状态、任务授权及目标服务/实例。阅读现有变更,保留与任务无关的工作;不能因为发现旧进程、容器或目录就停止、覆盖或删除它们。只要求讨论或审查时,不修改、部署或提交。 历史验收记录不代表当前环境已通过;文档与代码冲突时先核对真实实现和测试,明确差异后同步修订,不能只改描述使检查显得通过。 依赖方向由 scripts/check_architecture.py 核查。业务模块不反向依赖 application 或传输入口;通用层不依赖业务/基础设施/传输层。新增入口必须复用服务端权限、审计和操作注册,不能建立旁路。 Agent分支范围更新(2026-10-25):用户已明确要求服务端和员工端都支持AI,整体升级为智能体基座。 采用共享运行时、员工端SDK适配、服务端原应用异步适配及外部HTTP/MCP接入;具体设计及真实完成状态见总体方案和执行计划。服务端Agent和Web助手已实现;全局侧栏/持久会话见工作区计划,须维护服务端历史、本人有效权限指纹和单会话串行,不允许浏览器上传模型历史或自批。未来增加项目级数据范围或安全维度时,必须同时扩展Access.authorization_fingerprint与历史可见性,不能仅改前端筛选。运行配置、单进程约束与验收边界见运行指南,不能将可选依赖安装当成能力已上线。客户端和模型都不直连数据库;模型调用不得替代原权限、版本、幂等和审计。 FastAPI 请求链路保持异步:复用现有异步数据库、HTTP 和生命周期管理,不在事件循环执行阻塞 I/O 或重计算;必要的阻塞操作应明确隔离并验证取消、超时和资源释放。不能跨并发任务共享同一个有状态数据库会话。 公开产品标识集中在根目录 template.toml,具体字段以 配置文档 和生成器校验为准。修改后运行: 生成的 product.json、CLI 入口、身份主题、契约产品信息和 template-state.json 不分别手改。业务模型、业务码仍来自实际注册表,不能用品牌配置修改协议。 目标必须不存在;生成器导出已提交源码,允许本轮公开模板配置变更,但不接受其他未提交源码混入。生成后按 README 初始化独立 Git 仓库。
- Reads credentials
In this repositoryOne other file it gives its agents.
- office-skillsSkill
The file
Files
AI 协作与接手指南
本文件适用于本仓库及其生成的企业项目。先遵守当前环境更高优先级指令;子目录若存在更具体的 AGENTS.md,再结合其约束执行。本文是源码协作入口,员工实际使用技能仍以 技能入口 为准,不能假设所有 AI 工具都会自动读取本文件。
1. 先确认正在做什么
本仓库是企业智能办公基座模板:每家企业独立部署服务端,企业内部多名员工、多台设备共享服务;员工通过 AI 工具加载技能,调用 CLI/SDK 或受控 MCP 完成操作。
- 开发模板:修改可复用基座、测试和模板生成逻辑,不能加入客户资料、业务字段或专属指标。
- 生成企业项目:从模板创建独立目录,设置公开品牌,再实现该企业扩展;不要把修改回写为模板默认业务。
- 部署服务器:使用服务器安装入口,管理数据库、身份服务、网关和应用;不能把服务器凭证分发给员工。
- 安装/使用员工客户端:使用员工交付包和安装结果,不需要 Docker、数据库账号或服务器源码。
开始前确认工作目录、Git 状态、任务授权及目标服务/实例。阅读现有变更,保留与任务无关的工作;不能因为发现旧进程、容器或目录就停止、覆盖或删除它们。只要求讨论或审查时,不修改、部署或提交。
2. 按任务读取,避免盲目遍历
| 任务 | 优先阅读 |
| 了解定位、能力和限制 | README.md、架构 |
| 设置品牌/创建新企业 | 配置边界、template.toml、scripts/new_project.py、scripts/configure_template.py |
| 服务端/员工部署 | INSTALL.md、对应安装脚本及其帮助 |
| 开发、检查、活体验收 | CONTRIBUTING.md、验收记录与边界 |
| 登录/认证主题体验 | 登录体验研究;Keycloak主题不在Jinja页面目录内,品牌生成文件不手改,认证状态独立验收 |
| 工作台 UI 逐页设计与经验 | 设计与复核指南、当前重构账本;先判断常驻信息与按需详情,再选组件,不能以共享换肤代替逐页任务复核 |
| 控制台与助手整体体验升级 | 整体UI方案及阶段清单、tests/ui-pages.json;局部通过不能代替全部阶段完成 |
| Agent前端选型/CopilotKit示例研究 | 路线与证据核查;含产品范围、模型配置前置、交互数据流及阶段门槛;仍为研究草案,不代表已接入AG-UI或新前端 |
| 模型协议与管理员配置 | 三协议与文件格式、管理闭环复核方案、管理操作与恢复;协议、保存、应用与供应商可用分别验收;托管模式需迁移、独立秘密和允许出口 |
| 追溯模板来源与实现 | 来源、实现记录 |
| 全仓架构与 Web 复核结论 | 双维度审查记录;含被推翻的原判断、证据分级与未验范围,不要照抄历史报告定性 |
| 以 deepseek-harness 为范本的对比与优化建议 | DSH 对比审查;含可移植机制、明确不抄的部分与执行顺序 |
| 通过 AI 操作真实服务 | SKILL.md、RULES.md,再按情境读 references |
历史验收记录不代表当前环境已通过;文档与代码冲突时先核对真实实现和测试,明确差异后同步修订,不能只改描述使检查显得通过。
3. 架构与目录职责
| 路径 | 职责与约束 |
| office-data-service/app/common/ | 通用基础与产品元信息,不承载业务编排 |
| office-data-service/app/modules/ | access 身份与权限、data 容器与版本记录、query 受控查询、agent 本人任务与决定记录;保持模块边界 |
| office-data-service/app/application/ | 应用操作注册与编排 |
| office-data-service/app/infrastructure/ | 数据库、身份服务、配置等适配 |
| office-data-service/app/entrypoints/ | HTTP、MCP、Web、CLI 入口,复用应用能力,不复制授权与业务规则 |
| office-data-service/migrations/ | Alembic 数据结构演进;升级已有库不能仅修改建表模型 |
| clients/python/ | office-client 发行包、office_client SDK 与可配置命令名的 CLI |
| office-skills/ | AI 使用规则、能力入口和按需参考;复用 SDK/CLI,不另造认证 |
| packages/api-contracts/ | office-api-contracts 独立契约库;使用中立发行名/导入名并保留许可来源 |
| contracts/ | 从真实模型/注册表导出的契约快照 |
| deploy/ | 服务器安装、数据库初始化、身份主题与容器部署 |
| installers/client/ | 员工安装入口,支持脚本和 AI 引导安装 |
| scripts/、tests/ | 开发工具、生成与检查脚本、回归及隔离活体验收 |
依赖方向由 scripts/check_architecture.py 核查。业务模块不反向依赖 application 或传输入口;通用层不依赖业务/基础设施/传输层。新增入口必须复用服务端权限、审计和操作注册,不能建立旁路。
Agent分支范围更新(2026-10-25):用户已明确要求服务端和员工端都支持AI,整体升级为智能体基座。 采用共享运行时、员工端SDK适配、服务端原应用异步适配及外部HTTP/MCP接入;具体设计及真实完成状态见总体方案和执行计划。服务端Agent和Web助手已实现;全局侧栏/持久会话见工作区计划,须维护服务端历史、本人有效权限指纹和单会话串行,不允许浏览器上传模型历史或自批。未来增加项目级数据范围或安全维度时,必须同时扩展Access.authorization_fingerprint与历史可见性,不能仅改前端筛选。运行配置、单进程约束与验收边界见运行指南,不能将可选依赖安装当成能力已上线。客户端和模型都不直连数据库;模型调用不得替代原权限、版本、幂等和审计。
FastAPI 请求链路保持异步:复用现有异步数据库、HTTP 和生命周期管理,不在事件循环执行阻塞 I/O 或重计算;必要的阻塞操作应明确隔离并验证取消、超时和资源释放。不能跨并发任务共享同一个有状态数据库会话。
4. 配置的唯一来源与身份稳定性
公开产品标识集中在根目录 template.toml,具体字段以 配置文档 和生成器校验为准。修改后运行:
python3 scripts/configure_template.py
python3 scripts/configure_template.py --check生成的 product.json、CLI 入口、身份主题、契约产品信息和 template-state.json 不分别手改。业务模型、业务码仍来自实际注册表,不能用品牌配置修改协议。
创建新企业优先使用:
python3 scripts/new_project.py --output /path/to/new-enterprise目标必须不存在;生成器导出已提交源码,允许本轮公开模板配置变更,但不接受其他未提交源码混入。生成后按 README 初始化独立 Git 仓库。
- deploy/.env 管理实例地址、端口等运行配置;密码另存受限秘密文件/安全后端,不能合并进 template.toml。
- 发行包名、Python 导入名、内部 realm/scope、数据库账号、权限码和 API 路径是稳定协议边界,不随品牌全局替换。
- OAuth 客户端与本机凭证命名空间由配置派生。已有运行足迹时,配置工具会阻断原地换身份;不得删除足迹以绕过保护,迁址、换身份和升级需单独设计迁移。
- 当前支持文字品牌与主色,不能宣称已支持任意 Logo/favicon。
5. 数据、权限与接口不可破坏的约束
- project 是通用数据容器,不等于现成 CRM。字段定义有修订版本,同名字段不保证同义;不自动把跨容器字段合并为业务事实。
- 候选提交不等于业务确认;确认版本冻结,更正生成新版本并重新确认,历史保留。不得直接覆盖已确认事实。
- 角色、权限集、权限项组合灵活配置,服务端每次请求核验;不能靠前端隐藏按钮、固定角色名称或旧令牌中的权限替代实时授权。基础员工能力不等于管理员能力。
- 查询、分页、导出、批量与多维聚合沿用现有模型和预算。覆盖不完整、缺数、部分成功和截断必须可见,不把首屏称为全部、不把部分聚合称为全量。
- 统一响应、业务码、分页与批量结果复用契约库和注册模型;更新后导出契约,不在新路由另造包装或手改生成指纹。HTTP 状态与业务结果均应准确。
- 写入、权限调整和账号操作复用预览、版本检查、幂等与审计机制。预览摘要不证明真人已确认;重试前核对实际状态,不能盲目重放可能已成功的写入。
- 数字由程序计算,AI 不编造结果和原因;外部模型处理前脱敏,保留来源与确认状态。向量扩展可用不代表知识检索、嵌入模型和 RAG 已实现。
6. 安装与真实操作
服务器和员工电脑是两个独立环境,不能以本机同时具备源码、Docker 和管理员权限作为交付前提。
- 服务器按 INSTALL.md 使用 deploy/install.sh;初始化结构、迁移、数据库权限和必要身份配置均应由安装链路完成。不得预设对方有旧数据库或手工补表。
- HTTPS 是默认正式路径;局域网 HTTP 仅在明确选择演示模式时使用,不能删警告将其描述成正式生产方案。
- 员工包使用 setup.sh/setup.ps1,按
.office/installation.json的 cli 与 cli_args 调用,不能猜全局命令名。服务地址缺失时询问管理员/用户,先检查连接;不从员工电脑 IP 推断服务器地址。 - 浏览器 PKCE 的 127.0.0.1 回调是员工同机回调,不是服务端部署地址。登录、首次改密及系统钥匙串确认由本人完成;AI 不读取 first-login.txt、密码、令牌或授权回调。
- 当前可信 MCP 已有身份时复用其上下文;MCP 与 CLI 不默认共享凭证。具体操作遵守 office-skills/RULES.md。
- 安装成功、技能被宿主发现、用户授权成功、业务操作成功是不同验收项,逐项提供真实证据。企微等通知通过获准宿主连接器发送,不引入 webhook 密钥回退。
源码开发所需的隔离依赖操作可按已授权任务执行;安装/升级宿主全局 CLI、技能或修改 AI 工具配置须遵守技能规则的本次明确授权要求。不要把源码修改授权扩展为真实账号、业务数据、发布或外发授权。
7. 开发与验证顺序
开发环境为 Python 3.13/3.14,使用 uv 工作区和已锁定依赖:
uv sync --frozen先理解目标完整链路,再做最小内聚变更。新增能力先判断现有字段定义、权限组合或查询是否足够;真正新增规则再扩展模块。跨入口能力复用应用层,跨技能能力确认复用需求后提取,不创建大量空模块或复制整套认证。
按影响选择有意义的验证,完整命令见 CONTRIBUTING.md:
- 文档:核验链接、路径、命令和实现描述,不为纯文字变更重跑全部活体场景。
- Python:相关回归、Ruff 格式/静态检查及类型检查;变更公共链路时扩大回归。
- 架构/能力入口/技能:对应 architecture、capability coverage、skills 检查。
- 契约:运行 scripts/export_contracts.py 生成,再以
--check核查;不要仅更新快照逃避行为测试。 - 产品配置:配置一致性检查,并验证自定义命令/身份/主题,不能只测默认品牌。
- 数据迁移、权限、认证、容器和 UI:在独立实例验证完整及失败链路;会影响用户流程时检查浏览器实际交互。
live 测试可能写数据库、创建账号或改变授权,只能指向专用测试实例。不要直接运行未知测试命令到在用服务;不要占用既有端口、删除非本次创建的卷或读取用户凭证。完整操作步骤与环境变量见 CONTRIBUTING.md。
报告区分静态检查、隔离测试、真实服务、人工授权和真实 AI 宿主证据。配置了 CI 不等于远程 CI 已成功;macOS 成功不等于 Windows 已验收;没有验证的能力明确说明限制。
8. 提交与交付
- 中文优先:新增注释、文档和用户可见信息使用清晰中文;代码符号遵循既有风格。
- 提交使用
type(scope): 中文说明,例如docs(agents): 完善模板接手指南。提交前核对差异和暂存清单,只含本任务成果。 - 不提交/复制运行数据、账号资料、.env、秘密、日志、缓存、虚拟环境、绝对本机路径或构建制品。新增企业项目不能携带原客户历史和数据库。
- 发布包由 scripts/prepare_release.py 等现有入口生成,依据 INSTALL.md 校验版本、来源和校验和。源码或说明更新后,旧制品不会自动更新,不得混称同一交付版本已经同步。
- 新建远程、推送、打标签、发布、修改运行中实例或外发仓库材料须有对应明确授权;默认不自动公开。
- 每批实现、故障根因或关键结论变化后及时同步文档:可复用约束更新 AGENTS.md/专题指南,操作顺序更新 docs/OPERATIONS.md,逐次事实与失败证据更新对应账本;新结论替代旧结论时明确标记,不把一次验收固化为长期状态。沿用本轮已有提交授权及时提交,只暂存本任务文件。
- 完成后说明改了什么、验证了什么、未验证什么,以及是否影响现有部署。文档记录真实实现与边界,不承诺“覆盖一切”或“绝无故障”。
常用操作与发版流程(必读)
详细顺序、实际命令和失败边界见 常用操作与发版手册。涉及以下任务时按对应章节读取,不凭对话记忆或脚本默认参数操作:
| 任务 | 执行顺序 |
| 日常修改 | 核对仓库/分支与已有修改 → 相关门禁 → 文档同步 → 明确文件提交;受保护 main 走 PR |
| 可选Agent变更 | 先读AGENT_PLAN与AGENT_OPERATIONS;共享引擎及三协议HTTP回归/内部桥/隔离PG/浏览器;会话变更额外检查test_agent_conversations_postgres及test_assistant_workspace_browser,普通与Agent镜像分别核验;新版本同步两份锁文件和Agent模块版本 |
| 模型、业务码、数据库变更 | 真实模型/注册表 → 生成并审核契约 → 配套迁移与兼容验证,不手改生成指纹 |
| 发版准备 | 确定版本/范围 → 同步 VERSION、工作区包、锁文件、OpenAPI 与发布说明 → 最终源码提交及 CI |
| 候选构建 | 显式传当前版本 Tag 参数与新输出目录 → 核对两个 manifest 的 SHA → 摘要、许可与隔离安装验收 |
| 正式发布 | 核对最终 main SHA → 重建同源候选 → 附注 Tag → Release 草稿及审核资产 → 获准正式发布 → 下载复核 |
| 新环境与升级 | 服务器/PC 分开;新装读 INSTALL,升级先核验实例、备份恢复及迁移方案,再验证完整链路 |
| 排障/回退 | 保留现场和证据,核对已成功阶段,不盲目重试写入;应用回滚不等于数据库降级 |
- 发布候选、Tag、Release、镜像、实例升级和全局 CLI/技能更新是不同授权与验收项;已有明确覆盖的授权可复用,但不自动扩大范围。
- 候选流程不要求提前创建 Tag;当前工作流不靠 Tag push 自动发布。镜像发布与企业部署分离,不能把 CI 通过称为 CD 已完成。
- prepare_release.py 的默认版本不代表当前版本;从 VERSION 读取并显式传
--tag。已发布版本不移 Tag、不覆盖资产,来源 SHA 改变就重新构建。 - 本机开发/恢复辅助命令可能写入或创建实例,不能作为只读诊断直接对在用客户服务执行;凭证、回调及备份不进入日志、对话或 Git。
- 模板使用 office-api-contracts;公开前核验全历史、来源与许可。镜像发布还要求 ENABLE_IMAGE_RELEASE 显式开启。不得把企业资料或旧来源历史合并回来。
正式发布验收补充
- 发版需执行
scripts/verify_release.py <候选目录> --tag <版本Tag> --commit <目标SHA>;下载后的资产也用同一入口复核,不能只看上传成功。该入口仅用标准库,核对固定资产清单、来源、SHA和归档边界。 - 模板源码包保留 CI、测试和开发脚本以支持二次开发;运行镜像、员工包和技能包按各自职责裁剪,不含开发环境、实例配置、缓存或内部记录。不要把完整源码包当运行安装目录。
- image-release.yml 必须从 main 手动触发并传入已存在的附注 Tag;Tag 提交须等于本轮 main SHA。生成 linux/amd64 与 linux/arm64 镜像,标记版本与 SHA,并附 OCI 来源、SBOM 和 provenance。
- 镜像首次创建通常是私有;源码公开不证明镜像公开。独立核验包可见性、匿名拉取、平台、镜像内版本/来源及隔离容器运行。GitHub 网页登录或二次验证由本人处理,不索取密码,不用未公开接口绕过设置。
- 镜像发布环境已有明确发布授权时可由维护者按平台允许的审核路径继续;不删除审批保护来省略审核。未完成平台审核、匿名拉取或真实运行时,不声明镜像发布验收完成。
- 助手交互修改须同时核对原生工作台表单处理器:已preventDefault的组件提交不能二次导航;局域网HTTP不能依赖randomUUID或Clipboard安全上下文能力。草稿仅按会话保存在页面内存;Markdown保持固定本地解析器、允许列表DOM与许可证,禁止innerHTML及模型图片/嵌入。
- 浏览器验收以页面就绪及具体可见元素/操作结果为依据,不以全局 networkidle 代替业务断言;会话期限探针应独立计时,区分闲置失效、最长寿命与多设备隔离。短周期探针只作用于隔离恢复实例,不修改真实用户策略。
- UI确认页必须展示实际目标与提交字段;额外读取资料须核对版本,隐藏字段只作查询线索。保持原摘要/版本/幂等参数,不以客户端显示信息取代服务端核验。
- 助手桌面并排为非模态,窄屏全覆盖应隔离背景与循环焦点;尺寸变化和关闭须恢复原状态,共享Dialog/Popover仍负责各自焦点。任务详情与侧栏复用预览摘要,完整服务器预览与无JS阅读不能删除。
- 页面定位由web/navigation.py集中维护;新页面要验证无JS位置栏及所属导航。单页列表无需翻页或跳转,但每页数量与总数保留。UI独立审阅问题与验收边界持续记录于docs/UI_REVIEW_REMEDIATION.md。
- 站内真正离页须复用OfficeUI.confirmNavigation核对助手草稿,不依赖宿主可能隐藏的beforeunload提示;刷新/关页仍保留原生保护。原生select picker打开时Esc/Tab先交由浏览器,不穿透关闭父浮层;增强采用能力检测,保持触摸与无JS回退。
- 实例内网地址失效时,先核对网卡与安装公开配置;不得伪造旧IP或只改监听。内置PG、同端口HTTP演示迁址可用deploy/relocate.sh,按docs/INSTANCE_RELOCATION.md预检、备份、停写及验证;旧客户端需更新公开地址并本人重新登录。其他迁移范围不能套用此入口。
跨环境发版与验收经验(持续维护)
本节记录可复用规则,不记录“当前已通过”的长期结论。每轮先读取VERSION、实际分支/HEAD、远端Tag/Release和工作流;历史证据见对应docs/RELEASE_READINESS_<版本>.md,不能把旧版本测试数量或本机状态当成本轮结果。
- 版本同步以程序清单为准:读取prepare_release.py的PROJECTS;当前为根项目及四个工作区的五份pyproject。同步本地包间的精确版本约束、Agent模块版本、根和Agent独立锁文件、真实模型导出的OpenAPI及生成的template-state.json。只改产品版本时审核锁文件差异,不顺带升级第三方依赖。版本保护测试从VERSION取值;历史兼容夹具可固定旧版,但不能全局替换历史记录。
- 不绕过实例保护:配置生成器因runtime足迹拒绝写入时,不删足迹、不改身份、不手改生成状态。仅版本元数据更新可在隔离源码副本运行原生成器,审核输出仅含预期版本差异后回填源码,并执行--check;存在品牌、身份或运行配置差异则按迁移方案另行处理。
- 验收分层且保留失败证据:分别核对普通服务、可选Agent、数据库迁移、UI与安装包。合成身份/模型、隔离PG和真实供应商是不同证据;排除、跳过和未运行不算通过。失败先定位再修复并回归,不通过反复重跑掩盖不稳定。测试环境变量与真实命令以CONTRIBUTING及当前CI为准。
- 安装必须消费制品:普通CLI和可选Agent分别在仓库外临时环境安装候选轮包,核对模块来自安装环境、发行版本、内容指纹、帮助和依赖一致性;不能把editable源码测试当发行包证据。Agent验收目录只放脚本要求的Agent/SDK/契约三份轮包,不把全部发布资产传入三包校验器。不得因此升级全局工具或访问本人凭证。
- 来源必须闭合:所有待交付源码和文档提交后再构建。文档提交、修复或PR合并改变HEAD,旧候选仍属于旧SHA;使用新目录重建并校验两个manifest、verify_release和SHA256SUMS,不手改来源清单。记录构建SHA、安装验收SHA及未重验范围,避免为写入“最终SHA”反复改文档;最终SHA可放交付报告。
- 升级查真实迁移head:读取Alembic链,不抄旧文档中的迁移号;检查权限种子、数据保留和启用条件。全新库迁移成功不等于已有数据升级/备份恢复已验收;应用回退不等于可降级数据库。模型依赖安装、模型配置就绪和真实供应商可用也分别核验。
- 交付形态分别核验:普通镜像默认无Agent依赖;OFFICE_AGENT=1镜像另构建验收,发布工作流是否实际构建/推送该变体须查源码。依赖审计只证明查询时未发现已知漏洞。最终远端CI、跨系统矩阵、镜像公开与双架构、下载复核和运行实例更新分别报告,不互相替代。
- 保留用户操作与界面边界:登录/改密/钥匙串确认由本人完成。助手刷新使用OfficeUI.reloadPage;待HTTP回执时保护离页,已受理的后台任务不阻止导航;结束当前授权先确认草稿再发请求。验证取消无写入、成功有回执及异常不盲目重放,不把UI确认当服务端权限检查。
后续发现可复用问题时,将短规则更新到本文,命令和分支步骤更新到操作手册,逐次事实更新到验收记录;保持三者一致,不将本机IP、秘密路径、凭证或一次性测试状态固化为模板默认值。
- 面板加载/重试修改须同时测试普通抽屉与紧凑开户弹窗,覆盖403/5xx、取消重开及成功恢复;设置hidden=false不证明可见,必须检查CSS最终效果。错误提示不能直接展示整份main,失败标题不能继续显示加载中;保留有界错误和显式只读重试。
- 托管模型配置管理只面向人工HTTP/Web;不可把密钥操作注册为Agent/MCP工具。保存不等于应用,测试必须明确费用确认。新增迁移与独立根密钥/允许出口需同步部署和恢复说明;不读取旧密钥填表、不覆盖根密钥来修复解密失败。
- 原生表单的等待反馈使用共享
office:submit-approved事件,确认取消不能进入busy;不可提前禁用待序列化的输入字段。原生reset后的依赖UI在默认重置完成后再同步,不能假定微任务一定晚于reset;密码不纳入草稿快照。设置页布局使用容器查询,兼容助手并排,保留无JS与减少动态回退。 - 托管模型出口默认public;旧非空白名单未写策略保留allowlist。保存不发网络请求,实际调用必须使用受控transport逐请求解析、校验全部IP并固定连接,保留Host/SNI/证书校验;员工Agent及文件模式另有原边界。测试只用固定合成提示,不要求业务外发许可;启用仍要求。测试结果必须绑定不可变修订且持久化,重启中断不自动重试,撤权不能抹掉已发生的结果。
- 原生多提交按钮须保留submitter的formaction与专属确认文案;Enter默认无费用保存。共享等待事件携带实际按钮,不能把所有按钮同时改成同一阶段文案。
- 模型HTTP传输预算与业务输出预算独立;托管出口在SDK读取/解析前限制原始及解压后字节,错误体也受限。有界解压不得依赖无硬上限flush,未知压缩不直接交SDK解码。合成探针响应额外收紧至64KiB。
- 模型测试收尾必须覆盖开始提交、网络、输出校验与结果事务;请求取消不能丢失已知结果,也不能释放后立即重复计费。收尾独立任务需持有、观察和等待,并有时限;恢复排除真实活跃ID,不重发模型。DB故障只能报告回执未知,不能宣称调用未发生。
- 双变体交付:
OFFICE_AGENT=0/1与镜像引用在建库前统一解析;文件/环境冲突不可静默覆盖,未设置与显式0不能混淆。普通与Agent镜像分别构建、运行、记录来源;发布矩阵须分离标签/摘要/证明,不能因工作流存在就声称远端已发布。 - 模型恢复必须配套数据库与独立加密根密钥;隔离dump/restore验证活动修订、未应用草稿、缺失/错误密钥降级及普通功能,不能覆盖真实根密钥来修复。隔离同集群恢复不等于跨机整实例灾备验收。
- 模型DNS默认支持统一auto兼容,不要求业务人员逐供应商维护清单;可信解析器由运维统一设置。保留正常系统解析及已授权私网目标,不对私有解析结果做公共兜底;限定域名只属显式高级模式,旧配置兼容保持原语义。不把DoH当作绕过地址校验。DNS与模型响应都须有界、可取消、关闭资源;新增错误分类同步输出枚举和导出的契约。修复网络不代表模型有效,历史测试不重写,不自动重复计费调用。
- Web Cookie必须按受信public_url派生实例命名空间(含端口),涵盖登录、再次认证、退出和授权终止;不从请求Host生成,不清理其他实例Cookie。重启仍结束内存会话,统一提供本站恢复入口,不放宽PKCE/浏览器绑定或回放旧回调。Cookie命名隔离不能当作同主机恶意服务的安全边界。
- 连接探针预算与普通数据库操作预算分开;页面说明有效测试时限,保留独立收尾及费用确认。网关参数用结构化header/query,秘密经独立凭证通道;无密钥模式不读宿主密钥、不发占位认证。服务契约与独立Agent保持校验一致并有对照回归;禁止为了复用将可选Agent依赖引入普通服务。内网HTTP模型须独立明确授权,不套用企业服务HTTP演示许可。
- 模型目录与当前输入测试不以保存为前提,但只能由人工管理入口调用,不能注册成Agent/MCP工具。目录需有页数、ID数量、字节和总时限边界,截断与无目录手填通路必须可见。临时测试沿用同一收尾/恢复组件,revision=null且请求去重;不可自动绑定到保存修订或重发收费请求。
- 密钥显隐输入使用data-sensitive等稳定标记,脏表单快照不能只按type=password排除。保留密钥且更换目标时明确确认沿用;不把占位星号当密钥,不向浏览器回填原值。保存并启用分阶段失败要准确报告,不把保存成功说成全失败。
- 会话流式复用共享运行时observe、任务内progress及同源SSE;展示seq不改审批version。SSE重连仅回读已有任务,每次核验身份和权限;断线不取消任务,不重放写入。订阅代次必须隔离迟到事件,关闭和BackgroundTask释放幂等,失权清空旧内容。
- 模型连接测试与正式任务必须使用相同stream_output配置;不支持流式时由管理员显式关闭,失败不自动降级重发。ThinkingPart/签名不是可直接公开的摘要,禁止透传。UI增量更新需保留选区、焦点及阅读位置;完整门禁增加test_agent_progress_postgres、test_assistant_progress_browser和流式/非流式test_assistant_browser_postgres。
- 进度DOM标记在初始空正文和终态时保持稳定,只隐藏/清空内容,不删除后续querySelector依赖的标记;浏览器须覆盖空→有内容→终态→再次同步并捕获pageerror。模型目录调用成功不能当业务查询成功。模型事件消费不能等待进度落库,观察采用有界最新槽、单任务保存及终态/取消清理;参数为空须区分供应商原始结构与SDK解析时序。只读/预览操作使用
read_*/prepare_*具名工具,参数不合规返回结构化提示而非终止整轮;执行工具、网络异常与未知回执不得自动重试。模型出口的域名解析失败须与模型协议错误分开报告。只读工具必须全部常驻(按页面隐藏会导致模型不搜索而循环超限);变更预览可按明确意图预载,其余用内置search_tools发现,搜索只影响可见性,不替代服务端权限。完整排障、工具装载与验收步骤见第 9 节。 - Agent流式驱动使用公开的逐节点接口,完整消费ModelRequestNode后才进入工具节点;普通/流式及审批恢复共用累计预算与每次模型请求前的身份核验。真实供应商原始参数完整但SDK校验为空时,检查事件消费和节点推进顺序,不能通过猜参数、自动重试或默认关闭流式掩盖。临时诊断只存结构元信息,验收后移除,最终须在无诊断注入的实例复验。
9. 智能助手对话失败排障与工具装载(2026-10-29)
本节记录一次真实故障的根因、修复和验收方法;新环境遇到“处理记录 N 项后失败”“工具参数格式不正确”“页面报 null.hidden”时先照此排查。
9.1 症状 → 根因 → 修复
| 症状 | 根因 | 修复 |
| 前端 Cannot set properties of null (setting hidden) | 终态时删除 data-progress-text 标记,后续重绘仍查询该节点 | 保留标记,只隐藏并清空;回归覆盖“空正文→增量→终态→再次同步”并捕获 pageerror(tests/test_assistant_progress_browser.py) |
| 进度显示“1 项已完成”后整轮失败、参数为空 | 进度写库同步 await 观察端,阻塞模型事件流消费 | Progress 改为单工作任务 + 单一最新待保存槽;终态 flush,取消时清理(clients/agent/src/office_agent/progress.py) |
| 流式与非流式结果不一致、工具未执行 | agent.run(event_stream_handler=...) 与节点推进时序 | 使用公开 Agent.iter() + node.stream(run.ctx),完整消费 ModelRequestNode 后再进入工具节点 |
| 模型先查身份、再发“空参数”调用 | 通用工具 read_office(operation, arguments) 依赖模型拼参数;该模型收到一次纠错仍重复空参数 | 20 个只读操作拆成 read_ 前缀具名工具,9 个变更拆成 prepare_ 前缀;参数不合规返回结构化 invalid_arguments,不抛异常终止整轮 |
| 预览时整轮崩溃 | 工具内部非业务异常(如把 change 传成纯文本触发 AttributeError)未被兜住 | 工具异常转结构化结果并记录类型;预览失败明确“未执行任何变更”;预览工具说明写明对象结构 |
| 模型域名解析失败却显示“模型或工具执行失败” | 出口异常被当作未知异常 | 捕获 ModelEgressError,按 dns/policy 输出明确提示,请求未发出、未自动重试 |
| 按页面隐藏只读工具后预算超限 | 模型不调用搜索,反复查核心工具 | 只读工具全部常驻;仅变更预览延迟加载;该激进方案已回退 |
9.2 工具装载策略(clients/agent/src/office_agent/toolsets.py)
- 只读组 core/data/access/account(20 个 read_ 工具)每次全部可见,不按页面裁剪,保证任意页面都能查询。
- 变更组 data_write/access_write/account_write(9 个 prepare_ 工具)默认延迟加载;提示词出现“新建、创建、上报、提交、确认、更正、归档”等意图时预载对应组。
- 未预载时使用 Pydantic AI 内置 ToolSearch 能力:不支持原生 tool search 的供应商会得到本地 search_tools;自定义策略支持中文同义词(“待认领身份”“客户端授权”等)。
- execute_write 始终可见,仍须外部真人批准;工具可见性只影响上下文,权限、版本、幂等和审计全部由服务端逐次核验。
- 参考:Anthropic Advanced tool use(常驻 3–5 个高频工具、其余按需发现)、OpenAI Tool search(defer_loading、命名空间≤10)。不要把“隐藏只读工具”当作省 token 手段。
9.3 真实服务验收步骤
静态与单元门禁:
uv run --project clients/agent --frozen pytest clients/agent/tests -q uv run --extra agent --frozen pytest -m 'not live' -q uv run mypy office-data-service/app clients/python/src clients/agent/src --check-untyped-defs uv run ruff check clients/agent/src clients/agent/tests构建可选 Agent 镜像并更新实例:
docker build --build-arg OFFICE_AGENT=1 -f deploy/Dockerfile -t office-conversation:<tag> . # 修改 runtime/<实例>/compose.json 中 service/setup 的 image,再: docker compose -f runtime/<实例>/compose.json up -d --no-deps service curl -s -o /dev/null -w '%{http_code}\n' <public_url>/health/ready同步更新实例 installation.json 的 image/commit;核对容器内 office_agent/runtime.py、toolsets.py 与仓库源码 sha256 一致。
运行态证据(数据库只读):
docker compose -f runtime/<实例>/compose.json exec -T postgres psql -U postgres -d office -Atc \ "SELECT created_at,status,result->'usage',progress->'steps' FROM office.agent_run ORDER BY created_at DESC LIMIT 3;" docker compose -f runtime/<实例>/compose.json logs --since 10m service | rg 'OfficeAgent/(failed|validate|egress|cause)'completed + steps 含预期操作 + 无 validate/egress 错误,才算真实链路通过;requests=0 的失败先查出口与容器重启。
- 建议提示词(覆盖查询、跨组、越界、预览): “我具备的权限”“查询可访问的数据容器并说明覆盖范围,不要修改”“查询待认领身份,最多 5 条”“列出服务路径和系统信息”“预览新建项目 X,只预览不执行”。预览后必须核对业务表未变化、未产生写入。
业务数据不变校验(只读):
SELECT jsonb_build_object('count', count(*), 'digest', md5(coalesce(string_agg(md5(row_to_json(t)::text), '' ORDER BY md5(row_to_json(t)::text)), ''))) FROM office.<table> t;对 project / project_creation / project_schema / record / record_confirmation 验收前后逐表比对。浏览器侧检查“完成后再同步会话状态”无页面错误、控制台无应用报错。
9.4 常见误修
- 不要用 prepare 返回 None 隐藏工具:该工具会变成“未知工具”,模型无法恢复,整轮直接失败。
- 不要依赖“让模型补参数”的纠错:弱模型会重复空参数;应以具名工具 + 结构化参数提示解决。
- 不要向用户直接展示未知异常类型或模型响应正文;日志只记类型、代码位置与白名单工具名。
- 不要为了省 token 默认关闭流式;流式与非流式必须使用同一配置,失败不自动降级重发。
- 实测收益:只读常驻方案约降 11%–17% token、耗时约 6.5–10 秒;若未来接入更多 MCP 工具,再做按角色/意图分组,并以“查询不失败”为前置门槛。
9.5 第二阶段(暂不实施)与当前取舍
- 当前选择:只读常驻、写入按需。 20 个 read_ 工具全部可见;9 个 prepare_ 工具按意图预载(新建/创建/上报/提交/确认/更正/归档等),未命中时用内置 search_tools 发现。这是可靠性与成本之间更稳的平衡:按页面隐藏只读工具时,真实模型不调用搜索而是重复核心查询,最终预算超限,该方案已回退。
- 触发条件(满足任一才推进第二阶段): ① 接入更多 MCP 数据源、工具数量明显增长(经验阈值:工具总数超过约 40,或工具 schema 明显超过 1 万 token);② 现有分组仍出现明显选错工具或延迟;③ 业务需要按角色/页面强约束可见能力。
- 第二阶段方案:按角色/意图分组 + 搜索发现。 常驻 3–5 个高频核心工具,其余按组延迟加载;分组建议不超过 10 个工具(OpenAI Tool search 建议),组名与描述要可检索;可用 Pydantic AI ToolSearch(无原生支持的供应商走本地 search_tools)、OpenAI tool search 或 Anthropic Tool Search。
- 权限边界不变: 分组只影响上下文可见性,不替代服务端权限;不要硬编码角色名称,按权限/页面意图映射分组,并随权限变更实时生效。
- 进入第二阶段的门槛: 跨组查询成功率不低于当前;token 与延迟有实测下降;不存在因隐藏工具导致的未知工具或预算超限回归;先在隔离实例影子运行,再切换在用实例。
- 当前状态: 第二阶段仅记录、未实施。任何实施前先复测工具 schema 的实际 token 与真实查询成功率,不以理论收益替代实测。
10. 工作台 UI 经验维护
具体模式与反例见设计与复核指南,本轮结果见重构账本。
- 仪表盘先展示摘要;角色、权限长表按需查看。可点击统计卡使用单一整卡入口,保留键盘和无JS回退;统计明确集合范围与截断。
- 弹窗、抽屉和完整页按任务复杂度选择;组合后验证真实下一步与焦点。行操作增强不能隐藏弹窗中的入口,提示气泡不能遮挡其他控件。
- 完整助手可见性不能写成侧栏打开偏好;布局使用共享变量。只读文案、风险提示与按钮一样核对真实权限和状态。
- 关键结论必须二次复核:定位源码之外检查真实坐标、点击、恢复或回执;保留首轮失败、跳过和未验范围。不要只重复同一检查后提高结论强度。
- 分页授权选择仅操作本页可编辑项,跨页保留与撤销须独立验证;筛选标签仅展示页面实际支持且已提交的条件,移除时重置页码并保留范围,不另造查询状态。
- 页面标题语义与视觉字号分开;变更h1/h2须同步抽屉标题提取、焦点恢复和活体脚本。自动刷新复用OfficeUI.reloadPage,不绕过草稿与待回执保护。
- 展开组件按帮助/操作/元信息/长内容分类:帮助用明确入口,业务动作放操作区,短版本信息直接显示;高级筛选需外显已应用状态。无JS回退details不等于可见accordion,不能机械替换。
- 全站设计审查须把页面目录、动态状态和独立身份主题分开验收,记录自动扫描规则及人工复核范围。移动导航的Esc先交给账号菜单/模态/原生picker;关闭后焦点不得落入隐藏背景。多列表格优先复用可聚焦局部滚动,手机权限卡片的连续编码仍须换行;辅助追踪号和编码也核对文字对比度。本轮证据与未验状态见全站设计审阅。
- 登录认证与业务人员开通分开:不得将首次登录默认授予角色、已开户人员再认领或非受管绑定自动接管凭证作为UI优化。外部身份仍以受信issuer/subject核对;列表总数来自服务端分页,不以首屏条数代替。方案及边界见docs/IDENTITY_ONBOARDING_REVIEW.md。
- 共享弹窗中的预览POST须使用现有原生预览提交通路(data-native-submit),不能套用要求写入回执的异步保存处理器;浏览器覆盖预览、取消零写入和最终确认。单一主要流程动作可用data-keep-label保留文字,不一律压成更多图标;按实际对话框名称验收。
- 员工日常开通仅保留新建与搜索关联;不因后台能力存在就恢复手动绑定/待认领Web入口。开户与关联共用角色选择组件,默认普通员工;新角色复用完整配置页,刷新/搜索保留草稿与选择,截断显式提示。首次开通role_ids缺省或null使用内置employee角色,显式非空列表保持选择,空列表422;外部绑定/认领assign_default_role仅允许true。角色权限可调整,登录、启用和重启不补回撤权,不回填存量人员。兼容与运维边界见docs/IDENTITY_ONBOARDING_REVIEW.md。
- 按需导入的表单组件须从共享外壳提供幂等初始化,不能仅放在目标页面scripts块;工作区仍不执行响应脚本。开户角色验收同时覆盖完整页与工作区加载、失败重试和选择保留。关联预览校验失败须按账号隔离恢复资料,不把403或写入未知状态转成可重试表单。
- 动态角色选项刷新须分别保留当前选择与原生表单重置基线(defaultSelected);服务端错误恢复的初始角色不能在搜索后丢失,当前/初始角色不在结果中时仍需保留。浏览器回归覆盖普通默认、错误恢复及空搜索结果,不以刷新后当前值正确替代重置验证。
- 新增模板片段或同目录脚本须同步tests/ui-pages.json并运行完整性检查。账号闭环分层验收:临时真实Keycloak管理端口、正式迁移PG联合执行、浏览器交互各自提供证据;合成Principal及手动驱动执行器不能证明真实OIDC登录/再次认证或后台调度。使用CONTRIBUTING中的隔离入口,不复用会修改现有人员授权的live夹具。
- 导航收缩须共用布局宽度变量,桌面偏好与移动菜单独立;文字保留可访问名称,复用共享Tooltip并验证焦点/Esc/账号菜单裁切/助手并排/存储异常及无JS回退。身份主题对齐以真实父主题计算样式和几何为准,磁盘缓存刷新后再验收,不能只检查源码CSS。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

