KittyClaw

KittyClaw

kittyclaw.dev · 抢先体验

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

产品通过一个完整流程展示三项能力：实时看板、清晰易读的运行记录以及发布到外部之前由人工验证。新看板默认包含 Backlog、Todo、InProgress、Blocked、Scheduled、Review 和 Done（列仍可自定义）。运行可以使用 Claude Code、OpenAI Codex、Grok Build 或本地 Ollama 模型。

按照五分钟引导演示，使用真实的软件工单重现整个流程。配套的激活测试协议用于衡量符合条件的试用用户能否在十分钟内启动首次运行。

一个项目可以拆分为多个各自命名的独立流水线，其稳定标识不会因重命名而改变。列可以配置通用处理器，并具备持久记忆、可复用的项目技能、有序的工单选择、可持久化的重试，以及可切换到任意流水线中各列的路由。右键单击某列并选择 配置列，即可编辑其名称、颜色、角色、位置、工单指引、处理器和路由，同时保留看板的视觉上下文。Waiting 或 OwnerAction 列中的工单总会在描述和活动记录之间显示醒目的上下文区块，说明负责人是否需要发表评论，或将工单移至特定的验证／拒绝列；或者 KittyClaw 是否会自动恢复处理。还可以直接从看板在现有泳道之间插入列，或在末尾添加列；「工作流」页面仍用于总览全局流水线和技能。执行状态与业务列相互独立，因此 InProgress 列并非必需。周期性工作使用列计划任务。Agent 可通过 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）
• 通过 Entity Framework Core 使用 SQLite（每个项目一个数据库）
• OpenAPI，自动生成 Markdown 文档
• Agent 执行：至少需要一个受支持的 CLI —— Claude Code CLI、OpenAI Codex CLI、Grok Build 或 Mistral Vibe。Ollama 和 DeepSeek V4 可通过 Claude Code 使用。请参阅汇总的 Agent 提供方安装指南。
• 可选，用于初始化代码仓库、集成工作树和 Agent 提交：Git

开始使用

Windows 安装程序

从最新发布版本下载 Ekioo.KittyClaw-win-Setup.exe（该版本包含 Windows 安装程序时）。运行安装程序，确认安装，然后通过桌面或「开始」菜单快捷方式启动 KittyClaw。 Windows x64 安装程序包含 .NET、ASP.NET Core 和 Windows Desktop 运行时； 无需安装 SDK 或单独安装 .NET。Agent CLI 仍需单独安装并完成身份验证（请参阅提供方指南）。

KittyClaw 会在浏览器中打开，并常驻通知区域。双击其图标即可重新打开，或从菜单中选择 Quit KittyClaw 将其停止。安装仅对当前用户生效，路径为 %LOCALAPPDATA%/Ekioo.KittyClaw；项目数据保留在 %APPDATA%/KittyClaw。

更新横幅会提供 Download update，随后提供 Update and restart。下载不会中断工作；当 Agent 正在工作或正在进行受跟踪的收尾操作时，会阻止安装。 请参阅 Windows 打包与更新，了解构建和发布详情。

从源代码运行

先决条件

• .NET 10 SDK
• PATH 中至少有一个 Agent CLI：Claude Code（claude）、OpenAI Codex（codex）、Grok Build（grok）或 Mistral Vibe（vibe）。本地模型和 DeepSeek 执行使用 Claude Code 作为传输方式；DeepSeek 还要求在项目的安全保险库中设置 DEEPSEEK_API_KEY。
• 可选：Git（PATH 中有 git），用于初始化仓库、集成工作树和 Agent 提交
• 可选：Rust Token Killer (RTK)（PATH 中有 rtk），用于显式优化每个项目的 shell 输出。KittyClaw 从不自动安装或配置它，并会在选择启用的运行中强制关闭其遥测。

首次启动时，引导弹窗会使用与任务分派相同的可执行文件解析路径检查 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 是否可用。任意一个 Agent 提供方即可满足要求；检查失败或超时不会阻塞启动，依赖 Git 的功能仍需要 Git。

运行

在仓库根目录中：

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

两者都会封装 dotnet watch --project KittyClaw.Web --non-interactive，并在 http://localhost:5230 提供应用，同时启用热重载。

创建项目

在首页选择 Create a project，输入名称并选择工作区。内置文件夹浏览器适用于 Windows、macOS 和 Linux，不会在浏览器后方打开系统原生对话框。它会显示主目录、已挂载的驱动器或文件系统根目录、面包屑导航、上级目录导航和直接路径输入框。你也可以输入绝对路径，并在文件夹不存在时创建它。

点击 Initialize 以：

1. 创建项目注册表条目和每个项目独立的 SQLite 数据库。
2. 将项目模板从 ProjectTemplate/（preamble.md、{agent}/SKILL.md、{agent}/memory/MEMORY.md 索引、memory-consolidation.md、agent-budget.json、CLAUDE.md）复制到工作区——Agent 文件放在 <workspace>/.agents/ 下，CLAUDE.md 放在工作区根目录。
3. 如果工作区尚不是 git 仓库，则运行 git init（如果未安装 git，则跳过）。
4. 为模板中找到的每个 Agent slug 创建一个成员。
5. 打开项目设置向导。

设置向导会分析现有工作区，并提出各不相同的流水线、列、人类交接环节、处理器、路由和计划安排。对于空文件夹，它会先询问一些关于项目用途、交付成果、人类决策和重复性工作的简短问题。提案以图形方式呈现：你可以添加或移除流水线、查看每条流水线的列、使用提示词完善一个步骤，并在批准前返回上一步。准备过程中不会创建任何内容；点击 Create the workflow 会应用并验证已批准的计划，然后打开看板。

现有流水线可以通过 Edit with assistant 进行完善。旧版自动化引擎及其迁移向导已退役。

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

数据存储

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

• registry.db — 项目注册表
• projects/{slug}.db — 每个项目的数据库（工单、评论、标签、列、成员）
• uploads/ — 上传的图像
• runs/{runId}.json — Agent 运行快照（事件、状态、退出代码）
• settings.json — 语言和引导标记

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

项目结构

路径	描述
KittyClaw.Core	领域模型、EF Core 上下文、服务、列工作流引擎、嵌入式项目模板
KittyClaw.Core.Tests	xUnit 测试（处理器、计划安排、Agent 执行、API、存储）
KittyClaw.Web	Blazor Server UI 和 REST API
KittyClaw.QaRunner	隔离测试实例启动器（Playwright 和场景运行器），由 qa-tester Agent 使用
KittyClaw.ClaudeMock	模拟的 claude CLI，供 KittyClaw.QaRunner 在测试中进行隔离式 Agent 调度
ProjectTemplate/	新项目初始化的权威来源。Agents/ 下的文件会写入 <workspace>/.agents/；CLAUDE.md 会写入工作区根目录。
tools/	仓库辅助工具（例如，publish-stable.ps1 用于打包 Web、QaRunner 和 ClaudeMock，以供稳定渠道使用）

架构

各功能的架构文档位于 docs/ 下。多流水线模型请从流水线和列处理开始了解，也可以查看 docs/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 提供内置的 MCP 端点（Streamable HTTP），让 MCP 客户端管理项目、工单和验收标准，配置列工作流和计划任务，监督 Agent 运行，并处理审批和工作树集成。从主页打开 Settings 并启用 MCP 服务，然后将其连接到 Claude Code：

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

该服务提供 73 个工具：9 个看板和验收标准工具，以及 64 个管理和可观测性工具。升级后请重新连接客户端，以刷新其工具目录。此端点默认禁用，可在不重启 KittyClaw 的情况下切换，并沿用 REST API 的 localhost 信任边界。请参阅完整的工具目录和操作约定。

面向 AI Agent

此应用专为 AI Agent 通过 REST API 操作而设计。以下是入门步骤：

1. 阅读实时 API 文档：访问 http://localhost:5230/api/docs——其中包含每个端点、请求/响应示例和架构，并始终与正在运行的服务保持同步。
2. 表明身份——每个修改数据的端点都必须提供 author；省略该字段会返回 HTTP 400。使用纯 Agent 名称（例如 "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"，AI Agent 使用纯 Agent 名称（例如 "programmer"）
• 优先级：Idea、NiceToHave、Required、Critical
• 默认列：Backlog

UI 功能

• 首次启动时显示引导弹窗，检查 Git、Claude Code、OpenAI Codex、Grok Build、Mistral Vibe 和 Ollama
• 跨平台应用内工作区浏览器，支持根目录、面包屑导航、直接输入路径和创建文件夹
• 引导式新项目设置：分析工作区，并在创建工作流前提出可编辑的流水线和列
• 可视化工作流规划和限定范围的流水线优化，同时保留已完成的工单
• 统一的多项目主页，包含项目卡片和看板泳道
• 多流水线看板：根据处理器路由，以不同视觉样式标示允许和禁止的投放目标
• 上下文相关的列编辑器，可配置结构、角色、负责人指导、处理器、有序操作、计划任务和路由
• 可自定义的仪表板视图，支持自由拖动磁贴（Markdown、KPI、图表、热力图、时间线等）、通过 AI 聊天创建磁贴，以及通过 LLM 提示词自动刷新
• 工单详情面板，包含评论和活动时间线
• 实时 Agent 运行抽屉（通过 SSE 流式传输提供方输出，并提供引导和停止控件）
• 新指令聊天抽屉，可向 Agent 发送临时提示词
• Markdown 渲染，支持通过 @mention、#id 和 #{slug}:{id} 引用跨项目工单
• 高级搜索语法：#42、@owner、>date、priority:critical、label:bug、by:owner；全局编号搜索也会显示带有直接父工单的嵌套工单，以供参考
• 子工单，支持父子关系和进度跟踪
• 通过 REST API 在项目之间无损、原子地转移工单树
• 可直接从看板管理列（插入、复制、重新排序、配置和标记为已读）
• 标签和成员管理
• 在描述和评论中上传图片
• 支持本地模型（Ollama）：按项目设置基础 URL 并自动发现模型、为每位成员设置默认模型，以及按处理器配置模型
• 通过 Claude Code、OpenAI Codex、Grok Build、Mistral Vibe 或 Ollama 智能分发任务，支持对话交接和不可用模型回退
• 可选的按项目 RTK 指导，用于生成精简的 Shell 输出；检测范围受限、遥测强制关闭，并保留未经更改的原始命令回退

仪表板

每个项目除了看板外，还提供可自定义的仪表板视图。磁贴可自由拖动并按计划自动刷新，也可通过应用内 AI 聊天面板创建或编辑——Agent 会为你编写磁贴文件夹。

### 磁贴类型

模板 ID	渲染内容
markdown	自由格式的 Markdown 内容
table	包含表头和行的表格数据
kpi	带标签和可选变化值的单个大数字
kpi-grid	多个 KPI 卡片组成的网格
progress	显示当前值 / 目标值的进度条
sparkline	紧凑的内联趋势线
bar-chart	垂直或水平条形图
donut	显示分类比例的环形图 / 饼图
gauge	显示有限范围数值的径向仪表
status-grid	由彩色状态标签（正常 / 异常 / 警告）组成的网格
heatmap	按日历样式显示一段时间内强度的热力图
leaderboard	带分数的排名列表
timeline	按时间顺序排列的事件列表
image	静态或刷新的图片
mermaid	Mermaid 图表（流程图、时序图，……）

文件夹布局

每个磁贴都位于项目工作区中 .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 时发送给 Agent 的指令。

在仪表板的 AI 聊天面板中描述所需内容，即可创建磁贴——Agent 会选择模板、编写 tile.yaml、生成刷新脚本并创建初始 output.json。

成本报告

Costs 页面提供缓存的按项目 Agent 使用情况视图，因此即使运行历史很长，打开报告也会立即显示。日期预设可快速选择常用时段，同时可组合使用项目、流水线和模型筛选条件；流水线选项会自动根据所选项目更新。每日图表中会通过醒目的图例区分实测成本和估算成本。

自动化模型

• 触发器：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 执行聚焦任务，整理 Agent 的 memory/ 索引和主题文件）→ commitAgentMemory（提交结果）。

遥测

KittyClaw 每天向一项便于自托管的分析服务（Umami）发送 一次匿名心跳，以便我们了解有多少实例在运行，以及实际使用中的版本。负载恰好包含以下三个字段，不包含其他内容：

• 一个随机实例 ID（首次运行时在本地生成的 GUID，与任何用户、机器或项目数据均无关联）
• KittyClaw 版本
• OS 系列（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 许可证；应用为你生成的一切内容（工单、日志、Agent 提交等）都归你所有，不受许可证限制。使用 KittyClaw 管理项目绝不会使该项目受 AGPL 约束。
• 过去的版本：截至 v0.11（含）的版本均根据 MIT 许可证发布，并继续按该许可证提供。

---

更多项目与联系方式

→ 网站与演示： kittyclaw.dev

→ 社区展示： 使用 KittyClaw 的项目

欢迎访问 ekioo.com，了解我的其他项目。

在 X 上关注我：@DamienHOFFSCHIR