Skip to content

web-management-api.md

Latest commit

 

History

History
92 lines (77 loc) · 5.28 KB

web-management-api.md

File metadata and controls

92 lines (77 loc) · 5.28 KB
Raw

Web Management API

praxisd 在既有 daemon listener 上提供本地管理 API，固定前缀为 /api/v1。它与 /healthz、/statusz 共享同一个 http.Server，不启动第二 端口、进程或无主 goroutine。该能力面向本机管理 UI/脚本，不是公网管理面。

配置与数据

adapters:
  web:
    enabled: true          # 默认 true
    json_body_limit: 1048576
    upload_limit: 33554432
    report_ttl_seconds: 86400
    report_total_limit: 67108864
    report_cleanup_limit: 128
  • authority 来自 daemon.listen，不能由请求 Host 反向推导。
  • 生产治理数据默认保存到 ~/.praxis/praxis.db；可通过进程级 PRAXIS_DATA_DIR 覆盖数据根。目录权限收紧为 0700。
  • 上传先进入数据根下的私有随机临时文件，完成或失败后清理。
  • batch validation report 位于数据根的 web/reports/batch-validation/ 私有目录， 默认保留 24 小时、总容量 64 MiB；写入使用随机 opaque ID、0600 临时文件、 fsync 与原子 rename。启动、写入和读取只做有界惰性清理，不启动后台 goroutine。
  • 设置 adapters.web.enabled: false 可关闭整个 /api/v1 mount；治理 SQLite 文件与其它 replay/batch/MCP 组件不删除、不迁移、不受影响。

安全边界

  • 每个请求必须来自 loopback，且 Host 必须匹配 daemon authority。
  • 写请求必须携带 same-origin Origin，并先从 GET /api/v1/csrf 获取短期 CSRF session/token。
  • 不启用 CORS；统一设置 CSP、frame、referrer、nosniff 等响应头。
  • JSON 拒绝未知字段、重复字段、类型错误与尾随内容；列表使用有界 keyset cursor（默认 50，最大 200）。
  • 所有 JSON、错误 details、日志和下载元数据都经过注入的出口脱敏器；HTTP handler 不解引用 Vault，也不接触 Cognition、Agent、driver 或 SQL。
  • artifact 只允许已记录且归属对应 Run 的 artifact://run_<id>/step<N>.png，不提供目录枚举或通用文件服务。
  • Run/Trace JSON 只给浏览器返回 /api/v1/* 相对 canonical links。inline 预览 只接受实际内容再次验证为 PNG 的对象；SVG、HTML、JSON、CSV、XLSX、未知或 MIME mismatch 永不 inline。下载/预览均使用私有缓存、内容 ETag、nosniff， inline 额外设置严格 CSP。

Endpoint families

  • 看板与状态：GET /overview、GET /system；Overview 返回终态分布、 replay/heal token 分账、待审批、近期 Run、组件健康，真实趋势源缺失时明确 trend.status=unavailable；System 返回 api_version=v1、management readiness 与 cognition.configured 安全标量。
  • Run 与审批：Run 列表/详情/Trace/网络摘要/创建/审批，Run summary 增加 heal、 pending approval、exception 指示；详情增加脱敏 input_summary、 identity_alias 和 artifact descriptors。
  • Skills：旧单 segment routes 保持兼容；canonical family 使用服务端生成的 /skills/by-id/{skill_id} 覆盖详情、版本、单版本 Review、diff 和 transition， 支持含 //Unicode 的合法 skill_ref。Review evidence 只来自 Registry 持久摘要。
  • Batch：模板、受限上传导入、列表/详情、启动、导出、失败行重试模板；校验失败 返回 report_id 与同源 download_url，并可经 GET /batch-validation-reports/{report_id} 在 TTL 内恢复下载。
  • Policy：列表、显式/保守默认读取、带 If-Match 的覆盖更新
  • Scheduler：列表、GET /schedules/{id} 单项 ETag、带同一资源 If-Match 的 启停与手动 fire；集合 ETag 不能作为单项 PATCH 前置条件；不开放 trigger CRUD/cron 编辑。

所有 JSON 端点使用 {data,error,meta} 信封，错误码、request_id、cursor、 ETag/If-None-Match 与覆盖写 If-Match 语义保持稳定。可选能力未装配时返回 503 CAPABILITY_UNAVAILABLE，不返回 fake 零值。

依赖与许可证

Router 使用 github.com/gin-gonic/gin v1.12.0，上游许可证为 MIT。Gin import 由不变量测试限制在 internal/webapi/**，且源码静态禁止 gin.Default()、 Engine.Run、ListenAndServe 与通用文件服务器。

验证口径与已知边界

仓库验证覆盖 endpoint contract、安全否定矩阵、race/vet、I-4/I-5/I-6 import 边界、持久化重启、同 listener 控制面命令链和 adapter 禁用回滚。重启用例通过 正式共库 Store 写入 Run、HEAL_EVENT、ESCALATION、Skill、Policy、Trace、网络摘要 与 batch 簿记，再重新装配并经 API 回查。

这些证据是控制面/契约级验证，不是生产站点验收：

  • daemon 当前仍使用 noDriverReplay，因此无真实 Chrome 时 Run 会安全失败或被 policy 拒绝；/system 将 replay telemetry 标为 unavailable。
  • batch 的 BATCH/BATCH_ROW 簿记可跨重启查询，但上游 AggregateBatch 当前还依赖 进程内 columns anchor；不能据此宣称重启后可立即聚合或导出历史批次。
  • validation report 是 node-local、短期、可清理的错误 artifact，不是业务档案； service mode 请求若未落到 owner node，应把该 capability 显示为 unavailable， 不能回退到任意文件读取。
  • 真实 Chrome、目标站点、反检测与外部 Agent 全链必须另附实际运行证据。