Sigil
通用的 AI 上下文层。
架构 + 指令 + 行为配置文件 → 一个 token 优化后的 payload → 适用于所有 AI 工具。
12 种语言：TypeScript、Python、PHP、Go、Rust、Java、Ruby、C#、Kotlin、Swift、Elixir、Dart — 还可通过插件支持任何语言。
提取架构。定义指令。注入到 Claude Code、Cursor、Windsurf、Cline、Copilot、Continue。
## 快速开始
```
# Homebrew (macOS/Linux)
brew tap riomyers/sigil && brew install sigil-cli
# 或 npm
npm i -g @sigil-engine/cli
# 然后
cd your-project
sigil init
```
**就是这样。** Sigil 提取您代码库的架构，加载您的指令，并自动配置每个检测到的 AI 工具。现在，您的 AI 拥有了完整的上下文——实体、组件、路由、模式、约定以及您的自定义指令——所有内容都打包在一个经过 token 优化的 payload 中。
## 您将获得什么
```
$ sigil show
my-app — Context Summary
────────────────────────────────────────
Extracted: 2026-03-19
Time: 2929ms
Plugins: typescript@0.1.0
Stack
framework: next.js@16
language: typescript
orm: drizzle
database: postgresql
ui: tailwind, shadcn
auth: next-auth
Architecture
Entities: 31
Components: 28
Routes: 20
Exports: 115
Entities
Users (8 fields, 3 relations) ← src/db/schema.ts
Posts (6 fields, 2 relations) ← src/db/schema.ts
Invoices (12 fields, 1 relation) ← src/db/schema.ts
Components
Dashboard [client, route:/] ← src/app/page.tsx
UserCard [4 props] ← src/components/UserCard.tsx
DataTable [client, 6 props] ← src/components/DataTable.tsx
Routes
/api/users GET, POST [auth]
/api/posts GET, POST, DELETE [auth]
Patterns
auth: next-auth with JWT strategy
styling: tailwind + CVA variants
data_fetching: server components
```
## 原语：`context.yaml`
Sigil 创建一个结构化的 YAML 文档，捕获您代码库的**架构**，而不仅仅是文件。每个元素都通过 `_meta` 锚点链接回源代码：
```
version: "1.0"
project: "my-app"
stack:
framework: "next.js@16"
orm: "drizzle"
database: "postgresql"
entities:
- name: "Users"
_meta: { file: "src/db/schema.ts", symbol: "users", type: "entity" }
fields:
- { name: "id", type: "uuid", primary: true }
- { name: "email", type: "varchar(255)", unique: true }
- { name: "name", type: "varchar(100)" }
relations:
- { to: "Posts", type: "one-to-many", via: "userId" }
components:
- name: "Dashboard"
_meta: { file: "src/app/page.tsx", symbol: "Dashboard", type: "component" }
props:
- { name: "userId", type: "string", required: true }
dependencies: ["MetricCard", "ChartPanel"]
hooks: ["useState", "useEffect", "useMetrics"]
data_sources: ["/api/metrics"]
route: "/"
routes:
- path: "/api/users"
_meta: { file: "src/app/api/users/route.ts", symbol: "route", type: "route" }
methods:
GET: { auth: true, returns: "User[]" }
POST: { auth: true, body: "JSON" }
```
## MCP Server —— 零摩擦的 AI 上下文
只需在您的 AI 工具配置中添加一行。Sigil 会在每次会话中自动提供架构上下文。
```
// Claude Code: ~/.claude/settings.json
{
"mcpServers": {
"sigil": {
"command": "npx",
"args": ["@sigil-engine/mcp-server"]
}
}
}
```
就是这样。您的 AI 在每次会话中都能获取架构 + 指令。当您保存文件时会自动更新。
**您的 AI 可用的 MCP 工具：**
- `sigil_extract` — 强制进行全新提取
- `sigil_diff` — 检测架构变更
- `sigil_search` — 按名称、类型或文件搜索上下文
- `sigil_query` — 询问架构问题（依赖项、认证缺口、复杂度）
- `sigil_health` — 运行架构健康检查（评分 0-100）
- `sigil_context` — 获取用于聚焦任务的 token 优化上下文
## 指令 —— 持久化的 AI 指示
定义随处跟随您的 AI 的规则。指令从全局级联到项目级，支持基于优先级的修剪，并根据项目上下文进行条件过滤。
```
# Global directives (适用于每个项目)
sigil directives add "Never use any in TypeScript" --priority high --category code
sigil directives add "Never hardcode credentials" --priority critical --category security
# Conditional directives (仅在项目匹配时应用)
sigil directives add "Use server components by default" --when-framework next
# Project-specific directives (覆盖全局)
sigil directives add "Use MUI instead of Tailwind" --project --category code
# View all active directives (全局 + 项目，已合并)
sigil directives
```
```
Directives (3)
──────────────────────────────────────────────────
1. [G] [critical] (security) Never hardcode credentials
2. [G] [high] (code) Never use any in TypeScript
3. [P] (code) Use MUI instead of Tailwind
[G] = global (~/.sigil/directives.yaml) [P] = project (sigil.config.yaml)
```
指令在 `sigil context --tokens N` 中与架构共享 token 预算。Critical/high（关键/高优先级）指令永远不会被修剪。Normal/low（普通/低优先级）指令在预算压力下会为架构让路。
## 命令
### `sigil init`
设置项目 — 提取架构 + 加载指令 + 注入到 AI 工具：
```
sigil init # Extract + auto-configure AI tools
sigil init --no-interactive # CI mode (errors instead of prompting)
```
**智能项目发现：** 从任何目录运行 `sigil init` — 如果它不是项目根目录，Sigil 会扫描附近的目录并显示一个交互式选择器：
```
Found 8 projects nearby:
# Project Stack Files
──────────────────────────────────────────────────────
1 my-app Next.js · Drizzle 66
2 api-service Express 45
3 shared-lib TypeScript · monorepo 21
Select a project (1-3): _
```
这将提取您的上下文并自动将架构信息注入到您正在使用的任何 AI 工具中：
| AI Tool | Config File | How Detected |
|---------|-------------|--------------|
| Claude Code | `CLAUDE.md` | `CLAUDE_CODE` env, `~/.claude/` dir |
| Cursor | `.cursorrules` | `CURSOR_SESSION` env, `~/.cursor/` dir |
| Windsurf | `.windsurfrules` | `~/.windsurf/` 或 `~/.codeium/windsurf/` dir |
| Cline | `.clinerules` | `CLINE_DIR` env, VS Code extension installed |
| GitHub Copilot | `.github/copilot-instructions.md` | 项目中的 `.github/` dir |
| Continue | `.continuerules` | `~/.continue/` dir |
Sigil 检测您安装了哪些 AI 工具并自动创建正确的配置文件。如果未检测到任何内容，它将创建 `CLAUDE.md` 作为默认值。
### `sigil rules`
定义自动注入到每个 AI 工具的项目规则：
```
sigil rules add "Always use server components"
sigil rules add "Validate all input with Zod"
sigil rules # List current rules
sigil rules remove 1 # Remove by index
```
规则存储在 `sigil.config.yaml` 中，并在您运行 `sigil init` 时注入到您的 AI 工具配置中。一个事实来源 — 所有工具获得相同的指令。
### `sigil graph`
启动交互式依赖可视化：
```
sigil graph # Open in browser at localhost:4040
sigil graph --export graph.html # Export as static HTML
sigil graph --port 8080 # Custom port
```
### `sigil extract`
将您的代码库解析为结构化上下文：
```
sigil extract # Current directory
sigil extract ./my-app # Specific path
sigil extract --format json # JSON output
sigil extract --workspace portal # Monorepo workspace
```
### `sigil diff`
检测架构偏移 — 自上次提取以来发生了什么变化：
```
sigil diff # Compare current code vs saved context
sigil diff old.yaml new.yaml # Compare two context files
sigil diff --json # Machine-readable output
```
```
Context Diff Summary
────────────────────
5 changes: +2 added, -1 removed, ~2 modified
Entities
+ PaymentMethod (5 fields)
~ Users
+ field: avatarUrl (text)
Components
~ Dashboard
+ prop: billingEnabled: boolean
Routes
- /api/legacy-auth
+ /api/payments GET, POST [auth]
```
### `sigil profile`
设置您的全局 AI 行为配置文件（一次设置，随处适用）：
```
sigil profile init # Interactive setup wizard
sigil profile # View current profile
sigil profile edit # Open in $EDITOR
```
创建 `~/.sigil/profile.yaml` — 您的身份、沟通风格、工作流规则和代码标准。在您运行 `sigil init` 时注入到每个项目中。
### `sigil snapshot`
生成可共享的 HTML 架构报告：
```
sigil snapshot # Generate sigil-snapshot.html
sigil snapshot --out report.html # Custom output path
```
将其放入 PR 描述、Slack 或 wiki 中。零依赖 — 适用于任何浏览器。
### `sigil query`
询问关于您架构的问题：
```
sigil query "what depends on User" # Find all dependents (uses import graph)
sigil query "routes without auth" # Find unprotected endpoints
sigil query "largest components" # Rank by complexity
sigil query "dead code" # Find unreferenced functions
sigil query "config drift" # Find env var sync issues
sigil query "unused imports" # Find imported but never called symbols
sigil query "orphaned exports" # Find unused exports
```
### `sigil directives`
管理 AI 指令（全局 + 项目）：
```
sigil directives # List all active directives
sigil directives add "rule" --priority high --category code # Add globally
sigil directives add "rule" --project # Add to project
sigil directives add "rule" --when-language python # Conditional
sigil directives remove 3 # Remove by index
sigil directives disable 3 # Disable without removing
sigil directives enable 3 # Re-enable
sigil directives preset list # Show available presets
sigil directives preset install security # Install a preset pack
sigil directives preview # What applies to this project?
sigil directives validate # Check for duplicates/issues
sigil directives export > rules.yaml # Export for sharing
sigil directives import rules.yaml # Import (merges, skips dupes)
sigil directives edit # Open in $EDITOR
```
### `sigil context`
输出统一的、token 优化的上下文（架构 + 指令）：
```
sigil context --tokens 4000 # Pruned summary with directives
sigil context --tokens 8000 --format yaml # Pruned YAML
sigil context --no-directives # Architecture only
```
### `sigil health`
带有评分的架构健康检查：
```
sigil health # Scored report (0-100)
sigil health --json # Machine-readable
```
检测：循环依赖、上帝组件、认证缺口、孤立导出、孤立实体、深层调用链、死函数、配置偏移（环境变量同步）、未使用的导入。
### `sigil install-hook`
用于架构检查的 Git pre-commit hook：
```
sigil install-hook # Install pre-commit hook
sigil uninstall-hook # Remove it
```
### `sigil apply` *(实验性)*
编辑 YAML，将更改应用回代码：
```
sigil apply --yes # Apply changes
sigil apply # Dry run (preview only)
```
## 为什么选择 Sigil？
| Feature | Sigil | repomix | aider repo-map | Cursor |
|---------|-------|---------|----------------|--------|
| Structured output | ✅ YAML/JSON | ❌ flat text | ⚠️ tree-sitter map | ❌ proprietary |
| Architecture-aware | ✅ entities, routes, patterns | ❌ file dump | ⚠️ symbols only | ⚠️ basic |
| AI Directives | ✅ priority, conditional, inherited | ❌ | ❌ | ⚠️ .cursorrules only |
| Token-optimized | ✅ budget-aware pruning | ❌ | ❌ | ❌ |
| Dead code + config drift | ✅ function-level + env sync | ❌ | ❌ | ❌ |
| Drift detection | ✅ structural diff | ❌ | ❌ | ❌ |
| Plugin system | ✅ any language | ❌ | ❌ | ❌ |
| Portable | ✅ 6 AI tools | ✅ | ❌ aider only | ❌ Cursor only |
| Open source | ✅ MIT | ✅ MIT | ✅ Apache 2.0 | ❌ proprietary |
## 插件架构
Sigil 的核心是**语言无关的**。TypeScript 解析器是一个插件 — 您可以为任何语言编写一个：
```
import type { ExtractorPlugin } from '@sigil-engine/core';
export const pythonPlugin: ExtractorPlugin = {
name: 'python',
version: '0.1.0',
languages: ['python'],
detect(projectPath) {
// Check for pyproject.toml, requirements.txt, etc.
return existsSync(join(projectPath, 'pyproject.toml'));
},
init(projectPath) {
// Initialize your parser (tree-sitter, AST, etc.)
return { projectPath, sourceFiles: findPythonFiles(projectPath) };
},
extract(project) {
// Return partial ContextDocument
return {
entities: extractDjangoModels(project),
routes: extractDjangoUrls(project),
stack: { framework: 'django', language: 'python' },
};
},
};
```
## 包
| Package | Description |
|---------|-------------|
| [`@sigil-engine/core`](https://www.npmjs.com/package/@sigil-engine/core) | Schema, plugin system, diff engine, extraction orchestrator |
| [`@sigil-engine/parser-typescript`](https://www.npmjs.com/package/@sigil-engine/parser-typescript) | TypeScript, React, Next.js, Express, Fastify, Hono, Drizzle, Prisma |
| [`@sigil-engine/parser-python`](https://www.npmjs.com/package/@sigil-engine/parser-python) | Python, Django, Flask, FastAPI, SQLAlchemy |
| [`@sigil-engine/parser-php`](https://www.npmjs.com/package/@sigil-engine/parser-php) | PHP, Laravel, Symfony, Eloquent, Doctrine |
| [`@sigil-engine/parser-go`](https://www.npmjs.com/package/@sigil-engine/parser-go) | Go, Gin, Echo, Fiber, Chi, GORM |
| [`@sigil-engine/parser-rust`](https://www.npmjs.com/package/@sigil-engine/parser-rust) | Rust, Actix, Axum, Rocket, Diesel, SQLx |
| [`@sigil-engine/parser-java`](https://www.npmjs.com/package/@sigil-engine/parser-java) | Java, Spring Boot, JPA, Hibernate |
| [`@sigil-engine/parser-ruby`](https://www.npmjs.com/package/@sigil-engine/parser-ruby) | Ruby, Rails, ActiveRecord, Sinatra |
| [`@sigil-engine/parser-csharp`](https://www.npmjs.com/package/@sigil-engine/parser-csharp) | C#, ASP.NET, Entity Framework |
| [`@sigil-engine/parser-kotlin`](https://www.npmjs.com/package/@sigil-engine/parser-kotlin) | Kotlin, Ktor, Spring Boot, Exposed |
| [`@sigil-engine/parser-swift`](https://www.npmjs.com/package/@sigil-engine/parser-swift) | Swift, Vapor, Fluent |
| [`@sigil-engine/parser-elixir`](https://www.npmjs.com/package/@sigil-engine/parser-elixir) | Elixir, Phoenix, Ecto |
| [`@sigil-engine/parser-dart`](https://www.npmjs.com/package/@sigil-engine/parser-dart) | Dart, Flutter |
| [`@sigil-engine/cli`](https://www.npmjs.com/package/@sigil-engine/cli) | CLI — `init`, `extract`, `diff`, `show`, `graph`, `query`, `health`, `context`, `directives`, `snapshot`, `profile`, `rules` |
| [`@sigil-engine/mcp-server`](https://www.npmjs.com/package/@sigil-engine/mcp-server) | MCP server — auto-context for Claude Code, Cursor, any MCP client |
### 编程 API
```
import { extractContext, registerPlugin, diffContexts } from '@sigil-engine/core';
import { typescriptPlugin } from '@sigil-engine/parser-typescript';
registerPlugin(typescriptPlugin);
const doc = await extractContext({ projectPath: './my-app' });
console.log(doc.entities.length); // 31
console.log(doc.components.length); // 28
console.log(doc.routes.length); // 20
```
## Sigil 提取的内容
**实体** — 数据库表（Drizzle、Prisma）、模型、schema。字段、类型、约束、关系。
**组件** — React/Vue/Svelte 组件。带类型的 Props、hooks、依赖项、客户端/服务端分类、路由映射。
**路由** — API endpoints。HTTP 方法、认证检测、请求/响应类型、验证。
**调用图** — 跨文件的函数到函数调用边。数据流分析。
**模式** — 认证策略、数据获取、状态管理、样式、验证库。
**约定** — 文件命名、导入风格、API 模式、数据库 schema 位置。
**环境变量** — 跨文件的 `process.env` 使用情况，包含必需/可选检测。
**依赖项** — 来自 package manifest 的完整依赖列表。
## 贡献
Sigil 采用 MIT 许可证并欢迎贡献。最具影响力的贡献方式是**为新语言编写解析器插件**。
有关详细信息，请参阅 [插件编写指南](https://sigil.riomyers.com)。
```
git clone https://github.com/riomyers/sigil
cd sigil
pnpm install
pnpm build
pnpm test # 381 tests
```
## 许可证
[MIT](LICENSE) — 可随处使用，可嵌入任何内容。
由 [Rio Myers](https://riomyers.com) 构建。