create-import-module

创建导入模块

请先加载规则。 在读取、编辑或编写任何 .plain 文件之前，调用 load-plain-reference 技能，并阅读其指引的规则文件。仅当 load-plain-reference 已在本次对话中运行时，才可跳过此步骤。

什么是导入模块

导入模块是一个位于 template/ 目录中的 .plain 文件，且只包含 ***definitions***、***implementation reqs*** 和／或 ***test reqs***。它不得包含 ***functional specs***，且其 frontmatter 中不得使用 requires。其他模块通过其 YAML frontmatter 中的 import 字段引入其内容，从而使用其中的定义和需求。

导入模块适用于：

• 在多个模块间共享概念定义
• 提供通用实现需求（例如技术栈、编码标准）
• 提供通用测试需求
• 创建可复用的基础结构（模板）

如果模块需要包含功能规格（即描述软件应如何运行），它就不是导入模块——请参阅 create-requires-module 技能。

工作流

1. 确定此模块应提供哪些共享内容——其他模块需要哪些定义、实现需求或测试需求？
2. 在 template/ 目录中创建 .plain 文件并添加 YAML frontmatter。使用 required_concepts 声明导入模块必须定义的概念。可以选择 import 其他模板以分层复用，但不得使用 requires。
3. 添加共享内容——定义、实现需求和／或测试需求。
4. 不要添加 ***functional specs***——导入模块不得包含功能规格。
5. 验证概念是否可用——确保所有引用的 :Concepts: 都已在此模块中定义、由其自身导入的模块提供、通过 required_concepts 声明，或属于预定义概念。

格式

import 字段是 YAML frontmatter 中的模块路径列表：

---
import:
  - base_template
required_concepts: [":AppName:"]
description: Shared API definitions and reqs
---

***definitions***

- :ApiClient: is the HTTP client used to communicate with external services.

- :ApiResponse: is the response returned by :ApiClient:.

***implementation reqs***

- :Implementation: should handle HTTP errors by raising appropriate exceptions.

- :ApiClient: should support configurable timeouts.

***test reqs***

- :ConformanceTests: should mock all external HTTP calls made by :ApiClient:.

默认导入目录为 template/——导入路径中无需包含 template/ 前缀。.plain 扩展名也可省略。请注意，这里没有 ***functional specs***——导入模块不得包含这些内容。

满足必需概念

如果导入的模板声明了 required_concepts，导入该模板的模块必须在自己的 ***definitions*** 部分中定义这些概念：

---
import:
  - auth_template
---

> auth_template declares required_concepts: [":AuthSchema:", ":AuthApiSpec:"]
> So this module must define them:

***definitions***

- :AuthSchema: is the JSON schema describing the authentication data structure.

- :AuthApiSpec: is the OpenAPI specification for the external service's auth endpoint.

Import 与 Requires

方面	import	requires
引入定义	是	否（仅引入 exported_concepts）
引入实现需求	是	否
引入测试需求	是	否
引入功能规格	否	是（作为前置需求，并递归传递）
复制生成的代码	否	是（累积整个祖先链）
典型用途	模板、共享定义	将模块接入构建链

验证清单

• 模块文件位于 template/ 目录中
• 模块不包含 ***functional specs***
• 模块的 frontmatter 中不使用 requires
• 至少包含以下一项：定义、实现需求或测试需求
• 此模块使用的任何导入模块所声明的 required_concepts 均已满足
• 对此处引用但未定义的概念声明了 required_concepts
• 此模块导入的内容与本地定义之间没有概念名称冲突
• YAML frontmatter 已在 --- 标记之间正确格式化