跳到主要内容

DevStream 接口规范

最新版本：1.0.0

发布日期：2025年3月7日

编辑：

DevStream 接口规范定义面向人工智能应用的工作流标准接口格式，目标是为人、智能和程序提供统一的工作流理解和运行机制。 他们在本规范中统称为用户。 工作流接口通过一个约定的目录结构和目录中的文件进行定义。

1. 工作流定义​

每个工作流接口由一个YAML格式的文本文件完整定义，称为工作流定义。 工作流定义固定使用文件名 interface.yml，其所在目录称为工作流定义目录。 该文件描述工作流的功能、结构化参数等信息和运行所需的元数据。

1.1. 工作流属性​

在工作流定义中，通过工作流属性声明工作流的功能和行为。 每个工作流属性是一个 YAML 对象。 工作流属性名对应 YAML 对象中的键（key）。 本节按属性名列出并规定其值（value）的格式。

1.1.1. description（必选）​

工作流的简短描述，适用于用户快速了解工作流的功能。 在工作流列表或聊天窗口的提示中，通常展示该属性。 本属性值是一个字符串。

示例：

description: Say hello to the world!

1.1.2. help（可选）​

工作流的帮助文档，支持Markdown格式。 运行工作流时通过 --help 参数输出帮助文档内容（取系统默认语言）。 本属性值是一个子对象列表，其中每个子对象的键是语言代码，值是帮助文档的文件路径。 语言代码遵照ISO 639-1；文件路径按相对于工作流定义目录进行解析。 工作流参数 --help.<lang> 输出指定语言代码 <lang> 对应的帮助文档；如果没有匹配的语言代码，默认显示列表第一个。

示例：

help:
  - en: README.md
  - zh: README.zh.md

对应工作流 <workflow> 运行时：

/<workflow> --help  # 默认显示第一个帮助文档，即 README.md
/<workflow> --help.en  # 显示 README.md
/<workflow> --help.zh  # 显示 README.zh.md
/<workflow> --help.fr  # 不显示

1.1.3. runtime（必选）​

工作流运行环境的元数据，属性值是一个 YAML 对象。 该对象包含一个以 id 为键的必选子对象，其值是一个字符串。 该字符串声明使用哪个系统运行当前工作流，应为 DevStream 支持的某个运行时系统的唯一标识。

示例：

runtime:
  id: shell-python

DevStream 实现的运行时系统 shell-python 支持本地运行 Python 独立脚本。 运行时所需声明的其他对象参见具体运行时系统的要求，不在本规范中约定。 这些对象都应作为 runtime 属性值的子对象。

1.2. 工作流参数​

在工作流定义中，通过工作流参数声明工作流所需的输入信息。 工作流参数是一个以 parameters 为键的可选 YAML 对象，其值可包含如下子对象。

1.2.1. __input__（可选）​

用户的非结构化输入是否必选，其值是 required 或 optional。 非结构化输入指自然语言描述的用户需求。 用户运行工作流时可同时输入所需的文字表述。 相应的输入值在工作流运行时可由内置变量 __input__ 取得。

示例：

parameters:
  __input__: required

表明工作流必须辅以文字输入。例如，用户在聊天窗口输入 /slack.post LGTM to PR #2428，DevStream 会在工作流 /slack.post 运行时将 LGTM to PR #2428 赋值给内置变量 __input__。

2. 命名空间​

DevStream 采用文件目录组织工作流命名空间。 工作流定义存储于对应的目录下。 指定根目录下的目录树结构映射为一个工作流命名空间。

2.1. 名字路径​

目录路径相对于根目录表示，遵循 POSIX 风格，即使用正斜杠 / 作为路径分隔符。 工作流路径以正斜杠 / 起始，采用半角点号 . 作为分隔符，各路径组件与其定义目录路径一一对应。 工作流路径也称为工作流名称。

示例：

工作流 /feature.add 的定义位于 /feature/add/ 目录下；目录 /feature/remove/ 下定义的工作流名称是 /feature.remove。这两个工作流的目录树结构如下。

feature
├── add
│   └── interface.yml
└── remove
    └── interface.yml

2.2. 命名规范​

单个路径组件名字应遵循以下规范：

  • 仅使用字母、数字、下划线（_）和连字符（-）。
  • 不使用空格和特殊字符。
  • 最大长度255个字符。

合法名字的正则表达式为：^[A-Za-z0-9_-]{1,255}$。

2.3. 路径可见性​

为方便用户定制和扩展工作流，DevStream 设置多个命名空间，相互按优先级覆盖。 对于包含相同工作流名称的两个命名空间，高优先级命名空间中对应的目录路径对用户可见，即高优先级命名空间中的同名工作流会被用户运行。

2.3.1. 命名空间组织​

DevStream 设置两个默认命名空间，以名为 sys（系统）和 comm（社区）的目录为根目录，分别定义系统自带的工作流和社区贡献的工作流。 sys 命名空间的优先级高于 comm。

2.3.2. 自定义命名空间​

DevStream 保留一个名为 usr 的目录，存放用户自定义的命名空间。 用户自定义命名空间的根目录应置于 usr 目录下。 用户自定义命名空间需在 usr 目录下的 config.yml 文件中注册，否则对用户不可见。 config.yml 包含一个以 namespaces 为键、以字符串列表为值的 YAML 对象，称为命名空间注册表。 写入其中的自定义命名空间对用户可见，按列表顺序定义优先级由高到低。

示例：

namespaces: 
  - team
  - department

以上 config.yml 文件注册了两个命名空间 team（团队）和 department（部门），且前者的优先级高于后者。 如果团队和部门都定义了工作流 /commit，则当前用户运行 /commit 会调用 team 命名空间下的对应工作流。

总结起来，各个命名空间的优先级顺序为：

  • 所有注册的自定义命名空间
  • sys
  • comm