huhaa-myskills 0.1.5

package/docs/RUNBOOK-myskills.md

@@ -0,0 +1,258 @@
+# RUNBOOK: HuHaa-MySkills
+
+This runbook is the production/operator note for the local HuHaa-MySkills service.
+
+## Service identity
+
+- Name: HuHaa-MySkills
+- Purpose: local browser catalog for AI-agent skills, plugins, MCP configs, and runbooks
+- Default URL: `http://127.0.0.1:11520`
+- Default data dir: `~/.config/huhaa-myskills/`
+- Override data dir: `HUHAA_HOME=/path/to/dir`
+- Default preferred port: `11520`
+- Override port: `PORT=11530`
+- Bind address: `127.0.0.1` only
+
+## Main commands
+
+```bash
+npm install
+npm run init
+npm start
+npm test
+npm run verify
+npm run purge
+```
+
+## Files and directories
+
+Runtime/user data:
+
+```text
+~/.config/huhaa-myskills/sources.yaml
+~/.config/huhaa-myskills/cache.json
+~/.config/huhaa-myskills/state.json
+```
+
+Repository layout:
+
+```text
+service/bin/huhaa-myskills.mjs
+service/config/sources.example.yaml
+service/packages/scanner/src/index.mjs
+service/packages/server/src/index.mjs
+service/packages/web/src/App.vue
+service/scripts/verify.mjs
+```
+
+## Healthy state
+
+```bash
+curl -s http://127.0.0.1:11520/api/health
+```
+
+Expected shape:
+
+```json
+{"ok":true,"port":11520,"items":188,"version":"0.1.0","phase":"P6"}
+```
+
+The exact `items` count depends on local sources.
+
+## Full verification
+
+```bash
+npm run verify
+```
+
+Expected final line:
+
+```text
+[verify] PASS build + tests + HTTP/API/static smoke checks
+```
+
+The verify script proves:
+
+1. Vue SPA builds.
+2. Scanner/server tests pass.
+3. A real Fastify server starts on loopback.
+4. `/api/health`, `/api/skills`, `/api/skills/:id`, `/api/stats`, and `/api/reload` work.
+5. Built JS/CSS assets are served with correct content types.
+6. Temporary runtime data is removed.
+
+## Troubleshooting
+
+### Page does not open
+
+Check service:
+
+```bash
+curl -s http://127.0.0.1:11520/api/health
+```
+
+If it fails, start manually:
+
+```bash
+npm start
+```
+
+If port is busy:
+
+```bash
+PORT=11530 npm start
+```
+
+The CLI will also try fallback ports when the preferred port is unavailable.
+
+### Page opens but is blank
+
+Build assets:
+
+```bash
+npm run build:web
+npm start
+```
+
+Check static assets from `index.html`:
+
+```bash
+curl -I http://127.0.0.1:11520/
+curl -I http://127.0.0.1:11520/assets/<asset>.js
+curl -I http://127.0.0.1:11520/assets/<asset>.css
+```
+
+Expected content types:
+
+```text
+text/html; charset=utf-8
+text/javascript; charset=utf-8
+text/css; charset=utf-8
+```
+
+### No skills or too few skills
+
+Check config:
+
+```bash
+sed -n '1,220p' ~/.config/huhaa-myskills/sources.yaml
+```
+
+Run scan debug:
+
+```bash
+HUHAA_DEBUG=1 npm run scan >/tmp/huhaa-skills.json
+```
+
+Common causes:
+
+- source root path does not exist
+- source is disabled
+- file is larger than `limits.maxFileBytes`
+- glob does not match the target file
+- project runbooks are outside configured roots
+
+### MCP secrets appear in UI
+
+They should not. Verify using tests:
+
+```bash
+npm test
+```
+
+Specific redaction behavior lives in:
+
+```text
+service/packages/scanner/src/adapters/mcp-config.mjs
+```
+
+The adapter redacts keys matching token/key/secret/password/auth/cookie-style names and common inline secret patterns before writing `raw` or `preview`.
+
+### Reload does not update page
+
+Manual reload:
+
+```bash
+curl -s -X POST http://127.0.0.1:11520/api/reload
+curl -s http://127.0.0.1:11520/api/reload-state
+```
+
+Watch events endpoint:
+
+```bash
+curl -N http://127.0.0.1:11520/api/events
+```
+
+If watcher is unreliable on a synced/cloud directory, use manual reload. The server never clears the old snapshot on reload failure; it keeps the last good data.
+
+### Copy buttons do not work
+
+On macOS, copy uses `pbcopy` on the server side.
+
+Check:
+
+```bash
+command -v pbcopy
+```
+
+The tests use a fake temporary `pbcopy` and do not touch the real clipboard.
+
+### Open in Cursor does not work
+
+Check Cursor CLI:
+
+```bash
+command -v cursor
+```
+
+If missing, install Cursor shell command from Cursor itself, or use the path copy/reveal buttons instead.
+
+### Finder reveal does not work
+
+Finder reveal uses:
+
+```bash
+open -R <path>
+```
+
+This is macOS-only.
+
+## Public release checklist
+
+Before pushing a public repository:
+
+```bash
+npm run verify
+```
+
+Then check ignored/generated files:
+
+```bash
+git status --short
+git check-ignore -v node_modules service/packages/web/dist 2>/dev/null || true
+```
+
+Check for obvious secrets outside ignored directories:
+
+```bash
+git grep -n -E '(ghp_|sk-[A-Za-z0-9_-]{12,}|Bearer [A-Za-z0-9._~+/=-]{12,}|API[_-]?KEY|SECRET|PASSWORD|TOKEN)' -- . ':!service/packages/scanner/test/scanner.test.mjs'
+```
+
+Expected matches should be code patterns/documentation only, not real credential values.
+
+## Recovery
+
+Reset runtime config:
+
+```bash
+npm run purge
+npm run init
+npm start
+```
+
+Remove code checkout:
+
+```bash
+rm -rf /path/to/HuHaa-MySkills
+```
+
+`purge` intentionally touches only the runtime data dir, never the repository.

package/docs/SYNC-SKILLS.md

@@ -0,0 +1,259 @@
+# HuHaa-MySkills 编辑器技能同步 (v0.1.2)
+
+本文档说明如何使用编辑器技能自动同步功能。
+
+## 快速开始
+
+### 方式 1：本地安装后同步
+
+```bash
+# 克隆项目
+git clone https://github.com/aquarkgn/HuHaa-MySkills.git
+cd HuHaa-MySkills
+
+# 执行同步脚本（交互模式）
+npm run sync
+# 或直接运行
+bash service/scripts/sync-skills.sh
+```
+
+### 方式 2：远程一键安装 + 同步
+
+```bash
+# 通过 curl 直接执行（推荐）
+curl -fsSL https://raw.githubusercontent.com/aquarkgn/HuHaa-MySkills/main/install-and-sync.sh | bash
+```
+
+### 方式 3：仅同步（已安装项目后）
+
+```bash
+npm run sync
+# 或
+npm run sync:remote
+```
+
+---
+
+## 功能说明
+
+### 自动编辑器检测
+
+脚本会自动扫描以下编辑器，并列出已安装的编辑器：
+
+| 编辑器       | macOS 配置位置                                    | Linux 配置位置               |
+|------------|----------------------------------------------------|-----------------------------|
+| **Cursor** | `~/Library/Application Support/Cursor`            | `~/.config/Cursor`          |
+| **VS Code** | `~/Library/Application Support/Code`             | `~/.config/Code`            |
+| **Helix**  | `~/Library/Application Support/helix`            | `~/.config/helix`           |
+| **Neovim** | `~/.config/nvim`                                  | `~/.config/nvim`            |
+| **Sublime** | `~/Library/Application Support/Sublime Text`     | `~/.config/sublime-text-3`  |
+| **Windsurf** | `~/Library/Application Support/Windsurf`        | `~/.config/Windsurf`        |
+
+### 交互式选择
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  请选择要同步技能的编辑器（多选）
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  [1] cursor
+     Path: /Users/mac/Library/Application Support/Cursor
+
+  [2] vscode
+     Path: /Users/mac/Library/Application Support/Code
+
+  [3] helix
+     Path: /Users/mac/Library/Application Support/helix
+
+  0 - 全选
+  q - 退出
+
+请输入选择 (使用逗号分隔多个): 1,2
+```
+
+**支持的输入方式：**
+- `1` - 选择第一个编辑器
+- `1,2,3` - 选择多个编辑器
+- `0` - 全选所有编辑器
+- `q` - 取消操作
+
+### 同步功能
+
+脚本会将项目的技能和配置同步到选中的编辑器：
+
+#### Cursor
+- 同步 `.cursorrules` 文件到编辑器配置目录
+- 自动备份原有的 `.cursorrules`
+
+#### VS Code
+- 复制代码片段和脚本到编辑器的 snippets 目录
+- 支持自定义代码补全
+
+#### Helix
+- 同步 `config.toml` 配置文件
+- 集成 HuHaa 自定义命令
+
+#### Neovim
+- 生成 `init.lua` 基础配置
+- 加载 HuHaa 自定义配置
+
+#### Sublime Text
+- 同步用户设置和代码片段
+
+#### Windsurf
+- 同步编辑器配置
+
+---
+
+## 使用示例
+
+### 示例 1：在本地项目中同步所有编辑器
+
+```bash
+cd /path/to/HuHaa-MySkills
+npm run sync
+
+# 选择: 0（全选）
+```
+
+### 示例 2：只同步 Cursor
+
+```bash
+npm run sync
+
+# 选择: 1（假设 Cursor 是第一个）
+```
+
+### 示例 3：从远程直接运行（新机器）
+
+```bash
+# 自动安装 + 同步一体化
+curl -fsSL https://raw.githubusercontent.com/aquarkgn/HuHaa-MySkills/main/install-and-sync.sh | bash
+
+# 或者只执行同步
+curl -fsSL https://raw.githubusercontent.com/aquarkgn/HuHaa-MySkills/main/install-and-sync.sh | bash -s -- --sync-only
+```
+
+### 示例 4：本地项目路径
+
+```bash
+# 如果脚本在其他位置，指定本地项目路径
+bash /path/to/sync-skills.sh --local /path/to/HuHaa-MySkills
+```
+
+---
+
+## 环境变量
+
+脚本支持以下环境变量来自定义行为：
+
+```bash
+# 指定本地项目路径
+export HUHAA_LOCAL_PATH="/path/to/HuHaa-MySkills"
+
+# 指定远程仓库 URL（默认：https://github.com/aquarkgn/HuHaa-MySkills.git）
+export HUHAA_REPO_URL="https://github.com/your-fork/HuHaa-MySkills.git"
+
+# 指定原始内容 URL（默认：https://raw.githubusercontent.com/aquarkgn/HuHaa-MySkills）
+export HUHAA_REPO_RAW="https://raw.githubusercontent.com/your-fork/HuHaa-MySkills"
+
+# 执行脚本
+bash service/scripts/sync-skills.sh
+```
+
+---
+
+## 常见问题
+
+### Q: 脚本找不到我的编辑器配置？
+
+**A:** 某些编辑器在非标准位置安装。你可以：
+1. 检查编辑器是否在支持列表中
+2. 确认编辑器配置目录是否存在
+3. 手动指定项目路径：`HUHAA_LOCAL_PATH=/path/to/project bash service/scripts/sync-skills.sh`
+
+### Q: 同步会覆盖我的现有配置吗？
+
+**A:** 脚本会：
+- 为 Cursor 的 `.cursorrules` 创建备份（`.cursorrules.backup`）
+- 对于其他编辑器，如果配置文件已存在，会跳过覆盖并显示警告
+- 不会无故删除任何文件
+
+### Q: 可以部分同步吗？
+
+**A:** 可以！选择需要同步的编辑器即可：
+```bash
+npm run sync
+# 选择: 1,3（只同步第 1 和第 3 个编辑器）
+```
+
+### Q: 如何撤销同步？
+
+**A:** 如果有备份，恢复备份文件：
+```bash
+# 恢复 Cursor 备份
+cp ~/.cursor/.cursorrules.backup ~/.cursor/.cursorrules
+```
+
+### Q: 脚本支持 Windows 吗？
+
+**A:** 支持 Windows WSL（Windows Subsystem for Linux）。在 PowerShell 中：
+```powershell
+wsl bash -c "curl -fsSL https://raw.githubusercontent.com/aquarkgn/HuHaa-MySkills/main/install-and-sync.sh | bash"
+```
+
+---
+
+## 故障排查
+
+### 脚本执行权限错误
+
+```bash
+# 添加执行权限
+chmod +x service/scripts/sync-skills.sh
+bash service/scripts/sync-skills.sh
+```
+
+### 网络连接问题
+
+如果 curl 下载失败，可尝试：
+1. 检查网络连接
+2. 使用代理：`curl -x [proxy-url] ...`
+3. 使用本地项目：`npm run sync`
+
+### 编辑器不被识别
+
+检查编辑器配置目录是否存在：
+```bash
+# macOS
+ls ~/Library/Application\ Support/Cursor
+ls ~/Library/Application\ Support/Code
+ls ~/.config/nvim  # Linux
+
+# Linux
+ls ~/.config/Cursor
+ls ~/.config/Code
+ls ~/.config/helix
+```
+
+---
+
+## 后续更新
+
+脚本会在新版本中增加：
+- [ ] 更多编辑器支持（Emacs, Vim, etc）
+- [ ] 配置文件版本管理
+- [ ] 回滚功能
+- [ ] 增量同步（只同步改变的部分）
+
+---
+
+## 相关文档
+
+- [快速启动指南](./GUIDE.md)
+- [项目规划](./PLAN.md)
+- [发布规范](./RULES.md)
+
+---
+
+**v0.1.2 首发功能** | [GitHub](https://github.com/aquarkgn/HuHaa-MySkills)

package/docs/releases/README.md

@@ -0,0 +1,47 @@
+# 版本发布历史
+
+本目录包含每个版本的详细发布说明。
+
+## 🚀 已发布版本
+
+| 版本 | 日期 | 主题 | 文档 |
+|------|------|------|------|
+| **v0.1.1** | 2026-06-18 | npm 全局安装支持 | [详情](./v0.1.1.md) |
+| **v0.1.0** | 2026-06-17 | 首个可用版本 | [详情](./v0.1.0.md) |
+
+## 📋 计划中的版本
+
+| 版本 | 预期日期 | 主题 | 计划文档 |
+|------|---------|------|---------|
+| **v0.1.2** | 2026-06-30 | Hermes 技能集成 + 搜索优化 | [v0.1.2 计划](../todo/v0.1.2.md) / [发布说明](./v0.1.2.md) |
+| **v0.1.3** | 2026-07-07 | Obsidian + Claude.md 支持 | [v0.1.3 计划](../todo/v0.1.3.md) |
+| **v0.1.4** | 2026-07-21 | 分组与筛选增强 | [v0.1.4 计划](../todo/v0.1.4.md) |
+| **v0.1.5** | 2026-07-28 | 导出与分享 | [v0.1.5 计划](../todo/v0.1.5.md) |
+| **v0.1.6** | 2026-08-11 | 增量扫描与缓存 | [v0.1.6 计划](../todo/v0.1.6.md) |
+| **v0.1.7** | 2026-08-25 | 跨平台完整支持 | [v0.1.7 计划](../todo/v0.1.7.md) |
+| **v0.1.8** | 2026-09-01 | 开发者工具 | [v0.1.8 计划](../todo/v0.1.8.md) |
+| **v0.1.9** | 2026-09-15 | 完成度冲刺 | [v0.1.9 计划](../todo/v0.1.9.md) |
+
+## 📖 如何阅读版本说明
+
+每个发布版本的详细说明包含：
+
+- **🎯 版本目标** - 这个版本要达成什么
+- **✨ 新增功能** - 具体增加了哪些功能
+- **🐛 Bug 修复** - 修复了哪些问题
+- **📊 性能对比** - 性能改进数据
+- **🧪 测试覆盖** - 测试情况
+- **📦 发行物** - 如何获取这个版本
+- **🚀 安装指南** - 如何安装和升级
+- **📝 Breaking Changes** - 是否有不兼容改动
+- **🔄 迁移指南** - 如何从旧版本升级
+
+## 🔗 相关资源
+
+- [CHANGELOG.md](../../CHANGELOG.md) - 简明版本历史
+- [版本计划](../todo/) - 未来版本计划
+- [发布规范](../RULES.md) - 如何发布版本
+
+---
+
+**最后更新**: 2026-06-18