cc-web/AGENTS.md

Trellis Instructions

These instructions are for AI assistants working in this project.

Use the /trellis:start command when starting a new session to:

• Initialize your developer identity
• Understand current project context
• Read relevant guidelines

Use @/.trellis/ to learn:

• Development workflow (workflow.md)
• Project structure guidelines (spec/)
• Developer workspace (workspace/)

If you're using Codex, project-scoped helpers may also live in:

• .agents/skills/ for reusable Trellis skills
• .codex/agents/ for optional custom subagents

Keep this managed block so 'trellis update' can refresh the instructions.

Codex App / hapi 对齐经验

以下约定来自本项目对 /home/hdzx/2026/hapi 中 Codex app-server 接入方式的对比结果。后续如果继续维护 codexapp，默认按这些约定实现，避免再走偏到“看起来能跑、但拿不到原生协作能力”的分叉路径。

1. 初始化链路优先对齐上游协议

• initialize 成功后，先发送 initialized notification。
• 然后再做 best-effort 的能力探测：
  • experimentalFeature/enablement/set，当前至少尝试 { enablement: { goals: true } }
  • collaborationMode/list
• 上述探测失败时：
  • 只记录日志
  • 不直接中断 codexapp 启动

2. collaborationMode 的参数形状必须贴近 hapi

• 一旦本轮使用 collaborationMode，turn/start 顶层参数应保持精简。
• model、reasoning_effort、developer_instructions 应放入：
  • collaborationMode.settings.model
  • collaborationMode.settings.reasoning_effort
  • collaborationMode.settings.developer_instructions
• 使用 collaborationMode 时，不要再重复传顶层 model / effort，否则容易让 app-server 落到非原生协作路径。

3. 自定义跨会话能力走 MCP，不优先走 dynamicTools

• ccweb_list_conversations、ccweb_send_message 这类自定义能力，优先通过 thread/start.config.mcp_servers.* 挂载。
• 不要把它们当成 dynamicTools 主路径注入给 codexapp。
• 原因：
  • dynamicTools 容易污染 app-server 原生工具集
  • 会增加拿不到 spawn_agent / wait_agent / 原生协作工具的风险

4. MCP 配置要做成“线程级”而不是“进程级”

• codexapp 是长驻 app-server，不是一次一进程的 CLI 调用。
• 因此 CC_WEB_SOURCE_SESSION_ID、CC_WEB_CROSS_HOP_COUNT 这类来源上下文，不应只放在 app-server 进程全局环境里。
• 正确做法是随 thread/start.config.mcp_servers.ccweb.env 一起下发，让每个线程拿到自己的来源会话上下文。

5. guided input 依赖 plan 协作模式

• request_user_input 类能力默认按“协作 / plan 模式可用”来设计。
• Default / YOLO 模式下，不要假设引导输入一定可用。
• 如果要做降级：
  • 优先退回普通文本交互
  • 不要让整轮对话因为 guided input 不可用而直接失效

6. 能力降级要明确而保守

• 如果运行时拒绝 collaborationMode（例如 unknown field collaborationMode 或 unsupported collaboration mode）：
  • 应记录一次能力降级
  • 后续本轮可退回普通 turn 发送
• 但如果只是 goals 或 collaborationMode/list 探测失败：
  • 不应直接判定整个 app-server 不可用

7. 回归检查要覆盖协议形状，不只看 UI

后续涉及 codexapp 的改动，至少要检查这些点：

• initialize 后是否真的调用了：
  • experimentalFeature/enablement/set
  • collaborationMode/list
• collaborationMode 存在时：
  • 顶层是否没有重复 model
  • 顶层是否没有重复 effort
• ccweb 能力是否走 mcpToolCall，而不是再次退回 dynamicToolCall
• mock / regression 中是否覆盖了上述断言