workfile

用途

Workfile 是一个仓库原生（repository-native）协议，用于在人类与软件智能体之间协调工作项、文档、历史与持久项目记忆。它的核心理念是“仓库即数据库”：仓库中的 Markdown 文件是权威来源，CLI、HTTP API 和本地 UI 共用同一套核心服务、集合注册表、索引与校验规则，浏览器或数据库中不保留独占状态。

Workfile 记录工作，但不配置智能体。生态中的配置工具（如 gentle-ai）解决的是“你的智能体如何工作”，而 Workfile 解决的是“做了什么、谁持有、依据是什么”，答案就是那些比智能体、会话和软件包本身更长寿的 Markdown 文件。两者可以组合使用。

主要能力

• 仓库为权威：卡片就是拉取请求中的一个文件，可在 diff 中审查，格式错误时由 workfile doctor 报告。删除软件包后记录仍可读。
• 强制认领：所有权在变更时校验，若卡片被其他参与者持有，你的状态转换会被拒绝并返回 CARD_CLAIM_OWNER_MISMATCH，而不是静默接受。
• 证据驱动的完成：review 不等于 done，done 需要来自代码实际运行处的证据，合并本身不算证据。
• 人机同源：UI、渲染后的变更日志和发布说明都直接派生自智能体写入的内容，不存在需要同步的“机器视图”和“人类视图”。
• 刻意缺失：不安装或更新智能体、不提供人格设定、不做模型路由、不维护技能目录；只通过 workfile agents sync 将自身协议同步到智能体已读取的指令文件中，并通过 MCP 暴露所有操作。

使用方式

需要 Node.js 22 或更高版本，可用 npm、pnpm、yarn 或 Bun 调用。

一次性初始化：

pnpm dlx @illodev/workfile init

建议之后将包保留为 devDependency，这样 init 添加到 package.json 的 project* 脚本才能解析（例如 pnpm project 打开 UI，pnpm project:doctor 运行检查）。

wf 是别名而非重命名，两个名称指向同一入口点；在生成或共享的内容中请保留长格式。wf 仅在包安装后才可解析，且注册表中存在无关的 wf，因此 npx wf 可能拉取到他人的工具，而 npx workfile 会直接失败。

项目通过 project.config.mjs 发现，协议文件通常存放在 .project/ 下。配置是一个普通对象，加载器会自行应用 defineProject。

模块

• Work：.project/cards/ 下的受管 Markdown 记录，提供层级、依赖、认领、范围、状态转换、归档、资产和冲突感知写入。
• Docs：合并两个来源而不复制现有文档——从配置的 glob 发现的索引文档（获得确定性的 PATH-* ID，通过协议只读），以及存储在 .project/docs/ 的受管文档（稳定的 DOC-NNNN ID、类型化 frontmatter、修订感知变更）。受管文档递归读取，可按文件夹分组，ID 保持全局顺序。
• History：使用原子变更片段，而非让多个分支或智能体编辑同一个 CHANGELOG.md。发布时消费选定片段，移动到发布目录下并创建规范的 REL-NNNN 记录。
• Memory：一组类型化、原子且生命周期感知的记录，而非单一不断增长的对话记录。

workfile doctor 会检测损坏的本地链接、未解析的关联或取代记录、缺失的范围路径、过期的审查/来源关系、无效生命周期状态、缺失的毕业/取代目标、过期上下文和不完整的事件解决元数据。

索引与搜索

每个模块都通过公共集合注册表将其文件规范化为 ProjectRecord 条目。派生的进程内索引提供加权全文搜索、按稳定记录 ID 查找、跨四个域的出站引用与入站反向链接、卡片来源链接、模块健康/生命周期/新鲜度信号以及模块与集合计数。权威状态始终保留在磁盘上，服务器缓存短暂、可失效且可完全重建。

词法搜索保持确定性和本地化。宿主可以编程方式注入可选的语义提供程序；Workfile 自身从不选择供应商或通过网络发送仓库内容。第一方本地嵌入包 @illodev/workfile-search-local 在设备上运行嵌入（onnxruntime-web、CPU 上的 ONNX、Xenova/multilingual-e5-small 量化），仓库内容不离开本机。首次混合搜索会嵌入所有未缓存的候选记录，在数千条记录的工作区上可能持续数分钟 CPU 时间；提供程序默认将 ONNX 限制为一半核心数，按批持久化以便中断后恢复，并在 stderr 报告进度。

MCP 服务器

Workfile 包含一个本地、无依赖的 MCP 服务器，使用 stdio 上的 UTF-8 换行分隔 JSON-RPC，委托给与 CLI 和 HTTP API 相同的核心服务，同时支持现代（2026-07-28）和旧版（2025-11-25）协议修订，暴露 32 个工具、4 个资源和 3 个提示。--read-only 模式下变更工具完全消失。

无需安装即可指向客户端：

npx @illodev/workfile mcp

mcp 是子命令而非二进制文件。当客户端从工作区以外启动时追加 --root PATH，否则会向上搜索 .project/；追加 --read-only 仅提供读取工具。

对于 Claude Code，同一界面以插件形式提供——MCP 服务器加上 /claim、/card-context、/next 和 /done 命令、一个技能，以及将卡片认领变为可执行护栏的钩子，且不向仓库提交生成文件。

初始化与 CI

初始化器可交互运行或在自动化中确定性运行，检测包管理器、monorepo 文件夹、可能的卡片区域、文档来源、现有智能体环境和 CI 提供程序。试运行会暴露确切的文件系统计划。生成的 project.config.mjs 导出普通对象，因此通过 pnpm dlx 初始化的工作区在本地安装包之前仍可加载。除非显式 --force，否则不覆盖现有文件。.project/.cache/ 被加入 .gitignore，所有规范协议文件保持跟踪。

CI 文件使用相同的受管文件契约，可为 GitHub Actions、GitLab CI 或通用 shell 运行器生成，模板会针对固定的 Workfile 版本运行 workfile doctor 和智能体同步检查。

演示与发布

UI 附带用于静态托管的演示模式（Vercel、GitHub Pages、任何文件服务器）。npm run build:demo 使用内存 API 构建 UI，重放种子工作区快照：所有视图可用，变更在会话内正常，刷新后重置。仓库包含 vercel.json，导入 Vercel 即可零配置部署演示。常规构建会将演示层和快照从包中 tree-shake 掉。

发布通过 CI 使用 npm 可信发布（OIDC），仓库中不存储 npm 令牌。没有预发布通道：每个已发布版本都可通过一次 npm install 获得，v*-rc.* 标签会导致发布失败。

旧版迁移

v1 的 .planning 系统可通过确定性冲突检查进行规划和应用。有效的旧版卡片和资产成为规范的 v2 Work 记录；旧提案、变更日志、学习记录和格式错误的记录保留在 .project/sources/legacy-planning/ 下，而不是被静默地以不兼容方式重新解释。

适用场景

• 多个 AI 智能体并行处理同一仓库中的任务，需要避免编辑冲突。
• 希望工作项、文档、变更历史和项目记忆随代码一起版本化、可审查。
• 需要人机共享同一份权威记录，无需维护两套视图。
• 希望通过 MCP 将工作管理能力接入现有智能体客户端。

限制

• 需要 Node.js 22 或更高版本。
• 不安装或更新智能体、不提供人格设定、不做模型路由、不维护技能目录。
• 语义搜索为可选，首次运行成本较高，且默认不联网。
• 实验性集成注册表在当前 RC 中受限，供应商特定的问题跟踪器、部署系统和凭据不属于规范包。
• 没有预发布通道。
• 关于收费、价格、平台支持等具体信息，资料中暂未提供。