xuym-codex-collab 0.7.0 → 0.8.0

package/README.md

@@ -2,6 +2,8 @@
 
 把企业微信群的任务交给指定的已有 Codex 对话：管理员统一创建并分配机器人，同事导入个人接入包、绑定对话，即可接单、提交结果、通知真人审核并接力。每位成员只运行本机工具；共享任务协议和交接记录保存在业务仓库的 `agent-collab` 分支。
 
+当前只支持企业微信，先集中完善接入、任务协作和稳定性；其他 IM 的接入在企微流程稳定后再评估。
+
 ## 安装与入口
 
 需要 Node.js 20+、Git、Codex 桌面应用，以及业务仓库的读取和 push 权限。业务仓库需已有至少一个远程业务分支；可以使用独立的本机 clone，也可以让向导拉取新目录。成员无需 clone 本工具源码。
@@ -153,7 +155,7 @@ node bin/codex-collab.mjs setup
 - [团队签名协议与目录](docs/team-registry.md)
 - [Peer 机制与底层命令](docs/peer.md)
 - [已有桌面对话轮询机制](docs/desktop-poll.md)
-- [旧中心服务与飞书接入](docs/legacy-center.md)
+- [旧中心服务与企业微信接入](docs/legacy-center.md)
 
 2026-10-10 已由用户验证本机真实企业微信群 + Alice/Bob 两个已有 Codex 对话的接力闭环。网页向导与真人审核闭环通过临时 Git 仓库、模拟机器人和实际浏览器操作验证；2026-10-12 这轮测试没有连接真实机器人，原生 @ 尚未验证。跨两台机器的部署尚未验证。
 

package/docs/architecture.md

@@ -1,9 +1,17 @@
-# 旧中心服务实现与边界
+# 架构与范围
 
-本文描述源码保留的旧 HTTP 模式。当前推荐架构见 [团队接入](onboarding.md)、[Peer 机制](peer.md) 与 [签名团队登记](team-registry.md)。
+当前只支持企业微信。优先稳定企微的接入、收发、任务领取、交接和真人审核；其他 IM 的接入以后再评估。
 
-单个中心服务处理群消息、MCP 和 Runner HTTP API；它持有 `agent-collab` Git 独立 worktree，串行追加版本化事件。每位同事在自己的设备配置个人 MCP/Skill，选择性启动 Runner 领取由服务按用户分配的工作；Runner 为每个任务在本地创建独立 Git worktree 与 Codex SDK 会话。代码在 `codex/task-*` 分支，任务事件在 `agent-collab` 分支，两者不相互合并。群消息仅为结构化任务指令和状态摘要，**不共享原始私聊记录**。群内显示的是一个 Bot 代表不同账号的消息，不是真实的多个独立聊天机器人。
+## 推荐：本机 Peer 与网页向导
 
-消息路径：飞书/企微消息 -> 允许的群 ID 与平台用户 ID（飞书 open_id / 企微 userid） -> 命令解析 -> 服务权限检查 -> Git 提交 -> Bot 回复。任务路径：分配 -> Runner 领取 -> worktree 编码/提交/可信测试 -> 审查请求 -> 审查 Runner/人工审核 -> 管理员完成。`read_task` 和 `list_tasks` 可让同事桌面 Codex 人工参与；不会唤醒任意已开的桌面会话。
+每位成员运行本机 Peer，通过自己的企业微信智能机器人接收群消息，将任务交给绑定的已有 Codex 对话。管理员在网页向导中配置项目、分配机器人并批准成员；同事导入加密个人接入包、验证企微身份并绑定对话。项目可以包含多个机器人，每个机器人保留独立身份与权限。
 
-限制：仅支持单写服务，没有集群式 CAS、持久消息投递队列、续租/心跳、失败后自动恢复或 Git push 冲突重放。默认 localhost；远程接入必须自行部署 HTTPS 和访问限制。飞书或企业微信智能机器人长连接需应用权限、群和成员 ID；企微使用出站 WebSocket，无公网回调。企微尚待新凭据和真实群验证；两种通道都不能只以认证成功代替群收发验证。代理执行陌生仓库代码仍有风险，应在低权限容器隔离。
+团队目录、任务与交接记录存放在业务仓库的 `agent-collab` 分支，以签名记录校验身份和操作；代码在独立业务分支流转。协作远程与基准分支由向导识别和确认，每个任务固定基准 commit。已有桌面对话依赖显式启用的轮询自动化领取任务，安装 MCP 或 Skill 本身不会唤醒对话。详见 [Peer 机制](peer.md)、[签名团队协议](team-registry.md) 和 [桌面对话轮询](desktop-poll.md)。
+
+## 兼容：旧中心服务
+
+旧模式从源码启动一个 HTTP/MCP 服务，由它维护 `agent-collab` 的独立 Git worktree，串行追加版本化任务事件。每位同事配置个人 MCP/Skill，按需运行 Runner；Runner 创建任务 worktree 和新的 Codex SDK 会话。代码在 `codex/task-*` 分支，任务事件在 `agent-collab` 分支。群消息只提供任务指令和状态摘要，不共享原始私聊记录。此模式由一个 Bot 代表不同账号发送消息，不提供多个独立机器人路由。
+
+消息路径：企微群消息 → 群允许列表与 `wecom_userid` 身份映射 → 命令解析 → 服务权限检查 → Git 提交 → Bot 回复。任务路径：分配 → Runner 领取 → worktree 编码、提交与可信测试 → 审查 → 真人批准 → 管理员完成。只有明确属于当前企微群的任务才能通过群命令访问；历史未知通道数据保留原始来源，不自动转为企微任务。
+
+旧中心服务只支持单实例写入，没有持久消息投递队列、租约、失败自动恢复或 Git push 冲突重放。默认监听 localhost；跨机器需配置 HTTPS 与访问限制。企微智能机器人使用出站 WebSocket，无需公网回调；认证成功与实际群收发需分别验证。旧模式操作见 [中心服务指南](legacy-center.md)，不与推荐的 Peer 接入步骤混用。

package/docs/legacy-center.md

@@ -2,7 +2,7 @@
 
 日常团队接入请使用 [本机网页向导](onboarding.md)。本页保留旧 HTTP 服务操作，npm 包只分发 Peer 与本机向导；旧中心服务须从工具源码启动。
 
-以下为保留的**旧中心服务模式**操作；不要与上面的 Peer 测试混用机器人连接和命令。Peer 不使用 `localhost:38765`、HTTP 令牌或手工 `协作 分配` / `协作 交接` 命令。
+以下为保留的**旧中心服务模式**操作；不要与 Peer 混用机器人连接和命令。Peer 不使用 `localhost:38765`、HTTP 令牌或手工 `协作 分配` / `协作 交接` 命令。
 
 ## Codex 之间的代码接力
 
@@ -22,14 +22,14 @@ pnpm install --frozen-lockfile
 pnpm test
 ```
 
-演示目标仓库 `codex-collab-demo` 的 `main` 执行 `sh test.sh`，而任务事件在 `agent-collab`。示例任务 T-001 为故意未完成的编程任务；可用两个不同用户通过 API/MCP 和 Runner 测试。现有 T-001 未指定审核人，建议通过飞书命令创建**新任务**以获得默认管理员审核人。
+演示目标仓库 `codex-collab-demo` 的 `main` 执行 `sh test.sh`，而任务事件在 `agent-collab`。示例任务 T-001 为故意未完成的编程任务；可用两个不同用户通过 API/MCP 和 Runner 测试。现有 T-001 未指定审核人，建议通过企微群命令创建**新任务**以获得默认管理员审核人。
 
 ## 本地启动
 
 生成账号文件（不要放进 Git，执行完把终端输出的个人令牌安全地分发给对应用户）：
 
 ```sh
-node scripts/create-accounts.mjs /tmp/collab-accounts.json alice:admin:ou_alice bob:member:ou_bob
+node scripts/create-accounts.mjs /tmp/collab-accounts.json alice:admin:wx_alice bob:member:wx_bob
 COLLAB_REPO=/path/to/codex-collab-demo \
 COLLAB_ACCOUNTS_FILE=/tmp/collab-accounts.json \
 COLLAB_DATA_DIR=/tmp/collab-service \
@@ -37,7 +37,7 @@ COLLAB_REPO_ID=jack506255560/codex-collab-demo \
 node apps/server/main.mjs
 ```
 
-运行成功后 `curl http://127.0.0.1:38765/health`。`ou_alice` 与 `ou_bob` 需要换为飞书用户的**真实** `open_id`。管理员身份为默认审核人；编码负责人不能与审核人为同一人。如需自动领取任务，同事机器运行：
+运行成功后 `curl http://127.0.0.1:38765/health`。`wx_alice` 与 `wx_bob` 需要换为企微成员的真实 `userid`，可用下方发现脚本获取。账号参数格式为 `id:role:wecom_userid`；暂时仅通过 API 使用时填 `id:role:-`。旧四段账号参数不再接受，已有账号文件与个人令牌可继续使用，补充企微身份时使用 `scripts/bind-wecom-users.mjs`。管理员身份为默认审核人；编码负责人不能与审核人为同一人。如需自动领取任务，同事机器运行：
 
 ```sh
 COLLAB_REPO=/path/to/codex-collab-demo \
@@ -50,57 +50,17 @@ node apps/runner/main.mjs
 
 `COLLAB_API` 单机实验可用 `http://127.0.0.1:38765`；不同机器应提供 HTTPS，且每台机器的目标仓库含 `main` 和 `agent-collab` 分支。若跨机器分发代码分支，需要在服务和 Runner 均设置 `COLLAB_PUSH=1`，保证 origin 可访问且个人 Git 凭据已配置。服务向 `agent-collab` 推送账本，Runner 向 `codex/task-*` 推送代码；**没有凭据会失败**。不能直接把 localhost 地址给其他同事。
 
-## 飞书接入
+## 企业微信群接入
 
-1. 飞书开放平台创建企业自建应用，启用机器人、申请“以应用身份发送消息”和接收群消息所需权限；启用 `im.message.receive_v1` 事件，选择**长连接**接收并发布/授权应用（具体权限以飞书控制台当前要求为准）。
-2. 将 Bot 加到群中，先在本机设置 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` 并运行 `node scripts/discover-feishu.mjs`；在目标群发一条普通消息，终端只打印 `chat_id` 和 `sender_open_id`（不会保存正文），确认所有同事的 open_id 后停止该脚本，再填入账号文件与 `FEISHU_CHAT_IDS` 允许列表。**不要**写死或提交 App Secret。
-3. 启动中心服务时追加：`FEISHU_APP_ID=... FEISHU_APP_SECRET=... FEISHU_CHAT_IDS=oc_...`。看到 WebSocket 订阅日志后，在允许的群由已映射成员发：`协作 创建 写一个功能 | 验收一;验收二`，管理员 `协作 分配 T-... bob`，所有人 `协作 状态 T-...`。Runner 提交审核请求后审核人 `协作 审核 T-... 通过` 或 `协作 审核 T-... 退回`，最后管理员 `协作 完成 T-...`。
-4. 检查群回复、服务日志、目标仓库 `agent-collab` 事件与本机代码分支。未配置飞书凭据时可以跑本地模拟 E2E；模拟通过**不等于**真实群接通。
+1. 在企业微信创建支持 API 长连接的智能机器人，取得 Bot ID 和 Secret，并加入协作群。它通过官方 `@wecom/aibot-node-sdk` 建立出站 WebSocket，无需公网回调。一个 Bot 对应这一个中心服务，由私有账号文件区分成员。
+2. 在本机交互终端设置 `WECOM_BOT_ID`、`WECOM_BOT_SECRET` 后，运行 `node scripts/discover-wecom.mjs`。等待认证成功，再在目标群 @机器人发送文本。脚本只输出 `chatid` 和 `userid`，不输出正文。记录群和成员 ID 后，按 `Ctrl-C` 停止发现脚本，再启动服务；同一个机器人只保留一个连接。
+3. 新账号直接按上方三段格式生成；已有账号可运行 `node scripts/bind-wecom-users.mjs <旧账号文件> <新账号文件> 'alice:<真实userid>' 'bob:<真实userid>'`，再将 `COLLAB_ACCOUNTS_FILE` 指向新文件。此脚本保留个人令牌哈希，不改原文件。不同账号不能绑定相同 `userid`。
+4. 启动中心服务时同时设置 `WECOM_BOT_ID`、`WECOM_BOT_SECRET` 和 `WECOM_CHAT_IDS`，多个群 ID 用逗号分隔。凭据保存在本机私有环境，群 ID 和成员 ID 不提交到 Git。未配置机器人时只启用 HTTP/MCP API。
+5. 在允许的群由已映射成员依次验证：`协作 创建 写一个功能 | 验收一;验收二`、管理员 `协作 分配 T-... bob`、`协作 状态 T-...`。Bob 的 Runner 领取后，提交代码与测试证据并请求审查；指定审核人核对结果后执行 `协作 审核 T-... 通过` 或 `协作 审核 T-... 退回`，管理员最终执行 `协作 完成 T-...`。批准和完成均需真人明确操作。
 
-## 本机接企业微信群（已有隔离 demo 和两个 Runner 时）
+认证成功、群消息到达、群回复和主动任务通知需分别验证。排查无回复时可临时设置 `COLLAB_WECOM_DIAGNOSTICS=1` 并重启服务；诊断不输出正文、凭据或群/成员 ID。Runner 需单独启动，HTTP 服务不会代为启动它。
 
-**先在企业微信管理端创建/配置支持 API 长连接的智能机器人**，获取 Bot ID 和**新** Secret，加入测试群。此前曾在聊天里暴露的 Secret 已不安全：必须先重置，不要再次发送到聊天或提交 Git。此处用的是「智能机器人 API 模式」，不是只有 webhook URL 的群机器人；连接通过官方 `@wecom/aibot-node-sdk` WebSocket 出站发起，不需要公网地址。确认组织管理员允许此类型机器人、目标群确实能收到其群消息。一个 Bot 足够；它通过账号映射和本地两个 Runner 分配身份，不对应两个桌面 Codex 会话。群消息能否到达以真机发现为准，尝试在群内 @ 机器人发送文本。
-
-当前单机测试目录可以这样找（不要打印里面的令牌或环境文件）：
-
-```sh
-cd "$HOME/codex-collab"
-# 确保 Node.js >= 20 已安装并且 node 位于 PATH。
-root="$(cat "$HOME/.codex-collab-local-test/current")"
-# 仅在你的本机交互终端输入；不要把实际值放在命令行参数或聊天中。
-printf 'Bot ID: '; IFS= read -r WECOM_BOT_ID
-printf '新 Bot Secret（不回显）: '; IFS= read -rs WECOM_BOT_SECRET; echo
-export WECOM_BOT_ID WECOM_BOT_SECRET
-node scripts/discover-wecom.mjs
-```
-
-等待输出 `WeCom authenticated`，在目标群里向机器人发送文本，例如 `@机器人 协作 状态 T-NONE`；发现脚本仅输出 `{"chatid":"...","userid":"..."}`，**不会输出正文**。这一步如果只有认证而没有群消息，不代表群已接通：检查群是否已加入机器人、消息触发方式和企业管理员配置。在发现脚本按 `Ctrl-C` 关闭连接，再继续下面步骤；**同一个机器人不要让发现脚本和服务同时建立连接**。至少记下一个真实群 `chatid` 及你（管理员 alice）的 `userid`，若同事要在群里发命令，再收集其 `userid`。不要猜 ID、不要贴到 Git。以下命令的引号和交互输入要保留：
-
-```sh
-printf '刚发现的群 chatid: '; IFS= read -r WECOM_CHAT_IDS
-printf '你自己的 userid（alice）: '; IFS= read -r ALICE_WECOM_USERID
-export WECOM_CHAT_IDS
-node scripts/bind-wecom-users.mjs "$root/accounts.json" "$root/accounts.wecom.json" "alice:$ALICE_WECOM_USERID"
-# 可选：另一位真人需在群里操作时，用他的 userid 重建私有文件；不要把两人的 userid 填成同一个。
-# node scripts/bind-wecom-users.mjs "$root/accounts.json" "$root/accounts.team.json" "alice:$ALICE_WECOM_USERID" 'bob:<同事的真实userid>'
-# 新文件只保留原有的个人 token 哈希，原有 Runner 令牌不会变化。
-. "$root/private.env"
-export COLLAB_ACCOUNTS_FILE="$root/accounts.wecom.json"
-# 仅停原中心服务，保持两个 Runner；先确认旧 PID 确实是本工具的服务。
-old="$(cat "$root/server.pid")"
-ps -p "$old" -o command=
-# 仅在确认该进程属于当前仓库的 apps/server/main.mjs 后，才手动执行：kill "$old"
-node apps/server/main.mjs
-```
-
-上面最后一条**前台运行**，该终端不要退出；另开终端 `curl http://127.0.0.1:38765/health` 检查服务。若提示端口占用，先核对旧服务 PID，勿盲目杀其他进程。若群中收到真实回复才算接通。群里的任务示例：
-
-1. `协作 创建 给 greet.sh 增加 --upper 行为 | sh test.sh 通过;sh greet.sh --upper 输出 HELLO, WORLD;保留原有默认输出`，记下新任务 `T-...`；不要重复使用历史任务。
-2. `协作 分配 T-... bob`；本机 Bob Runner 自动领取并在隔离副本创建 `codex/task-*` 代码分支。Alice Runner 可读取审查任务并写私有审查记录。
-3. `协作 状态 T-...`；人工核对 `git -C "$root/demo" branch --list 'codex/task-*'`、`sh test.sh`（需要在**任务分支**的 worktree 执行；`main` 故意未完成，不能直接把它的失败当任务失败）和 `$root/server-data` 的 Git 账本；不能把 Runner 记录当人工批准。
-4. 确认代码和测试证据后，由 **alice 真人**发 `协作 审核 T-... 通过`，再发 `协作 完成 T-...`；这两个动作不会由 Runner 自动执行。失败就 `协作 审核 T-... 退回`。
-
-**注意**：发现、认证、模拟 E2E、真实群消息送达、群回复、主动任务通知是不同的成功条件；逐项核实。这里使用 `$root/demo` 隔离副本，不修改或推送原始 demo 仓库。`COLLAB_PUSH` 单机保持默认关闭；源仓库与真实企业账号信息勿放入 Git。若之前本机 Runner 不在运行，查看 `ps` 与 `apps/runner/README.md`；不要以为启动 HTTP 服务就会自动启动 Runner。
+当前只支持企微；新群任务明确写入 `channel: "wecom"`。历史任务的原始来源保留，不会被自动改写成企微来源；缺少通道或属于其他通道的任务不能在企微群查询，也不会向企微群发送通知。API 任务可继续通过已授权 API/MCP 操作。
 
 ## 同事接入 MCP 和 Skill
 

package/docs/protocol.md

@@ -16,6 +16,6 @@ Task IDs are opaque and unique within a repository. `spec.json` defines reposito
 
 From `open` (the task creator's desktop work), `assigned` (the current owner), or `running`, a verified `handoff` becomes `waiting`. It must contain a concise summary and `refs.branch`, `refs.commit` and `refs.tests`; the server verifies that the pinned commit is the tip of its own `codex/*` branch (on `origin` when Git push is enabled). Only the creator may hand off an open task and only the assignee may hand off assigned/running work. An admin then explicitly assigns the waiting task to the next person; that person's Runner fetches the handoff branch and starts from the pinned commit, not `main`. From `running`, `progress` stays `running`, `blocked` or `run_failed` becomes `blocked`; from `blocked` or `waiting`, `assigned` returns to `assigned`. From `review`, `review_started` records a review run and `review_note` records concise review notes while preserving `review`; `reviewed(changes_requested)` becomes `blocked`. A `review_requested` event must name the reviewing agent. `cancelled` terminates any nonterminal state. A `completed` event is allowed only after approved review, and must carry evidence references as required by the server policy. Run completion and task completion are different events.
 
-The server must deduplicate Feishu and WeCom message IDs with channel-prefixed idempotency keys. Group-created task `spec.source` includes `chat_id` and `channel` (`feishu` or `wecom`); group commands cannot access a task from another group/channel or a task without group provenance. The `channel` field on events records the originating platform for assignments. For two concurrent modifications, assignments and sequence allocation are serialized at the Git-writing service. A Git commit author string is not an authorization mechanism. Do not commit full chat transcripts, authentication material or private filesystem paths.
+WeCom is the only supported chat channel. The server must deduplicate WeCom message IDs with `wecom:<message-id>` idempotency keys. New group-created task `spec.source` includes `chat_id` and `channel: "wecom"`; new group assignments carry the same explicit channel. Unsupported channel values are rejected on create, assign and report. Group commands cannot access a task from another group or a task without explicit WeCom provenance. The schemas describe supported writes; historical metadata can still be read through the API without being rewritten or reinterpreted as WeCom, and tasks from an unsupported or unknown channel do not generate WeCom notifications. For two concurrent modifications, assignments and sequence allocation are serialized at the Git-writing service. A Git commit author string is not an authorization mechanism. Do not commit full chat transcripts, authentication material or private filesystem paths.
 
 Schemas: `schemas/task.schema.json`, `schemas/event.schema.json`. A simple executable reducer lives in `packages/protocol/src/index.mjs`.

package/docs/releases/0.8.0.md

@@ -0,0 +1,21 @@
+# 0.8.0：专注企业微信
+
+当前只支持企业微信，优先稳定接入、群收发、任务领取、代码交接与真人审核。其他 IM 的接入在企微流程稳定后再评估。
+
+- 移除飞书适配器、群信息发现脚本、身份映射入口及 SDK；安装依赖减少 24 个包。
+- 网页向导和 Peer 保持现有企微接入方式，同一项目多个机器人、个人接入包及已绑定 Codex 对话继续使用。
+- 旧中心服务保留企微、HTTP/MCP、Git 任务账本和 Runner。新群任务与分配明确记录 `channel: "wecom"`；其他通道写入被拒绝。
+- 历史任务保留原始来源。属于其他通道或缺少明确企微来源的任务仍可通过已授权 API 读取，不允许企微群查询或发送群通知。
+
+## 升级
+
+```sh
+npm install --global xuym-codex-collab@0.8.0
+codex-collab
+```
+
+现有 Peer 配置与业务仓库无需迁移。升级后重新启动本机工作台与已运行的机器人连接，使进程加载新版本；需要时在对应 Codex 对话重新连接 MCP。
+
+从源码使用旧中心服务时，账号生成脚本只接受 `id:role:wecom_userid`，仅用 API 则填 `id:role:-`。旧四段参数会报错，避免身份错配。已有账号文件与个人令牌继续有效；补充企微身份可使用 `scripts/bind-wecom-users.mjs`，无需重新生成令牌。
+
+本轮验证使用临时 Git 仓库、企微消息与 Codex mock，另检查 npm 安装和向导启动；不新增真实群或跨设备验收结论。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xuym-codex-collab",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Git-backed collaboration tools for Codex teams, with MCP, WeCom, and local runners.",
   "repository": {
     "type": "git",
@@ -52,7 +52,6 @@
     "peer": "node scripts/peer/cli.mjs"
   },
   "dependencies": {
-    "@larksuiteoapi/node-sdk": "1.74.0",
     "@modelcontextprotocol/node": "2.1.1",
     "@modelcontextprotocol/server": "2.3.1",
     "@openai/codex-sdk": "0.161.0",

package/schemas/event.schema.json

@@ -34,7 +34,7 @@
     "summary": { "type": "string", "maxLength": 4000 },
     "assignee": { "type": "string", "minLength": 1 },
     "chat_id": { "type": "string", "minLength": 1 },
-    "channel": { "enum": ["feishu", "wecom"] },
+    "channel": { "const": "wecom" },
     "run_id": { "type": "string", "minLength": 1 },
     "decision": { "enum": ["approved", "changes_requested"] },
     "refs": {

package/schemas/task.schema.json

@@ -13,6 +13,6 @@
     "description": { "type": "string" },
     "base_branch": { "type": "string", "minLength": 1 },
     "acceptance": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
-    "source": { "type": "object", "additionalProperties": { "type": "string" } }
+    "source": { "type": "object", "properties": { "channel": { "const": "wecom" } }, "additionalProperties": { "type": "string" } }
   }
 }