横木：基于证据的架构评审与设计技能集合

技能介绍

横木（Hengmu）是一个本地优先、以证据为约束的架构评审与目标架构设计工具，面向 Codex 以及兼容 Agent Plugins 的主机。它把仓库事实、已批准的设计意图和显式约束，转换成有证据支撑的现状评估、开放或受约束的目标架构、可追溯的决策、可执行的计划，以及确定性的策略结论。

现状评估与目标设计是两条平等的入口路径：既有系统可以从候选发现出发，经独立验证走到整改决策；新系统与重大重构则可以从一份已批准的 Design Brief 出发，产出完整的目标架构，而不必凭空编造一次评审或一组发现。必需、偏好与禁止类约束都是待挑战的输入，从来不是可行性或适配性的证明。

架构视图覆盖：性能效率、可靠性、安全与隐私边界、数据与 API 契约、可观测性、测试、部署、技术债、比例恰当性、技术选型与运行现实。专用镜头还覆盖 AI Agent 上下文与成本、Memory、工具权限、隐私、行为证据、技术演进、移动系统与多项目组合。

它刻意不是通用的"最佳实践"清单：一条规则只有在守护某个已声明的质量属性或关键流程时才有用；一条建议只有在项目能理解它的成本、依赖、迁移顺序和停止条件时才有用。它也不是托管式架构服务或通用代码 linter。项目 Profile 决定哪些质量属性与专项评审重要——全局 Skill 提供方法，仓库提供事实。

适用场景

• 仓库级架构评审：想拿到基于项目实据的架构风险清单与可落地修复方案。
• AI Agent 架构审计：上下文必要性/组装/压缩/缓存顺序、Memory、检索、工具、注入、隐私、审批、恢复、成本、延迟与演进边界。
• 目标架构设计：为新系统或重大重构设计符合性能、隐私等约束的目标架构。
• 架构决策治理：比较可选方案、记录备选方案为何落选、把授权决策转为有序实施切片。
• 整改规划：把已接受的发现变成带回滚、停止条件与验收证据的实施计划。
• 确定性质量门禁：用可复现的策略评估替代"文件里写了 must"。

核心能力

它同时工作在两个层级：单个仓库（使用项目专属的 Profile、约束、关键流程、规则与评审历史）；仓库组合（寻找重复建设、技术栈发散、共享能力、归属冲突、数据流与隐藏耦合）。

为什么需要它（典型评审失败 vs 横木的回应）：

八个聚焦工作流（$hengmu 是唯一需要记住的 Skill 名，直接调用可看到完整能力菜单）：

信任模型

模型可以提出主张。由证据、权限、溯源与策略决定什么能成为可信或阻断。

可信评审会绑定：被评审仓库的身份与 Git 状态、精确范围、Profile、仓库事实、选中的 Knowledge、规则包、候选评审、验证者权限、语义化 Finding 指纹、关键流程覆盖和可解析证据。

确定性运行时提供：项目/评审/决策/计划/策略/基线/风险接受/Knowledge/Provider/基准/治理工件的 JSON Schema；带完整覆盖检查的机器可读核心与领域规则包；在显式上下文预算下选取的有源 Knowledge Pack；可选启用、无 shell 执行、安全环境白名单、超时、结构化输出校验与防篡改运行记录的 Evidence Provider；以及 Git 证据解析、精确哈希、签名验证、SARIF、评审 diff、工件迁移、基准打分与分层门禁。

语言 linter 与质量分析器被当作可选证据来源而不是架构真理。Provider 发现过程会区分：适用标记、项目配置、是否启用、可执行文件是否存在、就绪状态。缺少可执行文件会保留为一个明确的"未评估"证据面。横木从不隐式下载、安装、启用或添加依赖；如果安装能显著改善评审，它会先说明确切的工具、范围、版本策略、命令、受影响文件与后果，再请求用户授权。Provider 通过只证明被捕获的命令、可执行文件、声明的项目依赖闭包、隔离缓存模式、配置、提交与输出字节；只有在绑定到适用不变量并独立评审之后，它才成为架构证据。

门禁阶段与治理模式

门禁阶段是累积的：

治理模式：

product_mode 是声明的运行层级，不是绕过机制：显式调用的门禁始终会评估它的策略。

非目标

横木不会：自主批准架构决策、风险或发布；把每个检测到的技术、模式或大文件都变成 Finding；在没有显式组合注册表的情况下发现无关仓库；自行实施被审计产品的整改；替代专门的安全、隐私、性能、法律或合规评估；证明某个系统是安全或正确的。

效果预览

工作方式

横木把模型判断与确定性信任分开。它接受两条来源路径，候选审计和约束声明都不是策略或证明：

1. 建立事实与意图 — 检查仓库并绑定 Profile；做目标设计时，补充一份带可度量场景与边界的已批准 Brief。
2. 加载上下文 — 绑定约束、关键流程、选中的规则包与任务范围内的 Knowledge，不把检测到的技术或负责人主张变成证明。
3. 评估或设计 — 既有系统产出候选发现供独立验证；Greenfield 工作用已批准 Brief 比较开放或合规的目标，不制造发现。
4. 决策 — 记录选中的目标、被拒的备选、取舍、完整架构模型、来源绑定与建议状态。
5. 授权 — 由具名决策者接受、拒绝或取代该决策；横木的路由器与 Advisor 不能执行这一转换。
6. 规划 — 把已接受的整改或 Greenfield 目标转成有序实施切片、防护、回滚、停止条件与验收证据。
7. 门禁 — 对溯源绑定的工件应用确定性的契约、发现、变更或发布策略。

一个方法，多个项目：仓库不应携带一份私有的架构方法副本，而只携带让它的决策与众不同的上下文——profile.yaml（项目类型、关键质量属性、必需评审）、constraints.md（真实的技术、产品、法规与团队限制）、critical-flows.md（不得回退的业务与运行时路径）、architecture-design-brief.yaml（目标意图、质量场景、边界与类型化约束）、reviews/（候选与已验证的评审、决策、计划与证据历史）。组合评审补充缺失的系统之系统视角：哪些能力应当共享、哪些边界必须独立、数据在哪里流动，以及一个仓库会在哪里意外影响另一个。

当前 Brief 1.1 路径会产出一份提议中的 Decision 1.4，其中包含完整目标架构。横木不批准 Brief 或 Decision，也不实现应用代码。在具名决策者接受 Decision 之后，$hengmu plan … 可以产出 Greenfield Plan 1.3。审计路径可以直接运行：Skill 会自动调用准备命令并初始化 .architecture/；只有当你想要一次不留仓库工件的一次性 Advisory 评估时，才使用显式的只读请求。

你需要提供

• Python 运行时：横木的 Skill 是可移植的，但确定性辅助工具需要 Python 3.11–3.13、PyYAML 和 jsonschema，依赖需按 lock 文件安装到 IDE agent 能用的 python3 环境。
• 完整安装目录：把解压目录放在稳定的绝对路径并称为 HENGMU_ROOT；每个主机都需要完整目录而不只是 skills/hengmu，因为路由器、聚焦 Skill、schema、Knowledge 与确定性 CLI 都在 skills/ 和 resources/ 之间使用相对路径。
• 仓库与该仓库的事实：要评审的项目仓库，以及项目专属的 Profile、约束与关键流程。
• 做目标设计时：一份已批准的 Design Brief（模板刻意是 draft；在改为 approved 之前，需要加入带授权决策者身份的 brief.approval、至少一个仓库相对路径的批准证据与 SHA-256，以及每位批准者一份分离的 SSH 签名。验证从不把模板作者或一个状态字符串当作批准）。

你会获得

• 候选评审（Candidate Review）与经独立验证、溯源绑定的可信评审（含 V0–V5 验证等级）。
• 完整的决策记录：选中目标、被拒备选、取舍、架构模型与来源绑定。
• 有序的整改计划（Plan 1.2）或 Greenfield 计划（Greenfield Plan 1.3），含回滚、停止条件与验收标准。
• 确定性的门禁结果与稳定退出码（0 通过、1 策略失败、2 输入或配置无效）。
• 仓库本地的控制面 .architecture/（profile.yaml、repository-facts.yaml、constraints.md、critical-flows.md、gate-policy.yaml、baseline.yaml、risk-acceptances.yaml、evidence-providers.yaml 以及 evidence/、rules/、runs/、reviews/ 目录）。

使用示例

安装与运行时准备

从同一个 GitHub release 下载两个 ZIP 文件及其 .sha256 文件，解压前先校验（macOS 用 shasum，Linux 用 sha256sum）：

shasum -a 256 -c hengmu-.zip.sha256
shasum -a 256 -c hengmu--agent-plugins.zip.sha256

cd "$HENGMU_ROOT"
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --require-hashes -r requirements-runtime.lock
python3 resources/scripts/architecture_tool.py --version

最后一条命令应打印 architecture_tool.py 1.0.4。Windows PowerShell 下用 .venv\Scripts\Activate.ps1 激活。安装不会授予权限或启用 Hooks；在允许仓库写入或 shell 执行前，请先检查每个主机的 agent 权限。

Codex / ChatGPT desktop：把 Codex ZIP 解压到个人插件目录（例如 ~/.codex/plugins/hengmu），然后把下面这条加入 ~/.agents/plugins/marketplace.json 的 plugins 数组（与已有 marketplace 合并，不要覆盖整个文件）：

{
  "name": "hengmu-local",
  "interface": { "displayName": "Hengmu Local" },
  "plugins": [
    {
      "name": "hengmu",
      "source": {
        "source": "local",
        "path": "./.codex/plugins/hengmu"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Developer Tools"
    }
  ]
}

重启 ChatGPT desktop，打开 Plugins，选择 Hengmu Local 并安装。Codex CLI 里运行 /plugins，从同一 marketplace 安装并开启新会话。用 $hengmu audit this repository 调用路由器，或直接用自然语言描述目标。ChatGPT Work 模式下用 @hengmu 选择它。

Cursor：把 Agent Plugins ZIP 解压到 ~/.cursor/plugins/local/hengmu，重启 Cursor 或运行 Developer: Reload Window；在 Customize 中确认 Hengmu Skills 已启用。开发时也可以软链接一个 checkout：

mkdir -p ~/.cursor/plugins/local
ln -s /absolute/path/to/hengmu ~/.cursor/plugins/local/hengmu

VS Code / GitHub Copilot：启用 chat.plugins.enabled，运行 Chat: Install Plugin From Source 并输入 https://github.com/qingye-lab/hengmu；固定本地构建时解压 Agent Plugins ZIP 并在设置里注册绝对目录：

{
  "chat.pluginLocations": {
    "/absolute/path/to/hengmu": true
  }
}

VS Code 会用插件名为插件提供的 Skill 加命名空间，因此在 Copilot Chat 中调用 /hengmu:hengmu audit this repository，或使用自然语言。GitHub Copilot CLI 也可直接安装：

copilot plugin install qingye-lab/hengmu
copilot plugin list
copilot

Kiro：Kiro 从 .kiro/skills/ 发现工作区 Skill，不使用横木根目录的 plugin.json。把 Agent Plugins ZIP 解压到稳定的 HENGMU_ROOT，再把 Skill 及其共享资源投影进仓库（仅当 .kiro/resources 未被占用时使用，或刻意合并目录）：

mkdir -p .kiro/skills .kiro/resources
cp -R "$HENGMU_ROOT/skills/." .kiro/skills/
cp -R "$HENGMU_ROOT/resources/." .kiro/resources/

在 Kiro 中打开 Agent Steering & Skills，确认九个横木 Skill 全部可见。不要只导入 skills/hengmu：路由器会委派给八个兄弟 Skill，它们都需要共享运行时。

快速开始

git clone https://github.com/qingye-lab/hengmu.git
cd hengmu

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --require-hashes -r requirements-runtime.lock
python3 scripts/validate_repository.py

准备仓库控制面（缺失时创建，存在时校验并复用，不覆盖）：

HENGMU_ROOT=/path/to/hengmu

python3 "$HENGMU_ROOT/resources/scripts/architecture_tool.py" \
  prepare-project-audit --repo /path/to/your-project

在 Codex 中选择结果。对既有系统，从现状评估开始：

Use $hengmu to audit this repository.
Treat missing capabilities as findings, but verify evidence before
recommending a structural change.

$hengmu 是唯一需要记住的 Skill 名，单独调用可看到完整能力菜单，也可以用自然语言描述目标：

$hengmu
$hengmu verify the latest candidate findings
$hengmu compare the queue and durable-workflow options

对新系统或重大重构，先添加并批准 Design Brief，再要求开放或受约束的目标：

if [ ! -e /path/to/your-project/.architecture/architecture-design-brief.yaml ]; then
  cp "$HENGMU_ROOT/resources/templates/architecture-design-brief.yaml" \
    /path/to/your-project/.architecture/architecture-design-brief.yaml
fi

python3 "$HENGMU_ROOT/resources/scripts/architecture_tool.py" \
  validate-design-brief \
  /path/to/your-project/.architecture/architecture-design-brief.yaml \
  --project /path/to/your-project

$hengmu design an open target architecture from the approved Design Brief
$hengmu constrain the target to FastAPI, PostgreSQL, and one production deployment; challenge each constraint and record rejected alternatives

项目 Profile 决定哪些质量属性与专项评审重要：

project:
  name: example-service
  type:
    - ai-agent-platform
  critical_qualities:
    - traceability
    - recoverability
    - privacy
  required_reviews:
    - project-architecture
    - ai-agent-architecture

校验结果

python3 "$HENGMU_ROOT/resources/scripts/architecture_tool.py" \
  validate-project /path/to/your-project

python3 "$HENGMU_ROOT/resources/scripts/architecture_tool.py" \
  gate --project /path/to/your-project --stage change

python3 "$HENGMU_ROOT/resources/scripts/architecture_tool.py" \
  gate --project /path/to/your-project \
  --decision .architecture/reviews/ --stage change

门禁返回 0 表示通过，1 表示策略失败，2 表示输入或配置无效。

可信评审与证据命令

python3 resources/scripts/architecture_tool.py review-bindings \
  --project /path/to/project \
  --candidate .architecture/reviews/example-candidates.yaml

python3 resources/scripts/architecture_tool.py validate-review \
  /path/to/verified.yaml --project /path/to/project

python3 resources/scripts/architecture_tool.py verify-evidence \
  --repo /path/to/project --review /path/to/verified.yaml

python3 resources/scripts/architecture_tool.py verify-review-signature \
  --project /path/to/project --review /path/to/verified.yaml

任务范围内的 Knowledge 选择

python3 resources/scripts/architecture_tool.py inspect-repository \
  --repo /path/to/project \
  --output /path/to/project/.architecture/repository-facts.yaml

python3 resources/scripts/architecture_tool.py select-knowledge \
  --facts /path/to/project/.architecture/repository-facts.yaml \
  --profile /path/to/project/.architecture/profile.yaml \
  --task "Current architecture audit" \
  --skill project-architecture-audit \
  --output /path/to/project/.architecture/knowledge-selection.yaml \
  --context-output /path/to/project/.architecture/knowledge-context.yaml

页面上的「试试这样做」示例

• 帮我审计当前项目仓库的架构，识别安全边界问题并给出可落地的修复方案。
• 帮我审计当前项目仓库的整体架构，输出经过验证的风险发现清单。
• 为我新开发的移动应用设计符合性能和隐私约束的目标架构。

支持范围：支持 Python 3.11–3.13，运行时完全本地——不需要托管服务、遥测、凭据、网络访问或 MCP 服务器。仓库当前已在 Codex、Cursor、VS Code / GitHub Copilot、Kiro 的官方安装路径上给出说明，但尚未记录在 Cursor 或其他外部 IDE 中的横木专属安装冒烟测试；格式兼容不等于命令、权限、UI 或市场行为完全一致。