AGENTS.md@src/host/service git:20260928.0bc633cA

Immutable. This exact content never changes and is served at /api/v1/blob/592fc284dce42354.

# Service Module Rules

## 范围与职责

适用于 `src/host/service/`。

让一个工作流以**常驻 HTTP 服务**的形态对外提供能力，并管理它的完整生命周期：

- 服务子进程的生命周期：启动、停止、崩溃判定、随主进程重启的自动恢复；
- 端口分配与子进程的组合挂载产物；
- 服务进程内的对外协议；
- 多用户隔离：外部用户标识到会话的稳定映射与持久化。

判断归属：该修改是否改变**服务进程的生命周期、进程间协作契约、对外协议或用户隔离语义**？若主要属于工作流语义、编排推进、图判定、界面展示，应放到对应模块。

## 进程边界

本模块横跨**两个进程侧**，两侧的规则不同：

- 主进程侧：子进程生命周期、端口分配、挂载产物渲染；
- 服务进程侧：对外协议、会话隔离、编排调用。

两侧只允许通过**磁盘事实**（服务文档、挂载产物文件）与**进程启动参数/标准流**协作：

- 禁止依赖内存共享、模块级单例或跨进程函数调用；
- 服务进程侧不得反向操作主进程侧的状态；
- 两个进程侧各自可独立测试：主进程侧的进程创建必须经可注入的子进程工厂，服务进程侧的编排依赖必须经抽象缝注入。

## 并发与幂等

- 启动的互斥必须在**第一个异步点之前**同步登记，否则并发的两次启动会同时通过检查并各自创建子进程（孤儿进程 + 端口泄漏）；
- 停止可被重复调用：重复调用不得泄漏或重复排程强杀定时器（宽限期以最后一次请求为准）；
- 关闭/退出事件与主动停止存在竞态：清理必须幂等；
- 会话映射的并发首解析必须去重，且"读改写"必须落在同一临界区内，不得跨锁执行。。

## 依赖边界

- 外部可执行文件（子进程命令）、网络服务（webServer）、官方能力（会话/Agent 创建）一律经运行时守卫 + 可注入缝使用，缺失时给出明确错误或降级告警，不得静默失效；
- 禁止在没有明确职责的位置读取环境变量或全局进程状态；进程环境继承、工作目录等启动参数必须集中在一处构造，便于审计；
- 对外协议层（HTTP）只做"请求/响应 ⇄ 核心调用"的转换与错误映射，**不得包含业务判断**；核心逻辑必须可在无 HTTP 的情况下测试。
- 本模块不反向依赖任何调用方。

## 核心原则

1. 两个进程侧只经磁盘事实与启动参数协作，不共享内存。
2. 服务状态以持久化文档为事实源，内存登记只是索引。
3. 启动互斥在第一个异步点之前，停止必须收敛整棵进程树。
4. 一切后台等待有上界，取消（超时/断开）必须传播。
5. 协议层只做转换与错误映射，核心逻辑可脱离 HTTP 测试。