Reorganize workspace and archive skill artifacts

This commit is contained in:
zhuyongxin
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
+25
View File
@@ -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/`
@@ -0,0 +1,46 @@
## Context
当前知识索引页面是由 `scripts/update-knowledge-index.sh` 生成的单文件静态 HTML。过滤状态分散在三个 UI 来源:
- `#search-input`:全文搜索词。
- `.tag-badge.active`:激活标签筛选。
- `#year-filter`:年份筛选。
过滤统一在 `applyFilters()` 中执行。上一轮年份筛选设计已经确认:生成脚本是模板真理源,不能只修改生成后的 `knowledge-index.html`。
## Design
新增一个清空筛选按钮,放在搜索框下方的筛选行中,与年份筛选同级。
点击按钮时执行 `clearFilters()`:
1. 将 `#search-input.value` 置空。
2. 将 `#year-filter.value` 置空。
3. 移除所有 `.tag-badge.active`。
4. 调用 `applyFilters()` 重新渲染列表。
`clearFilters()` 是统一清空入口。未来新增任何筛选器时,必须同时接入 `applyFilters()` 和 `clearFilters()`,避免“能筛选但不能一键清空”的状态漂移。
## OpenSpec Alignment
- 执行入口仍是 OpenSpec tasks/specs。
- devflow 上下文只用于确认现有过滤模型和生成脚本真理源。
- Phase 2 已确认采用“未来扩展”语义:清空按钮应清除所有当前支持的筛选器,未来新增筛选器也必须接入统一 `clearFilters()`。
## Edge Cases
- 没有筛选条件时点击:保持全部条目展示,不报错。
- 没有条目时点击:保持空状态,不报错。
- 标签过滤由多个 active badge 组成:必须全部取消。
- 清空后搜索高亮应消失,因为搜索词为空。
## Validation
- 静态验证:HTML 中存在 `clear-filters` 按钮和 `clearFilters()` 函数。
- 脚本验证:`scripts/update-knowledge-index.sh` 能重建 `knowledge-index.html`。
- 浏览器/人工验证:输入搜索词、选择年份、点击标签后,点击“清空筛选”恢复全部条目。
## Architecture Review
输入是搜索框、年份下拉框和标签 badge 的 UI 状态;处理入口是 `clearFilters()` 清空状态后调用 `applyFilters()`;输出是重新渲染后的完整条目列表。主要架构风险是未来新增筛选器时只接入 `applyFilters()`,忘记接入 `clearFilters()`,因此 `clearFilters()` 必须被记录为统一清空入口。实现必须改 `scripts/update-knowledge-index.sh`,再重建 `knowledge-index.html`,避免生成物和模板漂移。
@@ -0,0 +1,32 @@
## Why
知识库索引已经支持搜索、标签筛选和年份筛选。多个筛选条件可以组合生效,但用户清空条件时需要分别清空搜索框、取消所有激活标签、将年份切回“全部年份”。随着筛选维度增加,缺少“一键清空所有筛选”会让用户难以快速回到完整列表。
## What Changes
- 在 `knowledge-index.html` 中新增“清空筛选”按钮。
- 点击按钮时同时清空:搜索词、激活标签、年份筛选。
- 清空后重新渲染全部知识条目。
- 没有任何筛选条件时,按钮可以保留可点击,点击后保持全部条目展示。
- 更新 `scripts/update-knowledge-index.sh`,确保重建索引后按钮功能不会丢失。
## Devflow Context Used
- `devflow/glossary/CONTEXT.md` 定义了“索引面板”和“年份筛选”。
- `devflow/projects/2026-05-19-add-year-filter/add-year-filter-design.md` 明确 `applyFilters()` 是合并年份、标签、搜索过滤的单一入口。
- `devflow/projects/2026-05-19-add-year-filter/add-year-filter-acceptance.md` 记录了生成脚本是页面真理源,因此必须修改 `scripts/update-knowledge-index.sh` 并重建 `knowledge-index.html`。
## Capabilities
### New Capabilities
- `knowledge-filtering`: 用户可以一键清空搜索、标签和年份筛选,恢复完整知识条目列表。
### Modified Capabilities
- `knowledge-index-panel`: 页面在搜索/筛选区域增加“清空筛选”操作。
## Impact
- 修改 `scripts/update-knowledge-index.sh` 的 HTML 模板、样式和前端 JS。
- 重新生成 `knowledge-index.html`。
- 不修改任何 `knowledge_*/` 内容。
- 不引入外部依赖。
@@ -0,0 +1,33 @@
## ADDED Requirements
### Requirement: Clear all active filters
The knowledge index SHALL provide a control that clears all currently supported filtering state and restores the full entry list. Future filters added to the index SHALL be wired into the same clear-filters behavior.
#### Scenario: Clearing all currently supported filters
- **WHEN** the user has entered a search term
- **AND** selected a year
- **AND** activated one or more tag filters
- **WHEN** the user clicks the clear filters control
- **THEN** the search input is empty
- **AND** the year filter is set to all years
- **AND** no tag badge is active
- **AND** all entries are displayed again
#### Scenario: Clicking clear when no filters are active
- **WHEN** no search, year, or tag filter is active
- **WHEN** the user clicks the clear filters control
- **THEN** all entries remain displayed
- **AND** no error is shown
#### Scenario: Clearing removes search highlighting
- **WHEN** search highlighting is visible because of a search term
- **WHEN** the user clicks the clear filters control
- **THEN** search highlighting is removed from rendered entries
#### Scenario: Empty index remains stable
- **WHEN** the index has no entries
- **WHEN** the user clicks the clear filters control
- **THEN** the empty state remains visible
- **AND** no error is shown
@@ -0,0 +1,25 @@
## 1. OpenSpec 产物
- [x] 1.1 创建 `add-clear-filters` 变更提案
- [x] 1.2 编写清空筛选设计说明
- [x] 1.3 编写清空筛选 spec
## 2. 前端交互
- [x] 2.1 在筛选区域增加“清空筛选”按钮
- [x] 2.2 实现 `clearFilters()`,清空搜索、年份和标签激活状态
- [x] 2.3 将按钮点击绑定到 `clearFilters()`
- [x] 2.4 确保清空后调用 `applyFilters()` 恢复完整列表
## 3. 生成脚本
- [x] 3.1 修改 `scripts/update-knowledge-index.sh` 中的 HTML 模板、样式和 JS
- [x] 3.2 重新生成 `knowledge-index.html`
## 4. 验证与归档
- [x] 4.1 静态验证 HTML 包含按钮和函数
- [x] 4.2 脚本验证生成脚本能成功重建页面
- [ ] 4.3 浏览器/人工验证组合筛选后可一键清空
- [x] 4.4 将结果回填到 `devflow/projects/`
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-05-18
@@ -0,0 +1,58 @@
## Context
github-learn 是个人知识学习仓库。`/knowledge-absorber` 技能学习后,知识条目以 `knowledge_YYYYMMDD_Title/` 命名,当前集中存放在 `knowledge/entries/`。每个条目包含同名 `.md` 源文件和 `.html` 渲染页。
**约束**:
- Windows 11,Git Bash 可用。
- `knowledge-index.html` 放在项目根目录,浏览器直接打开。
- 零外部依赖(无 npm、无 CDN、无服务器)。
- 生成脚本是索引页面真理源;不要只手改生成后的 HTML。
## Goals / Non-Goals
**Goals:**
- 自动发现 `knowledge/entries/knowledge_YYYYMMDD_Title/` 文件夹。
- 从 `.md` 文件的 YAML frontmatter 解析元数据(title、author、tags、date)。
- 为每个条目生成可点击链接,跳转到对应条目的 `.html` 文件。
- 支持全文搜索、标签筛选、年份筛选和清空筛选。
- 保持单文件静态索引页面,不引入运行时服务。
**Non-Goals:**
- 不修改任何现有 knowledge 条目内容。
- 不做云端同步或数据库存储。
- 不实现编辑功能。
- 不支持分页(初期 < 50 条目)。
## Decisions
### D1: 目录收纳 — knowledge/entries 作为知识条目根
**选择**:知识条目从项目根目录迁移到 `knowledge/entries/`,保留原有 `knowledge_YYYYMMDD_Title/` 命名约定。
**理由**:根目录同时承载 OpenSpec、devflow、skills、验证沙箱和知识条目。把知识条目集中到 `knowledge/entries/` 能降低根目录噪音,同时不破坏目录名作为日期和 slug 真理源的 ADR。
### D2: 索引生成 — Bash 脚本预生成 ENTRIES
**选择**:`scripts/update-knowledge-index.sh` 扫描本地目录、解析 Markdown frontmatter 和正文,并把结果内联进 `knowledge-index.html` 的 `ENTRIES` 数组。
**理由**:浏览器无法可靠枚举本地目录;用脚本预生成数据避免本地 `fetch()` 和 CORS 问题,也保持最终页面零运行时依赖。
### D3: 向后兼容 — 找不到 knowledge/entries 时回退根目录
**选择**:脚本优先扫描 `knowledge/entries/knowledge_*/`;如果 `knowledge/entries/` 不存在,则回退扫描项目根目录的 `knowledge_*/`。
**理由**:兼容旧项目结构和迁移中状态。
### D4: 条目链接 — 存储相对路径
**选择**:生成时为每个条目写入相对项目根的 `path` 字段,前端用 `path/<dirname>.html` 构造链接。
**理由**:条目目录不再在根目录,仅靠 slug 无法定位文件;相对路径能支持后续进一步分组。
## Risks / Trade-offs
| Risk | Impact | Mitigation |
| --- | --- | --- |
| `/knowledge-absorber` 仍输出到根目录 | 新条目不会进入整理后的目录 | 脚本有根目录 fallback;后续应更新 knowledge-absorber 输出约定 |
| 移动目录后旧文档引用过期 | 历史文档路径不准确 | 保留历史语境;当前 glossary、OpenSpec 和 README 以新结构为准 |
| 只修改生成后的 HTML | 下次重建丢失功能 | 所有页面功能必须先改 `scripts/update-knowledge-index.sh` |
@@ -0,0 +1,28 @@
## Why
每次用 `/knowledge-absorber` 学习都会生成 `knowledge_YYYYMMDD_Title/` 文件夹。当前仓库将这些条目集中在 `knowledge/entries/`,但仍需要一个跨条目的索引页面,避免靠手动翻目录查找历史学习内容。随着知识条目增长(预计每月 5-10 个),搜索成本线性上升。需要一个人工可读的、零运行时依赖的索引面板。
## What Changes
- 新增 `knowledge-index.html`,放置在项目根目录,浏览器直接打开即可使用
- 自动扫描 `knowledge/entries/knowledge_*/` 目录,从 .md 文件的 YAML frontmatter 提取元数据(title、date、tags)
- 按标签自动关联——同一 tag 出现于不同条目时显示"相关内容"
- 全文搜索——输入关键词实时过滤所有知识条目
- 纯静态 HTML/CSS/JS,零外部依赖,不依赖任何服务器或构建工具
## Capabilities
### New Capabilities
- `knowledge-indexing`: 自动发现并解析 `knowledge/entries/knowledge_*/` 目录,提取 YAML frontmatter 元数据
- `knowledge-search`: 全文搜索——输入关键词,在所有知识条目的正文中检索并高亮匹配项
- `knowledge-linking`: 基于标签的关联图谱——点击标签显示所有共用该标签的知识条目
### Modified Capabilities
<!-- 没有已有 spec 需要修改 -->
## Impact
- 项目根目录新增 `knowledge-index.html`(无关现有文件结构)
- 不修改任何现有 `knowledge/entries/knowledge_*/` 目录或 .md 文件
- 不影响 `.claude/skills/` 中的任何技能
- 无 API 调用,无外部依赖
@@ -0,0 +1,39 @@
## ADDED Requirements
### Requirement: Knowledge entry discovery
The system SHALL scan all directories matching the pattern `knowledge/entries/knowledge_YYYYMMDD_Title/` and extract metadata from each entry's `.md` file.
If `knowledge/entries/` does not exist, the system SHALL fall back to scanning `knowledge_YYYYMMDD_Title/` directories in the project root for backward compatibility.
Metadata fields to extract from YAML frontmatter:
- `title` (required) — entry title
- `author` (optional) — author name
- `date` (optional) — creation date from directory name (YYYYMMDD)
- `tags` (optional) — array of tags
#### Scenario: Valid knowledge directory with complete frontmatter
- **WHEN** a directory `knowledge/entries/knowledge_20260518_mattpocock_skills/` contains `knowledge_20260518_mattpocock_skills.md` with valid YAML frontmatter including title, author, date, and tags
- **THEN** the system extracts all metadata fields and displays them in the index
#### Scenario: Knowledge directory with minimal frontmatter
- **WHEN** a knowledge directory has a `.md` file whose frontmatter contains only `title` (no tags, no author)
- **THEN** the system extracts the title and treats tags as an empty array
#### Scenario: Missing or malformed YAML frontmatter
- **WHEN** a knowledge directory's `.md` file has no YAML frontmatter or the frontmatter is malformed
- **THEN** the system SHALL display the entry using the directory name as a fallback title, with "unknown" date and no tags
#### Scenario: Multiple knowledge directories present
- **WHEN** the project contains 10 knowledge directories
- **THEN** the system SHALL display all 10 entries sorted by date descending
### Requirement: Manifest-based file discovery
The system SHALL generate an inline JavaScript entries array from the local filesystem at build time.
#### Scenario: Entries contain valid paths
- **WHEN** the generated entries array contains paths such as `knowledge/entries/knowledge_20260417_Waza`
- **THEN** the system SHALL render each entry and link its title to the corresponding `.html` file
#### Scenario: Backward-compatible root directory scan
- **WHEN** `knowledge/entries/` does not exist and root-level `knowledge_YYYYMMDD_Title/` directories exist
- **THEN** the system SHALL scan root-level knowledge directories and render them normally
@@ -0,0 +1,35 @@
## ADDED Requirements
### Requirement: Tag-based related entries
The system SHALL display a list of all unique tags across all knowledge entries. When a user clicks a tag, the system SHALL show only the entries that have that tag, and within each displayed entry, highlight the clicked tag.
#### Scenario: Clicking a tag filters entries
- **WHEN** user clicks the "Claude Code" tag
- **THEN** only entries tagged with "Claude Code" are displayed, and the tag is visibly active/selected
#### Scenario: Clicking the same tag again deselects
- **WHEN** user clicks an already-selected tag
- **THEN** the tag filter is removed and all entries are displayed again
#### Scenario: Entry has no tags
- **WHEN** a knowledge entry has no tags in its YAML frontmatter
- **THEN** the entry is displayed without any tag badges and is not matched by any tag filter click
#### Scenario: Multiple entries share a tag
- **WHEN** two or more entries share the same tag
- **THEN** clicking that tag shows all matching entries simultaneously
### Requirement: Related entries section
For each knowledge entry, the system SHALL display a "相关内容" (Related Content) section showing links to other entries that share at least one tag with the current entry.
#### Scenario: Entry has related entries
- **WHEN** entry A has tags ["Claude Code", "TypeScript"] and entry B has tags ["Claude Code", "React"]
- **THEN** under entry A, entry B is shown as related content (matching on "Claude Code")
#### Scenario: Entry has no related entries
- **WHEN** an entry's tags do not match any other entry's tags
- **THEN** no "相关内容" section is displayed for that entry
#### Scenario: Entry has no tags
- **WHEN** an entry has an empty tags array
- **THEN** no "相关内容" section is displayed and the entry is not included in any other entry's related content
@@ -0,0 +1,39 @@
## ADDED Requirements
### Requirement: Full-text search
The system SHALL provide a text input that filters knowledge entries in real-time as the user types. Filtering SHALL match against both metadata (title, tags) and the full body text of each knowledge entry.
#### Scenario: Search matches entry title
- **WHEN** user types "matt" in the search input
- **THEN** only entries whose title or body contains "matt" (case-insensitive) are displayed
#### Scenario: Search matches entry body text
- **WHEN** user types "三层加载" in the search input
- **THEN** all entries whose body text contains "三层加载" are displayed
#### Scenario: Search matches tag
- **WHEN** user types "Claude Code" in the search input
- **THEN** all entries tagged with "Claude Code" are displayed, along with entries mentioning it in body text
#### Scenario: No results found
- **WHEN** user types a keyword that matches no entry
- **THEN** the system SHALL display a "没有找到相关条目" (no results) message
#### Scenario: Clearing search restores all entries
- **WHEN** user clears the search input
- **THEN** all entries are displayed again in their original order (date descending)
#### Scenario: Search is case-insensitive
- **WHEN** user types "CLAUDE" or "claude" or "Claude"
- **THEN** the system SHALL return the same results regardless of case
### Requirement: Highlight matched text
The system SHALL visually highlight the portion of text that matched the search query in each displayed result.
#### Scenario: Single word match
- **WHEN** user searches for "skill" and an entry title is "Matt Pocock Skills"
- **THEN** the word "Skills" in the title is visually highlighted
#### Scenario: Multi-word query
- **WHEN** user searches for "ai agent" (two words)
- **THEN** entries containing both words are prioritized and matched text is highlighted
@@ -0,0 +1,26 @@
## 1. bash 索引生成脚本
- [x] 1.1 创建 `scripts/update-knowledge-index.sh`,实现 `knowledge/entries/knowledge_*/` 自动扫描,并兼容根目录 `knowledge_*/`
- [x] 1.2 实现从目录名提取 date(YYYYMMDD)和 slug
- [x] 1.3 实现从 .md 文件提取 YAML frontmatter(title、tags、author)和正文
- [x] 1.4 实现降级逻辑:YAML 解析失败时用 slug 作 title,空 tags 处理
- [x] 1.5 将提取的数据生成为 JS 数组字面量,包含条目相对路径,并注入 HTML 模板
## 2. HTML 模板和样式
- [x] 2.1 创建 HTML 模板结构(header、搜索栏、条目卡片区、标签云区、footer、`__DATA_PLACEHOLDER__` 占位符)
- [x] 2.2 编写 CSS 样式(响应式、卡片设计、搜索高亮 `<mark>`、标签徽章、中文优化字体)
## 3. 前端 JS 交互逻辑
- [x] 3.1 实现实时搜索过滤(匹配 title、tags、body,大小写不敏感)
- [x] 3.2 实现搜索高亮和"无结果"提示
- [x] 3.3 实现标签云渲染和点击过滤(选中高亮、再点取消)
- [x] 3.4 实现"相关内容"推荐(基于共享标签的条目间关联)
- [x] 3.5 实现条目标题链接,指向 `knowledge/entries/<entry>/<entry>.html`
## 4. 集成和测试
- [x] 4.1 用现有 2 个 knowledge 条目运行脚本,生成 knowledge-index.html
- [x] 4.2 测试边界情况:空 tags、YAML 最小 frontmatter、缺失目录
- [x] 4.3 在浏览器中验证搜索、标签过滤、相关推荐功能