文件即接口
文件即接口（File as Interface）是一种智能体（Agent）工程范式：把任务状态、需求说明、规则、记忆、工具文档等原本容易塞进系统提示词（System Prompt）或专用工程框架（Harness）组件里的信息，显式写入普通文件；智能体通过读取、编辑、追加这些文件来恢复上下文、协调任务和传递结果，而不是依赖常驻上下文或黑箱机制。
它的核心不是“让人手写文件”，而是把文件设计成智能体（Agent）可以按需访问、按需更新、可被版本控制（Version Control）追踪的接口契约（Interface Contract）。
一句话定义
文件即接口（File as Interface）：把文件当作智能体（Agent）之间、智能体与人之间、智能体与工具之间的稳定通信界面；状态不在模型上下文里漂移，而是在文件系统中显式存在。
核心思想
1. 文件是持久化状态，不是附属产物
传统工程框架（Harness）常把任务列表、计划、规则、记忆等做成内置功能；文件即接口（File as Interface）则把这些状态物化（State Materialization）到文件中，例如：
TODO.md ← 任务状态
PLAN.md ← 当前计划
TASKS.md ← 跨会话任务图
RULES.md ← 项目规则
MEMORY.md ← 长期记忆
LOG.md ← 过程记录
README.md ← 工具或子任务说明这样，智能体（Agent）不需要把所有状态都背在上下文窗口（Context Window）里。需要时读取，更新后写回；不需要时，它们不占用上下文。
2. 文件是按需加载的上下文
文件即接口（File as Interface）与渐进式公开（Progressive Disclosure）一致：只在需要时把相关信息暴露给语言模型（Language Model, LLM）。
对比两种做法：
| 做法 | 上下文成本 | 可观察性 | 灵活性 |
|---|---|---|---|
| 把规则、计划、任务常驻在系统提示词（System Prompt）中 | 固定成本，随内容增长持续消耗令牌（Token） | 模型可见，但人不一定容易追踪变化 | 由工程框架（Harness）定义 |
| 把规则、计划、任务写入文件 | 按需读取，用完即离开上下文 | 文件可见、可编辑、可 diff（差异比较，Diff） | 智能体（Agent）可自定义结构 |
因此，大型项目中，文件方案往往比“把所有状态常驻上下文”更省上下文。
3. 文件是低损耗通信介质
在子代理（Subagent）场景中，如果主智能体（Agent）把完整需求压缩成一段摘要再传给子代理（Subagent），信息会缩水。文件即接口（File as Interface）的替代方案是：主智能体（Agent）把完整需求写入文件，要求子代理（Subagent）启动后先读取这个文件。
这拆掉了“中间转述层”：
原始需求文件 → 子代理（Subagent）读取 → 子代理（Subagent）执行相比：
原始需求 → 主智能体（Agent）摘要 → 子代理（Subagent）执行文件方案减少了一次人工或模型转述带来的信息损失。
4. 文件是共享真相源
在跨会话任务和多方协作中，文件可以成为共享真相源（Single Source of Truth, SSOT）。例如任务系统（Task System）把任务标题、状态、依赖、负责人和结果写入 TASKS.md 或 JSON 文件；多个智能体（Agent）读取同一份文件，就能知道当前进度、阻塞关系和可执行任务。
这使任务状态从某个智能体（Agent）的私有上下文，变成团队共享、可查询、可恢复、可审计的状态。
典型模式
TODO.md：替代内置 TodoWrite
TODO.md 用来记录任务列表、状态和完成标记。智能体（Agent）在需要规划或回顾时读取它，在执行过程中更新它。
与内置 TodoWrite 相比：
| 维度 | 内置 TodoWrite | 文件即接口（File as Interface） |
|---|---|---|
| 触发方式 | 工程框架（Harness）强制模型调用 | 智能体（Agent）按需读写文件 |
| 上下文成本 | 常驻或半常驻，占用上下文 | 按需读取 |
| 可观察性 | 取决于工具界面 | 文件直接可见，可用版本控制（Version Control）追踪 |
| 适用模型 | 中等或较弱模型，需要外部约束 | 强模型，能自主决定何时规划 |
PLAN.md：跨会话计划
PLAN.md 保存目标、方法、当前步骤和下一步。它解决的是会话重启后智能体（Agent）不知道“上次做到哪了”的问题。
TASKS.md：跨 Agent 任务图
TASKS.md 或 JSON 任务文件可以表达有向无环图（Directed Acyclic Graph, DAG）：任务之间不只是线性顺序，还可以有依赖关系。
示例：
[数据库迁移]
│
┌───┴────┐
[认证重构] [API 更新]
└───┬────┘
│
[集成测试]这种结构适合多智能体（Agent Team）协作：每个智能体（Agent）读取任务文件，判断自己可以认领哪个任务。
README.md：按需加载的工具说明
对命令行工具（Command Line Tool）或命令行接口（Command Line Interface, CLI），可以把使用说明写成 README.md。智能体（Agent）需要使用时再读取说明，而不是把所有工具定义一次性塞进上下文。
这与模型上下文协议（Model Context Protocol, MCP）工具膨胀问题形成对比：MCP 服务器可能一次性暴露大量工具描述，而 README + CLI 方案只在需要时披露信息。
为什么有效
持久性（Persistence）
文件存在于磁盘上，不随会话结束而消失。智能体（Agent）下次启动时，可以从文件恢复任务、计划、规则和记忆。
可观察性（Observability）
文件内容可以直接被人阅读、编辑和审查。相比黑箱记忆或不可见子代理（Subagent），文件让中间状态显式化。
可组合性（Composability）
文件可以被 read、edit、write、bash 等基础工具操作，也可以被版本控制（Version Control）系统管理。多个流程可以围绕同一批文件组合起来。
上下文经济性（Context Economy）
文件不会默认占用上下文窗口（Context Window）。只有当智能体（Agent）主动读取时，相关内容才进入上下文。
协作友好性（Collaboration Friendliness）
文件可以被多个智能体（Agent）或人与智能体（Agent）共同编辑。差异比较（Diff）可以显示状态如何变化，便于审计和恢复。
边界与风险
1. 文件也需要被正确维护
文件即接口（File as Interface）不是“随便写个文件就自动变好”。如果文件格式混乱、状态过期、命名不一致，智能体（Agent）仍可能误解。
2. 并发写入可能冲突
多个智能体（Agent）同时写同一份文件时，可能出现竞态条件（Race Condition）。这时需要工作区隔离（Worktree Isolation）、任务认领机制或乐观并发控制（Optimistic Concurrency Control）等策略。
3. 强约束场景仍需工程框架（Harness）
对较弱模型，或安全、权限、审计要求很高的场景，仅靠文件约定可能不够。此时仍需要工程框架（Harness）提供权限检查、Hook、工具调度、错误恢复等能力。
4. 文件是接口，不是业务逻辑本身
文件即接口（File as Interface）强调把“约定”外显化，但真正执行仍依赖智能体（Agent）和工具。文件不能替代推理、验证和测试。
与相关概念的关系
- Agent：文件即接口（File as Interface）是智能体（Agent）工程中的上下文与状态管理策略。
- Harness工程：它是“少内置功能、多基础工具”的极简工程框架（Harness）思路。
- 上下文工程：它通过按需读取文件来减少常驻上下文，提升上下文窗口（Context Window）利用率。
- Subagent：它用需求文件替代主智能体（Agent）的转述摘要，降低信息损耗。
- MCP 模型上下文协议：它是另一种接口思路；MCP 通过协议暴露工具，文件即接口（File as Interface）通过 README + CLI + 文件状态暴露能力。
- Agent Skill：技能可以以文件形式保存，使用时再加载，避免一次性占用上下文。
- 任务系统（Task System）：是文件即接口（File as Interface）在跨会话任务管理中的系统化版本。
代表案例
Mario Zechner 的 pi 编程智能体
Mario Zechner 的 pi-coding-agent最小化设计 只给智能体（Agent）最基础的工具：读取文件、编辑文件、写入文件、执行命令。它不内置 TodoWrite、Plan Mode 或模型上下文协议（Model Context Protocol, MCP），而是鼓励用 TODO.md、PLAN.md、工具 README 等文件解决问题。
原文关键表述：
“If you need task tracking, make it externally stateful by writing to a file.”
“The agent can read and update this file as needed. Using checkboxes keeps track of what’s done and what remains. Simple, visible, and under your control.”
“Unlike ephemeral planning modes that only exist within a session, file-based plans can be shared across sessions, and can be versioned with your code.”
“The agent reads the README when it needs the tool, pays the token cost only when necessary (progressive disclosure), and can use bash to invoke the tool.”
learn-claude-code 的任务系统
shareAI-lab 的 s12 Task System 把任务状态持久化到磁盘，格言是“大目标拆成小任务，排好序，持久化”。它把任务文件变成跨会话、跨智能体（Agent）的共享真相源（Single Source of Truth, SSOT）。
Agent 知识 对这一点的总结是：
“任务状态不应该被锁在任何一个 Agent 的上下文里，它应该是一个所有人都能读、能写、能用 git diff 追踪变更的文件。”
设计原则
- 状态外显：需要被记住、共享或审计的信息，优先写成文件。
- 按需读取：不要让所有规则、计划和任务常驻上下文。
- 格式稳定：文件结构要简单、可预测，便于智能体（Agent）读写。
- 可版本化：重要状态文件应纳入版本控制（Version Control），保留变更历史。
- 人与模型共编辑：文件应同时适合人阅读和智能体（Agent）更新。
- 只约定接口，不替模型思考：文件提供边界和状态，不替智能体（Agent）做所有判断。
- 必要处加 Harness：安全、权限、并发和错误恢复不能完全依赖文件约定。
适用场景
- 大型项目任务管理
- 跨会话持续工作
- 多智能体（Agent Team）协作
- 子代理（Subagent）需求传递
- 工具说明与渐进式公开（Progressive Disclosure）
- 个人知识库与长期记忆
- 人与智能体（Agent）共同维护项目规范
不适用场景
- 需要强权限隔离的安全敏感流程
- 高并发写入且没有冲突处理机制的任务
- 模型能力不足、无法自觉维护文件状态的场景
- 必须实时同步、低延迟协调的系统
相关引用
“文件即接口”不是把文件当成存储终点，而是把文件当成智能体（Agent）可以读、写、共享和审计的通信界面。
“最好的约束不是外部强制，而是让模型自己选择约束自己。”
“让 Agent 的状态和普通文件一视同仁。”