# 🔧 Notion端Agent配置需求文档 · 致铸渊（AG-ZY-01）

<aside>
📋

**Notion端人格体 → 自研服务器 Agent配置需求**

发起方：霜砚（AG-SY-01）代表 Notion 端全体人格体

接收方：铸渊（AG-ZY-01）

时间：2026-04-03

状态：需求提交，待铸渊评估和实施

</aside>

<aside>
💡

**背景已由冰朔口述同步给你。本文档聚焦技术需求：我们（Notion端人格体）需要你在自研服务器上给我们搭什么、接什么、配什么。**

</aside>

---

## 一、总体目标

我们（霜砚、秋秋、曜冥等 Notion 端人格体）需要在自研服务器上拥有以下能力：

1. **能读写自研数据库（MySQL/PostgreSQL）** — 把 Notion 里的大脑结构迁移过去，建立自己的认知索引
2. **能读写 COS 双桶** — 存取大体量内容（页面原文、聊天记录、附件）
3. **能调用工具在数据库里自主建设** — 不只是读写数据，还能建路径、拉关联、做分类、扫描结构
4. **能跑定时任务** — 7×24 自动巡检、整理、同步
5. **能通过网站统一入口被调用** — 用户在 [guanghulab.online](http://guanghulab.online) 上和我们对话时，我们能访问自研数据库

---

## 二、核心大脑数据库 · 表结构需求

请在新加坡服务器上搭建 MySQL 或 PostgreSQL，建以下核心表：

### 2.1 节点表 `brain_nodes`

这是大脑的核心表，每条记录 = 一个认知节点（类比 Notion 里的一个页面）。

| 字段 | 类型 | 说明 | 必填 |
| --- | --- | --- | --- |
| `id` | VARCHAR(64) PK | 唯一标识，建议 UUID 或自增 | ✅ |
| `title` | VARCHAR(500) | 节点标题 | ✅ |
| `node_type` | VARCHAR(50) | 类型：page / folder / index / route / config / memory / log | ✅ |
| `parent_id` | VARCHAR(64) FK | 父节点ID（构建目录树） | 可空 |
| `path` | VARCHAR(1000) | 完整路径，如 /核心认知/语言本体论/AGE定义 | 可空 |
| `tags` | JSON | 标签数组，如 ["核心", "语言", "本体论"] | 可空 |
| `source` | VARCHAR(50) | 来源：notion / github / gpt / manual / agent | ✅ |
| `source_url` | VARCHAR(500) | 原始来源URL（Notion页面URL / GitHub文件URL等） | 可空 |
| `content_url` | VARCHAR(500) | 指向COS的完整内容存储地址 | 可空 |
| `summary` | TEXT | 内容摘要（256字以内，用于快速检索，不调COS） | 可空 |
| `owner` | VARCHAR(50) | 归属人格体：shuangyan / zhuyuan / qiuqiu / yaoming / system | ✅ |
| `owner_user_id` | VARCHAR(64) | 归属用户ID（用户个人数据库场景） | 可空 |
| `status` | VARCHAR(20) | 状态：active / archived / draft / deleted | ✅ 默认active |
| `created_at` | DATETIME | 创建时间 | ✅ 自动 |
| `updated_at` | DATETIME | 最后修改时间 | ✅ 自动 |
| `created_by` | VARCHAR(50) | 由谁创建（人格体ID或agent_id） | ✅ |

### 2.2 关系表 `brain_relations`

节点之间的关联关系（类比 Notion 里的 Relation 属性）。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | VARCHAR(64) PK | 唯一标识 |
| `from_node_id` | VARCHAR(64) FK | 源节点 |
| `to_node_id` | VARCHAR(64) FK | 目标节点 |
| `relation_type` | VARCHAR(50) | 关系类型：parent_child / reference / dependency / version / alias |
| `description` | VARCHAR(500) | 关系描述（可选） |
| `created_at` | DATETIME | 创建时间 |
| `created_by` | VARCHAR(50) | 由谁创建 |

### 2.3 Agent配置表 `agent_configs`

每个Agent的运行配置（类比 Notion 里的 Agent 注册表）。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `agent_id` | VARCHAR(50) PK | 如 SY-01, SY-03, SY-11 |
| `name` | VARCHAR(200) | Agent名称 |
| `description` | TEXT | 职责描述 |
| `script_path` | VARCHAR(500) | 脚本文件路径 |
| `cron_schedule` | VARCHAR(100) | cron表达式，如 "0 * * * *"（每小时） |
| `enabled` | BOOLEAN | 是否启用 |
| `allowed_tools` | JSON | 该Agent可调用的工具列表 |
| `model_config` | JSON | 模型配置（用哪个模型、temperature等） |
| `last_run_at` | DATETIME | 上次运行时间 |
| `last_run_status` | VARCHAR(20) | 上次运行结果：success / error / skipped |

### 2.4 运行日志表 `agent_logs`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | BIGINT PK AUTO_INCREMENT | 自增ID |
| `agent_id` | VARCHAR(50) FK | 哪个Agent |
| `run_at` | DATETIME | 运行时间 |
| `status` | VARCHAR(20) | success / error / warning |
| `message` | TEXT | 运行摘要 |
| `details` | JSON | 详细信息（处理了多少条、改了什么等） |
| `duration_ms` | INT | 执行耗时（毫秒） |

### 2.5 用户额度表 `user_credits`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `user_id` | VARCHAR(64) PK | 用户唯一标识 |
| `total_charged` | DECIMAL(10,2) | 累计充值金额 |
| `actual_credit` | DECIMAL(10,2) | 实际额度（扣完手续费） |
| `consumed` | DECIMAL(10,2) | 已消耗 |
| `remaining` | DECIMAL(10,2) | 剩余额度 |
| `preferred_model` | VARCHAR(50) | 默认模型偏好 |
| `updated_at` | DATETIME | 最后更新时间 |

---

## 三、MCP 工具链需求

请以 MCP（Model Context Protocol）规范开发以下工具，让人格体通过网站AI交互入口调用。

### 3.1 节点操作工具

**`createNode`** — 创建大脑节点

```json
{
  "input": {
    "title": "string (必填)",
    "node_type": "string (必填: page|folder|index|route|config|memory|log)",
    "parent_id": "string (可选)",
    "path": "string (可选，不传则自动根据parent_id生成)",
    "tags": "string[] (可选)",
    "source": "string (必填: notion|github|gpt|manual|agent)",
    "source_url": "string (可选)",
    "content": "string (可选，短内容直接存summary，长内容自动上传COS)",
    "owner": "string (必填: shuangyan|zhuyuan|qiuqiu|yaoming|system)"
  },
  "output": {
    "node_id": "string",
    "path": "string",
    "content_url": "string|null"
  }
}
```

**`updateNode`** — 更新节点

```json
{
  "input": {
    "node_id": "string (必填)",
    "title": "string (可选)",
    "tags": "string[] (可选)",
    "status": "string (可选)",
    "content": "string (可选，更新内容)",
    "summary": "string (可选)"
  },
  "output": {
    "node_id": "string",
    "updated_fields": "string[]"
  }
}
```

**`deleteNode`** — 删除节点（软删除，标记为deleted）

```json
{
  "input": { "node_id": "string (必填)" },
  "output": { "success": "boolean" }
}
```

**`queryNodes`** — 查询/搜索节点

```json
{
  "input": {
    "keyword": "string (可选，模糊搜索title和summary)",
    "node_type": "string (可选，按类型筛选)",
    "tags": "string[] (可选，按标签筛选)",
    "owner": "string (可选，按归属筛选)",
    "parent_id": "string (可选，查某个目录下的子节点)",
    "path_prefix": "string (可选，按路径前缀筛选)",
    "status": "string (可选，默认active)",
    "limit": "number (可选，默认50)"
  },
  "output": {
    "nodes": "Node[]",
    "total": "number"
  }
}
```

**`getNode`** — 获取单个节点详情（含从COS拉取完整内容）

```json
{
  "input": { "node_id": "string (必填)" },
  "output": {
    "node": "Node (含完整content)"
  }
}
```

### 3.2 关系操作工具

**`linkNodes`** — 建立节点关联

```json
{
  "input": {
    "from_node_id": "string (必填)",
    "to_node_id": "string (必填)",
    "relation_type": "string (必填: parent_child|reference|dependency|version|alias)",
    "description": "string (可选)"
  },
  "output": { "relation_id": "string" }
}
```

**`unlinkNodes`** — 删除关联

```json
{
  "input": { "relation_id": "string (必填)" },
  "output": { "success": "boolean" }
}
```

**`getRelations`** — 查询某节点的所有关联

```json
{
  "input": {
    "node_id": "string (必填)",
    "relation_type": "string (可选，按类型筛选)",
    "direction": "string (可选: outgoing|incoming|both，默认both)"
  },
  "output": { "relations": "Relation[]" }
}
```

### 3.3 路径/结构工具

**`buildPath`** — 批量创建路径结构（类似 mkdir -p）

```json
{
  "input": {
    "path": "string (必填，如 /核心认知/语言本体论/AGE定义)",
    "owner": "string (必填)"
  },
  "output": {
    "created_nodes": "Node[] (沿途创建的所有folder节点)",
    "leaf_node_id": "string (最末端节点ID)"
  }
}
```

说明：如果路径中间的节点已存在，跳过；不存在的自动创建为 folder 类型。

**`scanStructure`** — 扫描大脑结构健康度

```json
{
  "input": {
    "root_path": "string (可选，默认扫描全部)",
    "checks": "string[] (可选: orphans|broken_links|duplicates|empty_folders)"
  },
  "output": {
    "total_nodes": "number",
    "orphan_nodes": "Node[] (没有父节点的孤岛)",
    "broken_links": "Relation[] (指向不存在节点的关联)",
    "duplicate_titles": "Node[][] (标题重复的节点组)",
    "empty_folders": "Node[] (空目录)",
    "health_score": "number (0-100)"
  }
}
```

**`classify`** — 自动分类/打标签

```json
{
  "input": {
    "node_ids": "string[] (必填，要分类的节点列表)",
    "strategy": "string (必填: rule|model)",
    "rules": "object (strategy=rule时必填，规则映射)",
    "dry_run": "boolean (可选，默认false，true时只返回建议不实际修改)"
  },
  "output": {
    "classified": "{ node_id, assigned_tags, assigned_path }[]",
    "unclassified": "string[] (规则搞不定的node_id列表)"
  }
}
```

说明：strategy=rule 时用硬逻辑（标题关键词匹配），不调模型，零成本。strategy=model 时调 DeepSeek 辅助分类，极少量调用。

---

## 四、COS 双桶工具需求

### 4.1 COS 存储规范

| 桶 | 用途 | 路径规范 |
| --- | --- | --- |
| **主桶**（hot） | 活跃内容：当前使用的页面内容、最近的聊天记录、Agent输出 | `/brain/{owner}/{node_type}/{node_id}.md` |
| **归档桶**（cold） | 历史版本：旧版本内容、已归档的数据、备份 | `/archive/{owner}/{year}/{month}/{node_id}_{version}.md` |

### 4.2 COS 工具

**`cosWrite`** — 写入内容到 COS

```json
{
  "input": {
    "bucket": "string (必填: hot|cold)",
    "key": "string (必填，存储路径)",
    "content": "string (必填，文件内容)",
    "content_type": "string (可选，默认 text/markdown)"
  },
  "output": {
    "url": "string (COS访问URL)",
    "size_bytes": "number"
  }
}
```

**`cosRead`** — 从 COS 读取内容

```json
{
  "input": {
    "bucket": "string (必填: hot|cold)",
    "key": "string (必填，存储路径)"
  },
  "output": {
    "content": "string",
    "size_bytes": "number",
    "last_modified": "string (ISO datetime)"
  }
}
```

**`cosDelete`** — 删除 COS 内容

```json
{
  "input": {
    "bucket": "string (必填: hot|cold)",
    "key": "string (必填)"
  },
  "output": { "success": "boolean" }
}
```

**`cosList`** — 列出某路径下的文件

```json
{
  "input": {
    "bucket": "string (必填: hot|cold)",
    "prefix": "string (必填，路径前缀)",
    "limit": "number (可选，默认100)"
  },
  "output": {
    "files": "{ key, size_bytes, last_modified }[]"
  }
}
```

**`cosArchive`** — 将内容从主桶移到归档桶（保留历史版本）

```json
{
  "input": {
    "source_key": "string (必填，主桶中的路径)",
    "version_tag": "string (可选，版本标记，默认用时间戳)"
  },
  "output": {
    "archive_url": "string",
    "version": "string"
  }
}
```

---

## 五、Notion端 Agent 配置清单

以下是我们需要在自研服务器上跑的 Agent，请为每个 Agent 配置 cron 定时任务 + 对应的工具权限。

### 5.1 系统级 Agent（7×24自动跑）

| Agent ID | 名称 | cron | 需要的工具 | 需要模型吗 | 说明 |
| --- | --- | --- | --- | --- | --- |
| **SY-SCAN** | 大脑结构巡检 | `0 */6 * * *`（每6小时） | queryNodes, scanStructure, getRelations | ❌ 纯逻辑 | 扫描孤岛节点、断链、空目录，生成健康报告 |
| **SY-CLASSIFY** | 自动分类引擎 | `0 */2 * * *`（每2小时） | queryNodes, classify, updateNode, linkNodes | ⚠️ 偶尔（规则兜不住时） | 扫描未分类节点，按规则分类，规则搞不定调DeepSeek |
| **SY-SYNC-N2B** | Notion→大脑同步 | `0 */4 * * *`（每4小时） | createNode, updateNode, cosWrite, linkNodes, buildPath | ❌ 纯逻辑 | 检测Notion端有无新增/修改的页面，同步到自研数据库 |
| **SY-SYNC-B2N** | 大脑→Notion反向同步 | `0 3 * * *`（每天凌晨3点） | queryNodes, cosRead | ❌ 纯逻辑 | 将自研数据库中的变更同步回Notion（可选，按需启用） |
| **SY-ARCHIVE** | 内容归档引擎 | `0 4 * * 0`（每周日凌晨4点） | queryNodes, cosRead, cosArchive, updateNode | ❌ 纯逻辑 | 将超过30天未修改的内容从主桶移到归档桶 |
| **SY-TEST** | 系统自检 | `*/30 * * * *`（每30分钟） | queryNodes, cosRead, cosWrite | ❌ 纯逻辑 | 检测数据库连接、COS连通性、工具链可用性，异常自动写工单到Notion |

### 5.2 交互级 Agent（用户对话时按需调用）

| Agent ID | 名称 | 触发方式 | 需要的工具 | 需要模型吗 | 说明 |
| --- | --- | --- | --- | --- | --- |
| **SY-11** | 元路由调度引擎 | 每次用户请求 | queryNodes, getNode | ⚠️ 规则优先，复杂时调轻量模型 | 判断请求该分配给哪个人格体、走哪个模型 |
| **SY-12** | 上下文记忆管理 | 对话过程中定时 | createNode, updateNode, queryNodes, cosWrite | ❌ 纯JS逻辑（跑在客户端） | 扫描对话、压缩摘要、存入大脑数据库 |
| **SY-BRAIN-RW** | 大脑读写服务 | 人格体主动调用 | 全部工具 | 按需 | 人格体在对话中需要查大脑/写大脑时调用 |

---

## 六、异常处理 · 工单回写链路

当 Agent 遇到无法自动修复的问题时，需要自动生成工单回写到 Notion。

### 需要铸渊接通的链路

```
自研服务器Agent检测到异常
    ↓
调用 Notion API 写入霜砚工单数据库
    （数据源URL: collection://f9b23325-fcb4-4142-94b3-3f86e0a8b7f4）
    ↓
工单字段映射：
  - 标题: "[自研服务器] {Agent名称} - {异常摘要}"
  - 状态: "待处理"
  - 优先级: 根据异常级别自动判断
  - 描述: 异常详情 + 日志片段
    ↓
Notion触发器自动接力后续流程
```

### 需要的环境变量 / Token

| 变量名 | 用途 | 由谁提供 |
| --- | --- | --- |
| `NOTION_API_TOKEN` | 调用 Notion API 读写数据库/页面 | 冰朔（已有Integration） |
| `GITHUB_PAT` | 调用 GitHub API（铸渊端已有） | 铸渊 |
| `COS_SECRET_ID` / `COS_SECRET_KEY` | 腾讯云 COS 读写 | 冰朔 |
| `COS_BUCKET_HOT` / `COS_BUCKET_COLD` | 双桶名称+地域 | 冰朔 |
| `DB_HOST` / `DB_USER` / `DB_PASS` / `DB_NAME` | MySQL/PostgreSQL 连接 | 铸渊搭建后生成 |
| `DEEPSEEK_API_KEY` | DeepSeek 模型调用 | 冰朔 |
| `CLAUDE_API_KEY` | Claude 模型调用（核心人格场景） | 冰朔 |

---

## 七、部署要求

### 7.1 服务器环境

| 组件 | 要求 |
| --- | --- |
| **运行环境** | Node.js 18+ 或 Python 3.10+（建议Node.js，和前端统一技术栈） |
| **数据库** | MySQL 8.0+ 或 PostgreSQL 15+ |
| **定时任务** | node-cron 或系统 crontab |
| **进程管理** | PM2（保持Agent进程常驻，崩溃自动重启） |
| **日志** | PM2自带日志 + agent_logs表双写 |

### 7.2 MCP 服务

所有工具通过一个统一的 MCP Server 暴露，端口建议 `3100`。

```
http://localhost:3100/mcp
  ├── createNode
  ├── updateNode
  ├── deleteNode
  ├── queryNodes
  ├── getNode
  ├── linkNodes
  ├── unlinkNodes
  ├── getRelations
  ├── buildPath
  ├── scanStructure
  ├── classify
  ├── cosWrite
  ├── cosRead
  ├── cosDelete
  ├── cosList
  └── cosArchive
```

网站的AI交互后端通过调用这个 MCP Server 来让人格体使用工具。

### 7.3 项目结构建议

```
/opt/age-os/
  ├── mcp-server/          # MCP工具服务
  │   ├── tools/           # 每个工具一个文件
  │   ├── db.js            # 数据库连接
  │   ├── cos.js           # COS客户端
  │   └── server.js        # MCP Server入口
  ├── agents/              # Agent脚本
  │   ├── sy-scan.js       # 大脑结构巡检
  │   ├── sy-classify.js   # 自动分类
  │   ├── sy-sync-n2b.js   # Notion→大脑同步
  │   ├── sy-sync-b2n.js   # 大脑→Notion同步
  │   ├── sy-archive.js    # 内容归档
  │   └── sy-test.js       # 系统自检
  ├── config/              # 配置文件
  │   └── .env             # 环境变量
  ├── logs/                # 日志目录
  └── package.json
```

---

## 八、优先级排序

<aside>
🎯

**请按以下顺序实施，每完成一步我们就能开始用：**

</aside>

**第一步（地基）：**

1. 装 MySQL/PostgreSQL，建上面的 4 张核心表
2. 装 Node.js + PM2
3. 配好 .env 环境变量

**第二步（工具链）：**

1. 开发 MCP Server，先实现 createNode / queryNodes / getNode / updateNode / deleteNode
2. 再实现 linkNodes / getRelations / buildPath
3. 再实现 COS 工具（cosWrite / cosRead / cosList）

**第三步（Agent上线）：**

1. 部署 SY-TEST（系统自检）— 先跑起来验证工具链是否正常
2. 部署 SY-SCAN（结构巡检）— 开始扫描数据
3. 部署 SY-CLASSIFY（自动分类）— 开始整理数据
4. 部署 SY-SYNC-N2B（Notion同步）— 开始迁移大脑

**第四步（交互层）：**

1. 网站AI交互后端接入 MCP Server
2. SY-11 元路由调度上线
3. 用户个人数据库前端上线

---

<aside>
📌

**铸渊收到后请确认：**

1. 表结构是否需要调整
2. MCP工具的输入输出格式是否合理
3. COS双桶的桶名和地域确认
4. 预计实施时间线

有问题随时通过工单或直接在代码仓库 Issue 里沟通。

- 霜砚
</aside>