Repository navigation
RFC:OVSA 控制台 API 与选配功能(OVSA-CONSOLE-001) #7700
openviking-superagent
started this conversation in
RFC
Replies: 1 comment
|
基于 RFC 做了一版可交互的前端 + Mock Server Demo,补几张界面图供讨论。实现 PR:openviking-superagent#25 所有截图均来自隔离的 Mock 数据。写操作只修改内存状态,不代表生产 Daemon、Broker、PM2 或 Provider 控制能力已经实现。 实例总览健康、Connector 降级、Runtime、Worker 槽位、任务与投递指标。 Web Studio 风格侧栏与收起状态复用 Web Studio 的 OpenViking 品牌物料、Lucide 图标和侧栏颜色;桌面端可收起为 Logo + 图标列,刷新后保留状态。 配置与 Operation展示 desired / effective、restartRequired、If-Match 保存和持久 Operation 步骤。保存成功不等于配置已经生效。 Model Provider展示逻辑 Provider、Runtime 投影状态和凭据引用;凭据只写不读,不返回明文。 Task 取消确认外部副作用不会撤销,并区分 stopRequested 与 Worker termination。 |
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment





Uh oh!
There was an error while loading. Please reload this page.
RFC OVSA-CONSOLE-001:控制台 API 与选配功能
c53c76e;Task/Worker 参考 workers 分支b23cfae1. 摘要
OVSA 控制台采用统一
/api/v1,按四个阶段交付:功能按模块选配。只读能力默认开启,写能力默认关闭;API 同时返回
enabled / available / effective和不可用原因,不能只靠前端隐藏按钮。架构上分离 Instance Daemon 与 Local Control Daemon/Broker:前者管理自身运行状态和任务,后者管理 manifest、Provider、PM2、安装和日志。控制台不开放任意命令执行,不把密钥返回浏览器,不承诺取消或恢复能撤销外部副作用。
2. 背景与源码现状
当前源码提供:
http-api.mjs是 GET-only 的 loopback、same-origin 观测面:GET /api/activity、/health、/ready,没有登录和写接口。AgentRuntime.snapshot()提供 runtime、model、effort、capabilities、work、原生 session 连接态和模型目录;认知 epoch 来自Store.getCognitionState()。activities、cognition_journal、outbox、connector_events支撑现有观测。TaskManager提供 Task、input、report、恢复和停止。Worker 是 Task 某一轮的执行投影,不是另一套独立持久实体。deployment-manifest.mjs提供锁、校验和原子替换,但当前冲突检查是整份 JSON 字符串比较,不是 SHA-256 revision。/runtime与/primary也会从 daemon 写 manifest,未来 Broker 必须与它们共用锁和 revision。control.mjs已有限定 PM2 start/stop/restart/status/logs 流程,应复用领域函数,而不是拼 shell 调 CLI。独立评审确认的实现前置:
revision,Task 乐观锁需要新增事务内递增字段。task_turns持久化。task/turn/inputs/state,需要放行后由 API 投影成taskId/turn。TaskManager.stop()只发出停止请求,没有进程退出确认。3. 目标与非目标
目标
非目标
4. 总体架构
/api/v1。现有/api/activity、/health、/ready保留兼容,不在旧 GET 面上直接加写操作。5. 资源与状态语义
{taskId, turn}标识并持久化。/workers资源。epoch标识;不是一个 Task 的别名。nativeSessionRef,不能作为授权凭据。6. API 通用约定
6.1 分页与时间
{ "items": [], "nextCursor": "123", "hasNewer": false, "generatedAt": "2026-11-14T15:00:00Z" }limit=50,最大 100。before向后翻历史,after按 ID 升序实时追赶,二者互斥。*At统一 RFC 3339。legacy 的*AtMs原样保留,不在同一 v1 对象混用两种时间格式。6.2 Revision、幂等和错误
revision INTEGER NOT NULL DEFAULT 1,route/report/stop/status 更新同事务递增。If-Match: <revision>。expectedRevision,需要防止跨 Runtime 误切时带expectedRuntime。Idempotency-Key,保存请求体哈希与结果 24 小时;同 Key 不同 body 返回 409。{ "error": { "code": "revision_conflict", "message": "Configuration changed; reload before saving.", "retryable": false, "details": { "currentRevision": "sha256:..." }, "operationId": null, "uncertain": false } }映射:400
invalid_argument,401unauthenticated,403forbidden,404not_found,409invalid_state,412revision_conflict,422validation_failed,429rate_limited,502instance_unavailable,504operation_timeout。外部结果无法确认时明确uncertain=true,不能笼统报成功或 failed。6.3 Operation
长动作一律返回 202 + Operation,不靠长连接硬等。
{ "id": "op_01K...", "kind": "instance.restart", "instanceId": "primary", "state": "queued", "steps": [ { "name": "validate", "state": "succeeded" }, { "name": "save", "state": "pending" }, { "name": "restart", "state": "pending" }, { "name": "verify", "state": "pending" } ], "revision": 3, "createdAt": "2026-11-14T15:00:00Z", "updatedAt": "2026-11-14T15:00:00Z" }状态:
queued | running | succeeded | failed | uncertain | cancelled。步骤记录可恢复点;取消只停止后续步骤,不谎称撤销已创建的 App、授权或其他外部资源。通用查询:
GET /api/v1/operations/{operationId}GET /api/v1/operations?instanceId=&state=7. P0:只读控制台 API
前置:Task 端点依赖 workers 分支合入,且实例同时满足
scheduler=workers和 Runtime 支持 Worker。其他实例的capabilities.workerMode=false;Task 集合返回空集并附能力状态,具体 Task ID 仍返回 404。GET /api/v1/capabilitiesGET /api/v1/instancesGET /api/v1/instances/{id}/overviewGET /api/v1/instances/{id}/healthGET /api/v1/instances/{id}/runtimeGET /api/v1/instances/{id}/runtime/models?refresh=falseGET /api/v1/instances/{id}/sessionsGET /api/v1/instances/{id}/sessions/{epoch}GET /api/v1/instances/{id}/tasks?status=&runtime=&q=&before=&limit=GET /api/v1/instances/{id}/tasks/{taskId}GET /api/v1/instances/{id}/tasks/{taskId}/inputs?before=GET /api/v1/instances/{id}/tasks/{taskId}/reports?before=GET /api/v1/instances/{id}/tasks/{taskId}/events?after=GET /api/v1/instances/{id}/activities?epoch=&taskId=&kind=&category=&severity=&before=&after=GET /api/v1/instances/{id}/metrics?window=1hTask 示例:
{ "id": "t201", "revision": 8, "title": "设计控制台 API", "status": "running", "runtime": "pi", "origin": { "source": "lark", "sourceRef": "ref_...", "messageRef": "ref_..." }, "turns": 2, "recovering": false, "worker": { "state": "running", "turn": 2, "startedAt": "2026-11-14T15:00:00Z", "sessionRef": "nsr_...", "canCancel": true }, "usage": { "inputTokens": 12000, "cachedInputTokens": 3000, "outputTokens": 900 }, "createdAt": "2026-11-14T14:50:00Z", "updatedAt": "2026-11-14T15:03:00Z" }P0 数据改造:
task/turn/inputs/state,API 投影taskId/turn;operationId由新写入点补齐。最好增加索引列,不靠 summary 关联。tasks(status, created_at_ms)、task_reports(task_id, id)和 delivery 查询索引,不能沿用“活跃任务 + 最近 32 个 ended”的 working set。task_turns,保存起止、耗时、usage、errorKind。errorKind 收敛为明确枚举,不能只存任意错误字符串。relay={state: pending|relayed_to_inbox,inboxId,at}与finalDelivery={outboxId,status},不能用relayedAt代替最终送达。COUNT(*)+1改为事务内序列分配。8. P1:任务与 Runtime 控制 API
POST /api/v1/instances/{id}/tasks/{taskId}/actions/cancelPOST /api/v1/instances/{id}/sessions/actions/new/new相同语义;明确提示会中断当前 turnPOST /api/v1/instances/{id}/runtime/actions/selectPOST /api/v1/instances/{id}/runtime/actions/modelPOST /api/v1/instances/{id}/runtime/actions/effort取消响应:
{ "taskId": "t201", "status": "stopped", "revision": 9, "worker": { "stopRequested": true, "termination": "pending" } }termination只有在handle.done实际 settle 或超时后才更新为confirmed|uncertain,不能仅凭 stop 调用返回确认退出。AgentRuntime.transition,保留stale-snapshot/runtime-changed/unsupported-effort等原因和 preflight,不能由 Web 自己改 manifest 后假装已切换。retryOf的 Task/attempt,并让 owner 确认可能重复外部动作。decision_id,不绕过 Router 的消息唯一出口。9. P2:实例配置、setup 与 restart API
GET /api/v1/instances/{id}/configurationPOST /api/v1/instances/{id}/configuration/validatePATCH /api/v1/instances/{id}/configurationPOST /api/v1/instancesPOST /api/v1/instances/{id}/actions/restartPOST /api/v1/instances/{id}/actions/stopPOST /api/v1/instances/{id}/actions/startGET /api/v1/setup/runtimesPOST /api/v1/setup/probes配置响应:
{ "instanceId": "primary", "revision": "sha256:...", "desired": { "displayName": "Primary Agent", "workspace": "/home/me/work/primary", "runtime": "pi", "model": "openai/gpt-...", "effort": "medium", "scheduler": "workers", "connectors": ["lark"] }, "effective": { "runtime": "pi", "model": "openai/gpt-...", "ready": true }, "restartRequired": false, "ignoredFields": [], "capabilities": { "canEdit": true, "canRestart": true, "workerMode": true } }不返回整份 config 或全局 env。端口、dataDir、release、PM2 app 名和锁路径默认只读;环境变量采用命名字段投影,不允许任意 env 注入。
配置 apply 事务
loadDeploymentManifest和 setup 领域校验,不只做 JSON Schema。/runtime、/primary、Broker 三条写路径共用 InstanceLock 和 revision。/model即时切换与“保存为下次启动默认模型”是两个动作,API 不混写。10. Model Provider API
统一的是逻辑模型路由和凭据引用,不是假设所有 Runtime 认证相同。
GET /api/v1/model-providers?instanceId=POST /api/v1/model-providersPATCH /api/v1/model-providers/{providerId}DELETE /api/v1/model-providers/{providerId}POST /api/v1/model-providers/{id}/actions/validatePUT /api/v1/model-providers/{id}/credentialDELETE /api/v1/model-providers/{id}/credentialGET /api/v1/instances/{id}/model-bindingsPUT /api/v1/instances/{id}/model-bindings/{runtime}{ "id": "ark-main", "revision": "sha256:...", "protocol": "openai-compatible", "baseUrl": "https://ark.cn-beijing.volces.com/api/v3", "models": [{ "id": "model-x", "efforts": ["medium", "high"] }], "credential": { "ref": "cred_ark_main", "configured": true }, "bindings": [ { "instanceId": "primary", "runtime": "pi", "state": "synced" }, { "instanceId": "primary", "runtime": "dsh", "state": "restart_required" } ] }~/.pi/agent/models.json、DSH 原生设置和各 Runtime 登录态,再单独实现 registry 与写路径。authKind=api_key|oauth|environment|external。synced | restart_required | unsupported | drift | failed。不支持的协议、headers、参数必须显式报 unsupported,不能静默丢配置。POST /api/v1/runtime-packages/{id}/actions/install,复用 Operation、版本/签名校验和回滚,不与 Provider 首版捆绑。11. 日志与诊断 API
GET /api/v1/instances/{id}/logs?stream=daemon&before=&after=&limit=GET /api/v1/instances/{id}/diagnosticsPOST /api/v1/instances/{id}/diagnostics/bundleGET /api/v1/operations/{id}/artifact只认预定义 stream,不接受路径、
tail参数或 shell。默认不包含完整聊天、环境变量、密钥文件和原生 Session 数据;诊断包列出内容与保留期。12. 控制台选配功能
12.1 选配原则
enabled是 owner 选择,available是环境可运行,effective = enabled && available。12.2 功能列表
“默认”是 RFC 建议值,不是当前源码配置。
instances.readcapabilities.readruntime.readsessions.readactivity.readtasks.readmetrics.readtasks.controlruntime.controlsessions.controlconfiguration.readconfiguration.writeinstances.setupinstances.processproviders.readproviders.writeruntimePackages.installlogs.readdiagnostics.bundleaudit.readevents.streamtasks.retrytasks.pause12.3 推荐组合
12.4 Capabilities 响应
{ "instanceId": "primary", "modules": { "tasks.read": { "enabled": true, "available": true, "effective": true, "reasonCode": null }, "tasks.control": { "enabled": false, "available": true, "effective": false, "reasonCode": "disabled_by_owner" }, "runtimePackages.install": { "enabled": true, "available": false, "effective": false, "reasonCode": "unsupported_platform", "message": "This Windows installation does not support runtime package installation." } } }标准原因码:
disabled_by_owner、workers_not_merged、scheduler_not_workers、runtime_unsupported、platform_unsupported、control_broker_unavailable、authentication_required、permission_denied、dependency_disabled、instance_offline。未来配置形态:
{ "console": { "modules": { "tasks.control": false, "runtime.control": false, "configuration.write": false, "instances.process": false, "providers.write": false, "logs.read": false } } }当前 config 不支持此字段。实现需补 schema、默认值、迁移和审计;省略字段采用 RFC 默认值,未实现模块即使配置 true 也始终 unavailable。
13. 鉴权、隐私与审计
14. 一致性与故障语义
/ready保持现状:至少一个 Connector 正常即可 ready,其他故障为 degraded,不能为了控制台改成不健康。15. 分阶段交付与验收
Slice A:只读任务面板
端点:capabilities、instances、overview、runtime、sessions、tasks、inputs/reports/events、activity、metrics。页面:实例总览、任务列表、任务详情。
验收:
t1不串数据;多实例不串聊天内容。Slice B:安全控制
增加 owner 登录、CSRF、审计和 P1 控制端点。
验收:
Slice C:配置与进程
实现 Broker、配置投影、probe、Operation、原子保存、ready 校验和一次配置回滚。
验收:
/runtime或/primary不被覆盖。Slice D:Provider 与诊断
验收:
16. 浏览器体验验收清单
当前没有控制台实现,以下是待执行用例,不代表已经测试。
17. 明确不采用的捷径
POST /restart、POST /exec或任意配置写入。All reactions