内容
<div align="center">
<img src="./assets/pepe-silvia.jpg" alt="查理在佩佩·西尔维亚阴谋板前" width="640" />
# 查理工作
**一款代码健康工具，揭示并重视代码仓库中的维护工作。**
一个MCP服务器 *和* 一个命令行界面 *和* 一个持续集成门控。
那些大家都忽略的不愉快、承载重任的维护工作，直到它带来麻烦：**脆弱的测试**，**即将过期的TLS证书**，**已知漏洞的依赖项**，**已提交的秘密**，**死亡的功能标志**，**待办事项腐烂**，**没有人维护的脚本**。查理工作使用真正的解析器和真正的漏洞数据扫描您的代码仓库，根据您的团队实际花费时间的情况对发现的问题进行排名，并保留一个 **信用账本**，以便看不见的工作终于在每日例会上显示出来。
*以那一集命名，讲述帮派意识到查理一直在默默地维持着帕迪的生意。*
</div>
---
> **这是查理工作。没人会替你做这些事。所以这是你的。**
这些笑话是一个 **开关，而不是负担** —— 通过 `mode="plain"`（或设置 `CHARLIE_VOICE=off`）并使每个响应都无味，可以直接粘贴到工单中。持续集成和SARIF输出始终是纯文本。
## 与任何代理一起使用
查理是一个标准输入输出MCP服务器，因此它可以与 **每个** MCP客户端一起使用 — Claude Code、Codex、Cursor、VS Code、Claude Desktop、Windsurf、Zed、Gemini、Cline。通用配置是一个块：
```json
{
"mcpServers": {
"charlie-work": { "command": "uvx", "args": ["charlie-work-mcp"] }
}
}
```
[](cursor://anysphere.cursor-deeplink/mcp/install?name=charlie-work&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyJjaGFybGllLXdvcmstbWNwIl19)
**不要手写配置文件 — 让查理自己连接：**
```bash
uvx --from charlie-work-mcp charlie-work install --client cursor --write # 或：codex, claude-code, vscode, …
```
`install` 知道每个客户端的方言，并打印（或为项目本地客户端写入）确切的配置。运行 `install --client all` 以查看每一个。
<details><summary><b>每个客户端的配置（复制粘贴）</b></summary>
**Claude Code** — `claude mcp add --transport stdio charlie-work -- uvx charlie-work-mcp`（或上面的块在 `.mcp.json` 中）。
**OpenAI Codex CLI** — `~/.codex/config.toml`：
```toml
[mcp_servers.charlie-work]
command = "uvx"
args = ["charlie-work-mcp"]
```
**Cursor**（`.cursor/mcp.json`），**Claude Desktop**（`claude_desktop_config.json`），**Windsurf**，**Gemini CLI**，**Cline** — 上面的通用 `mcpServers` 块。
**VS Code** — `.vscode/mcp.json` 使用 `servers`（不是 `mcpServers`）：
```json
{ "servers": { "charlie-work": { "type": "stdio", "command": "uvx", "args": ["charlie-work-mcp"] } } }
```
**Zed** — `settings.json` 使用 `context_servers`：
```json
{ "context_servers": { "charlie-work": { "source": "custom", "command": "uvx", "args": ["charlie-work-mcp"] } } }
```
</details>
**教每个代理执行任务** — 在 `AGENTS.md`（Codex、Cursor、Copilot、Gemini、Aider、Windsurf、Zed读取的跨供应商规则文件）中添加一个查理部分：
```bash
uvx --from charlie-work-mcp charlie-work init
```
**作为命令行界面：**
```bash
uvx --from charlie-work-mcp charlie-work scan # 优先处理任务队列
charlie-work next # 单个下一个最佳修复，以补丁形式
charlie-work fix --top 5 | git apply # 修补安全的问题
charlie-work summary # 任务预算 + A–E评分
```
**作为持续集成门控** — 仅当引入 **新的** 高严重性任务时才失败PR（“Clean as You Code”）：
```yaml
- uses: Falcon305/charlie-work-mcp@master
with:
severity: "4"
```
**作为定时监视器** — 一些任务是 **基于时间** 的：证书悄悄接近过期，TODO老化，新CVE出现在已发布的依赖项上。夜间扫描在它影响你之前捕获它：
```yaml
on:
schedule: [{ cron: "0 7 * * *" }]
jobs:
charlie:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: uvx --from charlie-work-mcp charlie-work sarif -o charlie.sarif
- uses: github/codeql-action/upload-sarif@v3
with: { sarif_file: charlie.sarif }
```
> 在PyPI版本发布之前，请将 `uvx charlie-work-mcp` 替换为 `uvx --from git+https://github.com/Falcon305/charlie-work-mcp charlie-work-mcp`（命令行界面亦如此）。
## 可信赖的检测（不是正则表达式戏法）
每个扫描器都由解析器或权威数据源支持，每个发现结果都带有 **置信度等级**（`verified` / `high` / `heuristic`），因此持续集成门控基于事实，而不是猜测。
| 类型 | 如何检测 |
|------|-------------------|
| `vulnerable_dep` | Lockfiles → **OSV.dev**（免费，无需密钥）。发出CVE + 确切的修复版本。 |
| `secret_leak` | gitleaks样式的提供者正则表达式 + 香农熵门控 + 允许列表。 |
| `skipped_test` / `flaky_test` / `focused_test` | **Python AST** 和 **tree-sitter**（JS/TS/Go）— 绝不匹配字符串或注释。 |
| `debug_leftover` | AST调用：`breakpoint()`，`pdb.set_trace`，`debugger`，`console.log`。 |
| `dead_flag` | **读取但从未设置** 的标志（佩佩·西尔维亚案例），通过AST字面提取。 |
| `expiring_cert` | 真实的X.509解析 — `.pem`/`.crt` 在30天内过期，或已经过期。 |
| `outdated_dep` | 注册表查询（PyPI/npm/crates/Go）→ 主要版本落后。 |
| `todo_rot` | 真实的注释中的`TODO`/`FIXME`/`HACK`，按git blame排序。 |
| `dependency_risk` / `unowned_runbook` | 未固定的依赖项；无所有者或CODEOWNERS的操作脚本。 |
一行代码与正则表达式的区别：Python字符串 `"pytest.mark.skip"` 和注释 `# breakpoint()` **不会** 被标记。只有真正的代码才会被标记。
## 您的团队实际出血的地方 — 热点 + 任务预算
查理按 **变动 × 复杂度**（CodeScene风格）排名：某个文件中编辑了40次的债务比一个未被触及多年的相同债务优先级高。`charlie-work summary`将其滚动到 **任务预算** — 总修复分钟数，SQALE风格的债务比率和A–E评分。谷歌SRE表示将任务控制在50%以下。
## 不仅仅是一个报告工具 — 一个执行者
查理返回 **补丁，而不是文本**。`charlie_next`向代理提供单个最高价值的项目 — 它的位置、原因（热点 × 严重性）和一个 **准备应用的统一补丁**，当它可以安全修复时：
```bash
$ charlie-work next
在 pay.py:88 中遗留了 breakpoint() — 严重性 4，在热点（2.1x）中。[自动安全]
--- a/pay.py
+++ b/pay.py
@@ -85,7 +85,6 @@
- breakpoint()
```
每个补丁都是一个diff，您（或CI）可以使用 `git apply` 应用 — **服务器从不编辑您的文件**。修复被标记为 `auto-safe`（机械的：删除一个 `breakpoint()`）或 `needs-review`（更改行为：取消跳过测试，删除陈旧的TODO）。秘密、证书和依赖项升级会被暴露给人类，但绝不会自动修补。
| 工具 | 它做什么 |
|------|--------------|
| `charlie_next` | 单个下一个最佳修复，以补丁 + 原因 +后续操作的形式。 |
| `charlie_fix` | 针对某个发现（或前N个）的统一补丁，标记为自动安全/需要审查。 |
| `charlie_scan_toil` | 优先处理、分页的任务队列（结构化输出）。 |
| `charlie_summary` | 任务预算：分数、债务比率、A–E评分。 |
| `charlie_triage` | 代理处理的前N个行动计划。 |
| `charlie_explain` | 某个发现为何是债务 — 证据、热点、所有者、修复。 |
| `charlie_trend` | 记录快照并报告随时间变化的差异。 |
| `charlie_did_it` / `charlie_ledger` | 信用账本 — 谁清理了什么，油脂陷阱的冠军。 |
另外还有 `toil://queue` 和 `toil://item/{id}` **资源** 以及四个 **提示**（任何客户端中的斜杠命令）：`triage_toil`、`fix_next`、`pre_pr_check`、`charlie_rules`。仪表板无法完成的事情：“修复下一个问题，运行测试，并在账本中记录我的贡献。”
## 不是玩具：令牌规则 + 评估
- **繁重的工作在服务器端进行**。代理自己发现这个任务需要读取整个代码仓库；查理只返回一个紧凑的排名队列。原始文件从未进入模型的上下文。
- **可复制的评估框架**（`evals/run.py`）植入已知的任务并断言 **最终状态** — 召回率和排名 — 加上令牌成本测量。还有一个可选的模型评估工具选择评估（`evals/agentic.py`）。
```
$ uv run evals/run.py
kinds recalled : 9/9 (100% recall) top item is the cert : True
naive: read whole repo : 1881 tokens
charlie work queue : 1353 tokens → 28% fewer tokens
RESULT: PASS
```
这个28%是在一个小fixture上；差距迅速扩大 — 原始成本随着代码仓库的增长而增长，而队列保持在单个页面上。
## 配置和抑制
零配置即可开始。通过 `pyproject.toml`（或 `charlie.toml`）中的 `[tool.charlie]` 进行调整：
```toml
[tool.charlie]
exclude = ["vendor/**"]
disable = ["charlie/todo-rot"]
min_confidence = "high"
[tool.charlie.per-file-ignores]
"tests/**" = ["secret_leak"]
```
另外还有内联 `# charlie: ignore[rule]`、`.charlieignore` 和已提交的基准线（`charlie-work baseline`），以便全新安装从“0 new”开始。
## 开发
```bash
uv sync --extra dev
uv run ruff check . && uv run mypy && uv run pytest -q
uv run python evals/run.py
```
CI在Python 3.11–3.13上运行ruff + mypy（typed）+ pytest +评估。版本发布到PyPI via OIDC Trusted Publishing。
## 团队（路线图）
每个都作为其自己的独立MCP服务器发布：**The Implication**（身份验证和黑暗模式审计器），**Pepe Silvia**（死代码跟踪器），**The D.E.N.N.I.S. System**（滚动通信规划器）。
## 许可证
代码：MIT。英雄图像是 *It's Always Sunny in Philadelphia* （© FX Networks）的截图，用于识别和评论；它不受MIT许可证的约束。一个原始矢量渲染图像存放在 [`assets/hero.svg`](./assets/hero.svg) 中。
