Metadata-Version: 2.4
Name: kimi-dev-workflow
Version: 0.1.0
Summary: 让 Kimi CLI 像 Cursor 一样理解你的代码库
Project-URL: Homepage, https://github.com/<GITHUB_USERNAME>/kimi-dev-workflow
Project-URL: Repository, https://github.com/<GITHUB_USERNAME>/kimi-dev-workflow
Project-URL: Issues, https://github.com/<GITHUB_USERNAME>/kimi-dev-workflow/issues
Author: Kimi Dev Workflow Contributors
License: MIT
License-File: LICENSE
Keywords: ai,cli,code-index,kimi,memory,wiki
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🚀 Kimi Dev Workflow

> 让 Kimi CLI 像 Cursor 一样理解你的代码库 —— 本地优先、隐私安全、零费用。

## 是什么

一套完整的 **Kimi CLI + 代码索引** 开发工作流模板，包含：

- 📦 **自动代码索引** — 语义搜索你的整个代码库
- 📖 **Repo Wiki 集成** — 让 AI 读懂你的业务知识和架构文档
- 🧠 **Agent 记忆系统** — 自动记录决策、偏好和踩坑经验，越用越聪明
- 📝 **Prompt 模板** — 搜索/编写/重构/调试/审查/Wiki/记忆 7 大场景
- 🏗️ **项目上下文注入** — AGENTS.md 让 AI 理解你的架构
- ⚡ **一键脚本** — 启动/停止/搜索索引、管理 Wiki
- 🎯 **最佳实践** — 文件投喂策略、上下文管理

## 快速开始（2 分钟）

### 1. 安装

```bash
# 方式一：pip（推荐）
pip install kimi-dev-workflow

# 方式二：curl 一键安装
curl -fsSL https://raw.githubusercontent.com/<GITHUB_USERNAME>/kimi-dev-workflow/main/install.sh | sh
```

### 2. 安装依赖（如果还没装）

```bash
# Kimi CLI
curl -fsSL https://cli.moonshot.cn/install.sh | sh

# grepai — 本地代码索引工具
curl -fsSL https://raw.githubusercontent.com/yoanbernabeu/grepai/main/install.sh | INSTALL_DIR=$HOME/.local/bin sh

# Ollama — 本地 Embedding 推理
# macOS: https://ollama.com/download
# Linux: curl -fsSL https://ollama.com/install.sh | sh

# 下载轻量嵌入模型
ollama pull all-minilm:l6-v2
```

### 3. 初始化项目

```bash
cd your-project

# 一键初始化（自动检测项目类型、生成 AGENTS.md、复制模板）
kimi-dev init

# 或从 GitHub Wiki 克隆并初始化
kimi-dev init --wiki-url https://github.com/<USER>/<REPO>.wiki.git

# 非交互模式（CI/CD 场景）
kimi-dev init --yes
```

### 4. 启动索引

```bash
kimi-dev index start
# 等待索引完成（首次约 20-40 分钟，取决于项目大小）
```

### 5. 开始开发

```bash
kimi
> 帮我找一下用户认证的代码
> 参照 @src/pages/login.tsx 新增一个注册页面
> 搜索 wiki 中关于订单状态机的业务规则
```

---

## 📁 文件结构

```
your-project/
├── .kimi/                      ← 复制自 templates/.kimi/
│   ├── prompts/               ← Prompt 模板库
│   │   ├── 01-search.md      ← 代码搜索与分析
│   │   ├── 02-code.md        ← 新代码编写
│   │   ├── 03-refactor.md    ← 代码重构
│   │   ├── 04-debug.md       ← Bug 调试
│   │   ├── 05-review.md      ← 代码审查
│   │   ├── 06-wiki.md        ← 基于 Wiki 知识开发
│   │   └── 07-memory.md      ← 基于记忆的智能开发
│   ├── memory.md             ← Agent 记忆库（自动维护）
│   └── README.md              ← 项目级工作流指南
├── AGENTS.md                  ← 你的项目上下文（必须！）
├── wiki/                      ← Repo Wiki 知识库
│   ├── 01-getting-started.md
│   ├── 02-architecture.md
│   └── ...
├── .grepaiignore             ← 索引排除规则
└── .grepai/                   ← 自动生成的索引数据
```

---

## 📝 核心概念

### AGENTS.md — 让 AI 理解你的项目

这是**最重要**的文件。Kimi CLI 会自动读取它并注入到每次对话中。

模板：`templates/AGENTS.md.template`，替换以下占位符：

```markdown
# {项目名} — 项目架构与开发规范

## 技术栈
- 框架：{React/Vue/Angular} + {TypeScript/JavaScript}
- 构建：{Vite/Webpack}
- 状态：{Zustand/Redux/Pinia}
- 路由：{React Router/Vue Router}
- 样式：{Tailwind/Styled Components}

## 目录结构
- /src/pages/ — 页面组件
- /src/components/ — 复用组件
- /src/hooks/ — 自定义 hooks
- /src/stores/ — 状态管理
- /src/api/ — API 层
- /src/utils/ — 工具函数

## 编码规范
1. 组件用函数式 + Hooks
2. API 请求统一走封装层
3. 全局状态用 {store}，禁止直接修改
4. 表单校验用 {zod/yup}

## 常见问题定位
| 问题 | 定位路径 |
|------|---------|
| 路由跳转失败 | /src/router/ |
| 全局状态不更新 | /src/stores/ |
| API 请求报错 | /src/api/ 或封装 hooks |
```

### Prompt 模板 — 复用高效提问

项目目录 `.kimi/prompts/` 存放 7 大场景的 prompt 模板：

| 场景 | 用法 |
|------|------|
| 理解业务逻辑 | 打开 `01-search.md`，复制模板替换变量 |
| 新页面开发 | 打开 `02-code.md`，参照现有模式提问 |
| 重构代码 | 打开 `03-refactor.md`，指定需要改的文件 |
| 调试 Bug | 打开 `04-debug.md`，描述现象 |
| 审查代码 | 打开 `05-review.md`，贴 diff 或文件路径 |

### 索引排除 — 加速索引

`.grepaiignore` 控制哪些文件**不进入索引**，加速首次构建：

```
# 排除这些（默认值）
node_modules/
.git/
dist/
*.test.ts
*.spec.ts
*.css
*.md
public/

# 你的项目特定排除
types/auto-generated/
legacy/
mocks/
```

---

## 🛠️ kimi-dev 命令

安装后，在项目目录使用：

```bash
kimi-dev init                    # 初始化项目
kimi-dev index start             # 启动索引监听（后台）
kimi-dev index stop              # 停止索引进程
kimi-dev index status            # 查看索引状态
kimi-dev index search "关键词"    # 手动语义搜索代码
kimi-dev index reindex           # 重置并重新索引
kimi-dev wiki init [URL]         # 初始化 Wiki
kimi-dev wiki sync               # 同步远程 Wiki
kimi-dev wiki list               # 列出 Wiki 页面
kimi-dev wiki search "关键词"     # 搜索 Wiki
kimi-dev memory show             # 查看记忆文件
kimi-dev doctor                  # 诊断环境
kimi-dev version                 # 显示版本
```

---

## 💡 最佳实践

### 1. 文件投喂策略

```
✅ 精准投喂：     > 帮我看一下 @src/api/auth.ts 的登录逻辑
✅ 语义搜索：     > 搜索所有处理 JWT token 刷新的代码
✅ 参照模式：     > 参照 @src/pages/list.tsx 新增一个详情页
✅ AGENTS.md：   自动注入，无需手动

❌ 避免全量：     > 帮我改一下 @.    ← 浪费 token，效果差
```

### 2. 会话管理

```bash
# 长会话 (>20 轮) 后压缩上下文
> /compact

# 复杂任务前先制定计划
> /plan

# 信任项目开快速模式（自动批准文件修改）
kimi --yolo
```

### 3. 性能优化

| 优化项 | 效果 |
|--------|------|
| 使用 all-minilm:l6-v2 模型 | 比 nomic-embed-text 快 3-5 倍 |
| 配置 .grepaiignore 排除无关文件 | 减少 30-60% 索引时间 |
| 精准 @ 文件 | 节省上下文窗口 token |
| 定期 `/compact` | 防止长会话变笨 |

---

## 🔒 隐私说明

| 数据 | 流向 | 说明 |
|------|------|------|
| 源代码 | ❌ 不上传 | 100% 本地 Ollama 处理 |
| Embedding 向量 | ❌ 不上传 | 本地 gob 文件存储 |
| Kimi API | ✅ 仅发送搜索结果 | 只传召回的代码片段，非全量 |

---

## 📚 更多

- [详细配置指南](docs/setup.md)
- [Prompt 模板详解](.kimi/prompts/README.md)
- [常见问题](docs/faq.md)

---

## 📖 Repo Wiki 快速参考

```bash
kimi-dev wiki init [URL]    # 初始化 Wiki
kimi-dev wiki sync          # 同步远程 Wiki
kimi-dev wiki list          # 列出所有页面
kimi-dev wiki search "关键词" # 语义搜索 Wiki
kimi-dev wiki status        # 查看状态
```

Wiki 文档会被自动纳入语义索引，agent 可在对话中直接搜索利用。

---

## 🧠 Agent 记忆快速参考

Agent 记忆是**自动运作**的：

- **读取**：agent 在开始任务前自动搜索 `.kimi/memory.md`
- **写入**：agent 在完成任务后自动追加决策、偏好、踩坑记录
- **索引**：记忆文件进入语义索引，支持自然语言搜索
- **持久**：git 管理，跨会话、跨设备同步

```bash
kimi-dev memory show        # 查看记忆文件
```

---

**License**: MIT  
**Made with ❤️ for Kimi CLI users**
