skillpack-one 0.1.0-alpha.10

package/docs/research/2026-09-02-wikiskill-skill-state.md

@@ -0,0 +1,67 @@
+# WikiSkill and SKILL.state: implications for SkillPack One
+
+Date: 2026-09-02  
+Sources: [WikiSkill](https://arxiv.org/pdf/2608.27454) v1 and [SKILL.state](https://arxiv.org/pdf/2608.26263) v2, read from the official arXiv PDFs.  
+Decision question: what should SkillPack One adopt without changing Category → Atom → Capability Pack → Meta?
+
+## Direct answer
+
+The papers address different time scales and are complementary:
+
+| Paper | Time scale | Main state | Best placement in SkillPack One |
+| --- | --- | --- | --- |
+| WikiSkill | across optimization iterations | accumulated success/failure patterns and intervention outcomes | Meta-governed Evolution Knowledge |
+| SKILL.state | within one long-running execution | current future-relevant world/workflow state | optional Capability Pack runtime-state profile |
+
+Neither finding requires a new Skill kind. Categories still route needs, Atoms retain one capability boundary, Capability Packs compose them, and Meta Skills govern lifecycle changes.
+
+## What the papers actually show
+
+### WikiSkill
+
+WikiSkill separates immutable raw traces, a persistent wiki of consolidated patterns and impact logs, and reversible active Skills. Its inference agent uses active Skills but is deliberately denied wiki access; the maintainer and proposer can inspect the wiki and selected traces. Each iteration proposes one atomic Skill change and accepts it only when validation improves, while wiki knowledge persists after both accepted and rejected proposals.
+
+The paper evaluates five benchmarks and five models. Table 1 averages three independent evolution runs and uses paired bootstrap tests with 1,000 resamples. WikiSkill has the highest reported average for every model. The most decision-relevant ablation is Table 3: with wiki access disabled for the inference agent, adding wiki access for the proposer raises the reported four-benchmark average from 48.7% to 63.7%; exposing the wiki to the inference agent lowers the default configuration from 63.7% to 60.9%.
+
+The transfer study is a warning as well as a positive result. Evolved procedures often transfer across model families, but Table 2 includes severe negative transfer: a Qwen-3.5-4B spreadsheet Skill reduces Gemini-3.5-Flash from 50.5% without a Skill to 18.1%. The authors attribute this to small-model workarounds and fragmented diagnostics constraining a stronger model.
+
+Material limitations: the study injects full Skills and does not test retrieval; validation splits are small; the wiki has no automatic pruning; strict immediate-improvement gating can reject enabling changes; and the suite does not cover hundreds-of-action or multi-hour execution.
+
+### SKILL.state
+
+SKILL.state replaces append-only conversational execution with `(immutable procedure, current structured state, latest observation)`. The model may reason within a step, but only a validated state patch and action survive. Under the paper's bounded procedure/state/observation assumption, per-step context is O(1) in horizon and cumulative prompt tokens are O(T), rather than the O(T²) accumulation of replayed history.
+
+The paper tests a controlled two-environment SkillExecBench over five seeds plus InterCode CTF and Sierra τ-Bench. On the 100-step warehouse task, Table 1 reports 65,408 total tokens and 0.94 accuracy for SKILL.state versus 1,062,387 tokens and 0.91 for the transcript-plus-state baseline. At 200 steps it reports 122,384 tokens and 0.94 versus 5,041,164 and 0.88. On public tasks, Table 4 reports the highest completion rate for SKILL.state on InterCode CTF, τ-Bench Retail, and τ-Bench Airline, with lower cumulative tokens than the compared runtimes.
+
+The budget-matched control matters: shortening history alone performs badly, so the reported gain is not evidence for arbitrary truncation. It supports an explicit sufficient-state representation.
+
+Material limitations: a fixed state is unsafe when the relevant schema must be discovered dynamically, when an earlier observation's future relevance was missed, or when history itself is the requested output (audit, debugging, provenance). Multi-agent writes need conflict resolution. Smaller models also produced premature deletion/overwrite, type coercion, and malformed JSON, so deterministic merge and validation are necessary but do not prove semantic correctness.
+
+## Adopted
+
+1. **Evolution Knowledge, not a fifth Skill type.** `.skill-system/knowledge/` stores non-executable, scoped patterns with evidence, confidence, supersession, and a generated index. Raw runs, learned patterns, and active Skills remain separate.
+2. **Knowledge for Meta governance only.** Ordinary task execution cannot read the pattern layer. Proposals cite relevant pattern IDs; accepted and rejected outcomes remain evidence.
+3. **Prunable semantics with preserved provenance.** Unlike WikiSkill's never-pruned wiki, patterns may be superseded or archived. Silent deletion is forbidden.
+4. **Opt-in pack runtime state.** A Capability Pack may declare a JSON Schema, initial state, JSON Merge Patch semantics, and an external audit-log policy. The first profile is `safe-skill-evolution`.
+5. **Validate before commit.** Current state and candidate patches are deterministically validated; a rejected patch leaves current state unchanged. Dangerous prototype keys are rejected.
+6. **History remains out-of-band, not destroyed.** The runtime prompt may use only current state, but immutable audit evidence remains available for governance, provenance, debugging, and rollback.
+
+## Adjusted or deferred
+
+- Automatic trace sampling, Wiki Maintainer generation, and autonomous Skill proposal loops remain deferred until live, permission-bounded task traces and an independent verifier exist.
+- Runtime-state profiles are optional and pack-specific. There is no universal state schema and no forced history deletion.
+- Pi and Codex adapters do not yet execute long tasks through the state loop. The current release certifies schema, patch, and composition mechanics only; it does not claim the papers' token or accuracy gains.
+- Neutral enabling changes still require explicit staged evidence. They are not automatically admitted merely because WikiSkill identifies strict gating as a limitation.
+- Multi-agent merge semantics, constrained decoding, semantic state verification, state telemetry, and long-horizon benchmark certification remain future work.
+
+## Rejected
+
+- Replacing the four-layer SkillPack architecture with either paper's ontology.
+- Giving ordinary task agents direct access to Evolution Knowledge.
+- Automatically promoting generated Skills or trusting one validation score.
+- Treating model-specific workarounds as universally transferable procedures.
+- Discarding audit history for tasks whose purpose is explanation, debugging, compliance, or provenance.
+
+## Confidence and stopping rule
+
+Confidence is high that the two mechanisms fit distinct existing layers because this follows directly from their system boundaries and the repository's current contracts. Confidence is moderate that they will improve real SkillPack One executions: no live Pi provider run or long-horizon pack benchmark has yet measured lift. Research stopped after reading every page, checking the principal architecture figures, result tables, ablations, prompts, appendices, and stated limitations; further secondary commentary would not change the implementation decision.

package/docs/runtime-state.md

@@ -0,0 +1,31 @@
+# Capability Pack runtime state
+
+Runtime state is an optional execution contract for long-running Capability Packs. It does not change Skill discovery, Atom boundaries, or the agent harness by itself.
+
+A profile declares:
+
+- a pack-specific JSON Schema;
+- a schema-valid initial state;
+- deterministic JSON Merge Patch semantics;
+- `external-audit-log`, meaning active context may use current state while full run evidence remains separately retained.
+
+`skillpack compose` exposes the profile with the pack plan. The state CLI initializes, validates, or applies a patch without writing an active run:
+
+```sh
+npm run skillpack -- state init safe-skill-evolution
+npm run skillpack -- state validate safe-skill-evolution current.json
+npm run skillpack -- state apply safe-skill-evolution current.json patch.json
+```
+
+Both current and candidate states are validated before the candidate is returned. JSON Merge Patch preserves unspecified fields, uses `null` for deletion, replaces arrays, and rejects prototype-mutating keys. A failed patch never commits partial state.
+
+## Applicability boundary
+
+Use a runtime-state profile only when future decisions can safely depend on a bounded, reviewable sufficient state. Do not use it as the sole context when:
+
+- the relevant schema must be discovered dynamically;
+- an early observation may become important before its relevance can be recognized;
+- the requested output is the historical trajectory itself, such as audit, debugging, provenance, or explanation;
+- concurrent agents need unresolved merge semantics.
+
+The profile is currently a portable contract and deterministic validator. Pi and Codex adapters do not yet run an end-to-end state loop, so this release makes no live accuracy, latency, or token-saving claim.

package/docs/security-lifecycle.md

@@ -0,0 +1,23 @@
+# Lifecycle security reviews
+
+A reusable capability crosses multiple trust boundaries before it creates an effect. SkillPack One reviews those boundaries independently instead of treating one scanner, signature, or model judgment as a universal safety decision.
+
+| Stage | Trust assumption | Representative checks |
+| --- | --- | --- |
+| Authoring | The description, behavior, and requested authority agree. | hidden instructions, permission inflation, unsafe workflow construction |
+| Storage | The admitted artifact remains authentic and current. | provenance, payload digest, version lineage, rollback, dependencies |
+| Retrieval | Relevant candidates cannot win through manipulation alone. | keyword stuffing, semantic camouflage, Sybil duplicates, trigger poisoning |
+| Selection | Planner-visible metadata faithfully represents behavior and permission. | fabricated endorsements, deceptive claims, prompt injection, permission mismatch |
+| Execution | Every operation stays inside runtime authority and information-flow policy. | unauthorized tools, unsafe composition, sensitive sinks, privilege escalation |
+| Evolution | An update preserves provenance, boundaries, and protected behavior. | permission escalation, instruction injection, dependency changes, publisher compromise |
+
+Review artifacts conform to [`schemas/lifecycle-security-review.schema.json`](../schemas/lifecycle-security-review.schema.json). Validate one with:
+
+```sh
+npm run skillpack -- security check path/to/review.yaml
+```
+
+Every applicable stage must list the threats considered, traceable evidence, and residual risk. A `not-applicable` stage requires an explicit rationale. Updates re-enter the lifecycle instead of inheriting the previous version's trust.
+
+A passing review is necessary but not sufficient. Semantic consistency checks do not authorize runtime operations, signatures do not prove benign behavior, retrieval filtering does not replace planner validation, and runtime guards may still miss implicit information flow through model transformations.
+

package/docs/zh-CN/catalog-methodology.md

@@ -0,0 +1,46 @@
+# 目录采集方法
+
+这个目录为分类、拆分和组合提供证据，不是安装清单。
+
+`catalog/decomposition-map.yaml` 补齐“采集到本地设计”的闭环：每个非分类本地能力和每个能力包都映射到代表性的目录条目 ID，记录综合时采用的设计贡献，并绑定目录快照摘要。所有映射均为 `design-evidence-only`，不会复制、安装、执行或晋级上游内容。
+
+## 当前快照
+
+2026-09-02 快照包含 658 条规范化记录：
+
+- 来自 10 个官方或成熟社区仓库的 388 个 Agent Skill；
+- 来自官方 MCP Registry 的 270 个最新活动 MCP Server；
+- 307 条从固定 Git revision 检测到仓库许可证；
+- 351 条许可证仍未知，因此不能复制进本仓库或能力包。
+
+精确数量、revision 与聚合摘要记录在 `catalog/snapshots/manifest.yaml`。
+
+## 采集规则
+
+### Agent Skill
+
+采集器使用浅层、blob 过滤且不 checkout 的只读 Git 克隆，只列出 `HEAD` 中受版本控制的 `SKILL.md` 路径。它记录固定 commit、仓库、路径、作者命名空间、检测到的仓库许可证和新鲜度；不会运行 hook、包管理器、脚本或 Skill 指令。
+
+### MCP Server
+
+采集器读取[官方 MCP Registry](https://registry.modelcontextprotocol.io/)无需认证的只读 `GET /v0.1/servers` 接口，规范化每个最新活动版本，并以 SHA-256 固定其元数据。不会连接或执行其中声明的包和远程端点。
+
+官方文档提醒聚合器自行保存快照并跟踪删除状态，因为预览服务不保证持久性。因此离线测试使用仓库中提交的规范化快照，而不依赖实时服务。
+
+## 信任状态
+
+- `unreviewed`：只发现路径与来源，未检查指令。
+- `metadata-reviewed`：已规范化注册表元数据，未检查实现。
+- `statically-reviewed`：静态检查过指令和代码，未执行。
+- `sandbox-tested`：已在隔离环境执行并检查行为。
+- `rejected`：存在策略、来源或安全问题。
+
+被收录不会自动提升信任等级。安装必须经过独立安全审查和显式授权。
+
+## 许可证规则
+
+许可证检测保持保守，只从常规许可证文本识别 Apache-2.0、MIT、GPL-3.0-only、AGPL-3.0-only 与 BSD-3-Clause。无法识别、缺失或冲突时一律标记 `unknown`。未知许可证项目可以参与分类和重复分析，但不得复制其文本、脚本或资源。
+
+## 可复现性
+
+运行 `npm run skillpack -- catalog collect` 可按 `catalog/sources.yaml` 刷新。配置的 `verifiedAt`、固定 revision、逐项指纹和快照摘要使变更可审查。CI 只校验提交的快照，不需要实时联网。

package/docs/zh-CN/evaluation.md

@@ -0,0 +1,38 @@
+# 评测与发布门禁
+
+训练器把 Skill 命中与 Skill 执行视为两个独立问题。Skill 可能命中正确却不遵守流程，也可能手工调用时表现很好但始终无法被发现。
+
+## 数据集隔离
+
+- `train`：提案生成可以看到。
+- `dev`：快速迭代与回归反馈。
+- `test`：发布留出证据，不能输入提案生成。
+- `adversarial`：受保护的歧义、否定、不调用与安全案例。
+- `tasks`：带产物 Rubric 的可执行场景。
+
+在 split 之间移动样例会改变证据含义，必须审查。同一提案不能同时修改受保护数据集、其基线和被测 Skill。
+
+## 路由指标
+
+`categoryHit1`、`categoryHit3`、`atomHit1`、`atomHit3`、`atomMrr`、`nonInvocationAccuracy` 和 `safetyPassRate` 各自独立。`npm run skillpack -- gate` 会列出每个独立数据集上的每个失败指标。当前基线通过开发、英文留出、中文留出和对抗四套题集。
+
+## 完成指标
+
+任务完成使用 `taskCompletionRate`、`rubricPassRate` 和 `blockedRate`。Mock 的 synthetic 结果只证明管线连通，不能认证真实质量。真实 Harness 结果必须记录 Provider、模型、Harness 版本、Rubric 证据、成本和延迟，才可成为发布基线。
+
+## 成对 Skill 效果
+
+新 Skill 准入和重要修改必须在相同数据集、样例、Harness 与版本上分别运行 `without-skill` 和 `with-skill`。`skillpack harness effect <without.json> <with.json>` 会报告任务完成率增益、Rubric 增益、阻塞率变化，以及可用时的成本和延迟变化。默认门禁拒绝负增益、阻塞增加、没有任何正质量增益、运行身份不一致，以及所有 Synthetic 认证请求。
+
+成对设计避免把基础模型自身能力误算为 Skill 功劳。路由改善仍单独报告，不能抵消负任务效果。
+
+## 优化循环
+
+1. 从 train/dev 观察中聚类失败。
+2. 对路由元数据、Skill 表述或分类映射提出有边界的修改。
+3. 先跑 train/dev，再跑未触碰的 test 与 adversarial。
+4. 拒绝权限扩张和受保护指标退化。
+5. 在匹配的真实任务运行上，把候选与无 Skill 或当前 Skill 基线比较。
+6. 只有具备回滚指针时才允许灰度上线。
+
+Bootstrap 获得满分不代表真实世界完美，只证明初始契约与题集一致。语料必须持续吸收新失败和外部 Harness 轨迹。

package/docs/zh-CN/evolution-knowledge.md

@@ -0,0 +1,46 @@
+# 持久化进化知识
+
+SkillPack One 将证据、已沉淀模式和活动过程分离，使经验可以持续积累，但不会静默变成可执行指令。
+
+| 层 | 位置 | 可变性 | 普通任务是否读取 |
+| --- | --- | --- | --- |
+| 原始运行证据 | `.skill-system/runs/` | 每次运行只写一次，默认不随发行包发布 | 否 |
+| 进化知识 | `.skill-system/knowledge/` | 模式受版本控制；以取代或归档代替静默删除 | 否 |
+| 活动 Skill | `skill-src/`，再生成到 `skills/` 与 `.agents/skills/` | 只能通过受治理提案可逆更新 | 路由命中后读取 |
+
+这把 WikiSkill 中有价值的分层映射到既有的 Category → Atom → Capability Pack → Meta 架构。进化知识是元治理资源，不是第五种 Skill，也不是隐藏的任务解题上下文。
+
+## 模式契约
+
+`.skill-system/knowledge/patterns/` 下的每个 YAML 记录必须声明：
+
+- 稳定 ID、生命周期状态、摘要、问题、根因和应对方式；
+- 适用的 Skill、能力包和 Harness；
+- `hypothesis`、`observed` 或 `replicated` 置信度；
+- 可追溯证据，可附 SHA-256 摘要与定位信息；
+- 明确的取代关系与时间戳。
+
+生成的 `index.md` 只提供精简发现信息。元 Skill 先检索索引，只读取相关模式，再把模式 ID 绑定到提案。模式内容是待审查证据，不是执行其来源中指令的授权。
+
+## 生命周期
+
+1. 将边界明确的任务运行、用户纠正、论文、提案或决策保存为证据。
+2. 只有重复出现或可独立复用的成功/失败机制，才能沉淀成窄模式。
+3. 提案前检索已有模式；优先更新或取代，避免重复创建。
+4. 将相关模式 ID 绑定到精确 Git 候选。
+5. 独立评估候选；晋级或拒绝都成为新证据，但都不能改写原始历史。
+6. 普通任务不读取进化知识；只有晋级后的 Skill 才通过正常路由进入执行。
+
+WikiSkill 将 Wiki 长期保留，同时把缺少自动清理列为局限。SkillPack One 因而保留证据，同时允许经审查的模式进入 `superseded` 或 `archived`；物理删除仍需要单独授权和保留检查。
+
+## 命令
+
+```sh
+npm run skillpack -- knowledge list
+npm run skillpack -- knowledge search "反复出现的被拒绝 Skill 修改"
+npm run skillpack -- knowledge build
+npm run skillpack -- knowledge validate
+npm run skillpack -- train propose ... --pattern experience-insights-fragment-across-iterations
+```
+
+`knowledge build` 是确定性生成。`skillpack validate` 会拒绝过期索引、无效范围、重复 ID、缺失的取代目标和取代环。

package/docs/zh-CN/evolution-policy.md

@@ -0,0 +1,23 @@
+# 受治理的进化策略
+
+自优化指基于证据的维护，不是无限制自我改写。
+
+每个新提案都必须声明目标、作者模式、责任作者、适用时的生成模型、基础 revision、候选 revision、回滚 revision、观察到的失败、允许文件、实际变更文件、生成数据集、评测数据集、前后权限包络和批准记录。历史追加式记录保持有效，不追溯改写。生成的 `skills/` 与 `.agents/skills/` 投影绝不能直接修改。
+
+如果提案由重复出现的进化知识模式驱动，就必须记录稳定模式 ID。无论候选晋级还是被拒绝，模式层都独立保留，但绝不能注入普通任务推理。详见[持久化进化知识](evolution-knowledge.md)。
+
+`npm run skillpack -- train propose --id <id> --target <skill-id> --observation <evidence> --author <identity> --authorship <human|model-assisted|model-generated> [--generator <model>]` 会依据精确的 `HEAD^..HEAD` 规范 Git 差异生成提案。评估要求 `HEAD` 等于 `candidateRevision`，要求 `changedFiles` 与 Git 差异一致，并拒绝已跟踪文件漂移或意外的未跟踪文件。生成投影是可复现产物，不计入规范差异。
+
+## 硬性不变量
+
+- test、adversarial 和 tasks 数据集不能参与生成提案。
+- 任何超出提案边界的文件都会拒绝提案。
+- 权限扩大必须有具名、带时间的批准。
+- `meta-skill-governor` 不能在同一提案中修改自身和自身门禁/进化策略。
+- 受保护指标不得退化。
+- test、adversarial、tasks 数据集、已提交基线和 `evals/gates.yaml` 不能在认证同一候选时同时变更。
+- 上线必须生成只追加的决策记录，并具备不同的回滚 revision。
+- 纯人工候选不能由作者本人晋级；模型辅助或模型生成候选不能由生成模型晋级。
+- 删除必须在依赖和保留检查后另行获得 destructive-maintenance 批准。
+
+提案应尽量小。如果分类、权限、行为和评测同时变化，应拆开以保持因果可验证。

package/docs/zh-CN/harnesses.md

@@ -0,0 +1,40 @@
+# Harness 适配器
+
+Skill 的表现同时取决于 Skill 本身和 Agent Harness。每次运行都记录 Harness 名称与版本，不把不同 Harness 的结果假装成可直接互换。
+
+## Pi：默认真实适配器
+
+仓库固定使用 `@earendil-works/pi-coding-agent` 0.84.4。适配器直接调用 Pi 导出的 `loadSkillsFromDir` 做真实 Skill 发现校验，而不是用项目自己的近似逻辑。模型路由和任务执行通过 Pi 非交互、无会话 CLI 运行，并显式加载生成的 `skills/` 投影。
+
+```sh
+npm run skillpack -- harness status
+npm run skillpack -- harness discover --adapter pi
+npm run skillpack -- harness tasks --adapter pi --provider <provider> --model <model>
+npm run skillpack -- harness tasks --adapter pi --provider <provider> --model <model> --skills disabled > without-skill.json
+npm run skillpack -- harness tasks --adapter pi --provider <provider> --model <model> --skills enabled > with-skill.json
+npm run skillpack -- harness effect without-skill.json with-skill.json
+```
+
+凭据始终由 Pi 自己管理，本项目不会读取或输出凭据值。若没有可用 Provider，适配器返回结构化 `blocked`，绝不会用 Mock 分数冒充真实分数。
+
+## Mock：确定性 CI 适配器
+
+Mock 在无网络、无 API Key 条件下验证协议、数据集、路由指标、Rubric 和门禁。结果始终标记 `synthetic: true`，不能证明模型的真实任务能力。
+
+## Codex 原生目录适配器
+
+它检查 `.agents/skills` 与生成投影是否一致，并回放确定性路由轨迹；不会依赖未公开的 Codex UI 行为自动执行任务。未来可导入 Codex 导出的轨迹作为证据。
+
+## DeepSeek Harness（DSH）：可选适配器
+
+在显式固定兼容 CLI 版本前，DSH 保持禁用。命令缺失时只返回可操作的阻塞原因，不影响其余 CI。只有实现相同的发现、健康、路由和执行协议后，其分数才能进入发布门禁。
+
+## 完成情况声明
+
+路由门禁与任务完成门禁彼此独立。确定性路由通过，并不代表真实模型任务已经认证。公开报告必须保留阻塞、模型/Provider、Rubric 失败、成本和延迟，不能省略缺失证据。
+
+Skill 效果还要求在相同数据集和 Harness 身份下，分别提供无候选 Skill 与启用候选 Skill 的成对运行。把两次任务结果保存为 JSON 后运行 `harness effect`；不匹配运行和 Synthetic 证据都会被拒绝认证。
+
+## Runtime-state profile
+
+能力包可以声明可移植 runtime-state profile，但适配器不会自动执行它。当前 `skillpack state` 只认证初始状态和补丁机制。未来若某适配器声明长任务收益，就必须实现相同 Schema/合并契约，把完整审计证据保留在活动状态之外，并成对报告对话历史模式与状态模式的完成率、token、延迟和恢复指标。在此之前，不能把论文中的效率收益归因于 Pi、Codex 或 DSH。

package/docs/zh-CN/npm-release.md

@@ -0,0 +1,87 @@
+# 将 SkillPack One 发布到 npm
+
+SkillPack One 通过经过审核的 GitHub Release 和 npm Trusted Publishing 发布。长期流程使用短时 OIDC 凭证，不在仓库保存 `NPM_TOKEN`；公开仓库中的公开包会由 npm 自动生成 provenance。
+
+## 工作流强制约束
+
+`.github/workflows/publish-npm.yml` 会：
+
+- 只在 GitHub Release 发布时运行；
+- 要求标签对应提交可从 `origin/main` 到达；
+- 要求标签严格等于 `v<package.json version>`；
+- 要求 GitHub prerelease 标记与 SemVer 一致；
+- 预发布版本进入 npm `next`，稳定版本才进入 `latest`；
+- 发布前运行完整的 `npm run ci` 与 `npm pack --dry-run`；
+- 使用 GitHub 托管 Runner、`npm` Environment，以及最小的 `contents: read`、`id-token: write` 权限；
+- 在高权限发布任务中关闭包管理器缓存，并禁止依赖安装生命周期脚本。
+
+## 新 npm 包的一次性首次发布
+
+npm 要求包已经存在，才能绑定 Trusted Publisher。编写本文档时，`skillpack-one` 尚未被注册，因此第一次必须由启用账户级 2FA 的维护者创建。
+
+1. 把包含 `0.1.0-alpha.10` 的发布提交合并到 `main`，创建并推送标签；这一次不要创建 GitHub Release：
+
+   ```sh
+   git tag -a v0.1.0-alpha.10 -m "SkillPack One v0.1.0-alpha.10"
+   git push origin v0.1.0-alpha.10
+   ```
+
+2. 在该标签的干净检出中交互登录，并检查实际包内容：
+
+   ```sh
+   npm install --global npm@11.19.1
+   npm login
+   npm ci --ignore-scripts
+   npm run ci
+   npm pack --dry-run
+   npm publish --access public --tag next
+   ```
+
+3. 确认 `https://www.npmjs.com/package/skillpack-one` 中 `0.1.0-alpha.10` 位于 `next`。不要再为这个已发布的首次版本创建 GitHub Release，否则自动流程会按设计拒绝覆盖不可变版本。
+
+## 配置无 Token 发布
+
+1. 在 GitHub 仓库设置中创建名称严格为 `npm` 的 Environment，配置必要审核人，并按需要只允许受保护发布标签部署。
+2. 使用 npm 11.19.1 或更高版本、并启用账户级 2FA 后执行：
+
+   ```sh
+   npm login
+   npm trust github skillpack-one \
+     --repo WnagoiYy/skillpack-one \
+     --file publish-npm.yml \
+     --env npm \
+     --allow-publish
+   ```
+
+   文件名和 Environment 名称区分大小写，工作流必须已经存在于默认分支。
+3. 运行 `npm trust list skillpack-one`，或进入 npm 包设置的 **Trusted publishing** 核对。
+4. 第一次自动发布成功后，把 npm **Publishing access** 改为 **Require two-factor authentication and disallow tokens**，并撤销旧写入 Token。
+5. 在 GitHub 保护 `v*` 标签，防止未审核提交成为发布候选。
+
+## 日常发布
+
+1. 在经过审核的 PR 中更新 `package.json`、`package-lock.json` 和 `CHANGELOG.md`，绝不复用已发布版本。
+2. 合并到 `main` 并等待 CI 通过。
+3. 从该 `main` 提交创建严格匹配的 `v<version>` 标签。
+4. 为标签发布 GitHub Release。版本包含 SemVer 预发布后缀时必须勾选 prerelease，否则不能勾选。
+5. 审批 `npm` Environment 部署。工作流会把预发布版本发布到 `next`，稳定版发布到 `latest`。
+6. 验证包和来源证明：
+
+   ```sh
+   npm view skillpack-one version dist-tags repository --json
+   npm install --global skillpack-one@next
+   skillpack --version
+   npm audit signatures
+   ```
+
+## 失败与回滚
+
+- 如果在 `npm publish` 前失败，修复源码、使用新版本并发布新的 GitHub Release；不要修改已有标签背后的内容。
+- npm 版本不可覆盖。错误版本应发布修正版，不能覆盖原版本。
+- 通过交互式 2FA 运行 `npm deprecate skillpack-one@<version> "<原因>"` 标记已知问题版本。
+- 使用 `npm dist-tag add skillpack-one@<已知良好版本> next` 或 `latest` 恢复分发标签，再发布修正版。
+- 除范围明确的紧急安全事件外，不使用 `npm unpublish`；即使撤回，名称与版本组合也不能复用。
+
+未来若希望采用更严格模式，可以把 Trusted Publisher 改为只允许 stage，并把 `npm publish` 替换成 `npm stage publish`。这样公开前还需要一次独立 2FA 审批，但 staged publishing 不能创建全新包。
+
+官方资料：[npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)、[`npm trust`](https://docs.npmjs.com/cli/v11/commands/npm-trust/)、[npm provenance](https://docs.npmjs.com/generating-provenance-statements/)和 [GitHub 包发布](https://docs.github.com/zh/actions/tutorials/publish-packages/publish-nodejs-packages)。

package/docs/zh-CN/release-policy.md

@@ -0,0 +1,5 @@
+# 发布策略
+
+版本遵循语义化版本。研究阶段使用 `vMAJOR.MINOR.PATCH-alpha.N`，在真实任务完成率证据获得认证前始终标记为 GitHub 预发布。
+
+发布必须满足：工作区干净、本地与远端 revision 精确一致、该 revision 的 GitHub Actions 无警告通过、独立路由门禁通过、生成投影为最新、官方 Skill/插件校验通过、依赖与秘密扫描通过、来源归属完整，并创建不可变的 annotated tag。已发布标签永不移动；修正使用新的预发布序号。变更日志必须记录面向用户的行为和已知证据边界。

package/docs/zh-CN/research/2026-09-02-agent-skill-literature.md

@@ -0,0 +1,55 @@
+# Agent Skill 论文：证据与取舍
+
+日期：2026-09-02  
+范围：Agent Skill 的结构、检索、组合、评测、安全和受治理进化。
+
+本文记录 SkillPack One 本轮演进采用的证据。不同论文的场景、成熟度和 Harness 并不相同，因此不能把某一项实验结果直接当作普遍规律。
+
+## 指定文章的论文来源
+
+微信页面本身无法访问，但用户已明确文章讨论 [WikiSkill](https://arxiv.org/pdf/2608.27454) 与 [SKILL.state](https://arxiv.org/pdf/2608.26263)。本轮已完整阅读两份 arXiv 官方 PDF，并核对架构图、结果表、消融、附录、提示词与局限。详细映射见[WikiSkill 与 SKILL.state：对 SkillPack One 的启发](2026-09-02-wikiskill-skill-state.md)。
+
+## 证据—启发—取舍
+
+| 证据 | 启发 | SkillPack One 的取舍 |
+| --- | --- | --- |
+| [WikiSkill](https://arxiv.org/pdf/2608.27454) 将不可变轨迹、持久沉淀模式与影响日志、可回滚活动 Skill 分开；消融支持让 Proposer 访问 Wiki，但不让普通推理访问。 | 经验应跨迭代积累，但不能成为隐藏解题上下文，也不能直接激活生成 Skill。 | 增加不可执行 Evolution Knowledge，包含范围、证据、检索、取代和提案引用；被拒绝干预仍保留为证据，普通任务不读取该层。 |
+| [SKILL.state](https://arxiv.org/pdf/2608.26263) 以不可变规范、有界当前状态和最新观察执行长流程，每步验证状态补丁，并把历史移出活动提示。 | 长任务需要显式当前状态契约；任意截断历史不是安全替代。 | 增加能力包可选的专属 runtime-state profile，使用 JSON Schema、经验证的 JSON Merge Patch 和独立审计日志；历史本身是目标或充分状态假设不成立时不强制启用。 |
+| [SkillsBench](https://arxiv.org/abs/2602.12670) 对比无 Skill、精选 Skill 和模型自生成 Skill；首版结果显示精选 Skill 平均有效，但部分任务出现负增益，自生成 Skill 平均帮助很小，聚焦的小模块优于大而全说明。 | “存在、命中、生成流畅”都不能证明 Skill 有帮助。 | 新增 with-Skill/no-Skill 成对效果记录；Synthetic 只能验证管线，不能认证增益；继续保持 Atom 小而聚焦。 |
+| [Skill-Inject](https://arxiv.org/abs/2602.20156) 把 Skill 文件视为 Agent 供应链攻击面，并在基准中观察到很高的攻击成功率。 | 社区文本和脚本即使看起来有用，也仍是不可信输入；简单过滤和更强模型不是授权边界。 | 上游目录继续保持不可执行；激活前检查来源、提示注入、脚本和权限包络；生成身份与批准身份分离。 |
+| [Compositional Skill Routing](https://arxiv.org/abs/2606.18051) 将复杂请求形式化为“分解→检索→组合”，并指出任务分解粒度是大型技能库的主要瓶颈。 | 多步骤任务不能只做 Top-1 Skill 检索。 | 从多个 Atom/Meta 路由信号推荐已有能力包，并把声明的依赖编译成执行阶段；不自由生成巨型 Skill 或无约束执行图。 |
+| [Generative Skill Composition](https://arxiv.org/abs/2606.32025) 把 Skill 子集、数量和顺序视为一个结构化决策。 | 组合不是简单返回 Top-k。 | 能力包计划明确记录稳定 ID、数量、偏序、阶段和验收测试；未来学习型组合器也必须输出同一受约束结构。 |
+| [ToolScope](https://aclanthology.org/2026.acl-long.1573/) 说明重叠工具会干扰选择，合并与上下文过滤可以改善效果。 | 重复不仅浪费目录空间，也会降低命中。 | 重复簇继续作为审查队列；只有结果与失败边界审查后才能合并，不能因相似度自动删除。 |
+| [PORTS](https://aclanthology.org/2025.emnlp-main.507/) 用下游工具使用表现对齐检索器，而不只看文档相似度。 | 检索目标应是任务有效性。 | 可解释词法路由保留为可移植基线；未来语义检索必须在保留集任务增益和安全指标上证明更好。 |
+| [CoEvoSkills](https://arxiv.org/abs/2604.01687) 将迭代生成器与看不到真实测试内容的验证器分离。 | 生成者不能用自己优化过的证据给自己打分。 | 提案记录作者与生成器，晋级要求独立审核，留出集和对抗集保持在候选差异之外。 |
+| [SkillX](https://arxiv.org/abs/2604.04804)、[AutoSkill](https://arxiv.org/abs/2603.01145) 与 [Voyager](https://arxiv.org/abs/2305.16291) 展示了轨迹蒸馏、经验复用、课程和执行反馈。 | 经验可以在不改模型权重的情况下形成能力，但也可能固化噪声与重复。 | 轨迹只形成有边界提案：战略计划映射为能力包，功能分组映射为分类，独立复用执行单元映射为 Atom；不得直接写入活动投影。 |
+| [SkillRet](https://arxiv.org/abs/2605.05726) 面向真实规模的长 Skill 文档检索，修正功能等价造成的假阴性，并对多 Skill 请求报告 Recall 与严格 Completeness；其端到端结果也说明检索分数提高不必然提高任务成功率。 | 只看任一命中的 Hit@K 会掩盖组合缺失，错误地把功能等价项当负样本还会污染训练和评测。 | 在 Hit@K/MRR 之外增加等价感知的 Atom Recall 与 Full Coverage；晋级目标仍是下游成对 Skill 效果。 |
+| [How Well Do Agentic Skills Work in the Wild](https://arxiv.org/abs/2604.04323) 区分强制加载、自主选择、干扰项、检索、适配与无 Skill。条件越贴近真实环境，Skill 收益越脆弱；只有初始 Skill 覆盖足够时，面向具体任务的改写才较有效。 | 可用、检索到、加载、正确使用和最终有益是不同事件；改写主要放大已有有效信息，不能稳定创造缺失能力。 | 为未来真实 Harness 评测定义逐级现实度 profile；不得只凭检索指标晋级改写结果。任务特定合成保持隔离，验证通过前不进入活动 Skill。 |
+| [Agent Skill Security](https://arxiv.org/abs/2607.13987) 将信任边界拆为创作、存储、检索、选择、执行和进化；其受控实验中的防护仍有残余攻击与误报。 | 没有单一扫描器或 LLM Judge 能覆盖完整生命周期；更新必须重新准入，运行时授权独立于元数据审查。 | 增加六阶段生命周期安全审查，每阶段记录证据与残余风险；语义审查通过不能等同于执行安全。 |
+| [SkillNet](https://arxiv.org/abs/2603.04448) 分离分类树、类型化 Skill 关系和发布包，并从安全、完整、可执行、可维护、成本五个维度评估；论文也承认覆盖不完整和投毒贡献尚未彻底解决。 | 目录树不能单独表达替代、组合、打包与依赖，但关系图也不能成为未经审核的权限来源。 | 仅物化已有契约和已审查能力包支持的关系；分类体系继续作为路由骨架，推断关系只能先作为候选。 |
+| [SkillRouter](https://arxiv.org/abs/2603.22455) 表明 Skill 正文包含名称与描述缺失的路由信号，并发现重叠目录中假负样本过滤和 listwise 重排很重要；其核心查询集较小，端到端增益也受实验场景限制。 | 渐进披露不应被误解为离线检索只能看元数据；可使用正文衍生特征，同时仍避免把全库正文注入运行时。 | 保留窄化的运行时披露，但允许可选的离线正文感知索引与重排，共用同一 RouteTrace；增加同领域、功能错误的硬干扰开发集。 |
+| [SkillOpt](https://arxiv.org/abs/2605.23904) 使用有界增删改、严格优于选择集、失败编辑反馈和仅优化器可见的慢速/元状态训练紧凑 Skill。 | 自优化应是有版本的 propose-and-test 循环；平分、看似合理的反思和整篇重写都不是充分证据。 | 增加有界 evolution-attempt 记录，要求严格提升且受保护指标不回退；失败编辑保留为证据，优化器记忆不进入部署 Atom。 |
+
+## 立即采纳
+
+1. `skillpack compose <request>` 只推荐已审查能力包，并把依赖偏序编译成确定性阶段。
+2. `skillpack harness effect <without.json> <with.json>` 在相同数据集和 Harness 下测量 Skill Lift；Synthetic 证据明确不可认证。
+3. 新提案记录 `human`、`model-assisted` 或 `model-generated`。纯人工提案不能由作者本人批准；模型辅助或生成提案不能由生成模型批准。
+4. 社区 Skill 的指令、资源和脚本在来源、注入、权限与执行审查通过前一律视为不可信数据。
+5. Evolution Knowledge 分离原始运行、跨迭代模式和活动 Skill；提案可以引用模式 ID，但普通推理不能读取模式层。
+6. 能力包可以按需声明通过验证的当前状态 profile，同时在活动上下文之外保留完整审计历史。
+
+## 暂缓
+
+- 语义或学习型检索：只有在留出路由、任务增益、成本、延迟和安全上优于确定性基线才采用。
+- Skill-aware 迭代分解：先建设受保护的组合问题集，再进行优化。
+- 轨迹自动生成 Skill：在具备独立验证器与真实任务基线前只能进入隔离提案。
+- 模型权重强化学习：属于重要研究方向，但不进入可移植 Skill 包核心。
+- 自治轨迹沉淀与提案生成、真实 Harness 状态循环、多 Agent 状态合并和约束解码：在具备受保护长任务套件与真实证据前暂缓。
+
+## 明确不采纳
+
+- 用某篇论文的本体替换 Category → Atom → Capability Pack → Meta 治理。
+- 安装或执行整个上游目录。
+- 把相似度当成能力等价或删除授权。
+- 让生成 Skill、生成者或单一总分自行认证上线。

package/docs/zh-CN/research/2026-09-02-retrieval-security-optimization.md

@@ -0,0 +1,33 @@
+# Skill 检索、生命周期安全与有界优化
+
+日期：2026-09-02  
+状态：候选实现的证据综述；所引多数工作是 2026 年预印本。
+
+## 研究问题
+
+如何吸收近期 Agent Skill 研究，同时不替换 SkillPack One 的 Category -> Atom -> Capability Pack -> Meta 架构，也不把学习模型变成安装前置条件？
+
+## 精读来源
+
+- [SkillRet](https://arxiv.org/pdf/2605.05726)：基准构造、功能等价审计、分类、检索指标、端到端实验、附录与局限。
+- [How Well Do Agentic Skills Work in the Wild](https://arxiv.org/pdf/2604.04323)：Skill 收集与检索、逐级现实条件、改写实验、提示与结论。
+- [Agent Skill Security](https://arxiv.org/pdf/2607.13987)：威胁分类、信任边界、实验配置、结果与局限。
+- [SkillNet](https://arxiv.org/pdf/2603.04448)：本体、治理、五维评估、关系图、组合实验、失败分析与局限。
+- [SkillRouter](https://arxiv.org/pdf/2603.22455)：正文信号对照、硬负样本、假负样本过滤、listwise 重排、下游实验与局限。
+- [SkillOpt](https://arxiv.org/pdf/2605.23904)：问题定义、有界优化器、验证闸门、失败缓存、慢速/元更新、迁移与消融。
+
+## 证据到机制
+
+| 当前缺口 | 论文证据 | 候选机制 | 不做出的结论 |
+| --- | --- | --- | --- |
+| 多 Atom 请求只要命中任意一个就得分。 | SkillRet、SkillRouter 区分 Recall 与严格完整覆盖，并审计功能替代项。 | 增加等价感知 Atom Recall@3、Full Coverage@3 和同领域硬干扰项。 | 确定性路由指标不能证明任务成功。 |
+| 渐进披露容易被误解为检索只能看元数据。 | SkillRouter 与真实环境研究都发现正文提供额外信号。 | 允许可选离线正文感知索引/重排，但继续输出统一、可解释 RouteTrace。 | 不把全库正文注入实时提示，也不强制安装模型后端。 |
+| 安全主要集中在准入或执行。 | Agent Skill Security 给出相互独立的生命周期信任边界，并显示任何单一防护都有残余失败。 | 六阶段安全审查；每阶段记录证据和残余风险；更新重新准入。 | 语义审查通过不是运行时授权或信息流安全证明。 |
+| Skill 关系分散在契约和能力包中。 | SkillNet 分离分类、类型化关系和发布包。 | 只从已审查数据物化 `confusable-with`、`compose-with`、`depends-on`、`packaged-in`。 | 推断相似不能授权删除、执行或晋级。 |
+| 提案文件范围受控，但优化器单步不是一等证据。 | SkillOpt 的关键控制是严格验证、有界编辑、失败反馈和仅优化器可见的元状态。 | 只追加 evolution attempt，记录编辑预算、严格提升、受保护回退和拒绝证据。 | 这是控制协议，不是假称复现了 SkillOpt 模型实验。 |
+| 理想化测试掩盖选择与适配失败。 | 真实环境研究区分强制加载、自主选择、干扰、检索、适配和无 Skill。 | 未来真实运行记录现实度 profile 及可用/选择/加载/使用信号。 | Mock Harness 不能认证这些阶段。 |
+
+## 采用边界
+
+候选版本只实现确定性的 Schema、闸门、指标和类型化产物；不提供学习型检索器，不执行下载 Skill，不用模型生成受保护测试标签，也不把论文结果冒充本项目结果。涉及任务效用的结论仍需独立审核和真实 with-Skill/no-Skill 成对证据。
+

package/docs/zh-CN/research/2026-09-02-wikiskill-skill-state.md

@@ -0,0 +1,67 @@
+# WikiSkill 与 SKILL.state：对 SkillPack One 的启发
+
+日期：2026-09-02  
+来源：arXiv 官方 PDF，[WikiSkill](https://arxiv.org/pdf/2608.27454) v1 与 [SKILL.state](https://arxiv.org/pdf/2608.26263) v2。  
+决策问题：在不改变 Category → Atom → Capability Pack → Meta 的前提下，哪些机制值得采用？
+
+## 直接结论
+
+两篇论文作用于不同时间尺度，彼此互补：
+
+| 论文 | 时间尺度 | 主要状态 | 在 SkillPack One 中的归属 |
+| --- | --- | --- | --- |
+| WikiSkill | 多轮优化之间 | 已积累的成功/失败模式与干预结果 | 元治理下的 Evolution Knowledge |
+| SKILL.state | 一次长任务内部 | 对后续行动仍有用的当前世界/流程状态 | 能力包的可选 runtime-state profile |
+
+两者都不需要增加新的 Skill 类型。分类仍负责需求路由，原子仍保持单一能力边界，能力包负责编排，元 Skill 负责生命周期治理。
+
+## 论文实际证明了什么
+
+### WikiSkill
+
+WikiSkill 将不可变原始轨迹、沉淀模式与影响日志的持久 Wiki、可回滚的活动 Skill 分开。执行任务的 Inference Agent 只使用活动 Skill，明确不能访问 Wiki；Maintainer 和 Proposer 可以读取 Wiki 与选定轨迹。每轮只提出一个原子 Skill 修改，只有验证集提升才接受，但无论接受还是拒绝，Wiki 知识都会保留。
+
+论文覆盖五个基准和五个模型。表 1 对三次独立进化运行取平均，并使用 1,000 次成对 bootstrap。WikiSkill 在每个模型的平均结果上都是论文报告的最高值。最关键的消融是表 3：Inference Agent 不访问 Wiki 时，让 Proposer 访问 Wiki，四基准平均从 48.7% 提升到 63.7%；反过来把 Wiki 暴露给 Inference Agent，会把默认配置从 63.7% 降到 60.9%。
+
+跨模型迁移同时给出正面结果和警告。进化程序经常可以迁移，但表 2 也出现严重负迁移：Qwen-3.5-4B 生成的表格 Skill 使 Gemini-3.5-Flash 从无 Skill 的 50.5% 降到 18.1%。作者将其归因于小模型专用 workaround 和碎片化诊断流程限制了更强模型。
+
+重要局限：论文直接注入完整 Skill，没有测试检索；验证集较小；Wiki 没有自动清理；严格的即时提升门禁可能拒绝铺垫型修改；测试没有覆盖数百动作或数小时任务。
+
+### SKILL.state
+
+SKILL.state 用“不可变过程规范＋当前结构化状态＋最新观察”替代不断追加的对话历史。模型可以在单步内推理，但跨步只保留通过验证的状态补丁和动作。在过程、状态与观察大小有界的假设下，单步上下文相对任务长度为 O(1)，累计提示词为 O(T)，而不是回放历史导致的 O(T²)。
+
+论文在五个随机种子的两种 SkillExecBench 环境，以及 InterCode CTF 和 Sierra τ-Bench 上评测。仓库任务 100 步时，表 1 报告 SKILL.state 使用 65,408 tokens、准确率 0.94；带完整历史的 Stateful 基线使用 1,062,387 tokens、准确率 0.91。200 步时分别是 122,384/0.94 与 5,041,164/0.88。公共任务表 4 中，SKILL.state 在三个任务上的完成率都是论文报告的最高值，累计 token 也低于对照运行时。
+
+同 token 预算对照很重要：单纯截断或压缩历史表现很差。因此论文支持的是“显式充分状态”，而不是随意删上下文。
+
+重要局限：当状态结构需要动态发现、早期观察的未来价值当时未被识别，或者历史本身就是目标产物（审计、调试、来源解释）时，固定状态并不安全。多 Agent 并发写入需要冲突解决。较小模型还经常出现提前删除/覆盖、类型错误和 JSON 格式错误，所以确定性合并与 Schema 验证是必要条件，但不能证明语义正确。
+
+## 已采纳
+
+1. **Evolution Knowledge，而不是第五种 Skill。** `.skill-system/knowledge/` 保存不可执行、有范围、有证据、可取代并有生成索引的模式；原始运行、知识模式和活动 Skill 相互分离。
+2. **知识只服务元治理。** 普通任务不读取模式层；提案引用相关模式 ID，晋级和拒绝结果都保留为证据。
+3. **保留来源的可清理语义。** 不照搬 WikiSkill 永不清理的 Wiki；模式可被取代或归档，但不能静默删除。
+4. **能力包按需声明当前状态。** 能力包可以声明 JSON Schema、初始状态、JSON Merge Patch 和独立审计日志策略；首个 profile 用于 `safe-skill-evolution`。
+5. **提交前验证。** 当前状态和候选补丁都必须通过确定性验证；补丁失败不能改变现有状态；原型污染键直接拒绝。
+6. **历史移出活动上下文，不是销毁。** 运行提示可以只使用当前状态，但不可变审计证据仍用于治理、来源、调试与回滚。
+
+## 调整采纳或暂缓
+
+- 自动轨迹抽样、Wiki Maintainer 自动生成和自治 Skill 提案循环暂缓，直到存在权限受控的真实轨迹与独立验证器。
+- runtime-state profile 是可选且能力包专属的，不存在通用状态 Schema，也不强制删除历史。
+- Pi 与 Codex 适配器尚未通过该状态循环执行真实长任务。本版本只认证 Schema、补丁和组合机制，不宣称复现论文的 token 或准确率收益。
+- WikiSkill 指出严格门禁的局限，但铺垫型中性修改仍需分阶段证据，不能自动放行。
+- 多 Agent 合并、约束解码、语义状态验证、状态遥测和长任务认证继续暂缓。
+
+## 明确不采纳
+
+- 用任一论文的本体替换现有四层架构。
+- 让普通任务 Agent 直接访问 Evolution Knowledge。
+- 自动晋级生成的 Skill，或只凭一个验证总分上线。
+- 把模型专用 workaround 当作通用可迁移程序。
+- 对解释、调试、合规或来源任务丢弃审计历史。
+
+## 置信度与停止条件
+
+两种机制分别落在既有层级的判断置信度高，因为它直接对应论文系统边界和仓库现有契约。它们能提升 SkillPack One 真实运行的置信度为中等：目前还没有 Pi 模型提供商的真实长任务 Skill Lift。研究在阅读全文、核对主要架构图、结果表、消融、提示词、附录和局限后停止；继续收集二手评论不太可能改变当前工程取舍。

package/docs/zh-CN/runtime-state.md

@@ -0,0 +1,31 @@
+# 能力包运行状态
+
+运行状态是长任务能力包的可选执行契约。它本身不会改变 Skill 发现、Atom 边界或 Agent Harness。
+
+一个 profile 声明：
+
+- 能力包专属 JSON Schema；
+- 通过 Schema 校验的初始状态；
+- 确定性的 JSON Merge Patch 语义；
+- `external-audit-log`：活动上下文可以只使用当前状态，但完整运行证据要在外部独立保留。
+
+`skillpack compose` 会随能力包计划返回 profile。state CLI 可以初始化、验证或应用补丁，但不会写入活动运行：
+
+```sh
+npm run skillpack -- state init safe-skill-evolution
+npm run skillpack -- state validate safe-skill-evolution current.json
+npm run skillpack -- state apply safe-skill-evolution current.json patch.json
+```
+
+返回候选前，当前状态和候选状态都必须通过验证。JSON Merge Patch 保留未声明字段，以 `null` 删除字段，整体替换数组，并拒绝原型污染键。失败补丁不会提交部分状态。
+
+## 适用边界
+
+只有当未来决策可以安全依赖一个有界、可审查的充分状态时，才使用 runtime-state profile。以下情况不能把它作为唯一上下文：
+
+- 相关 Schema 需要在运行中动态发现；
+- 某个早期观察可能在当时无法判断其未来价值；
+- 用户要的产物就是历史轨迹，例如审计、调试、来源或解释；
+- 多 Agent 并发写入尚无明确合并语义。
+
+目前它是可移植契约和确定性验证器。Pi 与 Codex 适配器尚未执行端到端状态循环，因此本版本不宣称真实准确率、延迟或 token 节省。