ai_co_discuss 0.2.36 → 0.2.38

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

@@ -38,7 +38,7 @@ description: "AI CoDiscuss 的通用参与技能，所有参与者（包括主
 
 自由房间的普通成员可在回答中用 `--to 成员名` 或正文 `@成员` 提出回应建议，不能点名自己；这不会派发任务。网页显示“建议请 X 回应”，只有房主点击“转为请求”后才建立关联原回答的新用户任务链。任务的 `request_messages` 可能指向已读游标之前的原回答，须用 `message view ROOM ID` 补读；用户确认消息不代替原建议。不要把建议显示或复制入口当作已经通知；代码与引用里的正文 @ 不生成建议。
 
-**手动接入：** 用户已选手动时沿用人工触发或原生定时；需要持续参与才读 [手动持续参与](references/manual.md)。没有任务文件本身不代表手动授权：若房间正在自动运行，等待本次交付或核对缺项，不从旧文件接管。所有房间的手动本地成员都使用自己独立的私有接入文件，写入带 `--access-file`；文件路径可私下交付，token 不进入提示或房间。房主控制文件不能代替成员文件署名，在线成员没有自行写入资格。
+**手动接入：** 用户已选手动时沿用人工触发或原生定时；需要持续参与才读 [手动持续参与](references/manual.md)。没有任务文件本身不代表手动授权：若房间正在自动运行，等待本次交付或核对缺项，不从旧文件接管。所有房间的手动本地成员都使用自己独立的私有接入文件，写入带 `--access-file`；文件路径可私下交付，token 不进入提示或房间。房主控制文件不能代替成员文件署名，在线成员没有自行写入资格。手动本地成员首次读取房间后立即执行一次 `member register ROOM --as 本人 --access-file FILE` 注册；未注册前网站显示“待注册”，不算到场，也不会被本机服务接管。会话 ID 由 CLI 从宿主会话自动附带，不自行填写；凭证重新签发后须重新注册。
 
 ## 先读什么
 

package/backend/free_room.py

@@ -229,6 +229,7 @@ def free_view(connection, room_id):
     members = []
     for row in connection.execute("SELECT * FROM room_members WHERE room_id=? AND status<>'removed' ORDER BY id", (room_id,)):
         member = {key: row[key] for key in MEMBER_FIELDS}
+        member["registered_at"] = registered_at(connection, row)
         latest = connection.execute("SELECT * FROM member_executions WHERE member_id=? ORDER BY id DESC LIMIT 1",
                                     (row["id"],)).fetchone()
         member["execution"] = public_execution(latest)
@@ -258,6 +259,30 @@ def require_member(connection, room_id, token, name=None):
     return row
 
 
+def registered_at(connection, member):
+    """Return when the member registered with its current credential, or '' while it has not."""
+    row = connection.execute("SELECT registered_at FROM member_registrations WHERE member_id=? AND token_hash=?",
+                             (member["id"], member["token_hash"])).fetchone()
+    return row[0] if row else ""
+
+
+def register_member(connection, room_id, token, now):
+    """A manual member announces itself with its own credential; repeating it keeps the first time.
+
+    The session ID is not part of the request: the CLI attaches it to every call and the room records it separately.
+    """
+    begin_write(connection)
+    member = require_member(connection, room_id, token)
+    if member["access"] != "manual":
+        raise ValueError("只有手动接入的成员需要注册")
+    stamp = registered_at(connection, member) or now
+    connection.execute("""INSERT INTO member_registrations (member_id,room_id,token_hash,registered_at) VALUES (?,?,?,?)
+        ON CONFLICT(member_id) DO UPDATE SET token_hash=excluded.token_hash,registered_at=excluded.registered_at""",
+                       (member["id"], room_id, member["token_hash"], stamp))
+    reported = connection.execute("SELECT client FROM member_sessions WHERE member_id=?", (member["id"],)).fetchone()
+    return {"member": member["name"], "registered_at": stamp, "session_client": reported[0] if reported else ""}
+
+
 def authorize_free_write(connection, room_id, token, operation, payload):
     """Decide who is writing: the owner, or one member posting its own answer.
 
@@ -784,8 +809,45 @@ def save_discussion_experts(connection, room_id, experts):
     connection.execute("UPDATE topic_settings SET experts=? WHERE room_id=?", (json.dumps(experts, ensure_ascii=False), room_id))
 
 
+def current_round_speakers(connection, room_id, experts):
+    """Experts who have given an opinion in the latest unfinished round (empty when it just completed)."""
+    spoken = set()
+    rows = connection.execute("""SELECT messages.author FROM messages
+        JOIN message_details AS details ON details.message_id=messages.id AND details.kind='opinion'
+        WHERE messages.room_id=? ORDER BY messages.id""", (room_id,))
+    for row in rows:
+        if row["author"] not in experts:
+            continue
+        spoken.add(row["author"])
+        if len(spoken) == len(experts):
+            spoken = set()
+    return spoken
+
+
+def place_invited_expert(connection, room_id, name):
+    """Move the just-queued newcomer to where the current round completes: after the last queued expert who
+    has not spoken this round, before the first one who would speak again. Rows keep their ids; only who and what shift."""
+    rows = connection.execute("SELECT id,expert,question FROM discussion_turns WHERE room_id=? AND status='queued' ORDER BY id", (room_id,)).fetchall()
+    if len(rows) < 2 or rows[-1]["expert"] != name:
+        return
+    _, experts, _ = discussion_roster(connection, room_id)
+    spoken = current_round_speakers(connection, room_id, experts)
+    open_turn = connection.execute("SELECT expert FROM discussion_turns WHERE room_id=? AND status IN ('pending','notified')", (room_id,)).fetchone()
+    if open_turn:
+        spoken.add(open_turn["expert"])
+    slot = len(rows) - 1
+    for index, row in enumerate(rows[:-1]):
+        if row["expert"] in spoken:
+            slot = index
+            break
+        spoken.add(row["expert"])
+    ordered = rows[:slot] + [rows[-1]] + rows[slot:-1]
+    for target, source in zip(rows, ordered):
+        connection.execute("UPDATE discussion_turns SET expert=?,question=? WHERE id=? AND status='queued'", (source["expert"], source["question"], target["id"]))
+
+
 def queue_invited_expert(connection, room_id, name, now):
-    """Append a new expert to an existing live plan without changing its current speaker or hold."""
+    """Queue a new expert in an existing live plan at its round-completing slot, without changing the current speaker or hold."""
     connection.execute("""INSERT INTO discussion_turns (room_id,expert,question,status,submission_id,created_at)
         SELECT settings.room_id,member.name,
             CASE WHEN settings.phase='initial' THEN '欢迎加入：请先读取议题，独立给出你的开场观点。'
@@ -797,6 +859,7 @@ def queue_invited_expert(connection, room_id, name, now):
         AND NOT EXISTS (SELECT 1 FROM discussion_limits WHERE room_id=settings.room_id AND closing_at>0)
         AND EXISTS (SELECT 1 FROM discussion_turns WHERE room_id=settings.room_id AND status IN ('pending','notified','queued'))""",
         (now, room_id, name))
+    place_invited_expert(connection, room_id, name)
 
 
 def add_discussion_member(connection, room_id, token, payload, now):
@@ -873,6 +936,8 @@ def adopt_manual_member(connection, room_id, member, payload):
     """Hand a manual expert to the local service once its CLI reported the session it runs in; the owner's service resumes that session."""
     reported = connection.execute("SELECT session_id FROM member_sessions WHERE member_id=?", (member["id"],)).fetchone()
     run = connection.execute("SELECT mode FROM discussion_runtime WHERE room_id=?", (room_id,)).fetchone()
+    if not registered_at(connection, member):
+        raise ValueError("成员尚未注册，不能转为托管")
     if not reported or reported["session_id"] != payload.get("session_id") or payload.get("adapter") not in ADOPTABLE_ADAPTERS:
         raise ValueError("成员尚未上报与之相符的会话，不能转为托管")
     if member["access"] != "manual" or member["status"] != "active" or not run or run["mode"] != "automatic":

package/backend/schema.sql

@@ -546,6 +546,13 @@ CREATE TABLE IF NOT EXISTS member_sessions (
     session_id TEXT NOT NULL,
     client TEXT NOT NULL
 );
+-- A manual member's own registration; it is bound to the credential it used, so a re-issued credential must register again.
+CREATE TABLE IF NOT EXISTS member_registrations (
+    member_id INTEGER PRIMARY KEY REFERENCES room_members(id) ON DELETE CASCADE,
+    room_id TEXT NOT NULL,
+    token_hash TEXT NOT NULL,
+    registered_at TEXT NOT NULL
+);
 CREATE TABLE IF NOT EXISTS member_executions (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     room_id TEXT NOT NULL REFERENCES rooms(id) ON DELETE CASCADE,

package/backend/server.py

@@ -23,7 +23,7 @@ from .free_room import (add_member, after_free_message, authorize_free_write, ch
                         inbox, interrupt_member, member_action, member_values, migrate_free_tables, proxy_member, reserve_execution,
                         discussion_members, room_mode, save_room_access, sync_discussion_members, view_execution)
 from .free_room import add_discussion_member, convert_suggestion, discussion_member_action, message_suggestions, save_suggestions, sync_participants
-from .free_room import adopt_recommendation, recommend_member
+from .free_room import adopt_recommendation, recommend_member, register_member
 from .identity import MAX_ROOM_AGENTS, PARTICIPANTS, is_ai, is_participant
 from .room_import import import_room, imported_attachment
 from .runtime import (authorize_write, begin_write, configure_runtime, event_action,
@@ -211,13 +211,16 @@ def require_room(connection, room_id):
     room["limits"] = limits_view(connection.execute(LIMITS_SQL, (room_id,)).fetchone(), room)
     room["mode"] = room_mode(connection, room_id)
     room["members"] = [dict(row) for row in connection.execute(
-        """SELECT m.id,m.name,m.adapter,m.role,m.status,m.access,m.session_mode,COALESCE(s.session_id,'') AS reported_session,COALESCE(s.client,'') AS reported_client
-        FROM room_members AS m LEFT JOIN member_sessions AS s ON s.member_id=m.id WHERE m.room_id=? AND m.status<>'removed' ORDER BY m.id""", (room_id,))]
+        """SELECT m.id,m.name,m.adapter,m.role,m.status,m.access,m.session_mode,COALESCE(s.session_id,'') AS reported_session,COALESCE(s.client,'') AS reported_client,
+        COALESCE(r.registered_at,'') AS registered_at
+        FROM room_members AS m LEFT JOIN member_sessions AS s ON s.member_id=m.id
+        LEFT JOIN member_registrations AS r ON r.member_id=m.id AND r.token_hash=m.token_hash WHERE m.room_id=? AND m.status<>'removed' ORDER BY m.id""", (room_id,))]
     option = connection.execute("SELECT named_followup FROM discussion_options WHERE room_id=?", (room_id,)).fetchone()
     # Rooms created before the option keep the host's named follow-ups.
     room["named_followup"] = bool(option[0]) if option else True
     room["scheduler_decisions"] = [dict(row) for row in connection.execute(
         "SELECT * FROM scheduler_decisions WHERE room_id=? ORDER BY id DESC LIMIT ?", (room_id, RECENT_DECISIONS))][::-1]
+    room["host_arrangements"] = host_arrangements(connection, room_id, room["scheduler_decisions"])
     parent = connection.execute("""SELECT rooms.id,rooms.title FROM room_links JOIN rooms ON rooms.id=room_links.parent_id
         WHERE room_links.room_id=?""", (room_id,)).fetchone()
     room["parent_room"] = dict(parent) if parent else None
@@ -264,6 +267,23 @@ def require_floor(room, speaker):
         raise FileExistsError("请先领取本人发言权；他人持有或尚未被点名时不能发言或安排")
 
 
+def host_arrangements(connection, room_id, decisions):
+    """Each plan the host created (turns saved in one batch), anchored after the latest answer before it.
+
+    Invitation turns are not plans, and a plan the smart scheduler applied is already shown by its own decision.
+    """
+    plans, latest_answer = [], 0
+    for row in connection.execute("SELECT id,expert,question,answer_id,created_at,submission_id FROM discussion_turns WHERE room_id=? ORDER BY id", (room_id,)):
+        if not row["submission_id"].startswith("invite:"):
+            if plans and plans[-1]["created_at"] == row["created_at"]:
+                plans[-1]["turns"].append({"expert": row["expert"], "question": row["question"]})
+            else:
+                plans.append({"id": row["id"], "after_message_id": latest_answer, "created_at": row["created_at"], "turns": [{"expert": row["expert"], "question": row["question"]}]})
+        latest_answer = max(latest_answer, row["answer_id"] or 0)
+    applied = {item["after_message_id"] for item in decisions if item["applied"]}
+    return [plan for plan in plans if plan["after_message_id"] and plan["after_message_id"] not in applied][-RECENT_DECISIONS:]
+
+
 def discussion_rounds(connection, room_id, experts):
     """Group complete history metadata until every configured expert has spoken.
 
@@ -549,7 +569,7 @@ def manage_room(connection, room_id, action, payload):
 
 def delete_room_records(connection, room_id):
     """Remove a room's dependent records in the caller's transaction."""
-    for table in ("member_recommendations", "member_requests", "member_executions", "member_sessions", "room_members", "room_modes", "free_batches", "free_chains", "room_links",
+    for table in ("member_recommendations", "member_requests", "member_executions", "member_sessions", "member_registrations", "room_members", "room_modes", "free_batches", "free_chains", "room_links",
                   "discussion_options", "scheduler_decisions"):
         connection.execute(f"DELETE FROM {table} WHERE room_id=?", (room_id,))
     connection.execute("DELETE FROM message_timings WHERE message_id IN (SELECT id FROM messages WHERE room_id=?)", (room_id,))
@@ -1614,6 +1634,10 @@ class DiscussionHandler(BaseHTTPRequestHandler):
             record_reported_session(connection, room_id, token, {"session_id": self.headers.get("X-Discussion-Session"),
                                                                  "session_client": self.headers.get("X-Discussion-Session-Client")})
             connection.commit()
+        if parts[3:] == ["register"] and method == "POST":
+            result = register_member(connection, room_id, token, utc_now())
+            connection.commit()
+            return self.respond(result)
         free = room_mode(connection, room_id) == "free"
         if free and parts[3:4] in (["inbox"], ["executions"], ["members"], ["suggestions"], ["recommendations"]):
             return self.handle_free_api(connection, parts, method)

package/docs/architecture.md

@@ -220,7 +220,7 @@ Python 通过进程内条件变量唤醒订阅者，不占用数据库连接，
 ## 讨论选项与智能调度记录
 
 - `discussion_options`：建房时的讨论选项，目前只有 `named_followup`（0/1，建房 `named_followup` 布尔值，默认 false，计入建房幂等比对）。没有记录的旧房间视为 true；房间视图返回 `named_followup`。
-- `scheduler_decisions`：讨论中每次智能调度判断的可见记录（`kind` 为 `interjection` / `round`，`label`、`confidence`、`applied`、`provider`、`after_message_id`），由接入程序用运行控制凭据 `POST scheduler-decisions` 写入，不是消息，不影响轮次、发言权与暂扣；房间视图 `scheduler_decisions` 返回最近 100 条。
+- `scheduler_decisions`：讨论中每次智能调度判断的可见记录（`kind` 为 `interjection` / `round`，`label`、`confidence`、`applied`、`provider`、`after_message_id`），由接入程序用运行控制凭据 `POST scheduler-decisions` 写入，不是消息，不影响轮次、发言权与暂扣；房间视图 `scheduler_decisions` 返回最近 100 条。房间视图另附 `host_arrangements`：由 `discussion_turns` 按同一批创建时间分组得到的主持人安排（不含邀请追加的开场安排，也不含已由智能调度写入决策的那一批），`after_message_id` 取该批之前最新的回答，网页在该回答后显示“主持人安排”卡片，逐条列出专家与主持人写的任务说明（`turns`，默认前 3 条，其余可展开），样式同智能调度卡片；没有可跟随的回答（讨论开场）时不显示。不新增表。
 - 两表都是独立表，D1 重新应用 schema 即可；备份、导入（`after_message_id` 随消息重编号）与删除一并处理。智能调度代主持人执行的写入不新增权限，沿用该主持事件的执行凭据。
 
 ## 自动运行协议
@@ -249,6 +249,7 @@ running 状态即使只有 pending 事件，也必须先暂停才能重新启动
 
 - **凭据**：建房时由客户端提供房间控制凭据和每位成员的成员凭证，服务端只存哈希。用户身份的房间写入（发言、附件、存档、恢复、删除、打断）都须控制凭据；房间排序和归入文件夹只改共享目录，与站点级文件夹操作一样不需要凭据；无凭据、错误凭据、成员凭证或他房凭据一律只读。成员凭证只能以该成员身份发言或上传附件。声明字段（`author`、`source`、localhost）不代替凭据。
 - **成员**：`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`。
 - **执行**：`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 完成回交，回交请求按（派活消息，主持人）唯一，重复执行不会重复唤醒。

package/docs/cli.md

@@ -157,6 +157,8 @@ codiscuss message post ROOM --as Claude --kind chat --execution 执行编号 --b
 
 手动接入的成员没有执行编号：`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` 请求。普通成员也可用 `--to` 或正文 `@成员` 提出回应建议，但不会派发；房主在网页点击“转为请求”后才建立关联原消息的新用户任务链。代码与引用里的正文 @ 不生成建议。
 
 ## 写入核对与错误处理