Team Reports 插件
Team Reports 会收集 GitHub 组织活动以及可选的 Discord 讨论,并生成每日、每周和每月报告。它会在 Gateway 上保存报告历史,并在 Control UI 中添加 报告 选项卡。报告包括活动计数、按人员划分的历史记录、来源警告以及可选的模型撰写摘要。
Team Reports 是一个官方外部包:它不属于核心 openclaw npm 包,而是按需从 ClawHub 或 npm 安装。仓库的源代码检出会直接从 extensions/team-reports 加载它。在你启用它之前,它会保持禁用状态。报告页面使用 Gateway 身份验证。其默认 HTTP 路由是 /plugins/team-reports/;Control UI 选项卡打开于 /reports,并带有任何已配置的 Control UI 基础路径前缀。
开始之前¶
你需要一个可以读取已配置组织、仓库和团队成员身份的 GitHub token。收集只能包含该 token 可以访问的数据。对于 Discord,请使用一个可以访问所选 guild、频道、线程和消息历史的 bot token。只有明确配置的频道及其线程会被计入。
支持细粒度 GitHub token。Issue 搜索始终指定 is:issue 或 is:pull-request,合并搜索仅限于 pull request。
模型撰写摘要会使用代理已配置的模型和凭据。发送到该模型的证据可以包括仓库活动和已选择加入的 Discord 摘录。设置 summaries.enabled: false 可生成具有确定性文本且不调用摘要模型的报告。
安装并启用 Team Reports¶
除非你从源代码检出运行 Gateway(其中已包含该包),否则请安装该包:
然后将以下内容添加到你的 OpenClaw 配置中,并将示例组织、团队和登录名替换为你自己的值:
{
plugins: {
entries: {
"team-reports": {
enabled: true,
config: {
github: {
token: {
source: "env",
provider: "default",
id: "TEAM_REPORTS_GITHUB_TOKEN",
},
orgs: ["example-org"],
teams: [{ org: "example-org", slug: "maintainers" }],
},
people: [{ github: ["example-member"], display: "Example Member" }],
summaries: { enabled: false },
},
},
},
},
}
让被引用的环境变量对 Gateway 进程可用。有关其他 secret 提供者,请参阅 密钥管理。如果你使用 plugins.allow,请确保该列表中包含 team-reports。
插件配置更改会在默认混合重载模式下自动生效。如果 Gateway 处于离线状态,请在其已配置的 secret 可用时启动它。如果你更改了其进程环境,请使用更新后的环境重启它。然后检查该插件:
启动不会触发报告任务。首次计划运行会收集昨天的已关闭报告和今天的部分报告;如果该运行发生在下一个 UTC 午夜之后,还会收集启动前的一天,并复用同一组织范围内健康的已关闭每日报告。这也会恢复部分失败的运行,而无需重新收集已接受的已关闭日期。手动生成仍会刷新所请求的日期。周报和月报使用已存储的每日活动。 收集和聚合在 worker 中运行,有界批次暂存在插件的 SQLite 连接中。临时活动会在该连接关闭时消失;已接受的报告历史和保留策略保持不变。
状态会显示运行、已存储周期、下次计划时间和来源警告。若要立即请求报告,请使用:
生成操作会在记录运行后、收集和摘要完成前返回一个运行 ID。检查 status 以查看结果,然后在 Control UI 中打开 报告。
在 Control UI 中查看报告¶
对于已启用的插件以及具有 operator.read 的 Control UI 连接,会显示 报告 选项卡。它会在沙箱框架中嵌入报告页面。Gateway 会提供并续期一个作用域认证 cookie;报告 URL 中不会添加 Gateway token。
每个报告路由都需要 operator.read;operator.write 和 operator.admin 也满足该要求。Control UI 选项卡通过其作用域 cookie 授予 operator.read。CLI 的 Gateway RPC 方法已声明其所需的读取或生成作用域。
请使用 HTTPS、Tailscale Serve 或浏览器信任的回环源。LAN 主机名上的纯 HTTP 无法对框架进行身份验证。阻止所有第三方 cookie 的浏览器也可能使该选项卡不可用。
GitHub 和其他外部链接可能无法在沙箱框架内打开。每个页面都包含 在新窗口中打开,并带有该页面自身的 URL。如果浏览器也阻止该操作,请将链接复制到新选项卡中。Gateway 身份验证在那里仍然适用。
工作会话¶
概览会显示此 Gateway 上最近的 工作会话。打开 所有工作会话(或报告导航中的 工作会话)以分页查看当前会话列表。每个条目都链接到对话,并显示其当前所有者、运行状态以及(如果存在)项目。会话按最近活动排序。
每个人的历史页面以及每日、每周和每月报告中的每个成员部分也会显示 当前工作 / 拥有的会话,包括按人员筛选报告时。这些直接对话链接反映当前所有权,而不是历史报告窗口。所有拥有的会话 会打开一个分页目录,在分页之前先筛选到该成员。
成员匹配不区分大小写,使用其已配置和报告中的 GitHub 别名,与 Gateway 配置文件上链接的 GitHub 身份进行匹配。合并的配置文件会解析到其规范所有者。未链接或模糊的身份会与一个没有可见会话的已链接成员分开标注。显示名称从不用于推断所有权。
当你打开或刷新页面时,列表会使用你现有的会话权限读取。已归档、隐身、自动化、系统和隐藏的子代理会话会被排除。不会根据 GitHub 用户名或显示名称猜测会话所有者。 这是当前工作视图,而非历史贡献计数:它不会更改每日总计、模型摘要、Markdown 或 JSON 导出,或已存储的报告历史。会话记录不会被复制到报告数据库中。
在 Control UI 中,选择某个会话会通过宿主导航打开其聊天。在嵌入式标签页之外,会话链接是普通的 Control UI 链接。如果会话发现失败,页面会显示 工作会话不可用,而已存储的报告仍可使用。
页面镜像维护者报告站点布局:横幅和活动日期线、最新周期快速卡片、日/周/月历史、人员时间线,以及按人员划分的日历。生成面板显示调度器和源的健康状态。已关闭周期和部分周期保持区分,并在报告旁边显示覆盖率和摘要警告。
主题选择会通过页面片段(#theme=light 或 #theme=dark)跟随你在标签页内导航。在沙箱化的 Reports 标签页中,它仅持续该次访问。它仅在存储可用时按浏览器持久化,例如在独立窗口中。页面首先从片段选择主题,然后在可用时从浏览器存储选择,再选择操作系统的浅色或深色偏好,独立于 Control UI 主题。
相对时间和开放日倒计时通过一个小型内联脚本刷新,内容安全策略通过 nonce 允许该脚本。同一脚本启用历史切换、成员筛选和静默成员开关。页面在没有 JavaScript 时仍可工作:所有历史行和成员仍可用,并且时间戳具有服务器渲染的回退。
螃蟹艺术作品和图标从插件自身的 assets 路由提供,并经过与报告页面相同的身份验证和范围检查。这些资源使用私有的一日缓存;报告页面和导出保持不缓存。
名册成员和其他 GitHub 参与者显示来自 avatars.githubusercontent.com 的 GitHub 头像,使用主要 GitHub 登录名。图像延迟加载且不发送 referrer。当图像无法加载时,首字母缩写仍可见;无效登录名仅使用首字母缩写。显示名称和 Discord ID 从不用于构造头像 URL。页面打包其样式并使用系统字体,因此不需要外部样式表、Web 字体或脚本。
配置¶
以下所有键都位于 plugins.entries.team-reports.config 下。未知键会被拒绝。配置更改会以默认混合重载模式重新加载正在运行的插件;参见 热重载。密钥在报告服务启动时解析。轮换文件、exec 或存储密钥后,运行 openclaw plugins reload team-reports。环境更改需要使用更新后的环境重启 Gateway。
| 键 | 默认值 | 行为 |
|---|---|---|
basePath |
"/plugins/team-reports" |
使用字母、数字、.、_ 和 - 的非空路径段的绝对路由根。它不得使用 . 或 .. 段、/api/channels 前缀,或等于或位于显式配置的 Control UI 基础路径之下。尾部斜杠会被规范化移除。 |
displayTimezone |
"UTC" |
用于显示时间戳的 IANA 时区。报告窗口始终使用 UTC。 |
github |
必需 | GitHub 收集配置,如下所述。 |
discord |
未设置 | 可选的 Discord 收集配置。省略它则仅收集 GitHub。 |
people |
未设置 | 内联身份条目。与 peopleFile 互斥。 |
peopleFile |
未设置 | 指向最多 2 MiB 的常规 JSON 文件的绝对路径,形状为 { "people": [...] },并使用以下身份字段。 |
summaries |
以下默认值 | 模型选择和摘要启用。 |
schedule |
以下默认值 | UTC 收集时间和聚合刷新。 |
| 键 | 默认值 | 行为 |
|---|---|---|
retention.days |
400 |
在闭日运行后,删除存储时间超过此天数的报告;0 保留所有历史记录。 |
GitHub¶
| 键 | 默认值 | 行为 |
|---|---|---|
github.token |
必填 | 非空 Token 字符串或 SecretRef { source, provider, id }。Secret 来源为 env、file、exec 和 store。优先使用 SecretRef。 |
github.orgs |
必填 | 要收集的非空组织名称数组。 |
github.teams |
[] |
格式为 { org, slug } 的名册来源。 |
github.includeDirectCollaborators |
false |
将具有 push、maintain 或 admin 访问权限的直接仓库协作者添加到名册。 |
github.excludeRepos |
[] |
要跳过的 owner/name 形式仓库名称。归档仓库也会被跳过。 |
github.apiBaseUrl |
"https://api.github.com" |
HTTPS API 基础 URL;为 GitHub Enterprise Server 设置此项。 |
github.ignoreCommentPatterns |
[] |
正则表达式源字符串。匹配的 issue 评论和 PR 审查评论会被排除。无效模式会被拒绝。 |
Discord¶
以下是一个可选的部分配置示例。ID 仅用于说明:
```json5 validate=false discord: { token: { source: "env", provider: "default", id: "TEAM_REPORTS_DISCORD_TOKEN", }, guildId: "123456789012345678", channels: [ { id: "234567890123456789", excerpts: true }, { id: "345678901234567890" }, ], excerptMaxChars: 260, },
| 键 | 默认值 | 行为 |
| ----------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `discord.token` | 配置 Discord 时必填 | Bot Token 字符串或 SecretRef,形状与 `github.token` 相同。 |
| `discord.guildId` | 配置 Discord 时必填 | Guild ID。 |
| `discord.channels` | 配置 Discord 时必填 | 非空频道条目数组,每个条目包含 `id` 和可选的 `excerpts`。它们的线程也会被计入。 |
| `discord.channels[].excerpts` | `false` | 在报告和摘要证据中包含长度受限的消息摘录。当此项为 `false` 时,消息计数仍会计入。 |
| `discord.excerptMaxChars` | `260` | 每个摘录的最大字符数;`1` 到 `4000` 的整数。 |
### 人员与身份 {#people-and-identity}
名册会结合 GitHub 团队成员、活跃身份条目,以及在启用时加入的直接协作者。使用身份条目可将某人的 GitHub 别名和 Discord 用户 ID 关联起来:
```json5 validate=false
people: [
{
github: ["example-member", "example-member-old"],
display: "Example Member",
affiliation: "Example Company",
roleGroup: "core",
roleLabel: "Maintainer",
access: ["release"],
areas: ["documentation"],
discordUserId: "456789012345678901",
discordUsername: "example-member",
status: "active",
},
],
| 字段 | 必填 | 行为 |
|---|---|---|
github |
是 | 非空登录名数组。第一个登录名是主要身份;其余登录名是别名。 |
display |
否 | 显示名称;默认为主要登录名。 |
affiliation |
否 | 可选的所属单位标签。 |
| 字段 | 必填 | 行为 |
|---|---|---|
roleGroup |
否 | 组标签,例如 core、volunteer 或 readonly;接受自定义字符串。 |
roleLabel |
否 | 人类可读的角色标签。 |
access |
否 | 自由格式标签,例如 release 或 moderation;默认为空列表。这些标签不会授予权限。 |
areas |
否 | 负责领域;默认为空列表。 |
discordUserId |
否 | 用于将消息归属到该人员的 Discord 身份。 |
discordUsername |
否 | 可选的 Discord 用户名元数据。 |
status |
否 | active 或 archived;省略的条目为活动状态。已归档人员会从当前报告中排除,但存储的历史记录仍可用。 |
archivedAt |
否 | 归档日期,格式为 YYYY-MM-DD。 |
摘要¶
| 键 | 默认值 | 行为 |
|---|---|---|
summaries.enabled |
true |
生成由模型撰写的概述、亮点和按人员划分的摘要。false 使用确定性回退文本。 |
summaries.model |
未设置 | 请求的 provider/model 引用;否则使用目标代理的默认模型。需要下方主机策略才能生效。 |
summaries.reasoning |
未设置 | 请求的思考级别:off、minimal、low、medium、high、xhigh、adaptive、max 或 ultra。主机会针对所选模型对其进行规范化。 |
summaries.agentId |
未设置 | 使用其模型和凭据的代理。跨代理选择受主机 llm.allowAgentIdOverride 策略约束。 |
要允许使用已配置的摘要模型,请设置
plugins.entries.team-reports.llm.allowModelOverride: true。llm 对象
是 config 的同级项,而不是其中的字段:
```json5 validate=false "team-reports": { enabled: true, llm: { allowModelOverride: true }, config: { // Keep your github and identity configuration here. summaries: { enabled: true, model: "openai/gpt-5.6-sol", reasoning: "high", }, }, },
如果没有该显式选择,Team Reports 将使用目标代理的默认模型。
主机模型允许列表仍然适用。有关这些策略,请参阅
[插件 LLM 运行时](sdk-runtime.md)。
摘要基于有界证据摘要:总计、主要
仓库和频道、选定的活动项以及已选择加入的摘录。
它们描述观察到的活动,而不是推断绩效、雇佣关系
或私人事实。不活跃成员仍会保留在报告中,并附低活动说明。
插件会验证模型的 JSON 响应,并重试一次以修复
无效输出或缺失成员。如果重试失败,它会保留已收集的
报告,并显示带有可见回退横幅的确定性摘要。
输出预算随名册规模扩展;失败的模型尝试会在报告、Markdown 导出、最新一天状态和 Gateway 日志中包含一个有界的、不含凭据的原因。
未变化的证据会复用已存储的摘要,而不是再次调用模型。
收集会在摘要生成之前存储,摘要生成可能需要几分钟。
### 计划 {#schedule}
| 键 | 默认值 | 行为 |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `schedule.closedDayUtc` | `"00:05"` | 每日运行时间,格式为 `HH:MM` UTC,抖动前。生成昨天的已关闭报告和今天的部分报告。 |
| `schedule.intradayEveryHours` | `4` | 在对齐的 UTC 小时边界上刷新今天的报告;`0` 到 `24` 的整数。`0` 禁用日内运行。 |
| `schedule.jitterMinutes` | `5` | 添加到计划运行的最大随机延迟;`0` 到 `59` 的整数。 |
| `schedule.weekly` | `true` | 在每日收集后刷新当前 ISO 周的聚合数据。 |
| `schedule.monthly` | `true` | 在每日收集后刷新当前月份的聚合数据。 |
同一时间只执行一个运行。计划工作会等待活动运行;
当另一个运行处于活动状态时,手动生成会被拒绝。运行有
45 分钟截止时间。自动收集会在服务启动后至少等待五分钟。
该窗口内的日内边界会被跳过;到期落在窗口内的已关闭日
运行会等待到窗口结束。后续运行保持其常规节奏。
停止服务会取消其定时器,并最多等待
30 秒让活动工作完成,然后取消远程收集和摘要生成。
任何已在进行的数据库操作以及最终运行结果都会在存储关闭前完成。
## 理解报告窗口和计数 {#understand-report-windows-and-counts}
每日窗口从 UTC 午夜开始,到下一个 UTC 午夜结束,且结束时间不包含在内。今日报告会被标记为 **部分**。ISO 周从周一开始,并使用类似 `2026-W34` 的键;月份使用类似 `2026-08` 的键。
`displayTimezone` 仅更改时间戳标签,绝不会改变事件归属的报告。
周报和月报汇总已存储的日报。它们不会从 API 重新采集同一时间段。缺失的日期会产生源警告;在依赖汇总报告的完整性之前,请先生成缺失的日报。
当 UTC 日期跨越周期边界时,已关闭日运行还会完成包含昨天的那一周或月。
GitHub 合并活动计入合并该 PR 的人。提交计入作者以及每位已映射的合著者,每人只计一次。同一操作者和同一评论类型下的相同评论在窗口内只计一次。机器人活动会被排除,非成员的 GitHub 操作者会单独显示,且仅显示计数。
没有活动的成员仍会出现在名册中。
拉取请求评审提交(包括批准和请求修改正文)不会被采集;内联评审评论会被包含。
Discord 总数包含未映射的作者,但未匹配条目仅包含作者 ID 和计数,不包含消息内容。摘录仅来自启用了 `excerpts: true` 的频道,使用折叠空白,并每人保留最新的 8 条。当某人的 GitHub 或 Discord 计数不为零时,该人即为活跃。
报告每人最多保留 200 条 GitHub 项目和 8 条 Discord 摘录,汇总顶级项目最多 80 条。存储的报告 JSON 上限为 2 MiB;项目列表会按确定性方式截断,优先保留最新项目,并且报告会标明已截断。因此,计数可能超过显示的项目数。
## CLI 和导出 {#cli-and-exports}
CLI 与正在运行的 Gateway 通信,支持 `--json` 以及标准
[Gateway 客户端选项](../cli/gateway.md)。读取需要 `operator.read`;
生成需要 `operator.admin`。
```bash
openclaw team-reports status --json
openclaw team-reports list --json
openclaw team-reports show day 2026-08-20
openclaw team-reports show week 2026-W34 --markdown
openclaw team-reports generate --date 2026-08-20
openclaw team-reports generate --intraday
在未指定日期或 --intraday 时,生成会选择昨天。--intraday
选择今天;--date 接受过去的某一天或今天。今日报告仍为部分状态。
未来日期,或将 --intraday 与过去的日期组合使用,都会被拒绝。
侧边栏中的 Reports 选项卡会在 Control UI 外壳中打开 /reports,并前置任何
已配置的 Control UI 基础路径。固定 basePath: "/reports" 会遮蔽
根挂载的 Control UI /reports 页面,因此侧边栏会回退到通用的
/plugin?plugin=team-reports&id=team-reports 选项卡 URL。
在默认 basePath 下,经过身份验证的读者可以使用:
| 路径 | 结果 |
|---|---|
/plugins/team-reports/ |
报告索引和近期活动趋势。 |
/plugins/team-reports/latest/ |
重定向到最新的已关闭日报。 |
/plugins/team-reports/day/<key>/ |
每日 HTML 报告;将 day 替换为 week 或 month 以获取汇总报告。 |
/plugins/team-reports/day/<key>/report.md |
Markdown 导出;周和月也可用。 |
/plugins/team-reports/day/<key>/data.json |
结构化报告;周和月也可用。 |
/plugins/team-reports/sessions/ |
当前工作会话,并包含指向其对话的链接。 |
/plugins/team-reports/people/ |
名册索引。 |
/plugins/team-reports/people/<login>/ |
每个人的历史记录、日历和 30 天趋势。 |
/plugins/team-reports/index.json |
最新键和已存储周期索引。 |
/plugins/team-reports/status |
以 JSON 形式提供运行状态、计划和源警告。 |
报告和导出路由仅接受 GET 和 HEAD,并发送 Cache-Control: private,
no-store。请使用 CLI 或经过身份验证的 Gateway 方法生成报告;
读取报告页面不会触发采集。
报告和运行记录保存在插件拥有的数据库中,路径为
<state-dir>/plugins/team-reports/team-reports.sqlite。插件在禁用或重启时会关闭它。
保留策略在已关闭日生成后运行;
设置 retention.days: 0 可保留所有报告历史。
故障排除¶
Reports 选项卡缺失或不可用。 请确认插件已启用,
如果存在 plugins.allow 则已被其允许,并且 Control UI 会话具有
operator.read。配置更改会自动重新加载插件。如果修复配置后仍不可用,请运行 openclaw plugins reload team-reports。
如果 iframe 不可用,请检查 HTTPS 或受信任的环回访问以及第三方 Cookie 策略。
还没有报告。 运行 openclaw team-reports status --json。首次
自动采集会等待其计划时间,并且采集或模型调用可能仍在运行。
使用 generate --intraday 生成今日的部分报告。/latest/ 至少需要
一个已关闭的日报。
某个源存在警告或报告看起来不完整。 请阅读状态和报告中的警告。
失败运行的错误会指明每个受影响的周期和源
(例如 day/2026-08-20/github)。请检查 GitHub token 访问权限、组织/团队名称、
排除的仓库,以及 Discord 机器人对每个已配置频道及其历史的访问权限。
速率限制可能会延迟运行。待访问权限或速率限制恢复后,重新生成受影响的日期,
然后刷新汇总。轮换文件、exec 或存储密钥后,运行 openclaw plugins reload team-reports;环境更改
需要使用更新后的环境重启 Gateway。
仓库建议是可选的。返回 HTTP 403 或
404 的建议请求会计入 GitHub 源统计中的 advisoriesSkipped,而不会添加
警告或将当天标记为陈旧。速率限制响应仍会等待并重试;
其他建议失败会保留其警告。
Discord 采集包括活跃和已归档的线程,包括论坛和
媒体帖子。私有归档需要 MANAGE_THREADS 和
READ_MESSAGE_HISTORY;如果 Discord 返回 HTTP 403,采集会回退到
机器人已加入的私有线程,并使用 READ_MESSAGE_HISTORY。
如果两个私有归档端点都返回 HTTP 403,该频道会计入
Discord 源统计中的 privateArchivesSkipped,没有警告或陈旧
状态;其他失败会保留其警告。
机器人无法访问的私有线程不在报告覆盖范围内。
长时间运行会在成员名单、仓库、issue 搜索、提交、评论/建议以及 Discord 采集阶段
完成时,于 Gateway 日志中输出 team-reports: 进度行。这些行包含计数和提交策略,不包含 tokens 或
消息内容。
成员缺失或 Discord 活动未匹配。 检查 GitHub
团队成员名单和身份条目。将别名放在同一个 github 数组中,
使用此人的 Discord 用户 ID,并确保该条目未被归档。
仅 discordUsername 不会将消息映射到某个人。
摘要显示回退横幅或忽略请求的模型。 检查
目标代理的身份验证和默认模型、摘要设置以及主机
LLM 策略。请求的模型需要在 config 外部设置 llm.allowModelOverride: true。当模型被禁用、
不可用或返回无效输出时,回退文本会保留报告。
生成提示已有运行处于活动状态。 检查 status 并等待
该运行的结果。调度器会防止重叠的采集,并且每个
运行都受其截止时间约束。
另请参阅:插件配置、 Control UI 和 密钥管理。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw