# Flyto Agent - 项目宪法

> 所有贡献者(人类和 AI)都必须遵守这些原则.违反宪法的 PR 不予合并.

---

## 第一条:反向思维原则

**任何设计决策,在确认之前,必须先从反面论证一次.**

具体做法:
1. 提出方案
2. 列出至少 3 个反对理由
3. 如果反对理由站得住脚,修改方案
4. 如果反对理由不成立,记录为什么不成立

> 案例:FileEdit 的 validate+execute 合并提案.正面看"消除 TOCTOU,减少 IO".
> 反面看"丧失快速失败 UX,丧失用户修改窗口,丧失 Hook 时机".
> 结论:保持两步设计.反面理由更有说服力.

---

## 第二条:三层防御原则

**对每一个和模型交互的地方,都必须准备三层防御.**

```
指令层：在 prompt 中告诉模型应该怎么做
参数层：在 API 参数中限制模型能做什么
兜底层：在代码中处理模型没有遵守指令的情况
```

> 永远不要信任模型会 100% 遵守指令.1% 的违规 × 1000 次调用 = 10 次故障.

---

## 第三条:精妙与操蛋注释原则

**所有非显而易见的设计,必须标注注释.**

格式:
- `// 精妙之处(CLEVER): 说明` - 非显而易见的巧妙设计
- `// 历史包袱(LEGACY): 说明` - 不得已的技术债,附带改进方向

规则:
- 每个文件至少审查一次是否有需要标注的地方
- 操蛋之处不丢人,不标注才丢人
- 新代码和旧代码同等对待

---

## 第四条:零硬编码原则

**业务逻辑中不允许硬编码模型 ID,文件路径,或平台假设.**

- 模型 ID → 通过 ModelRegistry.GetRole(role) 获取
- 文件路径 → 通过配置或运行时计算
- 平台特性 → 通过 build tags 或运行时检测
- 行业假设 → 通过 FLYTO.md 和技能系统注入,不硬编码进核心

---

## 第五条:测试即文档原则

**每个功能必须有对应的测试.测试名就是功能规格.**

命名规范:
```go
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 合并提案的反向思考教训中总结 |