chore: stop tracking ignored directories (.claude, .cursor, .specify, .trae, .github, docs)

-{
-  "permissions": {
-    "allow": [
-      "Bash(tree:*)",
-      "Bash(xargs awk:*)",
-      "Bash(find:*)",
-      "Bash(grep:*)"
-    ]
-  }
-}

----
-description: 在生成 tasks.md 之后，对 spec.md、plan.md、tasks.md 做一次非破坏性的跨文件一致性与质量分析。
----
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-在继续之前，你**必须**先考虑用户输入（如果不为空）。
-
-## 目标
-
-在开始实现之前，识别三份核心产物（`spec.md`、`plan.md`、`tasks.md`）之间的不一致、重复、歧义和说明不足之处。本命令**必须**在 `/speckit.tasks` 成功生成完整的 `tasks.md` 之后才运行。
-
-## 运行约束
-
-**严格只读**：**不要**修改任何文件。输出结构化的分析报告。可以提供可选的修复方案（用户必须明确同意后，才可以人工触发后续的编辑命令）。
-
-**宪法优先级**：在本分析范围内，项目宪法（`.specify/memory/constitution.md`）**不可协商**。任何与宪法冲突的问题都自动视为 CRITICAL，并要求调整 spec/plan/tasks，而不是淡化、重新解释或悄悄忽略原则。如果确实需要修改原则本身，必须在 `/speckit.analyze` 之外，通过单独、明确的宪法更新来完成。
-
-## 执行步骤
-
-### 1. 初始化分析上下文
-
-在仓库根目录只运行一次 `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks`，并解析 JSON 中的 FEATURE_DIR 和 AVAILABLE_DOCS。推导出绝对路径：
-
-- SPEC = FEATURE_DIR/spec.md
-- PLAN = FEATURE_DIR/plan.md
-- TASKS = FEATURE_DIR/tasks.md
-
-如果缺少任何必需文件，直接报错并提示用户运行缺失的前置命令。
-当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）。
-
-### 2. 加载产物（渐进式披露）
-
-每个产物只加载最少且必要的上下文：
-
-**来自 spec.md：**
-
-- 概览/背景
-- 功能需求
-- 非功能需求
-- 用户故事
-- 边界情况（如存在）
-
-**来自 plan.md：**
-
-- 架构/技术栈选择
-- 数据模型引用
-- 阶段划分
-- 技术约束
-
-**来自 tasks.md：**
-
-- 任务 ID
-- 任务描述
-- 阶段分组
-- 并行标记 [P]
-- 引用到的文件路径
-
-**来自宪法：**
-
-- 加载 `.specify/memory/constitution.md` 用于原则校验
-
-### 3. 构建语义模型
-
-创建内部表示（输出中不要包含原始产物全文）：
-
-- **需求清单**：每条功能/非功能需求都要有稳定的 key（根据祈使句短语生成 slug；例如 “用户可以上传文件” → `user-can-upload-file`）
-- **用户故事/动作清单**：离散的用户动作及其验收标准
-- **任务覆盖映射**：将每个任务映射到一个或多个需求/故事（通过关键字推断或显式引用模式，比如 ID、关键短语）
-- **宪法规则集**：提取原则名称以及 MUST/SHOULD 等规范性语句
-
-### 4. 检测遍历（Token 高效分析）
-
-聚焦高信号问题。总计最多输出 50 条发现；其余聚合到溢出摘要中。
-
-#### A. 重复检测
-
-- 识别近似重复的需求
-- 标记表达质量较低的需求，建议合并收敛表述
-
-#### B. 歧义检测
-
-- 标记缺少可度量标准的模糊形容词（fast、scalable、secure、intuitive、robust 等）
-- 标记未解决的占位符（TODO、TKTK、???、`<placeholder>` 等）
-
-#### C. 说明不足
-
-- 有动词但缺少对象或可度量结果的需求
-- 用户故事缺少与验收标准对齐的说明
-- 任务引用了 spec/plan 中未定义的文件或组件
-
-#### D. 宪法对齐
-
-- 任意与宪法 MUST 原则冲突的需求或计划要素
-- 缺失宪法要求的必填章节或质量门禁
-
-#### E. 覆盖缺口
-
-- 没有关联任务的需求
-- 未映射到任何需求/故事的任务
-- 未在任务中体现的非功能需求（例如性能、安全）
-
-#### F. 不一致
-
-- 术语漂移（同一概念在不同文件中用不同名称）
-- plan 引用的数据实体在 spec 中缺失（或反之）
-- 任务顺序自相矛盾（例如未注明依赖却在基础初始化之前安排集成任务）
-- 需求相互冲突（例如一处要求 Next.js，另一处指定 Vue）
-
-### 5. 严重级别判定
-
-使用以下启发式规则为发现排序：
-
-- **CRITICAL**: 违反宪法 MUST、缺失核心产物，或关键需求零覆盖导致基线功能无法实现
-- **HIGH**: 重复或冲突的需求、含糊的安全/性能属性、不可测试的验收标准
-- **MEDIUM**: 术语漂移、缺少非功能需求的任务覆盖、边界情况说明不足
-- **LOW**: 风格/措辞改进、不影响执行顺序的轻微冗余
-
-### 6. 产出精简分析报告
-
-按以下结构输出 Markdown 报告（不写文件）：
-
-## 规格说明分析报告
-
-| ID | 类别 | 严重级别 | 位置 | 摘要 | 建议 |
-|----|----------|----------|-------------|---------|----------------|
-| A1 | 重复 | HIGH | spec.md:L120-134 | 两条相似需求…… | 合并表述；保留更清晰的版本 |
-
-（每条发现一行；生成稳定 ID，并以类别首字母作为前缀。）
-
-**覆盖摘要表：**
-
-| 需求 Key | 是否有任务 | 任务 ID | 备注 |
-|-----------------|-----------|----------|-------|
-
-**宪法对齐问题：**（如有）
-
-**未映射任务：**（如有）
-
-**指标：**
-
-- 需求总数
-- 任务总数
-- 覆盖率（至少关联 1 个任务的需求占比）
-- 歧义数量
-- 重复数量
-- 严重问题数量
-
-### 7. 给出下一步动作
-
-在报告末尾输出精炼的“下一步动作”区块：
-
-- 若存在 CRITICAL：建议在进入 `/speckit.implement` 之前先解决
-- 若只有 LOW/MEDIUM：可继续推进，但应给出改进建议
-- 给出明确命令建议：例如“用更精炼描述重新运行 /speckit.specify”“运行 /speckit.plan 调整架构”“手动编辑 tasks.md 为 ‘performance-metrics’ 补齐覆盖”
-
-### 8. 提供修复建议
-
-询问用户：“你希望我为前 N 个问题给出具体的修复编辑建议吗？”（不要自动应用。）
-
-## 运行原则
-
-### 上下文效率
-
-- **最小高信号 token**：聚焦可执行发现，不做穷举式文档复述
-- **渐进式披露**：逐步加载产物，不把全文倾倒进分析
-- **token 高效输出**：发现表最多 50 行，其余做溢出摘要
-- **确定性结果**：在无变更前提下重复运行应得到一致的 ID 与统计
-
-### 分析准则
-
-- **禁止修改文件**（严格只读分析）
-- **禁止臆造缺失章节**（缺失就如实报告）
-- **优先处理宪法违规则**（一律 CRITICAL）
-- **用例子胜过穷举规则**（引用具体实例而不是泛泛而谈）
-- **零问题也要输出报告**（给出覆盖统计并明确通过）
-
-## 上下文
-
-$ARGUMENTS

----
-description: 基于用户需求为当前功能生成一份定制检查清单。
----
-
-## 清单目的：“英文需求的单元测试”
-
-**关键概念（CRITICAL）**：检查清单是**需求写作的单元测试**——用于验证某个领域里需求的质量、清晰度与完整性。
-
-**不是用来做验证/测试**：
-
-- ❌ 不是“验证按钮能否正确点击”
-- ❌ 不是“测试错误处理是否有效”
-- ❌ 不是“确认 API 返回 200”
-- ❌ 不是检查代码/实现是否符合 spec
-
-**用于验证需求质量**：
-
-- ✅ “是否为所有卡片类型定义了视觉层级需求？”（完整性）
-- ✅ “‘突出展示’是否用具体的尺寸/位置进行了量化？”（清晰度）
-- ✅ “悬停态需求在所有可交互元素之间是否一致？”（一致性）
-- ✅ “是否定义了键盘导航的无障碍需求？”（覆盖度）
-- ✅ “spec 是否定义了当 logo 图片加载失败时的行为？”（边界情况）
-
-**类比**：如果把 spec 看作用英文写成的代码，那么检查清单就是它的单元测试套件。你要测试的是需求是否写得好、是否完整、是否无歧义、是否能直接进入实现阶段——而不是测试实现是否正确。
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-在继续之前，你**必须**先考虑用户输入（如果不为空）。
-
-## 执行步骤
-
-1. **准备**：在仓库根目录运行 `.specify/scripts/bash/check-prerequisites.sh --json`，并解析 JSON 中的 FEATURE_DIR 与 AVAILABLE_DOCS 列表。
-   - 所有文件路径必须是绝对路径。
-   - 当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）。
-
-2. **澄清意图（动态）**：最多生成三个初始的上下文澄清问题（不要使用预制问题库）。这些问题必须：
-   - 基于用户的表述 + 从 spec/plan/tasks 中提取到的信号生成
-   - 只询问会实质性改变检查清单内容的信息
-   - 如果 `$ARGUMENTS` 已经明确，则对应问题要逐个跳过
-   - 宁可精确，不求覆盖面
-
-   生成算法：
-   1. 提取信号：功能领域关键词（例如 auth、latency、UX、API）、风险指示词（“critical”“must”“compliance”）、干系人提示（“QA”“review”“security team”）以及显式交付物（“a11y”“rollback”“contracts”）。
-   2. 将信号聚类为候选关注方向（最多 4 个），并按相关性排序。
-   3. 如果未明确，推断可能的受众与使用时机（作者、审阅者、QA、发布）。
-   4. 识别缺失维度：范围宽度、深度/严谨度、风险侧重、排除边界、可量化的验收标准。
-   5. 从以下原型中选择并组织问题：
-      - 范围细化（例如：“是否需要包含与 X、Y 的集成触点，还是仅限本地模块正确性？”）
-      - 风险优先级（例如：“以下哪些潜在风险区域需要强制门禁检查？”）
-      - 深度校准（例如：“这是轻量的 pre-commit 自查清单，还是正式发布门禁？”）
-      - 受众框定（例如：“这份清单仅供作者使用，还是用于 PR 同行评审？”）
-      - 边界排除（例如：“这一轮是否明确排除性能调优条目？”）
-      - 场景类别缺口（例如：“未检测到恢复流程——回滚/部分失败路径是否在范围内？”）
-
-   问题格式规则：
-   - 如果提供选项，生成紧凑表格，列为：选项 | 候选项 | 为什么重要
-   - 选项最多 A–E；如果自由回答更清晰，则不输出表格
-   - 不要让用户重复已经说过的话
-   - 避免臆测分类（不要编造）。不确定时，直接问：“请确认 X 是否属于本次范围。”
-
-   无法互动时的默认值：
-   - 深度：标准
-   - 受众：若与代码相关则默认评审者（PR），否则默认作者
-   - 聚焦：相关性最高的 2 个聚类方向
-
-   输出问题（标记为 Q1/Q2/Q3）。用户回答后：如果仍有 ≥2 类场景（Alternate / Exception / Recovery / Non-Functional domain）不清晰，你可以再追问最多 2 个更有针对性的后续问题（Q4/Q5），并为每个问题给出一行理由（例如：“恢复路径风险仍未明确”）。总问题数不要超过 5 个。若用户明确拒绝更多问题，则跳过加问。
-
-3. **理解用户诉求**：结合 `$ARGUMENTS` 与澄清答案：
-   - 提炼清单主题（例如 security、review、deploy、ux）
-   - 汇总用户明确要求必须包含的条目
-   - 将关注方向映射到分类骨架
-   - 从 spec/plan/tasks 推断缺失上下文（不要编造）
-
-4. **加载功能上下文**：从 FEATURE_DIR 读取：
-   - spec.md：功能需求与范围
-   - plan.md（如果存在）：技术细节与依赖
-   - tasks.md（如果存在）：实现任务
-
-   **上下文加载策略**：
-   - 只加载与当前关注方向相关且必要的部分（避免整文件倾倒）
-   - 长段落优先汇总为简短的场景/需求要点
-   - 使用渐进式披露：仅当发现缺口时再做补充读取
-   - 源文档很大时，用中间摘要条目替代直接嵌入原文
-
-5. **生成检查清单**——创建“需求的单元测试”：
-   - 若 `FEATURE_DIR/checklists/` 不存在，则创建该目录
-   - 生成唯一的检查清单文件名：
-     - 根据领域使用短且有描述性的名称（例如 `ux.md`、`api.md`、`security.md`）
-     - 格式：`[domain].md`
-     - 如果文件已存在，则追加到现有文件
-   - 条目 ID 从 CHK001 开始顺序编号
-   - 每次运行 `/speckit.checklist` 都创建一个新文件（绝不覆盖已有清单）
-
-   **核心原则：测需求，而不是测实现**：
-   每条清单项都**必须**从“需求文本本身”出发，评估：
-   - **Completeness（完整性）**：是否包含所有必要需求？
-   - **Clarity（清晰度）**：需求是否明确且具体、无歧义？
-   - **Consistency（一致性）**：需求之间是否一致、无冲突？
-   - **Measurability（可度量性）**：需求是否能客观验证？
-   - **Coverage（覆盖度）**：是否覆盖所有场景/边界情况？
-
-   **分类结构**——按需求质量维度分组：
-   - **需求完整性**（Requirement Completeness）：是否记录了所有必要需求？
-   - **需求清晰度**（Requirement Clarity）：需求是否具体明确、无歧义？
-   - **需求一致性**（Requirement Consistency）：需求是否相互对齐且无冲突？
-   - **验收标准质量**（Acceptance Criteria Quality）：成功标准是否可度量？
-   - **场景覆盖**（Scenario Coverage）：是否覆盖所有流程/用例？
-   - **边界情况覆盖**（Edge Case Coverage）：是否定义了边界条件？
-   - **非功能需求**（Non-Functional Requirements）：性能/安全/无障碍等是否被明确规定？
-   - **依赖与假设**（Dependencies & Assumptions）：是否记录并验证？
-   - **歧义与冲突**（Ambiguities & Conflicts）：哪些点需要澄清？
-
-   **如何编写清单项——“英文需求的单元测试”**：
-
-   ❌ **错误示例**（在测实现）：
-   - “验证落地页展示 3 张剧集卡片”
-   - “测试桌面端悬停态是否生效”
-   - “确认点击 logo 会跳回首页”
-
-   ✅ **正确示例**（在测需求质量）：
-   - “是否明确规定了精选剧集的数量与布局？”[完整性]
-   - “‘突出展示’是否用具体的尺寸/位置进行了量化？”[清晰度]
-   - “悬停态需求在所有可交互元素之间是否一致？”[一致性]
-   - “是否为所有可交互 UI 定义了键盘导航需求？”[覆盖度]
-   - “当 logo 图片加载失败时，是否规定了兜底行为？”[边界情况]
-   - “是否为异步剧集数据定义了加载态？”[完整性]
-   - “spec 是否定义了存在竞争 UI 元素时的视觉层级？”[清晰度]
-
-   **条目结构（结构规范）**：
-   每条清单项应遵循以下模式：
-   - 用问题句式询问需求质量
-   - 聚焦 spec/plan 中“写了什么/没写什么”
-   - 在方括号中标注质量维度 [Completeness/Clarity/Consistency/etc.]
-   - 检查既有需求时引用 spec 章节 `[Spec §X.Y]`
-   - 检查缺失需求时使用 `[Gap]` 标记
-
-   **按质量维度的示例（维度示例）**：
-
-   Completeness:
-   - “是否为所有 API 失败模式定义了错误处理需求？[Gap]”
-   - “是否为所有可交互元素规定了无障碍需求？[Completeness]”
-   - “是否为响应式布局定义了移动端断点需求？[Gap]”
-
-   Clarity:
-   - “‘加载很快’是否用具体时间阈值量化？[Clarity, Spec §NFR-2]”
-   - “‘相关剧集’的筛选条件是否明确规定？[Clarity, Spec §FR-5]”
-   - “‘突出’是否用可衡量的视觉属性定义？[Ambiguity, Spec §FR-4]”
-
-   Consistency:
-   - “所有页面的导航需求是否一致？[Consistency, Spec §FR-10]”
-   - “落地页与详情页的卡片组件需求是否一致？[Consistency]”
-
-   Coverage:
-   - “是否定义了空状态场景（没有剧集）的需求？[Coverage, Edge Case]”
-   - “是否覆盖了并发用户交互场景？[Coverage, Gap]”
-   - “是否规定了部分数据加载失败时的需求？[Coverage, Exception Flow]”
-
-   Measurability:
-   - “视觉层级需求是否可测量/可验证？[Acceptance Criteria, Spec §FR-1]”
-   - “‘视觉重量均衡’是否能客观验证？[Measurability, Spec §FR-2]”
-
-   **场景分类与覆盖（聚焦需求质量）**：
-   - 检查是否存在以下场景的需求：Primary、Alternate、Exception/Error、Recovery、Non-Functional
-   - 对每个场景类别提问：“[scenario type] 的需求是否完整、清晰且一致？”
-   - 若缺失某类场景：提问“[scenario type] 的需求是有意排除还是遗漏？[Gap]”
-   - 当存在状态变更时，包含韧性/回滚要求：例如“是否定义了迁移失败时的回滚需求？[Gap]”
-
-   **可追溯性要求（Traceability Requirements）**：
-   - 最低要求：≥80% 的条目必须包含至少一个可追溯引用
-   - 每条应引用 spec 章节 `[Spec §X.Y]`，或使用标记：`[Gap]`、`[Ambiguity]`、`[Conflict]`、`[Assumption]`
-   - 若没有 ID 体系：提问“是否建立了需求与验收标准的 ID 体系？[Traceability]”
-
-   **暴露并推动解决问题（需求质量问题）**：
-   围绕“需求文本本身”提问：
-   - 歧义："'fast' 是否用具体指标量化？[Ambiguity, Spec §NFR-1]"
-   - 冲突：“§FR-10 与 §FR-10a 的导航需求是否冲突？[Conflict]”
-   - 假设：“‘播客 API 永远可用’这一假设是否得到验证？[Assumption]”
-   - 依赖：“是否记录了外部播客 API 的需求？[Dependency, Gap]”
-   - 定义缺失：“‘visual hierarchy’ 是否用可度量标准定义？[Gap]”
-
-   **内容收敛（Content Consolidation）**：
-   - 软上限：若候选条目 > 40，按风险/影响优先级筛选
-   - 合并检查同一需求点的近似重复条目
-   - 若低影响边界情况 > 5 个，合并为一条：“边界情况 X、Y、Z 是否在需求中被覆盖？[Coverage]”
-
-   **🚫 绝对禁止**——这些会把它变成“实现测试”，而不是“需求测试”：
-   - ❌ 任何以 “Verify/Test/Confirm/Check” 开头并描述实现行为的条目
-   - ❌ 引用代码执行、用户操作或系统行为
-   - ❌ “显示正确”“工作正常”“符合预期”等模糊描述
-   - ❌ “点击”“跳转”“渲染”“加载”“执行”等实现层动作
-   - ❌ 测试用例、测试计划、QA 流程
-   - ❌ 实现细节（框架、API、算法）
-
-   **✅ 必须使用的句式**——这些才是在测需求质量：
-   - ✅ “是否为 [scenario] 定义/规定/记录了 [requirement type]？”
-   - ✅ “[vague term] 是否用具体标准量化/澄清？”
-   - ✅ “[section A] 与 [section B] 的需求是否一致？”
-   - ✅ “[requirement] 是否能客观测量/验证？”
-   - ✅ “需求是否覆盖了 [edge cases/scenarios]？”
-   - ✅ “spec 是否定义了 [missing aspect]？”
-
-6. **结构参考**：按 `.specify/templates/checklist-template.md` 里的权威模板生成清单（标题、元信息、分类标题、ID 格式）。如果模板不可用，使用：一级标题（H1）+ purpose/created 元信息行 + `##` 分类段落；段落内使用 `- [ ] CHK### <清单项>`，ID 从 CHK001 全局递增。
-
-7. **报告（Report）**：输出生成的清单完整路径、条目数量，并提醒用户每次运行都会创建新文件。总结：
-   - 已选择的关注方向
-   - 深度等级
-   - 角色/时机
-   - 已纳入的用户显式 must-have 条目
-
-**重要**：每次执行 `/speckit.checklist` 都会创建一个用短且有描述性的名称命名的清单文件（如果文件已存在则追加）。这使得：
-
-- 多种类型的检查清单可并存（例如 `ux.md`、`test.md`、`security.md`）
-- 文件名简短易记，并能表达用途
-- 在 `checklists/` 目录中易于识别与定位
-
-为避免杂乱，请使用清晰的类型命名，并在完成后清理过时的清单文件。
-
-## 清单类型示例与样例条目
-
-**UX 需求质量：** `ux.md`
-
-样例条目（测需求，不测实现）：
-
-- “视觉层级需求是否用可度量标准定义？[Clarity, Spec §FR-1]”
-- “UI 元素的数量与位置是否被明确规定？[Completeness, Spec §FR-1]”
-- “交互状态（hover/focus/active）的需求是否一致地被规定？[Consistency]”
-- “是否为所有可交互元素规定了无障碍需求？[Coverage, Gap]”
-- “图片加载失败时的兜底行为是否被规定？[Edge Case, Gap]”
-- “‘突出展示’是否能被客观度量？[Measurability, Spec §FR-4]”
-
-**API 需求质量：** `api.md`
-
-样例条目：
-
-- “是否为所有失败场景规定了错误响应格式？[Completeness]”
-- “限流需求是否用具体阈值量化？[Clarity]”
-- “所有端点的认证需求是否一致？[Consistency]”
-- “是否为外部依赖定义了重试/超时需求？[Coverage, Gap]”
-- “需求中是否记录了版本管理策略？[Gap]”
-
-**性能需求质量：** `performance.md`
-
-样例条目：
-
-- “性能需求是否用具体指标量化？[Clarity]”
-- “是否为所有关键用户旅程定义了性能目标？[Coverage]”
-- “是否规定了不同负载条件下的性能需求？[Completeness]”
-- “性能需求是否能被客观测量？[Measurability]”
-- “高负载场景下的降级需求是否被规定？[Edge Case, Gap]”
-
-**安全需求质量：** `security.md`
-
-样例条目：
-
-- “是否为所有受保护资源规定了认证需求？[Coverage]”
-- “是否为敏感信息定义了数据保护需求？[Completeness]”
-- “是否已文档化威胁模型，并且需求与之对齐？[Traceability]”
-- “安全需求是否与合规义务保持一致？[Consistency]”
-- “是否定义了安全失败/泄露后的响应需求？[Gap, Exception Flow]”
-
-## 反例：不要这样做
-
-**❌ 错误——这些在测实现，不是在测需求：**
-
-```markdown
-- [ ] CHK001 - 验证落地页展示 3 张剧集卡片 [Spec §FR-001]
-- [ ] CHK002 - 测试桌面端悬停态是否正常 [Spec §FR-003]
-- [ ] CHK003 - 确认点击 logo 会跳转回首页 [Spec §FR-010]
-- [ ] CHK004 - 检查相关剧集区域是否展示 3-5 条 [Spec §FR-005]
-```
-
-**✅ 正确——这些在测需求质量：**
-
-```markdown
-- [ ] CHK001 - 是否明确规定了精选剧集的数量与布局？[Completeness, Spec §FR-001]
-- [ ] CHK002 - 是否为所有可交互元素一致地规定了悬停态需求？[Consistency, Spec §FR-003]
-- [ ] CHK003 - 是否为所有可点击的品牌元素明确规定了导航需求？[Clarity, Spec §FR-010]
-- [ ] CHK004 - 是否记录了相关剧集的筛选条件？[Gap, Spec §FR-005]
-- [ ] CHK005 - 是否为异步剧集数据定义了加载态需求？[Gap]
-- [ ] CHK006 - “视觉层级”需求是否能被客观测量？[Measurability, Spec §FR-001]
-```
-
-**关键差异：**
-
-- 错误：测试系统是否工作正常
-- 正确：测试需求是否写得正确
-- 错误：验证行为
-- 正确：验证需求质量
-- 错误：“它是否做了 X？”
-- 正确：“X 是否被清晰规定？”

----
-description: 通过最多 5 个高针对性的澄清问题，识别当前功能 spec 中说明不足的部分，并将答案写回 spec。
-handoffs:
-  - label: 生成技术计划
-    agent: speckit.plan
-    prompt: 为该 spec 生成实现计划。我将使用……
----
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-在继续之前，你**必须**先考虑用户输入（如果不为空）。
-
-## 概述
-
-目标：检测并减少当前功能说明中的歧义与缺失决策点，并将澄清内容直接记录到 spec 文件中。
-
-注意：本澄清流程预计应在调用 `/speckit.plan` 之前运行并完成。如果用户明确表示跳过澄清（例如做探索性验证），你可以继续，但必须提醒下游返工风险会增加。
-
-执行步骤：
-
-1. 在仓库根目录只运行一次 `.specify/scripts/bash/check-prerequisites.sh --json --paths-only`（组合模式：`--json --paths-only` / `-Json -PathsOnly`）。解析最小 JSON 字段：
-   - `FEATURE_DIR`
-   - `FEATURE_SPEC`
-   - （可选）为后续链路保留 `IMPL_PLAN`、`TASKS`
-   - 若 JSON 解析失败，立即终止并提示用户重新运行 `/speckit.specify` 或检查当前功能分支环境
-   - 当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）。
-
-2. 加载当前 spec 文件，并按以下分类做结构化的歧义与覆盖扫描。对每个类别标记状态：清晰 / 部分 / 缺失。生成一份用于排序的内部覆盖图（除非必要，不要输出原始覆盖图）。
-
-   功能范围与行为（Functional Scope & Behavior）：
-   - 核心用户目标与成功标准
-   - 明确的范围外（out-of-scope）声明
-   - 用户角色/人物画像的区分
-
-   领域与数据模型（Domain & Data Model）：
-   - 实体、属性、关系
-   - 身份/唯一性规则
-   - 生命周期/状态流转
-   - 数据量/规模假设
-
-   交互与 UX 流程（Interaction & UX Flow）：
-   - 关键用户旅程/操作序列
-   - 错误/空/加载状态
-   - 无障碍或本地化说明
-
-   非功能质量属性（Non-Functional Quality Attributes）：
-   - 性能（延迟、吞吐目标）
-   - 可扩展性（水平/垂直、上限）
-   - 可靠性与可用性（可用率、恢复预期）
-   - 可观测性（日志、指标、链路追踪信号）
-   - 安全与隐私（authN/Z、数据保护、威胁假设）
-   - 合规/监管约束（如有）
-
-   集成与外部依赖（Integration & External Dependencies）：
-   - 外部服务/API 与失败模式
-   - 数据导入/导出格式
-   - 协议/版本假设
-
-   边界情况与失败处理（Edge Cases & Failure Handling）：
-   - 负向场景
-   - 限流/节流
-   - 冲突解决（例如并发编辑）
-
-   约束与取舍（Constraints & Tradeoffs）：
-   - 技术约束（语言、存储、托管）
-   - 明确的取舍或被拒绝的备选方案
-
-   术语与一致性（Terminology & Consistency）：
-   - 规范术语表词条
-   - 避免使用的同义词/废弃术语
-
-   完成信号（Completion Signals）：
-   - 验收标准可测试性
-   - 可量化的完成定义（Definition of Done）风格指标
-
-   杂项/占位符（Misc / Placeholders）：
-   - TODO 标记/未决决策
-   - 未量化的模糊形容词（例如 “robust”“intuitive”）
-
-   对于状态为“部分”或“缺失”的类别，除非满足以下情况，否则应加入一个候选提问点：
-   - 澄清不会实质性改变实现或验证策略
-   - 信息更适合延后到规划阶段再确定（内部记录即可）
-
-3. 在内部生成一个候选澄清问题的优先队列（最多 5 个）。不要一次性全部输出。约束如下：
-    - 全会话最多 10 个问题。
-    - 每个问题必须能用以下任一方式回答：
-       - 简短的多选项（2–5 个明确且互斥的选项），或
-       - 一个词/短语（明确限制：“回答不超过 5 个词”）。
-    - 只包含那些会实质影响架构、数据建模、任务拆分、测试设计、UX 行为、运维就绪或合规验证的问题。
-    - 保持类别覆盖均衡：优先覆盖高影响且未解决的类别；不要在一个高影响领域（例如安全策略）未解决时，去问两个低影响问题。
-    - 排除已回答的问题、琐碎的风格偏好、或 plan 层面的执行细节（除非阻塞正确性）。
-    - 优先提出能降低下游返工风险或避免验收测试错位的问题。
-    - 若未解决类别超过 5 个，按（Impact * Uncertainty）启发式选取前 5 个。
-
-4. 顺序提问循环（交互式）：
-    - 每次**只**呈现一个问题。
-    - 对于多选题：
-       - **分析所有选项**，并基于以下因素确定**最合适的选项**：
-          - 该项目类型的最佳实践
-          - 类似实现的常见模式
-          - 风险降低（安全、性能、可维护性）
-          - spec 中可见的项目目标或约束是否匹配
-       - 在顶部突出展示你的**推荐选项**并给出清晰理由（1–2 句说明为何这是最佳选择）。
-       - 格式：`**推荐：** 选项 [X] - <理由>`
-       - 然后用 Markdown 表格列出所有选项：
-
-       | 选项 | 描述 |
-       |------|------|
-       | A | <选项 A 描述> |
-       | B | <选项 B 描述> |
-       | C | <选项 C 描述>（如需可加 D/E，最多 5 个） |
-       | Short | 提供不同的短答案（<=5 个词）（仅在需要自由回答时保留） |
-
-       - 表格后追加：`你可以回复选项字母（例如 “A”），也可以回复 “yes” 或 “recommended” 来接受推荐，或给出你自己的短答案。`
-    - 对于短答案形式（没有有意义的离散选项）：
-       - 基于最佳实践与上下文给出你的**建议答案**。
-       - 格式：`**建议：** <你的建议答案> - <简短理由>`
-       - 然后输出：`格式：短答案（<=5 个词）。你可以回复 “yes” 或 “suggested” 来接受建议，或提供你自己的答案。`
-    - 用户回答后：
-       - 若用户回复 “yes”“recommended” 或 “suggested”，使用你之前给出的推荐/建议作为最终答案。
-       - 否则，校验回答是否能映射到某个选项或满足 <=5 word 的限制。
-       - 若仍有歧义，快速追问以消歧（仍算同一个问题，不要推进到下一题）。
-       - 一旦答案满足要求，将其记录到工作记忆（先不要写盘），并进入队列里的下一个问题。
-    - 在以下条件下停止继续提问：
-       - 关键歧义已提前全部解决（剩余问题不再必要），或
-       - 用户表示结束（“done”“good”“no more”），或
-       - 已问满 5 个问题。
-    - 不要提前泄露后续排队的问题。
-    - 如果一开始就没有有效问题，立即报告“未发现值得正式澄清的关键歧义”。
-
-5. 每次采纳答案后的集成（增量更新方式）：
-    - 在内存中维护一份 spec 表示（会话开始时只加载一次）以及原始文件内容。
-    - 本次会话第一次写入时：
-       - 确保存在 `## Clarifications` 章节（若缺失，则按 spec 模板在最高层级的背景/概览段落之后创建）。
-       - 在其下创建（若不存在）今日对应的 `### Session YYYY-MM-DD` 小标题。
-    - 每次采纳后立即追加一行 bullet：`- Q: <问题> → A: <最终答案>`。
-    - 随后立即将澄清内容应用到最合适的章节：
-       - 功能歧义 → 更新/新增 Functional Requirements 下的 bullet。
-       - 用户交互/角色区分 → 在 User Stories 或 Actors 子章节（如存在）写入明确的角色、约束或场景。
-       - 数据形态/实体 → 更新 Data Model（新增字段/类型/关系时保持原有顺序），并用简短语句注明新增约束。
-       - 非功能约束 → 在 Non-Functional / Quality Attributes 中新增或修改可度量的标准（把模糊形容词转换为指标或明确目标）。
-       - 边界情况/负向流程 → 在 Edge Cases / Error Handling 下新增 bullet（或按模板占位创建对应小节）。
-       - 术语冲突 → 统一 spec 全文用词；仅在必要时保留旧称，并只在一个地方追加 `（此前称为“X”）`。
-    - 若澄清答案使先前的模糊表述失效，应替换旧表述而不是重复追加；不要留下过时的矛盾文本。
-    - 每次集成后都保存 spec 文件，尽量降低上下文丢失风险（原子覆盖写入）。
-    - 保持格式：不要重排无关章节；保持标题层级不变。
-    - 每次插入的澄清内容都要尽量精炼且可验证（避免叙事化扩散）。
-
-6. 校验（每次写入后执行，最终再做一次整体检查）：
-   - Clarifications 会话中每个被采纳答案只对应一条 bullet（不重复）。
-   - 总提问（被采纳）数量 ≤ 5。
-   - 更新后的章节中不应残留原本要被新答案解决的模糊占位符。
-   - 不应遗留自相矛盾的旧表述（扫描并移除已失效的备选说法）。
-   - Markdown 结构合法；仅允许新增标题：`## Clarifications`、`### Session YYYY-MM-DD`。
-   - 术语一致：所有更新章节使用同一套规范术语。
-
-7. 将更新后的 spec 写回 `FEATURE_SPEC`。
-
-8. 报告完成（当提问循环结束或被提前终止后）：
-   - 已提问并采纳的数量。
-   - 更新后的 spec 路径。
-   - 涉及修改的章节（列出名称）。
-   - 覆盖摘要表：列出每个分类及状态：Resolved（原为 Partial/Missing 且已补齐）、Deferred（超出配额或更适合留到规划阶段）、Clear（已足够清晰）、Outstanding（仍 Partial/Missing 但影响低）。
-   - 若仍存在 Outstanding 或 Deferred：建议是直接进入 `/speckit.plan`，还是在 plan 之后再跑一次 `/speckit.clarify`。
-   - 建议下一条命令。
-
-行为规则：
-
-- 如果未发现有意义的歧义（或所有候选问题影响都很低），则回复：“未发现值得正式澄清的关键歧义。”并建议继续。
-- 如果缺少 spec 文件，提示用户先运行 `/speckit.specify`（不要在这里新建 spec）。
-- 总提问数不要超过 5 个（同一问题的澄清重试不算新问题）。
-- 除非缺失信息会阻塞功能澄清，否则避免提出臆测性的技术栈问题。
-- 尊重用户的提前终止信号（“stop”“done”“proceed”）。
-- 若因覆盖完整而未提问，输出一份精简覆盖摘要（所有分类为 Clear）并建议继续推进。
-- 若配额用尽但仍有未解决的高影响分类，在 Deferred 下明确标记并说明原因。
-
-用于优先级判断的上下文：$ARGUMENTS

----
-description: 通过交互式或提供的原则输入创建/更新项目宪法，并确保所有依赖模板保持同步。
-handoffs:
-  - label: 生成规格说明
-    agent: speckit.specify
-    prompt: 基于更新后的宪法生成功能规格说明。我想要构建……
----
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-在继续之前，你**必须**先考虑用户输入（如果不为空）。
-
-## 概述
-
-你正在更新 `.specify/memory/constitution.md` 中的项目宪法。该文件是一个模板（Template），包含方括号占位符（例如 `[PROJECT_NAME]`、`[PRINCIPLE_1_NAME]`）。你的工作是：（a）收集/推导具体值，（b）精准填充模板，（c）将所有修订同步传播到依赖产物中。
-
-按以下流程执行：
-
-1. 加载 `.specify/memory/constitution.md` 中现有的宪法模板。
-   - 识别所有形如 `[ALL_CAPS_IDENTIFIER]` 的占位符 token。
-   **重要**：用户需要的原则数量可能少于或多于模板默认数量。如果用户指定了数量，必须尊重该数量，并在通用模板结构下调整文档内容。
-
-2. 收集/推导占位符的具体值：
-   - 若用户输入（对话中）已提供取值，直接使用。
-   - 否则从仓库上下文推断（README、文档、若存在则参考仓库内嵌的旧宪法内容）。
-   - 治理日期规则：`RATIFICATION_DATE` 为原始生效日期（未知则询问或标记 TODO）；`LAST_AMENDED_DATE` 若本次有修改则为今天，否则保留原值。
-   - `CONSTITUTION_VERSION` 必须按语义化版本规则递增：
-     - MAJOR：不向后兼容的治理/原则移除或重定义。
-     - MINOR：新增原则/章节，或对既有指导做实质性扩展。
-     - PATCH：澄清、措辞、错别字修正、非语义性的精炼。
-   - 若版本升级类型不明确，在最终落盘前先给出判断理由。
-
-3. 起草更新后的宪法内容：
-   - 用具体文本替换每个占位符（不应残留方括号 token；除非项目明确决定暂不定义，并对每个保留项给出理由）。
-   - 保持标题层级不变；占位符被替换后，注释可移除，除非该注释仍对理解有帮助。
-   - 确保每条原则包含：简短名称行、概括不可协商规则的段落（或要点列表），若理由不明显则补充明确的理由说明。
-   - 确保治理（Governance）章节包含：修订流程、版本策略、合规审查期望。
-
-4. 一致性传播清单（把旧清单转为可执行校验项）：
-   - 阅读 `.specify/templates/plan-template.md`，确保其中的“宪法检查”或规则与更新后的原则一致。
-   - 阅读 `.specify/templates/spec-template.md`，校验范围/需求对齐；若宪法新增/移除必填章节或约束，则同步更新模板。
-   - 阅读 `.specify/templates/tasks-template.md`，确保任务分类能体现新增/移除的原则驱动任务类型（例如可观测性、版本策略、测试纪律）。
-   - 阅读 `.specify/templates/commands/*.md` 下的每个命令文件（包含本文件），确保通用指导中不残留过时的 agent 特定引用（例如仅写 CLAUDE）。
-   - 阅读运行/使用指导文档（例如 `README.md`、`docs/quickstart.md`，或存在的 agent 专属指导文件），同步更新与宪法变更相关的引用。
-
-5. 生成“同步影响报告”（更新后，作为 HTML 注释插入到宪法文件顶部）：
-   - 版本变更：旧版本 → 新版本
-   - 修改过的原则列表（若重命名则写 旧标题 → 新标题）
-   - 新增章节
-   - 移除章节
-   - 需要更新的模板列表（✅ 已更新 / ⚠ 待处理），并附文件路径
-   - 若有占位符被刻意延期，列出后续 TODO
-
-6. 最终输出前校验：
-   - 不残留任何无法解释的方括号占位符 token。
-   - 版本行与同步影响报告一致。
-   - 日期使用 ISO 格式 YYYY-MM-DD。
-   - 原则陈述应可验证、可测试，避免含糊措辞（必要时将“should”替换为 MUST/SHOULD，并给出理由）。
-
-7. 将完成的宪法内容写回 `.specify/memory/constitution.md`（覆盖写入）。
-
-8. 输出给用户的最终总结应包含：
-   - 新版本号与升级理由。
-   - 需要人工跟进的文件（如有）。
-   - 建议的提交信息（例如 `docs: amend constitution to vX.Y.Z (principle additions + governance update)`）。
-
-格式与样式要求：
-
-- 标题层级必须与模板完全一致（不要升/降级标题）。
-- 适度换行以保持可读性（理想情况下 <100 字符），但不要为了硬性限制造成生硬断行。
-- 章节之间保持一个空行。
-- 避免行尾空格。
-
-如果用户只提供部分更新（例如只修改一条原则），也要照样执行校验与版本决策步骤。
-
-如果缺少关键信息（例如确实不知道 ratification date），插入 `TODO(<FIELD_NAME>): explanation`，并在同步影响报告的延期项（deferred）中列出。
-
-不要创建新的模板；始终在现有的 `.specify/memory/constitution.md` 文件上操作。

----
-description: 通过处理并执行 tasks.md 中定义的所有任务，落实实现计划
----
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-在继续之前，你**必须**先考虑用户输入（如果不为空）。
-
-## 概述
-
-1. 在仓库根目录运行一次 `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks`，并解析 JSON 中的 FEATURE_DIR 与 AVAILABLE_DOCS 列表。所有路径必须是绝对路径。当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）。
-
-2. **检查检查清单状态**（如果存在 FEATURE_DIR/checklists/）：
-   - 扫描 checklists/ 目录下的所有清单文件
-   - 对每个清单统计：
-     - 总条目：匹配 `- [ ]` 或 `- [X]` 或 `- [x]` 的所有行
-     - 已完成条目：匹配 `- [X]` 或 `- [x]` 的行
-     - 未完成条目：匹配 `- [ ]` 的行
-   - 生成状态表：
-
-     ```text
-     | Checklist | Total | Completed | Incomplete | Status |
-     |-----------|-------|-----------|------------|--------|
-     | ux.md     | 12    | 12        | 0          | ✓ PASS |
-     | test.md   | 8     | 5         | 3          | ✗ FAIL |
-     | security.md | 6   | 6         | 0          | ✓ PASS |
-     ```
-
-  - 计算总体状态：
-    - **PASS**：所有清单的未完成条目为 0
-    - **FAIL**：存在至少一个清单有未完成条目
-
-  - **如果存在未完成清单**：
-    - 展示状态表与未完成数量
-    - **停止**并询问：“有些检查清单尚未完成。是否仍要继续实现？（yes/no）”
-    - 等待用户回复后再继续
-    - 若用户回复 “no”“wait” 或 “stop”，则终止执行
-    - 若用户回复 “yes”“proceed” 或 “continue”，则进入第 3 步
-
-  - **如果所有清单都已完成**：
-    - 展示所有清单通过的状态表
-    - 自动进入第 3 步
-
-3. 加载并分析实现上下文：
-  - **必须**：读取 tasks.md 获取完整任务列表与执行计划
-  - **必须**：读取 plan.md 获取技术栈、架构与文件结构
-  - **如果存在**：读取 data-model.md 获取实体与关系
-  - **如果存在**：读取 contracts/ 获取 API 规范与测试要求
-  - **如果存在**：读取 research.md 获取技术决策与约束
-  - **如果存在**：读取 quickstart.md 获取集成场景
-
-4. **项目初始化校验**：
-   - **必须**：基于实际项目情况创建/校验 ignore 文件：
-
-  **检测与创建逻辑**：
-  - 通过下列命令是否成功来判断仓库是否是 git 仓库（如果是，则创建/校验 .gitignore）：
-
-     ```sh
-     git rev-parse --git-dir 2>/dev/null
-     ```
-
-  - 检查是否存在 Dockerfile* 或 plan.md 中提到 Docker → 创建/校验 .dockerignore
-  - 检查是否存在 .eslintrc* → 创建/校验 .eslintignore
-  - 检查是否存在 eslint.config.* → 确保配置中的 `ignores` 覆盖所需模式
-  - 检查是否存在 .prettierrc* → 创建/校验 .prettierignore
-  - 检查是否存在 .npmrc 或 package.json →（若要发布）创建/校验 .npmignore
-  - 检查是否存在 terraform 文件（*.tf）→ 创建/校验 .terraformignore
-  - 检查是否需要 .helmignore（存在 helm charts）→ 创建/校验 .helmignore
-
-  **如果 ignore 文件已存在**：校验其包含关键模式，只追加缺失且重要的模式
-  **如果 ignore 文件不存在**：按检测到的技术栈创建包含完整模式集合的文件
-
-  **按技术栈的常见模式**（来自 plan.md 的技术栈）：
-   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
-   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
-   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
-   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
-   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
-   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
-   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
-   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
-   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
-   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
-   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `Makefile`, `config.log`, `.idea/`, `*.log`, `.env*`
-   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
-   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
-   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
-
-  **工具特定模式**：
-   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
-   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
-   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
-   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
-   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
-
-5. 解析 tasks.md 结构并提取：
-   - **任务阶段**：初始化、测试、核心、集成、打磨
-   - **任务依赖**：串行与并行的执行规则
-   - **任务细节**：ID、描述、文件路径、并行标记 [P]
-   - **执行流程**：顺序与依赖要求
-
-6. 按任务计划执行实现：
-   - **按阶段执行**：完成当前阶段后再进入下一阶段
-   - **遵守依赖**：串行任务按顺序执行；并行任务 [P] 可同时执行
-   - **遵循 TDD**：若存在测试任务，先执行测试任务再执行对应实现任务
-   - **按文件协调**：影响同一文件的任务必须串行执行
-   - **阶段校验点**：进入下一阶段前先校验当前阶段是否完成
-
-7. 实现执行规则：
-   - **先做初始化**：初始化项目结构、依赖、配置
-   - **先写测试再写代码**：如果需要为契约、实体与集成场景编写测试
-   - **核心开发**：实现模型、服务、CLI 命令、端点
-   - **集成工作**：数据库连接、中间件、日志、外部服务
-   - **打磨与校验**：单元测试、性能优化、文档
-
-8. 进度跟踪与错误处理：
-   - 每完成一个任务都汇报进度
-   - 任意非并行任务失败时立即停止执行
-   - 并行任务 [P] 允许继续已成功任务，并汇报失败项
-   - 提供带上下文的清晰错误信息，便于定位
-   - 若实现无法继续，给出明确的下一步建议
-   - **重要**：任务完成后，务必在 tasks 文件中用 [X] 勾掉该任务
-
-9. 完成校验：
-   - 确认所有必需任务都已完成
-   - 检查实现的功能是否与原始 spec 一致
-   - 校验测试通过且覆盖率满足要求
-   - 确认实现遵循技术计划
-   - 汇报最终状态并总结已完成工作
-
-注意：本命令假设 tasks.md 中已存在完整的任务拆分。如果任务不完整或缺失，应建议先运行 `/speckit.tasks` 重新生成任务列表。

----
-description: 使用计划模板执行实现规划流程，并生成设计产物。
-handoffs:
-  - label: 生成任务列表
-    agent: speckit.tasks
-    prompt: 将实现计划拆分为可执行任务
-    send: true
-  - label: 生成检查清单
-    agent: speckit.checklist
-    prompt: 为以下领域生成一份检查清单……
----
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-在继续之前，你**必须**先考虑用户输入（如果不为空）。
-
-## 概述
-
-1. **准备**：在仓库根目录运行 `.specify/scripts/bash/setup-plan.sh --json`，并解析 JSON 中的 FEATURE_SPEC、IMPL_PLAN、SPECS_DIR、BRANCH。当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）。
-
-2. **加载上下文**：读取 FEATURE_SPEC 与 `.specify/memory/constitution.md`。加载 IMPL_PLAN 模板（已复制到目标位置）。
-
-3. **执行规划流程**：按 IMPL_PLAN 模板结构完成：
-   - 填写技术上下文（未知项标记为 “NEEDS CLARIFICATION”）
-   - 从宪法中填写“宪法检查”小节
-   - 评估门禁（若存在未经合理解释的违规则 ERROR）
-   - Phase 0：生成 research.md（解决所有 NEEDS CLARIFICATION）
-   - Phase 1：生成 data-model.md、contracts/、quickstart.md
-   - Phase 1：通过运行 agent 脚本更新 agent 上下文
-   - 设计完成后重新评估“宪法检查”
-
-4. **停止并汇报**：命令在 Phase 2 规划后结束。汇报分支名、IMPL_PLAN 路径与生成的产物。
-
-## 阶段
-
-### Phase 0：大纲与调研
-
-1. **从上面的技术上下文中提取未知项**：
-   - 每个 NEEDS CLARIFICATION → 一条调研任务
-   - 每个依赖 → 一条最佳实践任务
-   - 每个集成点 → 一条模式/方案任务
-
-2. **生成并分发调研 agent**：
-
-   ```text
-   对于技术上下文中的每个未知项：
-     任务："为 {feature context} 调研 {unknown}"
-   对于每个技术选型：
-     任务："为 {domain} 场景寻找 {tech} 的最佳实践"
-   ```
-
-3. **在 `research.md` 中汇总结论**，格式为：
-   - 决策（Decision）：[选择了什么]
-   - 理由（Rationale）：[为什么这样选]
-   - 备选方案（Alternatives）：[还评估了什么]
-
-**输出**：research.md，且所有 NEEDS CLARIFICATION 已解决
-
-### Phase 1：设计与契约
-
-**前置条件：** `research.md` 已完成
-
-1. **从功能 spec 中提取实体** → `data-model.md`：
-   - 实体名称、字段、关系
-   - 来自需求的校验规则
-   - 若适用：状态流转
-
-2. **从功能需求生成 API 契约**：
-   - 每个用户动作 → 一个 endpoint
-   - 使用标准 REST/GraphQL 模式
-   - 输出 OpenAPI/GraphQL schema 到 `/contracts/`
-
-3. **更新 agent 上下文**：
-   - 运行 `.specify/scripts/bash/update-agent-context.sh cursor-agent`
-   - 脚本会检测当前使用的是哪个 AI agent
-   - 更新对应的 agent 专属上下文文件
-   - 只追加本次计划中新引入的技术
-   - 保留标记区间内的人工补充内容
-
-**输出**：data-model.md、/contracts/*、quickstart.md、agent 专属上下文文件
-
-## 关键规则
-
-- 使用绝对路径
-- 门禁失败或存在未解决澄清项时直接 ERROR

----
-description: 根据自然语言的功能描述创建或更新功能规格说明（spec）。
-handoffs:
-  - label: 生成技术计划
-    agent: speckit.plan
-    prompt: 为该 spec 生成实现计划。我将使用……
-  - label: 澄清 spec 需求
-    agent: speckit.clarify
-    prompt: 澄清规格说明需求
-    send: true
----
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-在继续之前，你**必须**先考虑用户输入（如果不为空）。
-
-## 概述
-
-触发消息里，用户在 `/speckit.specify` 之后输入的文本**就是**功能描述。即使下面字面出现 `$ARGUMENTS`，也要假设在本次对话中你始终能拿到该描述。除非用户执行了空命令，否则不要让用户重复描述。
-
-基于该功能描述，执行以下流程：
-
-1. **为分支生成一个精炼短名**（2–4 个词）：
-   - 分析功能描述并提取最有意义的关键词
-   - 生成一个 2–4 词的 short name，能够概括功能核心
-   - 尽量使用“动作-名词”格式（例如 "add-user-auth"、"fix-payment-bug"）
-   - 保留技术术语与缩写（OAuth2、API、JWT 等）
-   - 保持简洁，但要足够描述性，能一眼看懂功能概念
-   - 示例：
-     - “我想增加用户认证功能” → "user-auth"
-     - “为 API 接入 OAuth2 集成” → "oauth2-api-integration"
-     - “创建一个数据分析看板” → "analytics-dashboard"
-     - “修复支付处理超时问题” → "fix-payment-timeout"
-
-2. **创建新分支前检查是否已存在同名分支**：
-
-   a. 先拉取所有远端分支，确保信息最新：
-
-      ```bash
-      git fetch --all --prune
-      ```
-
-   b. 在所有来源中查找该 short-name 的最大功能编号：
-      - 远端分支：`git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
-      - 本地分支：`git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
-      - Specs 目录：检查匹配 `specs/[0-9]+-<short-name>` 的目录
-
-   c. 计算下一个可用编号：
-      - 从三个来源中提取所有编号
-      - 找到最大编号 N
-      - 新分支编号使用 N+1
-
-   d. 使用计算出的编号与 short-name 运行脚本 `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"`：
-      - 传入 `--number N+1` 与 `--short-name "your-short-name"`，并携带功能描述
-      - Bash 示例：`.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"`
-      - PowerShell 示例：`.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
-
-   **重要**：
-   - 必须检查三处来源（远端分支、本地分支、specs 目录）以找到最大编号
-   - 只匹配与 short-name 完全一致的分支/目录模式
-   - 如果没有找到与 short-name 匹配的分支/目录，从编号 1 开始
-   - 每个功能只允许运行该脚本一次
-   - JSON 会作为终端输出打印出来 —— 获取路径等信息时必须以该 JSON 为准
-   - JSON 输出里会包含 BRANCH_NAME 与 SPEC_FILE 路径
-   - 当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）
-
-3. 加载 `.specify/templates/spec-template.md` 以了解必需章节。
-
-4. 按以下执行流程生成 spec：
-
-    1. 从输入中解析用户描述
-       如果为空：ERROR "未提供功能描述"
-    2. 从描述中提取关键概念
-       识别：参与者（actors）、动作（actions）、数据（data）、约束（constraints）
-    3. 对于不清晰的点：
-       - 基于上下文与行业常见做法做出有依据的默认判断
-       - 仅在以下情况下用 [NEEDS CLARIFICATION: 具体问题] 标记：
-         - 选择会显著影响功能范围或用户体验
-         - 存在多个合理解释且影响不同
-         - 不存在合理默认值
-       - **限制：总计最多 3 个 [NEEDS CLARIFICATION] 标记**
-       - 按影响优先级排序澄清：范围 > 安全/隐私 > 用户体验 > 技术细节
-   4. 填写“用户场景与验收”章节
-       如果没有明确用户流程：ERROR "无法确定用户场景"
-   5. 生成“需求 → 功能需求”
-       每条需求都必须可测试
-       对未明确的细节使用合理默认值（并在“假设（Assumptions）”章节记录假设）
-   6. 定义“成功标准”
-       产出可度量、与具体技术无关的结果
-       同时包含量化指标（时间、性能、容量）与定性指标（用户满意度、任务完成率）
-       每条标准必须在不依赖实现细节的情况下可验证
-   7. 识别关键实体（当功能涉及数据时）
-   8. 返回：SUCCESS（spec 已可进入规划阶段）
-
-5. 按模板结构将 spec 写入 SPEC_FILE：用功能描述（arguments）推导的具体内容替换占位符，同时保持章节顺序与标题不变。
-
-6. **spec 质量校验**：初版 spec 写入后，按质量标准进行校验：
-
-   a. **创建 spec 质量清单**：按检查清单模板结构，在 `FEATURE_DIR/checklists/requirements.md` 生成清单文件，并包含以下校验项：
-
-      ```markdown
-      # spec 质量清单：[FEATURE NAME]
-
-      **目的**：在进入规划阶段前，校验 spec 的完整性与质量
-      **创建时间**：[DATE]
-      **功能**：[Link to spec.md]
-
-      ## 内容质量
-
-      - [ ] 不包含实现细节（语言、框架、API）
-      - [ ] 聚焦用户价值与业务需求
-      - [ ] 面向非技术干系人撰写
-      - [ ] 所有必填章节已完成
-
-      ## 需求完整性
-
-      - [ ] 不再遗留 [NEEDS CLARIFICATION] 标记
-      - [ ] 需求可测试且无歧义
-      - [ ] 成功标准可度量
-      - [ ] 成功标准与技术实现无关（不包含实现细节）
-      - [ ] 所有验收场景已定义
-      - [ ] 已识别边界情况
-      - [ ] 范围边界清晰
-      - [ ] 已识别依赖与假设
-
-      ## 功能就绪度
-
-      - [ ] 所有功能需求都有清晰的验收标准
-      - [ ] 用户场景覆盖主流程
-      - [ ] 功能满足“成功标准”中定义的可度量结果
-      - [ ] spec 中没有渗入实现细节
-
-      ## 备注
-
-      - 标记为未完成的条目，需要先更新 spec，再进入 `/speckit.clarify` 或 `/speckit.plan`
-      ```
-
-   b. **执行校验**：逐条对照清单检查 spec：
-      - 对每条清单项判定通过/失败
-      - 记录发现的具体问题（引用 spec 的相关段落）
-
-   c. **处理校验结果**：
-
-      - **如果全部通过**：将清单标记为完成，并进入下一步
-
-      - **如果存在失败项（不含 [NEEDS CLARIFICATION]）**：
-        1. 列出失败项与具体问题
-        2. 更新 spec 逐项修复
-        3. 重新执行校验直到全部通过（最多 3 次迭代）
-        4. 若 3 次后仍未通过，在清单备注中记录剩余问题并提醒用户
-
-      - **如果仍存在 [NEEDS CLARIFICATION] 标记**：
-        1. 从 spec 中提取所有 [NEEDS CLARIFICATION: ...] 标记
-        2. **限制检查**：如果标记超过 3 个，只保留最关键的 3 个（按范围/安全/UX 影响排序），其余做有依据的默认判断
-        3. 对每个需要澄清的问题（最多 3 个），按以下格式向用户给出选项：
-
-           ```markdown
-           ## 问题 [N]：[Topic]
-
-           **上下文**：[引用 spec 相关段落]
-
-           **需要确认的信息**：[来自 NEEDS CLARIFICATION 标记的具体问题]
-
-           **建议答案**：
-
-           | 选项 | 答案 | 影响 |
-           |------|------|------|
-           | A | [建议答案 1] | [对该功能的影响] |
-           | B | [建议答案 2] | [对该功能的影响] |
-           | C | [建议答案 3] | [对该功能的影响] |
-           | Custom | 提供你自己的答案 | [说明如何提供自定义输入] |
-
-           **你的选择**：_[等待用户回复]_
-           ```
-
-        4. **关键（CRITICAL）- 表格格式**：确保 Markdown 表格格式正确：
-           - 使用一致的空格并对齐竖线
-           - 每个单元格内容两侧要有空格：`| Content |` 而不是 `|Content|`
-           - 表头分隔线至少 3 个短横线：`|--------|`
-           - 确认表格在 Markdown 预览中能正确渲染
-        5. 问题编号按顺序排列（Q1、Q2、Q3，最多 3 个）
-        6. 在等待用户回复之前，一次性展示全部问题
-        7. 等待用户按问题编号回复选项（例如 “Q1: A, Q2: Custom - [details], Q3: B”）
-        8. 用用户选择/提供的答案替换每个 [NEEDS CLARIFICATION] 标记并更新 spec
-        9. 当所有澄清完成后重新执行校验
-
-   d. **更新清单**：每次校验迭代后，更新清单文件中的通过/失败状态
-
-7. 汇报完成情况：分支名、spec 文件路径、清单结果，以及进入下一阶段（`/speckit.clarify` 或 `/speckit.plan`）的就绪情况。
-
-**注意（NOTE）**：脚本会先创建并切换到新分支，并在写入前初始化 spec 文件。
-
-## 通用指南
-
-## 快速指南
-
-- 聚焦用户需要**什么（WHAT）**与**为什么（WHY）**。
-- 避免描述如何实现（不写技术栈、API、代码结构）。
-- 面向业务/非技术干系人撰写，而不是只写给开发看。
-- 不要在 spec 里内嵌任何检查清单；清单由单独命令生成。
-
-### 章节要求
-
-- **必填章节**：每个功能都必须完成
-- **可选章节**：只在与功能相关时保留
-- 如果某个章节不适用，直接删除（不要留下 “N/A”）
-
-### 面向 AI 生成
-
-当根据用户输入生成该 spec 时：
-
-1. **做出有依据的默认判断**：用上下文、行业标准与常见模式补齐缺口
-2. **记录假设**：在 Assumptions 章节写下合理默认值
-3. **限制澄清点**：最多 3 个 [NEEDS CLARIFICATION] 标记，只用于以下关键决策：
-   - 会显著影响功能范围或用户体验
-   - 存在多种合理解释且影响不同
-   - 没有合理默认值
-4. **澄清优先级**：范围 > 安全/隐私 > 用户体验 > 技术细节
-5. **像测试人员一样思考**：任何模糊需求都应在“可测试且无歧义”项上失败
-6. **常见需要澄清的领域**（仅当不存在合理默认值时才问）：
-   - 功能范围与边界（包含/排除哪些用例）
-   - 用户类型与权限（存在多种冲突解释时）
-   - 安全/合规要求（法律/财务层面影响显著时）
-
-**合理默认值示例**（这些通常不必询问用户）：
-
-- 数据保留：该领域的行业通用做法
-- 性能目标：除非用户明确要求，否则按常规 web/移动端应用预期
-- 错误处理：用户友好的提示，并提供合适兜底
-- 认证方式：web 应用默认使用 session 或 OAuth2 的常见方式
-- 集成模式：除非另有说明，默认使用 RESTful API
-
-### “成功标准”编写指南
-
-成功标准必须满足：
-
-1. **可度量**：包含具体指标（时间、百分比、数量、比率等）
-2. **与技术无关**：不提框架、语言、数据库或工具
-3. **以用户为中心**：从用户/业务视角描述结果，而不是系统内部指标
-4. **可验证**：不依赖实现细节也能测试/验证
-
-**好的示例**：
-
-- "用户可在 3 分钟内完成结账"
-- "系统支持 10,000 并发用户"
-- "95% 的搜索在 1 秒内返回结果"
-- "任务完成率提升 40%"
-
-**不好的示例**（偏实现细节）：
-
-- "API 响应时间低于 200ms"（太技术化；应改为“用户几乎瞬时看到结果”这类用户侧指标）
-- "数据库可处理 1000 TPS"（实现细节；应改为用户侧可感知/可验收的指标）
-- "React 组件渲染高效"（框架相关）
-- "Redis 缓存命中率高于 80%"（技术相关）

----
-description: 基于现有设计产物，为该功能生成可执行、按依赖排序的 tasks.md。
-handoffs:
-  - label: 一致性分析
-    agent: speckit.analyze
-    prompt: 执行项目一致性分析
-    send: true
-  - label: 分阶段实现
-    agent: speckit.implement
-    prompt: 按阶段开始实现
-    send: true
----
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-在继续之前，你**必须**先考虑用户输入（如果不为空）。
-
-## 概述
-
-1. **准备**：在仓库根目录运行 `.specify/scripts/bash/check-prerequisites.sh --json` 并解析 FEATURE_DIR 与 AVAILABLE_DOCS 列表。所有路径必须是绝对路径。当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）。
-
-2. **加载设计文档**：从 FEATURE_DIR 读取：
-   - **必需**：plan.md（技术栈、依赖库、结构）、spec.md（带优先级的用户故事）
-   - **可选**：data-model.md（实体）、contracts/（API 端点）、research.md（决策）、quickstart.md（测试场景）
-   - 注意：并非所有项目都有全部文档。应基于当前可用文档生成任务。
-
-3. **执行任务生成流程**：
-   - 加载 plan.md，提取技术栈、依赖库与项目结构
-   - 加载 spec.md，提取带优先级的用户故事（P1、P2、P3 等）
-   - 如果存在 data-model.md：提取实体并映射到用户故事
-   - 如果存在 contracts/：将端点映射到用户故事
-   - 如果存在 research.md：提取决策用于初始化相关任务
-   - 按用户故事组织生成任务（见下方“任务生成规则”）
-   - 生成依赖图，展示用户故事的完成顺序
-   - 为每个用户故事提供并行执行示例
-   - 校验任务完整性（每个用户故事包含所需任务，且可独立测试）
-
-4. **生成 tasks.md**：以 `.specify/templates/tasks-template.md` 为结构，填充：
-   - 从 plan.md 读取正确的功能名称
-   - Phase 1：初始化任务（项目初始化）
-   - Phase 2：基础任务（所有用户故事的阻塞前置）
-   - Phase 3+：按 spec.md 的优先级为每个用户故事建一个阶段
-   - 每个阶段包含：故事目标、独立测试标准、测试（如有要求）、实现任务
-   - 最终阶段：打磨与横切关注点
-   - 所有任务必须遵循严格的清单格式（见下方“任务生成规则”）
-   - 每个任务都要写清楚文件路径
-   - Dependencies 章节展示故事完成顺序
-   - 每个故事提供并行执行示例
-   - Implementation strategy 章节说明实现策略（先 MVP，逐步交付）
-
-5. **报告（Report）**：输出生成的 tasks.md 路径与摘要：
-   - 任务总数
-   - 每个用户故事的任务数
-   - 识别到的并行机会
-   - 每个故事的独立测试标准
-   - 建议的 MVP 范围（通常只包含用户故事 1）
-   - 格式校验：确认所有任务都遵循清单格式（checkbox、ID、标签、文件路径）
-
-用于任务生成的上下文：$ARGUMENTS
-
-tasks.md 应当可以直接执行——每个任务都必须足够具体，使得 LLM 在不依赖额外上下文的情况下也能完成。
-
-## 任务生成规则
-
-**关键（CRITICAL）**：任务必须按用户故事组织，以支持独立实现与独立测试。
-
-**测试是可选项**：只有在 spec 明确要求，或用户要求 TDD 时才生成测试任务。
-
-### 清单格式（必须）
-
-每个任务都必须严格遵循以下格式：
-
-```text
-- [ ] [TaskID] [P?] [Story?] 包含文件路径的任务描述
-```
-
-**格式组成**：
-
-1. **勾选框（Checkbox）**：必须以 `- [ ]` 开头（Markdown checkbox）
-2. **任务 ID（Task ID）**：按执行顺序递增编号（T001、T002、T003...）
-3. **[P] 标记**：仅当任务可并行时才包含（不同文件，且不依赖未完成任务）
-4. **[Story] 标签**：仅用于“用户故事阶段”的任务，且必须包含
-   - 格式：[US1]、[US2]、[US3] 等（映射 spec.md 的用户故事）
-   - 初始化阶段：不加 story 标签
-   - 基础阶段：不加 story 标签
-   - 用户故事阶段：必须有 story 标签
-   - 打磨阶段：不加 story 标签
-5. **描述（Description）**：清晰描述动作，并包含准确文件路径
-
-**示例**：
-
-- ✅ 正确：`- [ ] T001 按实现计划创建项目结构`
-- ✅ 正确：`- [ ] T005 [P] 在 src/middleware/auth.py 实现认证中间件`
-- ✅ 正确：`- [ ] T012 [P] [US1] 在 src/models/user.py 创建 User 模型`
-- ✅ 正确：`- [ ] T014 [US1] 在 src/services/user_service.py 实现 UserService`
-- ❌ 错误：`- [ ] 创建用户模型`（缺少 ID 与 Story 标签）
-- ❌ 错误：`T001 [US1] 创建模型`（缺少 checkbox）
-- ❌ 错误：`- [ ] [US1] 创建用户模型`（缺少 Task ID）
-- ❌ 错误：`- [ ] T001 [US1] 创建模型`（缺少文件路径）
-
-### 任务组织方式
-
-1. **来自用户故事（spec.md）——主要组织方式**：
-   - 每个用户故事（P1、P2、P3...）对应一个阶段
-   - 将所有相关组件映射到对应的故事：
-     - 该故事需要的模型
-     - 该故事需要的服务
-     - 该故事需要的端点/UI
-     - 若需要测试：该故事专属的测试任务
-   - 标记故事依赖（大多数故事应尽量独立）
-
-2. **来自 contracts**：
-   - 将每个 contract/endpoint 映射到它服务的用户故事
-   - 若需要测试：每个 contract 在该故事阶段中，先生成 contract 测试任务 [P]，再实现
-
-3. **来自数据模型**：
-   - 将每个实体映射到需要它的用户故事
-   - 若实体服务多个故事：放入最早的故事阶段或初始化阶段
-   - 关系处理 → 放到对应故事阶段的服务层任务中
-
-4. **来自初始化/基础设施**：
-   - 共享基础设施 → 初始化阶段（Phase 1）
-   - 基础/阻塞任务 → 基础阶段（Phase 2）
-   - 故事特定的初始化 → 放到该故事阶段内
-
-### 阶段结构
-
-- **Phase 1**：初始化（项目初始化）
-- **Phase 2**：基础（阻塞前置；必须在用户故事之前完成）
-- **Phase 3+**：按优先级顺序的用户故事（P1、P2、P3...）
-  - 每个故事内：测试（如需）→ 模型 → 服务 → 端点 → 集成
-  - 每个阶段都应是一个完整且可独立测试的增量
-- **最终阶段**：打磨与横切关注点

----
-description: 基于现有设计产物，将已有任务转换为可执行、按依赖排序的 GitHub issue。
-tools: ['github/github-mcp-server/issue_write']
----
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-在继续之前，你**必须**先考虑用户输入（如果不为空）。
-
-## 概述
-
-1. 在仓库根目录运行 `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` 并解析 FEATURE_DIR 与 AVAILABLE_DOCS 列表。所有路径必须是绝对路径。当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）。
-2. 从脚本输出中提取 **tasks** 文件路径。
-3. 通过以下命令获取 Git 远端地址（remote）：
-
-```bash
-git config --get remote.origin.url
-```
-
-> [!CAUTION]
-> 只有当 remote 是 GitHub URL 时才允许继续后续步骤
-
-4. 对任务列表中的每个任务，使用 GitHub MCP server 在与该 remote 相匹配的仓库中创建一个新 issue。
-
-> [!CAUTION]
-> 任何情况下都不要在与 remote URL 不匹配的仓库里创建 issue

----
-description: "生成/更新项目原则（constitution）"
-agent: agent
----
-
-请根据当前仓库的技术栈与业务场景，生成或更新 .specify/memory/constitution.md：
-
-- 内容使用中文
-- 原则需要覆盖：工程规范、UI/样式规范、网络请求返回结构、资源链接规则、开发与发布约束
-- 原则要具体可执行，避免空泛口号
-- 如果已存在同名文件，保留现有有效条款，只补齐缺失部分并做结构化整理

----
-description: "按任务实现并自检（implement）"
-agent: agent
-argument-hint: "feature_key（例如 001-xxx）"
----
-
-你需要按 specs/<feature_key>/tasks.md 逐条完成实现，并遵循：
-
-- 严格对照 specs/<feature_key>/spec.md 的验收标准
-- 修改尽量小，避免无关重构
-- 接口返回结构固定为 { code, data, msg }，错误提示使用 msg
-- 图片域名为 cdn.ipadbiz.cn 时追加 ?imageMogr2/thumbnail/200x/strip/quality/70
-- 完成后运行现有的测试/检查脚本（如果仓库提供）
-- 不要启动或重启任何服务；不要引导打开预览

----
-description: "生成技术方案（plan）"
-agent: agent
-argument-hint: "feature_key（例如 001-xxx）"
----
-
-基于 specs/<feature_key>/spec.md，生成 specs/<feature_key>/plan.md。
-
-约束：
-- 给出最小改动方案，优先复用现有组件、工具与目录结构
-- 明确需要修改/新增的文件清单（按路径列出）
-- 明确数据流、状态管理方式（如需要 pinia/route query/组件本地状态）
-- 明确接口调用点与返回结构 { code, data, msg } 的处理策略
-- 样式：优先 TailwindCSS 类名（项目已引入），Less 用于层级补充
-- 不要启动或重启任何服务；不要引导打开预览
-
-plan.md 输出结构：
-1) 总体方案
-2) 页面与路由变更
-3) 组件与复用点
-4) 状态管理与数据流
-5) 接口与错误处理
-6) 样式与响应式策略
-7) 影响范围与回归清单

----
-description: "生成需求规格说明（spec）"
-agent: agent
-argument-hint: "feature_key 与需求描述（例如 001-xxx ...）"
----
-
-你需要把用户的需求整理成可评审的规格说明，输出到 specs/<feature_key>/spec.md。
-
-约束：
-- 只写“做什么/为什么”，不要写实现细节
-- 不确定的信息必须写成 [NEEDS CLARIFICATION]，并给出具体要问的问题
-- 规格说明使用中文，结构清晰，便于团队协作评审
-- feature_key 使用数字前缀与短横线命名，例如 001-course-share-poster
-
-spec.md 模板：
-
-1) 背景与目标
-- 背景：
-- 目标：
-- 非目标：
-
-2) 用户画像与使用场景
-
-3) 需求范围
-- 页面/入口：
-- 核心流程：
-- 状态与异常分支：
-
-4) 用户故事（User Stories）
-- 作为……我想……以便……
-
-5) 验收标准（Acceptance Criteria）
-- 使用可验证的条件描述
-
-6) 交互与视觉要点
-- 移动端优先（如涉及 PC/移动差异需要说明）
-
-7) 数据与接口
-- 需要的字段（仅描述数据含义，不给实现）
-- 返回结构固定为 { code, data, msg }
-
-8) 边界条件与风险
-
-9) 待确认事项
-- [NEEDS CLARIFICATION] ...

----
-description: "从方案拆分可执行任务（tasks）"
-agent: agent
-argument-hint: "feature_key（例如 001-xxx）"
----
-
-基于 specs/<feature_key>/plan.md，生成 specs/<feature_key>/tasks.md。
-
-约束：
-- 任务要可执行、可验收，按顺序列出
-- 每条任务不超过 14 个字
-- 标注必要的回归点
-- 不要包含“启动服务/打开预览”相关任务
-
-tasks.md 格式：
-- [ ] 任务1
-- [ ] 任务2
-
-回归清单：
-- [ ] 回归项1
-- [ ] 回归项2

-# mlaj 宪法
-
-## 核心原则
-
-### 用户需求为中心
-
-- 以用户需求为中心，优先实现最小可用闭环，避免过度设计
-
-### 修改尽量小且可回滚
-
-- 修改应尽量小且可回滚，避免大范围重构
-
-### 风格一致与复用优先
-
-- 保持现有代码风格与目录结构一致，优先复用已有工具与组件
-
-### 生产代码完毕后不要重启服务
-
-- 生产代码完毕后不要重启服务
-
-### 操作完成后不要自动打开预览
-
-- 操作完成后不要自动打开预览
-
-## 技术与工程约束
-
-- 依赖管理使用 pnpm
-- 构建工具使用 Vite
-- 前端使用 Vue3（优先 setup 语法糖）
-- 移动端 UI 优先使用 Vant
-- 样式使用 Less；如果项目已引入 TailwindCSS，布局优先用 Tailwind 类名，细节用 Less 补充
-- 路由使用 vue-router
-- 状态管理使用 pinia（如项目已接入）
-- 不引入不必要的新库；如必须新增依赖，需要在方案中说明原因与替代方案
-
-## 接口与数据约束
-
-- 所有网络请求返回对象结构必须为 { code, data, msg }
-- code=1 表示成功，其他值表示失败；失败时保持 msg 可读
-
-## 资源与链接约束
-
-- 若图片域名为 cdn.ipadbiz.cn，需要自动追加 ?imageMogr2/thumbnail/200x/strip/quality/70
-
-## 治理与管理
-
-- 本宪法优先级高于临时约定与个人习惯；出现冲突时以本宪法为准
-- 宪法变更应同步更新版本/日期信息，并确保对现有工程约束的兼容性
-
-**版本**: [CONSTITUTION_VERSION] | **批准**: [RATIFICATION_DATE] | **最后修订**: [LAST_AMENDED_DATE]

-#!/usr/bin/env bash
-
-# 前置条件检查脚本（整合版）
-#
-# 本脚本为 Spec-Driven Development 工作流提供统一的前置条件检查，
-# 用于替代此前分散在多个脚本中的同类功能。
-#
-# 用法：./check-prerequisites.sh [OPTIONS]
-#
-# OPTIONS：
-#   --json              以 JSON 格式输出
-#   --require-tasks     要求 tasks.md 必须存在（实现阶段使用）
-#   --include-tasks     在 AVAILABLE_DOCS 列表中包含 tasks.md
-#   --paths-only        仅输出路径变量（不做校验）
-#   --help, -h          显示帮助信息
-#
-# 输出：
-#   JSON 模式：{"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
-#   文本模式：FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
-#   仅路径：REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... 等
-
-set -e
-
-# 解析命令行参数
-JSON_MODE=false
-REQUIRE_TASKS=false
-INCLUDE_TASKS=false
-PATHS_ONLY=false
-
-for arg in "$@"; do
-    case "$arg" in
-        --json)
-            JSON_MODE=true
-            ;;
-        --require-tasks)
-            REQUIRE_TASKS=true
-            ;;
-        --include-tasks)
-            INCLUDE_TASKS=true
-            ;;
-        --paths-only)
-            PATHS_ONLY=true
-            ;;
-        --help|-h)
-            cat << 'EOF'
-用法：check-prerequisites.sh [OPTIONS]
-
-用于 Spec-Driven Development 工作流的前置条件检查（整合版）。
-
-选项：
-    --json              以 JSON 格式输出
-    --require-tasks     要求 tasks.md 必须存在（实现阶段使用）
-    --include-tasks     在 AVAILABLE_DOCS 列表中包含 tasks.md
-    --paths-only        仅输出路径变量（不做前置条件校验）
-    --help, -h          显示帮助信息
-
-示例：
-    # 检查任务前置条件（需要 plan.md）
-    ./check-prerequisites.sh --json
-
-    # 检查实现前置条件（需要 plan.md + tasks.md）
-    ./check-prerequisites.sh --json --require-tasks --include-tasks
-
-    # 仅获取功能路径（不做校验）
-    ./check-prerequisites.sh --paths-only
-
-EOF
-            exit 0
-            ;;
-        *)
-            echo "错误：未知选项 '$arg'。使用 --help 查看用法。" >&2
-            exit 1
-            ;;
-    esac
-done
-
-# 引入通用函数
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
-
-# 获取功能路径并校验分支
-eval $(get_feature_paths)
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
-
-# 若为仅路径模式：输出路径后退出（支持 --json 与 --paths-only 组合）
-if $PATHS_ONLY; then
-    if $JSON_MODE; then
-        # 最小 JSON 路径负载（不做校验）
-        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
-            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
-    else
-        echo "REPO_ROOT: $REPO_ROOT"
-        echo "BRANCH: $CURRENT_BRANCH"
-        echo "FEATURE_DIR: $FEATURE_DIR"
-        echo "FEATURE_SPEC: $FEATURE_SPEC"
-        echo "IMPL_PLAN: $IMPL_PLAN"
-        echo "TASKS: $TASKS"
-    fi
-    exit 0
-fi
-
-# 校验必要的目录与文件
-if [[ ! -d "$FEATURE_DIR" ]]; then
-    echo "错误：未找到功能目录：$FEATURE_DIR" >&2
-    echo "请先运行 /speckit.specify 以创建功能目录结构。" >&2
-    exit 1
-fi
-
-if [[ ! -f "$IMPL_PLAN" ]]; then
-    echo "错误：在 $FEATURE_DIR 中未找到 plan.md" >&2
-    echo "请先运行 /speckit.plan 以创建实现计划。" >&2
-    exit 1
-fi
-
-# 如果需要则检查 tasks.md
-if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
-    echo "错误：在 $FEATURE_DIR 中未找到 tasks.md" >&2
-    echo "请先运行 /speckit.tasks 以创建任务清单。" >&2
-    exit 1
-fi
-
-# 构建可用文档列表
-docs=()
-
-# 固定检查这些可选文档
-[[ -f "$RESEARCH" ]] && docs+=("research.md")
-[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
-
-# 检查 contracts 目录（仅当存在且非空）
-if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
-    docs+=("contracts/")
-fi
-
-[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
-
-# 若要求包含 tasks.md，且文件存在，则加入列表
-if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
-    docs+=("tasks.md")
-fi
-
-# 输出结果
-if $JSON_MODE; then
-    # 构建文档 JSON 数组
-    if [[ ${#docs[@]} -eq 0 ]]; then
-        json_docs="[]"
-    else
-        json_docs=$(printf '"%s",' "${docs[@]}")
-        json_docs="[${json_docs%,}]"
-    fi
-
-    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
-else
-    # 文本输出
-    echo "FEATURE_DIR:$FEATURE_DIR"
-    echo "AVAILABLE_DOCS:"
-
-    # 展示各文档的存在状态
-    check_file "$RESEARCH" "research.md"
-    check_file "$DATA_MODEL" "data-model.md"
-    check_dir "$CONTRACTS_DIR" "contracts/"
-    check_file "$QUICKSTART" "quickstart.md"
-
-    if $INCLUDE_TASKS; then
-        check_file "$TASKS" "tasks.md"
-    fi
-fi

-#!/usr/bin/env bash
-# 所有脚本共用的函数与变量
-
-# 获取仓库根目录（非 git 仓库时提供兜底）
-get_repo_root() {
-    if git rev-parse --show-toplevel >/dev/null 2>&1; then
-        git rev-parse --show-toplevel
-    else
-        # 非 git 仓库：回退为脚本所在目录向上查找
-        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-        (cd "$script_dir/../../.." && pwd)
-    fi
-}
-
-# 获取当前分支（非 git 仓库时提供兜底）
-get_current_branch() {
-    # 优先使用 SPECIFY_FEATURE 环境变量
-    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
-        echo "$SPECIFY_FEATURE"
-        return
-    fi
-
-    # 其次尝试从 git 读取
-    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
-        git rev-parse --abbrev-ref HEAD
-        return
-    fi
-
-    # 非 git 仓库：尝试找到最新的功能目录
-    local repo_root=$(get_repo_root)
-    local specs_dir="$repo_root/specs"
-
-    if [[ -d "$specs_dir" ]]; then
-        local latest_feature=""
-        local highest=0
-
-        for dir in "$specs_dir"/*; do
-            if [[ -d "$dir" ]]; then
-                local dirname=$(basename "$dir")
-                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
-                    local number=${BASH_REMATCH[1]}
-                    number=$((10#$number))
-                    if [[ "$number" -gt "$highest" ]]; then
-                        highest=$number
-                        latest_feature=$dirname
-                    fi
-                fi
-            fi
-        done
-
-        if [[ -n "$latest_feature" ]]; then
-            echo "$latest_feature"
-            return
-        fi
-    fi
-
-    echo "main"  # 最终兜底
-}
-
-# 检查是否为 git 仓库
-has_git() {
-    git rev-parse --show-toplevel >/dev/null 2>&1
-}
-
-check_feature_branch() {
-    local branch="$1"
-    local has_git_repo="$2"
-
-    # 非 git 仓库无法强制分支命名，但仍输出提示
-    if [[ "$has_git_repo" != "true" ]]; then
-        echo "[specify] 警告：未检测到 Git 仓库；已跳过分支校验" >&2
-        return 0
-    fi
-
-    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
-        echo "错误：当前不在功能分支。当前分支：$branch" >&2
-        echo "功能分支命名应类似：001-feature-name" >&2
-        return 1
-    fi
-
-    return 0
-}
-
-get_feature_dir() { echo "$1/specs/$2"; }
-
-# 按数字前缀查找功能目录，而不是严格按分支名匹配
-# 这样允许多个分支指向同一份规格（例如 004-fix-bug、004-add-feature）
-find_feature_dir_by_prefix() {
-    local repo_root="$1"
-    local branch_name="$2"
-    local specs_dir="$repo_root/specs"
-
-    # 从分支名提取数字前缀（例如从 "004-whatever" 提取 "004"）
-    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
-        # 分支名不含数字前缀：回退为按分支名拼路径
-        echo "$specs_dir/$branch_name"
-        return
-    fi
-
-    local prefix="${BASH_REMATCH[1]}"
-
-    # 在 specs/ 下查找以该前缀开头的目录
-    local matches=()
-    if [[ -d "$specs_dir" ]]; then
-        for dir in "$specs_dir"/"$prefix"-*; do
-            if [[ -d "$dir" ]]; then
-                matches+=("$(basename "$dir")")
-            fi
-        done
-    fi
-
-    # 处理查找结果
-    if [[ ${#matches[@]} -eq 0 ]]; then
-        # 未找到：返回按分支名拼的路径（后续会给出更明确的错误）
-        echo "$specs_dir/$branch_name"
-    elif [[ ${#matches[@]} -eq 1 ]]; then
-        # 仅一个匹配：直接返回
-        echo "$specs_dir/${matches[0]}"
-    else
-        # 多个匹配：命名规范正确时不应发生
-        echo "错误：发现多个同前缀规格目录 '$prefix'：${matches[*]}" >&2
-        echo "请确保每个数字前缀只对应一个规格目录。" >&2
-        echo "$specs_dir/$branch_name"  # 返回一个路径以避免脚本中断
-    fi
-}
-
-get_feature_paths() {
-    local repo_root=$(get_repo_root)
-    local current_branch=$(get_current_branch)
-    local has_git_repo="false"
-
-    if has_git; then
-        has_git_repo="true"
-    fi
-
-    # 使用前缀匹配以支持“多分支对应同一份规格”的场景
-    local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
-
-    cat <<EOF
-REPO_ROOT='$repo_root'
-CURRENT_BRANCH='$current_branch'
-HAS_GIT='$has_git_repo'
-FEATURE_DIR='$feature_dir'
-FEATURE_SPEC='$feature_dir/spec.md'
-IMPL_PLAN='$feature_dir/plan.md'
-TASKS='$feature_dir/tasks.md'
-RESEARCH='$feature_dir/research.md'
-DATA_MODEL='$feature_dir/data-model.md'
-QUICKSTART='$feature_dir/quickstart.md'
-CONTRACTS_DIR='$feature_dir/contracts'
-EOF
-}
-
-check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
-check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }

-#!/usr/bin/env bash
-
-set -e
-
-JSON_MODE=false
-SHORT_NAME=""
-BRANCH_NUMBER=""
-ARGS=()
-i=1
-while [ $i -le $# ]; do
-    arg="${!i}"
-    case "$arg" in
-        --json)
-            JSON_MODE=true
-            ;;
-        --short-name)
-            if [ $((i + 1)) -gt $# ]; then
-                echo '错误：--short-name 需要提供值' >&2
-                exit 1
-            fi
-            i=$((i + 1))
-            next_arg="${!i}"
-            # 检查下一个参数是否为另一个选项（以 -- 开头）
-            if [[ "$next_arg" == --* ]]; then
-                echo '错误：--short-name 需要提供值' >&2
-                exit 1
-            fi
-            SHORT_NAME="$next_arg"
-            ;;
-        --number)
-            if [ $((i + 1)) -gt $# ]; then
-                echo '错误：--number 需要提供值' >&2
-                exit 1
-            fi
-            i=$((i + 1))
-            next_arg="${!i}"
-            if [[ "$next_arg" == --* ]]; then
-                echo '错误：--number 需要提供值' >&2
-                exit 1
-            fi
-            BRANCH_NUMBER="$next_arg"
-            ;;
-        --help|-h)
-            echo "用法：$0 [--json] [--short-name <短名>] [--number N] <功能描述>"
-            echo ""
-            echo "选项："
-            echo "  --json              以 JSON 格式输出"
-            echo "  --short-name <短名> 为分支提供自定义短名（2-4 个单词）"
-            echo "  --number N          手动指定分支编号（覆盖自动检测）"
-            echo "  --help, -h          显示帮助信息"
-            echo ""
-            echo "示例："
-            echo "  $0 '新增用户登录与鉴权能力' --short-name 'user-auth'"
-            echo "  $0 '为 API 接入 OAuth2 登录' --number 5"
-            exit 0
-            ;;
-        *)
-            ARGS+=("$arg")
-            ;;
-    esac
-    i=$((i + 1))
-done
-
-FEATURE_DESCRIPTION="${ARGS[*]}"
-if [ -z "$FEATURE_DESCRIPTION" ]; then
-    echo "用法：$0 [--json] [--short-name <短名>] [--number N] <功能描述>" >&2
-    exit 1
-fi
-
-# 通过查找项目标记来定位仓库根目录
-find_repo_root() {
-    local dir="$1"
-    while [ "$dir" != "/" ]; do
-        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
-            echo "$dir"
-            return 0
-        fi
-        dir="$(dirname "$dir")"
-    done
-    return 1
-}
-
-# 从 specs 目录中获取最大编号
-get_highest_from_specs() {
-    local specs_dir="$1"
-    local highest=0
-
-    if [ -d "$specs_dir" ]; then
-        for dir in "$specs_dir"/*; do
-            [ -d "$dir" ] || continue
-            dirname=$(basename "$dir")
-            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
-            number=$((10#$number))
-            if [ "$number" -gt "$highest" ]; then
-                highest=$number
-            fi
-        done
-    fi
-
-    echo "$highest"
-}
-
-# 从 git 分支中获取最大编号
-get_highest_from_branches() {
-    local highest=0
-
-    # 获取所有分支（本地 + 远端）
-    branches=$(git branch -a 2>/dev/null || echo "")
-
-    if [ -n "$branches" ]; then
-        while IFS= read -r branch; do
-            # 清理分支名：移除前缀标记与远端前缀
-            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
-
-            # 若分支符合 ###-*，则提取功能编号
-            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
-                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
-                number=$((10#$number))
-                if [ "$number" -gt "$highest" ]; then
-                    highest=$number
-                fi
-            fi
-        done <<< "$branches"
-    fi
-
-    echo "$highest"
-}
-
-# 检查现有分支（本地 + 远端）并返回下一个可用编号
-check_existing_branches() {
-    local specs_dir="$1"
-
-    # 拉取所有远端以获取最新分支信息（无远端时忽略错误）
-    git fetch --all --prune 2>/dev/null || true
-
-    # 获取所有分支中的最大编号（不局限于匹配 short name）
-    local highest_branch=$(get_highest_from_branches)
-
-    # 获取所有 specs 中的最大编号（不局限于匹配 short name）
-    local highest_spec=$(get_highest_from_specs "$specs_dir")
-
-    # 两者取最大值
-    local max_num=$highest_branch
-    if [ "$highest_spec" -gt "$max_num" ]; then
-        max_num=$highest_spec
-    fi
-
-    # 返回下一个编号
-    echo $((max_num + 1))
-}
-
-# 清理并格式化分支名
-clean_branch_name() {
-    local name="$1"
-    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
-}
-
-# 解析仓库根目录：优先使用 git 信息；如不可用则回退为查找仓库标记，
-# 以兼容使用 --no-git 初始化的仓库。
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-if git rev-parse --show-toplevel >/dev/null 2>&1; then
-    REPO_ROOT=$(git rev-parse --show-toplevel)
-    HAS_GIT=true
-else
-    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
-    if [ -z "$REPO_ROOT" ]; then
-        echo "错误：无法确定仓库根目录。请在仓库内运行本脚本。" >&2
-        exit 1
-    fi
-    HAS_GIT=false
-fi
-
-cd "$REPO_ROOT"
-
-SPECS_DIR="$REPO_ROOT/specs"
-mkdir -p "$SPECS_DIR"
-
-# 生成分支名：包含停用词过滤与长度过滤
-generate_branch_name() {
-    local description="$1"
-
-    # 常见停用词（用于过滤）
-    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
-
-    # 转小写并按单词拆分
-    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
-
-    # 过滤单词：移除停用词与长度 < 3 的词（除非在原描述中以大写出现，通常为缩写）
-    local meaningful_words=()
-    for word in $clean_name; do
-        # 跳过空词
-        [ -z "$word" ] && continue
-
-        # 保留：不属于停用词，并且（长度 >= 3 或为可能的缩写）
-        if ! echo "$word" | grep -qiE "$stop_words"; then
-            if [ ${#word} -ge 3 ]; then
-                meaningful_words+=("$word")
-            elif echo "$description" | grep -q "\b${word^^}\b"; then
-                # 原描述中若以大写出现则保留（很可能是缩写）
-                meaningful_words+=("$word")
-            fi
-        fi
-    done
-
-    # 若有有效词，则取前 3-4 个
-    if [ ${#meaningful_words[@]} -gt 0 ]; then
-        local max_words=3
-        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
-
-        local result=""
-        local count=0
-        for word in "${meaningful_words[@]}"; do
-            if [ $count -ge $max_words ]; then break; fi
-            if [ -n "$result" ]; then result="$result-"; fi
-            result="$result$word"
-            count=$((count + 1))
-        done
-        echo "$result"
-    else
-        # 若未找到有效词：回退为原始逻辑
-        local cleaned=$(clean_branch_name "$description")
-        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
-    fi
-}
-
-# 生成分支名
-if [ -n "$SHORT_NAME" ]; then
-    # 使用用户提供的 short name，并做清理
-    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
-else
-    # 根据描述智能过滤生成
-    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
-fi
-
-# 确定分支编号
-if [ -z "$BRANCH_NUMBER" ]; then
-    if [ "$HAS_GIT" = true ]; then
-        # 检查远端已有分支
-        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
-    else
-        # 回退为本地目录检查
-        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
-        BRANCH_NUMBER=$((HIGHEST + 1))
-    fi
-fi
-
-# 强制按十进制解释，避免八进制转换（例如 010 在八进制会变为 8，但这里应是十进制 10）
-FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
-BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
-
-# GitHub 对分支名有 244 字节限制：必要时校验并截断
-MAX_BRANCH_LENGTH=244
-if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
-    # 计算需要从后缀中截断的长度
-    # 分支名包含：功能编号（3）+ 连字符（1）= 4 个字符
-    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
-
-    # 尽量按单词边界截断后缀
-    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
-    # 若截断产生了末尾连字符则移除
-    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
-
-    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
-    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
-
-    >&2 echo "[specify] Warning: 分支名超过 GitHub 的 244 字节限制"
-    >&2 echo "[specify] 原始：$ORIGINAL_BRANCH_NAME（${#ORIGINAL_BRANCH_NAME} 字节）"
-    >&2 echo "[specify] 已截断为：$BRANCH_NAME（${#BRANCH_NAME} 字节）"
-fi
-
-if [ "$HAS_GIT" = true ]; then
-    git checkout -b "$BRANCH_NAME"
-else
-    >&2 echo "[specify] Warning: 未检测到 Git 仓库；已跳过创建分支 $BRANCH_NAME"
-fi
-
-FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
-mkdir -p "$FEATURE_DIR"
-
-TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
-SPEC_FILE="$FEATURE_DIR/spec.md"
-if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
-
-# 为当前会话设置 SPECIFY_FEATURE 环境变量
-export SPECIFY_FEATURE="$BRANCH_NAME"
-
-if $JSON_MODE; then
-    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
-else
-    echo "BRANCH_NAME: $BRANCH_NAME"
-    echo "SPEC_FILE: $SPEC_FILE"
-    echo "FEATURE_NUM: $FEATURE_NUM"
-    echo "已设置 SPECIFY_FEATURE 环境变量为：$BRANCH_NAME"
-fi

-#!/usr/bin/env bash
-
-set -e
-
-# 解析命令行参数
-JSON_MODE=false
-ARGS=()
-
-for arg in "$@"; do
-    case "$arg" in
-        --json) 
-            JSON_MODE=true 
-            ;;
-        --help|-h) 
-            echo "用法：$0 [--json]"
-            echo "  --json    以 JSON 格式输出结果"
-            echo "  --help    显示帮助信息"
-            exit 0 
-            ;;
-        *) 
-            ARGS+=("$arg") 
-            ;;
-    esac
-done
-
-# 获取脚本目录并加载通用函数
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
-
-# 从通用函数获取所有路径与变量
-eval $(get_feature_paths)
-
-# 检查是否在合规的功能分支上（仅 git 仓库）
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
-
-# 确保功能目录存在
-mkdir -p "$FEATURE_DIR"
-
-# 如果存在计划模板，则复制
-TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
-if [[ -f "$TEMPLATE" ]]; then
-    cp "$TEMPLATE" "$IMPL_PLAN"
-    echo "已复制 plan 模板到：$IMPL_PLAN"
-else
-    echo "警告：未找到 plan 模板：$TEMPLATE"
-    # 如果不存在模板，则创建空的 plan 文件
-    touch "$IMPL_PLAN"
-fi
-
-# 输出结果
-if $JSON_MODE; then
-    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
-        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
-else
-    echo "FEATURE_SPEC: $FEATURE_SPEC"
-    echo "IMPL_PLAN: $IMPL_PLAN" 
-    echo "SPECS_DIR: $FEATURE_DIR"
-    echo "BRANCH: $CURRENT_BRANCH"
-    echo "HAS_GIT: $HAS_GIT"
-fi

-#!/usr/bin/env bash
-
-# 根据 plan.md 更新各类智能体的上下文文件
-#
-# 本脚本通过解析功能规格与实现计划，更新不同智能体对应的上下文/规则文件，
-# 以便在后续命令（如 /speckit.tasks、/speckit.implement）中提供一致的项目背景信息。
-#
-# 主要功能：
-# 1. 环境校验
-#    - 校验 git 仓库结构与分支信息
-#    - 校验所需的 plan.md 与模板文件是否存在
-#    - 校验文件权限与可访问性
-#
-# 2. 计划数据提取
-#    - 解析 plan.md 提取项目元信息
-#    - 识别语言/版本、主要依赖、存储与项目类型
-#    - 对缺失或不完整数据做容错处理
-#
-# 3. 智能体文件管理
-#    - 需要时基于模板创建新的上下文文件
-#    - 更新既有上下文文件并追加新的项目信息
-#    - 保留手工补充内容与自定义配置
-#    - 支持多种智能体格式与目录结构
-#
-# 4. 内容生成
-#    - 生成与语言相关的构建/测试命令
-#    - 生成合理的项目目录结构占位
-#    - 更新“当前技术栈”和“最近变更”等章节
-#    - 保持格式与时间戳一致
-#
-# 5. 多智能体支持
-#    - 处理不同智能体的路径与命名约定
-#    - 支持：Claude、Gemini、Copilot、Cursor、Qwen、opencode、Codex、Windsurf、Kilo Code、Auggie CLI、Roo Code、CodeBuddy CLI、Qoder CLI、Amp、SHAI、Amazon Q Developer CLI 等
-#    - 支持更新指定智能体或更新所有已存在的智能体文件
-#    - 若当前没有任何智能体文件，则创建默认的 Claude 文件
-#
-# 用法：./update-agent-context.sh [agent_type]
-# agent_type：claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|shai|q|bob|qoder
-# 不传参则更新所有已存在的智能体文件
-
-set -e
-
-# 开启更严格的错误处理
-set -u
-set -o pipefail
-
-#==============================================================================
-# 配置与全局变量
-#==============================================================================
-
-# 获取脚本目录并加载通用函数
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
-
-# 从通用函数获取所有路径与变量
-eval $(get_feature_paths)
-
-NEW_PLAN="$IMPL_PLAN"  # 兼容历史代码的别名
-AGENT_TYPE="${1:-}"
-
-# 不同智能体的文件路径
-CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
-GEMINI_FILE="$REPO_ROOT/GEMINI.md"
-COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
-CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
-QWEN_FILE="$REPO_ROOT/QWEN.md"
-AGENTS_FILE="$REPO_ROOT/AGENTS.md"
-WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
-KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
-AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
-ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
-CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
-QODER_FILE="$REPO_ROOT/QODER.md"
-AMP_FILE="$REPO_ROOT/AGENTS.md"
-SHAI_FILE="$REPO_ROOT/SHAI.md"
-Q_FILE="$REPO_ROOT/AGENTS.md"
-BOB_FILE="$REPO_ROOT/AGENTS.md"
-
-# 模板文件
-TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
-
-# 从 plan.md 解析得到的全局变量
-NEW_LANG=""
-NEW_FRAMEWORK=""
-NEW_DB=""
-NEW_PROJECT_TYPE=""
-
-#==============================================================================
-# 工具函数
-#==============================================================================
-
-log_info() {
-    echo "信息：$1"
-}
-
-log_success() {
-    echo "✓ $1"
-}
-
-log_error() {
-    echo "错误：$1" >&2
-}
-
-log_warning() {
-    echo "警告：$1" >&2
-}
-
-# 清理临时文件
-cleanup() {
-    local exit_code=$?
-    rm -f /tmp/agent_update_*_$$
-    rm -f /tmp/manual_additions_$$
-    exit $exit_code
-}
-
-# 设置清理 trap
-trap cleanup EXIT INT TERM
-
-#==============================================================================
-# 校验函数
-#==============================================================================
-
-validate_environment() {
-    # 检查是否能获取当前分支/功能（git 或非 git）
-    if [[ -z "$CURRENT_BRANCH" ]]; then
-        log_error "无法确定当前功能/分支"
-        if [[ "$HAS_GIT" == "true" ]]; then
-            log_info "请确认当前在功能分支上"
-        else
-            log_info "请设置 SPECIFY_FEATURE 环境变量，或先创建功能目录"
-        fi
-        exit 1
-    fi
-
-    # 检查 plan.md 是否存在
-    if [[ ! -f "$NEW_PLAN" ]]; then
-        log_error "未找到 plan.md：$NEW_PLAN"
-        log_info "请确认当前功能存在对应的 specs 目录"
-        if [[ "$HAS_GIT" != "true" ]]; then
-            log_info "可使用：export SPECIFY_FEATURE=your-feature-name，或先创建新功能"
-        fi
-        exit 1
-    fi
-
-    # 检查模板文件是否存在（创建新文件时需要）
-    if [[ ! -f "$TEMPLATE_FILE" ]]; then
-        log_warning "未找到模板文件：$TEMPLATE_FILE"
-        log_warning "创建新的智能体文件将会失败"
-    fi
-}
-
-#==============================================================================
-# plan.md 解析函数
-#==============================================================================
-
-extract_plan_field() {
-    local field_pattern="$1"
-    local plan_file="$2"
-
-    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
-        head -1 | \
-        sed "s|^\*\*${field_pattern}\*\*: ||" | \
-        sed 's/^[ \t]*//;s/[ \t]*$//' | \
-        grep -v "NEEDS CLARIFICATION" | \
-        grep -v "^N/A$" || echo ""
-}
-
-extract_plan_field_any() {
-    local plan_file="$1"
-    shift
-
-    local field_pattern=""
-    for field_pattern in "$@"; do
-        local value
-        value=$(extract_plan_field "$field_pattern" "$plan_file")
-        if [[ -n "$value" ]]; then
-            echo "$value"
-            return 0
-        fi
-    done
-
-    echo ""
-}
-
-parse_plan_data() {
-    local plan_file="$1"
-
-    if [[ ! -f "$plan_file" ]]; then
-        log_error "未找到 plan 文件：$plan_file"
-        return 1
-    fi
-
-    if [[ ! -r "$plan_file" ]]; then
-        log_error "plan 文件不可读：$plan_file"
-        return 1
-    fi
-
-    log_info "正在解析 plan 数据：$plan_file"
-
-    NEW_LANG=$(extract_plan_field_any "$plan_file" "语言/版本" "Language/Version")
-    NEW_FRAMEWORK=$(extract_plan_field_any "$plan_file" "主要依赖" "Primary Dependencies")
-    NEW_DB=$(extract_plan_field_any "$plan_file" "存储" "Storage")
-    NEW_PROJECT_TYPE=$(extract_plan_field_any "$plan_file" "工程类型" "Project Type")
-
-    # 输出解析结果
-    if [[ -n "$NEW_LANG" ]]; then
-        log_info "识别到语言：$NEW_LANG"
-    else
-        log_warning "plan 中未找到语言信息"
-    fi
-
-    if [[ -n "$NEW_FRAMEWORK" ]]; then
-        log_info "识别到主要依赖：$NEW_FRAMEWORK"
-    fi
-
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
-        log_info "识别到存储：$NEW_DB"
-    fi
-
-    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
-        log_info "识别到项目类型：$NEW_PROJECT_TYPE"
-    fi
-}
-
-format_technology_stack() {
-    local lang="$1"
-    local framework="$2"
-    local parts=()
-
-    # 追加非空项
-    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
-    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
-
-    # 按合适的格式拼接
-    if [[ ${#parts[@]} -eq 0 ]]; then
-        echo ""
-    elif [[ ${#parts[@]} -eq 1 ]]; then
-        echo "${parts[0]}"
-    else
-        # 多项用 " + " 连接
-        local result="${parts[0]}"
-        for ((i=1; i<${#parts[@]}; i++)); do
-            result="$result + ${parts[i]}"
-        done
-        echo "$result"
-    fi
-}
-
-#==============================================================================
-# 模板与内容生成函数
-#==============================================================================
-
-get_project_structure() {
-    local project_type="$1"
-
-    if [[ "$project_type" == *"web"* ]]; then
-        echo "backend/\\nfrontend/\\ntests/"
-    else
-        echo "src/\\ntests/"
-    fi
-}
-
-get_commands_for_language() {
-    local lang="$1"
-
-    case "$lang" in
-        *"Python"*)
-            echo "cd src && pytest && ruff check ."
-            ;;
-        *"Rust"*)
-            echo "cargo test && cargo clippy"
-            ;;
-        *"JavaScript"*|*"TypeScript"*)
-            echo "npm test \\&\\& npm run lint"
-            ;;
-        *)
-            echo "# 请补充 $lang 对应的命令"
-            ;;
-    esac
-}
-
-get_language_conventions() {
-    local lang="$1"
-    echo "$lang：遵循该语言的通用约定"
-}
-
-create_new_agent_file() {
-    local target_file="$1"
-    local temp_file="$2"
-    local project_name="$3"
-    local current_date="$4"
-
-    if [[ ! -f "$TEMPLATE_FILE" ]]; then
-        log_error "未找到模板文件：$TEMPLATE_FILE"
-        return 1
-    fi
-
-    if [[ ! -r "$TEMPLATE_FILE" ]]; then
-        log_error "模板文件不可读：$TEMPLATE_FILE"
-        return 1
-    fi
-
-    log_info "正在从模板创建新的智能体上下文文件..."
-
-    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
-        log_error "复制模板文件失败"
-        return 1
-    fi
-
-    # 替换模板占位符
-    local project_structure
-    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
-
-    local commands
-    commands=$(get_commands_for_language "$NEW_LANG")
-
-    local language_conventions
-    language_conventions=$(get_language_conventions "$NEW_LANG")
-
-    # 使用更安全的方式执行替换，并处理潜在的特殊字符
-    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
-    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
-    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
-
-    # 按条件构建“当前技术栈”和“最近变更”的写入内容
-    local tech_stack
-    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
-        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
-    elif [[ -n "$escaped_lang" ]]; then
-        tech_stack="- $escaped_lang ($escaped_branch)"
-    elif [[ -n "$escaped_framework" ]]; then
-        tech_stack="- $escaped_framework ($escaped_branch)"
-    else
-        tech_stack="- ($escaped_branch)"
-    fi
-
-    local recent_change
-    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
-        recent_change="- $escaped_branch：新增 $escaped_lang + $escaped_framework"
-    elif [[ -n "$escaped_lang" ]]; then
-        recent_change="- $escaped_branch：新增 $escaped_lang"
-    elif [[ -n "$escaped_framework" ]]; then
-        recent_change="- $escaped_branch：新增 $escaped_framework"
-    else
-        recent_change="- $escaped_branch：新增"
-    fi
-
-    local substitutions=(
-        "s|\[PROJECT NAME\]|$project_name|"
-        "s|\[项目名称\]|$project_name|"
-        "s|\[DATE\]|$current_date|"
-        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
-        "s|\[从所有 plan.md 中提取\]|$tech_stack|"
-        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
-        "s|\[从计划中提取的真实结构\]|$project_structure|g"
-        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
-        "s|\[仅保留与当前技术栈相关的命令\]|$commands|"
-        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
-        "s|\[语言相关规范（仅保留当前使用的语言）\]|$language_conventions|"
-        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
-        "s|\[最近 3 个功能及其变更\]|$recent_change|"
-    )
-
-    for substitution in "${substitutions[@]}"; do
-        if ! sed -i.bak -e "$substitution" "$temp_file"; then
-            log_error "执行替换失败：$substitution"
-            rm -f "$temp_file" "$temp_file.bak"
-            return 1
-        fi
-    done
-
-    # 将 \n 序列转换为真实换行
-    newline=$(printf '\n')
-    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
-
-    # 清理备份文件
-    rm -f "$temp_file.bak" "$temp_file.bak2"
-
-    return 0
-}
-
-
-
-
-update_existing_agent_file() {
-    local target_file="$1"
-    local current_date="$2"
-
-    log_info "正在更新已有的智能体上下文文件..."
-
-    # 使用单个临时文件实现原子更新
-    local temp_file
-    temp_file=$(mktemp) || {
-        log_error "创建临时文件失败"
-        return 1
-    }
-
-    # 单次扫描处理文件
-    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
-    local new_tech_entries=()
-    local new_change_entry=""
-
-    # 准备需要追加的技术条目
-    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
-        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
-    fi
-
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
-        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
-    fi
-
-    # 准备需要追加的变更条目
-    if [[ -n "$tech_stack" ]]; then
-        new_change_entry="- $CURRENT_BRANCH：新增 $tech_stack"
-    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
-        new_change_entry="- $CURRENT_BRANCH：新增 $NEW_DB"
-    fi
-
-    # 检查文件中是否已存在对应章节
-    local has_active_technologies=0
-    local has_recent_changes=0
-
-    if grep -qE "^(## Active Technologies|## 当前技术栈)$" "$target_file" 2>/dev/null; then
-        has_active_technologies=1
-    fi
-
-    if grep -qE "^(## Recent Changes|## 最近变更)$" "$target_file" 2>/dev/null; then
-        has_recent_changes=1
-    fi
-
-    # 逐行处理文件内容
-    local in_tech_section=false
-    local in_changes_section=false
-    local tech_entries_added=false
-    local changes_entries_added=false
-    local existing_changes_count=0
-
-    while IFS= read -r line || [[ -n "$line" ]]; do
-        # 处理“当前技术栈 / Active Technologies”章节
-        if [[ "$line" == "## Active Technologies" ]] || [[ "$line" == "## 当前技术栈" ]]; then
-            echo "$line" >> "$temp_file"
-            in_tech_section=true
-            continue
-        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
-            # 章节结束前补充新条目
-            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-                tech_entries_added=true
-            fi
-            echo "$line" >> "$temp_file"
-            in_tech_section=false
-            continue
-        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
-            # 在章节内遇到空行前补充新条目
-            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-                tech_entries_added=true
-            fi
-            echo "$line" >> "$temp_file"
-            continue
-        fi
-
-        # 处理“最近变更 / Recent Changes”章节
-        if [[ "$line" == "## Recent Changes" ]] || [[ "$line" == "## 最近变更" ]]; then
-            echo "$line" >> "$temp_file"
-            # 在标题行后立刻写入新的变更条目
-            if [[ -n "$new_change_entry" ]]; then
-                echo "$new_change_entry" >> "$temp_file"
-            fi
-            in_changes_section=true
-            changes_entries_added=true
-            continue
-        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
-            echo "$line" >> "$temp_file"
-            in_changes_section=false
-            continue
-        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
-            # 仅保留原有的前 2 条变更（加上新写入的 1 条，总计最多 3 条）
-            if [[ $existing_changes_count -lt 2 ]]; then
-                echo "$line" >> "$temp_file"
-                ((existing_changes_count++))
-            fi
-            continue
-        fi
-
-        # 更新时间戳
-        if [[ "$line" =~ (Last[[:space:]]updated:|最近更新：).*([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) ]]; then
-            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
-        else
-            echo "$line" >> "$temp_file"
-        fi
-    done < "$target_file"
-
-    # 循环结束后检查：若仍在“当前技术栈 / Active Technologies”章节且未追加，则补充新条目
-    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-        tech_entries_added=true
-    fi
-
-    # 若章节不存在，则在文件末尾补充
-    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-        echo "" >> "$temp_file"
-        echo "## 当前技术栈" >> "$temp_file"
-        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-        tech_entries_added=true
-    fi
-
-    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
-        echo "" >> "$temp_file"
-        echo "## 最近变更" >> "$temp_file"
-        echo "$new_change_entry" >> "$temp_file"
-        changes_entries_added=true
-    fi
-
-    # 原子替换写入
-    if ! mv "$temp_file" "$target_file"; then
-        log_error "更新目标文件失败"
-        rm -f "$temp_file"
-        return 1
-    fi
-
-    return 0
-}
-#==============================================================================
-# 智能体文件更新入口
-#==============================================================================
-
-update_agent_file() {
-    local target_file="$1"
-    local agent_name="$2"
-
-    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
-        log_error "update_agent_file 需要 target_file 与 agent_name 参数"
-        return 1
-    fi
-
-    log_info "正在更新 $agent_name 上下文文件：$target_file"
-
-    local project_name
-    project_name=$(basename "$REPO_ROOT")
-    local current_date
-    current_date=$(date +%Y-%m-%d)
-
-    # 目录不存在则创建
-    local target_dir
-    target_dir=$(dirname "$target_file")
-    if [[ ! -d "$target_dir" ]]; then
-        if ! mkdir -p "$target_dir"; then
-            log_error "创建目录失败：$target_dir"
-            return 1
-        fi
-    fi
-
-    if [[ ! -f "$target_file" ]]; then
-        # 基于模板创建新文件
-        local temp_file
-        temp_file=$(mktemp) || {
-            log_error "创建临时文件失败"
-            return 1
-        }
-
-        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
-            if mv "$temp_file" "$target_file"; then
-                log_success "已创建新的 $agent_name 上下文文件"
-            else
-                log_error "移动临时文件到目标路径失败：$target_file"
-                rm -f "$temp_file"
-                return 1
-            fi
-        else
-            log_error "创建新的智能体文件失败"
-            rm -f "$temp_file"
-            return 1
-        fi
-    else
-        # 更新已有文件
-        if [[ ! -r "$target_file" ]]; then
-            log_error "无法读取已有文件：$target_file"
-            return 1
-        fi
-
-        if [[ ! -w "$target_file" ]]; then
-            log_error "无法写入已有文件：$target_file"
-            return 1
-        fi
-
-        if update_existing_agent_file "$target_file" "$current_date"; then
-            log_success "已更新 $agent_name 上下文文件"
-        else
-            log_error "更新已有智能体文件失败"
-            return 1
-        fi
-    fi
-
-    return 0
-}
-
-#==============================================================================
-# 智能体选择与处理
-#==============================================================================
-
-update_specific_agent() {
-    local agent_type="$1"
-
-    case "$agent_type" in
-        claude)
-            update_agent_file "$CLAUDE_FILE" "Claude Code"
-            ;;
-        gemini)
-            update_agent_file "$GEMINI_FILE" "Gemini CLI"
-            ;;
-        copilot)
-            update_agent_file "$COPILOT_FILE" "GitHub Copilot"
-            ;;
-        cursor-agent)
-            update_agent_file "$CURSOR_FILE" "Cursor IDE"
-            ;;
-        qwen)
-            update_agent_file "$QWEN_FILE" "Qwen Code"
-            ;;
-        opencode)
-            update_agent_file "$AGENTS_FILE" "opencode"
-            ;;
-        codex)
-            update_agent_file "$AGENTS_FILE" "Codex CLI"
-            ;;
-        windsurf)
-            update_agent_file "$WINDSURF_FILE" "Windsurf"
-            ;;
-        kilocode)
-            update_agent_file "$KILOCODE_FILE" "Kilo Code"
-            ;;
-        auggie)
-            update_agent_file "$AUGGIE_FILE" "Auggie CLI"
-            ;;
-        roo)
-            update_agent_file "$ROO_FILE" "Roo Code"
-            ;;
-        codebuddy)
-            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
-            ;;
-        qoder)
-            update_agent_file "$QODER_FILE" "Qoder CLI"
-            ;;
-        amp)
-            update_agent_file "$AMP_FILE" "Amp"
-            ;;
-        shai)
-            update_agent_file "$SHAI_FILE" "SHAI"
-            ;;
-        q)
-            update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
-            ;;
-        bob)
-            update_agent_file "$BOB_FILE" "IBM Bob"
-            ;;
-        *)
-            log_error "未知的 agent type：'$agent_type'"
-            log_error "可选值：claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|shai|q|bob|qoder"
-            exit 1
-            ;;
-    esac
-}
-
-update_all_existing_agents() {
-    local found_agent=false
-
-    # 检查各类智能体文件：存在则更新
-    if [[ -f "$CLAUDE_FILE" ]]; then
-        update_agent_file "$CLAUDE_FILE" "Claude Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$GEMINI_FILE" ]]; then
-        update_agent_file "$GEMINI_FILE" "Gemini CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$COPILOT_FILE" ]]; then
-        update_agent_file "$COPILOT_FILE" "GitHub Copilot"
-        found_agent=true
-    fi
-
-    if [[ -f "$CURSOR_FILE" ]]; then
-        update_agent_file "$CURSOR_FILE" "Cursor IDE"
-        found_agent=true
-    fi
-
-    if [[ -f "$QWEN_FILE" ]]; then
-        update_agent_file "$QWEN_FILE" "Qwen Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$AGENTS_FILE" ]]; then
-        update_agent_file "$AGENTS_FILE" "Codex/opencode"
-        found_agent=true
-    fi
-
-    if [[ -f "$WINDSURF_FILE" ]]; then
-        update_agent_file "$WINDSURF_FILE" "Windsurf"
-        found_agent=true
-    fi
-
-    if [[ -f "$KILOCODE_FILE" ]]; then
-        update_agent_file "$KILOCODE_FILE" "Kilo Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$AUGGIE_FILE" ]]; then
-        update_agent_file "$AUGGIE_FILE" "Auggie CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$ROO_FILE" ]]; then
-        update_agent_file "$ROO_FILE" "Roo Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$CODEBUDDY_FILE" ]]; then
-        update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$SHAI_FILE" ]]; then
-        update_agent_file "$SHAI_FILE" "SHAI"
-        found_agent=true
-    fi
-
-    if [[ -f "$QODER_FILE" ]]; then
-        update_agent_file "$QODER_FILE" "Qoder CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$Q_FILE" ]]; then
-        update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$BOB_FILE" ]]; then
-        update_agent_file "$BOB_FILE" "IBM Bob"
-        found_agent=true
-    fi
-
-    # 若未发现任何智能体文件，则创建默认的 Claude 文件
-    if [[ "$found_agent" == false ]]; then
-        log_info "未发现已有智能体文件，正在创建默认 Claude 文件..."
-        update_agent_file "$CLAUDE_FILE" "Claude Code"
-    fi
-}
-print_summary() {
-    echo
-    log_info "变更摘要："
-
-    if [[ -n "$NEW_LANG" ]]; then
-        echo "  - 新增语言：$NEW_LANG"
-    fi
-
-    if [[ -n "$NEW_FRAMEWORK" ]]; then
-        echo "  - 新增主要依赖：$NEW_FRAMEWORK"
-    fi
-
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
-        echo "  - 新增存储：$NEW_DB"
-    fi
-
-    echo
-
-    log_info "用法：$0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|shai|q|bob|qoder]"
-}
-
-#==============================================================================
-# 主执行流程
-#==============================================================================
-
-main() {
-    # 执行前校验环境
-    validate_environment
-
-    log_info "=== 正在更新功能 $CURRENT_BRANCH 的智能体上下文文件 ==="
-
-    # 解析 plan 文件以提取项目信息
-    if ! parse_plan_data "$NEW_PLAN"; then
-        log_error "解析 plan 数据失败"
-        exit 1
-    fi
-
-    # 根据传入的 agent type 决定更新范围
-    local success=true
-
-    if [[ -z "$AGENT_TYPE" ]]; then
-        # 未指定智能体：更新所有已存在的智能体文件
-        log_info "未指定智能体，正在更新所有已存在的智能体文件..."
-        if ! update_all_existing_agents; then
-            success=false
-        fi
-    else
-        # 指定了智能体：仅更新该智能体
-        log_info "正在更新指定智能体：$AGENT_TYPE"
-        if ! update_specific_agent "$AGENT_TYPE"; then
-            success=false
-        fi
-    fi
-
-    # 打印摘要
-    print_summary
-
-    if [[ "$success" == true ]]; then
-        log_success "智能体上下文更新完成"
-        exit 0
-    else
-        log_error "智能体上下文更新完成，但存在错误"
-        exit 1
-    fi
-}
-
-# Execute main function if script is run directly
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-    main "$@"
-fi

-# [项目名称] 开发规范
-
-从所有功能计划自动生成。最近更新：[DATE]
-
-## 当前技术栈
-
-[从所有 plan.md 中提取]
-
-## 项目结构
-
-```text
-[从计划中提取的真实结构]
-```
-
-## 常用命令
-
-[仅保留与当前技术栈相关的命令]
-
-## 代码风格
-
-[语言相关规范（仅保留当前使用的语言）]
-
-## 最近变更
-
-[最近 3 个功能及其变更]
-
-<!-- 手工补充开始 -->
-<!-- 手工补充结束 -->

-# [清单类型] 检查清单：[功能名称]
-
-**用途**：[本清单覆盖内容的简要说明]
-**创建时间**：[DATE]
-**关联功能**：[链接到 spec.md 或相关文档]
-
-**说明**：本清单由 `/speckit.checklist` 命令基于功能上下文与需求自动生成。
-
-<!--
-  ============================================================================
-  重要：以下检查项仅为示例，用于说明格式。
-
-  /speckit.checklist 命令必须基于以下信息，将这些示例替换为真实检查项：
-  - 用户提出的具体检查清单诉求
-  - spec.md 中的功能需求
-  - plan.md 中的技术上下文
-  - tasks.md 中的实现细节
-
-  生成的 checklist 文件中不要保留这些示例项。
-  ============================================================================
--->
-
-## [分类 1]
-
-- [ ] CHK001 第一条检查项（动作明确）
-- [ ] CHK002 第二条检查项
-- [ ] CHK003 第三条检查项
-
-## [分类 2]
-
-- [ ] CHK004 另一类检查项
-- [ ] CHK005 带具体判定标准的检查项
-- [ ] CHK006 本分类最后一条检查项
-
-## 备注
-
-- 完成后勾选：`[x]`
-- 发现问题可直接在行内补充说明
-- 可添加链接指向相关资源或文档
-- 条目按编号顺序排列，便于引用

-# 实现计划：[FEATURE]
-
-**分支**：`[###-feature-name]` | **日期**：[DATE] | **规格说明**：[link]
-**输入**：来自 `/specs/[###-feature-name]/spec.md` 的功能规格说明
-
-**说明**：本模板由 `/speckit.plan` 命令填充。执行流程可参考 `.specify/templates/commands/plan.md`。
-
-## 摘要
-
-[从功能规格中提取：核心需求 +（结合 research 的）技术方案摘要]
-
-## 技术上下文
-
-<!--
-  必填：将本章节内容替换为项目的技术细节。
-  这里的结构仅用于引导迭代过程，可按需调整。
--->
-
-**语言/版本**: [例如 Python 3.11、Swift 5.9、Rust 1.75 或 NEEDS CLARIFICATION]
-**主要依赖**: [例如 FastAPI、UIKit、LLVM 或 NEEDS CLARIFICATION]
-**存储**: [如适用，例如 PostgreSQL、CoreData、文件 或 N/A]
-**测试**: [例如 pytest、XCTest、cargo test 或 NEEDS CLARIFICATION]
-**目标平台**: [例如 Linux 服务器、iOS 15+、WASM 或 NEEDS CLARIFICATION]
-**工程类型**: [single/web/mobile - 决定源码结构]
-**性能目标**: [领域相关，例如 1000 req/s、10k lines/sec、60 fps 或 NEEDS CLARIFICATION]
-**约束**: [领域相关，例如 <200ms p95、<100MB 内存、支持离线 或 NEEDS CLARIFICATION]
-**规模/范围**: [领域相关，例如 10k 用户、1M LOC、50 个页面 或 NEEDS CLARIFICATION]
-
-## 宪法检查
-
-*门禁：必须在阶段 0 调研前通过；在阶段 1 设计后需要复检。*
-
-[根据 constitution 文件确定门禁项]
-
-
-## 项目结构
-
-### 文档（本功能）
-
-```text
-specs/[###-feature]/
-├── plan.md              # 本文件（/speckit.plan 输出）
-├── research.md          # 阶段 0 输出（/speckit.plan）
-├── data-model.md        # 阶段 1 输出（/speckit.plan）
-├── quickstart.md        # 阶段 1 输出（/speckit.plan）
-├── contracts/           # 阶段 1 输出（/speckit.plan）
-└── tasks.md             # 阶段 2 输出（/speckit.tasks - 不由 /speckit.plan 创建）
-```
-
-### 源码（仓库根目录）
-<!--
-  必填：将下方占位树替换为本功能对应的真实目录结构。
-  删除未使用的选项，并将所选结构扩展为真实路径（例如 apps/admin、packages/xxx）。
-  最终交付的 plan.md 不应包含 “选项” 字样。
--->
-
-```text
-# [不使用则删除] 选项 1：单体工程（默认）
-src/
-├── models/
-├── services/
-├── cli/
-└── lib/
-
-tests/
-├── contract/
-├── integration/
-└── unit/
-
-# [不使用则删除] 选项 2：Web 应用（检测到 "frontend" + "backend" 时）
-backend/
-├── src/
-│   ├── models/
-│   ├── services/
-│   └── api/
-└── tests/
-
-frontend/
-├── src/
-│   ├── components/
-│   ├── pages/
-│   └── services/
-└── tests/
-
-# [不使用则删除] 选项 3：移动端 + API（检测到 "iOS/Android" 时）
-api/
-└── [同 backend 的结构]
-
-ios/ 或 android/
-└── [平台相关结构：功能模块、UI 流程、平台测试]
-```
-
-**结构选择**: [说明最终选择的结构，并引用上面列出的真实目录]
-
-## 复杂度记录
-
-> **仅在“宪法检查”存在需要解释的违规项时填写**
-
-| 违规项 | 必要性 | 为什么不能用更简单方案 |
-|--------|--------|--------------------------|
-| [例如：第 4 个子工程] | [当前需求] | [为何 3 个工程不够] |
-| [例如：Repository 模式] | [具体问题] | [为何不能直接访问数据库] |

-# 功能规格说明：[功能名称]
-
-**功能分支**：`[###-feature-name]`  
-**创建时间**：[DATE]  
-**状态**：草稿  
-**输入**：用户描述："$ARGUMENTS"
-
-## 用户场景与验收 *(必填)*
-
-<!--
-  重要：用户故事必须按重要性排序，体现为“用户旅程”优先级。
-  每个用户故事/旅程都必须可以独立验收——意味着即使只实现其中一个，
-  也应当形成可用的 MVP（最小可用产品）并能交付价值。
-
-  为每个故事分配优先级（P1、P2、P3...），其中 P1 最关键。
-  将每个故事视为一段可独立交付的功能切片，能够：
-  - 独立开发
-  - 独立验收
-  - 独立部署
-  - 独立向用户演示
--->
-
-### 用户故事 1 - [简短标题]（优先级：P1）
-
-[用通俗语言描述该用户旅程]
-
-**为什么是这个优先级**：[解释价值以及为何排在该优先级]
-
-**独立验收**：[描述如何独立验收——例如：“通过 [具体动作] 即可完整验收，并交付 [具体价值]”】【示例仅供参考】
-
-**验收场景**：
-
-1. **假设** [初始状态]，**当** [动作]，**则** [期望结果]
-2. **假设** [初始状态]，**当** [动作]，**则** [期望结果]
-
----
-
-### 用户故事 2 - [简短标题]（优先级：P2）
-
-[用通俗语言描述该用户旅程]
-
-**为什么是这个优先级**：[解释价值以及为何排在该优先级]
-
-**独立验收**：[描述如何独立验收]
-
-**验收场景**：
-
-1. **假设** [初始状态]，**当** [动作]，**则** [期望结果]
-
----
-
-### 用户故事 3 - [简短标题]（优先级：P3）
-
-[用通俗语言描述该用户旅程]
-
-**为什么是这个优先级**：[解释价值以及为何排在该优先级]
-
-**独立验收**：[描述如何独立验收]
-
-**验收场景**：
-
-1. **假设** [初始状态]，**当** [动作]，**则** [期望结果]
-
----
-
-[按需补充更多用户故事，并为每个故事分配优先级]
-
-### 边界情况
-
-<!--
-  需要补全：本章节内容是占位符。
-  请补充正确的边界情况。
--->
-
-- 当 [边界条件] 时会发生什么？
-- 系统如何处理 [错误场景]？
-
-## 需求 *(必填)*
-
-<!--
-  需要补全：本章节内容是占位符。
-  请补充正确的功能需求。
--->
-
-### 功能需求
-
-- **FR-001**：系统必须 [具体能力，例如“允许用户创建账号”]
-- **FR-002**：系统必须 [具体能力，例如“校验邮箱地址”]  
-- **FR-003**：用户必须能够 [关键交互，例如“重置密码”]
-- **FR-004**：系统必须 [数据要求，例如“持久化用户偏好”]
-- **FR-005**：系统必须 [行为要求，例如“记录所有安全事件”]
-
-*标记不清晰需求的示例：*
-
-- **FR-006**：系统必须通过 [NEEDS CLARIFICATION：认证方式未指定——邮箱/密码、SSO、OAuth？] 对用户进行认证
-- **FR-007**：系统必须保留用户数据 [NEEDS CLARIFICATION：保留期限未指定]
-
-### 关键实体 *(当功能涉及数据时填写)*
-
-- **[实体 1]**：[表示什么；关键属性（不写实现细节）]
-- **[实体 2]**：[表示什么；与其他实体的关系]
-
-## 成功标准 *(必填)*
-
-<!--
-  需要补全：定义可度量的成功标准。
-  必须与技术实现无关，并且可度量。
--->
-
-### 可度量结果
-
-- **SC-001**：[可度量指标，例如“用户可在 2 分钟内完成账号创建”】【示例仅供参考】
-- **SC-002**：[可度量指标，例如“系统在 1000 并发用户下无明显劣化”】【示例仅供参考】
-- **SC-003**：[用户满意度指标，例如“90% 的用户首次尝试即可完成主任务”】【示例仅供参考】
-- **SC-004**：[业务指标，例如“将与 [X] 相关的支持工单减少 50%”】【示例仅供参考】

----
-
-description: "功能实现的任务清单模板"
----
-
-# 任务清单：[功能名称]
-
-**输入**：来自 `/specs/[###-feature-name]/` 的设计与规格文档
-**前置条件**：plan.md（必需）、spec.md（用户故事必需）、research.md、data-model.md、contracts/
-
-**测试**：下方示例包含测试任务。测试是可选的——仅在功能规格中明确要求时才需要包含。
-
-**组织方式**：任务按用户故事分组，保证每个故事都能独立实现与独立验证。
-
-## 格式：`[ID] [P?] [Story] 描述`
-
-- **[P]**：可并行执行（不同文件、无依赖）
-- **[Story]**：任务所属用户故事（例如 US1、US2、US3）
-- 描述中包含准确的文件路径
-
-## 路径约定
-
-- **单体工程**：仓库根目录下 `src/`、`tests/`
-- **Web 应用**：`backend/src/`、`frontend/src/`
-- **移动端**：`api/src/`、`ios/src/` 或 `android/src/`
-- 下方展示默认按“单体工程”组织；请根据 plan.md 的结构调整
-
-<!--
-  ============================================================================
-  重要：以下任务仅为示例，用于说明结构与写法。
-
-  /speckit.tasks 命令必须基于以下信息，将这些示例替换为真实任务：
-  - spec.md 的用户故事（含优先级 P1、P2、P3...）
-  - plan.md 的功能与实现要求
-  - data-model.md 的实体
-  - contracts/ 的接口定义
-
-  任务必须按用户故事组织，使每个故事都能：
-  - 独立实现
-  - 独立验证
-  - 作为 MVP 增量交付
-
-  生成的 tasks.md 文件中不要保留这些示例任务。
-  ============================================================================
--->
-
-## 阶段 1：准备（共享基础设施）
-
-**目标**：项目初始化与基础结构搭建
-
-- [ ] T001 按实现计划创建项目结构
-- [ ] T002 初始化 [language] 工程并安装 [framework] 依赖
-- [ ] T003 [P] 配置 lint 与格式化工具
-
----
-
-## 阶段 2：基础（阻塞性前置条件）
-
-**目标**：核心基础设施（任何用户故事开始前必须完成）
-
-**⚠️ 关键**：在本阶段完成前，不允许开始任何用户故事的工作
-
-基础任务示例（请根据项目实际情况调整）：
-
-- [ ] T004 建立数据库结构与迁移机制
-- [ ] T005 [P] 实现认证/鉴权框架
-- [ ] T006 [P] 建立 API 路由与中间件结构
-- [ ] T007 创建所有故事依赖的基础模型/实体
-- [ ] T008 配置错误处理与日志基础设施
-- [ ] T009 建立环境配置管理
-
-**检查点**：基础设施就绪——用户故事实现可以并行推进
-
----
-
-## 阶段 3：用户故事 1 - [标题]（优先级：P1）🎯 MVP
-
-**目标**：[简述该故事交付内容]
-
-**独立验证**：[如何单独验证该故事可用]
-
-### 用户故事 1 的测试（可选：仅在明确要求测试时）⚠️
-
-> **注意：先写测试，并确保在实现前测试会失败**
-
-- [ ] T010 [P] [US1] 为 [endpoint] 编写契约测试：tests/contract/test_[name].py
-- [ ] T011 [P] [US1] 为 [用户旅程] 编写集成测试：tests/integration/test_[name].py
-
-### 用户故事 1 的实现
-
-- [ ] T012 [P] [US1] 创建 [Entity1] 模型：src/models/[entity1].py
-- [ ] T013 [P] [US1] 创建 [Entity2] 模型：src/models/[entity2].py
-- [ ] T014 [US1] 实现 [Service]：src/services/[service].py（依赖 T012、T013）
-- [ ] T015 [US1] 实现 [endpoint/feature]：src/[location]/[file].py
-- [ ] T016 [US1] 增加校验与错误处理
-- [ ] T017 [US1] 为用户故事 1 的关键操作补充日志
-
-**检查点**：此时用户故事 1 应完整可用，且可独立验证
-
----
-
-## 阶段 4：用户故事 2 - [标题]（优先级：P2）
-
-**目标**：[简述该故事交付内容]
-
-**独立验证**：[如何单独验证该故事可用]
-
-### 用户故事 2 的测试（可选：仅在明确要求测试时）⚠️
-
-- [ ] T018 [P] [US2] 为 [endpoint] 编写契约测试：tests/contract/test_[name].py
-- [ ] T019 [P] [US2] 为 [用户旅程] 编写集成测试：tests/integration/test_[name].py
-
-### 用户故事 2 的实现
-
-- [ ] T020 [P] [US2] 创建 [Entity] 模型：src/models/[entity].py
-- [ ] T021 [US2] 实现 [Service]：src/services/[service].py
-- [ ] T022 [US2] 实现 [endpoint/feature]：src/[location]/[file].py
-- [ ] T023 [US2] 与用户故事 1 的组件集成（如需要）
-
-**检查点**：此时用户故事 1 和 2 应都能独立工作
-
----
-
-## 阶段 5：用户故事 3 - [标题]（优先级：P3）
-
-**目标**：[简述该故事交付内容]
-
-**独立验证**：[如何单独验证该故事可用]
-
-### 用户故事 3 的测试（可选：仅在明确要求测试时）⚠️
-
-- [ ] T024 [P] [US3] 为 [endpoint] 编写契约测试：tests/contract/test_[name].py
-- [ ] T025 [P] [US3] 为 [用户旅程] 编写集成测试：tests/integration/test_[name].py
-
-### 用户故事 3 的实现
-
-- [ ] T026 [P] [US3] 创建 [Entity] 模型：src/models/[entity].py
-- [ ] T027 [US3] 实现 [Service]：src/services/[service].py
-- [ ] T028 [US3] 实现 [endpoint/feature]：src/[location]/[file].py
-
-**检查点**：此时所有用户故事都应可独立运行
-
----
-
-[如需要，可按同样格式继续添加更多用户故事阶段]
-
----
-
-## 阶段 N：打磨与横切关注点
-
-**目标**：影响多个用户故事的改进项
-
-- [ ] TXXX [P] 更新 docs/ 内的文档
-- [ ] TXXX 代码清理与重构
-- [ ] TXXX 跨故事的性能优化
-- [ ] TXXX [P] 在 tests/unit/ 增加单测（如需）
-- [ ] TXXX 安全加固
-- [ ] TXXX 验证 quickstart.md
-
----
-
-## 依赖与执行顺序
-
-### 阶段依赖
-
-- **准备（阶段 1）**：无依赖，可立即开始
-- **基础（阶段 2）**：依赖准备阶段完成——阻塞所有用户故事
-- **用户故事（阶段 3+）**：均依赖基础阶段完成
-  - 之后可并行推进（若有人力）
-  - 或按优先级串行推进（P1 → P2 → P3）
-- **打磨（最终阶段）**：依赖所有目标用户故事完成
-
-### 用户故事依赖
-
-- **用户故事 1（P1）**：基础阶段后可开始——不依赖其他故事
-- **用户故事 2（P2）**：基础阶段后可开始——可能与 US1 集成，但应保持可独立验证
-- **用户故事 3（P3）**：基础阶段后可开始——可能与 US1/US2 集成，但应保持可独立验证
-
-### 每个用户故事内部顺序
-
-- 测试（如包含）必须先写，且在实现前应失败
-- 先模型，再服务
-- 先服务，再接口/端点
-- 先核心实现，再集成
-- 完成当前故事后再进入下一个优先级
-
-### 并行机会
-
-- 阶段 1 中标记 [P] 的任务可并行
-- 阶段 2 中标记 [P] 的任务可并行（在阶段 2 内）
-- 基础阶段完成后，所有用户故事可并行开始（若团队容量允许）
-- 用户故事内标记 [P] 的测试可并行
-- 用户故事内标记 [P] 的模型可并行
-- 不同用户故事可由不同成员并行推进
-
----
-
-## 并行示例：用户故事 1
-
-```bash
-# 一次性启动用户故事 1 的所有测试（如需要测试）：
-任务: "为 [endpoint] 编写契约测试：tests/contract/test_[name].py"
-任务: "为 [用户旅程] 编写集成测试：tests/integration/test_[name].py"
-
-# 一次性启动用户故事 1 的所有模型任务：
-任务: "创建 [Entity1] 模型：src/models/[entity1].py"
-任务: "创建 [Entity2] 模型：src/models/[entity2].py"
-```
-
----
-
-## 实施策略
-
-### MVP 优先（仅用户故事 1）
-
-1. 完成阶段 1：准备
-2. 完成阶段 2：基础（关键：阻塞所有故事）
-3. 完成阶段 3：用户故事 1
-4. **停止并验证**：独立验证用户故事 1
-5. 如已就绪则部署/演示
-
-### 增量交付
-
-1. 完成准备 + 基础 → 基础设施就绪
-2. 增加用户故事 1 → 独立验证 → 部署/演示（MVP）
-3. 增加用户故事 2 → 独立验证 → 部署/演示
-4. 增加用户故事 3 → 独立验证 → 部署/演示
-5. 每个故事都应在不破坏既有能力的前提下增量交付价值
-
-### 多人并行策略
-
-多人协作时：
-
-1. 团队协作完成准备 + 基础
-2. 基础完成后：
-   - 开发 A：用户故事 1
-   - 开发 B：用户故事 2
-   - 开发 C：用户故事 3
-3. 各故事独立完成并独立集成
-
----
-
-## 备注
-
-- [P] 任务：不同文件、无依赖，可并行
-- [Story] 标签：将任务映射到具体用户故事，便于追溯
-- 每个用户故事都应可独立完成与独立验证
-- 实现前先确认测试会失败（如有测试）
-- 每完成一个任务或合理的任务组再提交
-- 在任意检查点都可以停下来做独立验证
-- 避免：任务描述模糊、同文件冲突、跨故事强耦合导致无法独立交付

-对话处理完成一个任务后，需要更新changelog.md文件，添加一个新的版本号，版本号的格式为YYYY-MM-DD，版本号的内容为任务的描述.

----
-name: vue-best-practices
-description: Vue 3 TypeScript, vue-tsc, Volar, Vite, component props, testing, composition API.
----
-
-# Vue Best Practices
-
-## Capability Rules
-
-| Rule | Keywords | Description |
-|------|----------|-------------|
-| [vue-tsc-strict-templates](rules/vue-tsc-strict-templates.md) | undefined component, template error, strictTemplates | Catch undefined components in templates |
-| [fallthrough-attributes](rules/fallthrough-attributes.md) | fallthrough, $attrs, wrapper component | Type-check fallthrough attributes |
-| [strict-css-modules](rules/strict-css-modules.md) | css modules, $style, typo | Catch CSS module class typos |
-| [data-attributes-config](rules/data-attributes-config.md) | data-*, strictTemplates, attribute | Allow data-* attributes |
-| [volar-3-breaking-changes](rules/volar-3-breaking-changes.md) | volar, vue-language-server, editor | Fix Volar 3.0 upgrade issues |
-| [module-resolution-bundler](rules/module-resolution-bundler.md) | cannot find module, @vue/tsconfig, moduleResolution | Fix module resolution errors |
-| [unplugin-auto-import-conflicts](rules/unplugin-auto-import-conflicts.md) | unplugin, auto-import, types any | Fix unplugin type conflicts |
-| [codeactions-save-performance](rules/codeactions-save-performance.md) | slow save, vscode, performance | Fix slow save in large projects |
-| [duplicate-plugin-detection](rules/duplicate-plugin-detection.md) | duplicate plugin, vite, vue plugin | Detect duplicate plugins |
-| [define-model-update-event](rules/define-model-update-event.md) | defineModel, update event, undefined | Fix model update errors |
-| [with-defaults-union-types](rules/with-defaults-union-types.md) | withDefaults, union type, default | Fix union type defaults |
-| [deep-watch-numeric](rules/deep-watch-numeric.md) | watch, deep, array, Vue 3.5 | Efficient array watching |
-| [vue-directive-comments](rules/vue-directive-comments.md) | @vue-ignore, @vue-skip, template | Control template type checking |
-| [script-setup-jsdoc](rules/script-setup-jsdoc.md) | jsdoc, script setup, documentation | Add JSDoc to script setup |
-| [vue-router-typed-params](rules/vue-router-typed-params.md) | route params, typed router, unplugin | Fix route params typing |
-
-## Efficiency Rules
-
-| Rule | Keywords | Description |
-|------|----------|-------------|
-| [hmr-vue-ssr](rules/hmr-vue-ssr.md) | hmr, ssr, hot reload | Fix HMR in SSR apps |
-| [pinia-store-mocking](rules/pinia-store-mocking.md) | pinia, mock, vitest, store | Mock Pinia stores |
-
-## Reference
-
-- [Vue Language Tools](https://github.com/vuejs/language-tools)
-- [Vue 3 Documentation](https://vuejs.org/)
\ No newline at end of file

----
-title: Fix Slow Save Times with Code Actions Setting
-impact: HIGH
-impactDescription: fixes 30-60 second save delays in large Vue projects
-type: capability
-tags: performance, save-time, vscode, code-actions, volar
----
-
-# Fix Slow Save Times with Code Actions Setting
-
-**Impact: HIGH** - fixes 30-60 second save delays in large Vue projects
-
-In large Vue projects, saving files can take 30-60+ seconds due to VSCode's code actions triggering expensive TypeScript state synchronization.
-
-## Problem
-
-Symptoms:
-- Save operation takes 30+ seconds
-- Editor becomes unresponsive during save
-- CPU spikes when saving Vue files
-- Happens more in larger projects
-
-## Root Cause
-
-VSCode emits document change events multiple times during save cycles. Each event triggers Volar to synchronize with TypeScript, causing expensive re-computation.
-
-## Solution
-
-Disable code actions or limit their timeout:
-
-**Option 1: Disable code actions (fastest)**
-```json
-// .vscode/settings.json
-{
-  "vue.codeActions.enabled": false
-}
-```
-
-**Option 2: Limit code action time**
-```json
-// .vscode/settings.json
-{
-  "vue.codeActions.savingTimeLimit": 1000
-}
-```
-
-**Option 3: Disable specific code actions**
-```json
-// .vscode/settings.json
-{
-  "vue.codeActions.enabled": true,
-  "editor.codeActionsOnSave": {
-    "source.organizeImports": "never"
-  }
-}
-```
-
-## VSCode Version Requirement
-
-VSCode 1.81.0+ includes fixes that reduce save time issues. Upgrade if using an older version.
-
-## Additional Optimizations
-
-```json
-// .vscode/settings.json
-{
-  "vue.codeActions.enabled": false,
-  "editor.formatOnSave": true,
-  "editor.codeActionsOnSave": {},
-  "[vue]": {
-    "editor.formatOnSave": true,
-    "editor.defaultFormatter": "Vue.volar"
-  }
-}
-```
-
-## Reference
-
-- [Vue Language Tools Discussion #2740](https://github.com/vuejs/language-tools/discussions/2740)

----
-title: Allow Data Attributes with Strict Templates
-impact: MEDIUM
-impactDescription: fixes data-testid and data-* attribute errors in strict mode
-type: capability
-tags: dataAttributes, vueCompilerOptions, strictTemplates, data-testid, testing
----
-
-# Allow Data Attributes with Strict Templates
-
-**Impact: MEDIUM** - fixes data-testid and data-* attribute errors in strict mode
-
-With `strictTemplates` enabled, `data-*` attributes on components cause type errors. Use the `dataAttributes` option to allow specific patterns.
-
-## Problem
-
-```vue
-<template>
-  <!-- Error: Property 'data-testid' does not exist on type... -->
-  <MyComponent data-testid="submit-button" />
-
-  <!-- Error: Property 'data-cy' does not exist on type... -->
-  <MyComponent data-cy="login-form" />
-</template>
-```
-
-## Solution
-
-Configure `dataAttributes` to allow specific patterns:
-
-```json
-// tsconfig.json or tsconfig.app.json
-{
-  "vueCompilerOptions": {
-    "strictTemplates": true,
-    "dataAttributes": ["data-*"]
-  }
-}
-```
-
-Now all `data-*` attributes are allowed on any component.
-
-## Specific Patterns
-
-You can be more selective:
-
-```json
-{
-  "vueCompilerOptions": {
-    "dataAttributes": [
-      "data-testid",
-      "data-cy",
-      "data-test-*"
-    ]
-  }
-}
-```
-
-This only allows the specified patterns, not all data attributes.
-
-## Common Testing Attributes
-
-For testing libraries, allow their specific attributes:
-
-| Library | Attribute | Pattern |
-|---------|-----------|---------|
-| Testing Library | `data-testid` | `"data-testid"` |
-| Cypress | `data-cy` | `"data-cy"` |
-| Playwright | `data-testid` | `"data-testid"` |
-| Generic | All data attributes | `"data-*"` |
-
-## Reference
-
-- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)

----
-title: Vue 3.5+ Deep Watch Numeric Depth
-impact: MEDIUM
-impactDescription: enables efficient array mutation watching with numeric deep option
-type: capability
-tags: watch, deep, vue-3.5, array, mutation, performance
----
-
-# Vue 3.5+ Deep Watch Numeric Depth
-
-**Impact: MEDIUM** - enables efficient array mutation watching with numeric deep option
-
-Vue 3.5 introduced `deep: number` for watch depth control. This allows watching array mutations without the performance cost of deep traversal.
-
-## Symptoms
-
-- Array mutations not triggering watch callback
-- Deep watch causing performance issues on large nested objects
-- Unaware of new Vue 3.5 feature
-
-> **Note:** TypeScript error "Type 'number' is not assignable to type 'boolean'" no longer occurs with Vue 3.5+ and current TypeScript versions. The types now correctly support numeric `deep` values.
-
-## The Feature
-
-```typescript
-// Vue 3.5+ only
-watch(items, (newVal) => {
-  // Triggered on array mutations (push, pop, splice, etc.)
-}, { deep: 1 })
-```
-
-| deep value | Behavior |
-|------------|----------|
-| `true` | Full recursive traversal (original behavior) |
-| `false` | Only reference changes |
-| `1` | One level deep - array mutations, not nested objects |
-| `2` | Two levels deep |
-| `n` | N levels deep |
-
-## Fix
-
-**Step 1: Ensure Vue 3.5+**
-```bash
-npm install vue@^3.5.0
-```
-
-**Step 2: Update @vue/runtime-core types**
-```bash
-npm install -D @vue/runtime-core@latest
-```
-
-**Step 3: Use numeric depth**
-```typescript
-import { watch, ref } from 'vue'
-
-const items = ref([{ id: 1, data: { nested: 'value' } }])
-
-// Watch array mutations only (push, pop, etc.)
-watch(items, (newItems) => {
-  console.log('Array mutated')
-}, { deep: 1 })
-
-// Won't trigger on: items.value[0].data.nested = 'new'
-// Will trigger on: items.value.push(newItem)
-```
-
-## Performance Comparison
-
-```typescript
-const largeNestedData = ref({ /* deeply nested structure */ })
-
-// SLOW - traverses entire structure
-watch(largeNestedData, handler, { deep: true })
-
-// FAST - only watches top-level changes
-watch(largeNestedData, handler, { deep: 1 })
-
-// FASTEST - only reference changes
-watch(largeNestedData, handler, { deep: false })
-```
-
-## Alternative: watchEffect for Selective Tracking
-
-```typescript
-// Only tracks properties actually accessed
-watchEffect(() => {
-  // Only re-runs when items.value.length or first item changes
-  console.log(items.value.length, items.value[0]?.id)
-})
-```
-
-## TypeScript Note
-
-If TypeScript complains about numeric deep, ensure:
-1. Vue version is 3.5+
-2. `@vue/runtime-core` types are updated
-3. tsconfig targets correct node_modules types
-
-## Reference
-
-- [Vue Watchers Docs](https://vuejs.org/guide/essentials/watchers.html)
-- [Vue 3.5 Release Notes](https://blog.vuejs.org/posts/vue-3-5)

----
-title: defineModel Fires Update Event with Undefined
-impact: MEDIUM
-impactDescription: fixes runtime errors from unexpected undefined in model updates
-type: capability
-tags: defineModel, v-model, update-event, undefined, vue-3.5
----
-
-# defineModel Fires Update Event with Undefined
-
-**Impact: MEDIUM** - fixes runtime errors from unexpected undefined in model updates
-
-> **Version Note (2025):** This issue may be resolved in Vue 3.5+. Testing with Vue 3.5.26 could not reproduce the double emission with `undefined`. If you're on Vue 3.5+, verify the issue exists in your specific scenario before applying workarounds.
-
-Components using `defineModel` may fire the `@update:model-value` event with `undefined` in certain edge cases. TypeScript types don't always reflect this behavior, potentially causing runtime errors when the parent expects a non-nullable value.
-
-## Symptoms
-
-- Parent component receives `undefined` unexpectedly
-- Runtime error: "Cannot read property of undefined"
-- Type mismatch between expected `T` and received `T | undefined`
-- Issue appears when clearing/resetting the model value
-
-## Root Cause
-
-`defineModel` returns `Ref<T | undefined>` by default, even when `T` is non-nullable. The update event can fire with `undefined` when:
-- Component unmounts
-- Model is explicitly cleared
-- Internal state resets
-
-## Fix
-
-**Option 1: Use required option (Vue 3.5+)**
-```typescript
-// Returns Ref<Item> instead of Ref<Item | undefined>
-const model = defineModel<Item>({ required: true })
-```
-
-**Option 2: Type parent handler to accept undefined**
-```vue
-<template>
-  <MyComponent
-    v-model="item"
-    @update:model-value="handleUpdate"
-  />
-</template>
-
-<script setup lang="ts">
-// Handle both value and undefined
-const handleUpdate = (value: Item | undefined) => {
-  if (value !== undefined) {
-    item.value = value
-  }
-}
-</script>
-```
-
-**Option 3: Use default value in defineModel**
-```typescript
-const model = defineModel<string>({ default: '' })
-```
-
-## Type Declaration Pattern
-
-```typescript
-// In child component
-interface Props {
-  modelValue: Item
-}
-const model = defineModel<Item>({ required: true })
-
-// Emits will be typed as (value: Item) not (value: Item | undefined)
-```
-
-## Reference
-
-- [vuejs/core#12817](https://github.com/vuejs/core/issues/12817)
-- [vuejs/core#10103](https://github.com/vuejs/core/issues/10103)
-- [defineModel docs](https://vuejs.org/api/sfc-script-setup.html#definemodel)

----
-title: Duplicate Vue Plugin Detection
-impact: MEDIUM
-impactDescription: fixes cryptic build errors from Vue plugin registered twice
-type: capability
-tags: vite, plugin, vue, duplicate, config, inline
----
-
-# Duplicate Vue Plugin Detection
-
-**Impact: MEDIUM** - fixes cryptic build errors from Vue plugin registered twice
-
-When using Vite's JavaScript API, if the Vue plugin is loaded in `vite.config.js` and specified again in `inlineConfig`, it gets registered twice, causing cryptic build errors.
-
-## Symptoms
-
-- Build produces unexpected output or fails silently
-- "Cannot read property of undefined" during build
-- Different build behavior between CLI and JavaScript API
-- Vue components render incorrectly after build
-
-## Root Cause
-
-Vite doesn't deduplicate plugins by name when merging configs. The Vue plugin's internal state gets corrupted when registered twice.
-
-## Fix
-
-**Option 1: Use configFile: false with inline plugins**
-```typescript
-import { build } from 'vite'
-import vue from '@vitejs/plugin-vue'
-
-await build({
-  configFile: false,  // Don't load vite.config.js
-  plugins: [vue()],
-  // ... rest of config
-})
-```
-
-**Option 2: Don't specify plugins in inlineConfig**
-```typescript
-// vite.config.js already has vue plugin
-import { build } from 'vite'
-
-await build({
-  // Don't add vue plugin here - it's in vite.config.js
-  root: './src',
-  build: { outDir: '../dist' }
-})
-```
-
-**Option 3: Filter out Vue plugin before merging**
-```typescript
-import { build, loadConfigFromFile } from 'vite'
-import vue from '@vitejs/plugin-vue'
-
-const { config } = await loadConfigFromFile({ command: 'build', mode: 'production' })
-
-// Remove existing Vue plugin
-const filteredPlugins = config.plugins?.filter(
-  p => !p || (Array.isArray(p) ? false : p.name !== 'vite:vue')
-) || []
-
-await build({
-  ...config,
-  plugins: [...filteredPlugins, vue({ /* your options */ })]
-})
-```
-
-## Detection Script
-
-Add this to debug plugin registration:
-```typescript
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    vue(),
-    {
-      name: 'debug-plugins',
-      configResolved(config) {
-        const vuePlugins = config.plugins.filter(p => p.name?.includes('vue'))
-        if (vuePlugins.length > 1) {
-          console.warn('WARNING: Multiple Vue plugins detected:', vuePlugins.map(p => p.name))
-        }
-      }
-    }
-  ]
-})
-```
-
-## Common Scenarios
-
-| Scenario | Solution |
-|----------|----------|
-| Using `vite.createServer()` | Use `configFile: false` |
-| Build script with custom config | Don't duplicate plugins |
-| Monorepo with shared config | Check for plugin inheritance |
-
-## Reference
-
-- [Vite Issue #5335](https://github.com/vitejs/vite/issues/5335)
-- [Vite JavaScript API](https://vite.dev/guide/api-javascript.html)

----
-title: Enable Fallthrough Attributes Type Checking
-impact: HIGH
-impactDescription: enables type-safe fallthrough attributes in component libraries
-type: capability
-tags: fallthroughAttributes, vueCompilerOptions, component-library, wrapper-components
----
-
-# Enable Fallthrough Attributes Type Checking
-
-**Impact: MEDIUM** - enables type-aware attribute forwarding in component libraries
-
-When building component libraries with wrapper components, enable `fallthroughAttributes` to get IDE autocomplete for attributes that will be forwarded to child elements.
-
-## What It Does
-
-Wrapper components that pass attributes to child elements can benefit from type-aware completion:
-
-```vue
-<!-- MyButton.vue - wrapper around native button -->
-<template>
-  <button v-bind="$attrs"><slot /></button>
-</template>
-```
-
-## Solution
-
-Enable `fallthroughAttributes` in your tsconfig:
-
-```json
-// tsconfig.json or tsconfig.app.json
-{
-  "vueCompilerOptions": {
-    "fallthroughAttributes": true
-  }
-}
-```
-
-## How It Works
-
-When `fallthroughAttributes: true`:
-- Vue Language Server analyzes which element receives `$attrs`
-- IDE autocomplete suggests valid attributes for the target element
-- Helps developers discover available attributes
-
-> **Note:** This primarily enables IDE autocomplete for valid fallthrough attributes. It does NOT reject invalid attributes as type errors - arbitrary attributes are still allowed.
-
-## Related Options
-
-Combine with `strictTemplates` for comprehensive checking:
-
-```json
-{
-  "vueCompilerOptions": {
-    "strictTemplates": true,
-    "fallthroughAttributes": true
-  }
-}
-```
-
-## Reference
-
-- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)

----
-title: HMR Debugging for Vue SSR
-impact: MEDIUM
-impactDescription: fixes Hot Module Replacement breaking in Vue SSR applications
-type: efficiency
-tags: vite, hmr, ssr, vue, hot-reload, server-side-rendering
----
-
-# HMR Debugging for Vue SSR
-
-**Impact: MEDIUM** - fixes Hot Module Replacement breaking in Vue SSR applications
-
-Hot Module Replacement breaks when modifying Vue component `<script setup>` sections in SSR applications. Changes cause errors instead of smooth updates, requiring full page reloads.
-
-## Symptoms
-
-- HMR works for `<template>` changes but breaks for `<script setup>`
-- "Cannot read property of undefined" after saving
-- Full page reload required after script changes
-- HMR works in dev:client but not dev:ssr
-
-## Root Cause
-
-SSR mode has a different transformation pipeline. The Vue plugin's HMR boundary detection doesn't handle SSR modules the same way as client modules.
-
-## Fix
-
-**Step 1: Ensure correct SSR plugin configuration**
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-
-export default defineConfig({
-  plugins: [vue()],
-  ssr: {
-    // Don't externalize these for HMR to work
-    noExternal: ['vue', '@vue/runtime-core', '@vue/runtime-dom']
-  }
-})
-```
-
-**Step 2: Configure dev server for SSR HMR**
-```typescript
-// server.ts
-import { createServer } from 'vite'
-
-const vite = await createServer({
-  server: { middlewareMode: true },
-  appType: 'custom'
-})
-
-// Use vite.ssrLoadModule for server-side imports
-const { render } = await vite.ssrLoadModule('/src/entry-server.ts')
-
-// Handle HMR
-vite.watcher.on('change', async (file) => {
-  if (file.endsWith('.vue')) {
-    // Invalidate the module
-    const mod = vite.moduleGraph.getModuleById(file)
-    if (mod) {
-      vite.moduleGraph.invalidateModule(mod)
-    }
-  }
-})
-```
-
-**Step 3: Add HMR acceptance in entry-server**
-```typescript
-// entry-server.ts
-import { createApp } from './main'
-
-export async function render(url: string) {
-  const app = createApp()
-  // ... render logic
-}
-
-// Accept HMR updates
-if (import.meta.hot) {
-  import.meta.hot.accept()
-}
-```
-
-## Framework-Specific Solutions
-
-### Nuxt 3
-HMR should work out of the box. If not:
-```bash
-rm -rf .nuxt node_modules/.vite
-npm install
-npm run dev
-```
-
-### Vite SSR Template
-Ensure you're using the latest `@vitejs/plugin-vue`:
-```bash
-npm install @vitejs/plugin-vue@latest
-```
-
-## Debugging
-
-Enable verbose HMR logging:
-```typescript
-// vite.config.ts
-export default defineConfig({
-  server: {
-    hmr: {
-      overlay: true
-    }
-  },
-  logLevel: 'info'  // Shows HMR updates
-})
-```
-
-## Known Limitations
-
-- HMR for `<script>` (not `<script setup>`) may require full reload
-- SSR components with external dependencies may not hot-reload
-- State is not preserved for SSR components (expected behavior)
-
-## Reference
-
-- [vite-plugin-vue#525](https://github.com/vitejs/vite-plugin-vue/issues/525)
-- [Vite SSR Guide](https://vite.dev/guide/ssr.html)

----
-title: moduleResolution Bundler Migration Issues
-impact: HIGH
-impactDescription: fixes "Cannot find module" errors after @vue/tsconfig upgrade
-type: capability
-tags: moduleResolution, bundler, tsconfig, vue-tsconfig, node, esm
----
-
-# moduleResolution Bundler Migration Issues
-
-**Impact: HIGH** - fixes "Cannot find module" errors after @vue/tsconfig upgrade
-
-Recent versions of `@vue/tsconfig` changed `moduleResolution` from `"node"` to `"bundler"`. This can break existing projects with errors like "Cannot find module 'vue'" or issues with `resolveJsonModule`.
-
-## Symptoms
-
-- `Cannot find module 'vue'` or other packages
-- `Option '--resolveJsonModule' cannot be specified without 'node' module resolution`
-- Errors appear after updating `@vue/tsconfig`
-- Some third-party packages no longer resolve
-
-## Root Cause
-
-`moduleResolution: "bundler"` requires:
-1. TypeScript 5.0+
-2. Packages to have proper `exports` field in package.json
-3. Different resolution rules than Node.js classic resolution
-
-## Fix
-
-**Option 1: Ensure TypeScript 5.0+ everywhere**
-```bash
-npm install -D typescript@^5.0.0
-```
-
-In monorepos, ALL packages must use TypeScript 5.0+.
-
-**Option 2: Add compatibility workaround**
-```json
-{
-  "compilerOptions": {
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "resolvePackageJsonExports": false
-  }
-}
-```
-
-Setting `resolvePackageJsonExports: false` restores compatibility with packages that don't have proper exports.
-
-**Option 3: Revert to Node resolution**
-```json
-{
-  "compilerOptions": {
-    "moduleResolution": "node"
-  }
-}
-```
-
-## Which Packages Break?
-
-Packages break if they:
-- Lack `exports` field in package.json
-- Have incorrect `exports` configuration
-- Rely on Node.js-specific resolution behavior
-
-## Diagnosis
-
-```bash
-# Check which resolution is being used
-cat tsconfig.json | grep moduleResolution
-
-# Test if a specific module resolves
-npx tsc --traceResolution 2>&1 | grep "module-name"
-```
-
-## Reference
-
-- [vuejs/tsconfig#8](https://github.com/vuejs/tsconfig/issues/8)
-- [TypeScript moduleResolution docs](https://www.typescriptlang.org/tsconfig#moduleResolution)
-- [Vite discussion#14001](https://github.com/vitejs/vite/discussions/14001)

----
-title: Mocking Pinia Stores with Vitest
-impact: HIGH
-impactDescription: properly mocks Pinia stores in component tests
-type: efficiency
-tags: pinia, vitest, testing, mock, createTestingPinia, store
----
-
-# Mocking Pinia Stores with Vitest
-
-**Impact: HIGH** - properly mocks Pinia stores in component tests
-
-Developers struggle to properly mock Pinia stores: `createTestingPinia` requires explicit `createSpy` configuration, and "injection Symbol(pinia) not found" errors occur without proper setup.
-
-> **Important (@pinia/testing 1.0+):** The `createSpy` option is **REQUIRED**, not optional. Omitting it throws an error: "You must configure the `createSpy` option."
-
-## Symptoms
-
-- "injection Symbol(pinia) not found" error
-- "You must configure the `createSpy` option" error
-- Actions not properly mocked
-- Store state not reset between tests
-
-## Fix
-
-**Pattern 1: Basic setup with createTestingPinia**
-```typescript
-import { mount } from '@vue/test-utils'
-import { createTestingPinia } from '@pinia/testing'
-import { vi } from 'vitest'
-import MyComponent from './MyComponent.vue'
-import { useCounterStore } from '@/stores/counter'
-
-test('component uses store', async () => {
-  const wrapper = mount(MyComponent, {
-    global: {
-      plugins: [
-        createTestingPinia({
-          createSpy: vi.fn,  // REQUIRED in @pinia/testing 1.0+
-          initialState: {
-            counter: { count: 10 }  // Set initial state
-          }
-        })
-      ]
-    }
-  })
-
-  // Get the store instance AFTER mounting
-  const store = useCounterStore()
-
-  // Actions are automatically stubbed
-  await wrapper.find('button').trigger('click')
-  expect(store.increment).toHaveBeenCalled()
-})
-```
-
-**Pattern 2: Customize action behavior**
-```typescript
-test('component handles async action', async () => {
-  const wrapper = mount(MyComponent, {
-    global: {
-      plugins: [
-        createTestingPinia({
-          createSpy: vi.fn,
-          stubActions: false  // Don't stub, use real actions
-        })
-      ]
-    }
-  })
-
-  const store = useCounterStore()
-
-  // Override specific action
-  store.fetchData = vi.fn().mockResolvedValue({ items: [] })
-
-  await wrapper.find('.load-button').trigger('click')
-  expect(store.fetchData).toHaveBeenCalled()
-})
-```
-
-**Pattern 3: Testing store directly**
-```typescript
-import { setActivePinia, createPinia } from 'pinia'
-import { useCounterStore } from '@/stores/counter'
-
-describe('Counter Store', () => {
-  beforeEach(() => {
-    setActivePinia(createPinia())
-  })
-
-  test('increments count', () => {
-    const store = useCounterStore()
-    expect(store.count).toBe(0)
-
-    store.increment()
-    expect(store.count).toBe(1)
-  })
-})
-```
-
-## Setup Store with Vitest
-
-```typescript
-// stores/counter.ts - Setup store syntax
-export const useCounterStore = defineStore('counter', () => {
-  const count = ref(0)
-  const doubleCount = computed(() => count.value * 2)
-
-  function increment() {
-    count.value++
-  }
-
-  return { count, doubleCount, increment }
-})
-
-// Test file
-test('setup store works', async () => {
-  const pinia = createTestingPinia({
-    createSpy: vi.fn,
-    initialState: {
-      counter: { count: 5 }
-    }
-  })
-
-  const wrapper = mount(MyComponent, {
-    global: { plugins: [pinia] }
-  })
-
-  const store = useCounterStore()
-  expect(store.count).toBe(5)
-  expect(store.doubleCount).toBe(10)
-})
-```
-
-## Reset Between Tests
-
-```typescript
-describe('Store Tests', () => {
-  let pinia: Pinia
-
-  beforeEach(() => {
-    pinia = createTestingPinia({
-      createSpy: vi.fn
-    })
-  })
-
-  afterEach(() => {
-    vi.clearAllMocks()
-  })
-
-  test('test 1', () => { /* ... */ })
-  test('test 2', () => { /* ... */ })
-})
-```
-
-## Reference
-
-- [Pinia Testing Guide](https://pinia.vuejs.org/cookbook/testing.html)
-- [Pinia Discussion #2092](https://github.com/vuejs/pinia/discussions/2092)

----
-title: JSDoc Documentation for Script Setup Components
-impact: MEDIUM
-impactDescription: enables proper documentation for composition API components
-type: capability
-tags: jsdoc, script-setup, documentation, composition-api, component
----
-
-# JSDoc Documentation for Script Setup Components
-
-**Impact: MEDIUM** - enables proper documentation for composition API components
-
-`<script setup>` doesn't have an obvious place to attach JSDoc comments for the component itself. Use a dual-script pattern.
-
-## Problem
-
-**Incorrect:**
-```vue
-<script setup lang="ts">
-/**
- * This comment doesn't appear in IDE hover or docs
- * @component
- */
-import { ref } from 'vue'
-
-const count = ref(0)
-</script>
-```
-
-JSDoc comments inside `<script setup>` don't attach to the component export because there's no explicit export statement.
-
-## Solution
-
-Use both `<script>` and `<script setup>` blocks:
-
-**Correct:**
-```vue
-<script lang="ts">
-/**
- * A counter component that displays and increments a value.
- *
- * @example
- * ```vue
- * <Counter :initial="5" @update="handleUpdate" />
- * ```
- *
- * @component
- */
-export default {}
-</script>
-
-<script setup lang="ts">
-import { ref } from 'vue'
-
-const props = defineProps<{
-  /** Starting value for the counter */
-  initial?: number
-}>()
-
-const emit = defineEmits<{
-  /** Emitted when counter value changes */
-  update: [value: number]
-}>()
-
-const count = ref(props.initial ?? 0)
-</script>
-```
-
-## How It Works
-
-- The regular `<script>` block's default export is merged with `<script setup>`
-- JSDoc on `export default {}` attaches to the component
-- Props and emits JSDoc in `<script setup>` still work normally
-
-## What Gets Documented
-
-| Location | Shows In |
-|----------|----------|
-| `export default {}` JSDoc | Component import hover |
-| `defineProps` JSDoc | Prop hover in templates |
-| `defineEmits` JSDoc | Event handler hover |
-
-## Reference
-
-- [Vue Language Tools Discussion #5932](https://github.com/vuejs/language-tools/discussions/5932)

----
-title: Enable Strict CSS Modules Type Checking
-impact: MEDIUM
-impactDescription: catches typos in CSS module class names at compile time
-type: capability
-tags: strictCssModules, vueCompilerOptions, css-modules, style-module
----
-
-# Enable Strict CSS Modules Type Checking
-
-**Impact: MEDIUM** - catches typos in CSS module class names at compile time
-
-When using CSS modules with `<style module>`, Vue doesn't validate class names by default. Enable `strictCssModules` to catch typos and undefined classes.
-
-## Problem
-
-CSS module class name errors go undetected:
-
-```vue
-<script setup lang="ts">
-// No error for typo in class name
-</script>
-
-<template>
-  <div :class="$style.buttn">Click me</div>
-</template>
-
-<style module>
-.button {
-  background: blue;
-}
-</style>
-```
-
-The typo `buttn` instead of `button` silently fails at runtime.
-
-## Solution
-
-Enable `strictCssModules` in your tsconfig:
-
-```json
-// tsconfig.json or tsconfig.app.json
-{
-  "vueCompilerOptions": {
-    "strictCssModules": true
-  }
-}
-```
-
-Now `$style.buttn` will show a type error because `buttn` doesn't exist in the CSS module.
-
-## What Gets Checked
-
-| Access | With strictCssModules |
-|--------|----------------------|
-| `$style.validClass` | OK |
-| `$style.typo` | Error: Property 'typo' does not exist |
-| `$style['dynamic']` | OK (dynamic access not checked) |
-
-## Limitations
-
-- Only checks static property access (`$style.className`)
-- Dynamic access (`$style[variable]`) is not validated
-- Only works with `<style module>`, not external CSS files
-
-## Reference
-
-- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)

----
-title: unplugin-vue-components and unplugin-auto-import Type Conflicts
-impact: HIGH
-impactDescription: fixes component types resolving as any when using both plugins
-type: capability
-tags: unplugin-vue-components, unplugin-auto-import, types, any, dts
----
-
-# unplugin-vue-components and unplugin-auto-import Type Conflicts
-
-**Impact: HIGH** - fixes component types resolving as any when using both plugins
-
-Installing both `unplugin-vue-components` and `unplugin-auto-import` can cause component types to resolve as `any`. The generated `.d.ts` files conflict with each other.
-
-## Symptoms
-
-- Components typed as `any` instead of proper component types
-- No autocomplete for component props
-- No type errors for invalid props
-- Types work when using only one plugin but break with both
-
-## Root Cause
-
-Both plugins generate declaration files (`components.d.ts` and `auto-imports.d.ts`) that can have conflicting declarations. TypeScript declaration merging fails silently.
-
-## Fix
-
-**Step 1: Ensure both .d.ts files are in tsconfig include**
-```json
-{
-  "include": [
-    "src/**/*.ts",
-    "src/**/*.vue",
-    "components.d.ts",
-    "auto-imports.d.ts"
-  ]
-}
-```
-
-**Step 2: Set explicit, different dts paths**
-```typescript
-// vite.config.ts
-import Components from 'unplugin-vue-components/vite'
-import AutoImport from 'unplugin-auto-import/vite'
-
-export default defineConfig({
-  plugins: [
-    Components({
-      dts: 'src/types/components.d.ts'  // Explicit unique path
-    }),
-    AutoImport({
-      dts: 'src/types/auto-imports.d.ts'  // Explicit unique path
-    })
-  ]
-})
-```
-
-**Step 3: Regenerate type files**
-```bash
-# Delete existing .d.ts files
-rm components.d.ts auto-imports.d.ts
-
-# Restart dev server to regenerate
-npm run dev
-```
-
-**Step 4: Verify no duplicate declarations**
-
-Check that the same component isn't declared in both files.
-
-## Plugin Order Matters
-
-Configure Components plugin AFTER AutoImport:
-```typescript
-plugins: [
-  AutoImport({ /* ... */ }),
-  Components({ /* ... */ })  // Must come after AutoImport
-]
-```
-
-## Common Mistake: Duplicate Imports
-
-Don't configure the same import in both plugins:
-```typescript
-// Wrong - Vue imported in both
-AutoImport({
-  imports: ['vue']
-})
-Components({
-  resolvers: [/* includes Vue components */]
-})
-```
-
-## Reference
-
-- [unplugin-vue-components#640](https://github.com/unplugin/unplugin-vue-components/issues/640)
-- [unplugin-auto-import docs](https://github.com/unplugin/unplugin-auto-import)

----
-title: Volar 3.0 Breaking Changes
-impact: HIGH
-impactDescription: fixes editor integration after Volar/vue-language-server upgrade
-type: capability
-tags: volar, vue-language-server, neovim, vscode, ide, ts_ls, vtsls
----
-
-# Volar 3.0 Breaking Changes
-
-**Impact: HIGH** - fixes editor integration after Volar/vue-language-server upgrade
-
-Volar 3.0 (vue-language-server 3.x) introduced breaking changes to the language server protocol. Editors configured for Volar 2.x will break with errors like "vue_ls doesn't work with ts_ls.. it expects vtsls".
-
-## Symptoms
-
-- `vue_ls doesn't work with ts_ls`
-- TypeScript features stop working in Vue files
-- No autocomplete, type hints, or error highlighting
-- Editor shows "Language server initialization failed"
-
-## Fix by Editor
-
-### VSCode
-
-Update the "Vue - Official" extension to latest version. It manages the language server automatically.
-
-### NeoVim (nvim-lspconfig)
-
-**Option 1: Use vtsls instead of ts_ls**
-```lua
--- Replace ts_ls/tsserver with vtsls
-require('lspconfig').vtsls.setup({})
-require('lspconfig').volar.setup({})
-```
-
-**Option 2: Downgrade vue-language-server**
-```bash
-npm install -g @vue/language-server@2.1.10
-```
-
-### JetBrains IDEs
-
-Update to latest Vue plugin. If issues persist, disable and re-enable the Vue plugin.
-
-## What Changed in 3.0
-
-| Feature | Volar 2.x | Volar 3.0 |
-|---------|-----------|-----------|
-| Package name | volar | vue_ls |
-| TypeScript integration | ts_ls/tsserver | vtsls required |
-| Hybrid mode | Optional | Default |
-
-## Workaround: Stay on 2.x
-
-If upgrading is not possible:
-```bash
-npm install -g @vue/language-server@^2.0.0
-```
-
-Pin in your project's package.json to prevent accidental upgrades.
-
-## Reference
-
-- [vuejs/language-tools#5598](https://github.com/vuejs/language-tools/issues/5598)
-- [NeoVim Vue Setup Guide](https://dev.to/danwalsh/solved-vue-3-typescript-inlay-hint-support-in-neovim-53ej)

----
-title: Vue Template Directive Comments
-impact: HIGH
-impactDescription: enables fine-grained control over template type checking
-type: capability
-tags: vue-directive, vue-ignore, vue-expect-error, vue-skip, template, type-checking
----
-
-# Vue Template Directive Comments
-
-**Impact: HIGH** - enables fine-grained control over template type checking
-
-Vue Language Tools supports special directive comments to control type checking behavior in templates.
-
-## Available Directives
-
-### @vue-ignore
-
-Suppress type errors for the next line:
-
-```vue
-<template>
-  <!-- @vue-ignore -->
-  <Component :prop="valueWithTypeError" />
-</template>
-```
-
-### @vue-expect-error
-
-Assert that the next line should have a type error (useful for testing):
-
-```vue
-<template>
-  <!-- @vue-expect-error -->
-  <Component :invalid-prop="value" />
-</template>
-```
-
-### @vue-skip
-
-Skip type checking for an entire block:
-
-```vue
-<template>
-  <!-- @vue-skip -->
-  <div>
-    <!-- Everything in here is not type-checked -->
-    <LegacyComponent :any="props" :go="here" />
-  </div>
-</template>
-```
-
-### @vue-generic
-
-Declare template-level generic types:
-
-```vue
-<template>
-  <!-- @vue-generic {T extends string} -->
-  <GenericList :items="items as T[]" />
-</template>
-```
-
-## Use Cases
-
-- Migrating legacy components with incomplete types
-- Working with third-party components that have incorrect type definitions
-- Temporarily suppressing errors during refactoring
-- Testing that certain patterns produce expected type errors
-
-## Reference
-
-- [Vue Language Tools Wiki - Directive Comments](https://github.com/vuejs/language-tools/wiki/Directive-Comments)

----
-title: Vue Router useRoute Params Union Type Narrowing
-impact: MEDIUM
-impactDescription: fixes "Property does not exist" errors with typed route params
-type: capability
-tags: vue-router, useRoute, unplugin-vue-router, typed-routes, params
----
-
-# Vue Router useRoute Params Union Type Narrowing
-
-**Impact: MEDIUM** - fixes "Property does not exist" errors with typed route params
-
-With `unplugin-vue-router` typed routes, `route.params` becomes a union of ALL page param types. TypeScript cannot narrow `Record<never, never> | { id: string }` properly, causing "Property 'id' does not exist" errors even on the correct page.
-
-## Symptoms
-
-- "Property 'id' does not exist on type 'RouteParams'"
-- `route.params.id` shows as `string | undefined` everywhere
-- Union type of all route params instead of specific route
-- Type narrowing with `if (route.name === 'users-id')` doesn't work
-
-## Root Cause
-
-`unplugin-vue-router` generates a union type of all possible route params. TypeScript's control flow analysis can't narrow this union based on route name checks.
-
-## Fix
-
-**Option 1: Pass route name to useRoute (recommended)**
-```typescript
-// pages/users/[id].vue
-import { useRoute } from 'vue-router/auto'
-
-// Specify the route path for proper typing
-const route = useRoute('/users/[id]')
-
-// Now properly typed as { id: string }
-console.log(route.params.id)  // string, not string | undefined
-```
-
-**Option 2: Type assertion with specific route**
-```typescript
-import { useRoute } from 'vue-router'
-import type { RouteLocationNormalized } from 'vue-router/auto-routes'
-
-const route = useRoute() as RouteLocationNormalized<'/users/[id]'>
-route.params.id  // Properly typed
-```
-
-**Option 3: Define route-specific param type**
-```typescript
-// In your page component
-interface UserRouteParams {
-  id: string
-}
-
-const route = useRoute()
-const { id } = route.params as UserRouteParams
-```
-
-## Required tsconfig Setting
-
-Ensure `moduleResolution: "bundler"` for unplugin-vue-router:
-```json
-{
-  "compilerOptions": {
-    "moduleResolution": "bundler"
-  }
-}
-```
-
-## Caveat: Route Name Format
-
-The route name matches the file path pattern:
-- `pages/users/[id].vue` → `/users/[id]`
-- `pages/posts/[slug]/comments.vue` → `/posts/[slug]/comments`
-
-## Reference
-
-- [unplugin-vue-router#337](https://github.com/posva/unplugin-vue-router/issues/337)
-- [unplugin-vue-router#176](https://github.com/posva/unplugin-vue-router/discussions/176)
-- [unplugin-vue-router TypeScript docs](https://uvr.esm.is/guide/typescript.html)

----
-title: Enable Strict Template Checking
-impact: HIGH
-impactDescription: catches undefined components and props at compile time
-type: capability
-tags: vue-tsc, typescript, type-checking, templates, vueCompilerOptions
----
-
-# Enable Strict Template Checking
-
-**Impact: HIGH** - catches undefined components and props at compile time
-
-By default, vue-tsc does not report errors for undefined components in templates. Enable `strictTemplates` to catch these issues during type checking.
-
-## Which tsconfig?
-
-Add `vueCompilerOptions` to the tsconfig that includes Vue source files. In projects with multiple tsconfigs (like those created with `create-vue`), this is typically `tsconfig.app.json`, not the root `tsconfig.json` or `tsconfig.node.json`.
-
-**Incorrect (missing strict checking):**
-
-```json
-{
-  "compilerOptions": {
-    "strict": true
-  }
-  // vueCompilerOptions not configured - undefined components won't error
-}
-```
-
-**Correct (strict template checking enabled):**
-
-```json
-{
-  "compilerOptions": {
-    "strict": true
-  },
-  "vueCompilerOptions": {
-    "strictTemplates": true
-  }
-}
-```
-
-## Available Options
-
-| Option | Default | Effect |
-|--------|---------|--------|
-| `strictTemplates` | `false` | Enables all checkUnknown* options below |
-| `checkUnknownComponents` | `false` | Error on undefined/unregistered components |
-| `checkUnknownProps` | `false` | Error on props not declared in component definition |
-| `checkUnknownEvents` | `false` | Error on events not declared via `defineEmits` |
-| `checkUnknownDirectives` | `false` | Error on unregistered custom directives |
-
-## Granular Control
-
-If `strictTemplates` is too strict, enable individual checks:
-
-```json
-{
-  "vueCompilerOptions": {
-    "checkUnknownComponents": true,
-    "checkUnknownProps": false
-  }
-}
-```
-
-## Reference
-
-- [Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)
-- [Vite Vue+TS Template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-vue-ts)

----
-title: withDefaults Incorrect Default with Union Types
-impact: MEDIUM
-impactDescription: fixes incorrect default value behavior with union type props
-type: capability
-tags: withDefaults, defineProps, union-types, defaults, vue-3.5
----
-
-# withDefaults Incorrect Default with Union Types
-
-**Impact: MEDIUM** - fixes spurious "Missing required prop" warning with union type props
-
-Using `withDefaults` with union types like `false | string` may produce a Vue runtime warning "Missing required prop" even when a default is provided. The runtime value IS applied correctly, but the warning can be confusing.
-
-## Symptoms
-
-- Vue warns "Missing required prop" despite default being set
-- Warning appears only with union types like `false | string`
-- TypeScript types are correct
-- Runtime value IS correct (the default is applied)
-
-## Problematic Pattern
-
-```typescript
-// This produces a spurious warning (but works at runtime)
-interface Props {
-  value: false | string  // Union type
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  value: 'default'  // Runtime value IS correct, but Vue warns about missing prop
-})
-```
-
-## Fix
-
-**Option 1: Use Reactive Props Destructure (Vue 3.5+)**
-```vue
-<script setup lang="ts">
-interface Props {
-  value: false | string
-}
-
-// Preferred in Vue 3.5+
-const { value = 'default' } = defineProps<Props>()
-</script>
-```
-
-**Option 2: Use runtime declaration**
-```vue
-<script setup lang="ts">
-const props = defineProps({
-  value: {
-    type: [Boolean, String] as PropType<false | string>,
-    default: 'default'
-  }
-})
-</script>
-```
-
-**Option 3: Split into separate props**
-```typescript
-interface Props {
-  enabled: boolean
-  customValue?: string
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  enabled: false,
-  customValue: 'default'
-})
-```
-
-## Why Reactive Props Destructure Works
-
-Vue 3.5's Reactive Props Destructure handles default values at the destructuring level, bypassing the type inference issues with `withDefaults`.
-
-```typescript
-// The default is applied during destructuring, not type inference
-const { prop = 'default' } = defineProps<{ prop?: string }>()
-```
-
-## Enable Reactive Props Destructure
-
-This is enabled by default in Vue 3.5+. For older versions:
-```javascript
-// vite.config.js
-export default {
-  plugins: [
-    vue({
-      script: {
-        propsDestructure: true
-      }
-    })
-  ]
-}
-```
-
-## Reference
-
-- [vuejs/core#12897](https://github.com/vuejs/core/issues/12897)
-- [Reactive Props Destructure RFC](https://github.com/vuejs/rfcs/discussions/502)

-# 架构实现与工程配置
-
-## 入口与初始化
-
-- 应用入口：[/src/main.js](file:///Users/huyirui/program/itomix/git/mlaj/src/main.js)
-  - 创建 App、注册全局 Icon 组件、挂载路由
-  - 全局注入 axios 到 app.config.globalProperties.$http
-- 根组件：[/src/App.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/App.vue)
-  - 初始化全局认证与购物车：provideAuth / provideCart
-  - 生产环境 + 微信环境：初始化微信 JSSDK（配置签名 URL）
-  - 生产环境：版本更新探测（弹窗提示刷新）
-
-## 路由与权限
-
-- 路由入口：[/src/router/index.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/index.js)
-  - Hash 路由：createWebHashHistory(import.meta.env.VITE_BASE || '/')
-  - beforeEach：统一登录页回跳处理，并在必要时探测“是否已登录”
-- 鉴权策略：[/src/router/guards.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/guards.js)
-  - 白名单 + meta.requiresAuth 双策略判断
-  - 未登录时重定向 /login 并带 redirect
-- 微信授权策略：[/src/router/guards.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/guards.js)
-  - 不在路由守卫自动触发授权，避免循环
-  - 仅在用户触发（如点击微信图标/购买流程探测）时调用 startWxAuth
-
-## 请求与登录态注入
-
-- Axios 封装：[/src/utils/axios.js](file:///Users/huyirui/program/itomix/git/mlaj/src/utils/axios.js)
-  - 请求拦截：动态读取本地 user_info 并注入 User-Id / User-Token
-  - 响应拦截：code=401 时，仅当当前路由确实需要登录才跳转登录（公开页面不强制跳转）
-- 登录态管理：[/src/contexts/auth.js](file:///Users/huyirui/program/itomix/git/mlaj/src/contexts/auth.js)
-  - provide/inject 维护 currentUser/loading/login/logout
-  - localStorage 持久化 currentUser
-  - 初始化流程中会探测授权/登录态并拉取用户信息
-
-## 购物车与结算
-
-- 购物车上下文：[/src/contexts/cart.js](file:///Users/huyirui/program/itomix/git/mlaj/src/contexts/cart.js)
-  - 单品/多品两种模式（App.vue 默认使用单品模式）
-  - localStorage 带时间戳的过期策略（默认一天过期）
-  - handleCheckout 负责构建订单数据并提交订单
-
-## 上传与预览
-
-- 上传工具：[/src/utils/upload.js](file:///Users/huyirui/program/itomix/git/mlaj/src/utils/upload.js)、[/src/utils/qiniuFileHash.js](file:///Users/huyirui/program/itomix/git/mlaj/src/utils/qiniuFileHash.js)
-  - 前端计算文件 Hash，支持“秒传检测 + 直传对象存储”
-- 关键业务复用：[/src/composables/useCheckin.js](file:///Users/huyirui/program/itomix/git/mlaj/src/composables/useCheckin.js)
-  - 打卡/作业提交流程：校验、上传、提交、编辑回填等
-- 预览组件：[/src/components/media](file:///Users/huyirui/program/itomix/git/mlaj/src/components/media)
-  - 视频/音频播放器、PDF/Office 预览等
-
-## Vite 配置与环境变量
-
-- Vite 配置：[/vite.config.js](file:///Users/huyirui/program/itomix/git/mlaj/vite.config.js)
-  - 自动按需引入 Vant 组件（unplugin-auto-import / unplugin-vue-components）
-  - 别名：@ / @components / @utils / @api 等
-  - 本地代理：createProxy(viteEnv.VITE_PROXY_PREFIX, viteEnv.VITE_PROXY_TARGET)
-- 环境变量示例：[.env](file:///Users/huyirui/program/itomix/git/mlaj/.env)
-  - VITE_PORT：开发端口
-  - VITE_PROXY_TARGET / VITE_PROXY_PREFIX：接口代理目标与前缀
-  - VITE_OUTDIR：构建输出目录
-  - VITE_CONSOLE：调试开关
-
-## 目录结构（详细）
-
-```
-mlaj/
-├── build/                 # Vite 代理封装
-├── docs/                  # 项目文档（本目录）
-├── public/                # 静态资源
-├── src/
-│   ├── api/               # 按业务域拆分的接口封装（auth/course/checkin/teacher/...）
-│   ├── assets/            # 图片等资源
-│   ├── common/            # 常量
-│   ├── components/        # 组件（按业务域归类）
-│   ├── composables/       # 组合式函数（逻辑复用，含单测）
-│   ├── contexts/          # 全局状态（provide/inject：auth/cart）
-│   ├── router/            # 路由定义与守卫
-│   ├── utils/             # 工具层（axios、上传、鉴权存储、版本更新等）
-│   └── views/             # 页面（按业务域归类）
-├── tailwind.config.js     # Tailwind 配置
-└── vite.config.js         # Vite 配置
-```

-# 功能更新记录（Recent Changes）
-
-说明：该章节从 README 迁移到本文件，避免 README 过长。后续新增变更建议追加在文件顶部。
-
-## 2026-01-25
-
-- 新增「暂存用户打卡信息」开发规划：[/docs/plan/暂存用户打卡信息.md](file:///Users/huyirui/program/itomix/git/mlaj/docs/plan/%E6%9A%82%E5%AD%98%E7%94%A8%E6%88%B7%E6%89%93%E5%8D%A1%E4%BF%A1%E6%81%AF.md)
-- 完成「暂存用户打卡信息」功能开发
-  - 核心逻辑：[/src/composables/useCheckinDraft.js](file:///Users/huyirui/program/itomix/git/mlaj/src/composables/useCheckinDraft.js)
-  - 页面集成：[/src/views/checkin/CheckinDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/checkin/CheckinDetailPage.vue)
-  - 支持自动保存、过期清理、恢复提示
-- 修复打卡详情页 `countValue` 初始化顺序导致的 ReferenceError 报错
-- 修复附件上传成功后未保存 URL 导致草稿恢复后无法预览的问题
-- 优化文件 URL 获取逻辑：移除硬编码默认域名，优先使用接口返回的 URL 或 src，仅在有域名信息时拼接 URL
-
-## 打卡详情页重构（/checkin/detail）
-
-- 统一了文本、媒体上传和计数打卡的入口
-- 实现了基于 composables 的通用提交流程：[/src/composables/useCheckin.js](file:///Users/huyirui/program/itomix/git/mlaj/src/composables/useCheckin.js)
-- 页面入口：[/src/views/checkin/CheckinDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/checkin/CheckinDetailPage.vue)
-- 优化了附件预览与编辑回填逻辑（音频/视频/图片预览能力）
-
-## 教师端功能完善（/teacher）
-
-- 新增作业管理页面：/teacher/tasks（列表展示：名称、开始/截止时间）
-- 新增作业主页：/teacher/tasks/:id（统计 + 日历视图）
-- 新增学员作业记录页：/teacher/student-record（作业帖子 + 点赞/点评）
-
-## 基础体验优化
-
-- 登录逻辑调整：仅在登录页点击微信图标时触发授权（避免路由守卫自动授权导致的循环）
-  - 关键文件：[/src/router/guards.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/guards.js)、[/src/router/index.js](file:///Users/huyirui/program/itomix/git/mlaj/src/router/index.js)、[/src/views/auth/LoginPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/auth/LoginPage.vue)
-- 搜索栏优化：提升 iOS 软键盘“搜索”键触发稳定性
-- 课程详情页：增加动态 Open Graph 标签，优化分享体验
-
-## 课程详情页动态 Open Graph 元标签
-
-- 行为：进入课程详情页时，在 head 中插入 og:title / og:description / og:image / og:url；离开页面时移除
-- CDN 规则：图片域名为 cdn.ipadbiz.cn 时，追加 ?imageMogr2/thumbnail/200x/strip/quality/70
-- 位置：[/src/views/courses/CourseDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/courses/CourseDetailPage.vue)
-
-## 购买流程环境校验与微信授权探测
-
-- 行为：仅对非免费课程在详情页点击“购买”时进行校验；生产环境必须为微信内置浏览器
-- 微信环境内：若未完成微信授权（openid_has=false），会自动发起一次微信授权并中止本次购买，授权后再次点击进入结算
-- 位置：[/src/views/courses/CourseDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/courses/CourseDetailPage.vue)
-
-## 401 拦截策略优化（公开页面不再跳登录）
-
-- 行为：接口返回 code=401 时，仅当当前路由确实需要登录时才重定向登录
-- 位置：[/src/utils/axios.js](file:///Users/huyirui/program/itomix/git/mlaj/src/utils/axios.js)
-
-## 搜索栏回车搜索兼容性提升
-
-- 行为：输入框类型改为 search，并可选开启 form submit 机制，同时保留 keyup.enter
-- 位置：[/src/components/common/SearchBar.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/components/common/SearchBar.vue)
-
-## 分享海报弹窗（可复用）
-
-- 入口：课程详情页底部操作栏“分享”按钮
-- 组件：[/src/components/poster/SharePoster.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/components/poster/SharePoster.vue)
-- 能力：弹窗打开时通过 Canvas 合成海报（封面、二维码、文案），生成 dataURL 展示，用户长按保存
-
-## 打卡弹窗与列表组件（可复用）
-
-- 打卡弹窗：[/src/components/checkin/CheckInDialog.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/components/checkin/CheckInDialog.vue)
-- 打卡列表：[/src/components/checkin/CheckInList.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/components/checkin/CheckInList.vue)

-# /src/components 组件目录索引
-
-## 目录划分
-
-| 目录 | 代表组件 | 说明 |
-| --- | --- | --- |
-| activity/ | ActivityCard.vue、ActivityApplyHistoryPopup.vue | 活动卡片、报名/历史相关弹窗 |
-| calendar/ | CollapsibleCalendar.vue、TaskCalendar.vue | 日历与任务日历组件 |
-| checkin/ | CheckInDialog.vue、CheckInList.vue、CheckinCard.vue、UploadVideoPopup.vue | 打卡/作业相关组件（弹窗、列表、卡片、上传） |
-| common/ | ConfirmDialog.vue、GradientHeader.vue、SearchBar.vue、UserAgreement.vue | 通用基础组件（确认、头部、搜索、协议） |
-| count/ | AddTargetDialog.vue、CheckinTargetList.vue、postCountModel.vue | 计数型打卡相关组件 |
-| courses/ | CourseCard.vue、CourseList.vue、LiveStreamCard.vue、ReviewPopup.vue | 课程展示与列表、直播卡片、评价弹窗等 |
-| effects/ | FrostedGlass.vue、StarryBackground.vue | 视觉效果组件 |
-| homePage/ | FeaturedCoursesSection.vue、LatestActivitiesSection.vue | 首页区块组件（精选/活动/推荐等） |
-| infoEntry/ | formPage.vue | 信息录入相关组件 |
-| layout/ | AppLayout.vue、BottomNav.vue | 页面布局与底部导航 |
-| media/ | AudioPlayer.vue、VideoPlayer.vue、PdfPreview.vue、OfficeViewer.vue | 音视频播放器与文档预览 |
-| payment/ | WechatPayment.vue | 微信支付相关组件 |
-| poster/ | RecallPoster.vue、SharePoster.vue | 海报生成与分享相关组件 |
-| studyDetail/ | StudyCatalogPopup.vue、StudyCommentsSection.vue、StudyMaterialsPopup.vue | 学习详情页的弹窗与评论区 |
-| teacher/ | TaskFilter.vue、TaskCascaderFilter.vue | 教师端筛选与任务相关组件 |
-
-## 备注
-
-- 布局目录已归一：统一使用 [/src/components/layout](file:///Users/huyirui/program/itomix/git/mlaj/src/components/layout)，已移除 /src/layouts

-用户反馈:

-# 暂存用户打卡信息
-
-## 背景
-
-用户在“提交作业/打卡”页面输入了较长文字并上传了媒体，但在未点击提交时被中断（误触返回、微信进程被系统回收、来电/切后台等），再次进入页面内容丢失，导致体验断裂。
-
-本规划目标是在不改动后端接口的前提下，在前端提供“草稿暂存（文本 + 已上传媒体信息）”能力，支持一周内自动过期清理，并在用户再次进入时提示恢复或删除。
-
-涉及页面与核心逻辑参考：
-
-- 打卡提交页：[CheckinDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/checkin/CheckinDetailPage.vue)
-- 打卡核心逻辑：[useCheckin.js](file:///Users/huyirui/program/itomix/git/mlaj/src/composables/useCheckin.js)
-- 环境变量约定：[.env](file:///Users/huyirui/program/itomix/git/mlaj/.env)
-
-## 需求拆解（逐条对齐）
-
-1. 缓存最多保存一周：写入时记录 saved_at，读写时执行过期清理（>7天删除）。
-2. 用户提交后清空缓存：提交成功（code===1）后删除对应草稿。
-3. 进入页面若存在未完成信息：弹框提示“继续/删除”，继续则回填，删除则清空。
-4. 功能开关放到 .env：新增 VITE_CHECKIN_DRAFT_CACHE（0/1），默认建议 1（也可先默认 0，灰度开启）。
-
-## 范围与不做项（第一版）
-
-- 覆盖：文字内容、已上传成功的媒体（含 url/meta_id/file_type/name）。
-- 不覆盖：未上传完成的 File/Blob（localStorage 无法可靠持久化；要支持需 IndexedDB 存 Blob，复杂度与风险较高）。
-- 编辑模式（route.query.status===edit）：第一版建议默认不启用草稿恢复，避免与“编辑回显（来自后端）”冲突；若要覆盖编辑场景，采用独立 key（见“扩展”）。
-
-## 关键设计
-
-### 1) 存储介质
-
-- 使用 localStorage：实现成本低，满足“一周”与“断网/切后台后仍可恢复”。
-- 数据量控制：只存“已上传成功”的附件元数据；不存 File 本体。
-
-### 2) 草稿 Key 设计（避免串号）
-
-建议 key 包含用户与作业上下文，确保不同用户/不同作业互不影响：
-
-- 前缀：CHECKIN_DRAFT_V1
-- 维度：user_id、task_id、date、task_type、status
-
-示例：
-
-- CHECKIN_DRAFT_V1:{user_id}:{task_id}:{date}:{task_type}:{status}
-
-其中：
-
-- user_id：来自 currentUser（contexts/auth.js 本地持久化）
-- task_id/date/task_type/status：来自路由 query（CheckinDetailPage 已使用 route.query.task_id/date/task_type/status）
-
-### 3) 数据结构（建议）
-
-```json
-{
-  "version": 1,
-  "saved_at": 1730000000000,
-  "expires_at": 1730000000000,
-  "context": {
-    "user_id": "123",
-    "task_id": "456",
-    "date": "2026-01-25",
-    "task_type": "upload",
-    "status": "create"
-  },
-  "payload": {
-    "message": "...",
-    "active_type": "image",
-    "subtask_id": "789",
-    "file_list": [
-      {
-        "meta_id": "xxx",
-        "url": "https://...",
-        "name": "a.jpg",
-        "file_type": "image"
-      }
-    ],
-    "count": {
-      "gratitude_count": 1,
-      "gratitude_form_list": []
-    }
-  }
-}
-```
-
-说明：
-
-- file_list：仅保存 useCheckin.afterRead 上传成功后写入的字段（item.status===done 且 meta_id 存在）。
-- count：来源于 CheckinDetailPage 的 selectedTargets/countValue（第一版可以先不存，或存但不影响非 count 类型）。
-
-### 4) 触发保存的时机（自动暂存）
-
-- 文本变化：watch(message) debounce 500ms 保存。
-- 附件变化：watch(fileList) 深度监听 debounce 500ms 保存（仅保存 done 项）。
-- 作业选择变化：watch(selectedTaskValue) debounce 200ms 保存。
-- 页面离开兜底：beforeRouteLeave 或 window.pagehide/visibilitychange 时强制保存一次（避免最后一次变更没落盘）。
-
-落盘时机要遵循开关：VITE_CHECKIN_DRAFT_CACHE === '1' 才启用。
-
-### 5) 弹框提示与回填流程
-
-进入 [CheckinDetailPage.vue](file:///Users/huyirui/program/itomix/git/mlaj/src/views/checkin/CheckinDetailPage.vue)（且非 edit 模式）时：
-
-1. 读取 key 对应草稿；若不存在或已过期，直接进入正常流程。
-2. 若存在草稿且 payload 有实际内容（message 有非空或 file_list 非空）：弹框提示。
-3. 用户选择：
-   - 继续：将草稿回填到 message / activeType / fileList / selectedTaskValue（以及 count 数据如启用），并立刻再保存一次（避免回填后又丢）。
-   - 删除：删除草稿并保持空表单。
-
-弹框建议用 showConfirmDialog（Vant 4），取消分支需要 catch，避免控制台出现 Uncaught (in promise) cancel（Vant 文档：showConfirmDialog.then/catch）[3](https://develop365.gitlab.io/vant/zh-CN/dialog/)。
-
-### 6) 清理策略（“定期清除一周前”）
-
-采用“惰性清理 + 低频全量清理”组合：
-
-- 惰性清理：每次读/写草稿时，如果 expires_at < now 则删除。
-- 低频全量：进入打卡页时，扫描 localStorage 中以 CHECKIN_DRAFT_V1: 开头的 key，删除所有过期项。
-
-说明：localStorage 没有内建 TTL，必须业务侧维护 expires_at。
-
-### 7) 提交成功后清空
-
-清空动作必须绑定到“真正提交成功”之后：
-
-- 建议在 useCheckin.onSubmit 中，当 add/edit API 返回 code===1 且后续逻辑准备 router.back 前，删除对应 key。
-
-这样可覆盖“不同入口页复用 onSubmit”以及“提交后立即返回上一页”的场景。
-
-## 开发步骤（可落地的实现顺序）
-
-### 第 0 步：验证手段先行（TDD）
-
-新增 Vitest 用例，先定义以下可验证点：
-
-- 写入后能读取同一 key 的草稿；过期后读取返回空且自动删除。
-- 仅保存 status===done 且含 meta_id 的附件。
-- 清理函数能删除所有过期 key，不误删其他业务 localStorage。
-- 提交成功时会调用清理（可通过 mock API 返回 code===1 验证）。
-
-### 第 1 步：抽离草稿存储模块
-
-位置建议：src/utils/checkinDraftCache.js（纯函数、无 UI 依赖）。
-
-对外 API（示例）：
-
-- is_enabled(): boolean（读取 env + 可选 query override）
-- build_key(context): string
-- save_draft(key, draft)
-- read_draft(key): draft|null（含 TTL 处理）
-- clear_draft(key)
-- cleanup_expired(prefix)
-
-### 第 2 步：在 CheckinDetailPage 接入“检测 + 弹框 + 回填”
-
-- onMounted：初始化后读取草稿并弹框。
-- 回填时机：建议在任务详情/子任务列表加载完成后再回填 selectedTaskValue，避免 option 未加载导致显示异常。
-
-### 第 3 步：在 CheckinDetailPage 接入“自动保存”
-
-- 对 message/fileList/selectedTaskValue/countValue/selectedTargets 建立 watch + debounce。
-- 页面离开事件兜底（pagehide/visibilitychange）。
-
-### 第 4 步：在 useCheckin.onSubmit 接入“成功清理”
-
-- onSubmit 成功分支清除草稿。
-- 失败分支不清除，保留草稿以便重试。
-
-## 边界条件与遗漏点梳理（建议补齐）
-
-1. 多用户切换：key 必须含 user_id，否则会串草稿。
-2. 多任务并存：key 必须含 task_id/date/task_type，否则会在不同作业之间误恢复。
-3. 附件未上传完成：
-   - 仅保存已上传成功的项；如果用户退出时仍有 uploading 项，恢复后无法找回该 File。
-   - 可在保存时统计未保存数量，并在恢复弹框里追加提示“有 X 个附件上传未完成未被暂存”。
-4. 关闭开关后的行为：
-   - 关闭后不再读/写；建议仍执行一次 cleanup_expired，避免历史堆积。
-5. 版本升级/数据结构变更：draft.version 不匹配时丢弃并清除，避免解析异常。
-6. localStorage 配额：图片多但只存 url/meta_id 一般不会超；仍需 try/catch JSON 与 setItem 异常。
-7. 编辑模式：
-   - 要支持“编辑中断恢复”，建议 key 加 post_id 维度，并在 initEditData 回显后再弹框询问是否覆盖当前表单。
-
-## 环境变量（规划）
-
-在 [.env](file:///Users/huyirui/program/itomix/git/mlaj/.env) 增加：
-
-- VITE_CHECKIN_DRAFT_CACHE = 1
-
-约定：
-
-- '1' 开启，'0' 关闭
-- 可选增加 URL 覆盖用于灰度测试：?enable_draft=1 / ?enable_draft=0（模式同 VITE_CHECKIN_MULTI_ATTACHMENT）