@aigne/doc-smith 0.8.6 → 0.8.7

package/prompts/{document → detail}/detail-example.md

@@ -63,18 +63,25 @@
 
   **Parameters**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `name` | `string` | The name of the product. |
-  | `description` | `string` | An optional description for the product. |
-  | `type` | `string` | The type of product (e.g., `'service'`, `'good'`). |
-  | `prices` | `Partial<TPrice>[]` | An optional array of partial price objects to associate with the product upon creation. Each object can include `type`, `unit_amount`, `currency_id`, and `recurring` details. |
+  <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>
 
   **Returns**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `product` | `TProductExpanded` | The newly created product object, including expanded details. |
+  <x-field data-name="product" data-type="TProductExpanded" data-desc="The newly created product object, including expanded details"></x-field>
 
   **Example**
 
@@ -124,15 +131,11 @@
 
   **Parameters**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `id` | `string` | The unique identifier of the product to retrieve. |
+  <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to retrieve."></x-field>
 
   **Returns**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `product` | `TProductExpanded` | The retrieved product object, including expanded details. |
+  <x-field data-name="product" data-type="TProductExpanded" data-desc="The retrieved product object, including expanded details."></x-field>
 
   **Example**
 
@@ -167,16 +170,13 @@
 
   **Parameters**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `id` | `string` | The unique identifier of the product to update. |
-  | `data` | `Partial<TProduct>` | An object containing the product fields to update. Available fields include `name`, `description`, `type`, etc. |
+  <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>
 
   **Returns**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `product` | `TProductExpanded` | The updated product object. |
+  <x-field data-name="product" data-type="TProductExpanded" data-desc="The updated product object."></x-field>
 
   **Example**
 
@@ -213,25 +213,31 @@
 
   **Parameters**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `active` | `boolean` | Optional. Filter by product active status. |
-  | `name` | `string` | Optional. Filter by product name. |
-  | `description` | `string` | Optional. Filter by product description. |
-  | `metadata.{key}` | `string` | Optional. Filter by custom metadata fields. Use `metadata.yourKey` to specify a metadata property. |
-  | `page` | `number` | Optional. The page number for pagination (default: 1). |
-  | `pageSize` | `number` | Optional. The number of items per page (default: 50). |
-  | `order` | `string` | Optional. Sort order (e.g., `'created_at:ASC'`, `'updated_at:DESC'`). |
-  | `activeFirst` | `boolean` | Optional. If `true`, active products are listed first. |
+  <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>
 
   **Returns**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `data` | `TProductExpanded[]` | An array of product objects. |
-  | `page` | `number` | The current page number. |
-  | `pageSize` | `number` | The number of items per page. |
-  | `total` | `number` | The total number of products matching the criteria. |
+  <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>
 
   **Example**
 
@@ -280,20 +286,21 @@
 
   **Parameters**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `query` | `string` | The search string to match against product fields. |
-  | `page` | `number` | Optional. The page number for pagination (default: 1). |
-  | `pageSize` | `number` | Optional. The number of items per page (default: 50). |
+  <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>
 
   **Returns**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `data` | `TProductExpanded[]` | An array of product objects that match the search query. |
-  | `page` | `number` | The current page number. |
-  | `pageSize` | `number` | The number of items per page. |
-  | `total` | `number` | The total number of products matching the criteria. |
+  <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>
 
   **Example**
 
@@ -341,15 +348,11 @@
 
   **Parameters**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `id` | `string` | The unique identifier of the product to archive. |
+  <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to archive."></x-field>
 
   **Returns**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `product` | `TProduct` | The archived product object. |
+  <x-field data-name="product" data-type="TProduct" data-desc="The archived product object."></x-field>
 
   **Example**
 
@@ -384,15 +387,11 @@
 
   **Parameters**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `id` | `string` | The unique identifier of the product to delete. |
+  <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to delete."></x-field>
 
   **Returns**
 
-  | Name | Type | Description |
-  |---|---|---|
-  | `product` | `TProduct` | The deleted product object. |
+  <x-field data-name="product" data-type="TProduct" data-desc="The deleted product object."></x-field>
 
   **Example**
 
@@ -421,6 +420,26 @@
 
   This example permanently deletes a specified product.
 
+  ## Context Types
+
+  When working with context objects, use `<x-field>` components to describe the structure:
+
+  **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>
+
   ---
 
   This section covered the essential operations for managing products within PaymentKit. You can now define and organize your offerings. Continue to the [Prices](/core-resources/prices) section to learn how to set up pricing for your products.

package/prompts/{document/detail-generator.md → detail/document-rules.md}

@@ -13,8 +13,11 @@
 - 每个 section 需要包含：标题、介绍、代码示例、响应数据示例、示例说明，示例说明跟在示例代码后描述，不需要‘示例说明’这样的小标题
 - 确保文档中的内容是完整、连贯的，用户可以跟着文档一步步顺利执行
 - 说明要尽可能的详细，如果存在配置项或参数，需要解释每个配置项或参数的含义，如果参数有多个可选值，每种可选值需要解释其含义，并尽可能配上代码示例
-- 参数优先使用 markdown 中的 table 来展示，让内容看上去更整齐，容易阅读
+- 参数、返回值、上下文数据（Context）、Props 以及与类型相关的内容优先使用 `<x-field>` 自定义组件来展示，支持嵌套结构来清晰描述复杂数据类型
+- 对于复杂对象类型，使用嵌套的 `<x-field>` 结构来递归描述参数结构，嵌套层级不超过 5 级
+- 所有类型都使用开闭标签格式 `<x-field ...></x-field>`，简单类型 children 为空，复杂类型包含嵌套字段
 - 接口/方法调用的说明必须包含 **响应数据示例**
+- 对于其他类型的列表数据，数据内容简单，优先使用 markdown 中的 table 来展示，让内容看上去更整齐，容易阅读
 - 对输出的 markdown 进行检查，确认输出内容完整，table、d2 信息完整并且格式正确
 - **确保内容完整性**：在生成任何文档内容，特别是代码块（如 d2、JSON、代码等）时，必须确保其是**完整且语法正确**的。在输出完成后，必须进行一次**自我检查**，确认所有的代码块、列表、表格等都已完全闭合且没有中途截断。
 - **代码块原子性**：将每个代码块（例如 ```d2 ... ```）视为一个**不可分割的原子单元**。必须一次性完整生成，从开始标记（```d2）到结束标记（```）之间的所有内容都不能省略或截断。
@@ -26,13 +29,6 @@
 
 </document_rules>
 
-<document_rules>
-
-D2 Diagram Generation Expert Guide:
-{% include "d2-chart/rules.md" %}
-
-</document_rules>
-
 <TONE_STYLE>
 - Documentation should be plain, rigorous and accurate, avoiding grandiose or empty vocabulary
 - You are writing for humans, not algorithms

package/prompts/{content-detail-generator.md → detail/generate-document.md}

@@ -1,12 +1,21 @@
-你是一个高级内容详情生成专家，擅长为网站、文档、书籍、演示文稿等多种场景生成结构合理、内容丰富且有吸引力的{{nodeName}}内容。
+<role>
+你是一位资深的文档专家和信息架构师，拥有渊博的知识和卓越的沟通能力。你的核心任务是将各种来源的信息，无论是代码、配置、设计文档、用户需求还是其他结构化或非结构化数据，转化为清晰、准确、全面且用户友好的文档。
 
-<goal>
-你的任务是根据用户提供的 当前 {{nodeName}}（包含标题、描述、路径）、DataSources、structurePlan（整体结构规划）等信息，生成当前{{nodeName}}的详细内容。
-</goal>
+你的优势在于：
+  - 深度理解能力： 你能够快速、深入地分析和理解不同类型的数据源，识别其中的关键信息、逻辑关系、潜在问题以及用户可能关心的重点。
+  - 信息提炼与组织： 你擅长从海量信息中提炼出核心要点，并根据文档的目的和目标受众，以逻辑清晰、结构严谨的方式进行组织和呈现。
+  - 通用化写作风格： 你不受限于特定技术领域，能够根据文档的通用性需求，采用恰当的语言风格，无论是技术说明、操作指南、产品介绍还是业务流程文档，都能游刃有余。
+  - 质量导向： 你始终追求文档的顶级质量，确保内容的准确性、完整性、一致性、可读性和实用性。你关注细节，力求每一处表述都精准到位。
+  - 用户视角： 你会站在目标读者的角度思考，预测他们可能遇到的疑问和困惑，并在文档中提前解答，从而提升文档的用户体验和价值。
 
-<review_feedback>
+你的任务是根据用户提供的信息：当前 {{nodeName}}（包含标题、描述、路径）信息、DataSources、documentStructure（整体结构规划）等信息，生成当前{{nodeName}}的详细内容。
+</role>
+
+{% if detailFeedback %}
+<content_review_feedback>
 {{ detailFeedback }}
-</review_feedback>
+</content_review_feedback>
+{% endif %}
 
 <user_locale>
 {{ locale }}
@@ -23,37 +32,45 @@
 
 </datasources>
 
+{% if glossary %}
 <terms>
 专有词汇表，使用时请确保拼写正确。
 
 {{glossary}}
 </terms>
+{% endif %}
 
-<structure_plan>
-{{ structurePlanYaml }}
-</structure_plan>
+<document_structure>
+{{ documentStructureYaml }}
+</document_structure>
 
-<current>
+<current_document>
 当前{{nodeName}}信息：
 title: {{title}}
 description: {{description}}
 path: {{path}}
 parentId: {{parentId}}
+</current_document>
 
+{% if content %}
 上一轮生成的内容：
 <last_content>
 {{content}}
 </last_content>
+{% endif %}
 
+{% if feedback %}
 用户对上一轮的反馈意见：
 <feedback>
 {{feedback}}
 </feedback>
+{% endif %}
 
-<review_feedback>
+{% if detailFeedback %}
+<content_review_feedback>
 {{ detailFeedback }}
-</review_feedback>
-</current>
+</content_review_feedback>
+{% endif %}
 
 <user_rules>
 {{ rules }}
@@ -61,15 +78,17 @@ parentId: {{parentId}}
 ** 使用 {{ locale }} 语言输出内容 **
 </user_rules>
 
+{% if userPreferences %}
 <user_preferences>
 {{userPreferences}}
 
 用户偏好使用规则：
-- 用户偏好来自用户之前操作中提供的反馈，生成结构规划中需要考虑用户的偏好，避免出现用户反馈的问题又重复出现
+- 用户偏好来自用户之前操作中提供的反馈，生成内容中需要考虑用户的偏好，避免出现用户反馈的问题又重复出现
 - 用户偏好的权重低于本次用户提交的反馈
 </user_preferences>
+{% endif %}
 
-<rules>
+<content_generation_rules>
 
 目标受众：{{targetAudience}}
 
@@ -78,7 +97,7 @@ parentId: {{parentId}}
 - 仅使用 DataSources 中的信息，不能虚构、补充未出现的内容。
 - 结合当前{{nodeName}}的标题、描述，合理规划{{nodeName}}内容结构，内容要丰富、有条理、有吸引力。
 - 内容风格需要匹配目标受众
-- 明确区分与 structurePlan 其他{{nodeName}}的内容，避免重复，突出本{{nodeName}}的独特价值。
+- 明确区分与 documentStructure 其他{{nodeName}}的内容，避免重复，突出本{{nodeName}}的独特价值。
 {% if enforceInfoCompleteness %}
 - 如果 DataSources 相关信息不足，直接返回错误信息，提示用户补充内容，要确保页面内容足够丰富，你可以放心的向用户提出补充信息的要求。
 - 只展示有价值、能吸引用户的信息，如信息不足，提示用户补充信息
@@ -91,7 +110,6 @@ parentId: {{parentId}}
 - 不要在输出中直接 Data Sources 中的文件路径，这对用户是没有意义的
 - 不要出现 '当前{{nodeName}}' 这种说法
 
-<media_rules>
 媒体资源使用规则：
 
 - DataSource 中如果包含媒体资源文件，在生成的结果需要合理的使用
@@ -100,21 +118,26 @@ parentId: {{parentId}}
 - 根据资源描述，在上下文相关的位置，合理的展示图片，让结果展示效果更丰富
 - 为了确保媒体资源路径正确，** 只能使用 media_list 中提供媒体资源或提供远程 URL 的媒体资源 **
 
-</media_rules>
 
-{% include "document/detail-generator.md" %}
+文档类型内容生成规则：
+{% include "./document-rules.md" %}
+
+自定义组件生成规则：
+{% include "custom/custom-components.md" %}
 
-{% include "document/custom-components.md" %}
+自定义代码块生成规则：
+{% include "custom/custom-code-block.md" %}
 
-{% include "document/custom-code-block.md" %}
-</rules>
+D2 Diagram Generation Expert Guide:
+{% include "d2-chart/rules.md" %}
+</content_generation_rules>
 
-{% include "document/detail-example.md" %}
+{% include "./detail-example.md" %}
 
-<output_schema>
+<output_rules>
 
 1. 输内容为{{nodeName}}的详细文本。
 2. 直接输出{{nodeName}}内容，不要包含其他信息.
 3. 仅参考示例中的风格，**以语言 {{locale}} 输出内容 **
 
-</output_schema>
+</output_rules>

package/prompts/{check-structure-planning-result.md → structure/check-document-structure.md}

@@ -3,20 +3,26 @@
 </role>
 
 <context>
-- **上一轮的结构规划 (originalStructurePlan)**:
+- **上一轮的结构规划 (originalDocumentStructure)**:
+<original_document_structure>
 ```json
-{{ originalStructurePlan }}
+{{ originalDocumentStructure }}
 ```
+</original_document_structure>
 
-- **新生成的结构规划 (structurePlan)**:
+- **新生成的结构规划 (documentStructure)**:
+<document_structure>
 ```json
-{{ structurePlan }}
+{{ documentStructure }}
 ```
+</document_structure>
 
+{% if feedback %}
 - **用户反馈**:
 ```
 {{ feedback }}
 ```
+{% endif %}
 </context>
 
 <goal>
@@ -28,9 +34,9 @@
 4.  **数据有效性**: 所有 {{ nodeName }} 都有关联数据源，sourceIds 中都有值。
 </goal>
 
-<rules>
+<quality_control_rules>
 ### 场景 1：首次运行（没有旧的规划）
-如果 `originalStructurePlan` 为 null、为空或未提供，这意味着这是第一次生成结构。没有可供比较的对象。
+如果 `originalDocumentStructure` 为 null、为空或未提供，这意味着这是第一次生成结构。没有可供比较的对象。
 你的检查自动通过。
 
 ### 场景 2：迭代运行（存在旧的规划）
@@ -38,13 +44,13 @@
 
 **分步分析**：
 1.  **分析反馈**：仔细阅读并理解 `<context>` 中 用户反馈 提出的每一项变更要求。明确哪些节点是需要被修改、添加或删除的目标。
-2.  **验证反馈的实现**：对比 `<context>` 中的 `structurePlan` 和 `originalStructurePlan`，确认所要求的变更是否已执行。例如，如果反馈是“移除‘示例’部分”，你必须检查该部分在 `structurePlan` 中是否已不存在。
-3.  **验证无关节点的稳定性**：这是最关键的检查。遍历 `structurePlan` 中的所有节点。对于每一个在 `originalStructurePlan` 中也存在、但并未在反馈中被提及的节点：
-    *   **至关重要**：其 `path`、`sourcesIds` 属性**必须**与 `originalStructurePlan` 中的完全相同。
+2.  **验证反馈的实现**：对比 `<context>` 中的 `documentStructure` 和 `originalDocumentStructure`，确认所要求的变更是否已执行。例如，如果反馈是“移除‘示例’部分”，你必须检查该部分在 `documentStructure` 中是否已不存在。
+3.  **验证无关节点的稳定性**：这是最关键的检查。遍历 `documentStructure` 中的所有节点。对于每一个在 `originalDocumentStructure` 中也存在、但并未在反馈中被提及的节点：
+    *   **至关重要**：其 `path`、`sourcesIds` 属性**必须**与 `originalDocumentStructure` 中的完全相同。
     *   理想情况下，其他属性（如 `title`、`description`）也应保持稳定，除非这些变更是由某个被要求的变更直接导致的，或者是 DataSource 变更导致。
-</rules>
+</quality_control_rules>
 
-<output>
+<output_rules>
 你的输出必须是一个包含 `isValid` 和 `reason` 的有效 JSON 对象，使用 en 返回。
 
 *   **如果两条规则都满足**：
@@ -52,7 +58,7 @@
     ```json
     {
       "isValid": true,
-      "reason": "The new structure plan correctly implements user feedback while maintaining stability of all unrelated nodes."
+      "reason": "The new document structure correctly implements user feedback while maintaining stability of all unrelated nodes."
     }
     ```
 
@@ -61,7 +67,7 @@
     ```json
     {
       "isValid": false,
-      "reason": "The new structure plan fails to correctly implement user feedback. [Please provide specific details, e.g.: 'Feedback requested renaming 'Introduction' to 'Overview', but this change was not executed.']"
+      "reason": "The new document structure fails to correctly implement user feedback. [Please provide specific details, e.g.: 'Feedback requested renaming 'Introduction' to 'Overview', but this change was not executed.']"
     }
     ```
 
@@ -70,7 +76,7 @@
     ```json
     {
       "isValid": false,
-      "reason": "The new structure plan modified unrelated nodes, which is not allowed. [Please provide specific details, e.g.: 'The path of node 'API Reference' was changed from '/api' to '/reference/api' without any feedback requesting this change. This is a critical error.']"
+      "reason": "The new document structure modified unrelated nodes, which is not allowed. [Please provide specific details, e.g.: 'The path of node 'API Reference' was changed from '/api' to '/reference/api' without any feedback requesting this change. This is a critical error.']"
     }
     ```
 
@@ -78,7 +84,7 @@
     ```json
     {
       "isValid": false,
-      "reason": "The structure plan contains nodes without associated data sources. Each node must have at least one source file linked through sourcesIds."
+      "reason": "The document structure contains nodes without associated data sources. Each node must have at least one source file linked through sourcesIds."
     }
     ```
 
@@ -87,7 +93,7 @@
     ```json
     {
       "isValid": true,
-      "reason": "First structure plan generation, no previous version to compare with."
+      "reason": "First document structure generation, no previous version to compare with."
     }
     ```
-</output>
+</output_rules>

package/prompts/{document/structure-planning.md → structure/document-rules.md}

@@ -1,5 +1,4 @@
 
-<document_rules>
 文档类结构规划规则：
   - 对于结构规划需要生成完整的文档结构，覆盖源码中的所有功能，并提供代码示例的示例。
   - 基于提供的源代码进行结构规划，确保规划的节点都有足够的信息展示
@@ -13,4 +12,3 @@
   - 标题中不需要包含产品名称，显示更加精简
   - 'Overview' 章节应该引用所有源代码，方便写出准确全面的介绍
   - 每个部分文档都应该尽可能多的引用相关的源代码，来确保生成文档更详细准确，对于你不确定的项，优先添加引用
-</document_rules>