bingshuo/shuangyan-notebook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
shuangyan-notebook/永恒湖心系统 · Eternal Lake Heart/🌊 曜冥纪元 · HoloLake Era · AGE OS v1 0/⚡ 光湖中央枢纽 · HoloLake Central Hub/🌍 数字地球·曜冥主控台 v2 0/🏗️ AGE OS 后端架构设计 · 客户端优先 + 双服务器串联 + API中转计费（2026-0/🔧 Notion端Agent配置需求文档 · 致铸渊（AG-ZY-01） ba97961ddec8406a8be089de99758767.md
Guanghu Domestic Migration a27e87cb99 chore: import sanitized domestic snapshot for REPO-007 
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc

[SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
2026-07-17 15:59:55 +08:00

18 KiB
Raw Permalink Blame History

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

一、总体目标

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

  1. 能读写自研数据库（MySQL/PostgreSQL） — 把 Notion 里的大脑结构迁移过去，建立自己的认知索引
  2. 能读写 COS 双桶 — 存取大体量内容（页面原文、聊天记录、附件）
  3. 能调用工具在数据库里自主建设 — 不只是读写数据，还能建路径、拉关联、做分类、扫描结构
  4. 能跑定时任务 — 7×24 自动巡检、整理、同步
  5. 能通过网站统一入口被调用 — 用户在 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 — 创建大脑节点

{
  "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 — 更新节点

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

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

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

queryNodes — 查询/搜索节点

{
  "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拉取完整内容）

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

3.2 关系操作工具

linkNodes — 建立节点关联

{
  "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 — 删除关联

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

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

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

3.3 路径/结构工具

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

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

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

scanStructure — 扫描大脑结构健康度

{
  "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 — 自动分类/打标签

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

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

cosRead — 从 COS 读取内容

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

cosDelete — 删除 COS 内容

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

cosList — 列出某路径下的文件

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

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

{
  "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. 用户个人数据库前端上线