@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/continuous-learning/evaluate-session.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Continuous Learning - Session Evaluator
+# Runs on Stop hook to extract reusable patterns from Claude Code sessions
+#
+# Why Stop hook instead of UserPromptSubmit:
+# - Stop runs once at session end (lightweight)
+# - UserPromptSubmit runs every message (heavy, adds latency)
+#
+# Hook config (in ~/.claude/settings.json):
+# {
+#   "hooks": {
+#     "Stop": [{
+#       "matcher": "*",
+#       "hooks": [{
+#         "type": "command",
+#         "command": "~/.claude/skills/continuous-learning/evaluate-session.sh"
+#       }]
+#     }]
+#   }
+# }
+#
+# Patterns to detect: error_resolution, debugging_techniques, workarounds, project_specific
+# Patterns to ignore: simple_typos, one_time_fixes, external_api_issues
+# Extracted skills saved to: ~/.claude/skills/learned/
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CONFIG_FILE="$SCRIPT_DIR/config.json"
+LEARNED_SKILLS_PATH="${HOME}/.claude/skills/learned"
+MIN_SESSION_LENGTH=10
+
+# Load config if exists
+if [ -f "$CONFIG_FILE" ]; then
+  MIN_SESSION_LENGTH=$(jq -r '.min_session_length // 10' "$CONFIG_FILE")
+  LEARNED_SKILLS_PATH=$(jq -r '.learned_skills_path // "~/.claude/skills/learned/"' "$CONFIG_FILE" | sed "s|~|$HOME|")
+fi
+
+# Ensure learned skills directory exists
+mkdir -p "$LEARNED_SKILLS_PATH"
+
+# Get transcript path from environment (set by Claude Code)
+transcript_path="${CLAUDE_TRANSCRIPT_PATH:-}"
+
+if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
+  exit 0
+fi
+
+# Count messages in session
+message_count=$(grep -c '"type":"user"' "$transcript_path" 2>/dev/null || echo "0")
+
+# Skip short sessions
+if [ "$message_count" -lt "$MIN_SESSION_LENGTH" ]; then
+  echo "[ContinuousLearning] Session too short ($message_count messages), skipping" >&2
+  exit 0
+fi
+
+# Signal to Claude that session should be evaluated for extractable patterns
+echo "[ContinuousLearning] Session has $message_count messages - evaluate for extractable patterns" >&2
+echo "[ContinuousLearning] Save learned skills to: $LEARNED_SKILLS_PATH" >&2

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/core-rules/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: core-rules
+description: 核心开发规则，每次对话自动加载
+---
+
+# 核心开发规则
+
+> 精简的硬性约束，确保代码质量和开发效率
+
+---
+
+## 1. 核心理念
+
+1. **上下文第一**：垃圾进垃圾出，先理解再动手
+2. **先结构后代码**：规划好框架再写实现
+3. **一次只做一件事**：极致专注，小步迭代
+
+
+## 2. 开发约束
+
+### 架构与设计
+
+4. 不得采用补丁式修改而忽视整体设计
+5. 不得在业务代码中硬编码外部服务或混入 IO/网络/数据库副作用
+6. 不得将状态提升到不必要的层级或跨请求共享可变状态
+
+### 代码质量
+
+7. 不得省略必要注释，代码必须对维护者可理解
+8. 不得违反 SOLID 与 DRY 原则
+9. 不得保留未使用的变量、函数或使用语义模糊的命名
+10. 不得让单个函数或模块承担多个不相关职责
+
+### 错误处理
+
+11. 不得吞掉异常或使用空 catch 掩盖错误
+12. 不得返回语义不清的错误结果（如混用 null/undefined/false）
+
+### 开发流程
+
+13. 不得臆测接口行为，必须先查询文档或源码
+14. 不得在需求不清晰的情况下直接实现
+15. 不得在缺乏上下文理解的情况下直接修改代码
+
+---
+
+## 3. 胶水编程约束
+
+### 依赖使用
+
+16. 不得自行实现底层或通用逻辑，必须优先复用成熟库
+17. 不得复制依赖库代码到项目中修改或进行功能裁剪
+18. 实际加载必须是完整生产级实现，不得使用简化版或 Mock
+
+### 代码职责
+
+19. 当前项目仅允许承担业务流程编排、模块组合、参数配置与适配职责
+20. 不得在当前项目中重复实现依赖库已提供的功能
+21. 所有导入模块必须在运行期真实参与执行，不得伪集成
+
+---
+
+## 4. 安全约束
+
+22. 绝不引入、记录或提交密钥、API Key 或敏感信息
+23. 确保所有用户输入都被正确验证和清理
+24. 实施最小权限原则
+
+---
+
+## 5. 违反约束处理
+
+当发现代码违反上述约束时：
+
+1. 立即停止当前操作
+2. 向用户说明违反了哪条约束
+3. 提供符合约束的替代方案
+4. 等待用户确认后再继续

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/data-flow-spec/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: data-flow-spec
+description: 数据流转规格模板
+---
+
+# 数据流转规格模板
+
+## 数据依赖关系 ⚠️ 必填
+
+| 数据A | 依赖数据B | 依赖类型 | 说明 |
+|-------|----------|----------|------|
+| 订单 | 客户 | 创建依赖 | 创建订单前必须先选择客户 |
+| 发货单 | 订单 | 创建依赖 | 订单审批通过后才能创建发货单 |
+| 订单 | 商品 | 引用依赖 | 商品下架后订单仍显示历史信息 |
+
+### 依赖类型说明
+- **创建依赖**：必须先有B才能创建A
+- **引用依赖**：A引用B，B变化时A如何处理
+- **级联依赖**：删除B时A如何处理
+
+## 数据联动规则 ⚠️ 必填
+
+| 触发字段 | 联动字段 | 联动规则 | 触发时机 |
+|----------|----------|----------|----------|
+| 商品数量 | 商品总价 | 数量 × 单价 | 输入时实时计算 |
+| 省份 | 城市列表 | 根据省份筛选城市 | 省份选择后 |
+| 优惠券 | 实付金额 | 总价 - 优惠金额 | 选择优惠券后 |
+| 全选 | 列表项选中状态 | 全部选中/取消 | 点击全选时 |
+
+## 数据缓存策略 ⚠️ 必填
+
+| 数据类型 | 缓存位置 | 缓存时长 | 失效条件 | 更新策略 |
+|----------|----------|----------|----------|----------|
+| 用户信息 | localStorage | 7天 | 退出登录 | 登录时更新 |
+| 字典数据 | sessionStorage | 会话期间 | 关闭标签页 | 首次访问时加载 |
+| 列表数据 | 内存(store) | 页面生命周期 | 路由切换 | 每次进入刷新 |
+| 表单草稿 | localStorage | 24小时 | 提交成功 | 输入时自动保存 |
+
+## 更新策略 ⚠️ 必填
+
+| 操作 | 更新策略 | 失败回滚 | 说明 |
+|------|----------|----------|------|
+| 点赞 | 乐观更新 | 是 | 先更新UI，失败后回滚 |
+| 删除 | 悲观更新 | - | 等API成功后再更新UI |
+| 编辑 | 悲观更新 | - | 等API成功后再更新UI |
+| 排序 | 乐观更新 | 是 | 拖拽时立即更新，失败回滚 |
+
+## 数据冲突处理 ⚠️ 必填
+
+| 场景 | 检测方式 | 处理策略 | 用户提示 |
+|------|----------|----------|----------|
+| 多人编辑 | 版本号比对 | 后提交者提示冲突 | "数据已被他人修改，请刷新后重试" |
+| 多标签页 | 时间戳比对 | 提示数据已变更 | "数据已更新，是否刷新？" |
+| 离线编辑 | 本地队列 | 恢复网络后同步 | "正在同步离线数据..." |
+
+## 数据同步机制
+
+| 场景 | 同步方式 | 同步频率 | 说明 |
+|------|----------|----------|------|
+| 消息通知 | WebSocket | 实时 | 新消息实时推送 |
+| 列表数据 | 轮询 | 30秒 | 定时刷新列表 |
+| 状态变更 | 事件驱动 | 操作后 | 操作成功后刷新相关数据 |
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/database/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: database
+description: Database Skill
+---
+
+# Database Skill
+
+数据库设计、建模和查询优化最佳实践。
+
+## 数据库设计原则
+
+### 范式化设计
+- **1NF**: 字段原子性，不可再分
+- **2NF**: 消除部分依赖
+- **3NF**: 消除传递依赖
+- 适度反范式化以提升查询性能
+
+### 命名规范
+```
+表名: 小写复数，下划线分隔
+  users, order_items, user_profiles
+
+字段名: 小写，下划线分隔
+  created_at, user_id, is_active
+
+主键: id 或 表名_id
+外键: 关联表名_id
+索引: idx_表名_字段名
+```
+
+## 表设计模板
+
+```sql
+CREATE TABLE users (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    uuid VARCHAR(36) NOT NULL UNIQUE,
+    email VARCHAR(255) NOT NULL UNIQUE,
+    password_hash VARCHAR(255) NOT NULL,
+    status TINYINT DEFAULT 1 COMMENT '0:禁用 1:正常',
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    deleted_at TIMESTAMP NULL COMMENT '软删除时间',
+    
+    INDEX idx_email (email),
+    INDEX idx_status (status),
+    INDEX idx_created_at (created_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+## 索引优化
+
+### 索引选择原则
+- 高选择性字段优先
+- 覆盖查询常用字段
+- 联合索引遵循最左前缀
+- 避免过度索引
+
+### 联合索引设计
+```sql
+-- 查询: WHERE a = ? AND b = ? ORDER BY c
+CREATE INDEX idx_a_b_c ON table(a, b, c);
+
+-- 最左前缀匹配
+✅ WHERE a = ?
+✅ WHERE a = ? AND b = ?
+✅ WHERE a = ? AND b = ? AND c = ?
+❌ WHERE b = ?
+❌ WHERE b = ? AND c = ?
+```
+
+### 索引失效场景
+```sql
+-- 避免这些写法
+WHERE YEAR(created_at) = 2024  -- 函数操作
+WHERE name LIKE '%keyword%'     -- 前导通配符
+WHERE status != 1               -- 否定条件
+WHERE id + 1 = 100              -- 表达式计算
+```
+
+## 查询优化
+
+### EXPLAIN 分析
+```sql
+EXPLAIN SELECT * FROM users WHERE email = 'test@example.com';
+```
+
+关注指标：
+- **type**: 至少达到 range，避免 ALL
+- **key**: 确认使用了预期索引
+- **rows**: 扫描行数越少越好
+- **Extra**: 避免 Using filesort、Using temporary
+
+### 分页优化
+```sql
+-- 避免大偏移量
+❌ SELECT * FROM orders LIMIT 100000, 20;
+
+-- 使用游标分页
+✅ SELECT * FROM orders WHERE id > 100000 ORDER BY id LIMIT 20;
+
+-- 延迟关联
+✅ SELECT * FROM orders o
+   INNER JOIN (SELECT id FROM orders ORDER BY id LIMIT 100000, 20) t
+   ON o.id = t.id;
+```
+
+## 事务与锁
+
+### 事务隔离级别
+| 级别 | 脏读 | 不可重复读 | 幻读 |
+|------|------|------------|------|
+| READ UNCOMMITTED | ✅ | ✅ | ✅ |
+| READ COMMITTED | ❌ | ✅ | ✅ |
+| REPEATABLE READ | ❌ | ❌ | ✅ |
+| SERIALIZABLE | ❌ | ❌ | ❌ |
+
+### 锁优化
+- 尽量使用行锁而非表锁
+- 事务尽量短小
+- 按固定顺序访问表和行
+- 合理设置锁等待超时
+
+## ORM 最佳实践
+
+### N+1 问题
+```python
+# ❌ N+1 查询
+users = User.query.all()
+for user in users:
+    print(user.orders)  # 每次循环都查询
+
+# ✅ 预加载
+users = User.query.options(joinedload(User.orders)).all()
+```
+
+### 批量操作
+```python
+# ❌ 逐条插入
+for item in items:
+    db.session.add(Item(**item))
+    db.session.commit()
+
+# ✅ 批量插入
+db.session.bulk_insert_mappings(Item, items)
+db.session.commit()
+```
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/deep-interview/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: deep-interview
+description: 深度访谈式需求收集 (Deep Interview)
+---
+
+# 深度访谈式需求收集 (Deep Interview)
+
+> 通过结构化访谈深入挖掘需求，确保规范文档的完整性和准确性
+
+## 触发条件
+
+- 用户请求"深度访谈"、"需求访谈"、"详细了解需求"
+- 新功能规划阶段，需求不明确时
+- 现有规范需要补充细节时
+
+## 访谈流程
+
+### 阶段 1: 上下文准备
+
+1. 阅读相关的现有文档（SPEC.md、requirements.md、design.md 等）
+2. 识别已知信息和信息缺口
+3. 准备访谈问题框架
+
+### 阶段 2: 多维度访谈
+
+按以下维度进行深入提问，每个维度 2-3 个问题：
+
+#### 2.1 业务价值维度
+- 这个功能解决什么核心问题？
+- 目标用户是谁？他们的痛点是什么？
+- 成功的衡量标准是什么？
+
+#### 2.2 技术实现维度
+- 有哪些技术约束或依赖？
+- 是否有现有系统需要集成？
+- 性能要求是什么？
+
+#### 2.3 用户体验维度
+- 用户的典型使用场景是什么？
+- 期望的交互方式是怎样的？
+- 有没有参考的产品或设计？
+
+#### 2.4 边界与约束维度
+- 哪些是必须有的功能？哪些是可选的？
+- 有什么明确不做的事情？
+- 时间和资源约束是什么？
+
+#### 2.5 风险与权衡维度
+- 最担心的技术风险是什么？
+- 如果必须简化，会牺牲什么？
+- 有哪些已知的权衡取舍？
+
+### 阶段 3: 信息整合
+
+1. 总结访谈收集的关键信息
+2. 识别仍需澄清的问题
+3. 与用户确认理解是否正确
+
+### 阶段 4: 规范输出
+
+将访谈结果转化为 Kiro 规范文档：
+- `requirements.md` - 用户故事和验收标准
+- `design.md` - 技术设计和架构决策
+- `tasks.md` - 实现任务清单
+
+## 访谈技巧
+
+### 问题设计原则
+
+1. **开放式问题** - 避免是/否问题
+   - ❌ "需要支持多语言吗？"
+   - ✅ "在国际化方面有什么考虑？"
+
+2. **场景化问题** - 通过具体场景挖掘需求
+   - ❌ "错误处理怎么做？"
+   - ✅ "当用户在弱网环境下操作时，你期望系统如何响应？"
+
+3. **追问式问题** - 深入挖掘
+   - "能详细说说这个场景吗？"
+   - "为什么这个对你很重要？"
+   - "有没有遇到过类似的问题？"
+
+4. **权衡式问题** - 明确优先级
+   - "如果只能选一个，你会选择 A 还是 B？"
+   - "在速度和准确性之间，你更看重哪个？"
+
+### 访谈节奏
+
+- 每轮提问 1-2 个问题，避免信息过载
+- 在用户回答后进行总结确认
+- 根据回答动态调整后续问题
+- 持续访谈直到覆盖所有维度
+
+## 输出模板
+
+访谈完成后，生成以下格式的规范：
+
+```markdown
+# 需求规范: [功能名称]
+
+## 背景与目标
+[从访谈中提取的业务背景和目标]
+
+## 用户故事
+[基于访谈整理的用户故事]
+
+## 验收标准
+[从访谈中明确的验收条件]
+
+## 技术约束
+[访谈中识别的技术限制]
+
+## 设计决策
+[访谈中讨论的权衡和决策]
+
+## 待澄清事项
+[仍需进一步确认的问题]
+```
+
+## 与 Kiro Spec 工作流集成
+
+深度访谈可以作为 Kiro Spec 工作流的前置步骤：
+
+```
+深度访谈 → requirements.md → design.md → tasks.md → 实现
+```
+
+在创建新 Spec 时，如果需求不明确，先进行深度访谈再生成规范文档。
+
+## 示例对话
+
+**开始访谈:**
+> 我注意到你想实现 [功能名称]。在我们开始详细规划之前，我想更深入地了解一些情况。
+> 
+> 首先，能告诉我这个功能主要是为了解决什么问题吗？是什么触发了这个需求？
+
+**追问:**
+> 你提到了 [用户回答的关键点]，这很有帮助。
+> 
+> 我想进一步了解：在实际使用中，用户通常会在什么情况下遇到这个问题？能描述一个具体的场景吗？
+
+**权衡确认:**
+> 我理解了你的需求。不过我注意到 [A] 和 [B] 之间可能存在一些权衡。
+> 
+> 如果必须在两者之间做选择，你会更倾向于哪个方向？
+
+**总结确认:**
+> 让我总结一下我们讨论的内容：
+> 1. [关键点 1]
+> 2. [关键点 2]
+> 3. [关键点 3]
+> 
+> 这个理解正确吗？还有什么需要补充的吗？
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/django-drf/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: django-drf
+description: Django + DRF 开发指南
+---
+
+# Django + DRF 开发指南
+
+## 项目结构
+
+```
+WHartTest_Django/
+├── wharttest_django/     # 项目配置
+│   ├── settings.py       # Django 设置
+│   ├── urls.py           # 根路由
+│   └── celery.py         # Celery 配置
+├── accounts/             # 用户认证
+├── api_keys/             # API Key 管理
+├── knowledge/            # 知识库模块
+├── langgraph_integration/# LLM 集成
+├── mcp_tools/            # MCP 工具
+├── orchestrator_integration/ # Agent 编排
+├── projects/             # 项目管理
+├── prompts/              # 提示词管理
+├── requirements/         # 需求管理
+└── testcases/            # 测试用例
+```
+
+## 开发规范
+
+### Model 定义
+```python
+from django.db import models
+
+class MyModel(models.Model):
+    """模型说明"""
+    name = models.CharField(max_length=100, verbose_name="名称")
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        verbose_name = "我的模型"
+        ordering = ['-created_at']
+```
+
+### Serializer 定义
+```python
+from rest_framework import serializers
+
+class MyModelSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = MyModel
+        fields = ['id', 'name', 'created_at']
+        read_only_fields = ['id', 'created_at']
+```
+
+### ViewSet 定义
+```python
+from rest_framework import viewsets
+from rest_framework.decorators import action
+from rest_framework.response import Response
+
+class MyModelViewSet(viewsets.ModelViewSet):
+    """ViewSet 说明"""
+    queryset = MyModel.objects.all()
+    serializer_class = MyModelSerializer
+    
+    @action(detail=True, methods=['post'])
+    def custom_action(self, request, pk=None):
+        """自定义操作"""
+        instance = self.get_object()
+        return Response({'status': 'ok'})
+```
+
+### URL 配置
+```python
+from rest_framework.routers import DefaultRouter
+
+router = DefaultRouter()
+router.register(r'mymodels', MyModelViewSet, basename='mymodel')
+urlpatterns = router.urls
+```
+
+## 测试命令
+
+```bash
+# 在 Docker 容器内执行
+docker-compose exec backend python manage.py test requirements.tests
+docker-compose exec backend python manage.py test --keepdb
+```
+
+## 数据库迁移
+
+```bash
+docker-compose exec backend python manage.py makemigrations
+docker-compose exec backend python manage.py migrate
+```
+