@sema-agent/server 1.214.0 → 1.214.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +158 -185
  2. package/README.zh-CN.md +176 -0
  3. package/deploy/sema-up/README.md +1 -1
  4. package/dist/http/server.d.ts.map +1 -1
  5. package/dist/http/server.js +1 -1
  6. package/dist/http/server.js.map +1 -1
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -1,207 +1,180 @@
1
+ <div align="center">
2
+
1
3
  # @sema-agent/server
2
4
 
3
- **Sema Server** 是 Sema 的服务端/API 实现层 —— 连接 core、registry、模型 provider、以及云端 agent 运行能力。
5
+ **The server/API layer of the Sema stack — wire the engine, serve the fleet.**
4
6
 
5
- ## 快速开始(公开分发)
7
+ [![npm](https://img.shields.io/npm/v/%40sema-agent%2Fserver)](https://www.npmjs.com/package/@sema-agent/server)
8
+ [![license: BUSL-1.1](https://img.shields.io/badge/license-BUSL--1.1-blue)](#license)
6
9
 
7
- ```bash
8
- # A) npm(需 node 22+)
9
- npm install @sema-agent/server
10
- MODEL_GATEWAY_BASEURL=https://api.deepseek.com MODEL_ID=deepseek-chat \
11
- MODEL_API_KEY=<你的-key> SERVICE_AUTH_TOKEN=<自定> \
12
- node node_modules/@sema-agent/server/dist/main.js # → :8090
10
+ [Quick start](#quick-start) · [Configuration](#configuration) · [HTTP API](#http-api-overview) · [Ecosystem](#ecosystem) · [License](#license)
13
11
 
14
- # B) 容器(零依赖,匿名可拉)
15
- docker run -p 8090:8090 \
16
- -e MODEL_GATEWAY_BASEURL=https://api.deepseek.com -e MODEL_ID=deepseek-chat \
17
- -e MODEL_API_KEY=<你的-key> -e SERVICE_AUTH_TOKEN=<自定> \
18
- ghcr.io/sema-agent/sema-server:latest # 或 docker.io/claybobby/sema-server:latest
12
+ [中文](./README.zh-CN.md)
19
13
 
20
- # 提交一个任务
21
- curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>" \
22
- -H 'content-type: application/json' -d '{"objective":"用一句话回答:1+1 等于几?"}'
23
- # 带指定模型:body 加 "model":"<catalog id>";可用模型见 GET /v1/capabilities
24
- ```
14
+ </div>
25
15
 
26
- - **一键部署**(DB+MinIO+registry 网站+沙箱池,docker/k8s 双路径):独立仓
27
- [`clayboby/sema-deploy`](https://github.com/clayboby/sema-deploy)。
28
- - **分发坐标**:npm=`@sema-agent/server`(npmjs 公开)· 镜像=`ghcr.io/sema-agent/sema-server` +
29
- `docker.io/claybobby/sema-server`(均 public,`:latest` 滚动 / `:<sha>` 钉版)。
30
- - **版本策略**:1.x=快速迭代期,BREAKING 变更可能落在 minor(见 [`MIGRATION.md`](MIGRATION.md))——
31
- **生产部署请锁精确版本**(`@sema-agent/server@1.184.0`);GA 后切 2.0 起严格 semver。
32
- - **许可**:[BUSL-1.1](LICENSE)(个人/教育/研究/非商用生产随意;**商用生产需商业授权**;
33
- 2030-07-13 起自动转 Apache-2.0)。≤1.180.1 的已发布副本仍受其发布时的 MIT 约束。
34
- - **沙箱装包源**:缺省=官方源(pypi/npmjs/crates.io/…,海外为准)。中国大陆部署配
35
- `SANDBOX_PKG_SOURCE=cn` 切国内镜像源(tuna/npmmirror/rsproxy/aliyun),自定义源用
36
- `SANDBOX_PKG_SOURCE=custom` + `SEMA_*_MIRROR/INDEX/REGISTRY` 显式 URL。
16
+ ---
37
17
 
38
- 中心化、容器化的 **Managed-Agents 服务**,构建于 [`@sema-agent/core`](https://www.npmjs.com/package/@sema-agent/core)。
18
+ ## What it is
39
19
 
40
- - **它是什么**:一个**无状态的 runner 服务**(Brain 平面 + HTTP/SSE 契约)。`docker run` 即起一个,可多开。
41
- - **它不是什么**:不是持久化中心。**真相/记忆在外部 TiDB**(Session 事件日志 L1 + 长期记忆 L2)。容器是手脚,TiDB 是记忆。
42
- - 与 core 的关系:core 是 npm 依赖(出机制+接口),本仓出部署物+后端插件+服务契约。**两仓路线图分开维护**(见 `design/ROADMAP.md`)。
20
+ `@sema-agent/server` is the server/API implementation layer of the Sema stack: it wires the
21
+ [`@sema-agent/core`](https://www.npmjs.com/package/@sema-agent/core) engine, registry configuration,
22
+ model gateways, and cloud agent execution behind an HTTP/SSE contract.
43
23
 
44
- > 架构依据(三平面解耦 brain/hands/session、多层记忆 L0-L3)见 core 仓库 `design/00-03`。
24
+ **It is:**
45
25
 
46
- > 🧭 **接手/最新真相(2026-06-15 架构师交叉验证)**:从代码反推、纠正了过时文档。先读 **[`HANDOFF.md`](HANDOFF.md)**(单一入口),它索引到:
47
- > [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)(架构+图)· [`docs/ROADMAP.md`](docs/ROADMAP.md)(前瞻路线)· [`docs/ORCHESTRATION-STATUS.md`](docs/ORCHESTRATION-STATUS.md)(编排矩阵+效果)·
48
- > [`docs/SERVICE-AI-GUIDE.md`](docs/SERVICE-AI-GUIDE.md)(对外使用+重点分析)· [`docs/REFERENCES.md`](docs/REFERENCES.md)(论文文献)· [`docs/DOC-CORRECTIONS.md`](docs/DOC-CORRECTIONS.md)(文档修正项+证据)· [`BUG-LEDGER.md`](BUG-LEDGER.md)(当前 bug 台账)。
49
- > **当前版本 = service `1.1.0` / core `^1.99.1`**;**v2 leader 编排器已建成并接线**(`LEADER_ENABLED`,默认关),不再 HOLD。
26
+ - **An HTTP/SSE server plus assembly layer.** Requests carry content (`objective`, `sessionId`,
27
+ `scenario`, …); the server assembles everything else per task — tools, sub-agent rosters,
28
+ prompts, skills, policy — and injects identity, sessions, and safety policy server-side.
29
+ Credentials live in server-side closures, never in the request body, the model, or the sandbox.
30
+ - **Stateless by design.** Replicas are cattle: `docker run` starts one, start as many as you need
31
+ behind a load balancer. Durable state — sessions, runs, replayable event logs, checkpoints,
32
+ approvals — lives in an external SQL store (any MySQL-protocol database such as MySQL/TiDB/MariaDB,
33
+ or PostgreSQL; a file-backed `local` mode covers single-machine use). Any replica can serve any
34
+ run's event stream; a task can suspend on one replica and resume on another.
35
+ - **The full server-side capability surface** (discoverable at `GET /v1/capabilities`):
36
+ asynchronous runs with replayable SSE, durable checkpoints with human-in-the-loop approvals,
37
+ sessions and long-term memory, multi-scenario assembly from one image, per-task sub-agents,
38
+ deterministic workflow orchestration, and pluggable sandbox execution lanes
39
+ (`host`, `local-docker`, `e2b`, `k8s`, `ssh`, `adb`).
50
40
 
51
- ## 跑起来(本地 dev)
41
+ **It is not:**
52
42
 
53
- ```bash
54
- cp .npmrc.example .npmrc # 填一个 read:package 的 Gitea token,用于装 @sema-agent/core
55
- npm install
56
- MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1 MODEL_ID=Qwen3.5-35B npm run dev
57
- # → POST /v1/tasks · POST /v1/tasks/stream (SSE) · GET /health
58
- ```
43
+ - **Not the engine.** The agent loop, tool harness, memory, and checkpoint machinery are
44
+ [`sema-core`](https://github.com/sema-agent/sema-core); this repository consumes it as an npm
45
+ dependency and contributes wiring, backends, and the service contract.
46
+ - **Not the CLI.** The terminal agent is [`sema`](https://github.com/sema-agent/sema); it (and the
47
+ web UI) are clients of this server.
48
+ - **Not the deployment tooling.** One-command self-hosted deployment (Docker single node or
49
+ Kubernetes) is [`sema-deploy`](https://github.com/sema-agent/sema-deploy).
50
+ - **Not a persistence center.** The truth lives in the external database; the server processes are
51
+ disposable.
52
+
53
+ ## Architecture
54
+
55
+ <!-- TODO: architecture SVG — visual assets live with the portal repo (sema-agent/sema); text version below. -->
56
+
57
+ <details>
58
+ <summary>Text version</summary>
59
59
 
60
- ```bash
61
- curl -s localhost:8090/health
62
- curl -s localhost:8090/v1/tasks -H 'content-type: application/json' \
63
- -d '{"objective":"用一句话自我介绍"}'
64
60
  ```
61
+ HTTP / SSE API Assembly Execution lanes
62
+ ────────────── ──────── ───────────────
63
+ /v1/tasks (sync) ──┐ ┌─ per-task spec ─┐ ┌─ host (this machine)
64
+ /v1/runs (async) ──┤ │ scenarios · skills │ ├─ local-docker (per-task container)
65
+ /v1/sessions ──┼──▶│ policy · approvals │──▶├─ e2b (Firecracker VM)
66
+ /v1/approvals ──┤ │ registry config │ ├─ k8s (Kata pod sandbox)
67
+ /v1/workflows ──┘ │ model gateway(s) │ └─ ssh / adb (real host / device)
68
+ └─ @sema-agent/core ─┘
69
+ │
70
+ Durable stores (MySQL/TiDB · PostgreSQL · local file)
71
+ sessions · runs · event logs · checkpoints · approvals
72
+ ```
73
+
74
+ </details>
65
75
 
66
- ## Docker(运行时 = **Bun**)
76
+ ## Quick start
67
77
 
68
- 镜像用 Bun **直接跑 TypeScript**(无 build/transpile,冷启动快、无 dist)。token 仅在构建装依赖阶段用,**不进终镜像**(多阶段)。
78
+ Requirements: Node ≥ 20 (npm path) and an OpenAI-compatible model gateway.
69
79
 
70
80
  ```bash
71
- # 直接 build/run
72
- docker build --build-arg GITEA_NPM_TOKEN=<read:package token> -t sema-server .
81
+ # A) npm
82
+ npm install @sema-agent/server
83
+ MODEL_GATEWAY_BASEURL=https://api.deepseek.com MODEL_ID=deepseek-chat \
84
+ MODEL_API_KEY=<your-key> SERVICE_AUTH_TOKEN=<pick-one> \
85
+ node node_modules/@sema-agent/server/dist/main.js # → :8090
86
+
87
+ # B) container (zero local deps, anonymous pull)
73
88
  docker run -p 8090:8090 \
74
- -e MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1 -e MODEL_ID=Qwen3.5-35B \
75
- -e DB_BACKEND=mysql -e MYSQL_HOST=... -e MYSQL_USER=... -e MYSQL_PASSWORD=... -e MYSQL_DATABASE=sema_server \
76
- -e SERVICE_AUTH_TOKEN=xxx sema-server
77
-
78
- # 或 compose:一条命令起「LB + worker 集群」。OA 只认 LB 一个地址 http://<host>:8090
79
- GITEA_NPM_TOKEN=<read:package token> TIDB_HOST=... TIDB_USER=... TIDB_PASSWORD=... docker compose up --build
80
- docker compose up --build --scale service=4 # 4 个无状态 worker,nginx LB 扇发,TiDB 协调
81
- # 本地 throwaway TiDB:加 -e TIDB_HOST=tidb 并 `docker compose --profile localdb up --build`
89
+ -e MODEL_GATEWAY_BASEURL=https://api.deepseek.com -e MODEL_ID=deepseek-chat \
90
+ -e MODEL_API_KEY=<your-key> -e SERVICE_AUTH_TOKEN=<pick-one> \
91
+ ghcr.io/sema-agent/sema-server:latest # or docker.io/claybobby/sema-server:latest
92
+
93
+ # Submit a task
94
+ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>" \
95
+ -H 'content-type: application/json' -d '{"objective":"Answer in one sentence: what is 1+1?"}'
96
+ # To pin a model: add "model":"<catalog id>" to the body; see GET /v1/capabilities for what is available
82
97
  ```
83
98
 
84
- > **拓扑**:没有单独的"中心化调度 API"。**中心化 = TiDB(数据)**;**统一入口 = LB(`deploy/nginx.conf`)**;worker 无状态可多开,跨 worker 靠 TiDB 协调(`task_active` 抢占防双跑、session CAS、事件日志重放、心跳+reaper),**无中央大脑**。任意 worker 都能服务任意 run 的 `/v1/runs/:id/events`(断线重连经 LB 落到别的 worker 也能接上)。
85
-
86
- > ⚠️ **大陆拉不动 Docker Hub**:基础镜像 `oven/bun:1-slim` 走 Docker Hub,大陆常连不上。三种解法:
87
- > 1. `--build-arg BUN_IMAGE=<镜像站>/oven/bun:1-slim`(或 compose:`BUN_IMAGE=… docker compose build`);
88
- > 2. 配 dockerd `registry-mirrors`,让 `oven/bun:1-slim` 自动走镜像站;
89
- > 3. **推荐(一次镜像,处处可用)**:在能访问 Docker Hub 的机器上跑 `deploy/mirror-base-images.sh`,把 bun-slim + nginx-alpine(+可选 tidb)一把镜像进你的内网 registry,之后所有构建/部署都 `--build-arg BUN_IMAGE=…/bun:1-slim`、compose `LB_IMAGE=…/nginx:1.27-alpine`,再不碰 Docker Hub。脚本顶部有用法。
90
-
91
- CI:`.gitea/workflows/ci.yml`(Node 跑确定性测试 → 构建 Bun 镜像 → 推 Gitea registry)。
92
- > 镜像基底默认 `oven/bun:1-slim`(`ARG BUN_IMAGE` 可覆盖);要更小可换 `oven/bun:1-distroless`(无 shell,用编排层 `httpGet /health` 探针)或后续 `bun build --compile` 出单二进制(待验证)。
93
-
94
- ## 配置(env)
95
-
96
- | 变量 | 默认 | 说明 |
97
- |------|------|------|
98
- | `PORT` | 8090 | 监听端口 |
99
- | `MODEL_GATEWAY_BASEURL` | http://127.0.0.1:8000/v1 | OpenAI 兼容网关(不带 /chat/completions) |
100
- | `MODEL_ID` | Qwen3.5-35B | 模型 id |
101
- | `MODEL_API_KEY` | — | 网关 key(可选) |
102
- | `DB_BACKEND` | mysql | SQL 引擎:`mysql`(任何 MySQL 协议库:MySQL/TiDB/MariaDB;`tidb` 为兼容别名)/ `pg`(PostgreSQL)/ `local`(免 DB 文件持久化)。**显式设置 mysql/pg 时 session 自动转 durable(2026-07-06 收编)** |
103
- | `SESSION_BACKEND` | memory* | `memory` / `mysql`(durable L1 中心;`tidb` 别名)/ `auto`(探测 DB host,连不上退 memory)。*显式 `DB_BACKEND=mysql/pg` 时默认转 durable |
104
- | `MEMORY_ENGINE` / `MEMORY_ENGINE_DIR` | on / `~/.ai-agent` | 长期记忆 = core 注入式**文件记忆引擎**(design/138;单用户默认开,`off` 显式关;多租户恒关)。旧 `MEMORY_BACKEND`/`EMBEDDING_*` SQL 记忆面已退役(数据不迁移,升级后跑 `scripts/drop-memory-tables.sql`) |
105
- | `MYSQL_HOST/PORT/USER/PASSWORD/DATABASE` | — | MySQL 协议连接(`TIDB_*` 同名别名仍认;缺省端口:MYSQL_HOST→3306,TIDB_HOST→4000) |
106
- | `SESSION_CACHE_TTL_SEC` | 300 | warm 缓存 idle TTL(需会话亲和);0 关 |
107
- | `SERVICE_AUTH_TOKEN` | — | 调用方需带 `Authorization: Bearer <token>` |
108
- | `PRINCIPAL_HEADER` / `REQUIRE_PRINCIPAL` | `x-agent-principal` / false | S6 身份头 / 多租户生产置 true |
109
- | `APPROVAL_REQUIRE` / `APPROVAL_DENY` / `APPROVAL_TIMEOUT_SEC` | — / — / 0 | F4 审批门控工具名 / 永拒 / 待审超时 |
110
- | `RATE_LIMIT_RPM` | 0 | 每 principal 每分钟请求上限(task/run 端点);0 关 |
111
- | `REAP_RUN_STALE_SEC` / `REAP_INTERVAL_SEC` | 120 / 60 | run 心跳超此判僵尸(须 > 30s 心跳;启动断言)/ reaper 周期 |
112
- | `LOG_LEVEL` | info | `debug`/`info`/`warn`/`error`(结构化 JSON 日志) |
113
- | `DEFAULT_SCENARIO` / `SKILLS_DIR` | default / skills | 缺省场景 / 烘焙 skill 目录 |
114
- | `SESSION_AUTO_TITLE` | true | session 自动起题(首次提交后用 cheap 档模型[`MODEL_CHEAP_ID`,未配则主模型]生成一次 title,每 session 一次调用;`false` 关) |
115
- | `GIT_API_BASEURL` / `GIT_API_TOKEN` | — | code-review 场景的只读 Git API(token 仅服务端) |
116
- | `CORS_ORIGIN` | — | 如 `https://oa.内网` |
117
-
118
- > **进阶 env(完整说明见 [`USAGE.md`](USAGE.md))**,按域分组:
119
- > - 成本/限额:`MAX_TASK_COST_USD` · `MAX_PRINCIPAL_COST_USD` · `MODEL_DEGRADE_TO`/`_AT_COST_FRACTION`/`_REACTIVE` · `MODEL_CASCADE_LADDER`
120
- > - 韧性:`MODEL_CONNECT_TIMEOUT_MS` · `MODEL_FIRST_TOKEN_TIMEOUT_MS` · `MODEL_IDLE_TIMEOUT_MS` · `MODEL_CIRCUIT_BREAKER`(+ 阈值)· `MODEL_GATEWAY_FALLBACK_URLS`
121
- > - 多模型:`MODEL_CHEAP_ID` · `MODEL_CODE_ROLES` · `ANTHROPIC_API_KEY`(云路由)
122
- > - 落盘/可观测:`TOOL_RESULT_TTL_SEC` · `OTEL_EXPORTER_OTLP_ENDPOINT`
123
- > - 安全/控制面:`OPERATOR_PRINCIPALS` · `SEMA_REGISTRY_URL`/`_TOKEN`/`_DRY_RUN`/`_WORKER`(新名,orchestrator 注入;旧名 `CONFIG_CENTER_*` 仍兼容回退)
124
- > - 远端执行(code-agent worker):`REMOTE_EXEC`(`e2b`/`k8s`/`ssh`/`adb`)· `E2B_API_KEY`/`E2B_TEMPLATE`/`E2B_LIVENESS_MS` · **`E2B_SANDBOX_ENV`**(本 worker env 变量名 CSV → 带外注入沙箱,口令不进 prompt/命令/日志;见 [`docs/CONSUMER-SANDBOX-SKILLS.md`](docs/CONSUMER-SANDBOX-SKILLS.md))
125
-
126
- > **场景/能力层**:一份镜像服务多场景。请求体可带 `scenario`(默认 `DEFAULT_SCENARIO`),服务端按场景**装配一次**好的 {工具(含 subagent 角色册)+ 整套 harness 提示词 + skill};**身份/会话/策略仍服务端注入,不信 body**。
127
- > - `default`:`now` 等通用工具。
128
- > - `code-review`:请求体带 `repo`(`owner/name` 或 URL);注入**只读 repo 工具**(`repo_tree`/`repo_read_file`/`repo_pull_diff`,走 Git API、token 服务端)+ 镜头 **subagent**(6 个:security / correctness / performance / api-contract / tests / readability,可用 `lenses:N` 取前 N 个,各自隔离上下文 + repo 访问)+ 评审 promptProvider + 评审 skill。lead 规划→派发→汇总成分级评审(`council:true` 开;`debate:true` 加平级辩论)。跑测试/lint(沙箱 ExecutionEnv)是后续扩展位。
129
-
130
- > **可观测**:`GET /metrics`(Prometheus)+ 结构化 JSON 日志(stdout)。指标:`http_requests_total`、`http_request_duration_seconds`、`tasks_total{status}`、`task_tokens_total`、`task_duration_seconds`、`runs_active`、`sessions_warm`、`rate_limited_total`。多实例下计数 per-instance,在 scraper 聚合。
131
-
132
- ## 服务契约(当前 / 目标)
133
-
134
- | 端点 | 现状 |
135
- |------|------|
136
- | `GET /health` | ✅ |
137
- | `GET /metrics` · `/metrics/summary` · `/metrics/plan-cache` | ✅ Prometheus 文本 / 精炼健康 JSON(Fleet 卡片)/ plan-cache 复现率;`SERVICE_AUTH_TOKEN` **或**只读 `METRICS_TOKEN` |
138
- | `GET /v1/capabilities` | ✅ 部署能力发现(asyncRuns/artifacts/approvals/leader/memory/scenarios/version)——免 501 探测 |
139
- | `GET /v1/models` | ✅ `@-model` 目录(仅名字,不含 baseUrl/key) |
140
- | `POST /v1/tasks` | ✅ 同步:跑到结束返回 `TaskResult`(短轮对话用);支持 `verify`/`cascade` |
141
- | `POST /v1/tasks/stream` | ✅ 同步 SSE:逐 token 流式 `TaskEvent`(同实例) |
142
- | `POST /v1/runs` | ✅ **异步(S1)**:立即 `202 {taskId, sessionId, status}`,后台续跑;同 session 已有活跃 run → `409` |
143
- | `GET /v1/runs/:id` | ✅ run 状态 + 结果(轮询;owner 校验) |
144
- | `GET /v1/runs/:id/events` | ✅ **可重放 SSE(S2)**:`Last-Event-ID` 续订,任意实例可服务(事件在 TiDB);文本按 turn 粒度合并 |
145
- | `POST /v1/runs/:id/cancel` | ✅ 协作式取消(本机即时;跨副本经 durable flag + 心跳)→ failed + errorCode `cancelled` |
146
- | `GET /v1/tasks` · `/:id/turns` · `/:id/stream` · `/:id/artifacts` | ✅ **Task Trace API(S1)**:CC 式轨迹 UI;`authToken` 或只读 `TRACE_TOKEN`(舰队级) |
147
- | `GET /v1/tasks/source-summary` | ✅ 按 (来源,状态) COUNT 的用量汇总 |
148
- | `POST /v1/leader` · `GET /v1/leader/:id` | ✅ **v2 leader 编排器**(异步;仅 `LEADER_ENABLED`)——见 [`docs/ORCHESTRATION-STATUS.md`](docs/ORCHESTRATION-STATUS.md) |
149
- | `GET /v1/approvals` | ✅ **F4**:operator 待审队列(operator RBAC = `OPERATOR_PRINCIPALS`);仅当审批/durable 开启时有意义 |
150
- | `GET /v1/approvals/:id` | ✅ 单条审批状态 |
151
- | `POST /v1/approvals/:id` | ✅ operator 批/否:`{decision:"approve"\|"deny", reason?}`;CAS,重复决议 → `409` |
152
- | `POST /v1/sessions/:id/wake` | ✅ 501 *by design*:无需显式 wake——用同 `sessionId` 再发任务即自动恢复(并 reconcile) |
153
- | `GET /v1/sessions/:id`(审计回溯) | ✅ 返回当前上下文 + 摘要(floor 有界窗口,非全量逐条);owner 校验 |
154
-
155
- > **F4 人工确认闸**:`APPROVAL_REQUIRE=delete_order,...` 配置需审批的工具名;命中的工具调用挂起,**待审状态落 TiDB**,任意实例的 operator 批复都能解开它(异步 run + LB 下决策与运行常不在同一实例);任务到 deadline 自动释放(deny)。`approve` 的 OA 接线见 `src/main.ts` 的 `resolveSpec`。
156
-
157
- > **异步 vs 同步**:`/v1/runs` 是无状态多实例的正路(长跑/自治、断线重连、崩溃不丢);`/v1/tasks*` 保留给短轮、要逐 token 即时反馈的场景。异步路径的文本流是 **turn 粒度**(delta 合并);跨实例逐 token 直播需共享低延迟总线(Redis Stream),暂缓。
158
-
159
- ## 重要:工具/MCP/策略 由部署方注入
160
- 请求体只带内容(`objective/sessionId/images`),**model、tools、以及安全策略由服务端 `resolveSpec`(见 `src/main.ts`)注入**——
161
- 工具的 `execute` 是函数,不过网络。在那里注入:
162
- - `tools`:`createSqlTool({ query: mysqlQuery(只读TiDB池) })`、任务级 `mcp`、`skills`。
163
- - `toolPolicy`(core 1.0):**高危写操作的人工确认闸**就是它——`createApprovalPolicy({ requireApproval:["delete_*"], approve: 接OA审批 })`,
164
- `approve` 是 async,把 promise 挂到 OA 审批回调即可(`limits.timeoutSec` 兜底)。**这条等于把 ROADMAP P0-6 从"自研"降级为"接线"。**
165
- - `promptProvider`(core 1.1):一个 Runner 服务多场景时,**按任务热插拔整套 harness 提示词**(如审查/客服/数据分析各一套)。
166
- - 凭据(DB 池、token)只活在服务端闭包里,**不进模型、不进请求体、不进沙箱**。
167
-
168
- ## 能力总览(已落地,core 依赖 `^1.99.1`,service `1.1.0`)
169
-
170
- P0-MVP 早就完成;现在是成熟期 + v2 编排期。详细 env/用法见 [`USAGE.md`](USAGE.md) 与 [`docs/SERVICE-AI-GUIDE.md`](docs/SERVICE-AI-GUIDE.md),逐项设计依据见 `design/`。
171
-
172
- - **持久化(跨副本)**:TiDB L1 session(F1 reconcile + F2 CAS)/ L2 记忆 / 异步 run 注册表 + 可重放事件日志(S1/S2)/ warm 会话缓存。无状态副本 + nginx LB 横向扩。
173
- - **多租户安全**:S6 owner 隔离;`REQUIRE_PRINCIPAL`;operator RBAC(`OPERATOR_PRINCIPALS`)守 F4 审批队列。
174
- - **韧性(全 opt-in)**:分级超时(connect/first-token/idle)+ 断路器 + failover + 反应式降级;断路器状态跨副本共享(TiDB)。
175
- - **成本治理**:每任务 `maxCostUsd`/`maxTokens` 上限、每 principal 跨副本累计配额、近预算前瞻降级、`/metrics` 权威 spend;**每模型定价**(`MODEL_COST_*`,USD/1M tokens → 真实 `costUsd`);请求限流跨副本(软)。
176
- - **多模型**:角色册 + `@-model`;**per-model key**(sema-registry `apiKeyEnv` → `getApiKeyAndHeaders`);质量门 **cascade**(便宜→强)、开发者 **verify** 门;**生成调参透传**(core 1.60 `Model.extraBody`,`MODEL_FREQUENCY_PENALTY`/`MODEL_PRESENCE_PENALTY`/`MODEL_EXTRA_BODY` — 源头压退化循环)。
177
- - **记忆**:core 文件记忆引擎(design/138 注入式:materialize→文件操作→harvest 门;`# Memory` 指令 + 派生索引,无 remember/recall 工具)——记忆就是模型的普通文件技能;单用户默认开(`MEMORY_ENGINE=off` 关)。
178
- - **大工具结果落盘**:durable `TiDBToolResultStore`(跨副本 wake 取回全文;TTL 回收)。
179
- - **可观测**:Prometheus `/metrics` + 可选 OTLP 导出;**`/metrics/summary`** 精炼健康 JSON(给 sema-registry Fleet 卡片,`METRICS_TOKEN` 只读门禁,与业务同端口 :8090)。退化任务 core 回 `salvagedOutput` + `errorCode="output.degenerate"`(整段打捞,非裁尾)。
180
- - **控制面**:`sema-registry`(控制面仓) 集中管理模型/角色/团队(`SEMA_REGISTRY_*` env 族,`DRY_RUN` 安全灰度;env 兜底;旧名 `CONFIG_CENTER_*` 仍兼容回退)。
181
- - **场景/能力**:`default` / `code-review`(direct/council/debate,镜头子 agent **代码驱动**,见 `design/35`)/ `scan`(中性只读 repo)/ `oa` / `team`;sema-registry 可声明组合场景。
182
- - **远端执行 Hands(可选,`REMOTE_EXEC`)**:`e2b`(Firecracker VM,默认 code-agent worker,可挂起)/ `k8s`(Kata pod,自托管;配 MinIO 可工作区快照挂起)/ `ssh`(真机,HITL 门控)/ `adb`(真机/真设备,App 测试);+ 可选 **LSP sidecar**(`LSP_ENABLED`)。
183
- - **v2 leader 编排器(`LEADER_ENABLED`,默认关)**:难度路由 → 扇出隔离 worker → 3-way merge + **隐藏 oracle 正确性门(B-2)** + 有界集成修复(B-1)→ Coordinator force-with-lease push;replan-lite 自恢复、资源切片挂起/续跑、belt-diff 打捞。已 live 跑通完整自治闭环(auto2/auto3)。见 [`docs/ORCHESTRATION-STATUS.md`](docs/ORCHESTRATION-STATUS.md)。
184
-
185
- 剩余前瞻见 [`docs/ROADMAP.md`](docs/ROADMAP.md)(最新)+ `design/30+`(历史)。
186
-
187
- ## 参考:core 仓库重要文档(架构依据)
188
-
189
- 本服务的架构/设计依据都在 core 仓库,建议接手前先读:
190
-
191
- - **设计入口/开放问题**:`design/00 设计索引与开放问题`(core 仓 `design/00-设计索引与开放问题.md`)(术语/已定决策/开放问题)
192
- - **服务化(Managed Agents 三平面)**:`design/02 服务化路线图`(core 仓 `design/02-服务化路线图.md`)(部署拓扑 + 服务契约)
193
- - **记忆与上下文**:`design/03 记忆与上下文架构`(core 仓 `design/03-记忆与上下文架构.md`)(L0-L3 多层记忆)
194
- - **双仓拆分 / core 路线图 / 谁改谁**:`design/04`(core 仓 `design/04-双仓拆分与core路线图.md`)
195
- - **1.0 完整设计 / 抽象层**:`design/06 core-1.0设计`(core 仓 `design/06-core-1.0设计.md`)(六个注入 seam + 注入/覆盖语义)
196
- - **core 用法/API/安全契约/零配置默认表**:`README`(core 仓 `README.md`) · **变更**:`CHANGELOG`(core 仓 `CHANGELOG.md`)
197
-
198
- ### 一手调研(蒸馏期,做 P1/P2 时的底层依据)
199
- core 仓库 `research/` 是从 openclaw 蒸馏时的原始调研,接手 service 的高阶能力时直接参考:
200
- - **执行环境分离**(做 P2 远程/沙箱 Hands SSH/Docker 时):`research/07 执行环境分离`(core 仓 `research/07-执行环境分离.md`)
201
- - **LLM provider 与 native 工具**(做 P1 多 provider/failover 时):`research/04`(core 仓 `research/04-LLM-provider与native工具.md`)
202
- - **session 与内存化**(TiDB 中心的语义依据):`research/05`(core 仓 `research/05-session与内存化.md`) · **自动压缩/裁剪**:`research/06`(core 仓 `research/06-自动压缩与裁剪.md`)
203
- - **subagent/team/mcp**(做 P2 orchestrator 蜂群时):`research/08`(core 仓 `research/08-subagent-team-mcp.md`) · **调研总览**:`research/00`(core 仓 `research/00-总览与阅读指南.md`)
204
-
205
- ### 怎么实现 TiDB 后端(core 已给出接法)
206
- - **Session 中心**:实现 core 的 `SessionStore`;底层 `extends BaseSessionStorage`(override `appendEntry`/`setLeafId` 落 TiDB)→ `new Session(storage)`;`acquire` 从事件日志重建(= wake)。core 的 `test/sessions.test.ts` 有完整 "DB rehearsal + wake" 范例。
207
- - **记忆**:不走 DB——design/138 文件记忆引擎(`RunnerDeps.memoryBackend`,单用户文件基座);旧 `MemoryStore`/`memory` 表已退役(`scripts/drop-memory-tables.sql`)。
99
+ - **Distribution coordinates**: npm = [`@sema-agent/server`](https://www.npmjs.com/package/@sema-agent/server)
100
+ (public on npmjs) · images = `ghcr.io/sema-agent/sema-server` + `docker.io/claybobby/sema-server`
101
+ (both public; `:latest` rolling, `:<sha>` pinned).
102
+ - **Bundled binaries**: the package ships two `bin` entries — `run-local` (single-machine local
103
+ runner) and `sema-up` (deployment bootstrap script).
104
+ - **Full-stack, one command** (DB + object store + registry web + sandbox pool; Docker and k8s
105
+ paths): [`sema-agent/sema-deploy`](https://github.com/sema-agent/sema-deploy).
106
+ - **Sandbox package sources**: default = official upstreams (pypi/npmjs/crates.io/…). For
107
+ deployments in mainland China set `SANDBOX_PKG_SOURCE=cn` (tuna/npmmirror/rsproxy/aliyun
108
+ mirrors); for custom mirrors use `SANDBOX_PKG_SOURCE=custom` plus explicit
109
+ `SEMA_*_MIRROR/INDEX/REGISTRY` URLs.
110
+
111
+ ## Configuration
112
+
113
+ The server is configured entirely through environment variables. The most important ones:
114
+
115
+ | Variable | Default | What it does |
116
+ |----------|---------|--------------|
117
+ | `PORT` | `8090` | HTTP listen port |
118
+ | `MODEL_GATEWAY_BASEURL` | `http://127.0.0.1:8000/v1` | OpenAI-compatible gateway base URL (without `/chat/completions`) |
119
+ | `MODEL_ID` | `Qwen3.5-35B` | Default model id |
120
+ | `MODEL_API_KEY` | — | Gateway API key (optional) |
121
+ | `SERVICE_AUTH_TOKEN` | — | Callers must send `Authorization: Bearer <token>` |
122
+ | `DB_BACKEND` | `mysql` | SQL engine: `mysql` (any MySQL-protocol DB: MySQL/TiDB/MariaDB; `tidb` is an alias) / `pg` (PostgreSQL) / `local` (file-backed, no DB). Setting `mysql`/`pg` explicitly also switches sessions to durable |
123
+ | `SESSION_BACKEND` | `memory`* | `memory` / `mysql` (durable session center; `tidb` alias) / `auto`. *Defaults to durable when `DB_BACKEND` is explicitly `mysql`/`pg` |
124
+ | `REMOTE_EXEC` | unset | Sandbox execution lane: `host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb`; unset = in-process stub (with `CONFIG_PROVIDER=local` the default becomes `host`) |
125
+ | `CONFIG_PROVIDER` | unset | Config source: `local` (file-backed `config.d/`, single machine) / `remote` (registry control plane) |
126
+ | `DEFAULT_SCENARIO` | `code` | Default scenario when the request body names none |
127
+ | `SANDBOX_PKG_SOURCE` | `global` | Package sources inside sandboxes: `global` (official upstreams) / `cn` (China mirrors) / `custom` / `none` |
128
+ | `SENSITIVE_WRITE_PATTERNS` | core's recommended set | Sensitive-path write deny list; comma-separated value replaces the set, `off` disables |
129
+ | `MODEL_CONNECT_TIMEOUT_MS` | `30000` | Gateway connect timeout |
130
+ | `MODEL_FIRST_TOKEN_TIMEOUT_MS` | `120000` | First-token timeout |
131
+ | `MODEL_IDLE_TIMEOUT_MS` | `300000` | Mid-stream idle timeout (`0` = off) |
132
+ | `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` (structured JSON logs) |
133
+
134
+ The full surface — cost/quota ceilings, circuit breaker and failover, multi-model roles, approval
135
+ gates, observability (Prometheus `/metrics` + optional OTLP), registry control plane, per-lane
136
+ sandbox settings — is documented in [`USAGE.md`](USAGE.md).
137
+
138
+ ## HTTP API overview
139
+
140
+ One row per endpoint family (not exhaustive):
141
+
142
+ | Endpoint family | What it serves |
143
+ |-----------------|----------------|
144
+ | `GET /health` · `GET /metrics` | Liveness + Prometheus metrics (`/metrics/summary`, `/metrics/plan-cache`) |
145
+ | `GET /v1/capabilities` | Deployment capability discovery — what this deployment can actually do, so clients never probe 501s |
146
+ | `GET /v1/models` | Model catalog (names only; no gateway URLs or keys) |
147
+ | `POST /v1/tasks` · `/v1/tasks/stream` | Synchronous task execution; SSE variant streams typed `TaskEvent`s token by token |
148
+ | `POST /v1/runs` · `GET /v1/runs/:id` | Asynchronous runs: immediate `202`, background execution, poll for status/result |
149
+ | `GET /v1/runs/:id/events` | Replayable SSE (`Last-Event-ID` resume); any replica can serve any run |
150
+ | `POST /v1/runs/:id/cancel` / `steer` / `compact` · `/v1/runs/:id/subagents/:target/steer` / `resume` | Run control verbs: cooperative cancel, mid-run steering, context compaction, sub-agent steering/resume |
151
+ | `/v1/approvals` (list · get · decide · stream) | Human-in-the-loop approval center backed by durable checkpoints; decisions from any replica |
152
+ | `/v1/sessions` (list · get · fork · init · settings · wake) | Session listing/search, audit inspection, fork, startup bundle |
153
+ | `/v1/workflows` (list · get · stream · agents/:label/steer) | Deterministic workflow orchestration runs with live streams and per-agent steering |
154
+ | `GET /v1/usage` · `GET /v1/policy` | Cumulative spend (when quotas are configured) and effective policy read surface |
155
+
156
+ ## Ecosystem
157
+
158
+ | Repository | What it is |
159
+ |------------|------------|
160
+ | [sema-agent/sema](https://github.com/sema-agent/sema) | The `sema` CLI portal — your own Claude Code-grade agent: terminal, web, your cloud |
161
+ | [sema-agent/sema-core](https://github.com/sema-agent/sema-core) | The agent engine, as a library — published as [`@sema-agent/core`](https://www.npmjs.com/package/@sema-agent/core) |
162
+ | [sema-agent/sema-sdk](https://github.com/sema-agent/sema-sdk) | Official TypeScript SDK for this server (`@sema-agent/sdk`) |
163
+ | [sema-agent/sema-deploy](https://github.com/sema-agent/sema-deploy) | One-command deployment — docker compose or k8s (helm), single machine to multi-node HA |
164
+ | [sema-agent/sema-web](https://github.com/sema-agent/sema-web) | Self-hosted web console + registry/config center + orchestrator |
165
+
166
+ ## Versioning
167
+
168
+ 1.x is a fast-iteration line: **breaking changes may land in minor versions** (tracked in
169
+ [`MIGRATION.md`](MIGRATION.md)). Production deployments should pin an exact version
170
+ (e.g. `@sema-agent/server@1.214.1`). Strict semver starts with 2.0 after GA.
171
+
172
+ ## License
173
+
174
+ [BUSL-1.1](LICENSE) (Business Source License):
175
+
176
+ - **Free** for personal, educational, research, and non-commercial production use.
177
+ - **Commercial production use requires a commercial license** from the licensor.
178
+ - **Converts to Apache-2.0 on 2030-07-13.**
179
+
180
+ Published copies at version ≤ 1.180.1 remain under the MIT terms they shipped with.
package/README.zh-CN.md ADDED
@@ -0,0 +1,176 @@
1
+ <div align="center">
2
+
3
+ # @sema-agent/server
4
+
5
+ **Sema 技术栈的服务端/API 层 —— 装配引擎,服务舰队。**
6
+
7
+ [![npm](https://img.shields.io/npm/v/%40sema-agent%2Fserver)](https://www.npmjs.com/package/@sema-agent/server)
8
+ [![license: BUSL-1.1](https://img.shields.io/badge/license-BUSL--1.1-blue)](#许可协议)
9
+
10
+ [快速开始](#快速开始) · [配置](#配置) · [HTTP API](#http-api-概览) · [生态导航](#生态导航) · [许可协议](#许可协议)
11
+
12
+ [English](./README.md)
13
+
14
+ </div>
15
+
16
+ ---
17
+
18
+ ## 它是什么
19
+
20
+ `@sema-agent/server` 是 Sema 的服务端/API 实现层:把
21
+ [`@sema-agent/core`](https://www.npmjs.com/package/@sema-agent/core) 引擎、registry 配置、
22
+ 模型网关与云端 agent 执行能力,装配到一套 HTTP/SSE 契约后面。
23
+
24
+ **它是:**
25
+
26
+ - **一个 HTTP/SSE 服务端 + 装配层。** 请求体只带内容(`objective`、`sessionId`、`scenario` 等);
27
+ 服务端按任务装配其余一切 —— 工具、子智能体角色册、提示词、skill、策略 ——
28
+ 身份/会话/安全策略由服务端注入,不信 body。凭据只活在服务端闭包里,
29
+ 不进请求体、不进模型、不进沙箱。
30
+ - **无状态设计。** 副本是 cattle:`docker run` 即起一个,挂在负载均衡后想开多少开多少。
31
+ 持久化状态 —— 会话、run、可重放事件日志、检查点、审批 —— 全在外部 SQL 存储
32
+ (任何 MySQL 协议数据库:MySQL/TiDB/MariaDB,或 PostgreSQL;单机场景另有文件持久化的
33
+ `local` 模式)。任意副本都能服务任意 run 的事件流;任务可以在一个副本上挂起、在另一个副本上恢复。
34
+ - **完整的服务端能力面**(可在 `GET /v1/capabilities` 发现):
35
+ 异步 run + 可重放 SSE、持久化检查点 + 人工审批(HITL)、会话与长期记忆、
36
+ 一份镜像服务多场景、任务级子智能体、确定性 workflow 编排,以及可插拔的沙箱执行通道
37
+ (`host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb`)。
38
+
39
+ **它不是:**
40
+
41
+ - **不是引擎本体。** agent 循环、工具 harness、记忆与检查点机制在
42
+ [`sema-core`](https://github.com/sema-agent/sema-core);本仓以 npm 依赖的方式消费它,
43
+ 自己出装配、后端与服务契约。
44
+ - **不是 CLI。** 终端智能体是 [`sema`](https://github.com/sema-agent/sema);它(以及网页端)
45
+ 都是本服务的客户端。
46
+ - **不是部署工具。** 一键自托管部署(Docker 单机或 Kubernetes)在
47
+ [`sema-deploy`](https://github.com/sema-agent/sema-deploy)。
48
+ - **不是持久化中心。** 真相在外部数据库里;服务进程随时可弃。
49
+
50
+ ## 架构
51
+
52
+ <!-- TODO: 架构 SVG —— 视觉资产归门户仓(sema-agent/sema);下面是文字版。 -->
53
+
54
+ <details>
55
+ <summary>文字版</summary>
56
+
57
+ ```
58
+ HTTP / SSE API 面 装配层 执行通道
59
+ ──────────────── ────── ────────
60
+ /v1/tasks (同步) ──┐ ┌─ 任务级 spec 装配 ─┐ ┌─ host (本机直跑)
61
+ /v1/runs (异步) ──┤ │ 场景 · skill │ ├─ local-docker (任务级容器)
62
+ /v1/sessions ──┼──▶│ 策略 · 审批门 │──▶├─ e2b (Firecracker VM)
63
+ /v1/approvals ──┤ │ registry 配置 │ ├─ k8s (Kata pod 沙箱)
64
+ /v1/workflows ──┘ │ 模型网关 │ └─ ssh / adb (真机 / 真设备)
65
+ └─ @sema-agent/core ─┘
66
+ │
67
+ 持久化存储(MySQL/TiDB · PostgreSQL · 本地文件)
68
+ 会话 · run · 事件日志 · 检查点 · 审批
69
+ ```
70
+
71
+ </details>
72
+
73
+ ## 快速开始
74
+
75
+ 环境要求:Node ≥ 20(npm 路径)+ 一个 OpenAI 兼容模型网关。
76
+
77
+ ```bash
78
+ # A) npm
79
+ npm install @sema-agent/server
80
+ MODEL_GATEWAY_BASEURL=https://api.deepseek.com MODEL_ID=deepseek-chat \
81
+ MODEL_API_KEY=<你的-key> SERVICE_AUTH_TOKEN=<自定> \
82
+ node node_modules/@sema-agent/server/dist/main.js # → :8090
83
+
84
+ # B) 容器(零依赖,匿名可拉)
85
+ docker run -p 8090:8090 \
86
+ -e MODEL_GATEWAY_BASEURL=https://api.deepseek.com -e MODEL_ID=deepseek-chat \
87
+ -e MODEL_API_KEY=<你的-key> -e SERVICE_AUTH_TOKEN=<自定> \
88
+ ghcr.io/sema-agent/sema-server:latest # 或 docker.io/claybobby/sema-server:latest
89
+
90
+ # 提交一个任务
91
+ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>" \
92
+ -H 'content-type: application/json' -d '{"objective":"用一句话回答:1+1 等于几?"}'
93
+ # 带指定模型:body 加 "model":"<catalog id>";可用能力见 GET /v1/capabilities
94
+ ```
95
+
96
+ - **分发坐标**:npm = [`@sema-agent/server`](https://www.npmjs.com/package/@sema-agent/server)
97
+ (npmjs 公开)· 镜像 = `ghcr.io/sema-agent/sema-server` + `docker.io/claybobby/sema-server`
98
+ (均 public,`:latest` 滚动 / `:<sha>` 钉版)。
99
+ - **随包二进制**:包内带两个 `bin` —— `run-local`(单机本地 runner)与
100
+ `sema-up`(部署引导脚本)。
101
+ - **一键全栈部署**(DB + 对象存储 + registry 网站 + 沙箱池,docker/k8s 双路径):
102
+ [`sema-agent/sema-deploy`](https://github.com/sema-agent/sema-deploy)。
103
+ - **沙箱装包源**:缺省 = 官方源(pypi/npmjs/crates.io/…)。中国大陆部署配
104
+ `SANDBOX_PKG_SOURCE=cn` 切国内镜像源(tuna/npmmirror/rsproxy/aliyun),自定义源用
105
+ `SANDBOX_PKG_SOURCE=custom` + `SEMA_*_MIRROR/INDEX/REGISTRY` 显式 URL。
106
+
107
+ ## 配置
108
+
109
+ 服务完全由环境变量配置。最核心的一批:
110
+
111
+ | 变量 | 默认 | 说明 |
112
+ |------|------|------|
113
+ | `PORT` | `8090` | HTTP 监听端口 |
114
+ | `MODEL_GATEWAY_BASEURL` | `http://127.0.0.1:8000/v1` | OpenAI 兼容网关地址(不带 `/chat/completions`) |
115
+ | `MODEL_ID` | `Qwen3.5-35B` | 缺省模型 id |
116
+ | `MODEL_API_KEY` | — | 网关 key(可选) |
117
+ | `SERVICE_AUTH_TOKEN` | — | 调用方需带 `Authorization: Bearer <token>` |
118
+ | `DB_BACKEND` | `mysql` | SQL 引擎:`mysql`(任何 MySQL 协议库:MySQL/TiDB/MariaDB;`tidb` 为兼容别名)/ `pg`(PostgreSQL)/ `local`(免 DB 文件持久化)。显式设置 `mysql`/`pg` 时 session 自动转 durable |
119
+ | `SESSION_BACKEND` | `memory`* | `memory` / `mysql`(durable 会话中心;`tidb` 别名)/ `auto`。*显式 `DB_BACKEND=mysql/pg` 时默认转 durable |
120
+ | `REMOTE_EXEC` | 未设 | 沙箱执行通道:`host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb`;未设 = 进程内 stub(`CONFIG_PROVIDER=local` 时缺省转 `host`) |
121
+ | `CONFIG_PROVIDER` | 未设 | 配置来源:`local`(单机文件 `config.d/`)/ `remote`(registry 控制面) |
122
+ | `DEFAULT_SCENARIO` | `code` | 请求体未指定场景时的缺省场景 |
123
+ | `SANDBOX_PKG_SOURCE` | `global` | 沙箱内装包源:`global`(官方源)/ `cn`(国内镜像)/ `custom` / `none` |
124
+ | `SENSITIVE_WRITE_PATTERNS` | core 推荐集 | 敏感路径写拒集;逗号分隔值为整体替换,`off` 关闭 |
125
+ | `MODEL_CONNECT_TIMEOUT_MS` | `30000` | 网关连接超时 |
126
+ | `MODEL_FIRST_TOKEN_TIMEOUT_MS` | `120000` | 首 token 超时 |
127
+ | `MODEL_IDLE_TIMEOUT_MS` | `300000` | 流中 idle 超时(`0` 关) |
128
+ | `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error`(结构化 JSON 日志) |
129
+
130
+ 完整配置面 —— 成本/配额上限、断路器与 failover、多模型角色、审批门、可观测
131
+ (Prometheus `/metrics` + 可选 OTLP)、registry 控制面、各沙箱通道细项 ——
132
+ 见 [`USAGE.md`](USAGE.md)。
133
+
134
+ ## HTTP API 概览
135
+
136
+ 一行一个端点族(非全量):
137
+
138
+ | 端点族 | 服务什么 |
139
+ |--------|----------|
140
+ | `GET /health` · `GET /metrics` | 存活探针 + Prometheus 指标(`/metrics/summary`、`/metrics/plan-cache`) |
141
+ | `GET /v1/capabilities` | 部署能力发现 —— 本部署真正能做什么,客户端免 501 探测 |
142
+ | `GET /v1/models` | 模型目录(仅名字,不含网关 URL/key) |
143
+ | `POST /v1/tasks` · `/v1/tasks/stream` | 同步任务执行;SSE 变体逐 token 流式输出类型化 `TaskEvent` |
144
+ | `POST /v1/runs` · `GET /v1/runs/:id` | 异步 run:立即 `202`,后台续跑,轮询状态/结果 |
145
+ | `GET /v1/runs/:id/events` | 可重放 SSE(`Last-Event-ID` 续订);任意副本可服务任意 run |
146
+ | `POST /v1/runs/:id/cancel` / `steer` / `compact` · `/v1/runs/:id/subagents/:target/steer` / `resume` | run 控制动词:协作式取消、运行中转向、上下文压缩、子智能体转向/恢复 |
147
+ | `/v1/approvals`(list · get · decide · stream) | 人工审批中心,底座是持久化检查点;任意副本都能批复 |
148
+ | `/v1/sessions`(list · get · fork · init · settings · wake) | 会话列表/检索、审计回溯、fork、启动包 |
149
+ | `/v1/workflows`(list · get · stream · agents/:label/steer) | 确定性 workflow 编排 run,带实时流与逐 agent 转向 |
150
+ | `GET /v1/usage` · `GET /v1/policy` | 累计花费(配置配额时)与生效策略只读面 |
151
+
152
+ ## 生态导航
153
+
154
+ | 仓库 | 是什么 |
155
+ |------|--------|
156
+ | [sema-agent/sema](https://github.com/sema-agent/sema) | `sema` CLI 门户 —— 属于你自己的 Claude Code 级智能体:终端、网页、你的云 |
157
+ | [sema-agent/sema-core](https://github.com/sema-agent/sema-core) | 智能体引擎,以库的形式发布 —— [`@sema-agent/core`](https://www.npmjs.com/package/@sema-agent/core) |
158
+ | [sema-agent/sema-sdk](https://github.com/sema-agent/sema-sdk) | 本服务的官方 TypeScript SDK(`@sema-agent/sdk`) |
159
+ | [sema-agent/sema-deploy](https://github.com/sema-agent/sema-deploy) | 一键部署 —— docker compose 或 k8s(helm),单机到多机 HA |
160
+ | [sema-agent/sema-web](https://github.com/sema-agent/sema-web) | 自托管网页控制台 + registry/配置中心 + orchestrator |
161
+
162
+ ## 版本策略
163
+
164
+ 1.x = 快速迭代期:**BREAKING 变更可能落在 minor**(记录于
165
+ [`MIGRATION.md`](MIGRATION.md))。生产部署请锁精确版本
166
+ (如 `@sema-agent/server@1.214.1`);GA 后切 2.0 起严格 semver。
167
+
168
+ ## 许可协议
169
+
170
+ [BUSL-1.1](LICENSE)(Business Source License):
171
+
172
+ - 个人、教育、研究及非商业生产使用 **免费**。
173
+ - **商业生产使用需要商业授权**。
174
+ - **2030-07-13 起自动转为 Apache-2.0。**
175
+
176
+ ≤ 1.180.1 的已发布副本仍受其发布时的 MIT 约束。
package/deploy/sema-up/README.md CHANGED
@@ -95,7 +95,7 @@ data-center:2c/2G/20G)以下 BLOCK——确实无法稳定部署,提前警告不
95
95
  ## 镜像从哪来
96
96
 
97
97
  - **server**:`SEMA_SERVER_IMAGE`(`ghcr.io/sema-agent/sema-server:<tag>`,public 匿名可拉;
98
- CN 兜底=内网 Gitea 仓。SWR 已弃用 2026-07-13)。
98
+ CN 兜底=自建镜像 registry。SWR 已弃用)。
99
99
  - **registry**:`SEMA_REGISTRY_IMAGE`(GHCR/Hub 的 `sema-registry` 镜像,迁移中,公开仓匿名可拉;
100
100
  SWR 已弃用;仅换 private 仓时才需 k8s 路径凭据=env `IMAGE_PULL_USER`/`IMAGE_PULL_TOKEN`)。
101
101
  - 公共镜像(postgres/minio/gitea)直接拉;国内网络不通时配 dockerd `registry-mirrors`。