📊 架构分析报告
使用手册 · For Humans

给你的 AI 团队装一条反腐败防线

OpenArch 不是又一个 linter。它承认代码腐化是熵、不可避免——所以给你的每个 AI Agent 一套能就地重建的本地治理防线：信息论度量、符号级变更冲击、fail-closed 门禁， 以及一份 Agent 真正会读的行动手册（Skill）。本地、确定、可审计，门禁里没有 LLM。

最省事 · 让 Agent 读 INSTALL.md 看日常工作流 GitHub 仓库 ↓
支持 · Claude / Codex / Cursor / OpenCode / Reasonix 语言 · TypeScript · Python · Rust · Java · Go 形态 · 单文件二进制，零 node_modules
一句话

为什么是它 传统质量门是一次性建好的墙——规则老化、Agent 学会绕过、下次重踩同一个坑。 OpenArch 是一条战壕：阈值随你的项目 P95 自校准，防线由 Agent 读着 playbook 就地重建， 每次改动用符号级证据照亮真实冲击，缺证据就 UNAVAILABLE 绝不假装通过。 门禁里没有 LLM——你的代码不出楼，裁决本地可复现。

01 · 日常长什么样

30 秒看懂工作流

装好之后，你和 Agent 的日常就多这四步。"状态是基线，变化是信号"——先建事实，再以变更取证。

每次开工

context

只读建立项目事实：基线、策略、治理可用性。判断下一步。

首次 / 存量盘点

scan → review

建基线；看 Top-3 局部负担文件与结构候选。

改代码中

check --worktree

以工作树取证：I_push 冲击、WARN、反模式 finding。

提交前

check --staged

以 Git index 同一快照取证，信号归零再提交。

02 · 安装（重点）

三步让 Agent 装上并用起来

从拿到 CLI 到 Agent 在项目里跑起来。源码构建与本地 tarball 均正式可用；npm 仓库发行仍暂缓（已在选项中置灰）；初始化与验证两步通用。

最省事 · 推荐

更高效的路径：让 Agent 读 INSTALL.md

与其照着下面三步手动敲，更高效的做法是把仓库的 INSTALL.md 直接交给你的 Agent——它会自己读文档、执行构建与 init、验证 Skill，人类只需在关键决策点（个人 / 团队模式、工具链路径）确认。仓库地址：github.com/VilTea/openarch

# 对你的 Agent 说：
读 https://github.com/VilTea/openarch 仓库里的 INSTALL.md，
把 OpenArch 装到当前项目（openarch init --agent claude，若你用的是 codex / cursor / opencode / reasonix 请替换），装完跑 openarch context 验证。

这契合 OpenArch 自身哲学——INSTALL §3.1 本就写着 "Agent: read this"，Skill 也是 Agent 真正会读的 playbook。下面的手动三步留给想自己掌控每一步的人。

1

获得 openarch CLI

一条持久命令，所有本地项目和 Agent 会话共享。

前置：Node.js 20+、pnpm 9.x（corepack enable）、bun、Git。先从 GitHub 克隆源码：

# 克隆源码
$ git clone https://github.com/VilTea/openarch
$ cd openarch
$ corepack enable
$ pnpm install
$ pnpm release:binary      # bun build --compile → 单文件二进制（含 TS 编译器 API，无需 node_modules）

产物在 artifacts/binary/openarch-<平台>-<架构>/：openarch(.exe) + resources/（tree-sitter WASM 语法、脚本资产、Skill）。脚本会在临时项目里先探测（--help、各语言 scan、Skill 安装）再落盘。

# 构建并原子安装到 %LOCALAPPDATA%\OpenArch\bin，写入用户 PATH
$ pnpm release:local-command
$ openarch --version       # 新开终端验证

在受治理项目里把 CLI 作为开发依赖：

$ npm install --save-dev @openarch/cli
$ npx openarch init --agent codex

可选：装一份用户级 Skill（跨项目，不含项目作用域）：

$ npm install --global @openarch/plugin
$ openarch-agent-install --target codex --locale en

用户级安装故意不带项目作用域；每个项目仍用 openarch init --agent <target>。

无网络或内网：本地打 tarball，装进受治理项目，再跑同样的 CLI 初始化：

$ pnpm release:local
$ npm install --save-dev /absolute/path/to/openarch-cli-<version>.tgz
$ npx openarch init --agent codex
2

初始化受治理项目 + 安装 Skill

在受治理仓库根目录执行。一条命令同时完成项目初始化与 Agent Skill 装机。

# 把 claude 换成你的 Agent：claude | codex | cursor | opencode | reasonix
$ openarch init --agent claude
$ openarch context

--agent 决定 Skill 落在哪个 harness 的项目级目录；它读取 .openarch/config.yml 的 presentation.locale 安装 zh 或 en Skill 树，原子替换旧目录。注意：--lang 只改本次 CLI 输出，不会改变已安装的 Skill。

Harness命令Skill 位置
Claudeopenarch init --agent claude.claude/skills/openarch/
Codexopenarch init --agent codex.codex/skills/openarch/
Cursoropenarch init --agent cursor.cursor/skills/openarch/
OpenCodeopenarch init --agent opencode.opencode/skills/openarch/
Reasonixopenarch init --agent reasonix.reasonix/skills/openarch/
其它兼容 Agentopenarch init --skill-dir .my-agent/skills自定项目相对目录
3

验证、Hook 与模式

按需装 pre-commit hook、选择个人/团队持久化模式、配置外部工具链。

# 代码仓 pre-commit hook：封存语义证据 + 执行已配置门禁
$ openarch init --install-hook

# 个人项目：运行产物不进 Git（只写 .git/info/exclude）
$ openarch init --mode personal --install-hook

# 团队审查模式：产物 tracked，可经 scan 重建
$ openarch init --mode team --install-hook

# 外部工具链（编译器/LSP）是机器事实，绝不进项目依赖
$ openarch toolchains              # 查看所需工具
$ openarch init --toolchains user  # 用户级；project 则写 .openarch/toolchains.local.yml（入本地 exclude）

CI 可用 OPENARCH_<TOOL_ID>_PATH 环境变量覆盖两个文件。Skill 在发现不可用时会按语言读取对应配置说明。

03 · Agent 必读

Skill 装机三步（Agent: read this）

CLI 装好后，Agent 自己把 OpenArch Skill 装进工作环境。这三步直接抄自 INSTALL §3.1。

1

为自己的 harness 装 Skill

执行 openarch init --agent <你的目标>，Skill 落入你的项目级 skills 目录。升级 OpenArch 后重跑刷新（退役文件被原子清除）。

2

验证 Skill 已就位

依赖它之前确认目录存在且含 SKILL.md：

$ ls .claude/skills/openarch/SKILL.md

若缺失，重跑对应 init --agent 并读错误输出。

3

工作中遵循 Skill

已安装的 Skill 就是行动手册：治理工作前先读它，跑 openarch context 建立事实，再按路由选 scan/review/check/rules/docs。check 输出是全量信号面——PASS 也要读 WARN、TEST_BLOAT、反模式 finding；PARTIAL/UNAVAILABLE 是事实边界，不是 clean。

04 · 命令速查

openarch 命令面

公开命令 11 个 · 高级命令 4 个。逐命令帮助用 openarch <command> --help。

11 + 4
公开 + 高级命令
5 种
符号级语言
28 条目
内置脚本清单
0 LLM
门禁确定性
init
初始化受治理项目 · 装 Skill · hook · 模式 · 工具链
context
只读项目事实：基线、策略、治理可用性 · --json 机器契约
contract
机器契约目录：插件消费的 JSON 契约 id/version/status
scan
建立/更新状态基线（CRL、结构、TEST_BLOAT）
review
存量复盘：Top-3 局部负担、结构候选 · --evolution 历史演化（仅报告）
check
变更冲击门禁：--worktree / --staged · --semantic · --tests/--full · --output-mode 报告层级 · --record-config
rules
项目规则：facts（自描述注册表：--domain/--query 检索 · --unused 零消费者 CI 提示）→ skeleton → 脚本 → scan · discover 隐式依赖
docs
协作文档库：check（相似候选 · --unfilled · --json）/ record / status / decide 处置
toolchains
查看/配置外部编译器与语言服务器
test
测试治理：六框架适配器、provider 覆盖、[--list] [--bloat] [--json]
update
只读远端发行感知：当前/最新版本 · --json
coordination
可选远程：Task / 租约 / 语义锁（默认 UNAVAILABLE）
lsp
LSP 预热与常驻 daemon（jdtls / gopls 转发）
calibration
P95 校准 epoch 管理
anti-patterns
反模式引擎直接访问
05 · 测试治理与机器契约

两个独立演进位面

测试治理面向仓库内部的测试事实，机器契约面向外部插件的消费边界——两个位面各自版本化、独立演进，谁也不绑架谁。

位面 A · 独立报告层

测试治理

provider 采集测试事实、runner 执行真实命令；报告按 decision / collection / execution / scripts 四层分开——策略裁决与证据边界不互相覆盖。测试与辅助文件不进生产度量。

🧪 openarch testVitest · node:test · Go testing · Rust Cargo · JUnit · pytest 六参考适配器；Cargo/Maven/Gradle/pytest/node:test runner 给实际命令证据；provider 边界 candidates / handled / missingBaseline / failed fail-closed，无启用 provider 时按语言只建议适配器、不自动启用。
🔍 finding 与关联test-illusion（看似有断言实则没有）、S2 静态模块→测试关联、--bloat minhash 膨胀诊断——全部 report-only，不进 gate。
✅ check --tests把测试治理评估追加进变更验证心流（可与 --full 组合跳过 diff 前置做全量）；test --list 列出已注册 provider，供配置引用。
位面 B · 版本化边界

机器契约

外部插件只消费版本化的 JSON 契约，不解析 .openarch 内部文件：破坏性变更必须 bump version，非破坏字段同版本追加；插件一律读顶层 schema 判断版本，不得用"缺字段即旧版"反推。

📜 openarch contract机器契约目录 contract-catalog-json-v1：context / test-governance / provider-list / rules-facts / docs-check 五份契约的 id、version、status 一览。
🔌 context --json顶层 schema 字段自识别（context-json-v1）；readiness 按 enforcing / advisory / optional 分级——code-hook 未装是 ⚠，协调服务未配置是常态。
🗂 docs check --json文档治理证据契约 docs-check-json-v1：索引文档、相似候选、未填写模板与处置记录——配合 docs decide 关闭相似候选的处置闭环。
🛰 update --json只读远端发行感知：打印当前/最新版本与升级步骤，绝不自动安装。
06 · 边角与取舍

常见疑问

Q. 个人项目和团队项目有什么区别？

governance.persistence 是运行产物是否进 Git 的唯一权威。新项目默认 tracked（团队）。--mode personal 写 local，只在 .git/info/exclude 管理 OpenArch 的 .openarch/ 区块——hook 仍封存证据、执行门禁，但不暂存生成的 baseline/history/审计产物。本地状态随时可用 openarch scan 重建。

Q. 外部工具链（pyright / rust-analyzer / jdtls）要装吗？

它们是机器事实，不是项目依赖——绝不写进 manifest/lockfile。TypeScript 用内置编译器 provider（精确），其余语言按需配置：openarch toolchains 查看，openarch init --toolchains user|project 填绝对路径。工具链不可用时符号级证据 fail-closed（不降级兑底）。符号级 complete 是语言级校准边界：Rust 单 crate 且无 build.rs/workspace/macro/cfg，Go 单 module 且无 go.work/build constraint/生成代码，Java 标准 Maven 布局且无模块/依赖/反射，Python 限 pyright 可解析范围；越界保持 PARTIAL 并保留已收集事实，绝不伪造零。

Q. 协调服务是必须的吗？

不是。本地 OpenArch 默认独立工作。只有用户显式执行 openarch init --coordination-url <https://...> 后，远程 Task/会议/语义锁才可用——否则这些操作是 UNAVAILABLE，本地治理照常。地址绝不从 Git remote、目录或环境变量推导。

Q. 升级 OpenArch 后怎么刷新 Skill？

重跑 openarch init --agent <target>。它会原子替换整个旧 OpenArch Skill 目录，清除退役文件。已安装的 Skill、runtime/plugin 镜像对接入项目是只读输入，发现过期或不匹配时上报上游，不在接入项目内修改。