vibe-coding-cn/assets/repo/prompts-library/docs/提示词库结构与 Excel 互转规范.md

提示词库结构与 Excel 互转规范

本规范用于约束“提示词库”在文件系统与 Excel 之间的一致结构、命名与转换规则，确保后期自动化同步、增量更新与团队协作的稳定性。

1. 目录结构（约定）

prompt-library/
├── prompts/                          # 核心输出目录
│   ├── <工作表名称-已净化>/           # 每个 Excel 子表对应一个文件夹
│   │   ├── (行,列)_标题.md           # 单元格 → 单文件（仅包含提示词文本）
│   │   └── index.md                  # 该表分类索引（自动生成）
│   └── index.json                    # 全局 JSON 索引（自动生成）
├── docs/
│   ├── tools.md                      # 工具/链接（从表自动提取）
│   ├── support.md                    # 支持/钱包地址（从表自动提取）
│   ├── excel-data.md                 # Excel 原始数据快照（自动生成）
│   └── STRUCTURE_AND_CONVERSION_SPEC.md  # 本规范
└── scripts/
    ├── convert_local.py              # Excel ↔ 文件 的本地转换器（实现 Excel→文件）
    ├── config.yaml                   # 可选配置（数据源/策略）
    └── requirements.txt              # 依赖

• 只允许在 prompts/<工作表名称-已净化>/ 下新增/修改提示词文件，其它自动文件（如 index.md、index.json）由转换器生成，禁止手改。

2. 命名与净化（Sanitization）

• 工作表文件夹名：对原始 Excel 工作表名称执行净化：
  • 移除非法字符：\\ / : * ? " < > | \r \n
  • 将空格替换为下划线 _
  • 最长 60 字符，超长截断
  • 示例："学习 提示词/1?" → "学习_提示词1"
• 提示词文件名：(行,列)_标题.md
  • 行、列为 1 基索引（Excel 中第 1 行/第 1 列即 1）
  • 标题来源：该行第一个非空单元格的首行文本的前若干词（用于人读），同样执行净化
  • 标题仅用于文件名可读性，回写 Excel 时忽略

3. 文件内容规范（强约束）

• 每个提示词文件（.md）内容必须是“对应单元格的原始文本”，末尾追加一个换行；不允许包含：
  • Markdown 标题/分隔线/元信息
  • 代码围栏（```）
  • 版本历史/导航/时间戳
• 编码：UTF-8，换行：LF

4. Excel → 文件 的生成规则

• 每个工作表 → prompts/<工作表名称-已净化>/
• 行类型判定（逐行）：
  • 提示词行：该行至少一列非空，且不属于工具/社交/钱包/警告/占位
  • 工具/链接：同行包含 http 且非 X/Twitter 链接 → 归档 docs/tools.md
  • 社交：链接中包含 x.com/twitter.com → 归档 docs/tools.md
  • 钱包区块：先出现“表头”（含“网络/网络名称”且含“礼貌要饭地址/钱包/地址”），其后若干行按 (网络, 地址) 提取 → 归档 docs/support.md
  • 警告：包含“广告位” → 记录为警告
  • 占位：.../…./.... → 忽略
• 对每个提示词行：
  • 对该行每个非空列 c 生成：(r,c)_标题.md，文件正文 = 单元格纯文本
• 自动索引：
  • prompts/<表>/index.md：统计、列表与版本矩阵（供浏览用，自动生成）
  • prompts/index.json：全局结构化索引，含各表、各行版本与外部资源（自动生成）
  • docs/excel-data.md：各表数据快照（截取前 3 列），便于审计

5. 文件 → Excel 的回写规则（规范定义，供实现）

说明：当前脚本已实现 Excel→文件；本节定义未来“文件→Excel”时的规范，以便实现反向同步器保持一致性。

• 工作表名：优先使用 prompts/index.json 中的 categories[].name 作为原始工作表名；若缺失，采用文件夹名将 _ 还原为空格（尽力而为）。
• 单元格位置：
  • 解析文件名 (r,c)_标题.md 得到 1 基 r,c，写入 Excel 的第 r 行、第 c 列
  • 标题部分忽略，仅用于文件名可读
• 写入值：文件全文（去掉末尾多余空行）即单元格值
• 缺表/缺行列：自动创建工作表、扩展行列
• 冲突：同一 (r,c) 出现多文件时应失败并报告（推荐），或采用“最后写入覆盖”（需在实现中明确开关）
• 非提示词文档：tools.md、support.md 不默认回写；如需回写，应定义目标工作表名称与行布局（建议启用配置项）

6. 变更与校验

• 合法性检查：
  • 文件名需符合正则：^\(\d+,\d+\)_.+\.md$
  • 内容不得包含本规范禁止的附加信息（元信息、代码围栏等）
• 冲突检测：同一 (r,c) 不允许多次定义
• 兼容性：文件夹名与表名的映射以 index.json 为准；直接根据文件夹名还原可能出偏差

7. 自动化工具与用法

• 依赖安装：

  python3 -m pip install -r prompt-library/scripts/requirements.txt
  

• 运行（Excel→文件）：

  python3 "prompt-library/scripts/convert_local.py" \
    --excel "prompt (2).xlsx"
  

• 行为摘要：
  • 为每个工作表生成一个同名（净化后）目录
  • 为每个非空单元格生成一个 .md 文件（仅含单元格文本）
  • 重新生成所有索引与快照文档

8. 新增提示词（两种路径）

• 在 Excel 中新增：
  • 在目标工作表的目标行、列填写文本
  • 运行转换脚本，生成对应 (行,列)_标题.md
• 在文件系统中新增：
  • 到 prompts/<工作表名称-已净化>/ 新建符合命名规范的文件
  • 文件正文仅填写提示词文本
  • 将在“文件→Excel”实现后由反向同步器写回相应 (行,列)

9. 设计取舍（Why）

• 只在提示词文件中保留“纯内容”，避免元信息造成噪声与二义性，便于复制/拼接/训练
• 元信息、导航、统计统一由自动化生成到索引与文档中，降低手工维护成本
• 以 (行,列) 作为跨介质的“主键”，确保 Excel 与文件的可逆映射

10. 版本与扩展

• 建议在 scripts/config.yaml 中引入可选项：
  • 反向同步开关与目标工作表名策略
  • 冲突策略（报错/覆盖）
  • 过滤器（忽略某些行/列/关键词）
• 未来可扩展：GitHub Actions/CI 校验规范合规性；支持更多字段映射（如 tag、语言）。

---

本规范适用于本仓库的所有提示词数据。如需调整，请在 PR 中同步更新 docs/STRUCTURE_AND_CONVERSION_SPEC.md 并说明向后兼容策略。