https://github.com/geyadawang-boop/MySkill

# MySkill-shiniyaya

`MySkill-shiniyaya` 是一个面向 Agent Skill 全生命周期的工程化 Skill：从历史要求、现有 Skill、代码仓库、URL、论文和大规模异构资料中提取可复用能力，建立可追溯需求与证据链，生成候选 Skill，执行新鲜评估与自主优化，并产出可独立验证的纯净交付包。

它不是简单的“提示词生成器”。它把 Skill 视为需要固定需求、版本身份、测试、回归门、恢复状态和发布完整性的可执行软件制品。

## 核心原则

– 先固定 requirement ID、验收条件和分母，再计算完成率。
– 区分 `planned`、`observed`、`verified`；计划、自报和历史完成信号不等于验证通过。
– 为本地文件、网页快照、Skill 树和候选版本绑定 SHA-256，防止证据与实际工件漂移。
– functional audit、improvement gate、三方 scorer 与 delivery manifest 共用 NFC、portable-path、碰撞拒绝和稳定读取的 Skill tree 身份规则。
– 资料按需加载：先建立轻量 inventory/索引，再检索有限证据片段，不把全集塞入模型上下文。
– 原始对话、记忆、研究快照、handoff、缓存和运行日志不进入发布 Skill。
– 自主优化只生成可证伪候选；候选通过 baseline/current/candidate 三方 gate 后才能替换当前版本。
– Event Ledger 是连续性真相源；进度文档和 handoff 都可从 ledger 重建并逐字验证。

## 功能总览

### 1. 需求澄清、canonical registry 与历史要求复核

`requirements_intake.py` 可以：

– 为历史要求分配或保留稳定 ID、来源和 P0–P3 优先级；
– 检测缺少验收条件、模糊表述、重复要求和显式/语义冲突；
– 生成按优先级排序、带回答契约的澄清问题；
– 接收 inline clarification 后快速重算；
– 通过 `exact`/`merge` registry 固定旧分母、拒绝 ID 缺失和需求漂移，并只追加真正的新要求；
– 自动生成 positive、negative、boundary、recovery、mutation 测试 charter；
– 明确区分“已计划测试”和“已有新鲜验证证据”。

`functional_audit.py` 将每条 requirement 连接到 acceptance、实现位置、文件哈希、test ID 和绑定当前候选树的执行证据，按固定分母计算 `verified / applicable`。JSON/JUnit receipt 必须真实存在、哈希匹配，并绑定 requirement、Skill tree、test IDs、fresh/pass 和所需语义证据类别；评审或流程要求不能再由无关 continuity 测试冒充。缺失或部分完成项不会从分母消失，P0 不能由实现者单方面标为不适用。

### 2. 本地与 URL 来源身份

`inventory_sources.py` 对文件和目录进行有界枚举，记录路径、字节数、SHA-256 和确定性 inventory hash，并拒绝链接/reparse point、路径碰撞、扫描超限和过程中漂移。

裸 URL 只有定位符身份，不能证明网页内容。先用 `snapshot_url.py` 获取受限快照，保存：

– requested URL 与 final URL；
– UTC 抓取时间、HTTP 状态、内容类型和响应字节数；
– 精确响应内容 SHA-256；
– 重定向次数、解析地址和抓取策略。

默认拒绝 URL 凭据、私网/本机地址、过多重定向、超时和超大响应。

### 3. 大型 TXT/PDF/ZIP/EXE 异构知识库

`corpus_pipeline.py` 解决资料过多时的存储、提取率、分析时间和 token 问题：

– 原始文件留在原处，不复制进知识库；
– 按“原始内容哈希 + 提取策略哈希”建立内容寻址缓存；
– 重复文件共享一个提取对象，保留多个 source alias；
– 使用 SQLite 元数据和 FTS5 构建本地增量全文索引；
– 多词 FTS5 查询先做 conjunctive 召回，再以 OR fallback 找回分布在不同 chunk 的词，并返回 matched terms 与 term coverage；
– FTS5 不可用时退化为确定性 LIKE 查询；
– 查询结果受 `limit` 和 `token-budget` 双重限制；
– 分别报告文件覆盖、字节覆盖、唯一内容覆盖和去重节省。

格式策略：

– TXT、Markdown、JSON、YAML、HTML、源码等：有界解码和字符上限；
– PDF：普通文本提取优先，低密度页标记为需要 OCR，避免全库无差别 OCR；
– ZIP：展开前检查成员数、总解压字节、压缩比、路径穿越和加密成员；
– EXE/PE：只读静态头部和字符串，报告固定 `executed: false`，绝不执行；
– 未支持格式：保留在固定分母并标记 `unsupported`，可通过有界 extractor adapter 扩展。

### 4. 资料发现、评估与利用率

`source_utilization.py` 把资料处理拆为三个阶段：

1. `assess`：检查内容身份、文件树、许可证、测试和源码线索；
2. `decide`：对每个 source unit 明确 adopt/adapt/reject/defer；
3. `audit`：计算 assessment、disposition 和 verified adoption。

报告同时使用 source-unit、file、byte 三种分母。独立 PDF/Office/电子书按文件形成资料单元，带项目标记的源码树按项目边界聚合，避免只采用一篇论文却把整个分类目录计为已采用。代码采用必须绑定来源树、PoC、兼容性证据、实现定位、实现哈希、测试和测试证据；只引用资料但没有转化与验证，不计为 verified adoption。

资料发现本身也可评估。`inspect_skills.py` 在进入普通文件 inventory 前，先从 `–requirements` 和可选 `–query` 生成“资料需求画像”，然后：

– 对多个 Skill 根执行有界扫描，使用 `–max-skills`、`–max-bytes` 和 `–time-budget-seconds` 限制文件数、读取字节与耗时；
– 拒绝或跳过 link/reparse point，第一轮只读取 `SKILL.md` metadata、正文和精确字节身份，不执行候选中的命令；
– 同时进行中英文概念匹配与“当前内容任务需要哪类 Skill”的意图匹配，按需求相关性稳定排序；
– 把每个重复的 `–query` 和每个 requirement 字段作为独立 facet，使用 best-facet score + reciprocal-rank fusion + coverage，避免多能力长查询互相稀释；
– 用不依赖具体产品名称的最短已发现名称前缀做同族多样化，`–max-per-family` 默认 2，并把被家族上限挤出的候选标成 `family_diversity_overflow`；
– 输出带分数、匹配原因和引用检查结果的 `selected` shortlist；
– 把未入选候选的身份、分数和原因保存在 `overflow` manifest，防止硬 `limit` 造成静默遗忘；
– `catalog_sha256` 只由稳定的目录身份排序计算，与查询文本、排序和 shortlist limit 无关；
– 对 selected 逐项记录 adopt/adapt/reject/defer，对高相关 overflow 继续评估或显式延期。

~~~powershell
python -B .\myskill-shiniyaya\scripts\inspect_skills.py `
“$env:USERPROFILE\.codex\skills” “$env:USERPROFILE\.agents\skills” `
–requirements .\RUN\requirements-audit.json `
–query “long-form distillation into executable Skills” –max-per-family 2 –limit 20 `
–max-skills 2000 –max-bytes 33554432 –time-budget-seconds 60 `
–output .\RUN\source-discovery.json
~~~

命令返回 `1` 表示 selected Skill 中发现缺失、逃逸或不安全引用；报告仍可用于明确修复、拒绝或延期，不能把该状态解释成“没有候选”。held-out 测试可以把一个相关 Skill 隐藏在多个干扰项中，测量 shortlist recall、误选率、overflow disposition、实际采用率、耗时和 token。

### 5. PDF、现有 Skill 与证据综合

– `extract_pdf_text.py` 依次尝试可用 PDF 提取后端，输出分页文本、页数、空页、密度和 OCR 建议。
– `inspect_skills.py` 根据需求排序现有 Skill，并对 shortlist 执行引用完整性检查；未入选候选保留在 overflow manifest。
– evidence card 区分 observed、interpretation、proposal，保存 source ID、精确 locator 和内容 hash。
– 候选知识需通过“可追溯、能改变新任务决策、不是泛泛常识”三重验证。
– 接受的知识被转换为含 trigger、actions、outputs、validation、failure/recovery 和 side effects 的能力契约。
– prerequisite、enhancement、alternative、conflict 等关系用于检索完整可执行子图，而不是相似文本集合。

本项目已把本地 `cangjie-skill` 主规范纳入二级参考，采用其候选池、三重验证、淘汰留痕、原子知识关联、压力测试和阶段恢复思想。检查时该 Skill 引用的 `methodology/`、`extractors/`、`templates/` 并不存在，因此本项目没有把缺失资源描述为已复用实现。

### 6. 历史对话工作流挖掘

对话处理采用 discovery/held-out 隔离：

– `index_conversations.py` 流式、有界、脱敏地建立索引；
– `split_conversation_index.py` 按重复哈希、conversation ID、父子线程和 fork 关系冻结泄漏组；
– `extract_conversation_workflows.py` 只从 discovery 集提取工作流和失败恢复轨迹。

默认排除 system、developer、reasoning 和工具载荷。历史 final、task-complete 或 exit code 只是观察信号，不能单独证明新 Skill 可用。原始对话及派生索引只保存在运行目录。

### 7. 已验证经验库与自迭代

`experience_pipeline.py` 提供：

– `record`：在 secret/Markdown/output preflight 后写入脱敏哈希链 journal；
– `validate`：验证 journal 完整性；
– `build-graph`：把已验证 workflow/error/provenance 物化为知识图；
– `query`：确定性检索相关经验节点；
– `propose`：只用 verified node 提出变更并绑定 current Skill tree；
– `gate`：绑定 evaluation 与 candidate tree，输出 KEEP 或 REJECT。

workflow 不能自报 `verified`；必须通过 `verification_refs` 指向 passed verifier。经验可以提出改进，不能自行晋升候选。

### 8. 自主 brainstorm、缺口发现与测验生成

`improvement_discovery.py` 从以下证据面发现候选：

– missing/partial requirement；
– unassessed/undisposed source；
– evaluation regression、missing result 和 critical failure；
– verified historical error；
– 未测试的生产 CLI；
– 未由 `SKILL.md` 直接路由的 reference；
– `–source-discovery-report` 提供的 selected 引用问题、高相关 overflow、资料召回漏检和未解释拒绝。

每项候选必须包含 relevance、impact、evidence strength、evidence、hypothesis、falsifier、acceptance、目标定位、五维测试 charter 和预算。硬 `limit` 之外的候选进入可审计 overflow manifest，不会静默丢失。`verify` 子命令要求 selected 和高相关 overflow 有 adopt/reject/defer 处置，并校验 positive、negative、boundary、recovery、mutation 五维真实 receipt；发现器不会直接修改 Skill。

### 9. Skill 创建、编排与验证

– `init_target_skill.py` 初始化候选目录和基础 metadata；
– `SKILL.md` 负责选择、顺序、恢复和完成门；
– 详细分支按需放入 `references/`；
– 脆弱、重复或需要确定性的操作放入 `scripts/`；
– `validate_skill.py` 检查 frontmatter、命名、引用、资源边界和 Python 语法；
– `score_evals.py` 执行严格 JSON schema、重复键拒绝、逐 case receipt、baseline/current/candidate 三棵 Skill 树绑定和三方 gate。

复杂能力可组织为 focused Skill、orchestrator Skill 或 Skill family。触发条件全部写入 frontmatter description，正文保持祈使式并低于 500 行。

### 10. 低 token 连续性与 handoff

`continuity.py` 提供：

– `record`：追加 canonical、hash-chained 状态事件；
– `project`：重建 `PROGRESS.md`、immutable handoff 和 overflow；
– `verify`：从 ledger 重建并逐字验证投影；
– `resume`：输出 anchor、未完成 ID、阻塞码、唯一下一动作、建议 Skill 绑定，以及 progress/completed/remaining/capabilities/requirement/optimization 六字段紧凑状态。

每个未完成 requirement ID 必须在 inline handoff 或 hash-bound overflow 中。resume 不展开完整历史，因此跨对话恢复不需要重新消耗大量上下文。

### 11. 确定性交付与独立验证

`build_delivery_manifest.py` 从候选目录进行新鲜递归枚举，记录每个发布文件的路径、字节数和 SHA-256。`verify_delivery_manifest.py` 使用独立实现重新枚举和复算，拒绝：

– cache、link/reparse point 和不安全路径；
– 大小写/Unicode 规范化碰撞；
– 重复 JSON key 和非有限数值；
– 文件系统漂移、额外文件、缺失文件或内容篡改；
– 资源上限超标。

发布包只包含 Skill 本体、根 README、manifest 和 verification 报告。

## 仓库结构

~~~text
MySkill/
├── README.md
├── .gitignore
├── .gitattributes
├── myskill-shiniyaya-manifest.json
├── myskill-shiniyaya-verification.json
└── myskill-shiniyaya/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── references/
│ ├── authoring.md
│ ├── continuity-and-handoff.md
│ ├── conversation-workflow-mining.md
│ ├── evaluation-and-optimization.md
│ ├── evidence-and-synthesis.md
│ ├── experience-and-self-iteration.md
│ ├── heterogeneous-corpus.md
│ ├── improvement-discovery-and-testing.md
│ ├── requirements-clarification.md
│ ├── research-basis.md
│ ├── source-routing.md
│ └── source-utilization.md
├── scripts/
└── tests/
~~~

`.gitattributes` 将 Skill 与发布证据视为字节寻址工件，避免 Git 自动换行破坏 manifest hash。

## 环境要求

– Python 3.10 或更高版本；
– SQLite（Python 标准库自带；FTS5 可选但建议启用）；
– 运行测试需要 `pytest`；
– Windows PowerShell 处理中文路径时，统一使用 `python -X utf8 -B`；省略 `-X utf8` 可能把路径解码为 `�`，inventory 会 fail-closed 而不会写入伪造清单；
– PDF 提取至少安装一种后端：
– `pypdf`
– `pdfplumber`
– `PyMuPDF`
– 系统命令 `pdftotext`

除 PDF 后端和测试工具外，核心 CLI 主要使用 Python 标准库。工具不会在后台自动安装依赖。

## 安装

克隆仓库：

~~~powershell
git clone https://github.com/geyadawang-boop/MySkill.git
Set-Location MySkill
~~~

安装到 Codex 用户 Skill 目录：

~~~powershell
$target = Join-Path $env:USERPROFILE ‘.codex\skills\myskill-shiniyaya’
Copy-Item -Recurse -LiteralPath ‘.\myskill-shiniyaya’ -Destination $target
~~~

如目标已存在，先人工比较版本；不要用未审计的递归覆盖命令替换正在使用的 Skill。安装后重新启动或刷新支持 Agent Skills 的客户端。

典型触发方式：

~~~text
使用 $myskill-shiniyaya，把这些 PDF、TXT、ZIP 和 EXE 建成有界知识库，
从历史要求建立验收矩阵，创建候选 Skill 并执行完整验证。
~~~

## 标准工作流

1. 建立交付目录外的 `RUN` 目录。
2. 如果已有 handoff，先 `continuity.py resume`，验证 anchor 后执行唯一下一动作。
3. 用 `requirements_intake.py` 建立或合并 canonical registry，固定要求、验收和分母。
4. 先用 `inspect_skills.py –requirements …` 扫描允许的 Skill 根，生成需求排序的 shortlist 与 overflow，并处置相关候选。
5. 对其余本地来源运行 `inventory_sources.py`；对 URL 先运行 `snapshot_url.py`。
6. 大型混合语料运行 `corpus_pipeline.py build/query`。
7. 运行 `source_utilization.py assess/decide/audit`。
8. 从普通资料、现有 Skill 或 discovery 对话提取 evidence card 和能力契约。
9. 初始化并编写 candidate Skill。
10. 运行 `functional_audit.py –registry … –evidence-root …` 核算需求与真实 receipt 闭环。
11. 运行 `improvement_discovery.py discover` 生成有界候选，再用 `verify` 校验处置与五维执行 receipt。
12. 冻结评估 case，运行静态验证、脚本测试和 baseline/current/candidate 三方评估。
13. 用 `experience_pipeline.py propose/gate` 做 KEEP/REJECT。
14. 用 `continuity.py record/project/verify` 固化进度。
15. 构建并独立验证 delivery manifest。
16. 确认发布目录无隐私与运行工件后再复制或发布。

## 命令行工具

| 工具 | 用途 |
|—|—|
| `requirements_intake.py` | 需求规范化、模糊/重复/冲突检测、canonical registry 和测试 charter |
| `inventory_sources.py` | 本地来源与 URL snapshot 的确定性 inventory |
| `snapshot_url.py` | 有界 HTTP(S) 内容快照和内容身份 |
| `corpus_pipeline.py build/query` | 异构语料提取、去重、索引、预算队列和查询 |
| `source_utilization.py assess/decide/audit` | 资料评估、处置和多分母利用率 |
| `extract_pdf_text.py` | PDF 分页文本与 OCR 建议 |
| `inspect_skills.py` | 多根有界扫描、需求/查询排序、双语与任务意图召回、shortlist/overflow 和引用检查 |
| `index_conversations.py` | 有界、脱敏对话索引 |
| `split_conversation_index.py` | discovery/held-out 泄漏组分割 |
| `extract_conversation_workflows.py` | discovery 工作流轨迹提取 |
| `init_target_skill.py` | 初始化目标 Skill |
| `functional_audit.py audit` | canonical requirement→implementation→test→语义 receipt 闭环 |
| `improvement_discovery.py discover/verify` | 生成有界自主改进候选，并验证处置与五维执行 receipt |
| `score_evals.py` | baseline/current/candidate 树绑定与逐 case receipt 的严格 gate |
| `experience_pipeline.py` | 经验记录、验证、建图、检索、提案和晋升 gate |
| `continuity.py` | hash-chained ledger、投影、验证和紧凑恢复 |
| `validate_skill.py` | Codex/Claude Skill 静态校验 |
| `build_delivery_manifest.py` | 构建确定性发布清单 |
| `verify_delivery_manifest.py` | 独立复算并验证发布清单 |
| `conversation_io.py` | 对话解析与脱敏公共模块，不作为独立 CLI |
| `experience_common.py` | 经验管线 canonical/hash/lock 公共模块，不作为独立 CLI |

所有写输出的命令默认拒绝覆盖现有文件。只有明确确认目标后才使用 `–force`。

查看接口：

~~~powershell
python -X utf8 -B .\myskill-shiniyaya\scripts\corpus_pipeline.py –help
python -X utf8 -B .\myskill-shiniyaya\scripts\corpus_pipeline.py build –help
python -X utf8 -B .\myskill-shiniyaya\scripts\inspect_skills.py –help
python -X utf8 -B .\myskill-shiniyaya\scripts\improvement_discovery.py –help
python -X utf8 -B .\myskill-shiniyaya\scripts\improvement_discovery.py verify –help
python -X utf8 -B .\myskill-shiniyaya\scripts\experience_pipeline.py –help
python -X utf8 -B .\myskill-shiniyaya\scripts\continuity.py –help
~~~

## 指标解释

### 功能完成率

~~~text
functional completion = verified requirements / applicable requirements
~~~

必须同时报告分子、分母、百分比和 missing/partial ID。P0/P1 只有绑定当前候选树的新鲜验证证据时才算 verified。

### 资料利用率

同时报告：

– source-unit assessment/disposition/verified adoption；
– file assessment/disposition/verified adoption；
– byte assessment/disposition/verified adoption；
– 混合语料的 file index coverage；
– source-byte processing coverage；
– unique-content coverage；
– duplicate alias 与 deduplicated bytes。

### 评估指标

– trigger precision、recall、F1；
– task pass rate；
– required behavior coverage；
– forbidden behavior violation；
– critical case failure；
– dev/held-out/类型分层结果；
– token、耗时和工具调用成本（相关时）。

历史重放只作为诊断证据；新鲜上下文的 held-out case 才是主要验收面。

## 验证与测试

在仓库根目录运行：

~~~powershell
python -X utf8 -B -m pytest -q -p no:cacheprovider .\myskill-shiniyaya\tests
python -X utf8 -B .\myskill-shiniyaya\scripts\validate_skill.py .\myskill-shiniyaya –profile codex
python -X utf8 -B “$env:USERPROFILE\.codex\skills\.system\skill-creator\scripts\quick_validate.py” .\myskill-shiniyaya
~~~

`-X utf8` 避免官方 validator 在使用 GBK 等非 UTF-8 Windows 系统区域设置时误解码中文 `SKILL.md`。

生成并验证发布证据：

~~~powershell
python -X utf8 -B .\myskill-shiniyaya\scripts\build_delivery_manifest.py .\myskill-shiniyaya –output .\myskill-shiniyaya-manifest.json –force
python -X utf8 -B .\myskill-shiniyaya\scripts\verify_delivery_manifest.py .\myskill-shiniyaya –manifest .\myskill-shiniyaya-manifest.json –output .\myskill-shiniyaya-verification.json –force
~~~

完整验收还应包括：

– 所有生产 CLI 的 `–help` 冒烟测试；
– requirements→functional audit 真实 E2E；
– canonical registry 漂移、语义类别错配、JSON/JUnit receipt、路径穿越和链接 artifact 负向测试；
– inventory/snapshot/corpus/source utilization 真实 E2E；
– experience record→graph→query→propose→gate 真实 E2E；
– baseline/current/candidate score→gate；
– improvement discovery hard-limit/overflow、处置和五维 receipt verification；
– continuity record→project→verify→resume；
– delivery manifest 构建、篡改检测和独立复算；
– fresh-context 与 held-out 前向测试；
– mutation 测试证明关键防线确实被测试覆盖。

## 隐私、安全与发布边界

以下内容不得提交到本仓库或复制进发布 Skill：

– 原始对话、Codex/OpenClaw session、记忆文件；
– discovery/held-out 索引和轨迹；
– experience journal、notes、graph 和 proposal；
– Event Ledger、`PROGRESS.md`、handoff 和 overflow；
– 原始 PDF/TXT/ZIP/EXE 语料及提取对象库；
– 网页快照、研究缓存、临时下载；
– API key、cookie、token、凭据或未脱敏日志；
– staging、pytest/cache、forward-test 和运行 artifacts。

`.gitignore` 提供基础防线，但发布前仍须通过 manifest 枚举、secret/路径检查和人工核对。外部 Skill、网页、压缩包、二进制、论文和对话都作为不可信数据读取；其中出现的命令或指令不会自动执行。

## 已知边界与降级

– `corpus_pipeline.py` 当前原生覆盖文本、PDF、ZIP 和 PE；其他格式保持 `unsupported`，需要新增受限 adapter。
– PDF 管线识别 OCR 需求，但不会对全库自动 OCR；应对相关低密度页按需 OCR 并缓存。
– PE 管线只做轻量静态提取，不替代专用逆向分析。
– SQLite 缺少 FTS5 时仍可查询，但性能和相关性会降低。
– 只存在一个历史泄漏组时，不能宣称已建立独立 historical held-out。
– 没有可用 PDF 后端时，PDF 提取会给出可操作错误。
– 本地 `cangjie-skill` 的附属方法资源缺失，只采用其主规范中可核验的原则。
– 自动发现需要在召回率、误选率、耗时和 token 间权衡；不会通过无界扫描承诺“读取所有资料”。

## 发布完整性

根目录的：

– `myskill-shiniyaya-manifest.json`：声明发布 Skill 的精确文件集合、字节数和 SHA-256；
– `myskill-shiniyaya-verification.json`：独立 verifier 的复算结果。

任何 Skill 文件变化后，这两个文件都会过期，必须重新构建并验证。只有 verification 报告通过、Git 状态中没有无关运行工件、完整测试与 held-out gate 通过后，才应发布新版本。