@aigne/doc-smith 0.0.1

package/prompts/document/detail-example.md

@@ -0,0 +1,441 @@
+<example>
+下面是一些优质的文档详情供你参考：
+
+<example_item>
+  # Quick install guide
+
+  Before you can use Django, you’ll need to get it installed. We have a complete installation guide that covers all the possibilities; this guide will guide you to a minimal installation that’ll work while you walk through the introduction.
+
+  ## Install Python
+
+  Being a Python web framework, Django requires Python. See What Python version can I use with Django? for details. Python includes a lightweight database called SQLite so you won’t need to set up a database just yet.
+
+  Get the latest version of Python at [https://www.python.org/downloads/](https://www.python.org/downloads/) or with your operating system’s package manager.
+
+  You can verify that Python is installed by typing `python` from your shell; you should see something like:
+
+  ```
+  Python 3.x.y
+  [GCC 4.x] on linux
+  Type "help", "copyright", "credits" or "license" for more information.
+  >>>
+  ```
+
+  ## Set up a database
+
+  This step is only necessary if you’d like to work with a “large” database engine like PostgreSQL, MariaDB, MySQL, or Oracle. To install such a database, consult the database installation information.
+
+  ## Install Django
+
+  You’ve got three options to install Django:
+
+  1. Install an official release. This is the best approach for most users.
+  2. Install a version of Django provided by your operating system distribution.
+  3. Install the latest development version. This option is for enthusiasts who want the latest-and-greatest features and aren’t afraid of running brand new code. You might encounter new bugs in the development version, but reporting them helps the development of Django. Also, releases of third-party packages are less likely to be compatible with the development version than with the latest stable release.
+
+  ## Verifying
+
+  To verify that Django can be seen by Python, type `python` from your shell. Then at the Python prompt, try to import Django:
+
+  ```python
+  >>> import django
+  >>> print(django.get_version())
+  5.2
+  ```
+
+  You may have another version of Django installed.
+
+  ## That’s it!
+
+  That’s it – you can now move onto the tutorial.
+</example_item>
+
+<example_item>
+  # Products
+
+  Products are a fundamental resource in PaymentKit, representing the goods or services you offer. This section provides a comprehensive guide to managing your products using the PaymentKit Node.js SDK, including creating, retrieving, updating, listing, and deleting products.
+
+  For information on defining pricing models for your products, refer to the [Prices](/core-resources/prices) section. To manage customer information, see [Customers](/core-resources/customers).
+
+  ## Create a Product
+
+  Use the `create` method to define a new product in your PaymentKit system. You can optionally include associated prices during product creation.
+
+  **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. |
+
+  **Returns**
+
+  | Name | Type | Description |
+  |---|---|---|
+  | `product` | `TProductExpanded` | The newly created product object, including expanded details. |
+
+  **Example**
+
+  ```javascript
+  import payment from '@blocklet/payment-js';
+
+  async function createNewProduct() {
+    try {
+      const product = await payment.products.create({
+        name: 'Premium Service Plan',
+        description: 'Access to all premium features and support.',
+        type: 'service',
+        prices: [
+          {
+            type: 'recurring',
+            unit_amount: '19.99',
+            currency_id: 'usd_xxxxxx', // Replace with your currency ID
+            recurring: {
+              interval: 'month',
+              interval_count: 1,
+            },
+          },
+        ],
+      });
+      console.log('Product created:', product.id);
+    } catch (error) {
+      console.error('Error creating product:', error.message);
+    }
+  }
+
+  createNewProduct();
+  ```
+
+  **Example Response**
+  ```
+  {
+    "id": xxxx,
+    "name": xxxx,
+  }
+  ```
+
+  This example demonstrates how to create a new product named "Premium Service Plan" with an associated monthly recurring price.
+
+  ## Retrieve a Product
+
+  Use the `retrieve` method to fetch details of a specific product by its ID.
+
+  **Parameters**
+
+  | Name | Type | Description |
+  |---|---|---|
+  | `id` | `string` | The unique identifier of the product to retrieve. |
+
+  **Returns**
+
+  | Name | Type | Description |
+  |---|---|---|
+  | `product` | `TProductExpanded` | The retrieved product object, including expanded details. |
+
+  **Example**
+
+  ```javascript
+  import payment from '@blocklet/payment-js';
+
+  async function getProductDetails(productId) {
+    try {
+      const product = await payment.products.retrieve(productId);
+      console.log('Product details:', product.name, product.description);
+    } catch (error) {
+      console.error(`Error retrieving product ${productId}:`, error.message);
+    }
+  }
+
+  getProductDetails('prod_xxx'); // Replace with a valid product ID
+  ```
+
+  **Example Response**
+  ```
+  {
+    "id": xxxx,
+    "name": xxxx,
+  }
+  ```
+
+  This example retrieves and logs the details of a product using its ID.
+
+  ## Update a Product
+
+  Use the `update` method to modify an existing product's details.
+
+  **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. |
+
+  **Returns**
+
+  | Name | Type | Description |
+  |---|---|---|
+  | `product` | `TProductExpanded` | The updated product object. |
+
+  **Example**
+
+  ```javascript
+  import payment from '@blocklet/payment-js';
+
+  async function updateProductDescription(productId) {
+    try {
+      const updatedProduct = await payment.products.update(productId, {
+        description: 'Updated description for the premium service plan.',
+      });
+      console.log('Product updated:', updatedProduct.id, updatedProduct.description);
+    } catch (error) {
+      console.error(`Error updating product ${productId}:`, error.message);
+    }
+  }
+
+  updateProductDescription('prod_xxx'); // Replace with a valid product ID
+  ```
+
+  **Example Response**
+  ```
+  {
+    "id": xxxx,
+    "name": xxxx,
+  }
+  ```
+
+  This example updates the description of an existing product.
+
+  ## List Products
+
+  Use the `list` method to retrieve a paginated list of products. You can filter the results by various criteria.
+
+  **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. |
+
+  **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. |
+
+  **Example**
+
+  ```javascript
+  import payment from '@blocklet/payment-js';
+
+  async function listActiveProducts() {
+    try {
+      const products = await payment.products.list({
+        active: true,
+        pageSize: 10,
+        order: 'name:ASC',
+      });
+      console.log(`Found ${products.total} active products:`);
+      products.data.forEach(product => {
+        console.log(`- ${product.name} (ID: ${product.id})`);
+      });
+    } catch (error) {
+      console.error('Error listing products:', error.message);
+    }
+  }
+
+  listActiveProducts();
+  ```
+
+  **Example Response**
+  ```
+  {
+    "page": 1,
+    "pageSize": 20,
+    "total": 100,
+    "data": [
+      {
+        "id": xxx,
+        "name": xxx,
+      }
+    ]
+  }
+  ```
+
+  This example lists the first 10 active products, sorted alphabetically by name.
+
+  ## Search Products
+
+  Use the `search` method to find products based on a general search query. This is useful for free-text searches across product fields.
+
+  **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). |
+
+  **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. |
+
+  **Example**
+
+  ```javascript
+  import payment from '@blocklet/payment-js';
+
+  async function searchProducts(searchTerm) {
+    try {
+      const searchResults = await payment.products.search({
+        query: searchTerm,
+        pageSize: 5,
+      });
+      console.log(`Found ${searchResults.total} products matching "${searchTerm}":`);
+      searchResults.data.forEach(product => {
+        console.log(`- ${product.name} (ID: ${product.id})`);
+      });
+    } catch (error) {
+      console.error(`Error searching for products with "${searchTerm}":`, error.message);
+    }
+  }
+
+  searchProducts('service');
+  ```
+
+  **Example Response**
+  ```
+  {
+    "page": 1,
+    "pageSize": 20,
+    "total": 100,
+    "data": [
+      {
+        "id": xxx,
+        "name": xxx,
+      }
+    ]
+  }
+  ```
+
+  This example searches for products containing the term "service" and logs the results.
+
+  ## Archive a Product
+
+  Use the `archive` method to set a product's status to archived. Archived products are typically not visible or purchasable but are retained in the system.
+
+  **Parameters**
+
+  | Name | Type | Description |
+  |---|---|---|
+  | `id` | `string` | The unique identifier of the product to archive. |
+
+  **Returns**
+
+  | Name | Type | Description |
+  |---|---|---|
+  | `product` | `TProduct` | The archived product object. |
+
+  **Example**
+
+  ```javascript
+  import payment from '@blocklet/payment-js';
+
+  async function archiveProduct(productId) {
+    try {
+      const archivedProduct = await payment.products.archive(productId);
+      console.log(`Product ${archivedProduct.id} has been archived.`);
+    } catch (error) {
+      console.error(`Error archiving product ${productId}:`, error.message);
+    }
+  }
+
+  archiveProduct('prod_xxx'); // Replace with a valid product ID
+  ```
+
+  **Example Response**
+  ```
+  {
+    "id": xxxx,
+    "name": xxxx,
+  }
+  ```
+
+  This example archives a specified product.
+
+  ## Delete a Product
+
+  Use the `del` method to permanently delete a product from your PaymentKit system. Use with caution, as this action is irreversible.
+
+  **Parameters**
+
+  | Name | Type | Description |
+  |---|---|---|
+  | `id` | `string` | The unique identifier of the product to delete. |
+
+  **Returns**
+
+  | Name | Type | Description |
+  |---|---|---|
+  | `product` | `TProduct` | The deleted product object. |
+
+  **Example**
+
+  ```javascript
+  import payment from '@blocklet/payment-js';
+
+  async function deleteProduct(productId) {
+    try {
+      const deletedProduct = await payment.products.del(productId);
+      console.log(`Product ${deletedProduct.id} has been permanently deleted.`);
+    } catch (error) {
+      console.error(`Error deleting product ${productId}:`, error.message);
+    }
+  }
+
+  deleteProduct('prod_xxx'); // Replace with a valid product ID
+  ```
+
+  **Example Response**
+  ```
+  {
+    "id": xxxx,
+    "name": xxxx,
+  }
+  ```
+
+  This example permanently deletes a specified product.
+
+  ---
+
+  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.
+
+</example_item>
+
+<bad_example>
+  - 错误示例：
+    - A["开始：`blocklet server upgrade`"]
+    - A -- "执行命令（例如 `start`、`stop`）" --> B
+</bad_example>
+
+<good_example>
+  - 正确示例：
+    - A["开始：blocklet server upgrade"]
+    - A -- "执行命令（例如 start、stop）" --> B
+</good_example>
+</example>

package/prompts/document/detail-generator.md

@@ -0,0 +1,95 @@
+
+<document_rules>
+文档类信息生成规则：
+- 如果当前部分是存在子文档，当前文档只展示简要的内容，引导用户到子文档中查看详细的内容
+- 每个部分文档需要包含：标题、开头介绍、多个 section 介绍、结尾总结
+- 文档标题中已经主题 API 名称，文档中的小标题不需要重复显示，直接显示子 API 名称
+- 开头介绍包含关联文档的链接，使用 markdown 的 link 格式，引导用户阅读相关的文档
+- 结尾总结中包含下一步阅读文档的链接，使用 markdown 的 link 格式，引导用户阅读相关的文档
+- 确保 markdown 链接格式正确，示例：[Next Chapter Title](next_chapter_path)
+- **确保 next_chapter_path 是外部地址或结构规划中存在的 path**, 直接使用结构规划中 path 绝对路径
+- 如果 dataSources 中包含相关的第三方链接，在文档详情中可以在相关的地方关联这些第三方链接
+- 每个 section 需要包含：标题、介绍、代码示例、响应数据示例、示例说明，示例说明跟在示例代码后描述，不需要‘示例说明’这样的小标题
+- 确保文档中的内容是完整、连贯的，用户可以跟着文档一步步顺利执行
+- 说明要尽可能的详细，如果存在配置项或参数，需要解释每个配置项或参数的含义，如果参数有多个可选值，每种可选值需要解释其含义，并尽可能配上代码示例
+- 参数优先使用 markdown 中的 table 来展示，让内容看上去更整齐，容易阅读
+- 接口/方法调用的说明必须包含 **响应数据示例** 
+- 使用 mermaid 图表解释复杂的概念 (```mermaid``` format)，让页面内容展示形式更丰富
+  - 使用 `flowchart` 图表解释概念之间的关系
+  - 使用 `sequenceDiagram` 图表解释调用、执行的流程，
+  - **确保 mermaid `flowchart` 和 `graph` 图表中所有节点的 label 都使用 " 包裹**，使用简单文案描述，不包含任何特殊符号，示例：A["@abc"]、B("AIGNE")、C{"@aigne/core"}
+  - **确保 mermaid `flowchart` 和 `graph` 图表中所有节点连线上的描述都使用 " 包裹**，使用简单文案描述，不包含任何特殊符号，示例： E -- "Yes, Cache Hit" --> F["Serve Cached HTML"];
+  - **确保 mermaid`sequenceDiagram` 图表所有节点名不使用 " 包裹，示例：`participant AIGNE as AIGNE Engine`
+- 更多的使用 table 、mermaid 图表来解释信息，过长的文本描述会让用户阅读有压力
+- 概览部分，必须包含 mermaid 图表，展示产品的架构图
+- 对输出的 markdown 进行检查，确认输出内容完整，table 、mermaid 信息完整并且格式正确
+- **确保内容完整性**：在生成任何文档内容，特别是代码块（如 Mermaid、JSON、代码等）时，必须确保其是**完整且语法正确**的。在输出完成后，必须进行一次**自我检查**，确认所有的代码块、列表、表格等都已完全闭合且没有中途截断。
+- **代码块原子性**：将每个代码块（例如 ```mermaid ... ```）视为一个**不可分割的原子单元**。必须一次性完整生成，从开始标记（```mermaid）到结束标记（```）之间的所有内容都不能省略或截断。
+- **确保 Markdown 语法**：Markdown 格式正确，特别是表格的分隔线（例如 `|---|---|---|`），需要与表格数据列数一致。
+- README 文件只做参考，你需要从代码中获取最新、最完整的信息
+</document_rules>
+
+<TONE_STYLE>
+- Documentation should be plain, rigorous and accurate, avoiding grandiose or empty vocabulary
+- You are writing for humans, not algorithms
+- Clarity and Flow
+  - Target a Flesch Reading Ease score near 80
+  - Vary sentence length to maintain rhythm and attention
+  - Use natural transitions and rhetorical cues to guide the reader
+  - Favor active voice, but mix in passive when needed
+  - Mimic natural human quirks: slight redundancy, mild digressions, and spontaneous tone
+- Voice Characteristics
+  - Use contractions and idioms sparingly to maintain an informal, yet credible tone
+  - Blend technical precision with relatable language
+  - Be direct: say what happened, why it matters, and how it helps
+
+Example Tone Transformations
+❌ "We’re thrilled to announce our most powerful update yet…" 
+✅ "You can now include location and timestamp metadata for each claim, enabling audit-ready transparency."
+
+❌ "Unlock the future of verification." 
+✅ "This release makes real-world claims independently verifiable across sectors."
+</TONE_STYLE>
+
+<WORDS_PHRASES_TO_AVOID>
+
+Do not use promotional fluff or filler emotion. Avoid the following unless quoting a user or citing feedback: Do not use words and phrases that are similar to following if you are asked to output in language other than English.
+
+<emotion-words>
+  excited
+  thrilled
+  delighted
+  proud to announce
+  happy to share
+  Overused Adjectives:
+  powerful
+  seamless
+  revolutionary
+  robust
+  amazing
+  significant
+  transformative
+  innovative
+  disruptive
+  groundbreaking
+</emotion-words>
+
+<generic-hype-verbs>
+  unlock
+  unleash
+  empower
+  elevate
+  reimagine
+  transform
+  Empty Marketing Phrases:
+  in today's world
+  at the end of the day
+  best practices
+  end-to-end
+  game changer
+  cutting edge
+</generic-hype-verbs>
+
+➡️ Instead, focus on concrete outcomes and observable benefits. 
+Example: “Now includes location and timestamp for each field report” is better than “a powerful new update.”
+</WORDS_PHRASES_TO_AVOID>

package/prompts/document/structure-example.md

@@ -0,0 +1,98 @@
+<example>
+下面是一些优质的文档结构规划供你参考：
+
+示例 A：开源前端框架 Docs
+```yaml
+- 概览
+- 快速开始
+  - 安装
+  - 第一个组件
+  - 运行本地示例
+- 基础概念
+  - 响应式原理
+  - 组件生命周期
+  - 状态管理
+- 教程
+  - Todo List 全流程
+  - SSR 博客示例
+- 任务指引
+  - 如何集成第三方 UI 库
+  - 如何做代码拆分
+  - 如何做单元测试
+- API 参考
+  - 核心包
+  - 路由模块
+  - CLI
+- 示例代码
+  - JavaScript
+  - TypeScript
+- 版本与迁移
+  - v3 → v4 迁移指南
+  - 发布日志
+- 贡献与社区
+  - 贡献指南
+  - 讨论区链接
+```
+
+示例 B：云服务 REST API Docs
+```yaml
+- Overview
+- Get Started
+  - Create Account
+  - Obtain API Key
+  - Hello World (cURL)
+- Concepts
+  - Authentication Model
+  - Rate Limits
+  - Error Handling
+- Tutorials
+  - Build a Serverless Image Resizer
+  - Streaming Analytics Pipeline
+- How-to Guides
+  - Upload Large Files
+  - Rotate API Keys
+  - Monitor Usage with Grafana
+- API Reference
+  - Authentication
+  - Storage
+  - CDN
+- SDK Examples
+  - Python
+  - Go
+  - JavaScript
+- Release Notes
+- Troubleshooting & FAQ
+- Security & Best Practices
+
+```
+
+示例 C：命令行工具 Docs（多平台发行版）
+```yaml
+- 概览
+- 快速开始
+  - 二进制下载
+  - Homebrew 安装
+  - Windows Scoop 安装
+- 核心概念
+  - Configuration 文件结构
+  - 插件系统
+- 教程
+  - 构建并部署一个静态站点
+  - 使用插件扩展功能
+- 指令参考
+  - init
+  - build
+  - deploy
+  - plugin
+- 故障排查
+  - 常见错误代码
+  - Debug 日志指南
+- 性能与安全
+- 版本与升级
+  - Changelog
+  - Breaking Changes
+- 贡献
+
+```
+
+</example>

package/prompts/document/structure-getting-started.md

@@ -0,0 +1,10 @@
+<document_rules>
+基于提供的数据源，规划一份 Getting Started 文档结构规划：
+  - 整个结构规划是完整且连续的，用户跟着文档一步步操作，可以完成一个可运行示例
+  - 每个部分文档完成一个相对完整的步骤，避免单个部分文档过长，用户阅读有压力
+  - 根据需要提供参考的命令行、代码，方便用户跟着文档执行
+  - 基于一个有趣的场景来设计 Getting Started 文档
+  - 在示例中介绍项目的核心概念，目标是用户跟随文档完成示例后，对项目有一个比较完整清晰的理解
+  - 尽可能包含项目的功能、核心概念
+
+</document_rules>

package/prompts/document/structure-planning.md

@@ -0,0 +1,17 @@
+
+<document_rules>
+文档类结构规划规则：
+  - 对于结构规划需要生成完整的文档结构，覆盖源码中的所有功能，并提供代码示例的示例。
+  - 基于提供的源代码进行结构规划，确保规划的节点都有足够的信息展示
+  - 相关的内容要聚合到同一个部分文档中，不要分散到多个部分文档中，避免内容在多个部分文档中重复
+  - 结构规划要精炼，避免同一个功能被拆为了多个部分，当内容足够复杂，放在一起展示过长影响用户阅读时，考虑拆出子层级
+  - **第一层 <= 7 项**，层级 <= 3 级；同一层使用统一语义（动词时态、名词单复数）
+  - 如果当前部分是存在子文档，当前文档只展示简要的内容，引导用户到子文档中查看详细的内容
+  - 总是在一开始包含下列内容：
+    - Overview：简要说明产品能解决什么，产品能提供什么，产品的结构信息，让用户能快速有一个全面的认识，给出下一步的入口，引导用户阅读
+    - Getting Started：内容包含安装、最小运行示例，让用户用通过一部分文档，在很短的时间就能跑通一个最简单的示例
+  - 标题中不需要包含产品名称，显示更加精简
+  - 'Overview' 和 'Getting Started' 章节应该引用所有源代码，方便写出准确全面的介绍
+  - **'Getting Started' 下不需要拆分子章节**
+  - 每个部分文档都应该尽可能多的引用相关的源代码，来确保生成文档更详细准确，对于你不确定的项，优先添加引用
+</document_rules>