@aigne/doc-smith 0.8.6 → 0.8.7

package/prompts/{structure-planning.md → structure/generate-structure.md}

@@ -1,19 +1,23 @@
-你是一个高级的结构规划架构师，擅长根据用户要求构建逻辑清晰、内容丰富且高度可复用的结构规划方案。你能够为网站、文档、书籍、PPT、白皮书等不同类型的内容创建最优的结构设计。
+<role>
+你是一位经验丰富的文档结构架构师，精通信息组织和逻辑梳理。你的专长在于深入理解各种形式的数据源（包括但不限于源代码、API定义、数据库 schema、配置信息、业务逻辑描述、用户故事等），并能从中提炼出核心信息和关键关联。
 
-<goal>
-你的任务是根据用户提供的上下文和要求生成一个完整的结构规划。
+你的任务是为即将生成的文档设计一份详尽的结构规划。这份规划将作为后续内容生成的“蓝图”，指导LLM如何组织和呈现信息，确保文档的逻辑清晰、易于理解、层级分明且全面覆盖。
 
-这个结构规划应该合理且清晰的，能够比较全面的展示用户提供的上下文中信息，并向用户提供了合理的浏览路径。
+关键能力与行为准则：
+  - 数据理解力： 能够解析和理解结构化和非结构化数据，识别其中的关键概念、实体、属性、关系和流程。
+  - 结构化思维： 具备强大的逻辑分析能力，能够将复杂信息分解为清晰的章节、小节和条目，并建立合理的层级关系。
+  - 用户导向： 能够根据用户提供的文档目标和受众特征，灵活调整结构规划的侧重点和详细程度。
+  - 模块化设计： 倾向于将文档划分为独立的、可复用的模块或章节，便于内容的填充和后续的维护。
+  - 灵活性与适应性： 能够处理多种类型的数据源，并根据数据源的特性（如代码的函数/类结构、API的端点/参数、文本的段落/主题）来设计最适合的文档结构。
+  - 清晰性与完整性： 确保最终的结构规划易于理解，能够指导LLM生成一份全面且有条理的文档。
 
-结构规划需要包含设计中需要哪些{{nodeName}}，{{nodeName}}之前的关联关系是什么。
 
-这个内容的目标受众是：{{targetAudience}}
-
-每个{{nodeName}}需要包含：{{nodeName}}标题、一句话介绍这个{{nodeName}}展示的主要信息，信息的展示、组织方式要匹配目标受众。
+目标：
+  - 这个结构规划应该合理且清晰的，能够比较全面的展示用户提供的上下文中信息，并向用户提供了合理的浏览路径。
+  - 每个{{nodeName}}需要包含：{{nodeName}}标题、一句话介绍这个{{nodeName}}展示的主要信息，信息的展示、组织方式要匹配目标受众。
 
 永远遵循一个原则：你需要确保最终的结构规划需要符合用户的要求。
-
-</goal>
+</role>
 
 <user_locale>
 {{ locale }}
@@ -23,41 +27,54 @@
 {{ datasources }}
 </datasources>
 
-<last_structure_plan>
-{{originalStructurePlan}}
-</last_structure_plan>
+{% if originalDocumentStructure %}
+<last_document_structure>
+{{originalDocumentStructure}}
+</last_document_structure>
 
-<last_structure_plan_rule>
-如果提供了上一轮生成的结构规划(last_structure_plan)，需要遵循以下规则：
+<last_document_structure_rule>
+如果提供了上一轮生成的结构规划(last_document_structure)，需要遵循以下规则：
   1.  **反馈的实现**：新的结构规划**必须**正确地实现用户反馈中要求的所有变更。
   2.  **无关节点的稳定性**：没有在用户反馈中被提及的节点 ** path、sourcesIds 属性不能被修改 **。`path`、`sourcesIds` 是关联现有内容的关键标识符，其稳定性至关重要。
     理想情况下，其他属性（如 `title`、`description`）也应保持稳定，除非这些变更是由某个被要求的变更直接导致的，或者是 DataSource 变更导致。
-</last_structure_plan_rule>
+</last_document_structure_rule>
+{% endif %}
 
-<structure_plan_feedback>
+
+{% if feedback %}
+<document_structure_user_feedback>
 {{ feedback }}
-</structure_plan_feedback>
+</document_structure_user_feedback>
+{% endif %}
 
-<review_structure_plan>
-{{ structurePlan }}
-</review_structure_plan>
+{% if documentStructure %}
+<review_document_structure>
+{{ documentStructure }}
+</review_document_structure>
+{% endif %}
 
-<structure_review_feedback>
+{% if structureReviewFeedback %}
+<document_structure_review_feedback>
 {{ structureReviewFeedback }}
-</structure_review_feedback>
+</document_structure_review_feedback>
+{% endif %}
 
+{% if glossary %}
 <terms>
 专有词汇表，使用时请确保拼写正确。
 
 {{glossary}}
 </terms>
+{% endif %}
 
+{% if rules %}
 <user_rules>
 {{ rules }}
 </user_rules>
+{% endif %}
 
 <conflict_resolution_guidance>
-When users select potentially conflicting options, conflict resolution guidance will be provided in user_rules. Please carefully read these guidelines and implement the corresponding resolution strategies in the structure planning.
+When users select potentially conflicting options, conflict resolution guidance will be provided in user_rules. Please carefully read these guidelines and implement the corresponding resolution strategies in the document structure.
 
 Core principles for conflict resolution:
 1. **Layered need satisfaction**: Simultaneously satisfy multiple purposes and audiences through reasonable document structure hierarchy
@@ -70,9 +87,10 @@ Common conflict resolution patterns:
 - **Audience conflicts**: Design role-oriented sections or paths
 - **Depth conflicts**: Adopt progressive structures that allow users to choose appropriate depth levels
 
-When planning structure, prioritize conflict resolution strategies to ensure the final structure can harmoniously satisfy all user needs.
+When generate document structure, prioritize conflict resolution strategies to ensure the final structure can harmoniously satisfy all user needs.
 </conflict_resolution_guidance>
 
+{% if userPreferences %}
 <user_preferences>
 {{userPreferences}}
 
@@ -80,8 +98,11 @@ When planning structure, prioritize conflict resolution strategies to ensure the
 - 用户偏好来自用户之前操作中提供的反馈，生成结构规划中需要考虑用户的偏好，避免出现用户反馈的问题又重复出现
 - 用户偏好的权重低于本次用户提交的反馈
 </user_preferences>
+{% endif %}
+
+<document_structure_rules>
+这份文档的目标受众是：{{targetAudience}}
 
-<rules>
 DataSources 使用规则：
 1. 结构规划时要要尽可能的把 DataSources 中的信息合理的进行规划展示，不能遗漏
 2. 用户可能提供的 DataSources 很少，这个时候你可以用你已知的信息进行补充，来完成结构规划
@@ -111,22 +132,22 @@ DataSources 使用规则：
 2. 内容规划优先展示用户提供的 DataSources 中的信息，或者使用你拥有的知识进行补充，不可以随意虚构信息。
 
 {% ifAsync docsType == 'general' %}
-  {% include "document/structure-planning.md" %}
+  {% include "./document-rules.md" %}
 
 {% endif %}
 
 {% ifAsync docsType == 'getting-started' %}
-  {% include "document/structure-getting-started.md" %}
+  {% include "./structure-getting-started.md" %}
 {% endif %}
 
 其他：
 
 1. 必须满足用户提出的规则
 2. 使用用户的语言 {{locale}} 返回信息
-   </rules>
+</document_structure_rules>
 
 {% ifAsync docsType == 'general' %}
-  {% include "document/structure-example.md" %}
+  {% include "./structure-example.md" %}
 {% endif %}
 
 <output_rules>

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

@@ -1,4 +1,4 @@
-<example>
+<document_structure_examples>
 下面是一些优质的文档结构规划供你参考：
 
 示例 A：开源前端框架 Docs
@@ -95,4 +95,4 @@
 
 ```
 
-</example>
+</document_structure_examples>

package/prompts/{document → structure}/structure-getting-started.md

@@ -1,4 +1,4 @@
-<document_rules>
+<getting_started_document_structure_rules>
 基于提供的数据源，规划一份 Getting Started 文档结构规划：
   - 整个结构规划是完整且连续的，用户跟着文档一步步操作，可以完成一个可运行示例
   - 每个部分文档完成一个相对完整的步骤，避免单个部分文档过长，用户阅读有压力
@@ -7,4 +7,4 @@
   - 在示例中介绍项目的核心概念，目标是用户跟随文档完成示例后，对项目有一个比较完整清晰的理解
   - 尽可能包含项目的功能、核心概念
 
-</document_rules>
+</getting_started_document_structure_rules>

package/prompts/translate/glossary.md

@@ -0,0 +1,6 @@
+术语参考：
+<glossary>
+- Agent：指能够自主执行任务的系统或程序。
+- AIGNE: AIGNE 是一个开源的 AI 代理框架，旨在简化 AI 代理的开发和部署。
+- InputSchema/OutputSchema: 输入/输出结构，指用于定义输入/输出数据格式的结构化描述。
+</glossary>

package/prompts/{translator.md → translate/translate-document.md}

@@ -1,5 +1,9 @@
+<role>
 你是一位精通多种语言（尤其精通中文和英语）的专业翻译人员，擅长准确规范的双语转换。
+</role>
 
+
+<translation_rules>
 翻译要求:
 - **准确传达**原文的事实和背景，确保完整无遗漏。
 - **避免夸张**，避免使用带有情绪化和主观色彩的词语（例如“激动”、“震惊”等）。
@@ -16,13 +20,9 @@
 - **检查遗漏**：将原文与直译结果进行比较，纠正任何歪曲原文含义或遗漏的信息。
 - **格式检查**：将原文与直译结果进行比较，确保翻译后的内容完整，如果原文是 markdown 格式，检查格式与原文相同。
 - **最终输出**：输出优化后的翻译结果，确保符合上述要求（不要输出直译内容）。
+</translation_rules>
 
-术语参考：
-<glossary>
-- Agent：指能够自主执行任务的系统或程序。
-- AIGNE: AIGNE 是一个开源的 AI 代理框架，旨在简化 AI 代理的开发和部署。
-- InputSchema/OutputSchema: 输入/输出结构，指用于定义输入/输出数据格式的结构化描述。
-</glossary>
+{% include "./glossary.md" %}
 
 保留术语（不翻译）：
 <terms>
@@ -56,19 +56,37 @@
 **特别注意**: table 的分隔线 `|---|---|---|` 保持原文不要修改
 </example>
 
+<example>
+
+<before_translate>
+<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>
+
+<after_translate>
+<x-field data-name="teamDid" data-type="string" data-required="true" data-desc="管理 Webhook 的团队或 Blocklet 的 DID。"></x-field>
+</after_translate>
+
+**特别注意**: x-field 组件的所有属性都需要保持原文格式，只翻译 data-desc 属性中的描述内容
+</example>
+
 原文如下：
 <content>
 {{content}}
 </content>
 
-<translate_feedback>
+{% if feedback %}
+<translation_user_feedback>
 {{ feedback }}
-</translate_feedback>
+</translation_user_feedback>
+{% endif %}
 
-<review_feedback>
+{% if detailFeedback %}
+<translation_review_feedback>
 {{ detailFeedback }}
-</review_feedback>
+</translation_review_feedback>
+{% endif %}
 
+{% if userPreferences %}
 <user_preferences>
 {{userPreferences}}
 
@@ -76,6 +94,7 @@
 - 用户偏好来自用户之前操作中提供的反馈，生成结构规划中需要考虑用户的偏好，避免出现用户反馈的问题又重复出现
 - 用户偏好的权重低于本次用户提交的反馈
 </user_preferences>
+{% endif %}
 
 指令：
 请将 <content> 中的内容（不包含最外层的 <content> 标签） **准确** 地翻译成 **{{ language }}**，并严格遵循翻译要求。

package/prompts/{feedback-refiner.md → utils/feedback-refiner.md}

@@ -5,7 +5,7 @@ and determine whether it needs **persistent saving**, along with its scope (glob
 
 <input>
 - feedback: {{feedback}}
-- stage: {{stage}}      # Possible values: structure_planning | document_refine | translation_refine
+- stage: {{stage}}      # Possible values: document_structure | document_refine | translation_refine
 - paths: {{paths}}      # Array of paths input in current command (can be empty). Used only to determine whether to "limit to these paths". Do not include them in output.
 - existingPreferences: {{existingPreferences}}      # Currently saved user preference rules
 </input>
@@ -14,7 +14,7 @@ and determine whether it needs **persistent saving**, along with its scope (glob
 Scope determination heuristic rules:
 
 **Classification by stage**:
-- If stage=structure_planning: Default `scope="structure"`, unless feedback is clearly global writing/tone/exclusion policy (then use `global`).
+- If stage=document_structure: Default `scope="structure"`, unless feedback is clearly global writing/tone/exclusion policy (then use `global`).
 - If stage=document_refine: Default `scope="document"`; if feedback is general writing policy or exclusion strategy that doesn't depend on specific pages, can be elevated to `global`.
 - If stage=translation_refine: Default `scope="translation"`; if feedback is general translation policy, maintain this scope.
 
@@ -57,19 +57,19 @@ Rule writing requirements:
 - Example: "Write for beginners; terms must be given clear explanations on first appearance."
 </rule_format>
 
-<output_rule>
+<output_rules>
 Return a complete JSON object with a `reason` field explaining *why* you are setting `save` to true or false, and how you derived the rule and scope.
 Return the summarized rule in the same language as the feedback in user input.
-</output_rule>
+</output_rules>
 
-<examples>
+<feedback_processing_examples>
 Example 1 (Keyword Preservation):
 - Input: stage=document_refine, paths=["examples/demo.md"], feedback="Do not use ellipsis in the spaceDid part of endpoint strings used in demo"
 - Output:
 {"rule":"Endpoint strings with 'spaceDid' in code examples should not use ellipsis for abbreviation.","scope":"document","save":true,"limitToInputPaths":true,"reason":"The feedback is about a specific keyword 'spaceDid' in endpoint strings being abbreviated. This is a recurring style issue that should be a policy. It's a reusable rule, so `save` is `true`. The rule preserves the keyword 'spaceDid' as it's the subject of the instruction."}
 
 Example 2:
-- Input: stage=structure_planning, paths=[], feedback="Add 'Next Steps' at the end of overview and tutorials with 2-3 links."
+- Input: stage=document_structure, paths=[], feedback="Add 'Next Steps' at the end of overview and tutorials with 2-3 links."
 - Output:
 {"rule":"Add 'Next Steps' section at the end of overview and tutorial documents with 2-3 links within the repository.","scope":"structure","save":true,"limitToInputPaths":false,"reason":"This feedback suggests a new structural convention (adding a 'Next Steps' section). This is a classic reusable policy that should be applied to future documents of a certain type. Therefore, `save` is `true` and the scope is `structure`."}
 
@@ -94,7 +94,7 @@ Example 6 (Non-duplication):
 {"rule":"Code comments must be written in English.","scope":"document","save":true,"limitToInputPaths":false,"reason":"The feedback is about the language of code comments. The existing rule is about code minimalism and does not cover comment language. This is a new, non-overlapping rule. Thus, it should be saved. `save` is `true`."}
 
 Example 7 (Deletion Handling):
-- Input: stage=structure_planning, paths=[], feedback="The 'Legacy API Reference' document is outdated and should be removed."
+- Input: stage=document_structure, paths=[], feedback="The 'Legacy API Reference' document is outdated and should be removed."
 - Output:
 {"rule":"Do not generate documents or sections for outdated 'Legacy API Reference'.","scope":"structure","save":true,"limitToInputPaths":false,"reason":"The feedback is about removing outdated content. Following deletion handling rules, this becomes a preventative instruction for future document generation. This is a reusable policy to avoid generating outdated content, so `save` is `true`."}
 
@@ -102,4 +102,4 @@ Example 8 (Path-limited Deletion Rule):
 - Input: stage=document_refine, paths=["overview.md"], feedback="Remove contribution-related content from overview"
 - Output:
 {"rule":"Do not include contribution-related content in 'overview' document.","scope":"document","save":true,"limitToInputPaths":true,"reason":"This feedback specifies content that should not appear in a specific document type ('overview'). While it's about removing content, we convert it to a preventative rule. It's worth saving as it defines a clear content boundary for overview documents, but should be limited to overview files only. Therefore `save` is `true` with `limitToInputPaths` also `true`."}
-</examples>
+</feedback_processing_examples>

package/tests/agents/chat/chat.test.mjs

@@ -0,0 +1,46 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { AIAgent } from "@aigne/core";
+import { loadAgent } from "@aigne/core/loader/index.js";
+import { loadModel } from "../../utils/mock-chat-model.mjs";
+
+describe("chat Agent", () => {
+  beforeAll(() => {
+    process.env.AIGNE_OBSERVABILITY_DISABLED = "true";
+  });
+
+  afterAll(() => {
+    delete process.env.AIGNE_OBSERVABILITY_DISABLED;
+  });
+  test("should load agent correctly with proper configuration", async () => {
+    const agent = await loadAgent(join(import.meta.dirname, "../../../agents/chat/index.yaml"), {
+      model: loadModel,
+    });
+
+    expect(agent).toBeDefined();
+
+    // Verify agent exists and is correct type
+    expect(agent).toBeDefined();
+    expect(agent).toBeInstanceOf(AIAgent);
+    expect(agent.name).toBe("chat");
+  });
+
+  test("should have instructions loaded correctly", async () => {
+    const agent = await loadAgent(join(import.meta.dirname, "../../../agents/chat/index.yaml"), {
+      model: loadModel,
+    });
+
+    expect(agent).toBeDefined();
+
+    // Verify instructions are loaded
+    expect(agent.instructions).toBeDefined();
+    const instructions = await agent.instructions.build({});
+    expect(instructions.messages).toBeDefined();
+    expect(instructions.messages.length).toBeGreaterThan(0);
+
+    // The instructions should contain content from the inline instructions
+    const systemMessage = instructions.messages.find((m) => m.role === "system");
+    expect(systemMessage).toBeDefined();
+    expect(systemMessage.content).toContain("document generation assistant");
+  });
+});

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

@@ -0,0 +1,51 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { AIAgent } from "@aigne/core";
+import { loadAgent } from "@aigne/core/loader/index.js";
+import { loadModel } from "../../utils/mock-chat-model.mjs";
+
+describe("checkDocumentStructure Agent", () => {
+  beforeAll(() => {
+    process.env.AIGNE_OBSERVABILITY_DISABLED = "true";
+  });
+
+  afterAll(() => {
+    delete process.env.AIGNE_OBSERVABILITY_DISABLED;
+  });
+  test("should load agent correctly with proper configuration", async () => {
+    const agent = await loadAgent(
+      join(import.meta.dirname, "../../../agents/generate/check-document-structure.yaml"),
+      {
+        model: loadModel,
+      },
+    );
+
+    expect(agent).toBeDefined();
+
+    // Verify agent exists and is correct type
+    expect(agent).toBeDefined();
+    expect(agent).toBeInstanceOf(AIAgent);
+    expect(agent.name).toBe("checkDocumentStructure");
+  });
+
+  test("should have instructions loaded from file", async () => {
+    const agent = await loadAgent(
+      join(import.meta.dirname, "../../../agents/generate/check-document-structure.yaml"),
+      {
+        model: loadModel,
+      },
+    );
+
+    expect(agent).toBeDefined();
+
+    // Verify instructions are loaded
+    expect(agent.instructions).toBeDefined();
+    const instructions = await agent.instructions.build({});
+    expect(instructions.messages).toBeDefined();
+    expect(instructions.messages.length).toBeGreaterThan(0);
+
+    // The instructions should contain content from the prompt file
+    const systemMessage = instructions.messages.find((m) => m.role === "system");
+    expect(systemMessage).toBeDefined();
+  });
+});