feat(admin-frontend): 完成订阅与系统管理真实工作台

补齐订单、优惠券、主题、插件、公告与支付管理页面，接入对应后台接口、路由入口与工具层类型定义。同时修复套餐页开关初始化误写问题，避免浏览即触发写操作。在订阅协议侧为 Stash 导出增加 AnyTLS 版本守卫，未知版本或低于 3.3.0 时不再导出该协议，并补充回归测试与知识记录。
2026-04-24 16:52:41 +08:00
parent 16203b14f6
commit f7cef30b9c
89 changed files with 11122 additions and 92 deletions
@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 4,
+  "failed": 0,
+  "pending": 0,
+  "total": 4,
+  "done": 4,
+  "percent": 100,
+  "current": "套餐管理页加载误触新购关闭的回归已修复并完成构建验证",
+  "updated_at": "2026-04-24 15:51:00"
+}
@@ -0,0 +1,69 @@
+# 变更提案: admin-frontend-plan-toggle-regression
+
+## 元信息
+```yaml
+类型: 缺陷修复
+方案类型: implementation
+优先级: P1
+状态: 已完成
+创建: 2026-04-24
+```
+
+---
+
+## 1. 需求
+
+### 背景
+用户反馈本地管理端 `#/subscriptions/plans` 页面一加载，就会把所有套餐的“新购”状态取消，属于高风险运营回归：仅浏览页面就会触发真实写操作。
+
+### 目标
+- 阻止套餐管理页在加载阶段触发任何 `show / sell / renew` 写操作。
+- 保持页面现有 Apple 风格视觉与交互不变，只修复状态开关的数据联动问题。
+
+### 约束条件
+```yaml
+范围约束: 仅修复套餐管理页加载即误触状态更新的问题，不扩展套餐管理其他功能
+技术约束: 继续使用 Vue3 + TypeScript + Element Plus 现有栈，不新增依赖
+业务约束: 不改动套餐保存/排序流程，只修补状态开关的数据初始化与提交防护
+```
+
+### 验收标准
+- [ ] 打开 `#/subscriptions/plans` 时，不会因为初始渲染自动调用状态更新接口。
+- [ ] “显示 / 新购 / 续费”开关仅在用户主动切换时才提交更新。
+- [ ] `admin-frontend` 构建通过。
+
+---
+
+## 2. 方案
+
+### 根因假设
+`ElSwitch` 在收到非 `true/false` 的 `modelValue` 时会立即回退到 `inactiveValue` 并发出 `change`。套餐列表里的 `sell` 字段存在后端返回数值 `0/1` 的情况，导致页面初始渲染时把“新购”批量提交为 `false`。
+
+### 技术方案
+1. 在套餐工具层新增开关字段归一化逻辑，把 `show / sell / renew` 统一转换为布尔值后再渲染。
+2. 在套餐管理页加载数据时先归一化，再绑定到 `ElSwitch`。
+3. 在开关提交逻辑增加“值未变化直接返回”的防抖护栏，防止初始化阶段或重复事件造成误写。
+
+### 风险评估
+| 风险 | 等级 | 应对 |
+|------|------|------|
+| 后端其他接口仍可能返回 `0/1` | 中 | 本次在前端入口先做归一化，确保当前页面稳定 |
+| 开关事件护栏过严导致用户点击无效 | 低 | 仅在“新值与当前值完全相同”时跳过，正常点击仍会提交 |
+
+---
+
+## 3. 技术决策
+
+### admin-frontend-plan-toggle-regression#D001: 先在前端入口归一化套餐开关值
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户选择优先止住页面加载误触写操作。
+**决策**: 先在 `admin-frontend` 的套餐列表加载阶段统一把 `show / sell / renew` 转成布尔值，再交给 `ElSwitch`。
+**理由**: 能最小代价阻断当前回归，不扩大后端改动面。
+
+### admin-frontend-plan-toggle-regression#D002: 开关提交增加同值短路护栏
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 即使后续仍有组件级重复 `change` 事件，也不应再次落库。
+**决策**: `handleToggle` 中先比较当前值与目标值，相同则直接返回。
+**理由**: 用最小逻辑补一层行为安全网，避免“浏览即写入”的同类回归。
@@ -0,0 +1,44 @@
+# 任务清单: admin-frontend-plan-toggle-regression
+
+> **@status:** completed | 2026-04-24 15:51
+
+```yaml
+@feature: admin-frontend-plan-toggle-regression
+@created: 2026-04-24
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 4 | 0 | 0 | 4 |
+
+---
+
+## 任务列表
+
+- [√] 1. 读取套餐管理页、工具层与相关接口代码，确认页面加载即误写的根因
+- [√] 2. 为套餐状态开关增加加载期归一化与同值短路保护
+- [√] 3. 运行 `admin-frontend` 构建验证，确认修复未破坏现有构建
+- [√] 4. 同步 `.helloagents` 文档与交付记录
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-24 15:42 | 方案包初始化 | completed | 已确认本轮以“阻止页面加载误触写操作”为首要目标 |
+| 2026-04-24 15:45 | 根因定位 | completed | 确认 `ElSwitch` 遇到非布尔 `sell` 值会立即回退到 `false` 并触发 `change` |
+| 2026-04-24 15:48 | 修复实施 | completed | 已在套餐列表加载阶段归一化 `show / sell / renew`，并为开关提交增加同值短路 |
+| 2026-04-24 15:50 | 构建验证 | completed | `admin-frontend` 执行 `npm run build` 通过 |
+| 2026-04-24 15:51 | 文档同步 | completed | 已更新 CHANGELOG、模块文档与方案包状态 |
+
+---
+
+## 执行备注
+
+- 当前根仓存在 `public/assets/admin` 子模块未提交状态，本轮需避免覆盖无关产物。
+- 构建验证会刷新 `public/assets/admin` 子模块产物；本轮未代做子模块提交与根仓发布。
@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 5,
+  "failed": 0,
+  "pending": 0,
+  "total": 5,
+  "done": 5,
+  "percent": 100,
+  "current": "公告管理真实工作台、构建验证与知识库同步已完成，等待用户验收",
+  "updated_at": "2026-04-24 16:09:00"
+}
@@ -0,0 +1,51 @@
+{
+  "updatedAt": "2026-04-24T07:55:06.613Z",
+  "version": 1,
+  "source": "R2",
+  "originCommand": "design",
+  "verifyMode": "review-first",
+  "reviewerFocus": [
+    "公告管理页面是否延续当前 Apple 风格后台的黑色 hero 与白色工作台结构",
+    "列表、编辑弹窗与排序模式是否覆盖用户要求的完整 CRUD 工作台",
+    "其余系统管理入口是否仍保持当前边界不被误改"
+  ],
+  "testerFocus": [
+    "公告列表是否真实连接 /notice/fetch",
+    "新增编辑是否真实连接 /notice/save，显隐是否连接 /notice/show，删除是否连接 /notice/drop",
+    "排序模式是否真实调用 /notice/sort 且 admin-frontend 构建通过"
+  ],
+  "ui": {
+    "required": true,
+    "designContract": true,
+    "sourcePriority": [
+      "plan.md",
+      ".helloagents/DESIGN.md",
+      "hello-ui"
+    ],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "",
+      "focus": []
+    },
+    "visualValidation": {
+      "required": true,
+      "reason": "公告管理属于真实后台 CRUD 页，需要确认列表、编辑弹窗与排序模式在浏览器中符合 Apple 风格后台契约",
+      "screens": [
+        "#/system/notices desktop",
+        "#/system/notices editor dialog",
+        "#/system/notices sort dialog"
+      ],
+      "states": [
+        "公告列表加载完成态",
+        "新增/编辑弹窗态",
+        "排序编辑态"
+      ]
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "",
+    "focus": [],
+    "preferredSources": []
+  }
+}
@@ -0,0 +1,90 @@
+# 变更提案: admin-frontend-notice-management
+
+## 元信息
+```yaml
+类型: 功能开发
+方案类型: implementation
+优先级: P1
+状态: 已完成
+创建: 2026-04-24
+```
+
+---
+
+## 1. 需求
+
+### 背景
+用户要求继续完成 `admin-frontend` 的“公告管理”模块，并明确选择“完整 CRUD 工作台”方案。当前 `/system/notices` 仍是占位页，但 Laravel 后端已存在 `notice/fetch`、`notice/save`、`notice/show`、`notice/drop`、`notice/sort` 管理接口，可直接承接真实公告管理工作流。
+
+### 目标
+- 将 `#/system/notices` 从占位页升级为真实可用的公告管理页。
+- 提供符合当前 Apple 风格后台体系的公告列表、搜索、显隐切换、编辑弹窗、删除与排序能力。
+- 保持前后端字段契约与现有 `NoticeController` / `NoticeSave` 一致，不在前端猜测额外接口。
+
+### 约束条件
+```yaml
+范围约束: 仅实现公告管理工作台，不扩展插件/主题/支付/知识库等其他系统模块
+技术约束: 继续使用 Vue3 + TypeScript + Element Plus，不新增第三方编辑器依赖
+业务约束: 公告保存字段以 title/content/img_url/tags/show/popup/id 为准；排序继续调用 /notice/sort
+视觉约束: 延续 apple/DESIGN.md 与 .helloagents/DESIGN.md 的黑色 hero + 白色工作台 + 克制蓝色交互体系
+```
+
+### 验收标准
+- [ ] `#/system/notices` 可真实拉取公告列表，并显示 ID、显隐状态、标题与操作列。
+- [ ] 页面支持标题关键词搜索，筛选后结果与计数同步更新。
+- [ ] 支持新增/编辑公告，字段覆盖标题、内容、背景图、标签、显示状态与弹窗公告开关。
+- [ ] 支持删除公告与显隐切换，并给出明确成功/失败反馈。
+- [ ] 支持独立排序模式，保存后调用 `/notice/sort` 同步顺序。
+- [ ] `admin-frontend` 执行 `npm run build` 通过。
+
+---
+
+## 2. 方案
+
+### 页面结构
+1. 延续系统配置/套餐管理的 Apple 风格后台结构，顶部保留黑色 hero，右侧展示公告统计摘要。
+2. 主工作区使用白色表格容器，头部提供“添加公告”“搜索公告标题”“编辑排序”。
+3. 编辑公告使用 `ElDialog` 弹窗，参考用户截图采用“标题 + 公告内容 + 公告背景 + 节点标签 + 显示开关”的集中编辑方式。
+4. 排序使用独立对话框，通过上移/下移维护本地顺序，再提交到 `/notice/sort`。
+
+### 前端实现策略
+1. 在 `src/types/api.d.ts` 新增公告类型，明确列表项与保存载荷结构。
+2. 在 `src/api/admin.ts` 新增公告管理 API 封装：`fetchNotices / saveNotice / toggleNoticeVisibility / deleteNotice / sortNotices`。
+3. 在 `src/utils/notices.ts` 下沉公告筛选、标签归一化、表单回填、排序移动等逻辑，避免页面组件膨胀。
+4. 新增：
+   - `src/views/system/SystemNoticesView.vue`
+   - `src/views/system/SystemNoticeEditorDialog.vue`
+   - `src/views/system/SystemNoticeEditorDialog.scss`
+5. 将路由 `/system/notices` 指向真实页面，保留其他系统入口占位不变。
+
+### 风险评估
+| 风险 | 等级 | 应对 |
+|------|------|------|
+| 后端 `show` / `popup` 可能返回 `0/1` | 中 | 前端统一布尔归一化，提交时再按接口兼容输出 |
+| 公告内容编辑器缺少富文本能力 | 低 | 本轮延续轻量文本/Markdown 输入策略，优先保证 CRUD 与数据流闭环 |
+| 构建会刷新 `public/assets/admin` 子模块产物 | 中 | 仅执行 `admin-frontend` 构建验证，不代做子模块发布 |
+
+---
+
+## 3. 技术决策
+
+### admin-frontend-notice-management#D001: 公告管理采用“真实列表页 + 独立编辑弹窗 + 独立排序对话框”
+**日期**: 2026-04-24  
+**状态**: ✅采纳  
+**背景**: 用户明确要求对齐截图所表达的后台管理工作台体验。  
+**决策**: 列表与行操作保留在主页面，新增/编辑使用集中弹窗，排序单独进入对话框处理。  
+**理由**: 最符合当前后台已有套餐管理模式，也能覆盖截图中的核心操作链路。
+
+### admin-frontend-notice-management#D002: 公告内容编辑延续轻量文本输入，不引入新的富文本依赖
+**日期**: 2026-04-24  
+**状态**: ✅采纳  
+**背景**: 现有 `admin-frontend` 已尽量控制依赖规模，且后端只要求标题/内容/图片/标签等基本字段。  
+**决策**: 本轮使用增强型 textarea 输入公告内容，并保留 Markdown 友好提示，不新增第三方富文本编辑器。  
+**理由**: 优先完成真实 CRUD 与可维护数据流，避免为了富文本皮层扩大实现成本。
+
+### admin-frontend-notice-management#D003: 公告显隐与弹窗开关在前端统一做布尔归一化
+**日期**: 2026-04-24  
+**状态**: ✅采纳  
+**背景**: 后台现有开关型字段历史上存在 `0/1` 与布尔混用情况。  
+**决策**: 拉取、回填和提交前都通过工具层统一归一化 `show / popup / tags`。  
+**理由**: 可避免再次出现 Element Plus 开关初始渲染误触发写操作的回归。
@@ -0,0 +1,43 @@
+# 任务清单: admin-frontend-notice-management
+
+> **@status:** completed | 2026-04-24 16:09
+
+```yaml
+@feature: admin-frontend-notice-management
+@created: 2026-04-24
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 5 | 0 | 0 | 5 |
+
+---
+
+## 任务列表
+
+- [√] 1. 读取公告管理相关前后端代码、类型与 UI 模式，冻结本轮实现边界
+- [√] 2. 新增公告管理 API、类型定义与工具函数，统一字段归一化/排序/表单转换
+- [√] 3. 实现真实公告管理页面与编辑弹窗，接通搜索、显隐、删除、新增/编辑工作流
+- [√] 4. 实现公告排序模式并将 `/system/notices` 路由切换到真实页面
+- [√] 5. 运行 `admin-frontend` 构建验证，并同步 `.helloagents` 文档与交付记录
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-24 15:55 | 方案包初始化 | completed | 已确认本轮采用完整 CRUD 工作台方案，目标对齐 `/notice/*` 后端接口与用户截图 |
+| 2026-04-24 16:04 | 页面实现 | completed | 已补齐公告 API、类型、工具层、真实列表页、编辑弹窗与排序模式 |
+| 2026-04-24 16:08 | 构建与知识同步 | completed | `admin-frontend` 执行 `npm run build` 通过，并已更新 context/module/changelog 记录 |
+
+---
+
+## 执行备注
+
+- 其余系统模块（插件/主题/支付/知识库）继续保持当前占位页，不在本轮展开。
+- 构建验证会刷新 `public/assets/admin` 子模块产物，本轮仅提供功能实现与验证证据，不自动代做发布。
@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 4,
+  "failed": 0,
+  "pending": 0,
+  "total": 4,
+  "done": 4,
+  "percent": 100,
+  "current": "知识库管理页已完成并通过构建验证",
+  "updated_at": "2026-04-24 16:24:00"
+}
@@ -0,0 +1,83 @@
+# 变更提案: admin-frontend-knowledge-management
+
+## 元信息
+```yaml
+类型: 功能增强
+方案类型: implementation
+优先级: P1
+状态: 已完成
+创建: 2026-04-24
+```
+
+---
+
+## 1. 需求
+
+### 背景
+`admin-frontend` 当前已经完成系统管理分组与系统配置页，但 `#/system/knowledge` 仍停留在结构化占位页。用户已提供目标截图，希望继续补齐真实“知识库管理”页面，并保持现有 Apple 化后台的低噪音运营风格。
+
+### 目标
+- 将 `#/system/knowledge` 从占位页升级为真实知识库管理工作台。
+- 支持知识列表查看、搜索、分类筛选、显隐切换、编辑排序、删除和新增/编辑。
+- 编辑器采用用户刚确认的“轻量 Markdown 编辑器”方案，支持常用格式插入与预览，不新增富文本依赖。
+
+### 约束条件
+```yaml
+范围约束: 仅实现 admin-frontend 的知识库管理页，不改 Laravel 后端接口行为
+技术约束: 继续使用 Vue3 + TypeScript + Element Plus + markdown-it 现有栈，不新增第三方编辑器依赖
+视觉约束: 保持 Apple 风格后台气质，贴近用户截图中的“轻表格 + 中央编辑弹窗”结构
+业务约束: 后端真相源固定为 knowledge/fetch、knowledge/getCategory、knowledge/save、knowledge/show、knowledge/drop、knowledge/sort
+```
+
+### 验收标准
+- [√] `#/system/knowledge` 可以展示真实知识列表，并支持关键字搜索与分类筛选。
+- [√] 列表支持显隐切换、删除、排序调整与编辑入口。
+- [√] 新增/编辑弹窗支持标题、分类、语言、显示状态与正文编辑；正文采用轻量 Markdown 方案并支持预览。
+- [√] `admin-frontend` 构建通过，产物成功输出到 `public/assets/admin`。
+
+---
+
+## 2. 方案
+
+### 信息架构
+1. 列表页采用“页头说明 + 操作工具条 + 白色数据表格”结构，贴近用户截图的运营后台感。
+2. 编辑页采用中央 `ElDialog`，而非侧滑抽屉，保持与截图一致的工作流。
+3. 排序采用本地编辑对话框，复用当前列表顺序生成 `ids`，再调用 `/knowledge/sort`。
+
+### 技术方案
+1. 在 `src/types/api.d.ts` 与 `src/api/admin.ts` 中补充知识库实体类型和请求封装。
+2. 新增 `src/utils/knowledge.ts`，统一处理分类、表单模型、Markdown 渲染和本地过滤逻辑。
+3. 新建 `SystemKnowledgeView.vue` 与 `KnowledgeEditorDialog.vue`，分别承载知识库列表页和编辑弹窗。
+4. 路由层将 `/system/knowledge` 从 `SystemPlaceholderView` 切换为真实页面组件。
+
+### 风险评估
+| 风险 | 等级 | 应对 |
+|------|------|------|
+| 后端列表接口不返回正文与语言 | 中 | 编辑时单独调用 `knowledge/fetch?id=` 拉取详情 |
+| 轻量 Markdown 编辑体验弱于完整富文本 | 低 | 用工具栏 + 预览补齐高频编辑动作，优先满足当前截图与范围 |
+| 排序与显隐属于真实写操作 | 中 | 保持明确按钮、反馈提示与失败回滚，避免静默提交 |
+
+---
+
+## 3. 技术决策
+
+### admin-frontend-knowledge-management#D001: 编辑器采用轻量 Markdown 方案
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户在执行前确认选择了“轻量 Markdown 编辑器（推荐）”。
+**决策**: 复用仓内已有 `markdown-it` 能力，自建工具栏 + 预览编辑器，不引入额外富文本依赖。
+**理由**: 能更快贴近当前截图的编辑体验，同时控制依赖和实现复杂度。
+
+### admin-frontend-knowledge-management#D002: 列表页采用真实表格，编辑页采用中央对话框
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户截图呈现的是“列表页 + 中央弹窗”的运营后台工作流。
+**决策**: 保持列表、筛选、开关、排序留在主页面，新增/编辑放入对话框集中处理。
+**理由**: 更符合知识库管理的批量维护场景，也能最大程度贴合用户提供的视觉参考。
+
+### admin-frontend-knowledge-management#D003: 排序采用本地草稿编辑后统一提交
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 后端排序接口为 `POST /knowledge/sort`，需要提交有序 `ids`。
+**决策**: 先在前端弹窗维护当前顺序草稿，再一次性提交排序结果。
+**理由**: 避免列表页直接拖拽带来的交互复杂度和误操作风险，保持后台操作克制清晰。
@@ -0,0 +1,43 @@
+# 任务清单: admin-frontend-knowledge-management
+
+> **@status:** completed | 2026-04-24 16:24
+
+```yaml
+@feature: admin-frontend-knowledge-management
+@created: 2026-04-24
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 4 | 0 | 0 | 4 |
+
+---
+
+## 任务列表
+
+- [√] 1. 梳理知识库后端接口、类型边界与现有系统管理设计契约
+- [√] 2. 实现知识库 API/类型/工具层与真实列表页面
+- [√] 3. 实现知识编辑弹窗、排序流程与显隐/删除操作
+- [√] 4. 运行 `admin-frontend` 构建验证，并同步 `.helloagents` 记录
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-24 16:10 | 方案包初始化 | completed | 用户已确认采用轻量 Markdown 编辑器方案 |
+| 2026-04-24 16:18 | 页面实现 | completed | 已接入知识列表、分类筛选、编辑弹窗、显隐切换与排序对话框 |
+| 2026-04-24 16:22 | 构建验证 | completed | `admin-frontend` 执行 `npm run build` 通过，并输出知识库页面产物 |
+| 2026-04-24 16:24 | 文档同步 | completed | 已更新 CHANGELOG、模块文档与状态快照 |
+
+---
+
+## 执行备注
+
+- 当前仓存在未提交的历史变更与多个未归档方案包，本轮只增量实现知识库管理，不覆盖无关文件。
+- `public/assets/admin` 为前端产物子模块；构建后需要同时复核根仓与子模块状态。
@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 4,
+  "failed": 0,
+  "pending": 0,
+  "total": 4,
+  "done": 4,
+  "percent": 100,
+  "current": "Stash AnyTLS 兼容过滤修复已完成，等待用户验收",
+  "updated_at": "2026-04-24 16:28:00"
+}
@@ -0,0 +1,81 @@
+# 变更提案: fix-stash-anytls-compat-filter
+
+## 元信息
+```yaml
+类型: 修复
+方案类型: implementation
+优先级: P1
+状态: 已完成
+创建: 2026-04-24
+```
+
+---
+
+## 1. 需求
+
+### 背景
+用户反馈 `?flag=stash` 订阅地址导入到 Stash 时，客户端提示“**不支持 anytls 协议**”。现场抓取订阅真值可见，当前 `stash` 导出仍包含多个 `type: anytls` 节点，因此报错不是客户端假警告，而是后端兼容过滤缺失。
+
+### 目标
+- 修复 `flag=stash` 订阅导出逻辑，避免未知版本或低版本 Stash 收到 `AnyTLS` 节点。
+- 保留高版本 Stash 的 `AnyTLS` 能力：仅当客户端版本 `>= 3.3.0` 时继续导出。
+- 改动范围限制在 Stash 订阅导出与相关知识记录，不联动其他协议。
+
+### 约束条件
+```yaml
+范围约束: 仅修复 Stash 的 AnyTLS 兼容过滤，不修改 Clash / ClashMeta / General / Shadowrocket
+技术约束: 继续使用现有 Laravel + Protocol 导出链路，不新增依赖
+验证约束: 当前工作区缺少 PHP 运行时与 vendor，无法执行 phpunit/php lint，只能做静态校验与真值复核
+业务约束: 未知版本采用保守策略，宁可少导出 AnyTLS，也不继续让 Stash 导入报错
+```
+
+### 验收标准
+- [ ] `app/Protocols/Stash.php` 在客户端版本未知或 `< 3.3.0` 时不再导出 `AnyTLS`
+- [ ] 客户端版本 `>= 3.3.0` 时仍允许导出 `AnyTLS`
+- [ ] 现场订阅问题的根因、修复范围与验证限制已记录到方案包和知识库
+
+---
+
+## 2. 方案
+
+### 根因分析
+`ClientController` 会把 `flag=stash` 解析为 `Stash` 协议，但当链接里只有 `flag=stash` 且没有明确版本时，`clientVersion` 为空。`Stash` 虽然声明了 `anytls.base_version = 3.3.0`，但当前兼容链路没有真正消费该门槛，导致 `AnyTLS` 节点仍被输出。
+
+### 技术方案
+1. 在 `Stash` 导出器中增加 `AnyTLS` 版本守卫：仅当 `clientVersion >= 3.3.0` 时写入 `AnyTLS` 节点。
+2. 未知版本默认视为不支持 `AnyTLS`，与用户选择的“保守兼容”策略保持一致。
+3. 补一条轻量回归测试，锁定该版本判断函数的边界行为，供具备 PHP 环境时执行。
+
+### 影响范围
+```yaml
+涉及模块:
+  - app/Protocols/Stash.php
+  - tests/Unit/Protocols/StashAnyTlsCompatibilityTest.php
+  - .helloagents 方案包与变更日志
+预计变更文件: 6-8
+```
+
+### 风险评估
+| 风险 | 等级 | 应对 |
+|------|------|------|
+| 未知版本 Stash 会少收到 AnyTLS 节点 | 低 | 这是有意的保守降级，优先保证“能导入” |
+| 其他协议也存在类似 base_version 配置未生效 | 中 | 本次按用户范围只修 Stash AnyTLS，其他协议后续按需单独处理 |
+| 当前环境无法执行 PHP 级验证 | 中 | 保留静态回归测试文件，并在交付中明确说明阻塞点 |
+
+---
+
+## 3. 技术决策
+
+### fix-stash-anytls-compat-filter#D001: 未知版本按不支持 AnyTLS 处理
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户明确选择“默认对 Stash 做保守兼容”，要求未知版本或 `< 3.3.0` 时自动过滤 `AnyTLS`。
+**决策**: `flag=stash` 导出在未拿到客户端版本时，直接跳过 `AnyTLS` 节点。
+**理由**: 现场问题正是因为未知版本仍收到 `AnyTLS`；优先恢复导入稳定性。
+
+### fix-stash-anytls-compat-filter#D002: 仅在 Stash 导出器中做定点修复
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: `base_version` 兼容机制的通用实现尚未完善，但当前用户问题只指向 `flag=stash`。
+**决策**: 先在 `Stash` 导出器内增加 `AnyTLS` 版本守卫，不扩散到其他协议类。
+**理由**: 改动最小、风险可控，且能精准解决现场报错。
@@ -0,0 +1,44 @@
+# 任务清单: fix-stash-anytls-compat-filter
+
+> **@status:** completed | 2026-04-24 16:28
+
+```yaml
+@feature: fix-stash-anytls-compat-filter
+@created: 2026-04-24
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 4 | 0 | 0 | 4 |
+
+---
+
+## 任务列表
+
+- [√] 1. 抓取现场 `flag=stash` 订阅真值，确认导入报错由 `AnyTLS` 节点仍被导出导致
+- [√] 2. 在 `Stash` 导出器中增加 `AnyTLS` 版本守卫，未知版本或 `< 3.3.0` 时跳过导出
+- [√] 3. 补充 `AnyTLS` 版本判断回归测试文件，覆盖未知版本 / 低版本 / 边界版本
+- [√] 4. 同步 `.helloagents` 方案包、上下文与变更记录，并说明 PHP 运行验证受限
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-24 16:19 | 方案包初始化 | completed | 已创建 `202604241619_fix-stash-anytls-compat-filter` |
+| 2026-04-24 16:21 | 现场复核 | completed | 远程 `flag=stash` 订阅真值确认仍包含 `type: anytls` 节点 |
+| 2026-04-24 16:24 | 修复实施 | completed | `Stash` 导出器已按 `3.3.0` 门槛过滤 AnyTLS |
+| 2026-04-24 16:26 | 静态验证 | completed | 已新增回归测试文件；当前环境缺少 PHP 与 vendor，无法执行 |
+| 2026-04-24 16:28 | 知识库同步 | completed | 已更新 context / module index / changelog / state |
+
+---
+
+## 执行备注
+
+- 当前工作区存在大量与 `admin-frontend` 相关的未提交变更，本轮仅触碰 Stash 导出与 `.helloagents` 文档，未整理其他脏改动。
+- 因当前环境缺少 `php` 命令、`vendor/autoload.php` 与 `vendor/bin/phpunit`，本轮无法运行 PHP lint / PHPUnit，只能交付代码修复与静态回归文件。