Reorganize workspace and archive skill artifacts

2026-05-20 11:39:30 +08:00
parent 0e0275d46a
commit f45122dafb
83 changed files with 9733 additions and 15 deletions
@@ -0,0 +1,31 @@
+## Context
+
+当前知识索引页面是单文件静态 HTML，由 `scripts/update-knowledge-index.sh` 生成。数据源 `ENTRIES` 中每个条目都有 `date` 字段，格式为 `YYYYMMDD`，页面渲染时已经用该字段展示 `YYYY-MM-DD`。
+
+## Design
+
+新增年份筛选采用纯前端派生数据：
+
+1. 从 `ENTRIES` 中读取有效 `date`。
+2. 取前四位作为 year。
+3. 去重后按年份倒序生成 `<select id="year-filter">`。
+4. `applyFilters()` 同时读取搜索词、激活标签和选中年份。
+5. 过滤顺序为：年份 → 标签 → 搜索。顺序不影响结果，但先按年份过滤能减少后续匹配集合。
+
+## UI Placement
+
+年份筛选放在搜索框下方、标签云上方，作为全局过滤器。这样用户先看到最常用的文字搜索，再看到粗粒度年份过滤和细粒度标签过滤。
+
+## Edge Cases
+
+- 没有条目：不渲染年份选项。
+- 条目缺失有效日期：不出现在年份选项中，但在“全部年份”下仍显示。
+- 选择某一年时，缺失有效年份的条目不匹配该年份。
+- 标签和搜索继续与年份筛选取交集。
+
+## Validation
+
+- 页面中应出现“年份”筛选控件。
+- 选择 `2026` 时，只显示 `date` 以 `2026` 开头的条目。
+- 搜索词、标签和年份同时生效。
+- 重新运行 `scripts/update-knowledge-index.sh` 后功能仍存在。
@@ -0,0 +1,26 @@
+## Why
+
+知识库索引已经支持全文搜索和标签筛选，但当知识条目跨越多个年份时，用户无法快速只查看某一年学习或沉淀的内容。当前条目已经包含 `date: YYYYMMDD`，因此可以在不改变数据模型和生成流程的前提下增加年份筛选。
+
+## What Changes
+
+- 在 `knowledge-index.html` 中新增年份筛选控件。
+- 从 `ENTRIES[].date` 自动提取年份并生成年份选项。
+- 年份筛选与现有搜索、标签筛选组合生效。
+- 默认显示全部年份；选择“全部年份”时清除年份筛选。
+- 更新 `scripts/update-knowledge-index.sh`，确保重建索引后功能不会丢失。
+
+## Capabilities
+
+### New Capabilities
+- `knowledge-filtering`: 用户可以按年份筛选知识条目，并与搜索、标签过滤组合使用。
+
+### Modified Capabilities
+- `knowledge-index-panel`: 页面增加一个年份筛选控件。
+
+## Impact
+
+- 修改 `scripts/update-knowledge-index.sh` 的 HTML 模板。
+- 重新生成 `knowledge-index.html`。
+- 不修改任何 `knowledge_*/` 内容。
+- 不引入外部依赖。
@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: Year-based filtering
+
+The knowledge index SHALL allow users to filter visible entries by year derived from each entry's `date` field.
+
+#### Scenario: Default shows all years
+- **WHEN** the page loads
+- **THEN** the year filter defaults to all years
+- **AND** all entries remain visible unless filtered by search or tags
+
+#### Scenario: Selecting a year filters entries
+- **WHEN** the user selects `2026` in the year filter
+- **THEN** only entries whose `date` starts with `2026` are displayed
+
+#### Scenario: Year combines with tag and search filters
+- **WHEN** the user selects a year, activates a tag, and enters a search term
+- **THEN** the displayed entries match all active filters
+
+#### Scenario: Clearing the year filter
+- **WHEN** the user selects the all-years option
+- **THEN** year filtering is removed while other active filters remain applied
+
+#### Scenario: Entries without valid dates
+- **WHEN** an entry has an empty or malformed `date`
+- **THEN** it does not contribute a year option
+- **AND** it is visible under all-years mode
+- **AND** it is hidden when a specific year is selected
@@ -0,0 +1,25 @@
+## 1. OpenSpec 产物
+
+- [x] 1.1 创建 `add-year-filter` 变更提案
+- [x] 1.2 编写年份筛选设计说明
+- [x] 1.3 编写年份筛选 spec
+
+## 2. 前端交互
+
+- [x] 2.1 在页面中增加年份筛选控件
+- [x] 2.2 从 `ENTRIES[].date` 构建年份选项
+- [x] 2.3 将年份筛选并入 `applyFilters()`
+- [x] 2.4 确保年份、标签、搜索组合生效
+
+## 3. 生成脚本
+
+- [x] 3.1 修改 `scripts/update-knowledge-index.sh` 中的 HTML 模板
+- [x] 3.2 重新生成 `knowledge-index.html`
+
+## 4. 验证与归档
+
+- [x] 4.1 验证 HTML 包含年份筛选控件
+- [x] 4.2 验证生成脚本能成功重建页面
+- [x] 4.3 将结果归档到 `devflow/projects/`
+
+