概览

PullStar 为一名工程师拉取 GitHub 活动数据（包括其创建的 PR 和给出的评审），在五个维度上运行确定性的本地评分引擎，并准备一份供 LLM 使用的输入载荷。随后，agent 执行 LLM 推理，并完成最终简报（brief）。

快速开始：

run_brief.py --login steipete --pr-insights --days 7
读取 llm_input_steipete.json，执行 LLM 推理，输出简报

数据流概要：

⚠️ 重要提示： 步骤 1–3 全部在本地运行。仅第 4 步（LLM 推理）会将数据发送至您的 AI 提供商。

系统要求

• Python 3.11+
• 安装依赖： pip install PyGithub python-dotenv requests
• 一个 GitHub 个人访问令牌（详见下方“安全与隐私”章节）

安全与隐私

令牌权限范围

细粒度 PAT 不支持跨任意用户的搜索。如需生成组织级简报，请使用经典 PAT。

设置 GITHUB_ORG 环境变量可将搜索范围限定于单个组织。

令牌解析顺序

密钥按层级查找，**首个匹配项生效**：

1. --github-token CLI 参数（仅用于覆盖或调试 — 绝不记录日志）
2. GITHUB_TOKEN 环境变量
3. ~/.pullstar/credentials（key=value 格式）
4. 技能目录下的 .env 文件

按模式划分的数据隐私策略

默认模式（未启用 --pr-insights）：

• 仅向 LLM 发送聚合统计值与评分结果
• 不包含原始 PR 文本、评论或评审正文

PR 洞察模式（启用 --pr-insights）：

• 将受限的原始 PR 讨论文本打包进 LLM 提示词中
• 限制为最多 5 个 PR，每个 PR 最多含 3 条评审/评论，每条内容不超过 600 字符
• 若您关注隐私，请在 LLM 推理前审阅 llm_input_{login}.json

配置

.env

使用方法

标准运行

python run_brief.py --login jsmith

启用 PR 洞察

python run_brief.py --login jsmith --pr-insights

常用选项

python run_brief.py --login jsmith --days 14          # 更长回溯窗口（默认：5 天）
python run_brief.py --login jsmith --max-results 10   # 高活跃用户下提速（默认：20）
python run_brief.py --login jsmith --api-mode rest    # 强制使用 REST API（默认：graphql）

全部选项

Agent 工作流

run_brief.py 运行确定性流水线（采集 → 评分 → 准备），然后打印一段明确的操作指令块。Agent 必须手动完成最后两个步骤：

============================================================
PIPELINE COMPLETE — AGENT ACTION REQUIRED
============================================================

  1. 读取：   .pullstar/llm_input_jsmith.json
  2. 提取其中的 "system" 和 "user" 字段
  3. 使用这两个字段分别作为 system prompt 和 user message 调用您的 LLM
  4. 将响应结果写入 .pullstar/llm_output_jsmith.json
  5. 运行：    python scripts/agent_finalize_1on1.py --login jsmith

Agent JSON 接口规范

输入（来自 run_brief.py）

文件路径：.pullstar/llm_input_{login}.json

输出（由 Agent 生成）

文件路径：.pullstar/llm_output_{login}.json

{
  "version":        "1.0",
  "engineer_login": "jsmith",
  "brief":          "## Quick Summaryn..."
}

格式要求：

• 合法 JSON 格式
• brief 字段必须是非空的 Markdown 字符串
• 也接受纯文本 — 整个文件内容将被直接用作简报正文

简报输出格式

最终简报文件（output_{login}.json）是一份 Markdown 文档，包含以下六个部分：

评分汇总表示例：

产物文件

所有产物均写入 .pullstar/ 目录（该目录已加入 .gitignore，永不提交）。

故障排查

“GitHub 拒绝了 PR 搜索请求（422）”
请使用经典 PAT — 细粒度 PAT 不支持跨任意用户的搜索。

“触发 GitHub 速率限制”
认证后：5000 次请求/小时；未认证：60 次请求/小时。请设置 GITHUB_TOKEN。

高活跃用户下采集缓慢
使用 --max-results 10 限制迭代数量。默认值为 20。

GraphQL 报错
使用 --api-mode rest 回退至传统 REST API。

面向 Agent 开发者的说明

子 Agent 最佳实践（勿做焦虑型家长）

当在 LLM 推理步骤中使用 sessions_spawn 时：

✅ 应当：

• 仅调用一次 sessions_spawn，任务为：读取 llm_input_{login}.json 并写入 llm_output_{login}.json
• 信任“自动完成即广播”的行为机制 — 您将收到 completion 事件
• 在事件到达后处理结果

❌ 不应：

• 在紧循环中反复轮询 subagents list 等待完成
• 为同一任务启动多个子 Agent
• 每隔几秒就检查一次状态 — 浪费资源

原因： 子 Agent 轻量高效（无完整 OpenClaw 上下文，环境隔离），但轮询违背了基于事件推送完成的设计初衷。系统会在任务完成后主动通知您。

恢复方案： 若子 Agent 执行失败，您始终可在主会话中直接生成简报 — 上述 JSON 接口规范简洁明确，且已完整文档化。

许可证

MIT 协议 — 完整许可文本请参阅源代码仓库。