putio-frontend-dev

put.io 前端开发

在目标仓库自身的指南和代码惯例之后，应用 put.io 前端工程默认规范。

开始

1. 使用 git ls-files '*AGENTS.md' '*SKILL.md' 清点嵌套指南，并阅读 README.md 和所修改区域的文档。目标仓库指南、项目本地技能和代码惯例优先于本技能。
2. 确认仓库类型、技术栈、验证入口、交付目标和运行时验证方式。
3. 仅选择任务所需的参考资料。

参考资料索引

• 功能代码、解析、状态、错误、表单、样式和测试： 前端默认规范
• README、CONTRIBUTING、安全问题报告和面向 Agent 的文档： 顶层文档
• 软件包和应用的 CI、验证、发布、部署和发布形态： 交付模型
• TypeScript 软件包和应用配置： TypeScript 默认规范
• 机器工具、同级克隆、Agent 工作树、就绪状态检查： 环境设置
• 本地开发密钥和 CI 凭据边界： 密钥
• 涉及密钥的发布、签名、发布流程和部署： 发布安全
• 浏览器、原生应用、电视、模拟器和设备验证： 测试工具概览
• 共享测试账户的浏览器授权： 测试工具模式
• 基于 CLI 的测试工具发现、授权、读取和写入： CLI 测试工具约定

Markdown 链接用于导航此技能包。参考资料中显示的其他路径（例如 .github/pull_request_template.md）是目标仓库中需要创建或检查的文件。

仓库

• repos.json 列出了 put.io 仓库；由前端负责的条目会在 owns 中列出 frontend。
• 字段说明：name 是本地文件夹名，repo 是 GitHub 远程仓库，path 是规范检出路径，owns 是负责团队，visibility 是文档可见范围，topics 是 GitHub 主题集合（可选），mode 表示团队的工作区工具是否管理该检出。
• owns 中有多个团队的条目属于共享条目。在 putdotio/.github 中，前端工作应放在 frontend-* 工作流中；在 putdotio/agent-skills 中，应放在 putio-* 技能中。
• 同级仓库位于同一个文件夹下，默认路径为 ~/projects/putdotio/。如果路径不存在，请运行 gh repo clone <repo> <path>，或使用环境设置中的克隆循环。
• 跨仓库引用内容前，请检查 visibility；私有内容不得出现在公开仓库中。
• 对于涵盖所有前端仓库的任务：遍历 owns 中包含 frontend 的条目；除非任务涉及 SDK，否则跳过 sdks 组；进入每个仓库根目录，阅读其 AGENTS.md，并运行该仓库自己的验证流程。

知识库

• 知识库位于 put.io Notion 工作区的前端中心；请通过 Notion MCP 阅读。
• 内容包括产品、规范、设计、服务、交付 （交付模型， 发布安全， 密钥管理）、 决策、分析和指南。
• 在作出产品、规范、发布或密钥相关决策前，请先阅读知识库。
• 仅编辑前端页面。除非任务有明确要求，否则不要修改其他团队的页面，包括共享数据库中的运维指南。

共享默认规范

• 在边界处解析外部输入，并根据经过验证的契约推导类型。
• 使用明确的状态和穷尽式转换来建模对错误敏感的流程。
• 为预期错误提供类型，并确保其可采取相应措施；限制意外故障的影响，避免无关 UI 一片空白。
• 将副作用保留在适配器和叶节点中，使渲染树保持纯粹。
• 避免使用会削弱契约的类型逃逸手段。
• 用户名、密码和当前的一次性密码仅可在 put.io 官方网站上接受。将长期有效的 TOTP 秘钥保存在生成当前验证码的授权密钥提供方中。CLI、移动端、TV、扩展程序、测试框架及其他客户端必须通过 OAuth 或设备链接流程，将账户授权交由网站处理，并且只处理由此产生的验证码或令牌。
• 将构建、验证、部署和冒烟测试逻辑放在仓库自有命令中，由 CI 调用，并保持工作流 YAML 精简。保留既有任务图；创建新流水线时，使用单一的 verify 入口。
• 仅在验证通过后，从可信的 main 或已验证的发布引用进行交付。
• 合并或推送到 main 即为交付，包括 CI 因此启动的部署和发布。手动执行部署或发布、修改密钥或提供方、向仓库托管平台以外的位置写入内容（商店、提供方控制台、共享账户），以及强制推送之前，都必须先征求同意。
• 尽可能精简拉取请求正文：写明结果、实际风险和未经验证的内容。每份正文都必须附带可视化材料，而非纯文字：UI 修改附经审核的截图或短视频，流程附 Mermaid 图，数字附表格，API 附简短代码示例。不要写测试数量、命令日志和审核历史。
• 在最近的 AGENTS.md 中记录不明显的代码规范；将用户、贡献者、分发和安全文档放在各自的规范位置。

验证依据

• 选择所有者为受影响行为及其依赖项记录的检查项。如果所有者的策略有要求、共享输入发生变化，或针对性覆盖情况不确定，则运行完整的规范验证流程。在安装后的软件包、下游使用方、浏览器和设备等边界重要时，分别提供验证依据。
• 如果存在真实的浏览器、应用、模拟器、仿真器或设备界面，则应在其中验证用户可见的行为。
• 在宣布 UI 工作完成之前，验证首次加载、加载中、错误和空状态、小屏幕，以及选择、焦点、水合和竞态等交互状态。自行检查结果，不要询问用户哪里不对。
• 只要验证依据的来源、输入和环境仍然有效，就可以复用已通过的结果；仅仅开启新一轮工作或交接并不需要重新运行。注明无法执行的验证及其确切阻碍。发现命令不代表获准执行实际操作。
• 在验证命令启动运行时之前，先设置清理操作，并记录该命令是否启动了指定目标。无论如何退出，都只停止由该命令启动的目标，并确认它们已停止；保留原先已运行的目标。

边界

• SDK 仓库属于专门的 SDK 开发工作流，包括其文档、验证、发布和交付形式。
• 将 putio CLI 用作文件、下载、传输、身份验证或存储客户端时，应遵循 CLI 的使用方指南。前端测试框架通过 CLI 测试框架契约 使用已安装的 CLI。
• 仓库策略、通用 GitHub Actions 加固、构建工具迁移、可启动性修复和独立代码审查均不属于本技能范围；本技能为执行这些工作的任意工作流提供 put.io 前端领域指导。
• 不要将特定机器的信息、凭据、账户详情和私有支持信息放入此公开技能；仓库注册表仅记录名称、远程仓库、规范路径、所有者、可见性、主题和模式。