内容
# 代码异味
本地命令行工具，将编码目标转换为 AI 代理的排名、按令牌预算的存储库上下文。
```
代理 → shell → 代码异味 JSON → 代理推理
```
无守护进程。无 MCP Server。无网络。读取本地代码仓库，写入 `.codesmell/` 缓存，然后退出。
## 用法
```sh
codesmell pack --root . --goal "修复刷新令牌错误" --budget 12000 --format json
```
所有命令都支持 `--format json`（代理合约）或纯终端输出（省略该标志）。
| 命令 | 目的 |
|---------|---------|
| `init` | 初始化 `.codesmell/` 配置和缓存 |
| `doctor` | 检查本地准备情况 |
| `map` | 仓库结构、语言、公共符号 |
| `search` | 查询的排名证据 |
| `pack` | 编码目标的预算上下文包 |
| `explain` | 深入研究文件或符号 |
| `diff` | 更改的文件、符号、风险提示 |
| `test-plan` | 集中的测试建议 |
| `review` | 确定性发现及证据 |
## 代理合约
`--format json` 在标准输出上输出一个 JSON 对象（`schema_version: "codesmell.agent.v1"`）。诊断信息输出到标准错误流。
关键字段：`status`, `confidence`, `budget`, `coverage`, `guidance`, `evidence`, `findings`, `risks`, `test_hints`, `redactions`, `recommended_next`.
状态值：
- `ok` — 有可行的证据，请继续。
- `partial` — 有证据但有保留；建议在进行大范围修改前运行后续命令。
- `needs_refinement` — 目标范围太广；请根据 `recommended_next` 缩小范围。
- `error` — 无证据；请检查 `warnings`。
输出前会删除敏感信息。只有计数和种类会被报告，绝不会是原始值。
## 架构
```
crates/
codesmell-cli 命令行参数处理，JSON/人类友好输出
codesmell-core 领域类型，配置，错误
codesmell-facts 语言无关的事实模型，AST 缓存模式
codesmell-engine 共享工作区分析调度
codesmell-scan gitignore 感知的遍历，分类，指纹识别
codesmell-parse tree-sitter 解析，符号/导入提取
codesmell-index 词汇排名，BM25 风格的评分
codesmell-pack 上下文预算，信息隐藏，证据选择
codesmell-review 差异分析，发现，测试计划
```
目前，Rust 是唯一一种经过 tree-sitter 解析的语言。其他语言通过词汇方式扫描和排名。
## 开发
```sh
cargo build --workspace
cargo test
cargo fmt --check
cargo clippy --all-targets -- -D warnings
```
本地运行：
```sh
cargo run -p codesmell-cli -- pack --root . --goal "修复错误" --budget 12000 --format json
```
测试固件：`tests/fixtures/rust-basic`。集成测试在临时仓库中合成忽略的文件、敏感信息、暂存更改、重命名和混合语言场景。
大型仓库烟雾测试（可选，默认忽略）：
```sh
scripts/clone-bun-test-repo.sh
cargo test -p codesmell-cli core_commands_smoke_run_on_ignored_bun_test_repo -- --ignored
```
## 文档
设计和路线图详情参见 [`docs/`](docs/)：
- [`IDEA.md`](docs/IDEA.md) — 产品愿景和定位
- [`AST_ENGINE_DESIGN.md`](docs/AST_ENGINE_DESIGN.md) — 引擎内部和 tree-sitter 策略
- [`ROADMAP.md`](docs/ROADMAP.md) — 里程碑跟踪
- [`TGREP_DESIGN.md`](docs/TGREP_DESIGN.md) — tgrep 关系搜索设计
- [`TGREP_ROADMAP.md`](docs/TGREP_ROADMAP.md) — tgrep 里程碑
MCP 市场