promptdown极简标记语言 · 兼容 Markdown 风格 · PD ↔ JSON 双向转换 为提示词(prompt)组织而生的 ✨ 特性
❓ Why提示词越写越多,如何"自然地结构化"就成了问题——简单场景用自然语言就够了,复杂需求(开发、媒体制作)下,现成方案都不太合适:
🚀 快速开始
写一个
转出来的 JSON:
📖 语法一览行类型
核心规则
🔗 引用示例(多段混排)以编程任务为例:
🖥️ CLI
自动识别输入类型(扩展名 → 内容探针):
JSON → pd 的空行规则(已移入 format,pdformat / VSCode 格式化 / compile 输出统一生效):默认无空行;唯一例外——顶层带子域键值后跟下一个顶层条目(键值/文本块/代码块)时,中间空一行:
✨ 格式化
格式化规则:
🎨 VSCode 扩展安装
🏷️ 语法高亮
扩展详情页、扩展列表和 🔍
|
| 场景 | 行为 |
|---|---|
- foo 行尾回车 |
新行补 -,缩进与原行一致 |
- key: value 行尾回车 |
同上(带-键值也是序列条目) |
- (空条目,带空格)行尾回车 |
清掉原行标记(含缩进)回到顶层:原行变空行,新行落行首,光标定新行 col 0 |
-(裸空条目,无空格)回车 |
退出列表(新行无标记) |
---(分隔线)回车 |
不续行 |
连按两次回车即可从子项层级脱身直接写顶层项:第一次由续行规则生成
<缩进>-,第二次清掉标记回到行首(严格匹配/\s*-\s/场景,裸-不清行)。
生效条件:
editor.autoIndent开启(默认开启)。
⇥ Tab 缩进
在序列项行(行首为 -,- 后可有可无空白,可带缩进)按 Tab,整行向右缩进一个 tab —— 快速调整嵌套层级(pd 的缩进即父子关系),而不是在光标处插入 tab 字符。缩进时若 - 后不是单个半角空格(裸 -、- x 等多空白),会自动规范化为 - x:
| 场景 | Tab 行为 |
|---|---|
光标在 - foo、裸 -、- x 等序列项行上 |
整行右缩进一个 tab,并把 - 后规范化为单个半角空格 |
| 其他行(键值行、内容行等) | 还原默认:插入 tab(遵循 editor.insertSpaces / editor.indentSize / editor.tabSize) |
| 跨行多选 | 所有选中行整体右缩进(序列项行同样规范化) |
| 补全列表 / 行内联补全(ghost text)/ 片段导航中 | 不拦截,保持 VSCode 原生行为 |
📁 文件图标
扩展附带图标主题 promptdown Icons(继承 Seti,只替换 .pd 图标):
Ctrl+Shift+P→ File Icon Theme → 选promptdown Icons- 或 settings.json 里设
"workbench.iconTheme": "promptdown-icons"
注:VSCode 不允许扩展强制覆盖用户的图标主题,需要在设置里手动切换一次。 因为继承了 Seti,其他文件图标保持不变,只有
.pd显示icons/pd-icon.png。扩展也提供了语言图标回退,但最终是否展示仍由当前文件图标主题决定;选择promptdown Icons可确保资源管理器与编辑器标签页显示专属图标。
⚙️ 设置一览
| 设置 | 默认 | 说明 |
|---|---|---|
promptdown.autoDetect |
true |
弱语法文件(untitled/txt/log 等)中出现 //!pd 段标记时,自动切换文档语言为 promptdown(获得高亮与格式化) |
🦀 Helix 支持
helix 语法高亮只用 tree-sitter(无 TextMate),项目附带一份 tree-sitter-promptdown/ grammar(helix / neovim 通用)。
一键安装(repo 或 npm 全局包均可):
pnpm hx-install # repo 内:检测 hx → 写 languages.toml → 装 queries → hx --grammar build
hx-install # npm 全局包(@andares/promptdown)自带此命令,用法相同
脚本自动:检测 hx → 写/合并 ~/.config/helix/languages.toml(source.path 指向当前来源的 grammar——repo 装链 repo,npm 装链包内,来源切换自动更新)→ 拷 queries → hx --grammar build。验证:hx --health promptdown。
高亮配色(queries/highlights.scm,值不设色与正文同色):
| 元素 | 颜色 |
|---|---|
| 键(含冒号) | 紫 @keyword |
引用 :refname |
橙 @constant(value 内拆分,URL 不误拆) |
--- 分隔线 / - 前缀 |
蓝 @operator |
//!pd 段标记 |
标题色粗体 @markup.heading |
``` 围栏行 |
代码块底色 @markup.raw.block |
| 值 / 普通文本 | 默认前景(无 capture) |
缩进继承(queries/indents.scm):列表项内回车自动缩进到内容列(- 模块A: 后新行列 2,嵌套逐级继承);顶层键值行回车回列 0。helix 无法自动补 - 前缀(平台限制,换行只输出空白),回车后手动输入即可。
写提示词工作流(config.toml 建议,脚本会输出):
[editor]
clipboard-provider = "wayland" # WSLg 默认已自动检测;显式声明更稳
[keys.normal]
F5 = ":set-language promptdown" # 一键激活 pd 语言(空 buffer / 未存盘场景)
F6 = ["select_all", "yank"] # 一键全选复制全文到系统剪贴板(WSLg → Windows 剪贴板)
hx 提示词.pd:.pd后缀自动识别,直接写(不:w即不落盘)- 写完
F6复制全文 → Windows 端Ctrl+V粘贴(WSLg 与系统剪贴板同步,已实测) - 手动安装:
languages.toml加[[language]]+[[grammar]](source.path指向 grammar 目录)→hx --grammar build→ 拷queries/*.scm到~/.config/helix/runtime/queries/promptdown/(⚠️ grammar 配置不管 queries,必须手动拷) - 限制:围栏只高亮
```行本身(围栏内行按普通文本);键名不能以-开头(-前缀归列表项)
🧩 多端一致性(语法规则同步状态)
pd 语法在四端实现,语义以 TS 核心(packages/pdfoundation/ 共享包 @andares/pdfoundation,解析/转换/格式化的唯一事实)为准,其余各端为显示层:
| 规则 | TS 核心 | VSCode(TextMate) | Helix(tree-sitter) |
|---|---|---|---|
严格键值判定(a : b/a:b 非键值) |
✅ | ✅ | ✅ |
:-/:- 整行转义 |
✅ | ✅ | ✅ |
| 行内代码内冒号不参与键值/转义判定 | ✅ | ✅ | ✅(0.8 同步) |
| 行内代码整体漂色 | ✅(语义) | ✅ | ⚠️ 仅语义豁免,无漂色 |
:- 行内代码内不触发整行转义 |
✅ | ⚠️ 保守(代码内 :- 也整行不识别键值) |
✅ |
SECTION 整行锚定(//!pd 名 字 非段标记) |
✅ | ✅ | ⚠️ 降级:前缀匹配 |
SEPARATOR 整行锚定(---x 非分隔线) |
✅ | ✅ | ⚠️ 降级:--- 前缀即匹配 |
引用前后空格约束(:name) |
✅ | ✅ | ⚠️ 降级:tree-sitter 正则无 lookahead |
| 未闭合反引号按普通字符 | ✅ | ✅ | ⚠️ 降级:近似处理 |
| ``` 围栏内原样/不切段/不展开引用 | ✅ | ✅(高亮) | ✅ |
| 寻址/引用解析(%N、%% 转义、先到先得) | ✅ | —(无寻址概念) | — |
降级说明(tree-sitter 外部 scanner 无法回退已消费字符 + 正则引擎不支持 lookahead,严格判定的失败分支会导致行内容丢失/误判;宽容前缀匹配在显示层更安全):
//!pd 名 字、---x在 Helix 中会按段标记/分隔线高亮(TS 核心按普通文本解析)`行内代码在 Helix 中无整体漂色(仅内部冒号不参与键值判定);`a: b`这类行内代码内冒号不会误高亮为键值- 未闭合反引号行(
`a: b)在 Helix 按非键值显示(TS 核心按普通文本,可作键名)
以上差异均为高亮显示层差异,不影响解析/转换结果(语义以 TS 核心为准)。
🔒 API 与稳定性(1.0 起冻结)
promptdown 由三个 npm 包组成,1.0 后以下公共面冻结(不可删除 / 改名 / 改签名;破坏性变更一律 2.0):
| 包 | 公共面 |
|---|---|
@andares/promptdown |
CLI 行为(pdtransform / pdcompile / pdformat / --version)、VSCode 贡献点(命令、语言 id promptdown、配置 promptdown.autoDetect、格式化程序、Tab/回车编辑行为)。不导出 JS 语义 API(已移至 foundation) |
@andares/pdfoundation |
语义 API:format / pdToJsonText / jsonToPdText / compilePdText / compileSections / detectTransformKind / splitSections / nameSections / resolveSection 等(完整清单见 1.0 规划) |
@andares/pdeditor |
组件 API:createPdEditor 与 PdEditorOptions 全部键;/pd 入口另含 highlightPd;两入口 re-export 语义 API |
- 语法规范:
docs/SPEC.md冻结——行类型、section 寻址、引用(含循环静默擦除)、格式化与转义/豁免矩阵;1.0 后只做非破坏性补充 - 版本策略:语义化版本;
@andares/pdfoundation与主包同号绑定(每次release-all一起发);@andares/pdeditor独立版本线
🤖 AI Skill
两个 skill,按需安装:
① 解析版 skill/promptdown/SKILL.md —— 提供 pd 语法知识(读):
- 输入中出现
//!pd→ 后续内容按 pd 格式解析 - 处理
.pd文件、转 JSON、语法纠错
② 作者版 skill/pd-author/SKILL.md —— 教 AI 写结构化提示词(默认 pd,不用 markdown):
- 结构化 prompt(角色/目标/约束/步骤/示例…)→ 默认输出 pd 结构,键替代
#标题 - 含通用 prompt 骨架模板、领域范例、作者视角避坑清单
- 触发词:写提示词、组织提示词、提示词结构、用 pd 写
安装到 AI 的 skill 目录即可(如 ~/.pi/agent/skills/ 或项目 .agents/skills/,pd-author/ 目录整体复制为独立 skill)。
🛠️ 开发
- Web 输入框组件:packages/editor/(npm 包 @andares/pdeditor)——headless 提示词输入框(pd/md/xml/json/yaml 高亮),基于 Yace;含 pd-only 精简入口(
@andares/pdeditor/pd,不含 Prism,~17 kB),该入口另 re-export 共享语义包(format/jsonToPdText/pdToJsonText/highlightPd);pnpm --filter @andares/pdeditor dev起 demo - 性能基准:
pnpm perf(10 副本样本 2099 行/150 段全链路基准);pnpm perf:gen [份数]重新生成样本(perf/generated/不入库) - 1.0 路线:见
docs/ROADMAP-1.0.md(API 冻结声明 + 全端对齐确认 + 发布节奏)
pnpm install
pnpm typecheck # 类型检查
pnpm test # node:test(壳层 + CLI 集成;语义规则 178 用例在 packages/pdfoundation)
pnpm build # tsc → dist/
pnpm package # 以 --no-dependencies 打包 .vsix
发布
pnpm release-all patch # 唯一主包发布入口:foundation(同号)→ npm → push/tag → vsce
pnpm release-editor patch # editor 独立发布(纯 npm)
pnpm release-all patch -- --dry-run # 预览计划(不改动任何东西;旧 release 命令已移除)
pnpm tag-current # 给当前版本打本地 tag vX.Y.Z(已存在则跳过,不推送)
pnpm release-all(唯一主包入口):sync(未提交改动自动 commit、本地领先自动 push、本地落后中止、没有则跳过)→ 门禁(含 foundation)→ 主包 + foundation 同号 bump →git commit + tag vX.Y.Z→ 先发 foundation 再发主包(workspace:^发布时自动改写为实际版本)→ push 分支 + tags → 创建 GitHub Release → vsce package + publish。npm 失败中止,vsce 失败降级为只发 npm。pnpm release/pnpm release-foundation已移除(并入 release-all):误敲会被拦截提示。
📁 项目结构
promptdown/
├── icons/pd-icon.png # 扩展品牌图标 + .pd 文件图标
├── src/cli.ts # pdtransform CLI(自动识别 pd/json 双向转换)
├── src/compile-cli.ts # pdcompile CLI(多段编译为单份完整 pd)
├── src/format-cli.ts # pdformat CLI(格式化)
├── src/extension.ts # VSCode 扩展(命令 + 格式化 + 回车/Tab 行为)
├── src/tab.ts # Tab 缩进逻辑(扩展专用)
├── src/enter.ts # 回车清子项标记(扩展专用)
├── src/version.ts # CLI 通用 --version
├── packages/pdfoundation/ # ⭐ 共享语义核心 @andares/pdfoundation(parser/format/转换 + 语义测试与 fixtures)
├── packages/editor/ # headless 输入框组件 @andares/pdeditor
├── syntaxes/ # TextMate 语法高亮
├── docs/SPEC.md # ⭐ 语法规范(唯一事实来源)
├── skill/ # AI skill(容器:promptdown/ 解析版 + pd-author/ 作者版)
└── test/ # 主包测试(CLI 集成 / tab 行为)