men （门）

治理

治理（governance）是 men（门）Agent 团队的协作规则总纲：以 6+1 角色权限矩阵与四类决策分级约束团队行为，以 D<No> 决策记录留存决策依据，以 PR + CODEOWNERS + chi 独立 Judge 构成变更与审查闭环，并以语义化版本 2.0.0 规范发布节奏。

角色与权限

治理规则定义了 6 个角色的模式、核心职责与负责维护的文件范围：

角色中文名模式核心职责负责维护的文件范围
men门primary意图分诊、任务分发、并行编排、汇总报告README.md、CHANGELOG.md、docs/PRD.md、docs/architecture.md、docs/governance.md、docs/guide/milestones.md、opencode.json
si思subagent深度思考、多角度方案、产出 plan envelope、知识管理docs/guide/quickstart.md、docs/drafts/、docs/knowledge/（沉淀与归档）
ji记subagent代码实现、前端开发、内容写作、本地 gate 验证scripts/*.mjs、.opencode/skills/*/、.opencode/command/*.md、docs/drafts/
chi持subagent投资分析、独立 Judge 评审、验收标准消费评审报告（如 docs/m2-acceptance/chi-*.md）
yi艺subagent文生图提示词工程、设计决策、生图、设计 Token设计文档、docs/ 下视觉方案、图片产物
xun寻subagent搜索、事实核查、RSS 扫描docs/research/、调研与事实核查报告
  • 入口唯一 — 6 个角色中仅 men 为 primary，是用户唯一对话入口；其余 5 个均为 subagent，由 men spawn。
  • 定义自维护 — 每个 agent 的自身定义文件（.opencode/agent/<名字>.md）由对应角色自己维护，遵守「变更流程」约束。
  • 独立 Judge — chi 兼任独立 judge，以 fresh-context spawn，不沿用上游 context，保证评审客观性。

来源：docs/governance.md

决策机制

决策类型

治理将决策分为四类，按影响面分配决策者与记录方式：

类型示例决策者记录方式
架构决策是否新增角色、是否迁移运行时men + 核心成员讨论docs/architecture.md 决策记录表
里程碑决策M5→M6 启动条件mendocs/guide/milestones.md
日常决策某个 skill 的修改对应 agentscripts/event.mjs 写入 events.jsonl
技术选型脚本语言、MCP 选择men + jidocs/research/00-m0-synthesis.md

判断规则：

  • 涉及多角色影响面（新增/删除角色、改运行时、改流程）→ 架构决策级别。
  • 仅影响单个 skill / 单个脚本的局部修改 → 对应 agent 自行决策，但必须留事件审计。
  • 低置信时先向用户确认，不猜。

决策记录

重要决策写入 docs/architecture.md 的「技术决策记录」表格，包含：决策编号、决策内容、依据、状态。

  • 决策编号格式：D<No>（如 D1–D6，已有 6 条沉淀在 milestones.md 与 architecture.md）。
  • 状态枚举：已采纳 / 已回滚 / 待验证。
  • 架构决策未经 men + 用户确认前，不得进入代码或文档正文。

回滚机制

某次决策导致回归（REGRESSED），需要回滚时：

  1. git revert 回退到上一版本
  2. 在 docs/governance.md 的「决策记录」中记录回滚原因
  3. 更新 CHANGELOG.md

回滚触发条件包括：

  • chi judge 判定 REGRESSED 且人工确认无法修复。
  • 机械验证退出码非 0，且 5 次强化后仍失败。
  • 用户明确要求放弃当前方案。

来源：docs/governance.md

变更流程

按变更对象分类，四类变更各有强制要求：

Agent 定义变更

修改 .opencode/agent/*.md 时必须遵守：

  1. 先 read 再 edit
  2. 保留 YAML frontmatter（description / mode / model）
  3. 保留 CHARTER_CHECK 字段
  4. 全员红线逐字一致
  5. 模型分配以 opencode.json 的 agent 字段为准

Skill 包变更

修改 .opencode/skills/*/SKILL.md 时必须：

  1. 保留 "Use when" 描述和「不要触发」节
  2. 步骤工作流编号连续
  3. 项目规范参考节保持一致的格式

脚本变更

修改 scripts/*.mjs 后必须：

  1. 运行 node scripts/verify.mjs . 验证自身
  2. 如果修改了 gate 规则，必须更新 docs/architecture.md 的验证体系描述
  3. 如果修改了 event 结构，必须更新 PRD.md 和 milestones.md

配置变更

修改 opencode.json 后必须：

  1. 验证 JSON 格式（node -e "JSON.parse(...)"）
  2. 同步更新 README.md 和 architecture.md 中对应的描述

来源：docs/governance.md

审查

审查流程

从开发提交 PR 到合并的完整审查链：

  1. 提交 PR — 开发提交 PR，CODEOWNERS 自动请求评审
  2. 自审清单确认 — 提交人对照自审清单逐项确认
  3. 机械检查 — verify.mjs 执行机械检查
  4. 语义复核 — chi judge 以 fresh-context 做语义复核
  5. 裁决 — PASS 则合并；FAIL / REGRESSED 则修复后重新提交；BLOCKED 则停止并汇报卡住
审查裁决：PASS = 合并；FAIL / REGRESSED = 修复后重新提交；BLOCKED = 停止，汇报卡住。

审查标准

标准检查项
机械验证verify.mjs 5 项全 PASS，退出码 0
红线遵守7 条全员红线无一违反
一致性agent 定义中全员红线逐字一致
完整性frontmatter / CHARTER_CHECK / 项目规范参考节完整
无回归相比上一版本无 REGRESSED

合并策略

  • 默认 squash merge
  • 合并后删除分支
  • 禁止 force push

来源：docs/governance.md · .github/CODEOWNERS

发布策略

版本策略

遵循 语义化版本 2.0.0：

版本类型触发条件
MAJOR不兼容变更（如角色变更、协议变更）
MINOR向后兼容的新功能（如新增 skill、新增命令）
PATCH向后兼容的修复（如 bugfix、文档修正）

发布流程

  1. 确认所有里程碑验收通过
  2. 运行 npm run release <type> 执行 SemVer bump + CHANGELOG + git tag
  3. 推送 tag 到 GitHub
  4. 在 GitHub Release 页面填写发布说明
  5. 更新 README.md 中的里程碑状态

发布检查清单

  • node scripts/verify.mjs . 全部 PASS
  • CHANGELOG.md 已更新
  • README.md 里程碑状态已更新
  • LICENSE 文件存在
  • .github/ 模板文件完整

来源：docs/governance.md

安全与合规

安全基线

  • .env 文件不得提交到版本控制
  • API key / 个人信息不得出现在任何文档或代码中
  • 内网数据源（元搜索聚合）仅限 局域网网段（不对外公开） 内网访问
  • 依赖安装限定在 .opencode/node_modules/，不污染根目录
  • 安全漏洞报告见 SECURITY.md

漏洞报告

  • GitHub Issue — 提交一个标记为 security 的 Issue，描述漏洞细节
  • 邮件 — 发送漏洞详情至 [email protected]
  • 响应承诺 — 72 小时内响应报告
阶段时间动作
确认24h 内确认收到报告，评估严重程度
复现48h 内本地复现漏洞，定位根因
修复72h 内提交修复 PR，回关 Issue
披露修复后公开披露漏洞细节与修复方案

依赖安全

  • .opencode/node_modules/ 本地安装，不共享根目录
  • 根目录 package.json 仅作 npm 发布载体，不含运行时依赖
  • 升级依赖前请核查 npm audit 结果

来源：docs/governance.md · SECURITY.md

社区参与

Issue 管理

  • Bug 报告使用 bug_report.md 模板
  • 功能建议使用 feature_request.md 模板
  • 每个 issue 必须指定对应的角色（men / si / ji / chi / yi / xun）

PR 管理

  • 遵循 CONTRIBUTING.md（分支命名 dev-/write-/fix-/chore-，Conventional Commits）
  • 必须通过 CODEOWNERS 自动评审流程
  • 必须通过 verify.mjs 机械检查

行为准则

  • 见 CODE_OF_CONDUCT.md
  • 尊重、包容、协作
  • 禁止骚扰、歧视、人身攻击

文档维护

文档更新时机负责人
README.md每次发布men
CHANGELOG.md每次提交后合并前men
docs/PRD.md里程碑变更men
docs/architecture.md架构决策变更men
docs/guide/quickstart.md安装/命令变更si
docs/guide/milestones.md里程碑验收men
docs/governance.md治理规则变更men
SECURITY.md安全策略变更men
CONTRIBUTING.md贡献流程变更men

更新原则：文档与代码同步提交，禁止「代码先合、文档后补」；所有文档遵循第 7 条红线（粗体关键信息、列表优先、单段 ≤6 行）；治理规则有冲突时，以文档版本号最新者为准，并在 CHANGELOG.md 记录变更。

来源：docs/governance.md · docs/governance.md · CONTRIBUTING.md · CODE_OF_CONDUCT.md

参见