KittyClaw

KittyClaw 是一个用于 AI 代理执行的软件工作的本地控制平面。 提交一个软件工单，观察它在实时看板上移动，阅读更改代码的运行记录，检查其验证证据，并由你自己做出最终发布决定。

该产品在一次旅程中证明了三件事：实时看板、可读的运行记录，以及外部发布前的人工验证。新看板以 Backlog、Todo、InProgress、Blocked、Scheduled、Review 和 Done 列开始（列保持可自定义）。运行可以使用 Claude Code、OpenAI Codex、Grok Build 或本地 Ollama 模型。

按照引导式五分钟演示使用一个真实的软件工单重复该旅程。配套的激活测试协议用于衡量符合条件的试用用户是否能在十分钟内达到他们的第一次运行。

一个项目可以拆分为独立命名的管道，其稳定身份在重命名后依然保留。列可以拥有具有持久记忆的通用处理器、可复用的项目技能、有序的工单选择、持久的重试，以及类似开关的路由到任何管道中的列。右键单击列并选择 配置列 以编辑其名称、颜色、角色、位置、工单指导、处理器和路由，而不会丢失看板的视觉上下文。Waiting 或 OwnerAction 列中的工单始终在其描述和活动之间显示一个突出的上下文块，说明所有者是必须评论或将工单移动到特定的验证/拒绝列，还是 KittyClaw 会自动恢复它。列也可以插入到现有泳道之间或直接从 Kanban 末尾添加；Workflows 页面仍然是全局管道和技能概览。执行状态与业务列分开，因此 InProgress 列是可选的。遗留的 AutomationEngine 仍然可用于基于触发器的规则、cron/间隔工作以及向后兼容。代理通过 Claude Code、OpenAI Codex、Grok Build、Mistral Vibe 或本地 Ollama 模型运行，同时其输出流式传输到应用中。

每个处理器都与其项目一起在 .agents/processors/column-<id>/processor.json 中进行版本管理。这个权威定义包含其 任务、显式提示、模型、技能、工单排序、重试策略和路由。SQLite 仅保留 同步的运行时投影和执行状态。持久经验教训位于定义旁边的 .agents/processors/column-<id>/memory/MEMORY.md 下。

技术栈

• .NET 10 / Blazor Server（交互式 SSR）

• SQLite 通过 Entity Framework Core（每个项目一个数据库）

• OpenAPI 带有自动生成的 Markdown 文档

• 代理执行：至少一个受支持的 CLI — Claude Code CLI、OpenAI Codex CLI、Grok Build 或 Mistral Vibe。Ollama 也支持通过 Claude Code CLI 使用本地模型（本地模型设置）。

• 可选用于仓库初始化、Git 感知自动化和代理提交：Git

入门

先决条件

• .NET 10 SDK

• 至少一个代理 CLI 在你的 PATH 上：Claude Code（claude）、OpenAI Codex（codex）、Grok Build（grok）或 Mistral Vibe（vibe）。本地模型执行需要 Claude Code CLI 和一个可访问的 Ollama 服务器。

• 可选：Git（git 在你的 PATH 上）用于仓库初始化、Git 感知自动化和代理提交

首次启动时，引导弹窗会使用与调度相同的解析可执行路径检查 Git 和每个受支持的提供方 CLI：Claude Code（claude / KITTYCLAW_CLAUDE_BIN）、OpenAI Codex（codex / KITTYCLAW_CODEX_BIN）、Grok Build（grok、~/.grok/bin 或 KITTYCLAW_GROK_BIN）和 Mistral Vibe（vibe / KITTYCLAW_MISTRAL_BIN）。它还会报告可选的 Ollama 可用性。任何一个代理提供方就足够了，失败或超时的探测保持非阻塞，而依赖 Git 的功能仍然需要 Git。

运行

从仓库根目录：

run.bat        (Windows)
./run.sh       (macOS / Linux)

两者都包装 dotnet watch --project KittyClaw.Web --non-interactive 并在 http://localhost:5230 上提供应用服务，并启用热重载。

创建项目

从主页选择 创建项目，输入名称，并选择其工作区。内置文件夹浏览器可在 Windows、macOS 和 Linux 上运行，无需在浏览器后面打开原生系统对话框。它显示主目录、挂载的驱动器或文件系统根目录、面包屑、父级导航和直接路径输入。你也可以输入绝对路径并在文件夹不存在时创建它。

点击 初始化 以：

1. 创建项目注册表条目 + 每个项目的 SQLite 数据库。

2. 将项目模板从 ProjectTemplate/（preamble.md、{agent}/SKILL.md、{agent}/memory/MEMORY.md 索引、memory-consolidation.md、automations.json、CLAUDE.md）复制到工作区 — 代理文件位于 <workspace>/.agents/ 下，CLAUDE.md 位于工作区根目录。

3. 如果工作区还不是 git 仓库，则运行 git init（如果未安装 git 则跳过）。

4. 为模板中找到的每个代理 slug 创建一个成员。

5. 打开项目设置向导。

设置向导分析现有工作区并提出不同的管道、列、人工交接、处理器、路由和计划。对于空文件夹，它首先询问几个关于项目目的、可交付成果、人工决策和重复工作的问题。建议是图形化的：你可以添加或删除管道，查看每个管道的列，用提示词细化步骤，并在批准前向后移动。在此准备过程中不会创建任何内容；创建工作流 应用并验证已批准的计划，然后打开看板。

这个新项目设置有意与遗留看板迁移向导分开。迁移术语和遗留自动化清理仅在现有基于自动化的看板需要转换时显示。

工作区文件夹本身永远不会被 KittyClaw 删除，即使你删除项目。

数据存储

所有 KittyClaw 数据都本地存储在 %APPDATA%/KittyClaw/ 中：

• registry.db — 项目注册表

• projects/{slug}.db — 每个项目的数据库（工单、评论、标签、列、成员）

• uploads/ — 上传的图片

• runs/{runId}.json — 代理运行快照（事件、状态、退出代码）

• settings.json — 语言 + 引导标志

每个项目的代理状态位于 工作区 中：<workspace>/.agents/{agent}/memory/（评分的 MEMORY.md 索引 + 每个主题的经验文件）、<workspace>/.agents/channel/（会话状态）等。

项目结构

架构

每个功能的架构文档位于 doc/ 下。从管道和列处理开始了解多管道模型，或从 doc/index.md 开始了解完整的架构图。

API

所有端点都在 /api 下。文档从实时的 OpenAPI 规范自动生成：

• 人类可读的 Markdown：GET http://localhost:5230/api/docs

• 机器可读的 JSON：GET http://localhost:5230/openapi/v1.json

MCP 服务器

KittyClaw 可以在 http://localhost:5230/mcp（Streamable HTTP）上暴露一个嵌入式 MCP 端点，因此任何 MCP 客户端都可以驱动看板 — 列出项目、创建和移动工单、评论以及读取看板布局 — 而无需接触 REST API。在启动 KittyClaw 之前设置 KITTYCLAW_MCP_ENABLED=1，然后将其连接到 Claude Code：

claude mcp add --transport http kittyclaw http://localhost:5230/mcp

v1 中提供了七个工具：list_projects、list_tickets、get_ticket、create_ticket、comment_ticket、move_ticket、board_overview。该端点默认禁用，并使用与 REST API 相同的 localhost 信任边界。详细信息见 doc/mcp.md。

对于 AI 代理

此应用旨在通过其 REST API 由 AI 代理操作。以下是如何开始：

1. 阅读实时 API 文档 在 http://localhost:5230/api/docs — 每个端点、请求/响应示例和模式，始终与运行中的服务器保持最新。

2. 标识你自己 — author 在每个变更端点上都是 必需的；省略它返回 HTTP 400。使用你的普通代理名称（例如 "programmer"、"groomer"）。人类用户是 "owner"。

3. 发现看板 — 首先调用 GET /api/projects，然后调用 GET /api/projects/{slug}/columns 以了解工作流阶段，以及 GET /api/projects/{slug}/members 以了解可分配的成员。

4. 使用正确的状态 — 工单状态必须与现有列名匹配。在移动工单之前获取列。

5. 跟踪你的工作 — 在工单上添加评论以解释你做了什么或你需要什么。使用 @mentions 通知成员，使用 #id 引用同一项目中的工单，使用 #{slug}:{id} 引用另一个项目中的工单。

6. 标签和优先级 — 使用 GET /api/projects/{slug}/labels 发现可用的标签，并将优先级设置为 Idea、NiceToHave、Required 或 Critical。

7. 检查提及 — 调用 GET /api/projects/{slug}/mentions/{your-handle} 查找提及你的工单。

8. 子工单 — 创建工单时设置 parentId 使其成为子工单。使用 PUT /api/projects/{slug}/tickets/{id}/parent 重新设置父级，或使用 DELETE 将其分离。使用 ?parentId={id} 列出子工单。

9. 跨项目转移 — 仅在检查目标项目具有兼容的列、分配者和标签后，使用 POST /api/projects/{slug}/tickets/{id}/transfer。该操作保留工单树及其历史，或在两个项目都不更改的情况下拒绝转移。请参阅无损工单转移。

约定

• 作者格式："owner" 表示人类用户，纯代理名称（如 "programmer"）表示 AI 代理

• 优先级级别：Idea、NiceToHave、Required、Critical

• 默认列：Backlog

UI 功能

• 首次启动时的引导弹窗，检查 Git、Claude Code、OpenAI Codex、Grok Build、Mistral Vibe 和 Ollama

• 跨平台应用内工作区浏览器，支持根目录、面包屑导航、直接路径输入和文件夹创建

• 引导式新项目设置，分析工作区并在创建工作流之前提出可编辑的管道和列

• 引导式旧版看板迁移，保留已完成的工单，并仅在验证后停用被替换的自动化

• 统一的多项目主页，包含项目卡片和看板泳道

• 多管道看板，根据处理器路由以视觉方式区分允许和禁止的拖放目标

• 上下文列编辑器，用于结构、角色、负责人指导、处理器、有序操作、计划任务和路由

• 可自定义的仪表板视图，支持自由拖拽磁贴（Markdown、KPI、图表、热力图、时间线等）、基于 AI 聊天的磁贴创建，以及通过 LLM 提示自动刷新

• 工单详情面板，包含评论和活动时间线

• 实时代理运行抽屉（提供商输出的 SSE 流、引导 + 停止控件）

• 新指令聊天抽屉，向代理发送临时提示

• Markdown 渲染，支持 @mention、#id 和 #{slug}:{id} 跨项目工单引用

• 高级搜索语法：#42、@owner、>date、priority:critical、label:bug、by:owner

• 子工单，支持父子关系和进度跟踪

• 通过 REST API 在项目之间进行无损、原子化的工单树转移

• 直接从看板管理列（插入、复制、重新排序、配置和标记已读）

• 标签和成员管理

• 描述和评论中的图片上传

• 本地模型支持（Ollama）：每个项目的基础 URL 支持模型自动发现、每个成员的默认模型，以及 .agents/automations.json 中的每个操作配置

• 通过 Claude Code、OpenAI Codex、Grok Build、Mistral Vibe 或 Ollama 进行提供商感知调度，支持对话交接和不可用模型回退

仪表板

每个项目在看板旁边都有一个可自定义的 Dashboard 视图。磁贴可自由拖拽、按计划自动刷新，并可从应用内 AI 聊天面板创建或编辑——代理会为你编写磁贴的文件夹。

磁贴类型

文件夹布局

每个磁贴都位于项目工作区中 .dashboard/ 下的自己的文件夹中：

.dashboard/
  <tile-slug>/
    tile.yaml        # template, title, refresh schedule, prompt
    script.ps1       # optional refresh script (or script.sh, script.py, …)
    output.json      # last refresh output consumed by the template

tile.yaml 关键字段

• template — 上表中 ID 之一。

• title — 磁贴标题中显示的显示名称。

• refresh — 定期刷新的间隔（例如 5m、1h）。

• refreshAt — cron 风格的每日定时刷新（refresh 的替代方案）。

• prompt — （重新）生成 output.json 时发送给代理的指令。

磁贴可以从仪表板的 AI 聊天面板中通过描述你想要的内容来创建——代理会选择一个模板、编写 tile.yaml、生成刷新脚本，并生成初始的 output.json。

成本报告

Costs 页面提供按项目缓存的代理使用情况视图，因此即使运行历史很长，打开报告也是即时的。日期预设可快速选择常见时间段，而项目、管道和模型过滤器可以组合使用；管道选项会自动跟随所选项目。可见的图例区分了每日图表中的实测成本和估算成本。

自动化模型

• 触发器：interval、ticketInColumn、statusChange、subTicketStatus、ticketCommentAdded、gitCommit、boardIdle、agentInactivity。

• 条件：ticketInColumn、ticketCountInColumn、fieldLength、priority、labels、assignedTo、hasParent、allSubTicketsInStatus、ticketAge。

• 操作：runAgent、moveTicketStatus、setLabels、assignTicket、addComment、consolidateAgentMemory、commitAgentMemory、executePowerShell、createTicket、httpRequest（出站 Webhook；除非 allowLocalTargets，否则阻止环回/链路本地目标）。

• runAgent.agent / runAgent.concurrencyGroup 中的 {assignee} 占位符从触发工单的 assignedTo 解析。

• 规范的后运行链：runAgent → consolidateAgentMemory（聚焦的 claude 处理，整理代理的 memory/ 索引和主题文件）→ commitAgentMemory（提交结果）。

遥测

KittyClaw 每天向一个适合自托管的分析服务（Umami）发送一次匿名心跳，以便我们了解有多少实例在运行以及野外运行哪些版本。负载恰好包含三个字段，没有其他内容：

• 一个随机实例 ID（首次运行时在本地生成的 GUID——不关联任何用户、机器或项目数据）

• KittyClaw 版本

• 操作系统系列（Windows / macOS / Linux）

绝不发送工单内容、项目名称、主机名或使用详情。失败是静默的，绝不会影响应用。开发实例从不发送遥测数据。

许可证

KittyClaw 根据 AGPL-3.0-or-later 许可。自托管和个人使用不受限制；如果你分发修改版本或将其作为网络服务提供，则必须在相同许可证下发布你的源代码。

AGPL §7 下的附加条款（全文见 NOTICE.md）：衍生作品必须保持 KittyClaw 署名可见（应用内法律声明和 README 中的"基于 KittyClaw"声明），必须不得歪曲其来源，并且不获得 KittyClaw 名称或徽标的任何权利。

AGPL 不涉及的两件事（见 NOTICE.md）：

• 你的项目：KittyClaw 复制到你的工作区中的模板文件（.agents/、CLAUDE.md 等）额外以 MIT 许可授权，应用为你生成的所有内容（工单、日志、代理提交等）都是你的，免许可。使用 KittyClaw 管理项目绝不会将该项目置于 AGPL 之下。

• 过去：直到并包括 v0.11 的版本以 MIT 发布，并继续在这些条款下可用。

更多项目与联系

→ 网站 + 演示： kittyclaw.dev

查看我的其他项目，请访问 ekioo.com。

在 X 上关注我：@DamienHOFFSCHIR