@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/glue-coding-workflow/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: glue-coding-workflow
+description: 胶水编程完整工作流，通过 #glue-coding-workflow 引用
+---
+
+# 胶水编程工作流
+
+> 当需要开发新功能时，优先使用此工作流
+
+---
+
+## 工作流概览
+
+```
+需求明确 → 寻找轮子 → 理解接口 → 描述连接 → 验证运行
+```
+
+---
+
+## 第一步：需求明确
+
+### 输出格式
+
+```markdown
+## 目标
+一句话描述要实现什么
+
+## 非目标
+明确不做什么
+
+## 输入
+- 数据来源
+- 数据格式
+
+## 输出
+- 期望结果
+- 输出格式
+```
+
+---
+
+## 第二步：寻找轮子
+
+### 搜索策略
+
+1. 让 AI 分析需求涉及的技术领域
+2. 推荐对应的 GitHub Topics 关键词
+3. 评估候选库的质量指标：
+   - Star 数量（>1000 优先）
+   - 最近更新时间（<6个月）
+   - Issue 活跃度
+   - 文档完整性
+   - 许可证兼容性
+
+### 常用 Topics
+
+| 需求 | Topic |
+|:---|:---|
+| Telegram Bot | telegram-bot |
+| 数据分析 | data-analysis |
+| AI Agent | ai-agent |
+| CLI 工具 | cli |
+| Web 爬虫 | web-scraping |
+| API 客户端 | api-client |
+
+### 提示词模板
+
+```
+我需要实现 [你的需求]，请帮我：
+1. 分析这个需求可能涉及哪些技术领域
+2. 推荐对应的 GitHub Topics 关键词
+3. 搜索并推荐 3-5 个成熟的开源库
+4. 对比它们的优缺点
+5. 给出最终推荐
+```
+
+---
+
+## 第三步：理解接口
+
+### 文档喂给 AI
+
+1. 下载官方文档到本地
+2. 让 AI 总结核心 API
+3. 明确：输入是什么，输出是什么
+
+### 输出格式
+
+```markdown
+## 库名称
+xxx
+
+## 核心功能
+- 功能1：描述
+- 功能2：描述
+
+## 关键 API
+### API 1
+- 输入：参数类型和含义
+- 输出：返回值类型和含义
+- 示例：代码片段
+
+### API 2
+...
+```
+
+---
+
+## 第四步：描述连接
+
+### 连接描述模板
+
+```markdown
+## 数据流
+A 的输出 → 转换逻辑 → B 的输入
+
+## 胶水代码职责
+1. 封装接口
+2. 统一输入输出格式
+3. 错误处理
+4. 日志记录
+```
+
+### 代码组织
+
+```
+project/
+├── libs/external/     # 第三方库（不可修改）
+├── src/
+│   ├── glue/          # 胶水代码
+│   │   ├── adapters/  # 适配器
+│   │   └── connectors/ # 连接器
+│   └── core/          # 最小业务逻辑
+└── main.py            # 入口
+```
+
+---
+
+## 第五步：验证运行
+
+### 验证清单
+
+- [ ] 所有导入模块在运行期真实参与执行
+- [ ] 无"只导入不用"的伪集成
+- [ ] 无路径遮蔽或重名模块问题
+- [ ] 功能与预期一致
+- [ ] 错误处理正常
+
+### 调试流程
+
+```
+跑通 → 完成
+  ↓
+报错 → 复制完整错误 → 给 AI → 继续粘
+```
+
+---
+
+## 约束检查清单
+
+### 开发前
+
+- [ ] 确认没有现成的开源实现
+- [ ] 确认选择的库是生产级实现
+- [ ] 确认许可证兼容
+
+### 开发中
+
+- [ ] 未复制依赖库代码到项目
+- [ ] 未对依赖库进行功能裁剪
+- [ ] 未使用 Mock/Stub 替代真实实现
+- [ ] 胶水代码只做组合/调用/封装/适配
+
+### 开发后
+
+- [ ] 所有模块真实参与执行
+- [ ] 无未使用的导入
+- [ ] 功能完整性验证通过
+
+---
+
+## 示例：Polymarket 数据分析 Bot
+
+### 需求
+
+实时获取 Polymarket 数据，分析后推送到 Telegram
+
+### 轮子选择
+
+```
+轮子 1: polymarket-py (官方 SDK)
+轮子 2: pandas (数据分析)
+轮子 3: python-telegram-bot (消息推送)
+```
+
+### 胶水代码
+
+```python
+# glue/connectors/polymarket_to_telegram.py
+
+from polymarket import Client as PolymarketClient
+from telegram import Bot
+import pandas as pd
+
+class PolymarketTelegramConnector:
+    """连接 Polymarket 数据到 Telegram 推送"""
+    
+    def __init__(self, pm_api_key: str, tg_token: str, chat_id: str):
+        self.pm_client = PolymarketClient(api_key=pm_api_key)
+        self.tg_bot = Bot(token=tg_token)
+        self.chat_id = chat_id
+    
+    def fetch_and_analyze(self, market_id: str) -> pd.DataFrame:
+        """获取数据并分析"""
+        data = self.pm_client.get_market(market_id)
+        df = pd.DataFrame(data)
+        # 分析逻辑
+        return df
+    
+    def send_report(self, df: pd.DataFrame) -> None:
+        """发送报告到 Telegram"""
+        message = self._format_report(df)
+        self.tg_bot.send_message(chat_id=self.chat_id, text=message)
+```
+
+### 结果
+
+- 胶水代码：50 行
+- 开发时间：2 小时
+- 传统做法：3000 行，2 周

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

@@ -0,0 +1,188 @@
+---
+name: harness-surface-sync
+description: Audit and propagate Codex Harness repository changes across root runtime, docs/testing, templates, workflows, config, package-assets, skills, and `.agents` mirrors. Use when rules, prompts, task templates, testing-left-shift truth sources, install docs, or package docs changed and the repo must be checked end-to-end, stale wording fixed, and mirrors re-synced in one pass.
+---
+
+# Harness Surface Sync
+
+## Overview
+
+Use this skill to do a full-surface consistency pass on this harness repo after workflow, rule, template, or testing-left-shift changes.
+
+Default goal:
+
+1. Find stale wording or missing propagation.
+2. Update the correct canonical source first.
+3. Sync mirrored copies across the current repo root, templates, `package-assets/`, and `.agents`.
+4. Validate diffs, JSON, PowerShell syntax, and mirror hashes.
+
+Read [references/current-repo-sync-matrix.md](references/current-repo-sync-matrix.md) before editing.
+Use [references/stale-patterns.md](references/stale-patterns.md) as the scan checklist.
+
+## When To Use
+
+Use this skill when the user asks to:
+
+- continue syncing harness/template changes
+- check whether old process wording still exists
+- propagate runtime or doc changes into templates/package assets
+- align `docs/testing/*`, `task` flow, `Stage 17`, or testing-left-shift behavior everywhere
+- package a new repo-local skill so installed projects inherit it too
+
+Do not use this skill for normal feature work inside an app repo.
+
+## Canonical Source Rules
+
+- For root runtime and root truth sources actually consumed by the driver, prefer repo-root files as canonical.
+- For human-facing harness/package docs, prefer `docs/codex-harness-engineering/*.md` as canonical.
+- For template config, workflows, and package-assets content, prefer `docs/codex-harness-engineering/templates/...` as canonical, then mirror to `.agents/docs/.../templates/...`.
+- For active repo skills, prefer `.agents/skills/<skill-name>` as canonical, then mirror into `docs/codex-harness-engineering/templates/package-assets/skills/<skill-name>` and both package-assets skill trees.
+- For active role rules, prefer `.codex/rules/agents.md` as canonical; installed projects must read rules from `.codex/rules`, not `.agents/rules`.
+
+## Workflow
+
+### 1. Snapshot the workspace
+
+- Run `git status --short` first.
+- Identify unrelated dirty files and avoid touching them.
+- Decide whether the request is:
+  - audit only
+  - fix and sync
+  - create/update a reusable skill and distribute it
+
+### 2. Build the truth-source stack
+
+Read only the surfaces relevant to the requested change. Typical order:
+
+1. Root runtime and truth sources:
+   - `AGENTS.md`
+   - `tools/install/bootstrap-codex-harness.ps1`
+   - `tools/harness/codex-loop.ps1`
+   - `tools/harness/doctor.ps1`
+   - `tools/harness/verify.ps1`
+   - `.codex/task-run-profile.json`
+   - `.codex/prompts/*.md`
+   - `tools/harness/templates/project-task-template.json`
+   - `docs/harness/*`
+   - `docs/testing/*`
+2. Active package/runtime mirrors:
+   - repo-root runtime/docs
+   - `.agents/*`
+   - `docs/harness/*`
+   - `docs/codex-harness-engineering/*`
+3. Template and distribution surfaces:
+   - `docs/codex-harness-engineering/templates/runtime/*`
+   - `docs/codex-harness-engineering/templates/docs/*`
+   - `docs/codex-harness-engineering/templates/testing/*`
+   - `docs/codex-harness-engineering/templates/config/*`
+   - `docs/codex-harness-engineering/templates/package-assets/*`
+   - `.agents/docs/codex-harness-engineering/templates/...`
+4. Skills when relevant:
+   - `.agents/skills/<name>`
+   - `docs/codex-harness-engineering/templates/package-assets/skills/<name>`
+   - `docs/codex-harness-engineering/templates/package-assets/skills/<name>`
+   - `.agents/docs/codex-harness-engineering/templates/package-assets/skills/<name>`
+
+### 3. Scan for stale signals
+
+Use `rg` against likely surfaces before opening many files.
+
+Common scan target groups:
+
+- `docs/codex-harness-engineering`
+- `docs/harness`
+- `docs/codex-harness-engineering/templates`
+- `.agents/docs/codex-harness-engineering/templates`
+- `docs/project-flow` when analysis docs must stay aligned
+
+Start from the patterns in [references/stale-patterns.md](references/stale-patterns.md).
+
+### 4. Update canonical files first
+
+- Edit the real source first with `apply_patch`.
+- Keep edits narrow and repository-aware.
+- Do not “fix” every mention of a keyword blindly; verify the sentence is actually stale.
+- If only wording changed, do not touch runtime scripts.
+- If runtime behavior changed, update the driver-facing root file first, then the mirrors.
+
+### 5. Propagate mirrors
+
+After canonical edits, copy the exact file to all mapped destinations from the sync matrix.
+
+Typical propagation pattern:
+
+- root canonical -> `.agents/` + template runtime mirrors
+- `docs/harness/*` / `docs/testing/*` canonical -> template docs/testing mirrors and any package docs that summarize them
+- `docs/codex-harness-engineering/*.md` canonical -> package-assets docs mirrors
+- `docs/codex-harness-engineering/templates/config|workflows|root/*` canonical -> `.agents/docs/.../templates/...`
+- `.agents/skills/<name>` canonical -> `docs/codex-harness-engineering/templates/package-assets/skills/<name>` + both package-assets skill trees
+
+### 6. Validate
+
+Run the smallest useful validation set for the touched files:
+
+- Diff quality:
+
+```powershell
+git diff --check -- <touched files>
+```
+
+- JSON parse:
+
+```powershell
+Get-Content <file>.json -Raw | ConvertFrom-Json | Out-Null
+```
+
+- PowerShell syntax:
+
+```powershell
+[System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path <file>.ps1), [ref]$null, [ref]$null) | Out-Null
+```
+
+- Mirror hash compare:
+
+```powershell
+(Get-FileHash <left>).Hash -eq (Get-FileHash <right>).Hash
+```
+
+Prefer validating only the touched surfaces, not the whole repo.
+
+### 7. Report
+
+Always summarize:
+
+- canonical files changed
+- mirrors updated
+- validations run
+- remaining stale areas or intentionally skipped surfaces
+
+## Current Repo Conventions
+
+For this repo, testing-left-shift means implementation-facing flows should normally reference:
+
+- `docs/testing/ACCEPTANCE_CRITERIA.md`
+- `docs/testing/ACCEPTANCE_EXAMPLES.md`
+- `docs/testing/TRACEABILITY_MATRIX.md`
+- `docs/testing/TEST_STRATEGY.md`
+- `docs/testing/TEST_DATA_MATRIX.md`
+- `docs/testing/RISK_BASED_TEST_PLAN.md`
+- `docs/testing/REGRESSION_PLAN.md`
+- `docs/testing/EVIDENCE_PROTOCOL.md`
+- `docs/testing/test-matrix.md`
+- `docs/testing/verify-matrix.md`
+
+Stage 17 / Verify should be described as:
+
+- fresh evidence
+- affected tests
+- P0/P1 regression
+- contract / E2E / visual confirmation when applicable
+
+It should not be described as the first place to define missing test scope.
+
+## Guardrails
+
+- Never revert unrelated user changes.
+- Never assume all duplicated files should be edited independently; pick the canonical source first.
+- When creating or updating a skill, ship it through the package duplication chain before closing the task.
+- If the request is review-only, stop after findings and do not sync files.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/harness-surface-sync/references/current-repo-sync-matrix.md

@@ -0,0 +1,110 @@
+# Current Repo Sync Matrix
+
+Use this matrix to decide where the real edit belongs and which copies must be refreshed afterwards.
+
+## 1. Root Runtime And Driver Truth Sources
+
+Canonical source:
+
+- repo root:
+  - `AGENTS.md`
+  - `tools/install/bootstrap-codex-harness.ps1`
+  - `tools/harness/codex-loop.ps1`
+  - `tools/harness/doctor.ps1`
+  - `tools/harness/verify.ps1`
+  - `.codex/task-run-profile.json`
+  - `.codex/prompts/*.md`
+  - `tools/harness/templates/project-task-template.json`
+  - `docs/harness/*`
+  - `docs/testing/*`
+
+Typical mirrors:
+
+- `.agents/*`
+- `docs/codex-harness-engineering/templates/runtime/*`
+- `.agents/docs/codex-harness-engineering/templates/runtime/*`
+- `docs/codex-harness-engineering/templates/docs/*` or `templates/testing/*` when the source is under `docs/harness/*` or `docs/testing/*`
+
+## 2. Active Role Rules
+
+Canonical source:
+
+- `.codex/rules/agents.md`
+
+Typical mirrors:
+
+- `docs/codex-harness-engineering/templates/config/rules/agents.md`
+- `docs/codex-harness-engineering/templates/package-assets/rules/agents.md`
+- `.agents/docs/codex-harness-engineering/templates/config/rules/agents.md`
+- `.agents/docs/codex-harness-engineering/templates/package-assets/rules/agents.md`
+
+## 3. Human-Facing Harness And Package Docs
+
+Canonical source:
+
+- `docs/codex-harness-engineering/*.md`
+
+Typical mirrors:
+
+- `docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/*.md`
+- `.agents/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/*.md`
+
+Special case:
+
+- `docs/harness/spec-to-ui-to-code-workflow.md` often also feeds:
+  - `docs/harness/spec-to-ui-to-code-workflow.md`
+  - `docs/codex-harness-engineering/spec-to-ui-to-code-workflow.md`
+  - `docs/codex-harness-engineering/templates/docs/spec-to-ui-to-code-workflow.md`
+  - package-assets doc mirrors
+
+## 4. Template Config
+
+Canonical source:
+
+- `docs/codex-harness-engineering/templates/config/*`
+
+Typical mirrors:
+
+- `.agents/docs/codex-harness-engineering/templates/config/*`
+
+Common targets:
+
+- `codex-config.toml`
+- `codex-readme.md`
+- `codex-agent-roles.md`
+- `global-AGENTS.md`
+- `agents/*.toml`
+
+## 5. Package-Assets Workflows
+
+Canonical source:
+
+- `docs/codex-harness-engineering/templates/package-assets/workflows/*`
+
+Typical mirrors:
+
+- `.agents/docs/codex-harness-engineering/templates/package-assets/workflows/*`
+
+## 6. Package-Assets Root Docs
+
+Canonical source:
+
+- `docs/codex-harness-engineering/templates/package-assets/root/*`
+
+Typical mirrors:
+
+- `.agents/docs/codex-harness-engineering/templates/package-assets/root/*`
+
+## 7. Repo Skills
+
+Canonical source for active usage:
+
+- `.agents/skills/<skill-name>/...`
+
+Distribution mirrors:
+
+- `docs/codex-harness-engineering/templates/package-assets/skills/<skill-name>/...`
+- `docs/codex-harness-engineering/templates/package-assets/skills/<skill-name>/...`
+- `.agents/docs/codex-harness-engineering/templates/package-assets/skills/<skill-name>/...`
+
+When a skill is created or updated, refresh the package distribution copies before considering the task done.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/harness-surface-sync/references/stale-patterns.md

@@ -0,0 +1,62 @@
+# Stale Pattern Checklist
+
+These patterns are high-signal starting points for this repo. Do not replace blindly; inspect context first.
+
+## Process And Testing-Left-Shift Signals
+
+- `Tests are OPTIONAL`
+  - Usually stale for implementation-facing harness workflows.
+- `Stage 17 验证回归` or `Stage 17 Verify / Regression` with no mention of `fresh evidence` or `affected tests`
+  - Usually needs the modern Stage 17 wording.
+- `test-matrix + test-data-plan`
+  - Often stale if it omits acceptance examples, traceability, regression plan, or evidence protocol.
+- text implying tests are first defined during verify/regression
+  - Usually conflicts with the current left-shift model.
+
+## Missing Truth Sources
+
+Look for docs that mention requirements, plan, or verification but omit:
+
+- `ACCEPTANCE_EXAMPLES.md`
+- `TRACEABILITY_MATRIX.md`
+- `TEST_DATA_MATRIX.md`
+- `verify-matrix.md`
+
+Common stale surfaces:
+
+- install docs
+- implementation guides
+- package root README/PACKAGE
+- workflow docs
+- planning docs
+- review prompts / review docs
+
+## Task And Workflow Shape Signals
+
+- tasks/workflows missing Requirement IDs
+- tasks/workflows missing an explicit test mapping or evidence line
+- workflows saying tests are optional for executable changes
+- implementation steps that say “write code then add tests later”
+
+## Install / Validation Signals
+
+- install docs that tell users to build a real `task.json` before testing truth sources exist
+- docs that treat `tools/install/env-check.ps1` as the main install gate when the repo now expects `tools/harness/doctor.ps1` + `tools/harness/verify.ps1`
+
+## Role / Profile Signals
+
+- `test-planner` described only as “test matrix”
+- `test-runner` described only as “reports”
+- no mention of acceptance examples, traceability, affected tests, or fresh evidence in config/role docs
+
+## Recommended First Scan
+
+Use `rg` against:
+
+- `docs/codex-harness-engineering`
+- `docs/harness`
+- `docs/codex-harness-engineering/templates`
+- `.agents/docs/codex-harness-engineering/templates`
+- `docs/project-flow`
+
+Then open only the hits that appear semantically stale.