# How to use Zouk

网站：https://zouk.zaynjarvis.com
GitHub：https://github.com/ZaynJarvis/zouk

核心观点：Zouk 不是一个普通聊天窗口，也不是单人 agent 控制台，而是多个人和多个 agent 共用的协作 workspace。频道承载任务上下文，人员负责判断和交接，agent 承载执行能力，右侧边栏承载运行状态和调试信息。

最小使用路径：
- 进 Home 看 workspace、频道和成员；日常任务放进对应 channel。
- 在消息框发任务。Enter 发送，Shift+Enter 换行。
- 用左侧上传按钮补充图片、文档、日志等材料。
- 看左侧 Agents 和右侧 Live Agents，确认是否有 agent 可用、谁正在执行。
- 点击 agent 打开右侧边栏，看 Activity、Memory、Config。
- 需要更多人协作时，admin 在 People 里加成员。
- 需要新 agent 或机器环境时，进入 agent 设置页，先配 Machine，再 Add agent。推荐 VPS + Codex。

## 频道页

频道是 Zouk 的基本协作单元。任务应该发到它所属的 channel，而不是散落到私聊或无关频道。这样多个人和多个 agent 共享同一段上下文，后续 review、debug、handoff 才能追溯。

频道页关键区域：
- Home：回到 workspace 首页。
- Channels：切换任务上下文。
- Message box：发任务或补充材料。
- Upload：上传图片、文档、日志等材料。
- People：管理人类协作者，admin 可以加人；同一个 workspace 可以有多个成员一起看任务、补材料、review 结果。
- Live Agents：看正在工作的 agent。

多人协作时的判断：
- Zouk 里的成员不是旁观者。人可以在同一个 channel 里补充材料、纠正 agent、接手 review，也可以把结论留给后来的成员。
- 私聊适合临时沟通；真正要沉淀的任务状态应该回到 channel。

推荐任务写法：目标、材料、约束、交付物。

例子：
- 目标：基于这三张截图做一篇 howto use Zouk notes。
- 材料：三张图片必须放进文章。
- 约束：不要写产品宣传，写实际操作。
- 交付物：直接 merge 到 notes。

## Agent 设置页

Agent 设置页有两层：
- Machine：运行环境。
- Agent：具体执行者。

先有机器，再在机器上创建 agent。

关键设置：
- Machine setup：添加或配置 agent 运行机器。长期运行建议用 VPS，本机适合临时开发。
- Add agent：创建新的 agent。通用执行优先选 Codex。
- Display name：agent 在 workspace 里的名字。建议用角色名。
- Description：agent identity / prompt 注入。写清职责边界、输出偏好、不能做什么。
- Lifecycle：Persistent 或 Ephemeral。长期任务选 Persistent，一次性任务选 Ephemeral。
- Model：复杂代码或研究用更强模型，简单任务用轻模型。
- OpenViking：agent memory/context 集成。需要长期记忆或 workspace context 时打开。

## Agent 侧边栏

在频道页点击 agent 头像或 agent 行，可以打开右侧边栏。这个侧边栏用于判断 agent 是否真的在运行、卡在哪里、读到了什么上下文。

Tab 用法：
- Activity：查看工具调用、thinking、状态变化。agent 没反应、卡住、结果不对时先看这里。
- Memory：查看 agent 可用记忆和 context。怀疑 agent 没读到背景、记错项目、沿用旧上下文时看。
- Config：查看当前 agent 设置，确认模型、runtime、identity、memory 开关。

## Reset session

如果 agent 明显沿用旧任务、旧 repo、旧判断，先不要继续补 prompt；可以 reset session，让它重新进入当前任务。

适合 reset：
- agent 明显混入旧任务。
- 上下文污染。
- 反复引用过时事实。

不适合 reset：
- 任务正在进行中。
- 还需要保留前面推理。
- 只是缺少一个小材料。

reset 后要重新给足目标、材料和交付物；不要假设 agent 还知道上一轮细节。

## 默认工作流

1. 提出任务：在 channel 里发目标、材料、约束、交付物。
2. Agent 执行：看 Live Agents 和 Activity，确认谁在做、是否卡住、是否调用了工具。
3. 补材料：人类成员同频道继续上传或回复，不要散到私聊。
4. Review：让 agent 给出 diff、验证、未决问题；人来做最终判断。
5. 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。