@swifty.js/swifty 0.0.1-canary

package/docs/ch10.md

@@ -0,0 +1,122 @@
+# Slash Command
+
+Slash Command: 以 / 开头的输入会被命令解析器拦截
+
+## 命令的分类
+
+<!-- 源码: src/commands/commands.ts -->
+
+- local: 不参与 Agent Loop
+- local_ui: 不参与 Agent Loop, 需要重新渲染 UI
+- prompt: 参与 Agent Loop, CLI 负责构造 prompt
+- skill_fork: skill 加载后自动注册为 Slash Command (prompt 命令)
+
+> 不参与 Agent Loop != 不调用 LLM API
+>
+> 例如 /compact 命令调用 LLM API 生成摘要, 但是不参与 Agent Loop
+
+命令拦截时机: 消息发送给 LLM API 前, 用户按下回车, 先判断输入是不是命令, 如果是命令则走命令处理逻辑, 不是命令才发送给 LLM API
+
+## local 命令
+
+`/help` 打印帮助信息
+
+<!-- 源码: src/commands/commands.ts -->
+
+```txt
+- /help, /h, /?   打印帮助信息
+- /compact, /c    压缩上下文
+- /clear          清除对话历史
+- /plan, /p       切换到 plan 模式
+- /session        会话管理
+- /memory         记忆管理
+- /permission     权限管理
+- /status, /s     打印状态信息
+- /review         代码审查
+
+输入 /help <命令名> 查看详细用法
+```
+
+`/compact` 手动触发上下文压缩, `/compact [description]` 指定上下文保留重点; 如果当前上下文窗口 <= 5k token, 直接提示无需压缩
+
+<!-- 源码: src/commands/commands.ts, 部分子命令未实现, TODO -->
+
+`/session` 会话信息
+
+- `/session` 打印当前会话信息
+- `/session list` 打印历史会话列表
+- `/session resume <id>` 切换到指定 ID 的会话
+- `/session new` 开启新会话
+- `/session delete <id>` 删除指定 ID 的会话
+
+`/memory` 记忆管理
+
+- `/memory list` 打印记忆列表
+- `/memory add <content>` 添加一条记忆
+- `/memory clear` 清空记忆, 需要用户确认
+
+`/permission` 权限管理
+
+- `/permission` 打印权限模式和生效的权限规则数量
+- `/permission mode <plan | default | acceptEdits | bypassPermissions>` 切换权限模式
+- `/permission rules` 打印生效的权限规则列表
+- `/permission add <rule> <effect>` 添加一条本地权限规则
+- `/permission reset` 重置本地权限规则
+
+`/status` 打印当前状态
+
+<!-- 源码: src/commands/commands.ts -->
+
+```txt
+Swifty Status
+──────────────
+  Mode:      default
+  Tokens:    45230 in / 1200 out
+  Tools:     6 enabled
+  Memories:  8 entries
+  Model:     claude-sonnet-4-20250514
+  Directory: /path/to/project
+```
+
+`/skills` skill 管理
+
+<!-- 源码: src/commands/commands.ts -->
+
+- `/skills list` 打印 skill 列表
+- `/skills info <name>` 打印指定 skill 的 frontmatter 和路径
+- `/skills reload` 重新扫描并加载所有 skill
+
+`/mcp` MCP 服务器连接状态
+
+<!-- 源码: src/commands/commands.ts -->
+
+- `/mcp` 打印 MCP 服务器连接状态
+
+`/code-review` 代码审查 agent team 管理
+
+<!-- 源码: src/commands/commands.ts -->
+
+- `/code-review`, `/cr` 管理代码审查 agent team
+- `/cr create` TODO
+- `/cr add <name>` TODO
+- `/cr remove <name>` TODO
+- `/cr list` TODO
+- `/cr status` TODO
+
+## local_ui 命令
+
+<!-- 源码: src/commands/commands.ts -->
+
+- `/clear` 开启新对话, 关闭当前会话, 持久化到磁盘的 jsonl 会话日志
+- `/compact, /c` 强制上下文压缩
+- `/plan, /p` 切换 plan 模式 (toggle), `/plan [description]` 指定任务描述
+- `/quit, /exit, /q` 退出 Swifty
+- `/resume, /r` 恢复以前的会话
+- `/rewind` 回退对话到以前的检查点
+- `/worktree, /wt` 管理 git worktree
+
+## prompt 命令
+
+<!-- 源码: src/commands/commands.ts -->
+
+`/review` CLI 将预设的代码审查 prompt 发送给 LLM API, 分析未提交的代码变更, `/review [description]` 指定代码审查重点; prompt 命令消耗 token

package/docs/ch11.md

@@ -0,0 +1,163 @@
+# 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

@@ -0,0 +1,288 @@
+# 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 了解项目架构, 再开始工作
+```
+
+- 使用 `<hook-notification />` 标签包裹, 注入到 system prompt, LLM 在下一轮 Agent Loop turn 请求中可以读到
+- 可以只在指定项目中注入, 或者只在第一轮对话中注入 (使用执行控制 `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 字段