协作协议执行引擎 · 产品定义说明书

> 版本: v0.1 · 重写

> 状态: 草稿 · 基于 Phase 2 原型验证结论（2026-07-22）

> 从属于：HEAD.md（全工程组最高定义）。矛盾时以 HEAD.md 原则为准。

> 施工前先查：生态对齐·基础设施发现记录——确认无现成标准解法。

执行基元（全引擎唯一母循环）


1. 看规则 — 读取协议定义文件，确认本次执行的节点、路由、条件、约束
2. 按规则定义的地址取数据 — 从规则指定的 slot 路径读取输入数据
3. 按规则定义的方法运行 — 用规则指定的计算方法/流程处理数据
4. 把结果按规则送回去 — 写入规则指定的输出 slot 路径，格式与 schema 一致



> 每一步只做规则定义的事。规则没说做的，不做。规则没定义的路径，不走。数据在规则定义的地址之间流转——不另起炉灶。
>
> 这个循环不假设底层是 Tick 轮询还是 watchdog 事件监听。它只定义"执行一次该做什么"。怎么触发是基础设施层的事，不是引擎的事。



一、产品定位


1.1 这是什么


一个本地运行的、基于文件系统状态的事件驱动执行引擎。

它读取预先定义好的节点链和路由规则，监听指定目录下的文件变化（通过 watchdog——不做轮询，轮询已被验证不可靠），当检测到某些文件满足特定条件时，自动触发对应的执行动作，并将结果写入指定位置。

1.2 它解决什么问题

当前系统由多个.md 工作流、JSON schema、自动化计划和手动操作组成。信息在节点之间传递依赖人工触发或 cron 轮询。



本引擎让节点之间的通信自动化——不是通过「人手动把结果粘到下一个对话框」，而是通过文件状态变化自动触发路由。

已验证的问题（2026-07-22）：
sleep 接力在自动化计划环境中不可靠——引擎不做轮询
部署链路不完整（B 同步缺失、sitemap 遗漏）——引擎的 deploy 节点已包含强制完整性检查
节点执行后无身份校验——紧追 L2 已嵌入路由检查器

1.3 它不做什么


不提供 Web 界面（第一版）

不处理并发冲突（假设同一时刻只有一个节点在写）
不处理跨机通信（所有路径都在本地）
不提供自动错误修复（只记录错误，按规则升级）

1.4 它不自己造的东西（生态对齐）


以下能力已由生态领主提供了成熟的标准解法，引擎不重复实现：

| 能力 | 领主 | 我们的用法 |
|------|------|------|

| HTTP 请求重试 | urllib3.Retry（Python 标准生态） | Retry(total=2, backoff_factor=5)——不是自己写 R/W 循环 |

| 日志轮替 | logging.RotatingFileHandler | 替换手动 cat >> |

| 凭据管理 | python-dotenv | .env 文件存储 SSH 密钥路径、服务器 IP |


| 文件事件监听 | watchdog | 跨平台，成熟稳定 |
| 配置校验 | jsonschema | 启动时自动验证 JSON 格式 |
| Agent 间通讯 | 巴别塔协议（MIT 开源） | slot 输出双写为巴别塔兼容 JSONL |

| 中文区 pip 加速 | 清华镜像 | pip install -i https://pypi.tuna.tsinghua.edu.cn/simple |

> 详见：生态对齐·基础设施发现记录.md





二、核心架构 · 五层结构


┌─────────────────────────────────────────────────────────────┐
│ Layer 5 · 仲裁层                                           │
│ 异常之异常 → 需要人介入时，生成 Alert 对象，等待决策          │
└─────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────┐
│ Layer 4 · 异常层                                           │
│ 执行方法无法处理的错误 → 按 error_type 分类 → handling 三态  │
└─────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────┐
│ Layer 3 · 执行层                                           │
│ 具体操作步骤、R/W 重试参数、DoD 验收、紧追安全校验           │
└─────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────┐
│ Layer 2 · 路径层                                           │
│ slot 文件路径定义、验证路径可达、原子写入（tmp→rename）      │
└─────────────────────────────────────────────────────────────┘
                              ↑
┌─────────────────────────────────────────────────────────────┐
│ Layer 1 · 依赖层                                           │
│ 启动时检查依赖：Python 版本、watchdog、jsonschema、.env      │
└─────────────────────────────────────────────────────────────┘



各层职责


| 层 | 职责 | 异常时的行为 |
|------|------|------|
| L1 依赖层 | 启动时检查所有依赖是否可用（含 .env 加载） | 缺失 → 立即报错，不启动 |
| L2 路径层 | 验证所有 slot 路径是否存在/可写。原子写入校验（紧追-L1） | 不可写 → 升级到 L4 异常层 |
| L3 执行层 | 按节点 schema 执行操作。pre/post 自检卡。R/W 重试。紧追-L2 身份校验 | 失败 → 按 error_type.handling 处理 |
| L4 异常层 | 匹配 error_type 枚举 → handling 三态处理 → 重试用尽则升级 | 未知类型 → 升级到 L5 仲裁层 |

| L5 仲裁层 | 生成 Alert 对象写入 alerts/ 目录。暂停下游。等待人决策 | 人决策：继续/终止/修改规则 |





三、数据模型


3.1 节点（Node）

`json


{
  "node_id": "exec-scan",
  "layer": 1,
  "role": "市场扫描·7维度信号采集",
  "description": "读取扫描文件，提取待处理条目",
  "input_slot": null,
  "output_slot": {
    "slot_id": "exec-scan",
    "path": "D:/LobsterPlayPool/.workbuddy/memory/slots/exec-scan_output.json",
    "babel_path": "D:/LobsterPlayPool/.workbuddy/memory/slots/exec-scan_babel.jsonl"
  },
  "capabilities": ["WebSearch", "Read", "Write"],
  "forbidden_capabilities": ["Edit", "scp"],
  "timeout_seconds": 7200,
  "retry": {
    "max_retries": 1,
    "retry_interval_seconds": 900
  },
  "check_rules": {
    "pre_execution": [
      "Read scan-velocity.md → 确定今日需扫描的维度",
      "确认 WebSearch 工具可用"
    ],
    "post_execution": [
      "输出槽位文件 tmp→rename 原子写入",
      "确认 status=completed 且 data.scan_file 路径存在"
    ]
  }
}

R/W 分离说明：max_retries（R）和 retry_interval_seconds（W）是两个独立参数，替代原 retry_cooldown_minutes。不同节点可以有不同的 R/W 配置。



3.2 路由（Route）

`json


{
  "route_id": "route-scan-to-dedup",
  "from_node": "exec-scan",
  "to_node": "exec-dedup",
  "condition": {
    "field": "status",
    "operator": "equals",
    "value": "completed",
    "additional_checks": ["data.scan_file 路径存在且文件可读"]
  },
  "priority": "P1",
  "description": "扫描完成后自动触发去重"
}

支持的 condition 操作符：equals、in、length_greater_than、length_equals。



3.3 错误类型（Error Type）与 R/W 策略

`json


{
  "error_type": "input_missing",
  "description": "输入槽位文件不存在",
  "handling": "retry",
  "max_retries": 3,
  "retry_interval_seconds": 60,
  "escalate_after": "max_retries_exceeded"
}



handling 三态：

| handling | 含义 | 适用场景 |
|------|------|------|

| retry | 等待 retry_interval 后重试，最多 max_retries 次 | 文件写入中、服务器重启中 |

| skip | 跳过此节点，记录日志，不阻断下游 | 条件不满足时跳过（非错误） |

| fail | 立即标记失败，升级到异常层 | 安全类错误——不重试 |

完整 error_type 枚举（10 种）见phase2-node-chain.json。

中文区特殊类型：external_unreachable——标记为 skip，不重试。原因是我们在的地方，某些外部 API 本身就可能不通。引擎不应把网络约束当成可修复的错误。





四、工作流程


4.1 通用执行循环（母框架）


执行基元（见本文档头部）适用所有流程——正常、异常、仲裁都在它的框架内运行。

4.2 正常流程


1. 引擎启动 → 读取 phase2-node-chain.json + 路由表 + .env
2. watchdog 监听 slots/ 目录下所有 _output.json 文件变化
3. 检测到文件变化 → 紧追-L1 原子写入校验（.tmp？.json？）
4. 读取文件 → 紧追-L2 节点身份校验（capabilities 与 schema 一致？）
5. 检查 status + condition + additional_checks
6. 匹配 → 写入下游节点的 input 槽位（status: pending）
7. 记录日志 → 继续监听



4.3 异常流程


1. 执行过程中发生错误
2. 捕获错误 → 匹配 error_type 枚举
3. handling = retry  → R/W 重试 → 用尽升级
   handling = skip   → 跳过·记录日志
   handling = fail   → 立即升级到异常层
4. 异常层生成 Alert 对象 → 写入 alerts/ 目录
5. L5 仲裁层接收 → 等待人决策



4.4 部署节点特殊流程


deploy 节点（exec-deploy）是今天发现的关键缺失环节，其完整性检查已强制化：


1. scp 每个新建文件到 C 端 → curl 验证 200
2. cp 到 B 镜像 → md5 校验
3. Edit sitemap.xml → scp C + cp B
4. 紧追-L3 diff：curl C 端 3 个特征点 → 与 Dev 端对比 → 不一致则 ERROR





五、技术选型


| 组件 | 选择 | 我们做什么 | 我们不用做什么 |
|------|------|------|------|
| 运行环境 | Python 3.10+ | 写执行逻辑 | — |
| 文件监听 | watchdog | 写回调函数 | 不写轮询循环——轮询已验证不可靠 |

| 日志 | logging.RotatingFileHandler | 配置格式 + 路径 | 不手写 cat >>——标准库自带轮替 |

| 凭据 | python-dotenv | .env 文件 | 不硬编码密码/密钥在 JSON |


| 配置校验 | jsonschema | 写 schema 文件 | — |
| 进程并发 | asyncio | 多链并行用协程 | — |
| 包管理 | pip + requirements.txt | 锁定版本号 | — |

| pip 源 | 清华镜像 | 安装命令默认带 -i | — |



依赖清单：


watchdog>=3.0.0
jsonschema>=4.0.0
python-dotenv>=1.0.0
requests>=2.31.0





六、目录结构


协作协议执行引擎/
├── .env                       # 凭据配置（不入版本控制）
├── requirements.txt           # 依赖清单
├── config/
│   ├── node_chain.json        # 节点+路由定义（从 phase2-node-chain.json 迁移）
│   └── schema.json            # JSON Schema 校验规则
├── src/
│   ├── main.py                # 入口·启动监听器
│   ├── listener.py            # watchdog 回调
│   ├── router.py              # 路由匹配 + 紧追校验
│   ├── executor.py            # 执行器
│   ├── exception_handler.py   # error_type 匹配 + handling 三态
│   └── arbitrator.py          # Alert 生成 + 人介入等待
├── logs/
│   └── engine.log             # RotatingFileHandler（5MB×5）
└── alerts/
    └── alert-{timestamp}.json # 结构化的待处理警报

七、版本规划

| 版本 | 目标 | 范围 | 前置依赖 |

|------|------|------|------|

| v0.2 | R/W 重试 + handling 三态 | 集成 error_type 枚举的 retry/skip/fail，HTTP 层用 urllib3.Retry | v0.1 |

| v0.3 | 仲裁层 | Alert 对象 + alerts/ 目录 + 人介入等待 | v0.2 |

| v0.4 | 多链并行 | 内容引擎 + 游戏事件路由同时运行 | v0.3 |

| v0.5 | 生产就绪 | 完整日志、性能监控、优雅关闭 | v0.4 |

> 当前 Phase 2 原型（Tick 轮询）的 route-checker-prototype.py 将在 v0.1 中被 watchdog 替代。原型验证了路由逻辑正确——现在换掉触发方式。

八、约束条件

1. 不猜测——遇到未定义的情况，不自行填补，升级到仲裁层

2. 不跳过自检——每个节点执行前/后必须通过 pre/post 检查卡（开发规范第六条）

3. 不造已有的轮子——任何外部依赖先查生态对齐记录

4. 可观测——所有操作写入 RotatingFileHandler，关键事件生成结构化 Alert

5. 可停止——任意时刻可用 SIGINT 优雅停止引擎

6. 可崩不怕——引擎无状态。数据在 slot 文件中，引擎崩了重启即可继续

九、修订记录

| 时间 | 版本 | 修改内容 |

|------|:---:|------|

| 2026-07-22 | v0.1 初版 | 创建产品定义，基于五层架构 |

| 2026-07-22 | v0.1 重写 | 整合 Phase 2 验证结论（sleep 不可靠→watchdog）、R/W 拆分（robocopy 模式）、中文区 external_unreachable、生态对齐（不造轮子清单）、紧追 L1/L2/L3 嵌入、deploy 节点强制化。技术选型增补 urllib3.Retry + RotatingFileHandler + .env + 清华镜像。 |