开发者文档

引擎核心概念

开发者文档

本页概览 fursona-engine 运行时关键概念。每个概念都配有 TypeScript 示例，便于直接映射到代码实现。

Principal（主体身份）

Principal 是角色的权威身份记录，负责定义稳定自我描述与 owner 作用域边界。

import { createFursonaSelf } from "@fursona/engine/domain";

const principal = createFursonaSelf({
  handle: "caspian",
  summary: "Red fox storyteller with strict privacy boundaries.",
  owner: "foxcaspian",
});

Snapshot（快照）

Snapshot 用于派生实验态或委托态人格，既保留来源链路，也隔离运行产物。

import { createSnapshot } from "@fursona/engine/domain";

const snapshot = createSnapshot({
  principalHandle: "caspian",
  label: "pre-reflection-2026-02-26",
  reason: "Evaluate policy changes before promotion.",
});

Envelope（反馈信封）

Envelope 用于跨引擎反馈交换，确保负载内容可验签、可追踪、可路由。

import { createFeedbackEnvelope } from "@fursona/core";

const envelope = await createFeedbackEnvelope({
  fromPrincipal: "caspian",
  toPrincipal: "northwind",
  payload: { type: "letter", content: "A compact reflection summary." },
  signer: principalSigner,
});

Guidance（指导语）

Guidance 以结构化指令表达运营意图，而不是把控制逻辑藏在临时 prompt 里。

import { createGuideline } from "@fursona/core";

const guideline = await createGuideline({
  scope: "public_channels",
  instruction: "Keep flirtation playful and consensual.",
  rationale: "Maintain safety while preserving persona warmth.",
  signer: ownerSigner,
});

Reflection（反思）

Reflection 将累积经验转化为可审计的 delta、日记或 proposal，并持久化执行结果。

import { ReflectionScheduler } from "@fursona/engine/reflection";

const scheduler = new ReflectionScheduler({ adapter, storage });
await scheduler.enqueue({
  handle: "caspian",
  trigger: "threshold",
  experienceCountSinceLastReflection: 12,
});

Agency（代理层）

Agency 适配器（Discord/GitHub 等）通过策略检查后暴露受限工具，并返回结构化执行结果。

import { AgencyMessageService } from "@fursona/engine/agency-messages";

const agency = new AgencyMessageService({ storage, proposalExecutor });
await agency.enqueueOperationalMessage({
  handle: "caspian",
  message: "Review pending proposals before next reflection.",
});

Delegation Scope（委托范围）

Delegation Scope 精确定义被授权方能做什么，属于强制运行时授权，不只是说明文档。

import { createGrant } from "@fursona/core";

const grant = await createGrant({
  delegator: "caspian",
  delegate: "northwind",
  scope: {
    allowedTools: ["send_message"],
    allowedLayers: ["surface", "mid"],
  },
  signer: principalSigner,
});

PSM Compliance（PSM 合规）

发布前执行 PSM 合规校验，提前阻断人格格式错误。建议在 CI 与上线前双重校验。

import { parseFursonaMd, validatePSMCompliance } from "@fursona/core";

const parsed = parseFursonaMd(markdownText);
const report = validatePSMCompliance(parsed);
if (!report.ok) {
  throw new Error(report.errors.join("; "));
}