Moai-Team-LLC/AgenticSelfHealingCode

# AgenticSelfHealingCode（自我修复的智能体代码） **面向智能体产品的自我修复运维** —— 由一组智能体组成的网络，用于生产监控、 事件诊断、人工确认的代码修复以及测试套件的自我修复，**采用对抗式设计， 随后精简为实际可以安全构建的部分。** [](LICENSE) [](https://github.com/Moai-Team-LLC/AgenticSelfHealingCode/actions/workflows/ci.yml) [](https://bun.sh) [](https://github.com/pgvector/pgvector) **独立**运行于 Postgres + pgvector，包含可选的集成（绝不会成为硬性依赖），详见 [`INTEGRATIONS.md`](INTEGRATIONS.md)。 ## 🚀 快速开始（60秒） 仅需 [Bun](https://bun.sh)。无需密钥、无需数据库、无需配置： ``` git clone https://github.com/Moai-Team-LLC/AgenticSelfHealingCode.git cd AgenticSelfHealingCode bun run demo ``` 该演示会启动真实的信号接收服务，并通过真实的 HTTP 和真实的 HMAC 签名向其播放五个场景。 你将看到它：为与部署相关的异常进行溯源分析并建议回滚（ **已确认**）；拒绝归咎于一个不存在的部署，并以**指明的缺失证据**进行升级（ 它绝不猜测）；在带签名的接收边界处拒绝被伪造的 webhook；将遥测数据内部的提示词注入尝试 标记为*数据，绝不仅是指令*；并拒绝为重复事件重复呼叫 on-call 人员。 ### 真实运行 ``` SIGNAL_SECRET=$(openssl rand -hex 16) docker compose up # Postgres + pgvector + the service, migrated SIGNAL_SECRET= bun run send-signal # fire a signed signal at it ``` 持久化状态（事件记忆、通知 CAS、kill switch、自动操作账本）现在存储在 Postgres 中，并在重启后仍然保留。如果你想使用自己的 Postgres：设置 `DATABASE_URL`，运行 `bun run migrate`， 然后运行 `bun run start`。 ### → 真正投入实战 将你的 **Sentry** 指向 `/webhook/sentry`（原生——无需垫片），通过本地仓库检出（`RCA_GIT_REPO`）和 Claude（`ANTHROPIC_API_KEY`）开启**基于事实的诊断**，通过点击确认（tap-to-ack）的方式 通过 **Telegram** 推送，并通过 HTTP（`GET /status`，`GET /incidents`，带签名的 `POST /kill|/release`）进行操作。 完整的 day-2 实战指南 —— 连接遥测数据 → 基于事实的 RCA（根因分析） → 运维 —— 见 [`USAGE.md`](USAGE.md)。 每一项能力都是一个可选的环境变量；该服务可以在没有任何这些变量的情况下（基于假数据）运行。复制 `connectors/.env.example` → `connectors/.env` 并填写你需要的内容。 ``` bun test packages # the whole product's test suite ``` 本仓库包含两部分：**一份协调一致的设计**（即根目录下的 Markdown 文档，经过对抗性审查 —— 请从 `ARCHITECTURE-REFRAMED.md` 开始），以及 **一个可用的产品** —— 即组成 可运行服务的 `@sho/*` 包，已通过真实的 Postgres + pgvector 验证。 ## 一句话重构 最初的目标是实现生产环境代码的自动修复。一项对抗性压力测试 （[`STRESS-TEST.md`](STRESS-TEST.md)）表明这是最小且风险最高的切片，因此重心 转移到了 **诊断（Loop A） + 测试套件自我修复（Loop B）**。代码修复本身以 **人工确认**的方式交付（Loop C **L1**，`@sho/loop-c`）：智能体会提议一个修复方案，该方案必须通过 非 LLM 的门控*然后人工才能看到它*，人工通过合并 PR 或点击 Telegram 来确认 —— 它 **绝不自动应用**。只有 **自主**修复（Loop C **L2/L3**，无人工参与） 保持 **推迟**，并基于不同事件类别的实际结果数据逐步解锁。信心锚定在布尔值上，而非 LLM 的 自述报告；信任会根据结果扩展，而不是因为不否决就信任。完整的原理见 [`ARCHITECTURE-REFRAMED.md`](ARCHITECTURE-REFRAMED.md)（事实来源）以及 [`DECISIONS.md`](DECISIONS.md)（D1–D10）。 ## 设计文档 | 文档 | 作用 | |---|---| | [ARCHITECTURE-REFRAMED.md](ARCHITECTURE-REFRAMED.md) | 🔑 事实来源 —— 拓扑结构、层级、契约、指标 | | [ARCHITECTURE-ORIGINAL.md](ARCHITECTURE-ORIGINAL.md) · [STRESS-TEST.md](STRESS-TEST.md) | 最初的目标 + 重塑了该目标的对抗性审查 | | [DECISIONS.md](DECISIONS.md) · [BUILD-PLAN.md](BUILD-PLAN.md) · [COHERENCE-REVIEW.md](COHERENCE-REVIEW.md) | D1–D10，分阶段推广，跨规范调和 | | 组件规范 | [LOOP-A](LOOP-A-SPEC.md) · [LOOP-B](LOOP-B-SPEC.md) · [LOOP-C-DEFERRED](LOOP-C-DEFERRED.md) · [VERIFICATION-GATE](VERIFICATION-GATE.md) · [INCIDENT-MEMORY](INCIDENT-MEMORY.md) · [TRUST-CONTROLLER](TRUST-CONTROLLER.md) · [ORCHESTRATION](ORCHESTRATION.md) · [HITL-APPROVAL](HITL-APPROVAL.md) · [SECURITY-THREATMODEL](SECURITY-THREATMODEL.md) · [D10-INSTRUMENT](D10-INSTRUMENT.md) | ## 产品 —— `packages/`（Bun-workspace monorepo，TS strict，零运行时依赖） 真实的系统，通过契约优先构建，因此没有组件会重新派生出一个分歧的形状。每一个包都是 纯粹的、经过单元测试的决策逻辑；基础设施（Postgres、LLM、Telegram）位于 **带有内存假数据的接口背后**，因此整个系统现在就可以测试，真实的适配器稍后会接入。 | 包 | 负责的内容 | 测试数 | |---|---|---| | [`@sho/contracts`](packages/contracts/) | 共享的骨干：类型，L↔层级对照，规范的 SQL DDL，不受信任输入的防护（D7）。 | 7 | | [`@sho/trust-controller`](packages/trust-controller/) | 结果折叠 + 关闭 D6 失控的非对称自主法则（在确认为良好时晋升，在有害时快速降级，kill→L0）。 | 9 | | [`@sho/incident-memory`](packages/incident-memory/) | Why-trace（原因追踪）存储，基于结果加权的检索（防投毒），`OutcomeEvent` 投影器，防漂移的重复事件。 | 20 | | [`@sho/aggregation`](packages/aggregation/) | 指纹 / 防重命名的症状签名 / 去重 / 优先级。 | 18 | | [`@sho/signal-layer`](packages/signal-layer/) | 带签名的接收（HMAC）+ 不受信任输入的归一化。 | 13 | | [`@sho/orchestrator`](packages/orchestrator/) | 持久化状态机，路由器，应用时写入器（幂等，两种着陆变体），单一 kill bit。 | 7 | | [`@sho/loop-a`](packages/loop-a/) | RCA 副驾驶：基于事实布尔值的信心，部署锚定分支，why-trace。**零写访问权限。** | 25 | | [`@sho/loop-b`](packages/loop-b/) | 测试套件自我修复：A/B/C/D 判别器 + 不稳定测试隔离。 | 16 | | [`@sho/loop-c`](packages/loop-c/) | **人工确认的代码修复（L1）**：提议 → 受保护路径块 → 基于事实的复现不变性 → 非 LLM 门控 → PR + L1 审批 → `human_approved` 着陆。从不自动应用。 | 18 | | [`@sho/hitl`](packages/hitl/) | 异步审批阶梯 + 关闭攻击 #6 的营业时间门控。 | 25 | | [`@sho/pipeline`](packages/pipeline/) | **端到端的垂直切片** —— 一个事件贯穿每一个包（信号→去重→RCA→路由→门控→应用→信任→kill）。 | 1 | | [`@sho/adapters`](packages/adapters/) | 接口背后的真实边缘：`TelegramNotifier` + `ClaudeLlmClient` + `githubPublisher`/webhook 验证（注入 fetch，离线测试；密钥通过环境变量传入）。 | 9 | | [`@sho/app`](packages/app/) | 可部署的服务：带签名的 webhook → pipeline → 推送，+ Loop C 提议触发器以及 PR 合并 / Telegram 确认通道。 | 12 | ``` bun test packages # the whole product — 152 tests bun run packages/app/src/server.ts # start the signal-intake service (fakes until keys are in .env) ``` ## 参考内核（已验证的构建块，用于生产化各包） | 内核 | 验证的内容 | 测试数 | |---|---|---| | [`d10-instrument/`](d10-instrument/) | MTTR 瓶颈（诊断 vs 修复）。适配器：CSV，PagerDuty，**Linear**，Sentry，丰富化。 | 18 | | [`verification-gate/`](verification-gate/) · [`mutation-gate/`](mutation-gate/) · [`gate/`](gate/) | must-fail-on-parent + 变异分数 + 集成 `verify()` + CLI + PR 工作流。 | 23 | | [`loop-b/`](loop-b/) | 判别器内核（移植到 `@sho/loop-b` 中）。 | 10 | | [`connectors/`](connectors/) | 实时的 Linear/Sentry 拉取（读取被 gitignored 的 `.env`） → 喂给 D10。 | — | 驱动程序仅为参考（字符串变异，git-worktree 叠加）；而决策层 是生产形状的，并且可以原封不动地替换到真实的引擎（StrykerJS，你的 CI，你的追踪器）上。 ## 快速开始 ``` # 运行任何 package 的测试 + 实时演示 cd verification-gate && bun test && bun run demo.ts cd mutation-gate && bun test && bun run demo.ts cd loop-b && bun test && bun run demo.ts cd gate && bun test && bun run demo.ts # 在样本数据上运行 D10 bun run d10-instrument/d10.ts d10-instrument/fixtures/incidents.sample.json # 将 verification gate 作为 PR check（参见 .github/workflows/verification-gate.yml） bun run gate/cli.ts --base --head --min-mutation-score 0.75 # 在您的 Linear 数据上运行 D10（在您添加 key 之后 — 参见 connectors/README.md） cp connectors/.env.example connectors/.env # fill LINEAR_API_KEY + LINEAR_STATE_* bun run connectors/linear-pull.ts ``` ## 开源 / 密钥边界 凭据**仅**存在于 `connectors/.env`（被 gitignored）中；本仓库附带 `.env.example` + 纯 映射器。拉取的数据（`incidents.json`，`*.pulled.json`）被 gitignored —— 它可能包含 可识别公司的内容。在推送之前，请验证 `git status` 显示没有 `.env` 并且没有拉取的数据， 并轮换任何粘贴在 `.env` 之外的密钥。详情：[`connectors/README.md`](connectors/README.md)。 ## 状态（什么是真实的，以及什么需要实时基础设施） - **已构建并验证（203 个测试，0 失败）：** 所有 12 个产品包 + 参考内核。组件 图能够组合（`@sho/pipeline` 垂直切片让一个真实事件端到端地贯穿），该 服务是可运行的（`@sho/app`），并且真实的 **Telegram + Claude 适配器已经过离线验证** （注入 fetch 的测试 —— 无需密钥，无需网络）。 - **Postgres + pgvector：已完全通过真实数据库验证。** 契约 `MIGRATIONS` 构建于 Postgres 16 + pgvector 之上，冻结触发器会触发，并且整个 `PostgresIncidentMemory` 路径 —— `projectOutcomeEvents`、`detectRecurrence`、`harmQuery`、向量余弦查询以及基于结果加权的 `retrieveSimilar`（通过 `retrieve_outcome_weighted` SQL 函数） —— 均会通过 （`packages/incident-memory/verify-pg.ts`，**18 个实时检查**）。并且该 **app 会端到端地持久化到 真实的 Postgres**：一个带签名的 webhook → HTTP 处理器 → `incident_memory.incidents` 中的一行 （`packages/app/verify-app-pg.ts`）。实时的运行捕获并修复了内存中测试无法发现的 三个 bug：一个迁移顺序错误，一个不可移植的数组绑定，以及缺失的检索函数。 重现：`docker run -d -e POSTGRES_PASSWORD=sho -e POSTGRES_DB=sho -p 54329:5432 pgvector/pgvector:pg16`，通过 psql 应用迁移，然后在设置了 `DATABASE_URL` 后运行两个验证脚本。当存在 `DATABASE_URL` 时，`server.ts` 会自动使用 Postgres。 - **持久化的编排器：基于 Postgres 构建，经过验证，并已接入到 app 中。** Kill bit （`orch.kill_switch`）、`notify_state` CAS 以及 `_action` 账本都会被持久化，并且**能够在 进程重启后幸存** —— 一个全新的 store 实例会准确读取到上一次中断的地方 （`packages/orchestrator/verify-orch-pg.ts`，13 个实时检查）。并且正在运行的服务使用了持久化的 notify：设置了 `DATABASE_URL` 后，一个带签名的 webhook 会推送一次，而**第二个进程（一次重启） 不会重复推送**相同的事件 （`packages/app/verify-app-pg.ts`）。适配器写入现在是可 等待的，因此事件行会在 CAS 读取它之前着陆。内存中版本仍然是单元测试假数据。 - **仍然开放：** LLM/Telegram 适配器只需要在 `connectors/.env` 中放入它们（轮换过的）密钥 —— 代码已经完成并经过了离线测试。这是唯一剩下的边缘部分；其他所有的都在真实的基础设施上运行。 - **决定性的产品决策权仍然属于你：** 在真实的事件 历史记录上运行 `connectors/linear-pull.ts` 以得出 D10 的判定 —— 是先做 Loop A，还是先解决修复交付中的摩擦问题。

标签：Bun, PostgreSQL, 模块化设计, 自动化修复, 自动化攻击, 自愈系统, 请求拦截, 运维监控