soma-governance Skill 技能

技能简介

Soma（PyPI 包名 soma-governance）是一套让 AI 编程 Agent 变得可信的治理框架，提供可观测、可追溯的治理能力：基于证据的规则选择、AST 分析工具与自适应规则生命周期管理。它的出发点是：无人治理的 Agent 会把大量 Token 浪费在循环返工、幻觉 API 与错误假设上；静态规则文件（.cursorrules、CLAUDE.md）有帮助但不会自适应，Agent 也可以直接忽略它。Soma 用即时上下文注入、自适应规则生命周期与 pre-commit 强制钩子来减少浪费——停止证明自身价值的规则会过期，持续证明的规则会被晋升，与证据不符的声明会被抓住。

核心能力

• 18 条核心规则 + 15 个 Agent 技能 + 61 个自动化脚本：开箱即用的治理资产库，覆盖扫描、分级、覆盖率与适应度评估。
• 自适应规则生命周期：规则按 Wilson 界适应度区间打分，失去价值即过期、持续有效即晋升，共 5 种自适应规则类型。
• 三层 MCP 工具体系：默认暴露 6 个读工具（scan、list_cells、grade、coverage、fitness 等）与 3 个写工具，另有 6 个执行工具需显式开启。
• 回执（Receipt）式写保护：所有写/执行工具必须先 soma_request_receipt 取得一次性回执，回执 300 秒过期，且绑定会话、工作区、参数与目标文件状态——文件一变就要重新申请。
• 两层验证与确定性仲裁：配合 AST 分析工具对改动做验证，规则「不能自证就失效」。
• 广泛宿主兼容：自动探测 Gemini、Claude Code、Cursor、Copilot，也可作为通用 MCP 服务器接入 AWS Kiro 等任何兼容客户端。
• 本地隐私：数据仅本地处理，附带完整的本地优先数据隐私声明（NOTICE）。

安装配置

1. PyPI 安装：pip install soma-governance（需 Python 3.9+）；或 git clone https://github.com/nseney1/Soma-Governance.git 后 pip install -e .。
2. 初始化治理：soma init --yes 自动探测本机 Agent 宿主并写入治理配置，soma status 查看当前激活状态。
3. 平台安装脚本：bash install/install.sh gemini|claude|copilot|kiro|mcp 指定宿主安装，Gemini 也可用 make install 全局装。
4. MCP 服务器配置：在客户端配置 python3 -m soma_mcp，设置 SOMA_WORKSPACE 指向含 .soma/cells/ 的项目；需要执行工具时再加 SOMA_EXECUTION_ENABLED=1（无需 API Key，模型由宿主提供）。

使用步骤

1. 安装并初始化：pip install soma-governance 后执行 soma init --yes，再用 soma status 确认激活。
2. 接入 MCP：把 soma 写进 Agent 的 mcpServers 配置，SOMA_WORKSPACE 指向被治理项目，重启会话加载。
3. 申请回执：写操作先调用 soma_request_receipt，operation 填目标工具名、arguments 填精确参数（报告结果还需 idempotency_key）。
4. 执行操作：带同一参数加回执调用目标工具完成写入或执行；回执单次有效，状态变了就重新申请。
5. 查看治理状态：用 soma_scan、soma_grade、soma_fitness 查看规则健康度，配合 pre-commit 钩子在提交时强制校验。

适用场景

• 规则文件失效治理：.cursorrules / CLAUDE.md 写了但 Agent 照样违反的团队。
• Token 浪费治理：陷入循环返工、反复幻觉同一 API 的 Agent 会话。
• 规则库长期维护：需要判断哪条规则该留、该升、该删的规则库维护者。
• 多人协作的 Agent 项目：要求改动可验证、可审计、可回溯的工程团队。
• 合规与安全审计：需要对 Agent 写操作施加状态绑定授权的场景。

适用人群

在 Cursor、Claude Code、Gemini 中维护大量规则文件的开发者；为 Agent 行为负责的平台与工程团队；关注 AI 治理、审计与合规的技术管理者。

工作原理

Soma 在项目内维护 .soma/cells/ 治理单元，把规则建模为可演化的「细胞」：每次会话通过 MCP 读工具扫描与分级，用 AST 分析工具收集规则是否真正被遵守、是否带来收益的证据，再按 Wilson 界适应度区间给规则打分——有证据支撑的晋升，停止自证的过期。写与执行类操作走回执流程：先申请、再携带一次性回执执行，回执绑定精确参数、目标文件与治理单元状态，任何变动都会使旧回执作废，从而保证每次写入都是被授权且可追溯的。整体数据留在本地，宿主 Agent 提供模型推理。

官方链接

• PyPI 主页：https://pypi.org/project/soma-governance/
• GitHub 仓库：https://github.com/nseney1/Soma-Governance
• 项目文档：https://github.com/nseney1/Soma-Governance/tree/main/docs