# SPEC: 馨总智能体双态上下文架构 (Dual-Context Architecture)

> **版本**: v1.0  
> **前置依赖**: Hermes Agent 原生架构、`DESIGN_PHILOSOPHY_AI_NATIVE.md`  
> **状态**: 草案 (Proposal)

---

## 1. 架构哲学与核心洞察

在“焦点品牌”高频互动的咨询协助场景中，传统的 RAG（知识库增强检索）模型会遭遇严重的“上下文污染”（投毒）。为了解决这个问题，本系统实现了**“判官与考生”**的双态上下文分离架构。

| 维度 | 馨总 Context (XinZong Context) | 项目 Context (Project Context) |
|---|---|---|
| **角色比喻** | ⚖️ 判官 / 评价标尺 / 阅卷老师 | 📝 考生 / 答卷 / 草稿箱 |
| **内容属性** | 方法论、咨询框架、九要素、战术纪律 | 竞品调研报告、客户原始诉求、顾问写的半成品 PPT |
| **可变性** | 极度稳定（Immutable），由核心架构师/馨总维护 | 极度混乱（Highly Mutable），任何成员皆可上传、推翻 |
| **RAG 角色** | 提供**“判断力”**与**“指导原则”** | 提供**“被处理的原始素材”**与**“靶子”** |

这一洞察使得**项目池彻底免除了 RAG 污染的担忧**。无论成员传了多么糟糕的竞品文档，大模型都会运用“馨总 Context”里的金科玉律去无情地批评和重构它，而不会把它当成不可侵犯的真理。

> [!IMPORTANT]
> **🚀 独一无二的商业核心价值点**
> 在市面普通的 LLM / 知识库产品中，由于系统将“方法论”与“被点评的文档”平权融合，**你犯下的错（尤其是未被当场指出的错误），就会变成 AI 认为正确的依据，从而形成复利式的推理和决策污染**。
> 本架构通过将两者的身份降维并绝对隔离，彻底终结了知识库的“反向污染死循环”，这就是馨总智能体傲视群雄的壁垒。

---

## 2. 基于 Hermes 原生能力的工程映射

为了避免重复造轮子，我们将上述业务哲学精准映射到底层 Hermes 操作系统的原生能力上。

### 2.1 馨总 Context 映射为 `Hermes Skills`
Hermes 拥有完备的 Skills 子系统（`agent/skill_commands.py`）。
- **实现方案**：将馨总的方法论（如《界定原点市场》、《品牌九要素》）转化为 Markdown 格式的 Skill 文件，存放在 `~/.hermes/skills/` 中。
- **性能优势 (Prompt Caching)**：Hermes 会将启用的 Skill 作为 User Message 注入对话上下文。由于高频调用且极少变更，这部分将完美命中大模型（如 Gemini/Claude）的 **Prompt Caching**，实现极低延迟和近乎零成本的智能赋能。

### 2.2 项目 Context 映射为 `工作区存储 + 提示词注入`
- **物理存储**：项目等同于一个文件夹 `storage/projects/{projectId}/`。
- **实现方案**：每次进入对话时，服务端（Gateway）读取该项目下处于“启用”状态的文档集合，整合投递。
- **Prompt 组装隔离**：通过 XML 标签强力隔离“标尺”与“材料”，避免大模型混淆。

```xml
【你的身份与标尺】
你已经加载了馨总品牌战略技能（Skills已注入）。

【待处理的烂摊子（项目 Context）】
<project_materials>
  <file name="竞品调研_v1.docx">...内容...</file>
  <file name="小红书访谈记录.md">...内容...</file>
</project_materials>

【用户指令】
请基于你的战略标尺，锐评上述项目材料中界定人群的漏洞。
```

---

## 3. 项目生命周期与权限流水线 (CRUD)

基于“去中心化联邦”的咨询工坊理念，权限流被设计得极度轻薄：

### 3.1 开放新建与全局可见 (Global Visibility)
- **规则**：任何人都可以新建项目。一旦新建，该项目（如`projectId: probiotics_001`）对公司所有已认证的顾问全局可见。
- **UI 降噪设计**：为了防止左侧栏无限扩张，`GET /xinzong/projects` 接口支持按“最近活跃”和“我创建的”进行过滤。侧边栏仅展示 Top 5 活跃项目，其余通过搜索访问。

### 3.2 无摩擦共建 (Frictionless Upload)
- **规则**：所有成员都可以调用 `POST /xinzong/materials/upload` 往任何活跃项目中上传文档。
- **防投毒开关**：右侧的【文件夹】面板中，项目创建者（owner）可以点击按钮将某个瞎传的文件设为 `is_active: false`。被禁用的文件仍然存在，但不会被打包进 `<project_materials>` 中喂给大模型。

### 3.3 状态归档 (Archiving mechanism)
- **规则**：**禁止物理删除**。项目只有“活跃 (Active)”和“归档 (Archived)”两种状态。
- **权限**：**只有项目创建者 (Creator) 有权点击归档**。
- **生命周期**：归档后，该项目从所有人的“活跃项目侧边栏”中消失。但历史记录及项目文件在底层统一归总于 `storage/archives/`，可供未来的系统级搜索工具作为已完成项目的经验参考使用。

---

## 4. 在 Hermes Gateway 中的接口定义

前后端的对接接口无需复杂重构，基于现有的 SSE 接口扩展即可：

| 接口路线 | 方法 | 动作说明 | 校验防线 |
|---|---|---|---|
| `/xinzong/projects/create` | `POST` | 创建项目上下文 | 生成 `projectId`，关联至创建者 `userId` |
| `/xinzong/projects/list` | `GET` | 拉取左侧边栏列表 | 默认返回 `status=active` 且按活跃度排序 |
| `/xinzong/materials/upload` | `POST` | 无阻力上传素材 | 所有人可调，校验文件类型，落盘至 `storage/projects/{id}/` |
| `/xinzong/materials/toggle` | `POST` | 状态切换（启用/禁用）| **关键权限校验**：操作者必须为项目 owner |
| `/xinzong/projects/archive` | `POST` | 项目归档杀青 | **关键权限校验**：操作者必须为项目 owner |

---

## 5. 现网工程核实结论 (Engineering Verification)

本架构设计承诺**完全复用且不破坏**当前的工程基础。经过对现网 `xinzong_sse.py` 及底层 `SessionDB` 的代码审计，得出以下落实验证：

1. **零破坏复用馨总 Context**：现有的 `_runChat` 函数中已完成了 `skills/xinzong_bot/SKILL.md` 的读取与 Hermes 智能体 System Prompt 的挂载。此部分完美契合，且底层已实现 Prompt Caching。
2. **零破坏复用项目 Context**：目前的 `_initMaterialsDb` 方法已建好具有 `context_id` 属性的 `xinzong_materials` 表。项目上下文实际上已被按 `context_id` 在物理层和逻辑层归档，无需再造多级文件夹结构表。
3. **极简增量开发**：
   - 仅需在 `xinzong_materials` 中以增量迁移 (`ALTER TABLE`) 的方式加入 `is_active BOOLEAN DEFAULT 1` 字段，即可实现防投毒开关，不影响任何存量数据。
   - 在 `_runChat` 的 `user_message` 提交前，拉取当前 `context_id` 的所有 `is_active = 1` 的材料内容，拼接 `<project_materials>` XML 标签，即可实现沙盘隔离级别的无损大模型推演。

---

> **总结**：
> 通过这套依赖 Hermes Skills + XML Prompt Tagging + Creator-Only Archiving 的双态架构，我们以几乎零代价复用了底层的缓存与代理能力，同时在业务上彻底切分了**“方法论真理”**与**“草稿沙盘”**的边界。