印记
通过NuGet包分发AI技能和MCP配置
概述
印记是一种分配人工智能技能的模式(那些 SKILLS.md GitHub Copilot、Claude、Cursor、Roo Code和其他AI助手的文件)和MCP服务器配置(通过NuGet包)。将Imprint包添加到项目中时:
- 开
dotnet build:技能会自动复制到每个AI代理的本地目录中 - 开
dotnet clean:技能被删除(包括空父目录) - 多代理支持:同时针对Copilot、Claude、Cursor、Roo Code、OpenCode和Windsurf——每个都在其本机位置(如果存在)获取文件
- 支持的所有文件类型:不只是
.md--脚本、配置和中的任何其他文件skills/包含文件夹 - MCP服务器注入:包可以注入 MCP(模型上下文协议) 每个代理的服务器配置
mcp.json - 代码+技能:软件包可以附带已编译的DLL库 和 AI技能——消费者从单个NuGet安装中获得运行时API和AI指导
这可以实现以下场景:
- 合规技能:全组织编码标准打包分发
- 框架技能:特定框架的最佳实践(例如Azure、EF Core)
- 团队技能:跨团队项目共享知识
- MCP服务器:将MCP服务器配置与技能一起发布——消费者从单个NuGet安装中获得AI知识和工具访问权限
- 图书馆+技能:发布一个实用程序库,其中包含有关如何使用它的人工智能指导
库作者可以选择消费者是选择加入还是退出技能和MCP片段。通过设置 ImprintEnabledByDefault 在包裹的 .csproj,作者控制默认行为:```xml
false
消费者始终可以使用其上的元数据覆盖每个包 `PackageReference`:```xml
false
消费者的显式设置始终优先于包作者的默认设置。
快速开始
使用印记包装```bash
Add the package
dotnet add package
Build to install skills (happens automatically before build)
dotnet build
Skills are now at .github/skills/, .claude/skills/, .cursor/rules/, .roo/rules/ etc.
Imprint通过扫描配置目录自动检测您使用的AI代理(`.github/`, `.claude/`, `.cursor/`, `.roo/`, `.opencode/`, `.windsurf/`).技能被复制到每个检测到的代理的本地位置。
A共享 `.gitignore` 在以下时间自动生成 `.imprint/.gitignore`,所以没有手册 `.gitignore` 需要配置。
### 创建自己的印记包
创建新的类库项目并添加 `` 用于声明内容的项目:```xml
创造你的技能 skills/ 文件夹,然后打包:```bash
dotnet pack -o ./packages
SDK会自动生成 `.targets` 打包时的文件--不需要手动编写MSBuild!
## 多代理支持
Imprint包括多代理支持。Imprint不仅可以针对GitHub Copilot,还可以将技能和MCP配置分发给 **多个AI代理同时**,将文件放置在每个代理的本机目录结构中。
### 支持的代理
|代理|检测|技能路径|MCP路径|MCP根密钥|
|-------|-----------|-------------|----------|--------------|
| `copilot` | `.github/` 存在| `.github/skills/` | `.vscode/mcp.json` | `servers` |
| `claude` | `.claude/` 存在| `.claude/skills/` | `.claude/mcp.json` | `mcpServers` |
| `cursor` | `.cursor/` 存在| `.cursor/rules/` | `.cursor/mcp.json` | `mcpServers` |
| `roo` | `.roo/` 存在| `.roo/rules/` | `.roo/mcp.json` | `mcpServers` |
| `opencode` | `.opencode/` 存在| `.opencode/skills/` | `opencode.json` (项目根)| `mcp` |
| `windsurf` | `.windsurf/` 存在| `.windsurf/rules/` | `.windsurf/mcp.json` | `mcpServers` |
| `agents` | `.agents/` 存在| `.agents/skills/` | `.agents/mcp.json` | `mcpServers` |
未知的代理名称可以追溯到 `.{name}/rules/` 对于技能和 `.{name}/mcp.json` 对于MCP。
### 代理解决方案
Imprint使用优先级层次结构确定要针对哪些代理:
1. **显式配置** --设置 `ImprintTargetAgents` 在你的 `.csproj`:```xml
claude;cursor
-
自动检测 (默认,ON)--在生成时扫描代理目录。如果
.github/和.claude/存在,两者皆有copilot和claude成为目标。
支持的检测目录:.github/(副驾驶),.claude/(克劳德),.cursor/(光标),.roo/(roo),.opencode/(开放代码),.windsurf/(风帆),.agents/(代理人)。 -
默认回退 --如果未检测到目录:```xml
copilot
### 配置属性
|属性|默认值|目的|
|----------|---------|---------|
| `ImprintTargetAgents` | *(空)* |显式代理列表(以分号分隔)。覆盖自动检测。 |
| `ImprintAutoDetectAgents` | `true` |在生成时扫描代理目录|
| `ImprintDefaultAgents` | *(空)* |未检测到代理时回退|
| `ImprintRootDirectory` | *(自动检测)* |技能所在的存储库根。看 根目录. |
### 根目录
默认情况下,Imprint自动检测 **存储库根目录** 从项目目录中向上走。标记按优先级顺序检查:
1. **VCS目录** - `.git/`, `.svn/`, `.hg/` (最权威)
1. **IDE目录** - `.vs/` (Visual Studio), `.idea/` (JetBrains)
1. **解决方案文件** - `*.sln`, `*.slnx` (回退)
这确保了在多项目解决方案中,技能被放置在存储库根(其中 `.git/` lives)而不是在单个项目目录中:```
/repo-root/ <-- Skills placed here (correct)
├── .git/
├── .github/skills/ <-- Not inside src/MyProject/.github/
├── src/
│ └── MyProject/
│ └── MyProject.csproj
└── MyApp.sln
如果自动检测不适用于您的设置,您可以显式设置根目录:```xml
$(MSBuildThisFileDirectory)..\
如果找不到存储库根,也没有设置显式覆盖,则Imprint将回退到项目目录。
### 输出示例
随着 `.github/` 和 `.claude/` 目录存在,正在安装 `Zakira.Imprint.Sample` 生产:```
.github/
skills/
personal/
SKILL.md # Copilot sees this
.claude/
skills/
personal/
SKILL.md # Claude sees this
.vscode/
mcp.json # MCP servers for Copilot/VS Code
.claude/
mcp.json # MCP servers for Claude
.imprint/
manifest.json # Unified tracking manifest (v2)
.gitignore # Prevents tracking of managed files
可用包
| 包 | 版本 | 描述 |
|---|---|---|
| 扎奇拉。Imprint.Sdk | 1.0.0-预览 | 核心MSBuild任务引擎--自动生成 .targets、内容复制、清理、MCP合并、多代理支持 |
运作原理
建筑
所有Imprint技能包取决于 扎奇拉。Imprint.Sdk,它提供MSBuild任务引擎。包作者声明 ` 他们的物品.csproj--SDK自动生成.targets` 在打包时处理文件,然后在构建/清理时处理代理解析、文件复制、MCP合并、清单跟踪和清理。```
┌───────────────────────────┐ ┌────────────────────────────────────┐
│ Sample │ │ Sample.FilesOnly │
│ (skills + MCP + code) │ │ (skills-only) │
└──────┬────────────────────┘ └──────┬─────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Zakira.Imprint.Sdk │
│ - Auto-generates .targets at pack time (ImprintGenerateTargets) │
│ - Copies skills to all agents (ImprintCopyContent) │
│ - Merges MCP servers (ImprintMergeMcpServers) │
│ - Cleans on dotnet clean (ImprintCleanContent, ImprintCleanMcp) │
└─────────────────────────────────────────────────────────────────────┘
### 构建时间流
1. **NuGet还原**:NuGet恢复技能包,这些技能包可传递地拉入 `Zakira.Imprint.Sdk`MSBuild通过以下方式自动导入SDK的道具和目标 `buildTransitive/` 文件夹。
1. **代理解决方案**:在任何文件操作之前, `AgentConfig.ResolveAgents()` 确定要针对哪些代理:
- 如果 `ImprintTargetAgents` 已设置,请使用该显式列表
- 否则如果 `ImprintAutoDetectAgents` 如果为真,请扫描 `.github/`, `.claude/`, `.cursor/`, `.roo/`, `.opencode/`, `.windsurf/` 目录
- 否则,请返回 `ImprintDefaultAgents`
1. **内容复制** (`Imprint_CopyContent`):对于每个已解析的代理,将技能文件复制到代理的本机技能目录。在以下位置写入统一清单v2 `.imprint/manifest.json` 跟踪每个代理每个包的所有文件。
1. **MCP合并** (`Imprint_MergeMcp`):将MCP服务器片段合并到每个代理的 `mcp.json`。跟踪统一清单中的托管服务器密钥。
1. **清洁** (`Imprint_CleanContent` + `Imprint_CleanMcp`):读取统一清单,仅删除跟踪的文件和托管的MCP服务器。删除空目录。保留用户定义的MCP服务器。
### 包装时间流
当你奔跑时 `dotnet pack` 在您的Imprint包装上:
1. **生成目标** (`Imprint_GenerateTargetsFile`):SDK读取所有 `` 您的物品 `.csproj` 并生成 `.targets` 文件在 `obj/{Configuration}/{TFM}/Imprint/{PackageId}.targets`。此文件声明 `ImprintContent` 和 `ImprintMcpFragment` 消费者将使用的物品。
1. **包含内容+交叉定向导入** (`Imprint_IncludeContentInPackage`):SDK添加生成的 `.targets` 文件到两者 `build/` 和 `buildTransitive/` 包路径,包括中的所有内容文件(技能、MCP片段) `content/` 文件夹,适用于多目标包项目(`...`)进口通过 `buildMultiTargeting/` 在外部包构建中,以便Imprint包目标可以在之前运行 `_GetPackageFiles`.
1. **NuGet包**:该包是使用所有必要的文件创建的,无需手动 `.targets` 需要创作。
### 统一清单(v2)
Imprint在以下位置使用单一清单 `.imprint/manifest.json` 追踪一切:```json
{
"version": 2,
"packages": {
"Zakira.Imprint.Sample": {
"files": {
"copilot": [".github/skills/personal/SKILL.md"],
"claude": [".claude/skills/personal/SKILL.md"]
}
}
},
"mcp": {
"copilot": {
"path": ".vscode/mcp.json",
"managedServers": ["sample-echo-server"]
},
"claude": {
"path": ".claude/mcp.json",
"managedServers": ["sample-echo-server"]
}
}
}
每个包裹的遗留问题 .manifest 文件仍然是为了向后兼容性而编写的。
MCP服务器注入
印记包可以提供MCP(模型上下文协议)服务器配置。构建时,服务器配置会自动合并到每个目标代理的配置中 mcp.json.
MCP注入的工作原理
- 每个印记包包括
mcp/.mcp.json包含其服务器定义的片段文件 - 在构建时,
Zakira.Imprint.Sdk收集所有ImprintMcpFragment已安装软件包中的项目 - 对于每个解析的代理,服务器都会合并到该代理的
mcp.json,保留您手动配置的任何服务器 - 统一清单跟踪Imprint管理的服务器
- 开
dotnet clean,只删除Imprint管理的服务器——您的服务器永远不会被触及
示例片段文件
印记包 mcp/.mcp.json:```json
{
"servers": {
"sample-echo-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@anthropic-ai/echo-mcp-server"]
}
}
}
> **备注**:软件包作者总是使用 `"servers"` 作为片段文件中的根密钥。当写入每个代理的根密钥时,SDK会自动将其转换为每个代理的正确根密钥 `mcp.json` 文件夹。
之后 `dotnet build` 两者皆有 `copilot` 和 `claude` 检测到的代理:
- `.vscode/mcp.json` 包含以下服务器 `"servers"` (VS代码/副驾驶模式)
- `.claude/mcp.json` 包含以下服务器 `"mcpServers"` (克劳德模式)
### 关键行为
- **幂等**:如果没有任何变化, `mcp.json` 未重写(无git噪声)
- **安全清洁**: `dotnet clean` 仅删除托管服务器;如果没有用户服务器剩余, `mcp.json` 已删除
- **保留用户服务器**:您手动添加到的任何服务器 `mcp.json` 从未被修改或删除
- **`inputs` 保存的**:顶级属性,如 `"inputs"` 在 `mcp.json` 通过构建和清洁来保存
- **多代理**:每个代理都有自己的 `mcp.json` 在其原产地
- **模式转换**:SDK会自动为每个代理使用正确的根密钥(`"servers"` 对于Copilot, `"mcpServers"` 克劳德/Cursor)
### MCP模式差异
不同的AI代理对其MCP配置文件使用不同的JSON模式。SDK会自动处理此问题:
|代理|根密钥|示例|
|-------|----------|---------|
|副驾驶(VS代码)| `servers` | `{"servers": {"my-server": {...}}}` |
|克劳德| `mcpServers` | `{"mcpServers": {"my-server": {...}}}` |
|光标| `mcpServers` | `{"mcpServers": {"my-server": {...}}}` |
|Roo代码| `mcpServers` | `{"mcpServers": {"my-server": {...}}}` |
|OpenCode| `mcp` | `{"mcp": {"my-server": {...}}}` |
|风帆冲浪| `mcpServers` | `{"mcpServers": {"my-server": {...}}}` |
**包作者总是使用 `"servers"`** 作为根密钥。SDK读取这些片段,并在写入各自的模式时将其转换为每个代理的预期模式 `mcp.json` 文件夹。内部服务器定义(`command`, `args`, `type`, `env`)在所有代理中都是相同的。
### 将MCP注射添加到您的包装中
1. 添加一个 `PackageReference` 到 `Zakira.Imprint.Sdk` 在你的 `.csproj`
1. 创建一个 `mcp/.mcp.json` 包含服务器定义的片段
1. 使用以下命令添加片段 `` 项目与 `Type="Mcp"`:```xml
SDK自动生成 .targets 打包时的文件——无需手动配置!
两种包装模式
仅技能套餐
对于仅分发AI技能和MCP配置(无编译代码)的包:```xml
false true
看 `samples/Sample.FilesOnly` 举个例子。
### 代码+技能包
对于同时提供编译DLL的包 **和** 人工智能技能:```xml
看 samples/Sample 例如,它将字符串实用程序方法与AI技能文件和MCP服务器配置一起提供。
配置
代理定位
控制哪些AI代理Imprint目标:```xml
copilot;claude false copilot
### 传统路径覆盖
这些属性仍然可用于向后兼容性,但通常会被多代理解析所取代:
|属性|默认值|目的|
|----------|---------|---------|
| `ImprintSkillsPath` | `.github/skills/` |传统:单一代理技能路径|
| `ImprintPromptsPath` | `.github/prompts/` |传统:单个代理提示路径|
| `ImprintMcpPath` | `.vscode/` |传统:单代理MCP路径|
## 测试此回购```bash
# 1. Pack the SDK first, then samples (to local-packages/)
dotnet pack src/Zakira.Imprint.Sdk -o ./local-packages
dotnet pack samples/Sample -o ./local-packages
dotnet pack samples/Sample.FilesOnly -o ./local-packages
# 2. Create a test consumer (or use samples/Consumer)
cd samples/Consumer
dotnet build
# 3. Verify skills are installed (agent directories vary by your setup)
ls .github/skills/
# personal/ StringUtils/
# 4. Verify MCP servers were injected
cat .vscode/mcp.json
# { "servers": { "sample-echo-server": {...} } }
# 5. Run unit tests
cd ../..
dotnet test Zakira.Imprint.sln
# 6. Test clean - skills and managed MCP servers are removed
cd samples/Consumer
dotnet clean
ls .github/ # Should be empty or not exist
ls .vscode/mcp.json # Should not exist (no user servers to preserve)
# 7. Build again - everything is restored
dotnet build
限制和已知问题
-
包装移除:当您删除Imprint包时,其技能将一直保留,直到您运行
dotnet clean或者手动删除它们。 -
IDE设计时构建:技能和MCP服务器仅在实际构建期间进行管理,而不是在IDE后台构建期间(这是为了避免性能问题)。
-
需要首次构建:技能和MCP配置是在第一次构建时安装的,而不是在还原时安装的。
-
共享输出文件夹:每个代理将多个包写入同一技能目录。如果两个包包含具有相同相对路径的文件,则最后一个复制的包获胜。
-
MCP服务器密钥冲突:如果两个Imprint包使用相同的密钥定义了一个服务器,则最后处理的片段将自动获胜。计划对此发出警告。
-
扎奇拉。印记.Sdk需要。净值8+:扎奇拉。Imprint.Sdk编译任务DLL目标
net8.0消费者必须拥有。NET 8 SDK或更高版本已安装。
未来改进
- [x] ~~一个项目中包含多个技能包~~
- [x] ~~ MCP服务器注入~~
- [x] ~~集中式SDK(Zakira.Imprint.SDK)--所有MSBuild逻辑的单一来源~~
- [x] ~~每个包裹清单用于精确的文件跟踪~~
- [x] ~~代码+技能包模式~~
- [x] ~~ MSBuild任务类的单元测试~~
- [x] ~~多代理支持(复制、Claude、Cursor、Roo代码)~~
- [x] ~~自动检测AI代理~~
- [x] ~~具有每个代理跟踪功能的统一清单v2~~
- [x] ~~自动生成
.targets文件--不需要手动编写MSBuild~~ - [x] ~~多项目解决方案的存储库根自动检测~~
- []多个包定义相同密钥时的服务器密钥冲突检测/警告
- []跨解决方案管理技能的全球工具
- []包装过程中的技能验证
- []技能包之间的冲突检测
- []用于构建和发布软件包的CI/CD管道
- []提示支持(分发
.prompt文件到特定于代理的目录) - [x] ~~ Windsurf代理支持~~
- []额外的代理支持(Cody等)
许可证
麻省理工学院
