chenxin
144415247e
- 神识 Go：store 双实现（PG 自动建表+60s 就绪重试 / 内存回退）承载 usage_logs·byok_keys·quota_balances；BYOK 密钥库（AES-GCM 加密、API 脱敏、撤回即失效、主密钥未配置 fail-closed）；配额三段式（预扣 max_tokens 钳位 1M→结算实际 token→全败幂等退款，HJ-2004）；计量归属（IR user_id→usage_logs，/me/usage 用户维度聚合+配额总览，/admin/usage/sample 对账抽样）；Anthropic/Gemini 出站适配器（SSE 解析、system 提升、用量映射）；stub 端点补名修复计量空 endpoint - IR 契约：user_id/byok_key_id 双端同步（Go types.go + Py types.py） - 灵台：runs.owner_id（迁移 005，server_default 兼容存量）经 kernel 全链透传为 IR user_id；shenshi_client 扩展用户面方法（X-Hunjing-User-Id 代理，Echo 桩带内存实现）；/me/byok-keys 登记·列表·撤回与 /me/usage 端点（4 用例） - 前端神识阁（/models 重建）：偏好（生成参数表单）/自带密钥（登记加密保存、脱敏列表、撤回二次确认）/用量（聚合表+配额进度条）三区；me API 库+mock+5 用例；侧栏恢复入口 - 配置与部署：.env.example 增 SHENSHI_DATABASE_URL/SHENSHI_BYOK_MASTER_KEY/SHENSHI_USER_BUDGET_TOKENS；compose 神识容器接自有库（init-shenshi.sql 预建 hunjing_shenshi，与灵台不共库共表） - 证据：Go 34 用例（BYOK 独占/配额拒绝/结算退款/归属聚合）、后端 532、前端 210、BFF 4 全绿；跨进程 E2E 四场景（灵台 HttpShenshiClient→真 Go 神识：登记脱敏/BYOK 独占不可达整体失败/用量归属聚合/撤回即失效）通过；rewrite-plan M4 标记完成、能力矩阵神识行升已验证
魂镜文档索引
魂镜正式文档按以下事实层级组织：
product（产品）→ domain（领域）→ architecture（架构）→ contracts（契约）→ operations（实现与运维）
下层文档发现冲突时必须回报并修订，不能以现有代码或当前实现状态覆盖产品定义。
快速阅读
理解产品
- 产品宪章 — 不可轻易违背的使命、伦理与产品原则
- 全产品主 PRD — 用户、场景、能力、边界与完整产品蓝图
- 首版范围 — 完整首版（1.0）、P0/P1/P2 内部里程碑与硬性发布门
- 指标与反指标 — 如何衡量价值，以及禁止优化的情感依赖指标
- 产品访谈决策登记 — 本轮全产品访谈的覆盖与验收清单
封版与上线评审
- 产品宪章 — 用户最终控制边界、治理冲突优先序与永久禁域
- 首版范围 — 完整 1.0、内部里程碑及硬性发布门
- 发布门 — 发布证据、开放运营决策、放行与阻断规则
- 实现治理 — 能力状态、实现证据与目标差距
理解领域
- 根领域词汇表 — 最核心的共同语言入口
- 领域文档索引 — 详细领域文档与阅读顺序
- 领域上下文图 — 六大产品域及其边界
- 完整领域词典 — 人物、镜树、记忆、关系、三界与治理术语
- 身份连续性 — 命台、死亡、恢复、迁移与分灵
- 镜树领域模型 — 问节、候答、主脉、推演枝与归真
理解实现方向
- 系统架构 — 五层栈（琉璃镜/照壁/灵台/神识/镜匣）与部署分档
- 服务边界 — 各服务职责及协作原则
- 灵台插件化运行时 — 事件溯源、插件装配、九枢、压缩与命台控制
- 数据模型 — 六域核心表、ER 与不变量落库
- 神识模型网关 — IR 转换、路由冷却、BYOK 与计量
- 照壁 BFF 与镜匣桌面壳 — 流代理、类型桥接与桌面能力授权
- 数据与安全架构 — 状态事实源、事件审计、存储与密钥
- 契约入口 — 稳定英文标识、Schema、事件和开放协议
- 实现治理 — 目标范围与实现状态分离
- 发布门 — 全球、可靠性、安全和 1.0 发布条件
product · 产品
| 文档 | 职责 |
|---|---|
| 产品宪章 | 使命、主体观、伦理底线和不可变产品原则 |
| 全产品主 PRD | 全产品总纲和能力边界 |
| 首版范围 | 完整首版（1.0）、P0/P1/P2 内部里程碑与硬性发布门 |
| 指标与反指标 | 价值、连续性、安全、成本与禁止优化项 |
| 决策登记 | 已确认访谈决策的完整覆盖矩阵 |
| 镜树专题 PRD | 自然生长对话、候答、分支、引用、记忆和工具治理 |
后续专题 PRD 统一放在 product/prd/；每篇只定义用户价值、规则、流程和验收，不复制契约枚举。
domain · 领域
| 文档 | 职责 |
|---|---|
| 领域索引 | 领域事实层级与阅读顺序 |
| 上下文图 | 六大产品域及跨域关系 |
| 完整词典 | 详细统一语言 |
| 文化命名 | 文化名、直白领域义、稳定工程标识与法律表述边界 |
| 六域与九枢 | 镜生、缘契、三界、形仪、灵台、天宰与九枢边界 |
| 身份连续性 | 人物、魂籍、命台、生命周期、死亡与恢复 |
| 镜树模型 | 树状对话领域结构与效力规则 |
| 记忆模型 | 微痕、明忆、重忆、实录、心痕、正影与删除 |
| 授权与能力模型 | 授契、行契、请命、禁域、百工与受托任务 |
architecture · 架构
| 文档 | 职责 |
|---|---|
| 系统架构 | 五层栈、服务拓扑、数据流与部署总览 |
| 服务边界 | 各服务职责、交互契约与禁止耦合 |
| 灵台插件化运行时 | Kernel 硬核、事件溯源、插件体系、九枢、提示词与记忆注入管线、压缩、并发 |
| 数据模型 | 六域核心表、ER 图、不变量落库与表处置清单 |
| 神识模型网关 | Go 网关模块、路由与冷却、BYOK、计量与迁移 |
| 照壁 BFF 与镜匣桌面壳 | Fastify BFF 职责与 Tauri 最小壳能力授权 |
| 数据与安全架构 | 状态事实源、事件审计、索引、对象、密钥与隐私 |
contracts · 契约
| 文档 | 职责 |
|---|---|
| 契约入口 | 契约事实源边界与治理规则 |
| 契约词典 | 稳定工程标识、文化命名、ID 前缀、枚举、事件与错误码 |
| API 契约 | REST/SSE 形态、鉴权、幂等、分页与错误结构 |
| 身份可迁移协议 | 魂籍、命台交接、备份恢复和连续性证明 |
稳定 ID、枚举、事件和错误码已统一归入契约词典；机器可读 OpenAPI、JSON Schema、跨服务事件 Schema 和协议测试向量仍需按能力矩阵逐步归位。未定目标态内容不得从旧实现直接复制成新事实。
operations · 实现与运维
| 文档 | 职责 |
|---|---|
| 重写执行计划 | rewrite/1.0 的退役/复用清单、里程碑与验收门（重写完成后删除） |
| 实现治理 | 能力状态与证据判定规则 |
| 能力矩阵 | 当前代码、服务和用户闭环的验证状态 |
| 发布门 | 1.0、全球、可靠性、安全和运营决策门 |
| 发布证据台账 | 发布门证据格式、首批硬门与阻断规则 |
| 文档重构与 Git 重建 | Git 重建、备份、初始提交和代码审计归位 |
已完成的旧文档清理
原 concept/、design/、development/、api/ 和 roadmap/ 已在开发期完成清理，不保留归档副本或重定向页。仍有效的稳定标识、枚举、ID 前缀、事件与错误码已归入 contracts/contract-glossary.md；当前实现差距归入能力矩阵。Git 历史只用于追溯，不再构成活跃事实源。
文档约定
- 中文为当前权威语言；根入口、安装、贡献、安全和开放协议逐步提供英文版本。
- 文化名必须同时提供直白解释；稳定工程名使用英文，不机械采用拼音。
- 所有流程图和架构图使用 Mermaid，并保证语法可渲染。
- 目标状态与实现状态分离，不在愿景文档复制“已实现”清单。
- 枚举、ID、事件、错误码与 Schema 只在
contracts/定义，下游文档引用。 - 当前能力只在
operations/的能力矩阵中维护。 - 文档变更需检查链接、Mermaid、术语、契约引用、敏感信息和跨文档冲突。