Reorganize workspace and archive skill artifacts

devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md

@@ -0,0 +1,39 @@
+# ADR-001: 目录名作为日期和标题的真理源
+
+**状态**：已接受  
+**日期**：2026-05-18
+
+## 背景
+
+知识吸收器输出目录遵循 `knowledge_YYYYMMDD_Title/` 命名约定。目录内的 `.md` 文件包含 YAML frontmatter，其中也有 `date`/`created` 和 `title` 字段，但实际使用中发现字段名不一致（`date` vs `created`）和格式差异。
+
+索引重建脚本需要确定日期和标题的权威来源。
+
+## 决策
+
+**日期和短标识符 (slug) 的真理源是目录名。显示标题、tags、author 的真理源是 YAML frontmatter。**
+
+- 日期从目录名的 `YYYYMMDD` 部分提取
+- 短标识符从目录名的 `Slug` 部分提取（用于文件路径构建，不用于显示）
+- 显示标题从 YAML frontmatter 的 `title` 字段提取
+- `tags` 和 `author` 从 YAML frontmatter 提取
+
+## 替代方案
+
+| 方案 | 被拒原因 |
+|------|---------|
+| YAML 全优先 | 字段名不一致（date vs created） |
+| 目录名全优先 | 标题中的语义信息在下划线转空格后丢失（如 `mattpocock_skills` → `mattpocock skills`，实际标题更长更精确）
+
+## 后果
+
+### 正面
+- 索引脚本不需要处理日期字段名变体（date vs created）
+- 目录名是可见的、可审计的——与 `ls` 输出完全一致
+- bash 用 glob 匹配 `knowledge_*` 目录，天然获取了日期和 slug
+- 显示标题从 YAML 取，支持完整的、精确的标题文本（含标点、中文）
+
+### 负面
+- 索引脚本需要解析 YAML frontmatter（复杂度比仅取目录名高）
+- 如果目录被重命名，slug 会变化但显示标题不受影响（可接受的行为）
+- 知识吸收器 skill 必须严格遵守 `knowledge_YYYYMMDD_Slug` 命名约定

devflow/projects/2026-05-18-knowledge-index-panel/knowledge-index-panel-prd.md

@@ -0,0 +1,57 @@
+# PRD: 知识库索引面板 (Knowledge Index Panel)
+
+## Problem Statement
+
+用户每次用 `/knowledge-absorber` 学习后，会在项目根目录生成 `knowledge_YYYYMMDD_Title/` 文件夹。目前有 2 个知识条目，预计每月增长 5-10 个。所有条目散落在根目录，没有跨条目的导航或搜索能力。想找之前学过的内容只能手动翻目录，搜索成本随条目数线性上升。
+
+## Solution
+
+在项目根目录生成一个 **纯静态的 `knowledge-index.html`**，浏览器直接打开即可使用。它能自动发现所有 knowledge 条目，提供标签关联和全文搜索。不需要任何服务器、数据库或外部依赖。
+
+## User Stories
+
+1. As a 学习者, I want to see all my knowledge entries on one page with dates, so that I can quickly find what I studied and when
+2. As a 学习者, I want to search across all knowledge entries by keyword, so that I can find "that thing about Redis" in 2 seconds instead of manually opening 10 folders
+3. As a 学习者, I want to click a tag like "Claude Code" and see all related entries, so that I can review interconnected topics
+4. As a 学习者, I want the index to auto-discover new knowledge entries, so that I don't need to manually update anything after running `/knowledge-absorber`
+5. As a 学习者, I want the page to work offline by just double-clicking the HTML file, so that I can use it without internet or any setup
+6. As a 学习者, I want to see which entries are related to each other via shared tags, so that I can discover connections between topics I've studied
+7. As a 学习者, I want the search to highlight matching text, so that I can see at a glance why an entry matched my query
+8. As a 学习者, I want to see a count of entries per tag, so that I know which topics I've studied most
+
+## Implementation Decisions
+
+- **Single HTML file**: All CSS and JS inlined in `knowledge-index.html`. No external files or CDN dependencies
+- **Manifest-based discovery**: A JavaScript array inside the HTML lists all known knowledge directory names. Browser security sandbox prevents dynamic directory listing via `fetch()`
+- **YAML frontmatter parsing**: Regex-based extraction from `.md` files. Simple key:value parsing only — no full YAML spec support
+- **Client-side search**: All `.md` content loaded into memory at page init. Real-time filtering with `String.includes()`, case-insensitive. `<mark>` tags for highlighting
+- **Tag system**: In-memory `Map<tag, entry[]>` built at load time. Click to filter, click again to deselect
+- **Related Content**: Computed from shared tags, displayed per-entry
+- **No pagination**: Designed for < 50 entries. Full list rendered at once
+- **UTF-8 encoding**: All files assumed UTF-8. `fetch()` handles encoding detection
+
+## Testing Decisions
+
+- **What makes a good test**: Test external behavior — "user types keyword → correct entries appear" — not internal state
+- **Test with real data**: Use existing 2 knowledge entries (`knowledge_20260417_Waza`, `knowledge_20260518_mattpocock_skills`) as test fixtures
+- **Edge cases to verify**:
+  - Missing directory (manifest lists a name that doesn't exist) → skip gracefully
+  - Malformed YAML → display directory name as fallback
+  - Empty tags array → no tag badges rendered
+  - No search results → show "没有找到相关条目" message
+  - Browser CORS when opened via `file://` protocol → document the workaround
+
+## Out of Scope
+
+- Google Drive / cloud sync
+- Editing knowledge entries
+- Full YAML 1.2 spec compliance
+- Pagination or virtual scrolling
+- Fuse.js or other fuzzy search libraries (keep it zero-dependency)
+- Dark mode toggle (can add later, not in v1)
+
+## Further Notes
+
+- The manifest maintenance problem (adding new entries) can be solved in a future iteration by modifying the `/knowledge-absorber` skill to auto-append to the manifest array
+- The `file://` protocol CORS limitation on Chrome means users may need to serve via `python -m http.server` or similar for full functionality
+- Tag counts provide a natural "learning heatmap" — most-studied topics bubble to the top

devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-acceptance.md

@@ -0,0 +1,70 @@
+# 清空所有筛选验收
+
+## 结果
+
+部分接受：实现和自动化/静态验证已完成，浏览器人工点击验证未运行。
+
+## 验证
+
+### 静态验证
+
+- 命令/检查：`rg -n -F "function clearFilters" knowledge-index.html scripts/update-knowledge-index.sh`
+- 结果：通过
+- 备注：生成脚本和生成后的 HTML 均包含 `clearFilters()`。
+
+- 命令/检查：`rg -n -F "bindClearFilters" knowledge-index.html scripts/update-knowledge-index.sh`
+- 结果：通过
+- 备注：初始化流程绑定清空按钮点击事件。
+
+- 命令/检查：`rg -n -F "tag-badge.active" knowledge-index.html scripts/update-knowledge-index.sh`
+- 结果：通过
+- 备注：`clearFilters()` 移除所有 active 标签。
+
+### 脚本验证
+
+- 命令：`C:\Program Files\Git\bin\bash.exe -n scripts/update-knowledge-index.sh`
+- 结果：通过
+- 备注：脚本语法检查成功。
+
+- 命令：`C:\Program Files\Git\bin\bash.exe scripts/update-knowledge-index.sh`
+- 结果：通过
+- 备注：成功扫描 3 个 `knowledge_*/` 目录并重新生成 `knowledge-index.html`。
+
+### 浏览器/人工验证
+
+- 步骤：输入搜索词，选择年份，点击一个标签，再点击“清空筛选”。
+- 结果：未运行
+- 备注：当前未打开浏览器做人工点击验证；建议用户本地打开 `knowledge-index.html` 补验。
+
+## 已完成范围
+
+- 新增“清空筛选”按钮。
+- 新增 `clearFilters()` 统一清空入口。
+- 清空当前支持的搜索、年份、标签筛选。
+- 清空后调用 `applyFilters()` 恢复完整列表。
+- 已在 OpenSpec 中记录未来新增筛选器必须接入统一清空行为。
+
+## 已知限制
+
+- 未做浏览器人工点击验证。
+- 没有新增 URL query、保存筛选状态或撤销清空功能。
+
+## Bug 修复和诊断
+
+- 问题：PowerShell `Set-Content -Encoding UTF8` 会把脚本写成带 BOM，Git Bash 执行 shebang 时可能报 `#!/usr/bin/env` 路径异常。
+- 诊断：检查首字节发现 BOM 后，用无 BOM UTF-8 重写脚本。
+- 回归验证：去 BOM 后 `bash -n` 和完整生成脚本均通过。
+
+## 交接
+
+- 下一步：浏览器人工验证后，可确认是否 archive `add-clear-filters` OpenSpec change。
+- OpenSpec 归档确认：用户已确认归档，已移动到 `openspec/changes/archive/2026-05-19-add-clear-filters/`。
+
+## OpenSpec Archive
+
+- Change：`add-clear-filters`
+- Schema：`spec-driven`
+- Archived to：`openspec/changes/archive/2026-05-19-add-clear-filters/`
+- Specs：未同步；当前仓库没有 `openspec/specs/` 主规格目录可同步。
+- Artifacts：`proposal`、`design`、`specs`、`tasks` 均为 done。
+- Tasks：无未完成 checkbox。

devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-alignment.md

@@ -0,0 +1,24 @@
+# 清空所有筛选：PRD / Devflow / OpenSpec 对齐记录
+
+## 对齐结论
+
+当前 PRD、devflow 上下文和 OpenSpec 产物基本一致，可以进入 Phase 2 澄清。
+
+## 已对齐项
+
+| 项目 | 结论 | 依据 |
+| --- | --- | --- |
+| 页面真理源 | 必须修改 `scripts/update-knowledge-index.sh` 并重建 HTML | `add-year-filter-acceptance.md` 记录生成脚本是页面真理源 |
+| 过滤入口 | `applyFilters()` 是搜索、标签、年份的统一过滤入口 | `add-year-filter-design.md` 模块地图 |
+| 清空范围 | 当前 OpenSpec 覆盖搜索、年份、标签三类过滤 | `add-clear-filters/spec.md` |
+| 验收方式 | 静态验证 + 脚本验证 + 浏览器/人工验证 | `add-clear-filters/design.md` |
+
+## 待确认项
+
+| 问题 | 类型 | 是否阻塞实现 |
+| --- | --- | --- |
+| “清空所有筛选”是否应定义为未来新增筛选器也必须接入统一清空入口？ | user-interview | 不阻塞当前实现，但影响 spec 表述和设计约束 |
+
+## OpenSpec 修正建议
+
+如果用户确认要面向未来筛选器，建议把 spec 文案从“search, year, tag filters”扩展为“all currently supported filters”，并在 design 中明确未来新增过滤器必须接入 `clearFilters()`。

devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-clarifications.md

@@ -0,0 +1,18 @@
+# 清空所有筛选：Phase 2 澄清记录
+
+## 决策摘要
+
+用户选择“未来扩展”语义：清空所有筛选不仅清空当前搜索、年份、标签三类筛选，也定义为未来新增筛选器必须接入统一 `clearFilters()`。
+
+## 澄清记录
+
+| 维度 | 模式 | 问题 | 证据 / 用户反馈 | 结论 | 是否回写 OpenSpec |
+| --- | --- | --- | --- | --- | --- |
+| 术语 | evidence-driven | 应使用“筛选 / filter”还是其它术语？ | 页面已有 `applyFilters()`，年份筛选术语已在 glossary 中存在 | 使用“筛选 / filter” | 是 |
+| 边界 | user-interview | 清空范围只包括当前筛选器，还是未来筛选器也必须接入？ | 用户确认选择“未来扩展” | 未来新增筛选器必须接入 `clearFilters()` | 是 |
+| 验收 | evidence-driven | 如何证明清空完成？ | OpenSpec spec 已覆盖搜索词、年份、标签和高亮清除 | 清空后无搜索词、全部年份、无 active 标签、列表恢复 | 是 |
+
+## OpenSpec 回写
+
+- `openspec/changes/add-clear-filters/specs/knowledge-filtering/spec.md` 已改为 “all currently supported filtering state”，并要求未来筛选器接入同一清空行为。
+- `openspec/changes/add-clear-filters/design.md` 已补充 `clearFilters()` 是统一清空入口。

devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-design.md

@@ -0,0 +1,24 @@
+# 清空所有筛选设计
+
+## 架构摘要
+
+输入是搜索框、年份下拉框和标签 badge 的 UI 状态；处理入口是 `clearFilters()` 清空所有当前支持的筛选器后调用 `applyFilters()`；输出是重新渲染后的完整知识条目列表。
+
+## 关键决策
+
+- `clearFilters()` 是统一清空入口。
+- 未来新增筛选器时，必须同时接入 `applyFilters()` 和 `clearFilters()`。
+- 实现必须修改 `scripts/update-knowledge-index.sh`，再重建 `knowledge-index.html`。
+
+## 模块地图
+
+| 模块 | 职责 | 备注 |
+| --- | --- | --- |
+| `scripts/update-knowledge-index.sh` | 生成 HTML、CSS、JS 模板 | 本次实现真理源 |
+| `knowledge-index.html` | 生成后的静态索引页面 | 由脚本重建 |
+| `clearFilters()` | 清空所有当前支持的筛选状态 | 新增统一清空入口 |
+| `applyFilters()` | 根据当前筛选状态重新过滤并渲染 | 现有统一过滤入口 |
+
+## 架构审计
+
+该功能是纯前端状态重置，不改变 `ENTRIES` 数据源、不影响 `knowledge_*/` 目录、不引入外部依赖。主要风险是未来新增筛选器时忘记接入 `clearFilters()`，因此 OpenSpec design/spec 已回写“未来筛选器必须接入统一清空行为”。另一个风险是只修改生成后的 HTML，因此 Phase 3 必须以 `scripts/update-knowledge-index.sh` 为修改入口。

devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-prd.md

@@ -0,0 +1,50 @@
+# 清空所有筛选 PRD
+
+## 问题陈述
+
+知识库索引已经支持搜索、标签筛选和年份筛选。用户组合多个筛选条件后，想回到完整列表时需要逐个清空搜索、取消标签、重置年份，操作成本随筛选维度增加而上升。
+
+## 解决方案
+
+在索引面板的筛选区域增加“清空筛选”按钮。点击后一次性清空当前所有筛选状态，并重新显示完整知识条目列表。
+
+## 用户故事
+
+1. 作为学习者，我希望一键清空搜索词，以便快速回到完整列表。
+2. 作为学习者，我希望一键取消所有激活标签，以便不用逐个点击标签。
+3. 作为学习者，我希望一键重置年份筛选，以便不用手动切回“全部年份”。
+4. 作为学习者，我希望清空后所有条目重新显示，以便重新开始浏览。
+5. 作为学习者，我希望没有筛选条件时点击按钮也不会报错，以便操作行为稳定。
+6. 作为学习者，我希望搜索高亮在清空后消失，以便页面状态与搜索框一致。
+7. 作为维护者，我希望功能写入生成脚本模板，以便重建 `knowledge-index.html` 后不会丢失。
+8. 作为维护者，我希望清空逻辑集中在一个函数中，以便未来新增筛选器时容易接入。
+
+## 实现决策
+
+- 决策：清空按钮放在搜索框下方的筛选行，与年份筛选同级。
+  - 原因：搜索、年份、标签都属于过滤器，按钮应靠近过滤控件。
+  - 影响：需要修改 HTML 模板和 CSS。
+- 决策：新增 `clearFilters()` 统一清空过滤状态。
+  - 原因：避免把清空逻辑散落在多个事件处理器中。
+  - 影响：未来新增筛选器时应接入该函数。
+- 决策：实现必须修改 `scripts/update-knowledge-index.sh`，再重建 `knowledge-index.html`。
+  - 原因：生成脚本是索引页面模板真理源。
+  - 影响：只改生成后的 HTML 不算完成。
+
+## 测试决策
+
+- 静态验证：检查生成后的 HTML 中存在按钮、`clearFilters()` 和事件绑定。
+- 脚本验证：运行生成脚本，确认能成功重建页面。
+- 浏览器/人工验证：组合搜索、年份、标签后点击“清空筛选”，确认所有条目恢复显示。
+
+## 非目标
+
+- 不新增保存筛选状态。
+- 不新增 URL query 参数同步。
+- 不新增“撤销清空”。
+- 不改变现有搜索、标签、年份筛选语义。
+
+## 补充说明
+
+- OpenSpec change：`openspec/changes/add-clear-filters/`
+- 本 PRD 是用户价值和验收口径说明；执行仍以 OpenSpec specs/tasks 为准。

devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-research.md

@@ -0,0 +1,23 @@
+# 清空所有筛选技术调研
+
+## 摘要
+
+- 变更原因：搜索、标签、年份筛选可以组合生效，但缺少一键恢复完整列表的入口。
+- 变更范围：新增清空筛选按钮、`clearFilters()`、按钮绑定，并更新生成脚本模板。
+- 主要技术方案：以 `clearFilters()` 作为统一清空入口，清空搜索、年份、标签状态后调用 `applyFilters()`。
+
+## 源产物
+
+- OpenSpec change: `openspec/changes/add-clear-filters/`
+- 关联 PRD: `add-clear-filters-prd.md`
+
+## 关键发现
+
+- `scripts/update-knowledge-index.sh` 是页面生成真理源，必须先改脚本再重建 `knowledge-index.html`。
+- 当前过滤状态来自 `#search-input`、`#year-filter`、`.tag-badge.active`。
+- `applyFilters()` 是现有统一过滤入口，`clearFilters()` 应清空状态后复用它。
+
+## 假设
+
+- “清空所有筛选”采用未来扩展语义：未来新增筛选器必须接入 `clearFilters()`。
+- 当前实现不需要新增状态管理或外部依赖。

devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-tasks.md

@@ -0,0 +1,20 @@
+# 清空所有筛选任务
+
+## 需求追踪
+
+| 需求 | 状态 | 备注 |
+| --- | --- | --- |
+| 清空搜索、年份、标签 | 已完成 | `clearFilters()` 清空三个当前支持的筛选状态 |
+| 清空后显示全部条目 | 已完成 | 清空后调用 `applyFilters()` |
+| 无筛选时点击不报错 | 已完成 | 函数使用元素存在性检查，重复点击保持全量状态 |
+| 清除搜索高亮 | 已完成 | 搜索词清空后重新渲染条目，不再调用高亮 |
+| 未来筛选器接入统一清空入口 | 已记录 | OpenSpec spec/design 已写入约束 |
+
+## 实现任务
+
+- [x] 在筛选区域增加“清空筛选”按钮。
+- [x] 实现 `clearFilters()`，清空搜索、年份和标签激活状态。
+- [x] 实现 `bindClearFilters()` 并绑定按钮点击。
+- [x] 清空后调用 `applyFilters()` 恢复列表。
+- [x] 修改 `scripts/update-knowledge-index.sh`。
+- [x] 重新生成 `knowledge-index.html`。

devflow/projects/2026-05-19-add-year-filter/add-year-filter-acceptance.md

@@ -0,0 +1,44 @@
+# 按年份筛选知识条目验收
+
+## 结果
+
+已接受。
+
+## 验证
+
+- 命令：`C:\Program Files\Git\bin\bash.exe -n scripts/update-knowledge-index.sh`
+- 结果：通过
+- 备注：需要提升权限运行；普通沙箱中 Git Bash 因 `Win32 error 5` 无法创建 signal pipe。
+
+- 命令：`C:\Program Files\Git\bin\bash.exe scripts/update-knowledge-index.sh`
+- 结果：通过
+- 备注：成功扫描 3 个 `knowledge_*/` 目录并重新生成 `knowledge-index.html`。
+
+- 命令：`rg -n "filter-row|year-filter|buildYearFilter|selectedYear|Year filter" knowledge-index.html`
+- 结果：通过
+- 备注：确认生成后的 HTML 包含年份控件、年份选项构建函数和过滤逻辑。
+
+## 已完成范围
+
+- 页面新增“年份”下拉筛选控件。
+- 年份选项从 `ENTRIES[].date` 自动提取并倒序排列。
+- 年份筛选与标签筛选、全文搜索组合生效。
+- 生成脚本已更新，重建页面后功能不会丢失。
+- `devflow/glossary/CONTEXT.md` 已新增“年份筛选 (Year Filter)”术语。
+
+## 已知限制
+
+- 当前只支持年份，不支持月份、日期范围或时间线视图。
+- 本次未做浏览器内手动点击验证；已做静态生成和代码路径验证。
+- 当前三个真实条目都在 2026 年，因此实际跨年份过滤需要未来新增其他年份条目后进一步人工验证。
+
+## Bug 修复和诊断
+
+- 问题：普通沙箱中运行 `bash` 或 Git Bash 失败，报 `Win32 error 5` / signal pipe 创建失败。
+- 诊断：这不是脚本语法错误，而是当前 Windows 沙箱对 MSYS/Git Bash 进程能力的限制；提升权限后 `bash -n` 和生成脚本均成功。
+- 回归验证：已用提升权限运行语法检查和完整生成流程。
+
+## 交接
+
+- 下一步：如需完成 OpenSpec 生命周期，可归档 `add-year-filter` change。
+- 建议：未来增加 2027 或其他年份条目后，在浏览器中手动确认下拉年份过滤的视觉行为。

devflow/projects/2026-05-19-add-year-filter/add-year-filter-design.md

@@ -0,0 +1,29 @@
+# 按年份筛选知识条目设计
+
+## 架构摘要
+
+输入是 `ENTRIES` 数组中的知识条目，处理过程是从 `date` 字段提取年份并维护一个全局年份筛选控件，输出是被年份、标签和搜索共同过滤后的条目列表。
+
+## Phase 2 澄清结论
+
+- 术语问题：使用“年份筛选 (Year Filter)”表示按 `YYYY` 过滤知识条目的全局过滤器；该术语已写入 `devflow/glossary/CONTEXT.md`。
+- 边界问题：本次只支持年份，不支持月份、时间线、日期范围或自定义排序。
+- 验收问题：选择某一年后，只有 `date` 以该年份开头的条目显示；选择“全部年份”后取消年份过滤；年份与搜索、标签取交集。
+
+## 关键决策
+
+- 年份从 `ENTRIES[].date.slice(0,4)` 派生，不新增数据字段。
+- 控件使用原生 `<select>`，避免引入依赖。
+- 缺失或异常日期不参与年份选项；在“全部年份”下保留显示，在指定年份下隐藏。
+
+## 模块地图
+
+| 模块 | 职责 | 备注 |
+| --- | --- | --- |
+| `scripts/update-knowledge-index.sh` | 生成 HTML 模板和数据数组 | 必须修改源模板，避免重建后丢功能 |
+| `knowledge-index.html` | 静态索引页面 | 由脚本重建 |
+| `applyFilters()` | 合并年份、标签、搜索过滤 | 保持单一过滤入口 |
+
+## 架构审计
+
+年份筛选是纯前端派生状态，不改变数据源、不影响 `knowledge_*/` 目录，也不引入外部依赖。主要风险是只改生成后的 HTML 而忘记改生成脚本，因此实现必须以 `scripts/update-knowledge-index.sh` 为真理源，再重建 `knowledge-index.html`。

devflow/projects/2026-05-19-add-year-filter/add-year-filter-prd.md

@@ -0,0 +1,50 @@
+# 按年份筛选知识条目 PRD
+
+## 问题陈述
+
+知识库索引已经支持全文搜索和标签筛选，但当知识条目跨越多个年份时，用户无法快速只查看某一年学习或沉淀的内容。
+
+## 解决方案
+
+在 `knowledge-index.html` 中增加一个年份筛选控件，从每个知识条目的 `date` 字段自动提取年份。用户可以选择全部年份或某个具体年份，筛选结果与现有搜索和标签过滤共同生效。
+
+## 用户故事
+
+1. 作为学习者，我希望按年份查看知识条目，以便回顾某一年学习过的内容。
+2. 作为学习者，我希望默认看到全部年份，以便页面加载行为不改变。
+3. 作为学习者，我希望年份筛选和搜索可以同时生效，以便在某一年范围内进一步搜索关键词。
+4. 作为学习者，我希望年份筛选和标签筛选可以同时生效，以便查看某一年某个主题下的内容。
+5. 作为学习者，我希望年份选项自动从已有条目生成，以便不需要手动维护年份列表。
+6. 作为学习者，我希望年份按倒序排列，以便最近年份更容易选择。
+7. 作为维护者，我希望功能写在生成脚本模板中，以便重新生成 `knowledge-index.html` 后功能不会丢失。
+8. 作为维护者，我希望缺失或异常日期不会破坏页面，以便旧数据或异常数据仍可在全部年份下显示。
+
+## 实现决策
+
+- 决策：年份来自 `ENTRIES[].date` 的前四位。
+  - 原因：现有生成脚本已经从目录名提取 `YYYYMMDD`，无需新增数据字段。
+  - 影响：只需修改前端模板和过滤逻辑。
+- 决策：年份筛选控件使用原生 `<select>`。
+  - 原因：实现简单、可访问性较好、无外部依赖。
+  - 影响：不引入新的 UI 库或复杂状态管理。
+- 决策：年份筛选与标签、搜索取交集。
+  - 原因：符合用户对多个过滤条件同时生效的直觉。
+  - 影响：`applyFilters()` 需要统一读取三类过滤状态。
+
+## 测试决策
+
+- 好测试应验证外部行为：选择年份后列表变化，而不是测试内部函数实现。
+- 必须覆盖：默认全部年份、选择具体年份、年份 + 标签 + 搜索组合过滤、重建页面后功能保留。
+- 不测试：复杂日期解析、时区、非 `YYYYMMDD` 的完整兼容性；异常日期只需要不破坏页面。
+
+## 非目标
+
+- 不增加月份筛选。
+- 不增加时间线视图。
+- 不改变 `knowledge_YYYYMMDD_Slug` 命名约定。
+- 不引入外部依赖或构建工具。
+
+## 补充说明
+
+- 本功能是 `knowledge-index-panel` 的增量增强。
+- slug 使用 `add-year-filter`。

devflow/projects/2026-05-19-add-year-filter/add-year-filter-research.md

@@ -0,0 +1,24 @@
+# 按年份筛选知识条目技术调研
+
+## 摘要
+
+- 变更原因：知识库索引已有搜索和标签过滤，但缺少按年份回顾知识条目的入口。
+- 变更范围：新增年份筛选 UI、年份选项生成逻辑、过滤组合逻辑，并更新生成脚本模板。
+- 主要技术方案：从 `ENTRIES[].date` 的前四位派生年份，使用原生 `<select>` 作为全局过滤控件，在 `applyFilters()` 中与标签和搜索取交集。
+
+## 源产物
+
+- OpenSpec change: `openspec/changes/add-year-filter/`
+- 关联 PRD: `add-year-filter-prd.md`
+
+## 关键发现
+
+- `knowledge-index.html` 由 `scripts/update-knowledge-index.sh` 生成，必须修改生成脚本而不是只改生成后的 HTML。
+- 现有数据项已经包含 `date: YYYYMMDD`，不需要新增数据字段或修改知识条目目录。
+- 当前已有三个知识条目，日期均为 2026 年，可用于验证年份控件和生成逻辑存在性。
+
+## 假设
+
+- 年份筛选使用 `YYYY` 粒度即可满足当前回顾需求：已通过需求边界确认。
+- 缺失或异常日期不参与具体年份筛选：已写入 OpenSpec spec。
+- 搜索、标签、年份过滤取交集：已作为验收标准写入 PRD 和 spec。

devflow/projects/2026-05-19-add-year-filter/add-year-filter-tasks.md

@@ -0,0 +1,20 @@
+# 按年份筛选知识条目任务
+
+## 需求追踪
+
+| 需求 | 状态 | 备注 |
+| --- | --- | --- |
+| 默认显示全部年份 | 已完成 | 页面加载后 `<select>` 默认为“全部年份” |
+| 选择年份后过滤条目 | 已完成 | `applyFilters()` 按 `date.slice(0,4)` 过滤 |
+| 年份与标签、搜索组合生效 | 已完成 | 年份、标签、搜索在同一过滤函数中取交集 |
+| 清除年份筛选 | 已完成 | 空 value 表示全部年份 |
+| 异常日期处理 | 已完成 | 异常日期不生成选项，指定年份时不匹配 |
+
+## 实现任务
+
+- [x] 创建 `openspec/changes/add-year-filter/` 变更产物。
+- [x] 在 `scripts/update-knowledge-index.sh` 中增加年份筛选样式和 HTML。
+- [x] 增加 `buildYearFilter()` 和 `bindYearFilter()`。
+- [x] 在 `applyFilters()` 中加入年份过滤。
+- [x] 重新生成 `knowledge-index.html`。
+- [x] 验证生成脚本和生成结果。

devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md

@@ -0,0 +1,116 @@
+# Dev Flow Skill 评估报告
+
+**日期**：2026-05-19  
+**对象**：`.claude/skills/dev-flow/SKILL.md`  
+**背景**：该 skill 基于 openspec 工作流，并融合 `to-prd`、`grill-with-docs`、`zoom-out`、`diagnose`、`tdd` 等开源 skill 思路，目标是形成一套从需求到实现再到知识沉淀的工程开发闭环。
+
+## 总体评价
+
+这套 `dev-flow` 的方向是正确的：它没有试图替代 openspec，而是在 openspec 的流程控制之上增加需求精化、架构审计、质量闭环和长期知识沉淀。
+
+最有价值的设计是 `devflow/` 产物聚合层：
+
+- `openspec/changes/` 负责机器可执行的变更工作区。
+- `devflow/projects/` 负责人类可回溯的项目档案。
+- `devflow/glossary/CONTEXT.md` 负责跨项目领域词汇。
+- `devflow/compound/` 负责沉淀可复用工程知识。
+
+目前最大的问题是：`SKILL.md` 更像一份设计说明书，而不是一份代理可以稳定执行的运行手册。它解释了很多理念，但缺少执行时必需的检查点、模板、分支规则和 fallback 策略。
+
+## 亮点
+
+1. **产物聚合层设计清晰**
+   - `devflow/projects/YYYY-MM-DD-{slug}/` 解决了 openspec archive 后上下文难以回溯的问题。
+   - 工具工作区和人类档案层分离，职责边界明确。
+
+2. **阶段顺序合理**
+   - Phase 0 → Phase 1 → Phase 1.5 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 的顺序能有效避免“需求没想清楚就开始编码”。
+
+3. **Phase 4 很有价值**
+   - 明确要求从 openspec 提炼 research、design、tasks、acceptance、ADR 和 compound knowledge。
+   - 这是区别于普通 openspec 流程和普通编码 skill 的核心优势。
+
+4. **grill-with-docs 融合方式正确**
+   - Phase 2 要求一次只问一个问题，并即时更新 `CONTEXT.md` / ADR。
+   - 这符合“边澄清边沉淀”的工作方式。
+
+5. **质量闭环意识强**
+   - Phase 3 明确要求 bug 不允许猜测式修复，必须走 diagnose 协议。
+   - TDD 被设计为可选增强，避免对所有任务强制套用重流程。
+
+## 主要问题
+
+1. **触发描述不够完整**
+   - 当前 `description` 说明了流程构成，但没有覆盖足够多的用户触发场景。
+   - 建议明确写入：当用户要从需求到实现、规划 feature、执行 openspec change、沉淀工程文档、规范化开发流程时使用。
+
+2. **Claude 工具耦合较强**
+   - `allowed-tools` 使用 Claude Code 风格工具名。
+   - 如果未来迁移到 Codex skill，这些工具名可能不适用。
+   - 建议把工具白名单保留给 Claude 版本，同时在正文中描述环境无关的 fallback 行为。
+
+3. **依赖安装状态不应写死**
+   - 依赖表中写了“✅ 已安装”，这对当前仓库成立，但复制到其他项目会误导。
+   - 应改成“启动时检查是否存在”，并区分 required、optional、fallback。
+
+4. **子 skill 调用方式不稳**
+   - 文档写“调用 Skill 工具启动 openspec-propose / openspec-apply-change”。
+   - 但不同代理环境未必支持直接调用 Skill 工具。
+   - 建议增加 fallback：如果不能直接调用，就读取对应 `SKILL.md` 并按其协议执行。
+
+5. **缺少初始化算法**
+   - 文档要求写入 `devflow/projects/YYYY-MM-DD-{slug}/`，但没有说明如何生成 slug、如何处理重名、如何创建目录骨架。
+
+6. **缺少模板**
+   - PRD、research、design、tasks、acceptance、CONTEXT、ADR、compound knowledge 都有路径要求，但没有最小模板。
+   - 这会导致代理每次输出格式不稳定。
+
+7. **quick 模式与约束存在冲突**
+   - `--quick` 说可以跳 Phase 1.5 和 2.5，仅 grill + apply。
+   - 约束又说严禁跳过 Phase 2。
+   - 需要明确 quick 模式只能跳哪些阶段，不能跳哪些阶段。
+
+8. **Phase 退出条件不足**
+   - 每个 Phase 有目标，但没有明确“什么时候可以进入下一阶段”。
+   - 建议增加进入条件、退出条件和必需产物。
+
+## 改进建议
+
+1. **将 `SKILL.md` 改成执行协议**
+   - 保留角色、触发场景、阶段总览、硬性约束和关键分支规则。
+   - 把长解释、模板、示例迁移到 `references/`。
+
+2. **增加启动前检查清单**
+   - 检查 `openspec/` 是否存在。
+   - 检查 `.claude/skills/openspec-*` 是否存在。
+   - 检查 `devflow/` 是否已初始化。
+   - 检查是否存在旧的根目录 `CONTEXT.md`，必要时迁移或合并到 `devflow/glossary/CONTEXT.md`。
+
+3. **增加 Phase 契约**
+   - 每个 Phase 明确：输入、动作、输出、退出条件、失败时回退路径。
+
+4. **补齐模板**
+   - 新增 `references/templates.md`，收纳 PRD、research、design、tasks、acceptance、ADR、compound knowledge 的最小模板。
+
+5. **补齐归档规则**
+   - 新增 `references/archive-rules.md`，明确如何从 openspec 文件提取信息到 `devflow/projects/`。
+
+6. **统一 quick 模式语义**
+   - quick 模式可以跳过 Phase 1.5 和 Phase 2.5。
+   - quick 模式不能跳过 Phase 2 的最小澄清，也不能跳过 Phase 4 的轻量归档。
+
+7. **增加 fallback 策略**
+   - 优先调用子 skill。
+   - 如果不可调用，则读取该 skill 的 `SKILL.md`。
+   - 如果 skill 文件不存在，则执行 dev-flow 内置的最小协议。
+
+## 优先级
+
+- **P0**：修正工具/环境耦合、依赖检查、quick 模式冲突。
+- **P1**：补模板和 Phase 退出条件。
+- **P2**：把长理念迁移到 `references/`，保持 `SKILL.md` 更短更可执行。
+- **P3**：增加 `agents/openai.yaml` 或等价元数据，方便技能列表展示。
+
+## 结论
+
+`dev-flow` 已经具备成为高价值工程元技能的基础：流程完整、沉淀意识强、质量闭环明确。下一步不应继续增加理念，而应把它产品化为“代理稳定执行协议”：更短的 `SKILL.md`、更明确的 Phase 契约、更标准的模板、更稳的 fallback 机制。

devflow/projects/2026-05-19-dev-flow-skill-evaluation/todo.md

@@ -0,0 +1,44 @@
+# Dev Flow Skill 改进 TODO
+
+## P0：先修正执行稳定性
+
+- [x] 重写 `description`，覆盖需求规划、feature 开发、openspec change、工程文档沉淀等触发场景。
+- [x] 将依赖表中的“✅ 已安装”改为“启动时检查”，区分 required、optional、fallback。
+- [x] 为子 skill 调用增加 fallback：优先调用 skill，不可调用时读取对应 `SKILL.md`，不存在时执行内置最小协议。
+- [x] 明确 `--quick` 模式：允许跳 Phase 1.5 和 Phase 2.5；禁止跳 Phase 2 最小澄清和 Phase 4 轻量归档。
+- [x] 增加 `devflow/` 初始化规则：创建 `projects/`、`glossary/`、`compound/`、`reference/`，并处理旧 `CONTEXT.md`。
+- [x] 增加 v3 OpenSpec-first 规则：devflow 辅助 OpenSpec，OpenSpec 指挥执行。
+- [x] 增加显式子 skill 调用规则：不能调用时必须标记 fallback 降级。
+- [x] 增加 devflow 产物分档：micro / standard / complex，避免默认产物过多。
+
+## P1：补齐 Phase 契约和模板
+
+- [x] 为 Phase 0 增加进入条件、退出条件、最小输入质量标准。
+- [x] 为 Phase 1 增加 openspec 产物检查：`proposal.md`、`design.md`、`specs/`、`tasks.md`。
+- [x] 为 Phase 1.5 增加 PRD/brief 最小模板和完成标准。
+- [x] 为 Phase 2 增加 `CONTEXT.md` 更新模板和 ADR 创建判断模板。
+- [x] 为 Phase 2.5 增加架构审计输出模板。
+- [x] 为 Phase 3 增加 diagnose 触发条件和 TDD 触发条件。
+- [x] 为 Phase 4 增加 acceptance report 模板和 openspec 提取规则。
+
+## P2：重构 skill 文件结构
+
+- [x] 将新版本迁移为 `.agents/skills/sm-flow/SKILL.md` 短执行协议。
+- [x] 新建 `.agents/skills/sm-flow/references/templates.md`，存放所有文档模板。
+- [x] 新建 `.agents/skills/sm-flow/references/phase-contracts.md`，存放 Phase 输入/动作/输出/退出条件。
+- [x] 新建 `.agents/skills/sm-flow/references/archive-rules.md`，存放 Phase 4 提取和归档规则。
+- [x] 新建 `.agents/skills/sm-flow/references/fallbacks.md`，存放子 skill 不可用时的最小协议。
+- [x] 删除或迁移 `SKILL.md` 中过长的理念说明，避免上下文膨胀。
+
+## P3：完善展示和可移植性
+
+- [ ] 评估是否需要 `agents/openai.yaml` 或其他技能展示元数据。
+- [ ] 增加一个最小示例项目，验证从 Phase 0 到 Phase 4 的完整流转。
+- [ ] 增加“复制到新项目后首次运行”的检查步骤。
+- [ ] 明确 Claude 版本与 Codex 版本的差异，避免工具名耦合。
+
+## 建议执行顺序
+
+1. 先改 `SKILL.md` 的触发描述、依赖检查、quick 模式和 fallback 规则。
+2. 再拆出 `references/` 模板与 Phase 契约。
+3. 最后用一个真实小需求跑通 Phase 0 到 Phase 4，回填发现的问题。