"""运行时审批队列(细粒度审批，P1 第 4 项)。 选型：只打通 elicitation 一类，其他审批类全部记为遗留。 选 elicitation 的理由： - 它是 host.py 里唯一已经特判的 server_request 类，未来 hook 的落点就是 _answer_server_request 的 elicitation 分支，加法 可接，不用先修一条错的通用回包。 - 决定语义最干净：二值，批准 = accept(content 为空对象， 与今天 approval=auto 时的行为完全一致)，拒绝 = decline， 不需要像 permissions 那样现拼权限 profile，也不需要像 file_change 的 cancel 那样附带“中断整轮”的副作用。 - 触发方是 MCP 服务器向用户要表单输入，正是“第三方工具向 用户要东西”的场景，用户在控制台点允许或拒绝最符合直觉。 关键语义(先定清楚，再写代码)： - 待审批期间原流程挂起等待，不先拒绝后补。队列里的 pending 项本身不做任何放行或拦截动作，它只是等一个决定。 - 等待有超时：默认 3600 秒，可在创建时改(服务端入口只接受 60 到 86400 秒)。超时默认是拒绝，绝不是放行：过期扫荡把 pending 置为 expired，同时把 effective decision 记为 denied， decided_by 记为 system-timeout，回执里看得见。 - 批准放行、拒绝拦截：决定一旦写入就是终态，再次决定返回 already_decided，原决定绝不被覆盖。回执字段：decided_by、 decided_at、decision，批准与拒绝、过期都留痕。 - 决定是 CAS：只有 pending 行能被改状态，并发下两个决定只 有一个能赢，输的那个拿到 already_decided 而不是假成功。 诚实边界(本片做到哪、没做到哪)： - 本片交付的是队列服务本身：建表迁移、创建、查询、批准、 拒绝、过期扫荡、回执、服务端端点、控制台 UI、单测。 - 本片没有把实时 elicitation 接到队列上，host.py 完全没动。 原因不是协议不让挂起：JSON-RPC 请求本来就可以晚回包， 挂起在协议上是成立的。真正缺的是通道：host.py 跑在 worker 拉起的子进程里，手头没有云 DB 连接，也没有到控制面的 带权请求通道(worker.py 本片禁动，没法给它递 DB 路径或 token)。在没有通道的情况下往 _answer_server_request 里 加“等决定”只会把回合无限挂死，所以不做假拦截。 - 在通道落地之前，实时 elicitation 的行为与今天完全一致： approval=auto 时 accept 空 content，其他一律 decline。 队列里的决定目前是记录加事后审计口径，供通道落地后的 hook 消费，绝不要对外宣称“实时请求已被事前拦截”。 - 通道落地时 host 侧要做的事只有两件，都已在本模块留好 映射函数：elicitation 到达时先建 pending 项再挂起等决定， 决定到了按 elicitation_response 回包；超时按 expired 的 denied 处理。通道本身(worker 递 DB 路径还是控制面 HTTP 带权轮询，生产是 Postgres 所以 DB 直连只够 SQLite 开发 环境用)是合流阶段的单独设计，不在本片里猜一个。 遗留的审批类(明确不塞进本片)： - item/commandExecution/requestApproval：命令审批。现 host 通用回包写的是 approve/deny，但新协议的决定词表是 accept/decline/acceptForSession 等，通用回包本身就是错的， 要先修词表再接队列；kind 里已预留 command，映射函数 command_response 已按新协议写好，但不接实时流。 - item/fileChange/requestApproval：文件改动审批。决定里有 cancel(拒绝并立即中断整轮)，不是纯二值，接队列要先定 cancel 的轮次语义，暂不接。 - item/permissions/requestApproval：权限审批。回包不是二值， 而是一份 GrantedPermissionProfile，要现拼 profile，暂不接。 - item/tool/requestUserInput：这根本不是审批，是向用户要 输入内容(问题列表)，blocking 与否另有语义，应另起输入 队列，暂不接。 - item/tool/call 与 account/chatgptAuthTokens/refresh：前者是 动态工具执行，后者是凭证刷新，都不是用户审批，排除。 本模块只依赖标准库，不 import cloud 其他模块，避免循环 import；服务端与未来 worker/hook 共用。占位符用 ?，建表与 列补齐写法与 peer_messages 同款(db 适配层负责翻译)。 """ import json import time import uuid KINDS = ("elicitation", "command", "file_change", "permissions", "user_input") DECISIONS = ("approved", "denied") DEFAULT_TIMEOUT_SECONDS = 3600 MAX_SUMMARY_CHARS = 2000 MAX_DETAIL_CHARS = 20000 def row_get(row, name): """行取值容错：sqlite3.Row 缺列报 IndexError、dict 缺键报 KeyError、空行报 TypeError，一律回 None(与 peer_messages 的同名函数同款，模块独立所以这里自带一份)。""" try: return row[name] except (KeyError, IndexError, TypeError): return None def ensure_approvals_table(conn): """幂等建审批队列表。调用方负责 commit(服务端入口在写 操作后统一 commit；本函数自己不 commit，避免半截事务)。""" conn.execute( "CREATE TABLE IF NOT EXISTS task_approvals(" "id TEXT PRIMARY KEY, " "task_id TEXT, " "project_id TEXT, " "kind TEXT, " "summary TEXT, " "detail TEXT, " "status TEXT, " "requested_by TEXT, " "decided_by TEXT, " "decided_at DOUBLE PRECISION, " "decision TEXT, " "created_at DOUBLE PRECISION, " "updated_at DOUBLE PRECISION, " "expires_at DOUBLE PRECISION)" ) conn.execute( "CREATE INDEX IF NOT EXISTS idx_approvals_task" " ON task_approvals(task_id, status)") conn.execute( "CREATE INDEX IF NOT EXISTS idx_approvals_project" " ON task_approvals(project_id, created_at)") def _detail_to_str(detail): if detail is None: return None if isinstance(detail, str): text = detail else: try: text = json.dumps(detail, ensure_ascii=False) except (TypeError, ValueError): text = str(detail) if len(text) > MAX_DETAIL_CHARS: raise ValueError("detail too long") return text def _detail_from_str(text): if text is None: return None try: return json.loads(text) except (TypeError, ValueError): return text def approval_to_dict(row): """行转 dict：回执字段原样带出，detail 尽量还原成对象。""" if row is None: return None return { "id": row_get(row, "id"), "task_id": row_get(row, "task_id"), "project_id": row_get(row, "project_id"), "kind": row_get(row, "kind"), "summary": row_get(row, "summary"), "detail": _detail_from_str(row_get(row, "detail")), "status": row_get(row, "status"), "requested_by": row_get(row, "requested_by"), "decided_by": row_get(row, "decided_by"), "decided_at": row_get(row, "decided_at"), "decision": row_get(row, "decision"), "created_at": row_get(row, "created_at"), "updated_at": row_get(row, "updated_at"), "expires_at": row_get(row, "expires_at"), } def create_approval(conn, task_id, project_id, kind="elicitation", summary="", detail=None, requested_by=None, timeout_seconds=DEFAULT_TIMEOUT_SECONDS, now=None): """创建一条待审批项，返回 dict。非法输入抛 ValueError， 调用方据此回 400；成功时 commit。 timeout_seconds：None 用默认值；0 表示不过期(只允许 模块级调用，服务端入口另有限制)；负数非法。""" if kind not in KINDS: raise ValueError("kind must be one of: " + ", ".join(KINDS)) if not isinstance(summary, str) or not summary.strip(): raise ValueError("summary required") summary = summary.strip() if len(summary) > MAX_SUMMARY_CHARS: raise ValueError("summary too long") if timeout_seconds is None: timeout_seconds = DEFAULT_TIMEOUT_SECONDS if not isinstance(timeout_seconds, (int, float)) \ or isinstance(timeout_seconds, bool) \ or timeout_seconds < 0: raise ValueError("timeout_seconds invalid") detail_str = _detail_to_str(detail) now = time.time() if now is None else now expires_at = None if timeout_seconds: expires_at = now + timeout_seconds item_id = uuid.uuid4().hex ensure_approvals_table(conn) conn.execute( "INSERT INTO task_approvals(id, task_id, project_id," " kind, summary, detail, status, requested_by," " decided_by, decided_at, decision," " created_at, updated_at, expires_at)" " VALUES(?, ?, ?, ?, ?, ?, 'pending', ?," " NULL, NULL, NULL, ?, ?, ?)", (item_id, task_id, project_id, kind, summary, detail_str, requested_by, now, now, expires_at), ) conn.commit() return approval_to_dict(conn.execute( "SELECT * FROM task_approvals WHERE id = ?", (item_id,)).fetchone()) def get_approval(conn, approval_id): """取一条，缺失回 None(不抛，让调用方定 404 还是 409)。""" ensure_approvals_table(conn) return approval_to_dict(conn.execute( "SELECT * FROM task_approvals WHERE id = ?", (approval_id,)).fetchone()) def list_approvals(conn, task_id=None, project_id=None, status=None): """列审批项：纯读，不扫荡过期(扫荡是写操作，调用方在 需要时先调 expire_overdue)。过滤全是可选的精确匹配。""" ensure_approvals_table(conn) query = "SELECT * FROM task_approvals WHERE 1 = 1" args = [] if task_id is not None: query += " AND task_id = ?" args.append(task_id) if project_id is not None: query += " AND project_id = ?" args.append(project_id) if status is not None: query += " AND status = ?" args.append(status) query += " ORDER BY created_at, id" rows = conn.execute(query, args).fetchall() return [approval_to_dict(r) for r in rows] def decide_approval(conn, approval_id, decision, decided_by): """写决定。返回 (status, item)：decided 表示本次写赢； already_decided 表示该项已有终态(批准、拒绝或过期)， 原决定绝不被覆盖；not_found 表示无此项。 决定是 CAS：UPDATE 只改 status='pending' 的行，rowcount 为 0 说明并发下已被别人先决定，调用方按 already_decided 处理，不要按成功回。成功与过期扫荡都 commit。""" if decision not in DECISIONS: raise ValueError("decision must be approved or denied") ensure_approvals_table(conn) item = get_approval(conn, approval_id) if item is None: return "not_found", None if item["status"] != "pending": return "already_decided", item now = time.time() cur = conn.execute( "UPDATE task_approvals SET status = ?, decision = ?," " decided_by = ?, decided_at = ?, updated_at = ?" " WHERE id = ? AND status = 'pending'", (decision, decision, decided_by, now, now, approval_id)) conn.commit() if cur.rowcount == 1: return "decided", get_approval(conn, approval_id) return "already_decided", get_approval(conn, approval_id) def expire_overdue(conn, now=None): """过期扫荡：把已到 expires_at 的 pending 项置为 expired， 同时把 effective decision 记为 denied(超时默认拒绝，绝不 放行)，decided_by 记为 system-timeout。返回过期条数。""" ensure_approvals_table(conn) now = time.time() if now is None else now cur = conn.execute( "UPDATE task_approvals SET status = 'expired'," " decision = 'denied', decided_by = 'system-timeout'," " decided_at = ?, updated_at = ?" " WHERE status = 'pending' AND expires_at IS NOT NULL" " AND expires_at <= ?", (now, now, now)) conn.commit() return cur.rowcount def elicitation_response(decision): """未来 host hook 的回包映射(本片未接实时流，只定映射)： 批准 = accept 空 content，与今天 approval=auto 的行为一致； 拒绝或过期 = decline。decision 取 approved/denied/expired 之外的任何值都按拒绝处理，绝不默认放行。""" if decision == "approved": return {"action": "accept", "content": {}} return {"action": "decline"} def command_response(decision): """未来命令审批 hook 的回包映射，按新协议词表写(accept / decline)，不是 host.py 现通用回包的 approve/deny——后者 与新协议不符，见模块 docstring 的遗留清单。非批准一律 decline，绝不默认放行。""" if decision == "approved": return {"decision": "accept"} return {"decision": "decline"}