newbee-sdd 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# newbee-sdd
+
+> **规格驱动开发（Spec-Driven Development）通用规范与多宿主工具套件**  
+> 规格先行 · 全链路 ID 双向追溯 · S/L 双轨制 · Fresh-Context 独立审查
+
+---
+
+## 📖 核心理念
+
+**「规格是唯一事实来源，代码是规格的可再生产物。」**
+
+在 AI 编码时代，很多开发者陷入了“让 AI 自由发挥、反复打补丁”的泥潭。`newbee-sdd` 提供了一套工业级的规格开发方法论：
+1. **先厘清、后架构、再编码**：通过结构化的规格与验收标准约束 AI，拒绝隐式假设。
+2. **S/L 双轨同构（一脉相承）**：小功能 S 轨单文件极速闭环；大系统 L 轨展开全套架构方案与防御性设计，支持平滑无损升轨。
+3. **全链路 ID 闭环**：`REQ`（需求）↔ `RULE`（规则）↔ `TC`（用例）↔ `TASK`（任务），机器自动化对账，无漏网之鱼。
+4. **多宿主（Multi-Harness）原生兼容**：一套核心资产，同时无缝支持 **dsh**、**OpenCode**、**Claude Code**、**Cursor**、**Codex**。
+
+---
+
+## 🚀 快速上手
+
+### 1. 一键分发安装到本机开发工具
+
+无需全局安装，使用 `npx` 即可将 `newbee-sdd` 规范挂载到您的开发工具中：
+
+```bash
+# 一键安装到本机所有支持的环境（自动检测 dsh / OpenCode / Claude Code / Cursor / Codex）
+npx newbee-sdd install
+
+# 或者仅安装到指定宿主：
+npx newbee-sdd install opencode
+npx newbee-sdd install claude
+npx newbee-sdd install dsh
+npx newbee-sdd install cursor
+npx newbee-sdd install codex
+```
+
+### 2. 在工程中初始化规格骨架
+
+在需要开启规格驱动的项目根目录下执行：
+
+```bash
+npx newbee-sdd init
+```
+将在当前目录生成标准 `newbee-specs/` 目录结构与标准模板文件。
+
+### 3. 运行零 Token 机器自动化校验
+
+```bash
+npx newbee-sdd verify
+```
+自动扫描当前工程规格，校验 `REQ ↔ RULE ↔ TC ↔ TASK` 闭环覆盖度，检查模糊词与未追溯标记 `[untracked]`。
+
+### 4. 一键无痛升级
+
+当 `newbee-sdd` 发布新版本时，升级只需一行命令：
+
+```bash
+npx newbee-sdd update
+```
+> **安全声明**：升级仅同步引擎规范、模板和校验脚本，**绝不触碰或改动您项目既有的任何业务规格工件！**
+
+---
+
+## 🛠️ CLI 命令速查
+
+| 命令 | 别名 | 说明 |
+|---|---|---|
+| `npx newbee-sdd install [target]` | `i` | 安装/挂载规范到指定宿主或全部宿主 |
+| `npx newbee-sdd update` | `u` | 一键无痛升级所有已安装宿主的规范定义 |
+| `npx newbee-sdd verify` | `v` / `check` | 运行纯 Node.js 跨平台追溯链机器自动化校验 |
+| `npx newbee-sdd init` | — | 在当前项目中初始化 `newbee-specs` 模板结构 |
+| `npx newbee-sdd --version` | `-v` | 查看当前发布版本 |
+| `npx newbee-sdd --help` | `-h` | 查看帮助文档 |
+
+---
+
+## 🎯 宿主（Harness）支持矩阵与使用指南
+
+| 宿主工具 | 安装路径与形式 | 运行机制与唤起方式 |
+|:---|:---|:---|
+| **OpenCode** | `~/.config/opencode/skills/newbee-sdd/` | **原生 Skill**：对话中直接提需求或输入 `/newbee-sdd` 唤起；支持 `subagent` 独立复审 |
+| **Claude Code** | `~/.claude/skills/newbee-sdd/` | **官方 Skill**：在对话中说「使用 newbee-sdd 规划...」或输入 `/newbee-sdd` 唤起 |
+| **DeepSeek Harness (dsh)** | `~/.agents/skills/newbee-sdd/` | **深度集成**：挂载 `subagent` 复审、`exit_plan_mode` 批准与本地 PowerShell 脚本 |
+| **Cursor** | `~/.cursor/rules/newbee-sdd.mdc` | **Rules 规则约束**：在 Composer / Chat 中提需求，AI 自动按 S/L 轨生成规范与 ID |
+| **Codex / Copilot** | `~/.codex/skills/newbee-sdd/` | **指令约束**：约束输出严格遵循 REQ/RULE/TC 契约 |
+
+---
+
+## 💡 常用实战对话范例（怎么跟 AI 说）
+
+安装成功后，您可以在各大 AI 编程助手中直接用自然语言与它交互：
+
+### 1. 开启一个新功能规格（S 轨敏捷模式）
+> **你对 AI 说**：  
+> *“我要为用户中心加一个『修改绑定手机号』的功能，比较简单，请按 newbee-sdd 的 S 轨为我生成 spec.md。”*  
+> **AI 的行为**：自动提炼背景，列出 `REQ-001`（带 GWT 验收条件）、`RULE-001`（验证码过期规则）与 `TC-001`（测试用例），并在 `newbee-specs/`（或当前目录）产出完整单文件规格。
+
+### 2. 开启一个复杂系统设计（L 轨深度模式）
+> **你对 AI 说**：  
+> *“我们要重构分布式对账结算系统，涉及外部支付渠道和高并发防重，请按 newbee-sdd 的 L 轨走完整流程。”*  
+> **AI 的行为**：
+> 1. 先进行需求澄清，确认待决问题（Open Questions）；
+> 2. 生成 `spec.md` 并等待你批准（`status: approved`）；
+> 3. 产出 `plan.md`，绘制 C4 模块图，设计超时/重试/幂等防御方案；
+> 4. 产出 `tasks.md`，拆解出带拓扑排序的微任务与 RTM 追溯矩阵。
+
+### 3. 要求独立复审（审查门禁）
+> **你对 AI 说**：  
+> *“请帮我按照 newbee-sdd 的 checklists，严格复审当前的 spec.md。”*  
+> **AI 的行为**：在 OpenCode 等工具中会自动调用 `subagent` 开启全新独立上下文，逐项核对可验证性、模糊词与覆盖率，输出结构化的 FIND 缺陷报告（APPROVE / REQUEST-CHANGES）。
+
+### 4. 本地终端一键机器对账
+> 在终端直接执行：  
+> ```bash
+> npx newbee-sdd verify
+> ```  
+> 0 Token 消耗，纯 Node.js 秒级对账全链路 ID 是否闭环。
+
+---
+
+## 📐 S/L 轨道体系
+
+| 维度 | S 轨（Small - 敏捷紧凑模式） | L 轨（Large - 工业深度流水线） |
+|---|---|---|
+| **适用场景** | 单模块、工作量 ≤ 1 天、无新外部依赖 | 跨模块、涉及高并发/NFR、新增外部集成 |
+| **产出工件** | 单一 `spec.md` 一档闭环 | `spec.md` → `plan.md` (C4/防御设计) → `tasks.md` |
+| **审查机制** | 规则自查 + 机器校验（`verify`） | Fresh-Context 独立子代理复审 + 机器校验 + 人工冻结 |
+| **升轨机制** | — | **平滑无损**：S 轨写到中途可直接解包展开为 L 轨，ID 保持不变 |
+
+---
+
+## 🔗 ID 追溯体系与铁律
+
+全链路采用统一 ID 体系保障可追溯性：
+* `REQ-###`：功能需求（含 Given/When/Then 验收条件）
+* `NFR-###`：非功能需求（量化指标 + 量测方式）
+* `RULE-###`：业务规则约束
+* `DEC-###`：关键决策记录（含 Context 与 Consequences）
+* `MOD-###`：系统模块与职责划分（单一职责）
+* `TC-###`：测试用例（100% 覆盖 REQ 与 RULE）
+* `TASK-###`：拆解任务（单人 0.5~2 天，可独立验收）
+* `FIND-###`：审查发现问题（强制二选一：转正为 ID 追踪 或 负责人书面豁免）
+
+---
+
+## 📦 发布到 npm
+
+在发布之前，可进行本地测试：
+
+```bash
+# 本地测试 CLI
+node bin/newbee-sdd.js --help
+
+# 验证机器检查功能
+node bin/newbee-sdd.js verify
+
+# 发布到 npm 官方仓库
+npm publish --access public
+```
+
+---
+
+## 👤 作者与许可证
+
+* **Author**: qieb
+* **License**: MIT

package/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: newbee-sdd
+description: "规格驱动开发工作流（newbee 流派）：规格先行、全链路ID双向追溯（REQ↔RULE↔TC↔TASK）、S/L双轨制（S轨单文件spec / L轨spec+plan+tasks全套）、Fresh-Context客观审查与自动化机器对账。支持 dsh, OpenCode, Claude Code, Cursor, Codex 等多宿主环境。USE FOR: 用户提出新系统/新功能想法、要求编写规格/技术方案/任务拆解、说 spec/plan/tasks/review、在项目中开发新功能。DO NOT USE FOR: 修复已知 Bug 与单行微小改动（走项目既有流程）；检测到项目已有自有 SDD 规范且用户未显式点名时主动让位。"
+license: MIT
+metadata:
+  author: qieb
+  version: "1.0.0"
+  scheme: "newbee-sdd v1"
+---
+
+# newbee-sdd：规格驱动开发（newbee 流派）
+
+规格是唯一事实来源，代码是规格的可再生产物。本规范遵循“薄内核”原则：主入口定义生命周期、质量门禁与铁律契约，细致清单沉淀于 `references/`，标准模板在 `templates/`，自动化检查通过 CLI / 脚本保证。
+
+---
+
+## 触发契约（三道门禁，按序执行）
+
+1. **用户显示意图最高**：用户点名 newbee-sdd → 立即执行；用户声明「按项目既有规范」→ 本规范完全不介入。
+2. **存量让位声明**：若检测到项目存在自有 SDD 规范（如已有 `specs/`、`spec/`、`docs/sdd/`、项目 AGENTS.md 另有声明）且用户未明确点名 → 主动让位，仅报告「检测到项目有自有规格方案，newbee-sdd 待命」。
+3. **Stage 0 确认**：已加载但发现未知或冲突方案痕迹，且用户未明确指示 → 在写入任何新文件之前先向用户确认，绝不猜测。
+
+---
+
+## Stage 0：方案地图（写入任何文件之前必做）
+
+1. **全景扫描**：扫描项目根目录是否存在：`newbee-specs/`、`.newbee-specs-path`、`specs/`、`spec/`、`docs/sdd/`、`spec.md`。
+2. **输出三行报告**：
+   - 自有正本状况（保护不改动）
+   - 项目定制规范（`CONVENTIONS.md`，按其要求执行）
+   - newbee 默认生效项（其余规则）
+3. **工件根解析**：
+   - 若项目根目录有 `.newbee-specs-path`（包含单行绝对路径）→ 以其指向为准；若指向无效 → **明确报错停下（fail-loud）**。
+   - 若无上述声明 → 默认使用 `<项目根>\newbee-specs\` 或既有规格目录。
+4. **断点续跑与编号**：新功能夹层编号取现有最大编号 + 1（如 `001-xxx`）；已有工件按 `scheme: newbee-sdd v1` 进行领地认领，不重复创建。
+
+---
+
+## 轨道选择（S 轨与 L 轨一脉相承）
+
+S 轨与 L 轨共享同一元模型与追溯体系，差异仅在展开粒度：
+
+| 轨道 | 判定标准 | 交付工件 | 核心门禁 |
+|---|---|---|---|
+| **S 轨 (Small)** | 单模块/子项目、工作量 ≤ 1 天、无新增外部依赖 | `spec.md` 一档闭环 | 结构自查 + 机器校验（`verify`） |
+| **L 轨 (Large)** | 跨模块、有 NFR 性能要求、新增外部依赖集成 | `spec.md` → `plan.md` → `tasks.md` | 独立 Fresh-Context 评审 + 机器校验 + 人工冻结 |
+
+> **平滑升轨机制**：S 轨写到中途如发现复杂度提升，可直接将各章节展开为 L 轨的独立工件，已有 `REQ/RULE/TC` 标号无需变更，平滑无损。
+
+---
+
+## 阶段与门禁（L 轨走全流程；S 轨完成 1-2 即闭环）
+
+| 阶段 | 阶段名称 | 核心交付工件 | 质量门禁与准出条件 |
+|---|---|---|---|
+| **1** | 需求澄清与规格制定 | `spec.md`（REQ+GWT 验收条件、RULE、DEC、TC 全链路闭环） | Fresh-Context 独立复审 + 机器自动化校验（`verify`） |
+| **2** | 用户评审与需求冻结 | spec.md 状态更新为 `approved` | 用户明确确认并批准，需求正式定格 |
+| **3** | 技术方案与架构设计 | `plan.md`（选型评分矩阵、C4 组件图、外部依赖失败模式） | 关键架构选型向用户确认 |
+| **4** | 任务拆解与 RTM 建立 | `tasks.md`（TASK 清单、依赖拓扑、RTM 矩阵） | 机器校验覆反对账（100% 覆盖） |
+| **5** | 编码实施与代码审查 | 业务代码 + RTM 实现状态回填 | 任务粒度完成 → 代码四维审查（Bug/性能/安全/可维护性） |
+| **6** | 收尾与全链路对账 | 状态更新为 `done`；更新 `INDEX.md` 索引表 | RTM 全闭环，无孤立待决缺陷 |
+
+---
+
+## 多宿主（Multi-Harness）机制挂载与自适应
+
+| 宿主工具 | 特色能力与挂载机制 | 降级机制 |
+|---|---|---|
+| **OpenCode** | 通过 `subagent` 工具执行 Fresh-Context 独立复审；利用机器脚本自动核验 | 无 subagent 时降级为分步自查 |
+| **Claude Code** | 官方 Skill 原生驱动；可调用独立子会话进行代码审查 | 遵循标准指令流 |
+| **dsh (DeepSeek Harness)** | 挂载 `subagent` 复审、`exit_plan_mode` 批准、`goal` 工具跨会话追踪 | 标准命令行对账 |
+| **Cursor** | 作为 `.cursorrules` / `.mdc` 系统规则，严格约束生成格式与追溯 ID | 提示词驱动自检 |
+| **Codex / Copilot** | 作为 Agent 指令或项目规范，约束输出符合 REQ/RULE 契约 | 纯提示词标准模式 |
+
+---
+
+## 核心铁律（不可被覆盖的质量契约）
+
+1. **身份行契约**：工件头部必须包含 `scheme: newbee-sdd v1`，校验工具依此辨识身份。
+2. **全链路追溯 ID 闭环**：`REQ ↔ RULE ↔ TC ↔ TASK` 必须双向可追；未追溯内容标记 `[untracked]` 并需人工裁决。
+3. **报错不回退（fail-loud）**：配置错误、指针失效时直接报错停下，绝不静默回退猜测。
+4. **写审分离原则**：在支持的宿主中，复审必须使用全新上下文（Fresh Context），审者不得既当运动员又当裁判员。
+5. **门禁只严不宽**：项目 `CONVENTIONS.md` 只允许对标准进行加严，绝不允许削减核心门禁。
+6. **编号终身制**：REQ/RULE/TC 标号一旦生效不可更改或复用；废弃条目标注 `superseded`，历史有迹可循。
+
+---
+
+## 状态机规范
+
+功能夹层的生命周期状态标记在 `spec.md` 的 frontmatter 中：
+
+```text
+draft (草稿) ──▶ approved (已冻结) ──▶ implementing (实施中) ──▶ done (已完成)
+                       │                       │
+                       └───▶ blocked (阻断) ───┘
+                                 │
+                      deprecated (已废弃，夹层保留)
+```
+
+- `approved`：需求冻结，除修复笔误外，业务变更加写变更记录。
+- `implementing`：实施中仅允许回填 tasks 进度与 RTM 提交哈希，不擅改 spec/plan 内容。
+
+---
+
+## 常用命令与辅助工具
+
+项目安装本 npm 包后，可在终端直接使用：
+
+```bash
+# 校验当前项目规格的追溯闭环性与无歧义性（零 Token 消耗）
+npx newbee-sdd verify
+
+# 在当前工程快速初始化 newbee-specs 结构
+npx newbee-sdd init
+
+# 一键将规范升级同步至本机所有支持的宿主环境
+npx newbee-sdd update
+```
+
+---
+
+## 卸载与无痕治理
+
+- **卸载**：运行 `npx newbee-sdd uninstall` 或直接删除对应工具的 skill 目录；项目内的 `newbee-specs/` 属于用户数据资产，永久完整保留。
+- **治理档位**：
+  - **A 档（默认推荐）**：`newbee-specs/` 纳入本地 git 管理，若不希望提交远端可在 `.gitignore` 排除。
+  - **B 档**：完全不纳入版本控制（用户自担数据丢失风险）。
+  - **C 档**：通过 `.newbee-specs-path` 将工件存储在代码仓外部的专用目录。

package/bin/newbee-sdd.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const { installAll, installToTarget, getTargets } = require('../lib/installer');
+const { update } = require('../lib/updater');
+const { verify } = require('../lib/verifier');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+
+const args = process.argv.slice(2);
+const command = args[0] ? args[0].toLowerCase() : 'help';
+
+function printBanner() {
+  console.log(`
+╔═══════════════════════════════════════════════════════════╗
+║                   newbee-sdd  v${pkg.version}                      ║
+║     规格驱动开发工作流 · S/L双轨制 · 全链路ID追溯          ║
+║      支持 dsh / OpenCode / Claude Code / Cursor / Codex   ║
+╚═══════════════════════════════════════════════════════════╝
+`);
+}
+
+function printHelp() {
+  printBanner();
+  console.log(`使用方法:
+  npx newbee-sdd <命令> [选项]
+
+常用命令:
+  install, i [目标]   安装规范到指定或全部宿主 (opencode, claude, dsh, cursor, codex)
+  update, u          一键无痛升级已安装的规范与脚本 (不改动您的已有项目工件)
+  verify, v          机器校验当前项目的追溯链闭环 (REQ ↔ RULE ↔ TC ↔ TASK)
+  init               在当前工程初始化 newbee-specs 目录结构与标准模板
+  version, -v        查看当前版本号
+  help, -h           查看此帮助文档
+
+示例:
+  npx newbee-sdd install           # 一键分发到全部支持的宿主工具
+  npx newbee-sdd install opencode  # 仅安装到 OpenCode
+  npx newbee-sdd update            # 一键升级最新规则
+  npx newbee-sdd verify            # 零 Token 自动化校验当前项目规格
+  npx newbee-sdd init              # 在当前项目新建规格骨架
+`);
+}
+
+function initProject(targetDir = process.cwd()) {
+  console.log(`\n📁 正在初始化 newbee-sdd 规格骨架: ${targetDir}`);
+  const specsDir = path.join(targetDir, 'newbee-specs');
+  if (!fs.existsSync(specsDir)) {
+    fs.mkdirSync(specsDir, { recursive: true });
+  }
+
+  // 复制模板
+  const templatesDir = path.join(PACKAGE_ROOT, 'templates');
+  if (fs.existsSync(templatesDir)) {
+    const tpls = fs.readdirSync(templatesDir);
+    for (const tpl of tpls) {
+      const src = path.join(templatesDir, tpl);
+      const dest = path.join(specsDir, tpl);
+      if (!fs.existsSync(dest)) {
+        fs.copyFileSync(src, dest);
+        console.log(`   + 生成模板: newbee-specs/${tpl}`);
+      } else {
+        console.log(`   - 已存在，跳过覆盖: newbee-specs/${tpl}`);
+      }
+    }
+  }
+
+  console.log(`\n🎉 初始化完成！您可以在 newbee-specs/ 中开始编写规格。\n`);
+}
+
+switch (command) {
+  case 'install':
+  case 'i': {
+    const target = args[1];
+    if (target) {
+      installToTarget(target.toLowerCase(), PACKAGE_ROOT);
+    } else {
+      installAll(PACKAGE_ROOT);
+    }
+    break;
+  }
+
+  case 'update':
+  case 'u': {
+    update(PACKAGE_ROOT);
+    break;
+  }
+
+  case 'verify':
+  case 'v':
+  case 'check': {
+    const res = verify(process.cwd());
+    if (!res.ok) {
+      process.exitCode = 1;
+    }
+    break;
+  }
+
+  case 'init': {
+    initProject(process.cwd());
+    break;
+  }
+
+  case 'version':
+  case '-v':
+  case '--version': {
+    console.log(`v${pkg.version}`);
+    break;
+  }
+
+  case 'help':
+  case '-h':
+  case '--help':
+  default: {
+    printHelp();
+    break;
+  }
+}

package/lib/index.js

@@ -0,0 +1,12 @@
+const { verify, findSpecsDir } = require('./verifier');
+const { installAll, installToTarget, getTargets } = require('./installer');
+const { update } = require('./updater');
+
+module.exports = {
+  verify,
+  findSpecsDir,
+  installAll,
+  installToTarget,
+  getTargets,
+  update
+};

package/lib/installer.js

@@ -0,0 +1,178 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOME = os.homedir();
+const RECORD_FILE = path.join(HOME, '.newbee-sdd-installed.json');
+
+// 定义 5 大宿主目标路径
+function getTargets(baseDir) {
+  return {
+    opencode: {
+      name: 'OpenCode',
+      type: 'skill',
+      path: path.join(HOME, '.config', 'opencode', 'skills', 'newbee-sdd'),
+      desc: 'OpenCode 全局 Skill 目录'
+    },
+    claude: {
+      name: 'Claude Code',
+      type: 'skill',
+      path: path.join(HOME, '.claude', 'skills', 'newbee-sdd'),
+      desc: 'Claude Code 官方 Skill 目录'
+    },
+    dsh: {
+      name: 'DeepSeek Harness (dsh)',
+      type: 'skill',
+      path: path.join(HOME, '.agents', 'skills', 'newbee-sdd'),
+      desc: 'dsh / agents 官方 Skill 目录'
+    },
+    cursor: {
+      name: 'Cursor Rules',
+      type: 'rule',
+      path: path.join(HOME, '.cursor', 'rules', 'newbee-sdd.mdc'),
+      desc: 'Cursor 全局或系统 Rules 规范文件'
+    },
+    codex: {
+      name: 'Codex / Copilot',
+      type: 'skill',
+      path: path.join(HOME, '.codex', 'skills', 'newbee-sdd'),
+      desc: 'Codex / Copilot 规范目录'
+    }
+  };
+}
+
+/**
+ * 递归复制目录内容
+ */
+function copyDirSync(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules' && entry.name !== '.git') {
+        copyDirSync(srcPath, destPath);
+      }
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * 安装核心资产到目标
+ */
+function installToTarget(targetKey, packageRoot) {
+  const targets = getTargets(packageRoot);
+  const target = targets[targetKey];
+  if (!target) {
+    throw new Error(`未知的安装目标: ${targetKey}`);
+  }
+
+  console.log(`📦 正在为 [${target.name}] 安装 newbee-sdd...`);
+
+  if (target.type === 'skill') {
+    // 复制整个 skill 核心 (SKILL.md, references/, templates/, scripts/)
+    if (!fs.existsSync(target.path)) {
+      fs.mkdirSync(target.path, { recursive: true });
+    }
+
+    // 复制文件
+    const filesToCopy = ['SKILL.md', 'upgrade.md', 'README.md'];
+    for (const file of filesToCopy) {
+      const srcFile = path.join(packageRoot, file);
+      if (fs.existsSync(srcFile)) {
+        fs.copyFileSync(srcFile, path.join(target.path, file));
+      }
+    }
+
+    // 复制文件夹
+    const dirsToCopy = ['references', 'templates', 'scripts'];
+    for (const dir of dirsToCopy) {
+      const srcDir = path.join(packageRoot, dir);
+      if (fs.existsSync(srcDir)) {
+        copyDirSync(srcDir, path.join(target.path, dir));
+      }
+    }
+  } else if (target.type === 'rule') {
+    // 为 Cursor 产出适配的 .mdc 规则文件
+    const ruleDir = path.dirname(target.path);
+    if (!fs.existsSync(ruleDir)) {
+      fs.mkdirSync(ruleDir, { recursive: true });
+    }
+
+    const skillContent = fs.readFileSync(path.join(packageRoot, 'SKILL.md'), 'utf8');
+    const mdcHeader = `---
+description: 规格驱动开发（newbee-sdd）：S/L双轨制、ID追溯链（REQ/RULE/TC/TASK）
+globs: **/*
+---
+
+`;
+    fs.writeFileSync(target.path, mdcHeader + skillContent, 'utf8');
+  }
+
+  console.log(`   ✅ 安装成功 -> ${target.path}`);
+  recordInstalledTarget(targetKey, target.path);
+}
+
+/**
+ * 记录已安装的目标
+ */
+function recordInstalledTarget(key, installedPath) {
+  let records = {};
+  if (fs.existsSync(RECORD_FILE)) {
+    try {
+      records = JSON.parse(fs.readFileSync(RECORD_FILE, 'utf8'));
+    } catch (e) {
+      records = {};
+    }
+  }
+  records[key] = {
+    path: installedPath,
+    installedAt: new Date().toISOString()
+  };
+  fs.writeFileSync(RECORD_FILE, JSON.stringify(records, null, 2), 'utf8');
+}
+
+/**
+ * 获取安装记录
+ */
+function getInstalledRecords() {
+  if (!fs.existsSync(RECORD_FILE)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(RECORD_FILE, 'utf8'));
+  } catch (e) {
+    return {};
+  }
+}
+
+/**
+ * 全量安装到所有支持的目标
+ */
+function installAll(packageRoot) {
+  const targets = getTargets(packageRoot);
+  console.log(`\n🚀 开始多环境分发 newbee-sdd 规范...`);
+  console.log(`📋 支持平台: OpenCode, Claude Code, dsh, Cursor, Codex\n`);
+
+  for (const key of Object.keys(targets)) {
+    try {
+      installToTarget(key, packageRoot);
+    } catch (err) {
+      console.error(`   ❌ [${targets[key].name}] 安装遇到问题: ${err.message}`);
+    }
+  }
+
+  console.log(`\n🎉 安装完成！所有平台已全部挂载 newbee-sdd 规范。\n`);
+}
+
+module.exports = {
+  getTargets,
+  installToTarget,
+  installAll,
+  getInstalledRecords
+};

package/lib/updater.js

@@ -0,0 +1,40 @@
+const fs = require('fs');
+const path = require('path');
+const { getTargets, installToTarget, getInstalledRecords } = require('./installer');
+
+/**
+ * 执行无痛升级逻辑
+ */
+function update(packageRoot) {
+  console.log(`\n🔄 [newbee-sdd] 正在检查已安装的宿主环境与升级规则...`);
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  console.log(`📌 当前最新发布版本: v${pkg.version}`);
+
+  const records = getInstalledRecords();
+  const installedKeys = Object.keys(records);
+
+  if (installedKeys.length === 0) {
+    console.log(`💡 未检测到历史安装记录，将自动扫描并执行首次分发...`);
+    const { installAll } = require('./installer');
+    installAll(packageRoot);
+    return;
+  }
+
+  console.log(`🎯 发现已挂载的宿主目标: ${installedKeys.join(', ')}`);
+  console.log(`🛡️  安全声明: 升级仅同步规范定义、模板与校验脚本，绝不触碰您项目已有的 specs/ 工件！\n`);
+
+  for (const key of installedKeys) {
+    try {
+      installToTarget(key, packageRoot);
+    } catch (e) {
+      console.error(`   ❌ 更新 ${key} 失败: ${e.message}`);
+    }
+  }
+
+  console.log(`\n🎉 [newbee-sdd] 所有宿主已成功无痛升级至 v${pkg.version}！\n`);
+}
+
+module.exports = {
+  update
+};