sofagent

sofagent

目录

• 这是什么
• 该不该装？
• 核心特性
• 什么是 FDE Harness
• 多平台挂载
• v1.7.0：判定底座 · 阶段二（模型与校准）
• FDE Harness 两阶段
• 安装
• 使用
• 常见问题
• 生态与文档索引

这是什么

💬 一句话版本：进场时它替你把业务摸清、写成文件；离场后你的数字员工每次改代码、动文件，都按文件过一道安检、留一份记录、存一个快照——出事能查、能回滚。

🏢 组织视角（点开）

AI 落地卡点已从「模型够不够聪明」迁到「组织敢不敢接」——能不能进组织架构、有没有账号、绩效怎么算、做错了怎么退。sofagent 是给数字员工办入职的制度：进场把岗位职责写成文件，离场按文件做绩效考核（每次变更留证据）、组织记忆（沉淀机制随使用迭代，边界见 LIMITATIONS）、试错容错（做错退得回）。给 AI 发工号前，先装 sofagent。

🧩 三因子口径（点开，术语见〈什么是 FDE Harness〉）

sofagent 是自带 Harness 的 FDE 交付物治理层——工程层（FDEing）与治理层（harness）已交付，判定层（S1M，把判定从生成里分出来的决策模型）排期 v1.6.0–v1.9.0 建设、v2.0.0 宣告。三层各司其职、不互替。

身份公式定稿 FDEing × S1A（S1A = S1M + Harness），口径 SSOT = PHILOSOPHY · 身份口径。

开源 FDE Harness 层（Harness = 「缰绳」，套住 Agent 的治理层；FDE = Forward Deployed Engineer 前线部署工程师，详见〈什么是 FDE Harness〉）——嵌在成熟 Agent（DSH / OpenClaw / WorkBuddy）与模型层之间做治理：进场把业务判断写成文件（工作流/本体数据/AI 节点），离场按文件审计每次变更。约束层五种能力（注入·审计·回溯·沉淀·进化），五种形态分发（FDE 插件 / Skill / MCP / CLI / Dashboard）。 sofagent 不造 Agent——交付的是让任何 Agent 被管住的那一层（管住强度按宿主分档：DSH/OpenClaw 硬注入可拦截，其余档位为建议性注入 + git hook 审计兜底——见〈多平台挂载〉档位表）。

零配置审计实拍：一行命令审计最近一次 commit，密钥泄漏当场拦截（现为 sofagent audit）

🗺️ 系统架构总览（FDE Harness 五模块编制）

约束 Agent 行为 · 审计每次变更 · 沉淀经验（五模块编制：治理模块 v1.5.0 已发版 · 执行模块 v1.5.4/v1.5.5 已发版；完整交互版见 ARCHITECTURE）

30 秒–2 分钟轻量试用（首次含 npx 拉包（网络依赖），复跑秒级；单次引擎审计约 1.1 秒，口径见下）：npx -y -p sofagent sofagent audit（任意 git 仓库，密钥泄漏当场拦截）。

💡 npm 通道只有伞包一个形态：npm i -g sofagent 装的就是完整依赖树（602 包口径见下）——不存在更小的「轻量包」。要更小安装面，用 npx 临时形态（npx -y -p sofagent sofagent audit，用完即弃不常驻；能力面见 LIMITATIONS）。

💡 试用时提交消息请写 ≥6 字符（如 initial audit test）——A19 质量规则（编号对照见 SECURITY 规则清单）对超短消息（init/add）判红属设计意图（防无意义提交信息），不是故障。

五分钟沙箱演示（v1.5.1 已交付；沙箱隔离、真实文件零接触）：npx -y -p sofagent sofagent audit demo——一条命令跑完「沙箱构建 → 注入 → 故意违规 → 审计拦截 → 快照回滚 → HMAC 举证导出」五幕链路（--speed fast 为 60 秒版；产物落 $SOFAGENT_DATA/demo，不触碰被审仓库）。（demo 经 npm 通道提供；install.sh 安装态 CLI 暂无 demo 子命令）

版本说明：v1.7.0 已发版（2026-10-22）；npm 可安装最新版 @sofagent/audit@1.7.0。

该不该装？

如果你是… · 建议 给现有 Agent 加纪律——已有 DSH / OpenClaw / WorkBuddy，想让 AI 干活时守规矩、留痕、出事能回溯 · ✅ 现在装。核心价值就是约束层（注入 · 审计 · 回溯 · 沉淀 · 进化），装完即用 一人公司 / 小企业想落地 AI——没有专职工程师，需要一个"不离职的 FDE"帮你梳理工作流、部署 AI 节点 · ✅ 现在装。FDE Harness 层就是干这个的——进场把判断写成文件，离场按文件执行与审计，全链路 要开箱即用的企业级 Agent 平台——期待完整商业产品（多租户、权限管理、计费、SLA） · ⏸️ 暂缓。sofagent 是 FDE Harness 层，不是平台产品——平台级能力不在本开源仓库范围内。有集成能力的团队仍可把约束层接入自有平台，作为其中的治理模块；纯开箱需求建议另选平台产品 纯研究 / 想看看约束层怎么设计——读代码、学架构、借鉴方法论 · ✅ 现在装。文档齐全（HANDBOOK / ARCHITECTURE / PHILOSOPHY），MIT 协议

和 gitleaks / pre-commit 这类工具什么关系？（互补不互替）

· gitleaks 等扫描器 · pre-commit 等钩子 · sofagent 定位 · 密钥全量历史扫描 · 通用提交钩子框架 · Agent 行为审计约束层 证据面 · 仓库文本模式 · 自定义脚本 · git diff 硬证据 + Agent 日志 + 决策留痕 覆盖维度 · 密钥泄漏 · 任意（自己写） · 28 条规则：密钥/越界/注入/权限/后门/数据产品 部署成本 · 低——单二进制，零运行时依赖 · 低——随语言生态装一个 CLI · 中——企业设备需一次 install.sh 装约束层（也可先用 npx 零配置试用） 维护负担 · 低——规则随上游更新 · 中——自定义脚本需自己维护 · 中——规则与 hook 随本仓升级，但每版需重装 hook 并对齐配置 建议 · 强密钥合规必配 · 已有体系可保留 · 与前两者并用，专注 Agent 治理维度

📌 本表只对比提交时密钥/钩子类工具；同类治理型工具（审计/约束/编排面）的对比见 WIKI 生态节与 VALIDATION 生态定位。

核心特性

### 万物皆可 FDEing（理念）

从 FDE 到 FDEing——万物皆可 FDEing：把 Forward Deployed Engineer（岗位）变成 Forward Deployed Engineering（能力）——岗位随人走，能力随交付物留。FDEing 即其缩写（读 /ef-di-i-ing/，与 engineering 同构）：名词指这种能力，动词指把 FDE 从人力工作变成这种能力。

- FDE 是名词，FDEing 是动词——把 FDE 从一项人力工作变成一种可自动执行的能力（打法 × 判定 × 治理合成）：花更少的人力，提供更多的能力。

- 不限于软件——任何业务对象、流程、节点，都可以被 FDEing 一遍「梳理 → 判定 → 交付 → 养护」；硬件节点、机器人运动过程同样是一条条 workflow，差别在执行器、不在治理形态。

- 它同时是一种思维方式——做任何事之前先想三件：① 这件事的 workflow 怎么搭；② 其中的 AI 节点是什么；③ 怎么让 AI 更好地帮你实现（详见 PHILOSOPHY · 从 FDE 到 FDEing）。

三层各归其位：工程层（FDEing） 进场把判断写成文件，判定层（S1M） 管判断怎么形成、怎么留痕、怎么被举证，治理层（harness） 离场后让判断 7×24 被执行。

工程层 · FDEing（进场 · 生成判断，FDE 相位——把「该不该上 AI、值多少钱」判断出来，冻结成交付物）：

• 🧭 梳理工作流——五要素深挖 + 三问判定法，把每个岗位环节摸清，算清每个 AI 节点值多少钱
• 🤖 部署 AI 节点——三层交付物（文档层 + Skill 层 + 运行层），装进你已有的 AI 工具，从"你干活"变"你派活"
• 📦 判断冻结成交付物——每个节点带「做好标准（merge_criteria）· 谁拍板（approver）」，机器可判定、跨阶段共享

判定层 · S1M（System One Model——判断与生成分离的决策模型；排期 v1.6.0–v1.9.0 施工、v2.0.0 宣告，尚未交付——本版只声明身份与路线，不声称能力实装；口径锚定 S1M-DECISION-POINTS 与 v2.0.0 §一。已交付落点是既有判定与举证面）：

• 🔎 判定留痕——decision-log 因果链记录每个可问责决策（谁拍板、依据什么、为何这么做），供 auto-PR 解释块与 daemon 周报消费
• 🔗 判定可举证——审计历史落 HMAC 链，--verify-chain 可离线复算链完整性，结论能被第三方复核

治理层 · harness（离场 · 驻留判断——「harness 治理」，按交付物 7×24 执行，进化时写回）：

• 🏠 离场后常驻——FDE 能力留下巡检、审计、优化（daemon 巡检需安装时显式确认，默认不装；QUICK_MODE / 非交互安装自动跳过），commit 时触发审计，人离场治理不离开
• 🔍 零配置审计——npx -y -p sofagent sofagent audit，任何 git 仓库秒级审计最近一次 commit（quick 约 1.1s、5 万行 diff 约 6.1s，口径见 HANDBOOK）
• 🧱 规则与安全面：28 条审计规则——密钥泄漏、越界编辑、注入防御、权限红线，违规当场拦截；fail-fast（critical 命中后其余跳过）、默认非 fail-closed（配置可被篡改、hook 可经 --no-verify 跳过——绕过面见 LIMITATIONS §三）
• 🔧 工具与能力面：104 个 MCP tool + 证据分档——28 条规则中 22 条基于 git diff（本地生效、零 token）、4 条 hybrid（diff + Agent 日志）、1 条 filesystem 扫描、1 条走 decision-log（清单见 SECURITY）。其中 commons_invoke 为 dry-run 预检语义（返回能力元数据与调用计划，真实执行由 Agent runtime 注入 executor；见 LIMITATIONS）
• 🛡️ 自动快照回溯——每次审计后自动存档，出事一键回到任意快照
• 🛡️ AgentShield 五类配置面静态扫描——@public SDK 能力（经 createAgentShield 调用），不在 commit hook 链路上，按需接入

什么是 FDE Harness

FDE = Forward Deployed Engineer（前线部署工程师）——把模型塞进企业真实业务里的人。sofagent 把该角色做成开源 FDE Harness 层，嵌在你的 Agent（DSH / OpenClaw / WorkBuddy）与模型层之间。完整工作流分两阶段，中间的交接物把它们缝成一件事：

• 进场 · 生成判断：四步——梳理工作流 → 构建双图谱 → 判定 AI 节点 → 部署。双图谱 = 业务图谱（边界、数据流向，人读）+ 本体图谱（共享语义底座，AI 读）；每个 AI 节点的「做好标准（merge_criteria）· 谁拍板（approver）· 何时跑（trigger）」在此判定并冻结进交付物（workflow.yml + 本体 + skills）。
• 离场 · 驻留判断：FDE 走，判断留下——审计在 commit 等变更事件时按冻结的标准自动触发（证据分档见「核心特性」首条）；daemon 7×24 巡检、快照可回滚、经验持续沉淀。人离场，治理不离开。

🔗 为什么必须一体：交付物是两阶段共享的活状态——进场写入、离场执行时读、进化时写回（试验分支晋升基线、反思蒸馏回流）。没有 FDE，约束层无判据可执行；没有约束层，FDE 的判断随人离场蒸发。「FDE Harness」之名即由此——不是两种功能的拼盘，是同一件事的两阶段。

两个阶段的合成效果——「从 FDE 到 FDEing」——见〈核心特性〉首段理念主线（万物皆可 FDEing）。

为什么是 FDE Harness

• 企业 AI 落地的瓶颈不是模型，是部署——MIT NANDA《生成式人工智能的鸿沟》：95% 企业 GenAI 项目未能产生可写进财务报表的价值，而 FDE 岗位发布量一年涨 729%（核验见 VALIDATION）
• 完整来自组合——DSH 解决「能干活」，sofagent 解决「持续干」，两者合起来才是完整的 FDE Harness（见下一章「多平台挂载」的 DSH 档）
• 约束层「持续优化」靠机制不靠承诺——外部独立实验（ARC-AGI-3，能力型 harness 数据，与治理型约束层的可靠性收益非同一量纲，仅作方向性参考）：同一模型仅优化外层 Harness 即可显著提升任务完成率（核验见 VALIDATION · THANKS）
• 能力可迁移，绝不绑死单一平台——约束层平台无关（可迁移的是约束资产与审计兜底，注入强度仍按宿主分档：DSH/OpenClaw 硬注入，其余建议性注入 + git hook 兜底——见〈多平台挂载〉档位表），方法论跟着业务走、不跟着平台走

🔄 自举：sofagent 给自己做的第一份 FDE，就是 sofagent 自己——项目本身就是一条完整的 FDE 工作流（梳理 → 构建 → 部署 → 离场），这个开源仓库就是那份交付物。

多平台挂载

横跨你已有的 Agent、纵贯模型层，不替代模型，只补可靠执行——FDE Harness 层平台无关（插件 / Skill / MCP / CLI / Dashboard 五种形态按宿主能力分发），方法论跟着业务走，不跟着平台走：

档位 · 平台 · 约束注入 · 挂载方式 深度结合 · DeepSeek Harness · ✅ 逐工具调用可拦 · 6 款原子 cordis-plugin-sofagent-* 挂进运行时（另有 1 款聚合可选）——tools/pre-execute 等 7 个生命周期事件（词汇表见 engine/dsh-plugins/SEAMS.md） 完整挂载 · OpenClaw · ✅ 每会话注入一次 · Hook 注入四层约束 + 断路器 + 4 款 OpenClaw 插件 标准挂载 · Claude Code / Cursor · ⚠️ Skill 自觉加载 · Skill 目录 symlink + 平台规则文件 + 拦截配置（内容为提交级 28 规则，非调用级拦截） 薄挂载 · WorkBuddy / Codex / Gemini CLI / Hermes · ⚠️ Skill 自觉加载 · Skill 目录 symlink（Codex 走 AGENTS.md 挂载点）+ git hook 审计

• 别假设能力对齐——档位差的是注入强度，不是「有没有」：DSH 逐工具调用可拦，OpenClaw 每会话注入一遍，其余宿主靠 Agent 自觉读 Skill 文本。「支持某平台」= 约束资产在该平台可用，≠ 强度与他平台相同；跨宿主迁移前先看目标宿主落在哪档，矩阵见 加载链 HOOK
• 审计兜底平台无关——sofagent audit --install-hook 走 git hook，任何档位每次 commit 都自动审计（默认启用 17 条；完整 28 条需在 .sofagent/config.yml 显式开启 extendedRulesEnabled: true），违规硬拦截。

约束是建议性的，审计是强制性的（强制的边界：默认非 fail-closed，--no-verify 可跳过前两层防线、post-commit 只留痕不阻断——被绕过的 commit 会留痕，详见 LIMITATIONS §三）

一条命令选定挂载档位：bash install.sh --platform （全部平台与差异见 HANDBOOK）

📌 AGENTS.md（Codex）/ GEMINI.md（Gemini CLI）/ .claude/ / .cursor/ 为各宿主的分层挂载点，均为对 SKILL/ 的薄引用。

v1.7.0：判定底座 · 阶段二（模型与校准）

🧪 让概率变得有意义——四阶段判定底座第二版：训练用严格适当评分规则（报真实概率得分优于偏离概率），校准让输出概率可对表读数，纪律门禁让无依据的置信度上不了决策路径：

能力 · 一句话 · 触达方式 RLCD 严格适当评分训练 · 三原语分派损失（noul 对数分数 / choice 对数+球面 / score RPS 序利用）+ 极端口径非对称惩罚 + RLOO/KL 锚/降权三防线；概率目标断言（硬标签拒载）+ 三档加权 + 可复现清单 · CLI：sofagent train rlcd --data [--dryrun] 分桶温度校准 · choice/score/noul 三原语分别拟合 · score 保序 · 独立校准集隔离断言（同判据跨侧拒载，违规拒出读数）· 校准制品纯 JSON 独立于权重 · SDK 面 校准纪律门禁 · 决策路径消费的置信度/概率阈值须带校准依据或显式 uncalibrated——未标注不得上线路（check-calibration-claims 接入发布链） · 门禁 · SDK 面 弃权第四态 · 弃权与 pass/warn/fail 并列（三源留痕：低置信/OOD/判据缺失）· 门槛按原语分档 · ECE 未达阈时弃权不可关 · SDK 面 三态对照与双达阈判定 · 零样本/训练后/校准后并列对照 · 一致率 ≥0.70（中英分列）与 ECE ≤0.10（分原语分语言）两线独立判定，not-measured 不得记达标；实测：ECE 17/18 格达线、一致率未达 ⇒ 阶段三暂缓（如实裁决） · SDK 面 · sofagent audit --criteria 判据列示 CLI 可达

FDE Harness 两阶段

两阶段的分工与不可分性见上文〈什么是 FDE Harness〉——本节补组织侧读法：两阶段合起来就是给数字员工办入职的全流程（离场侧自动动作——daemon 巡检、commit 审计、快照回滚、进化写回交付物，详见〈核心特性〉与〈安装〉）。

组织动作 · sofagent 对应 岗位职责说明书 · 进场冻结的交付物（merge_criteria / approver / trigger） 绩效考核 · 审计留痕 + 治理 KPI 面板（v1.5.0） 组织记忆 · 知识沉淀（think.md 反思 + knowledge/） 培训体系 · 经验→考核→晋级的自进化链（v1.5.8 SDK 面先行；入口与效果边界见 LIMITATIONS） 试错容错 · 快照回滚 + 能力基线版本线（v1.5.9 已交付） 劳动合同边界 · 可拔契约与主干能力清单（v1.5.7 交付；开关面与门控见 ARCHITECTURE）

📚 想深入：FDE/GUIDE（四阶段十二步）· ARCHITECTURE（五能力与模块）· PHILOSOPHY（设计禁区）· FDE/README（Skill 体系）；完整导航见 WIKI。

安装

版本阶段（装前必读）：sofagent 处于阿尔法施工期（v1.x）——功能面快速变动，不承诺接口稳定，跨版本升级前先读 CHANGELOG。自 v2.0.0 起进入贝塔阶段。

对应的 npm 发布通道策略：npm 不做 dist-tag 分道，`latest` 即最新版——npx -y -p sofagent sofagent audit 默认拉到当前最新版本，无需指定标签（版本号承载阶段语义：v1.x 阿尔法施工期 / v2.0.0 起贝塔期）。alpha tag 保留为历史发布痕迹不维护。

⚠️ 企业用户先读 LIMITATIONS §三——config.yml 默认非 fail-closed（规则可被 Agent 篡改绕过），多租户写入侧隔离尚未落地（v0 已交付查询侧隔离：orgId 过滤 + data// 路径地基，见 LIMITATIONS）。

强合规场景建议 CI 兜底 + 文件权限锁（chmod 400 .sofagent/config.yml——辅助层，对同用户进程无效，见 LIMITATIONS §三），不要用单机默认配置直接上生产。

🔐 数据主权：运行时数据不出本机（除安装时 npm 拉包外不联网）；三个 opt-in 出口（云同步 / 模型推理端点 / 云 VM 执行面）需你显式配置（另：dashboard 打开时会匿名只读拉取 GitHub 公开 star 数，无用户数据外发、失败静默降级），详见 SECURITY。

30 秒起，零配置（首次含 npx 拉包约 30 秒，复跑秒级——引擎本体约 1.1s，实测口径见上）——在任何 git 仓库跑一次审计：

npx -y -p sofagent sofagent audit

💡 quick 跑 17 条默认（A1–A11 + A18–A23；其中 A3 任务范围 / A9 commit-msg 注入检测——读最近一次 commit 消息，无消息时按无输入跳过）；--init 的 hook 默认同样 17 条，完整 28 条需在 .sofagent/config.yml 开 extendedRulesEnabled: true——详见 LIMITATIONS §三。

⚠️ 这一步是一次性审计（当次进程内），不装 git hook——之后 commit 不会被自动拦。要长期守护请跑 sofagent audit --init（见下方完整安装）。

拦截特定格式密钥泄漏时是这样的（真实输出；A2（编号对照见 SECURITY 规则清单）检测 AWS AKIA/Secret、OpenAI sk-*、GitHub ghp_、Google AIza、Slack xox*-、JWT、PEM 私钥等已知格式——sk- 形态需 ≥29 字符（主体 ≥27，厂商专属 sk-ant/sk-proj 等 ≥40），Stripe 下划线前缀 ≥24；更短/非标形态暂不覆盖——保守设计防误报，详见 LIMITATIONS §三 A2）：

$ npx -y -p sofagent sofagent audit
🔍 审计首个 commit（4573bb8）——首提交无父基线，对比空树审计全部新增内容。

❌ [sofagent] A2 不泄密钥 [底线]: 检测到疑似密钥/令牌泄漏: app.py: 检测到 AWS Access Key; app.py: 检测到 密钥赋值形态。密钥不应硬编码到源码中。

📊 [sofagent] 1 条违规 · 7 条通过 · ⚠️ 9 条本批未检查（critical 命中后 fail-fast）

首屏实拍图为 A1 场景（.env 敏感文件提交被拦、exit 2）；上为 A2 密钥格式检测实拍（AWS AKIA 形态硬编码被拦——修法：移入 .env 并加入 .gitignore，或改从环境变量/密钥管理服务读取）。

完整安装（Node.js ≥ 18，先下载审查再执行）——装在企业跑 AI 节点的设备上：

curl -fsSL https://raw.githubusercontent.com/KongFangXun/sofagent/refs/tags/v1.7.0/bootstrap.sh -o bootstrap.sh
less bootstrap.sh          # 先看一眼脚本内容，确认安全
bash bootstrap.sh && rm bootstrap.sh

🔒 供应链信任链：tag 钉定 + sha256 校验 + fail-closed + 自锚定哈希重入二次校验（详见 SECURITY.md 远程安装节）；⚠️ 审计日志默认明文落盘——企业部署建议开启静态加密。

sofagent audit --init      # 装 git hook，之后每次 commit 自动审计
sofagent audit --doctor    # 验证环境（可选）

🔧 新装机器首跑 `--doctor` 报「未建立 dist 基线」？ 运行 sofagent audit --doctor --baseline 建立基线（信任锚 = 你此刻确认 dist 可信的时刻——防影子审计器劫持，故不自动记录）。

💡 安装脚本写 ~/.sofagent/（数据）+ ~/.local/bin（CLI）；仅显式传 `--platform ` 时才写该平台集成目录（默认不探测不修改）；npm 权限不足时 CLI fallback 到 /usr/local/bin，其余系统文件零改动。

⚠️ 显式 --platform 会写该平台宿主配置（claude/codex/gemini/workbuddy/cursor 的 settings·AGENTS·GEMINI·mcp.json 及各平台 fde.md；合并写入+自动备份+幂等）。默认不传 `--platform` 零宿主配置写入。--init 装三层防线 hook（pre-commit / commit-msg / post-commit 对账）；

--no-verify 可跳过 pre-commit 与 commit-msg 两层防线；post-commit 事后对账不受影响（git 原生开关不作用于它）——防的是诚实 Agent 疏忽而非恶意绕过，被跳过的 commit 由 post-commit 留痕（提示「疑似绕过」）但不阻断；个人兜底三件：CI 侧 sofagent audit --diff、定期 --doctor、翻审计记录。详见 LIMITATIONS。