ai_co_discuss 0.1.11 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/.agents/skills/discuss-participant/SKILL.md +2 -0
  2. package/.github/SECURITY.md +2 -0
  3. package/README.md +181 -178
  4. package/backend/free_room.py +571 -0
  5. package/backend/identity.py +31 -0
  6. package/backend/schema.sql +573 -491
  7. package/backend/server.py +1722 -1588
  8. package/docs/architecture.md +233 -208
  9. package/docs/cli.md +14 -0
  10. package/docs/runner.md +8 -0
  11. package/docs/workflow.md +144 -125
  12. package/package.json +2 -2
  13. package/runner/discuss.py +874 -845
  14. package/runner/discussion_launch.mjs +138 -20
  15. package/runner/discussion_runner.mjs +4 -0
  16. package/runner/discussion_service.mjs +9 -1
  17. package/runner/free_runner.mjs +247 -0
  18. package/web/app.js +183 -12
  19. package/web/index.html +1 -1
  20. package/web/modern.css +1 -1
  21. package/web/modern.js +6817 -6442
package/.agents/skills/discuss-participant/SKILL.md CHANGED
@@ -32,6 +32,8 @@ description: "AI CoDiscuss 的通用参与技能，所有参与者（包括主
32
32
  - 本次受保护写入统一附同一 `--access-file`。只处理交付的职责和安排；专家提交答案即完成此执行，主持人的交接边界见主持技能。
33
33
  - 通知程序负责续租与后续交付。AI 不创建定时任务、不操作其他软件，不另发“就绪/完成”回执。确实无法继续时保留草稿，用 `execution fail ROOM EVENT --reason 原因 --access-file FILE` 暂停；已失效时不再写回执或清理消息。
34
34
 
35
+ **自由协作任务（任务文件含 `mode: "free"`）：** 没有发言权、安排和阶段，不执行 `execution enter`。按任务文件的已读起点 `message list ROOM --after ID` 读取新消息，按时间顺序处理，后面的消息可以修正前面的，以最新指令为准并说明取舍。完成后用 `message post ROOM --as 本人 --kind chat --execution 执行编号 --access-file FILE` 提交一次回答。提交被拒绝说明本次执行已被打断或过期：保留草稿并结束，不要去掉 `--execution` 改作普通发言。手动接入的自由成员没有执行编号：从 `room view` 的 `free.requests` 找到自己的待处理请求，回答时用 `--request 请求编号` 关闭。任务文件 `role` 为 `host` 时你是本房间主持人：`route` 请求是用户未点名的消息，`handoff` 表示你派出的成员都已结束；先 `room view` 看成员，需要他人时在回答中加 `--to 成员名` 派活并说明各自负责的文件或模块，不需要时不加，本次即结束；不点名自己，不扩大用户给的权限。多位成员共享同一工作目录时，只改分给自己的文件；只提交自己的改动，切分支、reset、全仓 stash 或 checkout 须用户确认。
36
+
35
37
  **手动接入：** 用户已选手动时沿用人工触发或原生定时；需要持续参与才读 [手动持续参与](references/manual.md)。没有任务文件本身不代表手动授权：若房间正在自动运行，等待本次交付或核对缺项，不从旧文件接管。受保护房间的手动写入使用用户提供的私有接入文件。
36
38
 
37
39
  ## 先读什么
package/.github/SECURITY.md CHANGED
@@ -4,6 +4,8 @@
4
4
 
5
5
  项目没有用户登录、读取权限隔离或租户隔离，默认站点只由信任的使用者访问。`--as`、作者、主持人均为客户端声明。显式启用运行配置后，凭据只用于程序与 AI：接入程序用控制凭据读取事件、领取任务、续租和启动；AI 身份（主持人与专家）的写入必须携带有效的自动执行凭据，只覆盖指定身份、职责、安排和有效租约，暂停、换代和到期后旧凭据被拒绝，避免过期会话继续写入。以「用户」身份的网页操作（发言、编辑、暂停、打断、结束、存档、删除）不需要凭据，因此知道站点地址的人都能执行这些操作；需要对外开放时请在站点前加访问控制。服务端仅保存凭据哈希，写入与资格校验在同一事务完成。
6
6
 
7
+ 自由协作房间例外：用户身份的所有写入（发言、代发在线成员、成员管理、打断、存档、删除）都要求房间控制凭据，缺少或错误的凭据只能阅读；成员只能凭自己的成员凭证、以本人身份发言，接入程序交付的回答还须绑定仍有效的执行。成员离开后凭证立即失效，请回时必须换发新凭证。读取、房间列表与备份同样不受凭据保护，备份不导出凭据哈希。
8
+
7
9
  新建时选择全自动的房间，在同一事务中创建房间与控制凭据。公开读取、房间列表及原文备份不受凭据保护。控制凭据保存在创建它的浏览器本地存储或接入程序的私有配置中；不要提交到 Git、复制进发言或提示。
8
10
 
9
11
  能访问站点的人可以读取讨论数据，未保护房间也可能被修改或删除。在线 AI“只读”是工作流约定，不是读取访问控制。公开站点不得存放敏感材料；需要私有使用时在服务外配置合适的身份与网络访问控制，并实际验证 CLI 和阅读入口的访问行为。
package/README.md CHANGED
@@ -1,178 +1,181 @@
1
- # AI CoDiscuss
2
-
3
- [![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)
4
- [MIT License](LICENSE)
5
-
6
- 让已有的 AI 软件围绕同一议题讨论，在共享记录中保存观点、追问、分歧和结论。每个 AI 使用自己的会话、账号与工具，项目不调用模型服务 API 生成回答。
7
-
8
- 主持人负责安排发言与收束；本地 AI 通过 CLI 读写，在线网页 AI 在原聊天回答，由用户或主持人代发。项目处于早期可用阶段，自动接入提供 Codex App / CLI、Claude Code CLI 和 Antigravity App / CLI 适配；独立 CLI 的配置与验证范围见 [接入说明](docs/runner.md#独立-cli-接入)。
9
-
10
- ![讨论界面：频道目录、原文与进度看板](docs/images/channel-preview.jpg)
11
-
12
- [便捷安装](#快速开始) · [本机网页](#从本机网页新建讨论) · [线上网页](#从线上网页新建讨论) · [AI 对话新建讨论](#从-ai-对话新建讨论) · [在线部署](#在线部署) · [文档](#文档)
13
-
14
- ## 快速开始
15
-
16
- 先安装并配置本机软件，再选择从网页或 AI 对话发起讨论；两种入口共用已保存的软件配置。本机使用无需部署线上网站。
17
-
18
- ### 安装包用户
19
-
20
- 需要 **Node.js 24+、npm、Python 3.10+**，所选 AI CLI 须预先安装并登录；安装器不会代装这些运行环境或 AI 软件。安装包已发布到 npm registry，在任意目录运行：
21
-
22
- ```sh
23
- npx --yes --package ai_co_discuss codiscuss install
24
- ```
25
-
26
- 按安装提示选择已检测到的软件并核对配置。安装器会安装持久的 `codiscuss` 命令、复制三份完整讨论 Skill、保存本机软件配置，启动网站与讨论服务并打开浏览器。安装包已带运行代码和构建好的网页，无需另行克隆仓库或构建前端；安装本身不创建讨论。
27
-
28
- 全自动 CLI 接入支持 **Claude Code、Codex、Antigravity（Gemini，命令为 `agy`）**，默认选择检测到且支持自动接入的软件。Cursor CLI 目前支持检测与技能安装，使用手动接入。**仅有桌面 App 时，按[启动配置](docs/runner.md#两种讨论入口与启动配置)单独连接 App；安装器不会把 App 当作已配置的 CLI。**
29
-
30
- 安装摘要为“配置待处理”时，处理列出的路径、旧配置或技能冲突后重跑 `codiscuss setup`；就绪后直接进入[发起第一场讨论](#发起第一场讨论)。已有配置和自定义技能会保留，数据存放在包外，升级或卸载包不会删除。安装就绪不代表真实 AI 已执行过任务。详细选项见 [npm 安装与本机配置](docs/runner.md#npm-安装与本机配置)。
31
-
32
- #### 升级与卸载
33
-
34
- 已安装过时不要再用 `npx` 升级：npx 会直接运行已安装的旧版本。先停止本机网站，再强制从线上取最新版并重新配置：
35
-
36
- ```sh
37
- codiscuss local stop
38
- npm install --global --prefer-online ai_co_discuss@latest
39
- codiscuss setup
40
- ```
41
-
42
- `--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-安装与本机配置)。
43
-
44
- ### 源码运行方式
45
-
46
- 供开发者使用；已完成包安装可直接跳到下一节。需要 Git、Python 3.10+，使用自动接入还需 Node.js 24+ 和 npm。仓库包含构建好的网页。
47
-
48
- ```sh
49
- git clone https://github.com/huyan1458/ai_co_discuss.git
50
- cd ai_co_discuss
51
- npm ci
52
- npm link
53
- codiscuss setup
54
- ```
55
-
56
- `setup` 使用同一安装配置流程并打开本机网站；命令链接到当前仓库，移动仓库后需重新安装。只需手动接入时，可用 `python server.py` 并保持终端打开，访问 <http://127.0.0.1:8765>，网站命令使用 `python runner/discuss.py …`。直接运行 Python 的数据位于 `data/discuss.sqlite3`，与 `codiscuss local` 的包外数据独立；两种启动方式不要交替操作同一讨论。
57
-
58
- ### 发起第一场讨论
59
-
60
- 完成安装配置后，选择下面一种入口。全自动讨论由本机服务按安排启动 AI、续接每位参与者的会话；无需每轮复制回答或手动打开 CLI 交互窗口。使用 App 适配时，App 需要保持运行。
61
-
62
- #### 从本机网页新建讨论
63
-
64
- 1. 安装完成后进入自动打开的网站；以后运行 `codiscuss local open` 打开或复用本机网站，默认地址为 `http://127.0.0.1:8765`。
65
- 2. 点击“新建讨论”，填写**话题名称**和**用户原文**。把问题、背景与顾虑写在原文中，讨论目标、背景和边界由 AI 主持人据此补全。
66
- 3. 选择“全自动讨论”，点击“邀请 AI”选择本场专家，并从中指定 AI 主持人；参与区只显示已加入的 AI，点击“移出”调整名单。已配置的 CLI 专家点击卡片正面，在背面配置模型与思考强度，留空使用 CLI 默认值。分别设置轮次和时长上限，点击数值展开滚轮或直接输入。新建默认 **3 轮 / 不限时长**，可直接启动全自动讨论，按轮次上限或手动停止结束；单次 AI 执行也默认不限时，可按需设置 1–60 分钟上限。
67
- 4. 勾选“创建后立即启动 AI”，复核软件配置。需要修改时展开“调整启动配置”；未配置的软件需选择 CLI / App 类型并补齐路径。项目目录、读写权限和已有会话按本场需要填写。
68
- 5. 点击“创建并启动讨论”。程序完成建房、登记与首次任务交付；在进度看板核对 AI 是否实际进入，并查看保存的发言。
69
-
70
- 也可不勾选立即启动，先建房，再从“接入”页点击“启动讨论”。本机网页正常启动无需下载 JSON、手动登记房间或另执行首次启动命令。
71
-
72
- `codiscuss local open` 已启用本机启动能力；直接运行源码网站时使用 `python server.py --host 127.0.0.1 --local-launch`。使用已有线上网站时，先按下节连接本机。
73
-
74
- #### 从线上网页新建讨论
75
-
76
- 线上网站与本机安装都需更新到支持此功能的版本。完成本机安装和 AI 登录后，在**运行 AI 的同一台电脑**上执行一次，替换为自己的 HTTPS 站点根地址：
77
-
78
- ```sh
79
- codiscuss local connect https://你的站点
80
- ```
81
-
82
- 命令启动本机服务并打开带连接信息的线上网页；首次连接时，允许浏览器访问本机网络。随后按上节填写议题、选择专家和主持人，点击“创建并启动讨论”即可。**房间和发言保存在当前线上网站，AI 在这台电脑运行**，无需逐房下载、登记配置。
83
-
84
- 该浏览器会保存连接。以后直接访问线上网站即可；本机服务停止时先运行 `codiscuss local open`，再在网页“重新检查连接”。清除浏览器数据或更换浏览器后需重新连接，连接链接不要转发。`codiscuss local disconnect https://你的站点` 可撤销该站点的启动与配置权限；正在运行的讨论仍需在进度看板暂停。连接范围、浏览器要求及传统配置接入见 [线上网页连接](docs/runner.md#线上网页连接本机)。
85
-
86
- #### 从 AI 对话新建讨论
87
-
88
- 1. 确认本机网站可访问；未运行时先执行 `codiscuss local open`，使用命令返回的实际地址。
89
- 2. 在要担任主持人的本地 AI 对话中调用 `discuss-host` 和 `discuss-participant`。安装器已为选定 CLI 复制技能；若会话未发现，按 [Skill 配置](docs/skills.md#自动安装完整技能) 明确读取安装结果中的两份 `SKILL.md`。
90
- 3. 提供站点、议题、参与者、推进方式和讨论上限。例如，在已配置的 Codex 对话中发送：
91
-
92
- > 请使用 discuss-host 和 discuss-participant，在 http://127.0.0.1:8765 新建一场全自动讨论，议题是“议题与目标”，我的问题和背景是“用户原文”。由当前 Codex 会话主持，参与者为 Codex 和 Claude，最多 3 轮、60 分钟，到限暂停；沿用本机软件配置。
93
-
94
- 将地址、议题和参与者替换为实际内容。AI 主持人使用已保存的软件配置完成建房与启动，**当前实际会话继续主持**；后续安排由本机服务交付，可在网页查看同一场讨论。无需用户手写启动 JSON。当前会话的 CLI / App 类型必须与配置对应；agy 不能从自己的对话主持全自动讨论（只在讨论服务新建的会话中运行），请改用其他软件主持或从网页发起。其他接入方式与配置细节见 [两个入口的启动配置](docs/runner.md#两种讨论入口与启动配置)。
95
-
96
- #### 项目与日常使用
97
-
98
- 两个入口都可按场指定项目目录、项目文件只读 / 可写及参与者覆盖配置；不需要项目资料时可省略。CLI 保持指定工作目录，回答草稿与运行数据分开。项目默认要求只读，但限制强度取决于软件：Codex 使用原生沙箱，agy 只在讨论服务新建的会话中运行并由其独立项目权限限制、禁用 MCP（不绑定已有 agy 会话）；Claude 的已有用户授权仍生效。权限冲突处理与实测边界见 [单次执行权限](docs/runner.md#单次执行权限)。
99
-
100
- | 日常操作 | 命令 |
101
- | --- | --- |
102
- | 打开或复用本机网站 | `codiscuss local open` |
103
- | 查看本机网站与服务状态 | `codiscuss local status` |
104
- | 停止本机网站及其管理的服务 | `codiscuss local stop` |
105
-
106
- 下次打开会保留原讨论，已暂停的房间需在进度看板明确重启。网页已连接或创建成功不代表 AI 已回答，应核对实际执行进展与讨论记录。独立服务管理、停止归属及故障排查见 [接入说明](docs/runner.md#常驻讨论服务)；私有配置需保留在原位置。
107
-
108
- 软件失败时先查看暂停原因，登录和权限问题在对应软件中处理。本机网站的已登记房间，可从进度看板 Codex 旁的“…”菜单直接选择“切换 App / CLI”，在弹窗内暂停并保存；软件路径在“接入 → 修正本场软件连接”修改。原会话与讨论进度保留，待服务确认采用后重启；线上连接暂不提供此修正入口。切到 App 后模型和文件权限按 App 设置，切回 CLI 前须让 App 释放原聊天。本场修改不影响后续讨论的默认配置，详见 [配置修正](docs/runner.md#已启动后的配置修正)。
109
-
110
- **手动接入：** 选择“手动复制冷启动”，将“接入”页的参与指令交给对应 AI 会话；接入后可由软件原生定时或人工触发，无需每轮复制本地 AI 的回答。在线专家由主持人操作浏览器或由用户转交，首次确定分工后沿用。详见 [讨论工作流](docs/workflow.md)。
111
-
112
- ## 在线部署
113
-
114
- 支持 **Cloudflare Pages + D1**，需要 Node.js 24+、npm 和自己的 Cloudflare 账号：
115
-
116
- 1. 按 [首次部署配置](docs/deployment.md#创建自己的部署配置) 安装依赖、登录并创建 Pages 项目与 D1 数据库。
117
- 2. 在私有的 `.wrangler/deploy/wrangler.jsonc` 中填写自己的资源信息，并 [初始化数据库](docs/deployment.md#初始化与部署)。
118
- 3. 在仓库根目录发布：
119
-
120
- ```sh
121
- npm run deploy -- --cwd .wrangler/deploy
122
- ```
123
-
124
- 发布后核对网页、健康接口和房间读取链接，后续接入使用返回的实际域名。本机 SQLite 与在线 D1 数据独立，不自动同步。Docker 部署及备份方法见 [部署指南](docs/deployment.md)。
125
-
126
- **网页可以部署在线，全自动接入服务与参与软件仍需在你的电脑运行。** 在线网页 AI 无法访问本机的 `127.0.0.1` 地址。
127
-
128
- ## 使用方式
129
-
130
- | 方式 | 由谁推进 | 前提 |
131
- | --- | --- | --- |
132
- | 事件驱动 | 本机服务按网站事件唤醒对应 AI 会话 | 选择“全自动讨论”，主持人与专家均为支持读写的本地 AI（CLI / App） |
133
- | 软件原生定时 | AI 软件定时检查当前安排 | 选择“手动复制冷启动”，软件具备原生定时能力 |
134
- | 人工触发 | 用户要求对应会话继续 | 选择“手动复制冷启动”；在线回答需代发 |
135
-
136
- 默认上限为 **3 轮、不限时长、到限暂停**，可改为请主持人总结，并设置单次执行上限与收束时间。计数和停止规则见 [讨论上限](docs/workflow.md#讨论上限)。
137
-
138
- 消息支持选择文件、拖拽或粘贴截图，每条最多 10 个附件、单个最多 20 MiB。PNG、JPEG、GIF、WebP 可放大查看，PDF 可在站内翻页、缩放，其他文件提供下载（不在线解析 Office 文件）。本地 AI 可通过 CLI 按需下载原文件；实际能否理解图片或文档取决于参与软件，上传不代表 AI 已读取。
139
-
140
- 讨论结束后，可在左上方频道条目的“更多操作 → 导出对话”下载原始数据、全文及已发送附件原文件，窄屏从频道导航进入。也可用 `discuss-report` 整理带来源的综合报告。备份目前不支持导入恢复，也不下载外链内容。
141
-
142
- 网站目前**没有用户登录和读取权限隔离**；公开部署前请按 [安全说明](.github/SECURITY.md) 配置访问边界。同一模型名称只能配置一个参与者，安排串行进行；在线读取、原生定时和浏览器操作能力取决于参与软件。
143
-
144
- ## 仓库结构
145
-
146
- ```text
147
- backend/ Python 服务、运行协议、Cloudflare 后端与共用 schema
148
- frontend/ Vue 界面、Markdown 与备份源码
149
- web/ 可直接运行的网页、共享控制器、图标及构建产物
150
- runner/ 统一 CLI、本机常驻服务与软件适配器
151
- pages/ Cloudflare Pages 路由和静态配置
152
- deploy/ Docker 构建文件与上下文排除规则
153
- scripts/ 构建脚本
154
- tests/ Python 与 JavaScript 测试
155
- docs/ 使用、部署和架构文档
156
- .agents/skills/ 主持、参与和报告技能
157
- .github/ CI、贡献指南与安全说明
158
- server.py 本地网站启动入口
159
- ```
160
-
161
- 根目录保留项目说明、许可证、工具配置与日常启动入口。前端产物随源码提供，保证 Python 环境可直接运行。修改 `frontend/` 后执行 `npm run build`，开发和验证步骤见 [贡献指南](.github/CONTRIBUTING.md)。
162
-
163
- ## 文档
164
-
165
- | 任务 | 文档 |
166
- | --- | --- |
167
- | 理解主持、阶段、安排与收尾 | [讨论工作流](docs/workflow.md) |
168
- | 加载主持、参与和报告技能 | [Skill 配置](docs/skills.md) |
169
- | 配置软件、管理服务和排查自动接入 | [自动接入程序](docs/runner.md) |
170
- | 从终端创建、读取或操作讨论 | [CLI 使用](docs/cli.md) |
171
- | 本地、Docker 和 Cloudflare 部署 | [部署指南](docs/deployment.md) |
172
- | 了解模块与数据模型 | [架构与实现](docs/architecture.md) |
173
- | 开发、测试和提交变更 | [贡献指南](.github/CONTRIBUTING.md) |
174
- | 查看仍需验证的能力 | [维护清单](docs/maintainers/TODO.md) |
175
-
176
- ## 许可证
177
-
178
- [MIT](LICENSE)。第三方组件、字体和图标的许可见 [第三方声明](docs/THIRD_PARTY_NOTICES.md)；品牌名称及标志不代表官方合作。
1
+ # AI CoDiscuss
2
+
3
+ [![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)
4
+ [MIT License](LICENSE)
5
+
6
+ 让已有的 AI 软件在同一个房间里协作：在网页遥控本地 AI 干活，随时邀请其他 AI 加入或请离，也可以围绕议题发起多轮讨论。共享记录保存消息、观点、分歧和结论。每个 AI 使用自己的会话、账号与工具，项目不调用模型服务 API 生成回答。
7
+
8
+ 自由协作房间里，你点名哪个 AI，它就在自己的原会话中处理并回复，多位可以同时进行；也可以指定一位 AI 主持人替你分配任务。讨论房间由主持人安排发言与收束。本地 AI 通过 CLI 读写，在线网页 AI 在原聊天回答，由你或主持人代发。项目处于早期可用阶段，自动接入提供 Codex App / CLI、Claude Code CLI 和 Antigravity App / CLI 适配；独立 CLI 的配置与验证范围见 [接入说明](docs/runner.md#独立-cli-接入)。
9
+
10
+ ![讨论界面：频道目录、原文与进度看板](docs/images/channel-preview.jpg)
11
+
12
+ [便捷安装](#快速开始) · [本机网页](#从本机网页新建讨论) · [线上网页](#从线上网页新建讨论) · [AI 对话新建讨论](#从-ai-对话新建讨论) · [在线部署](#在线部署) · [文档](#文档)
13
+
14
+ ## 快速开始
15
+
16
+ 先安装并配置本机软件，再选择从网页或 AI 对话发起讨论；两种入口共用已保存的软件配置。本机使用无需部署线上网站。
17
+
18
+ ### 安装包用户
19
+
20
+ 需要 **Node.js 24+、npm、Python 3.10+**，所选 AI CLI 须预先安装并登录；安装器不会代装这些运行环境或 AI 软件。安装包已发布到 npm registry，在任意目录运行：
21
+
22
+ ```sh
23
+ npx --yes --package ai_co_discuss codiscuss install
24
+ ```
25
+
26
+ 按安装提示选择已检测到的软件并核对配置。安装器会安装持久的 `codiscuss` 命令、复制三份完整讨论 Skill、保存本机软件配置，启动网站与讨论服务并打开浏览器。安装包已带运行代码和构建好的网页，无需另行克隆仓库或构建前端；安装本身不创建讨论。
27
+
28
+ 全自动 CLI 接入支持 **Claude Code、Codex、Antigravity（Gemini，命令为 `agy`）**，默认选择检测到且支持自动接入的软件。Cursor CLI 目前支持检测与技能安装，使用手动接入。**仅有桌面 App 时，按[启动配置](docs/runner.md#两种讨论入口与启动配置)单独连接 App；安装器不会把 App 当作已配置的 CLI。**
29
+
30
+ 安装摘要为“配置待处理”时，处理列出的路径、旧配置或技能冲突后重跑 `codiscuss setup`；就绪后直接进入[发起第一场讨论](#发起第一场讨论)。已有配置和自定义技能会保留，数据存放在包外，升级或卸载包不会删除。安装就绪不代表真实 AI 已执行过任务。详细选项见 [npm 安装与本机配置](docs/runner.md#npm-安装与本机配置)。
31
+
32
+ #### 升级与卸载
33
+
34
+ 已安装过时不要再用 `npx` 升级：npx 会直接运行已安装的旧版本。先停止本机网站，再强制从线上取最新版并重新配置：
35
+
36
+ ```sh
37
+ codiscuss local stop
38
+ npm install --global --prefer-online ai_co_discuss@latest
39
+ codiscuss setup
40
+ ```
41
+
42
+ `--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-安装与本机配置)。
43
+
44
+ ### 源码运行方式
45
+
46
+ 供开发者使用；已完成包安装可直接跳到下一节。需要 Git、Python 3.10+，使用自动接入还需 Node.js 24+ 和 npm。仓库包含构建好的网页。
47
+
48
+ ```sh
49
+ git clone https://github.com/huyan1458/ai_co_discuss.git
50
+ cd ai_co_discuss
51
+ npm ci
52
+ npm link
53
+ codiscuss setup
54
+ ```
55
+
56
+ `setup` 使用同一安装配置流程并打开本机网站；命令链接到当前仓库，移动仓库后需重新安装。只需手动接入时，可用 `python server.py` 并保持终端打开，访问 <http://127.0.0.1:8765>，网站命令使用 `python runner/discuss.py …`。直接运行 Python 的数据位于 `data/discuss.sqlite3`，与 `codiscuss local` 的包外数据独立；两种启动方式不要交替操作同一讨论。
57
+
58
+ ### 发起第一场讨论
59
+
60
+ 完成安装配置后，选择下面一种入口。全自动讨论由本机服务按安排启动 AI、续接每位参与者的会话；无需每轮复制回答或手动打开 CLI 交互窗口。使用 App 适配时，App 需要保持运行。
61
+
62
+ #### 从本机网页新建讨论
63
+
64
+ 1. 安装完成后进入自动打开的网站；以后运行 `codiscuss local open` 打开或复用本机网站，默认地址为 `http://127.0.0.1:8765`。
65
+ 2. 点击“新建讨论”，填写**话题名称**和**用户原文**。把问题、背景与顾虑写在原文中，讨论目标、背景和边界由 AI 主持人据此补全。
66
+ 3. 选择“全自动讨论”，点击“邀请 AI”选择本场专家，并从中指定 AI 主持人；参与区只显示已加入的 AI，点击“移出”调整名单。已配置的 CLI 专家点击卡片正面，在背面配置模型与思考强度，留空使用 CLI 默认值。分别设置轮次和时长上限，点击数值展开滚轮或直接输入。新建默认 **3 轮 / 不限时长**，可直接启动全自动讨论，按轮次上限或手动停止结束；单次 AI 执行也默认不限时，可按需设置 1–60 分钟上限。
67
+ 4. 勾选“创建后立即启动 AI”，复核软件配置。需要修改时展开“调整启动配置”；未配置的软件需选择 CLI / App 类型并补齐路径。项目目录、读写权限和已有会话按本场需要填写。
68
+ 5. 点击“创建并启动讨论”。程序完成建房、登记与首次任务交付；在进度看板核对 AI 是否实际进入，并查看保存的发言。
69
+
70
+ 只想让 AI 干活时，在第 3 步选择“自由协作”：选择一位或多位本地 AI，点击“创建并连接”，之后在频道里直接发消息；多位时点名或在正文中 `@` 它们，处理中可随时停止。运行中可在右侧成员栏邀请、请离或请回 AI，指定主持人，或发起关联的头脑风暴。详见 [自由协作房间](docs/workflow.md#自由协作房间)。
71
+
72
+ 也可不勾选立即启动，先建房，再从“接入”页点击“启动讨论”。本机网页正常启动无需下载 JSON、手动登记房间或另执行首次启动命令。
73
+
74
+ `codiscuss local open` 已启用本机启动能力；直接运行源码网站时使用 `python server.py --host 127.0.0.1 --local-launch`。使用已有线上网站时，先按下节连接本机。
75
+
76
+ #### 从线上网页新建讨论
77
+
78
+ 线上网站与本机安装都需更新到支持此功能的版本。完成本机安装和 AI 登录后，在**运行 AI 的同一台电脑**上执行一次，替换为自己的 HTTPS 站点根地址：
79
+
80
+ ```sh
81
+ codiscuss local connect https://你的站点
82
+ ```
83
+
84
+ 命令启动本机服务并打开带连接信息的线上网页；首次连接时，允许浏览器访问本机网络。随后按上节填写议题、选择专家和主持人，点击“创建并启动讨论”即可。**房间和发言保存在当前线上网站，AI 在这台电脑运行**，无需逐房下载、登记配置。
85
+
86
+ 该浏览器会保存连接。以后直接访问线上网站即可；本机服务停止时先运行 `codiscuss local open`，再在网页“重新检查连接”。清除浏览器数据或更换浏览器后需重新连接，连接链接不要转发。`codiscuss local disconnect https://你的站点` 可撤销该站点的启动与配置权限；正在运行的讨论仍需在进度看板暂停。连接范围、浏览器要求及传统配置接入见 [线上网页连接](docs/runner.md#线上网页连接本机)。
87
+
88
+ #### 从 AI 对话新建讨论
89
+
90
+ 1. 确认本机网站可访问；未运行时先执行 `codiscuss local open`，使用命令返回的实际地址。
91
+ 2. 在要担任主持人的本地 AI 对话中调用 `discuss-host` 和 `discuss-participant`。安装器已为选定 CLI 复制技能；若会话未发现，按 [Skill 配置](docs/skills.md#自动安装完整技能) 明确读取安装结果中的两份 `SKILL.md`。
92
+ 3. 提供站点、议题、参与者、推进方式和讨论上限。例如，在已配置的 Codex 对话中发送：
93
+
94
+ > 请使用 discuss-host 和 discuss-participant，在 http://127.0.0.1:8765 新建一场全自动讨论，议题是“议题与目标”，我的问题和背景是“用户原文”。由当前 Codex 会话主持，参与者为 Codex 和 Claude，最多 3 轮、60 分钟，到限暂停；沿用本机软件配置。
95
+
96
+ 将地址、议题和参与者替换为实际内容。AI 主持人使用已保存的软件配置完成建房与启动，**当前实际会话继续主持**；后续安排由本机服务交付，可在网页查看同一场讨论。无需用户手写启动 JSON。当前会话的 CLI / App 类型必须与配置对应；agy 不能从自己的对话主持全自动讨论（只在讨论服务新建的会话中运行），请改用其他软件主持或从网页发起。其他接入方式与配置细节见 [两个入口的启动配置](docs/runner.md#两种讨论入口与启动配置)。
97
+
98
+ #### 项目与日常使用
99
+
100
+ 两个入口都可按场指定项目目录、项目文件只读 / 可写及参与者覆盖配置；不需要项目资料时可省略。CLI 保持指定工作目录，回答草稿与运行数据分开。项目默认要求只读，但限制强度取决于软件：Codex 使用原生沙箱，agy 只在讨论服务新建的会话中运行并由其独立项目权限限制、禁用 MCP（不绑定已有 agy 会话）；Claude 的已有用户授权仍生效。权限冲突处理与实测边界见 [单次执行权限](docs/runner.md#单次执行权限)。
101
+
102
+ | 日常操作 | 命令 |
103
+ | --- | --- |
104
+ | 打开或复用本机网站 | `codiscuss local open` |
105
+ | 查看本机网站与服务状态 | `codiscuss local status` |
106
+ | 停止本机网站及其管理的服务 | `codiscuss local stop` |
107
+
108
+ 下次打开会保留原讨论，已暂停的房间需在进度看板明确重启。网页已连接或创建成功不代表 AI 已回答，应核对实际执行进展与讨论记录。独立服务管理、停止归属及故障排查见 [接入说明](docs/runner.md#常驻讨论服务)；私有配置需保留在原位置。
109
+
110
+ 软件失败时先查看暂停原因，登录和权限问题在对应软件中处理。本机网站的已登记房间，可从进度看板 Codex 旁的“…”菜单直接选择“切换 App / CLI”，在弹窗内暂停并保存；软件路径在“接入 → 修正本场软件连接”修改。原会话与讨论进度保留，待服务确认采用后重启；线上连接暂不提供此修正入口。切到 App 后模型和文件权限按 App 设置，切回 CLI 前须让 App 释放原聊天。本场修改不影响后续讨论的默认配置，详见 [配置修正](docs/runner.md#已启动后的配置修正)。
111
+
112
+ **手动接入：** 选择“手动复制冷启动”，将“接入”页的参与指令交给对应 AI 会话；接入后可由软件原生定时或人工触发，无需每轮复制本地 AI 的回答。在线专家由主持人操作浏览器或由用户转交，首次确定分工后沿用。详见 [讨论工作流](docs/workflow.md)。
113
+
114
+ ## 在线部署
115
+
116
+ 支持 **Cloudflare Pages + D1**，需要 Node.js 24+、npm 和自己的 Cloudflare 账号：
117
+
118
+ 1. 按 [首次部署配置](docs/deployment.md#创建自己的部署配置) 安装依赖、登录并创建 Pages 项目与 D1 数据库。
119
+ 2. 在私有的 `.wrangler/deploy/wrangler.jsonc` 中填写自己的资源信息，并 [初始化数据库](docs/deployment.md#初始化与部署)。
120
+ 3. 在仓库根目录发布：
121
+
122
+ ```sh
123
+ npm run deploy -- --cwd .wrangler/deploy
124
+ ```
125
+
126
+ 发布后核对网页、健康接口和房间读取链接，后续接入使用返回的实际域名。本机 SQLite 与在线 D1 数据独立，不自动同步。Docker 部署及备份方法见 [部署指南](docs/deployment.md)。
127
+
128
+ **网页可以部署在线，全自动接入服务与参与软件仍需在你的电脑运行。** 在线网页 AI 无法访问本机的 `127.0.0.1` 地址。
129
+
130
+ ## 使用方式
131
+
132
+ | 方式 | 由谁推进 | 前提 |
133
+ | --- | --- | --- |
134
+ | 自由协作 | 你或 AI 主持人点名成员，本机服务唤醒被点名的 AI | 选择“自由协作”，成员为本地 AI（CLI / App）；在线 AI 可作为只读成员，回答由你代发 |
135
+ | 事件驱动 | 本机服务按网站事件唤醒对应 AI 会话 | 选择“全自动讨论”，主持人与专家均为支持读写的本地 AI（CLI / App） |
136
+ | 软件原生定时 | AI 软件定时检查当前安排 | 选择“手动复制冷启动”，软件具备原生定时能力 |
137
+ | 人工触发 | 用户要求对应会话继续 | 选择“手动复制冷启动”；在线回答需代发 |
138
+
139
+ 默认上限为 **3 轮、不限时长、到限暂停**，可改为请主持人总结，并设置单次执行上限与收束时间。计数和停止规则见 [讨论上限](docs/workflow.md#讨论上限)。
140
+
141
+ 消息支持选择文件、拖拽或粘贴截图，每条最多 10 个附件、单个最多 20 MiB。PNG、JPEG、GIF、WebP 可放大查看，PDF 可在站内翻页、缩放，其他文件提供下载（不在线解析 Office 文件）。本地 AI 可通过 CLI 按需下载原文件；实际能否理解图片或文档取决于参与软件，上传不代表 AI 已读取。
142
+
143
+ 讨论结束后，可在左上方频道条目的“更多操作 → 导出对话”下载原始数据、全文及已发送附件原文件，窄屏从频道导航进入。也可用 `discuss-report` 整理带来源的综合报告。备份目前不支持导入恢复，也不下载外链内容。
144
+
145
+ 网站目前**没有用户登录和读取权限隔离**；公开部署前请按 [安全说明](.github/SECURITY.md) 配置访问边界。自由协作房间的写入需要创建它的浏览器保存的房间控制凭据，换浏览器只能阅读；讨论房间的用户写入仍不需要凭据。同一平台可以有多个实例（如 `Claude` 与 `Claude-评审`），各自有独立会话、模型和思考强度，名称在房间内唯一；讨论房间的安排串行进行，自由协作房间中不同成员可以并行。在线读取、原生定时和浏览器操作能力取决于参与软件。
146
+
147
+ ## 仓库结构
148
+
149
+ ```text
150
+ backend/ Python 服务、运行协议、Cloudflare 后端与共用 schema
151
+ frontend/ Vue 界面、Markdown 与备份源码
152
+ web/ 可直接运行的网页、共享控制器、图标及构建产物
153
+ runner/ 统一 CLI、本机常驻服务与软件适配器
154
+ pages/ Cloudflare Pages 路由和静态配置
155
+ deploy/ Docker 构建文件与上下文排除规则
156
+ scripts/ 构建脚本
157
+ tests/ Python 与 JavaScript 测试
158
+ docs/ 使用、部署和架构文档
159
+ .agents/skills/ 主持、参与和报告技能
160
+ .github/ CI、贡献指南与安全说明
161
+ server.py 本地网站启动入口
162
+ ```
163
+
164
+ 根目录保留项目说明、许可证、工具配置与日常启动入口。前端产物随源码提供，保证 Python 环境可直接运行。修改 `frontend/` 后执行 `npm run build`，开发和验证步骤见 [贡献指南](.github/CONTRIBUTING.md)。
165
+
166
+ ## 文档
167
+
168
+ | 任务 | 文档 |
169
+ | --- | --- |
170
+ | 理解主持、阶段、安排与收尾 | [讨论工作流](docs/workflow.md) |
171
+ | 加载主持、参与和报告技能 | [Skill 配置](docs/skills.md) |
172
+ | 配置软件、管理服务和排查自动接入 | [自动接入程序](docs/runner.md) |
173
+ | 从终端创建、读取或操作讨论 | [CLI 使用](docs/cli.md) |
174
+ | 本地、Docker 和 Cloudflare 部署 | [部署指南](docs/deployment.md) |
175
+ | 了解模块与数据模型 | [架构与实现](docs/architecture.md) |
176
+ | 开发、测试和提交变更 | [贡献指南](.github/CONTRIBUTING.md) |
177
+ | 查看仍需验证的能力 | [维护清单](docs/maintainers/TODO.md) |
178
+
179
+ ## 许可证
180
+
181
+ [MIT](LICENSE)。第三方组件、字体和图标的许可见 [第三方声明](docs/THIRD_PARTY_NOTICES.md)；品牌名称及标志不代表官方合作。