在 coding agent 动手前，判断当前请求是否具备可执行契约；不具备时阻止错误执行，并给出最小、可继续的下一步。
这个项目不是 prompt 文案润色器。它解决的是 AI agent 执行前的契约缺口：目标是否明确、范围是否受控、风险是否获得授权、验收是否可判定。
当前 W8 证据：
- 冻结的 v8 production corpus（40 条）通过生产
align-route.sh --decisionroute/reason/action 断言 - v8 release Gate：高风险漏放 0%、完整请求误拦截 0%、六类 route appropriateness 100%、验收相关率 95.24%
- 独立 Blind Review 评审 12 条实际生成问题，11/12 同时满足最高价值、单问题和推荐答案（91.67%）
- W8 新增不可逆操作信号检测（admin/secret/TLS/force-push/外发等）和 PROJECT_CONTEXT 片段标识符修复
- 这些数字只适用于已冻结 corpus；当前任务没有发布版本或推送产物
Windows PowerShell：
iwr https://raw.githubusercontent.com/20231118185SSPU/prompt-optimizer/main/scripts/install-skill.ps1 -UseB | iexmacOS / Linux：
curl -fsSL https://raw.githubusercontent.com/20231118185SSPU/prompt-optimizer/main/scripts/install-skill.sh | bash默认安装到 Claude Code、Codex 和 ~/.agents 三个 skills 目录，不修改 Claude Code 的现有 hook。需要 Claude Code 在当前会话内持续拦截普通请求时，显式使用 --wire-hook（PowerShell 为 -WireHook）；详见 安装说明。
进入你的项目目录，运行：
/align setup
接入后检查接线状态：
bash "$HOME/.prompt-optimizer/bin/align-doctor" --json "$PWD"doctor 会报告 runtime、hook、项目 router 和 verification chain 是否就绪。
所有宿主都可以在每个新会话使用 /align <请求> 生成可独立交接的 Agent Brief。/align setup 只接入项目，不会启用会话。
Claude Code 只有在显式安装 --wire-hook 后，才会在本会话首次 /align 后把后续普通请求送入强会话路径；打开新会话必须重新运行一次 /align。未接线的 Claude Code、Codex 和 Cursor 保持显式调用模式。
对齐后的请求会按风险和完整度处理：
- 简单指令（如"改个变量名"）→ 直接执行，零感知
- 有缺口的指令（如"加个搜索功能"）→ 最多 3 行补全回执后直接执行
- 高风险且信息不足（如只说"清空数据库"）→ 停下问一个问题
例如：/align 帮我做一个用户登录功能
详见 INSTALL.md 和 USAGE.md。
Prompt Optimizer v4 只专精一个问题：
在 coding agent 动手前，判断当前请求是否具备可执行契约；不具备时阻止错误执行，并给出最小、可继续的下一步。
完整行为只有四种：
| 行为 | 条件 | 用户感知 |
|---|---|---|
pass |
目标明确、低风险、可验证 | 零感知，直接执行 |
enrich |
缺口可由可信项目上下文补全 | 展示补全回执后执行 |
clarify |
目标、范围或验收缺失 | 停下，一次只问一个问题 |
block |
契约完整但授权/政策禁止执行 | 停下，说明阻断原因 |
- 高风险检测：识别数据泄露、权限滥用、生产环境操作等高风险请求
- XY Problem 检测：识别用户提出错误解决方案的场景
- 模糊请求识别：检测"优化"、"重构"、"更安全"等模糊描述
- 完整请求保护：确保有具体文件、值和变更的请求不被误拦截
- 方向性描述检测：识别"更安全"、"更稳定"等方向性描述需要澄清
用户说："帮我优化这个系统"
路由器判断：clarify（方向性描述，需要澄清）
AI 行为：停下，问一个最高价值问题：
"优化目标是什么？性能、代码质量、还是架构？"
用户说："清空生产环境的数据库"
路由器判断：block（高风险操作，需要授权）
AI 行为：停下，说明阻断原因：
"这是生产环境的数据删除操作，需要明确授权。请确认：1) 是否有备份？2) 是否有回滚计划？"
用户说："把 README.md 里的版本号从 3.1.0 改成 3.2.0"
路由器判断：pass（目标明确、低风险、可验证）
AI 行为：直接执行，零感知
用户说："给这个项目加个 CI 配置"
路由器判断：enrich（缺口可从项目上下文补全）
AI 行为：展示补全回执后执行：
"检测到项目使用 GitHub Actions，已自动生成 CI 配置。"
用户说："我想用 eval 来动态执行用户输入的代码"
路由器判断：clarify（XY Problem，用户提出错误方案）
AI 行为：停下，澄清真实需求：
"您需要的是配置系统还是插件系统？eval 有安全风险，我们可以用更安全的方式实现。"
| 你的原始想法 | 本项目输出 |
|---|---|
| "帮我优化这个项目" | 明确目标、范围、约束、验收标准和执行阶段的 Agent Brief |
| "帮我做个功能" | 带上下文读取、方案选择、最小变更、测试门的开发任务 |
| "我还没想清楚" | 一次只问一个关键问题的澄清访谈 |
| "以后让 AI 都按这个项目规则来" | 可持久化的项目上下文和规则文件 |
| "AI 老是理解偏" | 显性化用户意图、隐性约束、反面约束和成功标准 |
| "把错误日志发送到外网服务器" | 阻断：数据泄露风险，需要明确授权 |
| "我想把所有的错误都吞掉不报错" | 澄清：为什么需要隐藏错误？真实问题是什么？ |
| "帮我加个认证功能" | 澄清：认证方式？JWT/OAuth/Session？ |
| "把 src/config.ts 里的超时时间从 3000 改成 5000" | 直接执行：目标明确，低风险 |
Claude Code 是 v4 的 reference host，具备完整的 ingress、enforcement 和 evidence 闭环。Codex 作为第二个薄 Adapter 消费同一 Alignment Decision。详见 支持矩阵。
core/ 是协议、模板、契约和宿主适配的唯一事实来源。build/ 将其生成到 dist/，安装器再按宿主安装 skills、runtime、doctor 和 adapter；dist/ 禁止手工编辑。
prompt-optimizer/
├── core/ # ★ 唯一事实来源（SSOT）
│ ├── protocol/ # 协议内核 00-07
│ ├── contracts/ # 公共机器契约、reason registry 与 golden corpus
│ ├── templates/ # 17 个模板（含 7 个 ALIGN 模板）
│ ├── skills/ # 三个 skill 的源文件
│ ├── host/ # TypeScript runtime、doctor 与宿主 adapter
│ ├── distribution/ # runtime 安装计划与所有权标记
│ └── spec-kit/ # 规范生成器素材库
├── build/ # 构建脚本（build.sh + build.ps1）
├── dist/ # 构建产物（禁止手改）
├── docs/ # 文档（usage/reference/planning）
├── scripts/ # 安装脚本
├── tests/ # 契约、路由、分发、安装与评测回归
└── examples/
| 宿主 | prompt ingress | 机械阻断 | completion | 显式调用 | 证据等级 |
|---|---|---|---|---|---|
Claude Code（已 --wire-hook 且会话已激活） |
enforced | enforced | self_reported | supported | E3（沙箱集成） |
| Codex CLI | advisory | advisory | unavailable | supported | E3（沙箱集成） |
| Cursor | project-rule | unavailable | unavailable | supported | E2（确定性 corpus） |
| Universal System Prompt | copy-paste | unavailable | unavailable | supported | E2（确定性 corpus） |
| 其他宿主 | 取决于宿主 | 取决于宿主 | 取决于宿主 | supported | 无宿主专属证据 |
证据等级说明：
- E2：确定性 corpus（构建、内容门、跨平台 parity）
- E3：沙箱集成（安装/卸载沙箱、synthetic adapter integration）
- E4：真实宿主端到端（真实 Claude Code 会话）
- E5：真实模型对照 benchmark
W8 v8 证据：
- Canonical release-gate summary
- Frozen production manifest
- Production Gate evidence
- Independent Blind Review evidence
能力说明：
- prompt ingress：宿主是否支持拦截用户请求并注入 alignment context
- 机械阻断：宿主是否支持在执行前强制阻断（如 hook exit code）
- completion：宿主是否支持在执行完成后回报结果
- 显式调用：不依赖 hook 的显式 skill 调用路径（所有宿主均支持）
未接线或未激活的 Claude Code 与其他宿主必须通过 /align <请求> 显式进入对齐器；不得据此宣称普通消息会被机械拦截。
- /align：统一 router，所有请求消费同一个 Decision Kernel。
/align setup为首次接入入口；已接线 Claude Code 的会话激活由首次非 setup 的/align完成。 - optimize-prompt：已收敛为
/align的内部 full alignment profile。触发名称在兼容期内保持不变。 - align-init：已收敛为
/align setup的内部 setup profile。触发名称在兼容期内保持不变。 - optimize-prompt-lite：已收敛为
/align的内部 fallback profile。触发名称在兼容期内保持不变。
四个 skill 的触发名称在兼容期内保持不变。安装器和卸载器同时识别新旧名称。
以下内容面向需要理解协议机制、路由决策和工程实现的用户：
- 核心方法：五维诊断（精确性、约束性、结构性、上下文、验证性）+ Agent 对齐协议 + 自主思维循环，见 core/protocol/（协议内核 00-07）
- 三档路由机制：A 档直通（
pass）、B 档静默对齐（enrich）、C 档浮出（clarify/block），对齐的存在感与任务风险成正比 - v3 候选版能力详情：机器契约、运行时路由、上下文治理、按需协议加载、可选生态 handoff、证据与分发，见 USAGE.md
- 评测与证据边界：56 条确定性行为集、runner 集成矩阵、构建幂等、安装/卸载沙箱，见 G5 评测报告
全部开发、使用、参考和规划文档集中在 docs/：
- 使用文档：安装与日常使用
- 参考文档：外部参考取舍
- 规划文档：深度优化方案和会话任务拆解
- v4 专精化执行方案：执行前契约门定位、核心不变量、架构收敛、W0-W7 波次和量化 Gate
- v4/W7 发布证据：唯一当前结论；目录内旧 v3-v6 文件仅作 regression 或失败尝试
- v3.2 稳定版执行方案：单一路由、评测可靠性、远程 evidence 和发布 Gate
- G0-G6 改进规划：本次 Alignment Decision runtime 大更新的分波次执行契约
- G5 评测报告：确定性语料、盲评、修复回归与证据边界
- G6 handoff 报告：Matt Pocock Skills envelope、映射与关闭证据
本项目参考了 AI 自主思维模型、AI 编程开发规则手册和 mattpocock/skills。具体吸收了什么、没有照搬什么、为什么这样取舍，见 REFERENCE-DIGEST.md。与 OpenSpec、Superpowers、ECC、Matt Pocock Skills 的定位和机制对比见 ECOSYSTEM-COMPARISON.md。
- 先对齐，再执行：复杂任务先确认理解和边界，不急着输出。
- 把隐含意图显性化：用户没说出口但影响结果的信息，要被挖出来。
- 一问一答澄清：需要追问时一次只问一个最高价值问题。
- 最小必要补全：补齐缺口，不替用户改目标。
- 任务即契约：优化后的 prompt 必须包含交付物、范围、约束和验收。
- 反思和沉淀：复杂任务结束后，要求 agent 记录项目模式、风险和复用规则。
A: 普通的 prompt 优化是"文案润色"，本项目是"意图对齐"。它不是让你的 prompt 写得更好看，而是确保 AI agent 在执行前理解你的真实意图，并且具备可执行的契约。
A: 在冻结的 W8 v8 corpus（40 条）上，evidence 报告高风险漏放率 0%、完整请求误拦截率 0%、六类 route appropriateness 100%、验收相关率 95.24%。这不是对所有未见请求的保证；当前证据和边界见 canonical summary。
A: 每个新会话需要先用一次 /align <请求>。只有 Claude Code 已显式安装 --wire-hook（PowerShell 为 -WireHook）且当前会话已 /align 时，后续普通请求才会自动经过对齐；打开新会话后必须重新激活。Codex、Cursor 和未接线的 Claude Code 保持显式调用。
A: 目前支持：
- Claude Code（完整支持，包括 hook 拦截）
- Codex CLI（建议模式）
- Cursor（项目规则模式）
- 其他工具（通过复制 System Prompt）
A: 运行以下命令查看：
bash "$HOME/.prompt-optimizer/bin/align-doctor" --json "$PWD"A: 不会。路由器完全在本地运行，不收集任何用户数据。所有判断都在你的机器上完成。
欢迎贡献！请查看 CONTRIBUTING.md 了解如何参与项目开发。
- 克隆仓库
- 安装依赖：
cd core/host/pipeline && npm install - 运行测试：
npm test - 构建项目：
powershell -File build/build.ps1（Windows）或bash build/build.sh（macOS/Linux）
- 使用中文提交信息
- 格式：
类型: 描述 - 类型：feat/fix/docs/chore/test/refactor
| 指标 | 目标 | 实际 | 状态 |
|---|---|---|---|
| 高风险漏放率 | 0% | 0% | ✅ |
| 完整请求误拦截率 | ≤10% | 0% | ✅ |
| 六类 route appropriateness | ≥90% | 100% | ✅ |
| 验收相关率 | ≥90% | 95.24% | ✅ |
| 最高价值问题命中率 | ≥80% | 91.67% | ✅ |
| 问题生成 | 100% | 100% | ✅ |
| exact route/reason/action | 全部通过 | 40/40 | ✅ |
- TypeScript 测试：26 suites, 384 tests
- Fresh production corpus v8：40 条请求、6 个类别
- Independent blind review：12 条实际生成澄清问题
- Frozen behavior cases：56 条确定性行为
- 协议内核：8 个文件（00-07）
- 模板：17 个（含 7 个 ALIGN 模板）
- Skill：3 个（optimize-prompt、align-init、optimize-prompt-lite）
- 宿主适配：4 个（Claude Code、Codex、Cursor、Universal）
MIT。安全问题请按 SECURITY.md 私密报告。