简介

coding-ethos 是一个由 Blackcat Informatics® Inc. 开发和维护的开源项目，旨在为代码库生成和强制执行编码标准。该工具通过结构化的原则定义、策略表达和生成的代理文档，确保人类开发者和 AI 编码助手（Codex、Claude Code、 Gemini CLI）遵循一致的编码规范。

项目的主要目标是解决 AI 辅助编程中的标准一致性问题。在没有统一标准的情况下，不同的 AI 模型或同一模型的不同会话可能会产生风格不一致的代码。coding-ethos 通过以下方式解决这一挑战：

• 将编码原则和最佳实践结构化存储在 YAML 配置文件中
• 自动生成针对特定 AI 代理的文档（AGENTS.md、CLAUDE.md、GEMINI.md）
• 提供策略执行机制（CEL 表达式、lint 规则、pre-commit hooks）
• 支持 SARIF 格式的代码扫描结果输出

资料来源：README.md

核心概念

Ethos Bundle（准则包）

Ethos Bundle 是项目的核心数据结构，包含以下组件：

资料来源：coding_ethos/models.py:114-121

Principle（原则）

每个 Principle 代表一条编码原则，具有以下属性：

@dataclass(slots=True)
class Principle:
    id: str                    # 唯一标识符
    order: int                 # 排序顺序
    title: str                 # 标题
    summary: str               # 摘要
    body: str                  # 详细内容
    sections: list[PrincipleSection]  # 章节列表
    axioms: list[PrincipleAxiom]      # 公理
    directive: str            # 核心指令
    quick_ref: list[str]       # 快速参考
    merge_topics: list[str]    # 合并主题
    tags: list[str]            # 标签
    related: list[str]         # 相关原则
    agent_hints: dict[str, str]       # 代理提示

资料来源：coding_ethos/models.py:54-66

Section Kind（章节类型）

原则的详细内容支持多种章节类型，便于组织不同用途的信息：

资料来源：coding_ethos/markdown_seed.py:40-56

架构概览

graph TD
    A[用户/AI代理] --> B[CLI / MCP Server]
    B --> C[Loaders]
    C --> D[EthosBundle]
    D --> E[Renderers]
    E --> F[AGENTS.md<br/>CLAUDE.md<br/>GEMINI.md<br/>ETHOS.md]
    
    D --> G[Policy Engine]
    G --> H[Pre-commit Hooks]
    G --> I[SARIF Output]
    
    J[repo_ethos.yml] --> C
    K[coding_ethos.yml] --> C
    L[Markdown Seed] --> C
    
    M[CEL Expressions] --> G
    N[Tool Config] --> G

支持的 AI 代理

coding-ethos 当前支持三种主流 AI 编码代理：

每个代理的根文件表面（AgentRootSurface）定义了其特有的渲染逻辑和合并主题：

资料来源：coding_ethos/renderers.py:145-178

包结构

coding_ethos/
├── __init__.py          # 公共 API 导出
├── cli.py               # 命令行入口
├── loaders.py           # 加载和合并 ethos bundle
├── renderers.py         # 渲染代理文档
├── merging.py           # 合并引擎支持
├── models.py            # 数据模型定义
├── markdown_seed.py     # Markdown 转 YAML 工具
├── yaml_utils.py        # YAML 工具函数
├── presets.py           # 预设配置
├── resources.py         # 资源路径管理
└── resources/           # 打包后的资源文件

公共 API

项目的公共 API 通过 coding_ethos/__init__.py 导出：

from coding_ethos import (
    load_primary_bundle,    # 加载主 bundle
    merge_repo_ethos,      # 合并仓库 ethos
    render_agent_root_outputs,  # 渲染代理根文件
    parse_ethos_markdown,   # 解析 ethos markdown
    seed_primary_from_markdown, # 从 markdown 播种
    SUPPORTED_MERGE_ENGINES,    # 支持的合并引擎
    resolve_merge_bin,      # 解析合并二进制
)

资料来源：coding_ethos/__init__.py:18-40

配置系统

主配置文件 (coding_ethos.yml)

主配置文件定义了跨仓库共享的编码原则和策略：

仓库配置 (repo_ethos.yml)

repo_ethos.yml 用于覆盖或扩展主配置，添加仓库特定的设置：

repo:
  name: Example Service
  overview: 背景处理服务
  commands:
    install: [uv sync]
    test: [uv run pytest]
  paths:
    source: src/
    tests: tests/

principles:
  overrides:
    protocol-first-design:
      directive: 在实现工作前先在 src/interfaces/ 定义接口
  additional:
    - id: migration-hygiene
      order: 900
      title: 迁移卫生
      summary: 迁移是追加的，像代码一样审查

资料来源：repo_ethos.example.yml

合并策略

合并过程支持多种策略模式：

工作流程

生成工作流

graph LR
    A[coding_ethos.yml] --> B[load_primary_bundle]
    C[repo_ethos.yml] --> D[merge_repo_ethos]
    B --> D
    D --> E[EthosBundle]
    E --> F[render_agent_root_outputs]
    F --> G[AGENTS.md]
    F --> H[CLAUDE.md]
    F --> I[GEMINI.md]

生成命令：

uv run python main.py --repo .

资料来源：repo_ethos.yml

策略执行工作流

graph TD
    A[AI 代理执行操作] --> B{Pre-commit Hook 检查}
    B -->|通过| C[操作执行]
    B -->|失败| D[策略阻止]
    D --> E[MCP lint_advice]
    E --> F[获取修复建议]
    F --> G[应用修复]
    G --> B

策略表达

CEL 表达式

coding-ethos 支持 Common Expression Language (CEL) 进行策略表达：

policies:
  expressions:
    - id: filesystem.generated_artifact_edit
      scope: file
      severity: block
      mode: block
      skill_id: agent-operating-discipline
      lint_scopes:
        - staged
      tools:
        - Write
        - Edit
        - MultiEdit
      message: 生成的文件必须通过源输入修改
      advice: >-
        编辑 coding_ethos.yml、repo_ethos.yml 或渲染器代码，
        然后重新生成并审查差异。

该策略禁止直接编辑 AGENTS.md、CLAUDE.md、GEMINI.md 等生成文件，强制用户通过源配置进行修改。

资料来源：repo_ethos.yml

策略阻止的工具

MCP 服务器集成

coding-ethos 提供 MCP (Model Context Protocol) 服务器，为 AI 代理提供上下文：

启动 MCP 服务器：

make build
bin/coding-ethos-run mcp

资料来源：examples/mcp-lint-advice/README.md

工具配置

coding-ethos 支持多种 lint 工具配置，包括：

示例工具配置：

tool_config:
  golangci_lint:
    linters:
      enable:
        - name: ginkgolinter
          rationale: 此仓库的 Go 测试套件使用 Ginkgo 标准

资料来源：repo_ethos.example.yml

SARIF 集成

coding-ethos 支持 SARIF (Static Analysis Results Interchange Format) 输出，用于代码扫描结果集成：

graph LR
    A[Lint 检查] --> B[SARIF 生成]
    B --> C[GitHub Code Scanning]
    B --> D[Artifact 上传]
    C --> E[发现展示]
    E --> F[代理修复流程]
    F --> A

CI 配置示例参考 ci/gitlab/coding-ethos-sarif.yml：

资料来源：ci/gitlab/coding-ethos-sarif.yml

快速开始

环境要求

安装

git clone https://github.com/paudley/coding-ethos.git
cd coding-ethos
make install
make doctor

生成文档

uv run python main.py --repo .

运行测试

uv run pytest

资料来源：CONTRIBUTING.md

版本信息

当前版本：0.2.1

资料来源：coding_ethos/__init__.py:45

前提条件

在开始之前，请确保本地环境满足以下要求：

资料来源：CONTRIBUTING.md:55-58

本地环境配置

克隆仓库

git clone https://github.com/paudley/coding-ethos.git
cd coding-ethos

安装依赖

项目使用 uv 进行依赖管理和虚拟环境管理：

make install

此命令将：

• 创建或激活 Python 虚拟环境
• 安装项目依赖
• 安装开发组依赖

资料来源：CONTRIBUTING.md:59-65

环境诊断

安装完成后，运行健康检查以验证环境配置：

make doctor

该命令检查：

• Python 版本是否满足要求
• 依赖包是否完整安装
• 必要的系统工具是否可用

查看可用命令

make help

显示所有可用的 Makefile 目标和快捷命令。

核心工作流程

生成与渲染流程

coding-ethos 的核心功能是将声明式的 coding_ethos.yml 和 repo_ethos.yml 配置转换为各代理平台可读的根文档文件。

graph TD
    A[coding_ethos.yml] -->|加载| B[EthosBundle]
    C[repo_ethos.yml] -->|合并| B
    B --> D{渲染器}
    D --> E[AGENTS.md]
    D --> F[CLAUDE.md]
    D --> G[GEMINI.md]
    D --> H[ETHOS.md]

资料来源：coding_ethos/__init__.py:10-25

仓库输出再生

当需要重新生成代理根文档时：

uv run python main.py --repo .

生成后，运行测试套件验证输出：

uv run pytest

资料来源：repo_ethos.yml:95-98

CLI 入口点

项目提供统一的命令行接口：

# 通用入口
python main.py [命令]

# 或通过包安装
coding-ethos [命令]

支持的命令模块包括：

资料来源：coding_ethos/__init__.py:11

MCP 服务器快速使用

启动 MCP 服务器

make build
bin/coding-ethos-run mcp

服务器启动后，代理可通过 MCP 协议访问 lint 和策略上下文。

核心 MCP 工具

资料来源：examples/mcp-lint-advice/README.md:35-48

代理提示模式

使用以下提示模式将 lint 修复工作委托给代理：

Use the coding-ethos MCP server before running any raw linter command.
Call lint_check for the relevant scope, then use lint_advice or
sarif_remediation_advice for each actionable diagnostic.

资料来源：examples/mcp-lint-advice/README.md:56-60

CI SARIF 集成

GitHub Actions 工作流

启用 GitHub Actions SARIF 生成：

generated_config:
  ci:
    github_actions:
      enabled: true

生成的 SARIF 工作流应：

• 运行编译的 coding-ethos 策略 lint 路径
• 即使策略违规也要写入 SARIF
• 上传到 GitHub 代码扫描
• 在配置时上传调试工件
• 上传后如果存在阻止性发现则失败作业

资料来源：examples/github-sarif-ci/README.md:13-32

代理修复工作流

当 CI 报告 coding-ethos SARIF 发现时：

1. 检查 SARIF/代码扫描发现
2. 使用 MCP sarif_remediation_advice 获取 ETHOS 修复上下文
3. 修复结构性问题
4. 重新运行本地托管检查
5. 仅在本地证据干净后推送

资料来源：examples/github-sarif-ci/README.md:34-43

生成产物概览

根文档文件

生成的工件约定

生成的工件必须通过源输入更改，不能直接编辑：

• AGENTS.md
• CLAUDE.md
• GEMINI.md
• ETHOS.md
• .claude/ethos/MEMORY.md
• .agents/ethos/*
• .agent-context/prompt-addons/*

编辑 coding_ethos.yml、repo_ethos.yml 或渲染器代码，然后重新生成并审查差异。

资料来源：repo_ethos.yml:1-10

验证清单

完成快速开始后，确认以下项目正常工作：

• [ ] make install 成功完成
• [ ] make doctor 无错误
• [ ] uv run python main.py --repo . 生成根文档
• [ ] uv run pytest 所有测试通过
• [ ] MCP 服务器可启动（bin/coding-ethos-run mcp）

下一步

• 阅读 CODING_ETHOS.md 了解包级工作流
• 查看 CONTRIBUTING.md 了解贡献指南
• 参考 MCP_SERVER.md 深入 MCP 集成
• 探索 examples/ 目录中的实际使用场景

概述

coding-ethos 是一个用于生成和执行编码规范（ETHOS）的开源工具项目。该系统采用多语言架构，核心逻辑使用 Python 实现，而生成的 enforcement 工具配置、CI 集成、提示词包等则由 Go 语言组件处理。

系统的核心职责包括：

• 从 YAML 配置加载规范数据
• 将结构化数据渲染为 AI Agent 可读的 Markdown 文档
• 管理 pre-commit 钩子和策略执行
• 生成 SARIF 格式的扫描结果
• 提供 MCP 服务器接口供 AI Agent 调用

资料来源：coding_ethos/CODING_ETHOS.md:1-15

整体架构图

graph TB
    subgraph "前端层"
        CLI[CLI 入口<br/>bin/coding-ethos-run]
        MCP[MCP 服务器]
    end
    
    subgraph "Python 核心包 coding_ethos"
        CLI_PY[cli.py<br/>命令行解析]
        LOADER[loaders.py<br/>YAML 加载与验证]
        MODEL[models.py<br/>数据模型定义]
        RENDER[renderers.py<br/>Markdown 渲染]
        MERGE[merging.py<br/>合并策略]
        MARKDOWN[markdown_seed.py<br/>Markdown 解析]
        YAML_UTIL[yaml_utils.py<br/>YAML 工具]
    end
    
    subgraph "Go 组件 go/internal"
        HOOK[hookrunnercli<br/>钩子运行器]
        POLICY[policy<br/>策略引擎]
        SARIF[SARIF 生成器]
        CONFIG[配置生成器]
    end
    
    subgraph "输出产物"
        AGENTS[AGENTS.md<br/>CLAUDE.md<br/>GEMINI.md]
        HOOKS[pre-commit hooks]
        SARIF_OUT[SARIF 文件]
    end
    
    CLI --> CLI_PY
    MCP --> CLI_PY
    CLI_PY --> LOADER
    LOADER --> MODEL
    CLI_PY --> RENDER
    CLI_PY --> MERGE
    CLI_PY --> MARKDOWN
    CLI_PY --> YAML_UTIL
    CLI_PY --> HOOK
    HOOK --> POLICY
    POLICY --> SARIF
    POLICY --> HOOKS
    RENDER --> AGENTS
    MODEL --> AGENTS

模块边界与职责

Python 包结构

coding_ethos/ 目录包含 Python 包的核心逻辑，采用清晰的模块边界设计：

资料来源：coding_ethos/CODING_ETHOS.md:28-42

公共 API 导出

Python 包通过 coding_ethos/__init__.py 导出以下公开接口：

__all__ = [
    "SUPPORTED_MERGE_ENGINES",
    "UnsupportedMergeEngineError",
    "__version__",
    "format_yaml_file",
    "load_primary_bundle",
    "main",
    "merge_repo_ethos",
    "parse_ethos_markdown",
    "render_agent_root_outputs",
    "render_yaml",
    "required_root_imports",
    "resolve_merge_bin",
    "root_merge_topics",
    "seed_primary_from_markdown",
]

资料来源：coding_ethos/__init__.py:31-44

数据模型

核心数据结构

models.py 定义了系统内部使用的数据模型，采用 dataclass 和 slots 模式优化内存使用：

classDiagram
    class EthosBundle {
        +str title
        +str overview
        +list~Principle~ principles
        +dict~str, AgentProfile~ agent_profiles
        +list~EthosSkill~ skills
        +RepoContext repo
        +str source_markdown
    }
    
    class Principle {
        +str id
        +int order
        +str title
        +str summary
        +str body
        +list~PrincipleSection~ sections
        +list~PrincipleAxiom~ axioms
        +str directive
        +list~str~ quick_ref
        +list~str~ merge_topics
        +list~str~ tags
        +list~str~ related
        +dict~str, str~ agent_hints
    }
    
    class PrincipleSection {
        +str id
        +str title
        +str summary
        +str body
        +str kind
    }
    
    class AgentProfile {
        +str name
        +str root_file
        +list~str~ supporting_files
        +list~str~ notes
    }
    
    class EthosSkill {
        +str id
        +str title
        +str description
        +list~str~ principle_ids
        +list~str~ trigger_terms
        +str short_hint
        +str focus
        +list~str~ remediation_steps
    }
    
    class RepoContext {
        +str name
        +str overview
        +dict~str, list~str~~ commands
        +dict~str, str~ paths
        +list~str~ notes
        +dict~str, list~str~~ agent_notes
    }
    
    EthosBundle *-- Principle
    EthosBundle *-- AgentProfile
    EthosBundle *-- EthosSkill
    EthosBundle *-- RepoContext
    Principle *-- PrincipleSection
    Principle *-- PrincipleAxiom

资料来源：coding_ethos/models.py:1-95

支持的类型常量

支持的 Section 类型包括：overview、guidance、rule、policy、workflow、anti_patterns、correct_way、rationale、examples、reference、repo_context

资料来源：coding_ethos/models.py:15-25

渲染器架构

Agent 根文件表面

renderers.py 定义了支持的 Agent 根文件表面：

_AGENT_ROOT_SURFACES: tuple[AgentRootSurface, ...] = (
    AgentRootSurface(
        agent="codex",
        path="AGENTS.md",
        render_root=render_agents_md,
        render_addendum=render_agents_addendum,
        merge_topics=("repo commands", "key paths", "repo operating notes"),
    ),
    AgentRootSurface(
        agent="claude",
        path="CLAUDE.md",
        render_root=_render_claude_root,
        render_addendum=render_claude_addendum,
        imports=("@AGENTS.md", "@.claude/ethos/MEMORY.md"),
        merge_topics=(
            "Claude imports",
            "memory links",
            "Claude-specific workflow notes",
        ),
    ),
    AgentRootSurface(
        agent="gemini",
        path="GEMINI.md",
        render_root=render_gemini_md,
        render_addendum=render_gemini_addendum,
        imports=("@AGENTS.md",),
        merge_topics=(
            "Gemini root guidance",
            "linked detail docs",
            "repo operating notes",
        ),
    ),
)

资料来源：coding_ethos/renderers.py:1-50

渲染工作流

graph LR
    A[YAML 配置<br/>coding_ethos.yml] --> B[loaders.py<br/>加载与验证]
    C[repo_ethos.yml<br/>仓库覆盖] --> B
    B --> D[models.py<br/>标准化数据]
    D --> E[renderers.py<br/>渲染]
    E --> F[AGENTS.md]
    E --> G[CLAUDE.md]
    E --> G[GEMINI.md]
    E --> H[ETHOS.md]
    E --> I[.claude/ethos/MEMORY.md]

资源路径管理

打包资源路径解析

resources.py 模块处理打包后的资源路径查找：

def resource_path(*parts: str) -> Path:
    """返回源码或打包的 coding-ethos 资源的文件系统路径。"""
    source_root = Path(__file__).resolve().parent.parent
    source_candidates: dict[tuple[str, ...], Path] = {
        ("coding_ethos.yml",): source_root / "coding_ethos.yml",
        ("config.yaml",): source_root / "config.yaml",
        ("repo_config.example.yaml",): source_root / "repo_config.example.yaml",
        ("repo_ethos.example.yml",): source_root / "repo_ethos.example.yml",
    }
    source_path = source_candidates.get(parts)
    if source_path is not None and source_path.exists():
        return source_path
    return Path(__file__).resolve().parent.joinpath("resources", *parts)

该设计支持两种场景：

1. 源码检出的开发环境：直接从仓库根目录读取配置文件
2. PyPI 安装的包环境：从 coding_ethos/resources/ 子目录读取打包资源

Markdown 种子解析

解析流程

markdown_seed.py 实现了从 Markdown 规范文档到结构化 YAML 的转换：

graph TD
    A[Markdown 规范文档] --> B[SECTION_RE<br/>匹配 H2 标题<br/>^## \*\*(\d+)\.\s*(.+?)\*\*$]
    A --> C[SUBSECTION_RE<br/>匹配 H3 标题<br/>^###\s+(?:\*\*)?(.+?)(?:\*\*)?\s*$]
    B --> D[_split_sections<br/>分割章节]
    C --> D
    D --> E[_infer_section_kind<br/>推断章节类型]
    E --> F[Section Kind Markers<br/>关键词匹配]
    F --> G[PrincipleSection<br/>列表]
    A --> H[summarize_markdown<br/>提取摘要]
    H --> I[Principle.summary]

章节类型推断

系统通过关键词匹配自动推断章节类型：

资料来源：coding_ethos/markdown_seed.py:30-55

CLI 入口点

命令行入口架构

项目提供多层 CLI 入口：

graph TD
    A[用户命令] --> B{入口类型}
    B -->|bin/coding-ethos-run| C[Go CLI]
    B -->|python main.py| D[Python CLI]
    C --> E[hookrunnercli<br/>钩子运行]
    C --> F[policy<br/>策略检查]
    C --> G[mcp<br/>MCP 服务器]
    D --> H[cli.main<br/>主函数]
    H --> I[loaders.py<br/>加载配置]
    H --> J[renderers.py<br/>渲染输出]
    H --> K[merging.py<br/>合并文件]

main.py 是一个轻量级封装，直接调用包的公共 API：

from coding_ethos import main

if __name__ == "__main__":
    raise SystemExit(main())

资料来源：main.py:1-20

版本信息

资料来源：coding_ethos/__init__.py:47, pre-commit/hooks/coding_ethos_hooks/__init__.py:18

开发规则

根据项目架构设计原则：

1. cli.py 应仅作为编排层，不包含业务逻辑
2. 验证逻辑 应放在 loaders.py
3. 输出格式化 应放在 renderers.py
4. 合并行为 应放在 merging.py
5. 生成的 enforcement 产物 应放在 Go 包 go/internal/ 下

当更改影响标志、输出布局、覆盖行为、生成配置内容、技能表面或提示包内容时，应在同一更改中更新 README 指导和相关测试。

资料来源：coding_ethos/CODING_ETHOS.md:44-52

组件架构总览

coding-ethos 的核心组件可分为四个层次：

graph TD
    A["源文档层<br/>(Markdown/YAML)"] --> B["加载与解析层"]
    B --> C["数据模型层"]
    C --> D["渲染与输出层"]
    D --> E["AGENTS.md<br/>CLAUDE.md<br/>GEMINI.md<br/>ETHOS.md"]
    
    F["预设数据层<br/>(presets.py)"] --> B
    F --> C
    
    G["资源路径层<br/>(resources.py)"] -.-> A

资料来源：coding_ethos/__init__.py:1-47

数据模型层

数据模型层定义了项目内部的核心数据结构，所有组件共享统一的类型定义。

EthosBundle

EthosBundle 是整个系统的核心数据结构，代表一个完整的规范化 ethos 载荷：

资料来源：coding_ethos/models.py:108-119

Principle（原则）

Principle 表示单个规范化 ethos 原则：

@dataclass(slots=True)
class Principle:
    id: str
    order: int
    title: str
    summary: str
    body: str
    sections: list[PrincipleSection] = field(default_factory=_empty_sections)
    axioms: list[PrincipleAxiom] = field(default_factory=_empty_axioms)
    directive: str = ""
    quick_ref: list[str] = field(default_factory=_empty_str_list)
    merge_topics: list[str] = field(default_factory=_empty_str_list)
    tags: list[str] = field(default_factory=_empty_str_list)
    related: list[str] = field(default_factory=_empty_str_list)
    agent_hints: dict[str, str] = field(default_factory=_empty_str_map)

资料来源：coding_ethos/models.py:53-68

AgentProfile（Agent 配置文件）

AgentProfile 定义 Agent 特定的根文件和备注配置：

资料来源：coding_ethos/models.py:71-76

EthosSkill（Ethos 技能）

EthosSkill 表示从 ETHOS 原则生成的 Agent 技能：

资料来源：coding_ethos/models.py:90-100

支持的 Section 类型

系统定义了以下标准化的 section 类型：

资料来源：coding_ethos/models.py:20-31

加载与解析层

加载与解析层负责从各种格式的源文档中提取和构建数据模型。

Markdown 种子模块

markdown_seed.py 提供了将 Markdown ethos 文档转换为结构化 YAML 数据的辅助函数：

资料来源：coding_ethos/markdown_seed.py:1-100

Section 推断逻辑

模块使用正则表达式推断 section 的类型：

graph LR
    A["Markdown 标题"] --> B{SECTION_RE 匹配<br/>## **序号. 标题**}
    B --> C{SUBSECTION_RE 匹配<br/>### 标题}
    C --> D{关键词匹配}
    D -->|含 'why'/'rationale'| E["rationale"]
    D -->|含 'anti pattern'| F["anti_patterns"]
    D -->|含 'rule'/'policy'| G["rule/policy"]
    D -->|含 'example'| H["examples"]
    D -->|其他| I["guidance"]

资料来源：coding_ethos/markdown_seed.py:35-70

Section 关键词标记

资料来源：coding_ethos/markdown_seed.py:36-66

渲染层

渲染层负责将 EthosBundle 数据模型转换为各种 AI Agent 可读的根文件格式。

Agent 根表面定义

系统支持三种 AI Agent 的根文件表面：

资料来源：coding_ethos/renderers.py:80-105

AgentRootSurface 结构

@dataclass(slots=True)
class AgentRootSurface:
    agent: str
    path: str
    render_root: Callable[[EthosBundle, Path], str]
    render_addendum: Callable[[EthosBundle, Path], str]
    imports: tuple[str, ...] = ()
    merge_topics: tuple[str, ...] = ()

资料来源：coding_ethos/renderers.py:50-57

渲染器工作流程

graph TD
    A["EthosBundle"] --> B["render_agent_root_outputs()"]
    B --> C["遍历 _AGENT_ROOT_SURFACES"]
    C --> D["调用 surface.render_root()"]
    D --> E["生成 AGENTS.md"]
    D --> F["生成 CLAUDE.md"]
    D --> G["生成 GEMINI.md"]
    E --> H["dict[str, str]<br/>{path: content}"]
    F --> H
    G --> H

资料来源：coding_ethos/renderers.py:110-125

根合并主题

每个 Agent 表面定义了特定的合并主题：

资料来源：coding_ethos/renderers.py:81-104

预设数据层

presets.py 提供了共享的预设元数据和辅助构建器，保持 seeded 或手写 YAML 的紧凑性和一致性。

PRINCIPLE_PRESETS

预设数据包含以下核心原则的配置：

资料来源：coding_ethos/presets.py:20-90

辅助构建器函数

资料来源：coding_ethos/presets.py:1-15

资源路径层

resources.py 集中管理资源文件路径查找，支持源代码检出和打包安装两种场景。

resource_path() 函数

def resource_path(*parts: str) -> Path:
    source_root = Path(__file__).resolve().parent.parent
    source_candidates: dict[tuple[str, ...], Path] = {
        ("coding_ethos.yml",): source_root / "coding_ethos.yml",
        ("config.yaml",): source_root / "config.yaml",
        ("repo_config.example.yaml",): source_root / "repo_config.example.yaml",
        ("repo_ethos.example.yml",): source_root / "repo_ethos.example.yml",
    }
    source_path = source_candidates.get(parts)
    if source_path is not None and source_path.exists():
        return source_path
    return Path(__file__).resolve().parent.joinpath("resources", *parts)

资料来源：coding_ethos/resources.py:17-30

路径解析逻辑

graph TD
    A["resource_path() 调用"] --> B{"源码检出模式？"}
    B -->|是<br/>source_candidates 匹配| C["返回源码根目录路径"]
    B -->|否| D["返回打包资源路径<br/>coding_ethos/resources/*"]

资料来源：coding_ethos/resources.py:1-30

公共 API 导出

coding_ethos/__init__.py 导出以下公共接口：

资料来源：coding_ethos/__init__.py:20-45

版本信息

资料来源：coding_ethos/__init__.py:47

组件交互关系

graph LR
    A["coding_ethos.yml<br/>repo_ethos.yml"] --> B["loaders<br/>load_primary_bundle()"]
    C["Markdown ethos"] --> D["markdown_seed<br/>parse_ethos_markdown()"]
    B --> E["models<br/>EthosBundle"]
    D --> E
    F["presets<br/>PRINCIPLE_PRESETS"] --> E
    E --> G["renderers<br/>render_agent_root_outputs()"]
    G --> H["AGENTS.md"]
    G --> I["CLAUDE.md"]
    G --> J["GEMINI.md"]
    E --> K["merging<br/>merge_repo_ethos()"]
    K --> L["合并配置输出"]
    E --> M["yaml_utils<br/>render_yaml()"]
    M --> N["YAML 格式化输出"]

支持的 AI Agent

系统当前支持以下 AI Agent：

资料来源：coding_ethos/models.py:12

总结

coding-ethos 的核心组件体系采用分层架构设计：

1. 数据模型层 (models.py) 定义了 EthosBundle、Principle、AgentProfile 等核心类型，所有组件共享统一的类型定义

1. 加载与解析层 (markdown_seed.py) 负责从 Markdown 源文档提取和构建数据模型，使用正则表达式推断 section 类型

1. 渲染层 (renderers.py) 将数据模型转换为 AI Agent 可读的根文件，支持 Codex、Claude 和 Gemini 三种 Agent

1. 预设数据层 (presets.py) 提供预设元数据，保持配置的一致性和紧凑性

1. 资源路径层 (resources.py) 统一管理源码和打包场景下的资源文件查找

策略引擎（Policy Engine）是 coding-ethos 项目的核心子系统，负责将抽象的编码规范（ETHOS）转化为可执行的策略规则，并通过 hooks、lint、SARIF 等渠道实施强制执行。策略引擎连接了声明式的规范定义与运行时策略评估，是实现 "ethos is the policy source, config is the enforcement projection" 这一核心理念的关键组件。

设计目标与核心职责

策略引擎的设计目标是在代码工作流的所有关键节点（编辑前、提交前、CI 运行时）建立统一的策略评估层。它需要满足以下几个核心需求：

单一事实来源原则：策略规则必须与其所属的 ETHOS 原则保持紧密关联。每个策略规则都应能追溯到具体的原则 ID，而非独立存在于配置文件中。资料来源：POLICY_COMPILER.md

证据映射机制：策略引擎不仅仅是执行规则，还要理解外部工具（如 linter）的输出如何映射到 ETHOS 问题。linter 代码本身并不自动构成 ETHOS 违规——需要手动审查和归类后才能建立映射关系。资料来源：POLICY_COMPILER.md

多运行时分发：编译后的策略包需要被多个运行时消费，包括 Go git hooks、Python MCP 服务器、预提交钩子、以及生成式 AI 代理的提示包。资料来源：POLICY_COMPILER.md

策略数据模型

策略引擎的核心数据模型定义在 coding_ethos/models.py 中。该文件使用 Python dataclass 定义了层次化的数据结构，从原则到具体规则形成完整的语义图。

原则（Principle）

原则是 ETHOS 规范的基本单元，包含以下关键属性：

资料来源：coding_ethos/models.py:56-77

原则章节类型

原则的详细内容通过章节（Section）组织，支持的章节类型定义如下：

资料来源：coding_ethos/models.py:19-38

策略表达式（CEL Policy）

策略规则通过 CEL（Common Expression Language）表达式定义。CEL 提供了声明式的条件评估能力，适合表达文件系统操作、工具调用等策略约束。

policies:
  expressions:
    - id: filesystem.large_files.no_growth
      description: 大源文件禁止继续增长
      event: PreToolUse
      severity: block
      expression: |
        proposed_file_change.is_source
        && proposed_file_change.current_line_count >= 800
        && proposed_file_change.new_line_count > proposed_file_change.current_line_count

CEL 表达式中可用的上下文变量包括：

• event.tool：当前工具名称（如 Write、Edit、MultiEdit）
• proposed_file_change.*：提议的文件变更详情
• file_changes.exists(...)：检查已变更文件列表
• list_contains(...)：列表包含检查
• paths.exists(...)：路径存在性检查
• any_glob_match(...)：glob 模式匹配

资料来源：examples/cel-policy/README.md

ETHOS Bundle

EthosBundle 是完整的策略包数据结构，包含项目所有原则、技能、代理配置和仓库上下文：

@dataclass(slots=True)
class EthosBundle:
    title: str                          # 包标题
    overview: str                      # 概述
    principles: list[Principle]        # 原则列表
    agent_profiles: dict[str, AgentProfile]  # 代理配置
    skills: list[EthosSkill]           # 技能定义
    repo: RepoContext                  # 仓库上下文
    source_markdown: str = ""          # 原始 Markdown

资料来源：coding_ethos/models.py:105-117

策略编译流程

策略编译是将声明式 ETHOS 规范转换为可执行策略包的过程。根据 POLICY_COMPILER.md 的规划，这一流程包含多个阶段。

编译输入

策略编译器接受两类输入源：

语义策略源：

• coding_ethos.yml：主规范文件，定义团队的核心编码原则
• repo_ethos.yml：仓库级规范，定义特定项目的原则覆盖和追加

执行配置源：

• config.yaml：主配置文件，定义工具链、钩子设置
• repo_config.yaml：仓库级配置

资料来源：POLICY_COMPILER.md

编译输出

编译后的策略包采用 JSON 格式存储于 .git/coding-ethos-hooks/policy/policy-bundle.json。JSON 格式的选择是因为它易于被 Go、Python、Node.js 和 shell 脚本等多种语言消费。

{
  "version": 1,
  "bundle_id": "example-policy-2026-04-24",
  "generated_at": "2026-04-24T12:00:00Z",
  "sources": {
    "ethos": {
      "primary": "coding_ethos.yml",
      "repo": "repo_ethos.yml"
    },
    "enforcement": {
      "primary": "config.yaml",
      "repo": "repo_config.yaml"
    }
  },
  "principles": {},
  "policies": {},
  "dispatch": {}
}

资料来源：POLICY_COMPILER.md

编译架构

graph TD
    subgraph 编译输入
        A[coding_ethos.yml]
        B[repo_ethos.yml]
        C[config.yaml]
        D[repo_config.yaml]
    end
    
    subgraph 编译过程
        E[策略编译器]
        E --> F[语义策略图构建]
        E --> G[运行时分发索引]
    end
    
    subgraph 编译产物
        H[policy-bundle.json]
        I[policy-summary.md]
        J[policy-bundle.trig]
    end
    
    subgraph 运行时消费者
        K[Go Git Hooks]
        L[Python MCP Server]
        M[Pre-commit Hooks]
        N[Agent Prompt Packs]
    end
    
    A --> E
    B --> E
    C --> E
    D --> E
    H --> K
    H --> L
    H --> M
    H --> N
    J --> O[RDF查询工具]

编译产物分发到多个运行时组件，每个组件负责特定场景的策略评估。

证据映射机制

策略引擎的一个关键设计是证据映射（Evidence Mapping）。这一机制建立了外部工具输出与 ETHOS 策略之间的关联。

证据映射工作流

graph LR
    A[Linter 输出] --> B[追踪文件存储]
    B --> C[归一化处理]
    C --> D[定期审查]
    D --> E{是否重复出现?}
    E -->|是| F[建立证据映射]
    E -->|否| G[常规工具诊断]
    F --> H[策略包更新]
    G --> I[显示工具原始输出]
    H --> J[策略违规报告]

原始 linter 追踪存储在 .coding-ethos/ 目录下，经过归一化处理后定期审查。审查通过的标准 linter 代码会被归类为策略证据，并在策略包中建立映射关系。

资料来源：POLICY_COMPILER.md

证据映射示例

principles:
  - id: keep-files-focused
    title: 保持文件专注
    policies:
      expressions:
        - id: filesystem.large_files.no_growth
          skill_id: file-focus-discipline
          lint_scopes:
            - staged

每个策略表达式都可以关联到具体的技能 ID（skill_id），用于在 MCP 服务器中提供修复建议。

策略评估

评估上下文

策略评估发生在特定的事件上下文中。以下是主要的评估事件类型：

评估结果

策略评估的结果包含以下关键信息：

• severity：违规严重程度（block、warn、info）
• skill_id：关联的修复技能 ID
• message：面向用户的消息
• advice：修复建议

- id: filesystem.generated_artifact_edit
  severity: block
  skill_id: agent-operating-discipline
  message: 生成的文件必须通过源输入修改
  advice: >-
    编辑 coding_ethos.yml、repo_ethos.yml 或渲染器代码，
    然后重新生成并审查差异。

资料来源：repo_ethos.yml

运行时分发

策略包被设计为分发到多个运行时环境，每个环境使用编译后的 JSON 包执行评估。

Go Git Hooks

Go 实现的 git hooks 是主要的策略执行点。hooks 在关键 Git 操作点（pre-commit、pre-push 等）注入策略评估逻辑。

Python MCP 服务器

Python MCP 服务器提供工具调用接口，允许 AI 代理通过 MCP 协议查询策略信息：

• lint_check：运行托管的 lint 捕获或编译的策略 lint
• lint_advice：将诊断映射到 ETHOS 策略和技能指导
• sarif_remediation_advice：将 SARIF 证据转换为聚焦的修复建议
• sarif_risk_summary：汇总严重程度、文件、工具、策略和技能

资料来源：examples/mcp-lint-advice/README.md

预提交钩子

预提交钩子通过 pre-commit 框架集成，在代码提交前执行静态检查。

策略与原则的关联

策略引擎的一个核心设计原则是保持策略与原则的强关联。每个策略规则都必须归属于一个原则，并通过原则 ID 建立联系。

关联结构

Principle (keep-files-focused)
├── directive: "拆分大文件而非继续增长"
├── axioms:
│   └── "大文件隐藏多个变更原因"
├── policies:
│   └── expressions:
│       └── id: filesystem.large_files.no_growth
└── sections:
    ├── overview (概述)
    ├── rationale (理由)
    └── examples (示例)

原则继承与覆盖

仓库级规范可以通过 repo_ethos.yml 覆盖和追加主规范的策略：

principles:
  overrides:
    protocol-first-design:
      directive: 在 src/interfaces/ 中定义接口
      quick_ref:
        - 接口工作从 src/interfaces/ 开始
  additional:
    - id: migration-hygiene
      order: 900
      title: 迁移卫生

资料来源：repo_ethos.example.yml

错误处理与降级

策略引擎在遇到错误时采用渐进式降级策略：

1. 策略解析错误：记录错误但允许操作继续，同时报告违规
2. 评估超时：跳过评估并记录性能问题
3. 沙箱模式不可用：在 required 模式下阻止操作，在 optional 模式下仅警告

相关文档

• CEL 策略示例
• MCP 服务器集成
• 策略编译器设计
• 预提交钩子

概述

CEL策略表达式（CEL Policy Expressions）是coding-ethos项目中用于定义可执行策略谓词的核心机制。CEL（Common Expression Language）是一种表达力强、安全性高的策略描述语言，coding-ethos将其集成到ETHOS原则的策略层，实现代码规范的可执行化。

CEL策略表达式的设计目标是将抽象的编码原则转化为具体的、可被系统强制执行的规则。通过将策略表达式附加到ETHOS原则，开发者可以在单一源头定义规则的意图、上下文和执行逻辑，由系统自动调度至钩子（hooks）、lint检查、MCP服务和SARIF报告等各个执行路径。

资料来源：examples/cel-policy/README.md:1-10

架构设计

策略表达式在系统中的位置

CEL策略表达式位于coding-ethos架构的策略执行层，承上启下：

• 上游：ETHOS原则定义意图和上下文
• 执行层：CEL表达式提供可计算的谓词逻辑
• 下游：钩子、lint、MCP、SARIF消费同一策略ID

graph TD
    A[ETHOS原则] --> B[CEL策略表达式]
    B --> C[策略编译器]
    C --> D[PreToolUse钩子]
    C --> E[MCP lint_check]
    C --> F[SARIF报告]
    C --> G[CI/CD门控]

资料来源：examples/cel-policy/README.md:10-20

策略表达式的数据模型

策略表达式在数据模型中的定义包含以下核心字段：

资料来源：repo_ethos.yml:1-35

CEL表达式语法

表达式结构

CEL表达式是一个返回布尔值的谓词，当结果为true时表示策略违规。表达式中可以访问系统提供的上下文变量。

proposed_file_change.is_source
&& proposed_file_change.current_line_count >= 800
&& proposed_file_change.new_line_count > proposed_file_change.current_line_count

此表达式检查：如果文件是源代码文件，且当前行数不少于800行，且修改后行数增加，则触发策略违规。

资料来源：examples/cel-policy/README.md:20-35

策略表达式示例

以下是一个完整的策略表达式配置示例，附加到ETHOS原则：

principles:
  - id: keep-files-focused
    title: Keep Files Focused
    directive: Split large files into focused modules instead of growing them.
    axioms:
      - id: large-files-hide-design-problems
        text: Large files hide multiple reasons to change.
    policies:
      expressions:
        - id: filesystem.large_files.no_growth
          description: Large source files must not keep growing.
          event: PreToolUse
          severity: block
          expression: |
            proposed_file_change.is_source
            && proposed_file_change.current_line_count >= 800
            && proposed_file_change.new_line_count > proposed_file_change.current_line_count

资料来源：examples/cel-policy/README.md:14-30

可用的上下文变量

文件变更上下文

proposed_file_change对象提供当前文件变更的上下文信息：

事件上下文

event对象提供触发策略检查的事件信息：

资料来源：examples/cel-policy/README.md:30-45

路径与匹配函数

CEL表达式支持以下内置函数用于路径匹配：

(
  list_contains(["Write", "Edit", "MultiEdit"], event.tool) &&
  paths.exists(path,
    any_glob_match(
      [
        "AGENTS.md",
        "CLAUDE.md",
        "GEMINI.md",
        "ETHOS.md"
      ],
      path.file
    )
  )
)

资料来源：repo_ethos.yml:15-35

策略执行流程

触发与评估流程

sequenceDiagram
    participant Agent as AI Agent
    participant Hook as PreToolUse Hook
    participant Compiler as 策略编译器
    participant CEL as CEL运行时
    participant Skill as 修复技能

    Agent->>Hook: 执行工具操作
    Hook->>Compiler: 查询适用策略
    Compiler->>CEL: 评估表达式
    CEL-->>Compiler: 评估结果
    alt 违规
        Compiler-->>Hook: 返回阻止/警告
        Hook-->>Agent: 显示message和advice
        Agent->>Skill: 加载skill_id
        Skill-->>Agent: 返回修复步骤
        Agent->>Agent: 执行修复
        Agent->>Hook: 重试操作
    else 合规
        Compiler-->>Hook: 允许执行
        Hook-->>Agent: 工具执行成功
    end

MCP服务集成

CEL策略表达式通过MCP服务器的lint_check和lint_advice工具暴露：

• lint_check：运行托管的lint捕获或编译的策略lint
• lint_advice：将诊断结果映射到ETHOS策略和技能指导
• sarif_remediation_advice：将SARIF证据转换为聚焦的修复建议
• sarif_policy_feedback：识别未映射或噪音诊断

资料来源：examples/mcp-lint-advice/README.md:1-45

策略表达式的最佳实践

原则与策略的对应关系

每个策略表达式应该与其所属的ETHOS原则保持紧密对应：

1. 原则说明意图：通过title、directive、axioms描述规则的目的
2. 策略提供执行：通过policies.expressions提供可执行的谓词
3. 两者共享ID体系：策略ID应能追溯到原则ID

principles:
  - id: protocol-first-design
    title: Protocol First Design
    directive: Define interfaces before implementation.
    policies:
      expressions:
        - id: filesystem.interface_edit
          # 策略ID反映原则主题

资料来源：repo_ethos.example.yml:30-50

表达式的编写原则

• 保持表达式简洁：复杂的逻辑应拆分为多个策略或使用辅助函数
• 明确边界条件：使用精确的数值阈值和类型检查
• 提供有价值的advice：违规消息应包含具体的修复路径
• 设置合理的severity：block用于必须遵守的规则，warn用于建议性规则

资料来源：examples/cel-policy/README.md:45-55

与SARIF的集成

CEL策略违规可以输出为SARIF格式，携带以下信息：

通过SARIF输出，策略违规可以进入代码扫描工作流、编辑器和CI/CD门控。

资料来源：examples/cel-policy/README.md:55-65

总结

CEL策略表达式是coding-ethos实现可执行编码规范的核心机制。它通过：

• 声明式语法：使用CEL语言描述策略谓词
• 原则绑定：将策略附加到ETHOS原则，保持意图与执行的统一
• 多路径执行：通过钩子、MCP、SARIF等渠道统一执行
• 技能集成：策略违规关联修复技能，实现自动化修复指导

这一设计使得ETHOS原则既是人类可读的开发指南，也是机器可执行的策略规则，实现了编码规范从文档到实践的闭环。

Pitfall Log / 踩坑日志

项目：paudley/coding-ethos

摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Bundle or provision Bubblewrap as a required sandbox dependency。

1. 安装坑 · 失败模式：installation: Bundle or provision Bubblewrap as a required sandbox dependency

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Bundle or provision Bubblewrap as a required sandbox dependency
• 对用户的影响：Developers may fail before the first successful local run: Bundle or provision Bubblewrap as a required sandbox dependency
• 证据：failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/132 | Bundle or provision Bubblewrap as a required sandbox dependency

2. 安装坑 · 失败模式：installation: bug: commit amend is not blocked by git safety policy

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: bug: commit amend is not blocked by git safety policy
• 对用户的影响：Developers may fail before the first successful local run: bug: commit amend is not blocked by git safety policy
• 证据：failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/112 | bug: commit amend is not blocked by git safety policy

3. 安装坑 · 来源证据：Bundle or provision Bubblewrap as a required sandbox dependency

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bundle or provision Bubblewrap as a required sandbox dependency
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/paudley/coding-ethos/issues/132 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：bug: commit amend is not blocked by git safety policy

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: commit amend is not blocked by git safety policy
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/paudley/coding-ethos/issues/112 | 来源类型 github_issue 暴露的待验证使用条件。

5. 配置坑 · 失败模式：configuration: [feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping
• 证据：failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/54 | [feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping

6. 配置坑 · 失败模式：configuration: [test] Add sandbox workflow E2E coverage

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [test] Add sandbox workflow E2E coverage
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [test] Add sandbox workflow E2E coverage
• 证据：failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/129 | [test] Add sandbox workflow E2E coverage

7. 配置坑 · 来源证据：[test] Add real MCP stdio workflow coverage

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[test] Add real MCP stdio workflow coverage
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/paudley/coding-ethos/issues/114 | 来源类型 github_issue 暴露的待验证使用条件。

8. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:1214781313 | https://github.com/paudley/coding-ethos | README/documentation is current enough for a first validation pass.

9. 运行坑 · 失败模式：runtime: [feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: [feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation
• 对用户的影响：Developers may hit a documented source-backed failure mode: [feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation
• 证据：failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/55 | [feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:1214781313 | https://github.com/paudley/coding-ethos | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:1214781313 | https://github.com/paudley/coding-ethos | no_demo; severity=medium

12. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:1214781313 | https://github.com/paudley/coding-ethos | no_demo; severity=medium

13. 安全/权限坑 · 来源证据：[feature] Agent Proxy: Generate Global AST Repo Map on Session Start

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[feature] Agent Proxy: Generate Global AST Repo Map on Session Start
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/paudley/coding-ethos/issues/59 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：[feature] Agent Proxy: Implement Read Deduplication & Caching for File Access

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[feature] Agent Proxy: Implement Read Deduplication & Caching for File Access
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/paudley/coding-ethos/issues/53 | 来源类型 github_issue 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：[feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[feature] Agent Proxy: Pre-Flight File Indexing and AST Anatomy Mapping
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/paudley/coding-ethos/issues/54 | 来源类型 github_issue 暴露的待验证使用条件。

16. 安全/权限坑 · 来源证据：[feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[feature] Agent Proxy: Tool Output Compression and Stack Trace Truncation
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/paudley/coding-ethos/issues/55 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

17. 安全/权限坑 · 来源证据：[test] Add sandbox workflow E2E coverage

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[test] Add sandbox workflow E2E coverage
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/paudley/coding-ethos/issues/129 | 来源类型 github_issue 暴露的待验证使用条件。

18. 能力坑 · 失败模式：capability: [feature] Agent Proxy: Implement Read Deduplication & Caching for File Access

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: [feature] Agent Proxy: Implement Read Deduplication & Caching for File Access
• 对用户的影响：Developers may hit a documented source-backed failure mode: [feature] Agent Proxy: Implement Read Deduplication & Caching for File Access
• 证据：failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/53 | [feature] Agent Proxy: Implement Read Deduplication & Caching for File Access

19. 能力坑 · 失败模式：capability: [test] Add real MCP stdio workflow coverage

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: [test] Add real MCP stdio workflow coverage
• 对用户的影响：Developers may hit a documented source-backed failure mode: [test] Add real MCP stdio workflow coverage
• 证据：failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/114 | [test] Add real MCP stdio workflow coverage

20. 能力坑 · 失败模式：conceptual: [feature] Agent Proxy: Generate Global AST Repo Map on Session Start

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: [feature] Agent Proxy: Generate Global AST Repo Map on Session Start
• 对用户的影响：Developers may hit a documented source-backed failure mode: [feature] Agent Proxy: Generate Global AST Repo Map on Session Start
• 证据：failure_mode_cluster:github_issue | https://github.com/paudley/coding-ethos/issues/59 | [feature] Agent Proxy: Generate Global AST Repo Map on Session Start

21. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:1214781313 | https://github.com/paudley/coding-ethos | issue_or_pr_quality=unknown

22. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:1214781313 | https://github.com/paudley/coding-ethos | release_recency=unknown

23. 维护坑 · 失败模式：maintenance: v0.2.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.2.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.2.0
• 证据：failure_mode_cluster:github_release | https://github.com/paudley/coding-ethos/releases/tag/v0.2.0 | v0.2.0

24. 维护坑 · 失败模式：maintenance: v0.2.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.2.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.2.1
• 证据：failure_mode_cluster:github_release | https://github.com/paudley/coding-ethos/releases/tag/v0.2.1 | v0.2.1