Reorganize workspace and archive skill artifacts
This commit is contained in:
zhuyongxin
@@ -0,0 +1,136 @@
|
||||
# Skills v0.5.0 整合修复记录
|
||||
|
||||
**日期：** 2026-04-30
|
||||
**来源：** grill-me 逐项审查，基于 v0.5.0 changelog 和 design doc 对比实际实现发现的不一致
|
||||
|
||||
---
|
||||
|
||||
## 一句话摘要
|
||||
|
||||
在前次 v0.5.0 slim architecture 改造的基础上，逐文件对比 design doc、proposal、plan、实际实现，修复了 `/essence` 遗漏项、`/follow` 旧引用残留、`/explore` 阶段冗余、references 死文件、docs 目录垃圾等问题。
|
||||
|
||||
---
|
||||
|
||||
## 已完成的改动
|
||||
|
||||
### 1. `/essence` — 补齐 v0.5.0 改造（之前遗漏）
|
||||
|
||||
| 位置 | 修改内容 |
|
||||
|---|---|
|
||||
| 版本号 | `0.3.0` → `0.5.0` |
|
||||
| 透镜定义 | 删除 `(borrowed from /explore)`，声明为 `/essence` 自有 |
|
||||
| 透镜相关 Phase 2/3/4/5 表格 | 从独立 3 列表格瘦身为内联 bullet point |
|
||||
| HTML Card | `## Phase 6: Output (Optional HTML Card)` → `## Optional: HTML Card`；去 "production-critical" 条件，改为 `Only when the user explicitly requests it` |
|
||||
| HTML Card 死链接 | 删除 `Same as /explore.` 两处，改为自包含内容 |
|
||||
| Mode Selection 上下文感知 | 新增检测逻辑：来自 `/explore` → 默认 User-directed；独立启动 → 默认 Auto-detect |
|
||||
| Auto-detect 信号 | `Most imported file` → `Cross-module contract`（后端项目更准确） |
|
||||
|
||||
### 2. `/follow` — 消除旧引用和设计偏差
|
||||
|
||||
| 位置 | 修改内容 |
|
||||
|---|---|
|
||||
| Mode Selection | 新增前置报告感知：来自 `/explore` + 代码仓库 → Runnable；来自 `/explore` + 非代码 → Reader；来自 `/essence` → Reader |
|
||||
| Runnable Check | 删除重新扫描逻辑，改为从前置报告读取结论；运行时信号改为后端导向（`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile` 等） |
|
||||
| Reader Mode Flow | 从文件级 "Walk one core file" 提升为设计级 "Frame the learning goal around a core design" |
|
||||
| 教学规则 | `do not use "go read the code" as the default instruction without context` → `never say "go read the code" as a standalone instruction`；引用代码必须先交代设计上下文 |
|
||||
|
||||
### 3. `/explore` — 合并冗余阶段
|
||||
|
||||
| 位置 | 修改内容 |
|
||||
|---|---|
|
||||
| Phase 1+2 | `Phase 1: Positioning` + `Phase 2: Structure` 合并为 `Phase 1: Positioning & Structure` |
|
||||
| 阶段总数 | 5 Phase → 4 Phase |
|
||||
| Project Type Detection | 信号列表同步（`package.json` 不再为首例）；阶段跳过的编号更新 |
|
||||
| Outcome 模板 | `5/5` → `4/4` |
|
||||
|
||||
### 4. References 清理
|
||||
|
||||
| 文件 | 操作 |
|
||||
|---|---|
|
||||
| `skills/explore/references/deep-fission.md` | **删除** — 描述已移除的 Deep Fission 功能，引用不存在的 `/fission` 技能 |
|
||||
| `skills/essence/references/essence-signals.md` | `Most imported file` → `Cross-module contract`，与 SKILL.md 同步 |
|
||||
|
||||
### 5. docs 存档清理
|
||||
|
||||
| 文件 | 操作 | 原因 |
|
||||
|---|---|---|
|
||||
| `docs/superpowers/proposal.md` | 删除 | 原始 4-skill 提案，已过时 |
|
||||
| `docs/superpowers/plan.md` | 删除 | 实施模板与实际实现不一致 |
|
||||
| `docs/superpowers/plans/` | 删除 | 456 行 task-by-task 计划，含 `/map` 引用 |
|
||||
| `docs/superpowers/README.md` | 删除 | `superpowers/README.md` 的副本，不属于历史存档 |
|
||||
|
||||
---
|
||||
|
||||
## docs 存档最终结构
|
||||
|
||||
```
|
||||
docs/superpowers/
|
||||
├── specs/
|
||||
│ ├── issue.md # 原始需求
|
||||
│ ├── 2026-04-21-skills-v0.5.0-slim-architecture-design.md
|
||||
│ └── 2026-04-21-skills-v0.5.0-changelog-design.md
|
||||
└── changelog/
|
||||
├── 2026-04-21-skills-v0.5.0-slim-architecture.md # 第一次改造 changelog
|
||||
├── 2026-04-21-skills-v0.5.0-validation-handoff.txt # 交接指令
|
||||
└── 2026-04-30-skills-v0.5.0-consolidation.md # 本次整合（本文件）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 当前 skill 状态
|
||||
|
||||
| 技能 | 版本 | Phase/Mode | 备注 |
|
||||
|---|---|---|---|
|
||||
| `/explore` | v0.5.0 | 4 Phase | 支持代码/非代码仓库；合并 Positioning+Structure |
|
||||
| `/essence` | v0.5.0 | 5 Phase + Optional HTML | 透镜自有；上下文感知 Mode Selection |
|
||||
| `/follow` | v0.5.0 | Runnable / Reader | 来源感知；不再重新扫描项目 |
|
||||
|
||||
---
|
||||
|
||||
## 实践验证结果
|
||||
|
||||
**日期：** 2026-04-30
|
||||
**测试目标仓库：**
|
||||
- 非代码仓库：explore-skill-family（自身）
|
||||
- 代码仓库：SuperBizAgent-java（Spring Boot + AI Agent）
|
||||
|
||||
| # | 验证路径 | 目标 | 结果 |
|
||||
|---|---|---|---|
|
||||
| 1 | `/follow` 拒绝无前置报告 | 直接模拟 | ✅ |
|
||||
| 2 | `/explore` 非代码仓库 | 自身 skill family | ✅ — 正确识别 skill-docs，跳过 Flow/Start |
|
||||
| 3 | `/essence` 深挖 | "硬边界"设计 | ✅ — 结论-证据-解释，可迁移 |
|
||||
| 4 | `/explore` → `/follow` | 自身 | ✅ — Reader 分流，引用报告内容 |
|
||||
| 5 | `/essence` → `/follow` | 自身 | ✅ — design-focused，未重扫 |
|
||||
| 6 | 三技能职责边界 | 综合矩阵检查 | ✅ — 核心问题/深度/前置依赖/产出均无重叠 |
|
||||
| 7 | `/explore` 代码仓库 | SuperBizAgent-java | ✅ — 4 Phase 全流程，后端信号检测正常 |
|
||||
|
||||
### 验证发现的额外修复
|
||||
|
||||
验证过程中对 SKILL.md 的追加修改（已在代码中反映）：
|
||||
- `/essence` Phase 6 → Optional: HTML Card
|
||||
- `/essence` Mode Selection 上下文感知
|
||||
- `/essence` Most imported file → Cross-module contract
|
||||
- `/follow` Mode Selection 来源感知
|
||||
- `/follow` Runnable Check 不再重扫，引用前置报告
|
||||
- `/follow` Reader Mode Flow 提升到设计层
|
||||
- `/follow` Teaching Interaction Rules 收紧
|
||||
- `/explore` Phase 1+2 合并，5→4 Phase
|
||||
- `/explore` Project Type Detection 信号改为后端导向
|
||||
- 删除 `skills/explore/references/deep-fission.md`
|
||||
|
||||
### handoff 10 条检查清单逐项结论
|
||||
|
||||
| # | 问题 | 结论 |
|
||||
|---|---|---|
|
||||
| 1 | `/explore` 对代码/非代码给出不同输出？ | ✅ Phase 2/3 对非代码跳过 |
|
||||
| 2 | `/explore` 保持在项目级理解？ | ✅ Phase 4 概览深度 |
|
||||
| 3 | `/essence` 稳定找最高价值设计？ | ✅ "硬边界"提取到 pattern 层 |
|
||||
| 4 | `/follow` 无前置报告明确拒绝？ | ✅ 拒绝并引导 |
|
||||
| 5 | `/follow` 基于 /explore 或 /essence 结果？ | ✅ 两次测试均基于前置报告 |
|
||||
| 6 | `/follow` 避免重新扫描？ | ✅ 三次验证均未重扫 |
|
||||
| 7 | `/follow` 真正引导式教学？ | ✅ 先问后讲 |
|
||||
| 8 | 三技能职责重叠/模糊？ | ✅ 边界清晰 |
|
||||
| 9 | README 与实际行为一致？ | ✅ 三技能描述与 SKILL.md 一致 |
|
||||
| 10 | references 与 v0.5.0 一致？ | ✅ deep-fission 已删，signals 已同步 |
|
||||
|
||||
**总体验收结论：通过。** 文档、边界、行为三者一致。
|
||||
@@ -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` 命名约定
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user