otito

Òtítọ́ **适用于代理和审查者的本地优先代码上下文 - 这个更改究竟影响什么？** [](https://github.com/BASHBOP/otito/actions/workflows/otito-ci.yml) [](LICENSE) [](https://nodejs.org/)   ```text ___ _____ ___ _____ ___ / _ \_ _|_ _|_ _/ _ \ | | | || | | | || | | | | |_| || | | | | || |_| | \___/ |_| |___| |_| \___/ ``` 代理的输出受到两件事的限制：**模型** 和围绕它的 **运行环境** —— 提示、给定的上下文、工作代码库以及代码合并前必须经过的关卡。你无法控制模型。你控制运行环境，更紧密的运行环境让更便宜的模型通过更少的浪费令牌完成相同的工作。 **Òtítọ́** 就是这一层运行环境。它是本地优先、确定性的、与模型无关的：它发现仓库、建立本地索引、在代理编辑前生成任务感知上下文、评估更改实际影响的程度以及控制合并准备度 —— 每次都以相同的方式，没有服务器、账户和代码离开机器。因为它依赖于软件基础而不是任何一个模型，所以你今天构建的运行环境在模型在下面发生变化时仍然有效。 它不试图取代 `opensrc`、`code-structure`、Daytona 或 Harnss。它为开发者和编码代理提供了一个单一的 CLI，可以： 确定性合并差异化的核心。这是模型无法自我评估的人检查点： - 为本地更改和拉取请求评估合并准备度，使用一个_gate` 工具（CLI 上的 `gate`） - 解析 CODEOWNERS 以获取所需审查者和表面所有者决策警告 - 在合并前检查分支保护期望和所需检查 - 从 git 差异和可选的 GitHub 评论中生成可行的 PR 审查上下文 本地优先上下文 —— 为关卡提供支持： - 检查仓库 - 发现和索引本地仓库 - 维护本地目录并跨目录搜索 - 在代理计划或编辑前生成任务感知上下文数据包 - 为代理生成 AST 支持的 JSON优先代码映射 - 为仓库生成设置/验证/运行时运行环境 - 生成 Markdown 或 JSON 报告 - 估计生成工件令牌大小 - 为具有持久仓库索引缓存的代理主机运行 MCP 服务器 - 暴露简单的代理友好型工具元数据 - 检查工具可用性 - 通过 `code-structure` 生成 TypeScript 结构 HTML - 通过 `opensrc` 搜索依赖源 ## 文档 otito 现已包含一个可发布的 MkDocs 文档站点，塑造成一个实用的发现和交付包： - [首页](docs/index.md) - [高管摘要](docs/EXECUTIVE-SUMMARY.md) - [上下文基础/01-context-foundation/README.md) - [MCP 和代理工作流](docs/02-mcp-agent-workflows/README.md) - [贡献者治理](docs/03-contributor-governance/README.md) - [发布准备度](docs/04-release-readiness/README.md) - [信任](docs/05-trust-layer-demo/README.md) - [构建者-创始人运营循环](docs/06-operating-loop/README.md) - [运行环境论文和代理体验](docs/07-harness-thesis/README.md) - [教程集成（Codespaces）](docs/08-tutorials-integration/README.md) - [收敛论文和评分](docs/09-convergence-thesis/README.md) - [用法和性能仪表盘](docs/10-usage-dashboard/README.md) - [词汇表](docs/GLOSSARY.md) 当为仓库启用 GitHub Pages 时，已发布的站点配置为： ```text https://bashbop.github.io/otito/ ``` ## 快速入门 代码映射使用 TypeScript 编译器用于 JS/TS 和专用语言提取器用于 Go、Python、Java、Ruby 和 Rust（参见 `src/lib/code-map/ast-languages.js`）。可选的外部工具仅用于依赖源查找和 HTML 结构报告。 npm 包尚未发布。使用本地复刻： ```bash git clone https://github.com/BASHBOP/otito.git cd otito npm ci 安装依赖项 npm run ci # 运行完整的质量关卡 npm install -g . # 在全局安装 otito CLI otito doctor # 验证安装 ``` ```bash node src/cli.js help node src/cli.js doctor node src/cli.js init /path/to/target-repo node src/cli.js repo . --json node src/cli.js discover ~/projects --depth 2 --json node src/cli ~/projects --discover node src/cli.js catalog node src/cli.js search "events controller" node src/cli.js context "add a new MCP tool" --path . node src/cli.js map . --json node src/cli.js harness . --out .otito/harness.md node src/cli.js pr . --base origin/main --out .otito/pr-review.md node src/cli.js mcp node src/cli.js matrix node src/cli.js report . --out .otito/report.md node src/cli.js workspace /path/to/web /path/to/api --out .otito/workspace.md ``` 可选的外部工具： ```bash npm install -g opensrc code-structure ``` 然后： ```bash node src/cli.js deps zod --query parse node src/cli.js structure . --out .otito/structure.html ``` ## 用例 | 目标 | 命令 | 输出 | | --- | --- | --- | | 检查一个仓库 | ` repo . --json`仓库事实、脚本、语言、入口点和 git 状态 | | 构建代码映射 | `otito map . --json` | 源文件、域、导入、导出、符号和路由 | | 准备任务上下文 | `otito context "add a new MCP tool" --path .` | 主要文件、相关文件、测试、模式和验证命令 | | 生成代理运行环境 | `otito harness . --out .otito/harness.md` | 设置、验证、运行时和上下文命令 | | 审查本地更改 | `otito pr . --base origin/main --out .otito/pr-review.md` | 更改文件、风险提示、审查目标和测试提示 | | 索引本地项目 | `otito index ~/projects --discover` | `.otito/index.json` 文件和本地目录 | | 搜索索引仓库 | `otito search "events controller"` | 跨路径、域、路由、导入、导出和符号的排名匹配 | | 运行 MCP 服务器 | `otito mcp` | 暴露 otito 输入/输出服务器 | | 跟踪用法和性能 | `otito | 自包含 源自一个选择加入的本地用法日志（默认关闭） | 有关 Claude Desktop、VS Code、Cursor 和通用标准输入/输出客户端代码段，请参阅 [MCP 和代理工作流](docs/02-mcp-agent-workflows/README.md otito 与替代品比较 | 方法 | 优势 | otito 的不同之处 | | --- | --- | --- | | Sourcegraph / Cody 上下文 | 强大的托管代码搜索和基于嵌入的上下文跨组织 | otito 是本地优先和确定性的：无服务器，无账户，无代码离开机器，相同查询始终产生相同的数据包 | | 手写的 `CLAUDE.md` / 规则文件 | 精心策划的、富含意图的指导 | 手写的上下文很快就会过时；otito 从实际代码（符号、导入、路由、测试）中重新生成上下文，并在每次运行时补充简短的 `CLAUDE.md` | | `grep` / `ripgrep` | 快速、通匹配 | otito 按任务意图对整个文件进行排名，跨路径、符号、导出和测试，然后添加模式和验证命令 —— 一个上下文数据包，而不是匹配行的列表 | ## 质量关卡 在打开拉取请求或发布版本之前使用完整的关卡： ```bash npm run ci ``` 关卡运行： - `npm run format:check` - `npm run lint` - `npm run typecheck` - `npm run version:check` - `npm test` - `npm run test:coverage` - `npm run audit` - `npm run smoke` 覆盖率目前控制源文件在 70% 行、60% 分支和 75% 函数。`.otito/` 下的生成工件被 git、linting 和格式化忽略；请在那里保留持久报告而不是提交它们。 otito 遵循语义版本控制。拉取请求应标识是否为无版本影响、补丁、次要或主要更改；维护者在发布期间应用最终软件包版本。 对于更长时间的信任层工作，请使用 [构建者-创始人运营循环](docs/06-builder-founder-operating-loop/README.md) 将每个会话与上下文、聚焦更改、可见关卡、人工决策和持久证据联系起来。 ## 贡献 欢迎贡献。从 [CONTRIBUTING.md](CONTRIBUTING.md) 开始，为重大更改打开问题或草稿 PR，并在请求审查之前运行 `npm run ci`。 所有代码更改必须在合并前由维护者/代码所有者审查。受保护的 `main` 分支需要维护者批准、通过质量关卡和解决的 PR 会话。 ## 常见工作流 代理仓库运行环境： ```bash node src/cli.js harness . --out .otito/harness.md node src/cli.js map . --json ``` 本地发现、索引、目录和搜索： ```bash node src/cli.jsprojects --depth 2 node src/cli.js index ~/projects --discover node src/cli.js catalog node src/cli.js search "submit rsvp" ``` 任务感知代理上下文： ```bash node src/cli.js context "add a new MCP tool" --path . --json node src/cli.js context "add a new MCP tool" --path . --out .otito/context-pack.md ``` PR 审查运行环境： ```bash node src/cli.js pr . --base origin/main --out .otito/pr-review.md node src/cli.js pr . --number 123 --comment ``` 合并关卡（`gate` 是规范的 v2 命令；`pass` / `pass-pr` 仍作为旧别名保留）： ```bash node src/cli.js gate . --base origin/main # 本地关卡（无 GitHub） node src/cli.js gate . --staged --base origin/main # 分阶段路径证据，适用于 pre-commit 钩子 node src/cli.js gate . --base origin/main "update the greeting" --min-convergence 80 node src/cli.js converge "update the greeting" --path . --base HEAD --staged --json # 确切更改主题收据 node src/cli.js gate --pr 123 --path . # 通过 gh 的 GitHub PR 关卡 ``` 在分阶段模式下，变更路径、风险、机密和收敛证据使用确切的 Git 索引树。确切主题源分析流式传输原始 Git 块，并在超过 5,000 个源文件或 64 MiB 时关闭。发布命令和可选分析器检查仍会检查工作树，并在聚合收据之外报告。 多仓库产品上下文： ```bash node src/cli.js workspace ../web ../api --out .otito/workspace.md ``` GitHub Actions 引导： ```bash node src/cli.js init /path/to/target-repo本地 Ollama 审查： ```bash src/cli.js harness . --out .otito.md { echo "Use this repo harness to explain the project and suggest the next best engineering task." echo cat .otito/harness.md } | ollama run qwen3:8b --think false --hidethinking --nowordwrap ``` 本地 Ollama PR 审查： ```bash node src/cli.js pr . --base origin/main --out .otito/pr-review.md { echo "Review this PR context. Focus on bugs, missing tests, and risky changes." echo cat .otito/pr-review.md } | ollama run3:8b --think false --hidethinking --nowordwrap ``` ## 命令 ### `检查本地运行时和可选的外部工具。 ```bash node src/cli.js doctor --json ``` ### `install` / `i` 打印安装命令和当前二进制状态。从本地复刻中，`--global` 运行 `npm install -g .`；`--link` 运行 `npm link`。 ```bash node src/cli.js install node src/cli.js i node src/cli.js install --global node src/cli.js install --json ``` 安装后，使用 `otito` 作为命令。 ### `repo <path>` 检查仓库形状：包元数据、语言、包管理器、脚本、可能的入口点、git 元数据和被忽略的重目录。 ```bash node src/cli.js repo . --json ``` git 仓库通过 `git ls-files --cached --others --exclude-standard` 进行扫描，因此被忽略的文件不会污染运行环境上下文。普通目录会回落到内置的遍历器。 ### `discover <root...>` 在本地目录下发现仓库根目录而无需索引它们。 ```bash node src/cli.js discover ~/projects --depth 2 node src/cli.js discover . --json ``` 在具有常见仓库标记的目录中停止发现，例如 `package.json`、`.git`、`pyproject.toml`、`go.mod`、`Cargo.toml` 和 `Package.swift`。 ### `index <repo...>` 生成本地 `.otito/index.json` 文件并将仓库添加到本地目录。 ```bash node src/cli.js index . node src/cli.js index ~/projects --discover node src/cli.js index . --catalog /tmp/otito-catalog.json --json ``` 默认目录路径是 `~/.otito/catalog.json`。设置 `OTITO_CATALOG` 或传递 `--catalog` 以使用不同的文件。 ### `catalog` 列出当前索引到本地目录的仓库。 ```bash node src/cli.js catalog node src/cli.js catalog --json ``` ### `search <query>` 通过路径、域、类型、路由、控制器路径、导入、导出和符号搜索索引的本地仓库。 ```bash node src/cli.js search "events controller" node src/cli.js search "submit rsvp" --limit 10 node src/cli.js search "api client" --offline --json ``` 默认情况下，搜索会在指纹更改时刷新仓库索引。使用 `--offline` 读取存储的 `.otito/index.json` 文件。 ### `context <query>` 为任务生成本地上下文引擎数据包。数据包包括推断的意图、主要文件、相关文件、匹配测试、实现模式、验证命令、冲突、源证据和令牌估计。 ```bash node src/cli.js context "add a new MCP tool" --path . --json node src/cli.js context "add a new CLI command" --path . --out .otito/context-pack.md ``` 在将工作交给编码代理之前使用此命令。它是确定性和本地优先的：它依赖于仓库索引、代码映射、导入关系、测试和运行环境命令，而不是外部模型。 ### `harness <path>` 使用设置命令、验证脚本、运行时脚本、上下文命令、关注区域和估计的上下文令牌使用量生成仓库运行环境。 ```bash node src/cli.js harness . --out .otito/harness.md node src/cli.js harness . --json ``` 作为代理或 CI 工作流读取的第一个工件使用此命令。 ### `init <path>` 在另一个仓库中搭建 otito。 ```bash node src/cli.js init /path/to/target-repo node src/cli.js init /path/to/target-repo --force node src/cli.js init /path/to/target-repo --no-workflow node src/cli.js init /path/to/target-repo --tool-repo BASHBOP/otito --tool-ref main ``` 生成的文件： - `.otito/README.md` - `.github/workflows/otito-ci.yml` 生成的 workflow 在拉取请求和提交推送上运行。拉取请求运行会生成报告、上载工件并创建或更新粘性 PR 评论。推送运行会生成并上载报告工件而不会评论。 ### `structure>` 对 TypeScript 文件运行 `code-structure`。 ```bash node src/cli.js structure . --pattern "app/**/*.tsx" --out .otito/structure.html ``` 如果缺少 `code-structure`，命令会返回安装提示而不是神秘地失败。如果未全局安装但 `npx` 可用，otito 可以通过 `npx --yes code-structure` 运行它。 ### `deps <package>` 使用 `opensrc path <package>` 解析依赖源并可选地搜索它。 ```bash node src/cli.js depsquery parse --limit 20 ``` ### `report <path>` 生成可共享的开发者报告。 ```bash node src/cli.js report . node src/cli.js report . --out .otito node src/cli.js report . --json ``` 默认输出格式化为终端读取并以估计的令牌使用量结束。使用 `--out` 获取 Markdown 工件或 `--json` 获取结构化数据。 ### `workspace <repo...>` 跨相关仓库生成一个产品级报告。 ```bash node src/cli.js workspace /path/to/web /path/to/api --out .otito/workspace.md node src/cli.jspath/to/web /path/to/api --json ``` ### `pr <path>` 从本地 git 差异元数据、代码映射分类、审查目标、定向审查提示、风险标志、可选的 GitHub PR 评论中生成 PR 审查上下文包。 ```bash node src/cli.js pr . --base origin/main --out .otito/pr-review.md node src/cli.js pr . --number 123 --comment ``` 有用标志： - `--base <ref>`：比较特定的基准引用。默认为 PR 基准、上游、`origin/main` 或 `main`。 - `--head <ref>`：比较特定的头部引用。默认为 `HEAD`。 - `--number <n>`：使用 `gh pr view` 元数据和审查评论丰富。 - `--github`：要求 `gh` 推断当前分支的 PR。 - `--comment`：使用 `gh` 创建或更新粘性 GitHub PR 评论。 ### GitHub Actions 此仓库包含 `.github/workflows/otito-ci.yml`。工作流安装依赖项，运行 `npm run ci`，然后生成 PR 或推送审查上下文作为上传的工件。使用 `node src/cli.js init /path/to/target-repo` 在另一个仓库中搭建 otito 审查工作流。 ### `mcp` 启动一个stdio MCP服务器，暴露otito作为代理可调用的工具。MCP存储库映射查找缓存 `.otito/index.json`，并在文件更改时自动刷新。 ```bash node src/cli.js mcp ``` 将其连接到MCP主机（Claude Desktop、Claude Code、Codex CLI、Cursor等）： ```json { "mcpServers": { "otito": { "command": "npx", "args": ["-y", "@bashbop/otito", "mcp"] } } } ``` 如果您更喜欢全局安装的二进制文件： ```json { "mcpServers": { "otito": { "command": "otito", "args": ["mcp"] } } } ``` Ollama可以提供本地模型，但它本身并不调用MCP工具。要通过MCP使用otito和本地模型，请使用支持Ollama作为模型提供者的MCP代理客户端，并配置上面的`otito`服务器。 Òtítọ́ 暴露 **13** 个MCP工具，用于仓库检查、上下文、影响、审查和合并证据。 | 工具 | 目的 | | ------------------- | ---------------------------------------------------------------------------------- | | `repo_inspect` | 检查仓库结构、脚本、包管理器、入口点和git状态 | | `repo_map` | 紧凑的JSON代码映射，可按 `domain`、`kind` 和 `route` 过滤 | | `repo_index` | 生成 `.otito` 索引 + 目录条目；`dryRun:true` 发现只读 | | `repo_search` | 搜索目录；省略 `query` 以返回目录列表 | | `context_pack` | 构建任务感知上下文数据包 | | `change_impact` | 评估可能拥有纯英文变更请求的文档变更影响 | | `agent_experience` | 评估代理体验（AX 0–100）：可变性、包含性、防护措施、清晰度 | | `convergence_score` | 评估意图与执行情况（0–100），附带确切的变更主题收据 | | `review_context` | 差异/评论审查上下文（无裁决） | | `review_gate` | 通过/警告/失败合并门控 — 本地无 `pr`，GitHub PR 门控带 `pr` | | `review_verdict` | 综合裁决：影响 + 审查上下文 + 审查门控 | | `workspace_report` | 跨多个仓库的产品级报告 | | `repo_harness` | 代理或CI环境的设置、验证、运行时和上下文命令 | ### `matrix` 打印Greploop、 `code-structure` 、 `opensrc` 、Daytona和Harnss的工具评估矩阵。 ### `agent-tools` 打印代理集成的JSON元数据。这样设计故意轻量，以便以后可以在不更改命令语义的情况下成为MCP服务器。 ## 策略 先封装。再衡量痛点。根据需求构建。 这使得项目能够快速发挥作用，同时留有空间，以便稍后用自主实现替换薄弱的适配器。 --- ## 工具链的一部分 **otito** 是形成AI辅助开发的确定性信任层的四种工具之一。每种工具都回答了人们向LLM提出的问题——使用静态分析代替。 - **otito**（此工具）— 上下文：这个变更实际上影响了什么？ - [tieline](https://www.npmjs.com/package/@bashbop/tieline) — 契约：前端和后端是否悄悄地不再一致？ - [bouncer](https://www.npmjs.com/package/@bashbop/bouncer) — 合规性：你能向Ofcom证明这一点吗？ - [aiglare](https://www.npmjs.com/package/@bashbop/aiglare) — 治理：模型可以在哪里执行您无法撤销的操作？ 更多信息请访问 [segunolumbe.com](https://segunolumbe.com)。 _静态分析，而非模型。