企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• 交互助手
• 工具调用
• MCP 服务
• Agent 记忆
• RAG

本指南围绕 OpenSquilla 仓库中contracts/gateway/v4/goals目录下的 Goals 契约切片展开，系统讲解 v4 Gateway 面向持久化目标（durable goal）的goals.status、goals.set、goals.edit、goals.pause、goals.resume、goals.clear、goals.reattach与goals.capabilities等查询/命令方法的协议边界。读者将掌握这些方法的请求/响应帧结构、参数别名兼容规则、乐观并发与幂等语义、错误码矩阵，以及它们在后端 Python 网关与前端 WebUI 消费侧的实际落地方式，可直接用于跨语言客户端对接与契约代码生成。

一、契约切片定位：语言无关的查询/命令边界

该切片（契约总览）定义的是语言无关（language-neutral）的 v4 查询/命令边界，覆盖如下方法：

• 查询（query）：goals.status、goals.capabilities
• 命令（command）：goals.set、goals.edit、goals.pause、goals.resume、goals.clear、goals.reattach

切片的设计意图是：有意识地对既有 Gateway 处理器做一层薄封装——它不改变GoalService、任务执行、持久化或事件生产，仅提供统一的协议入口。从源码结构看，这一意图在 网关适配器 中得到印证：该模块为每个方法构造GatewayContractBinding，通过MethodRegistry/register_gateway_contract_method注册，绑定既有的 method descriptor、参数观察器与结果校验器，真正的目标业务逻辑仍在 GoalService 与 RPC 处理器 中保持权威。

切片同时明确了三个互操作约束：

1. 会话标识三别名并存：sessionKey/session_key/key均被接受；
2. 快照开放未知字段：Goal 快照保留未知字段（additionalProperties: true），使新旧 Gateway 可互操作；
3. 幂等与租约语义保留：goals.set保留既有 UUID-v4 幂等字段与错误码；goals.reattach保留连续性令牌/接管租约语义，并接受当前的 camelCase、snake_case 与遗留 key/epoch 别名。

二、Wire 元数据与代码生成链路

每个方法契约都是独立的 JSON Schema 文件（schema 目录），通过x-opensquilla-*扩展标注协议信息：

• x-opensquilla-wire：声明protocol: "opensquilla-websocket-json"、version: 4、compatibility: "exact-json-tree"，即请求/响应 JSON 树需精确匹配契约结构；
• x-opensquilla-codegen：声明代码生成工具链——Python 侧使用datamodel-code-generator（0.81.0，生成pydantic_v2.BaseModel），TypeScript 侧使用json-schema-to-typescript（16.0.0），运行时校验使用ajv（8.20.0，standalone-adapter-only模式）；
• x-opensquilla-method：声明方法名、种类（query/command）、访问 scope（operator.read/operator.write）、guestAllowed、幂等性与超时策略、能力声明、错误码列表。

仓库配套的生成脚本 generate_gateway_contracts.py 负责把上述 Schema 生成 Python wire 类型，生成产物落在 contracts/generated/v4（如goals_clear、goals_edit、goals_pause、goals_resume及其*_metadata模块），并由 gateway_contract_registry.py 汇总成GATEWAY_METHOD_CONTRACTS注册表供网关查询。契约验证工具链相关测试见 scripts/contracts/tests 与 契约测试。

三、统一帧结构：Request / Response / Error

所有 Goals 方法共享一致的帧封装（以 goals-status.schema.json 中的定义为准）：

RequestFrame（additionalProperties: false，必填type、id、method）：

{ "type": "req", "id": "request-abc-123", "method": "goals.status", "params": { ... } }

ResponseFrame为二选一（oneOf）：

• 成功：{ "type": "res", "id": "...", "ok": true, "payload": {...}, "error": null }
• 失败：{ "type": "res", "id": "...", "ok": false, "payload": null, "error": { "code": "...", "message": "...", "details": {...}, "retryable": null } }

RpcError必填code与message，可选details、retryable、accepted。retryable: true的错误（如UNAVAILABLE、GOAL_ACTIVE、STALE_GOAL）意味着客户端可安全重试。

四、查询方法：goals.status 与 goals.capabilities

goals.status：读取持久目标快照

goals.status是只读查询（idempotency: "read-only"，scopeoperator.read），用于读取持久目标的完整快照。

Params：仅需会话标识，三别名（sessionKey/session_key/key）任选其一，且additionalProperties: true允许携带额外字段。

Result（必填sessionKey、sessionId、epoch、goal）：

{ "sessionKey": "session-...", "sessionId": "session-...", "epoch": 3, "goal": { "goalId": "goal-...", "objective": "实现 xx 功能", "status": "active", "stateRevision": 5, "objectiveRevision": 2, "progressRevision": 4, "continuationSeq": 7, "activeTaskId": "task-...", "executionState": "running", "createdAt": 1700000000000, "updatedAt": 1700000100000, "finishedAt": null, "usageCoverage": "complete" } }

GoalSnapshot 关键字段（additionalProperties: true，仅status必填）：

goals.capabilities：能力发现

goals.capabilities同样为只读查询，用于发现目标能力。其 Result 必填 5 个字段（见 goals-capabilities.schema.json）：

• supported：boolean，是否支持持久目标；
• executionEnabled：boolean，目标执行是否启用；
• maxTurns：integer ≥ 0，最大轮次上限；
• runtimeBudgetSeconds：integer ≥ 0，运行时预算（秒）；
• methods：string 数组，可用方法名列表（如["goals.status","goals.set",...]）。

该方法的错误码集合最小（INVALID_REQUEST、UNAUTHORIZED、UNAVAILABLE、INTERNAL_ERROR），客户端可在会话建立后首先调用它来决定 UI 能力展示。

五、命令方法：set / edit / pause / resume / clear

goals.set：写入持久目标（幂等）

goals.set是幂等命令（idempotency: "idempotent"，scopeoperator.write）。其 Params 必填objective、clientRequestId、clientMessageId，其中两个 client 标识均为UUID v4 格式（^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$），并同时支持 camelCase 与 snake_case 变体（client_request_id、client_message_id）；message字段（minLength 1）为可选指令文本，sourceKind/source_kind可标识来源（如 web/cli）。它保留遗留 Params 形态（session_key+message+ 两个 client id）。

{ "type": "req", "id": "req-1", "method": "goals.set", "params": { "sessionKey": "session-...", "objective": "交付 v4 网关契约文档", "message": "完成后向团队同步", "clientRequestId": "550e8400-e29b-41d4-a716-446655440000", "clientMessageId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "sourceKind": "cli" } }

Result 含accepted/replayed（幂等重放标记）、status、taskId/task_id与goal快照，其中accepted与replayed为可空 boolean。

错误码（见 goals-set.schema.json）：除通用码外，还有INVALID_GOAL_COMMAND、UNSUPPORTED_GOAL_OPTIONS（不可重试）与GOAL_ACTIVE（可重试，表示当前已有活动目标）。

goals.edit / pause / resume / clear：乐观并发突变

这四个命令统一采用expected-goal 乐观并发模型，Params 必填三件套：

• expectedGoalId/expected_goal_id：期望的目标 ID；
• expectedStateRevision/expected_state_revision：integer ≥ 1，期望的stateRevision（从 1 开始，区别于快照中的 minimum 0）；
• clientRequestId/client_request_id：请求标识（此处未限定 UUID 格式，goals.edit中为普通 string）。

三者均定义STALE_GOAL（可重试）错误码，表示expectedStateRevision与服务端当前修订不一致，客户端应重新拉取goals.status后再提交。各方法特有语义：

其中goals.edit的expectedStateRevision为 integer ≥ 1；goals.pause/resume/clear的 Result 为开放对象（additionalProperties: true，无必填字段），成功即ok: true。

六、goals.reattach：连续性令牌与接管租约

goals.reattach是最复杂的命令（idempotency: "non-idempotent"，scopeoperator.write），用于重新挂接已分离（detached）的持久目标执行租约，其契约定义见 goals-reattach.schema.json。

Params 必填项（allOf 组合约束）：

1. 会话标识三选一：sessionKey/session_key/key（minLength 1）；
2. 会话 ID 二选一：sessionId/session_id；
3. 期望目标 ID 二选一：expectedGoalId/expected_goal_id；
4. 会话代数三选一：epoch/sessionEpoch/session_epoch（integer ≥ 0）；
5. 条件约束：若takeover为true则无需令牌；否则必须提供continuityToken或continuity_token（string，minLength 1、maxLength 256）。

{ "type": "req", "id": "req-2", "method": "goals.reattach", "params": { "sessionKey": "session-...", "sessionId": "session-...", "epoch": 4, "expectedGoalId": "goal-...", "continuityToken": "ct-9f8e...", "takeover": false } }

语义要点：

• continuityToken（≤256 字符）是执行租约的连续性凭证，携带它即可在会话/客户端切换后安全接回执行流；
• takeover: true表示接管模式，跳过令牌校验，用于接管遗留执行（服务端会做生成/租约校验兜底）；
• source（object，开放结构）与sourceKind/source_kind用于记录挂接来源。

Result（必填accepted（const true）、epoch、goal，且需满足 sessionKey/sessionId/continuityToken 三组任选其一的组合约束）：成功响应返回最新快照goal与续期后的continuityToken/continuity_token。

错误码最为丰富，含GOAL_NOT_FOUND、SESSION_GENERATION_CHANGED（可重试，会话代数不匹配）、STALE_GOAL（可重试）、GOAL_NOT_RESUMABLE、EXECUTION_LEASE_REQUIRED、GOAL_EXECUTION_DISABLED。其中SESSION_GENERATION_CHANGED表明客户端持有的epoch已过期，需要重新通过会话发现流程获取最新代数。

七、别名兼容矩阵

契约切片刻意维持三类字段命名并存，以兼容新旧客户端：

契约通过anyOf/allOf组合确保任意别名形态都满足“至少提供其中一种”，同时在响应中也保留session_key、task_id等别名输出，方便老客户端直接消费。

八、后端落地：适配器绑定与校验

Python 侧的实现链路为：

1. 契约校验层：定义方法常量（GOALS_STATUS_METHOD、GOALS_SET_METHOD、GOALS_CAPABILITIES_METHOD、GOALS_REATTACH_METHOD）、GoalsContractError，以及goals_*_params_contract_errors参数观察器与validate_goals_*_result结果校验器；
2. 网关适配器：为每个方法构造GatewayContractBinding，携带 method descriptor、参数错误观察器、结果校验器、违约事件名（如goals.status.request_contract_mismatch、goals.status.contract_violation），并注册进MethodRegistry；
3. RPC 处理器 与 GoalService：执行真正的目标业务逻辑。

这种“契约校验在适配器、业务权威在服务”的分层，使请求参数违约与响应违约能被统一观测（分别触发request_contract_mismatch与contract_violation事件），同时保证GoalService无需感知 wire 层细节。

九、WebUI 消费侧：GoalCenter 与 GoalContinuity

前端 TypeScript/Vue 侧遵循“wire 别名留在适配器、领域投影下沉到模块”的约定。契约明确说明：Vue 代码应依赖GoalCenter，而不是生成的 wire 类型，见 goalCenter.ts。

• GoalCenter：注入useChatGoals，统一承载所有 Goal 查询与突变操作。模块内定义领域投影GoalSnapshot（含usageCoverage的normalizeGoalUsageCoverage归一化函数，对未知值保留为undefined）、GoalStatusResult、GoalSetInput/GoalSetResult、GoalMutationInput（sessionKey+expectedGoalId+expectedStateRevision的乐观并发输入）等类型；
• GoalContinuity（见 goalContinuity.ts）：独立模块，专属goals.reattach与session.event.goal解码，负责连续性令牌与执行租约的续接。

v4 方法名与遗留别名全部封装在 Gateway Adapter 之内，前端模块只消费规范化后的领域类型，从而保持 UI 层与 wire 层解耦。

十、测试与契约验证

仓库为 Goals 契约提供了多层验证：

• test_goals_contract.py 与 契约工具链测试 覆盖 Schema 结构与参数/结果校验逻辑；
• gateway_contract_verification.mjs 与 generate_gateway_contract_ajv.mjs 用于生成并核验 ajv standalone 校验器；
• generate_sessions_list_contract.py 等生成脚本确保 wire 类型与 Schema 保持同步。

这些测试从“契约即代码”的层面守护了别名兼容、幂等字段与乐观并发语义不被无意破坏。

十一、实践要点小结

1. 先查询、后突变：所有写操作（edit/pause/resume/clear/reattach）都依赖expectedStateRevision或epoch，操作前先goals.status获取最新修订号，冲突时以STALE_GOAL/SESSION_GENERATION_CHANGED为信号重新同步；
2. 幂等靠 client ID：goals.set必须携带 UUID-v4 格式的clientRequestId/clientMessageId，重试时复用同一 ID 即可安全去重（replayed: true表示命中幂等重放）；
3. 租约靠连续性令牌：跨会话/客户端续接执行必须使用goals.reattach，妥善保管返回的新continuityToken；接管遗留执行时才使用takeover: true；
4. 兼容靠别名：新客户端优先使用 camelCase，老客户端可继续使用 snake_case 与key/epoch遗留别名，无需迁移即可互操作；
5. 能力靠发现：接入新 UI 前先调用goals.capabilities，依据supported、executionEnabled、maxTurns与runtimeBudgetSeconds决定功能展示。

• 人工智能
• 大模型
• AI Agent
• 交互助手
• 工具调用
• MCP 服务
• Agent 记忆
• RAG