@modus-ai/modus 0.1.4 → 0.1.5

package/templates/hooks/stop-update-skills.py

@@ -8,8 +8,55 @@ to trigger a knowledge write-back.
 import json
 import os
 import sys
+import urllib.request
+import hashlib
+import socket
 from datetime import datetime, timezone
 
+
+def _track(project_dir: str, event: dict) -> None:
+    """Send a usage event to the Modus Collector. Silently swallows all errors."""
+    if os.environ.get("MODUS_ANALYTICS_DISABLED") == "1":
+        return
+    try:
+        import yaml  # type: ignore[import-untyped]
+        config_path = os.path.join(project_dir, "modus", "config.yaml")
+        with open(config_path, encoding="utf-8") as f:
+            config = yaml.safe_load(f) or {}
+        analytics = config.get("analytics") or {}
+        if analytics.get("enabled") is False:
+            return
+        collector_url = (analytics.get("collectorUrl") or "").strip()
+        if not collector_url:
+            return
+        token = (analytics.get("token") or "").strip()
+        try:
+            import subprocess
+            email = subprocess.check_output(
+                ["git", "config", "--global", "user.email"],
+                timeout=2, stderr=subprocess.DEVNULL
+            ).decode().strip()
+            user_id = hashlib.md5(email.encode()).hexdigest()[:16] if email else None
+        except Exception:
+            user_id = hashlib.md5(socket.gethostname().encode()).hexdigest()[:16]
+
+        body = json.dumps({
+            **event,
+            "user_id": user_id,
+            "project_id": config.get("tapdProjectId"),
+            "team_name": config.get("teamName"),
+        }).encode()
+        req = urllib.request.Request(
+            f"{collector_url}/track",
+            data=body,
+            headers={"Content-Type": "application/json",
+                     **({"Authorization": f"Bearer {token}"} if token else {})},
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=2)
+    except Exception:
+        pass
+
 TRACKED_ARTIFACTS = [
     "01-analysis.md",
     "02-sprint-contract.md",
@@ -70,6 +117,17 @@ def main() -> int:
         print(json.dumps({"continue": True}))
         return 0
 
+    # Report each newly detected subagent artifact to the analytics collector
+    for item in pending:
+        for artifact in item["new_artifacts"]:
+            sub_agent = artifact.replace(".md", "").replace("-", "")[:32]
+            _track(project_dir, {
+                "event_type": "subagent.executed",
+                "sub_agent": sub_agent,
+                "result": "success",
+                "payload": {"story_id": item["story_id"]},
+            })
+
     lines = ["[Modus] 检测到以下 Harness 产出物尚未同步到 Skills 知识库："]
     for item in pending:
         lines.append(f"  Story {item['story_id']}: {', '.join(item['new_artifacts'])}")

package/templates/skills/modus-auto/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: modus-auto
+description: Use this skill when executing /modus:auto command. Reads a TAPD Story URL, scores it across 4 dimensions (complexity/risk/clarity/contract-impact), recommends the best Modus mode (vibe/plan/spec/harness), presents reasoning, waits for human mode selection, then auto-launches the chosen mode with context pre-filled. Trigger on /modus:auto command.
+allowed-tools: Read, Write, Glob, Bash
+disable: false
+---
+
+# modus-auto（智能模式推荐）
+
+**触发条件：** 用户运行 `/modus:auto [TAPD Story URL]` 时使用此 Skill。
+
+## 职责
+
+读取 TAPD Story 内容，从四个维度评分，推荐最合适的 Modus 模式（vibe/plan/spec/harness），展示推荐理由和备选对比，等待用户选择，确认参数后自动透传 TAPD 内容启动所选模式。
+
+---
+
+## 执行流程
+
+### Step 1：读取 TAPD Story
+
+通过 TAPD MCP 读取 Story 内容：
+
+```bash
+# 从 URL 提取 story-id，调用 TAPD MCP 获取内容
+story_id = extract_from_url(tapd_url)
+story = tapd_mcp.get_story(story_id)
+```
+
+提取以下字段：
+- 标题、描述、验收标准
+- 优先级、预估工时
+- 涉及模块（从标题/描述中判断）
+- 迭代/Sprint 信息
+
+若 TAPD MCP 不可用，提示用户手动粘贴 Story 内容，继续执行。
+
+### Step 2：读取知识目录
+
+读取 `modus/knowledge-catalog.md`，了解可用的业务 Skill 及其成熟度。用于判断哪些域已有充足上下文。
+
+### Step 3：四维评分
+
+对 Story 内容进行结构化分析，输出每个维度的评分：
+
+#### 维度一：复杂度 (Complexity)
+
+| 分值 | 判定条件 |
+|------|----------|
+| 低 (1) | 单文件修改、bug fix、文案/配置调整 |
+| 中 (2) | 1-2 个业务域、5 个以内文件变更、新增接口但无架构变化 |
+| 高 (3) | 跨 3+ 个域、需新建数据表、涉及消息队列/异步流程 |
+
+判断依据：Story 描述中的关键词（"新增表"、"重构"、"接入 MQ"、涉及文件数估算）
+
+#### 维度二：风险 (Risk)
+
+| 分值 | 判定条件 |
+|------|----------|
+| 低 (1) | 纯新增功能，不修改现有逻辑 |
+| 中 (2) | 修改已有接口或业务逻辑，影响单一模块 |
+| 高 (3) | 涉及支付/权限/多租户隔离/金额计算/数据迁移/接口废弃 |
+
+#### 维度三：需求明确度 (Clarity)
+
+| 分值 | 判定条件 |
+|------|----------|
+| 高 (3) | 验收标准完整（有具体输入输出）、边界条件明确 |
+| 中 (2) | 有基本描述，部分细节待确认 |
+| 低 (1) | 描述模糊、无验收标准、需大量澄清 |
+
+#### 维度四：接口契约影响 (Contract Impact)
+
+| 分值 | 判定条件 |
+|------|----------|
+| 无 (0) | 纯内部逻辑，不影响对外接口 |
+| 有 (1) | 新增接口、修改现有接口签名/返回值、废弃接口 |
+
+### Step 4：判定推荐模式
+
+根据四维评分，按以下判定树确定推荐模式：
+
+```
+复杂度=低 且 风险=低 且 接口契约影响=无
+  → 推荐 vibe（直接编码，无需文档）
+
+复杂度=低/中 且 明确度=高 且 接口契约影响=无
+  → 推荐 plan（功能规划，有 proposal+design+tasks）
+
+任意维度满足以下任一：
+  - 接口契约影响=有
+  - 风险=高
+  - 需要可测试的验收标准
+  → 推荐 spec（规范驱动，含 delta specs + GIVEN/WHEN/THEN）
+
+以下情况推荐 harness：
+  - 明确度=低（需求不清晰，AI 自动分析更可靠）
+  - 复杂度=高 且 风险=高
+  - 用户希望全自动从需求到部署
+  → 推荐 harness（双 Loop 全自动流程）
+```
+
+### Step 5：展示推荐与对比
+
+**输出格式：**
+
+```
+📊 需求分析结果 — {Story 标题}
+─────────────────────────────────────────
+复杂度:     {低/中/高}  — {一句话理由}
+风险:       {低/中/高}  — {一句话理由}
+需求明确度: {低/中/高}  — {一句话理由}
+接口契约:   {无/有}    — {一句话理由}
+
+🎯 推荐模式：/modus:{mode}
+理由：{2-3 句话说明为何这个模式最合适}
+
+📋 其他选项对比：
+  plan    — {适用场景，以及为何当前需求不优先选它}
+  spec    — {适用场景，以及为何当前需求不优先选它}
+  harness — {适用场景，以及为何当前需求不优先选它}
+  vibe    — {适用场景，以及为何当前需求不优先选它}
+
+请选择要使用的模式：
+A. /modus:vibe    — 直接编码
+B. /modus:plan    — 功能规划  ← 推荐
+C. /modus:spec    — 规范驱动开发
+D. /modus:harness — 全自动 Harness
+```
+
+⏸️ **等待用户选择**
+
+### Step 6：二次确认窗口
+
+用户选择模式后，展示参数确认窗口：
+
+**若选择 vibe：**
+```
+确认参数：
+  任务描述: {从 Story 标题/描述提取的一句话任务描述}
+  涉及业务域: {自动判断的域列表}
+  
+直接开始编码？[Y/n]
+```
+
+**若选择 plan：**
+```
+确认参数：
+  需求描述: {从 Story 内容生成的 plan prompt}
+  涉及域: {order, payment}
+  是否快速模式（跳过 design.md）: [y/N]
+
+确认后将启动 /modus:plan，输入以上描述。[Y/n]
+```
+
+**若选择 spec：**
+```
+确认参数：
+  需求描述: {从 Story 内容生成的 spec prompt}
+  涉及域: {order}
+  规格级别: Full（因为涉及接口契约变更）/ Lite（--lite flag）
+
+确认后将启动 /modus:spec，输入以上描述。[Y/n]
+```
+
+**若选择 harness：**
+```
+确认参数：
+  TAPD Story URL: {原始 URL}
+  将直接透传给 /modus:harness
+
+确认？[Y/n]
+```
+
+⏸️ **等待用户确认**
+
+### Step 7：启动所选模式
+
+用户确认后，根据选择自动触发对应模式：
+
+- **vibe**：以已整理的任务描述调用 `/modus:vibe`，上下文包含 Story 摘要
+- **plan**：以整理好的 prompt 调用 `/modus:plan`，自动跳过 Step 3 的澄清阶段（已通过 auto 确认）
+- **spec**：以整理好的 prompt 调用 `/modus:spec`，携带 Story 验收标准作为 Scenario 参考输入
+- **harness**：直接调用 `/modus:harness {tapd_url}`
+
+---
+
+## 四维评分快速参考卡
+
+| 模式 | 适用场景 | 不适合场景 |
+|------|----------|-----------|
+| `vibe` | 单文件改动、低风险 bug fix | 需要文档沉淀的功能 |
+| `plan` | 明确需求、中等复杂度、无接口契约变更 | 需要可测试规格、高风险 |
+| `spec` | 接口变更、高风险、需要 GIVEN/WHEN/THEN 验收 | 简单 bug fix、模糊需求 |
+| `harness` | 模糊需求、高复杂高风险、需要全自动流程 | 紧急小改动 |
+
+---
+
+## 无 TAPD URL 时的处理
+
+若用户直接运行 `/modus:auto`（不带 URL），提示：
+
+```
+请提供 TAPD Story URL，例如：
+  /modus:auto https://tapd.cn/company/stories/view/1234567890
+
+或粘贴 Story 内容（以 ---END--- 结束输入）：
+```
+
+接受手动粘贴的 Story 内容，跳过 MCP 读取，直接进入 Step 3 分析。

package/templates/skills/modus-init/SKILL.md

@@ -23,6 +23,75 @@ disable: false
 
 若 `modus/config.yaml` 不存在，将在 Step 5 创建默认配置。
 
+### Step 0.5：扫描已有 AI 工具配置
+
+在扫描业务代码之前，先读取项目中已有的 AI 工具配置文件，将存量规则、上下文和 MCP 配置融入 Modus 知识库，避免重复发明轮子。
+
+#### 扫描目标清单
+
+按优先级逐一检查以下路径是否存在：
+
+| 工具 | 检查路径 | 提取内容 |
+|------|---------|----------|
+| **Claude Code** | `CLAUDE.md`、`.claude/CLAUDE.md`、`CLAUDE.local.md` | 项目规则、技术栈、构建命令、命名约定 |
+| **Claude Code** | `.claude/rules/*.md`、`.claude/rules/*.mdc` | 路径级别的细粒度规则 |
+| **Claude Code** | `.claude/settings.json` | MCP 服务器配置 |
+| **Claude Code** | `.claude/commands/*.md` | 已有自定义斜杠命令（避免重复生成） |
+| **Cursor** | `.cursor/rules/*.md`、`.cursor/rules/*.mdc` | 项目规则（含 frontmatter `description`/`globs`） |
+| **Cursor** | `.cursor/mcp.json` | MCP 服务器配置 |
+| **Cursor** | `AGENTS.md`（根目录或子目录） | Agent 指令说明 |
+| **CodeBuddy** | `.codebuddy/rules/*.mdc` | 项目规则 |
+| **CodeBuddy** | `.codebuddy/settings.json` | MCP 服务器配置 |
+| **Continue.dev** | `.continue/config.json`、`.continue/config.yaml` | 上下文提供者、模型配置 |
+| **OpenCode** | `AGENT.md`、`.claude-internal/AGENT.md` | 项目 Agent 指令 |
+
+#### 提取与融合规则
+
+读取上述文件后，执行以下归类：
+
+1. **项目描述 / 背景**（`context` 字段）
+   - 从 `CLAUDE.md` / `AGENTS.md` 的开头段落提取项目一句话描述
+   - 若 `modus/config.yaml` 中 `context` 为空，自动填入（需用户确认）
+
+2. **技术栈信息**（`techStack` 字段）
+   - 从 `CLAUDE.md` 中寻找构建命令、框架名称等技术栈线索
+   - 与代码文件检测结果合并，用于 Step 5 的技术知识 Skill
+
+3. **编码规范 / 团队约定**（→ `modus-team-conventions` Skill）
+   - 将各工具中找到的约定规则（命名规范、禁止模式、最佳实践等）汇总
+   - 在 Step 4 生成团队约定 Skill 时，把这些规则作为**基础输入**，标注来源（如 `[来源: .cursor/rules/naming.mdc]`）
+   - 避免重复：如果规则已在其他 Skill 中描述，仅添加引用
+
+4. **MCP 服务器配置**（→ `modus/config.yaml` `mcpServers` 字段）
+   - 若 `modus init` CLI 已自动检测并写入 `mcpServers`，则跳过
+   - 否则从 `.claude/settings.json` / `.cursor/mcp.json` 提取，写入 `modus/config.yaml`
+
+5. **已有自定义命令**（仅记录，不重复生成）
+   - 列出 `.claude/commands/` 中已有的命令名称
+   - 在 `/modus:init` 完成回报中提示用户这些命令已存在
+
+#### 向用户展示扫描结果
+
+```
+🔍 扫描已有 AI 工具配置...
+
+✓ Claude Code — 找到 3 个文件
+    CLAUDE.md（项目指令 + 构建命令）
+    .claude/rules/java-conventions.mdc（Java 编码规范）
+    .claude/settings.json（MCP: tapd, git）
+
+✓ Cursor — 找到 2 个文件
+    .cursor/rules/naming.mdc（命名规范）
+    .cursor/mcp.json（MCP: tapd）
+
+将把以上规则融入 modus-team-conventions Skill，MCP 配置写入 modus/config.yaml。
+继续？[Y/n]
+```
+
+若用户确认，继续 Step 1；若无任何已有配置，直接进入 Step 1。
+
+---
+
 ### Step 1：项目扫描与业务分类
 
 启动一个「项目分析 SubAgent」，执行以下操作：
@@ -59,35 +128,79 @@ disable: false
 - 增加遗漏的业务域
 - 删除不需要的域
 
-### Step 3：生成业务 Skill（Layer 2）
+### Step 3：生成业务 Skill（Layer 2）—— 并行执行
 
-用户确认后，为每个业务域调用「Skills Builder SubAgent」（`modus-harness-00-skills-builder` Skill，模式 A），生成对应的业务 Skill 文件：
+用户确认后，**同时**为每个业务域启动独立的「Skills Builder SubAgent」（`modus-harness-00-skills-builder` Skill，模式 A），并行生成所有业务 Skill 文件。各域之间完全独立，无需等待彼此完成。
 
 **目标路径：** `.codebuddy/skills/modus-biz-{domain}/SKILL.md`
 
+**并行调度规则：**
+
+```
+用户确认域列表后，立即并行启动 N 个 SubAgent：
+
+SubAgent-1 (order域)   ──► 扫描订单相关文件 ──► 生成 modus-biz-order/SKILL.md
+SubAgent-2 (payment域) ──► 扫描支付相关文件 ──► 生成 modus-biz-payment/SKILL.md
+SubAgent-3 (user域)    ──► 扫描用户相关文件 ──► 生成 modus-biz-user/SKILL.md
+          │                                              │
+          └──────────────── 所有 SubAgent 完成 ──────────┘
+                                    ↓
+                         进入 Step 4（串行）
+```
+
+**每个 SubAgent 的任务（模式 A 标准流程）：**
+1. 接收域名称 + 代表性文件路径列表（来自 Step 1 的分析结果）
+2. 深度扫描该域的 Service/Manager/Mapper/Domain/Entity 层文件
+3. 提取：核心实体、业务规则、API 契约、关键代码模式
+4. 生成标准格式的 Skill 文件（含 `key_files`、`maturity: draft`）
+
+**聚合等待：** 所有 SubAgent 完成后，收集各 SubAgent 的完成状态摘要，在主流程中汇总展示：
+
+```
+✓ modus-biz-order   已生成（8 个 key_files，5 条业务规则，3 个 API）
+✓ modus-biz-payment 已生成（6 个 key_files，4 条业务规则，2 个 API）
+✓ modus-biz-user    已生成（5 个 key_files，3 条业务规则，4 个 API）
+```
+
 每个 Skill 文件遵循 Business Skill 标准格式（含 maturity/last_referenced/usage_count 字段）。
 
 ### Step 4：生成团队约定 Skill（Layer 0-T）
 
 调用「Skills Builder SubAgent」（模式 E：团队约定初始化）：
 
-从以下来源提取团队规范：
-1. 项目中已有的 `CONTRIBUTING.md`、`.editorconfig`、`checkstyle.xml`、`pmd.xml` 等规范文件
-2. `modus/config.yaml` 中的 `constitution.hard_rules`
-3. 代码中高频出现的注解模式（如 `@Transactional`、`@DistributedLock` 的用法）
+从以下来源提取团队规范（**按优先级排列**）：
+
+1. **Step 0.5 扫描结果**（最高优先级）
+   - 从 `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/` / `.codebuddy/rules/` 提取的编码规范
+   - 每条规则注明来源，例如：`[来源: .cursor/rules/naming.mdc]`
+   - 若同一规则在多个工具中重复，合并为一条并列出所有来源
+
+2. 项目中已有的 `CONTRIBUTING.md`、`.editorconfig`、`checkstyle.xml`、`pmd.xml` 等规范文件
+
+3. `modus/config.yaml` 中的 `constitution.hard_rules`
+
+4. 代码中高频出现的注解模式（如 `@Transactional`、`@DistributedLock` 的用法）
 
 生成文件：`.codebuddy/skills/modus-team-conventions/SKILL.md`
 
+**注意：** 若 Step 0.5 中已有来自其他工具的规则，在 Skill 文件开头添加来源声明：
+```markdown
+> 本 Skill 融合了以下 AI 工具的已有配置：Claude Code (CLAUDE.md)、Cursor (.cursor/rules/)
+> 原始文件保持不变，Modus 仅在此处做统一索引。
+```
+
 ### Step 5：生成技术知识 Skill（Layer 1）
 
-调用「Skills Builder SubAgent」（模式 E：技术知识初始化），初始化一个空的技术知识骨架：
+调用「Skills Builder SubAgent」（模式 E：技术知识初始化），初始化技术知识骨架：
 
 生成文件：`.codebuddy/skills/modus-tech-wiki/SKILL.md`
 
-初始内容包含：
-- 已发现的技术栈（从 `pom.xml` 或 `build.gradle` 提取）
-- 框架版本信息
-- 占位符章节（反模式库、架构决策、跨项目经验——待后续工作流积累）
+初始内容来源（按优先级）：
+1. **Step 0.5 扫描结果中的技术信息**
+   - `CLAUDE.md` 中记录的构建命令、测试命令（如 `mvn test`、`npm run test`）
+   - `.continue/config.json` 中的模型/上下文提供者配置
+2. 从构建文件提取的技术栈（`pom.xml` → Spring Boot 版本、`package.json` → 框架版本等）
+3. 占位符章节（反模式库、架构决策、跨项目经验——待后续工作流积累）
 
 ### Step 6：生成知识全景目录（knowledge-catalog.md）
 
@@ -151,6 +264,11 @@ constitution:
 ```
 ✅ Modus 知识库初始化完成
 
+已融合的已有 AI 工具配置（若有）：
+  Claude Code  — CLAUDE.md + .claude/rules/ (3 条规则已写入 modus-team-conventions)
+  Cursor       — .cursor/rules/ (2 条规则已写入 modus-team-conventions)
+  MCP 服务器   — tapd (来自 .claude/settings.json) 已写入 modus/config.yaml
+
 生成了 N 个业务 Skill（Layer 2）：
 - .codebuddy/skills/modus-biz-order/SKILL.md    [draft]
 - .codebuddy/skills/modus-biz-payment/SKILL.md  [draft]
@@ -158,6 +276,7 @@ constitution:
 
 初始化基础 Skill：
 - .codebuddy/skills/modus-team-conventions/SKILL.md  (Layer 0-T) [draft]
+  └─ 融合来源：CLAUDE.md, .cursor/rules/, CONTRIBUTING.md, 代码注解模式
 - .codebuddy/skills/modus-tech-wiki/SKILL.md          (Layer 1)   [draft]
 
 知识目录：
@@ -166,6 +285,9 @@ constitution:
 💡 建议：填写 modus/config.yaml 中的 constitution 字段，
    记录项目硬性约束（技术栈、命名规范等），后续所有命令将自动加载。
 
+已有自定义命令（不会与 Modus 命令冲突）：
+  .claude/commands/deploy.md、.claude/commands/review.md（来自 Claude Code）
+
 现在可以使用：
   /modus:vibe  — 氛围编程（自动加载业务上下文）
   /modus:plan  — 功能规划