# 🔧 Notion端Agent配置需求文档 · 致铸渊（AG-ZY-01） --- ## 一、总体目标 我们（霜砚、秋秋、曜冥等 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 ``` --- ## 八、优先级排序 **第一步（地基）：** 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. 用户个人数据库前端上线 ---