AGENTS.md

Fast.NET AI 编码规范

适用于本仓库全部文件。本仓库由多个独立 NuGet 模块组成；公共库的合同、模块依赖和多目标构建应与应用业务代码区分。

仓库定位与阅读入口

• Fast.NET.sln：模块与构建关系。
• src/：生产模块，包括 Runtime、IaaS、Core、Serialization、DependencyInjection、Cache、Logging、EventBus、JwtBearer、DynamicApplication、UnifyResult、SqlSugar 等能力。
• Directory.Build.props、global.json、各 .csproj：共享构建、SDK、目标框架、包元数据、XML 文档与模块引用。
• docs/ 及各模块现有说明：以实际维护位置和源码 XML 注释核对合同。
• UploadNuget.bat 是发布相关脚本，不是普通构建或验证入口。

工作原则

• 默认用简体中文沟通。简单问题直接给结论；复杂问题说明关键依据、取舍和未确认事项。
• 修改前按影响范围阅读源码、公开类型、配置、调用方、相关测试和文档；不要只凭文件名、历史聊天或示例推断合同。
• 先确认当前分支与工作区修改。保留已有未提交内容；相同文件存在重叠修改时先厘清归属，不回退他人的工作。
• 语言和框架的正式语义优先于历史写法。发现旧实现有误应说明证据并修正相关问题，但不能借“最佳实践”扩大任务。
• 以完成需求所需的合理改动为目标。可以重构有问题的内部实现，不进行无关全仓格式化、目录迁移或依赖升级。
• 跨仓库访问按本文件的明确授权及目标仓库适用规则执行；授权范围内的正常协作不重复询问。未列入范围的仓库和操作不因同属 Fast 生态而自动获得授权；实际沙箱、权限及任务中的明确限制仍需遵守。
• 新增文件放入现有职责目录。只在需求确有需要时引入模块、依赖或抽象；不自动创建总结、计划、架构报告等文件。
• 使用与任务匹配的可用 Skill，但以实际工具链和项目合同为准；不因 Skill 的偏好改换技术栈或自动安装、更新 Skill。

模块与公共 API

• 每个模块保持清晰依赖方向，不为便利引入循环引用，不把应用租户、页面或业务流程写进通用 SDK。
• API 调整同时检查程序集/包、命名空间、公开类型、方法重载、默认值、异常、序列化、配置项和扩展注册方式。
• 不因仓库内没有调用就删除公共成员；外部 NuGet 消费者同样属于合同范围。需要不兼容修改时先说明迁移与版本影响。
• 尽量使用受支持的公共扩展点，不依赖第三方未承诺的内部类型；无法避免时限定兼容范围并增加针对性验证。
• 各项目实际目标框架、语言与依赖范围以配置为准，不把最现代目标可用的 API 无条件用于所有目标。
• 条件编译尽量靠近真正的兼容边界，避免复制大段同义实现；不随意删去旧目标来让构建通过。

C# 编码与公开文档

• README 保留安装与最小完整用法；详细任务流程和 API 参考在 Fast.Docs 对应产品目录维护。摘要示例可以重复，完整合同表不在多处人工维护。

• 命名、缩进、可访问性和格式遵循 .editorconfig 与实际分析器配置；使用当前目标框架、语言版本能够支持的语法和 API。

• 局部表达保持简洁；不为形式重写为更多类型层、工厂或扩展方法。泛型约束、null 语义和资源所有权要明确。

• 公共 SDK API 使用 XML Documentation，说明摘要、非显然参数语义、返回、异常和约束；不要机械给私有成员堆完整 XML 标签。

• 成员和参数引用优先使用 <see cref="…"/>、<paramref name="…"/>；采用 <inheritdoc/> 时同时核对打包 XML 与 Fast.Docs 的解析结果，不能只凭 IDE 提示认为发布文档完整。

• docs/COMMENTING_GUIDE*.md 与本节保持一致；标点按内容是短语还是完整陈述区分，不按 XML 标签统一删除。

• 保留有价值注释并修正错误说明。

• 根据内容决定标点：名称、标题及简短描述不使用结束标点；完整行为、条件、原因和限制使用正常标点。同样适用于摘要、参数、返回、属性、XML 标签和普通注释，不按标签名称或单行/多行机械判断。

• 保持异步链路，不用 .Result、.Wait() 或无必要 Task.Run 包装 I/O；async void 仅用于确实要求的事件合同。

• 支持取消的路径按合同传播 CancellationToken，不要吞掉取消或把它记录成普通业务成功。异常保留必要上下文与原始堆栈。

• 是否使用 ConfigureAwait 取决于库/宿主上下文和实际约定，不执行机械全仓替换。

• 不随意修改共享 Nullable、语言版本或目标框架来消除局部诊断；兼容第三方限制时使用最小范围且有解释的处理。

生命周期、并发与 I/O

• 先确认 DI 注册方式、生命周期和所有权；不将 scoped 服务长期保存在 singleton 或静态字段中，不为获得服务临时构造第二个根容器。
• 资源由拥有者释放；不要提前释放调用者传入的流、连接或服务，也不要遗漏本模块创建的可释放资源。
• 静态缓存、注册表和事件订阅考虑并发、重复注册、作用域及释放；不能只验证单线程首次初始化。
• 缓存键、过期、序列化和失效保留合同；不能把身份/租户相关数据在无隔离的共享缓存中混用。
• HTTP、日志、消息和任务执行保留失败、超时、取消与重试边界；副作用操作不能无条件自动重试。
• 身份与权限相关修改核对验证参数、时间边界、错误暴露和敏感信息处理；不得为让样例成功关闭安全校验。
• ORM、数据库扩展和初始化流程只做代码/SQL 分析及安全的非写入验证，不运行迁移、建库、写入或业务初始化。

构建、包与生成文件

• 调整项目结构时同步解决方案、项目引用、资源路径、包内容与构建脚本，不随意改包名或程序集身份。
• 检查 Directory.Build.props 的实际求值与导入时机；不能假定项目内较晚定义的属性在共享 props 中已经可用。
• 构建产物与 XML 文档应按目标框架和项目正确隔离，不能多个目标互相覆盖或将生成结果误作手写源码。
• 新增测试或工具项目时明确目标框架和是否可打包，检查共享包资源、版本与自动打包属性是否错误继承。
• 锁文件、包版本和目标范围按现有依赖管理方式维护，不引入平行版本源或随意批量升级。
• build、pack 与 NuGet 推送不同；不因为构建会生成本地包就自动执行上传脚本。

测试与验证

• 优先验证可观察合同：边界输入、异常、取消、序列化、DI 生命周期、并发和资源释放；不要以反射遍历或“不报错”代替有意义断言。
• 复用当前实际存在的测试设施；新增设施时让框架和运行器匹配测试目标，不为使用某个工具强制迁移生产项目。
• 对时间、HTTP、文件和外部服务使用受控替身或明确隔离资源；不访问真实业务服务，不启动带数据库初始化的应用作验收。
• 项目能编译、某个目标测试成功与全部声明目标通过是不同结论。明确实际构建和执行了哪些项目、框架与用例。
• 修改默认行为或修复缺陷时，保留相应回归证据；不随实现一起修改测试预期掩盖回归。
• 不通过关闭分析器、删目标、删断言或扩大排除范围消除失败。缺少 SDK/runtime/测试设施时记录具体限制。

常用构建入口是在仓库根执行 dotnet build Fast.NET.sln -c Release。执行前检查自定义目标及自动打包行为。测试命令应指向实际存在的测试项目/解决方案，并核对发现的用例；没有测试被执行不能记为“测试通过”。

Fast.Docs 协作与版本同步

• 对有修改目的的开发任务，已授权读取同级 Fast.Docs，并更新与本仓库实际公开包对应的文档、示例、变更说明和版本核对记录；这是正常交付的一部分，不因跨仓库再次询问。只读审查、仅建议任务或用户明确排除文档时，不自动写入，报告待同步项。
• 相对路径以本仓库 Git 根目录为基准，默认文档位置为 ../Fast.Docs，不是相对终端当前子目录。先核实仓库身份、实际路径、分支和未提交修改；worktree 或非同级布局使用已明确配置的映射，不猜测路径、不扫描无关目录。
• 写入前主动读取 Fast.Docs 根及目标目录适用的 AGENTS 规则，并定位现有产品导航、包名映射与生成流程。允许对当前包的入口、示例依赖和校验配置作必要的最小联动，不授权重做站点结构、批量升级依赖或修改其他产品文档。
• 本任务实际更新包版本，或处理已明确纳入本任务且尚未同步的版本变更时，必须核对变化并同步对应文档。公开 API、默认值、类型、行为、兼容范围或使用方式变化，即使尚未升版本，也同步相关说明；不因为该规则自行决定升版。
• 根据实际差异和可确定的上次核对版本检查指南、API、示例、迁移说明及版本要求。没有文档正文变化时，不制造无意义改写；完成必要核对与验证后再更新已有的文档审阅记录，按实际包分别维护，不能只对齐字符串。
• NuGet 多包仓库按真实受影响的 PackageId、有效版本和模块记录同步，不假定所有项目同版本。版本来自实际项目及共享构建配置，不新增一套平行版本源。
• 目标版本尚未发布时，不把 Fast.Docs 的运行依赖盲目改成无法安装的版本。使用已授权的可追溯本地产物或现有预发布验证方式；源码只读核对不隐含在其他仓库构建或写入的授权，不能静默回退旧包冒充新版本验证。
• 执行与改动相关的现有文档构建、链接、API/示例及版本检查；不得删除检查、自动接受公共 API 基线变化或把未验证状态写成已通过。最终分别报告代码版本、文档同步和验证结果。
• Fast.Docs 缺失、映射不明、存在重叠未提交修改或环境/沙箱阻止访问时，说明具体阻塞和待同步内容，继续其他可安全完成的工作；不擅自创建替代文档仓库、覆写内容、放宽权限或绕过审批。此授权不包括提交、推送、发布及部署。

Git 提交说明

• 完成已授权的仓库或包版本更新后，在最终答复中输出可直接复制的推荐 Git 提交说明；有实际文档改动的 Fast.Docs 另给一份，即使文档站自身版本未变。仅提出版本建议、没有实际版本调整时，不得描述成已经更新。
• 根据本任务实际差异、版本变化及 git status、暂存/未暂存差异生成说明；区分既有修改，不将不属于本任务的内容混入提交建议。不要为生成说明执行暂存、取消暂存或提交操作。
• 默认使用 type(scope): 中文摘要；feat、fix、refactor、docs、chore 按实际主要改动选择。单纯版本调整使用 chore(release)；版本更新伴随功能或修复时，不要只写“更新版本”而省略实质变化。
• 每个独立仓库分别给出一个纯文本代码块，标题为首行；必要的正文与标题之间空一行。仓库名与解释放在代码块外，方便复制到 Git 图形客户端。
• 只描述真实完成的改动。未发布不写“已发布”，未运行验证不写“测试通过”；阻塞或未完成事项在代码块外单独说明。没有有效变更的仓库不生成空提交建议。
• 推荐提交说明不代表执行提交。未经另行明确授权，不执行 git add、commit、push、tag 或发布；用户要求命令时再输出供其复制的命令，并按真实差异限定文件范围。

安全边界

• .editorconfig、许可证全文和历史版权头的批量调整作为独立明确任务处理，不作为普通优化或格式化的附带动作。仓库描述、Topics、首页和组织介绍默认单独交付建议，不直接改远程设置。

• 不输出、保存或提交密码、Token、Secret、API Key、私钥及带凭据的地址。示例使用明确占位符；诊断输出须脱敏。

• 不直接执行数据库写入、结构修改、自动迁移或数据初始化；需要时仅生成 SQL 或方案供人工审核，测试环境也不自动建库或写库。

• 未经明确授权，不执行 git commit、push、reset --hard、clean、rebase 或历史重写，不发布 npm/NuGet 包，不修改远程服务。

• 不使用危险批量删除命令，不覆盖未提交修改。执行构建、测试、安装或工程脚本前，检查其自定义目标和生命周期是否包含发布、危险清理或外部写入。

• 共享 AI 规则与个人会话、缓存、凭据分开管理。不要为了隐藏正式代码或文档变更扩大 .gitignore；不擅自修改全局工具配置、Hook、MCP 或权限。

交付要求

说明模块改动、公共合同与兼容性影响、实际验证命令及结果、未验证范围。文档与 XML 注释只同步相关真实变化，不新增重复报告或未经验证的性能结论。