【免费下载链接】super-simple-software-factoryRepeatable agents-plus-code workflows, packaged as one skill, stamped into any repo. Deterministic Python owns the graph; coding agents are bounded nodes inside it.项目地址https://gitcode.com/gh_mirrors/su/super-simple-software-factory点击查看免费下载Super Simple Software Factory简称 SSSF是一个可复用的 Agent 加代码工作流工厂本文聚焦它的两大核心机制——Envelope信封和Gate门禁讲清楚类型化 JSON 如何让多个 AI Agent 之间的上下文无缝交接整条流水线既确定性又可观测。读完你会明白为什么把控制平面从 prompt 挪到 Python 代码里多 Agent 协作才跑得稳。为什么 Agent 上下文交接总是掉链子先看看没有 SSSF 时的窘境把一个完整开发流程交给一个大模型你会得到一台没有接缝的机器——️ 没有阶段边界说不出哪一步失败了❓ 没有可命名的验收标准做完只意味着 Agent 停止说话 重试等于冷启动Agent 刚才学到的东西全部丢掉 唯一的记录是一长段对话读起来像写小说。SSSF 的解法是一句话代码拥有流程编排、重试与验收Agent 只负责单个有界阶段内的工作。而信封Envelope就是上下文跨越阶段边界时唯一允许走的门——Context transfers in code, not in conversation上下文靠代码传递而不是靠对话传递。信封机制Agent 只有两个输出通道在 SSSF 中每个 Agent 的输出被严格限定为两种没有第三种引用文件写入本次会话的context_handoff/目录计划、笔记、产物一条最终的有效 JSON 响应也就是信封本体除此之外不带任何内容。所有信封类型都继承自 data_types.py 中的EnvelopeBase它只有四个字段class EnvelopeBase(BaseModel): status: Literal[success, fail] # 唯一必填字段 summary: str # 一句话发生了什么 artifacts: list[str] [] # 写出的产物路径 notes_for_next_agent: str # 下一个 Agent 必须知道的事这里有几个精妙的设计点status字段是承重墙。JSON 能解析、但statusfail的信封会直接抛出异常、让阶段失败——Agent 自己声明失败就不可能是成功阶段。信封是声明清单而非自由文本。以 BuildOutput 为例changed_files声明改了哪些文件、commit_message留给 git 提交阶段消费、notes_for_next_agent写给下游。下一位 Agent 拿到的不是模糊的上一步大概干了什么而是结构化的、可核对的事实。同一份合同写在三个地方data_types.py里的类型定义、该 Agent 的user.md中## Report段的 JSON 示例、以及调用处的output_type参数。改一处必须同一笔提交里改齐三处否则会白白烧掉纠错轮次。开箱即用的信封类型一览定义见 data_types.py信封类型归属 Agent关键字段PlanOutputplanner计划 提交信息BuildOutputbuilderchanged_files、commit_messageScoutOutputscoutfindings文件 说明ReviewOutputreviewerapproved、findings、blockingDocumentOutputdocumenterdocument_path、documented_files还有一个反直觉的细节代码块的结果也会被包装成信封VerifyOutput、ChangesOutput。测试跑挂了的报错会以和 Agent 报告完全相同的门流回 builder——下游 Agent 根本分不清信封来自模型还是来自代码。这正是代码拥有流程的具体体现。门禁机制验证声明从不预测Agent 说完我改了这些文件、测试都过了该信吗SSSF 的 Gate门禁给出的答案是事后拿事实对账。一个门禁就是一个函数签名固定为gate(envelope, run) - GateReport每检查一项就调用一次report.check(item, ok, note)。绿色门禁会告诉你它验证了什么而不只是通过了。内置门禁都在 gates.py 中门禁验证什么artifacts_exist声明的产物文件真实存在附文件大小作证据files_non_empty产物不是 0 字节空文件json_parses声明的 JSON 产物真的能解析diff_matches_claims声明改过的文件确实在磁盘上tests_pass(command)指定命令以 exit 0 结束失败时保留输出尾部 1000 字符作证据verdict_consistent评审结论自洽approvedtrue却带着 blocking 项当场驳回注意门禁的哲学边界它只验证机械上可验证的声明不评判计划质量或代码品味——那是 reviewer Agent 的工作。门禁的每个失败项会精确地拼成一句你哪里说错了直接发回给 Agent下一节讲它怎么发。出错怎么办同会话纠正拒绝冷重启这是信封 门禁组合里最省钱的一环。两种失败场景JSON 解析失败harness 不会重启 Agent而是在同一个会话里补发一条纠正消息列明缺失的字段和错误原因最多重试JSON_FIX_ATTEMPTS 2次见 agents.py门禁返回违规走完全相同的机制纠正消息里写明哪条 check 失败、证据是什么重试次数受阶段retries约束。为什么坚持同会话纠正因为冷重启会把产生差一点就对的那份上下文全部扔掉——Agent 忘了自己刚才为什么那样写。纠正只花一条消息的成本上下文窗口完好无损。pi 把--session-id当作 create-or-continue运行 Agent和继续 Agent本来就是同一个调用。每次尝试包括失败的都会被持久化为一条 envelope 记录所以你可以在追溯数据库里看到完整的纠错轨迹而不是只知道最终成功了。信封落在哪里会话目录与追溯链路session.ensure(cfg, adw_id)会为每次运行创建固定目录布局详见 handoff.mdadws/adw_data/sessions/{adw_id}/ ├── agent_map.json # Agent → 会话ID 模型 ├── context_handoff/ # 所有 Agent 共享的交接文件区 └── {agent_name}/ ├── prompts/ # 实际发出的提示词执行前存档 ├── raw_output.jsonl # Agent 原始输出流实时追加 └── envelope.json # 最终有效JSON由代码捕获、校验并持久化信封的生命周期是一条单向链路Agent 产出 → 代码按声明类型解析 → 落盘envelope.json→ 写入 SQLite 追溯库的envelopes表 → 注入下一个 Agent 的 user prompt通过 prompts.py 的{{previous_envelope}}占位符替换。每一步都有据可查文件是原始记录数据库是可查询镜像——数据库丢了也丢不了任何无法重建的东西。上手速查要改什么去哪里改需求改哪里调整信封字段加一个必填项data_types.py 的对应 Output 类 user.md的## Report示例 调用处output_type三处同改新增一条验收门禁gates.py写一个report.check(...)循环 一个 return看懂完整的交接契约references/handoff.md信封 schema、双通道规则、会话目录理解纠错与重试实现agents.py 的JSON_FIX_ATTEMPTS与解析重试配置 Agent 花名册templates/sssf.config.yaml查看运行中的信封事件追溯 UIapps/visualizer/只读界面总结Agent 提议代码拍板信封与门禁看似只是两个 JSON 类和一个校验函数它们共同解决的是多 Agent 协作的根本问题——上下文交接不再依赖对话的默契而是依赖代码的契约 信封让每个阶段的产出变成结构化、可验证、可注入下游的事实 门禁让完成有了机械定义不是 Agent 说不说了而是声明与事实对上了 同会话纠正让失败变得廉价上下文窗口是最大的资产绝不轻易丢弃 一切事件实时入 SQLite第 1000 次运行和第 1 次长一个样。想进一步动手把技能目录 .claude/skills/sssf/ 盖进你的仓库运行一次adw_plan_build之类的短链然后打开追溯库看看信封是怎么在 Agent 之间流转的——亲眼看一次胜过读十遍文档。赞分享【免费下载链接】super-simple-software-factoryRepeatable agents-plus-code workflows, packaged as one skill, stamped into any repo. Deterministic Python owns the graph; coding agents are bounded nodes inside it.项目地址https://gitcode.com/gh_mirrors/su/super-simple-software-factory点击查看免费下载相关推荐Super Simple Software Factory Agent团队详解5个Agent分工与一份YAML配置全拆解Super Simple Software Factory Agent团队详解5个Agent分工与一份YAML配置全拆解 Super Simple Softw如何快速用浏览器接入 OpenHands Software Agent SDKTypeScript 客户端完整指南如何快速用浏览器接入 OpenHands Software Agent SDKTypeScript 客户端完整指南 OpenHands Software AgACP完整指南如何实现AI Agent间的无缝通信ACP完整指南如何实现AI Agent间的无缝通信 在当今快速发展的AI领域ACPAgent Communication Protocol作为实现AI上一篇快速掌握 Go 表达式语言Expr 完整使用指南下一篇SkillHub 开发工作流实战指南本地开发、测试、Staging 验证与并行 Agent 协作全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考