Repository navigation
Conversation
- 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
There was a problem hiding this comment.
🟡 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
structured_form 可绕过必填值校验并触发自动审批 · New 非法表单请求无法通过拒绝操作退出暂停 · New 请求与响应校验错误未按用户语言本地化 · New
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" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


What
structured_form.py新增 358 行):request_structured_form的请求/响应双向校验、四类字段(integer/string/boolean/enum)的逐字段级错误定位timeout_seconds超时、提交幂等(consumed_submission_ids)、主动取消(cancel_structured_form)HitlPendingPostgresStore(pg_store.py 新增 604 行)+ 迁移 026(双方言 DDL)+ 运行时工厂 + 冒烟脚本Why
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).sqlSQLite /.pg.sqlPG):hitl_pending_records表 18 列 + 9 索引(含(form_context->>'form_id')部分索引);沿用 021–025 双方言约定,migrate.pysorted(iterdir())自动发现,无需改注册表factory.pybuild_pending_store():PG 控制面且 026 已应用 → PG store;探测方式psycopg.connect(conninfo, connect_timeout=5)执行SELECT 1 FROM hitl_pending_records LIMIT 1OCTOP_DATABASE_*→ 内存版;非 PG 控制面 → 内存版;PG 不可达/缺表 → warning + 回落内存版(HITL 记录是会话级状态,启动失败的代价远大于用内存版)__init__.pyPEP 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 = 64validate_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)scripts/smoke_hitl_pg_store.py(13 项,需先应用迁移 026)tests/unit/gatewaytests/unit/gateway/test_structured_form.pytest_hitl_form_context_registration.py(4 测试:form_context 注册落库 / 普通审批传 None / memory store 兼容 / slot 复用刷新)Limitations
_gc()无定时任务:过期记录按created_at在读写路径触发清理;多实例下各实例各自触发,非集中调度Dependencies
feat/db-migrate-to-pg:PG store 需要 PG 控制面先行就位;迁移 026 双方言 DDL 依赖migrate.py的自动发现机制(sorted(iterdir())),该机制随 PR3 的db.py命令组一同引入Related
feat/interaction-lifecycle:Agent 侧request_structured_form工具(本 PR 提供其网关侧校验与持久化)feat/db-migrate-to-pg:SQLite → PG 迁移工具(同属控制面 PG 化方向)