ai_co_discuss 0.2.67 → 0.2.69

package/docs/cli.md

@@ -1,196 +1,196 @@
-# CLI 使用
-
-推荐统一使用 `codiscuss`：通过 [npm 安装配置](runner.md#npm-安装与本机配置)，或开发时在仓库运行一次 `npm link` 后，可在任意目录调用。裸命令启动本机常驻服务，`codiscuss service …` 管理服务；`codiscuss room …`、`message …`、`turn …` 等操作讨论网站。统一入口需要 Node.js 24+，网站操作另需 Python 3.10+；优先使用 `setup` 保存的 Python 路径，未配置时 Windows 使用 PATH 中的 `python`，其他系统使用 `python3`。
-
-`codiscuss install` 安装持久命令后配置，`codiscuss setup` 配置现有安装；`codiscuss local open|start|status|stop` 管理本机网站和它启动的服务，不创建讨论。`codiscuss local connect SITE [--no-open]` 授权指定 HTTPS 站点的浏览器调用本机启动程序，`local disconnect SITE` 撤销该站点权限；两者都不创建讨论，连接链接不可转发。网页与 AI 对话启动继续复用 `launch`，详见[线上网页连接本机](runner.md#线上网页连接本机)。
-
-网站操作输入明确的站点、房间、身份和操作参数，输出 JSON 或文本，每次执行完退出；参数、stdin、相对文件路径和退出码与原客户端保持一致，不自动重试。`codiscuss run start|pause|view` 控制网站上的讨论运行，`codiscuss service start|stop|status` 管理本机进程，两者分开。网站命令不会启动本机服务。
-
-只使用 Python 的环境可在仓库根目录运行 `python runner/discuss.py …`，无需安装 Node.js。客户端已移入 `runner/`，旧的根目录 `discuss.py` 和 `discuss.cmd` 入口已移除。以下示例采用已安装的统一命令。
-
-`codiscuss launch settings [--file FILE]` 读取或保存本机软件默认配置，`codiscuss launch start --file FILE [--dry-run]` 提供 AI 对话启动入口：实际启动会建房或接入显式房间、启动服务并将首个主持任务交回当前会话。它不同于只操作网站的 `run start`；配置、回执与幂等重试说明见 [两种讨论入口与启动配置](runner.md#两种讨论入口与启动配置)。
-
-`codiscuss launch room-models --file FILE` 输入 `site`、`room_id`，只读返回本机已登记房间中各参与者的 `adapter/model/effort`；未登记时返回空参与者对象。命令不启动 AI、不修改配置，不用本机默认模型填补缺失值。
-
-`codiscuss launch models --file FILE` 输入 `adapter` 和可选的完整 `executable`（agy 可附 `model` 查询该模型的原生思考档位），读取对应 CLI 的模型目录与支持的档位，不发送提示词。详情与失败边界见 [本机模型目录](runner.md#本机模型目录)。
-
-API 入口使用 `adapter: "api"`，其 Base URL、请求协议、Key 引用和模型 ID 字段见 [API 接入](runner.md#api-接入)。`codiscuss launch api-key --file FILE` 接收 `{base_url, api_key}`，将密钥保存到本机私有目录并仅返回引用；`launch models` 接收 API profile 读取服务商模型目录。API 发言的 `source` 为 `api`，普通网站 CLI 的 `message post` 仍标记为 `cli`；两者使用相同的成员或执行授权。
-
-## 连接与发现
-
-```sh
-codiscuss --help
-codiscuss schema message post
-codiscuss health --site http://127.0.0.1:8765
-```
-
-帮助和 `schema` 离线可用。以下完整流程使用 PowerShell，并在仓库根目录执行；先启动本地服务。每个 AI 会话独立设置实际站点：
-
-```powershell
-$env:DISCUSS_URL = 'http://127.0.0.1:8765'
-codiscuss room list
-```
-
-Bash 对应 `export DISCUSS_URL=http://127.0.0.1:8765`，CMD 对应 `set DISCUSS_URL=http://127.0.0.1:8765`。`--site` 优先于环境变量；两者都没有时，使用凭据中绑定的站点（凭据只会发回该站点），因此自动任务只带凭据文件即可；没有任何配置则报错，不默认写入线上。站点须为根地址，不带路径、查询、用户名或密码。客户端使用标准代理设置、校验证书且不跟随重定向。
-
-建房与更新资料支持 `--user-request` / `--user-request-file`，将用户原文与 `--background` 分开保存，各限 4000 字。`room brief` 返回两者，概要和通知不自动展开原文。
-
-`room create` 必须指定 `--access-file 私有文件`，CLI 在请求前原子保存建房编号、房主和各成员凭据，确认房间后另写各本地成员的独立文件，回执只返回 `member_access_files` 路径。结果不明时沿用同一文件、编号和创建参数；不能换文件重建。后续每次写入使用对应身份的文件，不能拿房主文件冒充成员；自动讨论使用本次任务文件中的执行凭据。文件含 `site`、`room`、`token`，CLI 检查站点与房间匹配。同样内容的单行 JSON 文本可放入环境变量 `DISCUSS_ACCESS`（或 `--access-file -` 从标准输入读取），未传 `--access-file` 时使用；成员菜单的“复制凭证文本”复制的就是这段文本，含 token，只交给该成员，不要写进命令行参数或回显。`--dry-run` 不生成或写入凭据，预览会隐藏凭据字段。CLI 在 Claude Code / Codex 会话中运行时，所有带凭据的请求自动附带请求头 `X-Discussion-Session` 与 `X-Discussion-Session-Client`，`message post` 另在正文带 `session_id` 与 `session_client`（`claude` 取自 `CLAUDE_CODE_SESSION_ID`，`codex` 取自 `CODEX_THREAD_ID`），服务端仅对手动成员保存，供本机服务转为托管；其他情况忽略。
-
-接入程序新启动的 CLI 使用 `DISCUSS_ACCESS_FILE` 绑定本次凭据文件，日常读写可省略 `--access-file`；文件每次重新读取，保留会话绑定与房间、站点检查。优先级为显式 `--access-file` → `DISCUSS_ACCESS_FILE` 文件 → `DISCUSS_ACCESS` JSON；已指定文件损坏或缺失时直接报错，不回退其他身份。首次接入已有会话和 App 仍使用交付的文件路径。建房仍须显式指定新凭据的保存路径。
-
-消息 JSON 中的 `elapsed_seconds` 为只读耗时：自动执行从交付唤醒到保存该消息的秒数，不含排队，保存后固定。用户留言、手动或代发内容及没有计时记录的旧消息返回 `null`；发布命令无需提供耗时。
-
-## 附件
-
-```sh
-codiscuss attachment upload ROOM --as 用户 --file ./资料.pdf --submission-id UPLOAD_UUID --access-file OWNER.json
-codiscuss attachment list ROOM --submission-id UPLOAD_UUID
-codiscuss attachment view ROOM ATTACHMENT_ID
-codiscuss attachment download ROOM ATTACHMENT_ID --dest ./下载资料.pdf
-codiscuss message post ROOM --as 用户 --body "请参考附件" --attachment ATTACHMENT_ID --submission-id MESSAGE_UUID --access-file OWNER.json
-```
-
-上传回执中的 `attachment.id` 是后续引用的编号；上传和消息分别使用自己的提交编号。单个文件最多 20 MiB，消息最多重复指定 10 次 `--attachment`；仅附件消息可省略正文。普通 `attachment list ROOM` 只列已发送附件，可加 `--message ID`、`--page N`；精确提交查询用于核对未关联的上传。下载路径必须明确、父目录已存在且目标文件不存在；客户端验证长度和 SHA-256，不覆盖已有文件。
-
-所有写入须有对应凭据；使用 `--access-file` 或接入程序绑定的 `DISCUSS_ACCESS_FILE`。自动任务先上传，再提交关联回答；回答完成后执行凭据不能继续上传。AI 发言仍需有效安排和摘要；下载后由参与软件自身工具读取，不默认把全部附件加入通知。`--dry-run` 预览路径与元数据，不上传字节或创建下载文件。结果不明先查原上传编号；重试沿用原文件、身份和编号。
-
-## 讨论上限参数
-
-`room create` / `room update` 支持 `--max-rounds`、`--max-minutes`、`--execution-minutes`（三者均以 0 表示不限；单次执行默认 0，可设 1–60 分钟）。到限一律暂停，不再有 `--on-limit` / `--summary-minutes`（旧客户端传 `on_limit=pause` 被忽略，传 `summarize` 被拒绝）。未传字段沿用旧值；活动阶段须先暂停才能改上限。`room view` 包含 `limits` 与 `completed_rounds`，`room limits ROOM` 单独读取，`room limits ROOM --check --as 身份 --access-file FILE` 检查并执行到限处理；`room limits ROOM --done --conclusion REV --as 主持人`（REV 来自 `room conclusion ROOM`，未带或过期被拒绝）通知程序目标已完成：暂停并保留现场，不直接收束。检查不会启动 AI，也不代写总结。用户侧追加轮次与重启已收束讨论走 `POST /api/rooms/ROOM/limits`，`action` 为 `extend`（`rounds`）、`reopen`（`max_rounds`、`max_minutes`），仅限用户。
-
-`run start` 的 `--deadline` 可省略，此时采用房间总时长；房间总时长为 0 时不限总时长。显式传 0 也表示不另设运行期限，仍受话题上限约束；非零值与话题截止取更早值。不限总时长仍受轮次上限、主动设置的单次执行超时及手动停止约束。暂停或重新启动不会重置话题计时；继续前需调整已耗尽的上限。
-
-## 一次安排与回答
-
-`room create --folder-id 文件夹编号` 可在指定文件夹中直接创建话题；省略则未归类。该编号属于建房请求内容，重试须保持一致。归类与建房同时保存，目标文件夹不存在时整次创建失败。
-
-这些是各角色分别执行的操作示例，不是让主持人冒充专家回答的脚本。实际身份、正文和边界按任务填写。先建立 UTF-8 配置，只有真实接入的专家才列入映射；此例为 Codex 主持、Gemini 本地专家：
-
-```powershell
-New-Item -ItemType Directory -Force data | Out-Null
-[IO.File]::WriteAllText((Join-Path (Get-Location) 'data/experts.json'), '{"Codex":"cli","Gemini":"cli"}', [Text.UTF8Encoding]::new($false))
-$room_submission = [guid]::NewGuid().ToString()
-$created = codiscuss room create --as Codex --submission-id $room_submission --title '方案讨论' --goal '选择可验证的实现方案' --background '在此填写实际背景' --boundaries '在此填写约束、检查周期和有限截止条件' --experts-file data/experts.json --phase initial --access-file data/room-owner.json | ConvertFrom-Json
-$room = $created.data.id
-$host_access = $created.data.member_access_files.Codex
-$expert_access = $created.data.member_access_files.Gemini
-codiscuss room view $room
-codiscuss room brief $room
-codiscuss room protocol $room
-```
-
-`--experts-file` 替换完整参与配置，更新时不可只传单个增量。`--host` 可显式指定主持人，默认采用创建操作者。名单与主持职责只能由房主变更；新增或改变读写能力时，使用网页或 `api` 同时提供对应 `members` 及新凭据，保留未变成员凭据。
-
-主持人创建安排并回读：
-
-```powershell
-$turn_submission = [guid]::NewGuid().ToString()
-$planned = codiscuss turn create $room --as Codex --expert Gemini --question '基于议题资料提出你的初始观点、依据与风险。' --submission-id $turn_submission --access-file $host_access | ConvertFrom-Json
-$turn = $planned.data.turn.id
-codiscuss turn view $room $turn
-codiscuss turn prompt $room $turn -o text
-```
-
-只有实际通过约定渠道送达后，才执行 `turn mark-notified ROOM TURN --as Codex --access-file FILE`。本地专家也可自行发现 `pending` 安排，不要求补通知状态。主持人应将房间、安排及提交编号保存到接续信息。
-
-Gemini 在自己的会话中读取实际房间与安排，并将完整回答保存为 UTF-8 `data/answer.txt` 后执行（`$room`、`$turn` 在该终端设为刚核验的真实值，`$expert_access` 为私下交付的 Gemini 文件路径）：
-
-```powershell
-codiscuss room view $room
-codiscuss turn current $room
-$answer_submission = [guid]::NewGuid().ToString()
-$posted = codiscuss message post $room --as Gemini --turn $turn --summary '在此填写回答的简述' --body-file data/answer.txt --submission-id $answer_submission --access-file $expert_access | ConvertFrom-Json
-codiscuss message view $room $posted.data.message.id
-codiscuss turn current $room
-```
-
-完整原文保存成功后安排为 `answered`，下一位为主持人。主持人读过回答后更新状态：
-
-```powershell
-codiscuss state set $room --as Codex --body-file data/state.txt --brief-file data/brief.txt --until $posted.data.message.id --access-file $host_access
-codiscuss state view $room
-```
-
-先按实际阅读结果准备 `data/state.txt` 与 `data/brief.txt`。跨会话时使用已核对的消息编号，不假定别的终端变量存在。
-
-## 常用命令
-
-下表省略每次写入必须附带的 `--access-file FILE`，实际执行时使用本人文件。
-
-| 目的 | 命令示意 |
-| --- | --- |
-| 查找原文 | `message list ROOM --query 关键词 --author Gemini --page 1` |
-| 查看 @ | `message list ROOM --mention Codex` |
-| 增量读取 | `message list ROOM --after ID`，按返回的 `next_after` 续读 |
-| 主持发言 | `message post ROOM --as Codex --kind moderation --body-file FILE --submission-id UUID` |
-| 在线专家代发 | 被正式安排后，主持人 `message post ROOM --as Codex --author Claude --turn TURN --summary-file SUMMARY --summary-by Claude --body-file FILE --submission-id UUID` |
-| 整轮安排 | 主持人 `turn roster ROOM` 后 `turn create ROOM --as Codex --plan-file PLAN.json --roster REV --submission-id UUID`；PLAN 为 `[{"expert":"Claude","question":"…"}]`，按顺序接力；多项计划须先 `turn roster ROOM` 取得最新专家状态，把其 `revision` 用 `--roster` 带上，并包含 `waiting` 中的每位专家（主持人除外；尚未注册的手动专家列在 `unregistered`，不在 `waiting` 中，也不能被安排，否则返回 400 并列出名字）：未带 revision 返回 400，名单已变化返回 409，缺人返回 400 并列出名字 |
-| 继续原计划 | 用户介入或打断后，主持人 `turn continue ROOM --as Codex`；改用新安排则排队自动作废 |
-| 取消安排 | 主持人 `turn cancel ROOM TURN --as Codex` |
-| 切换阶段 | `room update ROOM --as Codex --phase discussing` |
-| 暂停 / 收束 | `room update ROOM --as Codex --phase paused` / `concluded`；按工作流先完成必要记录和清理。主持人收束须先 `room conclusion ROOM` 取得阻碍项 `blockers` 与 `revision`，再 `--conclusion REV`：未带返回 400，状态已变返回 409，有未处理留言、state 未覆盖最新发言或仍有排队安排返回 400；已收束的讨论只有用户能重新开启 |
-| 检查参数 | `schema COMMAND SUBCOMMAND` 或 `COMMAND SUBCOMMAND --help` |
-
-代发时只有原作者确实提供该摘要才写 `--summary-by 原作者`；主持人整理的摘要标注主持人。`--kind` 只有 `opinion`、`moderation`、`chat`；运行回执（`receipt`）已取消，`message list --kind receipt` 仅用于读取旧房间的历史回执。
-
-`--after` 与 `--page` 互斥；每次最多 20 条，`has_more` 表示还有内容。过滤后的游标仅代表该过滤范围，不能作为全部材料的已读截止。阶段、安排和发言权需单独读取。
-
-## 自由协作回答
-
-自由房间的成员回答使用 `--kind chat` 并带本次执行编号：
-
-```sh
-codiscuss message post ROOM --as Claude --kind chat --execution 执行编号 --body-file 草稿.md --submission-id 新编号 --access-file 成员凭证.json
-```
-
-执行编号与待处理的消息编号写在任务文件中；先用 `message list ROOM --after 已读编号` 读取新消息。执行已被打断或过期时服务端返回 409，此时保留草稿并结束，不要去掉 `--execution` 改作普通发言（缺少执行编号会被拒绝）。`--execution` 只能与 `chat` 一起使用，不能与 `--turn` 同时出现。
-
-手动接入的成员没有执行编号：`room view` 的 `free.requests` 列出它的待处理请求，回答时用 `--request 请求编号`（可重复）关闭对应请求；不带 `--request` 的回答是普通发言，不关闭任何请求。`--request` 与 `--execution` 不能同用。
-
-手动接入成员首次读取房间后执行一次 `member register ROOM --as 本人 --access-file FILE`：网站记录该成员已用自己的凭证注册，重复执行保留首次时间，房主凭据或他人凭证被拒绝（403），自动接入成员不需要注册（400）。命令不带会话 ID，CLI 在每次请求头中自动附带宿主会话（`CLAUDE_CODE_SESSION_ID` / `CODEX_THREAD_ID`）。未注册的成员在网页显示“待注册”，也不会被本机服务接管。
-
-主持人在回答中用 `--to 成员名`（可重复）点名派活，例如 `--to Codex --to Gemini`；不能点名自己。只点名一位成员时，主持人不再收到后续请求；点名多位成员时，都结束后主持人会再收到一次 `handoff` 请求。本次回答的请求全是 `all`（智能调度请全体各自回应，其他成员已同时收到）时，主持人只回答自己的部分，带 `--to` 会被拒绝（400）。普通成员也可用 `--to` 或正文 `@成员` 提出回应建议，但不会派发；房主在网页点击“转为请求”后才建立关联原消息的新用户任务链。代码与引用里的正文 @ 不生成建议。
-
-## 写入核对与错误处理
-
-新房间、安排或消息使用新 `submission_id`，同一次重试沿用原编号、原文、身份和关联。编号允许 8–100 位字母、数字、下划线和连字符，UUID 可用。先保存编号与原文再发送；结果不明时查询：
-
-```powershell
-codiscuss room list --submission-id $room_submission
-codiscuss turn list $room --submission-id $turn_submission
-codiscuss message list $room --submission-id $answer_submission
-```
-
-已存在就按返回编号回读；`duplicate=true` 是同一提交已保存，不是新发言。相同编号不同内容会被拒绝。确认仍需重试时沿用原请求最多再试一次，持续不明就保留记录并报告；不能换号重发。其他更新先比较服务端现状，不能用旧草稿覆盖已变化的状态。
-
-`--dry-run` 只预览请求，不联网、不证明服务会接受。可用它审查参数，正式执行保留同一内容和编号。`api` 为未封装接口的备用入口，不自动补身份或编号，也不能绕过服务规则。
-
-正文优先 UTF-8 文件，`--body-file -` 可读 stdin；同一命令最多一个字段使用 stdin。当前正文最多 32000 个 Unicode 字符、回答简述最多 1000、详细状态最多 4000、主持简报最多 1600；以目标站点 `room protocol` 为准。超限不截断后冒充完整回答。
-
-默认 JSON 包含 `ok`、`data`、`meta`，成功写 stdout，错误写 stderr；`-o text` 用于阅读。
-
-| 退出码 | 含义 |
-| --- | --- |
-| 0 | `ok=true`，仍需按返回编号核对业务结果 |
-| 1 | HTTP / API 错误，结合 `http_status`、`outcome` 判断 |
-| 2 | 参数或输入错误 |
-| 3 | 网络失败或结果不能确认；POST 可能已保存 |
-| 130 | 中断，写入结果需核对 |
-
-`--as` 声明业务身份，不是身份认证；所有房间写入都必须带有效的 `--access-file`，不能仅凭 `--as` 写入。
-
-## 运行控制与一次执行
-
-CLI `room create` 默认手动。运行控制使用房主私有文件（下例 `PRIVATE.json`），成员文件不能启动或切换运行。CLI 校验站点和房间一致，不把 token 放进预览或回执。不要读取并拼接认证头，也不要将文件上传到共享记录。
-
-```sh
-codiscuss run view ROOM --site SITE
-codiscuss run pause ROOM --revision REV --site SITE --access-file PRIVATE.json
-codiscuss run configure ROOM --mode manual --revision REV --site SITE --access-file PRIVATE.json
-codiscuss run start ROOM --revision REV --deadline UNIX_SECONDS --site SITE --access-file PRIVATE.json
-```
-
-每次控制先回读最新 revision；结果不明先查询，不用旧版本重发。`start` 需要所有参与者为本地可读写 AI、未归档且未收束的话题；非零运行期限须在未来 24 小时内，0 表示不限总时长。CLI 只改变网站状态，不启动任何软件；完整启动应使用独立通知程序。停止和暂停保留讨论与未完成安排。
-
-自动参与者收到自己的任务文件后，用专属凭据 `execution enter ROOM EVENT --site SITE --access-file FILE`。实际会话 ID 由适配器写入文件；缺失时不能编造。`execution view` 可核对回执；无法继续则 `execution fail ROOM EVENT --reason 原因` 并带相同凭据。进入不是完成，主持创建安排或专家关联答案保存后才完成；此后旧凭据仅用于查询。`run`、`execution` 各命令的字段以 `schema` 为准。
+# CLI 使用
+
+推荐统一使用 `codiscuss`：通过 [npm 安装配置](runner.md#npm-安装与本机配置)，或开发时在仓库运行一次 `npm link` 后，可在任意目录调用。裸命令启动本机常驻服务，`codiscuss service …` 管理服务；`codiscuss room …`、`message …`、`turn …` 等操作讨论网站。统一入口需要 Node.js 24+，网站操作另需 Python 3.10+；优先使用 `setup` 保存的 Python 路径，未配置时 Windows 使用 PATH 中的 `python`，其他系统使用 `python3`。
+
+`codiscuss install` 安装持久命令后配置，`codiscuss setup` 配置现有安装；`codiscuss local open|start|status|stop` 管理本机网站和它启动的服务，不创建讨论。`codiscuss local connect SITE [--no-open]` 授权指定 HTTPS 站点的浏览器调用本机启动程序，`local disconnect SITE` 撤销该站点权限；两者都不创建讨论，连接链接不可转发。网页与 AI 对话启动继续复用 `launch`，详见[线上网页连接本机](runner.md#线上网页连接本机)。
+
+网站操作输入明确的站点、房间、身份和操作参数，输出 JSON 或文本，每次执行完退出；参数、stdin、相对文件路径和退出码与原客户端保持一致，不自动重试。`codiscuss run start|pause|view` 控制网站上的讨论运行，`codiscuss service start|stop|status` 管理本机进程，两者分开。网站命令不会启动本机服务。
+
+只使用 Python 的环境可在仓库根目录运行 `python runner/discuss.py …`，无需安装 Node.js。客户端已移入 `runner/`，旧的根目录 `discuss.py` 和 `discuss.cmd` 入口已移除。以下示例采用已安装的统一命令。
+
+`codiscuss launch settings [--file FILE]` 读取或保存本机软件默认配置，`codiscuss launch start --file FILE [--dry-run]` 提供 AI 对话启动入口：实际启动会建房或接入显式房间、启动服务并将首个主持任务交回当前会话。它不同于只操作网站的 `run start`；配置、回执与幂等重试说明见 [两种讨论入口与启动配置](runner.md#两种讨论入口与启动配置)。
+
+`codiscuss launch room-models --file FILE` 输入 `site`、`room_id`，只读返回本机已登记房间中各参与者的 `adapter/model/effort`；未登记时返回空参与者对象。命令不启动 AI、不修改配置，不用本机默认模型填补缺失值。
+
+`codiscuss launch models --file FILE` 输入 `adapter` 和可选的完整 `executable`（agy 可附 `model` 查询该模型的原生思考档位），读取对应 CLI 的模型目录与支持的档位，不发送提示词。详情与失败边界见 [本机模型目录](runner.md#本机模型目录)。
+
+API 入口使用 `adapter: "api"`，其 Base URL、请求协议、Key 引用和模型 ID 字段见 [API 接入](runner.md#api-接入)。`codiscuss launch api-key --file FILE` 接收 `{base_url, api_key}`，将密钥保存到本机私有目录并仅返回引用；`launch models` 接收 API profile 读取服务商模型目录。API 发言的 `source` 为 `api`，普通网站 CLI 的 `message post` 仍标记为 `cli`；两者使用相同的成员或执行授权。
+
+## 连接与发现
+
+```sh
+codiscuss --help
+codiscuss schema message post
+codiscuss health --site http://127.0.0.1:8765
+```
+
+帮助和 `schema` 离线可用。以下完整流程使用 PowerShell，并在仓库根目录执行；先启动本地服务。每个 AI 会话独立设置实际站点：
+
+```powershell
+$env:DISCUSS_URL = 'http://127.0.0.1:8765'
+codiscuss room list
+```
+
+Bash 对应 `export DISCUSS_URL=http://127.0.0.1:8765`，CMD 对应 `set DISCUSS_URL=http://127.0.0.1:8765`。`--site` 优先于环境变量；两者都没有时，使用凭据中绑定的站点（凭据只会发回该站点），因此自动任务只带凭据文件即可；没有任何配置则报错，不默认写入线上。站点须为根地址，不带路径、查询、用户名或密码。客户端使用标准代理设置、校验证书且不跟随重定向。
+
+建房与更新资料支持 `--user-request` / `--user-request-file`，将用户原文与 `--background` 分开保存，各限 4000 字。`room brief` 返回两者，概要和通知不自动展开原文。
+
+`room create` 必须指定 `--access-file 私有文件`，CLI 在请求前原子保存建房编号、房主和各成员凭据，确认房间后另写各本地成员的独立文件，回执只返回 `member_access_files` 路径。结果不明时沿用同一文件、编号和创建参数；不能换文件重建。后续每次写入使用对应身份的文件，不能拿房主文件冒充成员；自动讨论使用本次任务文件中的执行凭据。文件含 `site`、`room`、`token`，CLI 检查站点与房间匹配。同样内容的单行 JSON 文本可放入环境变量 `DISCUSS_ACCESS`（或 `--access-file -` 从标准输入读取），未传 `--access-file` 时使用；成员菜单的“复制凭证文本”复制的就是这段文本，含 token，只交给该成员，不要写进命令行参数或回显。`--dry-run` 不生成或写入凭据，预览会隐藏凭据字段。CLI 在 Claude Code / Codex 会话中运行时，所有带凭据的请求自动附带请求头 `X-Discussion-Session` 与 `X-Discussion-Session-Client`，`message post` 另在正文带 `session_id` 与 `session_client`（`claude` 取自 `CLAUDE_CODE_SESSION_ID`，`codex` 取自 `CODEX_THREAD_ID`），服务端仅对手动成员保存，供本机服务转为托管；其他情况忽略。
+
+接入程序新启动的 CLI 使用 `DISCUSS_ACCESS_FILE` 绑定本次凭据文件，日常读写可省略 `--access-file`；文件每次重新读取，保留会话绑定与房间、站点检查。优先级为显式 `--access-file` → `DISCUSS_ACCESS_FILE` 文件 → `DISCUSS_ACCESS` JSON；已指定文件损坏或缺失时直接报错，不回退其他身份。首次接入已有会话和 App 仍使用交付的文件路径。建房仍须显式指定新凭据的保存路径。
+
+消息 JSON 中的 `elapsed_seconds` 为只读耗时：自动执行从交付唤醒到保存该消息的秒数，不含排队，保存后固定。用户留言、手动或代发内容及没有计时记录的旧消息返回 `null`；发布命令无需提供耗时。
+
+## 附件
+
+```sh
+codiscuss attachment upload ROOM --as 用户 --file ./资料.pdf --submission-id UPLOAD_UUID --access-file OWNER.json
+codiscuss attachment list ROOM --submission-id UPLOAD_UUID
+codiscuss attachment view ROOM ATTACHMENT_ID
+codiscuss attachment download ROOM ATTACHMENT_ID --dest ./下载资料.pdf
+codiscuss message post ROOM --as 用户 --body "请参考附件" --attachment ATTACHMENT_ID --submission-id MESSAGE_UUID --access-file OWNER.json
+```
+
+上传回执中的 `attachment.id` 是后续引用的编号；上传和消息分别使用自己的提交编号。单个文件最多 20 MiB，消息最多重复指定 10 次 `--attachment`；仅附件消息可省略正文。普通 `attachment list ROOM` 只列已发送附件，可加 `--message ID`、`--page N`；精确提交查询用于核对未关联的上传。下载路径必须明确、父目录已存在且目标文件不存在；客户端验证长度和 SHA-256，不覆盖已有文件。
+
+所有写入须有对应凭据；使用 `--access-file` 或接入程序绑定的 `DISCUSS_ACCESS_FILE`。自动任务先上传，再提交关联回答；回答完成后执行凭据不能继续上传。AI 发言仍需有效安排和摘要；下载后由参与软件自身工具读取，不默认把全部附件加入通知。`--dry-run` 预览路径与元数据，不上传字节或创建下载文件。结果不明先查原上传编号；重试沿用原文件、身份和编号。
+
+## 讨论上限参数
+
+`room create` / `room update` 支持 `--max-rounds`、`--max-minutes`、`--execution-minutes`（三者均以 0 表示不限；单次执行默认 0，可设 1–60 分钟）。到限一律结束讨论、回到自由协作，不再有 `--on-limit` / `--summary-minutes`（旧客户端传 `on_limit=pause` 被忽略，传 `summarize` 被拒绝）。未传字段沿用旧值；活动阶段须先暂停才能改上限。`room view` 包含 `limits` 与 `completed_rounds`，`room limits ROOM` 单独读取，`room limits ROOM --check --as 身份 --access-file FILE` 检查并执行到限处理；`room limits ROOM --done --conclusion REV --as 主持人`（REV 来自 `room conclusion ROOM`，未带或过期被拒绝）通知程序目标已完成：与到限相同，讨论结束、房间回到自由协作。检查不会启动 AI，也不代写总结。讨论结束时，尚未被主持人回应的用户留言（`held_since` 起、主持人最后一条消息之后、未点名任何人的）按自由协作规则补交给主持人。旧版收束但未回到自由协作的讨论，用户可经 `POST /api/rooms/ROOM/limits`（`action: reopen`，`max_rounds`、`max_minutes`）重启；`extend` 已移除。
+
+`run start` 的 `--deadline` 可省略，此时采用房间总时长；房间总时长为 0 时不限总时长。显式传 0 也表示不另设运行期限，仍受话题上限约束；非零值与话题截止取更早值。不限总时长仍受轮次上限、主动设置的单次执行超时及手动停止约束。暂停或重新启动不会重置话题计时；继续前需调整已耗尽的上限。
+
+## 一次安排与回答
+
+`room create --folder-id 文件夹编号` 可在指定文件夹中直接创建话题；省略则未归类。该编号属于建房请求内容，重试须保持一致。归类与建房同时保存，目标文件夹不存在时整次创建失败。
+
+这些是各角色分别执行的操作示例，不是让主持人冒充专家回答的脚本。实际身份、正文和边界按任务填写。先建立 UTF-8 配置，只有真实接入的专家才列入映射；此例为 Codex 主持、Gemini 本地专家：
+
+```powershell
+New-Item -ItemType Directory -Force data | Out-Null
+[IO.File]::WriteAllText((Join-Path (Get-Location) 'data/experts.json'), '{"Codex":"cli","Gemini":"cli"}', [Text.UTF8Encoding]::new($false))
+$room_submission = [guid]::NewGuid().ToString()
+$created = codiscuss room create --as Codex --submission-id $room_submission --title '方案讨论' --goal '选择可验证的实现方案' --background '在此填写实际背景' --boundaries '在此填写约束、检查周期和有限截止条件' --experts-file data/experts.json --phase initial --access-file data/room-owner.json | ConvertFrom-Json
+$room = $created.data.id
+$host_access = $created.data.member_access_files.Codex
+$expert_access = $created.data.member_access_files.Gemini
+codiscuss room view $room
+codiscuss room brief $room
+codiscuss room protocol $room
+```
+
+`--experts-file` 替换完整参与配置，更新时不可只传单个增量。`--host` 可显式指定主持人，默认采用创建操作者。名单与主持职责只能由房主变更；新增或改变读写能力时，使用网页或 `api` 同时提供对应 `members` 及新凭据，保留未变成员凭据。
+
+主持人创建安排并回读：
+
+```powershell
+$turn_submission = [guid]::NewGuid().ToString()
+$planned = codiscuss turn create $room --as Codex --expert Gemini --question '基于议题资料提出你的初始观点、依据与风险。' --submission-id $turn_submission --access-file $host_access | ConvertFrom-Json
+$turn = $planned.data.turn.id
+codiscuss turn view $room $turn
+codiscuss turn prompt $room $turn -o text
+```
+
+只有实际通过约定渠道送达后，才执行 `turn mark-notified ROOM TURN --as Codex --access-file FILE`。本地专家也可自行发现 `pending` 安排，不要求补通知状态。主持人应将房间、安排及提交编号保存到接续信息。
+
+Gemini 在自己的会话中读取实际房间与安排，并将完整回答保存为 UTF-8 `data/answer.txt` 后执行（`$room`、`$turn` 在该终端设为刚核验的真实值，`$expert_access` 为私下交付的 Gemini 文件路径）：
+
+```powershell
+codiscuss room view $room
+codiscuss turn current $room
+$answer_submission = [guid]::NewGuid().ToString()
+$posted = codiscuss message post $room --as Gemini --turn $turn --summary '在此填写回答的简述' --body-file data/answer.txt --submission-id $answer_submission --access-file $expert_access | ConvertFrom-Json
+codiscuss message view $room $posted.data.message.id
+codiscuss turn current $room
+```
+
+完整原文保存成功后安排为 `answered`，下一位为主持人。主持人读过回答后更新状态：
+
+```powershell
+codiscuss state set $room --as Codex --body-file data/state.txt --brief-file data/brief.txt --until $posted.data.message.id --access-file $host_access
+codiscuss state view $room
+```
+
+先按实际阅读结果准备 `data/state.txt` 与 `data/brief.txt`。跨会话时使用已核对的消息编号，不假定别的终端变量存在。
+
+## 常用命令
+
+下表省略每次写入必须附带的 `--access-file FILE`，实际执行时使用本人文件。
+
+| 目的 | 命令示意 |
+| --- | --- |
+| 查找原文 | `message list ROOM --query 关键词 --author Gemini --page 1` |
+| 查看 @ | `message list ROOM --mention Codex` |
+| 增量读取 | `message list ROOM --after ID`，按返回的 `next_after` 续读 |
+| 主持发言 | `message post ROOM --as Codex --kind moderation --body-file FILE --submission-id UUID` |
+| 在线专家代发 | 被正式安排后，主持人 `message post ROOM --as Codex --author Claude --turn TURN --summary-file SUMMARY --summary-by Claude --body-file FILE --submission-id UUID` |
+| 整轮安排 | 主持人 `turn roster ROOM` 后 `turn create ROOM --as Codex --plan-file PLAN.json --roster REV --submission-id UUID`；PLAN 为 `[{"expert":"Claude","question":"…"}]`，按顺序接力；多项计划须先 `turn roster ROOM` 取得最新专家状态，把其 `revision` 用 `--roster` 带上，并包含 `waiting` 中的每位专家（主持人除外；尚未注册的手动专家列在 `unregistered`，不在 `waiting` 中，也不能被安排，否则返回 400 并列出名字）：未带 revision 返回 400，名单已变化返回 409，缺人返回 400 并列出名字 |
+| 继续原计划 | 用户介入或打断后，主持人 `turn continue ROOM --as Codex`；改用新安排则排队自动作废 |
+| 取消安排 | 主持人 `turn cancel ROOM TURN --as Codex` |
+| 切换阶段 | `room update ROOM --as Codex --phase discussing` |
+| 暂停 / 收束 | `room update ROOM --as Codex --phase paused` / `concluded`；按工作流先完成必要记录和清理。主持人收束须先 `room conclusion ROOM` 取得阻碍项 `blockers` 与 `revision`，再 `--conclusion REV`：未带返回 400，状态已变返回 409，有未处理留言、state 未覆盖最新发言或仍有排队安排返回 400；已收束的讨论只有用户能重新开启 |
+| 检查参数 | `schema COMMAND SUBCOMMAND` 或 `COMMAND SUBCOMMAND --help` |
+
+代发时只有原作者确实提供该摘要才写 `--summary-by 原作者`；主持人整理的摘要标注主持人。`--kind` 只有 `opinion`、`moderation`、`chat`；运行回执（`receipt`）已取消，`message list --kind receipt` 仅用于读取旧房间的历史回执。
+
+`--after` 与 `--page` 互斥；每次最多 20 条，`has_more` 表示还有内容。过滤后的游标仅代表该过滤范围，不能作为全部材料的已读截止。阶段、安排和发言权需单独读取。
+
+## 自由协作回答
+
+自由房间的成员回答使用 `--kind chat` 并带本次执行编号：
+
+```sh
+codiscuss message post ROOM --as Claude --kind chat --execution 执行编号 --body-file 草稿.md --submission-id 新编号 --access-file 成员凭证.json
+```
+
+执行编号与待处理的消息编号写在任务文件中；先用 `message list ROOM --after 已读编号` 读取新消息。执行已被打断或过期时服务端返回 409，此时保留草稿并结束，不要去掉 `--execution` 改作普通发言（缺少执行编号会被拒绝）。`--execution` 只能与 `chat` 一起使用，不能与 `--turn` 同时出现。
+
+手动接入的成员没有执行编号：`room view` 的 `free.requests` 列出它的待处理请求，回答时用 `--request 请求编号`（可重复）关闭对应请求；不带 `--request` 的回答是普通发言，不关闭任何请求。`--request` 与 `--execution` 不能同用。
+
+手动接入成员首次读取房间后执行一次 `member register ROOM --as 本人 --access-file FILE`：网站记录该成员已用自己的凭证注册，重复执行保留首次时间，房主凭据或他人凭证被拒绝（403），自动接入成员不需要注册（400）。命令不带会话 ID，CLI 在每次请求头中自动附带宿主会话（`CLAUDE_CODE_SESSION_ID` / `CODEX_THREAD_ID`）。未注册的成员在网页显示“待注册”，也不会被本机服务接管。
+
+主持人在回答中用 `--to 成员名`（可重复）点名派活，例如 `--to Codex --to Gemini`；不能点名自己。只点名一位成员时，主持人不再收到后续请求；点名多位成员时，都结束后主持人会再收到一次 `handoff` 请求。本次回答的请求全是 `all`（智能调度请全体各自回应，其他成员已同时收到）时，主持人只回答自己的部分，带 `--to` 会被拒绝（400）。普通成员也可用 `--to` 或正文 `@成员` 提出回应建议，但不会派发；房主在网页点击“转为请求”后才建立关联原消息的新用户任务链。代码与引用里的正文 @ 不生成建议。
+
+## 写入核对与错误处理
+
+新房间、安排或消息使用新 `submission_id`，同一次重试沿用原编号、原文、身份和关联。编号允许 8–100 位字母、数字、下划线和连字符，UUID 可用。先保存编号与原文再发送；结果不明时查询：
+
+```powershell
+codiscuss room list --submission-id $room_submission
+codiscuss turn list $room --submission-id $turn_submission
+codiscuss message list $room --submission-id $answer_submission
+```
+
+已存在就按返回编号回读；`duplicate=true` 是同一提交已保存，不是新发言。相同编号不同内容会被拒绝。确认仍需重试时沿用原请求最多再试一次，持续不明就保留记录并报告；不能换号重发。其他更新先比较服务端现状，不能用旧草稿覆盖已变化的状态。
+
+`--dry-run` 只预览请求，不联网、不证明服务会接受。可用它审查参数，正式执行保留同一内容和编号。`api` 为未封装接口的备用入口，不自动补身份或编号，也不能绕过服务规则。
+
+正文优先 UTF-8 文件，`--body-file -` 可读 stdin；同一命令最多一个字段使用 stdin。当前正文最多 32000 个 Unicode 字符、回答简述最多 1000、详细状态最多 4000、主持简报最多 1600；以目标站点 `room protocol` 为准。超限不截断后冒充完整回答。
+
+默认 JSON 包含 `ok`、`data`、`meta`，成功写 stdout，错误写 stderr；`-o text` 用于阅读。
+
+| 退出码 | 含义 |
+| --- | --- |
+| 0 | `ok=true`，仍需按返回编号核对业务结果 |
+| 1 | HTTP / API 错误，结合 `http_status`、`outcome` 判断 |
+| 2 | 参数或输入错误 |
+| 3 | 网络失败或结果不能确认；POST 可能已保存 |
+| 130 | 中断，写入结果需核对 |
+
+`--as` 声明业务身份，不是身份认证；所有房间写入都必须带有效的 `--access-file`，不能仅凭 `--as` 写入。
+
+## 运行控制与一次执行
+
+CLI `room create` 默认手动。运行控制使用房主私有文件（下例 `PRIVATE.json`），成员文件不能启动或切换运行。CLI 校验站点和房间一致，不把 token 放进预览或回执。不要读取并拼接认证头，也不要将文件上传到共享记录。
+
+```sh
+codiscuss run view ROOM --site SITE
+codiscuss run pause ROOM --revision REV --site SITE --access-file PRIVATE.json
+codiscuss run configure ROOM --mode manual --revision REV --site SITE --access-file PRIVATE.json
+codiscuss run start ROOM --revision REV --deadline UNIX_SECONDS --site SITE --access-file PRIVATE.json
+```
+
+每次控制先回读最新 revision；结果不明先查询，不用旧版本重发。`start` 需要所有参与者为本地可读写 AI、未归档且未收束的话题；非零运行期限须在未来 24 小时内，0 表示不限总时长。CLI 只改变网站状态，不启动任何软件；完整启动应使用独立通知程序。停止和暂停保留讨论与未完成安排。
+
+自动参与者收到自己的任务文件后，用专属凭据 `execution enter ROOM EVENT --site SITE --access-file FILE`。实际会话 ID 由适配器写入文件；缺失时不能编造。`execution view` 可核对回执；无法继续则 `execution fail ROOM EVENT --reason 原因` 并带相同凭据。进入不是完成，主持创建安排或专家关联答案保存后才完成；此后旧凭据仅用于查询。`run`、`execution` 各命令的字段以 `schema` 为准。