Workfile

仓库就是数据库。

@illodev/workfile 是一种原生于仓库的协议，用于在人类与软件 Agent 之间协调工作、文档、历史记录和持久项目记忆。

仓库中的 Markdown 文件是权威内容。CLI、HTTP API 和本地 UI 使用相同的核心服务、集合注册表、索引和验证规则。浏览器或数据库中不会保留专有状态。

工作、文档、历史记录和记忆共用 ProjectRecord 索引。核心、CLI、HTTP 服务和 MCP 运行时均使用 TypeScript 编写，并以编译后的 ESM 和公共声明形式分发。本地 UI 已预编译并包含在软件包中；语义搜索则通过可选的 @illodev/workfile-search-local 工作区软件包在设备端运行。

试用在线演示 — 演示会重现此 仓库自身的工作区：Workfile 开发过程中的真实卡片、版本发布、事件和经验总结。更改仅对每个浏览器会话生效，重新加载后会重置。

https://github.com/user-attachments/assets/c9cd3035-6729-4cda-9172-984829ab5dbc

使用者

已用于生产环境

Workfile — 自用实践：每次发布都会在此仓库自己的 .project/ 中规划并记录

## 边界

Workfile 记录工作，不负责配置 Agent。

因为两者都与同一个代码仓库相伴，所以容易被混淆。生态配置工具——gentle-ai 就是一个很好的例子——会为你已在使用的 Agent 安装角色设定、精选技能、模型路由、MCP 服务和审查关卡，并可一次配置多个 Agent。它们关注的是 你的 Agent 如何工作。Workfile 关注的是 做了什么、由谁负责，以及依据是什么；它的答案是 Markdown 文件，这些文件的生命周期长于 Agent、会话和这个软件包。

两者可以配合使用。配置良好的 Agent 仍然需要一个持久的位置来记录它做过的事。

以下是本项目所负责的内容，也是配置工具不负责的内容：

• 代码仓库是权威来源。 卡片是拉取请求中的一个文件：在差异中审查；格式错误时由 workfile doctor 报告。浏览器、数据库或 ~/.config 中没有独占状态。移除软件包后，记录仍然可读。
• 声明会被强制执行，而非仅靠约定。 修改时会检查所有权，因此，如果某张卡片由其他参与者持有，你的状态转换会被拒绝，并返回 CARD_CLAIM_OWNER_MISMATCH，而不是悄悄接受——提示词中的任何句子都无法提供这种保证。
• review 不等于 done。 done 必须有来自代码实际运行环境的证据。合并不算证据。
• 人类读取相同的记录。 UI、渲染后的变更日志和版本发布都完全基于 Agent 写入的内容生成；无需维护机器视图和人类视图之间的一致性。

有意不包含的内容：Workfile 不安装或更新 Agent，不提供角色设定，不路由模型，也不精选技能目录。它会将自己的协议同步到 Agent 已经读取的指令文件中（workfile agents sync），并通过 MCP 提供所有操作——不绑定供应商，但它是一个服务，而非生态系统。

要求

• Node.js 22 或更高版本。
• 可使用 npm、pnpm、yarn 或 Bun 调用此软件包。

安装

本 README 中的所有 workfile … 命令都要求已安装此软件包——pnpm dlx / npx 的临时调用只会运行命令，之后便会丢弃二进制文件：

pnpm add -D @illodev/workfile     # per repository (recommended)
pnpm workfile doctor              # dependency bins run through pnpm / npx

pnpm add -g @illodev/workfile     # or globally: `workfile` lands on your PATH
workfile doctor
wf doctor                         # `wf` is the same binary, for typing by hand

wf 是别名，不是改名：两个名称都会调用同一个入口点，帮助和错误提示会使用你输入的名称。生成或共享的内容中，请使用完整名称。只有安装软件包后，wf 才能解析；而注册表中有一个与此无关的 wf，因此 npx wf 会下载其他人的工具，而 npx workfile 则会直接失败。

一次性初始化可以使用 pnpm dlx @illodev/workfile init，但之后仍应将此软件包保留为 devDependency：这样 init 添加到 package.json 的 project* 脚本才能正常解析。此前缀属于 npm 脚本命名空间——pnpm project 会打开 UI，pnpm project:doctor 会运行检查——与旧的二进制名称无关。

TypeScript API

发布的接口通过条件导出提供 JavaScript 和类型声明。TypeScript 使用者可以从根软件包和所有文档中列出的子路径获取类型化的配置、工作区、记录、搜索和集成契约：

import {
    defineProject,
    type CardStatus,
    type ProjectConfig,
    type ProjectRecord
} from "@illodev/workfile";
import { createSemanticSearchProvider } from "@illodev/workfile/search";

const config: ProjectConfig = defineProject({
    schemaVersion: 2,
    name: "Billing",
    cards: {
        areas: ["api", "web"]
    }
});

const status: CardStatus = "doing";

CLI 和 UI 无需在使用项目中安装 TypeScript。React、Primer、Vite 和 UI 类型软件包都只是构建依赖；安装后的软件包会从 dist/ui 提供打包好的浏览器资源。

工作区

通过 project.config.mjs 发现项目，并且通常将协议管理的 文件存放在 .project/ 下：

project.config.mjs
.project/
├── VERSION
├── cards/
│   └── archive/
├── assets/
├── docs/
├── changelog/
│   ├── unreleased/
│   └── releases/
├── memory/
│   ├── learnings/
│   ├── decisions/
│   ├── incidents/
│   ├── conventions/
│   └── context/
├── agents/
└── .cache/

最简配置——一个普通对象，而非 defineProject(...)。加载器会自行应用 defineProject，此处的导入是裸模块标识符，只有在存在 node_modules 时文件才能解析它，这会导致两个无需安装依赖即可运行的使用场景出问题：通过 pnpm dlx 初始化、尚未安装该软件包的工作区，以及生成的 CI 作业在干净克隆中运行 npx。JSDoc 注释可在不进行运行时导入的情况下保留编辑器类型提示：

/** @type {import("@illodev/workfile").ProjectConfigInput} */
export default {
    schemaVersion: 2,
    name: "My project",
    cards: {
        areas: ["api", "web", "infra", "docs"]
    },
    docs: {
        sources: [
            "README.md",
            "docs/**/*.md",
            "apps/*/README.md",
            ".project/specs/**/*.md"
        ]
    },
    changelog: {
        releaseStrategy: "semver",
        defaultVisibility: "public"
    },
    memory: {
        collections: [
            "learnings",
            "decisions",
            "incidents",
            "conventions",
            "context"
        ]
    },
    agents: {
        targets: ["agents-md", "cursor"]
    },
    ci: {
        targets: ["github"]
    },
    mcp: {
        allowMutations: true
    },
    search: {
        semanticWeight: 0.35,
        maxProviderRecords: 500
    }
};

项目专属的区域、路径和词汇表会在运行时解析，并通过有效架构公开。八种 Work 状态和 schema-v2 记忆集合语义仍是协议契约。

Work

卡片是 .project/cards/ 下的 Markdown 记录。Work 模块提供层级结构、依赖关系、认领、范围、状态转换、归档、资源和具备冲突感知能力的写入。

workfile card list --json
workfile card show T-0042 --json
workfile card create --title "Implement runtime schema" --area infra
workfile card create --json-input card.json   # body, parent, source and tags in one call
workfile card claim T-0042 --scope apps/api,packages/sdk   # actor resolves itself
workfile card transition T-0042 review
workfile card patch T-0042 --json-input changes.json --expected-revision sha256:...
workfile card archive T-0042
workfile card reopen T-0042 --status backlog

文档

Docs 结合两种来源，不复制现有文档：

• 已索引文档：通过配置的 glob 模式发现。系统会为其分配确定性的 PATH-* ID，并通过协议将其保持为只读。
• 托管文档：存储在 .project/docs/ 中，具有稳定的 DOC-NNNN ID、类型化 frontmatter 和支持版本修订的变更。

托管文档会递归读取，因此可以按文件夹分组，包括你手动创建的文件夹。ID 在全局范围内按顺序递增：文件夹用于组织，而非标识。新文档遵循 docs.layout（默认值 kind 会按文档类型分组；flat 则将文档写入托管根目录），也可通过 --folder 覆盖此设置。

workfile doc list --query billing
workfile doc show DOC-0012 --json
workfile doc create --title "Deployment runbook" --kind runbook --status current
workfile doc create --title "Rate limiting" --folder architecture/billing
workfile doc move DOC-0012 --folder architecture
workfile doc patch DOC-0012 --json-input changes.json --expected-revision sha256:...

doctor 会检测失效的本地链接、未解析的相关或已取代记录、缺失的范围路径，以及过时的审查／来源关系。

历史记录

History 使用原子化变更片段，而非要求多个分支或 Agent 编辑同一个 CHANGELOG.md。

未发布片段：

---
id: CHG-0042
title: Add portable history workspace
type: added
area: infra
visibility: public
cards: [T-0042]
created: 2026-07-28
updated: 2026-07-28
---

发布时会使用选定的片段，将其移入发布目录，并创建规范的 REL-NNNN 记录。公开或内部变更日志均为派生输出。

workfile changelog list --unreleased
workfile changelog add --title "Add portable history" --type added --area infra
workfile changelog preview
workfile changelog release 0.4.0 --title "History and Memory"
workfile changelog render --visibility public
workfile changelog render --visibility public --write
workfile changelog verify

发布版本可根据配置使用 semver、calendar 或 freeform 验证。片段和发布记录与卡片、文档和记忆一样，参与相同的工作文件搜索和反向链接图。

记忆

记忆由类型化、原子化且可感知生命周期的记录组成，而非一份不断增长的对话记录：

集合	前缀	用途
经验	LRN	带有置信度和出现频率信号的可复用观察
决策	ADR	提议、接受、拒绝或已取代的决策
事件	INC	运行事件、严重程度、时间和纠正措施
约定	CONV	人类和 Agent 遵循的持久规则
上下文	CTX	有用但可能过期的项目状态

workfile memory list --collection learnings --status active
workfile memory add learning --title "Atomic fragments avoid merge conflicts" \
  --confidence high
workfile memory add decision --title "Keep Markdown canonical" --status accepted
workfile memory add incident --title "Release pipeline stalled" --severity high
workfile memory graduate LRN-0004 --to CONV-0002,DOC-0012
workfile memory supersede ADR-0003 --by ADR-0009
workfile memory patch CTX-0002 --json-input changes.json --expected-revision sha256:...
workfile memory verify

doctor 会检查无效的生命周期状态、缺失的毕业／取代目标、过期上下文，以及不完整的事件解决元数据。

统一索引

每个模块都会通过通用集合注册表，将其文件规范化为 ProjectRecord 条目。派生的进程内索引提供：

• 整个项目的加权全文搜索；
• 按稳定记录 ID 查找；
• 所有四个领域之间的外发引用和传入反向链接；
• 卡片的 source: 链接和本地 Markdown 链接；
• 模块专属的健康状况、生命周期和时效信号；
• 模块和集合计数。

规范状态始终保留在磁盘上。服务端缓存生命周期短，可失效处理，并且能够完全重建。

workfile search "billing architecture"
workfile search release --kind change,release,memory --limit 25 --json

初始化

初始化器可交互运行，也可在自动化中确定性运行。它会检测包管理器、单体仓库文件夹、可能的卡片区域、文档来源、现有 Agent 环境和 CI 提供商。试运行会显示精确的文件系统计划。

pnpm dlx @illodev/workfile init
pnpm dlx @illodev/workfile init --yes \
  --agents agents-md,claude,cursor,copilot --ci github
workfile init --dry-run --json

生成的 project.config.mjs 会导出一个普通对象，因此通过 pnpm dlx 初始化的工作区，即使尚未在本地安装该包，也仍可加载。除非明确指定 --force，否则不会覆盖现有文件。.project/.cache/ 会添加到 .gitignore；所有规范协议文件都会保持受版本控制。

托管演示

UI 提供适用于静态托管（Vercel、GitHub Pages、任意文件服务器）的演示模式。npm run build:demo 会使用内存中的 API 构建 UI，该 API 会重放一个已植入种子的工作区快照：每个视图都可正常使用，变更在当前会话中表现正常，但重新加载后会重置。仓库包含 vercel.json，因此导入 Vercel 后即可零配置部署演示。

pnpm run demo:data   # reseed and resnapshot packages/workfile/ui/src/demo-data.json
pnpm run build:demo  # static demo build into packages/workfile/dist/demo

常规构建会通过摇树优化，将演示层和快照从打包文件中移除。

发布

发布通过 CI 使用 npm 可信发布（OIDC）完成，不会在仓库中存储 npm 令牌。发布前，如果上一个标签之后有任何 UI 变更，请运行 pnpm run screenshots：该命令会重新捕获所有视图，并自行发布 README 和落地页的静态截图；这些截图应放入修改了外壳的提交中，而不是版本升级提交中。发布流程如下：

1. 生成变更日志：workfile changelog release <version> 和 workfile changelog render --write。
2. 升级版本并打标签：npm version <version>，然后运行 git push && git push --tags。 版本钩子会在同一次升级中处理所有 packages/* 包；工作区包始终使用核心包的版本。
3. Release 工作流会验证标签与 package.json 是否一致（并确认工作区版本没有偏差），使用 pnpm 运行 check:release（构建、类型检查、测试、审计和打包归档文件冒烟测试），然后通过 npm CLI 将核心包和所有工作区包发布到 latest。

没有预发布渠道：任何已发布版本都可通过一次 npm install 获取；v*-rc.* 标签会导致发布失败，而不会进行发布。这是可信发布机制带来的结果，而非偏好：OIDC 只授权执行 npm publish，不授权其他注册表写入操作，因此一旦为候选版本设置了 dist-tag，CI 就无法将其移走。

Agent 协议

规范指令和工作流位于 .project/agents/ 下。系统会将精简的受管理区块同步到受支持的环境中，同时不替换用户的其他内容：

AGENTS.md
CLAUDE.md
.cursor/rules/workfile.mdc
.github/copilot-instructions.md

workfile agents sync
workfile agents sync --targets agents-md,claude,cursor,copilot
workfile agents check
workfile agents context --card T-0042

受管理区块包含包版本和 SHA-256 摘要。agents check 和 workfile doctor 会报告缺失、未受管理或过期的生成指令。Agent 上下文有容量限制，会优先加载所选卡片、直接关联内容、当前有效约定、未解决事件和未过期上下文，而不是加载所有 workfile 记忆。

Model Context Protocol

Workfile 包含一个本地、无依赖的 MCP 服务，使用 UTF-8 编码，通过标准输入输出传输以换行符分隔的 JSON-RPC。它将所有操作委托给 CLI 和 HTTP API 使用的相同核心服务，支持现代（2026-07-28）和旧版（2025-11-25）协议修订版，并公开 32 个工具、4 个资源和 3 个提示词。在 --read-only 模式下，所有变更工具都会完全隐藏。

无需安装任何内容，即可让客户端连接到它。这是官方注册表为 io.github.illodev/workfile 发布的调用方式，也是大多数客户端根据该列表为你生成的配置：

{
  "mcpServers": {
    "workfile": {
      "command": "npx",
      "args": ["-y", "@illodev/workfile", "mcp"]
    }
  }
}

这里的 mcp 是子命令，而不是二进制文件：npx 会解析名称与软件包匹配的 bin，并将后续所有内容传递给它。如果客户端从工作区以外的位置启动，请附加 --root PATH；否则，它会向上搜索 .project/。附加 --read-only 则只提供读取工具，并拒绝所有变更操作。

安装软件包后，只需调用子命令即可启动同一个服务：

workfile mcp
workfile mcp inspect --json
workfile mcp config --read-only --json

对于 Claude Code，同一套功能也以插件形式提供——包含 MCP 服务、/claim、/card-context、/next 和 /done 命令、一个技能，以及可将卡片认领转化为可执行防护机制的钩子——且不会向仓库提交生成文件：

/plugin marketplace add illodev/workfile
/plugin install workfile@illodev

完整契约——包括工具清单、资源、提示词、进程规范和插件功能——记录在 docs/mcp.md 中。

该服务已列入 Glama，Glama 会在容器中构建它，并检查它报告的功能：

搜索集成

词法搜索仍保持确定性并在本地运行。宿主可通过编程方式注入可选的语义提供程序；Workfile 不会自行选择供应商，也不会自行通过网络发送仓库内容。

第一方：本地嵌入

@illodev/workfile-search-local 会在设备上运行嵌入模型（onnxruntime-web、CPU 上的 ONNX、量化版 Xenova/multilingual-e5-small）——仓库内容绝不会离开本机。请在 project.config.mjs 中使用受保护的导入声明它，因为配置也必须能在无法解析该软件包的环境中加载（生成的 CI 任务会在干净的克隆仓库上运行 npx）：

export const integrations = await (async () => {
    try {
        const { localSearchIntegration } = await import(
            "@illodev/workfile-search-local"
        );
        return [localSearchIntegration()];
    } catch {
        return []; // package absent: search stays lexical
    }
})();

export default {
    // …
    search: { provider: "local-embeddings" }
};

接入前请了解其开销模型：首次混合搜索会为所有未缓存的候选记录生成嵌入——在包含数千条记录的工作区中，这会持续占用 CPU 数分钟，并由最先执行搜索的界面（CLI、看板 UI，或 Agent 加载的 MCP 服务）触发。该提供程序默认将 ONNX 的核心数上限设为可用核心数的一半，按批次持久化数据，因此中断后可从断点继续，而不必重新开始；进度会输出到 stderr。将 search.maxProviderRecords 设为语料库的大小，即可让每条记录都符合条件。详情和选项见 packages/search-local/README.md。

自行选择

import {
    createSemanticSearchProvider,
    searchProjectRecordsHybrid
} from "@illodev/workfile/search";

const provider = createSemanticSearchProvider({
    id: "company-embeddings",
    async search({ query, records }) {
        // Return [{ id, score }] with scores between 0 and 1.
        return rankWithYourApprovedProvider(query, records);
    }
});

const result = await searchProjectRecordsHybrid(index.records, query, {
    provider,
    semanticWeight: 0.35
});

适配器边界将外部数据披露明确留作宿主的决策，并使规范的 Markdown／索引实现不依赖具体提供程序。

实验性集成注册表

宿主可通过编程方式在一个小型、供应商中立的注册表中对获准的语义搜索和健康检查适配器进行分组：

import {
    createIntegrationRegistry,
    defineProjectIntegration
} from "@illodev/workfile/integrations";

const integrations = createIntegrationRegistry([
    defineProjectIntegration({
        id: "company.platform",
        semanticSearchProvider: provider,
        async healthCheck({ workspace, index }) {
            return [];
        }
    })
]);

MCP 服务和 doctor API 均接受该注册表。目前的 RC 版本有意限制了其范围：供应商专属的问题跟踪器、部署系统和凭据均不属于规范软件包。随着实际集成不断完善，这个边界也可逐渐成熟，而无需将架构绑定到 GitHub、GitLab、Jira 或某个部署提供程序。

CI 模板

CI 文件遵循相同的托管文件约定，可为 GitHub Actions、 GitLab CI 或通用 Shell 运行器生成：

workfile ci sync --targets github,gitlab,generic
workfile ci check

模板会使用固定版本的 Workfile，同时运行 Workfile doctor 和 Agent 同步检查。

旧版迁移

可以规划并应用 v1 .planning 系统的迁移，并进行确定性的冲突检查：

workfile migrate plan --source .planning
workfile migrate apply --source .planning --mode copy
workfile migrate apply --source .planning --mode move

有效的旧版卡片和资源会转换为规范的 v2 Work 记录。旧版提案、变更日志、 学习记录和格式错误的记录会保存在 .project/sources/legacy-planning/ 下， 不会被悄然按不兼容的架构重新解释。每次应用迁移都会写入 .project/migrations/legacy-planning.json，其中包含源、目标、摘要 和结果元数据。

通用 CLI

workfile init
workfile schema --json
workfile doctor --json
workfile ui
workfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com

命令通过 --json 返回稳定的机器可读错误。修订版本过期时以代码 3 退出； 配置错误以代码 2 退出；验证错误和未找到错误以代码 1 退出。完整的命令 列表请参阅 docs/cli.md。

HTTP API

workfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com 会以供人查看的形式提供同一看板：所有修改路由都会返回 409 WORKSPACE_READ_ONLY，并且 UI 会隐藏编辑功能。它本身仍不提供身份验证，因此请在以此方式发布的任何服务前配置经过身份验证的反向代理——请参阅 docs/security.md。

workfile ui 会启动本地服务，通常位于 http://127.0.0.1:4747。版本化的 /api/v2/* 接口涵盖工作区、统一搜索和所有集合——卡片、 文档、变更日志（包括发布预览／组装／渲染）、记忆生命周期、Agent 和 CI 同步。托管记录读取会返回 ETag，写入接受 If-Match，错误则使用稳定代码。 端点参考见 docs/http-api.md。

本地界面

导航栏是可折叠侧边栏，按领域分组：

• 工作： Explorer、Triage、Flow、Epics 和甘特时间线（按状态着色的条形、月份刻度、今日标记）。
• 知识： Docs（搜索、Markdown、元数据、新鲜度、范围、反向链接）和 Memory（类型化集合、生命周期警告、晋级和取代）。
• 项目： Workflow（来源关系图——每条记录都是一个节点，类型化关系作为边）、History（片段、发布、发布准备、渲染后的变更日志预览）和 Health。

Health 中的问题可以导航到任意领域的记录。运行时配置决定卡片区域、变更词汇和 Memory 集合状态；这些值不会被编译进视图。文件链接会打开本地编辑器；如果服务提供了 repoUrl（托管演示版就是如此），则会打开仓库的 Web 界面。

概览用一句按严重程度从高到低排列的判定回答“进展如何”——医生错误、悬而未决的认领、范围冲突、受阻卡片、进行中的工作——其下方是你离开期间各个 Agent 写下的每一条操作记录。

打开检查器的 Explorer	甘特时间线

包含发布记录的 History	Memory（深色主题）

Workflow 会将各个集合读入同一张关系图，而不是显示为四个列表：第一行切换项用于选择集合，第二行用于选择关系类型。在 frontmatter 中声明的关系会绘制为实线，而写在句子中的 ID 会绘制为虚线，因为散文中的链接不如字段中的声明有力，不应呈现得同样可靠。默认关闭散文扫描——它占此工作区 742 条边中的 294 条。上图展示的是经过整理且已声明关系的语料：文档 related 到其追踪的卡片，经验关联到教会它的事件，决策关联到它所定案的卡片——因此，卡片、背后的决策以及描述它的文档会作为一个整体呈现。

开发

此代码仓库是一个 pnpm 工作区：根目录是一个私有外壳，用于存放版本和委派脚本；所有发布内容都位于 packages/ 下——核心位于 packages/workfile，旁边是 packages/search-local 等提供方，所有包都使用相同的版本号。pnpm 通过 packageManager 字段 固定（corepack enable 会自动识别）：

pnpm install
pnpm run check
pnpm run smoke:package
node ./packages/workfile/dist/bin/workfile.js mcp inspect --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js schema --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js doctor --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js ui --root ./packages/workfile/test/fixtures/workspace

pnpm run check 会编译 TypeScript 运行时和声明文件，检查严格的公共使用者契约，对 React UI 进行类型检查和打包，并运行完整的测试套件。 pnpm run smoke:package 会在临时项目中打包并安装实际的 tarball，然后测试初始化、全部四个领域、MCP 和打包后的 UI——冒烟测试特意使用 npm 安装，以测试 npm 使用者路径。

prepack 会重新构建运行时声明和 UI，确保未来发布的包只包含 dist/ 下已编译的运行时产物，不包含开发用 TypeScript 或复制的 UI 源代码树。

当前保证

• 受限的 frontmatter 编解码器，确保标量和列表往返后字节稳定；
• 保留未知 frontmatter 字段和正文的字节内容；
• 原子文件替换、每条记录的锁以及可避免冲突的 ID 预留；
• SHA-256 修订令牌和对过时写入的拒绝；
• 原子化的 Work 认领、状态转换、归档和重新打开操作；
• 受管理的 Docs、History 片段和类型化 Memory 修改；
• 发布组装会规范地消费片段并派生渲染结果；
• 可配置且符合仓库安全要求的路径和运行时词汇表；
• 在所有领域中统一规范化、搜索、引用和反向链接；
• 针对 Work、Docs、History 和 Memory 的健康诊断；
• 为公共包及子路径导出提供已编译的 ESM 和 .d.ts 声明；
• 可执行的打包版 CLI/MCP 二进制，并通过全新 tarball 安装进行验证；
• 版本化 API，以及适配原始看板的兼容适配器。

文档

• docs/getting-started.md — 安装、初始化和日常工作流程。
• docs/cli.md — 每个模块的完整 CLI 参考。
• docs/http-api.md — 端点参考、约定和错误。
• docs/mcp.md — MCP 服务契约：工具、资源、提示词。
• docs/security.md — 本地服务的威胁模型、请求防护、资源处理，以及明确不在范围内的内容。
• docs/ui.md — 界面：构建方式、零依赖保证，以及 shadcn 迁移如何与设计系统共存。
• docs/SPEC.md — 规范性协议规范：数据模型、记录契约、修订语义和 MCP 集成契约。