开发并维护在自己电脑上运行的研究智能体工具

## 让研究工具在用户电脑上运行，并明确不做的事 构建本地优先的研究环境：默认在用户的设备上运行，通过有文档说明的公开路径安装，以文件和版本控制保存持久状态，并在一个项目工作区中支持完整的研究循环。即使通过轻量启动器或多个界面提供访问，也要保持一个实现运行时作为权威来源。 使用提示和专门技能指导研究工作，同时由小型服务持久化、恢复和路由状态。应优化一个聚焦的核心，而不是不断扩张的平台；凡是提案会扩大运行时、公共工具或部署范围，都要明确说明不属于目标的事项。 ## 相信当前文件和实际行为，而不是记忆或旧计划 从当前检出内容中实际存在的文件开始，而不是依赖记忆或旧计划。依次阅读产品概览、文档索引、维护者架构、开发指南、与子系统匹配的最小参考资料集、实际实现和相关测试。 当来源不一致时，依次优先采用当前运行时行为和已通过的契约测试、仓库级指南、维护者权威文档以及补充性的贡献者说明。应在同一项变更中更新不准确的文档，而不是保留过时的路径、功能声明或工作流。 将计划行为和已实现行为视为不同的声明。在实现、配置、集成、文档和测试全部支持某项声明之前，不得把相应组件描述为可用。 ## 把代码贡献者的规则和工具内 AI 的规则分开 区分面向仓库贡献者的说明，以及用于约束产品内智能体的提示和技能。运行时契约可以要求使用特定公共工具或受限执行路径，但这并不意味着编辑仓库的维护者也必须受到同样限制。 每当提示、技能、命令或工具行为发生变化时，都要保留这一边界。不得把产品内的安全契约重新解释为仓库贡献规则，也不得仅因维护者拥有更广泛的本地开发工具而削弱运行时契约。 ## 每个研究项目放在一个带版本历史的文件夹里 将每个研究项目视为一个受版本控制的仓库，并为其设置一个绝对项目根目录。把所有持久研究内容保留在该根目录内，并使用分支或隔离的工作树表示不同方法，避免把项目历史拆分到互不相关的位置。 为研究简介、计划、状态、摘要、产物、基线、实验、文献、交接材料、论文稿、记忆和私有运行时状态维护明确的工作区契约。运行时缓存和日志可以位于项目外部，但不得成为研究证据的唯一副本。 项目布局发生变化时，要同时更新布局模型、持久化服务、快照、API使用方、用户界面、测试和文档。不得只迁移一个使用方，却让其他使用方继续依赖过时结构。 ## 启动程序保持简单，重启前先确认正在运行的设置 将权威研究运行时保留在一个实现层中，并让包管理器启动器成为连接该运行时和预构建界面包的轻量适配器。公开安装包应包含启动所需的文件和已构建客户端；不得依赖最终用户的安装后构建来使受支持路径正常工作。 调试或重启正在运行的安装实例之前，要检查运行中的进程、有效配置、现有进程管理器或启动器、实际运行时可执行文件，以及健康检查端点报告的主目录路径。绝不能仅根据默认目录推断当前主目录、配置或进程所有者。 使包清单、项目元数据、公开文档和界面包预期保持一致。在把打包视为完成之前，必须通过包预览或试运行确认实际交付的文件集合。 ## 让 AI 的公共工具保持少量，新增时要说明理由 把内置公共工具接口限制在少量稳定职责内：持久记忆、版本化产物和持久命令执行。版本控制行为应位于产物边界之内，命令行执行应位于执行边界之内，不要为每个子系统添加新的公共命名空间。 让提示定义工作流预期和文件系统契约，让技能提供专门的执行行为。状态服务应保持轻量；如果提示和技能契约已经能清楚表达工作流，就不要硬编码庞大的中央阶段调度器。 任何新增公共工具的提案都必须证明现有职责无法容纳它，定义其持久化和权限模型，更新所有客户端，并添加契约测试。仅仅为了方便并不足以成立。 ## 用小型清单添加新连接，全部到位前不算完成 为研究运行器、通信渠道、连接器桥接层、技能发现、受管本地工具和可选适配器使用小型注册表。与庞大的分派分支或子系统专用条件相比，应优先采用一致的注册、查找和列出接口。 只有当运行时适配器、注册表元数据、配置默认值、验证、服务及命令行集成、用户可见文档和测试全部具备时，才能把一项集成称为已经实现。缺少其中任何一层，都意味着该集成只是部分完成。 把可选适配器放在核心路径之外，并明确说明它们缺失时的状态。注册表条目应展示功能和兼容性，不得在未明示的情况下安装依赖项、访问外部服务或更改本地配置。 ## 让浏览器和命令窗口共用项目状态与功能调用接口（API） 要求浏览器和终端界面使用同一套服务API、状态快照和事件模型。API路由或事件发生变化时，要在同一项变更中更新服务、所有客户端、导航前提和契约测试。 在各界面之间保持稳定的面向项目的路由和标识符。用户界面可以采用不同布局，但不得创造独立的状态语义，也不得隐藏其他受支持界面需要观察的状态转换。 把核心通信渠道视为通用渠道和桥接模型的一种实现。不得让某个重要连接器变成单独的运行时，并拥有独有的持久化、错误处理或生命周期规则。 ## 划分从调研到写作的研究阶段，不强行排成一条直线 定义一条精简的规范化推进流程，例如探索、建立基线、形成想法、实验、分析、写作和最终定稿。应把决策视为贯穿各阶段的活动，而不是假定每项重要活动都属于单一线性阶段。 接收审计、图表准备、评审和反驳可以作为专门活动存在，但除非当前代码和提示契约确实如此规定，否则不要把它们放入默认链条。命名阶段必须与系统当前有效的锚点、状态转换和用户文档一致。 把阶段行为放在系统提示、聚焦的提示契约、提示组装和阶段技能中。避免把阶段语义分散到服务处理程序、界面代码和临时条件分支里。 ## 把面向用户的指南和面向开发者的文档分开 将面向用户的指南与维护者架构和开发资料分开。公开文档应说明当前行为；维护者文档应说明契约、扩展点和需要协调完成的变更要求。 不得把临时计划、草稿检查清单、私有路径或内部专用说明放入公开文档树。保持已链接文档的名称稳定，移除对已删除文件的引用，并在用户可见行为变化时更新所有仍受维护的译文。 如果一项变更只影响内部维护，就更新维护者权威资料，不要凭空制造面向用户的公告。文档范围应与行为影响范围一致。 ## 不把密码和个人路径放进共享文件，并保留研究记录 不得提交工作站专用的绝对路径、凭据、令牌、本地缓存、依赖项目录、临时构建输出或测试缓存。只有当打包契约明确要求时，生成的界面包才应包含在公开软件包中。 把持久实验记录、文献笔记、基线、产物和论文稿保留在项目边界内并纳入版本控制。在概括之前保存原始证据，绝不能用仅存在于界面中的状态消息替代可复现结果。 发布前检查公开文件中是否存在秘密泄露、过时文档名称、私有引用和生成文件漂移。测试全部通过也不能成为发布敏感或不可复现内容的理由。 ## 先查看现有代码，再做小范围修改 在提出新抽象之前，先检查现有实现。优先采用小而连贯的变更，而不是广泛混杂的重构；先使用最小的相关文档集，再对照代码和测试验证提案。 代码与文档不一致时，要在一项范围明确的变更中同时修正两者。不得仅因某项引用过去存在就继续保留它；在确定有效运行时、进程、配置和主目录之前，也不得重启正在运行的研究服务。 将诊断与修改分开。在更改共享状态之前，记录观察到的信号、预期行为、受影响的使用方和最小修正方案。 ## 改代码时一并更新测试和文档，不碰无关的部分 针对正在修改的子系统，更新所有直接受影响的层： - 项目布局或持久状态：布局模型、持久化服务、快照、API使用方和状态测试； - 提示或阶段技能：提示来源、组装、技能定义、镜像安装程序、行为测试和用户指南； - 记忆、产物或命令执行：实现、公共边界、服务测试和契约文档； - 研究运行器：适配器、注册表、配置默认值、验证、服务及命令行集成、指南和测试； - 渠道或连接器桥接层：默认值、验证、渠道和桥接代码、连接器指南和集成测试； - 受管本地工具：注册表、具体适配器、状态和解析行为、维护者指南和测试； - 共享API接口：路由器、处理程序、浏览器客户端、终端客户端、导航和契约测试； - 打包：清单、项目元数据、公开概览、必需界面包和包内容验证。 不要把此矩阵扩展到无关子系统。其目的不是重写整个仓库，而是在直接影响边界内实现协调一致的完整性。 ## 完成前按文档中的安装方式确认能运行 针对变更范围运行相关的单元、集成、契约、编译、界面构建和打包检查。启动器或打包行为发生变化时，应通过文档说明的公开路径启动；直接启动服务只能作为诊断路径进行验证。 检查最终差异中是否有无关编辑、过时生成文件、缺失的翻译文档、没有依据的功能声明和不完整的客户端更新。要区分本地组件测试成功与受支持的安装及界面路径确实可用这两种证据。 以实际检出内容作为最终权威来源。如果引用的文件或行为已不存在，应修正该引用及其使用方，而不是保留错误。