让 AI 理解项目，也能验证改动的工作区设计

给下一位 agent 一个明确的起点

仓库通过 AGENTS.md 提供第一站。它明确 OpenSurge 是 macOS 网关与控制面，mihomo 是当前代理引擎，并指向相关的架构和验证文档。处理 TUN 路由的 agent 可以先沿着对应阅读路径理解设计，再进入实现。

这个入口也记录了容易被局部改动遗漏的约束：透明代理主线采用 TUN；Web GUI、菜单栏 App 和 CLI 应复用 Go 业务规则；高风险网络改动需要实验室证据。贡献者可以在开始编码前，知道哪些已有决策必须得到尊重。

把项目知识放在事实来源旁边

Agent Wiki 分成两层。sources 目录保存稳定的项目事实、决策和验证契约；wiki 目录提供短小、相互链接的上下文页面，并指回作为事实来源的代码与文档。

一次路由任务可以从概念页开始，找到相应决策，再进入配置编译器或生命周期代码。这样，后续会话能够找到实现背后的原因，也能继续核对支撑这些结论的来源。

AGENTS.md
README.md
docs/agent-wiki/
  sources/
    project-brief.md
    decisions/
    validation/
  wiki/
    index.md
    concepts/

让运行中的系统可以被检查

Web GUI 是主要操作入口，omg CLI 同时保留面向诊断和自动化的结构化接口。status、doctor、leases、logs、policies、connections、providers 和 snapshot 等命令支持 JSON 输出。

snapshot 将网关状态、检查结果、租约、日志尾部和 mihomo 观测聚合起来。如果 mihomo API 不可用，聚合结果会在对应局部字段记录失败。agent 可以据此区分服务未运行、配置有误和后端不可用，再提出针对性的修复。

• 通过结构化状态，辨认期望配置与实际运行状态。
• 通过连接和日志证据，核对流量实际经过的路径。
• 服务或 API 无法检查时，明确记录缺少了什么证据。

omg status --format json
omg doctor --format json
omg snapshot --format json

让每类改动找到对应的证明方式

验证地图回答一个具体问题：哪些检查通过后，才能说某种行为已经验证？单元测试保护配置与业务规则，host-network 门槛运行 macOS 网关，TUN、设备策略、下游 IPv6 和 Tailscale 还有各自更具体的门槛。

例如，Tailscale 规则编译测试可以检查目标与来源匹配，mihomo 配置检查成功可以说明当前内核接受生成的 YAML，专门的 Tailscale Lab 则让两台下游客户端实际发包，核对托管路径与未授权拒绝。每一步都对应不同层次的结论。

把可复用结论留给下一次任务

当改动影响生命周期不变量、路由决策或验证契约时，工作区规则要求随实现同步更新相关来源材料和 Wiki 页面。真实故障中沉淀出的可复用排查规则，也可以成为下一位贡献者的上下文。

一次性日志、临时命令输出、未经验证的猜测和普通 TODO 不进入这层稳定知识。Agent Wiki 当前由人工维护；目录形状为未来的 compiler 工作流预留了空间，但自动编译知识还不是项目当前具备的能力。

让贡献过程可以被复核

我们希望形成这样的工作流程：阅读入口，找到相关上下文，核对源码与当前状态，完成范围明确的改动，运行适用检查，再记录证据能够支持的结论。文档帮助选择测试，测试结果支撑能力描述，经过审查的发现继续改善下一次任务的上下文。

对用户而言，这种设计带来的价值是可追溯性。一项网络能力有对应的原理说明，有实现必须保持的约束，也有检查行为的方法。工作区让人类和 AI 贡献者都更容易理解这些关系。