Reorganize workspace and archive skill artifacts
This commit is contained in:
zhuyongxin
@@ -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 在浏览器中验证搜索、标签过滤、相关推荐功能
|
||||
Reference in New Issue
Block a user