工程案例
衡木：把架构发现变成可验证的工程决策
从系统审查与独立核实出发，把可信问题推进到方案选择、改造计划、回滚与确定性质量门禁。
角色
我的角色与范围
产品设计、架构实现、研究与验证，2026.07 · v0.4.2。
问题
要解决什么
很多代码与架构评审只输出观察：模型看到大文件、单例或技术名词就直接下结论；即使指出缺口，也没有进入方案权衡、迁移顺序、回滚和验收，团队仍然无法据此做工程决策。
衡木是本地优先、受证据约束的软件工程决策系统。它把仓库事实、项目 Profile、真实约束和关键链路作为上下文，连接候选审查、独立核实、方案决策、改造规划和确定性门禁。
范围
目标与不做事项
目标
- 让候选发现经过独立核实与证据解析后再成为可信结论
- 把确认缺口推进到方案比较、改造切片、回滚、测试和验收
- 同时支持单仓库质量审查与项目组合的共享能力、数据流和耦合分析
不做事项
- 提供脱离项目约束的通用最佳实践清单
- 把模型生成的审查意见直接当作确定性策略
- 依赖托管服务、遥测、凭据、网络或 MCP Server 才能运行
约束
现实边界
- 一套全局方法必须适配不同项目类型、质量属性与关键链路
- 事实、证据、来源、权限和门禁结果需要可验证地绑定
- 方案必须说明成本、依赖、迁移顺序、停止条件与可逆性
决策
真正影响结果的取舍
把候选审查与可信结论分开
模型输出先作为候选，独立核实器挑战事实、解析证据并保留被否定假设与局限，避免把表面结构直接升级为架构问题。
由项目 Profile 决定规则
全局方法提供审查与决策流程；项目只保存类型、关键质量属性、约束、关键链路和历史，使规则与真实业务保护目标绑定。
把批评推进到可执行方案
可信问题进入维持现状与结构性方案比较，再拆成有顺序的改造切片、保护措施、回滚、停止条件和验收证据。
模型判断与确定性门禁分离
JSON Schema、哈希、Git 证据、角色策略、指纹、签名和稳定退出码承担可复现门禁，模型不直接拥有策略通过权。
主流程
架构与实现
决策链：仓库事实与项目 Profile → 候选审查 → 独立核实 → 可信审核 → 方案比较 → 改造计划 → 确定性质量门禁。
作用层级：单仓库保护声明的质量属性与关键链路；项目组合识别重复能力、技术栈扩散、共享边界、所有权冲突、数据流和隐性耦合。
证据
如何确认它真的工作
结果
已经产生的影响
- 形成覆盖系统审查、独立核实、技术方案、改造规划与门禁的完整决策链
- 同时支持项目级与项目组合级工程治理，并为 AI Agent、移动和组合系统提供专项视角
- 发布 v0.4.2 公开基线、双语文档、项目网站和持续集成验证
边界
限制与后续
当前限制
- 候选审查仍可能遗漏事实，可信度取决于项目 Profile、证据提供者与独立核实质量
- 确定性门禁只能执行已声明策略，不能代替业务和组织层面的技术判断
- 项目组合分析需要维护跨仓库所有权、数据流和共享能力事实
后续
- 继续扩充真实项目的规则、性能运行证据与组合治理案例
- 验证方案比较和改造计划在长期项目演进中的可维护性