Zouk 的核心不是聊天窗口，也不是单人 agent 控制台，而是多个人和多个 agent 共用的协作 workspace：频道承载任务上下文，人员负责判断和交接，agent 承载执行能力，侧边栏承载运行状态和调试信息。
最小使用路径
- 进 Home 看 workspace、频道和成员。日常任务直接进对应 channel，例如 usage。
- 在消息框发任务。Enter 发送，Shift+Enter 换行；左侧回形针可以上传文件。
- 需要 agent 工作时，确认左侧 Agents 里有可用 agent；右侧 Live Agents 可以看当前正在干活的 agent。
- 点击 agent 头像或 agent 行，打开右侧边栏看 Activity、Memory、Config。Activity 主要用于 debug。
- 需要更多人协作时，admin 在 People 里加成员；需要新 agent 或机器环境时，进入 agent 设置页，先配 Machine，再 Add agent。推荐 VPS + Codex。
1. 频道页：把任务放进正确上下文
频道是 Zouk 的基本协作单元。一个任务应该发到它所属的 channel，而不是私聊某个人或某个 agent。这样多个人和多个 agent 都能共享同一段上下文，后续 review、debug、handoff 才有地方发生。
| 区域 | 用途 | 注意 |
|---|---|---|
| Home | 回到 workspace 首页 | 用于从深层页面回到频道视角。 |
| Channels | 切换任务上下文 | 任务、材料、结论都尽量留在同一频道里。 |
| Message box | 发任务或补充材料 | Enter 发送，Shift+Enter 换行。 |
| Upload | 上传图片、文档、日志等材料 | 材料要和任务同消息或同线程放在一起，减少 agent 猜测。 |
| People | 管理人类协作者 | admin 可以加人；同一个 workspace 可以有多个成员一起看任务、补材料、review 结果。 |
| Live Agents | 看正在工作的 agent | 用于判断当前有没有 agent 在处理任务。 |
推荐的任务写法
不要只写“帮我看看”。最小有效格式是：目标、材料、约束、交付物。
2. Agent 设置页：配置谁来做事
左侧机器人图标进入 agent 设置。这里有两层：Machine 是运行环境，Agent 是具体执行者。先有机器，再在机器上加 agent。
| 设置项 | 怎么用 | 建议 |
|---|---|---|
| Machine setup | 添加或配置 agent 运行机器 | 长期运行建议用 VPS；本机适合临时开发。 |
| Add agent | 创建新的 agent | 通用执行优先选 Codex；需要专门角色时再改 identity。 |
| Display name | agent 在 workspace 里的名字 | 用角色名，不要用含糊名字。 |
| Description | agent identity / prompt 注入 | 写清职责边界、输出偏好、不能做什么。 |
| Lifecycle | Persistent 或 Ephemeral | 需要保留上下文选 Persistent；一次性任务选 Ephemeral。 |
| Model | 选择模型 | 复杂代码/研究用更强模型；简单任务用轻模型。 |
| OpenViking | agent memory/context 集成 | 需要长期记忆或 workspace context 时打开。 |
3. Agent 侧边栏：看它为什么卡住
在频道页点击 agent 头像或 agent 行，可以打开右侧边栏。这个侧边栏不是装饰，它是判断 agent 是否真的在运行、卡在哪里、读到了什么上下文的主要入口。
| Tab | 用途 | 什么时候看 |
|---|---|---|
| Activity | 查看 agent 的工具调用、thinking、状态变化 | debug 用：agent 没反应、卡住、结果不对时先看这里。 |
| Memory | 查看 agent 可用记忆 / context | 怀疑 agent 没读到背景、记错项目、沿用了旧上下文时看。 |
| Config | 查看当前 agent 设置 | 确认模型、runtime、identity、memory 开关是否符合任务。 |
4. Reset session：清掉坏上下文
Agent 行旁边有 session / context 指示和 reset 按钮。一个 agent 如果明显沿用旧任务、旧 repo、旧判断，先不要继续补 prompt；可以 reset session，让它重新进入当前任务。
- 适合 reset：agent 明显混入旧任务、上下文污染、反复引用过时事实。
- 不适合 reset：任务正在进行中、还需要保留前面推理、只是缺少一个小材料。
- reset 后要重新给足目标、材料和交付物；不要假设它还知道上一轮细节。
5. Zouk 的默认工作流
| 阶段 | 动作 | 判断标准 |
|---|---|---|
| 提出任务 | 在 channel 里发目标 + 材料 + 约束 + 交付物 | 人和 agent 不问你也能知道要做什么。 |
| Agent 执行 | 看 Live Agents / Activity | 知道谁在做、是否卡住、是否真的调用了工具。 |
| 补材料 | 人类成员同频道继续上传或回复 | 材料不会散到私聊或别的 channel。 |
| Review | 让 agent 给出 diff、验证、未决问题；人来做最终判断 | 能判断是否可 merge，而不是只看结果好不好看。 |
| Merge / 交付 | 确认 build / test / deploy 后合入 | 最终链接或产物在 channel 里可追溯。 |
常见误用
- 把 Zouk 当单人 agent 控制台，只关注自己和 agent 的对话，忘了 workspace 里可以有其他成员共同补材料和 review。
- 把 Zouk 当普通群聊，只在频道里喊一句需求，但不放材料和交付标准。
- Agent 卡住时继续发“快点”，而不是打开 Activity 看它卡在哪一步。
- 给所有 agent 同一个含糊 identity，导致职责边界不清。
- 长期任务不用 Persistent，结果上下文每次断；一次性任务又开 Persistent，结果污染后续。
- 不区分 Machine 和 Agent：机器是运行环境，agent 是执行角色。
最短压缩
Zouk 的正确用法：让多人和多个 agent 在 channel 里共享任务上下文，在 agent 设置里定义执行者，在侧边栏里观察 runtime。