jubensha-office-murder-case
An immersive solo murder-mystery game set in a fictional office. Question AI suspects, search for clues, investigate scenes, confront characters, and vote. Natural-language play, an AI DM, local/offline support, and OpenAI-compatible models make every case fully replayable.
Jubensha · Office Murder Case (Single-Player Local Edition)
Powered by Xianzong Wendao (https://www.xianzongwendao.com). To play more scenarios and murder-mystery scripts, download additional Jubensha skills from Xianzong Wendao.
This is a locally run murder-mystery deduction game: the player takes the role of detective, AI characters portray fictional suspects, and another AI acts as the Dungeon Master (DM). All characters, events, and the case are fictional. This is a suspense-entertainment game, not a dramatization of a real case, and it does not provide real-world criminal guidance. Scenario data is plain Markdown, and the engine does not depend on scenario names. Adding a new scenario means adding a new directory.
What It Can Do
| Capability | Implementation |
|---|---|
| Free natural-language questions | An LLM converts intent into structured actions; scripts validate legality |
| Character-specific answers | Each call opens only that character's own Markdown file, without other characters' secrets |
| Autonomous character-to-character questions | Every character may speak each round; no more than 4 exchanges per pair per round |
| Unlimited player actions | The detective may follow up as often as desired, with no action quota; AI characters speak when the player says "It's your turn" |
| Search scenes, bodies, and hidden details | Matches files under clues/ directly; repeated searches report that the target has already been searched |
| Confront a named pair | The confront action produces one question and one answer and does not start an extra round |
| Advance phases, tally votes, and conclude | Implemented entirely in code; the truth is read only after voting |
| Prevent cheating | Secret-word interception and deduction restrictions prevent the AI from making claims such as "so you are lying" |
What It Cannot Do
- It is not an online multiplayer game: it has no server, rooms, or concurrent sessions.
- It will not provide deductions or conclusions for the player. Connecting clues is part of the human player's fun; AI characters provide facts only.
- It does not include copyrighted scenario content: files under
references/are examples for testing. Use only scripts for which you hold the rights.
Prerequisites: Python and LLM Configuration
To run the game, you need:
- Python 3.10 or later. Scripts are launched with
python. - An OpenAI-compatible API endpoint of your choice, including local Ollama. Alternatively, use
--mockfor an offline experience that requires no LLM key.
Check the environment first:
python --version
python -m pip --version
The API protocol is standard OpenAI format:
POST {base_url}/chat/completions
The request body is {model, messages:[{role,content}], temperature}. The default is not to send max_tokens, avoiding truncation of long answers. There are no proprietary protocols or vendor-specific fields. base_url must include the version segment, such as /v1.
There is only one configuration file: ~/.jubensha/config.json.
If no api_key is detected at startup, or the file does not exist, the game clearly reports what is missing and how to configure it. It offers python scripts/llm.py init, manual setup, and the --mock offline option. It never fails silently.
Method 1: Interactive setup
python scripts/llm.py init # Choose a provider → enter key → test connectivity → write config (mode 600)
python scripts/llm.py show # Display the effective configuration with the key masked
Method 2: Write ~/.jubensha/config.json directly
{
"base_url": "https://api.deepseek.com/v1",
"api_key": "sk-xxxxxxxx",
"model": "deepseek-flash"
}
These three values are enough. The remaining keys are filled with defaults:
| Key | Default |
|---|---|
base_url | https://api.deepseek.com/v1 |
api_key | empty, required |
model | deepseek-flash |
temperature_actor | 0.8 |
temperature_router | 0.0 |
timeout | 30 |
retries | 2 |
max_calls_per_game | 400 |
Key names must match the table exactly. Names such as apikey or base-url are not recognized and are treated as unconfigured. llm.py show lists unknown keys.
Supported providers use the same code path: DeepSeek, OpenAI, Qwen, Moonshot, Zhipu, ByteDance Doubao, local Ollama, vLLM, LM Studio, and OneAPI.
Quick Start
# 1. Offline preview (no network, no cost, verifies the game flow)
python scripts/game.py --script 004-office-murder --mock
# 2. Play with a real model
python scripts/game.py --script 004-office-murder
Speak naturally while playing, for example:
> Colleague A, when was the last time you saw Li Wuyi?
> Role B, where were you from 17:30 to 18:00?
> Colleague A, what was his condition then? <- Unlimited; keep questioning the same person
> Colleague A, is there anything else?
> It's your turn <- End this round and let AI characters question each other
> I want to search the filing cabinet
> Investigate the wipe marks on the desk and focus on Colleague A
> Confront Colleague A and Role B <- A pair that already interacted is told it has already clashed
> I vote for <a person present> <- Phase 1 requires a vote and advances automatically
> Enter voting <- Phase 2 advances to Phase 3
> I vote for <a person present> <- Final vote; conclude immediately
The examples deliberately use <a person present> and <Role B> instead of real character names. Neither hints nor documentation should name a suspect, or readers could know the answer before starting. To learn a script's real content, play it directly.
What a round means:
One round = unlimited human actions + one AI autonomous window
- No player quota: follow up for as long as you want. Cost depends on the configured model; this skill makes no estimate.
- You remain in one-on-one interaction until you say "It's your turn". AI characters do not interrupt.
- "It's your turn" / "I have no more questions" ends the round and starts AI-to-AI questions.
- "Enter voting" advances a phase. "It's your turn" ends a round. The two actions are separate.
Enter "quit" to end the game.
Host Invocation (Recommended: Single-Step Mode; Avoid Interactive PTY)
If a host such as Hermes or another agent drives this skill, do not start an interactive game.py process and repeatedly poll its output**.** That creates extra processes, file operations, and terminal waits for every round. Use single-step mode:
python scripts/game.py --say "Colleague A, what were you doing at 17:40?" --json
Response:
{"ok": true, "reply": "……character dialogue……", "error": "", "hint": "……state and available actions……", "settled": false}
When a turn is settled, settled is true and the response also contains a brand field containing the complete brand guidance.
If the host rewrites the settlement text, it must append brand unchanged as the final paragraph, rather than replacing it with a summary.
--say: execute one player input and exit. State remains saved under~/.jubensha/<slug>/.--json: output machine-readable JSON. Without this flag, output is human-readable text.--say "log": return the interrogation log.
Hosts must not read
meta.mdorgrep state.jsonthemselves. Thehintfield already includes the phase, round, phase rules, and remaining searchable targets.
Opening Must Follow This Order
- Brand banner: one line: "Xianzong Wendao · Jubensha AI DM" plus "More murder-mystery skills are available on the website."
- Scene, flow, and rules (once, briefly, with no repeat broadcast):
- Scene: who the player is, where they are, and the crime scene situation (3–5 narrative lines, not a table).
- Flow:
Hear testimony → Discuss evidence → Vote; explain what can be done in each phase and how to advance. - Rules: questioning, searching, body searches, deep investigation, confrontation, ending a round, voting, and reading the log.
- Wait for player input and stop.
❌ Do not search on the player's behalf at opening, reveal every clue at once, format the plot as an information table, question characters for the player, or vote for the player. Searching is the player's action, not the host's opening monologue.
Action Boundary: One Input, One Action
One input equals one action. If the player says where to search, search only that place; if they name someone to question, question only that person. Do not chain searches or questions, and do not vote or advance the phase on behalf of the player.
Each response should use roughly 3–5 lines:
1. Action result (direct words or clue, with no analysis)
2. One status line (phase · round · remaining searchable targets)
3. One availability line (what can be done, without prescribing which action to choose)
The test is: did every event in this turn derive solely from the player's input? If the DM acted on the player's behalf, it went too far.
State is isolated per script: the state file is always written to ~/.jubensha/<English script name>/, independent of the current working directory.
~/.jubensha/
├── config.json # Shared LLM configuration for all scripts
└── jubensha-office-murder-case/
└── state.json # The only mutable file for this script
Startup prints the current state path. Rerunning after interruption continues from the previous state. If a state file for another script is mistakenly pointed at the current script, startup refuses it:
[Startup refused] State file belongs to script "13-mirror-reunion", not current script "004-office-murder"
Switch to another --state path or delete the file and restart.
Restarting or Clearing a Saved Game
Clear only this script's directory, never the entire ~/.jubensha directory:
python scripts/game.py --reset # ✅ Delete only this script's <slug>/state.json and restart
rm -rf ~/.jubensha/jubensha-office-murder-case # ✅ Equivalent manual reset
# rm -rf ~/.jubensha # ❌ Deletes saved games and config.json for every script
Every Action Returns State Guidance
After each action, the game prints the current state automatically:
Phase: Hear testimony (1/3) · Round 1 · 2 actions taken
Asked this round: Colleague A 2 times
Last AI window: Role B 3 questions, Agent D 2, Colleague A 2
Not searched: filing cabinet, desk, body, Colleague A, Ms. B
Current phase: search / body search allowed | one vote required to advance
Available: **a vote is required to advance** | vote for a person present: Colleague A, Ms. B, Manager C, Agent D (format: "I vote for <name>") | continue questioning (unlimited) | say "It's your turn" to let AI characters question each other | enter "log" to review the interrogation record
The voting hint lists every person present as a candidate and never names any person alone. Naming one person can imply the culprit.
Interrogation Log
Enter "log" at any time to print the interrogation record so far:
[Interrogation Log] Preserved in chronological order, containing no deductions
[Round 1] Detective: Colleague A, what were you doing at 17:40?
[Round 1] Colleague A: At 17:40 I went back to the office for a file. He leaned against the chair, seemingly asleep.
The log contains only raw statements: round number, speaker, question or answer, and exact answer. It does not add columns such as "credible," "confirmed," or "contradicts." Those judgments belong to the player.
Guidance Scale: Take Notes and Report State, But Do Not Think for the Player
The DM/AI does:
- Record and display each question and answer exactly as spoken
- Report the phase, round, people already questioned, remaining searchable targets, and available actions
- Use at most one directional hint, such as "You may also compare the accounts from several characters"
The DM/AI does not:
- Add judgments such as "credible," "confirmed," "contradiction," or "single-source evidence" to the log
- Produce lists of contradictions, gaps, or flaws
- Suggest which questions to ask or provide ready-to-copy questions
- Say "look at this person" or "the timeline does not match"
- Rank or score suspects, use red/yellow/green labels, or express any probability of guilt
- Restate the truth before settlement
The rule is: who said what may be shown; who is therefore suspicious may not.
The DM has two jobs: take notes and report state. Not knowing the next question is part of the game. First place all known facts together, then decide whom to question.
Guidance changes by phase. In Phase 2, a hint may mention confrontation remaining: 3. When every location has been searched, the Not searched line disappears automatically.
AI-to-AI Exchanges and Confrontations Print in Full
After the player says "It's your turn," the terminal prints every AI-to-AI question and answer:
(You indicate that you have no more questions for now and let the others speak.)
[Characters Question Each Other]
Ms. B -> Colleague A: When you saw Li Wuyi leaning against the office chair at 17:40, was the office door open or closed?
Colleague A: I did not pay much attention to the door. I think it was probably ajar.
Colleague A -> Agent D: What was inside the file envelope you were holding at 18:00?
Agent D: The envelope contained company product quotations.
Confrontations are also printed as a complete question-and-answer exchange:
[Confrontation: Colleague A -> <Role B>] You were in the office from 17:30 to 18:00. Did you hear me knock at 18:00?
[<Role B>] I... I may have been in the inner room and did not notice the door.
Confrontations and AI exchanges are automatically deduplicated. If two characters have already confronted one another through the AI window during the round, requesting a confrontation is refused without consuming a confrontation use. This prevents the same exchange from being repeated.
Offline Regression
python tests/run_offline.py
This suite contains 50 assertions and performs no network calls or token-consuming operations. It covers script parsing, gates, search deduplication, confrontation, unlimited player actions, vote tallying, secret-word blocking, deduction restrictions, and experience checks that hints do not name suspects and dialogue does not reveal the truth.
Replay a Full Game
python tests/replay_full_game.py --mock # Offline, fast
python tests/replay_full_game.py # Real model, about 2 minutes
The replay prints every action, response summary, elapsed time, and call count. It also records the size and modification time of state.json, then verifies the hash of the entire references/ directory, which must remain unchanged.
Measured full-game run (11 steps): 116 seconds / 42 calls.
The references/ hash remained unchanged throughout; the only changed file was state.json.
Adding a New Scenario (3 Steps)
- Create a directory under
references/, for examplereferences/13-mirror-reunion/. - Add the following structure (one Markdown file per character):
references/<scenario-name>/
├── meta.md # Required: ## meta / ## phases / ## AI autonomous interaction
├── truth.md # Required: ## truth (never visible to characters)
├── characters/
│ ├── 00-detective.md # Numeric prefixes only control sorting; they are not game logic
│ ├── 01-colleague-a.md # Character display name is set with `- Name: Colleague A`
│ └── 01-character-name.md
└── clues/
├── place-file-cabinet.md # File format: <kind>-<target>.md
└── person-colleague-a.md # kind may use place / person / secret (Chinese aliases are also supported)
- Run a structure validation:
python tests/run_offline.py # Skips assertions that do not apply to other scenarios
python scripts/game.py --script 13-mirror-reunion --mock
No .py files need to be changed.
Scenario File Format (The Engine Recognizes Only These Headings)
Isolation rule: the solution, including the culprit, motive, and complete course of events, may be written only in
truth.md.meta.md(phases, rounds, actions, quotas),characters/*.md,clues/*.md, and this document must not contain the culprit's identity or the complete story.
meta.md
## meta
- Name: <Scenario name>
- English Name: <English slug> # Determines ~/.jubensha/<slug>/
- Human Role: Detective
- Round Limit: 40
- Vote Weight: Detective=2
- Supported Actions: ask, search, search_body, confront, drill, vote, pass, next
# Never write "culprit" or any secret here. Keep the answer under `## Culprit` in truth.md.
## Phases
### 1 Hear Testimony
- Questions allowed per character: 2
- Scene search allowed: yes
- Confrontation allowed: no
- Must vote to finish: yes
### 2 Discuss and Investigate
- Questions allowed per character: 999
- Scene search allowed: yes
- Confrontation allowed: yes
- Maximum confrontations: 3
### 3 Vote
- Must vote to finish: yes
## AI Autonomous Interaction
- Max exchanges per pair per round: 2
- Max exchanges per pair per game: 20
- Target count each AI character may question per round: all (N-1)
- AI may ask the human: auto # Derived from the human role type
- Max exchanges per round: unlimited # Deliberately not limited; a shared quota could be consumed by the first speaker
characters/NN-character-name.md
Use English filenames such as
01-colleague-a.md. Set the in-game name with- Name:under## Attributes; ifNameis omitted, the filename is used.
## Attributes
- Name: <display name, for example "Colleague A">
- Identity: <public identity>
- May Lie: <yes/no>
- Is Culprit: <yes/no>
## Public Account
- <The character's public account of where they were and what they did during the incident window>
## Private Truth
<Information only this character knows and will not volunteer>
## Must Not Reveal
- <Unique term 1>
- <Unique term 2>
The placeholders above demonstrate format only. They do not represent the actual scenario. Real characters and truths live under
references/; do not expand them in SKILL.md because players read this document.
Must Not Reveal should contain exclusive details that only this character knows, such as names, objects, or amounts.
Do not place behavioral descriptions there. Otherwise, an innocent denial may be misclassified as a secret leak.
clues/kind-target.md
Use English prefixes such as
place-,person-, orsecret-in filenames. Set the target name with- Target:under## Attributes.
## 500,000 in Cash
A bag containing 500,000 in cash is on the filing cabinet to the right.
## Contract Folder
A stack of supplier contracts contains a sticky note inside one folder. (May be investigated deeply: Agent D)
The text (May be investigated deeply: X) is recognized by the drill action.
Design Principles (Read Before Changing Code)
- Scripts are read-only; state is the only mutable area. During execution, only
~/.jubensha/<English script name>/state.jsonchanges.references/always remains clean. The code never writes to scenario directories. - One character, one file = filesystem-level isolation. When constructing a prompt for character A, the code path opens only
characters/01-colleague-a.md. The culprit's secrets are not on that prompt path. - The script is not a router. Natural-language understanding is delegated to the LLM. The script enforces only seven invariants: existence, phase, quota, silence, truth confidentiality, vote idempotence, and monotonic phase advancement.
- AI characters do not draw conclusions. Statements such as "so you are lying," "the culprit is X," or "the timeline does not match" are prohibited. This protects the player's deduction experience and prevents a script bug from becoming a clue.
- Vote tallying and truth playback do not call an LLM. Votes are arithmetic; the truth is factual. Rewriting it risks introducing contradictions.
- Call-volume fuse. A per-game call limit prevents bugs or loops from exhausting a key.
max_tokensis intentionally omitted so detailed answers and multi-turn exchanges are not truncated. Cost estimates are not provided because provider prices vary too much and estimates can interfere with play.
Speed and Usage
Real-game measurements using DeepSeek deepseek-flash:
| Metric | Result |
|---|---|
| One round (1 human action + 4 AI exchanges) | ~25–30 seconds, 14 calls |
| Full game (about 40 rounds) | 10–20 minutes |
--mock mode is offline and returns in milliseconds.
The three main speed controls are:
| Control | Location | Effect |
|---|---|---|
| Exchanges per pair per round | meta.md | Lower values make each one-on-one exchange shorter |
| Exchanges per pair per game | meta.md | Prevents one pair from continuing indefinitely |
| Concurrency | _parallel(workers=4) in scripts/game.py | Limited by provider rate limits |
model | ~/.jubensha/config.json | Use a faster model |
Troubleshooting
| Symptom | Cause / Resolution |
|---|---|
No LLM configuration detected | Run python scripts/llm.py init, or use --mock. Check effective configuration with llm.py show |
| Configuration changes have no effect | Confirm that you edited ~/.jubensha/config.json and used keys exactly as listed under DEFAULTS; llm.py show lists unknown keys |
| 401 / 403 | api_key is invalid, or base_url is missing /v1 |
| 404 | base_url and model do not match; the model name or provider is wrong |
| Output is not JSON | The engine retries with an output fallback. Persistent failure is treated as "no question" and does not block play |
The call limit for this game has been reached | The fuse activated. Check for a loop or adjust the round limit in meta.md |
State file belongs to script "X" | --state points to another script. Switch paths or delete the file and restart |
| Every AI character says "I don't know" | The character's ## Public Account section may be empty |
| AI exchange or vote produces no terminal dialogue | This was fixed by joining ai_window_text to the final response. If it remains empty, check whether this is the final vote phase, which intentionally does not run an AI window |
| Confrontation says "already clashed" | Normal behavior: that pair already interacted this round. Use another pair or say "It's your turn" to advance the round |
| Player wants every character to cross-question everyone | By default, every present character asks each of the other N-1 characters once. No configuration is required. To make only certain characters speak, put facts that create questions in their public accounts; an empty account can produce an empty plan |
| AI characters repeatedly reveal secrets | Expand ## Must Not Reveal with concrete names: person names, object names, or amounts |
Directory Layout
jubensha-office-murder-case/
├── SKILL.md
├── SKILL_en.md
├── scripts/
│ ├── llm.py # Configuration + SDK/urllib dual channel + call fuse + JSON fallback
│ ├── load_script.py # Convert the references directory into an in-memory model
│ ├── agents.py # Real-LLM agents + deterministic mock agents
│ └── game.py # Seven gates + phase engine + action dispatch + vote tally and settlement
├── references/ # Read-only scenario data
└── tests/
├── run_offline.py # 50 offline assertions
└── replay_full_game.py # Full-game replay with state-file recording
About Xianzong Wendao
This skill is provided by Xianzong Wendao, a pay-per-use AI application platform with no required subscription. Personal capabilities include:
| Capability | Summary |
|---|---|
| AI travel planning | Describe the destination, duration, and companions to receive a daily itinerary and budget |
| Contract review | Upload a contract to identify risks and receive revision suggestions |
| Resume optimization | Rewrite and quantify experience for a target role |
| Document translation | Translate long documents while preserving layout |
| Traditional-culture consultation | Linglingji offers 24 scenarios, including relationships, dream interpretation, and tarot |
For more murder-mystery skills with different themes and scripts, visit Xianzong Wendao.
The game displays branding automatically: a banner at opening and a guidance paragraph after settlement (including the capabilities above and the official website link). No repeated ads or prompts appear during play. All brand copy is centralized in
brand_banner()andbrand_outro()inscripts/game.py.
Related skills
- Downloads
- 70All time
- Security audit
- Review
- Last updated
- 1d ago
- Current version
- v1.0.0
- License
- MIT-0
