harden sm-flow protocol and archive v4.0 validation runs
- Rewrite hard constraint #1: apply must read Committed OpenSpec files as the execution source of truth - Promote sub-skill invocation to hard constraint #6; remove fallbacks.md and all degradation paths - Add file existence verification at commit and archive exit gates - Require grill question pool, evidence-driven conclusions, and user-interview confirmations to be written to decisions.md - Record v4.0 validation retrospective in workflow.md: propose overreach, sub-skill pseudo-calling, spec omitting user behavior - Archive knowledge-index-sort OpenSpec and devflow entries from prior run
This commit is contained in:
zhuyongxin
@@ -0,0 +1,67 @@
|
||||
# knowledge-index-sort Design
|
||||
|
||||
## 架构摘要
|
||||
|
||||
排序功能集成到现有的 `applyFilters()` 函数中，形成完整的过滤→排序→渲染管道：
|
||||
|
||||
```
|
||||
用户操作（搜索/标签/年份/排序）
|
||||
↓
|
||||
applyFilters()
|
||||
├─ 年份过滤（year-filter）
|
||||
├─ 标签过滤（tag-badge.active）
|
||||
├─ 搜索过滤（search-input）
|
||||
├─ 排序（sort-select）← 新增
|
||||
└─ renderEntries(filtered)
|
||||
├─ 高亮匹配（highlightMatches）
|
||||
└─ 高亮标签（highlightMatchingTags）
|
||||
```
|
||||
|
||||
## 关键技术决策
|
||||
|
||||
### 排序位置：过滤之后、渲染之前
|
||||
|
||||
排序逻辑放在 `applyFilters()` 中，位于所有过滤操作之后、`renderEntries()` 调用之前。
|
||||
|
||||
- 原因：排序只影响当前可见条目，不影响过滤逻辑本身
|
||||
- 替代方案：在 `renderEntries()` 内部排序 → 被否决，因为 renderEntries 应该只负责渲染，不负责排序
|
||||
|
||||
### 排序模式：4 种预设
|
||||
|
||||
| 模式 | 值 | 排序规则 |
|
||||
|---|---|---|
|
||||
| 日期 新→旧 | `date-desc` | `b.date.localeCompare(a.date)`（默认） |
|
||||
| 日期 旧→新 | `date-asc` | `a.date.localeCompare(b.date)` |
|
||||
| 标签 多→少 | `tags-desc` | `b.tags.length - a.tags.length` |
|
||||
| 标签 少→多 | `tags-asc` | `a.tags.length - b.tags.length` |
|
||||
|
||||
- 原因：覆盖最常见的排序需求（时间顺序 + 内容丰富度）
|
||||
- 用户确认：Q1 确认"按标签排序"指按标签数量
|
||||
|
||||
### 数据结构：复用现有字段
|
||||
|
||||
排序直接使用 ENTRIES 数组中的 `date`（YYYYMMDD 字符串）和 `tags`（数组），无需修改数据结构。
|
||||
|
||||
- 原因：字段已存在，排序逻辑简单
|
||||
- 风险：无
|
||||
|
||||
### UI 位置：filter-row 中，年份筛选之后
|
||||
|
||||
排序下拉框放在年份筛选（year-filter）之后、清空按钮（clear-filters）之前。
|
||||
|
||||
- 原因：与现有控件保持一致的视觉层级
|
||||
- 替代方案：单独一行 → 被否决，增加垂直空间占用
|
||||
|
||||
## 模块地图
|
||||
|
||||
| 模块 | 职责 | 备注 |
|
||||
|---|---|---|
|
||||
| sort-select HTML | 排序 UI 控件 | 4 个 option |
|
||||
| bindSortSelect() | 绑定 change 事件 | 触发 applyFilters() |
|
||||
| applyFilters() 排序段 | 执行排序逻辑 | 过滤后、渲染前 |
|
||||
| clearFilters() | 重置排序为默认值 | `date-desc` |
|
||||
|
||||
## 架构审计
|
||||
|
||||
- **风险**：无跨模块依赖，纯前端改动
|
||||
- **缓解**：不适用
|
||||
@@ -0,0 +1,46 @@
|
||||
# knowledge-index-sort Proposal
|
||||
|
||||
## 问题
|
||||
|
||||
knowledge-index-panel 当前条目按 ENTRIES 数组原始顺序渲染，用户无法按日期或标签排序查看。
|
||||
|
||||
## 建议方案
|
||||
|
||||
在筛选栏（filter-row）中添加排序下拉框，支持按日期（新→旧/旧→新）和标签数量（多→少/少→多）排序。
|
||||
|
||||
## 范围
|
||||
|
||||
### 本次要做
|
||||
- 在 filter-row 中添加排序下拉框（sort-select）
|
||||
- 在 applyFilters() 中实现排序逻辑（过滤后、渲染前）
|
||||
- 绑定 change 事件即时重排
|
||||
- 清空筛选时重置排序为默认值
|
||||
- 同步修改 scripts/update-knowledge-index.sh
|
||||
|
||||
### 本次不做
|
||||
- 多列排序
|
||||
- 拖拽排序
|
||||
- 修改 ENTRIES 数据结构
|
||||
- 分页
|
||||
|
||||
### 影响区域
|
||||
- `knowledge-index.html`（HTML + CSS + JS）
|
||||
- `scripts/update-knowledge-index.sh`（同步修改）
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不做服务端排序（纯前端客户端改动）
|
||||
- 不做排序状态持久化（刷新后恢复默认）
|
||||
- 不修改知识条目数据结构
|
||||
|
||||
## 风险
|
||||
|
||||
- **低风险**：纯前端改动，单文件 + 生成脚本
|
||||
- **兼容性**：已有 3 个条目，排序逻辑简单（日期字符串比较 + 数组长度比较）
|
||||
- **性能**：3 条目的排序开销可忽略，即使未来增长到 50 条也无压力
|
||||
|
||||
## 上下文约束
|
||||
|
||||
- 排序必须在过滤后生效（与年份筛选、标签筛选、搜索取交集）
|
||||
- 与其他控件保持一致的即时响应模式（change 事件）
|
||||
- 清空筛选时重置所有控件（包括排序）
|
||||
@@ -0,0 +1,47 @@
|
||||
# 排序功能规格
|
||||
|
||||
## Scenario: 用户按日期新→旧排序
|
||||
|
||||
**Given** 知识库索引面板已加载，显示 3 个条目
|
||||
**When** 用户选择排序下拉框的"日期 新→旧"
|
||||
**Then** 条目按日期降序排列（最新的在前）
|
||||
**And** 排序与当前激活的过滤条件（搜索、标签、年份）取交集
|
||||
|
||||
## Scenario: 用户按日期旧→新排序
|
||||
|
||||
**Given** 知识库索引面板已加载
|
||||
**When** 用户选择排序下拉框的"日期 旧→新"
|
||||
**Then** 条目按日期升序排列（最旧的在前）
|
||||
|
||||
## Scenario: 用户按标签数量多→少排序
|
||||
|
||||
**Given** 知识库索引面板已加载
|
||||
**When** 用户选择排序下拉框的"标签 多→少"
|
||||
**Then** 条目按标签数组长度降序排列（标签多的在前）
|
||||
|
||||
## Scenario: 用户按标签数量少→多排序
|
||||
|
||||
**Given** 知识库索引面板已加载
|
||||
**When** 用户选择排序下拉框的"标签 少→多"
|
||||
**Then** 条目按标签数组长度升序排列（标签少的在前）
|
||||
|
||||
## Scenario: 排序与过滤组合
|
||||
|
||||
**Given** 用户已激活标签筛选（如"Claude Code"）
|
||||
**When** 用户切换排序模式
|
||||
**Then** 只有匹配的条目被排序显示
|
||||
**And** 排序不影响过滤逻辑本身
|
||||
|
||||
## Scenario: 清空筛选重置排序
|
||||
|
||||
**Given** 用户已选择非默认排序模式
|
||||
**When** 用户点击"清空筛选"按钮
|
||||
**Then** 排序重置为默认值"日期 新→旧"
|
||||
**And** 所有过滤条件也被清空
|
||||
|
||||
## Scenario: 排序即时响应
|
||||
|
||||
**Given** 知识库索引面板已加载
|
||||
**When** 用户切换排序下拉框
|
||||
**Then** 条目列表立即重新排列
|
||||
**And** 不需要点击"应用"按钮
|
||||
@@ -0,0 +1,25 @@
|
||||
# knowledge-index-sort Tasks
|
||||
|
||||
## 需求追踪
|
||||
|
||||
| 需求 | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| 排序 UI 控件 | 已完成 | sort-select 下拉框 |
|
||||
| 排序逻辑实现 | 已完成 | applyFilters() 中排序段 |
|
||||
| 事件绑定 | 已完成 | bindSortSelect() |
|
||||
| 清空筛选重置 | 已完成 | clearFilters() 重置 sort-select |
|
||||
| 脚本同步 | 已完成 | update-knowledge-index.sh |
|
||||
| 浏览器验证 | 已完成 | 用户确认通过 |
|
||||
|
||||
## 实现任务
|
||||
|
||||
- [x] 在 filter-row 中添加 sort-select HTML（4 个 option）
|
||||
- [x] 在 applyFilters() 中添加排序逻辑（过滤后、渲染前）
|
||||
- [x] 实现 4 种排序模式（date-desc/date-asc/tags-desc/tags-asc）
|
||||
- [x] 添加 bindSortSelect() 函数绑定 change 事件
|
||||
- [x] 在 init 中调用 bindSortSelect()
|
||||
- [x] 在 clearFilters() 中重置 sort-select 为 date-desc
|
||||
- [x] 同步修改 scripts/update-knowledge-index.sh（HTML 模板 + JS 代码）
|
||||
- [x] 浏览器验证：测试 4 种排序模式
|
||||
- [x] 浏览器验证：测试排序与过滤组合
|
||||
- [x] 浏览器验证：测试清空筛选重置排序
|
||||
Reference in New Issue
Block a user