{"id":47338226,"url":"https://github.com/alienzhou/skill-discuss-for-specs","last_synced_at":"2026-03-17T22:19:55.904Z","repository":{"id":338027679,"uuid":"1156251426","full_name":"alienzhou/skill-discuss-for-specs","owner":"alienzhou","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-24T09:18:51.000Z","size":661,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T13:51:02.176Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alienzhou.png","metadata":{"files":{"readme":"README-zh.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-12T12:44:15.000Z","updated_at":"2026-02-24T10:58:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alienzhou/skill-discuss-for-specs","commit_stats":null,"previous_names":["alienzhou/skill-discuss-for-specs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/alienzhou/skill-discuss-for-specs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alienzhou%2Fskill-discuss-for-specs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alienzhou%2Fskill-discuss-for-specs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alienzhou%2Fskill-discuss-for-specs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alienzhou%2Fskill-discuss-for-specs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alienzhou","download_url":"https://codeload.github.com/alienzhou/skill-discuss-for-specs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alienzhou%2Fskill-discuss-for-specs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30633245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T17:32:55.572Z","status":"ssl_error","status_checked_at":"2026-03-17T17:32:38.732Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-17T22:19:55.179Z","updated_at":"2026-03-17T22:19:55.896Z","avatar_url":"https://github.com/alienzhou.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Skill Discuss for Specs\n\n\u003e 每当你有一个想法，希望让它变得更清晰、更具可执行性时，使用这个项目。\n\n一个由 AI 驱动的讨论促进系统，通过结构化的深度对话帮助你生成高质量的技术规范。\n\n![Discussion Mode](./assets/banner.jpg)\n\n\u003e 点击下方图片观看演示视频\n\n[![观看演示](./assets/cover.jpg)](https://s16-def.ap4r.com/kos/s101/nlav112218/mengshou/use-discuss-for-specs.0242e2cac0963606.mp4)\n\n---\n\n## 💡 问题背景\n\n在 **规范驱动开发(SDD)** 中，生成高质量规范是一个众所周知的难题：\n\n- **好的规范很强大**：完整、丰富的规范能显著提升代码生成质量、任务完成率，并使解决更高复杂度的问题成为可能\n- **但创建它们很难**：高效生成全面、深思熟虑的规范仍然很困难且认知负荷高\n- **缺失的环节**：如何在不造成认知负荷过重的情况下生成高质量规范？\n\n---\n\n## 🎯 解决方案：讨论模式\n\n本项目引入了**讨论模式**——一种由 AI 促进的对话方式，帮助你迭代式地开发清晰、可执行的技术规范。它解决了三个关键问题：\n\n### 1. AI 驱动的主动性\n\nAI Agent 积极推动讨论向前发展：\n\n- **AI 提议**：持续提供解决方案、替代方案和想法\n- **人类决策**：你只需要选择、确认或回答问题\n- **引导式完善**：通过这个引导过程，自然地深化和完善技术解决方案\n- **降低认知负荷**：你保持在决策者角色，AI 处理繁重的思考工作\n\n### 2. 状态管理与进度追踪\n\n在深度讨论中永不迷失方向：\n\n- **维护上下文**：通过结构化大纲持续追踪讨论状态\n- **决策沉淀**：自动捕获并文档化已确认的决策\n- **进度感知**：始终知道你在哪里，还有哪些问题待解决\n- **不丢失细节**：深度、长期的讨论保持有序，无需费力\n- **低成本深度**：可以进行全面探索，无需担心丢失线索\n\n### 3. 渐进式增强\n\n灵活适应你的工作流程：\n\n- **随时开始**：在规范生成前、开发中、调试时或分析问题时\n- **可控深度**：随时退出并沉淀决策，或继续讨论直到每个细节 100% 确认\n- **始终相关**：无论你只有一个模糊想法还是具体挑战，都有效\n\n---\n\n## 👀 看到差异\n\n### 对话流程\n\n**没有讨论模式** - 你驱动一切：\n\n```\n你 ──────►  \"我需要设计一个缓存系统。我在考虑使用 Redis，\n             但对 TTL 策略不确定。应该使用惰性过期还是主动过期？\n             另外，缓存失效模式呢？还有...\n             我需要考虑读写比例...\"\n\n             (你必须自己想出所有问题)\n             (你必须组织自己的思路)\n             (你必须推动对话)\n                       │\n                       ▼\nAI ────►  [回答你问的问题]\n                       │\n                       ▼\n你 ──────►  \"好的，但是关于...等等，我忘了问...\"\n\n             (你需要记住一切)\n             (你需要发现所有边界情况)\n             (你可能会错过重要方面)\n                       │\n                       ▼\n                     .....\n\n😓 高认知负荷：你思考、你提问、你追踪、你记忆\n```\n\n**有讨论模式** - AI 驱动，你决策：\n\n```\n你 ──────►  \"设计一个缓存系统\"  (就这样。只是主题。)\n                       │\n                       ▼\nAI ────►  \"让我先理解一下问题空间。\n\n             💡 缓存的主要驱动力是什么？\n                - 性能优化？\n                - 成本降低？\n                - 可靠性提升？\n\n             💡 我注意到我们应该尽早明确读写比例 -\n                这从根本上影响架构选择。\n\n             ❓ 这是读多写少还是写多读少？\"\n                       │\n                       ▼\n你 ──────►  \"读多写少，用于 API 响应\"  (简单回答)\n                       │\n                       ▼\nAI ────►  \"很好。对于读多的 API 缓存，你可能没考虑过：\n\n             💡 Cache-aside vs Read-through 模式在失效复杂度上\n                有很大不同。让我解释一下权衡...\n\n             ┌────────────── 进度追踪 ──────────────┐\n             │ ✅ 已确认：读多 API 缓存             │\n             │ 🔄 讨论中：缓存模式选择             │\n             │ 📋 待定：TTL 策略、失效机制          │\n             └──────────────────────────────────────┘\"\n                       │\n                       ▼\n你 ──────►  \"第一个\"  (简单选择)\n                       │\n                       ▼\n                     .....\n\n😊 低认知负荷：AI 思考、AI 提问、AI 追踪、你决策\n```\n\n### 输出对比\n\n| ❌ 没有讨论模式 | ✅ 有讨论模式 |\n|:--------------|:-------------|\n| 📜 只有聊天历史 | 📁 `.discuss/caching-system/` |\n| (向上滚动查找内容) | ├── 📋 `outline.md` (实时进度) |\n| (信息散落在对话中) | └── 📄 `decisions/` |\n| • 决策 2... 可能忘了 | \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;├── `01-cache-pattern.md` |\n| • 决策 3... 哪一轮？ | \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;├── `02-storage-choice.md` |\n| • 我们覆盖所有内容了吗？ | \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;└── `03-ttl-strategy.md` |\n| • 还有什么待定？ | \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;└── (每个决策独立归档) |\n|  |  |\n| ❌ 没有结构 | ✅ 结构化且可搜索 |\n| ❌ 容易迷失方向 | ✅ 无信息丢失 |\n| ❌ 难以后续恢复 | ✅ 随时恢复 |\n\n---\n\n## 🔍 讨论模式 vs Spec\n\n讨论模式**不是用来替代 Spec** 的，它是 Spec 的**上游决策层**，让 Spec 更容易写、更可靠。\n\n|  | 讨论模式 | Spec |\n|--|---------|------|\n| **关注点** | 过程（探索、决策） | 产物（文档、执行） |\n| **核心问题** | \"要决策什么？为什么？\" | \"要做什么？怎么做？\" |\n| **主要产出** | `outline.md` + `decisions/` | 结构化规范文档 |\n| **适用时机** | 不确定性高时 | 决策已清晰时 |\n\n### 在 SDD 中的工作流\n\n```\n讨论 → 沉淀决策 → 生成/更新 Spec → 实现 → (需要时回到讨论)\n```\n\n本项目**工具无关**：可以和你现有的任何 Spec 模板、IDE 流程或 Spec 生成器组合使用。\n\n---\n\n## 🔧 使用场景\n\n每当需要澄清和完善想法时，使用讨论模式：\n\n| 场景 | 什么时候用 | 如何帮助 |\n|------|-----------|---------|\n| **技术方案设计** | \"我要设计一个缓存系统，怎么做呢？\" | 探索架构、评估权衡、达成清晰决策 |\n| **问题诊断** | \"线上有个性能问题，该如何解决？\" | 系统性分析问题、追踪假设、文档化发现 |\n| **技术选型** | \"Redis 还是 Memcached？要不要上 Kafka？\" | 比较选项、评估适配性、做出明智选择 |\n| **产品设计** | \"这个功能的用户流程应该怎么设计？\" | 完善需求、探索用户流程、文档化决策 |\n| **规范生成** | \"我有个技术设想但还没想清楚，该怎么细化呢？\" | 将粗略想法转化为全面、可执行的技术规范 |\n\n---\n\n## ✨ 技术特性\n\n- **单一技能架构**：统一的 `discuss-for-specs` Skill，模板分离便于维护\n- **智能沉淀**：自动检测未沉淀决策，可配置提醒\n- **基于 Hook 的自动化**：流程工作（轮次计数、状态检查）由 Python 脚本处理，而非 AI\n- **多平台支持**：支持多个 AI 编程助手（见下表）\n- **结构化追踪**：问题生命周期管理、趋势分析和收敛检测\n- **跨平台设计**：共享技能内容，平台特定适配\n\n---\n\n## 🔌 平台支持\n\n| 平台 | 状态 | 级别 | 安装命令 |\n|------|:----:|:----:|----------|\n| **Claude Code** | ✅ 就绪 | L2 | `npx @vibe-x/discuss-for-specs install -p claude-code` |\n| **Cursor** | ✅ 就绪 | L2 | `npx @vibe-x/discuss-for-specs install -p cursor` |\n| **Cline** | ✅ 就绪 | L2 | `npx @vibe-x/discuss-for-specs install -p cline` |\n| **Kilocode** | ✅ 就绪 | L1 | `npx @vibe-x/discuss-for-specs install -p kilocode` |\n| **OpenCode** | ✅ 就绪 | L1 | `npx @vibe-x/discuss-for-specs install -p opencode` |\n| **Codex CLI** | ✅ 就绪 | L1 | `npx @vibe-x/discuss-for-specs install -p codex` |\n| **Trae** | ✅ 就绪 | L1 | `npx @vibe-x/discuss-for-specs install -p trae` |\n| **Qoder** | ✅ 就绪 | L1 | `npx @vibe-x/discuss-for-specs install -p qoder` |\n| **Roo-Code** | ✅ 就绪 | L1 | `npx @vibe-x/discuss-for-specs install -p roo-code` |\n| **CodeFlicker** | ✅ 就绪 | L1 | `npx @vibe-x/discuss-for-specs install -p codeflicker` |\n| Windsurf | 🔜 计划中 | - | - |\n\n### L1 和 L2 有什么区别？\n\n| 功能 | L1 平台 | L2 平台 |\n|------|:-------:|:-------:|\n| 讨论引导 | ✅ | ✅ |\n| 进度追踪 | ✅ | ✅ |\n| 决策沉淀 | ✅ | ✅ |\n| **自动提醒 Hooks** | ❌ | ✅ |\n\n- **L2 平台**（Claude Code、Cursor、Cline）支持 hooks，自动提醒你沉淀决策\n- **L1 平台**（Kilocode、OpenCode、Codex、Trae、Qoder、Roo-Code、CodeFlicker）拥有完整讨论功能，但需要手动追踪决策\n\n\u003e 💡 详细架构和 Hook 机制请参阅 [工作原理](docs/HOW-IT-WORKS-zh.md)。\n\n---\n\n## 🚀 快速开始\n\n### 安装\n\n选择最适合你的安装方式：\n\n#### 方式一：npx（推荐 - 无需安装）\n\n```bash\n# 指定平台安装（必须）\nnpx @vibe-x/discuss-for-specs install -p claude-code\nnpx @vibe-x/discuss-for-specs install -p cursor\n```\n\n#### 方式二：全局安装（经常使用推荐）\n\n```bash\nnpm install -g @vibe-x/discuss-for-specs\ndiscuss-for-specs install -p cursor\n```\n\n#### 方式三：项目级安装\n\n```bash\n# 安装到当前目录\ndiscuss-for-specs install -p cursor --target .\n\n# 安装到指定目录\ndiscuss-for-specs install -p claude-code --target /path/to/project\n```\n\n#### 方式四：导出到原始目录（用于不支持的平台）\n\n```bash\n# 直接导出技能，不创建平台目录结构\ndiscuss-for-specs export /my/custom/skills/\n\n# 包含 L1 引导（用于手动沉淀提醒）\ndiscuss-for-specs export /my/custom/skills/ --include-l1-guidance\n```\n\n### 前置要求\n\n- **Node.js** 16+（npm 安装需要）\n- **Python** 3.8+，安装 PyYAML（hooks 需要，安装时自动检查）\n\n### 开始讨论\n\n安装完成后，只需告诉你的 AI：\n\n\u003e \"进入讨论模式。我想讨论 [你的主题]。\"\n\n或英文：\n\n\u003e \"Enter discussion mode. I want to design [your topic].\"\n\nAgent 将引导你进行结构化对话，自动追踪决策和进度。\n\n### 卸载\n\n```bash\nnpx @vibe-x/discuss-for-specs uninstall -p cursor\n```\n\n---\n\n## 📁 项目结构\n\n```\nskill-discuss-for-specs/\n├── skills/              # 📝 技能源码（供 AI 使用的 Markdown）\n│   └── discuss-for-specs/          # 单一合并的讨论技能\n│       ├── SKILL.md                # 核心技能内容\n│       ├── headers/                # 平台特定的 YAML 头\n│       └── references/             # 模板和参考文档\n├── hooks/               # ⚡ 自动化脚本（Python）\n│   ├── stop/                # 沉淀检测 Hook（基于快照）\n│   └── common/              # 共享工具\n├── npm-package/         # 📦 NPM 发布包（唯一构建入口）\n│   ├── dist/                # 所有平台的构建产物\n│   ├── hooks/               # 打包的 hooks（构建时复制）\n│   └── src/                 # CLI 源码\n├── config/              # ⚙️ 配置模板\n└── .discuss/            # 💬 讨论归档（示例）\n```\n\n\u003e **说明**：所有技能构建通过 `npm-package/scripts/build.js` 完成。\n\n---\n\n## 📚 文档\n\n- **[工作原理](docs/HOW-IT-WORKS-zh.md)** - 架构、Hooks 和内部机制\n- [架构设计讨论](.discuss/2026-01-17/skill-discuss-architecture-design/outline.md) - 讨论模式实际运行示例\n- [决策记录](.discuss/2026-01-17/skill-discuss-architecture-design/decisions/) - 已文档化的架构决策\n- [AGENTS.md](AGENTS.md) - 与此系统协作的 AI 指南\n\n---\n\n## 🔧 配置\n\n配置存储在 `.discuss/.snapshot.yaml` 中。默认阈值：\n\n```yaml\nversion: 1\nconfig:\n  stale_threshold: 3      # outline 变更几次后轻柔提醒\n```\n\n更多配置选项详见 [工作原理](docs/HOW-IT-WORKS-zh.md#snapshotyaml)。\n\n---\n\n## 🛠️ 开发\n\n### 前置要求\n\n- Node.js 16+\n- Python 3.8+\n\n### 设置\n\n```bash\n# 安装 npm 依赖\ncd npm-package \u0026\u0026 npm install\n\n# 构建发布包\nnpm run build\n\n# 运行 Python 测试\ncd .. \u0026\u0026 python -m pytest tests/\n```\n\n### CLI 命令\n\n```bash\n# 列出支持的平台\nnpx @vibe-x/discuss-for-specs platforms\n\n# 带选项安装\nnpx @vibe-x/discuss-for-specs install --platform cursor --skip-hooks\nnpx @vibe-x/discuss-for-specs install --platform claude-code --skip-skills\n\n# 卸载\nnpx @vibe-x/discuss-for-specs uninstall --platform cursor\n```\n\n---\n\n## 🤝 贡献\n\n欢迎贡献！这是 V1 - 基础版本。我们根据实际使用情况进行迭代。\n\n---\n\n## 📄 许可证\n\n[MIT License](LICENSE)\n\n---\n\n## 🙏 致谢\n\n基于 Claude Skills 生态系统、规范驱动开发实践和跨平台 IDE 扩展架构的见解构建。\n\n---\n\n**版本**：0.3.0\n**状态**：V1 - 基础版本\n**理念**：通过 AI 引导的结构化讨论，将粗略想法转化为可执行规范。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falienzhou%2Fskill-discuss-for-specs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falienzhou%2Fskill-discuss-for-specs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falienzhou%2Fskill-discuss-for-specs/lists"}