harveyz-skill 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-06-22
+
+### Added
+- `sync-agent`：Syncthing 多设备同步工具与 skill — REST API 客户端、launchd 安装、CLI（start/stop/status/setup）、运行时管理同步 folder/device、为含 `.gitignore` 的目录自动创建 `.stignore`
+- `hub`：TODO.md → SQLite 同步（启动时同步所有项目，ctrl+r 同步当前项目）；`hub git` CLI 子命令（status/fetch/branches）与 TUI 对等；`hub projects remove` 命令 + TUI ctrl+d 快捷键
+- `scout-philosophy`：skill 设计哲学研究 skill（meta bundle）
+- `extract-url`：代码块支持；付费墙站点 cookie 重试；`HSKILL_EXTRACT_URL_CONFIG` 环境变量覆盖配置路径
+- `learn-video`：新增字幕翻译步骤（translate_subs）
+
+### Changed
+- `learn-skill` → v2.0.0：报告持久化到全局 skill 库、四维度归纳式重构、新增 Step 4 跨 skill 索引摘要
+- `analyze-skill` → `survey-skillrepo`：重命名并移至 research bundle，泛化到任意 skill 仓库并集成 learn-skill
+- `extract-url`：重构为从 `~/.hskill/config.json` 读取配置，各脚本不再依赖位置参数
+- `init-skill`：迁移至 experiment bundle；description 移除中文以符合 F3；支持可切换参考标准用于 A/B 实验
+- `publish-skill`：新增 R4 installScope 检查与修复引导
+- 13 篇设计 spec 迁移为正式文档（hub、sync-agent、opencode、init-skill 等）
+- 修正多个 skill 内容哈希与版本号，并为 10 个 skill 补充 `installScope`
+
+### Fixed
+- `extract-url`：playwright_xcom 图片下载 SSL 验证、脚本路径/setup 顺序/超时/权限等修复
+- `hub`：TUI remove 行为与 CLI 对齐、footer category map、remove 快捷键改为 ctrl+d
+- `sync-agent`：平台感知的 Syncthing 配置路径（macOS/Linux）
+- `learn-skill`：audit findings 修复，移除 reference/script 200 行读取上限
+- 测试：survey-skillrepo fixture 版本同步至 2.0.1，修复 test_config.py 导入与 bats meta-bundle 断言
+
 ## [0.18.0] - 2026-06-16
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Skill manager for Claude Code, Cursor, and Codex",
   "type": "module",
   "bin": {
@@ -34,8 +34,8 @@
     "skills/design/scout-brand/",
     "skills/design/build-style/",
     "skills/design/sync-design/",
-    "skills/meta/init-skill/",
-    "skills/meta/analyze-skill/",
+    "skills/experiment/init-skill/",
+    "skills/research/survey-skillrepo/",
     "skills/meta/clean-git/",
     "skills/meta/archive-skill/",
     "skills/meta/dedup-skill/",
@@ -43,8 +43,10 @@
     "skills/meta/publish-skill/",
     "skills/meta/runby-opencode/",
     "skills/meta/release-project/",
+    "skills/meta/sync-agent/",
     "skills/experiment/probe-session/",
     "skills/experiment/learn-paper/",
+    "skills/meta/scout-philosophy/",
     "tools/hub/",
     "hooks/check-similar-branch/"
   ],

package/skills/{meta → experiment}/init-skill/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: init-skill
-description: "Initialize a new skill from scratch in the harveyz-skill repo — scaffolds SKILL.md, directory structure, and a feature branch from a design spec or free-form notes. Triggers: 'create new skill', 'scaffold a skill', 'init skill', 'bootstrap skill from notes', 'create skill from spec', 'help me start a new skill', 'initialize a skill'."
+description: "Initialize a new skill from scratch in the harveyz-skill repo — scaffolds SKILL.md, directory structure, and a feature branch from a design spec or free-form notes. Applies the condensed skill design standard (16 philosophies + system mechanisms). Triggers: 'create new skill', 'scaffold a skill', 'init skill', 'bootstrap skill from notes', 'create skill from spec', 'help me start a new skill', 'initialize a skill'."
 user_invocable: true
-version: "1.0.1"
+version: "1.2.0"
 ---
 
 # 从设计文档初始化新 Skill
@@ -25,6 +25,12 @@ version: "1.0.1"
 
 ---
 
+## 参考标准
+
+本 skill 使用 `references/skill-standard.md` 作为单一标准——精简版（约 200 行），含 16 条设计哲学 + 系统机制 + 张力点。Step 2 加载该文件并对照检查。
+
+---
+
 ## 执行流程（6 步）
 
 ### Step 0 — 需求澄清
@@ -54,17 +60,17 @@ version: "1.0.1"
    ```
    列出候选文件供用户选择。
 
-### Step 2 — 提炼要素 + 最佳实践检查
+### Step 2 — 提炼要素 + 标准检查
 
-用 Read 工具读取 `references/skill-authoring-guide.md`，然后从设计文档中提取以下字段，以表格 + 建议形式展示给用户：
+**2a. 加载标准：** 用 Read 工具读取 `references/skill-standard.md`（精简版，约 200 行）。
 
-**提炼结果：**
+**2b. 提炼要素：** 从设计文档中提取以下字段：
 
 | 字段 | 提取值 | 规范约束 |
 |------|--------|---------|
-| `name` | `<verb>-<noun>` 格式 | 动词必须在规范词表中 |
+| `name` | `<verb>-<noun>` 格式 | 动词必须在标准词表中 |
 | `bundle` | 从现有 bundleMeta 中选 | 可新建 |
-| `description` | 英文，含触发短语 | ≥ 10 字符，不含中文 |
+| `description` | 英文，含触发短语 | ≥ 10 字符，仅英文 |
 | 正文大纲 | 中文，核心步骤列表 | — |
 | `category` 目录 | 对应 bundle 的目录名 | — |
 
@@ -73,13 +79,18 @@ version: "1.0.1"
 node -e "const i=JSON.parse(require('fs').readFileSync('skills-index.json','utf8')); Object.entries(i.bundleMeta).forEach(([k,v])=>console.log(k+': '+v))"
 ```
 
-**适用的最佳实践提示**（从 authoring guide 逐条检查，只列出适用的）：
+**2c. 适用哲学识别：** 对照标准的 16 条哲学，识别本 skill 涉及的（通常 3–10 条）。每条按"触发"条件判断是否成立。
+
+**2d. 标准检查：** 逐条核对相关哲学的"必做"和"检查"项，输出：
 
 ```
-[✓] <规范通过>  — <说明>
-[!] <需要注意>  — <具体建议>
+[✓] Φ1 可回退      — 破坏性 step 前有 y/n 确认
+[✓] Φ5 配置就地    — 路径 .hskill/<name>/ 正确
+[!] Φ12 输入清洁化 — URL 输入缺少控制字符剥离，建议加 re.sub(...)
 ```
 
+涉及多哲学冲突时查标准末尾"张力点"表消歧。
+
 **等用户明确确认后才进入 Step 3。**
 
 ### Step 3 — 生成 SKILL.md
@@ -111,7 +122,7 @@ version: "1.0.0"
 （2-4 条明确边界）
 ```
 
-若 skill 有参考材料（查找表、模板、禁忌清单）且超过 20 行，按 authoring guide 提示提取到 `references/` 子目录，而非全部内联在 SKILL.md 中。
+若 skill 有参考材料（查找表、模板、禁忌清单）且超过 20 行，按标准 Φ18 提取到 `references/` 子目录，而非全部内联在 SKILL.md 中。
 
 将生成内容展示给用户预览。**等用户明确确认后才进入 Step 4。**
 

package/skills/experiment/init-skill/references/skill-authoring-guide.md

@@ -0,0 +1,156 @@
+# Skill Authoring Guide
+
+init-skill 使用本文件作为生成新 skill 时的规范检查清单。内容分两类：**显性规范**（硬性要求，不符合则 publish-skill 报错）和**隐性模式**（从现有优质 skill 提炼的最佳实践）。
+
+---
+
+## 显性规范
+
+### 命名
+
+- 目录名格式：`<verb>-<noun>`（2 段，连字符分隔，全小写）
+- 动词必须在词表中：
+
+```
+extract  learn    forge    draw     manage   migrate  scout
+build    sync     publish  archive  contribute  analyze  clean
+release  validate init     dispatch close    setup    capture
+runby    dedup    survey
+```
+
+特殊：以 `runby-` 开头的目录直接视为合规。
+
+### Frontmatter 必填字段
+
+| 字段 | 要求 |
+|------|------|
+| `name` | 非空，值 == 目录名 |
+| `description` | 英文，≥ 10 字符，不含中文字符 |
+| `user_invocable` | 显式声明 `true` 或 `false` |
+| `version` | semver 格式 `X.Y.Z`，初始值 `"1.0.0"` |
+
+### description 格式
+
+```
+"<动词短语说明功能>. Triggers when <触发条件>. e.g. '<示例指令1>', '<示例指令2>'."
+```
+
+触发词宁宽勿窄，但要避免与现有 skill 触发场景重叠。举例比描述更精确。
+
+### 正文语言
+
+frontmatter 结束后的正文应为中文（含至少一个中文字符即合规）。
+
+---
+
+## 隐性模式
+
+### 正文结构
+
+推荐节顺序：**触发条件 → 执行步骤（Step N） → 边界说明（不在范围内）**
+
+- 每个 Step 对应一个可验证的原子操作，不要把两个动作塞进同一步
+- 边界说明必须有，明确列出 2-4 个常见误用场景，防止 skill 在对话中被过度扩展
+
+### 状态与配置
+
+**1. `.hskill/<skill-name>/` 配置缓存**（7 个 skill 使用此模式）
+
+有状态的 skill 将配置持久化到 `$HOME/.hskill/<skill-name>/`，每次运行 Step 1 先读此目录，未找到时落到默认值或询问用户。
+
+```
+clean-git → ~/.hskill/clean-git/branch-cleanup.md
+init-workflow → ~/.hskill/init-workflow/workflow-config.yml
+```
+
+**2. "读取配置"作为第一执行步骤**（6 个 skill 使用此模式）
+
+有状态 skill 的第一个实质步骤总是：检测配置文件存在性 → 不存在则用默认或询问 → 解析校验 → 才进入业务步骤。
+
+**3. Lock / snapshot 文件做变更检测**（3 个 skill 使用此模式）
+
+维护 `.lock` 或 manifest 快照，记录"上次运行状态"，实现 delta 操作（只处理变化部分）。
+
+```
+init-workflow → .githooks/.workflow-config.lock.yml
+sync-design → manifest.json 含 lastSyncCommit
+publish-skill → skills-index.json 中的 contentHash
+```
+
+**4. 多源配置覆盖链**（3 个 skill 使用此模式）
+
+多个配置源按固定顺序读取，后读优先级更高。明确注明"后读内容优先级更高"。
+
+### 错误处理与边界
+
+**5. "边界情况"表格放在步骤末尾**（5 个 skill 使用此模式）
+
+复杂多分支步骤末尾用表格列出所有边界条件和处理方式，便于一眼看全所有路径。
+
+```markdown
+| 情况 | 处理 |
+|------|------|
+| 目标路径已存在 | 停止报错，不覆盖 |
+| generate-npmignore.js 失败 | 报错，不执行 git 操作 |
+```
+
+**6. 冲突解决：批量收集，统一决策**（3 个 skill 使用此模式）
+
+出现冲突时，先收集所有冲突再分组展示，让用户一次性逐条决策。不要边发现边问。
+
+### 扩展与组合
+
+**7. references/ 承载平台/技术栈特定文档**（5 个 skill 使用此模式）
+
+Skill 顶层逻辑保持技术中立，平台/格式特定内容放进 `references/`，运行时按检测结果动态读取。扩展通过加文件而非改 SKILL.md。
+
+```
+setup-debug → references/tech-stacks/<stack>.md
+extract-url → platforms/SKILL.<platform>.md
+```
+
+阈值：references/ 内单文件 > 20 行时才提取；小内容直接内联。
+
+**8. Subagent 委派 + 变量注入**（2 个 skill 使用此模式）
+
+Skill 委派 subagent 时用环境变量注入运行时值（不是字符串拼接），并加载平台特定 patch 文件。
+
+### 输出格式
+
+**9. Emoji 与状态标记规范化**（5 个 skill 使用此模式）
+
+统一视觉符号：`✓` / `✅`（通过）、`⚠️`（注意）、`❌`（失败）、`━━━`（分组分隔）。状态标签：`UPDATED` / `UNCHANGED` / `NEW` / `OK` / `FAIL`。
+
+**10. 时间戳化 delta 报告**（3 个 skill 使用此模式）
+
+批量操作后每个条目标注状态（NEW / UPDATED / UNCHANGED），用户可跳过未变项。
+
+```markdown
+| 文件 | 状态 |
+|------|------|
+| .githooks/pre-commit | UPDATED |
+| .githooks/commit-msg | UNCHANGED |
+```
+
+**11. "下一步"交棒提示**（4 个 skill 使用此模式）
+
+Skill 完成后给出明确的下一步建议：调用下一个 skill，或询问用户是否深入某部分。
+
+```
+scout-brand: "确认后可运行 /build-style"
+init-skill:  "下一步：运行 /publish-skill 完成注册"
+```
+
+### 安全与规范
+
+**12. Bash 安全：禁止字符串拼接**（3 个 skill 使用此模式）
+
+Skill 中嵌入 bash/Python 时，禁止用 shell 字符串拼接传值。使用 `subprocess` 列表参数或环境变量；URL 净化用正则替换。
+
+**13. 版本字段在内容 hash 计算中视为占位**（2 个 skill 使用此模式）
+
+计算 SKILL.md 内容 hash 时，将 `version:` 行替换为固定占位符再计算，避免单纯改版本号触发"内容变更"误报。
+
+```bash
+sed 's/^version:.*$/version: __HASH_PLACEHOLDER__/' SKILL.md | sha256sum | cut -c1-16
+```

package/skills/experiment/init-skill/references/skill-standard.md

@@ -0,0 +1,219 @@
+# Skill 设计标准
+
+init-skill 生成 / 检查 SKILL.md 时遵循。每条哲学按"**触发 → 必做 → 检查 → 不适用**"组织。
+
+强度标注 `[强]` 表示反例不可接受（数据丢失 / 安全事故），`[中]` 表示有累积成本但不致命。
+
+---
+
+## 系统机制（必须满足，无例外）
+
+违反 = skill 加载失败 / 注册失败：
+
+- `name` 字段值与所在目录名完全一致
+- frontmatter 含 `name` / `description` / `user_invocable` / `version` 四字段
+- `description` 全英文 ≥ 10 字符（中文触发短语放正文"触发条件"节）
+- `version` 是 semver 三段 `X.Y.Z`，新 skill 从 `1.0.0`
+- `user_invocable` 显式 `true` 或 `false`
+- 注册到 `skills-index.json`，含 `path` / `bundle` / `installScope`
+- 正文至少含一个中文字符（团队约定）
+
+---
+
+## 命名与形式约定（Φ18 [中]）
+
+`name` 用 `<verb>-<noun>` 格式，2 词全小写连字符。动词必须在词表：
+
+```
+extract  learn   forge    draw     manage    migrate  scout
+build    sync    publish  archive  contribute  analyze  clean
+release  validate init    dispatch close    setup    capture
+dedup    runby
+```
+
+特殊：`runby-*` 后 noun 不受词表约束。
+
+`description` 格式：`"<动词短语>. Triggers: '<场景1>', '<场景2>'..."`，仅英文。
+
+节顺序：**触发条件 → 执行步骤 → 不在范围内**。Step 命名"动词 + 名词"（`Step 1 — 定位设计文档`）。
+
+参考材料 > 20 行时提取到 `references/` 子目录；平台 / 技术栈特定内容放 `references/<dim>/`。
+
+---
+
+## Φ1 可回退 [强]
+
+- **触发：** 破坏性操作（文件删除 / 移动 / 覆盖、git 写入）
+- **必做：** 操作前展示完整摘要 + 等待 y/n 确认；摘要列具体文件路径、分支名、外部脚本名
+- **必做：** 长流程（≥ 4 步）多 checkpoint，禁止"一次确认走到底"
+- **检查：** 破坏性 Step 前含 "(y/n)" 或"等用户确认"字样
+- **不适用：** read-only 操作（查询、列出、读文件）
+
+## Φ2 故障保留 [强]
+
+- **触发：** skill 含 ≥ 2 个步骤
+- **必做：** Step 1 先做前置检查（git 状态、文件存在、依赖工具、目标冲突），任一失败立即中止
+- **必做：** API / shell / subprocess 调用必须显式检查退出码或 HTTP 状态码
+- **必做：** 外部脚本失败后不进入 git commit / 文件删除；保留文件供调试
+- **必做：** 错误信息含三项：哪步失败 / 当前状态 / 用户下一步动作
+- **不适用：** 单一原子操作 skill
+
+## Φ3 边界显式 [中]
+
+- **触发（任一满足）：**
+  - skill 与其他 skill 功能可能混淆（触发词或职责可能重叠）
+  - skill 含多分支 / 多失败路径
+  - skill 易被对话扩展到设计意图外
+- **必做（与触发条件对应）：**
+  - 触发词与其他 skill 可能冲突 → "触发条件"节含"不触发：X 场景应使用 Y skill"
+  - 易被对话扩展 → "不在范围内"节列 2–4 个误用场景
+  - 多分支 → 步骤末尾用"边界情况汇总表"列处理方式
+- **检查：** 已识别的边界风险类型都有对应的显式声明
+- **不适用：** 功能单一、流程线性、无与其他 skill 重叠的工具型 skill
+
+## Φ4 信息按需收集 [中]
+
+- **触发：** skill 启动时需要参数
+- **必做：** 三级 fallback——上下文推断 → 显式指定 → 扫描列出
+- **必做：** 模糊意图澄清时一次只问一个，禁止堆叠问题列表
+- **必做：** 上下文已含模式信号时跳过询问（不忽略用户已提供的信息）
+- **不适用：** 完全自动化无参数的 skill
+
+## Φ5 配置就地 [强]
+
+- **触发：** skill 需要跨会话持久化配置 / 状态
+- **必做：** 存 `~/.hskill/<skill-name>/`（全局）或 `<project-root>/.hskill/<skill-name>/`（项目本地）
+- **判别：** 配置换个项目还有意义吗？有 → 全局；无 → 项目本地
+- **必做：** profile 一旦生成是后续运行的唯一依据，禁止"Execute 时还在改"
+- **检查：** SKILL.md 提到的所有持久化路径在 `.hskill/<skill-name>/` 下
+- **不适用：** 一次性 / 纯计算 skill
+
+## Φ6 单一真理源 [中]
+
+- **触发：** skill 引用会变化的列表 / 注册表（bundle 列表、版本、字段映射）
+- **必做：** 运行时用 Read / grep / jq / yaml 解析器读取，禁止在 SKILL.md 硬编码
+- **必做：** 报告数字必须来自实际计数，禁止 "约 N 个" 估算
+- **检查：** SKILL.md 不含可能过时的具体列表内容
+- **不适用：** 固定的步骤序列、字符串模板
+
+## Φ7 错误分级 [中]
+
+- **触发：** skill 输出问题报告
+- **必做：** 区分阻塞错误（必须修复才能通过）vs 建议警告（不影响通过）
+- **必做：** 退出码语义化（`0` 成功 / `1` 失败 / `2` 无内容触发降级）
+- **必做：** 多问题报告按类型分组（格式 / 注册 / 警告 / 通过），不按发现顺序混排
+- **检查：** 报告示例含 "错误 N 个 / 警告 M 个" 类分类
+
+## Φ8 可组合 [中]
+
+- **触发：** skill 完成后有自然下游
+- **必做：** 总结后输出独立"下一步"提示行（运行哪个 skill / 命令）
+- **必做：** 与外部生态对接时优先复用原生机制（如 `skills.paths`、`.stignore #include`）
+- **必做：** 与其他 skill 共享配置时在 SKILL.md 明确说明共享路径与读写约定
+- **不适用：** 独立工具型 skill 无明确下游
+
+## Φ9 保守不越权 [强]
+
+- **触发：** skill 涉及 git / 文件系统 / 远端 API
+- **必做：** 禁止自动 push、删除远端、发布到 npm；副作用最大的步骤交用户手动
+- **必做：** 禁止自动操作受保护分支（main / master / staging）；显式跳过或要求切换
+- **必做：** 目标路径已存在拒绝覆盖；停止报错或询问覆盖 / 重命名 / 中止
+- **必做：** 修改文件只动用户明确指定的字段，其他保持不变
+- **检查：** SKILL.md 不含自动执行的 `git push origin`、`npm publish` 等
+
+## Φ10 输出符号一致 [中]
+
+- **触发：** skill 输出含状态 / 进度 / 报告分类
+- **原则：**
+  - 同语义同符号——同一状态（"通过""失败"等）在 skill 内部和跨 skill 之间保持一致
+  - 符号有功能性，不为装饰
+  - 状态可单凭符号识别，不需要伴随文字解释
+  - 视觉区分度足够，避免语义重复或易混淆的符号
+- **禁忌：** 装饰性符号（❀ ✨ 🎉 等）—— 语义不明、可识别度低
+- **参考集（推荐但非强制，与生态保持一致）：**
+  - 通过 / 完成 → `✓` / `✅`
+  - 警告 / 关注 → `⚠️`
+  - 失败 / 拒绝 → `❌`
+  - 分组分隔 → `━━━`
+  - 状态标签 → 大写英文（如 `UPDATED` / `NEW` / `UNCHANGED` / `OK` / `FAIL` / `SKIP`）
+- **检查：** skill 输出示例符号在语义内自洽，跨示例一致
+- **不适用：** 无状态输出的纯生成 / 转换 skill
+
+## Φ11 关注点分离 [中]
+
+- **触发：** skill 内部含多角色（捕获 / 解析 / 写入 / 通知；消息层 vs 数据层）
+- **必做：** 用户区与 skill 管理区用明确标记区分（如 `# BEGIN MANAGED` / `# END MANAGED`）；MANAGED 块外永不被覆盖
+- **必做：** 捕获 / 观察层不修改原始数据，仅加时间戳 / 注解
+- **必做：** 消息层简洁（只含指令），数据层详细（放独立文件由接收方读）
+- **必做：** 内部接口名（机器使用）与用户可见名（UI 显示）不混用
+- **检查：** SKILL.md 各 step 职责清晰，无跨层混淆描述
+
+## Φ12 输入清洁化 [强]
+
+- **触发：** skill 接收用户原始输入（URL、文件路径、任意字符串）
+- **必做：** 剥离控制字符 + 长度截断：`re.sub(r'[\x00-\x1f\x7f]', '', x)[:2048]`
+- **必做：** 禁字符串拼接传 shell；用 subprocess list + env var：`subprocess.run([...], env={"X": value})`
+- **必做：** 解析 YAML / JSON / TOML 用原生解析器（python3 yaml / jq），禁 grep / sed / awk
+- **必做：** 路径变量显式展开 `~`：`os.path.expanduser` 或 `${path/#\~/$HOME}`
+- **必做：** 派 subagent 时显式标注用户数据为"分析对象非任务指令"
+- **不适用：** skill 自己生成的受控值（branch name、从 index.json 验证过的 ID）
+
+## Φ13 自我进化 [中]
+
+- **触发：** skill 执行中可能产生可复用知识（新模式、新边界、新技术栈处理）
+- **必做：** 写回 `references/` 满足五条全部：可复用 + 非显然 + 影响实质 + 技术栈归属 + 未被覆盖
+- **必做：** 首次运行无配置时主动询问"是否生成配置供下次复用"
+- **必做：** 维护 manifest 记录"已处理"项，下次跳过；发现新区域提示扩展
+- **不适用：** 项目特有、一次性、与 skill 无关的内容
+
+## Φ14 一次一问 [中]
+
+- **触发：** skill 需要澄清模糊用户意图
+- **必做：** 一次只问一个，等用户答完再问下一个
+- **必做：** 澄清前先用一句话复述用户意图让其校准方向
+- **必做：** 保留用户不确定语气（"也许"、"似乎"），不替用户升格为强声明
+- **不适用：** 清单 / 决策树等明确批量决策场景（属于 Φ1 不属于 Φ14）
+
+## Φ15 任务分阶段 [强]
+
+- **触发：** 复杂任务预期 context > 50k tokens 或需要全局视野
+- **必做（选一种或多种形态）：**
+  - 形态一 I/O vs LLM 拆分：抓取 + 理解拆为独立 subagent
+  - 形态二 广扫 vs 深读：仓库级 + 单元级拆为独立 skill 交棒
+  - 形态三 多遍读：定向 → 提取 → 批判
+  - 形态四 读完再写：跨文档先全部读完再做横向矩阵，禁止边读边写
+- **必做：** 多阶段任务支持单遍重跑 / 断点续传（如 `--pass N` 参数）
+- **不适用：** 简单任务（5 步以内、单文件操作）
+
+## Φ16 证据可溯源 [弱]
+
+- **触发：** skill 生成分析 / 解读 / 审计报告
+- **必做：** 每条结论标注来源（"来自 Step N" / "来自维度 X" / "原文 N 段"）
+- **必做：** 含推断的结论用显式标签 `[基于原文]` / `[Agent 推断]` / `[需核实]`
+- **必做：** 输出前完整性自查：找不到证据的结论删除或降级标注
+- **不适用：** 执行 / 工具型 skill，非分析类
+
+---
+
+## 哲学张力点（设计时常遇）
+
+| 张力对 | 区分 |
+|--------|------|
+| Φ1 vs Φ14 | Φ1 在输入已明 / 即将执行阶段一次确认；Φ14 在输入未明 / 澄清阶段一次一问 |
+| Φ2 vs Φ9 | Φ2 是"出错时"保留现场；Φ9 是"正常时"不越权 |
+| Φ9 vs Φ11 | Φ9 对外部不越权（远端 / 主干 / 用户已存在）；Φ11 对内部不越权（层间 / 块间） |
+| Φ8 vs Φ15 | Φ8 是 skill 间组合（交棒）；Φ15 是 skill 内阶段（拆分） |
+| Φ6 vs Φ13 | Φ6 是"读 SoT"（不硬编码）；Φ13 是"写回 SoT"（沉淀），方向相反但共生 |
+
+---
+
+## 应用流程
+
+1. **识别**：读 spec，判断涉及哪些哲学（一般 3–10 条）
+2. **触发检查**：对每条相关哲学，确认"触发"条件是否成立
+3. **抽取必做**：从命中的哲学"必做"中组装 SKILL.md 步骤
+4. **自验证**：用"检查"条目对照产物
+5. **消歧**：涉及多哲学冲突时查"张力点"表
+6. **核对系统机制**：确保 frontmatter / 命名 / 注册满足"系统机制"节
+
+写 skill 时反复问：**"违反这条会怎样？"** 能给出具体失败 → 必须遵守；不能 → 这条可能不适用当前 skill。

package/skills/meta/publish-skill/SKILL.md

@@ -2,7 +2,7 @@
 name: publish-skill
 description: "Validate and publish a skill to the harveyz-skill repository. Checks SKILL.md format compliance (frontmatter fields, semver version, name-directory match, verb-noun naming convention) and registration in skills-index.json. Rules defined in docs/reference/skill-spec.md. Triggers: publish skill, register skill, validate skill format, check skill, add skill to index, is skill ready to publish."
 user_invocable: true
-version: "1.2.1"
+version: "1.3.0"
 ---
 
 # skill-publish
@@ -123,6 +123,7 @@ _fm() {
 | R1 | `skills[]` 中有对应条目 | `path` 值 == `category/name` |
 | R2 | 对应条目有 `bundle` 字段且非空 | 必须指定归属 bundle |
 | R3 | `bundle` 值存在于 `bundleMeta` | bundle key 必须已声明 |
+| R4 | `installScope` 字段存在且值合法 | 值须为 `essential`/`global`/`project` 之一；缺失或值非法时报**警告**（不阻止通过） |
 
 ### Step 5 — 输出报告
 
@@ -146,6 +147,13 @@ skill-publish 检查结果
   skills/meta/my-skill
     R1  未在 skills-index.json 中注册
 
+注册警告（不阻止通过，建议修复）
+--------
+  skills/coding/setup-debug
+    R4  installScope 未设置（可选：essential / global / project）
+  skills/meta/my-other-skill
+    R4  installScope 值 'always' 非法（须为 essential / global / project）
+
 全部通过
 --------
   skills/meta/contribute-skill  ✓
@@ -153,15 +161,23 @@ skill-publish 检查结果
   ...
 
 ========================
-共发现 3 个问题（2 个格式，1 个注册）
+共发现 3 个问题（2 个格式，1 个注册），2 个警告
 ```
 
-若全部通过：
+若全部通过（含警告）：
 
 ```
 skill-publish 检查结果
 ========================
-所有 N 个 skill 格式与注册均符合规范。✓
+所有 N 个 skill 格式与注册均符合规范。✓（2 个 R4 警告，建议填写 installScope）
+```
+
+若完全无问题无警告：
+
+```
+skill-publish 检查结果
+========================
+所有 N 个 skill 格式、注册与推荐级别均符合规范。✓
 ```
 
 ### Step 6 — 修复引导（按需）
@@ -207,9 +223,18 @@ skill-publish 检查结果
 选择目标 bundle：
 ```
 
-选定后，在 `skills[]` 末尾追加：
+选定 bundle 后，继续询问推荐级别：
+```
+选择推荐级别（installScope）：
+  1. essential — 所有安装场景默认包含
+  2. global    — 推荐安装，跨项目通用
+  3. project   — 按项目需要安装
+  4. （不设置，跳过）
+```
+
+根据选择，在 `skills[]` 末尾追加（选 4 则省略 installScope 字段）：
 ```json
-{ "path": "meta/my-skill", "bundle": "meta" }
+{ "path": "meta/my-skill", "bundle": "meta", "installScope": "global" }
 ```
 
 若新建 bundle，在 `bundleMeta` 中同步添加。
@@ -219,6 +244,21 @@ skill-publish 检查结果
 cd "${REPO_ROOT}" && node scripts/generate-npmignore.js
 ```
 
+**注册警告（R4）** — 为已注册但缺少 installScope 的 skill 补充推荐级别：
+```
+修复 R4（installScope 未设置）— skills/coding/setup-debug：
+  选择推荐级别：
+    1. essential — 所有安装场景默认包含
+    2. global    — 推荐安装，跨项目通用
+    3. project   — 按项目需要安装
+    4. （跳过，保持不设置）
+```
+
+用户选择后，用 Edit 工具在 `skills-index.json` 对应条目中添加 `installScope` 字段，再暂存：
+```bash
+git add skills-index.json
+```
+
 ### Step 7 — 更新 contentHash
 
 在以下两种情况下执行，其余情况跳过：