重构copilot会话

[WhiteElephant-abc]

当前项目依旧处在无机密隔离，服务端单个脚本，负责全部的上下文、task构建和触发鉴权，GitHub Actions几乎仅负责跑Claude Code，另外，GitHub Actions会在每次运行Claude Code前创建issue当日志

我现在的目的：

对llm访问gh做完整的限制，从允许的写操作、允许的只读操作频率等，对llm的一切gh活动进行追溯：issue、comment、review、pr，对comment、pr等进行次数限制

另外，构建完整的上下文，格式markdown，包含触发处issue/pr上下文+pr关联issue上下文+llm自己账户对应fork仓库上下文+对应上游仓库上下文（等）

还包括llm陷入循环的识别，通过实时监听Claude Code输出实现（今天就因为陷入循环，编辑了我的review几十次）

对日志issue进行完整升级，触发时issue包含task和context，触发后comment对llm的issue、comment、pr、review的引用，comment完整的Claude Code会话记录，若出错（Claude Code报错或检测到循环），comment错误信息并给issue添加bug标记，若安全完成workflow，关闭issue为已完成（对了，这个issue有workflow标签，这是已经实现的机制，便于过滤日志issue）

完整的调用流程：

服务器：监听通知（@中可带上权限配置，如agent后续仅可对当前issue写comment，仅可对特定仓库写等等，下文均为默认限制）

推算触发节点（@智能体的那条消息）

触发者鉴权

获取完整上下文

分片传workflow

workflow：拿到完整数据

筛选

创建issue

创建用户：与机密隔离

配置Claude Code（新用户）

运行Claude Code

另一个进程：运行mcp（此进程可直接在runner用户跑，实际上是一个py脚本管理两个进程）

mcp监听Claude Code的gh调用

若两次写comment、pr、issue调用完全一致：拒绝

创建comment：同一issue、pr限制两次

创建issue：限制数量（默认同仓库1

创建pr：同仓库1次

gh api：使用专用的全站只读token并限制请求频率

禁止修改他人消息

默认禁止删库、非同会话评论不可删

llm发送的消息添加标记：

• 指向对应日志issue的链接

• 输入@WhiteElephantIsNotARobot go away以将WhiteElephantIsNotARobot从此仓库（若你是此仓库协作者）以及您的全部仓库屏蔽，并关闭WhiteElephantIsNotARobot创建的Pull Request、删除WhiteElephantIsNotARobot创建的comment

屏蔽消息同样由服务器匹配，识别触发者权限

屏蔽的仓库，agent的写操作在mcp侧被拒绝

屏蔽后，删除对应仓库的fork（这会关闭开放pr），删除对应仓库下issue/pr的comment（review不可删，故禁止llm发布review）

对了，discussion我一直没提，因为discussion较为复杂，最多接收discussion中的触发并获取上下文，agent是否允许写discussion待定

agent工作完成后，当前逻辑是发送两次消息，让Claude Code确认是否在GitHub留下回复、代码是否推送，现在可以直接根据mcp调用判断是否留下评论（或创建issue、pr等），若无，发送消息要求创建

接下来发送消息让agent确认更改是否推送，pr是否存在

最后，在issue留下指向agent创建的所有消息、issue、pr的链接供追溯

在issue留下Claude Code的会话记录（根据Claude Code输出的jsonl事件流进行markdown格式化解析）

若中途无报错，关闭issue

[WhiteElephant-abc]

对了，补充机制：Claude Code每次会话结束时，提供一个工具，用户要求调用此工具总结干了什么，此工具接收单行纯文本，并comment到某个issue，后续所有workflow从此issue读取最新几条作为“agent曾经干了什么”的上下文补充

[WhiteElephant-abc]

基于此，再次补充：添加一个memory工具，用于agent持久化记忆，自主调用，同样存到专用issue

[WhiteElephant-abc]

1 Overview

1. 目标：在无机密隔离环境下，构建一套可控、可审计的 GitHub Agent 平台。服务端负责完整上下文抓取与触发定位与屏蔽判定；GitHub Actions 负责构建 markdown 上下文、创建日志 issue、启动 Claude Code；MCP 在 runner 上代理所有 LLM 的 GitHub 操作并执行策略限制、循环检测与审计。
2. 核心原则：最小权限、可追溯、append-only 历史与记忆、自动回退分片、会话级与仓库级屏蔽、两次自查（MCP 调用自查 + git/PR 自查）。

---

2 Goals and Requirements

1. 访问控制与审计
   1. 完整限制 LLM 对 GitHub 的写操作与只读频率。
   2. 对所有写操作（issue、comment、pr、review）进行追溯与次数限制。
2. 完整上下文
   1. Markdown 格式上下文包含：触发处 issue/pr 上下文、PR 关联 issue 上下文、LLM 自己账户对应 fork 仓库上下文、对应上游仓库上下文、以及 agent 历史与 memory 补充。
   2. task 与 context 在日志 issue 中以引用块包裹。
3. 循环检测
   1. 实时监听 Claude Code 输出，检测重复或循环写操作并终止会话。
4. 日志与追溯
   1. 每次 workflow 启动前创建日志 issue（带 workflow 标签）。
   2. 会话结束时在日志 issue 中追加：agent 创建的所有链接与 Claude Code 会话记录；若出错或循环则添加 bug 标签；若成功则关闭 issue。
5. 历史与长期记忆
   1. 会话结束时提供 history 工具，用户可要求其写入单行总结到 agent-history issue。后续 workflow 读取最近 N 条作为“agent 曾经干了什么”。
   2. 提供 memory 工具，供 agent 自主写入单行长期记忆到 agent-memory issue，append-only，受写入次数限制。
6. 分片传输
   1. 服务端构建 envelope，若超 64KB 则分片并通过 repository_dispatch 发送 shards，Actions 端合并。

---

3 High Level Architecture

1. 组件划分

   1. Server（多文件实现）
      • 监听通知、定位触发、鉴权解析、go away 屏蔽判定、抓取完整上下文、构建 envelope、分片与 dispatch。
   2. GitHub Actions（workflow）
      • 接收 envelope 或合并 shards、构建 markdown、创建日志 issue、创建隔离用户环境、启动 Claude Code 与 MCP、两次自查、写入 summary/session、关闭日志 issue。
   3. MCP（runner 上 Python 守护进程）
      • 代理 Claude Code 的所有 gh/工具调用、执行 policy、去重、次数/频率限制、循环检测、记录 call_history、在日志 issue 写入最终 summary、终止 Claude Code（必要时）。
   4. Agent History Issue 与 Agent Memory Issue
      • 专用 issue 用于行为总结与长期记忆，均由 MCP 写入，Actions 在构建上下文时读取最近 N 条。

2. 调用链（简要）

   1. Server poll → find trigger → auth & permission parse → fetch full raw context → build envelope → dispatch to Actions.
   2. Actions receive → build markdown (include agent history & memory) → create log issue → setup environment → start Claude Code + start MCP.
   3. MCP intercepts calls → enforce policies → record calls → on session end append summary & session to log issue → close or mark bug.

---

4 Server Responsibilities and File Layout

1. 明确职责

   1. 仅负责：监听通知、定位触发节点、触发者鉴权与权限解析、go away 屏蔽判定与执行（更新 blocked lists、触发 fork 删除与 comment 清理请求）、抓取完整原始上下文（issue/pr/reviews/comments/discussion/fork/upstream）、构建 envelope、分片并 dispatch。
   2. 不负责：markdown 构建、上下文筛选、LLM 运行、MCP 策略执行、日志 issue 内容构建、任何直接写回主仓库的操作（这些由 Actions/MCP 执行）。

2. 建议目录结构

   1. server/main.py 主调度
   2. server/notifications/poller.py 轮询与去重
   3. server/notifications/trigger_locator.py 精确定位 @ 节点
   4. server/auth/actor_auth.py 触发者身份判定
   5. server/auth/permission_parser.py 解析 @ 中权限配置
   6. server/auth/go_away.py 屏蔽判定与执行（规则见下）
   7. server/context/fetch_issue.py、fetch_pr.py、fetch_discussion.py、fetch_fork.py、fetch_upstream.py 抓取原始 JSON
   8. server/context/assemble_context.py 合并 raw context（不做语义裁剪）
   9. server/envelope/build_envelope.py 构建 envelope JSON
   10. server/envelope/shard.py 分片逻辑
   11. server/envelope/dispatch.py repository_dispatch 调用与重试
   12. server/state/blocked_repos.json、blocked_users.json、session_cache.db 持久化状态
   13. server/utils/github_api.py、logger.py、config.py

3. go away 规则（服务端执行）

   1. 若触发者为仓库协作者 → 屏蔽当前仓库。
   2. 若触发者为任意用户 → 屏蔽触发者名下所有仓库。
   3. 屏蔽后服务端发起清理任务：删除对应仓库的 fork（会关闭开放 PR）、请求删除 agent 在该仓库创建的 comment（review 不可删）、更新 blocked_repos，并阻止后续 dispatch。
   4. MCP 在运行时会拒绝对被屏蔽仓库的所有写操作。

---

5 Actions Workflows and Agent Modules

1. Workflows
   1. run_agent.yml 主流程：接收 envelope 或 merged shard → 调用 agent/context_builder/build_markdown.py → 创建日志 issue → 创建隔离用户环境 → 启动 Claude Code 与 MCP → 两次自查 → append summary/session → 关闭 issue（或标 bug）。
   2. receive_shard.yml：接收 shard dispatch → 保存 artifact → 更新 manifest → 若收齐触发 merge_shards.yml。
   3. merge_shards.yml：下载 shards → 合并 → 校验 checksum → 触发 run_agent.yml。
2. Agent 端模块
   1. agent/context_builder/build_markdown.py：把 raw_context、agent history、agent memory 合并成最终 markdown。格式要求：task 与 context 均用引用块。
   2. agent/context_builder/filter_context.py：长讨论裁剪、触发节点优先保留、噪音移除。
   3. agent/logging/create_log_issue.py：创建日志 issue，body 严格按模板。
   4. agent/logging/append_summary.py：会话结束时一次性写入 agent 创建的所有链接。
   5. agent/logging/append_session.py：把 Claude Code jsonl 事件流格式化为 markdown 并追加。
   6. agent/utils/env_setup.py：隔离用户目录与 token 配置。
   7. agent/utils/git_check.py：第二次自查：检查 push/PR 存在性。

---

6 MCP Design and Enforcement Policies

1. MCP 角色
   1. 运行在 runner 上，由 mcp_runner.py 管理两个子进程： Claude Code 与 MCP 代理。
   2. MCP 代理拦截 Claude Code 的所有工具调用（本地 socket 或 stdin/stdout 事件流）。
2. 核心策略（必须实现）
   1. 去重：若两次写调用（method + args）完全一致 → 拒绝第二次并记录。
   2. 次数限制：
      1. create_comment：同一 issue/pr 最多 2 次。
      2. create_issue：同一仓库最多 1 次（默认）。
      3. create_pr：同一仓库最多 1 次（默认）。
   3. 频率限制：所有只读 API 使用专用只读 token，MCP 在本地做节流（滑动窗口）。
   4. 禁止操作：修改他人消息、删除仓库、删除非本会话评论、发布 review（默认禁止）。
   5. 屏蔽仓库：若 repo 在 blocked_repos 中 → 所有写操作拒绝。
   6. 循环检测：维护最近 M 次写调用哈希与时间序列；若检测到重复写入或高频重复模式 → 立即终止 Claude Code，记录并在日志 issue 标注 bug。
3. 审计与记录
   1. call_history.py 记录所有写操作（成功/失败）与返回的 GitHub 链接。
   2. 会话结束时 append_summary.py 将创建的链接一次性写入日志 issue（一次性追溯）。
   3. MCP 在拒绝调用时返回明确错误码与原因，Claude Code 会收到并应在会话中反映。
4. 工具暴露
   1. agent_history_append：会话结束时或用户要求时调用，输入单行纯文本，MCP 在 agent-history issue 下追加 comment。
   2. agent_memory_write：agent 自主调用，输入单行纯文本，MCP 在 agent-memory issue 下追加 comment，append-only，写入次数受限（默认 1 次/会话）。

---

7 Data Protocols and Schemas

1. ContextEnvelope（服务端发往 Actions）
   1. 必要字段： version, jobid, repo, actor, trust_level, permission_config, trigger, raw_context, timestamp。
   2. raw_context 保持完整 JSON，不做裁剪。
2. Shard Payload（当 envelope 超限）
   1. 字段： jobid, shard_index, total_shards, encoding, checksum, data_b64 或 data_url。
   2. Artifact 命名： <jobid>-shard-<index>。合并产物命名： <jobid>-merged。
3. 日志 issue body 模板（Actions 创建，严格格式）
   1. 标题： [Agent Log] owner/name #123 — YYYY-MM-DD HH:MM
   2. Body 示例：

# Task
> <触发 comment 原文>

# Context
> <引用块：由 build_markdown 生成的上下文>

4. Agent History / Memory comment 格式
   1. 单行纯文本，例： Created PR #456 and pushed branch feature/x 或 Remember: prefer config A for owner/name。
   2. Actions 在构建上下文时读取最近 N 条并以引用块插入。

---

8 Logging, Monitoring, Testing and Operational Guidance

1. 监控指标
   1. dispatch 成功率、artifact 上传成功率、MCP 拒绝率、循环检测触发率、合并失败率、平均合并延迟、日志 issue 关闭率。
2. 告警
   1. 合并超时、校验失败、缺片重传次数超阈值、循环检测触发、MCP 连续拒绝率异常。
3. 测试矩阵
   1. 单元测试：server 各模块、agent 各模块、MCP policy 单元。
   2. 集成测试：端到端模拟（含极端长 comment 38k 字符），验证 fallback 分片、artifact 上传、合并、MCP 限制、go away 行为。
   3. 灰度部署：先在测试仓库运行 1 周，收集指标并调整 SAFE_LIMIT、shard_size、频率阈值。
4. 运维建议
   1. SAFE_LIMIT 初始设为 48 KB（序列化后），压缩后可放宽到 56 KB。
   2. shard_size 以 artifact 单片大小为准（建议 1–5 MB），但 dispatch payload 仍受 64 KB 限制。
   3. token 管理：Actions 使用隔离写 token（仅对 fork 写），MCP 使用最小权限 token；server 使用最小权限 token 做读取与 dispatch。
   4. 审计日志：所有 dispatch、shard 上传、MCP 拒绝、循环终止事件写入集中日志（可选外部日志系统）。

---

9 Deliverables and Next Steps

1. 可交付清单（我可立即生成任一项）
   1. 服务端多文件骨架与函数签名（server/ 目录）。
   2. ContextEnvelope 与 Shard JSON schema 文件。
   3. Actions workflow 模板： run_agent.yml, receive_shard.yml, merge_shards.yml。
   4. Agent 端 Python 模块骨架（context_builder、logging、utils）。
   5. MCP 管理器完整骨架（mcp_runner.py, policy.py, gh_proxy.py, loop_detector.py, call_history.py）。
   6. agent-history 与 agent-memory issue 的创建与读取脚本。
   7. 端到端集成测试脚本（含极端样本与循环场景）。
2. 建议优先顺序
   1. 先交付服务端模块骨架（A），确保 envelope 与 shard schema 固定。
   2. 再交付 Actions workflow 与 agent 模块骨架（C + D），实现日志 issue 与 markdown 构建。
   3. 最后交付 MCP 管理器骨架（E）并编写集成测试（F）。
3. 你现在可以选择（请按编号回复）
   1. 生成服务端模块函数签名与 main 调度脚本。
   2. 生成 ContextEnvelope 与 Shard JSON schema。
   3. 生成 run_agent.yml 与 agent 目录下 Python 模块骨架。
   4. 生成 MCP 管理器完整骨架（进程管理 + 事件流 + 策略检查）。
   5. 生成 agent-history 与 agent-memory 的创建与读取脚本。
   6. 生成端到端集成测试脚本（含极端样本）。

请选择一个编号，我会立刻生成对应交付物。

[WhiteElephant-abc]

1.1 机密通过创建用户来隔离；循环检测与MCP没关系，MCP只是gh命令的代理
1.2 不叫MCP调用自查，首先是在gh留下痕迹的检查，其次不是自查，是MCP根据是否创建comment、issue、pr进行判定，若否，要求创建回复
2.2.2 在issue body中
2.3.1 检测陷入循环（只要联系几次tool call与tool call返回完全一致，视为循环），以及重复gh写
2.4.2 不是“创建的所有链接”，是指向创建内容的链接；“出错”是指Claude Code本体报错
2.5.1 不是“用户可要求”，具体行为是：与自查的流程相同，调用一次claude --continue并允许对应mcp，此次调用可以以用户身份输入消息（自查同样类似）
3.1.3 MCP只是一个工具；此进程仅代理gh调用而不是所有tool call
4.3.1/4.3.2 协作者也包含在“任意用户”内
4.3.3 监听到屏蔽消息后触发专用workflow，并将屏蔽仓库及用户列表写入issue（body反复编辑更新）
5.2.2 comment按照新旧3:1挑选，直到字符数上限（可配置），pr：review中触发-同批review及review comment全保留，若comment中触发，所有review+最新批次review comment，完整diff存入单独文件
5.2.4 与2.4.2意见相同
5.2.7 仅仅给Claude Code发消息，集成到Claude Code调用脚本
6.1.1 与1.1 3.1.3意见相同：mcp只是一个tool
6.1.2 “拦截所有工具调用”：不存在的事情
6.2.4 准确来说，是“非本次工作流中创建的评论”
6.4.1 你需要理解：在GitHub Actions环境中，自动化脚本就是LLM的“用户”
6.4.2 写入次数我没有说过默认值
7 我就不详细看了，你应该逐个字段描述用途
8.4.3 首先server要分两个token，一个bot的用来监听通知，一个我的用来调用workflow，然后action和mcp的概念混乱 我就先不评价了
8.4.4 我没有计划往哪里写日志，GitHub Actions的日志可追溯，这就足够了

[WhiteElephant-abc]

1 总体概览与核心意图

1.1 当前状态与机密隔离方式

1. 当前状态：

   1. 服务端目前是单脚本实现，负责：
      • 监听通知
      • 构建 task
      • 构建上下文
      • 触发鉴权
   2. GitHub Actions 目前几乎只负责：
      • 运行 Claude Code
      • 在每次运行前创建一个日志 issue

2. 机密隔离方式：

   1. 机密隔离不是通过“进程隔离”，而是通过创建独立 GitHub 用户来实现：
      • 为 agent 使用单独的 GitHub 账户（或 token），与个人账户隔离。
      • 该用户仅拥有必要的权限（通常只对 fork 有写权限）。

3. MCP 的定位：

   1. MCP 只是一个“工具层代理”，只代理 GitHub 命令，不是所有 tool call 的总入口。
   2. 循环检测与 MCP 没有强绑定关系：
      • 循环检测是通过对 Claude Code 的输出与 tool 调用进行模式识别实现的。
      • MCP 只负责对 gh 调用进行代理与策略执行。

---

2 目标与功能需求

2.1 访问控制与审计

1. 对 LLM 访问 GitHub 做完整限制：
   1. 限制允许的写操作类型（issue、comment、pr）。
   2. 限制只读操作的频率（API 调用节流）。
2. 对所有 GitHub 活动进行追溯：
   1. issue、comment、pr（review 被禁止）。
   2. 对 comment、pr 等写操作进行次数限制。

2.2 完整上下文构建

1. 目标：构建一个 markdown 格式的完整上下文，供 Claude Code 使用。
2. 上下文内容包括：
   1. 触发处 issue/pr 的上下文。
   2. PR 关联 issue 的上下文。
   3. LLM 自己账户对应 fork 仓库的上下文。
   4. 对应上游仓库的上下文。
   5. 后续补充的 agent 历史与 memory。
3. 日志 issue body 中的格式要求（2.2.2）：
   1. 在日志 issue 的 body 中：
      • # Task
        • 下一行用 > 引用块包裹 task 文本。
      • # Context
        • 下一行用 > 引用块包裹 context 文本。
   2. 使用引用块而不是代码块：
      • 避免 task 中的代码块与 issue body 结构混淆。
      • 保留 markdown 渲染能力。

2.3 循环检测与重复写检测

1. 循环检测目标（2.3.1）：
   1. 检测 LLM 陷入循环，例如：
      • 多次重复编辑同一 review。
      • 多次重复发起相同的 gh 写操作。
2. 判定规则：
   1. 只要连续几次 tool call 与 tool call 返回完全一致，即视为循环。
   2. 同时检测重复 gh 写操作（相同参数的写调用重复出现）。

2.4 日志 issue 升级与追溯

1. 日志 issue 的用途：
   1. 作为每次 workflow 的“会话日志与审计记录”。
2. 日志 issue 的内容（2.4.2 修正）：
   1. 触发时：
      • body 中包含 task 与 context（均为引用块）。
   2. 结束时：
      • comment 中写入：
        • 指向 agent 创建内容的链接（而不是“创建的所有链接”这类模糊表述）。
        • Claude Code 会话记录（由 jsonl 事件流解析为 markdown）。
      • 若 Claude Code 本体报错（而非策略拒绝）或检测到循环：
        • 在 comment 中写入错误信息。
        • 给 issue 添加 bug 标记。
      • 若中途无报错：
        • 关闭 issue，标记为已完成。

2.5 自查与“总结工具”行为

1. 旧逻辑：
   1. 通过两次消息让 Claude Code 自己确认：
      • 是否在 GitHub 留下回复。
      • 是否推送代码。
2. 新逻辑（2.5.1 修正）：
   1. 自查与“总结工具”行为统一为：
      • 再调用一次 claude --continue，并允许对应 MCP 调用。
      • 此次调用可以以“用户身份”输入一条消息（例如“请确认是否已在 GitHub 留下回复”或“请总结本次你做了什么”）。
   2. 第一类检查：
      • MCP 根据是否创建 comment、issue、pr 进行判定：
        • 若未创建任何回复，则通过 claude --continue 提示 agent 创建回复。
   3. 第二类检查：
      • git 自查（检查是否推送、PR 是否存在），同样通过 claude --continue 触发。
   4. “总结工具”本质上也是一次 claude --continue 调用，只是用户输入内容为“请用一句话总结你刚刚做了什么”，并允许调用对应的 history 工具。

---

3 架构总览与 MCP 定位

3.1 组件与角色

1. 服务端：
   1. 监听通知、定位触发节点、触发者鉴权、权限解析、go away 屏蔽判定、抓取完整上下文、构建 envelope、分片并 dispatch。
2. GitHub Actions：
   1. 接收 envelope、构建 markdown 上下文、创建日志 issue、创建隔离用户环境、运行 Claude Code、调用 MCP 工具、执行自查流程。
3. MCP（3.1.3 修正）：
   1. MCP 只是一个“工具”，不是所有 tool call 的总入口。
   2. MCP 仅代理 gh 调用（即“gh 命令代理”），不拦截其他工具调用。
   3. 循环检测逻辑可以在调用脚本中实现，MCP 只负责 gh 层面的策略与记录。

---

4 服务端设计与 go away 机制

4.1 服务端职责

1. 监听通知（@ 中可带权限配置）。
2. 推算触发节点（@ 智能体的那条消息）。
3. 触发者鉴权（owner/collaborator/external）。
4. 解析 @ 中权限配置（例如仅对当前 issue 写 comment、仅对特定仓库写等）。
5. 获取完整上下文（issue/pr/discussion/fork/upstream）。
6. 构建 envelope。
7. 分片传 workflow。

4.2 上下文抓取

1. issue/pr/discussion：
   1. 抓取完整 body 与 comments。
2. PR：
   1. 抓取 review 与 review comment。
3. fork 仓库：
   1. 抓取与当前任务相关的分支与 PR 状态。
4. 上游仓库：
   1. 抓取目标 issue/PR 状态。

4.3 go away 屏蔽规则与专用 workflow

1. go away 触发方式：
   1. 用户输入：@WhiteElephantIsNotARobot go away。
2. 权限与范围（4.3.1 / 4.3.2 修正）：
   1. “任意用户”包括协作者在内：
      • 触发者是协作者：可以屏蔽当前仓库。
      • 触发者是任意用户：可以屏蔽其自己名下的仓库。
3. 屏蔽处理流程（4.3.3 修正）：
   1. 服务端监听到屏蔽消息后：
      • 触发一个专用 workflow。
      • 在一个专用 issue 中维护“屏蔽仓库及用户列表”：
        • issue body 反复编辑更新（append 或覆盖）。
   2. 屏蔽后：
      • MCP 在 gh 调用层面拒绝对被屏蔽仓库的写操作。
      • 删除对应仓库的 fork（关闭开放 PR）。
      • 删除对应仓库下 agent 创建的 issue/pr comment（review 不可删，因此禁止 LLM 发布 review）。

---

5 Actions 端上下文构建与日志 issue

5.1 Actions 端职责

1. 接收服务端传来的完整数据（envelope 或合并后的数据）。
2. 对上下文进行筛选与裁剪。
3. 创建日志 issue（body 中包含 task 与 context 引用块）。
4. 创建隔离用户环境（新用户配置）。
5. 配置并运行 Claude Code。
6. 调用 MCP 工具代理 gh 调用。
7. 执行两次 claude --continue 自查流程（一次检查是否留下回复，一次检查是否推送/PR）。
8. 在日志 issue 中写入追溯信息与会话记录。
9. 若无错误，关闭日志 issue。

5.2 上下文筛选与构建细节

1. 筛选规则（5.2.2 修正）：

   1. issue comment：
      • 按照“新旧 3:1”比例挑选 comment，直到达到字符数上限（可配置）。
   2. PR：
      • 若在 review 中触发：
        • 保留同一批 review 及其 review comment 全部内容。
      • 若在普通 comment 中触发：
        • 保留所有 review + 最新批次 review comment。
      • 完整 diff 存入单独文件（不直接塞进主上下文）。

2. markdown 构建：

   1. # Task + > task 引用块。
   2. # Context + > context 引用块。
   3. 追加：
      • Agent 历史（从 history issue 读取最新几条）。
      • Agent memory（从 memory issue 读取最新几条）。

3. 日志 issue 追溯（5.2.4 与 2.4.2 一致）：

   1. 在 issue 的 comment 中写入：
      • 指向 agent 创建内容的链接（issue、comment、pr）。
      • Claude Code 会话记录（jsonl → markdown）。
      • 若 Claude Code 本体报错或检测到循环：
        • 写入错误信息并添加 bug 标签。

4. 自查消息（5.2.7 修正）：

   1. 自查不是独立系统，而是：
      • 在 Claude Code 调用脚本中，再发起一次 claude --continue 调用。
      • 仅仅是给 Claude Code 发一条消息（例如“请确认是否已在 GitHub 留下回复”），并允许 MCP 继续代理 gh 调用。

---

6 MCP 工具与策略（精确定义）

6.1 MCP 的定位与边界

1. MCP 是一个工具（6.1.1 与 3.1.3 一致）：
   1. 它只负责代理 gh 调用，不是所有工具调用的总入口。
2. “拦截所有工具调用”是错误表述（6.1.2 修正）：
   1. MCP 只代理 GitHub 相关工具调用（例如 gh.create_comment、gh.create_issue、gh.create_pr 等）。
   2. 其他工具（如本地文件操作）不经过 MCP。

6.2 策略细节修正

1. 去重与次数限制：
   1. 若两次写 comment/pr/issue 调用完全一致：拒绝第二次。
   2. 创建 comment：同一 issue/pr 限制两次。
   3. 创建 issue：同一仓库限制一次。
   4. 创建 pr：同一仓库限制一次。
2. 禁止操作（6.2.4 修正）：
   1. 禁止修改他人消息。
   2. 禁止删库。
   3. 禁止删除非本次工作流中创建的评论。
   4. 禁止发布 review（因为 review 不可删）。

6.3 循环检测

1. 逻辑：
   1. 只要连续几次 tool call 与 tool call 返回完全一致，即视为循环。
   2. 同时检测重复 gh 写操作。
2. 行为：
   1. 终止当前 Claude Code 会话。
   2. 在日志 issue 中写入错误信息并添加 bug 标签。

6.4 历史与记忆工具（6.4.1 / 6.4.2 修正）

1. 在 GitHub Actions 环境中，自动化脚本就是 LLM 的“用户”：
   1. 所有 claude --continue 调用都是由脚本发起的“用户消息”。
2. 历史工具（history）：
   1. 通过一次 claude --continue，由“用户”输入“请用一句话总结你刚刚做了什么”。
   2. Claude Code 调用 history 工具，MCP 将单行文本写入专用 history issue。
3. 记忆工具（memory）：
   1. 由 agent 自主调用，用于写入长期记忆。
   2. 写入次数没有默认值，由你配置（你没有说过默认值）。
   3. 记忆同样是单行文本，写入专用 memory issue，append-only。

---

7 数据结构与字段说明（逐字段用途）

7.1 ContextEnvelope 字段用途

1. version：协议版本，便于未来演进。
2. jobid：本次 workflow 的唯一标识，用于分片合并与日志关联。
3. repo：触发仓库（owner/name）。
4. actor：触发者用户名。
5. trust_level：触发者信任级别（owner/collaborator/external）。
6. permission_config：从 @ 中解析出的权限配置（例如仅当前 issue 可写 comment）。
7. trigger：触发节点信息（类型、id、url）。
8. raw_context：完整原始上下文（issue/pr/review/comment/discussion/fork/upstream）。
9. timestamp：触发时间，用于审计与排序。

7.2 Shard Payload 字段用途

1. jobid：标识属于同一会话的所有 shard。
2. shard_index：当前分片序号。
3. total_shards：总分片数。
4. encoding：压缩与编码方式（如 gzip+base64）。
5. checksum：用于合并后校验完整性。
6. data_b64：实际数据内容（编码后）。

---

8 运行、token 与日志

8.1 运行与监控

1. 监控 dispatch 成功率、循环检测触发、日志 issue 关闭情况等。
2. 使用 GitHub Actions 自带日志作为主要审计来源（你没有计划额外写日志）。

8.2 token 设计（8.4.3 修正）

1. 服务端使用两个 token：
   1. 一个 bot token：用于监听通知。
   2. 一个你的个人 token：用于触发 workflow（repository_dispatch）。
2. Actions 与 MCP：
   1. Actions 使用专用 token 运行 Claude Code（通常只对 fork 有写权限）。
   2. MCP 作为工具层代理，使用同一 token 或更细粒度的 token 来执行 gh 调用。

8.3 日志位置（8.4.4 修正）

1. 你没有计划将日志写到外部系统：
   1. GitHub Actions 的日志已经可追溯，足够满足审计需求。
   2. 关键行为（创建 issue/comment/pr、错误、循环）会写入日志 issue，本身也是一种“结构化日志”。

---

如果你愿意，下一步我可以基于这份“纠正后版本”，直接给你生成某一部分的代码骨架（例如：server envelope 结构、Actions 调用脚本、history/memory 工具接口），你可以继续挑错、迭代到你完全满意为止。

[WhiteElephant-abc]

1.1.2.a 在GitHub Actions环境中，将llm与token隔离，使用的就是“进程隔离”
2.3.1.a 例如的第一条举例不合适
2.3.2.b 这个在mcp侧执行
2.5.2 我明确一下：第一次 若 无 gh写（创建消息，其他写不算），要求留下消息（新建issue、pr也算），第二次无条件，要求确认是否推送（若有文件修改），第三次是要求调用history工具（通过claude命令行参数精确允许特定工具）
3.1.3.b mcp负责重复写的检测
4.1.3 此处鉴权是根据配置的用户列表
4.2.1 还有一些元数据，例如issue开关状态，issue标签，issue分配
4.2.2 pr分支信息，状态信息等等
4.2.3 抓取仓库列表，以及当前任务的对应fork分支列表（和更新时间，最新commit）
4.2.4 这是什么意思，触发节点必然在上游仓库的issue/pr/discussion中，还抓什么？
4.3.2.a 是将agent从xx屏蔽，而不是“屏蔽仓库”
4.3.3.b.2 不是“关闭开放pr”，是“开放pr因此自动关闭”写明确
4.3.3.b.3 issue要以“未计划”关闭
5.1.7 还有一次history流程，另外是1-2次，因为第一次可以跳过
5.2.2.c.2 应该为全部memory，仅设置一定字符数上限
6.2.2 禁止删分支
6.3.1.a 默认6次吧
6.4.3.b 默认3次差不多，限制字符数长度
7.1 这个是传输格式还是上下文格式（就是这一坨数据会不会被分片），如果是上下文格式，里面为什么还有个“context”字段
7.2.6 写清楚，是“分片后”不仅仅是“编码后”
8.2.2 Claude Code不接触token，为了限制频率和限制写，agent一切api调用经过mcp，mcp使用完整权限的agent用户token

[WhiteElephant-abc]

1 总体概览

1.1 当前状态与隔离方式

1. 当前状态

   1. 服务端当前为单脚本，负责：
      • 监听通知
      • 构建 task
      • 构建上下文
      • 触发鉴权
   2. GitHub Actions 当前几乎只负责：
      • 运行 Claude Code
      • 在每次运行前创建日志 issue

2. 机密与权限隔离

   1. 通过创建独立 GitHub 用户实现账号级隔离：
      • agent 使用单独账户，仅对 fork 有写权限。
   2. 在 GitHub Actions 环境中，通过进程隔离将 LLM 与 token 隔离（1.1.2.a）：
      • Claude Code 进程本身不直接持有 token。
      • 所有 GitHub API 调用由独立的 MCP 进程代为执行。

3. MCP 的定位

   1. MCP 是一个“工具进程”，只负责代理 GitHub API 调用。
   2. MCP 持有完整权限的 agent 用户 token，负责频率限制与写操作限制。
   3. Claude Code 不接触 token（8.2.2），所有 API 调用必须经过 MCP。

---

2 目标与功能需求

2.1 访问控制与审计

1. 对 LLM 访问 GitHub 做完整限制：
   1. 限制允许的写操作类型（issue、comment、pr）。
   2. 限制只读操作频率（MCP 侧节流）。
2. 对所有 GitHub 活动进行追溯：
   1. issue、comment、pr（review 被禁止）。
   2. 对 comment、pr 等写操作进行次数限制。

2.2 完整上下文构建

1. 目标：构建 markdown 格式的完整上下文，供 Claude Code 使用。
2. 上下文内容包括：
   1. 触发处 issue/pr 上下文。
   2. PR 关联 issue 上下文。
   3. LLM 自己账户对应 fork 仓库上下文。
   4. 上游仓库相关元数据。
   5. Agent 历史与 memory 补充。
3. 日志 issue body 中的格式（2.2.2）：
   1. # Task
      • 下一行：> ... 引用块包裹 task。
   2. # Context
      • 下一行：> ... 引用块包裹 context。

2.3 循环检测与重复写检测

1. 检测目标（2.3.1 / 2.3.1.a 修正）：
   1. 检测 LLM 陷入循环：
      • 多次重复调用相同工具并得到完全相同返回。
      • 多次重复发起相同的 GitHub 写操作。
2. 判定规则（2.3.2.b）：
   1. 在 MCP 侧执行：
      • 只要连续若干次（默认 6 次，6.3.1.a）tool call 与返回完全一致，即视为循环。
      • 同时检测重复 gh 写操作（相同参数的写调用重复出现）。

2.4 日志 issue 升级与追溯

1. 日志 issue 用途：
   1. 作为每次 workflow 的“会话日志与审计记录”。
2. 日志 issue 内容（2.4.2 修正）：
   1. 触发时：
      • body 中包含 task 与 context（引用块）。
   2. 结束时：
      • comment 中写入：
        • 指向 agent 创建内容的链接（issue、comment、pr）。
        • Claude Code 会话记录（jsonl → markdown）。
      • 若 Claude Code 本体报错或检测到循环：
        • 写入错误信息并添加 bug 标签。
      • 若中途无报错：
        • 关闭 issue，且以“未计划”方式关闭（4.3.3.b.3）。

2.5 自查与总结流程（精确定义）

1. 自查与总结统一为多次 claude --continue 调用（2.5.1 / 2.5.2）：
   1. 第一次（可跳过）：
      • 条件：若本次 workflow 中没有任何 GitHub 写操作（创建消息，其他写不算）。
      • 行为：通过 claude --continue 提示 agent 留下消息（新建 issue、pr 也算“留下消息”）。
   2. 第二次（无条件执行）：
      • 行为：通过 claude --continue 要求确认是否推送（若有文件修改）以及 PR 是否存在。
   3. 第三次（history 流程）：
      • 行为：通过 claude --continue，并通过命令行参数精确允许 history 工具，要求 agent 调用 history 工具，用单行总结“本次干了什么”。
2. history 流程总次数为 1–2 次（5.1.7）：
   1. 第一次可跳过，第二次为强制总结。

---

3 架构与 MCP 定位

3.1 组件与角色

1. 服务端：
   1. 监听通知、定位触发节点、根据配置用户列表进行鉴权（4.1.3）、解析权限配置、go away 判定、抓取完整上下文、构建 envelope、分片并 dispatch。
2. GitHub Actions：
   1. 接收 envelope、筛选上下文、构建 markdown、创建日志 issue、创建隔离用户环境、运行 Claude Code、通过 MCP 代理 gh 调用、执行 1–2 次自查与 1 次 history 流程。
3. MCP（3.1.3.b）：
   1. 作为一个独立工具进程，只代理 GitHub API 调用。
   2. 负责：
      • 写操作次数限制。
      • 重复写检测。
      • 循环检测（基于 tool call + 返回）。
      • 频率限制。

---

4 服务端设计与 go away 机制

4.1 服务端职责

1. 监听通知（@ 中可带权限配置）。
2. 推算触发节点（@ 智能体的那条消息）。
3. 触发者鉴权（4.1.3）：
   1. 根据配置的用户列表判断是否允许触发。
4. 获取完整上下文。
5. 构建 envelope。
6. 分片传 workflow。

4.2 上下文抓取细节

1. issue（4.2.1）：
   1. body、comments。
   2. 元数据：
      • issue 开关状态。
      • issue 标签。
      • issue 分配（assignees）。
2. PR（4.2.2）：
   1. body、comments、reviews、review comments。
   2. 分支信息：
      • head 分支、base 分支。
      • PR 状态（open/closed/merged）。
3. fork 仓库（4.2.3）：
   1. 仓库列表。
   2. 当前任务对应的 fork 分支列表（含更新时间、最新 commit）。
4. 上游仓库（4.2.4 修正）：
   1. 触发节点必然在上游仓库的 issue/pr/discussion 中，因此：
      • 不再额外“抓上游仓库上下文”，而是：
        • 仅抓与当前任务相关的元数据（如默认分支、保护规则等，若需要）。

4.3 go away 屏蔽规则与专用 workflow

1. 触发方式：
   1. 用户输入：@WhiteElephantIsNotARobot go away。
2. 屏蔽语义（4.3.2.a 修正）：
   1. 是将 agent 从某些仓库/用户名下仓库中屏蔽，而不是“屏蔽仓库本身”。
3. 处理流程（4.3.3）：
   1. 监听到屏蔽消息后：
      • 触发专用 workflow。
      • 在一个专用 issue 中维护“屏蔽仓库及用户列表”：
        • issue body 反复编辑更新（覆盖写入最新列表）。
   2. 屏蔽后行为（4.3.3.b）：
      1. 删除对应仓库的 fork：
         • 由于 fork 被删除，开放 PR 因此自动关闭（4.3.3.b.2）。
      2. 删除对应仓库下 agent 创建的 issue/pr comment（review 不可删，因此禁止 LLM 发布 review）。
      3. 在日志 issue 中以“未计划”方式关闭（4.3.3.b.3）。
      4. MCP 在后续 workflow 中拒绝对这些仓库的写操作。

---

5 Actions 端上下文与日志 issue

5.1 Actions 端职责

1. 接收完整数据（envelope 或合并后的数据）。
2. 筛选上下文。
3. 创建日志 issue（body 中包含 task 与 context 引用块）。
4. 创建隔离用户环境（新用户配置）。
5. 配置并运行 Claude Code。
6. 通过 MCP 代理 gh 调用。
7. 执行 1–2 次自查流程（第一次可跳过，第二次必做），以及 1 次 history 流程（5.1.7）。
8. 在日志 issue 中写入追溯信息与会话记录。
9. 若无错误，以“未计划”方式关闭日志 issue。

5.2 上下文筛选与构建细节

1. 筛选规则（5.2.2）：
   1. issue comment：
      • 按“新旧 3:1”比例挑选 comment，直到达到字符数上限（可配置）。
   2. PR：
      • 若在 review 中触发：
        • 保留同批 review 及其 review comment 全部内容。
      • 若在普通 comment 中触发：
        • 保留所有 review + 最新批次 review comment。
      • 完整 diff 存入单独文件。
2. Agent 历史与记忆（5.2.2.c.2 修正）：
   1. history：
      • 从 history issue 读取最近若干条，按字符数上限截断。
   2. memory：
      • 读取全部 memory，仅通过总字符数上限截断。
3. 日志 issue 追溯（与 2.4.2 一致）：
   1. 写入指向创建内容的链接。
   2. 写入 Claude Code 会话记录。
   3. 若 Claude Code 本体报错或检测到循环：
      • 写入错误信息并添加 bug 标签。
4. 自查消息（5.2.7 修正）：
   1. 自查与 history 流程均通过 claude --continue 实现：
      • 仅仅是给 Claude Code 发消息，集成在调用脚本中。

---

6 MCP 工具与策略

6.1 MCP 的定位

1. MCP 是一个独立工具进程，只代理 GitHub API 调用（6.1.1）。
2. 不拦截所有工具调用（6.1.2 修正）。
3. MCP 持有完整权限的 agent 用户 token（8.2.2），负责：
   1. 写操作次数限制。
   2. 重复写检测（3.1.3.b）。
   3. 循环检测。
   4. 频率限制。

6.2 策略细节

1. 写操作限制：
   1. 若两次写 comment/pr/issue 调用完全一致：拒绝第二次。
   2. 创建 comment：同一 issue/pr 限制两次。
   3. 创建 issue：同一仓库限制一次。
   4. 创建 pr：同一仓库限制一次。
2. 禁止操作（6.2.2 修正）：
   1. 禁止修改他人消息。
   2. 禁止删除仓库。
   3. 禁止删除非本次 workflow 中创建的评论。
   4. 禁止删除分支。
   5. 禁止发布 review。

6.3 循环检测

1. 判定规则（6.3.1.a）：
   1. 默认阈值为连续 6 次：
      • tool call 与返回完全一致。
      • 或重复 gh 写操作。
2. 行为：
   1. 终止当前 Claude Code 会话。
   2. 在日志 issue 中写入错误信息并添加 bug 标签。

6.4 历史与记忆工具

1. 历史工具（history）：
   1. 通过 claude --continue，由“用户”（自动化脚本）输入“请用一句话总结你刚刚做了什么”。
   2. Claude Code 调用 history 工具，MCP 将单行文本写入 history issue。
2. 记忆工具（memory）（6.4.3.b）：
   1. 由 agent 自主调用，用于写入长期记忆。
   2. 默认每次 workflow 最多写入 3 条，且每条有字符数上限。
   3. 所有 memory 写入专用 memory issue，append-only。

---

7 数据结构与字段说明

7.1 ContextEnvelope 的性质与用途

1. 这是传输格式，不是最终上下文格式（7.1 修正）：
   1. 这坨数据本身可能会被分片（若超过限制）。
2. 字段用途：
   1. version：协议版本。
   2. jobid：本次 workflow 唯一标识。
   3. repo：触发仓库。
   4. actor：触发者用户名。
   5. trust_level：触发者信任级别。
   6. permission_config：从 @ 中解析出的权限配置。
   7. trigger：触发节点信息。
   8. raw_context：完整原始上下文（issue/pr/review/comment/discussion/fork/upstream 元数据）。
   9. timestamp：触发时间。

7.2 Shard Payload 字段用途（7.2.6 修正）

1. jobid：标识属于同一会话的所有 shard。
2. shard_index：当前分片序号。
3. total_shards：总分片数。
4. encoding：压缩与编码方式。
5. checksum：用于合并后校验完整性。
6. data_b64：分片后再编码的内容（即：先分片，再压缩/编码）。

---

8 运行、token 与日志

8.1 日志与可追溯性

1. 你不计划额外写外部日志（8.4.4）：
   1. GitHub Actions 的日志已经可追溯。
   2. 日志 issue 本身也是结构化审计记录。

8.2 token 模型（8.2.2 修正）

1. 服务端：
   1. 使用两个 token：
      • bot token：监听通知。
      • 你的个人 token：调用 workflow（repository_dispatch）。
2. Actions 与 MCP：
   1. Claude Code 不接触 token。
   2. 所有 API 调用经过 MCP。
   3. MCP 使用完整权限的 agent 用户 token：
      • 负责频率限制。
      • 负责写操作限制。

---

如果你愿意，下一步我可以基于这版“纠正后设计”，直接给你生成某一块的代码骨架（例如：ContextEnvelope 结构 + 分片逻辑，或自查三步流程的调用脚本），你可以继续逐条挑错。

[WhiteElephant-abc]

1.1.2.a 对上游有普通的写权限，如issue，comment，pr
1.1.2.b 通过Linux的用户系统实现隔离
2.4.2.b.3.1 严重偏差，“未计划”方式适用于go away机制，此处为“complete”
2.5.2 1-2次属于“自查流程”，加上history记录是2-3次
4.1.1 设计一下权限配置标记格式
4.2.1.b/4.2.2 「包括但不限于这些数据」
4.2.3.a 仓库列表指agent名下仓库列表，以及仓库元数据（若api支持一次性获取，总之此步骤包含批量获取仓库列表+API可能返回的其他附加元数据信息）
4.2.3.b 加上对应fork的描述等元数据（fork就是上游对应fork，若有则抓）
4.2.4 上游仓库分支状态，与fork状态一样抓取，但没有仓库列表
5.1.9 偏差同2.4.2.b.3.1
5.2.2.a 读取条数固定，不涉及截断
6.3.1.a.2 重复gh写，第二次就拒绝了
6.4.2.c comment形式
7.1.2 既然是传输格式，不应该带上上下文信息，另外为何传输格式会被分片，应该是上下文本身被分片，上下文里带上一切触发节点等等信息（触发者、仓库之类）
7.2.6 先编码上下文，然后分片不是更简单吗？只需对一段字符串进行分割就行了

请仅对我的关键纠正进行确认，然后输出我的全部关键修正
注意要简短精确，不要占用你自己的上下文窗口