# https://github.com/adaline-ankit/oh-no-my-claudecode 项目说明书 生成时间：2026-06-27 13:54:47 UTC ## 目录 - [Introduction & Quick Start](#page-overview) - [Autonomous Loops, Autopilot, Swarm & No-Mistakes Gate](#page-execution) - [Repository Memory, Briefs, Guards & Sync](#page-memory) - [Cross-Agent Plug, MCP Server, Hooks & Skill Export](#page-integrations) ## Introduction & Quick Start ### 相关页面 相关主题：[Autonomous Loops, Autopilot, Swarm & No-Mistakes Gate](#page-execution), [Repository Memory, Briefs, Guards & Sync](#page-memory)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md) - [src/oh_no_my_claudecode/ingest/llm_extractor.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/llm_extractor.py) - [src/oh_no_my_claudecode/importers/markdown.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/markdown.py) - [src/oh_no_my_claudecode/ingest/repo_tree.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/repo_tree.py) - [src/oh_no_my_claudecode/models/brief.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/models/brief.py) - [src/oh_no_my_claudecode/loop/engine.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/engine.py) - [src/oh_no_my_claudecode/llm/base.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/llm/base.py) - [src/oh_no_my_claudecode/hooks/boot_digest.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/boot_digest.py) - [src/oh_no_my_claudecode/ingest/docs.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/docs.py) - [src/oh_no_my_claudecode/loop/models.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/models.py) - [src/oh_no_my_claudecode/importers/base.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/base.py)
# Introduction & Quick Start ## 项目概览 `oh-no-my-claudecode`（CLI 简写为 `onmc`）是一个面向 AI 代理的本地优先记忆与编排框架。它把仓库代码、文档、提交记录与历史失败抽取成结构化记忆，存放在本地 SQLite 与 `.agent-memory/` 目录中，使任何 LLM 代理在执行任务时都能拿到"已经被验证过、带证据、可证伪"的上下文，而非大段文件转储。 主要能力包括：可重现检索、失败记忆（`guard`）、任务简报（`brief`）、记忆驱动循环（`loop`）、自动驾驶（`autopilot`）、技能导出、记忆评测、可观测追踪与本地仪表盘。核心读写路径无需 LLM 即可工作，外部资源请求默认关闭，仪表盘绑定 `127.0.0.1`。资料来源：[README.md:1-40]() 最新 v0.52.0 引入"Agent Ops"批次（codegraph + reuse + conventions）并强化 in-session subagent swarm，实现 token-free 的并行扇出。资料来源：[v0.52.0 release notes](https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.52.0) ## 安装与初始化 开发模式下从源码安装： ```bash git clone https://github.com/adaline-ankit/oh-no-my-claudecode cd oh-no-my-claudecode pip install -e ".[dev]" ``` 随后执行 `onmc ui` 启动本地仪表盘，提供首次运行的欢迎视图（v0.36 引入）；仪表盘仅在 `127.0.0.1` 监听，不发起任何外部资产请求。资料来源：[README.md:14-22]() 记忆与状态按用途分离存放： | 路径 | 用途 | |---|---| | `.onmc/` | 本地 SQLite、追踪、日志、评测；已加入 `.gitignore` | | `.agent-memory/` | 可移植 JSON、技能、收据、最新简报；按需提交 | | `CLAUDE.md` | 生成的工程上下文；按团队约定决定是否提交 | 格式规范见 `AGENT-MEMORY-SPEC.md`，可使用 `onmc spec validate` 校验导出文件。资料来源：[README.md:24-34]() ## 核心命令一览 `onmc` 命令按"采集 → 检索 → 执行 → 观测 → 集成 → 分享"组织： | 类别 | 命令 | 作用 | |---|---|---| | 采集 | `onmc ingest`, `onmc import` | 抽取仓库/外部资源为记忆或技能 | | 检索 | `onmc recall`, `onmc guard`, `onmc brief`, `onmc codegraph` | 失败召回、任务简报、代码图谱 | | 执行 | `onmc loop`, `onmc autopilot`, `onmc task` | 记忆驱动循环、自动驾驶、任务管理 | | 观测 | `onmc trace`, `onmc eval`, `onmc replay`, `onmc benchmark` | 追踪、评测、回放、基准 | | 集成 | `onmc plug`, `onmc hooks`, `onmc gh-aw init`, `onmc mcp` | 适配 Claude Code/Codex/Cursor/OpenCode | | 分享 | `onmc ui`, `onmc tui`, `onmc wiki`, `onmc skill export` | 本地仪表盘、TUI、Obsidian 知识图、Agent Skills | `onmc brief` 支持完整 markdown、`compact`、`caveman` 三种风格；后两者通过裁剪冗余 markdown 噪声显著降低 token 用量。资料来源：[src/oh_no_my_claudecode/models/brief.py:1-40]() `onmc benchmark` 标签化报告两类结果：**MEASURED**（召回延迟、命中数、脑组成、terse-vs-verbose、TOON-vs-JSON 缩减）与 **SIM**（确定性 harness 产生的重复失败率、浪费尝试数、上下文 token 差）。资料来源：[README.md:36-50]() ## 记忆驱动循环 `onmc loop` 是项目核心引擎：每一次迭代都基于记忆做出可证伪的"预测—结果"契约，从而避免重复失败。资料来源：[src/oh_no_my_claudecode/loop/engine.py:11-30]() ```mermaid flowchart LR A[RECALL
compile_guard + prompt_recall] --> B[PROMPT
goal + brief] B --> C[ACT
agent_runner] C --> D[VERIFY
verify_runner] D --> E{Outcome} E -- WIN --> F[记录 DECISION 记忆] E -- LOSS --> G[记录 FAILED_APPROACH
阻止下次重试] F --> H{继续?} G --> H H -- 连续失败 ≥ 阈值 --> I[升级 escalation_level] H -- 无进展窗口耗尽 --> J[停止] H -- 仍可推进 --> A ``` 迭代结果由 `IterationContract`（`prediction` / `action_summary` / `files_touched` / `verify_output` / `outcome`）记录，连续无进展会触发升级与停止。资料来源：[src/oh_no_my_claudecode/loop/models.py:11-50]() v0.50.0 修复了"代理鉴权/API 错误被错误标记为 verified"的缺陷，确保失败永远不会污染记忆。资料来源：[v0.50.0 release notes](https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.50.0) ## Python API 快速上手 ```python import onmc repo = onmc.init(".") repo.ingest() brief = repo.brief(task="修复 checkout 优惠码失败", style="compact", max_tokens=500) memories = repo.memory.search(files=["src/checkout/service.py"]) task = repo.task.start(title="Fix checkout coupon failures") repo.sync.commit() ``` LLM 抽象层（`LLMProvider`）支持结构化输出：通过 `generate_structured` 把 `JSON_ONLY_INSTRUCTION` 注入系统提示，解析失败或 schema 不匹配会抛出 `LLMProviderError`。资料来源：[src/oh_no_my_claudecode/llm/base.py:40-70]() 文档摄取按 markdown 章节切分（`split_markdown_sections`），非英文或噪声片段会被降权（`confidence = 0.0`），低于 40 字符的片段被丢弃。资料来源：[src/oh_no_my_claudecode/ingest/docs.py:60-95]() 通用 markdown 导入器 `onmc import ` 可将 `*.md` 批量转为技能或记忆，按稳定 id 去重，结果汇总到 `ImportResult`。资料来源：[src/oh_no_my_claudecode/importers/markdown.py:1-15]()、[src/oh_no_my_claudecode/importers/base.py:1-20]() ## 下一步 - 阅读 [Architecture](docs/architecture.md) 与 [Memory model](docs/memory-model.md) 了解内部结构。 - 体验 [Demo: two agents, one brain](docs/demo.md) 看记忆如何在两个代理间共享。 - 查看 [Agent-native workflows](docs/agent-native-workflows.md) 了解 loop/autopilot/swarm 用法。 - 通过 `onmc audit` 把代理配置审计接入 CI。 ## See Also - [Architecture](docs/architecture.md) - [Memory model](docs/memory-model.md) - [CLI reference](docs/cli-reference.md) - [Demo: two agents, one brain](docs/demo.md) - [Shipped capabilities](docs/shipped-capabilities.md) --- ## Autonomous Loops, Autopilot, Swarm & No-Mistakes Gate ### 相关页面 相关主题：[Introduction & Quick Start](#page-overview), [Repository Memory, Briefs, Guards & Sync](#page-memory), [Cross-Agent Plug, MCP Server, Hooks & Skill Export](#page-integrations)
相关源码文件 以下源码文件用于生成本页说明： - [src/oh_no_my_claudecode/loop/engine.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/engine.py) - [src/oh_no_my_claudecode/loop/models.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/models.py) - [src/oh_no_my_claudecode/loop/adapters.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/adapters.py) - [src/oh_no_my_claudecode/loop/checkpoint.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/checkpoint.py) - [src/oh_no_my_claudecode/loop/receipt.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/receipt.py) - [src/oh_no_my_claudecode/loop/templates.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/templates.py) - [src/oh_no_my_claudecode/loop/__init__.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/__init__.py) - [src/oh_no_my_claudecode/hooks/boot_digest.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/boot_digest.py) - [src/oh_no_my_claudecode/models/brief.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/models/brief.py) - [README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md)
# Autonomous Loops, Autopilot, Swarm & No-Mistakes Gate ## 1. 概述与定位 `oh-no-my-claudecode`（简称 onmc）的核心交付是一套**有界、可验证、可恢复**的自主执行栈：底层是 `onmc loop`（`LoopEngine` 引擎），中层是 `onmc autopilot`（一次调用跑完整个 KNOW→PLAN(opt)→ACT→PROVE→LEARN 周期），再上层是 `onmc nomistakes`（PR 合并前的"不犯错"门禁），最新的 v0.49–v0.51 又叠加了 `onmc swarm`（并行可问责的子代理群）。所有这些构件共享同一套**记忆驱动 + 可证伪的预测-结果契约**。 如 [README.md](README.md) 所述，loop 不是用模型声明替代证明：只有当**循环收敛且最终的 verifier 退出码为 0** 时，该次运行才被记为 `verified`。模型自行宣称成功永远不能得到 verified 状态，这是 v0.50 "agent-error accountability fix" 之后的关键安全保证 [README.md](README.md)。 ## 2. Loop 引擎：基于记忆的迭代循环 ### 2.1 七步迭代协议 [`src/oh_no_my_claudecode/loop/engine.py`](src/oh_no_my_claudecode/loop/engine.py) 的模块级 docstring 明确列出了每一次迭代的七步： 1. **RECALL**：调用 `compile_guard`（拉取已知死胡同）和 `compile_prompt_recall`（拉取相关记忆）组装 brief 2. **PROMPT**：把 `goal + brief` 注入到 agent 提示词 3. **ACT**：通过 `AgentRunner` 调用 agent，得到 `AgentRunResult` 4. **VERIFY**：通过 `VerifyRunner` 执行 verifier 命令，得到 `VerifyOutcome` 5. **CONTRACT**：WIN → 写 `DECISION` 记忆；LOSS → 写 `FAILED_APPROACH` 记忆（**阻塞下一轮重蹈覆辙**） 6. **ESCALATE**：连续失败 ≥ `escalation_threshold` 时升级 escalation_level 7. **NO-PROGRESS**：相同 (files, verify_output) 签名在 `no_progress_window` 内重复 → 停止 这七步把"记忆"从一个被动的文本数据库变成**主动阻止重复失败的执行约束**。构建 brief 的逻辑（`build_brief`）严格遵循四段拼接：相关记忆 → 死胡同 → 上次失败摘要 → 升级提示；其中 recall 与 guard 都用 `try/except` 包裹，"best-effort，永不让循环因记忆不可用而崩溃" [engine.py](src/oh_no_my_claudecode/loop/engine.py)。 ### 2.2 数据模型与硬限制 [`loop/models.py`](src/oh_no_my_claudecode/loop/models.py) 定义了核心 dataclass： | 字段 | 含义 | |---|---| | `LoopSpec.goal` / `success_criteria` | 一次循环的目标与成功判据 | | `IterationContract` | 一次迭代的"预测-动作-文件-verify-结果"契约（可证伪） | | `LoopResult.converged` / `stop_reason` | 是否收敛及停止原因 | | `LoopConfig.max_iterations` / `budget_tokens` / `max_cost_usd` / `max_wall_seconds` / `duplicate_action_limit` | 硬限制，全部可被外部覆盖 | `max_cost_usd` 与 `max_wall_seconds` 的注释说明它们是**"在下一轮迭代前停止"**的守护参数，对应 README 中的"cost limits / wall-time limits"，同时也是 v0.46 "token-storm circuit breaker" 的实现入口 [models.py](src/oh_no_my_claudecode/loop/models.py)。 ### 2.3 Adapter 层：headless 真实 agent [`loop/adapters.py`](src/oh_no_my_claudecode/loop/adapters.py) 提供了三个 headless adapter，统一通过 `make_agent_runner("claude" | "codex" | "opencode", ...)` 工厂装配： - `ClaudeCliAdapter`：调用 `claude -p --output-format json`，解析结构化 JSON 提取文本、token、cost - `CodexCliAdapter`：调用 `codex exec `，stdout 即输出，headless 模式下不返回 token - `OpenCodeCliAdapter`（v0.43 起一等公民）：调用 `opencode run --format json`，对事件流做防御性解析 所有 adapter 通过对**调用前后两次 `git status --porcelain` 做 diff** 来派生 `files_touched`，避免凭空伪造文件列表；并接受可注入的 `CommandRunner` 以便测试时无需启动真实 agent [adapters.py](src/oh_no_my_claudecode/loop/adapters.py)。 ### 2.4 Checkpoint 与 Receipt：可恢复与可审计 [`loop/checkpoint.py`](src/oh_no_my_claudecode/loop/checkpoint.py) 暴露 `FileCheckpointStore` 与 `InMemoryCheckpointStore`，`CheckpointState` 保存中断时的 `LoopSpec` 哈希与上一次迭代状态——这是 v0.47 "durable checkpoint/resume" 的实现支撑，配合 `onmc loop --isolate --resume` 可在 worktree 中恢复运行 [loop/__init__.py](src/oh_no_my_claudecode/loop/__init__.py)。 [`loop/receipt.py`](src/oh_no_my_claudecode/loop/receipt.py) 把每次运行封装成 `RunReceipt`：包含**SHA-256 哈希链**、git tree SHA、diff SHA、verifier 命令与退出码、token/cost/耗时，以及 v0.44 引入的**reproducibility envelope**（模型/工具/配置哈希）。"Tamper-evident" 在这里的语义是：任何事后篡改都会改变 `receipt_hash`，但**不包含密码学签名**（Sigstore 等不在本期范围）。 ## 3. Autopilot、Swarm 与 No-Mistakes Gate ### 3.1 Autopilot：一个动词跑完全周期 `onmc autopilot ""` 是 `loop` 之上的编排层，对应 README 的"Full autopilot cycle"。它把： - KNOW：编译 brief（[brief.py](src/oh_no_my_claudecode/models/brief.py) 同时支持 markdown 与 caveman 两种渲染） - PLAN(opt)：v0.45 起支持 `--plan-with --execute-with ` 做"昂贵规划 + 廉价执行"成本拆分 - ACT / PROVE / LEARN：委托给 loop + verifier + receipt + skill_promote 结束时会输出 "your brain grew: +N memories · +N skills · N dead-ends known"。 ### 3.2 Loop 模板：开箱即用 [`loop/templates.py`](src/oh_no_my_claudecode/loop/templates.py) 提供了三个内置模板（v0.47 引入），通过 `onmc loop --template ` 装配默认值： | 模板 | 目标 | 默认 verifier | 默认迭代上限 | |---|---|---|---| | `ci-healer` | 修复失败 CI，不改公共行为 | `pytest`（可覆盖） | 15 | | `pr-babysitter` | 保持 PR 绿色（rebase / 解冲突 / 重跑） | `pytest` | 8 | | `issue-to-pr` | 把 issue 实现为 PR-ready 变更 | `pytest` | 20 | 任意显式 flag 都覆盖模板默认值。模板的存在让"昂贵 agent + 易出错决策"被预先降级为"标准化任务"。 ### 3.3 Swarm：token-free 并行扇出 v0.49 "parallel accountable agent swarm + hard abort" 与 v0.51 "in-session subagent swarm — token-free parallel fan-out" 是当前最高频被引用的新特性：swarm 在**同一会话内**派生子代理，**不再产生额外 token 计费**（因为复用父会话上下文），并且每条子代理路径都必须像 loop 一样满足相同的"可证伪契约 + verifier"才能算 verified——`hard abort` 保证任一子代理失控时整批中止。 ### 3.4 No-Mistakes PR Gate `onmc nomistakes ""`（v0.48 引入）是 PR 合并前的"非零退出才算数"门禁：依次跑 audit → eval（可选）→ 隔离的 autopilot → verifier → receipt 裁决；只有拿到 verified receipt 时命令才退出 0，否则非零退出码直接**阻塞 CI 合并**。这与 v0.50 的修复（agent auth/API 错误永远不能被记为 verified）一起，构成 "accountable" 的最后一道防线 [README.md](README.md)。 ## 4. 典型数据流与失败模式 ```mermaid flowchart LR A[goal + LoopSpec] --> B[build_brief
recall + guard + last_loss] B --> C[AgentRunner
claude/codex/opencode] C --> D[git diff
files_touched] C --> E[VerifyRunner] E -- pass --> F[WIN → DECISION 记忆] E -- fail --> G[LOSS → FAILED_APPROACH
阻塞下一轮] G --> H{escalation / no-progress
/ cost / wall-time?} H -- 继续 --> B H -- 停止 --> I[CheckpointStore] I --> J[RunReceipt
hash chain + git SHA + envelope] J --> K{verified?} K -- yes --> L[nomistakes 放行] K -- no --> M[CI 阻断] ``` 常见失败模式与缓解： - **Agent API/auth 错误被误报为 verified**：v0.50 修复点，详见 [release notes v0.50.0](https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.50.0) - **Token 风暴**：v0.46 引入 circuit breaker + worktree 隔离/回滚；触发条件由 `LoopConfig` 中各硬限制协同判定 - **死循环重试同一动作**：`duplicate_action_limit` + `no_progress_window` 双重保险 - **跨代理复用不可控**：v0.49 `hard abort` 保证 swarm 任一失败立即熔断整批 ## See Also - [Loop 数据模型与配置](loop-models.md) - [Receipt 与 Reproducibility Envelope](loop-receipt.md) - [Swarm 与 No-Mistakes Gate 设计](swarm-nomistakes.md) - [Project README](README.md) - [CHANGELOG.md](CHANGELOG.md) --- ## Repository Memory, Briefs, Guards & Sync ### 相关页面 相关主题：[Introduction & Quick Start](#page-overview), [Autonomous Loops, Autopilot, Swarm & No-Mistakes Gate](#page-execution)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md) - [src/oh_no_my_claudecode/ingest/llm_extractor.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/llm_extractor.py) - [src/oh_no_my_claudecode/ingest/repo_tree.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/repo_tree.py) - [src/oh_no_my_claudecode/ingest/pipeline.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/pipeline.py) - [src/oh_no_my_claudecode/ingest/docs.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/docs.py) - [src/oh_no_my_claudecode/importers/markdown.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/markdown.py) - [src/oh_no_my_claudecode/importers/hermes.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/hermes.py) - [src/oh_no_my_claudecode/loop/engine.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/engine.py) - [src/oh_no_my_claudecode/hooks/boot_digest.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/boot_digest.py) - [src/oh_no_my_claudecode/models/brief.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/models/brief.py)
# Repository Memory, Briefs, Guards & Sync ## 概述 `oh-no-my-claudecode` (简称 onmc) 是一个本地优先的代码库记忆系统，核心目标是为 AI 代理（Claude Code、Codex、Cursor、OpenCode 等）提供持久化、结构化的「仓库大脑」。整个系统围绕 **Memory（记忆摄取）→ Brief（任务简报）→ Guard（死路守卫）→ Sync（便携同步）** 四个环节构建，使代理在执行任务时能够检索相关历史经验、避开已知的失败路径，并通过 `.agent-memory/` 这一人类可读的 JSON 目录实现跨代理、跨仓库的记忆共享（[README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md)）。 ```mermaid graph LR A[扫描代码树] --> B[摄取流水线] C[Git历史] --> B D[文档解析] --> B E[LLM提取器] --> B B --> F[(SQLite 记忆存储)] F --> G[任务简报 Brief] F --> H[守卫 Guard] F --> I[循环引擎 Loop] F --> J[导入器/同步] J --> K[.agent-memory/] K --> F ``` ## 记忆摄取流水线 摄取阶段把代码库、Git 历史与文档三类原始信号转化为结构化的 `MemoryEntry`，存储到本地 SQLite。 **代码树扫描**：`scan_repository_files` 遍历仓库，过滤 `exclude_dirs`（例如 `.onmc/`、`.git/`），为每个文件产出 `RepoFileRecord`（含路径、扩展名、是否为测试、字节数），供后续路径分桶与 LLM 提取使用。资料来源：[src/oh_no_my_claudecode/ingest/repo_tree.py:1-40]() **Git 与文档摄取**：`pipeline.py` 协调 `_git_memories_for_paths` 等函数，把 Git 提交、文件统计结果映射为 `DECISION`/`HOTSPOT`/`GIT_PATTERN` 等记忆类型；`docs.py` 通过可配置的 glob 列表发现文档（默认排除多语言 README/CHANGELOG/CONTRIBUTING 与 TOC 章节），输出 `DOC_FACT` 类条目。资料来源：[src/oh_no_my_claudecode/ingest/docs.py:1-30]()、[src/oh_no_my_claudecode/ingest/pipeline.py:1-40]() **LLM 提取器**：`llm_extractor.py` 实现了基于 LLM 的批处理提取。它对提交、源代码、文档分别构造专用 prompt（`_commit_prompt` / `_source_file_prompt` / `_doc_prompt`），并通过 `should_run_source_extraction` 守卫仅当提交提取结果不足 8 条时才进入源码文件提取阶段。每个返回条目需达到最低置信度阈值（提交 0.7，源/文档 0.75），否则被丢弃。提取失败（超时或异常）的批次会被记录到 `warnings` 而不会中断整个流水线。资料来源：[src/oh_no_my_claudecode/ingest/llm_extractor.py:1-80]() ## 任务简报与守卫 摄取完成后，系统在两个关键节点使用这些记忆：**启动摘要（boot digest）** 与 **循环引擎（loop engine）**。 **Brief 模型**：`models/brief.py` 定义了 `Brief` 数据类，包含 `files_to_inspect`、`relevant_memories`、`risk_notes`、`validation_checklist` 等字段，并提供完整 Markdown 与「caveman」极简两种输出形态。极简模式强制代理「先读列出的文件，不做无差别 grep，不重复已失败的路径」，是减少 token 浪费的关键约束。资料来源：[src/oh_no_my_claudecode/models/brief.py:1-50]() **Boot Digest**：`hooks/boot_digest.py` 在代理启动时按优先级组装上下文：用户偏好 → 项目档案（由 `invariants`/`hotspots` 派生）→ 关键不变量与决策 → 活跃任务 → 常用技能，再通过 `_firewall_emit_boot_recall` 与 `_firewall_emit_profile_injected` 触发外部防火墙事件。资料来源：[src/oh_no_my_claudecode/hooks/boot_digest.py:1-50]() **Loop 守卫**：`loop/engine.py` 的每次迭代先调用 `compile_guard` 编译「死路」清单（来自 `FAILED_APPROACH` 类记忆），再结合 `compile_prompt_recall` 注入相关记忆，最后把上一次失败的 `action_summary` 与 `verify_output` 作为具体反馈写入下一轮 prompt；当 `verify_output` 在 `no_progress_window` 轮内重复时停止迭代。资料来源：[src/oh_no_my_claudecode/loop/engine.py:1-60]() ## 跨代理导入与便携同步 为了在不同代理生态之间复用记忆，onmc 提供了一组纯解析导入器与导出器，**不直接访问数据库**。 | 导入器 | 输入 | 产出 | | --- | --- | --- | | `markdown.py` | 单个或目录下的 `*.md` 文件 | `Skill`（默认）或 `MemoryEntry`（按 `##` 切片） | | `hermes.py` | Nous hermes-agent 的 `MEMORY.md` / `USER.md` | `MemoryEntry`，按关键词映射为 `DECISION`/`GOTCHA`/`FAILED_APPROACH` 等 | 资料来源：[src/oh_no_my_claudecode/importers/markdown.py:1-30]()、[src/oh_no_my_claudecode/importers/hermes.py:1-40]() **同步导出**：根据 `README.md` 的说明，`onmc sync --commit` 把内部 SQLite 中的记忆以人类可读的 JSON 写入 `.agent-memory/`，可选择性提交到 git 供团队协作或迁移到新环境；该目录同时承载 `CLAUDE.md` 项目上下文与「最新 brief」，是仓库大脑对外的便携形式（[README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md)）。 ## 常见失效模式 - **LLM 批次超时**：当配置的外接模型返回超时时，`llm_extractor` 仅记录警告并跳过该批次，不会让摄取完全失败，但可能导致某些提交未被结构化提取。资料来源：[src/oh_no_my_claudecode/ingest/llm_extractor.py:1-80]() - **极简简报信息不足**：当 `relevant_memories` 为空时，`_to_caveman_markdown` 会输出「No strong memory. Use files + tests.」，依赖代理遵循规则读取 `files_to_inspect`；若该列表本身缺失，代理可能回退到无差别搜索。资料来源：[src/oh_no_my_claudecode/models/brief.py:1-50]() - **导入器无 DB 访问**：`markdown.py` 与 `hermes.py` 明确说明「No DB access — pure parsing」，因此导入结果需要经过一次 `ingest` 或显式写入才会进入 SQLite，影响后续 Brief 召回。资料来源：[src/oh_no_my_claudecode/importers/markdown.py:1-30]() ## See Also - [Repository Brain Architecture（仓库大脑架构）](#) - [CLI Reference（CLI 参考）](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/cli-reference.md) - [Loop Engine（循环引擎）](#) - [Skill Export & Agent Skills SKILL.md（技能导出）](#) --- ## Cross-Agent Plug, MCP Server, Hooks & Skill Export ### 相关页面 相关主题：[Introduction & Quick Start](#page-overview), [Autonomous Loops, Autopilot, Swarm & No-Mistakes Gate](#page-execution)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md) - [src/oh_no_my_claudecode/loop/adapters.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/adapters.py) - [src/oh_no_my_claudecode/loop/engine.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/engine.py) - [src/oh_no_my_claudecode/loop/models.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/models.py) - [src/oh_no_my_claudecode/importers/__init__.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/__init__.py) - [src/oh_no_my_claudecode/importers/markdown.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/markdown.py) - [src/oh_no_my_claudecode/importers/hermes.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/hermes.py) - [src/oh_no_my_claudecode/importers/base.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/base.py) - [src/oh_no_my_claudecode/ingest/llm_extractor.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/llm_extractor.py) - [src/oh_no_my_claudecode/llm/base.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/llm/base.py) - [src/oh_no_my_claudecode/models/brief.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/models/brief.py)
# Cross-Agent Plug, MCP Server, Hooks & Skill Export ## 1. 概述 ONMC（oh-no-my-claudecode）通过四个相互衔接的子系统，让本地仓库记忆与外部智能体生态互通：（1）`onmc plug` 跨代理 headless 适配层；（2）`onmc serve --mcp` 暴露的 MCP 工具集（`recall` / `search_memory` / `get_brief` / `guard_task` / `record_attempt` / `record_memory` / `get_coverage` / `get_digest` / `get_skills` / `get_profile` / `ask` 等 12 个工具）；（3）`onmc hook` 会话钩子；（4）`onmc skill export` 技能导出与 `onmc import` 导入。社区在 v0.43（首类 OpenCode 适配器）与 v0.42（Agent Skills `SKILL.md` 导出，16+ 工具）显著扩展了这一层。资料来源：[README.md:80-130]() ## 2. Cross-Agent Plug：真实 headless 适配器 `onmc plug` 子命令背后的实现位于 `src/oh_no_my_claudecode/loop/adapters.py`，由工厂函数 `make_agent_runner(name, repo_root, ...)` 返回统一签名的可调用对象： | 适配器 | 调用的 CLI | 解析方式 | | --- | --- | --- | | `ClaudeCliAdapter` | `claude -p --output-format json` | 解析 JSON 抽取文本、tokens 与 cost | | `CodexCliAdapter` | `codex exec `（headless） | 返回原始 stdout；token 用量不可用 | | `OpenCodeCliAdapter` | `opencode run --format json [--model provider/model] ` | 防御性解析 JSON 事件流 | 三个适配器均通过对调用前后的两次 `git status --porcelain` 快照做 diff 得到 `files_touched`，从而保证文件清单来自真实工作树而非凭空捏造；同时接受可注入的 `CommandRunner`，让测试无需拉起真实代理进程。资料来源：[src/oh_no_my_claudecode/loop/adapters.py:1-35]() 这些适配器在 `loop/engine.py` 的迭代循环中被调用，依次执行 RECALL → PROMPT → ACT → VERIFY → CONTRACT → ESCALATE → NO-PROGRESS；ACT 步骤会触发 `agent_runner(prompt, escalation_level)` 并把退出结果封装进 `IterationContract`（含 `prediction / action_summary / files_touched / verify_passed / outcome / tokens`）。资料来源：[src/oh_no_my_claudecode/loop/engine.py:1-15]() / [src/oh_no_my_claudecode/loop/models.py:20-70]() `LoopConfig` 还提供 `max_cost_usd` / `max_wall_seconds` / `duplicate_action_limit` 等停机门禁，分别在累计成本、超时、重复动作时强制停止。资料来源：[src/oh_no_my_claudecode/loop/models.py:60-80]() ## 3. Skill Export 与跨工具导入 外联通道的另一端是技能/记忆的导入导出。顶层入口 `run_import(storage, source, path, *, dry_run, as_kind, cwd)` 位于 `importers/__init__.py`，按 `source` 派发到不同子模块： - `omc`：读取 `.omc/skills/*.md`，每条转换为 `Skill` 对象，标签为 `imported:omc`。 - `hermes`：解析 Nous hermes-agent 的 `MEMORY.md` / `USER.md`，按 `##` 段落拆分为 `MemoryEntry` 记录，标签为 `imported:hermes`；条目根据标题文本启发式映射到 `MemoryKind`（含 `decision` / `invariant` / `gotcha` / `failed` 等子串匹配）。资料来源：[src/oh_no_my_claudecode/importers/hermes.py:1-30]() - ``：通用 `.md` 文件或目录，默认按 skill 导入；传 `--as memory` 时按 `##` 段拆分为记忆，标签为 `imported:md`。资料来源：[src/oh_no_my_claudecode/importers/markdown.py:1-25]() `ImportResult` 数据类（`importers/base.py`）统一返回 `source / as_kind / imported / skipped / dry_run / items` 五个字段，供 CLI 与服务层共用。资料来源：[src/oh_no_my_claudecode/importers/base.py:10-30]() 反向方向，`onmc skill export` 会把已学习技能输出为符合 agentskills.io 标准的 `SKILL.md`，供 Claude Code、Codex、Cursor、OpenCode 等其他代理直接消费，形成"一处记忆，多端复用"。 ## 4. LLM 驱动的结构化抽取 导入与导出的中游是 `ingest/llm_extractor.py`：当 LLM 提供方被显式启用时，它会把源码、提交、文档批量送入提示词，分别抽取四类知识： - `invariant` — 含 `must / never / always` 等注释或 ALL_CAPS 常量； - `gotcha` — TODO/FIXME/WARNING/`DO NOT` 注释； - `validation_rule` — 测试函数名与断言模式； - `decision` — 架构选择或带 `we decided` / `rationale` 的描述。 `_doc_prompt` / `_source_file_prompt` / `_commit_prompt` 三套模板均要求返回置信度 ≥ 0.7 / 0.75 的 JSON 数组，并显式禁止通用编程建议；`commit_lines_from_payload` 将原始 commit 字典归一化为 ` | | files: ...` 单行字符串，便于批量推理。资料来源：[src/oh_no_my_claudecode/ingest/llm_extractor.py:30-200]() `llm/base.py` 中的 `generate_structured` 把 JSON 响应解析成 Pydantic 模型，失败时抛出 `LLMProviderError`；这保证从 LLM 抽取的内容可被回写进本地 SQLite 记忆库（`.onmc/`），成为后续 `onmc brief` / `onmc recall` 的事实来源。资料来源：[src/oh_no_my_claudecode/llm/base.py:20-60]() ## 5. 记忆→简报→钩子→外部代理 用户最终感知到的形态是 `models/brief.py` 生成的紧凑简报：它把任务、相关记忆、风险与校验清单压成"caveman"短文（首 5 个文件 + 3 条记忆 + 3 条风险 + 3 条测试 + 1 条规则），供 `onmc brief` 与 `onmc hook` 在代理会话中按需注入。资料来源：[src/oh_no_my_claudecode/models/brief.py:1-40]() 整体数据流可由下图概括： ```mermaid flowchart LR A["外部代理
Claude / Codex / OpenCode"] -->|plug adapter| B["loop engine"] B -->|RUNNER| C["verify command"] B -->|记录 WIN/LOSS| D[("本地 SQLite
.onmc/")] D -->|brief| E["onmc hook / MCP"] E -->|SKILL.md| F["onmc skill export"] F -->|import omc/hermes/md| A G["LLM 提供方"] -->|结构化抽取| D ``` ## 6. 常见配置与失败模式 - `onmc plug` 适配器依赖对应 CLI 在 PATH 中；缺失 `claude` / `codex` / `opencode` 会直接抛出 `FileNotFoundError`，建议在代理宿主而非 CI 中运行。 - `ImportResult.skipped` 反映基于 `stable_id` 的去重，重复导入同名 skill 安全无副作用。 - LLM 抽取在 `generate_structured` 中若返回非 JSON 或结构不符，会记录原始响应前 500 字符并抛出 `LLMProviderError`；无 LLM 模式下，记忆回退为启发式分段而非空集。 - 钩子注入的 `brief` 是只读上下文，不会回写到 `.onmc/`；实际记忆更新仍须经由 `onmc record` 或 loop 引擎的 WIN/LOSS 通道。 ## 参见 - [Architecture](docs/architecture.md) - [Memory model](docs/memory-model.md) - [Agent-native workflows](docs/agent-native-workflows.md) - [CLI reference](docs/cli-reference.md) - [Integration guides](docs/integrations/README.md) --- --- ## Doramagic 踩坑日志 项目：adaline-ankit/oh-no-my-claudecode 摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v0.48.0。 ## 1. 安装坑 · 失败模式：installation: v0.48.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.48.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.48.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.48.0 | v0.48.0 ## 2. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/adaline-ankit/oh-no-my-claudecode | host_targets=claude_code, claude, mcp_host ## 3. 配置坑 · 失败模式：configuration: v0.42.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.42.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.42.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.42.0 | v0.42.0 ## 4. 配置坑 · 失败模式：configuration: v0.43.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.43.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.43.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.43.0 | v0.43.0 ## 5. 配置坑 · 失败模式：configuration: v0.44.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.44.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.44.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.44.0 | v0.44.0 ## 6. 配置坑 · 失败模式：configuration: v0.45.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.45.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.45.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.45.0 | v0.45.0 ## 7. 配置坑 · 失败模式：configuration: v0.46.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.46.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.46.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.46.0 | v0.46.0 ## 8. 配置坑 · 失败模式：configuration: v0.47.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.47.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.47.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.47.0 | v0.47.0 ## 9. 配置坑 · 失败模式：configuration: v0.49.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.49.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.49.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.49.0 | v0.49.0 ## 10. 配置坑 · 失败模式：configuration: v0.50.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.50.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.50.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.50.0 | v0.50.0 ## 11. 配置坑 · 失败模式：configuration: v0.51.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.51.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.51.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.51.0 | v0.51.0 ## 12. 配置坑 · 失败模式：configuration: v0.52.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.52.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.52.0 - 证据：failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.52.0 | v0.52.0 ## 13. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/adaline-ankit/oh-no-my-claudecode | README/documentation is current enough for a first validation pass. ## 14. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/adaline-ankit/oh-no-my-claudecode | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/adaline-ankit/oh-no-my-claudecode | no_demo; severity=medium ## 16. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/adaline-ankit/oh-no-my-claudecode | no_demo; severity=medium ## 17. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/adaline-ankit/oh-no-my-claudecode | issue_or_pr_quality=unknown ## 18. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/adaline-ankit/oh-no-my-claudecode | release_recency=unknown