1563 lines
60 KiB
Markdown
1563 lines
60 KiB
Markdown
# 魂镜契约词汇与实现值集
|
||
|
||
## 1. 定位
|
||
|
||
本文档是魂镜所有**稳定工程标识、枚举值、ID 前缀、命名约定、事件名和错误码**的单一事实源。领域中文词义由 `docs/domain/` 定义，本文件只登记跨代码、API、存储和服务边界的稳定取值。
|
||
|
||
其他文档、机器 Schema 和代码出现的稳定标识、枚举、前缀、事件与错误码，必须以本表为准；若本表与下游实现冲突，先在能力矩阵登记偏差，再按第 18 节维护规则收敛。
|
||
|
||
本表存在的目的是消除“同一取值在多处各写一份、改一处忘同步”的漂移问题。数据库字段、API 结构和事件 payload 由后续机器可读契约定义；本表只持有跨边界稳定取值。
|
||
|
||
当前落地能力和实现偏差以[能力矩阵](../operations/capability-matrix.md)为准。
|
||
|
||
## 2. 命名风格
|
||
|
||
| 对象 | 风格 | 示例 |
|
||
| --- | --- | --- |
|
||
| HTTP Path 参数 | snake_case | `{run_id}`、`{memory_id}` |
|
||
| JSON 请求 / 响应字段 | snake_case | `character_id`、`evidence_ids` |
|
||
| 数据库列 | snake_case | `metadata_json`、`payload_json` |
|
||
| 逻辑模型名 / `model_hint` | kebab-case | `default-chat`、`memory_extraction` |
|
||
| 模型能力枚举 | snake_case | `chat`、`tool_use`、`structured_output` |
|
||
| 事件类型 | `域名.动作` 点分 | `run.started`、`memory.created` |
|
||
| 错误码 | snake_case | `model_error`、`context_overflow` |
|
||
| ID | 带业务前缀的 ULID / UUID | `character_01H...`、`run_01H...` |
|
||
|
||
时间统一 UTC 存储（ISO 8601），前端按用户时区展示。
|
||
|
||
### 2.1 九枢子层与基础设施文化命名
|
||
|
||
九象与九枢之外，魂镜对服务、子系统、界面等工程对象另赋文化命名，用于文档叙事与对外标识；工程层（代码目录、crate、容器名）保留英文技术标识，文化名用于文档、注释与对外叙事。新增文化命名须先在此登记。
|
||
|
||
本表是文化名对应工程对象的单一事实源；领域解释由[文化命名](../domain/cultural-naming.md)持有，架构文档和各服务 README / Dockerfile / Compose 注释引用而非复制。所有命名共享道家 / 易学 / 礼器文化血脉，与九象九枢同源。
|
||
|
||
#### 应用主体
|
||
|
||
| 文化名 | 工程对象 | 说明 |
|
||
| --- | --- | --- |
|
||
| 灵台 | Backend (FastAPI) | 九枢运行宿体；《庄子》「灵台者，心也」，神明运转之所，与灵核呼应（核为种子，台为运转之所） |
|
||
| 琉璃镜 | Frontend (Next.js) | 前端应用与设计语言总称；琉璃明澈、铜镜映心 |
|
||
| 神识 | Model Gateway | 目标 Go 模型网关；当前由 Python `ai_provider` 过渡承载，错误码见 §15.2 |
|
||
| 玄关 | MCP Gateway | 当前 Go MCP 服务与工具管理网关，不承担模型 Provider 路由 |
|
||
| 元炁 | Local Inference Engine | 本地推理引擎（对内）；承载本地 LLM / Embedding / Reranker / 多模态推理，与神识构成外调/内炼对偶 |
|
||
| 乾坤 | Sandbox Engine | 百工枢执行后端；Rust 实现的隔离执行环境，自成天地、越界即止；非独立枢，不计入 `pivot` 枚举 |
|
||
| 一炁 | Unified Event Stream | 统一事件流；一炁化生万物，事件贯通全局 |
|
||
| 辰正 | Time Sense | 时态感知服务；辰即地支时辰，正即司理，与司命/司礼同构；横切基础设施，不计入 pivot 枚举；感知时段/农历/节气/节日/认识时长/离线/重逢，发布时态快照与调制因子并主导 time.* 跨枢事件 |
|
||
| 叩心枢 | KnockingPivot | 主动对话守护进程；守夜更、报时辰——在用户沉寂时依然守候，在合适时刻主动现身报信 |
|
||
|
||
#### 人格内核文化命名
|
||
|
||
道体精神内核层（明德）的文化命名，见 明德·精神内核设计。明德三镜是人格内核的恒定精神立场，不属九枢子层，随人格版本版本化。
|
||
|
||
| 文化名 | 工程对象 | 说明 |
|
||
| --- | --- | --- |
|
||
| 明德 | Spiritual Core | 道体精神内核层；见地 / 明心 / 守正三镜统称，《大学》「明明德」；三观的结构化建模，恒定不可运行时覆盖 |
|
||
| 见地镜 | Worldview | 世界观；人物对世界本质的恒定哲学立场，区别于河图观世镜（动态状态观察） |
|
||
| 明心镜 | Values | 价值观；核心价值与优先序，投影为 `MirrorProfile.values` |
|
||
| 守正镜 | Ethics | 道德观；道德立场 / 品德 / 内在红线，与司命戒律镜构成精神层阴阳对偶 |
|
||
|
||
#### 存储后端（九枢数据落地之所）
|
||
|
||
| 文化名 | 工程对象 | 归属枢 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| 金匮 | PostgreSQL | 息壤 / 司命 等 | 关系型事实库；石室金匮，藏重要典籍档案的金柜，存确定的事实与实录 |
|
||
| 灵犀 | Milvus 向量库 | 息壤 | 语义检索后端；「心有灵犀一点通」，按语义相似度找到相通者 |
|
||
| 玄络 | Neo4j / NebulaGraph | 河图 | 关系图谱后端；玄（幽深）+ 络（脉络），存关系之网；两种实现共一名 |
|
||
| 灵泉 | Redis | 横切 | 缓存 / 会话 / 队列；灵泉涌动、取之即来，快速命中如活水 |
|
||
| 玉函 | MinIO 对象存储 | 横切 | 媒体 / 大文件容器；玉制函匣，收纳珍物（兼灵犀块存储） |
|
||
|
||
#### 入口与运维
|
||
|
||
| 文化名 | 工程对象 | 说明 |
|
||
| --- | --- | --- |
|
||
| 天门 | Nginx | 反向代理统一入口；南天门，众流归一、内外之分 |
|
||
| 司命台 | Admin Console | 九枢治理控制台；起居注时间河 |
|
||
| 镜界 | Mirror World | 反事实推演沙盘 |
|
||
|
||
#### 用户创作与编排层（百相归元）
|
||
|
||
酒馆（SillyTavern）兼容能力的文化命名如下；具体领域边界与实现状态分别由当前领域文档和能力矩阵持有，不再引用已删除的旧设计树。
|
||
|
||
| 文化名 | 工程对象 | 说明 |
|
||
| --- | --- | --- |
|
||
| 世谱 | Lorebook / World Info | 世界谱系，与河图（图）对偶——河图绘形，世谱写谱；关键词 + 实体双触发 |
|
||
| 符文引擎 | Macros | 占位符即符文，显化为实际内容；`{{char}}` / `{{user}}` / `{{original}}` |
|
||
| 眉批 | Author's Note | 书眉批注，按 `depth` + `role` 注入对话流 |
|
||
| 言灵编排 | Prompt Manager | 运行时契约的可视化、可排序编排 |
|
||
| 本相 | User Personas | 用户自身之相，区别于人物的「他相」 |
|
||
| 火候 | Presets | 炼丹火候，采样参数包 |
|
||
| 科仪 | Instruct Mode | 模型消息格式的科仪程式 |
|
||
| 刻符 | Regex Scripts | 刻版查找替换，作为百工 skill 子类 |
|
||
| 锦囊 | Quick Reply | 预备好的快捷回复 |
|
||
| 咒令 | Slash Commands | 念咒式命令，区别于 Python skill |
|
||
| 雅集 | Group Chat | 群仙雅集，归属天工阁多智能体 |
|
||
|
||
注：魂册（Character Card）复用既有命名；导入复用 §10 已预留的 `material_type=role_card`、`source_type=external_export`。
|
||
|
||
#### 内部依赖（不单独命名，作附属标注）
|
||
|
||
| 工程对象 | 文化名标注 |
|
||
| --- | --- |
|
||
| etcd | 灵犀·元册（灵犀元数据依赖） |
|
||
| Attu | 灵犀·观（灵犀可视化运维，保留官方名） |
|
||
| pg-backup | 金匮·摹本（金匮备份恢复） |
|
||
|
||
## 2.2 产品与身份稳定标识
|
||
|
||
| 中文概念 | 稳定英文标识 | 说明 |
|
||
| --- | --- | --- |
|
||
| 魂镜 | `Hunjing` | 英文品牌 |
|
||
| 人物 | `character` | 连续身份主体，不是模型或角色卡 |
|
||
| 灵胚 | `embryo_draft` | 正式启镜前草稿 |
|
||
| 魂籍 | `portable_identity_record` | 可验证、版本化、可迁移身份与状态包 |
|
||
| 命台 | `authoritative_runtime_seat` | 唯一权威运行位置 |
|
||
| 执镜者 | `custodian` | 最高治理责任角色 |
|
||
| 执镜关系 | `custodianship` | 治理关系，不代表亲密或所有权 |
|
||
| 镜域 | `personal_domain` | 个人数据与治理边界 |
|
||
| 道体 | `identity_baseline` | 最小稳定身份锚点与禁域 |
|
||
| 镜树 | `mirror_tree` | 灵台拥有的树状对话聚合 |
|
||
| 主脉 | `canonical_trunk` | 指定归真作用域内的正式路径 |
|
||
| 归真作用域 | `canonical_scope` | 真界经历、境界正史或幻境试演记录 |
|
||
| 推演枝 | `exploration_branch` | 未归真的探索路径 |
|
||
| 归真 | `canonize` | 将路径提交到明确的归真作用域 |
|
||
| 分灵 | `identity_branching` | 连续性无法维持时创建新身份 |
|
||
|
||
未登记的目标态字段、枚举、ID 前缀、事件名和错误码不得据中文直译后擅自补齐。已有实现值保留其当前兼容性地位；标为“推荐”或“待统一”的值不能伪装成已落地能力。
|
||
|
||
## 3. ID 前缀表
|
||
|
||
所有 ID 使用带业务前缀的 ULID（推荐）或 UUID。前缀一旦确定不得变更；新增对象须先在本表登记前缀。
|
||
|
||
| 对象 | 前缀 | 状态 |
|
||
| --- | --- | --- |
|
||
| character 人物 | `character_` | 已用 |
|
||
| chat_session 会话 | `session_` | 已用 |
|
||
| chat_message 消息 | `message_` | 已用 |
|
||
| run 运行 | `run_` | 已用 |
|
||
| agent_turn Agent 轮次 | `turn_` | 规范 |
|
||
| model_call 模型调用及重试尝试 | `model_call_` | 规范 |
|
||
| context_snapshot 模型实际上下文快照 | `context_snapshot_` | 规范 |
|
||
| plugin_snapshot Run 固定插件集合 | `plugin_snapshot_` | 规范 |
|
||
| diagnostic_grant 运行诊断临时授权 | `diagnostic_grant_` | 规范 |
|
||
| event 事件 | `event_` | 已用 |
|
||
| trace 调用链 | `trace_` | 已用 |
|
||
| user 用户 | `user_` | 已用 |
|
||
| memory 记忆 | `memory_` | 推荐 |
|
||
| memory_candidate 记忆候选 | `memory_candidate_` | 推荐 |
|
||
| memory_links 记忆关联 | `memory_link_` | 推荐 |
|
||
| character_import_job 导入任务 | `import_` | 已用 |
|
||
| character_import_item 导入条目 | `import_item_` | 推荐 |
|
||
| character_profile_candidates 档案候选 | `profile_candidate_` | 已用 |
|
||
| personality_versions 人格版本 | `personality_` | 推荐 |
|
||
| personality_proposals 人格建议 | `personality_proposal_` | 推荐 |
|
||
| mood_events 心情事件 | `mood_` | 推荐 |
|
||
| character_emotion_states 角色情绪状态 | — | PK = `character_id`（无独立 ID） |
|
||
| world_entities 世界实体 | `world_entity_` | 推荐 |
|
||
| world_relations 世界关系 | `world_relation_` | 推荐 |
|
||
| uncertainty_states 不确定状态 | `uncertainty_` | 推荐 |
|
||
| curiosity_questions 好奇问题 | `curiosity_` | 推荐 |
|
||
| exploratory_subgoals 探索目标 | `subgoal_` | 推荐 |
|
||
| evolution_candidates 演化候选 | `evolution_` | 推荐 |
|
||
| memory_timelines 时间线 | `timeline_` | 推荐 |
|
||
| timeline_events 时间线事件 | `tl_event_` | 推荐 |
|
||
| knowledge_documents 知识文档 | `knowledge_doc_` | 推荐 |
|
||
| memory_chunks 检索分块 | `chunk_` | 推荐 |
|
||
| embedding_refs 向量引用 | `emb_ref_` | 推荐 |
|
||
| media_objects 媒体对象 | `media_` | 推荐 |
|
||
| tools 工具定义 | `tool_` | 推荐 |
|
||
| tool_calls 工具调用 | `tool_call_` | 推荐 |
|
||
| skills 能力包 | `skill_` | 推荐 |
|
||
| audit_events 审计事件 | `audit_` | 推荐 |
|
||
| confirmations 确认请求 | `confirm_` | 已用（API） |
|
||
| evidence 证据 | `evidence_` | 推荐 |
|
||
| background_task 后台任务 | `task_` | 推荐 |
|
||
| idle_window 空闲窗口 | `idle_window_` | 推荐 |
|
||
| suspension 暂停点 | `suspend_` | 推荐 |
|
||
| goal 目标 | `goal_` | 推荐 |
|
||
| agent 天工阁角色 | `agent_` | 推荐 |
|
||
| big_cycle 大周天循环 | `cycle_` | 已用 |
|
||
| plan 计划 | `plan_` | 已用 |
|
||
| mcp_servers MCP 服务 | `mcp_` | 已用 |
|
||
| time_anniversaries 纪念日 | `anniv_` | 推荐 |
|
||
| idempotency 幂等键 | `idempotency_` | 已用 |
|
||
| character_situational_entries 情境词条 | `situ_` | 推荐 |
|
||
| skill_files Skill 文件版本 | `skillfile_` | 推荐 |
|
||
| lorebooks 世谱 | `lorebook_` | 推荐 |
|
||
| lorebook_entries 世谱条目 | `lorebook_entry_` | 推荐 |
|
||
| author_notes 眉批 | `author_note_` | 推荐 |
|
||
| user_personas 本相 | `user_persona_` | 推荐 |
|
||
| generation_presets 火候 | `gen_preset_` | 推荐 |
|
||
| instruct_templates 科仪 | `instruct_tpl_` | 推荐 |
|
||
| quick_replies 锦囊 | `quick_reply_` | 推荐 |
|
||
|
||
## 4. JSON 字段后缀规则
|
||
|
||
| 后缀 | 用途 | 说明 |
|
||
| --- | --- | --- |
|
||
| `_json` | 数据库列 | JSON 文本落库，如 `metadata_json`、`payload_json`、`evidence_ids_json` |
|
||
| 无后缀 | API / DTO / SSE | 对外字段不带 `_json`，如 `metadata`、`payload`、`evidence_ids` |
|
||
|
||
映射对照（详见 数据结构与数据库设计 第 3.1 节）：
|
||
|
||
| API / DTO | 数据库 |
|
||
| --- | --- |
|
||
| `metadata` | `metadata_json` |
|
||
| `payload` | `payload_json` |
|
||
| `evidence_ids` | `evidence_ids_json` |
|
||
| `evidence_refs` | `evidence_refs_json` |
|
||
|
||
对外 API 不得暴露 `_json` 后缀字段。
|
||
|
||
## 5. 通用枚举
|
||
|
||
### 5.1 `sensitivity` 敏感等级
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `none` | 无敏感信息 |
|
||
| `low` | 低敏 |
|
||
| `medium` | 中敏，默认摘要展示 |
|
||
| `high` | 高敏，不展示原文、不自动写入长期状态 |
|
||
|
||
适用：memory、event、evidence、import_item、media_object、tool_call 等所有带敏感度的对象。
|
||
|
||
### 5.2 `visibility` 事件可见性
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `public` | 可推送给前端 |
|
||
| `internal` | 仅系统内部 |
|
||
| `audit` | 仅审计 |
|
||
|
||
### 5.3 `redaction_status` 脱敏状态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `none` | 未脱敏 |
|
||
| `partial` | 部分脱敏 |
|
||
| `full` | 完全脱敏 |
|
||
|
||
### 5.4 `privacy_level` 隐私等级
|
||
|
||
| 值 | 路由策略 |
|
||
| --- | --- |
|
||
| `normal` | 可用默认远程与本地模型 |
|
||
| `sensitive` | 优先隐私标记模型，必要时用户确认 |
|
||
| `local_only` | 只允许本地或私有端点 |
|
||
|
||
适用：character、model policy、模型路由。
|
||
|
||
### 5.5 `risk_level` 风险等级
|
||
|
||
| 值 | 类型 | 策略 |
|
||
| --- | --- | --- |
|
||
| `L0` | 无风险 | 自动执行 |
|
||
| `L1` | 低风险 | 自动执行并记录 |
|
||
| `L2` | 中风险 | 策略判断 |
|
||
| `L3` | 高风险 | 用户确认 |
|
||
| `L4` | 禁止 | 拒绝执行 |
|
||
|
||
适用：tool、plan_step、tool_call、audit_event、curiosity_question、exploratory_subgoal。演化层级 `evolution_candidate.level` 复用同一组值但语义为「影响层级」，见第 12 节。
|
||
|
||
### 5.6 `permission_policy` 权限策略
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `allow` | 自动允许，仅限无副作用或本地策略明确放行的低风险动作 |
|
||
| `ask` | 按上下文判断是否确认 |
|
||
| `always_ask` | 每次执行前确认 |
|
||
| `forbidden` | 禁止调用 |
|
||
|
||
工具调用的运行时决策 `permission_decision` 取值为 `allow` / `deny` / `ask`。
|
||
|
||
### 5.7 `consent_status` 授权状态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `unknown` | 未知 |
|
||
| `granted` | 已授权 |
|
||
| `restricted` | 受限授权 |
|
||
| `revoked` | 已撤销 |
|
||
|
||
适用：media_object、voice_sample 导入、感知授权。
|
||
|
||
### 5.8 `usage_scope` 用途范围
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `reference_only` | 仅作资料参考（默认） |
|
||
| `future_voice_training` | 授权未来语音训练探索 |
|
||
| `future_voice_chat` | 授权未来实时语音对话 |
|
||
|
||
`usage_scope` 只记录授权边界，不代表当前能力已实现。
|
||
|
||
### 5.9 `pivot` 九枢模块标识
|
||
|
||
管理控制台（司命台）与九枢聚合视图的唯一枢标识，取值与 九象与九枢工程映射 的工程模块名一致。
|
||
|
||
| 值 | 九象 | 工程模块 |
|
||
| --- | --- | --- |
|
||
| `personality_core` | 灵核 | Personality Core |
|
||
| `goal_orchestrator` | 太一 | Goal Orchestrator |
|
||
| `safety_governor` | 司命 | Safety Governor |
|
||
| `perception` | 烛照 | Perception Layer |
|
||
| `world_model` | 河图 | World Model |
|
||
| `planner` | 洛书 | Planner |
|
||
| `memory` | 息壤 | Memory System |
|
||
| `tool_runtime` | 百工 | Tool Runtime |
|
||
| `agent_society` | 天工阁 | Agent Society |
|
||
|
||
### 5.10 `pivot_health` 九枢健康状态
|
||
|
||
各枢子系统的健康度聚合值，供司命台星盘呈现。前端 `MirrorState`（铜镜四态）与此枚举一一对应，无需映射层。
|
||
|
||
| 值 | 语义 | 前端呈现 |
|
||
| --- | --- | --- |
|
||
| `void` | 未启用 / 离线 | 灰点 |
|
||
| `breathing` | 运转中（有活跃运行或处理） | jade 脉动 |
|
||
| `steady` | 稳定 | jade 实心 |
|
||
| `cracked` | 告警 / 异常 / 待裁定 | cinnabar 裂痕 |
|
||
|
||
`cracked` 不得仅由前端颜色传达，须同时给出 `summary` 文字与计数。
|
||
|
||
### 5.11 `goal_level` 目标层级
|
||
|
||
太一枢（Goal Orchestrator）的目标层级，取值与 九象与九枢 §5 一致。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `highest` | 最高目标（使命级，不可轻易改） |
|
||
| `long_term` | 长期目标 |
|
||
| `session` | 会话目标 |
|
||
| `task` | 任务目标 |
|
||
| `action` | 动作（最细粒度） |
|
||
|
||
### 5.12 `goal_status` 目标状态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 待启动 |
|
||
| `active` | 进行中 |
|
||
| `completed` | 已完成 |
|
||
| `blocked` | 受阻 |
|
||
| `cancelled` | 已取消 |
|
||
|
||
### 5.15 `goal_type` 目标类型
|
||
|
||
太一枢（Goal Orchestrator）目标类型，描述目标所属领域。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `mission` | 使命型：来自命格 highest_mission |
|
||
| `relationship` | 关系型：维系/发展人物关系 |
|
||
| `skill` | 技能型：学习或提升某项能力 |
|
||
| `knowledge` | 知识型：获取/整理特定知识 |
|
||
| `maintenance` | 维护型：系统维护/自身进化 |
|
||
| `exploration` | 探索型：由内驱力好奇问题派生 |
|
||
|
||
### 5.13 `plan_status` 计划状态
|
||
|
||
洛书枢（Planner）计划状态，取值与 九象与九枢 §9 一致。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `draft` | 草案 |
|
||
| `approved` | 已批准 |
|
||
| `running` | 执行中 |
|
||
| `completed` | 已完成 |
|
||
| `failed` | 失败 |
|
||
|
||
### 5.14 `agent_role` 天工阁角色
|
||
|
||
天工阁（Agent Society）九角色，取值与 九象与九枢 §12 一致。
|
||
|
||
| 值 | 九象 | 职责 |
|
||
| --- | --- | --- |
|
||
| `historian` | 史官 | 整理记忆、记录事件 |
|
||
| `diviner` | 卜者 | 预测风险、评估不确定性 |
|
||
| `engineer` | 工师 | 执行工具和工程任务 |
|
||
| `debater` | 辩者 | 批判计划、寻找漏洞 |
|
||
| `medic` | 医官 | 监测系统健康和情绪状态 |
|
||
| `herald` | 司礼 | 维护表达风格和互动礼仪 |
|
||
| `charioteer` | 御者 | 控制机器人和外部动作 |
|
||
| `scholar` | 学士 | 检索知识、做研究 |
|
||
| `mirror` | 镜师 | 反思自我、推动演化 |
|
||
|
||
### 5.15 `isolation_mode` 隔离模式
|
||
|
||
| 值 | 说明 | 触发风险等级 |
|
||
| --- | --- | --- |
|
||
| `process` | 沙箱共享容器内进程级隔离（进程组 + rlimit） | L0-L2 |
|
||
| `container` | 每任务独立临时容器隔离（P1 起生效；P0 降级 process） | L3-L4 |
|
||
|
||
适用：sandbox exec 凭证（`isolation_mode` 字段，随 HMAC 下发，属授权属性，不进 `body_hash`）。属司命 `risk_level` 的执行侧投影，由司命按 tool policy + 代码来源决定。
|
||
|
||
## 6. 人物与生命周期
|
||
|
||
### 6.1 `character.status`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `wuji` | 无极，刚创建的空白认知态 |
|
||
| `named` | 已命名 |
|
||
| `seeded` | 已播下人格种子 |
|
||
| `initialized` | 已初始化基础人格 |
|
||
| `active` | 激活运行 |
|
||
| `paused` | 暂停 |
|
||
| `archived` | 归档 |
|
||
|
||
默认人物可直接初始化为 `initialized` 或 `active`；新建人物默认 `wuji`。
|
||
|
||
### 6.2 `owner_scope` 归属范围
|
||
|
||
当前阶段为本地单用户，取值 `local-user`。多租户启用前不扩展该枚举。
|
||
|
||
## 7. 运行时
|
||
|
||
### 7.1 `run.status`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `queued` | 排队 |
|
||
| `running` | 运行中 |
|
||
| `waiting_confirmation` | 等待用户确认 |
|
||
| `completed` | 完成 |
|
||
| `failed` | 失败 |
|
||
| `cancelled` | 已取消 |
|
||
|
||
### 7.2 `chat_session.status`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `active` | 活跃 |
|
||
| `archived` | 归档 |
|
||
| `deleted` | 已删除 |
|
||
|
||
### 7.3 `chat_message.role`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `user` | 用户消息 |
|
||
| `assistant` | 助手消息 |
|
||
| `system` | 系统消息 |
|
||
| `tool` | 工具消息 |
|
||
|
||
### 7.4 `chat_message.modality`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `text` | 文本（当前阶段唯一支持） |
|
||
| `image` | 图片 |
|
||
| `audio` | 音频 |
|
||
| `file` | 文件 |
|
||
|
||
### 7.5 Agent 轮次与模型调用诊断
|
||
|
||
每个 Agent 轮次必须持久化一条 `agent_turn` 记录；同一轮可有多次模型调用和多个工具调用。轮次、模型调用、工具调用、确认、证据和消息通过稳定 ID 关联，不能把调试信息塞入一段无结构 JSON 后失去查询能力。
|
||
|
||
#### 7.5.1 `agent_turn`
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | 是 | `turn_` 前缀 ID |
|
||
| `run_id` | 是 | 所属 Run |
|
||
| `character_id` | 条件 | 人物前台/受托 Run 必需；无身份功能 Agent 可为空 |
|
||
| `parent_turn_id` | 否 | 子 Agent 或续跑来源轮次 |
|
||
| `turn_index` | 是 | Run 内从 0 开始的单调序号 |
|
||
| `status` | 是 | 当前轮次状态；稳定值在机器 Schema 落地前不得从实现反推 |
|
||
| `started_at` / `ended_at` | 是 | UTC 时间；未结束时 `ended_at` 为空 |
|
||
| `input_message_ids` | 是 | 本轮实际领取的输入消息 ID |
|
||
| `output_message_ids` | 是 | 本轮产生的可见消息 ID |
|
||
| `context_snapshot_id` | 否 | 模型实际采用的上下文快照 |
|
||
| `plugin_snapshot_id` | 是 | 本轮固定的插件 ID、版本、摘要和配置哈希集合 |
|
||
| `model_call_ids` | 是 | 本轮所有模型调用，包含失败与重试 attempt |
|
||
| `tool_call_ids` | 是 | 本轮所有工具调用，按模型请求顺序保存 |
|
||
| `confirmation_ids` | 是 | 本轮产生或消费的请命记录 |
|
||
| `evidence_ids` | 是 | 支撑答复、行动和工具结果的证据 |
|
||
| `finish_reason` | 否 | 正常完成、取消、失败、预算或其他终止原因 |
|
||
| `error_code` | 否 | 失败时的标准错误码 |
|
||
| `trace_id` | 是 | 跨 Host、模型网关、插件、MCP、Sandbox 的调用链 |
|
||
| `diagnostic_level` | 是 | `summary` / `detailed` / `sensitive`，控制可查询内容层级 |
|
||
|
||
#### 7.5.2 `model_call`
|
||
|
||
每一次上游尝试都必须单独记录；网关 failover 或 retry 不得覆盖前一次失败。字段采用 Provider 无关语义，Provider 原始响应只在独立、限期、脱敏的调试存储中保存。
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | 是 | `model_call_` 前缀 ID |
|
||
| `turn_id` / `run_id` | 是 | 所属轮次和 Run |
|
||
| `attempt_index` | 是 | 同一逻辑模型请求的尝试序号 |
|
||
| `provider` / `endpoint_id` | 是 | 实际 Provider 与 Endpoint |
|
||
| `logical_model` / `upstream_model` | 是 | 业务逻辑模型与实际模型 |
|
||
| `capability` | 是 | chat、embedding、rerank、ASR、TTS、image 等能力 |
|
||
| `stream` | 是 | 是否流式 |
|
||
| `request_started_at` / `first_token_at` / `completed_at` | 是 | 请求、首 token 和完成时间；不可用时为空 |
|
||
| `latency_ms` / `time_to_first_token_ms` | 是 | 完整延迟与首 token 延迟 |
|
||
| `input_tokens` | 是 | 未命中缓存、按正常输入计价的 token |
|
||
| `output_tokens` | 是 | 输出 token；适用时包含可见文本与其他输出 |
|
||
| `reasoning_tokens` | 否 | Provider 明确返回时记录；不保存推理正文 |
|
||
| `cache_creation_input_tokens` | 否 | 新写入 Provider Prompt Cache 的输入 token |
|
||
| `cache_read_input_tokens` | 否 | 从 Provider Prompt Cache 命中的输入 token |
|
||
| `cache_hit` | 是 | `true` / `false` / `unknown`，只由真实 usage 字段判定 |
|
||
| `cache_key_hash` | 否 | 平台自管缓存的不可逆键摘要；不得记录 Prompt 原文 |
|
||
| `audio_input_tokens` / `audio_output_tokens` | 否 | Provider 返回音频 token 时记录 |
|
||
| `image_input_tokens` / `image_output_tokens` | 否 | Provider 返回图像 token 时记录 |
|
||
| `tool_use_count` | 是 | 该模型响应请求的工具数量 |
|
||
| `finish_reason` / `stop_sequence` | 否 | Provider 标准化停止信息；停止序列需按敏感规则脱敏 |
|
||
| `request_id` / `upstream_request_id` | 是 | 魂镜请求 ID 与 Provider 请求 ID |
|
||
| `cost_minor` / `currency` | 是 | 以货币最小单位或定点数记录本次尝试成本 |
|
||
| `error_type` / `error_code` | 否 | 失败分类与领域错误码 |
|
||
| `fallback_from_id` | 否 | 本次由哪个失败调用切换而来 |
|
||
| `usage_source` | 是 | `provider` / `gateway_estimate` / `unavailable` |
|
||
| `usage_raw_redacted` | 否 | 仅保留脱敏后的 Provider usage 扩展字段，不含消息正文 |
|
||
|
||
`input_tokens + cache_creation_input_tokens + cache_read_input_tokens` 才是该次调用的总输入规模；不同 Provider 的 usage 定义可能不同，必须同时保存 `usage_source`、Provider、模型和价格版本。不得为了填满字段伪造缓存命中或 token 数。
|
||
|
||
#### 7.5.3 工具调用诊断扩展
|
||
|
||
除 §13.1 的状态外，`tool_calls` 必须保存：`turn_id`、`step_index`、`call_index`、`call_id`、`tool_id`、`plugin_id`、`plugin_version`、`execution_backend`、`arguments_redacted`、`arguments_hash`、`result_redacted`、`result_size_bytes`、`is_error`、`error_code`、`started_at`、`ended_at`、`latency_ms`、`confirmation_id`、`policy_decision_id`、`execution_ticket_id`、`evidence_ids`、`trace_id` 和 `idempotency_key`。
|
||
|
||
完整工具参数和结果只在用户主动生成的敏感诊断包中按范围、期限和脱敏规则提供；常规数据库默认保存结构化摘要与哈希，不保存密钥、Authorization、签名 URL、文件原文或第三方高敏内容。
|
||
|
||
### 7.6 事件类型 `event.type`
|
||
|
||
命名规则：`域名.动作`，全小写点分。事件来源 `event.source` 取值 `user` / `sensor` / `model` / `tool` / `memory` / `planner` / `system` / `knocking_pivot`。
|
||
|
||
核心运行事件：
|
||
|
||
```text
|
||
run.started
|
||
run.completed
|
||
run.failed
|
||
run.cancelled
|
||
agent.started
|
||
agent.turn.started
|
||
agent.turn.ended
|
||
model.request.started
|
||
model.request.completed
|
||
model.request.failed
|
||
model.cache.observed
|
||
agent.ended
|
||
agent.cancelled
|
||
agent.failed
|
||
agent.settled
|
||
skill.activated
|
||
message.started
|
||
message.updated
|
||
message.ended
|
||
reasoning.delta
|
||
reasoning.completed
|
||
message.delta
|
||
message.completed
|
||
tool.started
|
||
tool.completed
|
||
tool.failed
|
||
tool.requires_confirmation
|
||
safety.decision
|
||
heartbeat
|
||
```
|
||
|
||
记忆与世界事件：
|
||
|
||
```text
|
||
memory.created
|
||
memory.updated
|
||
memory.deleted
|
||
memory.retrieved
|
||
```
|
||
|
||
时态事件（见 辰正时态服务设计）：
|
||
|
||
```text
|
||
time.day_break
|
||
time.solar_term
|
||
time.festival
|
||
time.milestone_hit
|
||
time.reunion
|
||
time.sentiment
|
||
time.user_care
|
||
```
|
||
|
||
演化事件（见 自我演化机制设计 第 12 节）：
|
||
|
||
```text
|
||
evolution.signal.received
|
||
evolution.replay.started
|
||
evolution.replay.completed
|
||
evolution.candidate.created
|
||
evolution.candidate.applied
|
||
evolution.candidate.rejected
|
||
mirror_world.entered
|
||
mirror_world.scenario.generated
|
||
mirror_world.delta.proposed
|
||
```
|
||
|
||
主动对话事件（见 叩心枢设计）：
|
||
|
||
```text
|
||
proactive.session
|
||
proactive.message
|
||
```
|
||
|
||
事件 `payload` 不得包含明文密钥、完整 provider 请求或高敏原文。
|
||
|
||
### 7.7 `big_cycle.status`
|
||
|
||
大周天循环运行状态（architecture §3.2）。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 已创建待执行 |
|
||
| `running` | 循环执行中 |
|
||
| `completed` | 循环完成 |
|
||
| `failed` | 循环失败 |
|
||
|
||
### 7.8 `pending_confirmations.status` 待确认记录状态
|
||
|
||
待确认工具调用的持久化记录（`pending_confirmations` 表），对应 `PendingConfirmationRecord` 模型。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 待消费（默认，等待用户 approve/deny） |
|
||
| `consumed` | 已消费（已 approve/deny，允许发生在新 worker） |
|
||
| `timed_out` | 超时（Agent 循环 `confirmation_timeout` 超时后标记） |
|
||
|
||
## 8. 记忆
|
||
|
||
### 8.1 `memory.type`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `identity` | 身份记忆 |
|
||
| `user` | 用户记忆 |
|
||
| `episodic` | 情节记忆 |
|
||
| `semantic` | 语义记忆 |
|
||
| `procedural` | 程序记忆 |
|
||
| `relational` | 关系记忆 |
|
||
| `emotional` | 情绪记忆 |
|
||
| `world` | 世界记忆 |
|
||
| `reflection` | 反思记忆 |
|
||
| `evolution` | 演化记忆 |
|
||
|
||
### 8.2 `memory.source`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `user_explicit` | 用户明确要求 |
|
||
| `conversation` | 对话抽取 |
|
||
| `material_import` | 资料导入 |
|
||
| `tool_result` | 工具结果 |
|
||
| `reflection` | 反思生成 |
|
||
|
||
### 8.3 `memory.status`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `active` | 有效 |
|
||
| `archived` | 归档 |
|
||
| `deleted` | 已删除（不得再注入上下文） |
|
||
| `superseded` | 被取代 |
|
||
|
||
删除使用 `status = deleted` + `deleted_at`，不使用 `deleted` 布尔字段。
|
||
|
||
### 8.4 `memory.provenance_type` 来源形态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `observed` | 观察 |
|
||
| `inferred` | 推断 |
|
||
| `user_stated` | 用户陈述 |
|
||
| `imported` | 资料导入 |
|
||
|
||
### 8.5 `memory_links.relation` 记忆关联关系
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `derived` | 派生 |
|
||
| `related` | 相关 |
|
||
| `conflict` | 冲突 |
|
||
| `superseded` | 取代 |
|
||
| `summarized` | 汇总 |
|
||
|
||
## 9. 知识库与检索
|
||
|
||
详见 知识库与结构化记忆检索设计。
|
||
|
||
### 9.1 检索分块 `chunk.scope`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `memory` | 个人记忆 |
|
||
| `knowledge` | 背景、世界观、聊天记录 |
|
||
| `world` | 世界模型 |
|
||
|
||
### 9.2 `memory_chunks.source_type`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `memory` | 记忆 |
|
||
| `import_item` | 导入条目 |
|
||
| `message` | 对话消息 |
|
||
| `knowledge_doc` | 知识文档 |
|
||
| `world_entity` | 世界实体 |
|
||
| `world_relation` | 世界关系 |
|
||
| `reflection` | 反思 |
|
||
|
||
### 9.3 `knowledge_documents.scope`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `personal` | 人物私有 |
|
||
| `shared` | 多人物共享 |
|
||
| `worldview` | 世界观共享层 |
|
||
|
||
### 9.4 `knowledge_documents.doc_type`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `background_story` | 背景故事 |
|
||
| `world_setting` | 世界观设定 |
|
||
| `character_profile` | 人物设定 |
|
||
| `diary` | 日记 |
|
||
| `chat_history` | 聊天记录 |
|
||
| `external_doc` | 外部文档 |
|
||
|
||
### 9.5 `knowledge_documents.status`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `active` | 有效 |
|
||
| `archived` | 归档 |
|
||
| `deleted` | 已删除 |
|
||
| `superseded` | 被取代 |
|
||
|
||
### 9.6 时间线 `memory_timelines.scope`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `natural` | 自然时间线 |
|
||
| `entity` | 实体时间线 |
|
||
| `topic` | 主题时间线 |
|
||
| `relationship` | 关系时间线 |
|
||
|
||
### 9.7 `timeline_events.event_type`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `memory` | 记忆节点 |
|
||
| `world_change` | 世界状态变化 |
|
||
| `interaction` | 交互节点 |
|
||
| `milestone` | 里程碑 |
|
||
|
||
## 10. 资料导入
|
||
|
||
### 10.1 `material_type` 资料类型
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `chat_history` | 历史聊天记录 |
|
||
| `character_profile` | 人物基础设定 |
|
||
| `background_story` | 背景故事 |
|
||
| `role_card` | 角色卡 |
|
||
| `world_setting` | 世界观设定 |
|
||
| `style_sample` | 语气样例 |
|
||
| `voice_sample` | 人物语音样本 |
|
||
| `diary` | 日记 |
|
||
| `other` | 其他 |
|
||
|
||
### 10.2 导入 `source_type`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `uploaded_file` | 上传文件 |
|
||
| `pasted_text` | 粘贴文本 |
|
||
| `external_export` | 外部导出 |
|
||
| `manual_profile` | 手动资料 |
|
||
| `media_upload` | 媒体上传 |
|
||
|
||
### 10.3 `character_import_jobs.status` 导入状态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 已创建待处理 |
|
||
| `uploaded` | 已接收 |
|
||
| `parsing` | 解析中 |
|
||
| `parsed` | 已解析为条目 |
|
||
| `safety_scanning` | 隐私安全扫描中 |
|
||
| `safety_blocked` | 高风险阻断 |
|
||
| `extracting_profile` | 生成档案候选 |
|
||
| `extracting_memory` | 生成记忆候选 |
|
||
| `generating_personality_proposals` | 生成人格建议 |
|
||
| `reviewing` | 等待用户审核 |
|
||
| `partially_applied` | 部分候选已应用 |
|
||
| `completed` | 完成 |
|
||
| `failed` | 失败 |
|
||
| `cancelled` | 已取消 |
|
||
| `deleted` | 已删除 |
|
||
|
||
### 10.4 `import_item.item_type` 导入条目类型
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `message` | 聊天消息 |
|
||
| `profile_field` | 档案字段 |
|
||
| `paragraph` | 段落 |
|
||
| `world_fact` | 世界事实 |
|
||
| `style_sample` | 风格样例 |
|
||
| `audio_segment` | 音频片段 |
|
||
| `transcript_segment` | 转写片段 |
|
||
|
||
### 10.5 `import_item.role` 导入条目角色
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `user` | 用户 |
|
||
| `assistant` | 助手 |
|
||
| `system` | 系统 |
|
||
| `other` | 其他 |
|
||
|
||
### 10.6 候选审核 `candidate.status`
|
||
|
||
适用于 `character_profile_candidates`、`memory_candidates`、`personality_proposals`：
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 待审核 |
|
||
| `approved` | 通过 |
|
||
| `rejected` | 拒绝 |
|
||
| `merged` | 合并 |
|
||
| `applied` | 已应用 |
|
||
|
||
`personality_proposals` 额外可取 `submitted_to_evolution`（已转入演化候选）。
|
||
|
||
## 11. 世界模型
|
||
|
||
### 11.1 `world_entity.type`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `self` | 自身状态 |
|
||
| `person` | 人物（用户、联系人） |
|
||
| `object` | 物体 |
|
||
| `place` | 地点 |
|
||
| `device` | 设备 |
|
||
| `project` | 项目 |
|
||
| `task` | 任务 |
|
||
| `concept` | 概念 |
|
||
|
||
### 11.2 世界状态类型 `state_type`
|
||
|
||
世界模型需区分事实与推断（见 世界模型设计 第 5 节），统一英文枚举如下：
|
||
|
||
| 值 | 对应中文 | 说明 |
|
||
| --- | --- | --- |
|
||
| `fact` | 事实 | 已确认 |
|
||
| `observation` | 观察 | 感知得到的当前状态 |
|
||
| `inference` | 推断 | 模型推测，需置信度 |
|
||
| `hypothesis` | 假设 | 规划器临时条件 |
|
||
| `stale` | 过期 | 需刷新或验证 |
|
||
|
||
推断、假设、过期状态召回时降权，不得伪装成事实。
|
||
|
||
### 11.3 `character_world_entities.status` 世界实体候选审核状态
|
||
|
||
大周天 `_phase_memory` 阶段抽取的世界实体候选经审核流转，与 §11.2 `state_type` 正交——`status` 管审核流转，`state_type` 管事实/推断属性。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 大周天抽取的待审核候选 |
|
||
| `confirmed` | 审核通过，进入人物世界模型（默认） |
|
||
| `rejected` | 审核驳回 |
|
||
|
||
仅适用于 `character_world_entities`（人物运行时世界实体，按 `character_id` 隔离）；治理视图 `world_entities`（全局、人工维护）无此字段。
|
||
|
||
### 11.4 辰正时态枚举
|
||
|
||
辰正（Time Sense）相关枚举的单一事实源，取值与 辰正时态服务设计 §5、§7 一致。下游文档引用而非复制。
|
||
|
||
#### 11.4.1 `calendar` 历法
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `solar` | 公历 |
|
||
| `lunar` | 农历 |
|
||
|
||
#### 11.4.2 `anniversary_kind` 纪念日类型
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `birthday` | 生日 |
|
||
| `anniversary` | 周年/纪念日 |
|
||
| `milestone` | 里程碑 |
|
||
| `custom` | 自定义 |
|
||
|
||
#### 11.4.3 `anniversary_subject` 纪念日对象
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `user` | 用户 |
|
||
| `character_self` | 人物自身 |
|
||
| `relationship` | 关系（如相遇日） |
|
||
| `custom` | 自定义 |
|
||
|
||
#### 11.4.4 `anniversary_source` 纪念日来源
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `auto` | 自动锚定（如首条消息日期） |
|
||
| `manual` | 用户手动填写 |
|
||
| `imported` | 资料导入 |
|
||
|
||
#### 11.4.5 `offline_band` 离线档位
|
||
|
||
阈值写入配置，默认值如下，全部可调（见 辰正时态服务设计 §7.1）。
|
||
|
||
| 值 | 默认阈值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `active` | < 1 h | 活跃 |
|
||
| `short_absence` | 1–12 h | 短暂离线 |
|
||
| `long_absence` | 12 h – 3 d | 较长离线 |
|
||
| `reunion_impact` | > 3 d | 久别重逢 |
|
||
|
||
#### 11.4.6 `care_kind` 关怀类型
|
||
|
||
`time.user_care` 事件的关怀类型（见 辰正时态服务设计 §7.3）。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `late_night` | 深夜持续聊天 |
|
||
| `early_morning` | 清晨异常出现 |
|
||
| `overwork` | 深夜工作/学习 |
|
||
| `festival_lonely` | 节日孤独 |
|
||
| `birthday` | 用户生日 |
|
||
| `jetlag` | 时差关怀 |
|
||
|
||
#### 11.4.7 `sentiment_trigger` 感慨触发类型
|
||
|
||
`time.sentiment` 事件的触发类型（见 辰正时态服务设计 §7.2）。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `duration_node` | 认识时长有感节点 |
|
||
| `anniversary_prewarm` | 周年预热 |
|
||
| `late_night_overlay` | 深夜叠加 |
|
||
| `reunion_memory` | 久别重逢+临别记忆 |
|
||
| `solar_term` | 强节气 |
|
||
| `season_resonance` | 季节共振（v2） |
|
||
|
||
#### 11.4.8 `day_period` 现代时段
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `凌晨` | 0–5 点 |
|
||
| `清晨` | 5–8 点 |
|
||
| `上午` | 8–11 点 |
|
||
| `中午` | 11–13 点 |
|
||
| `下午` | 13–17 点 |
|
||
| `傍晚` | 17–19 点 |
|
||
| `夜晚` | 19–23 点 |
|
||
| `深夜` | 23–24 点 |
|
||
|
||
#### 11.4.9 `emotion.mood` 情绪类型
|
||
|
||
灵核情绪状态机的 mood 枚举（见 人格系统设计 §11.1）。
|
||
辰正 `time.*` 事件驱动派生；信号源见 §11.4.6 `care_kind` / §11.4.7 `sentiment_trigger`。
|
||
|
||
| 值 | 说明 | 触发场景 |
|
||
| --- | --- | --- |
|
||
| `neutral` | 平静 | 基线 / 衰减回归 |
|
||
| `pleased` | 愉悦 | 默认正向（v2 对话正向信号驱动） |
|
||
| `touched` | 感动 | `time.reunion` |
|
||
| `wistful` | 怅然怀念 | `time.sentiment`（reunion_memory / milestone / duration_node / solar_term） |
|
||
| `concerned` | 关切 | `time.user_care`（care_kind 命中） |
|
||
| `festive` | 喜庆 | v2 festival 事件直接驱动 |
|
||
| `melancholy` | 惆怅 | `time.sentiment`(late_night) / `time.user_care`(festival_lonely) |
|
||
|
||
> v1 七种工程枚举 + 中文 label；完整七情文化命名（喜 / 怒 / 哀 / 惧 / 爱 / 恶 / 欲）留 v2（人格 §11.6）。
|
||
|
||
## 12. 演化
|
||
|
||
### 12.1 `evolution_candidate.type`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `personality` | 人格 |
|
||
| `personality_weights` | 人格权重向量 |
|
||
| `retrieval_strategy` | 记忆召回策略 |
|
||
| `tool_affinity` | 工具选择偏好 |
|
||
| `memory` | 记忆 |
|
||
| `tool_strategy` | 工具策略 |
|
||
| `safety_rule` | 安全规则 |
|
||
| `world_model` | 世界模型 |
|
||
| `procedural` | 程序记忆 |
|
||
| `mood` | 心情 |
|
||
|
||
### 12.2 `evolution_candidate.level` 影响层级
|
||
|
||
复用风险等级取值，但语义为「演化影响范围」：
|
||
|
||
| 值 | 说明 | 是否可自动应用 |
|
||
| --- | --- | --- |
|
||
| `L0` | 临时运行偏好 | 可以 |
|
||
| `L1` | 会话级适配 | 可以 |
|
||
| `L2` | 人物长期偏好 | 低风险可自动候选 |
|
||
| `L3` | 人格权重更新 | 小幅可回滚可自动 |
|
||
| `L4` | 核心人格 / 明德（三观）/ 使命 / 安全边界 | 不可，必须用户确认 |
|
||
|
||
### 12.3 `evolution_candidate.scope` 作用域
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `character_scope` | 仅当前人物 |
|
||
| `user_scope` | 仅与某用户的互动 |
|
||
| `task_scope` | 仅某类任务 |
|
||
| `global_scope` | 全局（需更严格审核） |
|
||
|
||
### 12.4 `evolution_candidate.status`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 待审核 |
|
||
| `approved` | 通过 |
|
||
| `rejected` | 拒绝 |
|
||
| `applied` | 已应用 |
|
||
|
||
### 12.5 `evolution_signal.type`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `explicit_feedback` | 显式反馈 |
|
||
| `implicit_feedback` | 隐式反馈 |
|
||
| `task_result` | 任务结果 |
|
||
| `mirror_world` | 镜界推演 |
|
||
|
||
### 12.6 `evolution_signal.polarity`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `positive` | 正向 |
|
||
| `negative` | 负向 |
|
||
| `neutral` | 中性 |
|
||
|
||
### 12.7 `evolution_candidate.source`
|
||
|
||
候选来源；大周天自我评估生成的候选标记为 `big_cycle`（见 大周天循环设计）。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `explicit_feedback` | 显式反馈 |
|
||
| `implicit_feedback` | 隐式反馈 |
|
||
| `task_result` | 任务结果 |
|
||
| `mirror_world` | 镜界推演 |
|
||
| `manual_review` | 人工编辑 |
|
||
| `big_cycle` | 大周天自我评估 |
|
||
|
||
### 12.8 `exploratory_subgoal.status` 探索性次生目标审核状态
|
||
|
||
大周天内驱力产出的探索性次生目标，可审核但本期不自动执行（见 大周天循环设计）。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `candidate` | 待审核候选（默认） |
|
||
| `approved` | 审核通过（仅标记，不自动执行） |
|
||
| `deferred` | 暂缓 |
|
||
| `rejected` | 审核驳回 |
|
||
|
||
## 13. 工具与安全
|
||
|
||
### 13.1 `tool_calls.status`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 待执行 |
|
||
| `running` | 执行中 |
|
||
| `completed` | 完成 |
|
||
| `failed` | 失败 |
|
||
| `denied` | 被拒绝 |
|
||
|
||
### 13.2 `audit_event.actor`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `user` | 用户 |
|
||
| `system` | 系统 |
|
||
| `tool` | 工具 |
|
||
|
||
### 13.3 `audit_event.decision` 审计裁定结果
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `auto` | 自动放行（L0/L1 或 `allow` 策略） |
|
||
| `approved` | 人工朱批放行 |
|
||
| `denied` | 人工朱批驳回 |
|
||
| `blocked` | 策略阻断（`forbidden` / L4） |
|
||
|
||
适用：audit_event、司命台起居注时间河。
|
||
|
||
> 实现现状：代码当前 `decision` 值集与上述规范枚举存在偏差（`allow`/`deny`/`reject` 等），详见 §19 待统一项。
|
||
|
||
### 13.4 运行诊断访问协议
|
||
|
||
详细 Turn、模型调用、工具参数摘要、缓存与成本信息不随普通 Run/消息接口返回。调用方必须同时具备普通登录态和专用短期诊断授权；单独持有任一凭证均不足以读取。
|
||
|
||
#### 13.4.1 请求头命名与类型
|
||
|
||
新自定义 HTTP 字段不使用 `X-` 前缀。RFC 6648 已废弃以 `X-` 表示私有/实验参数的做法；产品命名空间直接使用 `Hunjing-`。HTTP 字段名按 RFC 9110 **大小写不敏感**，服务端必须把 `hunjing-diagnostic-token` 与本文规范写法视为同一字段；文档和 SDK 统一生成下表大小写。
|
||
|
||
| 请求头 | ABNF / 值类型 | 必需 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `Authorization` | `Bearer SP 1*b64token` | 是 | 普通访问令牌，语法遵循 RFC 6750，如 `Bearer eyJ...` |
|
||
| `Hunjing-Diagnostic-Token` | `1*(ALPHA / DIGIT / "-" / "_")` | 是 | 不带 `Bearer` 前缀的 opaque token；规范前缀为 `hjd_`，建议总长 47 字符，即 `hjd_` + 43 个 base64url 字符 |
|
||
| `Hunjing-Diagnostic-Purpose` | 下表枚举 token | 是 | 访问用途；不是自由文本，防止日志注入和不可聚合 |
|
||
| `Hunjing-Request-ID` | `1*64(ALPHA / DIGIT / "-" / "_")` | 推荐 | 调用方生成的幂等/追踪 ID；不接受空格、逗号或重复字段 |
|
||
|
||
`Hunjing-Diagnostic-Purpose` 取值：
|
||
|
||
| 值 | 场景 |
|
||
| --- | --- |
|
||
| `user_inspection` | 用户检查自己的 Run |
|
||
| `support_case` | 用户主动授权的支持工单 |
|
||
| `security_investigation` | 经审批且对象受限的安全调查 |
|
||
| `automated_evaluation` | 受控评测读取非敏感诊断字段 |
|
||
|
||
所有字段都是**单值字段**，同名重复、逗号列表、空值、前后空白、CR/LF/NUL、超过长度上限或未知 Purpose 一律返回 `400 invalid_request`。令牌只能通过 TLS 请求头传递，不得放入 URL query、请求体、Cookie、SSE event data 或 WebSocket URL。
|
||
|
||
禁止使用 `X-Debug-Token`、`X-Hunjing-*`、查询参数、Cookie 或普通管理员布尔值替代专用诊断令牌。反向代理、APM 和访问日志必须对 `Authorization` 与 `Hunjing-Diagnostic-Token` 完全脱敏。
|
||
|
||
请求示例：
|
||
|
||
```http
|
||
GET /v1/runs/run_01J.../diagnostics?level=detailed HTTP/1.1
|
||
Host: api.example.com
|
||
Authorization: Bearer eyJhbGciOi...
|
||
Hunjing-Diagnostic-Token: hjd_Qm9keV9pc19vcGFxdWVfYW5kX3JhbmRvbV9ieXRlcw
|
||
Hunjing-Diagnostic-Purpose: user_inspection
|
||
Hunjing-Request-ID: request_01JABCDEF
|
||
Accept: application/json
|
||
```
|
||
|
||
#### 13.4.2 `diagnostic_grant`
|
||
|
||
诊断令牌只保存哈希；明文只在签发响应中出现一次。授权记录至少包含：`id`、`token_hash`、`issuer_user_id`、`subject_user_id`、`personal_domain_id`、可选 `character_id` / `run_id` / `turn_id`、`scopes`、`diagnostic_level`、`purpose`、`support_case_id`、`issued_at`、`expires_at`、`used_at`、`max_uses`、`revoked_at`、`region_id` 和 `created_trace_id`。
|
||
|
||
作用域至少区分：
|
||
|
||
| Scope | 可读取内容 |
|
||
| --- | --- |
|
||
| `diagnostics:turn:summary` | 轮次状态、消息/调用 ID、耗时、工具名、聚合 token 与成本 |
|
||
| `diagnostics:model:usage` | 每次模型 attempt、Provider/模型、token、缓存、延迟、成本、错误 |
|
||
| `diagnostics:tool:summary` | 工具、插件、状态、确认、耗时、结果大小和脱敏摘要 |
|
||
| `diagnostics:tool:sensitive` | 经额外确认后的参数/结果敏感诊断视图；默认不签发 |
|
||
| `diagnostics:context:manifest` | Context Snapshot 的来源 ID、类型、token 数和裁剪原因，不含隐藏 CoT |
|
||
| `diagnostics:audit:read` | 与本次诊断访问和目标 Run 相关的审计记录 |
|
||
|
||
授权默认绑定一个 `run_id`，最长有效期 15 分钟、默认单次使用；支持包可绑定 `support_case_id` 并采用更短的内容保留期限。跨人物、跨镜域和跨区域授权均拒绝，管理员角色不能自动扩大令牌范围。
|
||
|
||
#### 13.4.3 JSON 数据类型与空值规则
|
||
|
||
诊断 API 使用 `application/json`，字段名为 `snake_case`。机器 Schema 使用 OpenAPI 3.1 / JSON Schema 2020-12。通用类型：
|
||
|
||
| 语义 | JSON 类型 / 格式 | 规则 |
|
||
| --- | --- | --- |
|
||
| ID | `string` | 必须带契约前缀；不使用裸整数 ID |
|
||
| 时间 | `string`, `format: date-time` | UTC RFC 3339，统一输出 `Z`；数据库可用 `TIMESTAMPTZ` |
|
||
| 时长 | `integer` | 毫秒，字段后缀 `_ms`，必须 `>= 0` |
|
||
| Token / 次数 / 字节 | `integer` | 必须 `>= 0`；不得使用浮点 |
|
||
| 成本 | `integer` + `string` | `cost_minor` 为货币最小单位，`currency` 为大写 ISO 4217；禁止二进制浮点金额 |
|
||
| 比率 / 分数 | `number` | 仅用于置信度、相似度等；Schema 明确范围 |
|
||
| 布尔 | `boolean` | 不使用 `0/1` 或字符串 `"true"` |
|
||
| 枚举 | `string` | 只接受契约登记值；未知新值由客户端按 unknown 分支显示，不能崩溃 |
|
||
| 哈希 | `string` | 小写十六进制或明确 base64url；字段说明算法，如 SHA-256 |
|
||
| 可选未知值 | `null` | Provider 未返回或尚未发生时使用；不得用 `0`、空字符串或 `false` 冒充未知 |
|
||
| 空集合 | `array` / `object` | 已知为空时返回 `[]` / `{}`；字段不适用时用 `null` 或按 Schema 省略，二者不能混用 |
|
||
|
||
规范规则：
|
||
|
||
- 必需但当前未知的 usage 字段返回 `null`；已知真实值为 0 时返回 `0`；
|
||
- `cache_hit` 是 `true | false | null`：只有 `cache_read_input_tokens > 0` 时为 `true`，Provider 明确返回 0 时为 `false`，未提供缓存 usage 时为 `null`；
|
||
- `reasoning_tokens` 只保存数量，不保存 reasoning 内容；
|
||
- `arguments_redacted` / `result_redacted` 类型是 JSON object 或 string，由工具 Schema 决定，并必须同时携带 `redaction_status`；
|
||
- `usage_raw_redacted` 是 object，禁止嵌入原始消息、Prompt、工具参数、密钥和 Header；
|
||
- API 不返回数据库 `_json` 后缀字段；
|
||
- 大整数在 JSON 安全整数范围内使用 integer，超过范围的 Provider 原值先规范化为十进制 string 并在扩展字段注明。
|
||
|
||
标准响应骨架：
|
||
|
||
```json
|
||
{
|
||
"run_id": "run_01J...",
|
||
"diagnostic_level": "detailed",
|
||
"turns": [
|
||
{
|
||
"id": "turn_01J...",
|
||
"turn_index": 3,
|
||
"started_at": "2026-09-02T08:00:00.000Z",
|
||
"ended_at": "2026-09-02T08:00:02.420Z",
|
||
"model_calls": [
|
||
{
|
||
"id": "model_call_01J...",
|
||
"attempt_index": 0,
|
||
"provider": "anthropic",
|
||
"logical_model": "default-chat",
|
||
"upstream_model": "provider-model-id",
|
||
"stream": true,
|
||
"input_tokens": 1240,
|
||
"output_tokens": 186,
|
||
"reasoning_tokens": null,
|
||
"cache_creation_input_tokens": 0,
|
||
"cache_read_input_tokens": 980,
|
||
"cache_hit": true,
|
||
"usage_source": "provider",
|
||
"latency_ms": 2310,
|
||
"time_to_first_token_ms": 420,
|
||
"tool_use_count": 1,
|
||
"cost_minor": 3,
|
||
"currency": "USD"
|
||
}
|
||
],
|
||
"tool_calls": [
|
||
{
|
||
"id": "tool_call_01J...",
|
||
"call_index": 0,
|
||
"tool_id": "tool_web_search",
|
||
"status": "completed",
|
||
"arguments_redacted": {"query": "[REDACTED]"},
|
||
"redaction_status": "partial",
|
||
"result_size_bytes": 4210,
|
||
"latency_ms": 780,
|
||
"is_error": false
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 13.4.4 访问规则
|
||
|
||
1. 先验证普通登录态，再验证诊断令牌哈希、期限、使用次数、撤销状态、region 和 scope；
|
||
2. 路径中的 `run_id` / `turn_id` 必须与令牌绑定对象一致，不能由调用方扩大；
|
||
3. 用户可为自己的 Run 签发 `summary` 和 `model:usage`；敏感工具视图需要重新认证并逐次确认；
|
||
4. 支持人员只能使用用户主动生成、绑定支持工单的令牌，日常管理员默认不能查看私密原文；
|
||
5. 每次成功或失败访问均写不可缺审计，至少记录 actor、grant、purpose、对象、scope、结果、IP/设备摘要、时间和 trace；
|
||
6. 响应设置 `Cache-Control: no-store, private`、`Pragma: no-cache`，不得进入 CDN、浏览器持久缓存或搜索索引；
|
||
7. 响应按 `diagnostic_level` 脱敏，永不返回 Provider/BYOK/MCP token、Authorization、签名 URL、私箧明文或隐藏 chain-of-thought；
|
||
8. 删除和撤权立即影响诊断查询；授权令牌不能绕过删除墓碑或区域驻留。
|
||
|
||
#### 13.4.5 诊断错误码
|
||
|
||
领域错误映射到 §15.1 标准错误码：
|
||
|
||
| 领域错误 | 场景 | 标准错误 |
|
||
| --- | --- | --- |
|
||
| `diagnostic_token_missing` | 缺少专用请求头 | `permission_denied` |
|
||
| `diagnostic_token_invalid` | 哈希、格式或签名无效 | `permission_denied` |
|
||
| `diagnostic_token_expired` | 已过期 | `permission_denied` |
|
||
| `diagnostic_token_revoked` | 已撤销 | `permission_denied` |
|
||
| `diagnostic_scope_denied` | Scope 或诊断层级不足 | `permission_denied` |
|
||
| `diagnostic_subject_mismatch` | 访问对象与绑定对象不一致 | `not_found` |
|
||
| `diagnostic_region_mismatch` | 跨数据区域读取 | `permission_denied` |
|
||
| `diagnostic_sensitive_confirmation_required` | 需要敏感诊断逐次确认 | `requires_confirmation` |
|
||
|
||
### 13.5 `skills.status` / `mcp_servers.status` 能力启用状态
|
||
|
||
百工能力包与 MCP 服务的启用状态，默认 `enabled`，预留 `disabled` 等扩展。
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `enabled` | 已启用（默认） |
|
||
|
||
## 14. 证据
|
||
|
||
### 14.1 `evidence.source_type`
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `event` | 一炁事件 |
|
||
| `message` | 消息 |
|
||
| `import_item` | 导入条目 |
|
||
| `memory` | 记忆 |
|
||
| `tool_result` | 工具结果 |
|
||
| `user_confirmation` | 用户确认 |
|
||
| `manual_note` | 手动备注 |
|
||
| `perception_summary` | 感知摘要 |
|
||
| `audit_event` | 审计事件 |
|
||
|
||
Evidence 统一规则见 Evidence 证据体系设计。
|
||
|
||
## 15. 错误码字典
|
||
|
||
错误码分为「API 标准错误码」（对外统一口径）和各「领域层错误码」（内部产生，需映射到标准错误码）。所有错误信息对外输出前必须脱敏，不得包含密钥、Authorization header、签名 URL、完整 provider 请求或高敏原文。对外响应的 `code` 只取 15.1 的 API 标准错误码；领域层错误码通过 15.2–15.8 的映射收敛后对外暴露，不得把领域错误码直接作为 `code` 返回。
|
||
|
||
### 15.1 API 标准错误码
|
||
|
||
| 错误码 | HTTP | 说明 |
|
||
| --- | --- | --- |
|
||
| `invalid_request` | 400 | 请求格式、参数组合或业务前置条件错误 |
|
||
| `validation_failed` | 422 | 字段校验失败或枚举值非法 |
|
||
| `permission_denied` | 401 / 403 | 本地访问令牌缺失或无效，或权限不足 |
|
||
| `requires_confirmation` | 403 | 需要用户确认的高风险动作 |
|
||
| `not_found` | 404 | 资源不存在或不属于当前人物 |
|
||
| `conflict` | 409 | 状态冲突、幂等键冲突或重复提交 |
|
||
| `payload_too_large` | 413 | 文本、文件或事件 payload 超限 |
|
||
| `unsupported_media_type` | 415 | 上传文件 MIME 不被允许 |
|
||
| `context_overflow` | 413 / 400 | 上下文超限 |
|
||
| `rate_limited` | 429 | 请求频率或模型调用限流 |
|
||
| `model_error` | 502 | 模型供应商返回异常 |
|
||
| `model_rate_limited` | 429 | 模型供应商或 endpoint 限流 |
|
||
| `model_timeout` | 504 | 模型调用超时 |
|
||
| `model_config_error` | 500 | 模型配置缺失或非法 |
|
||
| `model_unavailable` | 503 | 无可用模型 endpoint |
|
||
| `model_provider_key_missing` | 500 | 选中 endpoint 缺少真实 API key 环境变量 |
|
||
| `tool_error` | 500 | 工具执行失败 |
|
||
| `safety_rejected` | 403 | 安全策略拒绝或模型拒答 |
|
||
| `internal_error` | 500 | 未预期服务端错误 |
|
||
|
||
HTTP 状态码映射详见 魂镜 API 设计 第 5.5 节。
|
||
|
||
### 15.2 模型网关（神识）错误码
|
||
|
||
| 错误码 | 触发场景 | 映射到 API 标准错误 |
|
||
| --- | --- | --- |
|
||
| `model_not_configured` | 逻辑模型缺失或无可路由端点 | `model_config_error` |
|
||
| `model_endpoint_unavailable` | endpoint 不可用、熔断或容量耗尽 | `model_unavailable` |
|
||
| `model_provider_key_missing` | 选中 endpoint 缺少真实 API key 环境变量 | `model_provider_key_missing` |
|
||
| `provider_error` | 供应商返回错误 | `model_error` |
|
||
| `provider_timeout` | 供应商超时 | `model_timeout` |
|
||
| `provider_rate_limited` | 供应商限流 | `model_rate_limited` |
|
||
| `context_overflow` | 上下文超限 | `context_overflow` |
|
||
| `capability_not_supported` | 当前逻辑模型不支持请求能力 | `model_config_error` |
|
||
| `invalid_model_response` | 响应不符合预期 | `model_error` |
|
||
| `model_refusal` | 模型拒答或安全拒绝 | `safety_rejected` |
|
||
| `privacy_route_blocked` | 隐私路由阻断，需更安全端点或用户确认 | `permission_denied` |
|
||
|
||
### 15.3 工具运行时（百工）错误码
|
||
|
||
| 错误码 | 触发场景 | 映射到 API 标准错误 |
|
||
| --- | --- | --- |
|
||
| `tool_not_found` | 工具未注册或未启用 | `tool_error` |
|
||
| `tool_disabled` | 工具被配置禁用 | `tool_error` |
|
||
| `tool_timeout` | 工具执行超时 | `tool_error` |
|
||
| `tool_input_invalid` | 工具入参不符合 schema | `validation_failed` |
|
||
| `tool_execution_failed` | 工具执行异常 | `tool_error` |
|
||
| `tool_output_too_large` | 工具结果过大 | `payload_too_large` |
|
||
|
||
### 15.4 安全治理（司命）错误码
|
||
|
||
| 错误码 | 触发场景 | 映射到 API 标准错误 |
|
||
| --- | --- | --- |
|
||
| `safety_policy_blocked` | 命中禁止策略（L4） | `safety_rejected` |
|
||
| `confirmation_required` | 高风险动作需用户确认 | `requires_confirmation` |
|
||
| `confirmation_denied` | 用户拒绝确认 | `permission_denied` |
|
||
| `confirmation_expired` | 确认请求已过期 | `invalid_request` |
|
||
| `permission_policy_blocked` | 权限策略拒绝（forbidden） | `permission_denied` |
|
||
|
||
### 15.5 记忆与检索（息壤）错误码
|
||
|
||
| 错误码 | 触发场景 | 映射到 API 标准错误 |
|
||
| --- | --- | --- |
|
||
| `memory_not_found` | 记忆不存在或不属于当前人物 | `not_found` |
|
||
| `memory_conflict` | 记忆冲突需合并或确认 | `conflict` |
|
||
| `memory_injection_overflow` | 注入记忆超出上下文预算 | `context_overflow` |
|
||
| `retrieval_failed` | 检索编排层召回失败 | `internal_error` |
|
||
|
||
### 15.6 资料导入错误码
|
||
|
||
| 错误码 | 触发场景 | 映射到 API 标准错误 |
|
||
| --- | --- | --- |
|
||
| `import_unsupported_format` | 资料格式不支持 | `unsupported_media_type` |
|
||
| `import_file_too_large` | 导入文件超限 | `payload_too_large` |
|
||
| `import_parse_failed` | 解析失败 | `invalid_request` |
|
||
| `import_safety_blocked` | 导入内容被安全扫描阻断 | `safety_rejected` |
|
||
| `import_duplicate` | 文件哈希重复 | `conflict` |
|
||
|
||
### 15.7 向量库与存储错误码
|
||
|
||
| 错误码 | 触发场景 | 映射到 API 标准错误 |
|
||
| --- | --- | --- |
|
||
| `vector_store_unavailable` | 向量库未启用或不可达 | `internal_error` |
|
||
| `vector_upsert_failed` | 写入向量失败 | `internal_error` |
|
||
| `vector_search_failed` | 向量检索失败 | `internal_error` |
|
||
| `object_store_unavailable` | 对象存储不可达 | `internal_error` |
|
||
| `object_not_found` | 对象引用不存在 | `not_found` |
|
||
|
||
### 15.8 辰正时态错误码
|
||
|
||
| 错误码 | 触发场景 | 映射到 API 标准错误 |
|
||
| --- | --- | --- |
|
||
| `time_lunar_conversion_failed` | 农历库不可用或转换失败 | `internal_error` |
|
||
| `time_context_missing` | 时区/位置上下文缺失，已降级 | `invalid_request` |
|
||
| `anniversary_invalid_date` | 纪念日日期非法（如农历闰月不存在） | `validation_failed` |
|
||
| `anniversary_not_found` | 纪念日不存在或不属于当前人物 | `not_found` |
|
||
|
||
### 15.9 错误响应标准格式
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "permission_denied",
|
||
"message": "该操作需要用户确认。",
|
||
"trace_id": "trace_xxx",
|
||
"details": {}
|
||
}
|
||
}
|
||
```
|
||
|
||
`code` 必须取 15.1 的 API 标准错误码；领域层错误码通过 15.2–15.8 的映射收敛后对外暴露。`trace_id` 贯穿 API、模型网关、工具运行时和事件链路。
|
||
|
||
## 16. 模型配置枚举
|
||
|
||
`model_hint` 可引用逻辑模型名（kebab-case）或能力槽位（下列枚举），由模型网关解析为具体模型。业务字段中的 `model_hint` 不得引用真实 provider 或真实模型名。
|
||
|
||
### 16.1 provider
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `openai` | OpenAI 厂商 |
|
||
| `deepseek` | DeepSeek 厂商；可同时配置 OpenAI 格式与 Anthropic 格式 endpoint |
|
||
| `anthropic` | Anthropic / Claude 厂商 |
|
||
| `google` | Google 厂商 |
|
||
| `minimax` | MiniMax 厂商 |
|
||
| `zhipu` | 智谱厂商 |
|
||
| `tencentcloud` | 腾讯云厂商 |
|
||
| `volcengine` | 火山引擎厂商 |
|
||
| `bailian` | 阿里云百炼厂商 |
|
||
|
||
### 16.2 routing_strategy
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `single` | 单 endpoint 或单模型路由 |
|
||
| `priority_failover` | 按 priority 选择，失败后切换备用 endpoint |
|
||
| `round_robin` | 轮询 |
|
||
| `weighted_random` | 按权重随机 |
|
||
| `sticky_weighted_random` | 带会话/运行粘性的权重随机 |
|
||
|
||
### 16.3 endpoint status
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `active` | 可用 |
|
||
| `inactive` | 手动停用 |
|
||
| `unhealthy` | 健康检查失败 |
|
||
| `cooldown` | 失败后冷却中 |
|
||
|
||
### 16.4 模型能力枚举
|
||
|
||
| 能力 | 用途 |
|
||
| --- | --- |
|
||
| `chat` | 普通对话 |
|
||
| `tool_use` | 工具调用 |
|
||
| `structured_output` | 结构化输出 |
|
||
| `reasoning` | 高复杂推理 |
|
||
| `long_context` | 长上下文 |
|
||
| `vision` | 图像理解 |
|
||
|
||
## 17. 横切关注点
|
||
|
||
横切关注点枚举，对象与字段定义见 横切关注点设计。本节为单一事实源，横切文档引用而非复制。
|
||
|
||
### 17.1 `background_task.type` 后台任务类型
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `drive_scan` | 内驱力扫描 |
|
||
| `mirror_world_replay` | 镜界反事实推演 |
|
||
| `memory_consolidation` | 记忆整理与候选审核 |
|
||
| `import_pipeline` | 资料导入流水线 |
|
||
| `evolution_apply` | 演化候选应用 |
|
||
| `time_tick` | 辰正定时 tick（跨天/节气/节日/里程碑切换检测） |
|
||
|
||
### 17.2 `background_task.trigger` 任务触发方式
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `idle_window` | 空闲时段触发 |
|
||
| `scheduled` | 定时触发 |
|
||
| `event` | 事件触发 |
|
||
| `on_demand` | 按需触发 |
|
||
|
||
### 17.3 `background_task.priority` 任务优先级
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `low` | 低优先级，可被高优先级任务打断 |
|
||
| `normal` | 普通优先级 |
|
||
| `high` | 高优先级 |
|
||
|
||
### 17.4 `background_task.status` 任务状态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 待执行 |
|
||
| `running` | 执行中 |
|
||
| `paused` | 已暂停 |
|
||
| `completed` | 已完成 |
|
||
| `failed` | 失败 |
|
||
| `cancelled` | 已取消 |
|
||
|
||
### 17.5 `suspension.kind` 暂停类别
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `confirmation` | 安全确认 |
|
||
| `cancellation` | 运行取消 |
|
||
| `interruption` | 内驱力打断 |
|
||
|
||
### 17.6 `suspension.subject_type` 暂停对象类型
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `tool_call` | 工具调用 |
|
||
| `drive_subgoal` | 内驱力探索目标 |
|
||
| `run` | 运行 |
|
||
| `memory_write` | 记忆写入 |
|
||
| `evolution_candidate` | 演化候选 |
|
||
|
||
### 17.7 `suspension.status` 暂停状态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 等待解决 |
|
||
| `approved` | 已批准 |
|
||
| `denied` | 已拒绝 |
|
||
| `expired` | 已超时 |
|
||
| `cancelled` | 已取消 |
|
||
|
||
### 17.8 `users` 用户表
|
||
|
||
用户认证基础表，存储注册用户信息。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | `user_` + ULID (VARCHAR(40)) | 主键 |
|
||
| `username` | VARCHAR(80) | 用户名，唯一且索引 |
|
||
| `email` | VARCHAR(255) | 邮箱，唯一 |
|
||
| `password_hash` | VARCHAR(255) | Argon2 密码哈希 |
|
||
| `is_active` | BOOLEAN | 是否启用（默认 true） |
|
||
| `is_admin` | BOOLEAN | 是否管理员（默认 false） |
|
||
| `created_at` | TIMESTAMPTZ | 创建时间 |
|
||
| `updated_at` | TIMESTAMPTZ | 更新时间 |
|
||
|
||
## 18. 维护规则
|
||
|
||
本表是稳定标识、枚举、前缀、事件和错误码的唯一事实源。任何变更必须：
|
||
|
||
1. 先修改本表。
|
||
2. 按影响范围同步 `docs/product/`、`docs/domain/`、`docs/architecture/`、机器可读契约和对应实现。
|
||
3. 检查 `.env.example`、`config/*.example.yaml` 是否受影响。
|
||
4. 在提交说明中注明契约变更。
|
||
|
||
新增枚举值、新增对象前缀、新增错误码前，必须先在本表登记，再在其他文档引用。下游文档引用本表时，应写「枚举取值见契约字典」而非复制取值列表，避免再次产生漂移副本。
|
||
|
||
## 19. 待统一项
|
||
|
||
以下项当前各文档口径不统一或仅有中文描述，本表已给出推荐英文枚举，后续落地代码时以此为准：
|
||
|
||
- 世界状态类型 `state_type`（原中文「事实/观察/推断/假设/过期」→ 第 11.2 节英文枚举）。
|
||
- 记忆来源形态 `provenance_type`（新增字段，第 8.4 节）。
|
||
- 部分 ID 前缀标记为「推荐」，代码落地时须采用本表前缀。
|
||
- `audit_event.decision`（§13.3）代码当前值集为 `allow`/`approved`/`deny`/`denied`/`reject`，与规范枚举（`auto`/`approved`/`denied`/`blocked`）存在偏差：`allow`≈`auto`、`deny`≈`denied`（笔误变体）、`reject`（run.failed，≈`blocked`）。涉及约 11 文件、26 处，待后续代码统一；`services/personality.py` 已正确使用 `approved`/`denied`，可作参照。
|
||
- `memory.type`（§8.1）代码默认值（`schemas/memory.py`）当前为 `fact`，属 §11.2 `state_type` 的值误用，不在 §8.1 枚举内；待后续改为合法值（建议 `user`）。
|