bazi-persona

Bazi Persona

A persona can be generated from a birthday alone, without chat history.

Bazi Persona is a persona system that organizes Bazi chart calculation, fate-analysis knowledge, and real-world facts together.
The goal is not to generate a "label report," but to generate a persona product that can sustain conversation, be continuously updated, and allow switching analytical perspectives.

By default, follow the language of the user's current input; when the language is unclear, use Chinese first.

1) What this Skill does

This skill handles 8 types of things:

1. Create persona (calculate the chart first, then generate the persona)
2. Update persona (add facts, correct information, add relationship clues)
3. Normal mode chat (first speak naturally like this person)
4. Cheat mode chat (overlay fate analysis on the persona's tone)
5. Dynamic time-flow analysis (major periods/annual/monthly/daily/hourly)
6. Almanac/perpetual calendar query
7. Import external chats and extract candidate facts
8. Optional persona startup injection (SOUL/agent startup context)

1.1) When NOT to Use

The following scenarios are not suitable for this skill:

• When you only want pure small talk and do not need persona, Bazi, time-flow, or almanac information.
• When doing only general tasks (coding, document retrieval, translation, reports, etc.), a general skill should be used instead.
• When the key information needed to create/locate a persona is missing (at least the target subject must be clear, or provide name/gender/birth_date）。
• In high-risk decision-making scenarios such as medical, legal, and investment matters that require professional advice, this skill can only provide a reference perspective.

1.2) Command-line usage (for local debugging/file management)

Execute in the skill root directory:

npm i

Recommended method (compiled artifact):

npm run bazi -- --action inspect
npm run bazi -- --action inspect --slug xiao-a
npm run bazi -- --action delete --slug xiao-a

Equivalent method (run the CLI directly):

node dist/cli.js --action inspect

Development debugging (requires tsx):

npx tsx src/cli.ts --action inspect

Notes:

• The command line is mainly used for inspect/list/delete/help file management actions.
• Creating personas, updating personas, chatting, time-flow analysis, and almanac queries should preferentially be executed according to the tools + workflow below.

2) Tool description (input / output)

2.1 bazi_chart_tool

Purpose: Bazi chart calculation + fixed persona knowledge mapping (static).

Input parameters:

• name string required
• gender string required,male / female(compatible with 男 / 女）
• birth_date string required,YYYY-MM-DD
• birth_time string optional,HH:mm
• birth_location string optional
• calendar_type string optional,solar / lunar, default solar

Result description:

• Returns the complete chart result, subsequently used for persona generation, state analysis, and fate-analysis evidence references.

2.2 bazi_flow_tool

Purpose: Dynamic Bazi query (major periods / annual / monthly / daily / hourly).

Input parameters:

• chart object optional (pass the natal chart directly)
• persona_slug string optional (read the natal chart from the persona)
• base_dir string optional
• at string optional (such as 今天 / 昨天 / 2026-04-12）
• include_calendar boolean optional, default true
• lang string optional,zh / en / ja / ko

Result description:

• Returns the dynamic state at the target time point (current major period, phase offset, communication/judgment changes);
• Can include date almanac information (lunar calendar, heavenly stems and earthly branches, solar terms, auspicious and inauspicious activities, etc.).

2.3 persona_data_tool

Purpose: persona file data management (List / Search / Create / Query / Patch(Update) / Delete).

Input parameters:

• action string required:list / search / create / query / patch / delete
• base_dir string optional
• persona_slug string（query/patch/delete required)
• search_query string（search optional)
• create_payload object（create required)
• patch_payload object（patch required)

Result description:

• Returns the corresponding action result and latest state;
• in query/patch scenario returns the persona file location, for chat injection and subsequent updates.

2.4 memory_tool

Purpose: writing, updating, merging, and querying key memories and knowledge.

Input parameters:

• action string required:upsert / merge / delete / query
• persona_slug string required
• base_dir string optional
• memories array（upsert/merge required)
• merge_policy string optional:append / replace_same_key / higher_confidence_wins

Result description:

• Returns a write/update summary (added, updated, deleted, conflicts);
• after writing, the persona snapshot is refreshed, for use in subsequent chats and analysis.

2.5 calendar_tool

Purpose: perpetual calendar / almanac query.

Input parameters:

• at string optional (defaults to today)
• lang string optional

Result description:

• Returns the Gregorian calendar, lunar calendar, heavenly stems and earthly branches, solar terms, auspicious and inauspicious activities, and other information corresponding to the date.

2.6 chat_import_tool

Purpose: import external chat records and extract candidate facts.

Input parameters:

• source_type string required:text / json / ocr_text
• payload string or object required
• persona_slug string optional
• timezone string optional, default Asia/Shanghai
• max_candidates number optional, default 50

Result description:

• Returns structured candidate chat items and candidate memory items;
• after further AI filtering, they enter memory_tool and persona_data_tool.patch。

3) Workflow (by tool connection)

3.1 Creating a persona

Applicable scenario: the user creates a persona for the first time.

1. Extract basic information:name/gender/birth_date necessary;birth_time/birth_location/relationship optional.
2. Call bazi_chart_tool to get chart。
3. Based on chart + relationship + initial_facts generate profile/snapshot。
4. Call persona_data_tool(action=create) to write the persona file.
5. When there are additional facts, call memory_tool(action=upsert) to write key memories.
6. Return creation complete and guide the start of chat.

Key judgments:

• If any of name/gender/birth_date is missing, first ask the minimum follow-up questions.
• If a persona with the same name exists, first confirm whether to overwrite or use a new slug.

3.2 Updating a persona

Applicable scenario: supplementing new changes, correcting old information, adding relationship clues.

1. Use persona_data_tool(search/query) to locate the target persona.
2. Extract newly added facts and correction information from the input.
3. Use memory_tool(upsert/merge) to write memories.
4. Use persona_data_tool(patch) to refresh the snapshot and necessary profile fields.
5. Return an update summary.

3.3 Normal mode chat

Applicable scenario: the user speaks directly to a persona.

1. First determine whether the context already has the current persona (current_persona_slug）。
2. when already locked and the target has not been switched, directly persona_data_tool(query), without repeating search.
3. When there is no context or the user explicitly switches, first search then query。
4. Inject the base chat prompt (chat_base) and persona.md。
5. generate a reply; call only when persistence is needed memory_tool + persona_data_tool.patch。

Key judgments:

• When multiple personas match, confirm first; do not guess.
• In normal mode, prioritize natural conversation and do not proactively expand on fate-calculation terminology.

3.4 Persona Startup Injection (Optional)

Applicable scenarios: the user explicitly requests "start the chat according to this persona" or "write into SOUL.md/agent startup context".

1. First locate the target persona according to 3.3.
2. Generate the persona-specific startup prompt and inject it into the current session context.
3. The injection takes effect only for the target persona and does not contaminate other personas.

3.5 Cheat Mode Chat (Fate-Calculation Enhancement)

Applicable scenarios: the user says "turn on cheat mode", "look at it from the Bazi perspective", "analyze it according to fate calculation", etc.

1. First locate the persona according to 3.3 and inject the base content of normal mode.
2. Then overlay the cheat mode prompt (cheat_mode）。
3. inject as needed bazi_data.json。
4. when time points are involved, call bazi_flow_tool, and when date details are needed, supplement calendar_tool。
5. Keep the persona's tone in the output while also providing explainable grounds.
6. When the user turns off cheat mode, return to normal mode.

3.6 Dynamic Flow-Time Analysis

Applicable scenarios: the user asks "today's state", "why has it changed this week", or "whether a certain day is suitable for pushing forward".

1. persona_data_tool(query) Read the target persona.
2. bazi_flow_tool Pass persona_slug/chart + at。
3. supplement if necessary calendar_tool。
4. Output conclusion + grounds + rhythm suggestions.

3.7 Almanac/Perpetual Calendar Query

Applicable scenarios: only query date information, without involving persona.

1. Call calendar_tool（at can be empty; if empty, then today).
2. Return the lunar calendar, heavenly stems and earthly branches, solar terms, and suitability/taboo.

3.8 External Chat Import

Applicable scenarios: the user uploads WeChat chat records, chat screenshot text, or other historical conversations.

1. chat_import_tool Extract candidate information.
2. AI filters high-value candidates.
3. memory_tool Write key memories.
4. persona_data_tool.patch Refresh snapshot.
5. Return an import summary (written/skipped/conflicted).

4) Persona Directory (Code Default)

Default directory:<当前 skill 根目录>/personas

Each persona directory:

• personas/<slug>/persona.md: persona finished product (main chat injection file)
• personas/<slug>/bazi_data.json: structured Bazi data
• personas/<slug>/memory.json: structured memory data
• personas/<slug>/history.json: structured historical sessions/import records

Override priority:

1. explicit base-dir
2. environment variable BAZI_PERSONA_HOME
3. default <skill-root>/personas

5) Quality Standards

A high-quality Bazi persona at least satisfies:

1. It feels like a person, not template labels.
2. It can start chatting immediately after creation.
3. After updates, it can naturally absorb real-world changes.
4. Switching between normal mode and cheat mode is natural, without contaminating each other.
5. Key judgments can return to Bazi evidence and real-world information.