![\"OpenWolf](\"demo.gif\")
\n\n \n
\n 你的 Agent 会换，项目记忆不该跟着重置。\n
\n\n\n 在 Claude Code、Codex 和 OpenCode 之间共享项目记忆，
\n 从真实会话记录测量 Token 使用；完全本地，无 API 调用。\n
\n ![\"npm](\"https://img.shields.io/npm/v/@alptech/openwolf.svg\")
\n ![\"License:](\"https://img.shields.io/badge/License-AGPL--3.0-blue.svg\"){kind=icon}
\n ![\"Node.js\"](\"https://img.shields.io/badge/Node.js-20%2B-green.svg\"){kind=icon}
\n
\n English ·\n 中文 ·\n 日本語 ·\n Русский\n
\n\n> **本仓库是 [openwolf](https://github.com/cytostack/openwolf)（[Cytostack](https://github.com/cytostack)）的 fork。** 同步上游业务能力，并保留 `@alptech/openwolf` 包名与项目身份。\n\n---\n\n| 没有 OpenWolf | 有 OpenWolf |\n|---|---|\n| Agent 重复读取已看过的文件（约 2,000 tokens） | 先读一行描述，或直接跳过读取 |\n| 为找一个函数读完整文件 | 符号级提示给出精确行号，支持 `offset`/`limit` |\n| 上下文压缩会丢掉本轮工作 | PreCompact 快照与恢复，压缩后仍可续作 |\n| 每个 Agent 都从冷启动开始 | 共享同一套 `.wolf/` 大脑（Codex / OpenCode / Claude Code / Cursor / Antigravity 等） |\n| 不知道 Token 花在哪里 | 从 harness 转录读取实测用量，并提供本地 Dashboard |\n\n---\n\n## 为什么需要 OpenWolf？\n\n编程 Agent 很强，但默认是“盲操作”：不知道文件内容与体量，会在同一次会话里重复读文件，跨会话忘记你的纠正，上下文压缩后又像失忆。\n\nOpenWolf 通过持久、共享的项目记忆解决这些问题：\n\n- **上下文管理**：会话开始注入预算受限的高价值摘要；PreCompact + 压缩后重启，避免工作进度被抹掉。\n- **架构脚手架**：可自愈的项目索引，含描述、Token 估算，大文件还有函数/类与行号范围。\n- **Token 利用**：拦截重复读取，整文件读变切片读，并从 harness 转录测量真实用量。\n\n## 快速开始\n\n```bash\nnpm install -g @alptech/openwolf\ncd your-project\nopenwolf init\n```\n\n不传 `--agent` 时，`init` 会接入 Claude Code，并自动检测本机安装的其他编程 Agent。传入 `--agent` 时，只接入明确指定的 Agent。\n\n## 支持的 Agent\n\n| Agent | 集成方式 | 深度 |\n|-------|----------|------|\n| **Codex CLI** | `.codex/hooks.json` 生命周期 Hook + `AGENTS.md` | 完整（Hook + 上下文） |\n| **OpenCode** | 原生插件 + `AGENTS.md` | 完整（Hook + 上下文） |\n| **Claude Code** | 12 个生命周期 Hook + `CLAUDE.md` | 完整（Hook + 上下文） |\n| **Cursor** | `.cursor/rules/openwolf.mdc`（始终应用） | Beta（上下文） |\n| **Antigravity** | `AGENTS.md` 协议块 | Beta（上下文） |\n| **Gemini CLI** | `GEMINI.md` 协议块 | Beta（上下文） |\n\n```bash\nopenwolf init # Claude + 自动检测其他已安装 Agent（推荐）\nopenwolf init --agent claude # 仅 Claude Code\nopenwolf init --agent codex # 仅 Codex\nopenwolf init --agent opencode # 仅 OpenCode\nopenwolf init --agent gemini # 仅 Gemini CLI\nopenwolf init --agent cursor # 仅 Cursor\nopenwolf init --agent antigravity # 仅 Antigravity\nopenwolf init --agent codex opencode # 仅 Codex 和 OpenCode\nopenwolf init --agent all # 全部受支持 Agent\n```\n\n显式参数会严格生效：例如 `--agent codex` 不会创建 Claude、OpenCode、Gemini、Cursor 或 Antigravity 配置。重新执行 `init` 不会删除项目中原本就存在的其他 Agent 文件。\n\n协议块使用 marker 围栏：不会改动你自己写在 `AGENTS.md` / `GEMINI.md` 中的内容，重复执行 `init` 也不会重复插入。\n\n## 会创建什么\n\n`openwolf init` 会在项目中创建 `.wolf/`：\n\n| 文件 | 作用 |\n|------|------|\n| `anatomy-index.json` | 持久化项目索引：描述、Token 估算、内容哈希、符号 |\n| `anatomy.md` | 索引的可读渲染，自动保持同步 |\n| `cerebrum.md` | 学习记忆：偏好、纠正、Do-Not-Repeat |\n| `memory.md` | 按时间顺序的操作日志与 Token 估算 |\n| `STATUS.md` | 会话交接：少量阅读即可恢复进度 |\n| `buglog.json` | Bug 修复记忆，可搜索，避免重复踩坑 |\n| `token-ledger.json` | 估算与实测 Token 用量（按会话/Agent） |\n| `hooks/` | 12 个生命周期 Hook（纯 Node.js，零依赖） |\n| `config.json` | 配置，含各 Agent 上下文预算 |\n| `OPENWOLF.md` | Agent 需遵循的操作协议 |\n\n## 工作原理\n\n```\n会话开始\n |\nOpenWolf 注入受 Token 预算限制的摘要：当前目标、已知错误、近期修复、项目地图指针\n |\nAgent 准备读取大文件\n |\nOpenWolf: \"auth.ts (~2,900 tok)。符号: validateToken L82-140 ~450 tok。\n可用 offset/limit 只读需要的部分。\"\n |\nAgent 编辑文件\n |\nOpenWolf 在跨进程锁下更新索引、记录动作、估算成本\n |\n会话中发生上下文压缩\n |\nOpenWolf 在压缩前快照，压缩后重新注入已修改文件摘要，避免重复劳动\n |\n会话结束\n |\nOpenWolf 从转录中读取真实 Token 用量写入 ledger\n```\n\n## 上下文管理\n\n- **会话摘要**：在可配置的每 Agent Token 预算内注入最高价值状态。\n- **压缩存活**：PreCompact 快照 + 压缩后摘要，续作不再从零开始。\n- **过期检测**：扫描会钉住 git HEAD；HEAD 变动或扫描过期时会提示重扫。\n- **STATUS.md 交接**：阶段结束状态集中在一个小文件，新会话一次读取即可恢复。\n\n## 项目 Anatomy\n\n索引以 `anatomy-index.json` 持久化，并以 `anatomy.md` 可读呈现。写操作通过跨进程锁协调；对手写或旧版 Hook 修改的 markdown，会按内容哈希做增量吸收。\n\n估算超过 500 tokens 的文件还会索引顶层符号：\n\n```\n- `shared.ts` (~3,200 tok)\n - fn `parseAnatomy` L82-104 (~180 tok)\n - fn `serializeAnatomy` L106-129 (~200 tok)\n```\n\n当前支持符号提取的语言：TypeScript、JavaScript、Python、Go、Rust。\n\n## Token 智能\n\n估算有用，测量更可信。会话结束时 OpenWolf 从 harness 转录读取真实用量：input / output / cache read / cache write / API 调用次数，并归属到对应 Agent。\n\n```bash\nopenwolf report\n```\n\n1.x 实战数据（20 个项目、132+ 会话）平均估算节省约 65.8% Token，71% 的重复读被拦截。2.x 起可用实测数据在你自己的工作负载上验证。\n\n## 安全\n\n- Dashboard 仅绑定 `127.0.0.1`，API/WebSocket 使用每项目 token（时序安全比较）\n- 动态进程调用一律参数数组，无 shell 拼接\n- Cron 文件访问有路径穿越防护（realpath，符号链接安全）\n- 密钥类文件（keys、keystore、credential、`.npmrc`、`.env` 等）不进入索引与 memory\n- `pnpm test` 包含安全回归套件\n\n## 内置 Skills\n\n`openwolf init` 会为已配置 Agent（Claude Code、Codex、OpenCode）安装：\n\n- **`/handoff`**：根据 Git、操作日志与未完成事项重新生成 `STATUS.md`\n- **`/security-audit [scope]`**：依赖、密钥、注入面、鉴权等分层审计，结果写入 `.wolf/buglog.json`\n- **`/reframe [migrate | audit | fix]`**：UI 框架选型/迁移与反“AI 味”设计审计（含 13 个框架知识库）\n\n## Dashboard\n\n```bash\nopenwolf daemon start\nopenwolf dashboard\n```\n\n本地、需 token 认证的控制台：估算 vs 实测 Token、缓存经济、按 Agent 用量、上下文健康、会话交接、实时活动、cron 控制、带符号的 anatomy 浏览器。\n\n## 命令\n\n```\nopenwolf init 初始化 .wolf/ 并接入检测到的 Agent\nopenwolf status 健康状态、统计、文件完整性\nopenwolf scan 重建项目索引\nopenwolf scan --check 校验索引是否与文件系统一致（适合 CI）\nopenwolf report Token 报告：估算 vs 实测\nopenwolf bench 对照测试启用/禁用 OpenWolf 的真实成本与完成率\nopenwolf map 按重要性生成有 Token 预算的项目概览\nopenwolf find