@sema-agent/server 1.185.0

package/LICENSE

@@ -0,0 +1,102 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             clay (github.com/clayboby)
+Licensed Work:        @sema-ai/server (sema-server)
+                      The Licensed Work is (c) 2026 clay.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      personal, educational, research, or other
+                      non-commercial purposes. Commercial production use
+                      requires a commercial license from the Licensor.
+Change Date:          2030-07-13
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact the Licensor.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Third-party notices
+
+Versions of this package up to and including 1.180.1 were published under the
+MIT License; those published copies remain governed by the license they were
+distributed under.

package/README.md

@@ -0,0 +1,207 @@
+# @sema-agent/server
+
+**Sema Server** 是 Sema 的服务端/API 实现层 —— 连接 core、registry、模型 provider、以及云端 agent 运行能力。
+
+## 快速开始(公开分发)
+
+```bash
+# A) npm(需 node 22+)
+npm install @sema-agent/server
+MODEL_GATEWAY_BASEURL=https://api.deepseek.com MODEL_ID=deepseek-chat \
+  MODEL_API_KEY=<你的-key> SERVICE_AUTH_TOKEN=<自定> \
+  node node_modules/@sema-agent/server/dist/main.js        # → :8090
+
+# B) 容器(零依赖,匿名可拉)
+docker run -p 8090:8090 \
+  -e MODEL_GATEWAY_BASEURL=https://api.deepseek.com -e MODEL_ID=deepseek-chat \
+  -e MODEL_API_KEY=<你的-key> -e SERVICE_AUTH_TOKEN=<自定> \
+  ghcr.io/clayboby/sema-server:latest              # 或 docker.io/claybobby/sema-server:latest
+
+# 提交一个任务
+curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>" \
+  -H 'content-type: application/json' -d '{"objective":"用一句话回答:1+1 等于几?"}'
+# 带指定模型:body 加 "model":"<catalog id>";可用模型见 GET /v1/capabilities
+```
+
+- **一键部署**(DB+MinIO+registry 网站+沙箱池,docker/k8s 双路径):独立仓
+  [`clayboby/sema-deploy`](https://github.com/clayboby/sema-deploy)。
+- **分发坐标**:npm=`@sema-agent/server`(npmjs 公开)· 镜像=`ghcr.io/clayboby/sema-server` +
+  `docker.io/claybobby/sema-server`(均 public,`:latest` 滚动 / `:<sha>` 钉版)。
+- **版本策略**:1.x=快速迭代期,BREAKING 变更可能落在 minor(见 [`MIGRATION.md`](MIGRATION.md))——
+  **生产部署请锁精确版本**(`@sema-agent/server@1.184.0`);GA 后切 2.0 起严格 semver。
+- **许可**:[BUSL-1.1](LICENSE)(个人/教育/研究/非商用生产随意;**商用生产需商业授权**;
+  2030-07-13 起自动转 Apache-2.0)。≤1.180.1 的已发布副本仍受其发布时的 MIT 约束。
+- **沙箱装包源**:缺省=官方源(pypi/npmjs/crates.io/…,海外为准)。中国大陆部署配
+  `SANDBOX_PKG_SOURCE=cn` 切国内镜像源(tuna/npmmirror/rsproxy/aliyun),自定义源用
+  `SANDBOX_PKG_SOURCE=custom` + `SEMA_*_MIRROR/INDEX/REGISTRY` 显式 URL。
+
+中心化、容器化的 **Managed-Agents 服务**,构建于 [`@sema-agent/core`](https://www.npmjs.com/package/@sema-agent/core)。
+
+- **它是什么**:一个**无状态的 runner 服务**(Brain 平面 + HTTP/SSE 契约)。`docker run` 即起一个,可多开。
+- **它不是什么**:不是持久化中心。**真相/记忆在外部 TiDB**(Session 事件日志 L1 + 长期记忆 L2)。容器是手脚,TiDB 是记忆。
+- 与 core 的关系:core 是 npm 依赖(出机制+接口),本仓出部署物+后端插件+服务契约。**两仓路线图分开维护**(见 `design/ROADMAP.md`)。
+
+> 架构依据(三平面解耦 brain/hands/session、多层记忆 L0-L3)见 core 仓库 `design/00-03`。
+
+> 🧭 **接手/最新真相(2026-06-15 架构师交叉验证)**:从代码反推、纠正了过时文档。先读 **[`HANDOFF.md`](HANDOFF.md)**(单一入口),它索引到:
+> [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)(架构+图)· [`docs/ROADMAP.md`](docs/ROADMAP.md)(前瞻路线)· [`docs/ORCHESTRATION-STATUS.md`](docs/ORCHESTRATION-STATUS.md)(编排矩阵+效果)·
+> [`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 台账)。
+> **当前版本 = service `1.1.0` / core `^1.99.1`**;**v2 leader 编排器已建成并接线**(`LEADER_ENABLED`,默认关),不再 HOLD。
+
+## 跑起来(本地 dev)
+
+```bash
+cp .npmrc.example .npmrc   # 填一个 read:package 的 Gitea token,用于装 @sema-agent/core
+npm install
+MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1 MODEL_ID=Qwen3.5-35B npm run dev
+# → POST /v1/tasks  ·  POST /v1/tasks/stream (SSE)  ·  GET /health
+```
+
+```bash
+curl -s localhost:8090/health
+curl -s localhost:8090/v1/tasks -H 'content-type: application/json' \
+  -d '{"objective":"用一句话自我介绍"}'
+```
+
+## Docker(运行时 = **Bun**)
+
+镜像用 Bun **直接跑 TypeScript**(无 build/transpile,冷启动快、无 dist)。token 仅在构建装依赖阶段用,**不进终镜像**(多阶段)。
+
+```bash
+# 直接 build/run
+docker build --build-arg GITEA_NPM_TOKEN=<read:package token> -t sema-server .
+docker run -p 8090:8090 \
+  -e MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1 -e MODEL_ID=Qwen3.5-35B \
+  -e DB_BACKEND=mysql -e MYSQL_HOST=... -e MYSQL_USER=... -e MYSQL_PASSWORD=... -e MYSQL_DATABASE=sema_server \
+  -e SERVICE_AUTH_TOKEN=xxx sema-server
+
+# 或 compose:一条命令起「LB + worker 集群」。OA 只认 LB 一个地址 http://<host>:8090
+GITEA_NPM_TOKEN=<read:package token> TIDB_HOST=... TIDB_USER=... TIDB_PASSWORD=... docker compose up --build
+docker compose up --build --scale service=4   # 4 个无状态 worker,nginx LB 扇发,TiDB 协调
+# 本地 throwaway TiDB:加 -e TIDB_HOST=tidb 并 `docker compose --profile localdb up --build`
+```
+
+> **拓扑**:没有单独的"中心化调度 API"。**中心化 = TiDB(数据)**;**统一入口 = LB(`deploy/nginx.conf`)**;worker 无状态可多开,跨 worker 靠 TiDB 协调(`task_active` 抢占防双跑、session CAS、事件日志重放、心跳+reaper),**无中央大脑**。任意 worker 都能服务任意 run 的 `/v1/runs/:id/events`(断线重连经 LB 落到别的 worker 也能接上)。
+
+> ⚠️ **大陆拉不动 Docker Hub**:基础镜像 `oven/bun:1-slim` 走 Docker Hub,大陆常连不上。三种解法:
+> 1. `--build-arg BUN_IMAGE=<镜像站>/oven/bun:1-slim`(或 compose:`BUN_IMAGE=… docker compose build`);
+> 2. 配 dockerd `registry-mirrors`,让 `oven/bun:1-slim` 自动走镜像站;
+> 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。脚本顶部有用法。
+
+CI:`.gitea/workflows/ci.yml`(Node 跑确定性测试 → 构建 Bun 镜像 → 推 Gitea registry)。
+> 镜像基底默认 `oven/bun:1-slim`(`ARG BUN_IMAGE` 可覆盖);要更小可换 `oven/bun:1-distroless`(无 shell,用编排层 `httpGet /health` 探针)或后续 `bun build --compile` 出单二进制(待验证)。
+
+## 配置(env)
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `PORT` | 8090 | 监听端口 |
+| `MODEL_GATEWAY_BASEURL` | http://127.0.0.1:8000/v1 | OpenAI 兼容网关(不带 /chat/completions) |
+| `MODEL_ID` | Qwen3.5-35B | 模型 id |
+| `MODEL_API_KEY` | — | 网关 key(可选) |
+| `DB_BACKEND` | mysql | SQL 引擎:`mysql`(任何 MySQL 协议库:MySQL/TiDB/MariaDB;`tidb` 为兼容别名)/ `pg`(PostgreSQL)/ `local`(免 DB 文件持久化)。**显式设置 mysql/pg 时 session 自动转 durable(2026-07-06 收编)** |
+| `SESSION_BACKEND` | memory* | `memory` / `mysql`(durable L1 中心;`tidb` 别名)/ `auto`(探测 DB host,连不上退 memory)。*显式 `DB_BACKEND=mysql/pg` 时默认转 durable |
+| `MEMORY_ENGINE` / `MEMORY_ENGINE_DIR` | on / `~/.ai-agent` | 长期记忆 = core 注入式**文件记忆引擎**(design/138;单用户默认开,`off` 显式关;多租户恒关)。旧 `MEMORY_BACKEND`/`EMBEDDING_*` SQL 记忆面已退役(数据不迁移,升级后跑 `scripts/drop-memory-tables.sql`) |
+| `MYSQL_HOST/PORT/USER/PASSWORD/DATABASE` | — | MySQL 协议连接(`TIDB_*` 同名别名仍认;缺省端口:MYSQL_HOST→3306,TIDB_HOST→4000) |
+| `SESSION_CACHE_TTL_SEC` | 300 | warm 缓存 idle TTL(需会话亲和);0 关 |
+| `SERVICE_AUTH_TOKEN` | — | 调用方需带 `Authorization: Bearer <token>` |
+| `PRINCIPAL_HEADER` / `REQUIRE_PRINCIPAL` | `x-agent-principal` / false | S6 身份头 / 多租户生产置 true |
+| `APPROVAL_REQUIRE` / `APPROVAL_DENY` / `APPROVAL_TIMEOUT_SEC` | — / — / 0 | F4 审批门控工具名 / 永拒 / 待审超时 |
+| `RATE_LIMIT_RPM` | 0 | 每 principal 每分钟请求上限(task/run 端点);0 关 |
+| `REAP_RUN_STALE_SEC` / `REAP_INTERVAL_SEC` | 120 / 60 | run 心跳超此判僵尸(须 > 30s 心跳;启动断言)/ reaper 周期 |
+| `LOG_LEVEL` | info | `debug`/`info`/`warn`/`error`(结构化 JSON 日志) |
+| `DEFAULT_SCENARIO` / `SKILLS_DIR` | default / skills | 缺省场景 / 烘焙 skill 目录 |
+| `SESSION_AUTO_TITLE` | true | session 自动起题(首次提交后用 cheap 档模型[`MODEL_CHEAP_ID`,未配则主模型]生成一次 title,每 session 一次调用;`false` 关) |
+| `GIT_API_BASEURL` / `GIT_API_TOKEN` | — | code-review 场景的只读 Git API(token 仅服务端) |
+| `CORS_ORIGIN` | — | 如 `https://oa.内网` |
+
+> **进阶 env(完整说明见 [`USAGE.md`](USAGE.md))**,按域分组:
+> - 成本/限额:`MAX_TASK_COST_USD` · `MAX_PRINCIPAL_COST_USD` · `MODEL_DEGRADE_TO`/`_AT_COST_FRACTION`/`_REACTIVE` · `MODEL_CASCADE_LADDER`
+> - 韧性:`MODEL_CONNECT_TIMEOUT_MS` · `MODEL_FIRST_TOKEN_TIMEOUT_MS` · `MODEL_IDLE_TIMEOUT_MS` · `MODEL_CIRCUIT_BREAKER`(+ 阈值)· `MODEL_GATEWAY_FALLBACK_URLS`
+> - 多模型:`MODEL_CHEAP_ID` · `MODEL_CODE_ROLES` · `ANTHROPIC_API_KEY`(云路由)
+> - 落盘/可观测:`TOOL_RESULT_TTL_SEC` · `OTEL_EXPORTER_OTLP_ENDPOINT`
+> - 安全/控制面:`OPERATOR_PRINCIPALS` · `SEMA_REGISTRY_URL`/`_TOKEN`/`_DRY_RUN`/`_WORKER`(新名,orchestrator 注入;旧名 `CONFIG_CENTER_*` 仍兼容回退)
+> - 远端执行(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))
+
+> **场景/能力层**:一份镜像服务多场景。请求体可带 `scenario`(默认 `DEFAULT_SCENARIO`),服务端按场景**装配一次**好的 {工具(含 subagent 角色册)+ 整套 harness 提示词 + skill};**身份/会话/策略仍服务端注入,不信 body**。
+> - `default`:`now` 等通用工具。
+> - `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)是后续扩展位。
+
+> **可观测**:`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 聚合。
+
+## 服务契约(当前 / 目标)
+
+| 端点 | 现状 |
+|------|------|
+| `GET /health` | ✅ |
+| `GET /metrics` · `/metrics/summary` · `/metrics/plan-cache` | ✅ Prometheus 文本 / 精炼健康 JSON(Fleet 卡片)/ plan-cache 复现率;`SERVICE_AUTH_TOKEN` **或**只读 `METRICS_TOKEN` |
+| `GET /v1/capabilities` | ✅ 部署能力发现(asyncRuns/artifacts/approvals/leader/memory/scenarios/version)——免 501 探测 |
+| `GET /v1/models` | ✅ `@-model` 目录(仅名字,不含 baseUrl/key) |
+| `POST /v1/tasks` | ✅ 同步:跑到结束返回 `TaskResult`(短轮对话用);支持 `verify`/`cascade` |
+| `POST /v1/tasks/stream` | ✅ 同步 SSE:逐 token 流式 `TaskEvent`(同实例) |
+| `POST /v1/runs` | ✅ **异步(S1)**:立即 `202 {taskId, sessionId, status}`,后台续跑;同 session 已有活跃 run → `409` |
+| `GET /v1/runs/:id` | ✅ run 状态 + 结果(轮询;owner 校验) |
+| `GET /v1/runs/:id/events` | ✅ **可重放 SSE(S2)**:`Last-Event-ID` 续订,任意实例可服务(事件在 TiDB);文本按 turn 粒度合并 |
+| `POST /v1/runs/:id/cancel` | ✅ 协作式取消(本机即时;跨副本经 durable flag + 心跳)→ failed + errorCode `cancelled` |
+| `GET /v1/tasks` · `/:id/turns` · `/:id/stream` · `/:id/artifacts` | ✅ **Task Trace API(S1)**:CC 式轨迹 UI;`authToken` 或只读 `TRACE_TOKEN`(舰队级) |
+| `GET /v1/tasks/source-summary` | ✅ 按 (来源,状态) COUNT 的用量汇总 |
+| `POST /v1/leader` · `GET /v1/leader/:id` | ✅ **v2 leader 编排器**(异步;仅 `LEADER_ENABLED`)——见 [`docs/ORCHESTRATION-STATUS.md`](docs/ORCHESTRATION-STATUS.md) |
+| `GET /v1/approvals` | ✅ **F4**:operator 待审队列(operator RBAC = `OPERATOR_PRINCIPALS`);仅当审批/durable 开启时有意义 |
+| `GET /v1/approvals/:id` | ✅ 单条审批状态 |
+| `POST /v1/approvals/:id` | ✅ operator 批/否:`{decision:"approve"\|"deny", reason?}`;CAS,重复决议 → `409` |
+| `POST /v1/sessions/:id/wake` | ✅ 501 *by design*:无需显式 wake——用同 `sessionId` 再发任务即自动恢复(并 reconcile) |
+| `GET /v1/sessions/:id`(审计回溯) | ✅ 返回当前上下文 + 摘要(floor 有界窗口,非全量逐条);owner 校验 |
+
+> **F4 人工确认闸**:`APPROVAL_REQUIRE=delete_order,...` 配置需审批的工具名;命中的工具调用挂起,**待审状态落 TiDB**,任意实例的 operator 批复都能解开它(异步 run + LB 下决策与运行常不在同一实例);任务到 deadline 自动释放(deny)。`approve` 的 OA 接线见 `src/main.ts` 的 `resolveSpec`。
+
+> **异步 vs 同步**:`/v1/runs` 是无状态多实例的正路(长跑/自治、断线重连、崩溃不丢);`/v1/tasks*` 保留给短轮、要逐 token 即时反馈的场景。异步路径的文本流是 **turn 粒度**(delta 合并);跨实例逐 token 直播需共享低延迟总线(Redis Stream),暂缓。
+
+## 重要:工具/MCP/策略 由部署方注入
+请求体只带内容(`objective/sessionId/images`),**model、tools、以及安全策略由服务端 `resolveSpec`(见 `src/main.ts`)注入**——
+工具的 `execute` 是函数,不过网络。在那里注入:
+- `tools`:`createSqlTool({ query: mysqlQuery(只读TiDB池) })`、任务级 `mcp`、`skills`。
+- `toolPolicy`(core 1.0):**高危写操作的人工确认闸**就是它——`createApprovalPolicy({ requireApproval:["delete_*"], approve: 接OA审批 })`,
+  `approve` 是 async,把 promise 挂到 OA 审批回调即可(`limits.timeoutSec` 兜底)。**这条等于把 ROADMAP P0-6 从"自研"降级为"接线"。**
+- `promptProvider`(core 1.1):一个 Runner 服务多场景时,**按任务热插拔整套 harness 提示词**(如审查/客服/数据分析各一套)。
+- 凭据(DB 池、token)只活在服务端闭包里,**不进模型、不进请求体、不进沙箱**。
+
+## 能力总览(已落地,core 依赖 `^1.99.1`,service `1.1.0`)
+
+P0-MVP 早就完成;现在是成熟期 + v2 编排期。详细 env/用法见 [`USAGE.md`](USAGE.md) 与 [`docs/SERVICE-AI-GUIDE.md`](docs/SERVICE-AI-GUIDE.md),逐项设计依据见 `design/`。
+
+- **持久化(跨副本)**:TiDB L1 session(F1 reconcile + F2 CAS)/ L2 记忆 / 异步 run 注册表 + 可重放事件日志(S1/S2)/ warm 会话缓存。无状态副本 + nginx LB 横向扩。
+- **多租户安全**:S6 owner 隔离;`REQUIRE_PRINCIPAL`;operator RBAC(`OPERATOR_PRINCIPALS`)守 F4 审批队列。
+- **韧性(全 opt-in)**:分级超时(connect/first-token/idle)+ 断路器 + failover + 反应式降级;断路器状态跨副本共享(TiDB)。
+- **成本治理**:每任务 `maxCostUsd`/`maxTokens` 上限、每 principal 跨副本累计配额、近预算前瞻降级、`/metrics` 权威 spend;**每模型定价**(`MODEL_COST_*`,USD/1M tokens → 真实 `costUsd`);请求限流跨副本(软)。
+- **多模型**:角色册 + `@-model`;**per-model key**(sema-registry `apiKeyEnv` → `getApiKeyAndHeaders`);质量门 **cascade**(便宜→强)、开发者 **verify** 门;**生成调参透传**(core 1.60 `Model.extraBody`,`MODEL_FREQUENCY_PENALTY`/`MODEL_PRESENCE_PENALTY`/`MODEL_EXTRA_BODY` — 源头压退化循环)。
+- **记忆**:core 文件记忆引擎(design/138 注入式:materialize→文件操作→harvest 门;`# Memory` 指令 + 派生索引,无 remember/recall 工具)——记忆就是模型的普通文件技能;单用户默认开(`MEMORY_ENGINE=off` 关)。
+- **大工具结果落盘**:durable `TiDBToolResultStore`(跨副本 wake 取回全文;TTL 回收)。
+- **可观测**:Prometheus `/metrics` + 可选 OTLP 导出;**`/metrics/summary`** 精炼健康 JSON(给 sema-registry Fleet 卡片,`METRICS_TOKEN` 只读门禁,与业务同端口 :8090)。退化任务 core 回 `salvagedOutput` + `errorCode="output.degenerate"`(整段打捞,非裁尾)。
+- **控制面**:`sema-registry`(控制面仓) 集中管理模型/角色/团队(`SEMA_REGISTRY_*` env 族,`DRY_RUN` 安全灰度;env 兜底;旧名 `CONFIG_CENTER_*` 仍兼容回退)。
+- **场景/能力**:`default` / `code-review`(direct/council/debate,镜头子 agent **代码驱动**,见 `design/35`)/ `scan`(中性只读 repo)/ `oa` / `team`;sema-registry 可声明组合场景。
+- **远端执行 Hands(可选,`REMOTE_EXEC`)**:`e2b`(Firecracker VM,默认 code-agent worker,可挂起)/ `k8s`(Kata pod,自托管;配 MinIO 可工作区快照挂起)/ `ssh`(真机,HITL 门控)/ `adb`(真机/真设备,App 测试);+ 可选 **LSP sidecar**(`LSP_ENABLED`)。
+- **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)。
+
+剩余前瞻见 [`docs/ROADMAP.md`](docs/ROADMAP.md)(最新)+ `design/30+`(历史)。
+
+## 参考:core 仓库重要文档(架构依据)
+
+本服务的架构/设计依据都在 core 仓库,建议接手前先读:
+
+- **设计入口/开放问题**:`design/00 设计索引与开放问题`(core 仓 `design/00-设计索引与开放问题.md`)(术语/已定决策/开放问题)
+- **服务化(Managed Agents 三平面)**:`design/02 服务化路线图`(core 仓 `design/02-服务化路线图.md`)(部署拓扑 + 服务契约)
+- **记忆与上下文**:`design/03 记忆与上下文架构`(core 仓 `design/03-记忆与上下文架构.md`)(L0-L3 多层记忆)
+- **双仓拆分 / core 路线图 / 谁改谁**:`design/04`(core 仓 `design/04-双仓拆分与core路线图.md`)
+- **1.0 完整设计 / 抽象层**:`design/06 core-1.0设计`(core 仓 `design/06-core-1.0设计.md`)(六个注入 seam + 注入/覆盖语义)
+- **core 用法/API/安全契约/零配置默认表**:`README`(core 仓 `README.md`) · **变更**:`CHANGELOG`(core 仓 `CHANGELOG.md`)
+
+### 一手调研(蒸馏期,做 P1/P2 时的底层依据)
+core 仓库 `research/` 是从 openclaw 蒸馏时的原始调研,接手 service 的高阶能力时直接参考:
+- **执行环境分离**(做 P2 远程/沙箱 Hands SSH/Docker 时):`research/07 执行环境分离`(core 仓 `research/07-执行环境分离.md`)
+- **LLM provider 与 native 工具**(做 P1 多 provider/failover 时):`research/04`(core 仓 `research/04-LLM-provider与native工具.md`)
+- **session 与内存化**(TiDB 中心的语义依据):`research/05`(core 仓 `research/05-session与内存化.md`) · **自动压缩/裁剪**:`research/06`(core 仓 `research/06-自动压缩与裁剪.md`)
+- **subagent/team/mcp**(做 P2 orchestrator 蜂群时):`research/08`(core 仓 `research/08-subagent-team-mcp.md`) · **调研总览**:`research/00`(core 仓 `research/00-总览与阅读指南.md`)
+
+### 怎么实现 TiDB 后端(core 已给出接法)
+- **Session 中心**:实现 core 的 `SessionStore`;底层 `extends BaseSessionStorage`(override `appendEntry`/`setLeafId` 落 TiDB)→ `new Session(storage)`;`acquire` 从事件日志重建(= wake)。core 的 `test/sessions.test.ts` 有完整 "DB rehearsal + wake" 范例。
+- **记忆**:不走 DB——design/138 文件记忆引擎(`RunnerDeps.memoryBackend`,单用户文件基座);旧 `MemoryStore`/`memory` 表已退役(`scripts/drop-memory-tables.sql`)。

package/deploy/sema-up/README.md

@@ -0,0 +1,145 @@
+# sema-up — 一键部署 sema 栈
+
+`sema-up` 把 sema 智能体服务端(`@sema-agent/server`)连同数据面(PG+MinIO)、配置中心
+(sema-registry)、可选 git 服务(Gitea)一键装到单机 docker 或 k8s 上。
+
+```bash
+# npm 分发姿势(package.json bin 已挂)
+npx -p @sema-agent/server sema-up --profile=full-single --gateway=https://api.deepseek.com/v1 \
+  --model=deepseek-v4-flash --model-key=sk-… -f site.env --yes
+# 或直接跑仓内脚本
+deploy/sema-up/sema-up.sh
+```
+
+## 三入口 × 部署形态矩阵
+
+三个入口进的是**同一引擎**(同一交互协议、同一 site.env 词表):
+
+| 入口 | 用法 | 适合 |
+|---|---|---|
+| TTY 交互 | `sema-up.sh`(无参) | 人在终端,一问一答(每问带「为什么问」) |
+| JSON 协议 | `sema-up.sh --interactive=json` | `sema cloud deploy` 等上层 UI 渲染决策点 |
+| 无人值守 | `sema-up.sh -f site.env --yes` | CI/脚本;缺必填直接 fail-loud 不猜 |
+
+| 形态(--profile) | 装什么 | 底座 | 状态 |
+|---|---|---|---|
+| `full-single` | 引擎+PG+MinIO(+registry+git) | 单机 docker compose | 可用 |
+| `data-center` | 只数据面 PG+MinIO(+registry+git),agent 在别处连 | 单机 docker compose | 可用 |
+| `local-plus` | 本机只跑 agent,连远端 data-center 数据面 | 单机 docker compose | 可用 |
+| `full-cluster --kube=existing` | 全栈上已有 k8s(kubeconfig 指向;kind/k3d/云商托管) | helm chart(`chart/`) | 可用 |
+| `full-cluster --kube=k3s` | 本机装 k3s 单机再 helm 装栈 | k3s+helm | 可用(Linux) |
+| `full-cluster --kube=machines` | 多机 ssh 装配 k3s HA(embedded etcd) | `cluster-up.sh` | 可用(≥3 机) |
+
+**配置中心(sema-registry)各档默认带上**;`--registry=false` 显式关。例外:`local-plus`
+默认不带(数据面在远端,配置中心应随数据面部署;本机再起一个=两个配置中心)。
+
+## git 面三态(--git)
+
+| 态 | 含义 | registry 集成 |
+|---|---|---|
+| `none`(默认) | 跳过 | — |
+| `provision` | 一键自建 Gitea(引导管理员+access token+持久卷) | **自动**:创建 OAuth app,registry 可用 Gitea 账号登录 |
+| `connect --git-url=… --git-token=…` | 接已有 git 服务 | Gitea:自动建 OAuth app;GitHub:无法自动(registry 只支持 Gitea OAuth),summary 打印待人工项 |
+
+自动化的边界(诚实声明):sema-registry 没有「git 服务器」持久化配置——能自动接的只有
+OAuth 登录(env:`GITEA_BASE_URL`/`GITEA_OAUTH_CLIENT_ID`/`GITEA_OAUTH_CLIENT_SECRET`);
+git 凭据按契约**不进配置中心**(worker 侧自管)。自动建 OAuth app 失败时不装成功,
+summary 会打印手动接法。
+
+## 全部 flag
+
+| flag | 默认 | 说明 |
+|---|---|---|
+| `--profile=P` | 交互问 | `full-single`/`data-center`/`local-plus`/`full-cluster` |
+| `--users=U` | `single` | `single`(超管 turnkey)/`multi`(身份隔离 REQUIRE_PRINCIPAL=true) |
+| `--region=R` | `auto` | `cn`/`global`;auto=对 aliyun/npmjs 探测延迟 |
+| `--project=NAME` | `sema` | compose project 名;并行试验/多套共存用 |
+| `--dry-run` | — | 只打印执行计划,不写 .env、不起容器 |
+| `--yes` | — | 无人值守(全默认;缺必填 fail-loud) |
+| `--interactive=json` | — | 机器可读交互协议 |
+| `-f FILE` | — | site 配置(env 形式;`machines.yaml` 走固定形状 mini-parser) |
+| `--port=N` | 8090 | 引擎端口;`--pg-port`(5432)/`--minio-port`(9000)/`--minio-console-port`(9001)同理 |
+| `--gateway=URL` | — | 模型网关 baseURL(OpenAI 兼容);带 agent 的档必需 |
+| `--model=ID` | `deepseek-v4-flash` | 模型 id |
+| `--model-key=K` | — | 模型 API key(也可 -f 里 MODEL_API_KEY) |
+| `--sandbox=LANE` | kvm 有→`kata` | `kata`/`e2b-cloud`/`runc`(full-single) |
+| `--registry=BOOL` | `true`(local-plus `false`) | 配置中心网站开关 |
+| `--registry-image=REF` | — | sema-registry 镜像(registry=true 必需) |
+| `--git=MODE` | `none` | `none`/`provision`/`connect` |
+| `--git-url=URL --git-token=T` | — | connect 态的已有服务(Gitea/GitHub/任意三方 git,自动识别;证书不校验) |
+| `--pg-url=URL` | — | 外接第三方 PG(`postgres://user:pass@host:port/db`);给了就不部署本地 PG,装配前真连检 |
+| `--s3-endpoint=URL --s3-access-key= --s3-secret-key=` | — | 外接第三方 S3(兼容协议:MinIO/OSS/COS/R2…);不部署本地 MinIO,装配前 ls+建桶检(`--insecure`) |
+| `--data-root=DIR` | 多盘机自动选大盘 | 数据卷 bind 到指定盘;首装落定不漂移(换盘=teardown-volumes 后重装) |
+| `--git-http-port=N` | 3300 | 自建 Gitea HTTP 口;`--git-ssh-port`(2222)同理 |
+| `--gitea-image=REF` | `gitea/gitea:1.24` | 自建 Gitea 镜像 |
+| `--pg-host= --pg-password= --minio-endpoint= --minio-password=` | — | local-plus 的远端数据面(data-center summary 里有) |
+| `--kube=MODE` | 交互问 | full-cluster:`existing`/`k3s`/`machines` |
+| `--kubeconfig=PATH` | `$KUBECONFIG`→`~/.kube/config` | `--kube=existing` 用 |
+| `--teardown` / `--teardown-volumes` | — | 卸载(留数据 / 连卷删) |
+| `--skip-preflight` | — | 跳过预检(不建议) |
+
+site.env 词表 = 上表的 env 形式(`PROFILE`/`SEMA_SERVER_IMAGE`/`SEMA_REGISTRY_IMAGE`/
+`GIT_MODE`/`GIT_URL`/`GIT_TOKEN`/`MODEL_API_KEY`/`E2B_API_KEY`/`IMAGE_PULL_USER`/`IMAGE_PULL_TOKEN` …);
+命令行显式参数赢过文件。k8s 路径额外:`STORAGE_CLASS`(缺省用集群默认 SC)、`NAMESPACE`(sema)。
+
+## 性能/磁盘:测量→建议(不强求)→硬底线
+
+preflight 实测 CPU/RAM/磁盘并分两档:**推荐值**(full:4c/8G/80G——4C8G 能部署全部)以下只给
+WARN+建议(data-center 档/local-plus/外接 S3+DB/换大盘),照样部署;**硬底线**(full:2c/3G/40G,
+data-center:2c/2G/20G)以下 BLOCK——确实无法稳定部署,提前警告不推进。多盘机自动扫描真实
+块设备挂载,存在明显更大的数据盘(>2× 根盘可用)时自动把数据卷 bind 过去(`--data-root` 可
+覆盖;macOS 只建议不自动)。k8s 路径同理:建议 3 节点(HA),少于 3 节点按缩放形态跑;
+单节点 allocatable <1c/2G 才拦。凡带 URL 的外接面(PG/S3/git)装配前都做真连接检测,
+一律忽略证书(内网自签是常态),验的是协议兼容与可达。
+
+## 镜像从哪来
+
+- **server**:`SEMA_SERVER_IMAGE`(`ghcr.io/clayboby/sema-server:<tag>`,public 匿名可拉;
+  CN 兜底=内网 Gitea 仓。SWR 已弃用 2026-07-13)。
+- **registry**:`SEMA_REGISTRY_IMAGE`(GHCR/Hub 的 `sema-registry` 镜像,迁移中,公开仓匿名可拉;
+  SWR 已弃用;仅换 private 仓时才需 k8s 路径凭据=env `IMAGE_PULL_USER`/`IMAGE_PULL_TOKEN`)。
+- 公共镜像(postgres/minio/gitea)直接拉;国内网络不通时配 dockerd `registry-mirrors`。
+
+## 凭据纪律
+
+全部凭据生成一次、落 `~/.sema-up/<project>/.env`(0600),重跑**绝不轮换**;
+summary 里管理员密码只显示一次(新生成那次),不进日志不进 git。
+
+## 验收
+
+```bash
+deploy/sema-up/smoke.sh --project=sema          # 数据面直验+registry/gitea+引擎
+deploy/sema-up/smoke.sh --url=http://host:8090 --token=$SERVICE_AUTH_TOKEN   # 远程引擎面
+```
+
+## 常见错误排查
+
+| 症状 | 原因 | 下一步 |
+|---|---|---|
+| `⛔ registry=true 需要 sema-registry 镜像` | 各档默认带 registry 了 | `--registry-image=…` 或 `--registry=false` |
+| `compose up 失败` + 拉镜像超时 | 镜像仓不可达/私仓没登录 | `docker login`;国内配 registry-mirrors;`docker compose -p <project> logs` |
+| preflight `port-XXXX occupied` | 端口被占 | `--port`/`--pg-port`/`--git-http-port` 换口,或停占用进程 |
+| preflight `BLOCK os` | 不在支持面 | Debian 12/13、Ubuntu 22.04/24.04、Rocky 9/10、macOS+docker |
+| `没有可用的 compose` | docker CLI 无 compose 插件 | 装 Docker Desktop/OrbStack 或 `brew install docker-compose` |
+| `docker-credential-desktop not found` | 卸载 Docker Desktop 后 `~/.docker/config.json` 残留 `credsStore` | 删掉该文件里的 `"credsStore": "desktop"` 行(或临时 `DOCKER_CONFIG` 指向干净目录) |
+| k8s:`集群没有默认 StorageClass` | PVC 会永久 Pending | `kubectl get sc` 后 `STORAGE_CLASS=<名>` 重跑 |
+| k8s:PG 一直不 healthy | 镜像在拉/PVC Pending/内存不足 | `kubectl -n sema describe cluster sema-pg` |
+| k8s:server `CreateContainerConfigError` | runner-token 复制晚于 pod 创建 | 重跑 kube-up(幂等);已内置先复制后等待 |
+| Gitea OAuth app 创建失败 | token 缺 `write:user` scope | summary 的待人工项有手动接法 |
+| smoke `auth 门` FAIL | SERVICE_AUTH_TOKEN 未生效=公网裸奔 | 立刻查 .env 与容器 env |
+| 模型面 402/401 | 余额耗尽/key 无效 | 充值/换 key 后重跑 smoke |
+| NodePort 不可达(kind/远程) | kind 节点是容器,宿主到 NodePort 不通 | `kubectl -n sema port-forward svc/sema-server 8090:8090` |
+
+## 文件地图
+
+```
+sema-up.sh            入口(决策/预检/凭据/装配/验证/summary)
+preflight.sh          单机预检(--json;BLOCK 带原因+建议)
+smoke.sh              验收(project 模式=数据面直验;--url 模式=引擎面)
+kube-up.sh            k8s 单机两态(existing kubeconfig / 本机 k3s)→ helm chart
+cluster-up.sh         多机 ssh k3s HA 装配(machines.yaml)
+chart/                helm chart(server/CNPG PG/MinIO/registry/gitea/沙箱 RBAC)
+stack/compose.yaml    单机 Layer 1(profiles: data/agent/registry/git)
+machines.example.yaml 多机清单模板
+lib/parse-machines.py machines.yaml mini-parser(标准库零依赖,fail-loud)
+```

package/deploy/sema-up/chart/Chart.yaml

@@ -0,0 +1,11 @@
+apiVersion: v2
+name: sema-stack
+description: >-
+  sema-stack — sema-server 引擎 + CNPG PG HA + MinIO + kata 沙箱 RBAC(DEPLOY-OVERSEAS-PILOT
+  Layer 1 正式 chart 化;对象名与 as-built 渲染清单(stack/sema-stack-cluster.yaml)完全一致,
+  便于从 kubectl-apply 存量 adoption)。前置(cluster-up.sh 负责,不在 chart 内):Longhorn 默认
+  SC、kata-deploy(runtimeclass)、CNPG operator、runner-token 跨 ns 复制、MinIO 建桶、
+  imagePullSecret(sema-regcred)。
+type: application
+version: 0.3.0
+appVersion: "1.156.1"

package/deploy/sema-up/chart/templates/gitea.yaml

@@ -0,0 +1,63 @@
+# ── 自建 Gitea(--git=provision;仓库+SQLite 同一 PVC;引导管理员/token/OAuth app
+#    是一次性动作,归 kube-up.sh,不进清单)────────────────────────────────────────
+{{- if .Values.gitea.enabled }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: sema-gitea-data
+  namespace: {{ .Release.Namespace }}
+spec:
+  accessModes: [ReadWriteOnce]
+{{- if .Values.gitea.storageClass }}
+  storageClassName: {{ .Values.gitea.storageClass }}
+{{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.gitea.storageSize }}
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: sema-gitea
+  namespace: {{ .Release.Namespace }}
+spec:
+  replicas: 1
+  strategy: { type: Recreate }   # RWO PVC 同 registry
+  selector:
+    matchLabels: { app: sema-gitea }
+  template:
+    metadata:
+      labels: { app: sema-gitea }
+    spec:
+      containers:
+        - name: gitea
+          image: {{ .Values.gitea.image | quote }}
+          ports: [{ containerPort: 3000 }, { containerPort: 22 }]
+          env:
+            - { name: GITEA__security__INSTALL_LOCK, value: "true" }
+            - { name: GITEA__database__DB_TYPE, value: sqlite3 }
+            - { name: GITEA__server__DOMAIN, value: {{ .Values.gitea.domain | default "localhost" | quote }} }
+            - { name: GITEA__server__ROOT_URL, value: "http://{{ .Values.gitea.domain | default "localhost" }}:{{ .Values.gitea.httpNodePort }}/" }
+            - { name: GITEA__server__SSH_PORT, value: {{ .Values.gitea.sshNodePort | quote }} }
+            - { name: GITEA__service__DISABLE_REGISTRATION, value: "true" }
+          volumeMounts: [{ name: data, mountPath: /data }]
+          readinessProbe:
+            httpGet: { path: /api/healthz, port: 3000 }
+            initialDelaySeconds: 5
+            periodSeconds: 5
+      volumes:
+        - name: data
+          persistentVolumeClaim: { claimName: sema-gitea-data }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: sema-gitea
+  namespace: {{ .Release.Namespace }}
+spec:
+  type: NodePort
+  selector: { app: sema-gitea }
+  ports:
+    - { name: http, port: 3000, targetPort: 3000, nodePort: {{ .Values.gitea.httpNodePort }} }
+    - { name: ssh, port: 22, targetPort: 22, nodePort: {{ .Values.gitea.sshNodePort }} }
+{{- end }}

package/deploy/sema-up/chart/templates/minio.yaml

@@ -0,0 +1,62 @@
+# ── MinIO(单副本 on Longhorn=盘冗余在下层;集群 EC 形态后续档)────────────────
+apiVersion: v1
+kind: Secret
+metadata:
+  name: sema-minio
+  namespace: {{ .Release.Namespace }}
+stringData:
+  rootUser: {{ .Values.minio.rootUser | quote }}
+  rootPassword: {{ required "minio.rootPassword is required" .Values.minio.rootPassword | quote }}
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: sema-minio-data
+  namespace: {{ .Release.Namespace }}
+spec:
+  accessModes: [ReadWriteOnce]
+{{- if .Values.minio.storageClass }}
+  storageClassName: {{ .Values.minio.storageClass }}
+{{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.minio.storageSize }}
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: sema-minio
+  namespace: {{ .Release.Namespace }}
+spec:
+  replicas: 1
+  selector:
+    matchLabels: { app: sema-minio }
+  template:
+    metadata:
+      labels: { app: sema-minio }
+    spec:
+      containers:
+        - name: minio
+          image: {{ .Values.minio.image }}
+          args: ["server", "/data", "--console-address", ":9001"]
+          env:
+            - name: MINIO_ROOT_USER
+              valueFrom: { secretKeyRef: { name: sema-minio, key: rootUser } }
+            - name: MINIO_ROOT_PASSWORD
+              valueFrom: { secretKeyRef: { name: sema-minio, key: rootPassword } }
+          ports: [{ containerPort: 9000 }, { containerPort: 9001 }]
+          volumeMounts: [{ name: data, mountPath: /data }]
+      volumes:
+        - name: data
+          persistentVolumeClaim: { claimName: sema-minio-data }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: sema-minio
+  namespace: {{ .Release.Namespace }}
+spec:
+  selector: { app: sema-minio }
+  ports:
+    - { name: s3, port: 9000 }
+    - { name: console, port: 9001 }

package/deploy/sema-up/chart/templates/namespace-sandbox.yaml

@@ -0,0 +1,9 @@
+# 沙箱 ns(release 本体装进 -n sema --create-namespace;sandbox ns 是第二个,chart 负责)
+# resource-policy: keep(build-host 真机验出):无它则 `helm uninstall sema-stack` 连带删本 ns——
+# 里面是 API 起的用户沙箱 pod + 6b 的 regcred,不该被卸栈操作级联杀。代价=卸栈后 ns 留待手清。
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: {{ .Values.sandbox.namespace }}
+  annotations:
+    helm.sh/resource-policy: keep