ai_co_discuss 0.4.4 → 0.4.6

package/.agents/skills/local-stt-setup/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: local-stt-setup
+description: "为 AI CoDiscuss 安装本机语音识别：下载 CrispASR 与 Qwen3-ASR 模型，在这台电脑上把语音输入转成文字，并配置为网页“设置 → 语音 → 语音输入”里的“本机”服务。用户要求安装、修复、升级或卸载本地语音识别、本机语音输入、离线 ASR 时使用；不用于填写火山引擎等云端语音的密钥，本机朗读见 local-tts-setup。"
+---
+
+# 本机语音识别（local-stt-setup）
+
+装好后的样子：
+
+- `SERVICE_HOME/crispasr/cli/`：CrispASR 程序（`crispasr.exe` 及其 DLL）；`SERVICE_HOME/crispasr/models/qwen3-asr-0.6b-q8_0.gguf`：识别模型（约 1 GB）。`SERVICE_HOME` 见“前提”第 2 条。
+- 访问令牌存在 CoDiscuss 的本机私有密钥里（地址 `http://127.0.0.1:18766`），不写进其他文件或命令行。
+- 语音输入切到“本机”。CrispASR 由 CoDiscuss 本机程序在识别时自动启动，只监听 `127.0.0.1:18766`；1 分钟没有识别请求自动结束并释放显存（CoDiscuss 崩溃也一样），不需要开机自启。
+
+全程只在用户电脑上操作：不改 CoDiscuss 源码，不把令牌写进回复、日志或命令行参数；下载与安装前把预计占用（下文“前提”）告诉用户。
+
+## 前提
+
+依次检查，任何一项不满足就停下说明，不硬装：
+
+1. **CoDiscuss 版本**：运行 `codiscuss launch tts-settings`，输出的 `stt_catalog` 里要有 `"id": "local"`。没有说明版本过旧，请用户先更新（`npm install -g ai_co_discuss@latest`，再 `codiscuss service restart`）后继续。
+2. **服务目录**：设置了环境变量 `DISCUSS_SERVICE_HOME` 时用它，否则是 `~/.codiscuss`。下文记为 `SERVICE_HOME`。
+3. **程序包**（GitHub `CrispStrobe/CrispASR` 的 Release 资产）：
+
+   | 平台 | 判断 | 资产 |
+   |---|---|---|
+   | Windows + NVIDIA | `nvidia-smi` 的驱动主版本 ≥ 580 | `crispasr-windows-x86_64-cuda13.zip`（RTX 50 系可用） |
+   | Windows + NVIDIA | 驱动更旧 | `crispasr-windows-x86_64-cuda.zip`（CUDA 12.8，也支持 RTX 50 系），驱动太旧则 `-cuda126.zip` |
+   | Windows + AMD / Intel 独显 | — | `crispasr-windows-x86_64-vulkan.zip` |
+   | Windows 无独显 | — | `crispasr-windows-x86_64-cpu.zip` |
+   | macOS Apple Silicon | — | `crispasr-macos-arm64.tar.gz` |
+   | Linux x64 | NVIDIA / 其他独显 / 无 | `crispasr-linux-x86_64-cuda13.tar.gz`（或 `-cuda`）/ `-vulkan.tar.gz` / `crispasr-linux-x86_64.tar.gz` |
+
+   只能用 CPU 时先告诉用户：识别速度约等于录音时长（一段 1 分钟的话要等约 1 分钟），用户同意再装。
+4. **显存与磁盘**：识别服务运行时约占 2.5 GB 显存；与本机朗读（约 3 GB）同时运行时，8 GB 显卡余量很紧，两者都是用完 1 分钟后自动退出。磁盘约 1.7 GB（Windows CUDA 13 程序约 0.7 GB + 模型约 1 GB）。
+
+## 安装
+
+命令以 Windows 为例，macOS / Linux 的可执行文件是 `crispasr`。下载走用户当前的网络设置；经代理访问 GitHub 时偶尔会 TLS 握手失败（`schannel: failed to receive handshake`），用 `curl --retry 3 --retry-all-errors` 重试即可，仍失败再问用户是否换网络或代理。
+
+1. **下载程序**：读 `https://api.github.com/repos/CrispStrobe/CrispASR/releases/latest`，取上表对应资产，记下资产的 `digest`（`sha256:...`）。下载到空目录 `SERVICE_HOME/crispasr/download/`，核对 SHA-256 与 `digest` 一致后解压。压缩包里有一层以资产名命名的文件夹，把其中全部文件移到 `SERVICE_HOME/crispasr/cli/`，使 `cli/crispasr.exe` 与 DLL 在同一层。已装过时先结束正在运行的 crispasr 进程再覆盖。用 `crispasr.exe --version` 确认。
+2. **模型**：下载 `https://huggingface.co/cstr/qwen3-asr-0.6b-GGUF/resolve/main/qwen3-asr-0.6b-q8_0.gguf` 到 `SERVICE_HOME/crispasr/models/`（约 1 GB）。不要用文件名带 `imatrix` 的版本（长录音可能陷入重复）。
+3. **令牌**：生成 64 位十六进制随机串，写入临时文件 `{"base_url": "http://127.0.0.1:18766", "api_key": "<令牌>"}`，运行 `codiscuss launch api-key --file <临时文件>`，随即删除临时文件。
+4. **切换语音输入**：把 `codiscuss launch tts-settings` 的输出存成临时文件，只改 `stt_provider` 为 `"local"`，其余字段不动（读出的 `catalog`、`stt_catalog` 等字段保存时会被忽略），用 `codiscuss launch tts-settings --file <临时文件>` 保存后删除临时文件。用户只要求安装、不想马上切换时跳过这一步，之后可在网页“设置 → 语音 → 语音输入”里点“本机”。
+5. **验证**：先结束正在运行的 crispasr 进程（旧令牌启动的服务会拒绝新令牌）。准备一段 16 kHz 单声道 16 位 WAV（可用本机朗读或任意录音转换），去掉 44 字节文件头得到 PCM，base64 后写入临时文件 `{"upload_id": "<新 UUID>", "index": 0, "data": "<base64>", "final": true}`（单段不超过 256 KB，约 8 秒；更长的录音按序号分段，只有最后一段带 `"final": true`），运行 `codiscuss launch stt --file <临时文件>`：返回 `text` 即成功，`SERVICE_HOME/crispasr/serve.log` 会出现 `crispasr-server: transcribed ...`。第一次要启动服务并加载模型，约 5–15 秒。参考：RTX 5060 8 GB + `cuda13`，服务启动后约 35 倍实时，5 分钟录音约 8.5 秒。
+6. **清理与汇报**：删除 `SERVICE_HOME/crispasr/download/` 与所有临时文件。向用户报告程序包、模型与实测耗时，并说明：中英混说、标点与英文大小写识别较好；逐字母念的缩写（如 npm 念成 N-P-M）和代码标识符（如 `tts_providers`）容易识别成别的写法；切回火山引擎只需在设置里点选。
+
+## 修复、升级与卸载
+
+- **修复**：读 `SERVICE_HOME/crispasr/serve.log`，对照下表处理；必要时从出问题的那一步重做，令牌变了就重做第 3 步并结束旧进程。
+- **升级 CrispASR**：结束 crispasr 进程，重做第 1 步。
+- **卸载**：先在设置里把语音输入切回火山引擎（或用第 4 步的方法改 `stt_provider`），结束 crispasr 进程，删除 `SERVICE_HOME/crispasr/`。
+
+| 现象 | 原因与处理 |
+|---|---|
+| 本机语音识别尚未安装 | 没找到令牌或 `cli/crispasr.exe`：重做第 1、3 步 |
+| 服务拒绝了令牌 | 18766 端口上是旧令牌启动的 crispasr：结束该进程后重试 |
+| 本机服务启动超时 | 看 `serve.log`：缺 DLL 时重做第 1 步（确认文件已移到 `cli/` 同一层）；CUDA 报错时检查驱动，或换 `-vulkan` / `-cpu` 包；端口被占用时请用户释放 18766 |
+| 识别失败（HTTP 500） | 看 `serve.log`；显存不足（out of memory）时关闭占显存的程序，或等本机朗读用完自动退出后再试 |

package/.agents/skills/workflow-creator/SKILL.md

@@ -123,7 +123,7 @@ project_access: write
 - **工作流 ID**（文件夹名 = SKILL.md 的 `name`）：小写英文和数字，可用单个连字符连接（不在首尾），1—40 位。`label` 最多 32 字。
 - **`description`** 最多 500 字：写清做什么、什么时候用。主持人只凭它判断一条请求该不该按这个工作流做，写含糊了，该用时会不用、不该用时会套用。
 - **卡片**：最多 30 张。`name` 是卡片 ID，等于文件名，只用小写英文、数字和下划线，最多 16 位。`platform` 是平台 ID：`Claude`、`Codex`、`Antigravity`、`DeepSeek`、`Qwen`、`Grok`、`OpenAI`、`Custom`（网页显示的 Gemini 写 `Antigravity`，自定义 API 写 `Custom`），须是本机已配置的软件，或已配置的模型 API（官方平台可按已保存的 API Key 加入；Custom 须先保存完整的本机 API 配置）。成员名由程序拼成 `平台-卡片ID`。
-- **卡片可选字段**：`label`、`description`、`project_access`（read / write / auto / full）、`model`、`effort`。不用的字段直接省略；模型和强度省略即用本机默认值。接入方式、可执行文件、密钥不写进卡片，由各自电脑的配置决定。
+- **卡片可选字段**：`label`、`description`、`project_access`（read / write / auto / full）、`model`、`effort`。不用的字段直接省略；模型和强度省略即用本机默认值。接入方式、可执行文件、密钥不写进卡片，由各自电脑的配置决定。各角色挑哪个平台和模型，见 [给卡片挑平台和模型](references/model-selection.md)。
 - 头信息只支持单行 `key: value`；不支持多行值、列表和嵌套。
 - 卡片正文留空时使用该软件的默认提示。
 

package/.agents/skills/workflow-creator/references/model-selection.md

@@ -0,0 +1,23 @@
+# 给卡片挑平台和模型
+
+> 依据 2026-11 的社区口碑整理，不是实测。模型迭代快，拿不准时问用户，用户的指定优先。
+
+按角色要做的活挑，不按“谁最强”挑：贵模型放在规划、审查等决定质量的位置，便宜模型放在量大、规则明确的执行位置。
+
+| 平台 | 擅长 | 注意 | 适合的角色 |
+|---|---|---|---|
+| Claude | 写代码执行、前端 UI、长任务先拆再做、叙事与文案 | 额度消耗快，部分地区账号不稳定 | 执行者、写作者、编剧 |
+| OpenAI / Codex（GPT） | 推理、审查挑错、复杂排障 | 慢；中文措辞防御性重（“并不代表”），不适合写正文 | 审稿、验收、规划 |
+| Antigravity（Gemini） | 中文文笔、知识面广、幻觉低、读长文 | 用词偏西方；最强型号未公开 | 写作者、资料研究 |
+| Grok | 单价低、上下文长 | 修复与工具调用口碑差 | 一般不首选 |
+| DeepSeek | 快、便宜、规则明确的执行稳定 | 复杂任务吃力；最高思考档效率低，用中高档 | 记录、整理、批量执行 |
+| Qwen | 可本地部署 | 思考久、编程口碑一般 | 本地或离线场景 |
+| Kimi K3 | 国产上限、前端还原、规划 | 慢、贵、额度少；新版措辞变保守 | 规划、前端 |
+| GLM-5.3 | 后端与严肃逻辑可靠；中文小说文笔有人推荐 | 慢、高峰限流 | 执行、审核、写作备选 |
+| MiniMax | 价格低 | 能力口碑一般 | 便宜杂活 |
+
+写卡片时：
+
+- 只写本机已配置的平台；不确定时 `model`、`effort` 省略，用本机默认值。
+- 纯 API 平台（`OpenAI`、`DeepSeek`、`Qwen`、`Grok`、`Custom`）的成员不读 `effort`，没有命令行，只能用文件工具和 `commands.json` 登记的命令；需要跑脚本的角色，要么登记命令，要么用 `Claude`、`Codex`、`Antigravity` 这类本机软件。
+- 同一件事要两个视角审时，两张卡片用不同平台，避免同一家模型的盲点重叠。

package/docs/en/workflow.md

@@ -71,7 +71,7 @@ The discussion ends as soon as a limit is reached and returns to free collaborat
 When creating a room, you can add a decision model under **Smart Scheduling** (智能调度) — TypeSafe Jev, with OpenAI Decisions as an experimental option — using your own key, billed per call. Routine routing is then decided by the decision model instead of waking the host every time:
 
 - Unaddressed messages go to the member they are clearly meant for, to everyone at once, to everyone one after another in speaking order (a relay or a count-off), or to no one; otherwise to the host.
-- Without Smart Scheduling, `@全体成员` runs everyone together. With it, uncertain or failed decisions go to the host. `@全体依次` always uses the established speaking order.
+- `@全体成员` always runs everyone together and is never judged by Smart Scheduling. `@全体依次` always uses the established speaking order.
 - In discussions, a local follow-up becomes an ordinary question without consuming a turn or changing the queue, including questions for members who already spoke or the host. It also picks the next speaker between rounds. Without Smart Scheduling, the host can make the same handoff.
 - While a Goal runs and the room is idle, it judges whether the latest replies are waiting for you (a question, an authorization or decision, or a completion report). When confident, the host is not woken and the room waits for your reply; when unsure or on errors, the host is woken as usual.
 - When the host has preauthorized a specific read-only reviewer, a completed implementation batch can move to that reviewer. The model checks delivery completeness, not code correctness, and cannot choose another reviewer. Review results still return to the host.

package/docs/runner.md

@@ -1,168 +1,168 @@
-# 安装与接入
-
-[English](en/runner.md) | 简体中文
-
-本机服务在各 AI 的原会话中唤醒它们，或调用你配置的模型 API。网站本身不运行模型，也不保存密钥。
-
-## 支持的软件
-
-| 软件 | 接入方式 |
-| --- | --- |
-| Claude Code CLI | 自动 |
-| Codex CLI（0.163.0+）/ Codex App | 自动；App 须保持运行 |
-| Antigravity CLI（`agy`）/ Antigravity App | 自动 |
-| Cursor CLI | 手动 |
-| 模型 API | 自动，见 [API 接入](#api-接入) |
-
-使用前须在对应软件中完成安装与登录。
-
-## npm 安装与本机配置
-
-需要 Node.js 24+ 与 Python 3.10+。
-
-```sh
-npm install --global ai_co_discuss@latest
-codiscuss setup
-```
-
-`setup` 检测本机 CLI，保存软件配置、安装讨论技能，然后启动本机网站（`http://127.0.0.1:8765`）并打开浏览器。非交互环境可用 `codiscuss setup --yes`，用 `--clients codex,claude` 指定软件。结果提示“待处理”时，按提示处理后重跑 `setup`。
-
-**升级**：先 `codiscuss local stop`，再运行 `npm install --global --prefer-online ai_co_discuss@latest` 和 `codiscuss setup`。
-
-**卸载**：先 `codiscuss local stop`，再 `npm uninstall --global ai_co_discuss`。讨论数据保存在 `~/.codiscuss`，卸载不会删除。本机服务会自动清理已删除房间的本机文件，并控制日志大小；也可运行 `codiscuss service clean` 立即清理。
-
-## 两种讨论入口与启动配置
-
-### 从网页发起
-
-运行 `codiscuss local open`，点击“新建房间”，添加成员并指定主持人。启动失败时刷新页面，可沿用原请求继续，不会重复建房。
-
-话题名称、项目目录和本次成员每次重新填写；智能调度、协作方式、讨论与 Goal 上限、连续派活轮数等选项自动记住上一次选择，取消建房也保留。偏好保存在运行服务的电脑上，其他已配对设备使用同一份；讨论与 Goal 的目标仍需每次填写。工作流只记住浏览选中项，不会因此启动。
-
-### 浏览项目文件
-
-房间设置了项目目录后，左栏“房间”下方的“文件”页可浏览电脑上的文件夹与文件，查看大小和修改时间。点击文件打开悬浮预览，支持文本、Markdown 渲染与 HTML 静态渲染，并可切换源码。可同时打开多个文件，以标签切换；标题栏的“收起”（手机上也可按住标签栏下拉，或正文在顶部时下拉）把预览缩成内容区左上角的悬浮按钮，悬浮按钮可拖到左侧或右侧；切到其他频道或其他房间后点它回到原处（打开的文件、模式和滚动位置都保留），关闭才清空。未设置项目目录时入口灰显。
-
-在 Markdown 预览或成员回答正文中选中文字后点“添加到对话”，选中处上方出现批注框（可留空），回车后这段文字成为一条摘录，原文末尾标上编号；文件摘录随即收起预览、回到“消息”页。输入框上方显示“N 条摘录”，点开可逐条查看、修改批注或删除，悬停时的 × 一次移除全部；点原文上的编号也能重新编辑批注或删除该条。发送时每段摘录以“文件路径 + 行号”或“成员名 + 消息编号”加引用原文与批注附在正文之后，引用中的 @ 不会唤醒成员。
-
-其他设备通过已配对电脑的加密连接读取同一目录。文件内容最多预览前 128 KB，支持 UTF-8 和带 BOM 的 UTF-16；HTML 展示内联样式与内嵌图片。文件访问限于房间项目目录，目录外的链接灰显。
-
-### 多个项目目录
-
-一个房间可以有一个主项目目录和最多 8 个其他项目目录。新建房间选好项目目录后，点下方“添加其他项目目录”；建房后在“成员与设置 → 协作设置”的“项目目录”一行增删，保存后从各成员下一次执行起生效，会话不中断。主项目目录设置后不能更改；建房时没选的，可在同一行补设一次，已在房间的成员保留原会话、按自己的项目权限读写它。
-
-- 成员按自己的项目权限读写这些目录：只读成员全部只读，可写成员全部可写。
-- “文件”页上方可切换目录；输入框里 `@` 搜索文件时会一起搜其他目录，选中后按完整路径引用。
-- Claude Code、Codex CLI、agy 和 API 成员由程序限制读写；Codex App、Antigravity App 与在原窗口工作的手动成员只在任务里写明，实际权限以软件自身设置为准。
-
-工作目录不在房间任何项目目录里的成员（例如手动接入时它的 Claude 会话属于别的文件夹，或在启动配置里给它设了别的工作目录）也可以加入：它在自己的目录工作，对房间的目录只读，它自己目录里的改动不参与冲突提示。它加入或换目录时，网页右下角会提示一次，成员卡上也会标出它的工作目录。Codex CLI、API 成员，以及只读档的 Claude Code、agy 由程序保证改不了房间目录；其他情况（App、手动成员、可写档的 Claude Code 与 agy、自动与全放开）只在任务里要求，成员卡会注明“程序拦不住”。
-
-### 从 AI 对话发起
-
-在要担任主持人的本地 AI 对话中调用 `discuss-host` 和 `discuss-participant`，说明站点、议题、参与者与上限。主持技能沿用本机软件配置建房，当前会话继续主持。agy 不能在自己的对话中主持全自动讨论。
-
-### 线上网页连接本机
-
-使用自己部署的线上网站时，在运行 AI 的电脑上执行一次：
-
-```sh
-codiscuss local connect https://你的站点
-```
-
-它用一次性绑定令牌把这台电脑绑定到网站：在部署网站的电脑上（已 `wrangler login`）自动生成，否则先在部署网站的电脑上运行 `codiscuss token`，再加 `--setup-key 令牌`。每个令牌只能用一次。线上网站没有账号和密码，也不保存房间；任何设备都要先与这台电脑配对，再经中转读写电脑上的房间，需先部署中转（见[部署指南](deployment.md)“中转”）。撤销使用 `codiscuss local disconnect https://你的站点`。
-
-### 在其他设备上远程控制
-
-手机或平板与电脑配对后，只要这台电脑开机并运行 codiscuss，就能像在电脑上一样操作：建房、邀请与请回成员、翻开卡片设置软件、模型和权限、录入 API 密钥、管理常用项目等。这些操作由网站转交给电脑执行，内容端到端加密，网站只经手密文。
-
-其他设备能用的目录由电脑决定：只能选择**常用项目**及其中的文件夹。点项目目录栏末尾的文件夹按钮，可以逐层浏览常用项目中的文件夹（只显示文件夹名）。想让其他设备使用更大的范围，就在电脑上把上级目录加为常用项目。以下设置只能在电脑上修改：软件位置、常用项目范围之外的目录。转交的命令只执行一次，发出 10 分钟后作废，所以手机时间需要大致准确。
-
-**设备配对**：每台手机、平板或其他电脑第一次使用前，都要在这台电脑前配对一次，不需要注册账号或记住密码。
-1. 在电脑的本机网页“设置 → 账号 → 已配对的设备”中点“添加设备”，显示一个二维码和 12 位配对码，2 分钟有效，只能用一次。
-2. 新设备用相机扫二维码；不方便扫码时，打开线上网站，在设置页输入配对码。扫码时页面会核对电脑密钥指纹，防止被换成别的电脑。
-3. 按提示用设备自己的面容、指纹或设备密码确认一次，同时创建这台设备的通行密钥。
-
-之后：
-- 设备在浏览器里保存一把不可导出的设备密钥，之后打开网站直接可用。网站只认电脑签过名的设备名单，没有能被盗用的账号密码。
-- 每台设备授权 30 天。到期前或到期后 30 天内打开网页，用通行密钥确认一次即续期 30 天，不用回到电脑前；超过这段时间须重新配对。勾选“临时设备”的只授权 1 天，用于借来的电脑，不能续期。
-- 新设备的浏览器不支持通行密钥时（例如没有 Google Play 服务的安卓平板），在电脑上添加设备前勾选“允许不用通行密钥”再生成二维码。这样的设备不需要每日确认，也不能续期，到期须回电脑前重新配对；它在解锁状态下被别人拿到就能操作电脑，只在确实需要时勾选。
-- 新设备只能在电脑前添加，已配对设备不能远程添加。设备丢失时，在其他已配对设备或电脑上解绑它；只有一台外出设备时，回到电脑前解绑并重新配对。
-- 每台设备的记录按钮（时钟图标）列出电脑为它记下的配对、解绑、每日确认和远程操作（不含内容）；已解绑设备的记录汇总在列表末尾。看到不是你做的操作，立即解绑对应设备。
-- 清除浏览器数据会删掉设备密钥，需要回到电脑前重新配对。
-
-**每日确认**：每台设备每天第一次打开网页时，用面容、指纹或设备密码确认一次，之后 24 小时内建房、发消息、设置任意权限档（含可写、全放开）都不再询问。配对和续期本身也算一次确认。解绑设备只阻止之后的远程操作，已经在运行的工作和已改动的文件不会因此撤回。
-
-配对后目录“协作房间”直接列出电脑上的房间，与在电脑上看到的一致，可以发消息、上传附件、管理成员、导出备份，并实时更新。对话只保存在电脑上，网站只转交加密内容。
-
-- 电脑关机或 codiscuss 未运行时看不到房间，目录标题提示“电脑未连接”或“电脑离线”；电脑上线后页面自动连上。
-- 电脑没有及时答复时，页面提示“结果待确认”，不会自动重发；请先查看房间确认是否已生效。
-
-## API 接入
-
-在“添加”行选择 **OpenAI**，翻开卡片填写 OpenAI 官方 API Key 并选择模型；已预填官方地址 `https://api.openai.com/v1` 和 Responses 协议。原有 Codex 卡片仍可选择 API 接入。
-
-选择 **自定义 API** 可接入其他服务：翻开卡片填写 Base URL、API Key 和完整模型 ID，默认使用 Chat Completions，也可选择 Responses、Anthropic Messages 或 Gemini generateContent。卡片背面的“名称与描述”按钮可修改显示名称；重复点击添加可配置多个不同的 API 成员。Anthropic、Google Gemini、DeepSeek、阿里云百炼（Qwen）、xAI（Grok）也保留官方地址预设。
-
-API 成员可以担任专家或主持人。房间指定了项目目录时，它可以用接入程序提供的文件工具读取、搜索项目文件；项目权限设为可写时还能新建和编辑文件，但没有命令行，不能运行测试或构建。`.env`、私钥等密钥文件、`.git` 目录和本机服务目录始终不开放，读到的内容会发给你配置的模型服务商。密钥只保存在本机，调用费用按你的账号计费。
-
-## 智能调度（可选）
-
-建房时在“智能调度”下选择供应商并填写密钥，需要连接本机服务。卡片下方的“判断方式”可选“引导（试验）”（默认，正在打磨）或“稳定”（已通过回归评测），影响未点名消息的分派和讨论中的插话、下一位发言、下一轮判断。作用见 [使用指南](workflow.md#智能调度)。
-
-翻开成员卡片，“提示”一行可以给这位专家单独写几句要求，例如“回答先给结论”。它只发给这位专家，不改变权限；部分软件带有预设，可随时恢复。卡片背面的书签图标把这张卡片的描述、提示词、项目权限、模型与强度存为专家预设，之后在“添加”行一键加入，见 [使用指南](workflow.md#成员管理)。
-
-## 工作流（可选）
-
-工作流把一种多人协作的做法存下来，供别的房间复用：一份给主持人读的 SKILL.md，加一组 Agent 卡片（每张就是一个专家预设）。工作流在左侧栏“工作流”打开的面板里管理（没打开房间时也能用）：查看 SKILL.md、成员卡片和示意图，新建、导入、编辑、删除都在这里。要在房间里用时，在输入框要求主持人启动（打 `/` 选工作流可以直接写好这句请求，权限见下文）；主持人此后按说明组织工作。它只带来做法和成员；没画流程时不保证工序，具体怎么做由主持人判断。你随时可以 @ 任何成员。
-
-- **内置工作流**：安装包自带“小说剧本连载”（`story-serial`：编剧、写手、两位批评家与记录员逐集接力，附项目模板与状态检查脚本，脚本需要 Python 的 PyYAML）。默认不安装。在终端里运行 `codiscuss setup` 时，选完软件后有一步“安装配置”：先显示概览，按 → 展开，用空格勾选要装的工作流，回车继续；不勾就不装。也可以直接加 `--workflows` 安装全部（`install` 同样适用，非交互运行只认这个选项）。装的时候，已有同名的会覆盖为包里的最新版，原来那份先备份到服务目录的 `backups/workflows/`。选择只对这一次有效，不会记住，不选就不动工作流库。
-- **保存**：点左侧栏“已存档”下面的“工作流”打开工作流面板（手机上先点左上角打开侧栏），点列表上方的“新建或导入”，选“新建”，或导入别人分享的 zip 或文件夹（手机、平板上同样可用）。导入的内容先放上画布预览，点“保存”才写入。复制文件夹路径和删除工作流在说明抽屉底部。编辑页可以“从当前房间成员导入”卡片，提示词保持原文。想让主持人起草，打开下面的“主持人完整权限”。
-- **流程画布**：工作流面板左边是工作流列表，中间是选中工作流的画布，右边是它的 SKILL.md；手机和竖着拿的平板上，工作流排成顶部的一行标签，右端在“画布”和“工作流”（即 SKILL.md）之间切换。每位成员就是一张专家卡片，拖卡片上方的标题栏移动，点卡片翻面设置，× 删除。左上“成员”添加卡片（平台、预设，或当前房间的成员），“主持人”添加主持人节点；也可以从卡片右侧的圆点拖线到空白处，就地选要加的成员并自动连上。名称在右上角直接改，Ctrl+S 保存；列表里每项右边的“…”可以重命名、停用、复制文件夹路径或删除（停用的工作流留在库里，但房间里不能再启用，已启用它的房间改用房间里的设置，随时可以再启用），列表右边缘可以拖动调宽；左上有撤销、重做（Ctrl+Z、Ctrl+Shift+Z），双击空白处复位视图。连线用来示意谁接谁：从「开始」右侧的圆点拖线连到卡片，连回前面的卡片画成金色虚线表示循环，主持人节点表示交回主持人判断。选中一条连线或一个主持人节点，可以写一句说明，如“同时审”“返工”“不等交回”“验收”。同一角色出场两次时，在“成员”菜单底部“已有成员再放一次”里点它。打开时按看得清卡片的大小从“开始”那端显示，双击空白处看全图。用 `workflow-creator` 新建或修改工作流时，AI 会照 SKILL.md 一起画好这张图。连线只帮你看懂工作流，程序不执行它，主持人也看不到；主持人派活按的是 SKILL.md（就在画布右侧，默认显示排好版的内容，点“编辑”修改；面板可以拖宽或收起），顺序、同时做、什么时候交回、要不要返工都写在那里。
-- **让主持人自己建**：建房时（第 3 节“协作方式”）或在“成员与设置 → 协作设置”勾选“主持人完整权限”后，直接对主持人说要什么分工（或“把这个房间的做法存成工作流”），它会自己保存、在本房间启用，并邀请工作流里的成员，接着就按流程派活，不需要你导入或添加成员。之后让它改流程，改动从成员下一次执行起生效。打开这个开关后，也可以在输入框输入 `/` 选一个已保存的工作流，输入框里会写好“启用工作流「名称」（ID），”，补上要做的事发给主持人，它就启用这个工作流并带来成员（没打开时该项灰显）。主持人带来的成员项目权限最高为可写；只有本地软件担任的主持人能这样做，API 主持人不行。
-- **主持人完整权限的其他控制**：同一个开关打开后，主持人会自己处理房间里的问题、持续推进：成员跑偏时插话、卡住时打断或重试、模型不可用时换模型、无法恢复时换人；你也可以直接说“停下写手”“全部停下”“下一个让批评家先说”“请一位 Codex 进来只读评审”“把记录员请出去”“开个 Goal 把剩下几集写完”“暂停讨论”。邀请只用本机已配置的软件，项目权限最高可写；它自己开的 Goal 用你的默认预算（不限时为 8 次续跑、90 分钟）。成员连续 10 分钟没有新输出时，系统会提醒主持人检查；主持人派出长任务时还可以给自己设定时检查（每 5–120 分钟一次，房间空闲后自动结束）。它也能撤回自己派出的活，正在循环的接力会立即停下。以下仍由你决定：对主持人自己操作或更换主持人、批准超出上限的轮数、高于可写的权限或放行工具、改项目目录、撤回你的消息、私聊。API 主持人没有命令行，不能这样做。
-- **分享**：工作流存在本机服务目录的 `workflows` 文件夹，一个工作流一个文件夹；编辑页可复制路径，把整个文件夹（或打成 zip）发给对方即可分享。导入时会列出每张卡片的提示词和项目权限；要求写文件的卡片默认按只读导入，逐张勾选后才放开。
-- **给 API 成员登记命令**：以 API 方式加入的成员没有命令行。工作流文件夹里放一个 `commands.json`（写法见 `workflow-creator` 技能），登记它们能运行的命令（例如检查脚本，脚本也放在工作流文件夹里），随工作流一起分享；启用后 API 成员只能按名字运行这些命令，改不了命令行，只读成员只能运行标为只读的命令。命令以你的身份在本机运行，所以导入别人的工作流时，编辑页会列出每条完整命令，勾选“允许这些命令在本机运行”才会带上；主持人起草或修改工作流时不能增删命令。
-- **修改与结束**：修改工作流会作用于所有启用它的房间，成员下一次执行就按新内容；新增的卡片不会自动进入房间，主持人用到时会自己补上，也可以在右栏工作流一行点刷新图标立即补齐（删掉的卡片，其成员留作普通成员；与库一致时不显示该图标）；工作流卡片的提示词只读，在工作流面板的画布上修改。工作流进行中时，主持人只在请求和它的用途相符（或你说按工作流做）时才用，其他请求照常处理。用完在“成员与设置 → 协作设置”的工作流一行点请离成员图标（或逐个让成员离开）：工作流带来的成员离开（主持人保留），正在进行的工作随之停止，工作流结束，右栏这一块消失；成员会话保留，下次在输入框打 `/` 选它就把原成员请回来，接着原来的上下文。换工作流时直接选另一个，原来的成员留作普通成员。
-
-## 朗读与语音输入（可选）
-
-朗读可在网页“设置”的“语音”里切换服务：火山引擎（豆包语音合成 2.0）、阿里云百炼（CosyVoice）、Azure（神经语音，另填语音资源所在区域），或“本机”（在这台电脑的显卡上运行 Qwen3-TTS，不需要密钥、不计费；让你的本地 AI 按 `local-tts-setup` 技能安装，约占 3.5 GB 磁盘、建议 4 GB 以上显存，不支持调语速；朗读时自动启动，停止朗读或 1 分钟没有朗读时自动退出、释放显存）。在所选服务的控制台获取 API Key 填进去；每个服务的 Key 与音色分开保存，切回时仍在。语音输入固定用火山引擎「录音文件识别2.0」，朗读用其他服务时需另填火山引擎的 Key。朗读可设一个通用音色，并按 AI 平台（Claude、Codex、Gemini 等）分别配音色，朗读项目文件也可单独配一个音色，没配的平台、你自己的消息、程序消息和文件用通用音色；还可选语速；火山引擎还可改语气提示（默认是“像给朋友讲故事一样”的自然语气）。密钥只保存在本机，费用按你的账号计费。
-
-- 朗读：每条消息的工具栏有“朗读”（手机上在“…”菜单里），在消息里选中文字后点“听当前”从选中处开始；读完这条会接着读后面的消息直到最新，点输入框右下角的播报按钮开启语音播报：之后的新回复会自动朗读回答摘要（没写摘要的短回答读全文，长回答读第一段），主持人的发言会报“主持人”；讨论中还会提示新一轮的发言顺序和轮到谁，执行失败、操作待你允许和讨论结束也会播一句。同时到达的回复依次播报，积压较多时只播最新 3 条。锁屏或切到其他 App 时继续播放，锁屏界面和耳机按键可以暂停、继续、跳到下一条；读过的段落会缓存在电脑上，重听不再计费。正在读的句子会高亮，点一下高亮的句子暂停，再点继续；代码块跳过。朗读时消息区底部有“跟随”和“退出”：页面默认不随朗读滚动，点“跟随”后才把正在读的句子保持在视野内，手动滚动一下就取消跟随。
-- 朗读文件：在“文件”里打开 Markdown 文件，预览模式下标题栏有“朗读”，从正文开头读到文件末尾（文件头的 `---` 元数据不读）；选中文字后可从选中处开始。暂停、跟随、退出与消息朗读相同；收起为悬浮窗时继续朗读，切到源码、换文件或关闭预览（含悬浮窗上的关闭）即停止。
-- 语音输入：点输入框右下角的麦克风开始说话，再点一次转成文字插入输入框，单次最长 5 分钟。浏览器会先请求麦克风权限。
-
-两者都由本机服务调用语音服务，手机等其他设备经已配对电脑使用，电脑关机时不可用。
-
-## 权限
-
-项目权限按程序启动的 CLI 与 API 成员设置，默认只读；可选只读、可写、自动、全放开，软件不支持的档位灰显（agy 后台不支持自动，API 只有只读和可写）。只读档预先放行读写房间的 `codiscuss` 命令和答案草稿，可写档允许修改项目、运行命令；自动档由软件审核操作，全放开跳过权限确认。具体范围见档位的悬停说明。Codex 使用原生沙箱，agy 使用独立项目规则，Claude Code 中你已有的授权仍然生效；手动启动成员的权限沿用原会话设置。
-
-## 常驻讨论服务
-
-`codiscuss local open` 会同时启动讨论服务。一个服务托管所有房间；停止服务会暂停它托管的讨论。
-
-| 操作 | 命令 |
-| --- | --- |
-| 打开本机网站 | `codiscuss local open` |
-| 查看状态 | `codiscuss local status` |
-| 停止 | `codiscuss local stop` |
-| 重启讨论服务（使新环境变量生效；Windows 上读取系统设置或 `setx` 保存的最新值，在旧终端执行也可，PATH 除外） | `codiscuss service restart` |
-| 登录时自动启动（Windows） | `codiscuss service autostart on` |
-
-## 命令行
-
-主持人可用 `codiscuss review roster ROOM` 查看本机服务上报的只读评审候选，当前限程序启动的 Codex CLI。此命令只读配置事实，不会自动派发评审；已有授权仍须在实际投递时核对。
-
-读取后，派实现任务可携带 `--next-review NAME --review-scope 范围 --review-roster REVISION`，将下一步评审绑定本批次；评审者不能同时是本批实现者。批次完成后，主持人先用 `review ready ROOM --batch ID` 核对完整交付，再用 `review advance ROOM --batch ID --revision REV --submission-id UUID --as 本人` 推进既定评审；不能推进时会说明原因。开启智能调度后可代办这一步；没有配置、判断失败或把握不足时仍交主持人。
-
-`codiscuss` 同时供 AI 读写房间。`codiscuss --help` 列出全部命令，`codiscuss schema <命令>` 显示字段，都可离线使用。
-
-讨论与普通协作统一读取请求并提交回答。成员回答使用 `message post --kind chat`，自动任务绑定 `--execution`，手动回答绑定 `--request`；主持人先读 `turn roster`，再带返回的 revision 创建或继续安排。讨论开关先用 `run view` 读取 revision，再执行开始、暂停、继续或结束；具体字段以命令帮助和房间协议为准。主持任务附有调度建议时，可用 `state decision ROOM DECISION_ID` 读取对应原判断；建议注明未生效时仍由主持人自行决定。
-
-## 常见问题
-
-- **软件送达失败**：查看成员状态与原位失败卡，在对应软件中处理登录或权限；倒计时期间可以立即重试或停止。本机接入程序重启或异常退出、导致进行中的软件进程随之结束时，同样自动重新投递同一执行，间隔缩短为 5 秒。三次重试用尽后，讨论专家的失败交给主持人处理；也可跳过本次发言。
-- **Codex 提示会话被占用**：原聊天仍被 Codex App 占用，可在进度看板切换到 App 接入。
-- **Windows 报告两处数据路径**：从普通终端管理服务，或设置环境变量 `DISCUSS_SERVICE_HOME`。
-- **结果不明**：已交付但无法确认的任务不会自动重发，请先在原会话与房间中核对。
+# 安装与接入
+
+[English](en/runner.md) | 简体中文
+
+本机服务在各 AI 的原会话中唤醒它们，或调用你配置的模型 API。网站本身不运行模型，也不保存密钥。
+
+## 支持的软件
+
+| 软件 | 接入方式 |
+| --- | --- |
+| Claude Code CLI | 自动 |
+| Codex CLI（0.163.0+）/ Codex App | 自动；App 须保持运行 |
+| Antigravity CLI（`agy`）/ Antigravity App | 自动 |
+| Cursor CLI | 手动 |
+| 模型 API | 自动，见 [API 接入](#api-接入) |
+
+使用前须在对应软件中完成安装与登录。
+
+## npm 安装与本机配置
+
+需要 Node.js 24+ 与 Python 3.10+。
+
+```sh
+npm install --global ai_co_discuss@latest
+codiscuss setup
+```
+
+`setup` 检测本机 CLI，保存软件配置、安装讨论技能，然后启动本机网站（`http://127.0.0.1:8765`）并打开浏览器。非交互环境可用 `codiscuss setup --yes`，用 `--clients codex,claude` 指定软件。结果提示“待处理”时，按提示处理后重跑 `setup`。
+
+**升级**：先 `codiscuss local stop`，再运行 `npm install --global --prefer-online ai_co_discuss@latest` 和 `codiscuss setup`。
+
+**卸载**：先 `codiscuss local stop`，再 `npm uninstall --global ai_co_discuss`。讨论数据保存在 `~/.codiscuss`，卸载不会删除。本机服务会自动清理已删除房间的本机文件，并控制日志大小；也可运行 `codiscuss service clean` 立即清理。
+
+## 两种讨论入口与启动配置
+
+### 从网页发起
+
+运行 `codiscuss local open`，点击“新建房间”，添加成员并指定主持人。启动失败时刷新页面，可沿用原请求继续，不会重复建房。
+
+话题名称、项目目录和本次成员每次重新填写；智能调度、协作方式、讨论与 Goal 上限、连续派活轮数等选项自动记住上一次选择，取消建房也保留。偏好保存在运行服务的电脑上，其他已配对设备使用同一份；讨论与 Goal 的目标仍需每次填写。工作流只记住浏览选中项，不会因此启动。
+
+### 浏览项目文件
+
+房间设置了项目目录后，左栏“房间”下方的“文件”页可浏览电脑上的文件夹与文件，查看大小和修改时间。点击文件打开悬浮预览，支持文本、Markdown 渲染与 HTML 静态渲染，并可切换源码。可同时打开多个文件，以标签切换；标题栏的“收起”（手机上也可按住标签栏下拉，或正文在顶部时下拉）把预览缩成内容区左上角的悬浮按钮，悬浮按钮可拖到左侧或右侧；切到其他频道或其他房间后点它回到原处（打开的文件、模式和滚动位置都保留），关闭才清空。未设置项目目录时入口灰显。
+
+在 Markdown 预览或成员回答正文中选中文字后点“添加到对话”，选中处上方出现批注框（可留空），回车后这段文字成为一条摘录，原文末尾标上编号；文件摘录随即收起预览、回到“消息”页。输入框上方显示“N 条摘录”，点开可逐条查看、修改批注或删除，悬停时的 × 一次移除全部；点原文上的编号也能重新编辑批注或删除该条。发送时每段摘录以“文件路径 + 行号”或“成员名 + 消息编号”加引用原文与批注附在正文之后，引用中的 @ 不会唤醒成员。
+
+其他设备通过已配对电脑的加密连接读取同一目录。文件内容最多预览前 128 KB，支持 UTF-8 和带 BOM 的 UTF-16；HTML 展示内联样式与内嵌图片。文件访问限于房间项目目录，目录外的链接灰显。
+
+### 多个项目目录
+
+一个房间可以有一个主项目目录和最多 8 个其他项目目录。新建房间选好项目目录后，点下方“添加其他项目目录”；建房后在“成员与设置 → 协作设置”的“项目目录”一行增删，保存后从各成员下一次执行起生效，会话不中断。主项目目录设置后不能更改；建房时没选的，可在同一行补设一次，已在房间的成员保留原会话、按自己的项目权限读写它。
+
+- 成员按自己的项目权限读写这些目录：只读成员全部只读，可写成员全部可写。
+- “文件”页上方可切换目录；输入框里 `@` 搜索文件时会一起搜其他目录，选中后按完整路径引用。
+- Claude Code、Codex CLI、agy 和 API 成员由程序限制读写；Codex App、Antigravity App 与在原窗口工作的手动成员只在任务里写明，实际权限以软件自身设置为准。
+
+工作目录不在房间任何项目目录里的成员（例如手动接入时它的 Claude 会话属于别的文件夹，或在启动配置里给它设了别的工作目录）也可以加入：它在自己的目录工作，对房间的目录只读，它自己目录里的改动不参与冲突提示。它加入或换目录时，网页右下角会提示一次，成员卡上也会标出它的工作目录。Codex CLI、API 成员，以及只读档的 Claude Code、agy 由程序保证改不了房间目录；其他情况（App、手动成员、可写档的 Claude Code 与 agy、自动与全放开）只在任务里要求，成员卡会注明“程序拦不住”。
+
+### 从 AI 对话发起
+
+在要担任主持人的本地 AI 对话中调用 `discuss-host` 和 `discuss-participant`，说明站点、议题、参与者与上限。主持技能沿用本机软件配置建房，当前会话继续主持。agy 不能在自己的对话中主持全自动讨论。
+
+### 线上网页连接本机
+
+使用自己部署的线上网站时，在运行 AI 的电脑上执行一次：
+
+```sh
+codiscuss local connect https://你的站点
+```
+
+它用一次性绑定令牌把这台电脑绑定到网站：在部署网站的电脑上（已 `wrangler login`）自动生成，否则先在部署网站的电脑上运行 `codiscuss token`，再加 `--setup-key 令牌`。每个令牌只能用一次。线上网站没有账号和密码，也不保存房间；任何设备都要先与这台电脑配对，再经中转读写电脑上的房间，需先部署中转（见[部署指南](deployment.md)“中转”）。撤销使用 `codiscuss local disconnect https://你的站点`。
+
+### 在其他设备上远程控制
+
+手机或平板与电脑配对后，只要这台电脑开机并运行 codiscuss，就能像在电脑上一样操作：建房、邀请与请回成员、翻开卡片设置软件、模型和权限、录入 API 密钥、管理常用项目等。这些操作由网站转交给电脑执行，内容端到端加密，网站只经手密文。
+
+其他设备能用的目录由电脑决定：只能选择**常用项目**及其中的文件夹。点项目目录栏末尾的文件夹按钮，可以逐层浏览常用项目中的文件夹（只显示文件夹名）。想让其他设备使用更大的范围，就在电脑上把上级目录加为常用项目。以下设置只能在电脑上修改：软件位置、常用项目范围之外的目录。转交的命令只执行一次，发出 10 分钟后作废，所以手机时间需要大致准确。
+
+**设备配对**：每台手机、平板或其他电脑第一次使用前，都要在这台电脑前配对一次，不需要注册账号或记住密码。
+1. 在电脑的本机网页“设置 → 账号 → 已配对的设备”中点“添加设备”，显示一个二维码和 12 位配对码，2 分钟有效，只能用一次。
+2. 新设备用相机扫二维码；不方便扫码时，打开线上网站，在设置页输入配对码。扫码时页面会核对电脑密钥指纹，防止被换成别的电脑。
+3. 按提示用设备自己的面容、指纹或设备密码确认一次，同时创建这台设备的通行密钥。
+
+之后：
+- 设备在浏览器里保存一把不可导出的设备密钥，之后打开网站直接可用。网站只认电脑签过名的设备名单，没有能被盗用的账号密码。
+- 每台设备授权 30 天。到期前或到期后 30 天内打开网页，用通行密钥确认一次即续期 30 天，不用回到电脑前；超过这段时间须重新配对。勾选“临时设备”的只授权 1 天，用于借来的电脑，不能续期。
+- 新设备的浏览器不支持通行密钥时（例如没有 Google Play 服务的安卓平板），在电脑上添加设备前勾选“允许不用通行密钥”再生成二维码。这样的设备不需要每日确认，也不能续期，到期须回电脑前重新配对；它在解锁状态下被别人拿到就能操作电脑，只在确实需要时勾选。
+- 新设备只能在电脑前添加，已配对设备不能远程添加。设备丢失时，在其他已配对设备或电脑上解绑它；只有一台外出设备时，回到电脑前解绑并重新配对。
+- 每台设备的记录按钮（时钟图标）列出电脑为它记下的配对、解绑、每日确认和远程操作（不含内容）；已解绑设备的记录汇总在列表末尾。看到不是你做的操作，立即解绑对应设备。
+- 清除浏览器数据会删掉设备密钥，需要回到电脑前重新配对。
+
+**每日确认**：每台设备每天第一次打开网页时，用面容、指纹或设备密码确认一次，之后 24 小时内建房、发消息、设置任意权限档（含可写、全放开）都不再询问。配对和续期本身也算一次确认。解绑设备只阻止之后的远程操作，已经在运行的工作和已改动的文件不会因此撤回。
+
+配对后目录“协作房间”直接列出电脑上的房间，与在电脑上看到的一致，可以发消息、上传附件、管理成员、导出备份，并实时更新。对话只保存在电脑上，网站只转交加密内容。
+
+- 电脑关机或 codiscuss 未运行时看不到房间，目录标题提示“电脑未连接”或“电脑离线”；电脑上线后页面自动连上。
+- 电脑没有及时答复时，页面提示“结果待确认”，不会自动重发；请先查看房间确认是否已生效。
+
+## API 接入
+
+在“添加”行选择 **OpenAI**，翻开卡片填写 OpenAI 官方 API Key 并选择模型；已预填官方地址 `https://api.openai.com/v1` 和 Responses 协议。原有 Codex 卡片仍可选择 API 接入。
+
+选择 **自定义 API** 可接入其他服务：翻开卡片填写 Base URL、API Key 和完整模型 ID，默认使用 Chat Completions，也可选择 Responses、Anthropic Messages 或 Gemini generateContent。卡片背面的“名称与描述”按钮可修改显示名称；重复点击添加可配置多个不同的 API 成员。Anthropic、Google Gemini、DeepSeek、阿里云百炼（Qwen）、xAI（Grok）也保留官方地址预设。
+
+API 成员可以担任专家或主持人。房间指定了项目目录时，它可以用接入程序提供的文件工具读取、搜索项目文件；项目权限设为可写时还能新建和编辑文件，但没有命令行，不能运行测试或构建。`.env`、私钥等密钥文件、`.git` 目录和本机服务目录始终不开放，读到的内容会发给你配置的模型服务商。密钥只保存在本机，调用费用按你的账号计费。
+
+## 智能调度（可选）
+
+建房时在“智能调度”下选择供应商并填写密钥，需要连接本机服务。卡片下方的“判断方式”可选“引导（试验）”（默认，正在打磨）或“稳定”（已通过回归评测），影响未点名消息的分派和讨论中的插话、下一位发言、下一轮判断。作用见 [使用指南](workflow.md#智能调度)。
+
+翻开成员卡片，“提示”一行可以给这位专家单独写几句要求，例如“回答先给结论”。它只发给这位专家，不改变权限；部分软件带有预设，可随时恢复。卡片背面的书签图标把这张卡片的描述、提示词、项目权限、模型与强度存为专家预设，之后在“添加”行一键加入，见 [使用指南](workflow.md#成员管理)。
+
+## 工作流（可选）
+
+工作流把一种多人协作的做法存下来，供别的房间复用：一份给主持人读的 SKILL.md，加一组 Agent 卡片（每张就是一个专家预设）。工作流在左侧栏的“工作流”列表里管理，点一项就在中间打开它（没打开房间时也能用）：查看 SKILL.md、成员卡片和示意图，新建、导入、编辑、删除都在这里。要在房间里用时，在输入框要求主持人启动（打 `/` 选工作流可以直接写好这句请求，权限见下文）；主持人此后按说明组织工作。它只带来做法和成员；没画流程时不保证工序，具体怎么做由主持人判断。你随时可以 @ 任何成员。
+
+- **内置工作流**：安装包自带“小说剧本连载”（`story-serial`：编剧、写手、两位批评家与记录员逐集接力，附项目模板与状态检查脚本，脚本需要 Python 的 PyYAML）。默认不安装。在终端里运行 `codiscuss setup` 时，选完软件后有一步“安装配置”：先显示概览，按 → 展开，用空格勾选要装的工作流，回车继续；不勾就不装。也可以直接加 `--workflows` 安装全部（`install` 同样适用，非交互运行只认这个选项）。装的时候，已有同名的会覆盖为包里的最新版，原来那份先备份到服务目录的 `backups/workflows/`。选择只对这一次有效，不会记住，不选就不动工作流库。
+- **保存**：点左侧栏“工作流”标题右侧的“+”（手机上先点左上角打开侧栏），选“新建”，或导入别人分享的 zip 或文件夹（手机、平板上同样可用）。导入的内容先放上画布预览，点“保存”才写入。复制文件夹路径和删除工作流在列表项的“…”里。编辑页可以“从当前房间成员导入”卡片，提示词保持原文。想让主持人起草，打开下面的“主持人完整权限”。
+- **流程画布**：在左侧栏“工作流”列表里点一项，中间换成它的画布，右边是它的 SKILL.md；点任一房间或频道工具回到房间。手机和竖着拿的平板上，顶部在“画布”和“工作流”（即 SKILL.md）之间切换。每位成员就是一张专家卡片，拖卡片上方的标题栏移动，点卡片翻面设置，× 删除。左上“成员”添加卡片（平台、预设，或当前房间的成员），“主持人”添加主持人节点；也可以从卡片右侧的圆点拖线到空白处，就地选要加的成员并自动连上。名称在右上角直接改，Ctrl+S 保存；列表里每项右边的“…”可以重命名、停用、复制文件夹路径或删除（停用的工作流留在库里，但房间里不能再启用，已启用它的房间改用房间里的设置，随时可以再启用）；左上有撤销、重做（Ctrl+Z、Ctrl+Shift+Z），双击空白处或鼠标中键双击复位视图。连线用来示意谁接谁：从「开始」右侧的圆点拖线连到卡片，连回前面的卡片画成金色虚线表示循环，主持人节点表示交回主持人判断。选中一条连线或一个主持人节点，可以写一句说明，如“同时审”“返工”“不等交回”“验收”。同一角色出场两次时，在“成员”菜单底部“已有成员再放一次”里点它。打开时按看得清卡片的大小从“开始”那端显示，双击空白处看全图。用 `workflow-creator` 新建或修改工作流时，AI 会照 SKILL.md 一起画好这张图。连线只帮你看懂工作流，程序不执行它，主持人也看不到；主持人派活按的是 SKILL.md（就在画布右侧，默认显示排好版的内容，点“编辑”修改；面板可以拖宽或收起），顺序、同时做、什么时候交回、要不要返工都写在那里。
+- **让主持人自己建**：建房时（第 3 节“协作方式”）或在“成员与设置 → 协作设置”勾选“主持人完整权限”后，直接对主持人说要什么分工（或“把这个房间的做法存成工作流”），它会自己保存、在本房间启用，并邀请工作流里的成员，接着就按流程派活，不需要你导入或添加成员。之后让它改流程，改动从成员下一次执行起生效。打开这个开关后，也可以在输入框输入 `/` 选一个已保存的工作流，输入框里会写好“启用工作流「名称」（ID），”，补上要做的事发给主持人，它就启用这个工作流并带来成员（没打开时该项灰显）。主持人带来的成员项目权限最高为可写；只有本地软件担任的主持人能这样做，API 主持人不行。
+- **主持人完整权限的其他控制**：同一个开关打开后，主持人会自己处理房间里的问题、持续推进：成员跑偏时插话、卡住时打断或重试、模型不可用时换模型、无法恢复时换人；你也可以直接说“停下写手”“全部停下”“下一个让批评家先说”“请一位 Codex 进来只读评审”“把记录员请出去”“开个 Goal 把剩下几集写完”“暂停讨论”。邀请只用本机已配置的软件，项目权限最高可写；它自己开的 Goal 用你的默认预算（不限时为 8 次续跑、90 分钟）。成员连续 10 分钟没有新输出时，系统会提醒主持人检查；主持人派出长任务时还可以给自己设定时检查（每 5–120 分钟一次，房间空闲后自动结束）。它也能撤回自己派出的活，正在循环的接力会立即停下。以下仍由你决定：对主持人自己操作或更换主持人、批准超出上限的轮数、高于可写的权限或放行工具、改项目目录、撤回你的消息、私聊。API 主持人没有命令行，不能这样做。
+- **分享**：工作流存在本机服务目录的 `workflows` 文件夹，一个工作流一个文件夹；编辑页可复制路径，把整个文件夹（或打成 zip）发给对方即可分享。导入时会列出每张卡片的提示词和项目权限；要求写文件的卡片默认按只读导入，逐张勾选后才放开。
+- **给 API 成员登记命令**：以 API 方式加入的成员没有命令行。工作流文件夹里放一个 `commands.json`（写法见 `workflow-creator` 技能），登记它们能运行的命令（例如检查脚本，脚本也放在工作流文件夹里），随工作流一起分享；启用后 API 成员只能按名字运行这些命令，改不了命令行，只读成员只能运行标为只读的命令。命令以你的身份在本机运行，所以导入别人的工作流时，编辑页会列出每条完整命令，勾选“允许这些命令在本机运行”才会带上；主持人起草或修改工作流时不能增删命令。
+- **修改与结束**：修改工作流会作用于所有启用它的房间，成员下一次执行就按新内容；新增的卡片不会自动进入房间，主持人用到时会自己补上，也可以在右栏工作流一行点刷新图标立即补齐（删掉的卡片，其成员留作普通成员；与库一致时不显示该图标）；工作流卡片的提示词只读，在工作流页的画布上修改。工作流进行中时，主持人只在请求和它的用途相符（或你说按工作流做）时才用，其他请求照常处理。用完在“成员与设置 → 协作设置”的工作流一行点请离成员图标（或逐个让成员离开）：工作流带来的成员离开（主持人保留），正在进行的工作随之停止，工作流结束，右栏这一块消失；成员会话保留，下次在输入框打 `/` 选它就把原成员请回来，接着原来的上下文。换工作流时直接选另一个，原来的成员留作普通成员。
+
+## 朗读与语音输入（可选）
+
+朗读可在网页“设置”的“语音”里切换服务：火山引擎（豆包语音合成 2.0）、阿里云百炼（CosyVoice）、Azure（神经语音，另填语音资源所在区域），或“本机”（在这台电脑的显卡上运行 Qwen3-TTS，不需要密钥、不计费；让你的本地 AI 按 `local-tts-setup` 技能安装，约占 3.5 GB 磁盘、建议 4 GB 以上显存，不支持调语速；朗读时自动启动，停止朗读或 1 分钟没有朗读时自动退出、释放显存）。在所选服务的控制台获取 API Key 填进去；每个服务的 Key 与音色分开保存，切回时仍在。语音输入可另选服务：火山引擎「录音文件识别2.0」（朗读用其他服务时需另填火山引擎的 Key），或“本机”（在这台电脑上运行 Qwen3-ASR，不需要密钥、不计费；让你的本地 AI 按 `local-stt-setup` 技能安装，约占 1.7 GB 磁盘、运行时约 2.5 GB 显存，用时自动启动、闲置 1 分钟退出）。朗读可设一个通用音色，并按 AI 平台（Claude、Codex、Gemini 等）分别配音色，朗读项目文件也可单独配一个音色，没配的平台、你自己的消息、程序消息和文件用通用音色；还可选语速；火山引擎还可改语气提示（默认是“像给朋友讲故事一样”的自然语气）。密钥只保存在本机，费用按你的账号计费。
+
+- 朗读：每条消息的工具栏有“朗读”（手机上在“…”菜单里），在消息里选中文字后点“听当前”从选中处开始；读完这条会接着读后面的消息直到最新，点输入框右下角的播报按钮开启语音播报：之后的新回复会自动朗读回答摘要（没写摘要的短回答读全文，长回答读第一段），主持人的发言会报“主持人”；讨论中还会提示新一轮的发言顺序和轮到谁，执行失败、操作待你允许和讨论结束也会播一句。同时到达的回复依次播报，积压较多时只播最新 3 条。锁屏或切到其他 App 时继续播放，锁屏界面和耳机按键可以暂停、继续、跳到下一条；读过的段落会缓存在电脑上，重听不再计费。正在读的句子会高亮，点一下高亮的句子暂停，再点继续；代码块跳过。朗读时消息区底部有“跟随”和“退出”：页面默认不随朗读滚动，点“跟随”后才把正在读的句子保持在视野内，手动滚动一下就取消跟随。
+- 朗读文件：在“文件”里打开 Markdown 文件，预览模式下标题栏有“朗读”，从正文开头读到文件末尾（文件头的 `---` 元数据不读）；选中文字后可从选中处开始。暂停、跟随、退出与消息朗读相同；收起为悬浮窗时继续朗读，切到源码、换文件或关闭预览（含悬浮窗上的关闭）即停止。
+- 语音输入：点输入框右下角的麦克风开始说话，再点一次转成文字插入输入框，单次最长 5 分钟。浏览器会先请求麦克风权限。
+
+两者都由本机服务调用语音服务，手机等其他设备经已配对电脑使用，电脑关机时不可用。
+
+## 权限
+
+项目权限按程序启动的 CLI 与 API 成员设置，默认只读；可选只读、可写、自动、全放开，软件不支持的档位灰显（agy 后台不支持自动，API 只有只读和可写）。只读档预先放行读写房间的 `codiscuss` 命令和答案草稿，可写档允许修改项目、运行命令；自动档由软件审核操作，全放开跳过权限确认。具体范围见档位的悬停说明。Codex 使用原生沙箱，agy 使用独立项目规则，Claude Code 中你已有的授权仍然生效；手动启动成员的权限沿用原会话设置。
+
+## 常驻讨论服务
+
+`codiscuss local open` 会同时启动讨论服务。一个服务托管所有房间；停止服务会暂停它托管的讨论。
+
+| 操作 | 命令 |
+| --- | --- |
+| 打开本机网站 | `codiscuss local open` |
+| 查看状态 | `codiscuss local status` |
+| 停止 | `codiscuss local stop` |
+| 重启讨论服务（使新环境变量生效；Windows 上读取系统设置或 `setx` 保存的最新值，在旧终端执行也可，PATH 除外） | `codiscuss service restart` |
+| 登录时自动启动（Windows） | `codiscuss service autostart on` |
+
+## 命令行
+
+主持人可用 `codiscuss review roster ROOM` 查看本机服务上报的只读评审候选，当前限程序启动的 Codex CLI。此命令只读配置事实，不会自动派发评审；已有授权仍须在实际投递时核对。
+
+读取后，派实现任务可携带 `--next-review NAME --review-scope 范围 --review-roster REVISION`，将下一步评审绑定本批次；评审者不能同时是本批实现者。批次完成后，主持人先用 `review ready ROOM --batch ID` 核对完整交付，再用 `review advance ROOM --batch ID --revision REV --submission-id UUID --as 本人` 推进既定评审；不能推进时会说明原因。开启智能调度后可代办这一步；没有配置、判断失败或把握不足时仍交主持人。
+
+`codiscuss` 同时供 AI 读写房间。`codiscuss --help` 列出全部命令，`codiscuss schema <命令>` 显示字段，都可离线使用。
+
+讨论与普通协作统一读取请求并提交回答。成员回答使用 `message post --kind chat`，自动任务绑定 `--execution`，手动回答绑定 `--request`；主持人先读 `turn roster`，再带返回的 revision 创建或继续安排。讨论开关先用 `run view` 读取 revision，再执行开始、暂停、继续或结束；具体字段以命令帮助和房间协议为准。主持任务附有调度建议时，可用 `state decision ROOM DECISION_ID` 读取对应原判断；建议注明未生效时仍由主持人自行决定。
+
+## 常见问题
+
+- **软件送达失败**：查看成员状态与原位失败卡，在对应软件中处理登录或权限；倒计时期间可以立即重试或停止。本机接入程序重启或异常退出、导致进行中的软件进程随之结束时，同样自动重新投递同一执行，间隔缩短为 5 秒，并在原会话里告知成员这是续跑、已做完的部分不必重做。三次重试用尽后，讨论专家的失败交给主持人处理；也可跳过本次发言。
+- **Codex 提示会话被占用**：原聊天仍被 Codex App 占用，可在进度看板切换到 App 接入。
+- **Windows 报告两处数据路径**：从普通终端管理服务，或设置环境变量 `DISCUSS_SERVICE_HOME`。
+- **结果不明**：已交付但无法确认的任务不会自动重发，请先在原会话与房间中核对。

package/docs/workflow.md

@@ -69,7 +69,7 @@ Goal 不扩大权限：主持人仍受成员项目权限和连续派活轮数限
 建房时可在“智能调度”下添加一个决策模型（TypeSafe Jev；OpenAI Decisions 为实验性），用你自己的密钥按次计费。开启后，常规分派由决策模型判断，不必每次唤醒主持人：
 
 - 未点名的消息：明确对某位成员说时直接交给他，或请全体同时回答、按发言顺序依次回答（如接龙、报数）、无需回应；其余仍交给主持人。
-- `@全体成员`：未配置时同时回答；配置后判断同时或依次，拿不准或调用失败时交主持人。`@全体依次` 始终按既定顺序回答。
+- `@全体成员` 始终同时回答，不经智能调度判断；`@全体依次` 始终按既定顺序回答。
 - 讨论中：局部追问转为不计轮次的普通提问，可追问已发言者或主持人，保留原讨论队列；轮次之间选出下一位发言人。没有智能调度时，主持人也可按同一方式转交。
 - Goal 进行中、房间空闲时：判断最近的回答是否已在等你回复（向你提问、请你授权或拍板、已汇报完成）。有把握时不唤醒主持人，等你回复；拿不准或调用失败时照常唤醒。
 - 循环接力每走完一圈时：判断本圈最后一位（通常是评审）是否明确要求返工，有把握才自动开始下一圈；认可、需要取舍或拿不准时交主持人验收。它不评价作品本身，也不改成员顺序。