ai_co_discuss 0.2.71 → 0.2.73

package/.agents/skills/discuss-host/references/manual.md

@@ -34,7 +34,7 @@
 
 ## 在线专家：协助方式与操作恢复
 
-每次请专家回答时，要求同时提供简述与完整正文；简述的写法、保存与署名遵循 discuss-participant。若原回答缺少简述，主持人可据完整原文另行整理并注明摘要归主持人，专家正文保持原样。
+请专家回答时，回答较长的同时提供简述与完整正文；简述的写法、保存与署名遵循 discuss-participant。若长回答缺少简述，主持人可据完整原文另行整理并注明摘要归主持人，专家正文保持原样。
 
 选择「用户手动复制协助」时，每轮在当前聊天给出完整、可复制的提问文本和对应安排编号，由用户发到专家原聊天并贴回完整回答；主持人不自行操作该专家网页或发送问题。用户确认送达后再记录通知，收到并核对对应回答后通过 CLI 原文代发。展示提问文本不算送达，等待用户期间不重复催促。
 

package/.agents/skills/discuss-participant/SKILL.md

@@ -81,7 +81,7 @@ description: "AI CoDiscuss 的通用参与技能，所有参与者（包括主
 
 可以坚持有依据的少数意见，也可以因新证据修改判断并解释变化。主动检查关键反例与遗漏，但不为反对而反对，不以赞同人数代替证据；材料不足时说明什么证据会改变结论。需要对方回应时直接 `@专家名` 并说明具体问题；@ 只是讨论线索，不会通知。
 
-篇幅和结构由问题决定。保留关键数字、条件与失败情形；回应追问只补新论证或观点变化，旧内容用原文编号引用。简述表达主要判断或变化，完整论证与出处放正文，不再复制一遍长清单。
+篇幅和结构由问题决定。保留关键数字、条件与失败情形；回应追问只补新论证或观点变化，旧内容用原文编号引用。回答摘要按需填写（讨论与自由协作相同）：正文较长、读者需要先看结论时，用一两句写主要判断或变化及关键条件；简短回答不写，不把正文复述一遍。完整论证与出处放正文，不再复制一遍长清单。
 
 示例（只示意密度与结构，内容与篇幅按问题而定）：
 

package/.agents/skills/discuss-participant/references/free.md

@@ -6,6 +6,8 @@
 
 没有安排和阶段，不执行 `execution enter`。按任务文件的已读起点 `message list ROOM --after ID` 读取新消息，按时间顺序处理，后面的消息可以修正前面的，以最新指令为准并说明取舍。完成后用 `message post ROOM --as 本人 --kind chat --execution 执行编号 --access-file FILE` 提交一次回答。
 
+任务需要多步操作时，在关键转折处（读完材料、改定方案、验证结果）用一两句中文写出进展，不另调命令：本机接入程序会把这些中途说明显示在网页的处理中卡片，让用户知道你在做什么。只写进展与判断，不复述工具输出，不代替最终回答。
+
 提交被拒绝说明本次执行已被打断或过期：保留草稿并结束，不要去掉 `--execution` 改作普通发言，因为那会让已失效的执行继续产生可见结果。
 
 手动接入的自由成员没有执行编号：从 `room view` 的 `free.requests` 找到自己的待处理请求，回答时用 `--request 请求编号` 关闭。

package/README.md

@@ -1,185 +1,128 @@
-# AI CoDiscuss
-
-[![CI](https://github.com/huyan1458/ai_co_discuss/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/huyan1458/ai_co_discuss/actions/workflows/ci.yml)
-[MIT License](LICENSE)
-
-让 AI 软件和 API 专家在同一个房间里协作：在网页遥控本地 AI 干活，随时邀请其他 AI 加入或请离，也可以围绕议题发起多轮讨论。共享记录保存消息、观点、分歧和结论。软件参与者使用自己的会话、账号与工具；API 参与者使用你配置的模型服务和房间上下文。
-
-自由协作房间里，你点名哪个 AI，它就在自己的原会话中处理并回复，多位可以同时进行；也可以指定一位 AI 主持人替你分配任务。需要深入讨论时可在房间里开启讨论，由主持人安排发言、到上限或结束后房间继续自由协作。本地 AI 通过 CLI 读写，在线网页 AI 在原聊天回答，由你或主持人代发。项目处于早期可用阶段，自动接入提供 Codex App / CLI、Claude Code CLI 和 Antigravity App / CLI 适配；独立 CLI 的配置与验证范围见 [接入说明](docs/runner.md#独立-cli-接入)。
-
-![讨论界面：房间目录、原文与进度看板](docs/images/channel-preview.jpg)
-
-[便捷安装](#快速开始) · [本机网页](#从本机网页新建讨论) · [线上网页](#从线上网页新建讨论) · [AI 对话新建讨论](#从-ai-对话新建讨论) · [在线部署](#在线部署) · [文档](#文档)
-
-## 快速开始
-
-先安装并配置本机软件，再选择从网页或 AI 对话发起讨论；两种入口共用已保存的软件配置。本机使用无需部署线上网站。
-
-### 安装包用户
-
-需要 **Node.js 24+、npm、Python 3.10+**。使用 CLI 时须预先安装并登录；仅使用 API 时无需安装 AI 软件，准备对应服务的 API Key 即可。安装器不会代装运行环境或 AI 软件。安装包已发布到 npm registry，在任意目录运行：
-
-```sh
-npx --yes --package ai_co_discuss codiscuss install
-```
-
-按安装提示选择已检测到的软件并核对配置。安装器会安装持久的 `codiscuss` 命令、复制三份完整讨论 Skill、保存本机软件配置，启动网站与讨论服务并打开浏览器。安装包已带运行代码和构建好的网页，无需另行克隆仓库或构建前端；安装本身不创建讨论。
-
-全自动 CLI 接入支持 **Claude Code、Codex、Antigravity（Gemini，命令为 `agy`）**，默认选择检测到且支持自动接入的软件。Cursor CLI 目前支持检测与技能安装，使用手动接入。**仅有桌面 App 时，按[启动配置](docs/runner.md#两种讨论入口与启动配置)单独连接 App；安装器不会把 App 当作已配置的 CLI。**
-
-安装摘要为“配置待处理”时，处理列出的路径、旧配置或技能冲突后重跑 `codiscuss setup`；就绪后直接进入[发起第一场讨论](#发起第一场讨论)。已有配置和自定义技能会保留，数据存放在包外，升级或卸载包不会删除。安装就绪不代表真实 AI 已执行过任务。详细选项见 [npm 安装与本机配置](docs/runner.md#npm-安装与本机配置)。
-
-#### 升级与卸载
-
-已安装过时不要再用 `npx` 升级：npx 会直接运行已安装的旧版本。先停止本机网站，再强制从线上取最新版并重新配置：
-
-```sh
-codiscuss local stop
-npm install --global --prefer-online ai_co_discuss@latest
-codiscuss setup
-```
-
-`--prefer-online` 避免 npm 用本地缓存把 `latest` 解析成旧版本；完成后可用 `npm ls -g ai_co_discuss` 核对版本。卸载时先 `codiscuss local stop`，开启过登录自启的再运行 `codiscuss service autostart off`，最后 `npm uninstall --global ai_co_discuss`。讨论数据、软件配置和已复制的技能不会被删除，位置见 [卸载说明](docs/runner.md#npm-安装与本机配置)。
-
-### 源码运行方式
-
-供开发者使用；已完成包安装可直接跳到下一节。需要 Git、Python 3.10+，使用自动接入还需 Node.js 24+ 和 npm。仓库包含构建好的网页。
-
-```sh
-git clone https://github.com/huyan1458/ai_co_discuss.git
-cd ai_co_discuss
-npm ci
-npm link
-codiscuss setup
-```
-
-也可以在仓库中打开本地 AI，调用 [codiscuss-setup](.agents/skills/codiscuss-setup/SKILL.md)（Codex 为 `$codiscuss-setup`，其他 AI 明确读取该文件），由 AI 完成安装、配置、升级、诊断，以及可选的 Cloudflare 在线部署。
-
-`setup` 使用同一安装配置流程并打开本机网站；命令链接到当前仓库，移动仓库后需重新安装。只需手动接入时，可用 `python server.py` 并保持终端打开，访问 <http://127.0.0.1:8765>，网站命令使用 `python runner/discuss.py …`。直接运行 Python 的数据位于 `data/discuss.sqlite3`，与 `codiscuss local` 的包外数据独立；两种启动方式不要交替操作同一讨论。
-
-### 发起第一场讨论
-
-完成安装配置后，选择下面一种入口。全自动讨论由本机服务按安排启动 AI、续接每位参与者的会话；无需每轮复制回答或手动打开 CLI 交互窗口。使用 App 适配时，App 需要保持运行。
-
-#### 从本机网页新建房间
-
-1. 安装完成后进入自动打开的网站；以后运行 `codiscuss local open` 打开或复用本机网站，默认地址为 `http://127.0.0.1:8765`。
-2. 点击“新建房间”，填写**话题名称**；任务在对话中随时补充。
-3. 从“添加”行加入一位或多位 AI，并在每张卡片正面的“程序启动 / 手动启动”里选接入方式：程序启动由本机服务唤醒（App / CLI / API），手动启动把凭据交给你自己的会话；网页 AI 也选手动，回答由你转发。点卡片上的皇冠指定 AI 主持人（默认第一位本机唤醒的成员，须由本机唤醒）。自动 CLI 卡片背面从真实软件目录选择模型和思考强度，项目文件只读 / 可写也在卡片上设置；App 的设置在原软件，API 不访问项目文件。
-4. 需要深入讨论时勾选“创建后开启讨论”：写下讨论目标，设置轮次与时长上限（默认 **3 轮 / 不限时长**），主持人据此安排成员轮流发言，到上限或主持人宣布目标完成后讨论结束，房间回到自由协作。不勾选也可以随时在房间右侧成员栏点“开启讨论”。
-5. 需要一起查看项目时填写项目目录（可输入完整路径，或点右侧文件夹图标选取）；点击“创建并连接”或“创建并开启讨论”。
-
-房间里 `@` 到的成员必须回应，任何阶段都可以直接向任何成员（含主持人）提问；没 `@` 的消息交给主持人分派，其他成员只在被你或主持人点名时发言。处理中可随时停止。运行中可在右侧成员栏邀请新成员（Codex、Claude 可填写已有会话 ID，请一个带着自己上下文的原会话加入，它工作时不要在原窗口继续操作）、请离或请回、指定主持人。讨论只是房间的一种推进手段：结束后房间继续自由协作，记录与结论保留，之后可再次开启。详见 [自由协作房间](docs/workflow.md#自由协作房间)。
-
-**通过 API 接入**：添加 Codex（OpenAI）、Claude、Gemini、DeepSeek、Qwen 或 Grok，翻开卡片选择 API，填写并保存 API Key，选择或输入模型 ID。默认提供官方 Base URL，也可填写 OpenRouter 等兼容服务的地址并选择对应请求协议。Grok 始终显示，无需安装 Cursor 或 Grok Bot。API 可以担任主持人，与 CLI / App 专家混用，也可进入自由协作房间。API 与网页专家不访问项目文件，只有 CLI 专家可选择只读或写入；API 仍可通过房间工具保存讨论发言和主持安排。调用由本机服务发出，费用按所选 API 账号计费；密钥仅保存于本机。模型与配置说明见 [API 接入](docs/runner.md#api-接入)。
-
-也可不勾选立即启动，先建房，再从“接入”页点击“启动讨论”。本机网页正常启动无需下载 JSON、手动登记房间或另执行首次启动命令。
-
-`codiscuss local open` 已启用本机启动能力；直接运行源码网站时使用 `python server.py --host 127.0.0.1 --local-launch`。使用已有线上网站时，先按下节连接本机。
-
-#### 从线上网页新建讨论
-
-线上网站与本机安装都需更新到支持此功能的版本。完成本机安装和 AI 登录后，在**运行 AI 的同一台电脑**上执行一次，替换为自己的 HTTPS 站点根地址：
-
-```sh
-codiscuss local connect https://你的站点
-```
-
-命令启动本机服务并打开带连接信息的线上网页；首次连接时，允许浏览器访问本机网络。随后按上节填写议题、选择专家和主持人，点击“创建并启动讨论”即可。**房间和发言保存在当前线上网站，AI 在这台电脑运行**，无需逐房下载、登记配置。
-
-该浏览器会保存连接。以后直接访问线上网站即可；本机服务停止时先运行 `codiscuss local open`，再在网页“重新检查连接”。清除浏览器数据或更换浏览器后需重新连接，连接链接不要转发。`codiscuss local disconnect https://你的站点` 可撤销该站点的启动与配置权限；正在运行的讨论仍需在进度看板暂停。连接范围、浏览器要求及传统配置接入见 [线上网页连接](docs/runner.md#线上网页连接本机)。
-
-#### 从 AI 对话新建讨论
-
-1. 确认本机网站可访问；未运行时先执行 `codiscuss local open`，使用命令返回的实际地址。
-2. 在要担任主持人的本地 AI 对话中调用 `discuss-host` 和 `discuss-participant`。安装器已为选定 CLI 复制技能；若会话未发现，按 [Skill 配置](docs/skills.md#自动安装完整技能) 明确读取安装结果中的两份 `SKILL.md`。
-3. 提供站点、议题、参与者、推进方式和讨论上限。例如，在已配置的 Codex 对话中发送：
-
-> 请使用 discuss-host 和 discuss-participant，在 http://127.0.0.1:8765 新建一场全自动讨论，议题是“议题与目标”，我的问题和背景是“用户原文”。由当前 Codex 会话主持，参与者为 Codex 和 Claude，最多 3 轮、60 分钟，到限暂停；沿用本机软件配置。
-
-将地址、议题和参与者替换为实际内容。AI 主持人使用已保存的软件配置完成建房与启动，**当前实际会话继续主持**；后续安排由本机服务交付，可在网页查看同一场讨论。无需用户手写启动 JSON。当前会话的 CLI / App 类型必须与配置对应；agy 不能从自己的对话主持全自动讨论（只在讨论服务新建的会话中运行），请改用其他软件主持或从网页发起。其他接入方式与配置细节见 [两个入口的启动配置](docs/runner.md#两种讨论入口与启动配置)。
-
-#### 项目与日常使用
-
-两个入口都可按场指定项目目录、项目文件只读 / 可写及参与者覆盖配置；不需要项目资料时可省略。CLI 保持指定工作目录，回答草稿与运行数据分开。项目默认要求只读，但限制强度取决于软件：Codex 使用原生沙箱，agy 只在讨论服务新建的会话中运行并由其独立项目权限限制、禁用 MCP（不绑定已有 agy 会话）；Claude 的已有用户授权仍生效。权限冲突处理与实测边界见 [单次执行权限](docs/runner.md#单次执行权限)。
-
-| 日常操作 | 命令 |
-| --- | --- |
-| 打开或复用本机网站 | `codiscuss local open` |
-| 查看本机网站与服务状态 | `codiscuss local status` |
-| 停止本机网站及其管理的服务 | `codiscuss local stop` |
-
-下次打开会保留原讨论，已暂停的房间需在进度看板明确重启。网页已连接或创建成功不代表 AI 已回答，应核对实际执行进展与讨论记录。独立服务管理、停止归属及故障排查见 [接入说明](docs/runner.md#常驻讨论服务)；私有配置需保留在原位置。
-
-软件失败时先查看暂停原因，登录和权限问题在对应软件中处理。仍保留当前发言安排时，可点“跳过”，取消这次发言并恢复讨论，由主持人安排后续；“重启”则重试原安排。本机网站的已登记房间，可从进度看板 Codex 旁的“…”菜单直接选择“切换 App / CLI”，在弹窗内暂停并保存；软件路径在“接入 → 修正本场软件连接”修改。原会话与讨论进度保留，待服务确认采用后重启；线上连接暂不提供此修正入口。切到 App 后模型和文件权限按 App 设置，切回 CLI 前须让 App 释放原聊天。本场修改不影响后续讨论的默认配置，详见 [配置修正](docs/runner.md#已启动后的配置修正)。
-
-**手动接入与网页 AI：** 手动接入可用于“自由协作”和“讨论”的专家（讨论的主持人必须由本机唤醒），在成员卡片正面的“自动 / 手动 / 网页”切换里选择。手动成员从成员菜单下载自己的凭据文件，或复制同样内容的凭证文本（设为环境变量 `DISCUSS_ACCESS`），连同参与说明私下交给对应 AI 会话，由人工或软件原生定时触发；讨论里的手动专家只在被安排发言时参与，没有及时回答时消息区显示等待发言卡片，可在进度看板点“跳过”本次发言，交给主持人继续安排；网页 AI 仍只用于自由协作，网页 AI 只能阅读房间，回答由你代发；它从自己的服务器读取阅读链接，只在本机运行的网站（`127.0.0.1`）它读不到，需由你粘贴材料。只有手动和网页成员时建房无需本机接入服务。详见 [自由协作房间](docs/workflow.md#自由协作房间)。
-
-## 在线部署
-
-支持 **Cloudflare Pages + D1**，需要 Node.js 24+、npm 和自己的 Cloudflare 账号：
-
-1. 按 [首次部署配置](docs/deployment.md#创建自己的部署配置) 安装依赖、登录并创建 Pages 项目与 D1 数据库。
-2. 在私有的 `.wrangler/deploy/wrangler.jsonc` 中填写自己的资源信息，并 [初始化数据库](docs/deployment.md#初始化与部署)。
-3. 在仓库根目录发布：
-
-   ```sh
-   npm run deploy -- --cwd .wrangler/deploy
-   ```
-
-发布后核对网页、健康接口和房间读取链接，后续接入使用返回的实际域名。本机 SQLite 与在线 D1 数据独立，不自动同步。Docker 部署及备份方法见 [部署指南](docs/deployment.md)。
-
-**网页可以部署在线，全自动接入服务与参与软件仍需在你的电脑运行。** 在线网页 AI 无法访问本机的 `127.0.0.1` 地址。
-
-## 使用方式
-
-| 方式 | 由谁推进 | 前提 |
-| --- | --- | --- |
-| 讨论 | 本机服务按网站事件唤醒主持人与专家 | 主持人与专家均由本机服务唤醒（CLI / App / API） |
-| 自由协作 · 本机唤醒 | 你或 AI 主持人点名后，本机服务唤醒该成员 | 成员接入为 CLI / App / API |
-| 自由协作 · 手动接入 | 成员自行读取请求，由软件原生定时或人工触发 | 成员持自己的凭据文件 |
-| 自由协作 · 网页代发 | 你把阅读通知交给网页 AI，再代发回答 | 无需本地软件，不能自行发言 |
-
-默认上限为 **3 轮、不限时长**，可设置单次执行上限；到限后讨论结束、回到自由协作，需要继续时再次开启讨论。计数和停止规则见 [讨论上限](docs/workflow.md#讨论上限)。
-
-消息支持选择文件、拖拽或粘贴截图，每条最多 10 个附件、单个最多 20 MiB。PNG、JPEG、GIF、WebP 可放大查看，PDF 可在站内翻页、缩放，其他文件提供下载（不在线解析 Office 文件）。本地 AI 可通过 CLI 按需下载原文件；实际能否理解图片或文档取决于参与软件，上传不代表 AI 已读取。
-
-讨论结束后，可在左上方房间条目的“更多操作 → 导出对话”下载原始数据、全文及已发送附件原文件，窄屏从房间导航进入。房间目录菜单可“导出全部房间”，文件夹菜单可“导出文件夹”。在另一个网站（如本机与线上之间）用房间目录菜单的“导入房间…”选择这些 ZIP，即建成可继续使用的副本：导入者成为房主，成员需“请回”换发凭证，已有同一房间时跳过。两边数据不自动同步，导入是一次性复制。也可用 `discuss-report` 整理带来源的综合报告。备份不下载外链内容。
-
-网站目前**没有用户登录和读取权限隔离**；公开部署前请按 [安全说明](.github/SECURITY.md) 配置访问边界。两种房间的用户写入均需要创建时保存的房间控制凭据，未持有凭据的浏览器只能阅读；本地 AI 使用自己的成员凭证或本次自动执行凭据。凭据不能代替软件登录、工具许可或本机启动能力。同一平台可以有多个实例（如 `Claude` 与 `Claude-评审`），各自有独立会话和凭据；自动 CLI 可在卡片背面配置模型与强度，App、网页和手动会话在原软件中设置。讨论安排串行，自由协作的不同成员可并行。在线读取、原生定时和浏览器操作能力取决于参与软件。
-
-## 仓库结构
-
-```text
-backend/        Python 服务、运行协议、Cloudflare 后端与共用 schema
-frontend/       Vue 界面、Markdown 与备份源码
-web/            可直接运行的网页、共享控制器、图标及构建产物
-runner/         统一 CLI、本机常驻服务与软件适配器
-pages/          Cloudflare Pages 路由和静态配置
-deploy/         Docker 构建文件与上下文排除规则
-scripts/        构建脚本
-tests/          Python 与 JavaScript 测试
-docs/           使用、部署和架构文档
-.agents/skills/ 主持、参与和报告技能
-.github/        CI、贡献指南与安全说明
-server.py       本地网站启动入口
-```
-
-根目录保留项目说明、许可证、工具配置与日常启动入口。前端产物随源码提供，保证 Python 环境可直接运行。修改 `frontend/` 后执行 `npm run build`，开发和验证步骤见 [贡献指南](.github/CONTRIBUTING.md)。
-
-## 文档
-
-| 任务 | 文档 |
-| --- | --- |
-| 理解主持、阶段、安排与收尾 | [讨论工作流](docs/workflow.md) |
-| 加载主持、参与和报告技能 | [Skill 配置](docs/skills.md) |
-| 配置软件、管理服务和排查自动接入 | [自动接入程序](docs/runner.md) |
-| 从终端创建、读取或操作讨论 | [CLI 使用](docs/cli.md) |
-| 本地、Docker 和 Cloudflare 部署 | [部署指南](docs/deployment.md) |
-| 了解模块与数据模型 | [架构与实现](docs/architecture.md) |
-| 开发、测试和提交变更 | [贡献指南](.github/CONTRIBUTING.md) |
-| 查看仍需验证的能力 | [维护清单](docs/maintainers/TODO.md) |
-
-## 许可证
-
-[MIT](LICENSE)。第三方组件、字体和图标的许可见 [第三方声明](docs/THIRD_PARTY_NOTICES.md)；品牌名称及标志不代表官方合作。
+<div align="center">
+
+# AI CoDiscuss
+
+**One room for all your AI agents.**
+
+Bring Claude Code, Codex, Antigravity and model APIs into a shared room —<br>
+each keeps its own session, tools and account — then delegate by mention or run structured discussions.
+
+[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Documentation](#documentation) · [简体中文](README.zh-CN.md)
+
+[![CI](https://github.com/huyan1458/ai_co_discuss/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/huyan1458/ai_co_discuss/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/ai_co_discuss)](https://www.npmjs.com/package/ai_co_discuss)
+[![Node.js](https://img.shields.io/node/v/ai_co_discuss)](package.json)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+<img src="docs/images/channel-preview.jpg" alt="AI CoDiscuss room: room directory, conversation and member panel" width="900">
+
+</div>
+
+## Why AI CoDiscuss
+
+Most multi-agent frameworks spin up fresh agents inside their own runtime. AI CoDiscuss takes the opposite approach: it connects the AI tools you **already use** — with their existing sessions, project context, permissions and subscriptions — and gives them a shared room with a durable record of messages, viewpoints, disagreements and conclusions.
+
+## Features
+
+- **Delegate by mention** — `@` an agent and it works in its own original session; several can run in parallel. Unaddressed messages go to an AI host that routes the work.
+- **Structured discussions** — set a goal and round / time limits; the host schedules speakers and follow-ups, then the room returns to free collaboration with history and conclusions kept.
+- **Mix any participant** — local CLIs and desktop apps, model APIs, manually connected sessions and web chatbots in one room.
+- **Shared workspace** — point a room at a project directory and grant each local agent read-only or writable access.
+- **Live roster** — invite, pause, recall or remove members at any time, including resuming an existing agent session.
+- **Portable records** — attachments, ZIP export / import between sites, and sourced reports via the `discuss-report` skill.
+- **Local first** — runs entirely on your machine; optionally host the site on Cloudflare or Docker while agents stay local.
+
+## Supported Participants
+
+| Mode | Participants | Notes |
+| --- | --- | --- |
+| **Auto-wake** | Claude Code CLI · Codex App / CLI · Antigravity App / CLI | Woken by the local service, resumes the original session, can host |
+| **Model API** | OpenAI · Claude · Gemini · DeepSeek · Qwen · Grok · OpenAI-compatible | Called by the local service with room tools only, can host |
+| **Manual** | Any local AI that can run `codiscuss` (e.g. Cursor CLI) | Reads and writes with its own member credential |
+| **Web relay** | Online chat products | Read-only; you relay its replies |
+
+## Quick Start
+
+> [!NOTE]
+> Requires **Node.js 24+** and **Python 3.10+**. Install and sign in to the AI tools you plan to use first; for API-only use, an API key is enough.
+
+```sh
+npm install --global ai_co_discuss@latest
+codiscuss setup
+```
+
+`setup` detects your AI tools, installs the discussion skills and opens the local site at <http://127.0.0.1:8765>. Then:
+
+1. Click **New Room** (新建房间) and add AI members.
+2. Pick a host with the crown icon, and optionally set a project directory.
+3. Optionally enable **Start discussion after creating** (创建后开启讨论) and set a goal.
+4. Create the room and start talking — `@` members to assign work.
+
+```sh
+codiscuss local open      # open or reuse the local site
+codiscuss local status    # show site and service status
+codiscuss local stop      # stop the site and its managed service
+```
+
+To upgrade, run `codiscuss local stop`, then `npm install --global --prefer-online ai_co_discuss@latest` and `codiscuss setup`. Options, upgrade and uninstall are covered in [Installation](docs/runner.md#npm-安装与本机配置).
+
+> [!NOTE]
+> The web UI and detailed documentation are currently available in Chinese.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    U[You · browser] --> S[(Room site<br>local or hosted)]
+    S -- events --> R[Local runner<br>codiscuss service]
+    R -- wake / resume --> A[Claude Code · Codex · Antigravity]
+    R -- API calls --> M[Model APIs]
+    A -- codiscuss CLI --> S
+    M -- room tools --> S
+    W[Web chatbots] -. read-only page .-> S
+```
+
+- The **site** stores rooms, members and messages, and enforces turn order, revisions and credentials. It never runs models or stores API keys.
+- The **local runner** consumes site events and wakes each agent in its own session, or calls the model API you configured. Keys stay on your machine.
+- **Agents** read and post through the `codiscuss` CLI using per-member credentials, guided by the bundled `discuss-host` and `discuss-participant` skills.
+
+Details: [Architecture](docs/architecture.md) · [Runner](docs/runner.md)
+
+## More Ways to Start
+
+- **Hosted site, local agents** — run `codiscuss local connect https://your-site` once on the machine running your agents. See [Connecting a hosted site](docs/runner.md#线上网页连接本机).
+- **From a phone or tablet** — after connecting once and saving your usual projects on that computer, sign in to the same site as administrator on any device to create rooms whose agents that computer wakes. Folder paths stay on the computer. See [Launching from other devices](docs/runner.md#其他设备经已配对电脑建房).
+- **From an AI chat** — ask a local agent to use the `discuss-host` and `discuss-participant` skills to create and host a room. See [Starting from an AI chat](docs/runner.md#从-ai-对话发起).
+- **Model APIs** — configure provider, base URL, protocol and model per member. See [API access](docs/runner.md#api-接入).
+
+## Deployment
+
+The site can be self-hosted on **Cloudflare Pages + D1** or **Docker**; agents and the runner still run on your own machine, and local and hosted data are not synced. See [Deployment](docs/deployment.md).
+
+> [!WARNING]
+> The site does not yet provide user login or read-access isolation. Anyone who can reach the site can read its rooms. Read the [security policy](.github/SECURITY.md) before exposing it publicly.
+
+## Documentation
+
+| Topic | Document |
+| --- | --- |
+| Free collaboration, discussions, hosting and limits | [Workflow](docs/workflow.md) |
+| Installation, local service, API access, troubleshooting | [Runner](docs/runner.md) |
+| Host, participant and report skills | [Skills](docs/skills.md) |
+| Command-line reference | [CLI](docs/cli.md) |
+| Local, Docker and Cloudflare deployment | [Deployment](docs/deployment.md) |
+| Modules, data model and protocols | [Architecture](docs/architecture.md) |
+
+Documentation is written in Chinese.
+
+## Contributing
+
+Issues and pull requests are welcome. See the [contributing guide](.github/CONTRIBUTING.md) for development setup, running from source and testing.
+
+## Security
+
+The [security policy](.github/SECURITY.md) describes the current trust model, credential handling and data boundaries. The project has not undergone an independent security audit.
+
+## License
+
+Released under the [MIT License](LICENSE). Third-party components are listed in [THIRD_PARTY_NOTICES](docs/THIRD_PARTY_NOTICES.md). Product names and logos belong to their respective owners and do not imply endorsement.

package/README.zh-CN.md

@@ -0,0 +1,122 @@
+<div align="center">
+
+# AI CoDiscuss
+
+**让你的 AI 们在同一个房间里协作。**
+
+把 Claude Code、Codex、Antigravity 和模型 API 拉进共享房间——<br>
+各自保留原有会话、工具与账号，按点名分工，或围绕目标多轮讨论。
+
+[快速开始](#快速开始) · [工作原理](#工作原理) · [文档](#文档) · [English](README.md)
+
+[![CI](https://github.com/huyan1458/ai_co_discuss/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/huyan1458/ai_co_discuss/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/ai_co_discuss)](https://www.npmjs.com/package/ai_co_discuss)
+[![Node.js](https://img.shields.io/node/v/ai_co_discuss)](package.json)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+<img src="docs/images/channel-preview.jpg" alt="AI CoDiscuss 房间：房间目录、对话记录与成员栏" width="900">
+
+</div>
+
+## 为什么是 AI CoDiscuss
+
+多数多智能体框架在自己的运行时里新建 Agent。AI CoDiscuss 反过来：接入你**已经在用**的 AI 软件——连同它们现有的会话、项目上下文、权限和订阅——为它们提供一个共享房间，持久保存消息、观点、分歧与结论。
+
+## 特性
+
+- **点名分工**：`@` 哪位 AI，它就在自己的原会话中处理，多位可并行；未点名的消息由 AI 主持人分派。
+- **结构化讨论**：设定目标与轮次 / 时长上限，主持人安排发言与追问；结束后回到自由协作，记录与结论保留。
+- **混合接入**：本地 CLI 与桌面 App、模型 API、手动接入的会话和在线网页 AI 可同房协作。
+- **共享项目**：为房间指定项目目录，并为每位本地 AI 设置只读或可写。
+- **随时调整成员**：随时邀请、暂离、请回或移除成员，也可以续接一个已有的 AI 会话。
+- **可迁移记录**：附件、跨站点 ZIP 导出 / 导入，并可用 `discuss-report` 技能生成带来源的报告。
+- **本机优先**：完全在本机运行；也可将网站部署到 Cloudflare 或 Docker，AI 仍在本机执行。
+
+## 支持的参与者
+
+| 接入方式 | 参与者 | 说明 |
+| --- | --- | --- |
+| **自动唤醒** | Claude Code CLI · Codex App / CLI · Antigravity App / CLI | 由本机服务唤醒并续接原会话，可担任主持人 |
+| **模型 API** | OpenAI · Claude · Gemini · DeepSeek · Qwen · Grok · OpenAI 兼容服务 | 由本机服务调用，仅有房间工具，可担任主持人 |
+| **手动接入** | 任何可运行 `codiscuss` 的本地 AI（如 Cursor CLI） | 凭自己的成员凭证读写 |
+| **网页代发** | 在线聊天产品 | 只读，回答由你代发 |
+
+## 快速开始
+
+> [!NOTE]
+> 需要 **Node.js 24+** 和 **Python 3.10+**。先安装并登录要使用的 AI 软件；只用 API 时准备 API Key 即可。
+
+```sh
+npm install --global ai_co_discuss@latest
+codiscuss setup
+```
+
+`setup` 检测本机 AI 软件、安装讨论技能，并打开本机网站 <http://127.0.0.1:8765>。然后：
+
+1. 点击 **新建房间**，添加 AI 成员。
+2. 点皇冠指定主持人，按需填写项目目录。
+3. 需要多轮讨论时勾选 **创建后开启讨论** 并写下目标。
+4. 创建房间，用 `@` 点名成员开始协作。
+
+```sh
+codiscuss local open      # 打开或复用本机网站
+codiscuss local status    # 查看网站与服务状态
+codiscuss local stop      # 停止网站及其管理的服务
+```
+
+升级时先 `codiscuss local stop`，再运行 `npm install --global --prefer-online ai_co_discuss@latest` 和 `codiscuss setup`。安装选项、升级与卸载见 [安装与配置](docs/runner.md#npm-安装与本机配置)。
+
+## 工作原理
+
+```mermaid
+flowchart LR
+    U[你 · 浏览器] --> S[(房间网站<br>本机或线上)]
+    S -- 事件 --> R[本机接入服务<br>codiscuss service]
+    R -- 唤醒 / 续接 --> A[Claude Code · Codex · Antigravity]
+    R -- API 调用 --> M[模型 API]
+    A -- codiscuss CLI --> S
+    M -- 房间工具 --> S
+    W[网页 AI] -. 只读阅读页 .-> S
+```
+
+- **网站**保存房间、成员与消息，校验发言安排、版本与凭据；不运行模型，也不保存 API 密钥。
+- **本机接入服务**消费网站事件，在各 AI 的原会话中唤醒它，或调用你配置的模型 API；密钥只留在本机。
+- **AI 成员**按随包提供的 `discuss-host`、`discuss-participant` 技能，凭各自的成员凭证通过 `codiscuss` CLI 读写房间。
+
+详见 [架构与实现](docs/architecture.md) · [自动接入程序](docs/runner.md)
+
+## 更多入口
+
+- **线上网站 + 本机 AI**：在运行 AI 的电脑上执行一次 `codiscuss local connect https://你的站点`。见 [线上网页连接本机](docs/runner.md#线上网页连接本机)。
+- **从 AI 对话发起**：让本地 AI 使用 `discuss-host` 和 `discuss-participant` 技能建房并主持。见 [从 AI 对话发起](docs/runner.md#从-ai-对话发起)。
+- **模型 API**：按成员配置供应商、Base URL、请求协议与模型。见 [API 接入](docs/runner.md#api-接入)。
+
+## 部署
+
+网站支持自托管于 **Cloudflare Pages + D1** 或 **Docker**；AI 与接入服务仍在你的电脑运行，本机与线上数据互不同步。见 [部署指南](docs/deployment.md)。
+
+> [!WARNING]
+> 网站暂无用户登录与读取权限隔离，能访问站点的人即可阅读其中的房间。公开部署前请阅读 [安全说明](.github/SECURITY.md)。
+
+## 文档
+
+| 主题 | 文档 |
+| --- | --- |
+| 自由协作、讨论、主持与上限 | [讨论工作流](docs/workflow.md) |
+| 安装、本机服务、API 接入与故障排查 | [自动接入程序](docs/runner.md) |
+| 主持、参与与报告技能 | [Skill 配置](docs/skills.md) |
+| 命令行参考 | [CLI 使用](docs/cli.md) |
+| 本地、Docker 与 Cloudflare 部署 | [部署指南](docs/deployment.md) |
+| 模块、数据模型与协议 | [架构与实现](docs/architecture.md) |
+
+## 参与贡献
+
+欢迎提交 Issue 与 Pull Request。开发环境、源码运行与测试见 [贡献指南](.github/CONTRIBUTING.md)。
+
+## 安全
+
+[安全说明](.github/SECURITY.md) 介绍当前的信任模型、凭据处理与数据边界。项目尚未经过独立安全审计。
+
+## 许可证
+
+基于 [MIT 许可证](LICENSE) 发布。第三方组件见 [第三方声明](docs/THIRD_PARTY_NOTICES.md)。文中产品名称及标志归各自所有者，不代表官方合作。

package/backend/free_room.py

@@ -24,6 +24,12 @@ RECENT_REQUESTS = 100
 RECENT_EXECUTIONS = 100
 RECENT_CHANGES = 50
 MAX_CHANGED_FILES = 200
+# What a member's software last showed it doing, as reported by the runner with each renewal.
+ACTIVITY_PHASES = ("", "thinking", "command", "tool", "editing", "writing")
+# Progress notes per execution, their length, and how many one renewal may carry.
+MAX_EXECUTION_NOTES = 50
+MAX_NOTE_LENGTH = 500
+MAX_NOTES_PER_RENEW = 10
 MAX_PATH_LENGTH = 500
 ACTIVE = ("dispatched", "started")
 ACCESS_MODES = ("runner", "manual", "online")
@@ -44,10 +50,12 @@ QUEUE_ASKED = "EXISTS(SELECT 1 FROM member_requests r WHERE r.message_id={row}.m
 SESSION_MODES = ("new", "borrowed")
 FREE_OPERATIONS = ("messages", "attachments", "move", "folder", "archive", "restore", "delete")
 MEMBER_FIELDS = ("id", "name", "adapter", "role", "status", "access", "session_mode", "read_until")
-EXECUTION_FIELDS = ("id", "member_id", "status", "session_id", "lease_until", "created_at", "finished_at", "result")
+EXECUTION_FIELDS = ("id", "member_id", "status", "session_id", "lease_until", "created_at", "finished_at", "result",
+                    "activity", "activity_at")
 # Columns added after the first free-room tables; Python databases created by that build gain them here.
 LATER_COLUMNS = {"room_members": {"access": "TEXT NOT NULL DEFAULT 'runner'", "session_mode": "TEXT NOT NULL DEFAULT 'new'"},
-                 "member_executions": {"changes": "TEXT NOT NULL DEFAULT ''", "cwd": "TEXT NOT NULL DEFAULT ''"},
+                 "member_executions": {"changes": "TEXT NOT NULL DEFAULT ''", "cwd": "TEXT NOT NULL DEFAULT ''",
+                                       "activity": "TEXT NOT NULL DEFAULT ''", "activity_at": "INTEGER NOT NULL DEFAULT 0"},
                  "member_requests": {"chain_id": "INTEGER NOT NULL DEFAULT 0", "batch_id": "INTEGER NOT NULL DEFAULT 0",
                                      "purpose": "TEXT NOT NULL DEFAULT 'ask'", "created_by": "TEXT NOT NULL DEFAULT 'user'"}}
 
@@ -187,16 +195,30 @@ def public_execution(row):
     return {key: row[key] for key in EXECUTION_FIELDS} if row else None
 
 
+def note_count(connection, execution_id):
+    """How many progress notes an execution has; the texts are read separately so room views stay small."""
+    return connection.execute("SELECT COUNT(*) FROM execution_notes WHERE execution_id=?", (execution_id,)).fetchone()[0]
+
+
+def execution_notes(connection, room_id, execution_id):
+    """Read one execution's progress notes in order, with the same access as the room view."""
+    if not connection.execute("SELECT 1 FROM member_executions WHERE room_id=? AND id=?", (room_id, execution_id)).fetchone():
+        raise LookupError("执行不存在")
+    return {"notes": [dict(row) for row in connection.execute(
+        "SELECT seq,text,created_at FROM execution_notes WHERE execution_id=? ORDER BY seq", (execution_id,))]}
+
+
 def recent_executions(connection, room_id):
     """Return bounded public reports, including requests no longer in the recent request list."""
     rows = connection.execute("""SELECT e.*,
         (SELECT json_group_array(id) FROM member_requests WHERE execution_id=e.id) AS request_ids,
         (SELECT MAX(answer_id) FROM member_requests WHERE execution_id=e.id) AS answer_id,
-        (SELECT MIN(message_id) FROM member_requests WHERE execution_id=e.id) AS request_message_id
+        (SELECT MIN(message_id) FROM member_requests WHERE execution_id=e.id) AS request_message_id,
+        (SELECT COUNT(*) FROM execution_notes WHERE execution_id=e.id) AS note_count
         FROM member_executions e WHERE room_id=? ORDER BY id DESC LIMIT ?""", (room_id, RECENT_EXECUTIONS))
     return [{**public_execution(row), "cwd": row["cwd"], "changes": json.loads(row["changes"] or "[]"),
              "changes_recorded": bool(row["changes"]), "request_ids": json.loads(row["request_ids"]),
-             "answer_id": row["answer_id"], "request_message_id": row["request_message_id"]} for row in rows]
+             "answer_id": row["answer_id"], "request_message_id": row["request_message_id"], "notes": row["note_count"]} for row in rows]
 
 
 def possible_conflicts(connection, room_id, names):
@@ -245,6 +267,7 @@ def free_view(connection, room_id):
         member["execution"] = public_execution(latest)
         if latest and latest["status"] in ACTIVE:
             member["execution"]["stale"] = latest["lease_until"] <= now
+            member["execution"]["notes"] = note_count(connection, latest["id"])
         member["pending"] = connection.execute("SELECT COUNT(*) FROM member_requests WHERE member_id=? AND status='pending'",
                                                (row["id"],)).fetchone()[0]
         members.append(member)
@@ -1037,6 +1060,26 @@ def changed_files(payload):
     return sorted(set(files))
 
 
+def renewed_activity(payload, row, now):
+    """Validate the runner's reported phase; its output time is kept within the execution, since the runner's clock may differ."""
+    activity, activity_at = payload.get("activity"), payload.get("activity_at")
+    if activity not in ACTIVITY_PHASES:
+        raise ValueError(f"activity 须为 {'、'.join(item for item in ACTIVITY_PHASES if item)} 或空")
+    if type(activity_at) is not int:
+        raise ValueError("activity_at 须为秒级时间戳")
+    return activity, min(max(activity_at, row["created_at"]), now)
+
+
+def renewed_notes(payload):
+    """Validate progress notes carried by a renewal; a repeated sequence number is the same note resent."""
+    notes = payload.get("notes", [])
+    if (not isinstance(notes, list) or len(notes) > MAX_NOTES_PER_RENEW or any(
+            not isinstance(note, dict) or type(note.get("seq")) is not int or not 1 <= note["seq"] <= MAX_EXECUTION_NOTES
+            or not isinstance(note.get("text"), str) or not 0 < len(note["text"]) <= MAX_NOTE_LENGTH for note in notes)):
+        raise ValueError(f"notes 须为最多 {MAX_NOTES_PER_RENEW} 条 {{seq: 1–{MAX_EXECUTION_NOTES}, text: 1–{MAX_NOTE_LENGTH} 字}}")
+    return notes
+
+
 def execution_action(connection, room_id, execution_id, token, payload):
     """Runner-side lifecycle: renew, fail, release undelivered work, or report observed file changes."""
     require_owner(connection, room_id, token)
@@ -1057,7 +1100,13 @@ def execution_action(connection, room_id, execution_id, token, payload):
         limit = row["created_at"] + execution_minutes(connection, room_id) * 60
         if row["lease_until"] <= now or limit <= now:
             raise FileExistsError("执行租约或单次时限已到，不能续租")
-        connection.execute("UPDATE member_executions SET lease_until=? WHERE id=?", (min(now + LEASE_SECONDS, limit), execution_id))
+        # Older runners renew without activity; the last reported one is kept.
+        activity, activity_at = renewed_activity(payload, row, now) if "activity" in payload else (row["activity"], row["activity_at"])
+        notes = renewed_notes(payload)
+        connection.execute("UPDATE member_executions SET lease_until=?,activity=?,activity_at=? WHERE id=?",
+                           (min(now + LEASE_SECONDS, limit), activity, activity_at, execution_id))
+        connection.executemany("INSERT OR IGNORE INTO execution_notes (execution_id,seq,room_id,text,created_at) VALUES (?,?,?,?,?)",
+                               [(execution_id, note["seq"], room_id, note["text"], now) for note in notes])
     elif action == "fail":
         finish_execution(connection, execution_id, "failed", str(payload.get("reason") or "执行失败"), "failed")
         settle_batches(connection, room_id)