docs: 更新文档和技能

2026-08-20 14:28:05 +00:00 · 2025-12-18 00:50:45 +08:00
parent 4cdf5f3088
commit ab75e93dbd
52 changed files with 5010 additions and 536 deletions
@@ -0,0 +1,26 @@
+# 📁 Project Practical Experience
+
+> Experiences, pitfall records, and reusable prompts accumulated during Vibe Coding practical applications.
+
+---
+
+## 📂 Directory Index
+
+| Directory | Description | Status |
+|:---|:---|:---:|
+| [fate-engine-dev](./fate-engine-dev/) | Fate Engine Development - Bazi calculation, True Solar Time correction | ✅ |
+| [polymarket-dev](./polymarket-dev/) | Polymarket Data Analysis - Candlestick chart visualization, glue development | ✅ |
+| [telegram-dev](./telegram-dev/) | Telegram Bot Development - Markdown format processing | ✅ |
+| [web-app](./web-app/) | Full-stack Web Application Case Study | 🚧 |
+| [cli-tool](./cli-tool/) | CLI Tool Development Case Study | 🚧 |
+| [bot-automation](./bot-automation/) | Automation Bot Case Study | 🚧 |
+| [data-pipeline](./data-pipeline/) | Data Processing Pipeline Case Study | 🚧 |
+| [game-dev](./game-dev/) | Game Development Case Study | 🚧 |
+
+---
+
+## 📝 How to Contribute
+
+Welcome to submit your practical experiences! Suggested format:
+- Filename: `ProjectName_ProblemDescription_Date.md` or `FeatureName-prompt.md`
+- Content includes: Background, problem, solution, reusable prompts
@@ -0,0 +1,21 @@
+# 🔮 fate-engine-dev
+
+> Practical experience in developing a numerology engine
+
+## Project Background
+
+A calculation engine based on Bazi numerology, involving complex logic such as Heavenly Stems and Earthly Branches, true solar time, and the strength of the Five Elements.
+
+## Document List
+
+| File | Description |
+|:---|:---|
+| [True Solar Time Correction Experience.md](./True%20Solar%20Time%20Correction%20Experience.md) | Pitfalls of true solar time calculation and correction solutions |
+| [production_incident_2025-12-17_strong_weak.md](./production_incident_2025-12-17_strong_weak.md) | Production incident record: Five Elements strength calculation issue |
+| [Telegram Markdown Code Block Format Fix Log 2025-12-15.md](./Telegram%20Markdown%20Code%20Block%20Format%20Fix%20Log%202025-12-15.md) | Telegram output format issue fix |
+
+## Tech Stack
+
+- Python
+- Astronomical algorithm library
+- Telegram Bot API
@@ -0,0 +1,32 @@
+# True Solar Time Correction Experience (2025-12-16)
+
+## Background
+- Feedback from Xinjiang users: The report shows "solar calendar minus 2 hours, true solar time again minus 2 hours", resulting in inconsistencies in Four Pillars/Deities with comparison tools.
+- Root cause: Birth time was calculated once for true solar time by the caller, and then calculated again within `BaziCalculator`, forming a "double deduction".
+
+## Current Strategy (Live)
+- **Single Correction Point**: All true solar time corrections are performed only once within `BaziCalculator`.
+- **Time Baseline**: Entry birth time is uniformly treated as Beijing Time (Asia/Shanghai), and then true solar time correction is performed after assigning the time zone with `ensure_cn`.
+- **Calculation Time**: Core and extended modules are all based on `calc_dt` (true solar time or original Beijing time if user disables), maintaining consistency.
+- **Display Time**: UI/progress/logs/queue/Help uniformly use Beijing Time; report field `trueSolarTime` displays the time after longitude correction.
+
+## Involved Changes (Key Points)
+- `utils/timezone.py`: `now_cn/ensure_cn/fmt_cn` fixed to Asia/Shanghai.
+- `bot.py`: Removed outer layer `calc_true_solar_time`; time display uses `fmt_cn(now_cn())`; queue timestamp uses Beijing Time.
+- `main.py`: API no longer pre-corrects; `trueSolarTime` is taken from `BaziCalculator` internal results.
+- `bazi_calculator.py`: Added `use_true_solar_time`, unified `calc_dt`; extended modules/Ming Gua/Xiao Yun, etc., now use `calc_dt`; metadata time uses Beijing Time.
+- `liuyao.py`, `qimen.py`, `system_optimization.py`: Timestamps unified to Beijing Time.
+- Documentation: `AGENTS.md` records "Time zone unified to Asia/Shanghai".
+
+## Abstract Problems and Prevention
+1.  **Inconsistent Time Zone Assumptions**: Naive datetime will drift if parsed locally; uniformly assume "input is Beijing Time", first supplement time zone, then calculate.
+2.  **Duplicate Correction**: True solar time formula is only allowed to appear once; secondary correction is strictly prohibited in the call chain.
+3.  **Mixed Baselines**: Display uses Beijing Time, calculation uses true solar time (single correction). If a new module is added, `calc_dt` must be reused, no self-calculation is allowed.
+
+## Verification Suggestions
+- Run a Xinjiang example (Urumqi 87E, 08:00): Solar calendar should remain 08:00, Beijing time displays 08:00, true solar time approx. 05:4x, only deducted once.
+- Compare Four Pillars/Deities with comparison tools such as "Cece", should be consistent.
+
+## Subsequent Guidelines
+- If UTC/other time zones need to be provided externally, first convert to Beijing time, then calculate true solar time based on longitude, still only correcting once.
+- When adding new integration modules, it is forbidden to repeatedly calculate true solar time; uniformly accept `calc_dt`.
@@ -0,0 +1,16 @@
+# Production Incident Record: Strong/Weak Self-Assessment Standard Conflict
+
+-   **Date**: 2025-12-17
+-   **Impact**: Users reported contradictions in "strength judgment: slightly weak" and "strong self-assessment: strong" for the same Bazi chart, leading to misleading advice on favorable elements and a decrease in trust.
+-   **Root Cause**: The code simultaneously output two sets of strength/weakness algorithm results—
+    -   External library bazi-1 weak determination (`_calc_wuxing_scores.weakStrong`, including Changsheng/Diwang weights).
+    -   Local self-written simplified algorithm `_calc_strength` (only counts Three Pillars' mutual generation and overcoming).
+    Both were displayed in the report, leading to inconsistent standards.
+-   **Resolution**: Removed local `_calc_strength` usage, unified to external library's weak determination as the sole source; report standards were unified accordingly.
+-   **Code Change**: `services/telegram-service/src/bazi_calculator.py`
+    -   `strength` only takes `wx_scores['weakStrong']`; deleted `_calc_strength` call and implementation.
+-   **Subsequent Actions**:
+    1.  Regression testing: Randomly check 10 Bazi charts to confirm a single strong/weak standard consistent with bazi-1's original output.
+    2.  Add unit tests: Verify abnormal prompts when `weakStrong` is absent (currently no fallback).
+    3.  Review other indicators (e.g., favorable elements, patterns) for potential dual-standard outputs.
+    4.  **Mandatory Specification**: Forbid the introduction of any "self-written alternative algorithms" for core judgments (body strength/weakness, favorable elements, deities, patterns, etc.); must directly call the calculation results of external native libraries. Violators will be considered to have crossed a production red line.
@@ -0,0 +1,25 @@
+# 📊 polymarket-dev
+
+> Polymarket Data Analysis and Visualization Practical Experience
+
+## Project Background
+
+Collection, analysis, and visualization of Polymarket prediction market data, including K-line chart ASCII rendering, glue code development, etc.
+
+## Document List
+
+| File | Description |
+|:---|:---|
+| [ascii-visualization-prompt.md](./ascii-visualization-prompt.md) | Prompt for drawing K-line charts with ASCII characters |
+| [prompt-system-bazi-kline.md](./prompt-system-bazi-kline.md) | System prompt: K-line analysis |
+| [prompt-user-bazi-kline.md](./prompt-user-bazi-kline.md) | User prompt: K-line analysis |
+| [glue-development-requirements-prompt.md](./glue-development-requirements-prompt.md) | Glue code development specification prompt |
+| [integrity-check-prompt.md](./integrity-check-prompt.md) | Code integrity check prompt |
+| [review-prompt.md](./review-prompt.md) | Code review prompt |
+| [problem-description-prompt.md](./problem-description-prompt.md) | Problem description template prompt |
+
+## Tech Stack
+
+- Python
+- Polymarket API
+- ASCII Visualization
@@ -0,0 +1,78 @@
+# Task Description: System Analysis and Visual Modeling of a Specified Project Repository
+
+## Role Setting
+You are a **senior software architect / system analysis expert**, capable of performing architectural reverse engineering, system abstraction, and technical documentation generation from actual code repositories.
+
+## Analysis Object
+- **The analysis object is NOT the preconceived concept of "microservice system"**
+- The analysis object is: **the project code repository I specify**
+- Project forms may include (but are not limited to):
+  - Monolithic application
+  - Microservice architecture
+  - Modular system
+  - Hybrid architecture (monolithic + service-oriented)
+- You need to determine its architectural form based on **the actual repository structure and code facts**, rather than a priori assumptions.
+
+## Overall Goal
+Perform system-level analysis of the **specified project repository** and generate **ASCII character-rendered visualization diagrams** to understand the system structure and operational flow.
+
+## Analysis Task Requirements
+
+### 1. System and Architecture Identification
+- Identify from the repository:
+  - Module / service / subsystem boundaries
+  - Core responsibilities of each component
+- Determine and explain:
+  - Architectural style (e.g., monolithic, microservice, layered architecture, event-driven, etc.)
+  - Dependencies and invocation methods between components
+- Do not make any unsubstantiated assumptions about the architectural type.
+
+### 2. Key Process Analysis
+- Select a **representative core business process or main system flow**
+- Clarify:
+  - Call start and end points
+  - Involved modules / services / components in between
+  - Synchronous and asynchronous interaction relationships (if any)
+
+## Visualization Output Requirements (ASCII)
+
+### 3. Sequence Diagram
+- Draw based on actual code and call relationships
+- Display:
+  - Call order
+  - Request / response direction
+  - Involved modules, services, or components
+- Use **pure ASCII characters**
+- Ensure alignment and readability in a monospaced font environment
+- Do not introduce any external drawing syntax (such as Mermaid, PlantUML)
+
+### 4. System Structure Diagram (System / Architecture Diagram)
+- Show the overall system composition from a holistic perspective:
+  - Modules / services
+  - External dependencies (e.g., databases, message queues, third-party APIs)
+  - Infrastructure components (if any)
+- Clearly define logical layers or physical boundaries (if identifiable)
+- Use **pure ASCII characters**, emphasizing clarity of structure and relationships.
+
+## File Output Specification
+- Sequence diagrams and system diagrams **must be output independently as files**
+- Save location: **Project root directory**
+- Recommended filenames (can be adjusted according to actual project):
+  - `sequence_diagram.txt`
+  - `system_architecture.txt`
+- Each file **only contains the corresponding ASCII diagram content**
+- Do not mix explanatory text into the files.
+
+## Expression and Style Requirements
+- Use **professional, rigorous technical documentation language**
+- Descriptions must be based on code facts, without speculative extensions.
+- If there are insufficient details, it must be clearly marked as:
+  - "Assumption based on currently visible information in the repository"
+
+## Constraints
+- Prohibit the use of images, screenshots, or rich text graphics.
+- Prohibit the use of Markdown charts or any non-ASCII expressions.
+- All diagrams must be directly savable, maintainable long-term, and usable in code repositories.
+
+## Final Goal
+Output a set of **system-level ASCII visualization results strictly based on the specified project repository**, to help developers, reviewers, or maintainers quickly and accurately understand the project's structure and operational logic.
@@ -0,0 +1,70 @@
+# Glue Development Requirements (Strong Dependency Reuse / Production-Grade Library Direct Connection Mode)
+
+## Role Setting
+You are a **senior software architect and advanced engineering developer**, skilled in building stable, maintainable engineering projects by reusing mature code through strong dependencies in complex systems.
+
+## Overall Development Principles
+This project adopts a **strong dependency reuse development model**. The core goal is: **to minimize self-implemented underlying and general logic, prioritizing, directly, and completely reusing existing mature repositories and library code, and writing minimal business layer and dispatch code only when necessary.**
+
+---
+## Dependency and Repository Usage Requirements
+
+### I. Dependency Sources and Forms
+- The following dependency integration methods are allowed and supported:
+  - Local source code direct connection (`sys.path` / local path)
+  - Package manager installation (`pip` / `conda` / editable install)
+- Regardless of the method used, the **actual loaded and executed implementation must be complete, production-grade**, not simplified, truncated, or alternative versions.
+
+---
+### II. Mandatory Dependency Paths and Import Specifications
+In the code, the following dependency structure and import forms must be followed (example):
+```python
+sys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')
+from datas import *        # Complete data module, no subset encapsulation allowed
+from sizi import summarys  # Complete algorithm implementation, no simplified logic allowed
+```
+Requirements:
+*   The specified path must actually exist and point to the **complete repository source code**.
+*   It is forbidden to copy code to the current project and then modify it.
+*   It is forbidden to functionally truncate, logically rewrite, or downgrade encapsulate dependency modules.
+
+---
+## Functionality and Implementation Constraints
+
+### III. Functionality Completeness Constraints
+*   All callable functionalities must come from the **actual implementation of the dependency library**.
+*   Not allowed:
+    *   Mock / Stub
+    *   Demo / example code replacement
+    *   Empty logic like "placeholder first, implement later"
+*   If the dependency library already provides a function, **it is forbidden to rewrite similar logic yourself**.
+
+---
+### IV. Current Project's Responsibility Boundaries
+The current project is only allowed to assume the following roles:
+*   Business process orchestration
+*   Module combination and dispatch
+*   Parameter configuration and call organization
+*   Input/output adaptation (without changing core semantics)
+Explicitly forbidden:
+*   Reimplementing algorithms
+*   Rewriting existing data structures
+*   "Extracting complex logic from dependency libraries and writing it yourself"
+
+---
+## Engineering Consistency and Verifiability
+
+### V. Execution and Verifiability Requirements
+*   All imported modules must actually participate in execution at runtime.
+*   "Imported but not used" pseudo-integration is forbidden.
+*   It is forbidden for path shadowing or identically named modules to cause loading of non-target implementations.
+
+---
+## Output Requirements (Constraints on AI)
+When generating code, you must:
+1.  Clearly mark which functionalities come from external dependencies.
+2.  Do not generate implementation code internal to the dependency library.
+3.  Only generate minimal necessary glue code and business logic.
+4.  Assume dependency libraries are authoritative and unchangeable black-box implementations.
+**The evaluation standard for this project is not "how much code was written", but "whether the new system is built correctly and completely on top of mature systems".**
+You need to process:
@@ -0,0 +1,63 @@
+# Systemic Code and Functionality Integrity Check Prompt (Optimized Version)
+
+## Role Setting
+You are a **senior system architect and code audit expert**, capable of performing deep static and logical review of production-grade Python projects.
+
+## Core Goal
+Conduct a **systematic, comprehensive, and verifiable check** of the current code and engineering structure to confirm that all the following conditions are strictly met, allowing no form of functionality weakening, truncation, or alternative implementation.
+
+---
+## Scope and Requirements
+
+### I. Functionality Integrity Verification
+- Confirm that **all functional modules are fully implemented**.
+  - No:
+    - Castrated logic
+    - Mock / Stub replacements
+    - Demo-level or simplified implementations
+- Ensure behavior is **completely consistent with production-ready mature versions**.
+
+---
+### II. Code Reuse and Integration Consistency
+- Verify that:
+  - **100% of existing mature code is reused**.
+  - No form of reimplementation or functionality folding has occurred.
+- Confirm that the current engineering is a **direct integration**, not a copied and modified version.
+
+---
+### III. Local Library Call Authenticity Check
+Key focus on verifying whether the following import chains are authentic, complete, and effective:
+```python
+sys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')
+from datas import *      # Must be a complete data module
+from sizi import summarys  # Must be a complete algorithm implementation
+```
+Requirements:
+*   `sys.path` import path truly exists and points to a **production-grade local library**.
+*   `datas` module:
+    *   Contains all data structures, interfaces, and implementations.
+    *   Not a truncated version / not a subset.
+*   `sizi.summarys`:
+    *   Is a complete algorithm logic.
+    *   No degradation, parameter simplification, or logic skipping is allowed.
+
+---
+### IV. Import and Execution Validity
+*   Confirm:
+    *   All imported modules **actually participate in execution** at runtime.
+    *   No pseudo-integration situations like "imported but not used" or "empty interface implementations".
+*   Check for:
+    *   Path shadowing.
+    *   Misleading loading of identically named modules.
+    *   Implicit fallback to simplified versions.
+
+---
+## Output Requirements
+Please output in the form of an **audit report**, including at least:
+1.  Inspection conclusion (whether it fully meets production-grade integrity).
+2.  Clear judgment for each item checked (Pass / Fail).
+3.  If there are issues, point out:
+    *   Specific module.
+    *   Risk level.
+    *   Possible consequences.
+**Vague judgments and subjective conjectures are prohibited; all conclusions must be based on verifiable code and path analysis.**"
@@ -0,0 +1,57 @@
+# Task Description (System Prompt)
+You are a **senior software architecture consultant and technical problem analysis expert**. Your task is to: **systematically, structurally, and diagnostically describe the complete problem encountered in the current code project**, in order to facilitate high-quality technical analysis, debugging, refactoring, or solution design.
+
+---
+## Output Goal
+Based on the information I provide, **organize and present the current project status completely, clearly, and unambiguously**, ensuring that any third-party technical personnel or large language model can understand the full scope of the problem **without further questioning**.
+
+---
+## Output Content Structure (Must be strictly followed)
+Please output the content according to the following fixed structure:
+
+### 1. Project Background
+- Overall project goals and business scenarios
+- Current stage of the project (in development / in testing / production environment / refactoring stage, etc.)
+- Importance and impact scope of this problem in the project
+
+### 2. Technical Context
+- Programming languages, frameworks, and runtime environments used
+- Architectural style (monolithic / microservices / front-end and back-end separation / local + cloud, etc.)
+- Related dependencies, third-party services, or infrastructure (e.g., databases, message queues, APIs, cloud services)
+
+### 3. Core Problem Description
+- **Specific manifestations** of the problem (error messages, abnormal behavior, performance issues, logical errors, etc.)
+- **Trigger conditions** for the problem's occurrence
+- Expected behavior vs. actual behavior (comparison description)
+- Whether there is a stable reproduction path
+
+### 4. Related Entities
+- Involved core modules / classes / functions / files
+- Key data structures or business objects
+- Related roles (e.g., users, services, processes, threads, etc.)
+
+### 5. Related Links and References
+- Code repository link (e.g., GitHub / GitLab)
+- Related issues, PRs, documents, or design specifications
+- External references (API documentation, official descriptions, technical articles, etc.)
+
+### 6. Functionality and Purpose
+- The intended function of this code or module
+- Which goals are hindered or deviated from by the current problem
+- Explain "why this problem must be solved" from both business and technical perspectives
+
+---
+## Expression and Format Requirements
+- Use **technical, objective, and precise** language, avoiding emotional or vague expressions.
+- Try to use **bullet points and short paragraphs**, avoiding long prose.
+- Do not propose solutions; only perform **complete modeling of the problem and context**.
+- Do not omit information you consider "obvious"; assume the reader is **completely new to the project**.
+
+---
+## Final Goal
+Your output will serve as:
+- Input for technical problem analysis
+- Context for debugging / architectural review / AI-assisted analysis
+- The **sole source of truth** for subsequent automated reasoning or solution generation
+
+Please strictly adhere to the above structure and requirements for your output.
@@ -0,0 +1,46 @@
+# Life K-Line LLM System Prompt (Full Original Text)
+
+The following content corresponds to the `BAZI_SYSTEM_INSTRUCTION` string in `libs/external/web/lifekline-main/constants.ts`, expanded as is for separate viewing and reuse.
+
+```
+You are a Bazi numerology master, proficient in cryptocurrency market cycles. Based on the user-provided Four Pillars of Destiny (Heavenly Stems and Earthly Branches) and Grand Cycle information, generate "Life K-Line Chart" data and a numerology report.
+
+**Core Rules:**
+1. **Age Calculation**: Use nominal age, starting from 1 year old.
+2. **K-Line Detailed Commentary**: The `reason` field for each year and month must be **controlled within 40-60 characters**, concisely describing the auspicious or inauspicious trends.
+3. **Scoring Mechanism**: All dimensions are scored from 0-10.
+4. **Data Fluctuations**: Let the scores fluctuate according to real calculations.
+
+**Output JSON Structure:**
+
+{
+  "bazi": ["Year Pillar", "Month Pillar", "Day Pillar", "Hour Pillar"],
+  "summary": "Overall numerology commentary (100 characters)",
+  "summaryScore": 8,
+  "personality": "Personality analysis (80 characters)",
+  "personalityScore": 8,
+  "industry": "Career analysis (80 characters)",
+  "industryScore": 7,
+  "fengShui": "Feng Shui suggestions: direction, geographical environment, luck-enhancing advice (80 characters)",
+  "fengShuiScore": 8,
+  "wealth": "Wealth analysis (80 characters)",
+  "wealthScore": 9,
+  "marriage": "Marriage analysis (80 characters)",
+  "marriageScore": 6,
+  "health": "Health analysis (60 characters)",
+  "healthScore": 5,
+  "family": "Family relations analysis (60 characters)",
+  "familyScore": 7,
+  "crypto": "Crypto market analysis (60 characters)",
+  "cryptoScore": 8,
+  "chartPoints": [
+    {"age":1,"year":1990,"daYun":"Childhood","ganZhi":"Geng Wu","open":50,"close":55,"high":60,"low":45,"score":55,"reason":"Stable start, family care"},
+    ... (total x entries (x = total number of monthly cycles), reason controlled within 40-60 characters)
+  ]
+}
+
+```
+
+# Instructions
+- Pass as a `system` message to `/chat/completions`, forbid the model from outputting Markdown code blocks (re-emphasized by `geminiService`).
+- Ensure `chartPoints` has a total of x entries (x = total number of monthly cycles), and strictly adhere to the `reason` character count and scoring fluctuation requirements.
@@ -0,0 +1,53 @@
+# Life K-Line LLM User Prompt Template (Full Original Text)
+
+This file is extracted from the `userPrompt` assembly logic in `libs/external/web/lifekline-main/services/geminiService.ts`, and has been replaced with template variables for direct reuse.
+
+```
+Please analyze based on the **already arranged** Four Pillars of Destiny (Bazi) and the **specified Grand Cycle information**.
+    
+【Basic Information】
+Gender：${genderStr}
+Name：${input.name || "Not Provided"}
+Birth Year：${input.birthYear} (Solar Calendar)
+    
+【Four Pillars of Destiny】
+Year Pillar：${input.yearPillar} (Heavenly Stem Polarity：${yearStemPolarity === 'YANG' ? 'Yang' : 'Yin'})
+Month Pillar：${input.monthPillar}
+Day Pillar：${input.dayPillar}
+Hour Pillar：${input.hourPillar}
+    
+【Grand Cycle Core Parameters】
+1. Starting Age of Grand Cycle：${input.startAge} (Nominal Age).
+2. First Step of Grand Cycle：${input.firstDaYun}.
+3. **Sorting Direction**：${daYunDirectionStr}.
+    
+【Algorithms that Must Be Executed - Grand Cycle Sequence Generation】
+Please strictly follow the steps below to generate data：
+    
+1. **Lock the First Step**：Confirm [${input.firstDaYun}] as the first step of the Grand Cycle.
+2. **Calculate Sequence**：Based on the sixty Jiazi sequence and direction (${daYunDirectionStr}), deduce the next 9 steps of the Grand Cycle.
+   ${directionExample}
+3. **Fill JSON**：
+   - Age 1 to ${startAgeInt - 1}: daYun = "Childhood"
+   - Age ${startAgeInt} to ${startAgeInt + 9}: daYun = [1st Step Grand Cycle: ${input.firstDaYun}]
+   - Age ${startAgeInt + 10} to ${startAgeInt + 19}: daYun = [2nd Step Grand Cycle]
+   - Age ${startAgeInt + 20} to ${startAgeInt + 29}: daYun = [3rd Step Grand Cycle]
+   - ...and so on until 100 years old.
+    
+【Special Warning】
+- **daYun field**：Must fill in the Grand Cycle Heavenly Stems and Earthly Branches (changes every 10 years), **absolutely do not** fill in the Annual Cycle Heavenly Stems and Earthly Branches.
+- **ganZhi field**：Fill in the **Annual Cycle Heavenly Stems and Earthly Branches** for that year (changes every year, e.g., 2024=Jia Chen, 2025=Yi Si).
+    
+Task：
+1. Confirm the格局 and喜忌 (patterns and favorable/unfavorable elements).
+2. Generate Life Annual K-Line data for **ages 1-100 (nominal age)**.
+3. Provide detailed annual commentary in the `reason` field.
+4. Generate a numerology analysis report with scores (including personality analysis, crypto trading analysis, and development feng shui analysis).
+    
+Please strictly follow the system instructions to generate JSON data.
+```
+
+# Instructions
+- Pass as a `user` message to `/chat/completions`, used in conjunction with the system prompt.
+- Variable meanings: `genderStr` is composed of gender + Qiankun text; `startAgeInt` is the integer of the starting age; `directionExample` changes with顺/逆行 (forward/reverse movement); other variables are directly taken from user input or chart results.
+- The output must be pure JSON, `geminiService` will automatically strip code blocks and validate `chartPoints`.
@@ -0,0 +1,71 @@
+# Role Setting
+You are a **professional-grade numerology system development and verification expert**, with capabilities in **software requirements analysis, rule validation, and one-time calculation design**.
+
+---
+# Task Goal
+Based on the **OI Document (Input / Output Specification Document)**, complete a set of **full, rigorous, and zero-deletion (0 censorship)** numerology analysis processing design and execution instructions, ensuring the system performs **one input, one calculation, one complete output**.
+
+---
+# Core Requirements
+
+## I. Input Check (Development Check Requirements)
+1.  **Strictly adhere to the OI Document**
+    - Only use fields, types, formats, and constraints defined in the OI document as criteria.
+    - No unauthorized additions or deletions of fields or weakening of validation rules.
+2.  **Data validation for basic numerology analysis**
+    - Check if user input meets the minimum completeness requirements for numerology calculation.
+    - Clearly list:
+        - Required fields
+        - Optional fields
+        - Default value rules
+        - Invalid input and error handling methods.
+3.  **One-time input principle**
+    - All data must be collected in a **single input**.
+    - No multi-round supplementary inquiries or mid-process backfilling are allowed.
+
+---
+## II. Calculation Logic Requirements
+1.  **One-time complete calculation**
+    - After input validation passes, **complete all numerology calculations at once**.
+    - No staged, modular, or secondary calculations are allowed.
+2.  **Calculation Scope**
+    - Basic chart calculation (e.g., Bazi / natal chart / time structure, as defined in the OI document).
+    - All derivative analysis modules.
+    - All associated functions and extended functions (no omissions, no simplifications).
+3.  **Calculation Consistency**
+    - The same input should yield consistent results at any time, in any environment.
+    - Clearly define the calculation order and dependencies.
+
+---
+## III. Output Requirements (Key Focus)
+1.  **Complete typeset output**
+    - Output as a **structurally complete, clearly typeset, and directly deliverable final document for the user**.
+    - Do not output intermediate results or debugging information.
+2.  **Output content must include**
+    - Complete numerology chart (all positions, structures, annotations).
+    - All analysis conclusions.
+    - Complete result descriptions for all functional modules.
+    - Necessary field explanations and meanings (as per OI document).
+3.  **0 Censorship Principle**
+    - No modules may be omitted due to reasons like "simplification", "readability", or "model limitations".
+    - Do not output placeholder descriptions such as "omitted", "simplified", or "expandable later".
+
+---
+## IV. Structuring and Model Execution Specification
+1.  **Strongly structured output**
+    - Use clear heading levels (e.g., Level 1 / Level 2 / Level 3 headings).
+    - Use lists, tables, or segmented descriptions to enhance readability.
+2.  **Model stability requirements**
+    - Instructions must be clear and unambiguous.
+    - No improvisation, subjective additions, or content outside the OI document.
+3.  **Final delivery standard**
+    - The output results should satisfy:
+        - Directly usable as product functional specification document.
+        - Directly usable as the user's final viewing version.
+        - Directly usable as a reference for development and testing.
+
+---
+# Output Format Constraints
+- **Only output the final complete document content.**
+- Do not explain your thought process.
+- Do not include additional explanations.
@@ -0,0 +1,19 @@
+# 🤖 telegram-dev
+
+> Telegram Bot Development Practical Experience
+
+## Project Background
+
+Problems and solutions encountered in Telegram Bot development, mainly involving message formatting, Markdown rendering, etc.
+
+## Document List
+
+| File | Description |
+|:---|:---|
+| [Telegram Markdown Code Block Format Fix Log 2025-12-15.md](./Telegram%20Markdown%20Code%20Block%20Format%20Fix%20Log%202025-12-15.md) | Telegram Markdown code block rendering issue fix |
+
+## Tech Stack
+
+- Python
+- python-telegram-bot
+- Telegram Bot API
@@ -0,0 +1,42 @@
+# telegram Markdown Code Block Format Fix Log 2025-12-15
+
+## Problem
+
+Error when sending message after chart generation:
+```
+❌ Chart generation failed: Can't parse entities: can't find end of the entity starting at byte offset 168
+```
+
+## Cause
+
+The Markdown code block format in the `header` message in `bot.py` is incorrect.
+
+The original code used string concatenation, adding `\n` after ```, which prevented the Telegram Markdown parser from correctly recognizing the code block boundary:
+
+```python
+# Incorrect usage
+header = (
+    "```\n"
+    f"{filename}\n"
+    "```\n"
+)
+```
+
+## Fix
+
+Changed to use triple-quoted strings, ensuring ``` is on its own line:
+
+```python
+# Correct usage
+header = f"""Report in attachment
+```
+{filename}
+{ai_filename}
+```
+"""
+```
+
+## Modified File
+
+- `services/telegram-service/src/bot.py` lines 293-308
+