@birdie_moblie/open_spec 2.1.7 → 2.2.0

package/presets/flutter-mobile/ui-conventions.md

@@ -1,122 +0,0 @@
-<!-- openspec:fill-me -->
-<!-- 本模板只记录宿主事实。逐节核查实现与有效约定后填写；不适用项明确注明。填写完成删除首行标记。 -->
-
-# UI 约定（<项目名>）
-
-维护人：<团队>。组件、路径、命令与默认行为必须来自本项目；以下占位内容不是既定技术选型。
-
-## 0. 以宿主为准的项（覆盖设计稿）
-
-下列项按宿主约定实现与验收，设计稿上的对应值只作参考：scout 在复用清单标记「以宿主为准」，build 按约定实现并在 result.notes 写明，verify 不把它们与设计稿的差异登记为问题。没有这类项写「无」。
-
-| 项 | 宿主标准 | 与设计稿差异的处理 |
-|---|---|---|
-| 字体族 | <pubspec 已声明的字体族与字重档> | <只取设计稿字号与字重；其它字体族不下载、不注册> |
-| 导航栏 | <共享导航栏组件及构造参数> | <高度、返回键、标题样式由组件负责机型适配，不按设计稿调整> |
-| <其它，如安全区、状态栏> | <标准> | <处理> |
-
-## 1. 页面状态容器
-
-状态管理与规范：<实际技术、规范路径及可复用实现>。
-
-| 组件 / 范式 | 用途 | 位置 | 约束 |
-|---|---|---|---|
-| <已有状态容器> | <加载、成功、空数据、失败与恢复> | <路径及符号> | <默认行为与适用范围> |
-| <结果模型> | <结果、业务错误和网络错误传播> | <路径及符号> | <消息展示、重试与状态更新约定> |
-| <跨模块交互入口> | <刷新、通知或共享状态> | <公开接口路径> | <调用责任与生命周期> |
-
-- 初始状态、订阅及结果传播：<实际接法、初值和时序>。
-- 对象所有权与释放：<创建、借用、取消与释放责任>。
-- 防重复操作、并发与竞态处理：<已有组件或规则>。
-
-## 2. 弹窗与底部面板
-
-| 组件 | 用途 | 位置 | 约束 |
-|---|---|---|---|
-| <标准提示或确认组件> | <适用交互> | <路径及符号> | <默认样式、按钮与关闭行为> |
-| <面板或其他浮层> | <适用交互> | <路径及符号> | <默认布局和生命周期> |
-
-页面与浮层形态词表：<项目实际形态、命名及来源>。
-
-## 3. 分享与媒体
-
-| 组件 | 用途 | 位置 | 约束 |
-|---|---|---|---|
-| <实际入口或不适用> | <内容生成、系统分享、保存或复制> | <路径及符号> | <权限、默认样式和错误处理> |
-
-## 4. 偏好与本地存储
-
-| 入口 | 用途 | 位置 | 约束 |
-|---|---|---|---|
-| <实际存储入口> | <设置、筛选或共享偏好> | <路径及符号> | <键命名、作用域与一致性> |
-
-## 5. 主题与颜色
-
-- 主题与颜色的唯一来源：<主题扩展、token 或常量定义路径>。
-- 主题切换入口与测试驱动入口：<实际机制与调用位置>。
-- 固定色、渐变及历史兼容约束：<适用来源和定义位置>。
-
-## 6. 国际化
-
-- 是否适用及实际工具：<项目选择或不适用>。
-- 资源格式、源语言与路径：<真实格式和路径>；键命名：<真实约定>。
-- 代码读取入口：<实际 API 和示例路径>。
-- 翻译、增量合入、生成与校验：<所选插件 Hook、宿主命令及参数来源>。
-- 运行参数：<项目配置、本机环境或显式临时覆盖的来源>；模板不指定个人凭据、模型或服务地址。
-- 必需语言、占位符规则、忽略范围与历史文案保护：<配置与验证入口>。
-- 文案来源优先级：<设计、需求和实际决定的适用关系>。
-
-## 7. 网络与接口
-
-- 客户端、请求封装、地址配置与数据模型：<实际路径和符号>。
-- 路径参数、查询参数、请求体及序列化约定：<实际实现与公开调用示例>。
-- 生成器或手写实现：<项目选择及配置来源>；原始生成证据位置：<不进入业务源码编译的产物路径>。
-- 动态或未展开对象、错误和恢复策略：<数据保留、解析、鉴权与重试约定>。
-
-## 8. 数值与文案格式化
-
-百分比、精度、单位、时间及其他格式化：<现有工具、路径及业务约束>。
-
-## 9. 设计资产
-
-资源目录、注册方式与缺失资产占位组件：<项目事实>。
-已声明的 assets 目录：<pubspec.yaml 中的每一行>。Flutter 的目录声明不递归子目录，为新页面新建的子目录必须在 pubspec.yaml 单独登记，UI task 范围须含 pubspec.yaml。
-资源来源与 TODO 标识：<设计节点或缺失说明的记录方式>。
-
-- 结合页面截图与节点 Meta 核对图片的用途、显示尺寸、背景和主题。分别记录节点设计值与导出件已含效果；opacity、渐变、阴影已包含在导出件时不再重复叠加，不根据 alpha 通道是否存在推断效果是否已包含。
-- 下载成功后核对实际资源。底板或主题不符时优先选择合适节点、透明导出或宿主资源；应用保留原件，显示按设计与宿主适配。
-- 小图供模型查看时优先使用父级组件或页面截图及对应 Meta。模型输入限制按当前提供商处理，不把某个提供商的阈值写成宿主通用标准，不为模型查看而改动生产切图，也不把模型拒收当成下载失败。
-
-## 10. Figma 变量 → 项目 token 映射
-
-| Figma 变量 | 项目 token / 定义位置 | 主题与用途 |
-|---|---|---|
-| <实际变量> | <实际 token 和路径> | <适用主题和语义> |
-
-业务数值或状态的着色规则：<实际规则或不适用>。
-无变量的固定强调色或渐变：<来源与具名定义>。
-
-## 11. 字体规格 → TextStyle 约定
-
-实际字体族与已打包字重：<字体资源和配置路径>。
-
-| 语义规格 | 字号 / 设计字重 | TextStyle / 定义位置 | 用途 |
-|---|---|---|---|
-| <实际规格> | <设计值> | <项目样式及路径> | <适用范围> |
-
-## 12. 主题资源命名
-
-| 资源 / 节点 | 各主题资源名与路径 | 选择入口与调用位置 |
-|---|---|---|
-| <实际节点> | <项目支持的主题资源> | <实际方法及路径> |
-
-## 13. 页面验证入口
-
-| 入口 | 命令 / 路径 | 产出 |
-|---|---|---|
-| 页面契约与导航测试 | <实际可执行命令> | <日志位置> |
-| 主题切换测试 | <实际可执行命令或不适用> | <日志及截图位置> |
-| 整页截图 | <命令及实际视口、缩放、语言> | <截图路径> |
-| 静态检查 | <宿主实际命令及既定失败阈值> | <完整日志位置> |
-
-受保护文件（固定断言、夹具和 manifest，Worker 不得修改）：<路径清单>。

package/presets/flutter-mobile.yaml

@@ -1,205 +0,0 @@
-schemaVersion: openspec.team-preset.v1
-version: 2.2.4
-id: flutter-mobile
-title: Flutter Mobile
-description: Flutter 移动应用团队的 spec-product 默认配置
-marketplaces:
-  - name: mobile-marketplace
-    repo: git@gitlab.bitrue.com:flutter_app/mobile_marketplace.git
-    ref: 06081ec27a557d8f5e4d443aa8549ab026173f94
-plugins:
-  - name: lark-cli
-    marketplace: mobile-marketplace
-  - name: yapi-dart-coding
-    marketplace: mobile-marketplace
-    minVersion: 0.2.1
-  - name: project-review
-    marketplace: mobile-marketplace
-  - name: intl-utils
-    marketplace: mobile-marketplace
-    minVersion: 0.2.3
-scaffold:
-  - path: docs/agent/ui-conventions.md
-    template: flutter-mobile/ui-conventions.md
-    description: 项目 UI 约定清单，parse/tech/plan/ui Worker 的 required file hook 目标
-configPatch:
-  schema: spec-product
-  taskCategories:
-    ui:
-      notes: >-
-        项目事实以 docs/agent/ui-conventions.md 为准；scout 抽取本 task 用到的行进 context.md，缺项按节补读；
-        不自造替代组件、颜色或文案。
-    logic:
-      notes: 防重复提交、pending 互斥、异步竞态与关闭后回调必须用真实状态测试验证，异常后可重试；保持业务逻辑内聚；跨页面联动用显式契约接口，不依赖库私有 State。异步恢复后再失败也须结束公开 Future，并保持约定异常与状态。局部响应按请求作用域合并并保留未涉及项；互斥按业务键区分，同键防重不应吞掉不同键操作。测试覆盖局部响应保留、同键重复、不同键同时触发及全量刷新与局部响应乱序。
-    api-codegen:
-      notes: >-
-        仅通过已声明的接口源生成代码。生成后核对路径占位符与 replaceAll 匹配串一致、GET 参数走 queryParameters。
-        字段与需求不符、缺字段或注释枚举与 schema wire type 冲突即 blocked，不自造字段/转换。
-        成功码按各接口 description 原文逐个映射到宿主已有判定 getter（如 0 与 200 各有入口），不统一口径、不改共享默认。
-        生成物形状与空类处理以所选生成插件的 Skill 为准；开放对象丢数据即 blocked，回工具项目修复，不手写解析器绕过。
-        原始 Dart 证据用 .dart.txt 等非源码文件名，保存字节与来源摘要；普通根分析不得新增错误。
-  hooks:
-    - id: lark-requirements
-      stage: collect
-      capability: requirements
-      use: lark-doc-fetch@mobile-marketplace
-    - id: yapi-interfaces
-      stage: collect
-      capability: interfaces
-      use: yapi-discovery@mobile-marketplace
-    - id: figma-design
-      stage: collect
-      capability: design
-      type: skill
-      name: figma-design-capture
-      purpose: >-
-        mobile-marketplace 暂无 figma adapter：定位级采集每页节点 id、形态、变体节点、深浅 section/frame 映射及需求冲突，保留含 fileKey 的 URL；
-        collect 不展开内部；tech 先定向核对影响组件复用及范围的设计事实，完整字号/颜色/间距与切图清单留给 apply。写成 markdown，
-        再以 sources add --source-file design=<path> 登记后重新 collect。
-    - id: parse-ui-conventions
-      stage: parse
-      type: file
-      path: docs/agent/ui-conventions.md
-      purpose: 项目平台组件与范式清单；写「能力与入口清单」时对照可复用组件与状态容器
-    - id: parse-spec-structure
-      stage: parse
-      type: check
-      category: spec
-      description: spec.md 已含「能力与入口清单」「状态与交互」「来源冲突与缺口」三章；每个有设计的界面形态（page / dialog / bottom-sheet / tab 子页）有设计节点依据，不从需求措辞推定；影响页面形态或入口的冲突已 blocked 提问而非自选口径
-    - id: tech-ui-conventions
-      stage: tech
-      type: file
-      path: docs/agent/ui-conventions.md
-      purpose: 写「复用清单」时逐项对照，能复用的写具体路径
-    - id: tech-reuse-inventory
-      stage: tech
-      type: check
-      category: tech
-      description: 复用清单已对照宿主优先项、目标截图/必要 Meta 与组件 API，区分直接复用、扩展后复用、新建；记录参数依据或能力缺口、修改文件及旧调用默认行为，未知不当作可直接复用
-    - id: plan-ui-conventions
-      stage: plan
-      type: file
-      path: docs/agent/ui-conventions.md
-      purpose: 按清单拆 task
-    - id: yapi-plan-coverage
-      stage: plan
-      type: command
-      use: yapi-plan-coverage@mobile-marketplace
-      capability: interfaces
-      required: true
-    - id: plan-crosscutting
-      stage: plan
-      type: notes
-      notes: 国际化文案、主题色、四态与错误提示不得拆成独立 task，必须包含在对应 UI task 内；UI task 的 notes 必须引用 spec 页面清单条目与形态，并包含实际 S 接线、翻译、生成与语言切换；不能以 raw_ 或固定文案作为普通文案豁免。UI task 的精确范围还须列出本页切图目录、pubspec.yaml 的 assets 注册、经适配确认需要扩展的共享 widget 文件（宿主优先项不因设计差异扩展；已有参数足够只改调用方）以及页面所属弹层文件，漏列会在 Gate-A 后触发边界失败。Flutter 的 assets 目录声明不递归子目录：为本页新建的资源子目录必须在 pubspec.yaml 单独登记一行，已声明父目录不覆盖它，因此 pubspec.yaml 几乎总在 UI task 范围内。API 生成任务按插件预演的完整生成物清单列出精确范围，覆盖检查输入见插件 Hook 说明，不用目录放开代替。
-    - id: ui-conventions
-      stage: execute
-      type: file
-      path: docs/agent/ui-conventions.md
-      taskCategories: [ui]
-      purpose: 项目事实清单；scout 抽取相关行进 context.md，缺项按节补读
-    - id: ui-states-complete
-      stage: execute
-      type: check
-      category: ui-states
-      description: 四态有状态测试或可读截图；按钮防重、pending 互斥、竞态、异常重试与关闭后回调必须有真实状态测试，截图不能替代，路径写在 result.notes
-      taskCategories: [ui, logic]
-    - id: theme-color-correct
-      stage: execute
-      type: check
-      category: theme
-      description: 核对深浅截图颜色与设计变量映射 token；无变量用约定具名固定色。普通视觉偏差记 advisory 并披露，主题切换功能失败仍阻断
-      taskCategories: [ui]
-    - id: i18n-inline
-      stage: execute
-      type: command
-      use: intl-locales-check@mobile-marketplace
-      taskCategories: [ui]
-      required: true
-      purpose: 真实 locale 校验；可见文案来源、截图无硬编码及历史语义仍由 intl-workflow 和 verify 文案 Hook 核对
-    - id: design-structure-match
-      stage: execute
-      type: check
-      category: design
-      description: 最终截图按 scout 设计清单逐项对照 Figma 与 Meta：形态、区块顺序与排列、尺寸间距圆角、背景边框、按钮、切图、深浅两套；§0 以宿主为准。passed 表示完成核对；普通视觉偏差记 advisory 并披露，字体或图片不可读不得通过
-      taskCategories: [ui]
-    - id: typography-match
-      stage: execute
-      type: check
-      category: design
-      description: 截图/样式核对：字号按设计，字重在宿主 §11 声明映射时按映射验收，字体族以 ui-conventions §0 的宿主约定为准；共享组件旧默认样式未改。普通视觉偏差记 advisory 并披露后可继续
-      taskCategories: [ui]
-    - id: flutter-analyze-changed
-      stage: verify
-      type: command
-      command: fvm flutter analyze --no-fatal-infos --no-fatal-warnings {files}
-      target: inScopeChangedFiles
-      include:
-        - "**/*.dart"
-      allowEmpty: true
-      required: true
-      purpose: 仅对变更 Dart 文件做静态检查
-    - id: flutter-review
-      stage: verify
-      type: skill
-      name: project-review
-      required: true
-      purpose: 按当前 change 契约与项目约定审查范围内改动
-    - id: visible-copy-and-locale
-      stage: verify
-      type: check
-      category: copy
-      description: 核对可见文案、占位符、locale 资源与项目业务术语一致性
-      required: true
-    - id: pending-work
-      stage: verify
-      type: check
-      category: todo
-      description: 引用 openspec todo 分类输出；非阻塞待办
-      required: false
-    - id: yapi-guidance-parse
-      stage: parse
-      type: skill
-      use: yapi-source-guidance@mobile-marketplace
-      capability: interfaces
-      required: true
-    - id: yapi-guidance-tech
-      stage: tech
-      type: skill
-      use: yapi-source-guidance@mobile-marketplace
-      capability: interfaces
-      required: true
-    - id: yapi-preview
-      stage: tech
-      type: command
-      use: yapi-discovery@mobile-marketplace
-      operation: preview
-      capability: interfaces
-      required: true
-    - id: yapi-generation
-      stage: execute
-      type: skill
-      use: yapi-codegen@mobile-marketplace
-      taskCategories: [api-codegen]
-      required: true
-    - id: intl-workflow
-      stage: execute
-      type: skill
-      use: intl-workflow@mobile-marketplace
-      taskCategories: [ui]
-      required: true
-  verify:
-    reviewScope:
-      includeDirs:
-        - lib
-        - test
-      excludeDirs:
-        - lib/generated
-notes:
-  - 假定 fvm 管理 Flutter。marketplace ref 是本 preset 发布时验证过的基线；宿主可在兼容范围内独立升级插件，实际使用的版本以宿主 openspec/config.yaml 与 marketplace-lock.json 为准（步骤见 docs/guides/plugin-migration.md）。
-  - init 会把 UI 约定清单模板生成到 docs/agent/ui-conventions.md（只创建不覆盖）；填写后删除首行 openspec:fill-me 标记，否则 parse/tech/plan/ui Worker 会以 blocked 停下。改路径时需同时修改四个 *-ui-conventions hook 与 scaffold.path。
-  - 约定文件只写项目事实（组件、路径、token、字体、资源、命令、受保护文件）；流程规则由 skill 节点承担，不在此重复。
-  - 不对整文件 grep 文案或颜色；宿主有真实行为/文案检查入口时配置 execute command Hook。check 描述是 verify 子代理逐条对照截图的闭合条件，Worker 回执只表示「已按此实现」。
-warnings:
-  - 本 preset 引用的插件入口最低需要 yapi-dart-coding 0.2.1（yapi-plan-coverage）与 intl-utils 0.2.3（任务快照翻译），已写入 plugins[].minVersion，安装与 doctor 会检查。当前基线 ref 中两者分别为 0.2.0、0.2.1，发布前须更新为包含新版本的已发布提交。各插件所需的工具版本与能力由插件 Skill 声明并在运行前核对。
-  - 既有宿主按 Hook ID 精确迁移，不能直接覆盖配置。preset apply 与 init --preset 保留宿主已声明的 marketplace ref；升级插件用 openspec marketplace upgrade。
-  - init --yes 才会安装 marketplace 插件；lark-cli、Dart/FVM 与认证仍是运行时前置条件。

package/presets/web-product.yaml

@@ -1,23 +0,0 @@
-schemaVersion: openspec.team-preset.v1
-version: 2.0.0
-id: web-product
-title: Web Product
-description: Web 产品团队的 spec-product 默认配置
-configPatch:
-  schema: spec-product
-  hooks:
-    - id: ui-task-notes
-      stage: execute
-      type: notes
-      taskCategories: [ui]
-      notes: 复用现有设计系统与可达性约定。
-    - id: unit-test
-      stage: verify
-      type: command
-      command: pnpm test
-      required: true
-    - id: build
-      stage: verify
-      type: command
-      command: pnpm build
-      required: true