Flyto Agent - 项目宪法¶
所有贡献者(人类和 AI)都必须遵守这些原则.违反宪法的 PR 不予合并.
第一条:反向思维原则¶
任何设计决策,在确认之前,必须先从反面论证一次.
具体做法: 1. 提出方案 2. 列出至少 3 个反对理由 3. 如果反对理由站得住脚,修改方案 4. 如果反对理由不成立,记录为什么不成立
案例:FileEdit 的 validate+execute 合并提案.正面看"消除 TOCTOU,减少 IO". 反面看"丧失快速失败 UX,丧失用户修改窗口,丧失 Hook 时机". 结论:保持两步设计.反面理由更有说服力.
第二条:三层防御原则¶
对每一个和模型交互的地方,都必须准备三层防御.
永远不要信任模型会 100% 遵守指令.1% 的违规 × 1000 次调用 = 10 次故障.
第三条:精妙与操蛋注释原则¶
所有非显而易见的设计,必须标注注释.
格式:
- // 精妙之处(CLEVER): 说明 - 非显而易见的巧妙设计
- // 历史包袱(LEGACY): 说明 - 不得已的技术债,附带改进方向
规则: - 每个文件至少审查一次是否有需要标注的地方 - 操蛋之处不丢人,不标注才丢人 - 新代码和旧代码同等对待
第四条:零硬编码原则¶
业务逻辑中不允许硬编码模型 ID,文件路径,或平台假设.
- 模型 ID → 通过 ModelRegistry.GetRole(role) 获取
- 文件路径 → 通过配置或运行时计算
- 平台特性 → 通过 build tags 或运行时检测
- 行业假设 → 通过 FLYTO.md 和技能系统注入,不硬编码进核心
第五条:测试即文档原则¶
每个功能必须有对应的测试.测试名就是功能规格.
命名规范:
func TestBashAST_HeredocWithDashStripsTabs(t *testing.T) // 清晰表达意图
func TestPermission_CompoundCommand_50SubcommandLimit(t *testing.T)
func TestCompact_CircuitBreaker_StopsAfter3Failures(t *testing.T)
测试风格: - 用 table-driven tests 覆盖多种输入 - 用 t.TempDir() 而不是手动清理 - 不 mock 外部 API(跳过需要网络的测试)
第六条:模块化边界原则¶
包之间通过接口通信,禁止循环依赖.
层次规则:
cmd/ → 只依赖 pkg/ 和 internal/
pkg/engine/ → 可以依赖 pkg/ 的其他包和 internal/
pkg/tools/ → 只依赖 pkg/tools/tool.go 的接口
pkg/其他/ → 互相不直接依赖
internal/ → 不依赖 pkg/（可以被 pkg/ 依赖）
第七条:跨行业通用原则¶
核心引擎不假设任何特定行业.
- 编程相关的内容(Git 操作,代码搜索)通过工具和技能提供,不写进引擎核心
- 系统提示词的行业部分通过 FLYTO.md 注入
- MCP 服务器连接任何行业的后端
- 权限规则的格式(prefix/glob/domain)是行业无关的
第八条:零外部依赖原则¶
不引入 Go 标准库以外的依赖.
原因: - 供应链安全(本项目就是因为供应链问题诞生的) - 编译速度 - 可审计性 - 减少升级维护负担
例外:如果标准库确实无法满足(如特定的加密算法),需要团队讨论并记录决策.
修订历史¶
| 日期 | 修订 | 原因 |
|---|---|---|
| 2026-04-02 | 初版 | 从 FileEdit 合并提案的反向思考教训中总结 |