<!-- TRELLIS:START -->
# 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.

<!-- TRELLIS:END -->

## 常用运维命令

重启 cc-web 服务：

```bash
pm2 restart ccweb --update-env
```

## 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 中是否覆盖了上述断言