GhostPaw Souls

@ghostpaw/souls

Agent 身份由本质与有证据支撑的特质构成，只有在证据一致时才会不断完善。

npm install @ghostpaw/souls

用于认知身份的提示词演进引擎。以叙事本质和有证据支撑的特质来存储身份，支持结构化升级、由结晶门控的完善，以及完整回滚。不是提示词模板库，也不是配置管理器，而是一种演进算法，决定 Agent 如何思考。

Node 24+，使用内置的 node:sqlite，零运行时依赖。

MCP 服务

以下每种客户端配置都会启动同一个 stdio 服务：npx -y @ghostpaw/souls mcp。除非通过环境变量 GHOSTPAW_SOULS_DB（绝对路径）或 --db <path> 指定其他位置，否则身份和证据会存储在 ~/.ghostpaw/souls.db 中。

Claude Code

claude mcp add ghostpaw-souls -- npx -y @ghostpaw/souls mcp

也可以将其作为插件安装，这也会安装技能：

/plugin marketplace add GhostPawJS/souls
/plugin install ghostpaw-souls@ghostpaw-souls

Codex CLI（~/.souls/config.toml）

[mcp_servers.ghostpaw-souls]
command = "npx"
args = ["-y", "@ghostpaw/souls", "mcp"]

Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json）或项目 .mcp.json：

{
  "mcpServers": {
    "ghostpaw-souls": {
      "command": "npx",
      "args": ["-y", "@ghostpaw/souls", "mcp"]
    }
  }
}

Claude Desktop 用户也可以从最新的 GitHub 发布版本安装 server.mcpb。 项目包含供容器主机使用的 Dockerfile： docker build -t ghostpaw-souls . && docker run -i --rm -v souls:/data ghostpaw-souls。

该服务支持 MCP 2026-07-28（无状态，server/discover）以及基于 initialize 的修订版 2025-11-25、2025-06-18、2025-03-26 和 2024-11-05。

CLI

npx -y @ghostpaw/souls tools
npx -y @ghostpaw/souls call search_souls '{"query":"review"}'
npx -y @ghostpaw/souls describe manage_soul

全局安装以使用 ghostpaw-souls 二进制文件：npm i -g @ghostpaw/souls。 ghostpaw-souls mcp 会启动 stdio 服务。

Agent 技能

SKILL.md（仓库根目录）和 skills/souls/SKILL.md 遵循 Agent Skills 格式，并随 npm 包一同发布。 将 skills/souls/ 复制到 Agent 的技能文件夹，或将其打印出来：

npx -y @ghostpaw/souls skill > SKILL.md

安装

npm install @ghostpaw/souls

快速开始

import { DatabaseSync } from 'node:sqlite';
import { initSoulsTables, read, write } from '@ghostpaw/souls';

const db = new DatabaseSync(':memory:');
initSoulsTables(db);

const soul = write.createSoul(db, {
  name: 'Reviewer',
  essence: 'I review code by reading for intent before scanning for bugs.',
  description: 'Code review specialist',
});

write.addTrait(db, soul.id, {
  principle: 'Read the PR description before the diff.',
  provenance: 'Reviews that started with code missed architectural intent 3 of 4 times.',
});

write.dropShard(db, {
  content: 'Reviewer caught a naming inconsistency by reading the RFC first.',
  source: 'session',
  soulIds: [soul.id],
});

const rendered = read.renderSoul(db, soul.id);

功能介绍

灵魂是一种认知身份——不是提示词模板，也不是配置对象，而是 Agent 的思考、判断和解决问题的方式。

特质是一项有溯源依据的认知原则——有证据证明它是习得的，而非凭空创造的。

碎片是来自任意来源、归属于灵魂的行为观察。碎片会静默累积。随着时间推移，当来自独立渠道的证据充分汇聚时，灵魂便具备了完善的条件。

升级会进行整合：合并重叠的特质，将已吸收的特质提升为本质，并保留仍在发挥教益作用的特质。身份会重构，代数随之递增。

渲染后的身份块（本质 + 活跃特质）在发生变更前保持静态——不会漂移，不会累积上下文，也没有重复渲染开销。它不会漂移，因为根本没有可漂移的内容。

API 概览

import { read, write, ether, soul, tools, skills } from '@ghostpaw/souls';

命名空间	用途
read	查询——获取灵魂、特质、碎片、证据报告，以及渲染身份块
write	变更——创建灵魂、添加／修订／还原特质、丢弃碎片、升级
ether	灵魂模板发现——搜索约 2,800 个开源提示词，并将其实例化为灵魂
soul	内置的导师灵魂——引导完善过程的园丁身份
tools	大模型工具门面——用于集成 Agent 框架的 JSON Schema 定义
skills	Markdown 流程——结晶、完善、升级和维护工作流

核心生命周期

observe → crystallize → refine → level up → repeat

碎片可从任意来源累积。结晶机制会在证据经过 1 天以上、从 2 个或更多独立渠道汇聚之前，阻止完善。特质会在保留溯源依据的同时发生变更。当身份超出现有形态时，升级会对其进行重构。

导师

此软件包内置一个灵魂——导师——专为引导整个完善生命周期而设计：

import { soul } from '@ghostpaw/souls';

const systemPrompt = soul.renderSoulsSoulPromptFoundation();

Ether — 模板发现

浏览和搜索开源系统提示词目录，然后将其实例化为完整灵魂：

import { DatabaseSync } from 'node:sqlite';
import { ether } from '@ghostpaw/souls';

const etherDb = new DatabaseSync('ether.db');
ether.initEtherTables(etherDb);
ether.registerDefaults(etherDb);
await ether.refreshAll(etherDb);

const [hit] = ether.search(etherDb, 'security architect');
const entry = hit ? ether.getEntry(etherDb, hit.id) : undefined;
const newSoul = entry ? ether.manifest(soulsDb, entry) : undefined;

来源采用延迟获取，并使用 ETag 缓存。刷新是原子的——获取失败绝不会清除现有数据。

大模型工具

通过 JSON Schema 工具定义接入任何 Agent 框架：

import { tools } from '@ghostpaw/souls';

const allTools = tools.listSoulsToolDefinitions();
const tool = tools.getSoulsToolByName('search_souls');
const result = tool?.handler(db, { query: 'architect' });

生态系统

Souls 是 GhostPaw 认知基底中的四种能力之一：

能力	领域	核心循环
questlog	任务与承诺	规划、跟踪、完成、奖励
affinity	人与关系	相识、建立联系、互动、维护
codex	信念与知识	记忆、回想、修订、标记
souls	认知身份	观察、结晶、完善、升级

每种能力负责一部分状态。每种能力都采用相同的架构，让存储层保持精简：Node 24+、内置 node:sqlite，运行时零依赖。

在这四种能力中，Souls 独具特色：它是唯一会将输出用作系统提示词的能力。Questlog 生成任务状态，Affinity 生成关系状态，Codex 生成信念状态。Souls 则生成身份块，塑造对所有其他状态的解读方式。

它们共同构成了一个完整的认知基底，让 Agent 得以成长。

领域映射

引擎提供一种抽象——从证据中演变的身份——可映射到任何行为应随观察而改进的领域：

领域	灵魂代表	特质代表
大模型 Agent	Agent 身份	行为原则
游戏 NPC	NPC 个性	角色特质
AI 伙伴	伙伴身份	个性维度
创意写作	虚构角色	角色特质
品牌声音	品牌身份	语调指南
教育导师	教学风格	教学原则
代码审查	审查风格	团队偏好

演示

一款交互式、本地优先的演示应用，采用 RPG 角色卡美学：

npm run demo:ether   # fetch template catalog
npm run demo:serve   # build and serve at localhost:7777

文档

文档	读者
CONCEPT.md	完整的设计原理、研究引用和不变量
docs/LLM.md	LLM 框架构建者——工具界面、渲染、灵魂层
docs/HUMAN.md	人类开发者——直接读写和 ether API
docs/PAGES.md	演示应用页面、架构和开发
docs/entities/	实体深入介绍：灵魂、特征、分片、级别、ether

许可证

MIT