@jun133/kitty 0.0.6 → 0.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +55 -51
- package/dist/cli.js +3959 -4624
- package/dist/cli.js.map +1 -1
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# 小猫智能体 Kitty
|
|
2
2
|
|
|
3
|
+
官网：https://agentjz.github.io/kitty/
|
|
4
|
+
|
|
3
5
|
<p align="center">
|
|
4
6
|
<strong>🐾 一个本地 agent 编程工作台：搜得到，看得懂，改得准，跑得通，记得住，能继续。</strong>
|
|
5
7
|
</p>
|
|
@@ -31,17 +33,18 @@
|
|
|
31
33
|
| 能力 | 当前事实 |
|
|
32
34
|
| --- | --- |
|
|
33
35
|
| 🧭 Agent 循环 | 模型、工具、session、收尾都在同一个主循环里推进 |
|
|
34
|
-
| 🧠 Context | 近场可见对话、项目上下文、项目地图、运行时上下文、工作记忆、工作集、长上下文压缩和预算报告 |
|
|
35
|
-
| 💾 Session | 会话记录、checkpoint、todo、工作集、恢复现场、结构化可审阅 memory assets |
|
|
36
|
-
| 🗺️ Project Map |
|
|
37
|
-
| 🔌 Provider | OpenAI-compatible provider、请求恢复、连接诊断 |
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
36
|
+
| 🧠 Context | 近场可见对话、项目上下文、项目地图、运行时上下文、工作记忆、工作集、长上下文压缩和预算报告 |
|
|
37
|
+
| 💾 Session | 会话记录、checkpoint、todo、工作集、恢复现场、结构化可审阅 memory assets |
|
|
38
|
+
| 🗺️ Project Map | 目录、入口、脚本、测试、仓库文档和 git 事实进入短项目地图 |
|
|
39
|
+
| 🔌 Provider | OpenAI-compatible provider、请求恢复、连接诊断 |
|
|
40
|
+
| ❄️ 缓存与省钱 | 读取 provider usage 里的缓存命中事实，记录 cache hit / miss / read / write，展示稳定前缀指纹和最近请求命中状态 |
|
|
41
|
+
| 🛠️ Core tools | `read`、`edit`、`write`、`bash` |
|
|
42
|
+
| 🧩 Extensions | `todo`、`worktree`、`network`、`background`、`subagent`、`skills` |
|
|
43
|
+
| 🧾 Control plane | SQLite 账本记录 task lifecycle、execution、deadline、输出健康、wait policy、pid、状态和 wake 事实；host 负责等待和恢复 lead |
|
|
44
|
+
| 📋 Plan 工作流 | `plan.md` 是当前任务总管，配合 plan skill 管理需求、事实、失败测试、目标、设计、任务、验证和收口 |
|
|
42
45
|
| 💬 产品面 | CLI、交互终端、Telegram 私聊服务 |
|
|
43
|
-
| 📎 证据记录 | session events、终端日志、崩溃记录、文件变更记录 |
|
|
44
|
-
| 🧪 Evaluation | `kitty eval`
|
|
46
|
+
| 📎 证据记录 | session events、终端日志、崩溃记录、文件变更记录 |
|
|
47
|
+
| 🧪 Evaluation | `kitty eval` 只暴露机器检查，`--run` 会跑本地检查闭环 |
|
|
45
48
|
|
|
46
49
|
## ⚡ 快速开始
|
|
47
50
|
|
|
@@ -58,45 +61,39 @@ npm.cmd run build
|
|
|
58
61
|
kitty init
|
|
59
62
|
```
|
|
60
63
|
|
|
61
|
-
启动交互式 agent：
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
kitty
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
如果已有会话，`kitty` 会先显示最近会话列表：输入 `1` 继续最近会话，输入 `0` 新建会话。没有历史会话时会直接新建。会话标题由模型在第一次真实对话完成后生成，后续保持稳定。
|
|
68
|
-
|
|
69
|
-
执行一次明确任务：
|
|
64
|
+
启动交互式 agent：
|
|
70
65
|
|
|
71
66
|
```bash
|
|
72
|
-
kitty
|
|
67
|
+
kitty
|
|
73
68
|
```
|
|
74
69
|
|
|
75
|
-
|
|
70
|
+
如果已有会话，`kitty` 会先显示最近会话列表：输入 `1` 继续最近会话，输入 `0` 新建会话。没有历史会话时会直接新建。会话标题由模型在第一次真实对话完成后生成，后续保持稳定。
|
|
71
|
+
|
|
72
|
+
执行一次明确任务：
|
|
76
73
|
|
|
77
74
|
```bash
|
|
78
|
-
kitty
|
|
75
|
+
kitty "检查这个仓库并修复失败测试"
|
|
79
76
|
```
|
|
80
77
|
|
|
81
|
-
## ⌨️ 常用命令
|
|
78
|
+
## ⌨️ 常用命令
|
|
82
79
|
|
|
83
80
|
| 命令 | 用途 |
|
|
84
81
|
| --- | --- |
|
|
85
82
|
| `kitty` | 进入默认 agent 交互；有历史会话时先选择继续或新建，也可直接接收一次性 prompt |
|
|
86
|
-
| `kitty agent` | 显式进入 agent 模式 |
|
|
87
|
-
| `kitty
|
|
88
|
-
| `kitty resume [sessionId]` | 恢复最近会话或指定会话 |
|
|
89
|
-
| `kitty sessions` | 查看最近会话 |
|
|
90
|
-
| `kitty events [sessionId]` | 查看最近会话或指定会话的机器事件 |
|
|
91
|
-
| `kitty config show` | 查看从 `.kitty/.env` 解析出的当前运行配置 |
|
|
83
|
+
| `kitty agent` | 显式进入 agent 模式 |
|
|
84
|
+
| `kitty background` | 查看后台任务；`wait <id>` 等待任务；`stop <id>` 停止任务 |
|
|
85
|
+
| `kitty resume [sessionId]` | 恢复最近会话或指定会话 |
|
|
86
|
+
| `kitty sessions` | 查看最近会话 |
|
|
87
|
+
| `kitty events [sessionId]` | 查看最近会话或指定会话的机器事件 |
|
|
88
|
+
| `kitty config show` | 查看从 `.kitty/.env` 解析出的当前运行配置 |
|
|
92
89
|
| `kitty config path` | 查看当前项目 `.kitty/.env` 路径 |
|
|
93
|
-
| `kitty status` | 查看当前项目现场：焦点、下一步、阻塞项、session、context budget、memory、skills、project map、execution、wake
|
|
94
|
-
| `kitty memory` | 创建、查看、读取、搜索、删除 runtime memory assets，或把 memory 沉淀到
|
|
90
|
+
| `kitty status` | 查看当前项目现场：焦点、下一步、阻塞项、session、context budget、memory、skills、project map、execution、wake |
|
|
91
|
+
| `kitty memory` | 创建、查看、读取、搜索、删除 runtime memory assets，或把 memory 沉淀到 skill references |
|
|
95
92
|
| `kitty changes` | 查看记录的文件变更 |
|
|
96
93
|
| `kitty undo [changeId]` | 撤销最近一次或指定变更 |
|
|
97
94
|
| `kitty diff [path]` | 查看当前 git diff |
|
|
98
|
-
| `kitty doctor` | 检查 `.kitty` 文件、env contract、provider preset、runtime、provider 连接和下一步 |
|
|
99
|
-
| `kitty eval` |
|
|
95
|
+
| `kitty doctor` | 检查 `.kitty` 文件、env contract、provider preset、runtime、provider 连接和下一步 |
|
|
96
|
+
| `kitty eval` | 查看机器检查；`kitty eval --run` 运行本地机器验收 |
|
|
100
97
|
| `kitty telegram serve` | 启动 Telegram 私聊服务 |
|
|
101
98
|
|
|
102
99
|
## 🛠️ 工具体系
|
|
@@ -117,20 +114,25 @@ Extension 是可启用、可禁用、独立存在的工具集合：
|
|
|
117
114
|
| `todo` | 会话级 todo 写入和可见 checklist |
|
|
118
115
|
| `worktree` | Git worktree 事实、创建、保留和删除 |
|
|
119
116
|
| `network` | HTTP session、请求、探测、下载、trace、OpenAPI 检查 |
|
|
120
|
-
| `background` | 后台命令执行、运行输出摘要、deadline、last output
|
|
121
|
-
| `subagent` | 聚焦子执行启动、派工边界、deadline、状态检查、worker 结论回传、wait policy、lead 挂起与 wake 恢复 |
|
|
122
|
-
| `skills` | 项目运行时 skill 包索引、正文加载、资源读取和脚本运行；使用事实进入 observability 和 task lifecycle |
|
|
123
|
-
|
|
117
|
+
| `background` | 后台命令执行、运行输出摘要、deadline、last output、检查、等待、停止和生命周期记录 |
|
|
118
|
+
| `subagent` | 聚焦子执行启动、派工边界、deadline、状态检查、worker 结论回传、wait policy、lead 挂起与 wake 恢复 |
|
|
119
|
+
| `skills` | 项目运行时 skill 包索引、正文加载、资源读取和脚本运行；使用事实进入 observability 和 task lifecycle |
|
|
120
|
+
|
|
121
|
+
默认 agent 会启用 `todo`、`worktree`、`network`、`background`、`subagent`、`skills`。
|
|
124
122
|
|
|
125
|
-
|
|
123
|
+
Runtime skills 放在项目 `SKILL.md`、`.skills/**/SKILL.md` 或 `skills/**/SKILL.md`。默认上下文只显示 skill 名称、说明、路径、健康状态和资源索引；完整正文必须由模型明确调用 `skill_load` 后进入当前轮。Skill 包内的 `references/`、`scripts/`、`examples/` 和 `assets/` 会作为资源分组出现，需要时用 `skill_read_resource` 读取资源，或用 `skill_run_script` 运行已声明的 `scripts/` 资源。Skill frontmatter 可用 `requires` 声明命令依赖，运行时用 `skill_check` 检查包健康和依赖可用性。`.codex/skills/**` 是 Codex 维护本仓库用的开发规范，不属于小猫运行时 skill。
|
|
126
124
|
|
|
127
|
-
|
|
125
|
+
当前仓库内置四个开发阶段 runtime skill：`research`、`plan`、`do`、`verification`。其中 `plan` 强制把 `plan.md` 写成单文件规格驱动执行合同：需求文档、当前事实、失败测试、目标、不做范围、设计、实施任务、验证计划和收口记录都在一个文件里闭环。
|
|
128
126
|
|
|
129
127
|
Provider 请求优先携带同 session 的近场可见对话。短会话不靠账本拼上下文；长会话超预算时摘要旧对话，保留最近对话 tail。Session memory 由模型在 turn 收口时按固定 Markdown 区块写出：`Current Focus`、`User Constraints`、`Decisions`、`Open Threads`、`Verification Facts`、`Reusable Lessons`。机器只维护格式和保存边界，不替模型判断事实重要性。
|
|
130
128
|
|
|
129
|
+
Provider usage 会归一化缓存事实：DeepSeek 的 `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`，OpenAI 的 `prompt_tokens_details.cached_tokens`，Anthropic 的 `cache_read_input_tokens` / `cache_creation_input_tokens`，以及 Gemini cached content tokens。`model.request` observability 事件会记录这些字段，`kitty status` 会显示最近模型请求的缓存命中和 context cache layout。OpenAI 请求会使用同 session 稳定 `prompt_cache_key`；DeepSeek 不写无效 `cache_control`，优先保持稳定前缀和命中观测。
|
|
130
|
+
|
|
131
|
+
`kitty eval --run` 包含 cache economy 检查：usage 字段解析、provider cache policy 和 stable prefix fingerprint 都必须能机器验证。真实省钱仍取决于 provider 是否返回 usage，以及同一 session 的前缀是否真的被上游缓存命中。
|
|
132
|
+
|
|
131
133
|
Session workset 记录当前会话实际读过和改过的文件。`read` 成功后记录读取事实，`edit` / `write` 成功后记录变更事实和 change id。工作集会进入 session、working memory 和 `kitty status`，让用户看到当前任务真正碰过哪些文件。
|
|
132
134
|
|
|
133
|
-
Memory assets 分为 `session`、`project`、`user` 和 `evidence`。每条 asset 暴露 kind、id、title、scope、tags、路径和 evidence references。Session memory 由模型写，project/user/evidence assets 通过 `kitty memory --create <kind> --title <title> --content <content>` 创建成可审阅 Markdown 资产。`kitty memory -q <query>` 做多词候选召回，只返回命中的资产和证据行，不替模型判断语义重要性。`kitty memory <memoryId> --append-to-
|
|
135
|
+
Memory assets 分为 `session`、`project`、`user` 和 `evidence`。每条 asset 暴露 kind、id、title、scope、tags、路径和 evidence references。Session memory 由模型写，project/user/evidence assets 通过 `kitty memory --create <kind> --title <title> --content <content>` 创建成可审阅 Markdown 资产。`kitty memory -q <query>` 做多词候选召回，只返回命中的资产和证据行，不替模型判断语义重要性。`kitty memory <memoryId> --append-to-skill <skillName>` 可以写入该 skill 的 `references/`。这条路径只沉淀已保存事实，不替模型判断哪些经验值得复用。
|
|
134
136
|
|
|
135
137
|
查看配置：
|
|
136
138
|
|
|
@@ -142,9 +144,9 @@ kitty config show
|
|
|
142
144
|
|
|
143
145
|
## ⚙️ 配置
|
|
144
146
|
|
|
145
|
-
项目运行配置只从 `.kitty/.env` 读取。初始化后按 `.kitty/.env` 填写当前启用的 provider、模型、API key 和 profile。
|
|
146
|
-
|
|
147
|
-
`kitty init` 创建 `.kitty/.env`、`.kitty/.env.example` 和 `.kitty/.kittyignore`，并输出本地配置 preflight 和下一步。`kitty doctor` 先检查这些本地事实，再加载 runtime，最后在 API key 存在时探测 provider 连接；失败时说明该补什么，成功时说明可以启动 Kitty。
|
|
147
|
+
项目运行配置只从 `.kitty/.env` 读取。初始化后按 `.kitty/.env` 填写当前启用的 provider、模型、API key 和 profile。
|
|
148
|
+
|
|
149
|
+
`kitty init` 创建 `.kitty/.env`、`.kitty/.env.example` 和 `.kitty/.kittyignore`，并输出本地配置 preflight 和下一步。`kitty doctor` 先检查这些本地事实，再加载 runtime，最后在 API key 存在时探测 provider 连接；失败时说明该补什么，成功时说明可以启动 Kitty。
|
|
148
150
|
|
|
149
151
|
`.kitty/.env` 放当前启用的 provider 和 API key，同时保留 YLS、TTAPI、DeepSeek 三组 provider preset 注释块，方便直接切换。Telegram、扩展开关和运行时配置也在 `.kitty/.env` 与 `.kitty/.env.example` 中保持同一结构。
|
|
150
152
|
|
|
@@ -172,18 +174,19 @@ kitty config show
|
|
|
172
174
|
| Provider / Config | `src/provider/`, `src/config/` |
|
|
173
175
|
| Core tools | `src/tools/` |
|
|
174
176
|
| Extensions | `src/extensions/` |
|
|
175
|
-
| Runtime skills | `src/skills/`, `skills/` |
|
|
176
|
-
| Project map | `src/project/map.ts` |
|
|
177
|
-
| Memory assets | `.kitty/memory/sessions/`, `.kitty/memory/project/`, `.kitty/memory/user/`, `.kitty/memory/evidence/` |
|
|
178
|
-
| Control plane | `src/control/`, `src/execution/` |
|
|
179
|
-
| Spec runtime | `src/spec/` |
|
|
177
|
+
| Runtime skills | `src/skills/`, `skills/` |
|
|
178
|
+
| Project map | `src/project/map.ts` |
|
|
179
|
+
| Memory assets | `.kitty/memory/sessions/`, `.kitty/memory/project/`, `.kitty/memory/user/`, `.kitty/memory/evidence/` |
|
|
180
|
+
| Control plane | `src/control/`, `src/execution/` |
|
|
180
181
|
| Host 边界 | `src/host/` |
|
|
181
|
-
| Session events | `.kitty/events/`, `src/session/events.ts` |
|
|
182
|
+
| Session events | `.kitty/events/`, `src/session/events.ts` |
|
|
182
183
|
| CLI / Shell / Telegram | `src/cli/`, `src/shell/`, `src/telegram/` |
|
|
183
184
|
| Runtime UI | `src/runtime-ui/` |
|
|
184
185
|
| Observability | `src/observability/` |
|
|
185
186
|
| Evaluation | `src/evaluation/`, `tests/evaluation/` |
|
|
186
|
-
|
|
|
187
|
+
| 产品宣传页 | `site/` |
|
|
188
|
+
| GitHub Pages 发布 | `.github/workflows/pages.yml` |
|
|
189
|
+
| 项目文档 | `spec/` |
|
|
187
190
|
| Tests | `tests/` |
|
|
188
191
|
|
|
189
192
|
## 🧪 开发
|
|
@@ -213,4 +216,5 @@ npm.cmd run verify
|
|
|
213
216
|
- `spec/用户审阅/宪法原则/`
|
|
214
217
|
- `spec/技术实现/`
|
|
215
218
|
|
|
216
|
-
|
|
219
|
+
项目文档、代码和测试共同描述同一个当前现实。项目入口、配置、文档和测试都跟随当前实现同步维护。
|
|
220
|
+
|