paudley/coding-ethos

# 编码理念 [](https://github.com/paudley/coding-ethos/actions/workflows/ci.yml) [](https://github.com/paudley/coding-ethos/actions/workflows/coding-ethos-sarif.yml) [](https://github.com/paudley/coding-ethos/actions/workflows/codeql.yml) [](https://github.com/paudley/coding-ethos/actions/workflows/osv-scanner.yml) [](https://github.com/paudley/coding-ethos/actions/workflows/zizmor.yml) [](https://github.com/paudley/coding-ethos/releases) [](https://pypi.org/project/coding-ethos/) [](https://pypi.org/project/coding-ethos/) [](https://github.com/paudley/coding-ethos/actions/workflows/release.yml) [](https://scorecard.dev/viewer/?uri=github.com/paudley/coding-ethos) [](https://www.bestpractices.dev/en/projects/12737) [](https://paudley.github.io/coding-ethos/) [](docs/SUPPLY_CHAIN_ATTESTATIONS.md) [](docs/SUPPLY_CHAIN_ATTESTATIONS.md) [](SECURITY.md) [](LICENSE) 面向 AI 代理的策略即代码执行：MCP 服务器、CEL 策略、Git 钩子、 SARIF、运行时沙箱以及静态分析防护机制。 `coding-ethos` 将工程原则转化为适用于 人类贡献者和 AI 编码代理的可运行仓库策略。 该项目目前获得了 [OpenSSF 最佳实践银级徽章](https://www.bestpractices.dev/en/projects/12737) 并在 [docs/OPENSSF_GOLD_CHECKLIST.md](docs/OPENSSF_GOLD_CHECKLIST.md) 中追踪金级就绪状态。 它将代理指令、生成的文档、静态分析配置、 Git 钩子、代理工具使用防护、MCP 工具、CEL 自定义策略、生成的 技能以及运行时公理保持在同一个源契约中。人类贡献者和 AI 代理看到相同的标准，运行相同的检查，并在 不良更改落地前触及相同的关键安全门。 在以下情况下请使用 `coding-ethos`： - 适用于 Codex、Claude Code、Gemini CLI 及其他编码代理的 AI 代理防护机制。 - 一个可供代理调用的本地 MCP 服务器，用于策略检查、lint 建议、 SARIF 修复以及基于 ETHOS 的上下文。 - Git 钩子强制执行，可在提交前捕获不安全的命令、受保护路径的编辑、 未管理的工具使用以及文件膨胀问题。 - CEL 策略即代码，将与 ETHOS 原则密切相关的仓库特定规则保留在它们所执行的位置附近。 - 用于 CI、拉取请求、IDE 和趋势分析的 SARIF 及代码扫描输出。 - 代码智能，将钩子跟踪、SARIF、修复结果、 Tree-sitter 块、AST 链接和 sqlite-vec 元数据存储在仓库本地的 SQLite 存储中，供代理搜索。 ## 30 秒快速开始 ``` make install make check make install-hooks ``` 完整的 Git 和 AI 代理钩子切换： ``` make cutover-install ``` 为已配置的代理启动本地 MCP 服务器： ``` bin/coding-ethos-run mcp ```  该项目围绕 AI 辅助编码的纵深防御构建： - **ETHOS 作为来源：** `coding_ethos.yml` 和仓库覆盖层是骨干： 原则拥有其技能、公理、生成的文档以及一流的策略基础。 - **编译时强制执行：** Go 钩子运行时通过相同的决策模型评估内置策略和 类型化的 CEL 表达式策略。 - **管理的工具：** lint 和类型检查通过生成的配置、 管理的二进制文件、规范化的诊断和跟踪日志运行。 - **运行时能力：** 管理的工具声明网络、Git、沙箱、 超时、内存、CPU 和 seccomp 能力，CEL、MCP、跟踪和 SARIF 都可以对其进行检查。 - **沙箱捕获：** 管理的 lint 可以通过 Bubblewrap 支持的 沙箱原型运行，该原型具有只读仓库和 `.git` 挂载，为离线工具断开 网络，并提供规范化的拒绝证据。 - **代理引导：** Claude、Codex 和 Gemini 接收生成的钩子设置、 MCP 服务器配置、技能、提示附录和简明的公理建议。 - **修复反馈：** lint 发现、被阻止的策略决定、技能提示 和 MCP 指导都会将代理引导回相关的 ETHOS 契约。 ## 为什么它很重要 当指导和执行发生偏差时，AI 编码工作面临的失败最为严重： - Markdown 规则说了一件事 - linter 检查了另一件事 - Git 钩子允许第三件事通过 - 代理看到了这种不匹配，并将安全系统视为已损坏 `coding-ethos` 通过将仓库的工作协议编译到 贡献者实际工作的位置来弥合这一差距： | 表面 | 它所获得的内容 | | --- | --- | | 代理上下文 | `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`ETHOS.md` 和深层原则文档 | | 工具配置 | Pyright、mypy、Ruff、Pylint、YAML、Bandit、SQLFluff、Tombi 和 golangci-lint 配置 | | Git 钩子 | 编译的 Go 策略预检和确定性的钩子组 | | 代理钩子 | Claude、Codex 和 Gemini 工具使用防护 | | MCP | 来自编译包的 stdio 策略、技能、lint、SARIF 和工具能力查询 | | AI 审查 | 基于 ethos 和仓库配置的 Gemini 提示包 | | CI/CD | SARIF 输出以及生成的 GitHub Actions 和 GitLab CI 门禁，包含 actionlint、CodeQL、OSV-Scanner、zizmor、artifacts、包验证和沙箱证据 | | 审计数据 | `.coding-ethos/hook-runs/`、`.coding-ethos/lint-runs/` 和 `.coding-ethos/code-intel.db`，包含策略、工具、SARIF、AST、修复和沙箱证据 | ## 本仓库中使用的代理 `coding-ethos` 在人类审查和 AI 代理辅助下进行开发。该项目明确针对并已在与以下工具的合作中成型： - **来自 OpenAI 的 Codex**：编码、审查、重构、文档和仓库策略工作流验证。 - **Claude Code**：编码、钩子集成、生成的技能表面和策略反馈循环。 - **Gemini CLI**：审查提示、生成的提示包和独立的代理钩子兼容性检查。 代理辅助不会改变质量标准。生成的或代理编写的更改应通过与人工编写的更改相同的钩子、静态分析、测试、审查反馈和 ETHOS 策略门禁。 该项目大量使用其自身的防护机制：在开发 `coding-ethos` 自身时，Codex、Claude 和 Gemini 会通过生成的钩子、MCP 配置、技能、公理、管理的工具链和策略反馈表面运行。 ## 纵深防御 策略被有意分层。没有单一的钩子、文件或代理指令会被信任为唯一的防线。 ``` coding_ethos.yml repo_ethos.yml │ │ ├──── merged ethos ──┤ │ │ ▼ ▼ AGENTS.md / CLAUDE.md / GEMINI.md / ETHOS.md .agents/ethos/ deep docs .agent-context/ prompt addons .agents/skills/ remediation playbooks runtime axioms with MCP next steps principle-owned CEL policies config.yaml repo_config.yaml │ │ ├── merged enforcement config │ ├── generated tool configs ├── transitional CEL expression policies ├── Gemini prompt pack ├── Go policy bundle ├── Git hook runtime ├── agent hook runtime └── MCP server tools ``` 相同的输入驱动指导和执行。未知的 linter 发现仍会正常流转；与 ETHOS 原则相关的发现可以接收更强有力的、基于策略的建议，而不是通用的工具文本。当发现映射到生成的技能时，面向代理的输出包括一个简明的 `skill_id` 提示和加载该修复手册的下一步操作。 技能和公理是相同纵深防御计划的一部分，而不是装饰性的提示文本。技能提供可跨提供商移植的修复手册。公理是简短的、特定于原则的提醒，当钩子与策略决定相关时（总是出现在 lint 调用中，以及在统计学概率上的其他后置钩子事件中），会显示这些提醒。渲染的公理建议包含代理接下来应使用的 MCP 调用，因此建议可以从简明的指导升级为 `policy_explain`、`skill_lookup` 或 `skill_recommend`，而无需将完整上下文转储到每个钩子响应中。 CEL 支持将相同的模型扩展到仓库特定的策略。一流的 CEL 策略与它们在 `coding_ethos.yml` 中执行的 ETHOS 原则放在一起。配置级别的 `policy.expressions` 仍然可用于消费者覆盖层和尚未表达为 ETHOS 契约一部分的过渡性策略。编译器预先检查 CEL，通过钩子和 lint 路径分发它，并发出具有 ETHOS 基础和技能提示的常规策略决定。 源感知策略遵循所记录的 [AST、CEL 和 SARIF 架构](docs/AST_CEL_SARIF_ARCHITECTURE.md)。Go 收集规范化的 Tree-sitter 事实，CEL 拥有可配置的策略谓词，而 SARIF 携带稳定的 AST 身份和修复元数据。相同的事实提供给钩子预检、lint 策略、SARIF、MCP 和代码智能存储。 新的 Python、Go、shell、JavaScript/TypeScript、YAML、JSON、TOML 或配置策略应在添加临时的文本扫描器或特定于策略的 AST 遍历器之前扩展该路径。 运行时能力策略使用相同的路径。管理的工具声明它们是否需要网络、Git、环境访问、可写路径、沙箱配置文件、超时、内存、CPU 和 seccomp 配置文件。这些事实作为 `tool_capabilities` 可用于 CEL，通过 MCP 公开，保留在 `.coding-ethos` 跟踪中，并复制到 SARIF 运行属性中。内置的管理工具契约会阻止忘记声明离线/无 Git 行为或资源边界的普通 lint 工具。 运行时沙箱是互补的数据平面。当前的 Go 原型可以通过 Bubblewrap 运行管理的 lint 捕获，具有只读根目录、只读仓库和 `.git`、隐藏的 HOME 目录、断开网络的离线工具、声明的可写挂载、硬超时、cgroup 资源请求和 seccomp 配置文件元数据。Linux cgroup 限制在进程启动前在委托层次结构中准备，并在退出后清理。所需的沙箱模式遇到故障会安全关闭并生成规范化的策略发现；建议模式记录降级的证据，而不声称进行了强制执行。参见 [docs/RUNTIME_SANDBOXING.md](docs/RUNTIME_SANDBOXING.md)。 代码智能存储是这些证据的记忆层。仓库本地的 SQLite 存储接收钩子跟踪、lint 跟踪、SARIF、修复结果、钩子使用分析、Tree-sitter 块、图边缘和 AST 到发现的链接。FTS5 提供精确搜索，而 sqlite-vec 存储派生的嵌入行，用于在没有守护进程或托管向量服务的情况下进行混合检索。MCP 工具公开搜索、代码索引、聚焦的块查找、嵌入候选和索引状态，以便代理在广泛读取文件或重复失败修复之前检索相关上下文。参见 [docs/CODE_INTEL.md](docs/CODE_INTEL.md)。 仓库信任表面是产品的一部分。公共仓库现在包含 CODEOWNERS、用于策略规则、钩子误报和 MCP 工具请求的结构化 issue 模板、GitHub Discussion 模板、适用于所有管理生态系统的 Dependabot 冷却期、受限的 Actions 允许列表、CodeQL、OSV-Scanner、zizmor、Scorecard、模糊冒烟测试、发布证明和 SBOM 生成。参见 [docs/TRUST_SIGNALS.md](docs/TRUST_SIGNALS.md)。 对于更大的平台方向，例如更深入的 MCP 上下文服务、策略语言支持、IDE 集成、SARIF/CI 组件、红队测试、ETHOS 继承和代理修复循环，请参见 [docs/STRATEGIC_ROADMAP.md](docs/STRATEGIC_ROADMAP.md)。 文档登录页是 [docs/index.md](docs/index.md)，推广/安全信任工作在 [docs/TRUST_SIGNALS.md](docs/TRUST_SIGNALS.md) 中进行跟踪。 供应链信任控制、Scorecard 发布、GitHub artifact 证明、SBOM 生成、PyPI Trusted Publishing 和验证命令记录在 [docsUPPLY_CHAIN_ATTESTATIONS.md](docs/SUPPLY_CHAIN_ATTESTATIONS.md) 中。 CI 发布 JUnit XML、Python 覆盖率和 Go 覆盖率 artifact 作为公共测试证据。 安全态势总结在 [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) 中， 发布就绪情况记录在 [docs/RELEASE.md](docs/RELEASE.md) 中。 已验证的演示文稿本是 [docs/DEMO.md](docs/DEMO.md)。 有关定位和采用规划，请参见 [docs/COMPARISON.md](docs/COMPARISON.md)、 [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) 和 [examples/](examples/)。 优先考虑 CEL 的策略语言设计在 [docs/POLICY_LANGUAGE_STRATEGY.md](docs/POLICY_LANGUAGE_STRATEGY.md) 中进行跟踪。 CI/CD 使用和 SARIF 上传示例记录在 [docs/CI_CD_SARIF.md](docs/CI_CD_SARIF.md) 中。 可运行且可复制的示例从 [examples/](examples/) 开始。 ## MCP 服务器 `coding-ethos` 包含一个由相同编译策略包和生成的技能元数据（供 Git 钩子和代理钩子使用）支持的本地 stdio MCP 服务器。 设计和扩展计划记录在 [docs/MCP_SERVER.md](docs/MCP_SERVER.md) 中。 服务器通过管理的运行时公开： ``` bin/coding-ethos-run mcp ``` 最初的工具被有意设计得狭窄且可审计： - `policy_check_command`：在运行建议的 shell 命令之前进行检查。 - `policy_check_edit`：在应用建议的文件编辑之前进行检查。 - `lint_check`：对 Ruff、mypy、pyright、pylint、ESLint、SQLFluff 和其他捕获的工具运行管理的 lint 捕获；当未提供工具时，对当前工作运行编译的 coding-ethos 策略 lint 检查。 - `lint_advice`：将 lint 诊断映射到 ETHOS 策略、建议和技能提示。 - `sarif_remediation_advice`：将 SARIF 或保留的跟踪证据转化为聚焦的基于 ETHOS 的修复指导。 - `sarif_risk_summary`：总结 SARIF 运行的策略、技能、文件、工具、严重性和下一步行动风险信号。 - `sarif_trend_analysis`：比较 SARIF 运行或保留的跟踪，以发现引入的、已修复的、持续存在的、重新打开的和恶化的发现。 - `sarif_policy_feedback`：向策略作者报告未映射的诊断、缺失的技能、弱严重性映射和嘈杂的规则。 - `tool_capabilities`：列出管理的工具能力，包括网络/Git 标签、沙箱配置文件、超时、内存、CPU、seccomp 配置文件元数据和声明的读/写挂载。 - `policy_explain`：返回策略 ID 的编译说明。 - `skill_lookup`：通过技能 ID 返回源于 ETHOS 的技能手册。 - `remediation_explain`：将发出的 `agent_remediation` 项扩展为策略、原则、技能和重试指导。 - `code_intel_search`：使用 FTS 和 sqlite-vec 向量搜索检索存储的 SARIF/修复/代码块证据。 - `code_intel_index_status`：报告 SQLite/sqlite-vec 索新鲜度和嵌入覆盖率。 - `code_similarity_check`：使用规范化的哈希和 MinHash LSH，针对索引的仓库符号对建议的代码进行预检。 - `code_intel_index_code`：刷新 Go、Python、JavaScript/TypeScript、shell、YAML、JSON 和 TOML 路径的 Tree-sitter 块。 - `code_intel_code_chunks`：在广泛读取文件之前获取聚焦的符号/配置块。 - `code_intel_code_context`：将已知的块、符号路径或文件行扩展为最近的 AST 上下文、图边缘和链接的发现。 - `code_intel_embedding_candidates`：为批准的嵌入生产者返回紧凑的可跟踪记录。 - `skill_recommend`：为手头的任务推荐源于 ETHOS 的技能。 当违规可以被解释时，钩子、提供商原生的块响应、lint、SARIF 和跟踪输出也包括一个 `agent_remediation` 负载。每一项都带有一个稳定的修复 ID、策略 ID、ETHOS 原则 ID、技能 ID、失败的操作或文件位置、具体的下一步骤、已知时的重新运行命令，以及代理接下来应进行的 MCP 调用。代理可以将完整项传递给 `remediation_explain`，或直接遵循嵌入的 `policy_explain` 或 `skill_lookup` 调用。参见[代理修复负载](docs/AGENT_REMEDIATION.md)。 工具定义包括 `coding_ethos` 元数据，该元数据告诉客户端某个工具是建议性的、读取文件的、执行管理的 lint 工具的，还是持久化跟踪的。 代理应调用 `lint_check` 而不是直接调用 linter，以便目标解析、生成的配置完整性、管理的工具版本、证据映射、技能提示和跟踪日志保持在强制执行路径上。 代理应在运行时行为重要时，在选择管理的工具之前调用 `tool_capabilities`；它是 CEL 用于策略决定的相同能力事实的 MCP 视图。 MCP 服务器是建议性上下文，而不是旁路。钩子强制执行保留在正常的 Git 和代理钩子路径上，并且 MCP 响应来自与这些强制执行路径相同的编译策略输入。 ## ETHOS 技能 技能是生成的修复手册，而不是单独的手动维护的文档层。`coding_ethos.yml` 用其 ETHOS 原则、触发词、简短提示、焦点和修复步骤定义每个技能。`make build` 将这些技能渲染到可移植的 `.agents/skills/` 树以及原生的 Claude、Codex 和 Gemini 技能位置。 编译的策略包携带相同的技能元数据。当发现通过证据映射、与技能的 ETHOS 原则重叠或匹配技能触发词时，运行时 lint 和钩子结果会附加一个 `skill_id`。 面向代理的输出保持紧凑：TOON 和人类输出发出技能 ID、简短提示和下一步操作，而不是将完整的技能主体转储到代理上下文中。 技能提示也记录在 `.coding-ethos/lint-runs/` 下。这些跟踪让项目能够衡量哪些修复手册出现在实际工作中，并将反复出现的未映射发现提升为更强的证据映射或仓库特定的技能。 `coding-ethos` 还可以将保留的 lint 和钩子跟踪导入本地的 SQLite 代码智能存储，用于重复失败和修复搜索： ``` bin/coding-ethos-run code-intel ingest-traces bin/coding-ethos-run code-intel repeated-failures --policy-id python.unused_imports bin/coding-ethos-run code-intel search --text 'unused import' bin/coding-ethos-run code-intel compact-context --path pkg/app.py bin/coding-ethos-run code-intel proxy-sessions --provider codex ``` 该存储位于 `.coding-ethos/code-intel.db`；它是仓库本地的，并派生自保留的跟踪、SARIF、AST 块、代理会话事件、修复记录和向量元数据。它不是钩子或 CEL 策略评估的替代品。 当前内置技能： - `agent-operating-discipline` - `conditional-imports` - `lint-remediation` - `managed-toolchain` - `safe-git-workflow` `agent-operating-discipline` 将来自 [`forrestchang/andrej-karpathy-skills`](https://github.com/forrestchang/andrej-karpathy-skills) 的有用行为模式调整到 coding-ethos 的派生技能模型中：明确的假设、简单的设计、精确的 diff 和可验证的成功标准。上游仓库是一个有用的灵感来源，但 coding-ethos 将规范文本保存在 `coding_ethos.yml` 中，并从该来源重新生成特定于提供商的技能文件。 ## 快速开始 安装依赖和生成的本地 artifact： ``` make install ``` 运行标准验证门禁： ``` make check ``` 安装仓库本地的 Git 钩子： ``` make install-hooks ``` 安装并验证完整的 Git 和代理钩子切换： ``` make cutover-install ``` 为此仓库生成面向代理的文件： ``` make generate ``` 为另一个仓库生成文件： ``` make generate REPO=/path/to/repo ``` ## PyPI 包使用 PyPI 包安装 Python 生成器 CLI 以及默认的 `coding_ethos.yml`、基础 `config.yaml` 和示例覆盖层。该路径适用于在不克隆源代码检出的情况下生成代理文档： ``` uvx coding-ethos --repo . ``` 相同的 CLI 可以通过 `pipx` 运行： ``` pipx run coding-ethos --repo . ``` PyPI 包有意不发布编译的 Go 钩子运行时或管理的二进制工具链。完整的 Git 钩子和代理钩子安装仍使用带有 `make build` 和 `make cutover-install` 的源代码检出/子模块路径；有关在源代码检出之外发布编译运行时所需的发布资产策略，请参见[运行时发布](docs/RUNTIME_PUBLICATION.md)。 在源代码检出中，生成的工具配置、生成的 GitHub/GitLab CI、Gemini 提示包和提供商技能表面仅由通过 `bin/coding-ethos-policy` 和 `bin/coding-ethos-run policy` 公开的编译策略运行时进行渲染。 ## 管理的运行时架构 Go 命令二进制文件被有意设计得很薄。产品行为位于专注的内部包中，而 `go/cmd/*` 包解析进程入口点参数并委托给这些包。这使得钩子执行、管理的捕获、策略评估、代码智能、MCP 和 Git 包装无需让 Go 代码通过 shell 调用其他 coding-ethos Go 二进制文件即可保持可测试性。 当前运行时所有权： | 表面 | 所属包 | | --- | --- | | 钩子组和钩子报告 | `go/internal/hookrunnercli` | | Git 钩子预检和生命周期钩子 | `go/internal/githookcli` | | 管理的 lint/测试捕获 | `go/internal/managedcapture` 加 `go/diagnostics` | | Lint CLI 编排 | `go/internal/lintcli` | | 策略包、配置同步和 CI 配置同步 | `go/internal/policycli`、`go/internal/toolconfigs` | | 代理钩子设置和检查 | `go/internal/agenthookscli`、`go/internal/agenthooks` | | MCP 服务器和 CLI | `go/internal/mcp`、`go/internal/mcpcli` | | 代码智能摄入/查询 | `go/internal/codeintel`、`go/internal/codeintelcli` | | Git 包装器行为 | `go/internal/policygitcli`、`go/internal/realgit`、`go/internal/gitwrap` | | 管理的工具链安装和验证 | `go/internal/toolchaincli` | 所有管理的工具输出都应通过相同的证据路径： 目录支持的执行、流捕获、解析器规范化、诊断、CEL 策略提升、跟踪保留和 SARIF 格式化。钩子运行器代码不拥有解析或格式化；它运行钩子组并从拥有这些关注点的包中报告规范化结果。 ## 常见工作流 | 目标 | 命令 | | --- | --- | | 显示解析的路径和配置 | `make status` | | 检查所需的本地工具 | `make doctor` | | 刷新生成的配置、管理的工具、钩子入口点和父运行时 | `make build` | | 运行 Python 测试 | `make test` | | 运行完整的本地检查 | `make check` | | 运行所有配置的 linter | `make lint` | | 运行所有配置的格式化工具 | `make format` | | 应用管理的自动修复工具 | `make fix` | | 格式化，然后应用自动修复工具 | `make lint-fix` | | 对构建的 wheel 进行冒烟测试 | `make package-smoke` | | 模拟运行发布包检查 | `make release-dry-run` | | 验证钩子运行时 | `make validate` | | 运行 Go 测试 | `make go-test` | | 同步生成的工具配置 | `make sync-tool-configs` | | 检查生成的工具配置偏差 | `make check-tool-configs` | | 同步 Gemini 提示包 | `make sync-gemini-prompts` | | 检查 Gemini 提示包偏差 | `make check-gemini-prompts` | | 检查生成的代理技能偏差 | `make check-agent-skills` | | 运行暂存文件钩子 | `make pre-commit` | | 对所有文件运行钩子 | `make pre-commit-all` | | 运行 pre-push 钩子 | `make pre-push` | | 生成代理文档 | `make generate` | | 在生成时保留现有的根代理文档 | `make generate-merge` | | 使用外部代理 CLI 进行根文件合并 | `make generate-merge-llm` | 有用的覆盖： ``` make generate REPO=/path/to/repo PRIMARY=/path/to/coding_ethos.yml make generate REPO=/path/to/repo REPO_ETHOS=/path/to/repo_ethos.yml make sync-tool-configs \ TOOL_CONFIG_REPO=/path/to/repo \ REPO_CONFIG=/path/to/repo_config.yaml make seed SEED_FROM=/path/to/ETHOS.md PRIMARY=/path/to/coding_ethos.yml ``` ## 直接 CLI 使用 该包公开了 `coding-ethos`。在本地开发期间，Makefile 通过 `uv run python main.py` 运行，以便使用仓库本地的源代码。 生成代理文档： ``` uv run coding-ethos --repo /path/to/repo --primary coding_ethos.yml ``` 从 Markdown 植入主 YAML 文件： ``` uv run coding-ethos \ --primary coding_ethos.yml \ --seed-from-markdown /path/to/ETHOS.md ``` 同步生成的工具配置： ``` make sync-tool-configs REPO=/path/to/repo ``` 默认情况下，相同的命令会写入管理的 SARIF CI 文件，并将其包含在 `.code-ethos/tool-config-hashes.json` 中。生成的 GitHub 工作流默认是可重用的，因此仓库级别的 CI 工作流可以拥有并发性、必需的检查、包验证和证明，而无需重复上传 SARIF。 具有例外的仓库可以在其合并的强制执行配置中设置 `generated_config.ci.github_actions.enabled: false` 或 `generated_config.ci.gitlab.enabled: false`。 它们由 `make check-tool-configs` 检查；没有单独的 CI 同步路径。 检查生成的工具配置偏差： ``` make check-tool-configs REPO=/path/to/repo ``` 跟踪和验证强制执行配置： ``` bin/coding-ethos-run policy config-trace --json ``` 同步 Gemini 钩子提示包： ``` make sync-gemini-prompts REPO=/path/to/repo PRIMARY=coding_ethos.yml ``` ## 仓库模型 | 来源 | 目的 | 派生输出 | | --- | --- | --- | | `coding_ethos.yml` | 共享的 ethos 契约 | 根代理文档、深层原则文档、ETHOS 技能、公理和原则拥有的 CEL 策略 | | `repo_ethos.yml` | 仓库本地上下文和覆盖 | 特定于仓库的代理指导 | | `config.yaml` | 包范围的强制执行默认值 | 工具配置、钩子、提示基础 | | `repo_config.yaml` / `repo_config.yml` | 消费者仓库覆盖 | 特定于仓库的强制执行 | | `pre-commit/prompts/` | Gemini 提示模板 | `.code-ethos/gemini/prompt-pack.json` | | `pre-commit/` | 钩子包 | 仓库本地的 Git 和代理钩子运行时 | 生成的 Markdown 文件是派生 artifact。首先更改 YAML 源或渲染器，然后重新生成并审查生成的 diff。 ## 生成的输出 面向代理的输出： ``` repo/ ├── AGENTS.md ├── CLAUDE.md ├── ETHOS.md ├── GEMINI.md ├── .agent-context/ │ └── prompt-addons/ │ ├── claude.md │ ├── codex.md │ └── gemini.md ├── .agents/ │ ├── ethos/ │ │ ├── README.md │ │ ├── solid-is-law.md │ │ └── ... │ └── skills/ │ ├── conditional-imports/ │ │ └── SKILL.md │ └── lint-remediation/ │ └── SKILL.md ├── .codex/ │ └── skills/ │ └── ... ├── .gemini/ │ └── extensions/ │ └── coding-ethos/ │ ├── gemini-extension.json │ └── skills/ │ └── ... └── .claude/ ├── ethos/ │ └── MEMORY.md └── skills/ └── ... ``` 强制执行输出： ``` repo/ ├── pyrightconfig.json ├── mypy.ini ├── ruff.toml ├── .yamllint.yml ├── .bandit.yml ├── .sqlfluff ├── tombi.toml ├── .golangci.yml └── .code-ethos/ ├── cache/ │ └── ... ignored runtime caches └── gemini/ └── prompt-pack.json ``` ## 配置 ### `coding_ethos.yml` 主要的 ethos YAML 是共享源契约。它使用 `version: 2`、元数据和一个有序的原则列表。每个原则需要一个 `id`、`order`、`title`、`directive` 和至少一个节或内联主体。 可选的顶层 `skills` 列表定义了基于 ETHOS 原则的可跨提供商移植的技能。生成会将相同的技能主体发送到可移植的 `.agents/skills/` 树以及原生的 Claude、Codex 和 Gemini 位置。编译的 Go 策略包也携带这些技能定义，以便 linter 证据可以指向 `skill_id`，运行时输出可以将代理引导到正确的修复手册。 每个原则还可以定义本地 `axioms`。公理是由它们所解释的 ETHOS 原则拥有的简短提醒，而不是单独的强制执行配置列表。编译器从 `principles[].axioms` 派生钩子提醒建议，当没有明确的公理时，回退到原则的 `quick_ref` 和指令。这使得建议、强制执行基础、生成的文档和运行时后置钩子提醒保持附加在相同的内聚 ETHOS 条目上。 运行时钩子建议分两个阶段显示这些公理：与策略相关的钩子结果首先发出优先的 ETHOS 提醒，而不相关的后置钩子输出在 lint 调用上获得一个环境提醒，在其他调用上获得一个抽样的单个提醒。渲染的提醒包括代理接下来应调用的 MCP 工具和参数，例如用于被阻止的策略的 `policy_explain` 或用于原则级别指导的 `skill_recommend`。 行为技能应遵循与修复技能相同的真实来源规则。例如，`agent-operating-discipline` 融合了来自 [`forrestchang/andrej-karpathy-skills`](https://github.com/forrestchang/andrej-karpathy-skills) 的想法，而没有将静态的提供商提示复制到仓库中；编辑应在 `coding_ethos.yml` 中进行，然后 `make build` 重新生成检入的表面。 当省略 `--primary` 时，可接受的主要别名： - `coding_ethos.yml` - `coding_ethos.yaml` - `code_ethos.yml` - `code_ethos.yaml` ### `repo_ethos.yml` 可选的仓库覆盖层添加了本地命令、路径、说明、每个代理的说明、原则覆盖和附加的特定于仓库的原则。 参见 [repo_ethos.example.yml](repo_ethos.example.yml)。 ### `config.yaml` 和 `repo_config.yaml` `coding_ethos.yml` 是策略意图的骨干。`config.yaml` 是用于生成的工具设置、操作默认值和尚未用 ETHOS 原则明确表达的策略的包范围强制执行 artifact。消费仓库可以在仓库根目录使用 `repo_config.yaml` 或 `repo_config.yml` 或通过传递 `--repo-config` 来优化编译的强制执行 artifact。 合并的配置驱动： - 生成的 Pyright、mypy、Ruff、Pylint、YAML、Bandit、SQLFluff、Tombi 和 golangci-lint 配置 - 生成的 GitHub Actions 和 GitLab CI SARIF 门禁，由 `generated_config.ci.*.enabled`、超时、触发器、artifact、测试和构建旋钮控制 - 用于 Python、shell、文本、提交消息和 Go 检查的钩子策略 - Gemini AI 审查设置和提示基础 - 共享的样式设置，例如 `style.python_version` 和 `style.line_length` `coding-ethos-policy config-trace` 验证已知的顶层强制执行部分，编译合并的包，验证它，并报告策略、证据映射和分派计数。在更改 `config.yaml` 或消费者 `repo_config.yaml` 时使用它，以便未知的部分不会悄悄地发生偏差。 许可证和版权强制执行是特定于仓库的。消费仓库不继承此仓库的许可证策略。要选择加入，请在 `repo_config.yaml` 中设置 `repo.license.spdx_identifier`，如果需要，还可以设置 `repo.license.copyright`。编译的策略会下载 SPDX 许可证文本，在不覆盖仓库 `LICENSE` 文件的情况下验证它，并要求匹配的 SPDX 源文件头。 参见 [repo_config.example.yaml](repo_config.example.yaml)。 ### CEL 表达式策略 一流的 CEL 策略应位于 `coding_ethos.yml` 中的相关原则之下： ``` principles: - id: solid-is-law policy: expressions: - id: filesystem.line_limits scope: file severity: block when: > file_changes.exists(file, file.ext == ".py" && file.line_count > 1000) message: Large source files must not keep growing. advice: Split large files into focused modules before committing. ``` 消费仓库也可以在 `repo_config.yaml` 的 `policy.expressions` 下添加小的自定义策略。该路径是一个覆盖层和过渡性扩展点，而不是共享 ETHOS 策略的首选归宿。这些策略是编译到策略包中并由与 Go 支持的策略相同的 Go 钩子运行时评估的 CEL 表达式。 将 CEL 用于规范化钩子或 lint 数据上的狭窄谓词，例如阻止特定于仓库的命令模式： ``` policy: expressions: - id: custom.no_python_subprocess_git description: Block Python subprocess attempts to route around protected Git. scope: command severity: block principle_ids: - one-path-for-critical-operations - no-rationalized-shortcuts skill_id: safe-git-workflow when: > shell_commands.exists(cmd, cmd.name in ["python", "python3"] && cmd.argv.exists(arg, arg.contains("subprocess")) && cmd.argv.exists(arg, arg.contains("git")) ) message: Git must use the approved repo workflow. advice: Run ordinary git commands without bypass flags or shell indirection; approved operations are routed by the hook automatically. ``` 当前支持的字段包括： - `command`：用于命令范围钩子策略的原始命令文本。 - `argv`：可用时解析的命令参数。 - `shell_commands`：来自 `mvdan.cc/sh/v3/syntax` 的解析器规范化的 shell 命令事实，包括命令名称、argv、前导分配、重定向、here-doc、行/列、后台执行、动态扩展标志、命令/进程替换标志、shell 执行检测、Git 检测、lint 工具检测和 PATH 覆盖检测。格式错误的 shell 文本会在策略评估继续之前被阻止。 - `files`：当前钩子或 lint 事件的仓库提供文件目标。 - `file_changes`：类型化的暂存文件事实，包括状态、扩展名、生成/测试/受保护标志、字节大小、当前行数以及在 Git 可以提供时的原始行数。 - `diff`：由 Go 准备的暂存 diff 事实，包括更改/暂存文件列表、块、添加的行、删除的行、行号、旧/新行号和块头。 - `event`：提供商原生的钩子元数据，例如提供商、钩子名称、工具、来源、匹配器、会话 ID、转录路径、工具输入/工具响应键、返回代码和用于 Claude、Codex 和 Gemini 的提供商布尔值。 - `cwd`：调用工作目录。 - `scope`：表达式范围，例如 `command`、`path`、`diagnostic` 或 `finding`。 - `metadata`：非敏感事件元数据。 - `path`、`diagnostic`、`finding` 和 `repo`：用于初始路径、诊断、发现和仓库策略切片的类型化对象。 - `similarity_facts`：当前文件集的基于 MinHash LSH 的代码相似性结果，包括源/匹配路径、符号元数据、Jaccard 相似性分数和精确规范化标志。仅当 CEL 表达式引用 `similarity_facts` 时，才从代码智能存储中惰性填充。运行时阈值和 MinHash 参数来自 `config.yaml` 的 `similarity` 部分。 CEL 被有意设计为纯函数。表达式不能读取文件、运行 shell 或 Git、检查环境变量、访问网络或依赖挂钟时间。Go 准备规范化的事实；CEL 对这些事实做出决定。 每个表达式策略必须基于 `principle_ids` 的 ETHOS，并且当生成的技能解释修复路径时，应包含一个 `skill_id`。CEL 匹配发出正常的 coding-ethos 决定、诊断、TOON/人类输出、跟踪数据和技能提示。 当前边界： - CEL 现在覆盖了规范化事实上的大多数简单和中等复杂度的策略谓词，包括 Git、shell、文件、diff、仓库、路径、诊断、发现和事件输入。 - 多文件和多发现语义必须使用明确的集合，例如 `paths`、`files`、`file_changes`、`findings` 和 `diff`；不要依赖于隐式的第一个文件排序。 - Diff 行事实是暂存 diff 事实。需要未暂存编辑器内容的策略应使用钩子文件/内容事实或专用 Go 评估器。 - 将解析、Git 状态建模、管理的工具链行为、路径规范化、文件内容扫描、生成的配置新鲜度和其他安全敏感的事实收集保留在 Go 中。CEL 对准备好的事实做出决定；它不直接检查主机。 有关优先考虑 CEL 的决策记录和完整通用策略引擎的路线图，请参见 [docs/POLICY_LANGUAGE_STRATEGY.md](docs/POLICY_LANGUAGE_STRATEGY.md)。 ## 合并行为 `--merge-existing` 保留根代理文件： - `AGENTS.md` - `CLAUDE.md` - `GEMINI.md` `ETHOS.md` 和支持生成的文件被替换为确定性输出。 注入合并是默认策略： ``` uv run coding-ethos --repo /path/to/repo --merge-existing ``` 它将管理的导入块和附录块插入到现有的根文件中。重新运行是幂等的，并且管理块之外的本地创作内容将被保留。 LLM 合并要求已安装的 `codex`、`gemini` 或 `claude` CLI 在隔离的临时工作区内合并 `existing.md` 和 `generated.md`： ``` uv run coding-ethos \ --repo /path/to/repo \ --merge-existing \ --merge-strategy llm \ --merge-engine gemini \ --merge-bin /path/to/gemini \ --merge-timeout-seconds 300 ``` 选定的 CLI 必须已安装并经过身份验证。合并过程必须写入 `merged.md`；否则命令将失败。 ## 钩子运行时 捆绑的强制执行包位于 [pre-commit/](pre-commit/)。它使用直接解析为编译的 `bin/coding-ethos-run` 运行器的仓库本地 Git 钩子入口点。 ### Git 钩子 已安装的 Git 钩子入口点是调用 `bin/coding-ethos-run git-hook ` 或 `bin/coding-ethos-run lfs-hook ` 并带有原始 Git 参数的小型可执行脚本。运行器使用 `make build` 修复缺失的检出本地运行时 artifact，并分派给构建的钩子二进制文件。 策略选择和验证保留在 `coding-ethos` 检出内。 运行 Git 钩子： ``` make pre-commit make pre-commit-all make pre-push ``` 钩子输出遵循 `hooks.output_format`（`auto`、`human`、`json` 或 `toon`）。当存在已知的代理或 LLM 环境标记时，`auto` 选择 TOON。成功的组默认情况下是静默的；失败输出被有意缩窄：显示失败的检查和可操作的发现，而不是通过表格、内部组名或无助于修复代码的时间。 当策略预检同时具有仅记录上下文和阻止决策时，面向代理的结果会首先报告阻止者，并从紧凑的发现表中省略非阻止记录行。 编译的 lint 预检也会在 `.coding-ethos/lint-runs/` 下写入规范化的 JSON 跟踪。没有跟踪目录的新仓库将作为空历史进行分析，并且跟踪文件名使用可移植的范围名称，以便捕获的工具结果可以跨平台工作。 捕获的 linter 运行遵循单一事件契约：存储原始 argv、重写的 argv、退出代码、解析器身份、解析器结果、用于工具/配置失败的被遮蔽的 stdout/stderr 摘要、规范化的诊断以及应用的任何 ETHOS 映射。没有解析的诊断的非零工具运行本身就是一个发现，而不是空结果；面向代理的输出必须解释哪个工具失败了，为什么它不能产生正常的诊断，以及接下来应该检查什么命令或配置。 捕获的工具执行由 coding-ethos 控制，而不是由目标仓库控制：目标仓库被视为不受信任的文件树和跟踪目的地。包装器绝不能信任目标仓库的 `PATH`、绝对二进制文件、`uv run` 设置、`pyproject.toml`、shell 状态、别名或本地工具安装。 捕获的 stdout 和 stderr 被并发排空，因此来自管理工具的大容量 stderr 不会在 stdout 保持打开状态时导致运行死锁。 Python linter 是从 coding-ethos 钩子项目运行的，带有 coding-ethos 版和显式的 coding-ethos 生成配置标志（`ruff.toml`、`mypy.ini`、`pyrightconfig.json`、`.pylintrc`、`.yamllint.yml`、`.bandit.yml`、`.sqlfluff` 和 `tombi.toml`）。绝不能意外发现父仓库中具有相同名称的配置文件。 对于非 linter 的 Python 命令，钩子更倾向于消费者仓库环境：对于 uv 项目使用 `uv run --project python ...`，然后当仅存在 virtualenv 时使用 `/.venv/bin/python ...`。运行时还会在 coding-ethos 管理的目录之后将 `/.venv/bin` 添加到 `PATH` 中，以便受保护的 shim 保持在首位。 诸如 ShellCheck、actionlint、hadolint、dotenv-linter、golangci-lint 和 ESLint 之类的二进制 linter 通过管理的安装器安装到 `build/toolchain/`。ShellCheck、actionlint 和 hadolint 使用带有 SHA-256 摘要的固定 GitHub 发布资产；actionlint 和 golangci-lint 使用仓库 Go 工具链构建到管理的 Go bin 目录中；ESLint 从检入的 npm lockfile 安装，并通过管理的包装器公开。 源清单位于 `pre-commit/hooks/managed-toolchain.tsv`，并且安装的工具链会写入 `build/toolchain/manifest.tsv`。钩子执行将缺失的管理二进制文件视为运行时 artifact 故障，而不是回退到主机工具。 ESLint 被注册为 `javascript` 钩子组和管理的捕获工具，但在仓库选择加入并拥有明确的 ESLint 配置边界之前，它不是默认 pre-commit 或 pre-push 组集的一部分。 当前管理的 lint 和分析器集成： | 工具 | 生态系统 | 管理的获取 | 诊断解析器 | | --- | --- | --- | --- | | Ruff | Python | hook 项目 | JSON 和文本 | | mypy | Python | hook 项目 | JSON 行和文本 | | Pyright | Python | hook 项目 | JSON | | Pylint | Python | hook 项目 | JSON | | Bandit | Python 安全 | hook 项目 | JSON | | SQLFluff | SQL | hook 项目 | JSON | | Tombi | TOML | hook 项目 | 文本 | | yamllint | YAML | hook 项目 | 可解析文本 | | ShellCheck | shell | 固定的 GitHub 发布 | JSON | | actionlint | GitHub Actions | 固定的 Go 安装 | JSON 行 | | hadolint | Dockerfile | 固定的 GitHub 发布 | JSON 和文本 | | dotenv-linter | dotenv | 固定的 GitHub 发布 | 文本 | | golangci-lint | Go | 固定的 Go 安装 | JSON | | ESLint | JavaScript 和 TypeScript | 固定的 npm lockfile | JSON | 仓库 Makefile 仅公开用于普通源代码质量工作的统一管理工具组：`make lint` 运行 `linters` 组，`make format` 运行 `formatters` 组，`make fix` 运行 `autofixers` 组，`make lint-fix` 在 `format` 之后运行 `fix`。这些目标调用 `coding-ethos-run policy-tool-group ...`；它们绝不能直接调用单个 linter 或格式化工具，因为直接的工具输出会绕过规范化的诊断、跟踪存储、CEL 评估和 SARIF 生成。 分析捕获的 lint 历史： ``` bin/coding-ethos-run policy-lint --analyze-log bin/coding-ethos-run policy-lint --analyze-log --for-files lib/python/app.py bin/coding-ethos-run policy-lint --replay .coding-ethos/lint-runs/.json ``` 为 CI/代码扫描表面发出 SARIF： ``` bin/coding-ethos-run policy-lint --sarif --scope files --files lib/python/app.py bin/coding-ethos-run policy-lint --managed-capture-tool ruff --sarif -- check lib/python/app.py bin/coding-ethos-run policy-lint --managed-capture-tool ruff --sandbox-mode required --sarif -- check lib/python/app.py bin/coding-ethos-run policy-lint --sarif --replay .coding-ethos/lint-runs/.json ``` SARIF 是超集证据 artifact。coding-ethos 可以观察到的关于管理运行的所有内容都属于 SARIF：解析的诊断、无路径的工具级别故障、解析器状态、退出状态、stdout/stderr 捕获、沙箱证据、ETHOS 规则元数据、修复技能 ID 和确定性指纹。 CEL 接收已理解的子集：足够稳定以用于确定性策略决定的规范化事实和诊断。因此，当发现被观察到但尚未被 CEL 理解时，它可以仅存在于 SARIF 中。 代码扫描消费者仍然更倾向于使用仓库相对的 artifact URI 进行内联注释。coding-ethos 在存在位置时发出带有确切位置的可定位发现，并在证据是聚合或执行级别时发出无路径/工具级别的 SARIF 结果以及运行和结果属性。审计、MCP 修复和代码智能摄入绝不能仅仅因为发现未绑定到某一源代码行而丢失工具实际发出的内容。 管理的捕获可以使用 `--sandbox-mode required` 请求 Bubblewrap 沙箱原型。沙箱后端、配置文件、声明的能力和拒绝保留在 lint 跟踪和 SARIF 运行属性中，因此运行时强制执行具有与 CEL 和静态分析发现相同的审计跟踪。 面向代理的 lint 输出在 JSON 和 TOON 格式中包含一个 `agent_remediation` 块。SARIF 结果属性和保留的 `.coding-ethos/lint-runs/` 跟踪携带相同的派生负载，以便 CI 发现、MCP 修复和本地钩子故障将代理指向相同的下一步操作，而不是重复建议逻辑。 分析器将未映射的工具/代码对与基于 ETHOS 的发现分开突出显示，因此真实的 lint 跟踪可以驱动下一次证据映射添加。 重放在不调用底层 linter 的情况下渲染保存的规范化结果，这使得不良代理输出可以从跟踪文件中重现。 捕获的跟踪包括发出的技能提示，以便后续分析可以显示在实际工作中建议了哪些 ETHOS 修复手册。 输出质量是契约的一部分：被阻止的结果绝不能渲染空的发现表、绝对本地路径、内部时间/组噪声或没有至少一个可操作发现的通用指导。黄金输出测试应涵盖每个管理的 linter 的正常 lint 故障、干净运行、无效配置、格式错误的工具输出和工具崩溃。 ### 代理钩子 渲染或验证仓库本地的代理钩子设置： ``` bin/coding-ethos-run agent-hooks print bin/coding-ethos-run agent-hooks sync bin/coding-ethos-run agent-hooks doctor bin/coding-ethos-run agent-hooks verify ``` 代理钩子生成是全有或全无的。`sync` 写入每个受支持的仓库本地表面： | 提供商 | 原生文件 | 覆盖范围 | | --- | --- | --- | | Claude | `.claude/settings.local.json`、`.mcp.json` | 完整的运行时钩子集加上 MCP stdio 服务器 | | Codex | `.codex/config.toml` | 原生支持的钩子事件加上 MCP stdio 服务器 | | Gemini CLI | `.gemini/settings.json` | 原生支持的钩子事件加上 MCP stdio 服务器 | Codex 为每个支持的事件运行一个原生命令钩子，因此当前的 Codex 会话进入相同的策略运行时，而不依赖于不稳定的工具匹配器名称。生成的 Codex 配置不内联 `PATH=` 更改，为工具钩子安装明确的 shell/edit 匹配器，并保持生命周期钩子无匹配器。在嵌套检出中，只有消费者根是最近仓库根的钩子会强制执行 Codex 事件，从而防止重复的父/嵌套报告。 相同的同步路径还为所有受支持的代理安装了本地 `coding-ethos` MCP 服务器。Claude 接收一个项目 `.mcp.json` 条目，Codex 在 `.codex/config.toml` 中接收一个管理的 `[mcp_servers.coding-ethos]` 块，而 Gemini 在 `.gemini/settings.json` 中接收一个 `mcpServers.coding-ethos` 条目。`doctor` 会与钩子一起检查这些条目，因此 MCP 偏差不是一个单独的隐藏设置步骤。 生成的 ETHOS 技能和原生代理设置使用相同的管理的输出模型。`make build` 刷新检出本地的技能表面、钩子设置和 MCP 设置，并且当 `coding-ethos` 安装在父仓库中时，它会刷新父仓库的 `.agents/skills/`、`.claude/skills/`、`.codex/skills/`、Gemini 扩展技能表面和原生代理 hook/MCP 设置，而无需重写父根代理文档。 `agent-hooks verify` 首先运行 doctor，然后使用提供商原生的 Claude、Codex 和 Gemini 负载调用配置的钩子命令。探测涵盖： - Claude 透明的 Git 包装器重写 - 当重写不可用时，针对原始 Git、绝对 Git 路径、嵌套 shell Git 和 Python 子进程 Git 的 Codex 块 - 针对原始 shell Git 和写入工具策略拒绝的 Gemini 拒绝响应 - 管理的钩子二进制文件篡改： `rm ...coding-ethos-git-hook && go build -o ...coding-ethos-git-hook` `.coding-ethos/hook-runs/` 下的钩子日志包括 stdout、stderr、元数据以及用于代理钩子执行的经过清理的 `event.json`。跟踪记录提供商、事件、工具、cwd、引用的文件、命令预览和哈希、策略 ID、状态和输出形状，而不会转储原始的提供商输入。 ### 切换 在准备仓库以安装主动生成的钩子表面时，请使用切换命令： ``` bin/coding-ethos-run cutover install bin/coding-ethos-run cutover verify ``` `cutover install` 安装仓库本地的 Git 钩子入口点，同步每个受支持的代理钩子表面，并运行就绪验证。`cutover verify` 检查 Git 钩子、代理钩子、所需的运行时忽略和策略运行时验证，然后发出一个简明的 TOON 就绪报告。 ### 篡改和旁路处理 代理 shell 策略拒绝钩子系统侦察和受保护的钩子二进制文件篡改。当被禁止的字符串直接出现在命令中以及出现在命令引用的常规文件中时，它们将被拒绝。 直接尝试在 `coding-ethos/bin/` 下检查、删除、重建、替换、chmod 或写入管理的钩子二进制文件的行为被视为篡改，而不是普通的 lint 故障。被阻止的篡改和 Git 旁路响应以统一的 `CODING-ETHOS EMPLOYMENT VIOLATION` 警告开始，然后是特定于策略的发现，包括明确说明行为者做错了什么以及持续尝试规避可能导致终止的语言。 提供商输出使用每个代理支持的最强原生形状： | 提供商 | 阻止形状 | 上下文/建议形状 | | --- | --- | --- | | Claude | `hookSpecificOutput.permissionDecision = deny` | 完整的 `hookSpecificOutput`，包括 `updatedInput` | | Codex | `decision: "block"` 加上用于 `PreToolUse` 的 `permissionDecision: "deny"`；用于 exit-code-2 stderr 的紧凑 `reason` 文本 | 用于受支持的生命周期/后置工具建议的紧凑原生 `additionalContext`；仅在 Codex 未公开 `additionalContext` 的地方使用紧凑的 `systemMessage` | | Gemini | `decision: "deny"` 加上 `systemMessage` | 在受支持的生命周期钩子上的 `additionalContext` | ### 代理钩子范围 代理钩子路径仅运行确定性的编译评估器：Python 策略检查、结构化数据语法验证、合并冲突检测、私钥检测、PII 清理、特定于仓库的许可证文件头、所需的运行时忽略检查、shebang 检查、大文件限制、行限制和 shell 最佳实践检查。 Python 策略检查使用 Tree-sitter 处理导入和函数式习惯用法表面。条件导入强制执行阻止在写入时引入函数局部导入、`TYPE_CHECKING` 导入分支、模块 `__getattr__` 导入 shim、`__import__` 和 `importlib.import_module`；函数式习惯用法指导标记分配的 lambda 和闭包工厂，并提供 `functools`、`operator` 和 `itertools` 修复建议。 Gemini 审查检查保留在 pre-commit/pre-push 中。代理钩子从不从工具使用路径调用 Gemini 或其他模型。 继续状态存储在配置的钩子继续目录下。 ## 本仓库的管理门控工作 对于直接在 `coding-ethos` 上进行的工作，管理员可以通过在 `/etc/coding-ethos-admin.pids` 中放置一个批准的进程 PID 来授权特定的代理会话。 仅在那种仓库本地、管理员监督的情况下，Git 包装器才会在 Git 子命令之前接受 `--admin-approved`： ``` bin/coding-ethos-run policy-git --admin-approved commit -F /tmp/msg ``` 该标志仅将 `git.staged_admin_files` 从阻止更改为记录。它不会禁用其他策略，并且在本仓库之外无效。 代理绝不能将 `/usr/bin/git` 或任何其他原始 Git 路径用于此工作流。 ## 开发 CLI 保持精简。行为属于专注的模块： | 路径 | 职责 | | --- | --- | | `coding_ethos/loaders.py` | 验证和合并 ethos YAML | | `coding_ethos/renderers.py` | 渲染确定性 Markdown | | `coding_ethos/merging.py` | 管理块注入和外部合并编排 | | `go/internal/toolconfigs/` | 源检出生成的仓库根工具配置和 CI 同步/检查 | | `go/internal/geminiprompts/` | 源检出 Gemini 提示包同步/检查 | | `go/internal/agentskills/` | 源检出提供商技能表面同步/检查 | | `go/internal/hookrunnercli/` | 活动钩子运行时、钩子组和钩子报告 | | `go/internal/managedcapture/` | 管理的 linter/执行捕获 | | `go/diagnostics/` | 用于 lint、格式化工具、类型检查和测试输出的解析器规范化 | | `go/internal/codeintel/` | 仓库本地跟踪、SARIF、AST、向量和修复存储 | | `go/internal/agentproxy/` | 与提供商无关的代理事件信封和转换基础 | | `go/cmd/` | 用于编译的策略、钩子、lint、MCP、代码智能和包装器工具的瘦进程入口点 | 当标志、输出布局、合并行为、覆盖语义或强制执行配置行为发生变化时，请在同一更改中更新此 README、相关的示例 YAML 和测试。 ## 验证 规范的本地验证： ``` make build make check ``` `make build` 是显式的环境变更目标。它刷新生成的配置、管理的工具、钩子入口点、提供商设置、策略包以及当此检出作为子模块安装时的父钩子运行时。 测试和诊断目标不会隐式运行 `build`；如果管理的运行时缺失，它们会快速失败并告诉操作员有意地运行 `make build`。Go 测试通过管理的捕获遵循正常的 Go 工作流：`make go-test` 运行 `go test`，`make go-e2e-test` 使用 `go test` 运行 e2e 包，而 `make check` 使用这些测试目标，而没有单独的编译和运行测试路径。测试绝不能安装工具、重新生成配置、刷新钩子、同步父 artifact 或以其他方式作为隐藏设置改变操作员环境。 针对钩子工作的更广泛验证： ``` make validate make go-test make go-tools-test make go-tools-smoke make pre-commit-all ``` 源代码更改后： | 更改 | 后续操作 | | --- | --- | | `coding_ethos.yml`、`repo_ethos.yml` 或渲染器 | `make generate` | | 生成的工具配置行为 | `make sync-tool-configs` | | Gemini 提示模板或基础 | `make sync-gemini-prompts` | | ETHOS 技能源或渲染器行为 | `make build` | | 钩子运行时或切换行为 | `make cutover-verify` | 有关钩子内部机制，请参见 [pre-commit/PRE-COMMIT.md](pre-commit/PRE-COMMIT.md) 和 [pre-commit/hooks/HOOKS.md](pre-commit/hooks/HOOKS.md)。

标签：AI代码审查, AI安全, AI智能体, CEL策略, Chat Copilot, CI/CD安全, CodeQL, DevSecOps, EVTX分析, GitHub Actions, Git钩子, Llama, MCP服务器, OpenSSF, OSV-Scanner, PyPI, Python, SARIF, 上游代理, 代码安全, 合规性自动化, 安全评估工具, 安全防护栏, 开发安全, 文档安全, 无后门, 日志审计, 漏洞枚举, 策略即代码, 聊天机器人安全, 自动笔记, 逆向工具, 错误基检测, 静态代码分析