spectra-cli 4.1.1

package/plugins/spectra/skills/spectra-batch/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: spectra-batch
+description: |
+  Use this skill when the user asks to:
+  - Generate specs for an entire project or codebase
+  - Document all modules systematically
+  - Create a complete specification index for the project
+  - Batch process multiple modules for spec generation
+  This skill generates an architecture overview index, then iterates through modules producing individual .spec.md files.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Systematically reverse-engineer specs for an entire codebase. Generates an index spec with architecture overview, then iterates through modules producing individual .spec.md files.
+
+## Execution Flow
+
+### 1. Project Survey
+
+Scan the project root to understand structure:
+
+1. **Detect project type**: monorepo, single app, library, CLI, etc.
+2. **Identify top-level modules**: `src/` subdirectories, packages in monorepo, major feature folders
+3. **Estimate total scope**: file count, LOC per module
+4. **Detect existing specs**: Check `specs/` directory for already-generated specs
+
+### 2. Generate Batch Plan
+
+Present the analysis plan to the user:
+
+```markdown
+## Spectra Batch Plan
+
+**Project**: <name>
+**Type**: <project type>
+**Total scope**: N files, ~N LOC
+
+### Modules to analyze (in dependency order):
+
+| # | Module | Files | LOC | Existing Spec? | Priority |
+|---|--------|-------|-----|----------------|----------|
+| 1 | core/utils | 5 | 320 | No | Foundation |
+| 2 | models/ | 8 | 890 | No | Data layer |
+| 3 | auth/ | 12 | 1450 | Yes (outdated) | Critical |
+| ... | | | | | |
+
+**Estimated effort**: ~N minutes with AI analysis
+
+Proceed with all? Or select specific modules (e.g., "1,3,5" or "auth/ models/")
+```
+
+Wait for user confirmation before proceeding.
+
+### 3. Run Batch Pipeline
+
+Execute the batch pipeline using the globally installed `spectra` CLI:
+
+```bash
+spectra batch
+```
+
+如果需要强制重新生成所有 spec：
+
+```bash
+spectra batch --force
+```
+
+如果需要自定义输出目录：
+
+```bash
+spectra batch --output-dir specs
+```
+
+如果需要指定运行模式（F5 新增，FR-001）：
+
+```bash
+# 完整模式（默认）
+spectra batch --mode=full
+
+# 轻量阅读模式：跳过产品文档层（product-overview、ADR 等），速度更快
+spectra batch --mode=reading
+
+# 纯 AST 模式：跳过所有 LLM 推断，仅保留代码结构分析
+spectra batch --mode=code-only
+```
+
+#### `--mode` 参数说明（FR-001 / FR-007）
+
+| 枚举值 | 说明 | 跳过的生成器 |
+|--------|------|-------------|
+| `full`（默认） | 完整文档生成，包含所有 LLM 推断 | 无 |
+| `reading` | 轻量模式，跳过产品文档层 | `product-overview`、`adrs`、`coverage-audit`、`docs-bundle` |
+| `code-only` | 纯 AST 模式，跳过所有 LLM 推断 | `architecture-overview`、`architecture-ir`、`pattern-hints`、`event-surface`、`runtime-topology`、`product-overview`、`adrs` 等所有 LLM 驱动生成器 |
+
+不传 `--mode` 时默认为 `full`（FR-002）。无效 mode 值会在启动时报错退出（FR-005），日志中包含允许的枚举值列表。运行时日志会输出当前 mode（FR-006）：`[info] batch mode=<full|reading|code-only>`。
+
+**MCP 工具透传**：通过 MCP 工具 `batch` 调用时，同样支持 `mode` 参数（FR-007）：
+```json
+{ "mode": "reading" }
+```
+
+如果需要启用 LLM hyperedge 提取（生成超边，用于 `graph_hyperedges` MCP 工具）：
+
+```bash
+spectra batch --hyperedges
+```
+
+#### Hyperedges 相关选项与环境变量
+
+| 选项 / 环境变量 | 类型 | 说明 |
+|---|---|---|
+| `--hyperedges` | CLI flag | 启用 LLM hyperedge 提取；等价于设置 `SPECTRA_HYPEREDGES_ENABLED=true` |
+| `SPECTRA_HYPEREDGES_ENABLED` | `true` \| `false` | 环境变量方式控制 hyperedge 提取（默认 `false`） |
+| `SPECTRA_EMBEDDING_PROVIDER` | `local` \| `openai` | 语义嵌入提供方（默认 `local`；选 `openai` 时需要 `OPENAI_API_KEY`） |
+| `OPENAI_API_KEY` | string | 仅当 `SPECTRA_EMBEDDING_PROVIDER=openai` 时需要提供 |
+
+**注意**：启用 `--hyperedges` 会额外调用 LLM 对 design-doc 进行超边提取，会增加 token 消耗和批量运行时间。建议仅在需要架构流程分析时启用。
+
+如果需要生成交互式图谱可视化（F5 新增，FR-018 ~ FR-024）：
+
+```bash
+# 生成 graph.html 可视化文件
+spectra batch --html
+
+# 可与 --mode 组合使用
+spectra batch --mode=reading --html
+```
+
+#### `--html` 参数说明（FR-018 ~ FR-024）
+
+`--html` 会在 batch 完成后，在 `<outputDir>/_meta/graph.html` 生成单文件离线交互图谱。
+
+| 特性 | 说明 |
+|------|------|
+| 力导向布局 | 节点数 < 2000 时启用 D3 力导向，节点可拖动 |
+| 大图静态模式 | 节点数 ≥ 2000 时切换为静态坐标模式，并显示顶部横幅提示 |
+| 搜索/过滤 | 搜索框支持节点名称过滤，匹配节点高亮，其余节点淡出 |
+| 跳转 Spec | 点击节点后侧边栏显示详情，含 "打开 Spec 文件" 按钮（指向 `.spec.md`） |
+| Hyperedge 凸包 | 若图谱含超边数据，渲染凸包轮廓并支持悬浮 tooltip |
+| 零 CDN | 单文件自包含，所有资源内联，可断网离线使用 |
+| 体积警告 | 文件超 5 MB 时输出 `[warn]` 日志，但不阻断生成 |
+
+### 4. Final Summary
+
+After batch completes:
+
+```markdown
+## Batch Spectra Complete
+
+**Generated**: N/M specs
+**Index**: specs/_index.spec.md
+**Total time**: ~N minutes
+
+### Generated Specs:
+- specs/auth.spec.md (high confidence)
+- specs/models.spec.md (medium confidence)
+- specs/api.spec.md (skipped by user)
+
+### Project-Wide Observations:
+- <Cross-module patterns noticed>
+- <Shared technical debt themes>
+- <Architecture recommendations>
+```
+
+## 语言规范
+
+**所有 spec 文档的正文内容必须使用中文撰写。** 具体规则：
+
+- **用中文**：所有描述、说明、分析、总结、表格内容、注释
+- **保留英文**：代码标识符（函数名、类名、变量名）、文件路径、类型签名、代码块内容
+- **章节标题**：使用中文，例如 `## 1. 意图`、`## 2. 接口定义`
+- **表格表头**：使用中文，例如 `| 模块 | 规格 | 用途 | 依赖 |`
+- **Frontmatter**：保留英文（YAML 键名）
+
+## Guidelines
+
+- 按**依赖顺序**处理模块（基础模块优先）
+- **可恢复**：如果中断，检查已有 specs 并跳过已完成的模块
+- **不重复生成**已存在的 spec，除非用户指定 `--force`
+- 每个模块的 spec 保持**自包含**，但通过索引交叉引用
+
+## 图查询工具（MCP）
+
+Batch 完成后，Spectra 自动生成 `specs/_meta/graph.json` 和 `specs/_meta/GRAPH_REPORT.md`，并暴露 5 个 MCP 图查询工具。在支持 MCP 的 AI 助手中可直接调用：
+
+### `graph_query` — 关键词子图查询
+
+按自然语言查询词匹配节点并扩展邻居子图。
+
+- 用途：探索"认证模块"、"数据库连接"等抽象主题的相关代码
+- 典型调用：`graph_query({ question: "认证模块", budget: 30, depth: 2 })`
+- 返回：JSON 格式的节点和边列表
+
+### `graph_node` — 单节点详情
+
+查询某个节点的详细信息和直接邻居。
+
+- 用途：追踪某个函数、模块或类的完整影响范围
+- 典型调用：`graph_node({ id: "src/auth/login.ts", budget: 20 })` 或 `graph_node({ keyword: "login" })`
+- 返回：目标节点元数据 + 邻居列表
+
+### `graph_path` — 最短路径
+
+查找两个节点间的最短调用/依赖路径。
+
+- 用途：理解"模块 A 是如何最终影响到模块 B 的"
+- 典型调用：`graph_path({ source: "src/cli/main.ts", target: "src/db/connection.ts" })`
+- 返回：有序的节点 ID 列表（起点 → 终点）
+
+### `graph_community` — 社区节点查询
+
+列出某个社区（模块聚类）的所有节点，识别代码边界。
+
+- 用途：从社区层面审视架构划分是否合理
+- 典型调用：`graph_community({ communityId: "c-0" })`
+- 返回：该社区下的全部节点
+
+### `graph_god_nodes` — 枢纽节点识别
+
+识别图谱中度数最高的核心节点，定位过度耦合或架构瓶颈。
+
+- 用途：代码审查、重构规划的起点
+- 典型调用：`graph_god_nodes({ limit: 10 })`
+- 返回：按度数降序的节点列表

package/plugins/spectra/skills/spectra-diff/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: spectra-diff
+description: |
+  Use this skill when the user asks to:
+  - Compare code against its spec to find drift
+  - Check if spec is still in sync with code
+  - Find new behaviors not documented in spec
+  - Identify spec items that no longer exist in code
+  - Validate spec accuracy after code changes
+  Useful after code changes to keep specs current, or before refactoring to understand what's changed.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Detect specification drift between a .spec.md and its corresponding source code. Useful after code changes to keep specs current, or before refactoring to understand what's changed.
+
+## Execution Flow
+
+### 1. Parse Arguments
+
+Expected format: `<spec-file> [source-target]`
+
+- `<spec-file>`: Path to existing .spec.md (required)
+- `[source-target]`: Path to source code (optional — inferred from spec's `related_files` frontmatter)
+
+If spec file doesn't exist, suggest running `/spectra` first.
+
+### 2. Run Drift Detection Pipeline
+
+Execute the drift detection using the globally installed `spectra` CLI:
+
+```bash
+spectra diff <spec-file> <source-target>
+```
+
+如果需要自定义输出目录：
+
+```bash
+spectra diff <spec-file> <source-target> --output-dir drift-logs/
+```
+
+流水线自动执行以下步骤：
+1. 从 spec HTML 注释加载基线 `CodeSkeleton`
+2. 对当前源代码进行 AST 分析
+3. 结构差异比较（`compareSkeletons`）
+4. 噪声过滤（空白/注释/import 重排序）
+5. 语义差异评估（LLM，可选）
+6. 组装 `DriftReport` 并写入 `drift-logs/`
+
+### 3. Fallback: Manual Analysis
+
+如果 CLI 流水线不可用（依赖未安装、编译错误等），手动执行：
+
+1. 读取 spec 文件，提取接口定义章节
+2. 对源代码进行 AST 分析
+3. 对比 spec 中的导出符号与当前代码
+4. 按严重级别分类差异：
+   - **HIGH**: 删除的导出（Breaking Change）
+   - **MEDIUM**: 签名修改、行为变更
+   - **LOW**: 新增导出
+
+### 4. Output Drift Report
+
+报告自动写入 `drift-logs/{module}-drift-{date}.md`，包含：
+- YAML frontmatter（spec 路径、源码路径、版本）
+- 汇总统计表（按严重级别和变更类型）
+- 逐项漂移详情（ID、类别、位置、旧/新值、建议更新）
+- 综合建议
+
+### 5. Offer Update
+
+**在任何 spec 更新前必须提示用户确认。**
+
+Ask: "是否需要更新 spec 以匹配当前代码？这将运行 `/spectra` 并使用现有 spec 作为基线。"
+
+Do NOT auto-update. Wait for user confirmation.
+
+## 语言规范
+
+**所有漂移报告的正文内容必须使用中文撰写。** 具体规则：
+
+- **用中文**：所有描述、说明、分析、总结、表格内容、建议
+- **保留英文**：代码标识符（函数名、类名、变量名）、文件路径、类型签名、代码块内容
+- **表格表头**：使用中文，例如 `| 项目 | 类型 | 位置 | 描述 |`
+
+## Guidelines
+
+- 这是**只读分析**——未经用户同意不修改任何文件
+- 关注**语义**差异，而非格式/风格变化
+- 忽略空白、纯注释变更和 import 重排序
+- **突出标记破坏性变更**（删除/修改的公开 API）

package/queries/go.scm

@@ -0,0 +1,54 @@
+;; Go 查询规则
+;; 用于提取函数声明、类型声明、import 语句等
+
+;; 函数声明
+(function_declaration
+  name: (identifier) @export.name
+  parameters: (parameter_list) @export.params
+  result: (_)? @export.result) @export.function
+
+;; 方法声明（含 receiver）
+(method_declaration
+  receiver: (parameter_list) @method.receiver
+  name: (field_identifier) @method.name
+  parameters: (parameter_list) @method.params
+  result: (_)? @method.result) @method.declaration
+
+;; struct 类型声明
+(type_declaration
+  (type_spec
+    name: (type_identifier) @export.name
+    type: (struct_type) @export.struct_body)) @export.struct
+
+;; interface 类型声明
+(type_declaration
+  (type_spec
+    name: (type_identifier) @export.name
+    type: (interface_type) @export.interface_body)) @export.interface
+
+;; 类型别名
+(type_declaration
+  (type_spec
+    name: (type_identifier) @export.name
+    type: (_) @export.alias_type)) @export.type_alias
+
+;; 单行 import
+(import_declaration
+  (import_spec
+    path: (interpreted_string_literal) @import.path)) @import.single
+
+;; 分组 import
+(import_declaration
+  (import_spec_list
+    (import_spec
+      path: (interpreted_string_literal) @import.path)*)) @import.group
+
+;; const 声明
+(const_declaration
+  (const_spec
+    name: (identifier) @export.name)) @export.const
+
+;; var 声明
+(var_declaration
+  (var_spec
+    name: (identifier) @export.name)) @export.var

package/queries/java.scm

@@ -0,0 +1,50 @@
+;; Java 查询规则
+;; 用于提取类声明、接口声明、枚举、record、import 语句等
+
+;; 类声明
+(class_declaration
+  (modifiers)? @export.modifiers
+  name: (identifier) @export.name
+  type_parameters: (type_parameters)? @export.type_params
+  superclass: (superclass)? @export.extends
+  interfaces: (super_interfaces)? @export.implements) @export.class
+
+;; 接口声明
+(interface_declaration
+  (modifiers)? @export.modifiers
+  name: (identifier) @export.name
+  type_parameters: (type_parameters)? @export.type_params) @export.interface
+
+;; 枚举声明
+(enum_declaration
+  (modifiers)? @export.modifiers
+  name: (identifier) @export.name) @export.enum
+
+;; record 声明 (Java 16+)
+(record_declaration
+  (modifiers)? @export.modifiers
+  name: (identifier) @export.name) @export.record
+
+;; 方法声明
+(method_declaration
+  (modifiers)? @member.modifiers
+  type: (_) @member.return_type
+  name: (identifier) @member.name
+  parameters: (formal_parameters) @member.params) @member.method
+
+;; 字段声明
+(field_declaration
+  (modifiers)? @member.modifiers
+  type: (_) @member.type
+  declarator: (variable_declarator
+    name: (identifier) @member.name)) @member.field
+
+;; 构造器声明
+(constructor_declaration
+  (modifiers)? @member.modifiers
+  name: (identifier) @member.name
+  parameters: (formal_parameters) @member.params) @member.constructor
+
+;; import 声明
+(import_declaration
+  (scoped_identifier) @import.path) @import.statement

package/queries/javascript.scm

@@ -0,0 +1,30 @@
+;; JavaScript 查询规则
+;; 基本与 TypeScript 相同，但不含 interface、type_alias、enum
+
+;; 导出函数声明
+(export_statement
+  declaration: (function_declaration
+    name: (identifier) @export.name) @export.function) @export.statement
+
+;; 导出类声明
+(export_statement
+  declaration: (class_declaration
+    name: (identifier) @export.name) @export.class) @export.statement
+
+;; 导出 const/let 变量
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @export.name))) @export.variable
+
+;; export default
+(export_statement
+  "default" @export.default) @export.default_statement
+
+;; re-export
+(export_statement
+  source: (string) @export.source) @export.reexport
+
+;; import 语句
+(import_statement
+  source: (string) @import.source) @import.statement

package/queries/python.scm

@@ -0,0 +1,35 @@
+;; Python 查询规则
+;; 用于提取函数定义、类定义、import 语句、装饰器等
+
+;; 顶层函数定义
+(function_definition
+  name: (identifier) @export.name) @export.function
+
+;; 异步函数定义
+(function_definition
+  "async" @export.async
+  name: (identifier) @export.name) @export.async_function
+
+;; 类定义
+(class_definition
+  name: (identifier) @export.name
+  superclasses: (argument_list)? @export.bases) @export.class
+
+;; import 语句
+(import_statement
+  name: (dotted_name) @import.module) @import.statement
+
+;; from...import 语句
+(import_from_statement
+  module_name: (dotted_name)? @import.module
+  module_name: (relative_import)? @import.relative
+  name: (dotted_name) @import.name) @import.from_statement
+
+;; 装饰器
+(decorated_definition
+  (decorator) @decorator
+  definition: (_) @decorated.definition) @decorated
+
+;; 类型注解
+(type
+  (identifier) @type.name) @type.annotation

package/queries/typescript.scm

@@ -0,0 +1,50 @@
+;; TypeScript 查询规则
+;; 用于提取导出声明、类定义、接口、类型别名、import 语句等
+
+;; 导出函数声明
+(export_statement
+  declaration: (function_declaration
+    name: (identifier) @export.name) @export.function) @export.statement
+
+;; 导出类声明
+(export_statement
+  declaration: (class_declaration
+    name: (type_identifier) @export.name) @export.class) @export.statement
+
+;; 导出接口声明
+(export_statement
+  declaration: (interface_declaration
+    name: (type_identifier) @export.name) @export.interface) @export.statement
+
+;; 导出类型别名
+(export_statement
+  declaration: (type_alias_declaration
+    name: (type_identifier) @export.name) @export.type) @export.statement
+
+;; 导出枚举
+(export_statement
+  declaration: (enum_declaration
+    name: (identifier) @export.name) @export.enum) @export.statement
+
+;; 导出 const/let 变量
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @export.name))) @export.variable
+
+;; export default
+(export_statement
+  "default" @export.default) @export.default_statement
+
+;; re-export
+(export_statement
+  source: (string) @export.source) @export.reexport
+
+;; import 语句
+(import_statement
+  source: (string) @import.source) @import.statement
+
+;; import type
+(import_statement
+  "type" @import.type_only
+  source: (string) @import.source) @import.type_statement

package/scripts/lifecycle-runner.cjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+const { existsSync } = require('node:fs');
+const { resolve } = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const lifecycleName = process.argv[2];
+
+if (!lifecycleName) {
+  console.error('spectra: missing lifecycle script name');
+  process.exit(1);
+}
+
+const targetScript = resolve(__dirname, '..', 'dist', 'scripts', `${lifecycleName}.js`);
+
+if (!existsSync(targetScript)) {
+  console.log(
+    `spectra: skip ${lifecycleName}, build output not found at dist/scripts/${lifecycleName}.js`,
+  );
+  process.exit(0);
+}
+
+const result = spawnSync(process.execPath, [targetScript], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(result.error);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);

package/templates/adr-draft.hbs

@@ -0,0 +1,51 @@
+---
+type: adr
+status: {{status}}
+decisionId: {{decisionId}}
+category: {{category}}
+confidence: {{confidence}}
+generatedBy: spectra adr-pipeline
+sourceTypes:
+{{#each sourceTypes}}
+  - {{this}}
+{{/each}}
+---
+
+# {{decisionId}} {{title}}
+
+## 摘要
+
+{{summary}}
+
+## Decision
+
+{{decision}}
+
+## Context
+
+{{#each context}}
+- {{this}}
+{{/each}}
+
+## Consequences
+
+{{#each consequences}}
+- {{this}}
+{{/each}}
+
+## Alternatives
+
+{{#each alternatives}}
+- {{this}}
+{{/each}}
+
+## Evidence
+
+{{#each evidence}}
+- [{{sourceType}}] {{label}}{{#if path}} ({{path}}){{/if}}: {{excerpt}}
+{{/each}}
+
+## Notes
+
+- 本草稿为候选 ADR，默认状态为 `proposed`
+- {{#if inferred}}部分结论为基于现有事实的推断，请在合并前人工确认{{else}}主要结论已由现有结构化事实直接支撑{{/if}}

package/templates/adr-index.hbs

@@ -0,0 +1,25 @@
+# {{title}}
+
+生成时间: {{generatedAt}}
+
+## 摘要
+
+{{#each summary}}
+- {{this}}
+{{/each}}
+
+## ADR 草稿列表
+
+| ID | 标题 | 分类 | 置信度 | 来源类型 |
+| --- | --- | --- | --- | --- |
+{{#each drafts}}
+| {{decisionId}} | [{{title}}]({{decisionId}}-{{slug}}.md) | {{category}} | {{confidence}} | {{sourceTypes}} |
+{{/each}}
+
+{{#if warnings.length}}
+## Warnings
+
+{{#each warnings}}
+- {{this}}
+{{/each}}
+{{/if}}