@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/src/openai/openai.ts

@@ -0,0 +1,510 @@
+import type { ClientOptions } from "openai"
+import { OpenAI } from "openai"
+import type { Stream } from "openai/streaming"
+import { Agent, setGlobalDispatcher } from "undici"
+
+import type { LoggerFriendly, LoggerFriendlyOptions } from "#Source/log/index.ts"
+import type { WithAbortSignal } from "#Source/abort/index.ts"
+import type { Either } from "#Source/result/index.ts"
+
+import { Logger } from "#Source/log/index.ts"
+import * as Aio from "#Source/aio/index.ts"
+import { controllerFromEitherType } from "#Source/result/index.ts"
+import { Tube } from "#Source/tube/index.ts"
+import { scheduleMacroTask, streamConsumeInMacroTask, streamTransformInMacroTask } from "#Source/basic/index.ts"
+
+export { OpenAI } from "openai"
+export { Stream } from "openai/streaming"
+
+export interface WithOpenai {
+  openai: Openai
+}
+
+export interface OriginalChatCompletionOptions
+  extends Omit<OpenAI.Chat.ChatCompletionCreateParams, never>, WithAbortSignal {
+}
+export type OriginalChatCompletionResult = OpenAI.Chat.ChatCompletion
+export type OriginalChatCompletionChunkResult = OpenAI.Chat.Completions.ChatCompletionChunk
+
+export interface CustomChatCompletionOptions extends OriginalChatCompletionOptions {
+  /**
+   * In milliseconds.
+   */
+  timeout?: number | undefined
+}
+export interface CustomChatCompletionNonStreamingLeft {
+  code: "NO_CHOICE" | "TOO_LONG" | "FILTERED" | "REFUSED" | "EMPTY" | "UNKNOWN"
+}
+export interface CustomChatCompletionNonStreamingRight {
+  content: string
+  token: number
+}
+export type CustomChatCompletionNonStreamingResult
+  = Either<CustomChatCompletionNonStreamingLeft, CustomChatCompletionNonStreamingRight>
+
+export interface CustomChatCompletionStreamingLeft {
+  code: never
+}
+export interface Completion {
+  content: Aio.TextContent
+  token: Aio.NumberContent
+}
+export interface CustomChatCompletionStreamingRight {
+  completionTube: Tube<Completion>
+}
+export type CustomChatCompletionStreamingResult =
+  Either<CustomChatCompletionStreamingLeft, CustomChatCompletionStreamingRight>
+
+export interface OriginalEmbeddingOptions
+  extends OpenAI.Embeddings.EmbeddingCreateParams, WithAbortSignal {
+}
+export type OriginalEmbeddingResult = OpenAI.Embeddings.CreateEmbeddingResponse
+
+export interface CustomEmbeddingOptions extends WithAbortSignal {
+  input: string
+  model?: OpenAI.Embeddings.EmbeddingCreateParams["model"] | undefined
+  dimensions?: OpenAI.Embeddings.EmbeddingCreateParams["dimensions"] | undefined
+}
+export interface CustomEmbeddingResultLeft {
+  code: "NO_EMBEDDING" | "MODEL_MISMATCH" | "UNKNOWN"
+}
+export interface CustomEmbeddingResultRight {
+  embedding: number[]
+  usage: {
+    promptTokens: number
+    totalTokens: number
+  }
+}
+export type CustomEmbeddingResult =
+  Either<CustomEmbeddingResultLeft, CustomEmbeddingResultRight>
+
+export type CustomSpeechOptions = Omit<OpenAI.Audio.SpeechCreateParams, "input" | "model" | "voice" | "response_format"> & {
+  input: string
+}
+
+export interface OpenaiOptions extends LoggerFriendlyOptions {
+  apiKey: Exclude<ClientOptions["apiKey"], undefined | null>
+  baseUrl: Exclude<ClientOptions["baseURL"], undefined | null>
+  /**
+   * In milliseconds.
+   *
+   * @default 5 * 60 * 1000
+   */
+  timeout?: ClientOptions["timeout"] | undefined
+}
+interface ResolvedOpenaiOptions {
+  apiKey: Exclude<ClientOptions["apiKey"], undefined | null>
+  baseUrl: Exclude<ClientOptions["baseURL"], undefined | null>
+  timeout: Exclude<ClientOptions["timeout"], undefined | null>
+}
+export class Openai implements LoggerFriendly {
+  protected options: ResolvedOpenaiOptions
+
+  readonly logger: Logger
+  protected openai: OpenAI
+
+  constructor(options: OpenaiOptions) {
+    this.options = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      timeout: options.timeout ?? 5 * 60 * 1_000,
+    }
+
+    this.logger = Logger.fromOptions(options).setDefaultName("Openai")
+    this.openai = new OpenAI({
+      baseURL: this.options.baseUrl,
+      // NOTE: 若服务方证书出现问题可暂时开启这个选项，问题解决后应该第一时间关闭。
+      // fetch: this.customFetchThatIgnoreTheCAs,
+      timeout: this.options.timeout,
+      apiKey: this.options.apiKey,
+    })
+  }
+
+  protected async customFetchThatIgnoreTheCAs(
+    url: string, init?: RequestInit
+  ): Promise<Response> {
+    setGlobalDispatcher(new Agent({ connect: { rejectUnauthorized: false } }))
+
+    const response = await fetch(url, init)
+    if (response.ok === false) {
+      throw new Error(`Request failed with status ${response.status}`)
+    }
+
+    return response
+  }
+
+  getBaseUrl(): string {
+    return this.openai.baseURL
+  }
+
+  /**
+   * 原始 chatCompletion 方法的包装，但将其固定为非流式且不自动重试。
+   */
+  async originalChatCompletionNonStreaming(
+    options: OriginalChatCompletionOptions,
+  ): Promise<OriginalChatCompletionResult> {
+    try {
+      const { abortSignal, ...restOptions } = options
+      const response = await this.openai.chat.completions.create({
+        ...restOptions,
+        stream: false,
+      }, {
+        maxRetries: 0,
+        signal: abortSignal,
+      })
+      return response
+    }
+    catch (exception) {
+      this.logger.error("Error creating chat completion: ", exception)
+      throw exception
+    }
+  }
+
+  /**
+   * 原始 chatCompletion 方法的包装，但将其固定为流式且不自动重试。
+   */
+  async originalChatCompletionStreaming(
+    options: OriginalChatCompletionOptions,
+  ): Promise<Stream<OriginalChatCompletionChunkResult>> {
+    try {
+      const { abortSignal, ...restOptions } = options
+      const response = await this.openai.chat.completions.create({
+        ...restOptions,
+        stream: true,
+      }, {
+        maxRetries: 0,
+        signal: abortSignal,
+      })
+      return response
+    }
+    catch (exception) {
+      this.logger.error("Error creating chat completion: ", exception)
+      throw exception
+    }
+  }
+
+  /**
+   * 此方法不会自动重试，调用方需要通过错误信息自行处理。
+   *
+   * {@link https://platform.openai.com/docs/api-reference/chat | Chat - OpenAI API}
+   */
+  async customChatCompletionNonStreaming(
+    options: CustomChatCompletionOptions,
+  ): Promise<CustomChatCompletionNonStreamingResult> {
+    const controller = controllerFromEitherType<CustomChatCompletionNonStreamingResult>()
+    try {
+      const { abortSignal, ...restOptions } = options
+      const response = await this.openai.chat.completions.create({
+        ...restOptions,
+        stream: false,
+      }, {
+        maxRetries: 0,
+        signal: abortSignal,
+      })
+      const choice = response.choices[0]
+      if (choice === undefined) {
+        this.logger.error("Chat completion is empty.")
+        return await controller.returnLeft({ code: "NO_CHOICE" })
+      }
+
+      const finishReason = choice.finish_reason
+      if (finishReason === "length") {
+        this.logger.error("Chat completion is too long.")
+        return await controller.returnLeft({ code: "TOO_LONG" })
+      }
+      if (finishReason === "content_filter") {
+        this.logger.error("Chat completion is filtered.")
+        return await controller.returnLeft({ code: "FILTERED" })
+      }
+
+      const refusal = choice.message.refusal
+      if (refusal !== null && refusal !== undefined) {
+        this.logger.error(`Chat completion is refused: ${refusal}`)
+        return await controller.returnLeft({ code: "REFUSED" })
+      }
+      const content = choice.message.content
+      if (content === null) {
+        this.logger.error("Chat completion is empty.")
+        return await controller.returnLeft({ code: "EMPTY" })
+      }
+
+      return await controller.returnRight({
+        content,
+        // TODO: count the tokens
+        token: 0,
+      })
+    }
+    catch (exception) {
+      this.logger.error("Error creating chat completion: ", exception)
+      return await controller.returnLeft({ code: "UNKNOWN" })
+    }
+  }
+
+  async customChatCompletionStreaming(
+    options: CustomChatCompletionOptions,
+  ): Promise<CustomChatCompletionStreamingResult> {
+    const controller = controllerFromEitherType<CustomChatCompletionStreamingResult>()
+
+    const {
+      timeout = this.options.timeout,
+      abortSignal,
+    } = options
+    const openaiClient = this.openai
+    const logger = this.logger
+
+    const completionTube = new Tube<Completion>({
+      historyCount: Infinity,
+      replayHistory: true
+    })
+
+    const start = async (): Promise<void> => {
+      const { abortSignal: _, ...restOptions } = options
+      try {
+        // Pass the AbortSignal to the OpenAI request to support aborting
+        logger.log("Starting chat completion streaming.")
+        const response = await openaiClient.chat.completions.create(
+          {
+            ...restOptions,
+            stream: true,
+          },
+          {
+            timeout,
+            maxRetries: 0,
+            signal: abortSignal, // Include the abort signal in the request options
+          },
+        )
+        logger.log("Chat completion streaming started.")
+
+        // NOTE: 以下将 response 转换成 ReadableStream
+        const readableStream = streamTransformInMacroTask<Uint8Array, OriginalChatCompletionChunkResult>({
+          reader: response.toReadableStream().getReader(),
+          onChunk: (chunk, controller) => {
+            if (abortSignal !== undefined && abortSignal.aborted) {
+              logger.log("Original chat completion api's stream aborted by invoker.")
+              const error = new Error("Original chat completion api's stream aborted by invoker.")
+              controller.error(error)
+              return
+            }
+            if (chunk.done) {
+              logger.log("Original chat completion api's stream ended.")
+              controller.close()
+              return
+            }
+            const textDecoder = new TextDecoder()
+            const decoded = textDecoder.decode(chunk.value)
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const parsed = JSON.parse(decoded) as OriginalChatCompletionChunkResult
+            // logger.log("Original chat completion api's stream chunk:", JSON.stringify(parsed))
+            controller.enqueue(parsed)
+            return
+          },
+          onError: (error) => {
+            logger.error("Error reading original chat completion api's stream:", error)
+          },
+        })
+
+        const latestCompletion: Completion = {
+          content: {
+            deltaList: [],
+            total: "",
+          },
+          token: {
+            deltaList: [],
+            total: 0,
+          },
+        }
+
+        streamConsumeInMacroTask({
+          readableStream,
+          onValue: async (chunk) => {
+            // If the signal is aborted, break and stop the stream
+            if (abortSignal !== undefined && abortSignal.aborted) {
+              throw new Error("Stream aborted by abort signal")
+            }
+            const choice = chunk.choices[0]
+            if (choice === undefined) {
+              // NOTE: sometimes there will be no choice in the chunk, just skip the chunk
+              // Example chunk:
+              // {
+              //   "id": "chatcmpl-hTMAcJUVRpO5Etj64tdowhgpQalcP",
+              //   "object": "chat.completion.chunk",
+              //   "created": 1734481734,
+              //   "model": "gpt-4o-mini",
+              //   "choices": [],
+              //   "usage": {
+              //     "prompt_tokens": 2345,
+              //     "completion_tokens": 90,
+              //     "total_tokens": 2435,
+              //     "prompt_tokens_details": {
+              //       "cached_tokens": 0,
+              //       "audio_tokens": 0
+              //     },
+              //     "completion_tokens_details": {
+              //       "audio_tokens": 0
+              //     }
+              //   }
+              // }
+              return
+            }
+
+            const finishReason = choice.finish_reason
+            if (finishReason === "stop") {
+              // the model hit a natural stop point or a provided stop sequence, do nothing
+            }
+            if (finishReason === "length") {
+              // the maximum number of tokens specified in the request was reached
+              logger.error("Chat completion is too long.")
+            }
+            if (finishReason === "content_filter") {
+              logger.error("Chat completion is filtered.")
+              throw new Error("Chat completion is filtered.")
+            }
+
+            const refusal = choice.delta.refusal
+            if (refusal !== null && refusal !== undefined) {
+              logger.error(`Chat completion is refused: ${refusal}`)
+              throw new Error(`Chat completion is refused: ${refusal}`)
+            }
+
+            const deltaContent = choice.delta.content
+            if (deltaContent !== null && deltaContent !== undefined) {
+              latestCompletion.content = Aio.applyDeltaToTextContent(latestCompletion.content, {
+                type: "append",
+                text: deltaContent,
+              })
+              latestCompletion.token = Aio.applyDeltaToNumberContent(latestCompletion.token, {
+                type: "append",
+                value: 0,
+              })
+              await completionTube.pushData(structuredClone(latestCompletion))
+            }
+          },
+          onDone: async () => {
+            await completionTube.end()
+          },
+          onError: async (error) => {
+            await completionTube.pushError(error)
+          },
+        })
+      }
+      catch (exception) {
+        if (abortSignal !== undefined && abortSignal.aborted) {
+          logger.log("Original chat completion api's stream aborted by invoker.")
+          const error = new Error("Original chat completion api's stream aborted by invoker.")
+          await completionTube.pushError(error)
+        }
+        else {
+          logger.error("Error starting chat completion streaming: ", exception)
+          const error = new Error(`Error starting chat completion streaming, ${String(exception)}`)
+          await completionTube.pushError(error)
+        }
+      }
+    }
+    scheduleMacroTask({
+      task: async () => {
+        await start()
+      },
+    })
+
+    return await controller.returnRight({
+      completionTube,
+    })
+  }
+
+  /**
+   * 原始 embedding 方法的包装，将其最大重试次数固定为 0。
+   */
+  async originalEmbedding(
+    options: OriginalEmbeddingOptions
+  ): Promise<OriginalEmbeddingResult> {
+    const { abortSignal, ...restOptions } = options
+    try {
+      const response = await this.openai.embeddings.create({
+        ...restOptions,
+      }, {
+        maxRetries: 0,
+        signal: abortSignal,
+      })
+      return response
+    }
+    catch (exception) {
+      this.logger.error("Error creating embedding: ", exception)
+      throw exception
+    }
+  }
+
+  /**
+   * {@link https://platform.openai.com/docs/api-reference/embeddings | Embeddings - OpenAI API}
+   */
+  async customEmbedding(
+    options: CustomEmbeddingOptions
+  ): Promise<CustomEmbeddingResult> {
+    const controller = controllerFromEitherType<CustomEmbeddingResult>()
+    const logger = this.logger
+    try {
+      const {
+        abortSignal,
+        input,
+        model = "text-embedding-3-large",
+        // IMPORTANT: the number of dimensions should be 1536 currently, ask @kongxiangyan for more information.
+        dimensions = 1_536,
+      } = options
+      logger.log(`Creating embedding with model: ${model}, dimensions: ${dimensions}, input: ${input}`)
+      const response = await this.openai.embeddings.create({
+        input,
+        model,
+        dimensions,
+      }, {
+        maxRetries: 0,
+        signal: abortSignal,
+      })
+      logger.log("Get embedding response.")
+      // logger.log("Embedding response: ", JSON.stringify(response, null, 2))
+      if (response.data.length === 0) {
+        logger.error("Embedding is empty.")
+        return await controller.returnLeft({ code: "NO_EMBEDDING" })
+      }
+      if (response.model !== model) {
+        logger.error(`Model mismatch: ${response.model} !== ${model}`)
+        return await controller.returnLeft({ code: "MODEL_MISMATCH" })
+      }
+
+      const embedding = response.data[0]!.embedding
+      const promptTokens = response.usage.prompt_tokens
+      const totalTokens = response.usage.total_tokens
+      return await controller.returnRight({
+        embedding,
+        usage: {
+          promptTokens,
+          totalTokens,
+        },
+      })
+    }
+    catch (exception) {
+      logger.error("Error creating embedding: ", exception)
+      return await controller.returnLeft({ code: "UNKNOWN" })
+    }
+  }
+
+  /**
+   * {@link https://platform.openai.com/docs/api-reference/audio/createSpeech | Audio - OpenAI API}
+   */
+  async customSpeech(options: CustomSpeechOptions, stream?: boolean): Promise<Buffer> {
+    try {
+      const response = await this.openai.audio.speech.create({
+        ...options,
+        model: "tts-1",
+        voice: "alloy",
+        response_format: "opus",
+      }, {
+        stream: stream ?? false,
+      })
+      const buffer = Buffer.from(await response.arrayBuffer())
+      return buffer
+    }
+    catch (exception) {
+      this.logger.error("Error creating speech: ", exception)
+      throw exception
+    }
+  }
+}

package/src/orchestration/README.md

@@ -0,0 +1,91 @@
+# Orchestration
+
+## Description
+
+Orchestration 模块提供围绕执行单元编排（orchestration）的基础建模能力，用于把多个执行单元之间的创建、组织、调度、分派、等待、放行、推进、收束以及整体协作关系表达为稳定且可复用的公共语义。
+
+它关注的不是某个具体框架、某个具体队列系统或某个具体工作流引擎的宿主接口，而是“多个执行单元如何被组织为可理解、可组合、可控制、可持续演化的编排结构”这一更一般的问题。因此，这个模块不应被理解为仅仅承载互斥锁、信号量或栅栏的协调原语集合；这些内容只是当前实现中更基础的一层，而不是 Orchestration 这个词所指向的全部问题域。
+
+## For Understanding
+
+理解 Orchestration 模块时，应先把它看作“执行单元组织关系”的建模层，而不是一组彼此孤立的小工具。它要解决的问题，不只是多个异步流程怎样竞争资源、怎样等待同步点，也包括执行单元该如何被表达、如何被组合成更大的结构、流程阶段该如何被推进，以及这些结构之间应该暴露什么样的稳定公共语义。
+
+因此，Orchestration 更适合被理解为一个分层的问题域：较底层是 coordination，用于表达进入控制、等待约束、同步点和资源占用；在其之上还可以有 dispatching，用于表达一组候选执行目标如何被选择、如何按上下文形成选择视图，以及反馈如何影响后续分派；再往上则可以逐步生长出更接近编排结构本身的能力，用于表达单个执行单元、执行单元之间的关系、阶段推进、依赖收敛、生命周期以及整体执行边界。未来这些能力的形态可能会落在 task、job、workflow 或其它更合适的抽象上，但 coordination 与 dispatching 都只是这些能力可复用的基础层，不等同于整个 orchestration 模块。
+
+理解这个模块时，还应守住几条边界原则：
+
+- Orchestration 模块表达的是编排语义与协调语义，但不应直接承担某个业务系统专属的流程定义语言、运营规则或领域状态机。
+- 它可以吸收一切稳定且通用的编排概念，但这些概念应以模型形式出现，而不是某个具体平台配置格式、DSL 或产品术语的直接翻版。
+- coordination 适合表达进程内、运行时内的基础协作约束；更高层的编排能力即使依赖这些约束，也不应把自己退化成底层锁语义的别名。
+- dispatching 适合表达一组候选目标之间的运行时分派、反馈驱动选择与局部选择视图，但不应直接退化成只面向某类网络节点的负载均衡器别名。
+- 它可以为重试、取消、阶段推进、依赖关系或执行计划等语义提供抽象空间，但不应把监控、持久化、分布式共识、租约续期或平台运维策略直接混入核心公共 API。
+
+## For Using
+
+当你希望把一组执行动作组织成清楚、可维护、可组合的编排结构，而不是在业务代码中反复拼接 `Promise`、计数器、布尔状态、临时队列和零散流程控制逻辑时，可以使用 Orchestration 模块。
+
+从使用角度看，当前模块中的能力大致可以分为三类：
+
+- 底层协调能力：用于表达互斥进入、限量并发、阶段会合、闭锁等待、资源占用句柄以及超时和中止等等待约束。
+- 分派能力：用于表达多个候选执行目标之间如何被选择、如何基于调用上下文形成可复用的 selector，以及失败或恢复反馈如何影响后续选择。
+- 更高层编排能力：用于表达单个执行单元的边界、多个执行单元之间的关系、阶段推进、失败传播、取消语义、执行计划以及整体完成条件。这部分目前还不是主实现重心，但属于该模块未来合理的组成方向。
+- 结构化执行能力：用于把一组原本零散的异步动作收束为可以理解、组合与扩展的执行结构。未来它可能体现为 task、job、workflow，也可能体现为其它更贴切的抽象，但都不应退化成业务代码里对底层 Promise 的随意组合。
+
+更合适的接入方式，是先判断你的问题属于哪一层：如果你的核心诉求是某个时刻能否进入、是否需要排队、何时统一继续，那么你更接近 coordination；如果你的核心诉求已经开始涉及执行单元如何被声明、取消、组合、计划、收束或被纳入更大的执行结构，那么你已经进入更高层的 orchestration 语义。
+
+当前对外已经落地的主要是 `coordination` 与 `dispatching` 子模块，因此现阶段使用时既可以处理互斥、信号量、读写锁、闭锁与栅栏这类问题，也可以处理一组候选目标之间的 selector 构造、目标选择与反馈驱动分派；但理解这个模块时仍不应把它局限为“并发锁工具箱”或“负载均衡工具箱”。更合适的看法是：coordination 与 dispatching 先提供底层编排积木，而 orchestration 的整体职责会继续向更完整的执行组织与流程编排语义扩展。
+
+## For Contributing
+
+为 Orchestration 模块贡献内容时，优先判断新增能力是否真的在澄清某种稳定的编排语义，而不是只是在补一个局部业务流程的便捷封装。这个模块应长期服务于“执行单元如何被表达”“多个执行单元如何组成更大的结构”“流程如何推进与结束”“等待与放行如何成为可复用原语”这几类问题。如果一个能力只有在绑定特定平台、特定产品流程或特定部署环境时才成立，那么它通常不应直接成为该模块的公共组成部分。
+
+扩展这个模块时，应特别警惕以下倾向：把 orchestration 退化成一堆零散锁工具；把 dispatching 退化成只对某一类 upstream 节点成立的网络负载均衡器包装；把某个具体工作流引擎的配置模型直接照搬进公共 API；把重试、补偿、优先级、监控或持久化策略无差别地下沉到所有层级；把调用方的一次性业务约定固化为模块语义；或者为了某个实现细节而暴露内部等待队列、内部状态节点、候选集快照与临时调度结构。文档应说明哪些编排边界是长期成立的，以及为什么这些边界成立，而不是复述当前版本的局部实现技巧。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/orchestration/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与 orchestration 相关的实现应优先围绕执行单元边界、执行单元关系、等待约束、分派语义、生命周期推进、阶段语义与可组合性组织；其中 coordination 子模块再单独关注占用句柄、队列调度、公平性与同步阶段语义，dispatching 子模块再单独关注候选目标集合、selector 视图、选择策略与反馈驱动调整，避免把具体业务流程、网络拓扑假设或宿主运行时策略混入模块边界。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的编排语义、协调语义或分派语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/orchestration`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/orchestration/<sub-module-name>`。
+- 对这个模块来说，测试应按层覆盖：coordination 层优先覆盖资源获取与释放、等待队列的 FIFO 或公平性约束、超时与中止导致的失败语义、同步点完成或破坏时的整体行为，以及 permit 重复释放等误用路径；dispatching 层优先覆盖 selector 复用与销毁、候选目标过滤、策略驱动的选择顺序、无可选目标与无可用目标的区分，以及反馈回写后对后续选择的影响；未来若引入更高层编排能力，则应优先覆盖生命周期推进、依赖关系收敛、失败传播、取消与重试边界，以及整体编排结果的确定性。