From efd027ee1d955fdb4b4ef6cc2b2334ce76f195ad Mon Sep 17 00:00:00 2001 From: VantIer Date: Fri, 24 Jul 2026 14:11:48 +0800 Subject: [PATCH] feat: add skill D2-Diagrams & HTMD --- skills/D2-Diagrams/SKILL.md | 277 +++++++ skills/D2-Diagrams/doc.md | 765 ++++++++++++++++++ skills/D2-Diagrams/references/release.md | 86 ++ .../D2-Diagrams/references/troubleshooting.md | 84 ++ skills/HTMD/SKILL.md | 148 ++++ skills/HTMD/SPEC.htmd | 254 ++++++ skills/HTMD/references/patterns.md | 313 +++++++ skills/HTMD/references/schema.md | 278 +++++++ skills/HTMD/references/tags.md | 170 ++++ 9 files changed, 2375 insertions(+) create mode 100644 skills/D2-Diagrams/SKILL.md create mode 100644 skills/D2-Diagrams/doc.md create mode 100644 skills/D2-Diagrams/references/release.md create mode 100644 skills/D2-Diagrams/references/troubleshooting.md create mode 100644 skills/HTMD/SKILL.md create mode 100644 skills/HTMD/SPEC.htmd create mode 100644 skills/HTMD/references/patterns.md create mode 100644 skills/HTMD/references/schema.md create mode 100644 skills/HTMD/references/tags.md diff --git a/skills/D2-Diagrams/SKILL.md b/skills/D2-Diagrams/SKILL.md new file mode 100644 index 0000000..446315d --- /dev/null +++ b/skills/D2-Diagrams/SKILL.md @@ -0,0 +1,277 @@ +--- +name: d2-diagrams +description: 使用 D2 声明式图表语言将文本描述转换为流程图、架构图、时序图、UML 类图等图表文件。仅支持 Windows 系统。当用户要求绘制流程图、架构图、系统图、网络拓扑、时序图、UML 图、数据库 ER 图、组织架构图，或提到"画图"、"图表"、"diagram"、"流程"、"架构"时使用本 Skill。即使用户只描述了要可视化的内容而未明确说"画图"，只要意图是生成图表就应触发。若用户在非 Windows 系统上请求画图，提示本工具仅支持 Windows。 +--- + +# D2 Diagrams — 文本转图表工具（Windows Only） + +> **平台限制**：本 Skill 内置的 `d2.exe` 为 Windows 可执行文件，仅支持在 Windows 系统上运行。非 Windows 环境只提示当前 Skill 不可用，不自动下载、安装或访问外部资源。D2 官方网站：（仅供用户手动查阅，本 Skill 不会自动访问）。 + +本 Skill 采用**完全离线策略**：只允许使用 Skill 目录中的 `d2.exe`、本地 `.d2` 文件、工作区内的本地图标、本地字体和本地导入文件。禁止在线演练场、远程图标、外部链接、远程导入、远程字体和任何自动下载行为。Watch 模式使用 `localhost` 或 `127.0.0.1` 时属于本机预览，不属于外部网络访问。 + +引导用户使用 D2 声明式图表语言，将自然语言或结构化描述转为 `.d2` 代码并渲染为图片。 + +## 与其他图表工具的边界 + +本节用于在多个图表工具都可能适用时进行路由，不改变 frontmatter 中的触发描述： + +1. **明确指定 D2**：用户提到 D2、`.d2`、`d2.exe` 或要求使用 D2 渲染时，优先使用本 Skill。 +2. **明确指定 Mermaid**：用户要求 Mermaid 语法、Mermaid 图表或 Mermaid 渲染时，交由 Mermaid 相关能力处理，不要擅自改写为 D2。 +3. **明确指定 PlantUML**：用户要求 PlantUML、UML 源文件或 PlantUML 渲染时，交由 PlantUML 相关能力处理，不要擅自改写为 D2。 +4. **明确指定飞书白板或画板**：用户要求飞书白板、画板、白板节点编辑或白板导出时，使用白板相关能力，不使用本地 D2 文件替代。 +5. **只说“画图”但未指定工具**：先确认用户希望的语法、输出格式和运行环境；只有用户接受 D2 或需要本地 Windows D2 渲染时，才进入本 Skill 的执行流程。 +6. **用户同时指定多个工具**：分别说明各工具的输入格式、平台限制和产物差异，再按用户选择执行；不要静默转换源格式。 + +## 离线与安全边界 + +执行前必须遵守以下规则： + +1. 只调用 Skill 目录内的本地 `d2.exe`，不执行下载、安装或联网更新。 +2. 只读取当前工作区或用户明确指定的本地 `.d2`、图标、字体和导入文件。 +3. 禁止使用 `d2 play`、远程 `icon`、远程 `link`、远程 `@import`、远程字体或任何 `http://`、`https://` 资源。 +4. 如果用户输入或生成的 D2 代码包含外部 URL，停止渲染并提示用户将其替换为本地资源；不要尝试访问该 URL。 +5. Watch 模式只能绑定 `localhost` 或 `127.0.0.1`，不绑定公网地址，也不向外部服务发送图表内容。 +6. 如果本地资源缺失，报告缺失路径并使用默认样式或停止处理，不自动从网络补齐。 + + +## 前置要求 + +- 运行环境必须是 Windows。 +- 当前 Skill 目录必须包含本地 `d2.exe`，预期版本为 `v0.7.1`；不从系统 PATH 猜测或替换该二进制。 +- 输入 `.d2` 文件必须位于当前工作区或用户明确指定的本地路径，并且可读。 +- 输出目录必须存在且可写；Skill 不创建工作区外的目录。 +- 运行过程中不安装依赖、不下载文件、不访问外部网络。 + +## 运行前检查 + +在验证或渲染前，按顺序执行以下检查： + +1. **检查平台**：确认当前系统为 Windows；否则停止并说明内置 `d2.exe` 不可用。 +2. **解析工具路径**：将 `` 解析为当前 `SKILL.md` 所在的 `D2-Diagrams` 目录，工具路径固定为 `/d2.exe`；禁止写入用户特定的绝对路径。 +3. **检查工具版本**：执行 `/d2.exe --version`，确认返回 `v0.7.1`。文件缺失、不可执行或版本不匹配时停止，不自动下载或替换。 +4. **检查输入**：确认输入文件存在、扩展名为 `.d2` 且可读；检查 D2 内容不包含远程图标、链接、导入或字体地址。 +5. **检查输出**：确认输出格式受支持，输出目录存在且可写；如果目标文件已存在，默认不覆盖，先询问用户是否覆盖或改用新文件名。 +6. **记录失败**：任一检查失败时，报告失败检查、具体路径或版本信息，并在修复后从该检查重新开始。 + +### 1. 收集需求 + +和用户确认以下信息（如果用户已提供则跳过对应项）： + +- **图表内容**：用户想画什么？接受自然语言描述、Markdown 列表、Mermaid 代码等任何形式 +- **图表方向**：`down`（默认）/ `up` / `left` / `right` +- **布局引擎**：`dagre`（默认，通用有向图）/ `elk`（分层算法，适合复杂层次结构） +- **绘图风格**： + - 是否开启手绘风格（`--sketch`） + - 主题 ID（不确定时可省略，使用默认主题。亮色主题 0-105, 300-303；暗色主题 200-201） +- **输出格式**：`svg` / `png` / `pdf` / `pptx` / `gif`（每次询问用户偏好） + +如果用户没有特别指定，不要逐一追问每个选项，用默认值即可。只在用户明确表达偏好时调整。 + +### 2. 生成 D2 代码 + +根据用户描述编写 `.d2` 文件。代码应遵循 D2 语法规范。 + +**关键原则：** + +- 将用户描述中的实体映射为形状，关系映射为连接 +- 根据内容语义选择合适的 `shape`——这是生成专业图表的关键，不要用矩形表示一切 +- 适当使用容器嵌套组织相关元素 +- **保持代码简洁**：只写语义和结构，避免手动添加大量颜色样式——除非用户明确要求美化。D2 的主题系统会自动处理样式，手动着色往往是多余的 +- 连接标签应简洁描述关系 + +**形状语义映射表：** + +在生成代码时，根据实体含义自动选择最合适的形状，而非全部用默认矩形： + +| 实体类型 | 推荐形状 | 示例 | +|----------|----------|------| +| 开始/结束 | `circle` | 开始、结束 | +| 决策/判断 | `diamond` | 是否通过？审核结果 | +| 数据库/存储 | `cylinder` | MySQL、Redis、MongoDB | +| 云服务/网关 | `cloud` | AWS、API Gateway、Nginx | +| 消息队列 | `queue` | Kafka、RabbitMQ | +| 文档/页面 | `page` | API 文档、合同 | +| 代码/配置 | `code` | 配置文件、脚本 | +| 人物/角色 | `person` | 用户、管理员 | +| 包/模块 | `package` | 微服务模块、SDK | +| 六边形概念 | `hexagon` | 核心领域概念 | +| 时序交互 | `sequence_diagram` | 协议流程、API 调用链 | +| 数据库表 | `sql_table` | ER 图中的表 | +| UML 类 | `class` | 类图中的类 | + +**特别提醒——时序图：** 当用户描述的是多个角色之间的交互顺序（如协议流程、API 调用链），务必使用 `sequence_diagram` 形状，不要用普通矩形+箭头模拟。时序图有专门的语法和渲染效果： + +```d2 +sequence: { + shape: sequence_diagram + 角色A; 角色B; 角色C + 角色A -> 角色B: 请求 + 角色B -> 角色C: 转发 +} +``` + +**D2 语法要点速查：** + +``` +# 形状 +名称 # 矩形（默认） +名称.shape: circle # 圆形 +名称.shape: diamond # 菱形/决策 +名称.shape: cylinder # 数据库 +名称.shape: cloud # 云服务 +名称.shape: queue # 消息队列 +名称.shape: person # 人物 +名称.shape: sql_table # SQL 表 +名称.shape: class # UML 类 +名称.shape: sequence_diagram # 时序图 + +# 连接 +A -> B: 标签 # 有向箭头 +A <-> B # 双向 +A -- B # 无向 + +# 容器 +组名: { A -> B -> C } + +# 方向 +direction: right + +# 文本格式 +说明: |md + **加粗** 和 *斜体** +| + +# 变量 +vars: { primary-color: "#FF5733" } +名称.style.fill: ${primary-color} +``` + +### 3. 验证并渲染 + +先验证语法，再渲染输出： + +```sh +# 将 解析为当前 SKILL.md 所在的 D2-Diagrams 目录 +"/d2.exe" --version + +# 验证语法 +"/d2.exe" validate input.d2 + +# 渲染（根据用户选择的格式和参数） +"/d2.exe" [选项] input.d2 output.<格式> +``` + +**d2.exe 路径**：始终根据当前 `SKILL.md` 的位置解析 ``，不要写入用户特定的绝对路径，也不要依赖系统 PATH 中可能存在的其他 D2。若使用 Bash，使用正斜杠并加引号；若使用 PowerShell，使用解析后的本地路径变量。 + +示例： + +```sh +"/d2.exe" validate input.d2 +``` + +其中 `` 必须由 Agent 根据当前 Skill 文件位置解析，不得直接照抄为示例路径。 + +**常用渲染参数：** + +| 参数 | 说明 | +|------|------| +| `-l dagre` / `-l elk` | 布局引擎 | +| `-t ` | 亮色主题 | +| `--dark-theme ` | 暗色主题 | +| `--sketch` | 手绘风格 | +| `--scale 0.5` | 缩放 | +| `--pad 200` | 边距填充 | +| `--center` | 居中 | + +**判断渲染是否成功**：始终以 `d2` 的退出状态码为准，而非输出文件是否存在。如果渲染失败，读取错误输出并修复 `.d2` 代码后重试。 + +### 4. 审核与迭代 + +渲染成功后： + +1. 告知用户输出文件路径，提示用户打开查看 +2. 等待用户反馈，可能的反馈类型： + - **满意**：流程结束 + - **需要修改内容**：根据反馈调整 `.d2` 代码，重新渲染 + - **需要调整样式/布局**：修改 style、方向、引擎等参数，重新渲染 +3. 重复直到用户满意 + +## 输出清单 + +完成验证或渲染后，向用户说明以下信息；这是结果覆盖清单，不要求固定返回文本格式： + +- **源文件**：`.d2` 输入文件路径。 +- **验证结果**：语法验证是否成功；失败时给出失败阶段和错误摘要。 +- **渲染结果**：是否成功、使用的输出格式，以及渲染退出状态。 +- **产物路径**：成功生成的文件路径；如果未生成，不要声称存在产物。 +- **参数**：实际使用的方向、布局引擎、主题、缩放、边距、手绘等非默认参数。 +- **备注**：覆盖确认、离线资源限制、未解决问题或下一步迭代建议。 + +## 常见图表模板 + +### 流程图 + +```d2 +direction: down +开始 -> 处理: 输入数据 +处理 -> 判断: 分析结果 +判断 -> 结束A: 条件满足 +判断 -> 结束B: 条件不满足 +判断.shape: diamond +``` + +### 架构图 + +```d2 +direction: down +客户端 -> 负载均衡器: HTTPS +负载均衡器 -> API 服务器 +API 服务器 -> 数据库 +API 服务器 -> 缓存 +数据库.shape: cylinder +缓存.shape: cylinder +负载均衡器.shape: cloud +``` + +### 时序图 + +```d2 +sequence: { + shape: sequence_diagram + 客户端; 服务器; 数据库 + 客户端 -> 服务器: 请求 + 服务器 -> 数据库: 查询 + 数据库 -> 服务器: 结果 + 服务器 -> 客户端: 响应 +} +``` + +### SQL 表关系 + +```d2 +users: { + shape: sql_table + id: int {constraint: primary_key} + name: varchar + email: varchar {constraint: unique} +} +orders: { + shape: sql_table + id: int {constraint: primary_key} + user_id: int {constraint: foreign_key} + amount: decimal +} +users.id -> orders.user_id +``` + +## 注意事项 + +- **完全离线**：本 Skill 不访问外部网络，不使用在线演练场、远程图标、外部链接、远程导入或远程字体；所有输入和资源必须来自本地。 +- D2 的 key 大小写不敏感，`PostgreSQL` 和 `postgresql` 引用同一个形状 +- 连接必须引用 key，而非 label +- 重复连接声明会创建新连接，不会覆盖——如需修改已有连接的样式，用索引引用：`(A -> B)[0].style.stroke: red` +- 对形状设置了 Markdown 标签时，需显式声明 `shape` 类型 +- 大型图表可增大 `--timeout` 值（默认 120 秒） +- 错误处理和边界场景的识别、停止、重试与确认规则，读取 `references/troubleshooting.md` +- D2 二进制的来源、版本、许可证、上游发布资产和 SHA-256 信息，读取 `references/release.md` +- 详细语法和参数参考，读取 `doc.md` diff --git a/skills/D2-Diagrams/doc.md b/skills/D2-Diagrams/doc.md new file mode 100644 index 0000000..8ccc029 --- /dev/null +++ b/skills/D2-Diagrams/doc.md @@ -0,0 +1,765 @@ +# D2 使用说明 + +> D2 v0.7.1 — 声明式图表渲染工具 + +--- + +## 一、命令总览 + +``` +d2 [选项] file.d2 [输出文件] +d2 layout [名称] +d2 fmt file.d2 ... +d2 validate file.d2 +``` + +D2 将 `.d2` 文本描述编译渲染为图表，支持以下输出格式： + +| 格式 | 扩展名 | +|------|--------| +| 矢量图 | `.svg`（默认） | +| 位图 | `.png` | +| 文档 | `.pdf`、`.pptx` | +| 动画 | `.gif` | +| 文本 | `.txt` | + +未指定输出文件时默认生成同名 `.svg` 文件。使用 `-` 可从标准输入读取或输出到标准输出。 + +**判断渲染是否成功：始终以 d2 的退出状态码为准**，而非输出文件是否存在（出错时可能仍生成部分渲染文件）。 + +--- + +## 二、渲染命令 + +### 2.1 基本渲染 + +```sh +# 渲染为 SVG（默认） +d2 input.d2 + +# 指定输出格式 +d2 input.d2 output.png +d2 input.d2 output.pdf + +# 从标准输入读取，输出到标准输出 +d2 - < input.d2 > output.svg + +# 指定标准输出格式 +d2 input.d2 --stdout-format png - > output.png +``` + +### 2.2 Watch 模式（实时预览） + +Watch 模式会监听文件变更并自动重载，同时在浏览器中预览： + +```sh +# 启动 Watch 模式 +d2 --watch input.d2 + +# 指定监听地址和端口 +d2 -w -h 127.0.0.1 -p 8080 input.d2 + +# Watch 模式不打开浏览器 +d2 --watch --browser 0 input.d2 +``` + +### 2.3 指定布局引擎 + +```sh +# 使用 ELK 引擎 +d2 -l elk input.d2 + +# 通过环境变量指定 +D2_LAYOUT=elk d2 input.d2 + +# 在 .d2 文件中指定 +vars: { + d2-config: { + layout-engine: elk + } +} +``` + +### 2.4 指定主题 + +```sh +# 使用 Terminal 主题 +d2 --theme 300 input.d2 + +# 暗色模式主题 +d2 --dark-theme 200 input.d2 + +# 同时指定亮色和暗色主题 +d2 --theme 300 --dark-theme 200 input.d2 + +# 手绘风格 + 主题 +d2 --sketch --theme 300 input.d2 +``` + +### 2.5 缩放与布局控制 + +```sh +# 缩小 50% +d2 --scale 0.5 input.d2 output.png + +# 原始大小（关闭 SVG 自适应） +d2 --scale 1 input.d2 + +# 图表周围填充像素 +d2 --pad 200 input.d2 + +# 居中 SVG +d2 --center input.d2 +``` + +### 2.6 渲染特定 Board + +```sh +# 仅渲染根 Board +d2 --target='' input.d2 + +# 渲染指定图层及其所有子级 +d2 --target='layers.detail.*' input.d2 + +# 渲染指定 Board（不含子级） +d2 --target='layers.detail' input.d2 +``` + +### 2.7 多 Board 动画 + +```sh +# 多个 Board 以 1 秒间隔自动切换（仅 SVG/GIF） +d2 --animate-interval 1000 input.d2 +``` + +--- + +## 三、子命令 + +### 3.1 `d2 layout` — 查看布局引擎 + +```sh +# 列出所有可用引擎 +d2 layout + +# 查看特定引擎的详细说明和参数 +d2 layout dagre +d2 layout elk +``` + +当前可用引擎： + +| 引擎 | 说明 | +|------|------| +| `dagre`（默认） | 有向图布局库 | +| `elk` | Eclipse 布局内核，分层算法 | + +### 3.2 `d2 themes` — 查看主题 + +```sh +d2 themes +``` + +**亮色主题：** + +| ID | 名称 | +|----|------| +| 0 | Neutral Default | +| 1 | Neutral Grey | +| 3 | Flagship Terrastruct | +| 4 | Cool Classics | +| 5 | Mixed Berry Blue | +| 6 | Grape Soda | +| 7 | Aubergine | +| 8 | Colorblind Clear | +| 100 | Vanilla Nitro Cola | +| 101 | Orange Creamsicle | +| 102 | Shirley Temple | +| 103 | Earth Tones | +| 104 | Everglade Green | +| 105 | Buttered Toast | +| 300 | Terminal | +| 301 | Terminal Grayscale | +| 302 | Origami | +| 303 | C4 | + +**暗色主题：** + +| ID | 名称 | +|----|------| +| 200 | Dark Mauve | +| 201 | Dark Flagship Terrastruct | + +### 3.3 `d2 fmt` — 格式化文件 + +```sh +# 格式化单个文件（原地修改） +d2 fmt input.d2 + +# 格式化多个文件 +d2 fmt a.d2 b.d2 c.d2 + +# 检查格式是否正确（不修改文件） +d2 --check input.d2 +``` + +### 3.4 `d2 play` — 禁用 + +`d2 play` 会将图表交给在线演练场处理。本 Skill 采用完全离线策略，禁止执行该命令，也不打开任何在线演练场。 + +如果用户需要预览，使用本地渲染命令生成 SVG 或 PNG；如果需要实时预览，只能使用绑定到 `localhost` 或 `127.0.0.1` 的 Watch 模式。 + +### 3.5 `d2 validate` — 验证语法 + +```sh +d2 validate input.d2 +``` + +仅验证 `.d2` 文件的语法正确性，不进行渲染。 + +--- + +## 四、命令行参数完整参考 + +### 4.1 核心参数 + +| 参数 | 短写 | 环境变量 | 默认值 | 说明 | +|------|------|----------|--------|------| +| `--watch` | `-w` | `D2_WATCH` | `false` | 监听文件变更并实时重载 | +| `--host` | `-h` | `HOST` | `localhost` | Watch 模式监听地址 | +| `--port` | `-p` | `PORT` | `0`（随机） | Watch 模式监听端口 | +| `--layout` | `-l` | `D2_LAYOUT` | `dagre` | 布局引擎 | +| `--theme` | `-t` | `D2_THEME` | `0` | 图表主题 ID | +| `--dark-theme` | | `D2_DARK_THEME` | `-1` | 暗色模式主题（-1 表示与亮色相同） | +| `--sketch` | `-s` | `D2_SKETCH` | `false` | 手绘风格渲染 | +| `--center` | `-c` | `D2_CENTER` | `false` | SVG 居中于视口 | +| `--scale` | | `SCALE` | `-1` | 缩放：-1=自动适配，1=原始，0.5=缩小一半 | +| `--pad` | | `D2_PAD` | `100` | 图表周围填充像素 | +| `--bundle` | `-b` | `D2_BUNDLE` | `true` | 将资源和图层打包到输出 SVG | +| `--target` | | | `*` | 指定渲染的 Board（`''` 仅根 Board，`*` 含所有子级） | +| `--animate-interval` | | `D2_ANIMATE_INTERVAL` | `0` | 多 Board 切换间隔（毫秒），仅 SVG/GIF | +| `--timeout` | | `D2_TIMEOUT` | `120` | 最大运行秒数 | +| `--browser` | | `BROWSER` | `""` | Watch 模式打开的浏览器（`0` 不打开） | +| `--img-cache` | | `IMG_CACHE` | `true` | Watch 模式缓存图标 | +| `--salt` | | | `""` | 为输出 ID 添加盐值（避免同页多图 ID 冲突） | +| `--debug` | `-d` | `DEBUG` | `false` | 输出调试日志 | +| `--check` | | `D2_CHECK` | `false` | 检查文件格式是否正确 | +| `--stdout-format` | | `D2_STDOUT_FORMAT` | `""` | 标准输出格式：svg/png/ascii/txt/pdf/pptx/gif | +| `--no-xml-tag` | | `D2_NO_XML_TAG` | `false` | 从 SVG 省略 XML 声明（便于 HTML 嵌入） | +| `--omit-version` | | `OMIT_VERSION` | `false` | 从输出图片中省略版本号 | +| `--force-appendix` | | `D2_FORCE_APPENDIX` | `false` | SVG 也添加附录（PNG 默认有附录） | +| `--ascii-mode` | | `D2_ASCII_MODE` | `extended` | 文本输出 ASCII 模式：standard / extended | +| `--version` | `-v` | | `false` | 输出版本号 | + +### 4.2 字体参数 + +| 参数 | 环境变量 | 默认字体 | +|------|----------|----------| +| `--font-regular` | `D2_FONT_REGULAR` | Source Sans Pro Regular | +| `--font-italic` | `D2_FONT_ITALIC` | Source Sans Pro Regular-Italic | +| `--font-bold` | `D2_FONT_BOLD` | Source Sans Pro Bold | +| `--font-semibold` | `D2_FONT_SEMIBOLD` | Source Sans Pro Semibold | +| `--font-mono` | `D2_FONT_MONO` | Source Code Pro Regular | +| `--font-mono-bold` | `D2_FONT_MONO_BOLD` | Source Code Pro Bold | +| `--font-mono-italic` | `D2_FONT_MONO_ITALIC` | Source Code Pro Italic | +| `--font-mono-semibold` | `D2_FONT_MONO_SEMIBOLD` | Source Code Pro Semibold | + +每个参数只接受本地 `.ttf` 字体文件路径。字体文件必须已经存在于当前工作区或用户明确指定的本地路径；禁止下载或访问远程字体。 + +### 4.3 布局引擎参数 + +**dagre（默认引擎）：** + +| 参数 | 默认值 | 说明 | +|------|--------|------| +| `--dagre-nodesep` | `60` | 节点间水平间距（像素） | +| `--dagre-edgesep` | `20` | 边与节点间水平间距（像素） | + +```sh +d2 --dagre-nodesep 80 --dagre-edgesep 30 input.d2 +``` + +**elk：** + +| 参数 | 默认值 | 说明 | +|------|--------|------| +| `--elk-algorithm` | `layered` | 布局算法 | +| `--elk-nodeNodeBetweenLayers` | `70` | 相邻层间节点间距 | +| `--elk-padding` | `[top=50,left=50,bottom=50,right=50]` | 父元素内边距 | +| `--elk-edgeNodeBetweenLayers` | `40` | 节点层与边的间距 | +| `--elk-nodeSelfLoop` | `50` | 自环间距 | + +```sh +d2 -l elk --elk-nodeNodeBetweenLayers 100 --elk-padding "[top=60,left=60,bottom=60,right=60]" input.d2 +``` + +--- + +## 五、D2 语言语法参考 + +### 5.1 形状 + +```d2 +imAShape # 形状（key 即标签） +pg: PostgreSQL # key 与标签不同 +SQLite; Cassandra # 分号分隔同行多形状 +"user-name": User Name # 特殊字符 key 用引号 +``` + +可用形状类型： + +| 形状 | 说明 | 形状 | 说明 | +|------|------|------|------| +| `rectangle` | 默认矩形 | `square` | 正方形 | +| `circle` | 圆形 | `oval` | 椭圆 | +| `diamond` | 菱形/决策 | `parallelogram` | 平行四边形 | +| `hexagon` | 六边形 | `octagon` | 八边形 | +| `triangle` | 三角形 | `cylinder` | 圆柱/数据库 | +| `queue` | 消息队列 | `page` | 文档 | +| `package` | 包/模块 | `cloud` | 云服务 | +| `callout` | 标注 | `step` | 流程步骤 | +| `text` | 纯文本（无边框） | `code` | 代码块 | +| `class` | UML 类图 | `sql_table` | 数据库表 | +| `sequence_diagram` | 时序图 | `image` | 图片/图标 | +| `stored_data` | 存储数据 | `person` | 人物 | + +```d2 +Cloud.shape: cloud +``` + +### 5.2 连接 + +| 操作符 | 含义 | +|--------|------| +| `->` | 有向箭头（指向目标） | +| `<-` | 有向箭头（指向源） | +| `<->` | 双向箭头 | +| `--` | 无向连线 | + +```d2 +A -> B: sends data # 带标签连接 +A -> B -> C -> D # 链式连接 +A <-> B # 双向 +``` + +**箭头样式：** + +| 类型 | 可填充 | 类型 | 可填充 | +|------|--------|------|--------| +| `triangle`（默认） | 是 | `arrow` | 否 | +| `diamond` | 是 | `circle` | 是 | +| `box` | 是 | `cross` | 否 | +| `cf-one` | 否 | `cf-many` | 否 | +| `cf-one-required` | 否 | `cf-many-required` | 否 | + +```d2 +a -> b: { + source-arrowhead: 1 + target-arrowhead: * { shape: diamond } +} +``` + +**引用重复连接：** + +```d2 +x -> y: hi +x -> y: hello +(x -> y)[0].style.stroke: red +(x -> y)[1].style.stroke: blue +``` + +### 5.3 容器/嵌套 + +```d2 +# 点号表示法 +server.process + +# 大括号嵌套 +clouds: { + aws: { + load_balancer -> api + api -> db + } +} + +# 容器标签简写 +gcloud: Google Cloud { ... } + +# 下划线 _ 引用父级 +_.christmas.presents -> presents: regift +``` + +### 5.4 文本格式 + +**Markdown：** + +```d2 +explanation: |md + # 标题 + - 列表项 + - 列表项 +| +``` + +**LaTeX 数学公式：** + +```d2 +formula: |latex + \lim_{h \rightarrow 0} \frac{f(x+h)-f(x)}{h} +| +``` + +**代码块（语法高亮）：** + +```d2 +code_block: |go + awsSession := From(c.Request.Context()) + client := s3.New(awsSession) +| +``` + +短别名：`md`→markdown, `tex`→latex, `js`→javascript, `go`→golang, `py`→python, `rb`→ruby, `ts`→typescript。 + +**内容含管道符时用扩展定界符：** + +```d2 +my_code: ||ts + declare function getSmallPet(): Fish | Bird; +|| +``` + +### 5.5 样式 + +| 属性 | 值 | 适用 | +|------|-----|------| +| `opacity` | 0.0 - 1.0 | 全部 | +| `stroke` | 颜色/渐变 | 全部 | +| `fill` | 颜色/渐变/transparent | 形状 | +| `fill-pattern` | dots / lines / grain / none | 形状 | +| `stroke-width` | 1 - 15 | 全部 | +| `stroke-dash` | 0 - 10 | 全部 | +| `border-radius` | 0 - 20 | 形状 | +| `shadow` | true / false | 形状 | +| `3d` | true / false | 矩形/正方形 | +| `multiple` | true / false | 形状（堆叠外观） | +| `double-border` | true / false | 形状 | +| `font` | mono | 全部 | +| `font-size` | 8 - 100 | 全部 | +| `font-color` | 颜色 | 全部 | +| `animated` | true / false | 全部 | +| `bold` | true / false | 全部 | +| `italic` | true / false | 全部 | +| `underline` | true / false | 全部 | +| `text-transform` | uppercase / lowercase / title / none | 全部 | + +```d2 +server: { + style: { + fill: "#FF5733" + stroke: blue + stroke-width: 3 + shadow: true + animated: true + } +} + +# 点号表示法 +server.style.fill: blue + +# 渐变填充 +server.style.fill: "#8BC34A;#0D47A1" + +# 根级样式（图表背景） +style: { + fill: "#f0f0f0" + fill-pattern: dots +} +``` + +### 5.6 图标 + +图标只能使用本地文件，路径应指向当前工作区或用户明确指定的本地资源。禁止使用 `http://`、`https://` 或其他远程地址。 + +```d2 +deploy: { + icon: ./assets/deploy.svg +} + +# 连接上的本地图标 +deploy -> backup: { + icon: ./assets/backup.svg +} + +# 图标位置 +server.icon.near: top-left +``` + +### 5.7 类 + +```d2 +classes: { + load_balancer: { + label: load\nbalancer + width: 100 + style: { + fill: "#44C7B1" + shadow: true + } + } +} + +# 应用类 +web_lb.class: load_balancer + +# 多个类（分号分隔，后者覆盖前者） +logo.class: [d2; sphere] +``` + +### 5.8 特殊参数 + +**`near` — 定位：** + +```d2 +title: "A winning strategy" { + near: top-center +} +``` + +位置值：`top-left`, `top-center`, `top-right`, `center-left`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right`。标签/图标还支持 `outside-*` 和 `border-*` 前缀。 + +**`direction` — 布局方向：** + +```d2 +direction: right # up / down / left / right，默认 down +``` + +**`tooltip` — 交互式提示（仅 SVG）：** + +```d2 +codedeploy: { + tooltip: |md + 提示信息 + | +} +``` + +**`link` — 本地链接：** + +离线模式只允许指向本地工作区内的相对路径，不允许外部 URL： + +```d2 +docs: { link: "./docs/index.html" } +``` + +**`width` / `height` — 尺寸：** + +```d2 +server: { width: 100; height: 200 } +``` + +### 5.9 图层、场景、步骤 + +**图层 — 不同抽象层级：** + +```d2 +layers: { + detail: { + Virginia data center <-> Hong Kong data center + } +} + +# 导航链接 +overview.link: layers.detail +``` + +**场景 — 同一基础图的不同视角：** + +```d2 +scenarios: { + hotfix: { + (local.code -> github.dev)[0].style.opacity: 0.1 + } +} +``` + +**步骤 — 事件序列（动画）：** + +```d2 +steps: { + 1: { Approach road } + 2: { Approach road -> Cross road } + 3: { Cross road -> Make you wonder why } +} +``` + +### 5.10 变量与配置 + +```d2 +vars: { + primary-color: "#FF5733" + server-width: 150 +} + +server: { + style.fill: ${primary-color} + width: ${server-width} +} + +# 内置配置 +vars: { + d2-config: { + layout-engine: elk + theme-id: 300 + dark-theme-id: 200 + theme-overrides: { + B1: "#2E7D32" + } + } +} +``` + +### 5.11 导入 + +导入只允许使用当前工作区或用户明确指定的本地路径。禁止使用网络 URL、远程仓库或任何会触发下载的导入方式。 + + +```d2 +# 整体导入 +a: @x.d2 + +# 展开导入 +a: { + ...@x.d2 +} + +# 部分导入 +...@people.management + +# 相对路径 +y: @../y + +# 绝对路径（Windows 需引号） +x: @"C:\path\to\file" +``` + +### 5.12 Glob 模式 + +```d2 +*.style.fill: blue # 所有直接子元素 +aws.*.style.stroke: red # aws 下所有子元素 +**.style.border-radius: 8 # 递归所有后代 +``` + +### 5.13 特殊形状语法 + +**SQL 表：** + +```d2 +users: { + shape: sql_table + id: int {constraint: primary_key} + email: varchar {constraint: unique} + department_id: int {constraint: foreign_key} +} +users.department_id -> departments.id +``` + +**UML 类图：** + +```d2 +DatabaseManager: { + shape: class + +connection: Connection # 公开 + -poolSize: int # 私有 + #timeout: int # 受保护 + +connect(): void + -validateConnection(): bool +} +``` + +**时序图：** + +```d2 +sequence: { + shape: sequence_diagram + alice; bob + alice -> bob: Hello + bob -> alice: Hi + alice -> alice: thinking... +} +``` + +### 5.14 注释 + +```d2 +# 这是注释 +``` + +### 5.15 保留关键字 + +以下关键字作为标识符时需加引号：`shape`, `style`, `label`, `width`, `height`, `icon`, `tooltip`, `link`, `near`, `direction`, `class`, `constraint` + +--- + +## 六、常用命令速查 + +```sh +# 基本渲染 +d2 input.d2 output.svg + +# 使用 ELK 布局 + Terminal 主题 +d2 -l elk -t 300 input.d2 + +# 手绘风格 + 暗色主题 +d2 --sketch --dark-theme 200 input.d2 output.png + +# Watch 模式（实时预览） +d2 --watch input.d2 + +# Watch 模式指定端口，不打开浏览器 +d2 -w -p 8080 --browser 0 input.d2 + +# 从标准输入读取，输出 PNG 到标准输出 +echo "x -> y: hello" | d2 - --stdout-format png - > out.png + +# 缩放 50% +d2 --scale 0.5 input.d2 output.png + +# 渲染特定 Board +d2 --target='layers.detail' input.d2 + +# 格式化 .d2 文件 +d2 fmt input.d2 + +# 验证 .d2 文件语法 +d2 validate input.d2 + +# 在线演练场功能已禁用；请使用本地 SVG/PNG 渲染或本地 Watch 模式 + + +# 检查格式 +d2 --check input.d2 + +# 查看版本 +d2 --version + +# 查看帮助 +d2 --help +``` + +--- + +## 七、注意事项 + +1. **判断渲染成功**：始终以 `d2` 的退出状态码为准，而非输出文件是否存在（出错时可能仍生成部分渲染文件）。 +2. **Key 大小写**：D2 的 key 是大小写不敏感的，`PostgreSQL` 和 `postgresql` 引用同一个形状。 +3. **Markdown 标签**：若对形状设置了 Markdown 标签，需显式声明 `shape` 类型（即使为默认的 `rectangle`）。 +4. **连接引用**：连接必须引用形状的 key，而非标签。 +5. **重复连接**：重复的连接声明会创建新连接，不会覆盖。 +6. **Watch 模式图标缓存**：如图标可能变化，使用 `--img-cache=false` 禁用缓存。 +7. **完全离线**：禁止 `d2 play`、远程图标、外部链接、远程导入、远程字体和任何 `http://` 或 `https://` 资源；只使用本地输入和资源。 +8. **Watch 模式**：只绑定 `localhost` 或 `127.0.0.1`，本地预览不向外部服务发送内容。 +9. **本地资源缺失**：报告缺失路径并使用默认样式或停止处理，不自动下载替代资源。 +10. **大图超时**：渲染大型图表时，增大 `--timeout` 值。 +11. **同页多图**：使用 `--salt` 避免输出 SVG 中 ID 冲突。 +12. **环境变量**：参数可通过对应的环境变量设置，适合脚本化和 CI/CD 场景；环境变量的值不得包含远程资源地址。 diff --git a/skills/D2-Diagrams/references/release.md b/skills/D2-Diagrams/references/release.md new file mode 100644 index 0000000..7f6d07b --- /dev/null +++ b/skills/D2-Diagrams/references/release.md @@ -0,0 +1,86 @@ +# D2 v0.7.1 发布与二进制来源说明 + +## 1. 适用范围 + +本文档记录 `D2-Diagrams` Skill 所附带的 D2 工具来源、版本、许可证、上游发布资产和本地二进制摘要。 + +本 Skill 采用完全离线执行策略。本文档中的 URL 仅供用户手动查阅，Skill 不会自动访问、下载、安装或更新任何外部资源。 + +## 2. 上游项目 + +| 项目 | 信息 | +|---|---| +| 项目名称 | D2 | +| 源代码仓库 | | +| 官方网站 | | +| 使用版本 | `v0.7.1` | +| 许可证 | MPL-2.0 License | +| Release 页面 | | +| Release 状态 | 正式版本，非 draft，非 prerelease | +| Release 发布时间 | 2025-08-19 13:50:56 UTC | +| Release target | `master` | + +## 3. 当前 Skill 中的本地文件 + +| 字段 | 值 | +|---|---| +| 文件 | `D2-Diagrams/d2.exe` | +| 实测版本 | `v0.7.1` | +| 文件大小 | 48,073,216 bytes | +| 本地 SHA-256 | `babff7db293aada7d0eceee786934fd087746e7b22c038bc93d23c188ce4206b` | +| 用途 | Windows 本地 D2 语法验证和图表渲染 | + +本地 SHA-256 是对当前 Skill 目录中 `d2.exe` 文件本身计算得到的摘要。它不能直接与上游压缩包或 MSI 的摘要比较，因为上游摘要对应的是发布资产容器，而不是解包后的 `d2.exe`。本说明不宣称当前本地文件与某个上游压缩包已经完成二进制级别的逐字节匹配。 + +## 4. v0.7.1 上游 Windows 发布资产 + +以下信息来自 GitHub Release `v0.7.1` 的 Release API 元数据。 + +| 资产 | 类型 | 大小 | 上游 SHA-256 | +|---|---|---:|---| +| `d2-v0.7.1-windows-amd64.msi` | Windows 安装包 | 19,140,608 bytes | `45c75848c0201ec68b3a3a88179a3294c7b12204e39b42bd62c76c6c6ea1613d` | +| `d2-v0.7.1-windows-amd64.tar.gz` | Windows amd64 压缩包 | 21,433,267 bytes | `d289c2866221c618c9fc6efcd416ee8c16e122bd0100761aea51001e3c958f57` | +| `d2-v0.7.1-windows-arm64.tar.gz` | Windows arm64 压缩包 | 20,007,517 bytes | `c7ebdc7b2f6df513b715d431762105386f7c702b0b2dddff2a500a032b1bba67` | + +同一 Release 还提供 Linux amd64、Linux arm64、macOS amd64 和 macOS arm64 资产；当前 Skill 不使用这些资产，因为主 Skill 明确限定内置工具仅在 Windows 环境运行。 + +## 5. v0.7.1 Release 摘要 + +### 新功能 + +- 支持将图表输出为 ASCII 文本格式（`txt`）。 +- 新增 `cross` 箭头形状。 +- 支持类字段和方法的 `style.underline`。 +- Markdown、LaTeX 和代码可作为边标签。 +- 支持 `border-x` 标签定位。 +- 设置 `near` 的工具提示始终显示。 +- CLI 支持通过 `--font-mono`、`--font-mono-bold`、`--font-mono-italic` 和 `--font-mono-semibold` 自定义等宽字体。 + +### 改进 + +- 场景和步骤 Board 支持使用主要值设置标签。 +- 自动格式化器保留 Board 顺序。 +- Legend 支持自定义标题或标签，适合非英文图表。 +- Sketch 模式在提供自定义字体时使用自定义字体。 + +### 修复 + +- 修复时序图中角色同时带标签和图标时可能重叠的问题。 +- 修复场景中的 double glob 传播问题。 +- 修复部分场景下图表边界未计入 Legend 的问题。 + +### 兼容性注意事项 + +如果将 D2 作为库或 API 使用，v0.7.1 中带有 `sketch` 的渲染传入 `FontFamily` 时会实际使用该字体；这与 v0.7.0 及更早版本忽略该字体的行为不同。本 Skill 通过本地 CLI 使用 D2，不直接调用 D2 库 API。 + +## 6. 更新记录要求 + +更新 `d2.exe` 时，维护者应同步更新本文件中的： + +1. 使用版本和 Release 发布时间。 +2. 本地文件大小和本地 SHA-256。 +3. 对应上游 Windows 发布资产及其 SHA-256。 +4. 许可证和来源链接（如果上游项目发生变化）。 +5. 与 `SKILL.md`、`doc.md` 中版本相关的说明。 + +本文件只记录来源和摘要，不提供自动校验脚本。发布前应由维护者手动核对版本、文件大小和 SHA-256；Skill 运行过程中不执行下载或联网校验。 diff --git a/skills/D2-Diagrams/references/troubleshooting.md b/skills/D2-Diagrams/references/troubleshooting.md new file mode 100644 index 0000000..e7d76c4 --- /dev/null +++ b/skills/D2-Diagrams/references/troubleshooting.md @@ -0,0 +1,84 @@ +# D2 故障排查与边界处理 + +## 使用范围 + +本文件是 D2 Skill 的按需故障排查参考。主流程先执行 `SKILL.md` 中的前置要求和运行前检查；遇到异常或边界情况时，再根据本文件选择停止、修复后重试或请求用户确认的动作。 + +本 Skill 采用完全离线策略。任何故障都不得通过下载依赖、访问远程资源、上传图表内容或从系统 PATH 中猜测其他 D2 来绕过。 + +## 处理动作说明 + +| 动作 | 含义 | +|---|---| +| **停止** | 不继续验证或渲染，向用户说明阻断原因和需要补充的信息 | +| **修复后重试** | 只在用户输入、参数或本地资源修正后重新执行对应检查，不跳过前置检查 | +| **请求确认** | 涉及覆盖文件、改变输出路径或改变用户选择时，先获得明确确认 | +| **降级处理** | 仅在不改变图表语义且用户接受时使用默认主题、默认布局或不使用缺失的可选资源 | + +## 平台与工具 + +| 场景 | 识别方式 | 处理方式 | 是否重试 | +|---|---|---|---| +| 非 Windows 环境 | 系统不是 Windows | 停止；说明内置 `d2.exe` 只能在 Windows 运行；不自动下载或安装替代工具 | 用户切换到 Windows 后再试 | +| `d2.exe` 缺失 | `/d2.exe` 不存在或无法读取 | 停止；报告解析出的工具路径；不要从 PATH、网络或其他目录自动替换 | 用户补齐或明确指定合规的 Skill 文件后再试 | +| 版本不匹配 | `d2.exe --version` 不是预期 `v0.7.1` | 停止；报告实际版本；不要自动升级、降级或替换二进制；来源和发布信息见 [`release.md`](release.md) | 用户确认合规二进制后再试 | +| 二进制不可执行 | 文件存在但启动失败、权限不足或进程立即异常退出 | 停止；报告工具路径和错误输出，检查本地文件权限和完整性 | 修复本地环境后再试 | +| 工具命令异常 | 命令返回非零状态但无法归类 | 保留完整错误输出，先确认平台、路径和版本，再决定是否修复输入或参数 | 不要盲目重复执行 | + +## 输入与源文件 + +| 场景 | 识别方式 | 处理方式 | 是否重试 | +|---|---|---|---| +| 输入文件不存在 | 指定路径无法读取 | 停止；报告实际解析路径，请用户提供存在且可读的 `.d2` 文件 | 用户修正路径后再试 | +| 扩展名不符合 | 输入不是 `.d2` 或用户只提供了未保存的文本 | 请求用户确认文件路径，或在明确允许时先保存为工作区内的 `.d2`；不要擅自改变原文件 | 修正输入后再试 | +| 输入文件不可读 | 权限、锁定或编码导致读取失败 | 停止；报告路径和可见错误，不读取工作区外的替代文件 | 用户修复权限或提供副本后再试 | +| D2 语法验证失败 | `validate` 返回失败状态或错误输出 | 不进入渲染；报告错误位置和摘要；只修改用户授权的源文件，修复后重新验证 | 修复后重试验证 | +| 输入包含不支持的语法或形状 | 验证错误指向语法、形状或引擎能力 | 参考 `doc.md`，改用当前版本支持的写法；不要静默改写用户语义 | 修复后重试验证 | +| 多份输入或多张图 | 用户提供多个 `.d2` 文件或要求多个产物 | 逐个记录源文件与对应产物，某一份失败时单独报告，不把其他文件的成功状态覆盖过去 | 按文件分别重试 | + +## 外部资源与离线边界 + +| 场景 | 识别方式 | 处理方式 | 是否重试 | +|---|---|---|---| +| 远程图标、链接、导入或字体 | D2 内容出现 `http://`、`https://` 或远程资源声明 | 停止渲染；指出资源位置，请用户改为工作区或明确指定的本地资源；绝不访问 URL | 替换为本地资源后再试 | +| 本地图标、字体或导入文件缺失 | 引用的本地路径不存在或不可读 | 报告缺失路径；如果资源是可选样式，可在用户接受时使用默认样式；如果会改变语义则停止 | 补齐资源或确认降级后再试 | +| 本地资源路径越界 | 路径指向工作区外或未获用户明确指定的位置 | 停止并请求工作区内路径或明确授权的本地路径；不自动复制或读取敏感目录 | 用户提供合规路径后再试 | +| 输入可能包含敏感内容 | 图表源或产物包含凭据、个人信息或内部拓扑 | 保持本地处理，提醒用户检查输出和共享范围；不上传、不调用在线演练场、不在无关日志中复制内容 | 用户确认脱敏或继续后再试 | + +## 输出与文件系统 + +| 场景 | 识别方式 | 处理方式 | 是否重试 | +|---|---|---|---| +| 输出格式不支持 | 用户指定的格式不在当前支持列表中 | 报告支持的格式，询问用户改用哪一种；不要伪造扩展名或声称完成转换 | 用户选择支持格式后再试 | +| 输出目录不存在 | 目标目录无法解析 | 请求用户选择已存在且可写的工作区目录；不擅自创建工作区外目录 | 用户确认目录后再试 | +| 输出目录不可写 | 创建文件或渲染时出现权限错误 | 停止；报告目录和权限错误，请用户修复权限或选择其他目录 | 修复后再试 | +| 目标文件已存在 | 目标路径已有文件 | 默认不覆盖；询问用户覆盖、改名或选择其他目录；未经确认不得删除或替换 | 用户明确选择后再试 | +| 输出文件存在但命令失败 | 文件存在，但 D2 退出状态为非零 | 以退出状态和错误输出为准，不把残留或旧文件当作新产物；报告该文件可能是旧版本或不完整文件 | 修复问题并使用新路径或经确认后再试 | +| 多种格式输出 | 用户要求 SVG、PNG 等多个格式 | 每种格式单独记录退出状态和产物路径；某种格式失败时单独报告 | 只重试失败格式 | + +## 渲染参数、性能与 Watch + +| 场景 | 识别方式 | 处理方式 | 是否重试 | +|---|---|---|---| +| 布局或主题参数无效 | 命令返回参数错误或渲染未启动 | 报告实际参数；恢复默认布局、主题或其他参数前先说明，必要时询问用户 | 修正参数后再试 | +| 渲染超时 | 达到 `--timeout` 限制或进程未在合理时间结束 | 停止当前尝试；报告超时和参数；可在用户接受时提高超时、简化图表或拆分图表，不无限重试 | 调整后重试 | +| 图表过大或布局质量不可接受 | 渲染成功但布局拥挤、截断或难以阅读 | 先向用户说明视觉问题；可调整方向、布局、缩放、边距或拆分内容，保留原源文件 | 根据用户反馈重渲染 | +| Watch 绑定公网地址 | 配置使用非 `localhost` 或非 `127.0.0.1` 地址 | 停止 Watch；改为本机地址；不开放端口、不向外部服务发送图表内容 | 用户确认本机地址后再试 | +| Watch 过程异常 | 本地预览进程退出或无法监听 | 报告本机监听地址和错误；需要静态产物时改走一次性验证和渲染，不自动启动公网服务 | 修复本机环境后再试 | + +## 统一处理流程 + +遇到任一异常时，按以下顺序处理： + +1. 记录失败阶段：平台、工具、输入、验证、渲染、写入或 Watch。 +2. 保留用户可复现所需的信息：源文件路径、工具版本、输出格式、关键参数和错误摘要。 +3. 判断是停止、修复后重试、请求确认还是允许降级；不要跳过失败检查。 +4. 修复后从失败的检查点重新开始；如果输入或参数改变，重新执行验证再渲染。 +5. 成功时同时报告验证状态、渲染状态和实际产物路径；失败时明确说明是否生成了可用产物。 +6. 不删除源文件、不覆盖已有产物、不修改工作区外文件，除非用户明确要求且操作范围已确认。 + +## 相关参考 + +- 主流程和基本前置检查：[`../SKILL.md`](../SKILL.md) +- D2 语法和参数：[`../doc.md`](../doc.md) +- 内置二进制来源、版本和完整性信息：[`release.md`](release.md) diff --git a/skills/HTMD/SKILL.md b/skills/HTMD/SKILL.md new file mode 100644 index 0000000..d7d8783 --- /dev/null +++ b/skills/HTMD/SKILL.md @@ -0,0 +1,148 @@ +--- +name: htmd-spec +description: HTMD（类HTML标记语言）规范技能——当用户请求设计规范、技术规格、标准文档、需求文档，或想要记录系统架构时使用此技能。也适用于将常规markdown文档转换为结构化格式。此技能提供标签定义、书写规范，并指导如何将普通markdown转换为结构化的HTMD格式。 +--- + +# HTMD 规范技能 + +HTMD（HTML-like Markdown）是一种结构化文档格式，使用类 XML 标签标记内容，使信息更具组织性和语义性，更易于大模型理解。HTMD 文件使用 `.htmd` 后缀。 + +## 何时使用此技能 + +以下情况触发此技能： + +- 用户请求设计规范、技术规格或标准文档。 +- 用户要求记录系统架构或模块设计。 +- 用户希望将现有 Markdown 文档转换为结构化格式。 +- 用户明确提及 HTMD 或类似的标记语言格式。 +- 用户描述需要对项目、API 或系统进行正式规范。 + +生成的设计规范应根据任务需要提供足够的生产级细节，包括项目结构、API 定义、数据流和执行流程、数据库或存储结构、配置项以及错误处理。不要为了填充模板而添加与实际设计无关的内容。 + +## 按需读取参考资料 + +主文件只保留核心规则和工作流程。根据任务需要读取以下 L3 资料： + +- [`references/tags.md`](references/tags.md)：核心标签目录、动态标签选择、内容模型细节和内容覆盖建议。 +- [`references/patterns.md`](references/patterns.md)：项目、API、事件、错误、流程、数据库模式和 Markdown 转换示例。 +- [`references/schema.md`](references/schema.md)：标签语义、包含关系和非强制设计原则的集中参考。 +- [`SPEC.htmd`](SPEC.htmd)：动态标签组织结构示例；文件内含不安全示例警告，不得直接作为生产架构使用。 + +这些资料是按需加载的语义参考，不是封闭标签白名单，也不要求所有文档采用相同的标签集合、层级或格式。 + +## 核心内容模型 + +HTMD 使用 XML-like 标签组织文档。标签实例根据实际承载内容分为两类：**元素**和**容器元素**。 + +### 元素 + +元素是承载文本的最小语义单元。自然语言、编号步骤、JSON、代码和协议示例都应位于开始标签与结束标签之间： + +```htmd +项目描述。 + + { + "name": "example" + } + +``` + +### 容器元素 + +容器元素用于承载一个或多个子元素，表达模块、组成部分、关系或层级。容器本身不直接承载未被标签包裹的文本；需要标题或说明时，使用 `` 或其他元素： + +```htmd + + 模块说明。 + 模块中的关键事实。 + +``` + +### 动态内容模型 + +核心标签用于常见语义；核心标签无法准确表达实际设计时，创建动态标签。动态标签的名称、类型和包含关系可以随设计调整： + +- 标签实例直接承载文本时属于元素。 +- 标签实例包含子标签时属于容器元素。 +- 不要在同一实例中混合未包裹文本和子标签。 +- 动态容器可以包含核心元素、核心容器、动态元素和动态容器。 +- 子标签应解释、分解或补充父标签表达的对象。 + +## 核心结构规则 + +1. 项目规范通常以 `` 作为唯一根容器；其下的模块、接口、实现、配置和关系按实际设计组织。其他类型的文档可以选择更准确的唯一根容器。 +2. 每个开始标签都必须有对应的结束标签，不依赖 HTML 中可省略结束标签的写法。 +3. 不使用 ``，也不输出没有内容的 ``；没有信息时省略该标签。 +4. 所有说明、列表、编号步骤、JSON、代码和其他文本都必须位于某个元素内部；容器不直接包含裸文本。 +5. HTMD 标签不使用属性；需要表达元数据时，将其放入元素文本或子元素。 +6. 标签名称应避免空格、引号、属性和未转义的特殊字符；英文小写和连字符通常更易读，但标签集合不封闭。 +7. 核心标签语义匹配时优先使用；无法准确表达时再创建动态标签，不要为了套用模板牺牲语义清晰度。 + +## 排版建议 + +- 推荐每层嵌套使用 **2 个空格**，便于识别层级。 +- 缩进、换行、空格数量、字段排列和标签出现顺序不是 HTMD 的语法要求。 +- 可以采用其他清晰一致的排版方式，不因空格数量不同判定内容无效。 +- 代码、JSON、命令和协议文本应完整保留在元素内部，不要为了统一排版破坏其内容。 + +## 内容完整性建议 + +根据任务需要选择下列内容，不要求机械填满所有项目： + +| 信息类型 | 推荐承载 | 建议覆盖内容 | +|---|---|---| +| 项目结构 | ``、`` 或动态模块容器 | 目录结构、模块职责、关键文件用途 | +| API 定义 | ``、``、``、`` | 参数、类型、必填性、返回值、错误码和样例 | +| 数据流和流程 | `` 或动态流程容器 | 步骤、输入输出、条件分支和异常流程 | +| 数据库或存储 | ``、``、`` | 字段、类型、约束、索引、关系和用途 | +| 配置项 | ``、`` | 名称、类型、默认值、范围和用途 | +| 错误处理 | ``、`` | 场景、状态、响应格式和恢复方式 | + +需要完整标签说明时读取 [`references/tags.md`](references/tags.md)；需要具体格式示例时读取 [`references/patterns.md`](references/patterns.md)。 + +## 工作流程 + +### 直接创建 HTMD + +1. **捕获目标**：确认文档对象、读者、用途和所需详细程度。 +2. **识别层级**：区分整体对象、主要组成部分、行为、关系和约束。 +3. **选择标签**：核心标签能准确表达时优先使用，否则创建语义明确的动态标签。 +4. **确定内容模型**：简单文本使用元素，需要组织多个信息单元时使用容器元素。 +5. **组织关系**：让子元素自然归属于父元素，不为了固定模板增加无意义层级。 +6. **补充细节**：按任务需要覆盖接口、流程、数据、配置、安全和错误处理。 +7. **语义自检**：检查标签闭合、文本包裹、空标签、层级归属和内容完整性。 +8. **按需参考**：遇到具体标签或模式选择困难时，再读取 `tags.md`、`patterns.md` 或 `schema.md`。 + +### Markdown 转 HTMD + +1. **识别文档类型**：判断是项目、系统、模块、API、流程还是其他领域对象。 +2. **分析内容层级**：区分顶层对象、主要部分和详细信息。 +3. **执行语义映射**：参考 [`references/patterns.md`](references/patterns.md) 的映射表；不要机械按 Markdown 标题套用标签。 +4. **选择内容模型**：需要展开的对象使用容器元素，简单文本使用元素。 +5. **应用排版建议**：推荐使用 2 空格缩进增强可读性，但不作强制要求。 +6. **检查结构**：确保标签闭合、所有文本被元素包裹、没有空元素，并确认父子关系能够表达实际设计。 +7. **输出文件**：保存为 `.htmd`；是否保留原始 Markdown 由任务需要决定。 + +## 输出契约 + +输出 HTMD 时遵循以下结构约束和表达建议： + +- 使用 `.htmd` 文件后缀。 +- 所有元素和容器元素使用成对标签。 +- 不使用空元素。 +- 文本、JSON、代码和编号步骤都放在元素内部。 +- 保持结构层级清晰，并根据实际设计选择标签。 +- 推荐 2 空格缩进，但不把缩进或标签顺序当作语法条件。 + +## 语义自检清单 + +这不是机器校验器，而是生成或转换完成后的思考顺序： + +1. 每个标签是否表达了可识别的对象、行为、关系或约束？ +2. 需要展开的对象是否使用了容器元素？ +3. 简单文本是否被不必要地拆成过多层级？ +4. 动态标签是否比泛化标签更准确？ +5. 父子关系是否能帮助读者理解归属和因果？ +6. 是否存在裸文本、空标签或未闭合标签？ +7. API、流程、数据、配置、错误和安全信息是否覆盖了当前任务真正需要的部分？ + diff --git a/skills/HTMD/SPEC.htmd b/skills/HTMD/SPEC.htmd new file mode 100644 index 0000000..411180b --- /dev/null +++ b/skills/HTMD/SPEC.htmd @@ -0,0 +1,254 @@ + + + 不安全示例警告：本文件仅用于展示 HTMD 的标签结构和动态标签组织方式，不得直接用于生产环境。 + 文件访问、命令执行、黑名单和自动授权策略是概念性设计，未达到生产安全基线；使用前必须重新设计路径沙箱、最小权限、允许列表、逐次确认、审计和回滚机制。 + + + 这是一个基于python语言的单会话大模型本地Agent项目，用于调用大模型并在本地执行指令，以完成用户指定的任务。 + + + + + 支持以命令行模式运行，接受用户输入，调用大模型，本地执行指令，并返回结果。 + + /quit：退出命令行模式。 + + + /help：显示帮助信息，列出所有可用命令及其说明。 + + + /y：允许当前待执行指令执行。 + + + /n：不允许当前待执行指令执行。 + + + /y-all：自动允许后续所有指令执行（将授权模式设为1）。 + + + /n-all：后续指令执行需要申请授权（将授权模式设为0）。 + + + /reset：重置会话，清除会话历史。 + + + 1. 用户输入消息，调用Model模块处理。 + 2. Model模块调用LLM并返回结果，若结果中包含命令调用，进入授权流程。 + 3. 若需要授权（auth_mode=0），Model模块在终端展示待执行命令，等待用户输入 /y、/n、/y-all、/n-all。 + 4. 用户授权后，执行命令，结果反馈给LLM继续多轮对话。 + 5. 用户拒绝则将拒绝信息反馈给LLM，继续对话。 + 6. 当LLM返回中不含任何命令调用时，对话停止，等待用户输入。 + + + + 支持以web模式运行，接受用户输入，调用大模型，本地执行指令，并返回结果。提供一个web界面，用户可以通过web界面输入指令，查看结果。 + + 支持用户输入指令执行并返回结果 + + + 支持文件管理功能 + + + 支持指令授权模式修改，支持显示主题修改，支持会话重置 + + + 1. 用户在Web界面输入消息，前端通过SSE流式连接调用Model模块。 + 2. Model模块以SSE事件流逐步推送：LLM回答片段(chunk) → 命令解析结果 → 授权请求(若需要)。 + 3. 若需要授权，前端弹出授权弹窗，用户选择允许/拒绝/部分允许。 + 4. 用户授权后，Model模块执行命令，推送执行结果事件。 + 5. 用户拒绝则推送拒绝事件，Model模块将拒绝信息反馈给LLM。 + 6. 当LLM返回中不含任何命令调用时，推送done事件，对话停止。 + + + answering：开始新一轮LLM调用。附加字段：iteration + + + chunk：LLM回答片段。附加字段：content + + + response_done：一轮LLM回答完成。附加字段：iteration, commands + + + auth_required：需要用户授权。附加字段：commands + + + waiting_auth：等待用户授权响应。附加字段：iteration + + + executing：正在执行命令。附加字段：commands + + + execution_done：命令执行完成。附加字段：results + + + auth_denied：用户拒绝授权。附加字段：message + + + error：发生错误。附加字段：error + + + done：整个对话轮次结束。附加字段：iteration + + + + + + 控制模块，配置信息加载维护，并控制整个Agent的运行。 + 启动时从config.json加载配置项，获取当前操作系统名称，注入到system_prompt的{system_name}占位符中 + 指令授权模式采用一个整型变量auth_mode进行保存，0为需要授权，1为自动授权，由控制模块维护，读取/修改需要加锁(threading.Lock) + 授权模式修改为临时性修改，不视作配置修改，不进行持久化 + auth_mode初始值从配置文件的auth_mode字段读取，若未配置则默认为0（需要授权） + 会话重置(/reset)时，授权模式恢复为初始值 + 配置文件在CLI模式与Web模式下均不提供修改功能，也不支持持久化保存 + 控制模块开放一个授权查询接口get_auth_mode() -> int，供命令模块调用，以查询当前授权模式，读取时加锁 + 控制模块开放一个授权修改接口set_auth_mode(mode: int)，当Web模式修改认证模式，及命令行模式执行/y-all或/n-all修改认证模式时，由控制模块接受请求并修改认证模式，写入时加锁 + 控制模块开放一个获取配置接口get_config() -> Config，返回当前配置对象的只读引用 + 控制模块开放一个重置授权接口reset_auth()，将授权模式恢复为配置文件中的初始值，加锁操作 + + + 模型模块，负责命令行模式/web模式交互，负责调用大模型，并返回结果。 + 模型模块调用大模型，并返回结果 + 允许大模型以json格式申请调用工具与指令 + 当大模型申请调用工具与指令时，自动调用命令模块执行该工具/指令 + 当大模型尝试同时执行多个指令时，模型模块采用线性串行模式，逐个传入并调用命令模块，由命令模块逐个进行解析、获取授权及执行，每条指令的授权与执行结果独立处理 + 工具/指令执行完毕后，将结果返回给大模型，并自动进行下一轮对话 + 当大模型的返回中不含任何工具/指令调用时，对话停止并等待用户输入 + 受工具/指令调用所触发的多轮调用，轮数受配置文件中的round_limit值限制。到达限制值时自动停止对话 + 模型模块开放一个授权请求接口request_auth(commands: list) -> AuthResult，供命令模块调用，以向用户申请授权 + CLI模式下授权请求在终端展示待执行命令列表，等待用户输入/y、/n、/y-all、/n-all + Web模式下授权请求通过SSE推送auth_required事件，等待前端通过/api/authorize-execute接口返回授权结果 + + CLI模式：同步阻塞调用，直接返回完整结果ChatResult。可使用流式或非流式LLM调用，直接打印到终端。授权交互通过终端输入/y、/n、/y-all、/n-all。结果展示直接终端打印。错误在终端打印。 + + + Web模式：SSE流式输出，分步推送事件。必须使用流式LLM调用，逐chunk推送。授权交互通过前端弹窗确认，通过API返回结果。结果展示通过SSE事件推送至前端渲染。错误在对话窗口中显示，样式同指令执行结果。 + + + chat(message: str) -> ChatResult：CLI模式同步阻塞调用，返回完整结果（含LLM响应、命令列表、执行结果、错误信息） + + + chat_stream(message: str) -> Iterator[SSEEvent]：Web模式流式调用，返回SSE事件迭代器，逐步推送 + + + request_auth(commands: list) -> AuthResult：供Command模块调用，向用户申请授权。CLI模式阻塞等待终端输入，Web模式阻塞等待API回调。AuthResult包含authorized(bool)和commands(list) + + + reset_conversation()：清除会话历史，通知Controller重置授权状态 + + + get_history() -> list[dict]：返回当前会话历史记录 + + + LLM API调用失败时，向用户返回错误信息，但不退出程序。等待用户输入：用户可输入新消息重新调用LLM API继续会话。CLI模式在终端打印错误信息，Web模式通过SSE推送error事件在对话窗口中显示。 + + + + 命令模块，负责解析指令，并返回结果。 + 收到指令后，进行解析 + 调用控制模块的授权查询接口get_auth_mode()，以查询当前授权模式 + 根据授权模式，判断是否需要授权：auth_mode=0需要授权，auth_mode=1自动授权 + 如果需要授权，则调用模型模块的授权请求接口request_auth()，以向用户申请授权 + 如果用户授权，则执行指令，将结果返回给模型模块，并继续对话 + 如果用户拒绝，则将用户拒绝的信息返回给模型模块，由模型模块反馈给LLM继续对话 + 命令执行前进行安全检查，黑名单仅保留"rm -rf /"，匹配到黑名单模式的命令将被阻止执行，匹配规则为命令字符串中包含黑名单模式（不区分大小写） + 命令执行超时机制：超时时长通过配置文件的cmd_timeout字段设置，默认60秒 + 文件类命令（list_dir、make_dir、delete_dir、rename_dir、read_file、write_file、delete_file、edit_file、rename_file）通过File模块执行，Command模块负责解析、授权检查、安全检查后，将执行委托给File模块 + 非文件类命令（exec_cmd）由Command模块直接执行 + 命令执行失败的错误返回格式同现有设计中指令执行信息返回的格式，但将信息部分替换为错误信息，格式为：[action] [参数摘要] Error: 错误信息 + 命令执行失败不影响后续命令的执行（同一轮次中的其他命令继续执行） + 所有命令执行结果（包括失败的）统一反馈给LLM进行后续处理 + + list_dir：列出目录内容。参数：path(可选，默认当前目录)。执行方式：委托File模块。 + + + make_dir：创建目录。参数：path(必填)。执行方式：委托File模块。 + + + delete_dir：删除目录。参数：path(必填)。执行方式：委托File模块。 + + + rename_dir：重命名目录。参数：path(必填), new_name(必填)。执行方式：委托File模块。 + + + read_file：读取文件内容。参数：path(必填), start_line(可选), end_line(可选)。执行方式：委托File模块。 + + + write_file：写入文件。参数：path(必填), content(必填)。执行方式：委托File模块。 + + + delete_file：删除文件。参数：path(必填)。执行方式：委托File模块。 + + + edit_file：编辑文件内容。参数：path(必填), operation(必填: add/del/modify), start_line(必填), end_line(必填: del/modify), content(必填: add/modify)。执行方式：委托File模块。 + + + rename_file：重命名文件。参数：path(必填), new_name(必填)。执行方式：委托File模块。 + + + exec_cmd：执行Shell命令。参数：command(必填)。执行方式：Command模块直接执行。 + + + parse_and_execute(commands: list) -> list[ExecutionResult]：解析命令列表，进行授权检查和安全检查，执行并返回结果列表。ExecutionResult包含action(str)、params(dict)、result(str) + + + execute(action: str, params: dict) -> str：直接执行单条命令，跳过授权检查。用于Web直接命令面板等场景。文件类命令同样委托File模块执行。 + + + + 文件模块，负责文件管理功能，为Command模块的文件类命令和Web模式的文件管理API提供统一执行层。 + 不设置路径访问限制 + list_dir(path: str = ".") -> str：列出指定目录下的文件和子目录 + create_file(path: str) -> str：创建空文件 + create_dir(path: str) -> str：创建目录（含父目录） + delete(path: str) -> str：删除文件或目录 + rename(path: str, new_name: str) -> str：重命名文件或目录 + read_file(path: str, start_line: int = 0, end_line: int = 0) -> str：读取文件内容，支持按行范围读取 + write_file(path: str, content: str) -> str：写入文件内容 + edit_file(path: str, operation: str, start_line: int, end_line: int, content: str = "") -> str：编辑文件，支持add/del/modify行操作 + copy(src: str, dest: str) -> str：复制文件或目录 + move(src: str, dest: str) -> str：移动文件或目录 + upload(filename: str, content: bytes) -> str：上传文件到当前目录 + download(path: str) -> FileResponse：下载指定文件 + + + + 模块间接口调用关系 + CLI/Web界面层调用Model模块的chat()或chat_stream()接口 + Model模块调用Command模块的parse_and_execute()接口 + Command模块调用Controller模块的get_auth_mode()接口查询授权状态 + Command模块调用Model模块的request_auth()接口向用户申请授权 + Command模块的文件类命令委托File模块执行 + Model模块调用Controller模块的set_auth_mode()接口修改授权模式 + Model模块调用Controller模块的reset_auth()接口重置授权状态 + + + 配置文件为项目根目录下的config.json，参照现有结构并增加新字段 + api_base：string，默认"http://localhost:11434/v1"，LLM API基础地址 + api_key：string，默认"ollama"，LLM API密钥 + model：string，默认"llama3.2"，模型名称 + round_limit：int，默认20，多轮对话最大轮次 + cmd_timeout：int，默认60，命令执行超时时间（秒），新增字段 + auth_mode：int，默认0，初始授权模式：0=需要授权，1=自动授权，新增字段 + system_prompt：string，内置默认值，系统提示词，支持{system_name}占位符 + listen_host：string，默认"127.0.0.1"，Web模式监听地址 + listen_port：int，默认8880，Web模式监听端口 + + + 错误处理策略 + LLM API调用失败：向用户返回错误信息，但不退出程序。等待用户输入，用户可输入新消息重新调用LLM API继续会话。CLI模式在终端打印错误信息，Web模式通过SSE推送error事件在对话窗口中显示，样式同指令执行结果的显示 + 命令执行失败：错误返回格式同现有设计中指令执行信息返回的格式，但将信息部分替换为错误信息，格式为[action] [参数摘要] Error: 错误信息。命令执行失败不影响后续命令的执行 + 命令执行超时：超时时长由配置文件cmd_timeout字段控制，超时后返回Error: Command timed out after {cmd_timeout} seconds + 安全检查拦截：被黑名单拦截的命令返回Error: Command blocked due to safety concerns + 所有命令执行结果（包括失败的）统一反馈给LLM进行后续处理 + + + 安全机制 + 仅对exec_cmd命令进行安全检查，文件类命令不进行安全检查 + 黑名单模式列表仅保留：rm -rf / + 匹配规则：命令字符串中包含黑名单模式即为拦截（不区分大小写） + 当auth_mode=0时，所有命令执行前需经用户授权 + 用户可通过/y-all(CLI)或Web界面切换为auth_mode=1（自动授权） + 用户可通过/n-all(CLI)或Web界面切换为auth_mode=0（需要授权） + + + diff --git a/skills/HTMD/references/patterns.md b/skills/HTMD/references/patterns.md new file mode 100644 index 0000000..cea69c3 --- /dev/null +++ b/skills/HTMD/references/patterns.md @@ -0,0 +1,313 @@ +# HTMD 模式与示例 + +## 文档定位 + +本文件收录 HTMD 的常用组织模式、文本映射示例和完整转换样例。它用于按需提供上下文，不要求所有文档套用同一模板。标签名称和包含关系可以根据实际设计调整；示例中的 2 空格缩进只是推荐排版。 + +标签含义和动态标签选择见 [`tags.md`](tags.md)，总体内容模型见 [`schema.md`](schema.md)。 + +## 多行内容的排版建议 + +元素内部可以使用实际换行符。为便于阅读，推荐将元素内部文本比元素标签多缩进一层，但空格数量不影响语义。 + +### 流程文本 + +```htmd + + 1. 第一步描述 + 2. 第二步描述 + 3. 第三步描述 + +``` + +是否使用编号、项目符号或自然语言段落，由流程内容决定。 + +### API 结构 + +以下结构可作为 API 文档的起点；参数、返回值和错误信息按实际设计补充或删减： + +```htmd + + + method_name(params) -> return_type：方法描述 + 错误码：XXX + + + { + "param": "value" + } + + + { + "result": "value" + } + + +``` + +### 字段定义 + +```htmd +字段名：类型，默认值，描述 +``` + +字段内容复杂时，可以改用容器元素组织类型、默认值、约束和说明。 + +## 常用模式 + +### 项目规范结构 + +```htmd + + 项目简短描述 + + + 命令行接口 + /quit：退出程序 + /help：显示帮助 + + 1. 用户输入命令 + 2. 解析并执行 + 3. 返回结果 + + + + Web接口 + 用户登录 + 文件管理 + onmessage：收到消息 + + 1. 用户在Web界面输入 + 2. SSE推送结果 + 3. 前端渲染 + + + + + + 模块一描述 + 关键点1：详细说明，包括输入输出、边界条件 + 关键点2：详细说明 + + + method_name(param: type, required: bool) -> return_type：方法详细描述 + 错误码：XXX + + + { + "param": "example value" + } + + + { + "result": "value" + } + + + + + + api_base：string，默认"http://localhost:11434/v1"，API基础地址 + timeout：int，默认30，超时时间（秒），取值范围1-300 + + + + table_name：字段1(type, PK, NOT NULL)，字段2(type, FK->other_table(id))，字段3(type, UNIQUE, INDEX) + 说明：表用途 + + + + 错误场景：错误码/状态码。错误返回格式：{"error": "code", "message": "描述"} + + + 安全机制描述：包括认证方式、加密方法、权限控制等 + + +``` + +### API 定义模式 + +```htmd + + + POST /endpoint(params: {param_name: type, required: bool, description}) -> {return_field: type, description} + 错误码：400参数错误，401未授权，404未找到 + + + { + "param_name": "example value" + } + + + { + "result_field": "result value" + } + + +``` + +### 事件定义模式 + +```htmd + + event_name：事件描述。附加字段：field1(type, 说明), field2(type, 说明) + 触发条件：什么情况下触发此事件 + 处理逻辑：事件发生后如何处理 + +``` + +### 错误处理模式 + +```htmd + + 错误场景描述。错误码：XXX。返回格式：[action] [参数摘要] Error: 错误信息 + 影响范围：此错误会影响哪些操作 + 恢复方式：如何从此错误中恢复 + +``` + +### 流程定义模式 + +```htmd + + 1. 步骤一：描述，包含输入参数、输出结果、可能的时间延迟 + 2. 步骤二：描述，包含条件判断 if condition then A else B + 3. 步骤三：描述，包含异常处理 if error then handle_error() + 异常：可能的异常情况及处理方式 + +``` + +### 数据库 Schema 模式 + +```htmd + + table_name： + - id：int, PK, AUTO_INCREMENT，主键 + - name：varchar(255), NOT NULL, 名称 + - email：varchar(255), UNIQUE, INDEX, 邮箱 + - created_at：datetime, DEFAULT CURRENT_TIMESTAMP，创建时间 + - updated_at：datetime, ON UPDATE CURRENT_TIMESTAMP，更新时间 + 说明：表用途和业务规则 + 索引：idx_name(name), idx_email(email) + +``` + +## Markdown 转 HTMD 的参考模式 + +### 文档类型映射 + +| Markdown 内容 | HTMD 参考表达 | +|---|---| +| `# 标题` | `` 或语义合适的根容器 | +| `## 子标题` | ``、``、`` 或动态容器 | +| `- 列表项` | 根据上下文使用 ``、``、`` 或动态元素 | +| `1. 编号列表` | `` 中的步骤文本 | +| `**粗体**` | 通常不需要，结构本身承载语义 | +| 代码块 | 对应 API、命令、查询或代码元素的多行文本 | +| `> 引用` | `` 或其他说明元素 | +| 表格 | 多个 ``、`` 或语义合适的容器 | + +### 转换步骤示例 + +1. 识别文档对象：项目、系统、模块、接口、流程或领域对象。 +2. 找出信息层级：整体对象、主要部分和详细信息。 +3. 为每个信息单元选择核心标签或动态标签。 +4. 需要展开的对象使用容器元素，简单文本使用元素。 +5. 推荐使用 2 空格缩进增强可读性，但不把缩进当作语法条件。 +6. 检查标签闭合、文本包裹和层级归属。 +7. 保存为 `.htmd` 文件；是否保留原 Markdown 由任务需要决定。 + +## 完整转换示例 + +### 原始 Markdown + +```markdown +# 用户认证系统 + +## 概述 +一个处理用户登录注册的系统，使用JWT令牌。 + +## API端点 +- POST /login - 用户认证 +- POST /register - 用户注册 + +## 错误处理 +认证失败时返回401状态码。 +``` + +### HTMD 输出 + +```htmd + + 用户认证系统，处理用户登录注册，使用JWT令牌 + + + 认证模块，负责用户注册、登录、Token管理 + 密码使用bcrypt加密存储，加盐哈希 + JWT token包含user_id、username、exp时间戳 + access_token有效期2小时，refresh_token有效期7天 + refresh_token存储在数据库中，支持token撤销 + + + POST /login(username_or_email: str, password: str, required: true) -> {access_token: str, refresh_token: str, expires_in: int, user: {id, username, email}} + 错误码：401用户名密码错误，423账户已锁定 + + + { + "username_or_email": "user@example.com", + "password": "******" + } + + + { + "access_token": "eyJhbGciOiJIUzI1NiIs...", + "refresh_token": "eyJ...", + "expires_in": 7200, + "user": { + "id": 1, + "username": "user", + "email": "user@example.com" + } + } + + + + + POST /register(username: str, email: str, password: str, required: true) -> {user_id: int, message: str} + 错误码：409用户名或邮箱已存在，422参数验证失败 + + + { + "username": "newuser", + "email": "new@example.com", + "password": "******" + } + + + { + "user_id": 1, + "message": "注册成功" + } + + + + + + 认证失败（用户名密码错误）：错误码401。返回：{"error": "AUTH_FAILED", "message": "用户名或密码错误"}。用户操作：检查输入，重新尝试 + Token过期：错误码401。返回：{"error": "TOKEN_EXPIRED", "message": "Token已过期"}。用户操作：使用refresh_token刷新或重新登录 + 权限不足：错误码403。返回：{"error": "FORBIDDEN", "message": "权限不足"}。用户操作：联系管理员提升权限 + + + 密码加密：使用bcrypt，cost factor 12，永不明文存储 + Token安全：HTTPS传输，设置合理过期时间 + 防暴力破解：同一IP登录失败5次后锁定15分钟 + + +``` + +## 使用提示 + +- 先读取本文件中与当前任务最接近的模式，再根据实际设计删减或改写标签。 +- 不要把示例中的标签名称、层级、字段顺序或缩进当成必须遵守的模板。 +- 代码、JSON、命令和协议文本应完整保留在元素内部，不要为了统一排版破坏其内容。 +- 示例只说明结构表达方式；具体安全、权限、部署和回滚方案必须结合目标环境单独设计。 diff --git a/skills/HTMD/references/schema.md b/skills/HTMD/references/schema.md new file mode 100644 index 0000000..123f1a8 --- /dev/null +++ b/skills/HTMD/references/schema.md @@ -0,0 +1,278 @@ +# HTMD 结构语义参考 + +## 文档定位 + +本文件是 HTMD 的**语义参考**，用于帮助 Agent 根据设计对象选择更准确的标签并组织信息。它不是封闭的标签白名单，也不是需要由解析器强制执行的格式标准。 + +HTMD 的主要价值是把信息按语义分组，使大模型更容易理解上下文、层级和关系，并在相同信息量下减少重复说明。标签名称和包含关系应服务于实际设计，而不是为了满足固定模板而牺牲表达准确性。 + +本文件只补充标签的含义、选择依据和常见组织方式。除 `SKILL.md` 中明确说明的基本结构原则外，以下内容均属于建议： + +- 不要求所有文档使用相同的标签集合。 +- 不要求标签具有固定的父子层级或出现顺序。 +- 不要求使用固定缩进、换行、空格数量或字段排列。 +- 不要求每个推荐标签都出现在文档中。 +- 不因为没有使用推荐标签，就判定文档无效。 + +## 基本内容模型 + +HTMD 中的标签实例根据实际承载内容分为两类。分类关注的是信息如何组织，而不是标签名称是否预先登记。 + +### 元素 + +元素是承载文本的最小语义单元。文本、编号步骤、JSON、代码片段和自然语言说明都应放在元素的开始标签与结束标签之间。 + +```htmd +这是一个元素，直接承载文本。 + +{ + "name": "example" +} + +``` + +### 容器元素 + +容器元素用于承载一个或多个子元素，以表达模块、组成部分、关系或层级。容器本身不直接承载未被标签包裹的文本；需要标题或说明时，应使用 `` 或其他合适的元素。 + +```htmd + + 这是一个容器的说明。 + 容器中的一个关键信息。 + +``` + +### 同一标签的上下文用法 + +标签的语义应优先由实际设计决定。如果某个标签实例直接承载文本，它在该处就是元素；如果某个标签实例需要组织子标签，它在该处就是容器元素。为了避免歧义，通常应让同一文档中的同名标签保持相近的内容模型；若语义差异明显，应使用更具体的动态标签。 + +以下两种写法都可以表达模块，但第二种在需要描述多个模块属性时更适合： + +```htmd +认证模块：负责登录和令牌管理。 + + + 认证模块。 + 处理用户登录。 + 限制登录尝试次数。 + +``` + +### 结构底线 + +为了让标签化信息保持可理解性，生成 HTMD 时遵循以下底线： + +1. 每个开始标签都配有对应的结束标签。 +2. 不使用 `` 或没有内容的 ``；没有信息时省略该标签。 +3. 任意说明文字都位于某个元素内部，容器不直接放置未包裹文本。 +4. 标签名称不包含属性、空格或未转义的特殊字符。 + +这些底线用于保持基本的结构可读性，不意味着 HTMD 需要实现完整的 XML、HTML 或领域标准兼容性。 + +## 核心标签语义目录 + +下表中的标签是常见语义的快捷表达。它们是推荐选项，不是必须使用的固定词汇。若实际设计有更准确的名称，可以使用动态标签替代或补充。 + +| 标签 | 默认类型 | 适合表达的语义 | 常见内容或子元素 | 使用提示 | +|---|---|---|---|---| +| `` | 容器元素 | 项目、系统或方案的整体描述 | ``、模块、接口、流程、配置等 | 默认的项目文档根容器；其他领域可选择更准确的根名称 | +| `` | 元素 | 对对象的概括说明 | 文本 | 用于标题性说明、摘要和上下文介绍 | +| `` | 容器元素 | 前端、用户界面或客户端部分 | 模块、页面、组件、流程 | 仅在设计确实区分前端时使用 | +| `` | 容器元素 | 后端、服务端或内部实现部分 | 模块、服务、数据流、接口 | 可由 ``、`` 等动态标签替代 | +| `` | 容器元素 | 用户或系统可交互的接口集合 | CLI、Web、API、事件等 | 不限定接口协议 | +| `` | 容器元素 | 实现细节和内部组成 | 模块、函数、流程、配置 | 当文档需要区分“对外接口”和“内部实现”时使用 | +| `` | 容器元素 | 模块、组件或功能单元 | ``、``、API、动态子元素 | 通用性较强；有更具体领域概念时优先使用动态标签 | +| `` | 容器元素 | 一个 API 或 API 相关说明 | ``、``、``、错误信息 | 子元素不是固定必选项，按实际信息取舍 | +| `` | 容器元素 | 配置项集合或配置策略 | ``、环境、策略 | 可用 ``、`` 等动态标签细化 | +| `` | 容器元素 | 数据存储、数据库或数据层 | ``、``、关系 | 非数据库存储可改用 ``、`` 等标签 | +| `` | 容器元素 | 错误处理和恢复策略 | ``、重试、降级、告警 | 适合表达整体策略，不限于单个错误 | +| `` | 容器元素 | 安全、权限、合规或风险控制 | ``、策略、约束 | 可按领域改为 ``、`` 等 | +| `` | 元素 | 一个关键点、约束或事实 | 文本 | 适合短内容；复杂内容可改用容器 | +| `` | 元素 | CLI 命令或操作入口 | 命令文本 | 需要参数分组时可使用动态容器 | +| `` | 元素 | 功能、能力或函数概述 | 文本 | 需要参数、流程和异常细节时可改为容器 | +| `` | 元素 | 事件、触发器或通知 | 文本 | 需要描述事件字段和处理阶段时可使用容器形式或动态标签 | +| `` | 元素 | 步骤、流程或数据流 | 多行步骤文本 | 是否编号、采用何种列表格式由实际表达需要决定 | +| `` | 元素 | API、函数或协议定义 | 签名、参数、返回值、错误信息 | 可用自然语言或项目约定的签名格式 | +| `` | 元素 | 请求样例或输入样例 | JSON、文本或代码 | 不限定具体序列化格式 | +| `` | 元素 | 响应样例或输出样例 | JSON、文本或代码 | 需要表达错误响应时可另设 `` | +| `` | 元素 | 数据、文件或资源操作 | 操作描述 | 可表达读、写、查询、迁移等行为 | +| `` | 元素 | 单个错误场景及其处理 | 错误描述、状态、恢复方式 | 多个错误可放入错误处理容器中 | +| `` | 元素 | 配置、请求或数据字段 | 字段名、类型、默认值、说明 | 字段复杂时可使用字段容器和子元素 | +| `` | 元素 | 数据结构、表结构或模式说明 | 多行文本 | 不限于关系数据库 schema | + +## 动态标签与包含关系 + +当核心标签不能准确表达设计对象时，直接创建动态标签。动态标签的名称、类型和包含关系都可以随项目语境调整。 + +### 动态标签的选择依据 + +1. 先识别信息表达的对象：模块、角色、接口、策略、资源、状态、关系或动作。 +2. 如果核心标签已经准确表达该对象，优先使用核心标签，减少不必要的词汇变化。 +3. 如果核心标签过于宽泛或会造成误解，创建一个能直接表达领域语义的名称。 +4. 只承载一句或一组文本时，将动态标签作为元素；需要组织多个信息单元时，将其作为容器元素。 +5. 父子关系按信息的自然归属组织：子标签应解释、分解或补充父标签表达的对象。 +6. 不为了凑出固定层级而增加中间容器，也不为了省标签而把互不相关的信息合并到同一个元素中。 + +### 动态标签示例 + +以下示例只是可能的设计选择，不是预定义标签清单： + +| 设计对象 | 动态标签示例 | 可能的类型 | 可能的内容 | +|---|---|---|---| +| 工作模式 | ``、`` | 容器元素 | ``、``、`` | +| 服务内部角色 | ``、``、`` | 容器元素 | ``、``、`` | +| 基础设施资源 | ``、``、`` | 容器元素 | ``、``、`` | +| 业务策略 | ``、`` | 容器元素 | ``、``、`` | +| 领域动作 | ``、`` | 元素或容器元素 | 文本，或动作的参数、流程和错误 | +| 模块关系 | ``、`` | 元素 | 关系描述 | + +例如，同一个项目可以根据实际架构选择不同的组织方式： + +```htmd + + + + 面向浏览器的交互入口。 + + POST /login：创建会话。 + {"username": "example"} + {"session": "opaque-token"} + + + + + + 负责凭据校验和会话管理。 + + 连续失败时增加等待时间。 + + + + +``` + +如果另一个项目更适合按领域组织，也可以使用不同的父子关系： + +```htmd + + + 身份相关能力。 + 刷新短期访问令牌。 + + + + 保存用户上传的对象。 + + + +``` + +## 关系设计建议 + +### 从整体到细节 + +适合在父容器中依次放置概述、组成部分、行为和约束，但具体顺序可根据阅读目标调整： + +```htmd + + 模块负责什么。 + + 组成部分负责什么。 + 组成部分提供的能力。 + + 调用模块时发生的主要步骤。 + 模块需要遵守的安全边界。 + +``` + +### 从接口到实现 + +当文档同时描述外部接口和内部实现时，可以用容器表达边界；也可以直接按业务域组织，不必强制采用 `` / `` 两层： + +```htmd + + + 外部调用方可使用的能力。 + + GET /items：返回可见项目。 + + + + 将查询转换为存储层操作。 + 按租户标识查询项目。 + + +``` + +### 从流程到异常 + +流程和错误可以作为同级信息，也可以让错误属于具体步骤或策略。选择能使因果关系最清楚的组织方式： + +```htmd + + 校验订单、锁定库存、创建支付请求、确认订单。 + + 库存不足时释放已创建的临时资源并返回可重试状态。 + + +``` + +## 文本、代码和数据的承载 + +HTMD 不要求把每种文本转换成另一种专用格式。根据大模型理解和读者使用场景，选择最能保留语义的元素： + +- 自然语言说明放在 ``、`` 或语义更准确的元素中。 +- 编号步骤可以放在 `` 中；是否使用数字、项目符号或段落由内容决定。 +- JSON、YAML、SQL、命令和代码可以作为元素的多行文本内容。 +- 表格可以拆成多个 ``，也可以保留为文本，或根据业务语义设计动态容器。 +- 不要为了形式统一而破坏代码、JSON 或协议示例的原始结构。 +- 如果文本包含标签分隔符等特殊字符，应采用不会误解为 HTMD 标签的表示方式。 + +示例： + +```htmd + +SELECT id, name +FROM users +WHERE tenant_id = :tenant_id; + + +{ + "items": [], + "next_cursor": null +} + +``` + +## 设计时的快速决策表 + +| 问题 | 建议 | +|---|---| +| 这段信息是在描述一个事实、动作或样例吗？ | 选择元素，直接承载文本 | +| 这段信息需要拆成多个相互关联的部分吗？ | 选择容器元素，再用子元素组织 | +| 是否存在能准确表达语义的核心标签？ | 使用核心标签 | +| 核心标签是否会让读者误解对象？ | 创建更具体的动态标签 | +| 子信息是否真正属于父对象？ | 属于则嵌套，否则并列或改用关系标签 | +| 是否只是为了满足模板才增加层级？ | 不增加该层级 | +| 内容是代码或数据样例吗？ | 放在元素内部，优先保留其原始结构 | +| 是否需要固定缩进或固定标签顺序？ | 不需要；保持当前表示清晰即可 | + +## 与 `SKILL.md` 的关系 + +- `SKILL.md` 说明 HTMD 的使用场景、基本内容模型和工作流程。 +- 本文件提供更集中的标签语义索引、动态标签决策依据和组织示例。 +- 两者都不构成封闭标签集合；当实际设计需要时，应以语义准确性为优先。 +- 本文件没有对应的校验脚本，也不要求 Agent 把推荐关系当作硬性错误条件。 +- 若 `SKILL.md` 与具体项目的设计目标存在表面冲突，应保留元素/容器元素的基本可读结构，并调整标签名称和包含关系以准确表达项目语义。 + +## 输出前的语义自检 + +这不是机器校验清单，而是帮助 Agent 改善表达的思考顺序： + +1. 每个标签是否表达了可识别的对象、行为、关系或约束？ +2. 需要展开的对象是否使用了容器元素？ +3. 简单文本是否被不必要地拆成过多层级？ +4. 动态标签是否比泛化标签更准确？ +5. 父子关系是否能帮助读者理解归属和因果？ +6. 文本、代码和数据是否完整地保留在元素内部？ +7. 是否存在无内容标签、未闭合标签或容器中的裸文本？ diff --git a/skills/HTMD/references/tags.md b/skills/HTMD/references/tags.md new file mode 100644 index 0000000..82607f7 --- /dev/null +++ b/skills/HTMD/references/tags.md @@ -0,0 +1,170 @@ +# HTMD 标签语义参考 + +## 文档定位 + +本文件是 HTMD 的标签快速索引，供 Agent 在需要选择标签或设计包含关系时按需读取。标签名称、父子关系和出现顺序都是语义设计选择，不构成封闭白名单。 + +HTMD 的总体内容模型、动态标签原则和非强制格式说明见 [`schema.md`](schema.md)。本文件只提供常见标签的快捷表达；实际设计应以语义准确性为优先。 + +## 标签类型与内容模型 + +### 元素 + +元素是承载文本的最小语义单元。自然语言、编号步骤、JSON、代码片段和协议示例都可以作为元素的文本内容。 + +```htmd +元素直接承载文本内容。 + + { + "name": "example" + } + +``` + +### 容器元素 + +容器元素承载一个或多个子元素，用于表达模块、组成部分、关系或层级。容器本身不直接承载未被标签包裹的文本；需要标题或说明时，使用 `` 或其他元素。 + +```htmd + + 容器的用途说明。 + 容器中的关键事实。 + +``` + +### 动态内容模型 + +同一个标签名称的具体类型由其当前实例决定：直接承载文本时是元素，包含子标签时是容器元素。若同名标签在同一文档中承担明显不同的角色，应改用更具体的动态标签以减少歧义。 + +## 核心标签目录 + +下表中的标签是常见语义的推荐快捷表达，不是必须使用的固定词汇。实际项目可以增加动态标签，也可以用更准确的动态标签替代核心标签。 + +| 标签 | 默认类型 | 适合表达的语义 | 常见内容或子元素 | 使用提示 | +|---|---|---|---|---| +| `` | 容器元素 | 项目、系统或方案的整体描述 | ``、模块、接口、流程、配置等 | 项目文档通常使用的根容器 | +| `` | 元素 | 对对象的概括说明 | 文本 | 用于摘要、标题性说明和上下文介绍 | +| `` | 容器元素 | 前端、用户界面或客户端部分 | 模块、页面、组件、流程 | 仅在设计确实区分前端时使用 | +| `` | 容器元素 | 后端、服务端或内部实现部分 | 模块、服务、数据流、接口 | 可由 ``、`` 等动态标签替代 | +| `` | 容器元素 | 用户或系统可交互的接口集合 | CLI、Web、API、事件等 | 不限定接口协议 | +| `` | 容器元素 | 实现细节和内部组成 | 模块、函数、流程、配置 | 用于表达对外接口之外的内部设计 | +| `` | 容器元素 | 模块、组件或功能单元 | ``、``、API、动态子元素 | 有更具体领域概念时优先使用动态标签 | +| `` | 容器元素 | 一个 API 或 API 相关说明 | ``、``、``、错误信息 | 子元素按实际信息取舍，不是固定必选集合 | +| `` | 容器元素 | 配置项集合或配置策略 | ``、环境、策略 | 可用 ``、`` 细化 | +| `` | 容器元素 | 数据存储、数据库或数据层 | ``、``、关系 | 非数据库存储可改用 ``、`` | +| `` | 容器元素 | 错误处理和恢复策略 | ``、重试、降级、告警 | 适合表达整体策略 | +| `` | 容器元素 | 安全、权限、合规或风险控制 | ``、策略、约束 | 可按领域改为 ``、`` | +| `` | 元素 | 一个关键点、约束或事实 | 文本 | 复杂内容可改为容器 | +| `` | 元素 | CLI 命令或操作入口 | 命令文本 | 参数复杂时可使用动态容器 | +| `` | 元素 | 功能、能力或函数概述 | 文本 | 需要参数和异常细节时可改为容器 | +| `` | 元素 | 事件、触发器或通知 | 文本 | 事件字段复杂时可使用容器形式 | +| `` | 元素 | 步骤、流程或数据流 | 多行步骤文本 | 是否编号由内容表达需要决定 | +| `` | 元素 | API、函数或协议定义 | 签名、参数、返回值、错误信息 | 可用自然语言或项目约定的签名格式 | +| `` | 元素 | 请求样例或输入样例 | JSON、文本或代码 | 不限定序列化格式 | +| `` | 元素 | 响应样例或输出样例 | JSON、文本或代码 | 可另设 `` 表达错误响应 | +| `` | 元素 | 数据、文件或资源操作 | 操作描述 | 可表达读、写、查询、迁移等行为 | +| `` | 元素 | 单个错误场景及其处理 | 错误描述、状态、恢复方式 | 多个错误可放入错误处理容器 | +| `` | 元素 | 配置、请求或数据字段 | 字段名、类型、默认值、说明 | 字段复杂时可改为字段容器 | +| `` | 元素 | 数据结构、表结构或模式说明 | 多行文本 | 不限于关系数据库 | + +## 根标签与结构关系 + +在项目规范场景中，通常以 `` 作为唯一根容器，并在其下按实际设计组织接口、实现、模块、配置和关系。下表是推荐关系，不是层级白名单： + +| 标签 | 默认类型 | 推荐内容或子标签 | +|---|---|---| +| `` | 容器元素 | ``、``、``、``、``、``、``、``、`` | +| `` | 容器元素 | `` 或动态界面容器 | +| `` | 容器元素 | ``、动态服务容器或数据层 | +| `` | 容器元素 | 动态接口容器、``、`` | +| `` | 容器元素 | ``、``、``、``、`` 或动态实现容器 | +| `` | 容器元素 | ``、``、``、`` 或动态子元素 | +| `` | 容器元素 | `` 或动态配置元素 | +| `` | 容器元素 | ``、`` 或动态数据库元素 | +| `` | 容器元素 | `` 或动态错误元素 | +| `` | 容器元素 | `` 或动态安全元素 | + +如果文档对象不是项目，例如单独描述一个服务、协议或领域模型，可以选择更准确的根容器；关键是保持根对象唯一且语义明确。 + +## 动态标签与包含关系 + +### 选择动态标签的依据 + +1. 先识别信息表达的对象：模块、角色、接口、策略、资源、状态、关系或动作。 +2. 核心标签已经准确表达对象时，优先使用核心标签，减少不必要的词汇变化。 +3. 核心标签过于宽泛或会造成误解时，创建能直接表达领域语义的名称。 +4. 只承载一组文本时，将动态标签作为元素；需要组织多个信息单元时，将其作为容器元素。 +5. 子标签应解释、分解或补充父标签表达的对象，不要为了凑固定层级增加中间容器。 +6. 互不相关的信息不要合并到同一个元素中；如果关系本身是重点，可以使用 ``、`` 等动态关系元素。 + +### 命名和结构建议 + +- 如果希望被 XML-like 工具读取，标签名称应避免空格、引号、属性和未转义的特殊字符；英文小写和连字符通常更易读，例如 ``。 +- 动态容器可以包含核心元素、核心容器、动态元素和动态容器；具体包含关系由实际设计决定。 +- 动态元素只直接承载文本；动态容器通过子元素组织信息。需要同时表达标题和详细内容时，使用 `` 加其他子元素。 +- 核心标签在语义匹配时优先使用；不能准确表达时再创建动态标签，不要复用核心标签表达完全不同的语义。 +- 标签名、父子关系、出现顺序和推荐标签集合都可以随设计调整。 + +### 动态标签示例 + +以下名称只是可能的设计选择，不是预定义清单： + +| 设计对象 | 动态标签示例 | 可能的类型 | 可能的内容 | +|---|---|---|---| +| 工作模式 | ``、`` | 容器元素 | ``、``、`` | +| 服务内部角色 | ``、``、`` | 容器元素 | ``、``、`` | +| 基础设施资源 | ``、``、`` | 容器元素 | ``、``、`` | +| 业务策略 | ``、`` | 容器元素 | ``、``、`` | +| 领域动作 | ``、`` | 元素或容器元素 | 文本，或参数、流程和错误 | +| 模块关系 | ``、`` | 元素 | 关系描述 | + +### 动态接口标签 + +``、``、``、`` 等只是动态接口标签的示例。项目可以使用 ``、`` 或其他更准确的接口容器名称。 + +| 标签 | 默认类型 | 描述 | 推荐内容或子标签 | +|---|---|---|---| +| `` | 容器元素 | 接口定义的组织容器 | 动态接口容器元素 | +| `` | 容器元素 | 示例 Web 接口 | ``、``、``、`` 或动态接口元素 | +| `` | 容器元素 | 示例 CLI 接口 | ``、``、`` 或动态接口元素 | +| `` | 元素 | CLI 命令定义 | 文本，例如 `/command：描述` | +| `` | 元素 | 功能或能力 | 文本内容 | +| `` | 元素 | 逐步工作流程 | 多行步骤文本 | +| `` | 元素 | 事件驱动系统中的事件 | 文本内容 | + +## 详情标签 + +| 标签 | 默认类型 | 描述 | 内容形式 | +|---|---|---|---| +| `` | 元素 | 关键点或要点 | 文本内容 | +| `` | 容器元素 | API 端点定义 | 通常包含 ``、``、`` | +| `` | 元素 | API 定义和参数说明 | HTTP 方法、路径、参数、返回类型、错误码等文本 | +| `` | 元素 | 请求样例 | JSON 或其他约定格式的多行文本 | +| `` | 元素 | 响应样例 | JSON 或其他约定格式的多行文本 | +| `` | 元素 | 数据库、文件或资源操作 | `name(params) -> return_type` 或自然语言 | +| `` | 元素 | 模块函数或功能 | 文本内容 | +| `` | 元素 | 错误处理行为 | 场景、状态、影响和恢复方式 | +| `` | 元素 | 配置字段定义 | 字段名、类型、默认值和描述 | +| `` | 元素 | 数据模式定义 | 表结构、字段约束或其他多行模式文本 | + +## 标签使用规则 + +1. 文本标签和动态元素使用成对标签，文本位于开始标签与结束标签之间。 +2. 容器标签承载子元素，不直接包含未包裹的文本。 +3. 空元素不属于 HTMD：不使用 ``，也不输出没有内容的 ``。 +4. 每个开始标签都有对应的结束标签，不依赖 HTML 中可省略结束标签的写法。 +5. HTMD 标签不使用属性；需要表达元数据时，将其放入元素文本或子元素。 +6. 推荐每层使用 2 个空格帮助读者识别层级，但缩进、换行和空格数量不是语法要求。 + +## 内容覆盖建议 + +生产级设计规范通常应根据任务需要覆盖以下信息。它们是内容完整性建议，不要求每份文档机械填满所有标签： + +| 信息类型 | 推荐承载 | 建议覆盖内容 | +|---|---|---| +| 项目结构 | ``、`` 或动态模块容器 | 目录结构、模块职责、关键文件用途 | +| API 定义 | ``、``、``、`` | 参数、类型、必填性、返回值、错误码和样例 | +| 数据流和流程 | `` 或动态流程容器 | 步骤、输入输出、条件分支和异常流程 | +| 数据库或存储 | ``、``、`` | 字段、类型、约束、索引、关系和用途 | +| 配置项 | ``、`` | 名称、类型、默认值、范围和用途 | +| 错误处理 | ``、`` | 场景、状态、响应格式和恢复方式 | -- Gitee