fmode-app/docs/03-interface

容器接入文档索引（2026-11-12 梳理）

⚠️ 先看这里：容器接入相关文档一度分散在 20+ 份里，内容重叠、部分过期。 本文给出唯一权威清单，避免看错版本。

---

一、三份必读（其他都可以不看）

#	文档	用途	谁看
1	新容器接入优化-对齐lj-test基线-20261112.md	新容器接入的唯一执行文档：行为基线 + 配置 + 上报协议 + 多人共用反面案例 + 四阶段提示词	容器（按阶段执行）
2	容器接入标准流程-SOP-v3-20261112.md	操作单：体检 → 修改 → 自审 → 复验 → 交付	人（照着做）
3	提示词-容器自我优化-v2-20261111.md	早期版提示词（已被第 1 份的四阶段提示词取代）	⚠️ 保留备查
4	多用户共用容器-完整规范-20261112.md	同公司多人共用容器的完整链路	人（特殊场景）

---

二、权威源代码位置

内容	位置
provision 云函数	cloud/functions/fmodeagent-matrix-provision.js（v0.1.6）
状态上报云函数	cloud/functions/fmodeagent-status.js（xlosi3m46q）
容器侧实测基线	docs/03-interface/容器侧标准包-基线采集-20261111.md

---

三、已验证的容器（2026-11-12）

容器	agentId	状态	说明
lj-test	agent-node-lj-test	✅ 标准参考	全部字段达标，DNS 已修复（21ms）
lj	agent-lj	✅ 已对齐	所有字段与 lj-test 一致

两者实测对比（2026-11-12）

字段	lj-test	lj	一致
heartbeatAt	✅	✅	✅
usage	✅	✅	✅
host / channels / balance	✅	✅	✅
extra.currentSessions	✅ 6 字段	✅ 9 字段（更全）	✅
心跳间隔	3600s+900s	3600s+900s	✅
✅ reaction	✅	✅	✅
DNS 解析	21ms（已修）	62ms（本来就快）	✅

---

四、已废弃文档（不要再看）

文档	废弃原因	替代
容器接入规范提示词-20261111.md	早期版本，被 SOP v3 + 提示词 v2 取代	见 §一
容器侧改造-图文合并处理-20261110.md	图文合并插件已就位，待启用	§容器接入指南
容器侧改造-文件与成果统一上云-20261109.md	已被 file-hub 方案取代	2026-11-10-修改留痕-文件台账与按会话隔离.md
reporter字段规范-20261020.md	字段已扩充	容器侧标准包-基线采集-20261111.md
待问容器-* / 待问Agent-* 系列	一次性问答记录，已归档	容器取证-*.md
多容器协作-* 系列	群聊方案已变	见群聊相关文档

---

五、当前有待确认的事项

#	事项	状态	归属
1	图文合并插件未启用	⏳ plugin-media-text-merge 已就位但不在 enabled	容器侧（需重启）
2	图片回复格式	⏳ 容器把工具过程行当正文发	容器侧
3	RES_OPTIONS 软覆盖	⚠️ 写的是 ${RES_OPTIONS:-...}，会被外部值顶掉	容器侧（可选）
4	白名单 vs ALLOW_ALL 行为不确定	⚠️ .env 有白名单但没加载进进程	见多用户规范 §3.4
5	usageSessions 残留数据	⚠️ agent-lj 曾误用该字段，遗留 2 条	可忽略（App 不读）
6	群聊 NULL thread	已评估：不改（风险大于收益）	已闭环
7	🔴 lj 多用户准入未打通	未解决（agent-lj 同事不可用）	平台侧：删 s6 注入

7 的详情

agent-lj 的 /run/s6/container_environment/MATRIX_ALLOWED_USERS 是平台注入（root:root）， 导致 .env 的任何修改都压不过它，同事永远被拒。

• 受影响的容器：10-21 之后创建的（如 agent-lj）
• 不受影响：10-17 创建的 agent-node-lj-test（s6 里没这个文件）
• 解决：平台侧删掉该文件 → 重启
• 详见：docs/00-tracking/2026-11-12-遗留问题-多用户准入未打通.md

---

六、文档维护约定

• 新增容器接入相关文档前，先看本索引，避免再产生重复
• 权威文档只有 3 份（§一），其余一律视为历史资料
• 每次实测后，把新结论补进对应的权威文档，不要新建文档
• 本索引随权威文档变更同步更新

---

最后更新：2026-11-12