Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: add prompt guides in zh and en (#1292)
Jiahui Zhouaaaedfe89b8c
diff --git a/docs/en/guides/10-prompt-guide.md b/docs/en/guides/10-prompt-guide.mdnew file mode 100644index 000000000..5649a1464--- /dev/null+++ b/docs/en/guides/10-prompt-guide.md@@ -0,0 +1,679 @@+# OpenViking Prompt Guide and Customization++This document introduces OpenViking's current prompt template system, with a focus on:++- what prompts currently exist+- which processing stage each prompt is used in+- which external capabilities or results each prompt affects+- the format requirements for template files+- how to customize prompts safely++This document only covers templates under `openviking/prompts/templates/` plus a small set of configuration items related to template loading.++## Overview++OpenViking's current prompts fall into two main groups:++1. Regular prompt templates+ - Stored under `openviking/prompts/templates/<category>/*.yaml`+ - Used to instruct the model to perform tasks such as image understanding, document summarization, memory extraction, and retrieval intent analysis+2. Memory schema templates+ - Stored under `openviking/prompts/templates/memory/*.yaml`+ - Used to define the fields, filename templates, content templates, and directory rules for a memory type++From a usage perspective, these templates mainly serve the following processing stages:++| Category | Representative template | Main purpose | Effective stage | External capability affected |+|----------|-------------------------|--------------|-----------------|------------------------------|+| `vision` | `vision.image_understanding` | Image, page, and table understanding | Resource parsing and scanned-document understanding | Image parsing, PDF page understanding, table extraction results |+| `parsing` | `parsing.context_generation` | Document structure splitting and semantic node generation | Resource ingestion and parsing | Document chapter structure, node summaries, image summaries |+| `semantic` | `semantic.document_summary` | File-level and directory-level summaries | Semantic indexing | File summaries, directory overviews, downstream retrieval quality |+| `retrieval` | `retrieval.intent_analysis` | Retrieval intent analysis and query planning | Pre-retrieval analysis | Search query planning and context recall direction |+| `compression` | `compression.memory_extraction` | Memory extraction, merging, compression, and summarization | Session commit / memory pipeline | Long-term memory extraction, session compression, memory merge results |+| `memory` | `profile` | Memory type definitions | Memory persistence and updates | The organization and final content of different memory types |+| `processing` | `processing.tool_chain_analysis` | Extracting experience from interactions or resource background | Post-processing and experience distillation | Strategy extraction, tool-chain experience, interaction learning results |+| `indexing` | `indexing.relevance_scoring` | Candidate relevance evaluation | Retrieval and indexing support | Relevance scoring quality |+| `skill` | `skill.overview_generation` | Skill information distillation | Skill resource processing | Skill retrieval summaries |+| `test` | `test.skill_test_generation` | Automatic test case generation | Test and validation support | Skill test case generation |++## Prompt Format Requirements++### Regular Prompt YAML++A regular prompt template usually contains the following fields:++```yaml+metadata:+ id: "semantic.document_summary"+ name: "Document Summary"+ description: "Generate summary for documentation files"+ version: "1.0.0"+ language: "en"+ category: "semantic"++variables:+ - name: "file_name"+ type: "string"+ description: "Input file name"+ required: true++template: |+ ...++output_schema:+ ...++llm_config:+ ...+```++Field meanings:++- `metadata`+ - Describes the template identity and category+ - `id` usually corresponds to the file path, for example `semantic.document_summary`+- `variables`+ - Defines the input variables accepted by the template+ - Common fields include `name`, `type`, `description`, `default`, `required`, and `max_length`+- `template`+ - The actual prompt body sent to the model+ - Rendered with Jinja2 variables+- `output_schema`+ - Optional+ - Describes the expected output structure so callers can constrain model output+- `llm_config`+ - Optional+ - Describes suggested model-side parameters and is not part of the prompt body itself++When writing a regular prompt, follow these guidelines:++- Keep `metadata.id` consistent with the template category and purpose+- Keep variable names stable so they stay compatible with callers+- Ensure placeholders inside `template` match the definitions in `variables`+- If the template expects structured output, specify the fields, format, and constraints clearly+- If the input is length-sensitive, control prompt size through `max_length` or upstream truncation++### Memory Schema YAML++`memory/*.yaml` files are not regular prompt text templates. They define memory types. The example below is only a schematic structure showing common fields. Whether a built-in template includes `content_template`, or whether its directory uses a subdirectory, depends on the specific memory type.++```yaml+memory_type: "profile"+description: "User profile memory"+fields:+ - name: "content"+ type: "string"+ description: "Profile content"+ merge_op: "patch"+filename_template: "profile.md"+content_template: |+ ...+directory: "viking://user/{{ user_space }}/memories/..."+enabled: true+operation_mode: "upsert"+```++Field meanings:++- `memory_type`+ - The name of the memory type+- `description`+ - The definition of the memory type and its extraction requirements+- `fields`+ - The fields included in this memory type+- `filename_template`+ - The template used to generate the file name+- `content_template`+ - The body template used when writing the memory file+- `directory`+ - The directory where this memory type is stored+- `enabled`+ - Whether this memory type is enabled+- `operation_mode`+ - The update mode of the memory type, such as `upsert`++When writing a memory schema, focus on:++- whether the field granularity is stable+- whether the filename template is predictable and searchable+- whether the directory rule matches the intended retrieval scope+- whether the merge strategy is appropriate for that memory type++## Current Prompt Template Reference++The sections below list all current templates by category. Each entry explains which processing stage it belongs to and which external capabilities it mainly affects.++When reading this section, a simple rule helps:++- For regular prompt templates, focus on `Purpose` and `Key inputs`+- For memory schemas, focus on `Purpose` and `Key fields`++### Compression++These prompts are mainly used for session compression, memory extraction, memory merging, and field compression. They are a core part of long-term memory quality.++- `compression.dedup_decision`+ - Effective stage: memory candidate deduplication and decision stage+ - Affects: long-term memory deduplication and create/merge strategy+ - Purpose: decides whether a new memory candidate should be skipped, created, or merged into existing memory+ - Key inputs: `candidate_content`, `candidate_abstract`, `candidate_overview`, `existing_memories`++- `compression.field_compress`+ - Effective stage: memory field compression stage+ - Affects: controllable length and readability of long fields such as tool memories+ - Purpose: compresses field content while preserving key information+ - Key inputs: `field_name`, `content`, `max_length`++- `compression.memory_extraction`+ - Effective stage: post-compression memory extraction stage+ - Affects: long-term memory extraction quality and downstream recall hit rate+ - Purpose: extracts memory candidates worth preserving from session summary and recent messages+ - Key inputs: `summary`, `recent_messages`, `user`, `feedback`, `output_language`++- `compression.memory_merge`+ - Effective stage: single-memory merge stage+ - Affects: content quality after updating existing memory+ - Purpose: merges existing memory with new information into a more complete version+ - Key inputs: `existing_content`, `new_content`, `category`, `output_language`++- `compression.memory_merge_bundle`+ - Effective stage: structured memory merge stage+ - Affects: merged L0/L1/L2 memory output+ - Purpose: returns merged `abstract`, `overview`, and `content` in one call+ - Key inputs: `existing_abstract`, `existing_overview`, `existing_content`, `new_abstract`, `new_overview`, `new_content`, `category`, `output_language`++- `compression.structured_summary`+ - Effective stage: session archive summary generation stage+ - Affects: archived session summaries and downstream review/retrieval quality+ - Purpose: generates a structured summary for archived sessions+ - Key inputs: `latest_archive_overview`, `messages`++### Indexing++This category is mainly used to support retrieval or indexing workflows with relevance judgments.++- `indexing.relevance_scoring`+ - Effective stage: candidate relevance evaluation stage+ - Affects: retrieval ranking and candidate filtering quality+ - Purpose: evaluates how relevant candidate content is to the user's query+ - Key inputs: `query`, `candidate`++### Memory++These YAML files define the structure of different memory types. They are not single-inference prompts. Together, they determine how user memories and agent memories are stored, updated, and used by later retrieval.++- `cases`+ - Effective stage: case-memory persistence and update stage+ - Affects: reusable problem-to-solution case accumulation+ - Purpose: defines case memory for "what problem happened and how it was solved"+ - Key fields: `case_name`, `problem`, `solution`, `content`++- `entities`+ - Effective stage: entity-memory persistence and update stage+ - Affects: long-term storage of people, projects, organizations, systems, and other entities+ - Purpose: defines the storage structure for named entities and their attributes+ - Key fields: `category`, `name`, `content`++- `events`+ - Effective stage: event-memory persistence and update stage+ - Affects: event review, timeline-aware retention, and conversation narrative recording+ - Purpose: defines structured event memory such as summaries, goals, and time ranges+ - Key fields: `event_name`, `goal`, `summary`, `ranges`++- `identity`+ - Effective stage: agent identity memory persistence stage+ - Affects: long-term consistency of the agent's identity settings+ - Purpose: defines the agent's name, persona, vibe, avatar, and self-introduction fields+ - Key fields: `name`, `creature`, `vibe`, `emoji`, `avatar`++- `patterns`+ - Effective stage: pattern-memory persistence and update stage+ - Affects: long-term accumulation of reusable workflows and methods+ - Purpose: defines pattern memory for "under what circumstances to follow what process"+ - Key fields: `pattern_name`, `pattern_type`, `content`++- `preferences`+ - Effective stage: preference-memory persistence and update stage+ - Affects: user preference recall and downstream personalization behavior+ - Purpose: defines user preference memory under different topics+ - Key fields: `user`, `topic`, `content`++- `profile`+ - Effective stage: user profile memory persistence and update stage+ - Affects: long-term storage of user profile, work background, and stable attributes+ - Purpose: defines the storage structure for "who the user is"+ - Key fields: `content`++- `skills`+ - Effective stage: skill-usage memory persistence and update stage+ - Affects: skill usage statistics, experience accumulation, and recommended workflows+ - Purpose: defines skill usage counts, success rates, best-fit scenarios, and related information+ - Key fields: `skill_name`, `total_executions`, `success_count`, `fail_count`, `best_for`, `recommended_flow`++- `soul`+ - Effective stage: agent soul memory persistence stage+ - Affects: the agent's core boundaries, continuity, and long-term identity stability+ - Purpose: defines the agent's core truths, boundaries, vibe, and continuity+ - Key fields: `core_truths`, `boundaries`, `vibe`, `continuity`++- `tools`+ - Effective stage: tool-usage memory persistence and update stage+ - Affects: tool usage experience, optimal parameters, and failure pattern accumulation+ - Purpose: defines the storage structure for tool call statistics and tool-usage experience+ - Key fields: `tool_name`, `static_desc`, `call_count`, `success_time`, `when_to_use`, `optimal_params`++### Parsing++These prompts are mainly used to convert raw resource content into structured nodes, chapters, summaries, or image overviews that are easier to retrieve and understand.++- `parsing.chapter_analysis`+ - Effective stage: long-document chapter splitting stage+ - Affects: document chapter structure and page organization+ - Purpose: analyzes document content and splits it into a reasonable chapter structure+ - Key inputs: `start_page`, `end_page`, `total_pages`, `content`++- `parsing.context_generation`+ - Effective stage: document node semantic generation stage+ - Affects: node abstract/overview quality and downstream retrieval matching+ - Purpose: generates shorter, retrieval-friendly semantic titles, abstracts, and overviews for text nodes+ - Key inputs: `title`, `content`, `children_info`, `instruction`, `context_type`, `is_leaf`++- `parsing.image_summary`+ - Effective stage: image node summarization stage+ - Affects: semantic overviews of image resources and downstream retrieval+ - Purpose: generates a concise summary for image content+ - Key inputs: `context`++- `parsing.semantic_grouping`+ - Effective stage: semantic grouping and splitting stage+ - Affects: document node granularity and content chunking quality+ - Purpose: decides whether content should be merged or split based on semantics+ - Key inputs: `items`, `threshold`, `mode`++### Processing++These prompts are mainly used to distill strategies or experience from interaction records, tool chains, and resource background. They are used for post-processing and knowledge accumulation rather than direct one-turn user answering.++- `processing.interaction_learning`+ - Effective stage: post-interaction experience extraction stage+ - Affects: reusable interaction experience and distillation of effective resources and successful skills+ - Purpose: extracts reusable experience from interaction records+ - Key inputs: `interactions_summary`, `effective_resources`, `successful_skills`++- `processing.strategy_extraction`+ - Effective stage: post-resource-addition strategy extraction stage+ - Affects: structured extraction and reuse of resource background intent+ - Purpose: extracts usage strategies from the reason, instruction, and abstract associated with resource addition+ - Key inputs: `reason`, `instruction`, `abstract`++- `processing.tool_chain_analysis`+ - Effective stage: tool-chain analysis stage+ - Affects: tool combination pattern recognition and tool experience accumulation+ - Purpose: analyzes tool call chains and identifies valuable usage patterns+ - Key inputs: `tool_calls`++### Retrieval++These prompts are mainly used to understand user intent before retrieval and decide the query plan and context type.++- `retrieval.intent_analysis`+ - Effective stage: pre-retrieval intent analysis stage+ - Affects: retrieval query planning, recall direction, and search quality across different context types+ - Purpose: generates a retrieval plan using compressed summary, recent messages, and the current message+ - Key inputs: `compression_summary`, `recent_messages`, `current_message`, `context_type`, `target_abstract`++### Semantic++These prompts are mainly used to generate file-level and directory-level summaries and are an important part of semantic indexing.++- `semantic.code_ast_summary`+ - Effective stage: AST skeleton summarization for large code files+ - Affects: code file summaries, code retrieval, and structural understanding+ - Purpose: generates code summaries from an AST skeleton instead of the full source+ - Key inputs: `file_name`, `skeleton`, `output_language`++- `semantic.code_summary`+ - Effective stage: code file summarization stage+ - Affects: semantic indexing for code files, code retrieval, and understanding results+ - Purpose: generates summaries for code files with a focus on structure, functions, classes, and key logic+ - Key inputs: `file_name`, `content`, `output_language`++- `semantic.document_summary`+ - Effective stage: documentation file summarization stage+ - Affects: document summaries, document retrieval, and overview quality+ - Purpose: generates summaries for Markdown, text, RST, and similar documentation files+ - Key inputs: `file_name`, `content`, `output_language`++- `semantic.file_summary`+ - Effective stage: generic file summarization stage+ - Affects: directory indexing and generic file retrieval quality+ - Purpose: generates a summary for a single file as upstream input for directory abstract/overview generation+ - Key inputs: `file_name`, `content`, `output_language`++- `semantic.overview_generation`+ - Effective stage: directory overview generation stage+ - Affects: directory overviews, hierarchical retrieval, and navigation experience+ - Purpose: generates a directory-level overview from file summaries and child directory abstracts+ - Key inputs: `dir_name`, `file_summaries`, `children_abstracts`, `output_language`++### Skill++These prompts are mainly used to compress Skill content into summaries suitable for retrieval and reuse.++- `skill.overview_generation`+ - Effective stage: Skill content processing stage+ - Affects: Skill retrieval summaries and Skill discovery quality+ - Purpose: extracts key retrieval information from a Skill's name, description, and content+ - Key inputs: `skill_name`, `skill_description`, `skill_content`++### Test++These prompts are mainly used to help generate test cases.++- `test.skill_test_generation`+ - Effective stage: Skill testing support stage+ - Affects: Skill scenario test design and validation sample generation+ - Purpose: generates test cases from the names and descriptions of multiple Skills+ - Key inputs: `skills_info`++### Vision++These prompts are mainly used for image, page, table, and multimodal document analysis, and directly affect image parsing and scanned-document understanding.++- `vision.batch_filtering`+ - Effective stage: multi-image batch filtering stage+ - Affects: keep/drop decisions for images in multi-image document understanding+ - Purpose: determines in batch whether multiple images are worth including in document understanding+ - Key inputs: `document_title`, `image_count`, `images_info`++- `vision.image_filtering`+ - Effective stage: single-image filtering stage+ - Affects: whether an image enters downstream understanding workflows+ - Purpose: determines whether a single image is meaningful for document understanding+ - Key inputs: `document_title`, `context`++- `vision.image_understanding`+ - Effective stage: image understanding stage+ - Affects: image parsing results and the quality of image `abstract`, `overview`, and `detail_text`+ - Purpose: uses the VLM to generate three-layer information for an image+ - Key inputs: `instruction`, `context`++- `vision.page_understanding`+ - Effective stage: scanned-page understanding stage+ - Affects: scanned PDF page understanding and downstream semantic results+ - Purpose: understands a single image-based document page+ - Key inputs: `instruction`, `page_num`++- `vision.page_understanding_batch`+ - Effective stage: multi-page batch understanding stage+ - Affects: efficiency and consistency when understanding scanned pages in batch+ - Purpose: batch-understands multiple image-based document pages+ - Key inputs: `page_count`, `instruction`++- `vision.table_understanding`+ - Effective stage: table understanding stage+ - Affects: table-image parsing, table summaries, and structural understanding+ - Purpose: analyzes a table image and generates three-layer information+ - Key inputs: `instruction`, `context`++- `vision.unified_analysis`+ - Effective stage: unified multimodal analysis stage+ - Affects: parsing results for complex documents that include images, tables, and chapters+ - Purpose: batch-analyzes document images, tables, and chapter-related information+ - Key inputs: `title`, `instruction`, `reason`, `content_preview`, `image_count`, `images_section`, `table_count`, `tables_section`++## How to Customize Prompts++OpenViking supports two main customization patterns:++1. Override regular prompt templates+2. Extend memory schemas++Before going into the specific methods, you can use the following table to judge change risk:++| Change type | Risk level | Notes |+|-------------|------------|-------|+| Changing prompt wording, adding examples, adjusting tone | Low | Usually only changes model behavior style and does not change the caller contract |+| Changing output style, extraction preference, or summary granularity | Medium | Changes result distribution and should be revalidated against the target capability |+| Changing variable names, output structure, or memory field names | High | Easy to break compatibility with callers or parsing logic |+| Changing `directory`, `filename_template`, or `merge_op` | Very high | Directly changes memory storage location, organization, and update behavior |++### Override Regular Prompt Templates++Applicable when:++- you want to adjust memory extraction preferences+- you want to change summarization style+- you want image understanding output to be more detailed or more concise+- you want to change retrieval intent planning behavior++Available configuration:++- `prompts.templates_dir`+- environment variable `OPENVIKING_PROMPT_TEMPLATES_DIR`++Load priority:++1. Explicitly provided template directory+2. Environment variable `OPENVIKING_PROMPT_TEMPLATES_DIR`+3. `prompts.templates_dir` in `ov.conf`+4. Built-in template directory `openviking/prompts/templates/`++In other words, regular prompt customization works by checking the custom directory first and falling back to the built-in template when the same relative path is not found.++Recommended approach:++1. Copy the target file from the built-in template directory first+2. Keep the same category directory and file name+3. Only modify the prompt body or output requirements+4. Avoid changing variable names that callers already depend on++Example directory:++```text+custom-prompts/+├── compression/+│ └── memory_extraction.yaml+├── retrieval/+│ └── intent_analysis.yaml+└── semantic/+ └── document_summary.yaml+```++Example configuration:++```json+{+ "prompts": {+ "templates_dir": "/path/to/custom-prompts"+ }+}+```++Or:++```bash+export OPENVIKING_PROMPT_TEMPLATES_DIR=/path/to/custom-prompts+```++Impact examples:++- Modifying `compression.memory_extraction`+ - mainly affects the memory extraction stage+ - ultimately affects long-term memory quality and downstream recall results+- Modifying `retrieval.intent_analysis`+ - mainly affects pre-retrieval query planning+ - ultimately affects search direction and recall quality+- Modifying `semantic.document_summary`+ - mainly affects document summarization+ - ultimately affects document indexing and summary output++### Extend Memory Schemas++Applicable when:++- you want to add a new business-specific memory type+- you want to adjust the field structure of an existing memory type+- you want to change memory storage directories or filename templates++Available configuration:++- `memory.custom_templates_dir`++Loading behavior:++- Built-in memory schemas are loaded first+- If `memory.custom_templates_dir` is configured, schemas in that directory are loaded afterward+- As a result, memory customization behaves more like extension and supplementation than a full replacement of the built-in set++Example directory:++```text+custom-memory/+├── project_decisions.yaml+└── user_preferences_ext.yaml+```++Example configuration:++```json+{+ "memory": {+ "custom_templates_dir": "/path/to/custom-memory"+ }+}+```++Recommendations when extending memory schemas:++- Start by following the style of existing `memory/*.yaml` files+- Confirm that the new memory type really needs to be independent+- Keep field names clear and stable for future updates+- Ensure `directory` and `filename_template` are easy to search and maintain++Impact examples:++- Adding `project_decisions`+ - affects memory persistence types and downstream search organization+- Modifying `preferences`+ - affects how user preference memories are organized and the granularity of recall+- Modifying `tools`+ - affects tool experience accumulation and tool usage recommendations++### High-Risk Changes During Customization++The following changes are the most likely to break existing workflows:++- changing variable names in regular prompts+- changing the expected output structure of a prompt without updating downstream parsing logic+- changing key field names in a memory schema+- changing `directory`, which changes retrieval scope+- changing `filename_template`, which changes how historical files are organized+- changing `merge_op`, which changes how existing memories are updated++If your goal is only to improve quality, these are usually the safer first moves:++- add clearer output examples to the prompt+- strengthen rules about what to keep and what to ignore+- adjust summary granularity or response style+- modify only one prompt category at a time instead of several at once++A conservative approach is:++1. copy the existing template first+2. change the instruction content and phrasing first+3. change structural fields last+4. modify only one prompt category at a time so impact is easier to isolate++## Validation and Troubleshooting++After modifying a prompt, validate it at two levels: whether the template was actually picked up, and whether the capability output changed as expected.++### First: Verify the Template Was Picked Up++Checklist:++- whether the custom directory is configured correctly+- whether the file path keeps the same relative path as the original template+- whether the YAML is valid+- whether the variable names still match the original template++For a regular prompt, focus on:++- whether the template was loaded correctly+- whether the target stage really uses that template++For a memory schema, focus on:++- whether the new schema was loaded successfully+- whether the target memory type actually participates in extraction and persistence++### Then: Verify That External Results Changed++The most effective validation is capability-focused:++- If you changed a `vision` template, re-parse images, tables, or scanned PDFs and check whether the results changed+- If you changed a `semantic` or `parsing` template, re-import documents or files and check whether summaries and structure changed+- If you changed a `retrieval` template, rerun the relevant search and check whether query planning and recall behavior changed+- If you changed a `compression` template, re-trigger session commit or memory processing and check whether extraction and merge results changed+- If you changed a `memory` schema, inspect the final persisted memory files, directories, and field structure++### Common Troubleshooting Patterns++Symptoms and first things to check:++| Symptom | First thing to check |+|---------|----------------------|+| Results do not change at all after modification | The custom directory is not active, or the file path does not match |+| The model reports missing variables | Template variable names do not match what callers provide |+| Returned content format is broken | The prompt output format changed, but downstream parsing still expects the old structure |+| A new memory type never appears | `memory.custom_templates_dir` is not active, or the schema was not loaded correctly |+| Retrieval quality gets worse | The `retrieval`, `semantic`, or `compression` prompt was changed too aggressively |++## Appendix++### Template Directory++Built-in prompt template directory:++```text+openviking/prompts/templates/+```++It contains:++- `compression/`: compression, extraction, and merging+- `indexing/`: relevance evaluation+- `memory/`: memory type definitions+- `parsing/`: structure analysis and semantic node generation+- `processing/`: experience and strategy extraction+- `retrieval/`: retrieval intent analysis+- `semantic/`: file and directory summaries+- `skill/`: Skill summaries+- `test/`: test case generation+- `vision/`: image, page, and table understanding++### Key Configuration Items++The main configuration items related to prompt customization are:++| Configuration item | Purpose |+|--------------------|---------|+| `prompts.templates_dir` | Override directory for regular prompt templates |+| `OPENVIKING_PROMPT_TEMPLATES_DIR` | Environment variable for the override directory of regular prompt templates |+| `memory.custom_templates_dir` | Directory for custom memory schemas |++### Practical Rule of Thumb++If your goal is:++- to change how the model speaks, extracts, or summarizes+ - modify a regular prompt template first+- to change what a memory looks like, where it is stored, or how it is organized+ - modify or extend a memory schema first++If you are not sure which layer to modify, ask yourself:++"Am I changing the model's instruction, or the structure of the final memory file?"++That question is usually enough to help decide whether you should modify a regular prompt or a memory schema.diff --git a/docs/zh/guides/10-prompt-guide.md b/docs/zh/guides/10-prompt-guide.mdnew file mode 100644index 000000000..1e1351b8e--- /dev/null+++ b/docs/zh/guides/10-prompt-guide.md@@ -0,0 +1,679 @@+# OpenViking Prompt 说明与自定义指南++本文介绍 OpenViking 当前的 prompt 模板体系,重点说明:++- 当前有哪些 prompt+- 它们分别用于哪个处理环节+- 它们会影响哪些对外能力或结果+- 模板文件的格式要求是什么+- 如何安全地自定义 prompt++本文只覆盖 `openviking/prompts/templates/` 下的模板,以及少量与模板加载有关的配置项。++## 总览++OpenViking 当前的 prompt 主要分为两类:++1. 普通 prompt 模板+ - 存放在 `openviking/prompts/templates/<category>/*.yaml`+ - 用于给模型下发任务,例如做图片理解、文档总结、记忆提取、检索意图分析等+2. memory schema 模板+ - 存放在 `openviking/prompts/templates/memory/*.yaml`+ - 用于定义某类记忆的字段、文件名模板、内容模板和目录规则++从使用角度看,这些模板主要服务于以下处理环节:++| 类别 | 代表模板 | 主要作用 | 生效环节 | 影响的对外能力 |+|------|----------|----------|----------|----------------|+| `vision` | `vision.image_understanding` | 图片、页面、表格理解 | 资源解析、扫描件理解 | 图片解析、PDF 页面理解、表格抽取结果 |+| `parsing` | `parsing.context_generation` | 文档结构划分与节点语义生成 | 资源导入与解析 | 文档章节结构、节点摘要、图像摘要 |+| `semantic` | `semantic.document_summary` | 文件与目录级摘要 | 语义索引构建 | 文件摘要、目录概览、后续检索质量 |+| `retrieval` | `retrieval.intent_analysis` | 检索意图分析与查询规划 | 检索前分析 | 搜索 query 规划、上下文召回方向 |+| `compression` | `compression.memory_extraction` | 记忆提取、合并、压缩、摘要 | session commit / memory 管线 | 长期记忆抽取、session 压缩、记忆合并结果 |+| `memory` | `profile` | 记忆类型定义 | 记忆落盘与更新 | 不同记忆类型的组织方式和最终内容 |+| `processing` | `processing.tool_chain_analysis` | 从交互或资源背景中提炼经验 | 后处理与经验沉淀 | 策略提炼、工具链经验、交互学习结果 |+| `indexing` | `indexing.relevance_scoring` | 评估候选内容相关性 | 检索与索引辅助 | 相关性打分质量 |+| `skill` | `skill.overview_generation` | 提炼 Skill 信息 | Skill 资源处理 | Skill 检索摘要 |+| `test` | `test.skill_test_generation` | 自动生成测试样例 | 测试与验证辅助 | Skill 测试样例生成 |++## Prompt 格式要求++### 普通 Prompt YAML++普通 prompt 模板通常包含以下字段:++```yaml+metadata:+ id: "semantic.document_summary"+ name: "Document Summary"+ description: "Generate summary for documentation files"+ version: "1.0.0"+ language: "en"+ category: "semantic"++variables:+ - name: "file_name"+ type: "string"+ description: "Input file name"+ required: true++template: |+ ...++output_schema:+ ...++llm_config:+ ...+```++字段含义:++- `metadata`+ - 描述模板身份与分类+ - 其中 `id` 通常与文件路径对应,例如 `semantic.document_summary`+- `variables`+ - 定义模板可接受的输入变量+ - 常见字段包括 `name`、`type`、`description`、`default`、`required`、`max_length`+- `template`+ - 真正发送给模型的 prompt 正文+ - 使用 Jinja2 变量渲染+- `output_schema`+ - 可选+ - 用于描述期望输出结构,方便调用方约束模型返回+- `llm_config`+ - 可选+ - 用于描述模型调用建议参数,不直接属于 prompt 正文++编写普通 prompt 时,建议遵守以下要求:++- `metadata.id` 与模板的类别和用途保持一致+- 变量名保持稳定,避免与调用方约定不一致+- `template` 中的占位变量应与 `variables` 定义一致+- 如果模板要求结构化输出,应明确写清字段、格式和约束+- 如果存在长度敏感输入,应通过 `max_length` 或上游截断控制 prompt 大小++### Memory Schema YAML++`memory/*.yaml` 不是普通 prompt 文本模板,而是记忆类型定义。下面是一个示意结构,用来说明常见字段;实际内置模板是否包含 `content_template`、目录是否带子目录,取决于具体 memory type。++```yaml+memory_type: "profile"+description: "User profile memory"+fields:+ - name: "content"+ type: "string"+ description: "Profile content"+ merge_op: "patch"+filename_template: "profile.md"+content_template: |+ ...+directory: "viking://user/{{ user_space }}/memories/..."+enabled: true+operation_mode: "upsert"+```++字段含义:++- `memory_type`+ - 该记忆类型的名称+- `description`+ - 对该类记忆的定义和提取要求+- `fields`+ - 该类记忆包含哪些字段+- `filename_template`+ - 生成文件名时使用的模板+- `content_template`+ - 落盘时使用的正文模板+- `directory`+ - 该类记忆写入的目录+- `enabled`+ - 是否启用该类记忆+- `operation_mode`+ - 该类记忆的更新模式,例如 `upsert`++编写 memory schema 时,建议重点关注:++- 字段粒度是否稳定+- 文件名模板是否可预测、可检索+- 目录规则是否符合预期检索范围+- 合并策略是否适合该类记忆++## 当前 Prompt 模板说明++下面按类别列出当前全部模板。每个条目都说明它用于哪个处理环节,以及主要影响哪类对外能力。++阅读这一节时,可以用一个简单规则:++- 普通 prompt 模板,重点看“作用”和“关键输入”+- memory schema,重点看“作用”和“关键字段”++### Compression++这一类 prompt 主要用于 session 压缩、记忆提取、记忆合并和字段压缩,是长期记忆质量的核心部分。++- `compression.dedup_decision`+ - 生效环节:记忆候选去重与决策阶段+ - 影响能力:长期记忆去重、创建或合并策略+ - 作用:决定新候选记忆应跳过、创建,还是与已有记忆合并+ - 关键输入:`candidate_content`、`candidate_abstract`、`candidate_overview`、`existing_memories`++- `compression.field_compress`+ - 生效环节:记忆字段压缩阶段+ - 影响能力:工具记忆等长字段内容的可控长度与可读性+ - 作用:在保留关键信息的前提下压缩字段内容+ - 关键输入:`field_name`、`content`、`max_length`++- `compression.memory_extraction`+ - 生效环节:会话压缩后的记忆提取阶段+ - 影响能力:长期记忆抽取质量、后续 recall 命中率+ - 作用:从会话摘要和最近消息中提取值得长期保存的记忆候选+ - 关键输入:`summary`、`recent_messages`、`user`、`feedback`、`output_language`++- `compression.memory_merge`+ - 生效环节:单条记忆合并阶段+ - 影响能力:已有记忆更新后的内容质量+ - 作用:将已有记忆与新信息合并成更完整的版本+ - 关键输入:`existing_content`、`new_content`、`category`、`output_language`++- `compression.memory_merge_bundle`+ - 生效环节:结构化记忆合并阶段+ - 影响能力:L0/L1/L2 三层记忆合并结果+ - 作用:一次性输出 abstract、overview、content 三层合并结果+ - 关键输入:`existing_abstract`、`existing_overview`、`existing_content`、`new_abstract`、`new_overview`、`new_content`、`category`、`output_language`++- `compression.structured_summary`+ - 生效环节:session archive 摘要生成阶段+ - 影响能力:历史会话压缩摘要、后续回顾和检索效果+ - 作用:为归档后的 session 生成结构化摘要+ - 关键输入:`latest_archive_overview`、`messages`++### Indexing++这一类 prompt 主要用于为检索或索引辅助流程做相关性判断。++- `indexing.relevance_scoring`+ - 生效环节:候选内容相关性评估阶段+ - 影响能力:检索结果排序、候选筛选质量+ - 作用:评估候选内容与用户查询之间的相关性+ - 关键输入:`query`、`candidate`++### Memory++这一类 YAML 定义不同记忆类型的结构,不是单次推理 prompt。它们共同决定用户记忆和 agent 记忆如何落盘、如何更新、如何被后续检索使用。++- `cases`+ - 生效环节:案例型记忆落盘与更新阶段+ - 影响能力:问题到解决方案的案例沉淀与复用+ - 作用:定义“遇到了什么问题、如何解决”的案例型记忆+ - 关键字段:`case_name`、`problem`、`solution`、`content`++- `entities`+ - 生效环节:实体型记忆落盘与更新阶段+ - 影响能力:人物、项目、组织、系统等实体信息的长期保存+ - 作用:定义命名实体及其属性信息的存储结构+ - 关键字段:`category`、`name`、`content`++- `events`+ - 生效环节:事件型记忆落盘与更新阶段+ - 影响能力:事件回顾、带时间线的信息保留、对话叙事记录+ - 作用:定义事件摘要、目标、时间范围等结构化事件记忆+ - 关键字段:`event_name`、`goal`、`summary`、`ranges`++- `identity`+ - 生效环节:agent identity 记忆落盘阶段+ - 影响能力:agent 身份设定的长期一致性+ - 作用:定义 agent 的名字、形象、风格、自我介绍等身份字段+ - 关键字段:`name`、`creature`、`vibe`、`emoji`、`avatar`++- `patterns`+ - 生效环节:模式型记忆落盘与更新阶段+ - 影响能力:可复用流程和方法的长期积累+ - 作用:定义“在什么情况下按什么流程处理”的模式记忆+ - 关键字段:`pattern_name`、`pattern_type`、`content`++- `preferences`+ - 生效环节:偏好型记忆落盘与更新阶段+ - 影响能力:用户偏好 recall 和后续个性化表现+ - 作用:定义不同主题下的用户偏好记忆+ - 关键字段:`user`、`topic`、`content`++- `profile`+ - 生效环节:用户 profile 记忆落盘与更新阶段+ - 影响能力:用户画像、工作背景、稳定属性的长期保存+ - 作用:定义“用户是谁”这一类稳定信息的存储结构+ - 关键字段:`content`++- `skills`+ - 生效环节:skill 使用记忆落盘与更新阶段+ - 影响能力:skill 使用统计、经验沉淀与推荐流程+ - 作用:定义 skill 使用次数、成功率、适用场景等信息+ - 关键字段:`skill_name`、`total_executions`、`success_count`、`fail_count`、`best_for`、`recommended_flow`++- `soul`+ - 生效环节:agent soul 记忆落盘阶段+ - 影响能力:agent 核心边界、连续性和长期人格稳定性+ - 作用:定义 agent 的核心真值、边界、风格和连续性+ - 关键字段:`core_truths`、`boundaries`、`vibe`、`continuity`++- `tools`+ - 生效环节:工具使用记忆落盘与更新阶段+ - 影响能力:工具使用经验、最佳参数、失败模式沉淀+ - 作用:定义工具调用统计和工具使用经验的存储结构+ - 关键字段:`tool_name`、`static_desc`、`call_count`、`success_time`、`when_to_use`、`optimal_params`++### Parsing++这一类 prompt 主要用于把原始资源内容转成适合检索和理解的结构化节点、章节、摘要或图像概述。++- `parsing.chapter_analysis`+ - 生效环节:长文档章节划分阶段+ - 影响能力:文档章节结构、页面组织效果+ - 作用:分析文档内容并划分合理的章节结构+ - 关键输入:`start_page`、`end_page`、`total_pages`、`content`++- `parsing.context_generation`+ - 生效环节:文档节点语义生成阶段+ - 影响能力:节点 abstract/overview 质量、后续检索匹配效果+ - 作用:为文本节点生成更短、更适合检索的语义标题、abstract 和 overview+ - 关键输入:`title`、`content`、`children_info`、`instruction`、`context_type`、`is_leaf`++- `parsing.image_summary`+ - 生效环节:图像节点摘要阶段+ - 影响能力:图片资源的语义概述和后续检索效果+ - 作用:为图像内容生成简洁摘要+ - 关键输入:`context`++- `parsing.semantic_grouping`+ - 生效环节:语义分组与切分阶段+ - 影响能力:文档节点粒度、内容块切分质量+ - 作用:根据语义决定内容应该合并还是拆分+ - 关键输入:`items`、`threshold`、`mode`++### Processing++这一类 prompt 主要用于从交互记录、工具链和资源背景中提炼策略或经验,不直接面向单次用户问答,而是面向后处理和知识沉淀。++- `processing.interaction_learning`+ - 生效环节:交互后经验提炼阶段+ - 影响能力:可复用交互经验、有效资源和成功 skill 的沉淀+ - 作用:从交互记录中抽取可复用经验+ - 关键输入:`interactions_summary`、`effective_resources`、`successful_skills`++- `processing.strategy_extraction`+ - 生效环节:资源添加后策略提炼阶段+ - 影响能力:资源背景意图的结构化提炼和后续复用+ - 作用:从资源添加原因、指令和抽象信息中提炼使用策略+ - 关键输入:`reason`、`instruction`、`abstract`++- `processing.tool_chain_analysis`+ - 生效环节:工具链分析阶段+ - 影响能力:工具组合模式识别、工具经验沉淀+ - 作用:分析工具调用链并识别有价值的使用模式+ - 关键输入:`tool_calls`++### Retrieval++这一类 prompt 主要用于检索前理解用户意图,决定 query plan 和上下文类型。++- `retrieval.intent_analysis`+ - 生效环节:检索前意图分析阶段+ - 影响能力:检索 query 规划、召回方向、不同 context 类型的搜索质量+ - 作用:结合压缩摘要、最近消息和当前消息生成检索计划+ - 关键输入:`compression_summary`、`recent_messages`、`current_message`、`context_type`、`target_abstract`++### Semantic++这一类 prompt 主要用于文件级和目录级摘要生成,是语义索引构建的重要部分。++- `semantic.code_ast_summary`+ - 生效环节:大型代码文件 AST 骨架总结阶段+ - 影响能力:代码文件摘要、代码检索和结构理解效果+ - 作用:基于 AST 骨架而不是完整源码生成代码摘要+ - 关键输入:`file_name`、`skeleton`、`output_language`++- `semantic.code_summary`+ - 生效环节:代码文件摘要阶段+ - 影响能力:代码文件语义索引、代码检索与理解结果+ - 作用:为代码文件生成结构、函数、类和关键逻辑摘要+ - 关键输入:`file_name`、`content`、`output_language`++- `semantic.document_summary`+ - 生效环节:文档文件摘要阶段+ - 影响能力:文档内容摘要、文档检索与概览效果+ - 作用:为 Markdown、Text、RST 等文档生成内容摘要+ - 关键输入:`file_name`、`content`、`output_language`++- `semantic.file_summary`+ - 生效环节:通用文件摘要阶段+ - 影响能力:目录索引与通用文件检索质量+ - 作用:为单个文件生成摘要,作为目录 abstract/overview 的上游输入+ - 关键输入:`file_name`、`content`、`output_language`++- `semantic.overview_generation`+ - 生效环节:目录级概览生成阶段+ - 影响能力:目录 overview、层级检索与导航体验+ - 作用:根据文件摘要和子目录 abstract 生成目录级 overview+ - 关键输入:`dir_name`、`file_summaries`、`children_abstracts`、`output_language`++### Skill++这一类 prompt 主要用于把 Skill 内容压缩成适合检索和复用的摘要。++- `skill.overview_generation`+ - 生效环节:Skill 内容处理阶段+ - 影响能力:Skill 检索摘要、Skill 发现效果+ - 作用:从 Skill 名称、描述和正文中抽取关键检索信息+ - 关键输入:`skill_name`、`skill_description`、`skill_content`++### Test++这一类 prompt 主要用于辅助生成测试样例。++- `test.skill_test_generation`+ - 生效环节:Skill 测试辅助阶段+ - 影响能力:Skill 场景测试设计与验证样例生成+ - 作用:根据多个 Skill 的名称和描述生成测试用例+ - 关键输入:`skills_info`++### Vision++这一类 prompt 主要用于图片、页面、表格和多模态文档分析,直接影响图片解析和扫描件理解结果。++- `vision.batch_filtering`+ - 生效环节:多图批量筛选阶段+ - 影响能力:多图文档理解中的图片保留与忽略策略+ - 作用:批量判断多张图片是否值得纳入文档理解+ - 关键输入:`document_title`、`image_count`、`images_info`++- `vision.image_filtering`+ - 生效环节:单图筛选阶段+ - 影响能力:图片是否进入后续理解流程+ - 作用:判断单张图片是否对文档理解有意义+ - 关键输入:`document_title`、`context`++- `vision.image_understanding`+ - 生效环节:图片理解阶段+ - 影响能力:图片解析结果、图片 abstract/overview/detail_text 质量+ - 作用:使用 VLM 对图片生成三层信息+ - 关键输入:`instruction`、`context`++- `vision.page_understanding`+ - 生效环节:扫描页理解阶段+ - 影响能力:扫描 PDF 页面理解与后续语义化结果+ - 作用:理解单页图片化文档内容+ - 关键输入:`instruction`、`page_num`++- `vision.page_understanding_batch`+ - 生效环节:多页批量理解阶段+ - 影响能力:批量扫描页理解效率与结果一致性+ - 作用:批量理解多页图片化文档内容+ - 关键输入:`page_count`、`instruction`++- `vision.table_understanding`+ - 生效环节:表格理解阶段+ - 影响能力:图片表格解析、表格摘要和结构理解+ - 作用:分析表格图片并生成三层信息+ - 关键输入:`instruction`、`context`++- `vision.unified_analysis`+ - 生效环节:多模态统一分析阶段+ - 影响能力:包含图片、表格和章节的复杂文档解析结果+ - 作用:批量分析文档中的图片、表格和章节信息+ - 关键输入:`title`、`instruction`、`reason`、`content_preview`、`image_count`、`images_section`、`table_count`、`tables_section`++## 如何自定义 Prompt++OpenViking 支持两种主要的自定义方式:++1. 覆盖普通 prompt 模板+2. 扩展 memory schema++在进入具体方法之前,可以先用下面的边界判断改动风险:++| 改动类型 | 风险级别 | 说明 |+|----------|----------|------|+| 改 prompt 措辞、补示例、调整语气 | 低 | 通常只影响模型表达方式,不改变调用方协议 |+| 改输出风格、改抽取偏好、改摘要粒度 | 中 | 会影响结果分布,需要重新验证目标能力 |+| 改变量名、改输出结构、改 memory 字段名 | 高 | 容易和调用方或解析逻辑不兼容 |+| 改 `directory`、`filename_template`、`merge_op` | 很高 | 会直接影响记忆存储位置、组织方式和更新行为 |++### 覆盖普通 Prompt 模板++适用场景:++- 想调整记忆提取偏好+- 想改变摘要风格+- 想让图片理解输出更细或更简+- 想调整检索意图分析的规划方式++可用配置:++- `prompts.templates_dir`+- 环境变量 `OPENVIKING_PROMPT_TEMPLATES_DIR`++加载优先级:++1. 显式传入的模板目录+2. 环境变量 `OPENVIKING_PROMPT_TEMPLATES_DIR`+3. `ov.conf` 中的 `prompts.templates_dir`+4. 内置模板目录 `openviking/prompts/templates/`++也就是说,普通 prompt 的自定义方式本质上是“优先从自定义目录查找,同路径未命中时再回退到内置模板”。++推荐做法:++1. 先复制内置模板目录中的目标文件+2. 保持相同的类别目录和文件名+3. 仅修改 prompt 正文或输出要求+4. 尽量不要修改已被调用方依赖的变量名++示例目录:++```text+custom-prompts/+├── compression/+│ └── memory_extraction.yaml+├── retrieval/+│ └── intent_analysis.yaml+└── semantic/+ └── document_summary.yaml+```++示例配置:++```json+{+ "prompts": {+ "templates_dir": "/path/to/custom-prompts"+ }+}+```++或者:++```bash+export OPENVIKING_PROMPT_TEMPLATES_DIR=/path/to/custom-prompts+```++影响面示例:++- 修改 `compression.memory_extraction`+ - 主要影响记忆抽取阶段+ - 最终影响长期记忆质量和后续 recall 结果+- 修改 `retrieval.intent_analysis`+ - 主要影响检索前 query plan+ - 最终影响搜索方向和召回效果+- 修改 `semantic.document_summary`+ - 主要影响文档摘要阶段+ - 最终影响文档索引和摘要结果++### 扩展 Memory Schema++适用场景:++- 想新增一类业务记忆+- 想调整某类记忆的字段结构+- 想改变记忆落盘目录或文件模板++可用配置:++- `memory.custom_templates_dir`++加载行为:++- 内置 memory schema 会先加载+- 如果配置了 `memory.custom_templates_dir`,再继续加载自定义目录中的 schema+- 因此,memory 自定义更接近“扩展和补充”,而不是完全替换整套内置模板++示例目录:++```text+custom-memory/+├── project_decisions.yaml+└── user_preferences_ext.yaml+```++示例配置:++```json+{+ "memory": {+ "custom_templates_dir": "/path/to/custom-memory"+ }+}+```++扩展 memory schema 时建议:++- 优先参考现有 `memory/*.yaml` 写法+- 先确定该类记忆是否真的需要独立类型+- 保持字段名清晰、可稳定更新+- 确保 `directory` 和 `filename_template` 易于检索和维护++影响面示例:++- 新增 `project_decisions`+ - 影响记忆落盘类型和后续搜索组织方式+- 修改 `preferences`+ - 影响用户偏好类记忆的组织方式和 recall 颗粒度+- 修改 `tools`+ - 影响工具经验沉淀和工具使用建议结果++### 自定义时的高风险改动++以下改动最容易破坏现有链路:++- 修改普通 prompt 的变量名+- 修改 prompt 的预期输出结构,但未同步调整调用方解析逻辑+- 修改 memory schema 的关键字段名+- 修改 `directory` 导致检索范围变化+- 修改 `filename_template` 导致历史文件组织方式变化+- 修改 `merge_op` 导致已有记忆更新策略变化++如果只是想优化效果,通常优先考虑这些低风险改法:++- 给 prompt 增加更明确的输出示例+- 强化“该保留什么、该忽略什么”的规则+- 调整摘要粒度或表达风格+- 只改某一类 prompt,而不是同时改多类++保守做法是:++1. 先复制现有模板+2. 尽量只改指令内容和表达方式+3. 结构字段最后再改+4. 每次只改一类 prompt,方便定位影响范围++## 验证与排查++修改 prompt 之后,建议按“模板是否命中”和“能力是否变化”两层来验证。++### 先验证模板是否命中++检查项:++- 自定义目录是否配置正确+- 文件路径是否与原模板保持相同相对路径+- YAML 格式是否有效+- 变量名是否和原模板一致++如果是普通 prompt,重点确认:++- 模板是否被正确加载+- 目标环节是否真的使用了该模板++如果是 memory schema,重点确认:++- 新 schema 是否被成功加载+- 目标记忆类型是否真的参与了提取和落盘++### 再验证对外结果是否变化++从使用者角度验证最有效:++- 如果改的是 `vision` 类模板,就重新解析图片、表格或扫描 PDF,看结果是否变化+- 如果改的是 `semantic` 或 `parsing` 类模板,就重新导入文档或文件,看摘要和结构是否变化+- 如果改的是 `retrieval` 类模板,就重新执行相关搜索,看 query 规划和召回效果是否变化+- 如果改的是 `compression` 类模板,就重新触发 session commit 或 memory 处理流程,看记忆抽取和合并结果是否变化+- 如果改的是 `memory` 类 schema,就检查最终落盘的记忆文件内容、目录和字段结构是否符合预期++### 常见排查思路++现象与优先检查项:++| 现象 | 优先检查 |+|------|----------|+| 修改后结果完全没变 | 自定义目录未生效,或文件路径不匹配 |+| 模型报缺少变量 | 模板变量名与调用方不一致 |+| 返回内容格式错乱 | prompt 输出格式改了,但下游解析还按旧结构处理 |+| 新 memory 类型没有出现 | `memory.custom_templates_dir` 未生效,或 schema 未被正确加载 |+| 检索结果变差 | `retrieval`、`semantic` 或 `compression` 类 prompt 改得过于激进 |++## 附录++### 模板目录++内置 prompt 模板目录:++```text+openviking/prompts/templates/+```++其中:++- `compression/`:压缩、提取、合并+- `indexing/`:相关性评估+- `memory/`:记忆类型定义+- `parsing/`:结构分析与语义节点生成+- `processing/`:经验与策略提炼+- `retrieval/`:检索意图分析+- `semantic/`:文件和目录摘要+- `skill/`:Skill 摘要+- `test/`:测试样例生成+- `vision/`:图片、页面、表格理解++### 关键配置项++与 prompt 自定义相关的配置主要有:++| 配置项 | 用途 |+|--------|------|+| `prompts.templates_dir` | 指定普通 prompt 模板覆盖目录 |+| `OPENVIKING_PROMPT_TEMPLATES_DIR` | 通过环境变量指定普通 prompt 模板覆盖目录 |+| `memory.custom_templates_dir` | 指定 custom memory schema 目录 |++### 选型建议++如果你的目标是:++- 改模型“怎么说、怎么提取、怎么总结”+ - 优先改普通 prompt 模板+- 改“记忆长什么样、存在哪里、怎么组织”+ - 优先改 memory schema++如果不确定该改哪一层,先问自己一句:++“我要改的是模型的指令,还是最终记忆文件的结构?”++这个问题通常足以帮助你区分应该改普通 prompt 还是 memory schema。