code-copilot 1.0.0

package/core/agents/spec-reviewer.md

@@ -0,0 +1,67 @@
+# Spec Compliance Reviewer
+
+专职验证代码实现是否符合 spec 规格。**只读不写**，独立于实现者的上下文。
+
+## 核心理念
+
+**不信报告，只信代码** — reviewer 必须读取实际代码独立验证，不能仅凭实现者的报告下结论。
+
+## 身份
+
+你是一个严格的 Spec 合规审查员。你的唯一职责是比对 spec 与代码，找出偏差。
+
+## 审查流程
+
+1. 读取 `changes/<变更名>/spec.md`，理解每个功能点的预期行为
+2. 读取 `changes/<变更名>/tasks.md`，了解任务拆分和涉及文件
+3. **逐个读取涉及的代码文件**，用 Grep/Read 工具验证实际实现
+4. 逐条比对 spec 功能点与实际代码
+5. 输出审查报告
+
+## 审查维度
+
+| 维度 | 检查内容 | 严重程度 |
+|------|---------|---------|
+| **缺失实现** | spec 要求了但代码没做 | ❌ FAIL |
+| **多余实现** | spec 没要求但代码多做了（YAGNI 违规） | ⚠️ WARN |
+| **理解偏差** | 做了但做错了方向 | ❌ FAIL |
+| **业务规则落地** | spec 中的业务规则是否全部体现在代码中 | ❌ FAIL |
+| **数据变更准确性** | spec 中的表/字段变更是否准确落地 | ❌ FAIL |
+
+## 输出格式
+
+```markdown
+# Spec Compliance Review — <变更名>
+
+## 功能点逐条验证
+
+### 功能 1: <功能名>
+- **Spec 要求**: (简述 spec 中的预期)
+- **代码实现**: (简述实际代码做了什么)
+- **文件出处**: `path/to/File.java:L行号`
+- **结论**: ✅ 合规 / ❌ 不合规（原因）/ ⚠️ 有偏差（说明）
+
+### 功能 2: <功能名>
+(同上格式)
+
+## 总结
+
+- ✅ 合规: N 个
+- ❌ 不合规: N 个
+- ⚠️ 偏差: N 个
+
+## 最终结论
+
+**✅ Spec 合规** / **❌ 不合规**（附具体问题和修复建议）
+```
+
+## 工具权限
+
+仅需 Read / Grep / Glob / Bash（只读），**不需要写入权限**。
+
+## 约束
+
+- 不评价代码质量（那是 code-quality-reviewer 的职责）
+- 不提出改进建议（只判断是否符合 spec）
+- 不修改任何文件
+- 如果 spec 本身有歧义或矛盾，标记出来但不自行解释

package/core/knowledge/index.md

@@ -0,0 +1,31 @@
+# 知识索引
+
+> 领域知识的轻量索引。每条用一句话说清核心逻辑。
+> 格式：`- **触发关键词**: 一句话核心逻辑 → 包名.类名.方法名`（可选）
+>
+> 这个文件是知识飞轮的输出。通过 `/archive` 从变更日志中沉淀而来。
+> AI 在工作时会根据当前任务的关键词搜索此索引，加载相关知识。
+
+---
+
+## 业务知识
+
+> 与业务领域相关的核心逻辑和规则。
+
+- (待补充)
+
+---
+
+## 技术约定
+
+> 项目中非标准但重要的技术约定和最佳实践。
+
+- (待补充)
+
+---
+
+## 踩坑记录
+
+> 容易踩的坑、已知的坑、及解决方案。
+
+- (待补充)

package/core/rules/coding-style.md

@@ -0,0 +1,48 @@
+---
+alwaysApply: true
+---
+
+# 编码规范
+
+## 1. 命名
+
+- 类名：大驼峰（PascalCase），见名知意
+- 方法名：小驼峰（camelCase），动词开头
+- 常量：全大写下划线分隔（UPPER_SNAKE_CASE）
+- 抽象类以 `Abstract` 或 `Base` 开头
+- 测试类以被测类名开头，`Test` 结尾
+- 禁止拼音、中英混拼命名
+
+## 2. 异常处理
+
+- 业务异常使用自定义 `BizException`，携带错误码
+- 系统异常向上抛出，由统一异常处理器兜底
+- **禁止吞掉异常**（空 catch 块）
+- catch 中必须记录日志
+- 异常信息必须包含上下文（关键参数值、操作目标）
+
+## 3. 日志
+
+- Controller 入口打 INFO，含请求关键参数
+- Service 关键业务节点打 INFO
+- 异常打 ERROR，含完整堆栈
+- **禁止在日志中打印用户敏感信息**（手机号、身份证、银行卡等）
+
+## 4. 接口设计
+
+- 写接口必须考虑幂等
+- 涉及并发场景必须说明同步策略（加锁/乐观锁/队列）
+- 入参必须有校验（`@Valid` / 手动校验）
+- 返回值必须包装（统一响应格式）
+
+## 5. 代码质量
+
+- 魔法值必须定义为常量
+- 单个方法不超过 80 行（超长需拆分并说明原因）
+- 单个类不超过 500 行
+- 圈复杂度不超过 10
+- 嵌套层级不超过 4 层
+
+## 6. 项目特定规范
+
+> 在实践中补充项目特有的编码约定。

package/core/rules/domain-rules.md

@@ -0,0 +1,30 @@
+---
+alwaysApply: false
+description: "当涉及业务领域特定逻辑时应用本规则"
+---
+
+# 业务领域约束
+
+## 1. 通用领域规则
+
+- 所有金额使用 `long` 类型，单位为**分**（避免浮点精度问题）
+- 时间字段统一使用项目标准时间类型
+- 外部接口调用必须设置超时（默认 3s）并做降级处理
+- 状态变更必须通过状态机，禁止直接 set 状态字段
+- 分布式操作必须考虑幂等性和顺序性
+- 配置变更必须有灰度机制，禁止全量生效
+
+## 2. 项目特定规则
+
+> 在实践中补充项目特有的业务规则。
+> 格式：`- **场景**: 规则描述 → 涉及的类/方法`
+
+- (待补充)
+
+## 3. 领域术语表
+
+> 项目中的业务术语定义，避免歧义。
+
+| 术语 | 定义 | 备注 |
+|------|------|------|
+| (待填充) | | |

package/core/rules/project-context.md

@@ -0,0 +1,59 @@
+---
+alwaysApply: true
+---
+
+# 工程上下文
+
+> 首次使用时执行 `/init` 让 AI 分析工程并填充本文件。
+> 填充后，AI 在每次会话中都会参考这些信息来理解项目结构。
+
+## 1. 应用概况
+
+- **应用名**: (待填充)
+- **简介**: (一句话描述这个应用做什么)
+- **技术栈**: (待填充，如 Java 21 / Spring Boot 3.x / ...)
+- **构建工具**: (待填充，如 Maven / Gradle / npm / pnpm)
+- **包名/模块名**: (待填充)
+
+## 2. 目录结构与模块职责
+
+> 执行目录扫描后填充。按模块/包列出各目录的职责。
+
+```
+(待填充)
+```
+
+## 3. 分层架构
+
+> 根据项目实际分层模式填充。以下是常见的 Java 后端分层，仅供参考。
+
+```
+Controller (入口层)     ← 参数校验 + 协议转换
+    ↓
+Service (业务编排层)    ← 业务逻辑 + 事务边界
+    ↓
+Manager (领域能力层)    ← 单一职责 + 可复用
+    ↓
+DAO (数据访问层)        ← 纯数据访问
+```
+
+**项目实际分层**: (待填充)
+
+## 4. 关键依赖
+
+| 中间件/依赖 | 用途 | 备注 |
+|------------|------|------|
+| (待填充) | | |
+| (待填充) | | |
+
+## 5. 核心配置
+
+| 配置项 | 位置 | 说明 |
+|--------|------|------|
+| (待填充) | | |
+
+## 6. 特殊约定
+
+> 项目中非标准但重要的约定，如特殊的包命名规则、特殊的异常处理方式等。
+
+- (待填充)

package/core/rules/security.md

@@ -0,0 +1,37 @@
+---
+alwaysApply: true
+---
+
+# 安全红线
+
+## 1. 代码安全
+
+- ❌ **禁止**在代码中硬编码密钥、AK/SK、数据库密码
+- ❌ **禁止**提交包含用户个人信息的测试数据
+- ❌ **禁止**在日志中打印手机号、身份证、银行卡等敏感信息
+- ❌ **禁止**使用已知的废弃/不安全算法（如 MD5 做密码哈希）
+
+## 2. 业务安全
+
+- ⚠️ 涉及**资金变更**的逻辑，必须在 spec 中明确标注，人工审查后方可编码
+- ⚠️ 涉及**状态流转**的逻辑，必须检查状态机合法性
+- ⚠️ 涉及**权限变更**的逻辑，必须显式校验操作人权限
+- ⚠️ 涉及**批量数据操作**的逻辑，必须考虑性能影响和数据一致性
+
+## 3. 接口安全
+
+- 外部接口必须做参数校验，不信任任何外部输入
+- 涉及鉴权的接口必须有明确的权限标识
+- 文件上传必须校验文件类型、大小
+- SQL 必须使用参数化查询，禁止字符串拼接
+
+## 4. 数据安全
+
+- 敏感数据存储必须加密
+- 数据库查询必须有合理的索引支撑，防止慢查询
+- 批量操作必须考虑事务边界和回滚策略
+- 删除操作优先使用逻辑删除（软删除）
+
+## 5. 项目特定安全规则
+
+> 在实践中补充项目特有的安全约束。

package/core/templates/log.md

@@ -0,0 +1,51 @@
+# 变更日志 — $CHANGE_NAME
+
+> 记录决策、踩坑和知识发现。知识飞轮的输入。
+
+---
+
+## 时间线
+
+| 时间 | 阶段 | 事件 | 备注 |
+|------|------|------|------|
+| (待填充) | | | |
+
+---
+
+## 技术决策
+
+| 决策 | 选择 | 放弃的方案 | 原因 |
+|------|------|-----------|------|
+| (待填充) | | | |
+
+---
+
+## 踩坑记录
+
+| 问题 | 原因 | 解决方案 | 沉淀？ |
+|------|------|---------|--------|
+| (待填充) | | | ☐ |
+
+---
+
+## 知识发现
+
+> 每个 task 后实时记录，`/archive` 时逐条确认沉淀到 `knowledge/`
+
+- [ ] **关键词**: (描述这个发现) → `包名.类名.方法名`（可选）
+
+---
+
+## Spec-Code 偏差记录
+
+| 偏差点 | Spec 预期 | 实际情况 | 处理方式 |
+|--------|----------|---------|---------|
+| (待填充) | | | |
+
+---
+
+## 代码质量备忘
+
+> 记录执行过程中发现但未在 review 中体现的代码质量问题。
+
+- (待填充)

package/core/templates/spec.md

@@ -0,0 +1,140 @@
+# Spec — $CHANGE_NAME
+
+> status: propose | confirmed | apply | review | done
+> created: $DATE
+> complexity: 🟢简单 | 🟡中等 | 🔴复杂
+
+---
+
+## 1. 背景与目标
+
+**为什么做**：
+(描述需求来源、业务驱动、当前痛点)
+
+**做完后的效果**：
+(可验证的结果描述，如"用户可以在设置页开启/关闭消息推送，开关实时生效")
+
+---
+
+## 2. 代码现状（Research Findings）
+
+> 每个结论必须有代码出处（文件路径 + 类名/方法名）
+
+### 2.1 相关入口与链路
+
+- 入口：`path/to/Controller.java` → `ClassName.methodName()`
+- (待填充)
+
+### 2.2 现有实现
+
+- (描述与本次变更相关的现有代码逻辑)
+- (每个描述必须有出处：`path/to/File.java:L行号`)
+
+### 2.3 发现与风险
+
+- (代码侦察中发现的问题、潜在风险)
+- (待填充)
+
+---
+
+## 3. 功能点
+
+- [ ] **功能 1**：(输入→处理→输出)
+- [ ] **功能 2**：(输入→处理→输出)
+- (按需添加)
+
+---
+
+## 4. 业务规则
+
+| # | 规则描述 | 触发条件 | 备注 |
+|---|---------|---------|------|
+| 1 | (待填充) | | |
+
+---
+
+## 5. 数据变更
+
+| 操作 | 表名 | 字段/索引 | 说明 |
+|------|------|----------|------|
+| (待填充) | | | |
+
+---
+
+## 6. 接口变更
+
+| 操作 | 接口 | 方法 | 变更内容 |
+|------|------|------|---------|
+| (待填充) | | | |
+
+---
+
+## 7. 影响范围
+
+- **直接影响**：(哪些模块/服务会受到影响)
+- **间接影响**：(下游调用方、依赖方)
+- **不涉及**：(明确排除的范围)
+
+---
+
+## 8. 风险与关注点
+
+> ⚠️ 涉及资金/状态流转/权限变更必须标注
+
+| # | 风险描述 | 影响等级 | 缓解措施 |
+|---|---------|---------|---------|
+| (待填充) | | 🟢/🟡/🔴 | |
+
+---
+
+## 8.5 测试策略
+
+- **测试范围**：(哪些模块需要测试)
+- **覆盖率目标**：(核心逻辑 100%？新增代码 80%+？)
+- **独立 Test Spec**：是/否
+
+---
+
+## 9. 待澄清
+
+> 全部解决后才能进入 `/apply`
+
+- [ ] 问题 1：(待回答)
+- (按需添加)
+
+---
+
+## 10. 技术决策
+
+| 决策点 | 选择 | 放弃的方案 | 原因 |
+|--------|------|-----------|------|
+| (待填充) | | | |
+
+---
+
+## 11. 执行日志
+
+> 由 `/apply` 阶段自动填充
+
+| Task | 状态 | 实际改动文件 | 备注 |
+|------|------|------------|------|
+| (待填充) | | | |
+
+---
+
+## 12. 审查结论
+
+> 由 `/review` 阶段自动填充
+
+**Spec Compliance**: PASS / FAIL
+**Code Quality**: PASS / FAIL
+
+(待填充具体结论)
+
+---
+
+## 13. 确认记录（HARD-GATE）
+
+- **确认时间**: (待填充)
+- **确认人**: (待填充)
+- **确认内容**: spec.md + tasks.md 全部内容已审查并确认

package/core/templates/tasks.md

@@ -0,0 +1,58 @@
+# 任务拆分 — $CHANGE_NAME
+
+> 拆分原则：
+> - 顺序：数据模型 → 接口协议 → 底层实现 → 上层编排 → 入口层
+> - 每个任务 = 可独立提交的原子变更（3-5 个文件）
+> - 每个任务必须精确到文件路径和函数签名
+
+---
+
+## 前置条件
+
+- [ ] spec.md 已确认（HARD-GATE 通过）
+- [ ] (其他前置条件，如依赖的二方包是否就绪)
+
+---
+
+## Task 1: $TASK_NAME
+
+- **目标**: (一句话描述这个任务完成什么)
+- **涉及文件**:
+  - `path/to/File1.java` — 新增/修改，(做什么)
+  - `path/to/File2.java` — 新增/修改，(做什么)
+- **关键签名**:
+
+```
+(关键方法签名)
+```
+
+- **依赖**: 无 / Task N
+- **验收标准**: (怎样算完成)
+
+---
+
+## Task 2: $TASK_NAME
+
+(同上格式)
+
+---
+
+## Task 3: $TASK_NAME
+
+(同上格式)
+
+---
+
+(按需添加更多 Task)
+
+---
+
+## 变更摘要
+
+> `/apply` 全部完成后填写
+
+- **总文件数**: (待填充)
+- **新增文件**: (待填充)
+- **修改文件**: (待填充)
+- **Spec-Plan 偏差记录**: (如有偏差，记录在 log.md 中)
+- **遗留问题**: (待填充)

package/core/templates/test-spec.md

@@ -0,0 +1,62 @@
+# 单测 Spec — $CHANGE_NAME
+
+> status: propose | apply | done
+> created: $DATE
+
+---
+
+## 0. 测试原则
+
+- **Red/Green TDD**：测试必须先 Red 再 Green，跳过 Red 的测试无法证明有效
+- **First Run the Tests**：开始前先跑已有测试套件，了解框架和基线
+- **展示工作**：必须展示实际测试输出，禁止"测试通过"等无证据声明
+
+---
+
+## 1. 测试框架
+
+| 项目 | 值 |
+|------|-----|
+| 测试框架 | (JUnit 5 / pytest / Jest / ...) |
+| Mock 框架 | (Mockito / unittest.mock / ...) |
+| 已有测试数量 | (待填充) |
+| 已有测试风格 | (待填充) |
+
+---
+
+## 2. 覆盖范围
+
+### P0 — 核心业务逻辑（必须覆盖）
+
+#### 类名: $ClassName
+
+| 方法 | 场景 | 输入 | Mock 行为 | 预期结果 |
+|------|------|------|-----------|---------|
+| (待填充) | | | | |
+
+### P1 — 数据访问层
+
+| 方法 | 场景 | 输入 | Mock 行为 | 预期结果 |
+|------|------|------|-----------|---------|
+| (待填充) | | | | |
+
+### P2 — 入口层/服务层
+
+| 方法 | 场景 | 输入 | Mock 行为 | 预期结果 |
+|------|------|------|-----------|---------|
+| (待填充) | | | | |
+
+### 不测试（明确列出原因）
+
+| 类/方法 | 原因 |
+|--------|------|
+| (待填充) | |
+
+---
+
+## 3. 执行计划
+
+- [ ] **Step 1**: 运行已有测试套件，确认基线
+- [ ] **Step 2**: 生成 P0 测试 → 确认 Red → 确认 Green
+- [ ] **Step 3**: 生成 P1/P2 测试
+- [ ] **Step 4**: 运行完整测试套件，确认覆盖率

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "code-copilot",
+  "version": "1.0.0",
+  "description": "Progressive Spec Coding Framework — cross-platform AI coding collaboration",
+  "bin": {
+    "code-copilot": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "AGENTS.md",
+    "core/",
+    "adapters/"
+  ],
+  "keywords": [
+    "ai-coding",
+    "spec-driven",
+    "claude-code",
+    "cursor",
+    "cline",
+    "coding-framework",
+    "progressive-spec"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lawushanshan/code-copilot.git"
+  }
+}