Codewhale Agent 多端统一身份架构解析：从 GitHub PR 评审到聊天频道的单一 Agent 表面

Codewhale Agent 多端统一身份架构解析：从 GitHub PR 评审到聊天频道的单一 Agent 表面

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale

Codewhale Agent 是 Codewhale（用 Rust 构建的开源终端编码 Agent）推出的"一个产品身份、多种传输表面"（one identity, many surfaces）架构。它以单一引擎Engine::run_turn为 I/O 中枢，通过 GitHub App 机器人、Git commit 共同署名与聊天频道（当前为 Telegram）三种表面对外服务，并以统一会员身份、统一审批路由与全链路审计作为"多端仍是一体"的契约规则。阅读本文，你将理解 Codewhale Agent 各表面的构成、身份归属与状态、端到端的 Telegram 配对链路，以及驱动这些表面的 GitHub PR 评审工作流与源码级实现细节。

一个身份，多种表面：Codewhale Agent 的定位

根据 docs/CODEWHALE_AGENT.md，"Codewhale Agent" 不是多个分散的机器人，而是一个产品身份承载在多种"表面"（transport surface）上。这份文档本身是该身份的地图（identity map）：回答"每个表面是什么、它在哪里、以及哪些规则让它们仍然是同一个产品而不是多个产品"。

三张表面的身份总览

需要说明：表格中services/control-plane、integrations/chat/、packages/contracts位于文档所指的 CWC（companion）仓库，不属于本仓库。但本仓库根目录下的 integrations/ 目录实际收纳了多个桥接实现（telegram-bridge、feishu-bridge、wecom-bridge、weixin-bridge），与文档"多聊天渠道扩展"的方向相互印证；其中weixin-bridge的入口配置与"个人微信自动化不受支持"的约束并存。

聊天表面的演进路线

文档明确了渠道推进顺序：Telegram（今天）→ Slack / Feishu / Lark（下一步）→ Discord / WeCom（未来）。每种渠道都通过独立的格式适配器工作（详见下文"频道契约"一节），因此扩展新渠道并不改变 Agent 的身份与内核。

让"多端"保持"一体"的六条规则

核心文档 中"Rules that make it one identity"一节给出了六条不可逾越的架构约束，它们是整个多端设计的灵魂：

1. 单一引擎、单一回合循环：每个表面都只是围绕唯一Engine::run_turn的 I/O（crates/tui/src/core/engine/turn_loop.rs），任何表面都不得拥有自己的引擎或回合循环。
2. 同一会员身份：每个表面都向同一 Codewhale 会员身份认证（即codewhale login建立的账户会话）。会员资格是云 Agent 的准入门槛；各 provider 品牌保持内部化且不可见。
3. 审批回流同一引擎：来自任何表面的审批都作为"权限决策"（permission decision）路由回同一个引擎；一条裸消息永远不会执行被门控的操作。
4. 全渠道全量审计：每个命令和每次审批，在每个渠道上都被审计记录。
5. 所有表面免费：速率限制只用于反滥用；没有按渠道收费、按消息计量、团队门禁或试用计时器；对渠道功能挂上计费钩子被"钱模型"（money model）明令禁止。

这些规则在源码层面有清晰的落点：引擎的回合入口位于 crates/tui/src/core/engine.rs（pub struct Engine于第 782 行附近定义），而实际的单回合执行函数run_turn定义在 crates/tui/src/core/engine/turn_loop.rs，其签名接收TurnContext、ToolSurfacePolicy（工具表面策略）与前台子进程注册表等参数——这恰好印证了"表面（surface）作为引擎输入策略、而非独立实现"的设计：不同端只是以不同方式调用同一回合循环并施加各自的工具面策略。

引擎同时承载着回合级墙钟预算（turn_wall_clock_budget，R1 预算，见 engine.rs）与审批等待暂停机制，所有表面共享这些语义，从实现上杜绝了"某个端绕过审批/预算"的可能。

命名规范：对外永远只说 Codewhale

• 产品名：Codewhale；Agent 表面名："Codewhale Agent"。
• 在可选处，bot 句柄统一为codewhale-agent。
• Agent 对外自称"Codewhale cloud agent"，绝不以任何 provider 品牌自称（如从不宣称自己是某模型厂商的机器人）。

这保证了无论用户在 GitHub PR 评论区、Telegram 私聊还是 commit 作者字段里遇到它，认知都是同一个产品。

频道契约：命令白名单、审批键盘与配对安全

codewhale-agent.md 的 Channel contract 章节 定义了所有聊天表面的统一行为契约：

• 按频道命令白名单：默认只读——status、jobs、receipts、help；可显式选择加入的写命令——new task、approve、deny。
• 内联 approve/deny 键盘：作为权限决策被路由（与"规则"部分的第 3 条呼应——键盘点击最终会转化为引擎内的授权判定，而不会绕过审批直接执行）。
• assistant_changes回复模式：仅在"有变化发生"时才发消息，减少噪音。
• 按频道消息格式适配器：今天为 Telegram markdown；规划中的有 Slack blocks、Feishu/Lark cards、WeCom markdown。
• 静默时段与摘要（quiet hours + digest）。
• 自动化输出可路由到任意已配对频道。
• 一个配对码绑定在已认证应用内；解除绑定立即吊销（unbind revokes instantly）。

Telegram 配对链路（端到端）

文档给出 Telegram 表面已打通的关键链路：

token → vaultcredentialRef→ 一次性代码 →/start绑定 chat ↔ membership

即：用户登录获得 token，凭证以credentialRef形式进入 vault；bot 颁发一次性配对码；用户在 Telegram 对 bot 发送/start完成聊天会话与 Codewhale 会员身份的绑定。整个配对码被绑定在"已认证应用"之内（即无法脱离账户会话单独使用），而 unbind 是即时吊销，不存在宽限期窗口。

微信渠道的明确边界

• 个人微信自动化不被支持——逆向工程协议会导致用户账号被封禁。
• 官方公众号/服务号 API 是唯一可接受路径，且仍处于评估阶段（under assessment）。

这一点与仓库中 integrations/weixin-bridge/ 的存在并不冲突：桥接方向是合规的官方 API 通道，而非个人号逆向。

纵深示例：GitHub PR 评审表面如何落地

仓库内最完整的表面实现证据就是 GitHub 评审工作流。该工作流由文档定位到本仓库内的 .github/workflows/codewhale-review.yml，而完整的一步步配置说明在同目录的 docs/GITHUB_APP.md。

工作流行为与"身份切换"机制

• 触发器：pull_request的opened / synchronize / reopened / ready_for_review，分支限master、main；draft == false才运行。
• 每个非 draft PR 产生一次 COMMENT 评审：一段摘要正文加锚定到 PR head SHA 的行内评论；它从不 approve、从不 request changes——人类权威（CODEOWNERS）不被取代。
• 身份切换：当仓库变量CODEWHALE_APP_ID与密钥CODEWHALE_APP_PRIVATE_KEY同时存在时，通过actions/create-github-app-token@v3铸造 App 的短期安装 token，并以GH_TOKEN注入 CLI；否则回退到工作流自身的github.token。CLI 从不存储 token，每次运行重新铸造。
• 未配置评审密钥时，任务以绿色 + notice 跳过（"safe to merge before configured"）；真实评审失败（HTTP 401/402/403/408/429/5xx）时同样不阻塞 PR，但会在 PR 上留下幂等的codewhale-review-nonrun标记注释——沉默绝不等于评审通过。

评审密钥体系（CODEWHALE_API_KEY 优先）

任意一个密钥即可启用。工作流用case "$PROVIDER"把权威密钥映射到目标 provider 的环境变量名上，因此更换模型时密钥名不必变动；若同时设置了权威密钥与 provider 自有密钥，权威密钥胜出（覆盖 BYOK 值）。密钥存在性检测放在 job 级env:（而非if:）中，是因为 GitHub Actions 的secrets上下文不可用于 job 级if:，只能读进env.HAS_ANY_KEY布尔串再被各 step 的if:引用——真正的密钥值只注入到运行评审的唯一步骤。

路由选择与输出预算

• 仓库变量CODEWHALE_REVIEW_PROVIDER（例zai）直通为codewhale review --provider zai；CODEWHALE_REVIEW_MODEL（例GLM-5.3）直通为--model。
• 两者均可选：未设置时，provider 由"设置了哪把密钥"推断（权威密钥默认走 z.ai Coding Plan 路由），模型用该 provider 默认值。不设置--provider的风险在于：当一个模型 id 能被多个已配置路由触达时，路由解析拒绝猜测并硬报错——如model glm-5.3 is available from configured provider route(s): openrouter, zai，此时必须显式传--provider。
• 输出预算：GLM-5.3 是推理模型，先输出reasoning_content再输出content，两者都计入max_tokens，因此过小的预算会得到空评审而非错误。CLI 自带 64K 自动上限已足够，工作流默认不设上限；若通过变量CODEWHALE_REVIEW_MAX_OUTPUT_TOKENS覆盖，则导出为CODEWHALE_MAX_OUTPUT_TOKENS并拒绝低于 8192 的值，同时对"exit 0 但零长度输出"判失败。

GitHub App 一次性配置（五步）

App 身份是可选项——本地codewhale review --pr N打印报告并不需要它。需要 App 身份时，仓库管理员（owner 权限）只需完成 GITHUB_APP.md 的五个步骤：

1. 创建 App：GitHub → Settings → Developer settings → GitHub Apps → New GitHub App，命名（如Codewhale Agent），并取消勾选 Webhook → Active（评审由 Actions 在 PR 事件上拉取，无需 webhook）。

2. 授予两个仓库权限：Pull requests →Read & write（发布评审与行内评论）；Contents →Read-only（读 diff，够用即可）；可见范围选Only on this account。

3. 下载私钥：Private keys → Generate a private key，妥善保存.pem。

4. 安装 App并选择要覆盖的仓库。

5. 添加仓库设置（Settings → Secrets and variables → Actions）：

   种类	名称	值
   Variable	CODEWHALE_APP_ID	App 页面上显示的 App ID
   Secret	CODEWHALE_APP_PRIVATE_KEY	.pem文件全文
   Secret	CODEWHALE_API_KEY	你的 Codewhale 评审密钥（或上表任一 BYOK provider 密钥）

   评审密钥是唯一必需项；CODEWHALE_REVIEW_PROVIDER、CODEWHALE_REVIEW_MODEL、CODEWHALE_REVIEW_MAX_OUTPUT_TOKENS三个变量可选。

本地手动评审命令

# 本地打印报告（使用你已配置的 provider 密钥） codewhale review --pr 1234 # 当某模型可被多个 provider 触达时，钉住路由 codewhale review --pr 1234 --provider zai --model GLM-5.3 # 发布到 GitHub，身份取决于 GH_TOKEN 携带的是谁 codewhale review --pr 1234 --post

GH_TOKEN可以是ghCLI token（以你本人身份发布）或 App 安装 token（以 App 身份发布）；--post始终是显式选择加入。

常见故障排查速查表

• 评审以你本人身份而非 bot 发布：变量或私钥密钥缺失/为空，任务静默回退到github.token，逐字符核对两个名字。
• 日志显示 "No Codewhale review key is set — skipping"：属预期，直到CODEWHALE_API_KEY（或任一 BYOK 密钥）存在。
• 报错 "available from configured provider route(s): ..."：配置了两把 provider 密钥且模型可被两者触达，设置CODEWHALE_REVIEW_PROVIDER即可。
• 空评审但任务绿色：推理模型把整个预算花在reasoning_content上，提高CODEWHALE_REVIEW_MAX_OUTPUT_TOKENS（或取消以用 CLI 自动上限）。
• App token 步骤失败：.pem可能在设密钥后被重新生成——把最新密钥重新粘贴到CODEWHALE_APP_PRIVATE_KEY，并确认 App 确实安装到了该仓库。
• 名字已被占用：GitHub App 名称全局唯一，换一个名字即可（bot 的展示登录名是<slug>[bot]，由名字派生）。

另一张现有表面：commit 共同署名（AUTHOR_MAP）

GitHub 评审之外，文档把commit 共同署名也列为一张"已存在"的表面：仓库根目录下的 .github/AUTHOR_MAP 是一份"贡献者信用身份映射表"，格式为：

alias = Display Name <id+login@users.noreply.github.com>

其关键约束（文件头部注释即说明）：右侧必须使用GitHub 的数字 noreply 地址（如101357273+Hmbown@users.noreply.github.com），这样被收割（harvested）的共同署名信用才能正确落入 GitHub 贡献者图谱；左侧可以是 GitHub 登录名、旧式 noreply 地址、贡献者提交里的原始邮箱，或历史中被收割过的本地机器邮箱。仓库内该文件当前收录了 243 行映射，覆盖从核心维护者到社区提交者的多条别名归一。

这张表与文档"多端同身份"的主题直接相关：无论贡献者历史上以哪种邮箱提交，最终都会归一为同一个 GitHub 数字身份，使跨表面的信用统计保持一致。

身份一致性在本仓库中的实现证据小结

若要深入源码验证"一引擎、多表面"的架构约束，可在本仓库中按以下路径追踪：

• 引擎与回合循环：核心文档指向的 crates/tui/src/core/engine/turn_loop.rs，run_turn定义于 L626 起；引擎本体（含回合墙钟预算、审批暂停等横切语义）见 crates/tui/src/core/engine.rs。
• 审批决策语义：引擎审批实现位于 crates/tui/src/core/engine/approval.rs，与"approve/deny 键盘路由为权限决策、裸消息不执行门控动作"的契约对应。
• GitHub 表面：评审工作流 .github/workflows/codewhale-review.yml 与完整配置文档 docs/GITHUB_APP.md；更广的自动工作流语境见 docs/AUTOMATIC_WORKFLOWS.md。
• 贡献者署名表面：.github/AUTHOR_MAP 与配套的 .github/scripts 收割流程。
• 聊天桥接方向：仓库根目录 integrations/ 下的telegram-bridge、feishu-bridge、wecom-bridge、weixin-bridge，可作为理解多渠道扩展的辅助材料（注意其中 Telegram 的正式后端控制面在文档所指 CWC 仓库中）。

综上，Codewhale Agent 的核心设计可以浓缩为一句话：无论用户从 GitHub 评论区、Telegram 会话还是 commit 图谱中遇见它，背后都是同一个Engine::run_turn、同一个 Codewhale 会员身份，以及同一套审批回流与审计纪律——这正是"one identity, many surfaces"的可执行定义。

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale