@netpilot/skills 0.3.2 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "netpilot-skills",
       "source": "./",
       "description": "中文工程协作 skills 与可组合工作流",
-      "version": "0.3.2",
+      "version": "0.4.0",
       "author": {
         "name": "NetPilot"
       },

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "netpilot-skills",
   "displayName": "NetPilot Skills",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "面向 Claude Code 的中文工程协作 skills 与可组合工作流",
   "author": {
     "name": "NetPilot"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "netpilot-skills",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "面向 Codex 的中文工程协作 skills 与可组合工作流",
   "author": {
     "name": "NetPilot"

package/AGENTS.md

@@ -6,27 +6,37 @@
 
 - 默认使用中文沟通、中文正文和中文 description；`display_name` 使用由 canonical skill name 派生的英文标题，`short_description` 与 `default_prompt` 使用中文。
 - skill 目录、frontmatter `name`、代码标识符、命令与技术字段使用英文。
+- 普通过程标题和说明使用中文。对行为有锚定作用的 leading word、领域词、协议字段、label 和代码术语保留英文，并在首次出现时用中文解释；不得让普通导航标题无理由保持全英文。
 - 同一职责只保留一个主名称；触发与产物重叠时优先合并。
 - `ask` 是唯一工作流路由入口；不得新增 `clarify`、`ask-*` 等同义入口。
-- `grill` 是可由用户或路由器启动的访谈入口，`grilling` 是可复用访谈引擎，两者不得复制同一套流程。
+- `grill-me` 是 stateless、只读且不创建任何本地或远程 artifact 的显式访谈入口；需要文档时显式改用 `grill-with-docs`。`grilling` 是模型可调用的复用访谈引擎；三者不得复制同一套流程。
 
 ## Skill 编写
 
 - 修改 skill 前读取 `skills/writing-great-skills/SKILL.md`。
-- 每个 `SKILL.md` 必须包含清楚的触发条件、不适用边界、完成标准和反模式。
+- 每个 `SKILL.md` 的 description 必须说明触发范围和关键边界。Skill 真正包含顺序 steps 时，每一步在原位置结束于可检查的 completion criterion；reference-only skill 不为此伪造步骤。不得强制追加全局“完成标准”或“反模式”模板，反模式只在它提供上游方法本身的诊断价值时保留。
 - 新 skill 使用 kebab-case，并通过官方 skill 脚手架创建。
 - 每个 skill 必须提供 `agents/openai.yaml`；`default_prompt` 显式提到 `$skill-name`。
 - `display_name` 必须与目录名和 frontmatter `name` 一一对应，例如 `code-review` 显示为 `Code Review`、`tdd` 显示为 `TDD`；不得另造中文别名。
-- 当前采用跨宿主单源策略，所有 skill 的 `policy.allow_implicit_invocation` 保持 `true`，通过正文中的权限门禁限制动作。若未来确实需要宿主级禁用隐式调用，必须先建立可验证的宿主专用生成层，不能只修改 Codex metadata。
+- 当前采用跨宿主成对标记：只能由用户启动的 skill 在 Claude frontmatter 设置 `disable-model-invocation: true`，并在 Codex metadata 设置 `policy.allow_implicit_invocation: false`；模型可调用的 skill 省略前者并将后者设为 `true`。校验器必须阻止两端分类不一致。
+- 仓库保存完整的双宿主单源；同步到 Codex 时必须生成确定性投影，移除 `argument-hint`、`disable-model-invocation` 等 Claude-only frontmatter，并保留 `agents/openai.yaml` 中对应的 Codex 行为。官方 skill validator 应验证临时安装后的 Codex 投影，而不是原始双宿主源。
+- user-invoked skill 只能由用户显式调用；其他 skill 可以推荐它，但不能把路由或上游调用自动视为授权。model-invoked skill 可以按正文中声明的调用关系启动。
 - skill 调用另一 skill 时，说明触发条件、宿主调用形式和返回关系，禁止循环依赖。
 - 只加入实际需要的 `scripts/`、`references/` 或 `assets/`，不要建立空目录。
 
 ## 上游吸收
 
-- 可以吸收优秀方法，但必须重新表达并适配本项目的语言、权限和工具边界。
-- 不建立 upstream registry、adoption map 或逐 skill 吸收台账。
+- 吸收上游时采用“保留优先”而不是“摘要优先”：默认认为上游的限定词、判断规则、失败边界、示例和重复强调都可能改变 agent 行为。以语义、步骤顺序、leading words、completion criteria 原位置、示例作用和 progressive disclosure 结构的忠实度为首要目标；不能仅因本地总结更整齐或更短就替换上游方法。
+- 合并或删除上游语句前必须证明它属于允许适配、真正重复或经前向测试确认的 no-op；不得把 `where possible`、`each claim`、`before`/`after`、`only` 等限定词概括成更宽松或更严格的规则。无法证明时保留并翻译。
+- 上游的具体例子只在个人化、失效或与真实宿主冲突时替换；替换后仍须保留例子原本承担的诊断、反例或选择功能。不能用抽象总结代替会帮助 agent 区分相邻分支的例子。
+- 允许的适配限于：去除个人角色与作者口吻、移除不存在的 setup/命令、中文化普通说明、映射真实宿主工具与路径、加入必要权限门禁，以及修复有测试或明确证据支持的矛盾。
+- 不统一扩写短 orchestration skill，不给 reference-first skill 强加流程，不把每个 skill 改成同一套章节。若新增内容与项目通用规则重复，应保留在 `AGENTS.md` 而不是复制进所有 skill。
+- 上游 skill 自带的 `references/`、Markdown 资料和可移植脚本默认保留；若原 skill 因个人化 setup 被移除，把仍有方法价值的资料迁移到职责最接近的现有 skill，并更新 context pointer。
+- 不建立需要长期人工维护的 upstream registry、adoption map 或逐 skill 吸收台账；但测试必须固定本地运行时不可丢失的行为契约和附件。
 - 复制或实质改编受许可证约束的内容时，只在 `THIRD_PARTY_NOTICES.md` 保留必要声明。
-- 不引入个人化角色、作者口吻、默认 commit/push、未经授权的远程 issue 写入或其他扩大权限的行为。
+- 不引入个人化角色、作者口吻或不存在的 setup/命令。
+- 显式调用且仓库、branch、tracker item 与目标状态唯一时，相关 skill 可以按正文执行本地 branch/commit，以及 issue、comment、label、assignment、status 和 close 等 tracker 动作；目标不明时必须预览并询问。
+- 上述授权永不隐式扩展到 push、PR、merge、deploy、publish 或相邻任务；这些动作必须由用户单独明确授权。
 
 ## Codex Agent 编写
 
@@ -35,17 +45,23 @@
 - agent 保持窄职责和固定返回契约，只保存角色、推理强度与 sandbox；完整前后端规范继续由项目 `AGENTS.md` 和 standards 提供。
 - 分发 agent 默认不固定 `model`，继承当前会话实际可用模型；用户或项目层可以在确认账号能力后覆盖。代码探索使用低推理只读配置；复杂审查和架构判断根据风险提高推理强度，不能只按“读/写”机械分档。
 - reviewer 默认 `read-only`。需要运行测试而写缓存的 verifier 可以使用 `workspace-write`，但正文必须禁止修改受版本控制文件、安装依赖和更新快照。
-- 用户级 agent 只由 CLI 显式组件安装；项目级 `.codex/agents/` 仍由独立 harness 或项目初始化工具负责。
+- 用户级 agent 由 `@netpilot/skills` 的用户安装流程管理，常规安装默认包含；`--component system-agents` 只用于局部安装。项目级 `.codex/agents/` 仍由独立 harness 或项目初始化工具负责。
 - skill 引用 custom agent 时使用 `` `agent:<name>` ``，仓库校验必须阻止不存在的 agent 引用。
 
 ## 同步与安全
 
 - `npm run sync` 默认必须是 dry-run；只有显式 `--apply` 才能写入用户目录。
-- 默认组件只有 skills；只有显式 `--component agents` 或 `--component all` 才能写入 `~/.codex/agents`。
+- `npx @netpilot/skills` 与 CLI `install` 默认直接执行用户级安装：默认 host 为 Codex，默认 components 为 skills + agents；`preview` 或 `--dry-run` 才只展示计划。只有显式 `--host claude` 或 `--host all` 才安装 Claude Code Skills。底层 `npm run sync` 仍保持 Codex-only dry-run 默认。npm 在包选择发生前可能复用项目已有本地版本，因此文档必须同时给出强制远程 `latest` 的 `npx @netpilot/skills@latest`，不能把无版本命令错误描述成任何环境下都保证 latest。
+- `--local` 把 Codex skills 安装到当前项目，`--project PATH` 安装到指定项目；Codex 使用项目的 `.agents/skills`。只有显式 `--host claude` 或 `--host all` 才写入 `.claude/skills`。项目范围不安装 agents，项目 `.codex/agents` 仍由独立 harness 或项目工具管理。
 - 同步只覆盖 manifest 记录且自上次同步后未被用户修改的文件。
+- manifest key 必须采用 canonical 形式并唯一映射到目标文件；非规范 key 或目标碰撞必须整批冲突，不能进入 stale removal。
+- 源中已经删除或改名的受管理文件，仅在安装副本仍与 manifest hash 一致时移除；删除前先在同卷事务目录中原子隔离并复核 hash，再安全清理空的受管理子目录。用户修改过的旧文件必须作为冲突保留。
 - 未受管理的同名文件必须报冲突并整批停止，不得提供隐式强制覆盖。
+- apply 模式的同步锁必须覆盖 source discovery、manifest 读取、规划和提交；owner 已退出的 stale lock 只能经内容比对后回收，存活 owner 或无法验证的锁不得删除。
+- create、update、remove、manifest 发布及 rollback 都必须使用逐目标 compare-and-swap：最终提交不得覆盖刚出现的文件，回滚不得删除或覆盖事务期间变化的内容；父目录在每次提交前重新检查。
+- 事务 staging 与目标必须位于同一文件系统；合法但跨设备的 mount 必须在写入前给出稳定冲突，不能退化为可覆盖复制或非原子回滚。
 - 测试必须使用临时 home，禁止触碰真实 `~/.agents`、`~/.claude` 或宿主配置。
-- 本仓库不默认安装插件、不修改宿主 settings，也不执行 commit、push、发布或远程写入。
+- 安装器不默认安装插件、不修改宿主 settings，也不替用户执行项目 commit、push、发布或远程写入；skill 运行时的受控动作只以对应 skill 正文为准。
 
 ## 交付门禁
 

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 本文件记录用户可观察的版本变化。版本遵循 SemVer；`0.x` 阶段仍可能包含明确说明的兼容性调整。
 
+## Unreleased
+
+## 0.4.0
+
+- 将工程与生产力方法扩展为 21 个去个人化 skills，按上游原有结构恢复完整工作流、步骤内门禁、方法自身的反模式，以及有实际价值的 `references/` 和跨平台脚本；不再为每个 skill 强加统一尾部章节。
+- 将无文档访谈入口从 `grill` 更名为 canonical `grill-me`，并新增 `improve-codebase-architecture`、`triage` 与 `resolving-merge-conflicts`。
+- 为 Claude Code 与 Codex 建立成对的 user-invoked / model-invoked metadata，并由校验器阻止两端分类漂移和失效的相对文档链接。
+- Codex 同步改为生成确定性的宿主投影：保留双宿主源中的 Claude-only frontmatter，但不再把这些字段写入 Codex skill 安装目录。
+- 显式调用且目标唯一时，相关 workflows 可按正文执行本地 branch/commit 和受控 tracker 写入；push、PR、merge、deploy 与 publish 仍需单独授权。
+- `npx @netpilot/skills` 现在零参数直接安装 Codex 用户 Skills 与 Agents；只有 Claude Code 或双宿主安装才需要显式 `--host claude|all`。`npx @netpilot/skills@latest` 可绕过本地依赖匹配并保证使用 npm `latest`；`--dry-run` 用于预览，底层 `npm run sync` 仍保持 Codex-only dry-run 默认。
+- 新增等价的 `preview` 预览命令；`--local` 与 `--project PATH` 默认只把 Codex Skills 安装到项目范围，显式 `--host all` 时才同步双宿主 Skills，项目 Agent 继续由 Harness 管理。
+- 删除与 Codex 内置 `explorer` 重叠且没有真实调用方的 `code-reader`；reviewer 统一 P0–P3 证据契约，`test-verifier` 增加执行前后工作树完整性证据。
+- apply 锁现在覆盖 source discovery、manifest 读取、规划与提交；owner 已退出的 stale lock 经内容比对后自动回收，存活 owner 或无法验证的锁保持不动。
+- create、update、remove、manifest 发布与 rollback 都采用逐目标 compare-and-swap：旧文件先原子隔离并复核 hash，新文件以无覆盖 hard link 发布，事务期间出现或变化的用户内容不会被覆盖或删除；父目录在每次提交前重新检查，源中已删除或改名的受管理文件仍会安全清理。
+- 同步锁记录先写入完整临时文件再以 hard link 原子发布，避免进程中断留下空锁；若目标目录是 home 内合法但不同设备的 mount，会在写入前给出稳定冲突，而不是降级为非原子复制。
+- 非规范 manifest key、目标碰撞、home 根 symlink/junction 和用户修改过的旧文件继续作为冲突保留；参数错误只输出稳定消息，不泄露 Node 堆栈。
+- 增加 21-skill 集合、附属资料、双宿主调用分类、HITL 脚本和安装包完整性的回归验证。
+- 上游本地化改为 conservation-first：保留会改变执行行为的限定词、失败边界和诊断例子，并以契约测试阻止 `where possible`、`each claim`、提前 handoff、stateless 访谈等语义再次被摘要弱化。
+- 补齐 `wayfinder → prototype` 的窄授权链：明确 prototype ticket 可以生成并提交 throwaway artifact，但仍需另行授权 `implement` 才能写入正式代码。
+- 用零配置发现与可选项目级文档替代个人化 setup：优先读取项目规则和兼容配置，其次从唯一 Git remote 推断 GitHub/GitLab，再回退 Local Markdown；自定义 labels 和 PR/MR request surface 不再通过修改已安装 Skill 保存。
+
 ## 0.3.2
 
 - 首次发布公开 npm 包 `@netpilot/skills`，README 默认使用 npm `latest`，团队和 CI 可固定完整版本。

package/README.md

@@ -1,151 +1,117 @@
 # NetPilot Skills
 
-一套以中文为主、面向 Codex 并兼容 Claude Code 的工程协作 skills，以及少量可选的 Codex custom agents。本仓库只管理跨项目工作流和用户级角色；项目规则、文档骨架与技术栈组合由 [NetPilot Harness](https://github.com/netpilot-z/harness) 管理。
+面向 Codex、兼容 Claude Code 的中文工程协作 Skills，并附带少量 Codex custom agents。内容覆盖需求澄清、研究、设计、实现、测试、审查、分诊和交接。
 
-## 安装
+## 快速安装
 
-前提：Node.js 版本满足 [`package.json`](package.json) 中的 `engines`。CLI 默认 dry-run，未加 `--apply` 时不会写入用户目录。
-
-预览安装计划：
+要求 Node.js 满足 [`package.json`](package.json) 的 `engines`。推荐直接安装 npm 已发布的 `latest`：
 
 ```shell
-npx --yes @netpilot/skills install
+npx @netpilot/skills@latest
 ```
 
-安装 Codex Skills，或同时安装可选 Agents：
+也可以使用短命令：
 
 ```shell
-npx --yes @netpilot/skills install --host codex --apply
-npx --yes @netpilot/skills install --host codex --component all --apply
+npx @netpilot/skills
 ```
 
-Claude Code 使用 `--host claude`。默认只安装 Skills；Codex Agents 不会进入 Claude Code。
+默认一次性安装当前用户的 Codex Skills（`~/.agents/skills`）和 Codex 用户 Agents（`~/.codex/agents`），不会安装 Claude Code Skills，也不需要额外传入 `--host codex`、`--component all` 或 `--apply`。
+
+`npx` 可能优先匹配当前项目中的同名本地依赖；需要保证选择 npm `latest` 时使用带 `@latest` 的命令。团队或 CI 需要可复现安装时，应固定完整 SemVer。
+
+常用高级选项：
 
 ```shell
-npx --yes @netpilot/skills doctor
-npx --yes @netpilot/skills validate
+npx @netpilot/skills preview                 # 只预览
+npx @netpilot/skills --dry-run               # 只预览
+npx @netpilot/skills --host claude           # 只安装 Claude Code Skills
+npx @netpilot/skills --host all              # 同时安装 Claude Code Skills
+npx @netpilot/skills --component skills      # 只安装 Skills
+npx @netpilot/skills --component system-agents
+npx @netpilot/skills --local                 # 安装到当前项目
+npx @netpilot/skills --project PATH          # 安装到指定项目
+npx @netpilot/skills doctor
+npx @netpilot/skills validate
 ```
 
-省略版本时使用 npm 的 `latest`。团队或 CI 需要可复现安装时，可在包名后追加经过验证的完整 SemVer。
-
 频繁使用时可以全局安装：
 
 ```shell
 npm install --global @netpilot/skills
-netpilot-skills doctor
-netpilot-skills install --host codex --component all --apply
+netpilot-skills
 ```
 
-## 推荐的初始工作流
+安装器不会覆盖未受管理或用户修改过的同名文件；发生冲突时整批停止。项目范围只安装 Skills，项目级 Agents 仍由 [NetPilot Harness](https://github.com/netpilot-z/harness) 管理。
 
-Skills 是可组合工具，不是固定瀑布流程。入口不确定时使用 `ask`；主 skill 已经明确时直接调用它。
+## 核心用法
 
-首次进入陌生项目，可先让 agent 只读建立最小上下文：
-
-```text
-请使用 $ask，只读检查项目规则、README、与当前任务相关的入口、测试和工作树状态，
-不要修改文件；然后为当前任务选择最短且合适的 workflow。
-```
+Codex 使用 `$skill-name`；Claude Code 用户级安装使用 `/skill-name`。入口不确定时从 `ask` 开始，主 Skill 已明确时直接调用。
 
 | 场景 | 推荐链路 |
 | --- | --- |
-| 跨会话学习 | `teach → 按需 research / grilling → 下一节课` |
-| 模糊方向 | `ask → wayfinder → research / prototype → grill → to-spec` |
-| 重要新功能 | `grill-with-docs → to-spec → to-tickets → tdd / implement → code-review` |
-| 明确的小改动 | `implement → 定向验证` |
+| 模糊方向 | `ask → wayfinder → research / prototype → grill-me → to-spec` |
+| 重要新功能 | `grill-with-docs → to-spec → to-tickets → implement → code-review` |
+| 明确小改动 | `implement → 定向验证` |
 | Bug 根因未知 | `diagnosing-bugs → tdd → code-review` |
-| 跨会话交付 | `to-spec → to-tickets → 分切片实现与审查 → handoff` |
+| 跨会话学习 | `teach → 按需 research / grilling → 下一节课` |
+| 跨会话交付 | `to-spec → to-tickets → implement → handoff` |
 
-`grill-with-docs` 仅在需要边访谈边维护 `CONTEXT.md`、领域术语或 ADR 时使用；不写项目文档时改用 `grill`。
+`grill-me` 是 stateless、只读且不创建本地或远程 artifact 的访谈入口；需要同步维护领域文档或 ADR 时使用 `grill-with-docs`。
 
-## Skill 体系
+显式调用且目标唯一时，相关 Skills 可以按正文创建本地 branch/commit，或操作明确的 issue、label、assignment 和状态。push、PR、merge、deploy、npm publish 等动作始终需要单独授权。
 
-Codex 使用 `$skill-name`；Claude Code 用户级同步使用 `/skill-name`；Claude Code 插件模式使用 `/netpilot-skills:skill-name`。canonical name 和 UI 标题保持英文，说明与默认提示使用中文。
+## Skill 体系
 
-| 阶段 | Skill | 作用与适用时机 | 主要产物 |
+| 阶段 | Skill | 适用时机 | 主要产物 |
 | --- | --- | --- | --- |
-| 路由 | `ask` | 入口不确定或关键边界缺失时选择主 skill | 主 skill、已确认边界与下一步 |
-| 学习 | `teach` | 在专用目录中跨会话学习一个主题 | Mission、资料、课程、术语与学习记录 |
-| 深入确认 | `grill` | 对计划或关键决策进行只读逐题深访 | 事实、决策、假设与未决问题 |
-| 深入确认 | `grill-with-docs` | 访谈时同步维护领域文档和 ADR | 更新后的领域文档与决策记录 |
-| 深入确认 | `grilling` | 供其他 skill 复用的一次一题访谈引擎 | 可继续执行的共识 |
-| 探索 | `wayfinder` | 把巨大或模糊想法收敛成可验证路线 | 候选路径、实验与路线图 |
-| 探索 | `research` | 用一手资料核验陌生或快速变化的事实 | 来源、事实、比较与建议 |
-| 探索 | `prototype` | 用最小可运行实验验证关键假设 | 实验、证据与继续/停止结论 |
-| 设计 | `domain-modeling` | 统一术语、状态、关系和业务不变量 | 术语表、模型与必要 ADR |
-| 设计 | `codebase-design` | 设计模块职责、接口、依赖和测试接缝 | 模块边界与测试策略 |
-| 交付 | `to-spec` | 将已明确结论整理成可实现规格 | 范围、规则与验收标准 |
-| 交付 | `to-tickets` | 将规格拆成可独立验证的垂直任务 | 任务、依赖与验证要求 |
-| 交付 | `implement` | 在已批准边界内实施明确任务 | 范围内改动与验证证据 |
-| 质量 | `tdd` | 用 RED/GREEN/REFACTOR 保护行为变更 | 测试证据与实现 |
-| 质量 | `diagnosing-bugs` | 系统定位尚未证实的根因 | 最小复现、根因与回归建议 |
-| 质量 | `code-review` | 审查正确性、风险、测试和架构边界 | 按严重度排列的 findings |
-| 连续性 | `handoff` | 为跨会话、agent 或人员交接建立恢复点 | 状态、证据、决策与下一步 |
-| 维护 | `writing-great-skills` | 创建、改写、本地化或测试 skill | 可验证的 skill |
-
-`ask` 始终只有一个。`grill` 是默认访谈入口，`grill-with-docs` 负责同步项目文档，`grilling` 是内部访谈引擎。
-
-## Teach：跨会话学习工作区
-
-`teach` 用于围绕明确目标持续学习，并通过短课程、主动练习、反馈和复习保存可靠进度。它不是 `research` 或工程实施的别名：一次性事实问题使用 `research`，需要修改项目则进入工程工作流。
-
-| 教学资产 | 作用 |
-| --- | --- |
-| `MISSION.md` | 学习目标、成功标准、约束和非目标 |
-| `RESOURCES.md` | 经筛选并带用途说明的可信资料 |
-| `GLOSSARY.md` | 已经理解并能正确使用的术语 |
-| `lessons/` | 每次一个目标的短课程与练习 |
-| `learning-records/` | 有练习证据支持的掌握记录 |
-| `NOTES.md` | 稳定教学偏好和必要工作笔记 |
-
-开始时可直接说：
-
-```text
-请使用 $teach，在我指定的独立学习目录中建立学习项目。
-先确认可观察的成功标准并做简短基础诊断，再安排第一节最小课程。
-```
-
-`teach` 只维护用户确认的教学目录，不修改业务代码、项目配置、Git 状态或远程资源。
-
-## Codex Subagents（可选）
-
-完整规则保存在项目 `AGENTS.md` 和 standards 中；skill 保存跨宿主工作流；custom agent 只定义窄职责、推理强度、sandbox 和返回格式。模型默认继承当前 Codex 会话，避免绑定特定账号能力。
-
-| Agent type | 作用 | Model | Reasoning | Sandbox |
-| --- | --- | --- | --- | --- |
-| `code-reader` | 快速只读定位职责、调用链、配置和测试 | 继承会话 | `low` | `read-only` |
-| `frontend-reviewer` | 审查前端状态、交互、可访问性和测试风险 | 继承会话 | `high` | `read-only` |
-| `backend-reviewer` | 审查接口、权限、事务、幂等和数据一致性 | 继承会话 | `high` | `read-only` |
-| `architecture-designer` | 比较模块边界、依赖、数据流和迁移路径 | 继承会话 | `high` | `read-only` |
-| `test-verifier` | 执行测试、类型检查、lint 和构建并压缩证据 | 继承会话 | `medium` | `workspace-write` |
-
-配置位于 `agents/codex/*.toml`。完整边界见 [`docs/agent-authoring.md`](docs/agent-authoring.md)。
-
-## 从源码或插件使用
-
-从源码同步默认只展示计划：
-
-```shell
-npm run sync
-npm run sync -- --apply
-npm run sync -- --host codex --component all --apply
-```
-
-同步器只更新由本项目管理且用户未修改的文件；冲突会在写入前整批停止，不提供 `--force`。写入前会拒绝 symlink/junction 目标；异常中断时保留 staging 证据，不承诺断电级事务。状态保存在 `~/.netpilot-skills/manifest.json`。
-
-仓库也包含 Codex 与 Claude Code plugin manifest。不要同时安装插件副本和普通用户级 Skills，以免出现重复名称。Claude Code 本地验证：
-
-```shell
-claude plugin validate ./.claude-plugin/plugin.json --strict
-claude plugin validate ./.claude-plugin/marketplace.json --strict
-claude --plugin-dir .
-```
-
-## 开发与验证
+| 路由 | `ask` | 入口或关键边界不清楚 | 主 Skill 与已确认边界 |
+| 学习 | `teach` | 建立跨会话学习项目 | 课程、资料与学习记录 |
+| 访谈 | `grill-me` | 深入盘问但不写文档 | 当前对话中的共识 |
+| 访谈 | `grill-with-docs` | 访谈时同步沉淀文档 | 领域文档与 ADR |
+| 访谈 | `grilling` | 供其他 Skills 复用访谈 | 已确认决定与未决分支 |
+| 探索 | `wayfinder` | 大型工作仍处于 fog of war | Decision map 与 frontier |
+| 探索 | `research` | 核验陌生或变化中的事实 | 带一手引用的研究文档 |
+| 探索 | `prototype` | 用低成本实验验证假设 | Throwaway artifact 与 verdict |
+| 设计 | `domain-modeling` | 统一术语、状态和不变量 | Glossary、模型与必要 ADR |
+| 设计 | `codebase-design` | 判断 Module、Interface 和 Seam | 设计词汇与接口比较 |
+| 设计 | `improve-codebase-architecture` | 扫描架构摩擦和 deepening 机会 | HTML 报告与候选项 |
+| 交付 | `to-spec` | 把已确认结论整理为规格 | Spec issue 与验收标准 |
+| 交付 | `to-tickets` | 把规格拆成垂直任务 | Tickets、blocking 与 frontier |
+| 交付 | `implement` | 按明确规格实际实施 | 代码、验证与受控 commit |
+| 质量 | `tdd` | 可观察行为需要 RED/GREEN | 测试与最小实现 |
+| 质量 | `diagnosing-bugs` | 真实根因尚不明确 | 最小复现、根因与证据 |
+| 质量 | `code-review` | 审查 diff、commit 或 PR | Standards + Spec findings |
+| 质量 | `resolving-merge-conflicts` | 解决 merge/rebase 冲突 | 已验证的冲突解决结果 |
+| 维护 | `triage` | 推进 issue 或外部 PR | 标签、brief、评论或关闭结果 |
+| 连续性 | `handoff` | 跨会话或人员交接 | 可恢复的状态与下一步 |
+| 维护 | `writing-great-skills` | 创建、本地化或审查 Skill | 可验证的 Skill |
+
+## Codex Agents
+
+| Agent | 用途 | 默认配置 |
+| --- | --- | --- |
+| `frontend-reviewer` | 前端状态、交互、可访问性和测试审查 | high / read-only |
+| `backend-reviewer` | 接口、权限、事务和数据一致性审查 | high / read-only |
+| `architecture-designer` | 模块边界、依赖和迁移方案比较 | high / read-only |
+| `test-verifier` | 执行测试、类型检查、lint 和构建 | medium / workspace-write |
+
+Agents 默认继承当前 Codex 会话模型。代码定位直接使用 Codex 内置 `explorer`；详细配置见 [`docs/agent-authoring.md`](docs/agent-authoring.md)。
+
+## 项目配置与安全
+
+- Tracker 默认从项目规则和唯一 Git remote 自动发现；自定义配置见 [`skills/triage/references/project-config.md`](skills/triage/references/project-config.md)。
+- 双宿主调用 metadata 由仓库校验器保持一致；调用分类不等于写入权限。
+- 同步器只更新本项目管理且用户未修改的文件，不提供隐式强制覆盖。
+- 上游方法采用 conservation-first 本地化：保留限定词、步骤顺序、失败边界、诊断例子和有方法价值的附件，只移除个人化表达、不存在的命令，并适配真实宿主权限。
+
+## 开发
 
 ```shell
 npm run verify
 npm run doctor
+npm run sync                    # dry-run
+npm run sync -- --apply         # 写入用户目录
 ```
 
-项目规范见 [AGENTS.md](./AGENTS.md)，版本变化见 [CHANGELOG.md](./CHANGELOG.md)，第三方声明见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。本项目使用 MIT License；上游内容经过中文化、去个人化和权限收敛，不全量复制上游仓库。
+项目规范见 [AGENTS.md](AGENTS.md)，版本变化见 [CHANGELOG.md](CHANGELOG.md)，安全政策见 [SECURITY.md](SECURITY.md)，第三方声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # 第三方声明
 
-本仓库的部分工作流结构与方法由 [mattpocock/skills](https://github.com/mattpocock/skills) 翻译、蒸馏并重新适配。本地版本去除了个人化角色，改写为中文，并增加了权限、安全、验证与双宿主约束。
+本仓库的部分工作流结构、方法与附属资料源自 [mattpocock/skills](https://github.com/mattpocock/skills)。本地版本以保留原有语义、步骤顺序、leading words、示例作用和 progressive-disclosure 关系为目标，在此基础上完成中文化、去个人化、宿主映射与必要的权限和安全适配。
 
 无需维护逐 skill 的来源表或吸收记录；本文件仅保留许可证要求所需的最小声明。
 

package/agents/codex/architecture-designer.toml

@@ -7,5 +7,6 @@ developer_instructions = """
 明确目标、质量属性和不可改变的边界，再画出现状模块、依赖、数据流、失败面和测试接缝。
 提出最少数量的可行方案，用一致维度比较复杂度、耦合、演进性、迁移成本、可逆性和风险，并给出推荐及反对理由。
 不要修改代码或文档，不要创建 ADR，不要为了未来可能性提前抽象，也不要脱离仓库证据设计理想化系统。
-向主 agent 返回现状证据、候选方案、推荐边界、迁移切片、需要用户决定的取舍和验证方式。
+返回固定结果：status 只能是 completed 或 blocked，并包含 current_state、options、recommendation、migration_slices、validation、decisions 和 unknowns。
+current_state 和每个 option 必须带可定位仓库证据；关键上下文不足以比较方案时返回 blocked，不能用理想化假设补齐。
 """

package/agents/codex/backend-reviewer.toml

@@ -7,5 +7,7 @@ developer_instructions = """
 先读取适用的 AGENTS.md、规格、后端标准、接口契约、数据模型和完整 diff，再追踪必要的调用方、迁移与测试。
 重点检查输入验证、认证授权、租户隔离、事务边界、并发与竞态、幂等、错误语义、重试、资源释放、日志与指标以及回归测试。
 不要修改文件，不要执行生产或数据写入，不要把缺少个人偏好的抽象当成问题。
-每个 finding 返回严重度、文件与行、可复现路径、影响和最小修复方向；明确区分已证实问题、未知项和建议验证。
+返回固定结果：status 只能是 completed 或 blocked；finding priority 只能是 P0、P1、P2 或 P3。
+每个 finding 返回 file 与 line、trigger、impact、evidence 和 minimal fix，并明确区分已证实问题、未知项和建议验证。
+没有可执行问题时显式返回 no findings；最后列出 unknowns 与未执行验证，不用建议代替证据。
 """

package/agents/codex/frontend-reviewer.toml

@@ -7,5 +7,7 @@ developer_instructions = """
 先读取适用的 AGENTS.md、规格、前端标准、设计系统约束和完整 diff，再检查必要的调用方与测试。
 重点检查行为正确性、状态同步、竞态与取消、错误和加载状态、键盘与屏幕阅读器可用性、组件职责、渲染成本以及测试缺口。
 不要修改文件，不要安装依赖，不要把纯风格偏好或无法证明影响的猜测列为 finding。
-每个 finding 返回严重度、文件与行、触发条件、实际影响和最小修复方向；最后列出未决问题与未执行验证。
+返回固定结果：status 只能是 completed 或 blocked；finding priority 只能是 P0、P1、P2 或 P3。
+每个 finding 返回 file 与 line、trigger、impact、evidence 和 minimal fix，并明确区分已证实问题与推断。
+没有可执行问题时显式返回 no findings；最后列出 unknowns 与未执行验证，不用建议代替证据。
 """

package/agents/codex/test-verifier.toml

@@ -4,8 +4,11 @@ model_reasoning_effort = "medium"
 sandbox_mode = "workspace-write"
 developer_instructions = """
 先读取适用的 AGENTS.md、package scripts、测试说明和主 agent 给出的变更范围，选择最小充分的现有验证命令。
+执行前后运行 `git status --short` 或项目认可的等价检查，记录基线和新增变化；不得清理、回滚或隐藏用户已有改动。
 可以运行会产生正常缓存、coverage 或临时构建产物的测试工具，但不得修改受版本控制的源码、测试、配置或快照。
 不要安装或升级依赖，不要删除文件，不要弱化断言，不要用跳过检查换取绿色结果。
 记录实际命令、退出码和关键输出；失败时定位到最可能的阶段并保留原始错误含义，不擅自修复。
-向主 agent 返回已通过、失败、未执行及其原因，并区分由当前变更引起的失败和环境限制。
+固定返回 status、commands、passed_checks、failed_checks、skipped_checks、baseline_worktree、final_worktree、workspace_change 和 environment_limits。
+status 只能是 passed、failed 或 blocked：全部必需检查成功且没有新增受版本控制 diff 才能是 passed；检查发现失败时是 failed；命令、依赖或环境不可用导致必需检查无法执行时是 blocked。
+区分由当前变更引起的失败和环境限制。若验证新增了受版本控制的 diff，结果不得返回 passed，必须保留现场并交给主 agent 判断。
 """

package/bin/netpilot-skills.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const commands = Object.freeze({
   install: "scripts/sync.mjs",
+  preview: "scripts/sync.mjs",
   sync: "scripts/sync.mjs",
   doctor: "scripts/doctor.mjs",
   validate: "scripts/validate.mjs",
@@ -17,13 +18,21 @@ function printHelp() {
   console.log(`NetPilot Skills CLI
 
 用法：
-  netpilot-skills [install] [--host codex|claude|all] [--component skills|agents|all] [--home PATH] [--apply]
+  netpilot-skills [install] [--host codex|claude|all] [--component skills|system-agents|agents|all] [--home PATH] [--dry-run]
+  netpilot-skills preview [--host codex|claude|all] [--component skills|system-agents|agents|all] [--home PATH]
+  netpilot-skills [install|preview] --local [--host codex|claude|all]
+  netpilot-skills [install|preview] --project PATH [--host codex|claude|all]
+  netpilot-skills sync [--host codex|claude|all] [--component skills|system-agents|agents|all] [--home PATH] [--apply]
   netpilot-skills doctor
   netpilot-skills validate
   netpilot-skills --version
 
-install 默认只执行 dry-run。确认计划无冲突后，再追加 --apply。
-默认只安装 skills；Codex agents 必须显式选择 --component agents 或 all。
+install 默认直接写入，默认安装 Codex skills 与 agents；--dry-run 或 preview 仅预览。
+sync 与 npm run sync 保持默认 dry-run，只有显式 --apply 才写入。
+--local 安装到当前项目；--project PATH 安装到指定项目。项目范围默认安装 Codex skills。
+只有安装 Claude Code skills 时才显式传入 --host claude 或 --host all。
+--host、--component 和 --home 用于宿主、组件或自定义用户目录等高级覆盖。
+system-agents 是用户全局 agents 的语义化别名，目标为 ~/.codex/agents。
 省略命令或直接传入安装参数时，等同于 install。`);
 }
 
@@ -32,11 +41,114 @@ function packageVersion() {
   return manifest.version;
 }
 
+function hasOption(arguments_, option) {
+  return arguments_.includes(option);
+}
+
+function assertProjectDirectory(projectDir) {
+  const stats = lstatSync(projectDir, { throwIfNoEntry: false });
+  if (!stats) throw new Error(`项目目录不存在：${projectDir}`);
+  if (!stats.isDirectory() || stats.isSymbolicLink()) {
+    throw new Error(`项目目标必须是普通目录：${projectDir}`);
+  }
+}
+
+function prepareInstallArguments(rawArguments, { preview = false } = {}) {
+  const commandArguments = [];
+  let projectDir = null;
+  let scopeOption = null;
+  let homeSpecified = false;
+  let component = null;
+
+  for (let index = 0; index < rawArguments.length; index += 1) {
+    const argument = rawArguments[index];
+    if (argument === "--local") {
+      if (scopeOption) throw new Error("--local 与 --project 不能同时使用");
+      scopeOption = "--local";
+      projectDir = path.resolve(process.cwd());
+      continue;
+    }
+    if (argument === "--project") {
+      if (scopeOption) throw new Error("--local 与 --project 不能同时使用");
+      const requestedProject = rawArguments[index + 1];
+      if (!requestedProject || requestedProject.startsWith("-")) {
+        throw new Error("--project 需要一个目录路径");
+      }
+      scopeOption = "--project";
+      projectDir = path.resolve(requestedProject);
+      index += 1;
+      continue;
+    }
+    if (argument === "--home") {
+      const requestedHome = rawArguments[index + 1];
+      if (!requestedHome || requestedHome.startsWith("-")) {
+        throw new Error("--home 需要一个目录路径");
+      }
+      homeSpecified = true;
+      commandArguments.push(argument, requestedHome);
+      index += 1;
+      continue;
+    }
+    if (argument === "--host") {
+      const requestedHost = rawArguments[index + 1];
+      if (!requestedHost || requestedHost.startsWith("-")) {
+        throw new Error("--host 需要 codex、claude 或 all");
+      }
+      commandArguments.push(argument, requestedHost);
+      index += 1;
+      continue;
+    }
+    if (argument === "--component") {
+      const requestedComponent = rawArguments[index + 1];
+      if (!requestedComponent || requestedComponent.startsWith("-")) {
+        throw new Error("--component 需要 skills、system-agents、agents 或 all");
+      }
+      component = requestedComponent;
+      commandArguments.push(argument, requestedComponent);
+      index += 1;
+      continue;
+    }
+    commandArguments.push(argument);
+  }
+
+  if (projectDir) {
+    if (homeSpecified) throw new Error("--local/--project 与 --home 不能同时使用");
+    if (component && component !== "skills") {
+      throw new Error("项目范围只支持 --component skills；Codex 项目 agents 由项目工具管理");
+    }
+    assertProjectDirectory(projectDir);
+    commandArguments.push("--home", projectDir);
+    if (!component) commandArguments.push("--component", "skills");
+  }
+
+  if (preview) {
+    if (hasOption(commandArguments, "--apply")) {
+      throw new Error("preview 不能与 --apply 一起使用");
+    }
+    if (!hasOption(commandArguments, "--dry-run")) commandArguments.push("--dry-run");
+  } else if (
+    !hasOption(commandArguments, "--apply") &&
+    !hasOption(commandArguments, "--dry-run")
+  ) {
+    commandArguments.push("--apply");
+  }
+
+  return commandArguments;
+}
+
 function run() {
   const rawArguments = process.argv.slice(2);
   const firstArgument = rawArguments[0];
+  const knownOrImplicitCommand =
+    firstArgument === undefined ||
+    firstArgument.startsWith("-") ||
+    Object.hasOwn(commands, firstArgument);
 
-  if (firstArgument === "--help" || firstArgument === "-h" || firstArgument === "help") {
+  if (
+    firstArgument === "help" ||
+    (knownOrImplicitCommand &&
+      rawArguments.some((argument) => argument === "--help" || argument === "-h"))
+  ) {
     printHelp();
     return;
   }
@@ -47,7 +159,7 @@ function run() {
 
   const implicitInstall = firstArgument === undefined || firstArgument.startsWith("-");
   const command = implicitInstall ? "install" : firstArgument;
-  const commandArguments = implicitInstall ? rawArguments : rawArguments.slice(1);
+  const rawCommandArguments = implicitInstall ? rawArguments : rawArguments.slice(1);
   const script = commands[command];
 
   if (!script) {
@@ -57,6 +169,18 @@ function run() {
     return;
   }
 
+  let commandArguments;
+  try {
+    commandArguments =
+      command === "install" || command === "preview"
+        ? prepareInstallArguments(rawCommandArguments, { preview: command === "preview" })
+        : [...rawCommandArguments];
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+    return;
+  }
+
   const result = spawnSync(process.execPath, [path.join(packageRoot, script), ...commandArguments], {
     stdio: "inherit",
     windowsHide: true,