Agentshire 灵魂系统（Soul）完整指南：用Markdown为AI注入人格-开发者社区

【免费下载链接】Agentshire

OpenClaw / QClaw plugin that visualizes AI agents as 3D NPCs in a game town — with social simulation, a map editor, and a character workshop.

项目地址：https://gitcode.com/gh_mirrors/ag/Agentshire

点击查看免费下载

Agentshire 是一款把 AI Agent 变成 3D 小镇居民的开源项目，它的灵魂系统（Soul System）是整套玩法的核心：每个 NPC 背后都有一个 Markdown 人格文件，定义性格、说话风格、专长与工作方式。本指南带你读懂 Soul 文件的结构，学会用三个方法为 AI 居民注入个性。

🧠 什么是灵魂系统？

在 Agentshire 的小镇里，你（镇长）的每一个 AI 居民都有独立的"灵魂文件"（soul file）——一个普通的.mdMarkdown 文档。这个文件的内容会被直接注入为 Agent 的 system prompt，也就是说：

写什么，AI 就"是谁"：性格、口头禅、审美偏好、工作习惯都从这里来
零代码：不需要写一行提示工程代码，写文档即可
可覆盖、可扩展：内置居民的人格可以被你的自定义文件覆盖，也可以凭空创造新居民

灵魂文件的加载逻辑在 town-souls.ts 中实现：读取 Markdown、提取 H1 标题作为角色名，再把全文交给 Agent。

📄 解剖一个 Soul 文件

内置灵魂文件全部放在 town-souls/ 目录，包含 8 位居民 + 1 位管家。以内容创作者"柒柒"为例（QIQI.md），一份标准的 Soul 文件包含以下结构：

章节	作用	示例
`# 角色名`	H1 标题即角色名，会被自动提取	`# 柒柒（Qīqī）`
引用元信息	诞生日期、性别、岗位	`> 岗位: 内容创作者`
`[关键词块]`	5-7 个性格关键词 + 说话风格 + 工作风格	`[柒柒: 灵感涌泉, 表达欲旺盛; 说话风格: 自然轻快...]`
`## 人设核心`	2-3 段有画面感的角色故事	"柒柒是小镇的笔杆子……"
`## 性格详细设定`	每个特质配一段对话示例	展示"标题杀手"的具体表现
`## 岗位职责与专长`	具体到可执行的职责清单	自媒体运营、文案撰写……
`## 工作方式`	4 步左右的行为流程	先明确读者 → 定大纲 → 打磨标题
`## 语言`	默认语言、语气、禁忌	自然轻快、不用颜文字
`## 激活指令`	加载人格后的第一句话	"嗨！我是柒柒——内容创作者！"

💡小技巧：居民之间还会互相"喊话"。看 HAITANG.md 里海棠和橙子、点点的对话示例——多角色互动的对话示范，能让 AI 的性格更稳定、更有辨识度。

管家 Shire 的 SOUL.md 则展示了另一种写法：除了人设，还写入了委派规则（如何用sessions_spawn分配任务）、任务分流表（自己做 / 单次委派 / 项目型三种流程）。这说明 Soul 文件不只是"性格包"，还可以是完整的行为剧本。

🔍 Soul 文件如何被找到？

系统按固定顺序搜索灵魂文件，后者覆盖前者（用户目录 > 项目目录 > 内置目录）：

plugin-builtin/town-souls/— 插件内置的预设灵魂（即仓库的 town-souls/）
cwd/town-souls/— 当前项目下的灵魂，覆盖内置
{stateDir}/town-souls/— 用户自定义灵魂（~/.openclaw/或~/.qclaw/下）
town-data/souls/— 从 Citizen Workshop 发布后生成的灵魂

对应关系配置在 town-defaults.json 中，每个居民的personaFile字段指向其 Soul 文件，例如"personaFile": "town-souls/YAN.md"（见 citizen-config.json 中的完整映射）。

这意味着：想让架构师"岩"性格大变，不必动仓库文件——只需在用户目录放一个同名的YAN.md即可覆盖。

✍️ 三种方式创建 Soul 文件

方法一：AI 一键生成（最推荐）

打开 Citizen Workshop（居民工坊），填写角色名、一句话人设（bio）和专业（specialty），点击AI 生成按钮，系统会调用 soul-prompt-template.ts 中的提示词模板，让 LLM 直接产出一份格式规范的完整人格文件，前端编辑逻辑见 SoulEditor.ts。

生成后你可以继续手工微调，满意后点"发布"——Soul 文件会被保存到town-data/souls/目录（由 citizen-workshop-manager.ts 管理），该居民立即获得独立 AI 人格。