Skip to content

feat(hitl) PostgreSQL 持久化 pending store + structured_form 生命周期 - #3026

Closed
labspc wants to merge 3 commits into
TencentCloud:mainfrom
labspc:main
Closed

labspc wants to merge 3 commits into
TencentCloud:mainfrom
labspc:main

Conversation

@labspc

@labspc labspc commented Nov 18, 2026

Copy link
Copy Markdown

仓库:TencentCloud/Octop
分支:labspc:Octop feat/hitl-postgres-store → main
Base:octop v1.0.3b5(merge-base cd17e8d3 即 v1.0.3b5 本身,上游对涉及文件无额外提交,可干净 rebase 无冲突)
关联:octop-harness feat/interaction-lifecycle(request_structured_form 工具,协议 octop.structured_form.v1 两端对齐)

⚠️ 本分支内含三份 PR 描述文档,对应三个逻辑子集,建议合入顺序:先功能(表单协议 → 生命周期),后基础设施(PG store)。

What

  1. structured_form 网关侧协议(structured_form.py 新增 358 行):request_structured_form 的请求/响应双向校验、四类字段(integer/string/boolean/enum)的逐字段级错误定位
  2. 表单生命周期补全:timeout_seconds 超时、提交幂等(consumed_submission_ids)、主动取消(cancel_structured_form)
  3. HITL pending 记录 PostgreSQL 持久化:HitlPendingPostgresStore(pg_store.py 新增 604 行)+ 迁移 026(双方言 DDL)+ 运行时工厂 + 冒烟脚本

变更总量:16 个文件,+2,358 行,-5 行(相对于 merge-base cd17e8d3)

Why

  • HITL pending 记录原先只存内存:网关重启即丢失所有『等待用户审批/响应』状态;多实例部署下各实例状态互不可见
  • structured_form 协议缺少生命周期:无超时(表单挂起永久占坑)、无幂等(重复提交无法去重)、无主动取消入口
  • 顺带修复一个安全漏洞:原 if not allowed: continue 逻辑会放行未声明的中断类型,改为 if allowed and kind not in allowed 正确拦截

How

PG store 与工厂

  • pg_store.py:HitlPendingPostgresStore,19 个方法与内存版 HitlPendingStore 签名完全一致(直接替换实现);psycopg v3 + dict_row + ConnectionPool(min=1, max=4)
  • 迁移 026 双方言 DDL(.sql SQLite / .pg.sql PG):hitl_pending_records 表 18 列 + 9 索引(含 (form_context->>'form_id') 部分索引);沿用 021–025 双方言约定,migrate.py sorted(iterdir()) 自动发现,无需改注册表
  • factory.py build_pending_store():PG 控制面且 026 已应用 → PG store;探测方式 psycopg.connect(conninfo, connect_timeout=5) 执行 SELECT 1 FROM hitl_pending_records LIMIT 1
  • 失败降级而非抛错:无 config.json 且无 OCTOP_DATABASE_* → 内存版;非 PG 控制面 → 内存版;PG 不可达/缺表 → warning + 回落内存版(HITL 记录是会话级状态,启动失败的代价远大于用内存版)
  • __init__.py PEP 562 __getattr__ 惰性导出 PG store:pg_store.py 模块级导入 psycopg/psycopg_pool,惰性解析避免无 PG 驱动的纯 SQLite 安装导入失败

表单生命周期

  • HitlPendingRecord 新增 form_context(form_id/schema_version/timeout_seconds/context)与 consumed_submission_ids: set[str]
  • coordinator.register_from_request:注册时将 form_context 传入 store.register() 同一 INSERT 落库(修复『只给返回对象赋值、持久化不落库』,否则 cancel_pending_by_form_id 无法匹配)
  • decision_rejection_reason 新增校验链:请求校验 → timeout 过期 → 已消费表单禁 cancel → respond 响应校验 → 重复 submission_id 幂等拒绝
  • 新方法:mark_form_consumed(幂等,重复返回 False,仅 pending 态有效)、cancel_pending_by_form_id(仅过期未消费表单,PG 版按 form_id+agent_id(+user_id) 批量置 expired)
  • append_ask_answer 使用 FOR UPDATE 行锁

网关侧协议校验(structured_form.py)

  • 常量:STRUCTURED_FORM_PROTOCOL = "octop.structured_form.v1"、SCHEMA_VERSION = 1、MAX_STRUCTURED_FORM_BYTES = 32768、MAX_STRUCTURED_FORM_FIELDS = 64
  • validate_structured_form_request:MVP 仅 integer 字段;timeout ∈ [30,3600];required 不可同时 nullable;step 必须为 1;context ≤16 键
  • validate_structured_form_response:校验 respond JSON 的 protocol/version/form_id/submission_id/values,逐字段校验 required/nullable/int 类型/min-max 范围

Test

测试平台:本地 + PostgreSQL 实库(连接串经环境变量 OCTOP_TEST_DSN 传入;依赖 psycopg[binary]>=3.2、psycopg_pool>=3.2)

测试项 结果
PG 冒烟 scripts/smoke_hitl_pg_store.py(13 项,需先应用迁移 026) 13/13 通过,连续两次
工厂三场景实测(无配置→内存 / SQLite→内存 / PG 可达→PG store) 通过
回归 tests/unit/gateway 599 passed
HITL 专项 84 passed
迁移测试 46 passed
structured_form 协议单测 tests/unit/gateway/test_structured_form.py 63 passed(四类字段校验 + 字段级错误定位)
ruff 全过(3 个模块因缺 PIL/fastapi 无法收集,与本改动无关)
新增 test_hitl_form_context_registration.py(4 测试:form_context 注册落库 / 普通审批传 None / memory store 兼容 / slot 复用刷新) 通过

Limitations

  • 未含端到端集成测试(需完整 Octop 运行时 + LLM 后端),建议后续补
  • PG 版 _gc() 无定时任务:过期记录按 created_at 在读写路径触发清理;多实例下各实例各自触发,非集中调度

Dependencies

  • 上游依赖 PR3 feat/db-migrate-to-pg:PG store 需要 PG 控制面先行就位;迁移 026 双方言 DDL 依赖 migrate.py 的自动发现机制(sorted(iterdir())),该机制随 PR3 的 db.py 命令组一同引入

Related

  • octop-harness feat/interaction-lifecycle:Agent 侧 request_structured_form 工具(本 PR 提供其网关侧校验与持久化)
  • Octop feat/db-migrate-to-pg:SQLite → PG 迁移工具(同属控制面 PG 化方向)

labspc and others added 3 commits November 12, 2026 11:07
- Add gateway-side structured_form.py with request/response validation
- Tighten decision_rejection_reason: skip only when allowed decisions
  are explicitly configured and the kind is not in the allowlist
- Add structured form validation branch in decision_rejection_reason

Based on upstream v1.0.3b5
feat(hitl): add structured form request/response validation
Copilot AI balanced review requested due to automatic review settings November 18, 2026 06:59
@labspc labspc closed this Nov 18, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Structured-form handling allows approve/edit decisions and session auto-approval to bypass required form values, potentially resuming execution without a valid submission.

3 open issues
What changed in this PR

本次变更为 Octop 的人工审批(HITL)网关增加结构化表单协议校验,在恢复 Agent 前检查表单请求与用户响应。实际提交范围为协议校验子集。

Changes:

  • 新增 integer 表单校验,覆盖协议版本、大小限制、字段约束及响应值。
  • 在决策校验流程中接入 structured_form 校验,避免因缺少允许列表而跳过该分支。
  • 添加协议说明、调用示例、MVP 限制和验证记录。

本次核对了代码及相关调用路径,未运行测试。

File Description
src/​octop/​infra/​gateway/​hitl/​structured_form.py 定义协议常量及请求、响应校验函数。
src/​octop/​infra/​gateway/​hitl/​coordinator.py 将结构化表单校验接入 HITL 决策流程。
PULL_REQUEST_BODY.md 记录协议设计、使用示例与验证说明。

Review effort: Balanced

request_error = validate_structured_form_request(action.get("args"))
if request_error:
return request_error
if kind == "respond":
Comment on lines +258 to +260
request_error = validate_structured_form_request(action.get("args"))
if request_error:
return request_error
def validate_structured_form_request(args: Any) -> str | None:
"""Return a user-facing error when a form request is outside the MVP contract."""
if not isinstance(args, dict):
return "structured form args must be an object"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants