服务

服务运维

运行时状态、内存指标与常用命令。

In Habitat chat, the agent can load ToolSet ops (toolset_load(["ops"])) for on-demand health/status, sanitized config, and partner-confirmed config patch / restart — see docs/tools/ops.md.

状态与内存指标

anima service status and createTypedHabitatClient().call("status.get") (REST GET /rpc/v1/status/get) report process memory under memory_kb and memory_detail.

字段 / 标签	来源	含义
`rss (phys)` / `memory_kb`	Linux `VmRSS`，或 `process.memoryUsage().rss` 回退	进程当前驻留的物理 RAM
`heap (jsc)` / `heap_used_kb`	`process.memoryUsage().heapUsed`	JavaScriptCore 堆统计（非 OS 物理内存）
`native` / `external_kb`	`process.memoryUsage().external`	绑定到 JS 的原生对象
`virtual` / `vm_size_kb`	Linux `VmSize`	预留的虚拟地址空间（Gigacage 隔离区）；非实际 RAM 占用

在 Bun + JavaScriptCore 上，heap (jsc) 可能远大于 rss (phys)。问「anima 占多少 RAM？」请看 RSS。JS 压力看 heap 趋势（随时间、GC 后）——不要与 RSS 做绝对值对比。

请在 shell 中验证（业务 API 需要 Service API Token——见 remote-access.md）：

curl -s -H "Authorization: Bearer <fa_at_...>" http://127.0.0.1:2658/rpc/v1/status/get | jq '.memory_kb, .memory_detail'
grep -E '^(VmRSS|VmSize):' /proc/$(pgrep -f 'anima service' | head -1)/status
just misc memory-sample -- --habitat-url http://127.0.0.1:2658 --stage full

Development vs production

模式	如何运行 Habitat
Monorepo / worktree	`just dev habitat`（默认随机端口 ≥10000；可选 `--port` / `--strict-port`；源码树 `anima` 无 `service` 命令）
Standalone install	`anima service start` / `stop` / `status`（systemd user unit；2658 / TLS 2659）

Discord / 微信消息网关的配置见 message-gateway.md。

常用命令

# --- standalone install CLI only ---
anima service start          # background (systemd user unit when available)
anima service start --foreground
anima service status
anima service stop
anima service restart

# --- monorepo / worktree ---
just dev                     # Habitat (≥10000) + Vite Web (≥5000); proxy via FREEANIMA_URL
just dev habitat              # Habitat foreground; default random ≥10000; skip Habitat TLS (Vite may HTTPS)
just dev web              # Vite HMR from :5000 (set FREEANIMA_URL to Habitat); browser Habitat = page origin

anima.service is a single-unit stack: Habitat (:2658, REST + SAP + bundled /web when dist exists) managed by one foreground supervisor.

Web build is never triggered by service start. Paths:

Mode	When to `just pack web`	UI
Standalone release	Forced during `just pack cli`	Embedded, served at `/web/*`
Source deploy	Run `just pack web` before start	Habitat `/web/*` whenever dist exists
Dev	Not required	`just dev` / `just dev habitat` + `just dev web` → Web :5000+ HMR

When Web dist (src/portal/app/web/dist or embedded) is present, the stack serves browser Web UI at http://<host>:2658/web/* from Habitat (no separate API proxy). Clients store Habitat URL and Service API Token (fa_at_...) in Habitat settings. Optional Habitat native TLS listens on https://<host>:2659 when http.tls.enabled: true (see remote-access.md) — production only; source just dev habitat skips Habitat TLS and lets Vite terminate HTTPS when enabled.

Startup order: Habitat must pass GET /rpc/v1/health/probe (status: ok) before serve() onReady hooks run. anima service start waits up to 15 minutes by default (FREEANIMA_HABITAT_READY_TIMEOUT_MS) because schema migrations run before HTTP listen. Remote-tool host disconnects are retried by @freeanima/shared/rpc-contract transport (exponential backoff).

UI access:

Desktop / mobile Portal: Chat and Habitat inside the Tauri app (not served from Habitat :2658 unless dist is present and Habitat is hosting /web).
Browser / PWA: http://<host>:2658/web/* from Habitat when dist is present. Default Habitat URL in /web/config.json is the page origin.
本地 Web 开发（just dev web）： Vite 从 :5000 起，base 为 /web/——聊天室 http://127.0.0.1:5000/web/chat，Habitat …/web/habitat/dashboard；/rpc 与 /mcp 代理到 FREEANIMA_URL。浏览器 Habitat 默认页面 origin；just dev habitat 通过 ~/.anima/dev-web.token 自动注入 token。