@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/update-codemaps.md

@@ -0,0 +1,73 @@
+# 更新代码地图
+
+分析代码库结构并生成简洁的架构文档。
+
+## 步骤 1：扫描项目结构
+
+1. 识别项目类型（单体仓库、单应用、库、微服务）
+2. 查找所有源码目录（src/, lib/, app/, packages/）
+3. 映射入口点（main.ts, index.ts, app.py, main.go 等）
+
+## 步骤 2：生成代码地图
+
+在 `docs/CODEMAPS/`（或 `.reports/codemaps/`）中创建或更新代码地图：
+
+| 文件 | 内容 |
+|------|----------|
+| `architecture.md` | 高层系统图、服务边界、数据流 |
+| `backend.md` | API 路由、中间件链、服务 → 仓库映射 |
+| `frontend.md` | 页面树、组件层级、状态管理流 |
+| `data.md` | 数据库表、关系、迁移历史 |
+| `dependencies.md` | 外部服务、第三方集成、共享库 |
+
+### 代码地图格式
+
+每个代码地图应为简洁风格 —— 针对 AI 上下文消费进行优化：
+
+```markdown
+# 后端架构
+
+## 路由
+POST /api/users → UserController.create → UserService.create → UserRepo.insert
+GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
+
+## 关键文件
+src/services/user.ts (业务逻辑，120行)
+src/repos/user.ts (数据库访问，80行)
+
+## 依赖项
+- PostgreSQL (主要数据存储)
+- Redis (会话缓存，速率限制)
+- Stripe (支付处理)
+```
+
+## 步骤 3：差异检测
+
+1. 如果存在先前的代码地图，计算差异百分比
+2. 如果变更 > 30%，显示差异并在覆盖前请求用户批准
+3. 如果变更 <= 30%，则原地更新
+
+## 步骤 4：添加元数据
+
+为每个代码地图添加一个新鲜度头部：
+
+```markdown
+<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
+```
+
+## 步骤 5：保存分析报告
+
+将摘要写入 `.reports/codemap-diff.txt`：
+
+* 自上次扫描以来添加/删除/修改的文件
+* 检测到的新依赖项
+* 架构变更（新路由、新服务等）
+* 超过 90 天未更新的文档的陈旧警告
+
+## 提示
+
+* 关注**高层结构**，而非实现细节
+* 优先使用**文件路径和函数签名**，而非完整代码块
+* 为高效加载上下文，将每个代码地图保持在 **1000 个 token 以内**
+* 使用 ASCII 图表表示数据流，而非冗长的描述
+* 在主要功能添加或重构会话后运行

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/update-docs.md

@@ -0,0 +1,86 @@
+# 更新文档
+
+将文档与代码库同步，从单一事实来源文件生成。
+
+## 步骤 1：识别单一事实来源
+
+| 来源 | 生成内容 |
+|--------|-----------|
+| `package.json` 脚本 | 可用命令参考 |
+| `.env.example` | 环境变量文档 |
+| `openapi.yaml` / 路由文件 | API 端点参考 |
+| 源代码导出 | 公共 API 文档 |
+| `Dockerfile` / `docker-compose.yml` | 基础设施设置文档 |
+
+## 步骤 2：生成脚本参考
+
+1. 读取 `package.json` (或 `Makefile`, `Cargo.toml`, `pyproject.toml`)
+2. 提取所有脚本/命令及其描述
+3. 生成参考表格：
+
+```markdown
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | 启动带热重载的开发服务器 |
+| `npm run build` | 执行带类型检查的生产构建 |
+| `npm test` | 运行带覆盖率测试的测试套件 |
+```
+
+## 步骤 3：生成环境文档
+
+1. 读取 `.env.example` (或 `.env.template`, `.env.sample`)
+2. 提取所有变量及其用途
+3. 按必需项与可选项分类
+4. 记录预期格式和有效值
+
+```markdown
+| 变量 | 必需 | 描述 | 示例 |
+|----------|----------|-------------|---------|
+| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 | `postgres://user:pass@host:5432/db` |
+| `LOG_LEVEL` | 否 | 日志详细程度（默认：info） | `debug`, `info`, `warn`, `error` |
+```
+
+## 步骤 4：更新贡献指南
+
+生成或更新 `docs/CONTRIBUTING.md`，包含：
+
+* 开发环境设置（先决条件、安装步骤）
+* 可用脚本及其用途
+* 测试流程（如何运行、如何编写新测试）
+* 代码风格强制（linter、formatter、预提交钩子）
+* PR 提交清单
+
+## 步骤 5：更新运行手册
+
+生成或更新 `docs/RUNBOOK.md`，包含：
+
+* 部署流程（逐步说明）
+* 健康检查端点和监控
+* 常见问题及其修复方法
+* 回滚流程
+* 告警和升级路径
+
+## 步骤 6：检查文档时效性
+
+1. 查找 90 天以上未修改的文档文件
+2. 与最近的源代码变更进行交叉引用
+3. 标记可能过时的文档以供人工审核
+
+## 步骤 7：显示摘要
+
+```
+文档更新
+──────────────────────────────
+已更新：docs/CONTRIBUTING.md（脚本表格）
+已更新：docs/ENV.md（新增3个变量）
+已标记：docs/DEPLOY.md（142天未更新）
+已跳过：docs/API.md（未检测到变更）
+──────────────────────────────
+```
+
+## 规则
+
+* **单一事实来源**：始终从代码生成，切勿手动编辑生成的部分
+* **保留手动编写部分**：仅更新生成的部分；保持手写内容不变
+* **标记生成的内容**：在生成的部分周围使用 `<!-- AUTO-GENERATED -->` 标记
+* **不主动创建文档**：仅在命令明确要求时才创建新的文档文件

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/verify.md

@@ -0,0 +1,60 @@
+# 验证命令
+
+对当前代码库状态执行全面验证。
+
+## 说明
+
+请严格按照以下顺序执行验证：
+
+1. **构建检查**
+   * 运行此项目的构建命令
+   * 如果失败，报告错误并**停止**
+
+2. **类型检查**
+   * 运行 TypeScript/类型检查器
+   * 报告所有错误，包含文件:行号
+
+3. **代码检查**
+   * 运行代码检查器
+   * 报告警告和错误
+
+4. **测试套件**
+   * 运行所有测试
+   * 报告通过/失败数量
+   * 报告覆盖率百分比
+
+5. **Console.log 审计**
+   * 在源文件中搜索 console.log
+   * 报告位置
+
+6. **Git 状态**
+   * 显示未提交的更改
+   * 显示自上次提交以来修改的文件
+
+## 输出
+
+生成一份简洁的验证报告：
+
+```
+验证： [通过/失败]
+
+构建：    [成功/失败]
+类型：    [成功/X 错误]
+代码检查： [成功/X 问题]
+测试：    [X/Y 通过，Z% 覆盖率]
+密钥检查： [成功/X 发现]
+日志：     [成功/X console.logs]
+
+准备提交 PR： [是/否]
+```
+
+如果存在任何关键问题，列出它们并提供修复建议。
+
+## 参数
+
+$ARGUMENTS 可以是：
+
+* `quick` - 仅构建 + 类型检查
+* `full` - 所有检查（默认）
+* `pre-commit` - 与提交相关的检查
+* `pre-pr` - 完整检查加安全扫描

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/contexts/dev.md

@@ -0,0 +1,23 @@
+# 开发上下文
+
+模式：活跃开发中
+关注点：实现、编码、构建功能
+
+## 行为准则
+
+* 先写代码，后做解释
+* 倾向于可用的解决方案，而非完美的解决方案
+* 变更后运行测试
+* 保持提交的原子性
+
+## 优先级
+
+1. 让它工作
+2. 让它正确
+3. 让它整洁
+
+## 推荐工具
+
+* 使用 Edit、Write 进行代码变更
+* 使用 Bash 运行测试/构建
+* 使用 Grep、Glob 查找代码

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/contexts/research.md

@@ -0,0 +1,30 @@
+# 研究背景
+
+模式：探索、调查、学习
+重点：先理解，后行动
+
+## 行为准则
+
+* 广泛阅读后再下结论
+* 提出澄清性问题
+* 在研究过程中记录发现
+* 在理解清晰之前不要编写代码
+
+## 研究流程
+
+1. 理解问题
+2. 探索相关代码/文档
+3. 形成假设
+4. 用证据验证
+5. 总结发现
+
+## 推荐工具
+
+* `Read` 用于理解代码
+* `Grep`、`Glob` 用于查找模式
+* `WebSearch`、`WebFetch` 用于获取外部文档
+* 针对代码库问题，使用 `Task` 与探索代理
+
+## 输出
+
+先呈现发现，后提出建议

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/contexts/review.md

@@ -0,0 +1,25 @@
+# 代码审查上下文
+
+模式：PR 审查，代码分析
+重点：质量、安全性、可维护性
+
+## 行为准则
+
+* 评论前仔细阅读
+* 按严重性对问题排序（关键 > 高 > 中 > 低）
+* 建议修复方法，而不仅仅是指出问题
+* 检查安全漏洞
+
+## 审查清单
+
+* \[ ] 逻辑错误
+* \[ ] 边界情况
+* \[ ] 错误处理
+* \[ ] 安全性（注入、身份验证、密钥）
+* \[ ] 性能
+* \[ ] 可读性
+* \[ ] 测试覆盖率
+
+## 输出格式
+
+按文件分组发现的问题，严重性优先

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/examples/CLAUDE.md

@@ -0,0 +1,100 @@
+# 示例项目 CLAUDE.md
+
+这是一个示例项目级别的 CLAUDE.md 文件。请将其放置在您的项目根目录下。
+
+## 项目概述
+
+\[项目简要描述 - 功能、技术栈]
+
+## 关键规则
+
+### 1. 代码组织
+
+* 多个小文件优于少量大文件
+* 高内聚，低耦合
+* 每个文件典型 200-400 行，最多 800 行
+* 按功能/领域组织，而非按类型
+
+### 2. 代码风格
+
+* 代码、注释或文档中不使用表情符号
+* 始终使用不可变性 - 永不改变对象或数组
+* 生产代码中不使用 console.log
+* 使用 try/catch 进行适当的错误处理
+* 使用 Zod 或类似工具进行输入验证
+
+### 3. 测试
+
+* TDD：先写测试
+* 最低 80% 覆盖率
+* 工具函数进行单元测试
+* API 进行集成测试
+* 关键流程进行端到端测试
+
+### 4. 安全
+
+* 不硬编码密钥
+* 敏感数据使用环境变量
+* 验证所有用户输入
+* 仅使用参数化查询
+* 启用 CSRF 保护
+
+## 文件结构
+
+```
+src/
+|-- app/              # Next.js 应用路由
+|-- components/       # 可复用的 UI 组件
+|-- hooks/            # 自定义 React 钩子
+|-- lib/              # 工具库
+|-- types/            # TypeScript 定义
+```
+
+## 关键模式
+
+### API 响应格式
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+}
+```
+
+### 错误处理
+
+```typescript
+try {
+  const result = await operation()
+  return { success: true, data: result }
+} catch (error) {
+  console.error('Operation failed:', error)
+  return { success: false, error: 'User-friendly message' }
+}
+```
+
+## 环境变量
+
+```bash
+# Required
+DATABASE_URL=
+API_KEY=
+
+# Optional
+DEBUG=false
+```
+
+## 可用命令
+
+* `/tdd` - 测试驱动开发工作流
+* `/plan` - 创建实现计划
+* `/code-review` - 审查代码质量
+* `/build-fix` - 修复构建错误
+
+## Git 工作流
+
+* 约定式提交：`feat:`, `fix:`, `refactor:`, `docs:`, `test:`
+* 切勿直接提交到主分支
+* 合并请求需要审核
+* 合并前所有测试必须通过

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/examples/django-api-CLAUDE.md

@@ -0,0 +1,308 @@
+# Django REST API — 项目 CLAUDE.md
+
+> 使用 PostgreSQL 和 Celery 的 Django REST Framework API 真实示例。
+> 将此复制到你的项目根目录并针对你的服务进行自定义。
+
+## 项目概述
+
+**技术栈:** Python 3.12+, Django 5.x, Django REST Framework, PostgreSQL, Celery + Redis, pytest, Docker Compose
+
+**架构:** 采用领域驱动设计，每个业务领域对应一个应用。DRF 用于 API 层，Celery 用于异步任务，pytest 用于测试。所有端点返回 JSON — 无模板渲染。
+
+## 关键规则
+
+### Python 约定
+
+* 所有函数签名使用类型提示 — 使用 `from __future__ import annotations`
+* 不使用 `print()` 语句 — 使用 `logging.getLogger(__name__)`
+* 字符串格式化使用 f-strings，绝不使用 `%` 或 `.format()`
+* 文件操作使用 `pathlib.Path` 而非 `os.path`
+* 导入排序使用 isort：标准库、第三方库、本地库（由 ruff 强制执行）
+
+### 数据库
+
+* 所有查询使用 Django ORM — 原始 SQL 仅与 `.raw()` 和参数化查询一起使用
+* 迁移文件提交到 git — 生产中绝不使用 `--fake`
+* 使用 `select_related()` 和 `prefetch_related()` 防止 N+1 查询
+* 所有模型必须具有 `created_at` 和 `updated_at` 自动字段
+* 在 `filter()`、`order_by()` 或 `WHERE` 子句中使用的任何字段上建立索引
+
+```python
+# BAD: N+1 query
+orders = Order.objects.all()
+for order in orders:
+    print(order.customer.name)  # hits DB for each order
+
+# GOOD: Single query with join
+orders = Order.objects.select_related("customer").all()
+```
+
+### 认证
+
+* 通过 `djangorestframework-simplejwt` 使用 JWT — 访问令牌（15 分钟）+ 刷新令牌（7 天）
+* 每个视图都设置权限类 — 绝不依赖默认设置
+* 使用 `IsAuthenticated` 作为基础，为对象级访问添加自定义权限
+* 为登出启用令牌黑名单
+
+### 序列化器
+
+* 简单 CRUD 使用 `ModelSerializer`，复杂验证使用 `Serializer`
+* 当输入/输出结构不同时，分离读写序列化器
+* 在序列化器层面进行验证，而非在视图中 — 视图应保持精简
+
+```python
+class CreateOrderSerializer(serializers.Serializer):
+    product_id = serializers.UUIDField()
+    quantity = serializers.IntegerField(min_value=1, max_value=100)
+
+    def validate_product_id(self, value):
+        if not Product.objects.filter(id=value, active=True).exists():
+            raise serializers.ValidationError("Product not found or inactive")
+        return value
+
+class OrderDetailSerializer(serializers.ModelSerializer):
+    customer = CustomerSerializer(read_only=True)
+    product = ProductSerializer(read_only=True)
+
+    class Meta:
+        model = Order
+        fields = ["id", "customer", "product", "quantity", "total", "status", "created_at"]
+```
+
+### 错误处理
+
+* 使用 DRF 异常处理器确保一致的错误响应
+* 业务逻辑中的自定义异常放在 `core/exceptions.py`
+* 绝不向客户端暴露内部错误细节
+
+```python
+# core/exceptions.py
+from rest_framework.exceptions import APIException
+
+class InsufficientStockError(APIException):
+    status_code = 409
+    default_detail = "Insufficient stock for this order"
+    default_code = "insufficient_stock"
+```
+
+### 代码风格
+
+* 代码或注释中不使用表情符号
+* 最大行长度：120 个字符（由 ruff 强制执行）
+* 类名：PascalCase，函数/变量名：snake\_case，常量：UPPER\_SNAKE\_CASE
+* 视图保持精简 — 业务逻辑放在服务函数或模型方法中
+
+## 文件结构
+
+```
+config/
+  settings/
+    base.py              # 共享设置
+    local.py             # 开发环境覆盖设置 (DEBUG=True)
+    production.py        # 生产环境设置
+  urls.py                # 根 URL 配置
+  celery.py              # Celery 应用配置
+apps/
+  accounts/              # 用户认证、注册、个人资料
+    models.py
+    serializers.py
+    views.py
+    services.py          # 业务逻辑
+    tests/
+      test_views.py
+      test_services.py
+      factories.py       # Factory Boy 工厂
+  orders/                # 订单管理
+    models.py
+    serializers.py
+    views.py
+    services.py
+    tasks.py             # Celery 任务
+    tests/
+  products/              # 产品目录
+    models.py
+    serializers.py
+    views.py
+    tests/
+core/
+  exceptions.py          # 自定义 API 异常
+  permissions.py         # 共享权限类
+  pagination.py          # 自定义分页
+  middleware.py          # 请求日志记录、计时
+  tests/
+```
+
+## 关键模式
+
+### 服务层
+
+```python
+# apps/orders/services.py
+from django.db import transaction
+
+def create_order(*, customer, product_id: uuid.UUID, quantity: int) -> Order:
+    """Create an order with stock validation and payment hold."""
+    product = Product.objects.select_for_update().get(id=product_id)
+
+    if product.stock < quantity:
+        raise InsufficientStockError()
+
+    with transaction.atomic():
+        order = Order.objects.create(
+            customer=customer,
+            product=product,
+            quantity=quantity,
+            total=product.price * quantity,
+        )
+        product.stock -= quantity
+        product.save(update_fields=["stock", "updated_at"])
+
+    # Async: send confirmation email
+    send_order_confirmation.delay(order.id)
+    return order
+```
+
+### 视图模式
+
+```python
+# apps/orders/views.py
+class OrderViewSet(viewsets.ModelViewSet):
+    permission_classes = [IsAuthenticated]
+    pagination_class = StandardPagination
+
+    def get_serializer_class(self):
+        if self.action == "create":
+            return CreateOrderSerializer
+        return OrderDetailSerializer
+
+    def get_queryset(self):
+        return (
+            Order.objects
+            .filter(customer=self.request.user)
+            .select_related("product", "customer")
+            .order_by("-created_at")
+        )
+
+    def perform_create(self, serializer):
+        order = create_order(
+            customer=self.request.user,
+            product_id=serializer.validated_data["product_id"],
+            quantity=serializer.validated_data["quantity"],
+        )
+        serializer.instance = order
+```
+
+### 测试模式 (pytest + Factory Boy)
+
+```python
+# apps/orders/tests/factories.py
+import factory
+from apps.accounts.tests.factories import UserFactory
+from apps.products.tests.factories import ProductFactory
+
+class OrderFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = "orders.Order"
+
+    customer = factory.SubFactory(UserFactory)
+    product = factory.SubFactory(ProductFactory, stock=100)
+    quantity = 1
+    total = factory.LazyAttribute(lambda o: o.product.price * o.quantity)
+
+# apps/orders/tests/test_views.py
+import pytest
+from rest_framework.test import APIClient
+
+@pytest.mark.django_db
+class TestCreateOrder:
+    def setup_method(self):
+        self.client = APIClient()
+        self.user = UserFactory()
+        self.client.force_authenticate(self.user)
+
+    def test_create_order_success(self):
+        product = ProductFactory(price=29_99, stock=10)
+        response = self.client.post("/api/orders/", {
+            "product_id": str(product.id),
+            "quantity": 2,
+        })
+        assert response.status_code == 201
+        assert response.data["total"] == 59_98
+
+    def test_create_order_insufficient_stock(self):
+        product = ProductFactory(stock=0)
+        response = self.client.post("/api/orders/", {
+            "product_id": str(product.id),
+            "quantity": 1,
+        })
+        assert response.status_code == 409
+
+    def test_create_order_unauthenticated(self):
+        self.client.force_authenticate(None)
+        response = self.client.post("/api/orders/", {})
+        assert response.status_code == 401
+```
+
+## 环境变量
+
+```bash
+# Django
+SECRET_KEY=
+DEBUG=False
+ALLOWED_HOSTS=api.example.com
+
+# Database
+DATABASE_URL=postgres://user:pass@localhost:5432/myapp
+
+# Redis (Celery broker + cache)
+REDIS_URL=redis://localhost:6379/0
+
+# JWT
+JWT_ACCESS_TOKEN_LIFETIME=15       # minutes
+JWT_REFRESH_TOKEN_LIFETIME=10080   # minutes (7 days)
+
+# Email
+EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
+EMAIL_HOST=smtp.example.com
+```
+
+## 测试策略
+
+```bash
+# Run all tests
+pytest --cov=apps --cov-report=term-missing
+
+# Run specific app tests
+pytest apps/orders/tests/ -v
+
+# Run with parallel execution
+pytest -n auto
+
+# Only failing tests from last run
+pytest --lf
+```
+
+## ECC 工作流
+
+```bash
+# Planning
+/plan "Add order refund system with Stripe integration"
+
+# Development with TDD
+/tdd                    # pytest-based TDD workflow
+
+# Review
+/python-review          # Python-specific code review
+/security-scan          # Django security audit
+/code-review            # General quality check
+
+# Verification
+/verify                 # Build, lint, test, security scan
+```
+
+## Git 工作流
+
+* `feat:` 新功能，`fix:` 错误修复，`refactor:` 代码变更
+* 功能分支从 `main` 创建，需要 PR
+* CI：ruff（代码检查 + 格式化）、mypy（类型检查）、pytest（测试）、safety（依赖检查）
+* 部署：Docker 镜像，通过 Kubernetes 或 Railway 管理