clay-good/spec-gen
GitHub: clay-good/spec-gen
一个将代码库逆向工程为结构化规范文档的自动化工具，结合静态分析与 LLM 理解业务逻辑并持续同步。
Stars: 39 | Forks: 7
# spec-gen
从现有代码库逆向工程 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 规范，并在代码演进时保持同步。
## 问题所在
大多数软件没有规范。代码本身就是规范，分散在数千个文件、部落知识和过时的文档中。像 `openspec init` 这样的工具只创建空的脚手架，但仍需人工编写所有内容。等到手动编写完规范，代码早已变更。
spec-gen 使这一过程自动化。它通过静态分析分析您的代码库，使用 LLM 生成结构化规范，并持续检测代码与规范何时失去同步。
## 快速开始
```
# 从 npm 安装
npm install -g spec-gen-cli
# 导航到你的项目
cd /path/to/your-project
# 运行 pipeline
spec-gen init # Detect project type, create config
spec-gen analyze # Static analysis (no API key needed)
spec-gen generate # Generate specs (requires API key)
spec-gen drift # Check for spec drift
```
## 功能概览
**1. 分析** (无需 API key)
使用纯静态分析扫描您的代码库：
- 遍历目录树，遵循 .gitignore，按重要性对文件评分
- 解析导入和导出以构建依赖图
- 自动将相关文件聚类为业务领域
- 生成结构化上下文，使 LLM 生成更准确
**2. 生成** (需要 API key)
将分析上下文发送给 LLM 以生成规范：
- 阶段 1：项目调研与分类
- 阶段 2：实体提取（核心数据模型）
- 阶段 3：服务分析（业务逻辑）
- 阶段 4：API 提取（HTTP 端点）
- 阶段 5：架构综合（整体结构）
- 阶段 6：ADR 增强（架构决策记录，使用 `--adr`）
**3. 验证** (需要 API key)
通过仅根据规范预测文件内容，然后将预测与实际代码进行比较，来测试生成的规范。报告准确度评分并识别差距。
**4. Drift 检测** (无需 API key)
将 git 变更与规范文件映射进行比较以发现偏差：
- **Gap (差距)**：代码已更改但其规范未更新
- **Stale (过时)**：规范引用了已删除或重命名的文件
- **Uncovered (未覆盖)**：新文件没有匹配的规范域
- **Orphaned (孤立)**：规范声明了不再存在的文件
- **ADR gap**：代码在 ADR 引用的域中发生了更改
- **ADR orphaned**：ADR 引用了规范中不再存在的域
## 架构
```
graph TD
subgraph CLI["CLI Layer"]
CMD[spec-gen commands]
end
subgraph API["Programmatic API"]
API_INIT[specGenInit]
API_ANALYZE[specGenAnalyze]
API_GENERATE[specGenGenerate]
API_VERIFY[specGenVerify]
API_DRIFT[specGenDrift]
API_RUN[specGenRun]
end
subgraph Core["Core Layer"]
direction TB
subgraph Init["Init"]
PD[Project Detector]
CM[Config Manager]
end
subgraph Analyze["Analyze -- no API key"]
FW[File Walker] --> SS[Significance Scorer]
SS --> IP[Import Parser]
IP --> DG[Dependency Graph]
DG --> RM[Repository Mapper]
RM --> AG[Artifact Generator]
end
subgraph Generate["Generate -- API key required"]
SP[Spec Pipeline] --> FF[OpenSpec Formatter]
FF --> OW[OpenSpec Writer]
SP --> ADR[ADR Generator]
end
subgraph Verify["Verify -- API key required"]
VE[Verification Engine]
end
subgraph Drift["Drift -- no API key"]
GA[Git Analyzer] --> SM[Spec Mapper]
SM --> DD[Drift Detector]
DD -.->|optional| LE[LLM Enhancer]
end
LLM[LLM Service -- Anthropic / OpenAI / Compatible]
end
CMD --> API_INIT & API_ANALYZE & API_GENERATE & API_VERIFY & API_DRIFT
API_RUN --> API_INIT & API_ANALYZE & API_GENERATE
API_INIT --> Init
API_ANALYZE --> Analyze
API_GENERATE --> Generate
API_VERIFY --> Verify
API_DRIFT --> Drift
Generate --> LLM
Verify --> LLM
LE -.-> LLM
AG -->|analysis artifacts| SP
AG -->|analysis artifacts| VE
subgraph Output["Output"]
SPECS[openspec/specs/*.md]
ADRS[openspec/decisions/*.md]
ANALYSIS[.spec-gen/analysis/]
REPORT[Drift Report]
end
OW --> SPECS
ADR --> ADRS
AG --> ANALYSIS
DD --> REPORT
```
## Drift 检测
Drift 检测是持续规范维护的核心。它在毫秒级内运行，无需 API key，完全基于 git diff 和规范文件映射工作。
```
$ spec-gen drift
Spec Drift Detection
Analyzing git changes...
Base ref: main
Branch: feature/add-notifications
Changed files: 12
Loading spec mappings...
Spec domains: 6
Mapped source files: 34
Detecting drift...
Issues Found: 3
[ERROR] gap: src/services/user-service.ts
Spec: openspec/specs/user/spec.md
File changed (+45/-12 lines) but spec was not updated
[WARNING] uncovered: src/services/email-queue.ts
New file has no matching spec domain
[INFO] adr-gap: openspec/decisions/adr-0001-jwt-auth.md
Code changed in domain(s) auth referenced by ADR-001
Summary:
Gaps: 2
Uncovered: 1
ADR gaps: 1
```
### ADR Drift 检测
当 `openspec/decisions/` 包含架构决策记录时，Drift 检测会自动检查代码更改是否影响 ADR 引用的域。ADR 问题以 `info` 严重级别报告，因为代码更改很少使架构决策失效。被取代和弃用的 ADR 被排除在外。
### LLM 增强模式
静态 Drift 检测能捕捉结构性变化，但无法判断更改是否真正影响规范中记录的行为。变量重命名会触发与真正的行为更改相同的警报。
`--use-llm` 通过将每个文件的 diff 及其匹配的规范发送给 LLM 来后处理 Gap 问题。LLM 将每个 Gap 分类为相关（保留警报）或不相关（降级为 info）。这减少了误报。
```
spec-gen drift # Static mode: fast, deterministic
spec-gen drift --use-llm # LLM-enhanced: fewer false positives
```
## CI/CD 集成
spec-gen 旨在自动化流水线中运行。确定性命令（`init`、`analyze`、`drift`）无需 API key 并产生一致的结果。
### Pre-Commit Hook
```
spec-gen drift --install-hook # Install
spec-gen drift --uninstall-hook # Remove
```
该 Hook 以静态模式运行（快速，无需 API key），并在检测到警告级别或以上的 Drift 时阻止提交。
### GitHub Actions / CI 流水线
```
# .github/workflows/spec-drift.yml
name: Spec Drift Check
on: [pull_request]
jobs:
drift:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history needed for git diff
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install -g spec-gen-cli
- run: spec-gen drift --fail-on error --json
```
```
# 或在任何 CI script 中
spec-gen drift --fail-on error --json # JSON output, fail on errors only
spec-gen drift --fail-on warning # Fail on warnings too
spec-gen drift --domains auth,user # Check specific domains
spec-gen drift --no-color # Plain output for CI logs
```
### 确定性与 LLM 增强
| | 确定性 (默认) | LLM 增强 |
|---|---|---|
| **API key** | 否 | 是 |
| **速度** | 毫秒级 | 每次 LLM 调用数秒 |
| **命令** | `analyze`, `drift`, `init` | `generate`, `verify`, `drift --use-llm` |
| **可复现性** | 每次运行完全相同 | 可能变化 |
| **适用场景** | CI, pre-commit hooks, 快速检查 | 初始生成, 减少误报 |
## LLM 提供商
spec-gen 支持四种提供商。默认为 Anthropic Claude。
| 提供商 | `provider` 值 | API key 环境变量 | 默认模型 |
|----------|-----------------|-----------------|---------------|
| Anthropic Claude | `anthropic` *(默认)* | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
| OpenAI | `openai` | `OPENAI_API_KEY` | `gpt-4o` |
| OpenAI-compatible *(Mistral, Groq, Ollama...)* | `openai-compat` | `OPENAI_COMPAT_API_KEY` | `mistral-large-latest` |
| Google Gemini | `gemini` | `GEMINI_API_KEY` | `gemini-2.0-flash` |
### 选择提供商
在 `.spec-gen/config.json` 的 `generation` 块中设置 `provider`（以及可选的 `model`）：
```
{
"generation": {
"provider": "openai",
"model": "gpt-4o-mini",
"domains": "auto"
}
}
```
单次运行时覆盖模型：
```
spec-gen generate --model claude-opus-4-20250514
```
### OpenAI-compatible 服务器
使用 `provider: "openai-compat"` 配合 base URL 和 API key：
**环境变量：**
```
export OPENAI_COMPAT_BASE_URL=http://localhost:11434/v1 # Ollama, LM Studio, local servers
export OPENAI_COMPAT_API_KEY=ollama # any non-empty value for local servers
# use your real API key for cloud providers (Mistral, Groq...)
```
**配置文件** (按项目)：
```
{
"generation": {
"provider": "openai-compat",
"model": "llama3.2",
"openaiCompatBaseUrl": "http://localhost:11434/v1",
"domains": "auto"
}
}
```
**自签名证书** (内部服务器, VPN 端点)：
```
spec-gen generate --insecure
```
或在 `config.json` 中：
```
{
"generation": {
"provider": "openai-compat",
"openaiCompatBaseUrl": "https://internal-llm.corp.net/v1",
"skipSslVerify": true,
"domains": "auto"
}
}
```
适用于：Ollama, LM Studio, Mistral AI, Groq, Together AI, LiteLLM, vLLM,
text-generation-inference, LocalAI, Azure OpenAI, 以及任何 `/v1/chat/completions` 服务器。
### Anthropic 或 OpenAI 的自定义 Base URL
要将内置的 Anthropic 或 OpenAI 提供商重定向到代理或自托管端点：
```
# CLI (一次性)
spec-gen generate --api-base https://my-proxy.corp.net/v1
# Environment variable
export ANTHROPIC_API_BASE=https://my-proxy.corp.net/v1
export OPENAI_API_BASE=https://my-proxy.corp.net/v1
```
或在 `config.json` 的 `llm` 块中：
```
{
"llm": {
"apiBase": "https://my-proxy.corp.net/v1",
"sslVerify": false
}
}
```
`sslVerify: false` 禁用 TLS 证书验证 —— 仅用于具有自签名证书的内部服务器。
优先级：CLI 标志 > 环境变量 > 配置文件 > 提供商默认值。
## 命令
| 命令 | 描述 | API Key |
|---------|-------------|---------|
| `spec-gen init` | 初始化配置 | 否 |
| `spec-gen analyze` | 运行静态分析 | 否 |
| `spec-gen generate` | 从分析生成规范 | 是 |
| `spec-gen generate --adr` | 同时生成架构决策记录 | 是 |
| `spec-gen verify` | 验证规范准确性 | 是 |
| `spec-gen drift` | 检测规范 Drift (静态) | 否 |
| `spec-gen drift --use-llm` | 检测规范 Drift (LLM 增强) | 是 |
| `spec-gen run` | 完整流水线：init, analyze, generate | 是 |
| `spec-gen view` | 在浏览器中启动交互式图表和规范查看器 | 否 |
| `spec-gen mcp` | 启动 MCP server (stdio, 用于 Cline / Claude Code) | 否 |
### 全局选项
```
--api-base # Custom LLM API base URL (proxy / self-hosted)
--insecure # Disable SSL certificate verification
--config # Config file path (default: .spec-gen/config.json)
-q, --quiet # Errors only
-v, --verbose # Debug output
--no-color # Plain text output (enables timestamps)
```
Generate 特定选项：
```
--model # Override LLM model (e.g. gpt-4o-mini, llama3.2)
```
### Drift 选项
```
spec-gen drift [options]
--base # Git ref to compare against (default: auto-detect)
--files # Specific files to check (comma-separated)
--domains
从源码安装
``` git clone https://github.com/clay-good/spec-gen cd spec-gen npm install && npm run build && npm link ```Nix/NixOS
**直接运行：** ``` nix run github:clay-good/spec-gen -- init nix run github:clay-good/spec-gen -- analyze nix run github:clay-good/spec-gen -- generate ``` **临时 Shell：** ``` nix shell github:clay-good/spec-gen spec-gen --version ``` **系统 Flake 集成：** ``` { inputs.spec-gen.url = "github:clay-good/spec-gen"; outputs = { self, nixpkgs, spec-gen }: { nixosConfigurations.myhost = nixpkgs.lib.nixosSystem { modules = [{ environment.systemPackages = [ spec-gen.packages.x86_64-linux.default ]; }]; }; }; } ``` **开发：** ``` git clone https://github.com/clay-good/spec-gen cd spec-gen nix develop npm run dev ```- # Only check specific domains
--use-llm # LLM semantic analysis
--json # JSON output
--fail-on
- # Only generate specific domains
--merge # Merge with existing specs
--no-overwrite # Skip existing files
--adr # Also generate ADRs
--adr-only # Generate only ADRs
```
### Analyze 选项
```
spec-gen analyze [options]
--output
- # Only verify specific domains
--json # JSON output
```
## MCP Server
`spec-gen mcp` 通过 stdio 将 spec-gen 作为 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器启动，将静态分析作为工具暴露给任何兼容 MCP 的 AI 代理（Cline, Roo Code, Kilocode, Claude Code, Cursor...），无需 API key。
### 设置
**Claude Code** —— 在项目根目录添加 `.mcp.json`：
```
{
"mcpServers": {
"spec-gen": {
"command": "spec-gen",
"args": ["mcp"]
}
}
}
```
或用于本地开发：
```
{
"mcpServers": {
"spec-gen": {
"command": "node",
"args": ["/absolute/path/to/spec-gen/dist/cli/index.js", "mcp"]
}
}
}
```
**Cline / Roo Code / Kilocode** —— 在编辑器的 MCP 设置 JSON 中的 `mcpServers` 下添加相同的块。
### Cline / Roo Code / Kilocode
对于支持 MCP 的编辑器，在设置中添加 `mcpServers` 块后，下载斜杠命令工作流：
```
mkdir -p .clinerules/workflows
curl -sL https://raw.githubusercontent.com/clay-good/spec-gen/main/examples/cline-workflows/spec-gen-analyze-codebase.md -o .clinerules/workflows/spec-gen-analyze-codebase.md
curl -sL https://raw.githubusercontent.com/clay-good/spec-gen/main/examples/cline-workflows/spec-gen-check-spec-drift.md -o .clinerules/workflows/spec-gen-check-spec-drift.md
curl -sL https://raw.githubusercontent.com/clay-good/spec-gen/main/examples/cline-workflows/spec-gen-plan-refactor.md -o .clinerules/workflows/spec-gen-plan-refactor.md
curl -sL https://raw.githubusercontent.com/clay-good/spec-gen/main/examples/cline-workflows/spec-gen-execute-refactor.md -o .clinerules/workflows/spec-gen-execute-refactor.md
curl -sL https://raw.githubusercontent.com/clay-good/spec-gen/main/examples/cline-workflows/spec-gen-implement-feature.md -o .clinerules/workflows/spec-gen-implement-feature.md
curl -sL https://raw.githubusercontent.com/clay-good/spec-gen/main/examples/cline-workflows/spec-gen-refactor-codebase.md -o .clinerules/workflows/spec-gen-refactor-codebase.md
```
可用命令：
| 命令 | 功能 |
|---------|-------------|
| `/spec-gen-analyze-codebase` | 运行 `analyze_codebase`，总结结果（项目类型、文件数量、前 3 个重构问题、检测到的域），显示调用图亮点，并建议下一步。 |
| `/spec-gen-check-spec-drift` | 运行 `check_spec_drift`，按严重性（gap / stale / uncovered / orphaned-spec）展示问题，显示按类型的修复命令，并可选深入查看受影响文件的签名。 |
| `/spec-gen-plan-refactor` | 运行静态分析，选择具有覆盖门槛的最高优先级目标，评估影响和调用图，然后将详细计划写入 `.spec-gen/refactor-plan.md`。无代码更改。 |
| `/spec-gen-execute-refactor` | 读取 `.spec-gen/refactor-plan.md`，建立绿色基线，并逐一应用每个计划的更改 —— 每步之后都有 diff 验证和测试运行。可选的最后一步包括死代码检测和命名对齐（需要 `spec-gen generate`）。 |
| `/spec-gen-implement-feature` | 规划并实现具有完整架构上下文的新功能：架构概览、OpenSpec 需求、插入点、实现和 Drift 检查。 |
| `/spec-gen-refactor-codebase` | 便捷重定向，依次运行 `/spec-gen-plan-refactor` 和 `/spec-gen-execute-refactor`。 |
所有六个命令都会询问要使用的目录，直接调用 MCP 工具，并引导您查看结果而无需离开编辑器。它们适用于任何支持 `.clinerules/workflows/` 约定的编辑器。
### Claude Skills
对于 Claude Code，将技能文件复制到项目的 `.claude/skills/` 中：
```
mkdir -p .claude/skills
curl -sL https://raw.githubusercontent.com/clay-good/spec-gen/main/skills/claude-spec-gen.md -o .claude/skills/claude-spec-gen.md
curl -sL https://raw.githubusercontent.com/clay-good/spec-gen/main/skills/openspec-skill.md -o .claude/skills/openspec-skill.md
```
**Spec-Gen Skill** (`claude-spec-gen.md`) —— 代码考古技能，引导 Claude 完成：
- 项目类型检测和域识别
- 实体提取、服务分析、API 提取
- 架构综合和 OpenSpec 规范生成
**OpenSpec Skill** (`openspec-skill.md`) —— 用于处理 OpenSpec 规范的技能：
- 使用 `search_specs` 进行语义规范搜索
- 使用 `list_spec_domains` 列出域
- 导航需求和场景
### 工具
所有工具均基于**纯静态分析**运行 —— 不消耗 LLM 配额。
**分析**
| 工具 | 描述 | 需要预先分析 |
|------|-------------|:---:|
| `analyze_codebase` | 运行完整静态分析：repo 结构、依赖图、调用图（Hub 函数、入口点、层级违规）和顶级重构优先级。结果缓存 1 小时（`force: true` 以绕过）。 | 否 |
| `get_call_graph` | Hub 函数（高 fan-in）、入口点（无内部调用者）和架构层级违规。支持 TypeScript, JavaScript, Python, Go, Rust, Ruby, Java。 | 是 |
| `get_signatures` | 每个文件的紧凑函数/类签名。使用 `filePattern` 按路径子串过滤。用于在不阅读完整源码的情况下理解模块的公共 API。 | 是 |
| `get_duplicate_report` | 检测重复代码：Type 1（精确克隆）、Type 2（结构化 —— 重命名变量）、Type 3（Jaccard 相似度 >= 0.7 的近似克隆）。按影响排序分组。 | 是 |
**重构**
| 工具 | 描述 | 需要预先分析 |
|------|-------------|:---:|
| `get_refactor_report` | 具有结构性问题的函数优先列表：不可达代码、Hub 过载（高 fan-in）、God 函数（高 fan-out）、SRP 违规、循环依赖。 | 是 |
| `analyze_impact` | 针对特定函数的深度影响分析：fan-in/fan-out、上游调用链、下游关键路径、风险评分 (0-100)、爆炸半径和推荐策略。 | 是 |
| `get_low_risk_refactor_candidates` | 最安全的重构函数：低 fan-in、低 fan-out、非 Hub、无循环参与。增量、低风险会话的最佳起点。 | 是 |
| `get_leaf_functions` | 不进行内部调用的函数（调用图的叶子）。零下游爆炸半径。默认按 fan-in 排序 —— 调用最多的叶子具有最佳的单元测试 ROI。 | 是 |
| `get_critical_hubs` | 按性排名的最高影响 Hub 函数。每个 Hub 获得稳定性评分 (0-100) 和推荐方法：extract, split, facade, 或 delegate。 | 是 |
| `get_god_functions` | 检测项目或特定文件中的 God 函数（高 fan-out，可能是协调者），并返回其调用图邻域。使用此工具识别需要重构的函数并了解要提取哪些逻辑块。 | 是 |
**导航**
| 工具 | 描述 | 需要预先分析 |
|------|-------------|:---:|
| `get_subgraph` | 以函数为中心的深度受限子图。方向：`downstream`（它调用什么）、`upstream`（谁调用它）或 `both`。输出为 JSON 或 Mermaid 图。 | 是 |
| `get_architecture_overview` | 高级集群映射：角色（入口层、协调者、核心实用程序、API 层、内部）、集群间依赖、全局入口点和关键 Hub。无需 LLM。 | 是 |
| `get_function_skeleton` | 源文件的降噪视图：移除日志、内联注释和非 JSDoc 块注释。保留签名、控制流、return/throw 和调用表达式。返回减少百分比。 | 否 |
| `suggest_insertion_points` | 对向量索引进行语义搜索，以在实现新功能时找到最佳的现有函数进行扩展或挂钩。返回带有角色和策略的排名候选。 | 是 (+ `--embed`) |
| `search_code` | 对已索引函数的自然语言语义搜索。按含义返回最接近的匹配项及相似度评分。用于导航不熟悉的代码库。 | 是 (+ `--embed`) |
**规范**
| 工具 | 描述 | 需要预先分析 |
|------|-------------|:---:|
| `get_mapping` | 由 `spec-gen generate` 生成的需求-函数映射。显示哪些函数实现了哪些规范需求、置信度级别以及无规范覆盖的孤立函数。 | 是 (generate) |
| `check_spec_drift` | 检测未反映在 OpenSpec 规范中的代码更改。将 git 更改的文件与规范覆盖图进行比较。问题：gap / stale / uncovered / orphaned-spec / adr-gap。 | 是 (generate) |
| `search_specs` | 对 OpenSpec 规范的语义搜索，按含义查找需求、设计说明和架构决策。返回链接的源文件以进行图形高亮。当被问及“哪个规范涵盖了 X？”或“我们应该在哪里实现 Z？”时使用此工具。需要使用 `spec-gen analyze --embed` 或 `--reindex-specs` 构建的规范索引。 | 是 (generate) |
| `list_spec_domains` | 列出此项目中所有可用的 OpenSpec 域。在进行定向 `search_specs` 调用之前，使用此工具发现存在哪些域。 | 是 (generate) |
### 参数
**`analyze_codebase`**
```
directory string Absolute path to the project directory
force boolean Force re-analysis even if cache is fresh (default: false)
```
**`get_refactor_report`**, **`get_call_graph`**
```
directory string Absolute path to the project directory
```
**`get_signatures`**
```
directory string Absolute path to the project directory
filePattern string Optional path substring filter (e.g. "services", ".py")
```
**`get_subgraph`**
```
directory string Absolute path to the project directory
functionName string Function name to centre on (case-insensitive partial match)
direction string "downstream" | "upstream" | "both" (default: "downstream")
maxDepth number BFS traversal depth limit (default: 3)
format string "json" | "mermaid" (default: "json")
```
*注意：如果未找到精确名称匹配，`get_subgraph` 将回退到语义搜索（当向量索引可用时）以查找最相似的函数。*
**`get_mapping`**
```
directory string Absolute path to the project directory
domain string Optional domain filter (e.g. "auth", "crawler")
orphansOnly boolean Return only orphan functions (default: false)
```
**`get_duplicate_report`**
```
directory string Absolute path to the project directory
```
**`check_spec_drift`**
```
directory string Absolute path to the project directory
base string Git ref to compare against (default: auto-detect main/master)
files string[] Specific files to check (default: all changed files)
domains string[] Only check these spec domains (default: all)
failOn string Minimum severity to report: "error" | "warning" | "info" (default: "warning")
maxFiles number Max changed files to analyze (default: 100)
```
**`list_spec_domains`**
```
directory string Absolute path to the project directory
```
**`analyze_impact`**
```
directory string Absolute path to the project directory
symbol string Function or method name (exact or partial match)
depth number Traversal depth for upstream/downstream chains (default: 2)
```
*注意：如果未找到精确名称匹配，`analyze_impact` 将回退到语义搜索（当向量索引可用时）以查找最相似的函数。*
**`get_low_risk_refactor_candidates`**
```
directory string Absolute path to the project directory
limit number Max candidates to return (default: 5)
filePattern string Optional path substring filter (e.g. "services", ".py")
```
**`get_leaf_functions`**
```
directory string Absolute path to the project directory
limit number Max results to return (default: 20)
filePattern string Optional path substring filter
sortBy string "fanIn" (default) | "name" | "file"
```
**`get_critical_hubs`**
```
directory string Absolute path to the project directory
limit number Max hubs to return (default: 10)
minFanIn number Minimum fan-in threshold to be considered a hub (default: 3)
```
**`get_architecture_overview`**
```
directory string Absolute path to the project directory
```
**`get_function_skeleton`**
```
directory string Absolute path to the project directory
filePath string Path to the file, relative to the project directory
```
**`get_god_functions`**
```
directory string Absolute path to the project directory
filePath string Optional: restrict search to this file (relative path)
fanOutThreshold number Minimum fan-out to be considered a god function (default: 8)
```
**`suggest_insertion_points`**
```
directory string Absolute path to the project directory
description string Natural-language description of the feature to implement
limit number Max candidates to return (default: 5)
language string Filter by language: "TypeScript" | "Python" | "Go" | ...
```
**`search_code`**
```
directory string Absolute path to the project directory
query string Natural-language query, e.g. "authenticate user with JWT"
limit number Max results (default: 10)
language string Filter by language: "TypeScript" | "Python" | "Go" | ...
minFanIn number Only return functions with at least this many callers
```
**`search_specs`**
```
directory string Absolute path to the project directory
query string Natural language query, e.g. "email validation workflow"
limit number Maximum number of results to return (default: 10)
domain string Filter by domain name (e.g. "auth", "analyzer")
section string Filter by section type: "requirements" | "purpose" | "design" | "architecture" | "entities"
```
### 典型工作流
**场景 A —— 初始探索**
```
1. analyze_codebase({ directory }) # repo structure + call graph + top issues
2. get_call_graph({ directory }) # hub functions + layer violations
3. get_duplicate_report({ directory }) # clone groups to consolidate
4. get_refactor_report({ directory }) # prioritized refactoring candidates
```
**场景 B —— 定向重构**
```
1. analyze_impact({ directory, symbol: "myFunction" }) # risk score + blast radius + strategy
2. get_subgraph({ directory, functionName: "myFunction", # Mermaid call neighbourhood
direction: "both", format: "mermaid" })
3. get_low_risk_refactor_candidates({ directory, # safe entry points to extract first
filePattern: "myFile" })
4. get_leaf_functions({ directory, filePattern: "myFile" }) # zero-risk extraction targets
```
**场景 C —— 规范维护**
```
1. check_spec_drift({ directory }) # code changes not reflected in specs
2. get_mapping({ directory, orphansOnly: true }) # functions with no spec coverage
```
## 交互式图形查看器
`spec-gen view` 启动一个本地 React 应用，可视化您的代码库分析，并允许您并排探索规范需求和依赖图。
```
# 首先运行 analysis (如果尚未完成)
spec-gen analyze
# 启动 viewer (自动打开浏览器)
spec-gen view
# Options
spec-gen view --port 4000 # custom port (default: 5173)
spec-gen view --host 0.0.0.0 # expose on LAN
spec-gen view --no-open # don't open browser automatically
spec-gen view --analysis
标签：AI编程, DevOps工具, DLL 劫持, GNU通用公共许可证, IPv6支持, LLM, LNA, MITM代理, Nix, NLP, Node.js, OpenSpec, Unmanaged PE, 业务逻辑提取, 云安全监控, 云资产清单, 代码分析, 代码理解, 代码规范, 凭证管理, 大语言模型, 威胁情报, 安全专业人员, 开发者工具, 数据管道, 文档自动化, 架构分析, 源码同步, 网络安全研究, 自动化攻击, 自动化文档生成, 软件工程, 逆向工程, 静态分析