dshills/plancritic
GitHub: dshills/plancritic
一款利用大语言模型对软件实施计划进行结构化审查的 CLI 工具，能在执行前自动发现矛盾、歧义和缺失项并输出修补建议。
Stars: 2 | Forks: 0
# PlanCritic
一个用于审查软件实现计划并返回结构化评审结果的 CLI 工具：包括矛盾、歧义、缺失的前置条件、问题以及建议的补丁。输出以 JSON 为主（Markdown 是从 JSON 渲染而来的）。
专为希望在执行计划之前获取机器可读反馈的工程师和编码代理（coding agents）而设计。
## 安装
```
go install github.com/dshills/plancritic/cmd/plancritic@latest
```
或者从源码构建：
```
git clone https://github.com/dshills/plancritic.git
cd plancritic
go build -o plancritic ./cmd/plancritic
```
可选的 Web UI 是一个独立的二进制文件：
```
go build -o plancritic-web ./cmd/plancritic-web
```
## 配置
为你的 LLM 提供商设置 API 密钥：
```
# Anthropic (首选)
export ANTHROPIC_API_KEY=sk-ant-...
# OpenAI
export OPENAI_API_KEY=sk-...
```
如果两者都设置了，默认使用 Anthropic。可以使用 `--model` 进行覆盖。
## 使用方法
```
# 基础 review (JSON output)
plancritic check plan.md
# Markdown 报告
plancritic check plan.md --format md
# 带有 context files 和特定的 profile
plancritic check plan.md --context constraints.md --context tree.txt --profile go-backend
# Strict grounding 模式（不对 codebase 做假设）
plancritic check plan.md --strict
# 将输出写入文件
plancritic check plan.md --out review.json
# 生成 patch suggestions (unified diff)
plancritic check plan.md --patch-out fixes.diff
# CI 模式：如果 verdict 不是 executable 则非零退出
plancritic check plan.md --fail-on not_executable
# 仅筛选 warnings 及以上级别
plancritic check plan.md --severity-threshold warn
# Override model
plancritic check plan.md --model anthropic/claude-opus-4-6
# Verbose output（显示每个 pipeline stage）
plancritic check plan.md --verbose
```
## Web UI
`plancritic-web` 运行一个本地的 HTMX 界面，用于审查上传的计划文件。
```
# 构建 web binary
go build -o plancritic-web ./cmd/plancritic-web
# 启动服务器
./plancritic-web
```
默认监听 `127.0.0.1:8080`。打开 ，选择一个计划文件，可选择添加上下文文件，然后运行审查。Web UI 使用与 CLI 相同的提供商环境变量和审查默认值。
常用覆盖项：
```
# 监听不同的本地端口
./plancritic-web --addr 127.0.0.1:8100
# 设置表单中显示的默认值
./plancritic-web --provider openai --model gpt-5.2 --profile go-backend
```
## 标志
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--format` | `json` | 输出格式：`json` 或 `md` |
| `--out` | stdout | 输出文件路径 |
| `--context ` | — | 额外的基础参考文件（可重复使用） |
| `--profile ` | `general` | 内置清单配置文件 |
| `--strict` | false | 严格基础参考模式（见下文） |
| `--model ` | — | 模型覆盖 |
| `--max-tokens ` | 4096 | 限制 LLM 响应大小 |
| `--temperature ` | 0.2 | LLM 温度 |
| `--seed ` | — | 用于可复现性的种子（如果支持） |
| `--severity-threshold` | `info` | 包含在输出中的最低严重级别 |
| `--patch-out ` | — | 将建议的计划修改以 unified diff 格式写入 |
| `--fail-on ` | — | 如果判定结果达到或超过此级别，则以退出码 2 退出 |
| `--redact` | true | 在发送给模型前对敏感信息进行脱敏 |
| `--offline` | false | 如果未配置提供商则失败 |
| `--verbose` | false | 打印流水线步骤 |
| `--debug` | false | 将脱敏后的 prompt 保存到本地文件 |
## 配置文件
内置配置文件通过特定领域的清单来引导评审：
| 配置文件 | 描述 |
|---------|-------------|
| `general` | 语言无关的基线（默认） |
| `go-backend` | Go 后端：最小依赖、明确的契约、错误处理、测试 |
| `react-frontend` | React/TypeScript：组件、状态管理、可访问性、包大小 |
| `aws-deploy` | AWS 基础设施：IAM 最小权限、网络、回滚、IaC、成本 |
| `davin-go` | 带有主观偏好的 Go 后端内部规则 |
配置文件嵌入在二进制文件中——不需要网络访问。
## 严格模式
使用 `--strict` 时，模型会将所有未出现在计划或上下文文件中的内容视为未知：
- 除非在提供的上下文中出现，否则问题不得声称“代码库使用了 X”。
- 不确定的推断被限制在 WARN 严重级别，并标记为 `"assumption"`。
- 后置检查会扫描描述中暗示捏造代码库知识的短语，并将这些问题降级为 `UNVERIFIED`。
在审查不熟悉代码库的计划时，或者当你想要保守的、仅基于引用的输出时，请使用严格模式。
## 输出格式
JSON 输出遵循严格的 schema：
```
{
"tool": "plancritic",
"version": "1.0",
"input": {
"plan_file": "plan.md",
"plan_hash": "sha256:...",
"context_files": [],
"profile": "general",
"strict": false
},
"summary": {
"verdict": "EXECUTABLE_WITH_CLARIFICATIONS",
"score": 72,
"critical_count": 2,
"warn_count": 5,
"info_count": 7
},
"questions": [ ... ],
"issues": [ ... ],
"patches": [ ... ],
"meta": {
"model": "anthropic/claude-opus-4-6",
"temperature": 0.2
}
}
```
### 判定结果
| 判定结果 | 含义 |
|---------|---------|
| `EXECUTABLE_AS_IS` | 计划足够清晰和完整，可以直接交接 |
| `EXECUTABLE_WITH_CLARIFICATIONS` | 存在细微缺口；回答相关问题后即可解除执行阻碍 |
| `NOT_EXECUTABLE` | 存在关键阻碍；必须首先修改计划 |
### 评分
评分是确定性计算的：从 100 分开始，每个 CRITICAL 扣 20 分，每个 WARN 扣 7 分，每个 INFO 扣 2 分，最低为 0 分。
### 问题类别
`CONTRADICTION`、`AMBIGUITY`、`MISSING_PREREQUISITE`、`MISSING_ACCEPTANCE_CRITERIA`、`RISK_SECURITY`、`RISK_DATA`、`RISK_OPERATIONS`、`TEST_GAP`、`SCOPE_CREEP_RISK`、`UNREALISTIC_STEP`、`ORDERING_DEPENDENCY`、`UNSPECIFIED_INTERFACE`、`NON_DETERMINISM`
每个问题都包含证据引用，并附带行号和计划中的引用摘录。
## 退出码
| 退出码 | 含义 |
|------|---------|
| 0 | 成功，判定结果低于失败阈值 |
| 2 | 判定结果达到或超过 `--fail-on` 阈值 |
| 3 | 输入错误（文件缺失、格式错误） |
| 4 | 模型/提供商错误 |
| 5 | Schema 验证错误（模型返回了无效的 JSON） |
## 示例
请参阅 [`examples/`](examples/) 目录以获取示例计划、JSON 审查输出和 Markdown 报告。
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
标签：AI辅助编程, Anthropic, API安全, CIS基准, Claude, CVE检测, DLL 劫持, EVTX分析, Go语言, HTMX, JSON输出, OpenAI, Web界面, 云安全监控, 代码审查, 代码审查工具, 内存规避, 大语言模型, 威胁情报, 实现计划评估, 开发者工具, 开源框架, 持续集成, 数据管道, 文档结构分析, 日志审计, 机器可读, 程序破解, 统一差异补丁, 编码代理, 软件工程, 软件生命周期管理, 需求分析, 静态分析