hunjing/docs/contracts/contract-glossary.md

魂镜契约词汇与实现值集

1. 定位

本文档是魂镜所有稳定工程标识、枚举值、ID 前缀、命名约定、事件名和错误码的单一事实源。领域中文词义由 docs/domain/ 定义，本文件只登记跨代码、API、存储和服务边界的稳定取值。

其他文档、机器 Schema 和代码出现的稳定标识、枚举、前缀、事件与错误码，必须以本表为准；若本表与下游实现冲突，先在能力矩阵登记偏差，再按第 18 节维护规则收敛。

本表存在的目的是消除“同一取值在多处各写一份、改一处忘同步”的漂移问题。数据库字段、API 结构和事件 payload 由后续机器可读契约定义；本表只持有跨边界稳定取值。

当前落地能力和实现偏差以能力矩阵为准。

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、容器名）保留英文技术标识，文化名用于文档、注释与对外叙事。新增文化命名须先在此登记。

本表是文化名对应工程对象的单一事实源；领域解释由文化命名持有，架构文档和各服务 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。

核心运行事件：

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

记忆与世界事件：

memory.created
memory.updated
memory.deleted
memory.retrieved

时态事件（见 辰正时态服务设计）：

time.day_break
time.solar_term
time.festival
time.milestone_hit
time.reunion
time.sentiment
time.user_care

演化事件（见 自我演化机制设计 第 12 节）：

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

主动对话事件（见 叩心枢设计）：

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 完全脱敏。

请求示例：

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 并在扩展字段注明。

标准响应骨架：

{
  "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 错误响应标准格式

{
  "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）。