ai_co_discuss 0.2.69 → 0.2.71

package/docs/architecture.md

@@ -256,9 +256,12 @@ running 状态即使只有 pending 事件，也必须先暂停才能重新启动
 - **成员**：`room_members` 以 `id` 为稳定主键，`access` 为 `runner`（接入程序投递）、`manual`（成员自行读写）或 `online`（只读、原文代发），`session_mode` 标记是否借用用户正在使用的会话。房主用控制凭据 `POST members` 运行中加入成员，`POST members/ID {action}` 让成员离开（`away`，作废其进行中执行与未投递请求）、请回（`active`，必须提供不同于原凭证的新凭证，旧凭证副本不再有效）或移除（`remove`，保留历史发言）。同一成员凭证不能复用于其他成员或房主；相同凭证与配置的邀请、请回重试返回已有结果。会话续接由本机接入程序负责，服务端不保存会话绑定；唯一例外是手动成员上报的会话：带凭据的请求可带请求头 `X-Discussion-Session` 与 `X-Discussion-Session-Client`，`message post` 也可在正文带 `session_id` 与 `session_client`（CLI 读取 `CLAUDE_CODE_SESSION_ID` 或 `CODEX_THREAD_ID`，取值 `claude` / `codex`），服务端在 `member_sessions` 保存该手动成员最近上报的会话，成员视图以 `reported_session` 暴露。房主用 `POST members/ID {action:"adopt", adapter:"claude", session_id}`（须与上报一致、仅全自动讨论中在场的手动成员）把成员改为 `runner`、`borrowed` 并清除上报，本机接入程序据此接管。两套后端行为一致。
 - **手动成员注册**：`member_registrations`（`member_id`、`room_id`、`token_hash`、`registered_at`）记录手动成员自己发起的注册，`POST /api/rooms/ID/register` 只接受该成员自己的凭证（房主凭据与他人凭证返回 403），重复调用保留首次时间。记录绑定注册时的凭证哈希：请回换发新凭证后旧记录不再匹配，视图中的 `registered_at` 回到空串，须重新注册。会话 ID 不属于注册内容，仍由 CLI 头部采集进 `member_sessions`；`adopt` 要求已注册。讨论房间的成员视图与自由房间 `free.members` 都带 `registered_at`；新表为独立表，D1 重新应用 schema 即可。
 - **请求**：用户消息按结构化接收者 `to`（成员名）为每位成员生成一条请求；省略且仅有一位在场成员时默认点名该成员，多位成员时交给主持人（`route`），只有在线成员而没有主持人时只作留言，不广播。网页只从正文中代码与引用之外的 `@成员` 生成 `to`，没有 @ 时省略 `to`。请求状态为 `pending`（待投递）→ `delivering`（处理中）→ `completed` / `cancelled` / `failed`。
+- **取消原因**：`request_cancel_reasons`（`request_id`、`reason`）是独立侧表，记录请求被取消的原因（`user_stop`、`member_away`、`member_removed`、`rerouted` 智能调度改派或换主持人、`no_reply` 无需回应、`archived` 房间归档），房间视图的每条请求带 `cancel_reason`；此表加入前已取消的请求没有记录，旧库重复执行 schema 即可。归档自由房间会作废其未完成的执行与排队请求；主持人离开、被移出或被更换时，其尚未开始的 `route` 请求由新主持人重新接收。
 - **执行**：`member_executions` 每位成员最多一个 `dispatched/started`（部分唯一索引），不同成员可并行。接入程序用控制凭据 `GET inbox`、`POST executions {member_id, client_id}`（同一 `client_id` 返回同一执行）把成员的全部待投递请求打包；`POST executions/ID {action}` 支持 `renew`（租约 120 秒，不超过单次执行时限，默认 20 分钟）、`fail`（请求标记失败）和 `release`（仅确认未送达时退回队列）。租约过期的执行在下次读取或领取时标记失败，不自动重发。
 - **主持人与任务链**：用户是需求方，不担任主持人。只要有在场的非在线成员，房间就保持恰好一位主持人：成员变动时，离开或移出的主持人失去角色，由第一位在场的 runner 成员（没有则手动成员）接任；建房和每条房主消息前也做同样的补位，因此旧房间在下一条消息时自动获得主持人。房主用 `POST members/ID {action:"role", role:"host"}` 更换主持人（在线成员不能担任），把现任主持人改为 `member` 会被拒绝。多位成员时未点名的房主消息生成给主持人的 `route` 请求。主持人的回答可带 `to` 点名其他成员（不能点名自己），这些请求组成一个批次（`free_batches`）；批次内全部进入终态后：只有一个请求的批次不再回交（该成员的回答直接面向用户）；多个请求的批次只要有一个完成就给主持人生成一次 `handoff` 请求；全部失败则停下该任务链。每条房主消息开启一条任务链（`chain_id` 为该消息编号），链上 AI 发起的请求（派活与回交）最多 8 次，超出即停下（`free_chains`，原因 `budget` / `all_failed`），房主发新消息开启新链。Worker 用同一批次内的集合 SQL 完成回交，回交请求按（派活消息，主持人）唯一，重复执行不会重复唤醒。
-- **依次点名**：房主消息带 `to` 且 `sequential: true`（网页 `@全体依次` / `@all-seq`）时不立即建全部请求，而是把被点名成员按主持人在前、其余按成员编号排入 `free_queue`，只给第一位建 `ask` 请求（`created_by=user`、`chain_id` 为原消息、不进 `free_batches`）。每次结算批次（回答、失败、打断、离开、租约过期）时，该消息已没有 `pending` / `delivering` 请求就为队首建下一条请求并出队；已不在场的成员直接出队。Python 与 Worker 用相同的集合 SQL 推进；该表只存未轮到的成员，不进备份，删除房间时一并清除（独立表，D1 重新应用 schema 即可）。
+- **发言顺序**：房间视图 `speaking_order`（亦可 `GET speaking-order` 单独读取）在两种模式下给出同一结构：`kind`、`items[{name, state}]`（`done` / `speaking` / `queued` / `idle`，依次为已发言、正在发言、待发言、其余成员）、可调整的 `movable`、房间默认顺序 `default` 与 `revision`。自由协作有未完成的依次点名时 `kind=queue`（`message_id` 为该消息），否则 `kind=default`、全体成员按默认顺序为 `idle`；讨论为 `kind=turns`，由本轮已发言者、当前安排与本轮的排队安排组成；排队按轮切分（专家在正在填充的一轮里第二次出现即开始下一轮），后续轮次以 `later`（每轮一组名字）列出，不在 `movable` 中，调序请求带上它们返回 400。房主用控制凭据 `POST speaking-order {revision, order}` 调整：缺 revision 400，已变化 409，`order` 须恰好包含 `movable`（缺少或多出的名字列在 400 中）。`queue` 删除并按新顺序重插该消息尚未请求的 `free_queue` 行；`turns` 只在本轮排队安排（队列最前面的若干行）的 id 之间整体交换内容（专家、问题、提交编号、创建时间），id 顺序即接力顺序，原计划的提交编号仍对应原内容；`default` 写入 `speaking_orders`（成员编号 JSON 数组，未列出者排在后面，主持人在前、其余按编号）。主持人的 `turn roster` 按此顺序列出专家。
+- **全体点名**：房主消息带 `to`（多于一人）且 `order: "auto"`（网页 `@全体成员` / `@all`）、主持人由本机唤醒（`access=runner`）时，只给主持人建一条 `purpose=group` 请求；主持人不由本机唤醒时按普通点名同时请求。`group` 请求从不投递（预留执行时排除，`inbox` 仍列出），由接入程序用 `POST recommendations/MESSAGE_ID {action:"all"|"sequential"}` 安排：`all` 与未点名消息的全体相同，把它原地改为 `all` 并为其他成员各建一条 `all` 请求；`sequential` 删除这条请求，再把在场成员按房间默认顺序写入 `free_queue`（同下条依次点名）。对 `group` 请求用其他 action 返回 400，已安排过返回 409 或 404（依次安排后已无该请求）。主持人更换、离开或被移除时，尚未安排的 `group` 请求与 `route` 一样交给新主持人。
+- **依次点名**：房主消息带 `to` 且 `sequential: true`（网页手动输入 `@全体依次` / `@all-seq`）时把被点名成员按房间默认顺序写入 `free_queue`，只给第一位建 `ask` 请求（`created_by=user`、`chain_id` 为原消息、不进 `free_batches`）。每次结算批次（回答、失败、打断、离开、租约过期）时，该消息已没有 `pending` / `delivering` 请求就为下一位尚未请求的成员建请求；尚未请求且已不在场的成员被删去。已请求的行保留，供发言顺序显示已发言者。Python 与 Worker 用相同的集合 SQL 推进；`free_queue` 与 `speaking_orders` 不进备份，删除房间时一并清除（独立表，D1 重新应用 schema 即可）。
 - **智能调度推荐**：接入程序用控制凭据 `POST recommendations {message_id, member_id, provider, confidence}` 为一条已交给主持人（`route`）的未点名消息记录推荐对象（在场的非该主持人成员，含手动与在线成员），写入 `member_recommendations`（每条消息一条，重复提交忽略；独立表，D1 重新应用 schema 即可），有效期 60 秒，主持人的请求不受影响。房主用 `POST recommendations/MESSAGE_ID {action:"adopt", mode}` 采纳：`interrupt` 取消主持人这条请求（已投递则作废主持人本次整个执行），`after` 等主持人这条请求进入终态。两种方式都先置为 `waiting`，由 `release`（采纳时与每次 `inbox` 读取时执行）在主持人请求已终态时为推荐成员建一条 `ask` 请求（`created_by=user`、`chain_id` 为原消息），状态改为 `adopted`。过期 5 秒宽限后采纳返回 409，重复采纳返回原结果。同一入口的 `{action:"all"}` / `{action:"none"}` 不经推荐表：全体把主持人尚未开始的 `route` 请求原地改为 `purpose=all`（每条消息每位成员只有一条请求），并为其余在场成员各建一条 `all` 请求（`created_by=user`、`chain_id` 为原消息、不进 `free_batches`，因此没有 `handoff`）；无需回应取消该 `route` 请求；主持人请求已不是 `pending` 时返回 409。主持人本次回答的请求全是 `all` 时，带 `to` 的回答被拒绝（400），避免重复请求其他成员。房间视图 `free.recommendations` 带成员名、状态、方式、置信度与剩余秒数 `expires_in`；备份、导入（仅作历史，不再生效）与删除一并处理。`inbox` 的待投递项带 `purpose` 供接入程序识别。`inbox.members` 只列由本机唤醒的成员；手动与在线成员另列于 `inbox.observers`（含待处理请求，供智能调度识别主持人与推荐对象），接入程序从不向它们投递。
 - **回应建议**：普通成员新发言的结构化 `to` 与正文在场成员 @ 合并保存到 `member_suggestions`（原消息编号、稳定成员编号），排除自己、代码与引用；不会创建请求。消息读取返回 `suggestions`，包含目标在场状态及已转换的请求编号。房主用 `POST suggestions {message_id,member_id}` 转换：同一事务记录用户确认消息，调用现有建请求路径，`message_id` 保留原回答、`chain_id` 使用用户确认消息编号、`created_by=user`。`UNIQUE(message_id,member_id)` 使重复或并发点击只生成一个请求及一条确认，终态不重新派发。权限、在场状态和未存档条件在写入事务内校验；Worker 使用批次断言。升级须应用包含新表的 schema；Python 重启时自动建表，D1 发布前显式执行。已有历史消息不补写建议。
 - **讨论中的直接提问**：讨论房间的用户消息带 `to`（点名成员名列表）时，除保存消息外为每位被点名的在场成员建一条 `ask` 请求（`created_by=user`，不入 `free_batches`，不占安排）；讨论运行中点名主持人不重复建请求。`GET inbox`、`POST executions` 与 `executions/ID` 对讨论房间同样可用，成员以 `execution_id`（接入程序交付）或 `request_ids`（手动 / 代发）提交 `chat` 回答，走自由房间的写入校验。同一成员的 `member_executions` 与 `discussion_events` 互斥（任一方领取时另一方有进行中则返回 409）。房间视图 `asks` 给出最近请求与执行，供消息旁的状态徽标。本机服务以 `DiscussionWithQuestions`（`runner/discussion_service.mjs`）并行运行讨论 runner 与 `FreeRoomRunner`，共用同一成员会话绑定。

package/docs/cli.md

@@ -1,196 +1,197 @@
-# 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` 为准。
+# 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 order ROOM` 读取发言顺序（`items` 的已发言 / 正在发言 / 待发言、可调整的 `movable`、讨论中后续轮次的只读 `later` 与 `revision`），自由协作与讨论通用；讨论中只能调整本轮；房主凭据 `turn reorder ROOM --revision REV --member A --member B …` 按新顺序列出 `movable` 中的全部成员，已发言与正在发言者不动：未带 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` 为准。

package/docs/runner.md

@@ -338,7 +338,8 @@ Codex 要求 CLI 0.163.0 或更新版本，使用 permission profiles 和本地
   - `__all__` 全体：全体成员（含主持人）各自回应一次，彼此不需要配合；
   - `__none__` 无需回应：只是确认、致谢或旁注。
 
-  选中成员且 `confidence ≥ 0.7` 时，用 `POST recommendations` 记录推荐，并随即由接入程序以 `adopt` + `interrupt` 自动采纳：打断主持人，改由该成员回答，自动采纳失败时保留原推荐与 60 秒倒计时，用户仍可手动选“打断主持人”或“主持人答完后再回答”。选中全体或无需回应时阈值为 0.85（`ROUTE_WIDE_CONFIDENCE`，选错分别浪费 N 次执行或让用户的话没人理），由 `POST recommendations/MESSAGE_ID {action:"all"|"none"}` 一步生效：全体把主持人这条请求原地改为 `all`，并为其他在场成员各建一条 `all` 请求（以用户名义，不进派发批次，所以不会唤醒主持人汇总）；无需回应取消主持人这条请求。主持人已开始处理时两者都返回 409，消息仍由主持人处理。每次判断（含交回主持人）都用房主凭据写入 `POST scheduler-decisions`（`kind` 为 `interjection`，`after_message_id` 为该用户消息，`detail` 为题目、选项与各选项概率），在消息下显示为“智能调度：改由 B 回答 / 请全体各自回应 / 无需回应 / 交给主持人 A”及置信度；房主可点 👍 / 👎 评价（`POST scheduler-decisions/ID`，`rating` 为 `good` / `bad` / `null` 撤回）；评为 👎 时可再选填“应该由谁回答”（`should_be`）和不超过 200 字的说明（`note`）。评价存于 `scheduler_feedback`，每条判断产生时的模型、阈值、提示词版本（`ROUTE_PROMPT_VERSION`，改动题目或选项描述时递增）和包版本存于 `scheduler_decision_context`；两者随房间备份导出与导入，用于日后跨版本校准 0.7 阈值。判断失败、超时或置信度不足时不显示推荐，行为与未开启相同。
+  选中成员且 `confidence ≥ 0.7` 时，用 `POST recommendations` 记录推荐，并随即由接入程序以 `adopt` + `interrupt` 自动采纳：打断主持人，改由该成员回答，自动采纳失败时保留原推荐与 60 秒倒计时，用户仍可手动选“打断主持人”或“主持人答完后再回答”。选中全体或无需回应时阈值为 0.85（`ROUTE_WIDE_CONFIDENCE`，选错分别浪费 N 次执行或让用户的话没人理），由 `POST recommendations/MESSAGE_ID {action:"all"|"none"}` 一步生效：全体把主持人这条请求原地改为 `all`，并为其他在场成员各建一条 `all` 请求（以用户名义，不进派发批次，所以不会唤醒主持人汇总）；无需回应取消主持人这条请求。主持人已开始处理时两者都返回 409，消息仍由主持人处理。每次判断（含交回主持人）都用房主凭据写入 `POST scheduler-decisions`（`kind` 为 `interjection`，`after_message_id` 为该用户消息，`detail` 为题目、选项与各选项概率），在消息下显示为“智能调度：改由 B 回答 / 请全体各自回应 / 无需回应 / 交给主持人 A”及置信度；房主可点 👍 / 👎 评价（`POST scheduler-decisions/ID`，`rating` 为 `good` / `bad` / `null` 撤回）；评为 👎 时可再选填“应该由谁回答”（`should_be`）和不超过 200 字的说明（`note`）。评价存于 `scheduler_feedback`，每条判断产生时的模型、阈值、提示词版本（`ROUTE_PROMPT_VERSION`，改动题目或选项描述时递增）和包版本存于 `scheduler_decision_context`；两者随房间备份导出与导入，用于日后跨版本校准 0.7 阈值。每次判断还上传 `input`（发给模型的 `state` 原文与含选项描述的完整题目），存于 `scheduler_decision_inputs`，不进备份、随房间删除。评为 👎 时服务端把该判断连同 `context`、`detail`、`input`、`should_be`、`note` 和房间标题复制为一条 `scheduler_feedback_cases` 快照；改评 👍 或撤回即删除快照，删除房间不影响快照。管理员（本机站点回环访问即是）用 `GET /api/scheduler-feedback?after=DECISION_ID` 按决策编号升序每页读取 50 条（`next_after` 续读），供提示词审查。判断失败、超时或置信度不足时不显示推荐，行为与未开启相同。
+- **@全体成员（同时或依次）**：接入程序每次读取 `inbox` 时处理新的 `group` 请求（不论是否开启智能调度，失败的下次重试）。未开启智能调度时直接 `{action:"all"}`；开启时问一道选择题：`parallel` 同时回答（各自独立回应即可，如打招呼、各自介绍、各说看法）或 `sequential` 依次回答（后发言的需要看到前面的回答，如接龙、轮流补充或反驳、逐个评审、按顺序接力，选项描述带房间发言顺序）；上下文与未点名路由相同。选 `sequential` 且置信度 ≥ 0.7 时 `{action:"sequential"}`，其余（含调用失败）`{action:"all"}`。判断期间标记“分析中”，判断后写入一条决策记录（“请全体同时回答 / 请全体按发言顺序依次回答”），同样可评价。
 - **讨论房间（有把握即执行）**：投递主持事件前先只读判断，置信度 ≥ 0.7 才执行，否则照常唤醒主持人：
   - **插话**：`held_since` 后恰有一条用户留言时判断。仅补充信息且有排队安排 → `turns/continue`；在问某位非主持专家 → 新计划先请该专家回应这条留言（问题引用原文 300 字），原排队安排按原顺序跟在后面（最多 10 项）；改变方向、多条留言或话题修改 → 主持人。仅补充但计划已结束时，按下一条处理。
   - **轮次衔接**：仅 `named_followup` 为 false、无排队、上一轮已完成时判断。继续 → 先请模型选出的专家（不是上一轮最后发言者），其余按房间专家顺序，统一使用 `peer_round_question`；第 1 轮后自动把阶段从 `initial` 改为 `discussing`。可收束、跑偏、重复或卡住 → 主持人。