@swifty.js/swifty 0.0.1-canary → 0.0.1

package/dist/tool-filter-6ETY4ZEY.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { createRequire as __swiftyCreateRequire } from "node:module";
+const require = __swiftyCreateRequire(import.meta.url);
+import{b as a,c as b,d as c,e as d,f as e,g as f}from"./chunk-GW6RG76F.js";import"./chunk-X3UA5OZL.js";export{a as ALL_AGENT_DISALLOWED_TOOLS,c as ASYNC_AGENT_ALLOWED_TOOLS,b as CUSTOM_AGENT_DISALLOWED_TOOLS,e as FORK_QUERY_SOURCE,f as cloneRegistryForFork,d as filterToolsForAgent};

package/docs/ch1.md

@@ -1,14 +1,14 @@
 # 什么是 Agent
 
-Agent 是 LLM 在循环中根据环境反馈自主使用工具的系统
+agent 是 LLM 在循环中根据环境反馈自主使用工具的系统
 
 - LLM 是大脑，负责理解和思考
 - 循环: 意味着不是一次性问答就结束, 做一步操作, 拿到结果，再决定下一步
-- 反馈: Agent 每做一步操作, 都能拿到到结果, 这些反馈驱动下一步决策
+- 反馈: agent 每做一步操作, 都能拿到到结果, 这些反馈驱动下一步决策
   - 执行一条命令, 拿到输出
   - 读一个文件, 拿到内容
   - 跑一个测试, 拿到错误信息
-- 自主使用工具: Agent 自主判断使用什么工具, 是读文件还是写文件, 是 grep 搜索代码还是执行 shell 命令
+- 自主使用工具: agent 自主判断使用什么工具, 是读文件还是写文件, 是 grep 搜索代码还是执行 shell 命令
 
 ## Swifty 的 5 层架构
 

package/docs/ch10.md

@@ -6,14 +6,14 @@ Slash Command: 以 / 开头的输入会被命令解析器拦截
 
 <!-- 源码: src/commands/commands.ts -->
 
-- local: 不参与 Agent Loop
-- local_ui: 不参与 Agent Loop, 需要重新渲染 UI
-- prompt: 参与 Agent Loop, CLI 负责构造 prompt
+- local: 不参与 agent loop
+- local_ui: 不参与 agent loop, 需要重新渲染 UI
+- prompt: 参与 agent loop, CLI 负责构造 prompt
 - skill_fork: skill 加载后自动注册为 Slash Command (prompt 命令)
 
-> 不参与 Agent Loop != 不调用 LLM API
+> 不参与 agent loop != 不调用 LLM API
 >
-> 例如 /compact 命令调用 LLM API 生成摘要, 但是不参与 Agent Loop
+> 例如 /compact 命令调用 LLM API 生成摘要, 但是不参与 agent loop
 
 命令拦截时机: 消息发送给 LLM API 前, 用户按下回车, 先判断输入是不是命令, 如果是命令则走命令处理逻辑, 不是命令才发送给 LLM API
 

package/docs/ch11.md

@@ -35,11 +35,11 @@ fork_context: 可选的, 仅在 mode: fork 时生效, 决定携带的上下文;
 
 ### inline 模式
 
-默认执行模式, 内联 skill 的 prompt 到用户消息, 参与 Agent Loop
+默认执行模式, 内联 skill 的 prompt 到用户消息, 参与 agent loop
 
 ### fork 模式
 
-开启新对话, 调用 LLM API, 只将 LLM API 的响应返回给主对话, 不参与 Agent Loop
+开启新对话, 调用 LLM API, 只将 LLM API 的响应返回给主对话, 不参与 agent loop
 
 fork 模式的实现:
 
@@ -90,7 +90,7 @@ Swifty 启动时, 扫描 skills 目录, 加载所有 skill 的 frontmatter 元
 
 LLM 判断用户意图匹配某个 skill 时, 调用 LoadSkill 工具
 
-LoadSkill 工具根据该 skill 的 name, 读取 SKILL.md 的 SOP 作为工具调用结果返回, LLM 在下一轮 Agent Loop turn 中可以看到该 skill 的 SOP
+LoadSkill 工具根据该 skill 的 name, 读取 SKILL.md 的 SOP 作为工具调用结果返回, LLM 在下一轮 agent loop turn 中可以看到该 skill 的 SOP
 
 ### LoadSkill
 

package/docs/ch12.md

@@ -47,7 +47,7 @@ hooks:
 ### Agent Loop 轮次级
 
 - turn_start 用户发送新消息时触发, 一轮对话开始
-- turn_end LLM 退出 Agent Loop 时触发, 一轮对话结束
+- turn_end LLM 退出 agent loop 时触发, 一轮对话结束
   - LLM 决定退出循环
   - 超过最大循环次数后强制退出循环
   - 用户按 esc 退出循环
@@ -156,7 +156,8 @@ action:
   prompt: 先阅读 ARCHITECTURE.md 了解项目架构, 再开始工作
 ```
 
-- 使用 `<hook-notification />` 标签包裹, 注入到 system prompt, LLM 在下一轮 Agent Loop turn 请求中可以读到
+- 使用 `<system-reminder />` 标签包裹, 作为一条 user 消息追加到对话历史, LLM 在下一轮 agent loop turn 请求中可以读到
+- system prompt 不变、prompt cache 前缀不变
 - 可以只在指定项目中注入, 或者只在第一轮对话中注入 (使用执行控制 `once: true`)
 
 ### http

package/docs/ch13.md

@@ -47,7 +47,7 @@ interface Tool {
 
 ## 两种创建模式
 
-- 预定义的 subagent (Definition-based): 预定义的专家, 无对话历史
+- 预定义的 subagent (Definition-based): 预定义的 subagent 角色, 无对话历史
 - fork 的 subagent (Fork-based): spawn (fork) 一个 subagent, 继承父 Agent 的完整对话历史
 
 ### 预定义的 subagent (Definition-based)
@@ -121,11 +121,11 @@ Rules (non-negotiable):
 Your task: ${prompt}
 ```
 
-fork 的 subagent 必须后台异步运行, 执行结束后使用 `<task-notification />` 标签包裹执行结果, 作为一条 user message 注入到主 Agent 的对话历史 (TODO)
+fork 的 subagent 必须后台异步运行, 执行结束后使用 `<task-notification />` 标签包裹执行结果, 作为一条 user 消息注入到主 agent 的上下文 (TODO)
 
 > 为什么 fork 的 subagent 必须后台异步运行?
 
-1. fork 的场景是主 Agent 分发多个子任务, 并行执行
+1. fork 的场景是主 agent 分发多个子任务, 并发执行
 2. fork 的 subagent 继承父 Agent 的完整对话历史, 首次 API 请求耗时长; 前台同步等待, 父 Agent 阻塞, 用户体验很差
 
 > 定义式 subagent 默认前台同步运行
@@ -152,11 +152,11 @@ background: true
   - 可以精确控制 subagent 的能力边界
   - 可以限制 subagent 调用的工具
   - 可以指定一个更小更快的模型: haiku, sonnet, deepseek...
-- 如果任务不通用、与主 Agent 的当前工作高度相关, 例如: 迁移一个组件的 useImperativeHandle 从 react18 到 react19, fork 3 个 subagent 迁移剩余的类组件, 使用 fork 的 subagent, subagent_type 为空
+- 如果任务不通用、与主 agent 的当前工作高度相关, 例如: 迁移一个组件的 useImperativeHandle 从 react18 到 react19, fork 3 个 subagent 迁移剩余的类组件, 使用 fork 的 subagent, subagent_type 为空
 
 ## 上下文隔离
 
-- 基础设施共享: API Key、LLM API 连接池、工具列表、MCP、Skill、Hook
+- 基础设施共享: API Key、LLM API 连接池、工具集、MCP、Skill、Hook
 - 权限 (permissionMode) 隔离
 - 文件系统: 默认共享, 使用 `isolation: "worktree"` 时隔离
 
@@ -164,26 +164,26 @@ background: true
 
 <!-- 源码: src/subagent/loader.ts -->
 
-|                              | Skill                     | Subagent                                                                                                                     |
-| ---------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| body                         | 注入 messages 的 SOP 指令 | 对于定义式 subagent, 作为 system prompt; 对于 fork 的 subagent, body 使用 `<fork_boilerplate />` 标签包裹注入到 user message |
-| frontmatter.name             | name                      | name, 映射到 AgentDefinition 的 agentType                                                                                    |
-| frontmatter.description      | description               | description, 映射到 AgentDefinition 的 whenToUse                                                                             |
-| frontmatter.model            | model                     | model                                                                                                                        |
-| frontmatter.system_prompt    | X                         | 覆盖默认 system prompt                                                                                                       |
-| frontmatter.subagent_type    | X                         | 预定义的 agent 角色, 例如 explore, plan, code-review                                                                         |
-| frontmatter.background       | X                         | 是否后台异步运行, fork 的 subagent 必须后台异步运行, 为了对齐 Claude, properties (parameters) 中是 run_in_background         |
-| frontmatter.isolation        | X                         | `isolation: undefined \| 'worktree'`, 是否使用 git worktree 文件系统隔离                                                     |
-| frontmatter.memory           | X                         | 记忆范围: `"user" \| "project" \| "local"`                                                                                   |
-| frontmatter.tools            | X                         | 工具白名单                                                                                                                   |
-| frontmatter.disallowed_tools | X                         | 工具黑名单                                                                                                                   |
-| frontmatter.permission_mode  | X                         | 例如 `permissionMode: "acceptEdits"` 调用工具, 不弹出对话框                                                                  |
-| frontmatter.max_turns        | X                         | 最大 Agent Loop 次数数                                                                                                       |
+|                              | Skill                     | Subagent                                                                                                                  |
+| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| body                         | 注入 messages 的 SOP 指令 | 对于定义式 subagent, 作为 system prompt; 对于 fork 的 subagent, body 使用 `<fork_boilerplate />` 标签包裹注入到 user 消息 |
+| frontmatter.name             | name                      | name, 映射到 AgentDefinition 的 agentType                                                                                 |
+| frontmatter.description      | description               | description, 映射到 AgentDefinition 的 whenToUse                                                                          |
+| frontmatter.model            | model                     | model                                                                                                                     |
+| frontmatter.system_prompt    | X                         | 覆盖默认 system prompt                                                                                                    |
+| frontmatter.subagent_type    | X                         | 预定义的 agent 角色, 例如 explore, plan, code-review                                                                      |
+| frontmatter.background       | X                         | 是否后台异步运行, fork 的 subagent 必须后台异步运行, 为了对齐 Claude, properties (parameters) 中是 run_in_background      |
+| frontmatter.isolation        | X                         | `isolation: undefined \| 'worktree'`, 是否使用 git worktree 文件系统隔离                                                  |
+| frontmatter.memory           | X                         | 记忆范围: `"user" \| "project" \| "local"`                                                                                |
+| frontmatter.tools            | X                         | 工具白名单                                                                                                                |
+| frontmatter.disallowed_tools | X                         | 工具黑名单                                                                                                                |
+| frontmatter.permission_mode  | X                         | 例如 `permissionMode: "acceptEdits"` 调用工具, 不弹出对话框                                                               |
+| frontmatter.max_turns        | X                         | 最大 agent loop 次数数                                                                                                    |
 
 <!-- 源码: src/subagent/definition.ts -->
 
 ```ts
-/** Memory scope for a sub-agent. Mirrors Go's AgentMemoryScope. */
+/** Memory scope for a subagent. Mirrors Go's AgentMemoryScope. */
 export type AgentMemoryScope = "user" | "project" | "local";
 
 export interface AgentDefinition {
@@ -217,11 +217,11 @@ Agent 定义文件, 优先级从低到高
 
 ## Subagent Loop
 
-Subagent Loop 和主 Agent Loop 的区别
+subagent loop 和主 agent loop 的区别
 
-1. Subagent Loop turn 不等待用户输入
-2. LLM 不再调用工具, Subagent Loop 结束, 返回执行结果
-3. pre_tool_use hook -> 调用 AgentTool -> Subagent Loop -> post_tool_use hook
+1. subagent loop turn 不等待用户输入
+2. LLM 不再调用工具, subagent loop 结束, 返回执行结果
+3. pre_tool_use hook -> 调用 AgentTool -> subagent loop -> post_tool_use hook
 
 ## Subagent 不能继续 spawn
 
@@ -249,7 +249,7 @@ Subagent Loop 和主 Agent Loop 的区别
 3. 按 esc 键将前台同步运行的 subagent 手动切换到后台异步运行
 4. fork 的 subagent 无条件后台异步运行
 
-Swifty 没有管理后台异步任务的 Slash Command, 后台异步任务通过 4 个内置工具暴露给 Agent:
+swifty 没有管理后台异步任务的 Slash Command, 后台异步任务通过 4 个内置工具暴露给 agent:
 
 - TaskList 任务列表
 - TaskGet 获取某个任务的状态或结果
@@ -281,7 +281,7 @@ permission_mode: plan
 - 使用 Grep 搜索内容
 - 使用 ReadFile 读取指定路径的文件
 - 只允许执行只读的 Bash 命令
-- 尽可能并行调用多个工具以提高效率
+- 尽可能并发调用多个工具以提高效率
 ```
 
 ### Plan
@@ -315,6 +315,6 @@ permission_mode: plan
 ```md
 ---
 name: general-purpose
-description: 你是 Swifty 的 Subagent, 不是主 Agent
+description: 你是 Swifty 的 Subagent, 不是主 agent
 ---
 ```

package/docs/ch14.md

@@ -108,6 +108,7 @@ git rev-list --count ${headCommit}..HEAD
 - 进程崩溃、用户强制退出, 会导致 .swifty/worktree 堆积大量的 worktree 目录
   - workflow 创建的 worktree: `wf-[hash]`, 会被自动清理
   - subagent 创建的 worktree: `agent-[hash]`, 会被自动清理
+  - agent team leader 指定 teammate `isolation: "worktree"`, leader 创建的 worktree: `team-${teamNae}/${teammateName}`, 见 ch15
   - 用户手动创建的 worktree, 不会被自动清理
 - 如果 worktree 没有未 commit 的修改, 也没有新增的 commit, 则可以自动清理
 - 如果 worktree 已过期、有新增的 commit 并且推送到远端, 则可以自动清理
@@ -141,6 +142,11 @@ export function buildWorktreeNotice(parentCwd: string, wtPath: string): string {
 
 > 考虑以下场景
 
-subagent 在 worktree 中修改并提交了 server.ts, 主 Agent 期望将该 subagent 的变更合并到主分支, Swifty 没有内置的 merge 工具, 主 Agent 只能调用 Bash 工具, 执行 `git merge` 或者 `git cherry-pick`
+subagent 在 worktree 中修改并提交了 server.ts, 主 agent 期望将该 subagent 的变更merge/rebase/cherry-pick 到主分支; Swifty 没有内置的 merge/rebase/cherry-pick 工具, 主 agent 调用 Bash 工具, 执行 `git merge/rebase/cherry-pick`
 
-为什么 Swifty 没有将 merge 作为内置工具? (参考 Claude 的设计), 可以从「主 Agent 应该看到合并冲突」、「不同的项目合并策略不同」、「合并失败时如何 abort」等角度思考
+为什么 Swifty 没有将 merge/rebase/cherry-pick 作为内置工具?
+
+- merge/rebase/cherry-pick 不是 Agent 的原子操作
+- 主 agent 可以调用 Bash 工具执行 git 命令
+- 主 agent 需要调用 ReadFile 工具查看冲突文件, 以确定 merge/rebase/cherry-pick 顺序和冲突解决策略
+- merge/rebase/cherry-pick 失败时, 主 agent 需要调用 Bash 工具 abort