mirror of
https://github.com/aicode-standard/prompt-config.git
synced 2025-10-07 06:45:14 +08:00
484 lines
14 KiB
Markdown
484 lines
14 KiB
Markdown
# AI 代码编辑器提示词配置文件标准化提案
|
||
|
||
[English](./README.md) | 简体中文
|
||
|
||
## 提案概述
|
||
|
||
为 AI 代码编辑器创建一个统一的提示词配置文件标准，解决当前各编辑器使用不同路径和格式导致的配置碎片化问题。
|
||
|
||
## 当前问题
|
||
|
||
1. **路径不统一**：
|
||
- Cursor: `.cursor/rules.md`
|
||
- Trae: `.trae/rules/project_rules.md`
|
||
- Codeium: `.codeium/context.md`
|
||
- 其他编辑器各有自己的约定
|
||
|
||
2. **配置同步困难**：团队成员使用不同编辑器时需要维护多份相同内容
|
||
3. **版本控制冲突**：不同编辑器的配置文件需要分别添加到 `.gitignore`
|
||
4. **迁移成本高**：切换编辑器时需要重新配置提示词
|
||
5. **单体仓库挑战**：单体仓库中的不同项目需要不同的提示词配置
|
||
|
||
## 提案标准
|
||
|
||
### 核心标准路径
|
||
|
||
```
|
||
.prompt/
|
||
├─ rules/
|
||
│ ├─ project[/[<自定义文件名>]][.<编辑器标识>].md # 项目级提示词（主要文件）
|
||
│ ├─ context[/[<自定义文件名>]][.<编辑器标识>].md # 上下文规则（可选）
|
||
│ └─ code_style[/[<自定义文件名>]][.<编辑器标识>].md # 代码风格规范（可选）
|
||
├─ config.json # 配置文件
|
||
└─ README.md # 说明文档（可选）
|
||
```
|
||
|
||
其中，`[.<编辑器标识>]` 是编辑器特定配置。不添加则是全局使用的公共提示词文件。
|
||
|
||
### 单体仓库支持与路径特定规则
|
||
|
||
对于单体仓库项目，使用 `.prompt-config.yaml` 中的 glob 模式配置路径特定规则：
|
||
|
||
```yaml
|
||
version: 1.0
|
||
|
||
prompt:
|
||
rules:
|
||
- scope: "packages/frontend/**" # 前端包
|
||
files:
|
||
- .prompt/frontend-rules.md
|
||
- docs/frontend/ai-context.md
|
||
|
||
- scope: "packages/backend/**" # 后端包
|
||
files:
|
||
- .prompt/backend-rules.md
|
||
- "!docs/frontend/**" # 排除前端文档
|
||
|
||
- scope: "**/legacy/**" # 任何遗留目录
|
||
files:
|
||
- .prompt/legacy-overrides.md
|
||
|
||
default: # 未匹配路径的默认规则
|
||
files:
|
||
- .prompt/general.md
|
||
- docs/ai-guidelines.md
|
||
```
|
||
|
||
#### 规则评估
|
||
1. **特异性**：精确路径 > 通配符模式 > 默认规则
|
||
2. **排除**：否定模式（`!路径`）排除文件
|
||
3. **就近原则**：嵌套配置中最接近的 `.promptconfig.yaml` 生效
|
||
4. **合并**：数组会合并，对象会深度合并
|
||
|
||
### 配置示例
|
||
|
||
**基础配置：**
|
||
|
||
如果我们想配置项目级提示词，我们可以这样做：
|
||
|
||
```
|
||
.prompt/
|
||
└─ rules/
|
||
├─ project.md # 项目级提示词（主要文件）
|
||
├─ project.vscode.md # 在 VSCode 编辑器中扩展 `project.md` 文件（可选）
|
||
├─ project.cursor.md # 在 Cursor 编辑器中扩展 `project.md` 文件（可选）
|
||
└─ project.trae.md # 在 TRAE 编辑器中扩展 `project.md` 文件（可选）
|
||
```
|
||
|
||
**高级配置（多文件结构）：**
|
||
|
||
当提示词内容较多，需要拆分成多个文件时，可以创建对应目录，将提示词按照自定义目录结构进行分类。同样的，也以 `[.<编辑器标识>].md` 结尾。所有的文件都是可选的。
|
||
|
||
```
|
||
.prompt/
|
||
└─ rules/
|
||
├─ project/
|
||
│ ├─ [foo].vscode.md
|
||
│ ├─ [foo].cursor.md
|
||
│ ├─ [foo].trae.md
|
||
│ └─ index.md
|
||
├─ project.md
|
||
├─ project.vscode.md
|
||
├─ project.cursor.md
|
||
└─ project.trae.md
|
||
```
|
||
|
||
在这个示例中，`.prompt/rules/project/index.md` 与 `.prompt/rules/project.md` 作用相同，同时存在时，他们都将生效。
|
||
|
||
对于 VSCode 编辑器，在这个示例中，会加载以下 markdown 文件作为提示词：
|
||
- `.prompt/rules/project/[foo].vscode.md`
|
||
- `.prompt/rules/project/index.md`
|
||
- `.prompt/rules/project.md`
|
||
- `.prompt/rules/project.vscode.md`
|
||
|
||
### 文件加载规则
|
||
|
||
1. **全局文件**：`.prompt/rules/project.md`（所有编辑器共享）
|
||
2. **编辑器特定文件**：`.prompt/rules/project.{editor}.md`（按编辑器加载）
|
||
3. **目录结构**：支持子目录组织，`index.md` 作为目录入口文件
|
||
4. **合并策略**：所有匹配的文件内容会被合并，编辑器特定配置会扩展全局配置
|
||
5. **路径特定规则**：对于单体仓库，使用 glob 模式为不同路径应用不同的提示词
|
||
|
||
## 配置文件格式 (`.prompt/config.json`)
|
||
|
||
```json
|
||
{
|
||
"promptFileVersion": "1.0",
|
||
"response_language": "zh-CN", // 指定模型返回的语言
|
||
"defaultMergeStrategy": "append", // 默认合并策略：append|overwrite|smart
|
||
"fileLoadingOrder": ["global", "editor-specific"], // 文件加载顺序
|
||
"supportedEditors": ["vscode", "cursor", "trae", "codeium"],
|
||
"editorSpecific": {
|
||
"vscode": {
|
||
"promptPriority": ["project.md", "project.vscode.md"],
|
||
"maxTokenLimit": 4000
|
||
},
|
||
"cursor": {
|
||
"promptPriority": ["project.md", "project.cursor.md"],
|
||
"maxTokenLimit": 8000
|
||
},
|
||
"trae": {
|
||
"promptPriority": ["project.md", "project.trae.md"],
|
||
"maxTokenLimit": 6000
|
||
},
|
||
"[editor_name]": {
|
||
...
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 实施路径
|
||
|
||
### 阶段一：兼容层（立即可行）
|
||
|
||
创建转换工具和符号链接脚本：
|
||
|
||
```bash
|
||
# migrate-prompts.sh
|
||
#!/bin/bash
|
||
|
||
# 创建标准目录结构
|
||
mkdir -p .prompt/rules
|
||
|
||
# 迁移现有配置并创建符号链接
|
||
migrate_editor_config() {
|
||
local editor=$1
|
||
local source_path=$2
|
||
local target_name=$3
|
||
|
||
if [ -f "$source_path" ]; then
|
||
# 迁移到新位置
|
||
cp "$source_path" ".prompt/rules/${target_name}.${editor}.md"
|
||
# 创建符号链接保持向后兼容
|
||
ln -sf "../.prompt/rules/${target_name}.${editor}.md" "$source_path"
|
||
echo "Migrated ${editor} configuration"
|
||
fi
|
||
}
|
||
|
||
# 迁移各编辑器配置
|
||
migrate_editor_config "cursor" ".cursor/rules.md" "project"
|
||
migrate_editor_config "trae" ".trae/rules/project_rules.md" "project"
|
||
migrate_editor_config "codeium" ".codeium/context.md" "context"
|
||
|
||
# 创建基础配置文件
|
||
if [ ! -f ".prompt/config.json" ]; then
|
||
cat > ".prompt/config.json" << EOF
|
||
{
|
||
"promptFileVersion": "1.0",
|
||
"response_language": "",
|
||
"defaultMergeStrategy": "append",
|
||
"supportedEditors": ["vscode", "cursor", "trae", "codeium"]
|
||
}
|
||
EOF
|
||
fi
|
||
```
|
||
|
||
### 阶段二：编辑器适配
|
||
|
||
鼓励编辑器厂商原生支持标准路径：
|
||
|
||
```json
|
||
// 编辑器配置示例 (VSCode settings.json)
|
||
{
|
||
"aiPrompts.standardPath": ".prompt/rules",
|
||
"aiPrompts.loadOrder": [
|
||
"project.md",
|
||
"project.vscode.md",
|
||
"context.md",
|
||
"context.vscode.md"
|
||
],
|
||
"aiPrompts.mergeStrategy": "smart",
|
||
"aiPrompts.scopeAware": true, // 启用单体仓库路径感知加载
|
||
"aiPrompts.debug": false // 显示已加载提示词的调试信息
|
||
}
|
||
```
|
||
|
||
### 编辑器实现示例
|
||
|
||
```javascript
|
||
// 范围匹配的伪代码
|
||
function getApplicablePrompts(filePath, config) {
|
||
const rules = config.rules.filter(rule =>
|
||
micromatch.isMatch(filePath, rule.scope)
|
||
);
|
||
|
||
// 按特异性排序（更具体的模式优先）
|
||
rules.sort((a, b) => compareSpecificity(a.scope, b.scope));
|
||
|
||
return rules.flatMap(rule => rule.files);
|
||
}
|
||
```
|
||
|
||
### 阶段三：生态系统建设
|
||
|
||
1. **开发核心工具**：
|
||
- 配置验证工具：`prompt-validator`
|
||
- 文件合并工具：`prompt-merger`
|
||
- 迁移辅助工具：`prompt-migrate`
|
||
- 范围调试工具：`prompt-debug`（显示哪些提示词应用于哪些路径）
|
||
|
||
2. **编辑器插件**：
|
||
- VSCode 扩展：`vscode-prompt-config-integration`
|
||
- Cursor 插件：`cursor-prompt-config-integration`
|
||
|
||
3. **模板库**：
|
||
- 常见项目类型的配置模板
|
||
- 各语言的最佳实践示例
|
||
- 单体仓库配置示例
|
||
|
||
## 配置文件详细规范
|
||
|
||
### 项目提示词模板 (`.prompt/rules/project.md`)
|
||
|
||
```markdown
|
||
# 项目提示词
|
||
|
||
## 项目概述
|
||
{{项目描述}}
|
||
|
||
## 编码规范
|
||
- 语言: {{编程语言}}
|
||
- 代码风格: {{代码风格指南}}
|
||
- 命名约定: {{命名规则}}
|
||
|
||
## 架构约束
|
||
- 设计模式: {{使用的模式}}
|
||
- 分层架构: {{架构层次}}
|
||
- 依赖管理: {{依赖规范}}
|
||
|
||
## 业务规则
|
||
{{具体业务逻辑和要求}}
|
||
```
|
||
|
||
### 编辑器特定扩展示例 (`.prompt/rules/project.vscode.md`)
|
||
|
||
```markdown
|
||
# VSCode 特定配置
|
||
|
||
## 编辑器集成
|
||
- 优先使用 VSCode 扩展: {{扩展列表}}
|
||
- 调试配置: {{调试设置}}
|
||
- 代码片段: {{自定义片段}}
|
||
|
||
## 性能优化
|
||
- 大文件处理策略: {{处理方式}}
|
||
- 内存管理: {{优化建议}}
|
||
```
|
||
|
||
### 完整 config.json 规范
|
||
|
||
```json
|
||
{
|
||
"promptFileVersion": "string", // 配置版本号
|
||
"responseLanguage": "string", // 默认响应语言
|
||
"defaultMergeStrategy": "string", // 默认合并策略
|
||
"fileLoadingOrder": ["string"], // 文件加载顺序
|
||
"maxFileSizeKB": number, // 最大文件大小限制
|
||
"encoding": "string", // 文件编码格式
|
||
"validationRules": { // 验证规则
|
||
"maxLength": number,
|
||
"allowedSections": ["string"],
|
||
"requiredSections": ["string"]
|
||
},
|
||
"editorSpecific": {
|
||
"[editor_name]": {
|
||
"promptPriority": ["string"], // 提示词优先级
|
||
"maxTokenLimit": number, // 最大 token 限制
|
||
"temperature": number, // 温度参数
|
||
"modelPreferences": ["string"] // 模型偏好
|
||
}
|
||
},
|
||
"extensions": { // 扩展配置
|
||
"customSections": ["string"], // 自定义章节
|
||
"templateVariables": { // 模板变量
|
||
"key": "value"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 迁移指南
|
||
|
||
### 从现有系统迁移
|
||
|
||
1. **自动迁移**：
|
||
```bash
|
||
# 使用迁移工具
|
||
npx @prompt-standard/migrate --editor cursor --editor trae
|
||
|
||
# 或使用交互式迁移
|
||
npx @prompt-standard/migrate-interactive
|
||
```
|
||
|
||
2. **手动迁移**：
|
||
```bash
|
||
# 1. 创建标准目录
|
||
mkdir -p .prompt/rules
|
||
|
||
# 2. 迁移并重命名现有配置
|
||
mv .cursor/rules.md .prompt/rules/project.cursor.md
|
||
mv .trae/rules/project_rules.md .prompt/rules/project.trae.md
|
||
|
||
# 3. 创建符号链接（可选，保持兼容）
|
||
ln -s ../.prompt/rules/project.cursor.md .cursor/rules.md
|
||
ln -s ../.prompt/rules/project.trae.md .trae/rules/project_rules.md
|
||
```
|
||
|
||
3. **验证配置**：
|
||
```bash
|
||
# 安装验证工具
|
||
npm install -g @prompt-standard/validator
|
||
|
||
# 验证配置完整性
|
||
prompt-validate
|
||
```
|
||
|
||
### 验证工具功能
|
||
|
||
```bash
|
||
# 检查配置完整性
|
||
prompt-validate --check-completeness
|
||
|
||
# 验证语法正确性
|
||
prompt-validate --check-syntax
|
||
|
||
# 生成配置报告
|
||
prompt-validate --generate-report
|
||
|
||
# 检查编辑器兼容性
|
||
prompt-validate --check-editor vscode cursor
|
||
|
||
# 调试路径匹配（用于单体仓库）
|
||
prompt-debug --path packages/frontend/src/index.js
|
||
```
|
||
|
||
## 收益分析
|
||
|
||
### 对开发者
|
||
- ✅ **一致性**：跨编辑器统一体验，减少上下文切换
|
||
- ✅ **可维护性**：集中管理，单一事实来源
|
||
- ✅ **灵活性**：支持全局配置和编辑器特定扩展
|
||
- ✅ **协作性**：团队配置标准化，易于共享
|
||
- ✅ **单体仓库支持**：为单体仓库中的不同项目提供路径特定规则
|
||
|
||
### 对编辑器厂商
|
||
- ✅ **互操作性**：降低用户迁移成本，提高用户粘性
|
||
- ✅ **生态系统**：促进工具链集成和插件开发
|
||
- ✅ **标准遵从**：体现专业性和前瞻性，增强竞争力
|
||
- ✅ **扩展性**：支持自定义配置和高级功能
|
||
|
||
## 行动计划
|
||
|
||
### 立即行动（1-2周）
|
||
- [ ] 创建核心工具库：`@prompt-standard/core`
|
||
- [ ] 开发配置验证工具：`@prompt-standard/validator`
|
||
- [ ] 编写详细文档和示例
|
||
- [ ] 建立社区讨论组（Discord/GitHub Discussions）
|
||
- [ ] 为核心库添加单体仓库路径匹配支持
|
||
|
||
### 短期目标（1-3月）
|
||
- [ ] 争取 2-3 个主流编辑器支持
|
||
- [ ] 创建流行项目的配置模板
|
||
- [ ] 开发 IDE 插件原型
|
||
- [ ] 建立自动化测试流程
|
||
- [ ] 添加单体仓库示例和最佳实践
|
||
|
||
### 长期愿景（6-12月）
|
||
- [ ] 成为事实标准，被多个编辑器原生支持
|
||
- [ ] 建立认证程序和兼容性测试
|
||
- [ ] 扩展支持更多 AI 开发工具
|
||
- [ ] 开发图形化配置管理工具
|
||
- [ ] 具有继承和覆盖规则的高级单体仓库支持
|
||
|
||
## 技术支持
|
||
|
||
### 开发工具
|
||
```bash
|
||
# 核心库安装
|
||
npm install @prompt-standard/core
|
||
|
||
# 验证工具安装
|
||
npm install -g @prompt-standard/validator
|
||
|
||
# 迁移工具安装
|
||
npm install -g @prompt-standard/migrate
|
||
|
||
# 调试工具安装
|
||
npm install -g @prompt-standard/debug
|
||
```
|
||
|
||
### API 示例
|
||
```javascript
|
||
// 使用核心库
|
||
import { PromptLoader, PromptValidator } from '@prompt-standard/core'
|
||
|
||
const loader = new PromptLoader('.prompt/rules')
|
||
const prompts = await loader.loadForEditor('vscode')
|
||
|
||
const validator = new PromptValidator()
|
||
const results = await validator.validate(prompts)
|
||
|
||
// 用于单体仓库路径感知加载
|
||
const pathSpecificPrompts = await loader.loadForPath('packages/frontend/src/index.js', 'vscode')
|
||
```
|
||
|
||
## 呼吁参与
|
||
|
||
我们邀请以下各方参与：
|
||
|
||
### 对于编辑器开发者
|
||
- 实现原生标准支持
|
||
- 提供反馈和改进建议
|
||
- 参与标准规范的制定
|
||
- 添加单体仓库路径感知提示词加载功能
|
||
|
||
### 对于开源项目
|
||
- 率先采用标准配置
|
||
- 贡献项目配置模板
|
||
- 分享使用经验和最佳实践
|
||
- 提供单体仓库用例
|
||
|
||
### 对于社区成员
|
||
- 测试和报告问题
|
||
- 参与文档编写和翻译
|
||
- 开发辅助工具和插件
|
||
- 贡献单体仓库支持功能
|
||
|
||
### 对于企业用户
|
||
- 提供实际业务需求
|
||
- 分享企业级应用场景
|
||
- 参与标准推广和实施
|
||
- 贡献大规模单体仓库需求
|
||
|
||
**参与方式**：
|
||
- 📝 提交 Issue 和 Feature Request
|
||
- 🔄 提交 Pull Request
|
||
- 💬 加入社区讨论
|
||
- 🚀 分享你的配置案例
|
||
- 🏗️ 贡献单体仓库解决方案
|
||
|
||
**GitHub 仓库**: https://github.com/aicode-standard/prompt-config
|
||
|
||
加入 https://github.com/aicode-standard/prompt-config/issues 的讨论！
|