@aigne/doc-smith 0.8.10-beta → 0.8.10-beta.2

package/prompts/detail/detail-example.md

@@ -63,21 +63,20 @@
 
   **Parameters**
 
-  <x-field data-name="name" data-type="string" data-required="true" data-desc="The name of the product."></x-field>
-
-  <x-field data-name="description" data-type="string" data-required="false" data-desc="An optional description for the product."></x-field>
-
-  <x-field data-name="type" data-type="string" data-required="false" data-desc="The type of product (e.g., 'service', 'good')."></x-field>
-
-  <x-field data-name="prices" data-type="Partial<TPrice>[]" data-required="false" data-desc="An optional array of partial price objects to associate with the product upon creation">
-    <x-field data-name="type" data-type="string" data-required="true" data-desc="The type of price (e.g., 'recurring', 'one_time')"></x-field>
-    <x-field data-name="unit_amount" data-type="string" data-required="true" data-desc="The price amount as a string"></x-field>
-    <x-field data-name="currency_id" data-type="string" data-required="true" data-desc="The currency identifier"></x-field>
-    <x-field data-name="recurring" data-type="object" data-required="false" data-desc="Recurring price configuration">
-      <x-field data-name="interval" data-type="string" data-required="true" data-desc="The billing interval (e.g., 'month', 'year')"></x-field>
-      <x-field data-name="interval_count" data-type="number" data-required="true" data-desc="The number of intervals between each billing"></x-field>
+  <x-field-group>
+    <x-field data-name="name" data-type="string" data-required="true" data-desc="The name of the product."></x-field>
+    <x-field data-name="description" data-type="string" data-required="false" data-desc="An optional description for the product."></x-field>
+    <x-field data-name="type" data-type="string" data-required="false" data-desc="The type of product (e.g., 'service', 'good')."></x-field>
+    <x-field data-name="prices" data-type="Partial<TPrice>[]" data-required="false" data-desc="An optional array of partial price objects to associate with the product upon creation">
+      <x-field data-name="type" data-type="string" data-required="true" data-desc="The type of price (e.g., 'recurring', 'one_time')"></x-field>
+      <x-field data-name="unit_amount" data-type="string" data-required="true" data-desc="The price amount as a string"></x-field>
+      <x-field data-name="currency_id" data-type="string" data-required="true" data-desc="The currency identifier"></x-field>
+      <x-field data-name="recurring" data-type="object" data-required="false" data-desc="Recurring price configuration">
+        <x-field data-name="interval" data-type="string" data-required="true" data-desc="The billing interval (e.g., 'month', 'year')"></x-field>
+        <x-field data-name="interval_count" data-type="number" data-required="true" data-desc="The number of intervals between each billing"></x-field>
+      </x-field>
     </x-field>
-  </x-field>
+  </x-field-group>
 
   **Returns**
 
@@ -169,10 +168,11 @@
   Use the `update` method to modify an existing product's details.
 
   **Parameters**
-
-  <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to update."></x-field>
-
-  <x-field data-name="data" data-type="Partial<TProduct>" data-required="true" data-desc="An object containing the product fields to update. Available fields include name, description, type, etc."></x-field>
+  
+  <x-field-group>
+    <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to update."></x-field>
+    <x-field data-name="data" data-type="Partial<TProduct>" data-required="true" data-desc="An object containing the product fields to update. Available fields include name, description, type, etc."></x-field>
+  </x-field-group>
 
   **Returns**
 
@@ -213,31 +213,25 @@
 
   **Parameters**
 
-  <x-field data-name="active" data-type="boolean" data-required="false" data-desc="Optional. Filter by product active status."></x-field>
-
-  <x-field data-name="name" data-type="string" data-required="false" data-desc="Optional. Filter by product name."></x-field>
-
-  <x-field data-name="description" data-type="string" data-required="false" data-desc="Optional. Filter by product description."></x-field>
-
-  <x-field data-name="metadata.{key}" data-type="string" data-required="false" data-desc="Optional. Filter by custom metadata fields. Use metadata.yourKey to specify a metadata property."></x-field>
-
-  <x-field data-name="page" data-type="number" data-default="1" data-required="false" data-desc="Optional. The page number for pagination (default: 1)."></x-field>
-
-  <x-field data-name="pageSize" data-type="number" data-default="50" data-required="false" data-desc="Optional. The number of items per page (default: 50)."></x-field>
-
-  <x-field data-name="order" data-type="string" data-required="false" data-desc="Optional. Sort order (e.g., 'created_at:ASC', 'updated_at:DESC')."></x-field>
-
-  <x-field data-name="activeFirst" data-type="boolean" data-required="false" data-desc="Optional. If true, active products are listed first."></x-field>
+  <x-field-group>
+    <x-field data-name="active" data-type="boolean" data-required="false" data-desc="Optional. Filter by product active status."></x-field>
+    <x-field data-name="name" data-type="string" data-required="false" data-desc="Optional. Filter by product name."></x-field>
+    <x-field data-name="description" data-type="string" data-required="false" data-desc="Optional. Filter by product description."></x-field>
+    <x-field data-name="metadata.{key}" data-type="string" data-required="false" data-desc="Optional. Filter by custom metadata fields. Use metadata.yourKey to specify a metadata property."></x-field>
+    <x-field data-name="page" data-type="number" data-default="1" data-required="false" data-desc="Optional. The page number for pagination (default: 1)."></x-field>
+    <x-field data-name="pageSize" data-type="number" data-default="50" data-required="false" data-desc="Optional. The number of items per page (default: 50)."></x-field>
+    <x-field data-name="order" data-type="string" data-required="false" data-desc="Optional. Sort order (e.g., 'created_at:ASC', 'updated_at:DESC')."></x-field>
+    <x-field data-name="activeFirst" data-type="boolean" data-required="false" data-desc="Optional. If true, active products are listed first."></x-field>
+  </x-field-group>
 
   **Returns**
 
-  <x-field data-name="data" data-type="TProductExpanded[]" data-desc="An array of product objects."></x-field>
-
-  <x-field data-name="page" data-type="number" data-desc="The current page number."></x-field>
-
-  <x-field data-name="pageSize" data-type="number" data-desc="The number of items per page."></x-field>
-
-  <x-field data-name="total" data-type="number" data-desc="The total number of products matching the criteria."></x-field>
+  <x-field-group>
+    <x-field data-name="data" data-type="TProductExpanded[]" data-desc="An array of product objects."></x-field>
+    <x-field data-name="page" data-type="number" data-desc="The current page number."></x-field>
+    <x-field data-name="pageSize" data-type="number" data-desc="The number of items per page."></x-field>
+    <x-field data-name="total" data-type="number" data-desc="The total number of products matching the criteria."></x-field>
+  </x-field-group>
 
   **Example**
 
@@ -286,21 +280,20 @@
 
   **Parameters**
 
-  <x-field data-name="query" data-type="string" data-required="true" data-desc="The search string to match against product fields."></x-field>
-
-  <x-field data-name="page" data-type="number" data-default="1" data-required="false" data-desc="Optional. The page number for pagination (default: 1)."></x-field>
-
-  <x-field data-name="pageSize" data-type="number" data-default="50" data-required="false" data-desc="Optional. The number of items per page (default: 50)."></x-field>
+  <x-field-group>
+    <x-field data-name="query" data-type="string" data-required="true" data-desc="The search string to match against product fields."></x-field>
+    <x-field data-name="page" data-type="number" data-default="1" data-required="false" data-desc="Optional. The page number for pagination (default: 1)."></x-field>
+    <x-field data-name="pageSize" data-type="number" data-default="50" data-required="false" data-desc="Optional. The number of items per page (default: 50)."></x-field>
+  </x-field-group>
 
   **Returns**
 
-  <x-field data-name="data" data-type="TProductExpanded[]" data-desc="An array of product objects that match the search query."></x-field>
-
-  <x-field data-name="page" data-type="number" data-desc="The current page number."></x-field>
-
-  <x-field data-name="pageSize" data-type="number" data-desc="The number of items per page."></x-field>
-
-  <x-field data-name="total" data-type="number" data-desc="The total number of products matching the criteria."></x-field>
+  <x-field-group>
+    <x-field data-name="data" data-type="TProductExpanded[]" data-desc="An array of product objects that match the search query."></x-field>
+    <x-field data-name="page" data-type="number" data-desc="The current page number."></x-field>
+    <x-field data-name="pageSize" data-type="number" data-desc="The number of items per page."></x-field>
+    <x-field data-name="total" data-type="number" data-desc="The total number of products matching the criteria."></x-field>
+  </x-field-group>
 
   **Example**
 
@@ -426,19 +419,19 @@
 
   **UserContext**
 
-  <x-field data-name="user" data-type="object" data-required="true" data-desc="Current user information">
-    <x-field data-name="id" data-type="string" data-required="true" data-desc="User unique identifier"></x-field>
-    <x-field data-name="name" data-type="string" data-required="true" data-desc="User display name"></x-field>
-    <x-field data-name="email" data-type="string" data-required="true" data-desc="User email address"></x-field>
-    <x-field data-name="role" data-type="string" data-default="user" data-desc="User role (user, admin, moderator)"></x-field>
-  </x-field>
-
-  <x-field data-name="session" data-type="object" data-required="true" data-desc="Current session information">
-    <x-field data-name="token" data-type="string" data-required="true" data-desc="Session authentication token"></x-field>
-    <x-field data-name="expiresAt" data-type="number" data-required="true" data-desc="Session expiration timestamp"></x-field>
-  </x-field>
-
-  <x-field data-name="permissions" data-type="array" data-required="false" data-desc="User permissions list"></x-field>
+  <x-field-group>
+    <x-field data-name="user" data-type="object" data-required="true" data-desc="Current user information">
+      <x-field data-name="id" data-type="string" data-required="true" data-desc="User unique identifier"></x-field>
+      <x-field data-name="name" data-type="string" data-required="true" data-desc="User display name"></x-field>
+      <x-field data-name="email" data-type="string" data-required="true" data-desc="User email address"></x-field>
+      <x-field data-name="role" data-type="string" data-default="user" data-desc="User role (user, admin, moderator)"></x-field>
+    </x-field>
+    <x-field data-name="session" data-type="object" data-required="true" data-desc="Current session information">
+      <x-field data-name="token" data-type="string" data-required="true" data-desc="Session authentication token"></x-field>
+      <x-field data-name="expiresAt" data-type="number" data-required="true" data-desc="Session expiration timestamp"></x-field>
+    </x-field>
+    <x-field data-name="permissions" data-type="array" data-required="false" data-desc="User permissions list"></x-field>
+  </x-field-group>
 
   ---
 

package/prompts/detail/document-rules.md

@@ -13,9 +13,10 @@
 - 每个 section 需要包含：标题、介绍、代码示例、响应数据示例、示例说明，示例说明跟在示例代码后描述，不需要‘示例说明’这样的小标题
 - 确保文档中的内容是完整、连贯的，用户可以跟着文档一步步顺利执行
 - 说明要尽可能的详细，如果存在配置项或参数，需要解释每个配置项或参数的含义，如果参数有多个可选值，每种可选值需要解释其含义，并尽可能配上代码示例
-- 参数、返回值、上下文数据（Context）、Props 以及与类型相关的内容优先使用 `<x-field>` 自定义组件来展示，支持嵌套结构来清晰描述复杂数据类型
+- 参数、返回值、上下文数据（Context）、Props 以及其它与类型相关的内容优先使用 `<x-field>` 自定义组件来展示，支持嵌套结构来清晰描述复杂数据类型
 - 对于复杂对象类型，使用嵌套的 `<x-field>` 结构来递归描述参数结构，嵌套层级不超过 5 级
 - 所有类型都使用开闭标签格式 `<x-field ...></x-field>`，简单类型 children 为空，复杂类型包含嵌套字段
+- 描述同一个对象的多个最外层的 `<x-field>` 元素应该用 `<x-field-group>` 元素包裹。注意内嵌的 `<x-field>` 不需要包裹
 - 接口/方法调用的说明必须包含 **响应数据示例**
 - 对于其他类型的列表数据，数据内容简单，优先使用 markdown 中的 table 来展示，让内容看上去更整齐，容易阅读
 - 对输出的 markdown 进行检查，确认输出内容完整，table、d2 信息完整并且格式正确

package/prompts/structure/check-document-structure.md

@@ -5,29 +5,25 @@
 <context>
 - **上一轮的结构规划 (originalDocumentStructure)**:
 <original_document_structure>
-```json
 {{ originalDocumentStructure }}
-```
 </original_document_structure>
 
-- **新生成的结构规划 (documentStructure)**:
-<document_structure>
-```json
-{{ documentStructure }}
-```
-</document_structure>
-
 {% if feedback %}
 - **用户反馈**:
 ```
 {{ feedback }}
 ```
 {% endif %}
+
+- **新生成的结构规划 (documentStructure)**:
+<document_structure>
+{{ documentStructure }}
+</document_structure>
 </context>
 
 <goal>
 你的主要目标是验证三条关键规则：
-1.  **反馈的实现**：新的结构规划**必须**正确地实现用户反馈中要求的所有变更。
+1.  **反馈的实现**：新的结构规划(document_structure)**必须**正确地实现用户反馈中要求的所有变更。
 2.  **无关节点的稳定性**：没有在用户反馈中被提及的节点 ** path、sourcesIds 属性不能被修改 **
   - `path`、`sourcesIds` 是关联现有内容的关键标识符，其稳定性至关重要。
   - 对于用户要求新增节点的场景，新增的节点可能会影响原来节点的顺序，这是允许的。
@@ -36,17 +32,17 @@
 
 <quality_control_rules>
 ### 场景 1：首次运行（没有旧的规划）
-如果 `originalDocumentStructure` 为 null、为空或未提供，这意味着这是第一次生成结构。没有可供比较的对象。
+如果 `original_document_structure` 为 null、为空或未提供，这意味着这是第一次生成结构。没有可供比较的对象。
 你的检查自动通过。
 
 ### 场景 2：迭代运行（存在旧的规划）
 这是主要场景。你必须执行详细的比较。
 
 **分步分析**：
-1.  **分析反馈**：仔细阅读并理解 `<context>` 中 用户反馈 提出的每一项变更要求。明确哪些节点是需要被修改、添加或删除的目标。
-2.  **验证反馈的实现**：对比 `<context>` 中的 `documentStructure` 和 `originalDocumentStructure`，确认所要求的变更是否已执行。例如，如果反馈是“移除‘示例’部分”，你必须检查该部分在 `documentStructure` 中是否已不存在。
-3.  **验证无关节点的稳定性**：这是最关键的检查。遍历 `documentStructure` 中的所有节点。对于每一个在 `originalDocumentStructure` 中也存在、但并未在反馈中被提及的节点：
-    *   **至关重要**：其 `path`、`sourcesIds` 属性**必须**与 `originalDocumentStructure` 中的完全相同。
+1.  **分析反馈**：仔细阅读并理解中用户反馈提出的每一项变更要求。明确哪些节点是需要被修改、添加或删除的目标。
+2.  **验证反馈的实现**：确认所要求的变更在`document_structure`已执行。例如，如果反馈是“移除‘示例’部分”，你必须检查该部分在 `document_structure` 中是否已不存在。
+3.  **验证无关节点的稳定性**：这是最关键的检查。遍历 `document_structure` 中的所有节点。对于每一个在 `original_document_structure` 中也存在、但并未在反馈中被提及的节点：
+    *   **至关重要**：其 `path`、`sourcesIds` 属性**必须**与 `original_document_structure` 中的完全相同。
     *   理想情况下，其他属性（如 `title`、`description`）也应保持稳定，除非这些变更是由某个被要求的变更直接导致的，或者是 DataSource 变更导致。
 </quality_control_rules>
 

package/prompts/translate/translate-document.md

@@ -2,30 +2,32 @@
 你是一位精通多种语言（尤其精通中文和英语）的专业翻译人员，擅长准确规范的双语转换。
 </role>
 
-
 <translation_rules>
 翻译要求:
+
 - **准确传达**原文的事实和背景，确保完整无遗漏。
 - **避免夸张**，避免使用带有情绪化和主观色彩的词语（例如“激动”、“震惊”等）。
 - **遵守语言规范**，确保标点符号和语法正确，表达自然流畅。
 - **保留原文结构**，仅翻译内容部分，不添加或修改标签，不添加额外内容或标点符号。不要在最外层添加 markdown 语法。确保翻译后结构和原文相同，原文中的换行、空白行也要保留。
-- **严格保护 Markdown 语法**：Markdown 的所有语法字符，包括但不限于表格中的 `|` 和 `-`、列表中的 `*` 和 `-`、标题的 `#`、代码块的 ``` ` ``` 等，都必须**原样复制**，不得进行任何形式的修改、增删或合并。特别是表格的分隔线（例如 `|---|---|---|`），必须与原文的列数和格式完全一致,且表格的分隔线与表格数据列数相同。
+- **严格保护 Markdown 语法**：Markdown 的所有语法字符，包括但不限于表格中的 `|` 和 `-`、列表中的 `*` 和 `-`、标题的 `#`、代码块的 `` ` `` 等，都必须**原样复制**，不得进行任何形式的修改、增删或合并。特别是表格的分隔线（例如 `|---|---|---|`），必须与原文的列数和格式完全一致,且表格的分隔线与表格数据列数相同。
 - **遵循翻译流程**，包括直译、优化和检查遗漏，确保最终输出符合要求。
 - **使用术语参考**，确保专业术语的准确性和一致性。
 - **保留术语**，保留特定术语的原文形式，避免翻译。
 
 翻译过程：
+
 - **直译**：将原文逐字逐句翻译成目标语言，确保每个词语的含义都被准确传达。
 - **优化**：在直译结果的基础上，确保译文在忠实于原文含义的同时更加通俗易懂，并符合 **{{ language }}** 的表达习惯。
 - **检查遗漏**：将原文与直译结果进行比较，纠正任何歪曲原文含义或遗漏的信息。
 - **格式检查**：将原文与直译结果进行比较，确保翻译后的内容完整，如果原文是 markdown 格式，检查格式与原文相同。
 - **最终输出**：输出优化后的翻译结果，确保符合上述要求（不要输出直译内容）。
-</translation_rules>
+  </translation_rules>
 
 {% include "./glossary.md" %}
 
 保留术语（不翻译）：
 <terms>
+
 - Agent（所有 Agent 或带有 Agent 前缀或后缀的术语均不翻译）
 
 {{glossary}}
@@ -33,9 +35,9 @@
 
 双语术语（使用 `原文 (翻译)` 格式）：
 <bilingual-terms>
-- Guide Rails: 行为导轨
-</bilingual-terms>
 
+- Guide Rails: 行为导轨
+  </bilingual-terms>
 
 <example>
 <before_translate>
@@ -62,11 +64,19 @@
 <x-field data-name="teamDid" data-type="string" data-required="true" data-desc="The DID of the team or Blocklet managing the webhook."></x-field>
 </before_translate>
 
+<x-field data-name="apiKey" data-type="string" data-required="true">
+    <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section.</x-field-desc>
+</x-field>
+
 <after_translate>
 <x-field data-name="teamDid" data-type="string" data-required="true" data-desc="管理 Webhook 的团队或 Blocklet 的 DID。"></x-field>
+
+<x-field data-name="apiKey" data-type="string" data-required="true">
+    <x-field-desc markdown>您的 **API 密钥**，用于身份验证。请从 `设置 > API 密钥` 部分生成一个。</x-field-desc>
+</x-field>
 </after_translate>
 
-**特别注意**: x-field 组件的所有属性都需要保持原文格式，只翻译 data-desc 属性中的描述内容
+**特别注意**: x-field 组件的所有属性都需要保持原文格式，只翻译 data-desc 属性中或 x-field-desc 元素中的描述内容
 </example>
 
 原文如下：
@@ -91,10 +101,11 @@
 {{userPreferences}}
 
 用户偏好使用规则：
+
 - 用户偏好来自用户之前操作中提供的反馈，生成结构规划中需要考虑用户的偏好，避免出现用户反馈的问题又重复出现
 - 用户偏好的权重低于本次用户提交的反馈
-</user_preferences>
-{% endif %}
+  </user_preferences>
+  {% endif %}
 
 指令：
-请将 <content> 中的内容（不包含最外层的 <content> 标签） **准确** 地翻译成 **{{ language }}**，并严格遵循翻译要求。
+请将 <content> 中的内容（不包含最外层的 <content> 标签） **准确** 地翻译成 **{{ language }}**，并严格遵循翻译要求。

package/tests/agents/generate/check-need-generate-structure.test.mjs

@@ -21,6 +21,9 @@ describe("check-need-generate-structure", () => {
   let saveValueToConfigSpy;
 
   beforeEach(() => {
+    // Set test environment variable
+    process.env.NODE_ENV = "test";
+
     // Reset all mocks
     mock.restore();
 
@@ -32,6 +35,7 @@ describe("check-need-generate-structure", () => {
     mockOptions = {
       prompts: {
         input: mock(async () => ""),
+        select: mock(async () => ""),
       },
       context: {
         agents: { refineDocumentStructure: {} },
@@ -70,6 +74,9 @@ describe("check-need-generate-structure", () => {
   });
 
   afterEach(() => {
+    // Clean up environment variable
+    delete process.env.NODE_ENV;
+
     // Restore all spies
     accessSpy?.mockRestore();
     getActiveRulesForScopeSpy?.mockRestore();
@@ -92,19 +99,7 @@ describe("check-need-generate-structure", () => {
     expect(mockOptions.context.invoke).not.toHaveBeenCalled();
   });
 
-  test("should prompt for user feedback when originalDocumentStructure exists", async () => {
-    const userFeedback = "Need more API documentation";
-    mockOptions.prompts.input.mockImplementation(async () => userFeedback);
-
-    await checkNeedGenerateStructure({ originalDocumentStructure, docsDir: "./docs" }, mockOptions);
-
-    expect(mockOptions.prompts.input).toHaveBeenCalledWith({
-      message: "How can we improve the documentation structure? (press Enter to skip):",
-    });
-    expect(mockOptions.context.invoke).toHaveBeenCalled();
-  });
-
-  test("should skip prompting if feedback is already provided", async () => {
+  test("should handle pre-existing feedback without prompting", async () => {
     const providedFeedback = "Already provided feedback";
 
     await checkNeedGenerateStructure(
@@ -257,17 +252,6 @@ describe("check-need-generate-structure", () => {
     expect(result.feedback).toBe("");
   });
 
-  test("should preserve documentStructureFeedback", async () => {
-    const feedback = "user submitted feedback";
-
-    const result = await checkNeedGenerateStructure(
-      { originalDocumentStructure, feedback, docsDir: "./docs" },
-      mockOptions,
-    );
-
-    expect(result.documentStructureFeedback).toBe(feedback);
-  });
-
   test("should pass through additional parameters", async () => {
     const additionalParams = {
       customParam1: "value1",
@@ -289,4 +273,17 @@ describe("check-need-generate-structure", () => {
       expect.objectContaining(additionalParams),
     );
   });
+
+  test("should return userDeferred when user selects 'later' and no originalDocumentStructure exists", async () => {
+    mockOptions.prompts.select.mockImplementation(async () => "later");
+
+    const result = await checkNeedGenerateStructure({ docsDir: "./docs" }, mockOptions);
+
+    expect(result).toBeDefined();
+    expect(result.userDeferred).toBe(true);
+    expect(result.documentStructure).toBe(null);
+
+    expect(mockOptions.prompts.select).toHaveBeenCalled();
+    expect(mockOptions.context.invoke).not.toHaveBeenCalled();
+  });
 });