nanoclaw/docs/answers/04-container-lifecycle.md

Q10-Q12: 容器生命周期

---

Q10: 启动 agent 容器时 mount 了哪些东西？

答案

Container mount 由 src/container-runner.ts:242-335 的 buildMounts() 构建。容器内文件系统结构：

容器路径	宿主机来源	权限	用途
/workspace/	data/v2-sessions/<agentGroup>/<session>/	RW	Session 目录：inbound.db、outbound.db、.heartbeat、outbox/、inbox/
/workspace/agent/	groups/<folder>/	RW	Per-group 工作文件 + CLAUDE.local.md
/workspace/agent/container.json	groups/<folder>/container.json	RO	嵌套 RO 覆盖——agent 可读不能改（line 276-278）
/workspace/agent/CLAUDE.md	groups/<folder>/CLAUDE.md	RO	组合的 CLAUDE.md，spawn 时重新生成（line 287-290）
/workspace/agent/.claude-fragments/	groups/<folder>/.claude-fragments/	RO	per-skill/per-MCP 指令片段
/workspace/global/	groups/global/	RO	共享全局记忆
/app/CLAUDE.md	container/CLAUDE.md	RO	共享基础 CLAUDE.md，通过 .claude-shared.md symlink 导入
/home/node/.claude/	data/v2-sessions/<agentGroup>/.claude-shared/	RW	Claude SDK 状态、settings.json、skill symlinks
/app/src/	container/agent-runner/src/	RO	共享 agent-runner TypeScript 源码
/app/skills/	container/skills/	RO	共享容器技能
额外	containerConfig.additionalMounts	→	Provider-contributed mounts（line 330）

调用链

1. spawnContainer()（line 108）→ buildMounts()（line 134）
2. Pre-mount 初始化：
   • initGroupFilesystem(agentGroup)（line 253）：幂等创建 groups/<folder>/、CLAUDE.local.md、.claude-shared/ 目录和 DB 行
   • syncSkillSymlinks()（line 257）：根据 container.json 的 skills 选择，在 .claude-shared/skills/ 下创建 symlink
   • composeGroupClaudeMd(agentGroup)（line 261）：重新生成组合 CLAUDE.md
3. Mount 按顺序组装（line 267-333）
4. 所有 volume mount 进入 buildContainerArgs()（line 447-453）

边界情况

• CLAUDE.md 和 .claude-fragments/ 是嵌套 RO mount，叠加在 RW group 目录上——agent 只能写 CLAUDE.local.md
• container.json 单独 RO mount 防止 agent 修改自己的配置
• Skill symlinks 指向容器内路径（/app/skills/<name>），在宿主机上是悬空符号链接，容器内有效

---

Q11: Agent 的 system prompt 是怎么拼出来的？

答案

Agent 的 system prompt 由三部分拼成：(A) 共享基础 CLAUDE.md，(B) per-skill/per-MCP 指令片段，(C) 运行时 addendum（身份 + destinations）。

Host 端组合（spawn 时）

src/claude-md-compose.ts:43-136 → composeGroupClaudeMd()：

1. 共享基础 symlink（line 49-50）：groups/<folder>/.claude-shared.md → /app/CLAUDE.md（21 行通用 agent 指令：交流风格、workspace、memory、conversation history）

2. Fragment 发现（line 58-107）：

   • Skill fragments（line 66-76）：container/skills/ 下任何有 instructions.md 的技能
   • 内置模块 fragments（line 83-96）：container/agent-runner/src/mcp-tools/ 下的 .instructions.md。cli.instructions.md 在 cli_scope='disabled' 时被跳过
   • MCP server fragments（line 100-107）：container.json 中外部 MCP server 的 instructions 字段，生成内联 fragment 文件

3. Fragment 协调（line 110-122）：删除不再需要的过期 fragment，创建/更新 symlink

4. 组合入口（line 125-130）：写出 groups/<folder>/CLAUDE.md，只含 import 指令：

   @./.claude-shared.md
   @./.claude-fragments/skill-onecli-gateway.md
   @./.claude-fragments/skill-welcome.md
   @./.claude-fragments/module-cli.md
   

   Claude Code 跟随 @ import 解决所有 fragment

5. Per-group 记忆（line 132-135）：确保 CLAUDE.local.md 存在——这是唯一可写的 CLAUDE.md 文件

Container 端运行时 addendum

container/agent-runner/src/destinations.ts:82-92 → buildSystemPromptAddendum()：

• 身份（line 85-87）：如果设置了 assistantName："You are <name>" + 自我介绍和签名指引
• Destination map（line 94-130）：从 inbound.db 的 destinations 表读取，生成 "Sending messages" 部分

各部分贡献

来源	内容	Agent 可修改？
container/CLAUDE.md（共享基础）	通用 agent 行为	否（RO mount）
Skill instructions.md	Per-skill 指引	否（RO）
MCP tool .instructions.md	如何使用内置工具	否（RO）
MCP server instructions	外部 MCP server 指引	仅 admin（DB中）
CLAUDE.local.md	Per-group 记忆	是（唯一可写）
buildSystemPromptAddendum()	身份 + destination map	生成时自动

---

Q12: 容器心跳怎么检测？进程活着但 poll loop 卡死了怎么发现？

答案

心跳是文件 touch 机制，不是 DB 写入，避免跨 mount DB 写入争用。

Container 端：心跳 touch

• Path：/workspace/.heartbeat（container/agent-runner/src/db/connection.ts:25）
• touchHeartbeat()（connection.ts:156-168）：用 fs.utimesSync() 更新文件 mtime。失败时回退 fs.writeFileSync()
• 触发时机：poll-loop.ts:361，在 for await (const event of query.events) 循环中——每个 SDK event（init、result、error、progress）都触发。意味着仅 agent 活跃流式回复时更新，poll 轮空间歇不更新

Host 端：卡住检测

Host sweep 每 60s 运行（host-sweep.ts:61），对每个有运行容器的 session 调用 enforceRunningContainerSla()（line 192 → line 228）。

两种检测层级（decideStuckAction()，line 82-118）：

1. 绝对天花板（line 91-105）：heartbeat mtime 年龄 > max(30 min, 当前Bash超时) → kill-ceiling

• ABSOLUTE_CEILING_MS = 30 * 60 * 1000
• 扩展 declaredBashMs：从 outbound.db 读 container_state，如果当前工具是 Bash 且有 tool_declared_timeout_ms，天花板扩大到该值
• 关键守护（line 92-98）：heartbeatMtimeMs === 0（刚 spawn，还没有 SDK activity）→ 跳过

2. Claim-stuck per-message（line 107-115）：对每个 processing_ack 中的 processing 行，如果 (claim_age > tolerance) 且 (heartbeat_mtime <= status_changed) → kill-claim

• CLAIM_STUCK_MS = 60s：claim 一条消息后 60s 内没有任何 heartbeat → poll loop 卡住
• 条件 heartbeat_mtime <= claimedAt 恰好检测 "claim 了消息后没有任何生命迹象"

3. 容器不在运行（line 199-201）：!isContainerRunning → resetStuckProcessingRows() 用指数退避（基数 5s × 2^tries，最多 5 次）重调度消息

处理器卡在 poll loop 的完整场景

Container 进程存活，poll loop 卡住：
  poll-loop.ts:101 → markProcessing(ids) → DB: status='processing', status_changed=NOW
  poll-loop.ts:174 → config.provider.query(...) → 启动，但 SDK 挂起
  [没有 heartbeat touch，因为没有 event 触发]
  ...
  Host sweep（60s后）：
    → getProcessingClaims(outDb) → 发现 claim，status_changed 很旧
    → heartbeatMtimeMs() → 返回旧 mtime（挂起前最后一次 event 的）
    → decideStuckAction(): claimAge > 60s, heartbeat_mtime <= claimedAt
    → action: 'kill-claim' → killContainer() + resetStuckProcessingRows()

边界情况

• 新 spawn 宽容期：heartbeat 文件不存在时跳过天花板检查，但 claim-stuck 检查仍然处理 "claim 了消息但在门口卡住"
• 每次 spawn 清 heartbeat（container-runner.ts:155）：防止旧容器的过期 mtime 立即触发 kill
• 孤儿 claim 清理（line 319）：kill 后 deleteOrphanProcessingClaims() 清掉 outbound.db 中的 processing 行，防止 sweep 立即 kill 新容器
• Bash 自定义超时：扩展容忍度，确保长运行 Bash 不被误杀