KongFangXun/sofagent

简体中文 | English
目录
- 这是什么
- 该不该装？
- 核心特性
- 什么是 FDE Harness
- 多平台挂载
- v1.6.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 仓库，密钥泄漏当场拦截）。
> 💡 只要审计 CLI、不想拉全量依赖树？改装裸名总包：npm i -g 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.6.0 已发版（2026-10-15）；npm 可安装最新版 @sofagent/audit@1.6.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 治理维度 |
核心特性
> ### 万物皆可 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 可离线复算链完整性，结论能被第三方复核