s16 团队协议：Team Protocols - Harness Engineering - 后端

# 三行速读

团队有消息还不够，关键动作需要协议化。
request_id 让请求与响应可关联、可追踪、可审计。
这章把协作从 “能沟通” 提升到 “可治理”。

# 先修知识

已理解 s15 的队友与 inbox 模型。
知道状态机基本概念（pending/approved/rejected 等）。

# 读完后你应该能做到（可检验清单）

创建并完成一次带 request_id 的审批流程。
解释协议请求与普通消息的本质差别。
设计一个可验证的状态迁移规则。

# 本篇要解决什么

s15 有了团队消息流，但高风险动作（关机、审批）不能只靠普通消息。s16 要解决的是 “结构化协作协议”：请求、响应、状态必须能对上号。

核心目标：把关键协作动作做成 request-response 协议，而不是随意聊天。

# 用一个类比先理解

像公司审批单：

每张单有唯一编号；
谁提交、谁审批、何时审批都可查；
单据状态可追踪。

request_id 在这里就是审批单号。

# 为什么这一步必须现在做

没有协议层，团队规模一大就会出现 “谁同意了、同意了什么、现在状态是什么” 全靠猜。s16 用结构化协议把这件事做实。

# 关键代码怎么读

# 1) 请求存储层

1
2
3

REQUESTS_DIR = TEAM_DIR / "requests"
class RequestStore: ...
REQUEST_STORE = RequestStore(REQUESTS_DIR)

协议请求落盘后，协作就具备可审计性。

# 2) 协议处理器函数

1 2	def handle_shutdown_request(teammate: str) -> str: ... def handle_plan_review(request_id: str, approve: bool, feedback: str = "") -> str: ...

把业务动作封装为处理器，避免散落在消息分支中。

# 3) 状态查询接口

1 2	def _check_shutdown_status(request_id: str) -> str: ...

这一步非常适合前端 / 上层调用：随时确认协议进展。

# 4) 协议能力进入统一工具池

TOOLS = [
    ...,
    {"name": "protocol_shutdown_request", ...},
    {"name": "protocol_plan_review", ...},
]

协议不是外置系统，而是原生能力的一部分。

# 你可以怎么复现

创建一条 shutdown 请求。
使用 request_id 查询状态变化。
对同一 request 做 approve/reject，观察状态一致性。

# 常见误区

误区 1：关键动作走普通消息，不落 request_id。
误区 2：请求已创建但缺少状态更新规则。
误区 3：协议处理器中夹带过多隐式副作用。

# 一句话总结

s16 的价值是让团队协作从 “能沟通” 升级到 “可治理、可追踪、可审计”。

# 补充解读：协议层如何避免 “消息歧义”

# A. RequestStore 的角色

它把 “请求” 从普通消息中抽离出来，形成独立生命周期：创建、待处理、已批准 / 已拒绝、已关闭。

# B. `request_id` 的强约束价值

所有响应都必须带回同一个 request_id ，这样协议链路不会串线。

# C. shutdown 与 plan review 共用协议骨架

两种业务动作虽然不同，但共享 “请求 - 响应 - 状态查询” 骨架，说明协议层是可复用抽象。

# D. 为什么要有 `_check_shutdown_status`

这类查询接口让上层可以做 “轮询等待” 与可视化，而不是通过日志猜当前状态。

# 进阶练习

扩展一个 handoff_request 协议（任务移交）。
为协议请求增加 TTL 过期处理。
给协议状态变更增加审计事件写入。

# 再补一层：把协议做成 “可维护资产”

# A. 每种协议都应有最小字段规范

至少包含：

request_id
type
from
to
status
created_at
updated_at

字段稳定，后续才能无痛接监控和可视化。

# B. 响应必须引用原请求 ID

这是协议系统最不能妥协的一条规则。没有 ID 关联，所有审批流都会退化成文本猜谜。

# C. 状态迁移要可验证

建议显式定义允许迁移，例如：

pending -> approved/rejected -> closed

防止出现非法跳转（如 pending 直接 closed）。

# D. 协议日志建议单独存放

不要和普通聊天日志混在一起。分开存储可显著降低故障排查成本。

# 统一术语口径（本章）

Protocol Request ：带唯一 ID 的结构化协作请求。
Request Store ：协议请求状态的持久存储层。
Correlation ID ：请求与响应关联的标识符（request_id）。

# 章节衔接（从易到难）

本章解决 “协作可治理”。
下一章 s17 进入 “队友如何在规则内自治推进任务”。

Harness Engineering