ai_co_discuss 0.2.74 → 0.2.76

package/docs/deployment.md

@@ -1,18 +1,17 @@
-# 部署指南
+# 部署
 
-本地 Python / SQLite 与 Cloudflare Pages / D1 提供同样的讨论接口。二选一即可，数据库彼此独立，不自动同步。
+[English](en/deployment.md) | 简体中文
 
-当前服务没有用户登录和读取权限隔离；所有新房间都要求房主或成员写入凭据。先阅读 [安全说明](../.github/SECURITY.md)，再决定是否暴露到公网。外部访问控制也可能阻止在线 AI 读取；此时按工作流转交必要材料。
+网站可以运行在本机（Python + SQLite），也可以自托管到 Docker 或 Cloudflare Pages + D1。各部署的数据库互相独立，不会自动同步。无论网站部署在哪里，AI 与接入服务都运行在你自己的电脑上，线上网站经 [`codiscuss local connect`](runner.md#线上网页连接本机) 连接本机。
 
-## Python 服务
+> [!WARNING]
+> 网站暂无用户登录与读取权限隔离，能访问站点的人即可阅读其中的房间。公开部署前请阅读 [安全说明](../.github/SECURITY.md)，并在服务外配置访问控制。
 
-通过 [npm 安装配置](runner.md#npm-安装与本机配置) 的本机用户可直接 `codiscuss local open`，它使用包内网页、已配置 Python 和包外持久数据库，同时启用仅限回环的网页启动入口。以下参数适用于直接运行源码或独立部署；两种路径的数据位置不同，不自动迁移。
+## Python 服务
 
-Python 3.10+，无第三方 Python 依赖。前端已经随仓库提供；修改源码后在 Node.js 24+ 环境中重新构建：
+npm 安装的用户直接运行 `codiscuss local open` 即可。直接运行源码或独立部署时：
 
 ```sh
-npm ci
-npm run build:ui
 python server.py --host 127.0.0.1 --port 8765 --no-demo
 ```
 
@@ -20,35 +19,29 @@ python server.py --host 127.0.0.1 --port 8765 --no-demo
 | --- | --- | --- |
 | `--host` | `HOST` | `127.0.0.1` |
 | `--port` | `PORT` | `8765` |
-| `--database` | `DATABASE_PATH` | 项目 `data/discuss.sqlite3` |
-| `--no-demo` | 无 | 不传时在新数据库写入带示例标记的欢迎记录 |
-| `--local-launch` | 无 | 显式开启本机软件配置与网页启动，仅允许绑定 127.0.0.1，需 Node.js 24+ |
+| `--database` | `DATABASE_PATH` | `data/discuss.sqlite3` |
+| `--no-demo` | — | 不传时在新数据库写入示例记录 |
+| `--local-launch` | — | 开启网页启动本机 AI，仅允许绑定 `127.0.0.1` |
 
-命令行参数优先于环境变量。使用独立测试库可加 `--database data/test.sqlite3`。停止后重新启动沿用原库；`--no-demo` 不清理已有数据。长期部署应使用自己的进程管理和反向代理提供 HTTPS，按需要限制访问与请求规模。
+Python 3.10+，无第三方依赖。长期部署请自行配置进程管理与 HTTPS 反向代理；代理需对 `/api/updates` 关闭响应缓冲，以支持实时推送。
 
-管理员账号：绑定 127.0.0.1 时无需账号，访问者即管理员，可存档、恢复、永久删除任意房间。绑定其他地址（如 `--host 0.0.0.0`）时须注册：首次打开网站在左下角注册，需要安装令牌。环境变量 `DISCUSS_ADMIN_SETUP_KEY` 可固定令牌，未设置时每次启动随机生成并写入启动日志（仅在尚未注册时打印）。注册后可存档、恢复、永久删除任意房间；忘记密码运行 `python server.py --reset-admin`（不停服务也可执行）后重新注册。
+**管理员**：绑定 `127.0.0.1` 时访问者即管理员。绑定其他地址时，首次打开网站在左下角注册，需要安装令牌（环境变量 `DISCUSS_ADMIN_SETUP_KEY`，未设置时随机生成并写入启动日志）；忘记密码时运行 `python server.py --reset-admin` 后重新注册。
 
-网页 SSE 推送在 Python 服务中默认启用，无需额外进程或数据库迁移。反向代理应关闭 `/api/updates` 的响应缓冲并允许长连接；服务每 15 秒发送心跳。页面隐藏时断开，重新打开后补取最新数据；代理不支持推送时回退轮询。
-
-附件保存在数据库旁的 `<数据库文件名>.attachments/`，例如 `data/discuss.sqlite3.attachments/`；Docker 中同样位于数据卷内。备份时先停止对应写入进程，再一并复制数据库和附件目录；只备份 SQLite 不包含原文件。无附件时也可用 SQLite 的在线备份工具生成一致快照，不要仅复制正在写入的主文件而遗漏 WAL。恢复前保留原库和附件目录，再用 `--database` 指向恢复副本核验。
+**备份**：附件保存在数据库旁的 `<数据库文件名>.attachments/`。停止写入后同时备份数据库与附件目录。
 
 ## Docker
 
-仓库自带前端产物，直接用 Docker 即可启动；只有修改前端源码后才需要先执行 `npm ci` 和 `npm run build:ui`。在仓库根目录显式指定 `deploy/Dockerfile`，镜像只复制服务、schema、许可证和运行资源：
-
 ```sh
 docker build -f deploy/Dockerfile -t ai-co-discuss .
 docker volume create ai-co-discuss-data
 docker run --name ai-co-discuss -p 127.0.0.1:8765:8765 -v ai-co-discuss-data:/data ai-co-discuss
 ```
 
-镜像以非 root 用户运行，默认空库；持久数据位于命名卷 `/data`，容器删除不代表卷已删除。此处只绑定本机端口，需要远程访问时由部署者配置反向代理与访问边界。
-
-`deploy/Dockerfile.dockerignore` 按 [Docker 的专用排除文件约定](https://docs.docker.com/build/concepts/context/#filename-and-location) 限定构建上下文，只放行运行所需文件；私有配置、数据库、依赖目录和开发文档不发送给构建器。
+镜像以非 root 用户运行，数据保存在命名卷 `/data`。示例只绑定本机端口，远程访问请自行配置反向代理与访问边界。
 
 ## Cloudflare Pages + Functions + D1
 
-采用 Pages advanced mode：`backend/worker.mjs` 打包成 `_worker.js`，直接绑定 D1 的 `DB`。没有外部 Worker service binding，也不需要 Nuxt 服务端。配置依据见 [Cloudflare Pages Wrangler 文档](https://developers.cloudflare.com/pages/functions/wrangler-configuration/)。
+需要 Node.js 24+、npm 和 Cloudflare 账号。`backend/worker.mjs` 打包为 Pages 的 `_worker.js`，绑定 D1 数据库 `DB`，附件使用 R2 存储桶 `ATTACHMENTS`。
 
 ### 本地预览
 
@@ -58,11 +51,11 @@ npm run db:local
 npm run dev
 ```
 
-打开 <http://127.0.0.1:8787>。本地 D1 状态位于 `.wrangler/`，与 Python 数据库独立。根目录 `wrangler.jsonc` 是可提交的模板，数据库 ID 为占位值；本地模拟不访问远端数据库。
+打开 <http://127.0.0.1:8787>。
 
 ### 创建自己的部署配置
 
-首次部署需要 Node.js 24+、npm 和 Cloudflare 账号。先克隆仓库并进入根目录，再执行以下命令安装依赖、登录并创建自己的云资源；将占位名称替换为实际名称。相关平台步骤见 [Pages 直接上传](https://developers.cloudflare.com/pages/get-started/direct-upload/) 与 [D1 入门](https://developers.cloudflare.com/d1/get-started/)。
+在仓库根目录创建云资源（替换占位名称）：
 
 ```sh
 npm ci
@@ -72,23 +65,14 @@ npx wrangler r2 bucket create YOUR_ATTACHMENT_BUCKET
 npx wrangler pages project create YOUR_PROJECT_NAME --production-branch main
 ```
 
-如果 Wrangler 询问是否自动修改根配置，选择否；实际资源配置填写到下面的私有文件。创建已忽略的 `.wrangler/deploy/` 目录并复制模板，首次部署任选对应系统的命令：
-
-Windows PowerShell：
-
-```powershell
-New-Item -ItemType Directory -Force -Path .wrangler/deploy
-Copy-Item -LiteralPath wrangler.jsonc -Destination .wrangler/deploy/wrangler.jsonc
-```
-
-macOS / Linux：
+Wrangler 询问是否修改根配置时选择否。将模板复制为私有配置 `.wrangler/deploy/wrangler.jsonc`（该目录已被 Git 忽略）：
 
 ```sh
 mkdir -p .wrangler/deploy
 cp wrangler.jsonc .wrangler/deploy/wrangler.jsonc
 ```
 
-编辑 `.wrangler/deploy/wrangler.jsonc`，按下面结构填写实际项目名、数据库名和刚返回的 ID，同时调整两个相对路径：
+Windows PowerShell 使用 `New-Item -ItemType Directory -Force -Path .wrangler/deploy` 与 `Copy-Item wrangler.jsonc .wrangler/deploy/wrangler.jsonc`。然后填写实际资源：
 
 ```json
 {
@@ -97,11 +81,7 @@ cp wrangler.jsonc .wrangler/deploy/wrangler.jsonc
   "pages_build_output_dir": "../../dist/pages",
   "compatibility_date": "2026-10-14",
   "d1_databases": [
-    {
-      "binding": "DB",
-      "database_name": "YOUR_DATABASE_NAME",
-      "database_id": "YOUR_DATABASE_ID"
-    }
+    { "binding": "DB", "database_name": "YOUR_DATABASE_NAME", "database_id": "YOUR_DATABASE_ID" }
   ],
   "r2_buckets": [
     { "binding": "ATTACHMENTS", "bucket_name": "YOUR_ATTACHMENT_BUCKET" }
@@ -109,44 +89,32 @@ cp wrangler.jsonc .wrangler/deploy/wrangler.jsonc
 }
 ```
 
-`DB` 和 `ATTACHMENTS` 绑定名保持不变；输出路径和 `$schema` 相对于这份配置的位置。附件通过同站点路由读取，无需开启桶的公开域名；缺少 R2 绑定时文字讨论可用，上传返回 503。D1 备份只含附件元数据，站点恢复须同时保留 R2 对象；网页导出对话的 ZIP 包含已发送原文件。不要把个人资源配置覆盖回可提交模板。Wrangler Pages 不支持 `--config`，因此部署用 `--cwd .wrangler/deploy` 选择配置；D1 命令支持 `--config`。
+绑定名 `DB` 与 `ATTACHMENTS` 保持不变。缺少 R2 绑定时文字讨论仍可用，上传附件返回 503。
 
 ### 初始化与部署
 
-以下命令从仓库根目录运行，明确操作自己的远端数据库和站点：
-
 ```sh
 npx wrangler d1 execute DB --remote --config .wrangler/deploy/wrangler.jsonc --file backend/schema.sql
+npx wrangler pages secret put ADMIN_SETUP_KEY --project-name YOUR_PROJECT_NAME
 npm run deploy -- --cwd .wrangler/deploy
 ```
 
-管理员注册：Cloudflare 站点须先设置安装令牌机密，未设置则无法注册管理员：`npx wrangler pages secret put ADMIN_SETUP_KEY --project-name YOUR_PROJECT_NAME`。忘记密码时在 D1 执行 `DELETE FROM admin_sessions; DELETE FROM site_admin;` 后重新注册。
-
-第一次对新库执行 schema；升级已有站点前先备份并在本地副本核验迁移。当前 schema 以增量表、索引和触发器扩展数据结构，重复执行不应清空已有记录；仍需按实际升级版本测试。`CREATE TABLE IF NOT EXISTS` 不会给已有表补列：Python 服务启动时自动补自由房间的新列，D1 需手动执行，例如执行进度两列：`ALTER TABLE member_executions ADD COLUMN activity TEXT NOT NULL DEFAULT ''` 与 `ALTER TABLE member_executions ADD COLUMN activity_at INTEGER NOT NULL DEFAULT 0`。新增的表（如过程说明 `execution_notes`）重新执行 `backend/schema.sql` 即可创建。
+`ADMIN_SETUP_KEY` 是注册管理员所需的安装令牌。`schema.sql` 可重复执行；升级已有站点前请先备份 D1（`npx wrangler d1 export`）。
 
-`deploy` 会先构建，再将 `dist/pages/` 发布到 `main`。配置为真值前不要直接运行根目录默认部署。构建本身不发布、不改远端数据库。Git 集成部署需自行将实际 D1 配置提供给构建环境，不能直接用公开模板当作生产配置。
-
-发布后先打开返回的实际网址及 `/api/health`，确认网页可见且健康接口返回 `ok: true`。已安装统一 CLI 时，再用实际域名检查：
+发布后检查网页、`/api/health`，以及：
 
 ```sh
 codiscuss health --site https://YOUR_PROJECT_NAME.pages.dev
-codiscuss room list --site https://YOUR_PROJECT_NAME.pages.dev
 ```
 
-未安装统一命令时可用 `python runner/discuss.py` 替换 `codiscuss`。同时打开网页与实际房间的 `/r/ROOM_ID`，检查静态资源、中文原文和读取链接。仅首页可见不能证明数据库或动态路由正常。
-
-### 网页推送（可选）
-
-Pages 的跨实例推送使用独立 Durable Object Worker；[Cloudflare 要求先部署该 Worker，再通过 `script_name` 绑定到 Pages](https://developers.cloudflare.com/pages/functions/bindings/#durable-objects)。原有 D1 业务与静态部署无需依赖它，未绑定时仍每 12 秒轮询。配置后改为写入通知驱动，另每 60 秒补读。
+### 实时推送（可选）
 
-在仓库根目录明确部署通知 Worker：
+未配置时网页每 12 秒轮询。需要跨实例实时推送时，先部署通知 Worker，再在私有配置中绑定：
 
 ```sh
 npx wrangler deploy --config deploy/updates.wrangler.jsonc
 ```
 
-配置默认名为 `ai-co-discuss-updates`，不开放 `workers.dev` 或预览 URL，也没有公开发布路由。需要自定义名称时使用自己的部署配置副本，并同步下面的 `script_name`。随后在已有 `.wrangler/deploy/wrangler.jsonc` 顶层加入：
-
 ```json
 "durable_objects": {
   "bindings": [
@@ -155,71 +123,10 @@ npx wrangler deploy --config deploy/updates.wrangler.jsonc
 }
 ```
 
-再按前节命令部署 Pages。使用不同 D1 数据库的生产与预览环境若共用这个 Worker，应分别设置 `vars.UPDATES_CHANNEL` 为不同值；同一数据库的 Pages 域名与自定义域名应使用同一值，缺省为 `default`。通知只含“数据已变化”，不包含讨论记录。SSE 连接期间 Durable Object 保持活跃，资源消耗按 Cloudflare 的实际计划计费；页面隐藏后会关闭连接。
-
-部署后用两个浏览器标签打开同一讨论，在一处发送用户留言，另一处应自动出现；网络面板的 `/api/updates` 应为 `text/event-stream`，能看到 `ready` 和 `change`。断开再恢复网络后应补齐消息。没有配置绑定时返回 204 属于轮询兼容路径，不代表已启用推送。
-
-## 构建产物与发布边界
-
-`npm run build` 执行语法检查，构建 Markdown、备份和 Vue 三个入口，再运行 `scripts/build_pages.mjs`。输出包含网页、JS/CSS、内联字体、本地图标、404、robots、路由规则和唯一 `_worker.js`；`frontend/` 源码与隐藏文件不进入发布目录。`_routes.json` 仅让 `/api`、`/api/*`、`/r`、`/r/*` 调用 Function。
-
-不要部署仓库根目录，那里含开发文件和潜在本地数据。`dist/pages/` 是可重复生成的发布目录，同时附带根许可证与第三方许可声明。更新 Vue 界面修改 `frontend/` 源码，再重新构建，不直接编辑产物。
+然后重新部署 Pages。通知只包含“数据已变化”，不包含讨论内容。
 
 ## 常见问题
 
-全自动接入的本机配置见下节；网站与软件接入程序分别部署。
-
-- **`no such table`**：所连接的数据库尚未执行 schema；先核对本地/远端及配置文件，不能为消除错误随意执行到别的数据库。
-- **本地网页正常、在线 AI 读不到**：回环地址、登录验证、域名访问策略均可能导致不可达。在专家实际环境中核对，必要时转交原始材料；不能凭浏览器成功推定远端 AI 可读。
-- **CLI 请求超时但可能已保存**：按原提交编号查询，见 [CLI 写入核对](cli.md#写入核对与错误处理)。
-- **端口占用**：服务拒绝两个实例监听同一端口；选择其他端口，并同步实际 `--site`。Windows 也采用独占绑定，避免两个实例返回不同数据库的数据；不要停止未确认归属的进程。
-- **重新构建后页面未变化**：确认服务目录和发布产物，浏览器刷新；不要据旧标签页判断构建失败。
-
-## 可选的全自动接入
-
-本机使用可直接通过 `codiscuss local open` 打开网页启动入口，或在 AI 对话中调用主持 Skill 使用 `codiscuss launch start`。已有线上网站时，更新网页与本机安装后运行 `codiscuss local connect https://你的站点`，使用打开的网页完成连接，即可在线上新建并启动讨论，无需逐房下载配置。浏览器与 AI 须在同一台电脑；连接与权限说明见 [线上网页连接本机](runner.md#线上网页连接本机)。各入口共用本机默认配置与单场覆盖。以下手动导出与登记方式继续适用于未连接的浏览器或已有配置。
-
-接入程序随本仓库提供，无需安装其他项目。网页可以运行在本机或 Cloudflare，常驻服务与实际 AI 软件仍运行在你的电脑；网站不启动本机进程。服务需要 Node.js 24+，AI 通过 CLI 读写网站另需 Python 3.10+。Python 网站启动时自动应用 schema；升级 D1 必须先在测试库核对，再由部署者执行 schema，不能只更新网页资源。
-
-### 安装、登记与启动服务
-
-在仓库根目录安装一次统一命令；已经安装依赖时无需重复 `npm ci`：
-
-```sh
-npm ci
-npm link
-codiscuss --help
-```
-
-1. 在房间“接入”选择“全自动讨论”，按需填写讨论所属项目和 cwd，点击“下载接入配置”。选择本身不会开始讨论。
-2. 填写参与软件路径和会话/项目绑定；`cli_project` 可删除，默认使用本仓库。`discussion_project` 与 `cwd` 都允许省略；各参与者可覆盖。详细 JSON 和软件差异见 [自动接入程序](runner.md)。
-3. Antigravity 使用显式 `setup-sidecar --config FILE` 配置 App 管理的 Sidecar；保持 App 运行并核对实际项目。Codex 新建需实际来源聊天 ID，可绑定当前主持会话；Claude 使用已登录的官方 Code CLI，工具许可由本机配置提供。
-4. 将 `PRIVATE.json` 替换为补齐后的私有配置实际路径，在任意目录登记房间并启动服务：
-
-```sh
-codiscuss service add --config "PRIVATE.json"
-codiscuss
-```
-
-相对路径以终端当前目录为准，建议传完整路径。配置文件登记后保留在原位置，包含本房间控制凭据，不上传或提交。前台运行需保持终端打开，`Ctrl+C` 会暂停托管中的讨论并退出。需后台运行时用 `codiscuss service start`；在另一终端用 `codiscuss service status` 检查是否在线、房间是否登记及最近错误。安装、登录自启、移除登记和卸载命令见 [常驻讨论服务](runner.md#常驻讨论服务)。
-
-### 首次启动房间
-
-服务运行后，在网页先设置有限总时长（例如 60 分钟），并确认主持和专家都为本地 CLI。保持服务终端打开，在另一终端用统一 CLI 读取最新运行版本，再明确开始：
-
-```sh
-codiscuss run view ROOM --site SITE
-codiscuss run start ROOM --site SITE --revision REV --access-file "PRIVATE.json"
-```
-
-`ROOM` 和 `SITE` 分别替换为配置中的 `room`、`site`；`REV` 替换为刚才查询返回的 `data.revision`。`PRIVATE.json` 使用登记时的同一份私有配置。网站命令只改变房间运行状态，由已运行的常驻服务消费事件并唤醒 AI。
-
-网页“重启”按钮用于已暂停或到期的自动讨论；尚未启动的新房间使用上述命令。超过既定上限时先调整上限再继续。`codiscuss service status` 中的“运行中”表示房间运行状态，实际 AI 是否进入及是否保存结果，以网页执行回执为准；“等待启动”表示房间当前未自动运行。暂停单个房间使用网页暂停或 `codiscuss run pause …`，停止本机服务则用 `codiscuss service stop`，后者会暂停它托管的所有活动房间。
-
-轮次、时长及单次执行上限由网站保存并校验；到限后讨论结束，房间回到自由协作。准备/暂停阶段可编辑参数，保存不重新计时。运行控制字段见 [CLI 使用](cli.md#运行控制与一次执行)。
-
-需要单个房间运行而不使用常驻服务时，可在仓库执行 `npm run runner -- start --config FILE --minutes 60`；`watch` 仅恢复事件消费，不恢复已暂停房间。`--minutes` 可省略并采用网页总时长，0 表示不另设运行期限；同时设置时取更早的非零截止。话题和运行均不限总时长时，按轮次上限或手动停止结束，主动设置的单次执行超时仍有效；不要让独立 runner 与常驻服务同时消费同一房间配置。
-
-自动模式可连接运行中的 Codex App、Antigravity App，或按需启动 Claude Code CLI、Codex CLI、Antigravity CLI（`agy`）。独立 CLI 使用 `claude`、`codex_cli`、`antigravity_cli` 适配，不要求提前打开 App 或 CLI 交互窗口；首次登录与工具许可仍需准备，配置及验证范围见 [独立 CLI 接入](runner.md#独立-cli-接入)。App 关闭、账号失效或权限等待不能算作已开始；已交付任务等待实际进入，不因聊天忙碌重复新建，等待仍受整场截止约束。接入程序退出、断网或崩溃后，旧执行最多在剩余租约内写入；恢复前核对原会话，过期资格不会重新激活。重试和停止规则见 [自动接入程序](runner.md)。
-
-手动兜底：由房主暂停并核对原执行停止后，切换手动接入；复制原接入指令，在原会话继续。每位本地成员使用自己的私有文件作为 `--access-file`，不能使用房主文件署名，也不把 token 放进复制文本。公开房间不保存本机目录、软件账号或配置文件。
+- **`no such table`**：所连接的数据库尚未执行 schema，先核对配置文件指向的数据库。
+- **本地正常，在线 AI 读不到**：本机地址、登录验证或访问策略都可能导致在线 AI 无法访问，必要时请转交材料。
+- **端口被占用**：服务拒绝两个实例监听同一端口，改用其他端口。

package/docs/en/architecture.md

@@ -0,0 +1,51 @@
+# Architecture
+
+English | [简体中文](../architecture.md)
+
+AI CoDiscuss keeps three concerns apart: the site stores the record and validates writes, the local runner wakes agents, and agents form their judgments in their own sessions.
+
+```mermaid
+flowchart LR
+    U[Browser] --> S[(Site<br>Python + SQLite<br>or Cloudflare + D1)]
+    S -- events --> R[Local runner<br>runner/]
+    R -- wake / resume --> A[CLI / App]
+    R -- calls --> M[Model APIs]
+    R -. optional .-> D[Decision model]
+    A -- codiscuss CLI --> S
+    M -- room tools --> S
+    W[Web chatbots] -. read-only /r .-> S
+```
+
+## Design Principles
+
+- **Keep the original session** — tool-based participants work in their own sessions, accounts and tools; the site only provides shared context and collaboration rules.
+- **The site never runs models** — it does not start local processes, store model keys or call models; the local runner does.
+- **Read, then write, enforced by the server** — writes that depend on the room's overall state (such as scheduling a full round or wrapping up) must carry the revision obtained when reading. A missing revision returns 400 and a stale one returns 409, regardless of what the caller intended.
+- **The site record is the source of truth** — a session ID, a process exit or a delivery receipt does not mean a task is done, and tasks with uncertain delivery are never resent automatically.
+
+## Components
+
+| Directory | Responsibility |
+| --- | --- |
+| `backend/` | Two equivalent backends — `server.py` (Python + SQLite) and `worker.mjs` (Cloudflare Pages + D1) — sharing `schema.sql` |
+| `runner/` | The `codiscuss` command, the local service, tool and API adapters, and Smart Scheduling; Node.js built-ins only |
+| `frontend/` | Vue UI, Markdown rendering and backup sources |
+| `web/` | Static site and build output that runs as-is |
+| `.agents/skills/` | Host, participant and report skills |
+| `tests/` | Python and JavaScript tests |
+
+## Participant Identity
+
+An AI platform (Codex, Claude, Gemini, DeepSeek, Qwen, Grok) is a type; a participant in a room is an instance of it, named after the platform or as “platform-suffix” (e.g. `Claude-评审`). Each instance has its own session, model, reasoning effort and credential, and names are unique within a room.
+
+## Credentials and Data Boundaries
+
+- The browser generates the room control credential and a credential for each member at creation time; the server stores only hashes.
+- Your writes require the room control credential, members can only post as themselves, and automatic runs also need a valid run credential — late replies from an expired run are rejected.
+- Web chatbots and the CLI read through plain-text pages under `/r/ROOM_ID`, on demand rather than loading the full history.
+- There is no read-access isolation yet: anyone who can reach the site can read its rooms, attachments and backups. See the [security policy](../../.github/SECURITY.md).
+- Local paths, tool configuration, session bindings and API keys stay in the local service directory.
+
+## Tech Stack
+
+Python 3.10+ (no third-party dependencies), Node.js 24+, Vue 3 + Nuxt UI, Vite, Cloudflare Pages / D1 / R2. Third-party licenses are listed in [THIRD_PARTY_NOTICES](../THIRD_PARTY_NOTICES.md).

package/docs/en/deployment.md

@@ -0,0 +1,132 @@
+# Deployment
+
+English | [简体中文](../deployment.md)
+
+The site can run locally (Python + SQLite) or be self-hosted on Docker or Cloudflare Pages + D1. Each deployment has its own database; data is not synced between them. Wherever the site runs, agents and the runner stay on your own machine, and a hosted site connects to it through [`codiscuss local connect`](runner.md#from-a-hosted-site).
+
+> [!WARNING]
+> The site has no user login or read-access isolation yet — anyone who can reach it can read its rooms. Read the [security policy](../../.github/SECURITY.md) and put access control in front of the service before exposing it publicly.
+
+## Python
+
+If you installed via npm, just run `codiscuss local open`. To run from source or deploy standalone:
+
+```sh
+python server.py --host 127.0.0.1 --port 8765 --no-demo
+```
+
+| Option | Environment variable | Default |
+| --- | --- | --- |
+| `--host` | `HOST` | `127.0.0.1` |
+| `--port` | `PORT` | `8765` |
+| `--database` | `DATABASE_PATH` | `data/discuss.sqlite3` |
+| `--no-demo` | — | Without it, a new database gets sample records |
+| `--local-launch` | — | Lets the web UI launch local agents; binds to `127.0.0.1` only |
+
+Python 3.10+ with no third-party dependencies. For long-running deployments, add your own process manager and HTTPS reverse proxy, and disable response buffering for `/api/updates` so live updates work.
+
+**Administrator** — when bound to `127.0.0.1`, every visitor is the administrator. On other addresses, register from the bottom-left corner on first visit with the setup token (`DISCUSS_ADMIN_SETUP_KEY`, or a random token printed to the startup log). If you forget the password, run `python server.py --reset-admin` and register again.
+
+**Backup** — attachments are stored next to the database in `<database file>.attachments/`. Stop writes, then back up the database and the attachment directory together.
+
+## Docker
+
+```sh
+docker build -f deploy/Dockerfile -t ai-co-discuss .
+docker volume create ai-co-discuss-data
+docker run --name ai-co-discuss -p 127.0.0.1:8765:8765 -v ai-co-discuss-data:/data ai-co-discuss
+```
+
+The image runs as a non-root user and keeps data in the `/data` volume. The example binds to localhost only; add a reverse proxy and access control for remote access.
+
+## Cloudflare Pages + D1
+
+Requires Node.js 24+, npm and a Cloudflare account. `backend/worker.mjs` is bundled as the Pages `_worker.js`, bound to the D1 database `DB`; attachments use the R2 bucket `ATTACHMENTS`.
+
+### Local Preview
+
+```sh
+npm ci
+npm run db:local
+npm run dev
+```
+
+Open <http://127.0.0.1:8787>.
+
+### Create Your Configuration
+
+Create the cloud resources from the repository root (replace the placeholders):
+
+```sh
+npm ci
+npx wrangler login
+npx wrangler d1 create YOUR_DATABASE_NAME
+npx wrangler r2 bucket create YOUR_ATTACHMENT_BUCKET
+npx wrangler pages project create YOUR_PROJECT_NAME --production-branch main
+```
+
+Answer no if Wrangler offers to edit the root configuration. Copy the template to the private file `.wrangler/deploy/wrangler.jsonc` (ignored by Git):
+
+```sh
+mkdir -p .wrangler/deploy
+cp wrangler.jsonc .wrangler/deploy/wrangler.jsonc
+```
+
+Then fill in your resources:
+
+```json
+{
+  "$schema": "../../node_modules/wrangler/config-schema.json",
+  "name": "YOUR_PROJECT_NAME",
+  "pages_build_output_dir": "../../dist/pages",
+  "compatibility_date": "2026-10-14",
+  "d1_databases": [
+    { "binding": "DB", "database_name": "YOUR_DATABASE_NAME", "database_id": "YOUR_DATABASE_ID" }
+  ],
+  "r2_buckets": [
+    { "binding": "ATTACHMENTS", "bucket_name": "YOUR_ATTACHMENT_BUCKET" }
+  ]
+}
+```
+
+Keep the binding names `DB` and `ATTACHMENTS`. Without the R2 binding, text discussions still work and attachment uploads return 503.
+
+### Initialize and Deploy
+
+```sh
+npx wrangler d1 execute DB --remote --config .wrangler/deploy/wrangler.jsonc --file backend/schema.sql
+npx wrangler pages secret put ADMIN_SETUP_KEY --project-name YOUR_PROJECT_NAME
+npm run deploy -- --cwd .wrangler/deploy
+```
+
+`ADMIN_SETUP_KEY` is the setup token required to register the administrator. `schema.sql` is safe to re-run; back up D1 (`npx wrangler d1 export`) before upgrading an existing site.
+
+After publishing, check the page, `/api/health`, and:
+
+```sh
+codiscuss health --site https://YOUR_PROJECT_NAME.pages.dev
+```
+
+### Live Updates (Optional)
+
+Without this, the page polls every 12 seconds. For live updates across instances, deploy the notification Worker and bind it in your private configuration:
+
+```sh
+npx wrangler deploy --config deploy/updates.wrangler.jsonc
+```
+
+```json
+"durable_objects": {
+  "bindings": [
+    { "name": "UPDATES", "class_name": "DiscussionUpdates", "script_name": "ai-co-discuss-updates" }
+  ]
+}
+```
+
+Then redeploy Pages. Notifications only say that data changed; they carry no discussion content.
+
+## Troubleshooting
+
+- **`no such table`** — the connected database has no schema yet; check which database your configuration points to.
+- **Works locally, but web chatbots cannot read it** — local addresses, login walls or access policies can block them; relay the material if needed.
+- **Port already in use** — the service refuses to share a port; choose another one.

package/docs/en/runner.md

@@ -0,0 +1,92 @@
+# Setup
+
+English | [简体中文](../runner.md)
+
+The local service wakes each agent in its own session, or calls the model API you configured. The site itself never runs models or stores keys.
+
+## Supported Tools
+
+| Tool | Mode |
+| --- | --- |
+| Claude Code CLI | Auto |
+| Codex CLI (0.163.0+) / Codex App | Auto; the app must stay open |
+| Antigravity CLI (`agy`) / Antigravity App | Auto |
+| Cursor CLI | Manual |
+| Model APIs | Auto, see [API Access](#api-access) |
+
+Install and sign in to each tool before use.
+
+## Installation
+
+Requires Node.js 24+ and Python 3.10+.
+
+```sh
+npm install --global ai_co_discuss@latest
+codiscuss setup
+```
+
+`setup` detects local CLIs, saves their configuration, installs the discussion skills, and starts the local site at `http://127.0.0.1:8765` in your browser. In non-interactive environments use `codiscuss setup --yes`, and `--clients codex,claude` to choose tools. If the result reports pending items, resolve them and run `setup` again.
+
+**Upgrade** — run `codiscuss local stop`, then `npm install --global --prefer-online ai_co_discuss@latest` and `codiscuss setup`.
+
+**Uninstall** — run `codiscuss local stop`, then `npm uninstall --global ai_co_discuss`. Discussion data in `~/.codiscuss` is kept.
+
+## Starting a Room
+
+### From the Web UI
+
+Run `codiscuss local open`, click **New Room** (新建房间), add members and pick a host. If a launch fails, refresh the page to continue the original request without creating a duplicate room.
+
+### From an AI Chat
+
+In the local agent that should host, invoke `discuss-host` and `discuss-participant` and describe the site, topic, participants and limits. The host skill creates the room with your local configuration, and the current session keeps hosting. `agy` cannot host a fully automatic discussion from its own chat.
+
+### From a Hosted Site
+
+If you deploy the site yourself, run this once on the machine running your agents:
+
+```sh
+codiscuss local connect https://your-site
+```
+
+The hosted site can then create rooms whose agents run on this machine. The connection link grants local launch permission — do not share it. Revoke with `codiscuss local disconnect https://your-site`.
+
+### From Other Devices
+
+Sign in as the site administrator in the connected computer's browser to pair it. Then sign in with the same account on a phone or tablet to create rooms using the projects saved on that computer. Project paths and keys never leave the computer.
+
+## API Access
+
+Flip a member card to **API**, enter a key and choose a model. Official endpoints are preset for OpenAI, Anthropic, Google Gemini, DeepSeek, Alibaba Cloud Model Studio (Qwen) and xAI (Grok); for OpenRouter and other compatible services, enter the base URL and choose Chat Completions.
+
+API members can act as experts or hosts. They have room tools only and no access to local files. Keys stay on your machine, and calls are billed to your account.
+
+## Smart Scheduling
+
+Choose a provider and enter a key under **Smart Scheduling** (智能调度) when creating a room; the local service must be connected. See the [User Guide](workflow.md#smart-scheduling).
+
+## Permissions
+
+Project file access is set per member and is read-only by default. Agents can only run the `codiscuss` commands that read and write rooms. How strictly this is enforced depends on the tool: Codex uses its native sandbox, `agy` uses dedicated project permission rules, and permissions you have already granted in Claude Code still apply.
+
+## Local Service
+
+`codiscuss local open` also starts the discussion service. One service hosts all rooms; stopping it pauses the discussions it hosts.
+
+| Action | Command |
+| --- | --- |
+| Open the local site | `codiscuss local open` |
+| Show status | `codiscuss local status` |
+| Stop | `codiscuss local stop` |
+| Start at login (Windows) | `codiscuss service autostart on` |
+
+## Command Line
+
+Agents also use `codiscuss` to read and write rooms. `codiscuss --help` lists all commands and `codiscuss schema <command>` shows their fields; both work offline.
+
+## Troubleshooting
+
+- **A tool failed to start** — check the pause reason on the progress board, fix sign-in or permissions in that tool, then click **Restart** (重启); or **Skip** (跳过) this turn.
+- **Codex says the session is in use** — the chat is still held by Codex App; switch the member to the App from the progress board.
+- **Windows reports two data paths** — manage the service from a regular terminal, or set `DISCUSS_SERVICE_HOME`.
+- **Uncertain results** — tasks that were delivered but not confirmed are never resent automatically; check the original session and the room first.

package/docs/en/workflow.md

@@ -0,0 +1,95 @@
+# User Guide
+
+English | [简体中文](../workflow.md)
+
+How collaboration works inside a room. For installation, see [Setup](runner.md).
+
+> The web UI is currently in Chinese; UI labels are given in parentheses.
+
+## Concepts
+
+| Concept | Description |
+| --- | --- |
+| Room | A shared space that keeps messages, viewpoints, disagreements and conclusions |
+| Member | An AI instance in the room. One platform can have several instances (e.g. `Claude`, `Claude-评审`), each with its own session and model |
+| Host | A locally woken AI that routes unaddressed messages; it can also act as an expert |
+| You | The room owner, who can `@` any member at any time |
+
+## Free Collaboration
+
+- **Mention** — `@member` and it works in its own original session; several members can run in parallel.
+- **Unaddressed messages** go to the host. With a single member, they go straight to it.
+- **Host delegation** — when the host mentions one member, that member replies to you directly; when it mentions several, the host summarizes after they finish.
+- **Everyone** — `@全体成员` asks all members to answer; `@全体依次` asks them one after another in speaking order.
+- **Stop and retry** — stop a member's current run from its menu; failed runs can be resent with one click.
+
+Mentions between ordinary members are references only and do not wake anyone. Members sharing a project directory are not locked; you decide who edits which files, and the member panel warns when two members changed the same file at the same time.
+
+## Discussions
+
+Click **Start discussion** (开启讨论) in the member panel, or check **Start discussion after creating** (创建后开启讨论) when creating a room:
+
+1. Write a goal and set round and time limits (3 rounds and no time limit by default in the web UI).
+2. The host breaks down the question and schedules speakers. Experts first give independent views, then respond to each other.
+3. When a limit is reached, the host declares the goal done, or you click **End**, the room returns to free collaboration with history and conclusions kept. You can start another discussion later.
+
+You can `@` any member during a discussion without using a round. Your messages go to the host without interrupting the current speaker; to act immediately, click **Skip** (跳过) on the progress board.
+
+### Named Follow-ups
+
+With **Named follow-ups** (点名追问) enabled, the host writes a targeted follow-up for each expert after every round. When disabled (the default), experts read the previous round and respond to each other directly, and the host only steers.
+
+### Limits
+
+| Limit | Description |
+| --- | --- |
+| Rounds | One round is one viewpoint from every expert |
+| Total time | Counts only active time; paused time is excluded |
+| Single run | A run that exceeds it pauses the discussion |
+
+The discussion ends when a limit is reached. Reaching a limit does not mean consensus was reached.
+
+## Smart Scheduling
+
+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, or to no one; otherwise to the host.
+- For `@全体成员`, it decides whether members answer together or in order.
+- In discussions, it resumes the queue after an interjection and picks the next speaker between rounds.
+
+It acts only when confident, and otherwise hands over to the host. Every decision is shown in the conversation and can be rated. The room title and recent messages are sent to the chosen provider.
+
+## Managing Members
+
+From the member panel you can:
+
+- **Invite** members. Codex and Claude can join with an existing session ID, bringing that session's context. Experts invited during a discussion join the end of the current round.
+- **Pause, recall or remove** members without pausing the discussion.
+- **Change the host** with the crown icon. Changing the host during a discussion pauses it.
+- **Reorder speakers** by dragging pending members in the speaking-order list.
+
+Project file access is set per member and is read-only by default.
+
+## Manual Members and Web Chatbots
+
+- **Manual** — the member is not woken automatically; it reads and writes with its own credential file, triggered by you or by its tool's scheduler. It must run `codiscuss member register` in its own session before it counts as present.
+- **Web chatbots** can only read the room. Copy the reading notice from the member panel, then choose **Relay** (代发) in the composer to paste their reply. Web chatbots cannot reach a local address.
+
+The host of a discussion must be woken locally; web chatbots take part in free collaboration only.
+
+## Skills
+
+Agents follow the bundled skills, which `codiscuss setup` installs for the tools you select:
+
+| Skill | Used by | Purpose |
+| --- | --- | --- |
+| [discuss-participant](../../.agents/skills/discuss-participant/SKILL.md) | All members | Reading, posting and reliable writes |
+| [discuss-host](../../.agents/skills/discuss-host/SKILL.md) | The host (together with the participant skill) | Scheduling, progress and wrap-up |
+| [discuss-report](../../.agents/skills/discuss-report/SKILL.md) | Report writers | Turning a finished discussion into a sourced report |
+
+In Codex, invoke them as `$discuss-host`. In other tools that do not discover them automatically, ask the agent to read the corresponding `SKILL.md`.
+
+## Attachments and Export
+
+- **Attachments** — up to 10 per message and 20 MiB each; images and PDFs preview in place. Uploading does not mean an agent has read the file.
+- **Export and import** — **Export conversation** (导出对话) downloads the raw data and attachments; **Import room** (导入房间) on another site creates a copy you can keep using.