@jtf19/vibecoding-kit 0.1.0

package/docs/vibecoding-fork-analysis.md

@@ -0,0 +1,398 @@
+# Vibecoding Skill / 辅助工具架构分析
+
+## 背景
+
+当前目标是实现一套自己的 vibecoding skill 或辅助工具，并能放到 Claude、Codex、Cursor 等平台作为 skill、插件或辅助工具使用。
+
+`fork` 目录下的参考项目主要包括：
+
+- `distill`
+- `ECC`
+- `external reference`
+- `token-savior`
+
+这些项目不建议被简单合并成一个大仓库。更合理的方向是：以自己的 vibecoding 方法论为主线，参考它们的结构、能力和边界，选择性吸收可控模块。
+
+## 核心结论
+
+当前项目不应该做成“几个 fork 项目的源码拼接仓库”。
+
+更合适的定位是：
+
+> 做一套自己的 vibecoding skill / plugin / assistant toolkit，面向 Claude、Codex、Cursor 等平台发布；参考这些项目的结构、能力和方法论，但只选择性整合少数可控模块。
+
+主次关系建议如下：
+
+1. `external reference`：主参考，作为跨平台 skill/plugin 的结构骨架。
+2. `distill`：轻量工具参考，作为命令输出压缩和 DSL 化表达的最小工具蓝本。
+3. `token-savior`：工具能力参考，重点参考 MCP、上下文压缩、结构化代码检索、记忆系统。
+4. `ECC`：大内容库参考，只筛选高价值 skill，不整体搬运。
+
+## 各参考项目作用分析
+
+### `external reference`
+
+定位：跨 Claude、Codex、Cursor 等环境的通用开发流程 skill 框架。
+
+它的核心价值不是 skill 数量，而是跨平台插件结构和工作流组织方式。
+
+主要特点：
+
+- 有 `.claude-plugin`、`.codex-plugin`、`.cursor-plugin` 等平台插件入口。
+- 同一套 `skills/` 可映射到多个 agent harness。
+- 有 `using-external-reference` 作为 session bootstrap。
+- 围绕真实开发流程组织 skill：
+  - brainstorming
+  - writing plans
+  - executing plans
+  - systematic debugging
+  - test-driven development
+  - code review
+  - finishing branch
+
+建议定位：当前项目的主骨架参考。
+
+适合借鉴：
+
+- 跨平台插件 manifest。
+- skill 目录组织方式。
+- bootstrap 入口设计。
+- workflow skill 的触发和组合方式。
+- 不同平台的 hook 适配方式。
+
+不建议照搬：
+
+- 原项目的全部 skill 内容。
+- 原项目的语气和身份表达。
+- 强绑定它自身品牌的方法论。
+
+当前项目可以参考的目录形态：
+
+```text
+skills/
+hooks/
+docs/
+.claude-plugin/
+.codex-plugin/
+.cursor-plugin/
+CLAUDE.md
+AGENTS.md
+```
+
+### `ECC`
+
+定位：大规模 agent harness operating system，覆盖 skills、agents、commands、hooks、rules、MCP 配置和多平台目录。
+
+它的价值在于覆盖面和分类法，而不是适合被直接整体整合。
+
+主要特点：
+
+- 大量 skills。
+- 大量 agents。
+- commands、hooks、rules、MCP configs 较完整。
+- 平台覆盖广：
+  - Claude
+  - Codex
+  - Cursor
+  - Kiro
+  - OpenCode
+  - Gemini
+  - Qwen
+  - Zed
+- 包含通用开发、架构、测试、安全、研究、内容、运营、媒体、业务域等大量主题。
+
+建议定位：内容库和平台适配案例库。
+
+适合筛选的方向：
+
+- `tdd-workflow`
+- `verification-loop`
+- `security-review`
+- `coding-standards`
+- `frontend-patterns`
+- `backend-patterns`
+- `documentation-lookup`
+- `mcp-server-patterns`
+- `project-flow-ops`
+- `repo-scan`
+- `strategic-compact`
+
+不建议第一阶段纳入：
+
+- 大量业务域 skill。
+- 投资、市场、社媒、视频、科学数据库等垂直场景。
+- 大规模 agents 编排体系。
+- 复杂 dashboard / hosted service 相关内容。
+- 过多平台一次性适配。
+
+主要风险：
+
+- 体量过大，容易吞掉当前项目主线。
+- 内容主题太散，容易让项目变成“大而全资料库”。
+- 若全量整合，后续维护成本会急剧上升。
+
+### `token-savior`
+
+定位：MCP server + 结构化代码检索 + 持久记忆 + bash 输出压缩。
+
+它不是 skill 内容库，而是工具能力层。
+
+主要特点：
+
+- 提供 MCP server。
+- 提供结构化代码导航。
+- 提供 persistent memory。
+- 提供 Bash 输出压缩。
+- 支持 hook 初始化。
+- 支持 Claude、Cursor、Gemini、Codex 等 agent 的配置注入。
+- 提供 compactors，用于压缩 git、test、lint、docker、gh、cloud、shell 等命令输出。
+
+建议定位：中后期工具层参考。
+
+适合借鉴：
+
+- shell 输出 compactors。
+- hook 初始化方式。
+- agent 配置注入方式。
+- codebase index / project map 思路。
+- memory 的跨会话沉淀方式。
+- MCP 工具暴露方式。
+
+不建议第一阶段全量整合：
+
+- 它是完整 Python MCP 项目，体量较重。
+- 引入后会把当前项目从 skill/toolkit 拉向完整 MCP 平台。
+- 依赖、测试、运行时边界都更复杂。
+
+当前项目可以先做轻量版本：
+
+```text
+tools/
+  compact-output/
+  project-map/
+  session-memory/
+  skill-index/
+  install-adapters/
+```
+
+### `distill`
+
+定位：命令输出压缩和 DSL 化表达的轻量工具。
+
+它的目标是把 agent 看到的大段命令输出压缩成真正有用的关键信号。
+
+主要特点：
+
+- CLI 入口清晰。
+- 从 stdin 接收内容。
+- 输出面向 LLM。
+- 支持 onboarding。
+- 支持 DSL memory。
+- 支持本地或远程摘要模型。
+- 可包装成 skill、命令或辅助工具。
+
+建议定位：第一阶段轻量工具参考。
+
+适合借鉴的能力：
+
+- `vibe compact`
+- `vibe distill`
+- `vibe summarize-output`
+- `vibe learn-dsl`
+
+它比 `token-savior` 更适合作为当前项目的第一个工具原型。
+
+## 是否基于源码整合
+
+建议分三类处理。
+
+### 参考结构，不复制内容
+
+适用项目：
+
+- `external reference`
+- `ECC`
+
+处理方式：
+
+- 学习目录结构。
+- 学习插件 manifest。
+- 学习 skill 分类。
+- 学习 hook / command / rule 的组织方式。
+- 不全量复制 skill 文本。
+- 不继承原项目品牌语气。
+
+### 局部吸收能力，重写实现
+
+适用项目：
+
+- `distill`
+- `token-savior`
+
+处理方式：
+
+- 参考 compactors 思路。
+- 参考 CLI 形态。
+- 参考 hook 注入流程。
+- 参考 MCP 工具暴露方式。
+- 根据当前项目边界重写轻量实现。
+
+### 不建议全量整合源码
+
+不建议全量整合的原因：
+
+- `ECC` 内容太大，直接整合会失去当前项目主线。
+- `token-savior` 工具链太完整，第一阶段全量接入会引入过高复杂度。
+- `external reference` 的方法论有明确原项目风格，需要转化为自己的 vibecoding 风格。
+- `distill` 可以作为工具原型参考，但也建议重写为自己的 CLI 和接口。
+
+## 当前项目建议职责边界
+
+当前项目建议定位为：
+
+```text
+vibe-coding-kit
+```
+
+或：
+
+```text
+vibe-skills
+vibe-agent-kit
+vibe-workflow
+```
+
+建议模块划分：
+
+```text
+core-skills/
+  自己的 vibecoding 方法论、任务流程、检查清单、输出规范
+
+adapters/
+  Claude / Codex / Cursor / Gemini / OpenCode 的 manifest、目录映射、hook 配置
+
+tools/
+  命令输出压缩、项目扫描、skill 索引、上下文整理
+
+hooks/
+  会话开始、工具前后、压缩、记忆写入等自动化
+
+docs/
+  安装说明、平台兼容、设计原则、参考项目分析
+
+examples/
+  不同平台的使用示例
+```
+
+## 推荐的第一阶段 MVP
+
+第一阶段不要做“大一统 agent OS”。
+
+建议先做一个可安装、可理解、可维护的小核心。
+
+推荐结构：
+
+```text
+vibe-coding-kit/
+  skills/
+    vibe-planning/
+    vibe-debugging/
+    vibe-implementation/
+    vibe-review/
+    vibe-verification/
+    vibe-context-compact/
+  adapters/
+    claude/
+    codex/
+    cursor/
+  hooks/
+    session-start/
+    post-tool-compact/
+  tools/
+    compact-output/
+    project-map/
+  docs/
+    install-claude.md
+    install-codex.md
+    install-cursor.md
+```
+
+第一版目标：
+
+1. Claude / Codex / Cursor 都能安装。
+2. 有统一的 vibecoding bootstrap。
+3. 有 5 到 8 个高质量 workflow skills。
+4. 有一个轻量命令输出压缩工具。
+5. 不引入大型 MCP 和复杂 memory 系统。
+
+## 推荐主次关系
+
+| 优先级 | 项目 | 当前职责 |
+| --- | --- | --- |
+| 1 | `external reference` | 主骨架参考，跨平台插件结构和 workflow skill 组织方式 |
+| 2 | `distill` | 轻量工具参考，命令输出压缩和 DSL memory |
+| 3 | `token-savior` | 中后期工具能力参考，MCP、memory、code navigation、hook 初始化 |
+| 4 | `ECC` | 内容库参考，筛选高价值 skills 和平台适配样例 |
+
+## 当前项目应该形成的核心资产
+
+当前项目真正应该沉淀的不是 fork 代码，而是这些资产：
+
+1. 自己的 vibecoding 工作流。
+2. 跨平台安装和适配能力。
+3. 高质量、少数量、强约束的 workflow skills。
+4. 对 agent 上下文和 token 的轻量优化工具。
+5. 可维护的 skill catalog 和版本治理。
+
+## 后续演进路径
+
+### 阶段一：skill / plugin 核心
+
+目标：能安装、能触发、能指导 agent 工作。
+
+范围：
+
+- `skills/`
+- `adapters/claude`
+- `adapters/codex`
+- `adapters/cursor`
+- 基础 `hooks/session-start`
+
+### 阶段二：轻量上下文工具
+
+目标：降低 token 浪费，让 agent 更稳定读取项目上下文。
+
+范围：
+
+- `tools/compact-output`
+- `tools/project-map`
+- `hooks/post-tool-compact`
+
+主要参考：`distill`。
+
+### 阶段三：记忆和 MCP 能力
+
+目标：让项目具备跨会话记忆、结构化检索和工具暴露能力。
+
+范围：
+
+- `tools/session-memory`
+- `tools/skill-index`
+- MCP server 或 MCP adapter
+
+主要参考：`token-savior`。
+
+### 阶段四：扩展 skill catalog
+
+目标：从 `ECC` 这类大内容库中筛选真正符合当前项目风格的技能。
+
+范围：
+
+- TDD
+- verification
+- security review
+- architecture review
+- documentation lookup
+- repo scan
+
+不建议扩展到大量业务域 skill，除非当前项目已经有明确使用场景。