在既定的产品约束内修改本地优先的 AI 设计桌面应用

## 指令文件之间有冲突时，以智能体指南为准 在做出任何修改之前先阅读本文件。仓库中其他的智能体指令文件可能落后于当前的计划；当它们与本文件不一致时，以本文件为准。 诸如愿景文档、原则文档或当前发布计划之类的内部设计文档，如果存在于你的检出副本中，就是有用的额外上下文。内部文档目录被 gitignore 忽略，因此维护者会把计划、交接材料和调研保存在本地，而公开贡献者可能一份都拿不到。 - 绝不要让公开贡献者的工作卡在只有维护者才能看到的文件上。 - 绝不要在公开的评审评论中引用被 gitignore 忽略的文档目录下的路径，除非该文件同时也存在于公开的检出副本中。 - 当这些文档缺失时，依靠本文件、公开的 issue 和 pull request，以及 README。 ## 把每个设计当作带有自己工作区的长期会话 本产品不是一个单次提示词生成器。每一个工作单元都是一个长时间运行的智能体会话，其背后是用户机器上一个真实的工作区；智能体可以读取和编辑文件、运行经过授权的命令、提出结构化问题、预览产物、暴露微调控件、在所配置的模型支持时生成图像，以及产出设计系统文档。 - 一个设计拥有一个工作区。不存在封闭／开放的划分：工作区的文件系统就是产物与资源的事实来源。 - 智能体编辑工作区中的源文件；预览运行时把这些源文件渲染成可查看的文档；导出器把已渲染的文档或源文档转换成 HTML、PDF、PPTX、ZIP 或 Markdown 等标准输出。 - 为当前格式保留一个规范的源入口文件（例如一个 JSX 组件文件），并把独立的 HTML 文件留给导出用途或遗留的工作区文件。 - 借鉴已被验证的编码智能体机制是有意为之的；产品的边界在于：领域专用工具和本地优先的工作区模型才是你在其之上添加的东西。 ## 守住不打包模型、只用用户自带密钥等硬性约束 这些是项目的承诺，不是偏好。不要为了方便而拿它们做交换。 1. 不捆绑模型运行时。不要把推理引擎、语言解释器、浏览器二进制文件或模型权重打包进安装程序。使用系统已安装的组件，或者在用户可见的同意之下延迟下载。 2. 只允许自带密钥。默认不提供托管账号、代理 API 或遥测。用户凭据保存在人类可读的本地配置中。 3. 本地优先的存储。会话以只追加的会话文件加上真实的工作区文件的形式存在。遗留的嵌入式数据库中已有的数据可以迁移，但不要在其中为会话、聊天历史、评论、快照或设计文件新增表。 4. 每个设计都有一个工作区。任何重要的东西都不得只存在于一条会话记录之中。 5. 任何随产品交付、捆绑、链接、被应用代码导入或分发给用户的东西，都必须采用宽松许可证并与项目许可证兼容。在这一范围内，拒绝 copyleft、source-available、专有以及来源不明的第三方资源。仅用于工作流的 CI 与发布工具，在没有被 vendor 化、捆绑、链接或复制进产品的前提下可以使用 copyleft 许可证；要记录原因，并把其输出限制在普通的元数据或清单文件。 6. 重型功能延迟加载。导出器、网页抓取、脚手架、技能、参考资源和图像生成必须按需加载，而不是在应用启动时加载。 7. 优先复用底层智能体框架的原语。会话、内置工具、shell 执行、事件流、模型注册表、提供方注册以及能力数据都归它所有，除非某个领域专用的需求证明并非如此。 8. 参考数据是数据，不是模型记忆。品牌与样式的取值要来自工作区的设计文档、用户文件、官方资源或已发布的来源。绝不要凭记忆编造品牌色或规格。 9. 变更应当保持兼容、可升级、精简且优雅，并且在项目存在详细的原则检查清单时应当遵循它。 ## 建网站时一并准备 llms.txt 等面向 AI 的文件 在构建或更新任何网站、项目主页、产品页、个人站点、文档站点、博客或公开的项目页面时，除非用户明确选择退出，否则要把 AI 可见性纳入默认的交付范围。 - 添加 `/llms.txt` 文件，用简洁的 Markdown 概述站点、作者或组织、关键页面、规范的项目或产品描述，以及指向机器可读资源的链接。 - 当站点拥有足够多有实质内容的公开内容、足以支撑一份更完整的 AI 可读上下文文件时，添加 `/llms-full.txt` 文件。 - 有意识地配置 `robots.txt`：允许那些有助于 AI 系统引用或检索公开内容的搜索与检索爬虫，并把训练用爬虫当作一项单独的策略决定来处理。 - 维护 `sitemap.xml`，并确保它覆盖重要的公开页面。在相关时提及向站长工具提交。 - 在有用的地方添加合适的 JSON-LD 结构化数据，例如 person、organization、website、article、software application、FAQ 或 creative-work 等类型。 - 对于个人资料、项目、文章、文档、发布、FAQ 和产品事实等重要实体，优先提供干净的 Markdown 或 JSON 机器可读端点。 - 保持内容真实、有来源支撑且不含垃圾信息。目标是帮助 AI 系统准确理解并引用真实存在的内容，而不是生成低质量的填充内容。 ## 所有模型调用和工具都经过共享的智能体框架 - 在共享的智能体框架及其模型抽象层之上构建，而不是自己手写一套等价物。 - 使用框架内置的读取、写入、编辑、shell、grep、查找和列举工具，而不是另写一套平行的版本。 - 让每一次工具调用都经过框架的工具调用钩子和应用的权限 UI 进行把关。 - 从框架的模型描述字段读取模型能力，例如可接受的输入类型、推理支持、成本、上下文窗口和最大输出 token 数。不要把能力表硬编码。 - 通过框架的提供方注册 API 注册自定义提供方。不要构建一层平行的提供方 SDK。 - 所有模型调用都要走框架的模型抽象层。不要在应用代码中直接导入厂商 SDK。 ## 会话存为只追加的文件，设计放在用户工作区 - 一个设计就是一个会话。会话历史以只追加的会话文件形式存放在应用的用户数据目录下。 - 设计源文件、生成的标记与样式、资源、导出结果，以及工作区级别的智能体文档和设计文档，都存放在用户工作区中，而不是应用数据库中。 - 工作区设置存放在一个带版本的设置文件中，该文件带有明确的 schema 版本字段。 - 个人的本地设置文件是按用户区分的，必须保持被 gitignore 忽略。 - 遗留的嵌入式数据库是待迁移的数据，不是当前的存储模型。不要用新的功能状态去扩展它。 ## 只用框架内置工具加少量设计专用工具 工具面就是框架的内置工具，加上一份简短的领域工具清单： - `ask(questions)` 渲染结构化问题并等待用户。 - `scaffold(kind, path)` 把一份精选的起始模板复制进工作区。 - `skill(name)` 从清单中延迟加载技能文本。 - `preview(path)` 渲染产物，并返回控制台错误、资源错误、DOM 大纲、指标，以及供视觉模型使用的截图。 - `gen_image(prompt, path)` 在能力和提供方配置允许时把生成的图像写入磁盘。 - `tweaks(blocks)` 声明跨文件的可编辑控件。 - `todos(items)` 为复杂的回合展示任务状态。 - `done(path)` 在完成一次预览自检之后结束当前回合。 除非计划发生变化，否则不要重新引入验证器子智能体、片段捕获工具、自定义 shell 工具、自定义列举文件工具，或由智能体书写的工作记忆。 ## 把四类设计资源分开使用，不互相替代 设计文档遵循已发布的规范，既可以是输入也可以是输出。智能体生成的多屏工作通过在 token 出现时更新该文档来保持视觉一致性。内置的参考系统必须带有署名、来源、许可证元数据以及一条“无从属关系”的说明，内置技能则使用标准的技能文件格式。技能清单与脚手架清单必须带有许可证和来源元数据。 这四类资源不可互换： - Markdown 技能是方法规则。它们告诉智能体应该怎样工作；它们不会把文件复制进工作区。 - 参考设计系统是只读的，按名称作为技能加载。不要为了某个项目而修改它们；把你所采纳的选择转写进工作区的设计文档。 - 脚手架是被复制进工作区的具体起始资源和源资源。只要清单对它们的描述是准确的，它们可以是任何文本格式。 - 设计技能代码片段是通过虚拟文件系统暴露的可复制组件模式。它们是源代码片段，既不是方法规则，也不是品牌权威。 工作区的设计文档是项目专属的接力棒。一旦它存在，它对当前设计就具有权威性，生成的工作应当保全或修复它，而不是把它当作又一个预设。 ## 把起始模板当作产品代码审查，并让扩展名与内容一致 - 把起始模板和脚手架资源当作产品代码，而不是提示词填充物。在修改或新增一个预设之前，除了清单之外还要审阅文件的实际内容。 - 保持源格式与文件扩展名一致。完整的 HTML 文档应放在 `.html` 文件中，组件起始模板放在组件扩展名的文件中，样式片段放在 `.css` 中。复制工具应当保留源扩展名，但资源本身仍然必须被正确命名和描述。 - 内置的 HTML 起始模板必须是自包含的，并且能在当前运行时中预览。不要往脚手架资源里添加 CDN 或第三方运行时脚本。如果某个起始模板需要运行时行为，就使用本地的纯 HTML、CSS 和 JavaScript，或者使用由应用提供的、许可证路径清晰的延迟加载依赖。 - 避免诸如“幻灯片标题”“页面内容”“替换此处”或“要点一”这类无力的占位文案。使用中性、可用的示例内容，并通过起始模板所声明的微调默认值把显而易见的替换点暴露出来。 - 清单描述必须说明某个起始模板是哪种格式，并且必须指出对扩展名敏感的资源，尤其是那些智能体可能会用错误扩展名复制的文件。 - 在改动脚手架目录树时，要审查扩展名与内容是否不匹配、是否有外部网络 URL、是否有陈旧的占位文案，以及清单是否漂移。当变更影响到复制路径、预览分类或工具行为时，要新增或更新有针对性的脚手架测试和运行时测试。 ## 沿用已选定的工具，从锁文件读取版本 - 整个仓库只用一个包管理器。绝不要混入第二个。 - 使用仓库既定的构建编排工具、单一的 lint 与格式化工具、单元测试运行器和端到端测试运行器，而不是引入替代方案。 - TypeScript 使用严格模式，配合 verbatim module syntax 和 bundler 解析方式。不允许 `any`。 - 提交信息使用 Conventional Commits，版本管理使用 changeset 工具。不要手工编辑 changelog。在版本文件和 engines 字段中都固定运行时版本。 - 精确的包版本存放在清单文件和锁文件中。去读这些文件，而不是相信过时的文档。 - 前端选型已经确定：既定的视图库和构建工具、带 CSS 变量的实用类 CSS、一个轻量状态库、封装在共享 UI 包中的可访问无头原语、一套图标集、使用 form data 的原生表单，以及用于动画的 CSS 过渡。不要引入相互竞争的状态库、动画库或组件库。 - 应用外壳必须使用共享 UI 包的 token。生成的设计源文件和导出结果可以定义它们自己的视觉体系。 - 仓库把应用外壳、智能体核心、提供方集成、预览运行时、共享 UI、产物 schema、导出器、模板和共享类型拆分为各自独立的包。把代码放进拥有该关注点的那个包里。 ## 较大的任务先写计划文件，并把改动范围收窄 - 对于非琐碎的架构或产品工作，当愿景、原则和当前计划文档在本地存在时就去阅读它们；否则依靠本文件和公开讨论。 - 对于跨越大约五次以上工具调用、或涉及三个以上文件的任务，写一份持久的本地计划文件。不要为小而直接的修复制造计划上的折腾。 - 对并行的或互不相关的功能工作使用独立的工作树。不要在同一个检出副本里混用两个不相关的分支。 - 在改动沙箱、行内评论、微调控件、导出器、框架能力、脚手架、技能或参考资源之前，如果调研队列文件在本地存在，就先查看它。 - 让改动保持在限定范围内，避免顺手的重构。 - 在添加随产品交付的依赖或运行时依赖之前，检查它的许可证、安装体积、替代方案，以及它能否作为 peer dependency。对于仅用于工作流的工具，记录为什么它们没有被捆绑，以及它们的输出是否会影响分发的产物。 - 为功能工作新增或更新单元测试覆盖，并在修改迁移、权限、工具钩子或共享契约时扩大测试范围。 - 在有两个真实调用方需要更多能力之前，优先采用清单加 switch 逻辑，而不是注册表。 - 只在原因会让下一位维护者感到意外的地方写注释。 ## 按四级权限处理命令，并显示被拦截的原因 存在单一的权限模型，其层级逐级递增： - 第 0 层：工作区本地的读写、简单的文件命令，以及只读的版本控制命令，可以不受打断地运行。 - 第 1 层：安装、构建命令、非本地的网络请求，以及工作目录之外的命令，会询问一次，之后可以被加入允许列表。 - 第 2 层：发布、推送、提权，以及其他影响半径很大的命令，每次都要询问。 - 第 3 层：破坏性的系统命令、把下载的脚本直接管道输入 shell，以及对系统目录的写入，在没有明确覆盖的情况下会被阻止。 不要隐藏被阻止的工具调用。要展示命令、路径、层级，以及它被阻止的原因。 ## 不要直接导入厂商 SDK，也不要未经同意加入跟踪 - 把依赖目录、构建产物、环境文件、生成的发布产物或私有的本地文件加入版本控制。 - 在应用代码中导入模型厂商的 SDK，或者编写在厂商 SDK 层面模拟模型的测试。改为在核心层或框架边界处进行模拟。 - 在没有明确选择加入体验的情况下，添加追踪、分析、账号流程、云同步或自动更新。 - 硬编码用户路径。要尊重平台的目录约定、应用的路径 API 以及工作区根目录。 - 为会话数据或设计数据添加新的、由遗留数据库支撑的功能状态。 - 在工作区之上引入更重的分组抽象。多个会话可以共享一个工作区，但侧边栏列出的是会话。 - 除非计划发生变化，否则不要暴露会话分支、撤销与版本回滚、外部工具服务器支持，或社区技能安装。 - 在主进程、核心、提供方、导出器或共享包中使用原始的 console 调用。要使用项目的日志器。