@swifty.js/swifty 0.0.1 → 0.0.2

package/docs/ch11.md

@@ -1,163 +0,0 @@
-# Skill
-
-skill 是写给 AI 的 SOP (Standard Operation Procedure)
-
-背景: ch10 的 Slash Command 中, prompt 类型的命令可以将硬编码的代码审查 prompt 发送给 LLM, 不独立、不可更新、不可移植
-
-1. skill 是独立、可 (热) 更新、可移植
-2. 可以显式指定 skill, 提高 LLM 的准确率
-3. skill 可以携带资产:
-   - SKILL.md: SOP
-   - API reference、docs、example、scripts
-4. 执行模式: inline 或 fork
-5. 参数 $ARGUMENTS
-
-## Frontmatter
-
-```md
----
-name: skill-creator <!-- 不能和 Slash Comment 重名 -->
-description: Create new skills...
-allowed_tools: [] <!-- 可选的, 指定 skill 的工具白名单 -->
-mode: skill 执行模式, inline 或 fork
-model: 可选的, 指定 skill 使用的模型
-fork_context: 可选的, 仅在 mode: fork 时生效, 决定携带的上下文; 可以是 full 对话摘要、recent 最近的 5 条消息、none 不携带对话历史; inline 模式共享对话历史, fork_context 字段会被静默忽略 <!-- 源码: src/skills/catalog.ts -->
----
-```
-
-## skills 目录, 优先级从高到低
-
-1. 项目级: ${workDir}/.swifty/skills/
-2. 用户级: ~/.swifty/skills
-3. 内置级: Swifty 内置的 skills
-
-## skill 执行模式
-
-### inline 模式
-
-默认执行模式, 内联 skill 的 prompt 到用户消息, 参与 agent loop
-
-### fork 模式
-
-开启新对话, 调用 LLM API, 只将 LLM API 的响应返回给主对话, 不参与 agent loop
-
-fork 模式的实现:
-
-- 开启新对话
-- 根据 skill.fork_context
-  - full 压缩上下文, 生成对话摘要, 携带对话摘要
-  - recent 携带最近的 5 条消息
-  - none 不携带对话历史 (默认)
-- 如果用户传递参数, 则替换或追加 skill prompt 中的参数 $ARGUMENTS
-- 使用 skill.model 创建一个临时 Agent, 拿到 LLM API 的响应
-- 将 LLM API 的响应作为 assistant 消息返回给主对话
-
-## `$ARGUMENTS`
-
-```md
-请审查以下代码变更
-$ARGUMENTS
-如果没有指定代码审查范围, 请审查 `git diff` 的所有变更
-```
-
-用户输入 `/review 重点关注类型问题` (replaceAll 字符串替换)
-
-```md
-请审查以下代码变更
-重点关注类型问题
-如果没有指定代码审查范围, 请审查 `git diff` 的所有变更
-```
-
-fork 模式
-
-如果用户有输入, 则在 prompt 末尾追加 `\n\nARGUMENTS: ${args}`
-
-## 自动注册为 Slash Command (prompt 命令)
-
-skill 加载后自动注册为 Slash Command (prompt 命令)
-
-热加载: 每次使用 skill 时都重新读文件
-
-## 意图识别: 让 Agent 自己选择 skill
-
-### 两阶段加载
-
-第一阶段: 轻量启动
-
-Swifty 启动时, 扫描 skills 目录, 加载所有 skill 的 frontmatter 元信息 (name, description), 不加载完整 prompt 正文, 将 skill 元信息注入到 system prompt, 告诉 LLM 有哪些 skill
-
-第二阶段: 按需加载
-
-LLM 判断用户意图匹配某个 skill 时, 调用 LoadSkill 工具
-
-LoadSkill 工具根据该 skill 的 name, 读取 SKILL.md 的 SOP 作为工具调用结果返回, LLM 在下一轮 agent loop turn 中可以看到该 skill 的 SOP
-
-### LoadSkill
-
-- properties: name
-- metadata: 只读、非破坏性、分类 read
-
-```js
-function LoadSkill(name) {
-  const skill = this.catalog.get(name);
-  if (!skill) {
-    return {
-      output: `Skill '${name}' not found. Available skills: ${available}`,
-      isError: true,
-    };
-  }
-  const body = runInline(skill, "", this.host);
-  // 记录已激活
-  // 用于上下文压缩, CLI 侧压缩恢复, 恢复关键上下文 skills
-  return {
-    output: `Skill '${name}' activated.\n\n${body}`,
-    isError: false,
-  };
-}
-```
-
-## 渐进式披露
-
-渐进式披露: Agent 启动时, 扫描 skills 目录, 加载所有 skill 的 frontmatter 元信息 (name, description), 选择压力很低, LLM 判断用户意图匹配某个 skill 时, 才加载完整 SOP, 注意力集中在当前任务
-
-## 目录型 skill
-
-- 单文件 skill 只有 SOP
-- 目录型 skill 可以携带资产: SOP、API reference、docs、example、scripts, 整套技能方便打包、移植
-
-```txt
-$ tree ~/.claude/skills/skill-creator
-.claude/skills/skill-creator
-├── agents
-│   └── xxx.md
-├── assets
-│   └── xxx.html
-├── docs
-│   └── ...
-├── example
-│   └── xxx.md
-├── LICENSE.txt
-├── references
-│   └── xxx.md
-├── scripts
-│   ├── xxx.py
-│   └── yyy.py
-└── SKILL.md
-```
-
-## 完整流程
-
-```txt
-1. 启动时扫描 skills 目录, 加载所有 skill 的 frontmatter 元信息 (name, description), 轻量启动
-2. 将 skill 元信息注入到 system prompt, 告诉 LLM 有哪些 skill
-3. skill 加载后自动注册为 Slash Command (prompt 命令)
-4. 用户输入: 做一个 react 计数器 app
-5. 意图识别: LLM 判断匹配 react-best-practices skill
-6. Agent 请求调用工具 LoadSkill("react-best-practices")
-7. SOP 作为工具调用结果返回, 注入到 messages
-8. LLM 按 SKILL.md 的 critical/high/medium/low 规则、进行开发
-```
-
-- MCP 负责接入
-- 工具调用负责调用
-- skill 负责编排工作流

package/docs/ch12.md

@@ -1,289 +0,0 @@
-# Hook
-
-在 Agent 的生命周期事件上挂载自动化动作
-
-## Hook 的三要素
-
-- 事件
-- 条件, 可以省略, 如果省略则无条件触发
-- 动作
-
-配置:
-
-- ~/.swifty/config.yaml
-- ${projectRoot}/.swifty/config.yaml
-- ${projectRoot}/.swifty/config.local.yaml
-
-3 个配置文件按顺序加载, 后加载的 hook 配置不会覆盖先加载的 hook 配置, 多个 hook 配置会被拼接; 一个事件有多个 hook 时, 按 yaml 中的顺序逐个执行
-
-<!-- 源码: src/config/config.ts HookConfigSchema -->
-
-```yaml
-hooks:
-  - event: post_tool_use
-    condition: tool == "WriteFile"
-    action:
-      type: command
-      command: "prettier -w $SWIFTY_FILE_PATH"
-```
-
-<!-- 源码: src/hooks/hooks.ts 环境变量 SWIFTY_EVENT, SWIFTY_TOOL, SWIFTY_FILE_PATH -->
-
-每当 Agent 调用 WriteFile 工具写文件后, 自动 format 代码
-
-- 事件: post_tool_use
-- 条件: tool == "WriteFile"
-- 动作: format 代码
-
-## 事件
-
-<!-- 源码: src/hooks/hooks.ts EventName 类型定义 -->
-
-### 会话级
-
-- session_start 会话开始时触发
-- session_end 会话结束时触发
-
-### Agent Loop 轮次级
-
-- turn_start 用户发送新消息时触发, 一轮对话开始
-- turn_end LLM 退出 agent loop 时触发, 一轮对话结束
-  - LLM 决定退出循环
-  - 超过最大循环次数后强制退出循环
-  - 用户按 esc 退出循环
-
-### 工具级
-
-- pre_tool_use 工具调用前触发, 可以拦截工具调用
-- post_tool_use 工具调用后触发
-
-### 消息级
-
-- pre_send 用户消息发送给 LLM API 前触发
-- post_receive 收到 LLM API 响应后触发
-
-### 系统级
-
-- startup: Swifty 启动时触发
-- shutdown: Swifty 退出时触发
-- error: Swifty 发生错误时触发
-- compact: 上下文压缩时触发
-- permission_request: 权限请求时触发
-- file_change: 文件被修改时触发
-- command_execute: Slash Command 执行时触发
-
-## pre_tool_use
-
-```yaml
-hooks:
-  - event: pre_tool_use
-    condition: 'tool == "WriteFile" && path == "pnpm-lock.yaml"'
-    action:
-      type: command
-      command: "echo 'Never manually edit pnpm-lock.yaml'"
-    reject: true
-
-  - event: pre_tool_use
-    condition: 'tool == "Bash" && command =~ "rm\\s+-rf\\s+\\/"'
-    action:
-      type: command
-      command: "echo 'Dangerous rm command detected'"
-    reject: true
-```
-
-<!-- 源码: src/hooks/hooks.ts -->
-
-reject: true 是 pre_tool_use 事件的特殊字段, reject: true 时, 工具调用被拒绝, CLI 将 hook 抛出的错误 reason 作为工具调用结果 `{ content: reason, isError: true }` 返回给 LLM, LLM 调整策略
-
-pre_tool_use 事件的动作默认同步执行 (`async: false`)、阻塞等待返回值, 检查是否拒绝
-
-<!-- 源码: src/hooks/hooks.ts reject 仅在 pre_tool_use 事件中断循环 -->
-
-## 条件
-
-<!-- 源码: src/hooks/hooks.ts evaluateSingleCondition -->
-
-- == 等于, equal match
-- != 不等于, not equal match
-- =~ 正则匹配, regex match, 语法: `变量 =~ "正则表达式"`
-- =\* glob (filesystem 通配符语法) 匹配, glob match
-- 支持 && || 组合多个条件
-
-变量名:
-
-- tool: 匹配 ctx.toolName
-- event: 匹配 ctx.event
-- file_path 匹配 ctx.filePath
-- message 匹配 ctx.message
-- 其他变量名在工具参数字典 ctx.args 中按 key 查找, 例如 path 匹配 args.path, command 匹配 args.command
-
-<!-- 源码: src/hooks/hooks.ts getContextValue -->
-
-## 动作
-
-<!-- 源码: src/hooks/hooks.ts executeAction -->
-
-四种动作执行器
-
-- command: 执行 shell 命令
-- prompt: 注入 system prompt
-- http: 发送 http 请求
-- agent: 启动 subagent
-
-### command
-
-```yaml
-action:
-  type: command
-  command: "prettier -w $SWIFTY_FILE_PATH"
-```
-
-<!-- 源码: src/hooks/hooks.ts executeAction command 分支 -->
-
-- 执行 shell 命令, shell 命令执行前会设置环境变量 SWIFTY_EVENT, SWIFTY_TOOL, SWIFTY_FILE_PATH
-- 启动一个 shell 子进程执行命令, 拿到输出和退出码
-- timeout 字段指定命令超时时间
-
-<!-- 源码: src/hooks/hooks.ts timeout 硬编码 30000ms, HookConfigSchema 没有 timeout 字段 -->
-
-### prompt
-
-<!-- 源码: src/hooks/hooks.ts executeAction prompt 分支 -->
-
-```yaml
-action:
-  type: prompt
-  prompt: 先阅读 ARCHITECTURE.md 了解项目架构, 再开始工作
-```
-
-- 使用 `<system-reminder />` 标签包裹, 作为一条 user 消息追加到对话历史, LLM 在下一轮 agent loop turn 请求中可以读到
-- system prompt 不变、prompt cache 前缀不变
-- 可以只在指定项目中注入, 或者只在第一轮对话中注入 (使用执行控制 `once: true`)
-
-### http
-
-<!-- 源码: src/hooks/hooks.ts executeAction http 分支 -->
-
-```yaml
-action:
-  type: http
-  url: https://api.example.com
-  method: POST
-```
-
-<!-- 源码: src/hooks/hooks.ts http 请求体固定为 JSON.stringify(context), HookConfigSchema 没有 body 字段 -->
-
-发送 http 请求, 请求体是 HookContext 的 json 字符串 (包含 event, toolName, args, filePath, message 字段), 场景有: 发送 App 通知、日志收集、监控报警
-
-### agent
-
-```yaml
-action:
-  type: agent
-  prompt: "review 刚刚写入的 $SWIFTY_FILE_PATH 是否有安全漏洞"
-```
-
-<!-- 源码: src/hooks/hooks.ts executeAction agent 分支 -->
-
-启动 subagent, 见 ch13
-
-## hook 执行控制
-
-- once: 只执行一次
-- async: 异步执行, 注意: pre_tool_use 事件的动作默认同步执行 (`async: false`)、阻塞等待返回值, 检查是否拒绝
-- on_error: hook 执行错误时的行为, 枚举值:
-  - ignore: 默认, 忽略错误
-  - fail 标记 hook 执行错误
-  - reject 拒绝工具调用
-- 错误捕获: hook 执行错误不能中断 Agent
-
-<!-- 源码: src/hooks/hooks.ts on_error 处理逻辑 -->
-
-```yaml
-hooks:
-  - event: session_start
-    action:
-      type: prompt
-      prompt: "使用英文注释"
-    once: true
-
-  - event: post_tool_use
-    condition: tool == "WriteFile"
-    action:
-      type: http
-      url: https://api.example.com
-      method: POST
-    async: true
-```
-
-## 上下文变量
-
-事件触发时, 创建一个 HookContext 对象, 包含事件的上下文信息:
-
-<!-- 源码: src/hooks/hooks.ts HookContext 接口定义 -->
-
-HookContext 属性:
-
-- event 事件名 $SWIFTY_EVENT
-- toolName 工具名 $SWIFTY_TOOL
-- args 工具参数字典
-- filePath 文件路径 $SWIFTY_FILE_PATH
-- message 消息内容
-
-<!-- 源码: src/hooks/hooks.ts 暴露 SWIFTY_EVENT, SWIFTY_TOOL, SWIFTY_FILE_PATH 环境变量 -->
-
-## 示例配置
-
-```yaml
-hooks:
-  - id: auto-format
-    event: post_tool_use
-    condition: 'tool == "WriteFile" && path =* "*.ts"' # glob match
-    action:
-      type: command
-      command: "prettier -w $SWIFTY_FILE_PATH"
-
-  - id: readonly-vendor
-    event: pre_tool_use
-    condition: 'tool == "WriteFile" && path =* "node_modules/*"'
-    action:
-      type: command
-      command: "echo 'Never manually edit node_modules/*'"
-    reject: true
-
-  - id: project-context
-    event: session_start
-    action:
-      type: prompt
-      prompt: |
-        - Tech Stack: TypeScript, React, Ink, Zod, Vitest, ESLint, oxfmt, pnpm workspace deps: `@swifty.js/glob-addon`, `@swifty.js/glob-wasm`.
-        - Code Conventions: Enforced by `eslint.config.js`.
-        - Reference: Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
-    once: true
-
-  - id: block-dangerous-rm
-    event: pre_tool_use
-    condition: 'tool == "Bash" && command =~ "rm\\s+-rf\\s+\\/"'
-    action:
-      type: command
-      command: "echo 'Dangerous rm command detected'"
-    reject: true
-
-  - id: app-notify
-    event: post_tool_use
-    condition: 'tool == "WriteFile"'
-    action:
-      type: http
-      url: https://api.example.com
-      method: POST
-    async: true
-```
-
-## 配置校验
-
-- reject 字段只能用于 pre_tool_use 事件
-- async 字段不能用于 pre_tool_use 事件
-- command 动作必须有 command 字段
-- prompt 动作必须有 prompt 字段
-- http 动作必须有 url 字段
-- agent 动作必须有 prompt 字段或 command 字段