内容
# 洛威斯
适用于使用人工智能编码代理构建软件的本地优先项目管理的工具。工单、文档、架构决策和代理会话历史记录作为纯Markdown文件存放在代码仓库中的 `.lovelace/` 目录下，洛威斯是运行这些文件的桌面应用程序：支持 macOS、Linux 和 Windows，无需服务器、数据库、账户或云服务。
**[观看完整演示](.github/lovelace-demo.mp4)**（45秒）：初始化项目、定义自定义状态、创建工单、浏览文档树和链接图。
本仓库本身就是一个证明。洛威斯通过管理其自身的开发过程：139 个工单、144 条代理会话记录和 12 条架构决策记录，这些都存放在本仓库根目录下的 [`.lovelace/`](.lovelace) 中，由与下载版本相同的工具编写。当 Claude Code 会话在此代码库上工作时，它从这些文件中读取其方向，处理一个工单，并在完成之前写入会话记录。Git 承载整个历史记录，因此您可以查看导致当前状态的每个决策。
## 为什么使用本地文件
编码代理已经存在于文件系统和 Git 中。将工单、文档和会话历史记录放在代理已经存在的位置，可以为它们提供完整的项目上下文，并且以 Git 作为审计追踪。文件是真实的来源；所有其他内容（索引、板块、摘要）都源自它们，可以随时重新生成。Obsidian 之于 Notion，而洛威斯之于 Jira 和 Linear。
## 工作原理
项目的所有信息都存放在代码仓库根目录下的 `.lovelace/` 中：
```
.lovelace/
manifest.yaml 项目标识和规范版本
schema.yaml 工单类型（及其字段）、状态、优先级
actors.yaml 用户和命名代理身份
board-order.yaml 可选；手动每列卡片顺序
AGENTS.md 代理操作说明，由代理集成安装和再生
documentation/ 嵌套知识树；index.md 是代理开始读取的目录（约定，非必需）
architecture/
decisions/ 架构决策记录
tickets/ 平铺；每个工单一个文件，例如 T-0142.md
comments/
<ticket-id>/ 每个评论一个时间戳文件
sessions/ 每个代理会话一个文件，例如 S-0031.md
templates/ 新工单、架构决策记录和会话的模板
state/ gitignored；活动工单、存在、计数器
index/
index.json 生成，gitignored
BOARD.md 生成，提交
```
everywhere 适用的规则：
- 每个文件对应一个实体。评论和会话记录是追加的 sibling 文件。
- 手动编辑的文件是一种支持路径。格式错误输入会产生清晰的验证错误，指向文件和行，而不是崩溃或静默修复。
- 工单字段是数据，而不是代码。每个工单类型在 `schema.yaml` 中定义其自己的字段；验证器、索引器、MCP 服务器和应用程序表单在运行时都会读取这些定义。只有五个核心字段是固定的：`id`、`type`、`status`、`created`、`updated`。
- 索引是派生的和确定的。两次运行索引器，输入不变，输出的字节是相同的。
- 往返保真度是一个验收标准。打开并保存文件，没有编辑，字节是相同的；编辑会产生最小的差异。
- 格式是版本化的（目前是 spec 3.2.0）。工具拒绝它不理解的主要版本，并为旧项目提供迁移。
完整的磁盘格式在 [SPEC.md](SPEC.md) 中指定，编写时可以让开发人员使用该文档手动创建有效的 `.lovelace/` 目录。 [BRIEF.md](BRIEF.md) 描述了正在构建的内容以及构建顺序。
## 使用洛威斯
### 初始化项目
打开应用程序并指向一个目录。如果目录中没有 `.lovelace/`，则会提供初始化向导，适用于新建项目和现有代码仓库。它会搭建清单、默认模式、参与者、模板和文档树，将 gitignored 路径添加到 `.gitignore`，并可以安装代理集成。可以同时打开多个项目，每个项目一个标签页。
### 在应用程序中工作
- **板块。** 工单按状态分组，列从 `schema.yaml` 来。拖动卡片在列之间更改状态；列内卡片顺序由您自定义，并在 `board-order.yaml` 中持续。
- **列表。** 工单按状态分组在扁平列表中，支持筛选和批量操作。
- **工单详情。** 每个字段都从模式定义中运行时渲染，因此用户定义的字段会自动出现，并根据类型具有正确的输入。 正文在块编辑器中编辑，编译为 Markdown 并具有往返保真度。评论、会话记录和提交在时间轴中显示。
- **文档。** `documentation/` 层次结构作为可导航树显示，`index.md` 作为目录的登陆页面，过期文档（超过其 `review_by` 日期）显示徽章。
- **图。** 跨工单和文档的 wiki 链接图，手动节点位置本地保存。
- **设置。** 通过生成表单编辑工单类型、字段、状态、优先级和参与者；所有更改都通过核心验证写入 YAML 文件。
应用程序运行文件监视器：外部编辑（代理写入时您正在读取）重新验证、重新索引并在 UI 中实时显示。所有突变都通过核心验证，因此应用程序永远不会产生验证器拒绝的文件。
### 与代理合作
Claude Code 是 v1 中的代理集成。初始化流程安装：
- 项目范围的 `.mcp.json` 注册捆绑的 MCP 服务器（stdio 传输）。
- `CLAUDE.md` 中的指针部分指向 `.lovelace/AGENTS.md`，一个由 Lovelace 拥有、再生的文件，包含参与规则。
- `.claude/settings.json` 中的钩子：会话开始摘要引导代理，会话停止检查确保写入会话记录，阻止直接编辑工单文件，以及存在跟踪，以便应用程序显示实时代理活动。
- 斜杠命令（`/ticket <id>`，`/done`）和一个 `prepare-commit-msg` Git 钩子（可选），将活动工单 ID 注入提交消息。
MCP 服务器公开八种工具：
| 工具 | 目的 |
|---|---|
| `create_ticket` | 验证字段，对 schema 进行验证，分配 ID，写入文件 |
| `update_ticket` | 更新字段和状态；拒绝编辑锁定核心字段 |
| `describe_schema` | 返回项目的类型、字段、状态和优先级 |
| `query_tickets` | 按状态、类型、分配者、父级或任何定义字段筛选 |
| `read_document` | 返回文档正文或目录的登陆页面以及子摘要 |
| `log_session` | 写入追加会话记录 |
| `set_active_ticket` | 记录会话正在处理的工单 |
| `search` | 跨实体正文和标题的纯文本搜索 |
每次突变都会触发重新索引。新的代理会话启动时，会注入进展中的工单、最近的会话记录和验证警告，所有这些都少于 1,500 个令牌。
## 安装
### 对于用户
从 [lovelace.co](https://lovelace.co) 为您的平台下载安装程序。macOS 获取 `.app` 和 `.dmg`，Windows 获取 `.msi` 和 `.exe`，Linux 获取 `.deb`、`.rpm` 和 `.AppImage`。应用程序通过 Tauri 更新器自动更新；更新检查是应用程序进行的唯一网络调用。无遥测。
### 从源代码构建
先决条件：
- Node 22 或更高版本
- pnpm 10（`corepack enable` 或 `npm install -g pnpm`)
- Rust 工具链（用于 Tauri shell 和解决目标三元组）
- Bun（编译 sidecar 二进制文件）
- Tauri 平台依赖项：macOS 上的 Xcode 命令行工具，Windows 上的 WebView2，Linux 上的 `webkit2gtk` 等（参见 Tauri v2 先决条件指南）
然后：
```sh
pnpm install
pnpm build # 类型检查并构建每个包
pnpm test # 完整的测试套件
```
在开发过程中运行应用程序：
```sh
pnpm app:dev
```
开发版本依赖于 `packages/mcp/dist/host.js`（通过 `LOVELACE_HOST_JS`），因此只需执行一次 `pnpm build` 即可获取主机更改。
要生成打包的生产版本，请先编译 sidecar 二进制文件，否则应用程序将使用过时的二进制文件：
```sh
pnpm sidecars # Bun 编译主机、代理和 MCP 二进制文件到 src-tauri/binaries/
pnpm app:build # 安装程序位于 apps/desktop/src-tauri/target/release/bundle/
```
编译后的 sidecar 二进制文件不存储在仓库中；`pnpm sidecars` 在本地生成它们，发布流水线为每个平台编译新的二进制文件。完整的发布过程（签名、记号、更新工件、`latest.json`）记录在 [docs/RELEASING.md](docs/RELEASING.md) 中。
## 仓库结构
一个 pnpm 工作区 monorepo。开发版本使用 Node 22，整个代码库都使用 TypeScript 严格模式。
```
apps/
desktop/ Tauri 应用程序（Rust shell，React 前端）
packages/
core/ 解析、模式、验证、索引、摘要、突变
mcp/ MCP 服务器、代理助手和核心主机
examples/
demo-project/ 规范示例；测试运行在此项目上
docs/ 发布指南、设计系统、基调和语言
scripts/release/ 从签名发布工件组装 latest.json
SPEC.md 磁盘格式规范
BRIEF.md 正在构建的内容以及构建顺序
```
### packages/core
纯逻辑，无 UI 界面，无进程级 IO 假设。其他所有内容都调用它。主要模块：
- `frontmatter.ts`、`config.ts`、`fields.ts`：解析实体 frontmatter 和 YAML 配置文件；根据运行时模式定义验证工单字段。
- `project.ts`、`validate.ts`：加载整个项目并验证它，错误携带文件和行。错误和警告是不同的；警告永远不会阻塞。
- `index-gen.ts`、`links.ts`、`order.ts`：构建确定性的 `index.json`（包括 wiki 链接图）和提交的 `BOARD.md`；管理手动板块排序。
- `digest.ts`：代理会话开始时注入的紧凑型定位摘要。
- `mutate.ts`、`ids.ts`：创建和更新工单，记录会话，添加评论，跟踪活动工单和代理存在。ID 分配通过独占锁下的计数器文件是原子的。
- `init.ts`、`schema-config.ts`：搭建新的 `.lovelace/` 目录和默认模式。
- `search.ts`、`watch.ts`、`graph-layout.ts`：纯文本搜索，延迟再验证和再索引层，保存图节点位置。
- `version.ts`、`migrations/`：规范版本分类和跨主要版本的项目迁移。
### packages/mcp
三个面向代理的进程，都作为自包含的 Bun 编译 sidecar 二进制文件与应用程序捆绑：
- `server.ts`（`lovelace-mcp`）：MCP 服务器，基于官方 TypeScript MCP SDK，支持 stdio，公开上述八种工具。
- `helper.ts`（`lovelace-agent`）：Claude Code 调用头部助手：打印摘要，检查停止时是否有会话记录，阻止工单文件直接编辑，并维护每会话存在和活动工单标记。错误输出到 stderr，数据输出到 stdout。
- `host.ts`（`lovelace-host`）：桌面应用程序 Rust shell 和 `packages/core` 之间的无状态桥梁。输入一个 JSON 请求，输出一个 JSON 响应，然后进程退出；应用程序为每个操作生成它。
- `claude.ts`：生成和维护 Claude Code 资产（CLAUDE.md 部分、 `.lovelace/AGENTS.md`、钩子、斜杠命令、 `.mcp.json`）。
### apps/desktop
Tauri 应用程序。它仅通过 `packages/core` 读取和写入（通过 sidecar 主机）；没有私有存储，因此关闭应用程序时不会丢失任何内容。
- `src/views/`：欢迎、板块、列表、工单详情、文档、图表和设置。
- `src/components/`：初始化向导、模式编辑器、生成字段输入、搜索调色板、对话框和共享件。
- `src/editor/`：基于 Lexical 的块编辑器，支持 Markdown 往返转换、wiki 链接和逐字节点、斜杠菜单和拖放手柄。
- `src/lib/`：主机 IPC、格式化和显示名称解析器、日期和时间（通过 OS 区域设置）、链接、存在和平台帮助程序。
- `src/state/`：应用程序存储和主题。
- `src/styles/`：设计令牌（`tokens.css`）和应用程序样式。视觉语言在 `docs/design/lovelace-design-system.md` 中有文档记录。
- `src-tauri/`：Rust shell、Tauri 配置和功能。Sidecar 二进制文件由 `pnpm sidecars` 编译到 `src-tauri/binaries/`，不跟踪。
### examples/demo-project
规范示例：一个虚构的天气 API，其 `.lovelace/` 目录演练了规范中的每个实体类型，包括每个工单类型拥有的自定义字段。跨 monorepo 的测试运行在此项目和故意损坏的变体上。 它必须始终保持有效；规范更改会更新夹具和 SPEC.md 在同一提交中。
## 开发
```sh
pnpm build # 类型检查并构建每个包
pnpm test # 运行完整的 vitest 套件
pnpm watch:packages # 重建核心和 mcp 更改时
pnpm app:dev # 运行桌面应用程序，构建主机
pnpm sidecars # 编译 sidecar 二进制文件，用于打包构建
pnpm app:build # 生成平台安装程序
```
测试约定：`packages/core` 具有每个模式和验证规则的测试，MCP 服务器具有跨 demo 夹具的集成测试，应用程序组件具有来自 `index.json` 夹具的确定性渲染测试。
## 贡献
洛威斯在开放中开发，这里有所有内容，包括引导它的工单和会话记录。我们是一个由两个人组成的团队，路线图贯穿 `.lovelace/` 中的工单，因此在此阶段我们不接受外部代码贡献。错误报告和问题欢迎作为 GitHub 问题。如果发生变化，本节也会随之变化。
## 许可证
洛威斯是免费软件，根据 GNU Affero 通用公共许可证版本 3.0（[AGPL-3.0-only](LICENSE)）许可。 使用它，阅读它，构建它，fork 它。 如果您分发修改后的版本，或通过网络向他人提供，您需要根据相同的许可证发布您的源代码。
版权 2026 ADACA PROJECTS PTY LTD.
