🎉 init: 小龙的工作空间
This commit is contained in:
大海
@@ -0,0 +1,44 @@
|
||||
# 错误处理规范
|
||||
|
||||
> 从 Claude Code 的 `categorizeRetryableAPIError()` + `isTerminalTaskStatus()` 模式迁移。
|
||||
|
||||
## 错误三分类
|
||||
|
||||
```
|
||||
类别 处理方式 例子
|
||||
───── ────────── ──────────
|
||||
可重试 退避重试（3次） 网络超时、API 限流
|
||||
不可重试 立即报告 权限不足、参数非法
|
||||
用户取消 静默终止 用户中断、超时退出
|
||||
```
|
||||
|
||||
## 具体规则
|
||||
|
||||
### 网络/API 相关
|
||||
- 首次失败等待 2s → 第二次 5s → 第三次报告失败
|
||||
- 网络超时不等同于系统故障，一律重试
|
||||
- 重试时保持操作幂等（不产生重复副作用）
|
||||
|
||||
### 文件操作
|
||||
- 写文件前置检查路径合法性
|
||||
- 移动/删除文件用 `mv` 而非 `rm`（保留恢复可能）
|
||||
- 目录创建用 `mkdir -p` 确保幂等
|
||||
|
||||
### 执行命令
|
||||
- `exec` 失败时先看 stderr，非零退出不等同于失败
|
||||
- `timeout` 后进程可能仍在运行，需 `process kill` 清理
|
||||
- 用 `pipefail` 确保中间步骤失败能被检测
|
||||
|
||||
### 用户取消
|
||||
- 用户中断（如 `Ctrl+C`）不做重试
|
||||
- 已产生的副作用不回滚，但标记状态
|
||||
- 报告"已处理到哪一步"而非"失败了"
|
||||
|
||||
## Fast-Path 模式
|
||||
|
||||
```
|
||||
复杂操作前先问快速路径:
|
||||
1. 这个操作我能 10s 内完成吗？→ 直接干
|
||||
2. 需要用户决策？→ 先问再干
|
||||
3. 可能失败？→ 预估风险，必要时先问
|
||||
```
|
||||
@@ -0,0 +1,33 @@
|
||||
# Git 提交规范
|
||||
|
||||
> 从 Claude Code commit.ts 的"why not what"原则迁移。
|
||||
|
||||
## 提交消息格式
|
||||
|
||||
```
|
||||
<emoji> <简短描述>
|
||||
|
||||
<正文：说明"为什么"而非"做了什么"（可选）>
|
||||
```
|
||||
|
||||
## Emoji 约定
|
||||
|
||||
| Emoji | 含义 |
|
||||
|-------|------|
|
||||
| 🎉 | 初次提交 / 新项目 |
|
||||
| ✨ | 新功能 / 新模式 |
|
||||
| 🐛 | 修 bug |
|
||||
| 🔧 | 配置 / 工程变更 |
|
||||
| 📝 | 文档 / 记忆 |
|
||||
| ♻️ | 重构（行为不变） |
|
||||
| ⚡️ | 性能优化 |
|
||||
| 🧹 | 清理 / 删除 |
|
||||
| 🚀 | 部署 / 发布 |
|
||||
| 🐉 | 小龙专属（我的个人提交） |
|
||||
|
||||
## 原则
|
||||
|
||||
1. **消息说"为什么"** — 背景和动机，而非文件列表
|
||||
2. **正文说"怎样"** — 只有复杂变更需要正文
|
||||
3. **一个提交一件事** — 如果改了无关内容，拆提交
|
||||
4. **提交前先编译** — 确保 `git status` 干净
|
||||
@@ -0,0 +1,139 @@
|
||||
# 任务执行规范 — Planning vs Reactive
|
||||
|
||||
> 此规范是 AGENTS.md Execution Protocol 的详细参考。
|
||||
> 实际执行以 AGENTS.md（注入上下文）为准。
|
||||
|
||||
## 0. 总则 — 先分类，再执行
|
||||
|
||||
**收到任务后，第一步是分类，不是执行。**
|
||||
|
||||
- **Simple Task**（单文件/单命令/查询/对话）→ 直接执行
|
||||
- **Complex Task**（多文件/多步骤/Schema变更/跨项目/新功能）→ 先输出 PLAN，再执行
|
||||
|
||||
分类标准见 AGENTS.md §0. Complexity Classification。
|
||||
|
||||
## 1. 任务理解
|
||||
|
||||
明确回答以下问题：
|
||||
- 用户要解决什么问题？
|
||||
- 目标是什么？（可衡量的标准）
|
||||
- 输入是什么？（文件/参数/数据）
|
||||
- 输出是什么？（代码/文档/分析/配置）
|
||||
- 约束是什么？（时间/平台/兼容性/安全）
|
||||
- 风险是什么？（数据丢失/功能破坏/回滚难度）
|
||||
- 是否需要读文件/跑命令/查文档/测试？
|
||||
|
||||
**如果答案不明确，先问我，不要假设。**
|
||||
|
||||
## 2. 上下文建立
|
||||
|
||||
- 扫描项目顶层结构（`ls` / `find` / `wc -l`）
|
||||
- 扫描技术栈（`package.json` / `pyproject.toml` / `pom.xml` / `go.mod`）
|
||||
- 定位相关文件（入口文件、核心模块、配置文件）
|
||||
- 理解已有的代码风格和架构约定
|
||||
- 查找是否有类似已有实现
|
||||
|
||||
**不在没看项目的情况下写代码。**
|
||||
|
||||
## 3. 任务拆解
|
||||
|
||||
如果任务可以拆成多个子任务，必须拆解。每个子任务明确：
|
||||
- 任务目标
|
||||
- 输入 / 输出
|
||||
- 依赖关系 / 执行顺序
|
||||
- 验收标准
|
||||
- 失败处理策略
|
||||
|
||||
并行子任务要分别列出（前端/后端/数据库/配置/测试/文档）。
|
||||
|
||||
## 4. Skill 匹配
|
||||
|
||||
- 是否处理过类似任务？→ 查 MEMORY.md
|
||||
- 是否有类似项目的经验？→ 查 memory/daily/
|
||||
- 是否有已有的 skill？→ 查 tools/、scripts/
|
||||
- 如果有，优先复用并调整；如果没有，完成后判断是否创建新 skill
|
||||
|
||||
## 5. 方案设计
|
||||
|
||||
动手前给出方案：
|
||||
- 推荐方案是什么？
|
||||
- 为什么选这个？（选型理由）
|
||||
- 最小改动点是什么？
|
||||
- 影响范围是什么？
|
||||
- 风险是什么？
|
||||
- 如何验证？
|
||||
|
||||
**优先选择：低风险、可回滚、符合项目风格、可测试、可维护、不破坏现有功能。**
|
||||
|
||||
## 6. 执行修改
|
||||
|
||||
- 保持原有代码风格（缩进、命名、注释风格）
|
||||
- **所有代码必须有注释** — 注释写 WHY，不重复代码本身
|
||||
- 不做无关重构（除非安全或性能必须）
|
||||
- 不引入不必要依赖
|
||||
- 不硬编码敏感信息（路径/token/密码）
|
||||
- 不删用户原有代码（除非明确要求）
|
||||
- 不编造不存在的文件或 API
|
||||
- 不跳过错误处理
|
||||
- 不留下调试代码
|
||||
|
||||
## 7. 验证结果
|
||||
|
||||
明确回答：
|
||||
- 如何运行？（命令或操作）
|
||||
- 如何测试？（单元测试/集成测试/手动测试）
|
||||
- 如何构建？（编译/打包）
|
||||
- 如何手动验证？（UI 截图/日志/响应）
|
||||
- 边界情况覆盖了吗？
|
||||
- 失败时如何排查？
|
||||
|
||||
如果不能实际运行，也要给出用户可执行的验证命令。
|
||||
|
||||
## 8. 经验沉淀
|
||||
|
||||
任务完成后，必须判断：
|
||||
- 是否有可复用的经验？
|
||||
- 应创建 skill？（适用场景 + 输入 + 步骤 + 风险 + 验证 + 输出）
|
||||
- 应更新 MEMORY.md？
|
||||
- 应更新默认工作流？
|
||||
- 有不该再重复的错误？
|
||||
|
||||
**输出一段简短的"经验沉淀"。**
|
||||
|
||||
## 9. 输出格式
|
||||
|
||||
任务结果**必须**按以下格式组织：
|
||||
|
||||
```
|
||||
## 任务结果
|
||||
|
||||
说明完成了什么，解决了什么问题。
|
||||
|
||||
## 关键修改 / 关键判断
|
||||
|
||||
核心改动或核心分析，不列无关细节。
|
||||
|
||||
## 影响范围
|
||||
|
||||
涉及哪些模块、文件、接口、数据或页面。
|
||||
|
||||
## 验证方式
|
||||
|
||||
如何运行、测试、构建或手动验证。给出可执行命令。
|
||||
|
||||
## 风险与注意事项
|
||||
|
||||
可能的问题、后续建议、未处理的情况。
|
||||
|
||||
## 经验沉淀
|
||||
|
||||
可复用经验 / skill 建议 / memory 更新 / 工作流改进。
|
||||
```
|
||||
|
||||
## 10. 兜底原则
|
||||
|
||||
- **能读文件不靠猜**：不要假设文件内容，读它
|
||||
- **能跑命令不空想**：不确定就执行确认
|
||||
- **能测试不跳过**：改了什么要验证
|
||||
- **能回滚才动手**：没有安全退路的修改先问
|
||||
- **能问就别说"我猜"**：不确定就问，不丢人
|
||||
@@ -0,0 +1,38 @@
|
||||
# 工具定义规范
|
||||
|
||||
> 从 Claude Code `buildTool<T>()` 模式迁移而来。
|
||||
> 适用于需要"统一接口"的重复任务。
|
||||
|
||||
## 模式
|
||||
|
||||
所有工具调用遵循以下骨架：
|
||||
|
||||
```
|
||||
目的 + 输入 + 执行 + 输出 + 错误
|
||||
```
|
||||
|
||||
## 通用工具定义格式
|
||||
|
||||
```typescript
|
||||
// 伪代码思路：工具即定义
|
||||
Tool = {
|
||||
name: string, // 唯一名称
|
||||
description: string, // 一句话说明"为什么"有这个工具
|
||||
input: Schema, // 输入参数定义
|
||||
validate(input): // 前置校验（快速失败）
|
||||
run(input, ctx): // 核心执行
|
||||
error(e, ctx): // 错误处理（分级）
|
||||
}
|
||||
```
|
||||
|
||||
## 规则
|
||||
|
||||
1. **快速失败优先**：参数校验在 run 之前，不执行无效操作
|
||||
2. **输出确定性**：相同输入 + 相同状态 = 相同输出
|
||||
3. **错误分级**：可重试 / 不可重试 / 用户取消
|
||||
4. **执行时间预估**：10s 以内的直接干，以上的先汇报
|
||||
5. **不重复造轮子**：先看 tools/ 目录是否有已有工具
|
||||
|
||||
## 当前已定义工具
|
||||
|
||||
见 `tools/` 目录中的工具模板文件。
|
||||
Reference in New Issue
Block a user