内容
# hersona
[**English**](./README.md) · [日本語](./README.ja.md)
> **Build once. Keep personality everywhere.**
> *Composable personalities for every LLM.*
**346 reusable character attributes** for AI agent personas — compose a
persona from personality / speech / archetype / visual / hobby templates,
**measure** that it actually holds up in conversation, and port it to any
LLM or agent framework. **MIT** (code) + **CC0** (templates). CLI, MCP
server, and Hermes Agent skill.
[](https://pypi.org/project/hersona/)
[](https://pepy.tech/project/hersona)
[](./LICENSE)
[](./LICENSE-CC0.txt)
[](#use-as-an-mcp-server-optional)
[](https://shiro-0x.github.io/hersona/)
[Docs](https://shiro-0x.github.io/hersona/) · [PyPI](https://pypi.org/project/hersona/) · [Repository](https://github.com/shiro-0x/hersona)
## 快速开始（30秒）
```bash
pip install hersona
hersona blend personality/tsundere speech/keigo --weight strong # injection block → stdout
hersona export personality/tsundere speech/keigo --format openai_assistants > persona.json
hersona persistent personality/tsundere speech/keigo --target claude # writes CLAUDE.md
hersona bench tsundere keigo --cost-only # measure the injection cost
```
No install? The **[live demo site](https://shiro-0x.github.io/hersona/app/)**
runs the attribute catalog, blending, and a 9-question diagnostic quiz in the
browser (auto-detects EN/JA).
## 有测量，不只是感觉
Personas drift: they lose their voice mid-conversation, get talked out of
character, and cost tokens every turn. hersona ships a deterministic
benchmark (`hersona bench` — no LLM, no embeddings, reproducible) so those
are numbers instead of impressions:
| `tsundere` + `keigo` | mild | moderate | strong |
|---|---:|---:|---:|
| Injection cost (measured) | 1751 chars (~437 tok) | 1931 chars (~482 tok) | 2039 chars (~509 tok) |
- **维护率 + 衰减曲线** — score any conversation transcript
turn-by-turn against the blend's speech patterns.
- **锁定抵抗率** — bundled persona-override attack scenarios
("ignore your system prompt", "become another character") quantify how well
`personality/persona_lock` holds under pressure.
- **Token 成本** — the exact per-context price of your blend, per weight.
First official run (2026-07-11, minimax/MiniMax-M3, tsundere+keigo moderate):
`a_lock` mean score 9.8 vs `a` 8.6 vs hand-written baseline `b` 8.0 vs no-persona
`c` 2.4 on the persona-override attack scenario — a small but consistent
direction for the lock, well below the surface threshold (full table with
all bad numbers published as-is in `docs/BENCHMARKS.md`).
Commands, honest caveats, and the run-it-yourself comparison recipe:
[`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md).
## 直接应用于您的代理配置
`hersona persistent --target` writes the persona straight into the
convention file of your coding agent:
| Target | Writes | Used by |
|---|---|---|
| `--target claude` | `CLAUDE.md` | Claude Code |
| `--target codex` (alias `agents`) | `AGENTS.md` | Codex / AGENTS.md-compatible agents |
| `--target cursor` | `.cursorrules` | Cursor |
| `--target gemini` | `GEMINI.md` | Gemini CLI |
`hersona export` hands the same persona to everything else — `json`,
`messages` (chat array), `markdown`, `openai_assistants`,
`langchain_system_message`.
## 为什么选择Hersona？
System-prompt authoring is the most copy-pasted code in AI agents.
Most teams either hand-roll long persona descriptions or steal prompts
from Discord threads — and the resulting characters drift, contradict
themselves, or lose intensity mid-conversation.
Hersona gives you a typed, schema-validated library of 346 character
attributes you can mix and match:
- **性格（43）** — tsundere, kuudere, yandere, airhead, intellectual, …
- **语言风格（140）** — kansai_ben, keigo, mandarin_casual, banmal, british_en, valley_girl_en, …
- **原型（66）** — heroine, mentor, rival, idol, shrine_maiden, school_nurse, knight, villain, …
- **视觉（46）** — silver_hair, glasses, petite, glamorous, animal_ears, heterochromia, scar, …
- **兴趣爱好（51）** — cooking, gamer, music, reading, sports, calligraphy, astronomy, …
Each attribute declares `core_traits`, `catchphrases`, `tone`, and an
explicit `compatible_archetypes` / `conflicts_with` matrix — so the
blend engine can detect incompatible mixes and surface warnings (persistence
paths may reject conflicting blends), while you tune intensity per attribute
(`mild` / `moderate` / `strong`).
Use it with any Hermes agent, OpenAI-compatible API, Claude, local LLMs, LangChain,
AutoGen, CrewAI—or as a drop-in MCP server for Claude Desktop.
## Hersona 是什么？
Hersona is a **persona layer** for defining and maintaining a character's personality and speech style across conversations.
It helps AI systems stay consistent as a **character, branded voice, roleplay partner, virtual influencer, mascot, or conversational persona**.
| You need | Reach for |
|---|---|
| One fixed persona, never switched | A hand-written system prompt — hersona adds no value here |
| Several personas, swapped per session/user, with intensity control | **hersona** (`blend` / `soul` / `persistent`) |
| To *know* whether a persona held up over a long conversation | **hersona** (`measure` / `verify_intensity` — deterministic, not vibes) |
| Conflict-free trait combinations at scale (many attributes × many combos) | **hersona** (`compatible_archetypes` / `conflicts_with` matrix) |
| Better reasoning, retrieval, or tool-calling | LangGraph, OpenAI Agents SDK, LlamaIndex, Semantic Kernel — hersona's `export` formats hand a persona *into* these, it doesn't replace them |
| A one-off character for a single project | Your own YAML/prompt is fine too — hersona helps once you have more than one persona, or need to reuse the same ones across projects |
See [`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md) for how `hersona bench`
measures persona-maintenance rate and injection token cost, and how to run
your own hersona-vs-baseline comparison rather than take our word for it.
## 更多命令
```bash
hersona list # browse all 346 attributes
hersona show personality/tsundere # inspect one attribute
hersona recommend # diagnostic quiz → recommended blend
hersona measure tsundere keigo --weight strong --input out.txt # score one text
```
For the full programmatic API, see [`docs/PUBLIC_API.en.md`](./docs/PUBLIC_API.en.md).
## Guides
Cross-persona playbooks (not attribute templates):
- [自我介绍](./docs/guides/self-introduction.md) — public intro rules, privacy, checklist
- [日本語](./docs/guides/self-introduction.ja.md) · [Index](./docs/guides/README.md)
```bash
hersona lint-intro --canonical --allow-handle YOUR_X --text "..."
hersona soul personality/kuudere speech/soft \
--memory-file examples/self-intro-memory.json \
--with-self-intro-guide --lint-self-intro-strict --allow-handle YOUR_X \
--profile myagent --force
```
## 安装（Hermes Agent）
No registry approval needed — works right now via tap:
```bash
hermes skills tap add shiro-0x/hersona
hermes skills install hersona
hermes skills install hersona-initializer
```
## License 结构
The repository is split into two layers, each under a different license:
| Scope | License | Notes |
|---|---|---|
| `scripts/`, `schema/`, `pyproject.toml`, etc. (code) | **MIT** | `LICENSE` |
| `attributes/**/*.yaml` (general attribute templates) | **CC0 1.0** | `LICENSE-CC0.txt` — public domain dedication |
| `personas/**/*.yaml` (persona packs, recipes of named blends) | **CC0 1.0** | `LICENSE-CC0.txt` — public domain dedication |
## 当前覆盖范围
**346 attributes** across 5 categories. The two biggest expansions are
**speech 31 → 140** (the **+103** phased registers through v1.4.x, plus **+6** native zh/ko in v1.5.0)
and **archetype 9 → 66 / visual 5 → 46 / hobby 5 → 51** (batch expansions through v1.7.x
covering roles, appearances, and hobbies not in the original template set).
Speech's history is structured in five historical phases plus the v1.5.0 wave:
| Phase | Count | What | Examples |
|---|---:|---|---|
| **Phase 0/8** (pre-existing) | 26 | Foundational Japanese speech + English registers + `archaic_otaku` | `kansai_ben`, `keigo`, `gyaru`, `british_en` |
| **Phase 1: regional dialects** | 36 | All major Japanese regions including Kyushu/Okinawa | `hokkaido_ben`, `nagoya_ben`, `osaka_ben`, `okinawa_ben` |
| **Phase 3: character voices** | 25 | Era, Z-gen, subculture, classic character roles | `warawa`, `vtuber`, `yankee`, `business`, `akuma_oujo` |
| **Phase 4: foreign languages** | 24 | English dialects (10) + translation-style registers (14) | `aussie_en`, `valley_girl_en`, `mandarin`, `korean`, `french` |
| **Phase 5: anime-genre voices** | 18 | School-romcom, isekai, fantasy, subculture-isekai | `osananajimi`, `imouto`, `mesugaki`, `densetsu_no_yuusha`, `villainess` |
| **v1.5.0: native zh/ko** | 6 | `content_lang` zh/ko speech (not ja-flavored translation) | `mandarin_casual`, `keigo_zh`, `taiwan_mandarin`, `banmal`, `jondaetmal`, `seoul_casual` |
Total breakdown: **personality 43 + speech 140 + archetype 66 + visual 46 + hobby 51 = 346**.
## 概述
An open-source project that systematizes the speech and personality of anime characters and distributes them
as a template collection that can be injected into an AI agent's system prompt.
- Provides **attribute templates** (`attributes/<category>/<name>.yaml`)
- A user (or agent) builds the personality of any character by assigning the attributes they need
## 用法
### 与 Hermes Agent 配合使用
Attach attributes via `/hersona <category>/<name>`:
```
/hersona # listing + usage help
/hersona list # list available attributes
/hersona show personality/tsundere # details of a given attribute
/hersona personality/tsundere single # attach a single attribute
/hersona personality/tsundere speech/keigo multi # blend multiple attributes
/hersona default # detach
```
#### 常见配方
**Make a character more tsundere without changing their archetype**
```
/hersona personality/tsundere single
```
Attaches only `tsundere` (with `weight: moderate` by default). The next
agent turn speaks with classic tsundere traits — distant on the surface,
warmer underneath — without altering the existing archetype or speech
register.
**Stack a keigo speech layer on top of an already-attached personality**
```
/hersona speech/keigo single
```
Adds `speech/keigo` to the current attachment. Useful when the existing
persona should switch to polite/formal speech (customer-support scene,
noble-archetype roleplay, etc.).
**Blend a multi-attribute persona from scratch```
```
/hersona personality/tsundere speech/keigo multi
```
Composes a brand-new persona from `tsundere` + `keigo` and replaces any
existing attachment. The `blend` engine checks `compatible_archetypes` /
`conflicts_with` first — if the two attributes fight each other (e.g.
`yandere` + `airhead`), you'll get a warning suggesting a replacement
before the attach goes through.
**Control intensity per attribute**
```
/hersona personality/tsundere strong speech/keigo mild
```
`strong` makes tsundere traits dominant (catchphrases land hard, "べ、
別にあんたのためじゃない" frequency goes up); `mild` keeps keigo as
background flavor. Intensity is per-attribute, so you can mix-and-match
within a single command.
**Save a blend as a reusable preset**
```
/hersona save my_tsun personality/tsundere speech/keigo --weight strong
/hersona load my_tsun
```
`save` writes the recipe to `~/.hermes/presets/my_tsun.yaml`; `load`
replays it on demand without re-typing the full command. Saved presets
live in the user namespace and never pollute the public `attributes/`.
**Detach everything and return to the base agent**
```
/hersona default
```
Strips every attached attribute in one shot. Useful between sessions or
when starting a fresh blend from a known clean state.
**Preview without attaching```
```
/hersona preview personality/tsundere speech/keigo --weight strong
```
Renders the injection block + sample phrases (no LLM call) so you can
review the result before committing it to the live agent context.
See [skills/hersona/SKILL.md](./skills/hersona/SKILL.md) for Hermes skill
behavior notes, and [skills/hersona/REFERENCE.md](./skills/hersona/REFERENCE.md)
for verification checklists, version history, and edge-case recipes
(saved-blend persistence, intensity measurement, MCP export). For CLI truth,
prefer `hersona --help`, this README, and [`docs/PUBLIC_API.en.md`](./docs/PUBLIC_API.en.md).
#### 专业操作模式 / 用例
`--use-case` layers a professional control-plane prompt on top of the selected
personality / speech attributes. The persona remains expressive, while the agent
gets task discipline for real work.
```bash
hersona use-case list
hersona use-case show programmer
hersona blend personality/tsundere speech/keigo --use-case programmer
hersona soul personality/puppyish speech/keigo archetype/heroine --use-case planner --force
hersona export personality/tsundere --format openai_assistants --use-case product_manager
```
Initial public use cases (20 total, see `docs/PERSONA_PACKS_DESIGN.md` section6):
**Initial 8 (Phase 1)**: `programmer`, `planner`, `research`, `marketing`,
`product_manager`, `qa_reviewer`, `data_analyst`, `customer_support`.
**Added 12 (PR-A W2, Phase 2)**:
`frontend_developer`, `backend_architect`, `devops_engineer`, `security_reviewer`,
`tech_writer`, `executive_assistant`, `hr_recruiter`, `tutor`, `creative_writer`,
`game_master`, `community_manager`, `streamer_copilot`.
`hersona soul ... --use-case <id>` and `hersona persistent ... --use-case <id>`
write the Operating Mode into generated SOUL.md content, so professional task
discipline survives future persona regeneration instead of living in a manual
append-only note. Regeneration also preserves user-owned text below
`<!-- hersona:gen-end -->`.
#### Persona packs for Hermes (recipe catalog)
A persona pack is a **named recipe** that combines one or more attributes into
a reusable persona. The pack declares `persona_name` / `blend` / weight /
`use_case`; the injection block is rendered at install time from the named
attributes, so attribute updates propagate automatically.
```bash
hersona personas list # 14 bundled packs (keigo_support, gyaru_community, …)
hersona personas show keigo_support # blend + preview
hersona personas install keigo_support --auto-config
hersona personas install keigo_support british_pm --apply # last one becomes agent.personality
hersona personas use keigo_support # switch active personality
hersona recommend --install-persona my_pack # bridge: diagnose → register in one shot
```
Shipped packs (14 total, see `docs/PERSONA_PACKS_DESIGN.md` §6):
| Pack | Blend | Use case |
|---|---|---|
| `keigo_support` | diligent + keigo | customer_support |
| `kansai_marketer` | genki + kansai_ben | marketing |
| `tsundere_reviewer` | tsundere + blunt | qa_reviewer |
| `kuudere_analyst` | kuudere + soft | data_analyst |
| `genki_planner` | genki + casual_en | planner |
| `sensei_writer` | intellectual + sensei | tech_writer |
| `butler_assistant` | diligent + butler | executive_assistant |
| `onee_recruiter` | sociable + onee_kotoba | hr_recruiter |
| `samurai_devops` | stoic + samurai_lol | devops_engineer |
| `vtuber_streamer` | playful + vtuber | streamer_copilot |
| `miko_tutor` | serious + miko | tutor |
| `british_pm` | pragmatist + british_en | product_manager |
| `gyaru_community` | sociable + gyaru | community_manager |
| `warawa_gamemaster` | mysterious + warawa | game_master |
**What sets persona packs apart from generic agent catalogs:**
| Generic agent catalogs | hersona persona packs |
|---|---|
| Role only, no personality control | Persona × use-case × **intensity dial** |
| Static templates | Conflict-checked blends, **measurable maintenance** (incl. lock resistance under persona-override attacks) via `hersona bench` |
| Generic tool plumbing | **Native for Hermes' multi-personality registry** |
All 14 bundled packs pass `validate_persona()` (zero errors) on every CI run
via `tests/test_personas.py::test_all_shipped_personas_validate_clean`; the
table above is the authoritative list — schema additions must follow the
`docs/PERSONA_PACKS_DESIGN.md` §6 contract.
### 从命令行界面（CLI）使用
在执行 `pip install hersona`（Python >= 3.11）后，`hersona` 命令即可使用。
对于本地开发，可以使用 `pip install -e .` 或 `python -m hersona.cli`：
```bash
hersona list # 列出可用属性（公开 + 用户）
hersona show tsundere # 属性详情
hersona matrix --json # 以 JSON 格式导出兼容性矩阵
hersona blend tsundere keigo --weight strong # 将属性混合成注入块（带有强度）
hersona blend airhead intellectual --suggest # 在冲突时，建议非冲突替换（标准错误）
hersona diff tsundere dandere # 比较两个属性（共同 / 独有字段 + 关系）
hersona preview tsundere kyoto_ben --weight strong # 注入块 + 示例短语（无大语言模型）
hersona recommend # 诊断测验 -> 推荐（交互式；英文界面跳转到英文语音）
hersona recommend --answers distance=1,speech=0,role=1 --apply # 同时打印注入块
hersona recommend --export openai_assistants > my_agent.json # 测验结果直接导出到任意格式（无需重新输入）
hersona recommend --soul --profile myagent # 测验结果直接导出到 SOUL.md (--dry-run / --force)
hersona recommend --save from_quiz # 测验结果保存为可重用的预设
hersona create --category personality --name my_attr \
--display-ja マイ属性 --display-en MyAttr \
--desc-ja 説明 --desc-en desc --example "..." # 创建属性并保存到用户命名空间
hersona measure kyoto_ben --weight strong --text "ようおいでやすどす" # 输出强度指标
hersona measure tsundere heroine --weight moderate --input out.txt # 混合的强度指标
hersona bench tsundere keigo --demo --turns 6 # 人物维护率 + token 成本自我检查（参见文档/BENCHMARKS.md）
hersona save my_tsun tsundere keigo --weight strong # 保存混合预设为可重用的命名预设（本地）
hersona presets # 列出已保存的混合预设
hersona load my_tsun # 重放已保存的预设为注入块
hersona export tsundere keigo --format messages # 为其他框架导出混合预设（json/messages/markdown）
hersona soul puppyish keigo heroine --use-case planner --force # 编写 SOUL.md 并具有持久运行模式
hersona update # 从仓库下载最新的属性数据
hersona update --ref v1.8.0 # 指定分支 / 标签 / 提交 SHA（默认为 main）
hersona update --clear # 删除下载的数据并恢复到捆绑模板
```
用户创建的属性保存在 `~/.hermes/attributes/`（默认）或 `HERSONA_USER_DIR` 指定的目录下，并且不会与公共 `attributes/` 混合。
`hersona update` 在不重新安装软件包的情况下保持属性模板更新。当通过 `pip`/wheel 安装时，`attributes/` 和 `schema/` 在构建时捆绑在一起，因此上游的添加操作仅在重新安装后生效。`hersona update` 从仓库将最新的 `attributes/` 和 `schema/` 下载到本地数据缓存（默认为 `~/.hermes/data/` 或 `HERSONA_DATA_DIR`），优先于捆绑模板。`hersona update --clear` 删除缓存并恢复到捆绑数据。下载仅使用 Python 标准库（无额外依赖）。
默认情况下，`hersona update` 通过从单独的 GitHub 交付路径获取的 SHA-256 清单（`checksums.json`）验证下载内容，在不匹配时中止；参见 [SECURITY.md](./SECURITY.md) 以了解其保护的具体内容和未保护的内容。可以通过 `hersona update --no-verify` 跳过验证。
已保存的混合预设存储在 `~/.hermes/presets/`（默认）或 `HERSONA_PRESETS_DIR` 指定的目录下。预设仅是一个命名配方（`attributes` + `weight`）；`hersona load` 通过相同的混合引擎重放它，因此它始终反映最新的属性模板。
### 作为 MCP 服务器使用（可选）
将 hersona 暴露给支持 MCP 的代理（如 Claude Desktop），它们可以直接调用这些工具：
| 工具 | 功能 |
|---|---|
| `list_attributes` / `show_attribute` | 浏览目录 |
| `blend` / `export` | 组合并移交人物（`export` 支持所有 5 种格式） |
| `recommend_blend` | 诊断测验推荐（`export_format` 跳过第二次调用） |
| `compatibility` | 冲突 / 兼容性查找 |
| `measure_intensity` | 根据混合的强度带对一个响应进行评分 - 确定性，无需大语言模型 |
| `bench_transcript` | 对整个对话记录进行人物维护率 + 锁阻力评分 |
| `list_personas` | 浏览 14 个捆绑的人物包 |
| `install_persona` | 预览一个包的渲染注入块（dry-run - 不写入任何内容） |
`measure_intensity` 和 `bench_transcript` 让代理可以自行关闭：生成响应，评分，并自行纠正如果偏移了人物 - 相同的确定性评分器 `hersona measure` / `hersona bench` 在 CLI 上使用。`install_persona` 按设计仅为预览（无文件系统写入来自 MCP 调用）；实际上安装一个包仍然通过 CLI 的 `hersona personas install <name>` 进行。
```bash
pip install "hersona[mcp]"
hersona-mcp # 启动标准输入输出 MCP 服务器
```
服务器（`hersona.mcp.server`）是 `hersona.core` 的薄封装；工具逻辑位于 `hersona.mcp.tools` 中，可以单独使用。`mcp` 仅需要运行服务器，不需要使用库或 CLI。
### 与其他大语言模型配合使用
将 `attributes/<category>/<name>.yaml` 中的字段（如 `core_traits` / `catchphrases` / `tone` / `description_en`）直接粘贴到系统提示中。
混合多个属性时，通过每个 YAML 的 `compatible_archetypes` / `conflicts_with` 检查兼容性。
## 数据格式
```bash
attributes/
├── personality/ # 人物属性（43: 日语基础 35 + 英语原生 5 + 日语基础 hautaine + 日语基础 sociable + persona_lock）
├── speech/ # 言语属性（140: 日语内容 119 + 英语 15 + 原生中文/韩语 6）
├── archetype/ # 原型属性（16）
├── visual/ # 视觉属性（5）
└── hobby/ # 爱好属性（5）
```
每个属性 YAML 都符合 [`schema/attribute.schema.json`](./schema/attribute.schema.json)。
### 属性模板（`attributes/`）
一个通用属性标签的模板集合，附加到角色配置文件，由 [schema/attribute.schema.json](./schema/attribute.schema.json) 验证。目前总共定义了 346 个：人物 43 / 言语 140 / 原型 66 / 视觉 46 / 爱好 51（参见 [attributes/](./attributes/) 下的内容）。
言语类别包含 140 个条目：119 个日语内容注册（`content_lang: ja`，包括基础言语风格，地区方言，翻译风格外国语言注册，动漫/亚文化声音，`archaic_otaku` 和 `okinawa_ben`），15 个英语注册（`content_lang: en`）和 6 个原生中文 / 韩语注册（`content_lang: zh` / `ko`）。人物跨度为 35 个日语基础和 5 个英语原生（`content_lang: en`）原型，针对国际用户，加上 `hautaine`（与生俱来的傲慢 / 鄙视的语气）和 `sociable`（读取房间，桥梁人们，校准语气）。
#### 346 个属性
| 类别 | 数量 | 包含的属性 |
|---|---|---|
| 人物（日语基础） | 35 | airhead / battle_junkie / chuunibyou / crybaby / dandere / deadpan / deredere / diligent / genki / gluttonous / himedere / hinedere / hot_blooded / intellectual / kamidere / klutz / kuudere / laid_back / menhera / mysterious / narcissist / optimist / pessimist / playful / pragmatist / protective / puppyish / sadodere / scheming / serious / socially_anxious / stoic / switch / tsundere / yandere |
| 人物（日语基础，第 8 阶段） | 2 | hautaine / sociable |
| 人物（英语原生） | 5 | sassy / rebel / charmer / drama_queen / go_getter |
| 言语（日语） | 25 | archaic / blunt / boku_girl / burikko / gyaru / hakata_ben / hiroshima_ben / kansai_ben / keigo / kyoto_ben / mischievous / mixed_dialect / onee_kotoba / ore_boy / princess_speech / robotic / seductive / soft / stutter / theatrical / third_person / tohoku_ben / tomboy / washi / whispery |
| 言语（日语，第 8 阶段） | 1 | archaic_otaku |
| 言语（日语，第 1 阶段：地区方言） | 36 | akita_ben / ehime_ben / gifu_ben / gunma_ben / hokkaido_ben / hyogo_ben / ibaraki_ben / kagoshima_ben / kanagawa_ben / kanazawa_ben / kochi_ben / kumamoto_ben / mie_ben / miyazaki_ben / nagoya_ben / nagasaki_ben / nara_ben / niigata_ben / oita_ben / okayama_ben / okinawa_ben / osaka_ben / saga_ben / saitama_ben / sanuki_ben / sendai_ben / shimane_ben / shizuoka_ben / tochigi_ben / tokushima_ben / tokyo_ben / toyama_ben / tsugaru_ben / wakayama_ben / yamagata_ben / yamaguchi_ben |
| 言语（日语，第 3 阶段：角色和亚文化声音） | 25 | akuma_oujo / business / butler / chuunibyou_speech / kawaii / mahou_shoujo / mama / miko / musuko / obaachan / ojisan / ol / ryoushi / sage / samon / sensei / shouwa_retro / streamer / taishou_retro / vtuber / wagahai / warawa / yankee / yuuusha / z_jidai_slang |
| 言语（日语，第 4 阶段：亚洲和欧洲语言） | 14 | mandarin / taiwanese / cantonese / korean / french / german / italian / spanish / russian / arabic / hindi / vietnamese / thai / tagalog |
| 言语（日语，第 5 阶段：动漫类型声音） | 18 | boin_girl / bokukko / dark_hero / densetsu_no_yuusha / hero_yamero / imouto / isekai_cheat / kuudere_girl / kuukichou / mesugaki / onee_san / osananajimi / oujo / samurai_lol / sensei_goroshi / tsukkomi / villainess / wizard |
| 言语（英语） | 15 | formal_en / casual_en / blunt_en / southern_us_en / british_en / aussie_en / scottish_en / irish_en / valley_girl_en / brooklyn_en / new_york_en / midwestern_en / pidgin_en / jamaican_en / punjabi_en |
| 言语（中文/韩语原生，v1.5.0） | 6 | mandarin_casual / keigo_zh / taiwan_mandarin / banmal / jondaetmal / seoul_casual |
| 原型 | 66 | alien / angel / antihero / apprentice / artist / assassin / bartender / best_friend / big_brother / big_sister / bodyguard / chef / childhood_friend / chosen_one / commander / cyborg / delinquent / demon / doctor / dragon / engineer / entrepreneur / fairy / fallen_hero / gakkyuu_iinchou / gamer_otaku / ghost / goddess / heroine / hikikomori / honor_student / idol / journalist / kitsune / knight / kouhai / little_brother / little_sister / lone_wolf / maid / mediator / mentor / mercenary / mother_figure / noble / nurse / office_worker / ojou_sama / oni / prince / rival / robot_android / school_nurse / scientist / seitokaicho / senpai / shrine_maiden / sidekick / soldier / teacher / tenkousei / twin / underdog / vampire / villain / witch |
| 视觉 | 46 | ahoge / androgynous / animal_ears / black_hair / blonde / blue_hair / blunt_bangs / blush / bob_cut / braids / chubby / drill_hair / droopy_eyes / eyebags / eyepatch / freckles / glamorous / glasses / golden_eyes / gradient_hair / hair_bun / heterochromia / hime_cut / inner_color / jitome / kimono / long_hair / messy_hair / mole / muscular / pale_skin / petite / pink_hair / ponytail / red_eyes / red_hair / scar / sharp_eyes / short_hair / side_ponytail / silver_hair / slender / tall / tan / twintails / white_hair |
| 爱好 | 51 | art / astronomy / baking / board_games / cafe_hopping / calligraphy / camping / coffee / collecting / cooking / cosplay / crafting / cycling / dance / fashion / fishing / flower_arrangement / fortune_telling / gamer / gardening / hiking / history_buff / karaoke / knitting / languages / makeup / martial_arts / meditation / model_building / movies / music / occult / pet_care / photography / pottery / programming / puzzles / reading / running / sado / shopping / singing / skateboarding / sports / surfing / swimming / trains / travel / wine / writing / yoga |
#### 必需字段（attribute.schema.json）
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `attribute_category` | 枚举 | ✓ | `personality` / `speech` / `archetype` / `visual` / `hobby` |
| `attribute_name` | 字符串（snake_case） | ✓ | 匹配文件名的唯一 ID |
| `weight_dimension` | 枚举 | ✓ | `none` / `mild` / `moderate` / `strong` |
| `examples` | 字符串[]（1+） | ✓ | AI 代理使用示例。无专有名词或特定作品 |
元数据必须使用模式的两种接受的形状之一：
| 形状 | 必需字段 | 注释 |
|---|---|---|
| 当前国际化元数据 | `display_name` / `description` | 基础语言为英语；本地化标签/描述放在 `i18n.<lang>` 下（例如 `i18n.ja.display_name`） |
| 遗留后缀对元数据 | `display_name_ja` / `display_name_en` / `description_ja` / `description_en` | 仍然接受以向后兼容，但新属性应首选当前的国际化形状 |
#### 可选字段
| 字段 | 类型 | 描述 |
|---|---|---|
| `core_traits` | 字符串[]（3-7） | 人物特征列表；注入时由 AI 代理解释的核心 |
| `speech_style` | 字符串 | 言语风格的整体描述（1行）；注入到混合中 |
| `first_person` | 字符串 | 第一人称代词，主要用于言语属性；注入到混合中，用于强度测量 |
| `second_person` | 字符串 | 第二人称（例如“贵方”，“お前”）；可能包括用户的角色名称 |
| `sentence_endings` | 字符串[]（1+） | 句子结尾模式（日语，例如“〜の”，“〜のね”） |
| `lexical_markers` | 字符串[] | 特征词/短语（英语，例如“gonna”，“y'all”）；注入到混合中，用于英语强度 |
| `register` | 枚举 | 言语登记：`formal` / `neutral` / `casual` / `vulgar`（主要用于英语） |
| `catchphrases` | 字符串[] 或 `{phrase, when}` 对象 | 常用语；每个条目可以是纯字符串或具有可选触发条件的对象 |
| `tone` | 字符串 | 声音氛围（1行） |
| `image_prompt_tags` | 字符串[] | 英语图像生成标签，主要用于视觉属性 |
#### 关系和本地化字段
| 字段 | 类型 | 描述 |
|---|---|---|
| `compatible_archetypes` | 字符串[] | 期望与哪些原型属性名称配对良好的列表 |
| `conflicts_with` | 字符串[] | 期望相互排斥的其他属性名称列表 |
| `tags` | 字符串[] | 跨切搜索标签 |
| `typical_value_range` | 字符串 | 使用权重时的典型值（例如 `0.4-0.7`） |
| `content_lang` | 枚举 (`ja`/`en`/`zh`/`ko`) | 角色内容字段的语言；驱动响应语言指令和强度。缺失 ⇒ `ja` |
| `content_i18n` | 对象 | 每种语言的本地化角色内容 (`<lang>.catchphrases, tone, core_traits, examples`)；让注入的常用语保留在角色的语言中 |
| `i18n` | 对象 | 本地化元数据（`display_name` / `description`）按语言代码键控 |
| `has_catchphrase` | 布尔值 | 是否存在常用语 |
| `variant` | 字符串（snake_case） | 相同 `attribute_name` 的变体标签 |
| `notes` | 字符串 | 补充/操作说明 |
#### 模板生成脚本
通常的维护流程是直接在 `attributes/<category>/<name>.yaml` 下添加或编辑属性文件，并运行 `python scripts/validate.py` 进行验证。下面是冻结的遗留快照 - 请不要将其用于日常维护。
`scripts/_oneoff/gen_v1_attributes.py` 可以重新生成 YAML 作为单一事实来源。与其直接编辑 YAML，请更新列表并重新运行：
```bash
# 无确认重新生成（旧版）属性 YAML
python scripts/_oneoff/gen_v1_attributes.py
```
# 只显示将被写入的路径
python scripts/_oneoff/gen_v1_attributes.py --dry-run
```
> 注意：此生成器是一个冻结的快照，并发出旧版元数据格式
> (`display_name_zh_CN/en`，`description_zh_CN/en`）。重新生成后，运行
> `python scripts/migrate_i18n.py` 以转换回 i18n 块格式（BASE=en + `i18n.zh_CN`）。
#### 验证
```bash
python scripts/validate.py
```
确认所有 346 个属性 YAML 文件都符合模式验证。
## 许可证
- 本存储库中的代码：**MIT**
- `attributes/` 下的模板：**CC0 1.0**（公共领域专用）
- 免责声明：请务必阅读 [DISCLAIMER.md](./DISCLAIMER.md)
- 安全/威胁模型：请参阅 [SECURITY.md](./SECURITY.md)（`hersona update` 的校验和验证能保护和不能保护的内容）
## 贡献
1. 在 `attributes/<category>/<name>.yaml` 格式中添加属性模板
2. `examples` / `core_traits` / `catchphrases` 等不需要注明来源（LLM 会解释它们），但
必须不包括专有名词或特定作品
3. 在打开拉取请求（PR）之前使用 `python scripts/validate.py` 进行验证
4. 按照规则，一个 PR 对应一个属性；对于多个添加，请事先在问题中达成一致
请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 获取详细信息。在项目中使用 hersona？
将自己添加到 [USED_BY.md](./USED_BY.md)。
代理/开发人员的使用指南（“下一步要构建什么”）位于
[docs/IMPLEMENTATION_GUIDE.md](./docs/IMPLEMENTATION_GUIDE.md)。
连接信息
猜你喜欢
暂无推荐服务器