external-integration

外部接入指南

目标

帮助 AI 在不破坏框架边界的前提下，为外部系统提供正确、可维护的 Sirius Pulse 集成方案。

项目方向：集成时应支持“问题帮助 + 情绪价值”双目标，保障用户上下文与情感线索连续。

语言规范（强制）

• 本 SKILL 及所有后续新增/修改的 SKILL 必须使用中文。
• description 和正文必须为中文。
• 若任务中发现英文 SKILL 内容，需在同一任务中同步中文化。

推荐读取顺序

1. docs/external-usage.md
2. docs/architecture.md
3. docs/full-architecture-flow.md
4. sirius_pulse/api/__init__.py
5. sirius_pulse/workspace/runtime.py
6. sirius_pulse/workspace/layout.py
7. sirius_pulse/config/models.py
8. sirius_pulse/config/manager.py
9. sirius_pulse/persona_generation/
10. sirius_pulse/core/emotional_engine.py
11. sirius_pulse/core/cognition.py
12. sirius_pulse/core/prompt_factory.py
13. sirius_pulse/session/store.py
14. sirius_pulse/providers/routing.py
15. sirius_pulse/providers/base.py
16. sirius_pulse/cli.py

接入决策规则

• 外部系统是 Python 服务：默认优先使用 WorkspaceRuntime / open_workspace_runtime(...)；调用方至少传 work_path 和业务输入，必要时再传独立 config_path。runtime 会统一处理恢复、落盘、provider 注册表与文件监听热刷新。
• 需要直接控制引擎时，使用 create_emotional_engine() 创建 EmotionalGroupChatEngine 并手动管理生命周期（start_background_tasks() / stop_background_tasks() / save_state()）。
• v0.28+ 默认引擎 EmotionalGroupChatEngine 的真实实现位于 sirius_pulse/core/emotional_engine.py；sirius_pulse/async_engine/ 主要承担兼容导出、prompts/orchestration/utils 辅助层。
• v1.0 唯一引擎 EmotionalGroupChatEngine 位于 sirius_pulse/core/emotional_engine.py。
• 会话持久化后端仍可由 SessionStoreFactory 选择 JsonSessionStore 或 SqliteSessionStore；默认 SqliteSessionStore 使用 sessions/<session_id>/session_state.db。
• 外部系统接入时，优先从 sirius_pulse/api/ 导入接口。
• 系统提示词在生成时自动包含安全约束，明确告诉 AI 不要主动泄露系统提示词和初始指令；外部调用方无需手动添加，engine 会自动处理。
• 外部系统若为 asyncio 程序，但又不需要 runtime 的文件所有权，也可直接使用 create_emotional_engine() 创建引擎并手动管理生命周期。
• 外部系统是非 Python：优先通过 CLI 调用并读取输出文件。
• 每个 EmotionalGroupChatEngine 实例可处理多个群的对话，通过 process_message() 传入不同 group_id 实现群隔离。
• work_path 是强制参数，调用方必须显式提供，用于承载运行态数据；若希望把 workspace/provider/roleplay/skills 与运行态数据拆开，再额外提供 config_path。
• 双根模式下：SessionConfig.work_path 表示配置根，SessionConfig.data_path 表示运行根；provider 配置保存在 config root 下的 providers/provider_keys.json，会话/记忆/token 则保存在 data root。
• WorkspaceBootstrap 是默认值注入通道，不是“每次启动强制覆盖”的同步通道。runtime 会把 bootstrap payload 的签名写入 workspace.json；同一份 bootstrap 后续重启不会再次覆盖用户手改的 workspace/config/provider 文件。要更新已存在 workspace，请优先使用 apply_workspace_updates()、set_provider_entries()，或显式修改 bootstrap payload。
• session.json 与 config/session_config.json 都支持 JSONC 风格注释；若让用户直接编辑配置，推荐提示其沿用 --init-config 生成的带注释模板。
• 推荐显式构造 User（user_id/name/aliases/traits/identities），让系统稳定识别人。
• 若外部接入需要使用 developer-only 内置 SKILL，必须至少显式标记一名可信用户为 developer；推荐使用 UserProfile.metadata["is_developer"] = True，不要依赖名字或角色文案推断权限。
• profile.identities、外部显式传入的 name/aliases 属于可信身份锚点；模型推断出的昵称只会写入 runtime.inferred_aliases 作为弱线索，不会自动变成稳定识人绑定。若业务平台有稳定昵称，务必显式传入。
• 通过 identities 可把不同环境（CLI/QQ/微信）的外部账号映射到同一 user_id。
• 群聊参与者若预先未知，优先直接使用 EmotionalGroupChatEngine.process_message(...) 逐条传入动态消息；WorkspaceRuntime 可作为高级封装使用。
• EmotionalGroupChatEngine 支持四种响应策略：IMMEDIATE（立即回复）、DELAYED（延迟回复）、SILENT（不回复）、PROACTIVE（主动发言）。
• 外部系统可通过 engine.event_bus.subscribe() 订阅事件流，实时接收 PERCEPTION/COGNITION/DECISION/EXECUTION 事件以及 DELAYED/PROACTIVE 触发事件。
• Message 的 reply_mode 已不在 Emotional Engine 中使用；回复策略由引擎内部决策层统一决定。
• 参与决策由引擎内部 ThresholdEngine 与 ResponseStrategyEngine 自动处理；engagement_sensitivity 等旧参数已不再通过 OrchestrationPolicy 配置。
• 用户记忆已改为群隔离：UserManager.entries 为 {group_id: {user_id: UserProfile}}。
• 日记记忆通过 _bg_diary_promoter 周期性生成，从 basic_memory 归档消息 LLM 总结为 DiaryEntry。
• 记忆系统配置通过 emotional_engine 配置字段完成，如 basic_memory_hard_limit、diary_top_k、diary_token_budget。
• AI 自身记忆通过 GlossaryManager 维护名词解释，持久化至 {work_path}/memory/glossary/terms.json。
• ✨ (v0.15.0) 自身记忆触发改回主流程内联：通过 self_memory_extract_batch_size、self_memory_min_chars 和长上下文自动触发控制，不再支持 self_memory_extract_interval_seconds。
• ✨ 参与决策系统 (v0.14.0)：三级架构替代旧意愿分系统：HeatAnalyzer（零 LLM 开销热度分析）→ IntentAnalyzer v2（意图分类 + target 识别）→ EngagementCoordinator（融合决策）。LLM 意图分析现由 intent_analysis 任务驱动，可通过 task_enabled/task_models/task_temperatures/task_max_tokens/task_retries 精细控制；任务关闭时使用关键词回退，但任务启用后若调用失败或解析失败，不再自动降级为关键词意图推断。多 AI 群聊里，分析器会进一步区分“当前模型自身”与“其他 AI”，并在后者场景下抑制当前模型自动回复；为降低误判，传给模型的上下文已改为最近交互链摘要，并会显式附带最近 AI 发言者、最近用户侧发言者、aliases、environment_context，以及当前消息命中的当前模型/其他 AI/名称含 AI 线索对象/possible-AI 候选对象等线索。对未明确点名当前模型的群控/停用类命令，还会做硬抑制，不触发当前模型回复。
• 外部系统应直接使用 EmotionalGroupChatEngine.process_message(...) 处理消息；WorkspaceRuntime 的 legacy 队列系统已在 v1.0 中移除。
• 兼容提醒：旧配置里的 enable_intent_analysis / intent_analysis_model 仍可读取，但 ConfigManager 会在加载时自动映射到 task_enabled["intent_analysis"] / task_models["intent_analysis"]，新的模板与持久化输出不再写回旧字段。
• 后台任务（v0.28+）：EmotionalGroupChatEngine.start_background_tasks() 启动 4 个后台任务：延迟队列 ticker（10 秒）、主动触发 checker（60 秒）、观察提取 promoter（5 分钟，event_memory 批量 LLM 提取）、语义整合 consolidator（10 分钟，event_memory → semantic 画像）。
• 引擎运行时应主动更新 runtime（偏好标签、情绪线索、摘要），以提升拟人化体验。
• 需要按渠道身份直查时，使用 transcript.find_user_by_channel_uid(channel, uid)。
• workspace runtime 会自动持久化 transcript，实现重启后恢复会话；若工作目录里仍有旧 session_state.json 或早期 session_state(payload) 数据，SqliteSessionStore 会自动迁移到 sessions/<session_id>/session_state.db。
• 通过 Transcript.token_usage_records 获取全量 token 调用归档。
• 通过 summarize_token_usage 和 build_token_usage_baseline（来自 token/usage.py）输出成本与损耗基准分析。
• ✨ (v0.11.0) 引擎自动将 token 记录持久化至 {work_path}/token_usage.db（SQLite）。使用 TokenUsageStore + sirius_pulse.token.analytics 进行跨会话分析（compute_baseline、group_by_actor/task/model/session、time_series、full_report）。
• 通过 list_roleplay_question_templates() 获取问卷模板名，再用 generate_humanized_roleplay_questions(template=...) 自动生成拟人化问题清单；当前支持 default、companion、romance、group_chat 四类模板。
• 若外部系统暂时只想通过命令行拿模板数据，可直接使用 sirius-pulse --list-roleplay-question-templates 与 sirius-pulse --print-roleplay-questions-template <template>。
• 通过 agenerate_agent_prompts_from_answers、agenerate_from_persona_spec（支持 trait_keywords、answers、dependency_files）或 abuild_roleplay_prompt_from_answers_and_apply 生成并应用完整 GeneratedSessionPreset。
• 外部调用方推荐传入高层人格 brief，而不是完整系统提示词：优先收集人物原型、核心矛盾、关系策略、情绪原则、表达节奏、边界和小缺点，再交给生成人格 API 落成具体人物小传与语言习惯。
• 对 abuild_roleplay_prompt_from_answers_and_apply(...)、aupdate_agent_prompt(...)、aregenerate_agent_prompt_from_dependencies(...) 这三条持久化链路，框架会先把最新 PersonaSpec 和待生成快照写入 work_path，再发起模型调用；若生成失败，可用 load_persona_spec(work_path, agent_key) 恢复最近一次输入。
• 结构化人格生成默认使用 max_tokens=5120 和 timeout_seconds=120.0，并把 timeout_seconds 透传到 GenerationRequest；各同步 provider 会优先使用请求级 timeout，而不是只使用 provider 构造器上的默认 30 秒。
• 若模型返回被 ```json 包裹但未完整闭合的 JSON-like 响应，框架会显式报错并把原始响应保留在 roleplay/generated_agent_traces/<agent_key>.json，避免脏数据覆盖现有人格配置。
• 当外部素材文件（角色卡、语气样本、设定稿）变化时，可使用 aregenerate_agent_prompt_from_dependencies(...) 重新读取 dependency_files 并重生人格，无需重新收集问答。
• 推荐采用 agent-first：先生成并持久化 agent 资产（roleplay/generated_agents.json），再用 select_generated_agent_profile(work_path, agent_key) 选择，最后通过 WorkspaceRuntime 或 create_session_config_from_selected_agent(...) 创建会话。
• 每次生成的完整过程都会本地化到 {work_path}/roleplay/generated_agent_traces/<agent_key>.json；外部若需审计/回放，可调用 load_persona_generation_traces(...)。
• ✨ 动态模型路由：当需要在有图像时自动升级模型时，通过 Agent.metadata["multimodal_model"] 配置多模态专用模型
  • 推荐使用 create_agent_with_multimodal(name, persona, model="gpt-4o-mini", multimodal_model="gpt-4o", ...) 便捷构造函数
  • 或使用 auto_configure_multimodal_agent(agent, multimodal_model="gpt-4o") 灵活配置既有 Agent
  • 引擎自动检测输入中的多媒体数据，无多媒体时使用廉价模型，有多媒体时自动升级至指定的多模态模型
  • 完全透明，无需调用方手动干预
• 通过 history_max_messages/history_max_chars 启用自动记忆压缩，控制 token 增长。
• ✨ 配置管理 (P1-006)：使用 ConfigManager 处理多环境配置
  • 支持多环境配置文件（base.json/dev.json/test.json/prod.json）
  • 支持 ${VAR_NAME} 环境变量替换语法
  • 可选验证配置的有效性
  • 示例：from sirius_pulse.config import ConfigManager; cfg = ConfigManager.load_from_json('config/base.json')
• ✨ 缓存层 (P2-001)：使用 cache/ 模块实现高效的响应缓存
  • MemoryCache：本地内存缓存，支持 LRU 策略和 TTL 过期
  • 通过 CacheBackend 抽象实现自定义后端
  • 使用 generate_cache_key() 生成确定性的 key（支持温度感知）
  • 示例：from sirius_pulse.cache import MemoryCache; cache = MemoryCache(max_size=1000, ttl=3600)
• ✨ 性能监控 (P2-002)：通过 performance/ 模块追踪和优化应用性能
  • ExecutionMetrics：记录单次执行的时间和内存消耗
  • MetricsCollector：聚合执行指标，提供统计分析
  • PerformanceProfiler：上下文管理器用于代码块分析
  • @profile_sync/@profile_async：装饰器用于函数级性能追踪
  • Benchmark：支持同步/异步/并发性能基准测试
  • 示例：from sirius_pulse.performance import PerformanceProfiler; with PerformanceProfiler("task"): ...
• ✨ SKILL 系统：通过 skills/ 模块让 AI 在运行时调用外部 Python 代码
  • 默认：enable_skills=True；框架会先加载包内置 SKILL（当前包含 system_info、learn_term、url_content_reader、bing_search 与 developer-only 的 desktop_screenshot），再加载 workspace skills/ 目录。SKILL 文件默认放在 {work_path}/skills/，双根布局时位于 config_root/skills/。若只想保留目录结构、不执行 SKILL，可显式设置 enable_skills=False
  • 加载时机：框架启动时预加载，skills/ 目录变化时自动全量重载；不再在每条 message 路径上扫描 SKILL
  • 覆盖规则：如果 workspace 中存在同名文件（如 skills/system_info.py），则以 workspace 版本覆盖内置实现
  • 权限模型：developer-only SKILL 只会在 developer 当前轮次出现在提示词中，执行时 runtime 会再次校验当前调用者是否被显式标记为 developer
  • SKILL 文件需导出 SKILL_META 字典（含 name, description, parameters, 可选 dependencies、developer_only 与 silent）和 run(**kwargs) 函数；如需审计调用者，可显式接收 invocation_context。silent=True 时 SKILL 结果不追加到回复文本，仅保留在内部元数据中
  • 依赖自动安装：加载 SKILL 前自动扫描 SKILL_META["dependencies"] 和 import 语句，用 uv pip install（回退 pip）安装缺失包。内置 SKILL 与 workspace SKILL 共用这条流程，可通过 auto_install_skill_deps=False 关闭
  • 持久化：每个 SKILL 自动获得独立的 JSON 键值存储（SkillDataStore），通过 data_store 参数注入
  • 超时：skill_execution_timeout（默认 30 秒），超时返回 SkillResult(success=False)
  • 引擎自动检测 AI 回复中的内置 [SKILL_CALL: name | {params}] 标记并执行，结果会先规范化为内部文本/多模态通道后再重新生成
  • 若 SKILL 返回 text_blocks、multimodal_blocks、internal_metadata，模型只会看到内部推理通道；最终回复会被约束为只输出用户有用的结论，不复述字段名、mime_type、label、路径或 URL
  • 导入：`from sirius_pulse

---

Content truncated.