mmnto-ai/totem

# 图腾 _AI 编码代理是优秀的金鱼。Totem 是它们持久化、跨仓库的记忆。_ 在使用大型语言模型处理项目时，我发现代理不断犯同样的架构错误。它们忘记上下文，并重新发明已经存在的辅助工具。速度很快，但架构完整性很快退化。每个 PR 都变成了与审查机器人就琐事的反复拉锯。 它们可以让错误的方式看起来精彩（直到你意识到发生了什么）。它们很少会问：_“难道已经存在一个共享的辅助工具了吗？”_ Totem 是为了解决这种摩擦而提取出来的。它是一套 CLI 工具，为 AI 代理提供持久化内存和强制执行层。它使用确定性钩子来记住 AI 忘记的教训。 - [文档仅是一种建议](#documentation-is-merely-a-suggestion) - [错误如何变成规则](#how-mistakes-become-rules) - [记忆层](#the-memory-layer) - [盒中有什么](#whats-in-the-box) - [有效与无效的实践](#what-works-and-what-doesnt) - [快速入门](#quickstart) - [立即体验](#try-it-live) - [文档与工作流](#documentation--workflows) ## 文档仅是一种建议 我尝试了那种规定代理每一步工作流程的沉重编排方法，发现它僵硬且会破坏人类参与的动态。Totem 基于不同的哲学构建：**触发线，而非轨道。** 你提供一个被电围栏包围的开放场地。LLM 可以自由地以任何方式编码，但当它试图改变世界的永久状态时（例如 `git push`），它会撞上确定性触发线。 Totem 将纯英文课程说明转化为物理约束，由一个本地的、零 LLM 的代码检查工具强制执行： **输入：**（`.totem/lessons/no-child-process.md`） ``` ## 课程 - 永远不要使用原生子进程 Tags: architecture Direct use of `node:child_process` is forbidden outside `core/src/sys/`. Use the `safeExec` shared helper instead. ``` **输出：**（`git push` 在代理机器上被阻止） ``` $ git push [Lint] Running 393 rules (zero LLM)... ### 警告 - **packages/cli/src/git.ts:22** - Never use native child_process Pattern: `import { execSync } from 'node:child_process'` Lesson: "Direct use of `node:child_process` is forbidden outside `core/src/sys/`. Use the `safeExec` shared helper instead." [Lint] Verdict: FAIL - Fix violations before pushing. ``` “错误”的方式变成了“嘈杂”的方式。运行时没有 LLM 介入。只是亚秒级的离线强制执行。 ## 错误如何变成规则 核心循环很简单。一个错误在 PR 审查、机器人检查或生产 Bug 中被捕获。我写一份纯英文的课程说明，解释哪里出了问题。`totem compile` 将课程说明转换为 AST 或正则规则，`totem lint` 在此后每次推送时强制执行该规则。同样的错误永远不会再发生。 ``` graph LR Catch["Catch a mistake"] -->|write a lesson| Compile["totem compile"] Compile -->|generates rule| Enforce["totem lint"] Enforce -->|catches next attempt| Catch style Catch fill:#4b3a75,stroke:#9b72cf,color:#fff style Compile fill:#5e3a24,stroke:#e67c3b,color:#fff style Enforce fill:#1a4d2e,stroke:#34a853,color:#fff ``` 当规则匹配注释或字符串字面量而不是实际代码时，`totem doctor` 会将其标记为嘈杂，并通过上下文遥测建议升级。`totem compile --upgrade` 会使用针对精度优化的提示重新运行编译器。我宁愿有 300 条精确规则，也不愿有 1000 条嘈杂规则。 ## 记忆层 默认情况下，AI 代理是无状态的。每个新会话都从零开始，没有任何对先前事件或已编写共享辅助工具的记忆。你最终不得不反复解释相同的上下文。 Totem 通过将你的课程说明和 ADR 编入本地语义知识库（Tree-sitter + LanceDB）来解决这个问题。该索引以纯文件形式保留在你的仓库中，因此没有云依赖，也没有供应商锁定。 任何兼容 MCP 的代理都可以查询它：Claude、Gemini、Cursor、Windsurf、GitHub Copilot。在你的代理编写代码行之前，它可以询问“此代码库中有哪些禁止的模式？”或“认证系统的架构是什么？”，并获得基于你项目实际历史的真实答案。 通过[跨仓库网格](docs/wiki/cross-repo-mesh.md)，你可以在兄弟仓库之间进行联合搜索。一个仓库的课程说明可以被所有关联仓库查询，因此上下文不会在仓库边界处停止。 ## 盒中有什么 Totem 是一套 CLI 工具，而不是一个框架。你可以将构建模块连接到你已有的任何 CI 和工作流中。每个命令都支持 `--json` 以用于脚本编写。 | 命令 | 功能 | |------|------| | `totem lint` | 在你的代码上运行所有已编译的规则。零 LLM、离线、亚秒级。 | | `totem compile` | 将纯英文课程说明转换为 AST 或正则规则。 | | `totem extract` | 从 PR 审查和机器人评论中提取课程说明。 | | `totem doctor` | 通过上下文遥测标记嘈杂规则，并建议升级。 | | `totem spec` | 在接触任何代码之前从 GitHub 问题生成实现说明（LLM 驱动，需要 API 密钥）。 | | `totem review` | 在未提交的差异上进行 LLM 驱动的架构审查（需要 API 密钥）。 | | `totem sync` | 从你的课程说明和文档中重建语义索引。 | | `totem hooks` | 安装 Git 钩子（`pre-push` 审查门控）。 | 内置的 MCP 服务器将知识库暴露给任何兼容代理。这是相同的索引，无需额外设置。 ## CI/CD 与 GitHub 集成 因为 `totem lint` 是确定性的且运行时间不到两秒，它可以无缝地集成到 CI 流水线中。三种输出格式分别为：`text`（默认）、`json`（用于脚本编写）和 `sarif`（用于安全仪表板）： ``` totem lint --format sarif --out totem.sarif ``` 将 SARIF 文件通过标准 `github/codeql-action/upload-sarif` 操作或任何兼容 SARIF 的工具传入 GitHub Code Scanning，Totle 的触发线会作为内联 PR 注解显示在违反规则的代码旁边。该流被刻意限制为仅错误严重性的发现，以防止 PR 审查被暂挂警告淹没。警告会保留为本地遥测数据，直到规则积累足够信号后才升级。 相同的 `--format sarif` 标志也适用于无需 Node.js 的独立 `totem-lite` 二进制文件。CI/CD 集成请参考[CI/CD 集成](https://github.com/mmnto-ai/totem/blob/main/docs/wiki/ci-integration.md)中的流水线配方。 ## 有效与无效的实践 Totem 有三个层次，我想诚实地说明每个层次的现状： 1. **强制执行层有效。** 已编译的规则和 Git 钩子能在不到 2 秒内机械且离线地捕获违规。这是所有其他功能所依赖的承重地板。该地板上的任何内容都不会接触网络，因此可以在隔离环境中原生运行。不会有源代码离开你的机器。 2. **规划层也有效，这让我惊讶。** 在代理编写任何代码之前，`totem spec` 会提取 GitHub 问题正文并查询知识库以获取相关的课程说明和 ADR。它会编写一份结构化的实现说明到 `.totem/specs/.md`。该说明包含架构上下文、需要检查的文件、问题描述中遗漏的边缘情况，以及内联注入的已检索课程说明作为不变量的任务驱动 TDD 指令。这些都不是硬性触发线。代理可以编写模糊的说明并忽略检索到的上下文。但在实践中，结构化的提示可靠地抓住了“即将重新发明一个已存在的辅助工具”的情况，这在我最初添加它之前并未预料到。速度和架构一致性中很大一部分来自这个上游门控，比我最初添加时预期的更多。 3. **记忆层是真实的基础设施。** 索引确实存在。它是跨仓库可移植的，任何 MCP 代理都可以查询它。但代理**持续地**基于检索到的上下文采取行动，是一个我正在积极研究的开放问题。可用性是确定性的，但代理的纪律性不是。 我构建强制执行层是因为上游层次本身并不足够。代理可以拥有干净的说明、上下文中的相关课程说明，但仍会在深入任务时偏离。触发线捕获了规划和记忆层遗漏的内容。这就是为什么将它们保持为三个独立层次而不是一个的原因：每一层都在工作流的不同阶段以不同的方式捕获故障类别。 ## 更新日志 请查看[版本发布](https://github.com/mmnto-ai/totem/releases)了解最新更新。 ## 快速入门 在任何项目（Node、Python、Go、Rust）中初始化 Totem： ``` pnpm dlx @mmnto/cli init ``` 这会生成 `totem.config.ts` 并连接 `pre-push` Git 钩子。它还会安装基线规则包。 运行代码检查器（零设置、离线）： ``` pnpm dlx @mmnto/cli lint ``` ### 独立二进制文件（无需 Node.js） 如果你在非 JavaScript 生态系统中工作（Rust、Go、Python）且不想安装 Node.js，你可以从[版本发布](https://github.com/mmnto-ai/totem/releases)页面下载 **Totem Lite** 独立二进制文件。 ``` # Linux (x64) curl -L https://github.com/mmnto-ai/totem/releases/latest/download/totem-lite-linux-x64 -o totem chmod +x totem && sudo mv totem /usr/local/bin/ # macOS (Apple Silicon) curl -L https://github.com/mmnto-ai/totem/releases/latest/download/totem-lite-darwin-arm64 -o totem chmod +x totem && sudo mv totem /usr/local/bin/ ``` Lite 二进制文件包含完整的 AST 引擎，可以完全离线运行 `totem init`、`totem lint` 和 `totem hooks`。对于 Windows 及其他平台，请参考[安装指南](https://github.com/mmnto-ai/totem/blob/main/docs/wiki/installation.md)。 ## 立即体验 [Totem Playground](https://github.com/mmnto-ai/totem-playground) 是一个包含 5 个故意架构违规的预置 Next.js 应用。在 Codespaces 中它并运行 `totem lint`。Totem 会捕获每一个违规，无需任何配置或 API 密钥。然后尝试运行 `totem rule list --json`，以脚本化 API 的形式查看引擎。 ## 文档与工作流 请参阅 Wiki，了解如何使用 Totem 来治理你的工作流： - [**永不再发生：**](https://github.com/mmnto-ai/totem/blob/main/docs/wiki/it-never-happens-again.md) 如何在 60 秒内将 PR 错误转化为永久的项目法规。 - [**治理 AI 代理：**](https://github.com/mmnto-ai/totem/blob/main/docs/wiki/governing-ai-agents.md) 如何使用钩子和 MCP 工具从第一轮开始对 Claude 和 Gemini 强制执行项目规则。 - [**不再误报：**](https://github.com/mmnto-ai/totem/blob/main/docs/wiki/it-stops-crying-wolf.md) 自愈循环如何根据开发者沮丧程度自动降级嘈杂规则。 ### 深入探讨 - [CLI 参考](https://github.com/mmnto-ai/totem/blob/main/docs/wiki/cli-reference.md) - [架构与工作流](https://github.com/mmnto-ai/totem/blob/main/docs/reference/architecture-diagram.md) - [MCP 服务器设置](https://github.com/mmnto-ai/totem/blob/main/docs/wiki/mcp-setup.md) - [CI/CD 集成](https://github.com/mmnto-ai/totem/blob/main/docs/wiki/ci-integration.md) ## 开放核心承诺 **单仓库本地使用免费。多仓库集中治理需付费。** 强制执行引擎、课程管线、MCP 服务器和自愈循环均采用 Apache 2.0 许可，并将保持免费和开源。详见 [`COVENANT.md`](https://github.com/mmnto-ai/totem/blob/main/COVENANT.md)。 ## 许可证 Apache 2.0 许可证。

标签：AI 代理, AI 安全, AI 编码, AI 记忆层, CLI 工具, LLM 辅助开发, MITM代理, Tripwires 架构, 上下文记忆, 云计算, 代码助手, 代码审查, 代码规范, 共享助手, 威胁情报, 开发效率, 开发者工具, 持久化内存, 持续记忆, 文档即建议, 本地 linter, 架构完整性, 确定性钩子, 约束与护栏, 网络可观测性, 自动化攻击, 规则引擎, 跨仓库记忆, 防止重复造轮子, 零 LLM 干预